ClipGen

ClipGen is a command-line tool for turning a long local video into:

• timestamped transcript cache
• candidate highlight clips
• chapter summaries
• a compact overall markdown summary

Requirements

• Python 3.10+
• ffmpeg installed and available on PATH
• OPENAI_API_KEY set in the environment

Optional:

• OPENAI_MODEL to override the default model

Recommended default model:

• gpt-4o-mini

You can put these in either:

• workspace root .env
• ClipGen/.env

Install

cd ClipGen
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Create a .env file from .env.example and set your API key.

Install ffmpeg separately and confirm:

ffmpeg -version

Usage

.\.venv\Scripts\python.exe -m ClipGen.main analyze "E:\videos\stream.mp4"

Common flags:

• --language auto|en|ja
• --out-dir out\my_run
• --highlight-count 15
• --min-clip-seconds 20
• --max-clip-seconds 90
• --model gpt-4o-mini
• --resume
• --whisper-model small

Output Files

By default, outputs are written to ClipGen\out\latest_run. Relative --out-dir values are resolved from the ClipGen project root.

• transcript.jsonl: raw transcript segments with start, end, text
• chunks.json: normalized analysis chunks
• chapters.json: chapter summaries with timestamps
• highlights.json: structured highlight candidates
• highlights.csv: spreadsheet-friendly highlight list
• highlights.md: human-readable review file
• analysis.json: combined structured output
• summary.md: overall markdown summary

Notes

• --resume reuses transcript.jsonl when it already exists.
• Missing ffmpeg or OPENAI_API_KEY will fail fast with a clear error.
• Whisper model cache is stored under ClipGen\.cache\ instead of the user profile.
• Transcription defaults to CPU mode for compatibility on machines without CUDA.
• The first version focuses on highlight discovery and summarization only.
• Translation, EDL/XML export, and editor integration are intentionally left for later.