Skip to content

janstrm/Home-Assistant-Samsung-Frame-Art-Director-Integration

BranchesTags

Repository files navigation

Samsung Frame Art Director

🖼️ Samsung Frame Art Director

A Custom Integration for Home Assistant to control Samsung Frame TV Art Mode.

hacs_badge License: MIT

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

Control your Samsung Frame TV's Art Mode directly from Home Assistant. Upload local images with automatic resizing, rotate art on a schedule, manage TV storage, and build gallery dashboards. Optionally integrates with Google Gemini to auto-tag images dropped into an inbox folder.

📋 Prerequisites

  • Home Assistant (Core, Supervised, or OS)
  • HACS (Home Assistant Community Store) installed.
  • A Samsung Frame TV connected to the same local network.
  • (Optional) A Google Gemini API Key for automatic image tagging.

✨ Capabilities

  • State Verification: Toggles Art Mode ON/OFF and verifies the state to ensure the screen displays art rather than just being powered down.
  • Local Uploads: Upload local images directly to the TV. Images are resized to 3840×2160 before upload (choose crop to fill or fit to letterbox in the options).
  • Auto-Tagging (Optional): Drop images into an inbox folder and run Process Inbox — Gemini analyzes, tags, and catalogs them to your local library.
  • Gallery Sensor: Exposes a database of your local art, allowing you to build dashboard views with the provided example YAML.
  • Media Browser: Browse your tagged library in Home Assistant's Media panel and "play" any image to the Frame (it uploads and displays it).
  • Auto-Rotation: Rotates art from local storage or limits selection based on assigned tags, favorites, and filters.
  • Favorites: Mark individual artworks as favorites. Filter the gallery or rotation to only use your favorite pieces.
  • Storage Management: Detects and deletes orphaned or un-favorited artworks from the TV memory to manage limited storage capacity.

🚀 Installation

Method 1: HACS (Recommended)

  1. Open HACS in Home Assistant.
  2. Go to Integrations -> Click the 3-dots in the top right -> Custom repositories.
  3. Add https://github.com/janstrm/Home-Assistant-Samsung-Frame-Art-Director-Integration as an Integration.
  4. Click Install and restart Home Assistant.

Method 2: Manual

  1. Download this repository.
  2. Copy the custom_components/samsung_frame_art_director/ folder into your Home Assistant /config/custom_components/ directory.
  3. Restart Home Assistant.

⚙️ Configuration

If your TV is on, it is usually auto-discovered — look for "Samsung Frame Art Director" under Settings → Devices & Services and click Configure to set it up. Otherwise add it manually from Add Integration and search for "Samsung Frame Art Director".

Initial Setup

  • You will be asked for the TV's IP address and a Name (pre-filled when discovered).
  • Follow the prompt on your TV to "Allow" the connection.
  • If the TV's IP later changes, use Reconfigure on the integration to update it (no need to delete and re-add); discovery also updates it automatically.

Options Flow (Configure)

Nothing here is required — the integration works out of the box after pairing. Click Configure to adjust optional settings, grouped into collapsible sections:

  • AI Image Tagging: Add a Gemini (or OpenAI) API key to enable Process Inbox / Sync Library auto-tagging. This is the only thing most users will set.
  • Storage Cleanup: Max items / age to keep on the TV, preserve-current, dry-run.
  • Folders & Image: Inbox/library folder paths and the image fit mode (crop vs. fit/letterbox).
  • Connection & Power: Wake-on-LAN MAC and power-key fallback.
  • Advanced: AI model override and verbose logging.

Slideshow, matte and favorites are controlled by their own entities (switches/selects/number/text), not this dialog — so you can drive them from dashboards and automations.

📂 Folder Structure

The integration uses two folders on your HA filesystem:

Folder Purpose
/media/frame/inbox Drop new images here. Process Inbox will analyze, tag, and move them to the library.
/media/frame/library Permanent storage for processed images. Used by rotation and the gallery sensor.

Workflow

  1. Drop images into /media/frame/inbox/
  2. Run Process Inbox → Gemini tags each image, then moves it to /media/frame/library/
  3. Images appear in the Gallery sensor and are available for rotation
  4. If you add images directly to /media/frame/library/, run Sync Library to tag and register them

🖥️ Dashboard Example (UI)

We provide a ready-to-use Dashboard YAML that combines the TV controls and the Art Gallery into a beautiful 3-column frontend view.

You can find the code here: examples/dashboard.yaml

To use the Art Gallery with popups, you will need these HACS frontend plugins:

  1. auto-entities (For the dynamic image gallery grid)
  2. browser_mod (For clicking an image to open the Push/Favorite/Delete popup)
  3. card-mod (Optional) (For visual enhancements like favorite indicators)

Simply create a new Dashboard View in Home Assistant, click Edit (Raw Configuration), and paste the contents of the example file! Home Assistant will automatically arrange the 3 columns on wide screens.

🧪 Testing dashboard (no extra plugins)

For exercising every entity and service from one screen — using only built‑in Lovelace cards (no HACS frontend plugins) — paste examples/testing_dashboard.yaml into a new dashboard's Raw configuration. It surfaces the art preview, Art Mode toggle, brightness/color/motion settings, matte, slideshow, the library sensor, a media‑control card to browse + play to the Frame, and buttons for rotate / process inbox / sync / cleanup / diagnostics / purge.

Entity IDs in both examples assume the prefix samsung_frame. If your device uses a different prefix (e.g. 65_the_frame_…), find‑replace it (check Developer Tools → States).

🎮 Services

Domain: samsung_frame_art_director

Core Services

set_artmode

Toggle Art Mode on or off.

service: samsung_frame_art_director.set_artmode
target:
  entity_id: media_player.samsung_frame
data:
  enabled: true

upload_art

Upload and immediately display an image from your HA filesystem.

service: samsung_frame_art_director.upload_art
target:
  entity_id: media_player.samsung_frame
data:
  path: /media/frame/library/example.jpg

(Paths must reside in /media or /config for security).

rotate_art_now

Force an immediate rotation of the displayed art. Picks a random image from the library (optionally filtered by tags). Automatically retries if a selected image no longer exists on disk.

service: samsung_frame_art_director.rotate_art_now
target:
  entity_id: media_player.samsung_frame
data:
  source: library       # library | folder
  tags: "nature, ocean" # Optional: only rotate images matching these tags
  match_all: false      # Optional: require ALL tags to match (default: any)

rotate_favorites

Rotate art but only pick from images marked as favorites.

service: samsung_frame_art_director.rotate_favorites
target:
  entity_id: media_player.samsung_frame

Library Services

process_inbox

Scan /media/frame/inbox, analyze each image with Gemini, move to /media/frame/library, and register in the database with tags.

service: samsung_frame_art_director.process_inbox

Note: Requires a Gemini API key in the integration options. If rate-limited (HTTP 429), processing pauses and logs how many images were completed.

sync_library

Full bidirectional sync of the library database:

  1. Deduplicates the database (removes duplicate entries, keeps newest)
  2. Removes stale entries — DB records whose files no longer exist on disk
  3. Adds untracked images — files in /media/frame/library/ not yet in the DB (tagged via Gemini AI)
service: samsung_frame_art_director.sync_library

Note: Phases 1 & 2 (cleanup) always run, even without a Gemini key. Phase 3 (adding new images) requires the API key.

purge_database

Wipe the local SQLite database (art history, tags, favorites). Does NOT delete image files from /media/frame/library/.

service: samsung_frame_art_director.purge_database

Tip: After purging, run Sync Library to re-scan and re-tag your existing images.

Gallery Management Services

toggle_favorite

Toggle the favorite status of an artwork in the library database.

service: samsung_frame_art_director.toggle_favorite
data:
  content_id: "MY-C0002_xxxxxxxx"

delete_art

Delete an artwork from the library database.

service: samsung_frame_art_director.delete_art
data:
  content_id: "MY-C0002_xxxxxxxx"

cleanup_storage

Remove non-favorite artworks from the TV's internal storage to free up space.

service: samsung_frame_art_director.cleanup_storage
target:
  entity_id: media_player.samsung_frame
data:
  max_items: 50                  # Optional: keep at most N items
  max_age_days: 30               # Optional: delete items older than N days
  preserve_current: true         # Optional: don't delete the currently displayed artwork
  only_integration_managed: true # Optional: only delete items tracked by this integration
  dry_run: false                 # Optional: preview what would be deleted without actually deleting

Diagnostics

art_diagnostics

Log Art Mode support status, current artwork, and a sample of available content IDs (useful for debugging).

service: samsung_frame_art_director.art_diagnostics
target:
  entity_id: media_player.samsung_frame

📊 Entities

When configured, the integration creates the following entities (where samsung_frame is your configured device name):

Media Player

Entity Description
media_player.samsung_frame Main control entity. State reflects Art Mode. Attributes include art_mode_status and the current content_id. Supports browse/play from the Media panel.

Image

Entity Description
image.samsung_frame_art_preview Live preview of the currently displayed artwork on the Frame TV.

Switches

Entity Description
switch.samsung_frame_slideshow_enabled Enable/disable automatic art rotation.
switch.samsung_frame_gallery_favorites_only Restrict the gallery and rotation to only favorited images.
switch.samsung_frame_auto_brightness Art Mode auto-brightness (the TV's light sensor).

Select Entities

Entity Description
select.samsung_frame_slideshow_source Choose rotation source: Library, Folder, or Tags.
select.samsung_frame_matte_style Matte (border) style: none, modern, shadowbox, flexible, etc. Set to none to disable the matte.
select.samsung_frame_matte_color Matte (border) color: polar, apricot, navy, etc. Combined with the style as {style}_{color} (e.g. shadowbox_polar). Ignored when style is none.
select.samsung_frame_motion_timer Art Mode motion auto-off timer: off, 5, 15, 30, 60, 120, 240 (minutes).

Number Entities

Entity Description
number.samsung_frame_slideshow_interval Custom rotation interval in minutes (0–1440).
number.samsung_frame_art_mode_brightness Art Mode brightness (0–10).
number.samsung_frame_art_mode_color_temperature Art Mode color temperature (−5…5).
number.samsung_frame_motion_sensitivity Art Mode motion-sensor sensitivity (1–3).

Text Entities

Entity Description
text.samsung_frame_slideshow_filter Free-text filter for tags or folder path used by rotation.

Sensors

Entity Description
sensor.samsung_frame_art_library Reports total tracked artworks. Attributes include the full items list for dashboard gallery rendering.

🔔 Events

The integration fires an event whenever the displayed artwork changes (upload or rotation), so you can build automations off it:

trigger:
  - platform: event
    event_type: samsung_frame_art_director_art_changed
# event.data: { host: "<tv ip>", content_id: "<id or path>" }

🛠️ Troubleshooting

Problem Solution
Art uploads stall or fail Ensure the TV is paired. Try turning on manually and watching for permission popups.
"No Gemini API key" warning Add your API key in Settings → Devices → Samsung Frame Art Director → Configure.
"Local file missing" warnings during rotation Run Purge Database then Sync Library to clean up stale entries.
Gallery shows no images Ensure images exist in /media/frame/library/ and run Sync Library.
Rate limit (429) during inbox processing Gemini free tier has request limits. Wait a few minutes and try again.

Check HA logs filtered by samsung_frame_art_director for detailed error messages.

Note

Art‑Mode settings (brightness, color temperature, motion, auto‑brightness) show unknown / don't apply. These features exist only in the NickWaterton samsungtvws fork that this integration pins. If another integration (e.g. Home Assistant's built‑in Samsung Smart TV) already installed the official samsungtvws from PyPI, HA keeps that version and ignores the pin — so those extra settings won't work. They're therefore hidden by default; enable Show Art‑Mode setting entities under the integration's options → Advanced (and reload) only if you have the fork. Everything else (Art Mode on/off, uploads, slideshow, matte, gallery, Media browser) works on either version. Check the installed version in the logs at startup (samsungtvws package version: …).

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

Working on the code? See CONTRIBUTING.md for dev setup and checks, and read ARCHITECTURE.md first — it explains the module layout, the SQLite data model, the key control flows, and (importantly) why the TV-API fallback logic exists before you refactor it.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Warning

TV Model Compatibility Samsung's internal Art Mode APIs vary significantly between different models and production years. This integration has been primarily developed, tested, and confirmed working on model Samsung The Frame Q65LS03DAU. Your mileage may vary on older or newer models.

Disclaimer: Not affiliated with Samsung. Uses the internal WebSockets API of Frame TVs.

About

Home Assistant integration to control & automate Samsung The Frame Art Mode — local uploads, AI tagging, slideshow, and a gallery dashboard.

Topics

tizen home-assistant homeassistant hacs custom-integration tizen-tv samsung-frame samsung-frame-tv art-mode

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

3 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases 1

v1.9.8 Latest
May 31, 2026

Packages

 
 
 

Contributors

Languages