AutoCliper.AI — Habilidade do Agente
Converta um vídeo longo do YouTube em 5 a 15 clipes curtos com embalagem chinesa e legendas embutidas (hard-burned).
Este documento é a fonte única da verdade para qualquer agente de IA executando o pipeline AutoCliper. Siga cada etapa numerada em ordem. Não pule etapas. Não adivinhe nomes de arquivos — inspecione o sistema de arquivos após cada operação de escrita.
0. Verificações Pré-voo
Antes de fazer qualquer outra coisa, verifique o ambiente. Reporte o bloqueador exato e pare se alguma verificação falhar.
| Verificação | Comando | Condição de Sucesso |
|---|---|---|
| yt-dlp instalado | which yt-dlp | retorna um caminho |
| ffmpeg instalado | which ffmpeg | retorna um caminho; se faltar, tente python3 -c "import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())" |
| Python 3.9+ | python3 --version | >= 3.9 |
| Repositório da skill disponível | verifique se o diretório corekit/ existe relativo à raiz da skill | corekit/__init__.py está presente |
Configure o ambiente para todos os comandos subsequentes:
export PYTHONPATH="<caminho-para-o-repositório-AutoCliper.AI>"
Todos os comandos python3 -m corekit.* abaixo assumem que este PYTHONPATH está definido.
1. Criar Espaço de Trabalho
Crie a estrutura de diretórios de saída para este vídeo. Derive <slug> do título ou ID do vídeo — minúsculas, hífens, sem espaços, sem caracteres especiais.
mkdir -p "studio/<slug>/intake"
mkdir -p "studio/<slug>/intel"
mkdir -p "studio/<slug>/exports"
Resultado esperado:
studio/<slug>/
├── intake/ ← vídeo bruto + legendas ficam aqui
├── intel/ ← artefatos de análise ficam aqui
└── exports/ ← pastas por clipe ficam aqui
2. Buscar Ativos da Fonte
Baixe o vídeo e as legendas do YouTube:
python3 -m corekit.fetch_source "<URL_do_YouTube>" "studio/<slug>/intake"
O que acontece internamente: o downloader tenta primeiro legendas em inglês (en, en-US, en-orig), e depois cai para chinês (zh-Hans, zh-CN, zh). Ele usa --cookies-from-browser chrome para acesso autenticado.
Após o comando terminar, liste a pasta de intake e identifique:
- O arquivo de vídeo
.mp4(pode conter o título e ID do vídeo no nome do arquivo) - O arquivo de legenda
.srt(pode ter uma tag de idioma como.en.srtou.zh-Hans.srt) - Quaisquer arquivos auxiliares (
.ytdl,.jpg, etc.) — anote-os, mas não são necessários
Se o download falhar:
- Erro de cookie → peça ao usuário para atualizar o login do YouTube no Chrome, depois tente novamente
- Nenhuma legenda encontrada → reporte "nenhuma legenda disponível para este vídeo" e pare
- Erro de download de vídeo → tente novamente uma vez com um formato diferente; se ainda falhar, reporte o erro
Registre os nomes exatos dos arquivos para as próximas etapas. Não adivinhe nem codifique nomes.
3. Analisar Legendas em JSON
Converta o arquivo de legenda SRT em JSON estruturado para facilitar a análise:
python3 -m corekit.subtitle_to_json \
"studio/<slug>/intake/<nome-exato-do-arquivo-srt>" \
"studio/<slug>/intel/transcript.json"
Verifique se o arquivo de saída existe e contém um array de objetos de cue. Cada cue tem:
{
"index": 1,
"start": "00:00:01,234",
"end": "00:00:03,456",
"start_seconds": 1.234,
"end_seconds": 3.456,
"text": "the spoken content"
}
Se a transcrição estiver vazia ou tiver menos de 10 cues, reporte "transcrição muito curta ou corrompida" e pare.
4. Analisar Transcrição e Propor Candidatos
Esta é a etapa intelectual mais importante. Leia os seguintes arquivos antes de iniciar a análise:
- playbooks/clip-contract.md — define o esquema JSON exato para
selected_clips.json - playbooks/content-analysis-playbook.md — define o método de análise em múltiplas passadas, a rubrica de pontuação e a formatação de revisão
4a. Análise em Múltiplas Passadas
NÃO tente escolher clipes em uma única passada. Siga esta sequência:
Passada 1 — Folhear e sinalizar: Leia o transcript.json procurando por trechos que contenham conteúdo memorável, denso em informação, opinativo, contraintuitivo ou emocionalmente marcante. Sinalize generosamente — é melhor sinalizar muitos do que poucos.
Passada 2 — Refinamento de limites: Para cada trecho sinalizado, releia as cues ao redor (5–10 cues antes e depois). Escolha um início e fim limpos:
- O início deve cair em uma linha que prenda o espectador nos primeiros 3 segundos do clipe
- O fim deve cair depois que o orador completou o pensamento — nunca no meio de uma frase
- Se um momento promissor precisar de alguns segundos de contexto, estenda o início para antes
- Se um pensamento se perder, estenda o fim até que se resolva
Passada 3 — Verificação de completude: Para cada candidato, verifique:
- Tem 20–180 segundos de duração (pode esticar para 3 min se o retorno justificar)
- Contém exatamente uma ideia clara
- A linha de abertura é um gancho, não um preenchimento
- A linha de fechamento resolve o pensamento
- É compreensível sem assistir ao resto do vídeo
- NÃO é uma saudação, leitura de patrocinador, preâmbulo de Q&A ou longa digressão
Passada 4 — Pontuar e classificar: Pontue cada candidato em quatro dimensões (1–5):
hook— quão convincente é a abertura nos primeiros 3 segundos?clarity— é uma ideia limpa com baixa ambiguidade?standalone— pode ser compreendido sozinho sem contexto anterior?payoff— o final é útil, memorável ou digno de compartilhamento?
Classifique pelo total ponderado: hook × 0.35 + clarity × 0.25 + standalone × 0.2 + payoff × 0.2
4b. Orientação sobre Número de Candidatos
| Duração da Fonte | Candidatos Alvo |
|---|---|
| < 20 min | 5 – 8 |
| 20 – 60 min | 8 – 12 |
| > 60 min | 10 – 15 |
O modo de falha padrão deve ser "poucos candidatos demais", não "muitos demais". Quando em dúvida, inclua mais. O usuário fará a poda.
4c. Lidando com Legendas Geradas Automaticamente (Ruidosas)
As legendas automáticas do YouTube geralmente contêm:
- Fragmentos repetidos (a mesma frase aparecendo em cues consecutivas)
- Pontuação e capitalização ausentes
- Palavras ouvidas incorretamente (especialmente nomes, termos técnicos)
Quando as legendas de origem forem geradas automaticamente:
- Infira o significado pretendido de forma conservadora — não invente afirmações
- Ignore fragmentos duplicados ao julgar limites de clipe
- Use o contexto circundante para determinar onde as sentenças realmente terminam
- Anote no resumo do candidato se a qualidade da fonte é baixa
4d. Escrever Saídas
Escreva dois arquivos:
-
studio/<slug>/intel/selected_clips.json— as decisões de clipe legíveis por máquina. Deve seguir exatamente o esquema emplaybooks/clip-contract.md. -
studio/<slug>/intel/candidate-board.md— a tabela de revisão legível por humanos.
5. Apresentar Candidatos para Revisão do Usuário
Mostre a lista de candidatos em um formato amigável para revisão. Para cada candidato, exiba:
| Campo | Formato | Exemplo |
|---|---|---|
| ID | clip-XX | clip-01 |
| Intervalo de tempo | HH:MM:SS → HH:MM:SS | 00:12:03 → 00:13:22 |
| Duração | legível para humanos | 1m 19s |
| Título | um título chinês provocativo, ≤12 caracteres | AI终将取代一切? |
| Resumo | exatamente duas frases em chinês | 句1: 在讲什么。句2: 为什么值得看。 |
Apresente como uma tabela numerada para que o usuário possa responder com IDs.
Se o usuário disser "prosseguir" ou "escolha automática": selecione você mesmo os candidatos mais bem classificados. Para um vídeo de 1 hora, exporte pelo menos 8.
Se o usuário escolher IDs específicos: exporte apenas aqueles.
6. Exportar Cada Clipe Escolhido
Para cada clipe que o usuário escolheu (ou você selecionou automaticamente), execute as etapas 6a a 6f em ordem. Complete todas as subetapas para um clipe antes de passar para o próximo.
6a. Cortar o Segmento do Vídeo
python3 -m corekit.cut_video \
"studio/<slug>/intake/<nome-exato-do-arquivo-mp4>" \
<segundo_inicio> <segundo_fim> \
"studio/<slug>/exports/<pasta-do-clipe>/clip.mp4"
A convenção de nomenclatura <pasta-do-clipe> é XX-<slug-do-titulo>, por exemplo, 01-ai-will-replace.
Verifique se o arquivo de saída existe e tem tamanho diferente de zero.
6b. Janelar a Legenda de Origem
python3 -m corekit.window_subtitles \
"studio/<slug>/intake/<nome-exato-do-arquivo-srt>" \
<segundo_inicio> <segundo_fim> \
"studio/<slug>/exports/<pasta-do-clipe>/clip.src.srt"
Isso extrai apenas as cues que se sobrepõem à janela do clipe e desloca todos os timestamps para que o clipe comece em 00:00:00,000.
Verifique se o SRT de saída tem pelo menos uma cue.
6c. Traduzir para Legenda em Chinês
Leia clip.src.srt e traduza-o para chinês simplificado. Escreva o resultado em clip.zh.srt na mesma pasta.
Regras de tradução (siga estritamente):
- Chinês falado natural — não chinês escrito/formal. O espectador está assistindo a um vídeo curto, não lendo um documento.
- Preserve os timestamps exatamente — a menos que você precise mesclar duas cues para legibilidade. Nunca altere o timing arbitrariamente.
- Mantenha entidades nomeadas precisas — nomes de pessoas, empresas, produtos, números e frases entre aspas devem ser fielmente retidos.
- Linhas concisas — prefira frases curtas em chinês que se encaixem no ritmo de vídeos curtos. Legendas longas e rolantes matam a retenção.
- Reequilibre entre cues quando necessário — se uma frase em inglês estiver dividida em 3 cues, você pode redistribuir o texto chinês nessas mesmas 3 cues. Preserve a ordem das cues.
- NÃO colapse cues — um SRT em inglês com muitas cues (40) deve produzir aproximadamente 35–45 cues em chinês, não 10. O modo de falha padrão é ligeiramente muitas cues, não poucas demais.
- Remova apenas duplicatas verdadeiras — legendas automáticas geralmente repetem o mesmo fragmento em cues consecutivas. Você pode remover a duplicata, mas mantenha a primeira ocorrência.
- Se a fonte já for em chinês — não traduza. Apenas limpe ruídos óbvios de legendas automáticas (fragmentos repetidos, caracteres quebrados).
6d. Gerar Título e Descrição
Para cada clipe, crie:
Título (para a sobreposição do primeiro segundo):
- Afiado, clicável, opinativo
- Alvo ≤ 12 caracteres chineses para caber bem na tela no tamanho de fonte 48
- Pode ser provocativo ou contrário, mas deve ser fiel ao significado do orador
- Deve criar curiosidade, tensão ou urgência para continuar assistindo
Descrição (para distribuição na plataforma):
- ≤ 140 caracteres chineses
- Deve mencionar: quem está falando, de que programa/entrevista é, sobre o que é o tópico, qual é a principal afirmação ou conclusão
Escreva ambos em studio/<slug>/exports/<pasta-do-clipe>/metadata.txt:
标题:AI终将取代一切?
描述:Sam Altman 在 Lex Fridman 播客中谈到 AGI 的时间表——他认为大多数人严重低估了 AI 的发展速度,未来三年将改变一切。
6e. Queimar Legendas em Chinês + Título no Vídeo
python3 -m corekit.render_hardsubs \
"studio/<slug>/exports/<pasta-do-clipe>/clip.mp4" \
"studio/<slug>/exports/<pasta-do-clipe>/clip.zh.srt" \
"studio/<slug>/exports/<pasta-do-clipe>/clip.hardsub.mp4" \
--title "<o-título-da-etapa-6d>"
CRÍTICO: Passe o arquivo chinês clip.zh.srt, NÃO clip.src.srt. Este é o erro mais comum do agente — passar a legenda no idioma de origem em vez da tradução.
A etapa de queima irá:
- Detectar automaticamente libass; se indisponível, recorrer à renderização drawtext (nenhuma ação necessária de sua parte)
- Selecionar automaticamente o melhor codificador H.264 para a máquina atual
- Renderizar o título centralizado no tamanho de fonte 48 com contorno preto de 3px durante o primeiro segundo
- Renderizar as cues de legenda na parte inferior do quadro pelo resto do clipe
Verifique se o arquivo de saída clip.hardsub.mp4 existe e tem um tamanho de arquivo maior que clip.mp4 (a cadeia de filtros adiciona dados visuais).
6f. Anexar à Cópia de Empacotamento
Após cada clipe ser exportado, anexe seu título e descrição ao arquivo de empacotamento combinado:
studio/<slug>/intel/packaging-copy.md
Formato:
## clip-01: AI终将取代一切?
**标题**: AI终将取代一切?
**描述**: Sam Altman 在 Lex Fridman 播客中谈到 AGI 的时间表...
**文件**: studio/<slug>/exports/01-ai-will-replace/clip.hardsub.mp4
**时长**: 1m 19s
---
7. Saída Final
Após todos os clipes serem exportados, retorne ao usuário:
- Pasta de ativos de origem:
studio/<slug>/intake/ - Lista de candidatos: a tabela completa da etapa 5 (timestamps, duração, título, resumo)
- Arquivo de empacotamento:
studio/<slug>/intel/packaging-copy.md - Clipes exportados: liste cada caminho de
clip.hardsub.mp4
Referência da Estrutura do Espaço de Trabalho
studio/<slug-do-video>/
├── intake/ # ativos brutos do YouTube
│ ├── <título> [<id>].mp4 # vídeo de origem (nome do arquivo do yt-dlp)
│ └── <título> [<id>].<idioma>.srt # legenda de origem
├── intel/ # artefatos de análise
│ ├── transcript.json # cues de legenda estruturadas (da etapa 3)
│ ├── selected_clips.json # decisões de clipe (da etapa 4)
│ ├── candidate-board.md # tabela de revisão (da etapa 4)
│ └── packaging-copy.md # todos os títulos + descrições (da etapa 6f)
└── exports/ # uma pasta por clipe exportado
└── 01-<slug>/
├── clip.mp4 # corte bruto (sem legendas)
├── clip.src.srt # legenda no idioma de origem (janelada)
├── clip.zh.srt # legenda traduzida para chinês
├── clip.hardsub.mp4 # entrega final (legendas queimadas + título)
└── metadata.txt # título + descrição para este clipe
Referência dos Módulos
| Módulo | Invocação | Argumentos |
|---|---|---|
corekit.fetch_source | python3 -m corekit.fetch_source <url> <dir_saida> | URL do YouTube, diretório de saída |
corekit.subtitle_to_json | python3 -m corekit.subtitle_to_json <entrada.srt> <saida.json> | caminho do arquivo SRT, caminho de saída JSON |
corekit.cut_video | python3 -m corekit.cut_video <entrada.mp4> <seg_inicio> <seg_fim> <saida.mp4> | vídeo de origem, segundo de início (float), segundo de fim (float), caminho de saída |
corekit.window_subtitles | python3 -m corekit.window_subtitles <entrada.srt> <seg_inicio> <seg_fim> <saida.srt> | SRT de origem, segundo de início (float), segundo de fim (float), caminho de saída |
corekit.render_hardsubs | python3 -m corekit.render_hardsubs <entrada.mp4> <entrada.srt> <saida.mp4> --title "..." | vídeo do clipe, SRT em chinês, caminho de saída, texto do título opcional |