Symptom → cause → fix
| Symptom | Likely cause | Fix |
|---|---|---|
| Constant hiss/hum, HVAC or fan in transcripts, ASR word errors on a browser/app caller | Noise suppression was disabled on capture (or a raw/BYO track was passed) | Re-enable noiseSuppression (and echoCancellation/autoGainControl) in captureMicrophone() |
| First syllable of each caller turn missing (“…es, that’s right” instead of “Yes, that’s right”) | Turn detector’s prefix_padding_ms too low — the speech-start marker trims real onset before it reaches ASR | Raise prefix_padding_ms on the agent’s turn_detection |
| Echo of the agent’s own voice returning as caller audio; agent cancels itself / stutters — caller on speakerphone or a raw SIP/PSTN leg | No server-side echo canceller on the media plane; browser AEC bypassed or absent | Route through browser AEC where possible; on telephony keep the barge gate conservative and ask the caller to use a handset |
| Level pumping — audio swings loud/quiet, quiet talkers get lost | No server-side automatic gain control; capture-side AGC off | Enable autoGainControl on browser capture; on telephony rely on carrier/handset gain |
| Loud caller clips (distortion) even with clean network, MOS looks fine | Input already clipped upstream (handset/PBX gain staging) before it reached us | Cannot be recovered server-side — fix at the source device/PBX |
TeleQuick Voice does not run echo cancellation (AEC), automatic gain
control (AGC), or a server-side denoise stage in the media plane — that plane
is a codec/timing path by design. Cleanup lives at the capture edge. See
/modalities/voice/concepts/voice-isolation
for why, and what is built.
Narrow it down first
Identify the leg
Is the noisy caller on a browser/app connection or a SIP/PSTN
trunk? Browser/app legs can be cleaned client-side; telephony legs cannot be
cleaned by us at all — their cleanup is entirely carrier/handset side.
Listen to the recording, split by channel
Call recordings are written stereo — caller on the left channel, agent on
the right. Solo the left channel: if the noise/echo is there, it entered
on the inbound leg (capture or carrier). If the agent’s voice is bleeding
into the left channel, you have echo, not a source-noise problem. See
/modalities/voice/observability/call-traces.
Check the media-quality score
The media plane derives a per-call MOS estimate from packet loss and jitter.
A good MOS with bad-sounding audio means the transport is fine and the
problem is signal quality at the source, not the network — don’t chase
jitter buffers. A poor MOS points you at
/modalities/voice/troubleshooting/high-latency
and packet loss instead.
Fix: noise suppression is off on browser capture
captureMicrophone() enables echo cancellation, automatic gain control, and
noise suppression by default. Noisy browser input almost always means those were
overridden — or a pre-captured track was passed that never went through the
device pipeline.
- Restore the defaults
- Force them on explicitly
Fix: first syllables are being clipped
When callers’ openings (“Yes”, “No”, a digit) arrive truncated at ASR, the turn detector is marking speech-start slightly after the real onset.prefix_padding_ms
is the amount of pre-speech audio retained ahead of that marker; raise it so the
onset is preserved.
Agent turn_detection
Milliseconds of audio kept ahead of the detected speech-start marker.
Raise (e.g. 400–600) if the ASR clips first syllables; the cost is a little
extra leading audio per turn. This is the same knob documented in
turn detection.
agent.telequick.dev or push it through the
control-plane API — see
/modalities/voice/runtime/configuration.
Fix: echo on speakerphone (no server AEC)
There is no echo canceller in the media plane. On a browser/app leg the device’s own AEC removes the agent’s voice before it is ever encoded. On a raw SIP/PSTN leg — especially a caller on speakerphone — nothing on our side cancels that echo, so the agent’s text-to-speech can loop back into the inbound audio and self-trigger a false interruption.Prefer an AEC-capable path
Where you control the client, keep callers on the browser/app SDK (device
AEC on) rather than a bare SIP endpoint. A handset or headset beats a
speakerphone in an open room every time.
Keep the barge-in gate conservative on non-AEC legs
Because the agent’s own audio can bleed back on a no-AEC leg, the barge-in
gate is not lowered while the agent is speaking on telephony. If you see
the agent cutting itself off, do not lower that gate on the PSTN path. The
interruption-gate behavior is covered in
/modalities/voice/concepts/turn-detection
and
/modalities/voice/troubleshooting/barge-in.
Rule out real echo vs. self-interruption
Solo the caller (left) channel of the recording. Faint agent voice on that
channel = acoustic echo from the caller’s room → device/handset fix. No echo
on the channel but the agent still stops mid-sentence = a barge-in tuning
problem, not isolation → see the barge-in page above.
Speaker identification, voiceprint/biometrics, and acoustic diarization are
not built — do not reach for them to separate caller from agent. You
already get clean per-party separation structurally: the two legs are distinct
streams and recordings are stereo (caller left / agent right).
What you can and can’t fix here
| If the audio is… | Fixable by you? | Where |
|---|---|---|
| Noisy on a browser/app caller | Yes | Re-enable capture-side noise suppression |
| Clipped at the start of turns | Yes | Raise prefix_padding_ms |
| Echoey on a browser/app caller | Yes | Ensure device AEC is on (don’t disable echoCancellation) |
| Echoey on a speakerphone SIP/PSTN caller | Only at the source | No server AEC — move to handset / keep barge gate high |
| Already clipped/distorted before it reached us | No | Fix the upstream device or PBX gain staging |
Voice isolation concepts
Where AEC/AGC/NS run, and why the media plane has no APM stage.
Turn detection & barge-in
prefix_padding_ms, the interruption gate, and why it stays high on telephony.Browser audio capture
The capture constraints that control browser-side cleanup.
High latency
When a poor MOS points at the network, not signal quality.