Capture Device Options - The Basic Setup

Before you can start using motion you need to know some basics about your camera. Either you have a camera connected directly to your computer. In this case it is a video4linux type of camera. Or you connect to a network camera using a normal web URL.

video4linux (V4L) devices

You need to install your camera with the right driver. It is out of scope of this document to tell you how to do this and it depends on which type of camera.

Once installed the camera(s) will have the device names /dev/video0, /dev/video1, /dev/video2...

FreeBSD has a different naming of devices. When you build Motion for FreeBSD the default device name is /dev/bktr0. Under FreeBSD a TV card has a special device for controlling the tuner (e.g. /dev/tuner0). The option tunerdevice is only valid when Motion is built and running under FreeBSD. For Linux do not include this option in the config file (remove or comment out).

USB cameras take a lot of bandwidth. A USB camera connected to a USB 1.1 port or hub consumes all the bandwidth. Even with a small framesize and low framerate you should not expect to have more than one camera per USB 1.1 controller. If you need more than 1 USB camera add extra USB PCI cards to your computer. There exists cards that have 4 inputs each with their own controller and with full bandwidth. Many 4-input cards only have 1 controller. USB cameras do not have the feature of selecting input channels. To disable the input selection the option input must be set to the value 8 for USB cameras.

Composite video cards are normally made with a chip called BT878 (older cards have a BT848). They all use the Linux driver called 'bttv'.

There are cards with more then one video input but still only one BT878 chip. They have a video multiplexer which input is selected with the config option input. Input channel numbers start at 0 (which is why the value 8 and not 0 disables input selection). There are video capture cards available with 4 or 8 inputs but only one chip. They present themselves as one single video device and you select input using the 'input' option. If you define e.g. 4 thread config files with the same videodevice name but different input numbers Motion automatically goes into round robin mode. See the round robin section for more information. Many TV tuner cards have the input channels: TV Tuner = 0, Standard composite video = 1, S-VHS = 3. Other have TV=0, composite video 1= 1, composite video = 2, S-VHS = 3. For video capture cards input 1 is normally the composite video input.

Some capture cards are specially made for surveillance with for example 4 inputs. Others have a TV tuner, a composite input (phono socket) and perhaps also a S-VHS input. For all these cards the inputs are numbered. The numbering varies from card to card so the easiest is to experiment for 5 minutes with a program that can show the videostream. Use a program such as Camstream or xawtv to experiment with the values.

If you use the TV tuner input you also need to set the frequency of the TV channel using the option frequency. Otherwise set 'frequency' to 0.

Finally you need to set the TV norm. Values: 0 (PAL), 1 (NTSC), 2 (SECAM), 3 (PAL NC no colour). Default is 0 (PAL). If your camera is a PAL black and white you may get a better result with norm=3 (PAL no colour).

If the netcam_url option is defined all the video4linux options are ignored so make sure the netcam_url option is commented out if you do not need it.

These are the parameters used for video4linux devices

auto_brightness

• Type: Boolean
• Range / Valid values: on, off
• Default: off
• Option Topic

Let motion regulate the brightness of a video device. Only recommended for cameras without auto brightness

Motion will try to adjust the brightness of the video device if the images captured are too dark or too light. This option will be most useful for video devices like web cams, which sometimes don't have such an option in hardware.

The auto_brightness feature will adjust the brightness of the device up or down until the value defined by the option brightness is reached (1 = dark, 255 = bright). If brightness is zero auto_brightness will try to adjust to the average brightness level 128.

You need to know if the camera supports auto brightness. Most cameras have auto everything. If your video device already does this for you this option might cause oscillations. If you do not know assume that it has and do not use the Motion auto brightness feature. At least not to start with.

brightness

• Type: Integer
• Range / Valid values: 0 - 255
• Default: 0 (disabled)
• Option Topic

The brightness level for the video device.

Value 0 means that Motion does not set the brightness value but leaves it unchanged.

If this setting is used in conjunction with the auto_brightness feature then this setting is the average brightness level in the range 1 (dark) to 255 (bright) that the auto_brightness feature will try to achieve by adjusting the device brightness up and down.

contrast

• Type: Boolean
• Range / Valid values: 0 - 255
• Default: 0 (disabled)
• Option Topic

The contrast level for the video device.

Disabled (Value 0) means that Motion does not set the contrast value.

framerate

• Type: Integer
• Range / Valid values: 2 - 100
• Default: 100 (no limit)
• Option Topic

Maximum number of frames to be captured from the camera per second.

The faster you fetch pictures from the camera the more CPU load you get and the more pictures get included when Motion is detected.

Motion will stop storing pictures if the framerate is set to less than 2.

Set this parameter to the maximum number of images per second that you want to store either as images or as mpeg films.

To set intervals longer than one second use the 'minimum_gap' option instead.

frequency

• Type: Boolean
• Range / Valid values: 0 - 999999
• Default: 0 (Not set)
• Option Topic

The frequency to set the tuner to (kHz). Valid range: per tuner spec, default: 0 (Don't set it)

This option is only relevant if you have a TV tuner card where you can select the tuner frequency. Your tuner card must support this feature.

height

• Type: Integer
• Range / Valid values: Device Dependent
• Default: 288
• Option Topic

The height of each frame in pixels.

The height of the image in pixels. Motion does not scale so should be set to the actual size of the v4l device. In case of a net camera motion sets the height to the height of the first image read.

Motion actually set the size of the image coming from the video4linux device.

Your camera or capture/TV card will not support any picture size. You must know which frame size (width and height) the camera supports. If you do not know start with width 320 and height 240 which most cameras and capture cards supports.

For some device drivers like pwc (driver for Philips USB cameras) setting the size to a non-standard value makes the driver create an image of the nearest smaller size and create a gray band around the image to fit the size given by motion. Note that it is the driver and not motion that generates the gray band. Motion will try to detect motion in the entire image including the gray band.

Motion requires that dimensions of camera image must have both height and width that are a multiple of 16. Thís is normally not a problem. All standard sizes like 640, 480, 352, 320, 288, 240, ...etc are multiples of 16.

hue

• Type: Integer
• Range / Valid values: 0 - 255
• Default: 0 (disabled)
• Option Topic

The hue level for the video device.

Normally only relevant for NTSC cameras.

input

• Type: Integer
• Range / Valid values: 0 - 7, 8 = disabled
• Default: 8 (disabled)
• Option Topic

Input channel to use expressed as an integer number starting from 0. Should normally be set to 1 for video/TV cards, and 8 for USB cameras.

This parameter is really used only with video capture cards that has more than one input.

However if you set the input number to e.g. 1 for a USB camera (ov511 or pwc driver) motion writes an error message back. If you set it to 8 it does not give you any warning.

If you have a video capture card you can define the channel to tune to using this option. If you are using a USB device, network camera or a capture card without tuner you should set the value to the default 8.

Many TV tuner cards have the input channels: TV Tuner = 0, Standard composite video = 1, S-VHS = 3. Other have TV=0, composite video 1= 1, composite video = 2, S-VHS = 3. It is recommended to set the parameter to 8 for USB cameras as your first try. For video capture cards input 1 is normally the composite video input.

minimum_frame_time

• Type: Integer
• Range / Valid values: 0 - 2147483647
• Default: 0
• Option Topic

Minimum time in seconds between the capturing picture frames from the camera. Default: 0 = disabled - the capture rate is given by the camera framerate.

This option is used when you want to capture images at a rate lower than 2 per second.

When this is enabled the framerate option is used only to set the pace the Motion service the webcam port etc. Running Motion at framerate 2 is normally fine.

This feature is introduced in Motion 3.2.7

norm

• Type: Discrete Strings
• Range / Valid values: 0 (PAL), 1 (NTSC), 2 (SECAM), 3 (PAL NC no colour)
• Default: 0 (PAL)
• Option Topic

Select the norm of the video device. Values: 0 (PAL), 1 (NTSC), 2 (SECAM), 3 (PAL NC no colour). Default: 0 (PAL)

This value is only used for capture cards using the BTTV driver.

rotate

• Type: Discrete Strings
• Range / Valid values: 0, 90, 180, 270
• Default: 0 (not rotated)
• Option Topic

Rotate image the given number of degrees. The rotation affects all saved images as well as mpeg movies.

The rotation feature is used when the camera is hanging upside down (180 degrees) or if you choose a picture format in portrait instead of the normal landscape (90 or 270 degrees).

Note that the CPU load increases when using this feature with a value other than 0. Also note that Motion automatically swaps width and height if you rotate 90 or 270 degrees, so you don't have to touch these options.

saturation

• Type: Integer
• Range / Valid values: 0 - 255
• Default: 0 (disabled)
• Option Topic

The colour saturation level for the video device.

tunerdevice

• Type: String
• Range / Valid values: Max 4095 characters
• Default: /dev/tuner0
• Option Topic

The tuner device used for controlling the tuner in a tuner card. This option is only used when Motion is compiled for FreeBSD.

Make sure to remove or comment out this option when running Motion under Linux.

v4l2_palette

• Type: Integer
• Range / Valid values: 0 - 8
• Default: 8
• Option Topic

Allow to choose preferable palette to be use by motion to capture from those supported by your videodevice. ( new in 3.2.10 )

i.ex if your videodevice supports V4L2 _PIX_FMT_SBGGR8 and V4L2 _PIX_FMT_MJPEG by default motion will use V4L2 _PIX_FMT_MJPEG so set v4l2_palette 1 to force motion use V4L2 _PIX_FMT_SBGGR8 instead.

Values :

V4L2_PIX_FMT_SN9C10X : 0 'S910'
V4L2_PIX_FMT_SBGGR8 : 1 'BA81'
V4L2_PIX_FMT_MJPEG : 2 'MJPEG'
V4L2_PIX_FMT_JPEG : 3 'JPEG'
V4L2_PIX_FMT_RGB24 : 4 'RGB3'
V4L2_PIX_FMT_UYVY : 5 'UYVY'
V4L2_PIX_FMT_YUYV : 6 'YUYV'
V4L2_PIX_FMT_YUV422P : 7 '422P'
V4L2_PIX_FMT_YUV420 : 8 'YU12'

videodevice

• Type: String
• Range / Valid values: Max 4095 characters
• Default: /dev/video0 (FreeBSD: /dev/bktr0)
• Option Topic

The video device to be used for capturing. Default for Linux is /dev/video0. for FreeBSD the default is /dev/bktr0.

This is the video4linux device name. Ignore this for net cameras.

width

• Type: Integer
• Range / Valid values: Device Dependent
• Default: 352
• Option Topic

The width in pixels of each frame. Valid range is camera dependent.

Motion does not scale so should be set to the actual size of the v4l device.

In case of a net camera motion sets the height to the height of the first image read.

Motion actually set the size of the image coming from the video4linux device.

Your camera or capture/TV card will not support any picture size. You must know which frame size (width and height) the camera supports. If you do not know start with width 320 and height 240 which most cameras and capture cards supports.

For some device drivers like pwc (driver for Philips USB cameras) setting the size to a non-standard value makes the driver create an image of the nearest smaller size and create a gray band around the image to fit the size given by motion. Note that it is the driver and not motion that generates the gray band. Motion will try to detect motion in the entire image including the gray band.

Motion requires that dimensions of camera image must have both height and width that are a multiple of 16. Thís is normally not a problem. All standard sizes like 640, 480, 352, 320, 288, 240, ...etc are multiples of 16.

Network Cameras

Motion can connect to a network camera through a normal TCP socket. All you need to give it is the URL. The URL given must return either one single jpeg picture or an mjpeg stream. For the time being Motion cannot connect to a video stream such a mpeg, mpeg4, divx. The URL must return one single jpeg image or an mjpeg stream! You can connect through a proxy server.

Also watch out that you do not use a URL that create an HTML page with an embedded jpg. What must be returned is the jpg picture itself or the raw mjpeg stream.

When the netcam_url is defined all the video4linux options above are ignored!!

If the connection to a network camera is lost - Motion will reuse the last good image for approx 30 seconds. AFter 30 seconds the image is replaced by a grey image with a text telling that the signal is lost and when the connection was lost. This text and its date format is not configurable and there are no plans to make it configurable in order to keep the number config options under control.

Note that Motion requires that dimensions of camera image must have both height and width that are a multiple of 16. Thís is normally not a problem. All standard sizes like 640, 480, 352, 320, 288, 240, ...etc are multiples of 16. But if you intend to monitor a network camera which is saving jpeg images you may have to pay attention to the dimensions of the picture.

The network camera feature has been completely re-written in Motion 3.2.2. We believe the netcam feature is much more stable now that it was in previous versions. Motion tries to reconnect to the camera if the connection is lost. There is no official standard for mjpeg and we know that there are probably still some cameras that are not yet supported. If you run into a problem please file a Bug Report with as much information about the format as possible. A binary raw dump of the first 2-3 frames with headers and boundary strings is very useful. You can see how to make it on the special topic NetcamMjpegStreamDumps. When you have the file you can upload it to the same topic.

netcam_http

• Type: Discrete Strings
• Range / Valid values: 1.0, keep_alive, 1.1
• Default: 1.0
• Option Topic

The setting for keep-alive of network socket, should improve performance on compatible net cameras. ( new in 3.2.10 )

• 1.0: the historical implementation using HTTP/1.0, closing the socket after each http request.
• keep_alive: Use HTTP/1.0 requests with keep alive header to reuse the same connection.
• 1.1: Use HTTP/1.1 requests that support keep alive as default.

netcam_proxy

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
• Option Topic

URL to use for a netcam proxy server, if required. The syntax is http://myproxy:portnumber

Use this if you need to connect to a network camera through a proxy server.

Example of syntax: "http://myproxy.mydomain.com:1024

If the proxy port number is 80 you can ommit the port number. Then the syntax is use "http://myproxy.mydomain.com" .

Leave this option undefined if you do not use a proxy server.

netcam_tolerant_check

• Type: Boolean
• Range / Valid values: on, off
• Default: off
• Option Topic

Set less strict jpeg checks for network cameras with a poor/buggy firmware.

netcam_url

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
• Option Topic

Specify an url to a downloadable jpeg file or raw mjpeg stream to use as input device. Such as an AXIS 2100 network camera.

Example of URL: http://www.gate.com/pe1rxq/jeroen.jpg.

Motion can connect to a network camera through a normal TCP socket. All you need to give it is the URL. The URL given must return either one single jpeg picture or an mjpeg stream. For the time being Motion cannot connect to a video stream such a mpeg, mpeg4, divx. The URL must return one single jpeg image or an mjpeg stream!

Also watch out that you do not use a URL that create an HTML page with an embedded jpg. What must be returned is the jpg picture itself or the raw mjpeg stream.

When the netcam_url is defined all the video4linux options are ignored!!

Motion can also fetch jpeg pictures via ftp. You then use the ftp:// syntax instead.

netcam_userpass

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
• Option Topic

For network cameras protected by username and password, use this option for HTTP 1.1 Basic authentication. The string is specified as username:password. Do not specify this option for no authentication.

To use no authentication simply remove this option from the config file comment it out with "#" or ";" in front.

Round Robin feature

This feature is automatically activated where multiple threads are sharing the same video device (for example /dev/video0). Each thread can then set different input channels to change camera with the input option or by tuning the tuner with frequency option.

Round Robin is not relevant for Network cameras or standard USB web cameras. The Round Robin feature is used with video capture cards which have multiple inputs per video chip.

Note that round robin is not the ideal way to run multiple cameras. When the capture card changes input it takes a little while before the decoder chip has syncronized to the new camera. You can improve this if you have expensive cameras with a syncronize input. Only one camera can be decoded at a time so if you have 4 cameras connected 3 of the camera threads will need to wait for their turn. The fact that cameras have to take turns and the fact that you have to skip a few frames after each turn dramatically lowers the possible framerate. You can get a high framerate by viewing each camera for a long time. But then you may miss the action on one of the inactive cameras. If you can affort it avoid Round Robin and buy the more expensive type of capture cards that has one decoder chip per input. If you only need 2 or 3 cameras you can also simply put 2 or 3 cheap TV cards in the computer. Linux has no problem working with multiple TV cards.

• If multiple threads use the same video device, they each can capture roundrobin_frames number of frames before having to share the device with the other threads.
• When another thread wants to watch another input or frequency or size the first roundrobin_skip number of frames are skipped to allow the device to settle.
• The last option switch_filter is supposed to prevent the change of camera from being detected as Motion. Its function is not perfect and sometimes prevents detection of real motion. You should start with having the option disabled and then try with the option enabled to see if you can skip less frames without loosing the detection of the type of motion you normally want to detect.

These are the special Round Robin options

roundrobin_frames

• Type: Integer
• Range / Valid values: 1 - 2147483647
• Default: 1
• Option Topic

Specifies the number of frames to capture before switching inputs, this way also slow switching (e.g. every second) is possible.

The Round Robin feature is automatically activated where multiple threads are sharing the same video device. Each thread can then set different input channels or frequencies to change camera.

If multiple threads use the same video device, they each can capture roundrobin_frames number of frames before having to share the device with the other threads.

roundrobin_skip

• Type: Integer
• Range / Valid values: 1 - 2147483647
• Default: 1
• Option Topic

Specifies the number of frames to skip after a switch. (1 if you are feeling lucky, 2 if you want to be safe).

The Round Robin feature is automatically activated where multiple threads are sharing the same video device. Each thread can then set different input channels or frequencies to change camera.

When another thread wants to watch another input or frequency or size the first roundrobin_skip number of frames are skipped to allow the device to settle.

switchfilter

• Type: Boolean
• Range / Valid values: on, off
• Default: off
• Option Topic

Turns the switch filter on or off. The filter can distinguish between most switching noise and real motion. With this you can even set roundrobin_skip to 1 without generating much false detection.

This is a round robin related feature used when you have a capture card with multiple inputs (controlled by the 'input' option) on the same videodevice.

This feature was seriously broken until Motion 3.2.4

-- KennethLavrsen - 11 Apr 2005