framectl

README

framectl

Manage the art on a Samsung The Frame TV from the command line — discover it on the LAN, pair once, then upload, list, mirror, and run the art-mode slideshow.

[!WARNING] Unofficial. This talks to the TV's undocumented art-app WebSocket channel, reverse-engineered against one set of firmware. It can break with a firmware update. Use at your own risk.

Install

go install github.com/garyburd/framectl@latest

Quick start

Pair once (accept the prompt that appears on the TV), then drive it with the recorded data file — no -host/-name and no prompt thereafter:

framectl pair -name "The Frame 50" ~/frame.json
framectl wake ~/frame.json && framectl sync ~/frame.json ~/Pictures/frame

wake blocks until the TV is reachable and exits non-zero if it never comes up, so it gates the sync cleanly in a script.

Commands

Command	What it does
discover [-timeout d]	Stream a ip⇥name⇥mac line per TV found on the LAN (SSDP/UPnP) until interrupted.
pair (-host <ip> | -name <name>) <file>	Authorize against the TV (prompts on screen the first time) and record the connection — host/name, auth token, and MAC — in <file>.
wake <file>	Send Wake-on-LAN, then wait until the TV's control port answers.
list [-all] <file>	List photos on the TV (My Photos only; -all for every category).
gallery [-all] <file> [out.html]	Write a self-contained HTML contact sheet (thumbnails inlined as data URLs).
slideshow [-shuffle] [-category id] <file> <interval>	Run the art-mode slideshow. <interval> is off or one of the firmware's fixed durations (3m, 15m, 1h, 12h, 24h).
sync [-n] [-delete-unmanaged] [-force] <file> <dir>	Sync <dir> into My Photos: upload new/changed images, delete ones it uploaded that are gone. -n previews the plan; -delete-unmanaged makes it an exact mirror; -force re-uploads everything.
delete <file> <content-id>...	Delete photos from the TV by content id.

<file> is the data file pair writes and the others read back. The full contract — flag placement, name re-resolution, My Photos semantics — lives in the package doc:

go doc github.com/garyburd/framectl

How sync presents photos

Photos that aren't already 16:9 are rendered onto the 3840×2160 panel without cropping; the letter/pillar bars are filled automatically based on the photo content. Create a 16:9 image to avoid automatic bar fills.

Notes

• -timeout bounds only connecting (resolve + dial + handshake), never the operation, so a long sync or gallery is never cut off by a deadline. For wake it's instead how long to wait for the TV to come up.
• Ctrl-C cancels any command cleanly (exit 130).
• -debug dumps every raw message exchanged with the TV to stderr.
• Put flags before <file>: flag parsing stops at the first non-flag argument.

Documentation

Overview

Command framectl manages art on a Samsung "The Frame" TV over its undocumented art-app WebSocket channel. Its subcommands:

framectl discover                                 # stream TVs found on the LAN (SSDP/UPnP) until interrupted
framectl pair (-host <ip> | -name <name>) <file>  # authorize, record connection in data file
framectl wake <file>                              # Wake-on-LAN, then wait until the TV is reachable
framectl list <file>                              # list photos on the TV (TSV)
framectl display <file> <content-id>             # show one photo on the TV
framectl display-all <file> <interval>           # slideshow My Photos (the TV's "Display All"; off, 3m, 15m, 1h, 12h, 24h)
framectl contact-sheet <file> [out.html]          # write an HTML contact sheet (thumbnails as data URLs)
framectl upload <file> <image>...                 # upload images to "My Photos", printing each content id
framectl sync <file> <dir>                        # sync <dir> to "My Photos" (-delete-unmanaged for exact mirror)
framectl delete <file> <content-id>...            # delete photos from the TV by content id

list and contact-sheet default to the "My Photos" category (the photos uploaded to the TV); pass -all to include every category.

discover streams a tab-separated "ip<TAB>name<TAB>mac" line per device as it's found (see discover.go). pair and the commands that follow take exactly one of -host (an address) or -name (an SSDP friendly name, resolved by a discovery pass and matched case-insensitively).

pair connects to the remote-control channel, which prompts for approval on the TV the first time (accept it) and returns an auth token; pair records that token in the data file <file> along with the identifier it was given — the -name if pairing used -name (re-resolved by SSDP on each later use, so it survives the TV's address changing), otherwise the -host verbatim — plus the TV's MAC, so wake can send a Wake-on-LAN packet. list (and the other commands) read <file> and reuse the token, so they need no -host/-name and trigger no prompt:

framectl pair -name "The Frame 50" ~/data.json
framectl wake ~/data.json && framectl sync ~/data.json ~/Pictures/frame

wake powers the TV up and blocks until it's reachable, then exits 0, so it gates a sync cleanly in a script (it exits non-zero if the TV never comes up).

Put any flags before <file>: flag parsing stops at the first non-flag argument. Add -debug to dump every message exchanged with the TV.

-timeout bounds only *connecting* to the TV (resolving a -name + dial + handshake) — never the operation itself, so a long sync or contact-sheet is never cut off by a deadline. Ctrl-C cancels any command cleanly (for discover, the scan duration; without -timeout, discover watches until Ctrl-C). For wake, -timeout is instead how long to wait for the TV to become reachable.