Skip to content

added random playlist example in json-api.md #276

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AlexeyMal wants to merge 2 commits into
base: main
Choose a base branch
from
Open

added random playlist example in json-api.md #276

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d35d9dd
Update json-api.md
AlexeyMal Oct 18, 2025
b38cb9d
Merge branch 'main' into pr/276
softhack007 May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/interfaces/json-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -345,6 +345,17 @@ transition | Array of time each preset should transition to the next one, in ten
repeat | How many times the entire playlist should cycle before finishing. Set to `0` for an indefinite cycle. Default to indefinite if not provided.
end | Single preset ID to apply after the playlist finished. Has no effect when an indefinite cycle is set. If not provided, the light will stay on the last preset of the playlist.

Sample playlist for an endless cycle of random effects with random colors and random palettes:

```json
{
"9":{"playlist":{"ps":[12],"dur":[600],"transition":[30],"repeat":0,"r":false,"end":0},"on":true,"n":"AllRandomPlaylist"},

"12":{"bri":255,"mainseg":0,"on":true,"seg":[{"bri":255,"c1":128,"c2":128,"c3":16,"cct":127,"col":["r",[0,0,0], "r"],"frz":false,"fx":"r","grp":1,"id":0,"ix":128,"m12":1,"mi":false,"o1":false,"o2":false,"o3":false,"of":0,"on":true,"pal":"r","rev":false,"sel":true,"set":0,"si":0,"spc":0,"start":0,"stop":50,"sx":128 ,"fxdef":true}],"transition":7,"n":"random effect"}
}
```
Comment on lines +348 to +356
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Clarify what this numeric-key JSON payload is for ("9" playlist + "12" preset), and which endpoint to POST to.

This example uses top-level numeric keys "9" and "12" to define both a playlist and a preset in one payload, which differs from the earlier sample that uses a top-level "playlist": { ... } object. The section doesn’t explain whether this form is meant to:

  • apply a playlist immediately, or
  • persist/store a playlist and preset configuration (and which endpoint: e.g., /json, /json/state, /json/cfg, etc.).

Please add one short sentence under the code block (or adjust the example heading) clarifying the intended usage and endpoint so users don’t copy a payload that does nothing.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/interfaces/json-api.md` around lines 348 - 356, The example uses
top-level numeric keys "9" (playlist object with "playlist":{...}) and "12"
(preset/preset segment under "seg":{...}); add one short clarifying sentence
below the JSON explaining that those numeric keys are resource IDs (playlist ID
9 and preset ID 12), that POSTing this payload to /json/cfg will persist/save
both the playlist and preset, and that to apply a playlist immediately you would
instead POST an appropriate state update to /json/state (or use the "playlist"
command) — reference the "9" playlist and "12" preset in the sentence so readers
know which parts are persisted vs applied.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# First, locate and read the relevant section of the documentation file
head -356 docs/interfaces/json-api.md | tail -50

Repository: wled/WLED-Docs

Length of output: 2773

🏁 Script executed:

# Search for playlist-related definitions in the codebase to verify if "r" field exists
rg "\"r\"" -A 2 -B 2 --type-list | head -20

Repository: wled/WLED-Docs

Length of output: 448

🏁 Script executed:

# Search for WLED playlist structure definitions
rg -i "playlist.*object\|playlist.*schema" -A 10 -B 2 docs/

Repository: wled/WLED-Docs

Length of output: 40

🏁 Script executed:

# Look for any mention of "r" in the context of playlists
rg -i "playlist" docs/interfaces/json-api.md -A 5 -B 5 | grep -i "\"r\""

Repository: wled/WLED-Docs

Length of output: 549

🏁 Script executed:

# Search for WLED source code files (likely in a src or similar directory)
find . -name "*.cpp" -o -name "*.h" | grep -i playlist | head -20

Repository: wled/WLED-Docs

Length of output: 40

🏁 Script executed:

# Search for playlist struct/class definitions with "r" field
rg -i "struct.*playlist\|class.*playlist" -A 20 | head -100

Repository: wled/WLED-Docs

Length of output: 40

🏁 Script executed:

# Search for "r" field in playlist context
rg "repeat.*r\|\"r\".*false" -B 3 -A 3 | head -50

Repository: wled/WLED-Docs

Length of output: 40

🏁 Script executed:

# Check if there's a WLED source directory
ls -la | head -20

Repository: wled/WLED-Docs

Length of output: 696

🏁 Script executed:

# Search all documentation files for mentions of "r" field in any context
rg -i "\"r\"" docs/ -B 2 -A 2 | head -100

Repository: wled/WLED-Docs

Length of output: 2742

🏁 Script executed:

# Search for any other references to playlist structure or examples
rg -i "playlist" docs/ -l

Repository: wled/WLED-Docs

Length of output: 219

🏁 Script executed:

# Look for any API documentation or JSON schema files
find docs/ -name "*api*" -o -name "*schema*" -o -name "*json*"

Repository: wled/WLED-Docs

Length of output: 1022

🏁 Script executed:

# Check the main json-api.md file for any notes or footnotes about the "r" field
grep -n "r\|repeat" docs/interfaces/json-api.md | head -30

Repository: wled/WLED-Docs

Length of output: 2159

Remove or document the playlist.r field in the example.

The example includes "r": false inside the playlist object, but the Playlist object table above lists only ps, dur, transition, repeat, and end as valid fields. The documented uses of "r" elsewhere in this file (for segment properties like col, fx, and pal) indicate random values at the segment level, not the playlist level. Either document what r means for playlists in the table, or remove it from the example to align with the documented schema.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/interfaces/json-api.md` around lines 348 - 356, The sample playlist JSON
includes an undocumented "r" field inside the playlist object (the object keyed
as "9" with "playlist":{...}); either remove that "r" property from the example
to match the documented Playlist schema (which lists only ps, dur, transition,
repeat, end), or update the Playlist table above to add a clear entry for "r"
(explaining its type and semantics for playlists). Modify the sample under the
"AllRandomPlaylist" example or the Playlist object documentation accordingly so
the schema and example are consistent.



#### Light capabilities

In order to e.g. only show color controls relevant to a given setup, it is necessary to obtain the color capabilities of the light.
Expand Down