A speech download starts with a sharp click. The next recording sounds unnaturally high and finishes early. A streaming preview works, but the downloadable version fails in the same browser. These symptoms can come from the application interpreting generated bytes incorrectly, even when the model produced usable speech.

This audio forensics walkthrough investigates an illustrative migration from an older Gemini TTS integration to Gemini 3.8 TTS. The old exporter assumed every response was raw PCM and added a WAV header. That assumption can now create a WAV file containing another WAV file. A separate playback configuration can make valid samples run at the wrong speed. Neither defect is repaired by asking the narrator to speak more slowly.

The investigation concerns text-to-speech output. The example observations are diagnostic scenarios, not production measurements. The Python checks use authored offline fixtures; no generation request was executed for this article. Documentation was checked on November 16, 2026.

The case file: one model name is not an audio contract

Write the full contract on the incident record: API surface, model identifier, unary or streaming delivery, requested encoding, observed media type, sample rate, channels, and sample width. Without those fields, “the audio changed after the upgrade” gives an engineer too little information to reproduce the defect.

For the Gemini Developer API, the current speech generation guide describes these defaults:

Request familyDefault decoded payloadDefault sample layout
Gemini 3.8 TTS, unaryComplete WAV container24 kHz, mono, signed 16-bit little-endian PCM
Gemini 3.8 TTS, streamingHeaderless PCM chunks24 kHz, mono, signed 16-bit little-endian PCM
Earlier TTS, including 3.1 previewHeaderless PCMVerify the older model's documented contract

The older raw-PCM behavior explains why a previously sensible wrapper becomes the regression. Keep that historical comparison scoped to the Developer API; it is not a rule for every product with “Gemini” in its name.

The current Developer Interactions interface documents response_format.mime_type and sample_rate. Google's separate Cloud Agent Platform TTS overview says its Gemini 3.8 models ignore sampleRate: PCM/WAV remains 24 kHz, while μ-law/A-law is 8 kHz. Meanwhile, the Cloud Text-to-Speech Gemini page says 3.8 is unavailable through the Cloud Text-to-Speech API itself. These are different interfaces, not interchangeable parameter spellings.

The request example below therefore targets Developer Interactions only, at 24 kHz. Before adapting it to a relay, confirm the selected model, Interactions endpoint, encoding fields, and response metadata are supported; the existing Gemini endpoint selection guide explains why matching the wire contract matters.

At the bench: inspect the bytes before touching the voice

Evidence bag A: the response before your exporter

Save the decoded audio payload separately from the file produced by the application. Keep request settings and response metadata alongside it. Compare their sizes and checksums locally. If the response already contains a valid container and the exported file grows by another header, the change happened inside your application.

Start with the first twelve decoded bytes. An ordinary RIFF WAV has RIFF at bytes zero through three and WAVE at bytes eight through eleven. Those markers identify a candidate container; they do not prove the whole file is valid. A truncated response can preserve both markers while losing most of its sample data.

Decode the transport representation exactly once. REST JSON audio data is Base64 text; the sample below uses Python's strict Base64 decoder. An SDK may expose bytes already, so inspect the actual field type before adapting that step. The adjacent Gemini image response validation article covers the same transport-versus-media distinction for downloadable images.

Evidence bag B: the file that clicks

A WAV header belongs outside the sample frames. When a legacy exporter places an entire WAV response inside a new data chunk, the inner header becomes apparent sample values to a PCM player. A click or short burst is plausible; it does not guarantee that this is the only defect.

Do not search the entire recording for the letters RIFF and delete every occurrence. Arbitrary sample bytes can contain those values. Inspect the container structure and the start of its declared sample data. In the narrow migration investigated here, a second WAV signature at that boundary is suspicious enough to reject the export and inspect the original response.

Nor should the repair unconditionally remove the first 44 bytes. Microsoft's RIFF documentation describes chunks with lengths and padding. Additional chunks can move the sample data. A fixed offset can leave metadata in the recording or remove genuine samples, creating a new fault while hiding the old one.

Evidence bag C: the recording that finishes early

For uncompressed audio, duration equals sample-data bytes divided by sample rate, channel count, and bytes per sample. Our mono, 16-bit contract consumes two bytes per frame. An authored fixture containing 48,000 sample bytes therefore represents one second at 24,000 frames per second. A player interpreting those same frames at 48,000 frames per second finishes in half a second.

That example is arithmetic, not a measured Gemini output. It nevertheless gives a useful diagnostic distinction: the correct words arriving uniformly too fast suggest a clock mismatch; a short burst at the beginning suggests a container boundary; sustained harsh noise suggests a broader interpretation error, including encoding or byte order. Symptoms guide inspection rather than establish a diagnosis.

Changing a WAV header from 24,000 to 48,000 does not resample the signal. It relabels how quickly the existing frames should play. If the destination needs another rate, use an actual audio resampler and validate its output separately. Keep the original rate and the converted rate as distinct fields in the asset record.

Repair path A: keep the WAV that already exists

Choose this path for a download service whose consumer expects a complete WAV file. Validate the container, then preserve the returned bytes. Remove the old unconditional wrapping step. Keep raw-response storage separate from publication so a failed validation cannot replace a previously accepted recording.

The following standard-library helper deliberately supports a small contract: ordinary RIFF WAV with integer PCM, one channel, 16-bit samples, one data chunk, and the configured rate. It checks chunk bounds, padding, internal format consistency, and frame alignment. It accepts extra metadata chunks without assuming where samples begin. It rejects unsupported encodings rather than inventing a conversion.

Save it as 01_audio_guard.py. The writer uses Python's wave module, while the reader's explicit checks make this example's acceptance policy visible. WAV extensible, floating-point WAV, RF64, and multiple-data-chunk files require an expanded parser or a dedicated audio library; this helper does not claim to accept every valid WAV variant.

"""Strict 16-bit mono PCM/WAV boundary helpers; no resampling or network I/O."""
import base64
import io
import struct
import wave


def looks_wav(blob):
    return blob[:4] == b"RIFF" and blob[8:12] == b"WAVE"


def pcm_bytes(blob):
    if not blob or len(blob) % 2:
        raise ValueError("Empty audio or incomplete 16-bit mono frame")
    if looks_wav(blob):
        raise ValueError("WAV container found where PCM frames were expected")
    return blob


def wav_frames(blob, rate=24000):
    """Accept one ordinary integer-PCM RIFF file, including extra chunks."""
    if not looks_wav(blob) or len(blob) < 12:
        raise ValueError("Expected RIFF/WAVE")
    if struct.unpack_from("<I", blob, 4)[0] + 8 != len(blob):
        raise ValueError("Truncated WAV or bytes after its RIFF container")
    pos, fmt, frames = 12, None, None
    while pos < len(blob):
        if pos + 8 > len(blob):
            raise ValueError("Truncated chunk header")
        tag, size = struct.unpack_from("<4sI", blob, pos)
        start, end = pos + 8, pos + 8 + size
        if end + (size % 2) > len(blob):
            raise ValueError("Truncated chunk or missing padding")
        if tag == b"fmt ":
            if fmt is not None or size < 16:
                raise ValueError("Invalid or duplicate fmt chunk")
            fmt = struct.unpack_from("<HHIIHH", blob, start)
        elif tag == b"data":
            if frames is not None:
                raise ValueError("Multiple data chunks require a separate policy")
            frames = blob[start:end]
        pos = end + (size % 2)
    if fmt != (1, 1, rate, rate * 2, 2, 16) or frames is None:
        raise ValueError("Expected integer PCM, mono, 16-bit, configured rate")
    return pcm_bytes(frames)


def to_wav(blob, kind, rate=24000):
    if type(rate) is not int or rate <= 0:
        raise ValueError("Sample rate must be a positive integer")
    if kind == "wav":
        wav_frames(blob, rate)
        return blob  # Preserve a validated container byte for byte.
    if kind != "pcm_s16le":
        raise ValueError("Unsupported encoding")
    frames = pcm_bytes(blob)
    output = io.BytesIO()
    with wave.open(output, "wb") as target:
        target.setparams((1, 2, rate, 0, "NONE", "not compressed"))
        target.writeframes(frames)
    return output.getvalue()


def decode_audio(encoded):
    return base64.b64decode(encoded, validate=True)


def aligned_pcm_chunks(chunks):
    """Input: decoded raw PCM chunks from ONE already-validated audio track."""
    pending, total = b"", 0
    for chunk in chunks:
        pending += chunk
        usable = len(pending) - len(pending) % 2
        if usable:
            total += usable
            yield pending[:usable]
            pending = pending[usable:]
    if pending or total == 0:
        raise ValueError("Incomplete final frame or empty stream")

The signature check inside pcm_bytes is intentionally conservative. A matching prefix could occur accidentally in raw samples; treat rejection as a reason to inspect the asset, not permission to automatically strip bytes. The helper also cannot determine the true sample rate of arbitrary headerless audio. Its rate argument must come from the selected API contract and verified metadata.

Repair path B: make raw PCM the explicit boundary

Choose this path when the downstream system mixes segments, feeds a PCM player, or shares one audio path between preview and download. Request raw PCM explicitly, retain its format description, and add a WAV container only at the file-export boundary. If your source is already a validated WAV, obtain frames with wav_frames; do not pass the whole container to a mixer.

This Developer Interactions probe supports either path through TTS_MIME: use audio/wav to preserve a returned container or audio/l16 to request raw samples. Set GEMINI_TTS_MODEL to the supported TTS identifier you intend to test and keep GEMINI_API_KEY in the server environment. Save the code beside the helper as 01_tts_request_template.py. It is a live-request template that was compiled, not executed against an API. It creates probe.wav exclusively; rename that file before another run so the two results remain separate.

"""Developer Interactions API unary probe. NOT executed against an API."""
import json
import os
from pathlib import Path
import runpy
import urllib.error
import urllib.request


def main():
    guard = runpy.run_path(str(Path(__file__).with_name("01_audio_guard.py")))
    mime = os.environ.get("TTS_MIME", "audio/wav")
    kinds = {"audio/wav": "wav", "audio/l16": "pcm_s16le"}
    if mime not in kinds:
        raise ValueError("Probe supports only WAV or raw signed little-endian PCM")
    body = {
        "model": os.environ["GEMINI_TTS_MODEL"],
        "input": [{"type": "user_input", "content": [{
            "type": "text", "text": "Your training session is ready."
        }]}],
        "response_format": {"type": "audio", "mime_type": mime, "sample_rate": 24000},
        "generation_config": {"speech_config": [{"voice": "Kore"}]},
        "stream": False,
    }
    req = urllib.request.Request(
        "https://generativelanguage.googleapis.com/v1beta/interactions",
        data=json.dumps(body).encode(),
        headers={"Content-Type": "application/json", "x-goog-api-key": os.environ["GEMINI_API_KEY"]},
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=90) as response:
        payload = response.read(10_000_001)
    if len(payload) > 10_000_000:
        raise ValueError("Probe response exceeded its size limit")
    result = json.loads(payload)
    if result.get("status") != "completed":
        raise ValueError("Interaction did not complete")
    audio = [part for step in result.get("steps", []) if step.get("type") == "model_output"
             for part in step.get("content", []) if part.get("type") == "audio"]
    if len(audio) != 1:
        raise ValueError("Probe requires exactly one inline audio block")
    part = audio[0]
    if part.get("mime_type") != mime or not isinstance(part.get("data"), str):
        raise ValueError("Audio format or inline data does not match the probe")
    if part.get("sample_rate", 24000) != 24000 or part.get("channels", 1) != 1:
        raise ValueError("Unexpected sample rate or channels")
    wav = guard["to_wav"](guard["decode_audio"](part["data"]), kinds[mime])
    with open("probe.wav", "xb") as output:
        output.write(wav)


if __name__ == "__main__":
    try:
        main()
    except urllib.error.HTTPError as exc:
        raise SystemExit(f"HTTP {exc.code}: inspect the server-side request record") from None
    except (urllib.error.URLError, TimeoutError, ValueError, KeyError, OSError) as exc:
        raise SystemExit(f"Probe stopped: {type(exc).__name__}") from None

The probe expects one completed inline audio block, because its input is one short acceptance sentence. It uses the current Interactions response schema rather than assuming that every successful response contains audio at a fixed list index. Multiple audio blocks, URI-only assets, and incomplete interactions stop this probe instead of becoming a misleading success file. A production adapter can support those cases with explicit policies.

The resulting WAV is checked against the same 24 kHz contract in either mode. For headerless output, that still relies on the service honoring its documented rate; raw samples cannot independently prove the sampling clock. Compare a known-duration fixture through your own playback path before judging generated speech. Keep pronunciation and pacing review as a separate listening check after byte-level validation passes.

The streaming twist: a network chunk is not a sample frame

A streaming implementation needs two boundaries: the API event boundary and the audio frame boundary. Parse the event first, select audio deltas for the intended track, decode each complete Base64 field, and only then send its bytes to the PCM buffer. Joining Base64 strings from independently padded events can corrupt the transport decode.

The aligned_pcm_chunks helper carries an incomplete two-byte frame into the next chunk. This matters even if current API events usually arrive aligned: another transport adapter may split the bytes differently. Use a fresh buffer for each audio track. Never combine fragments from simultaneous requests simply because they reached the same socket.

A successful loop ending is not sufficient evidence that synthesis completed. Preserve the stream's terminal status and distinguish interruption from completion. A connection can stop on an even byte boundary and still omit the final words. The helper detects a partial frame, but only the API state and application acceptance criteria can detect a missing ending.

For a downloadable archive, write frames to one seekable WAV writer and close it after successful completion so its length fields are finalized. Do not prepend a header to every event and concatenate those files. If the bytes are valid but arrive in a burst, the streaming buffering investigation provides an adjacent method for tracing delivery boundaries; its GLM event parser should not be copied into this audio integration.

Close the incident with repeatable evidence

The audio helper's offline suite exercises fourteen cases, including an extra odd-sized metadata chunk, a double wrapper, malformed lengths, mismatched rate, invalid Base64, and every split position in a tiny PCM fixture. Eight additional mocked-response tests cover the request parser without making network calls. Passing these checks establishes the code's behavior on those fixtures. It does not establish model availability, voice quality, relay support, or live stream completeness.

Keep a small acceptance packet for the migration: request mode, requested and observed media types, raw decoded byte count, validated frame count, expected playback rate, and a human listening result for the first and final words. Record the exporter version too. That makes a later regression attributable to a particular boundary rather than to a vague change in “audio quality.”

Roll out one repair path at a time. For a WAV download, compare the saved file with the validated upstream container. For a PCM pipeline, compare the frame bytes before and after wrapping; they should be identical. A legitimate resampling stage changes those bytes, so document and test that stage separately instead of weakening the container check.

A small business use: training narration with instant preview

Consider a training portal that generates short lesson introductions. The author wants to preview narration while it arrives, and the publishing worker needs a downloadable asset. A shared internal PCM contract lets both consumers use the same validated sample layout; the download worker adds the container once. Alternatively, a simpler portal can keep unary WAV output intact and avoid incremental preview altogether.

The useful product decision is whether authors need that preview interaction. Make it explicitly, then test the corresponding audio path. A migration should not quietly change the preview player's sampling clock or the format stored for an already published lesson.

Questions from the audio bench

Can I fix fast playback by asking for slower speech?

First verify the sample clock. A pacing instruction changes the performance; it cannot correct a player interpreting the same frames at the wrong rate. Once the byte contract is correct, evaluate delivery style on its own merits.

Can I join several WAV responses to build one lesson?

Parse each container, require compatible sample layouts, concatenate the extracted frames in the intended order, and write one final container. Joining complete WAV files byte for byte is not the same operation. Keep segment identity so a failed turn can be located without regenerating accepted material.

Does renaming a PCM file to .wav make it playable?

No. A filename does not supply a container or a sampling contract. Wrap verified PCM frames once, or use a raw-audio player configured with the correct rate, channels, width, and byte order.

Related reading

Official references

To evaluate this migration on your intended route, open the Treerouter API documentation and prepare one short speech probe with an explicit format, then compare its decoded bytes with the acceptance contract above.