Metadata-Version: 2.4
Name: video-caption-ai
Version: 0.1.1
Summary: AI video subtitle transcription, refinement, and composition
Author: video-caption-ai contributors
License: MIT
Project-URL: Homepage, https://github.com/iamyb/video-caption-ai
Project-URL: Repository, https://github.com/iamyb/video-caption-ai
Project-URL: Issues, https://github.com/iamyb/video-caption-ai/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: faster-whisper
Requires-Dist: numpy
Requires-Dist: onnxruntime
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# video-caption-ai

video-caption-ai turns video audio into SRT subtitles with faster-whisper, optionally refines subtitles with an OpenAI-compatible AI service, and can mux or burn subtitles back into video.

## Features

- FFmpeg audio extraction
- faster-whisper transcription
- AI semantic segmentation
- AI transcript correction with validation and retries
- Optional TXT/Markdown reference transcript matching
- SmartSub-inspired timing and readability guards
- Soft subtitle muxing or hard subtitle burning
- Hard subtitle style presets: `classic`, `yellow`, `cinema`, `top`

## Requirements

- Python 3.10 or newer
- FFmpeg available as `ffmpeg` on PATH
- CPU or NVIDIA CUDA runtime as appropriate for faster-whisper

## Install

Install the published package from PyPI:

```powershell
python -m pip install video-caption-ai
```

Verify the installation:

```powershell
video-caption --help
```

To upgrade an existing installation:

```powershell
python -m pip install --upgrade video-caption-ai
```

FFmpeg must be installed separately and available on your PATH. Official
downloads are listed at [ffmpeg.org/download.html](https://ffmpeg.org/download.html).

### Windows

Using WinGet:

```powershell
winget install Gyan.FFmpeg.Shared
```

Or download a Windows build, extract it, and add its `bin` directory to PATH.
Open a new terminal after changing PATH, then verify:

```powershell
ffmpeg -version
```

### macOS

```bash
brew install ffmpeg
ffmpeg -version
```

### Ubuntu/Debian

```bash
sudo apt update
sudo apt install ffmpeg
ffmpeg -version
```

## Install for development

```powershell
python -m pip install -e ".[dev]"
```

The package provides the `video-caption` command. `video-subtitle` remains as a
compatibility alias. It can also be run with:

```powershell
python -m video_caption_ai --help
```

## Transcribe video

```powershell
video-caption input.mp4 output.srt --model small --language zh --device cpu --no-vad
```

Use a reference transcript without changing Whisper cue timing:

```powershell
video-caption input.mp4 output.srt `
  --model small --language zh --device cpu --no-vad `
  --reference-script reference.md
```

The reference file can be `.txt` or `.md`. Markdown headings, lists, links,
emphasis, and fenced code are cleaned before matching. If the text does not
match the ASR transcript reliably, the original ASR cue text is kept.

## AI refinement

The AI endpoint must expose an OpenAI-compatible `/chat/completions` endpoint.

```powershell
video-caption input.mp4 output.srt `
  --model small --language zh --device auto --no-vad `
  --ai-segmentation --ai-correction `
  --ai-base-url "http://192.168.0.41:9292/v1" `
  --ai-model "Qwen3.6-35b-A3B-UD-Q6_K_XL-MTP"
```

An API key is optional for local services.

## Compose an existing SRT

Soft subtitles, selectable in a compatible player:

```powershell
video-caption input.mp4 existing.srt --compose-only `
  --video-output subtitled.mkv --subtitle-mode soft
```

Hard subtitles burned into the picture:

```powershell
video-caption input.mp4 existing.srt --compose-only `
  --video-output subtitled.mp4 --subtitle-mode hard `
  --style-preset yellow
```

Override a preset when needed:

```powershell
video-caption input.mp4 existing.srt --compose-only `
  --video-output subtitled.mp4 --subtitle-mode hard `
  --style-preset yellow --font-size 56 --outline-width 4
```

## Python API

```python
from video_caption_ai import compose_video, transcribe_video

# CLI-oriented transcription entry point is available through video-caption.
# Video composition is also available as a Python function.
```

## Development checks

```powershell
python -m pytest
python -m video_caption_ai --help
python -m build
```

## License

MIT. See [LICENSE](LICENSE).

## Credits

video-caption-ai is an independent Python rewrite inspired by and based on the
subtitle transcription and refinement workflow of [SmartSub](https://github.com/buxuku/SmartSub).
It is not the official SmartSub distribution. The original SmartSub project is
licensed separately; see its repository for its license and attribution details.
