- Download
ring-view.jsfrom the latest release. - Copy it to
<config>/www/ring-view.js. - Add
/local/ring-view.jsas a JavaScript module under Settings → Dashboards → Resources. - Refresh the browser. After upgrades, a hard refresh may be necessary.
For the recommended HACS installation, see Get started.
Every Ring View setting is available through Home Assistant's visual card configuration. The UI configuration column below shows whether an option appears in Ring View's Config tab, Home Assistant's standard Layout tab, or is handled automatically.
Choose a simple preview or expose camera controls directly on the dashboard.
| Option | UI configuration | Default | Accepted values | Purpose |
|---|---|---|---|---|
type |
No — added automatically | Required | custom:ring-view |
Identifies the custom card. Added automatically by the card picker. |
recording_entity |
Yes — Config tab | Required | camera.* or select.* entity ID |
Official Ring Last recording camera, or the Ring-MQTT Event Select entity whose current option identifies the recording to play. |
recording_selection |
Yes — Ring-MQTT Event Select only | newest |
newest, selected |
newest maps the category from last_activity_entity to that category's slot 1 before playback. selected preserves the Event Select choice for manual history browsing. It has no effect on camera recording sources. |
live_entity |
Yes — Config tab | Required | camera.* entity ID |
Camera entity that starts the Ring live view. |
snapshot_entity |
Yes — Snapshots | Not set | camera.* entity ID |
Device snapshot camera, such as the snapshot entity created by Ring-MQTT. Used by snapshot previews, as the Event Select recording poster, and preferred for manual snapshots when configured and available. |
name |
Yes — Card appearance, when Show camera name is enabled | Entity name | Text | Optional label used instead of the recording entity's friendly name. The editor preserves it while name display is disabled. |
last_activity_entity |
Yes — Card appearance | Auto-discover enabled official Ring recording timestamp | sensor.*, event.*, input_datetime.*, or binary_sensor.* entity ID |
Shows recording age for official Ring Last recording sensors, otherwise relative activity time. An explicit source overrides automatic discovery. Ring-MQTT Ding and motion sensors are supported directly. |
default_mode |
Yes — Fullscreen viewer | last_recording |
last_recording, live |
View selected when the viewer opens. |
remember_last_mode |
Yes — Fullscreen viewer | false |
true, false |
Remembers the most recent view in the current browser and uses it instead of default_mode. |
autoplay_recording |
Yes — Fullscreen viewer | true |
true, false |
Starts the latest recording immediately; when disabled, the viewer waits for Play. |
recording_muted |
Yes — Fullscreen viewer | false |
true, false |
Starts fullscreen recordings muted. When disabled, a browser that refuses audible autoplay leaves the recording ready for a manual Play instead of changing this preference. |
live_muted |
Yes — Fullscreen viewer | false |
true, false |
Starts Live muted. Browser autoplay rules can still require muted playback. |
dashboard_behavior |
Yes — Dashboard card | open_viewer |
open_viewer, interactive |
Keeps the passive card that opens fullscreen, or exposes camera controls directly in the card. |
dashboard_start |
Yes — Dashboard card, interactive only | on_demand |
on_demand, last_recording, live |
Waits for a tap, starts the recording, or starts Live when an interactive card becomes visible. |
dashboard_recording_muted |
Yes — Dashboard card, interactive only | true |
true, false |
Starts recordings inside the dashboard muted. This is recommended for reliable autoplay on phones and wall tablets. |
dashboard_live_muted |
Yes — Dashboard card, interactive only | true |
true, false |
Controls audio when Live starts inside the dashboard. Muted is recommended for tablets and autoplay. |
two_way_audio |
Yes — Fullscreen viewer | false |
true, false |
Uses one direct WebRTC session for live video, listening, and push-to-talk when live_entity is an official Ring live_view camera. |
doorbell_entity |
Yes — Doorbell features | Not set | event.* or binary_sensor.* entity ID |
Displays a temporary ring alert when an official Ring event reports ring, or when a Ring-MQTT Ding sensor changes from off to on. |
door_entity |
Yes — Door access | Not set | lock.* entity ID |
Enables door access for the selected Home Assistant lock. |
door_contact_entity |
Yes — Door access | Not set | binary_sensor.* entity ID |
Optionally makes the icon reflect the physical door state. An open contact replaces and disables the door action until the door closes. |
door_action |
Yes — Door access | unlock |
unlock, open |
Calls lock.unlock, or lock.open for locks that advertise latch-opening support. |
door_control_visibility |
Yes — Door access | live_only |
live_only, all_views |
Shows the door action only in Live by default, or also over recordings. |
door_hold_to_activate |
Yes — Door access | true |
true, false |
Requires a 1.6-second press-and-hold confirmation. Disable for one-tap operation. |
door_control_location |
Yes — Door access, interactive only | viewer_only |
viewer_only, dashboard_and_viewer |
Keeps the door action in fullscreen only, or places it on both the interactive dashboard card and fullscreen viewer. |
show_name |
Yes — Card appearance | false |
true, false |
Shows the camera name at the top left of both the dashboard card and viewer, and reveals the optional custom-name field. |
show_action_button_labels |
Yes — Card appearance | true |
true, false |
Shows text beside the Talk and door-action icons. Disable it for compact icon-only controls in both the dashboard card and fullscreen viewer; accessible names and status remain available. |
show_snapshot_button |
Yes — Snapshots | false |
true, false |
Shows one manual snapshot action while Live is active. |
snapshot_directory |
Yes — Snapshots | /media/ring-view |
Absolute directory path | Folder where manual snapshots are saved by Home Assistant. |
preview_source |
Yes — Dashboard card | last_recording |
last_recording, live, default, snapshot, newest |
Chooses the entity used for the dashboard still. default follows the view that will open; newest compares the optional snapshot with the latest recording. |
preview_fallback |
Yes — Dashboard card | last_recording |
last_recording, snapshot |
Chooses the still used by newest when capture times or update order cannot be compared. Only shown for newest. |
aspect_ratio |
Yes — Card appearance | auto |
auto, 16:9, 4:3, 1:1 |
Sets the image shape. auto follows the loaded poster or video dimensions; explicit values force that shape. |
fit_mode |
Yes — Card appearance | contain |
contain, cover |
Fits the entire image inside the card or crops it to fill the card. |
grid_options |
Yes — Layout tab | See below | Object | Standard Home Assistant Sections-layout sizing. Configure it in the Layout tab. |
These are standard Home Assistant card layout fields rather than Ring View behavior:
| Field | Card default | Purpose |
|---|---|---|
columns |
12 |
Preferred number of grid columns, or full. |
rows |
auto for newly added cards |
Preferred number of grid rows. Existing fixed-height cards keep their saved value. |
min_columns |
12 |
Minimum supported width in grid columns in both dashboard modes. |
min_rows |
3 with fixed height; not set for auto height |
Minimum supported height in grid rows in both dashboard modes. |
max_columns |
Not set | Optional maximum width. |
max_rows |
Not set | Optional maximum height. |
aspect_ratio: auto uses 16:9 as a stable loading shape until valid media
dimensions are available, then follows the current poster or video. It adapts
again when Recording and Live use different shapes. If a custom player does not
expose valid image or video dimensions, the loaded poster remains authoritative.
Cards without a saved grid-row setting use automatic height. An explicitly
saved row count, including three rows, remains fixed.
In a Home Assistant Sections layout, Automatic uses intrinsic row sizing
unless you explicitly configure a fixed grid_options.rows value. Inside an
explicitly fixed slot, fit_mode continues to control cropping or letterboxing.
Narrow or
very short fullscreen layouts also prioritize the available viewport and apply
fit_mode inside it.
type: custom:ring-view
recording_entity: camera.front_door_last_recording
live_entity: camera.front_door_live_view
snapshot_entity: camera.front_door_snapshot
name: Entrance
last_activity_entity: sensor.front_door_last_activity
default_mode: last_recording
remember_last_mode: false
autoplay_recording: true
recording_muted: false
live_muted: false
dashboard_behavior: interactive
dashboard_start: on_demand
dashboard_recording_muted: true
dashboard_live_muted: true
show_snapshot_button: true
snapshot_directory: /media/ring-view
two_way_audio: true
doorbell_entity: event.front_door_ding
door_entity: lock.front_door
door_contact_entity: binary_sensor.front_door_contact
door_action: open
door_control_visibility: live_only
door_hold_to_activate: true
door_control_location: viewer_only
show_name: true
show_action_button_labels: true
preview_source: newest
preview_fallback: last_recording
aspect_ratio: auto
fit_mode: contain
grid_options:
columns: 12
rows: auto
min_columns: 12For Ring-MQTT, select its Ding binary sensor instead:
doorbell_entity: binary_sensor.front_door_dingRing View determines the listener behavior from the entity domain. Event
entities alert when a new ring event arrives. Binary sensors alert only on a
clean off to on transition, so retained on states, reconnects, attribute
updates, and the later on to off reset do not create duplicate alerts.
Ring View 0.2 and newer use this flat configuration only. Earlier nested preview, appearance, viewer, and performance structures are not supported.
With Home Assistant 2026.10+, Ring View automatically uses the enabled official
Ring Last recording timestamp sensor on the selected recording camera's
device when last_activity_entity is unset. Enable that sensor in Home
Assistant's entity settings; it is disabled by default. Discovery uses registry
metadata and requires a single matching sensor, so renamed entities work.
An explicit source always takes precedence. Recording sensors show Recorded …
ago; activity sources retain their activity wording. Older versions and
Ring-MQTT continue to work without this sensor.
Open Card appearance and choose Last activity timestamp to show compact relative text such as 2 min. ago. When the camera name is visible, the time appears directly below it. When the name is hidden, the time takes the same top-left position without leaving an empty line. The option works in the dashboard card and fullscreen viewer.
For sensor, event, and input-datetime entities, the selected entity's state must
contain a complete date and time. Ring View accepts ISO 8601 values, Home
Assistant input-datetime values such as 2026-09-12 10:15:30, and Unix
timestamps in seconds or milliseconds.
A Ring-MQTT Ding or motion binary sensor can be selected directly. Ring View
uses its explicit lastDingTime, lastMotionTime, lastDing, and lastMotion
attributes and, when Home Assistant's device registry is available, chooses the
freshest supported timestamp across available Ring-MQTT binary sensors on the
same device. This continues to work when entities are renamed. It deliberately
does not use the Ring-MQTT Info sensor state, last_changed, or last_updated,
because those values can change for reasons unrelated to visitor activity.
Hovering the relative time shows the exact localized date and time. Assistive technology receives the fuller label Last activity, 2 minutes ago. Unknown, unavailable, or invalid values are not displayed; the visual editor shows a configuration warning instead.
Open Snapshots and enable Show snapshot button. One camera button then appears in the header only while Live is actually active. It is available in the interactive dashboard card and fullscreen viewer. It stays hidden on the passive dashboard card, in Recording, and while an on-demand card is waiting for its first tap.
The button is both Take snapshot and Save. Ring View gives Home Assistant a timestamped JPEG filename, so no separate automation, script, or second save button is required. The icon briefly turns green only after the full capture and save sequence succeeds. A readable message appears when either step fails, using the same centered status display as Ring View's loading, unavailable, Retry, Resume, door-action, and talkback information. Talk and door controls remain visible above the temporary status layer.
Ring View automatically chooses the capture entity:
- Use the configured
snapshot_entitywhen that entity exists and is available. This is normally the Ring-MQTT snapshot camera. - Otherwise use the configured
live_entity, normally the official Ring Live view camera. - Disable the button if neither camera is available.
The first choice uses the same Device snapshot camera already configured
for dashboard snapshot previews. When it belongs to Ring-MQTT, Ring View first
finds the enabled Take Snapshot button on the same Home Assistant device,
presses it, and waits for the snapshot camera's explicit timestamp attribute
to change. Only then does it call camera.snapshot to save the fresh image.
This wait reacts to Home Assistant state updates and never polls. It times out
after 15 seconds rather than saving the old image. A missing or ambiguous
Ring-MQTT refresh control is also reported as an error instead of false success.
Renaming either entity is supported through registry and device identity.
The Snapshots section deliberately does not add another camera selector. The saved image comes from the selected Home Assistant camera entity; it is not a browser screenshot of the visible video frame.
The official Ring Live camera is a compatibility fallback, not a guarantee of
a current Live frame. camera.snapshot can save only the still image that the
entity exposes to Home Assistant. It cannot copy pixels from the active WebRTC
player. With current official Ring behavior, the result can be unavailable or
represent the latest recording instead. Configure the Ring-MQTT snapshot
camera when a fresh device snapshot is required. Ring devices that cannot take
a snapshot while recording or streaming can still time out; Ring View reports
that limitation and does not save a stale frame.
The default folder is /media/ring-view. Home Assistant OS creates /media
automatically.
Home Assistant Container users must mount a directory at
/media. Open Media > My media > ring-view to view saved files. Media files
require Home Assistant authentication, unlike files under /config/www, which
can be publicly accessible.
The editor checks that the configured path is absolute and rejects the
filesystem root, path traversal, control characters, and template markers. It
warns about /config/www and custom locations. Only Home Assistant can verify
that the server folder exists and is writable, so the real write check happens
when the button is pressed. Custom locations may need to be added to
allowlist_external_dirs
in configuration.yaml. Home Assistant creates the final subfolder when the
standard camera.snapshot
action saves the first image.
Files are named like
entrance_2026-09-12_18-42-03-125.jpg, using Home Assistant's configured time
zone. Each tap creates a new file. Ring View does not currently provide a
gallery, automatic cleanup, or a retention limit.
Saving a file does not replace the dashboard preview. The preview continues to follow Image source and its own camera entity. A saved JPEG is a file, not a camera entity, so treating it as the new preview would require a separate Local file camera and would change the meaning of the existing preview setting.
Open Dashboard card and choose one of two intentionally distinct surfaces:
| Behavior | Dashboard | Fullscreen |
|---|---|---|
| Open fullscreen viewer (default) | One passive still image; tapping opens the viewer. | Recording, Live, Talk, and configured door access. |
| Control camera in card | Recording/Live tabs, media controls, optional Talk and optional door access, plus fullscreen. | The same full viewer, opened with the currently selected mode. |
The interactive fields appear only after that mode is selected. No — wait for a tap is the safest startup and does not mount a player until Recording or Live is started. The selected view remains highlighted while its still image is idle, making it clear what tapping the image will start. When a recording is waiting to start in either the dashboard card or fullscreen viewer, tap or click the camera image to play it. The large central Play button is intentionally omitted so the image stays unobstructed. The image surface is also keyboard accessible. The Recording mode remains highlighted after the video ends because it identifies the selected view, not the current playback state. Automatic Live starts only while the card is visible and is muted by default. Home Assistant edit and card-picker previews never connect to the camera and never expose Talk or door actions.
| Visual editor setting | It controls | It does not control |
|---|---|---|
| Dashboard behavior | Whether the dashboard is a still image or an interactive camera. | Which media starts. |
| Start media automatically | What an interactive card starts: nothing, Recording or Live. | What opens in fullscreen. |
| Start recordings muted (Dashboard card) | Initial recording sound inside an interactive dashboard card. | Fullscreen recording or Live sound. |
| Start Live muted (Dashboard card) | Initial Live sound inside an interactive dashboard card. | Fullscreen Live or recording sound. |
| Open viewer on | Whether fullscreen initially shows Recording or Live. | The interactive dashboard startup. |
| Start recordings muted (Fullscreen viewer) | Initial recording sound in the fullscreen viewer. | Dashboard recording or Live sound. |
| Start Live muted (Fullscreen viewer) | Initial Live sound in the fullscreen viewer. | Dashboard Live or recording sound. |
| Show control in | Whether the door action appears only in Live or also over recordings. | Whether it appears on the dashboard. |
| Door control location | Fullscreen only, or dashboard and fullscreen. | Whether Talk is supported. |
Talk is always Live-only and requires Enable two-way audio plus the official Ring Live view camera. If Talk and door access are both available, they appear next to each other as independent, fully rounded controls. If either is unavailable, the remaining action stays centered on its own.
| Use case | Dashboard behavior | Startup | Door location | Suggested safety |
|---|---|---|---|---|
| Normal phone or desktop dashboard | Open fullscreen viewer | Not applicable | Fullscreen only | Live-only door action with hold enabled. |
| Shared family dashboard | Open fullscreen viewer | Not applicable | Fullscreen only | Keep the door action out of the dashboard. |
| Wall tablet, start only when needed | Control camera in card | No, wait for a tap | Dashboard and fullscreen | Live-only, muted Live, hold enabled. |
| Always-on entrance monitor | Control camera in card | Live | Your choice | Start muted; add dashboard door access only on a trusted tablet. |
type: custom:ring-view
recording_entity: camera.front_door_last_recording
live_entity: camera.front_door_live_view
dashboard_behavior: interactive
dashboard_start: on_demand
dashboard_recording_muted: true
dashboard_live_muted: true
two_way_audio: true
door_entity: lock.front_door
door_contact_entity: binary_sensor.front_door_contact
door_action: open
door_control_visibility: live_only
door_control_location: dashboard_and_viewer
door_hold_to_activate: truetype: custom:ring-view
recording_entity: camera.front_door_last_recording
live_entity: camera.front_door_live_view
dashboard_behavior: interactive
dashboard_start: live
dashboard_recording_muted: true
dashboard_live_muted: true
two_way_audio: truetype: custom:ring-view
recording_entity: camera.front_door_last_recording
live_entity: camera.front_door_live_view
door_entity: lock.front_door
door_contact_entity: binary_sensor.front_door_contact
door_action: unlock
door_control_visibility: live_only
door_control_location: viewer_only
door_hold_to_activate: trueDoor control location makes the placement explicit: Fullscreen viewer only or Dashboard and fullscreen. With Live-only visibility, the action reads Open when ready or Unlock when ready and stays disabled until the current Live player has connected. It hides if Live fails, leaving the compact Retry state and the existing mode tabs.
On an exceptionally short interactive card, Ring View temporarily prioritizes a connection, Ding, or error message instead of stacking it over the bottom actions. The actions return when the message clears or the card has enough height.
Open Door access and select a Home Assistant lock to enable the feature. The remaining settings appear only after a lock is selected. Removing the lock returns the card to its previous behavior and removes the inactive door settings from the saved visual configuration.
Door contact sensor is optional. When configured, on means the physical
door is open and off means it is closed, following Home Assistant's binary
sensor convention. The icon then follows the physical state: closed door for
off, open door for on, and a warning for an unknown or unavailable state.
While open, the door control reads Door open and cannot be activated. A
closed contact leaves the configured Unlock or Open action available. If the
contact is unknown or unavailable, the action remains usable and shows
Status unknown; only a positive open state blocks it. Without a contact
sensor, the icon continues to represent the configured action.
Unlock uses the standard lock.unlock service. Open door uses
lock.open, intended for locks such as compatible Nuki devices that can release
the latch. Ring View disables Open when the selected entity does not advertise
that capability.
Require hold to activate is the default confirmation. It is not a pop-up: hold the action for 1.6 seconds while a visible progress fill completes, or release early to cancel. Turning it off makes the action respond to a single deliberate tap, click, Space, or Enter activation.
Live view only is the recommended default. Live and recordings is available for users who intentionally want door access while viewing historical footage. When Talk and door access are both visible, they appear next to each other as separate, fully rounded controls with an eight-pixel gap. If Talk is disabled or unsupported by the configured camera, the door action remains centered on its own.
With Open fullscreen viewer selected, open Dashboard card and set Image source to Newest snapshot or recording, then open Snapshots and select Device snapshot camera. Ring View still renders only one passive image on the dashboard, and tapping it opens the configured Recording or Live view—there is no third viewer tab.
Ring-MQTT publishes a Unix-seconds timestamp attribute whenever it
successfully retrieves a new snapshot. Ring View compares explicit capture
timestamps when both camera entities provide them. The official Ring
last-recording entity currently exposes last_video_id but no capture time, so
Ring View also follows the order of snapshot timestamp and recording ID changes
received after the card loads. On initial load, after a reload, or whenever the
two sources remain incomparable, If capture times cannot be compared makes
the result deterministic. General Home Assistant last_updated values are not
treated as media capture times.
For the official Ring integration, use its last-recording and live-view entities. With a suitable Ring subscription, Home Assistant provides both but disables Last recording by default.
- Open Settings → Devices & services → Ring, then open your Ring device and its entity list.
- Show disabled entities. Before enabling it, the disabled camera entry is Last recording; enable it if you have the required Ring subscription. The camera enabled by default is Live view.
- Open each entry and copy its exact entity ID into the corresponding Ring View field.
The _last_recording and _live_view suffixes in this guide are examples, not requirements. Home Assistant entity IDs can be changed and may be assigned differently. In one field report covering fresh 2K and 4K Ring doorbell installations, both camera entries appeared alike and neither entity ID used the expected suffix. Identify the entities by their roles and default enabled state rather than relying on their displayed names or ID suffixes.
For Ring-MQTT recording playback:
- Choose the device's Event Select entity as Last recording in the Ring View editor.
- For Newest event (automatic), choose a Ring Last activity timestamp entity that reports the event category. Official Ring last-activity sensors and same-device Ring-MQTT Ding/motion timestamps are supported.
- For Selected event (manual), open Event Select and choose the recording you want. Slot 1 is newest within a category; higher numbers are older.
- Open Ring View and select Last recording.
Automatic mode reads the latest activity category, selects Ding 1, Motion 1,
Person 1, or On-demand 1, and waits for the Event Select eventId and
recordingUrl to update. A newer event in the same category also causes slot 1
to be reselected. Manual mode leaves the current Event Select option unchanged.
Ring View tries the direct recording first on every browser, including iPhone
and iPad, while preserving the event slot. If direct playback fails, it requests
the matching (Transcoded) option. If a signed URL is missing or within 30
seconds of expiry, Ring View refreshes it and waits up to 70 seconds for
Ring-MQTT to publish a playable URL. The wait is driven by Home Assistant state
updates; it does not poll. Closing the viewer, changing modes, hiding the page,
or suspending an inline card cancels the wait and cannot start a late recording.
Ring-MQTT can report Recording Not Found or Transcoding in Progress
instead of a URL. Ring View treats both as unavailable media and shows Retry
after the refresh wait. Configure the Ring-MQTT snapshot camera as
snapshot_entity; it supplies
the still image used behind the Last recording view because Event Select is not
a camera entity.
For Live, follow Ring-MQTT's Home Assistant Generic Camera instructions
once, using the device's _live RTSP path and its snapshot proxy as the still
image when available. Choose the resulting camera as live_entity. Ring View
then uses the same Live tab and Home Assistant player as it does for an
official Ring Live view camera. Do not enable camera stream preloading: opening
Ring View already starts the stream on demand.
For two-way audio, live_entity must be the official Ring live_view camera. A Ring-MQTT or Generic Camera RTSP entity does not expose the microphone return path Ring View needs. Ring-MQTT can still supply the optional snapshot_entity alongside the official Ring live camera.
The editor warns when two-way audio is selected for an unsupported live camera. The viewer then uses Home Assistant's normal player without Hold to talk.