Controlling Planning Center LIVE with a Stream Deck

In my last post, I mentioned a great tool, Companion, that integrates with the Elgato Stream Deck. I’ve had the opportunity to write a few modules for it to extend its control capabilities, like controlling a CueServer, or my own software, ProTally.

If you work in tech for a church, chances are that you use or have at least heard of Planning Center Online to manage your worship services and people. PCO has a feature for their Services product called Services LIVE that allows you to designate where you are at in a service flow while a service is ongoing, which updates anyone who may be watching. It also records the times so you can look back later and see things like “Did that song we said would take 5 minutes actually take more like 6 minutes and 30 seconds?” It’s a very useful tool.

The interface to advance a LIVE plan, however, has not been the best for our volunteers. Even within the PCO app, the buttons to advance a plan to the next item are rather tiny, and some of my team have trouble knowing whether or not they hit the button.

IMG_9032
This is the standard PCO Live interface. The small double arrows at the bottom left and right of the screen are the controls. Our volunteers have a hard time pressing these.

One thing that makes Planning Center Online great is that they love developers, and they’ve made a very extensive Application Programming Interface (API) available for anyone to use. This means you can get access to your service and plan data without having to actually click and browse the website.

I delved into that API this past week and used it to create a new module for Companion. One of the caveats of using the API is that in order to advance a live plan, you have to know both the service type ID and the plan ID. This requires traversing the API data some and making multiple requests. If you’re a programmer, this makes sense. If you’re just an end-user, it may not be as straightforward. So, I set out to make something easy enough for anyone to use.

Here is a walkthrough video on how the module works:

What it actually does:

  1. When you first load the module and supply it with the authentication tokens, it requests all of the available service types and stores that internally.
    https://api.planningcenteronline.com/services/v2/service_types
  2. Then it asks for the next 7 upcoming plans for each service type based on the list that was just retrieved. This is then used to build the drop down list so you can choose your plan.
    https://api.planningcenteronline.com/services/v2/service_types/${serviceTypeId}/plans?filter=future&per_page=7
  3. When you send a “Previous” or “Next” command, it first asks for the LIVE information for that selected plan.
    https://api.planningcenteronline.com/services/v2/service_types/${serviceTypeId}/plans/${planId}/live
  4. It checks for who the current controller of the plan is, and compares that to an internal variable in Companion that represents the owner of the authentication token.
  5. If the current controller is null, a command is sent to toggle control to the token owner, and the returning value of the current controller is stored in that internal variable so we know who “we” are for next time.
    https://api.planningcenteronline.com/services/v2/service_types/${serviceTypeId}/plans/${planId}/live/toggle_control
  6. If the current controller is not null, a toggle command is sent to release control of the plan to no one, and then a toggle command is immediately sent again so that control is toggled to us. The reason for this is that if our authentication key is not the current controller, the API will return an error when we try to advance the plan.
  7. Now that we know we are in control, the current controller value returned by the API is stored as an internal variable, and then the next or previous command is sent to advance the plan.
    https://api.planningcenteronline.com/services/v2/service_types/${serviceTypeId}/plans/${planId}/live/go_to_next_item

Because Node.js is an asychronous programming language, all of this is done through Promises, which is similar in concept to a callback function, however it allows for cleaner and easier to read code.

So, stay tuned for this module to become available in the next stable release of Companion, and if you’re willing to try it out in development mode, it’s available now!

IMG_9035
The PCO Live module in action!

Support for blink(1) now available in ProTally!

I wrote ProTally last year so our volunteers running ProPresenter could know when their source was on screen or about to be on screen. It has been very helpful in minimizing our mistakes by making distracting graphic changes while on-air. It supports tally data from our Ross Carbonite switchers but I’ve also written support for the TSL 3.1 protocol, Blackmagic ATEM switchers, OBS Studio scenes, and most recently, Bitfocus Companion.

I recently picked up a blink(1) to test out for another project I’m working on. If you’ve not heard of it, the blink(1) is a small $30 USB device with LEDs built in, designed to give you a quick-glance notice of anything on your computer. The creators have made libraries in several popular programming languages, like Node.js (the language ProTally is written in), to interact with it.

 

I decided to get my feet wet and learn about the device’s capabilities by integrating it with ProTally. Since ProTally can read and work with tally data from so many different types of sources, that means it’s already primed to take that tally data and act on it in different ways, not just on-screen.

So, I am pleased to announce, that ProTally now supports up to 4 blink(1) devices that can mirror the color the user chooses for an on-screen tally box. The user can choose between showing the tally color on a box on their monitor (like normal), a connected blink(1) device, or both. If you are using multiple tally boxes but don’t own an equal number of blink(1) devices, you can also choose to share the blink(1) across multiple tally boxes, and the higher box will get priority.

 

The latest release of ProTally supporting blink(1) devices as tally lights is available on Github now, so go check it out!

Using a Stream Deck as a Production Controller, Revisited

One of my first posts on this blog detailed how I wrote software in Node.js to interface with an Elgato Stream Deck to control some of our production equipment, interfacing with the video switchers, router, Ross Dashboard, etc. It’s time to revisit that.

We’ve been using my controller now every week in our control rooms and tech booths for about a year. My team loves it. It integrates into our centralized production workflow, where each deck sends commands to a central Dashboard panel, which runs the command, and then sends out updates to all the connected stream decks.

However, I haven’t had much time to make it a better product for other people. I wrote support for the Stream Deck Mini when that was released, but that’s about it. I haven’t had time or cause to do much else with it. So, for that reason, I wanted to share with you a piece of software that is under constant, active development: Bitfocus Companion.

Screen Shot 2019-02-15 at 10.43.46 AM

 

Companion is written in Node.js and packaged in Electron just like my product, so it can run on Mac, Windows, or Linux. But it can do so much more than my controller! One of the best features is that it has a web-based management interface, so you can add actions to buttons easily and on-the-fly. It supports a ton of production equipment and chances are good that your gear is already on the supported list, or, perhaps someone can create a module for it.

I was asked to join the development team recently for Companion, so I’ve started making some modules for Companion to integrate with software and gear that we have. I’ve created a module for Interactive Technologies’ CueServer, which we have in a couple of our venues here.

Screen Shot 2019-02-15 at 10.54.05 AM
Here are some actions you can perform on a CueServer now with the module I created for Companion.
Screen Shot 2019-02-15 at 10.53.53 AM
An example of a key down action for triggering a CueServer macro in Companion.

If you use ProTally, my on-screen tally box notification software, and want to integrate with Companion, I made a module for that too! Make sure to go download the latest ProTally release which supports this feature! With Companion, in addition to Preview and Program windows, you can also send a Beacon, which flashes at a custom rate and color. Check this video out for a demo:

Both of these modules are available in the bleeding edge builds of Companion and will be included in the next stable release soon.

So, if you’re looking for a great production controller that integrates with the Stream Deck, go check out Companion! It’s only going to get better from here!