Library to capture and stream Raspberry Pi camera data directly to NodeJS
npm install pi-camera-connect
pi-camera-connect is a library to capture and stream Raspberry Pi camera data directly to NodeJS.
There are many NPM modules for connecting to the Raspberry Pi camera, why use this?
- Speed: JPEG images can be captured in ~33ms using a built in MJPEG parser
- Efficient: Pictures and video streams are piped directly into Node as a Buffer, keeping all data in memory and eliminating disk I/O
- Usable: Video streams are available as stream.Readable objects that can be piped or listened to
- Tested: Contains automated tests using Jest
- Modern: Uses the latest ESNext features and up to date development practices
- Structure: Ships with TypeScript definition files
$ npm install --save pi-camera-connect
Yarn
$ yarn add pi-camera-connect
Basic Usage
$3
Image capture:
javascript
import { StillCamera } from "pi-camera-connect";
import * as fs from "fs";// Take still image and save to disk
const runApp = async () => {
const stillCamera = new StillCamera();
const image = await stillCamera.takeImage();
fs.writeFileSync("still-image.jpg", image);
};
runApp();
`Video capture:
javascript
import { StreamCamera, Codec } from "pi-camera-connect";
import * as fs from "fs";// Capture 5 seconds of H264 video and save to disk
const runApp = async () => {
const streamCamera = new StreamCamera({
codec: Codec.H264
});
const videoStream = streamCamera.createStream();
const writeStream = fs.createWriteStream("video-stream.h264");
videoStream.pipe(writeStream);
await streamCamera.startCapture();
await new Promise(resolve => setTimeout(() => resolve(), 5000));
await streamCamera.stopCapture();
};
runApp();
`$3
Image capture:
javascript
const { StillCamera } = require("pi-camera-connect");const stillCamera = new StillCamera();
stillCamera.takeImage().then(image => {
fs.writeFileSync("still-image.jpg", image);
});
`Video capture:
javascript
const { StreamCamera, Codec } = require("pi-camera-connect");const streamCamera = new StreamCamera({
codec: Codec.H264
});
const writeStream = fs.createWriteStream("video-stream.h264");
const videoStream = streamCamera.createStream();
videoStream.pipe(writeStream);
streamCamera.startCapture().then(() => {
setTimeout(() => streamCamera.stopCapture(), 5000);
});
`Capturing an image
There are 2 ways to capture an image with :
1. StillCamera.takeImage() - Slow, but higher quality
This is equivalent to running the raspistill command. Under the hood, the GPU will run a strong noise reduction algorithm to make the image appear higher quality.
`javascript
import { StillCamera } from "pi-camera-connect"; const runApp = async () => {
const stillCamera = new StillCamera();
const image = await stillCamera.takeImage();
// Process image...
};
runApp();
`2.
- Fast, but lower quality This works by grabbing a single JPEG frame from a Motion JPEG (MJPEG) video stream . Images captured from the video port tend to have a grainier appearance due to the lack of a strong noise reduction algorithm.
Using this method, you can capture a JPEG image at more or less the frame rate of the stream, eg. 30 fps = ~33ms capture times.
`javascript
import { StreamCamera, Codec } from "pi-camera-connect"; const runApp = async () => {
const streamCamera = new StreamCamera({
codec: Codec.MJPEG
});
await streamCamera.startCapture();
const image = await streamCamera.takeImage();
// Process image...
await streamCamera.stopCapture();
};
runApp();
`Capturing a video stream
Capturing a video stream is easy. There are currently 2 codecs supported: and MJPEG.$3
The GPU on the Raspberry Pi comes with a hardware-accelerated H264 encoder and JPEG encoder. To capture videos in real time, using these hardware encoders are required.$3
A standard NodeJS readable stream is available after calling createStream(). As with any readable stream, it can be piped or listened to.`javascript
import { StreamCamera, Codec } from "pi-camera-connect";
import * as fs from "fs";const runApp = async () => {
const streamCamera = new StreamCamera({
codec: Codec.H264
});
const videoStream = streamCamera.createStream();
const writeStream = fs.createWriteStream("video-stream.h264");
// Pipe the video stream to our video file
videoStream.pipe(writeStream);
await streamCamera.startCapture();
// We can also listen to data events as they arrive
videoStream.on("data", data => console.log("New data", data));
videoStream.on("end", data => console.log("Video stream has ended"));
// Wait for 5 seconds
await new Promise(resolve => setTimeout(() => resolve(), 5000));
await streamCamera.stopCapture();
};
runApp();
`You can test the video by viewing it in
(ships with the Pi):
`
$ omxplayer video-stream.h264
Note that this example produces a raw H264 video. Wrapping it in a video container (eg. MP4, MKV, etc) is out of the scope of this module.API
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
A class for taking still images. Equivalent to running the command.$3
Instantiates a new
StillCamera class.`javascript
const stillCamera = new StillCamera({
...
});
` are:
- width: number - Default: Max sensor width
- height: number - Default: Max sensor height
- rotation: Rotation - Default: Rotation.Rotate0
- - Default: Flip.None
- - Default: 1 ms
- shutter: number - Default: Auto calculated based on framerate (1000000µs/fps). Number is in microseconds
- sharpness: number - Range: -100-100; Default: 0
- - Range: -100-100; Default: 0
- - Range: 0-100; Default: 50
- - Range: -100-100; Default: 0
- - Default: Auto
- exposureCompensation: number - Default: 0
- - Default: Auto
- awbMode: AwbMode - Default: Auto
- analogGain: number - Default: 0
- digitalGain: number - Default: 0$3
Takes a JPEG image from the camera. Returns a
Promise with a Buffer containing the image bytes.
`javascript
const stillCamera = new StillCamera();const image = await stillCamera.takeImage();
`
A class for capturing a stream of camera data, either as or MJPEG.$3
Instantiates a new
StreamCamera class.`javascript
const streamCamera = new StreamCamera({
...
});
` are:
- width: number - Default: Max sensor width
- height: number - Default: Max sensor height
- rotation: Rotation - Default: Rotation.Rotate0
- - Default: Flip.None
- - Default: 17 Mbps
- fps: number - Default: 30 fps
- codec: Codec - Default: Codec.H264
- - Default: SensorMode.AutoSelect
- - Default: Auto calculated based on framerate (1000000µs/fps). Number is in microseconds
- sharpness: number - Range: -100-100; Default: 0
- - Range: -100-100; Default: 0
- - Range: 0-100; Default: 50
- - Range: -100-100; Default: 0
- - Default: Auto
- exposureCompensation: number - Default: 0
- - Default: Auto
- awbMode: AwbMode - Default: Auto
- analogGain: number - Default: 0
- digitalGain: number - Default: 0$3
Begins the camera stream. Returns a Promise that is resolved when the capture has started.$3
Ends the camera stream. Returns a Promise that is resolved when the capture has stopped.$3
Creates a readable stream of video data. There is no limit to the number of streams you can create.Be aware that, as with any readable stream, data will buffer in memory until it is read. If you create a video stream but do not read its data, your program will quickly run out of memory.
Ways to read data so that it does not remain buffered in memory include:
- Switching the stream to 'flowing' mode by calling either
resume(), pipe(), or attaching a listener to the 'data' event
- Calling read() when the stream is in 'paused' modeSee the readable stream documentation for more information on flowing/paused modes.
`javascript
const streamCamera = new StreamCamera({
codec: Codec.H264
});const videoStream = streamCamera.createStream();
await streamCamera.startCapture();
videoStream.on("data", data => console.log("New video data", data));
// Wait 5 seconds
await new Promise(resolve => setTimeout(() => resolve(), 5000));
await streamCamera.stopCapture();
`$3
Takes a JPEG image frame from an MJPEG camera stream, resulting in very fast image captures. Returns a
with a Buffer containing the image bytes.Note:
StreamOptions.codec must be set to Codec.MJPEG, otherwise takeImage() with throw an error.
`javascript
const streamCamera = new StreamCamera({
codec: Codec.MJPEG
});await streamCamera.startCapture();
const image = await streamCamera.takeImage();
await streamCamera.stopCapture();
`
Image rotation options.
-
-
-
- javascript
import { Rotation } from "pi-camera-connect";
`
Image flip options.
-
-
-
- javascript
import { Flip } from "pi-camera-connect";
`
Stream codec options.
-
- javascript
import { Codec } from "pi-camera-connect";
`
Stream sensor mode options.
-
-
-
-
-
-
-
- javascript
import { SensorMode } from "pi-camera-connect";
`These are slightly different depending on the version of Raspberry Pi camera you are using.
#### Camera version 1.x (OV5647):
| Mode | Size | Aspect Ratio | Frame rates | FOV | Binning |
|------|---------------------|--------------|-------------|---------|---------------|
| 0 | automatic selection | | | | |
| 1 | 1920x1080 | 16:9 | 1-30fps | Partial | None |
| 2 | 2592x1944 | 4:3 | 1-15fps | Full | None |
| 3 | 2592x1944 | 4:3 | 0.1666-1fps | Full | None |
| 4 | 1296x972 | 4:3 | 1-42fps | Full | 2x2 |
| 5 | 1296x730 | 16:9 | 1-49fps | Full | 2x2 |
| 6 | 640x480 | 4:3 | 42.1-60fps | Full | 2x2 plus skip |
| 7 | 640x480 | 4:3 | 60.1-90fps | Full | 2x2 plus skip |
#### Camera version 2.x (IMX219):
| Mode | Size | Aspect Ratio | Frame rates | FOV | Binning |
|------|---------------------|--------------|-------------|---------|---------|
| 0 | automatic selection | | | | |
| 1 | 1920x1080 | 16:9 | 0.1-30fps | Partial | None |
| 2 | 3280x2464 | 4:3 | 0.1-15fps | Full | None |
| 3 | 3280x2464 | 4:3 | 0.1-15fps | Full | None |
| 4 | 1640x1232 | 4:3 | 0.1-40fps | Full | 2x2 |
| 5 | 1640x922 | 16:9 | 0.1-40fps | Full | 2x2 |
| 6 | 1280x720 | 16:9 | 40-90fps | Partial | 2x2 |
| 7 | 640x480 | 4:3 | 40-90fps | Partial | 2x2 |
Exposure mode options.
-
-
-
-
-
-
-
-
-
-
-
-
- javascript
import { ExposureMode } from "pi-camera-connect";
`
White balance mode options.
-
-
-
-
-
-
-
-
-
-
- javascript
import { AwbMode } from "pi-camera-connect";
``