path: root/transcode.sh.1

\# 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
Encoding is performed into a temporary file in the same directory as the
input, which ensures an atomic rename on completion.
.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 \-\-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 \-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 ", " \-\-saving
After each successful encode, append a line to the savings log file
recording the filename, original size in bytes, new size in bytes and the
percentage saved. Requires
.BR bc (1).
.TP
.BR \-\-saving\-file " \fIPATH\fR, " \-\-saving\-file= \fIPATH\fR
Path to the savings log file written by
.BR \-\-saving .
Defaults to
.B transcode_savings
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 \-\-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 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 [skip] codecs
Array of strings. Merged with any codecs from
.BR \-S .
.TP
.B [saving] enabled
Boolean. Equivalent to
.BR \-s .
.TP
.B [saving] file
String. Equivalent to
.BR \-\-saving\-file .
.TP
.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 bc
when
.B \-\-saving
is active, or
.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 log size savings:
.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
.PP
Use
.BR ffmpeg (1)
installed via Homebrew (macOS):
.PP
.RS
.nf
PATH="/opt/homebrew/bin:$PATH" transcode.sh input.mp4
.fi
.RE
.SH NOTES
The script resets
.B PATH
to
.I /bin:/usr/bin:/usr/local/bin
for security. If
.BR ffmpeg (1)
is installed outside these directories (e.g. via Homebrew or Nix),
prepend the correct directory to
.B PATH
before invoking
.BR transcode.sh .
.SH SEE ALSO
.BR ffmpeg (1),
.BR ffprobe (1),
.BR nice (1),
.BR bc (1),
.BR tomlq (1)
.SH AUTHOR
Dennis Fink <me+coding@dennisfink.me>
.SH LICENSE
BSD\-3\-Clause