O que EdgeSpeak Karaoke faz?
Crie legendas karaokê a partir de uma única requisição de transcrição do EdgeSpeak. Use os scripts Node.js integrados (zero dependências) para geração determinística de ASS, pré-visualização de estilos em quadros reais e renderização com FFmpeg.
Deixe o usuário escolher o visual
Colete o caminho de origem, o local de saída e se o usuário deseja ASS, legendas incorporadas (hard subtitles) ou ambos. O estilo é a única decisão que o usuário pode ver e com a qual pode discordar, portanto, trate-a como sendo dele por padrão:
- Explícito: respeite o preset nomeado ou as substituições. Os presets disponíveis são
classic,minimal,boxedehigh-contrast. - Automático: somente quando o usuário realmente entrega a decisão — "você escolhe", "tanto faz", "só faz rápido", "usa o padrão". Escolha da tabela abaixo e continue sem bloquear.
- Pré-visualizar e perguntar — o padrão sempre que o usuário não declarou preferência de estilo. Renderize cada preset em quadros reais da fonte, mostre os PNGs com a capacidade de visualização de imagens do runtime e faça uma pergunta compacta. Um terminal pode listar caminhos e descrições, mas texto ANSI não é uma pré-visualização visual fiel.
Silêncio não é delegação. Um usuário que nunca mencionou estilo geralmente não viu as opções, em vez de ter decidido ignorá-las. Perguntar custa uma troca curta; adivinhar errado custa uma re-renderização do vídeo inteiro, e com legendas incorporadas esse é o caminho caro.
Para saída bilíngue, qual idioma fica em cima é o mesmo tipo de escolha visível — inclua-a nessa única pergunta em vez de perguntar duas vezes.
Nunca renderize pré-visualizações sem mostrá-las. --preview-media renderiza todos os quatro presets em cada execução, então no momento em que o comando termina, a comparação completa já existe em disco. Abrir um PNG, escolher silenciosamente e relatar apenas o vencedor esconde uma troca que o usuário tinha o direito de ver.
Para o modo automático — e para semear a recomendação oferecida junto com as pré-visualizações — inspecione quadros representativos da fonte e use estes padrões:
| Tipo de Conteúdo | Preset |
|---|---|
| Paisagem geral ou conteúdo misto | classic |
| Fundo limpo e predominantemente escuro | minimal |
| Fundo movimentado, claro, slides ou gravação de tela | boxed |
| Vídeo vertical/mobile ou fundo consistentemente difícil | high-contrast |
Quando a luminosidade varia na fonte — cenas escuras e claras no mesmo vídeo — nenhum quadro único resolve a escolha. Renderize pré-visualizações em dois timestamps contrastantes e compare ambos, porque um preset que vence em um quadro claro pode ficar invisível em um escuro.
Instruções da solicitação atual vencem. Se presente, leia também as preferências opcionais de .edgespeak-skills/edgespeak-karaoke/EXTEND.md e depois ~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md; preferências do projeto vencem as do usuário. Preferências úteis incluem preset, fonte, tamanho da fonte, cores ASS, margem, formato de saída e qualidade.
Transcreva e alinhe uma vez
-
Confirme que a fonte existe e inspecione sua duração, dimensões e contêiner com
ffprobe. -
Chame
edgespeak_transcribe_fileuma vez:{ "path": "/caminho/absoluto/midia-fonte", "timestamps": "word", "start_margin": 0, "end_margin": 0 }Adicione
min_chars/max_charssomente quando o usuário solicitar comprimentos diferentes de legenda. Adicionemodelsomente quando o usuário nomear um. Se a localidade importar, inspecioneedgespeak_list_modelse não escolha um modelo remoto sem consentimento. -
Não chame
edgespeak_alignapós uma transcrição com timestamps de palavra bem-sucedida. Esta requisição já executa o caminho de alinhamento forçado local inline do EdgeSpeak e retornasegments[].words[]. -
Para uma resposta MCP longa, use
artifact_json_path. Para uma resposta inline, salve o objetoresultcomo JSON. O conversor aceita tanto JSON de transcrição direto quanto um wrapper comresult. -
Exija temporização de palavra não vazia em cada segmento temporizado. Nunca invente temporização de palavra ou recorra silenciosamente à temporização de segmento.
Use edgespeak_align somente quando o usuário forneceu uma transcrição final externa ou editou materialmente o texto do ASR. O alinhamento deve usar a sequência final de palavras; nunca mantenha timposts obsoletos após edições.
Requisitos
- Node.js 18 ou mais recente para os scripts integrados.
- FFmpeg compilado com
libass, além deffprobe— um executável separado que também deve estar no PATH. Cada pré-visualização e cada queima passa pelo filtroass, então um FFmpeg sem libass falha comNo such filter: 'ass'independentemente do preset selecionado. Queimar para MP4/MOV/MKV/TS também precisa delibx264; WebM precisa delibvpxelibopus. Homebrew e os pacotes das principais distribuições incluem todos esses. edgespeak-cli(ou o aplicativo EdgeSpeak) para transcrição, que roda em macOS Apple Silicon, Linux x86_64 e Windows x64. No Windows, instale o aplicativo de desktop EdgeSpeak, que inclui a CLI. No macOS e Linux, usecurl -fsSL https://edgespeak.com/install.sh | sh(autocontido, sem necessidade de aplicativo de desktop; no Linux o instalador detecta automaticamente GPUs NVIDIA e instala um runtime com CUDA). OminCliVersionno frontmatter é a CLI mais antiga para a qual este skill foi escrito — seedgespeak-cli --versionfor mais antigo, ou uma flag documentada estiver faltando em--help, executeedgespeak-cli update.
Quando uma execução falha em uma dependência ausente, relate qual verificação falhou em vez de tentar novamente:
node --version # v18+
ffprobe -version # deve existir junto com ffmpeg
ffmpeg -filters | grep -w ass # o renderizador ASS (libass)
ffmpeg -encoders | grep -w libx264 # saída H.264
Gere ASS e pré-visualizações
Gere o preset selecionado:
node <skill-dir>/scripts/karaoke-ass.mjs /caminho/para/transcricao.json \
-o /saida/fonte.karaoke.ass \
--style classic \
--title "Título da fonte"
Para apresentar a escolha, renderize cada preset em uma dica ativa da fonte real. Este é o caminho padrão, não um caso especial — e cada PNG que produz deve ser mostrado:
node <skill-dir>/scripts/karaoke-ass.mjs /caminho/para/transcricao.json \
-o /saida/fonte.karaoke.ass \
--style classic \
--preview-media /caminho/para/video-fonte \
--preview-dir /saida/fonte.karaoke-previews
Use --preview-at <segundos> quando outro quadro for mais representativo e execute-o duas vezes com timestamps diferentes quando a fonte misturar cenas claras e escuras. Liste presets com --list-styles. Ajuste fino com --font, --font-size, --margin-v, --primary, --secondary, --outline e --back; cores ASS usam &HAABBGGRR. O script preserva os limites de segmento do EdgeSpeak e mapeia apenas durações/lacunas alinhadas para tags \kf / \k.
O espaçamento entre palavras vem do text da própria dica, não de um espaço por palavra. O alinhamento forçado anexa pontuação à palavra que a segue, então cada entrada words[] é uma substring de text e suas posições só avançam — o gerador percorre text uma vez e reutiliza o que realmente está entre duas palavras. Isso é o que mantém alta-performance hifenizado (o alinhamento divide em alta e performance, e o hífen não pertence a nenhuma) e o que mantém o CJK sem espaços em vez de renderizar 本地转录 como 本 地 转 录. Se uma palavra não puder ser encontrada em text, o gerador recorre a espaços simples em vez de adivinhar.
Karaokê bilíngue
Quando a transcrição carrega uma translation em cada segmento — o que edgespeak-translate escreve — o gerador emite duas linhas por dica e não precisa de flag extra:
node <skill-dir>/scripts/karaoke-ass.mjs /caminho/para/transcricao.zh.json \
-o /saida/fonte.karaoke.ass --style boxed
Ambas as linhas vivem em um evento Dialogue separado por \N, então o ASS as empilha como um único bloco a partir da margem compartilhada. Dois eventos separados ancorariam cada um nessa margem e se sobreporiam.
--layout translation-top(padrão) coloca a tradução acima da fonte;source-topinverte, para espectadores que acompanham no idioma de origem. A linha superior renderiza no tamanho do preset e a inferior em 72%, para que o olho se fixe no idioma principal de qualquer maneira.--layout source-onlyignora as traduções e produz o arquivo monolíngue.- Apenas a linha fonte desliza. As temporizações das palavras descrevem o áudio fonte, então a tradução não recebe tags
\k— ela mantém um preenchimento simples durante toda a dica. Distribuir a duração da dica entre os caracteres da tradução seria temporização inventada; não a adicione. Para temporização real de palavras no idioma de destino, sintetize comedgespeak-broadcaste alinhe esse áudio.
A fonte não é opcional — em nenhuma linha
O libass não substitui fontes por glifo como um navegador faz. Texto CJK em uma fonte de estilo latino renderiza como caixas vazias — silenciosamente, durante toda a queima. Cada preset inclui uma fonte latina, então o gerador escolhe por script em vez de herdar a do preset. Isso se aplica à linha fonte também, não apenas à tradução: uma transcrição em chinês sem --font queimaria como uma fileira de caixas.
- O script é detectado a partir do texto da própria linha e combinado via
fc-match :lang=<tag>, pegando um alias de família ASCII único (uma lista de aliases quebraria a linha de estilo delimitada por vírgula do ASS). --font <nome>(fonte) e--translation-font <nome>(tradução) substituem, e são rejeitados quandofc-listdiz que essa fonte não cobre o idioma detectado. Não contorne o erro escolhendo outra fonte latina — verifique o que cobre o script comfc-list :lang=zh-cn family.- Texto latino mantém a fonte do preset inalterada; a troca só acontece quando o preset não cobriria o script.
- Sem fontconfig, a seleção automática falha ruidosamente; passe a fonte explicitamente. A execução relata
source_font_verified: false/translation_font_verified: falsequando a cobertura não pôde ser verificada, então relate essa ressalva em vez de afirmar que a fonte está boa. - A execução relata
source_font/source_scriptsempre que a fonte não é latina.
Uma transcrição parcialmente traduzida é rejeitada de imediato — significa que a etapa de tradução parou cedo, e emitir dicas apenas da fonte para o restante passaria um arquivo incompleto como concluído.
Queime legendas incorporadas (hard subtitles)
Quando a fonte tem vídeo e o usuário quer legendas incorporadas:
node <skill-dir>/scripts/render-hardsub.mjs \
/caminho/para/video-fonte \
/saida/fonte.karaoke.ass
O padrão --format source preserva o contêiner da fonte quando prático:
- MP4/M4V/MOV -> mesma extensão com H.264/AAC.
- MKV -> MKV com H.264 e áudio copiado.
- WebM -> WebM com VP9/Opus.
- TS/M2TS -> mesma extensão com H.264/AAC.
- Extensões de fonte não suportadas/ambíguas -> fallback para MKV, relatado como
container_fallback: true.
Legendas incorporadas sempre exigem re-codificação de vídeo; preservar o contêiner não significa copiar o codec de vídeo da fonte. Use --format mp4|mov|mkv|webm ou um -o explícito somente quando o usuário solicitar um formato de entrega diferente. Use --overwrite somente com autorização.
Corresponder à taxa de bits da fonte
Re-codificar em qualidade fixa ignora a taxa de bits com que a fonte foi enviada, e a diferença pode ser grande: queimar CRF 21 em um arquivo AV1 enxuto de 1,5 Mbps produz uma cópia H.264 de 4,2 Mbps — 2,8x a taxa de bits da fonte, quase 3x o tamanho do arquivo, sem ganho visível. O script, portanto, sonda a fonte e deriva um teto -maxrate / -bufsize a partir de sua taxa de bits, escalado por quanto menos eficiente o codec de saída é (H.264 precisa de aproximadamente 1,6x a taxa de bits de AV1 para qualidade comparável). A qualidade ainda vem do CRF; o limite apenas impede que ultrapasse a fonte.
Isso é automático para alvos x264. VP9/WebM é deixado intacto porque o perfil .webm fixa -b:v 0 para modo de qualidade constante. O relatório inclui source_video_bitrate, video_bitrate e a decisão bitrate_cap — compare os dois primeiros ao relatar o resultado.
Substitua apenas quando o usuário solicitar uma taxa de bits ou nível de qualidade específico:
--crf <n>define o alvo de qualidade (menor é melhor, 21 padrão para H.264).--maxrate <taxa>substitui o teto derivado, ex.:--maxrate 4M.--maxrate nonedesativa o teto completamente e restaura o comportamento CRF simples.
A taxa de bits também é a alavanca para o tamanho do arquivo. Quando um usuário reclamar do tamanho da saída, cite a taxa de bits da fonte junto com a taxa de bits da saída antes de propor uma mudança, e lembre-se que conteúdo plano de ilustração ou gravação de tela comprime muito mais do que ação ao vivo — o texto da legenda em si permanece nítido mesmo em CRF 28, então nunca é a restrição.
Fallback CLI
Recorra a edgespeak-cli sempre que o MCP não puder fazer o trabalho — incluindo quando o servidor MCP estiver ativo, mas suas ferramentas falharem. O caso mais comum: o aplicativo de desktop não está em execução, então toda ferramenta MCP do EdgeSpeak retorna runtime_error: could not reach gateway. Isso não é uma instalação quebrada e não é algo para tentar novamente; o servidor MCP de longa duração deliberadamente nunca inicia um motor próprio (um servidor residente segurando o motor colidiria com o aplicativo que o usuário abrir em seguida). A CLI não tem essa restrição — ela inicia o motor no dispositivo por conta própria. Então trate could not reach gateway de qualquer ferramenta MCP EdgeSpeak como "use a CLI agora", não como uma falha a ser relatada.
Se o comando edgespeak-cli não for encontrado, instale o aplicativo de desktop EdgeSpeak no Windows x64, ou use curl -fsSL https://edgespeak.com/install.sh | sh no macOS Apple Silicon e Linux x86_64 (autocontido, sem necessidade de aplicativo de desktop; CUDA detectado automaticamente no Linux).
edgespeak-cli transcribe /caminho/para/midia-fonte -o /saida/transcricao.json \
--start-margin 0 --end-margin 0
O JSON da transcrição da CLI já contém segments[].words[]. Não execute edgespeak-cli align em texto que o mesmo comando transcribe acabou de produzir. Ao contrário dos scripts integrados (que se recusam a substituir saídas existentes sem --overwrite), edgespeak-cli -o sobrescreve um arquivo existente silenciosamente — se o caminho da transcrição já existir, confirme com o usuário antes de sobrescrever ou escolha um novo caminho.
Validação e relatórios
- Dê orçamentos de tempo realistas para MCP e FFmpeg; não interrompa processamento saudável e silencioso.
- Mantenha `start_...