feat(audio): AudioResult.WriteWavTo/WriteWavFile + README TTS section

- Promotes the RIFF/WAVE writer that was duplicated between
  samples/LiveAudioPlayback and samples/AudioRoundTrip into
  AudioResult.WriteWavTo(stream) / WriteWavFile(path). Sample rate
  defaults to the value parsed from MimeType. Both samples now call
  the SDK helper instead of carrying their own copies.
- README gains a Text-to-Speech and Speech-to-Text section showing
  SpeakAsync + GeminiAudioTags + WriteWavFile and the new
  ISpeechToTextClient (MEAI) round-trip. The features bullet now
  mentions ISpeechToTextClient and TTS support.
- Adds 3 new unit tests covering WAV header, explicit-rate override,
  and the empty-AudioData guard (15 total Audio tests now pass).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: HavenDV

README.md

@@ -11,7 +11,8 @@
 - Updated and supported automatically if there are no breaking changes
 - All modern .NET features - nullability, trimming, NativeAOT, etc.
 - Support .Net Framework/.Net Standard 2.0
-- Microsoft.Extensions.AI `IChatClient` and `IEmbeddingGenerator` support
+- Microsoft.Extensions.AI `IChatClient`, `IEmbeddingGenerator` and `ISpeechToTextClient` support
+- First-class TTS (`SpeakAsync` with Gemini 3.1 Flash TTS), audio-tag controllability, and built-in WAV output
 
 ### Usage
 ```csharp
@@ -26,6 +27,7 @@ The SDK implements [`IChatClient`](https://learn.microsoft.com/en-us/dotnet/api/
 ```csharp
 using Google.Gemini;
 using Microsoft.Extensions.AI;
+#pragma warning disable MEAI001 // ISpeechToTextClient is evaluation API
 
 // IChatClient
 IChatClient chatClient = new GeminiClient(apiKey);
@@ -38,8 +40,37 @@ IEmbeddingGenerator<string, Embedding<float>> generator = new GeminiClient(apiKe
 var embeddings = await generator.GenerateAsync(
     ["Hello, world!"],
     new EmbeddingGenerationOptions { ModelId = "gemini-embedding-001" });
+
+// ISpeechToTextClient
+ISpeechToTextClient stt = new GeminiClient(apiKey);
+using var wav = File.OpenRead("speech.wav");
+var transcription = await stt.GetTextAsync(wav);
+```
+
+### Text-to-Speech and Speech-to-Text
+
+`SpeakAsync` synthesizes speech with `gemini-3.1-flash-tts-preview` (default) and returns
+raw PCM that you can write to disk with the built-in WAV helper:
+
+```csharp
+using Google.Gemini;
+
+using var client = new GeminiClient(apiKey);
+
+var result = await client.SpeakAsync(
+    text: $"{GeminiAudioTags.Cheerful} Hello! {GeminiAudioTags.Excited} This is Gemini.",
+    voiceName: GeminiVoices.Puck);
+
+Console.WriteLine($"{result.AudioData!.Length} bytes @ {result.SampleRateHz} Hz");
+result.WriteWavFile("speech.wav");
 ```
 
+`GeminiAudioTags` exposes constants for the commonly supported inline audio tags
+(emotion / style / delivery / pacing). `GeminiVoices` lists all 30 prebuilt voice
+names, and `client.ListTtsModelsAsync()` discovers TTS-capable models at runtime.
+See [`docs/guides/tts-and-stt.md`](docs/guides/tts-and-stt.md) and the
+[`samples/AudioRoundTrip`](samples/AudioRoundTrip) console for a complete walk-through.
+
 ### Live API (Real-time Voice/Video)
 
 The SDK supports the [Gemini Live API](https://ai.google.dev/gemini-api/docs/live-api) for real-time bidirectional voice and video interactions over WebSocket:

samples/AudioRoundTrip/Program.cs

@@ -39,13 +39,12 @@
     return 1;
 }
 
-var pcmData = tts.AudioData!;
 var sampleRate = tts.SampleRateHz ?? 24000;
-Console.WriteLine($"  {pcmData.Length:N0} bytes PCM @ {sampleRate} Hz ({pcmData.Length / (double)(sampleRate * 2):F1}s)");
+Console.WriteLine($"  {tts.AudioData!.Length:N0} bytes PCM @ {sampleRate} Hz ({tts.AudioData.Length / (double)(sampleRate * 2):F1}s)");
 
 // 2) Save as WAV next to the executable so the user can play it.
 var wavPath = Path.Combine(Directory.GetCurrentDirectory(), "audio_round_trip.wav");
-WriteWavFile(wavPath, pcmData, sampleRate: sampleRate, bitsPerSample: 16, channels: 1);
+tts.WriteWavFile(wavPath);
 Console.WriteLine($"  Saved: {wavPath}");
 
 // 3) Round-trip the audio through the MEAI ISpeechToTextClient interface
@@ -61,29 +60,3 @@
 Console.WriteLine($"  Text:  {response.Text}");
 
 return 0;
-
-static void WriteWavFile(string path, byte[] pcmData, int sampleRate, int bitsPerSample, int channels)
-{
-    var byteRate = sampleRate * channels * bitsPerSample / 8;
-    var blockAlign = channels * bitsPerSample / 8;
-
-    using var fs = System.IO.File.Create(path);
-    using var writer = new BinaryWriter(fs);
-
-    writer.Write("RIFF"u8);
-    writer.Write(36 + pcmData.Length);
-    writer.Write("WAVE"u8);
-
-    writer.Write("fmt "u8);
-    writer.Write(16);
-    writer.Write((short)1);
-    writer.Write((short)channels);
-    writer.Write(sampleRate);
-    writer.Write(byteRate);
-    writer.Write((short)blockAlign);
-    writer.Write((short)bitsPerSample);
-
-    writer.Write("data"u8);
-    writer.Write(pcmData.Length);
-    writer.Write(pcmData);
-}

samples/LiveAudioPlayback/Program.cs

@@ -99,7 +99,7 @@
     {
         var pcmData = audioStream.ToArray();
         var wavPath = Path.Combine(Directory.GetCurrentDirectory(), $"response_{turnNumber:D3}.wav");
-        WriteWavFile(wavPath, pcmData, sampleRate: 24000, bitsPerSample: 16, channels: 1);
+        new AudioResult { AudioData = pcmData }.WriteWavFile(wavPath, sampleRate: 24000);
         Console.WriteLine($"  Audio saved: {wavPath} ({pcmData.Length:N0} bytes PCM, {pcmData.Length / 48000.0:F1}s)\n");
     }
     else
@@ -109,35 +109,3 @@
 }
 
 Console.WriteLine("\nSession ended.");
-
-/// <summary>
-/// Writes raw PCM audio data as a WAV file with the specified format.
-/// </summary>
-static void WriteWavFile(string path, byte[] pcmData, int sampleRate, int bitsPerSample, int channels)
-{
-    var byteRate = sampleRate * channels * bitsPerSample / 8;
-    var blockAlign = channels * bitsPerSample / 8;
-
-    using var fs = System.IO.File.Create(path);
-    using var writer = new BinaryWriter(fs);
-
-    // RIFF header
-    writer.Write("RIFF"u8);
-    writer.Write(36 + pcmData.Length); // file size - 8
-    writer.Write("WAVE"u8);
-
-    // fmt sub-chunk
-    writer.Write("fmt "u8);
-    writer.Write(16);               // sub-chunk size (PCM)
-    writer.Write((short)1);         // audio format (PCM = 1)
-    writer.Write((short)channels);
-    writer.Write(sampleRate);
-    writer.Write(byteRate);
-    writer.Write((short)blockAlign);
-    writer.Write((short)bitsPerSample);
-
-    // data sub-chunk
-    writer.Write("data"u8);
-    writer.Write(pcmData.Length);
-    writer.Write(pcmData);
-}

src/libs/Google.Gemini/Extensions/GeminiClientExtensions.Audio.cs

@@ -242,4 +242,76 @@ public record AudioResult
 
         return int.TryParse(rateValue, out var rate) ? rate : null;
     }
+
+    /// <summary>
+    /// Writes <see cref="AudioData"/> as a 16-bit little-endian PCM WAV stream.
+    /// Useful for saving Gemini TTS output (which arrives as raw PCM in
+    /// <c>audio/L16;…;rate=NNN</c>) to a playable file or HTTP response.
+    /// </summary>
+    /// <param name="destination">Target stream. Must be writable. Not closed by this method.</param>
+    /// <param name="sampleRate">Sample rate in Hz. Defaults to <see cref="SampleRateHz"/> or 24000.</param>
+    /// <param name="channels">Channel count. Defaults to 1 (mono — Gemini TTS is single-channel).</param>
+    /// <param name="bitsPerSample">Bit depth. Defaults to 16 (matches Gemini's L16 output).</param>
+    public void WriteWavTo(
+        Stream destination,
+        int? sampleRate = null,
+        int channels = 1,
+        int bitsPerSample = 16)
+    {
+        ArgumentNullException.ThrowIfNull(destination);
+        if (AudioData is not { Length: > 0 } pcm)
+        {
+            throw new InvalidOperationException("AudioResult contains no audio data.");
+        }
+
+        var effectiveRate = sampleRate ?? SampleRateHz ?? 24000;
+        WriteWavHeaderAndBody(destination, pcm, effectiveRate, channels, bitsPerSample);
+    }
+
+    /// <summary>
+    /// Writes <see cref="AudioData"/> as a WAV file at <paramref name="path"/>.
+    /// Overwrites the file if it already exists.
+    /// </summary>
+    public void WriteWavFile(
+        string path,
+        int? sampleRate = null,
+        int channels = 1,
+        int bitsPerSample = 16)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(path);
+
+        using var fs = System.IO.File.Create(path);
+        WriteWavTo(fs, sampleRate, channels, bitsPerSample);
+    }
+
+    private static void WriteWavHeaderAndBody(
+        Stream destination,
+        byte[] pcmData,
+        int sampleRate,
+        int channels,
+        int bitsPerSample)
+    {
+        var byteRate = sampleRate * channels * bitsPerSample / 8;
+        var blockAlign = channels * bitsPerSample / 8;
+
+        using var writer = new BinaryWriter(destination, System.Text.Encoding.ASCII, leaveOpen: true);
+
+        writer.Write("RIFF"u8);
+        writer.Write(36 + pcmData.Length);
+        writer.Write("WAVE"u8);
+
+        writer.Write("fmt "u8);
+        writer.Write(16);
+        writer.Write((short)1);
+        writer.Write((short)channels);
+        writer.Write(sampleRate);
+        writer.Write(byteRate);
+        writer.Write((short)blockAlign);
+        writer.Write((short)bitsPerSample);
+
+        writer.Write("data"u8);
+        writer.Write(pcmData.Length);
+        writer.Write(pcmData);
+        writer.Flush();
+    }
 }

src/tests/IntegrationTests/Tests.Audio.cs

@@ -39,4 +39,58 @@ public void AudioResult_SampleRateHz_MirrorsParseResult()
         new AudioResult { MimeType = null }.SampleRateHz.Should().BeNull();
         new AudioResult { MimeType = "audio/wav" }.SampleRateHz.Should().BeNull();
     }
+
+    [TestMethod]
+    public void AudioResult_WriteWavTo_EmitsRiffWaveHeader()
+    {
+        var pcm = new byte[] { 0x01, 0x00, 0x02, 0x00, 0x03, 0x00, 0x04, 0x00 };
+        var result = new AudioResult
+        {
+            AudioData = pcm,
+            MimeType = "audio/L16;codec=pcm;rate=16000",
+        };
+
+        using var ms = new MemoryStream();
+        result.WriteWavTo(ms);
+
+        var bytes = ms.ToArray();
+        bytes.Length.Should().Be(44 + pcm.Length, "WAV header is 44 bytes for PCM");
+
+        // RIFF / WAVE / fmt  / data chunk IDs in the standard offsets.
+        System.Text.Encoding.ASCII.GetString(bytes, 0, 4).Should().Be("RIFF");
+        System.Text.Encoding.ASCII.GetString(bytes, 8, 4).Should().Be("WAVE");
+        System.Text.Encoding.ASCII.GetString(bytes, 12, 4).Should().Be("fmt ");
+        System.Text.Encoding.ASCII.GetString(bytes, 36, 4).Should().Be("data");
+
+        // Sample rate at offset 24 (little-endian uint32) should match parsed rate.
+        BitConverter.ToInt32(bytes, 24).Should().Be(16000);
+
+        // Body should be the PCM payload verbatim.
+        bytes.AsSpan(44).ToArray().Should().BeEquivalentTo(pcm);
+    }
+
+    [TestMethod]
+    public void AudioResult_WriteWavTo_UsesExplicitSampleRateOverParse()
+    {
+        var result = new AudioResult
+        {
+            AudioData = new byte[] { 0, 0 },
+            MimeType = "audio/L16;codec=pcm;rate=24000",
+        };
+
+        using var ms = new MemoryStream();
+        result.WriteWavTo(ms, sampleRate: 48000);
+
+        BitConverter.ToInt32(ms.ToArray(), 24).Should().Be(48000);
+    }
+
+    [TestMethod]
+    public void AudioResult_WriteWavTo_ThrowsWhenNoAudio()
+    {
+        var result = new AudioResult { AudioData = null };
+        using var ms = new MemoryStream();
+
+        var act = () => result.WriteWavTo(ms);
+        act.Should().Throw<InvalidOperationException>();
+    }
 }