How abdeladim-s/subsai works
Project type and purpose
• This is an open-source Python tool and library (“Subs AI”) for generating, translating, and synchronizing subtitles from audio/video.
• It offers three interaction surfaces: a CLI (subsai), a local Web-UI (subsai-webui), and a Python API (SubsAI class).
File structure
• Top-level directories/files:
• src/subsai/ – the core Python package
• assets/ – sample media and demo assets
• examples/ – Jupyter notebooks showing usage
• docs/ + mkdocs.yml – static documentation
• tests/ – unit tests
• Docker files (Dockerfile, docker-compose.yml, .github/workflows) for CI/Deployment
• Within src/subsai/:
• cli.py – entrypoint for the command-line interface
• webui.py – launches the local Web-UI (likely Streamlit or similar)
• main.py – core orchestration logic
• configs.py – JSON/config parsing utilities
• models/ – an abstract model interface and multiple implementations (Whisper variants, faster-whisper, whisper.cpp, whisperX, stable-ts, Hugging Face, OpenAI API)
• utils.py – common helpers (e.g., format conversion via pysubs2, VAD)
README for additional insights
• Confirms supported model backends, subtitle formats, translation via dl-translate, auto-sync via ffsubsync, merges via ffmpeg.
• Shows Docker usage, dependency on ffmpeg, optional GPU support.
• Describes three usage modes: Web-UI, CLI, Python API.
Main components and their interactions
a. User interfaces (UI layer)
• CLI (subsai console command)
• Web-UI (subsai-webui command serving a webpage locally)
• Python API (SubsAI class)
b. Core orchestration
• main.py – initializes configuration, selects model, processes media pipeline
c. Model abstraction layer
• abstract_model.py defines the common interface (load, transcribe)
• Concrete implementations in models/ folder call out to Whisper, Faster-Whisper, Whisper.cpp, WhisperX, Stable-TS, Hugging Face, OpenAI API
d. Pre/Post-processing utilities
• VAD slicing (optional)
• Subtitle formatting and file I/O (via pysubs2)
• Translation (calls dl-translate)
• Auto-sync (calls ffsubsync)
• Merging subtitles back into video (ffmpeg)
e. External services & dependencies
• ffmpeg (media I/O)
• PyTorch or CTranslate2 backends for model inference
• Hugging Face / OpenAI network calls (if using those backends)
Architectural patterns and design principles
• “Plug-in” model pattern: abstract interface + multiple interchangeable backends
• Separation of concerns: UI layer ↔ core engine ↔ model implementations ↔ utils
• Single binary/library with three front-ends (CLI, Web, API) but shared core
• Containerization: Dockerfile + docker-compose for reproducible environments