# Use as conversas nos comentários do YouTube para encontrar lacunas em um tutorial

Relacione um comentário de um espectador ao trecho exato da aula antes de mudar um tutorial. Leia as respostas públicas e ouça a explicação falada na aula. Veja também as imagens. Depois, registre o que encontrou. Pode faltar uma explicação na aula. A aula pode já explicar o ponto. Ou os fatos verificados podem ser insuficientes para avaliar.

Uma lacuna na aula é uma explicação ausente, uma formulação pouco clara ou uma configuração que não corresponde à aula. Um mapa de lacunas da aula é um conjunto de linhas. Cada linha relaciona um comentário à aula, a uma decisão e a um teste.

Use o Actor [YouTube Comments Scraper](https://apify.com/chronometrica/youtube-comments-scraper) para coletar comentários públicos. Um Actor é um programa hospedado que coleta linhas de dados da fonte. Uma Task é uma configuração de entrada salva. A [Task pública de análise de comentários de vídeo](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis) é apenas uma configuração de entrada inicial. Ela não comprova que a verificação ocorre por conta própria. O Actor não avalia a aula. Você faz esse trabalho.

Esses limites correspondem às versões públicas verificadas em 2026-10-13. Versões posteriores podem mudar. Leia a saída da execução da versão que você usar.

## Colete uma amostra limitada de comentários

A versão pública 1.1.6 do coletor de comentários aceita um endereço conhecido de vídeo público ou um identificador de vídeo. Você pode enviar de 1 a 100 endereços em `startUrls`. Defina `maxCommentsPerVideo` entre 1 e 1.000. Esse número é o limite. O limite é a quantidade máxima de comentários de nível superior que você solicita. Um comentário de nível superior é um comentário que não é uma resposta. Defina `commentSortMode` como `top`, `newest` ou `both`. Top corresponde aos comentários que o YouTube coloca primeiro. Newest corresponde aos comentários mais recentes. Ative ou desative `includeReplies`. Com as respostas ativadas, `maxRepliesPerComment` aceita de 1 a 100. Uma resposta fica abaixo de um comentário de nível superior. As linhas de respostas são adicionais. Elas não consomem o limite de comentários de nível superior.

A Task salva ainda tem um vídeo de música como exemplo, limite de 250, respostas ativadas e até 10 respostas. Substitua esse exemplo antes de avaliar um tutorial.

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

Colete uma amostra limitada de comentários

Para a primeira verificação, use um tutorial que você já sabe que é público. Defina o limite como 2. Defina `commentSortMode` como `both`. Defina `includeReplies` como false. Não inclua o limite anterior de respostas.

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

Colete uma amostra limitada de comentários

Um pequeno teste de controle separado usou um vídeo educativo, limite de 2 e os dois modos de ordenação. Ele gravou 2 comentários de nível superior que continham texto. Uma linha era Top. Uma linha era Newest. Cada linha tinha um `commentId`. `publishedAt` era null. OUTPUT mostrou `commentsWritten` 2 e `repliesWritten` 0. `stopReasonCounts` incluía `requested_comment_limit_reached`. Não procure um único campo `stopReason`.

`commentsWritten` 2 significa que 2 linhas de comentários foram salvas. `repliesWritten` 0 significa que 0 linhas de respostas foram salvas. Esse zero é uma contagem daquela execução. `publishedAt` null significa que a data não foi fornecida. Um valor desconhecido não é zero. Não armazene uma data em branco como 0.

Esse teste de controle não comprova a exportação de respostas. O teste de aceitação não abrangeu respostas automáticas. Este método não trata o arquivo como uma conversa reconstruída. Quando uma resposta puder mudar o sentido, abra a página pública do vídeo e leia a resposta. Se uma resposta não estiver lá, mantenha essa ausência. Não invente o texto.

Mantenha a [ordem da fonte e o limite](/pt-BR/articles/amostragem-de-comentarios-do-youtube/) nas suas anotações. O limite seleciona uma amostra pequena. Ele não classifica qual é o maior problema da aula. Seu vídeo pode retornar uma combinação diferente de uma linha Top e uma linha Newest.

Cada linha de comentário deve conter estes campos:

| Campo | O que significa |
| --- | --- |
| `videoId` | O identificador público do vídeo |
| `videoUrl` | O link público do vídeo |
| `commentId` | O identificador público do comentário |
| `sortMode` | Top ou Newest para aquela linha |
| `text` | O texto do comentário |
| `authorChannelId` | O identificador público do canal do autor, quando a fonte o fornece |
| `publishedTimeText` | O texto sobre o tempo de publicação exibido com o comentário, quando presente |
| `publishedAt` | Uma data e hora. null significa desconhecido, não zero |
| `scrapedAt` | Quando a linha foi coletada |
| `status` | O resultado da linha |

Se uma entrada não estava disponível, OUTPUT informa isso. Leia `status` antes de avaliar uma linha. Se o texto estiver ausente, mantenha essa linha separada. Não preencha o texto por conta própria. Se `authorChannelId` estiver ausente, o autor é desconhecido. Não invente uma pessoa. Um autor ausente não significa zero espectadores.

Uma contagem de comentários não é uma contagem de alunos. Ela não mede o quanto as pessoas entenderam. Se nenhum comentário for gravado, `commentsWritten` será 0. Esse zero significa que você não tem uma amostra de comentários. Não significa que os espectadores entenderam a aula. Não transforme a amostra em uma pontuação de sentimento.

## Colete legendas com marcações de tempo para o mesmo tutorial

A versão pública 0.1.43 do coletor de transcrições aceita `startUrls` conhecidos, `preferredLanguages` e `outputFormats`. Use o mesmo tutorial que usou para os comentários. Substitua toda a lista `startUrls`. Não deixe o vídeo de música de exemplo na lista. Solicite `json` quando precisar de segmentos com marcações de tempo. Um segmento é um trecho de legenda com marcação de tempo.

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

Colete legendas com marcações de tempo para o mesmo tutorial

`preferredLanguages` é uma preferência. O exemplo usa `en` para inglês. Altere esse valor se preferir outro idioma de legenda. Esse campo não traduz a aula.

Um teste de controle de transcrição para o mesmo vídeo educativo foi bem-sucedido. Ele retornou uma faixa de legendas manuais em inglês com conteúdo e segmentos com marcações de tempo. Uma faixa manual é um arquivo de legendas preparado por uma pessoa. O teste de controle mostra que essa versão pode retornar o texto das legendas e suas marcações de tempo quando existe uma faixa. Ele não demonstra que seu vídeo tem legendas. Este artigo não copia o texto das legendas reais.

Use os campos públicos dos segmentos: `startSeconds`, `endSeconds`, `durationSeconds` e `text`. Leia `endSeconds` no segmento. Se `durationSeconds` estiver presente, some `startSeconds` e `durationSeconds`. A soma deve corresponder ao mesmo intervalo indicado por `endSeconds`. Se `durationSeconds` estiver ausente, mantenha o valor como desconhecido. Não registre zero.

As legendas podem estar erradas. Elas podem omitir um diagrama ou uma ação sem fala. Uma legenda ausente não comprova que a imagem deixa de mostrar o ponto. Se a faixa estiver ausente, assista e ouça. Não invente o texto das legendas. O Actor de transcrição não lê comentários. Ele não atribui rótulos de lacunas da aula. Ele não comprova que um aluno deixou de entender.

## Faça a verificação em 8 etapas

1. Defina o resultado da aula antes de coletar comentários. Escreva o conceito em uma frase simples. Escreva o que o aluno deve ser capaz de fazer após a aula. Escolha um tutorial público. Declare o limite antes de ler os comentários. Para a primeira verificação, o limite é 2. Atenha-se ao que o espectador escreveu. Não suponha idade, habilidade ou motivo.
2. Verifique a amostra antes de interpretá-la. Confirme o identificador do vídeo, cada `commentId` e se `text` pode ser usado. Leia OUTPUT, incluindo `commentsWritten`, `repliesWritten` e `stopReasonCounts`. Mantenha a ordem da fonte e o limite visíveis nas suas anotações. Marque um autor ausente ou um `publishedAt` null como desconhecido. Não converta um valor desconhecido em zero. 2 linhas são 2 comentários na amostra. Elas não são 2 alunos nem uma nota da turma.
3. Escolha um comentário que apresente uma tarefa concreta ou uma dúvida específica. Mantenha o link da fonte. Cite apenas as palavras de que precisa nas suas próprias anotações. Escreva uma interpretação simples que não acrescente uma causa. Uma pergunta, por si só, não indica falta de compreensão. Uma piada, uma discordância ou uma formulação repetida, por si só, não indicam falta de compreensão. Antes de avaliar a aula, atribua à anotação o rótulo `stated_confusion`, `possible_gap` ou `insufficient_context`. `stated_confusion` significa que o comentário apresenta uma tarefa ou pergunta concreta. `possible_gap` significa que o texto pode indicar um problema na aula, mas você ainda não verificou o trecho. `insufficient_context` significa que falta no comentário um fato necessário.
4. Leia a conversa pública quando as respostas puderem mudar o sentido. Abra a página do vídeo e leia as respostas abaixo daquele comentário. Uma resposta pode informar a configuração usada pelo espectador. Uma resposta pode mostrar que o problema veio de outro produto. Registre o que você verificou. Registre o que não conseguiu abrir. O pequeno teste de controle não salvou respostas. Não descreva a exportação como uma conversa completa. Se não conseguir encontrar uma resposta, informe que o contexto das respostas está indisponível. Não escreva uma resposta que você não leu.
5. Encontre o trecho da aula na linha do tempo do vídeo. Use as legendas com marcações de tempo para [encontrar um possível intervalo](/pt-BR/articles/como-encontrar-um-conceito-em-uma-aula-longa-no-youtube/). Depois, reproduza esse intervalo. Registre o tempo inicial e o tempo final em segundos do vídeo. Registre o conceito, a fala anterior relevante e a ação visível. Assista e ouça antes de decidir. Uma explicação ausente das legendas ainda pode estar clara em um diagrama. Uma palavra na legenda não comprova que a fala é clara ou correta. Use o contador de tempo do vídeo. Não use a hora do relógio de parede.
6. Compare o comentário com a aula verificada. Primeiro, faça 3 perguntas. A aula deixou de apresentar a explicação? A aula já apresentou o ponto? Ou ainda falta um fato necessário? Depois, registre um estado. As evidências são o comentário, as respostas que você abriu e o trecho a que assistiu. `explanation_missing` significa que o trecho não ensina o ponto sobre o qual o espectador perguntou. `explanation_present_question_unresolved` significa que o trecho apresenta o ponto e nada do que você verificou mostra que esse espectador deixou de entendê-lo. Uma pergunta posterior não comprova falta de compreensão. Não diga que o professor falhou. Use esse estado, a menos que uma resposta verificada mostre a falta de compreensão. `possible_wording_gap` significa que a aula mostra o ponto, mas o texto falado nunca o contrapõe ao erro do espectador. `setup_mismatch` significa que o comentário trata de outra configuração, produto ou modelo. `unresolved` significa que um fato necessário não foi verificado, portanto você não aponta uma causa. Salve as evidências ao lado do estado. Um comentário com uma dúvida não pode mostrar que todos os espectadores tiveram o mesmo problema.
7. Escreva uma única mudança somente quando as evidências sustentarem uma edição da aula. Você pode acrescentar um pré-requisito, mostrar uma etapa resolvida passo a passo, indicar a unidade, explicar uma transição com mais calma ou colocar uma breve recapitulação junto daquele trecho. Um pré-requisito é um fato que o aluno precisa saber antes. Declare o que deve ficar mais claro. Declare o teste. Não prometa que as pessoas assistirão por mais tempo. Não prometa mais visualizações. Mude a explicação naquele trecho. Mudar um menu ou resumir o vídeo inteiro é outra tarefa. Se o estado for `unresolved` ou `setup_mismatch`, não force uma edição nesta aula.
8. Salve uma linha do mapa de lacunas da aula que outra pessoa possa auditar. Inclua a fonte do comentário e das respostas, o contexto verificado, o tempo do trecho, o conceito pretendido, o estado, a mudança proposta e a verificação de aceitação. Uma verificação de aceitação é um teste que mostra que a mudança cumpriu seu objetivo ou que nenhuma mudança se justificava. Outra pessoa deve conseguir abrir as mesmas fontes e acompanhar a decisão. Se faltar contexto, mantenha a linha como `unresolved`. Não invente uma causa precisa.

## Estude um mapa fictício de lacunas da aula

A aula de jardinagem, os comentários, as respostas e os tempos desta seção são uma ficção original. Eles formam um exemplo didático. Não são saída de um Actor nem resultado de um produto.

A aula fictícia ensina uma habilidade. O aluno mede uma bandeja e usa uma única unidade. Os segmentos de legenda inventados são:

```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."
  }
]
```

Estude um mapa fictício de lacunas da aula

Verifique o primeiro intervalo com uma soma simples. 20 mais 8 é igual a 28. Isso corresponde a `endSeconds`. Verifique o segundo intervalo. 28 mais 5 é igual a 33. Isso corresponde a `endSeconds`. Essas somas apenas confirmam os tempos fictícios. Elas não avaliam a aula.

O texto da legenda não menciona uma régua. Na história, você reproduz o trecho de 20–28 segundos e observa a imagem. Uma régua começa na borda interna esquerda. Você só sabe disso porque assistiu. A ausência da palavra régua não significa que a imagem esteja em branco. O texto da legenda também não comprova que a fala é suficiente.

A aba externa é a borda que fica na parte de fora da bandeja. A aula mostra as bordas internas. Ela nunca diz que a aba externa não entra na medida.

| Comentário | Conceito | Conversa verificada | Trecho da aula verificado | Estado | Mudança proposta | Verificação de aceitação |
| --- | --- | --- | --- | --- | --- | --- |
| C1 no tutorial fictício de jardinagem. Texto do comentário: "Devo medir por fora da bandeja?" | Meça a largura entre as bordas internas. | Você abriu a conversa. A resposta diz que o espectador mediu a aba externa. | 20–28 segundos. Fala: "Meça a largura entre as bordas internas da bandeja." A régua começa na borda interna esquerda. A fala não faz uma comparação com a aba externa. | `possible_wording_gap` | Aos 20 segundos, mostre as 2 bordas, marque a borda interna e diga que a aba externa não entra na medida. | Um revisor consegue indicar a borda exata de início e a borda exata de fim apenas com o novo trecho, sem consultar o comentário e suas respostas. |
| C2 no tutorial fictício de jardinagem. Texto do comentário: "Posso misturar polegadas e centímetros?" | Use uma única unidade para as 2 dimensões. | Nenhuma resposta verificada diz que esse espectador deixou de entender a fala sobre a unidade. | 28–33 segundos. Fala: "Use centímetros para as 2 dimensões." | `explanation_present_question_unresolved` | Apenas como opção: acrescente uma indicação visível da unidade ou uma breve recapitulação junto ao ponto de 28 segundos. Mantenha a frase original. Não reescreva a aula como se a regra estivesse ausente. | Um revisor ainda consegue encontrar a frase original sobre a unidade em 28–33 segundos. A pergunta, por si só, não é contada como uma explicação que o espectador deixou de entender. |
| C3 no tutorial fictício de jardinagem. Texto do comentário: "O botão não aparece." | Encontrar um botão. O comentário não informa o dispositivo nem a versão. | Nenhuma resposta estava disponível para verificação. O dispositivo e a versão continuam desconhecidos. | Indisponível. O tempo do trecho é desconhecido. Não invente um. | `unresolved` | Nenhuma edição na aula. | A linha continua sem resolução. Um revisor não acrescenta um dispositivo, uma versão, uma causa ou um tempo do trecho. |
| C4 no tutorial fictício de jardinagem. O comentário pergunta sobre outro modelo de produto. | Etapas para o modelo ensinado neste vídeo. | Você abriu a conversa. A resposta confirma que o comentário trata de outro modelo. | A aula atual não é apontada como a causa. Nenhum tempo do trecho é atribuído. | `setup_mismatch` | Nenhuma edição nesta aula. Anote que o comentário menciona outro modelo. | Um revisor consegue identificar o outro modelo na resposta verificada e mantém as etapas desta aula sem alterações. |

C1 começa como `stated_confusion` porque faz uma pergunta concreta sobre medição. O trecho já diz para medir entre as bordas internas da bandeja. A imagem confirma isso, pois a régua começa na borda interna esquerda. A explicação não está ausente, portanto o estado não é `explanation_missing`. A resposta verificada diz que o espectador usou a aba externa. A aula nunca compara essa aba com a borda interna. A classificação adequada é `possible_wording_gap`. A resposta não mostra por que o espectador escolheu a aba. Não invente um motivo. A mudança é uma comparação direta aos 20 segundos. O teste usa apenas a nova imagem e a nova frase.

C2 também começa como `stated_confusion`. A fala de 28–33 segundos já apresenta a regra: usar centímetros para as 2 dimensões. Nada na conversa verificada mostra que esse espectador deixou de entender aquela fala. Uma pergunta após uma fala clara não comprova falta de compreensão. O estado é `explanation_present_question_unresolved`. Uma indicação da unidade pode ajudar um espectador posterior a identificar a regra. Ela é opcional. Ela não deve substituir a frase original nem dar a entender que a regra estava ausente.

C3 é `insufficient_context` antes de você procurar um trecho. "O botão não aparece" não informa o dispositivo nem a versão. Nenhuma resposta acrescenta esses fatos. Você não pode escolher um tempo do vídeo. Você não pode apontar uma causa. O contexto desconhecido continua desconhecido. O estado permanece `unresolved`, e a verificação de aceitação proíbe uma edição forçada.

C4 começa como uma pergunta concreta, portanto você pode marcar `stated_confusion` antes de verificar a conversa. A resposta verificada diz que o modelo não é o modelo desta aula. Isso muda o estado para `setup_mismatch`. Não invente uma falha no trecho atual. Não mude esta aula para responder sobre outro modelo.

Conte as linhas desta história. 1 linha é `possible_wording_gap`. 1 linha é `explanation_present_question_unresolved`. 1 linha é `unresolved`. 1 linha é `setup_mismatch`. Isso representa 4 linhas de comentários. Uma linha não comprova a existência de uma pessoa distinta. A história não diz quantas pessoas assistiram. Ela não diz que todos os espectadores tiveram o mesmo problema. Os tempos das legendas apenas ajudam você a encontrar o trecho. Eles não substituem assistir e ouvir.

## Próxima ação

Escolha um comentário que apresente uma dúvida específica. Reproduza aquele momento do vídeo e observe a imagem, não apenas o texto da legenda. Salve uma mudança proposta e um teste que outra pessoa possa repetir. Obtenha as linhas de comentários com o Actor [YouTube Comments Scraper](https://apify.com/chronometrica/youtube-comments-scraper). Coloque seu próprio tutorial na [Task de análise de comentários de vídeo](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis). O Actor apenas coleta linhas. Você continua responsável por avaliar o trecho.

## Fontes e leituras adicionais

- [Actor YouTube Comments Scraper](https://apify.com/chronometrica/youtube-comments-scraper)
- [Task de análise de comentários de vídeo](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis)
- [Task de transcrição com marcações de tempo](https://apify.com/chronometrica/youtube-transcript-scraper/examples/youtube-timestamped-transcript-json)
- [Como analisar seu público do YouTube](https://www.reddit.com/r/YouTubeCreators/comments/1tdvbvx/how_do_you_analyze_your_youtube_audience_across/)