Companion module 0.2.0

Aurelo Companion & Stream Deck Guide

Use Bitfocus Companion to start or stop translation, change or swap languages, and control listener access from a physical button panel. Aurelo's authenticated local API also works with your own trusted integrations.

Download the Companion module

Version 0.2.0 for Bitfocus Companion. Keep the package as a .tgz file.

Download module

1. Choose how Companion connects

Companion sends commands to Aurelo over your computer or trusted local network. Aurelo remains the source of truth for session state and language rules.

AureloMac or Windows

Local APIToken protected

CompanionSame PC or LAN

Stream DeckPhysical controls

Same computer

Use host 127.0.0.1. Local network access can stay off.

Different computer

Enable local network access in Aurelo and use the displayed LAN address. Both computers must be on the same trusted network.

2. Set up Companion and Stream Deck

Allow about five minutes. Keep Aurelo open while you configure the connection.

1.
Install Bitfocus Companion
Download and install a current version of Bitfocus Companion on the computer connected to your Stream Deck. Companion may run on the Aurelo computer or another computer on the same network.
2.
Connect Stream Deck
Connect your Elgato Stream Deck to the Companion computer. For Companion's direct USB control, close the Elgato Stream Deck application so both programs do not compete for the device.
3.
Import the Aurelo module
Download the Aurelo module package. In Companion, open Modules, choose Import module package, and select the downloaded .tgz file. Do not unzip it.
4.
Enable external control in Aurelo
Open Aurelo → Settings → External Control / Companion and turn it on. Note the host address and port, then copy the authentication token.
Same computer: use 127.0.0.1. Another computer: enable Allow local network access and use Aurelo's displayed LAN host, such as 192.168.1.25.
5.
Add the Aurelo connection
In Companion, add a new connection and search for Aurelo. Enter only the host, port (default 3031), and secret token from Aurelo. Wait for the connection to report ready.
6.
Add buttons
Use the included Start, Stop, Start/Stop tally, and Swap button presets, or assign individual Aurelo actions to your own buttons. Live state, language pair, and errors update automatically.

3. Add actions to your buttons

Choose one of the included presets or assign these actions to your own Companion buttons.

Action	Behavior
Start translation	Runs Aurelo's normal authentication, network, subscription, quota, and readiness checks.
Stop translation	Stops through Aurelo's normal session finalization path.
Toggle start / stop	Starts while idle and stops while live—useful for a single tally button.
Set source and target languages	Applies a language pair. If translation is live, Aurelo safely stops, changes languages, and restarts.
Swap languages	Swaps source and primary target. A live session safely restarts with the swapped pair.
Enable or disable listener access	Controls whether listeners can access Aurelo's translated output.

4. Feedbacks, variables, and presets

Companion uses Aurelo's live status to update button tallies and expose useful values.

Feedbacks

Session live, session transitioning, connection ready, and error present.

Variables

Session state, live flag, source, target, language pair, session ID, Aurelo version, and last error.

Button presets

Ready-made Start, Stop, Start/Stop tally, and Swap buttons.

5. Use the Local Control API

The versioned REST and WebSocket API is available whenever External Control is enabled. Every request and WebSocket connection requires the generated bearer token.

Local network only

Treat the token like a password. Do not forward port 3031 through your router or expose it publicly. Regenerating the token immediately disconnects existing clients.

Authentication and status

curl http://127.0.0.1:3031/api/v1/status \
  -H "Authorization: Bearer YOUR_TOKEN"

API endpoints

Method	Endpoint	Purpose
`GET`	`/api/v1/status`	Read readiness, lifecycle, session, languages, capabilities, and last error.
`GET`	`/api/v1/languages`	List supported language identifiers and current selection.
`POST`	`/api/v1/session/start`	Start translation.
`POST`	`/api/v1/session/stop`	Stop translation.
`PUT`	`/api/v1/languages`	Set source and target. Restarts an active session.
`POST`	`/api/v1/languages/swap`	Swap source and primary target.
`POST`	`/api/v1/listener-access/enable`	Enable listener access.
`POST`	`/api/v1/listener-access/disable`	Disable listener access.
`WS`	`/api/v1/events`	Receive initial and revision-numbered status updates.

Change languages

curl -X PUT http://127.0.0.1:3031/api/v1/languages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"spanish","target":"english"}'

Responses use { ok, data?, error?, requestId }. Common errors include 401 authentication, 409 transition conflict, 422 invalid language, 503 Aurelo unavailable, and 504 timeout.

6. Troubleshooting

Companion cannot connect to Aurelo

Confirm External Control is enabled and Aurelo is open. Recheck the host, port, and token. For another computer, enable local network access, use the LAN address—not 127.0.0.1—and allow Aurelo through the computer firewall.

The module does not appear in Companion

Import the downloaded .tgz from Companion's Modules page. Do not extract the package. Restart Companion after importing if the module is not listed immediately.

Stream Deck is not detected

Close the native Elgato Stream Deck application when using Companion's direct USB control, reconnect the device, and restart Companion.

A language button briefly stops translation

This is expected. Aurelo safely stops the live session, applies the new language pair, and restarts so the translation pipeline uses the new configuration.

Buttons stopped working after token regeneration

Regenerating the token invalidates existing HTTP and WebSocket credentials. Paste the new token into the Aurelo connection in Companion.

7. Downloads and support

Aurelo Companion module: Download version 0.2.0 (.tgz)

Bitfocus Companion: companion.free

Aurelo support: [email protected]

Last updated: August 2026