offer a clearer explanation of the flicker effect and its parameters #5392
Conversation
There was a problem hiding this comment.
Pull Request Overview
Improves the documentation for the flicker light effect to provide clearer explanations of its behavior and parameters.
Key changes:
- Replaces vague description with clear explanation of the effect's behavior on brightness and color channels
- Clarifies the
alphaparameter as a smoothing factor rather than "forget-factor" - Better explains the
intensityparameter's impact on visual changes
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughUpdated documentation in Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. 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: 0
🧹 Nitpick comments (1)
content/components/light/_index.md (1)
628-628: Tighten wording; avoid scare quotes and state mean behavior explicitly.Suggest clearer phrasing and remove quotes around hover.
-This effect applies random variations to the brightness and all color channels which "hover" around the active color of the light. The default values simulate a gentle candle flicker, but with different settings it can produce gentle color shifts or chaotic sparkly noise. +This effect applies small random variations to brightness and all color channels that hover around the current light color. Defaults simulate a gentle candle‑like flicker; higher settings can introduce subtle color shifts or more chaotic, sparkly noise.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
content/components/light/_index.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
- Do not generate or add any sequence diagrams
Files:
content/components/light/_index.md
🔇 Additional comments (1)
content/components/light/_index.md (1)
646-647: Define recurrence and clarify intensity units/clipping (verify implementation parity).Replace the two bullets in content/components/light/_index.md (around lines 646–647) with the explicit recurrence and clipping below; docs show defaults alpha = 95% and intensity = 1.5% — verify the implementation uses these defaults, that the update uses next = alpha * prev + (1 − alpha) * random_offset per channel (or adjust wording if the code uses the opposite EMA convention), and that outputs are clamped to [0%,100%].
- alpha (Optional, percentage): Smoothing/memory factor for the random offset per channel. Each step uses an exponential blend
offset_next = alpha · offset_prev + (1 − alpha) · random_offset. Higher alpha → smoother/slower changes; lower alpha → quicker/rougher changes. Defaults to95%.- intensity (Optional, percentage): Magnitude of the per‑step random_offset as a percentage of full‑scale channel value. Applied independently to all active color channels; higher values cause larger brightness/color excursions. Values that push channels below 0% or above 100% are clipped. Defaults to
1.5%.
Description:
Improve documentation and clarity for the flicker effect.
I've always found the description and parameter docs a bit confusing. It mentions "forget-factor" and "amplitude" in the parameter descriptions, and doesn't mention that brightness AND color channels are affected.
After many years of head-scratching I decided to look at the code carefully, test different value combinations, and tried to write a better explanation. My hope is that this change would make it more clear to users how to configure and experiment with the flicker effect.
Related issue (if applicable): none
Pull request in esphome with YAML changes (if applicable):
(none)
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/components/index.rstwhen creating new documents for new components or cookbook.