# Subtitle Automation
A CLI tool to generate Final Cut Pro compatible subtitle files from audio/video files using OpenAI's Whisper.
## Features
- **Multiple file format support**: MP3, MP4, WAV, M4A
- **Automatic audio extraction**: Extracts audio from MP4 video files
- **AI transcription**: Uses OpenAI Whisper for accurate speech-to-text
- **Final Cut Pro integration**: Generates FCPXML subtitle files compatible with Final Cut Pro
- **Multiple model sizes**: Choose from tiny, base, small, medium, or large Whisper models
- **Language support**: Auto-detect or specify language for better accuracy
- **Frame-accurate timing**: Generates subtitles with precise frame boundaries (30fps)
## Installation
This project uses `uv` for dependency management. Make sure you have Python 3.13+ installed.
```bash
# Clone the repository
git clone <repository-url>
cd subtitle_automation
# Install dependencies using uv
uv sync
```
## Usage
### Basic Usage
```bash
# Generate subtitles from an MP3 file
python subtitle_generator.py input.mp3
# Generate subtitles from an MP4 file (audio will be extracted)
python subtitle_generator.py input.mp4
```
### Advanced Options
```bash
# Specify output file
python subtitle_generator.py input.mp3 -o custom_subtitles.fcpxml
# Use a different Whisper model (higher quality but slower)
python subtitle_generator.py input.mp3 -m large
# Specify language for better accuracy
python subtitle_generator.py input.mp3 -l en
# Combine all options
python subtitle_generator.py input.mp4 -o subtitles.fcpxml -m medium -l ko
```
### Command Line Arguments
- `input_file`: Path to the input audio/video file (MP3, MP4, WAV, M4A)
- `-o, --output`: Output FCPXML file path (default: `input_filename.fcpxml`)
- `-m, --model`: Whisper model size - `tiny`, `base`, `small`, `medium`, `large` (default: `base`)
- `-l, --language`: Language code (e.g., 'en', 'es', 'fr', 'ko', 'ja'). Auto-detect if not specified
## Dependencies
- **openai-whisper**: AI transcription engine
- **moviepy**: Video/audio processing for MP4 files
- **Python 3.13+**: Required Python version
## Output Format
The tool generates FCPXML files that can be directly imported into Final Cut Pro as subtitle tracks. The generated subtitles include:
- Precise timing synchronized to 30fps frame boundaries
- XML-escaped text content
- Standard FCPXML 1.11 format structure
- Basic Title effect references for Final Cut Pro compatibility
## Technical Details
- **Frame Rate**: 30fps (1001/30000s per frame)
- **Audio Processing**: Temporary WAV files for MP4 audio extraction
- **Text Encoding**: UTF-8 with XML escaping
- **Timing Precision**: Frame-accurate subtitle positioning
## Examples
```bash
# Process a podcast MP3 file
python subtitle_generator.py podcast.mp3
# Process a video interview with Korean language
python subtitle_generator.py interview.mp4 -l ko -m medium
# Generate subtitles with high accuracy model
python subtitle_generator.py presentation.mp4 -m large -o presentation_subs.fcpxml
```
## License
This project is open source. Please check the license file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "fcpxml-subtitle-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "subtitle, whisper, final-cut-pro, transcription, video, audio",
"author": null,
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/86/7d/cfdbf93b26b7c86ac2aad8f2aab9b543fafa6f99e152db76ccaf22b6faba/fcpxml_subtitle_generator-0.1.0.tar.gz",
"platform": null,
"description": "# Subtitle Automation\n\nA CLI tool to generate Final Cut Pro compatible subtitle files from audio/video files using OpenAI's Whisper.\n\n## Features\n\n- **Multiple file format support**: MP3, MP4, WAV, M4A\n- **Automatic audio extraction**: Extracts audio from MP4 video files\n- **AI transcription**: Uses OpenAI Whisper for accurate speech-to-text\n- **Final Cut Pro integration**: Generates FCPXML subtitle files compatible with Final Cut Pro\n- **Multiple model sizes**: Choose from tiny, base, small, medium, or large Whisper models\n- **Language support**: Auto-detect or specify language for better accuracy\n- **Frame-accurate timing**: Generates subtitles with precise frame boundaries (30fps)\n\n## Installation\n\nThis project uses `uv` for dependency management. Make sure you have Python 3.13+ installed.\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd subtitle_automation\n\n# Install dependencies using uv\nuv sync\n```\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Generate subtitles from an MP3 file\npython subtitle_generator.py input.mp3\n\n# Generate subtitles from an MP4 file (audio will be extracted)\npython subtitle_generator.py input.mp4\n```\n\n### Advanced Options\n\n```bash\n# Specify output file\npython subtitle_generator.py input.mp3 -o custom_subtitles.fcpxml\n\n# Use a different Whisper model (higher quality but slower)\npython subtitle_generator.py input.mp3 -m large\n\n# Specify language for better accuracy\npython subtitle_generator.py input.mp3 -l en\n\n# Combine all options\npython subtitle_generator.py input.mp4 -o subtitles.fcpxml -m medium -l ko\n```\n\n### Command Line Arguments\n\n- `input_file`: Path to the input audio/video file (MP3, MP4, WAV, M4A)\n- `-o, --output`: Output FCPXML file path (default: `input_filename.fcpxml`)\n- `-m, --model`: Whisper model size - `tiny`, `base`, `small`, `medium`, `large` (default: `base`)\n- `-l, --language`: Language code (e.g., 'en', 'es', 'fr', 'ko', 'ja'). Auto-detect if not specified\n\n## Dependencies\n\n- **openai-whisper**: AI transcription engine\n- **moviepy**: Video/audio processing for MP4 files\n- **Python 3.13+**: Required Python version\n\n## Output Format\n\nThe tool generates FCPXML files that can be directly imported into Final Cut Pro as subtitle tracks. The generated subtitles include:\n\n- Precise timing synchronized to 30fps frame boundaries\n- XML-escaped text content\n- Standard FCPXML 1.11 format structure\n- Basic Title effect references for Final Cut Pro compatibility\n\n## Technical Details\n\n- **Frame Rate**: 30fps (1001/30000s per frame)\n- **Audio Processing**: Temporary WAV files for MP4 audio extraction\n- **Text Encoding**: UTF-8 with XML escaping\n- **Timing Precision**: Frame-accurate subtitle positioning\n\n## Examples\n\n```bash\n# Process a podcast MP3 file\npython subtitle_generator.py podcast.mp3\n\n# Process a video interview with Korean language\npython subtitle_generator.py interview.mp4 -l ko -m medium\n\n# Generate subtitles with high accuracy model\npython subtitle_generator.py presentation.mp4 -m large -o presentation_subs.fcpxml\n```\n\n## License\n\nThis project is open source. Please check the license file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI tool to generate Final Cut Pro compatible subtitle files from audio/video files using Whisper",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/yourusername/subtitle_automation",
"Issues": "https://github.com/yourusername/subtitle_automation/issues",
"Repository": "https://github.com/yourusername/subtitle_automation"
},
"split_keywords": [
"subtitle",
" whisper",
" final-cut-pro",
" transcription",
" video",
" audio"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "73846f8f9f714b7d42dc5288256ab005642c99312a4f4fca2dfd8cfdcbe126e7",
"md5": "50d18e686be3cfdf89edad22ef4493b6",
"sha256": "17d782adf70b423a27c61ac1dd7d4a0a716f4031d9a4e0eb2f9c193aac15b169"
},
"downloads": -1,
"filename": "fcpxml_subtitle_generator-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50d18e686be3cfdf89edad22ef4493b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 6241,
"upload_time": "2025-07-29T14:39:56",
"upload_time_iso_8601": "2025-07-29T14:39:56.976121Z",
"url": "https://files.pythonhosted.org/packages/73/84/6f8f9f714b7d42dc5288256ab005642c99312a4f4fca2dfd8cfdcbe126e7/fcpxml_subtitle_generator-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "867dcfdbf93b26b7c86ac2aad8f2aab9b543fafa6f99e152db76ccaf22b6faba",
"md5": "d638a0aaccac012a3c92f3b92d89b6bc",
"sha256": "7df0c6710b44d0e403a66365e205c5b72f6e534942d39f3c6caa93172ca92c7a"
},
"downloads": -1,
"filename": "fcpxml_subtitle_generator-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d638a0aaccac012a3c92f3b92d89b6bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 5608,
"upload_time": "2025-07-29T14:39:57",
"upload_time_iso_8601": "2025-07-29T14:39:57.972686Z",
"url": "https://files.pythonhosted.org/packages/86/7d/cfdbf93b26b7c86ac2aad8f2aab9b543fafa6f99e152db76ccaf22b6faba/fcpxml_subtitle_generator-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 14:39:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "subtitle_automation",
"github_not_found": true,
"lcname": "fcpxml-subtitle-generator"
}
JSON
