Scenes - Home Assistant

Scenes capture and restore the state of multiple entities at once. They provide a simple way to set your home to a specific configuration with a single action.

What is a Scene?

A scene is a snapshot of desired entity states that can be activated to set multiple entities to specific states simultaneously. Unlike automations and scripts, scenes don’t have complex logic - they simply set states.

scene:
  - name: Movie Time
    entities:
      light.living_room:
        state: on
        brightness: 30
        color_temp: 400
      light.kitchen:
        state: off
      media_player.tv:
        state: playing
        volume_level: 0.3
      cover.blinds:
        state: closed

Scene Structure

Scenes are entities with the domain scene and are implemented in homeassistant/components/scene/.

Scene Entity

The base scene class extends RestoreEntity:

class BaseScene(RestoreEntity):
    """Base type for scenes."""

    _attr_should_poll = False
    __last_activated: str | None = None

    @property
    @final
    def state(self) -> str | None:
        """Return the state of the scene."""
        if self.__last_activated is None:
            return None
        return self.__last_activated

    async def _async_activate(self, **kwargs: Any) -> None:
        """Activate scene."""
        raise NotImplementedError

    def activate(self, **kwargs: Any) -> None:
        """Activate scene. Try to get entities into requested state."""
        raise NotImplementedError

    async def async_activate(self, **kwargs: Any) -> None:
        """Activate scene. Try to get entities into requested state."""

Key Properties

entity_id: Format is scene.<scene_name>
state: ISO timestamp of last activation
entities: Dictionary of entity states to set

Defining Scenes

Scenes can be defined in multiple ways:

YAML Configuration

scene:
  - name: Romantic
    icon: mdi:candle
    entities:
      light.tv_back_light:
        state: on
        brightness: 1
        rgb_color: [255, 0, 0]
      light.ceiling:
        state: off
      media_player.speaker:
        state: playing
        source: Spotify

Home Assistant Platform

The built-in platform allows dynamic scene creation:

scene:
  - platform: homeassistant
    name: Concentrate
    entities:
      light.office:
        state: on
        brightness: 255
        color_temp: 250

Scene Service

Create scenes dynamically using the scene.create service:

service: scene.create
data:
  scene_id: my_dynamic_scene
  snapshot_entities:
    - light.living_room
    - light.kitchen
    - media_player.tv

Or specify exact states:

service: scene.create
data:
  scene_id: custom_scene
  entities:
    light.living_room:
      state: on
      brightness: 200
    cover.blinds:
      state: closed

Activating Scenes

Turn On Service

Scenes are activated using the scene.turn_on service:

service: scene.turn_on
target:
  entity_id: scene.movie_time
data:
  transition: 2  # Optional transition time in seconds

From Automations

automation:
  - alias: "Evening Scene"
    trigger:
      - platform: sun
        event: sunset
    action:
      - service: scene.turn_on
        target:
          entity_id: scene.evening

From Scripts

script:
  bedtime:
    sequence:
      - service: scene.turn_on
        target:
          entity_id: scene.goodnight
      - delay: "00:00:30"
      - service: lock.lock
        target:
          entity_id: lock.front_door

Scene Entity States

The state of a scene entity represents the last time it was activated:

state = hass.states.get("scene.movie_time")
# state.state = "2024-03-10T14:30:00+00:00"

Scenes maintain their last activation timestamp, which is persisted across restarts.

Transition Support

Some entity types support smooth transitions when activating scenes:

service: scene.turn_on
target:
  entity_id: scene.bright
data:
  transition: 5  # Fade lights over 5 seconds

component.async_register_entity_service(
    SERVICE_TURN_ON,
    {ATTR_TRANSITION: vol.All(vol.Coerce(float), vol.Clamp(min=0, max=6553))},
    "_async_activate",
)

Transition is primarily supported by:

Lights
Some media players
Smart switches with dimming

Scene Components

Base Scene Class

class BaseScene(RestoreEntity):
    """Base type for scenes."""

    _attr_should_poll = False
    __last_activated: str | None = None

    @property
    @final
    def state(self) -> str | None:
        """Return the state of the scene."""
        if self.__last_activated is None:
            return None
        return self.__last_activated

Scene Class

class Scene(BaseScene):
    """A scene is a group of entities and the states we want them to be."""

    @final
    async def _async_activate(self, **kwargs: Any) -> None:
        """Activate scene.

        Should not be overridden, handle setting last press timestamp.
        """
        self._async_record_activation()
        self.async_write_ha_state()
        await self.async_activate(**kwargs)

Dynamic Scenes

Create scenes programmatically using the scene.create service:

Snapshot Current State

# Capture current state of entities
service: scene.create
data:
  scene_id: before_party
  snapshot_entities:
    - light.living_room
    - light.kitchen
    - light.bedroom
    - media_player.tv

Later, restore the scene:

service: scene.turn_on
target:
  entity_id: scene.before_party

Specify Exact States

service: scene.create
data:
  scene_id: work_from_home
  entities:
    light.office:
      state: on
      brightness: 255
      color_temp: 250
    climate.office:
      state: heat
      temperature: 21
    media_player.speaker:
      state: playing
      volume_level: 0.2

Scene Best Practices

Meaningful Names

Use descriptive names that clearly indicate what the scene does.

Complete States

Include all relevant entities to ensure consistent scene activation.

Test Transitions

Test transition times with different entity types to ensure smooth changes.

Scene Snapshots

Use scene.create with snapshot_entities to capture current states before changes.

Integration with Other Components

With Automations

automation:
  - alias: "Morning Routine"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: scene.turn_on
        target:
          entity_id: scene.wake_up

With Scripts

script:
  party_mode:
    sequence:
      - service: scene.turn_on
        target:
          entity_id: scene.party_lights
      - service: media_player.play_media
        target:
          entity_id: media_player.speaker
        data:
          media_content_id: "spotify:playlist:party"

Scene Triggers

Scenes can be used in automation triggers:

scene:
  - name: trigger
    entities:
      sensor.scene_trigger:
        state: "movie"

Comparing Scenes, Scripts, and Automations

Feature	Scenes	Scripts	Automations
Triggers	None	None	Yes
Conditions	None	Yes (in sequences)	Yes
Complexity	Simple state setting	Complex sequences	Complex with triggers
Timing	Instant (with transitions)	Sequential with delays	Event-driven
Use Case	Set multiple entity states	Reusable action sequences	React to events

Platform-Specific Scenes

Some integrations provide their own scene platforms:

scene:
  - platform: hue
    # Hue-specific scene configuration
  
  - platform: homekit_controller
    # HomeKit scene configuration

Scene Services

scene.turn_on

Activate a scene:

service: scene.turn_on
target:
  entity_id: scene.relax
data:
  transition: 3

scene.create

Create or update a scene:

service: scene.create
data:
  scene_id: my_scene
  snapshot_entities:
    - light.living_room
  # OR
  entities:
    light.living_room:
      state: on
      brightness: 128

scene.reload

Reload scene configuration:

service: scene.reload

Scene Storage

Scenes maintain minimal state - primarily the last activation timestamp:

class BaseScene(RestoreEntity):
    async def async_internal_added_to_hass(self) -> None:
        """Call when the scene is added to hass."""
        await super().async_internal_added_to_hass()
        state = await self.async_get_last_state()
        if (
            state is not None
            and state.state is not None
            and state.state != STATE_UNAVAILABLE
        ):
            self.__last_activated = state.state

Common Use Cases

Home Theater

scene:
  - name: Movie Night
    entities:
      light.living_room: off
      light.tv_backlight:
        state: on
        brightness: 10
        rgb_color: [0, 0, 255]
      media_player.tv:
        state: on
        source: "HDMI 1"
      cover.blinds: closed

Work Mode

scene:
  - name: Focus Time
    entities:
      light.office:
        state: on
        brightness: 255
        color_temp: 250
      climate.office:
        temperature: 21
      media_player.speaker:
        state: off

Departure

scene:
  - name: Away
    entities:
      light.all_lights: off
      climate.thermostat:
        preset_mode: away
      lock.front_door: locked
      alarm_control_panel.home:
        state: armed_away

Automations

Use scenes in automation actions

Scripts

Incorporate scenes into scripts

Service Calls

Learn about the service system

State Machine

Understand entity state management

Getting Started

Core Architecture

Building Integrations

Core Concepts

Development

​What is a Scene?

​Scene Structure

​Scene Entity

​Key Properties

​Defining Scenes

​YAML Configuration

​Home Assistant Platform

​Scene Service

​Activating Scenes

​Turn On Service

​From Automations

​From Scripts

​Scene Entity States

​Transition Support

​Scene Components

​Base Scene Class

​Scene Class

​Dynamic Scenes

​Snapshot Current State

​Specify Exact States

​Scene Best Practices

Meaningful Names

Complete States

Test Transitions

Scene Snapshots

​Integration with Other Components

​With Automations

​With Scripts

​Scene Triggers

​Comparing Scenes, Scripts, and Automations

​Platform-Specific Scenes

​Scene Services

​scene.turn_on

​scene.create

​scene.reload

​Scene Storage

​Common Use Cases

​Home Theater

​Work Mode

​Departure

​Related Resources

Automations

Scripts

Service Calls

State Machine

Build docs developers (and LLMs) love

What is a Scene?

Scene Structure

Scene Entity

Key Properties

Defining Scenes

YAML Configuration

Home Assistant Platform

Scene Service

Activating Scenes

Turn On Service

From Automations

From Scripts

Scene Entity States

Transition Support

Scene Components

Base Scene Class

Scene Class

Dynamic Scenes

Snapshot Current State

Specify Exact States

Scene Best Practices

Integration with Other Components

With Automations

With Scripts

Scene Triggers

Comparing Scenes, Scripts, and Automations

Platform-Specific Scenes

Scene Services

scene.turn_on

scene.create

scene.reload

Scene Storage

Common Use Cases

Home Theater

Work Mode

Departure

Related Resources