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** (the device ID), that will be the identifier of the virtual device and you will need it for the following operations.
You can also set a custom device ID with for example:

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

This way the device will be created as **FakeCamera0** instead of using the default prefix and numeration (AkVCamVideoDeviceNUMBER), there is no particular rule for the custom ID, you can use any character combination at your choice.  
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/1/id = MyFakeCamera0

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.
* **id**: Set a custom device ID. This property is optional.

## 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
```