Communitygithub.com

Chengfeng Subtitle — legendas calculadas a partir do corte

Legenda um vídeo falado já editado direto da transcrição palavra por palavra e do registro de cortes: calcula os tempos após o corte, corrige nomes mal ouvidos com seu dicionário e roteiro, divide as frases em telas e revisa cada tela no Studio.

O que é Chengfeng Subtitle — legendas calculadas a partir do corte?

Short-form Editing, passo 2 (legendar): video-skill-ku-chengfeng-subtitle. As legendas guardam IDs de palavras e o texto exibido, nunca segundos, então o tempo é recalculado a partir do registro toda vez e telas desatualizadas são apontadas com precisão. Rode de novo sempre que cortar outra frase e depois passe para a exportação.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/2789927464king-jpg/video-skill-ku/tree/HEAD/chengfeng-videocut-skills/plugins/chengfeng-videocut/skills/chengfeng-subtitle

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Legendas

Isto é uma ação, não uma etapa de um fluxo. Deve ser executada quando o usuário a solicitar – pode ser feita logo após a edição, ou novamente após ele ter removido algumas falas.

Tem apenas um pré-requisito: o livro-razão já deve existir. Não porque vem depois da edição, mas porque, sem ele, não é possível saber quais falas permanecem e em que segundo do vídeo final cada uma se encontra.

Entrada   edit-list.json (livro-razão), transcript.json (transcrição palavra por palavra)
Saída     subtitles.json

Ao terminar, pare. Não oriente o usuário para o próximo passo.

Primeiro, leia e execute o contrato de fase do Skill de negócio. Critérios de julgamento conforme Regras de correção de legendas. Para grafia de termos específicos, consulte o Dicionário de termos de IA.

Quem decide o quê

Esta é a base do que se segue; todo o resto deriva daqui.

Edição de narração   decide "quais falas ficam e em que momento"   ← única verdade temporal
Legendas            decide "que texto aparece na tela"             ← única verdade de exibição

Uma tela de legenda armazena uma lista de IDs de palavras + texto exibido, não armazena segundos. O tempo é calculado a partir do livro-razão a cada execução. Assim, não há uma segunda linha do tempo que possa divergir. Falhas podem ser localizadas com precisão por tela: "as palavras das telas 7 e 12 foram cortadas", em vez de uma imprecisa "legendas podem estar desatualizadas".

A legenda armazena seu próprio texto intencionalmente. A transcrição responde "o que ele disse", a legenda responde "o que se mostra para as pessoas" – pontuação, vícios de linguagem removidos, grafia formal de termos próprios, tudo isso deve ser diferente. Forçar uma única string a fazer ambos os trabalhos impede, por exemplo, a adição de vírgulas.

0. Prontidão

Execute primeiro a "verificação de prontidão" de Verificar atualizações – se os skills estão atualizados e o Runtime é compatível; a raiz do plugin também é localizada ali (substitua <raiz-do-plugin> nos comandos abaixo pelo caminho literal). Prossiga somente se o status for "pronto"; para "requer nova sessão" ou "parar", siga as instruções (incluindo a proibição de "interfaces substitutas customizadas"). O Skill de negócio não contém lógica de ambiente.

Se o resultado da prontidão for runtime.kind=desktop-managed, reutilize diretamente a CLI estável já instalada pelo aplicativo desktop e o mesmo serviço launchd/windows-task; não analise caminhos do Electron, instale dependências adicionais ou inicie um segundo Runtime.

1. Validação de entrada

node "<raiz-do-plugin>/scripts/ensure-running.cjs" --json
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" inspect "<diretório-do-projeto>" --json
ValidaçãoSe falhar
edit-list.json existe e contém segmentosInforme que o livro-razão está faltando e peça ao usuário para executar a edição da narração. Não corte você mesmo.
transcript.json existeO projeto não está pronto; pare. Não crie uma transcrição você mesmo.

Não valide a existência de source_cut.mp4 nem realize transcrição. A legenda não precisa de nenhum dos dois – veja a próxima seção.

2. Correção de texto: primeiro dicionário, depois script

Não é necessário retranscrever. A transcrição palavra por palavra já contém os timestamps; o livro-razão sabe quais trechos permanecem – em que segundo do vídeo final cada palavra cai é calculado, não obtido por nova audição:

O segundo da palavra no vídeo original   está na transcrição
Quais trechos permanecem                 está no livro-razão
O segundo da palavra no vídeo final      calcula-se a partir dos dois

Enviar novamente para ASR é apenas reouvir a mesma fala: custa dinheiro, tempo e, pior, o resultado é inferior – os termos próprios precisarão ser corrigidos novamente. (transcript retranscribe é um resquício do design anterior, quando a legenda dependia da transcrição do vídeo editado para obter a linha do tempo. Com a legenda ancorada por IDs de palavras, esse problema desapareceu. Não o use ao fazer legendas.)

Duas ferramentas diferentes, ambas devem ser usadas.

# Dicionário: grafia fixa para este falante, sem necessidade de evidências
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript dictionary "<diretório-do-projeto>" --dictionary "<raiz-do-plugin>/references/ai-term-dictionary.md" --json

# Script: somente se o autor tiver o roteiro em mãos; cada correção exige evidência
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript align "<diretório-do-projeto>" --script "<arquivo-do-roteiro>" --json
Dicionário   sempre escreva assim            ignora contexto, corrige diretamente, lista as alterações
Script       só escreva assim se o contexto   exige evidência para cada ocorrência; se não confirmar,
             corresponder                    reporta "incerto", sem adivinhar

Por que o dicionário é obrigatório e o script sozinho não basta: as narrações podem ser regravadas. Em projetos reais, a mesma frase foi gravada quatro vezes; assim, contextos como "conector X" e "X é" aparecem várias vezes. O align só pode reportar "incerto" – ele não adivinha, porque errar um nome é pior do que ouvir errado. De três ocorrências de "X", ele só corrige uma. O dicionário não tem esse problema: na obra deste falante, "X" é "X".

Há apenas um dicionário, no nível do plugin: references/ai-term-dictionary.md. Ele corrige a transcrição, e tanto a edição da narração quanto as legendas consomem a mesma transcrição. Não crie outro dicionário neste skill.

Após a correção, revise a lista. O dicionário ignora contexto, portanto também pode corrigir erroneamente – por exemplo, normalizar "Skills" (Claude Skills, nome próprio no plural) para "Skill". Se vir algo errado, corrija o dicionário; não aplique remendos no comando.

transcript align apenas reporta; não aplica. Para aplicar suas propostas, converta corrections em [{wordId, text}] e execute:

node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript correct "<diretório-do-projeto>" --file "<arquivo-de-correção>" --json

Após corrigir a transcrição, as telas de legenda que referenciam essas palavras são automaticamente atualizadas na mesma etapa, retornando subtitles.updated. As que não puderem ser alteradas (porque a linha foi reescrita manualmente) vão para needsAttention; reporte-as para revisão humana, sem adivinhar.

Quando nem o dicionário nem o script confirmam uma grafia correta, não adivinhe. Reporte para o usuário adicionar ao dicionário – uma vez adicionado, o próximo vídeo estará automaticamente correto; adivinhar agora exigirá nova adivinhação na próxima vez.

3. Divisão em telas

node "<raiz-do-plugin>/scripts/videocut-cli.cjs" subtitle build "<diretório-do-projeto>" --json

Quatro regras, em ordem:

① Fala removida aqui       Se os lados do trecho removido estão adjacentes na linha do tempo
                           e não têm relação de sentido. "Remover silêncio" não conta – cortar
                           uma pausa no meio de uma frase não deve quebrar a frase.
② Pontuação                 Qualquer pontuação fornecida pelo ASR, incluindo ponto final e vírgula –
                           **mesma granularidade da divisão da edição da narração**, a quebra
                           ocorre no mesmo ponto. A pontuação é mais forte que qualquer evidência
                           temporal: o falante pode dizer duas frases sem pausa, ou pausar no meio
                           de uma frase.
③ Limite de parágrafo + pausa  **Use somente quando a palavra não tiver pontuação.** É "quando
                              não há pontuação, assume-se que o parágrafo terminou". Se houver
                              pontuação, a regra ② e a vírgula devem gerenciar – elas consideram
                              se a tela é longa o suficiente; a regra ③ não. (Aplicar ③ em limites
                              com pontuação, em projeto real, aumentou de 40 para 43 telas,
                              criando mais telas curtas.)
④ Pausa longa para o público    Para quebrar dentro de uma frase, o silêncio precisa ser mais
                              longo.

A edição da narração e a legenda consomem a mesma pontuação, com a mesma granularidade: uma vírgula = um segmento / uma tela.

Fragmentos (uma ou duas palavras) são mesclados, mas não entre pontos finais – "Você vê" inicia uma nova frase, não é o final da anterior; mesclar resultaria em "...chamar Grok CLI você vê", duas frases coladas.

Frases curtas ditas rapidamente permanecem (em projeto real, "Toda manhã" e "Executar tarefa" duravam 0,6 segundos cada). Isso é como ele realmente fala; não alerte. Uma vírgula por tela naturalmente produz essas telas; alertar equivaleria a alertar sobre fala normal – com muitos alertas, ninguém os lê.

As telas restantes, mais longas que o ideal, são divididas uniformemente em várias telas, uma tela por linha. Se aparecerem fragmentos de uma ou duas palavras, significa que o limite ② não era um ponto final; mescle o fragmento de volta à tela anterior.

O comando retorna quatro itens, todos devem ser revisados:

stale              Telas alteradas pela edição – informe exatamente o número da tela e quais palavras foram perdidas
tooFast            Muitas palavras, tempo insuficiente para leitura
transcriptMoved    A transcrição não é mais a original

Quando já existem legendas – pare e pergunte aqui

Sem a opção --replace, o comando se recusará a executar. Este é o único ponto neste skill onde é necessário obter consentimento do usuário, pois --replace descarta o trabalho humano de divisão e redação, irrecuperável pelo produto.

O usuário quer alterar algumas palavras   Não execute build. Deixe-o editar diretamente no Studio
                                          ou informe quais telas alterar.
O usuário quer recomeçar do zero           Após confirmação, adicione --replace.

4. Revisão: tela por tela no Studio

node "<raiz-do-plugin>/scripts/videocut-cli.cjs" open "<diretório-do-projeto>" --json

Após abrir, vá para a guia "Legendas" na barra lateral esquerda. Uma linha por tela: à esquerda, o número da tela e o tempo; à direita, o texto. Clique para editar diretamente.

  • Enter = inicia uma nova tela a partir do cursor
  • Backspace no início da linha = mescla com a tela anterior
  • Na barra lateral direita, em "Parâmetros → Legendas", escolha um dos quatro predefinidos; um estilo para todo o vídeo
  • Na tela, a legenda é exibida diretamente; posição e tamanho da fonte são proporcionais à imagem – a prévia e o vídeo final usam os mesmos valores

Durante a revisão, pelo menos confirme com o usuário: os termos próprios estão corretos? Há palavras engolidas? A quebra de linha soa natural? O tempo de exibição é suficiente para a leitura?

5. Até subtitles.json

Esta etapa está concluída. Não faça corte físico, storyboard, animação nem renderização do vídeo final. Também não apresse o usuário para o próximo passo.

O relatório deve ser separado: o readback estruturado do Produto é API/readback PASS; a revisão dos quadros reais do navegador no mesmo projeto é visual frame PASS; se ninguém tiver verificado visualmente se as legendas correspondem às imagens, o status deve ser human listening UNVERIFIED. Não substitua por DOM, captura de tela ou detecção de arquivo.

Limite: gravação na imagem não faz parte desta etapa

O formato de saída definido é gravação na imagem, e a imagem é gerada durante a exportação. A saída da legenda é subtitles.json – todas as dimensões são porcentagens da imagem; a exportação as converte em pixels de acordo com a resolução de saída. Ambos os lados usam os mesmos valores.

O mp4 exportado hoje não contém legendas, pois essa etapa ainda não foi realizada. Deixe claro no relatório essa consequência; não se limite a dizer "legendas prontas" – o usuário pode pensar que o vídeo final as contém.

Recuperação e falhas

  • subtitles_exist: Já existem legendas. Pergunte primeiro, não use --replace diretamente.
  • revision_conflict: Outra instância também está escrevendo. Releia, não sobrescreva automaticamente.
  • Dicionário reporta "Linha N não pôde ser interpretada": é uma linha de tabela mal formatada. A regra reconhece apenas linhas de tabela (| grafia correta | erro comum de reconhecimento |); prosa e listas são ignoradas silenciosamente.
  • transcript correct reporta "must not change any word id, time or gap flag": a proposta de correção de texto incluiu alterações de tempo. Corrija apenas o texto.
  • runtime_unhealthy: Não reinstale em loop.
  • Em caso de falha, nunca descreva "transcrição concluída" como "legendas prontas". O resultado do ASR é matéria-prima, não produto final.

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

2789927464king-jpg/video-skill-ku

剪辑环境的唯一管理者:就绪检查(skills 是否最新 → Runtime 是否配套)、Skills 更新激活、Runtime 安装与体检。用户说检查更新、安装剪辑环境、装播放器、检查剪辑环境、剪辑环境就绪了吗、配置转录凭证时使用;业务 Skill(剪口播/字幕/画面/导出)第 0 步也引用本 Skill 的就绪检查。不用于剪辑、字幕、画面、导出本身或项目数据迁移。

2789927464king-jpg/video-skill-ku

剪辑中文口播原素材:逐词转录、词典修字出修字表、五轮扫描找口误与重复、汇总表与重复句子表、打开 Studio 让用户复核、复盘沉淀用户偏好与词典。只产出一份已复核的删词账本,不切媒体、不做字幕、不做分镜动画。用户说剪口播、处理口误、生成口播基础素材、继续剪口播,或确认卡回传 action=return_cut_review 时使用。不要用于执行物理剪切、导出剪后视频、单独安装、单独打开工作台或口播分镜成片。

2789927464king-jpg/video-skill-ku

把剪好的口播烧成一个成片文件:账本切片段、推近、字幕、HTML 画面层,一次全部烧进 mp4。用户说导出、出成片、烧字幕、渲染、导出视频、生成最终文件时使用。不要用于生成删词候选、写字幕、做画面动画。

2789927464king-jpg/video-skill-ku

整理、脱敏并上报 chengfeng-videocut 的 GitHub Bug。用户说上报 Bug、反馈剪口播问题、提交 GitHub Issue、这个问题告诉开发者,或要求继续提交已预览的 Bug 草稿时使用。不要用于功能建议、普通排错、代码提交或未获用户确认的自动上报。

2789927464king-jpg/video-skill-ku

操作 chengfeng-videocut 剪辑工作台的已有工程,通过 Runtime CLI 查工程与词句位置、添加或替换画面覆盖层、移除画面、删除明确指定的词句或片段、拆分裁剪移动已有片段、调整画布比例并回读核验。用户说插入片段、删掉这句、移除动画、换个画面、调整顺序或管理时间线时使用;先区分画面覆盖与主轨顺延插入,不负责自动判断口误、创作动画、制作字幕、导出或排查安装故障。

2789927464king-jpg/video-skill-ku

Create Ian Xiaohei-style HTML/SVG motion illustrations for Chinese articles, scripts, storyboard scenes, workflow explanations, concept metaphors, and short video visual aids. Use when the user asks for 小黑 SVG、漫画感 HTML、分层 SVG 动效、把小黑生图做成 HTML/SVG、可编辑矢量动效、口播流程动画、手绘漫画动效、正文配图动画, or wants a Xiaohei illustration style adapted into controllable HTML/SVG/GSAP output instead of raster image generation.

2789927464king-jpg/video-skill-ku

给剪好的口播配画面:在录屏上盖 HTML 层(圈重点标注 / 小黑整屏动画 / 推近),层绑字幕屏、由播放器逐帧驱动、直接在预览里看。用户说做分镜、配画面、加动画、圈重点、B-roll、做 storyboard 时使用。不要用于删词剪辑、字幕、物理剪切或成片渲染。

2789927464king-jpg/video-skill-ku

剪映 (JianYing) AI自动化剪辑的高级封装 API (JyWrapper),提供开箱即用的 Python 接口,支持录屏、素材导入、字幕生成、Web 动效合成及项目导出。全面适配 MacOS (Apple Silicon/Intel) 与 Windows,支持 v5.9+ (draft_info.json) 架构、工程自修复、智能配音字幕及录屏变焦。

Habilidades Relacionadas