57 lines
2.7 KiB
Markdown
57 lines
2.7 KiB
Markdown
# Daemon Socket Protocol
|
|
|
|
Toak uses a lightweight, custom Unix Domain Socket protocol for IPC (Inter-Process Communication). This allows front-end short-lived CLI tools (like `toak toggle`) to execute instantly while the persistent state and API operations happen inside the background daemon (`toak daemon`).
|
|
|
|
## Connection
|
|
|
|
The UNIX domain socket is typically located at:
|
|
`$XDG_RUNTIME_DIR/toak.sock` (falls back to `/tmp/toak.sock` if `$XDG_RUNTIME_DIR` is not set).
|
|
|
|
## Message Format
|
|
|
|
Clients send small byte arrays to issue commands to the server. Depending on the command, the structure ranges from a single byte to a 3-byte payload containing the command ID and configuration flags for standard output handling.
|
|
|
|
### Command Bytes
|
|
|
|
| Command | Byte | Description |
|
|
|---|---|---|
|
|
| **START** | `1` | Forces the daemon to start recording. Ignored if already recording. |
|
|
| **STOP** | `2` | Forces the daemon to stop recording and begin processing the audio. Takes flags for response handling. |
|
|
| **ABORT** | `3` | Stops audio recording and discards the buffer without making API calls. |
|
|
| **TOGGLE** | `4` | Stops recording if currently recording; starts recording if currently inactive. Takes flags for response handling. |
|
|
|
|
## Payload Formats
|
|
|
|
### 1-Byte Payloads (`START`, `ABORT`)
|
|
When the client only needs to trigger state changes without receiving processing results back, it sends a single byte.
|
|
|
|
```text
|
|
[ Command Byte ]
|
|
```
|
|
Example (`ABORT`): `[ 0x03 ]`
|
|
|
|
### 3-Byte Payloads (`STOP`, `TOGGLE`)
|
|
When asking the daemon to process audio, the client can specify how it wants to receive the finalized text: typed via hotkeys (default), piped to standard output (`--pipe`), or copied to the clipboard (`--copy`).
|
|
|
|
The client sends exactly 3 bytes:
|
|
```text
|
|
[ Command Byte ] [ Pipe Flag ] [ Copy Flag ]
|
|
```
|
|
|
|
- **Byte 0:** The command (`0x02` or `0x04`)
|
|
- **Byte 1:** Pipe to Stdout: `0x01` if enabled, `0x00` if disabled.
|
|
- **Byte 2:** Copy to Clipboard: `0x01` if enabled, `0x00` if disabled.
|
|
|
|
Example (`TOGGLE` with stdout piping enabled): `[ 0x04, 0x01, 0x00 ]`
|
|
|
|
## Server Responses
|
|
|
|
Depending on the flags provided in a 3-Byte Payload:
|
|
|
|
1. **Default (No flags set):**
|
|
The server will process the audio, handle LLM modifications, and inject the text into the user's active window using Wayland (`wtype`) or X11 (`xdotool`). The socket is closed by the server.
|
|
|
|
2. **Pipe or Copy Flag Set:**
|
|
The client will keep the connection open and wait to read the incoming text from the server.
|
|
The server will stream UTF-8 encoded text chunks back to the client as the LLM generates them. The client reads these chunks and pushes them to `stdout`. Once sending is complete, the server closes the socket.
|