picamera.js
Advanced tools
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.
npm install picamera.js
Check out the online demo: Live Demo
You can also view the demo source code here: index.html.
These examples show how to use individual features separately.
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>
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();
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();
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();
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);
}
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();
When running PiCamera.js over a local network or a VPN, set stunUrls to null or leave it out of the configuration altogether.
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
});
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.
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. |
= (state: RTCPeerConnectionState) => {}
Emitted when the WebRTC peer connection state changes.
= (id: ChannelId) => {}
Emitted when the data channel successfully opens for data communication.
= (received: number, total: number, type: CmdType) => {}
If any data transfer by datachannel, the on progress will give the received/total info.
= (stream: MediaStream) => {}
Triggered when a media stream is received from either SFU or MQTT.
= (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.
= (base64: string) => {}
Emitted after calling the snapshot() method. This event emits a base64-encoded image once all image packets are received from the server.
= (metadata: VideoMetadata) => {}
Emitted when the metadata of a recording file is retrieved.
= (file: Uint8Array) => {}
Emitted when a video file is successfully downloaded from the server.
= () => {}
Emitted when the P2P connection cannot be established within the allotted time. Automatically calls the terminate() function.
= (msg: string) => {}
Read IPC message from server.
= (participant: RoomInfo) => {}
Emitted when the SFU room information changes.
= (quality: Quality[]) => {}
Emitted when the quality of SFU connections change.
= (speaking: Speaking[]) => {}
Emitted when an SFU participant starts or stops speaking.
= (participant: Participant[]) => {}
Emitted when the list of participants in the SFU room changes.
.connect()
Start trying to establish the WebRTC connection.
.terminate()
Terminates the WebRTC connection.
.getStatus()
Retrieves the current connection status.
.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.
.fetchRecordedVideo(path: string)
Requests a video file from the server.
path - The path to the video file..setCameraProperty(key: CameraPropertyKey, value: CameraPropertyValue)
Sets camera properties, such as 3A or so.
.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..(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(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(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.
This project is licensed under the AGPL-3.0-only license. Under this license, anyone is free to use, modify, and distribute the code, but any use in network services or any modifications require the source code to be made public. Commercial usage without source code disclosure is not permitted.
If your use case does not permit source code disclosure or you have other licensing requirements, a commercial license is available. This option exempts you from the AGPL's source code sharing requirements and includes dedicated support. The commercial license also enables optional features, such as removing watermarks or unlocking additional functionalities.
For more information, please contact: š§ Email: tzu.huan.tai@gmail.com
FAQs
WebRTC connection for Raspberry Pi Camera
The npm package picamera.js receives a total of 14 weekly downloads. As such, picamera.js popularity was classified as not popular.
We found that picamera.js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Ā It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
CAI is a new open source AI framework that automates penetration testing tasks like scanning and exploitation up to 3,600Ć faster than humans.
Security News
Deno 2.4 brings back bundling, improves dependency updates and telemetry, and makes the runtime more practical for real-world JavaScript projects.
Security News
CVEForecast.org uses machine learning to project a record-breaking surge in vulnerability disclosures in 2025.