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
• 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 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.
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 all instances of the 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.

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)

The following 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.

The following scene / source setup will be used to achieve this behaviour:

• A single example scene (1)
• A color source used to block certain parts of the screen (2)
• A display capture source to capture the gameplay (3)

Toggling the visibility of the color source will either show or hide the production tab, by overlaying a grey box over top off it.

Next we need a pattern to match - for this example we will use the "Marine" icon.
This image was created by simply taking a screenshot of the video source and cutting it down to the needed size.

Now we can create our macros to automate the showing and hiding of the color source overlay. We start by creating a macro to show the color source if the pattern is found:

First we create a video condition and select "Display Source" as the video source to analyze (1), "matches pattern" as the type of check we want to perform (2), and which pattern file we want to use (3).
Next we add an action of type "Scene item visibility" to show the color source if the above condition is met. (4)

While this might already work as expected we can tweak the settings of video condition for better results and performance:

First we reduce the interval at which this conditions is checked to roughly only once a second (1) and we reduce the area that needs to be checked to only cover the area where we expect the pattern to occur (2).

An additional improvement that could be made to avoid false positives would be to improve the pattern.
By replacing the area at which the number is being displayed to represent the number of units of that type being produced with an transparent rectangle we can effectively ignore this part of the pattern.

To achieve this we create a new pattern:

... and select it in the video condition (1).
Then we check the "Use alpha channel as mask for pattern" option.

Next we have to tweak the "Threshold" value to be used.
This is best done by clicking the "Show match" option and playing back some example footage.
If the pattern can be found it will be highlighted in a red box.

As a last step we create the inverse of the "Show overlay" macro to automatically hide the overlay if the pattern cannot be found:

Instead of once again performing the same pattern matching we can reuse the results of the checks of the "Show overlay" macro by using a condition of type "Macro" of type "State". (1)
This will safe CPU resources and will also avoid conflicts if you change some parameters on one macro but not the other. Now we just need to add the action to hide the overlay (2) and everything should be set up.

Make sure that the scene switcher is running and enjoy your automatic overlay toggling! :)

Example (object detection)

TODO