mirror of
https://github.com/vondas-network/videobeaux.git
synced 2025-12-05 15:30:02 +01:00
67 lines
2.9 KiB
Plaintext
67 lines
2.9 KiB
Plaintext
# videobeaux: captburn
|
||
|
||
## Description
|
||
`captburn` is a modular caption-generation and burn-in engine for videobeaux.
|
||
It ingests video and transcript data (JSON-based) and produces high-quality `.ass` subtitle files or directly burns captions into the video.
|
||
It supports multiple captioning modes — **pop-on**, **paint-on**, and **roll-up** — and preserves all ASS styling fields.
|
||
|
||
## Features
|
||
- Generates ASS subtitles from JSON transcripts or caption files.
|
||
- Supports `popon`, `painton`, and `rollup` timing modes.
|
||
- Full styling options: font, size, color, outline, background, alignment, margins, rotation.
|
||
- Generates both `.captburn.json` (metadata) and `.captburn.ass` (subtitle style) sidecars.
|
||
- Can reburn captions directly using `--caption` JSON without reprocessing.
|
||
- Threaded pipeline compatible with FFmpeg rendering.
|
||
|
||
## Parameters
|
||
| Flag | Type | Description |
|
||
|------|------|--------------|
|
||
| `-i, --input` | str | Input video file |
|
||
| `--json` | str | Path to transcript or caption JSON |
|
||
| `--caption` | str | (Optional) Caption JSON for reburn |
|
||
| `--rotate` | float | Rotation angle for text (ASS Angle tag) |
|
||
| `--font` | str | Font family (e.g. Arial, Helvetica) |
|
||
| `--font-size` | int | Text size |
|
||
| `--color` | str | Primary text color (hex or ASS color) |
|
||
| `--outline-color` | str | Outline color |
|
||
| `--back-color` | str | Background box color |
|
||
| `--back-opacity` | float | Background opacity (0.0–1.0) |
|
||
| `--align` | int | Alignment (ASS-style \\anN code) |
|
||
| `--margin-v` | int | Vertical margin in pixels |
|
||
| `--tracking` | float | Character spacing multiplier |
|
||
| `--rotate` | float | Rotation of the text block |
|
||
| `-F, --force` | flag | Overwrite existing files |
|
||
|
||
## Modes
|
||
| Mode | Description |
|
||
|------|--------------|
|
||
| `popon` | Sentence-level captions (common for subtitles) |
|
||
| `painton` | Word-by-word reveal effect |
|
||
| `rollup` | Scrolling line-by-line broadcast style |
|
||
|
||
## Example Usage
|
||
```bash
|
||
# Generate and burn captions using a transcript JSON
|
||
videobeaux -P captburn -i ./media/bbb.mov --json ./media/bbb.json -F
|
||
|
||
# Burn captions from an existing caption JSON (reburn mode)
|
||
videobeaux -P captburn -i ./media/bbb.mov --caption ./media/bbb.captburn.json -F
|
||
|
||
# Specify font, size, and color
|
||
videobeaux -P captburn -i ./media/bbb.mov --json ./media/bbb.json --font "Helvetica" --font-size 42 --color "#FFFFFF" --outline-color "#000000" --align 2 --margin-v 50 -F
|
||
|
||
# Apply rotation to text (e.g., stylized tilt)
|
||
videobeaux -P captburn -i ./media/bbb.mov --json ./media/bbb.json --rotate 5 -F
|
||
```
|
||
|
||
## Outputs
|
||
- `.captburn.ass`: Styled subtitle file
|
||
- `.captburn.json`: Caption metadata file
|
||
- `.mp4`: (if burn enabled) Video with captions baked in
|
||
|
||
## Notes
|
||
- Automatically detects video resolution for accurate ASS PlayResX/Y.
|
||
- Uses actual pixel-true coordinates and alignment.
|
||
- Fully compatible with reburn workflow using `--caption`.
|
||
- Built upon FFmpeg `subtitles` and `ass` filters for reliable rendering.
|