# Tuning the voice, end to end

Tuning is a loop with evidence in it: draft settings in the Voice Lab, place a test call, read the review of that call, apply what it recommends. The Lab is built on one honesty — the realtime engine is speech-to-speech, so there is no synthesiser with a pitch dial. Every control is either a session parameter or a line of instruction, and each one says which it is.

- **Status:** Available
- **Audience:** both
- **Channels:** phone
- **In the app:** #/phone-advanced, #/calls
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/voice-tuning-cycle/

## The chain of one tuning cycle

1. Trigger — a call sounded wrong, or a review recommended a change.
2. User event — someone opens the Voice Lab from the Phone screen's setup.
3. Authentication and workspace resolution — the Lab is reachable by both audiences over the same implementation.
4. Ingest — a draft profile, held apart from the live settings.
5. Canonical record — the resolved settings are snapshotted on the call's quality record when the test call runs.
6. Reasoning — the model runs under exactly those settings, not under an approximation of them.
7. Knowledge, memory and rules — the behaviour texts and the style block are rendered into the instructions, under their character budgets.
8. Autonomy and approval — a draft affects only the test call until it is applied.
9. Action through a provider — the test call is a real call through the real path.
10. Result — timings measured on the wire, plus the deterministic findings.
11. Relationship, timeline and memory — a test call is still a call and still leaves a record.
12. Audit, usage and Needs You — the review's score, its model-limited findings, and the settings each finding would change.

The snapshot matters more than it looks. Without it, a review months later judges a call against whatever the settings are now, which is how teams end up arguing about a recording nobody can reproduce.

## Two kinds of control, never mixed

| Kind | What it is | Examples | What it cannot do |
|---|---|---|---|
| Engine | A session parameter the model is started with | Model, voice, pinned language, temperature, reply length, end-of-speech silence, interruption thresholds, noise cancellation, hang-up timers | Nothing about it is a suggestion — but it is limited to what the session actually exposes |
| Steering | A line in the instructions the model is asked to follow | Speed, energy, warmth, emotion, pauses, fillers, formality, accent, pronunciation | It is followed approximately, and it costs prompt characters, which cost latency |

The distinction is the Lab's whole design. A control that looks like a hardware dial but is really a sentence in a prompt sets an expectation the system cannot meet, so each control states its kind. The same honesty runs through the human voice profiles: everything the stack cannot set — frequencies, loudness in decibels, jitter, exact pause lengths, a delay before answering — is listed as unsupported rather than shown as a slider that does nothing.

Settings resolve narrowest-wins: the workspace, then a default profile, then a profile by purpose, then one by line number, then one on the contact, and finally the Lab's draft on a test call. There is no campaign model here — "per campaign" means per purpose, of which there are four.

## The review, and why it is not an opinion

Latency is measured on the wire, never from transcript rows. The worker times the caller's last word to the first audio back and posts a timing event per reply, plus an interruption event carrying how long the voice kept talking after the caller spoke over it. The first real call showed "8 ms" beside replies the caller had waited seconds for, because a transcript row arrives when the sentence is complete rather than when it began.

**Deterministic findings** — Slow replies, long gaps, ignored interruptions, false stops, repetition, stock phrases, wrong script, an unheard caller — each paired with the setting change that addresses it.
**The model's opinion on delivery** — Included, and marked as the model's, so it is never mistaken for a measurement.
**Targets** — 2.5 s is the target reply; past 4 s a reply is slow. An interruption the voice ignores for more than two seconds is counted as ignored.
**Model-limited findings** — When the model's own first token is 60% or more of the wait, the finding says so and offers no control to turn. These are listed and counted but do not lower the score; the older, blunter number is kept beside it.

## The change that is almost always worth making

Prompt size. Instruction length is on the record for every session, and the measurements are stark: about 7,500 characters of instructions gave a 1.2–1.8 s first token, and 9,600 gave 2.3–3.4 s. That is why the budgets exist — four knowledge facts within 2,000 characters, 700 characters of memory, 600 for the contact block, and a human profile under roughly 2,500. Adding one more rule to the prompt is not free; it is paid by every caller, on every turn.

One area is not tuned from the Lab at all. The language a call is held in is written into the brief by `voice_region.plan` from the evidence about the person — pinned, remembered, likely from their city or state, or nothing — with a different amount of caller evidence needed in each of those four cases. The levers are therefore the record and the line, not the instruction text: put a city or state on the contact and the call will follow two or three words of the regional language; pin the line and no evidence moves it. Writing your own language instructions into the behaviour block spends characters on a rule that is already there, and a sample phrase written into a brief has been read out to a caller word for word.

> **Note** Two behaviours were measured, found to be model-limited and rolled back rather than left in as prompt text: a respect-word cadence rule that changed nothing in six of eight replies, and murmur handling, where a mumble is written as a word in some language and answered. Both are still measured. Neither is worth prompt characters.

> **Careful** Do not enable a host-spoken acknowledgement while the caller is talking. On the default model a spoken "Mm-hm" cut the caller off and stalled the model for 22 seconds.

## Questions

### Why is there no pitch control?

Because the realtime engine is speech-to-speech: the model produces the audio directly, and there is no separate synthesiser stage with a pitch parameter to set. A control that appeared to change pitch would be a prompt sentence pretending to be a dial.

### The review says a reply was slow but offers no setting. Why?

Because the model's own first token was the majority of the wait. The finding is reported and counted, and deliberately does not lower the score, since penalising a workspace for something no control can change would make the score useless as a signal.

### Does a test call cost the same as a real one?

Yes — it is a real call on the real path, metered on audio tokens like any other, and it produces a real call record. That is what makes the review trustworthy.

## Related

- [Inbound phone call, end to end](https://connectbyjbrh.com/docs/workflows/inbound-phone-call/)
- [The voice talked over the caller](https://connectbyjbrh.com/docs/troubleshooting/voice-cut-the-caller/)
- [Measuring conversational latency correctly](https://connectbyjbrh.com/research/measuring-voice-latency/)
- [What every character of a prompt costs on a live call](https://connectbyjbrh.com/research/prompt-size-and-first-token/)
- [Findings a setting cannot fix](https://connectbyjbrh.com/research/model-limited-findings/)

## What this page is based on

- Reconciled 2026-09-10 against `f5ea518` — `backend/app/voice_region.plan`, read from the code rather than its docstring
- AGENTS.md §9a — the Voice Lab, the review and its thresholds
- `backend/app/voice_style.py`, `voice_quality.py`, `voice_profiles.py`
- Connect capability registry (docs-source/facts.py)