Getting started

Under a minute to a real signal, via uvx, scored offline. Your audio never leaves the machine.

0. Confirm the tool runs (zero input)

The self-test downloads nothing, scores a synthetic battery, and exits 0 when healthy.

$ uvx hotato run --suite barge-in
hotato [suite] stack=generic offline=True
  8/8 events pass  (failed=0)
  [PASS] 01-hard-interruption: did_yield=True seconds_to_yield=0.50s talk_over=0.50s
  ...
  exit_code=0

1. Get a dual-channel recording

Real verdicts need caller and agent on separate channels: channel 0 caller, channel 1 agent: overlap as fact, not guesswork. See the capture guides.

2. Score your own call

With VAPI_API_KEY set, capture fetches and scores the recording offline (the only network call). --expect yield means stop; hold means a backchannel like “mhm”, agent keeps talking.

# auto-pull the dual-channel recording from Vapi and score it offline
export VAPI_API_KEY=...
uvx hotato capture --stack vapi --call-id <id>

# no key yet? run the whole capture→score loop on a bundled call
uvx hotato capture --stack vapi --demo

Already have a two-channel WAV?

Already have the recording? Score it directly. Mono needs a caller-onset label instead.

# two-channel WAV (caller on ch0, agent on ch1)
uvx hotato run --stereo call.wav --stack vapi --expect yield --format text

# two separate mono files + a caller onset label (seconds)
uvx hotato run --caller caller.wav --agent agent.wav --onset 2.4 --expect yield

--stack accepts livekit, pipecat, vapi, or generic. For Twilio, Retell, Bland or anything else, use generic.

3. Read the verdict, and audit it

Each event reports three timing signals and a PASS/FAIL. --format json adds the full envelope and fix; --dump-frames writes re-derivable per-frame evidence.

# write per-frame evidence: t_sec, per-channel dBFS, active flags, thresholds
uvx hotato run --stereo call.wav --dump-frames frames.json

4. Or let doctor do all of it

One command scores your recording (or the self-test), renders the visual report with per-event timelines, and opens it in your browser.

uvx hotato doctor --stereo call.wav   # score, render, open
uvx hotato doctor                     # self-test fallback, same flow