# ach-raf/opensubtitles_subtitle_downloader architecture

> Architecture diagram of the GitHub repository ach-raf/opensubtitles_subtitle_downloader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ach-raf/opensubtitles_subtitle_downloader
- Repository: https://github.com/ach-raf/opensubtitles_subtitle_downloader

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core modules
    CLI["CLI Orchestrator\ndownload_subs.py"]:::core
    Config["Configuration Loader\nconfig.yaml.sample"]:::config
    Scanner["File Scanner / Input Handler\nsubtitle_utils.py"]:::core

    subgraph "Source Adapters"
        OSClient["OpenSubtitles API Client\nOpenSubtitles.py"]:::core
        SubDLClient["SubDL API Client\nSubDL.py"]:::core
    end

    subgraph "Processing Pipeline"
        Cleaner["Subtitle Cleaner\nclean_subtitles.py"]:::processing
        AdsList["Ad Markers List\nads.txt"]:::core
        Sync["Audio Synchronizer\nsync_subtitles.py"]:::processing
        Encode["Encoding Enforcer\n(UTF-8)"]:::processing
    end

    Writer["Output Writer\ndownload_subs.py"]:::core

    %% External services & dependencies
    ExtOS["OpenSubtitles.com API"]:::external
    ExtSubDL["SubDL.com API"]:::external
    FFS["ffsubsync / ffmpeg"]:::external
    Req["Python Dependencies\nrequirements.txt"]:::deps

    %% Data flow
    CLI -->|"load config"| Config
    Config -->|"scan paths"| Scanner
    Scanner -->|"file metadata"| OSClient
    Scanner -->|"file metadata"| SubDLClient

    OSClient -->|"HTTP/S subtitle request"| ExtOS
    SubDLClient -->|"HTTP/S subtitle request"| ExtSubDL

    OSClient -->|"raw subtitle stream"| Cleaner
    SubDLClient -->|"raw subtitle stream"| Cleaner

    AdsList -->|"ad markers"| Cleaner
    Cleaner -->|"cleaned subtitle"| Sync
    Sync -->|"synced subtitle"| Encode
    Sync -->|"shell invocation"| FFS
    Encode -->|"encoded subtitle"| Writer

    Writer -->|"writes .srt files"| FileSystem

    Req -.-> CLI

    %% Click Events
    click CLI "https://github.com/ach-raf/opensubtitles_subtitle_downloader/blob/master/download_subs.py"
    click Config "https://github.com/ach-raf/opensubtitles_subtitle_downloader/blob/master/config.yaml.sample"
    click Scanner "https://github.com/ach-raf/opensubtitles_subtitle_downloader/blob/master/library/subtitle_utils.py"
    click OSClient "https://github.com/ach-raf/opensubtitles_subtitle_downloader/blob/master/library/OpenSubtitles.py"
    click SubDLClient "https://github.com/ach-raf/opensubtitles_subtitle_downloader/blob/master/library/SubDL.py"
    click Cleaner "https://github.com/ach-raf/opensubtitles_subtitle_downloader/blob/master/library/clean_subtitles.py"
    click AdsList "https://github.com/ach-raf/opensubtitles_subtitle_downloader/blob/master/library/ads.txt"
    click Sync "https://github.com/ach-raf/opensubtitles_subtitle_downloader/blob/master/library/sync_subtitles.py"
    click Writer "https://github.com/ach-raf/opensubtitles_subtitle_downloader/blob/master/download_subs.py"
    click Req "https://github.com/ach-raf/opensubtitles_subtitle_downloader/blob/master/requirements.txt"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#2980B9
    classDef external fill:#FDEBD0,stroke:#D35400
    classDef processing fill:#D5F5E3,stroke:#27AE60
    classDef config fill:#EBEDEF,stroke:#566573
    classDef deps fill:#E8DAEF,stroke:#8E44AD
```
