Prepare YouTube transcripts for RAG with source timestamps

Get one timestamped transcript

JSON is a text data format. It writes structured data as text. A cue index is a reader-assigned label for one original position in the segments array. Cue indices are not a promised Actor output field. Teaching tables use one-based positions. The first position is 1. Keep the original row untouched. Store these labels and their lineage on the working copy.

An Actor is a data collection program that runs online for you. A Task is a saved input setup for an Actor. You can follow this method without the Actor if you already have captions. If you still need captions, follow YouTube caption extraction. This page does not repeat that work.

The public collector checked on 13 October 2026 was Actor build 0.1.43. When a caption read succeeds, that build gives timestamped segments. A segment is one cue in the json. A later build can differ. The check date is the observation date. It is not a video publication date. The Actor page is the YouTube Transcript Scraper. The saved Task is YouTube Transcripts for RAG Pipelines.

Here is the boundary. Grain means what one row stands for. The Actor output grain is one successful unique video for each dataset row. A dataset row is one saved record. The reader-created chunk table grain is one row for each chunk. A chunk is not a dataset row. All chunk columns are reader-created. The Actor takes a direct video URL or a video ID you already know. It does not find videos for you. The Task returns json, text, and llm. Use json for citations. A citation is the video plus the time span for a claim. The llm result is llmText. llmText is text ready for a prompt. A prompt is the message you send a model. llmText does not replace segment times.

The Actor does not make chunks. It does not make embeddings. It does not build an index. An index is a stored structure for search. The Actor does not retrieve passages. It does not answer questions. It does not score answers. You clean, group, and test by hand.

Keep these source fields on the untouched row.

A track is one caption language version. Keep these fields on every segment.

If preferredLanguages is empty, the run selects an available caption track. Check transcriptLanguageCode. An empty list does not mean you chose the language. Set one language rule before you add a second video. Keep isAutoGenerated with the row. Automatic means the track is marked as machine-made. Machine captions can repeat lines. That mark alone does not prove the words are wrong.

Failed input details are in OUTPUT. Set includeFailedInputDetails so those details stay visible. A failed input is not a transcript with zero cues. Do not write 0 for an unknown time. A real cue can start at 0 seconds. Unknown and zero are not the same. scrapedAt is when you collected the row. It is not when the video was published.

One caption check does not prove the words match the speech. It does not prove the captions will remain later. The checked Task is only a start. It includes sample videos. Replace them with one public video you chose. The Task does not clean, group, or test.

Follow seven actions

Do the actions in order. If you group before you clean, a repeat can look like two facts. If you score before you write the questions, you may favor one grouping too early. Write the questions first. Then use those same questions on both groupings.

1. Save the raw collector row exactly as it arrived. Do not edit that row. Do not change the raw source. Make a working copy for cleaning and grouping. Store the reader-assigned original array-position labels on the working copy. Keep the video ID, the video URL, the language code, and scrapedAt. Keep status and isAutoGenerated.
2. Read cues that sit next to each other when their times overlap. The same words can be a rolling caption. A rolling caption writes one spoken line again in the next cue. Remove the extra cue only when the cues and the playback show one spoken event. Play that moment on a real video with YouTube caption-line seeking. The same words alone are not proof. Keep emphasis that was spoken again. Keep a repeated instruction. Do not delete every identical sentence in the video. Write the original cue numbers behind the change.
3. Put a claim with its condition. Put an example with the claim it serves. Put a contrast with the claim it limits. Keep a question with its answer. Prefer one complete short passage. Do not cut at a random second count. Do not cut at a random word count. You may split a very long passage at a real topic change. Then check that a needed limit was not left behind.
4. Make one row per chunk. The columns are chunk_id, source_video_id, source_url, language, start_seconds, end_seconds, original_cue_indices, text, and cleaned_text_version. start_seconds is the earliest cue start in the chunk. end_seconds is the latest cue end in the chunk. Call that pair the passage span. A passage span can cover silence or a gap. A gap does not mean each second was speech. If you overlap chunks for context, store that overlap. Count the repeated evidence one time.
5. Before any search, write three to five questions. Write a source-backed answer for each question. Mark every clause the answer needs. A clause is one needed part of the answer. A shared keyword is not enough. Include one question with no caption evidence.
6. Use the same questions on both groupings. Write the selected-chunk count before you look. Use that same count for both groupings. This taught example uses one chunk. Record the chunk ID you select. Record whether that chunk has the full answer and its conditions. Record whether the citation points at the right passage. A person can do this by reading. Do not claim an embedding search ran if you only read.
7. Keep the simplest grouping that still holds the needed context. It must also keep clear times. A shorter chunk is not better when a needed clause is gone. Do not report a general gain from a tiny set. If the source has no evidence, say it cannot answer. Do not fill the gap with a likely story.

Apply the actions to fictional cues

The cues in this section are fictional teaching text. VID-DEMO-01 is not a real YouTube ID. Do not search for it. The lines are English, so the language cell says en. A real row must copy transcriptLanguageCode from the source. There is no real URL and no publication date.

Cue 1 runs from 0 to 6 seconds. That 0 is a real start. It is not a fill-in for unknown. Cue 2 runs from 5 to 9 seconds. The two ranges overlap. The words match. Matching words still do not prove one spoken event. In this invented example, a playback check does prove it. Cue 2 repeats the same spoken line as cue 1. Remove cue 2 from the working text. Keep cue numbers 1 and 2 behind that change. Leave all six cues on the untouched source row.

Cue 6 is not the same event as cue 2. Cue 6 gives a reason to keep different versions. It stays. Do not wipe every repeated idea in the video.

Both groupings below use that working copy. The clean is shared. The comparison is about boundaries, not about two cleaning rules. cleaned_text_version is your own label. It is not an Actor field. Here the label is clean-1. Cue 2 stays in the cue-number list wherever its old span is covered. Its sentence is not typed again.

The time grouping cuts at the short cue edges.

T1 covers cue numbers 1, 2, and 3, from 0 to 15 seconds. Its cleaned text is: "Store documents by their source ID. Keep a version when the source changes."

T2 is cue 4, from 15 to 22 seconds. Its text is: "A new version is not a new source."

T3 is cue 5, from 22 to 29 seconds. Its text is: "Remove an exact repeated import only when the source ID and version match."

T4 is cue 6, from 29 to 36 seconds. Its text is: "Keep different versions because the text can change."

The meaning grouping keeps each claim with its limit. M1 is about what identifies a document and what a change means. M2 is about when a repeated import may be removed. That is a real topic change.

M1 covers cue numbers 1, 2, 3, and 4, from 0 to 22 seconds. Cue 2 is lineage only. The retained sentences are: "Store documents by their source ID. Keep a version when the source changes. A new version is not a new source."

M2 covers cue numbers 5 and 6, from 22 to 36 seconds. The retained sentences are: "Remove an exact repeated import only when the source ID and version match. Keep different versions because the text can change."

The 0 to 22 second span is a passage span. It uses the earliest start and the latest end. It does not mean speech filled every second. M1 ends at 22 seconds. M2 starts at 22 seconds. They share a boundary. They do not share a sentence. If you later overlap chunks on purpose, store that overlap. Count the repeated evidence once.

These two meaning rows are the chunk table that passes the fictional test below.

The time rows are the comparison set. They are not the selected table.

The questions were fixed before either grouping was judged. The selected-chunk count was fixed too. It is one chunk. The choice is manual. No embedding search ran. No database ran.

Question 1: What identifies a document, and what happens when it changes? The answer needs three clauses. The document is tied to a source ID. A change means you keep a version. A new version is not a new source.

Question 2: When may a repeated import be removed, and why keep other versions? The answer needs two clauses. Remove it only when the source ID and the version match. Keep other versions because the text can change.

Question 3: How many dollars does storage cost? No cue states a dollar cost. The source cannot answer.

The invented manual choice for question 1 is T1 on the time side and M1 on the meaning side. T1 has the source ID and the keep-version clause. T1 stops at 15 seconds, so it lacks cue 4. Without cue 4, a new version can be misread as a new document. That contrast is the condition. M1 keeps all three clauses. Cue 4 alone would also fail, because it lacks the source ID and the keep-version clause. No single time chunk holds all three. Joining T1 and T2 would put the clauses back together, but that is a two-chunk rule. This test does not use a two-chunk rule.

The invented manual choice for question 2 is T3 on the time side and M2 on the meaning side. T3 has the removal rule. It lacks the reason. The reason is that the text can change. Without that reason, the removal rule looks wider than the lesson. T4 has the reason and lacks the match rule. No single time chunk holds both clauses. M2 holds both.

Question 3 has no supporting clause in any chunk. A chunk that mentions storage still does not name a price. Both groupings must be marked unsupported. The reply says the source cannot answer.

Separate moments sit inside those citation ranges.

A score here is a count of passed checks. Complete support uses only answerable questions.

Complete support = answerable questions whose selected chunk holds every required clause / answerable questions

Time grouping = 0/2

Meaning grouping = 2/2

Abstention means you do not answer. The abstention count uses only the question with no caption evidence.

Abstention = correct refusals / unsupported questions = 1/1

Do not add 1/1 to the 2. The unsupported check is separate.

These fractions belong only to this invented manual comparison. They are not an embedding benchmark. A benchmark would be a measured test score. They are not a measured quality lift. A quality lift would be a proved gain on real searches. Do not infer a gain for other videos. On another video, a short time chunk might already hold every clause. Then the simpler passing grouping could be the time grouping.

A fictional reply should cite inside the retained span. A later reviewer checks the playback. VID-DEMO-01 has no real page, so the playback step is also fictional. On a real video, use YouTube caption-line seeking.

Fictional reply to question 1: "The source ID identifies the document. When the source changes, keep a version. A new version is not a new source." Citation: VID-DEMO-01, 0-22 seconds, cue numbers 1, 2, 3, and 4. The spoken clauses are cues 1, 3, and 4. Cue 2 is only the removal record.

Fictional reply to question 2: "Remove an exact repeated import only when the source ID and the version match. Keep different versions because the text can change." Citation: VID-DEMO-01, 22-36 seconds, cue numbers 5 and 6.

Fictional reply to question 3: "The source cannot answer. No cue states a storage cost in dollars." There is no citation span.

Under the one-chunk rule, the meaning grouping is the one that holds the needed context. Each answer fits in one chunk, and the times stay clear. The time grouping is shorter per chunk, but it drops a clause. For this invented case, keep M1 and M2. Do not treat that choice as a rule for every video. Run the same seven actions on your own file before you add more videos.