aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorDennis Fink2026-05-08 19:41:14 +0200
committerDennis Fink2026-05-08 19:41:14 +0200
commit7e73a76bba167c2a6d5bd9afc145690c5049ebf2 (patch)
treee3d6f0596f3d7083c5b9c2141649590a2931a5d3 /README.md
parentaea6e655e1c572c2a11c5438c57634f15649bf5e (diff)
downloadtranscode.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.md59
1 files changed, 50 insertions, 9 deletions
diff --git a/README.md b/README.md
index 64dd6c0..6d6c74d 100644
--- a/README.md
+++ b/README.md
@@ -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