WinUI communicates with its private Rust Native Host process over standard input and output. The current protocol version is 1.
Channel contract
stdinandstdoutcarry newline-delimited JSON.stdoutcontains protocol responses and events only; logs go tostderr.- Requests include
protocolVersion; responses carry the request ID. - Startup begins with a handshake for host version, session, capabilities, and data location.
- Invalid versions, arguments, and messages return explicit errors rather than silently succeeding.
Client message types live in Core/Protocol/HostMessages.cs, transport in Core/Transport/StdioHostTransport.cs, and the host implementation in src-tauri/src/native_host.rs.
Gate behavior by capability
The handshake’s capabilities describe what the connected host actually offers. Verify connection and required capability before exposing an operation. A visible window or known command name is insufficient. Playback and queue state have one authority in the native host; the shell, immersive view, and capsule share it.
Events and reconnection
| Event | Meaning |
|---|---|
playback.changed |
Playback state changed |
playback.progress |
Playback position |
playback.meter |
Audio level |
playback.ended |
Current track ended |
session.changed |
Session state changed |
import.progress |
Import progress |
storage.watch-changed |
Scan-folder change |
Events carry a sessionId and increasing seq. After reconnecting, discard events from the old session. High-frequency progress and meter updates can be coalesced, but stop, end, and other critical transitions must not be lost.
A timeout is an unknown outcome
A timed-out play, seek, import, or write may already have happened. Read the current state and confirm the result before considering another request; do not automatically repeat an operation with side effects. When disconnected, mark the operation unavailable instead of assuming the old host remains active.
The host requires an explicit data directory and holds an exclusive cross-process lock. Production directories have additional protection. Shut down with stdin EOF or host_shutdown; force termination is a last resort. Pairing and sync recovery have their own persistent state and do not imply resuming an old playback transaction.
Test version mismatches, invalid arguments, response matching, late events, host exits, and unknown write outcomes. Then run real-process protocol tests and validate the native UI. A command inventory alone does not establish feature completion.