Audio I/O
Hydra is strict about audio formats. Get this wrong and you’ll either see invalid_audio errors or distorted playback.
Input (client → server)
Python
Browser (AudioWorklet)
The mic delivers float32 samples; you need to (a) convert to int16 and (b) base64-encode each chunk. Use an AudioWorklet - the deprecated ScriptProcessorNode works for a prototype but blocks the main thread under load.
Output (server → client)
Sample rate is per-model. Read it from session.configured before initializing your audio pipeline.
?model=hydra (bare, no version) currently routes to hydra-v1.0. This parameter will be deprecated in the future.
Choosing the output sample rate for hydra-v1.1
hydra-v1.1 sends its reply audio at the sample rate you ask for, so a 16 kHz telephony leg no longer needs its own resampling step. Set session.output_audio_sample_rate in your first session.configure:
- The rate you’ll actually get is confirmed in
session.configured.session.output_audio_sample_rate. Read it from there rather than assuming the value you sent was honored. - Any other value is rejected with an
errorframe (code: "invalid_request_error",param: "session.configure.session.output_audio_sample_rate"). - This only affects output audio. The caller audio you send in
input_audio_buffer.appendstays 16 kHz PCM16 mono regardless of this setting. hydra-v1.0does not support this field - its output stays fixed at 48000 Hz.
Python
Browser (gapless playback)
Schedule each chunk against a running playCursor so chunks play back-to-back with no audible gap. The AudioContext is created after session.configured arrives so its sample rate matches the server’s.
For barge-in, you reset playCursor = playCtx.currentTime when a fresh response.created arrives - see Turn detection & barge-in.
Common gotchas
- Sending audio before
session.configured- frames are silently dropped; the server does not queue them and does not emit an error. Always wait for thesession.configuredecho before starting the mic. - Sample-rate mismatch - sending 24 kHz audio while claiming PCM16 16 kHz produces unintelligible transcription on the model side. Resample explicitly.
- Stereo input - Hydra expects mono. If you have stereo, downmix before encoding.
Streaming a WAV file (for CI / regression tests)
Replay a known utterance through Hydra and capture the reply to disk
Hydra is built for live mic streams. For test fixtures, regression tests, or batch jobs you sometimes want to replay a known WAV instead. The pattern paces a 16 kHz mono PCM16 WAV at real-time speed, then collects the response audio to disk.
Don’t have a 16 kHz mono WAV? Convert with ffmpeg:
This pattern is for testing only - it doesn’t exercise full-duplex behaviour (no overlap, no barge-in). For interactive use, see the quickstart.
Next
- Turn detection & barge-in - VAD events and how to flush scheduled audio
- Errors & reconnection -
invalid_audioand friends