Invocation and Termination

Invocation

The binary name of Inlab-MJPG-Streamer is streamer.

SYNOPSIS

streamer [-d <device>] [-r <resolution>] [-p <port>]
         [-D <deny-ACL>] [-A <allow-ACL>]
         [-R <restrict-ACL>] [-E <extend-ACL>]
         [-u <url-component>] [-m <max-fps>]
         [-n <camera-name>]   
         [-tYb]

Options

The following options are available:

-d <device>

This option specifies the v4l2-device that Inlab-MJPG-Streamer makes accessible over HTTP. If this option is unspecified, the default /dev/video0 is used. In many cases there’s only one single camera connected which is then usually represented exactly by this default.

Example:

$ streamer -d /dev/video2
-r <resolution>

This option specifies the preferred resolution with the format <width>x<height>, the default (if left unspecified) is 640x480 (VGA). To be precise, this is more something like a proposal: The v4l2 device driver chooses the closest camera resolution available and reports this back. Inlab-MJPG-Streamer allows a minimal setting of 160x90 and a maximum of 1920x1080 (full HD) as some sort of plausibility check.

Example:

$ streamer -r 1024x786
-p <port>

This option specifies the port on which Inlab-MJPG-Streamer offers its HTTP service. It always listens on all available interfaces in both IP protocol versions (IPv4 and IPv6). The default of this option is 8080 (if left unspecified).

Example:

$ streamer -p 8085
-D <deny-ACL>

This option loads a denial ACL (access control list) at startup. If specified, every client connecting to the HTTP service is checked if it matches an arbitrary entry in this list. If it matches, the connection is immediately closed. For the syntax of the external ACL files see the description below.

If the deny-ACL is empty or if this option is not specified, no client connection will ever be denied this way. The deny-ACL is generally checked before the allow-ACL.

Example:

$ streamer -D ./deny.acl
-A <allow-ACL>

This option loads an “allow” ACL (access control list) at startup. If specified, every client connecting to the HTTP service is checked if it matches an arbitrary entry in this list. Only if it matches, the connection is allowed and further processed, otherwise it gets immediately closed. For the syntax of the external ACL files see the description below.

If the allow-ACL option is unspecified (no allow-ACL file loaded), all connections are allowed. If an allow-ACL is loaded, only matching clients are permitted. The allow-ACL is generally checked after the deny-ACL.

Example:

$ streamer -A ./allow.acl
-u <url-component>

This option allows to add a secret URL component which needs to be prepended to all HTTP requests. This implements some sort of a “light” security feature, but - of course - be aware that this secret component can be seen on the network since there’s no encryption on packet level. If this URL component is specified and not prepended on a HTTP request, an HTTP 404 “not found” response is returned. The default of this option is "" (empty).

Example:

$ streamer -u MySecretURLComponent
-n <camera-name>

This option specifies a camera name which is inserted at the upper left corner. Adding a camera name requires decoding and re-encoding of each frame and thus consumes additional CPU cycles within the grabber thread.

Example:

$ streamer -n "Cam1 - Data Center"
-t

This option adds a RFC 3339 timestamp at the upper right position of each frame. Adding a timestamp requires decoding and re-encoding each frame and thus consumes additional CPU cycles within the grabber thread.

Example:

$ streamer -tb
-Y

This option forces the device format to be always YUYV 4:2:2. If unspecified Inlab-MJPG-Streamer always tries first to use MJPEG, and falls back to YUYV 4:2:2 only if the camera device doesn’t offer MJPG-mode. In any case: If the camera device is accessed in mode YUYV 4:2:2, Inlab-MJPG-Streamer automatically performs the necessary conversions to JPG with a fixed quality of 90%.

Mode YUYV 4:2:2 typically decreases the internal frame rate substantially, since the USB subsystem needs to transfer the data uncompressed.

Example:

$ streamer -Y
-b

With this “background” option provided, Inlab-MJPG-Streamer detaches itself from the controlling TTY and operates as a daemon in background (after all internal threads are successfully set up and started).

Example:

$ streamer -b
-?

This option (or any other unknown option) displays a short but complete usage description.

Example:

$ streamer -?

Invocation Examples

Starting Inlab-MJPG-Streamer in foreground with all its defaults:

$ streamer

Starting Inlab-MJPG-Streamer with all its defaults and sending it to background:

$ streamer -b

Starting Inlab-MJPG-Streamer in foreground for another video device and HTTP port:

$ streamer -d/dev/video2 -p8085

Starting Inlab-MJPG-Streamer in background for yet another video device, a higher resolution, and allow-ACL and another specific HTTP port:

$ streamer -d/dev/video4 -r1024x768 -p8081 -A/home/pi/allow.acl -b

Starting Inlab-MJPG-Streamer in background with all operating defaults, with a deny-ACL and secret URL component in place:

$ streamer -D/home/pi/deny.acl -uMySecretURLComponent -b

Termination

  • When you are running Inlab-MJPG-Streamer in foreground (no -b option), just type Ctrl-C as usual.

  • When Inlab-MJPG-Streamer is running in background (with the -b option), you need to know which streamer you would like to terminate. For this purpose you need to know the device that it is streaming from, determine the PID (process id) for terminating it with a simple kill command.

Here’s an example for terminating a Inlab-MJPG-Streamer instance currently offering streaming services for /dev/video0:

$ fuser /dev/video0
/dev/video0:         83652m
$ kill 83652
$

The “m” after the PID from the fuser /dev/video0 output stands for the memory mapping access method that is being used and just needs to be ommited in the subsequent kill command.