@polymorphism-tech/morph-spec 8.28.0 → 8.31.0

package/framework/standards/ai-agents/modalities-text-to-speech.md

@@ -1,181 +1,181 @@
-# Modalities — Text to Speech (Text to Audio)
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 2 (on-keyword)
-> **Keywords:** text to speech, TTS, voice synthesis, audio generation, speech synthesis
-> **Read by Claude in:** implement (quando o projeto precisa gerar áudio a partir de texto)
-
-**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.x. Last-verified: 2026-05-19.
-
----
-
-## Quando usar TTS
-
-TTS converte texto em áudio narrado. É um caso de uso **raro** — só adicione quando há demanda real e comprovada:
-
-- **Acessibilidade:** leitura em voz alta para usuários com deficiência visual ou dificuldade de leitura
-- **Notificações em áudio:** resumos falados de alertas ou relatórios em contextos hands-free (painel industrial, carro)
-- **Resumos falados:** o usuário quer ouvir um digest em vez de ler (ex: podcast personalizado gerado on-demand)
-
-**Nota honesta:** TTS tem custo por caractere e latência perceptível. Se o caso de uso não é explicitamente solicitado pelo usuário final ou pelo cliente, não adicione — um botão "copiar texto" ou um leitor de tela nativo do SO resolve a maioria dos casos de acessibilidade sem custo de API.
-
-TTS é uma **chamada de serviço**, não um agente conversacional. Use `AudioClient` diretamente via DI — não crie `AIAgent` para isso.
-
----
-
-## A API
-
-No OpenAI SDK (.NET 2.x), o caminho é `AudioClient.GenerateSpeech`:
-
-```csharp
-using OpenAI.Audio;
-
-AudioClient client = new("tts-1", apiKey);
-BinaryData speech = await client.GenerateSpeechAsync(text, GeneratedSpeechVoice.Alloy);
-```
-
-Retorna `BinaryData` (bytes de áudio) que você persiste ou serve via stream. Para controlar formato e velocidade, use `SpeechGenerationOptions`.
-
----
-
-## Exemplo C# completo
-
-```csharp
-using OpenAI.Audio;
-using Microsoft.Extensions.Configuration;
-
-public sealed class TextToSpeechService
-{
-    private readonly AudioClient _client;
-
-    public TextToSpeechService(IConfiguration config)
-    {
-        // tts-1: mais rápido, menor qualidade. tts-1-hd: mais lento, maior qualidade.
-        var model = config["TTS:Model"] ?? "tts-1";
-        var apiKey = config["OpenAI:ApiKey"]!;
-        _client = new AudioClient(model, apiKey);
-    }
-
-    /// <summary>
-    /// Converte texto em áudio e retorna bytes MP3.
-    /// Cachear o resultado é altamente recomendado para textos repetitivos — gerar o mesmo texto
-    /// duas vezes é desperdício de custo e latência.
-    /// </summary>
-    public async Task<BinaryData> SynthesizeAsync(
-        string text,
-        GeneratedSpeechVoice? voice = null,
-        GeneratedSpeechFormat? format = null,
-        float speedRatio = 1.0f,
-        CancellationToken ct = default)
-    {
-        var resolvedVoice  = voice  ?? GeneratedSpeechVoice.Alloy;
-        var resolvedFormat = format ?? GeneratedSpeechFormat.Mp3;
-
-        var options = new SpeechGenerationOptions
-        {
-            ResponseFormat = resolvedFormat,
-            SpeedRatio     = speedRatio
-        };
-
-        BinaryData speech = await _client.GenerateSpeechAsync(text, resolvedVoice, options, ct);
-        return speech;
-    }
-}
-```
-
-**Registro DI:**
-
-```csharp
-// Program.cs
-builder.Services.AddSingleton<TextToSpeechService>();
-```
-
-**Servindo como download ou stream:**
-
-```csharp
-public class AudioController(TextToSpeechService tts) : ControllerBase
-{
-    [HttpPost("synthesize")]
-    public async Task<IActionResult> Synthesize([FromBody] SynthesizeRequest req)
-    {
-        // Verificar cache antes de gerar (ver Anti-patterns)
-        BinaryData audio = await tts.SynthesizeAsync(
-            text:       req.Text,
-            voice:      GeneratedSpeechVoice.Nova,
-            format:     GeneratedSpeechFormat.Mp3,
-            speedRatio: 1.1f);
-
-        // the storage layer may assign the final name; use a timestamp-based name here
-        var fileName = $"tts-{DateTime.UtcNow:yyyyMMddHHmmss}.mp3";
-        return File(audio.ToStream(), "audio/mpeg", fileName);
-    }
-}
-```
-
----
-
-## Parâmetros
-
-> Valores verificados contra OpenAI TTS API + OpenAI .NET SDK 2.x (2026-05-19).
-
-**Vozes disponíveis (`GeneratedSpeechVoice`):**
-
-| Voz | Característica |
-|-----|---------------|
-| `Alloy` | Neutra, versátil — boa escolha padrão |
-| `Echo` | Masculina, suave |
-| `Fable` | Britânica, expressiva |
-| `Onyx` | Masculina, grave |
-| `Nova` | Feminina, amigável |
-| `Shimmer` | Feminina, suave |
-
-**Formatos de saída (`GeneratedSpeechFormat`):**
-
-| Formato | Caso de uso |
-|---------|-------------|
-| `Mp3` | Default — compatibilidade universal |
-| `Opus` | Streaming de baixa latência |
-| `Aac` | Dispositivos Apple / YouTube |
-| `Flac` | Arquivo sem perda |
-| `Wav` | Processamento de áudio downstream |
-| `Pcm` | Raw bytes sem container |
-
-**`SpeedRatio`:** `0.25` (muito lento) a `4.0` (muito rápido). Padrão `1.0`.
-
-**Modelos:**
-- `tts-1` — rápido, custo menor, qualidade suficiente para a maioria dos casos
-- `tts-1-hd` — maior qualidade, mais lento e mais caro — use apenas quando a clareza de voz é crítica
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Por quê é errado | Jeito certo |
-|--------------|-----------------|-------------|
-| Adicionar TTS sem caso de uso real | Custo por caractere + latência sem benefício ao usuário | Só adicione com demanda explícita; leitores de tela nativos cobrem acessibilidade básica |
-| Gerar o mesmo texto repetidamente sem cache | Textos fixos (intro, disclaimers, respostas FAQ) custam o mesmo toda vez | Cachear bytes de áudio para textos invariantes — CDN ou Redis com key baseada em hash do texto + voz + formato |
-| Criar `AIAgent` para TTS | `AudioClient.GenerateSpeech` não é conversacional; não há raciocínio LLM envolvido | Injete `TextToSpeechService` via DI — é um serviço de síntese, não um agente |
-| Gerar texto longo de uma vez sem segmentar | Providers têm limite de caracteres por request (OpenAI: ~4096 tokens / ~4000 chars); textos muito longos falham | Divida em parágrafos, gere áudio por segmento, concatene os bytes |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] `AudioClient` injetado via DI — não instanciado inline
-- [ ] Cache implementado para textos invariantes (não gera o mesmo áudio duas vezes)
-- [ ] Textos longos segmentados antes de enviar ao provider
-- [ ] `GeneratedSpeechVoice` e `GeneratedSpeechFormat` escolhidos adequados ao contexto (não só defaults)
-- [ ] Model e API key vêm de config, não hardcoded
-- [ ] Não usa `AIAgent`/`AsAIAgent` para TTS — é um `TextToSpeechService`
-
----
-
-## References
-
-- `ai-agents-setup` — packages, DI, e providers disponíveis
-- `ai-agents-providers-model-registry` — padrão de alias; adapte para resolver `AudioClient` por provider
-- OpenAI .NET SDK — `AudioClient`: https://github.com/openai/openai-dotnet
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-text-to-speech.md v1.0 (2026-05-19)*
+# Modalities — Text to Speech (Text to Audio)
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** text to speech, TTS, voice synthesis, audio generation, speech synthesis
+> **Read by Claude in:** implement (quando o projeto precisa gerar áudio a partir de texto)
+
+**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.x. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar TTS
+
+TTS converte texto em áudio narrado. É um caso de uso **raro** — só adicione quando há demanda real e comprovada:
+
+- **Acessibilidade:** leitura em voz alta para usuários com deficiência visual ou dificuldade de leitura
+- **Notificações em áudio:** resumos falados de alertas ou relatórios em contextos hands-free (painel industrial, carro)
+- **Resumos falados:** o usuário quer ouvir um digest em vez de ler (ex: podcast personalizado gerado on-demand)
+
+**Nota honesta:** TTS tem custo por caractere e latência perceptível. Se o caso de uso não é explicitamente solicitado pelo usuário final ou pelo cliente, não adicione — um botão "copiar texto" ou um leitor de tela nativo do SO resolve a maioria dos casos de acessibilidade sem custo de API.
+
+TTS é uma **chamada de serviço**, não um agente conversacional. Use `AudioClient` diretamente via DI — não crie `AIAgent` para isso.
+
+---
+
+## A API
+
+No OpenAI SDK (.NET 2.x), o caminho é `AudioClient.GenerateSpeech`:
+
+```csharp
+using OpenAI.Audio;
+
+AudioClient client = new("tts-1", apiKey);
+BinaryData speech = await client.GenerateSpeechAsync(text, GeneratedSpeechVoice.Alloy);
+```
+
+Retorna `BinaryData` (bytes de áudio) que você persiste ou serve via stream. Para controlar formato e velocidade, use `SpeechGenerationOptions`.
+
+---
+
+## Exemplo C# completo
+
+```csharp
+using OpenAI.Audio;
+using Microsoft.Extensions.Configuration;
+
+public sealed class TextToSpeechService
+{
+    private readonly AudioClient _client;
+
+    public TextToSpeechService(IConfiguration config)
+    {
+        // tts-1: mais rápido, menor qualidade. tts-1-hd: mais lento, maior qualidade.
+        var model = config["TTS:Model"] ?? "tts-1";
+        var apiKey = config["OpenAI:ApiKey"]!;
+        _client = new AudioClient(model, apiKey);
+    }
+
+    /// <summary>
+    /// Converte texto em áudio e retorna bytes MP3.
+    /// Cachear o resultado é altamente recomendado para textos repetitivos — gerar o mesmo texto
+    /// duas vezes é desperdício de custo e latência.
+    /// </summary>
+    public async Task<BinaryData> SynthesizeAsync(
+        string text,
+        GeneratedSpeechVoice? voice = null,
+        GeneratedSpeechFormat? format = null,
+        float speedRatio = 1.0f,
+        CancellationToken ct = default)
+    {
+        var resolvedVoice  = voice  ?? GeneratedSpeechVoice.Alloy;
+        var resolvedFormat = format ?? GeneratedSpeechFormat.Mp3;
+
+        var options = new SpeechGenerationOptions
+        {
+            ResponseFormat = resolvedFormat,
+            SpeedRatio     = speedRatio
+        };
+
+        BinaryData speech = await _client.GenerateSpeechAsync(text, resolvedVoice, options, ct);
+        return speech;
+    }
+}
+```
+
+**Registro DI:**
+
+```csharp
+// Program.cs
+builder.Services.AddSingleton<TextToSpeechService>();
+```
+
+**Servindo como download ou stream:**
+
+```csharp
+public class AudioController(TextToSpeechService tts) : ControllerBase
+{
+    [HttpPost("synthesize")]
+    public async Task<IActionResult> Synthesize([FromBody] SynthesizeRequest req)
+    {
+        // Verificar cache antes de gerar (ver Anti-patterns)
+        BinaryData audio = await tts.SynthesizeAsync(
+            text:       req.Text,
+            voice:      GeneratedSpeechVoice.Nova,
+            format:     GeneratedSpeechFormat.Mp3,
+            speedRatio: 1.1f);
+
+        // the storage layer may assign the final name; use a timestamp-based name here
+        var fileName = $"tts-{DateTime.UtcNow:yyyyMMddHHmmss}.mp3";
+        return File(audio.ToStream(), "audio/mpeg", fileName);
+    }
+}
+```
+
+---
+
+## Parâmetros
+
+> Valores verificados contra OpenAI TTS API + OpenAI .NET SDK 2.x (2026-05-19).
+
+**Vozes disponíveis (`GeneratedSpeechVoice`):**
+
+| Voz | Característica |
+|-----|---------------|
+| `Alloy` | Neutra, versátil — boa escolha padrão |
+| `Echo` | Masculina, suave |
+| `Fable` | Britânica, expressiva |
+| `Onyx` | Masculina, grave |
+| `Nova` | Feminina, amigável |
+| `Shimmer` | Feminina, suave |
+
+**Formatos de saída (`GeneratedSpeechFormat`):**
+
+| Formato | Caso de uso |
+|---------|-------------|
+| `Mp3` | Default — compatibilidade universal |
+| `Opus` | Streaming de baixa latência |
+| `Aac` | Dispositivos Apple / YouTube |
+| `Flac` | Arquivo sem perda |
+| `Wav` | Processamento de áudio downstream |
+| `Pcm` | Raw bytes sem container |
+
+**`SpeedRatio`:** `0.25` (muito lento) a `4.0` (muito rápido). Padrão `1.0`.
+
+**Modelos:**
+- `tts-1` — rápido, custo menor, qualidade suficiente para a maioria dos casos
+- `tts-1-hd` — maior qualidade, mais lento e mais caro — use apenas quando a clareza de voz é crítica
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é errado | Jeito certo |
+|--------------|-----------------|-------------|
+| Adicionar TTS sem caso de uso real | Custo por caractere + latência sem benefício ao usuário | Só adicione com demanda explícita; leitores de tela nativos cobrem acessibilidade básica |
+| Gerar o mesmo texto repetidamente sem cache | Textos fixos (intro, disclaimers, respostas FAQ) custam o mesmo toda vez | Cachear bytes de áudio para textos invariantes — CDN ou Redis com key baseada em hash do texto + voz + formato |
+| Criar `AIAgent` para TTS | `AudioClient.GenerateSpeech` não é conversacional; não há raciocínio LLM envolvido | Injete `TextToSpeechService` via DI — é um serviço de síntese, não um agente |
+| Gerar texto longo de uma vez sem segmentar | Providers têm limite de caracteres por request (OpenAI: ~4096 tokens / ~4000 chars); textos muito longos falham | Divida em parágrafos, gere áudio por segmento, concatene os bytes |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `AudioClient` injetado via DI — não instanciado inline
+- [ ] Cache implementado para textos invariantes (não gera o mesmo áudio duas vezes)
+- [ ] Textos longos segmentados antes de enviar ao provider
+- [ ] `GeneratedSpeechVoice` e `GeneratedSpeechFormat` escolhidos adequados ao contexto (não só defaults)
+- [ ] Model e API key vêm de config, não hardcoded
+- [ ] Não usa `AIAgent`/`AsAIAgent` para TTS — é um `TextToSpeechService`
+
+---
+
+## References
+
+- `ai-agents-setup` — packages, DI, e providers disponíveis
+- `ai-agents-providers-model-registry` — padrão de alias; adapte para resolver `AudioClient` por provider
+- OpenAI .NET SDK — `AudioClient`: https://github.com/openai/openai-dotnet
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-text-to-speech.md v1.0 (2026-05-19)*