ILORB Signal developers

Real-time voice rooms for your app: a stage with many microphones and an audience listening, or a voice call where everyone talks. ILORB Signal runs on the Cloudflare global network. You keep your users, your rooms and your rules; we carry the audio.

Core concepts

Quickstart

1. Create a project

In the console, open Projects → Create project, pick Voice room and copy the App ID and App Secret. The secret is shown only once; you can rotate it later.

2. Issue a token on your server

import { createUserToken } from '@ilorb/signal-server'

// e.g. inside your authenticated "join room" endpoint
const token = await createUserToken({
  appId: process.env.ILORB_APP_ID,
  appSecret: process.env.ILORB_APP_SECRET,
  userId: user.id,          // your user id, [0-9A-Za-z_-] up to 40 chars
  roomId: 'room-42',        // optional: lock the token to one room
  expiresInSeconds: 3600,  // optional: default 24 h, max 7 days
})

3. Join from the app

import { VoiceClient } from '@ilorb/signal'

const voice = new VoiceClient({ serverUrl: 'https://api-signal.ilorb.app' })
voice.on('userJoined', (u) => console.log('joined', u.userId))
voice.on('soundLevels', (levels) => drawWaves(levels))   // { userId: 0–100 }
voice.on('error', (e) => console.warn(e.code, e.message))

await voice.joinRoom('room-42', tokenFromYourServer, { name: 'Ana' })
await voice.startPublishing()      // go on stage (asks for the microphone)
voice.muteMicrophone(true)          // stays on stage, sends nothing

Open the same room in a second tab or phone and the two of you hear each other. The console's Test room does exactly this without writing any code.

User tokens

A user token is a JWT signed with HS256 using your App Secret. Your server creates it; the SDK sends it when connecting; ILORB Signal checks the signature, the expiry and the room.

createUserToken(options)

@ilorb/signal-server uses only WebCrypto, so it runs on Node 18+, Cloudflare Workers, Deno, Bun and the browser. It also exports verifyUserToken(token, appSecret) and peekAppId(token). In any other language, sign the claims above as a standard HS256 JWT.

To debug, the console has Tools → Generate test token (valid 24 h) and Verify token, which tells you whether a token is valid, which project it belongs to and when it expires.

Server credentials

The REST API is for your server only. Authenticate every call with HTTP Basic using the project credentials:

Authorization: Basic base64("<App ID>:<App Secret>")

curl -u "$ILORB_APP_ID:$ILORB_APP_SECRET" https://api-signal.ilorb.app/v1/rooms

Rotating the App Secret in the console invalidates the old one immediately for new tokens and REST calls. People already in a room stay connected.

Server SDKs BETA

Libraries for your backend (they hold the App Secret, so never ship them in the app). Each one does the same four things, with the language's standard library only:

1. User token — createUserToken, byte-for-byte identical to @ilorb/signal-server (same claims, same order), plus verifyUserToken and peekAppId.
2. Signed callbacks — verifyCallback for room and chat callbacks: x-ilorb-signature = sha256=hex(HMAC-SHA256(callback_secret, "<x-ilorb-timestamp>.<raw body>")), 300 s tolerance. Pass the raw body as received, not re-serialized JSON.
3. Rooms (api-signal.ilorb.app): balance, listRooms, roomState, kick, close, link, unlink, broadcast, setAttributes (room & member attributes). The token also takes admin.
4. Chat (chat-signal.ilorb.app): moderation, ban / unban, reports, send a message (also system), revoke, set a profile, push test and callback log.

Version 0.2.0 (2026-11-02) adds, in all four languages: the callback eventId receiver (handle each event once), call push to FCM / APNs VoIP, cloud mix, recording (whole room and per person), RTMP output and the cloud player, content moderation (settings, flags, verdicts, bans) and Live Shop (store, catalogue, pins).

"Tested" means: tokens identical to the TypeScript ones (fixed test vectors), tampered or expired tokens and callbacks refused, unit tests, the local API, and a real join and leave against our development server. Available on request: the packages are not on PyPI, the Go proxy, Maven Central or Packagist yet, so pip install / go get / Maven / composer require do not work today — ask us and we send the package (the names above are the ones they will be published under).

# Python
from ilorb_signal import create_user_token, verify_callback, RoomsClient, ChatServerClient

token = create_user_token(APP_ID, APP_SECRET, "ana", room_id="room-1", expires_in_seconds=3600)
ok = verify_callback(CB_SECRET, request.headers["x-ilorb-timestamp"], request.get_data(), request.headers["x-ilorb-signature"])
RoomsClient(APP_ID, APP_SECRET).kick("room-1", "bruno")
ChatServerClient(APP_ID, APP_SECRET).send_message("shop", "peer", "ana", {"type": "system", "text": "Order paid"})

// Go
import ilorbsignal "signal.ilorb.com/server"

tok, err := ilorbsignal.CreateUserToken(appID, appSecret, "ana", ilorbsignal.TokenOptions{RoomID: "room-1", ExpiresInSeconds: 3600})
body, _ := io.ReadAll(r.Body)   // the RAW body
ok := ilorbsignal.VerifyCallback(cbSecret, r.Header.Get("x-ilorb-timestamp"), body, r.Header.Get("x-ilorb-signature"), 0)   // 0 = 300 s
ilorbsignal.NewRoomsClient(appID, appSecret).Kick(ctx, "room-1", "bruno")
ilorbsignal.NewChatServerClient(appID, appSecret).BanUser(ctx, "bruno", 3600, "spam")

// Java (also Kotlin)
String tok = IlorbSignal.createUserToken(APP_ID, APP_SECRET, "ana", "room-1", 3600);
boolean ok = IlorbSignal.verifyCallback(CB_SECRET, req.getHeader("x-ilorb-timestamp"), rawBody, req.getHeader("x-ilorb-signature"));
new RoomsClient(APP_ID, APP_SECRET).broadcast("room-1", "score", Map.of("a", 3));
new ChatServerClient(APP_ID, APP_SECRET).banUser("bruno", 3600, "spam");

// PHP
use IlorbSignal\{Auth, RoomsClient, ChatServerClient};

$tok = Auth::createUserToken($appId, $appSecret, 'ana', roomId: 'room-1', expiresInSeconds: 3600);
$ok  = Auth::verifyCallback($cbSecret, $_SERVER['HTTP_X_ILORB_TIMESTAMP'], file_get_contents('php://input'), $_SERVER['HTTP_X_ILORB_SIGNATURE']);
(new RoomsClient($appId, $appSecret))->kick('room-1', 'bruno');

API errors become an exception (or Go *ilorbsignal.Error) with the HTTP status and a code: Python IlorbSignalError, Java and PHP IlorbSignalException.

Install the client SDK

npm install @ilorb/signal
npm install @ilorb/signal-server   # on your server

Without a bundler, load the browser build. It exposes the global IlorbSignal:

<script src="https://api-signal.ilorb.app/sdk/ilorb-signal.js"></script>
<script>
  const voice = new IlorbSignal.VoiceClient({ serverUrl: 'https://api-signal.ilorb.app' })
</script>

VoiceClient

new VoiceClient(options: VoiceClientOptions)

Methods

Events

Audio options

Types

type RoomUser = { userId: string; name: string; publishing: boolean; micOpen: boolean; attributes: Record<string, string>; position: { x, y, z } | null; team: string | null }

type NetworkStats = {
  sendKbps, receiveKbps, sendLossPct, receiveLossPct, jitterMs, rttMs: number | null
  codec: string | null
  concealedPct: number | null   // % of received audio that was concealed (loss)
  listening: number              // how many voices I am receiving
}

type AudioHooks = {
  prepare?(options): Promise<void> | void       // before connecting: audio session, route
  afterConnect?(options): Promise<void> | void  // native processing needs WebRTC up
  release?(): Promise<void> | void              // on leaving
}

Video (camera) BETA

The same room carries video. Each person's camera is published on a connection of its own (like the microphone), so turning it on never disturbs the audio. Defaults follow the 540p live preset: 540×960, 15 fps, 1,200 kbps, H.264 (hardware encoder on almost every phone). When the network drops, WebRTC lowers resolution and frame rate gradually.

await voice.startCamera()                       // or startCamera({ width: 720, height: 1280, maxBitrateKbps: 1500 })
voice.on('localVideoChanged', (stream) => showPreview(stream))
voice.on('videoTrackChanged', (userId, stream) => showTile(userId, stream))   // stream null = gone

// React Native
<RTCView streamURL={stream.toURL()} objectFit="cover" mirror={isMe} />
// browser
videoElement.srcObject = stream

RoomUser gains camera (has a camera published) and cameraOn (published and not closed). Option autoSubscribeVideo (default true) receives every camera automatically; set it to false in large rooms and call setVideoReceiving for what is visible.

Billing: video rooms are measured the same way (participant-minutes), and camera-minutes are recorded separately for each room. Video pricing will be announced separately. Effects before the encoder (filters, beauty, background) come from ILORB FX through setCameraEffects.

Simulcast & quality per person BETA

With video.simulcast the camera is sent in two sizes: the full one (sendSize / maxBitrateKbps) and one with half the width at about a quarter of the bitrate. Each viewer picks, only for themselves, which one to receive: 'low' for thumbnails and grids, 'high' for the highlighted tile. Without enough bandwidth the server drops to the small one by itself. It costs the publisher more upload and saves download for every viewer. Tested in Chrome (H.264 and VP8); not yet on real phones.

const voice = new VoiceClient({
  serverUrl: 'https://api-signal.ilorb.app',
  video: { width: 720, height: 1280, sendSize: { width: 540, height: 960 }, simulcast: true },
})

voice.setVideoQuality('ana', 'high')    // the big tile
voice.setVideoQuality('bruno', 'low')   // a thumbnail

setVideoQuality(userId, quality) only has an effect if the publisher turned simulcast on.

Video stats & events BETA

voice.on('remoteVideoFirstFrame', (userId, w, h) => swapAvatarForVideo(userId))   // first frame arrived
voice.on('remoteVideoSizeChanged', (userId, w, h) => relayout(userId, w, h))   // layer change, rotation
voice.on('localVideoFirstFrame', (w, h) => hideSpinner())

const { local, remote } = await voice.getVideoStats()
// local:  { width, height, fps, kbps, limitation, layers: [{ rid, width, height, kbps, active }] }
// remote: { [userId]: { width, height, fps, kbps, lossPct, quality: 'high' | 'low', frozen } }

kbps and fps are measured since the previous call; limitation says why the encoder is sending less (bandwidth, cpu…).

Poor network: audio only BETA

With lowNetworkVideo: 'audio-only', when someone's camera freezes for me (under 3 fps or over 15% loss for about 6 s), the SDK stops receiving that camera and the voice carries on. It tries again after 20 s, then 40, 80 and 120 s. Only my side is affected; the others keep receiving.

const voice = new VoiceClient({ serverUrl, lowNetworkVideo: 'audio-only' })
voice.on('videoPausedForNetwork', (userId, paused) => showWeakNetworkBadge(userId, paused))

Device table: quality per phone BETA

Your app only says the account's quality (the preset); the SDK caps it by what this phone can publish, before the camera goes live. The answer comes from the server's device table, inside the device profile (settings.video): the device class from the hardware (weak → 540p 24 fps one layer, medium → 720p, good → 1080p), then a measured verdict per phone model from real sessions (a model whose camera ran at low fps, was CPU-limited, went into light mode or ran the effects slowly is capped one step below the size it was sending; a model that proved healthy at a size is allowed that size), then the operator's rows. The SDK never raises what you asked for, only lowers it.

// before going live (the preview): the account preset, already capped for this phone
const video = await voice.videoForPreset('preset1080p')
await voice.startCamera(video)                // startCamera caps by itself too

voice.on('videoCapped', ({ caps, capped, requested, effective }) => log(caps.reason, capped))
voice.videoCaps   // { caps: { maxPreset, maxFps, maxKbps, codec, simulcast, effectsMaxSide, gpuTier, reason }, requested, effective, capped }

startCamera waits up to 1.5 s for the first answer of the table (the last answer is kept on the device and applies at once). A table change during the live re-caps the camera without republishing. capVideo(options, caps) and videoForPreset(preset, { caps }) are exported for custom flows. Turn it off with the tuning key videoDeviceCaps: false.

Data synced to the frame (SEI) BETA

What other SDKs call SEI or video metadata: a small payload (a gift id, a karaoke line, a game state) that viewers receive at the frame it was sent with, not whenever the network delivers it. The video itself is never changed, so every decoder keeps working.

// publisher — frameData: true stamps the camera from the first startCamera
const voice = new VoiceClient({ serverUrl, frameData: true })
voice.sendFrameData({ gift: 'rose', x: 0.4 })      // text or JSON, ≤ 4096 chars, ≤ 60/s; false = not sent

// viewer (browser): register the <video> showing that person, then listen
voice.setVideoElement('ana', videoElement)
voice.on('frameData', (userId, data, info) => showGift(JSON.parse(data)))   // info.mode: 'frame' | 'timed'

The publisher stamps the payload with the RTP timestamp of the next encoded frame (a pass-through RTCRtpScriptTransform); the room relays it; the viewer releases it when that frame is presented (requestVideoFrameCallback), holding the video a little longer in its jitter buffer (up to 250 ms) when the data would otherwise arrive late. Measured in Chrome through the SFU: 98–100% of the payloads fire on their own frame after a ~3 s warm-up (a plain room message: 3%). Where the publisher cannot stamp (React Native today) or the viewer has no element, the payload is released by the viewer's measured video delay (info.mode: 'timed', about ±1–2 frames). frameDataStats shows the counters.

End-to-end encryption PREVIEW BROWSER REACT NATIVE

Development server only for now (protocol 15). Browser and React Native (Android proven against a browser in the same room; iOS builds, not yet run on an iPhone); Kotlin and Swift are next. Every audio and video frame is encrypted on the sender's device and decrypted only by the other participants. The media still goes through our SFU — simulcast layer switches and keyframe requests keep working — but the server never has a key and never sees a decoded sample.

// 1) a secret your server gives every participant of the room
const voice = new VoiceClient({ serverUrl, e2ee: { key: roomSecretFromYourServer } })

// 2) your key service, per key index (0–255)
new VoiceClient({ serverUrl, e2ee: { keyProvider: { getKey: ({ roomId, keyIndex }) => fetchKey(roomId, keyIndex) } } })

// 3) no app secret: a random room key exchanged between the participants (ECDH), rotated when someone leaves
new VoiceClient({ serverUrl, e2ee: { keyProvider: 'exchange' } })   // + key: '…' = the server cannot swap the public keys

voice.on('e2eeDecryptionFailed', ({ userId, kind, reason, keyIndex }) => …)   // auth_failed | missing_key | not_encrypted
voice.on('e2eeKeyChanged', ({ keyIndex, reason }) => …)
await voice.rotateE2eeKey()       // shared key: ratchet (the others follow by themselves) · exchange: only the leader
await voice.setE2eeKey(newSecret)  // shared key: every participant sets the same new secret
voice.getE2eeStats()             // mode, engine, key index, frames encrypted / decrypted / dropped by reason, µs per frame, leader, fingerprints

// React Native: hand the SDK the native frame cryptor of @livekit/react-native-webrtc (nothing else changes)
import { MediaStream, RTCFrameCryptorFactory, RTCPeerConnection, mediaDevices } from '@livekit/react-native-webrtc'
new VoiceClient({ serverUrl, webrtc: { RTCPeerConnection, mediaDevices, MediaStream, RTCFrameCryptorFactory }, e2ee: { key } })

• Format. Per encoded frame, the format of WebRTC's native FrameCryptor (webrtc-sdk), so browsers and phones decrypt each other: AES-GCM-128 with a 96-bit IV; the codec header stays clear and is authenticated (Opus: 1 byte; VP8: the 3/10-byte frame tag; H.264: the NAL headers up to the first slice, the encrypted part escaped so it never looks like a start code). Trailer: IV, IV length (12), key index — 30 bytes per frame with the tag (+12 kbps for 50 audio frames/s, +7.2 kbps for 30 video fps). The browser encrypts in an encoded-transform worker (RTCRtpScriptTransform), React Native in WebRTC's native FrameCryptor (getE2eeStats().engine: 'web' / 'native'; the native engine reports each track's state, not per-frame counters).
• Keys. Key material per index: your secret (shared key), what your key service returns (keyProvider) or the leader's random key (exchange). Frame key = HKDF-SHA-256(material, salt "ilorb-e2ee/v2/" + roomId, info 128 zero bytes, 16 bytes); rotation ratchets the material (index + 1, HKDF to 32 bytes), receivers ratchet on their own up to 16 steps (React Native installs the next 16 ahead). Exchange: each participant has a P-256 key pair; the leader (lowest user id holding the key) sends the room key wrapped with an AES-GCM key derived from the pairwise ECDH secret (and your key, if given) through the room's WebSocket. When someone leaves, the leader makes a new key for the ones who stayed; the previous keys are kept briefly so frames in flight still decrypt. Compare getE2eeStats().fingerprint out of band to rule out a man in the middle when you do not give a key.
• What cannot work. Cloud mix, recording (room and per person), RTMP, the cloud player and content moderation need to see the media. Joining a room where any of them is on fails with e2ee_conflict; while anyone in the room encrypts, the server refuses to start them (HTTP 409 e2ee_active) and the room state lists e2ee.users. e2ee: { allowConflicts: true } joins anyway (those features get undecodable data; moderation samples are never sent). The separate music track is not available (the music stays on the encrypted mic).
• Never in clear. A frame that does not decrypt is dropped, never played (a wrong key hears silence and sees no video). A runtime that cannot encrypt fails the join with e2ee_unsupported instead of sending in clear: a browser without encoded transforms, React Native without RTCFrameCryptorFactory in webrtc, and keyProvider: 'exchange' on React Native (it needs WebCrypto ECDH in JS, which Hermes lacks — use key or a keyProvider there). The Kotlin and Swift SDKs do not support E2EE yet.
• Cost. Measured in Chrome (2 peers, mic + 640×480 camera, VP8 and H.264): ~30–70 µs to encrypt and ~25–55 µs to decrypt a frame (the added latency, well under a millisecond); the browser's CPU with and without E2EE differed by −1 to +4 points of one core across three runs (run-to-run noise); the same time to the first video frame.

Screen sharing BETA

The screen goes on a track of its own ({roomId}-{userId}-screen), separate from the camera: you can share the screen with the camera on, and viewers receive both. Protocol 7. Tested end to end in Chrome; React Native (Android and iOS) still needs testing on real phones.

• No simulcast: viewers always get the full size, so text stays readable.
• contentHint = 'detail' and degradationPreference = 'maintain-resolution': on a bad network the frame rate drops, not the sharpness.
• Defaults: 15 fps, up to 2,500 kbps, the camera's codec.

Sharing

// Browser: call it straight from the click (getDisplayMedia needs a user gesture)
button.onclick = async () => {
  const stream = await voice.startScreenShare()        // preview: video.srcObject = stream
}
await voice.stopScreenShare()

voice.on('screenShareEnded', (reason) => …)   // 'stopped' | 'system' | 'no_frames' | 'left'
voice.isScreenSharing                          // boolean
voice.localScreenStream                        // preview stream or null

Where the track comes from, in this order: startScreenShare({ track, stream }) (a ready video track) → startScreenShare({ capture }) (capture for this call only) → new VoiceClient({ screenCapture }) (the client's default) → navigator.mediaDevices.getDisplayMedia (browser). A track that came from your app is yours: on stop the SDK unpublishes it but does not stop it — unless you pass stopTrackOnEnd: true (what you want in React Native: any end, including a stop from the system UI, then also ends the capture). A track the SDK captured itself, it stops.

React Native with @ilorb/signal-react-native-screen (iOS: the ReplayKit extension, created by its Expo plugin):

import { ScreenCapturePickerView } from '@livekit/react-native-webrtc'
import { IlorbScreen } from '@ilorb/signal-react-native-screen'

const picker = useRef(null)   // <ScreenCapturePickerView ref={picker} /> somewhere on screen
await voice.startScreenShare({
  capture: () => IlorbScreen.start({ pickerRef: picker }),   // a refused consent rejects: screen_share_denied
  stopTrackOnEnd: true,                                      // the SDK ends the capture on every end
})

It ends by itself when the person stops it from the system bar or button (track ended → screenShareEnded('system')) and when no frame arrives in 15 s (iOS: the person cancelled the system picker → error screen_share_no_frames and screenShareEnded('no_frames')). On a network drop the capture keeps going and the screen is published again on reconnect, without asking for permission again.

Errors from startScreenShare (err.code, not terminal): not_in_room, screen_share_unsupported (no getDisplayMedia and no capture given), screen_share_denied (the person refused), screen_share_failed.

Watching

voice.on('remoteScreenStarted', (userId, stream) => { screenEl.srcObject = stream })   // RN: <RTCView streamURL={stream.toURL()} />
voice.on('remoteScreenStopped', (userId) => { screenEl.srcObject = null })
voice.getUsers()                          // RoomUser.screenOn: true while sharing
voice.getScreenStream(userId)             // the screen stream or null (the camera stays in getVideoStream)
voice.setScreenReceiving(userId, false)  // stop receiving it (cancels the subscription)

new VoiceClient({ autoSubscribeScreen: false }) receives nobody's screen until setScreenReceiving(userId, true). A shared screen counts as video in usage (video minutes and the traffic of whoever receives it).

PK — linked rooms BETA

A PK (host vs host) links two rooms: everyone in each room sees and hears the stage of the other room (whoever is publishing), with no mixer — zero added delay, each app draws its own layout (1v1, 2v2…), and voice levels arrive per person. The audience of each room stays in its own room. Your server decides who plays whom (invites, random match, score, timer) and links/unlinks the rooms:

Both rooms must be open (409 otherwise) and belong to the same project. broadcast sends a message from your server to everyone in the room (score, "PK started", winner) — it arrives as roomMessage with fromUserId: "server". GET /v1/rooms/{roomId} lists the links and the remote stage.

voice.on('roomLinked', (roomId, users) => showPkLayout(users))      // the other room's stage
voice.on('videoTrackChanged', (userId, stream) => drawTile(userId, stream)) // same as local people
voice.on('roomUnlinked', (roomId) => backToSolo())
// RoomUser.roomId tells who is from the other room; getLinkedRooms() lists the links

Everything you do with local people works with the linked stage: setVideoReceiving, muteUser, setUserVolume. Traffic from the other room counts in the room of whoever receives it. Coming next: a mixed output (one composed stream) for very large audiences and RTMP. Cloud recording is in beta.

PK battle in the SDK PREVIEW

voice.pk runs the whole battle for you — no server code needed: one host invites a host of another room, the other accepts, the rooms link, a timer runs, gifts add points to a side, the result comes with a punishment timer, then the rooms unlink by themselves. The state is the room attribute pk:state in both rooms (written only by the room), so whoever joins late gets the current score and timers with the room. Timers are in server time: remainingMs() gives the same countdown in both rooms.

// host A (publishing, or an admin token)
const { pkId } = await voice.pk.invite('room-b', 'host-b', { durationSec: 180, punishSec: 60, scoring: 'server' })
// host B
voice.pk.on('invited', (inv) => ask(inv) ? voice.pk.accept(inv.pkId) : voice.pk.reject(inv.pkId))
// everyone, in both rooms
voice.pk.on('state', (s) => render(s))         // s.phase 'battle' | 'punish' | 'ended', s.sides[0|1].score, s.winner, s.reason
voice.pk.remainingMs()                            // the current phase's countdown
voice.pk.sides()                                  // { mine, other }: my room's host and the other one
voice.pk.on('gift', (g) => playGift(g.giftId))     // a gift in either room
await voice.pk.end()                              // a PK host ends it early

Points. With scoring: 'server' (the default) only your server adds points, after it charges the gift: POST /v1/rooms/{roomId}/pk { "action": "score", "points": 10, "to"?: "roomId", "giftId"?: "rose", "userId"?: "buyer" } (Basic appId:appSecret; to defaults to this room). With scoring: 'clients' viewers add points with voice.pk.sendGift({ giftId, points, to? }) — only for free gifts. { "action": "state" } reads the PK, { "action": "end" } ends it.

Edge cases the room handles: a host whose connection drops is waited for 15 s (a reconnection keeps the battle); after that the other side wins (reason: 'host_left'); an unanswered invite expires in 20 s; a busy room refuses (pk_busy); points after the battle are refused (pk_not_running); pk:* attributes cannot be written by clients or /attrs. Errors: pk_not_host, pk_busy, pk_pending, pk_invite_not_found, pk_host_absent, pk_scoring_server, pk_invalid, sfu_mismatch. Examples: examples/web/pages/pk, the React Native PK battle screen.

Room & member attributes BETA

Small key → text values kept by the room and sent to everyone: the room's (topic, cover, who is on each seat, the score) and each person's own (role, level, "hand raised"). Changes reach everyone as events with only what changed. Protocol 9.

// the room's: everyone receives roomAttributesUpdated
await voice.setRoomAttributes({ seat1: 'ana', topic: 'Friday karaoke' })
await voice.deleteRoomAttributes(['seat1'])
voice.getRoomAttributes()                         // { topic: 'Friday karaoke' }

// mine: everyone receives memberAttributesUpdated; gone when I leave, sent again by the SDK after a reconnect
await voice.setMyAttributes({ hand: 'up', level: '12' })
await voice.setMyAttributes({ hand: null })          // null deletes
voice.getUsers()[0].attributes                   // someone else's

voice.on('roomAttributesUpdated', (changes, attributes, by) => render(attributes))   // changes: only what changed, null = deleted
voice.on('memberAttributesUpdated', (userId, changes, attributes, by) => …)          // by: userId, or '__server'

The promises resolve when the room confirms. A refusal rejects the promise with err.code and is not a session error: attrs_invalid (bad key or non-text value), attrs_too_large, attrs_denied (room attributes are locked to admins). One call changes everything or nothing.

Room attributes are not for things that change many times per second (use sendRoomMessage), and they are not a database: closing the room deletes them.

Stage seats (voice.stage) BETA

The mic seats of a voice room, built into the SDK and enforced by the room (protocol 13): a member takes only a free, unlocked seat for themselves and leaves their own; a muted seat cannot open its mic; with the stage on, only someone on a seat publishes the microphone. The seats live in the room attributes (stage.seats, seat.<n>), so late joiners get them with the room.

voice.on('seatsChanged', (seats) => render(seats))       // [{ index, user, locked, muted }]
await voice.stage.takeSeat()                           // first free seat (or takeSeat(3)); publishes the mic
await voice.stage.leaveSeat()                          // stops publishing and frees the seat
// host (a token with admin: true) or your server (POST /v1/rooms/{roomId}/attrs)
await voice.stage.setSeatCount(8)                      // turns the stage on
await voice.stage.muteSeat(2, true)                    // whoever sits there cannot unmute
await voice.stage.removeFromSeat(2)                    // takes them off the stage (their mic stops)
await voice.stage.lockSeat(5, true)                    // nobody can take seat 5

Someone on a seat whose connection drops keeps the seat for a short grace period (a reconnection); a kick or a closed room frees it at once. Demo: examples/voice-room-demo.

Range voice & teams BETA

For games and virtual spaces: each person has a position and, optionally, a team. You hear people near you louder, people far away not at all, and your team anywhere. The room only relays positions and teams; volume, stereo pan and who to receive are decided on the device. Protocol 10.

voice.setPosition({ x: 12, y: 0, z: -4 }, { right: { x: 1, y: 0, z: 0 } })   // your game's units; right = the vector to my right (pan)
voice.setAudioRange(30)                 // hear up to 30 units away (default 100)
voice.setTeam('red')                      // or null
voice.setRangeMode('world')               // 'off' (default) | 'world' | 'team'

voice.on('positionChanged', (userId, position, team) => moveAvatar(userId, position))
voice.getRangeInfo()   // { mode, radius, users: [{ userId, distance, gain, pan, audible, subscribed }] }

• Out of range = unsubscribed. Someone farther than the range × 1.15 is unsubscribed: nothing arrives and nothing is billed. They are subscribed again when they come back inside the range. The gap between the two (hysteresis) keeps someone on the edge from being subscribed and unsubscribed all the time. Coming back takes about 0.5–1 s, like muteUser.
• Rate. Call setPosition as often as you like (every frame is fine): it reaches the others at most 5 times per second, and the latest position always arrives.
• Pan works in the browser (WebAudio) and, in beta, on React Native Android and the Kotlin SDK through the SDK's own stereo output (see spatial audio). React Native iOS and Swift get the volume by distance; their stereo pan is written but not yet tested on an iPhone.
• Position, team, range and mode are kept across reconnects and rooms. RoomUser.position / team show everyone else's. Your own setUserVolume multiplies the distance volume.

Speech detector & spatial audio BETA ANDROID

Our own speech detector runs in the native audio core (@ilorb/signal-react-native-audio; the Kotlin SDK runs the same C code; Swift and React Native iOS are written but not tested on an iPhone). Every 10 ms it weighs the energy above the noise floor, the pitch (80–400 Hz), the speech-band shape and how the level moves between syllables, plus the noise AI's voice probability; a music detector (held pitch, steady spectral peaks, a beat) keeps songs from opening it. Its send gate sends exact silence while nobody speaks, so Opus DTX stops sending.

const voice = new VoiceClient({ serverUrl, webrtc, vad: true })   // or { gate: false }: detector and events only
voice.on('localSpeakingChanged', (speaking) => showTalking(speaking))
await voice.setVad(true)          // change it later
await voice.getVadStats()          // { enabled, gate, available, speaking, speechPct, gatedPct, openPct, onsets, frames, levelDb, … }

On recordings: the gate stays open on 97% of loud speech frames and loses 1.46% of the speech energy (word starts); all 11 music clips stay at or under 12% open. Weak spots: dog barks, a café with voices, and speech over a song (the voice loses more there). The default is off (tuning.vad): the device table can turn it on per phone model from the server. Cost: 17–56 µs per 10 ms frame on the emulator.

Spatial audio on phones. WebRTC plays every received voice as one mono stream, so a pan cannot live inside it. With range mode 'world' or 'team', React Native Android (and the Kotlin SDK) taps each received voice, mixes them in our C mixer with their distance gain and an equal-power pan, and plays the stereo mix on the SDK's own output, while WebRTC keeps running muted so the echo canceller still has its reference. Measured on the emulator: hard left/right +100 / −100 dB between the channels, half-left 7.7 dB (the law says 7.66), 0 underruns. Range mode 'off' gives the output back to WebRTC. await voice.getSpatialStats() reports the mixer. Not heard on a real phone yet (headphones, loudspeaker echo, Bluetooth).

Spatial audio in the browser. The browser uses the same pan law as the phones' C mixer (equal power, unity in the center, +3 dB on one side at the ends; not WebAudio's StereoPannerNode, which is 3 dB quieter in the center), so a voice sounds the same on the web and on a phone. await voice.getSpatialStats() works there too: { platform: 'web', active, voices, leftDb, rightDb, limited, tracks: [{ userId, pan, gain, gl, gr, leftDb, rightDb }] }, levels in dBFS measured on the real WebAudio output over the last ~0.7 s. Measured against the development server (two Chrome peers, a 440 Hz tone): hard left/right ±105 dB between the channels, in front 0 dB, half-left 7.7 dB (law 7.66), distance 30 vs 60 = 0.7/0.4, in front at 60 exactly −7.96 dB under the reference. Demo: examples/web/pages/range-audio.

Noisy place warning BETA ANDROID

Tells the person on the mic that the place is too noisy for their voice ("move somewhere quieter") before the room hears it. The native audio core (@ilorb/signal-react-native-audio) measures the voice against the background on the raw microphone, before the noise AI, over 5 s windows: 'poor' = the AI removes the noise but the voice may sound muffled or robotic, 'bad' = the noise covers the voice. With the noise AI's voice probability it measures the speech-to-noise ratio; without the AI it mostly flags a loud background. The SDK only warns while your mic is open, stays quiet with music on the mic (Android: the sound classifier), and does not repeat the same warning within the cooldown.

const voice = new VoiceClient({ serverUrl, webrtc, noiseWarning: true })   // or { cooldownMs, snrPoorDb, snrBadDb, noisePoorDbfs, noiseBadDbfs }
voice.on('noiseWarning', (w) => w.level === 'ok' ? hideBanner() : showBanner(w.message))
// w = { level: 'ok' | 'poor' | 'bad', reason: 'noise' | 'quiet' | 'music' | 'micClosed', quality, message }
// other languages: noiseWarningMessage(w.level, 'pt', w.quality?.noiseKind)
await voice.setNoiseWarning(false)          // change it later
await voice.getNoiseQuality()             // { enabled, available, level, snrDb, noiseDbfs, voiceDbfs, speaking, voiceAi, music, noiseKind, badSeconds, measuring }

Timing (defaults, server-tunable): the level rises after ~7 bad seconds in 10 and falls after ~8 good ones; a rise must then hold 4 s with no music (tuning.noiseWarningConfirmMs); the same warning waits 5 min (noiseWarningCooldownMs); thresholds noiseSnrPoorDb 6, noiseSnrBadDb 0, noisePoorDbfs −30, noiseBadDbfs −20. Measured on the Android emulator (speech over a loud fan played into the mic): warned after 14–16 s, cleared 10 s after the place went quiet; a quiet room, clean speech and music gave no warning. The default is off (tuning.noiseWarning). iOS: written (no sound classifier, so no music check and no noise name), not tested on an iPhone.

Karaoke PREVIEW BROWSER

Lyrics synced on the singer and on every viewer, real-time pitch scoring, lead + chorus singing, a song catalogue and a pitch/timbre voice changer. Web first, on our development server; the platform-neutral core (packages/client/src/karaoke.ts: LRC parser, melody, scorer, sync, chorus clock) is shared with React Native, which still needs the native pitch tap.

import { VoiceClient } from '@ilorb/signal'
import { ilorbWebRTC, ilorbAudioHooks, IlorbAudio, IlorbKaraoke, KaraokeCatalogue } from '@ilorb/signal-web-fx'

const voice = new VoiceClient({ serverUrl, webrtc: ilorbWebRTC(), hooks: ilorbAudioHooks() })
const catalogue = new KaraokeCatalogue({ serverUrl, token: userToken })
const karaoke = new IlorbKaraoke(voice, { catalogue })   // BEFORE startPublishing: it stamps the mic sender
await voice.joinRoom(room, token)
await voice.startPublishing()

karaoke.on('line', ({ index, line }) => …)            // line: { startMs, endMs, text, words } | null (gap)
karaoke.on('word', ({ line, index, word, progress }) => …)
karaoke.on('pitch', (p) => …)                         // { posMs, hz, midi, refMidi, cents, credit, line } every 10 ms
karaoke.on('lineScore', (s) => …)                     // { userId, index, score 0–100, grade S/A/B/C/D, … }
karaoke.on('score', (t) => …)                         // { userId, score, grade, lines, final }
karaoke.on('state', (e) => …)                         // { state: playing | paused | stopped, role, singer, song }

// singer
await karaoke.loadSong('twinkle-twinkle')             // from the catalogue — or load({ track, lrc, melody, songId })
await karaoke.start(); await karaoke.pause(); await karaoke.resume(); await karaoke.seek(ms); await karaoke.stop()
await karaoke.setLatencyCompensation('auto')        // or ms
// viewer: nothing to call (it follows whoever sings), or karaoke.follow(userId)
// chorus (someone publishing, e.g. on a seat)
await karaoke.joinChorus(leadUserId, { leadVolume: 0.25 }); karaoke.leaveChorus()

await IlorbAudio.setVoiceMorph('female')   // 'male' | 'child' | 'giant' | 'anime' | 'whisper' | 'off', or { semitones, targetHz, formant, tilt, breath, whisper, mix }

• Viewer sync. The singer's mic sender reports the RTP timestamp of every encoded frame and sends a beacon on the room-message topic ilorb.karaoke about 4 times a second; each viewer maps the RTP timestamp of the audio it is playing to the song position, so network delay and the jitter buffer cancel out. Measured with three browsers on the development server: the line event lands 9–28 ms before the viewer hears the line (median), worst 23–38 ms. Without encoded transforms (or with E2EE on) it falls back to a timed mode.
• Scoring. YIN pitch every 10 ms on the singer's raw voice (before voice effects), against the reference melody: full credit within 35 cents, none from 150 cents, octave-folded. A line's score is the mean credit of its frames; line scores go to the room so viewers can show them.
• Chorus. The server only forwards media, so every chorus member plays the song locally on the lead's clock (NTP-style clock sync over room messages). Measured at a listener: chorus voice vs the lead's music 29–43 ms (median); singing to the lead's audio as it arrives would be 203–395 ms. Use headphones.
• Voice morph is a source-filter vocoder, not a neural network: pitch and timbre move independently, 20.7 ms of added latency (0 when off), ~0.3% of a core inside Chrome's audio worklet.
• Not yet: React Native / Kotlin / Swift engines, the voice morph in C, a latency calibration screen, a licensed song catalogue. The catalogue holds only content we may use (public-domain melodies and our own songs).

The catalogue's REST API is under Karaoke catalogue; the console lists your project's songs under Develop → Karaoke catalogue.

Background & economy

Most of the cost of a voice room is audio flowing to people who aren't listening. The SDK is built to send and receive only what is heard:

• Muted microphone sends nothing. muteMicrophone(true) keeps you on stage but sends zero packets; unmuting is instant. It stays at zero after a reconnect or a republish while muted — automatic, nothing to call.
• Muting someone unsubscribes. muteUser stops receiving that voice at the network level, not just the volume.
• Long background? Stop receiving. Call setReceiving(false) after a few minutes in the background, and setReceiving(true) on return.
• Closed camera sends nothing. muteCamera(true) stops the frames at once (viewers get cameraOn: false and show the avatar); stopCamera() also turns the camera off. In the background, call suspendCamera() and resumeCamera() on return (not stopCamera/startCamera: those rebuild the connection and every viewer subscribes again).
• Android: run a foreground service while live. Without one, Android 15 / HyperOS freezes a background app and cuts its network after a few seconds, so the room is lost and the return costs a reconnection (~3–5 s). IlorbLiveService.start({ title, text }) from @ilorb/signal-react-native-audio (type microphone|mediaPlayback, start it from the foreground) and IlorbLiveService.stop() when leaving; or keep your own media foreground service running.
• React Native Android: apply the SDK's react-native-webrtc patch. packages/react-native-audio/patches/@livekit+react-native-webrtc+144.1.2.patch (patch-package format) lets the SDK set the ICE ping interval of the selected pair; without it a join or reconnect can wait up to 2.5 s for the connection to be nominated.
• Send the size you show. A video tile is small: capture big and send small with sendSize (e.g. capture 720×1280, send 360×640 at ~400 kbps). On a phone screen it looks the same and costs about a third.
• Watch only who is on screen. setVideoReceiving(userId, false) unsubscribes a camera — it is not delivered and not billed as traffic. In big rooms, use autoSubscribeVideo: false and subscribe to the visible tiles.
• Coming back from the background. Call resume(). If the connection survived, voice is back in about 0.3 s; there is no need to leave and join again (that takes seconds).

AppState.addEventListener('change', (s) => {
  if (s === 'active') voice.resume()
})

Pre-call test BETA

Check the network, the microphone, the speaker and the camera before joining. It works outside a room, without a token. The simplest way is one call, runPrecheck, which runs every test and returns one verdict, each check's details and advice you can show as is (English) or translate by code:

import { runPrecheck, testCamera } from '@ilorb/signal'

const r = await runPrecheck({
  serverUrl,                                     // network test (omit to skip it)
  camera: { onStream: (s) => setPreview(s) }, // false for a voice-only app
  onProgress: (name, check) => render(name, check.status), // 'running' → 'pass' | 'warn' | 'fail' | 'skipped'
})
r.verdict   // 'ready' | 'degraded' | 'not-ready'
r.checks    // { network, microphone, speaker, camera }: { status, result, advice, durationMs }
r.advice    // [{ check, code: 'camera-too-dark', severity: 'warn', message }] — failures first

const cam = await testCamera({ facing: 'user' })
// { ok, opened, frames, fps, width, height, requested, brightness, freezes, longestGapMs, problems, source }

testCamera opens the camera, waits for the first frame, then measures the frames and the fps and size actually delivered (versus what was asked), freezes (a gap of 600 ms or more), and the brightness (too-dark / too-bright). On Android with @ilorb/signal-react-native-audio a native frame processor sees every frame; in the browser a hidden video element is used; elsewhere (iOS today) WebRTC statistics, without brightness. On Android testSpeaker plays a real tone and speakerTest() also returns the media volume (0 → advice speaker-muted). Advice codes: network-bad, network-poor, network-no-video, network-unreachable, mic-silent, mic-permission, mic-missing, mic-busy, speaker-no-output, speaker-muted, speaker-low, speaker-blocked, camera-permission, camera-missing, camera-busy, camera-open-failed, camera-no-frames, camera-frozen, camera-low-fps, camera-low-resolution, camera-too-dark, camera-too-bright. Each test also exists alone:

import { testNetwork, testMicrophone, testSpeaker } from '@ilorb/signal'

const net = await testNetwork('https://api-signal.ilorb.app')
// { rttMs, downKbps, upKbps, quality: 'excellent' | 'good' | 'poor' | 'bad', maxCameras }

const mic = await testMicrophone({ durationMs: 3000 })   // ask the user to speak
// { ok, peak, average }   levels 0–1; ok = something above silence

const played = await testSpeaker()   // 1 s tone, the user confirms (browser; Android with the native package)

testNetwork measures the round trip to the nearest Cloudflare edge (median of 5) and the download/upload speed against /v1/probe. maxCameras is how many cameras at ~400 kbps fit in the download. testMicrophone uses a local WebRTC loop on the device, so it behaves the same in React Native and in the browser; in React Native pass webrtc as in the VoiceClient.

Reconnection & diagnostics

When the network drops, the SDK reconnects by itself (attempts at most 4 s apart) and republishes your microphone and camera. If the server notices that your microphone track was lost on the media server, it asks the SDK to republish it automatically. When your app knows the internet is back (React Native: NetInfo), call reconnectNow() to skip the wait.

NetInfo.addEventListener((s) => { if (s.isConnected) voice.reconnectNow() })

const voice = new VoiceClient({
  serverUrl: 'https://api-signal.ilorb.app',
  webrtc,
  device: { brand: Device.brand, model: Device.modelName, os: `android ${Device.osVersion}`, appVersion: '1.8.0' },
})

const info = voice.getConnectionInfo()
// { socket, receive: { connection, ice }, publish, camera, lastError, muteLeaks, republishes }

Per-device diagnostics. Every 30 s (and when leaving) the SDK sends a summary of the connection: what it sends and receives, how many voices, time with no audio, loss, delay, drops and automatic fixes. The console shows it in Develop → Diagnostics, grouped by device model and by person, so you can see which phones have trouble without asking users for logs. Pass device so React Native sessions are grouped by model; turn it off with sendStats: false.

Console: Live

Console → Live lists the rooms open right now. Open one to see each person, refreshed every 10 s, from the latest stats sample their SDK sent: device and app version, microphone open or muted, publishing, send / receive kbps, loss, RTT, concealed audio, reconnects, muted-microphone leaks, republishes and the last error. In red: loss above 5%, receiving nothing while someone is speaking, muted microphone leaking, app version below the minimum, and a call or media volume of 0–2.

Each person also shows the SDK's live blocks of that sample — on Android, iOS and the browser, with no code in your app: Echo now (the canceller running, AEC3 echo return loss / enhancement, the echo meter's likelihood and coupling over the last window), Voice now (microphone level in dBFS, speech level and share of the window with speech, native AGC gain, the noise AI running), Device now (network type and changes, app CPU, thermal state, free memory, battery, power saving), Video now (camera wanted / published, outgoing size, fps, kbps and limitation, light mode, the cameras received: fps, loss, kbps, smallest height, frozen) and Effects (ILORB FX fps, ms per frame, face detection ms, delegate, size, effects on). Fields a platform cannot measure are null (see stats values). In red also: echo heard (likelihood above 0.5), a hot device (thermal 3 or more), a frozen received camera and a camera the app asked for that is not published. With no diag from your app, the SDK's own summary (noise AI, echo canceller, NS/AGC, bitrate, scenario, device profile) is shown as the person's diag.

Volume, audio route, echo canceller and OTA version come from your app, not from the SDK: send them as a room message with the topic diag and the console shows the latest one per person. Any JSON works; keys containing vol, route, echo/aec and ota are shown in their own rows, the rest under "app diag".

voice.sendRoomMessage(JSON.stringify({
  version: 112, ota: '2026-10-21.3',
  volume: { call: 9, media: 6 }, route: { call: 'speaker' },
  echo: { mode: 'hw', residualDb: -32.5 },
}), 'diag')

Other people in the room also receive this message (roomMessage with topic diag); ignore that topic in your UI.

Console → Quality turns the same stats into a 1–5 score per connection (MOS-style, a simplified ITU-T G.107 E-model from round-trip time, loss and concealed audio; a connection that received nothing while others spoke scores 1), by day, by room and by device model, worst first. The formula is shown on the page.

React Native

import { mediaDevices, MediaStream, RTCPeerConnection } from '@livekit/react-native-webrtc'
import { VoiceClient } from '@ilorb/signal'

const voice = new VoiceClient({
  serverUrl: 'https://api-signal.ilorb.app',
  webrtc: { RTCPeerConnection, mediaDevices, MediaStream },
})

Android needs the RECORD_AUDIO permission (and MODIFY_AUDIO_SETTINGS); iOS needs NSMicrophoneUsageDescription.

Native audio processing (@ilorb/signal-react-native-audio)

Our voice processing on the device, after the system echo canceller. Without the native module in the app, VoiceClient keeps working with the standard WebRTC audio, and every call below returns without doing anything.

import { IlorbAudio } from '@ilorb/signal-react-native-audio'

await IlorbAudio.configure({
  noise: 'ai',              // AI noise reduction (DeepFilterNet on Android arm64, RNNoise otherwise)
  noiseStrengthDb: 24,       // 12 soft · 24 medium · 100 no limit
  agc: true, clarity: true, highPass: true, howlingSuppression: true,
  echoResidual: 'simple',    // BETA, Android: lowers the mic when it only hears the others
})
// turn off the WebRTC versions you replaced
await voice.setAudioOptions({ noiseSuppression: false, autoGainControl: false })

await IlorbAudio.setVoiceChanger('robot')     // 'off' | 'robot' | 'child' | 'maleToFemale' | 'femaleToMale' | 'monster'
await IlorbAudio.setReverb('concert', 0.3)    // 'off' | 'room' | 'studio' | 'concert' | 'church', mix 0..1

// iOS: in-ear monitoring (only with headphones)
const voice = new VoiceClient({ serverUrl, webrtc, hooks: { prepare: () => IlorbAudio.prepareEarMonitoring() } })
await IlorbAudio.setEarMonitoring(true, 0.8)

Screen sharing (@ilorb/signal-react-native-screen) PREVIEW

Captures the screen as a WebRTC video track (@livekit/react-native-webrtc ≥ 144) for startScreenShare. Video only: the system sound is not captured; the voice keeps going through the microphone. Built for both platforms; not yet tested on real phones (the iOS extension protocol is tested on the Mac).

import { ScreenCapturePickerView } from '@livekit/react-native-webrtc'
import { IlorbScreen } from '@ilorb/signal-react-native-screen'

const picker = useRef(null)
<ScreenCapturePickerView ref={picker} />      // iOS opens the broadcast picker through it; can be invisible, 1×1

await voice.startScreenShare({ capture: () => IlorbScreen.start({ pickerRef: picker }), stopTrackOnEnd: true })
// by hand: const share = await IlorbScreen.start({ pickerRef: picker }) → { stream, track } … IlorbScreen.stop(share)
// Android: await IlorbScreen.stats(share) → captured frames, size, single-app content

ILORB FX (video effects) BETA

ILORB FX is our video effects engine: color filters, beauty, makeup, face shape, background, 3D stickers, animated overlays and an avatar, applied to the camera on the device, before the encoder. It is a separate package (@ilorb/signal-react-native-fx) with its own license, and works with any react-native-webrtc camera track — with or without ILORB Signal rooms.

License. One line of text, OFX1.<payload>.<signature>: the payload (base64url JSON) lists the app IDs it accepts (iOS bundle ID and/or Android applicationId), the features and the expiry; the signature is ECDSA P-256 / SHA-256. ILORB FX is a subscription per app: in the console, Project → ILORB FX, pick the packages and request it; once ILORB Signal activates it, issue the license there (validity 1–730 days, default 365, never past the end of the subscription). Packages = features: lut color filters · beauty · makeup · reshape face shape · background blur/replace · sticker 3D stickers, animated effects, text balloon and face paint · avatar (all but lut are beta; sticker overlays and avatar are Android only for now; face, makeup and background run on iOS in the simulator, not yet tested on an iPhone). The subscription is per app, in the console menu Effects. The engine verifies it offline with an embedded public key: signature, expiry and the installed app's ID. A license copied into another app does not work; editing the payload breaks the signature. Because the check is offline, revoking in the console does not switch off apps already shipped with that license — it stays valid until it expires.

import { IlorbFx } from '@ilorb/signal-react-native-fx'

const { ok, reason } = IlorbFx.setLicense(LICENSE)   // reason: 'format' | 'signature' | 'expired' | 'bundle'
IlorbFx.setFilter(IlorbFx.FILTERS.warm, 1)             // filter + intensity 0..1
IlorbFx.setFilter(null)                                // no filter

// ILORB Signal camera (VoiceClient)
voice.setCameraEffects([IlorbFx.PROCESSOR])
// or any react-native-webrtc video track
track._setVideoEffects(['ilorb-fx'])

Recurring licence (monthly or yearly) BETA

ILORB FX is billed as a recurring licence per app: monthly, or yearly with a discount (prices per package and the yearly discount are set by ILORB Signal and shown in Console → Effects). Subscribe there with a card (Stripe Checkout); change the card, see invoices or cancel in the billing portal; switch monthly → yearly in one click (Stripe credits what is left of the month). The licence you issue never runs past what is paid, so a monthly plan means a fresh licence every period. Let the SDK keep it current with two calls, both with the current licence in x-ilorb-fx-license (an expired one is accepted, up to 400 days old):

// the plan's state as the server sees it
GET  /v1/fx/license/status   → { app, license: { id, exp, valid, revoked }, subscription: { state, billing, interval, features, validUntil, graceUntil, cancelAtPeriodEnd }, action }
// action: 'keep' (licence fine) | 'refresh' (a newer one can be issued) | 'stop' (no paid plan)
POST /v1/fx/license/refresh  → { license, exp, reused, state }      // 402 subscription_suspended | subscription_canceled …

States: active · grace (a renewal payment failed: everything keeps working for the grace period while Stripe retries; a licence refreshed now ends with the grace) · suspended (grace over: the server refuses the licence — 402 subscription_suspended on the catalogue and the device report — and the device stops when its licence expires) · canceled (the app's licences are revoked on the server). Paying the open invoice turns it back to active at once. Call status on app start and once a day; on refresh, call refresh and pass the new licence to IlorbFx.setLicense.

Without a valid license the video passes through unchanged (no effect, no error in the call). For debugging, POST /v1/fx/verify with { "license": "OFX1…" } returns { ok, reason, payload } (signature and expiry only; the app ID is checked on the device).

Video enhancement: low light, denoise, sharpen, super resolution BETA ANDROID iOS

Video quality, not an effect: no license needed. lowLight lifts a dark scene automatically (the frame's average brightness decides how much; a bright scene is left alone), denoise removes the grain a phone sensor makes in the dark (it follows the lift), sharpen brings detail back. Each 0..1. It runs on the GPU before the filter and the face effects; on the CPU path only the low-light lift runs. superRes (0..1, off by default) is super resolution: a camera that gives less than upscaleTo pixels on its long side (default 960 — e.g. a cheap phone's 640×480 front camera) is brought up to it as the last step, with an edge-preserving upscale and a contrast-adaptive sharpen of that strength that never makes halos. It is closer to the real full-size picture than the stretch the viewer's screen would do (emulator: SSIM 0.964 → 0.981 against the same scene filmed at full size). Not machine learning; Android GPU path and iOS.

import { IlorbFx, FX_ENHANCE_DEFAULT } from '@ilorb/signal-react-native-fx'
IlorbFx.setEnhance(FX_ENHANCE_DEFAULT)                // { lowLight: 0.6, denoise: 0.5, sharpen: 0.25 }
IlorbFx.setEnhance({ ...FX_ENHANCE_DEFAULT, superRes: 0.5 })  // + a small camera brought up to 960
IlorbFx.setEnhance(null)                              // off

Face, makeup, image & background BETA

setFace replaces the whole set: send everything you want on; {} turns it all off. Strengths are 0..1 (shape values marked −1..1 go both ways). Each group only works with its package in the license; the result tells which ones were applied.

const applied = IlorbFx.setFace({
  beauty:  { smooth: 0.6, whiten: 0.3, acne: 0.5, darkCircles: 0.4, sharpen: 0.2 },
  makeup:  { lipstick: { color: '#c2405a', intensity: 0.5 }, blush: { intensity: 0.3 }, lashes: { intensity: 0.6, style: 'curl' } },
  reshape: { slimFace: 0.3, bigEyes: 0.2, chin: -0.1 },
  image:   { temperature: 0.1, brightness: 0.05, saturation: 0.1, contrast: 0.05 },
  background: { mode: 'blur', source: 'person', amount: 0.8 },   // 'none' | 'blur' | 'image' | 'mosaic'; source 'green' = green screen
})   // { beauty, makeup, reshape }: false = not in the license

await IlorbFx.setBackgroundImage(jpegBase64)              // for background.mode 'image'
IlorbFx.setFace({ ...FX_LOOKS[0].face, beauty: { smooth: 0.5 } })  // ready-made makeup looks
const preview = await IlorbFx.processImage(photoBase64)        // "try on a photo" → JPEG base64

FX_LOOKS (full makeup looks), FX_BEAUTY_PRESETS, FX_FACE_SHAPES and FX_SKIN_TONES are exported for building your menu. Call IlorbFx.release() when leaving the live; it also happens by itself 15 s after the camera stops.

Stickers & overlays BETA ANDROID

All in the sticker package. Each call with null removes it.

// 3D model on the head (.glb in base64). anchor = face landmark 0–467, sizes in cm
await IlorbFx.setSticker({
  anchor: 1, width: 6, offset: [0, 0, 1], rotation: [0, 0, 0], occlude: true,
  react:   { shape: 'jawOpen', offset: [0, -1, 0], scale: 0.2 },   // follows an expression
  animate: { bob: 0.3, speed: 1 },                              // spin, bob, pulse, sway
}, glbBase64)
await IlorbFx.setStickerConfig({ anchor: 1, width: 7, offset: [0, 0.5, 1], rotation: [0, 0, 0] })   // adjust live

// animated 2D effects: up to 8 items and 60 particles
await IlorbFx.setParticles({ items: ['❤️', '💖'], motion: 'orbit', area: 'head', count: 10 })   // orbit | rise | twinkle | fall

// text balloon on the head or fixed on the screen
await IlorbFx.setTextBalloon({ text: 'Hi!', pin: 'head', background: '#ffffff', textColor: '#111111', tail: true })

// face paint: PNG drawn on the front face template (512×584); follows mouth and head
await IlorbFx.setFacePaint(pngBase64, 0.9)

Avatar BETA ANDROID

A mascot that mimics the face in real time (package avatar). 'studio' covers the whole frame — an avatar live where the person does not appear; 'overlay' puts it in place of the head. Feed the voice level and the mouth moves even with no face on camera.

await IlorbFx.setAvatar({ mode: 'studio', style: 'cute', hairStyle: 'bun', accessory: 'glasses', ears: 'cat', background: '#20263a' })
voice.on('localSoundLevel', (level) => IlorbFx.setAvatarVoiceLevel(level / 100))   // ~10×/s, 0–1
await IlorbFx.setAvatar(null)

Remote effects & catalogue BETA ANDROID

Effects are data, not code: an effect package is a JSON manifest in the same parameter model as the setters above (FxFace, a 17³ color LUT, a 3D sticker .glb + placement, a face-paint PNG, particles, hair color) plus its files. The app lists your project's catalogue, downloads an effect on demand, checks it and applies it — a new effect ships without an app build. Every manifest is signed by ILORB Signal (ECDSA P-256 over OFXP1.<manifest>, verified with the key already embedded in the engine) and lists the SHA-256 of each file; nothing is cached or applied unless the signature and every hash check out. Effects are cached in the app's files folder, re-checked before use (a damaged file is downloaded again) and still load offline. The license you set with setLicense authenticates the catalogue calls and says which project's catalogue to list.

IlorbFx.setLicense(LICENSE)
const cat = await IlorbFx.catalog()          // { categories, items: [{ id, name, category, kind, version, bytes, thumbUrl, cache: 'none' | 'current' | 'stale' }] }
const fx = await IlorbFx.loadEffect('look-glam-night')   // download → verify → cache (FxEffectError: signature | hash | network | not_found …)
await IlorbFx.applyEffect(fx)                     // setFace / setFilter / setSticker / setFacePaint / setParticles; parts it lacks stay as they are
IlorbFx.effectCache()                              // { packages: [{ id, versions }], assets, bytes }
IlorbFx.clearEffectCache('look-glam-night')       // or () for everything

Console → Effect catalogue: the house catalogue (looks, lipsticks, color filters, skin tones, hair colors, 3D stickers, face paints, particles, packs — over 200 effects) with thumbnails; switch any of them off for a project, or create your own in the editor (sliders and color pickers for the same parameters, .cube LUT upload, face-paint PNG and sticker .glb upload, live preview on a test photo — an approximation in the browser; the phone is the reference). Saving publishes a new signed version; apps see it on their next catalog() (the item says 'stale' where an older version is cached). REST, with the license in x-ilorb-fx-license: GET /v1/fx/catalog · GET /v1/fx/packages/{id}[/{version}] → { manifest, signature } · GET /v1/fx/blobs/{sha256}. iOS: catalog() works; loadEffect answers unavailable for now.

Makeup map BETA

59 makeup models, each approved by eye on our effects demo and then matched by the SDK on the same photo (mean colour difference ΔE under 2 over the face): blush (11), lipstick (5), eyeshadow (6), eyeliner (5), lashes (5), contour (2), skin (4), lenses (4), complete looks (1), freckles (1), highlighter (5), brows (3) and makeup-map stickers (7). On Android the map renders live: the masks are built once and warped through the face mesh on the GPU every frame — 0.6–1.2 ms per effect per frame on the emulator (720×960), a complete look 1.2 ms. iOS has the same placement, curves and lash strip (Simulator).

ILORB FX is a separate subscription per app; ask us which looks are in your license.

Web effects (@ilorb/signal-web-fx) BETA BROWSER

Voice effects, a music player and camera effects for the browser SDK, with the same names as the React Native packages, so code moves between them by changing the import. The voice chain is our native C chain ported to an AudioWorklet; the camera effects run on WebGL2 + MediaPipe.

import { VoiceClient } from '@ilorb/signal'
import { ilorbWebRTC, ilorbAudioHooks, IlorbAudio, IlorbMediaPlayer, IlorbMusicTrack, IlorbFx, FILTERS } from '@ilorb/signal-web-fx'

const voice = new VoiceClient({ serverUrl, webrtc: ilorbWebRTC(), hooks: ilorbAudioHooks() })
await IlorbAudio.setVoiceChanger('robot')
await IlorbMediaPlayer.load('/song.mp3'); await IlorbMediaPlayer.start()
await voice.startMusicTrack(IlorbMusicTrack)          // optional: the music on its own track
await IlorbFx.setFilter(FILTERS.warm)
IlorbFx.setFace({ makeup: { lipstick: { color: '#c96f7e', intensity: 0.7 } } })

Demo page and a two-browser test: examples/web. Background blur/replace is native-only for now.

Platforms & native SDKs

The TypeScript / React Native SDK is the reference and the only one used in production. The others expose the same functions with the same names; where each one stands (2026-11-02):

Desktop: Electron, .NET and Unity

Electron (@ilorb/signal-electron, macOS and Windows) BETA — the web client + web-fx plus what only a desktop app has: OS media permissions, a screen picker (desktopCapturer) with the computer's sound where the OS allows it, device auto switching, call notifications and the tray. Tested on macOS against the development server (29/29, also packaged); the Windows build is packaged but has not been run on Windows yet.

// renderer
import { createElectronVoiceClient } from '@ilorb/signal-electron'
const ilorb = createElectronVoiceClient({ serverUrl: 'https://api-signal.ilorb.app' })
await ilorb.ensurePermissions()                    // macOS asks for mic + camera
await ilorb.voice.joinRoom(room, token, { name })
const sources = await ilorb.screen.sources()       // your picker
await ilorb.screen.start({ sourceId: sources[0].id, systemAudio: true })
// main process: setupIlorbMain from '@ilorb/signal-electron/main'; preload: '@ilorb/signal-electron/preload'

.NET (packages/dotnet, netstandard2.1 + net8.0) PREVIEW — room signaling, room messages, attributes, chat and the server-side token, no media; tested on the Mac against the development server. Unity (com.ilorb.signal.sdk, the same C# core) — the core is tested; the voice/video layer over com.unity.webrtc is written but has not been compiled in the Unity editor yet. A native Windows media SDK (without Electron) is a plan only.

var voice = new IlorbRoomClient("https://api-signal.ilorb.app");   // Unity: events arrive on the main thread
voice.RoomMessage += (from, text, topic) => Debug.Log($"{from}: {text}");
await voice.JoinRoom(room, tokenFromYourServer, playerName);
await voice.SendRoomMessage("gg");

In-app chat BETA

Messages, groups and call invitations inside your app, with the same user token as the rooms. @ilorb/signal-chat runs in React Native and the browser.

Subscription by MAU. Chat is billed by monthly active users — see subscription by MAU. Pricing coming soon; nothing is charged today.

import { ChatClient } from '@ilorb/signal-chat'

const chat = new ChatClient({ serverUrl: 'wss://chat-signal.ilorb.app' })
chat.on('message', (m) => append(m))                       // new message (also mine, from another device)
chat.on('conversationChanged', (c) => updateRow(c))          // unread count, last message…
chat.on('tokenWillExpire', async () => chat.renewToken(await tokenFromYourServer()))

await chat.login('ana', token)            // createUserToken without roomId
await chat.updateUserInfo({ name: 'Ana', avatarUrl: 'https://…' })
await chat.sendText('peer', 'bruno', 'hi!')
const { conversations } = await chat.queryConversations()
const { messages, hasMore } = await chat.queryHistory('peer', 'bruno', { limit: 30 })
await chat.markAsRead('peer', 'bruno')

A conversation is (conversationType, conversationId): peer with the other person's userId, or group with the groupId.

Rules: revoke and edit your own messages within 24 h (group owner/admin can revoke any); up to 20 pinned messages per group; 10 messages/s per person. History is kept on the server, and optionally on the device. Public channels for very large audiences and message translation: below (preview).

Offline history & send queue

Give the client a storage and it keeps the conversation list and the latest messages on the device: the app opens with them even without network, and messages sent offline wait in a queue that survives closing the app.

import { ChatClient, indexedDBStorage, asyncStorageAdapter } from '@ilorb/signal-chat'
import AsyncStorage from '@react-native-async-storage/async-storage'   // React Native (your app installs it)

const chat = new ChatClient({ storage: asyncStorageAdapter(AsyncStorage), cache: { maxMessagesPerConversation: 50 } })
await chat.login('ana', token, { waitForConnection: false })   // returns right away: opens without network
chat.getCachedConversations()                                 // the list, immediately
await chat.getCachedHistory('peer', 'bruno')                   // the latest N + queued ones (pending: true)
chat.on('synced', reload)                                      // connected and the cache is up to date
chat.on('pendingMessageSent', (m) => replace(m.localId, m))      // a queued message went out
await chat.logout()                                            // clears the cache ({ keepCache: true } keeps it)

Public channels & translation PREVIEW

A channel is public: anyone in your app finds it, reads it and joins it without an invite. A channel message is stored once and broadcast through socket shards — no per-member inbox and no unread counter per member — so one channel can hold a very large audience. The SDK opens a live socket per joined channel, reconnects it and catches up by seq after a drop.

const { channels } = await chat.searchChannels({ keyword: 'music' })
const { info, messages } = await chat.joinChannel(channels[0].channelId)   // live from now on
chat.on('channelMessage', (m) => show(m))              // m.senderName comes with it
await chat.sendChannelText(info.channelId, 'hi all')
const t = await chat.translateMessage(messages[0], 'pt')       // t.text, cached for everyone

Limits: 50 messages/s per channel (error rate_limited), 10/s per person, the newest 10,000 messages kept, up to 200 joined channels per person. Errors: not_member, channel_deleted, translation_unavailable.

Push (app closed)

Register the device's push token and the chat decides when to notify; your server delivers through its own FCM / APNs (webhook mode).

await chat.setPushToken('fcm', fcmToken, deviceId, 'en')          // Android
await chat.setPushToken('apns', apnsToken, deviceId, 'en')        // iPhone: messages
await chat.setPushToken('apns-voip', voipToken, deviceId, 'en')   // iPhone: calls (PushKit → CallKit)
await chat.setPushSettings({ showPreview: false, mutedUntil: 0 })
await chat.logout()                                                 // removes this device's token ({ keepPushToken: true } keeps it)

Rules: only when the user has no device connected; muted conversations don't notify; 1:1 right away; groups are batched per conversation (3 s); a call invitation is high priority (VoIP on iPhone) and a cancelled or unanswered one becomes "missed call". Up to 10 devices per user; texts in en / pt / es by the device locale. Also removePushToken(deviceId). Your server receives a signed chat.push callback:

{ "event": "chat.push", "userId": "davi", "kind": "message | call | call_missed | test", "priority": "normal | high",
  "devices": [{ "deviceId": "ios-1", "provider": "apns", "token": "…", "locale": "en" }],
  "title": "Ana · Group", "body": "three (3 new messages)", "badge": 5, "collapseKey": "group:pushg",
  "data": { "conversationType": "group", "conversationId": "pushg", "seq": 9, "messageId": "m_…", "count": 3 },
  "raw": { "senderName": "Ana", "conversationName": "Group", "preview": "…", "count": 3 } }

devices is already filtered (VoIP only for calls); use raw to build your own text. Test it with POST /v1/server/push/test { userId }.

Delivering it: new PushSender({ fcm, apns }).send(body) from @ilorb/signal-server/push sends it through your own Firebase project (FCM HTTP v1; calls are data-only, high priority, with the invitation's TTL) and Apple key (calls as VoIP pushes to <bundle>.voip, everything else as alerts). A result with unregistered: true means the token is dead (app uninstalled): send those tokens to POST /v1/server/push/unregister { userId, tokens } and the chat stops using them. The sample server in examples/web/callbacks.mjs does both.

Call invitations

Ring someone, then everyone joins an ILORB Signal room. The room token still comes from your server.

// caller
const call = await chat.callInvite(['bruno', 'carla'], { roomId: 'call-123', timeoutSeconds: 60, extendedData: '{"type":"video"}' })
chat.on('callUserStateChanged', ({ call, users }) => render(users))   // inviting | accepted | rejected | cancelled | timeout | quit
chat.on('callEnded', () => voice.leaveRoom())

// callee
chat.on('callInvitationReceived', async ({ call }) => {
  await chat.callAccept(call.callId)
  await voice.joinRoom(call.roomId, await roomTokenFromYourServer(call.roomId))
})

Also callReject, callCancel, callingInvite (add people mid-call), callQuit (leave without ending), callEnd, queryCallInfo, queryCallList. Up to 10 invitees per call to callInvite, 50 per call; timeout 5–600 s. A user who was offline gets a still-valid invitation when they connect; a phone with the app closed is rung by a high-priority push (VoIP on iPhone).

Chat server API

From your server, with the same Basic auth as the rooms:

Callbacks go to the project's callback URL, signed like the room ones: chat.message.review (hook review, before saving; answer { action: 'allow' | 'reject' | 'replace' } within 2 s), chat.message.sent (hook notify), chat.message.reported, chat.call.created, chat.call.ended, chat.push. The server SDKs wrap all of these.

Subscription by MAU

Chat is a subscription per project billed by monthly active users: each user who logs in to the chat counts once per month (UTC) in that project, however many devices and logins. The structure follows the usual MAU model:

See it in Console → Chat (this month and previous months per project, the plans, and a subscription request) and in each project's Chat tab. Above the quota the console only warns — nothing is blocked. Payment is not in the console yet: a request stays "awaiting payment" until ILORB Signal activates it. From your server: GET /v1/server/mau.

UIKit for React Native PREVIEW

Five ready-made screens on top of ChatClient and VoiceClient: @ilorb/signal-react-native-uikit. Only react and react-native — no icon or navigation library — and the video is drawn by your app. Also runs in the browser through react-native-web.

import { UIKitProvider, ChatList, ChatThread, CallScreen, AudioRoom, LiveVideo, darkTheme } from '@ilorb/signal-react-native-uikit'
import { RTCView } from '@livekit/react-native-webrtc'

const renderVideo = ({ stream, mirror, style }) => <RTCView streamURL={stream.toURL()} mirror={mirror} objectFit="cover" style={style} />

<UIKitProvider theme={darkTheme}>
  <ChatList chat={chat} onOpen={(c) => open(c)} />
  <ChatThread chat={chat} conversationType="peer" conversationId="ana" title="Ana" onBack={back} />
  <CallScreen chat={chat} voice={voice} invitees={['ana']} getRoomToken={(roomId) => myServer.token(roomId)} onClose={close} />
  <AudioRoom voice={voice} roomId="room-1" token={token} hostId="host" onLeave={leave} />
  <LiveVideo voice={voice} roomId="live-1" token={token} renderVideo={renderVideo} onLeave={leave} />
</UIKitProvider>

• Theme: lightTheme / darkTheme, or your own — even just the brand color: { ...lightTheme, colors: { ...lightTheme.colors, primary: '#E85D04' } }.
• Texts: English by default; ptBR is included; override any key with strings={{ send: 'Go' }}.
• Clients: the screens only need the shape (ChatLike, VoiceLike): the real ChatClient and VoiceClient fit directly, and a fake one works for tests and demos.
• Answering a call: chat.on('callInvitationReceived', ({ call }) => show(<CallScreen call={call} … />)). With the app closed, the call push brings it up (CallKit / full-screen on Android).
• Raise hand uses room messages with the topic uikit: { t: 'hand' | 'invite' | 'down' }.
• Offline history: with ChatClient({ storage }), ChatList and ChatThread show the cache immediately (even offline); messages sent offline show 🕓 until they go out, and "!" if the server refused them.

Not yet: sending photo / audio / file from ChatThread (uploadMedia exists; the picker depends on your app's library), PK and cloud mix in LiveVideo.

Server REST reference

All endpoints use Basic auth with the project credentials and return JSON with an ok field. Errors return { ok: false, error } with HTTP 4xx.

Account balance

{
  "ok": true,
  "tenantId": "ten_3f9a…",
  "status": "active",          // active | suspended
  "creditSeconds": 5400000,     // participant-seconds
  "creditMinutes": 90000,
  "usage": [{ "app_id": "app_…", "day": "2026-10-20", "seconds": 41220 }]   // last days, per project
}

Live rooms of the project

{ "ok": true, "rooms": [
  { "room_id": "room-42", "participants": 18, "publishers": 4,
    "started_at": "2026-10-20T13:00:00Z", "updated_at": "2026-10-20 13:41:10" }
] }

Who is in a room

{ "ok": true, "roomId": "room-42", "startedAt": "2026-10-20T13:00:00Z",
  "people": [{ "userId": "42", "name": "Ana", "publishing": true, "micOpen": false }] }

Remove a person

curl -u "$ID:$SECRET" -X POST https://api-signal.ilorb.app/v1/rooms/room-42/kick \
  -H 'content-type: application/json' -d '{"userId":"42"}'

The person stops hearing and speaking immediately (their tracks are closed on the media server) and receives the kicked error. Returns 404 not_in_room if they are not there. Remember to stop issuing tokens for that room to them, or they can join again.

Close a room

{ "ok": true, "removed": 18 }

Everyone receives room_closed and is disconnected. The room's attributes are deleted. The room id can be used again afterwards.

Room & member attributes

{ "room": { "topic": "Final", "seat1": null },          // null deletes
  "members": { "bruno": { "role": "vip" } },              // people in the room now
  "writers": "admin" }                                 // 'everyone' (default) | 'admin'
// → { "ok": true, "attributes": { "topic": "Final" }, "writers": "admin", "members": { "bruno": { "role": "vip" } } }

All fields are optional; everything is checked before anything changes. Works on an empty room too (set the topic before anyone joins). Everyone receives the changes with by: '__server'. Errors: 400 attrs_invalid, 413 attrs_too_large, 404 not_in_room (a member who is not there). GET /v1/rooms/{roomId} returns attributes, attributeWriters and members (each person's attributes).

Cloud recording BETA

Records the room as one video: the grid of cameras with every voice mixed (720×640 by default), in MP4 chunks (H.264 + Opus) of up to 60 s stored by ILORB Signal. Starting a recording turns on the room's composition by itself; it stops by itself when the room empties.

{ "action": "start", "segmentSeconds": 60 }          // or { "action": "stop" }; segmentSeconds 5–300
// → { "ok": true, "recording": { "id": "mviv1a2b", "startedAt": "2026-10-21T22:00:00.000Z", "seconds": 0 } }

Starting again while it records returns the same recording. Errors: 409 (the room is empty), 503 recording_unavailable, 502 mixer_failed. GET /v1/rooms/{roomId} shows recording while it runs.

{ "ok": true, "recordings": [{
  "roomId": "room-1", "id": "mviv1a2b", "startedAt": "2026-10-21T22:00:00.000Z",
  "seconds": 127.5, "bytes": 23110421,
  "files": [{ "name": "seg-0000-00000.mp4", "size": 10893212, "duration": 60, "uploaded": "…" }, …]
}] }

Newest first. Play the files in order (each is a complete MP4). duration is read from the file itself; seconds is their sum. Each recording has kind: "room" (the mix) or "person" (with the userId, see below).

Per-person recording

Records each person separately: their own voice and their own camera (or screen) in their own MP4 chunks (H.264 640×480 + Opus; audio only for someone with no camera). It runs alongside the room recording and the mix, and does not need either of them.

{ "action": "start", "scope": "person" }                          // everyone publishing, and whoever starts publishing later
{ "action": "start", "scope": "person", "userIds": ["ana"] }      // only these people
{ "action": "stop", "scope": "person", "userIds": ["ana"] }       // stop these; without userIds: stop all
// → { "ok": true, "started": ["ana", "bia"], "everyone": true,
     "personRecordings": [{ "userId": "ana", "id": "mvyiljsspqed", "startedAt": "…", "seconds": 0, "inRoom": true }] }

Each person gets their own recording id; listing, download, delete and retention work as for the room recording. Someone stopped one by one is not picked up again by "everyone" until you start them by userIds. Someone who leaves keeps their recording open for 60 s (a reconnection continues it), then it stops; an empty room stops them all. Errors: 404 not_in_room (none of the userIds is in the room), 409 (empty room), 503 recording_unavailable, 502 mixer_failed. GET /v1/rooms/{roomId} shows personRecordings and personRecordingEveryone. Callbacks: recording.person.started and recording.person.stopped. Server SDKs: RoomsClient.record_person() (Python) and RecordPerson() (Go).

Mix layout

The room mix (and so the room recording and RTMP) uses a grid by default. POST /v1/rooms/{roomId}/mix { "action": "start", "layout": "focus", "focusUserId": "ana" } puts one person big on top and the others in a strip below; { "action": "layout", "layout": "grid" | "focus", "focusUserId"? } changes it while it runs. GET /v1/rooms/{roomId} → mix.layout, mix.focusUserId.

The MP4 file. Supports Range, so a <video> can seek.

{ "ok": true, "deleted": 3 }                      // files removed; 404 if there is no such recording

Retention. Each project keeps recordings for 30 days by default; change it in Console → Recordings (0 = keep forever). Once a day (03:00 UTC) recordings that started earlier than that are deleted. Console: Develop → Recordings lists them by project, room and date, plays the chunks one after the other, downloads and deletes; Live has a Record / Stop button for an open room. Callbacks: recording.started and recording.stopped (below). Recording is not billed during the beta.

Content moderation BETA

Live video and audio are checked while people publish. The SDK samples by itself: a JPEG frame of the camera every video.intervalSeconds and an audio clip of audio.clipSeconds every audio.intervalSeconds, only while that track is published and open. Pick one of three ways to judge them, per project (Console → project → Moderation, or the API below):

Keys are stored encrypted and never returned (only a hint). Provider test (deterministic: the scores come from test.nudity / test.transcript) exists for automated tests. Only violations and webhook checks keep their media (30 days).

{ "mode": "provider", "threshold": 0.8, "banMinutes": 1440,
  "video": { "enabled": true, "intervalSeconds": 15, "action": "takedown", "takedownMinutes": 10 },   // action: takedown | report
  "audio": { "enabled": true, "intervalSeconds": 30, "clipSeconds": 8, "action": "review", "bannedTerms": ["…"] },  // action: review | auto_ban
  "provider": { "name": "sightengine", "key": "api_user:api_secret" }, "speech": { "name": "deepgram", "key": "…" },
  "ai": { "provider": "openai", "key": "…", "model": "gpt-4o-mini", "baseUrl": "https://api.openai.com/v1" },
  "webhook": { "url": "https://your-server.com/ilorb/moderation" } }     // partial updates; "key": null removes a key

Basic appId:appSecret. GET /v1/moderation/settings returns them (keys as hints) plus effective: what the room asks the SDK to sample. Open rooms pick changes up within 30 s.

Video. A frame at or above threshold is a violation. With takedown the room removes the camera at once (viewers lose it), the publisher's SDK fires streamTakenDown and startCamera is refused with stream_taken_down until takedownMinutes pass (0 = until you restore it). With report it only becomes a flag. Audio. A banned term or an abusive transcript becomes a pending flag: you approve or reject the ban (or set auto_ban).

{ "ok": true, "flags": [{ "id": "mf_…", "roomId": "live-1", "userId": "42", "kind": "audio", "source": "provider:deepgram",
  "score": 1, "reason": "banned terms: …", "transcript": "…", "matched": ["…"], "hasMedia": true,
  "status": "pending", "action": "none", "createdAt": "…" }] }   // status: checking | pending | confirmed | dismissed | clean

GET /v1/moderation/flags/{id} · GET /v1/moderation/flags/{id}/media (the JPEG or the clip).

{ "decision": "confirm" }   // audio: approves the BAN · video: takes the camera down if it was only reported; "ban": true bans too
{ "decision": "dismiss" }   // rejects: restores a camera that was taken down, lifts an automatic ban
// → { "ok": true, "status": "confirmed", "action": "ban" }

A banned user is removed from the room (the SDK gets moderationAction banned and the terminal banned error) and refused on join in every room of the project until banMinutes pass. GET /v1/moderation/bans · POST /v1/moderation/bans { userId, minutes?, reason?, roomId? } · DELETE /v1/moderation/bans/{userId}.

Webhook mode: answer the moderation.check right away in the HTTP response ({ "violation": true | false, "score"?, "reason"? }, within 8 s), or later here with the same body. A violation then follows the video/audio rules above.

// moderation.check (POST to your URL, x-ilorb-signature like the callbacks)
{ "event": "moderation.check", "checkId": "mf_…", "appId": "…", "roomId": "live-1", "userId": "42", "kind": "video",
  "contentType": "image/jpeg", "mediaBase64": "/9j/…", "mediaUrl": "https://api-signal.ilorb.app/v1/moderation/media/mf_…?exp=…&sig=…" }

SDK. Nothing to call: the room sends the config (moderationConfig event) and the SDK samples. On Android the native package @ilorb/signal-react-native-audio provides the capture (a camera frame processor that sees what viewers see, and the clip of what the mic sends after the voice chain); in the browser it uses the camera and mic tracks. An app may capture by itself with voice.moderation.setCapture({ frame, audio }); voice.moderation.stats shows what was sent. Events: moderationAction ({ action: 'stream_taken_down' | 'stream_restored' | 'banned' | 'warning', kind, reason, flagId, until }), streamTakenDown, streamRestored. Callbacks: moderation.flagged, moderation.stream_taken_down, moderation.user_banned, moderation.decided, moderation.samples_missing (a publisher whose SDK sends no samples). Demo: examples/moderation-demo.

Live Shop BETA

Live shopping on top of a live room: the host pins products of your own store during the live and every viewer sees the product card (name, image, price, stock, variants) in real time, then taps to open the product page or add it to the store's own cart. No payments in ILORB Signal: the checkout is your store's site. Stores: Shopify and Nuvemshop / Tiendanube, one per project (Console → project → Live Shop, or the API below).

Tokens are stored encrypted and never returned (only a hint).

{ "platform": "shopify", "domain": "my-store.myshopify.com", "token": "shpat_…", "storefrontUrl": "https://www.my-store.com" }
{ "platform": "nuvemshop", "domain": "my-store.lojavirtualnuvem.com.br", "storeId": "1234567", "token": "…" }   // "token": null removes it

Basic appId:appSecret. GET /v1/shop/store · DELETE /v1/shop/store · POST /v1/shop/sync (imports the catalogue now, up to 2,000 products) · GET /v1/shop/products?q=&limit=&offset= · GET /v1/shop/stats?days=7&room= (pins, opens and add-to-cart taps per product and per room).

{ "productId": "10568701444152", "variantId": "51436343066680" }   // variantId optional · also …/shop/unpin, …/shop/list { add?, remove?, list? }

The host's SDK (a token with admin: true) or your server (Basic). The server re-reads the product from the store (fresh price and stock), then writes the room attributes shop:pinned (a snapshot of the product, ≤ 1,024 characters: as many variants as fit) and shop:list (the live's product ids). Only the server writes shop:* keys: a client that tries gets attrs_denied.

// host
const { products } = await voice.shop.catalogue({ query: 'board' })
await voice.shop.pin(products[0].id)            // error not_host without an admin token
await voice.shop.unpin()
// everyone
voice.shop.on('pinnedProduct', (p) => showCard(p))          // null = unpinned; late joiners get it on join
voice.shop.on('productsChanged', (ids) => refreshBag(ids))  // voice.shop.liveProducts() = full details
const url = voice.shop.openProduct(p, { variantId, addToCart: true })   // counts the tap; you open the URL

PinnedProduct: id, title, url, image, price, compareAtPrice, currency, available, stock (null when the store does not publish it), variants, variantCount, variantsComplete, links { product, variant, cart }, pinnedAt, pinnedBy. voice.shop.getProduct(id) returns every variant. Demo: examples/live-shop-web.

Live gifts BETA

A viewer buys one gift with money for someone in the live — a one-time purchase through Stripe Checkout — and ILORB Signal delivers it into the room exactly once when the payment is confirmed: everyone in the room gets a room message with topic gift, and your server gets the gift.purchased callback (credit the recipient however your app does). A repeated or delayed payment event never shows a gift twice.

Console → Live gifts: add gifts from the ILORB Signal gift shop (animated gifts with a transparent background) and set each one's price (US$ 0.50 minimum; a gift with no price is not on sale). Orders and deliveries are listed there.

// with the viewer's room token (?token= or Authorization: Bearer)
GET  /v1/rooms/{roomId}/gifts                  → { available, testMode, gifts: [{ giftId, name, priceCents, currency, animationUrl, alphaLayout, thumbUrl }] }
POST /v1/rooms/{roomId}/gifts/checkout { giftId, to, successUrl?, cancelUrl? }  → { orderId, url, amountCents, currency }
// open url in the browser (in-app browser / Custom Tab); successUrl/cancelUrl: https, default a page that says "go back to the app"
GET  /v1/rooms/{roomId}/gifts/orders/{orderId} → { order: { status: 'pending' | 'delivered' | 'expired' | …, deliveredAt, viewers } }

// everyone in the room
voice.on('roomMessage', (from, text, topic) => {
  if (topic !== 'gift') return
  const g = JSON.parse(text)   // { orderId, giftId, name, animationUrl, alphaLayout, thumbUrl, from, to, amountCents, currency, at }
  playGift(g.animationUrl)        // alpha MP4, mask on the left (IlorbAlphaVideoView on React Native)
})

The buyer is the token's user; to is any userId (not the buyer). An unpaid Checkout expires after 31 minutes. Payments go to ILORB Signal's Stripe account; paying out to hosts is up to your app (the callback says who received what).

Billing & payments

Three ways ILORB Signal charges, all paid by card through Stripe in the console:

• Participant-minutes — prepaid top-up. Console → Billing: pick an amount, pay, the credit is added as soon as Stripe confirms (and a room refused for lack of credit opens right after). Rooms close with insufficient_credit at zero.
• ILORB FX — recurring licence, monthly or yearly with a discount, per app: see Recurring licence.
• Live gifts — one-time purchase by your viewers, delivered in the room: see Live gifts.

Every price is set by ILORB Signal in the admin panel (the gift prices by you, per project). Stripe sends its events to one signed endpoint; each event is applied once (by its id), events older than what was applied are ignored, and only test-mode events are accepted until live payments are switched on.

Cloud player BETA

Play a video or a song from the internet in the room, for everyone: a watch party, background music, a clip during a live. ILORB Signal fetches the URL, encodes it (H.264 + Opus) and publishes it in the room as the person __player. Every app receives it like anyone else: userJoined, videoTrackChanged and the voice. No change is needed in the app.

{ "action": "play", "url": "https://cdn.example.com/trailer.mp4", "loop": false, "volume": 0.8 }
{ "action": "pause" }   { "action": "resume" }   { "action": "seek", "ms": 20000 }   { "action": "stop" }
// → { "ok": true, "player": { "state": "playing", "positionMs": 0, "durationMs": 152000, "hasVideo": true, "hasAudio": true, "loop": false, … } }

Callbacks: player.started, player.paused, player.resumed, player.seeked, player.stopped, player.ended. The player is not billed during the beta (people in the room are billed as usual).

Viewers (audience) PREVIEW

For a live with a big audience, give the audience a viewer token: createUserToken({ …, role: 'viewer' }). A viewer watches and listens; it does not publish and nobody sees it in the list of people — the room only keeps a counter. Tokens without role behave exactly as before.

const voice = new VoiceClient({ serverUrl })
voice.on('viewersChanged', (n) => setAudience(n))      // everyone gets it, at most once per second
await voice.joinRoom(roomId, viewerToken)
voice.isViewer()        // true
voice.getViewerCount()  // how many viewers are in the room
voice.getReceiveMode()  // 'mix' while the cloud mix is on, otherwise 'individual'

Stream with OBS PREVIEW

A streamer goes live in a room from OBS Studio (game streaming, a capture card, a desktop studio). OBS 30+ publishes over WHIP straight into the room (sub-second, ~50 ms glass-to-glass measured); older OBS and other encoders use RTMP through the ILORB ingest gateway. The streamer shows up for everyone as the person __ingest:<userId> with a voice track and a camera (or screen) track, up to 1080p60 — a normal publisher: userJoined, videoTrackChanged, the voice, simulcast layers when the encoder sends them. No change is needed in the viewers' app. Full guide with the OBS settings: docs/STREAM-WITH-OBS.md.

// your server (Basic appId:appSecret) — any user and room; or the app with a room token created with ingest: true (only its own user)
{ "room": "live-42", "userId": "streamer-7", "kind": "camera" }   // no room = a per-user key (any room)
// → { "key": { "keyId": "ik_…", "secret": "osk_…", "ingestUserId": "__ingest:streamer-7", … }, "limits": { "maxWidth": 1920, "maxHeight": 1080, "maxFps": 60, "maxKbps": 6000 },
//    "obs": { "whip": { "server": "https://api-signal.ilorb.app/v1/ingest/whip/live-42", "bearerToken": "osk_…" }, "rtmp": { "server", "streamKey" } | null, "encoder": { … } } }

Callbacks: ingest.live (userId, streamer, keyId, protocol, tracks, videoCodec, simulcast) and ingest.ended (reason: stopped | revoked | kicked | disconnected | no_media | replaced | room_closed | insufficient_credit, durationMs). A live ingest is billed as one participant publishing; it goes into the cloud mix and recordings like a person.

OBS settings. Settings → Stream: Service WHIP, Server = obs.whip.server, Bearer Token = the osk_… secret. Output: x264 or a hardware H.264 encoder (NVENC, QuickSync, AMF, Apple VT), CBR 4,500 kbps for 720p60 or 6,000 for 1080p60, keyframe interval 1 s, no B-frames (bframes=0; NVENC: Max B-frames 0), tune zerolatency. HEVC/AV1 are refused (415).

Viewers see "live" 1.5–3.3 s after OBS connects; an OBS that crashes without stopping is removed in 41–61 s. Not proven yet: the real OBS Studio app and a gateway on a real server. Console: Develop → Stream keys creates and revokes keys and shows the OBS fields.

ILORB Live Studio BETA

Our desktop streaming app for creators (macOS, Windows and a browser version): scenes with game / screen / window capture, webcam with beauty, logo, text, chat and gift/follow alerts on the stream, and an audio mixer (mic with noise suppression and voice effects, game sound, music). It goes live straight into a room through the SDK (WebRTC, no OBS, no RTMP) as a normal publisher. It signs in with an app token from your server (a room claim locks the room).

• Measured (M-series Mac, development server): the viewer decodes 720p60 at 59.8–60 fps; studio → viewer 40–59 ms (median); the studio uses ~4–5% of a 16-core machine at 720p60 with simulcast (software H.264).
• Room messages it understands: topic chat (text or {"text","name"}), gift ({"gift","count","name","coins"}), follow ({"name"}) — send them with sendRoomMessage(text, topic).
• Builds are unsigned betas (macOS Gatekeeper and Windows SmartScreen warn). The Windows installer has not been run on Windows yet, 1080p60 and the macOS system sound on a real game are not measured. Ask us for a build.

Karaoke catalogue PREVIEW

The songs the karaoke engine lists and sings: the house songs plus your project's own. A song is a backing track (mp3, m4a, ogg or wav) + LRC lyrics (line and word timing) + an optional reference melody (JSON or MIDI) for the score. Files are never public: the API returns signed URLs (6 h) that a player can stream with Range requests.

Authentication: a user token (Authorization: Bearer … or ?token=). Each song: id, title, artist, language, durationMs, license, tags, lines, wordTimed, melodyNotes, owner (house | app), trackUrl, lrcUrl, melodyUrl. KaraokeCatalogue in @ilorb/signal-web-fx wraps both calls. Adding your own songs goes through us for now (we check the licence); the console lists them under Develop → Karaoke catalogue.

Callbacks

Set a callback URL (https) and generate a callback secret in Project → Callbacks. ILORB Signal then sends a POST to your server on each event. Callbacks are sent only when both URL and secret are set.

Every body has event, eventId, appId and at (room events also roomId). The typed payload of each event is CallbackEvent in @ilorb/signal-server/callback. New events may be added: answer 2xx to events you don't know.

POST https://your-server.com/ilorb/callback
x-ilorb-event: user.joined
x-ilorb-event-id: evt_4f1c2a9e0b7d3c5a8e6f1b2c
x-ilorb-timestamp: 1760965200
x-ilorb-signature: sha256=5d1c…

{ "event": "user.joined", "eventId": "evt_4f1c2a9e0b7d3c5a8e6f1b2c", "appId": "app_…", "roomId": "room-42",
  "at": "2026-10-20T13:00:00.000Z", "userId": "42", "participants": 3 }

Verify the signature

The signature is sha256= + hex(HMAC-SHA256(callback secret, timestamp + "." + raw body)). Always verify it on the raw body, and reject old timestamps to block replays.

import crypto from 'node:crypto'

app.post('/ilorb/callback', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.header('x-ilorb-timestamp')
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.ILORB_CALLBACK_SECRET)
    .update(ts + '.' + req.body).digest('hex')
  const got = req.header('x-ilorb-signature') ?? ''
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300
  if (!fresh || got.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected)))
    return res.sendStatus(401)
  const event = JSON.parse(req.body)
  // …
  res.sendStatus(200)
})

Handle each event once

eventId (also the x-ilorb-event-id header) is unique per event. Remember the ids you handled for at least 10 minutes (twice the 300 s window) and answer 2xx without acting again when one comes back: a captured delivery replayed within the window, or the same event handled by two of your servers. Anything older is refused by its timestamp. Deliveries are not ordered: each one is its own request, so user.joined can arrive before room.started, or room.ended before the last user.left; order by at (apply a change only if it is newer than the last one you applied for that user or room). In Node, CallbackReceiver does the three checks:

import { CallbackReceiver } from '@ilorb/signal-server/callback'

const receiver = new CallbackReceiver({ secret: process.env.ILORB_CALLBACK_SECRET })  // a list while rotating; store: your Redis/DB with several servers
const r = await receiver.receive(req.headers, rawBody)
if (!r.ok) return res.status(401).json({ error: r.reason })   // bad_signature | stale_timestamp | missing_headers | bad_timestamp | bad_json
if (r.duplicate) return res.json({})                         // already handled
try { res.json(await handle(r.event)) } catch (e) { await receiver.forget(r.eventId); res.sendStatus(500) }

A complete sample server that issues tokens and receives every callback (keeps who is in each room, copies recording chunks, answers moderation checks, decides flags, hands chat.push to FCM/APNs) is examples/web/server.mjs + examples/web/callbacks.mjs in the SDK repository.

Answer with any 2xx within 5 seconds. Deliveries are not retried; every delivery (status and time) is listed in Project → Callbacks → Recent deliveries. Treat callbacks as notifications and use the REST API as the source of truth.

Device profiles

Phones differ a lot: some play voice too low, some route audio oddly, some leave echo behind, and entry-level phones need a lighter audio chain. ILORB Signal tunes this for you, from our servers. The SDK asks for its profile when the app opens and applies it; nothing ships in your app, and there is nothing to configure per device in the console.

• Layers. The profile is merged key by key, from the most general to the most specific: default › device class › brand › model prefix (moto g*) › exact model.
• Device class. The SDK sends the hardware (RAM, total and fast CPU cores, max frequency, chip) and the server classifies the phone as low, mid or high end, with rules kept on the server. Low-end phones get a lighter chain automatically.
• About 188 SDK settings plus the native audio settings can change this way: no new build and no store update. The new profile is used the next time the app opens.
• Echo per model (calibrating). The SDK measures echo on each phone with a detector that only measures and never changes the audio. The server will use those measurements to choose echo cancellation per model; today it only observes.

{ "ok": true, "lang": "en", "profile": { "id": 1, "name": "default + medium + Motorola", "deviceClass": "medium",
  "layers": [ … ], "settings": { "playbackGain": 1.25, "quality": { … }, "tuning": { "sdk": { … }, "native": { … }, "app": { … } }, "sound": { … } } } }   // or "profile": null

The SDK calls this for you. Without v=2 the endpoint answers as before (only the most specific profile), so older app versions keep working. Missing settings mean "use the default". Missing brand or model → 400 { ok: false, error: 'brand_and_model_required' }. If a phone model misbehaves in your app, tell us: we fix it on the server for every app at once.

en=1 (sent by the current SDK) returns the profile with English names and lang: 'en':

Automatic device profile (React Native)

With @ilorb/signal-react-native-audio imported, VoiceClient does all of this by itself — no code: it sends the device identity and hardware (RAM, cores, CPU clock, chip) with v=2, so the server picks the device class (weak / medium / good) and merges the layers default › class › brand › model › user; it caches the profile on the device and applies it on the next launch before the network answers; it applies the audio quality, the SDK tuning and the native tuning; it asks again every 20 s while the app is in the foreground; and it sends CPU, network and echo measurements with the session stats. On Android add one line to MainApplication.onCreate, after LiveKitReactNative.setup: com.ilorb.signal.audio.IlorbCaptureConfig.applyAtStartup(this) (microphone source, sample rate and hardware effects from the profile).

import '@ilorb/signal-react-native-audio'   // registers the platform

const voice = new VoiceClient({ serverUrl, webrtc })
voice.on('deviceProfileChanged', (c) => console.log(c.changedKeys))   // already applied
voice.on('needsRestart', (keys) => askToRestartAudio())          // route, mic source… apply on the next launch
voice.deviceProfile?.appTuning   // free keys your app reads (settings.tuning.app)

// opt out, or keep the quality in your own UI
new VoiceClient({ serverUrl, webrtc, deviceProfile: false })
new VoiceClient({ serverUrl, webrtc, deviceProfile: { applyQuality: false } })

The same VoiceClient also recovers a microphone the system silenced while the app was in the background (captureRecovery, on by default; getConnectionInfo().captureReopens). iOS: the profile, quality, tuning, native storage and the device stats (CPU, thermal state, memory, battery, network) work; the silent-capture guard is Android only for now.

Engine API

@ilorb/signal-engine gives you IlorbEngine: a singleton room engine with named events, plain argument objects and numeric enums for voice rooms (log in, go on stage, play, sound levels, room messages). It runs on top of VoiceClient; you create it once and your room screens talk only to the engine.

1. Install

npm install @ilorb/signal-engine @ilorb/signal @livekit/react-native @livekit/react-native-webrtc
npm install @ilorb/signal-server   # on your server

2. Issue tokens on your server

The App Secret never goes into the app: it stays on your server, which creates a short-lived user token per user. Expose it from an authenticated endpoint of your API.

3. Create the engine

Create the engine once, with your server URL, a token callback and the WebRTC implementation. Everything after that talks to IlorbEngine.instance().

import { IlorbEngine } from '@ilorb/signal-engine'
import { RTCPeerConnection, mediaDevices, MediaStream } from '@livekit/react-native-webrtc'

await IlorbEngine.createEngineWithProfile({
  serverUrl: 'https://api-signal.ilorb.app',
  getToken: (roomID, userID) => myApi.voiceToken(roomID, userID), // your server
  webrtc: { RTCPeerConnection, mediaDevices, MediaStream },
})

const engine = IlorbEngine.instance()
engine.on('roomStreamUpdate', (roomID, type, streams) => {
  /* your handler */
})
await engine.loginRoom(roomID, { userID, userName })
await engine.startPublishingStream(`${roomID}-${userID}`)

The enums (IlorbUpdateType, IlorbRemoteDeviceState, IlorbPublisherState, IlorbPlayerState, IlorbRoomStateChangedReason, IlorbRoomState) are exported by @ilorb/signal-engine.

Profile options

Call by call

Anything that is not on the engine is still reachable through engine.getVoiceClient(): muteUser, setReceiving, resume, getNetworkStats.

Good to know

• Tokens come from your server. No secret in the app; getToken is called on every loginRoom.
• Playing is volume-only. Everyone on stage is received; startPlayingStream / stopPlayingStream only change the volume, so it is instant and never breaks listening. To really stop receiving (and egress), use engine.getVoiceClient().muteUser(userId, true) or setReceiving(false).
• Stream IDs are derived from the user with streamIdOf, not chosen freely on each publish.
• The engine is voice only. For video use the VoiceClient directly (startCamera / getVideoStream); PK uses linked rooms instead of a mixer. No CDN relay, media player or stream/room extra info yet.
• Room members are always notified when someone joins or leaves.

Engine error codes

Each ILORB Signal error code becomes a numeric engine errorCode. The original code always goes in extendedData, so you can still tell "out of credit" from "kicked".

At login these come back in loginRoom's result and in roomStateChanged(…, 2); during a session, terminal codes arrive as roomStateChanged(roomID, 6, errorCode, code).

RTC API

The RTC API is a channel-style API on top of VoiceClient: @ilorb/signal-rtc-web for the browser, @ilorb/signal-rtc-react-native for React Native, ilorb-signal-rtc-android for Android (package com.ilorb.signal.rtc) and IlorbRtcKit for iOS. Clients and engines join channels with a numeric uid, publish tracks and report everything through named events, string states and numeric enums that are the same on every platform.

1. Install

# Web
npm install @ilorb/signal-rtc-web @ilorb/signal
# React Native
npm install @ilorb/signal-rtc-react-native @ilorb/signal @livekit/react-native @livekit/react-native-webrtc
npm install @ilorb/signal-react-native-audio   # optional: music (startAudioMixing), mic gain
# Android (Gradle)
implementation "com.ilorb.signal:ilorb-signal-rtc-android:0.1.0"
# iOS (Swift Package) — product IlorbRtcKit
.package(path: "…/packages/ios-swift-rtc")
# your server
npm install @ilorb/signal-server

2. Issue tokens on your server

appId is your ILORB Signal App ID and appCertificate your App Secret; the channel is the room and the uid the user. The result is a regular user token.

import { RtcTokenBuilder, RtcRole } from '@ilorb/signal-server/rtc-token'
const token = RtcTokenBuilder.buildTokenWithUid(appId, appCertificate, channel, uid, RtcRole.PUBLISHER, 3600, 3600)

tokenExpire is seconds from now (0 = 24 h; a Unix timestamp also works), from 60 s up to 7 days; with privilegeExpire the shorter one wins. role is accepted and ignored. uid 0 ("any user") does not exist: every ILORB token is for one user. buildTokenWithUserAccount takes a string account (up to 40 characters [0-9A-Za-z_-]).

3. Join from the browser

import IlorbRTC, { configureIlorb } from '@ilorb/signal-rtc-web'
configureIlorb({ serverUrl: 'https://api-signal.ilorb.app' }) // optional

const client = IlorbRTC.createClient({ mode: 'rtc', codec: 'vp8' })
client.on('user-published', async (user, type) => {
  await client.subscribe(user, type)
  type === 'audio' ? user.audioTrack.play() : user.videoTrack.play(el)
})
await client.join(appId, channel, token, uid)
const mic = await IlorbRTC.createMicrophoneAudioTrack()
await client.publish(mic)

appId is your ILORB Signal App ID. configureIlorb is only needed off production; without it the package uses https://api-signal.ilorb.app (or globalThis.ILORB_SIGNAL_SERVER_URL).

React Native

import createIlorbRtcEngine, { ChannelProfileType, ClientRoleType, RtcSurfaceView, configureIlorb } from '@ilorb/signal-rtc-react-native'
import { IlorbMediaPlayer, IlorbAudio } from '@ilorb/signal-react-native-audio'   // optional
configureIlorb({ mediaPlayer: IlorbMediaPlayer, audioProcessing: IlorbAudio })        // optional, once

const engine = createIlorbRtcEngine()
engine.initialize({ appId, channelProfile: ChannelProfileType.ChannelProfileLiveBroadcasting })
engine.registerEventHandler({ onJoinChannelSuccess, onUserJoined, onUserOffline, onAudioVolumeIndication })
engine.joinChannel(token, channel, uid, { clientRoleType: ClientRoleType.ClientRoleBroadcaster, publishMicrophoneTrack: true })
// video: <RtcSurfaceView canvas={{ uid }} />  (uid 0 = me)

Enums (ChannelProfileType, ClientRoleType, ConnectionStateType, ConnectionChangedReasonType, ErrorCodeType, RemoteAudioState, AudioProfileType…) have fixed numeric values, the same on Android and iOS. Methods return 0 or a negative ErrorCodeType, and the result arrives as an event.

uid ↔ user ID. A numeric ILORB user ID (1 to 2³²−1) is the uid. Any other user ID (e.g. "ana", from a web app that joined with a string uid) becomes a stable 32-bit number; engine.getUserIdOfUid(uid) gives the original back. Issue tokens with numeric uids and you never see the difference.

Android (Kotlin or Java)

RtcEngine, RtcEngineConfig, IRtcEngineEventHandler, ChannelMediaOptions, Constants, VideoCanvas and VideoEncoderConfiguration live in com.ilorb.signal.rtc and run on the Kotlin VoiceClient. IRtcEngineEventHandler is a Java class, so your overrides compile with either nullability.

import com.ilorb.signal.rtc.*

val config = RtcEngineConfig()
config.mContext = applicationContext
config.mAppId = "your ILORB Signal App ID"
config.mEventHandler = handler
config.mServerUrl = "https://api-signal.ilorb.app"   // this is the default
config.mTokenProvider = TokenProvider { channel, uid -> myApi.token(channel, uid) }   // optional
val engine = RtcEngine.create(config)

engine.enableAudioVolumeIndication(200, 3, true)
val options = ChannelMediaOptions()
options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER
options.publishMicrophoneTrack = true
engine.joinChannel(token, "room-1", 1001, options)

Callbacks arrive on the main thread; methods return the error code right away and the effect runs in order. mLicense, mAreaCode, mLogConfig and extensions are accepted and ignored.

iOS (Swift)

IlorbRtcEngineKit, IlorbRtcEngineDelegate, IlorbRtcEngineConfig, IlorbRtcChannelMediaOptions, IlorbRtcVideoCanvas, IlorbVideoEncoderConfiguration and the enums keep the same raw values as the other platforms. Conform with extension MyVC: IlorbRtcEngineDelegate { … }. It runs on the Swift VoiceClient.

import IlorbRtcKit

let config = IlorbRtcEngineConfig()
config.appId = "your ILORB Signal App ID"
config.channelProfile = .liveBroadcasting
config.serverUrl = "https://api-signal.ilorb.app"   // this is the default
config.tokenProvider = { channel, uid in await myApi.token(channel, uid) }   // optional
rtcKit = IlorbRtcEngineKit.sharedEngine(with: config, delegate: self)

rtcKit.enableAudioVolumeIndication(200, smooth: 3, reportVad: true)
let options = IlorbRtcChannelMediaOptions()
options.clientRoleType = .broadcaster
options.publishMicrophoneTrack = true
rtcKit.joinChannel(byToken: token, channelId: "room-1", uid: 1001, mediaOptions: options)

Add NSMicrophoneUsageDescription (and NSCameraUsageDescription for video) and UIBackgroundModes → audio to your Info.plist. startAudioMixing plays local files (wav, mp3, m4a/aac, caf, aiff).

Native uid ↔ user ID. Same rule as React Native: a numeric user ID that fits in 32 bits is the uid ("1001" ↔ 1001); any other ID becomes a stable 32-bit FNV-1a hash with bit 31 set ("ana" ↔ 0x9429CA85 on iOS, -1809200507 on Android); onUserInfoUpdated / didUpdatedUserInfo gives the original string. Roles: with the default LIVE_BROADCASTING profile only hosts show up (onUserJoined), and a host who steps down leaves with USER_OFFLINE_BECOME_AUDIENCE; with COMMUNICATION everyone shows up.

Call by call

Good to know

• The token is required and carries app, room and user. There is no "testing mode" with only an App ID, and no uid-0 token.
• User IDs are strings in ILORB Signal. Web: numeric uids come back as numbers when you joined with a number. React Native: see uid ↔ user ID above.
• Remote audio plays automatically. Web play()/stop() control volume, so a late play() never misses the first words.
• Messages (sendStreamMessage, data channels) go through the room's WebSocket: reliable and ordered; every member receives them — Web, React Native, Android and iOS use the same format (topic rtc:stream:<id>, base64 body).
• Channel names are [0-9A-Za-z_-], up to 64 characters. Names with spaces or symbols return -ERR_INVALID_CHANNEL_NAME.
• Network quality is reported for you (uid 0) only, not per remote user.
• Live hosts who have not published yet: Web and React Native also show a host marked by the rtc.role=host attribute; native Android and iOS show a host once it publishes.

Error codes

Errors reach the app through the error event. When the server ends a session for a business reason, the WebSocket closes with code 4001 and the error code as the reason. All codes below are terminal: the SDK does not reconnect.

viewer_cannot_publish (a viewer tried to publish) does not end the session. Non-terminal errors (network, internal) are reported too; with autoReconnect the SDK reconnects by itself and fires connectionStateChanged('reconnecting').

Limits

Measured load

Synthetic participants that speak this protocol (Go + Pion) against the full path — edge Worker, room coordinator, Cloudflare Realtime and TURN — on our development server, from one test site in São Paulo (2026-11-02). Hold 180 s unless noted.

Churn of ~8 joins and 8 leaves per second in one room: no join refused. At 100 rooms × 5 the test site's own link saturated (about 25 Mbps of received audio), so that run measures the bench, not the service. Join latency is dominated by distance: the room coordinator runs in North America, so a participant in Brazil pays about two round trips of ~120 ms per signaling exchange — this is what we are working on.

Billing

ILORB Signal is prepaid. The account balance is kept in participant-minutes: each person connected to a room for one minute consumes one, whether they speak or listen. Rooms are metered continuously; when the balance reaches zero, open rooms close with insufficient_credit and new joins are refused until the next top-up.

• Console → Usage: any period, grouped by day, project or room, with CSV export.
• Console → Billing: balance, average per day, how long the balance lasts, monthly statements, the low-balance alert (also sent as the balance.low callback) and the card top-up (Billing & payments).
• GET /v1/balance: the same balance from your server.

WebSocket protocol

You don't need this if you use the SDK; it is documented for other platforms and for debugging. Connect to:

Messages are JSON with a type field t. Audio goes over WebRTC to the Cloudflare SFU (STUN stun:stun.cloudflare.com:3478); the socket carries signaling only. Your microphone always publishes in a session of its own, separate from the session that receives the others.

Client → server

Server → client

Protocol versions

Each version only adds; older clients keep working (the room speaks the dialect each client announces). Production server: 14. Development server: 16 (15 and 16 reach production with the next server release).

Protocol 4 adds linked rooms: linked / unlinked messages and an optional roomId on people and track messages (absent = your room). Protocol 16 adds the PK battle: the client sends { t: 'pk', op: 'invite' | 'accept' | 'reject' | 'cancel' | 'end' | 'score' | 'tick', … }, the server answers with { t: 'pk', event: 'invited' | 'invite-sent' | 'accepted' | 'rejected' | 'cancelled' | 'expired' | 'failed', … }; the state is the room attribute pk:state; welcome carries now (the server clock) and the cap 'pk'.

Protocol version: 3 (adds video: publish/unpublish/published take kind: 'video', camera tracks are named {roomId}-{userId}-video, and cam messages). Clients on version 2 keep working.

Protocol 5 adds simulcast: publish takes layers (rids, largest first) and the client sends layer (trackName, 'high' | 'low'). Protocol 6 adds diagnostics: the client sends stats every 30 s, and the server may send republish (kind) when the media server lost a track. Protocol 7 adds screen sharing: publish / unpublish / published and republish take kind: 'screen', and the screen track is named {roomId}-{userId}-screen (no simulcast layers). Protocol 9 adds attributes: attrs both ways, welcome.roomAttributes and people[].attributes. Protocol 10 adds range voice: pos both ways and people[].position / team in welcome. Protocol 11 adds the music's own track: publish / republish take kind: 'music' (a separate publication that does not replace the microphone; the room announces it with the 'music' cap). Protocol 12 adds the 'en' cap in join.caps and welcome.caps: everything the client and the server exchange uses English values. Protocols 13–16: see the table above. Current version: 16 (development server; production: 14).

Stats values (protocol 12)

The stats message ({ t: 'stats', s }) carries the connection sample. Fields with fixed values:

Live blocks (2026-11-01; every block is sent on every platform, a field the platform cannot measure is null):

App broadcast: fix echo

The room owner (or an admin) asks the server to fix a listener's echo with an app broadcast whose message is { "topic": "fix-echo", "text": "{\"to\":\"<userId>\",\"id\":…}" } (text is a JSON string). The server limits these requests and relays the broadcast to each recipient in the dialect it speaks: clients with the 'en' cap get fix-echo / to.

Changelog