Terminal audio

Speak through the microphone and audio output attached to the runtime host.

Install terminal audio support

Activate the same Python environment used for Sleeptalk, then install the optional extra:

python -m pip install 'sleeptalk[terminal]'

On Linux, terminal audio also needs PortAudio (sudo apt install libportaudio2). If you used the uv-based release installer, add the extra with uv tool install --reinstall --python 3.11 'sleeptalk[terminal]' instead. Keep any other extras you use in that install request.

Start an attached call

cd /path/to/your/project
sleeptalk --terminal

1. Answer whether you are on headphones or speakers. Press Enter for speakers.
2. Grant microphone access to the terminal application when the OS asks.
3. Ask a short question and confirm that you hear the reply.
4. Press q or Ctrl+C to end the call and release the audio devices.

A terminal opened over SSH does not connect your laptop's microphone to the remote host. Use a browser call when the microphone is on another device; if both machines are on the same Tailscale network, a tailnet call needs no hosted relay.

Keys during a call

The settings menu changes speech speed, tool narration, and reply length for the running call. See settings and profiles.

Select audio devices

The default is the host's input and output device. For explicit selection, merge these fields into the profile's existing transport table:

[transport]
type = "terminal"
capture_mode = "headphones"
input_device = ""
output_device = ""

Replace an empty device value with a device name or numeric index available on the host. An invalid selection produces an error at startup instead of silently switching devices. Leave the fields empty to follow the host defaults.

Headphones and speakers

Setting capture_mode skips the question at the start of each call. headphones means the microphone cannot hear the agent, so interruption can use the same speech detector as browser and Discord calls, and a cough or door slam is less likely to cut the agent off. speakers, the default when nothing is set, uses a volume-based detector so the agent's own voice does not interrupt it.

Choose the mode that matches your actual audio setup. Answering headphones while using speakers makes the agent interrupt itself. Test a spoken interruption rather than assuming a setting fixed echo. See VAD and turn taking.

Recover from audio errors

If capture fails, check OS microphone permission and the selected device. If output is silent, check volume and the output device. Stop and restart the call after changing device settings.

Use sleeptalk doctor --config /path/to/profile.toml to separate provider failures from audio-device failures. A successful provider check does not prove microphone capture or audible playback.

Terminal audio needs an attached person at the keyboard. It is not a path for an unattended service.