subs-down-n-sync 1.0.0__tar.gz

subs_down_n_sync-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,164 @@
+# 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/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "subs-down-n-sync"
+version = "1.0.0"
+description = "CLI to download and sync subtitles for video files using semantic embeddings + DTW"
+requires-python = ">=3.12"
+authors = [{name = "Airton Soares", email = "airtonnsoares@gmail.com"}]
+license = {text = "MIT"}
+readme = "README.md"
+keywords = ["subtitles", "subtitle-sync", "opensubtitles", "nlp", "cli", "video", "sentence-transformers", "dtw"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.12",
+    "Environment :: Console",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Utilities",
+    "Natural Language :: Portuguese (Brazilian)",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "subliminal>=2.2",
+    "sentence-transformers>=3.0",
+    "scipy>=1.13",
+    "setuptools<81",
+    "rich>=13",
+]
+
+[project.scripts]
+subs-down-n-sync = "subs_down_n_sync.cli:main"
+
+[project.urls]
+Homepage = "https://pypi.org/project/subs-down-n-sync/"
+Repository = "https://github.com/airton-soares/subs_down_n_sync"
+"Bug Tracker" = "https://github.com/airton-soares/subs_down_n_sync/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-mock>=3.12",
+    "pytest-cov>=6.0",
+    "ruff>=0.9",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+markers = ["integration: testes que dependem de ffmpeg, stable-ts e rede"]
+addopts = "-m 'not integration' --cov=src/subs_down_n_sync --cov-report=term-missing --cov-fail-under=90"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.coverage.run]
+source = ["src/subs_down_n_sync"]
+
+[tool.coverage.report]
+fail_under = 90
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/subs_down_n_sync/__init__.py:__version__"]
+branch = "main"
+build_command = "pip install build && python -m build"
+commit_message = "chore(release): {version} [skip ci]"

subs_down_n_sync-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

subs_down_n_sync-1.0.0/src/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-1.0.0/src/subs_down_n_sync/__main__.py

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