\# SPDX-FileCopyrightText: 2025 Dennis Fink <me+coding@dennisfink.me>
\# SPDX-License-Identifier: BSD-3-Clause
.TH TRANSCODE.SH 1 "2026-05-23" "2.1.0" "User Commands"
.SH NAME
transcode.sh \- batch transcode helper for media files using ffmpeg
.SH SYNOPSIS
.B transcode.sh
[\fIOPTION\fR]... [\fB\-\-\fR] \fIFILE\fR...
.SH DESCRIPTION
.B transcode.sh
is a batch transcoding wrapper around
.BR ffmpeg (1)
that processes one or more media files in place, replacing each with a
re-encoded version unless no-replacement output mode is enabled with
.BR \-\-output\-dir .
.PP
Encoding parameters are not hard-coded; instead they are supplied by
.IR presets ,
which are small shell snippets stored under the preset directory (see
.B FILES
below). Each preset must define a Bash array named
.B ffargs
containing the extra arguments passed to
.BR ffmpeg (1).
.PP
The script probes every input file with
.BR ffprobe (1)
to detect the input video codec, pixel format and frame rate of the selected
video probe stream. The selected stream defaults to
.B v:0
and can be changed with
.BR \-\-video\-stream .
Files whose codec appears in the skip list are silently skipped. The output
pixel format is derived automatically so that chroma subsampling (4:2:0, 4:2:2,
4:4:4) and bit depth (8, 10, 12, 16\-bit) are preserved.
.PP
All streams, metadata and chapter markers from the input are retained by
default (\fB\-map 0 \-map_metadata 0 \-map_chapters 0 \-c copy\fR); the
preset only needs to override the streams it cares about (typically
video).
.PP
After encoding completes,
.BR ffprobe (1)
is run against the temporary output file to verify it is a valid,
playable media file before the original is replaced. If the integrity
check fails the temporary file is removed and the encode is treated as a
runtime failure, leaving the original untouched.
.SH OPTIONS
.SS "Input options"
.TP
.BR \-\-config\-file " \fIPATH\fR, " \-\-config\-file= \fIPATH\fR
Load configuration from \fIPATH\fR instead of the default location
.RI ( ${XDG_CONFIG_HOME:-$HOME/.config}/transcode.sh/config.toml ).
If the specified file does not exist the script exits with a configuration
error. CLI flags always take precedence over values in the config file.
Requires
.BR tomlq (1)
when the file is present.
.TP
.BR \-\-no\-config
Do not load any configuration file.
.TP
.BR \-f " \fIPATH\fR, " \-\-encode-file " \fIPATH\fR, " \-\-encode-file= \fIPATH\fR
Read the list of files to encode from \fIPATH\fR (one file per line)
instead of taking files from the command line.
.SS "Encoding options"
.TP
.BR \-p " \fINAME\fR, " \-\-preset " \fINAME\fR, " \-\-preset= \fINAME\fR
Load the preset named \fINAME\fR from the preset directory. Defaults to
.BR default .
.TP
.BR \-N " \fIVALUE\fR, " \-\-nice " \fIVALUE\fR, " \-\-nice= \fIVALUE\fR
Run
.BR ffmpeg (1)
under
.BR nice (1)
with the given niceness value. Defaults to
.BR 19
(lowest priority).
.TP
.BR \-\-hwaccel " [\fIMETHOD\fR], " \-\-hwaccel= \fIMETHOD\fR
Pass
.BI \-hwaccel " METHOD"
to
.BR ffmpeg (1)
before the input file, enabling hardware-accelerated decoding.
\fIMETHOD\fR is optional; when omitted it defaults to
.BR auto ,
which lets
.BR ffmpeg (1)
select the best available hardware decoder and fall back to software
automatically.
Common values include
.BR cuda ,
.BR vaapi ,
.BR dxva2 ,
and
.BR videotoolbox .
Hardware acceleration is
.B enabled by default
(method
.BR auto ).
.TP
.B \-\-no\-hwaccel
Do not pass
.B \-hwaccel
to
.BR ffmpeg (1).
Use this on hosts where hardware acceleration causes compatibility or
stability issues.
.TP
.BR \-\-video\-stream " \fISTREAM_SELECTOR\fR, " \-\-video\-stream= \fISTREAM_SELECTOR\fR
Select the input video stream that is probed for preset helper variables.
Defaults to
.BR v:0 .
The selector must be a conservative video stream selector such as
.B v:0
or
.BR v:1 .
This option does not change ffmpeg stream mapping; presets remain responsible
for selecting which stream to encode.
.SS "Processing options"
.TP
.BR \-S " \fILIST\fR, " \-\-skip\-codec " \fILIST\fR, " \-\-skip\-codec= \fILIST\fR
Comma-, space- or colon-separated list of video codec names to skip.
Files whose detected input codec appears in this list are left untouched.
By default, codecs specified here are merged with any codecs listed under
.B [processing] skip_codecs
in
.B config.toml
\(em both sources contribute to the skip list.
.TP
.BR \-\-skip\-codec\-override
Ignore codecs listed under
.B [processing] skip_codecs
in
.B config.toml
and use only codecs provided through
.BR \-S / \-\-skip\-codec
for this run. The position of this flag on the command line does not matter;
it changes how the final skip list is resolved after all options are parsed.
.TP
.BR \-n ", " \-\-dry\-run
Print what would be done without actually invoking
.BR ffmpeg (1).
Combine with
.B \-v
to see the selected video stream and detected codec, pixel format and frame
rate information.
.TP
.BR \-\-backup\-dir " \fIDIR\fR, " \-\-backup\-dir= \fIDIR\fR
Copy originals to \fIDIR\fR before replacing them after successful encoding.
\fIDIR\fR must already exist; the script exits with a usage error if it does
not. Backups preserve the source file's absolute path below \fIDIR\fR, and
existing backup files are not overwritten.
.TP
.BR \-\-output\-dir " \fIDIR\fR, " \-\-output\-dir= \fIDIR\fR
Write encoded files below \fIDIR\fR instead of replacing originals.
\fIDIR\fR must already exist; the script exits with a usage error if it does
not. Relative input paths are preserved below \fIDIR\fR, while absolute input
paths are stored without their leading slash. Existing output files are not
overwritten; numeric suffixes such as
.B .1
or
.B .2
are appended when needed.
.TP
.BR \-l ", " \-\-only\-if\-smaller
After encoding, keep the new output only when it is strictly smaller than the
original. In replacement mode, a larger output is removed and the original is
kept unchanged. In
.BR \-\-output\-dir
mode, a larger output is removed and no encoded copy is kept.
.TP
.BR \-\-no\-only\-if\-smaller
After encoding, replace the original also if the new file is bigger.
.TP
.BR \-\-verify\-output
After encoding, probe the temporary output file with
.BR ffprobe (1)
to confirm it is a valid, playable media file before replacing the
original. Enabled by default.
.TP
.BR \-\-no\-verify\-output
Skip the post-encode integrity check. The original is replaced as long
as
.BR ffmpeg (1)
exits successfully. Useful for large batch jobs on trusted encoders
where the additional probe round-trip is undesirable.
.TP
.BR \-c ", " \-\-continue
Continue processing the next file even if
.BR ffmpeg (1)
fails on the current one. Without this flag the script exits immediately
on the first failure.
.TP
.BR \-\-no\-continue
Do not continue processing next file even if
.BR ffmpeg (1)
fails on the current one.
.SS "Size report options"
.TP
.BR \-s ", " \-\-size\-report
Print per-file size feedback after successful encodes and size-based skips,
then write a TSV status log for encoded, skipped and failed files. For runs
with more than one input file, print a final summary with encoded, skipped
and failed counts, total bytes saved and the overall saved percentage.
.TP
.BR \-\-no\-size\-report
Disable size reporting from the configuration file.
.TP
.BR \-\-size\-report\-file " \fIPATH\fR, " \-\-size\-report\-file= \fIPATH\fR
Path to the TSV status log written by
.BR \-\-size\-report .
Defaults to
.B transcode_size_report
in the current working directory.
.SS "Display options"
.TP
.BR \-\-ffmpeg\-loglevel " \fILEVEL\fR, " \-\-ffmpeg\-loglevel= \fILEVEL\fR
Pass
\.BI \-v " LEVEL"
to
.BR ffmpeg(1).
Defaults to
.BR fatal .
.TP
.BR \-q ", " \-\-quiet
Suppress all normal output. Takes precedence over
.BR \-v / \-\-verbose .
.TP
.BR \-v ", " \-\-verbose
Emit additional informational messages, including the selected video stream and
detected codec, pixel format and frame rate.
.TP
.B \-\-color
Force colored output even when stdout is not a terminal or
.B NO_COLOR
is set.
.TP
.B \-\-no\-color
Disable colored output unconditionally.
.SS "General options"
.TP
.BR \-h ", " \-\-help ", " \-?
Print a short help message and exit.
.TP
.B \-\-version
Print version, author and license information and exit.
.TP
.B \-\-list\-presets
Print all preset names found in the preset directory, along with their
one-line description (read from a
.B # description:
comment on the first line of the preset file), then exit.
If the preset directory does not exist or contains no
.B .sh
files, a notice is printed instead.
.TP
.B \-\-
End of options. All subsequent arguments are treated as file names even
if they begin with
.BR \- .
.SH ENVIRONMENT
.TP
.B NO_COLOR
When set (to any value), colored output is disabled. See
.IR https://no-color.org/ .
.TP
.B FORCE_COLOR
When set, colored output is enabled regardless of
.B NO_COLOR
or terminal detection.
.TP
.B DEBUG
Set to
.B 1
to enable structured debug messages (high-level state reporting).
After configuration loading, a summary of all effective option values
is printed.
.TP
.B TRACE
Set to
.B 1
to enable Bash execution tracing
.RB ( set\ \-x ),
which prints every command as it is executed.
.TP
.B XDG_CONFIG_HOME
Base directory for user configuration. Defaults to
.BR $HOME/.config .
.SH BACKUPS AND OUTPUT DIRECTORIES
When
.BR \-\-backup\-dir
is used, backups are only created after
.BR ffmpeg (1)
completed successfully and, when enabled, the integrity check passed. Codec
skips, failed encodes, failed integrity checks, dry runs, and
.BR \-\-only\-if\-smaller
size skips leave the original file in place and create no backup.
.PP
The backup directory itself must already exist. Parent directories below it are
created as needed to preserve the input file path. If the intended backup file
already exists, a numeric suffix such as
.B .1
or
.B .2
is appended.
.PP
When
.BR \-\-output\-dir
is used, originals are never replaced, moved, or deleted. Encoded files are
written below the existing output directory. Relative input paths are preserved
(for example,
.I movies/a.mp4
becomes
.I encoded/movies/a.mp4
when the output directory is
.IR encoded ),
and absolute input paths are stored without their leading slash. Existing output
files are not overwritten; numeric suffixes are appended as needed.
.PP
.BR \-\-backup\-dir
and
.BR \-\-output\-dir
are compatible. When both are set, the original is copied to the backup
directory and the encoded file is written to the output directory.
.SH SIZE REPORT TSV
When
.BR \-\-size\-report
is enabled, the TSV log uses this schema:
.PP
.RS
.nf
status	input_path	output_path	original_bytes	new_bytes	saved_pct
.fi
.RE
.PP
The status column is one of
.BR encoded ,
.BR skipped_codec ,
.BR skipped_larger
or
.BR failed .
The
.B input_path
field records the original input. The
.B output_path
field records the final encoded path for successful encodes and size-based
skips, and may be empty when no encoded output exists. Failed rows may leave
output-size fields empty when no encoded output exists.
.PP
.SH FILES
.TP
.IR "${XDG_CONFIG_HOME:-$HOME/.config}/transcode.sh/presets/<name>.sh"
Preset files. Each preset is sourced as Bash code and must define an
array variable named
.B ffargs
containing additional arguments for
.BR ffmpeg (1).
These variables are derived from the selected video probe stream, which
defaults to
.B v:0
and can be changed with
.BR \-\-video\-stream
or
.B [encoding] video_stream
in
.BR config.toml .
.RS
.TP
.B input_codec
The video codec of the input file as reported by
.BR ffprobe (1)
(e.g.\&
.IR h264 ,
.IR hevc ).
.TP
.B input_pixel_format
The pixel format of the input file after
.I yuvj*
normalisation (e.g.\&
.IR yuv420p ,
.IR yuv444p10le ).
.TP
.B output_pixel_format
The recommended output pixel format, automatically derived from the
input to preserve chroma subsampling (4:2:0, 4:2:2, 4:4:4) and bit
depth (8, 10, 12, 16\-bit).
.TP
.B input_frame_rate
The raw frame rate of the input video stream as reported by
.BR ffprobe (1),
expressed as a fraction (e.g.\&
.IR 30000/1001 ,
.IR 25/1 ,
.IR 60/1 ).
.TP
.B input_fps
The input frame rate rounded to the nearest integer (e.g.\&
.IR 30 ,
.IR 25 ,
.IR 60 ).
Derived from
.B input_frame_rate
and provided as a convenience for encoder heuristics that require a whole
number.
.TP
.B output_gop_size
The recommended GOP (Group of Pictures) size for the output, derived from
.B input_fps
as approximately five seconds of video (capped at 300 frames).
Use this in presets to set
.B \-g
for encoders that accept an explicit GOP size.
.RE
.IP
Before the preset's
.B ffargs
are appended, the script always passes the following base arguments to
.BR ffmpeg (1):
.RS
.nf
\-map 0          # include all streams from the input
\-map_metadata 0 # copy all container\-level metadata
\-map_chapters 0 # copy all chapter markers
\-c copy         # default to stream copy for every stream
.fi
.RE
.IP
A preset therefore only needs to specify the streams it wishes to
re-encode (typically
.BR \-c:v:0 )
and any associated encoder options. All other streams — audio,
subtitles, attachments — are passed through unchanged unless the preset
explicitly overrides them.
.IP
Example preset:
.RS
.nf
ffargs=( \-c:v:0 libsvtav1 \-crf 30 \-preset 6 \-pix_fmt "$output_pixel_format" )
.fi
.RE
.IP
.B Warning:
presets are executed as shell code. Only use presets from trusted
sources.
.TP
.IR "${XDG_CONFIG_HOME:-$HOME/.config}/transcode.sh/config.toml"
Optional TOML configuration file. Provides defaults for all options.
CLI flags generally take precedence. Skip codecs are additive by default:
configured codecs and CLI codecs are merged unless
.BR \-\-skip\-codec\-override
is used. The file must be valid TOML; an unparseable file is a hard error. Requires
.BR tomlq (1).
Supported sections and keys:
.RS
.TP
.B [encoding] preset
String. Default preset name. Equivalent to
.BR \-p .
.TP
.B [encoding] nice
Integer. Default niceness value. Equivalent to
.BR \-N .
.TP
.B [encoding] hwaccel
String or boolean.
.B false
disables hardware acceleration.
.B true
enables it with method
.BR auto .
Any other string (e.g.\&
.IR vaapi ,
.IR cuda )
enables it with that specific method.
Equivalent to
.BR \-\-hwaccel " / " \-\-no\-hwaccel .
.TP
.B [encoding] video_stream
String. Input video stream to probe for preset helper variables. Defaults to
.BR v:0 .
Equivalent to
.BR \-\-video\-stream .
Invalid configured values are ignored with a warning and the default is used.
This setting does not change ffmpeg stream mapping in presets.
.TP
.B [processing] skip_codecs
Array of strings. Merged with any codecs from
.BR \-S
by default. Use
.BR \-\-skip\-codec\-override
to ignore this configured list and use only codecs provided through
.BR \-S / \-\-skip\-codec .
.TP
.B [processing] backup_dir
String. Existing directory where originals are copied after successful
encoding and before replacement. Equivalent to
.BR \-\-backup\-dir .
CLI \fB--backup-dir\fR takes precedence.
.TP
.B [processing] output_dir
String. Existing directory where encoded files are written without replacing
originals. Equivalent to
.BR \-\-output\-dir .
CLI \fB--output-dir\fR takes precedence.
.TP
.B [processing] only_if_smaller
Boolean. Equivalent to
.BR \-\-only\-if\-smaller / \-\-no\-only\-if\-smaller .
.TP
.B [processing] verify_output
Boolean. Equivalent to
.BR \-\-verify\-output / \-\-no\-verify\-output .
Defaults to
.BR true .
.TP
.B [processing] continue
Boolean. Equivalent to
.BR \-c / \-\-continue / \-\-no\-continue .
.TP
.B [size_report] enabled
Boolean. Equivalent to
.BR \-s / \-\-no\-size\-report .
.TP
.B [size_report] file
String. Equivalent to
.BR \-\-size\-report\-file .
.TP
.B [output] verbose
Boolean. Equivalent to
.BR \-v .
.TP
.B [output] quiet
Boolean. Equivalent to
.BR \-q .
.TP
.B [output] ffmpeg_loglevel
String. Equivalent to
.BR \-\-ffmpeg\-loglevel .
Defaults to
.BR fatal .
.RE
.SH EXIT STATUS
.TP
.B 0
Success (or all skipped files were intentionally skipped).
.TP
.B 1
Runtime failure (e.g.
.BR ffmpeg (1)
error on one or more files).
.TP
.B 2
Usage error (invalid option or missing argument).
.TP
.B 3
Configuration error (missing or invalid preset).
.TP
.B 127
A required dependency
.RB ( ffmpeg ,
.BR ffprobe ,
.BR nice ,
.B tomlq
when
.B config.toml
is present) was not found.
.SH EXAMPLES
Transcode a single file using the default preset:
.PP
.RS
.nf
transcode.sh video.mp4
.fi
.RE
.PP
Transcode a batch of files listed in a file and print/write a size report:
.PP
.RS
.nf
transcode.sh \-s \-f list.txt
.fi
.RE
.PP
Dry-run with verbosity to inspect detected formats:
.PP
.RS
.nf
transcode.sh \-n \-v my_movie.mkv
.fi
.RE
.PP
Write encoded copies elsewhere without replacing originals:
.PP
.RS
.nf
transcode.sh \-\-preset av1 \-\-output\-dir ./encoded video.mp4
.fi
.RE
.PP
Use a custom preset and only keep the result if it is smaller:
.PP
.RS
.nf
transcode.sh \-p av1_fast \-l /media/films/*.mkv
.fi
.RE
.PP
Run at a less aggressive niceness and skip already-AV1 files:
.PP
.RS
.nf
transcode.sh \-N 10 \-S av1 input.mkv
.fi
.RE
.PP
Temporarily replace configured skip codecs with only HEVC:
.PP
.RS
.nf
transcode.sh \-\-skip\-codec\-override \-S hevc input.mkv
.fi
.RE
.PP
Load an alternative configuration file:
.PP
.RS
.nf
transcode.sh \-\-config\-file ~/profiles/fast.toml input.mp4
.fi
.RE
.PP
Probe the second video stream for preset helper variables:
.PP
.RS
.nf
transcode.sh \-\-video\-stream v:1 \-n \-v input.mkv
.fi
.RE
.SH SEE ALSO
.BR ffmpeg (1),
.BR ffprobe (1),
.BR nice (1),
.BR tomlq (1)
.SH AUTHOR
Dennis Fink <me+coding@dennisfink.me>
.SH LICENSE
BSD\-3\-Clause