From dc3d2cb05800d866972b7ba32022428e8474beaa Mon Sep 17 00:00:00 2001
From: Dennis Fink
Date: Thu, 14 May 2026 09:56:14 +0200
Subject: feat(size-report): replace savings log with status reports

Rename the old savings log feature to size report across the CLI,
configuration, documentation, man page, and bash completion. The new
`--size-report` option keeps the existing `-s` shorthand, while
`--saving`, `--saving-file`, and the `[saving]` config section are
replaced by `--size-report`, `--size-report-file`, and `[size_report]`.

Extend reporting beyond successful encodes. The TSV log now gains a
leading `status` column and records encoded files, codec skips,
only-if-larger skips, and failed inputs. Size-report output also prints
per-file feedback for encoded and skipped-larger files, including
human-readable original/new sizes, bytes saved, and saved percentage.

Track batch-level report counters and print an end-of-run summary for
multi-file runs with encoded/skipped/failed counts, total bytes saved,
and the overall weighted saving percentage across successful encodes.

Document the new TSV schema in the README and man page, update examples
and config snippets, and adjust bash completion for the renamed options.

BREAKING CHANGE: `--saving` is now `--size-report`. `--saving-file` is
now `--size-report-file`. `[saving]` in config.toml is now
`[size_report]`. The TSV log gains a leading `status` column and may
contain skipped and failed rows in addition to successful encodes.
---
 README.md | 38 ++++++++++++++++++++++++++++----------
 1 file changed, 28 insertions(+), 10 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 3c4053f..85e45b3 100644
--- a/README.md
+++ b/README.md
@@ -18,8 +18,8 @@ replaces the original atomically on success.
   untouched (e.g. skip files already encoded as AV1).
 - **Only-if-smaller mode** (`-l`) — discard the re-encoded file if it is
   larger than the original.
-- **Savings log** (`-s`) — append filename, original size, new size and
-  percentage saved to a log file after each successful encode.
+- **Size report** (`-s`) — print per-file size feedback, show a batch
+  summary, and write a status TSV log for encoded, skipped, and failed files.
 - **Dry-run** (`-n`) — preview what would happen without touching any files.
 - **Nice** — runs ffmpeg at niceness 19 by default to avoid starving other
   processes; configurable with `-N`.
@@ -146,9 +146,9 @@ nice   = 10
 [skip]
 codecs = ["av1", "hevc"]
 
-[saving]
+[size_report]
 enabled = true
-file    = "transcode_savings"
+file    = "transcode_size_report"
 
 [output]
 verbose = false
@@ -162,8 +162,8 @@ quiet   = false
 | `[encoding]` | `verify_output` | boolean | `--verify-output` |
 | `[encoding]` | `hwaccel` | string or boolean | `--hwaccel` / `--no-hwaccel` |
 | `[skip]` | `codecs` | array of strings | `-S` (merged with CLI) |
-| `[saving]` | `enabled` | boolean | `-s` |
-| `[saving]` | `file` | string | `--saving-file` |
+| `[size_report]` | `enabled` | boolean | `-s` / `--no-size-report` |
+| `[size_report]` | `file` | string | `--size-report-file` |
 | `[output]` | `verbose` | boolean | `-v` |
 | `[output]` | `quiet` | boolean | `-q` |
 
@@ -198,8 +198,9 @@ transcode.sh [OPTION] [--] FILE...
 | `-N VALUE`, `--nice VALUE`, `--nice=VALUE` | Niceness value 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`, `--saving` | Log filesize savings after each encode |
-| `--saving-file PATH`, `--saving-file=PATH` | Savings log path (default: `transcode_savings`) |
+| `-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`) |
 | `-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 |
@@ -217,8 +218,8 @@ transcode.sh [OPTION] [--] FILE...
 # Transcode a single file with the default preset
 transcode.sh video.mp4
 
-# Transcode a list of files and record size savings
-transcode.sh --saving --encodefile list.txt
+# Transcode a list of files and print/write a size report
+transcode.sh --size-report --encode-file list.txt
 
 # Dry-run with verbose output to inspect detected formats
 transcode.sh --dry-run --verbose my_movie.mkv
@@ -233,6 +234,23 @@ transcode.sh --nice 10 --continue *.mp4
 transcode.sh --config-file ~/profiles/fast.toml input.mp4
 ```
 
+## Size report TSV
+
+When `--size-report` is enabled, the TSV log uses this schema:
+
+```tsv
+status	filename	original_bytes	new_bytes	saved_pct
+```
+
+The `status` column is one of `encoded`, `skipped_codec`, `skipped_larger`,
+or `failed`. Failed rows may leave `new_bytes` and `saved_pct` empty when no
+encoded output exists. `skipped_larger` rows record the temporary output size
+and therefore usually have a negative `saved_pct`; the original file is kept.
+
+For runs with more than one input file, `--size-report` also prints an end
+summary with encoded/skipped/failed counts, total bytes saved, and the overall
+weighted saving percentage across successful encodes.
+
 ## Debugging
 
 ```sh
-- 
cgit v1.3.1