ham-parrot

Voice keyer for ham radio contests. Runs as a long-lived CLI: proxies your microphone straight to the radio the whole time, and when you press Enter it plays back a pre-recorded voice sequence over the air (keying PTT via Hamlib rigctld) so you don't have to shout the same CQ / exchange fifty times an hour.

Install

pipx install ham-parrot
# or, for development:
poetry install

Use

ham-parrot \
    --mic-device "USB Audio" \
    --radio-audio-device "USB Audio" \
    --monitor-enable --monitor-device "MacBook Pro Speakers" \
    --hamlib-ptt localhost:4532 \
    --mic-passthrough-level 100 \
    --playback-level 90 \
    --eq-json eq_examples/ssb.json

Keys, while running:

• r — start recording your voice sequence (mic is muted from the air while recording so you don't stomp on yourself). Press r again to stop; the file is saved as ./recording.wav and a filtered companion ./recording_eq.wav is rendered next to it.
• Enter — key PTT, play the recording over the radio (and to your monitor device, if enabled), release PTT.
• p — toggle a 1 kHz pilot tone (PTT-keyed) at --playback-level. Useful for setting mic drive on the radio.
• q or Ctrl-C — quit.

recording.wav in the current directory is auto-loaded on startup, so a contest run is: record once, then hit Enter every time you need it. If the radio is already transmitting (PTT reads high on rigctld) when you hit Enter or p, the action is refused so you don't collide with an ongoing over.

Flags

Audio processing

Everything sent to the radio (mic passthrough, playback, pilot) goes through the same chain:

• Butterworth bandpass 100 Hz – 4 kHz (4th order per edge → ~48 dB/octave rolloff), always on.
• Optional 17-band peaking EQ on the ISO 1/3-octave centres, controlled by --eq-json.
• Hard-clip at ±1.0 after gain + filter so overshoots don't wrap into artefacts.

recording.wav is captured raw (pre-gain, pre-filter) so you can change --eq-json between runs without re-recording. recording_eq.wav is a filtered snapshot re-rendered on every startup and every stop-recording — use it in VLC / any other player to hear the on-air version. Playback prefers the pre-rendered file so the IIR chain doesn't run over every playback sample.

Diagnostics

• The banner at startup prints the resolved audio targets (mic, radio, monitor) so you can verify device routing before pressing anything.
• A rate-limited mic clipping (peak=X.XXX) line is printed to stdout whenever the raw mic hits the ADC ceiling — back off the mic or lower input gain on the interface.
• paplay / parec stderr is captured in log.txt so silent-death of the subprocess doesn't stay silent.

Device hints accept: a substring of the OS device name ("USB Audio"), a numeric index (from pactl list short sinks on Linux, or sounddevice's device list elsewhere), or pulse:<name> to force the Pulse path.

License

MIT. See LICENSE.