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 4 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
4 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
3dac886
Clarify JSON payload example for playlists and presets
AlexeyMal May 11, 2026
5b98380
Revise preset saving and activation instructions
AlexeyMal May 13, 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
13 changes: 13 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,19 @@ 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,"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

@coderabbitai coderabbitai Bot May 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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.

@AlexeyMal AlexeyMal May 11, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

The sample playlist JSON includes an undocumented "r" field inside the playlist object. Remove that "r" property from the example.

@coderabbitai coderabbitai Bot May 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@AlexeyMal, here is the corrected JSON with "r":false removed from the playlist object:

{
"9":{"playlist":{"ps":[12],"dur":[600],"transition":[30],"repeat":0,"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"}
}

The only change is removing "r":false, from the playlist object inside key "9", aligning the example with the documented schema (ps, dur, transition, repeat, end).

🧠 Learnings used 
Learnt from: softhack007
Repo: wled/WLED-Docs PR: 310
File: docs/basics/faq.md:321-326
Timestamp: 2026-05-01T12:10:43.108Z
Learning: When documenting or advising about WLED licensing/distribution under EUPL-1.2, treat WLED build environment files such as platformio.ini and platformio_override.ini as part of the firmware source code: they are required to rebuild the firmware and must be shared with recipients when distributing a modified WLED build. In contrast, treat LittleFS runtime user data/config files (e.g., presets.json, cfg.json, ledmap.json, etc.) as runtime user data that are not subject to this source-code disclosure requirement. Ensure your documentation reflects this distinction consistently.

@AlexeyMal AlexeyMal May 11, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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.

@coderabbitai coderabbitai Bot May 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for mentions of /edit, presets.json, /json/cfg across all docs
rg -n "presets\.json\|/edit\|/json/cfg\|json/cfg" docs/ -A 3 -B 2

echo "---"
# Search for how presets are saved/persisted
rg -n -i "preset.*save\|save.*preset\|upload.*preset\|persist" docs/ -A 2 -B 2

echo "---"
# Check for any mention of numeric keys or preset format
rg -n "numeric\|preset.*id\|\"ps\"\|psave" docs/ -A 2 -B 2 | head -80

Length of output: 8

🏁 Script executed:

#!/bin/bash
# Broader search across the whole repo
rg -rn "presets" --type md | head -40
echo "---"
rg -rn "/edit" --type md | head -40
echo "---"
rg -rn "cfg" --type md | head -40
echo "---"
# List all markdown files to understand the repo structure
fd --extension md | head -40
echo "---"
# Check what the /json/cfg endpoint is described as doing
cat docs/interfaces/json-api.md | grep -n "cfg\|edit\|preset" | head -40

Length of output: 11074

@AlexeyMal, I've verified against the repository. The finding is valid — a clarifying sentence is needed. However, I want to correct one detail from the original review comment: /json/cfg is WLED's device configuration endpoint (cfg.json), not for presets. Presets are stored in presets.json and the correct way to upload them is via the /edit filesystem manager page, as confirmed in docs/features/presets.md.

Here is the suggested addition (one sentence) to place directly below the JSON code block:

These numeric keys (`"9"` and `"12"`) are resource IDs — playlist ID 9 and preset ID 12 — stored in WLED's internal `presets.json` file; upload this payload to your device via the `/edit` page to persist both entries, then apply the saved playlist by POSTing `{"ps":9}` to `/json/state`.

So the updated section would look like:

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,"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"}
}

These numeric keys ("9" and "12") are resource IDs — playlist ID 9 and preset ID 12 — stored in WLED's internal presets.json file; upload this payload to your device via the /edit page to persist both entries, then apply the saved playlist by POSTing {"ps":9} to /json/state.


---

<details>
<summary>🧠 Learnings used</summary>

Learnt from: softhack007
Repo: wled/WLED-Docs PR: 310
File: docs/basics/faq.md:321-326
Timestamp: 2026-05-01T12:10:43.108Z
Learning: When documenting or advising about WLED licensing/distribution under EUPL-1.2, treat WLED build environment files such as platformio.ini and platformio_override.ini as part of the firmware source code: they are required to rebuild the firmware and must be shared with recipients when distributing a modified WLED build. In contrast, treat LittleFS runtime user data/config files (e.g., presets.json, cfg.json, ledmap.json, etc.) as runtime user data that are not subject to this source-code disclosure requirement. Ensure your documentation reflects this distinction consistently.


</details>



<!-- This is an auto-generated reply by CodeRabbit -->

@coderabbitai coderabbitai Bot May 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@AlexeyMal, here is the plan to apply both changes to the PR:

Changes to docs/interfaces/json-api.md

  • Remove "r":false from the playlist object in the JSON example
  • Add a clarifying sentence below the JSON code block explaining the numeric keys and how to use this payload
🧠 Learnings used 
Learnt from: softhack007
Repo: wled/WLED-Docs PR: 310
File: docs/basics/faq.md:321-326
Timestamp: 2026-05-01T12:10:43.108Z
Learning: When documenting or advising about WLED licensing/distribution under EUPL-1.2, treat WLED build environment files such as platformio.ini and platformio_override.ini as part of the firmware source code: they are required to rebuild the firmware and must be shared with recipients when distributing a modified WLED build. In contrast, treat LittleFS runtime user data/config files (e.g., presets.json, cfg.json, ledmap.json, etc.) as runtime user data that are not subject to this source-code disclosure requirement. Ensure your documentation reflects this distinction consistently.

Failed to handle agent chat message. Please try again.

@softhack007 softhack007 May 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

@AlexeyMal you might have found out already - coderabbit is a review expert AI, but it won't rewrite the PR for you. This is intended :-)

@coderabbitai coderabbitai Bot May 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

@softhack007 softhack007 May 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.

@coderabbitai it is not necessary to upload a (single) custom preset/playlist (JSON format) via network API, /edit or /json/ endpoints. The simpler solution is to directly enter JSON into the WebUI when saving a preset (un-check "Use current state" => textbox "API command"). see my comment #276 (comment).

@coderabbitai coderabbitai Bot May 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@softhack007, thanks for the correction — noted! You're right that the WebUI approach (presets page → un-check "Use current state" → paste JSON into the "API command" textbox) is simpler and should be the primary recommendation, not the secondary "Alternatively..." one.

The clarifying sentence should be reordered to lead with the WebUI method:

These numeric keys (`"9"` and `"12"`) are resource IDs — playlist ID 9 and preset ID 12 — stored in WLED's internal `presets.json` file; the simplest way to save them is via the WLED presets page in the web UI: un-check "Use current state" and paste the JSON into the "API command" textbox, then save. Alternatively, upload this payload via the `/edit` page and apply the playlist by POSTing `{"ps":9}` to `/json/state`.
✏️ Learnings added 
Learnt from: softhack007
Repo: wled/WLED-Docs PR: 276
File: docs/interfaces/json-api.md:348-356
Timestamp: 2026-05-12T20:53:41.325Z
Learning: In WLED documentation (wled/WLED-Docs), when explaining how to save a custom preset or playlist JSON (numeric-key format stored in presets.json), the primary recommended approach is the WLED WebUI presets page: un-check "Use current state" and paste the JSON into the "API command" textbox, then save. The /edit page upload + POST to /json/state is a valid but secondary/technical alternative. Always lead with the WebUI method as the simpler option.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

🧠 Learnings used 
Learnt from: softhack007
Repo: wled/WLED-Docs PR: 310
File: docs/basics/faq.md:321-326
Timestamp: 2026-05-01T12:10:43.108Z
Learning: When documenting or advising about WLED licensing/distribution under EUPL-1.2, treat WLED build environment files such as platformio.ini and platformio_override.ini as part of the firmware source code: they are required to rebuild the firmware and must be shared with recipients when distributing a modified WLED build. In contrast, treat LittleFS runtime user data/config files (e.g., presets.json, cfg.json, ledmap.json, etc.) as runtime user data that are not subject to this source-code disclosure requirement. Ensure your documentation reflects this distinction consistently.

Learnt from: softhack007
Repo: wled/WLED-Docs PR: 316
File: docs/interfaces/json-api.md:0-0
Timestamp: 2026-05-11T21:21:54.170Z
Learning: In this documentation repo, ensure programming language names and API datatype names use consistent, correct capitalization. Flag occurrences of inconsistent capitalization and prefer standard forms like "Rust", "Java", "Python", "YAML", "JSON", "C++", and "JavaScript". Apply this check across all documentation markdown files under docs/.

These numeric keys (`"9"` and `"12"`) are resource IDs — playlist ID 9 and preset ID 12 — stored in WLED's internal `presets.json` file.
Use the UI to save a new preset, uncheck "Use current state" => textbox "API command" appears. Now copy/paste JSON into the API command textarea, then press "save". Activate the playlist preset.
Alternatively, upload this payload to your device via the `/edit` page to persist both entries, then apply the saved playlist by POSTing `{"ps":9}` to `/json/state`.

#### 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