Install Companion on a Mac

Companion also runs on Windows and Pi. This article will focus on a Mac installation.

Running Companion is one of those “easy when you know how” things. This article will show you how. Easy!

 

1. COMPANION (2.2.0 – beta build)

  • Download Companion:

    • Companion 2.2.0. While 2.2.0 is still pre-release, it’s generally pretty stable and you can grab the latest build available. That said, make sure you thoroughly test your setup before implementing in a live production. The current version the DJF profile has been tested with is 2.2.0 build 3399.
  • Open Companion

    • If running for the first time, right click the Companion app and select “Open”.
    • You’ll receive a notification that the developer is unknown. Cancel this.
    • Right-click “Open” a second time, and now you can open the app.
    • Companion’s Web Server icon will be in the top-right menu bar. Click it to open the tray.
    • Check the server is running locally on 127.0.0.1 (easiest setup).
  • Install the DJF Companion Profile

    • Launch GUI in a web browser. Navigate tabs to Buttons > Import/Export.
    • If you already have your own Companion setup, click “Export” to save a backup of your profile.
    • Select Import. Choose the DJF Companion Profile (ends with “.companionconfig”)
    • Select “Replace current configuration”. Note that this will wipe all existing Companion pages, so make sure you’ve backed up any essential work first.
  • Set ATEM Module’s Target IP Address

    • Under the Connections tab, click “Edit” for the “atem Blackmagic Design” module. Update the Target IP to the IP address for your ATEM Mini/Pro/ISO.
      • **Note: you can find the ATEM IP using BlackMagic’s “ATEM Setup Software”. Setting a static IP address is recommended.
    • All other modules (VLC, H2R, VICREO, OSC) are pre-set to local 127.0.0.1 and don’t need to be changed.
  • Set the Home Page

    • Under the Surfaces tab, click the green “Settings” button for the “Elgato Streamdeck Plugin” (or the actual Stream Deck serial number, if running Companion solo).
    • Slide the Page number for your specific profile:
      • 32-button Profile’s Home Page uses PAGE 1
      • 15-button Profile’s Home Page uses PAGE 31
      • Vertical Profile for Stream Deck Mobile app uses PAGE 71
  • Troubleshooting:

    • If the profile is not showing up on your Stream Deck, go to Companion’s “Surfaces” tab, and click “Rescan USB”
    • If you’d like to run this without an actual Stream Deck (on a computer or tablet) , click on “Emulator” in the top left corner.
    • If there’s a conflict while running Elgato Stream Deck’s native software simultaneously, quit both applications, then try opening Elgato’s Stream Deck software first, then starting the Companion server secondly. Make sure you have installed the Companion Plugin within the native Elgato Stream Deck app.
    • **Note: The DJF Companion Profiles require running Companion 2.2.0 to support the most up-to-date features and modules. Some functions will be missing if you try to operate the profile using Companion 2.1.3.

 

2. BLACKMAGIC ATEM SWITCHERS (8.6.1)

  • Install ATEM Switcher software

    • Download and install the most recent ATEM Switcher software from Blackmagic Design’s Support page.
    • Each “update” is a full program installation, so the most recent version will do.
  • Connect your computer to the ATEM via USB

    • When connected via USB, you can set the IP address of the ATEM within the “ATEM Setup” app.
    • Choosing a static IP address appropriate to your router’s range is recommended.
    • Also update this Target IP within the ATEM Companion module, as previously mentioned in the Companion setup.
  • Open ATEM Software Control

    • Go to File > Restore
    • Choose the “DJF-ATEM-MACROS.xml” that came with your DJF Companion Profile and restore Macros.
    • Go to File > Save Startup State to commit the macros to the ATEM hardware.
    • Once you’ve “Saved the Startup State”, the macros will still be present each time you power on the ATEM.
  • Troubleshooting

    • Companion speaks directly to the ATEM via the Ethernet Network and does not require the ATEM Software Control to be running in order to operate.
    • Note that Companion only speaks to the ATEM via Ethernet, not the USB port. While you can install the ATEM Macros via a USB connection, you will need an Ethernet connection to control the ATEM via Companion.

 

3. STREAM DECK (5.0)

  • Elgato Stream Deck software available here
  • Add the Companion Plugin to your native Elgato Stream Deck software

    • At the bottom right of the window, click “More Actions…”
    • Search for “Companion”.
    • Install the plugin.
  • Back up your own Stream Deck Profiles

    • If you are already using Elgato’s Stream Deck software, make sure you back up your work first!
    • Go to the Stream Deck Icon in the top-right menu bar
    • Select “Preferences” (Command + ,), then “Profiles”.
    • To the right of the “+/-” symbols, select the dropdown menu.
    • Go Backup All > Create Backup…
    • Save the file to a safe folder.
  • Install the bonus Stream Deck Profiles

    • **Note that these profiles are bonus items and may be incomplete. They are a 32-button layout, so some buttons will be missing if you use a 15-button Stream Deck. Further, there’s been some strange instances of links between profiles not reconnecting properly, so it’s recommended to copy useful buttons into your own configuration, rather than importing the full profile backup.
    • Go to the Stream Deck Icon in the top-right menu bar
    • Select “Preferences” (Command + ,), then “Profiles”.
    • To the right of the “+/-” symbols, select the dropdown menu.
    • Go Backup All > Restore From Backup…
    • Select to restore:
      • an individual profile (“.streamDeckProfile”)
      • or a full profile backup (“.streamDeckProfilesBackup”)
    • Caution! While importing individual profiles will add to your existing setup, restoring a full backup will wipe your current configuration entirely. Ensure you have backed up your profile first.
  • Add Companion buttons to your Stream Deck Profile

    • You can also build your own Elgato Stream Deck profile pages in conjunction with Companion.
    • From the right sidebar, again Search “Companion”
    • Drag the “Companion button” to each of the Stream Deck’s keys
  • Choose “Dynamic” or Static pages/buttons

    • By default, dragging a Companion button on to Stream Deck will create a Dynamic Button
    • Not modifying the default Dynamic button is recommended, as it will update the function as you navigate through the Companion Profile
  • Static buttons

    • If you want a dedicated Companion button, choose the corresponding Page and Button number (as found in your Companion software)
  • Simultaneously running Elgato Stream Deck software and Companion’s server

    • You can now add regular Stream Deck buttons into your Elgato Stream Deck’s Companion profile page
    • Button 9 in the DJF profile (the 1st button on the 2nd row of every page) has been reserved across all Companion pages. This is to allow you to create a dedicated Stream Deck button to switch to other native Elgato Stream Deck profiles you may have.
    • It’s recommended to leave all other buttons on the profile as the default “Dynamic” state, so that Companion will dynamically update them
  • Troubleshooting

    • If there’s a conflict while running Companion and Elgato Stream Deck’s native software simultaneously:
      • Quit both applications.
      • Then try opening Elgato’s Stream Deck software first, then starting the Companion server secondly.
      • Make sure you have installed the Companion Plugin within the native Elgato Stream Deck app.
    • If you are trying to run a 15-button or 32-button Stream Deck XL surface simultaneously but independently to the Vertical Stream Deck Mobile app surface on your phone (ie so your two surfaces don’t change pages in sync):
      • Quit both Companion and Stream Deck software
      • Open Companion first
        • Under the Surfaces tab, click “Rescan USB”
        • The “Elgato Streamdeck XL device” will appear with a specific serial number under the ID field.
      • Next open Elgato’s native Stream Deck software
        • Open the Stream Deck Mobile app on your phone
        • Ensure your phone’s WiFi is connected to the same network as the computer
        • Enjoy!
      • Note that because the 15-button or 32-button Stream Deck is now running natively to Companion, the native Elgato Stream Deck profiles will not be available on the hardware (instead you’ll see the DJF logo – hey there! 🙂

 

4. VICREO LISTENER (2.1.0)

  • Download VICREO
  • Install and Open

    • Leave Default Port Number 10001
    • Close the window and the app will still run in the top-right menu bar

 

5. VLC (3.0.13)

  • Download VLC
  • Connect your Computer to HDMI 4

    • **If you have a Macbook, you may need a USB-C-to-HDMI adapter.
    • Connect the HDMI cable from your computer to the ATEM input HDMI 4.
    • Under Mac’s System Preferences > Displays > Arrangement… Uncheck “Mirror Displays”.
    • Under VLC > Video > Full Screen Video Device… Select the appropriate display that is feeding into ATEM’s HDMI 4.
  • Configure VLC to connect to Companion

    • Preferences > Show All > Interface tab > HTTP Web Interface
      • Enable HTTP web interface
        • Set password to “vlcpassword” (this is the password within the DJF Companion Profile VLC module. If you use a different password in VLC, make sure to update the password within the VLC module in Companion).
    • Preferences > Show All > Interface tab > Show All > interface > main interface
      • Select “Web”
      • Select “Telnet”
    • Preferences > Show All > Interface tab > Show All > interface > main interface > macosx
      • Deselect “use the native fullscreen mode”
      • Deselect “Show fullscreen controller”
    • Preferences > Show All > Interface tab > Show All > interface > main interface > macosx
      • Select “Play and Pause”
    • Preferences > Subtitles/OSD tab > Onscreen display
      • Disable “Enable OSD”

 

6. H2R Graphics (0.4)

  • Download H2R Graphics
  • Create a Chroma Shortcut Key

    • Open Mac’s System Preferences > Keyboard > Shortcuts > App Shortcuts
      • Press the “+” button
      • Application: H2R Graphics
      • Menu Title: Chroma
      • Keyboard Shortcut: “OPTION+1”
  • Install DJF Bonus Preset

    • Note: this bonus DJF Profile for H2R is just to help you understand some of the Custom CSS available within H2R.
    • Open H2R Graphics
    • Under the Settings tab on the far right > Themes > Load
      • Select the bonus H2R Graphics template that came with the DJF Companion Profile:
      • “DJF_H2R_Graphics.json”