🏴‍☠️ parley

"Ye speak, and the wee gremlins in the machine scribble it down. That be the whole of it, savvy?"

parley be a voice-to-text dictation pipeline for them as would rather speak their piece than peck at the keys like a gull at a biscuit. Ye press a key, ye talk, ye press again, and parley hauls yer words up from the deep with whisper.cpp, tidies the punctuation, lets ye fix any barnacles in yer editor, and spits clean text out the other end.

It also carries a Claude Code skill, so /parley in any session lets ye dictate yer next message instead o' typin' it.

🪝 The hook

The name be no accident. Parley be the pirate's word for "to speak" (from the French parler), the truce-talk ye invoke when ye'd sooner use yer tongue than yer cutlass. So that's what this be: ye parley with the machine. Ye run parley, ye say yer piece, and the Code o' the Brethren says it must hear ye out.

☠️ What's in the hold

• parley, the shell pipeline: record (PipeWire) → transcribe (whisper.cpp) → spoken-punctuation cleanup → edit → print.
• lib/punctuation.sh, a pure filter that turns spoken punctuation into symbols ("exclamation point" becomes !, "ellipsis" becomes ..., and so on). Testable on its lonesome.
• skill/parley.md, the Claude Code /parley skill.

Two ways to transcribe, picked automatic:

• Local: if whisper-cli and a model be aboard, parley runs on yer own iron (GPU if ye've got it). ❌ No network, ❌ no eavesdroppers.
• Server: otherwise it POSTs the audio to a whisper-server ye point it at with PARLEY_SERVER.

⚠️ PARLEY_SERVER must include the /inference route — the full endpoint, not just host:port. whisper.cpp's whisper-server serves transcription at /inference, and parley POSTs straight to the URL ye give it. Point it at the bare http://host:9000 and curl -f gets a rejection from the server root, and ye'll see the maddeningly-vague transcription request … failed.

# ✅ right — full route
export PARLEY_SERVER=http://example.com:9000/inference
# ❌ wrong — no /inference, fails at the root
export PARLEY_SERVER=http://example.com:9000

Running a whisper-server on another box on yer tailnet (or LAN) and pointin' every other machine at it is the fastest way to a working parley — no local build, no model download. Just mind the route.

🛢️ Provisions (prerequisites)

• pw-record (PipeWire) for capturin' yer voice
• an editor ($EDITOR, else vi)
• curl (only for server mode)
• whisper.cpp: either whisper-cli plus a model locally, or a whisper-server ye can reach

⚓ Comin' aboard (install)

git clone https://github.com/BlueFenixProductions/parley.git
cd parley
./install.sh

That drops parley on yer PATH, stows the punctuation lib, installs the /parley skill, and seeds ~/.config/parley from the examples (it'll never clobber config ye've already set, on me honor).

🧭 Settin' yer course (config)

parley reads, in order, first to answer wins:

1. environment variables (PARLEY_*)
2. ~/.config/parley/config (sourced shell)
3. built-in defaults

Setting	What it steers	Default
PARLEY_SERVER	whisper-server endpoint (server mode)	(unset; local-only)
PARLEY_MODEL	local whisper.cpp model file	~/whisper-models/ggml-medium.bin
PARLEY_VOCAB	proper-noun / jargon vocab file	~/.config/parley/vocabulary.txt
PARLEY_MIC	PipeWire node-name substring to target a mic	(unset; default source)
PARLEY_LANG	transcription language	en
PARLEY_EDITOR	editor for the transcript	$EDITOR, else vi

The vocabulary file be plain text, one term or comma-separated terms to a line, # for comments. Feed it yer crew's names and yer jargon so whisper spells 'em right instead o' guessin'.

⛵ Sailin' her (usage)

$ parley
Press any key to start recording...
● ON AIR... (press any key to stop)
Transcribing...

# yer editor opens on the transcript; fix any barnacles, save & quit
# clean text prints to stdout

Speak yer punctuation out loud and parley sets it for ye: say "make it so period" and ye get make it so. Say "where be the rum question mark" and ye get where be the rum?

In Claude Code, type /parley, run parley in a terminal as it bids ye, and paste the transcript back as yer next message.

🐙 The Kraken test ☠️

Every seaworthy vessel gets a shakedown, and ❌ marks the spot where ours be buried. 'Tis the finest line ever bellowed across a deck, and it just so happens to drill the punctuation engine through !, the dread doubled !!, and the ... all at once:

"Let no joyful voice be heard! Let no man look to the sky with hope! And let this day be cursed by we who ready to wake... the Kraken!!"

Spoken aloud (punctuation and all), that be:

"Let no joyful voice be heard exclamation point Let no man look to the sky with hope exclamation point And let this day be cursed by we who ready to wake ellipsis the Kraken exclamation point exclamation point"

...and parley raises it back, properly punctuated, every time. 'Tis hella fun to say, and if she passes this, she'll pass anything. Run the suite:

./test/bats/bin/bats test/

(Tests run on bats, vendored as a submodule. After cloning, fetch it with git submodule update --init --recursive.)

🗺️ The lineage, honest and true

parley be naught but a friendly bosun atop better souls' work:

• The engine be whisper.cpp by Georgi Gerganov and the ggml authors (MIT). Not OpenAI's code.
• The model weights it loads be OpenAI's Whisper, converted to ggml format.

So "whisper" in these waters means the Whisper model lineage, naught more. No affiliation flown false.

⚔️ Colors (license)

MIT. 🪙 Hoist it, fork it, sail it where ye please. See LICENSE.

---

A Blue Fenix Productions vessel. Fair winds and following seas. 🦜🏴‍☠️