Skip to content

README.md

Latest commit

 

History

History
136 lines (101 loc) · 5.14 KB

README.md

File metadata and controls

136 lines (101 loc) · 5.14 KB
Raw

Read aloud

Opt-in Linux read-aloud support for assistant responses.

This feature stays thin. It does not bundle a voice model and it does not speak automatically. It adds an explicit icon button under assistant messages. A click is the only app-rendering path that starts speech.

Enable the feature

Add the feature to linux-features/features.json:

{
  "enabled": ["read-aloud"]
}

Then rebuild/package the app. The installed app remains silent until the user explicitly clicks a message's speech icon, uses conversation mode, or calls the Read Aloud MCP tool. For older builds, or to force-enable direct runtime calls, set the runtime opt-in:

mkdir -p ~/.config/codex-desktop
node -e 'const fs=require("fs"),p=process.env.HOME+"/.config/codex-desktop/settings.json";let s={};try{s=JSON.parse(fs.readFileSync(p,"utf8"))}catch{}s["codex-linux-read-aloud-enabled"]=true;fs.writeFileSync(p,JSON.stringify(s,null,2)+"\n")'

or:

CODEX_LINUX_READ_ALOUD_ENABLED=1 codex-desktop

The generated Read Aloud settings page also gets setup controls for machines where the default Kokoro paths are not ready:

  • Choose folder stores a folder that already contains kokoro-v1.0.onnx and voices-v1.0.bin.
  • Download voice creates the default Python runtime and downloads the Kokoro model files into the default data directory.
  • Speech pace controls Kokoro playback speed from 0.70x to 1.40x and stores the value in codex-linux-read-aloud-kokoro-speed.

Nothing is downloaded during app install or on first launch.

Conversation mode direction

The current feature intentionally stops at an explicit output button. A higher-level conversation mode should be layered on top of this instead of hidden inside message rendering:

  • enter an explicit voice/conversation mode from the UI or by user instruction;
  • stream microphone audio through a separate opt-in STT component;
  • after a short quiet period, submit the transcribed user turn to Codex;
  • stream the assistant response into the voice backend as chunks become stable;
  • when the user starts talking again, call stop and steer the active response.

That keeps the safe primitive small while leaving room for a real back-and-forth voice experience.

For the first agent-facing primitive, enable linux-features/read-aloud-mcp. That stages a separate read-aloud MCP plugin with doctor, read_aloud, and stop tools. It reuses the same Kokoro paths and runtime overrides documented below.

Voice model

Default speech uses an opt-in Kokoro ONNX runtime, similar in shape to readd but not dependent on a local readd checkout. The app stages only a tiny runner. Users provide or download the model files and Python runtime outside the Electron bundle.

Default paths:

  • Python runtime: ~/.local/share/codex-desktop/read-aloud/kokoro-venv/bin/python
  • Model: ~/.local/share/kokoro/kokoro-v1.0.onnx
  • Voices: ~/.local/share/kokoro/voices-v1.0.bin

Install the Python runtime and model files from the command line:

bash linux-features/read-aloud/install-kokoro-runtime.sh

Set CODEX_LINUX_READ_ALOUD_SKIP_MODEL_DOWNLOAD=1 to install only the Python runtime.

Runtime overrides:

  • CODEX_LINUX_READ_ALOUD_KOKORO_PYTHON
  • CODEX_LINUX_READ_ALOUD_KOKORO_MODEL
  • CODEX_LINUX_READ_ALOUD_KOKORO_VOICES
  • CODEX_LINUX_READ_ALOUD_KOKORO_VOICE, default bm_george
  • CODEX_LINUX_READ_ALOUD_KOKORO_SPEED, default 1.05, clamped to 0.70-1.40
  • CODEX_LINUX_READ_ALOUD_KOKORO_LANG, default en-us
  • CODEX_LINUX_READ_ALOUD_KOKORO_THREADS, default 4
  • CODEX_LINUX_READ_ALOUD_KOKORO_FIRST_CHARS, default 90
  • CODEX_LINUX_READ_ALOUD_KOKORO_CHUNK_CHARS, default 180
  • CODEX_LINUX_READ_ALOUD_KOKORO_MODEL_URL
  • CODEX_LINUX_READ_ALOUD_KOKORO_VOICES_URL

Kokoro speech is chunk-streamed: the runner synthesizes a short first chunk and starts writing PCM to aplay, then prepares the next chunks while audio is already playing. It does not synthesize the whole assistant response before playback starts.

The default downloads use Hugging Face-hosted Kokoro files that match the kokoro-onnx runtime shape:

  • https://huggingface.co/zijuncheng/kokoro_model_v1.0/resolve/main/kokoro-v1.0.onnx
  • https://huggingface.co/zijuncheng/kokoro_model_v1.0/resolve/main/voices-v1.0.bin

The settings page has a ? help affordance beside the setup actions. It summarizes the two supported setup paths: choose a local folder containing both files, or let Codex create the managed Python runtime and download the Hugging Face files into the default data directory.

For private/local setups, a custom command can still be used. Codex writes the cleaned response text to stdin:

CODEX_LINUX_READ_ALOUD_COMMAND="/path/to/tts-stdin-command" codex-desktop

When Kokoro is not ready, Read Aloud can fall back to system TTS through spd-say or espeak-ng. This fallback is enabled by default only after the user has opted into the Read Aloud feature/runtime; Kokoro remains the preferred backend when it is available. Disable the native fallback if the machine voice is not acceptable:

CODEX_LINUX_READ_ALOUD_NATIVE_FALLBACK=0 codex-desktop

The handler never invokes a shell for response text.