\# SPDX-FileCopyrightText: 2025 Dennis Fink <me+coding@dennisfink.me>
\# SPDX-License-Identifier: BSD-3-Clause
.TH TRANSCODE.SH 1 "2026-02-02" "1.0.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.
.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 and pixel format. 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
.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.
.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 \-\-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 \-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.
.TP
.BR \-n ", " \-\-dry\-run
Print what would be done without actually invoking
.BR ffmpeg (1).
Combine with
.B \-v
to see the detected codec and pixel format information.
.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 \-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 \-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.
.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.
Codecs specified here are merged with any codecs listed under
.B [skip] codecs
in
.B config.toml
\(em both sources contribute to the skip list.
.TP
.BR \-l ", " \-\-only\-if\-smaller
After encoding, replace the original only when the new file is strictly
smaller. If the transcoded file is larger the temporary file is removed
and the original is kept unchanged.
.TP
.BR \-\-no\-only\-if\-smaller
After encoding, replace the original also if the new file is bigger.
.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 \-h ", " \-\-help ", " \-?
Print a short help message and exit.
.TP
.BR \-q ", " \-\-quiet
Suppress all normal output. Takes precedence over
.BR \-v / \-\-verbose .
.TP
.BR \-v ", " \-\-verbose
Emit additional informational messages (detected codec, pixel format,
etc.).
.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 \-\-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.
.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 SIZE REPORT TSV
When
.BR \-\-size\-report
is enabled, the TSV log uses this schema:
.PP
.RS
.nf
status	filename	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 .
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).
The following variables are available to presets at source time:
.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 always take precedence. 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] verify_output
Boolean. Equivalent to
.BR \-\-verify\-output / \-\-no\-verify\-output .
Defaults to
.BR true .
.TP
.B [skip] codecs
Array of strings. Merged with any codecs from
.BR \-S .
.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 .
.B [output] verbose
Boolean. Equivalent to
.BR \-v .
.TP
.B [output] quiet
Boolean. Equivalent to
.BR \-q .
.RE
.TP
.IR "${XDG_CONFIG_HOME:-$HOME/.config}/transcode.sh/skip.conf"
.B Deprecated.
This file is no longer read. If it exists, a warning is printed.
Migrate its contents to
.B [skip] codecs
in
.B config.toml
and delete the file.
.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
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
Load an alternative configuration file:
.PP
.RS
.nf
transcode.sh \-\-config\-file ~/profiles/fast.toml input.mp4
.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