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.
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.
| Address | Arguments | Effect |
|---|---|---|
/emt/play | — | Start the sound |
/emt/stop | — | Stop the sound |
/emt/masterVolume | 0…1 | Master volume |
/emt/listenerXY | x, y (0…1) | Position of the listening cursor |
/emt/sourceGain | source identifier, 0…1 | Volume of a source |
/emt/sourceAutoPlay | source identifier, off / presence / always | Autonomous playback |
/emt/sourceAutoPause | source identifier, seconds | Pause between two repeats |
/emt/layerEnable | layer identifier, 0 or 1 | Turn a layer on or off |
/emt/layerVolume | layer identifier, 0…1 | Volume of a layer |
/emt/layerOpacity | layer identifier, 0…1 | Opacity of a layer |
/emt/setVar | name, value | Set a scenario variable |
/emt/gotoMap | address of the map (what follows map= in its link) | Change map |
/emt/blackscreen | 0 or 1 | Black screen |
/emt/record | start / stop | Recording of the output |
/emt/cueGo | cue name | Recall a cue (module Cues and state recall) |
/emt/headPlay | playhead name, play / stop / rewind | Start, 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
| Option | Default | Role |
|---|---|---|
--osc <port> | 9130 | UDP port listened to |
--web <port> | 9131 | Port of the bridge window (to enter in the OSC panel) |
--sortie <host:port> | 127.0.0.1:9132 | Where to send OSC back |
--lang fr|en | system language | Language of the messages in the terminal |
--origine <address> | earmotion.net, and port 8000 of this machine | One 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.