# Use YouTube comment threads to find gaps in a tutorial

Match one viewer comment to the exact lesson passage before you change a tutorial. Read the public replies and the spoken lesson. Watch the picture too. Then record what you found. The lesson may leave out an explanation. The lesson may already explain the point. Or the checked facts may be too thin to judge.

A lesson gap is a missing explanation, unclear wording, or a setup that does not match the lesson. A lesson-gap map is a set of rows. Each row ties one comment to the lesson, a decision, and a test.

Use the [YouTube Comments Scraper](https://apify.com/chronometrica/youtube-comments-scraper) Actor to collect public comments. An Actor is a hosted program that collects source rows. A Task is a saved input preset. The public [video comment analysis Task](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis) is only a starting input. It is not proof that the check runs by itself. The Actor does not judge the lesson. You do that work.

These limits match the public builds checked on 2026-10-13. Later builds can change. Read the run output for the copy you use.

## Collect a bounded comment sample

Public comments build 1.1.6 accepts a known public video address or video id. You may send 1 to 100 addresses in `startUrls`. Set `maxCommentsPerVideo` from 1 to 1,000. That number is the cap. The cap is the most top-level comments you ask for. A top-level comment is a comment that is not a reply. Set `commentSortMode` to `top`, `newest`, or `both`. Top means the comments YouTube ranks first. Newest means the latest comments. Set `includeReplies` on or off. When replies are on, `maxRepliesPerComment` accepts 1 to 100. A reply is a response under a top-level comment. Reply rows are extra. They do not use up the top-level cap.

The saved Task still has a sample song video, a cap of 250, replies on, and up to 10 replies. Replace that sample before you judge a tutorial.

```json
{
  "startUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
  "maxCommentsPerVideo": 250,
  "commentSortMode": "both",
  "includeReplies": true,
  "maxRepliesPerComment": 10
}
```

Collect a bounded comment sample

For the first check, use one tutorial you already know is public. Set the cap to 2. Set `commentSortMode` to `both`. Set `includeReplies` to false. Leave the old reply cap out.

```json
{
  "startUrls": ["https://www.youtube.com/watch?v=YOUR_TUTORIAL"],
  "maxCommentsPerVideo": 2,
  "commentSortMode": "both",
  "includeReplies": false
}
```

Collect a bounded comment sample

A separate small control used one educational video, a cap of 2, and both sort modes. It wrote two top-level comments that had text. One row was Top. One row was Newest. Each row had a `commentId`. `publishedAt` was null. OUTPUT showed `commentsWritten` 2 and `repliesWritten` 0. `stopReasonCounts` included `requested_comment_limit_reached`. Do not look for one single `stopReason` field.

`commentsWritten` 2 means two comment rows were saved. `repliesWritten` 0 means zero reply rows were saved. That zero is a count for that run. `publishedAt` null means the date was not given. Unknown is not zero. Do not store a blank date as 0.

That control does not prove reply export. The acceptance test did not cover automatic replies. This method does not treat the file as a rebuilt thread. When a reply can change the meaning, open the public watch page and read it. If a reply is not there, leave it missing. Do not invent the words.

Keep the [source order and the cap](/en/articles/youtube-comment-sampling/) in your notes. The cap chooses a small sample. It does not rank the largest lesson problem. Your video can return a different mix than one Top row and one Newest row.

Each comment row should carry these fields:

| Field | What it means |
| --- | --- |
| `videoId` | The video's public id |
| `videoUrl` | The public video link |
| `commentId` | The comment's public id |
| `sortMode` | Top or Newest for that row |
| `text` | The comment words |
| `authorChannelId` | The author's public channel id, when the source gives it |
| `publishedTimeText` | The time words shown with the comment, when present |
| `publishedAt` | A date-time. Null means unknown, not zero |
| `scrapedAt` | When the row was collected |
| `status` | The row result |

If an input was not available, OUTPUT says so. Read `status` before you judge a row. If the text is missing, keep that row apart. Do not fill in words. If `authorChannelId` is missing, the author is unknown. Do not invent a person. A missing author is not zero viewers.

A comment count is not a count of learners. It is not a score of how well people understood. If no comments are written, `commentsWritten` is 0. That zero means you have no comment sample. It does not mean viewers understood the lesson. Do not turn the sample into a mood score.

## Collect timed captions for the same tutorial

Public transcript build 0.1.43 accepts known `startUrls`, `preferredLanguages`, and `outputFormats`. Use the same one tutorial you used for comments. Replace the whole `startUrls` list. Do not leave the song sample in the list. Ask for `json` when you need timed segments. A segment is one timed caption piece.

```json
{
  "startUrls": ["https://www.youtube.com/watch?v=YOUR_TUTORIAL"],
  "preferredLanguages": ["en"],
  "outputFormats": ["json"]
}
```

Collect timed captions for the same tutorial

`preferredLanguages` is a preference. The example uses `en` for English. Change it if you prefer another caption language. This field does not translate the lesson.

A transcript control for the same educational video succeeded. It returned a nonempty English manual track and timed segments. A manual track is a caption file a person prepared. The control shows that this build can return caption text and timing when a track exists. It does not show that your video has captions. This article does not copy the real caption words.

Use the public segment fields `startSeconds`, `endSeconds`, `durationSeconds`, and `text`. Read `endSeconds` from the segment. If `durationSeconds` is present, add `startSeconds` and `durationSeconds`. The sum should cover the same span as `endSeconds`. If `durationSeconds` is missing, leave it unknown. Do not write zero.

Captions can be wrong. Captions can skip a diagram or a silent action. A missing caption is not proof that the picture lacks the point. If the track is missing, watch and listen. Do not invent caption text. The transcript Actor does not read comments. It does not assign lesson-gap labels. It does not prove that a learner failed to understand.

## Do the check in eight steps

1. Name the lesson result before you collect comments. Write the concept in one plain line. Write what the learner should be able to do after the lesson. Choose one public tutorial. Declare the cap before you read the comments. For the first check, the cap is 2. Stay inside the viewer's words. Do not guess age, skill, or motive.
2. Check the sample before you interpret it. Confirm the video id, each `commentId`, and that `text` is usable. Read OUTPUT, including `commentsWritten`, `repliesWritten`, and `stopReasonCounts`. Keep the source order and the cap visible in your notes. Mark a missing author or a null `publishedAt` as unknown. Do not convert unknown into zero. Two rows are two comments in the sample. They are not two learners, and they are not a class score.
3. Choose one comment with a concrete task or a concrete confusion. Keep the source link. Quote only the words you need for your own notes. Write a plain reading that adds no cause. A question is not, on its own, a misunderstanding. A joke, a disagreement, or repeated wording is not, on its own, a misunderstanding. Before you judge the lesson, label the note `stated_confusion`, `possible_gap`, or `insufficient_context`. `stated_confusion` means the comment names a concrete task or question. `possible_gap` means the words might point to a lesson problem, but you have not checked the passage. `insufficient_context` means the comment lacks a fact you need.
4. Read the public thread when replies can change the meaning. Open the video page and read the replies under that comment. A reply can name the viewer's setup. A reply can show that the trouble came from a different product. Record what you checked. Record what you could not open. The small control saved no replies. Do not describe the export as a full thread. If you cannot find a reply, say the reply context is unavailable. Do not write a reply that you did not read.
5. Find the lesson passage on the video timeline. Use the timed captions to [find a candidate interval](/en/articles/youtube-concept-navigation-notes/). Then play that interval. Record the in-time and out-time in video seconds. Record the concept, the earlier line that matters, and the visible action. Watch and listen before you decide. A line missing from the captions can still be clear in a diagram. A caption word does not prove the spoken line is clear or correct. Use the video clock. Do not use the time on your wall clock.
6. Compare the comment with the checked lesson. First ask three questions. Did the lesson leave the explanation out? Did the lesson already state the point? Or is a needed fact still missing? Then save one state. Evidence is the comment, the replies you opened, and the passage you watched. `explanation_missing` means the passage does not teach the point the viewer asked about. `explanation_present_question_unresolved` means the passage states the point, and nothing you checked shows that this viewer missed it. A later question does not prove a miss. Do not say the teacher failed. Use this state unless a checked reply shows the miss. `possible_wording_gap` means the lesson shows the point, but the words never contrast the viewer's mistake. `setup_mismatch` means the comment is about a different setup, product, or model. `unresolved` means a needed fact was not checked, so you do not name a cause. Save the evidence next to the state. One confusion comment cannot show that every viewer had the same problem.
7. Write one change only when the evidence supports a lesson edit. You might add a prerequisite, show one worked step, name the unit, slow a jump, or place a short recap beside that passage. A prerequisite is a fact the learner needs first. State what should become clearer. State the test. Do not promise that people will stay longer. Do not promise more views. Change the explanation at that passage. A menu change, or a summary of the whole video, is a different task. If the state is `unresolved` or `setup_mismatch`, do not force an edit to this lesson.
8. Save one lesson-gap row that a second person can audit. Include the comment and thread source, the context you checked, the passage time, the intended concept, the state, the proposed change, and the acceptance check. An acceptance check is a test that shows the change did the job, or that no change was justified. A second person should open the same sources and follow the decision. If context is missing, keep the row `unresolved`. Do not invent a precise cause.

## Study one fictional lesson-gap map

The garden lesson, comments, replies, and times in this section are original fiction. They are a teaching example. They are not Actor output, and they are not a product result.

The fictional lesson teaches one skill. The learner measures a tray and uses one unit. The made-up caption segments are:

```json
[
  {
    "startSeconds": 20,
    "endSeconds": 28,
    "durationSeconds": 8,
    "text": "Measure the width inside the tray edges"
  },
  {
    "startSeconds": 28,
    "endSeconds": 33,
    "durationSeconds": 5,
    "text": "Use centimeters for both dimensions."
  }
]
```

Study one fictional lesson-gap map

Check the first span in plain addition. 20 plus 8 equals 28. That matches `endSeconds`. Check the second span. 28 plus 5 equals 33. That matches `endSeconds`. These sums only confirm the fictional timing. They do not judge the lesson.

The caption text does not mention a ruler. In the story, you play 20–28 seconds and watch the picture. A ruler starts at the inner left edge. You know that only because you watched. The missing ruler words do not mean the picture is blank. The caption words also do not prove the spoken line is enough.

The outer lip is the outside rim of the tray. The lesson shows the inside edges. It never says that the outer lip is excluded.

| Comment | Concept | Checked thread | Checked lesson passage | State | Proposed change | Acceptance check |
| --- | --- | --- | --- | --- | --- | --- |
| C1 on the fictional garden tutorial. Comment text: "Should I measure outside the tray?" | Measure width on the inside edges. | You opened the thread. The reply says the viewer measured the outer lip. | 20–28 seconds. Spoken line: "Measure the width inside the tray edges." The ruler starts at the inner left edge. No spoken contrast with the outer lip. | `possible_wording_gap` | At 20 seconds, show both edges, mark the inside edge, and say the outside lip is excluded. | A reviewer can name the exact start edge and end edge from the new passage alone, without the comment thread. |
| C2 on the fictional garden tutorial. Comment text: "Can I mix inches and centimeters?" | Use one unit for both dimensions. | No checked reply says this viewer missed the unit line. | 28–33 seconds. Spoken line: "Use centimeters for both dimensions." | `explanation_present_question_unresolved` | Optional only: add a visible unit label or a short recap beside 28 seconds. Keep the original sentence. Do not rewrite the lesson as if the rule were absent. | A reviewer can still find the original unit sentence at 28–33 seconds. The question alone is not counted as a missed explanation. |
| C3 on the fictional garden tutorial. Comment text: "The button is missing." | Find a button. The comment gives no device or version. | No reply was available to check. Device and version stay unknown. | Unavailable. No passage time is known. Do not invent one. | `unresolved` | No lesson edit. | The row stays unresolved. A reviewer does not add a device, a version, a cause, or a passage time. |
| C4 on the fictional garden tutorial. The comment asks about a different product model. | Steps for the model taught in this video. | You opened the thread. The reply confirms the comment is about a different model. | The current lesson is not used as the cause. No passage time is assigned. | `setup_mismatch` | No edit to this lesson. Note that the comment names another model. | A reviewer can see the other model in the checked reply and leaves this lesson's steps unchanged. |

C1 starts as `stated_confusion` because it asks a concrete measuring question. The passage already says to measure inside the tray edges. The picture agrees, because the ruler starts on the inner left edge. The explanation is not absent, so the state is not `explanation_missing`. The checked reply says the viewer used the outer lip. The lesson never contrasts that lip with the inside edge. The fit is `possible_wording_gap`. The reply does not show why the viewer chose the lip. Do not invent a motive. The change is a direct contrast at 20 seconds. The test uses the new picture and the new sentence only.

C2 also starts as `stated_confusion`. The 28–33 second line already gives the rule: use centimeters for both dimensions. Nothing in the checked thread shows that this viewer missed that line. A question after a clear line is not proof of a miss. The state is `explanation_present_question_unresolved`. A unit label may help a later viewer see the rule. It is optional. It must not replace the original sentence or pretend the rule was missing.

C3 is `insufficient_context` before you look for a passage. "The button is missing" gives no device and no version. No reply adds those facts. You cannot choose a video time. You cannot name a cause. Unknown context stays unknown. The state remains `unresolved`, and the acceptance check forbids a forced edit.

C4 starts as a concrete question, so you can mark `stated_confusion` before the thread check. The checked reply says the model is not the model in this lesson. That moves the state to `setup_mismatch`. Do not invent a fault in the current passage. Do not change this lesson to answer a different model.

Count the rows in this story. One row is `possible_wording_gap`. One row is `explanation_present_question_unresolved`. One row is `unresolved`. One row is `setup_mismatch`. That is four comment rows. A row is not one proved person. The story does not say how many people watched. It does not say that every viewer shared a problem. Caption times only help you find the passage. They do not replace watching and listening.

## Next action

Pick one comment that states a concrete confusion. Play that video moment and watch the picture, not only the caption text. Save one proposed change and a test a second person can repeat. Get the comment rows from the [YouTube Comments Scraper](https://apify.com/chronometrica/youtube-comments-scraper) Actor. Put your own tutorial in the [video comment analysis Task](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis). The Actor only collects rows. You still judge the passage.

## Sources

- [YouTube Comments Scraper Actor](https://apify.com/chronometrica/youtube-comments-scraper)
- [Video comment analysis Task](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis)
- [Timestamped transcript Task](https://apify.com/chronometrica/youtube-transcript-scraper/examples/youtube-timestamped-transcript-json)
- [How do you analyze your YouTube audience](https://www.reddit.com/r/YouTubeCreators/comments/1tdvbvx/how_do_you_analyze_your_youtube_audience_across/)