Integrations

PerritoDeck can talk directly to OBS Studio and Home Assistant, it can turn your tablet into a panel for Bitfocus Companion, and AI assistants can use it if you let them.

Setting them up

OBS, Home Assistant and Companion are set up in the app, under Settings → Integrations. Each has its own box:

1. Tick Use OBS Studio, Use Home Assistant or Use Bitfocus Companion, and fill in its address and password or token. The sections below say where to find them.
2. Click Test connection. It tries what you typed, before you save it, and says what it found, for example Connected to OBS 31.0.3, or what went wrong and what to check.
3. Click Save, then Restart now. PerritoDeck uses the new settings after it restarts.

Saved passwords and tokens are never shown again: the box says one is saved, and typing in it replaces it. A saved one is used only with the address it was saved for (or that address moved to https://); if you change the address to another computer, type the password or token again.

To turn one off for a while, untick it and click Save: its settings are kept, so you can turn it back on without typing them again (handy for Home Assistant, which shows a token only once). Remove saved settings… deletes them.

What Test connection can say, and what to do about it:

The integrations file (advanced)

What the form saves goes in a small text file called integrations.toml, in PerritoDeck's settings folder. It's kept separate from your button layouts because it holds passwords, so you can share a profile without giving away your logins. You can also edit it by hand: Open the file under the integrations opens it in your text editor (and makes it if it isn't there yet).

• The file can be read only by your user account. On Windows that's you, SYSTEM and Administrators; on macOS and Linux its permissions are 600. If other accounts on the computer can read it, Settings says so and Make it private fixes it.
• Saving from Settings keeps your notes and anything else in the file as you wrote it; it changes only the lines it needs.
• PerritoDeck reads the file when it starts, so restart it after editing by hand.
• enabled = false in a section keeps its settings but leaves it off, as unticking it in Settings does.

Here's a complete example. Lines starting with # are notes and are ignored.

[obs]
url = "ws://127.0.0.1:4455"
password = "your OBS WebSocket password"

[home_assistant]
url = "http://homeassistant.local:8123"
token = "your long-lived access token"

[companion]
host = "127.0.0.1"
port = 16622

If the file has a mistake, such as a misspelt name or a missing quote, PerritoDeck ignores the whole file, so OBS, Home Assistant and Companion all stay off. Settings → Integrations then says integrations.toml has a mistake and which line it's on, and shows the file read-only until it's fixed. Fix it in your text editor, click Check again, then restart PerritoDeck. Or click Start over…: the file is renamed to integrations.toml.old (which keeps your passwords, so delete it once you're set up again) and you can fill in the form from scratch.

OBS Studio

Switch scenes, start and stop recording or streaming, mute your mic, and see what OBS is doing, right on the tablet. It works with OBS 28 and newer, which have remote control built in.

Set it up

1. In OBS, open Tools → WebSocket Server Settings and tick Enable WebSocket server.
2. Click Show Connect Info to see the port (usually 4455) and the password.
3. In PerritoDeck, go to Settings → Integrations, tick Use OBS Studio, paste the password, and click Test connection, then Save and Restart now. (By hand, it's an [obs] section in the integrations file.)

The address starts with ws://, not wss:// or http://: OBS's WebSocket server only speaks ws://. Type just 192.168.1.20 and the form fills in ws:// and the port 4455. If a saved address starts with anything else, OBS buttons say so, for example OBS: the address 127.0.0.1:4455 in Settings → Integrations must start with ws://, like ws://127.0.0.1:4455.

If OBS runs on a different computer, use that computer's address instead of 127.0.0.1, for example ws://192.168.1.20:4455, and allow port 4455 through its firewall.

OBS buttons

In the button settings, choose OBS Studio under When pressed, then pick what to do In OBS:

• Switch scene (type the scene's name exactly as OBS shows it)
• Start or stop recording; start recording; stop recording
• Start or stop streaming; start streaming; stop streaming
• Mute or unmute an audio source (e.g. Mic/Aux)
• Start or stop the replay buffer; save the replay

In Studio Mode, Switch scene always changes the live scene (OBS's Program side), with OBS's current transition. The preview stays as it is. To set the preview instead, use the OBS Studio plugin.

You can also show OBS's state in titles with {obs:scene}, {obs:recording} and {obs:streaming}, make a toggle that follows obs:recording so it's red exactly while you record, and set an audio source's volume with a slider.

If OBS can't do what a button asks, the button flashes ⚠, and Try it on the Buttons page says why, for example OBS: already recording or OBS: the replay buffer is turned off (Settings → Output → Replay Buffer). When you start a stream, PerritoDeck waits a few seconds to see that it goes live. If OBS can't connect to the streaming service, the button then flashes ⚠, and OBS shows its own message saying why. While OBS is closed, the {obs:…} values show –, and PerritoDeck tries to reach OBS again after 5 seconds, then waits longer each time, up to 30 seconds. Pressing an OBS button always tries straight away.

Want more? The OBS Studio plugin

The built-in OBS support covers the everyday buttons. For much more, such as Studio Mode and transitions, showing or hiding sources, filters, screenshots, the virtual camera, chapter markers, stream time, dropped frames (from the network, and skipped while rendering or encoding) and a live "is this scene on air?" value, add the OBS Studio plugin from the Plugins page. It's set up on the Plugins page rather than in the integrations file. See Plugins.

You can use both at once: they're independent.

Home Assistant

Turn lights on and off, run scripts and scenes, and show sensor readings like the temperature on your buttons.

Set it up

1. In Home Assistant, click your user name at the bottom left to open your profile, then open the Security tab.
2. Under Long-lived access tokens, click Create token, name it "PerritoDeck" and copy the token. Home Assistant shows it only once.
3. In PerritoDeck, go to Settings → Integrations, tick Use Home Assistant, type its address and paste the token. Click Test connection, then Save and Restart now. (By hand, it's a [home_assistant] section in the integrations file.)

Use the same address you use to open Home Assistant in your browser, such as http://homeassistant.local:8123. A saved token goes only to the address it was saved with, or to that same address on https://; for any other address the form asks you to paste it again. The OBS password works the same way. If Home Assistant answers with a redirect, Test connection says where it sends you: use that address instead.

Home Assistant buttons

Choose Home Assistant under When pressed and fill in:

• Service: what to do, such as light.toggle, switch.turn_off, scene.turn_on or script.turn_on. (Newer versions of Home Assistant call these "actions"; they're the same thing.)
• Entity (optional): which device, such as light.desk. You'll find entity IDs in Home Assistant under Settings → Devices & services → Entities.
• Extra data as JSON (optional): settings for the service, such as {"brightness_pct": 40} to dim a light to 40%.

To show a reading in a title, write {ha: followed by the entity ID and }: {ha:sensor.outside_temperature} shows the state with its unit. For one attribute, add it after a dot: {ha:light.desk.brightness}.

A slider can set a light's brightness, and a toggle can follow a light, such as ha:light.desk, so it shows whether the light is really on.

Bitfocus Companion

Bitfocus Companion controls broadcast and AV gear: video switchers, cameras, audio desks, lighting and thousands more. PerritoDeck can make your tablet a Companion surface, so Companion draws the buttons and handles the presses, just like a hardware button panel. You don't need to install anything in Companion.

Set it up

1. In PerritoDeck, go to Settings → Integrations and tick Use Bitfocus Companion. Leave Computer at 127.0.0.1 if Companion runs on the same computer, or type the address of the computer that runs it. 16622 is Companion's usual Satellite port for remote surfaces. Click Test connection, then Save and Restart now. (By hand, it's a [companion] section in the integrations file.)
2. On the Buttons page, click + Profile, type a name such as "Companion", tick Show Bitfocus Companion's buttons and click Create.
3. Show that profile on a tablet: on the Tablets page, pick it in the tablet's Shows menu. (A switching rule works too.)

How tablets appear in Companion

Each tablet showing a Companion profile appears in Companion's Surfaces list as PerritoDeck followed by the tablet's name. Set up its buttons in Companion as you would for any surface. The surface has the same number of rows and columns as the tablet's grid, and pressing and releasing a button both reach Companion, so "on press" and "on release" actions work.

When the tablet disconnects or switches to a different profile, its surface disappears from Companion, and it comes back when the tablet returns.

The Buttons page shows the connection, for example Connected to Companion 3.4.0 or Connecting…. While Companion can't be reached, the tablet's first button says Companion offline, and PerritoDeck keeps trying to reconnect.

Pause keys on the computer pauses Companion buttons too.

Not yet supported

• Companion's rotary encoders and LED rings; PerritoDeck sliders don't map to anything in Companion. Coming
• Putting single Companion buttons on an ordinary PerritoDeck page: a Companion profile shows only Companion's buttons. Coming
• Connecting through Companion's WebSocket port (16623). The regular port works with every Companion since version 2.

AI assistants

AI assistants that support the Model Context Protocol (MCP), such as Claude Desktop and Claude Code, can look at your profiles, press your keys and make new ones for you: "add a key that mutes my mic", "make me a page for my video calls". It's off until you turn it on, and works only on this computer.

1. In PerritoDeck, open Settings → AI assistants (MCP) and tick Let AI assistants use PerritoDeck. It should say Running at http://127.0.0.1:46711/mcp.
2. Choose what assistants may do. Each is off until you tick it:
   • Press keys: press keys already on your profiles, and switch the profile a tablet shows.
   • Edit profiles: make, change, move and remove keys, pages and profiles. Their edits can be undone on the Buttons page like your own. Together with Press keys, this lets an assistant type and submit anything a keyboard can: it can make one key that types a command and another that presses Enter, then press both. Turn one of the two off if you don't want that.
   • Run actions: run any action straight away, including programs and commands. An assistant allowed this can do anything you can do on the computer, so turn it on only for an assistant you trust, and only while you need it. Giving a key an action that runs a program or a plugin also needs this, and so does a key that types something and then confirms it (Enter, Space, or a line break or tab in its text), whether as text or one key at a time, since typing a command and pressing Enter runs it. These are the same keys PerritoDeck lists when you import a profile.
   Changes apply straight away. Without any of them, an assistant can still see your profiles (including what each key does, such as its commands and web addresses), your tablets and live values.
3. Copy the setup for your assistant from the same section:
   • Claude Desktop, and other apps that start a program: copy the first snippet into the app's MCP settings file (for Claude Desktop, claude_desktop_config.json, which its developer settings open for you), then restart the app.
   • Claude Code: copy the claude mcp add --scope user perritodeck "--" … command and run it in a terminal (PowerShell, Command Prompt, Git Bash or any other). It adds PerritoDeck for every folder you use Claude Code in. The "--" is quoted on purpose: PowerShell drops a bare one.
   • Apps that connect to a web address instead: open Connect by address instead. These snippets contain an access token, so keep them private. Make a new token replaces it if it leaks.
4. Ask the assistant something like "What's on my PerritoDeck?" to check it works.

PerritoDeck must be running for the assistant to reach it. If it isn't, or the connection is turned off, the assistant gets a message saying so.

An assistant set up with a command (the first two above) starts a small program, perritodeck-mcp, that passes its messages along, and keeps it running until the assistant closes. You may see it in Task Manager or Activity Monitor as a second PerritoDeck. It's a copy PerritoDeck keeps in its settings folder, so you can quit, update or reinstall PerritoDeck while the assistant is open: the assistant reaches it again by itself once it's running. A new token or a new port needs nothing either.

Assistants set up with an earlier PerritoDeck start PerritoDeck itself with mcp. They still work, but while they're open PerritoDeck's own program stays in use, so on Windows updating it asks to close it. Settings says so when one connects: copy the new setup into that assistant.