added random playlist example in json-api.md#276
Conversation
added random playlist example
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
WalkthroughDocumentation update adds a new JSON example in the Playlists section demonstrating configuration of an endless playlist with preset 12, random effect and palette selection, and segment brightness settings; includes instructions for uploading via ChangesPlaylists example
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches✨ Simplify code
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/interfaces/json-api.md (1)
350-355: 💤 Low valueFormat the JSON example for readability/correct copy-paste.
The
"12"preset object (and nested"seg"fields) is currently very dense on one line, which increases the risk of accidental edits when users copy it (missing commas/quotes/brackets, etc.). Consider re-indenting the JSON to match the style used in earlier examples in this file.🤖 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 350 - 355, Reformat the JSON example so the preset objects (especially the "12" preset and its nested "seg" array) are pretty-printed with proper indentation and line breaks like the earlier examples; expand the single-line object for "12" into multiple lines for each key (bri, mainseg, on, seg, transition, n) and likewise format the seg object fields (bri, c1/c2/c3, cct, col, frz, fx, grp, id, ix, m12, mi, o1/o2/o3, of, on, pal, rev, sel, set, si, spc, start, stop, sx, fxdef) so commas, brackets and quotes are clear and the "9" -> "playlist" structure remains readable for safe copy/paste.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/interfaces/json-api.md`:
- Around line 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.
- Around line 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.
---
Nitpick comments:
In `@docs/interfaces/json-api.md`:
- Around line 350-355: Reformat the JSON example so the preset objects
(especially the "12" preset and its nested "seg" array) are pretty-printed with
proper indentation and line breaks like the earlier examples; expand the
single-line object for "12" into multiple lines for each key (bri, mainseg, on,
seg, transition, n) and likewise format the seg object fields (bri, c1/c2/c3,
cct, col, frz, fx, grp, id, ix, m12, mi, o1/o2/o3, of, on, pal, rev, sel, set,
si, spc, start, stop, sx, fxdef) so commas, brackets and quotes are clear and
the "9" -> "playlist" structure remains readable for safe copy/paste.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: e7383106-b1af-4603-abdb-28b78eb0982d
📒 Files selected for processing (1)
docs/interfaces/json-api.md
| 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"} | ||
| } | ||
| ``` |
There was a problem hiding this comment.
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.
🧩 Analysis chain
🏁 Script executed:
# First, locate and read the relevant section of the documentation file
head -356 docs/interfaces/json-api.md | tail -50Repository: 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 -20Repository: 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 -20Repository: 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 -100Repository: 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 -50Repository: wled/WLED-Docs
Length of output: 40
🏁 Script executed:
# Check if there's a WLED source directory
ls -la | head -20Repository: 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 -100Repository: wled/WLED-Docs
Length of output: 2742
🏁 Script executed:
# Search for any other references to playlist structure or examples
rg -i "playlist" docs/ -lRepository: 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 -30Repository: 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.
There was a problem hiding this comment.
The sample playlist JSON includes an undocumented "r" field inside the playlist object. Remove that "r" property from the example.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
🧩 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 -->
There was a problem hiding this comment.
@AlexeyMal, here is the plan to apply both changes to the PR:
Changes to docs/interfaces/json-api.md
- Remove
"r":falsefrom 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.
There was a problem hiding this comment.
@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 :-)
There was a problem hiding this comment.
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!
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
@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/.
Updated JSON example in documentation to clarify resource IDs and usage instructions.
AlexeyMal
left a comment
AlexeyMal
left a comment
There was a problem hiding this comment.
resolved coderabbitai reported issues
This comment was marked as outdated.
This comment was marked as outdated.
Updated instructions for saving presets and activating playlists in the JSON API documentation.
|
Dear Frank, |
|
Hallo Alexey, I agree with what you say. Also this is a small addition, that should not require very long discussions. I've actually added the review bot in this repo to (incrementally) improve/harmonize writing style - the bot is still learning and no need to implement each of the requests it makes. Human judgement is still most important 😃. That's why we don't want the bot to re-write docs by itself - AI-written manuals are often unusable. For this PR, my main concern was to keep the example simple and do-able for average users. That why I interfered when seeing the suggestion to use JSON API requests - HA users might be used to that, but most users will not be able to follow. Just please confirm that the example works now (short test) and then I think we're ready to merge. Thanks for the contribution 👍 Frank. |
2 participants
added random playlist example
Summary by CodeRabbit