diff --git a/Variables.md b/Variables.md new file mode 100644 index 0000000..0812748 --- /dev/null +++ b/Variables.md @@ -0,0 +1,100 @@ +# Variables + +Variables allow users to simplify complex [macro](Macros#what-are-macros) setups. +They each have a name and a value, which can be checked using the Variable condition and modified using the Variable action. + +Variables can also be used in scene selections or scene item selections in place of scenes or sources. +In this case the value of the variable will be used to find the corresponding scene or source. + +## Creating a new variable + +A new variable can be added to a Variable condition or action by clicking on the "Add new variable" entry in the variable selection menu. + +![AddVar](https://user-images.githubusercontent.com/19472752/193638051-9c6c32d5-a6a8-4f1c-adeb-67ca42ebd873.png) + +When selecting this entry a dialog will open in which you will have to enter the variable properties: + +![VarProps](https://user-images.githubusercontent.com/19472752/193638572-caca0856-cdca-4faf-b89d-ee28dcaf6d72.PNG) + + * Unique name for this new variable (1). + * The current value of the variable (2). + * What to do with the current value when closing OBS: (3) + * Don't save it, resulting in the value to be empty when restarting OBS. (a) + * Saving it, resulting in the current value to be restored when restarting OBS. (b) + * Setting it to a different value on OBS restart. (c) + +![VarSave](https://user-images.githubusercontent.com/19472752/193638337-d02b5241-8580-4c7f-a272-7e36d9280860.png) +## Modifying existing variables + +![VarProp](https://user-images.githubusercontent.com/19472752/193638697-691d3980-5ca0-4917-9232-e6809b85c5da.png) + +To modify the properties of an existing variable simply select it in the drop down menu of a variable action or condition and click the marked gear symbol. +Next click the "Properties" entry and a dialog like described above will open in which you can modify the variable's settings. + +The gear icon will also allow you to rename or remove existing variable. + +## Variable condition + +![VarCond](https://user-images.githubusercontent.com/19472752/193638777-67d78b75-0742-4c0b-b714-66a2c1e7b401.PNG) + +The Variable condition will allow you to test for various properties of the value of a given variable. +It supports checking if the variable ... + * equals a given value. + * is empty. + * equals a given number. + * is less / greater than a given number. + * has changed. + +## Variable action + +![VarAction](https://user-images.githubusercontent.com/19472752/193638988-9939ee0d-82af-4684-a1fa-76e942fbb8db.PNG) + +The Variable action will allow you to modify the value of a given variable in various ways. +It supports ... + * setting the value of a variable. + * appending to the value of a variable. + * appending the value of another variable. + * in-/ decrement the value of a given variable. (Assuming it is a valid number) + +## Example "Podcast" + +The following example is intended to showcase how to set up [macros](Macros#what-are-macros) to automatically switch scenes in a podcast setting, with scenes focusing on a single person in case only single person is speaking and a scene in case multiple people are speaking at the same time. + +The example will use the Variable "Next Scene" to indicate which scene the advanced scene switcher will switch to at the end of the check interval. + +### Setup + +The following setup is assumed: + * Three audio input sources named "Guest 1 mic", "Guest 2 mic", and "Host mic". + * Four scenes are created named "Guest 1 scene", "Guest 2 scene", "Host scene", and "Wide scene". + The first three represent a scene focusing on the guests or host respectively and the last one is used when more than one person is speaking at a time. + +### Macros + +Three [macros](Macros#what-are-macros) are created to set the variable "Next scene" to the respective scene if only a single person is speaking. + +This is achieved by using an [audio condition](Audio-condition) (1) to check the volume of the particular audio source and then setting the variable to the desired value using a [variable action](Variables#Variable-action) (2). +Optionally one can add a [duration modifier](Macro-duration-modifiers) (3) to make sure the scenes are not switched to frequently. + +![G1](https://user-images.githubusercontent.com/19472752/193794441-c52f49f8-e46b-4108-a41d-638fb96589fd.PNG) + +Similarly, the other two [macros](Macros#what-are-macros) are created using different sources and values for the variable. + +![G2](https://user-images.githubusercontent.com/19472752/193794978-b61e05b5-d9d9-4f9f-b77a-3a160f20005e.PNG) + +![H](https://user-images.githubusercontent.com/19472752/193794984-ffb4e9dd-6973-4258-bc94-cadaa73ff99c.PNG) + +To handle the case of multiple people speaking at the same time we use the "Macro" condition in combination with the option to check the states of other [macros](Macros#what-are-macros). +In case of more than one of the other [macros](Macros#what-are-macros) being true we set the variable to the name of the wide scene. + +![W](https://user-images.githubusercontent.com/19472752/193795372-f23791a8-4571-4db8-bd4c-0744ff6edfb8.PNG) + +Finally, we add a [macro](Macros#what-are-macros) that does the scene switching. +To avoid unnecessary scene switches we choose to only run this [macro](Macros#what-are-macros) if the value of the variable changed using the [variable condition](Variables#Variable-condition). + +![SS](https://user-images.githubusercontent.com/19472752/193795600-e5745fac-b517-45f5-b56e-24b6ec5bbcf5.PNG) + +Note that it is recommended that the [macro](Macros#what-are-macros) switching the scene is below the [macros](Macros#what-are-macros) setting the value for the "Next Scene" variable. +Otherwise, the value of the previous interval will be used, which might lead to undesired effects. + +Without the use of a variable one would have to repeatedly add condition checks to make sure a scene switch did not already happen to avoid rapidly switching between in the same interval.