Tuesday, January 26, 2021

ATEM Animation And Triggering from ProPresenter 7

We have a Pastor who is partial to graphical illustrations. Especially in our current climate of COVID, we've struggled with the best way to display them for our online viewers. Going to fullscreen graphics for long enough to absorb them can detach you from the speaker. Picture-in-picture can be awkward (inexperienced camera operators mess up the timing or placement of the transition) and tiny (40% of our often-mobile audience is watching on < 720p). What we finally settled on was general use of split screen graphics, so viewers can see the speaker and a sizeable image simultaneously. This looks great, but can still be awkward to transition to traditionally, requiring precise coordination between your technical director, graphics operator, and camera operator.

I started to explore options to solve this problem, and discovered that people have been able to do animated transitions of the SuperSource on Blackmagic Design ATEM switchers using nothing but some clever scripting. In particular, I found this excellent article by Ian Morrish where he does this, and also provides a flexible Windows Powershell library for doing this and more with an ATEM. Taking his groundwork and implementing a sleek solution to automate fly-ins of our side graphics was fairly easy. 


Concept

The method we settled on always displays the camera via the ATEM's SuperSource Box 1 and uses a script to automate moving the camera to the left (and then back), while we rely on ProPresenter 7 transitions to move the images (which are being overlayed on the ATEM via a downstream key) in and out. Midi cues translated into a command to run the scripts keep both of these actions in sync. 

Pre-Requisites

  • A general comfort with scripting: This project uses Microsoft Powershell scripts. I don't have the time to provide you scripts that are 100% fool-proof and robustly ready to use in your exact situation, so you will need to tinker at least a little bit under the hood by adjusting some things. Powershell is super easy, though, so comfort with any basic scripting should be enough to get started; I actually hadn't done much with Powershell before starting this.
  • A Windows 10 Computer with ProPresenter 7: Sorry, Mac users; because this project uses powershell as its script language of choice, and relies on Ian Morrish's ATEM Powershell library, it is very specific to running on a Windows computer. The theory here could easily be adapted to other scripting environments on other systems, but you'd be starting from scratch and on your own.
  • A Blackmagic Design ATEM Switcher with SuperSource: This means a ATEM 2 M/E or higher. It does not include the ATEM Mini or Mini Pro, or the ATEM 1 M/E. No way around this; SuperSource is where the magic happens. NOTE: My scripts are setup such that you are using your 1 M/E for output (it will always use the SuperSource as it's source) and doing actual camera switching on 2 M/E. I hope to expand this article later with a few ideas of other ways to do this that I explored, but right now if you want a different setup you will need to modify things.
  • ATEM Software installed on the computer: Like most third party libraries that access the ATEM, you have to have the actual blackmagic design ATEM software installed on your computer. Make sure you've launched it once to see it can connect to your switcher. 
  • Propresenter 7 output is sent to your ATEM via some keyed method: The explanations below rely on the left half of your image slides being transparent as seen by the ATEM, so however you connect from ProPresenter 7 to the ATEM needs to support transparency. Key/Fill is preferred, Chroma or Luma key would probably work too. 
  • Bome Midi Translator Pro - If you do ANY work with MIDI triggers you should already consider having this in your toolkit. It allows you to take simple MIDI signals (such as those done by ProPresenter) and translate them into any number of different, complex tasks. This is how I glue ProPresenter 7 midi triggers to Powershell scripts. The steps below assume you've already set up a connection so that ProPresenter MIDI output is going to a Bome Translator virtual input.

Getting Started

  1. While not strictly necessary, having a good development environment for PowerShell will help you a lot with adjusting things and testing. Ian Morrish has good instructions for setting up the 32bit PowerShell ISE here. Configuring the ISE lets you open the scripts (in step 3) and easily run them with debug output independent of any of the other pieces, and validate they are working ok. 
  2. Download Ian Morrish's ATEM powershell library (switcherlib.dll) from this site and place it some place you can remember (His suggested location of C:\Users\[UserName]\Documents\WindowsPowerShell\SwitcherLib.dll is fine). NOTE: as briefly alluded to on that page, current versions of Windows 10 have a security feature where .dll files downloaded from the internet are automatically blocked from use. After placing your file, you need to Right Click->Properties and you will see either a checkbox or button (depending on your exact version of Windows 10) to allow. Make sure you do this or later steps will inexplicably fail with ambiguous error messages. 
  3. Download my adaptation of Ian Morrish's automation example script by using this Google Drive link. Place them someplace you can remember. NOTE: Powershell scripts like those contained in this download have the capability of executing arbitrary code on your computer. You should ONLY run scripts you trust and know the origin of, or better yet review the code yourself to make sure they're doing what you expect and nothing extra or malicious. 
  4. After you've placed the scripts, open both of them in the editor of your choice. At the very top of each, there are two variables. ATEMipAddress needs to be set to the IP of your ATEM, and LibPath needs to be set to the location of Ian Morish's ATEM powershell library you downloaded in step 2. 
  5. Generate a 10x10 transparent PNG (OR, ALTERNATIVELY, WHATEVER CHROMA/LUMA YOUR ATEM SEES AS TRANSPARENT) file using this website. We'll use this when building our ProPresenter slides. For the transition effects we will be using to work properly, our "empty"/clear slide must have a foreground image.

Configure Your ATEM 

  1. Set your ATEM 1 M/E source to SuperSource. 
  2. In the SuperSource configuration, set the Box 1 source to 2 M/E Program. Set the scale of Box 1 to 1.0, and the Crop and Position values to zero. 
  3. Set your 2 M/E Program to a camera. You will do all camera switching on your 2 M/E. 
  4. Make sure your downstream key is turned on so you can see output from ProPresenter overlaid
  5. Monitor your 1 M/E program output.

Add Actions to Bome Midi Translator Pro

In Bome, Create two new triggers, assigned to whatever input notes you want (we'll use those notes to add triggers to our slides in Pro7). One trigger will be for our layout1 file (which moves the camera to the left), and the other will be for our layout0 file (which moves our camera back to the right). 

Set their action to execute command C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe with the arguments set to -NonInteractive -WindowStyle hidden -File "C:\FullPath\To\layout1.ps1" and -NonInteractive -WindowStyle hidden -File "C:\FullPath\To\layout1.ps1" respectively. You should end up with triggers like this:




Build Your ProPresenter Slides 

We will be using two slides, a build in trigger (with our image as foreground), and a clear trigger (with our transparent image we generated above as foreground) . Each has a MIDI cue (to change the camera) and a transition effect (to fly the image in/out in propresenter):




When I tested this, our image was a full slide size with the left half transparent. In theory, a half-slide image simply composed on the right side should be the same, but ProPresenter seems to have some weird differences with how transitions operate with content differences, so if in doubt do what we did and build a full slide image.

The MIDI trigger for the build slide should be whatever you chose for the layout1 trigger in Bome, and the remove slide shoule be what you picked for the layout0 trigger. 

For the build slide, I used a Move In transition set to From Right with a time of 2.7. You may have to test and adjust this number; your goal is to match the camera transition and that can vary depending on a bunch of factors (how quickly your computer runs the script, network connection to the ATEM, etc). 


For the clear slide, I used a Push transition set to From Left with a time of 5.2. Again, adjust this number to preference and smooth operation.




Test

At this point, you should be ready to go: The build in slide should cause the fly in effect, and the clear slide should fly out. You may need to adjust the ProPresenter transition numbers mentioned above for smooth operation, or advanced users might want to tweak the numbers in the Supersource Animation script to change how fast the camera moves. 

If nothing is happening, open the script(s) in the Powershell ISE (Setup in #1 of Getting Started, above) and run them there. The console output should give you an idea of where things are getting hung up. 

If you're getting weird transitions or behavior, double check that your ATEM is set up exactly as described in the ATEM configuration section above.

Conclusion

Hopefully this helps or inspires you! If you want to do even more with a similar system, check out Ian Morrish's site and library for details on what you can do; his library offers full remote control of the ATEM in almost any way you can imagine. 

If you run into problems with this, feel free to reach out. I'd also love any corrections on any of this content or the scripts I've provided.