Video condition

The "Video" macro condition allows you to trigger actions when a video source ...

• is similar to a provided pattern or exactly matches it
• contains certain objects
• contains text matching a given pattern
• has changed
• has no output

These different options will be described in more detail below.

Important note

If a video source is currently not being rendered by OBS (e.g. if every instance of the source is hidden) some check types might not work as you would expect.
You can work around this limitation by opening a "Windowed Projector" of the source by right-clicking on the particular source and choosing the "Windowed Projector (Source)" entry in the context menu.

General settings

This section will cover the general settings which are available regardless of which video condition type is chosen.

Video source selection

All video condition types require you to select which video source you want to analyze.
You can select the source by clicking on the desired entry in the combobox.

Condition type selection

You can select which type of check you want to perform in the highlighted combobox.

Image selection

Most condition types require specifying a reference image or pattern the video source's output has to be compared to.
The path can be entered in the highlighted text input field (2) or you can press the "Browse" button to select the file in OS' file explorer.
In some cases you also have the option to create a screenshot of the current output of the video source when pressing the "Browse" button.

Area selection

Most check types of the video condition support only matching a specified area of the video output source. This can be useful if you want to ignore certain areas of the video source.
Another reason to use this option is if you try to apply the video condition checks to a very high resolution source and want to reduce the performance impact of running this condition's checks. (Especially the object detection and pattern matching can become very resource intensive)

To select enable this functionality first tick the corresponding checkbox. (1)
Next either manually enter the area you want to focus on by typing in the desired X coordinate, Y coordinate, width and height. (2)
Alternatively press the "Select area" button to open a preview window of the source and mark the area by drawing a rectangle over it. (3)

Condition types

Exactly matches

When selecting this type of check the video source or the sub-area that was selected to be checked needs to match for every single pixel. That means if resolution of the video source / selected area and the provided input image do not match the condition will always be false.

Does not match

This condition type is the inverse to "exactly matches".
Meaning, if only a single pixel does not match or the resolution of the checked source / area differs to the provided image this condition will be true.

Has changed

This condition type is true if the video source or the selected area has changed.
As the name would suggest, it is most useful if you do not really care about the exact content of a video source but want to trigger actions if something changed.

If you want to ignore minor changes in the image you can enable "pattern matching". (1)

Has not changed

This condition type is the inverse of the "has changed" condition type.

Has no output

This condition is true if the video source has no output at all. (So an image with a "0x0 resolution")
This is not the same as the video source having a black image as video output.

An example of a video source having no output would be if a game capture source has no window to capture or all instances of a particular source are currently hidden. (Eye icon next to source)

Matches pattern

This condition type is used if an exact matching of the video sources output is not possible.

You can specify how similar the video source needs to be to the provided pattern by changing the threshold using the slider. (1)
If you want to match non-rectangle shaped areas of the video source you have the option to use the alpha channel of the provided input image as mask for areas of the pattern which should be ignored. (2)
Depending on the size of the pattern and the video sources resolution the checks might become rather resource expensive. In this case it might be worth it to reduce the frequency at which the checks are performed using (4).
You can press the "Show match" button for a preview of whether or not the provided pattern can be found in the video source. (3)

Contains object

This condition type can be used to detect certain objects in the video source using haar cascade models.

You can specify which model to use using the file selection at (1).
By default a face recognition model will be used.
The "Scale factor" can be used to control the accuracy of the object detection in relation to the CPU resources used. (2)
The "Minimum neighbors" parameter can be used to control the quality of the matches.
So if you get a lot of false positive matches it might be worth increasing its value and if you get too few match it might be worth testing if lowering it leads to better results. (3)
The minimum and maximum size parameters let you control how large the object can be to be considered a match. (4)
If the value is left at 0 it will be ignored and any size will be accepted.
Increasing the minimum size might increase the performance of the object detection.
If you want to preview whether or not objects are successfully being detected you can press the "Show match" button. (5)
As the object detection can be very resource intensive it might be worth considering to decrease the frequency at which the condition is checked. (6)
Limiting the area which is to be check can also drastically improve the performance of this condition type.

Contains text

An essential aspect of the process is to select the appropriate text color that allows for differentiation between the text and the background. Typically, the text's color is the optimal choice, but it may not always be the case.

Choosing the correct text type selection is also crucial, and the descriptions of the available options should hopefully be self-explanatory.

Moreover, detecting larger texts will in general be easier than smaller ones.

It is noteworthy that the text detection model was trained using the English language. Therefore, for example, if you aim to detect French words, the model may encounter difficulties. Nonetheless, you can replace the model under obs-studio\data\obs-plugins\advanced-scene-switcher\res\ocr with the relevant one for a particular language, but keeping the eng.traineddata name. You can find the model data for other languages here: https://github.com/tesseract-ocr/tessdata.

Improving the outcomes could be possible by restricting the search area to the relevant parts of the video source.

Example (output has changed)

Have a look at the motion detection example for a possible use case for the "has changed" check type.

Example (output has not changed)

Have a look at the creating a macro page for an example on how to automatically switch to a specified scene if the output of a video source has not changed for a specified amount of time.

Example (pattern match)

This example will use pattern matching to make sure certain elements of the screen are hidden if a particular pattern can be found. We will use hiding the production tab in Starcraft 2 whenever an a certain unit is built - regardless of how many - as an example.

Example (object detection)

The scene switcher provides a few the OpenCV example models which can be used to detect faces. (E.g. "haarcascade_frontalface_alt.xml")
Thus you could use the object detection condition to automatically switch scenes if a video source contains a face.