View source for Zyzyl's Multi-cam Switcher tool

[[File:Multi-cam switcher overview.jpg|thumb|512px|The Multi-cam Switcher tool with 2 preview screens visible]]
This multi-cam switcher tool dramaticaly enhances filming or streaming workflows for people wanting to play with multiple camera angles. It allows you to easily create, fine tune, and switch between all of your viewpoints. A major improvement over the standard Resonite streaming UI is the ability to ''preview all your available shots'' at all times!

The tool can be found in this public folder <code>resrec:///U-Zyzyl/R-cc51cd79-db99-4ec4-aa72-c72761617bfc</code> along with documentation and a copy of the [https://creativecommons.org/licenses/by/4.0/ Attribution 4.0 International (CC BY 4.0) license]. Basically, this license means that '''the tool is free to use for any purpose but you must provide reasonable attribution to Zyzyl''' as the tool's original creator. The license also allows for freely creating and releasing modified versions with some additional conditions. Please see [[#License]] for more information. Sharing the tool with other users is explicitly allowed and encouraged. If you do so, please share the public folder containing the tool rather than just the multi-cam switcher UI alone. This will help to ensure everyone has the most up-to-date version along with the documentation and license.

It will be hard to fully utilize this tool without a basic understanding of the built-in Resonite streamer camera and UI. ProbablePrime's tutorial series is highly recommended: [https://www.youtube.com/watch?v=PFe3mb3JKYY part 1], [https://www.youtube.com/watch?v=Kymxo4O4Zzk part 2], and [https://www.youtube.com/watch?v=7dMRq-D-GGI part 3].

If you would like to provide feedback or suggestions please message Zyzyl#1441 on Discord or Zyzyl within Resonite. Both positive reviews and constructive criticism are very welcome. Please reach out if you are willing to translate this tool and/or documentation into other languages. 

== Quick Start ==
# Spawn the multi-cam switcher tool and your Resonite streaming camera.
# Put your camera in the green camera anchor on the right hand side of the UI.
# Add new viewpoints by using one of the 'Create New' button options.
# You can switch the active viewpoint (indicated by a red border) by laser clicking on any of the preview screens as long as your streaming camera is in the anchor. 
# You can fine tune all types of view point using the settings (click the cogwheel button in the header of each preview screen). For static viewpoints you can also grab the blue camera visual to do general positioning. 
# When you're finished setting up, you can leave editing mode by pressing the 'Disable editing' button on the lower toolbar. Disabling editing locks most things from being changed and prevents any stray laser clicks from messing up your shots!
# Lastly you can hide the multi-cam switcher UI from the stream camera using the InteractiveCameraObjectExcludeTip (see [[#Hiding the multi-cam switcher UI from the streamer camera]] for details).

Happy filming!

== Getting the Multi-cam Switcher tool ==
The tool is available from this public folder <code>resrec:///U-Zyzyl/R-cc51cd79-db99-4ec4-aa72-c72761617bfc</code>. If you copy and paste that record URL into the Resonite window it will spawn a copy of the public folder which you can save to your inventory. Inside the public folder there is (in order):
* The Multi-cam Switcher tool.
* A variant of this documentation.
* A copy of the [https://creativecommons.org/licenses/by/4.0/ Attribution 4.0 International (CC BY 4.0) license] text.
* A copy of the Resonite InteractiveCameraObjectExcludeTool included for convenience (this is '''not''' covered by the above license and Zyzyl did not create it - it's a part of the Resonite's codebase).

You can spawn out any of the above items by double clicking on the inventory icon. It's recommended to always get the tool from the public folder (rather than saving your own copy) to ensure that you get the most up-to-date version.

== Tool layout ==
The tool is composed of 3 major parts. There is the upper UI piece called the 'display', the lower UI piece called the 'toolbar', and the green camera anchor which sits on the right of the tool when empty. The display UI contains the viewpoint preview screens and the 'Create New' option buttons. Each preview screen has a header which contains the viewpoint name and several buttons.

The display and toolbar automatically adjust their size depending on various factors (e.g. preview screens being added to the display). 

Note that only the user who spawned the tool can interact with the display and toolbar UI buttons. 

== Setting up ==
=== Anchoring the streamer camera ===
The multi-cam switcher tool works by moving the attached camera anchor between the viewpoint positions. This is how it switches your stream camera's viewpoint, so you need to have your camera set into the camera anchor for the tool to work. Once your streaming camera has spawned, you can anchor it by aiming your laser at the green camera anchor and pressing the trigger. If successful the camera will move to the anchor's position.

=== Creating new viewpoints ===
You can add new viewpoints by using one of the four option buttons on the 'Create New' screen on the display. The '1st person view', '3rd person front view', and '3rd person back view' viewpoints will be positioned relative to a specified user. The 'Static view' viewpoints remain stationary relative to the world root unless deliberately moved. When any new viewpoint is created a corresponding preview screen is created on the display. 

When adding a new '1st person view', '3rd person front view', or '3rd person back view' you will be prompted to input a username. Start typing until "Matched: <code>target user</code>" (where <code>target user</code> is the user the viewpoint should track) appears in green text below the text entry box. If no match can be found, "No matching username" is displayed in red instead. The username matching process will attempt to match partial names and is case insensitive. If multiple users have usernames which share some letters you may need to type in the full name to ensure the correct match. Once the desired user is matched, click on the green 'Create' button. Press the red 'Cancel' button if you wish to return to the 'Create New' screen instead.

When a new static viewpoint is added, a blue viewpoint visual indicator spawns on the left side of the UI. This can be grabbed and moved into position but it ''does not'' act as a Resonite camera anchor in any way despite appearing similar. This means that you cannot laser click on the blue static viewpoint visuals to anchor the camera and they will not appear in the camera anchor list in the built-in Resonite streaming UI. The blue viewpoint visuals will be automatically hidden when you disable editing (see [[#Enable / disable editing | enabling and disabling editing]]).

=== Switching viewpoints ===
After placing your streamer camera in the tool camera anchor you can move it to any of the displayed viewpoints by clicking on the associated preview screen with your laser. The currently active viewpoint is indicated by a red border around the corresponding preview screen. Hovering over a preview screen whose viewpoint is not currently active highlights it with a white border. Viewpoints cannot be switched if there is no camera in the anchor!

=== Hiding the multi-cam switcher UI from the streamer camera ===
It's possible to prevent the streamer camera from rendering the multi-cam switcher UI by using the InteractiveCameraObjectExcludeTip. A copy of this is in the same public folder as the multi-cam switcher tool. Otherwise it can be obtained from Essential Tools > Misc. The most reliable way to make this work seems to be to equip the tool, grab the multi-cam switcher UI with the same hand, and then press primary fire. It may take a few attempts and you can verify whether it was successful by checking whether the switcher UI appears in the Resonite private streaming UI.

== Customizing viewpoints and previews ==
=== Perfecting your shot ===
The multi-cam switcher tool offers convenient options for fine tuning each viewpoint. To edit a viewpoint, click on the cogwheel 'settings' button in the header of the associated preview screen. This shows an overlay over the preview screen which allows tweaking the position, rotation, and FOV (field of view - works similarly to a zoom function). Since the settings options obscure the rendered preview, it is recommended to switch your camera to a viewpoint before making edits. You can use the render in the Resonite default streaming UI to aid in making adjustments. If you make any mistakes you can reset the position, rotation, and FOV using the buttons on the bottom right of the preview settings UI.

=== Organizing the preview screens ===
Preview screens can be renamed by clicking on the title for the relevant preview. The order of screens can be changed with the '<' and '>' buttons in the preview screen header. Alternatively, you can 'drag and drop': hover your laser over a preview and grab. You should see some blue text appear near your hand. Continue to hold grip and hover over the preview position you would like to move it to and then release grip. If done correctly, the grabbed preview screen will move to the target position. This only works when editing is enabled (see [[#Enable / disable editing | enabling and disabling editing]]).

=== Show / hide previews ===
You can hide the render view on preview screen by clicking on the eye icon in the header. This only hides the preview - it is still possible to swap the streamer camera to a viewpoint if the render is hidden. The main reason to do this is to remove the performance impact of rendering unnecessary preview screens.

=== Deleting a viewpoint ===
Viewpoints can be deleted by pressing the red 'X' button in the preview screen header. Static viewpoints can also be deleted by grabbing and deleting the blue viewpoint visual indicator. Deleting a static viewpoint by either method will automatically remove both the preview screen and the blue camera visual.

== Toolbar functions ==
=== Enable / disable editing ===
The "Disable editing / Enable editing" button swaps the multi-cam switcher between 2 states. The tool spawns with editing enabled by default. This allows the full range of viewpoint creation and editing functionality. The intended workflow is that, after lining up the viewpoints you'd like available, you would then disable editing.

Disabling editing has several effects:
* The "Create New" screen on the display is hidden.
* The blue position indicators for static viewpoints are hidden.
* All header buttons apart from the show / hide preview button are hidden.
* Editing of view points is disabled and any open viewpoint editing screens will be closed.
* The ability to move and rename viewpoints is disabled.
* The ability to save / load viewpoint data is disabled.

These changes are all intended to reduce the possibility of accidentally deleting, moving, or otherwise making changes to your setup during active filming.

=== Parenting to user ===
This button controls whether the multi-cam switcher tool stays positioned relative to the user who presses the button (i.e. it is parented to them). Once the tool is parented to a user it is still possible to re-position it by grabbing and moving it. Parenting the UI to the operator is helpful as it means it will automatically move with you as you navigate through the world.

=== Hiding the UI from others ===
This button controls whether the UI is visible to other users in the world. The tools spawns as visible to everyone by default. It is generally recommended that the UI be hidden from other users unless they absolutely need to be able to see it. This is because anyone who cannot see the UI does not suffer the (potentially significant) performance cost of rendering the preview screens.

=== Preview quality ===
This toolbar section allows you to determine the resolution of the preview screens. The options are very low, low, medium, and high - the tool spawns with low quality set by default. Changing the preview quality can affect the performance cost of rendering the preview screens with lower quality being lighter on performance. As such, it's recommended to use the lowest quality level which is sufficient for your needs. It may make sense to perform the initial setup at a higher quality before switching down when filming. These preview quality options are completely independent of the quality at which the streamer camera records.

=== Saving and loading viewpoints ===
It is possible to save all of the current viewpoints by pressing the "Save viewpoints" button while editing is enabled. When viewpoints are successfully saved, an audio clip will play and a glowing data cube will spawn below the toolbar. This can be saved and loaded from the Resonite inventory like any other object.

To load viewpoints, simply snap the datacube into the translucent snap box at the bottom right of the toolbar (only visible when editing is enabled) and press the "Load saved viewpoints" button which becomes enabled just to the left of the snap point. This will load all saved viewpoints into the world and creates preview screens for them. This retains any fine tuning performed using the cogwheel settings screen for each viewpoint. Customized viewpoint names are also retained. 1st person and 3rd person viewpoints will be loaded as long as the relevant user is present in the world. However loading saved viewpoints which were attached to users who are not present will fail silently. This failure does not prevent all other saved viewpoints being loaded.

== Resonite streaming UI settings ==
There are several settings in the Resonite streamer UI which particularly affect filming using the multi-cam switcher.

Settings on the main streamer UI (left hand side):

'''Hide camera''' - it can be useful to see the camera when setting up, but it's often best to hide the camera when filming to avoid distracting other users or breaking immersion.

'''Audio from camera viewpoint''' - this controls where the audio which the streaming camera picks up is recorded from. By default (with this option off) it is recorded from the viewpoint of the user who the camera belongs to. If this option is turned on, the audio is recorded from the position of the camera and the user who owns the camera also hears audio from that position. Which is the better to use depends on personal preference, however audio may not be well recorded from viewpoints which are far away from the streamer if this option is not turned on. For more information on controlling user audio levels when streaming see [https://www.youtube.com/watch?v=Kymxo4O4Zzk this tutorial from ProbablePrime].

In the camera anchor settings (location pin icon on the right hand side):

'''Interpolate between anchors''' - this controls whether the camera instantly switches between positions or smoothly moves between them. It's generally recommended to have this turned off (which allows instant switches) unless you specifically set up positions for a panning shot. Take care '''not''' to disable this while the camera is moving as that can lead to unexpected behavior.

== Known issues & troubleshooting ==
The multi-cam switcher tool is not intended to be saved into worlds and several problems will occur if you try do so. To re-use a specific camera setup, please see instructions for [[#Saving_and_loading_viewpoints |saving and loading viewpoints]]. If you would find the ability to save the multi-cam switcher into a world useful for your workflow, please message Zyzyl#1441 on Discord or Zyzyl within Resonite to discuss.

There is a known bug where the colliders for the UI can become displaced from the actual UI. This can result in part or all of the UI becoming unusable. This situation seems to arise most often when the UI is parented to a user and the UI resizes (e.g. from enabling / disabling editing). It is possible that this may be fixed by unparenting the UI from a user and/or inspecting the UI and disabling then re-enabling the BoxCollider components associated with the two UI canvases. If you find a reliable reproduction case or another way to fix or mitigate the issue, please message Zyzyl#1441 on Discord or Zyzyl within Resonite.

== License ==
The multi-cam switcher tool is licensed under the [https://creativecommons.org/licenses/by/4.0/ Attribution 4.0 International (CC BY 4.0) license]. A summary of Zyzyl's interpretation of this license is given below. Please see the text on the creative commons website for the full legal terms.

Under this license you are free to use the tool for any purpose as long as you provide attribution. This may be done in any reasonable way, however it must not suggest that Zyzyl endorses you or your use of the tool (unless explicitly arranged with Zyzyl). On a stream or film this might be an entry on the credits roll, a spoken accreditation, or a mention in a video description if posted online. A note saying something like "The Multi-cam Switcher tool created by Zyzyl was used in filming this production" would be perfectly sufficient.

You may also share, modify, and share modified versions of the tool for others to use. If you do so, you must give appropriate credit, provide a link to the license, and indicate whether changes were made to the tool. You may do so in any reasonable manner, but not in any way that suggests Zyzyl endorses you, any modifications you make, or your use of the tool (unless explicitly arranged with Zyzyl).

== Credits & acknowledgements ==
The multi-cam switcher tool was originally created by Zyzyl. 

Many thanks to Jason who commissioned and paid for the creation of this tool. Jason generously agreed to release this tool to the Resonite community for general use.

Thanks also to Jason, Carlos Austin, Hambone, and BassOnToast for providing valuable feedback during the design and testing phases of the tool's development.