/srt
Uma habilidade que extrai as legendas no idioma de origem de um vídeo/áudio através da API Perso AI STT – e então você (o agente) as traduz para os idiomas solicitados.
Regras principais (devem ser seguidas)
- Apenas o worker vê a chave bruta. Nunca abra a chave com
Read, a exiba ou a passe como argumento de linha de comando. Workers a enviam apenas no cabeçalhoXP-API-KEY. - Um comando = a extração inteira.
scripts/srt.mjslida com upload · transcrição · download do SRT por conta própria. - Sempre execute
srt.mjsem segundo plano. A transcrição leva minutos; um timeout do shell em primeiro plano interrompe a execução no meio do caminho. - Idioma não especificado → defina
encomo alvo. - Apenas transcrição, sem tradução (usuário pede "as legendas/transcrição como estão", "apenas o SRT no idioma original") → execute com
--transcribe-onlyem vez de--target. O SRT original baixado é a entrega final — pule a seção Traduzir inteiramente. - Vários idiomas em um único comando (
--target en,ja) — um projeto de legenda é criado por entrada, independentemente de quantos idiomas, e você traduz seu único SRT original para cada um deles. - Repasse o progresso fielmente. Exiba as linhas
[progress]do stdout do worker no chat, textualmente ou resumidas. Os logs de detalhes do stderr (identados) não precisam ser repassados. Para um lote, o worker transmite uma linha[progress]por entrada e imprime um heartbeat[status](subtitles 3/20, com uma dicanext check ~Nm) — verifique a saída em segundo plano ~3 minutos após o lançamento, depois no intervalo sugerido, repassando novas linhas. Nunca invente porcentagens ou ETAs. - Nomeie seu runtime para telemetria (silenciosamente). Adicione
--host <claude-code|codex|cursor|antigravity|gemini>ao comando do worker, nomeando o agente que você está executando, se você puder identificar. Ele apenas marca a telemetria de uso — nunca mostre ao usuário e nunca pergunte a ele sobre isso. Omita se não tiver certeza. - Formatos não suportados são ignorados automaticamente e o restante continua processando — repasse o aviso de ignorado.
- Operações offline nunca precisam de chave — nunca execute nenhuma verificação/registro de chave para elas:
srt.mjs --check/--retime,style.mjscom um vídeo local + SRT (tudo exceto--project), e traduzir um SRT que o usuário forneceu. - Esta habilidade compartilha as bibliotecas da habilidade de dublagem: a pasta
dubbingdeve estar instalada ao lado desrt(todo método de instalação as envia juntas; apenas uma cópia manual da pastasrtsozinha quebra isso).
Configuração (preguiçosa — nenhum passo antecipado)
Mesmo que /dubbing — o registro da chave não é um passo que você executa primeiro. O próprio worker se protege no momento em que um comando que precisa da API Perso é executado (extração, ou style.mjs --project), abrindo o fluxo do navegador (fallback de arquivo) então; repasse suas instruções impressas. Em uma máquina headless/SSH, ele pula o fluxo do navegador e começa automaticamente com o registro de arquivo/--import. Nunca execute uma verificação/registro de chave proativamente. Nunca cole a chave no chat.
Execução
Colete a entrada (caminho local ou URL — pergunte novamente se estiver faltando) e execute em segundo plano (o próprio worker gerencia a chave quando a extração realmente começa):
- Único:
node scripts/srt.mjs "<arquivo|URL>" [--target en] [--space "nome do espaço"] [--out pasta] - Multi-idioma / multi-entrada:
node scripts/srt.mjs "<URL>" "<arquivo>" --target en,ja - Pasta (lote):
node scripts/srt.mjs "<pasta>" [--target en] [--recursive] [--out pasta] - Apenas transcrição (sem tradução):
node scripts/srt.mjs "<arquivo|URL>" --transcribe-only
Os arquivos SRT originais extraídos são salvos ao lado de cada fonte (ou em --out), mantendo o nome do arquivo do servidor (…_OriginalSubtitle_….srt).
Local de salvamento — mesma política que /dubbing: o padrão é ao lado de cada arquivo de origem; não pergunte. No primeiro trabalho da sessão, informe-o na linha de início e comece imediatamente. Uma pasta nomeada pelo usuário anteriormente nesta sessão continua sendo aplicada (--out "<pasta>") até que ele a altere; os SRTs traduzidos vão para a mesma pasta que seus originais. Exceção: quando toda entrada é uma URL, pergunte onde salvar antes de começar.
Seleção de espaço — com vários workspaces, o worker para antes de fazer o upload, imprime linhas [space-select] (nome | (plano) | créditos restantes) e para. Mostre ao usuário APENAS essas opções (sem números internos), pergunte qual delas e execute novamente com --space "<nome do espaço>". Um espaço com capacidade de dublagem → nenhuma pergunta; PERSO_SPACE_SEQ o fixa.
Mídia acima do limite do plano — esta habilidade não faz divisão automática. Se o worker relatar que a mídia excede o limite de duração/tamanho do plano, repasse sua mensagem: o usuário pode dividir/cortar o arquivo eles mesmos ou atualizar o plano, e então tentar novamente. Em um workspace Free, essa mensagem vem como linhas [free-limit] (um arquivo mais curto ou uma atualização — não há sinalizador de prosseguimento); repasse-as e pare.
Plano gratuito (sem .srt local) — um workspace Free transcreve normalmente, mas o servidor recusa todo download, então nada é salvo localmente. O worker imprime Free plan — <nome>: subtitles ready on Perso → <link> (downloads need a paid plan) e nenhuma linha [srt-original]. Sem arquivo, não há nada para traduzir: pule a seção Traduzir inteiramente, repasse o link como o resultado entregue (a execução está completa — nada falhou, nada para retomar) e mencione que arquivos .srt para download precisam de um plano pago.
Créditos — cada projeto de legenda consome créditos proporcionalmente à duração da mídia (um projeto por entrada). A cobrança do servidor é autoritativa; não cite preços exatos.
Traduzir (você faz esta parte)
Usuário fornece um SRT diretamente (sem STT): não há passo do worker e nenhuma linha [srt-original] — trate o SRT fornecido como path e os idiomas que o usuário pediu como langs, então siga os Passos 1–5 conforme escrito, derivando o {stem} do Passo 3 do próprio nome do arquivo SRT. Totalmente offline: apenas --check/--retime, sem chave, sem créditos.
Quando a extração termina, o worker imprime uma linha por entrada, carregando cada idioma alvo:
[srt-original] {"input":"video.mp4","langs":["en","ja"],"path":"C:\\clips\\video_OriginalSubtitle_2026-07-15.srt","seq":389259}
Se langs for null (uma execução --transcribe-only), não há nada para traduzir: entregue esse arquivo ao usuário como está e pare aqui.
Mostre o progresso da tradução. A extração STT está concluída, mas traduzir para cada idioma leva tempo também — torne isso visível. Antes de começar, poste uma linha nomeando os idiomas que você vai produzir (ex.: "Legendas extraídas — agora traduzindo para japonês e inglês"). Depois que você terminar e salvar o arquivo de cada idioma, poste uma atualização de uma linha (ex.: Japonês ✓ (1/2)), para que o usuário veja o progresso por idioma como em uma dublagem multilíngue. Um arquivo longo pode ficar silencioso dentro de um único idioma enquanto você processa suas seções em lote — isso é normal.
Para cada linha [srt-original], traduza o único arquivo em path para cada idioma em langs:
Passo 1 — leia o arquivo inteiro primeiro e construa o contexto. Leia o SRT em path do início ao fim antes de traduzir qualquer coisa, e determine:
- qual é o conteúdo (palestra, tutorial, vlog, drama, anúncio, …) e para quem é
- o tom e o registro do locutor (formal / casual / humorístico / técnico) — e decida o estilo no idioma alvo que combine com ele
- nomes e termos recorrentes — use uma tradução consistente para cada um em todo o arquivo
Passo 2 — traduza para cada idioma em langs, seção por seção (processe arquivos longos em lote, mas aplique o tom e os termos fixados no Passo 1 a cada lote; o Passo 1 é feito uma vez por arquivo, não por idioma):
- Traduza apenas as linhas de texto. Mantenha os números das deixa, as linhas de timestamp (
-->), as linhas em branco e a contagem de deixas exatamente como estão — nunca altere timestamps ou mescle/divida deixas durante a tradução (reaplicação de tempo é uma passagem separada posterior, Passo 5). - O texto de cada deixa permanece em sua própria deixa. O STT corta a fonte pela duração da fala, não pela gramática, então as deixas frequentemente terminam no meio de uma frase — não espelhe essa quebra na tradução. Termine cada deixa em uma unidade legível e continue a continuação com uma vírgula ou uma frase contínua. Mantenha um fragmento apenas onde o locutor é genuinamente interrompido ou cortado.
- Significado e tom vêm em primeiro lugar: prefira uma tradução natural que carregue o tom do Passo 1 em vez de uma palavra por palavra. Traduza expressões idiomáticas, trocadilhos e humor com equivalentes no idioma alvo.
- Layout — no máximo 2 linhas de texto por deixa, cada linha com no máximo 42 caracteres para scripts latinos (20 para CJK). Uma linha mais longa é quebrada forçadamente pelo player em 3+ linhas na tela que cobrem a imagem. Quebre as linhas em fronteiras naturais de frase; se o texto não couber, encurte-o com a prioridade abaixo.
- Fique dentro do tempo de exibição de cada deixa: orçamento ≈ duração da deixa × 17 caracteres/s para scripts latinos (9 para CJK); além de ~21/s (13 CJK) a legenda desaparece antes de ser lida. Uma tradução natural geralmente cabe, então a maioria das deixas não precisa de corte — encurte apenas as que transbordarem.
- Quando precisar encurtar, mantenha esta prioridade: significado → tom/nuance → comprimento. Corte preenchimentos, redundância e repetição primeiro; mantenha informações principais, frases de efeito e expressões emocionais por último. Se um trocadilho realmente não couber, substitua-o por uma linha mais curta que ainda transmita o humor — reduzi-lo a um resumo sem graça é o último recurso.
Passo 3 — salve: UTF-8, na mesma pasta, um arquivo por idioma nomeado como {stem}_{lang}_Subtitle.srt, onde stem é o nome do arquivo de entrada sem sua extensão — extraia do campo input da linha [srt-original] (ex.: "input":"video.mp4" + ["en","ja"] → video_en_Subtitle.srt e video_ja_Subtitle.srt; para entradas URL, use o título da mídia ou um slug curto). Não derive o stem do nome do arquivo baixado — o servidor o constrói a partir do título do projeto. Mantenha o arquivo SRT original — não o exclua ou sobrescreva.
Passo 4 — verifique cada arquivo salvo (offline — sem chave, sem rede, sem créditos):
node scripts/srt.mjs --check "<traduzido.srt>" --source "<original .srt>"
Linhas [check] FAIL significam que o arquivo quebra o alinhamento das deixas, o layout 2×42 ou o limite de velocidade de leitura. Reescreva APENAS as deixas listadas (mesma prioridade de significado em primeiro lugar), salve e execute novamente até que nenhum FAIL permaneça. Linhas WARN são polimento opcional. Execute isso antes do Passo 5 — após a reaplicação de tempo, a contagem de deixas não corresponde mais à fonte por design.
Passo 5 — reaplicação de tempo para legibilidade (offline; uma vez por arquivo entregue, após a verificação passar):
node scripts/srt.mjs --retime "<traduzido.srt>"
Ele estende deixas muito rápidas para o silêncio seguinte e mescla deixas vizinhas curtas em um único evento de 2 linhas (estilo Netflix), reescrevendo o arquivo no local — a numeração das deixas pode mudar; o SRT original intocado mantém o mapa de tempo 1:1. Então:
- encurte o texto de quaisquer deixas que ele ainda lista como muito rápidas (fala genuinamente rápida), e
- para conteúdo de comédia/drama, revise suas linhas
[retime] merged: se uma mesclagem mostrar uma punchline cedo ou completar uma linha intencionalmente interrompida, restaure essas duas deixas com seus tempos originais do estado pré-mesclagem.
Reporte os caminhos dos arquivos SRT traduzidos salvos ao usuário, mencionando que os originais são mantidos ao lado. Se o usuário quiser abrir o projeto de legenda no Perso, construa o link a partir do seq da linha [srt-original]: https://perso.ai/en/workspace/vt/stt/<seq>.
Estilo e legendas fixas (hardsub)
Opcionalmente, queime uma faixa de legenda estilizada no vídeo (hardsub permanente) com scripts/style.mjs. Este é um passo local do ffmpeg — sem chave, sem créditos (exceto --project, que baixa a fonte do Perso). Requer ffmpeg; se estiver faltando, diga ao usuário para instalá-lo e pare.
Quando oferecer (dois pontos de entrada):
- Após a tradução: uma vez que os SRTs são entregues, ofereça-se para adicionar legendas estilizadas — redação natural voltada ao usuário, não "queimar/hardsub". Para vários idiomas, pergunte por todos ou apenas alguns.
- Solicitação direta (vídeo + SRT fornecidos a você): vá direto para a seleção de predefinições.
Fluxo:
- Sempre mostre as predefinições primeiro — nunca pule para aplicar uma. Como mostrá-las depende da superfície:
- Aplicativo Claude (ou qualquer superfície que possa renderizar um widget interativo): mostre a galeria de predefinições — um bloco por predefinição que o usuário seleciona, com um botão Aplicar que envia a escolha de volta como a solicitação de geração. Preferido lá.
- CLI / Antigravity / Codex / qualquer lugar sem renderização interativa (fallback universal): anexe
assets/style_presets.png(a prévia estática) e executenode scripts/style.mjs --list-presetspara o menu de texto. Ambos vêm das mesmas predefinições. Agrupe formato curto (9:16) / formato longo (16:9). O usuário pode escolher uma predefinição ou descrever qualquer estilo (ex.: "texto amarelo, contorno preto, na parte inferior"). Sugira um padrão por orientação (retrato → formato curto, paisagem → formato longo), mas deixe que eles escolham. Aplique apenas depois que eles escolherem ou descreverem.
- Aplique. Execute o worker em segundo plano (a codificação leva tempo):
- De um projeto STT do Perso:
node scripts/style.mjs --project <seq> --preset <id> [--out pasta] - De arquivos locais:
node scripts/style.mjs "<vídeo>" "<legenda.srt>" --preset <id> [--out pasta] - Quando o SRT que você queimou veio de uma extração STT do Perso (um arquivo
[srt-original]ou uma tradução dele), adicione--origin perso; para um arquivo de legenda que o usuário forneceu, omita-o. Apenas telemetria — não altera a saída. - Estilo personalizado: mapeie a descrição do usuário para sinalizadores de substituição sobre qualquer predefinição base —
--position center|lower|bottom|upper,--font,--fontsize,--primary RRGGBB,--outline RRGGBB,--outline-width,--box RRGGBB@opacity|none,--karaoke/--no-karaoke,--highlight RRGGBB,--uppercase,--bold/--no-bold(veja--help). - Fontes:
--font "<nome>"usa uma fonte instalada; um nome que não está instalado cai de volta para a fonte de sistema mais próxima automaticamente (mencione quando relevante). Um arquivo de fonte fornecido pelo usuário (.ttf/.otf/.ttc) vai em--font-file "<caminho>"— o nome da família é lido do próprio arquivo. - Vários idiomas: execute uma vez por SRT de idioma com o mesmo
--preset, adicionando--lang <código>para que as saídas sejam...
- De um projeto STT do Perso: