JoeyRedfield/videobook

VideoBook: Transforme um Vídeo em um eBook Técnico Ilustrado

Dado um link do YouTube / Bilibili, produza um eBook técnico legível online: output/<video_id>/book.md + book.html (com cards de player embutidos, screenshots clicáveis para ampliar, diagramas Mermaid), opcionalmente transcript.corrected.txt (roteiro de correção de legendas), e publique no GitHub Pages para outros lerem.

Este skill é uma camada de orquestração e auto-contido: todas as instruções necessárias para o agente estão neste diretório (SKILL.md + references/), não dependendo de instructions.md / README.md (esses são para leitores humanos, permanecem intocados, não mantidos por este skill). A única dependência externa é o código executável da pipeline em src/*.py: comandos e parâmetros sempre seguem --help dos scripts, nunca reescreva a lógica. Dados voláteis (ex: mapa de erros em src/make_corrected.py) não devem ser copiados para o skill, apenas a regra e a referência ao arquivo fonte; única exceção: as instruções de formatação do passo 2, deste diretório (references/stitcher-prompt.md, priorizando a versão do repositório se existir).

Pré-requisitos (leitura obrigatória na primeira execução)

1. Diretório de trabalho = raiz do repositório videobook (verificar: existência de src/dump_transcript.py e prompts/), todos os caminhos relativos (output/<video_id>/...) são resolvidos a partir dele. Se o repositório não estiver local, primeiro: git clone https://github.com/Luke-Evan/videobook.git no diretório onde o usuário guarda projetos de código (não em diretório temporário, nem criar diretório projects), depois cd para dentro.
2. Python >= 3.10 (recomendado 3.12). Instalar dependências: uv sync (se usar uv) ou pip install -r requirements.txt. Executar usando o interpretador do ambiente do repositório: uv run python src/xxx.py ou .venv/Scripts/python.exe src/xxx.py.
3. Login único: python src/capture_frames.py --setup-profile abre um Chrome dedicado (diretório de dados .capture-profile/), faça login no Bilibili / YouTube, feche a janela — o estado de login será reutilizado por muito tempo. O nível da conta do usuário logado determina a resolução máxima das screenshots.
4. Vídeos estrangeiros: terminal precisa de proxy (para capturar legendas), navegador também precisa de proxy global (senão o iframe do YouTube na página gerada fica preto).
5. Comandos que exigem elevação/fora do sandbox estão na última coluna da tabela geral; passos puramente locais podem ser executados dentro do sandbox.

Visão Geral da Pipeline

Passo	O que fazer	Comando	Detalhes	Elevação
1	Extrair legendas	python src/dump_transcript.py "<URL>"	references/transcript.md	Bilibili precisa
1b	Fallback ASR local quando plataforma não tem legenda	python src/asr_transcript.py <video_id>	references/transcript.md	Não (demorado)
1.5	Materiais oficiais do curso + slides 4K (executado por padrão, pula se curso não tem página)	python src/course_assets.py <video_id> --course-url <página_do_curso>	references/course-assets.md	Renderização precisa
2	LLM reescreve legendas em book.md	Seguir instruções de formatação (references/stitcher-prompt.md, priorizando prompts/stitcher_system.md do repositório se existir)	references/writing.md	Não
2b	Roteiro de correção de legendas (opcional)	python src/make_corrected.py <video_id>	references/correction.md	Não
3	Capturar frames e materializar placeholders em imagens	python src/capture_frames.py <video_id> "<URL>"	references/capture.md	Sim
4	Renderizar HTML + iniciar preview local	python src/post_process.py "<URL>" output/<id>/book.md depois python -m http.server 8080 --directory output/<id>	—	Não
5	Informar usuário sobre resultado, perguntar sobre limpeza de arquivos grandes	—	Veja "Entrega" abaixo	—
6	Publicar artefato na branch pages (opcional)	python src/publish.py <video_id> depois git push origin pages	references/publish.md	Não (push precisa de rede)

Para erros, qualidade de captura, legendas não encontradas, interrupção de ASR, consulte primeiro references/troubleshooting.md.

Regras de Ferro (Innegociáveis)

1. Cobertura de legendas < 50% (código de saída 3) não pode entrar no passo 2: primeiro corrija estado de login/proxy, ou use fallback ASR.
2. As imagens de tela devem vir do player do navegador logado na plataforma, nenhum passo pode baixar arquivos de vídeo/áudio (ffmpeg para extrair frames é apenas último recurso). Lista de métodos proibidos em references/capture.md.
3. Cookies gravados apenas em diretório temporário do sistema, deletados após uso, nunca commitados no repositório, nem colocar cookies.txt manualmente na área de trabalho.
4. output/ não é afetado por operações git; artefatos publicados apenas na branch orphan pages, main contém apenas código.
5. Fidelidade do roteiro corrigido: manter parágrafos originais e ordem do instrutor, apenas substituir erros de ASR + limpar vícios de fala; proibido deletar parágrafos, juntar linhas, ou reescrever drasticamente (camada de validação rejeitará diretamente).
6. Fidelidade da escrita: escrita formal não significa sumarização; manter analogias, exemplos, cadeias de raciocínio; acréscimos do editor devem ser marcados com "Nota do editor".
7. Direitos autorais de materiais do curso: apostilas e slides pertencem ao instrutor (geralmente CC BY-NC), bloco de informações no início do livro e no final devem conter link de atribuição, nome do autor e licença.
8. Regra de cobertura de slides: cada página de slides_text.md deve aparecer exatamente uma vez no livro; antes da entrega, --audit deve passar.
9. Perguntar antes de deletar arquivos grandes (audio.m4a, video_source.mp4 etc.), só deletar após confirmação.
10. Ao gerar ou modificar HTML, contraste entre texto e fundo deve ser >= 4.5:1 (WCAG AA).
11. Cada passo é idempotente e pode ser reexecutado: antes de materializar placeholders, o script faz backup automático de book.tagged.md; enquanto ele existir, reexecutar o passo 3 restaura as screenshots.

Entrega (passo 5: informar tudo de uma vez)

1. Localização de output/<video_id>/book.md;
2. Endereço de pré-visualização: http://localhost:8080/book.html, para parar o servidor, pressione Ctrl+C no terminal;
3. Vídeos do YouTube exigem que o navegador consiga acessar YouTube (proxy), vídeos do Bilibili podem ser vistos diretamente;
4. Qualidade das screenshots depende do nível da conta logada em .capture-profile/; para maior qualidade, troque de conta e reexecute o passo 3;
5. Se foram usados materiais oficiais do curso, as ilustrações dos slides são renderizações 4K oficiais (origem e licença CC indicadas no início do livro), os frames de demonstração continuam sendo frames de vídeo; o diretório course/ pode ser deletado por completo sem afetar a leitura;
6. Pergunte se deseja deletar os arquivos de mídia grandes gerados durante o processo (regra de ferro 9).

Conteúdo deste Diretório (leia sob demanda, não leia tudo de uma vez)

Arquivo	Quando ler
references/transcript.md	Passo 1 (extrair legendas); quando plataforma não tem legendas, usar ASR local
references/writing.md	Passo 2 (reescrever legendas em book.md)
references/stitcher-prompt.md	Instruções de formatação do passo 2 (priorizar versão do repositório prompts/stitcher_system.md se existir)
references/course-assets.md	Quando o curso tem página oficial (passo 1.5), regras de cobertura, upgrade de slides
references/correction.md	Gerar roteiro de correção de legendas e propostas de correção por IA em nível de linha
references/capture.md	Passo 3 (captura de frames): prioridades, métodos explicitamente proibidos, boas práticas de QA
references/publish.md	Passo 6 (publicar na branch pages)
references/troubleshooting.md	Qualquer erro, qualidade anômala, legendas não capturadas, elevação negada

Convenções de Manutenção

• Este skill é versionado junto com o código da pipeline no mesmo repositório: se alterar parâmetros de src/*.py, ordem dos passos ou regras de ferro, deve atualizar este diretório simultaneamente.
• Os arquivos instructions.md e README.md do repositório são para leitores humanos, permanecem intocados, não mantidos por este skill; não os modifique para fazer o skill funcionar; em caso de sobreposição de conteúdo, o agente deve usar este diretório como referência.
• Ao sincronizar references/stitcher-prompt.md, atualize o hash do commit na nota de origem no cabeçalho do arquivo.
• Instalação por terceiros: skill-installer com --repo Luke-Evan/videobook --path skills/videobook; ou após clonar, copie/symlink este diretório para ~/.codex/skills/ (apenas Codex) ou ~/.agents/skills/ (multi-agente).
• Este diretório não contém cookies, estado de login, artefatos de output/ ou nenhum arquivo de mídia, podendo ser distribuído publicamente com segurança.