Communitygithub.com

Perso SRT extrair+traduzir — passe fonte de captions

Extrai legendas (SRT) de vídeo/áudio/URL via Perso AI STT e traduz mantendo timings. Caminho grátis de legendas para dub e hard-burn.

O que é Perso SRT extrair+traduzir — passe fonte de captions?

Video Localization passo 1 (ASR/traduzir): perso-dubbing-plugin-srt. Vídeo/URL → SRT fonte → SRT multi-idioma pronto para dub lip-sync e hardburn bilíngue.

Funciona com✓Claude Code✓Codex CLI✓Cursor✓Antigravity✓Gemini CLI
npx skills add https://github.com/perso-ai/perso-dubbing-plugin/tree/HEAD/skills/srt

Perguntar na sua IA favorita

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

Documentação

/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çalho XP-API-KEY.
  • Um comando = a extração inteira. scripts/srt.mjs lida com upload · transcrição · download do SRT por conta própria.
  • Sempre execute srt.mjs em 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 en como 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-only em 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 dica next 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.mjs com 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 dubbing deve estar instalada ao lado de srt (todo método de instalação as envia juntas; apenas uma cópia manual da pasta srt sozinha 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:

  1. 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 execute node scripts/style.mjs --list-presets para 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.
  2. 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...

Individual skills in this repo

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

Habilidades Relacionadas