Skip to content

Audio API ​

The audio controller manages DFPlayer playback and the track metadata stored in /assets/audio.json.

Routes ​

MethodPathDescription
getaudioList tracks.
getaudio.statePlayback state, volume, and equalizer.
setaudioUpdate a track.
addaudioAppend a track.
delaudioDelete a track.
cmdaudioPlayback action.

The set/add/del handlers do not inspect the sub-path. Only the plain audio path is intended; use audio.state for reads.

Track List ​

GET audio returns the contents of /assets/audio.json.

json
{
  "id": 1,
  "path": "audio",
  "data": [
    { "id": 1, "title": "Adzan Magrib", "dur": 180 },
    { "id": 2, "title": "Tarhim", "dur": 300 }
  ]
}
FieldTypeDescription
idintegerTrack ID, 1–3000.
titlestringDisplay title.
durintegerDuration metadata in seconds.

Error: no audio config when the file cannot be read.

GET audio.state ​

json
{
  "id": 2,
  "path": "audio.state",
  "data": {
    "vol": 15,
    "eq": 0,
    "state": 1,
    "file": 2
  }
}
FieldTypeDescription
volintegerVolume, 0–30.
eqintegerEqualizer preset, 0–5.
stateinteger0 stopped, 1 playing, 2 paused.
fileintegerCurrent track ID. Present only while playing.

Errors: audio not ready, unknown path for any other read path.

SET audio — update a track ​

json
{
  "id": 3,
  "method": "set",
  "path": "audio",
  "data": { "id": 2, "title": "Tarhim Subuh", "dur": 320 }
}
FieldTypeRequiredDescription
idintegeryesTrack to update.
titlestringnoNew title.
durintegernoNew duration metadata.

A successful update produces no reply. Read audio again to refresh the list.

Errors: missing data, missing id, no audio config, track not found.

ADD audio — append a track ​

json
{
  "id": 4,
  "method": "add",
  "path": "audio",
  "data": { "title": "New Track", "dur": 240 }
}

The server assigns id = max(existing ids) + 1. Defaults are title = "lagu" and dur = 300. Success produces no reply.

Errors: missing data, no audio config.

DEL audio — delete a track ​

json
{
  "id": 5,
  "method": "del",
  "path": "audio",
  "data": { "id": 2 }
}

Success produces no reply. Errors: missing data, missing id, no audio config, track not found (only when duplicate IDs remain after the first match is removed).

Deleting an unknown ID currently returns success without changing the list.

CMD audio ​

json
{
  "id": 6,
  "method": "cmd",
  "path": "audio",
  "data": { "action": "play", "target": 1 }
}
ActionPayloadDescription
playtargetPlay track ID, 1–3000.
pause—Pause the current track.
resume—Resume a paused track.
stop—Stop playback.
volvalSet volume, 0–30.
eqvalSet equalizer preset, 0–5.

Success produces no unicast reply. The device broadcasts audio.state to all clients.

Errors:

ErrorCause
missing datadata is not an object.
missing actionaction is missing.
audio not readyThe DFPlayer is not initialized.
unknown actionUnsupported action.
missing targetplay without target.
invalid targettarget is not an integer or is outside 1–3000.
not playingpause while not playing.
not pausedresume while not paused.
already stoppedstop while already stopped.
missing val / invalid valvol or eq without a valid value.
command failedThe manager rejected the command.
unknown command pathcmd used with a sub-path.

Events ​

See audio.state.

json
{ "event": "audio.state", "data": { "state": 1, "file": 2 } }
{ "event": "audio.state", "data": { "vol": 20 } }
{ "event": "audio.state", "data": { "eq": 3 } }