feat: keep a concealed copy of damaged sources when asked (0.6.2) (#44)

## Problem

On the real library, 0.6.1's strict decode refuses 9 FLACs that have no clean copy on Soulseek today: Beatsteaks - Hail To The Freaks, Diana Ross & The Supremes - Baby Love, Die Toten Hosen - Tage wie diese and - Wannsee, Julieta Venegas - Limón y sal, Radiohead - High and Dry, Scott McKenzie - San Francisco, Simple Plan Feat. Sean Paul - Summer Paradise, and Steve Harley & Cockney Rebel - Make Me Smile. Refusing them means the phone has no copy of those songs at all. That is worse than the one-frame glitch the old release let through.

## Changes

- **The setting.** `corrupt_source: skip | encode_anyway`, either under `settings` (for every output) or on one output (overrides the global value). The default is `skip`, which is exactly the 0.6.1 behaviour.
- **What `encode_anyway` does.** The strict run fails and logs the same ERROR lines as today. Then one more encode runs without `-xerror` and `-err_detect crccheck+explode`, so ffmpeg conceals the damaged frames. If it works, the copy exists, one WARNING line says it was made from a damaged source, and its manifest row gets kind `tolerant`. A source that fails even that run stays refused. Timeouts and other non-decode failures get no tolerant run.
- **Failure memory.** The source is still remembered as failed, so the strict attempt is not repeated on every scan.
- **Clean replacement (from the CodeRabbit review).** A clean replacement has a new size or modification time. That clears the failure memory, and a plain scan now rebuilds the tolerant copy with the strict encode. Only `tolerant` rows are rebuilt this way.
- **How the caller tells failures apart.** `atomic_ffmpeg_encode` now returns `DECODE_ERROR_RC` for any failure that printed a decode error, so it can be told from a timeout or a disk error. It takes `strict=False` for the tolerant run, where only the exit code counts.
- **Release files.** Version 0.6.2, CHANGELOG entry, and docs for the setting in `docs/configuration.md` (a "Damaged sources" section), `docs/how-it-works.md` and `config.example.yaml`.

## Testing

- CI ran in `python:3.14-slim` with FFmpeg 7.1.5: 435 passed, 0 skipped, 97% coverage. Codecov patch is 96.15% and project 96.32%.
- **Both modes:**
  - `skip` runs one strict encode, writes no output, and remembers the source.
  - `encode_anyway`, set globally or per output, runs one strict encode and exactly one tolerant encode. The tolerant command has no strict flags. The copy is written with manifest kind `tolerant`, the ERROR is still logged, and exactly one WARNING appears. The source is remembered, and the next scan makes no encode at all.
  - A source that also fails the tolerant run stays refused, with no WARNING. A timeout gets no tolerant run.
- **Real file:** a FLAC with 400 flipped bytes, on the local ffmpeg 9 and on 7.1 in CI, gets a tolerant AAC and is remembered as failed.
- **Red controls:** every new test failed against a deliberate break, 21 mutations in all, run with bytecode caching off.
- **Ruff:** `ruff format --check` is clean. `ruff check` still reports the 23 known `BLE001`/`S110` findings and nothing new.

Author: GeiserX

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
 
+## [0.6.2] - 2026-10-05
+
+### Added
+
+- `corrupt_source: skip | encode_anyway`, under `settings` or on one output (default `skip`, the 0.6.1 behaviour). Some damaged FLACs have no clean copy to replace them, and refusing them leaves the phone with no copy of the song at all. With `encode_anyway`, a source that fails the strict decode still gets the same ERROR line, then one more encode without `-xerror` and `-err_detect`, so FFmpeg conceals the damaged frames. That copy is logged with one WARNING saying it was made from a damaged source, and its manifest row has kind `tolerant`. The source is still remembered as failed, so the strict attempt is not repeated on every scan, and a source that fails even the tolerant encode stays refused. When the damaged file is later replaced by a clean one (a different size or modification time), the next scan rebuilds the tolerant copy with the strict encode.
+
 ## [0.6.1] - 2026-10-04
 
 ### Added
@@ -53,5 +59,6 @@ All notable changes to this project are documented here. The format follows [Kee
 - Lossy copies are written through a temp file and renamed, like encodes, so a half-written copy is never visible.
 - `force_reencode: true` purges the outputs once at startup. It used to purge them again on every periodic sync, which re-encoded the whole library every five minutes.
 
+[0.6.2]: https://github.com/GeiserX/audio-transcode-watcher/releases/tag/v0.6.2
 [0.6.1]: https://github.com/GeiserX/audio-transcode-watcher/releases/tag/v0.6.1
 [0.6.0]: https://github.com/GeiserX/audio-transcode-watcher/releases/tag/v0.6.0

README.md

@@ -35,7 +35,7 @@ Keep one library in several formats: lossless for the archive, lossy for phones
 curl -fsSL -o config.yaml https://raw.githubusercontent.com/GeiserX/audio-transcode-watcher/main/config.example.yaml
 docker run -d --name audio_transcoder -e CONFIG_FILE=/app/config.yaml \
   -v ./config.yaml:/app/config.yaml:ro -v /path/to/flac:/music/flac:ro -v /path/to/mp3:/music/mp3 \
-  drumsergio/audio-transcoder:0.6.1
+  drumsergio/audio-transcoder:0.6.2
 ```
 
 Edit `config.yaml` first so its outputs match the folders you mount; the example writes ALAC, MP3 and AAC. [Getting started](https://github.com/GeiserX/audio-transcode-watcher/blob/main/docs/getting-started.md) has Docker Compose and the full `docker run`.

config.example.yaml

@@ -1,4 +1,4 @@
-# Audio Transcode Watcher Configuration (0.6.1)
+# Audio Transcode Watcher Configuration (0.6.2)
 # ======================================
 #
 # This configuration file defines the source folder and output destinations
@@ -62,6 +62,13 @@ settings:
   # Seconds between periodic full syncs (default: 300)
   sync_interval_seconds: 300
 
+  # A source that does not decode cleanly (a damaged FLAC):
+  #   skip           write nothing for it (default)
+  #   encode_anyway  log the error, then encode it with FFmpeg's error
+  #                  concealment, so a one-frame glitch is better than no copy
+  # An output can set its own corrupt_source to override this.
+  corrupt_source: skip
+
   # whisper_fallback and whisper_model were removed in 0.6.0 and are ignored
 
 

docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-Current version: **0.6.1**
+Current version: **0.6.2**
 
 ## Completed
 
@@ -13,6 +13,7 @@ Current version: **0.6.1**
 - **Recursive directory support** -- mirror source folder hierarchy in outputs (v0.5.0)
 - **Lossy sources copied, not inflated**, corrupt sources fail loudly, ReplayGain and MusicBrainz tags kept in M4A outputs, configurable periodic sync (v0.6.0)
 - **Portable AAC**: stereo downmix and a 48 kHz cap for AAC outputs, per-output `channels` and `max_sample_rate` (v0.6.1)
+- **Damaged sources**: `corrupt_source: encode_anyway` makes a concealed copy instead of none (v0.6.2)
 
 ## v0.7.0 -- Quality of Life
 

docs/configuration.md

@@ -60,8 +60,30 @@ settings:
 
   # Seconds between periodic full syncs (default: 300)
   sync_interval_seconds: 300
+
+  # What to do with a source that does not decode cleanly: skip | encode_anyway
+  # (default: skip). An output can set its own corrupt_source.
+  corrupt_source: skip
+```
+
+### Damaged sources
+
+A source that fails the strict decode (see [Corrupt sources](how-it-works.md#corrupt-sources)) is handled by `corrupt_source`:
+
+- `skip` (the default) writes nothing for it.
+- `encode_anyway` logs the same ERROR, then encodes it once more without `-xerror` and `-err_detect`, letting FFmpeg conceal the damaged frames. The copy exists, one WARNING line says it was made from a damaged source, and its manifest row has kind `tolerant`. A source that fails even that run stays refused.
+
+Set it under `settings` for every output, or on one output to override, for example only on the AAC output that a phone plays from:
+
+```yaml
+  - name: aac-256
+    codec: aac
+    path: /music/aac
+    corrupt_source: encode_anyway
 ```
 
+Either way the source is remembered as failed, so the strict attempt is not repeated on every scan. Replacing the file with a clean copy (a new size or modification time) clears that, and the next scan rebuilds the tolerant copy with the strict encode.
+
 `whisper_fallback` and `whisper_model` were removed in 0.6.0 along with the Whisper lyrics fallback. A config that still sets them loads, and the first load logs one warning that they are ignored.
 
 ## Source formats

docs/getting-started.md

@@ -29,7 +29,7 @@ outputs:
 ```yaml
 services:
   audio-transcoder:
-    image: drumsergio/audio-transcoder:0.6.1
+    image: drumsergio/audio-transcoder:0.6.2
     container_name: audio_transcoder
     environment:
       - TZ=Europe/Madrid
@@ -60,6 +60,6 @@ docker run -d \
   -v /path/to/flac:/music/flac:ro \
   -v /path/to/mp3:/music/mp3 \
   --restart unless-stopped \
-  drumsergio/audio-transcoder:0.6.1
+  drumsergio/audio-transcoder:0.6.2
 ```
 

docs/how-it-works.md

@@ -17,7 +17,7 @@ Each output folder holds `.atw-manifest.json`, a map from each output file to th
 
 ## Corrupt sources
 
-FFmpeg runs with `-xerror` and `-err_detect crccheck+explode`, so a frame whose checksum does not match stops the encode. If a source does not decode cleanly, the encode fails even when FFmpeg exits 0 but printed a decode error. The error is logged with the file name and no output is written. The file is not tried again until its modification time changes, or the service restarts.
+FFmpeg runs with `-xerror` and `-err_detect crccheck+explode`, so a frame whose checksum does not match stops the encode. If a source does not decode cleanly, the encode fails even when FFmpeg exits 0 but printed a decode error. The error is logged with the file name and no output is written, unless `corrupt_source: encode_anyway` is set; then the file is encoded once more with FFmpeg's error concealment and marked `tolerant` in the manifest (see [Damaged sources](configuration.md#damaged-sources)). The strict attempt is not repeated until the file's modification time changes, or the service restarts.
 
 ## Recursive Directory Support
 

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "audio-transcode-watcher"
 
-version = "0.6.1"
+version = "0.6.2"
 
 description = "Watch a source folder and automatically transcode audio files to multiple formats"
 readme = "README.md"

src/audio_transcode_watcher/__init__.py

@@ -1,3 +1,3 @@
 """Audio Transcode Watcher - Automatic audio file transcoding."""
 
-__version__ = "0.6.1"
+__version__ = "0.6.2"

src/audio_transcode_watcher/config.py

@@ -45,10 +45,19 @@
 # Portable-playback limits applied when an output does not set them.
 # AAC goes to phones, AirPods and CarPlay: stereo, at most 48 kHz.
 # Any codec can opt in by setting channels / max_sample_rate; 0 = no limit.
+# What to do with a source that does not decode cleanly: "skip" writes
+# nothing; "encode_anyway" retries with ffmpeg's error concealment.
+CORRUPT_SOURCE_MODES = ("skip", "encode_anyway")
+
 DEFAULT_CHANNELS = {"aac": 2}
 DEFAULT_MAX_SAMPLE_RATE = {"aac": 48000}
 
 
+def _check_corrupt_source(value: Any, label: str) -> None:
+    if value not in CORRUPT_SOURCE_MODES:
+        raise ValueError(f"{label} must be one of {', '.join(CORRUPT_SOURCE_MODES)}")
+
+
 @dataclass
 class OutputConfig:
     """Configuration for a single output destination."""
@@ -60,6 +69,7 @@ class OutputConfig:
     include_artwork: bool = True
     channels: int | None = None  # Downmix above this many channels; 0 = keep
     max_sample_rate: int | None = None  # Resample above this rate (Hz); 0 = keep
+    corrupt_source: str | None = None  # "skip" | "encode_anyway"; None = global
 
     def __post_init__(self) -> None:
         """Validate and set defaults after initialization."""
@@ -83,6 +93,10 @@ def __post_init__(self) -> None:
             self.channels = DEFAULT_CHANNELS.get(self.codec, 0)
         if self.max_sample_rate is None:
             self.max_sample_rate = DEFAULT_MAX_SAMPLE_RATE.get(self.codec, 0)
+        if self.corrupt_source is not None:
+            _check_corrupt_source(
+                self.corrupt_source, f"Output '{self.name}': corrupt_source"
+            )
         for key in ("channels", "max_sample_rate"):
             value = getattr(self, key)
             if isinstance(value, bool) or not isinstance(value, int) or value < 0:
@@ -111,6 +125,7 @@ def from_dict(cls, data: dict[str, Any]) -> OutputConfig:
             include_artwork=data.get("include_artwork", True),
             channels=data.get("channels"),
             max_sample_rate=data.get("max_sample_rate"),
+            corrupt_source=data.get("corrupt_source"),
         )
 
 
@@ -127,12 +142,15 @@ class Config:
     min_stable_seconds: float = 1.0
     fetch_lyrics: bool = True  # Auto-fetch .lrc lyrics via syncedlyrics
     sync_interval_seconds: int = 300  # Seconds between periodic full syncs
+    corrupt_source: str = "skip"  # Default for outputs that don't set it
 
     def __post_init__(self) -> None:
         """Validate configuration after initialization."""
         if not self.source_path:
             raise ValueError("source_path is required")
 
+        _check_corrupt_source(self.corrupt_source, "settings.corrupt_source")
+
         interval = self.sync_interval_seconds
         if (
             isinstance(interval, bool)
@@ -159,6 +177,10 @@ def output_paths(self) -> list[str]:
         """Get list of all output directory paths."""
         return [o.path for o in self.outputs]
 
+    def corrupt_source_for(self, output: OutputConfig) -> str:
+        """The corrupt_source mode for *output*: its own, else the global one."""
+        return output.corrupt_source or self.corrupt_source
+
     def get_output_by_name(self, name: str) -> OutputConfig | None:
         """Get an output configuration by name."""
         for output in self.outputs:
@@ -183,6 +205,7 @@ def from_dict(cls, data: dict[str, Any]) -> Config:
             min_stable_seconds=settings.get("min_stable_seconds", 1.0),
             fetch_lyrics=settings.get("fetch_lyrics", True),
             sync_interval_seconds=settings.get("sync_interval_seconds", 300),
+            corrupt_source=settings.get("corrupt_source", "skip"),
         )
 
     @classmethod