akvirtualcamera-wiki/Configure-the-cameras.md

Please read [Build and install](https://github.com/webcamoid/akvirtualcamera/wiki/Build-and-install) page before going further.

# Quick rundown

The first step to create a virtual camera is defining a virtual device:

```
AkVCamManager add-device "Virtual Camera"
```

The command will return a message like:

```
Device created as AkVCamVideoDevice0
```

Keep track of **AkVCamVideoDevice0**, that will be the identifier of the virtual device and you will need it for the following operations. The created device is a blank device without any defined capture formats, that meaning it won't work as-is.  
Now, you must define a at least one capture format for that device, as:

```
AkVCamManager add-format AkVCamVideoDevice0 FORMAT WIDTH HEIGHT FRAME_RATE
```

For example:

```
AkVCamManager add-format AkVCamVideoDevice0 YUY2 640 480 30
```

First format defined is the default frame format.  
You can list all capture formats with:

```
AkVCamManager supported-formats --output
```

The frame rate can be expressed either as an integer or a fraction, for example 15/2.  
Once you finished defining your devices, you must obligatorily apply the changes to the system with.

```
AkVCamManager update
```

**Note**: You must run an update every time you modify any parameter of the virtual camera. Also **NEVER** modify the virtual camera parameters when a client is running it.

# Managing the devices

List all devices:

```
AkVCamManager devices
```

You can remove a device with:

```
AkVCamManager remove-device AkVCamVideoDevice0
```

Or you can remove all devices:

```
AkVCamManager remove-devices
```

You can change the device description with:

```
AkVCamManager set-description AkVCamVideoDevice0 "My Virtual Camera"
```

Or get the device description with:

```
AkVCamManager description AkVCamVideoDevice0
```

# Managing the formats

List all formats:

```
AkVCamManager formats AkVCamVideoDevice0
```

Add a new format at a given index:

```
AkVCamManager add-format --index 5 AkVCamVideoDevice0 YUY2 640 480 30
```

Remove a device format at INDEX with:

```
AkVCamManager remove-format AkVCamVideoDevice0 INDEX
```

Remove all device formats:

```
AkVCamManager remove-formats AkVCamVideoDevice0
```

You can get the default recommended output format with:

```
AkVCamManager default-format --output
```

# No signal picture

When a client program try to play the virtual camera but it isn't receiving any frame, it will show a random dot pattern, you can change it to show a custom picture instead with:

```
AkVCamManager set-picture /path/to/place_holder_picture.png
```

And you can get place holder picture path again with:

```
AkVCamManager picture
```

You must give a full path to a picture file, the supported formats for the picture are:

* BMP (24 bpp and 32 bpp).
* JPG
* PNG

# Loading configurations from a file

Alternatively, you can define and configure all virtual devices at once using an INI file like.  
The INI file follows [QSettings file format](https://doc.qt.io/qt-5/qsettings.html).  
Once you have finished writing your settings file, you can pass it to the manager as:

```
AkVCamManager load settings.ini
```

You don't need to call **update** because **load** will automatically call it for you.  
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.  

## Defining the devices

Following is the code for defining the devices:

```
[Cameras]
cameras/size = 2

cameras/1/description = My Virtual Camera
cameras/1/formats = 1

cameras/2/description = My Other Virtual Camera
cameras/2/formats = 1, 2
```

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:

* **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.

## Defining the formats

Next step is defining the formats:

```
[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 devices. 

## No signal picture

You must add the following lines to the settings file for setting the place holder picture:

```
[General]
default_frame = /path/to/place_holder_picture.png
```