Automatic Chapter Generation for Podcasts Using Video Analysis API

The naive approach (and why it fails)

You could chunk a transcript every N minutes and call it a day — but arbitrary cuts land mid-sentence and ignore where topics actually change. Good chapters follow the content, which means you need to detect topic shifts, not clock ticks.

Step 1: Get a timestamped transcript

from supacrawlx import Client

client = Client(api_key="your_api_key")

t = client.youtube.transcript(
    url="https://youtu.be/your_episode",
    timestamps=True,
)

Step 2: Ask for structured chapters

The video analysis endpoint accepts a JSON schema, so you get back exactly the shape you want — no brittle string parsing:

schema = {
    "type": "object",
    "properties": {
        "chapters": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "start": {"type": "number"},
                    "title": {"type": "string"},
                },
                "required": ["start", "title"],
            },
        }
    },
}

analysis = client.video.analyze(
    url="https://youtu.be/your_episode",
    schema=schema,
    prompt="Identify topic changes and give each a short chapter title.",
)

Step 3: Format as chapter markers

YouTube chapters are just timestamps in the description, starting at 00:00:

def fmt(seconds: float) -> str:
    m, s = divmod(int(seconds), 60)
    h, m = divmod(m, 60)
    return f"{h:02d}:{m:02d}:{s:02d}" if h else f"{m:02d}:{s:02d}"

lines = [f"{fmt(c['start'])} {c['title']}" for c in analysis['chapters']]
print("\n".join(lines))

Always make sure the first chapter starts at 00:00 — YouTube silently ignores the whole chapter list if it doesn't.

Going further

• Generate an episode summary in the same analysis call to populate your show notes.
• Extract guest names and links for automatic credits.
• Run it as a post-publish webhook so every new episode is chaptered without manual work.