Install DJF Companion Profile on a Mac

 

Installation Instructions (on a Mac)

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

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

Here’s a consolidated list of software downloads for the 6 Segments we will dive into below:

  1. Companion 2.4.2
  2. Blackmagic Switcher Software 9
  3. Stream Deck 6.1.0
  4. VLC 3.0.18
  5. VICREO 5.0.1
  6. H2R Graphics 2.14

 

** UPDATED MARCH 21, 2023 **

1. COMPANION (2.4.2)

Download Companion:

    • The DJF Companion Profiles require running Companion 2.4.2 or later to support the most up-to-date features and modules.

 

Open Companion

    • 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).
    • Set the Port to 8000
    • Launch GUI in a web browser.

Install the DJF Companion Profile

    • Navigate tabs to Buttons > Import/Export.
    • If you already have your own custom Companion setup, click “Export” to save a backup of your profile first!

 

  • Replace Current Configuration (recommended)
    • Select Import. Choose the DJF Companion Profile file (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!

  • Individual page import (not recommended)
    • Note that the DJF Companion Profile pages are heavily inter-connected, hence it is recommended to “replace current configuration”. While you can copy and paste buttons quite easily after the initial “replace current configuration”, importing individual pages will require manually updating the Page-jump actions, plus you must be careful to target the correct instance label of a module when importing.
    • If you still wish to import individual pages, note that there are also several “backend” service pages need to be imported to very specific pages to maintain integrity:

 

        • Backend service pages for v3.1:
          • Extreme………..Pages 55, 56, 57, 58
          • Pro………………Pages 83, 84
          • PTZ……………..Pages 86, 87
        • Backend service pages for v2.5:
          • Pro………………Pages 22, 23

 

    • Once those backend pages have been imported to their specific page numbers, you can import individual pages to any other Companion page.
      • If dealing with a dual profile that contains both ATEM Extreme and ATEM Pro, make sure you target the correct instance (i.e. “ext-atem” and “pro-atem” are completely different implementations of the same ATEM Module).
      • Note that any Menu or Page-jump buttons will need to have their action “Set surface with s/n to…” updated manually.
    • For example, if you wanted to import the Extreme’s VLC page:
      • Import DJF Companion Profile Pages 55, 56, 57, 58 to their respective Pages, 55, 56, 57, 58 in your Companion profile.
      • Import the Extreme VLC (Page 30) to whatever blank page you have available in your configuration.
      • Update the Page-jump button actions (ie VLC Page’s Button #1) to target your configuration layout.

 

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, and for your ATEM Mini Extreme/ISO if running dual systems.
      • **Note: it is recommended to keep the connection labels the way they are (i.e. “ext-atem” and “pro-atem” etc.) Changing the connection label names will update most – but not all – variable names, and will leave some button text (i.e. the BLK button) unable to find the new name.
      • **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’s HOME PAGE
          • DJF PROFILE v3.1
            • 32-button Extreme…………………..PAGE 1
            • 32-button Pro…………………………PAGE 66
            • PTZ……………………………………..PAGE 88
            • Vertical Pro…………………………….PAGE 96
            • Vertical Extreme……………………..PAGE 98
          • DJF PROFILE v2.5
            • 32-button Pro…………………………PAGE 1
            • 15-button Pro…………………………PAGE 31
            • Vertical Pro…………………………….PAGE 71

Make Changes to Companion’s Settings

    • “Remove the Topbar on all buttons”:
      • Go to Companion > Settings > Navigation Buttons > “Remove the topbar on each button” > SELECT “Enabled”.
      • **Note that the PNGs and text layout on the DJF Companion Profile buttons have been designed for the full 72 x 72px.m The buttons will look squished unless you remove the topbar.
    • “Enable OSC”:
      • Go to Companion > Settings > OSC > SELECT “Enabled”.
      • Set the OSC Listen Port to “12321”.

Troubleshooting:

    • If your Stream Deck is plugged in but the Companion buttons are not showing up, go to Companion’s “Surfaces” tab, and click “Rescan USB”
    • If you’d like to run this without a the actual Stream Deck hardware (i.e. use it on a computer or tablet instead), click on “Emulator” in the top left corner. Locally, the address will be http://127.0.0.1:8000/emulator
    • If there’s a conflict while running Elgato Stream Deck’s native software simultaneously with Companion, quit both applications.
      • Then try opening Elgato’s Stream Deck software first;
      • then starting the Companion server secondly.
        • (Make sure the Companion Plugin within the native Elgato Stream Deck app has been installed – see “Stream Deck” installation instructions below).

 

 


2. BLACKMAGIC ATEM SWITCHERS (9.0)

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 suffice).

 

Set a Static IP Address

    • Connect your computer to the ATEM via USB.
    • When connected via USB (as opposed to ethernet), you will be able to change the IP address of the ATEM within the “ATEM Setup” application.
    • Choosing a static IP address appropriate to your router’s range is recommended.
      • Your settings will likely differ, but for example:
        • Router            192.168.1.1
        • Computer       192.168.1.2
        • ATEM             192.168.1.3
    • Within Companion, make sure the ATEM Module’s Target IP has been updated with the new IP Address that was set for the ATEM hardware (as previously mentioned in the Companion setup).

 

Install DJF Macros in ATEM Software Control

    • Open the “ATEM Software Control” application.
    • Go to File > Restore
    • Choose the “DJF-ATEM-MACROS.xml” that came with your DJF Companion Profile and restore Macros.
      • Basic requirement is to install the Macros only.
        • Deselect all options, then select “Macros” only
      • Selecting all options will restore the Media Pool and other presets – this is not essential, but included as a courtesy to help with understanding presets, Super Source layouts, Chroma Keying and so on.
    • 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. The ATEM can now operate without the need for Blackmagic’s ATEM Software Control application.

 

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 (6.1.0)

Elgato Stream Deck software is available here

Turn On Elgato Plugin within Companion

 

    • Within Companion, navigate to Settings > Devices and select the checkbox “Use Elgato Plugin for StreamDeck access (Requires Companion restart)”

 

    • This will enable Companion to operate via the native Elgato application plugin.

 

Add the Companion Plugin to your native Elgato Stream Deck software

    • Open the Stream Deck Store
    • Search for “Companion”.
    • Install the Companion 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

    • FULL RESTORE
    • 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 the file ending in “.streamDeckProfilesBackup” to restore a full backup
    • INDIVIDUAL PAGE RESTORE
    • Alternatively, if you don’t want to overwrite your existing setup, you can import individual pages.
    • 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.
    • Select “Import…”
    • Find the individual profile ending with “.streamDeckProfile”
      • Note that when importing individual Stream Deck Profiles, the “profile jump” buttons will need to be manually re-linked to the appropriate profile (by contrast, these links will remain intact if “restoring a full backup” instead).

 

Creating Companion buttons on 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
    • “Dynamic” vs 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, however:
    • “Static” buttons:
      • If you want a dedicated Companion button that does not change when the Companion surface does, choose the specific Page and Button number (as found in your Companion software)

 

Simultaneously running Elgato Stream Deck software and Companion’s server

    • You can now mix native Stream Deck buttons into your Elgato Stream Deck’s Companion profile page
    • Button #9 in the DJF Companion Profile (the 1st button on the 2nd row of every page) has been reserved across all Companion pages. When running Companion solo, this button will jump between profiles within Companion.
    • However, if you are also running native Stream Deck software, Button #9 will now switch between your Stream Deck profiles (yes- all these names get confusing!!). This is to allow you to create a dedicated Stream Deck button to switch to other native Elgato Stream Deck profiles you may have.
      • If using this option, you’ll have to use Button #22 on the Menu page to switch between different Companion Profiles (i.e. to jump between controlling the ATEM Pro vs Extreme).
    • It’s recommended to leave all other buttons on the profile as the default “Dynamic” state, so that Companion will dynamically update them

 

Troubleshooting

    • Note that as of Companion version 2.2.0+, you cannot separate multiple Stream Deck Surfaces when using Elgato’s software. This is because it’s now mandatory under Companion > Settings > Devices to select the checkbox “Use Elgato Plugin for StreamDeck access (Requires Companion restart)” to operate Companion via the native Elgato application. Therefore, all Stream Deck hardware (32-button, 15-button, and Mobile App) is routed through the “plugin” surface in Companion, and a change on one surface will sync changes on the other surfaces.
    • In this instance, if you want to use multiple Stream Decks as independent surfaces, it is best to quit Elgato’s native software entirely, and only run the Stream Decks via the Companion software.

 

 


4. VICREO LISTENER (5.0.1)

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
    • Set the password to “vicreopassword” in VICREO app, and also within the Companion VICREO Module
    • That’s it! (phew – that one was easy, right?)

 


5. VLC (3.0.18)

Download VLC

Connect your Computer to your ATEM via HDMI

    • **If you have a Macbook, you may need a USB-C-to-HDMI adapter
    • For the ATEM Mini Pro profiles, use inputs HDMI 3 or HDMI 4
      • **If you are also running H2R v1, it is best to run VLC into HDMI 3, and H2R v1 into HDMI 4
    • For the ATEM Mini Extreme profiles, use inputs HDMI 7 or HDMI 8
      • **If you are also running H2R v1, it is best to run VLC into HDMI 7, and H2R v1 into HDMI 8
    • 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 > Playlist
      • Select “Play and Pause”
    • Preferences > Subtitles/OSD tab > Onscreen display
      • Disable “Enable OSD”

 

 


6. H2R Graphics (2.14)

Download H2R Graphics

In H2R Graphics version 2, install the “DJF 3.1 H2R2.json” project settings

    • Open H2R Graphics V2
    • Under the Settings > Import/Export, select Import
      • Select the H2R Graphics template that came with the DJF Companion Profile (“DJF 3.1 H2R2.json“)
      • This is essential to install, as the shortcodes included in this H2R .json profile link specifically to the Companion buttons
      • After this is installed, you may modify the text fields and theme look.

Set the background color to Green

 

In Companion, set the H2R Graphics module to V2

    • Note that Companion’s H2R module now selects version 2 of the H2R application by default.
      • If running V2 of H2R, ensure the checkbox that says “Vers.2 Running H2R Graphics v2? (Default: Enabled)” is checked.
    • Set Target IP to 127.0.0.1 to control the H2R Graphics on your local computer
    • Set Target Port to 4001
    • Set Project ID to ABCD
    • Click “Save”

Connect your Computer’s HDMI output to the ATEM

    • Connect the HDMI cable from your computer to the ATEM input.
      • **If you have a Macbook, you may need a USB-C-to-HDMI adapter.
      • For the ATEM Mini Pro profiles, use input HDMI 4
        • **If you are also running VLC, it is best to run VLC into HDMI 3, and H2R v1 into HDMI 4
      • For the ATEM Mini Extreme profiles, use input HDMI 8
        • **If you are also running VLC, it is best to run VLC into HDMI 7, and H2R v1 into HDMI 8
    • Open Output 1 within H2R, and make the green window full screen on that HDMI output source.
    • Press Button #11 on your Stream Deck’s H2R page to automatically key out the Green background
    • Long-Press Button #10 on your Stream Deck’s H2R page to push the Upstream Key to Air
    • Now you effectively have an “invisible” layer over your program that is always active, and any time you trigger H2R graphics, they will appear on screen.

Alternative Output via Network Computer or Raspberry Pi 4

    • H2R version 2 is network-based. Therefore, if you have another computer running within your local network, you can open a web browser and direct the URL to H2R’s Output. Depending on your router’s address, it will look something like this (bold parts for emphasis):
      • http://192.168.8.107:4001/output/ABCD/
        • In this example, “107” refers to the computer that is running the H2R application (likely your local machine), and “ABCD” refers to the specific H2R Project that is open.
    • The advantage of this set up is that your computer/laptop that is running and controlling H2R does not need to be connected via an HDMI cable to your switcher. Instead, you could operate graphics over the local WiFi.