remote-v1: LAN control API
The desktop app can run a small WebSocket API so another device on the same network can edit its effect pipeline, presets and IR library. When network music is available, clients can also browse libraries and control playback on a chosen player. The API carries control messages, not audio. Pipeline commands use EffeTune’s own format; the API does not depend on a particular client. The app also serves a browser client on the same port, so a phone or another computer needs nothing installed.
It is off by default. A random token in the pairing link authorizes access. Without a TLS certificate, traffic uses plain HTTP/WS: use that mode only on a network you trust. Configure TLS to protect the pairing token and commands in transit.
Encrypted connections
Use Settings > Config… > Network > HTTPS connection to select a PEM certificate-chain
file and its private key, and optionally set an HTTPS endpoint such as
https://music.example.com:47300. Saving restarts the remote listener. The endpoint is an
origin only, with no path, query, or fragment; omitting its port selects 443. It names the
direct TLS listener, including one reached over an already configured VPN. Reverse-proxy path
prefixes and forwarded-header discovery are not supported. The configured endpoint is used
for pairing links, PWA media, and effects connections. A fixed endpoint does not fall back to
another port.
Alternatively, set EFFETUNE_REMOTE_TLS_CERT and EFFETUNE_REMOTE_TLS_KEY to those files
before starting the desktop app. EFFETUNE_REMOTE_ENDPOINT selects the HTTPS origin, and
EFFETUNE_REMOTE_PORT selects the listener port; when both are set, their ports must agree.
Setting any of these four environment variables makes the environment configuration take
precedence as a whole and makes the GUI connection settings read-only. Keep the private key
outside the application’s public asset folders and restrict access to your account.
The certificate must cover the IP address or hostname in the pairing link, and each connecting browser,
desktop client or MCP runtime must trust its issuer. For a private CA, install that CA in the
client’s trust store; Node-based MCP clients can use NODE_EXTRA_CA_CERTS. Do not disable
certificate verification. Renew the certificate before it expires and restart EffeTune after
replacing it.
Both files are required for TLS. An unreadable, invalid or mismatched certificate/key prevents the remote server from starting; it never silently falls back to plaintext. With neither variable set and no GUI TLS configuration, HTTP/WS connections remain available. TLS mode requires HTTPS/WSS clients; HTTP/WS is not also exposed on another port.
Enabling
Open Settings > Remote Control…. The dialog opens over the main window. Allow remote control
enables the server and shows a QR code and the pairing link as text. The setting and the token are saved in
config.json in the user-data folder, so the server comes back after a restart. New token
replaces the token; clients that are connected are closed with 4401 and must pair again.
Clearing the checkbox closes all clients (1001) and releases the port.
Allow remote control is also available under Settings > Config… > Network; both dialogs use the same setting.
In the main window, the Effect Pipeline header has a Remote Control icon (broadcast symbol, tooltip “Remote Control”, Electron app only). It is dimmed while the server is off, drawn in the accent color while it listens, and shows a small badge with the number of connected devices. Clicking it opens the same Remote Control dialog. Close it with Close or Escape; remote control stays enabled.
The port is 47300 unless it is busy. When another process (for example a previous instance that is still shutting down) holds it, the app retries the same port 4 times, 750 ms apart, then moves up to the next free port (47301 … 47309). The pairing link and QR code always carry the port that was actually bound, and the Remote Control dialog shows it. If every port from 47300 to 47309 is taken, the dialog reports the error.
Overrides, mainly for tests:
set EFFETUNE_REMOTE=1 (or pass --remote) start the server regardless of the switch
set EFFETUNE_REMOTE_TOKEN=<token> use this token instead of the saved one
set EFFETUNE_REMOTE_PORT=<port> first port to try instead of 47300 (fallback: <port>+1 ... <port>+9)
npm start
Pairing
The desktop player’s integrated effect editor also uses this authenticated v1 connection. Its saved pairing link is associated with the player explicitly selected by the user, not a matching device name. Selecting another playback destination never changes the meaning of this server: clients connected to A continue to edit A’s pipeline even while A’s screen is showing B. Network discovery and library sharing do not grant effect-editing access.
One link and one QR code serve every client. It is the http URL of the web client the app hosts:
http://<LAN IPv4>:<port>/?t=<token>
A browser opens it as is. A native client that speaks WebSocket takes the same link and derives the connection URL from it: same host and port, scheme ws, same
t (see Connection). The Remote Control dialog does not ask which kind of client will connect.
Copy link puts this link on the system clipboard.
Without a configured HTTPS endpoint, the address is the computer’s private IPv4 address (192.168.x, 10.x, 172.16-31.x). Virtual adapters (VirtualBox, Hyper-V, VMware, WSL, Docker, Tailscale’s 100.64/10, VPNs) are left out where they can be recognised by name or MAC prefix. If several addresses remain, the window offers a choice between them.
Connection
ws://<host>:<port>/?t=<token>- A missing or wrong token: the socket is closed with code 4401.
- At most 16 authenticated clients; extra ones are closed with 1013.
- Frames are JSON text, at most 4 MB.
- Requests that arrive while the window is still starting (or reloading) are held for up to
20 s, then answered with
renderer-unavailable.
Pipeline format
Items use the “short” serialization, the same one used by ?p= share links and undo history
(getSerializablePluginStateShort in js/utils/serialization-utils.js):
[{"nm":"Volume","en":true,"vl":-3},
{"nm":"5Band PEQ","en":true,"f0":100,"ch":"L","ib":1,"ob":2}]
nm is the effect’s display name, and the other keys are the parameter keys from each
effect’s params.json. IR Reverb refers to its impulse response by library id: "ir":"<24 hex>".
Requests (client → app)
Any request may carry "seq": <integer>. When it does, the app answers with
{"op":"ack","seq":n,"ok":true} or {"op":"ack","seq":n,"ok":false,"error":"..."}. For
requests that also return data, the ack comes first and the data message carries the same
seq (except getIR, see below).
| Request | Effect |
|---|---|
{"op":"hello","v":1,"app":"MyRemote","version":"1.0","build":"12"} |
Replies with state, which also carries "features":["origin","savePreset","irSync","irSelection","sync1","describe1"], "appName" and, once the effect renderer is ready, "effects". "music1" is also advertised when network music is available. Any other v is rejected. app, version and build are optional strings naming the client (control characters removed, cut to 48 characters). The Remote Control dialog shows app and version. Other extra fields are ignored. |
{"op":"get"} |
Replies with state. |
{"op":"chain","pipeline":[...]} |
Replaces the whole pipeline (at most 256 items). If any nm is unknown, the request fails and nothing changes. Master bypass keeps its state. |
{"op":"params","index":i,"params":{...}} |
Applies the keys to stage i (0-based) of the current pipeline. Keys that are not given stay as they are. |
{"op":"bypass","on":true} |
Sets master bypass. |
{"op":"listPresets"} |
Replies {"op":"presets","names":[...]}: the presets whose effects all exist in this build. |
{"op":"getPreset","name":"..."} |
Replies {"op":"preset","name":"...","pipeline":[...]} in the short format. |
{"op":"savePreset","name":"...","pipeline":[...]} |
Saves the pipeline as a preset under name, overwriting one with the same name. Same file and format as the preset dialog’s Save. Fails if any nm is unknown or the name is empty. The live pipeline does not change. |
{"op":"listIRs"} |
Replies {"op":"irs","items":[{"id","name","bytes","ext","channels","sampleRate","frames"}]}. |
{"op":"listIRs","includePairs":true} |
Also lists true-stereo pairs for selection and includes topology and importedAt. File transfer remains limited to single-file entries. |
{"op":"selectIR","epoch":"...","slot":"A","id":"h.1","ir":"..."} |
Loads a saved IR on the host into the addressed IR Reverb stage. Requires the current epoch and slot; a missing stage or IR fails. Advertised by the irSelection feature. |
{"op":"getIR","id":"..."} |
Sends the IR file (see IR transfer). Unknown id: ok:false. |
{"op":"putIR", ...} |
Uploads an IR file into the library (see IR transfer). |
Pushes (app → client)
{"op":"state","rev":12,"app":"2.12.0","masterBypass":false,"pipeline":[...],"origin":"local"}
Sent in reply to hello and get, and pushed to every authenticated client whenever the
pipeline changes for any reason, at most 10 times per second. rev goes up only when the
content changes.
origin says where the change came from:
"local": made on the computer (the app’s UI, undo, loading a preset there, …)."remote": caused by a client’schain,paramsorbypass. The copy sent to the client that issued the command also carries that command’s"seq"; the other clients get noseqand should treat the change like an external one.
Changes that arrive within 300 ms after a command finished are counted as that command’s.
When one push covers changes of several origins, it is "local" if any of them was local,
and it carries no seq if they came from different clients. A client can therefore follow
the computer by applying every push that does not carry one of its own seq values.
A client that cannot keep up with the pushes (its socket buffer is full) skips some and receives
one coalesced state once it has drained. That state keeps the same rule: when everything it
covers was that client’s own commands it is "remote" with the seq of the latest of them, and
otherwise it carries no seq.
Replies to hello and get carry the request’s seq and "origin":"remote". They are
snapshots, not echoes of an edit: always apply them. A command that leaves the pipeline as it
was produces no push, so do not wait for one to confirm a command; the ack does that.
Since the sync1 extension every state also carries epoch, ids, slot and host (see
Sync extension). Clients that do not know them ignore them.
audio carries the host’s sampleRate, channelCount, and routingChannelCount. The last
field is the channel limit used by the host’s routing editor, which may allow preparing
routing before the output device is active. The browser editor uses these values for its UI.
The reply to hello also carries "appName" ("EffeTune") next to "app", which is the
version string. They are for display. Clients decide what they can do from features, never
from app or the version.
Once the effect renderer is ready, it also carries "effects", the sorted names (nm) of every
effect this app can load. During startup, a music-capable hello may arrive before the renderer
is ready and omit effects. Request hello again after the renderer is ready before comparing
effect sets. A client
compares effects with its own effect set before sending a chain: an effect that is not listed
makes chain fail as a whole (unknown effect), so the client should leave such stages out and
say so.
IR transfer
IRs are identified the same way as in the app’s IR library (js/ir-library/ir-library-id.js):
the first 24 hex characters of the SHA-256 of the file’s bytes. Files are sent as they are
(WAV, FLAC, AIFF, …), base64 encoded, in chunks of at most 512 KiB of raw data. Files may
be up to 64 MiB and up to 16 channels.
Download:
→ {"op":"getIR","id":"6fc4…","seq":7}
← {"op":"irChunk","id":"6fc4…","name":"Hall.wav","ext":"wav","index":0,"total":3,"bytes":1234567,"data":"<base64>","seq":7}
← ... index 1, 2 ...
← {"op":"ack","seq":7,"ok":true}
All chunks come before the ack.
Upload: send the chunks in order on one connection, starting at index 0:
→ {"op":"putIR","id":"6fc4…","name":"Hall.wav","ext":"wav","index":0,"total":3,"bytes":1234567,"data":"<base64>","seq":8}
← {"op":"ack","seq":8,"ok":true}
→ ... index 1, 2 ...
Every chunk that carries seq is acked. After the last chunk the app checks that the bytes
hash to id and imports the file through the same call as the library’s Import button, so the
id and name are registered as usual; the last ack says whether that worked (id mismatch,
unsupported file type, import failed, …). A chunk out of order, or a size that does not
add up, cancels the upload. At most two uploads can be in progress per connection. name is
the file name; ext is added when name does not already end with it. Uploading a file that
is already in the library succeeds and changes nothing.
Only single-file IRs are listed and transferred. A true-stereo pair (two stereo files named L/R) has a combined id and is left out.
Browser clients
The desktop app also serves the EffeTune web client on the remote port, over HTTP or HTTPS when TLS is configured:
http://<LAN IPv4>:<port>/?t=<token>
The Remote Control dialog shows this link and its QR code (the same ones apps use). The page is remote.html: the real effect list and pipeline editor
of EffeTune, without the player, library, audio settings or measurement tools. It keeps the token
in localStorage, removes t from the address bar and opens ws://<same host:port>/?t=<token>
(or wss:// when the page uses HTTPS).
The hosted web version (https) cannot do this: a browser refuses ws:// to a LAN address from an
https page, which is why the desktop app serves the page itself. The desktop app can also join
another one: Join another EffeTune in the same dialog opens a client window for a pasted link.
The remote editor receives effect settings, not audio measurements or processing status. It hides analyzer results, live meters, and local IR or filter readiness messages. Graphs that also explain the settings remain visible, with their unsynchronized measurement traces and readouts removed. On mobile, the + button sits near the bottom edge because this page has no player or navigation tabs.
In IR Reverb, Choose from library… selects a saved IR from the connected computer,
including true-stereo pairs. With irSync, Upload file… explicitly imports one IR file
of up to 64 MiB into that computer and Download saves a single-file IR to the controlling
device. Pairs cannot be transferred, and deletion stays on the connected computer. IR libraries
are never copied automatically. Individual effects offer built-in presets, but individual user
presets are unavailable remotely; saved pipeline presets belong to the connected computer.
Measurement and SFZ library selection are unavailable in the remote editor and their selectors
are hidden. Existing assignments remain in use, and their effect parameters can still be adjusted.
Actions that only reset local audio analysis or learning are also hidden. Graph editing remains
available, while frequency audition is unavailable from the remote editor.
- Static files:
GETandHEADonly. Only the files the web version precaches (sw-precache.js, withouteffetune.html,sw.js,sw-precache.jsandmanifest.json) are served; everything else, includingconfig.jsonand the app’s ownelectron/code, is 404. They are public application code, so they need no token; the WebSocket still does, unchanged. Hostheader (static files, and WebSocket upgrades that carry anOrigin): an IPv4 literal,localhost,[ipv6]or*.local, optionally with a port. Anything else gets 403 (DNS-rebinding defence), except the exact hostname and port of a configured HTTPS endpoint. A WebSocket upgrade withoutOriginis not a browser request, so itsHostis not checked: native clients and scripts may connect through any host name (NetBIOS, MagicDNS).Originheader (WebSocket upgrade only): anhttp:/https:origin must be exactlyhttp://<Host>in plaintext mode orhttps://<Host>in TLS mode. A missingOrigin(native clients, scripts) is accepted;Origin: nulland other schemes get 403.remote.htmlis sent withContent-Security-Policy: connect-src 'self' ws://<Host>(usingwss://<Host>in TLS mode).- The page is served from one origin per port. If the port falls back (47300 busy, 47301 used), the origin changes and the QR code must be scanned again.
Sync extension (sync1)
Advertised as "sync1" in features. It lets every participant (the app itself, browser clients,
native clients) edit the same pipeline and see each other’s edits live. Everything is additive: a client
that ignores it keeps working with chain, params and bypass exactly as before.
State fields
Every state message (replies and pushes) also carries:
| Field | Meaning |
|---|---|
epoch |
8 hex characters, new whenever the app’s window is (re)loaded. Ids and rev are comparable only within one epoch. |
ids |
string[], parallel to pipeline: the stage id of every item. It is not inside the items, because clients echo items back unchanged. |
slot |
"A" or "B": the active pipeline. |
host |
the computer’s host name, for display. |
hello may carry "sync":1 (and "build":"browser" or "desktop-client" for the web client). It
only makes the connection receive presetsChanged and irsChanged.
Stage ids
A stage id is an opaque string matching ^[A-Za-z0-9_.-]{1,40}$ that belongs to one plugin
instance. The app gives h.<n> to every stage it creates (adds, preset loads, undo, chain, A/B).
A client names the stages it creates c<random>.<n> and may propose the id in ins; ids starting
with h. cannot be proposed. A loaded preset, chain or undo replaces every id.
Ops
edit carries a batch of ops that address stages by id:
{"t":"set", "id", "p":{<shortKey>:value,...}, "d":[<optional shortKey>,...]} // d: optional keys to unset
{"t":"ins", "id", "after": id|null, "at": int, "item":{"nm":..., ...short state}}
{"t":"del", "id"}
{"t":"mov", "id", "after": id|null, "at": int}
{"t":"bypass", "on": bool}
Position rule, the same everywhere: after:null puts the stage at the head; otherwise, if the
after stage exists, right after it; otherwise at min(at, length). set, del and mov on a
missing id are skipped, ins of an existing id is skipped, set is last-writer-wins per key in the
order the app receives them. A changed effect (nm) is a del plus an ins, never a set.
d removes optional keys omitted from the new short state, including ib, ob, ch and
effect parameters such as Room EQ’s ms0 and mn0. Effect parameters are restored using the
effect’s serialized-state rules after those keys are removed. The required nm and en keys
cannot be removed.
→ {"op":"edit","seq":5,"epoch":"9f3a01cc","base":41,"slot":"A","ops":[...]}
← {"op":"ack","seq":5,"ok":true,"rev":42,"skipped":[1]}
The whole batch is validated before anything is applied. Errors (ok:false): stale-epoch,
slot-mismatch, invalid-op (malformed op or id), unknown-effect, too-long (more than 512 ops
or a result over 256 stages). base (the client’s confirmed rev) is informational and never makes
an edit fail.
slot is the pipeline ("A" or "B") the client made the batch against, taken from the state it
had adopted. Stage ids belong to one pipeline: when slot differs from the host’s active slot (the
A/B button was pressed in the meantime) the host answers slot-mismatch and applies nothing, so an
ins can never land in the other pipeline. The client then fetches the state (get) and shows the
active pipeline. A malformed slot is invalid-op; an edit without slot is applied to the
active pipeline as before (clients written before this field).
edit may carry operation, a unique string matching ^[A-Za-z0-9_.-]{1,40}$, to group
successive batches from one user action into one undo step. Keep the same id throughout a
slider drag, including pauses, and use a new id for the next action. Send the final value
before operationEnd:true; an empty ops array with the same id can close the action when
its last value was already sent. Batches without operation are recorded individually.
An intervening host or client action starts a separate undo step. Undo and redo remain global.
The browser editor uses its pointer, keyboard and text-edit boundaries and flushes pending
values before requesting undo or redo.
rev on acks: every ack of edit, history, slot, copySlot, loadPreset and also of the older
chain, params and bypass, plus selectIR, carries rev, the app’s revision after the command took effect. A
state with rev >= ack.rev contains the command. skipped lists the indexes of ops that did not
apply.
Other ops
| Op | Effect |
|---|---|
{"op":"history","dir":"undo"} / "redo" |
The app’s own undo or redo. It is global: it reverts the last change by anyone. |
{"op":"slot","slot":"B"} |
Switches the active pipeline like the A/B button, including its short fade. No-op when already active. |
{"op":"copySlot","from":"A","to":"B"} |
Same as the copy A to B / B to A buttons. |
{"op":"presets"} |
Replies {"op":"presets","presets":{name:preset,...}} (loadable presets, stored format). |
{"op":"loadPreset","name":"..."} |
Loads a stored preset as if the user picked it on the computer (message, preset name, history). |
{"op":"deletePreset","name":"..."} |
Deletes a stored preset. |
{"op":"presetsChanged"} (no seq) is pushed to sync connections whenever the stored presets
change.
{"op":"irsChanged"} (no seq) is pushed to sync connections whenever the IR library gains or
loses an entry (an import in the app, an upload with putIR, a backup restore, a removal). It
carries no payload: the client calls listIRs and fetches what it is missing with getIR. The
host waits for a pause of 400 ms before sending (at most 3 s while imports keep coming), so a
folder import produces a few notices, not one per file. The notice also reaches the connection
whose putIR caused it; re-listing then finds nothing new. Connections without "sync":1 never
receive it.
A removal also sends it, so a client that uploads its own IRs should only send what was added on
its side since its last listing: uploading everything the host lacks would undo the removal at once.
Transport details
- A connection whose send buffer holds more than 1 MiB skips state pushes and gets the latest state once it drains (a full state replaces any earlier one).
- Pushes never carry a
seq, except the copy for the client that issued the command, as before.
Client algorithm
The app broadcasts full states; a client keeps confirmed (the last state it adopted) and a list of
pending batches it sent. What it shows is apply(confirmed, pending).
- On a state: if the epoch changed, drop
pendingand adopt it; ifrevwent backwards, ignore it; otherwise adopt it. Drop every pending batch whose ackrevis<=the adoptedrev. Redraw fromapply(confirmed, pending). - On a local edit: diff the editor against
apply(confirmed, pending)into ops, send them as oneedit(at most every 33 ms) and add them topending. - On an ack: remember its
rev; a failed ack removes the batch and the editor snaps back. - After 10 s without an ack, drop the batch and send
get. - On disconnect, drop
pending; the state received after reconnecting is adopted as a whole. An edit whose ack was lost is never resent, because it could undo a newer change by someone else.
Conflicts:
| Case | Outcome |
|---|---|
| Same key edited at once | The app’s arrival order wins; everyone adopts it. |
| Different keys of one stage | Both are kept. |
set/mov on a deleted stage |
Skipped. |
ins/mov after a deleted stage |
Placed at the clamped at. |
Preset load, chain or undo racing an edit |
New ids; later ops on old ids are skipped. |
| App restart or window reload | New epoch; pending is dropped and the state adopted. |
Effect descriptions (describe1)
Advertised as "describe1" in features. It tells a client which short keys each effect takes,
so it can build a stage it has never seen in a pipeline.
→ {"op":"describeEffects","seq":7}
← {"op":"ack","seq":7,"ok":true}
← {"op":"effects","seq":7,"effects":[
{"nm":"Volume","category":"Basics","params":[
{"key":"vl","type":"number","default":0,"control":"number","label":"Volume",
"min":-60,"max":24,"step":0.1,"unit":"dB","scale":"linear","scaled":false}]},
...]}
effects is sorted by nm and lists every effect the app can load. Each entry has:
| Field | Meaning |
|---|---|
nm |
The effect name used in pipeline items. |
category |
The category shown in the effect list, when the effect has one. |
params |
One entry per key of the effect’s short state except nm and en, in the order of that state. |
uiError |
true when building the effect’s controls failed; its params then carry only key, type and default. |
error |
Present instead of usable params when the effect could not be created. |
A params entry always has key, type (number, string, boolean, array, object or
null) and default (the value of a newly added stage). source says where the rest of the entry
comes from, in this order of preference:
source |
Meaning |
|---|---|
ui |
The standard control the effect builds for the key. |
catalog |
The generated DSP parameter catalog (dsp/plugins/*/params.json), for keys edited in a graph or a custom control. |
hint |
The hand-written table js/remote/parameter-hints.js (by plugin class name), for keys that neither of the above knows. |
A key without source is described by nothing but its default; keep its shape and change it
with care. A described key has one of these:
| Field | Extra fields |
|---|---|
control: "number" |
label, min, max, step, unit, scale (linear or log); integer: true for whole numbers; scaled for ui |
control: "select" |
label, options ([{"value","label"}]; send value) |
control: "checkbox" |
label |
items |
An array key whose elements all share the description in items. |
elements |
An array key with one description per element. |
members |
An array of objects (for example bands): one description per member key, or an array of them when the elements differ. |
format |
A value with no range, with label and a description of the expected content: text, routing (Matrix), ir-id (IR library id), sfz-id, measurement-id, measurement-channel-id, or internal (computed by the effect; values sent are ignored). |
scaled: true means the control shows a converted view of the stored value (for example a 0..1
value shown as -100..100 %): min, max, step and unit then describe the control, not the key.
When the catalog knows the stored range too, it is given as value: {"min","max"}.
A number may carry minKey: its lower end is then also the current value of that key (for example
Multiband Compressor’s f4 stays at or above f3). Any hint entry may carry a description with constraints a range cannot express (for example a
frequency that must stay above the previous band’s).
A hint whose description says “not clamped by the effect” gives the range of the app’s
control; the effect itself accepts other values. The routing keys ch, ib and ob appear only when
an effect sets them by default; any stage accepts them as in the pipeline format.
The app builds the descriptions once per window load (each effect builds its controls once,
off screen), so the first request can take a moment. These temporary instances stay disconnected
from the live audio pipeline. Descriptions follow the effect set of the app: a new
effect is described as soon as the app ships it. A test starts the app and fails when any key of any
effect is left without source, so a new effect must either use the standard controls, have a DSP
params.json, or get an entry in js/remote/parameter-hints.js.
Network music (music1)
When "music1" appears in features, authenticated clients can browse the paired app’s Music
Library or known network libraries and control playback. The paired app is the gateway. A
library’s serverId identifies the source; a player’s playerId identifies the destination.
Omitting either selects the paired app’s local source or player as described below. Explicit
IDs are always respected, and pipeline and effect requests still control the paired app.
Each accepted request below takes a seq and receives an ack followed by a musicResult carrying that
seq. The ack confirms receipt, not completion. A successful result has "ok":true and a
result; a failed result has "ok":false and an error with code and message.
Request op |
Fields and effect |
|---|---|
listMusicDevices |
Returns a snapshot of the local library, any local player, and currently known network devices, with IDs, availability and capabilities. Optional refresh:true starts asynchronous discovery; an immediate empty network list is not a final finding. |
browseMusic |
Optional serverId, objectId (default "0"), query, sortCriteria, start, count: returns one source’s page of tracks or containers. Search and sorting depend on that source’s capabilities. |
getPlayback |
Optional playerId, start and count: returns playback state and a page of queue entries. |
playMusic |
Optional playerId, ordered items:[{"serverId":"...","trackId":"..."}], optional startIndex: replaces the queue and starts playback at the selected occurrence. Duplicate tracks retain their positions. |
queueMusic |
Optional playerId, ordered items, optional position:"end" or "afterCurrent": inserts tracks without starting playback. |
controlPlayback |
Optional playerId and required action (play, pause, stop, next, previous, seek, seekId, repeat, shuffle, volume, mute), with the action’s seconds, queue-entry id, or value as needed. seekId also starts playback; volume takes a number and mute a boolean, each requiring player support. |
editPlaybackQueue |
Optional playerId and action:"delete" with a queue-entry id, or action:"clear". A queue-entry ID is distinct from a source track’s trackId. |
Without serverId, a blank query browses the local catalog only. Its root objectId:"0"
lists tracks directly; it accepts title sorting with +dc:title or -dc:title. A nonblank query
searches the full local catalog first. Only when that search succeeds with total:0 does the
gateway try known available searchable network libraries in ID order, returning the first
match. A local error does not trigger fallback. An explicit serverId searches only that
source. The result and every item identify their concrete serverId; use the result’s
serverId for later pages and each item’s serverId with its trackId for playback. Local
tracks use serverId:"local" and the native catalog track ID, including CUE tracks.
searchedSources, when present, records matched, noMatches, error, unsupported, or
unavailable for each attempted or skipped source; it does not establish that discovery is complete.
Without playerId, playback requests use the paired app’s actual local player and fail if it
is unavailable. Explicit playerId never substitutes another player. Successful playback
results include the effective playerId. Local catalog playback on the local player needs no
LAN sharing; sending local tracks to another player follows the existing sharing restrictions.
Ordered items may mix local and network track references, but each item requires its concrete
serverId and trackId rather than a file path or media URL.
Pages have a maximum count of 500. A play or queue request accepts 1–4096 items, subject
to the player’s own queue limit. Results contain selected display fields, not media URLs,
file paths, or raw library metadata. Successful commands return the observed player state
after the operation; they do not guarantee audible output. An in-band failure after a change
has begun may carry "outcome":"unknown" and a refreshed playback snapshot. If the socket
closes before the reply, no musicResult arrives; a sent change may still have been partly
applied. Read the player’s state before retrying rather than repeating the change automatically.
Playback results include volume, volumeMax, mute, and per-action capabilities. An
unsupported volume or mute value is null; clients must use the corresponding capability
before enabling a control. Player volume and mute affect music playback on that destination,
independently of system volume, effect gain, and AirPlay sender volume. OpenHome players use
their native queues. AVTransport-only players use a queue held by the gateway, which must
remain running for automatic advancement. Subsonic sources use their own serverId and opaque
track IDs through the same browsing and playback operations; login credentials and stream URLs
are not part of music1 results.
Limitations
- Only the active pipeline (A or B) is exposed.
chaingoes through the preset loader: it adds an undo entry, shows the “preset loaded” message, and clears the current preset name. With master bypass on, the effects may be heard for a moment before bypass is restored.- Effects whose filters are designed in the app (FIR EQ, group-delay EQ, Room EQ) take their parameters as given. IR Reverb finds its file by id, so upload the IR before sending a chain that uses it; an IR Reverb that is already showing “IR not found” does not pick up a later upload by itself.
- Analyzer readings, effect overlays and meters are not sent to clients.
- The IR library window does not refresh while it is open when an IR arrives.
- Browser clients hide unsynchronized analyzer outputs and runtime status. Parameter-derived graphs stay visible, including the settings portion of graphs that also show real-time readings. The IR picker uses the host’s saved library. Measurement and SFZ selectors, audio preview, spectrum overlays, and learning reset are unavailable and hidden. MIDI and clipboard features are unavailable. Undo and redo are global, not per client.
- A client whose plugin rewrites its own parameters without a user gesture is not allowed to send that change (the app’s value is restored); only edits made within 2 s of a touch, key or pointer event are sent.
- No discovery (mDNS). Pair with the QR code or enter the address by hand.