Omniscio

Spoken Narration

Spoken Narration is the audio sibling of Plain Speak. Where Plain Speak shows a rewritten glance-card on screen, Spoken Narration plays a short, friendly spoken recap of each completed agent reply — in the agent's own words ("here's what I did …"), not the raw message text and not the general read-aloud summary. It reuses the existing TTS pipeline (Fish Audio / Grok / ElevenLabs).

On this page

What it is

In development — hidden by default. Spoken Narration ships behind the spoken-narration unreleased-feature gate (setting narrationEnabled, default off; reveal via Settings → Lab or AMC_SHOW_SPOKEN_NARRATION=1). It is not visible to users until it is flipped to shipped.

Spoken Narration is the audio sibling of Plain Speak. Where Plain Speak shows a rewritten glance-card on screen, Spoken Narration plays a short, friendly spoken recap of each completed agent reply — in the agent's own words ("here's what I did …"), not the raw message text and not the general read-aloud summary. It reuses the existing TTS pipeline (Fish Audio / Grok / ElevenLabs).

Every engine can produce it (2026-07-31). The recap is written by the agent itself, inline, after a [[OMNISCIO_NARRATION]] marker at the very end of its reply (Omniscio strips it and routes it to the narration overlay / TTS). A Claude session is nudged to write it via the CLI --append-system-prompt; a non-Claude engine (Codex, Gemini, OpenCode, Cursor, Kimi Code, Hermes, Devin) — which has no such flag — gets the SAME nudge invisibly through the shared external first-message context plus a short per-turn reminder, the same generalized channel that delivers the Plain Speak card and the Final-Message marker to those engines (see plain-speak.md → "Every engine gets the directive"). Codex (2026-08-11) on a recent version instead carries the standing narration directive in Codex's own developerInstructions system-prompt slot (an older Codex falls back to first-message; its per-turn reminder still rides first-message). The narration extraction is engine-agnostic, so a Codex recap plays exactly like a Claude one.

A single narration mode (narrationMode, default auto) — set from the control in the top toolbar (on a phone, in the session header) or in Settings — picks the behavior:

  • Auto-play (auto) — when a reply finishes in the session you're viewing, its recap plays automatically. New replies only: switching away and back does not replay, and opening a session does not auto-play its last message.
  • Click to play (click) — every agent message that carries a narration shows a ▶ play button to play that message's recap on demand; nothing auto-plays.
  • Don't narrate (off) — the agent is not asked to write a recap at all (no [[OMNISCIO_NARRATION]] script), nothing is captured, and no play button appears. The mode control itself stays visible so you can switch back on.

The reply text streams live and is never blocked or delayed by narration. If there's no script or TTS fails, the text is unaffected and audio simply doesn't play.

On mobile (the phone / web client): tap a message's play button to hear its recap — the audio plays right on your phone. Auto-play of new replies is best-effort: because mobile browsers block sound until you've interacted with the page, a new reply only auto-plays after your first tap on a narration play button (that tap unlocks audio for the session). Before that first tap, new replies stay silent until you tap one.

Where to find it

A setting in Settings picks the behaviour, and the Narration tab appears on the same glance-card surface as Plain Speak. It is off by default and can be revealed early from Settings → Lab.

How it behaves

The mini-player

When nothing is playing, a narrated message shows just a ▶ play button. Press it and the button expands in place into a little player — pause/resume, a go-to-beginning ⏮, and a stop ✕ — right where the ▶ was. When the recap finishes (or you press stop) the player collapses back to just ▶. So the extra controls are only there while you're actually listening, never cluttering the header the rest of the time.

The play/pause control also stays in sync with your keyboard's media keys and your computer's media controls — pause or resume the recap from outside Omniscio and the button flips to match, so it never shows the wrong state.

If narration can't play right now, the ▶ is greyed out and hovering it tells you why — your daily narration limit is reached (resets tomorrow), no narration voice is set up, you're offline, or read-aloud is turned off — instead of a button that silently does nothing.

  • Go Back to Beginning (⏮, inside the player) — restart the recap from the top. It stops whatever is playing first (so it never overlaps or picks up mid-sentence), then replays the same cached audio — no new synthesis, no extra cost.

Reading it

  • Narration view — the message's view switch (the pill that flips Plain Speak ⇄ Original) gains a third Narration tab that shows the spoken script as text, so you can READ the recap instead of, or as well as, hearing it. The text loads the moment you open the tab; if it can't be found you get a short "not available to read" note rather than a spinner. The default view is never Narration — it's an explicit pick, one click away.

Both work on desktop and the phone / web client.

How it works

  1. The agent writes the script inline — no extra AI call. When the feature is on AND the mode isn't off, spawned sessions are nudged to end their reply with a [[OMNISCIO_NARRATION]] marker followed by a short spoken script. Because it rides the agent's normal turn, there is $0 of additional generation cost. Choosing "Don't narrate" removes the nudge, so the agent is never asked to narrate.
  2. Omniscio captures + hides it. The marker and its tail are stripped so they never appear as visible message text (even a partial marker mid-stream). The script is stored on an ai_manager_decisions feature='narration' row (its own narration_text column), keyed by message id — the same split-storage pattern Plain Speak uses, so the immutable message row is untouched.
  3. The renderer learns a message has audio via a presence-only signal (a boolean hasNarration on history load + a text-free availability push). The auto-play / availability path never carries the script text — audio is synthesized on demand in the main process and streamed as sound. The one time the text crosses to the renderer is when you deliberately open the Narration read-view (below): it lazily fetches THAT message's script over a read-only channel so you can read it — an explicit, per-message read of your own content, never a bulk load.
  4. Playback is metered under its own daily cap (narrationDailyCapUSD, default $2, separate from the general read-aloud cap) with a distinct tts-narration cost source — no double-counting against the read-aloud path.
  5. A private session never speaks in a voice you didn't pick. In AI Coaching or Journal, a recap is only spoken by a voice you added your own key for. The free company voice — which is also the out-of-the-box default voice, so it is what narrates when you have not chosen one — is never used for a private recap, not even on the first try and not even by the background audio pre-render. Instead the recap tells you it could not play with your voice, on either the computer or the phone. Everywhere else, a failed voice still plays the recap on the free voice and heals itself when your own voice comes back. This holds for everything read aloud from a private session, not just the play button: the inbox voice walk reading its stored recap, reading its last message when it has no recap, reading a follow-up answer back, and finishing a recap the live voice could not say — with no voice of your own, each of those says it could not read it rather than using the free voice.

Relationship to Plain Speak

Plain Speak (screen card) and Spoken Narration (audio) are independent: a narration is captured whenever narration is active (narrationEnabled on and the mode isn't off), even if the Plain Speak overlay is off. When an agent emits both, the narration is the canonical last tail, and Omniscio splits the two cleanly so neither swallows the other.

Engineering invariants (dual-marker parse order, presence-only delivery, the availability-keyed auto-play race fix, the cost-cap discipline) are pinned by spoken-narration-contract.md.

Last verified 2026-09-23