TUI Usage Notes

Platform Differences

Platform	Default Mode	Interruption Method
macOS	Full-duplex with echo cancellation	Speak directly
Linux / Windows	Half-duplex	Enter /interrupt

Terminal Layout

The TUI uses a full-screen, two-region layout. The scrollable upper region shows conversation history, live voice transcripts, task state, and connection logs. Gateway and microphone state plus a persistent text composer stay fixed at the bottom. Asynchronous output and reconnect attempts do not interrupt text editing. Use PageUp / PageDown to browse history and Ctrl-C to exit at any time.

Text and Attachment Input

In addition to voice, the TUI accepts text, images, and regular files:

• Type directly in the bottom composer and press Enter to send.
• Paste a local file path to immediately show an image as [Image N] or a regular file as @absolute-path, staging it for the next turn.
• An @file-path in the text is sent as an attachment.
• Enter /mute to mute or restore the microphone, or /help for all commands.

A staged attachment can accompany either composer text or the next voice turn. Deleting its anchor from the composer also removes the staged attachment.

The TUI reads attachment content and sends it to the Gateway. The realtime voice frontend receives metadata only. When it delegates through spawn_thinking, the Gateway converts the original attachments into ACP ContentBlocks for the backend agent. Text anchors such as [Image 1] or @file-path remain bound to their file parts for multi-attachment references, replay, and backend interpretation. Each attachment is limited to 8 MB and the per-turn total is limited to 12 MB. The Gateway assigns each attachment a stable conversation-local input ID. This allows a later text or voice turn to delegate a previously submitted image to the backend without reinjecting file bytes into the realtime voice model.

macOS

macOS always uses CoreAudio AEC full-duplex: audio is continuously captured during playback, supporting direct-speech interruption, without additional configuration. The CoreAudio helper program is compiled by default to ~/Library/Caches/qwaudio/tui/macos-voice-io and is automatically built on first launch.

Linux / Windows

By default, half-duplex mode is used via the bundled Python audio bridge using sounddevice / PortAudio: the microphone is paused during reply playback. Enter /interrupt to stop playback manually; capture resumes after playback ends or is interrupted. Before first use, install sounddevice and the system PortAudio.

You can also enable full-duplex mode without echo cancellation:

qwenaudio tui --audio-mode full

This mode has no echo cancellation; please wear headphones to avoid misrecognition or false interruptions caused by speaker audio. Different sound cards and Bluetooth headsets have varying levels of support for simultaneous input and output streams at different sample rates; if you continuously experience input overflow, output underflow, or device errors, please exit and fall back to --audio-mode half.

Configuration

The default audio mode can also be set persistently via an environment variable:

QWEN_AUDIO_AGENT_TUI_AUDIO_MODE=half

Setting it to full is equivalent to --audio-mode full. For full parameter details, see Configuration.