docs: document --keep-mtime and bit-depth preservation

Update the CLI options reference and the What's New / Features sections,
and regenerate the bash and zsh shell completions for the new options.

Author: slhck

README.md

@@ -33,6 +33,14 @@ This program normalizes media files to a certain loudness level using the EBU R1
 
 ## 🆕 What's New
 
+- Version 1.39.0 preserves the **input bit depth** by default when encoding to formats like FLAC, so 16-bit input stays 16-bit without needing `-e "-sample_fmt s16"`. Use `--no-keep-bit-depth` to opt out. It also adds `--keep-mtime` to copy the input file's modification time to the output, which is useful for preserving when a track was added to a music library.
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize input.flac -nt peak -t 0 -c:a flac --keep-mtime -o output.flac
+    ```
+
 - Version 1.38.0 writes the normalized output  directly to the destination without using temporary files
 
 - Version 1.36.0 introduces **presets** with `--preset`! Save and reuse your favorite normalization configurations for different use cases. Comes with three built-in presets: `podcast` (AES standard), `music` (RMS-based batch normalization), and `streaming-video` (video content). Create custom presets too!

completions/ffmpeg-normalize-shtab.bash

@@ -2,7 +2,7 @@
 
 
 
-_shtab_ffmpeg_normalize_option_strings=('-h' '--help' '--input-list' '-o' '--output' '-of' '--output-folder' '-f' '--force' '-d' '--debug' '-v' '--verbose' '-q' '--quiet' '-n' '--dry-run' '-pr' '--progress' '--version' '--preset' '--list-presets' '-nt' '--normalization-type' '-t' '--target-level' '-p' '--print-stats' '--replaygain' '--batch' '-lrt' '--loudness-range-target' '--keep-loudness-range-target' '--keep-lra-above-loudness-range-target' '-tp' '--true-peak' '--offset' '--lower-only' '--auto-lower-loudness-target' '--dual-mono' '--dynamic' '-as' '--audio-streams' '--audio-default-only' '--keep-other-audio' '-c:a' '--audio-codec' '-b:a' '--audio-bitrate' '-ar' '--sample-rate' '-ac' '--audio-channels' '-koa' '--keep-original-audio' '-prf' '--pre-filter' '-pof' '--post-filter' '-vn' '--video-disable' '-c:v' '--video-codec' '-sn' '--subtitle-disable' '-mn' '--metadata-disable' '-cn' '--chapters-disable' '-ei' '--extra-input-options' '-e' '--extra-output-options' '-ofmt' '--output-format' '-ext' '--extension')
+_shtab_ffmpeg_normalize_option_strings=('-h' '--help' '--input-list' '-o' '--output' '-of' '--output-folder' '--keep-mtime' '-f' '--force' '-d' '--debug' '-v' '--verbose' '-q' '--quiet' '-n' '--dry-run' '-pr' '--progress' '--version' '--preset' '--list-presets' '-nt' '--normalization-type' '-t' '--target-level' '-p' '--print-stats' '--replaygain' '--batch' '-lrt' '--loudness-range-target' '--keep-loudness-range-target' '--keep-lra-above-loudness-range-target' '-tp' '--true-peak' '--offset' '--lower-only' '--auto-lower-loudness-target' '--dual-mono' '--dynamic' '-as' '--audio-streams' '--audio-default-only' '--keep-other-audio' '-c:a' '--audio-codec' '-b:a' '--audio-bitrate' '-ar' '--sample-rate' '-ac' '--audio-channels' '-koa' '--keep-original-audio' '--keep-bit-depth' '--no-keep-bit-depth' '-prf' '--pre-filter' '-pof' '--post-filter' '-vn' '--video-disable' '-c:v' '--video-codec' '-sn' '--subtitle-disable' '-mn' '--metadata-disable' '-cn' '--chapters-disable' '-ei' '--extra-input-options' '-e' '--extra-output-options' '-ofmt' '--output-format' '-ext' '--extension')
 
 
 
@@ -14,6 +14,7 @@ _shtab_ffmpeg_normalize__h_nargs=0
 _shtab_ffmpeg_normalize___help_nargs=0
 _shtab_ffmpeg_normalize__o_nargs=+
 _shtab_ffmpeg_normalize___output_nargs=+
+_shtab_ffmpeg_normalize___keep_mtime_nargs=0
 _shtab_ffmpeg_normalize__f_nargs=0
 _shtab_ffmpeg_normalize___force_nargs=0
 _shtab_ffmpeg_normalize__d_nargs=0
@@ -42,6 +43,8 @@ _shtab_ffmpeg_normalize___audio_default_only_nargs=0
 _shtab_ffmpeg_normalize___keep_other_audio_nargs=0
 _shtab_ffmpeg_normalize__koa_nargs=0
 _shtab_ffmpeg_normalize___keep_original_audio_nargs=0
+_shtab_ffmpeg_normalize___keep_bit_depth_nargs=0
+_shtab_ffmpeg_normalize___no_keep_bit_depth_nargs=0
 _shtab_ffmpeg_normalize__vn_nargs=0
 _shtab_ffmpeg_normalize___video_disable_nargs=0
 _shtab_ffmpeg_normalize__sn_nargs=0

completions/ffmpeg-normalize-shtab.zsh

@@ -5,7 +5,7 @@
 
 _shtab_ffmpeg_normalize_commands() {
   local _commands=(
-
+    
   )
   _describe 'ffmpeg-normalize commands' _commands
 }
@@ -26,6 +26,11 @@ Example\: ffmpeg-normalize 1.wav 2.wav -o 1n.wav 2n.wav
 This folder will be used for input files that have no explicit output
 name specified.
 ]:output_folder:"
+  "--keep-mtime[Copy the input file\'s modification time to the output file.
+
+Only the access and modification times are copied\; a file\'s creation
+time (tracked separately on some operating systems) is not affected.
+]"
   {-f,--force}"[Force overwrite existing files]"
   {-d,--debug}"[Print debugging output]"
   {-v,--verbose}"[Print verbose output]"
@@ -54,7 +59,7 @@ level.
 
 Peak normalization brings the signal to the specified peak level.
 ]:normalization_type:(ebu rms peak)"
-  {-t,--target-level}"[Normalization target level in dB\/LUFS (default\: -23).
+  {-t,--target-level}"[Normalization target level in dB\/LUFS (default\: -23.0).
 
 For EBU normalization, it corresponds to Integrated Loudness Target
 in LUFS. The range is -70.0 - -5.0.
@@ -155,6 +160,18 @@ which will change the input sample rate to 192 kHz.
 If not specified, the input channel layout will be used.
 ]:audio_channels:"
   {-koa,--keep-original-audio}"[Copy original, non-normalized audio streams to output file]"
+  {--keep-bit-depth,--no-keep-bit-depth}"[Carry the detected input bit depth through to the output encoder
+(default\: enabled).
+
+By default, the matching output sample format is set for the chosen
+encoder (e.g. FLAC), so you do not need to pass it via
+\`-e\`\/\`--extra-output-options\` yourself. Use \`--no-keep-bit-depth\` to let
+the encoder pick its own sample format instead.
+
+The chosen sample format is constrained to what the encoder supports.
+ffmpeg has no 24-bit sample format, so 24-bit audio is carried in the
+32-bit \`s32\` format. Floating-point sources are left to the encoder.
+]:keep_bit_depth:"
   {-prf,--pre-filter}"[Add an audio filter chain before applying normalization.
 Multiple filters can be specified by comma-separating them.
 ]:pre_filter:"
@@ -231,7 +248,7 @@ _shtab_ffmpeg_normalize() {
       (( CURRENT += 1 ))
       curcontext="${curcontext%:*:*}:_shtab_ffmpeg_normalize-$line[1]:"
       case $line[1] in
-
+        
       esac
   esac
 }

completions/ffmpeg-normalize.bash

@@ -10,6 +10,7 @@ _ffmpeg_normalize()
     opts="--input-list \
           -o --output \
           -of --output-folder \
+          --keep-mtime \
           -f --force \
           -d --debug \
           -v --verbose \
@@ -38,6 +39,7 @@ _ffmpeg_normalize()
           -ar --sample-rate \
           -ac --audio-channels \
           -koa --keep-original-audio \
+          --keep-bit-depth --no-keep-bit-depth \
           -prf --pre-filter \
           -pof --post-filter \
           -vn --video-disable \

completions/ffmpeg-normalize.zsh

@@ -10,6 +10,7 @@ _ffmpeg_normalize() {
     '--input-list[Read input list from file]:input list:_files'
     '(-o --output)'{-o,--output}'[Output file names]:output file:_files'
     '(-of --output-folder)'{-of,--output-folder}'[Output folder (default: normalized)]:directory:_files -/'
+    '--keep-mtime[Copy the input file modification time to the output file]'
 
     # General Options
     '(-f --force)'{-f,--force}'[Force overwrite existing files]'
@@ -46,6 +47,7 @@ _ffmpeg_normalize() {
     '(-ar --sample-rate)'{-ar,--sample-rate}'[Audio sample rate]:sample rate:'
     '(-ac --audio-channels)'{-ac,--audio-channels}'[Number of audio channels]:channels:'
     '(-koa --keep-original-audio)'{-koa,--keep-original-audio}'[Keep original audio streams]'
+    '(--keep-bit-depth --no-keep-bit-depth)'{--keep-bit-depth,--no-keep-bit-depth}'[Carry the input bit depth through to the output encoder (default: on)]'
     '(-prf --pre-filter)'{-prf,--pre-filter}'[Pre-normalization audio filter]:filter:'
     '(-pof --post-filter)'{-pof,--post-filter}'[Post-normalization audio filter]:filter:'
 

docs/index.md

@@ -31,6 +31,14 @@ Batch processing of several input files is possible, including video files.
 
 ## 🆕 What's New
 
+- Version 1.39.0 preserves the **input bit depth** by default when encoding to formats like FLAC, so 16-bit input stays 16-bit without needing `-e "-sample_fmt s16"`. Use `--no-keep-bit-depth` to opt out. It also adds `--keep-mtime` to copy the input file's modification time to the output, which is useful for preserving when a track was added to a music library.
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize input.flac -nt peak -t 0 -c:a flac --keep-mtime -o output.flac
+    ```
+
 - Version 1.38.0 writes the normalized output directly to its destination without using temporary files
 
 - Version 1.36.0 introduces **presets** with `--preset`! Save and reuse your favorite normalization configurations for different use cases. Comes with three built-in presets: `podcast` (AES standard), `music` (RMS-based batch normalization), and `streaming-video` (video content). Create custom presets too!

docs/usage/cli-options.md

@@ -31,6 +31,12 @@ Output folder (default: `normalized`)
 
 This folder will be used for input files that have no explicit output name specified.
 
+### `--keep-mtime`
+
+Copy the input file's modification time to the output file.
+
+This is useful when you want to preserve the time a file was originally added to your collection (e.g. for sorting in a music library). Only the access and modification times are copied; a file's creation time (which some operating systems such as Windows track separately) is not affected.
+
 ## General
 
 ### `-f, --force`
@@ -222,6 +228,16 @@ Set the number of audio channels. If not specified, the input channel layout wil
 
 Copy original, non-normalized audio streams to output file
 
+### `--keep-bit-depth`, `--no-keep-bit-depth`
+
+Carry the detected input bit depth through to the output encoder. This is enabled by default.
+
+When you specify a non-PCM encoder (e.g. `-c:a flac`), ffmpeg would otherwise pick its own default sample format, which can promote 16-bit audio to 24-bit. With bit-depth preservation, the matching output sample format is set for you, so you no longer need to pass it via `-e`/`--extra-output-options` (e.g. `-e "-sample_fmt s16"`). Use `--no-keep-bit-depth` to let the encoder choose its own sample format instead.
+
+The chosen sample format is constrained to what the encoder actually supports. Note that ffmpeg has no 24-bit sample format, so 24-bit audio is carried in the 32-bit `s32` format (and the encoder stores it accordingly). Floating-point sources are left to the encoder, and for lossy encoders that only support floating-point formats (e.g. AAC) this has no effect.
+
+Example: `ffmpeg-normalize input.flac -nt peak -t 0 -c:a flac -o output.flac`
+
 ## Audio Stream Selection
 
 ### `-as AUDIO_STREAMS, --audio-streams AUDIO_STREAMS`