lattifai 1.2.0__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,86 +123,46 @@ 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":
-                    # raise NotImplementedError("Transcription-based alignment is not yet implemented.")
-                    assert (
-                        "gemini" not in self.transcriber.name.lower()
-                    ), "Transcription-based alignment is not supported with Gemini transcriber."
-                    assert (
-                        caption.supervisions
-                    ), "Input caption should contain supervisions when using transcription-based alignment."
+                    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:
-                        import asyncio
-
-                        safe_print(colorful.cyan("📝 Transcribing media for alignment..."))
-                        if output_caption_path:
-                            transcript_file = (
-                                Path(str(output_caption_path)).parent
-                                / f"{Path(str(media_audio)).stem}_{self.transcriber.file_name}"
-                            )
-                            if transcript_file.exists():
-                                # print(colorful.cyan(f"Reading existing transcription from {transcript_file}"))
-                                transcript = self._read_caption(transcript_file, verbose=False)
-                                caption.transcription = transcript.supervisions
-                                caption.audio_events = transcript.audio_events
-
-                        if not caption.transcription:
-                            transcript = asyncio.run(
-                                self.transcriber.transcribe(media_audio, language=self.caption_config.source_lang)
-                            )
-                            caption.transcription = transcript.transcription
-                            caption.audio_events = transcript.audio_events
-
-                    # Align caption.supervisions with transcription to get segments
-                    import regex
-                    from error_align import ErrorAlign, 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,
-                            )
+                        transcript = self._transcribe(
+                            media_audio,
+                            source_lang=self.caption_config.source_lang,
+                            is_async=False,
+                            output_dir=Path(str(output_caption_path)).parent if output_caption_path else None,
                         )
+                        caption.transcription = transcript.supervisions or transcript.transcription
+                        caption.audio_events = transcript.audio_events
+                    if not caption.transcription:
+                        raise ValueError("Transcription is empty after transcription step.")
 
-                    alignments = error_align(
-                        f"{JOIN_TOKEN}".join(sup.text for sup in caption.supervisions),
-                        f"{JOIN_TOKEN}".join(sup.text for sup in caption.transcription),
-                        tokenizer=custom_tokenizer,
-                    )
-
-                    for align in alignments:
-                        if align.hyp == JOIN_TOKEN and align.op_type == OpType.MATCH:
-                            pass
+                    if split_sentence or self.caption_config.split_sentence:
+                        caption.supervisions = self.aligner.tokenizer.split_sentences(caption.supervisions)
 
-                        # if align.op_type == OpType.MATCH:
-                        #     continue
-                        # elif align.op_type in (OpType.INSERT, OpType.DELETE, OpType.SUBSTITUTE):
-                        #     # print(colorful.yellow(f"⚠️ Alignment warning: {op}"))
-                        #     pass
+                    matches = align_supervisions_and_transcription(
+                        caption, max_duration=media_audio.duration, verbose=True
+                    )
 
-                    raise NotImplementedError("Transcription-based segmentation is not yet implemented.")
+                    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:
@@ -220,9 +180,10 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
                         )
 
                 # align each segment
+                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"
                         )
@@ -234,18 +195,15 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
 
                     offset = round(start, 4)
                     # Extract audio slice
-                    audio_slice_ndarray = media_audio.ndarray[
-                        :, int(start * media_audio.sampling_rate) : int(end * media_audio.sampling_rate)
-                    ]
-                    emission = self.aligner.emission(audio_slice_ndarray)
+                    audio_slice = media_audio.ndarray[:, int(start * sr) : int(end * sr)]
+                    emission = self.aligner.emission(audio_slice)
 
                     # Align segment
                     _supervisions, _alignments = self.aligner.alignment(
                         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,
@@ -253,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
@@ -358,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)
@@ -366,9 +328,11 @@ 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)
+        media_audio = self.audio_loader(
+            media_file, channel_selector=channel_selector, streaming_chunk_secs=streaming_chunk_secs
+        )
 
         # Step 2: Get or create captions (download or transcribe)
         caption = self._download_or_transcribe_caption(
@@ -393,7 +357,7 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
             output_caption_path=output_caption_path,
             split_sentence=split_sentence,
             channel_selector=channel_selector,
-            streaming_chunk_secs=streaming_chunk_secs,
+            streaming_chunk_secs=None,
         )
 
         return caption

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

@@ -28,11 +28,11 @@ class AlignmentConfig:
     """Computation device: 'cpu' for CPU, 'cuda' for NVIDIA GPU, 'mps' for Apple Silicon."""
 
     batch_size: int = 1
-    """Batch size for inference (number of samples processed simultaneously)."""
+    """Batch size for inference (number of samples processed simultaneously, NotImplemented yet)."""
 
     # Segmented Alignment for Long Audio
     trust_caption_timestamps: bool = False
-    """When True, use original caption timestamps as strong reference constraints during alignment.
+    """When True, use original caption.supervisions' timestamps as strong reference constraints during alignment.
     The alignment process will still adjust timestamps but stay close to the input timing.
     Use this when you want to re-segment caption sentence boundaries (caption.split_sentence=True)
     while preserving the approximate timing from the original captions.
@@ -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()