BlogImplementation Guide

Chunk a YouTube Transcript for RAG, With Timestamps That Link Back

Turn a video link into timed transcript segments, merge them into chunks of a useful size, and keep a timestamp and deep link on each one so answers can cite the moment in the video.

On this page8 sections

You want users to ask questions about a video, or search inside a library of talks, lessons or podcasts. The retrieval part is ordinary RAG: split the text, embed it, store it, look it up. What's specific to video is the input. You need the transcript from a link, on a server that YouTube may block, and you want every chunk to remember where in the video it came from, so an answer can cite "12:34" and open the video at that moment.

This guide covers that part: get timed segments from a link, merge them into chunks of a sensible size, and attach the timestamp, a deep link and the source. The output is a list of records you can send to any embedding model and vector store.

Why not embed the caption lines directly

Transcripts arrive as short segments. Caption tracks give you one segment per on-screen line, often five to ten words; speech-to-text gives roughly one per sentence. Embedding each one separately makes retrieval worse: a five-word line carries too little meaning to match a question, and you end up storing thousands of vectors per hour of video.

Merging consecutive segments into chunks of about 150 to 300 words works better. Each chunk keeps the start of its first segment and the end of its last, so you lose no timing information.

Step 1: get the segments from a link

Send the link to Importly's /transcribe endpoint with "mode": "auto". It returns the video's captions when it has some and runs speech-to-text when it doesn't, and it works the same from a server, a worker or a CI job as from your laptop. The Python transcript guide has a complete get_transcript() with polling and error handling by code; this guide reuses it.

The part you need from the result is data.segments, times in seconds:

json
{
  "text": "All right, so here we are, in front of the elephants\n...",
  "source": "platform_captions",
  "language": "en",
  "duration": 19,
  "data": {
    "segments": [
      { "start": 1.2, "end": 3.36, "text": "All right, so here we are, in front of the elephants" },
      { "start": 5.318, "end": 7.974, "text": "the cool thing about these guys is that they have really..." },
      { "start": 7.974, "end": 12.616, "text": "really really long trunks" }
    ]
  }
}

The shape is the same for captions and speech-to-text, and for TikTok, X, Vimeo, podcasts and the other supported sites, so the chunker below doesn't care where the video came from.

Step 2: merge segments into chunks

Standard library only. It counts words rather than model tokens, which is close enough for sizing chunks and keeps the code independent of any one model:

python
# chunks.py
from urllib.parse import parse_qs, urlparse


def chunk_segments(segments, max_words=200, overlap=1):
    """Merge transcript segments into chunks of about max_words words.

    Each chunk keeps the start of its first segment and the end of its last,
    and repeats the last `overlap` segments of the previous chunk so a
    sentence cut at the boundary still appears whole in one of them.
    """
    chunks, current, words = [], [], 0
    for seg in segments:
        n = len(seg["text"].split())
        if current and words + n > max_words:
            chunks.append(_merge(current))
            carry = current[-overlap:] if overlap else []
            words = sum(len(s["text"].split()) for s in carry)
            # Skip the overlap when it wouldn't leave room for new text
            current, words = (carry, words) if words + n <= max_words else ([], 0)
        current.append(seg)
        words += n
    if current:
        chunks.append(_merge(current))
    return chunks


def _merge(segs):
    return {
        "text": " ".join(s["text"].strip() for s in segs),
        "start": segs[0]["start"],
        "end": segs[-1]["end"],
    }


def youtube_id(url):
    u = urlparse(url)
    if u.hostname == "youtu.be":
        return u.path.lstrip("/")
    if u.path.startswith("/shorts/"):
        return u.path.split("/")[2]
    return parse_qs(u.query).get("v", [None])[0]


def link_at(url, seconds):
    """A link that opens the video at `seconds` (YouTube), else the plain URL."""
    video_id = youtube_id(url)
    if not video_id:
        return url
    return f"https://www.youtube.com/watch?v={video_id}&t={int(seconds)}s"


def clock(seconds):
    m, s = divmod(int(seconds), 60)
    h, m = divmod(m, 60)
    return f"{h}:{m:02}:{s:02}" if h else f"{m}:{s:02}"

Run on the segments above with max_words=15, it returns:

json
[
  { "text": "All right, so here we are, in front of the elephants", "start": 1.2, "end": 3.36 },
  { "text": "the cool thing about these guys is that they have really... really really long trunks", "start": 5.318, "end": 12.616 }
]

A few choices worth knowing:

  • Overlap is in segments, not words. Repeating the last caption line of the previous chunk keeps a sentence that straddles the boundary findable, without cutting a line in half. Set overlap=0 if you'd rather not store the repeat.
  • One long segment is never split. Caption lines and speech-to-text sentences are usually far shorter than a chunk. If you do see oversized chunks, split long segments on sentence punctuation before chunking.
  • The timestamps stay honest. start is when the first line of the chunk begins, so a deep link lands just before the matching passage rather than after it.

Step 3: build records with a deep link

python
# records.py
from chunks import chunk_segments, clock, link_at
from transcript import get_transcript  # from the Python transcript guide


def video_chunks(url, title=None, max_words=200):
    result = get_transcript(url)
    records = []
    for i, chunk in enumerate(chunk_segments(result["data"]["segments"], max_words)):
        records.append({
            "id": f"{url}#{i}",
            "text": chunk["text"],
            "metadata": {
                "url": url,
                "title": title,
                "start": chunk["start"],
                "end": chunk["end"],
                "label": f"{clock(chunk['start'])}-{clock(chunk['end'])}",
                "link": link_at(url, chunk["start"]),
                "language": result["language"],
                "source": result["source"],
            },
        })
    return records

Each record looks like this:

json
{
  "id": "https://www.youtube.com/watch?v=jNQXAC9IVRw#1",
  "text": "the cool thing about these guys is that they have really... really really long trunks and that's cool",
  "metadata": {
    "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "title": "Me at the zoo",
    "start": 5.318,
    "end": 17.0,
    "label": "0:05-0:17",
    "link": "https://www.youtube.com/watch?v=jNQXAC9IVRw&t=5s",
    "language": "en",
    "source": "platform_captions"
  }
}

Embed text with whatever model you already use and store the record with its metadata in your vector store. At answer time, put the label next to each retrieved passage in the prompt and ask the model to cite it, then render link so the user can jump straight to the moment. For sites without a time parameter, link_at returns the plain URL and you can show the label on its own.

If you don't have the title already, POST /metadata/basic returns the title, duration and thumbnail for $0.003.

Doing this for many videos

Don't hold a web request open per video. Send each link to /transcribe with a webhookUrl, and run the chunk-and-embed step in the webhook handler; the transcript fields sit directly on data there (data.data.segments). See webhooks. Store the id so re-ingesting a video replaces its chunks instead of duplicating them.

Importly takes one link per request. It doesn't expand a channel or playlist into videos, so your app needs the list of video links itself.

What it costs

  • From captions, uploaded or auto-generated: $0.003 per video.
  • Speech-to-text, when a video has no captions: $0.01 per media minute, with a $0.01 minimum.
  • Chunking runs in your code, and embeddings are billed by whoever you use for them. maxCostDollars caps each transcript request, and failed transcriptions are refunded.

It's free to try, no card required. See pricing.

Have your coding agent wire it in

Connect https://mcp.importly.io/mcp to Claude Code, Cursor or another coding agent and ask it to add video transcripts to your RAG pipeline. It gets working code for your stack, writes the integration and tests real calls with your API key. The steps are in Have your agent build Importly into your app.

FAQ

What chunk size should I use for video transcripts?

About 200 words with one segment of overlap is a reasonable starting point. Then adjust from your own retrieval results: if answers miss context, go larger; if retrieved passages are mostly off-topic, go smaller.

Should I chunk by time instead of words?

Time windows (say, every 60 seconds) are simple, but speaking speed varies a lot between videos, so the amount of text per chunk does too. Counting words gives chunks of a steadier size, and the segment times still give you the timestamps.

Does Importly chunk or embed the transcript for me?

No. It returns the full text and timed segments; chunking and embeddings stay in your code, with the model and store you choose.

Does this work for videos without captions?

Yes. With "mode": "auto", speech-to-text runs when there are no captions, and the segments come back in the same shape, one per sentence.

Related: YouTube transcripts in Python, YouTube transcripts in Node.js, Best YouTube transcript API, Video to SRT subtitles, Podcast transcription API.

Keep reading

Put video and audio links to work in your app

One API for files, transcripts and metadata. Free to try, no card required.

Try free →