step2

2026-10-17 15:49:20 +01:00
parent 430997bd2e
commit bfed42c3b3
124 changed files with 5646 additions and 249 deletions
@@ -20,6 +20,25 @@ TTS_REFERENCE_AUDIO=/root/pipecat-voice/voice_profiles/solis.wav
 # otherwise the raw string is used. Leave empty to auto-load <audio>.txt.
 TTS_REFERENCE_TEXT=/root/pipecat-voice/voice_profiles/solis.txt

+# --- Drama 3 de-emphasis (TTS_ENGINE=fish) ---
+# Drama 3 can sound overly theatrical/recitative. Two knobs trim that register
+# without changing the voice reference. Leave a sampling variable EMPTY to omit
+# the field and fall back to the server default.
+# Sampling temperature sent to SGLang. Lower values reduce over-articulation;
+# the recitative "radio drama" register lives in the distribution tails, so a
+# lower value makes the delivery flatter. Tunable range: 0.3–0.6.
+TTS_TEMPERATURE=0.45
+# Nucleus sampling top-p: trims the tail of the acoustic token distribution
+# (exaggerated intonations). 0.7–0.8 is the useful range.
+TTS_TOP_P=0.75
+# Optional top-k. Leave empty to omit the field (server default).
+TTS_TOP_K=
+# Neutral style tag prepended to every synthesis request that does not already
+# start with a "[...]" tag. LLM replies carry no tag (the system prompt forbids
+# stage directions), so they get this register; clip banks with their own tag
+# are left untouched. Empty disables the prefix.
+TTS_STYLE_TAG="[conversational, casual]"
+
 # --- Kokoro (TTS_ENGINE=kokoro) ---
 KOKORO_URL=http://localhost:8880
 KOKORO_VOICE=af_heart
@@ -71,15 +90,50 @@ FILLER_ENABLED=true
 FILLER_DELAY_MS=2500
 FILLER_GAIN_IDLE=1.0
 FILLER_GAIN_DUCK=0.15
+# --- Start filler (turn-start acknowledgment when the reply is late) ---
+# A second latency mask, on its own mixer channel: if the first audio chunk of
+# the reply has not reached the mixer within START_FILLER_GO_DELAY ms, one of the
+# phrases below (picked at random) is played so the agent acknowledges the turn
+# while the LLM/TTS are still working. If audio arrives in time the cue is
+# dropped. It shares the filler gain, so it ducks out of the way once the reply
+# starts.
+START_FILLER_ENABLED=true
+# How long (ms) to wait for the first audio chunk of the reply before playing the
+# start filler (default 1200). Measured from chunk ARRIVAL (not from playback
+# start, which would also include the TTS_PREBUFFER_MS jitter buffer). Same idea
+# as FILLER_DELAY_MS, but shorter.
+START_FILLER_GO_DELAY=500
+# Phrases spoken by the start filler, ONE PER LINE (a single line with "|"
+# separators also works). One clip is synthesized per phrase and a RANDOM one is
+# played when the reply is late, so the cue varies turn to turn. The bank follows
+# this list: editing it triggers a full re-synthesis at the next restart (no
+# manual deletion needed), phrases dropped here are deleted on disk, and a
+# failed synthesis keeps the previous clip. An unchanged list is skipped, so
+# startup stays fast. Drama-3 style tags ([calm], [sigh], ...) are passed
+# through to the TTS.
+START_FILLER_TEXTS="[calm] Un momento...
+[thoughtful] A ver, veamos...
+[hesitant] Entonces... echemos un vistazo...
+[sigh] Vale, ya voy..."
+# Directory holding the start-filler clips (kept separate from FILLERS_DIR so
+# they are not added to the round-robin filler bank).
+START_FILLER_DIR=assets/start_filler
 # TTS jitter buffer (ms): how much synthesized audio the mixer buffers before it
 # starts playing the reply. Lower values start speaking sooner; higher values
 # absorb uneven TTS chunk arrival at the cost of added latency. Drama-3's vocoder
-# emits audio in windows of `stream_followup_stride` codec frames (2048 samples =
-# 46.4 ms each); with the recommended server setting (stride 16, ramp
-# "[10,12,16]") the first window is 10 frames = 0.464 s, so 450 ms starts
-# playback on that very first window. Mid-reply underruns resume as soon as any
-# audio is queued again (no full refill).
-TTS_PREBUFFER_MS=450
+# emits audio in windows of codec frames (2048 samples = 46.4 ms each); with the
+# recommended server setting (stride 4, followup 8, overlap 16, crossfade 512)
+# the first window is 4 frames = 185.8 ms and the steady windows are 8 frames =
+# 371.6 ms. The first arrives at the server TTFB (~0.38 s) and the second ~350 ms
+# later, so ANY value in (186, 557] ms primes on the same second window (TTFA
+# ~0.73 s); 550 ms takes the whole ~557 ms cushion for free. That cushion absorbs
+# the drain when several TTS requests share one GPU and produce slower than real
+# time (measured ~1.5x concurrent vs ~0.94x alone); without it every chunk seam
+# starves the queue and pauses playback (a micro-gap at each sentence start).
+# Below ~186 ms playback starts on the first window (TTFA ~= server TTFB) but
+# leaves almost no cushion. Mid-reply underruns resume as soon as any audio is
+# queued again (no refill).
+TTS_PREBUFFER_MS=550
 # Number of TTS requests kept in flight at once. Reply chunks are synthesized
 # ahead of playback (and replayed in order) so each request's start-up latency
 # hides behind the previous chunk's audio instead of leaving an audible gap.
@@ -89,18 +143,98 @@ TTS_PIPELINE_DEPTH=3
 # --- Backchannel (short acknowledgments while the user speaks) ---
 # Master switch. When disabled, no during-utterance acknowledgment is played.
 BACKCHANNEL_ENABLED=true
-# Directory of preloaded "*.raw" PCM clips (16-bit LE mono, 44.1 kHz), e.g.
-# mmhmm / ajá / claro. Played round-robin.
+# Directory of the generated "*.raw" PCM clips (16-bit LE mono, 44.1 kHz). One
+# clip is synthesized per phrase of BACKCHANNEL_TEXTS at startup.
 BACKCHANNEL_DIR=assets/backchannel
+# Phrases spoken by the backchannel, ONE PER LINE (a single line with "|"
+# separators also works). One clip is synthesized per phrase and a RANDOM one is
+# played, so the cue varies from turn to turn. The bank follows this list:
+# editing it triggers a full re-synthesis at the next restart (no manual
+# deletion needed), phrases dropped here are deleted on disk, and a failed
+# synthesis keeps the previous clip. An unchanged list is skipped, so startup
+# stays fast. Drama-3 style tags ([calm], ...) are passed through to the TTS.
+#
+# A line may start with an optional "category::" prefix (e.g. "agree::..."); the
+# scheduler uses it to progress through the turn (an acknowledgment first,
+# agreement later) and to avoid chaining two cues of the same kind. Lines
+# without a prefix belong to the default "ack" category.
+BACKCHANNEL_TEXTS="ack::[calm] Mm-hmm...
+ack::[attentive] Ajá...
+agree::[agreeing] Claro...
+ack::[listening] Ya veo..."
 # Mix gain applied to the backchannel channel (0..1). Kept low so the cue stays
 # in the background.
-BACKCHANNEL_GAIN=0.35
-# Continuous speech required (ms) before the first backchannel of a turn.
+BACKCHANNEL_GAIN=0.55
+# Confirmed speech required (ms) before the first cue may be considered.
 BACKCHANNEL_MIN_SPEECH_MS=1500
-# Minimum spacing (ms) between two backchannels. Clamped to >= MIN_SPEECH_MS.
+# Base spacing (ms) between two cues of the same turn; randomized by ±JITTER/2.
 BACKCHANNEL_INTERVAL_MS=3000
-# Maximum backchannels emitted per user turn.
-BACKCHANNEL_MAX_PER_TURN=2
+# Timing jitter (ms): delays the first cue by 0..JITTER after MIN_SPEECH_MS and
+# spreads the spacing, so cues don't land on a fixed cadence.
+BACKCHANNEL_JITTER_MS=1200
+# Micro-pause window (ms): the cue lands only while the user is in a short
+# pause. The reaction DEPTH is drawn at random inside [MIN, MAX] per pause, so
+# cues don't all land at exactly MIN. Below MIN the user is likely still
+# mid-word; above MAX (capped below VAD_MIN_SILENCE_MS) the utterance is about
+# to close.
+BACKCHANNEL_PAUSE_MIN_MS=96
+BACKCHANNEL_PAUSE_MAX_MS=260
+# Probability (0..1) of cueing when a qualifying micro-pause occurs.
+BACKCHANNEL_PROB=0.65
+# Random per-cue volume scaling (± fraction) so cues don't sit at a fixed level.
+BACKCHANNEL_VOLUME_JITTER=0.2
+# Maximum cues emitted per user turn.
+BACKCHANNEL_MAX_PER_TURN=3
+
+# --- Multilingual clip banks (backchannel + filler + start filler) ---
+# Every clip bank lives in a per-language subdirectory `<dir>/<lang>` named after
+# the ISO 639-1 code (<dir>/<lang>/, e.g. assets/backchannel/es/), including the
+# default language LANG_DEFAULT. When the user is detected speaking a different
+# language, that language's banks are generated on demand into their own
+# subdirectory and the session switches to them. Each language has its own
+# directory, so regenerating one never removes the clips of another.
+LANG_DEFAULT=es
+# Detect the user's language with a dedicated LLM call (a short auxiliary
+# request that returns only the ISO code) and switch the banks when it differs
+# from the active one. Requires the LLM (LLM_ENABLED=true).
+LANG_DETECT_ENABLED=true
+# Minimum transcript length (chars) before a sample is sent to the LLM.
+LANG_MIN_CHARS=12
+# The first user turn is always checked; afterwards the language is re-checked
+# once every N turns, so a mid-conversation switch is picked up without paying
+# for a detection call on every turn.
+LANG_REDETECT_EVERY=5
+# Built-in phrase tables cover es/en/it/fr/de/pt. For any other language the
+# phrase list is generated by the LLM; set false to keep only the tables.
+LANG_LLM_FALLBACK_ENABLED=true
+
+# --- Per-session audit log ---
+# Writes one structured JSONL file per WebSocket session: a configuration
+# snapshot at the start, every inbound control message and outbound event, the
+# cue emissions, the language switches, the barge-ins / interrupts and an
+# event-count summary at the end. Useful for post-mortem analysis and for
+# tuning latency knobs (FILLER_DELAY_MS, START_FILLER_GO_DELAY, ...). One
+# <id>.jsonl file per session, written under SESSION_AUDIT_DIR.
+SESSION_AUDIT_ENABLED=true
+SESSION_AUDIT_DIR=logs/sessions
+
+# --- External audio source (URL / radio / YouTube) ---
+# Injects an audio stream — a direct media URL, an Icecast/Shoutcast radio or a
+# YouTube link — into the mixer's own "external" channel, mixed under the
+# agent's voice. Demonstrated in the /mivocero client (URL box + Play/Stop +
+# volume slider). Decoding is delegated to external tools:
+#   * ffmpeg  — decodes direct URLs, radio and HLS streams (required);
+#   * yt-dlp  — resolves YouTube URLs to a decodable stream (YouTube only).
+# A barge-in (interrupt) stops the agent but leaves this background source
+# playing; the external channel does not count as the agent speaking.
+# Gain applied to the external channel (kept below 1 so it sits under the voice).
+EXTERNAL_AUDIO_GAIN=0.6
+# Override the decoder binaries if they are not on PATH.
+MEDIA_FFMPEG_BIN=ffmpeg
+MEDIA_YTDLP_BIN=yt-dlp
+# Extra yt-dlp arguments (space-separated), e.g. to pass cookies or a JS
+# runtime: "--cookies /path/cookies.txt". Leave empty normally.
+MEDIA_YTDLP_ARGS=

 # --- LLM reasoning (OpenAI-compatible chat-completions endpoint) ---
 # When enabled, the user transcript is sent to the model and the reply is
@@ -143,12 +277,35 @@ LLM_DIRECT_ANSWERS=true
 # word-boundary flush (chunks then end on sentence punctuation only).
 LLM_STREAM_FIRST_CHUNK_CHARS=20
 # Same threshold for every chunk after the first. Larger chunks give better
-# prosody; smaller ones keep the audio flowing while the model is generating.
-LLM_STREAM_CHUNK_CHARS=120
+# prosody and fewer TTS requests: each chunk is a separate request with its own
+# start-up and its own audio seam, so a larger value cuts the number of seams
+# (where the TTS queue can starve) per reply.
+LLM_STREAM_CHUNK_CHARS=240
 # Optional system prompt override. Leave unset for the built-in voice-assistant
 # prompt (see `DEFAULT_LLM_SYSTEM_PROMPT` in src/config.rs).
 #LLM_SYSTEM_PROMPT=

+# --- Tool calling (configurable HTTP tools) ---
+# Lets the model call external HTTP services (weather, home automation, a
+# webhook, …) before answering. The deployment's vLLM server runs without a
+# tool parser, so it returns the call as text in the Qwen native
+# `<tool_call>` format: the engine parses it client-side, executes the HTTP
+# request and hands the result back to the model (see src/tools.rs). The
+# tool-call block is never spoken nor shown in the chat box.
+# Enabled automatically when LLM_TOOLS_FILE points to a valid tool file.
+LLM_TOOLS_ENABLED=false
+# JSON file with the tool definitions (name, description, JSON schema, url,
+# method, headers). See tools.example.json.
+LLM_TOOLS_FILE=
+# Maximum tool-call rounds per turn (call → execute → re-prompt). Bounds
+# runaway loops; the first round is the model's initial reply.
+LLM_TOOL_MAX_ITERATIONS=4
+# Timeout of a single tool HTTP request, in seconds.
+LLM_TOOL_TIMEOUT_SECS=15
+# Tool responses are truncated to this many characters before being handed
+# back to the model (keeps the context small).
+LLM_TOOL_RESULT_MAX_CHARS=2000
+
 # --- HTTPS (optional) ---
 # Set BOTH to serve HTTPS/WSS instead of plain HTTP. A secure context is
 # required by browsers to grant microphone access (getUserMedia) when the page
@@ -15,6 +15,8 @@ Cargo.lock.temp
 *.log
 *.tmp
 *.bak
+# Per-session audit logs (SESSION_AUDIT_DIR)
+/logs/

 # --- Variabili d'ambiente e credenziali ---
 .env
@@ -36,9 +36,27 @@ Browser mic ──► WebSocket PCM ──► STT (Parakeet/ONNX) + VAD/EOU
  the reply is late*: it is scheduled `FILLER_DELAY_MS` (default 2500 ms) after
  the turn starts and dropped if the response audio has already begun. Clips are
  played round-robin from `FILLERS_DIR`; `FILLER_ENABLED=false` disables it.
+- **Start filler** — a second latency mask on its own mixer channel: if the first
+  audio chunk of the reply has not reached the mixer within
+  `START_FILLER_GO_DELAY` (default 1200 ms) the agent plays a short
+  acknowledgment ("Un momento...") while the LLM/TTS are still working, and drops
+  it as soon as audio arrives in time. One phrase is picked **at random** from
+  `START_FILLER_TEXTS`, so the cue varies turn to turn. Independent of the delayed
+  latency filler above; `START_FILLER_ENABLED=false` disables it. See
+  [Fillers](#fillers--end-of-utterance-acknowledgments).
 - **During-utterance backchannel** — short acknowledgments ("mm-hmm", "ajá")
  are mixed in at a reduced gain *while the user is speaking*, so the agent
-  signals it is listening without taking the turn. Plugin-style `.env` config.
+  signals it is listening without taking the turn. Like the start filler the
+  bank is a phrase list (`BACKCHANNEL_TEXTS`) with Drama-3 tags, one clip per
+  phrase synthesized at startup. To sound natural the scheduler cues only on a
+  VAD **micro-pause**, randomizes the timing, gates each pause probabilistically,
+  avoids repeating the recent clips, drifts the volume slightly and follows a
+  **category** progression through the turn (`category::phrase` lines).
+- **External audio injection** — a dedicated mixer channel can play a background
+  source (direct audio URL, Icecast/Shoutcast radio, HLS, or a YouTube link)
+  alongside the agent's voice, with an independent runtime volume and its own
+  decoder process (`ffmpeg` for URLs/radio, `yt-dlp` for YouTube). See
+  [External audio injection](#external-audio-injection).
 - **Barge-in / interrupt** — cancels in-flight synthesis and flushes audio,
  triggered client-side or server-side by the VAD.
 - **Voice cloning** — reference audio + transcript (Fish Audio `references`).
@@ -55,10 +73,20 @@ Browser mic ──► WebSocket PCM ──► STT (Parakeet/ONNX) + VAD/EOU
  (first chunk after a few words, tunable) for the lowest time-to-first-audio;
  chain-of-thought (`reasoning_content` / ` thinking`) is stripped from both the
  audio and the chat box.
+- **Tool calling** — the model can call external HTTP tools described in a JSON
+  file (`LLM_TOOLS_FILE`) before answering. Calls are parsed client-side from
+  the model's native `<tool_call>` format, executed over HTTP and fed back to
+  the model; the tool-call block is never spoken. See
+  [Tool calling](#tool-calling).
 - **Embedded playground** — a single-page HTML client served at `/`.
 - **Mivocero speech-to-speech client** — an example agent client at `/mivocero`
  with a microphone, a live chat box (user transcript + streaming assistant
  reply) and a text composer, useful to drive a full STT → LLM → TTS turn.
+- **Per-session audit log** — each WebSocket session can be recorded to a
+  structured JSONL file: the configuration snapshot, every inbound control
+  message and outbound event, the cue emissions, the language switches, the
+  barge-ins and an end-of-session summary. Best-effort and off the audio hot
+  path. See [Session audit log](#session-audit-log).

 ---

@@ -72,6 +100,9 @@ Browser mic ──► WebSocket PCM ──► STT (Parakeet/ONNX) + VAD/EOU
 - *(Optional)* An OpenAI-compatible chat-completions endpoint (e.g. a local
  vLLM / SGLang server) for the LLM reasoning stage. Without it the pipeline is
  a plain STT → TTS echo.
+- *(Optional)* `ffmpeg` on `PATH` (or `MEDIA_FFMPEG_BIN`) to inject external
+  audio from a URL / radio stream, and `yt-dlp` (or `MEDIA_YTDLP_BIN`) to inject
+  a YouTube link. Both are only needed for the external audio channel.

 ---

@@ -152,6 +183,10 @@ See [`.env.example`](.env.example) for a copy-paste template.
 | `TTS_VOICE` | `default` | Voice identifier. |
 | `TTS_REFERENCE_AUDIO` | `…/voice_profiles/solis.wav` | Voice-cloning reference WAV (path on the TTS server). |
 | `TTS_REFERENCE_TEXT` | *(empty)* | Reference transcript. If it names an existing `.txt`, its contents are loaded; otherwise the raw string is used. Empty → auto-load `<audio-stem>.txt`. |
+| `TTS_TEMPERATURE` | `0.45` | Sampling temperature sent to the SGLang speech endpoint (`fish` engine). Lower values flatten the delivery — the recitative "radio drama" register lives in the distribution tails. Empty omits the field (server default). |
+| `TTS_TOP_P` | `0.75` | Nucleus sampling `top_p` sent to SGLang. Trims the tail of the acoustic token distribution, where exaggerated intonations live. Empty omits the field. |
+| `TTS_TOP_K` | *(unset)* | Optional `top_k` sampling. Unset/empty omits the field (server default). |
+| `TTS_STYLE_TAG` | `[conversational, casual]` | Neutral style tag prepended to every synthesis request that does not already start with a `[...]` tag. LLM replies carry no tag (the system prompt forbids stage directions), so they get this register; clip banks with their own tag are left untouched. Empty disables the prefix. **Quote the value in `.env`** (it contains a space). |
 | `KOKORO_URL` | `http://localhost:8880` | Kokoro HTTP endpoint (`kokoro` engine). |
 | `KOKORO_VOICE` | `af_heart` | Kokoro voice name. |
 | `STT_MODEL_PATH` | `models/parakeet` | Directory of the Parakeet TDT ONNX pipeline (see below). |
@@ -167,19 +202,38 @@ See [`.env.example`](.env.example) for a copy-paste template.
 | `VAD_SEGMENT_STT` | `true` | Feed the STT engine with VAD-segmented utterances instead of the worker's RMS segmentation. |
 | `VAD_BARGE_IN` | `true` | Interrupt the agent when the user starts speaking over it. |
 | `VAD_DEBUG` | `false` | Log the speech probability of every analysis window. |
-| `FILLERS_DIR` | `assets/fillers` | Directory of `*.raw` filler PCM files (16-bit LE mono, 44.1 kHz), played round-robin, at most once per turn. |
+| `FILLERS_DIR` | `assets/fillers` | Directory of `*.raw` filler PCM files (16-bit LE mono, 44.1 kHz), played round-robin, at most once per turn. Clips live in a per-language subdirectory `<dir>/<lang>` (e.g. `assets/fillers/es/`). |
 | `FILLER_ENABLED` | `true` | Master switch for the end-of-turn filler. `false` => no filler is ever queued. |
 | `FILLER_DELAY_MS` | `2500` | How long (ms) to wait for the response audio to start before playing the filler. If the reply starts earlier, the filler is dropped instead of talking over the beginning of the answer. |
 | `FILLER_GAIN_IDLE` | `1.0` | Filler gain when TTS is idle. |
-| `FILLER_GAIN_DUCK` | `0.15` | Filler gain while TTS is active (ducking). |
-| `TTS_PREBUFFER_MS` | `450` | Synthesized audio (ms) buffered on the TTS channel before the reply starts playing. Lower = the agent speaks sooner; higher = fewer drop-outs on uneven TTS chunk arrival. Only awaited at the start of a reply; mid-reply underruns resume as soon as any audio is queued again. |
+| `FILLER_GAIN_DUCK` | `0.15` | Filler gain while TTS is active (ducking). Also applies to the start-filler channel. |
+| `START_FILLER_ENABLED` | `true` | Master switch for the **start filler** — a turn-start acknowledgment queued on its own mixer channel when the reply audio is late, independently of the delayed filler above. `false` => no cue is ever queued. |
+| `START_FILLER_GO_DELAY` | `1200` | How long (ms) the agent waits for the **first audio chunk of the reply** to reach the mixer before queueing the start filler. If audio arrives within this window the cue is dropped instead of talking over the beginning of the answer. The gate is latched on chunk *arrival* (`AudioMixer::tts_audio_arrived`), not on playback start, so it does not wait for the `TTS_PREBUFFER_MS` jitter buffer. Same idea as `FILLER_DELAY_MS`, but shorter — the start filler only covers the gap before the reply begins, not the whole generation. |
+| `START_FILLER_TEXTS` | `[calm] Un momento...` | Phrases spoken by the start filler, **one per line** (a `\|` separator also works). One clip is synthesized per phrase and a **random** one is played when the reply is late, so the acknowledgment varies. Editing the list re-synthesizes the whole bank at the next restart (no manual deletion); an unchanged list is skipped to keep startup fast, and a failed synthesis keeps the previous clip. Drama-3 style tags (`[calm]`, `[sigh]`, …) are passed through to the TTS. |
+| `START_FILLER_DIR` | `assets/start_filler` | Directory holding the start-filler clips (`sf01.raw`, `sf02.raw`, …, plus a `texts.txt` list index). Clips live in a per-language subdirectory `<dir>/<lang>` (e.g. `assets/start_filler/es/`). Kept out of `FILLERS_DIR` so the clips are not part of the round-robin filler bank. |
+| `TTS_PREBUFFER_MS` | `550` | Synthesized audio (ms) buffered on the TTS channel before the reply starts playing. Lower = the agent speaks sooner; higher = fewer drop-outs on uneven TTS chunk arrival. With the deployment's vocoder windows (first `185.8` ms, then `371.6` ms), any value in `(186, 557]` ms primes on the *same* second window, so `550` takes the whole cushion at no extra TTFA (~`0.73 s`). Below the first window (~`186` ms) playback starts on that window (TTFA ≈ server TTFB, ~`0.38 s`) but leaves almost no margin and exposes chunk seams. Only awaited at the start of a reply; mid-reply underruns resume as soon as any audio is queued again. |
 | `TTS_PIPELINE_DEPTH` | `3` | How many TTS requests may be in flight at once. Chunks are synthesized ahead of playback and replayed in order, so each request's start-up latency hides behind the previous chunk's audio. `1` restores strictly serial synthesis. |
 | `BACKCHANNEL_ENABLED` | `true` | Master switch for during-utterance acknowledgments. |
-| `BACKCHANNEL_DIR` | `assets/backchannel` | Directory of `*.raw` backchannel PCM clips (16-bit LE mono, 44.1 kHz). |
+| `BACKCHANNEL_DIR` | `assets/backchannel` | Directory of the generated `*.raw` backchannel PCM clips (16-bit LE mono, 44.1 kHz; `bc01.raw`, `bc02.raw`, …, plus a `texts.txt` list index). Clips live in a per-language subdirectory `<dir>/<lang>` (e.g. `assets/backchannel/es/`). |
+| `BACKCHANNEL_TEXTS` | `ack::[calm] Mm-hmm...` … | Phrases spoken by the backchannel, **one per line** (a `\|` separator also works). One clip is synthesized per phrase and one is played per cue. Editing the list re-synthesizes the whole bank at the next restart (no manual deletion); an unchanged list is skipped to keep startup fast, and a failed synthesis keeps the previous clip. Drama-3 style tags (`[calm]`, …) are passed through to the TTS. A line may carry an optional **`category::`** prefix (e.g. `agree::[agreeing] Claro...`) used to progress through the turn; a line without it belongs to the default `ack` category. |
 | `BACKCHANNEL_GAIN` | `0.35` | Mix gain applied to the backchannel channel (0..1). |
-| `BACKCHANNEL_MIN_SPEECH_MS` | `1500` | Continuous speech required before the first backchannel of a turn. |
-| `BACKCHANNEL_INTERVAL_MS` | `3000` | Minimum spacing between two backchannels (clamped to ≥ `BACKCHANNEL_MIN_SPEECH_MS`). |
-| `BACKCHANNEL_MAX_PER_TURN` | `2` | Maximum backchannels emitted per user turn. |
+| `BACKCHANNEL_MIN_SPEECH_MS` | `1500` | Confirmed speech required before the first cue may be considered. |
+| `BACKCHANNEL_INTERVAL_MS` | `3000` | Base spacing between two cues of the same turn; randomized by ±`BACKCHANNEL_JITTER_MS`/2. |
+| `BACKCHANNEL_JITTER_MS` | `1200` | Timing jitter: delays the first cue by `0..JITTER` after `BACKCHANNEL_MIN_SPEECH_MS` and spreads the spacing. |
+| `BACKCHANNEL_PAUSE_MIN_MS` | `96` | Lower bound of the VAD micro-pause window (ms). The reaction **depth** inside a pause is drawn at random in `[MIN, MAX]`, so cues don't all land at exactly `MIN`. Below this the user is likely still mid-word. |
+| `BACKCHANNEL_PAUSE_MAX_MS` | `260` | Upper bound of the micro-pause window, capped below `VAD_MIN_SILENCE_MS` so a cue never lands on the pause that closes the turn. |
+| `BACKCHANNEL_PROB` | `0.65` | Probability (0..1) of cueing on a qualifying micro-pause — keeps the agent from acknowledging every pause. |
+| `BACKCHANNEL_VOLUME_JITTER` | `0.2` | Random per-cue volume scaling (± fraction), so cues don't sit at a fixed level. |
+| `BACKCHANNEL_MAX_PER_TURN` | `3` | Maximum backchannels emitted per user turn. |
+| `LANG_DEFAULT` | `es` | Base language of the **filler, start-filler and backchannel** banks — its clips live in the `<dir>/<lang>` subdirectory (e.g. `assets/backchannel/es/`). Other languages are generated on demand into their own per-language subdirectories. See [Multilingual clip banks](#multilingual-clip-banks). |
+| `LANG_DETECT_ENABLED` | `true` | Master switch for LLM-based language detection. Requires the LLM (`LLM_ENABLED=true`). |
+| `LANG_MIN_CHARS` | `12` | Minimum transcript length (chars) before a sample is sent to the detector. |
+| `LANG_REDETECT_EVERY` | `5` | The first user turn is always checked; afterwards the language is re-checked once every N turns. |
+| `LANG_LLM_FALLBACK_ENABLED` | `true` | Phrase tables cover `es/en/it/fr/de/pt`; for any other language the phrase list is generated with the LLM. `false` keeps only the tables. |
+| `EXTERNAL_AUDIO_GAIN` | `0.6` | Mix gain applied to the external audio channel (0..1) at session start. Overridable at runtime from the Mivocero volume slider. |
+| `MEDIA_FFMPEG_BIN` | `ffmpeg` | `ffmpeg` binary used to decode a URL / radio / HLS stream into PCM. |
+| `MEDIA_YTDLP_BIN` | `yt-dlp` | `yt-dlp` binary used to resolve a YouTube link to a direct stream URL. |
+| `MEDIA_YTDLP_ARGS` | *(empty)* | Extra whitespace-separated args appended to the `yt-dlp` invocation (e.g. `--cookies /path/cookies.txt` when YouTube asks for bot verification, or a custom `--extractor-args`). |
 | `LLM_ENABLED` | *(auto)* | Master switch for the LLM reasoning stage. Default: enabled when `LLM_BASE_URL` and `LLM_MODEL` are both set. When `false`, the pipeline is a plain STT → TTS echo. |
 | `LLM_BASE_URL` | *(empty)* | Base URL of the OpenAI-compatible endpoint; the client posts to `{LLM_BASE_URL}/chat/completions`. |
 | `LLM_API_KEY` | `EMPTY` | Bearer token sent in the `Authorization` header (local servers usually ignore it). |
@@ -188,14 +242,21 @@ See [`.env.example`](.env.example) for a copy-paste template.
 | `LLM_TEMPERATURE` | `0.7` | Sampling temperature. |
 | `LLM_STREAM` | `true` | `true` → SSE token streaming, TTS starts on the first words; `false` → one blocking request, the whole reply is synthesized at once. |
 | `LLM_STREAM_FIRST_CHUNK_CHARS` | `20` | Characters buffered before the **first** chunk is sent to the TTS, cut on a word boundary. Small = the agent starts speaking on the first few words. `0` disables the early flush. |
-| `LLM_STREAM_CHUNK_CHARS` | `120` | Same threshold for every following chunk (larger chunks give better prosody). `0` disables. |
+| `LLM_STREAM_CHUNK_CHARS` | `240` | Same threshold for every following chunk (larger chunks give better prosody and fewer TTS seams). `0` disables. |
 | `LLM_HISTORY_MESSAGES` | `16` | Rolling conversation window (user+assistant messages) kept across turns. |
 | `LLM_ENABLE_THINKING` | *(unset)* | `false` sends `chat_template_kwargs: {"enable_thinking": false}` — turns Qwen3-style thinking off on vLLM/SGLang so the model answers directly. Unset omits the vendor-specific field entirely (safe for strict OpenAI-compatible servers). |
 | `LLM_STRIP_REASONING` | `true` | Drop the chain-of-thought from the reply before it reaches the chat box / TTS: ignores `reasoning_content` deltas and removes inline think blocks. `false` passes the raw output through. |
 | `LLM_DIRECT_ANSWERS` | `true` | Append an "answer directly, never narrate your reasoning" directive to the system prompt. |
 | `LLM_SYSTEM_PROMPT` | *(built-in)* | Overrides the system prompt. The default asks for short, spoken-friendly replies (no markdown / bullet points). |
+| `LLM_TOOLS_ENABLED` | *(auto)* | Master switch for tool calling. Default: enabled when `LLM_TOOLS_FILE` is a non-empty path. |
+| `LLM_TOOLS_FILE` | *(empty)* | JSON file with the tool definitions (`name`, `description`, `parameters` JSON schema, `url`, `method`, `headers`). See [Tool calling](#tool-calling) and [`tools.example.json`](tools.example.json). |
+| `LLM_TOOL_MAX_ITERATIONS` | `4` | Maximum tool-call rounds per turn (call → execute → re-prompt). Bounds runaway loops. |
+| `LLM_TOOL_TIMEOUT_SECS` | `15` | Timeout of a single tool HTTP request. |
+| `LLM_TOOL_RESULT_MAX_CHARS` | `2000` | Tool responses are truncated to this many characters before being handed back to the model. |
 | `TLS_CERT` | *(empty)* | PEM certificate chain. Set together with `TLS_KEY` to serve HTTPS/WSS. |
 | `TLS_KEY` | *(empty)* | PEM private key matching `TLS_CERT`. |
+| `SESSION_AUDIT_ENABLED` | `true` | Write a structured JSONL audit file per WebSocket session (config snapshot, inbound control messages, every outbound event, cues, language switches, barge-ins, end-of-session summary). Best-effort — a write failure never affects the session. See [Session audit log](#session-audit-log). |
+| `SESSION_AUDIT_DIR` | `logs/sessions` | Directory holding the per-session audit files (`<id>.jsonl`). Relative to the process working directory; git-ignored. |

 ---

@@ -268,9 +329,10 @@ An unknown value panics at startup with a clear message.

 ##### Starting the Drama 3 backend (SGLang-Omni)

-The `fish` engine talks to an **SGLang-Omni** server running Drama 3. Start it
-with the vocoder streaming window narrowed, otherwise the vocoder emits ~3 s
-bursts and the client is forced into a large pre-buffer:
+The `fish` engine talks to an **SGLang-Omni** server running Drama 3. The
+vocoder emits audio in **windows** of codec frames (2048 samples = 46.4 ms each);
+the window sizes are the single biggest lever on latency, so the server must be
+started with them tuned:

 ```bash
 sgl-omni serve \
@@ -278,8 +340,12 @@ sgl-omni serve \
    --host 0.0.0.0 --port 8000 \
    --tts_engine.gpu_memory_fraction 0.45 \
    --tts_engine.factory.max_running_requests 4 \
-    --vocoder.factory.stream_followup_stride 16 \
-    --vocoder.factory.stream_followup_stride_ramp "[10,12,16]"
+    --tts_engine.factory.enable_async_decode true \
+    --vocoder.factory.stream_stride 4 \
+    --vocoder.factory.stream_followup_stride_ramp "[8,8,8]" \
+    --vocoder.factory.stream_followup_stride 8 \
+    --vocoder.factory.stream_overlap_tokens 16 \
+    --vocoder.factory.stream_crossfade_samples 512
 ```

 In this deployment the launcher is `/root/drama3/start-drama3.sh` and the server
@@ -290,26 +356,71 @@ pm2 restart start-drama3 --update-env   # after editing the launcher
 pm2 logs start-drama3 --lines 100       # CUDA-graph rebuild takes ~2 min at start
 ```

-The two `--vocoder.factory.*` overrides are the key part:
+| Flag | Value | Meaning |
+|---|---|---|
+| `stream_stride` | `4` | **First** window, in codec frames (decoded with *no* overlap context). Sets the server TTFB floor: at `4` it is ~`0.38 s`, at `16` it is ~`1.2 s`, because the TTS engine must emit that many codec tokens before the vocoder can decode anything. |
+| `stream_followup_stride` | `8` | Steady-state window: `8` frames = `0.372 s`, arriving ~`0.35 s` apart (the server runs at ~`0.95×` real time), so the client queue grows and never starves. Larger windows mean **fewer seams** per second, which is what removes the audible artifacts. Upstream default `64` ⇒ `2.97 s` bursts. |
+| `stream_followup_stride_ramp` | `"[8,8,8]"` | Windows 2..4, as a JSON tuple. Keep it flat: a *rising* ramp (e.g. `[4,6,10]`, or the upstream `(10,12,32)`) makes later windows arrive after the small ones have drained, which gaps playback at the start of a reply. |
+| `stream_overlap_tokens` | `16` | Decoder warm-up context. It is decoded and **discarded** on output, so it only costs compute. This is the seam-quality lever: with too little context the streaming decoder wobbles in timbre/pitch at each seam (an audible "detune"/falsetto on long replies). `16` with stride `8` is a `(16+8)/8 = 3×` real-time decode load and stays sustainable (~`0.95×` ratio); the same `16` with stride `4` would be 5× and is **not** sustainable. Upstream default `32`. |
+| `stream_crossfade_samples` | `512` | ~`11.6 ms` blend at each window seam, smoothing the hand-off between windows. |

-| Flag | Meaning |
-|---|---|
-| `stream_followup_stride` | Steady-state window, in codec frames (`2048` samples = `46.4 ms` each). `16` ⇒ `0.743 s` bursts; the upstream default `64` ⇒ `2.97 s`. |
-| `stream_followup_stride_ramp` | Window sizes for the first windows, as a JSON tuple. `[10,12,16]` emits a `0.464 s` then a `0.557 s` window first, so playback can start sooner. Upstream default `(10,12,32)`. |
+Measured on this deployment (with the voice-cloning reference), server-side:
+
+| Config | TTFB | Real-time ratio |
+|---|---|---|
+| `stream_stride 4`, followup `8`, overlap `16`, crossfade `512` *(this deployment)* | **~0.38 s** | ~`0.94–0.98×` |
+| `stream_stride 4`, followup `4`, overlap `8`, crossfade `256` | ~`0.38 s` | ~`0.95×` (but audible detune / micro-gaps on long replies) |
+| `stream_stride 16`, overlap `16` | ~`1.2 s` | ~`1.0×` |
+
+The engine's Time-to-First-Audio is essentially `TTFB + (TTS_PREBUFFER_MS − first
+window)`, quantized to the window the pre-buffer lands on. With this config the
+first window is `185.8` ms and the second `371.6` ms, so any `TTS_PREBUFFER_MS`
+in `(186, 557]` ms primes on the **same** second window → TTFA ≈ `0.73 s`. The
+deployment ships `550 ms`: the whole cushion, no extra latency. Dropping to a
+value below the first window (~`186` ms) starts playback on the first window
+(TTFA ≈ `0.38 s`) but leaves little margin, and under concurrent TTS requests the
+per-request throughput dips below real time (measured ~`1.5×` vs ~`0.94×` alone),
+so each chunk seam starves the queue and pauses playback — an audible micro-gap at
+the start of each sentence.

 Two gotchas when writing the command:

 - The flags are **dotted keys into the pydantic config**, so they go *without* a
  `stages.` prefix — `--vocoder.factory.stream_followup_stride`, not
  `--stages.vocoder.factory.stream_followup_stride` (the latter is rejected).
- The ramp tuple must be passed as a **JSON string** — `"[10,12,16]"` — because
+- The ramp tuple must be passed as a **JSON string** — `"[8,8,8]"` — because
  the config manager parses non-scalar paths with JSON.

-Smaller stride = finer delivery granularity but more compute: each window
-re-decodes `stream_overlap_tokens` (default `32`) of context, so `stride 16`
-decodes 48 frames per 16 emitted. Keep the stride at or below the client's
-`TTS_PREBUFFER_MS` budget (see *Mixer & jitter buffering*) — with the defaults
-above, `TTS_PREBUFFER_MS=450` starts playback on the first window.
+##### De-emphasis — reducing Drama 3's recitative register
+
+Drama 3 tends to over-articulate: an LLM reply can come back with a theatrical,
+radio-drama cadence rather than a conversational tone. The engine applies two
+configurable mitigations, both in [`src/tts/fish_audio.rs`](src/tts/fish_audio.rs):
+
+1. **Sampling knobs** — `temperature` / `top_p` / `top_k` are sent in the
+   `/v1/audio/speech` payload (`TTS_TEMPERATURE` default `0.45`, `TTS_TOP_P`
+   default `0.75`). Exaggerated intonations live in the tails of the acoustic
+   token distribution, so trimming them flattens the delivery. Lowering
+   `temperature` toward `0.3` flattens it further; `0.8+` makes it unstable and
+   theatrical again. An empty value omits the field (server default). Note that
+   this server **rejects `repetition_penalty`** with anything other than `1.0`,
+   so that knob cannot be used.
+2. **Neutral style tag** — `TTS_STYLE_TAG` (default `[conversational, casual]`)
+   is prepended to every request whose text does not already start with a `[...]`
+   tag. LLM replies carry no tag (the system prompt forbids stage directions), so
+   they get this register; the filler/backchannel banks carry their own tags and
+   are left untouched. Empty disables the prefix. Quote the value in `.env`, as
+   it contains a space.
+
+> **`.env` parsing note.** The file is read with `dotenvy`, which **fails on
+> unquoted values containing spaces** — and a single bad line makes it discard the
+> *entire* file (the process then silently falls back to built-in defaults: no
+> LLM, plain HTTP). Always quote values that contain spaces, e.g.
+> `TTS_STYLE_TAG="[conversational, casual]"`.
+
+The remaining lever — replacing the voice-cloning reference with a more
+conversational one — is not applied here: the default `solis.wav` is a
+"locutor profesional" reading, whose prosody is part of the recitative tone.

 #### `kokoro` — Kokoro TTS *(stub)*

@@ -494,27 +605,60 @@ All VAD logs live under the `audio_agent_engine::vad` target;

 ## Startup clip bootstrap

-The filler and backchannel banks are plain `*.raw` PCM files. At startup
-[`assets::ensure_clips`](src/assets.rs) checks each expected clip and, **if a
-clip is missing, synthesizes it with the configured TTS engine** and writes it
-to disk (the directory is created if needed). Existing clips are never
-overwritten, so a fresh checkout works without a manual generation step and a
-partial/customized bank is left untouched.
+The filler, start-filler and backchannel banks are plain `*.raw` PCM files
+(16-bit LE mono PCM at 44.1 kHz). At startup the clip banks are bootstrapped with
+the configured TTS engine and the files are written to disk (the directory is
+created if needed), so a fresh checkout works without a manual generation step.
+Every bank lives in a per-language subdirectory `<dir>/<lang>` (see
+[Multilingual clip banks](#multilingual-clip-banks)); the startup bootstrap
+targets the `LANG_DEFAULT` subdirectory (e.g. `assets/fillers/es/`).

- Defaults live in [`assets::FILLER_CLIPS`](src/assets.rs) (7 clips: `uhm`,
-  `eh`, `mmm`, `aver`, `bueno`, `pues`, `vaya`) and
-  [`assets::BACKCHANNEL_CLIPS`](src/assets.rs) (4 clips: `mmhmm`, `aja`, `claro`,
-  `yaveo`). The generated voice matches the configured TTS voice-cloning
-  reference.
- Backchannel clips are only generated when `BACKCHANNEL_ENABLED=true`.
+- Filler uses [`assets::ensure_clips`](src/assets.rs): each expected clip is
+  checked and **synthesized only if missing**, so an existing bank is left
+  untouched. Defaults live in [`assets::FILLER_CLIPS`](src/assets.rs) (7 clips:
+  `uhm`, `eh`, `mmm`, `aver`, `bueno`, `pues`, `vaya`). The generated voice
+  matches the configured TTS voice-cloning reference.
+- The **start filler** and the **backchannel** use the generic
+  [`assets::ensure_text_bank_clips`](src/assets.rs) (through
+  [`ensure_start_filler_clips`](src/assets.rs) / [`ensure_backchannel_clips`](src/assets.rs)):
+  both are driven by their phrase list (`START_FILLER_TEXTS` /
+  `BACKCHANNEL_TEXTS`) instead of a fixed clip set, so editing the list from
+  `.env` is enough to change what is spoken. The list the current clips were made
+  from is recorded in `<dir>/texts.txt`; when it is unchanged and every clip is
+  still on disk the synthesis is **skipped** (startup stays at ~2 s). Editing,
+  adding or dropping a phrase — or deleting a clip — triggers a **full refresh**
+  at the next restart, and clips left over from a previous list are removed.
+  Clips are named by position (`sf01`, `sf02`, … for the start filler; `bc01`,
+  `bc02`, … for the backchannel) and generated a few at a time
+  (`TEXT_BANK_CONCURRENCY`); a failed synthesis keeps the previous clip of that
+  position, and the index is only written once every clip succeeded, so a partial
+  failure is retried next time.
+- Backchannel clips are only generated when `BACKCHANNEL_ENABLED=true`; its
+  default phrase list lives in
+  [`DEFAULT_BACKCHANNEL_TEXTS`](src/orchestrator/backchannel.rs).
 - Generation is best-effort: if the TTS backend is unreachable each clip logs a
  warning and the server still starts (that bank simply stays silent).

 ```text
-INFO audio_agent_engine::assets: generating missing clips at startup label="filler" dir=assets/fillers missing=7 engine="fish-audio"
-INFO audio_agent_engine::assets: generated clip label="filler" name="uhm" samples=32768 path=assets/fillers/uhm.raw
+INFO audio_agent_engine::assets: generating clips at startup label="filler" dir=assets/fillers/es clips=7 engine="fish-audio"
+INFO audio_agent_engine::assets: generated clip label="filler" name="uhm" samples=32768 path=assets/fillers/es/uhm.raw
 ...
-INFO audio_agent_engine: clip banks bootstrapped generated=11
+INFO audio_agent_engine::assets: refreshing backchannel clips at startup label="backchannel" dir=assets/backchannel/es clips=8 engine="fish-audio"
+INFO audio_agent_engine::assets: generated backchannel clip label="backchannel" name="bc01" samples=28672 path=assets/backchannel/es/bc01.raw
+...
+INFO audio_agent_engine::assets: removed stale backchannel clip label="backchannel" path=assets/backchannel/es/mmhmm.raw
+INFO audio_agent_engine::assets: refreshing start-filler clips at startup label="start-filler" dir=assets/start_filler/es clips=22 engine="fish-audio"
+INFO audio_agent_engine::assets: generated start-filler clip label="start-filler" name="sf01" samples=36864 path=assets/start_filler/es/sf01.raw
+...
+INFO audio_agent_engine::assets: removed stale start-filler clip label="start-filler" path=assets/start_filler/es/start_filler.raw
+INFO audio_agent_engine: clip banks bootstrapped generated=30
+```
+
+On a later startup with unchanged lists:
+
+```text
+INFO audio_agent_engine::assets: backchannel clips up to date — skipping synthesis label="backchannel" dir=assets/backchannel/es clips=8
+INFO audio_agent_engine::assets: start-filler clips up to date — skipping synthesis label="start-filler" dir=assets/start_filler/es clips=22
 ```

 ---
@@ -546,25 +690,73 @@ PCM at 44.1 kHz** — selected **round-robin** (`TurnManager::next_filler` →
 different fillers. With a single clip the behaviour is unchanged. Missing clips
 are synthesized at startup ([Startup clip bootstrap](#startup-clip-bootstrap)).

+### Start filler (turn-start acknowledgment when the reply is late)
+
+A second latency mask, on its own mixer channel. It works exactly like the filler
+above, but with its own — shorter — delay
+([`TurnManager::schedule_start_filler`](src/orchestrator/turn_manager.rs)):
+`START_FILLER_GO_DELAY` (default **1200 ms**) after the turn is dispatched, if the
+first audio chunk of the reply has **not** reached the mixer yet
+(`AudioMixer::tts_audio_arrived` is still `false`) the cue is queued; if audio
+arrived within that window, the cue is dropped instead of talking over the
+beginning of the answer.
+
+The gate is latched on chunk *arrival* (at the moment anything is pushed on the
+TTS queue, checked on the 20 ms ticker), not on playback start: unlike
+`tts_playback_started`, which only flips once the `TTS_PREBUFFER_MS` jitter buffer
+is full, it does not wait out the pre-buffer. With the reference deployment the
+first chunk lands ~`0.7`–`1.0 s` after the dispatch while playback starts
+~`1.9 s` later, so gating on playback made the cue fire on every turn; gating on
+arrival lets a reply that produces audio within `START_FILLER_GO_DELAY` suppress
+it. A pending cue is also dropped on barge-in / new turn via the turn's
+`CancellationToken`. This means a fast reply is never preceded by an
+acknowledgment — only a late one is masked.
+
+It lives on its own mixer channel (`start_filler_queue`), so it plays
+independently of the round-robin latency filler above, but it shares the filler
+gain, so it ducks to `FILLER_GAIN_DUCK` once the reply starts. Disabled by
+`START_FILLER_ENABLED=false`.
+
+Its clips live in `START_FILLER_DIR` (default `assets/start_filler`) and are
+**not** part of the round-robin `FILLERS_DIR` bank. One clip is synthesized per
+phrase of `START_FILLER_TEXTS` (default `"[calm] Un momento..."`) with the
+configured voice, and [`FillerBank::random`](src/orchestrator/turn_manager.rs)
+picks one **uniformly at random**, so the acknowledgment varies instead of
+repeating the same sentence. Editing the phrase list re-synthesizes the bank at
+the next restart (see
+[Startup clip bootstrap](#startup-clip-bootstrap)); a failed synthesis leaves the
+previous clip in place.
+
+```text
+START_FILLER_TEXTS="[calm] Un momento...
+[thoughtful] A ver, veamos...
+[sigh] Vale, ya voy..."
+```
+
 ---

 ## Backchannel — during-utterance acknowledgments

 A **backchannel** is a short acknowledgment ("mm-hmm", "ajá", "claro") played
 *while the user is still speaking*, at a low gain, to signal that the agent is
-listening — without taking the turn. It is distinct from the **filler** — the
-instant acknowledgment injected at end-of-utterance by the
-[`TurnManager`](src/orchestrator/turn_manager.rs) from `FILLERS_DIR` (played
-round-robin; see [Fillers](#fillers--end-of-utterance-acknowledgments)).
+listening — without taking the turn. It is distinct from the **filler** and the
+**start filler** injected around end-of-utterance by the
+[`TurnManager`](src/orchestrator/turn_manager.rs) (delayed mask from
+`FILLERS_DIR` played round-robin, and a shorter-delay cue from `START_FILLER_DIR`;
+see [Fillers](#fillers--end-of-utterance-acknowledgments)).

 It is implemented in [`src/orchestrator/backchannel.rs`](src/orchestrator/backchannel.rs).

 ### Clips

-`BACKCHANNEL_DIR` (default `assets/backchannel`) holds `*.raw` clips — **16-bit
-LE mono PCM at 44.1 kHz** — played round-robin. The bundled set is synthesized
-with the same cloned voice as the TTS (`mmhmm`, `aja`, `claro`, `yaveo`). The
-clips are loaded once at startup into a
+`BACKCHANNEL_DIR` (default `assets/backchannel`) holds the generated `*.raw`
+clips — **16-bit LE mono PCM at 44.1 kHz** — one per phrase of
+`BACKCHANNEL_TEXTS`, named by position (`bc01`, `bc02`, …). Each phrase may carry
+an optional `category::` prefix; clips keep the list order, so the i-th clip
+inherits the i-th phrase's category. The default list
+([`DEFAULT_BACKCHANNEL_TEXTS`](src/orchestrator/backchannel.rs), Spanish with
+Drama-3 tags) is synthesized with the same cloned voice as the TTS. The clips are
+loaded once at startup into a
 [`FillerBank`](src/orchestrator/turn_manager.rs) and shared across sessions.
 Missing clips are synthesized at startup
 ([Startup clip bootstrap](#startup-clip-bootstrap)).
@@ -575,18 +767,46 @@ Missing clips are synthesized at startup

 | Signal | Action |
 |---|---|
-| `VadEvent::SpeechStart` | begin a turn (`on_speech_start`) |
+| `VadEvent::SpeechStart` | begin a turn (`on_speech_start`, randomizes the first-cue instant) |
 | `VadEvent::SpeechEnd` | close the turn, reset counters (`on_speech_end`) |
-| every frame while speaking | `maybe_emit()` attempts a cue |
+| every frame while speaking | `maybe_emit(pause_ms)` attempts a cue |

 `maybe_emit()` emits a clip **only when all** of the following hold:

 - `BACKCHANNEL_ENABLED=true` and the clip bank is non-empty;
- the user has been speaking for at least `BACKCHANNEL_MIN_SPEECH_MS`;
- at least `BACKCHANNEL_INTERVAL_MS` elapsed since the previous cue;
- fewer than `BACKCHANNEL_MAX_PER_TURN` cues were emitted this turn;
 - the agent is **not** speaking (`!TurnManager::is_speaking()`) — cuing over the
-  agent's own TTS would be an interruption, not a backchannel.
+  agent's own TTS would be an interruption, not a backchannel (checked by the
+  caller);
+- the user is in a **micro-pause**: `VadDetector::silence_ms()` reached the
+  per-pause reaction depth, a random value drawn in `[BACKCHANNEL_PAUSE_MIN_MS,
+  BACKCHANNEL_PAUSE_MAX_MS]`, so the cue never lands mid-word *and* doesn't
+  always react at the same depth. A zero-length pause (voice ongoing) re-arms
+  the gate;
+- the first cue is due (a per-turn randomized instant,
+  `BACKCHANNEL_MIN_SPEECH_MS + 0..BACKCHANNEL_JITTER_MS` after the speech start);
+- a randomized `BACKCHANNEL_INTERVAL_MS ± JITTER/2` gap elapsed since the
+  previous cue;
+- fewer than `BACKCHANNEL_MAX_PER_TURN` cues were emitted this turn;
+- the **probabilistic gate** (`BACKCHANNEL_PROB`) does not skip this pause — so
+  the agent acknowledges some pauses but not all.
+
+### Naturalness
+
+Six mechanisms keep the cues from sounding like a metronome:
+
+| Mechanism | How |
+|---|---|
+| Cue on micro-pauses | gated on the VAD `silence_ms()` (a `PAUSE_MIN..PAUSE_MAX` window, 32 ms steps, capped below `VAD_MIN_SILENCE_MS`), not on a timer |
+| Randomized reaction depth | per pause, the depth to react at is drawn at random in `[PAUSE_MIN, PAUSE_MAX]`, so the cue doesn't always land at exactly `PAUSE_MIN` |
+| Randomized timing | the first cue and every following gap are jittered by `BACKCHANNEL_JITTER_MS` |
+| Probabilistic gate | `BACKCHANNEL_PROB` skips a share of the qualifying pauses |
+| Anti-repetition | the last two clip names are excluded from the pick, across turns |
+| Volume drift | each cue is scaled by a random ±`BACKCHANNEL_VOLUME_JITTER` factor |
+
+The phrase list is further grouped in **categories**: the scheduler prefers a
+category other than the previous cue's, then a category not yet used this turn,
+so a turn tends to start with an acknowledgment (`ack`) and drift toward
+agreement (`agree`) instead of repeating the same kind of nod.

 ### Mixing

@@ -594,13 +814,90 @@ The cue is pushed into the mixer's dedicated `backchannel_queue` and summed at a
 fixed low gain (`BACKCHANNEL_GAIN`, default `0.35`):

 ```text
-mixed = tts + (filler × filler_gain) + (backchannel × BACKCHANNEL_GAIN)
+mixed = tts + ((filler + start_filler) × filler_gain) + (backchannel × BACKCHANNEL_GAIN)
 ```

 The queue is included in `AudioMixer::flush()`, so a barge-in clears any pending
-cue along with the TTS and filler audio. Logs live under the
-`audio_agent_engine::orchestrator::backchannel` target (`INFO` when a cue is
-emitted).
+cue along with the TTS and filler audio. At session start the effective policy is
+logged under `audio_agent_engine::orchestrator::backchannel`
+(`backchannel scheduler ready …`, with the parsed categories), and every emitted
+cue is logged under `audio_agent_engine::ws::session`
+(`backchannel emitted during user speech`, with the clip name and the pause
+length).
+
+---
+
+## Multilingual clip banks
+
+The filler, start-filler and backchannel banks are pre-synthesized in a single
+language — the base language `LANG_DEFAULT` (default `es`). When the user is
+detected speaking a different language, the engine generates that language's
+banks on demand and switches the session to them, **without touching** the clips
+of any other language.
+
+### Layout
+
+Every language — **including the base `LANG_DEFAULT`** — lives in its own
+subdirectory named after its ISO 639-1 code under `FILLERS_DIR` /
+`START_FILLER_DIR` / `BACKCHANNEL_DIR`:
+
+```text
+assets/backchannel/es/     <- base language (LANG_DEFAULT), pre-synthesized
+assets/fillers/es/
+assets/start_filler/es/
+assets/backchannel/en/     <- English, generated on demand
+assets/backchannel/it/     <- Italian, generated on demand
+assets/fillers/en/
+assets/start_filler/en/
+```
+
+Because the refresh pass (`remove_stale_clips`) only prunes `*.raw` files inside
+the directory it is given, scoping each language — base included — to its own
+subdirectory is what guarantees a regeneration never deletes another language's
+clips. No language is special-cased to the top level.
+
+### Phrase source
+
+Phrases come from built-in tables (Spanish, English, Italian, French, German and
+Portuguese) in [`src/lang.rs`](src/lang.rs) — one table for the backchannel, one
+for the end-of-turn filler and one for the start filler; for any other language
+they are generated with the LLM (`LANG_LLM_FALLBACK_ENABLED=true`). Each
+language's list is then synthesized through the same
+[`ensure_text_bank_clips`](src/assets.rs) pipeline used at startup, so an
+already-generated language is only reloaded (its `texts.txt` index matches) and
+never re-synthesized.
+
+### Detection & switching
+
+- A dedicated, short LLM call returns only the ISO 639-1 code
+  ([`lang::detect_language`](src/lang.rs)); it runs on the first user turn and
+  then once every `LANG_REDETECT_EVERY` turns (default `5`), so a
+  mid-conversation switch is picked up without paying for a detection call on
+  every turn.
+- Detection only runs when `LANG_DETECT_ENABLED=true`, the LLM is present, at
+  least one language-aware cue (backchannel / filler / start filler) is enabled
+  and the transcript is at least `LANG_MIN_CHARS` long (shorter samples are too
+  noisy to classify).
+- If the detected code equals the base language the session falls back to the
+  startup banks; otherwise the language's clips are ensured/loaded into a new
+  bank and the session switches to it.
+- The active language is shared between the consumers through an
+  `Arc<LanguageState>` ([`src/lang.rs`](src/lang.rs)): the end-of-turn and start
+  fillers ([`TurnManager`](src/orchestrator/turn_manager.rs)) read the active
+  bank per turn, while the backchannel scheduler is re-pointed via
+  [`BackchannelScheduler::retarget`](src/orchestrator/backchannel.rs) whenever
+  the language generation counter changes. Detection runs in the background, so
+  it never blocks the reply — it takes effect from the following turn.
+
+### Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LANG_DEFAULT` | `es` | Language of the startup filler / start-filler / backchannel banks (each in its own `<dir>/<lang>` subdirectory) |
+| `LANG_DETECT_ENABLED` | `true` | Master switch for LLM language detection |
+| `LANG_MIN_CHARS` | `12` | Minimum transcript length before detecting |
+| `LANG_REDETECT_EVERY` | `5` | Re-check the language every N user turns |
+| `LANG_LLM_FALLBACK_ENABLED` | `true` | Generate phrases via LLM for languages absent from the tables |

 ---

@@ -645,8 +942,9 @@ chat box  ──────────────┘
  the **first** chunk is cut once `LLM_STREAM_FIRST_CHUNK_CHARS` (default `20`)
  characters are buffered — so the agent starts speaking on the first few words
  instead of waiting for a whole sentence — and every following chunk at
-  `LLM_STREAM_CHUNK_CHARS` (default `120`). Set either to `0` to disable that
-  flush (chunks then end on sentence punctuation only).
+  `LLM_STREAM_CHUNK_CHARS` (default `240`). Set either to `0` to disable that
+  flush (chunks then end on sentence punctuation only). Larger follow-up chunks
+  mean fewer TTS requests, hence fewer chunk seams to starve the queue.
 - **Pipelined synthesis** — chunks are *not* synthesized one after another. Each
  chunk is requested as soon as the LLM produces it (up to `TTS_PIPELINE_DEPTH`,
  default `3`, in flight at once) and streams into its own staging buffer; a
@@ -666,6 +964,145 @@ chat box  ──────────────┘

 ---

+## Tool calling
+
+With `LLM_TOOLS_FILE` pointing at a JSON file, the model can call external HTTP
+services before answering. Tools are plain descriptions of an HTTP request, so
+any service (weather API, webhook, home automation, internal REST endpoint) can
+be exposed without touching the code:
+
+```json
+[
+  {
+    "name": "get_weather",
+    "description": "Current weather and temperature for a city.",
+    "parameters": {
+      "type": "object",
+      "properties": { "city": { "type": "string" } },
+      "required": ["city"]
+    },
+    "url": "https://wttr.in/{city}?format=3",
+    "method": "GET",
+    "headers": { "X-Api-Key": "…" }
+  }
+]
+```
+
+- `url` may contain `{arg}` placeholders substituted from the call arguments.
+- `GET` sends the arguments that were **not** consumed by a placeholder as query
+  parameters; `POST` (the default) sends them as a JSON body.
+- `headers` are optional and sent verbatim (API keys, etc.).
+
+See [`tools.example.json`](tools.example.json) for a ready-to-use file.
+
+### Why a client-side parser
+
+The deployment's OpenAI-compatible server (vLLM) runs **without** a tool parser
+(`--enable-auto-tool-choice --tool-call-parser …`), so it never returns
+structured `tool_calls` or `finish_reason: "tool_calls"`. The tools are still
+advertised in every request (`tools` + `tool_choice: "auto"`), so the Qwen model
+knows about them and emits the call **as text** in its native format:
+
+```text
+<tool_call>
+<function=get_weather>
+<parameter=city>
+Paris
+</parameter>
+</function>
+</tool_call>
+```
+
+[`src/tools.rs`](src/tools.rs) parses that format client-side and works with any
+server, no server-side reconfiguration needed.
+
+### Turn loop
+
+Each turn runs a bounded loop (`LLM_TOOL_MAX_ITERATIONS`, default `4`):
+
+1. Stream one reply. A `ToolCallStripper` removes `<tool_call>` blocks from the
+   streamed text — a block that is still incomplete is **held back**, so it is
+   never spoken by the TTS nor shown in the chat box even when split across
+   deltas. The visible text is spoken as usual, so the assistant can say
+   something short ("Let me check…") before calling.
+2. If the round produced no tool call, the turn ends.
+3. Otherwise the assistant message (with its native call) plus one `tool` role
+   message per result are appended, and the loop re-prompts the model, which can
+   then answer using the results.
+
+Tool errors (unknown tool, transport failure, non-2xx status) are returned to
+the model as text, so it can recover and still produce an answer; the turn never
+fails because of a tool. Only the *spoken* text is written to the rolling
+history — the tool exchange stays local to the turn.
+
+The `tool_call` event is also forwarded to the client for observability:
+
+```json
+{ "type": "tool_call", "name": "get_weather", "arguments": { "city": "Paris" } }
+```
+
+---
+
+## External audio injection
+
+The mixer has a dedicated **external channel** (`external_queue`) that plays an
+audio source injected from the client — a direct audio URL, an Icecast/Shoutcast
+radio stream, an HLS playlist, or a YouTube link — mixed together with the
+agent's voice. It is implemented by [`src/media.rs`](src/media.rs)
+(`MediaSource`) and driven over the WebSocket by the `audio_source` message
+(see [WebSocket Protocol](#websocket-protocol)). The Mivocero client exposes it
+in its footer bar.
+
+### Why `ffmpeg` / `yt-dlp`
+
+The channel does not decode audio itself: it spawns an external decoder process
+whose raw PCM output feeds the ring buffer.
+
+- **`ffmpeg`** (URL / radio / HLS) — reads the source and writes
+  `-f s16le -acodec pcm_s16le -ac 1 -ar 44100 pipe:1`, i.e. exactly the mixer's
+  format (44.1 kHz, 16-bit LE, mono). URL inputs use `-reconnect 1
+  -reconnect_streamed 1 -reconnect_delay_max 5` so a dropped radio connection is
+  retried instead of ending the stream.
+- **`yt-dlp`** (YouTube) — used only to *resolve* a YouTube page to a direct
+  media URL (`-f bestaudio/best -g --no-playlist`); that URL is then handed to
+  `ffmpeg`. YouTube-specific cookies/extractor tweaks go in `MEDIA_YTDLP_ARGS`
+  (e.g. `--cookies /path/cookies.txt` if the media server asks to "confirm
+  you're not a bot").
+
+Both binaries are configurable (`MEDIA_FFMPEG_BIN`, `MEDIA_YTDLP_BIN`) and are
+only required when the external channel is actually used.
+
+### Backpressure
+
+A live radio always produces audio at real time, but a bounded VOD source (a
+YouTube video, a file) decodes far faster than real time. The decode task
+respects the channel's `remaining_capacity()` and sleeps 20 ms whenever the
+queue is full, so a fast source is throttled to the mixer's drain rate instead
+of overflowing the ring buffer (which would drop the oldest samples).
+
+### Independence from the agent
+
+The external channel is deliberately **not** cleared by `AudioMixer::flush()`:
+a barge-in stops the *agent* (TTS + fillers), not the background music. It also
+does not count towards `AudioMixer::is_active()` — the agent is not considered
+to be "speaking" because the music is playing. Its volume is a runtime atomic
+(`AudioMixer::set_external_gain`) so the client slider takes effect on the next
+mixed frame.
+
+### Lifecycle
+
+| Step | What happens |
+|---|---|
+| `play` | Any current source is stopped; state `loading` is emitted. For a YouTube URL `yt-dlp` resolves the direct URL first. |
+| ready | `ffmpeg` is spawned and reading begins; state `playing` is emitted. |
+| streaming | Decoded PCM is pushed into `external_queue` under backpressure. |
+| `stop` / new `play` / disconnect | The `CancellationToken` is cancelled and the child processes are killed (`kill_on_drop(true)`); `stopped` (or `error`) is emitted. |
+
+A monotonic generation counter guards against a stale task clearing the state of
+a newer source.
+
+---
+
 ## Mivocero chat client

 A ready-to-use speech-to-speech example client is served at **`/mivocero`**
@@ -685,12 +1122,77 @@ A ready-to-use speech-to-speech example client is served at **`/mivocero`**
  without using the microphone (`{"type":"user_text","text":…}`).
 - **Interrupt button** — flushes audio and cancels the in-flight reply
  (`{"type":"interrupt"}`).
+- **External audio bar** — footer controls to inject a background source by URL
+  (direct audio / radio / YouTube), with **Play** / **Stop** buttons, a volume
+  slider (0–150 %, sent as `EXTERNAL_AUDIO_GAIN` × slider) and a live state
+  label driven by the server's `audio_source` events. Demonstrates the
+  [external audio channel](#external-audio-injection).
+- **Cue indicators** — a row of three tiles (**Filler**, **Start filler**,
+  **Backchannel**) that flash and bump a session counter each time the server
+  emits the matching cue, driven by the `{"type":"cue"}` events. The detail line
+  shows the backchannel category (or the clip name), so the emission cadence of
+  the latency masks is visible live. Counters reset on each connect.
+- **Cue methods panel** — a collapsible **Cue methods** section below the tiles
+  that documents the method used by each cue (when it fires, how a clip is
+  chosen) and shows the **live parameters** reported by the server in the
+  `{"type":"cues"}` event sent at session start: filler delay / gains / clip
+  count, start-filler go-delay, and the backchannel gain, min-speech, interval,
+  jitter, pause window, probability, volume jitter, per-turn cap and categories
+  — all read from the effective runtime configuration (no hard-coded values).
+- **Idle auto-disconnect** — the session closes itself after **2 minutes**
+  (`IDLE_TIMEOUT_MS`) without any traffic in either direction. The timer is
+  reset by every server event *and* audio frame received, and by every user
+  action sent (typed message, Stop, media controls) — so an ongoing reply or a
+  playing external source counts as activity. On expiry the WebSocket is closed,
+  the microphone is released, an explanatory message is appended to the chat and
+  the **Connect** button becomes available again.

 Open `http://localhost:8787/mivocero` (or `https://…` for remote microphone
 access — see [HTTPS](#https-microphone-access)).

 ---

+## Session audit log
+
+Every WebSocket session can be recorded to its own structured **JSONL** file —
+one JSON object per line — under `SESSION_AUDIT_DIR` (default `logs/sessions`),
+named `s-<epoch_ms>-<seq>.jsonl`. It is meant for post-mortem analysis and for
+tuning the latency knobs (why a filler fired, when a cue landed, how long the
+first audio took).
+
+Each record carries a wall-clock timestamp, the elapsed time since the session
+started, an event discriminator and a payload:
+
+```json
+{"ts":1729170000000,"elapsed_ms":12,"event":"session_start","data":{"config":{…},"runtime":{…}}}
+{"ts":1729170000123,"elapsed_ms":135,"event":"control","data":{"type":"user_text","text":"…"}}
+{"ts":1729170000456,"elapsed_ms":468,"event":"out","data":{"type":"assistant_delta","text":"Hola,"}}
+{"ts":1729170000500,"elapsed_ms":512,"event":"out","data":{"type":"cue","kind":"start_filler","name":"sf02"}}
+{"ts":1729170009000,"elapsed_ms":9012,"event":"session_end","data":{"reason":"client_disconnected","counts":{…}}}
+```
+
+| `event` | When | `data` |
+|---|---|---|
+| `session_start` | Session opens | `config` — the full non-secret configuration snapshot; `runtime` — which of STT / VAD / tokenizer / LLM are actually active (plus the LLM model). |
+| `control` | `user_text` control message received | The text turn. |
+| `out` | **Every** event sent to the client | The exact WS payload — `user`, `assistant_delta`, `assistant_end`, `tool_call`, `cue`, `error`, `audio_source` state, … Recorded at the single sender tap, so nothing sent to the browser is missed. |
+| `interrupt` | Client barge-in (`interrupt` JSON or legacy `INTERRUPT`) | `source` (`client` / `client_legacy`). |
+| `barge_in` | VAD-driven barge-in | `prob` (onset speech probability). |
+| `vad_speech_start` / `vad_speech_end` | Utterance boundaries | `prob`; `duration_ms`, `avg_prob`. |
+| `media` | External audio control | `action` (`play`/`stop`/`volume`) with `url` / `gain`. |
+| `reference` | Voice-cloning reference change | `action` (`set`/`clear`) and the audio path. |
+| `speak` | Direct TTS request (playground / fallback text) | `text`. |
+| `language_switch` | Detected language changed | `from`, `to`, `generated` (whether clip banks were synthesized). |
+| `error` | Transport / receiver error | `where`, `text`. |
+| `session_end` | Session closes | `reason`, `duration_ms`, `session_id`, `file`, `counts` (per-event totals). |
+
+The sink is **best-effort**: if the file cannot be opened, or a write fails, the
+session runs unchanged (the failure is logged once in the tracing output and the
+sink then goes quiet). Files are appended and flushed after every record, so the
+log survives a crash or a `pm2 restart`. The directory is git-ignored.
+
+---
+
 ## WebSocket Protocol

 Connect to `ws://<host>:8787/ws`.
@@ -702,6 +1204,9 @@ Connect to `ws://<host>:8787/ws`.
 | **Binary** | Raw 16-bit LE mono PCM microphone frames (44.1 kHz). Resampled to 16 kHz server-side for STT. |
 | **Text — `{"type":"user_text","text":"…"}`** | Text turn from the chat box: runs the same LLM → TTS path as a spoken utterance (no STT). |
 | **Text — `{"type":"interrupt"}`** | Barge-in: cancel the in-flight LLM reply / TTS and flush all queued audio. |
+| **Text — `{"type":"audio_source","action":"play","url":"…"}`** | Inject an external audio source (direct URL / radio / HLS / YouTube) into the mixer's external channel, replacing any current one. |
+| **Text — `{"type":"audio_source","action":"stop"}`** | Stop the external source and clear the channel. |
+| **Text — `{"type":"audio_source","action":"volume","gain":0.6}`** | Set the external channel gain (0..1) at runtime. |
 | **Text — `INTERRUPT`** *(also `interrupt`, `BAARGEIN`, `bargein`)* | Legacy barge-in form (kept for the playground). |
 | **Text — `SET_REFERENCE:<path>\|<text>`** | Set/change the voice-cloning reference. `<text>` may be omitted to re-use the sibling `.txt`. |
 | **Text — `CLEAR_REFERENCE`** | Disable voice cloning. |
@@ -715,7 +1220,11 @@ Connect to `ws://<host>:8787/ws`.
 | **Text — `{"type":"user","text":"…"}`** | The user's turn (STT transcript or chat-box message) — rendered in the chat box. |
 | **Text — `{"type":"assistant_delta","text":"…"}`** | Streaming chunk of the assistant reply (chain-of-thought already removed). |
 | **Text — `{"type":"assistant_end"}`** | The assistant turn is complete. |
+| **Text — `{"type":"tool_call","name":"…","arguments":{…}}`** | The model called a tool; the call has been executed (result is not echoed in the chat box, only in the model's next round). Purely informational. |
 | **Text — `{"type":"error","text":"…"}`** | LLM request failed; the turn was aborted. |
+| **Text — `{"type":"audio_source","state":"…","url":"…"}`** | External audio channel state change: `loading` (decoding is being set up / YouTube URL resolving), `playing` (PCM is streaming), `stopped`, or `error` (with a `text` message). |
+| **Text — `{"type":"cue","kind":"…","name":"…","category":"…"}`** | A latency-mask / backchannel cue was actually emitted into the mixer: `kind` is `filler` (end-of-turn), `start_filler` (turn start) or `backchannel` (during user speech); `name` is the clip name and `category` (backchannel only) its category. Fired only when the cue really plays — a skipped cue sends nothing. Drives the demo's cue indicators. |
+| **Text — `{"type":"cues","lang":"…","config":{…}}`** | Sent once at session start: the effective policy of the three cues for the active language — the filler parameters (`delay_ms`, gains, clip count), the start-filler `go_delay_ms` and the full backchannel configuration (gain, min-speech, interval, jitter, pause window, probability, volume jitter, per-turn cap, categories). Purely informational; drives the demo's **Cue methods** panel so it shows the live values instead of hard-coded ones. |

 ---

@@ -736,23 +1245,32 @@ Constants are defined in [`src/config.rs`](src/config.rs):
 ### Mixer & jitter buffering ([`src/audio/mixer.rs`](src/audio/mixer.rs))

 - Mixing formula:
-  `mixed = tts + (filler × filler_gain) + (backchannel × BACKCHANNEL_GAIN)`.
+  `mixed = tts + ((filler + start_filler) × filler_gain) + (backchannel × BACKCHANNEL_GAIN) + (external × external_gain)`.
  The filler gain is `1.0` when TTS is idle, else `filler_gain_duck` (default
  `0.15`); the backchannel gain is fixed (`BACKCHANNEL_GAIN`, default `0.35`).
-  Output is clamped to `i16`.
+  The start-filler channel is summed with the filler, so it shares the same gain.
+  The external channel gain starts at `EXTERNAL_AUDIO_GAIN` (default `0.6`) and
+  is adjustable at runtime (`AudioMixer::set_external_gain`). Output is clamped
+  to `i16`.
 - **Pre-buffer:** TTS playback does not start until the queue holds
-  ≥ `TTS_PREBUFFER_MS` (default **450 ms**) of synthesized audio. It absorbs
+  ≥ `TTS_PREBUFFER_MS` (default **550 ms**) of synthesized audio. It absorbs
  uneven TTS chunk arrival; lower it to start speaking sooner, raise it for fewer
-  drop-outs. With pipelined synthesis (above) the pre-buffer only has to cover
-  arrival jitter, not the TTS engine's per-request start-up, so it can stay
-  small. Note: Drama-3 delivers ~1.04× real time, and its *granularity* is set by
-  the server's vocoder window
-  (`--vocoder.factory.stream_followup_stride`, in codec frames of 2048 samples =
-  46.4 ms). With stride `16` and ramp `"[10,12,16]"` the first window is 10
-  frames = 0.464 s, so `450 ms` starts playback on that very first window (the
-  steady state then delivers a 0.743 s burst every ~0.69 s). With the upstream
-  default (`64`, a 2.97 s burst every ~2.7 s) gapless playback would instead
-  require a ~3 s pre-buffer.
+  drop-outs. Note: Drama-3's *granularity* is set by the server's vocoder window
+  (`--vocoder.factory.stream_stride` / `stream_followup_stride`, in codec frames
+  of 2048 samples = 46.4 ms). With the deployment used here (stride `4`, followup
+  `8`, overlap `16`) the first window is 4 frames = 0.186 s and the steady windows
+  are 8 frames = 0.372 s, delivered ~0.35 s apart (the server runs at ~0.95× real
+  time). Because `TTFA ≈ TTFB + (prebuffer − window)`, any pre-buffer in
+  `(186, 557]` ms primes on the **same** second window → TTFA ≈ `0.73 s`; the
+  default `550 ms` takes that whole cushion at no extra latency. A pre-buffer
+  below ~`186 ms` starts playback on the first window (TTFA ≈ `0.38 s`) but leaves
+  almost no margin: under concurrent TTS requests one GPU serves several requests
+  and the per-request throughput dips below real time (~`1.5×` vs ~`0.94×` alone),
+  so every chunk seam starves the queue and pauses playback → an audible
+  micro-gap at the start of each sentence. With the upstream default (`64`, a
+  2.97 s burst every ~2.7 s) gapless playback would instead require a ~3 s
+  pre-buffer; a large constant stride (`16`) both raises the TTFB (~1.2 s) and
+  bursts, and a growing ramp gaps the tail while the small early windows drain.
 - **Resilient resume:** the full pre-buffer is only required at the *first*
  playback of a reply. If the queue empties mid-reply (after the 200 ms drain
  grace) playback pauses, but resumes as soon as *any* audio is queued again —
@@ -774,13 +1292,15 @@ audio-agent-engine/
 ├── server.sh                 # start / stop / restart / status / logs / cert
 ├── certs/                    # self-signed TLS cert+key (generated)
 ├── UPDATES.md                # changelog (English, newest-first)
-├── assets/fillers/           # *.raw filler PCM (16-bit LE mono, 44.1 kHz; round-robin)
-├── assets/backchannel/       # *.raw backchannel PCM (16-bit LE mono, 44.1 kHz)
+├── tools.example.json        # tool definitions for LLM tool calling (copy/edit)
+├── assets/fillers/<lang>/    # *.raw filler PCM (16-bit LE mono, 44.1 kHz; round-robin), one dir per language
+├── assets/start_filler/<lang>/  # sf01.raw … turn-start start-filler clips + texts.txt index
+├── assets/backchannel/<lang>/   # bc01.raw … backchannel clips + texts.txt index
 ├── models/                   # Parakeet ONNX + Silero VAD + tokenizer
 └── src/
    ├── main.rs               # Axum server, routes, graceful shutdown
    ├── config.rs             # env-var config + audio constants
-    ├── assets.rs             # startup clip bootstrap (auto-generate fillers/backchannel)
+    ├── assets.rs             # startup clip bootstrap (auto-generate fillers/backchannel/start filler)
    ├── tls.rs                # optional HTTPS/WSS termination (rustls)
    ├── onnx.rs               # shared process-wide ONNX Runtime environment
    ├── audio/                # ring_buffer, mixer
@@ -791,6 +1311,9 @@ audio-agent-engine/
    ├── stt/                  # Parakeet ONNX + tokenizer + worker
    ├── vad/                  # Silero VAD v5 + onset/offset state machine
    ├── llm.rs                # OpenAI-compatible chat-completions client (streaming + think stripping)
+    ├── tools.rs              # configurable HTTP tool calling (native <tool_call> parser + executor)
+    ├── media.rs              # external audio source (URL / radio / YouTube) via ffmpeg + yt-dlp
+    ├── audit.rs              # per-session JSONL audit log (config snapshot, events, summary)
    ├── orchestrator/         # turn_manager (EOU/STT → LLM → filler → TTS) + backchannel
    ├── ws/                   # handler, session (per-connection audio loop)
    └── web/                  # embedded playground.html + mivocero.html
@@ -5,6 +5,813 @@ Entries are written in English and ordered newest-first.

 ---

+## 2026-10-17 — Cue methods panel in the Mivocero client (live cue policy)
+
+### Added
+
+- **`cues` WebSocket event** — sent once at session start by
+  `src/ws/session.rs`, it reports the **effective policy** of the three cues for
+  the active language: the filler (`delay_ms`, `gain_idle`, `gain_duck`, clip
+  count, bank dir), the start filler (`go_delay_ms`, clip count, bank dir) and
+  the backchannel (gain, min-speech, interval, jitter, pause window,
+  probability, volume jitter, per-turn cap, categories, clip count). The
+  backchannel `pause_max_ms` is capped to the VAD EOU window exactly like
+  `BackchannelScheduler::pause_max`; the bank paths are the language
+  subdirectories (`assets/fillers/<lang>`). Purely informational.
+- **Cue methods panel** in `src/web/mivocero.html` — a collapsible
+  `<details>` section under the cue tiles with one card per cue: the **method**
+  used (when it fires, how a clip is chosen) and the **live parameters** from
+  the `cues` event, so the panel always matches the running configuration
+  instead of hard-coded values.
+
+### Notes
+
+- The panel is display-only; it changes no behaviour. Values reflect the
+  process configuration at session start (env-derived), so a `.env` change is
+  visible after the next session.
+
+---
+
+## 2026-10-17 — Per-session audit log (structured JSONL)
+
+### Added
+
+- **`src/audit.rs`** — a best-effort per-session audit sink. Each WebSocket
+  session is recorded to its own JSONL file
+  (`SESSION_AUDIT_DIR/<id>.jsonl`, id `s-<epoch_ms>-<seq>`), one record per line:
+  `{"ts":…,"elapsed_ms":…,"event":…,"data":…}`. Records are flushed as they are
+  written, and any failure (directory/file creation, write) only disables the
+  sink for that session — the session itself is never affected.
+- **Event coverage (complete)**:
+  - `session_start` — full non-secret configuration snapshot plus the active
+    runtime capabilities (STT / VAD / tokenizer / LLM + model);
+  - `control` — inbound `user_text` turns;
+  - `out` — **every** event sent to the client, tapped at the single sender
+    point in `src/ws/session.rs` so nothing is missed (`user`,
+    `assistant_delta`, `assistant_end`, `tool_call`, `cue`, `error`,
+    `audio_source` state, …);
+  - `interrupt` — client barge-in (JSON or legacy text form);
+  - `barge_in` — VAD-driven barge-in (with the onset probability);
+  - `vad_speech_start` / `vad_speech_end` — utterance boundaries;
+  - `media` / `reference` / `speak` — external-audio control, voice-reference
+    changes and direct TTS requests;
+  - `language_switch` — detected language change (`from`, `to`, `generated`) —
+    `src/orchestrator/turn_manager.rs`;
+  - `error` — transport/receiver errors;
+  - `session_end` — reason, duration, session id, file and per-event counts.
+- **Config** — `SESSION_AUDIT_ENABLED` (default `true`) and
+  `SESSION_AUDIT_DIR` (default `logs/sessions`); documented in `.env`,
+  `.env.example` and the README. `logs/` is git-ignored.
+
+### Changed
+
+- `TurnManager::new` takes an `Arc<SessionAudit>` (used for the language-switch
+  record); every other event reaches the log through the sender tap.
+
+### Notes
+
+- The audit path is off the audio hot path (the sink only touches the outbound
+  text events, not the 20 ms frames) and is disabled cleanly when the LLM/VAD/…
+  are off. Intended for post-mortem analysis and for tuning the latency knobs.
+
+---
+
+## 2026-10-17 — Cue emission indicators in the Mivocero demo
+
+### Added
+
+- **`{"type":"cue"}` WebSocket event** — the server now tells the client each
+  time a latency-mask / backchannel cue is **actually emitted** into the mixer:
+  - **filler** (end-of-turn) — `src/orchestrator/turn_manager.rs`
+    (`schedule_filler`),
+  - **start_filler** (turn start) — `src/orchestrator/turn_manager.rs`
+    (`schedule_start_filler`),
+  - **backchannel** (during user speech) — `src/ws/session.rs` (mic task).
+  The payload is `{"type":"cue","kind":…,"name":…}` and, for backchannel, also
+  `"category":…`. A cue that is skipped (audio already arrived / playing, or a
+  barge-in) sends nothing.
+- **`BackchannelScheduler::maybe_emit`** now returns `(name, category)` instead
+  of just the name, so the backchannel cue carries its category.
+- **Mivocero cue indicators** — `src/web/mivocero.html` gained a row of three
+  tiles (**Filler**, **Start filler**, **Backchannel**) that flash (colour-coded
+  dot + border glow) and bump a per-session counter on every `cue` event, with a
+  detail line showing the backchannel category (or the clip name). Counters reset
+  on each connect.
+
+### Notes
+
+- Only real emissions are reported, so the panel is a faithful view of what the
+  user actually hears — useful for tuning `FILLER_DELAY_MS` /
+  `START_FILLER_GO_DELAY` and the backchannel cadence.
+
+---
+
+## 2026-10-17 — Per-language subdirectory for every clip bank (base included)
+
+### Changed
+
+- **`src/main.rs`** — the startup bootstrap now generates and loads the three
+  base banks (filler, start-filler, backchannel) from
+  `<dir>/<LANG_DEFAULT>/` via [`assets::lang_dir`](src/assets.rs) instead of the
+  top-level directory. Every language — **including the default one** — now
+  lives in its own subdirectory, so the filler, start-filler and backchannel
+  share the exact same layout for every language and no language is special-cased
+  to the top level.
+- **`src/assets.rs`** — [`lang_dir`](src/assets.rs) doc updated accordingly.
+
+### Notes
+
+- On the first start after this change the base clips are re-synthesized into
+  `assets/<bank>/<lang>/`. To avoid the re-synthesis, move the existing
+  top-level `*.raw` files (and `texts.txt`) into the matching language
+  subdirectory by hand — this was done for the `es` deployment.
+- No other language's clips are touched: the per-language subdirectory remains
+  what isolates each language's refresh (`remove_stale_clips`).
+
+---
+
+## 2026-10-17 — Multilingual clip banks (backchannel, filler & start filler)
+
+### Added
+
+- **`src/lang.rs`** — new multilingual module. It holds built-in phrase tables
+  for **backchannel** (category + phrase), **filler** (interjections) and
+  **start filler** (turn-start acknowledgments, with Drama-3 style tags) in
+  Spanish, English, Italian, French, German and Portuguese, exposes accessors
+  for them, and implements the auxiliary LLM calls: `detect_language` (returns
+  only the ISO 639-1 code, or `und`) and `generate_backchannel_texts` /
+  `generate_filler_texts` / `generate_start_filler_texts` (LLM fallback for
+  languages absent from the tables).
+  It also defines `LangBanks` (a language's loaded clip banks, including its
+  start-filler bank) and `LanguageState` (the session's active language plus a
+  generation counter, kept in a parking-lot `RwLock`).
+- **On-demand per-language generation** — when the user's language differs from
+  the active one, that language's backchannel/filler/start-filler clips are
+  synthesized into a **per-language subdirectory** (`assets/backchannel/<lang>/`,
+  `assets/fillers/<lang>/`, `assets/start_filler/<lang>/`) and the session
+  switches to them. Because the refresh pass only prunes clips inside the
+  directory it is given, **no other language's clips are ever removed**; the
+  base language keeps living in the top-level directories, so no migration is
+  needed.
+- **New env vars** — `LANG_DEFAULT` (default `es`), `LANG_DETECT_ENABLED`
+  (default `true`), `LANG_MIN_CHARS` (default `12`), `LANG_REDETECT_EVERY`
+  (default `5`) and `LANG_LLM_FALLBACK_ENABLED` (default `true`).
+
+### Changed
+
+- **`src/llm.rs`** — new `LlmClient::simple_chat` for short, non-streaming
+  auxiliary requests (explicit system + user message, **no** tools), used by the
+  language detection and phrase-generation calls.
+- **`src/config.rs`** — five new `LANG_*` fields, parsed in `from_env`.
+- **`src/assets.rs`** — `lang_dir` helper plus `ensure_lang_backchannel_clips` /
+  `ensure_lang_filler_clips` / `ensure_lang_start_filler_clips`, which scope the
+  text-bank refresh to `<base>/<lang>/` so each language is refreshed
+  independently.
+- **`src/orchestrator/backchannel.rs`** — the clip/category mapping is extracted
+  into `map_clips`, and `BackchannelScheduler::retarget` re-points a live
+  scheduler to a new bank when the language changes. `DEFAULT_CATEGORY` is now
+  `pub(crate)` so `lang.rs` can reuse it.
+- **`src/orchestrator/turn_manager.rs`** — `TurnManager` now holds an
+  `Arc<LanguageState>` instead of a single filler bank; `next_filler` and the
+  start filler read from the active language (`schedule_start_filler` picks from
+  `langs.current().start_filler`). A new `maybe_detect_language` runs on each
+  user turn (first turn + every `LANG_REDETECT_EVERY`) and spawns
+  `switch_language_if_needed`, which detects, generates/loads the target
+  language's banks (start filler optional: a missing table just leaves that cue
+  silent) and swaps the active state — in the background, so the reply is never
+  blocked.
+- **`src/ws/session.rs`** — builds the shared `LanguageState`; the mic task polls
+  the language generation counter each frame and calls `retarget` on the
+  backchannel scheduler only when it changes.
+- **`.env` / `.env.example`** — new "Multilingual clip banks" section;
+  **`README.md`** — new "Multilingual clip banks" section.
+
+### Why
+
+- The banks were pre-synthesized in a single language, so a user speaking any
+  other language heard Spanish cues — including the start filler. Generating the
+  matching language on demand keeps the acknowledgment natural in a multilingual
+  deployment, while the per-language directory layout guarantees that adding a
+  language never destroys the clips already generated for the others.
+
+### Notes
+
+- Detection needs the LLM (`LANG_DETECT_ENABLED` is a no-op without it); the LLM
+  phrase fallback is used only for languages outside the built-in tables.
+- Generating a new language's bank calls the TTS backend once per phrase, which
+  can take a few seconds on the first switch; it is idempotent (an
+  already-generated language is only reloaded).
+
+---
+
+## 2026-10-16 — Mivocero: auto-disconnect an idle session after 2 minutes
+
+### Added
+
+- **Idle guard in the Mivocero client** ([`src/web/mivocero.html`](src/web/mivocero.html)) —
+  the session closes itself after `IDLE_TIMEOUT_MS` (2 minutes) without any
+  activity. `touchActivity()` re-arms the timer and is called on every server
+  event, on every received audio frame and on every user action sent
+  (`sendJson`), so an ongoing reply or a playing external source keeps the
+  session alive. On expiry it logs the reason, appends an explanatory message to
+  the chat and calls `disconnect()`, which closes the WebSocket and releases the
+  microphone.
+
+### Changed
+
+- **Reconnect after close** — `ws.onclose` now clears the `ws` reference.
+  Without it the Connect button stayed bound to the stale socket, so a session
+  closed by the idle guard (or by any disconnect) could not be reopened without
+  reloading the page.
+
+### Why
+
+- A microphone-backed session left open keeps the device busy and the server
+  streaming silent 20 ms frames forever. An inactivity timeout releases both
+  without user action, while still allowing a long reply or a background radio
+  to run uninterrupted.
+
+### Notes
+
+- The timer counts *any* traffic in either direction: TTS audio is sent as
+  binary frames, so speaking does not trip the timeout.
+- The timeout is a client-side constant (`IDLE_TIMEOUT_MS` in the HTML); change
+  it there and rebuild (the page is embedded with `include_str!`).
+
+---
+
+## 2026-10-16 — Tool calling: configurable HTTP tools for the LLM
+
+### Added
+
+- **`src/tools.rs`** — new tool-calling module. It loads tool definitions from a
+  JSON file and provides: a `ToolRegistry` (builds the OpenAI `tools` array,
+  executes a call over HTTP), a client-side parser for the model's **native**
+  `<tool_call>` format, and a `ToolCallStripper` that removes tool-call blocks
+  from the streamed reply — holding back a block that is still incomplete, so it
+  is never spoken by the TTS nor shown in the chat box even when split across
+  deltas (same hold-back pattern as the chain-of-thought stripper).
+- **`tools.example.json`** — ready-to-use definitions: `get_weather` (GET with a
+  `{city}` URL placeholder, wttr.in) and `send_webhook` (POST with a custom
+  header), covering both request shapes.
+- **New env vars** — `LLM_TOOLS_ENABLED` (auto: on when `LLM_TOOLS_FILE` is set),
+  `LLM_TOOLS_FILE`, `LLM_TOOL_MAX_ITERATIONS` (default `4`),
+  `LLM_TOOL_TIMEOUT_SECS` (default `15`) and `LLM_TOOL_RESULT_MAX_CHARS`
+  (default `2000`).
+- **`ChatMessage::tool`** — `role: "tool"` message used to hand a tool result
+  back to the model.
+- **WebSocket protocol** — informational
+  `{"type":"tool_call","name":"…","arguments":{…}}` event emitted when the model
+  calls a tool.
+
+### Changed
+
+- **`LlmClient`** carries an optional `Arc<ToolRegistry>`
+  ([`src/llm.rs`](src/llm.rs)); when present, every request advertises
+  `tools` + `tool_choice:"auto"`, so the model knows which functions it may
+  call. The registry is built by `load_tools(config)`; a missing or invalid file
+  logs a warning and leaves tool calling disabled without breaking the pipeline.
+- **[`TurnManager::run_llm_turn`](src/orchestrator/turn_manager.rs)** now runs a
+  bounded tool loop: each round streams a reply through the `ToolCallStripper`;
+  if a call was emitted, the assistant message (with its native call) plus one
+  `tool` message per result are appended and the model is re-prompted, up to
+  `LLM_TOOL_MAX_ITERATIONS`. The TTS pipeline is created once and every round's
+  visible text flows into it, so the assistant can say something short before
+  calling. Only the spoken text is written to the rolling history.
+
+### Why
+
+- The deployment's vLLM server runs **without** a tool parser
+  (`--enable-auto-tool-choice --tool-call-parser …`), so it never returns
+  structured `tool_calls` / `finish_reason:"tool_calls"`. Tools are still
+  advertised in the request and the Qwen model emits the call as text in its
+  native format; parsing it client-side keeps the feature working with any
+  server and requires no server-side reconfiguration.
+- Tool definitions live in a JSON file rather than `.env` so the verbose JSON
+  schemas stay readable and editable.
+
+### Notes
+
+- Tool errors (unknown tool, transport failure, non-2xx status) are returned to
+  the model as text so it can recover; a tool never fails the turn.
+- `GET` sends arguments not consumed by a `{arg}` placeholder as query
+  parameters; `POST` sends them as a JSON body. `headers` are sent verbatim.
+
+---
+
+## 2026-10-16 — External audio channel: inject a URL / radio / YouTube source
+
+### Added
+
+- **`src/media.rs`** — new [`MediaSource`](src/media.rs) module implementing an
+  external audio source for a WebSocket session. A source is decoded by an
+  external process and its raw PCM is pushed into the mixer's new external ring
+  buffer. `ffmpeg` decodes direct URLs / radio / HLS
+  (`-f s16le -acodec pcm_s16le -ac 1 -ar 44100 pipe:1`, with
+  `-reconnect 1 -reconnect_streamed 1 -reconnect_delay_max 5`); YouTube links are
+  first resolved to a direct URL with `yt-dlp` (`-f bestaudio/best -g
+  --no-playlist`). Child processes are killed on stop / replacement /
+  disconnection (`kill_on_drop(true)` + `CancellationToken`), and a monotonic
+  generation counter prevents a stale task from clearing a newer source.
+- **Mixer external channel** — `AudioMixer` gains `external_queue` and a runtime
+  gain ([`src/audio/mixer.rs`](src/audio/mixer.rs)). The mixing formula becomes
+  `… + (external × external_gain)`; `set_external_gain` updates the gain (an
+  atomic, so it takes effect on the next frame without rebuilding the mixer).
+  The external queue is **not** cleared by `flush()` and does not count towards
+  `is_active()`: a barge-in stops the agent, not the background audio.
+- **New env vars** — `EXTERNAL_AUDIO_GAIN` (default `0.6`),
+  `MEDIA_FFMPEG_BIN` (default `ffmpeg`), `MEDIA_YTDLP_BIN` (default `yt-dlp`) and
+  `MEDIA_YTDLP_ARGS` (extra `yt-dlp` args, e.g. `--cookies …`).
+- **WebSocket protocol** — new `audio_source` message:
+  `{"type":"audio_source","action":"play","url":"…"}`,
+  `{"type":"audio_source","action":"stop"}` and
+  `{"type":"audio_source","action":"volume","gain":0.6}`. The server reports
+  state back with `{"type":"audio_source","state":"loading|playing|stopped|error","url":"…"}`
+  ([`src/ws/session.rs`](src/ws/session.rs)).
+- **Mivocero client** — footer bar with a URL input, **Play** / **Stop**
+  buttons, a volume slider (0–150 %) and a live state label, driving the external
+  channel ([`src/web/mivocero.html`](src/web/mivocero.html)).
+
+### Changed
+
+- [`TurnManager::set_external_gain`](src/orchestrator/turn_manager.rs) forwards
+  the client volume to the mixer.
+- New module declared in [`src/main.rs`](src/main.rs) (`mod media;`).
+
+### Why
+
+- Lets the agent play a music/radio/YouTube bed under the voice — useful for
+  demos (radio, background music) — while keeping the channel fully independent
+  of the speech pipeline so it survives barge-in.
+
+### Notes
+
+- Only needed when the external channel is used: `ffmpeg` for URL/radio/HLS and
+  `yt-dlp` for YouTube. YouTube may require cookies in some environments; pass
+  them via `MEDIA_YTDLP_ARGS=--cookies /path/cookies.txt`.
+- A bounded source (VOD) is throttled to the mixer's drain rate via backpressure
+  (`remaining_capacity()` + 20 ms sleeps), so a fast decoder cannot overflow the
+  ring buffer.
+
+---
+
+## 2026-10-16 — Drama 3 de-emphasis: sampling knobs + neutral style tag
+
+### Added
+
+- **`TTS_TEMPERATURE`** (default `0.45`), **`TTS_TOP_P`** (default `0.75`) and
+  **`TTS_TOP_K`** (unset) — optional sampling overrides forwarded in the
+  `/v1/audio/speech` payload by the `fish` engine. An empty value omits the field
+  so the server default applies. New `env_opt_f32` / `env_opt_u32` helpers in
+  [`src/config.rs`](src/config.rs) implement the "unset → fallback, empty →
+  `None`" semantics.
+- **`TTS_STYLE_TAG`** (default `[conversational, casual]`) — a neutral style tag
+  prepended to every synthesis request whose text does not already start with a
+  `[...]` tag ([`FishAudioTts::styled`](src/tts/fish_audio.rs)). Empty disables
+  the prefix.
+
+### Changed
+
+- [`SpeechRequest`](src/tts/fish_audio.rs) gains optional `temperature`, `top_p`
+  and `top_k` fields (serialized only when set); the request body now uses the
+  styled text as `input`. Startup logs `TTS de-emphasis settings …`, and the
+  per-request debug log shows the sampling values and whether the text was
+  prefixed (`styled=`).
+
+### Why
+
+- Drama 3 over-articulates: LLM replies could come back with a theatrical,
+  radio-drama cadence. Exaggerated intonations live in the tails of the acoustic
+  token distribution, so trimming the sampling tails (`temperature` / `top_p`)
+  flattens the delivery, and a neutral style tag steers untagged (LLM) prose into
+  a conversational register. Clip banks carry their own tags and are untouched.
+
+### Notes
+
+- `repetition_penalty` is deliberately **not** exposed: this server rejects any
+  value other than `1.0` (`Drama 3 request: repetition_penalty must be 1.0`).
+  `min_p`, `seed` and a nested `sampling_params` are rejected too.
+- The voice-cloning reference (`solis.wav`) is left unchanged for now — its
+  "locutor profesional" prosody is a further, separate lever.
+- **`.env` gotcha surfaced during this change.** `dotenvy` fails on unquoted
+  values containing spaces, and a single bad line makes it discard the whole
+  file: the process then silently starts with built-in defaults (no LLM, plain
+  HTTP) while `server.sh` still reports the scheme from its own `.env` grep. The
+  style tag is therefore quoted (`TTS_STYLE_TAG="[conversational, casual]"`).
+
+---
+
+## 2026-10-16 — Backchannel: random reaction depth inside the micro-pause
+
+### Changed
+
+- [`BackchannelScheduler::maybe_emit`](src/orchestrator/backchannel.rs) now draws
+  the depth at which it reacts **per pause**: the first time a micro-pause is
+  seen, a target is picked uniformly in `[BACKCHANNEL_PAUSE_MIN_MS,
+  BACKCHANNEL_PAUSE_MAX_MS]` and the cue fires only once `silence_ms()` reaches
+  it (new `pause_target_ms` field, cleared when the pause ends or the turn
+  resets). Previously the cue fired at the *first* analysis window inside the
+  window, so with a 32 ms VAD step every cue landed at exactly
+  `BACKCHANNEL_PAUSE_MIN_MS`.
+- A pause that grows past the upper bound (on its way to end-of-utterance) is
+  abandoned without firing.
+
+### Why
+
+- Verification on a live session showed every cue at `pause_ms=96`, i.e. all cues
+  reacting at exactly the minimum — a residual regularity in an otherwise
+  naturalized feature. Randomizing the depth removes it: cues now land anywhere
+  in the window (observed `pause_ms` of `96`, `128`, `192`, …).
+
+### Notes
+
+- No new environment variables: the behaviour is driven by the existing
+  `BACKCHANNEL_PAUSE_MIN_MS` / `BACKCHANNEL_PAUSE_MAX_MS` window.
+- Because the VAD advances in 32 ms windows, the emitted `pause_ms` is a multiple
+  of 32 ms; the randomly drawn target is what varies.
+
+---
+
+## 2026-10-16 — Backchannel sounds more natural (micro-pause cues, jittered timing, categories)
+
+### Added
+
+- **`BACKCHANNEL_JITTER_MS`** (default `1200`), **`BACKCHANNEL_PAUSE_MIN_MS`**
+  (default `96`), **`BACKCHANNEL_PAUSE_MAX_MS`** (default `260`),
+  **`BACKCHANNEL_PROB`** (default `0.65`) and **`BACKCHANNEL_VOLUME_JITTER`**
+  (default `0.2`) — new `.env` knobs (`.env`, `.env.example`,
+  [`BackchannelSettings`](src/orchestrator/backchannel.rs)) that shape the cue
+  timing, spacing, hit rate and loudness drift.
+- **Category prefix** in `BACKCHANNEL_TEXTS`: a line may be written
+  `category::phrase` (e.g. `ack::[calm] Mm-hmm...`, `agree::[agreeing] Claro...`);
+  [`parse_texts`](src/orchestrator/backchannel.rs) stores the category alongside
+  the phrase and defaults to `ack` when the prefix is absent.
+- [`VadDetector::silence_ms`](src/vad/silero.rs) — exposes the running silence
+  inside the current utterance (multiples of the 32 ms analysis window), i.e. the
+  length of the micro-pause the speaker is currently in.
+- [`FillerBank::names`](src/orchestrator/turn_manager.rs) — read accessor for the
+  clip names, used to map the bank order onto the phrase/category list.
+
+### Changed
+
+- [`BackchannelScheduler::maybe_emit`](src/orchestrator/backchannel.rs) now takes
+  the VAD micro-pause length and fires a cue **only inside a
+  `PAUSE_MIN_MS..PAUSE_MAX_MS` window** (the upper bound is capped just below
+  `VAD_MIN_SILENCE_MS` so it never collides with end-of-utterance), **at most once
+  per pause** (latched with `pause_settled`).
+- Cue timing is **randomized**: the first cue of a turn waits
+  `MIN_SPEECH_MS + rand(0..JITTER_MS)`, and the gap to the next cue is
+  `INTERVAL_MS ± JITTER_MS/2` — instead of a fixed interval.
+- Each qualifying pause passes a **probabilistic gate** (`PROB`); a miss does not
+  retry on the same pause.
+- The clip is chosen with an **anti-repetition** rule (skips the last two clips)
+  and its samples are scaled by **±`VOLUME_JITTER`** before being pushed to
+  `backchannel_queue`.
+- Selection follows a **category progression** through the turn — it prefers a
+  category other than the last one used and favours categories not yet used this
+  turn (e.g. `ack` then `agree`), falling back to a random clip.
+- `BACKCHANNEL_MAX_PER_TURN` default lowered **8 → 3**, so the agent emits a
+  couple of cues per turn rather than chattering.
+
+### Why
+
+- A fixed interval with a fixed clip made the backchannel feel mechanical and
+  detached from the speaker. Real listeners react to *pauses*, not to a metronome:
+  cueing inside the speaker's own micro-pauses, with jittered spacing, an
+  occasional deliberate skip, mild volume drift and a little progression
+  (acknowledge → agree) reads as attentive listening instead of a loop.
+
+### Notes
+
+- The naturalness knobs are all optional; omitting them keeps the previous
+  behaviour except for the `MAX_PER_TURN` default (now `3`).
+- Nested clamps in `from_env`: `interval_ms >= 500`, `pause_max >= pause_min`,
+  and `gain`/`prob`/`volume_jitter` are clamped to sane ranges.
+- A debug line is logged only when a cue is actually emitted:
+  `backchannel emitted during user speech … pause_ms=…` (enable
+  `audio_agent_engine::orchestrator=debug` in `RUST_LOG`).
+
+---
+
+## 2026-10-16 — Backchannel becomes a random phrase bank driven by `BACKCHANNEL_TEXTS`
+
+### Added
+
+- **`BACKCHANNEL_TEXTS`** (`.env`, `.env.example`,
+  [`BackchannelSettings`](src/orchestrator/backchannel.rs)): the backchannel bank
+  is now a list of phrases, **one per line** (a `|` separator is also accepted),
+  with Drama-3 style tags passed straight through to the TTS. `.env` ships 8
+  Spanish phrases (`[calm] Mm-hmm...`, `[attentive] Ajá...`, …); the Rust default
+  is [`DEFAULT_BACKCHANNEL_TEXTS`](src/orchestrator/backchannel.rs).
+- [`assets::ensure_backchannel_clips`](src/assets.rs), implemented on top of the
+  new generic [`assets::ensure_text_bank_clips`](src/assets.rs): synthesizes **one
+  clip per phrase** at startup (`bc01`, `bc02`, …, `TEXT_BANK_CONCURRENCY = 4` at
+  a time) and removes clips left over from a previous list. The list the current
+  clips were made from is stored in `BACKCHANNEL_DIR/texts.txt`; when it is
+  unchanged and every clip is present the whole synthesis is **skipped**, so a
+  restart costs ~2 s instead of ~1 s per phrase. The index is only written once
+  every clip succeeded, so a partial failure is retried at the next startup.
+
+### Changed
+
+- [`BackchannelScheduler::maybe_emit`](src/orchestrator/backchannel.rs) picks the
+  clip **at random** ([`FillerBank::random`](src/orchestrator/turn_manager.rs),
+  xorshift64 seeded from the clock) instead of round-robin, so the acknowledgment
+  varies from turn to turn — the same behaviour the start filler already had. The
+  `next_index` cursor was dropped.
+- `assets::ensure_start_filler_clips` is now a thin wrapper over
+  `ensure_text_bank_clips`, so the start filler and the backchannel share one
+  implementation. Its logs gained a `label` field
+  (`refreshing backchannel clips at startup …`).
+- The backchannel no longer uses the fixed `assets::BACKCHANNEL_CLIPS` list
+  (removed); its defaults moved to `DEFAULT_BACKCHANNEL_TEXTS`.
+
+### Why
+
+- A fixed 4-clip bank repeated the same "mm-hmm / ajá" over and over; a curated
+  list with tags keeps the agent sounding natural and is editable straight from
+  `.env`, exactly like the start filler.
+- The old bootstrap (`ensure_clips`) only generated *missing* clips, so changing
+  the phrases required deleting files by hand; the phrase list is now the source
+  of truth.
+
+### Notes
+
+- Clips are named by position, so switching from the old names (`mmhmm`, `aja`,
+  `claro`, `yaveo`) to `bc01`…**removes** the four legacy files on the first
+  restart after this change (logged as `removed stale backchannel clip`).
+- `BACKCHANNEL_GAIN`, `BACKCHANNEL_MIN_SPEECH_MS`, `BACKCHANNEL_INTERVAL_MS` and
+  `BACKCHANNEL_MAX_PER_TURN` are unchanged.
+
+---
+
+## 2026-10-16 — Fix: start filler fired on every turn (gate on chunk arrival, not playback)
+
+### Fixed
+
+- [`TurnManager::schedule_start_filler`](src/orchestrator/turn_manager.rs) gated the
+  cue on `AudioMixer::tts_playback_started`, which only flips once the **TTS
+  pre-buffer** (`TTS_PREBUFFER_MS`) is full — i.e. when playback starts, ~1.9 s
+  after the dispatch in the reference deployment. The first response chunk
+  actually arrives at ~0.7–1.0 s, so a `START_FILLER_GO_DELAY` of 1200 ms was
+  almost always *shorter* than the gate's own signal and the acknowledgment was
+  queued on essentially every turn.
+- The gate now uses the new
+  [`AudioMixer::tts_audio_arrived`](src/audio/mixer.rs), latched as soon as the
+  first TTS samples are queued for the turn (checked on the 20 ms ticker),
+  **before** the pre-buffer is reached. Both `tts_audio_arrived` and
+  `tts_playback_started` are reset by `mark_stream_start` / `flush`.
+  A fast reply that produces audio within `START_FILLER_GO_DELAY` therefore
+  suppresses the cue, as intended.
+
+### Changed
+
+- The skip log line is now `first response audio already arrived — start filler
+  skipped` (was `response audio already playing — start filler skipped`).
+- The end-of-turn filler is unchanged: it still keys off
+  `tts_playback_started` (its 2500 ms delay is long enough that playback start is
+  the right signal).
+
+### Notes
+
+- No configuration change; `START_FILLER_GO_DELAY=1200` now means what the `.env`
+  comment always said ("first audio chunk of the reply"). Verified in the log: a
+  text turn in which the first chunk reached the mixer ~0.4 s after the TTS
+  request logged `first response audio already arrived — start filler skipped`
+  with no `queued start filler` for the turn.
+
+---
+
+## 2026-10-16 — Start filler becomes conditional: `START_FILLER_GO_DELAY` (1200 ms)
+
+### Changed
+
+- The start filler is no longer played on **every** turn: it is now a *latency
+  mask*, scheduled exactly like the end-of-turn filler but on its own channel and
+  with its own, shorter delay.
+  [`TurnManager::schedule_start_filler`](src/orchestrator/turn_manager.rs)
+  (replacing `play_start_filler`) sleeps `START_FILLER_GO_DELAY` after the turn is
+  dispatched and queues a random phrase **only if the first response audio has not
+  started playing** (`AudioMixer::tts_playback_started` still `false`); otherwise
+  the cue is dropped. *(The gate was later changed to `tts_audio_arrived` — see
+  the entry above, which fixes this cue firing on every turn.)* A pending cue is
+  cancelled on barge-in / new turn through the turn's `CancellationToken`, and
+  `mixer.flush` clears it once queued.
+- The scheduling now happens in `run_llm_turn` / `dispatch_tts` next to
+  `schedule_filler` (where the turn's cancellation token and `mark_stream_start`
+  live) instead of at the top of `handle_user_turn`, because the delay must be
+  measured from the dispatch of the reply and be cancellable with it.
+
+### Added
+
+- **`START_FILLER_GO_DELAY`** (`.env`, `.env.example`, default `1200` ms): how long
+  to wait for the first response audio before falling back to the start filler.
+
+### Why
+
+- The cue is only useful when the reply is *late*; a fast reply (LLM + TTS first
+  chunk under 1200 ms) is now answered directly, without an unnecessary
+  "Un momento…" in front of it.
+
+### Notes
+
+- The 22-clip bank, the random pick and the startup refresh are unchanged.
+
+---
+
+## 2026-10-16 — Start filler: random phrase bank driven by `START_FILLER_TEXTS`
+
+### Added
+
+- **`START_FILLER_TEXTS`** (`.env`, `.env.example`,
+  [`src/config.rs`](src/config.rs)) replaces the single `START_FILLER_TEXT`: a
+  list of phrases, **one per line** (a `|` separator is also accepted), e.g. the
+  Spanish set `"[calm] Un momento..."`, `"[thoughtful] A ver, veamos..."`, … with
+  Drama-3 style tags passed straight through to the TTS. `.env` ships 22 phrases.
+- [`assets::ensure_start_filler_clips`](src/assets.rs): synthesizes **one clip per
+  phrase** at startup (`sf01`, `sf02`, …, generated
+  `START_FILLER_CONCURRENCY = 4` at a time) and removes clips left over from a
+  previous list. The list the current clips were made from is stored in
+  `START_FILLER_DIR/texts.txt`; when it is unchanged and every clip is present the
+  whole synthesis is **skipped**, so a restart costs ~2 s instead of ~1 s per
+  phrase. The index is only written once every clip succeeded, so a partial
+  failure is retried at the next startup.
+- [`FillerBank::random`](src/orchestrator/turn_manager.rs): uniform pick over the
+  bank using a per-bank xorshift64 state seeded from the clock;
+  [`TurnManager::play_start_filler`](src/orchestrator/turn_manager.rs) now uses it,
+  so the acknowledgment differs from turn to turn instead of always repeating the
+  same sentence. *(Caller renamed to `schedule_start_filler` by the entry above,
+  which also made the cue conditional.)*
+
+### Why
+
+- A single fixed acknowledgment ("Un momento…") becomes annoying across a long
+  conversation; a random phrase from a curated list keeps the agent sounding
+  natural, and the phrase list is editable straight from `.env`.
+- Re-synthesizing 22 clips on *every* startup added ~21 s to the boot time
+  (measured), so the bootstrap now tracks the phrase list and only re-synthesizes
+  when it changed (or a clip is missing).
+
+### Notes
+
+- `force` was dropped from [`assets::ensure_clips`](src/assets.rs): the filler /
+  backchannel banks keep the "generate only if missing" behaviour, and the start
+  filler has its own list-driven bootstrap.
+- [`server.sh`](server.sh) startup wait raised from ~20 s to ~60 s: the first
+  startup after a list change synthesizes the whole bank before the socket is
+  bound.
+- A failed synthesis keeps the previous clip of that position; a barge-in still
+  clears the start-filler channel (`AudioMixer::flush`), and
+  `START_FILLER_ENABLED=false` disables it entirely.
+
+---
+
+## 2026-10-16 — Start filler: immediate turn-start acknowledgment on its own mixer channel
+
+### Added
+
+- **`START_FILLER_ENABLED` / `START_FILLER_TEXT` / `START_FILLER_DIR`** (`.env`,
+  `.env.example`, [`src/config.rs`](src/config.rs)). The *start filler* is a
+  pre-generated clip queued the moment a user turn begins — no delay — on a
+  **dedicated mixer channel**, so it acknowledges the turn while the LLM/TTS are
+  still working, independently of the delayed latency filler. *(Superseded by the
+  entry above: `START_FILLER_TEXT` became the `START_FILLER_TEXTS` list and the
+  clip is now picked at random.)*
+- [`AudioMixer`](src/audio/mixer.rs): new `start_filler_queue` channel, mixed as
+  `mixed = tts + ((filler + start_filler) × filler_gain) + (backchannel ×
+  BACKCHANNEL_GAIN)`, so the start filler shares the filler gain (idle `1.0`,
+  ducked `0.15` under TTS). Included in `is_active()` and cleared by `flush()`.
+- [`TurnManager::play_start_filler`](src/orchestrator/turn_manager.rs), called
+  from `handle_user_turn` right after the in-flight reply is cancelled.
+- Startup bootstrap synthesizes `START_FILLER_DIR/start_filler.raw` with the
+  configured voice if it is missing ([`src/assets.rs`](src/assets.rs)); the clip
+  is preloaded into its own [`FillerBank`](src/orchestrator/turn_manager.rs),
+  kept out of the round-robin `FILLERS_DIR` bank.
+
+### Why
+
+- The delayed latency filler only fires after `FILLER_DELAY_MS` (and only if the
+  reply is still silent), so with the current fast TTFB (~`0.73 s`) the agent can
+  stay silent for a moment after the user stops speaking. The start filler
+  provides an immediate acknowledgment instead, without touching the existing
+  delayed filler.
+
+### Notes
+
+- *(Superseded — see the entry above.)* The clip was re-synthesized on every
+  startup (`ensure_clips(..., force = true)`), so editing `START_FILLER_TEXT` took
+  effect at the next restart with no manual deletion. A new clip was written only
+  on success, so a failed synthesis left the previous clip in place; the filler /
+  backchannel banks kept the "generate only if missing" behaviour.
+- A barge-in clears the start filler along with every other channel
+  (`AudioMixer::flush`); `START_FILLER_ENABLED=false` disables it entirely.
+
+---
+
+## 2026-10-16 — Fixed micro-gaps at the start of each sentence → `TTS_PREBUFFER_MS` 170 → 550 ms, `LLM_STREAM_CHUNK_CHARS` 120 → 240
+
+### Changed
+
+- **`TTS_PREBUFFER_MS` raised `170` → `550`** (`.env`, `.env.example`). With the
+  current vocoder windows (first `185.8` ms, steady `371.6` ms) any pre-buffer in
+  `(186, 557]` ms primes playback on the *same* second window, so `550 ms` takes
+  the entire ~557 ms cushion **at no extra TTFA** (~`0.73 s`).
+- **`LLM_STREAM_CHUNK_CHARS` raised `120` → `240`** (`.env`, `.env.example`). The
+  first-chunk threshold stays at `20` (early flush preserved), but every following
+  chunk is now twice as long → **fewer TTS requests, hence fewer chunk seams**.
+- **README** (`Mixer & jitter buffering`, the `TTS_PREBUFFER_MS` /
+  `LLM_STREAM_CHUNK_CHARS` tables and the TTFA note) updated to the new defaults
+  and rationale. No Rust code changed — both values are read from `.env` at
+  runtime.
+
+### Why
+
+- After the seam-quality retune left the **audible micro-interruptions at the
+  start of sentences**. Diagnosis from `run/server.log`: the defect is a **TTS
+  queue underrun at the chunk seams**, not a timbre artifact. Each sentence /
+  fragment is a *separate* HTTP request whose PCM is concatenated with no
+  crossfade; the relay advances chunk-by-chunk, so the first dip in production
+  empties the queue and the mixer logs
+  `TTS queue underrun — pausing playback until audio resumes` (94 occurrences in
+  the sampled log; 0 `running low` warnings), then restarts with `need = 1` → an
+  audible micro-gap at the start of the next sentence.
+- **Why the queue empties:** with `TTS_PIPELINE_DEPTH = 3` on a single GPU the
+  measured per-window cadence under concurrency is **552–613 ms (~1.5×)** versus
+  **~350 ms (~0.94×)** for a lone request. A `170 ms` cushion has no margin
+  against that; `550 ms` does, and it is latency-free because the pre-buffer
+  already lands on the second window.
+- Measured in the log at the seam (12:56:36–38): chunks of `16384` samples
+  (`queue_len=16384`, `prebuffer=7497` = 170 ms) with two concurrent requests
+  (`text_len=119` and `19`), each followed by an underrun-pause line.
+
+### Notes
+
+- Both levers are pure configuration; the binary is unchanged, so `./server.sh
+  restart` (no rebuild) is enough to apply them.
+- The `550 ms` cushion is the ~557 ms gap to the third window start, so raising
+  it further only adds latency (it would wait for the *next* window).
+
+---
+
+## 2026-10-16 — Drama-3 vocoder retuned for seam quality → stride `4` / followup `8` / overlap `16`; `TTS_PREBUFFER_MS` 450 → 170 ms
+
+### Changed
+
+- **The Drama-3 launcher (`/root/drama3/start-drama3.sh`, pm2 `start-drama3`) now
+  carries more decoder context per window.** The previous config (stride `4`,
+  flat ramp `"[4,4,4]"`, overlap `8`, crossfade `256`) was replaced by:
+  ```
+  --vocoder.factory.stream_stride 4
+  --vocoder.factory.stream_followup_stride_ramp "[8,8,8]"
+  --vocoder.factory.stream_followup_stride 8
+  --vocoder.factory.stream_overlap_tokens 16
+  --vocoder.factory.stream_crossfade_samples 512
+  --tts_engine.factory.enable_async_decode true
+  ```
+- **`TTS_PREBUFFER_MS` lowered `450` → `170`** (`.env`, `.env.example`,
+  [`src/config.rs`](src/config.rs)). With stride `4` the *first* vocoder window is
+  4 codec frames = **0.186 s**, so `170 ms` starts playback on that first window
+  and **TTFA collapses to the server's own TTFB (~0.38 s)**.
+- **README:** the *"Starting the Drama 3 backend (SGLang-Omni)"* subsection and
+  the *"Mixer & jitter buffering"* pre-buffer note were rewritten around the new
+  stride/overlap values and the ~0.186 s first / ~0.372 s steady window cadence.
+
+### Why
+
+- The previous latency-first config (stride `4`, overlap `8`) produced **audible
+  micro-gaps and a slight detune / falsetto on long replies**. Root cause: with
+  only `8` tokens of decoder warm-up context *per window*, and one TTS request
+  per reply chunk (PCM concatenated without crossfade at the request seams), the
+  streaming decoder's state was too shallow and its timbre/pitch wobbled at each
+  window and request boundary.
+- **Seam context restored without breaking real-time:** raising the overlap to
+  `16` at stride `4` pushes decode to 5× real time, which the box **cannot**
+  sustain (ratio rose to 1.18–1.98×). Raising *strides and overlap together* —
+  stride `4` (first window) / followup `8` (steady) with overlap `16` — keeps the
+  decode load at a sustainable **`(16+8)/8 = 3×`** (~0.95× ratio) while giving
+  each steady window twice the context, and `crossfade 512` smooths the seams
+  further.
+- A/B measurements on the live endpoint (`measure_tts.py`, warm server, voice
+  cloning, single request vs sentence-chunked like the engine) on a long
+  multi-sentence reply: **the amplitude jump at the seam boundaries dropped from
+  the 99.5+ percentile of the signal to 96–98**, i.e. the seams no longer stand
+  out. TTFB stays **~0.38 s** (the first window is unchanged) and the real-time
+  ratio stays **~0.94–0.98×**.
+
+### Notes
+
+- The first window is unchanged (4 frames), so the residual latency is still
+  dominated by the server's **fixed ~0.38 s TTFB**; the steady window grew from
+  0.186 s to **0.372 s** (8 frames) and arrives ~350 ms apart, so the pre-buffer
+  of `170 ms` still starts playback on the very first window. Further latency
+  gains would need a faster first token (model / preprocessing), not a smaller
+  stride.
+- `measure_tts.py` was added to the repo: it streams `/v1/audio/speech` and prints
+  the per-window arrival schedule, TTFB and real-time ratio (plus a seam-jump
+  summary), so future A/B runs are one command.
+
+---
+
 ## 2026-10-16 — Mivocero: karaoke word highlighting on the assistant reply

 ### Changed
@@ -0,0 +1,8 @@
+[calm] Mm-hmm...
+[attentive] Uh-huh...
+[agreeing] Right...
+[listening] I see...
+[attentive] Yeah, yeah...
+[calm] Got it...
+[relaxed] Okay...
+[thoughtful] Oh, I see...
@@ -0,0 +1,8 @@
+[calm] Mm-hmm...
+[attentive] Ajá...
+[agreeing] Claro...
+[listening] Ya veo...
+[attentive] Sí, sí...
+[calm] Entiendo...
+[relaxed] Vale...
+[thoughtful] Ah, ya...
@@ -0,0 +1,8 @@
+[calm] Mmm...
+[attentive] Eh già...
+[agreeing] Certo...
+[listening] Capisco...
+[attentive] Sì, sì...
+[calm] Ho capito...
+[relaxed] Va bene...
+[thoughtful] Ah, ecco...
@@ -0,0 +1,7 @@
+Uhm...
+Hmm...
+Mmm...
+Well...
+Uh, let's see...
+Okay...
+Right...
@@ -0,0 +1,7 @@
+Uhm...
+Eh...
+Mmm...
+Vediamo...
+Allora...
+Beh...
+Dunque...
@@ -0,0 +1,3 @@
+[calm] One moment...
+[thoughtful] Let me see...
+[sigh] Okay, coming up...
@@ -0,0 +1,22 @@
+[calm] Un momento...
+[thoughtful] A ver, veamos...
+[calm][thinking] Déjame revisar...
+[serious] A ver, déjame entender bien esto...
+[hesitant] Entonces... echemos un vistazo...
+[calm] Dame solo un segundo...
+[sigh] Vale, ya voy...
+[laughs] Buena pregunta... déjame ver...
+[chuckle] De acuerdo, a ver qué encontramos...
+[inhale] Bueno, vamos por partes...
+[casual] Sí, espera un instante...
+[confident] Recibido, me pongo a ello ahora mismo...
+[excited] Perfecto, mira esto...
+[enthusiastic] ¡Genial! Vamos a comprobarlo de inmediato...
+[determined] Sin problema, me encargo ya...
+[hesitant] Mmm... espera un segundo...
+[confused] Déjame comprobarlo otra vez...
+[curious] Curioso... a ver un momento...
+[whispering] Shh, solo un instante...
+[speaking softly, thinking out loud] Déjame echar un vistazo rápido...
+[sighing gently, reassuring] Tranquilo, enseguida tengo la respuesta...
+[focused, typing on a keyboard] Solo un momento, lo compruebo ya mismo...
@@ -0,0 +1,3 @@
+[calm] Un momento...
+[thoughtful] Vediamo un po'...
+[sigh] Va bene, arrivo...
@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Measure Drama 3 / SGLang TTS streaming: TTFB, burst sizes, real-time ratio.
+
+Streams /v1/audio/speech as raw PCM and reports how the audio arrives, so the
+vocoder window schedule (stream_stride / ramp / followup) and the real-time
+ratio can be checked. Run against the local SGLang-Omni server.
+
+Two modes:
+  (default)    one request for the whole text -> only the server's own vocoder
+               window seams are present.
+  --chunked    split the text on sentence boundaries and issue one request per
+               sentence, concatenating the raw PCM like the engine does -> adds
+               the engine's per-chunk request boundaries on top of the seams.
+               Comparing the two WAVs tells whether an artifact comes from the
+               vocoder (present in both) or from the engine's chunking (only in
+               the chunked one).
+"""
+import array
+import re
+import sys
+import time
+import wave
+
+import requests
+
+URL = "http://localhost:8000/v1/audio/speech"
+MODEL = "fishaudio/drama-3"
+SR = 44100
+BYTES_PER_SAMPLE = 2
+
+# Voice-cloning reference (matches the engine's .env defaults).
+REF_AUDIO = "/root/piperust/audio-agent-engine/voice_profiles/solis.wav"
+REF_TEXT = "/root/piperust/audio-agent-engine/voice_profiles/solis.txt"
+
+
+def load_ref_text(path: str) -> str:
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read().strip()
+    except OSError:
+        return ""
+
+
+def save_wav(path: str, pcm: bytes, sr: int) -> None:
+    with wave.open(path, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(BYTES_PER_SAMPLE)
+        w.setframerate(sr)
+        w.writeframes(pcm)
+
+
+def analyze_seams(pcm: bytes, boundaries: list[int]) -> None:
+    """Compare the sample-to-sample jump exactly at each boundary against the
+    jumps inside the windows. A boundary jump no larger than the interior
+    distribution means no amplitude discontinuity there (the vocoder crossfade /
+    the engine's crossfade are doing their job)."""
+    s = array.array("h")
+    s.frombytes(pcm[: len(pcm) // BYTES_PER_SAMPLE * BYTES_PER_SAMPLE])
+    n = len(s)
+    if n < 2:
+        return
+    deltas = sorted(abs(s[i] - s[i - 1]) for i in range(1, n))
+    p999 = deltas[int(len(deltas) * 0.999)]
+    global_max = deltas[-1]
+    bounds = [b for b in boundaries[:-1] if 0 < b < n]
+    bj = [abs(s[b] - s[b - 1]) for b in bounds]
+    max_b = max(bj) if bj else 0
+    rank = deltas.index(max_b) / len(deltas) * 100 if bj else 0
+    print(f"seam analysis: boundaries={len(bounds)} max_boundary_jump={max_b} "
+          f"global_max_jump={global_max} global_p99.9={p999} "
+          f"max_boundary_percentile={rank:.2f}")
+
+
+def stream_pcm(text: str, use_ref: bool, t0: float):
+    """POST one text and return (pcm_bytes, events, sample_rate).
+    events = list of (t_seconds, bytes_cumulative, chunk_bytes)."""
+    body = {
+        "model": MODEL,
+        "input": text,
+        "voice": "default",
+        "response_format": "pcm",
+        "stream": True,
+    }
+    if use_ref:
+        body["references"] = [
+            {"audio_path": REF_AUDIO, "text": load_ref_text(REF_TEXT)}
+        ]
+    resp = requests.post(URL, json=body, stream=True, timeout=120)
+    resp.raise_for_status()
+    sr = int(resp.headers.get("x-sample-rate") or SR)
+    pcm = bytearray()
+    events = []
+    total = 0
+    with resp:
+        for chunk in resp.iter_content(chunk_size=None):
+            if not chunk:
+                continue
+            total += len(chunk)
+            pcm += chunk
+            events.append((time.perf_counter() - t0, total, len(chunk)))
+    return bytes(pcm), events, sr
+
+
+def summarise_events(events) -> None:
+    ttfb = events[0][0]
+    tlast = events[-1][0]
+    audio_s = (events[-1][1] // BYTES_PER_SAMPLE) / SR
+    print(f"chunks={len(events)} ttfb={ttfb*1000:.0f}ms "
+          f"last={tlast*1000:.0f}ms audio={audio_s:.2f}s "
+          f"wall={tlast:.2f}s ratio={tlast/audio_s:.3f}x")
+
+
+def measure(text: str, use_ref: bool = True, out: str | None = None) -> None:
+    print(f"[single] text={text!r} ref={use_ref}")
+    t0 = time.perf_counter()
+    pcm, events, sr = stream_pcm(text, use_ref, t0)
+    print("x-sample-rate:", sr)
+    summarise_events(events)
+    boundaries = [cum // BYTES_PER_SAMPLE for _, cum, _ in events]
+    analyze_seams(pcm, boundaries)
+    if out:
+        save_wav(out, pcm, sr)
+        print(f"saved WAV -> {out}")
+
+
+def measure_chunked(text: str, use_ref: bool = True, out: str | None = None) -> None:
+    parts = [p for p in re.split(r"(?<=[.!?;])\s+", text.strip()) if p]
+    print(f"[chunked] parts={len(parts)} ref={use_ref}")
+    t0 = time.perf_counter()
+    pcm = bytearray()
+    events = []
+    sr = SR
+    total = 0
+    for i, part in enumerate(parts):
+        t_req = time.perf_counter()
+        p, ev, sr = stream_pcm(part, use_ref, t0)
+        ttfb = ev[0][0] - (t_req - t0)
+        print(f"  part {i}: {len(part):3d} chars ttfb={ttfb*1000:4.0f}ms "
+              f"audio={(len(p)//BYTES_PER_SAMPLE)/sr:.2f}s part={part[:40]!r}")
+        pcm += p
+        for t, cum, cb in ev:
+            total += cb
+            events.append((t, total, cb))
+    print("x-sample-rate:", sr)
+    summarise_events(events)
+    boundaries = [cum // BYTES_PER_SAMPLE for _, cum, _ in events]
+    analyze_seams(bytes(pcm), boundaries)
+    if out:
+        save_wav(out, bytes(pcm), sr)
+        print(f"saved WAV -> {out}")
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    use_ref = "--no-ref" not in args
+
+    def arg_value(flag):
+        return args[args.index(flag) + 1] if flag in args else None
+
+    out = arg_value("--out")
+    text = arg_value("--text") or (
+        "Ciao, questa e' una prova per misurare la latenza del motore vocale. "
+        "Contiamo insieme da uno fino a venti: uno, due, tre, quattro, cinque, "
+        "sei, sette, otto, nove, dieci, undici, dodici, tredici, quattordici, "
+        "quindici, sedici, diciassette, diciotto, diciannove, venti.")
+    if "--chunked" in args:
+        measure_chunked(text, use_ref=use_ref, out=out)
+    else:
+        measure(text, use_ref=use_ref, out=out)
@@ -0,0 +1,4 @@
+./server.sh restart
+tail -f run/server.log
+
+
@@ -0,0 +1,2 @@
+cargo r
+
--- a/Show More
+++ b/Show More