Advanced configuration

Configuration folder#

On first run, OctoCue Receiver (v1.1.0 onwards) creates some configuration files on your system. These are populated with default details that will work fine for the majority of show setups, but can be edited to tweak the receiver's behaviour as required.

The location of these files depends on your operating system:

OS	Configuration file
Windows	`%APPDATA%\OctoCue receiver\storage`
macOS	`/Users/<username>/Library/Application Support/OctoCue receiver/storage`

note

On macOS, the Library folder is not always displayed by default. To show it:

Open finder and navigate to /Users/<username>
Option-click and select Show View Options
Select Show Library folder

Each file in this folder is a JSON object that contains configuration information for a particular function. If you edit these files, you'll need to close and re-open OctoCue Receiver as configuration details are loaded on app start.

If you make edits and things stop working, delete the contents of this folder entirely - new files with system defaults will be created on startup.

Configuration file edits will persist through upgrades and uninstall/reinstall cycles.

Configuring keypresses#

OctoCue can control PowerPoint by emulating keypresses on your host machine. By default it uses Page Down (for next) and Page Up (for back).

If you'd like to change the keys used, edit keypress.json in the configuration folder.

The default setting for this is:

{
    "useKeyPress": "auto",
    "next": "PageDown",
    "back": "PageUp"
}

As of v1.4.0 useKeyPresscan have one of three values:

true: Always use keypresses
false: Never use keypresses
"auto": Use keypresses when PPT add-in not detected - otherwise use PptDirect (see below)

Individual keys can be set using a set of standard codes that a common across macOS and Windows. Key codes are not case sensitive.

KeyA - KeyZ
Digit0 - Digit9
F1 - F15
ArrowDown, ArrowUp, ArrowLeft, ArrowRight
PageDown, PageUp, Tab, Home, Enter and Escape

Here's an example using the a and b keys:

{
    "useKeyPress": "auto",
    "next": "KeyA",
    "back": "KeyB"
}

There's no support for multiple keypresses or key combinations (e.g. ctrl-v).

Debugging keypresses#

Check and debug your keypresses using our key press logger utility.

PptDirect#

PptDirect allows OctoCue Receiver to control PowerPoint slides without having to emulate keypresses. For a full description, including the advantages of PptDirect over regular keypresses, please read this update article.

By default, OctoCue Receiver will make sensible decisions about when to switch to using PptDirect. However, if you'd like to manually control the use of PptDirect, edit pptdirect.json in the configuration folder. The default setting for this is:

{
    "usePptDirect": "auto"
}

usePptDirect can be true, false or "auto". See the keypresses section above for details of how auto works.

note

PptDirect is a Windows-only technology.

Network control protocols#

In addition to emulating keypresses, OctoCue Receiver v1.1.1 and greater can control third party applications (such as Companion and vMix) using OSC, UDP and TCP commands.

Sample applications

OSC: BitFocus Companion, LightJams, Disguise media servers
Generic UDP: BrightSign players
TCP: vMix, Green Hippo media servers, BlackMagic Design devices

Open sound control (OSC)#

OctoCue receiver can output OSC commands via UDP when it receives 'next' and 'back' clicks from the OctoCue servers. By default this function is disabled, but you can enable it by editing osc.json in the configuration folder.

The default setting for this is pre-configured to work with Bitfocus Companion, but can be re-configured to suit your system requirements.

{
    "useOsc": false,
    "localPort": 57121,
    "localAddress": "0.0.0.0",
    "remotePort": 12321,
    "remoteAddress": "192.168.0.255",
    "next": {
        "address": "/press/bank/1/3",
        "args": []
        },
    "back": {
        "address": "/press/bank/1/2",
        "args": []
        }
}

Here's a more complete example with arguments - which must be of type f (float), s (string), i (integer) or b (blob) - see the OSC specification document for full details:

{
    "useOsc": true,
    "localPort": 57121,
    "localAddress": "0.0.0.0",
    "remotePort": 12321,
    "remoteAddress": "192.168.0.255",
    "next": {
        "address": "/press/bank/1/3",
        "args": [
            {"type": "f","value": 34.5},
            {"type": "s","value": "OctoCue is great!"}
        ]
    },
    "back": {
        "address": "/press/bank/1/2",
        "args": [
            {"type": "i","value": 34},
            {"type": "s","value": "Heading back..."}
        ]
    }
}

UDP#

OctoCue receiver can output generic UDP packets when it receives next and back clicks from the OctoCue servers. By default this function is disabled, but you can enable it by editing udp.json in the configuration folder.

The default UDP configuration is shown below. This will broadcast to every device on the network using address 255.255.255.255:8100.

{
    "useUdp": false,
    "localAddress": "0.0.0.0",
    "remotePort": 8100,
    "remoteAddress": "255.255.255.255",
    "next": "OctoCue says NEXT",
    "back": "OctoCue says BACK"
}

note

The local port is fixed at 57121, and a local address of 0.0.0.0 should work for all applications.

TCP#

OctoCue receiver can connect to TCP servers and send TCP data when it receives next and back clicks from the OctoCue servers. By default this function is disabled, but you can enable it by editing tcp.json in the configuration folder.

The default TCP configuration is shown below - this is setup to control vMix inputs on the local machine (at 127.0.0.1:8099), but can be changed to control anything with a TCP API.

{
    "useTcp": false,
    "localPort": 57123,
    "localAddress": "0.0.0.0",
    "remotePort": 8099,
    "remoteAddress": "127.0.0.1",
    "next": "FUNCTION PreviewInput Input=1\r\n",
    "back": "FUNCTION PreviewInput Input=2\r\n"
}

In most situations the local port should not matter - you should only change this if you get port conflict problems. A local address of 0.0.0.0 should work for all applications.