How to Toggle ProPresenter Audience Screens with Companion: A Detailed Guide

Securely Integrating ProPresenter with Companion: A Comprehensive Guide

This guide provides a secure method to integrate ProPresenter with Companion using native scripting languages on both macOS and Windows.

Prerequisites

  1. ProPresenter (All versions) installed on your computer
  2. Companion (version 2+ or 3+) installed on the same computer or on your network
  3. GRANT PERMISSIONS WHERE NEEDED

Security Considerations

  • These scripts use native, built-in scripting languages (AppleScript for macOS, PowerShell for Windows) to enhance security.
  • No third-party software installation is required.
  • Scripts only interact with ProPresenter and do not access sensitive system resources.
  • Always download scripts from trusted sources (like official ProPresenter channels).

Step 1: Prepare the Script

For macOS:

  1. Open “Script Editor” (found in Applications > Utilities)
  2. Copy and paste the macOS AppleScript provided below
  3. Save the script as “ToggleAudienceScreens.scpt” in a secure, easy-to-find location
				
					-- ProPresenter Audience Screen Toggle Script (macOS)
-- Uses native AppleScript for improved security
-- Uses keyboard shortcut instead of menu navigation

on run
	tell application "ProPresenter" to activate
	delay 0.5 -- Give ProPresenter time to come to the foreground
	
	tell application "System Events"
		keystroke "1" using command down
	end tell
	
	return "Toggle command sent to ProPresenter"
end run
				
			

This is the crucial step to resolve the “Script Editor is not allowed to send keystrokes” error:

1. Open “System Preferences” (or “System Settings” on newer macOS versions)
2. Go to “Security & Privacy” > “Privacy” tab
3. Select “Accessibility” from the left sidebar
4. Click the lock icon in the bottom left and enter your password to make changes
5. Click the “+” button and add the following applications:
– Script Editor
– Companion (if you’re running it locally)
– Terminal (if you plan to run the script via command line)
6. Ensure the checkboxes next to the added apps are ticked
7. Close System Preferences and restart the added applications

For Windows:

  1. Open “Notepad” or any text editor
  2. Copy and paste the Windows PowerShell script provided below
  3. Save the file as “ToggleAudienceScreens.ps1” in a secure, easy-to-find location
				
					# ProPresenter Audience Screen Toggle Script (Windows) - Updated for speed and reliability
Add-Type -AssemblyName System.Windows.Forms

$processName = "ProPresenter"

# Function to check if ProPresenter is running and bring it to foreground
function Focus-ProPresenter {
    $proc = Get-Process | Where-Object { $_.ProcessName -eq $processName } | Select-Object -First 1
    if ($proc) {
        # Bring ProPresenter to foreground
        $sig = '[DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr hWnd);'
        $type = Add-Type -MemberDefinition $sig -Name WinAPI -Namespace Win32 -PassThru
        $type::SetForegroundWindow($proc.MainWindowHandle) | Out-Null
        Start-Sleep -Milliseconds 100
        return $true
    }
    return $false
}

# Main function to toggle audience screens
function Toggle-AudienceScreens {
    if (Focus-ProPresenter) {
        # Send Ctrl+1
        [System.Windows.Forms.SendKeys]::SendWait("^1")
        return "Toggle command sent to ProPresenter"
    } else {
        return "Error: ProPresenter not found or not running"
    }
}

# Run the function and output the result
try {
    $result = Toggle-AudienceScreens
    Write-Output $result
    exit 0
} catch {
    Write-Error "An error occurred: $_"
    exit 1
}
				
			

Step 2: Set Up Companion

  1. Launch Companion
  2. Access the GUI interface (default is 127.0.0.1:8000 or click Launch GUI)

Step 3: Create a Button

  1. Go to the “Buttons” tab in Companion
  2. Find an empty button slot and click on it
  3. In the right sidebar, click “Add action”
  4. Choose your “Execute Shell” connection from the dropdown (internal: Run shell path (local))

For macOS:

  1. In the “Path” field, enter: osascript /path/to/ToggleAudienceScreens.scpt
    (Replace
    /path/to/ with the actual path where you saved the script
    eg.: osascript /Users/kohp/Documents/ToggleAudienceScreens.scpt)
    ** if you do not know what’s the path, open a terminal (found in Applications > Utilities > Terminal.app) then drag and drop the file in the terminal and you will see the full path  
  2. In the timeout field enter: 2000 (increase to 5000 if no response)
  3. Run the test button

For Windows:

  1. In the “Path” field, enter: powershell.exe -ExecutionPolicy Bypass -File "C:\path\to\ToggleAudienceScreens.ps1"

    (Replace
    C:\path\to\ with the actual path where you saved the script
    eg.: 
    powershell.exe -ExecutionPolicy Bypass -FileC :\Users\kohp\Documents\ToggleAudienceScreens.ps1)
    ** if you do not know what’s the path, open a terminal window (run cmd) then drag and drop the file in the terminal and you will see the full path
  2. In the timeout field enter: 2000 (increase to 5000 if no response)
  3. Run the test button

Step 4: Test the Integration

  1. Ensure ProPresenter is running and is the active window
  2. Press the button you created in Companion
  3. Check if the audience screens in ProPresenter toggle on/off

Troubleshooting

  • If the button doesn’t work, verify that the path to your script is correct
  • Ensure ProPresenter is running and is the active window before pressing the button
  • On Windows, if you encounter a PowerShell execution policy error:
    1. Open PowerShell as Administrator
    2. Run: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
    3. Type ‘Y’ to confirm the change

Additional Security Measures

  1. Regularly update ProPresenter, Companion, and your operating system
  2. Use strong, unique passwords for all your accounts
  3. Be cautious when downloading scripts or software from the internet
  4. Consider running scripts in a sandboxed environment if available on your system

Using in Companion v3+

The setup process is similar in Companion v3+, with a more intuitive interface:

  1. In the “Connections” tab, add a new “Execute Shell” connection
  2. In the “Surfaces” tab, find your control surface and add a new button
  3. In the button properties, add a new action and select your “Execute Shell” connection
  4. Configure the action as described in Step 3 above
  5. Use the improved button designer to customize your button’s appearance

Remember, you can always edit your button or connection settings later if needed.

WINDOWS POWERSHELL TESTING (OPTIONAL)

Prerequisites

  1. Windows 10 or later
  2. ProPresenter installed and running
  3. The PowerShell script saved on your computer (e.g., as “ToggleAudienceScreens.ps1” on your Desktop)
  4. Install the official latest release of Microsoft Powershell 7 by clicking here (only for testing directly inside Powershell)
  5. Run Powershell from “C:\Program Files\PowerShell\7\pwsh.exe”

     

Important: Setting PowerShell Execution Policy (OPTIONAL)

 

IMPORTANT: (you can skip this step if you manually installed powershell 7)

Before running the script, you may need to adjust PowerShell’s execution policy. This is a security feature that prevents unauthorized scripts from running.

  1. Open PowerShell as Administrator:
    • Right-click on the Start button
    • Select “Windows PowerShell (Admin)”
  2. Set the execution policy by running:
    Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
  3. Type ‘Y’ and press Enter to confirm the change
  4. Close the Administrator PowerShell window

Steps to Run and Test the Script

  1. Start ProPresenter and ensure it’s running.
  2. Open PowerShell:
    • Press Win + X on your keyboard
    • Select “Windows PowerShell” or “Windows PowerShell (Admin)” from the menu
  3. Navigate to the directory containing your script:
    • If you saved it on your Desktop, type:
    • cd $HOME\Desktop
    • Press Enter
  4. Run the script by typing:
    • .\ToggleAudienceScreens.ps1
    • Press Enter
  5. Watch ProPresenter to see if the audience display toggles on or off.
  6. Check the PowerShell window for the output message. It should say either:
    • “Toggle command sent to ProPresenter” (if successful)
    • “Error: ProPresenter not found or not running” (if ProPresenter wasn’t detected)
  7. Run the script multiple times to ensure it consistently toggles the audience display on and off.

Troubleshooting

If you encounter any issues:

  1. Execution Policy Error:
    • If you get an error about the execution policy, try running this command first:
    • Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
    • Then run the script again.
  2. Script Not Found:
    • Ensure you’re in the correct directory. Use the dir command to list files and verify the script’s presence.
  3. ProPresenter Not Responding:
    • Make sure ProPresenter is running and not minimized
    • Try increasing the sleep duration in the script (change Start-Sleep -Milliseconds 500 to a higher value, e.g., 1000)
  4. Toggle Not Working:
    • Manually press Ctrl+1 in ProPresenter to verify if it toggles the audience display
    • If Ctrl+1 doesn’t work, check ProPresenter’s settings for the correct shortcut
  5. Script Runs But No Effect:
    • Ensure ProPresenter is the active window when the script runs
    • Check if any pop-up windows or dialogs in ProPresenter are blocking the command

Modifying the Script

If you need to make changes:

  1. Open the script in Notepad or a code editor
  2. Make your changes (e.g., adjust the sleep duration or the keystroke sent)
  3. Save the file
  4. Run the script again to test your changes

Remember to test the script thoroughly before integrating it with Companion.