picam

Features

Generate H.264/AAC encoded MPEG-TS file from Raspberry Pi Camera (v1/v2) and optionally USB microphone or Wolfson Audio Card
Generate HTTP Live Streaming files with optional encryption
Display timestamp on video image
Display Unicode text with arbitrary font

Required hardware

Raspberry Pi
Raspberry Pi Camera Board (v1 or v2) or compatible cameras
(optionally) USB microphone or Wolfson Audio Card

Supported operating system

Raspberry Pi OS 32-bit or 64-bit (with libcamera enabled)
Raspberry Pi 5 is not supported

Installation

Binary release is available at https://github.com/iizukanao/picam/releases/latest

If you want to build picam yourself, see BUILDING.md.

Using a binary release

The fastest way to use picam is to use a binary release. To set up and use it, run the following commands on your Raspberry Pi OS. It will set up picam in ~/picam/.

# If you have enabled legacy camera support, disable it with raspi-config then reboot
sudo raspi-config

# Install dependencies
sudo apt update
sudo apt install libharfbuzz0b libfontconfig libepoxy0

# Create directories and symbolic links
cat > make_dirs.sh <<'EOF'
#!/bin/bash
DEST_DIR=~/picam
SHM_DIR=/run/shm

mkdir -p $SHM_DIR/rec
mkdir -p $SHM_DIR/hooks
mkdir -p $SHM_DIR/state
mkdir -p $DEST_DIR/archive

ln -sfn $DEST_DIR/archive $SHM_DIR/rec/archive
ln -sfn $SHM_DIR/rec $DEST_DIR/rec
ln -sfn $SHM_DIR/hooks $DEST_DIR/hooks
ln -sfn $SHM_DIR/state $DEST_DIR/state
EOF

chmod +x make_dirs.sh

# Run make_dirs.sh each time the OS is rebooted
./make_dirs.sh

# Optionally, increase microphone volume with alsamixer
alsamixer

# Install picam binary
wget https://github.com/iizukanao/picam/releases/download/v2.0.13/picam-2.0.13-`uname -m`.tar.gz
tar zxvf picam-2.0.13-*.tar.gz
cp picam-2.0.13-*/picam ~/picam/

# Run picam
cd ~/picam
./picam --alsadev hw:1,0

Usage

For High Quality Camera users

Please make sure that at least 160 MB is assigned to GPU.

Create symbolic links (optional, but strongly recommended)

You can take advantage of RAM drive (/run/shm/) and reduce access to SD card. It also provides better quality of recording.

First, stop picam if it is running. Create rec, hooks, and state directories in /run/shm/, then change directories with the same name in picam to symbolic links. Create another symbolic link from /run/shm/rec/archive to somewhere on SD card.

Result:

picam
| ...
|-- archive
|-- hooks -> /run/shm/hooks
|-- rec -> /run/shm/rec
`-- state -> /run/shm/state

/run/shm/
|-- hooks
|-- rec
|   |-- archive -> /home/pi/picam/archive
|   `-- tmp (automatically created by picam)
`-- state

Finding ALSA device name

First, find ALSA device name of your microphone.

$ arecord -l
**** List of CAPTURE Hardware Devices ****
card 1: Device [USB PnP Sound Device], device 0: USB Audio [USB Audio]
  Subdevices: 1/1
  Subdevice #0: subdevice #0

ALSA device name is consisted of hw:<card>,<device>. In the above example, the ALSA device name is hw:1,0.

If you got no soundcards found error, try sudo arecord -l. If that output looks good, you might want to add your user to audio group.

$ sudo usermod -a -G audio $USER
(once logout, then login)
$ groups
wheel audio pi  <-- (make sure that 'audio' is in the list)
$ arecord -l
**** List of CAPTURE Hardware Devices ****
card 1: Device [USB PnP Sound Device], device 0: USB Audio [USB Audio]
  Subdevices: 1/1
  Subdevice #0: subdevice #0

Starting picam

Run picam with your ALSA device name.

$ ./picam --alsadev hw:1,0
configuring devices
capturing started

Recording

To start recording, create a file named hooks/start_record while picam command is running.

$ touch hooks/start_record

You will see smth like disk_usage=23% start rec to rec/archive/2017-08-05_16-41-52.ts in the picam command output.

To stop recording, create a file named hooks/stop_record.

$ touch hooks/stop_record

You will see stop rec in the picam command output.

The recorded MPEG-TS file is in rec/archive/ directory.

To convert MPEG-TS to MP4, run:

$ ffmpeg -i test.ts -c:v copy -c:a copy -bsf:a aac_adtstoasc test.mp4
# or
$ avconv -i test.ts -c:v copy -c:a copy -bsf:a aac_adtstoasc test.mp4

Mute/Unmute

To mute microphone temporarily, create a file named hooks/mute.

$ touch hooks/mute

To unmute microphone, create a file named hooks/unmute.

$ touch hooks/unmute

Command options

picam version 2.0.13
Usage: picam [options]

Options:
 [video]
  -w, --width <num>   Width in pixels (default: 1920)
  -h, --height <num>  Height in pixels (default: 1080)
  -v, --videobitrate <num>  Video bit rate (default: 3000000)
                      Set 0 to disable rate control
  -f, --fps <num>     Frame rate (default: 30.0)
  -g, --gopsize <num>  GOP size (default: same value as fps)
  --vfr               Enable variable frame rate. GOP size will be
                      dynamically controlled.
  --minfps <num>      Minimum frames per second. Implies --vfr.
  --maxfps <num>      Maximum frames per second. Implies --vfr.
  --hflip             Flip image horizontally
  --vflip             Flip image vertically
  --avcprofile <str>  Set AVC/H.264 profile to one of:
                      constrained_baseline/baseline/main/high
                      (default: high)
  --avclevel <value>  Set AVC/H.264 level (default: 4.1)
  --brightness <num>  Adjust image brightness (default: 0.0)
                      0.0=unchanged / -1.0=darkest / 1.0=brightest
  --contrast <num>    Adjust image contrast (default: 1.0)
                      1.0=normal / >1.0=more contrast
  --saturation <num>  Adjust image color saturation (default: 1.0)
                      1.0=normal / 0.0=grayscale / >1.0=more saturated
  --sharpness <num>   Adjust image sharpness (default: 0.0)
                      0.0=no sharpening / >0.0=sharpened
 [audio]
  -c, --channels <num>  Audio channels (1=mono, 2=stereo)
                      Default is mono. If it fails, stereo is used.
  -r, --samplerate <num>  Audio sample rate (default: 48000)
                      The sample rates supported by libfdk_aac encoder are:
                      8000, 11025, 12000, 16000, 22050, 24000,
                      32000, 44100, 48000, 64000, 88200, 96000
  -a, --audiobitrate <num>  Audio bit rate (default: 40000)
  --alsadev <dev>     ALSA microphone device (default: hw:0,0)
  --volume <num>      Amplify audio by multiplying the volume by <num>
                      (default: 1.0)
  --ngate <t,a,h,r>   Enable noise gate and set <threshold volume, attack/hold/release times>
                      optional parameters. Defaults: 1.00, 0.20, 1.00, 0.50.
                      Enter - to use a parameter default.
  --noaudio           Disable audio capturing
  --audiopreview      Enable audio preview
  --audiopreviewdev <dev>  Audio preview output device (default: plughw:0,0)
 [HTTP Live Streaming (HLS)]
  -o, --hlsdir <dir>  Generate HTTP Live Streaming files in <dir>
  --hlsnumberofsegments <num>  Set the number of segments in the m3u8 playlist (default: 3)
  --hlskeyframespersegment <num>  Set the number of keyframes per video segment (default: 1)
  --hlsenc            Enable HLS encryption
  --hlsenckeyuri <uri>  Set HLS encryption key URI (default: stream.key)
  --hlsenckey <hex>   Set HLS encryption key in hex string
                      (default: 75b0a81de17487c88a47507a7e1fdf73)
  --hlsenciv <hex>    Set HLS encryption IV in hex string
                      (default: 000102030405060708090a0b0c0d0e0f)
 [output for node-rtsp-rtmp-server]
  --rtspout           Enable output for node-rtsp-rtmp-server
  --rtspvideocontrol <path>  Set video control socket path
                      (default: /tmp/node_rtsp_rtmp_videoControl)
  --rtspaudiocontrol <path>  Set audio control socket path
                      (default: /tmp/node_rtsp_rtmp_audioControl)
  --rtspvideodata <path>  Set video data socket path
                      (default: /tmp/node_rtsp_rtmp_videoData)
  --rtspaudiodata <path>  Set audio data socket path
                      (default: /tmp/node_rtsp_rtmp_audioData)
 [MPEG-TS output via TCP]
  --tcpout <url>      Enable TCP output to <url>
                      (e.g. --tcpout tcp://127.0.0.1:8181)
 [camera]
  --camera <num>      Choose the camera to use. Use --query to list the cameras.
  --autoex            Enable automatic control of camera exposure between
                      daylight and night modes. This forces --vfr enabled.
  --autoexthreshold <num>  When average value of Y (brightness) for
                      10 milliseconds of captured image falls below <num>,
                      camera exposure will change to night mode. Otherwise
                      camera exposure is in daylight mode. Implies --autoex.
                      (default: 5.0)
                      If --verbose option is enabled as well, average value of
                      Y is printed like y=28.0.
  --ex <value>        Set camera exposure. Implies --vfr. <value> is one of:
                        normal short long custom
  --wb <value>        Set white balance. <value> is one of:
                        off: Disable auto white balance control
                        auto: Search over the whole colour temperature range (default)
                        incandescent: Incandescent AWB lamp mode
                        tungsten: Tungsten AWB lamp mode
                        fluorescent: Fluorescent AWB lamp mode
                        indoor: Indoor AWB lighting mode
                        daylight: Daylight AWB lighting mode
                        cloudy: Cloudy AWB lighting mode
                        custom: Custom AWB mode
  --wbred <num>       Red gain. Implies "--wb off". (0.0 .. 8.0)
  --wbblue <num>      Blue gain. Impli

Picam

Install / Use

README