← Back to the help

Controlling EarMotion with OSC

OSC lets you control a map from Max/MSP, Pure Data, TouchOSC, QLab, Reaper or any tool that speaks this protocol: start the sound, move the listening cursor, recall a cue, change the volume of a source, turn a layer on.

How to do it depends on where you use EarMotion.

Menus are named here as the editor shows them in English. The bridge window speaks the language of the editor; the program's messages in the terminal follow the language of your system (or --lang en).

In the desktop application (installations)

The EarMotion desktop application, the one that runs installations, receives OSC without a bridge, over UDP on port 9130. The receiver opens when the installation.txt file asks for it (osc = oui, the default for an installation). It only listens to the machine itself; to control it from another device, add osc-adresse = 0.0.0.0 (macOS will ask for the “Local Network” permission).

Today it only understands the original addresses: /transport/play, /transport/stop, /master, /listener/xy, /map/leave. The /emt/… addresses listed further down go through the bridge, in a browser.

On the website: start the bridge

A browser cannot receive UDP — that is a limit of the browser, not of EarMotion. So you need a small go-between program, the bridge, which listens for OSC on your computer and passes it on to the page.

Max/MSP ──OSC/UDP──▶︎ bridge ──▶︎ bridge window ──▶︎ EarMotion (your computer) (keep it open)

1. Get the bridge

Download emt-osc-bridge.py — a single file, about 20 KB.

It runs with Python 3. On macOS, the first command may offer to install Apple's developer tools: accept. On Linux, Python 3 is usually already there. On Windows, install Python from python.org, checking “Add Python to PATH”; the command is then python emt-osc-bridge.py. The bridge installs nothing and uses no external library.

2. Start it

In a terminal, in the folder where you saved it:

python3 emt-osc-bridge.py

It lists the ports it uses and waits. Leave this terminal window open.

3. Connect the map

In the editor, first turn on the OSC module: right column › Modules › Manage… (or, at the bottom of the left column, Module library › Manage modules…). The OSC entry then appears in the left column, under Interact. Open Local bridge and click Connect the bridge…. A small window opens; it counts the messages received and shows the last one. The bridge stays connected when you switch to Play.

This small window must stay open. Closing it cuts the bridge. You can minimize it or drag it into a corner, but do not close it.

This is the price of a necessary detour: since 2026, browsers ask for a permission before a page can reach a program running on your computer, and that permission is not always offered. Going through a window avoids the question entirely.

Browsers. The setup is tested on Chrome 150 / macOS, end to end, from an external OSC sender. It has not been tested on Safari. On iPad and iPhone, the bridge cannot be used: you need a computer to run the program. Safari has always been the strictest about links between windows, and the bridge window may fail to reach EarMotion there. If in doubt, use Chrome — or the desktop application, which receives OSC without a bridge.

The addresses

One address per action: /emt/<action>. Actions that target something specific — a source, a layer — take its identifier as their first argument.

Why the identifier is an argument and not part of the address. An OSC address accepts neither spaces nor several other characters, while a source identifier looks like src_1723456789_42. The form /emt/sourceGain/src_42 is still accepted, but it is never the only way.

Careful: the name is not enough. A source or a layer is designated by its internal identifier, which the interface does not show yet. To target a source or a layer by a name, go through a cue: set the state you want, then Interact › Cues › Capture the current state, name the cue, and send /emt/cueGo followed by that name.

AddressArgumentsEffect
/emt/play—Start the sound
/emt/stop—Stop the sound
/emt/masterVolume0…1Master volume
/emt/listenerXYx, y (0…1)Position of the listening cursor
/emt/sourceGainsource identifier, 0…1Volume of a source
/emt/sourceAutoPlaysource identifier, off / presence / alwaysAutonomous playback
/emt/sourceAutoPausesource identifier, secondsPause between two repeats
/emt/layerEnablelayer identifier, 0 or 1Turn a layer on or off
/emt/layerVolumelayer identifier, 0…1Volume of a layer
/emt/layerOpacitylayer identifier, 0…1Opacity of a layer
/emt/setVarname, valueSet a scenario variable
/emt/gotoMapaddress of the map (what follows map= in its link)Change map
/emt/blackscreen0 or 1Black screen
/emt/recordstart / stopRecording of the output
/emt/cueGocue nameRecall a cue (module Cues and state recall)
/emt/headPlayplayhead name, play / stop / rewindStart, stop or rewind a playhead

The full list is shown in the OSC panel itself, under Recognized addresses: it always follows what the application can do.

The original addresses still work

/transport/play, /transport/stop, /master, /listener/xy, /map/leave and /source/<id>/gain are also understood by the bridge (and /cue, /head as shortcuts for /emt/cueGo and /emt/headPlay): a patch written for the desktop application works as it is.

Sending the position back to your controller

The Send back the cursor position box makes EarMotion send, twenty times per second, the address /emt/etat/listener with two floats between 0 and 1, to 127.0.0.1:9132. Enough to drive a Max patch or a TouchOSC surface.

To change the destination:

python3 emt-osc-bridge.py --sortie 192.168.1.20:9000

Bridge options

OptionDefaultRole
--osc <port>9130UDP port listened to
--web <port>9131Port of the bridge window (to enter in the OSC panel)
--sortie <host:port>127.0.0.1:9132Where to send OSC back
--lang fr|ensystem languageLanguage of the messages in the terminal
--origine <address>earmotion.net, and port 8000 of this machineOne more page allowed to receive the OSC: an EarMotion served elsewhere (self-hosted, a test server), for example --origine https://emt.my-server.org. Can be repeated, or take several addresses separated by commas; never a path after the host and port.

If it does not work

“No answer from the bridge” — the program is not running, or not on the port shown in the panel. Check the terminal.

“The bridge refuses this page: origin not allowed” — the bridge is running, but you are using EarMotion from an address other than earmotion.net. The bridge window shows the same reason. Restart the bridge with the address given: python3 emt-osc-bridge.py --origine https://emt.my-server.org.

“bridge not connected” after being connected — the small bridge window was closed: closing it cuts the bridge. Click Connect the bridge… again.

“The window was blocked by the browser” — the browser blocked the window from opening. Allow pop-up windows for earmotion.net and try again.

The bridge says “connected” but nothing arrives — your messages are probably not sent to the right port. The bridge counts what it receives: if the counter stays at zero, the problem is upstream, in the tool that sends.

An address is received but marked “unknown” — it does not exist, or its arguments do not fit: missing target, value not in the list. Compare with Recognized addresses, keeping the exact upper and lower case of the action.

The address is not “unknown”, but nothing changes — the target matches no source and no layer (a name is not enough: go through a cue). If the panel shows “OSC module turned off.”, turn the module back on in the module manager.

Security. The bridge window can only be reached from your own computer, and it only passes messages on to EarMotion. The OSC port (9130), however, receives messages from the local network: that is what lets you control the map from TouchOSC on a phone. On a shared network, any device on that network can therefore send commands to the map while the bridge is running; stop it (Ctrl-C) when you are done.