tuimble/docs/USAGE.md

Usage

Running

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

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:

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.

[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.

[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:

[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.