Samsung Tizen
Use the @agent-device/tizen plugin to drive web apps on Samsung Tizen TVs. The plugin
debug-launches the app over sdb, forwards its DevTools port, and drives the page over the Chrome
DevTools Protocol (CDP): remote keys, pointer, text, snapshots, screenshots, and console logs.
The plugin is experimental. The commands it admits are listed in How commands map to the TV.
Requirements
sdbfrom the Tizen SDK of the VS Code Tizen extension, set up with its Set Up step. The plugin finds it in the SDK that$TIZEN_SDKor~/.tizen.path.confignames.sdbis not onPATH; to point at it directly, set thesdbPathplugin option.- The TV in Developer Mode with this host’s IP set as the developer IP. To set this up, follow Samsung’s Connecting the TV and SDK.
- The app installed on the TV from a debug-enabled package.
- The TV and this host on the same network.
Install the plugin
agent-device plugins add @agent-device/tizenThe plugin is an optional npm package installed under AGENT_DEVICE_HOME.
After you add or update it, close open sessions and run agent-device daemon stop
with the state directory you use; the next device command loads the plugin.
Plugin options, set under plugins["@agent-device/tizen"].options in config.json:
| Option | Meaning |
|---|---|
sdbPath |
Path to sdb, when the Tizen SDK is not found. |
device |
TV IP or sdb serial to drive when connect names none. Defaults to the only TV connected to sdb. |
Connect and run a session
export AGENT_DEVICE_SESSION=checkout-tvagent-device connect tizen --device 192.0.2.10agent-device open com.example.appagent-device wait text "Home"agent-device tv-remote press downagent-device snapshot -iagent-device screenshot ./tv.pngagent-device logs startagent-device close com.example.appagent-device disconnectThe TV is a leased device, so every command from connect to disconnect names its session with
AGENT_DEVICE_SESSION, --session <name>, or a config session. Without one, the command fails with
REMOTE_SESSION_REQUIRED.
--device takes the TV IP or an sdb serial. When the TV is not connected to sdb yet, the
plugin runs sdb connect <ip>:26101. Without --device, the plugin uses the device option,
then the only TV connected to sdb. connect does not contact the TV; open connects it.
agent-device leases only iOS, Android, and HarmonyOS devices, so a Tizen TV enters as an Android
TV device that the plugin owns (platform: android, target: tv, id tizen:<sdb serial>).
Every command on that device goes to the plugin, never to adb.
How commands map to the TV
| Command | How |
|---|---|
open / close |
sdb shell 0 was_kill, sdb shell 0 debug, and sdb forward, then CDP / sdb shell 0 was_kill |
tv-remote press up/down/left/right/select/back, back |
Input.dispatchKeyEvent with the Samsung remote codes |
tv-remote press media-play/media-pause/media-play-pause/media-stop/media-next/media-previous/media-rewind/media-fast-forward |
Input.dispatchKeyEvent with the Samsung media key codes |
appstate |
The attached app while its page is visible |
apps |
sdb shell 0 vd_applist |
logs |
Console calls, exceptions, and browser log entries of the attached page, one line each |
snapshot, find, is, get, wait |
A DOM walk over Runtime.evaluate: visible interactive, labelled, or text nodes, with focus from document.activeElement. -s, -d, and -i apply to the walk. |
screenshot |
Page.captureScreenshot. --crop-on <selector> crops the capture to the frame of the node that the selector resolves in a snapshot taken on the same screen. |
click, press <x> <y>, longpress, hover |
Input.dispatchMouseEvent |
fill |
Pointer press on the field, select its contents, then Input.insertText, or Backspace for an empty value |
type |
Input.insertText into the focused element |
scroll |
mouseWheel at the centre of the scroll container or the viewport, by the requested distance |
Not supported yet: system buttons (home, menu, volume, and channel), network dump, perf,
install and uninstall, recording, URLs and deep links in open, and power.
Known limitations
openis always a cold start:sdb shell 0 debugcannot attach to a running app, soopenkills it first.opencan return before the app leaves its splash screen; wait for app content before the first snapshot.- Idle leases expire after 60 seconds by default, and expiry ends the session. When the lease
ends, by
disconnector by expiry, the plugin closes the page connection and removes thesdbforward. The next command then fails withLease is not activeorNo active sessionand needs a newconnectandopen. To keep longer pauses alive, runagent-device daemon stop, then start the daemon withAGENT_DEVICE_LEASE_TTL_MSandAGENT_DEVICE_LEASE_MAX_TTL_MSset, for example1800000. screenshotcaptures the app page, not the TV screen. When the app is in the background, the page renders no frames, soscreenshotfails;open <appId>brings the app back. While the on-screen keyboard is open, the page viewport and the screenshot are shorter. System layers such as the Samsung menu never appear inscreenshotorsnapshot.appstateknows only the attached app. The TV reports no foreground app that the plugin can read.- Console messages logged before the attach are replayed without object previews.
- A second DevTools client on the same page can hang the session. Close Chrome DevTools and other inspector clients attached to the app first.
- Snapshots are read from the DOM. Labels come from
aria-label,alt,title, or own text. Rects are CSS pixels. The screenshot magnifies them by the page’svisualViewport.scale: awidth=1280meta viewport on a 1920x1080 TV gives 1.5.screenshot --crop-onapplies that scale, and refuses a page whose browser has novisualViewportor whose visual viewport is panned.screenshot --overlay-refsdraws ref boxes at the same scale; without one it draws them 1:1. The walk does not enter iframes or shadow roots.