murmur

murmur

Transfer data between nearby devices using sound.

Quick start

just install    # go install ./cmd/murmur
just lint       # golangci-lint run
murmur help

murmur bench sim            # the whole link through a simulated room, no hardware
murmur bench loopback       # the same through the audio device stack, no second laptop

Does it work here?

Check the software before pointing two laptops at each other:

murmur test                     # an encode/decode round trip inside this process

Every device murmur test knows carries the samples in-process, so it needs no sound server and no hardware - it proves the software works. To prove a room does, run the real pipeline from below between the two machines.

Profiles

Two profiles share one physical layer - the same 8 ms chirp preamble and the same 32-tone non-coherent alphabet - and differ only in symbol length, which sets both the band and the rate. There is no handshake to negotiate one, so the receiver must be told the same profile the sender used; on murmur decode that is one more --profile flag.

murmur bench sim runs both through the simulated channel. Over 40 uncoded frames per preset, fast delivers 40/40 clean, 40/40 typical, 26/40 noisy and 9/40 hostile, against robust's 40/40, 40/40, 14/40 and 0/40, with no corrupt frame either way. A shorter burst spends its margin and crosses fewer dropouts; the simulator models the wide band as flat, so the real room may disagree.

Sending something

One-way: murmur encode and murmur decode. One burst after another, in the clear, with nothing sent back — not even an acknowledgement, so the sender never learns whether anyone heard it.

murmur decode is the inverse of murmur encode and never opens an audio device: raw 16-bit mono PCM at 48 kHz from standard input.

# on the receiver: capture the microphone and decode the resulting PCM
pw-record --raw --format=s16 --rate=48000 --channels=1 - | murmur decode

# on the receiver: decode a capture you already have
murmur decode < capture.raw

# on the sender, straight to a player
murmur encode key.txt | pw-play --raw --format=s16 --rate=48000 --channels=1 -
echo -n "correct horse" | murmur encode | pw-play --raw --format=s16 --rate=48000 --channels=1 -
printf '%s' "$TOKEN" | murmur encode --loudness whisper | pw-play --raw --format=s16 --rate=48000 --channels=1 -
printf '\x01' | murmur encode | pw-play --raw --format=s16 --rate=48000 --channels=1 -

# on the sender, to a file you play whenever you like
printf '\x01' | murmur encode --wav > key.wav
pw-play key.wav

What goes in. printf '%s' sends exactly the string; echo adds a trailing newline. With no file arguments murmur encode reads standard input, and a file argument reads that file; no name, mode or timestamp travels with the bytes. --wav needs a seekable output. --loudness is whisper (−30 dBFS), normal (−20, the default) or loud (−12, the hard ceiling). --profile picks the modulation and is robust (the default) or fast; both ends must name the same profile, because the receiver has to be listening for the right one. Every stream begins with 300 ms of silence so a freshly started player has time to wake.

What comes out. --one stops after the first payload. Bytes go to stdout and prose to stderr, so a redirect captures only the payload:

pw-record --raw --format=s16 --rate=48000 --channels=1 - | murmur decode > key.txt
murmur decode < capture.raw > go.mod           # a recording, decoded
pw-record --raw --format=s16 --rate=48000 --channels=1 - | murmur decode --one > byte.bin

Use as a Go library

The root package is the whole library: murmur.Payload in, murmur.Message out. murmur.Encode writes samples to any io.Writer and never plays them; murmur.Decode reads raw PCM from any io.Reader.

Receive. Feed a PCM stream to Decode and range over what arrives:

stream, err := murmur.Decode(os.Stdin) // `pw-record ... | murmur decode`
if err != nil {
	log.Fatal(err)
}
defer stream.Close()

for msg := range stream.Chan() {
	// The payload is the bytes themselves: write them wherever they go.
	os.Stdout.Write(msg.Data)
}
if err := stream.Err(); err != nil {
	log.Fatal(err)
}

Chan() closes at io.EOF or Close; only digest-checked payloads are delivered.

Send. Read the bytes, produce the sound, and write it wherever you like:

key, err := os.ReadFile("id_ed25519.pub")
if err != nil {
	log.Fatal(err)
}
err = murmur.Encode(os.Stdout, murmur.Payload{Data: key})
if err != nil {
	log.Fatal(err)
}

Raw 16-bit mono PCM at 48 kHz, or with a WAV header via WithWAV — which needs an io.WriteSeeker because the header states the length of what follows:

key, err := os.ReadFile("id_ed25519.pub")
if err != nil {
	log.Fatal(err)
}
f, err := os.Create("key.wav")
if err != nil {
	log.Fatal(err)
}
defer f.Close()
err = murmur.Encode(f, murmur.Payload{Data: key}, murmur.WithWAV())

Decode. The inverse, from any io.Reader: raw 16-bit mono PCM at 48 kHz, read until io.EOF, after which Chan closes:

stream, err := murmur.Decode(os.Stdin)
if err != nil {
	log.Fatal(err)
}
defer stream.Close()
for msg := range stream.Chan() {
	os.Stdout.Write(msg.Data)
}

Using PipeWire instead of stdin. Decode takes any io.Reader, so a program can put the microphone there itself instead of relying on a shell pipe. murmur has no sound-server code and no device for one: the seam is raw 16-bit mono PCM at 48 kHz, so the recorder is the caller's, and the easiest one to start is pw-record.

cmd := exec.Command("pw-record", "--raw", "--format=s16",
	"--rate=48000", "--channels=1", "-")
stdout, err := cmd.StdoutPipe()
if err != nil {
	log.Fatal(err)
}
if err := cmd.Start(); err != nil {
	log.Fatal(err)
}
defer cmd.Process.Kill()

stream, err := murmur.Decode(stdout) // as above: range over stream.Chan()

Name the input with --target=<node> to avoid the session manager's default, which on many laptops is an echo-cancelling virtual source:

cmd := exec.Command("pw-record", "--raw", "--format=s16",
	"--rate=48000", "--channels=1", "--target", node, "-")

Sending is the mirror image: hand the encoder's output to a player's standard input, or write a file with WithWAV and play it whenever you like. Anything that produces or consumes 48 kHz mono 16-bit PCM at a process boundary will do - pw-record and pw-play, another recorder, a saved capture, or a test harness.

Options. Decode and Encode share the options that matter to both; WithWAV applies only to Encode. A different modulation profile:

stream, err := murmur.Decode(os.Stdin, murmur.WithScheme(scheme))

Notes for problems that did not stop reception; the callback runs on the receiving goroutine, so keep it quick and do not block in it:

stream, err := murmur.Decode(os.Stdin, murmur.WithNotes(func(err error) {
	log.Printf("murmur: %v", err)
}))

Exported underneath for a different stack: pkg/modulation, pkg/link, pkg/mac, pkg/fec, pkg/audio.