Configure the cameras
Please read Build and install page before going further.
akvcam is an unorthodox driver, while traditional Linux drivers can be configured using kernel parameters, kernel parameters are not good enough to describe a relatively complex layout without writing a gigantic, unreadable and unmaintainable parameter line, the other option would be passing the parameters through sysfs, but then when would need to create a daemon, play with init systems and that adds more and more layers of problems to the development. The third option would be offering a fixed set of devices and setting, but that would be a lot far from the experience that want to be offered with the driver.
That's why akvcam reads it's setting from a simple straight forward INI like configuration file, totally discouraged by kernel developers, but this driver is not part of mainline, and we are already breaking a lot of rules, so who cares, we have absolute freedom to do whatever we want with the driver 😄
The driver reads it setting from /etc/akvcam/config.ini file by default, this path can be changed using the config_file kernel parameter. So you start creating the file with:
sudo mkdir -p /etc/akvcam
sudo touch /etc/akvcam/config.ini
sudo chmod -vf 644 /etc/akvcam/config.ini
Before continue, let make it clear that the order of the sections (those enclosed between [ ]) or it's fields (those lines in the form of key = value) does not matters, we are just putting it in natural order to make it easier to understand.
The INI file follows QSettings file format.
You can find an example config.ini here.
Inside of the file, we start defining the devices. The driver supports two types of devices: Capture devices and Output devices.
Capture devices are those which webcam programs will use to capture frames, just like any normal webcam device, when you plug a real webcam into your computer, the system will automatically create a capture device for you, the virtual Capture devices emulates that behavior.
Output devices are those that will receive frames from a streaming program and redirect them to one or more Capture devices.
The following graph shows the data flow in akvcam and the relation between Capture and Output devices:
Let see how we create the devices before going further:
[Cameras]
cameras/size = 2
cameras/1/type = output
cameras/1/mode = mmap, userptr, rw
cameras/1/description = Virtual Camera (output device)
cameras/1/formats = 2
cameras/1/videonr = 7
cameras/2/type = capture
cameras/2/mode = mmap, rw
cameras/2/description = Virtual Camera
cameras/2/formats = 1, 2
cameras/2/videonr = 9
First at all you must create a [Cameras] section and set the number of webcams that will be defined with cameras/size, cameras indexes starts with 1. Each camera has the following properties:
- type: This can be either capture or output to define the type of device as we said before. You must have at least one capture and one output device to have a fully functional system.
- mode: Each device supports 3 streaming modes: mmap, userptr, dmabuf and rw. mmap is the most widely supported mode by far, enabling this is more than enough in most cases. rw allow you to echo or cat frames as raw data directly to the device using the default frame format. A device can support all 4 modes at same time.
- description: The description that will shown to the capture or streaming program.
- formats: is a comma separated list of index of formats supported by the device, we will talk about this in a moment.
- videonr: Set the device number. If for example videonr=7 the the device will be created as /dev/video7. If videonr is already taken, negative or not set, the driver will assign the first free device number.
Each device must also define the pixel formats, resolutions and frame rates for capture/output. There are a few well defined but very popular pixel formats supported.
For Capture devices:
- RGB32
- RGB24
- RGB16
- RGB15
- BGR32
- BGR24
- UYVY
- YUY2
For Output devices:
- RGB24
- BGR24
Output devices support less pixel formats because the driver needs to convert the frames to the format configured in the Capture device, more formats could be added in the future.
Similar to what we did with Devices section, we can define the formats as follows:
[Formats]
formats/size = 2
formats/1/format = YUY2
formats/1/width = 640
formats/1/height = 480
formats/1/fps = 30
formats/2/format = RGB24, YUY2
formats/2/width = 640
formats/2/height = 480
formats/2/fps = 20/1, 15/2
format can be set to any pixel format we been talk before, then set the frame resolution with width and height, fps sets the frame rate and it can be either a positive integer number or a positive fraction in the form numerator/denominator.
You may be noted that the second format has comma separated values, this is because you can actually define many formats with similar properties at once with just a minimal number of lines. The driver will combine the values, so for format 2 in this example you get the following formats:
- RGB24 640x480 20 FPS
- RGB24 640x480 7.5 FPS
- YUY2 640x480 20 FPS
- YUY2 640x480 7.5 FPS
If you want a good compatibility with many capture programs you must provide at least the YUY2 640x480 format in your Capture devices. First format defined is the default frame format for capture/output, and that's the format that will be used for cat/echo with rw mode.
We have defined to the devices and formats used by them, we already have a functional system, but at this point if you try to send frames to the Output devices you will not get any reaction in Capture devices, this is because the devices are not connected and Output devices has not any idea where they must send the incoming frames. We define connections as follows:
[Connections]
connections/size = 1
connections/1/connection = 1:2
A connection is defined in the form o:c0:c1:c2:c3:c4:..., the first number is always the index of an Output device, the following numbers are Capture devices.
Connecting the devices in the opposite way, as for example in the form of c:o0:o1: o2:o3:o4:..., won't work. The following syntax won't work:
[Connections]
connections/size = 1
# This does not works
connections/1/connection = 2:1
Now you have a fully functional system.
When a capture program try to play a Capture device but it isn't receiving any frame from a Output device, it will show a random dot pattern, you can change it to show a custom picture instead. You must add the following lines to the settings file:
[General]
default_frame = /etc/akvcam/default_frame.bmp
You must give a full path to a picture file, only 24 bpp and 32 bpp BMP files are supported for the moment.