Web API - piggei/wled-usermod-buzzer GitHub Wiki

The usermod exposes:

GET /buzzer

Replace <WLED-IP> with the IP address or hostname of the WLED device.

Play once

curl "http://<WLED-IP>/buzzer?play=victory"

Repeat a finite number of times

repeat is the total number of executions, from 1 to 255:

curl "http://<WLED-IP>/buzzer?play=alarm&repeat=3"

This plays the complete alarm sound exactly three times.

Loop indefinitely

curl "http://<WLED-IP>/buzzer?play=alarm&loop=1"

Stop it explicitly:

curl "http://<WLED-IP>/buzzer?stop=1"

loop and repeat are mutually exclusive.

Custom tone

curl "http://<WLED-IP>/buzzer?tone=1000&duration=200"

Frequency must be an integer from 20 to 20000 Hz. Optional duration must be an integer from 1 to 60000 ms. Malformed, signed, or out-of-range values return HTTP 400.

Custom beep

Duration is an integer from 1 to 60000 ms:

curl "http://<WLED-IP>/buzzer?beep=150"

Optional frequency is an integer from 20 to 20000 Hz:

curl "http://<WLED-IP>/buzzer?beep=150&frequency=2000"

Status

With no command parameters:

curl "http://<WLED-IP>/buzzer"

Example fields include:

{
  "version":"0.2.0",
  "build":"release",
  "enabled":true,
  "ready":true,
  "playing":false,
  "sound":"",
  "loop":false,
  "repeatRemaining":0
}

Important Bash rule

Always quote URLs containing &:

curl "http://<WLED-IP>/buzzer?play=alarm&repeat=3"

Without the quotes, Bash interprets & as a background operator and the parameter after it is not sent to WLED.

Input contract and HTTP errors

Only one command category may be supplied per request: stop, play, tone, or beep. Ambiguous command combinations return 400.

Boolean text is case-insensitive and accepts only 0/1, false/true, and off/on. Numeric parameters are strict decimal integers: values such as -1, 3abc, or abc are rejected.

Status codes:

400 — malformed/out-of-range input, ambiguous commands, invalid repeat, or loop combined with repeat.
404 — unknown sound ID.
409 — buzzer hardware/service is not ready.
503 — a valid command could not acquire/start/stop the playback engine.

Network model

The endpoint follows the same trusted-network assumption as the WLED HTTP interface. Do not expose the device directly to untrusted networks solely to reach /buzzer.

Night Mode

When Night Mode is currently active, playback commands (play, tone, and beep) return HTTP 423 with Buzzer muted by night mode. Stop remains available. A plain status request reports nightMode, nightFrom, nightTo, and muted.