long-form-ingest

Long-Form Ingest

Extract three artifacts from a raw video:

1. transcript.json — word-level timestamps from faster-whisper
2. scenes.json — visual scene boundaries from PySceneDetect
3. meta.json — video technical metadata

All outputs go to ./out/<source-basename>/.

Workflow

# 1. Metadata
ffprobe -v quiet -print_format json -show_format -show_streams "$INPUT" > meta.json

# 2. Extract audio (mono 16kHz for Whisper)
ffmpeg -y -i "$INPUT" -ac 1 -ar 16000 -vn _staging/audio.wav

# 3. Transcribe with faster-whisper (word-level)
python scripts/transcribe.py _staging/audio.wav transcript.json

# 4. Scene detection (optional but cheap — skip for pure talking-head if user says --no-scenes)
python scripts/scenes.py "$INPUT" scenes.json

transcript.json schema

{
  "language": "en",
  "duration": 2534.12,
  "segments": [
    {
      "id": 0,
      "start": 0.32,
      "end": 8.74,
      "text": " So this one time I got a call from a founder who was convinced his SaaS was dying.",
      "words": [
        {"word": " So", "start": 0.32, "end": 0.48, "probability": 0.99},
        {"word": " this", "start": 0.48, "end": 0.63, "probability": 0.98},
        ...
      ]
    }
  ]
}

scenes.json schema

{
  "scenes": [
    {"start": 0.0, "end": 128.4, "type": "static"},
    {"start": 128.4, "end": 245.1, "type": "cut"}
  ]
}

scripts/transcribe.py

#!/usr/bin/env python3
import sys, json
from faster_whisper import WhisperModel

audio_path, out_path = sys.argv[1], sys.argv[2]

# large-v3 for quality. Use "medium" if GPU-poor.
model = WhisperModel("large-v3", device="auto", compute_type="auto",
                     download_root="~/.cache/whisper-models")

segments, info = model.transcribe(
    audio_path,
    word_timestamps=True,
    vad_filter=True,
    vad_parameters={"min_silence_duration_ms": 500}
)

out = {
    "language": info.language,
    "duration": info.duration,
    "segments": []
}

for i, seg in enumerate(segments):
    out["segments"].append({
        "id": i,
        "start": seg.start,
        "end": seg.end,
        "text": seg.text,
        "words": [
            {"word": w.word, "start": w.start, "end": w.end, "probability": w.probability}
            for w in (seg.words or [])
        ]
    })

with open(out_path, "w") as f:
    json.dump(out, f, indent=2)

print(f"Transcribed {info.duration:.1f}s in {len(out['segments'])} segments")