2533e43391
F6/F7 keybindings, audio.pitch config option, voice pitch section in USAGE.md. Updated profiling notes to reflect per-thread coverage.
122 lines
3.3 KiB
Markdown
122 lines
3.3 KiB
Markdown
# Usage
|
|
|
|
## Running
|
|
|
|
```sh
|
|
tuimble # uses ~/.config/tuimble/config.toml
|
|
tuimble --host mumble.example.com --user myname
|
|
```
|
|
|
|
## Key Bindings
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `Tab` | Cycle focus (chat input / channel tree) |
|
|
| `F1` | Toggle self-deafen |
|
|
| `F2` | Cycle output volume |
|
|
| `F3` | Cycle input volume |
|
|
| `F4` | Push-to-talk (configurable) |
|
|
| `F5` | Reload config from disk |
|
|
| `F6` | Pitch down (1 semitone) |
|
|
| `F7` | Pitch up (1 semitone) |
|
|
| `Enter` | Send message / join channel (sidebar) |
|
|
| `Up` | Previous message (input) / previous channel (sidebar) |
|
|
| `Down` | Next message (input) / next channel (sidebar) |
|
|
| `q` | Quit |
|
|
| `Ctrl+C` | Quit |
|
|
|
|
## Push-to-Talk Modes
|
|
|
|
- **toggle** — press to start, press again to stop (default)
|
|
- **hold** — hold key to transmit, release to stop (requires evdev)
|
|
|
|
## Profiling
|
|
|
|
```sh
|
|
tuimble --cprofile # saves to ~/.config/tuimble/profile.prof
|
|
tuimble --cprofile /tmp/tuimble.prof # saves to custom path
|
|
```
|
|
|
|
Profile data is dumped every 30 seconds and on exit, so snapshots
|
|
are available even after a crash or `kill`. Output is standard `.prof`
|
|
format:
|
|
|
|
```sh
|
|
python3 -m pstats /tmp/tuimble.prof # interactive explorer
|
|
# or install snakeviz for a browser-based flamegraph:
|
|
# pip install snakeviz && snakeviz /tmp/tuimble.prof
|
|
```
|
|
|
|
Profiling covers both the main thread and all worker threads
|
|
(including the audio send loop where pitch shifting runs).
|
|
|
|
## Volume Control
|
|
|
|
`F2` and `F3` cycle through volume steps: 0%, 25%, 50%, 75%, 100%,
|
|
125%, 150%, 200%, then back to 0%. Volume is shown in the status bar
|
|
as block indicators.
|
|
|
|
```toml
|
|
[audio]
|
|
output_gain = 0.75 # 0.0 to 2.0 (default 1.0)
|
|
input_gain = 1.5 # 0.0 to 2.0 (default 1.0)
|
|
```
|
|
|
|
## Voice Pitch
|
|
|
|
`F6` and `F7` adjust outgoing voice pitch in 1-semitone steps,
|
|
ranging from -12 to +12. Negative values make the voice deeper,
|
|
positive values make it higher. The current setting is shown in the
|
|
status bar when non-zero.
|
|
|
|
```toml
|
|
[audio]
|
|
pitch = 3 # semitones, -12 to +12 (default 0)
|
|
```
|
|
|
|
When pitch is 0, the processing step is skipped entirely (no CPU
|
|
overhead).
|
|
|
|
## Client Certificates
|
|
|
|
For servers requiring client certificate authentication:
|
|
|
|
```toml
|
|
[server]
|
|
certfile = "/path/to/client-cert.pem"
|
|
keyfile = "/path/to/client-key.pem"
|
|
```
|
|
|
|
Both must be PEM-encoded. Leave empty to connect without a certificate.
|
|
|
|
## Config Reload
|
|
|
|
`F5` reloads `~/.config/tuimble/config.toml` from disk.
|
|
|
|
**Safe changes** (applied immediately): PTT key/mode/backend, audio
|
|
gain values, pitch.
|
|
|
|
**Restart-requiring changes** (server settings, audio device/rate):
|
|
shown as warnings. Press `F5` again to confirm reconnect, or any
|
|
other key to cancel.
|
|
|
|
## Reconnection
|
|
|
|
On unexpected disconnect (server restart, network loss), tuimble
|
|
automatically retries with exponential backoff:
|
|
|
|
- Initial delay: 2 seconds, doubling each attempt (2, 4, 8, 16, 30...)
|
|
- Maximum delay: 30 seconds
|
|
- Maximum attempts: 10
|
|
|
|
The status bar shows `◐ reconnecting` during retry. If the server
|
|
rejects authentication, retries stop immediately.
|
|
|
|
After all attempts are exhausted, press `F5` to retry manually.
|
|
`F5` also cancels an in-progress reconnect and starts a fresh attempt.
|
|
|
|
## Configuration
|
|
|
|
See `~/.config/tuimble/config.toml`. All fields are optional;
|
|
defaults connect to localhost:64738.
|