From deb787ab8c2e4425bd170a2645306561af36316e Mon Sep 17 00:00:00 2001
From: Dennis Fink
Date: Sun, 22 Feb 2026 10:00:21 +0100
Subject: docs: document base ffmpeg arguments passed before preset ffargs

Both the README and the man page now explain that the script always
passes -map 0, -map_metadata 0, -map_chapters 0, and -c copy to
ffmpeg before appending the preset's ffargs array. This context is
important for preset authors, who only need to override the streams
they intend to re-encode.

Also fix a minor blockquote rendering issue in the README (missing
blank line before the fenced code block in the PATH note).
---
 README.md      | 18 +++++++++++++++++-
 transcode.sh.1 | 20 ++++++++++++++++++++
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 65db49a..4001672 100644
--- a/README.md
+++ b/README.md
@@ -59,8 +59,9 @@ install -Dm644 transcode.sh.bash-completion \
 ```
 
 > **PATH note:** the script resets `PATH` to `/bin:/usr/bin:/usr/local/bin`
-> for security.  If your `ffmpeg` lives elsewhere (e.g. Homebrew on macOS,
+> for security. If your `ffmpeg` lives elsewhere (e.g. Homebrew on macOS,
 > Nix), prepend its directory:
+>
 > ```sh
 > PATH="/opt/homebrew/bin:$PATH" transcode.sh input.mp4
 > ```
@@ -79,6 +80,21 @@ Each preset is sourced as Bash and must define an array named `ffargs`.
 The variable `output_pixel_format` is available and contains the
 automatically selected pixel format (derived from the input file).
 
+Before the preset's `ffargs` are appended, the script always passes
+these base arguments to `ffmpeg`:
+
+```
+-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
+```
+
+A preset therefore only needs to specify the streams it wishes to
+re-encode (typically `-c:v:0`) and any associated encoder options.
+All other streams — audio, subtitles, attachments — are passed through
+unchanged unless the preset explicitly overrides them.
+
 **Example — `~/.config/transcode.sh/presets/default.sh`:**
 
 ```sh
diff --git a/transcode.sh.1 b/transcode.sh.1
index 9001e8a..fe38c21 100644
--- a/transcode.sh.1
+++ b/transcode.sh.1
@@ -158,6 +158,26 @@ The variable
 is available to presets and contains the automatically selected output
 pixel format string.
 .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
-- 
cgit v1.3.1