# Speech > Use quando o usuário solicita narração em texto-para-fala, voiceovers de acessibilidade, prompts de áudio ou geração em lote via OpenAI Audio API; execute a CLI incluída (`scripts/text_to_speech.py`) com vozes integradas e requer `OPENAI_API_KEY` para chamadas diretas. Criação de vozes customizadas está fora do escopo. - Skill: `artubss/speech` (Agent Skill, multi-file: 16 files) - Install (CLI): `npx skillmds@latest add artubss/speech` - Raw SKILL.md: https://api.skillmd.com/api/skills/artubss/speech/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: artubss (https://skillmd.com/u/artubss) - Updated: 2026-08-19 - Page: https://skillmd.com/skills/artubss/speech --- # 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 1. Decida a intenção: único vs lote (veja árvore de decisão acima). 2. Colete inputs antecipadamente: texto exato (palavra por palavra), voz desejada, estilo de entrega, formato e qualquer restrição. 3. Se lote: escreva um JSONL temporário em tmp/ (um job por linha), execute uma vez, depois delete o JSONL. 4. Aumente instruções em uma especificação curta e rotulada sem reescrever o texto de entrada. 5. Execute a CLI incluída (`scripts/text_to_speech.py`) com padrões sensatos (veja references/cli.md). 6. Para clipes importantes, valide: inteligibilidade, pacing, pronúncia e conformidade com restrições. 7. Itere com uma única mudança direcionada (voz, velocidade ou instruções), depois revise. 8. 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: 1. Crie uma API key na UI da plataforma OpenAI: https://platform.openai.com/api-keys 2. Configure `OPENAI_API_KEY` como variável de ambiente em seu sistema. 3. 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: Tom: Pacing: Emoção: Pronúncia: Pausas: Ênfase: Entrega: ``` 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.