lattifai 1.2.1__py3-none-any.whl → 1.2.2__py3-none-any.whl

lattifai/client.py

@@ -7,7 +7,7 @@ import colorful
 from lattifai_core.client import SyncAPIClient
 from lhotse.utils import Pathlike
 
-from lattifai.alignment import Lattice1Aligner, Segmenter
+from lattifai.alignment import Lattice1Aligner, Segmenter, align_supervisions_and_transcription
 from lattifai.audio2 import AudioData, AudioLoader
 from lattifai.caption import Caption, InputCaptionFormat
 from lattifai.config import AlignmentConfig, CaptionConfig, ClientConfig, DiarizationConfig, TranscriptionConfig
@@ -123,9 +123,14 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
             alignment_strategy = self.aligner.config.strategy
 
             if alignment_strategy != "entire" or caption.transcription:
-                safe_print(colorful.cyan(f"🔄 Using segmented alignment strategy: {alignment_strategy}"))
+                safe_print(colorful.cyan(f"🔄   Using segmented alignment strategy: {alignment_strategy}"))
 
                 if caption.supervisions and alignment_strategy == "transcription":
+                    if "gemini" in self.transcriber.name.lower():
+                        raise ValueError(
+                            f"Transcription-based alignment is not supported for {self.transcriber.name} "
+                            "(Gemini's timestamp is not reliable)."
+                        )
                     if not caption.transcription:
                         transcript = self._transcribe(
                             media_audio,
@@ -135,117 +140,29 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
                         )
                         caption.transcription = transcript.supervisions or transcript.transcription
                         caption.audio_events = transcript.audio_events
-                    assert caption.transcription, "Transcription is empty after transcription step."
-
-                    # Align caption.supervisions with transcription to get segments
-                    import regex
-                    from error_align import error_align  # noqa: F401
-                    from error_align.utils import DELIMITERS, NUMERIC_TOKEN, STANDARD_TOKEN, OpType
-
-                    JOIN_TOKEN = "❄"
-                    if JOIN_TOKEN not in DELIMITERS:
-                        DELIMITERS.add(JOIN_TOKEN)
-
-                    def custom_tokenizer(text: str) -> list:
-                        """Default tokenizer that splits text into words based on whitespace.
-
-                        Args:
-                            text (str): The input text to tokenize.
-
-                        Returns:
-                            list: A list of tokens (words).
-
-                        """
-                        # Escape JOIN_TOKEN for use in regex pattern
-                        escaped_join_token = regex.escape(JOIN_TOKEN)
-                        return list(
-                            regex.finditer(
-                                rf"({NUMERIC_TOKEN})|({STANDARD_TOKEN}|{escaped_join_token})",
-                                text,
-                                regex.UNICODE | regex.VERBOSE,
-                            )
-                        )
+                    if not caption.transcription:
+                        raise ValueError("Transcription is empty after transcription step.")
 
                     if split_sentence or self.caption_config.split_sentence:
                         caption.supervisions = self.aligner.tokenizer.split_sentences(caption.supervisions)
 
-                    ref = f"{JOIN_TOKEN}".join(sup.text for sup in caption.supervisions)
-                    hyp = f"{JOIN_TOKEN}".join(sup.text for sup in caption.transcription)
-                    alignments = error_align(ref, hyp, tokenizer=custom_tokenizer)
-
-                    idx = 0
-                    for k, align in enumerate(alignments):
-                        if align.hyp == JOIN_TOKEN and align.op_type == OpType.MATCH:
-                            # safe_print(f"Segment {k}: JOIN_TOKEN detected, creating segment.")
-
-                            # Find first non-None ref_slice starting from idx
-                            ref_start = 0
-                            for i in range(idx, k + 1):
-                                if i < len(alignments) and alignments[i].ref_slice is not None:
-                                    ref_start = alignments[i].ref_slice.start
-                                    break
-
-                            # Find last non-None ref_slice up to current position
-                            ref_stop = len(ref)
-                            for i in range(k, idx - 1, -1):
-                                if i < len(alignments) and alignments[i].ref_slice is not None:
-                                    ref_stop = alignments[i].ref_slice.stop
-                                    break
-
-                            # Find first non-None hyp_slice starting from idx
-                            hyp_start = 0
-                            for i in range(idx, k + 1):
-                                if i < len(alignments) and alignments[i].hyp_slice is not None:
-                                    hyp_start = alignments[i].hyp_slice.start
-                                    break
-
-                            # Find last non-None hyp_slice up to current position
-                            hyp_stop = len(hyp)
-                            for i in range(k, idx - 1, -1):
-                                if i < len(alignments) and alignments[i].hyp_slice is not None:
-                                    hyp_stop = alignments[i].hyp_slice.stop
-                                    break
-
-                            safe_print(f"[REF]: {ref[ref_start:ref_stop]}")
-                            safe_print(f"[HYP]: {hyp[hyp_start:hyp_stop]}\n")
-                            idx = k + 1
-
-                    # last part - handle remaining alignments after last JOIN_TOKEN
-                    if idx < len(alignments):
-                        # Find first non-None ref_slice starting from idx
-                        ref_start = 0
-                        for i in range(idx, len(alignments)):
-                            if alignments[i].ref_slice is not None:
-                                ref_start = alignments[i].ref_slice.start
-                                break
-
-                        # Find last non-None ref_slice from end
-                        ref_stop = len(ref)
-                        for i in range(len(alignments) - 1, idx - 1, -1):
-                            if alignments[i].ref_slice is not None:
-                                ref_stop = alignments[i].ref_slice.stop
-                                break
-
-                        # Find first non-None hyp_slice starting from idx
-                        hyp_start = 0
-                        for i in range(idx, len(alignments)):
-                            if alignments[i].hyp_slice is not None:
-                                hyp_start = alignments[i].hyp_slice.start
-                                break
-
-                        # Find last non-None hyp_slice from end
-                        hyp_stop = len(hyp)
-                        for i in range(len(alignments) - 1, idx - 1, -1):
-                            if alignments[i].hyp_slice is not None:
-                                hyp_stop = alignments[i].hyp_slice.stop
-                                break
-
-                        safe_print(f"[REF]: {ref[ref_start:ref_stop + 1]}")
-                        safe_print(f"[HYP]: {hyp[hyp_start:hyp_stop + 1]}\n")
-
-                    raise NotImplementedError("Transcription-based segmentation is not yet implemented.")
+                    matches = align_supervisions_and_transcription(
+                        caption, max_duration=media_audio.duration, verbose=True
+                    )
+
+                    skipalign = False
+                    matches = sorted(matches, key=lambda x: x[2].WER.WER)  # sort by WER
+                    segments = [(m[3].start[1], m[3].end[1], m, skipalign) for m in matches]
+                    for segment in segments:
+                        # transcription segments -> sentence splitting
+                        segment[2][1] = self.aligner.tokenizer.split_sentences(segment[2][1])
                 else:
                     if caption.transcription:
+                        if "gemini" in self.transcriber.name.lower():
+                            raise ValueError(
+                                f"Transcription-based alignment is not supported for {self.transcriber.name} "
+                                "(Gemini's timestamp is not reliable)."
+                            )
                         if not caption.supervisions:  # youtube + transcription case
                             segments = [(sup.start, sup.end, [sup], not sup.text) for sup in caption.transcription]
                         else:
@@ -266,7 +183,7 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
                 sr = media_audio.sampling_rate
                 supervisions, alignments = [], []
                 for i, (start, end, _supervisions, skipalign) in enumerate(segments, 1):
-                    print(
+                    safe_print(
                         colorful.green(
                             f"  ⏩ aligning segment {i:04d}/{len(segments):04d}: {start:8.2f}s - {end:8.2f}s"
                         )
@@ -286,8 +203,7 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
                         media_audio,
                         _supervisions,
                         split_sentence=split_sentence or self.caption_config.split_sentence,
-                        return_details=self.caption_config.word_level
-                        or (output_caption_path and str(output_caption_path).endswith(".TextGrid")),
+                        return_details=True,
                         emission=emission,
                         offset=offset,
                         verbose=False,
@@ -295,14 +211,16 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
 
                     supervisions.extend(_supervisions)
                     alignments.extend(_alignments)
+
+                # sort by start
+                alignments = sorted(alignments, key=lambda x: x.start)
             else:
                 # Step 2-4: Standard single-pass alignment
                 supervisions, alignments = self.aligner.alignment(
                     media_audio,
                     caption.supervisions,
                     split_sentence=split_sentence or self.caption_config.split_sentence,
-                    return_details=self.caption_config.word_level
-                    or (output_caption_path and str(output_caption_path).endswith(".TextGrid")),
+                    return_details=True,
                 )
 
             # Update caption with aligned results
@@ -400,6 +318,8 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
         use_transcription: bool = False,
         channel_selector: Optional[str | int] = "average",
         streaming_chunk_secs: Optional[float] = None,
+        audio_track_id: Optional[str] = "original",
+        quality: str = "best",
     ) -> Caption:
         # Prepare output directory and media format
         output_dir = self._prepare_youtube_output_dir(output_dir)
@@ -408,7 +328,7 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
         safe_print(colorful.cyan(f"🎬 Starting YouTube workflow for: {url}"))
 
         # Step 1: Download media
-        media_file = self._download_media_sync(url, output_dir, media_format, force_overwrite)
+        media_file = self._download_media_sync(url, output_dir, media_format, force_overwrite, audio_track_id, quality)
 
         media_audio = self.audio_loader(
             media_file, channel_selector=channel_selector, streaming_chunk_secs=streaming_chunk_secs

lattifai/config/__init__.py

@@ -1,7 +1,13 @@
 """Configuration system for LattifAI using nemo_run."""
 
 from .alignment import AlignmentConfig
-from .caption import CaptionConfig
+from .caption import (
+    CaptionConfig,
+    CaptionFonts,
+    CaptionStyle,
+    KaraokeConfig,
+    StandardizationConfig,
+)
 from .client import ClientConfig
 from .diarization import DiarizationConfig
 from .media import AUDIO_FORMATS, MEDIA_FORMATS, VIDEO_FORMATS, MediaConfig
@@ -11,6 +17,10 @@ __all__ = [
     "ClientConfig",
     "AlignmentConfig",
     "CaptionConfig",
+    "CaptionFonts",
+    "CaptionStyle",
+    "KaraokeConfig",
+    "StandardizationConfig",
     "TranscriptionConfig",
     "DiarizationConfig",
     "MediaConfig",

lattifai/config/alignment.py

@@ -93,6 +93,13 @@ class AlignmentConfig:
     Default: 0.20. Typical range: 0.0-0.5.
     """
 
+    boost: float = 5.0
+    """Boost for preferring supervisions over transcription in diff alignment decoding graph.
+    A positive value encourages the decoder to prefer supervision text over ASR transcription.
+    Only effective when strategy='transcription'. Has no effect with 'entire' or 'caption' strategies.
+    Default: 5.0. Typical range: 0.0-10.0.
+    """
+
     client_wrapper: Optional["SyncAPIClient"] = field(default=None, repr=False)
     """Reference to the SyncAPIClient instance. Auto-set during client initialization."""
 

lattifai/config/caption.py

@@ -1,29 +1,249 @@
 """Caption I/O configuration for LattifAI."""
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import TYPE_CHECKING, Literal, Optional
+from typing import TYPE_CHECKING, Dict, Literal, Optional, get_args
 
 from lhotse.utils import Pathlike
 
-# Supported caption formats for reading/writing
-CAPTION_FORMATS = ["srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "md", "ttml", "sami", "smi"]
+# =============================================================================
+# Caption Style Configuration Classes
+# =============================================================================
 
-# Input caption formats (includes special formats like 'auto' and 'gemini')
-INPUT_CAPTION_FORMATS = ["srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "ttml", "sami", "smi", "auto", "gemini"]
 
-# Output caption formats (includes special formats like 'TextGrid' and 'json')
-OUTPUT_CAPTION_FORMATS = ["srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "ttml", "sami", "smi", "TextGrid", "json"]
+class CaptionFonts:
+    """Common caption font constants.
+
+    These are reference constants for popular fonts. You can use any
+    system font name as the font_name parameter in CaptionStyle.
+    """
+
+    # Western fonts
+    ARIAL = "Arial"
+    IMPACT = "Impact"
+    VERDANA = "Verdana"
+    HELVETICA = "Helvetica"
+
+    # Chinese fonts
+    NOTO_SANS_SC = "Noto Sans SC"
+    MICROSOFT_YAHEI = "Microsoft YaHei"
+    PINGFANG_SC = "PingFang SC"
+    SIMHEI = "SimHei"
+
+    # Japanese fonts
+    NOTO_SANS_JP = "Noto Sans JP"
+    MEIRYO = "Meiryo"
+    HIRAGINO_SANS = "Hiragino Sans"
+
+    # Korean fonts
+    NOTO_SANS_KR = "Noto Sans KR"
+    MALGUN_GOTHIC = "Malgun Gothic"
+
+
+@dataclass
+class CaptionStyle:
+    """Caption style configuration for ASS/TTML formats.
+
+    Attributes:
+        primary_color: Main text color (#RRGGBB)
+        secondary_color: Secondary/highlight color (#RRGGBB)
+        outline_color: Text outline color (#RRGGBB)
+        back_color: Shadow color (#RRGGBB)
+        font_name: Font family name (use CaptionFonts constants or any system font)
+        font_size: Font size in points
+        bold: Enable bold text
+        italic: Enable italic text
+        outline_width: Outline thickness
+        shadow_depth: Shadow distance
+        alignment: ASS alignment (1-9, numpad style), 2=bottom-center
+        margin_l: Left margin in pixels
+        margin_r: Right margin in pixels
+        margin_v: Vertical margin in pixels
+    """
+
+    # Colors (#RRGGBB format)
+    primary_color: str = "#FFFFFF"
+    secondary_color: str = "#00FFFF"
+    outline_color: str = "#000000"
+    back_color: str = "#000000"
+
+    # Font
+    font_name: str = CaptionFonts.ARIAL
+    font_size: int = 48
+    bold: bool = False
+    italic: bool = False
+
+    # Border and shadow
+    outline_width: float = 2.0
+    shadow_depth: float = 1.0
+
+    # Position
+    alignment: int = 2
+    margin_l: int = 20
+    margin_r: int = 20
+    margin_v: int = 20
+
+
+@dataclass
+class KaraokeConfig:
+    """Karaoke export configuration.
+
+    Attributes:
+        enabled: Whether karaoke mode is enabled
+        effect: Karaoke effect type
+            - "sweep": Gradual fill from left to right (ASS \\kf tag)
+            - "instant": Instant highlight (ASS \\k tag)
+            - "outline": Outline then fill (ASS \\ko tag)
+        style: Caption style configuration (font, colors, position)
+        lrc_precision: LRC time precision ("centisecond" or "millisecond")
+        lrc_metadata: LRC metadata dict (ar, ti, al, etc.)
+        ttml_timing_mode: TTML timing attribute ("Word" or "Line")
+    """
+
+    enabled: bool = False
+    effect: Literal["sweep", "instant", "outline"] = "sweep"
+    style: CaptionStyle = field(default_factory=CaptionStyle)
+
+    # LRC specific
+    lrc_precision: Literal["centisecond", "millisecond"] = "millisecond"
+    lrc_metadata: Dict[str, str] = field(default_factory=dict)
+
+    # TTML specific
+    ttml_timing_mode: Literal["Word", "Line"] = "Word"
 
-# All caption formats combined (for file detection)
-ALL_CAPTION_FORMATS = list(set(CAPTION_FORMATS + ["TextGrid", "json", "gemini"]))
 
-# Type aliases for better type hints
-InputCaptionFormat = Literal["auto", "srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "ttml", "sami", "smi", "gemini"]
+@dataclass
+class StandardizationConfig:
+    """Caption standardization configuration following broadcast guidelines.
+
+    Reference Standards:
+    - Netflix Timed Text Style Guide
+    - BBC Subtitle Guidelines
+    - EBU-TT-D Standard
+
+    Attributes:
+        min_duration: Minimum segment duration (seconds). Netflix recommends 5/6s, BBC 0.3s
+        max_duration: Maximum segment duration (seconds). Netflix/BBC recommends 7s
+        min_gap: Minimum gap between segments (seconds). 80ms prevents subtitle flicker
+        max_lines: Maximum lines per segment. Broadcast standard is typically 2
+        max_chars_per_line: Maximum characters per line. CJK auto-adjusted by ÷2 (e.g., 42 → 21)
+        optimal_cps: Optimal reading speed (chars/sec). Netflix recommends 17-20 CPS
+        start_margin: Start margin (seconds) before first word. None = no adjustment (default)
+        end_margin: End margin (seconds) after last word. None = no adjustment (default)
+        margin_collision_mode: How to handle collisions: 'trim' (reduce margin) or 'gap' (maintain min_gap)
+    """
+
+    min_duration: float = 0.8
+    max_duration: float = 7.0
+    min_gap: float = 0.08
+    max_lines: int = 2
+    max_chars_per_line: int = 42
+    optimal_cps: float = 17.0
+    start_margin: Optional[float] = None
+    end_margin: Optional[float] = None
+    margin_collision_mode: Literal["trim", "gap"] = "trim"
+
+    def __post_init__(self):
+        """Validate configuration parameters."""
+        if self.min_duration <= 0:
+            raise ValueError("min_duration must be positive")
+        if self.max_duration <= self.min_duration:
+            raise ValueError("max_duration must be greater than min_duration")
+        if self.min_gap < 0:
+            raise ValueError("min_gap cannot be negative")
+        if self.max_lines < 1:
+            raise ValueError("max_lines must be at least 1")
+        if self.max_chars_per_line < 10:
+            raise ValueError("max_chars_per_line must be at least 10")
+        if self.start_margin is not None and self.start_margin < 0:
+            raise ValueError("start_margin cannot be negative")
+        if self.end_margin is not None and self.end_margin < 0:
+            raise ValueError("end_margin cannot be negative")
+        if self.margin_collision_mode not in ("trim", "gap"):
+            raise ValueError("margin_collision_mode must be 'trim' or 'gap'")
+
+
+# =============================================================================
+# Format Type Definitions (Single Source of Truth)
+# =============================================================================
+
+# Type alias for input caption formats (all formats with registered readers)
+InputCaptionFormat = Literal[
+    # Standard subtitle formats
+    "srt",
+    "vtt",  # WebVTT (auto-detects YouTube VTT with word-level timestamps)
+    "ass",
+    "ssa",
+    "sub",
+    "sbv",
+    "txt",
+    "sami",
+    "smi",
+    # Tabular formats
+    "csv",
+    "tsv",
+    "aud",
+    "json",
+    # Specialized formats
+    "textgrid",  # Praat TextGrid
+    "gemini",  # Gemini/YouTube transcript format
+    # Professional NLE formats
+    "avid_ds",
+    "fcpxml",
+    "premiere_xml",
+    "audition_csv",
+    # Special
+    "auto",  # Auto-detect format
+]
+
+# Type alias for output caption formats (all formats with registered writers)
 OutputCaptionFormat = Literal[
-    "srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "ttml", "sami", "smi", "TextGrid", "json"
+    # Standard subtitle formats
+    "srt",
+    "vtt",  # WebVTT (use karaoke_config.enabled=True for YouTube VTT style output)
+    "ass",
+    "ssa",
+    "sub",
+    "sbv",
+    "txt",
+    "sami",
+    "smi",
+    # Tabular formats
+    "csv",
+    "tsv",
+    "aud",
+    "json",
+    # Specialized formats
+    "textgrid",  # Praat TextGrid
+    "gemini",  # Gemini/YouTube transcript format
+    # TTML profiles (write-only)
+    "ttml",  # Generic TTML
+    "imsc1",  # IMSC1 (Netflix/streaming) TTML profile
+    "ebu_tt_d",  # EBU-TT-D (European broadcast) TTML profile
+    # Professional NLE formats
+    "avid_ds",  # Avid Media Composer SubCap format
+    "fcpxml",  # Final Cut Pro XML
+    "premiere_xml",  # Adobe Premiere Pro XML (graphic clips)
+    "audition_csv",  # Adobe Audition markers
+    "edimarker_csv",  # Pro Tools (via EdiMarker) markers
 ]
 
+# =============================================================================
+# Runtime Format Lists (Derived from Type Definitions)
+# =============================================================================
+
+# Input caption formats list (derived from InputCaptionFormat)
+INPUT_CAPTION_FORMATS: list[str] = list(get_args(InputCaptionFormat))
+
+# Output caption formats list (derived from OutputCaptionFormat)
+OUTPUT_CAPTION_FORMATS: list[str] = list(get_args(OutputCaptionFormat))
+
+# Standard caption formats (formats with both reader and writer)
+CAPTION_FORMATS: list[str] = ["srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "sami", "smi"]
+
+# All caption formats combined (for file detection, excludes "auto")
+ALL_CAPTION_FORMATS: list[str] = list(set(INPUT_CAPTION_FORMATS + OUTPUT_CAPTION_FORMATS) - {"auto"})
+
 
 @dataclass
 class CaptionConfig:
@@ -34,13 +254,20 @@ class CaptionConfig:
     """
 
     input_format: InputCaptionFormat = "auto"
-    """Input caption format: 'auto', 'srt', 'vtt', 'ass', 'txt', or 'json'."""
+    """Input caption format. Supports: 'auto' (detect),
+        standard formats (srt, vtt, ass, ssa, sub, sbv, txt, sami, smi),
+        tabular (csv, tsv, aud, json),
+        specialized (textgrid, gemini),
+        NLE (avid_ds, fcpxml, premiere_xml, audition_csv).
+        Note: VTT format auto-detects YouTube VTT with word-level timestamps.
+    """
 
     input_path: Optional[str] = None
     """Path to input caption file."""
 
     output_format: OutputCaptionFormat = "srt"
-    """Output caption format: 'srt', 'vtt', 'ass', 'txt', or 'json'."""
+    """Output caption format. Supports: standard formats, tabular, specialized, TTML profiles (ttml, imsc1, ebu_tt_d),
+    NLE (avid_ds, fcpxml, premiere_xml, audition_csv, edimarker_csv)."""
 
     output_path: Optional[str] = None
     """Path to output caption file."""
@@ -57,12 +284,21 @@ class CaptionConfig:
     word_level: bool = False
     """Include word-level timestamps in alignment results (useful for karaoke, dubbing)."""
 
+    karaoke: Optional[KaraokeConfig] = None
+    """Karaoke configuration when word_level=True (e.g., ASS \\kf tags, enhanced LRC).
+    When None with word_level=True, outputs word-per-segment instead of karaoke styling.
+    When provided, karaoke.enabled controls whether karaoke styling is applied."""
+
     encoding: str = "utf-8"
     """Character encoding for reading/writing caption files (default: utf-8)."""
 
     source_lang: Optional[str] = None
     """Source language code for the caption content (e.g., 'en', 'zh', 'de')."""
 
+    standardization: Optional[StandardizationConfig] = None
+    """Standardization configuration for broadcast-grade captions.
+    When provided, captions will be standardized according to Netflix/BBC guidelines."""
+
     def __post_init__(self):
         """Validate configuration after initialization."""
         self._normalize_paths()
@@ -86,14 +322,17 @@ class CaptionConfig:
         return True
 
     def _normalize_paths(self) -> None:
-        """Normalize and expand input/output paths."""
+        """Normalize and expand input/output paths.
+
+        Uses Path.resolve() to get absolute paths and prevent path traversal issues.
+        """
         # Expand and normalize input path if provided, but don't require it to exist yet
         # (it might be set later after downloading captions)
         if self.input_path is not None:
-            self.input_path = str(Path(self.input_path).expanduser())
+            self.input_path = str(Path(self.input_path).expanduser().resolve())
 
         if self.output_path is not None:
-            self.output_path = str(Path(self.output_path).expanduser())
+            self.output_path = str(Path(self.output_path).expanduser().resolve())
             output_dir = Path(self.output_path).parent
             output_dir.mkdir(parents=True, exist_ok=True)
 
@@ -154,7 +393,7 @@ class CaptionConfig:
         if not self.input_path:
             raise ValueError("input_path is required but not set in CaptionConfig")
 
-        input_file = Path(self.input_path).expanduser()
+        input_file = Path(self.input_path).expanduser().resolve()
         if not input_file.exists():
             raise FileNotFoundError(
                 f"Input caption file does not exist: '{input_file}'. " "Please check the path and try again."
@@ -164,15 +403,20 @@ class CaptionConfig:
                 f"Input caption path is not a file: '{input_file}'. " "Expected a valid caption file path."
             )
 
-    def check_sanity(self) -> bool:
-        """Perform sanity checks on the configuration."""
-        assert self.is_input_path_existed(), "Input caption path must be provided and exist."
+    def check_sanity(self) -> None:
+        """Perform sanity checks on the configuration.
+
+        Raises:
+            ValueError: If input path is not provided or does not exist.
+        """
+        if not self.is_input_path_existed():
+            raise ValueError("Input caption path must be provided and exist.")
 
     def is_input_path_existed(self) -> bool:
         """Check if input caption path is provided and exists."""
         if self.input_path is None:
             return False
 
-        input_file = Path(self.input_path).expanduser()
+        input_file = Path(self.input_path).expanduser().resolve()
         self.input_path = str(input_file)
         return input_file.exists() and input_file.is_file()

lattifai/config/media.py

@@ -91,6 +91,26 @@ class MediaConfig:
     force_overwrite: bool = False
     """Overwrite existing output files without prompting."""
 
+    audio_track_id: Optional[str] = "original"
+    """Audio track ID for multi-language YouTube videos.
+    - "original": Select the original audio track (default)
+    - Language code (e.g., "en", "ja", "fr"): Select by language
+    - Format ID (e.g., "251-drc", "140-0"): Select specific format
+    - None: No filtering, use yt-dlp default selection
+    """
+
+    quality: str = "best"
+    """Media quality for YouTube downloads.
+    For audio:
+    - "best": Highest bitrate (default)
+    - "medium": ~128 kbps
+    - "low": ~50 kbps
+    - Numeric string (e.g., "128"): Target bitrate in kbps
+    For video:
+    - "best": Highest resolution (default)
+    - "1080", "720", "480", "360": Target resolution
+    """
+
     def __post_init__(self) -> None:
         """Validate configuration and normalize paths/formats."""
         self._setup_output_directory()