whisper-node

I wrote the actual complaint that started this one straight into the README, because it's true and I didn't see a reason to soften it: most Whisper Node packages are poorly maintained or require complex setup. Speech-to-text is a solved problem, technically: Whisper is a genuinely excellent model, faster-whisper is a genuinely excellent optimized implementation of it, and the gap isn't the model. It's that wrapping a Python-native ML model cleanly for a Node project, across three operating systems, without asking the person installing your package to fight a dependency chain first, is a real amount of unglamorous work that most small wrapper packages skip.

whisper-node tries to skip less of it than most. It looks for a prebuilt faster-whisper binary first (spawned as a child process with the right CLI flags for your requested model size and options), and falls back to an inline Python script, invoked directly via spawn("python", ["-c", script]), calling faster_whisper.WhisperModel if no binary is present. Two paths to the same result, so a missing binary doesn't mean a missing feature, just a slower fallback.

What it actually returns

transcribe(filePath, options) gives you back {text, language, segments, duration}: the full text, the detected language, timestamped segments if you want them, and how long the audio was. It supports the full range of Whisper model sizes from tiny up through large-v3, word-level timestamps if you need that granularity, a configurable beam size for the search, and both transcription and translation modes, since Whisper can translate non-English speech directly to English text as part of the same pass. There are also two small utility exports, binaryExists() and getBinaryPath(), so calling code can check ahead of time which path it's about to take instead of finding out implicitly when transcription either runs fast or runs slow.

The part I have to be completely honest about

The postinstall script, scripts/download-binary.js, is supposed to fetch a prebuilt binary from GitHub releases the moment you npm install the package, so the fast path is available immediately without anyone touching Python. It hits real, correctly-formed GitHub release URLs. The actual download logic underneath that request is a stub. There's a comment in the source that says, plainly, this is a placeholder so the postinstall doesn't fail: no real binaries are hosted yet. Which means, as of right now, every single install of this package silently falls through to the Python fallback path, regardless of platform, regardless of what the README's "no complex setup" pitch implies.

I left that comment in on purpose rather than deleting it and pretending the binary path was finished. It's the most honest line in the whole package, and I'd rather someone reading the source find a clear explanation of exactly where the gap is than infer, from a postinstall script that runs without error, that binaries actually exist when they don't. The Windows, macOS, and Linux binary-path resolution logic is all real and ready: it knows exactly where to look for a binary on each platform, it's just currently looking for something that was never actually shipped.

Why the Python fallback isn't a failure state, exactly

I built the fallback first, functionally, and always intended the binary path as the optimization layered on top later: faster startup, no Python dependency, a smoother install for anyone who doesn't already have a Python environment set up. That optimization hasn't shipped yet. What has shipped is a fully working Python-backed transcription pipeline that does everything the API promises, just with a Python process spinning up under the hood instead of a lean native binary. For my own use, that's been entirely sufficient: I already have Python installed for a dozen other reasons, so the "complex setup" the README promises to avoid was never actually complex for me personally, even though it currently doesn't hold for someone installing this fresh with no Python on their machine at all.

That's the gap between the pitch and the current reality, stated as plainly as I can: the package works, today, for anyone with Python available. It doesn't yet deliver the zero-dependency, binary-only experience the README implies is the whole point.

What finishing this actually looks like

Hosting real prebuilt binaries, for faster-whisper specifically, across Windows, macOS, and Linux, and wiring the download logic in download-binary.js to actually fetch and extract them instead of logging a placeholder message. That's the entire remaining gap between where this package is and where the README says it already is. It's not a redesign. The architecture, the fallback logic, the API surface, all of that is done and works. It's specifically the binary distribution pipeline that's unfinished, and I know exactly what closing it requires, I just haven't spent the afternoon on it yet.

Where it fits

Anywhere I want spoken input turned into text without sending audio to a cloud API: early voice-interaction experiments, transcribing something quickly without uploading it anywhere. Paired with kokoro-js for the output side, this is half of a fully local voice loop: speech in through whisper-node, text out through kokoro-js, nothing leaving the machine in either direction. Neither half is finished to the standard I'd call production-ready. Both do the actual job, today, honestly, with the rough edges named instead of hidden.

Why I built the fallback first instead of the binary path first

Building the Python fallback before the binary distribution pipeline wasn't laziness; it was sequencing the risk correctly. The Python path only needed me to get the actual transcription logic right: the right faster-whisper parameters, the right way to spawn and read from the subprocess, the right shape for the returned result. The binary path adds an entirely separate problem on top of that: hosting real, correctly-built binaries for three operating systems, versioning them, handling the download and extraction reliably across different network conditions and permission setups. Getting the core transcription logic right first, with the simpler of the two delivery mechanisms, meant I had something genuinely working to test against before taking on the more failure-prone infrastructure work of binary distribution. If I'd built the binary pipeline first and gotten the transcription logic wrong, I'd have been debugging two hard problems at once instead of one at a time.

What "no complex setup" was actually promising, and what it costs to keep that promise honest

The pitch line in the README is aspirational in a way I've already admitted, but it's worth being specific about exactly what closing that gap requires, because it's not vague future work: it's three concrete tasks. Build faster-whisper into a standalone binary for Windows, macOS, and Linux, each with their own build toolchain quirks. Host those binaries somewhere reliable, versioned against the package's own version so an update doesn't silently break someone's install. Wire download-binary.js's stub into an actual fetch-and-extract routine that runs correctly across three different filesystem and permission models. None of that is conceptually hard. All of it is the unglamorous kind of work that's easy to keep deferring because the fallback already works well enough for my own daily use, which is exactly why it's still deferred.

Full stack developer. Founder of Yashveer Labs. The fallback works. The fast path is still being built.