diff options
| author | Dennis Fink | 2026-05-24 17:09:09 +0200 |
|---|---|---|
| committer | Dennis Fink | 2026-05-24 17:09:09 +0200 |
| commit | 8804eba7a519bccc6c0ae6b90d666d4e1c09eaf0 (patch) | |
| tree | b696ce8851e4297cea664f3fd230d926da94b7ae /README.md | |
| parent | a049faf194165e74c8d75c85bb4473fedf7e6dbd (diff) | |
| download | transcode.sh-8804eba7a519bccc6c0ae6b90d666d4e1c09eaf0.tar.gz transcode.sh-8804eba7a519bccc6c0ae6b90d666d4e1c09eaf0.zip | |
docs(cli): regroup option documentation
Reorganize CLI options into matching sections across help output,
README, man page, and bash completion.
Split input, encoding, skip, processing, size report, display, and
general options so related flags are easier to find and the documented
order matches the parser more closely.
Add --no-config to the README and man page while updating bash
completion order to follow the new help structure.
Diffstat (limited to '')
| -rw-r--r-- | README.md | 84 |
1 files changed, 59 insertions, 25 deletions
@@ -153,11 +153,12 @@ An optional TOML configuration file can be placed at: ${XDG_CONFIG_HOME:-$HOME/.config}/transcode.sh/config.toml ``` -Use `--config-file FILE` to load an alternative path. CLI flags generally take -precedence over values in the config file. Skip codecs are additive by default: -configured codecs and CLI codecs are merged unless `--skip-codec-override` is -used. The file must be valid TOML — an unparseable file is a hard error. -Requires `tomlq` when the file is present. +Use `--config-file FILE` to load an alternative path, or `--no-config` to skip +configuration loading entirely. CLI flags generally take precedence over values +in the config file. Skip codecs are additive by default: configured codecs and +CLI codecs are merged unless `--skip-codec-override` is used. The file must be +valid TOML — an unparseable file is a hard error. Requires `tomlq` when the +file is present. **Example `config.toml`:** @@ -182,18 +183,18 @@ quiet = false | Section | Key | Type | CLI equivalent | |---------|-----|------|----------------| -| `[encoding]` | `backup_dir` | string | `--backup-dir` | -| `[encoding]` | `hwaccel` | string or boolean | `--hwaccel` / `--no-hwaccel` | -| `[encoding]` | `nice` | integer | `-N` | | `[encoding]` | `preset` | string | `-p` | -| `[encoding]` | `verify_output` | boolean | `--verify-output` | +| `[encoding]` | `nice` | integer | `-N` | +| `[encoding]` | `hwaccel` | string or boolean | `--hwaccel` / `--no-hwaccel` | | `[encoding]` | `video_stream` | string | `--video-stream` | -| `[output]` | `quiet` | boolean | `-q` | -| `[output]` | `verbose` | boolean | `-v` | -| `[output]` | `ffmpeg_loglevel` | string | `--ffmpeg-loglevel` | +| `[encoding]` | `backup_dir` | string | `--backup-dir` | +| `[encoding]` | `verify_output` | boolean | `--verify-output` | +| `[skip]` | `codecs` | array of strings | `-S` / `--skip-codec-override` | | `[size_report]` | `enabled` | boolean | `-s` / `--no-size-report` | | `[size_report]` | `file` | string | `--size-report-file` | -| `[skip]` | `codecs` | array of strings | `-S` / `--skip-codec-override` | +| `[output]` | `ffmpeg_loglevel` | string | `--ffmpeg-loglevel` | +| `[output]` | `quiet` | boolean | `-q` | +| `[output]` | `verbose` | boolean | `-v` | > **Note:** `[skip] codecs` from the config file and `--skip-codec` from the > CLI are **merged** by default — both sources contribute to the skip list. Use @@ -225,35 +226,68 @@ deprecation warning is printed at startup. Migrate its contents to transcode.sh [OPTION] [--] FILE... ``` +### Input options + | Option | Description | |--------|-------------| -| `-c`, `--continue` | Continue to next file if ffmpeg fails | -| `--no-continue` | Do not continue with the next file if ffmpeg fails | -| `--verify-output` | Probe output with ffprobe before replacing original (default) | -| `--no-verify-output` | Skip the post-encode integrity check | | `--config-file FILE`, `--config-file=FILE` | Load configuration from FILE instead of the default path | +| `--no-config` | Do not load any configuration file | | `-f PATH`, `--encode-file PATH`, `--encode-file=PATH` | Read file list from PATH (one per line) | -| `-n`, `--dry-run` | Show what would be done; don't run ffmpeg | -| `--backup-dir DIR`, `--backup-dir=DIR` | Copy originals to an existing backup directory before replacing them | + +### Encoding options + +| Option | Description | +|--------|-------------| +| `-p NAME`, `--preset NAME`, `--preset=NAME` | Preset to use (default: `default`) | | `-N VALUE`, `--nice VALUE`, `--nice=VALUE` | Nice adjustment for ffmpeg (default: 19) | | `--hwaccel [METHOD]`, `--hwaccel=METHOD` | Enable hardware acceleration; METHOD defaults to `auto` if omitted (e.g. `cuda`, `vaapi`, `videotoolbox`); enabled by default | | `--no-hwaccel` | Disable hardware acceleration (omit `-hwaccel` from ffmpeg invocation) | -| `-s`, `--size-report` | Print per-file size feedback and write a status TSV log | -| `--no-size-report` | Disable a size report enabled in `config.toml` | -| `--size-report-file PATH`, `--size-report-file=PATH` | Size report TSV path (default: `transcode_size_report`) | +| `--video-stream STREAM_SELECTOR`, `--video-stream=STREAM_SELECTOR` | Select the input video stream to probe for preset helper variables, e.g. `v:0` or `v:1` (default: `v:0`) | + +### Skip options + +| Option | Description | +|--------|-------------| | `-S LIST`, `--skip-codec LIST`, `--skip-codec=LIST` | Add codecs to the effective skip list (comma/space/colon separated) | | `--skip-codec-override` | Use only codecs from `--skip-codec`, ignoring `[skip].codecs` from config | + +### Processing options + +| Option | Description | +|--------|-------------| +| `-n`, `--dry-run` | Show what would be done; don't run ffmpeg | +| `--backup-dir DIR`, `--backup-dir=DIR` | Copy originals to an existing backup directory before replacing them | | `-l`, `--only-if-smaller` | Only replace original if new file is smaller | | `--no-only-if-smaller` | Do replace original even if new file is bigger | -| `-p NAME`, `--preset NAME`, `--preset=NAME` | Preset to use (default: `default`) | -| `--video-stream STREAM_SELECTOR`, `--video-stream=STREAM_SELECTOR` | Select the input video stream to probe for preset helper variables, e.g. `v:0` or `v:1` (default: `v:0`) | +| `--verify-output` | Probe output with ffprobe before replacing original (default) | +| `--no-verify-output` | Skip the post-encode integrity check | +| `-c`, `--continue` | Continue to next file if ffmpeg fails | +| `--no-continue` | Do not continue with the next file if ffmpeg fails | + +### Size report options + +| Option | Description | +|--------|-------------| +| `-s`, `--size-report` | Print per-file size feedback and write a status TSV log | +| `--no-size-report` | Disable a size report enabled in config | +| `--size-report-file PATH`, `--size-report-file=PATH` | Size report TSV path (default: `transcode_size_report`) | + +### Display options + +| Option | Description | +|--------|-------------| | `--ffmpeg-loglevel LEVEL`, `--ffmpeg-loglevel=LEVEL` | Specify the loglevel to pass to ffmpeg (default: `fatal`) | | `-q`, `--quiet` | Suppress all output (overrides `-v`) | | `-v`, `--verbose` | More detailed output | | `--color` / `--no-color` | Force or disable colored output | + +### General options + +| Option | Description | +|--------|-------------| +| `-h`, `-?`, `--help` | Show help and exit | | `--version` | Print version information | | `--list-presets` | List available presets (name + description) and exit | -| `-h`, `-?`, `--help` | Show help and exit | ### Examples |
