subs-down-n-sync 1.0.0__py3-none-any.whl

subs_down_n_sync/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "1.0.0"
+
+from subs_down_n_sync.core import run
+
+__all__ = ["run", "__version__"]

subs_down_n_sync/__main__.py

@@ -0,0 +1,3 @@
+from subs_down_n_sync.cli import main
+
+main()

subs_down_n_sync/cli.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TaskID,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Table
+
+from subs_down_n_sync.core import DEFAULT_LANG, VIDEO_EXTENSIONS, RunSummary, run
+from subs_down_n_sync.exceptions import SubsDownError
+
+MAX_PARALLEL_WORKERS = 2
+
+console = Console()
+err_console = Console(stderr=True)
+
+_STEP_LABELS: dict[str, str] = {
+    "validando": "Validando vídeo...",
+    "buscando": "Buscando legenda no OpenSubtitles...",
+    "baixado": "Legenda encontrada e baixada",
+    "referencia": "Baixando legenda EN de referência...",
+    "sem_referencia": "Referência EN não encontrada — sincronização ignorada",
+    "sincronizando": "Alinhando com embeddings semânticos...",
+    "sincronizado": "Sincronização concluída",
+    "sem_sync": "Legenda já sincronizada",
+    "erro_sync": "Erro na sincronização",
+    "concluido": "Finalizado",
+}
+
+_STEPS_WITH_SYNC = [
+    "validando",
+    "buscando",
+    "baixado",
+    "referencia",
+    "sincronizando",
+    "concluido",
+]
+
+_STEPS_NO_SYNC = [
+    "validando",
+    "buscando",
+    "baixado",
+    "concluido",
+]
+
+
+def _make_progress() -> Progress:
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[bold blue]{task.description}"),
+        TextColumn("[dim]{task.fields[detail]}"),
+        TimeElapsedColumn(),
+        console=console,
+        transient=False,
+    )
+
+
+def _print_summary(summary: RunSummary) -> None:
+    if summary.sync_error:
+        status_line = (
+            f"[yellow]Aviso:[/yellow] sincronização falhou — legenda original mantida.\n"
+            f"Detalhe: {summary.sync_error}"
+        )
+        border = "yellow"
+    elif summary.synced:
+        status_line = (
+            f"[green]Sincronizada[/green] "
+            f"(ajuste médio: {summary.offset_seconds:.2f}s, modo: {summary.sync_mode})"
+        )
+        border = "green"
+    else:
+        status_line = (
+            f"[cyan]Já sincronizada[/cyan] (offset médio: {summary.offset_seconds:.2f}s < 0.10s)"
+        )
+        border = "cyan"
+
+    body = (
+        f"Idioma: [bold]{summary.lang_tag}[/bold]  |  "
+        f"Provider: {summary.provider}  |  "
+        f"Match: {summary.match_type}\n"
+        f"{status_line}\n"
+        f"Tempo total: {summary.elapsed_seconds:.2f}s"
+    )
+
+    console.print(Panel(body, title="subs-down-n-sync", border_style=border))
+
+
+def _make_batch_progress() -> Progress:
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[bold blue]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TextColumn("[dim]{task.fields[detail]}"),
+        TimeElapsedColumn(),
+        console=console,
+        transient=False,
+    )
+
+
+def _process_video(
+    video: Path,
+    lang_tag: str,
+    progress: Progress,
+) -> RunSummary:
+    task_id = progress.add_task(video.name, detail="aguardando...", total=None)
+
+    def on_progress(step: str, detail: str) -> None:
+        label = _STEP_LABELS.get(step, step)
+        progress.update(task_id, description=f"{video.name} — {label}", detail=detail)
+
+    try:
+        return run(str(video), lang_tag=lang_tag, on_progress=on_progress)
+    finally:
+        progress.remove_task(task_id)
+
+
+def _run_directory(
+    dir_path: Path,
+    lang_tag: str,
+    overwrite: bool,
+    parallel: bool = False,
+) -> tuple[list[RunSummary], list[Path], list[tuple[Path, str]]]:
+    videos = sorted(p for p in dir_path.rglob("*") if p.suffix.lower() in VIDEO_EXTENSIONS)
+
+    results: list[RunSummary] = []
+    skipped: list[Path] = []
+    errors: list[tuple[Path, str]] = []
+
+    to_process: list[Path] = []
+    for video in videos:
+        srt_path = video.with_suffix("").with_suffix(f".{lang_tag}.srt")
+        if srt_path.exists() and not overwrite:
+            skipped.append(video)
+            continue
+        to_process.append(video)
+
+    if not to_process:
+        return results, skipped, errors
+
+    progress = _make_batch_progress()
+    overall = progress.add_task(
+        f"Lote ({len(to_process)} vídeo(s))",
+        detail="",
+        total=len(to_process),
+    )
+
+    with progress:
+        if parallel:
+            with ThreadPoolExecutor(max_workers=MAX_PARALLEL_WORKERS) as pool:
+                futures = {
+                    pool.submit(_process_video, v, lang_tag, progress): v for v in to_process
+                }
+                for fut in as_completed(futures):
+                    video = futures[fut]
+                    try:
+                        results.append(fut.result())
+                    except SubsDownError as e:
+                        errors.append((video, str(e)))
+                    progress.advance(overall)
+        else:
+            for video in to_process:
+                try:
+                    results.append(_process_video(video, lang_tag, progress))
+                except SubsDownError as e:
+                    errors.append((video, str(e)))
+                progress.advance(overall)
+
+    return results, skipped, errors
+
+
+def _print_batch_summary(
+    results: list[RunSummary],
+    skipped: list[Path],
+    errors: list[tuple[Path, str]],
+) -> None:
+    table = Table(title="subs-down-n-sync — lote", show_lines=False)
+    table.add_column("Arquivo", style="bold")
+    table.add_column("Status")
+    table.add_column("Idioma")
+    table.add_column("Provider")
+    table.add_column("Offset")
+
+    for s in results:
+        if s.sync_error:
+            status = "[yellow]aviso[/yellow]"
+        elif s.synced:
+            status = "[green]sincronizado[/green]"
+        else:
+            status = "[cyan]ok[/cyan]"
+        table.add_row(
+            s.output_path.name,
+            status,
+            s.lang_tag,
+            s.provider,
+            f"{s.offset_seconds:.2f}s",
+        )
+
+    for path in skipped:
+        table.add_row(path.name, "[dim]pulado[/dim]", "-", "-", "-")
+
+    for path, _msg in errors:
+        table.add_row(path.name, "[red]erro[/red]", "-", "-", "-")
+
+    console.print(table)
+
+    parts = []
+    if results:
+        parts.append(f"[green]{len(results)} processado(s)[/green]")
+    if skipped:
+        parts.append(f"[dim]{len(skipped)} pulado(s)[/dim]")
+    if errors:
+        parts.append(f"[red]{len(errors)} erro(s)[/red]")
+
+    console.print("  ".join(parts) if parts else "[dim]Nenhum vídeo encontrado.[/dim]")
+
+    if errors:
+        console.print()
+        for path, msg in errors:
+            err_console.print(f"[bold red]Erro[/bold red] {path.name}: {msg}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="subs-down-n-sync",
+        description="Busca e sincroniza legenda para arquivo(s) de vídeo.",
+    )
+    parser.add_argument("path", help="Caminho para arquivo de vídeo ou diretório.")
+    parser.add_argument(
+        "-l",
+        "--lang",
+        default=DEFAULT_LANG,
+        help=f"Código de idioma BCP 47 (ex: pt-BR, en, es). Default: {DEFAULT_LANG}.",
+    )
+    parser.add_argument(
+        "-o",
+        "--overwrite",
+        action="store_true",
+        default=False,
+        help=(
+            "Sobrescrever legendas existentes. Por padrão, vídeos com legenda "
+            "já existente são pulados."
+        ),
+    )
+    parser.add_argument(
+        "-p",
+        "--parallel",
+        action="store_true",
+        default=False,
+        help=(
+            f"Processar vídeos em paralelo (até {MAX_PARALLEL_WORKERS} simultâneos) "
+            "quando o caminho for um diretório."
+        ),
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    p = Path(args.path).expanduser()
+
+    if p.is_dir():
+        results, skipped, errors = _run_directory(
+            p,
+            lang_tag=args.lang,
+            overwrite=args.overwrite,
+            parallel=args.parallel,
+        )
+        _print_batch_summary(results, skipped, errors)
+        return 1 if errors else 0
+
+    if not p.exists():
+        err_console.print(f"[bold red]Erro:[/bold red] Caminho não existe: {p}")
+        return 1
+
+    progress = _make_progress()
+    task_id: TaskID | None = None
+
+    completed_steps: list[str] = []
+
+    def on_progress(step: str, detail: str) -> None:
+        nonlocal task_id
+
+        label = _STEP_LABELS.get(step, step)
+
+        if task_id is None:
+            task_id = progress.add_task(label, detail=detail, total=None)
+        else:
+            progress.update(task_id, description=label, detail=detail)
+
+        completed_steps.append(step)
+
+        if step in ("baixado", "sincronizado", "sem_sync", "sem_referencia", "erro_sync"):
+            console.log(f"[dim]{label}[/dim] {detail}")
+
+    with progress:
+        try:
+            summary = run(args.path, lang_tag=args.lang, on_progress=on_progress)
+        except SubsDownError as e:
+            progress.stop()
+            err_console.print(f"[bold red]Erro:[/bold red] {e}")
+            return 1
+
+    _print_summary(summary)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

subs_down_n_sync/core.py

@@ -0,0 +1,538 @@
+"""subs_down_n_sync: busca e sincroniza legendas (pt-BR por padrão, qualquer BCP 47)."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import tempfile
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import subliminal
+from babelfish import Language
+from scipy.spatial.distance import cdist
+from sentence_transformers import SentenceTransformer
+from subliminal.refiners.hash import refine as hash_refine
+from subliminal.score import compute_score
+
+from subs_down_n_sync.exceptions import (
+    InvalidLanguageError,
+    InvalidVideoError,
+    MissingCredentialsError,
+    MissingDependencyError,
+    SubtitleNotFoundError,
+    SubtitleSyncError,
+)
+
+VIDEO_EXTENSIONS = {".mkv", ".mp4", ".avi", ".mov", ".m4v", ".wmv", ".flv", ".webm"}
+
+DEFAULT_LANG = "pt-BR"
+
+SCORE_THRESHOLD = 0.9  # score/max_score >= 90% → sem sync
+
+SYNC_THRESHOLD_SECONDS = 0.1
+
+_TS_RE = re.compile(
+    r"^(\d{2}):(\d{2}):(\d{2}),(\d{3})\s*-->\s*\d{2}:\d{2}:\d{2},\d{3}",
+    re.MULTILINE,
+)
+
+_SRT_BLOCK_RE = re.compile(
+    r"(\d+)\n"
+    r"(\d{2}):(\d{2}):(\d{2}),(\d{3})\s*-->\s*(\d{2}):(\d{2}):(\d{2}),(\d{3})\n"
+    r"((?:.+\n?)+)",
+    re.MULTILINE,
+)
+
+
+@dataclass(frozen=True)
+class SubtitleInfo:
+    provider: str
+    match_type: str  # "hash" | "release" | "fallback"
+    needs_sync: bool
+
+
+@dataclass(frozen=True)
+class SyncResult:
+    synced: bool
+    offset_seconds: float
+    sync_mode: str = "none"  # "video" | "none"
+
+
+@dataclass(frozen=True)
+class RunSummary:
+    output_path: Path
+    provider: str
+    match_type: str
+    synced: bool
+    offset_seconds: float
+    sync_mode: str
+    sync_error: str | None
+    elapsed_seconds: float
+    lang_tag: str
+
+
+def check_ffmpeg() -> None:
+    if shutil.which("ffmpeg") is None:
+        raise MissingDependencyError(
+            "ffmpeg não encontrado no PATH. Instale via gerenciador de pacotes "
+            "(ex.: sudo apt install ffmpeg, brew install ffmpeg)."
+        )
+
+
+def load_credentials() -> tuple[str, str]:
+    user = os.environ.get("OPENSUBTITLES_USERNAME")
+    pwd = os.environ.get("OPENSUBTITLES_PASSWORD")
+
+    missing = [
+        name
+        for name, val in (
+            ("OPENSUBTITLES_USERNAME", user),
+            ("OPENSUBTITLES_PASSWORD", pwd),
+        )
+        if not val
+    ]
+
+    if missing:
+        raise MissingCredentialsError(
+            "Variáveis de ambiente obrigatórias faltando: " + ", ".join(missing)
+        )
+
+    return user, pwd  # type: ignore[return-value]
+
+
+def validate_video_path(raw: str) -> Path:
+    p = Path(raw).expanduser()
+
+    if not p.exists():
+        raise InvalidVideoError(f"Arquivo de vídeo não existe: {p}")
+    if not p.is_file():
+        raise InvalidVideoError(f"Caminho não é um arquivo: {p}")
+    if p.suffix.lower() not in VIDEO_EXTENSIONS:
+        raise InvalidVideoError(
+            f"Extensão não suportada ({p.suffix}). "
+            f"Esperado um destes: {', '.join(sorted(VIDEO_EXTENSIONS))}"
+        )
+
+    return p
+
+
+def parse_language(raw: str) -> Language:
+    try:
+        return Language.fromietf(raw)
+    except Exception as e:
+        raise InvalidLanguageError(
+            f"Código de idioma inválido: {raw!r}. Use tags BCP 47 como 'pt-BR', 'en', 'es', 'ja'."
+        ) from e
+
+
+def _classify_match(matches: set[str]) -> str:
+    if "hash" in matches:
+        return "hash"
+    if "release_group" in matches:
+        return "release"
+
+    return "fallback"
+
+
+def _filename_similarity(sub_filename: str, video_name: str) -> float:
+    """Fração de tokens do stem do vídeo presentes no nome da legenda."""
+    norm = re.compile(r"[\W_]+")
+    video_stem = Path(video_name).stem
+    sub_tokens = set(norm.sub(" ", sub_filename.lower()).split())
+    video_tokens = set(norm.sub(" ", video_stem.lower()).split())
+    if not video_tokens:
+        return 0.0
+    return len(sub_tokens & video_tokens) / len(video_tokens)
+
+
+def _pick_subtitle(
+    candidates: list,
+    video: object,
+) -> tuple[object, str, bool]:
+    """Escolhe melhor legenda e decide se precisa de sync.
+
+    Retorna (subtitle, match_type, needs_sync).
+    Ordem de preferência:
+      1. hash match → sem sync
+      2. release_group match → melhor filename similarity → com sync
+      3. fallback → melhor filename similarity → com sync
+    """
+    video_name = getattr(video, "name", "") or ""
+
+    scored = [(sub, compute_score(sub, video)) for sub in candidates]
+    scored.sort(key=lambda x: x[1], reverse=True)
+
+    # 1. hash match
+    for sub, _ in scored:
+        if "hash" in set(sub.get_matches(video)):
+            return sub, "hash", False
+
+    # 2. release_group match
+    release_candidates = [
+        (sub, score) for sub, score in scored if "release_group" in set(sub.get_matches(video))
+    ]
+    pool = release_candidates if release_candidates else scored
+    match_type = "release" if release_candidates else "fallback"
+
+    best_sub = max(
+        pool,
+        key=lambda x: _filename_similarity(getattr(x[0], "filename", "") or "", video_name),
+    )[0]
+    return best_sub, match_type, True
+
+
+def _download_sub(
+    video: object,
+    language: Language,
+    provider_configs: dict,
+) -> object | None:
+    """Busca e baixa melhor legenda disponível para o idioma. Retorna subtitle ou None."""
+    results = subliminal.list_subtitles(
+        {video},
+        {language},
+        providers=["opensubtitles"],
+        provider_configs=provider_configs,
+    )
+    candidates = results.get(video, [])
+    candidates = [s for s in candidates if getattr(s, "language", None) == language]
+
+    if not candidates:
+        return None
+
+    scored = [(sub, compute_score(sub, video)) for sub in candidates]
+    scored.sort(key=lambda x: x[1], reverse=True)
+    best = scored[0][0]
+
+    subliminal.download_subtitles([best], provider_configs=provider_configs)
+    return best if best.text else None
+
+
+def find_and_download_subtitle(
+    video_path: Path,
+    language: Language,
+    credentials: tuple[str, str],
+) -> tuple[Path, SubtitleInfo]:
+    user, pwd = credentials
+    video = subliminal.scan_video(str(video_path))
+    hash_refine(video)
+
+    provider_configs = {"opensubtitles": {"username": user, "password": pwd}}
+
+    results = subliminal.list_subtitles(
+        {video},
+        {language},
+        providers=["opensubtitles"],
+        provider_configs=provider_configs,
+    )
+    candidates = results.get(video, [])
+    target_candidates = [s for s in candidates if getattr(s, "language", None) == language]
+
+    if not target_candidates:
+        raise SubtitleNotFoundError(
+            f"Nenhuma legenda em {language.alpha3} encontrada para: {video_path.name}"
+        )
+
+    subtitle, match_type, needs_sync = _pick_subtitle(target_candidates, video)
+
+    subliminal.download_subtitles([subtitle], provider_configs=provider_configs)
+
+    # Não usamos subliminal.save_subtitles porque ele grava os bytes crus no
+    # encoding detectado (ex.: cp1252), produzindo mojibake. Pegamos o texto
+    # já decodificado e escrevemos em UTF-8.
+    if not subtitle.text:
+        raise SubtitleNotFoundError(f"Legenda veio vazia do provider para: {video_path.name}")
+
+    srt_path = video_path.parent / Path(subtitle.get_path(video)).name
+    srt_path.write_text(subtitle.text, encoding="utf-8")
+
+    info = SubtitleInfo(
+        provider=subtitle.provider_name,
+        match_type=match_type,
+        needs_sync=needs_sync,
+    )
+
+    return srt_path, info
+
+
+def find_reference_subtitle(
+    video_path: Path,
+    credentials: tuple[str, str],
+) -> Path | None:
+    """Baixa legenda EN como referência de alinhamento. Retorna path ou None."""
+    user, pwd = credentials
+    video = subliminal.scan_video(str(video_path))
+    hash_refine(video)
+
+    en = Language("eng")
+    provider_configs = {"opensubtitles": {"username": user, "password": pwd}}
+
+    subtitle = _download_sub(video, en, provider_configs)
+    if subtitle is None:
+        return None
+
+    tmp_dir = Path(tempfile.mkdtemp(prefix="subs_ref_"))
+    ref_path = tmp_dir / Path(subtitle.get_path(video)).name
+    ref_path.write_text(subtitle.text, encoding="utf-8")
+
+    return ref_path
+
+
+def _ts(h: str, m: str, s: str, ms: str) -> float:
+    return int(h) * 3600 + int(m) * 60 + int(s) + int(ms) / 1000
+
+
+def _seconds_to_ts(total: float) -> str:
+    total = max(0.0, total)
+    h = int(total // 3600)
+    m = int((total % 3600) // 60)
+    s = int(total % 60)
+    ms = round((total - int(total)) * 1000)
+    if ms == 1000:
+        ms = 0
+        s += 1
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def _srt_to_segments(srt_text: str) -> list[dict]:
+    segments = []
+    for m in _SRT_BLOCK_RE.finditer(srt_text):
+        segments.append(
+            {
+                "start": _ts(m.group(2), m.group(3), m.group(4), m.group(5)),
+                "end": _ts(m.group(6), m.group(7), m.group(8), m.group(9)),
+                "text": m.group(10).strip(),
+            }
+        )
+    return segments
+
+
+def _parse_srt_timestamps(srt_text: str) -> list[float]:
+    out: list[float] = []
+
+    for h, m, s, ms in _TS_RE.findall(srt_text):
+        out.append(int(h) * 3600 + int(m) * 60 + int(s) + int(ms) / 1000)
+
+    return out
+
+
+def _mean_offset_seconds(orig: list[float], synced: list[float]) -> float:
+    n = min(len(orig), len(synced))
+
+    if n == 0:
+        return 0.0
+
+    total = sum(abs(synced[i] - orig[i]) for i in range(n))
+
+    return total / n
+
+
+_SEMANTIC_MODEL = "paraphrase-multilingual-MiniLM-L12-v2"
+
+
+def _align_cues_by_semantics(
+    target_cues: list[dict],
+    ref_cues: list[dict],
+) -> list[dict]:
+    """Alinha cues de legenda alvo aos timestamps da referência via embeddings semânticos + DTW.
+
+    Para cada cue alvo, encontra o(s) cue(s) ref mais similar(es) semanticamente
+    e copia os timestamps. Garante ordem monotônica crescente no resultado.
+    """
+    model = SentenceTransformer(_SEMANTIC_MODEL)
+
+    target_texts = [c["text"] for c in target_cues]
+    ref_texts = [c["text"] for c in ref_cues]
+
+    target_emb = model.encode(target_texts, convert_to_numpy=True)
+    ref_emb = model.encode(ref_texts, convert_to_numpy=True)
+
+    # matriz de distância coseno: shape (len_target, len_ref)
+    dist_matrix = cdist(target_emb, ref_emb, metric="cosine")
+
+    # DTW simples: encontra caminho de alinhamento ótimo
+    n, m = dist_matrix.shape
+    cost = np.full((n + 1, m + 1), np.inf)
+    cost[0, 0] = 0.0
+
+    for i in range(1, n + 1):
+        for j in range(1, m + 1):
+            cost[i, j] = dist_matrix[i - 1, j - 1] + min(
+                cost[i - 1, j],  # inserção
+                cost[i, j - 1],  # deleção
+                cost[i - 1, j - 1],  # match
+            )
+
+    # traceback
+    path: list[tuple[int, int]] = []
+    i, j = n, m
+    while i > 0 and j > 0:
+        path.append((i - 1, j - 1))
+        options = [
+            (cost[i - 1, j - 1], i - 1, j - 1),
+            (cost[i - 1, j], i - 1, j),
+            (cost[i, j - 1], i, j - 1),
+        ]
+        _, i, j = min(options, key=lambda x: x[0])
+    path.reverse()
+
+    # para cada cue alvo, coleta os ref_cues mapeados e usa média dos timestamps
+    from collections import defaultdict
+
+    target_to_refs: dict[int, list[int]] = defaultdict(list)
+    for ti, ri in path:
+        target_to_refs[ti].append(ri)
+
+    result = []
+    for ti, cue in enumerate(target_cues):
+        mapped = target_to_refs.get(ti, [])
+        orig_duration = max(cue["end"] - cue["start"], 0.0)
+
+        if mapped:
+            # usa start do primeiro ref mapeado (não média, evita puxar p/ meio)
+            start = float(ref_cues[mapped[0]]["start"])
+            # preserva duração original do target (frase pt pode ser mais longa que en)
+            end = start + orig_duration
+        else:
+            start, end = cue["start"], cue["end"]
+
+        # duração mínima de leitura: ~60ms/char, mínimo 1s, teto 7s
+        min_duration = max(1.0, min(len(cue["text"]) * 0.06, 7.0))
+        if end - start < min_duration:
+            end = start + min_duration
+
+        result.append({"start": start, "end": end, "text": cue["text"]})
+
+    # garante ordem monotônica e clamp contra próximo cue
+    for i in range(1, len(result)):
+        if result[i]["start"] <= result[i - 1]["start"]:
+            gap = max(result[i - 1]["end"] - result[i - 1]["start"], 0.1)
+            result[i]["start"] = result[i - 1]["start"] + gap
+            duration = result[i]["end"] - result[i]["start"]
+            result[i]["end"] = result[i]["start"] + max(duration, 0.1)
+
+    # clamp: end do cue i não invade start do cue i+1 (deixa 50ms de gap)
+    for i in range(len(result) - 1):
+        max_end = result[i + 1]["start"] - 0.05
+        if result[i]["end"] > max_end:
+            result[i]["end"] = max(max_end, result[i]["start"] + 0.1)
+
+    return result
+
+
+def _cues_to_srt(cues: list[dict]) -> str:
+    lines = []
+    for i, cue in enumerate(cues, start=1):
+        lines.append(
+            f"{i}\n{_seconds_to_ts(cue['start'])} --> {_seconds_to_ts(cue['end'])}\n{cue['text']}\n"
+        )
+    return "\n".join(lines)
+
+
+def sync_subtitle(
+    srt_path: Path,
+    ref_path: Path,
+) -> SyncResult:
+    """Alinha legenda alvo usando legenda EN de referência via embeddings semânticos."""
+    target_text = srt_path.read_text(encoding="utf-8", errors="replace")
+    target_cues = _srt_to_segments(target_text)
+    target_ts_orig = [c["start"] for c in target_cues]
+
+    ref_text = ref_path.read_text(encoding="utf-8", errors="replace")
+    ref_cues = _srt_to_segments(ref_text)
+
+    try:
+        aligned_cues = _align_cues_by_semantics(target_cues, ref_cues)
+    except Exception as e:
+        raise SubtitleSyncError(f"alinhamento semântico falhou: {e}") from e
+
+    aligned_ts = [c["start"] for c in aligned_cues]
+    offset = _mean_offset_seconds(target_ts_orig, aligned_ts)
+
+    if offset < SYNC_THRESHOLD_SECONDS:
+        return SyncResult(synced=False, offset_seconds=offset, sync_mode="none")
+
+    srt_path.write_text(_cues_to_srt(aligned_cues), encoding="utf-8")
+    return SyncResult(synced=True, offset_seconds=offset, sync_mode="ref")
+
+
+def finalize_output_path(video_path: Path, srt_path: Path, lang_tag: str) -> Path:
+    target = video_path.with_suffix(f".{lang_tag}.srt")
+
+    if srt_path == target:
+        return target
+
+    srt_path.replace(target)
+
+    return target
+
+
+ProgressCallback = Callable[[str, str], None]
+
+
+def run(
+    video_arg: str,
+    lang_tag: str = DEFAULT_LANG,
+    on_progress: ProgressCallback | None = None,
+) -> RunSummary:
+    def _notify(step: str, detail: str = "") -> None:
+        if on_progress:
+            on_progress(step, detail)
+
+    start = time.monotonic()
+
+    _notify("validando", video_arg)
+    video_path = validate_video_path(video_arg)
+    check_ffmpeg()
+    language = parse_language(lang_tag)
+    credentials = load_credentials()
+
+    _notify("buscando", f"idioma={lang_tag}")
+    srt_path, info = find_and_download_subtitle(
+        video_path, language=language, credentials=credentials
+    )
+    _notify("baixado", f"provider={info.provider} match={info.match_type}")
+
+    sync_error: str | None = None
+
+    if info.needs_sync:
+        _notify("referencia", "buscando EN")
+        ref_path = find_reference_subtitle(video_path, credentials=credentials)
+
+        if ref_path is None:
+            sync_error = "legenda EN de referência não encontrada — sincronização ignorada"
+            sync_result = SyncResult(synced=False, offset_seconds=0.0, sync_mode="none")
+            _notify("sem_referencia", "")
+        else:
+            _notify("sincronizando", "embeddings semânticos")
+            try:
+                sync_result = sync_subtitle(srt_path, ref_path=ref_path)
+                _notify("sincronizado", f"offset={sync_result.offset_seconds:.2f}s")
+            except SubtitleSyncError as e:
+                sync_error = str(e)
+                sync_result = SyncResult(synced=False, offset_seconds=0.0, sync_mode="none")
+                _notify("erro_sync", str(e))
+    else:
+        sync_result = SyncResult(synced=False, offset_seconds=0.0, sync_mode="none")
+        _notify("sem_sync", f"offset={sync_result.offset_seconds:.2f}s")
+
+    final_path = finalize_output_path(video_path, srt_path, lang_tag=lang_tag)
+    elapsed = time.monotonic() - start
+
+    _notify("concluido", str(final_path))
+
+    return RunSummary(
+        output_path=final_path,
+        provider=info.provider,
+        match_type=info.match_type,
+        synced=sync_result.synced,
+        offset_seconds=sync_result.offset_seconds,
+        sync_mode=sync_result.sync_mode,
+        sync_error=sync_error,
+        elapsed_seconds=elapsed,
+        lang_tag=lang_tag,
+    )

subs_down_n_sync/exceptions.py

@@ -0,0 +1,31 @@
+"""Exceptions raised by subs_down_n_sync. Message is user-facing (in Portuguese)."""
+
+from __future__ import annotations
+
+
+class SubsDownError(Exception):
+    """Erro base do script — mensagem é o que vai para o usuário."""
+
+
+class InvalidVideoError(SubsDownError):
+    pass
+
+
+class MissingDependencyError(SubsDownError):
+    pass
+
+
+class MissingCredentialsError(SubsDownError):
+    pass
+
+
+class InvalidLanguageError(SubsDownError):
+    pass
+
+
+class SubtitleNotFoundError(SubsDownError):
+    pass
+
+
+class SubtitleSyncError(SubsDownError):
+    pass

subs_down_n_sync-1.0.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: subs-down-n-sync
+Version: 1.0.0
+Summary: CLI to download and sync subtitles for video files using semantic embeddings + DTW
+Author-email: Airton Soares <airtonnsoares@gmail.com>
+License: MIT
+Project-URL: Homepage, https://pypi.org/project/subs-down-n-sync/
+Project-URL: Repository, https://github.com/airton-soares/subs_down_n_sync
+Project-URL: Bug Tracker, https://github.com/airton-soares/subs_down_n_sync/issues
+Keywords: subtitles,subtitle-sync,opensubtitles,nlp,cli,video,sentence-transformers,dtw
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Classifier: Natural Language :: Portuguese (Brazilian)
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: subliminal>=2.2
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: scipy>=1.13
+Requires-Dist: setuptools<81
+Requires-Dist: rich>=13
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+
+# subs_down_n_sync
+
+![CI](https://github.com/airton-soares/subs_down_n_sync/actions/workflows/ci.yml/badge.svg)
+[![PyPI version](https://img.shields.io/pypi/v/subs-down-n-sync)](https://pypi.org/project/subs-down-n-sync/)
+[![Python versions](https://img.shields.io/pypi/pyversions/subs-down-n-sync)](https://pypi.org/project/subs-down-n-sync/)
+[![License](https://img.shields.io/github/license/airton-soares/subs_down_n_sync)](LICENSE)
+
+CLI Python para baixar e sincronizar legendas para arquivos de vídeo. Idioma padrão: **pt-BR**, configurável via flag `--lang` (qualquer tag BCP 47).
+
+A sincronização usa embeddings semânticos multilíngues ([sentence-transformers](https://www.sbert.net/), modelo `paraphrase-multilingual-MiniLM-L12-v2`) combinados com DTW: baixa uma legenda EN de referência e alinha os cues da legenda alvo aos timestamps da referência por similaridade semântica. Legendas com match exato (hash ou release group) são usadas sem sincronização.
+
+## Instalação
+
+```bash
+pip install subs-down-n-sync
+```
+
+Instale também o `ffmpeg`:
+
+```bash
+sudo apt install ffmpeg    # Debian/Ubuntu
+brew install ffmpeg        # macOS
+winget install Gyan.FFmpeg # Windows
+```
+
+Configure as credenciais do OpenSubtitles:
+
+```bash
+export OPENSUBTITLES_USERNAME="seu_usuario"
+export OPENSUBTITLES_PASSWORD="sua_senha"
+```
+
+> Para desenvolvimento, veja [Setup](#setup).
+
+## Setup
+
+Linux/macOS:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Windows (PowerShell):
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+```
+
+Windows (cmd.exe):
+
+```cmd
+python -m venv .venv
+.venv\Scripts\activate.bat
+pip install -e ".[dev]"
+```
+
+Instale também o `ffmpeg` no sistema:
+
+```bash
+sudo apt install ffmpeg    # Debian/Ubuntu
+brew install ffmpeg        # macOS
+```
+
+```powershell
+winget install Gyan.FFmpeg          # Windows (winget)
+choco install ffmpeg                # Windows (Chocolatey)
+scoop install ffmpeg                # Windows (Scoop)
+```
+
+Confirme que `ffmpeg` está no `PATH` rodando `ffmpeg -version` em novo terminal.
+
+## Configuração (uma única vez)
+
+Linux/macOS:
+
+```bash
+export OPENSUBTITLES_USERNAME="seu_usuario"
+export OPENSUBTITLES_PASSWORD="sua_senha"
+```
+
+Windows (PowerShell, sessão atual):
+
+```powershell
+$env:OPENSUBTITLES_USERNAME = "seu_usuario"
+$env:OPENSUBTITLES_PASSWORD = "sua_senha"
+```
+
+Windows (persistente, próximas sessões):
+
+```powershell
+setx OPENSUBTITLES_USERNAME "seu_usuario"
+setx OPENSUBTITLES_PASSWORD "sua_senha"
+```
+
+## Uso
+
+```bash
+# Default: pt-BR
+subs-down-n-sync /caminho/para/filme.mkv
+
+# Outro idioma (BCP 47: 'en', 'pt-BR', 'en-US', 'es', 'ja', ...)
+subs-down-n-sync /caminho/para/filme.mkv --lang en
+subs-down-n-sync /caminho/para/filme.mkv -l es
+
+# Processar diretório inteiro (busca vídeos recursivamente)
+subs-down-n-sync /caminho/para/pasta/
+subs-down-n-sync /caminho/para/pasta/ --lang en
+subs-down-n-sync /caminho/para/pasta/ --overwrite   # sobrescreve legendas existentes
+subs-down-n-sync /caminho/para/pasta/ --parallel    # processa até 2 vídeos simultâneos
+
+# Ou via módulo Python
+python -m subs_down_n_sync /caminho/para/filme.mkv
+```
+
+Ao passar um diretório, vídeos que já têm legenda (`<video>.<lang>.srt`) são pulados por padrão. Use `--overwrite` / `-o` para reprocessar. Use `--parallel` / `-p` para processar até 2 vídeos em paralelo.
+
+Saída: `/caminho/para/filme.<lang>.srt` (ex.: `filme.pt-BR.srt`, `filme.en.srt`). Isso permite manter legendas do mesmo vídeo em idiomas diferentes sem sobrescrever.
+
+## Desenvolvimento
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Os testes unitários rodam com gate de cobertura de 90% (configurado em `pyproject.toml`). O CI falha se a cobertura cair abaixo disso.
+
+Para rodar sem o gate (útil ao explorar com `-k` ou `--collect-only`):
+
+```bash
+pytest --no-cov
+```
+
+## Lint e formatação
+
+O projeto usa [Ruff](https://docs.astral.sh/ruff/) para formatação e lint.
+
+```bash
+ruff format .           # aplica formatação
+ruff format --check .   # verifica sem escrever (usado no CI)
+ruff check .            # roda lint
+ruff check --fix .      # aplica fixes automáticos
+```
+
+O CI falha se `ruff format --check` ou `ruff check` encontrarem problemas.
+
+## Testes de integração
+
+O projeto tem duas camadas de testes:
+
+- **Testes unitários** (padrão, `pytest`) — rápidos, mockam `subliminal` e `sentence_transformers`. Não precisam de rede nem de binários externos além do Python.
+- **Testes de integração** (`pytest -m integration`) — exercitam o pipeline real de alinhamento semântico (download do modelo `sentence-transformers` + DTW) sobre legendas reais. Requer acesso à internet no primeiro run para baixar o modelo (~120 MB), cacheado pelo Hugging Face em `~/.cache/huggingface/`.
+
+Como rodar cada camada:
+
+```bash
+pytest                    # só unit (rápido)
+pytest -m integration     # só integração (baixa modelo de embeddings, roda DTW real)
+pytest -m ""              # tudo (unit + integração)
+```

subs_down_n_sync-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+subs_down_n_sync/__init__.py,sha256=jlLhNwF8RXLhwXUYKN0v8AeiCwKbb9pejoJecLFCGxk,95
+subs_down_n_sync/__main__.py,sha256=4UUonBkrqVeT-ZqrBs96xCz1wsuAltma9tqYBAS-X-w,46
+subs_down_n_sync/cli.py,sha256=8j-T1DXmxnVQtdORQZYmTScB19YWPA6tCicukddXsnU,9298
+subs_down_n_sync/core.py,sha256=ScH0q6mvm2NSynO4Ylqbm7n_937y7KoO73vH6tnjua0,16714
+subs_down_n_sync/exceptions.py,sha256=HeOfy398O1dwhXGB8QuJ2PU8RvU5bFcBfrlEDzj8ti0,552
+subs_down_n_sync-1.0.0.dist-info/METADATA,sha256=uPvBQ-9BsbAQRPRzfzHK8Rz4uZc0tRoekVg4hh8s24g,6351
+subs_down_n_sync-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+subs_down_n_sync-1.0.0.dist-info/entry_points.txt,sha256=ml-sdvqTipASHrCRNYVhlKa5gSHOXEgXik80pcx-Db4,63
+subs_down_n_sync-1.0.0.dist-info/top_level.txt,sha256=uMLMnRnFOJuCkpl_5DIM-E2tl8Rg11rg8k0bwSMFze8,17
+subs_down_n_sync-1.0.0.dist-info/RECORD,,

subs_down_n_sync-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

subs_down_n_sync-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+subs-down-n-sync = subs_down_n_sync.cli:main

subs_down_n_sync-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+subs_down_n_sync