audio-transcode-watcher 0.4.2__py3-none-any.whl

audio_transcode_watcher/__init__.py

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

audio_transcode_watcher/config.py

@@ -0,0 +1,190 @@
+"""Configuration loading for audio-transcode-watcher."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+# Codec to file extension mapping
+CODEC_EXTENSIONS = {
+    "alac": ".m4a",
+    "aac": ".m4a",
+    "mp3": ".mp3",
+    "opus": ".opus",
+    "flac": ".flac",
+    "wav": ".wav",
+}
+
+# Codecs that support embedded artwork
+ARTWORK_SUPPORTED_CODECS = {"alac", "aac", "mp3", "flac"}
+
+# Default bitrates for lossy codecs
+DEFAULT_BITRATES = {
+    "aac": "256k",
+    "mp3": "256k",
+    "opus": "128k",
+}
+
+
+@dataclass
+class OutputConfig:
+    """Configuration for a single output destination."""
+    
+    name: str
+    codec: str
+    path: str
+    bitrate: str = ""
+    include_artwork: bool = True
+    
+    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
+    
+    @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."""
+        return cls(
+            name=data["name"],
+            codec=data["codec"],
+            path=data["path"],
+            bitrate=data.get("bitrate", ""),
+            include_artwork=data.get("include_artwork", True),
+        )
+
+
+@dataclass
+class Config:
+    """Main configuration for audio-transcode-watcher."""
+    
+    source_path: str
+    outputs: list[OutputConfig] = field(default_factory=list)
+    force_reencode: bool = False
+    allow_initial_bulk_encode: bool = True  # Allow encoding when outputs are empty
+    parallel_workers: int = 4  # Number of parallel encoding workers
+    stability_timeout: float = 60.0
+    min_stable_seconds: float = 1.0
+    fetch_lyrics: bool = True  # Auto-fetch .lrc lyrics via syncedlyrics
+    whisper_fallback: bool = True  # Use Whisper local transcription as fallback
+    whisper_model: str = "base"  # Whisper model size: tiny, base, small, medium, large
+    
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization."""
+        if not self.source_path:
+            raise ValueError("source_path is required")
+        
+        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 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", {})
+        
+        return cls(
+            source_path=data.get("source", {}).get("path", ""),
+            outputs=outputs,
+            force_reencode=settings.get("force_reencode", False),
+            allow_initial_bulk_encode=settings.get("allow_initial_bulk_encode", True),
+            parallel_workers=settings.get("parallel_workers", 4),
+            stability_timeout=settings.get("stability_timeout", 60.0),
+            min_stable_seconds=settings.get("min_stable_seconds", 1.0),
+            fetch_lyrics=settings.get("fetch_lyrics", True),
+            whisper_fallback=settings.get("whisper_fallback", True),
+            whisper_model=settings.get("whisper_model", "base"),
+        )
+    
+    @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."""
+        data = json.loads(json_str)
+        return cls.from_dict(data)
+
+
+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
+    """
+    # Try CONFIG_FILE first
+    config_file = os.getenv("CONFIG_FILE")
+    if config_file:
+        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) "
+        "or CONFIG_JSON (JSON configuration string)."
+    )

audio_transcode_watcher/encoder.py

@@ -0,0 +1,208 @@
+"""FFmpeg encoding logic for audio-transcode-watcher."""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+
+from .config import OutputConfig
+from .utils import nfc_path
+
+logger = logging.getLogger(__name__)
+
+
+def build_ffmpeg_command(
+    source: str,
+    dest: str,
+    output_config: OutputConfig,
+) -> list[str]:
+    """
+    Build an FFmpeg command for transcoding.
+    
+    Args:
+        source: Path to source audio file
+        dest: Path to destination file
+        output_config: Output configuration
+    
+    Returns:
+        FFmpeg command as list of arguments
+    """
+    source = nfc_path(source)
+    dest = nfc_path(dest)
+    
+    # Common arguments
+    cmd = [
+        "ffmpeg", "-loglevel", "error", "-y",
+        "-i", source,
+        "-map", "0:a:0",  # First audio stream
+    ]
+    
+    # Add video/artwork mapping if enabled
+    if output_config.include_artwork:
+        cmd.extend(["-map", "0:v:0?"])  # First video/image stream (optional)
+    
+    # Copy metadata
+    cmd.extend(["-map_metadata", "0"])
+    
+    # Codec-specific options
+    codec = output_config.codec
+    
+    if codec == "alac":
+        cmd.extend(["-c:a", "alac"])
+        if output_config.include_artwork:
+            cmd.extend(["-c:v", "copy"])
+        # Ensure album_artist is mapped correctly for M4A (aART tag)
+        cmd.extend(["-movflags", "+faststart", "-f", "mp4"])
+    
+    elif codec == "aac":
+        cmd.extend(["-c:a", "aac", "-b:a", output_config.bitrate])
+        if output_config.include_artwork:
+            cmd.extend(["-c:v", "copy"])
+        cmd.extend(["-movflags", "+faststart", "-f", "mp4"])
+    
+    elif codec == "mp3":
+        cmd.extend(["-c:a", "libmp3lame", "-b:a", output_config.bitrate])
+        if output_config.include_artwork:
+            # MP3 needs mjpeg for ID3 APIC artwork
+            cmd.extend(["-c:v", "mjpeg"])
+        cmd.extend(["-id3v2_version", "3", "-write_id3v2", "1", "-f", "mp3"])
+    
+    elif codec == "opus":
+        cmd.extend(["-c:a", "libopus", "-b:a", output_config.bitrate])
+        cmd.extend(["-f", "opus"])
+    
+    elif codec == "flac":
+        cmd.extend(["-c:a", "flac"])
+        if output_config.include_artwork:
+            cmd.extend(["-c:v", "copy"])
+        cmd.extend(["-f", "flac"])
+    
+    elif codec == "wav":
+        cmd.extend(["-c:a", "pcm_s16le", "-f", "wav"])
+    
+    else:
+        raise ValueError(f"Unsupported codec: {codec}")
+    
+    cmd.append(dest)
+    return cmd
+
+
+def _remove_artwork_from_command(cmd: list[str]) -> list[str]:
+    """
+    Remove artwork-related options from an FFmpeg command.
+    
+    Used for retry when artwork encoding fails.
+    """
+    filtered = []
+    i = 0
+    
+    while i < len(cmd):
+        arg = cmd[i]
+        
+        # Skip -map 0:v:0? pair
+        if arg == "-map" and i + 1 < len(cmd) and cmd[i + 1] == "0:v:0?":
+            i += 2
+            continue
+        
+        # Skip -c:v and its value
+        if arg == "-c:v":
+            i += 2
+            continue
+        
+        # Skip -vf and its value
+        if arg.startswith("-vf"):
+            i += 2
+            continue
+        
+        filtered.append(arg)
+        i += 1
+    
+    return filtered
+
+
+def atomic_ffmpeg_encode(
+    cmd: list[str],
+    final_dest: str,
+    retry_without_artwork: bool = True,
+) -> int:
+    """
+    Run FFmpeg with atomic output (write to temp, then rename).
+    
+    Args:
+        cmd: FFmpeg command (last element is destination)
+        final_dest: Final destination path
+        retry_without_artwork: If True, retry without artwork on failure
+    
+    Returns:
+        Return code (0 for success)
+    """
+    final_dest = nfc_path(final_dest)
+    dest_dir = os.path.dirname(final_dest)
+    os.makedirs(dest_dir, exist_ok=True)
+    
+    tmp_dest = final_dest + ".tmp__ff"
+    
+    # Clean up any stale temp file
+    try:
+        if os.path.exists(tmp_dest):
+            os.remove(tmp_dest)
+    except Exception:
+        pass
+    
+    # Replace destination with temp path
+    cmd = list(cmd)
+    cmd[-1] = tmp_dest
+    
+    logger.info("► %s", " ".join(cmd))
+    proc = subprocess.run(cmd, capture_output=True)
+    rc = proc.returncode
+    
+    if rc == 0:
+        try:
+            os.replace(tmp_dest, final_dest)
+            return 0
+        except Exception as e:
+            logger.error("Atomic replace failed for %s: %s", final_dest, e)
+            _cleanup_temp(tmp_dest)
+            return 1
+    
+    # Handle failure
+    logger.error("FFmpeg failed (rc=%s) for %s", rc, final_dest)
+    stderr = proc.stderr.decode("utf-8", errors="ignore") if proc.stderr else ""
+    _cleanup_temp(tmp_dest)
+    
+    # Retry without artwork if error seems artwork-related
+    artwork_error_hints = ["vf#", "vist#", "VipsJpeg", "png", "mjpeg", "decode"]
+    if retry_without_artwork and any(h in stderr.lower() for h in artwork_error_hints):
+        logger.warning("Retrying without cover art for %s", final_dest)
+        
+        filtered_cmd = _remove_artwork_from_command(cmd)
+        filtered_cmd[-1] = tmp_dest
+        
+        logger.info("► (retry) %s", " ".join(filtered_cmd))
+        proc2 = subprocess.run(filtered_cmd, capture_output=True)
+        rc = proc2.returncode
+        
+        if rc == 0:
+            try:
+                os.replace(tmp_dest, final_dest)
+                return 0
+            except Exception as e:
+                logger.error("Atomic replace failed for %s: %s", final_dest, e)
+                _cleanup_temp(tmp_dest)
+                return 1
+        
+        logger.error("FFmpeg retry also failed (rc=%s) for %s", rc, final_dest)
+        _cleanup_temp(tmp_dest)
+    
+    return rc
+
+
+def _cleanup_temp(path: str) -> None:
+    """Clean up a temporary file."""
+    try:
+        if os.path.exists(path):
+            os.remove(path)
+    except Exception:
+        pass

audio_transcode_watcher/lyrics.py

@@ -0,0 +1,193 @@
+"""Automatic lyrics fetching with syncedlyrics and Whisper fallback."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from pathlib import Path
+
+import mutagen
+import syncedlyrics
+
+from .utils import nfc, nfc_path
+
+logger = logging.getLogger(__name__)
+
+# Lazy-loaded Whisper model (heavyweight, only load once when needed)
+_whisper_model = None
+_whisper_load_failed = False
+
+
+def _get_whisper_model(model_name: str = "base"):
+    """Lazy-load and cache the Whisper model."""
+    global _whisper_model, _whisper_load_failed
+    if _whisper_load_failed:
+        return None
+    if _whisper_model is not None:
+        return _whisper_model
+    try:
+        import whisper
+
+        logger.info("Loading Whisper model '%s' (first use, may take a moment)...", model_name)
+        _whisper_model = whisper.load_model(model_name)
+        logger.info("Whisper model '%s' loaded", model_name)
+        return _whisper_model
+    except Exception:
+        logger.warning("Failed to load Whisper model", exc_info=True)
+        _whisper_load_failed = True
+        return None
+
+
+def _segments_to_lrc(segments: list[dict]) -> str:
+    """Convert Whisper transcript segments to LRC format."""
+    lines = []
+    for seg in segments:
+        start = seg.get("start", 0.0)
+        text = seg.get("text", "").strip()
+        if not text:
+            continue
+        mins = int(start // 60)
+        secs = start % 60
+        lines.append(f"[{mins:02d}:{secs:05.2f}] {text}")
+    return "\n".join(lines)
+
+
+def _transcribe_with_whisper(filepath: str, model_name: str = "base") -> str | None:
+    """
+    Transcribe audio to synced lyrics using Whisper.
+
+    Args:
+        filepath: Path to the audio file.
+        model_name: Whisper model size (tiny, base, small, medium, large).
+
+    Returns:
+        LRC-formatted string, or None on failure.
+    """
+    model = _get_whisper_model(model_name)
+    if model is None:
+        return None
+
+    try:
+        logger.info("Transcribing with Whisper: %s", Path(filepath).name)
+        result = model.transcribe(filepath, verbose=False)
+        segments = result.get("segments", [])
+        if not segments:
+            logger.info("Whisper produced no segments for: %s", Path(filepath).name)
+            return None
+        lrc = _segments_to_lrc(segments)
+        logger.info(
+            "Whisper transcribed %d segments for: %s", len(segments), Path(filepath).name
+        )
+        return lrc
+    except Exception:
+        logger.warning("Whisper transcription failed for: %s", filepath, exc_info=True)
+        return None
+
+
+def extract_metadata(filepath: str) -> tuple[str, str] | None:
+    """
+    Extract artist and title from an audio file.
+
+    Tries embedded metadata first (mutagen), then falls back to parsing
+    the filename as "Artist - Title.ext".
+
+    Returns:
+        Tuple of (artist, title) or None if not extractable.
+    """
+    # Try embedded metadata via mutagen
+    try:
+        audio = mutagen.File(filepath, easy=True)
+        if audio and audio.tags:
+            artists = audio.tags.get("artist", [])
+            titles = audio.tags.get("title", [])
+            if artists and titles:
+                artist = artists[0].strip()
+                title = titles[0].strip()
+                if artist and title:
+                    return artist, title
+    except Exception:
+        logger.debug("Could not read metadata from %s", filepath)
+
+    # Fallback: parse filename "Artist - Title.ext"
+    stem = Path(filepath).stem
+    # Strip leading track numbers like "01 - ", "01. ", "1 "
+    stem = re.sub(r"^\d+[\s.\-]+\s*", "", stem).strip()
+    if " - " in stem:
+        artist, title = stem.split(" - ", 1)
+        artist = artist.strip()
+        title = title.strip()
+        if artist and title:
+            return artist, title
+
+    return None
+
+
+def fetch_lyrics_for_file(
+    filepath: str,
+    whisper_fallback: bool = True,
+    whisper_model: str = "base",
+) -> str | None:
+    """
+    Fetch synced lyrics (.lrc) for an audio file if not already present.
+
+    Strategy:
+      1. Check if .lrc sidecar already exists -> skip
+      2. Try syncedlyrics providers (Musixmatch, LRCLIB, NetEase)
+      3. If nothing found and whisper_fallback enabled, transcribe locally
+
+    Args:
+        filepath: Path to the audio file.
+        whisper_fallback: Use Whisper local transcription as fallback.
+        whisper_model: Whisper model size (tiny, base, small, medium, large).
+
+    Returns:
+        Path to the written .lrc file, or None if lyrics were not found
+        or already existed.
+    """
+    filepath = nfc_path(filepath)
+    lrc_path = nfc_path(str(Path(filepath).with_suffix(".lrc")))
+
+    # Already has lyrics
+    if os.path.isfile(lrc_path):
+        return None
+
+    lrc_content: str | None = None
+
+    # Step 1: Try syncedlyrics
+    meta = extract_metadata(filepath)
+    if meta is not None:
+        artist, title = meta
+        query = f"{artist} {title}"
+        try:
+            lrc_content = syncedlyrics.search(query)
+        except Exception:
+            logger.warning("syncedlyrics search failed for: %s", query, exc_info=True)
+
+        if lrc_content:
+            return _write_lrc(lrc_path, lrc_content, f"{artist} - {title}", "syncedlyrics")
+
+        logger.info("No lyrics found via syncedlyrics for: %s - %s", artist, title)
+    else:
+        logger.debug("Cannot extract metadata for lyrics: %s", filepath)
+
+    # Step 2: Whisper fallback
+    if whisper_fallback:
+        lrc_content = _transcribe_with_whisper(filepath, whisper_model)
+        if lrc_content:
+            label = f"{meta[0]} - {meta[1]}" if meta else Path(filepath).stem
+            return _write_lrc(lrc_path, lrc_content, label, "whisper")
+
+    return None
+
+
+def _write_lrc(lrc_path: str, content: str, label: str, source: str) -> str | None:
+    """Write LRC content to disk."""
+    try:
+        with open(lrc_path, "w", encoding="utf-8") as f:
+            f.write(content)
+        logger.info("♫ lyrics saved (%s): %s → %s", source, label, lrc_path)
+        return lrc_path
+    except Exception:
+        logger.error("Failed to write lyrics file: %s", lrc_path, exc_info=True)
+        return None

audio_transcode_watcher/main.py

@@ -0,0 +1,97 @@
+"""Main entry point for audio-transcode-watcher."""
+
+from __future__ import annotations
+
+import gc
+import logging
+import os
+import sys
+import time
+
+from .config import load_config
+from .sync import initial_sync
+from .utils import nfc_path
+from .watcher import start_watcher
+
+
+def setup_logging() -> None:
+    """Configure logging for the application."""
+    # Ensure Unicode output works
+    try:
+        if hasattr(sys.stdout, "reconfigure"):
+            sys.stdout.reconfigure(encoding="utf-8")
+        if hasattr(sys.stderr, "reconfigure"):
+            sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+    
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+def main() -> int:
+    """Main entry point."""
+    setup_logging()
+    logger = logging.getLogger(__name__)
+    
+    # Load configuration
+    try:
+        config = load_config()
+    except ValueError as e:
+        logger.error("Configuration error: %s", e)
+        return 1
+    
+    # Normalize paths
+    config.source_path = nfc_path(config.source_path)
+    for output in config.outputs:
+        output.path = nfc_path(output.path)
+    
+    # Validate source exists
+    if not os.path.isdir(config.source_path):
+        logger.error("Source directory does not exist: %s", config.source_path)
+        return 1
+    
+    # Log configuration
+    logger.info("Source: %s", config.source_path)
+    for output in config.outputs:
+        logger.info(
+            "Output: %s (%s%s) -> %s",
+            output.name,
+            output.codec,
+            f" {output.bitrate}" if output.bitrate else "",
+            output.path,
+        )
+    
+    # Perform initial sync
+    initial_sync(config)
+    
+    # Start watcher
+    observer = start_watcher(config)
+    logger.info("Watching %s …", config.source_path)
+    
+    # Periodic sync interval (check for missing outputs every 5 minutes)
+    sync_interval = 300  # 5 minutes
+    last_sync = time.time()
+    
+    try:
+        while True:
+            time.sleep(10)
+            
+            # Periodic sync to catch deleted outputs
+            if time.time() - last_sync >= sync_interval:
+                logger.info("Periodic sync check…")
+                initial_sync(config)
+                gc.collect()
+                last_sync = time.time()
+    except KeyboardInterrupt:
+        observer.stop()
+    
+    observer.join()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())