How ach-raf/opensubtitles_subtitle_downloader works
Project type and purpose
• This is a standalone, full-featured Python CLI tool whose primary job is to automate subtitle discovery, download, cleaning, and synchronization for one or more video files or folders.
• It integrates with two external subtitle services (OpenSubtitles.com and SubDL.com), uses ffsubsync (and by extension ffmpeg) for audio‐subtitle synchronization, and offers a configurable pipeline (cleaning ads, enforcing UTF-8, language selection, API key management).
File structure
• Top-level scripts
• download_subs.py – the main CLI entry point
• download_subs.sh / 1_download_subs.bat – OS-specific wrappers to activate the virtualenv and run the Python script
• Configuration
• config.yaml.sample – YAML template for API keys, behaviors, language options
• Library modules (in library/) – core logic broken into components:
• OpenSubtitles.py – API client for OpenSubtitles.com
• SubDL.py – API client for SubDL.com
• subtitle_utils.py – utilities for scanning video files and matching metadata
• clean_subtitles.py – removes ads/boilerplate from subtitle files
• sync_subtitles.py – wraps ffsubsync synchronization calls
• ads.txt – list of ad markers used by clean_subtitles.py
• Other files
• requirements.txt – Python dependencies
• LICENSE, .gitignore, Readme.md, screenshots/**
README for additional insights
• Describes a step-by-step install and config process using uv or pip
• Highlights core features: multi-source support, interactive vs automated modes, bulk processing
• Notes external dependencies: Python ≥3.7, ffmpeg, ffsubsync
Detailed capture of essential elements
• Notes on key config options that alter flow (e.g., preferred_backend, sync_audio_to_subs)
• External dependencies separately so viewers see which components they must install or configure