ytcap 0.1.0__py3-none-any.whl

ytcap/__init__.py

@@ -0,0 +1,5 @@
+"""Top-level package for ytcap."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

ytcap/__main__.py

@@ -0,0 +1,9 @@
+"""Module execution support for ``python -m ytcap``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ytcap/app/__init__.py

@@ -0,0 +1,3 @@
+"""Application use-case layer for ytcap."""
+
+from .process_batch import ProcessBatchOptions, ProcessBatchResult, process_batch

ytcap/app/existing_outputs.py

@@ -0,0 +1,80 @@
+"""Helpers for recognizing completed video outputs."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ytcap.exporters.output_paths import OutputLayout
+
+
+@dataclass(frozen=True)
+class ExistingVideoOutput:
+    metadata_path: Path
+    subtitle_path: Path
+
+
+def find_existing_video_output(
+    video_id: str,
+    *,
+    layout: OutputLayout,
+    language: str,
+    source: str,
+    subtitle_format: str,
+) -> ExistingVideoOutput | None:
+    """Return matching existing output for the requested subtitle selection."""
+    meta_path = layout.metadata_path(video_id)
+    if not meta_path.exists():
+        return None
+
+    try:
+        with open(meta_path, "r", encoding="utf-8") as f:
+            meta = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+
+    subtitles = meta.get("subtitles", [])
+    if not isinstance(subtitles, list):
+        return None
+
+    for track in subtitles:
+        if not _track_matches(track, language=language, source=source, subtitle_format=subtitle_format):
+            continue
+        subtitle_path = _existing_subtitle_path(track.get("path"), layout=layout)
+        if subtitle_path is not None:
+            return ExistingVideoOutput(metadata_path=meta_path, subtitle_path=subtitle_path)
+    return None
+
+
+def _track_matches(track: Any, *, language: str, source: str, subtitle_format: str) -> bool:
+    if not isinstance(track, dict):
+        return False
+    if not track.get("selected") or not track.get("downloaded"):
+        return False
+    if track.get("language") != language:
+        return False
+    track_source = track.get("source")
+    if source == "any":
+        if track_source not in {"manual", "auto"}:
+            return False
+    elif track_source != source:
+        return False
+
+    formats = track.get("formats")
+    return isinstance(formats, list) and subtitle_format in formats
+
+
+def _existing_subtitle_path(path_value: Any, *, layout: OutputLayout) -> Path | None:
+    if not isinstance(path_value, str) or not path_value:
+        return None
+
+    subtitle_path = Path(path_value)
+    if subtitle_path.exists():
+        return subtitle_path
+
+    rooted_path = layout.root / subtitle_path
+    if rooted_path.exists():
+        return rooted_path
+    return None

ytcap/app/export_subtitles.py

@@ -0,0 +1,318 @@
+"""Subtitle export use case."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ytcap.errors import ErrorCode, YtcapError
+from ytcap.exporters.jsonl_writer import write_cue_jsonl_file, write_sentence_jsonl_file
+from ytcap.exporters.output_paths import normalized_file_path
+from ytcap.models.subtitle import SubtitleCue, SubtitleSentence
+from ytcap.services.subtitle_parser import parse_srt_file, parse_vtt_file
+from ytcap.services.subtitle_segmenter import segment_cues_into_sentences
+
+
+SUPPORTED_SUBTITLE_SUFFIXES = (".srt", ".vtt")
+SUPPORTED_SEGMENTS = ("cue", "sentence")
+KNOWN_SOURCES = ("manual", "auto")
+
+
+@dataclass(frozen=True)
+class ExportSubtitlesOptions:
+    input_path: str | Path
+    segments: str
+    output_dir: str | Path
+    video_id: str | None = None
+    language: str | None = None
+
+
+@dataclass(frozen=True)
+class ExportedSubtitleFile:
+    input_path: Path
+    output_path: Path
+    video_id: str
+    language: str
+    source: str
+    segment_count: int
+
+
+@dataclass(frozen=True)
+class ExportSubtitlesResult:
+    files: tuple[ExportedSubtitleFile, ...]
+
+
+@dataclass(frozen=True)
+class _SubtitleFileMetadata:
+    video_id: str | None
+    language: str | None
+    source: str
+
+
+@dataclass(frozen=True)
+class _ExportSubtitleJob:
+    input_path: Path
+    output_path: Path
+    metadata: _SubtitleFileMetadata
+
+
+@dataclass(frozen=True)
+class _PreparedSubtitleExport:
+    job: _ExportSubtitleJob
+    cues: tuple[SubtitleCue, ...]
+    sentences: tuple[SubtitleSentence, ...] | None
+    segment_count: int
+
+
+def export_subtitles(options: ExportSubtitlesOptions) -> ExportSubtitlesResult:
+    _validate_segments(options.segments)
+    input_path = Path(options.input_path)
+    subtitle_files = _subtitle_files(input_path, options=options)
+    output_dir = Path(options.output_dir)
+    jobs = _export_jobs(subtitle_files, output_dir=output_dir, options=options)
+    _validate_output_paths(jobs)
+    prepared_exports = tuple(
+        _prepare_subtitle_export(job, segments=options.segments)
+        for job in jobs
+    )
+
+    exported_files = tuple(
+        _write_prepared_export(prepared, segments=options.segments)
+        for prepared in prepared_exports
+    )
+    return ExportSubtitlesResult(files=exported_files)
+
+
+def _subtitle_files(input_path: Path, *, options: ExportSubtitlesOptions) -> tuple[Path, ...]:
+    if not input_path.exists():
+        raise YtcapError(
+            ErrorCode.INVALID_INPUT,
+            f"input path does not exist '{input_path}'",
+            exit_code=2,
+        )
+
+    if input_path.is_file():
+        _validate_supported_file(input_path)
+        return (input_path,)
+
+    if input_path.is_dir():
+        if options.video_id or options.language:
+            raise YtcapError(
+                ErrorCode.INVALID_INPUT,
+                "--video-id and --lang can only be used with a single subtitle file",
+                exit_code=2,
+            )
+        try:
+            files = tuple(
+                sorted(
+                    path
+                    for path in input_path.iterdir()
+                    if path.is_file() and _is_supported_subtitle_file(path)
+                )
+            )
+        except OSError as exc:
+            raise YtcapError(
+                ErrorCode.INVALID_INPUT,
+                f"could not read input directory '{input_path}': {exc}",
+                exit_code=2,
+            ) from exc
+        if not files:
+            raise YtcapError(
+                ErrorCode.INVALID_INPUT,
+                f"no SRT/VTT subtitle files found in directory '{input_path}'",
+                exit_code=2,
+            )
+        return files
+
+    raise YtcapError(
+        ErrorCode.INVALID_INPUT,
+        f"input path is not a file or directory '{input_path}'",
+        exit_code=2,
+    )
+
+
+def _export_jobs(
+    subtitle_files: tuple[Path, ...],
+    *,
+    output_dir: Path,
+    options: ExportSubtitlesOptions,
+) -> tuple[_ExportSubtitleJob, ...]:
+    jobs: list[_ExportSubtitleJob] = []
+    for path in subtitle_files:
+        metadata = _metadata_for_path(path, options=options)
+        output_path = normalized_file_path(
+            output_dir,
+            video_id=str(metadata.video_id),
+            language=str(metadata.language),
+            segments=options.segments,
+        )
+        jobs.append(
+            _ExportSubtitleJob(
+                input_path=path,
+                output_path=output_path,
+                metadata=metadata,
+            )
+        )
+    return tuple(jobs)
+
+
+def _validate_output_paths(jobs: tuple[_ExportSubtitleJob, ...]) -> None:
+    seen: dict[Path, Path] = {}
+    for job in jobs:
+        existing_input_path = seen.get(job.output_path)
+        if existing_input_path is not None:
+            raise YtcapError(
+                ErrorCode.INVALID_INPUT,
+                (
+                    f"multiple subtitle files map to the same output file '{job.output_path}': "
+                    f"'{existing_input_path}' and '{job.input_path}'"
+                ),
+                exit_code=2,
+            )
+        seen[job.output_path] = job.input_path
+
+    for job in jobs:
+        if job.output_path.exists():
+            raise YtcapError(
+                ErrorCode.OUTPUT_WRITE_FAILED,
+                (
+                    f"output file already exists '{job.output_path}'; "
+                    "remove it or choose another --out directory"
+                ),
+                exit_code=5,
+            )
+
+
+def _prepare_subtitle_export(
+    job: _ExportSubtitleJob,
+    *,
+    segments: str,
+) -> _PreparedSubtitleExport:
+    cues = tuple(_parse_subtitle_file(job.input_path))
+    if segments == "cue":
+        return _PreparedSubtitleExport(
+            job=job,
+            cues=cues,
+            sentences=None,
+            segment_count=len(cues),
+        )
+
+    sentences = tuple(segment_cues_into_sentences(cues))
+    return _PreparedSubtitleExport(
+        job=job,
+        cues=cues,
+        sentences=sentences,
+        segment_count=len(sentences),
+    )
+
+
+def _write_prepared_export(
+    prepared: _PreparedSubtitleExport,
+    *,
+    segments: str,
+) -> ExportedSubtitleFile:
+    job = prepared.job
+    metadata = job.metadata
+
+    if segments == "cue":
+        write_cue_jsonl_file(
+            job.output_path,
+            prepared.cues,
+            video_id=str(metadata.video_id),
+            language=str(metadata.language),
+            source=metadata.source,
+        )
+    else:
+        sentences = prepared.sentences or ()
+        write_sentence_jsonl_file(
+            job.output_path,
+            sentences,
+            video_id=str(metadata.video_id),
+            language=str(metadata.language),
+            source=metadata.source,
+        )
+
+    return ExportedSubtitleFile(
+        input_path=job.input_path,
+        output_path=job.output_path,
+        video_id=str(metadata.video_id),
+        language=str(metadata.language),
+        source=metadata.source,
+        segment_count=prepared.segment_count,
+    )
+
+
+def _metadata_for_path(path: Path, *, options: ExportSubtitlesOptions) -> _SubtitleFileMetadata:
+    inferred = _infer_metadata_from_filename(path)
+    metadata = _SubtitleFileMetadata(
+        video_id=options.video_id or inferred.video_id,
+        language=options.language or inferred.language,
+        source=inferred.source,
+    )
+    if metadata.video_id and metadata.language:
+        return metadata
+
+    raise YtcapError(
+        ErrorCode.INVALID_INPUT,
+        (
+            f"could not infer video id and language from subtitle file '{path.name}'; "
+            "expected VIDEO_ID.lang[.source].srt/vtt"
+        ),
+        exit_code=2,
+    )
+
+
+def _infer_metadata_from_filename(path: Path) -> _SubtitleFileMetadata:
+    parts = path.stem.split(".")
+    if len(parts) < 2:
+        return _SubtitleFileMetadata(video_id=None, language=None, source="unknown")
+
+    if len(parts) >= 3:
+        source_candidate = parts[-1].lower()
+        source = source_candidate if source_candidate in KNOWN_SOURCES else "unknown"
+        return _SubtitleFileMetadata(
+            video_id=".".join(parts[:-2]),
+            language=parts[-2],
+            source=source,
+        )
+
+    return _SubtitleFileMetadata(video_id=parts[0], language=parts[1], source="unknown")
+
+
+def _parse_subtitle_file(path: Path) -> list[SubtitleCue]:
+    suffix = path.suffix.lower()
+    if suffix == ".srt":
+        return parse_srt_file(path)
+    if suffix == ".vtt":
+        return parse_vtt_file(path)
+    _raise_unsupported_file(path)
+
+
+def _validate_segments(segments: str) -> None:
+    if segments in SUPPORTED_SEGMENTS:
+        return
+    supported = ", ".join(SUPPORTED_SEGMENTS)
+    raise YtcapError(
+        ErrorCode.INVALID_INPUT,
+        f"unsupported segment type '{segments}'; supported segments: {supported}",
+        exit_code=2,
+    )
+
+
+def _validate_supported_file(path: Path) -> None:
+    if _is_supported_subtitle_file(path):
+        return
+    _raise_unsupported_file(path)
+
+
+def _is_supported_subtitle_file(path: Path) -> bool:
+    return path.suffix.lower() in SUPPORTED_SUBTITLE_SUFFIXES
+
+
+def _raise_unsupported_file(path: Path) -> None:
+    supported = ", ".join(SUPPORTED_SUBTITLE_SUFFIXES)
+    raise YtcapError(
+        ErrorCode.INVALID_INPUT,
+        f"unsupported subtitle file extension '{path.suffix}'; supported extensions: {supported}",
+        exit_code=2,
+    )