DEV Community: Hamed

WaveRune: hiding a 32-bit ID inside a WAV file, and reading it back without the original

Hamed — Fri, 11 Sep 2026 16:04:36 +0000

A while ago I wanted to answer a small question about an audio file: which copy is this? Not who owns it, not whether it was tampered with, only which of several exported versions ended up in front of me. The obvious answers all had a catch. Metadata tags disappear the moment someone re-exports the file. Fingerprinting tells you what a recording is, not which copy. Comparing against the original needs the original, and the whole point was that I did not have it at the time I was asking.

So I built WaveRune. It embeds a 32-bit identifier inside the audio itself, and it reads the identifier back using only a key. The original recording is not needed for detection. It is a TypeScript library with zero runtime dependencies, a command-line tool, and a browser demo that never uploads your file.

This post is a tour of what it does, how the signal processing works in plain terms, and what I measured. That last part matters more than the rest. Watermarking libraries tend to promise a lot, and I would rather show you the failure cases up front.

Repository: https://github.com/hamedniroomand/waverune
Live demo: https://hamedniroomand.github.io/waverune/
Package: npm install waverune

Thirty seconds with the CLI

Install it globally, or run it through npx:

npm install -g waverune

Embed the identifier 42 into a WAV file with a key of your choice:

waverune embed input.wav -o marked.wav --id 42 --key my-secret-key

Wrote the watermark to "marked.wav".
Requested id: 42
Recovered id: 42
Correlation score: 0.176
SNR: 23.69 dB
MSE: 5.3213e-5
PSNR: 34.33 dB

Notice that embed did not stop at writing the file. It read marked.wav back from disk and ran detection on it, so the "Recovered id" line is a real check on the saved bytes. If that check fails, the command keeps the file for inspection and exits with code 3 instead of pretending it worked.

Now detect, with only the file and the key:

waverune detect marked.wav --key my-secret-key

Watermark found. Id: 42
Correlation score: 0.176

And with the wrong key:

waverune detect marked.wav --key wrong-key

No watermark found.

That run exits with code 2, which is useful in scripts. Add --json to any command to get the full result as one line of JSON, including the diagnostics I describe further down.

If you do not want a JavaScript runtime at all, there are standalone executables for macOS, Linux and Windows on the releases page, with an install script that checks the SHA-256 before it puts anything on your PATH.

The library

The functional API is four calls. Read a file, embed, write, detect:

import { detect, embed, readWavFile, writeWavFile } from 'waverune';

const key = 'my-watermark-key';
const payload = 42n;

const original = await readWavFile('input.wav');
const marked = embed(original, { key, payload });
await writeWavFile('marked.wav', marked);

const saved = await readWavFile('marked.wav');
const result = detect(saved, { key });

if (result.detected && result.payload === payload) {
  console.log('Verified:', result.payload.toString());
}

The payload is a bigint in the range 0 to 4294967295. embed returns a new buffer and leaves the input alone. If you already have bytes in memory, decodeWav and encodeWav work on Uint8Array, which is what the browser demo uses. The codec handles 16, 24 and 32-bit PCM and 32-bit float.

Everything runs on Node.js 22 or later and on Bun. There is no native addon, no model download and no network call anywhere in the package.

How the data gets into the sound

I want to explain this properly, because "it hides data in the audio" is not an explanation. The approach is classical spread-spectrum watermarking in the frequency domain. Nothing here is new research. The work was in choosing parameters that hold up on real recordings and in writing an honest acceptance rule.

Framing. The signal is analysed in overlapping windows of about 46 milliseconds, moving forward 10 milliseconds at a time. Both values are set in seconds rather than samples, so the frame grid is the same at 44.1 and 48 kHz.

The band. The payload is spread across 500 to 5000 Hz, divided into 48 frequency slots of equal width. That band survives most things people do to audio, and it stays clear of the very low end where a small change is easy to hear.

A masking threshold. For every frame and every slot, the embedder computes how much it is allowed to change the magnitude. The rule is simple: take the energy of the strongest neighbouring slot, let it spread at 10 dB per slot, then drop 14 dB below that. Frames quieter than 5% of the loudest frame carry nothing at all. I want to be clear that this is a simplified spreading model, not a calibrated psychoacoustic one. Staying under it is not proof that the change is inaudible.

Embedding. A pseudo-random sequence derived from the key assigns each spectral cell a sign and a bit position. The embedder nudges each cell's magnitude up or down by a fraction of its threshold, according to the bit it carries. Because the analysis windows overlap, one analysis-and-synthesis pass only delivers part of the intended change, so the embedder runs eight passes, each one re-analysing the previous output.

Detection. The detector analyses the candidate file the same way, then removes the host audio statistically. It whitens each frame against its own slots and each slot against its average over the file, and it weights every cell by the inverse of its local residual power so a drum hit or a plosive does not dominate the correlation. Then it correlates against the keyed sequence for every possible block position and for eight sub-hop sample shifts, and keeps the alignment that agrees best with a sync pattern. This is why the original is not needed: the key regenerates the sequence, and the whitening step does the job the original would have done.

What "detected" means. The payload lives in a 1.5 second block along with a 16-bit sync pattern and an 8-bit checksum, and the block repeats for the length of the file. Acceptance is exact and deterministic. All 16 sync bits must match, and the 8 checksum bits must match the checksum of the decoded payload bits, at the chosen alignment. There is no correlation threshold to tune. If the rule fails, detected is false, payload is null, and the raw decoded bits are exposed as a diagnostic so you can see what the detector was looking at.

The correlation score you saw in the CLI output is diagnostic only. Unmarked audio scores about 0.05, with 0.083 the highest value seen across 585 unmarked, wrong-key and silent trials. The clean embed above scored 0.176, and digital silence scores exactly 0. The score plays no part in the accept or reject decision. I made that choice after an earlier detector accepted a wrong payload on a real-audio excerpt, and I did not want a tunable number standing between the user and a clear answer.

The browser demo

The demo is the same library bundled for the browser. Choose a WAV file, type a key, and either embed a new identifier or detect an existing one. Processing happens on your machine. The page has no backend, and there is nothing to upload to.

After an embed, the results panel shows the original and the watermarked audio side by side for listening, the recovered identifier, the sync and checksum outcomes, how many frames were active, and a download button for the marked file.

The demo caps files at 120 seconds because the work happens on the main thread and a long stereo file can pause the page for a while. The library and the CLI have no such cap.

What I measured, and where it fails

Every number in the README comes from a reproducible benchmark run, and the reliability report in the repository lists the inputs, commands and per-file results. These are the results for the current detector on the test sets I have. They are not guarantees for your audio.

Test set	Result
Clean synthetic audio, 20 key and payload pairs on each of two fixtures	40 of 40 exact
The same trials after a 16-bit WAV round trip	40 of 40 exact
Sample-rate conversions through macOS Core Audio	50 of 50 exact
Clean recorded audio, three pairs across nine files	24 of 27 exact
Prefix removal on eligible recorded files	119 of 119 exact
Recorded excerpts of 5 seconds or less	115 of 329 exact
Rejection trials with unmarked audio, wrong keys and silence	0 acceptances in 585

The line I want you to read twice is the excerpt one. Short clips are where this breaks. The block is 1.5 seconds long and the detector wants to see it repeat, so a clip under about three seconds rarely recovers on recorded audio. On the recorded corpus the clean full-length recovery rate is 24 of 27, not 27 of 27, and the three misses happened on ordinary recordings, not on synthetic edge cases.

A few more things it does not do:

It is WAV only. MP3, AAC and Opus are out of scope. The transform coding in those formats does its own thing to the spectrum, and I have not measured survival through it.
Audibility has not been validated by listening tests. The masking model is simplified. Some spectral cells exceed its threshold in the measurements. The SNR figures from waverune metrics are a number, not an opinion about how it sounds.
A watermark is not proof of ownership. Anyone who has the key can embed one that passes. The checksum protects against decoding errors. It does not authenticate anything.
False acceptance is possible in principle. No wrong payload was accepted in the 585 rejection trials for the current detector. A finite test set does not establish a rate, and the previous detector did accept one, which is the whole reason the acceptance rule is now exact.

If you try it on your own recordings and something fails, the most useful thing you can send me is a reproduction: duration, sample rate, bit depth, channel count, the command you ran, and what you did to the audio between embed and detect. Use a throwaway key. The contributing guide in the repo has the full list.

Why I published it anyway

There are commercial watermarking systems that do more than this, and there are research models that survive far harsher attacks. WaveRune is not competing with those. It is a small, readable implementation of the classical approach, with a test matrix that says exactly what it can and cannot do, and no dependency you have to audit.

If you need to tell copies of a WAV file apart in a pipeline you control, it does that job today. If you want to learn how spread-spectrum audio watermarking works by reading code instead of papers, the source is short enough to read in an afternoon, and every non-obvious signal-processing step has a comment explaining why it is there.

The repository is at https://github.com/hamedniroomand/waverune, under the MIT licence. Try the demo, break it, and tell me how.

Browser first: the one rule behind every tool on KitDev Space

Hamed — Sun, 06 Sep 2026 22:30:42 +0000

A while ago I caught myself pasting a JWT from a production API into the first "JWT decoder" Google gave me. I wanted to read the claims. I didn't stop to think about where the token went, and honestly, neither does anyone else. We do the same with .env files in JSON converters and with photos in EXIF strippers. The site has a privacy policy that says the server keeps nothing, and we take its word for it.

That moment is roughly why KitDev Space exists. I wanted a set of everyday developer tools where I didn't have to take anyone's word for it, including my own. The way I got there was less about the tools and more about one rule I wrote down early and then refused to bend. This post is about that rule.

The rule

Run the work in the browser. Use a server only when the browser genuinely can't do the job.

The first half is easy to agree with. The second half is where it gets interesting, because "can't" has to mean something concrete or every tool ends up on the server for convenience. So I wrote down the situations that actually qualify, and the list ended up shorter than I expected:

The work needs a native library. Encoding AVIF or rasterizing an SVG needs a real image codec. Opening a TLS handshake needs a socket.
The work needs to talk to another host. DNS records, HTTP headers, RDAP, OpenGraph previews. The browser can't make those requests because of CORS, and it shouldn't be able to.
The work needs a runtime API with no browser equivalent, like Bun.dns or Bun.Archive.
The input is too large for a browser tab to hold comfortably.

If a tool doesn't hit one of those, it stays in the browser. I've been tempted to make exceptions a few times, usually when the server version would have been twenty lines and the browser version two hundred. I haven't yet.

The browser does more than I gave it credit for

Going in, I assumed I'd be writing a lot of server code. I was wrong about that. Most of what a developer tool site does is already covered by platform APIs or by a small dependency that runs fine in a tab.

Work	What handles it in the browser
SHA-1, SHA-256, SHA-384, SHA-512	`crypto.subtle.digest`
Random bytes, UUIDs	`crypto.getRandomValues`
AES-256-GCM, PBKDF2, HMAC	`crypto.subtle`
Resize, rotate, crop	`OffscreenCanvas`, `createImageBitmap`
JPEG, PNG, WebP encode	`OffscreenCanvas.convertToBlob`
Reading EXIF and GPS metadata	a `DataView` over the file bytes
Gzip, deflate, tar	`fflate`
YAML, TOML, JSONC, JSON5	`confbox`
SQLite	`sql.js` (WebAssembly)

So the JWT debugger verifies HS256 signatures with Web Crypto and never sees a server. The AES tool derives its key with PBKDF2 in your tab. The tar explorer opens an archive without uploading it. The SQLite studio runs an actual database in memory. None of that required anything clever, just a willingness to check what the platform already had before reaching for a route.

Web Crypto does have gaps. There's no MD5, no CRC32, no xxHash. I could have pulled in a JavaScript MD5 library and kept everything client side, but the hash tool also offers xxhash64 and wyhash, and shipping all of that to the browser for algorithms most people rarely use felt wrong. So the hash generator keeps a server path for those, and the page says so in plain words when you pick one. I'd rather tell you which option leaves your machine than pretend nothing does.

One module, two paths

A tool with both a browser path and a server path is a maintenance trap waiting to happen. Two implementations, one of them quietly drifts, and now the same input gives different output depending on where it ran. I got bitten by exactly this on the data converter early on.

The fix I settled on: each shared module exports the function that does the work plus a small guard that answers "can this run here?". The page checks the guard. The server route imports the same module. The code that actually hashes a file exists once.

// shared/utils/crypto/hash.ts
const SUBTLE_NAMES = {
  sha1: 'SHA-1',
  sha256: 'SHA-256',
  sha384: 'SHA-384',
  sha512: 'SHA-512'
}

export function canHashInBrowser(algorithm: HashAlgorithm): boolean {
  return algorithm in SUBTLE_NAMES
}

// simplified page logic
const result = canHashInBrowser(algorithm)
  ? await hashInBrowser(input, algorithm)
  : await $fetch('/api/hash', { method: 'POST', body: { input, algorithm } })

Hashing, data format conversion, code formatting and semver all use this shape now. When a new tool needs both paths, it gets the same treatment, and I don't have to think about it anymore.

What the server is actually for

The tools that do need a server run on Bun. Each one is there because of one of the four reasons above, and I can tell you which:

The TLS Certificate Inspector opens a socket and reads the chain, the SANs and the cipher suite.
DNS Lookup and the Email Health Inspector query A, MX, TXT, SPF, DKIM and DMARC records.
The HTTP Inspector, OpenGraph Previewer and RDAP Lookup all fetch from a third-party host.
Image Studio and the Favicon Set Generator use Bun.Image for AVIF and ICO output.
The TS/JSX Transpiler and the AST Playground run OXC, which is native code.

Because every server route is a liability, they all go through the same checklist before they ship. Validate the URL and allow only http and https. Block localhost, private ranges, link-local, cloud metadata hosts, and the IPv6 transition ranges that smuggle an IPv4 address inside (I learned about NAT64 and Teredo the hard way while writing that blocklist). Restrict the destination port, so the TLS inspector can't be turned into a port scanner. Check content-length, then stream the body and stop at a cap instead of buffering it. Rate-limit by a client key that isn't derived from x-forwarded-for, since anyone can set that header. Keep uploads in memory and never touch the disk. And store no input and no output, period.

Analytics follows the same idea. An event carries the tool id and nothing else. I can see that someone opened the cron visualizer today. I have no idea what expression they typed, and I like it that way.

Making the rule visible

A rule that only I know about isn't a privacy feature. It's a promise. So the sidebar shows where each tool runs.

Every tool has a small badge next to its name. 🔒 Client means nothing on that page calls the server. ⚡ Bun means every action does. A tool with both paths shows no badge, and the page itself explains which action leaves the browser. The badge isn't something I type by hand, either. It comes from two flags in the tool registry, the same registry that generates the page title and the search index, so it can't drift out of sync with the code.

And the code is public. KitDev Space is open source under the MIT license, and the repository is linked from the site footer. If a badge says Client, you don't have to trust the badge. You can open the tool's module and see for yourself that nothing in it calls a server. That was the last piece of the "don't take my word for it" idea, and honestly the part I should have done first.

What's in there

New tools land most weeks, so I won't give you a count. Here are the ones I open most often, by category.

Data: a JSON formatter that accepts JSON5 and JSONC, JSON to TypeScript, converters between YAML, TOML, XML and CSV (including CSV to SQL inserts), a table viewer for large CSVs, and the SQLite studio.

Dev: a regex tester that explains each token, a cron visualizer that shows the next runs, cURL to fetch/Axios/Python/Go, HTML and SVG to JSX or Vue, a glob tester, and the tar explorer.

Network: TLS inspector, DNS lookup, email health check, HTTP header inspector, CIDR calculator, cookie inspector, RDAP lookup.

Crypto: hash generator, HMAC, JWT debugger, TOTP generator, AES encrypt and decrypt, UUID and passphrase generators.

Color: an OKLCH converter, a WCAG contrast checker, a Tailwind shade generator, a CSS gradient studio, and palette extraction from an image.

Image: crop, resize, rotate and convert in one pass, an EXIF inspector and remover, SVG to PNG or WebP at 1x/2x/4x, and a favicon set generator that hands you a ZIP.

There's no account, no paywall, and the whole thing is open source. The site follows your system color scheme, so you won't have to hunt for a toggle.

Under the hood

Nuxt 4 and Nuxt UI 4 on the front end, VueUse for composables, CodeMirror for the editors, Bun for the server routes, Vitest and Playwright for tests, deployed on Vercel. Nothing exotic.

I'd like your help

If you try kitdev.space, I have two requests. Tell me which tool you wanted and couldn't find. And if you ever catch a tool sending something to the server that should have stayed in your browser, tell me that first. It would mean the rule has a hole, and I'd want to know.

The repository is one click away from the footer. Issues and pull requests are welcome, whether it's a new tool, a fix, or just a note that a badge is wrong. A tool hub like this gets better with more hands on it, which is the main reason I opened the source.

If you build tools of your own, take the rule with you. Write down the handful of cases where the browser truly can't do the work. Everything else belongs on the user's machine.