API Documentation

• Data channels
• Options
• Events
  • onConnectionState
  • onDatachannel
  • onProgress
  • onStream
  • onSfuStream
  • onSnapshot
  • onVideoListLoaded
  • onVideoDownloaded
  • onMessage
  • onRecording
  • onTimeout
  • onError
  • onRoomInfo
  • onQuality
  • onSpeaking
  • onParticipant
  • onDeviceSession
• Methods
  • connect
  • terminate
  • getStatus
  • getStats
  • refresh
  • fetchVideoList
  • downloadVideoFile
  • setCameraControl
  • snapshot
  • startRecording
  • stopRecording
  • sendText
  • sendData
  • canSend
  • toggleMic
  • toggleSpeaker
  • setJitterBufferTarget
  • getJitterBufferTarget
• Gamepad
  • The device has to be listening
  • Exports
  • Options
  • Behaviour

Data channelsCopy Anchor Link

Four channels, each with one job. onDatachannel reports each one as a ChannelRole.

On the mqtt path the four are negotiated out-of-band on those fixed SCTP ids: both sides open them locally, so ondatachannel never fires and the ids have to match the device's. Over livekit the SFU opens its own reserved channels in-band instead, and only _lossy / _reliable exist there. The cloudflare path has no data channels at all.

Because a negotiated channel opens as soon as the SCTP association is up, whether or not the device opened its side, onDatachannel fires for all four on the mqtt path even when the device is running without --enable-ipc. It reports that the channel is usable locally, not that anything is listening on the other end.

Splitting bulk content onto its own channel is what keeps a multi-megabyte downloadVideoFile() from blocking the commands issued while it runs — a snapshot requested mid-transfer comes back without waiting for the file. Because stream is unordered and several streams are in flight at once, every request carries a request_id that the device echoes on the matching answer.

Nothing on a stream says what its body is: request_id names the request it answers, and the channel it arrived on says whether it is an answer at all or an IPC payload. The client keeps the pending-request map that turns one into the other, so onProgress can report overlapping transfers separately and each completed body is parsed as what was actually asked for.

OptionsCopy Anchor Link

Available flags for initialization.

EventsCopy Anchor Link

• onConnectionStateCopy Anchor Link

  = (state: RTCPeerConnectionState) => {}

  Emitted when the WebRTC peer connection state changes.

• onDatachannelCopy Anchor Link

  = (role: ChannelRole) => {}

  Emitted when the data channel successfully opens for data communication.

• onProgressCopy Anchor Link

  = (received: number, total: number, type: RequestType, requestId?: string) => {}

  Emitted during DataChannel transfers with received/total progress. requestId says which request the bytes belong to, so overlapping transfers can be told apart.

• onStreamCopy Anchor Link

  = (stream: MediaStream) => {}

  Triggered when a media stream is received from either SFU or MQTT.

• onSfuStreamCopy Anchor Link

  = (sid: string, stream: MediaStream) => {}

  Triggered only when a media stream is received from the SFU, delivering both the participant's server-side ID (sid) and the associated MediaStream. On the cloudflare path there are no participants, so the first argument is the name of the track that was pulled.

  On the mqtt path the audio track and the first camera share one stream, so the sid is whichever arrived first. To tell cameras apart, read track.id — the device names them video_track_<alias>.

• onSnapshotCopy Anchor Link

  = (base64: string) => {}

  Emitted after calling the snapshot() method. This event emits a base64-encoded image once all image packets are received from the server.

• onVideoListLoadedCopy Anchor Link

  = (res: QueryFileResponse) => {}

  Emitted when the metadata of a recording file is retrieved.

• onVideoDownloadedCopy Anchor Link

  = (file: Uint8Array) => {}

  Emitted when a video file is successfully downloaded from the server.

• onTimeoutCopy Anchor Link

  = () => {}

  Emitted when the P2P connection cannot be established within the allotted time. Automatically calls the terminate() function.

• onErrorCopy Anchor Link

  = (err: Error) => {}

  Emitted when signaling fails for a reason worth putting in front of a user — a device that has never reported a session, one that is registered but not publishing, a track the SFU refused. Distinct from onTimeout, which only says the peer never came up.

• onDeviceSessionCopy Anchor Link

  = (session: DeviceSession) => {}

  Emitted on the cloudflare path once the device's session record has been read, before the peer is built. Cloudflare mints a new session id on every device reconnect, so this is the only place the current one is visible.

• onMessageCopy Anchor Link

  = (msg: Uint8Array) => {}

  Emitted when an IPC message is received from the server.

• onRecordingCopy Anchor Link

  = (res: RecordingResponse) => {}

  Emitted when the server responds to a startRecording() or stopRecording() command.

  • res.isRecording — true if recording has started, false if it has stopped.
  • res.filepath — The active recording file path.

• onRoomInfoCopy Anchor Link

  = (participant: RoomInfo) => {}

  Emitted when the SFU room information changes.

• onQualityCopy Anchor Link

  = (quality: Quality[]) => {}

  Emitted when SFU connection quality changes.

• onSpeakingCopy Anchor Link

  = (speaking: Speaking[]) => {}

  Emitted when an SFU participant starts or stops speaking.

• onParticipantCopy Anchor Link

  = (participant: Participant[]) => {}

  Emitted when the list of participants in the SFU room changes.

MethodsCopy Anchor Link

• connectCopy Anchor Link

  .connect()

  Starts establishing the WebRTC connection.

• terminateCopy Anchor Link

  .terminate()

  Terminates the WebRTC connection.

• getStatusCopy Anchor Link

  .getStatus()

  Retrieves the current connection status.

• getStatsCopy Anchor Link

  .getStats(selector?: MediaStreamTrack | null): Promise<RTCStatsReport> | undefined

  The browser's stats for the receiving peer, where inbound-rtp reports the jitter buffer, freezes and packet loss actually being seen. undefined before a peer exists.

• refreshCopy Anchor Link

  .refresh(): Promise<number>

  Pulls whatever the device has started publishing since the connection was established, and resolves to how many tracks that was. Rejects if the SFU refuses. Only the cloudflare path has anything to re-read; elsewhere new tracks arrive on their own and this resolves to 0.

• fetchVideoListCopy Anchor Link

  .fetchVideoList(options?: { param?: string | Date, mode?: VideoMode })

  Retrieves recording file metadata.

  If called without arguments, returns metadata of the latest recorded file.

  If param is a file path (string), returns metadata of up to 8 older recordings before the given file.

  If param is a date, returns metadata of the closest recorded file to that time.

  • param - (optional) A file path (string) or a Date; controls pagination/filtering.
  • mode - (optional) Filters results to the specified VideoMode.

• downloadVideoFileCopy Anchor Link

  .downloadVideoFile(path: string)

  Requests a video file from the server.

  • path - The path to the video file.

• setCameraControlCopy Anchor Link

  .setCameraControl(key: CameraControlId, value: CameraControlValue)

  Sets camera properties (for example, 3A controls).

• snapshotCopy Anchor Link

  .snapshot(quality?: number)

  Requests a snapshot image from the server.

  • quality - The range from 0 to 100, determines the image quality. The default value is 30.

• startRecordingCopy Anchor Link

  .startRecording()

  Sends a START_RECORDING command to the server via the command DataChannel. The server response is delivered via onRecording.

• stopRecordingCopy Anchor Link

  .stopRecording()

  Sends a STOP_RECORDING command to the server via the command DataChannel. The server response is delivered via onRecording.

• sendTextCopy Anchor Link

  .sendText(msg: string, mode?: 'lossy' | 'reliable')

  Sends an IPC message. mode is chosen per message and defaults to reliable, which retransmits until delivered; lossy may drop the message but has lower latency. Both channels are open whenever the device runs with --enable-ipc. Payloads over 64 KB are chunked and are only accepted on reliable.

• sendDataCopy Anchor Link

  .sendData(binary: Uint8Array, mode?: 'lossy' | 'reliable')

  Same as sendText, but sends in binary format.

• canSendCopy Anchor Link

  .canSend(mode?: 'lossy' | 'reliable'): boolean

  Whether a payload sent right now would reach the device. False until the channel carrying mode is open, and again once the connection is gone.

• toggleMicCopy Anchor Link

  .toggleMic(enabled?: boolean)

  Toggles the local audio stream on or off. If an argument is provided, it will force the state to the specified value, otherwise, the current state will be toggled.

• toggleSpeakerCopy Anchor Link

  .toggleSpeaker(enabled?: boolean)

  Toggles the remote audio stream on or off. If an argument is provided, it will force the state to the specified value, otherwise, the current state will be toggled.

• setJitterBufferTargetCopy Anchor Link

  .setJitterBufferTarget(target: number | null)

  Milliseconds the receive jitter buffer should hold (0–4000, clamped). Lower means less delay but more freezes. null hands the decision back to the browser.

  A hint: the browser converges on it gradually, so read the real delay from getStats. Needs Chrome 124, Firefox 115 or Safari 27.

• getJitterBufferTargetCopy Anchor Link

  .getJitterBufferTarget(): number | null | undefined

  The target last asked for, not the one the browser settled on. undefined means none has been asked for.

GamepadCopy Anchor Link

Reads a controller, encodes each reading, and sends it to the device's gamepad endpoint.

import { attachGamepad, Button, isPressed } from '@mazupo/client/gamepad';
import { useGamepad, GamepadView } from '@mazupo/client/gamepad/react';

react is an optional peer dependency, needed only for the second. GamepadView draws with SVG and is web-only; the headless entry point works under React Native.

Examples: browser, React.

The device has to be listeningCopy Anchor Link

pi-webrtc --enable-ipc --enable-gamepad ...

--enable-ipc opens the channels this arrives on, --enable-gamepad opens the socket it is routed to. Without the second, input is sent and silently discarded.

Each reading reaches that socket as a protocol.InputReport, preceded by a big-endian uint32 length:

header = await reader.readexactly(4)
body = await reader.readexactly(int.from_bytes(header, "big"))
report = InputReport(); report.ParseFromString(body)

ExportsCopy Anchor Link

attachGamepad(camera, options?) is the whole setup, in any order relative to connect(): a reading taken before the link is up is dropped, and sending picks up once the channel opens. canSend is what it consults. GamepadSampler is the same loop without the camera, for driving it by hand or sending somewhere else; its setSink() changes destination, it does not follow a connection.

buttons is a bitfield, bit n being buttons[n].pressed in the standard mapping; read it with isPressed(snapshot, Button.Start). An axis or button the controller does not report reads as centred or released rather than throwing.

onButton and onButtonChange fire once on press and once on release, never while a button is held, and run whether or not a sink is set. Both return a function that removes the listener. A controller unplugged mid-hold reports whatever it held as released, so a toggle cannot stick on.

OptionsCopy Anchor Link

Taken by attachGamepad, useGamepad, and the GamepadSampler constructor.

Anything with sendToEndpoint is an IpcSink, exported from the main entry point; PiCamera implements it.

BehaviourCopy Anchor Link

• Samples on a fixed timer rather than requestAnimationFrame: the device reads a steady stream as proof the link is alive, so the rate must not follow the display.
• Stops while the document is hidden. sampleWhileHidden: true overrides it.
• Sequences every message, so the device can drop a stale reading arriving late on the unordered lossy channel.
• Sends nothing for a pad outside the W3C standard mapping, reporting it as standardMapping: false — its fields would not mean what their names say.
• start() is idempotent, and a second controller does not start a second loop.
• Applies no deadzone. pi-webrtc's own consumer does, and splitting that decision across two codebases would drift.

Back to the README.