From 7e73a76bba167c2a6d5bd9afc145690c5049ebf2 Mon Sep 17 00:00:00 2001
From: Dennis Fink
Date: Fri, 8 May 2026 19:41:14 +0200
Subject: 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.
---
 README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 50 insertions(+), 9 deletions(-)

(limited to 'README.md')

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
-- 
cgit v1.3.1