Documentation

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’s chain, params or bypass. The copy sent to the client that issued the command also carries that command’s "seq"; the other clients get no seq and 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: GET and HEAD only. Only the files the web version precaches (sw-precache.js, without effetune.html, sw.js, sw-precache.js and manifest.json) are served; everything else, including config.json and the app’s own electron/ code, is 404. They are public application code, so they need no token; the WebSocket still does, unchanged.
  • Host header (static files, and WebSocket upgrades that carry an Origin): 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 without Origin is not a browser request, so its Host is not checked: native clients and scripts may connect through any host name (NetBIOS, MagicDNS).
  • Origin header (WebSocket upgrade only): an http:/https: origin must be exactly http://<Host> in plaintext mode or https://<Host> in TLS mode. A missing Origin (native clients, scripts) is accepted; Origin: null and other schemes get 403.
  • remote.html is sent with Content-Security-Policy: connect-src 'self' ws://<Host> (using wss://<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).

  1. On a state: if the epoch changed, drop pending and adopt it; if rev went backwards, ignore it; otherwise adopt it. Drop every pending batch whose ack rev is <= the adopted rev. Redraw from apply(confirmed, pending).
  2. On a local edit: diff the editor against apply(confirmed, pending) into ops, send them as one edit (at most every 33 ms) and add them to pending.
  3. On an ack: remember its rev; a failed ack removes the batch and the editor snaps back.
  4. After 10 s without an ack, drop the batch and send get.
  5. 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.
  • chain goes 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.