Build Timestamped Show Notes from a Video's Chapters

Timestamped show notes — a list of sections with the exact moment each one starts — come from combining two things Scriptube returns separately: the video's description (where chapter markers usually live as plain text) and the transcript's timed segments. Scriptube doesn't parse chapter markers into a structured field today, so this is a build-it-yourself step, not a one-call export. Here's exactly what's available now and how to assemble it.

What Scriptube gives you

Request metadata alongside the transcript:

curl "https://scriptube.me/api/v1/transcripts/{batch_id}?include_metadata=true&include_segments=true" \
  -H "X-API-Key: YOUR_API_KEY"

Two fields matter here:

• description — the video's full YouTube description as plain text. If the creator added chapters, they're in there as ordinary lines like 0:00 Intro and 4:32 Getting started — not as a separate structured list.
• Timed segments — every transcript's underlying {text, start, duration} objects, in seconds, available with ?include_segments=true. This is the same data SRT and VTT exports are built from.

Parsing chapter markers out of the description into a structured field isn't something the API does for you — the raw description (chapter lines included) is what you get back, via include_metadata or the description column in exports. See youtube-video-description-chapters-links for the current state of description/chapters/tags metadata generally. Building real show notes means a short parsing step on your end, covered next.

Step 1: Extract chapter markers from the description

Chapter timestamps follow a predictable pattern — a line starting with a timestamp, followed by a label:

import re

TIMESTAMP_LINE = re.compile(r'^(\d{1,2}(?::\d{2}){1,2})\s+(.+)$', re.MULTILINE)

def parse_chapters(description: str):
    chapters = []
    for match in TIMESTAMP_LINE.finditer(description):
        ts, label = match.groups()
        parts = [int(p) for p in ts.split(':')]
        seconds = parts[-1] + parts[-2] * 60 + (parts[-3] * 3600 if len(parts) == 3 else 0)
        chapters.append({"start_seconds": seconds, "label": label.strip()})
    return chapters

This is a heuristic, not a guarantee — not every creator formats chapters the same way, and a description that mentions an unrelated time ("we launched this in 2019, 14:32 UTC") can produce a false match. Sanity-check the output, especially the first entry: a real chapter list almost always starts at 0:00.

Step 2: Slice the transcript segments between chapter boundaries

Once you have ordered chapter start times, group the transcript's timed segments into each chapter's window:

def build_show_notes(chapters, segments):
    notes = []
    for i, chapter in enumerate(chapters):
        start = chapter["start_seconds"]
        end = chapters[i + 1]["start_seconds"] if i + 1 < len(chapters) else float("inf")
        text = " ".join(
            seg["text"] for seg in segments
            if start <= seg["start"] < end
        )
        notes.append({"label": chapter["label"], "start_seconds": start, "text": text})
    return notes

The result is a list of sections, each with a label, a start time, and the transcript text spoken during that window — real show notes, not a flat transcript with a chapter list pasted above it.

Step 3: Format for publishing

A simple rendering for a show notes page or video description reply:

for note in notes:
    minutes, seconds = divmod(note["start_seconds"], 60)
    print(f"{minutes}:{seconds:02d} — {note['label']}")
    print(note["text"][:200] + "...")
    print()

Link each timestamp back to the video with YouTube's &t= parameter (https://www.youtube.com/watch?v=VIDEO_ID&t=272s) so readers can jump straight to that section.

When there are no chapters at all

Not every video has them. If the description has no timestamp lines, fall back to building your own section breaks from the transcript directly — look for natural pauses (gaps between segment start times longer than a few seconds) as rough section boundaries, or just publish the full timestamped transcript and let readers use their browser's find function, covered in how-to-search-inside-youtube-video-transcripts.

Worked example end to end

Run the whole thing against a real video. Submit it, then pull metadata and segments together:

curl -X POST https://scriptube.me/api/v1/transcripts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"]}'

curl "https://scriptube.me/api/v1/transcripts/{batch_id}?include_metadata=true&include_segments=true" \
  -H "X-API-Key: YOUR_API_KEY"

Feed the resulting item's description into parse_chapters() and its segments into build_show_notes() from above. If the video has no chapter markers in its description — plenty of videos don't — parse_chapters returns an empty list, and build_show_notes returns nothing to iterate over; that's your signal to fall back to the no-chapters approach rather than publishing an empty notes section.

Sanity-checking the result

Before publishing, check two things: the last chapter's start_seconds should be comfortably less than the video's total duration_seconds (also available with include_metadata=true) — if it isn't, your regex probably matched something in the description that wasn't actually a chapter marker. And the chapter count should roughly match what you'd expect from skimming the video yourself; a show with eight visible segments producing three parsed chapters usually means the creator's timestamp formatting didn't match the pattern the regex expects (single-digit hours, non-standard separators, or a bullet character in front of each line), and the regex needs a small adjustment for that channel's style.

For podcasts specifically

This pattern is exactly what a podcast's show notes page needs if the show is published as a YouTube video with manual chapters. See youtube-transcripts-for-podcast-show-notes-complete-workflow for the full show-notes-specific workflow, and youtube-transcript-with-timestamps for every other way to get timed output (SRT, VTT, the dashboard view) if structured chapters aren't the goal and you just need timestamps somewhere in the output.

If you're repurposing the same video into a written article instead of notes, turn-youtube-video-into-blog-post covers that pipeline.

None of this needs anything beyond a standard batch export plus a short, reusable parsing script — once it's written, the same two functions work for every video that has description chapters.

Pull a transcript with segments to try this: /ui/signup.