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 channels複製段落連結

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.

Options複製段落連結

Available flags for initialization.

Events複製段落連結

• onConnectionState複製段落連結

  = (state: RTCPeerConnectionState) => {}

  Emitted when the WebRTC peer connection state changes.

• onDatachannel複製段落連結

  = (role: ChannelRole) => {}

  Emitted when the data channel successfully opens for data communication.

• onProgress複製段落連結

  = (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.

• onStream複製段落連結

  = (stream: MediaStream) => {}

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

• onSfuStream複製段落連結

  = (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>.

• onSnapshot複製段落連結

  = (base64: string) => {}

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

• onVideoListLoaded複製段落連結

  = (res: QueryFileResponse) => {}

  Emitted when the metadata of a recording file is retrieved.

• onVideoDownloaded複製段落連結

  = (file: Uint8Array) => {}

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

• onTimeout複製段落連結

  = () => {}

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

• onError複製段落連結

  = (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.

• onDeviceSession複製段落連結

  = (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.

• onMessage複製段落連結

  = (msg: Uint8Array) => {}

  Emitted when an IPC message is received from the server.

• onRecording複製段落連結

  = (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.

• onRoomInfo複製段落連結

  = (participant: RoomInfo) => {}

  Emitted when the SFU room information changes.

• onQuality複製段落連結

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

  Emitted when SFU connection quality changes.

• onSpeaking複製段落連結

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

  Emitted when an SFU participant starts or stops speaking.

• onParticipant複製段落連結

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

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

Methods複製段落連結

• connect複製段落連結

  .connect()

  Starts establishing the WebRTC connection.

• terminate複製段落連結

  .terminate()

  Terminates the WebRTC connection.

• getStatus複製段落連結

  .getStatus()

  Retrieves the current connection status.

• getStats複製段落連結

  .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.

• refresh複製段落連結

  .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.

• fetchVideoList複製段落連結

  .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.

• downloadVideoFile複製段落連結

  .downloadVideoFile(path: string)

  Requests a video file from the server.

  • path - The path to the video file.

• setCameraControl複製段落連結

  .setCameraControl(key: CameraControlId, value: CameraControlValue)

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

• snapshot複製段落連結

  .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.

• startRecording複製段落連結

  .startRecording()

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

• stopRecording複製段落連結

  .stopRecording()

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

• sendText複製段落連結

  .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.

• sendData複製段落連結

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

  Same as sendText, but sends in binary format.

• canSend複製段落連結

  .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.

• toggleMic複製段落連結

  .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.

• toggleSpeaker複製段落連結

  .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.

• setJitterBufferTarget複製段落連結

  .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.

• getJitterBufferTarget複製段落連結

  .getJitterBufferTarget(): number | null | undefined

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

Gamepad複製段落連結

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 listening複製段落連結

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)

Exports複製段落連結

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.

Options複製段落連結

Taken by attachGamepad, useGamepad, and the GamepadSampler constructor.

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

Behaviour複製段落連結

• 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.