Vid Subtitle

Now supports Model Context Protocol (MCP) for video subtitle processing and secure local file access!!! See server/README.md for more details.

https://github.com/user-attachments/assets/105a2fe6-9122-4f33-a4a0-b8ed3f64cabc

vid-subtitle

A Python library to add subtitles to videos using FFmpeg and OpenAI Whisper API.

https://github.com/user-attachments/assets/7c2d0a6a-7d75-4837-b141-097104a0cb5e

Features

• Extract audio from MP4 and MOV video files
• Transcribe audio using OpenAI Whisper API
• Generate SRT subtitle files
• Embed subtitles into video files
• Support for multiple languages (English by default)

Prerequisites

• Python 3.7+
• FFmpeg installed on your system
• OpenAI API key

Installation

pip install vid-subtitle

Setup

1. Install FFmpeg on your system:

   • macOS: brew install ffmpeg
   • Ubuntu/Debian: sudo apt update && sudo apt install ffmpeg
   • Windows: Download from FFmpeg official website

2. Set your OpenAI API key as an environment variable:

   export OPENAI_API_KEY="your-api-key-here"
   

   or create a .env file in the root directory and add the following:

   OPENAI_API_KEY=your-api-key-here
   

Usage

Basic Usage

from vid_subtitle import add_subtitles, add_subtitle_file

# Add subtitles to a video using transcription
add_subtitles(
    input_video="input.mp4",
    output_video="output_with_subtitles.mp4",
    language="en"  # Optional, defaults to English
)

# Add existing subtitles to a video (no transcription needed)
add_subtitle_file(
    input_video="input.mp4",
    subtitle_file="existing_subtitles.srt",
    output_video="output_with_embedded_subtitles.mp4"
)

This will:

1. Extract audio from the input video
2. Transcribe the audio using OpenAI Whisper API
3. Generate an SRT subtitle file
4. Create a new video with embedded subtitless

CLI Usage

# Add subtitles with transcription
vid-subtitle add -l en -v input.mp4 output.mp4

# Embed existing subtitles into video
vid-subtitle embed input.mp4 subtitles.srt output.mp4

# Extract subtitles only (no video output)
vid-subtitle extract input.mp4 -o subtitles.srt

# Refine subtitles
vid-subtitle refine subtitles.srt refined_subtitles.srt -i "Refine the subtitles to be more accurate."

# Show supported languages
vid-subtitle languages

# Show library information
vid-subtitle info

Supported Languages

The library supports all languages supported by OpenAI Whisper API. Use ISO 639-1 language codes:

• en - English (default)
• es - Spanish
• fr - French
• de - German
• it - Italian
• pt - Portuguese
• ru - Russian
• ja - Japanese
• ko - Korean
• zh - Chinese
• And many more...

Supported Video Formats

• MP4 (.mp4)
• MOV (.mov)

Output Files

The library generates two outputs:

1. Video file with embedded subtitles: {output_video}
2. Separate SRT subtitle file: {input_video_name}.srt

Error Handling

The library includes comprehensive error handling for:

• Missing FFmpeg installation
• Invalid video formats
• Missing OpenAI API key
• Network connectivity issues
• File permission errors

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.