Docs Philips Hue

Entertainment Area

What a Hue Entertainment Area is, why LumaSync requires one, and how to create or edit one in the Hue app — plus Hue Zones, AR-locked sizing, and per-bulb gamut clipping.

What is an Entertainment Area

A Hue Entertainment Area is a grouping of bulbs that the Hue Bridge can drive via its low-latency streaming API instead of the default state API. Streaming trades the bridge’s normal “set colour, wait for ack” round-trip for a continuous feed of RGB frames at up to 20 Hz — fast enough for video-synced ambient lighting.

LumaSync talks to the bridge through the Entertainment API exclusively. That’s why pairing requires at least one area to exist: there’s no fallback to the slower state API.

Why the bridge caps at 20 Hz

The Hue Bridge’s Entertainment API is rate-limited at the source. Streaming faster doesn’t get you more frames — the bridge drops them and your feed stalls. LumaSync’s pipeline is tuned to hit 20 Hz exactly, no more. The telemetry pill (Σ 20 fps on the Hue target) reflects that.

If you want a faster update rate, you need a different output target — that’s what USB LED strips are for. Hue + USB can run simultaneously from the same screen source.

How to create one

Do this once, in the Hue app (iOS or Android):

  1. Open the Hue app.
  2. Go to Settings → Entertainment areas.
  3. Tap Create Entertainment area.
  4. Choose a room. The app suggests adding every bulb in that room; tap individual bulbs to include or exclude.
  5. Position each bulb on the room layout. This is what drives LumaSync’s screen-region-to-channel mapping — a bulb the app puts “top-right” will sample the top-right quadrant of your screen.
  6. Save.

Back in LumaSync, open Settings → Hue, click Refresh list, and pick your new area from the dropdown.

From v1.4, the area-select UI shows each area’s room archetype — Living Room, Bedroom, Kitchen, Office, and so on — fetched in parallel from the CLIP v2 API. Useful when you have multiple Entertainment Areas with ambiguous names (“Area 1”, “Hue area”) and want to pick the right one at a glance.

Bulb selection tips

Not every Hue bulb belongs in an Entertainment Area:

  • Good for Entertainment: Play bars, Lightstrip, Go, Iris, Bloom, standard E27/E14 bulbs. Anything that colour-shifts smoothly.
  • Less good: warm-white-only bulbs can still be included but only respond to the L channel, giving you a dim/bright effect without colour.
  • Avoid: motion sensors, buttons, plugs — they’re not light sources.

LumaSync uses all bulbs in the selected area. If you don’t want a particular bulb dancing along, create a smaller area that excludes it.

Positioning matters

The coordinates you set in the Hue app’s room layout aren’t cosmetic — they’re what LumaSync reads back via CLIP v2 to decide which part of the screen each bulb should sample. Position your Play bars roughly where they physically sit relative to the TV. A bulb at “back-left” will pull colour from the top-left edge of your screen.

You can fine-tune this in LumaSync’s Hue Channel Map Panel (Settings → Hue → Edit positions) without touching the Hue app — LumaSync persists overrides locally.

Hue Zones

From v1.5.0, LumaSync introduces Hue Zones — a layer on top of the Entertainment Area’s bulb positions that lets you group bulbs into logical regions on the room map and place them with zone-relative coordinates instead of absolute ones.

A zone is defined by a centre point, a border colour, and an aspect-ratio-locked size slider that exposes the long-edge metric in real-world units. The size slider keeps the zone’s AR fixed as you scale, so a 16:9 TV-aligned zone stays 16:9 regardless of how big you make it. Each zone can contain a subset of the Entertainment Area’s bulbs; bulb positions inside the zone are stored as fractions of the zone’s bounds, so resizing the zone scales the bulb layout uniformly without re-positioning each bulb by hand.

Zones are persisted as part of the room map (schema migrated automatically from v1.4 layouts via a 1→2 migration shim — your existing setup keeps working). The room map editor renders every zone simultaneously with a per-zone show/hide toggle, so you can sanity-check the layout before streaming.

The full editor walkthrough lives on the LED calibration page; the same canvas drives Hue Zones, USB strip placement, and furniture markers.

Per-bulb gamut clipping

The Hue colour gamut is bulb-specific. Philips classifies bulbs into three gamut types — A, B, and C — each defined by a different RGB triangle in xy chromaticity space. Sending a colour outside a bulb’s gamut causes the bridge to silently clip in the brightest channel direction, which can shift hue.

From v1.5.0, LumaSync fetches each bulb’s archetype and gamut_type from the CLIP v2 /resource/light endpoint during area activation and applies per-bulb gamut A/B/C triangle clipping in the DTLS frame builder hot-path. The clip is luminance-preserving (xy→RGB mapping retains brightness while constraining the chromaticity), so Play bars (gamut C) stay accurate while older E27 bulbs (gamut B) clip without colour drift. No configuration is needed; clipping happens automatically per bulb.

Multiple areas

Only one Entertainment Area can stream at a time from a given client. If you want different lighting per room (living room for movies, bedroom for reading), create one area per room and switch between them in LumaSync’s dropdown. No re-pairing needed.

Type to search. Up and down arrows to navigate, Enter to open.