speech

Visão geral do skill de speech

O que o skill de speech faz

O skill de speech transforma texto em áudio falado para narração, voiceover, prompts de IVR, leituras de acessibilidade e geração em lote de fala. Ele funciona melhor quando você precisa de saída de áudio reproduzível a partir de um prompt, e não de um pedido livre do tipo “faz soar bonito”.

Quem deve usar

Use speech se o install de speech precisar se encaixar em um fluxo de trabalho real: demos de produto, onboarding de app, materiais de acessibilidade ou muitos clipes curtos a partir de texto estruturado. É uma boa opção quando voz, ritmo, formato de saída e consistência entre execuções importam.

O que o torna diferente

O guia de speech é construído em torno da OpenAI Audio API e do CLI incluído, então privilegia uso determinístico em vez de prompting improvisado. Ele usa vozes nativas, suporta jobs únicos ou em lote e espera OPENAI_API_KEY para geração ao vivo. Criação de voz personalizada está fora de escopo.

Como usar o skill de speech

Instale e localize o fluxo de trabalho

Instale com npx skills add openai/skills --skill speech. Depois disso, leia primeiro SKILL.md, depois references/cli.md para detalhes dos comandos, references/audio-api.md para limites de modelo e parâmetros, e references/prompting.md ou references/voice-directions.md para escrever instruções melhores. Para contexto rápido, confira agents/openai.yaml e references/sample-prompts.md.

Transforme um objetivo bruto em um prompt utilizável

O padrão de uso do speech funciona melhor quando você fornece ao skill o texto exato que deve ser lido, a voz alvo, o estilo de entrega, o formato de saída e quaisquer restrições de pronúncia. Um pedido forte seria: “Gere uma locução de 45 segundos para demo de produto a partir deste script, use cedar, mantenha um tom caloroso e estável, saída em mp3 e destaque o nome do produto na primeira menção.” Isso é melhor do que “faça isso soar profissional”, porque dá ao skill controles concretos de síntese.

Fluxo de trabalho único vs em lote

O skill foi pensado para dois caminhos: um clipe ou vários clipes. Se você tiver várias linhas, prompts ou arquivos, trate como lote e prepare um arquivo JSONL temporário em tmp/, depois execute o CLI uma única vez e apague o JSONL depois do uso. Se tiver apenas um script, use o caminho de arquivo único. Essa decisão importa porque a estrutura do skill e as etapas de validação mudam conforme o volume de saída.

O que verificar antes de executar

Para melhores resultados, valide o texto palavra por palavra, não só o tema. Confirme a voz, o formato do arquivo, a velocidade e se a saída precisa ser neutra, expressiva ou priorizar acessibilidade. O principal arquivo do repositório a inspecionar para a execução é scripts/text_to_speech.py; não o modifique a menos que o mantenedor do repositório oriente isso.

FAQ do skill de speech

O skill de speech é só para narração?

Não. O skill de speech também serve para voiceover, leituras de acessibilidade, prompts de IVR e prompts curtos de áudio. Ele é menos útil para clonagem de voz personalizada ou design criativo de voz, que este repo não cobre.

Preciso do CLI para usar speech?

Para um uso confiável do speech, sim. O CLI incluído é o caminho esperado para geração ao vivo, enquanto --dry-run é útil para conferir a forma da chamada sem fazer uma requisição de API. Se você apenas escrever um prompt genérico, perde a estrutura que torna o skill reproduzível.

Isso é amigável para iniciantes?

Sim, desde que você consiga fornecer o texto exato e uma direção básica de voz. O install de speech é simples, mas a qualidade da saída depende de quão claramente você define ritmo, tom, formato e pronúncia. Iniciantes costumam ter mais sucesso quando começam com um clipe curto e uma única voz.

Quando eu não devo usar este skill?

Não use speech se você precisar criar uma voz personalizada, fazer pós-produção pesada ou depender de um fluxo que envolva modificar o script incluído. Também é uma escolha ruim se você não puder usar chamadas de rede para a OpenAI API ou não tiver OPENAI_API_KEY.

Como melhorar o skill de speech

Reduza ambiguidades ao máximo

O maior ganho de qualidade na saída do skill de speech vem de eliminar suposições. Forneça o texto exato, não um resumo; diga quem é o público-alvo; e especifique se a leitura deve soar como narração, mensagem de suporte, acessibilidade ou prompt de IVR. Se um termo for difícil de pronunciar, escreva como deve ser lido ou adicione uma nota de pronúncia.

Ajuste uma variável por vez

Quando a primeira versão estiver perto, mas não certa, mude apenas uma coisa: voz, velocidade ou estilo da instrução. Isso torna a iteração mais limpa do que reescrever o prompt inteiro. Por exemplo, se o tempo parecer apressado, mantenha texto e voz fixos e ajuste só a velocidade de 1.0 para 0.95.

Use restrições de saída que realmente importam

O guia de speech funciona melhor quando as restrições são operacionais, não vagas. Diga “mp3 para reprodução rápida”, “wav para revisão” ou “estável e neutro para acessibilidade”. Em jobs em lote, mantenha cada linha com escopo bem delimitado para que o skill preserve uma entrega consistente entre as saídas.

Leia primeiro as referências certas

Se você quer melhores resultados com speech para Design Implementation, priorize references/accessibility.md para leituras neutras, references/voiceover.md para entrega no estilo apresentação e references/sample-prompts.md para a estrutura dos prompts. Esses arquivos ajudam você a escrever instruções que o CLI e a API conseguem executar sem interpretação extra.