feat: add recursive directory support (#11)

* feat: add recursive directory support

Mirror source folder hierarchy (Artist/Album) in all output
directories. Flat source folders continue to work unchanged.

Closes #10

* fix: address CodeRabbit review feedback

- Handle directory move/delete events in watcher (clean mirrored subtrees)
- Guard orphan cleanup when source has no audio files (prevent data loss)
- Log exception in _cleanup_orphans instead of bare except
- Clean empty output subdirectories immediately on file deletion
- NFC-normalize directory paths in verify_sync get_rel_stem
- Add text language tag to README code fence
- Fix unused variable warnings (Ruff B007)

* fix: guard directory deletion against root/outside paths and unblock watcher thread

- Reject rel_dir=="." or ".." prefixes in _handle_directory_delete to prevent
  wiping entire output directories when source root is deleted
- Add safety_guard_active check to directory-level deletions
- Offload directory move reprocessing to a background thread so the watchdog
  dispatcher is not blocked by per-file sleep+encode
- Move os import to module scope, remove unused get_output_file_path import

Author: GeiserX

.github/workflows/dockerhub-description.yml

@@ -0,0 +1,19 @@
+name: Docker Hub Description
+
+on:
+  push:
+    branches: [main]
+    paths: [README.md]
+  workflow_dispatch:
+
+jobs:
+  update-description:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: peter-evans/dockerhub-description@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          repository: drumsergio/audio-transcoder

README.md

@@ -34,6 +34,7 @@ Perfect for maintaining a music library in multiple formats -- lossless for arch
 ## Features
 
 - **Real-time file watching** -- Detects new, modified, renamed, or deleted files via watchdog
+- **Recursive directory support** -- Mirrors source folder hierarchy (Artist/Album) in all outputs
 - **Multiple simultaneous outputs** -- Transcode to any number of formats in a single pass
 - **Six codecs** -- ALAC, AAC, MP3, Opus, FLAC, WAV with configurable bitrates
 - **Synced lyrics** -- Auto-fetches `.lrc` lyrics with Whisper speech-to-text fallback
@@ -75,7 +76,7 @@ outputs:
 ```yaml
 services:
   audio-transcoder:
-    image: drumsergio/audio-transcoder:0.4.1
+    image: drumsergio/audio-transcoder:0.5.0
     container_name: audio_transcoder
     environment:
       - TZ=Europe/Madrid
@@ -106,7 +107,7 @@ docker run -d \
   -v /path/to/flac:/music/flac:ro \
   -v /path/to/mp3:/music/mp3 \
   --restart unless-stopped \
-  drumsergio/audio-transcoder:0.4.1
+  drumsergio/audio-transcoder:0.5.0
 ```
 
 ## Configuration
@@ -198,6 +199,26 @@ environment:
 3. **Orphan cleanup** -- Removes output files that no longer have a matching source.
 4. **Lyrics sync** -- Fetches synced `.lrc` lyrics from online databases; falls back to Whisper transcription when no lyrics are found.
 
+### Recursive Directory Support
+
+Source folder hierarchy is automatically mirrored in all outputs. Both flat and nested structures work out of the box -- no configuration needed.
+
+```text
+Source:                          Output (MP3):
+/music/flac/                     /music/mp3/
+├── Artist A/                    ├── Artist A/
+│   ├── Album 1/                 │   ├── Album 1/
+│   │   ├── 01 - Track.flac     │   │   ├── 01 - Track.mp3
+│   │   └── 02 - Track.flac     │   │   └── 02 - Track.mp3
+│   └── Album 2/                 │   └── Album 2/
+│       └── 01 - Song.flac      │       └── 01 - Song.mp3
+└── Artist B/                    └── Artist B/
+    └── Live Album/                  └── Live Album/
+        └── 01 - Intro.flac             └── 01 - Intro.mp3
+```
+
+When source files or directories are deleted, the corresponding outputs and empty directories are cleaned up automatically.
+
 ### Safety Guards
 
 The service includes multiple guards to prevent data loss:

docs/ROADMAP.md

@@ -1,91 +1,71 @@
 # Roadmap
 
-Future improvements and features for audio-transcode-watcher.
+Current version: **0.5.0**
 
-## v0.2.0 - Quality of Life
+## Completed
+
+- **Parallel encoding** with configurable workers (v0.1.0)
+- **Lossless source priority** over MP3 duplicates (v0.1.1)
+- **Stale temp file cleanup** on startup (v0.1.2)
+- **Synced lyrics sidecar** (.lrc) copying to outputs (v0.2.0)
+- **Auto-fetch synced lyrics** via syncedlyrics providers (v0.3.0)
+- **Whisper local transcription fallback** for lyrics (v0.4.0)
+- **Recursive directory support** -- mirror source folder hierarchy in outputs (v0.5.0)
+
+## v0.6.0 -- Quality of Life
 
 - [ ] **Progress reporting during initial sync**
-  - Show progress bar or percentage during bulk encoding
-  - Estimated time remaining
+  - Show file count progress (e.g. 42/500)
+  - Log estimated time remaining for large libraries
+
+- [ ] **Graceful shutdown**
+  - Complete in-progress encodes before stopping
+  - Resume interrupted syncs on next startup
+
+- [ ] **Dry-run mode**
+  - Preview what would be encoded without doing it
+  - Useful for testing configuration changes
+
+## v0.7.0 -- Observability
 
 - [ ] **Health check endpoint**
   - HTTP endpoint for container health monitoring
   - Prometheus metrics (files processed, errors, queue size)
 
-- [ ] **Graceful shutdown**
-  - Complete in-progress encodes before stopping
-  - Resume interrupted syncs
-
-## v0.3.0 - Advanced Features
+- [ ] **Notifications**
+  - Webhook/Shoutrrr support for encoding events
+  - Error alerts for failed encodes
 
-- [ ] **Folder structure preservation**
-  - Option to mirror source folder hierarchy in outputs
-  - Support for Artist/Album/Track structure
+## v0.8.0 -- Smart Encoding
 
-- [ ] **Quality profiles**
-  - Pre-defined quality presets (high, medium, low)
-  - Per-folder quality overrides
+- [ ] **FFmpeg multi-output (tee muxer)**
+  - Single decode pass, multiple encodes
+  - Significant CPU reduction for multi-output configurations
 
-- [ ] **Smart re-encoding**
-  - Detect source file changes (checksum-based)
-  - Only re-encode when source actually changed, not just touched
+- [ ] **Checksum-based re-encoding**
+  - Detect actual content changes vs. metadata-only touches
+  - Skip re-encode when source content is unchanged
 
 - [ ] **Replay gain support**
   - Calculate and embed replay gain tags
   - Album and track gain modes
 
-## v0.4.0 - Performance & Scalability
-
-- [ ] **FFmpeg multi-output**
-  - Single decode, multiple encodes (FFmpeg tee muxer)
-  - Reduces CPU usage for multiple outputs from same source
-
-- [ ] **Distributed encoding**
-  - Queue-based architecture (Redis/RabbitMQ)
-  - Multiple worker nodes for large libraries
-
-- [ ] **GPU acceleration**
-  - NVENC/VAAPI support for compatible codecs
-  - Hardware-accelerated AAC encoding
-
-## v0.5.0 - User Experience
-
-- [ ] **Web UI dashboard**
-  - Real-time encoding status
-  - Queue management
-  - Configuration editor
-
-- [ ] **Notifications**
-  - Webhook support for encoding events
-  - Discord/Telegram/Email notifications
-  - Error alerts
-
-- [ ] **Dry-run mode**
-  - Preview what would be encoded without doing it
-  - Useful for testing configuration changes
-
 ## Future Ideas (Backlog)
 
 ### Format Support
 - [ ] Ogg Vorbis output codec
-- [ ] WavPack input support
 - [ ] DSD/DSF input support (convert to PCM first)
-- [ ] Multi-channel audio handling (5.1 → stereo downmix option)
+- [ ] Multi-channel audio handling (5.1 to stereo downmix option)
 
 ### Metadata
-- [ ] Lyrics preservation (embedded and .lrc sidecar)
 - [ ] MusicBrainz integration for missing metadata
-- [ ] Custom metadata mapping rules
 - [ ] Chapter markers for audiobooks
 
 ### Integration
 - [ ] Plex/Jellyfin library refresh triggers
 - [ ] Lidarr/Beets integration
-- [ ] S3/MinIO source and destination support
-- [ ] SFTP/SMB remote sources
 
 ### Analysis
-- [ ] Audio quality analysis (clipping detection)
 - [ ] Loudness normalization (EBU R128)
 - [ ] Silence trimming option
 - [ ] Duplicate detection

pyproject.toml

@@ -4,7 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "audio-transcode-watcher"
-version = "0.4.2"
+
+version = "0.5.0"
+
 description = "Watch a source folder and automatically transcode audio files to multiple formats"
 readme = "README.md"
 license = "GPL-3.0-or-later"