Skill de Geração de Fala

Gere áudio falado para o projeto atual (narração, voiceover de demo de produto, prompts de IVR, leituras de acessibilidade). Padrão: gpt-4o-mini-tts-2025-12-15 e vozes integradas, com preferência pela CLI incluída para execuções determinísticas e reproduzíveis.

Quando usar

Gerar um único clipe falado a partir de texto
Gerar um lote de prompts (múltiplas linhas, múltiplos arquivos)

Árvore de decisão (único vs lote)

Se o usuário fornece múltiplas linhas/prompts ou deseja muitos outputs -> lote
Caso contrário -> único

Workflow

Decida a intenção: único vs lote (veja árvore de decisão acima).
Colete inputs antecipadamente: texto exato (palavra por palavra), voz desejada, estilo de entrega, formato e qualquer restrição.
Se lote: escreva um JSONL temporário em tmp/ (um job por linha), execute uma vez, depois delete o JSONL.
Aumente instruções em uma especificação curta e rotulada sem reescrever o texto de entrada.
Execute a CLI incluída (scripts/text_to_speech.py) com padrões sensatos (veja references/cli.md).
Para clipes importantes, valide: inteligibilidade, pacing, pronúncia e conformidade com restrições.
Itere com uma única mudança direcionada (voz, velocidade ou instruções), depois revise.
Salve/retorne os outputs finais e anote o texto final + instruções + flags utilizadas.

Convenções de temp e output

Use tmp/speech/ para arquivos intermediários (por exemplo, lotes JSONL); delete ao terminar.
Escreva artefatos finais em output/speech/ ao trabalhar neste repositório.
Use --out ou --out-dir para controlar paths de output; mantenha nomes de arquivo estáveis e descritivos.

Dependências (instale se faltarem)

Prefira uv para gerenciamento de dependências.

Pacotes Python:

uv pip install openai

Se uv não estiver disponível:

python3 -m pip install openai

Ambiente

OPENAI_API_KEY deve estar definida para chamadas diretas de API.

Se a chave estiver faltando, forneca ao usuário estas etapas:

Crie uma API key na UI da plataforma OpenAI: https://platform.openai.com/api-keys
Configure OPENAI_API_KEY como variável de ambiente em seu sistema.
Ofereça-se para guiá-lo através da configuração da variável de ambiente para seu SO/shell, se necessário.

Nunca peça ao usuário que cole a chave completa no chat. Peça que configure localmente e confirme quando pronto.

Se a instalação não for possível neste ambiente, informe ao usuário qual dependência está faltando e como instalá-la localmente.

Padrões & regras

Use gpt-4o-mini-tts-2025-12-15 a menos que o usuário solicite outro modelo.
Voz padrão: cedar. Se o usuário quer um tom mais brilhante, prefira marin.
Apenas vozes integradas. Vozes customizadas estão fora do escopo desta skill.
instructions são suportadas para modelos GPT-4o mini TTS, mas não para tts-1 ou tts-1-hd.
O comprimento da entrada deve ser <= 4096 caracteres por requisição. Divida textos mais longos em chunks.
Enforce 50 requisições/minuto. A CLI limita --rpm a 50.
Requer OPENAI_API_KEY antes de qualquer chamada de API direto.
Forneça uma divulgação clara aos usuários finais de que a voz é gerada por IA.
Use o SDK Python da OpenAI (pacote openai) para todas as chamadas de API; não use HTTP bruto.
Prefira a CLI incluída (scripts/text_to_speech.py) em vez de escrever novos scripts pontuais.
Nunca modifique scripts/text_to_speech.py. Se algo estiver faltando, pergunte ao usuário antes de fazer qualquer coisa.

Aumento de instrução

Reformate a direção do usuário em uma especificação curta e rotulada. Apenas torne explícitos detalhes implícitos; não invente novos requisitos.

Esclarecimento rápido (aumento vs invenção):

Se o usuário diz "narração para uma demo", você pode adicionar restrições de entrega implícitas (clara, pacing constante, tom amigável).
Não introduza uma nova persona, sotaque ou estilo emocional que o usuário não tenha solicitado.

Template (inclua apenas linhas relevantes):

Textura de Voz: <caráter geral e textura da voz>
Tom: <atitude, formalidade, calidez>
Pacing: <lento, constante, rápido>
Emoção: <emoções-chave a transmitir>
Pronúncia: <palavras a enunciar ou enfatizar>
Pausas: <onde adicionar pausas intencionais>
Ênfase: <palavras ou frases-chave a estressar>
Entrega: <notas de cadência ou ritmo>

Regras de aumento:

Mantenha breve; adicione apenas detalhes que o usuário já implícita ou explicitamente forneceu.
Não reescreva o texto de entrada.
Se algum detalhe crítico estiver faltando e bloquear sucesso, faça uma pergunta; caso contrário, prossiga.

Exemplos

Exemplo único (narração)

Texto de entrada: "Bem-vindo à demo. Hoje vamos mostrar como funciona."
Instruções:
Textura de Voz: Quente e composta.
Tom: Amigável e confiante.
Pacing: Constante e moderado.
Ênfase: Estresse "demo" e "mostrar".

Exemplo de lote (prompts de IVR)

{"input":"Obrigado por ligar. Por favor, aguarde.","voice":"cedar","response_format":"mp3","out":"hold.mp3"}
{"input":"Para vendas, pressione 1. Para suporte, pressione 2.","voice":"marin","instructions":"Tom: Claro e neutro. Pacing: Lento.","response_format":"wav"}

Melhores práticas de instrução (lista breve)

Estruture direções como: textura -> tom -> pacing -> emoção -> pronúncia/pausas -> ênfase.
Mantenha 4 a 8 linhas curtas; evite orientação conflitante.
Para nomes/acrônimos, adicione dicas de pronúncia (ex: "enuncie A-I") ou forneça uma soletração fonética no texto.
Para edições/iterações, repita invariantes (ex: "mantenha pacing constante") para reduzir desvios.
Itere com follow-ups de mudança única.

Mais princípios: references/prompting.md. Especificações para colar: references/sample-prompts.md.

Orientação por caso de uso

Use estes módulos quando a solicitação é para um estilo de entrega específico. Eles fornecem padrões e templates direcionados.

Narração / explainer: references/narration.md
Demo de produto / voiceover: references/voiceover.md
IVR / prompts de telefone: references/ivr.md
Leituras de acessibilidade: references/accessibility.md

Notas CLI + ambiente

Comandos CLI + exemplos: references/cli.md
Referência rápida de parâmetros de API: references/audio-api.md
Padrões de instrução + exemplos: references/voice-directions.md
Se aprovações de rede / configurações de sandbox estão atrapalhando: references/codex-network.md

Mapa de referência

references/cli.md: como executar geração de fala/lotes via scripts/text_to_speech.py (comandos, flags, receitas).
references/audio-api.md: parâmetros de API, limites, lista de vozes.
references/voice-directions.md: padrões de instrução e exemplos.
references/prompting.md: melhores práticas de instrução (estrutura, restrições, padrões de iteração).
references/sample-prompts.md: receitas de instrução pronta para colar (apenas exemplos; sem teoria extra).
references/narration.md: templates + padrões para narração e explainers.
references/voiceover.md: templates + padrões para voiceovers de demo de produto.
references/ivr.md: templates + padrões para prompts de IVR/telefone.
references/accessibility.md: templates + padrões para leituras de acessibilidade.
references/codex-network.md: troubleshooting de ambiente/sandbox/aprovação de rede.

speech

SKILL.mdskills/skills/media/speech/SKILL.md