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

$ npm install --save pi-camera-connect 

Yarn

$ yarn add pi-camera-connect 

Image capture:

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:

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();

Image capture:

const { StillCamera } = require('pi-camera-connect'); const stillCamera = new StillCamera(); stillCamera.takeImage().then(image => { fs.writeFileSync('still-image.jpg', image); });

Video capture:

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); });

There are 2 ways to capture an image with pi-camera-connect:

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.

   import { StillCamera } from 'pi-camera-connect'; const runApp = async () => { const stillCamera = new StillCamera(); const image = await stillCamera.takeImage(); // Process image... }; runApp();

2. StreamCamera.takeImage() - 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.

   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 is easy. There are currently 2 codecs supported: H264 and MJPEG.

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.

A standard NodeJS readable stream is available after calling createStream(). As with any readable stream, it can be piped or listened to.

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 omxplayer (ships with Raspbian):

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

• StillCamera
  • constructor(options?: StillOptions): StillCamera
  • takeImage(): Promise<Buffer>
• StreamCamera
  • constructor(options?: StreamOptions): StreamCamera
  • startCapture(): Promise<void>
  • stopCapture(): Promise<void>
  • createStream(): stream.Readable
  • takeImage(): Promise<Buffer>
• Rotation
• Flip
• Codec
• SensorMode
• ExposureMode
• AwbMode
• DynamicRange
• ImageEffectMode

A class for taking still images. Equivalent to running the raspistill command.

Instantiates a new StillCamera class.

const stillCamera = new StillCamera({ ... });

StillOptions are:

• width: number - Default: Max sensor width
• height: number - Default: Max sensor height
• rotation: Rotation - Default: Rotation.Rotate0
• flip: Flip - Default: Flip.None
• delay: number - 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
• contrast: number - Range: -100-100; Default: 0
• brightness: number - Range: 0-100; Default: 50
• saturation: number - Range: -100-100; Default: 0
• iso: number - Range: 100-800; Default: Auto
• exposureCompensation: number - Range: -10-10; Default: 0
• exposureMode: ExposureMode - Default: ExposureMode.Auto
• awbMode: AwbMode - Default: AwbMode.Auto
• awbGains: [number, number] - Range: 0.0-8.0; Default: undefined
• analogGain: number - Range: 1.0-12.0 (OV5647: 1.0-8.0); Default: 0
• digitalGain: number - Range: 1.0-64.0; Default: 0
• quality: number - Range: 0-100; Default: 100
• colorEffect: [number, number] (U, V) - Range: 0-255; Default: undefined
• imageEffectMode: ImageEffectMode - Default: ImageEffectMode.None
• dynamicRange: DynamicRange - Default: DynamicRange.Off
• videoStabilization: boolean - Default: false
• raw: boolean - Default: false
• meteringMode - Default: MeteringMode.Off
• thumbnail: [number, number, number] | false (X, Y, Q) - Default: [64, 48, 35]; false to dismiss thumbnail
• flickerMode - Default: FlickerMode.Off
• burst: boolean - Default: false
• roi: [number, number, number, number] (X, Y, W, H) - Range: 0.0-1.0; Default: [0, 0, 1, 1] (Full sensor)
• statistics: boolean - Default: false
• exif: { [key:string]: string | number } | false - Default: Default camera values; false to dissmis default exif
• gpsExif: boolean - Default: false
• annotate: (number | string)[] - Default: No annotations
• annotateExtra: [number, string, string] (fontSize, fontColor, backgroundColor) - Default: [32, '0xff', '0x808000']

Takes a JPEG image from the camera. Returns a Promise with a Buffer containing the image bytes.

const stillCamera = new StillCamera(); const image = await stillCamera.takeImage();

A class for capturing a stream of camera data, either as H264 or MJPEG.

Instantiates a new StreamCamera class.

const streamCamera = new StreamCamera({ ... });

StreamOptions are:

• width: number - Default: Max sensor width
• height: number - Default: Max sensor height
• rotation: Rotation - Default: Rotation.Rotate0
• flip: Flip - Default: Flip.None
• bitRate: number - Default: 17000000 (17 Mbps)
• fps: number - Default: 30 fps
• codec: Codec - Default: Codec.H264
• sensorMode: SensorMode - Default: SensorMode.AutoSelect
• shutter: number - Default: Auto calculated based on framerate (1000000µs/fps). Number is in microseconds
• sharpness: number - Range: -100-100; Default: 0
• contrast: number - Range: -100-100; Default: 0
• brightness: number - Range: 0-100; Default: 50
• saturation: number - Range: -100-100; Default: 0
• iso: number - Range: 100-800; Default: Auto
• exposureCompensation: number - Range: -10-10; Default: 0
• exposureMode: ExposureMode - Default: ExposureMode.Auto
• awbMode: AwbMode - Default: AwbMode.Auto
• awbGains: [number, number] - Range: 0.0-8.0; Default: undefined
• analogGain: number - Range: 1.0-12.0 (OV5647: 1.0-8.0); Default: 0
• digitalGain: number - Range: 1.0-64.0; Default: 0
• colorEffect: [number, number] (U, V) - Range: 0-255; Default: undefined
• imageEffectMode: ImageEffectMode - Default: ImageEffectMode.None
• dynamicRange: DynamicRange - Default: DynamicRange.Off
• videoStabilization: boolean - Default: false
• meteringMode - Default: MeteringMode.Off
• flickerMode - Default: FlickerMode.Off
• roi: [number, number, number, number] (X, Y, W, H) - Range: 0.0-1.0; Default: [0, 0, 1, 1] (Full sensor)
• statistics: boolean - Default: false
• annotate: (number | string)[] - Default: No annotations
• annotateExtra: [number, string, string] (fontSize, fontColor, backgroundColor) - Default: [32, '0xff', '0x808000']

Begins the camera stream. Returns a Promise that is resolved when the capture has started.

Ends the camera stream. Returns a Promise that is resolved when the capture has stopped.

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' mode

See the readable stream documentation for more information on flowing/paused modes.

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();

Takes a JPEG image frame from an MJPEG camera stream, resulting in very fast image captures. Returns a Promise with a Buffer containing the image bytes.

Note: StreamOptions.codec must be set to Codec.MJPEG, otherwise takeImage() with throw an error.

const streamCamera = new StreamCamera({ codec: Codec.MJPEG, }); await streamCamera.startCapture(); const image = await streamCamera.takeImage(); await streamCamera.stopCapture();

Image rotation options.

• Rotation.Rotate0
• Rotation.Rotate90
• Rotation.Rotate180
• Rotation.Rotate270

import { Rotation } from 'pi-camera-connect';

Image flip options.

• Flip.None
• Flip.Horizontal
• Flip.Vertical
• Flip.Both

import { Flip } from 'pi-camera-connect';

Stream codec options.

• Codec.H264
• Codec.MJPEG

import { Codec } from 'pi-camera-connect';

Stream sensor mode options.

• SensorMode.AutoSelect
• SensorMode.Mode1
• SensorMode.Mode2
• SensorMode.Mode3
• SensorMode.Mode4
• SensorMode.Mode5
• SensorMode.Mode6
• SensorMode.Mode7

import { SensorMode } from 'pi-camera-connect';

These are slightly different depending on the version of Raspberry Pi camera you are using.

*For frame rates over 120fps, it is necessary to turn off automatic exposure and gain control using -ex off. Doing so should achieve the higher frame rates, but exposure time and gains will need to be set to fixed values supplied by the user.

Exposure mode options.

• ExposureMode.Off
• ExposureMode.Auto
• ExposureMode.Night
• ExposureMode.NightPreview
• ExposureMode.Backlight
• ExposureMode.Spotlight
• ExposureMode.Sports
• ExposureMode.Snow
• ExposureMode.Beach
• ExposureMode.VeryLong
• ExposureMode.FixedFps
• ExposureMode.AntiShake
• ExposureMode.Fireworks

import { ExposureMode } from 'pi-camera-connect';

White balance mode options.

• AwbMode.Off
• AwbMode.Auto
• AwbMode.Sun
• AwbMode.Cloud
• AwbMode.Shade
• AwbMode.Tungsten
• AwbMode.Fluorescent
• AwbMode.Incandescent
• AwbMode.Flash
• AwbMode.Horizon
• AwbMode.GreyWorld

import { AwbMode } from 'pi-camera-connect';

Image Effect options.

• ImageEffectMode.None
• ImageEffectMode.Negative
• ImageEffectMode.Solarise
• ImageEffectMode.Sketch
• ImageEffectMode.Denoise
• ImageEffectMode.Emboss
• ImageEffectMode.OilPaint
• ImageEffectMode.Hatch
• ImageEffectMode.GPen
• ImageEffectMode.Pastel
• ImageEffectMode.Watercolour
• ImageEffectMode.Film
• ImageEffectMode.Blur
• ImageEffectMode.Saturation
• ImageEffectMode.ColourSwap
• ImageEffectMode.WashedOut
• ImageEffectMode.Posterise
• ImageEffectMode.ColourPoint
• ImageEffectMode.ColourBalance
• ImageEffectMode.Cartoon

import { ImageEffectMode } from 'pi-camera-connect';

Dynamic Range options.

• DynamicRange.Off
• DynamicRange.Low
• DynamicRange.Medium
• DynamicRange.High

import { DynamicRange } from 'pi-camera-connect';

Dynamic Range options.

• MeteringMode.Average
• MeteringMode.Spot
• MeteringMode.Backlit
• MeteringMode.Matrix

import { MeteringMode } from 'pi-camera-connect';

Dynamic Range options.

• FlickerMode.Off
• FlickerMode.Auto
• FlickerMode.Frq50hz
• FlickerMode.Frq60hz

import { FlickerMode } from 'pi-camera-connect';