Metadata-Version: 2.2
Name: word-by-word-captions
Version: 1.0.0
Summary: Generate synchronized word-by-word captions for videos using WhisperX timestamps
Author: Xabi Ezpeleta
Project-URL: Homepage, https://github.com/xezpeleta/word-by-word-captions
Project-URL: Bug Tracker, https://github.com/xezpeleta/word-by-word-captions/issues
Keywords: captions,video,whisperx,subtitles
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: wheel; extra == "dev"

# Word-By-Word Captions (wbw-captions)

A Python tool to generate synchronized one-word captions for videos using word-level timestamps from WhisperX.

## Overview

WBW takes WhisperX's word-level timestamp JSON output and creates visually appealing videos with synchronized one-word captions.

The JSON file generated by [WhisperX](https://github.com/m-bain/whisperX) with the high-precision word-level timestamps is required as input.

## Installation

```bash
pip install word-by-word-captions
```

## Dependencies

- ffmpeg (for video processing)

## Usage

### 1. Generate Word-level Timestamps

First, use WhisperX to generate word-level timestamps for your audio/video:

```bash
# Install WhisperX
pip install git+https://github.com/m-bain/whisperX.git

# Generate word-level timestamps
whisperx <audio.wav> --hf_token <your-token> --vad_method silero --language <lang> --model <model> --align_model <align_model>
```

This will create a JSON file with precise word timings.

### 2. Create Captioned Video

```bash
# Add captions to an existing video
wbw-captions -v input_video.mp4 -j whisperx_output.json -o output.mp4
```

Options:
- `-v, --video`: Input video file (optional)
- `-j, --json`: WhisperX JSON output file (required)
- `-o, --output`: Output video file path (required)
- `--max_lines`: Maximum number of lines per subtitle (default: 1)
- `--max_line_chars`: Maximum characters per line (default: 40)

## Example Output

The tool creates videos where:
- Each word is highlighted in yellow as it's spoken
- Words are synchronized with precise timing from WhisperX
- Text is easily readable with proper contrast and outlines
- Captions are positioned at the bottom with proper margins

## Development

To set up the development environment:

1. Clone the repository
2. Install development dependencies:
   ```bash
   pip install -e ".[dev]"
   ```
3. Run tests:
   ```bash
   pytest
   ```

## License

MIT License
