USB camera

On older ARMv6l / ARMv7l (e.g. Raspberry Pi 1 or 2), USB cameras work but only with a very low framerate. It will work with a higher framerate on more powerfull systems. Because the video stream from an USB camera is usually not encoded in H.264, which is a requirement for Restreamer, it needs to be encoded. This encoding requires significant CPU resources.

Your USB camera needs to be v4l (Video4Linux) compliant in order to work with Restreamer. Because of this, USB cameras currently work only with Restreamer on Linux Docker hosts.

Configure Restreamer

Connect the USB camera. For Restreamer to be able to access the USB camera, you have to stop the Restreamer if it is currently running:

docker stop restreamer
docker rm restreamer

Restart the Restreamer with the USB camera with the environment variable RS_MODE=USBCAM and add the video device from the host to the container as /dev/video:

docker run -d --restart always \
    --name restreamer \
    -e "RS_USERNAME=..." -e "RS_PASSWORD=..." -e "RS_MODE=USBCAM" \
    -p 8080:8080 \
    -v /mnt/restreamer/db:/restreamer/db \
    --device /dev/video0:/dev/video \
    datarhei/restreamer:latest

If you are running this on an ARM device, please use the datarhei/restreamer-armv7l:latest Docker image.

Please read the Video Support section in order to find out what USB camera devices are available.

In order to stream what your USB camera is recording, you have to put rtmp://127.0.0.1/live/usbcam.stream into the “RTMP/RTSP/HLS Video Source” field and press “Start”. Keep in mind that you should set the video setting to copy because the RTMP stream from the USB camera is already H.264 encoded.

USB camera

Environment Variables

These environment variables enable you to control the encoding of the video stream from your USB camera.

Name	Default	Description
`RS_USBCAM_VIDEODEVICE`	`/dev/video`	The path to container video device that you also pass in the command line for Docker.
`RS_USBCAM_FPS`	`25`	Set the framerate. The effective framerate may get changed based on the capabilities of your USB camera.
`RS_USBCAM_GOP`	`50`	Set the GOP size. Usually the framerate multiplied by 2 is a good value.
`RS_USBCAM_BITRATE`	`5000000`	Bitrate of the video stream in bit/s, e.g. `5000000` is 5Mbit/s.
`RS_USBCAM_H264PRESET`	`ultrafast`	Set a preset for H.264 encoding. `ultrafast` is the fasted encoding that requires the least CPU. Read more about the available H.264 presets.
`RS_USBCAM_WIDTH`	`1280`	Video stream width in pixels. You have to set this values according to the capabilities of your USB camera.
`RS_USBCAM_HEIGHT`	`720`	Video stream height in pixels. You have to set this values according to the capabilities of your USB camera.
`RS_USBCAM_AUDIO`	`false`	Set this to `true` to enable audio from your USB camera. Please read more below in the Audio Support section.
`RS_USBCAM_AUDIODEVICE`	`0`	The audio device number according to the ALSA utilities. Please read more below in the Audio Support section.
`RS_USBCAM_AUDIOBITRATE`	`64000`	Bitrate of the audio stream in bit/s, e.g. `64000` is 64Kbit/s.
`RS_USBCAM_AUDIOCHANNELS`	`1`	Number of audio channels. Please read more below in the Audio Support section.
`RS_USBCAM_AUDIOLAYOUT`	`mono`	Layout of audio channels. Please read more below in the Audio Support section.
`RS_USBCAM_AUDIOSAMPLING`	`44100`	Sampling rate of the audio signal. Please read more below in the Audio Support section.

Change the defaults of these environment variable with care and make sure that you know what you are doing.

Video Support

For a list of available video devices on your host system, call (you need to have the v4l-utils installed):

v4l2-ctl --list-devices

The output may look like this:

Webcam C170: Webcam C170 (usb-3f980000.usb-1.1.2):
        /dev/video1

Microsoft® LifeCam HD-3000: Mi (usb-3f980000.usb-1.3):
        /dev/video0

If you want to stream the “LifeCam HD-3000”, you have to add /dev/video0 as /dev/video to the Docker container: --device /dev/video0:/dev/video. If you want to stream the “Webcam C170”, you have to add /dev/video1 as /dev/video to the Docker container: --device /dev/video1:/dev/video.

To see a list of all available formats that you may pass as value for the environment variables RS_USBCAM_FPS, RS_USBCAM_WIDTH, and RS_USBCAM_HEIGHT, call:

v4l2-ctl -d /dev/video0 --list-formats-ext

This will output something like this (shortened):

ioctl: VIDIOC_ENUM_FMT
        Index       : 0
        Type        : Video Capture
        Pixel Format: 'YUYV'
        Name        : YUYV 4:2:2
                Size: Discrete 640x480
                        Interval: Discrete 0.033s (30.000 fps)
                        Interval: Discrete 0.050s (20.000 fps)
                        Interval: Discrete 0.067s (15.000 fps)
                        Interval: Discrete 0.100s (10.000 fps)
                        Interval: Discrete 0.133s (7.500 fps)
                Size: Discrete 1280x720
                        Interval: Discrete 0.100s (10.000 fps)
                        Interval: Discrete 0.133s (7.500 fps)
                Size: Discrete 960x544
                        Interval: Discrete 0.067s (15.000 fps)
                        Interval: Discrete 0.100s (10.000 fps)
                        Interval: Discrete 0.133s (7.500 fps)
                Size: Discrete 800x448
                        Interval: Discrete 0.050s (20.000 fps)
                        Interval: Discrete 0.067s (15.000 fps)
                        Interval: Discrete 0.100s (10.000 fps)
                        Interval: Discrete 0.133s (7.500 fps)
...
(output truncated)

There you see, that you can stream e.g. in a resolution of 1280x720 with 10 frames per second or in a resolution of 640x480 with 30 frames per seconds, just to name a few examples. Use these values for the respective environment variables.

Audio Support

Audio support is disabled by default, however an audio track with silence encoded as AAC will be added to the stream. Use the environment variables RS_USBCAM_AUDIOBITRATE, RS_USBCAM_AUDIOLAYOUT, and RS_USBCAM_AUDIOSAMPLING to modifiy the parameter of the audio stream. Values for RS_USBCAM_AUDIOLAYOUT are usually mono or stereo. There are more known layouts, but they are less common.

Audio is currently only supported on Linux Docker hosts that have the /dev/snd device available. In order to make the sound device available inside of the docker container, you have to add it to the container and enable audio with RS_USBCAM_AUDIO=true:

docker run -d --restart always \
    --name restreamer \
    -e "RS_USERNAME=..." -e "RS_PASSWORD=..." \
    -e "RS_MODE=USBCAM" -e "RS_USBCAM_AUDIO=true" \
    -p 8080:8080 \
    -v /mnt/restreamer/db:/restreamer/db \
    --device /dev/video0:/dev/video \
    --device /dev/snd \
    datarhei/restreamer:latest

The sound device is accessed with the ALSA drivers. Depending what system you have, there may be several audio devices available and you have to pass the RS_USBCAM_AUDIODEVICE with the correct value for your USB camera. To find the correct value, call (you need to have the alsa-utils installed):

arecord --list-devices

The output could be similar to this:

**** List of CAPTURE Hardware Devices ****
card 1: HD3000 [Microsoft® LifeCam HD-3000], device 0: USB Audio [USB Audio]
  Subdevices: 1/1
  Subdevice #0: subdevice #0
card 2: C170 [Webcam C170], device 0: USB Audio [USB Audio]
  Subdevices: 1/1
  Subdevice #0: subdevice #0

The value for RS_USBCAM_AUDIODEVICE is the number after card. In this example it is 1 for the audio from the LifeCam. It is also possible that there are several devices with the same card number. Then you also have to specify the device number in the value, separated with a , after the card number, e.g. 1,0.

For the audio environment variables RS_RASPICAM_AUDIOCHANNELS and RS_RASPICAM_AUDIOSAMPLING you need to know the capabilities of the device. You can list those with the command:

arecord --dump-hw-params  --device hw:1,0

The output could be similar to this:

Recording WAVE 'stdin' : Unsigned 8 bit, Rate 8000 Hz, Mono
HW Params of device "hw:1,0":
--------------------
ACCESS:  MMAP_INTERLEAVED RW_INTERLEAVED
FORMAT:  S8 S16_LE
SUBFORMAT:  STD
SAMPLE_BITS: [8 16]
FRAME_BITS: [8 16]
CHANNELS: 1
RATE: [8000 48000]
PERIOD_TIME: [1000 65536000]
PERIOD_SIZE: [32 524288]
PERIOD_BYTES: [64 524288]
PERIODS: [2 1024]
BUFFER_TIME: (1333 131072000]
BUFFER_SIZE: [64 1048576]
BUFFER_BYTES: [64 1048576]
TICK_TIME: ALL
--------------------
arecord: set_params:1339: Sample format non available
Available formats:
- S8
- S16_LE

The field CHANNELS tells you which channel setups are available (here 1, i.e. mono) and RATE tells you in which range the value for RS_RASPICAM_AUDIOSAMPLING can be (here between 8000 and 48000).

docker run -d --restart always \
    --name restreamer \
    -e "RS_USERNAME=..." -e "RS_PASSWORD=..." \
    -e "RS_MODE=USBCAM" -e "RS_USBCAM_AUDIO=true" -e "RS_USBCAM_AUDIODEVICE=1,0" \
    -p 8080:8080 \
    -v /mnt/restreamer/db:/restreamer/db \
    --device /dev/video0:/dev/video \
    --device /dev/snd \
    datarhei/restreamer:latest