audio2sub 0.1.2

Transcribe media files to SRT subtitles.

Audio2Sub

Audio2Sub is a command-line tool that automatically transcribes audio from video or audio files and generates subtitles in the .srt format. It uses FFmpeg for media handling, Silero VAD for precise voice activity detection, and supports multiple transcription backends to convert speech to text.

Installation

Before installing, you must have FFmpeg installed and available in your system's PATH.

You can install Audio2Sub using pip. The default installation includes the faster_whisper backend.

pip install audio2sub[faster_whisper]

To install with a different backend, see the table in the Backends section below.

Usage

Basic Example

audio2sub my_video.mp4 -o my_video.srt --lang en

This command will transcribe the audio from my_video.mp4 into English and save the subtitles to my_video.srt.

Notes:

• First-Time Use: The first time you run the program, it will download the necessary transcription models. This may take some time and require significant disk space.
• CUDA: Performance significantly degraded without CUDA when using whisper-based local models. The program will raise a warning if CUDA is not available when it starts. If your system has a compatible GPU, install the CUDA Toolkit first. If you are sure CUDA has been installed correctly and still get the warning, you may need to reinstall a compatible PyTorch version manually. The reinstallation of PyTorch may break other dependencies if you choose a different version than what you currently have. In this case, you may need to reinstall those according to the warnings shown.

Using a Different Transcriber

Use the -t or --transcriber flag to select a different backend.

audio2sub my_audio.wav -o my_audio.srt --lang en -t whisper --model medium

Each transcriber has its own options. To see them, use --help with the transcriber specified.

audio2sub -t faster_whisper --help

Docker

Audio2Sub provides official Docker images for easy deployment without managing dependencies.

Quick Start

# With GPU support (recommended)
docker run --rm --gpus all -v "$(pwd):/media" xavierlam/audio2sub \
  my_video.mp4 -o my_video.srt --lang en

# Without GPU support, whisper backend
docker run --rm -v "$(pwd):/media" xavierlam/audio2sub:whisper \
  my_video.mp4 -o my_video.srt --lang en

Use --gpus all to enable GPU support, use different tags to select different backends.

Available Images

Image Tag	Backend	Description
xavierlam/audio2sub:latest	faster-whisper	Recommended (same as faster-whisper)
xavierlam/audio2sub:faster-whisper	faster-whisper	Fast CTranslate2-based Whisper
xavierlam/audio2sub:whisper	whisper	Original OpenAI Whisper
xavierlam/audio2sub:gemini	gemini	Google Gemini API

For detailed Docker documentation, GPU setup, and troubleshooting, see docker/README.md.

Backends

Audio2Sub supports the following transcription backends.

Backend Name	Description
faster_whisper	A faster reimplementation of Whisper using CTranslate2. See Faster Whisper. This is the default backend.
whisper	The original speech recognition model by OpenAI. See OpenAI Whisper.
gemini	Google's Gemini model via their API. Requires a GEMINI_API_KEY environment variable or --api-key argument.

You should use pip install audio2sub[<backend>] to install the desired backend support and use the corresponding transcriber with the -t flag.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on the GitHub repository.