diff options
| author | Dennis Fink | 2026-05-08 19:41:14 +0200 |
|---|---|---|
| committer | Dennis Fink | 2026-05-08 19:41:14 +0200 |
| commit | 7e73a76bba167c2a6d5bd9afc145690c5049ebf2 (patch) | |
| tree | e3d6f0596f3d7083c5b9c2141649590a2931a5d3 /README.md | |
| parent | aea6e655e1c572c2a11c5438c57634f15649bf5e (diff) | |
| download | transcode.sh-7e73a76bba167c2a6d5bd9afc145690c5049ebf2.tar.gz transcode.sh-7e73a76bba167c2a6d5bd9afc145690c5049ebf2.zip | |
feat(cli)!: add TOML config file support
Add a structured config file so common defaults can live in one place
instead of being repeated in aliases or shell wrappers. CLI flags keep
precedence, which keeps one-off overrides predictable.
Use tomlq only when a config file is present, and fail early on missing
dependencies or invalid TOML so configuration mistakes do not silently
change encode behavior.
Move the persistent skip-codec list from the legacy skip.conf file to
[skip] codecs in config.toml. Config codecs are merged with --skip-codec
so global defaults and per-run skips can be combined.
Document the new format in the README and man page, update dependency
notes, and extend bash completion for config-file paths and the new
negative boolean flags.
BREAKING CHANGE: skip.conf is no longer read for codec skips. Migrate
its entries to [skip] codecs in config.toml and remove the old file.
BREAKING CHANGE: --encodefile and --encodefile= are replaced by
--encode-file and --encode-file=. Update scripts, aliases, and
completion usage to use the hyphenated option name.
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 59 |
1 files changed, 50 insertions, 9 deletions
@@ -33,6 +33,7 @@ replaces the original atomically on success. | `ffprobe` | always | codec/format detection | | `nice` | always | process priority control | | `bc` | only with `--saving` | percentage calculation | +| `tomlq` | only when `config.toml` is present | TOML config parsing | ## Installation @@ -114,22 +115,56 @@ ffargs=( > **Security:** presets are executed as shell code. Only use presets from > trusted sources. -### Codec skip list +### Configuration file -To permanently skip files that are already in a particular codec, add codec -names (one per line) to: +An optional TOML configuration file can be placed at: ``` -${XDG_CONFIG_HOME:-$HOME/.config}/transcode.sh/skip.conf +${XDG_CONFIG_HOME:-$HOME/.config}/transcode.sh/config.toml ``` -**Example — skip files already encoded as AV1 or HEVC:** +Use `--config-file FILE` to load an alternative path. CLI flags always take +precedence over values in the config file. The file must be valid TOML — an +unparseable file is a hard error. Requires `tomlq` when the file is present. -``` -av1 -hevc +**Example `config.toml`:** + +```toml +[encoding] +preset = "av1" +nice = 10 + +[skip] +codecs = ["av1", "hevc"] + +[saving] +enabled = true +file = "transcode_savings" + +[output] +verbose = false +quiet = false ``` +| Section | Key | Type | CLI equivalent | +|---------|-----|------|----------------| +| `[encoding]` | `preset` | string | `-p` | +| `[encoding]` | `nice` | integer | `-N` | +| `[skip]` | `codecs` | array of strings | `-S` (merged with CLI) | +| `[saving]` | `enabled` | boolean | `-s` | +| `[saving]` | `file` | string | `--saving-file` | +| `[output]` | `verbose` | boolean | `-v` | +| `[output]` | `quiet` | boolean | `-q` | + +> **Note:** `[skip] codecs` from the config file and `--skip-codec` from the +> CLI are **merged** — both sources contribute to the skip list. + +### Codec skip list (deprecated) + +The legacy `skip.conf` file is no longer read. If it still exists, a +deprecation warning is printed at startup. Migrate its contents to +`[skip] codecs` in `config.toml` and delete the old file. + ## Usage ``` @@ -139,13 +174,16 @@ transcode.sh [OPTION] [--] FILE... | Option | Description | |--------|-------------| | `-c`, `--continue` | Continue to next file if ffmpeg fails | -| `-f PATH`, `--encodefile PATH`, `--encodefile=PATH` | Read file list from PATH (one per line) | +| `--no-continue` | Do not continue with the next file if ffmpeg fails | +| `--config-file FILE`, `--config-file=FILE` | Load configuration from FILE instead of the default path | +| `-f PATH`, `--encode-file PATH`, `--encodefile=PATH` | Read file list from PATH (one per line) | | `-n`, `--dry-run` | Show what would be done; don't run ffmpeg | | `-N VALUE`, `--nice VALUE`, `--nice=VALUE` | Niceness value for ffmpeg (default: 19) | | `-s`, `--saving` | Log filesize savings after each encode | | `--saving-file PATH`, `--saving-file=PATH` | Savings log path (default: `transcode_savings`) | | `-S LIST`, `--skip-codec LIST`, `--skip-codec=LIST` | Codecs to skip (comma/space/colon separated) | | `-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`) | | `-q`, `--quiet` | Suppress all output (overrides `-v`) | | `-v`, `--verbose` | More detailed output | @@ -170,6 +208,9 @@ transcode.sh --preset av1_fast --only-if-smaller --skip-codec av1 /media/films/* # Run at a moderate priority and continue past failures transcode.sh --nice 10 --continue *.mp4 + +# Load an alternative config file +transcode.sh --config-file ~/profiles/fast.toml input.mp4 ``` ## Debugging |
