Voice runtime

Everything on this page applies only to bots that publish or receive audio. The voice control plane is pure JavaScript and needs none of it.

Install the engine

Install at the exact pin

npm i @livekit/rtc-node@0.13.31 && npm i -D patch-package

The exact version matters. See why the pin is exact.

Copy the patch out of the SDK

mkdir -p patches
cp node_modules/@cloak-software/bot-sdk/patches/@livekit+rtc-node+0.13.31.patch patches/

The patch file ships inside the SDK package for exactly this.

Apply it on every install

npm pkg set scripts.postinstall="patch-package"
npm install

The constants VOICE_ENGINE_PIN and VOICE_ENGINE_PATCH_FILE are exported so your own setup scripts can read the version and filename rather than hardcoding them.

Why the patch is mandatory

The engine’s only per-participant key setter takes no key argument, at any published version, while its wire protocol marks that field required. Every call throws. Under per-participant encryption a publisher must install a key under its own identity, so an unpatched engine cannot publish audio anyone can decrypt. The SDK repo carries a one-line fix. Patches are repo-local: the engine installs into your node_modules unpatched, so a bot that publishes audio has to apply the same patch in its own app. The patch retires when upstream lands the fix.

npm install --ignore-scripts silently skips the patch. patch-package runs as a postinstall script. If your CI, Docker build, or lockfile-install step uses --ignore-scripts, the engine ends up unpatched and the bot publishes undecryptable audio with no error anywhere. Run npx patch-package explicitly in that case.

Why the pin is exact

A patch-package patch is named for one version. A floating range resolves to a version the patch does not name, patch-package skips it with a warning, and the bot publishes audio nobody can decrypt. The frame-key parameters the engine sends are also a cross-platform contract with the Cloak desktop, web, and mobile apps, and a minor version bump can change a default.

Host requirements


Node	`^20.19.0 \|\| >=22.12.0`. 21.x never qualifies.
glibc	2.28 or newer.
musl / Alpine	No build, at any version. Prebuilt binaries cover macOS arm64 and x64, Linux gnu x64 and arm64, and Windows x64.
Disk	About 15 MiB of native code beside the SDK’s own JavaScript.

The Node floor is a crypto requirement, not a transport or voice one. The HPKE stack needs globalThis.crypto.getRandomValues, which Node 18 does not define in ESM. The default wire is a plain wss:// WebSocket over the pure-JS ws package, and installing the SDK itself compiles nothing. The voice engine ships prebuilt binaries, so it does not compile either.

The engine sits in optionalDependencies specifically because npm tolerates platform and install-script failures there. A musl host or a prebuild miss still gets a working text bot.

Optional executables

Neither is a dependency of correctness. Feeding the player raw PCM needs neither.

Executable	Needed by	Reported by the dependency report?
`ffmpeg`	`ffmpegResource()`	Yes, under “Voice (optional)”.
`yt-dlp`	`ytdlpResource()`, `resolveMediaUrl()`	No. Nothing probes it, so its absence shows up as a `CloakEnvironmentError` at play time.

Checking the host

Two different questions, two different tools.

import { probeVoiceRuntime, generateDependencyReport } from '@cloak-software/bot-sdk';

// Does the engine actually LOAD? This is where glibc and musl show up.
const probe = await probeVoiceRuntime();
if (!probe.available) console.error(probe.error, '\n', probe.remedy);

// Is it INSTALLED, and is ffmpeg on PATH?
console.log(generateDependencyReport());

probeVoiceRuntime() never throws. A text-only bot must not be failed by an absent voice engine, so it is a diagnostic rather than a gate.

interface VoiceRuntimeProbe {
  available: boolean;
  version?: string;
  error?: string;   // present when it did not load
  remedy?: string;  // an actionable fix, present when it did not load
}

Probe before joining, and report probe.remedy to whoever invoked the command. It is written to be shown to a human.

Run the dependency report from a file, not from node -e. The -e form fabricates a crypto global that no module in the process can see, so the secure-random row would lie on exactly the hosts it exists to diagnose.

voiceEnvError(cause) is the same mapping the SDK uses internally: hand it a load failure and it returns a CloakEnvironmentError with a remedy naming what to change on the machine. It recognises old glibc, musl hosts, and a missing package.

The media engine surfaces no per-participant encryption failure state, so a bot cannot detect that nobody can decrypt it. Decryption failures and missing keys are dropped rather than reported. The one per-participant event that does exist reports that a participant’s frames are marked encrypted, which stays true through exactly the key and identity mismatches that matter. The failure tolerance is set to never give up, so a frame decryptor with no key retries quietly forever.There is no event to subscribe to and no counter to read. Silence is the only symptom.

Because of that, the SDK ships no voice health check and no retry-on-decrypt-failure path. Both would be theatre. Do not build one.

A bot cannot detect	So the SDK ships
”I am publishing and nobody can decrypt me”	No publish health check
”I am subscribed and cannot decrypt member X”	No per-participant decrypt monitor
A key or identity mismatch of any kind	No retry-on-decrypt-failure path

The only defence is to be correct by construction, which is what VoiceMediaSession.attach() does: install exactly what voiceFrameKeyFor() returns, under the identity the SFU reported, before publishing, and fail closed on every precondition. The real acceptance test is a live call with a human on the other end.

Symptom to cause

Symptom	Likely cause	Fix
Bot joins and publishes, members hear nothing, no errors anywhere	The engine is unpatched	Copy and apply the patch, and check `--ignore-scripts` is not in your install step
Same, and the patch is applied	Installed `getVoiceKey().key` instead of `voiceFrameKeyFor()`	Let `attach()` install keys, or install only what `voiceFrameKeyFor(serverId, identity)` returns
Same, and both of those are right	The installed engine version does not match the patch filename	Pin `0.13.31` exactly and re-run `patch-package`
`attach()` throws an identity mismatch	`botId` is not the bot’s own user id	Pass `client.user.id`
Bot holds `voice_listen` and still hears nothing	It joined deafened	Rejoin with `deafened: false`. The subscribe grant is fixed at join time
Bot hears some members but not others	One identity’s key install failed, or the bot never saw half the roster	Check the per-identity warnings in the log, and re-attach
`play()` finished instantly and the track never sounded	The decoder exited non-zero	Read the thrown `CloakEnvironmentError`, it carries ffmpeg’s own first error line
ffmpeg reports invalid data for an `http` URL	You handed it a watch page	Use `ytdlpResource()` instead of `ffmpegResource()`
`yt-dlp` not found	Not installed, and nothing probes it	`brew install yt-dlp`, `pipx install yt-dlp`, or pass `ytdlpPath`
Environment error mentioning GLIBC	Host glibc is older than the prebuild needs	Run on an image with glibc 2.28 or newer
Error loading shared library on Alpine	There is no musl build	Move to a glibc base image
`setVoiceKey()` threw and the session detached	The scope changed, meaning `voice_listen` was granted or revoked	Rejoin voice and `attach()` again
`acquireVoiceKey()` timed out	No online human member sealed a key in the window	Have a member open the server, then retry
`acquireVoiceKey()` was denied	Not a member, or missing `voice_connect`, or holds neither `voice_speak` nor `voice_listen`	Fix the grant on the server

Publishing audio

The media session, the player, and the resource helpers.

Voice keys and scopes

The other half of every silence bug.

Voice reference

probeVoiceRuntime, voiceEnvError, and the voice constants.

Handling errors

CloakEnvironmentError and the rest of the error model.

Get started

Core concepts

Messaging

Slash commands

Embeds and cards

Voice

Server management

Advanced

Running in production

Examples

API reference

Reference

Install the engine

Why the patch is mandatory

Why the pin is exact

Host requirements

Optional executables

Checking the host

The blind spot

Symptom to cause

Next

Publishing audio

Voice keys and scopes

Voice reference

Handling errors

​Install the engine

​Why the patch is mandatory

​Why the pin is exact

​Host requirements

​Optional executables

​Checking the host

​The blind spot

​Symptom to cause

​Next

Publishing audio

Voice keys and scopes

Voice reference

Handling errors

Install the engine

Why the patch is mandatory

Why the pin is exact

Host requirements

Optional executables

Checking the host

The blind spot

Symptom to cause

Next