PiCamera.js

JavaScript client for pi-webrtc — stream low-latency video/audio from Raspberry Pi using native WebRTC with hardware H.264 (V4L2) or OpenH264.

Supports P2P, SFU, DataChannel control, and snapshot/file transfer over WebRTC.

Installation

npm install picamera.js

Usage

Check out the online demo: Live Demo

You can also view the demo source code here: index.html.

Notes:

Local IP or VPN address
Mosquitto
Self-signed certificates

API

API Documentation

Example

These examples show how to use individual features separately.

Live video

Display live streaming on the HTML <video> element.

<video id="videoElement"></video>
<script type="module">
  import { PiCamera } from 'picamera.js';

  let videoRef = document.getElementById('videoElement');

  let conn = new PiCamera({
    deviceUid: 'your-custom-uid',
    mqttHost: 'your.mqtt.cloud',
    mqttPath: '/mqtt',
    mqttPort: '8884', // Websocket Port
    mqttUsername: 'hakunamatata',
    mqttPassword: 'Wonderful',
    stunUrls: ["stun:stun1.l.google.com:19302"],
  });
  conn.onStream = (stream) => {
    videoRef.srcObject = stream ?? null;
  };
  conn.connect();
</script>

Capture a snapshot only

Use webrtc datachannel to get the snapshot image only.

let conn = new PiCamera({
  deviceUid: 'your-custom-uid',
  mqttHost: 'your.mqtt.cloud',
  mqttPath: '/mqtt',
  mqttPort: '8884', // Websocket Port
  mqttUsername: 'hakunamatata',
  mqttPassword: 'Wonderful',
  stunUrls: ["stun:stun1.l.google.com:19302"],
  datachannelOnly: true,
});

conn.onDatachannel = (id) => {
  // on connected to remote datachannel
  if (id === ChannelId.Command)
    conn.snapshot();
}

conn.onSnapshot = (image) => {
  // get a base64 image here, then terminate the connection.
  conn.terminate();
}

conn.connect();

Send message for IPC via DataChannel

Use WebRTC DataChannel to send messages to a Unix domain socket on the Raspberry Pi. This allows sending custom messages for inter-process communication (IPC).

let conn = new PiCamera({
  deviceUid: 'your-custom-uid',
  mqttHost: 'your.mqtt.cloud',
  mqttPath: '/mqtt',
  mqttPort: '8884', // Websocket Port
  mqttUsername: 'hakunamatata',
  mqttPassword: 'Wonderful',
  stunUrls: ["stun:stun1.l.google.com:19302"],
  datachannelOnly: true,
  ipcMode: 'reliable'
});

conn.onDatachannel = (id) => {
  // on connected to remote datachannel
  if (id === ChannelId.Reliable)
    conn.sendMessage('Hello Reliable Channel!');
}

conn.onMessage = (msg) => {
  // get a response msg here.
  conn.terminate();
}

conn.connect();

Download the latest video record

let conn = new PiCamera({
  deviceUid: 'your-custom-uid',
  mqttHost: 'your.mqtt.cloud',
  mqttPath: '/mqtt',
  mqttPort: '8884', // Websocket Port
  mqttUsername: 'hakunamatata',
  mqttPassword: 'Wonderful',
  datachannelOnly: true,
  stunUrls: ["stun:stun1.l.google.com:19302"],
});

conn.onDatachannel = () => {
  // connected to remote datachannel and request the latest file.
  conn.getRecordingMetadata();
}

conn.onMetadata = (metadata) => {
  // retrieved the file's metadata and request download the target.
  conn.fetchRecordedVideo(metadata.path);
}

conn.onProgress = (recv, total) => {
  // show up downloading progress of the datachannel.
}

conn.onVideoDownloaded = (file) => {
  // the file is completely downloaded.
  const blob = new Blob([file], { type: 'video/mp4' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'video_filename.mp4';
  document.body.appendChild(a);
  a.click();
  document.body.removeChild(a);
  URL.revokeObjectURL(url);

  conn.terminate();
}

conn.connect();

Set camera properties while streaming

This example only set auto-focus and auto white balance. Other properties see CameraPropertyKey.

let videoRef = document.getElementById('videoElement');

let conn = new PiCamera({
  deviceUid: 'your-custom-uid',
  mqttHost: 'your.mqtt.cloud',
  mqttPath: '/mqtt',
  mqttPort: '8884', // Websocket Port
  mqttUsername: 'hakunamatata',
  mqttPassword: 'Wonderful',
  stunUrls: ["stun:stun1.l.google.com:19302"],
});
  
conn.onStream = (stream) => {
  videoRef.srcObject = stream ?? null;
};
conn.connect();

// click the button with onclick="setAwb()" when it's connected
setAwb = () => {
  conn.setCameraProperty(CameraPropertyKey.AWB_MODE, AwbModeEnum.AwbCloudy);
}

// click the button with onclick="setAf()" when it's connected
setAf = () => {
  conn.setCameraProperty(CameraPropertyKey.AF_MODE, AfModeEnum.AfModeContinuous);
}

Watch videos via the SFU server

This example demonstrates how to watch a live stream through an SFU server. For more details, see Broadcasting Live Stream to 1,000+ Viewers via SFU.

let videoRef = document.getElementById('videoElement');

let conn = new PiCamera({
  signaling: 'websocket',
  websocketUrl: 'wss://free1-api.picamera.live',
  apiKey: 'APIz3LVTsM2bmNi',
  roomId: 'the-room-name'
});

conn.onSfuStream = (sid, stream) => {
  videoRef.srcObject = stream;
};

conn.connect();

Notes on local IP or VPN address

When running PiCamera.js over a local network or a VPN, set stunUrls to null or leave it out of the configuration altogether.

Notes on Mosquitto

When running Mosquitto as your own MQTT server, we have experienced problems running Mosquitto with self-signed certificates with the MQTT client in PiCamera.js. Instead, run Mosquitto without SSL and then interpose nginx. For example:

# mosquitto.conf
listener 1883 localhost
allow_anonymous true

listener 1884
protocol websockets
allow_anonymous true

Then interpose nginx's between the browser and Mosquitto. (This example assumes that the project files live in /home/pi/src/project, for example, with run/ and ssl/ and logs/ and dist/ subdirectories). It will run the secure port on 8443 (not standard port 443!). Change as you see fit -- this is for documentation purposes only.

# nginx.conf
pid /home/pi/src/project/run/nginx.pid;

events {}

http {
  # Map to manage WebSocket upgrade headers
  map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
  }

  # Upstream definition for Mosquitto WebSocket listener
  upstream mosquitto_websocket {
    server localhost:1884;  # Mosquitto WebSocket listener
  }

  # HTTPS server
  server {
    listen 8443 ssl;
    access_log /home/pi/src/project/logs/access.log;
    error_log /home/pi/src/project/logs/error.log;

    ssl_certificate /home/pi/src/project/ssl/server.crt;
    ssl_certificate_key /home/pi/src/project/ssl/server.key;

    location / {
      root /home/pi/src/project/dist/;
      try_files $uri $uri/ =404;
    }

    # Location block for WebSocket proxying to Mosquitto
    location /mqtt {
      proxy_pass http://mosquitto_websocket;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
    }
  }

  # HTTP server
  server {
    listen 8080;
    access_log /home/pi/src/project/logs/access_http.log;
    error_log /home/pi/src/project/logs/error_http.log;

    location / {
      root /home/pi/src/project/dist/;
      try_files $uri $uri/ =404;
    }

    # Location block for WebSocket proxying to Mosquitto over HTTP
    location /mqtt {
      proxy_pass http://mosquitto_websocket;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
    }
  }
}

This example would require PiCamera.js to be initialized as

let conn = new PiCamera({
  deviceUid: 'some-unique-uuid',      // must match pi_webrtc's --uid argument
  mqttHost: window.location.hostname, // same host and
  mqttPort: window.location.port,     // port as page itself
  mqttPath: '/mqtt',                  // to match nginx.conf configuration
});

Notes on self-signed certificates

Most browsers require https for video to work. When using self-signed certificates, you first need to accept the browser's warning about the certificate. You also need to do this explicitly for the websocket host/port. In the above example, you would have to open https://your.mqtt.cloud:8884/ and accept the warning before the example works. Keep on eye on the browser's console to pick up on errors about self-signed certificates and open the wss:// URLs it complains about as https:// to accept the self-signed certificates.

API Documentation

Options
Events
Methods

Options

Available flags for initialization.

Option	Type	Default	Description
signaling	`'mqtt' \| 'websocket'`	`mqtt`	The signaling method.
deviceUid	`string`		The custom `--uid` provided in the running `pi_webrtc`.
mqttHost	`string`		The MQTT server host.
mqttPath	`string`	`/mqtt`	The MQTT server path.
mqttPort	`number`	`8884`	The WebSocket port for the MQTT server.
mqttProtocol	`string`	`wss`	The portocol for the MQTT server.
mqttUsername	`string`		The username for the MQTT server.
mqttPassword	`string`		The password for the MQTT server.
websocketUrl	`string`		The WebSocket URL used to connect to the SFU server.
apiKey	`string`		The API key used to authenticate with the SFU server.
userId	`string`	`(random uuid)`	The user identifier displayed in the room after joining the SFU server.
roomId	`string`		The room ID used to join a session on the SFU server.
stunUrls	`string[]`		An array of STUN server URLs for WebRTC. Leave out or set to null for local network or VPN IP addresses.
turnUrl	`string`		The TURN server URL for WebRTC.
turnUsername	`string`		The username for the TURN server.
turnPassword	`string`		The password for the TURN server.
timeout	`number`	`10000`	The connection timeout in milliseconds (`ms`).
datachannelOnly	`boolean`	`false`	Specifies that the connection is only for data transfer, without media streams.
ipcMode	`string`		Defines the communication mode for `sendMessage()` in IPC (inter-process communication). Accepts `lossy` (UDP-like) or `reliable` (TCP-like) modes.
isMicOn	`boolean`	`true`	Enables the local microphone stream by default if the connection is established.
isSpeakerOn	`boolean`	`true`	Enables the remote audio stream by default if the connection is established.
credits	`boolean`	`true`	Show watermark to run it under credits.
codec	`string`		Codecs include `H264`, `VP8`, `VP9`, and `AV1`.

Events

onConnectionState

= (state: RTCPeerConnectionState) => {}

Emitted when the WebRTC peer connection state changes.
onDatachannel

= (id: ChannelId) => {}

Emitted when the data channel successfully opens for data communication.
onProgress

= (received: number, total: number, type: CmdType) => {}

If any data transfer by datachannel, the on progress will give the received/total info.
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.
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.
onMetadata

= (metadata: VideoMetadata) => {}

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

= (msg: string) => {}

Read IPC message from server.
onRoomInfo

= (participant: RoomInfo) => {}

Emitted when the SFU room information changes.
onQuility

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

Emitted when the quality of SFU connections change.
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()

Start trying to establish the WebRTC connection.
terminate

.terminate()

Terminates the WebRTC connection.
getStatus

.getStatus()

Retrieves the current connection status.
getRecordingMetadata

.getRecordingMetadata()

.getRecordingMetadata(path: string)

.getRecordingMetadata(time: Date)

Retrieves metadata of recording files.

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

If provided with a file path, returns metadata of up to 8 older recordings before the given file.

If provided with a date, returns metadata of the closest recorded file to that time.
- path - The path to an existing recorded file; retrieves metadata of up to 8 older recordings before it.
- time - A specific date/time; retrieves metadata of the closest recorded file.
fetchRecordedVideo

.fetchRecordedVideo(path: string)

Requests a video file from the server.
- path - The path to the video file.
setCameraProperty

.setCameraProperty(key: CameraPropertyKey, value: CameraPropertyValue)

Sets camera properties, such as 3A or so.
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.
sendMessage

.(msg: string)

If ipcMode is set to reliable, the message will be retransmitted until successfully delivered. If set to lossy, the message may be lost, but with lower latency.
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.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Included Third-Party Licenses mqtt: MIT License @livekit/protocol: Apache License 2.0 See the NOTICE file for full license texts of third-party dependencies.

Commercial License If your use case does not permit compliance with the AGPL (e.g., source code disclosure), a commercial license is available. For more information, please contact: 📧 tzu.huan.tai@gmail.com

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github/workflows		.github/workflows
demo		demo
doc		doc
src		src
.gitignore		.gitignore
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
build.js		build.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

TzuHuanTai/picamera.js

Folders and files

Latest commit

History

Repository files navigation

PiCamera.js

Installation

Usage

Examples:

Notes:

API

Example

Live video

Capture a snapshot only

Send message for IPC via DataChannel

Download the latest video record

Set camera properties while streaming

Watch videos via the SFU server

Notes on local IP or VPN address

Notes on Mosquitto

Notes on self-signed certificates

API Documentation

Options

Events

onConnectionState

onDatachannel

onProgress

onStream

onSfuStream

onSnapshot

onMetadata

onVideoDownloaded

onTimeout

onMessage

onRoomInfo

onQuility

onSpeaking

onParticipant

Methods

connect

terminate

getStatus

getRecordingMetadata

fetchRecordedVideo

setCameraProperty

snapshot

sendMessage

toggleMic

toggleSpeaker

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Uh oh!

Contributors 2

Uh oh!

Languages