| name | youtube-dashboard |
| description | Configura dashboard HTML de metricas do YouTube via Apify. Coleta dados publicos do canal (inscritos, total de views, descricao), videos recentes (views, likes, comentarios, duracao, titulo, thumbnail). Todas as thumbnails embutidas em base64. Roda localmente na maquina do mentorado, sem servidor, sem GitHub, sem agendamento automatico.
|
| user-invocable | false |
YouTube Dashboard. Metricas Diarias Automaticas
Quando Usar
- Quando o aluno quiser monitorar o crescimento do proprio canal no YouTube de forma automatica, sem precisar abrir o YouTube Studio toda manha.
- Como base de dados para
/copy-roteiro (roteiros baseados nos videos que performam melhor) e analise de padroes de titulo e thumbnail.
- Quando o aluno precisar mostrar evolucao de metricas para clientes ou parceiros.
Nao usar para:
- Analisar canais de concorrentes (adaptar o script passando outro canal).
- Dados avancados do YouTube Analytics (CPM, receita, retencao) — esses requerem a YouTube Data API com OAuth, fora do escopo do Apify.
O Que Entrega
| Arquivo | Descricao |
|---|
.claude/skills/youtube-dashboard/scripts/atualizar.py | Script Python principal (Windows, macOS, Linux) — compartilhado entre todos os produtos |
meus-produtos/{ativo}/entregas/youtube-dashboard/dashboard.html | Dashboard HTML completo, abre no navegador |
meus-produtos/{ativo}/entregas/youtube-dashboard/imagens/ | Thumbnails dos videos (gerados pelo script) |
meus-produtos/{ativo}/entregas/youtube-dashboard/insights.json | Dados estruturados sem base64 |
meus-produtos/{ativo}/entregas/youtube-dashboard/historico.json | Snapshots acumulativos (inscritos, engajamento) entre execucoes |
meus-produtos/{ativo}/entregas/youtube-dashboard/log.txt | Log de cada execucao com timestamp e status |
Como Funciona
atualizar.py
├── POST Apify (streamers~youtube-scraper, sync) — videos regulares
│ {canal_url} → ultimos 30 videos + metadados do canal embutidos
│ avatar: aboutChannelInfo.channelAvatarUrl → base64
├── POST Apify (streamers~youtube-scraper, sync, opcional) — Shorts
│ {canal_url}/shorts → ate 30 Shorts
│ Deduplicados por id/videoId e mesclados com os videos regulares
│ Se falhar ou estiver vazio, continua sem erro
├── Para cada video/Short: views, likes, comentarios, duracao, titulo, data, thumbnail → base64
├── Calcula metricas: engajamento = (likes + comentarios) / views * 100
├── Atualiza historico.json com snapshot do dia
└── Regenera dashboard.html com dados + thumbnails embutidos como variavel JS
O dashboard.html e sempre autossuficiente. Nao depende de servidor local. Funciona abrindo direto no navegador, inclusive offline apos a primeira geracao.
APIs Utilizadas
Ator utilizado: streamers~youtube-scraper.
| # | Ator Apify | URL chamada | Tipo | Parametro chave | Retorna |
|---|
| 1 | streamers~youtube-scraper | {canal_url} | sync, timeout 300s | startUrls, maxResults: 30 | videos regulares + metadados do canal (aboutChannelInfo.channelAvatarUrl, channelName, numberOfSubscribers etc.) |
| 2 | streamers~youtube-scraper | {canal_url}/shorts | sync, timeout 300s, obrigatorio=False | startUrls, maxResults: 30 | Shorts do canal (adicionados e deduplicados por id/videoId) |
Chamada 1 busca os videos regulares. Chamada 2 busca a aba /shorts — se falhar ou retornar vazio, o script continua sem erro. Os resultados sao mesclados e deduplicados por ID antes de normalizar. O script extrai os dados do canal percorrendo os itens da chamada 1 e priorizando o que tiver mais dados.
Por que sync e nao async: mesmo motivo do Instagram/TikTok. Endpoints async retornam run IDs que podem ficar inacessiveis dependendo do plano. Sync e mais simples e confiavel.
Thumbnails do YouTube: o script baixa thumbnails via https://i.ytimg.com/vi/{videoId}/hqdefault.jpg com requests. Se a URL vier preenchida no campo thumbnailUrl do Apify, usa essa. Caso contrario, monta a URL padrao com o videoId. Converte para base64 para funcionar em HTML local.
Custo por execucao: cerca de US$0,05-0,30 no plano gratuito Apify (varia com o numero de videos coletados).
Compatibilidade por Sistema Operacional
Instalacao da dependencia (unica):
pip install requests
| OS | Como rodar |
|---|
| Windows | python .claude/skills/youtube-dashboard/scripts/atualizar.py --abrir |
| macOS | python3 .claude/skills/youtube-dashboard/scripts/atualizar.py --abrir |
| Linux | python3 .claude/skills/youtube-dashboard/scripts/atualizar.py --abrir |
Configuracao Necessaria
| Chave | Onde fica | Como obter |
|---|
APIFY_API_TOKEN | .env | console.apify.com > Settings > Integrations > Personal API token |
YOUTUBE_CHANNEL | .env | URL do canal ou @handle (ex: https://www.youtube.com/@meuperfil ou @meuperfil) |
Dashboard: O Que Mostra
ESTRUTURA OBRIGATORIA — todas as secoes devem estar presentes, nesta ordem:
- Cabecalho (canal): avatar em base64 (fallback: inicial do nome), nome do canal, descricao, data de criacao, ultima atualizacao
- Visao Geral (KPIs): inscritos, total de views do canal, engajamento medio (%), total de videos
- Evolucao ao Longo do Tempo: tendencia de inscritos e engajamento medio entre execucoes. So aparece com 2+ snapshots em historico.json.
- Desempenho por Duracao: videos agrupados por faixa (Short ate 60s, curto 1-5min, medio 5-15min, longo 15min+). Media de views, likes, engajamento.
- Melhores Dias para Publicar: heatmap ou grafico de barras por dia da semana. Intensidade = views medias.
- Frequencia de Publicacao: videos por semana vs views. Insight comparando semanas mais ativas.
- Top 3 Videos: os 3 com mais views, com thumbnail em base64, views, likes, comentarios, duracao, taxa de engajamento e link.
- Analise de Titulos: palavras mais frequentes nos videos com mais views (wordcloud ou barras). Insight sobre comprimento ideal de titulo.
- Tamanho do Titulo vs Views: 3 buckets (curto, medio, longo) com views medias por faixa.
- Linha do Tempo (graficos): views, likes, engajamento (%) ao longo do tempo. Canvas puro, tooltip.
- Barra de Filtros: filtros por duracao e periodo (7/15/30 dias). Afeta grade de videos, Top 3 e KPIs.
- Todos os Videos (grade): thumbnail em base64, views, likes, comentarios, duracao, data, titulo truncado e link.
NUNCA omitir nenhuma dessas 12 secoes.
Metricas YouTube (diferente do Instagram e TikTok)
| Metrica | Campos Apify tentados (em ordem) | Observacao |
|---|
| Views | views, viewCount | Metrica principal no YouTube |
| Likes | likes, likeCount | YouTube removeu dislikeCount da API publica |
| Comentarios | commentsCount, commentCount, comments | |
| Duracao | duration, durationSeconds | Script converte ISO 8601 (PT1H2M3S), HH:MM:SS e segundos para int |
| Titulo | title, name | |
| Thumbnail | thumbnailUrl, thumbnail, ou montar de videoId | URL padrao: i.ytimg.com/vi/{id}/hqdefault.jpg |
| Video ID | id, videoId, ou extraido de url (v=...) | |
| Inscritos | numberOfSubscribers, subscriberCount (no item ou em channelInfo) | |
| Total views canal | channelInfo.viewCount, channelInfo.totalViews, channelTotalViews | Fallback: soma dos videos coletados |
| Engajamento YouTube | (likes + comentarios) / views * 100 | Benchmark: acima de 3% e bom |
Fluxo
PASSO -1. Verificar Plataforma Ativa (OBRIGATORIO — executar antes de qualquer outra coisa)
Leia .env. Verifique o valor de YOUTUBE_ATIVO.
Cenario: YOUTUBE_ATIVO=false (aluno ja disse que nao tem YouTube)
Voce marcou que nao tem um canal ativo no YouTube.
Quer atualizar essa preferencia?
1. Sim, tenho YouTube agora — configurar o dashboard
2. Nao, pode ignorar
Se escolher 1: troque YOUTUBE_ATIVO=false por YOUTUBE_ATIVO=true no .env e continue para o PASSO 0.
Se escolher 2: encerre sem fazer nada.
Cenario: YOUTUBE_ATIVO nao existe no .env (primeira vez)
Voce tem um canal ativo no YouTube que quer monitorar?
1. Sim, tenho YouTube
2. Nao tenho YouTube
Se escolher 1: salve YOUTUBE_ATIVO=true no .env (Edit cirurgico, adicionar linha). Continue para o PASSO 0.
Se escolher 2: salve YOUTUBE_ATIVO=false no .env. Encerre com:
Tudo bem. Se um dia criar um canal no YouTube, e so chamar essa skill de novo.
Cenario: YOUTUBE_ATIVO=true (aluno confirmou que tem YouTube)
Continue direto para o PASSO 0 sem perguntar nada.
PASSO 0. Detectar Estado
Antes de qualquer pergunta, leia em paralelo:
.env na raiz do projeto — existe APIFY_API_TOKEN com valor? existe YOUTUBE_CHANNEL com valor?meus-produtos/{ativo}/entregas/youtube-dashboard/dashboard.html — o arquivo existe?
Cenario A. Dashboard ja configurado (dashboard.html existe)
Mostre o menu sem perguntas:
Dashboard do YouTube ja esta configurado.
Canal monitorado: {YOUTUBE_CHANNEL do .env}
O que quer fazer?
1. Abrir o dashboard agora
2. Atualizar os dados agora
3. Trocar o canal monitorado
4. Recriar o script do zero
Cenario B. Primeira configuracao
1. Canal do YouTube
Prioridade: ler .env primeiro (YOUTUBE_CHANNEL). Se encontrar, confirme.
Se nao encontrar, pergunte:
Qual o endereco do seu canal no YouTube?
(ex: https://www.youtube.com/@meuperfil ou @meuperfil)
Normalize: aceitar @handle, URL completa ou channel ID. Salve com Edit cirurgico no .env: YOUTUBE_CHANNEL=<valor>.
2. Token Apify
Se APIFY_API_TOKEN estiver no .env: use diretamente, nao pergunte.
Se nao estiver: execute a skill configurar-apify e retorne aqui apos concluir.
PASSO 1. Confirmacao
Configuracao confirmada:
- Canal YouTube: {YOUTUBE_CHANNEL}
- Token Apify: configurado
- Script: .claude/skills/youtube-dashboard/scripts/atualizar.py
- Dashboard: meus-produtos/{ativo}/entregas/youtube-dashboard/dashboard.html
1. Tudo certo, gerar agora
2. Quero ajustar algo
PASSO 2. Executar
python .claude/skills/youtube-dashboard/scripts/atualizar.py --abrir
macOS / Linux: python3 ...
Leia o log para confirmar sucesso:
tail -10 meus-produtos/{ativo}/entregas/youtube-dashboard/log.txt
Erros comuns:
| Erro no log | Causa | Solucao |
|---|
401 ou autenticacao | Token Apify invalido | Verificar token em console.apify.com |
Canal vazio ou erro | URL errada ou canal sem videos publicos | Confirmar URL do canal |
| Timeout | Ator YouTube lento | Aumentar timeout no script ou rodar novamente |
PASSO 3. Entrega
Apos confirmar sucesso no log, atualize o painel de entregas:
py -3 scripts/painel-incremental.py --secao dashboards
(macOS/Linux: python3 scripts/painel-incremental.py --secao dashboards)
Se o painel ainda nao existir, informe:
O painel de entregas ainda nao foi criado para este produto.
Rode /produto-concepcao primeiro para gerar o painel, depois atualize os dashboards.
Informe ao aluno:
Dashboard do YouTube gerado.
Acesse pelo Painel de Entregas:
meus-produtos/{ativo}/painel-entregas.html (aba Dashboards)
Para atualizar os dados quando quiser:
python .claude/skills/youtube-dashboard/scripts/atualizar.py
(depois rode: py -3 scripts/painel-incremental.py --secao dashboards)
Canal monitorado: {YOUTUBE_CHANNEL}
Sem agendamento automatico: o aluno roda o script manualmente.
PASSO 4. Verificar Proxima Plataforma na Fila
Apos confirmar entrega com sucesso, verifique se meus-produtos/{ativo}/.dashboard-queue.json existe.
Se o arquivo NAO existir: exibir os "Proximos Passos" normalmente e encerrar. (Skill foi chamada diretamente, sem fila.)
Se o arquivo EXISTIR:
- Leia o conteudo do arquivo.
- Mova
"youtube" de pendentes para concluidos (Edit cirurgico no JSON).
- Verifique se ainda ha itens em
pendentes.
Se pendentes estiver vazio: delete o arquivo .dashboard-queue.json. Exiba:
Todos os dashboards foram gerados.
E encerre.
Regra: o YouTube e sempre o ultimo da fila (ordem Instagram, TikTok, YouTube). Se pendentes ficar vazio aqui, e porque todos foram concluidos. Nunca havera proximo apos o YouTube.
Regra: nunca exibir os "Proximos Passos" quando o arquivo de fila existir. A fila tem prioridade sobre as sugestoes de conteudo.
Regras
- Sempre ler
.env antes de pedir o token Apify ao usuario.
- O token Apify e o canal ficam no
.env (APIFY_API_TOKEN e YOUTUBE_CHANNEL). Nunca hardcodar no script.
- Dashboard em HTML puro. Sem libs externas alem de Google Fonts. Canvas puro para graficos.
- Nao usar travessao em nenhum texto exibido no dashboard.
- Tema claro: fundo #f8fafc, cards brancos, accent vermelho YouTube #ff0000 ou neutro indigo.
- CRITICO — Thumbnails: verificar se as URLs publicas do YouTube (
i.ytimg.com) carregam em HTML local. Se nao, converter para base64.
- CRITICO — Duracao ISO 8601: converter
PT1H2M3S para segundos no script. Exibir no dashboard em formato 1h 2min 3s ou HH:MM:SS.
- CRITICO — Engajamento no YouTube e calculado sobre views. Formula: (likes + comentarios) / views * 100. Benchmark: 3-5% e considerado bom.
- YouTube removeu dislikes da API: nao tentar coletar ou exibir dislikeCount.
Proximos Passos Apos Configurar
/copy-roteiro — criar roteiros baseados nos videos com mais views/copy-social — criar conteudo para outras plataformas baseado nos temas que performam/copy-anuncio — transformar videos de sucesso em anuncios
