audio-transcode-watcher 0.6.0__tar.gz → 0.6.2__tar.gz

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/.beads/config.yaml

@@ -65,7 +65,7 @@
 # - linear.api_key  → use LINEAR_API_KEY env var instead
 # - github.token    → use GITHUB_TOKEN env var instead
 
-# Public repo: the tracker syncs only to this private Gitea repo, never to GitHub.
-sync.remote: "git+ssh://git@gitea.geiser.cloud:2222/giteaer/audio-transcode-watcher-beads.git"
+# Public repo: the tracker syncs only to this private remote, never to GitHub.
+sync.remote: "git+ssh://git@beads-tracker/giteaer/audio-transcode-watcher-beads.git"
 # Every bd write is a Dolt commit, so a push always carries it.
 dolt.auto-commit: "on"

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/AGENTS.md

@@ -104,4 +104,4 @@ This protocol applies when ending a Beads implementation workflow. It is subordi
 
 ## Where the tracker syncs
 
-This repo is public, so its tracker syncs only to the private Dolt remote named by `sync.remote` in `.beads/config.yaml` (`giteaer/audio-transcode-watcher-beads` on Gitea). The block above says sync uses "your git remote". Here that never means this GitHub repo. Don't add it as a Dolt remote and don't push `refs/dolt/*` to it.
+This repo is public, so its tracker syncs only to the private remote named by `sync.remote` in `.beads/config.yaml`. The block above says sync uses "your git remote". Here that never means this GitHub repo. Don't add it as a Dolt remote and don't push `refs/dolt/*` to it.

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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
+
+- Per-output `channels` and `max_sample_rate`. An `aac` output now defaults to `channels: 2` and `max_sample_rate: 48000`, so the AAC copies play everywhere a phone, AirPods or CarPlay can take them: anything with more than two channels is downmixed to stereo, 88.2 and 176.4 kHz sources become 44.1 kHz, and 96 and 192 kHz sources become 48 kHz. Nothing is ever upsampled or upmixed. A lossy AAC source that exceeds the limits is transcoded rather than copied. Other codecs have no limit unless they set one, and `0` turns a limit off. ALAC is unchanged.
+
+### Fixed
+
+- A lossless file that arrives after a lossy one of the same name now replaces the lossy file's transcode too, not only its copy. An Ogg transcoded into an MP3 output as `X.mp3` used to block the later `X.flac` from ever being encoded there. Each output folder now keeps `.atw-manifest.json`, recording which source made each file and how (encode, copy or transcode). A row is trusted only while the output still has the size and modification time it was written with. A missing or unreadable manifest means "unknown", which behaves exactly as before, and the orphan pass drops rows whose file is gone.
+
+### Upgrading
+
+- Existing AAC files are not rebuilt by the upgrade. They are re-encoded only when their source changes, or with `force_reencode: true` on startup. To rebuild just the hi-res and multichannel ones, delete the AAC files above 48 kHz or 2 channels and the next periodic sync encodes them again: `docker exec audio_transcoder find /music/aac -name '*.m4a' -exec sh -c 'ffprobe -v error -select_streams a:0 -show_entries stream=sample_rate,channels -of default=nw=1 "$1" | awk -F= "/^sample_rate/{r=\$2} /^channels/{c=\$2} END{exit !(r>48000||c>2)}" && rm -v "$1"' _ {} \;`
+
+### Security
+
+- `urllib3` is now required at 2.8.0 or newer, for GHSA-vxq7-64xx-v4gw, GHSA-8988-9cw3-xx77 and GHSA-gh4c-6fx4-qh6g. It comes in through syncedlyrics and requests; the image installs from `pyproject.toml`, so the floor is declared there and `uv.lock` resolves 2.8.0.
+
 ## [0.6.0] - 2026-10-04
 
 ### Changed
@@ -35,4 +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

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/CLAUDE.md

@@ -100,4 +100,4 @@ This protocol applies when ending a Beads implementation workflow. It is subordi
 
 ## Where the tracker syncs
 
-This repo is public, so its tracker syncs only to the private Dolt remote named by `sync.remote` in `.beads/config.yaml` (`giteaer/audio-transcode-watcher-beads` on Gitea). The block above says sync uses "your git remote". Here that never means this GitHub repo. Don't add it as a Dolt remote and don't push `refs/dolt/*` to it.
+This repo is public, so its tracker syncs only to the private remote named by `sync.remote` in `.beads/config.yaml`. The block above says sync uses "your git remote". Here that never means this GitHub repo. Don't add it as a Dolt remote and don't push `refs/dolt/*` to it.

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: audio-transcode-watcher
-Version: 0.6.0
+Version: 0.6.2
 Summary: Watch a source folder and automatically transcode audio files to multiple formats
 Project-URL: Homepage, https://github.com/GeiserX/audio-transcode-watcher
 Project-URL: Repository, https://github.com/GeiserX/audio-transcode-watcher
@@ -21,6 +21,7 @@ Requires-Python: >=3.14
 Requires-Dist: mutagen>=1.47.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: syncedlyrics>=1.0.0
+Requires-Dist: urllib3>=2.8.0
 Requires-Dist: watchdog>=4.0.0
 Provides-Extra: dev
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
@@ -65,7 +66,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.0
+  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`.

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/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.0
+  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`.

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/config.example.yaml

@@ -1,4 +1,4 @@
-# Audio Transcode Watcher Configuration (0.6.0)
+# Audio Transcode Watcher Configuration (0.6.2)
 # ======================================
 #
 # This configuration file defines the source folder and output destinations
@@ -28,12 +28,18 @@ outputs:
     path: /music/mp3
     include_artwork: true
   
-  # AAC 256kbps for modern devices
+  # AAC 256kbps for phones, AirPods and CarPlay
   - name: aac-256
     codec: aac
     bitrate: 256k
     path: /music/aac
     include_artwork: true
+    # Portable limits. These are the AAC defaults, shown for reference:
+    # more than 2 channels are downmixed to stereo, and rates above 48 kHz
+    # drop to 44.1 kHz (88.2/176.4 kHz sources) or 48 kHz (96/192 kHz).
+    # Lower rates are never upsampled. Any codec can opt in; 0 = no limit.
+    channels: 2
+    max_sample_rate: 48000
 
 # Optional settings
 settings:
@@ -56,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
 
 

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-Current version: **0.6.0**
+Current version: **0.6.2**
 
 ## Completed
 
@@ -12,6 +12,8 @@ Current version: **0.6.0**
 - **Whisper local transcription fallback** for lyrics (v0.4.0, removed in v0.6.0)
 - **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
 

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/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
@@ -75,7 +97,30 @@ A lossless source is encoded to every output.
 
 A lossy source is never encoded into a lossless output, because that only makes a big file that looks lossless. It is copied there unchanged, with its own extension, so an ALAC folder can hold `.m4a` encodes next to `.mp3` or `.ogg` copies. Into a lossy output it is copied unchanged when it already has that output's codec (`.mp3` into `mp3`, `.m4a` or `.aac` into `aac`, `.opus` into `opus`) and transcoded otherwise. Copies keep their tags and cover as they are.
 
-When a lossless and a lossy file share a name in the source folder, the lossless one is used for every output. If the lossy file came first and was already copied, the copy is removed and the lossless file is encoded as soon as it is processed.
+When a lossless and a lossy file share a name in the source folder, the lossless one is used for every output. If the lossy file came first and was already copied or transcoded, that file is replaced by an encode of the lossless one as soon as it is processed. To tell those files apart, each output folder keeps a hidden `.atw-manifest.json` recording which source made each file and whether it was an encode, a copy or a transcode. Deleting it is safe: files it does not know about are treated as they were before 0.6.1.
+
+## Portable limits (channels and sample rate)
+
+Each output can cap the channel count and the sample rate:
+
+```yaml
+  - name: aac-256
+    codec: aac
+    bitrate: 256k
+    path: /music/aac
+    channels: 2              # downmix anything with more channels to stereo
+    max_sample_rate: 48000   # resample anything above 48 kHz
+```
+
+`aac` outputs get `channels: 2` and `max_sample_rate: 48000` when they don't set them, because they are for phones, AirPods and CarPlay. Every other codec has no limit unless you set one, and `0` turns a limit off (also for `aac`).
+
+The sample rate never goes up, and a rate above the cap drops within its own family: 88.2 and 176.4 kHz become 44.1 kHz, 96 and 192 kHz become 48 kHz. A rate from neither family goes to the cap. A mono or stereo source is never upmixed. A lossy source that would normally be copied into the output (an `.m4a` into `aac`) is transcoded instead when it exceeds a limit. ALAC and the other lossless outputs keep the source's rate and channels.
+
+Changing these settings does not rebuild files that already exist. They are re-encoded when their source changes, or on startup with `force_reencode: true`. To rebuild only the files above the limits, delete them and let the next periodic sync encode them again:
+
+```bash
+docker exec audio_transcoder find /music/aac -name '*.m4a' -exec sh -c 'ffprobe -v error -select_streams a:0 -show_entries stream=sample_rate,channels -of default=nw=1 "$1" | awk -F= "/^sample_rate/{r=\$2} /^channels/{c=\$2} END{exit !(r>48000||c>2)}" && rm -v "$1"' _ {} \;
+```
 
 ## Tags in ALAC and AAC outputs
 

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/docs/getting-started.md

@@ -29,7 +29,7 @@ outputs:
 ```yaml
 services:
   audio-transcoder:
-    image: drumsergio/audio-transcoder:0.6.0
+    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.0
+  drumsergio/audio-transcoder:0.6.2
 ```
 

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/docs/how-it-works.md

@@ -11,9 +11,13 @@
 
 Lossy sources are copied rather than encoded where that keeps quality honest; see [Source formats](configuration.md#source-formats).
 
+## Provenance manifest
+
+Each output folder holds `.atw-manifest.json`, a map from each output file to the source that made it (path, size, modification time) and how: `encode`, `copy` or `transcode`. It is written in batches at most every 5 seconds and at the end of each sync. It is only used to replace a file made from a lossy source once a lossless source of the same name appears. A missing or unreadable manifest just means "unknown".
+
 ## 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
 

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "audio-transcode-watcher"
 
-version = "0.6.0"
+version = "0.6.2"
 
 description = "Watch a source folder and automatically transcode audio files to multiple formats"
 readme = "README.md"
@@ -30,6 +30,9 @@ dependencies = [
     "pyyaml>=6.0",
     "mutagen>=1.47.0",
     "syncedlyrics>=1.0.0",
+    # Transitive via syncedlyrics/requests; pinned up for GHSA-vxq7-64xx-v4gw,
+    # GHSA-8988-9cw3-xx77 and GHSA-gh4c-6fx4-qh6g.
+    "urllib3>=2.8.0",
 ]
 
 [project.optional-dependencies]

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/src/audio_transcode_watcher/__init__.py

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

{audio_transcode_watcher-0.6.0 → audio_transcode_watcher-0.6.2}/src/audio_transcode_watcher/config.py

@@ -42,45 +42,78 @@ DEFAULT_BITRATES = {
     "opus": "128k",
 }
 
+# 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."""
-    
+
     name: str
     codec: str
     path: str
     bitrate: str = ""
     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."""
         self.codec = self.codec.lower()
-        
+
         if self.codec not in CODEC_EXTENSIONS:
             raise ValueError(
                 f"Unknown codec '{self.codec}'. "
                 f"Supported: {', '.join(CODEC_EXTENSIONS.keys())}"
             )
-        
+
         # Set default bitrate for lossy codecs
         if not self.bitrate and self.codec in DEFAULT_BITRATES:
             self.bitrate = DEFAULT_BITRATES[self.codec]
-        
+
         # Artwork not supported for some codecs
         if self.include_artwork and self.codec not in ARTWORK_SUPPORTED_CODECS:
             self.include_artwork = False
-    
+
+        if self.channels is 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:
+                raise ValueError(
+                    f"Output '{self.name}': {key} must be a whole number, 0 for no limit"
+                )
+
     @property
     def extension(self) -> str:
         """Get the file extension for this codec."""
         return CODEC_EXTENSIONS[self.codec]
-    
+
     @property
     def is_lossless(self) -> bool:
         """Check if this codec is lossless."""
         return self.codec in {"alac", "flac", "wav"}
-    
+
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> OutputConfig:
         """Create OutputConfig from a dictionary."""
@@ -90,13 +123,16 @@ class OutputConfig:
             path=data["path"],
             bitrate=data.get("bitrate", ""),
             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"),
         )
 
 
 @dataclass
 class Config:
     """Main configuration for audio-transcode-watcher."""
-    
+
     source_path: str
     outputs: list[OutputConfig] = field(default_factory=list)
     force_reencode: bool = False
@@ -106,48 +142,59 @@ 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) or not isinstance(interval, (int, float)) or interval <= 0:
+        if (
+            isinstance(interval, bool)
+            or not isinstance(interval, (int, float))
+            or interval <= 0
+        ):
             raise ValueError("sync_interval_seconds must be a number greater than 0")
-        
+
         if not self.outputs:
             raise ValueError("At least one output is required")
-        
+
         # Check for duplicate output names
         names = [o.name for o in self.outputs]
         if len(names) != len(set(names)):
             raise ValueError("Duplicate output names detected")
-        
+
         # Check for duplicate output paths
         paths = [o.path for o in self.outputs]
         if len(paths) != len(set(paths)):
             raise ValueError("Duplicate output paths detected")
-    
+
     @property
     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:
             if output.name == name:
                 return output
         return None
-    
+
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> Config:
         """Create Config from a dictionary."""
         outputs = [OutputConfig.from_dict(o) for o in data.get("outputs", [])]
         settings = data.get("settings", {})
         _warn_deprecated_settings(settings)
-        
+
         return cls(
             source_path=data.get("source", {}).get("path", ""),
             outputs=outputs,
@@ -158,15 +205,16 @@ class 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
     def from_yaml_file(cls, path: str) -> Config:
         """Load configuration from a YAML file."""
         with open(path, "r", encoding="utf-8") as f:
             data = yaml.safe_load(f)
         return cls.from_dict(data)
-    
+
     @classmethod
     def from_json_string(cls, json_str: str) -> Config:
         """Load configuration from a JSON string."""
@@ -191,11 +239,11 @@ def _warn_deprecated_settings(settings: dict[str, Any]) -> None:
 def load_config() -> Config:
     """
     Load configuration from environment variables.
-    
+
     Configuration is loaded from one of these sources (in priority order):
     1. CONFIG_FILE env var - path to a YAML config file
     2. CONFIG_JSON env var - JSON string with full configuration
-    
+
     Raises:
         ValueError: If no valid configuration is found
     """
@@ -205,12 +253,12 @@ def load_config() -> Config:
         if not Path(config_file).exists():
             raise ValueError(f"CONFIG_FILE not found: {config_file}")
         return Config.from_yaml_file(config_file)
-    
+
     # Try CONFIG_JSON
     config_json = os.getenv("CONFIG_JSON")
     if config_json:
         return Config.from_json_string(config_json)
-    
+
     # No configuration provided
     raise ValueError(
         "No configuration found. Set CONFIG_FILE (path to YAML config) "