A tiny HTTP API for LG webOS Signage displays. Screenshot the panel, switch HDMI inputs, and view an external HDMI source inside the app — all over LAN, no cloud, no vendor portal.
Pack a native webOS Signage IPK that exposes a small REST API on the panel. Aimed at lab benches, kiosk fleets, CI rigs, and AI coding agents that need eyes on what an HDMI-output device is actually rendering — all without standing in front of the panel with a remote.
HTTP client (LAN) ──HTTP──▶ JS service ──IDCAP──▶ panel middleware
▲ (idcap.js Node mode) (luna://com.webos.service.idcapmw.mwcommand/callidcap)
│
port 9999
│
▼
Web app (status UI + HDMI overlay)
GET /screenshot— capture the panel's current framebuffer (JPEG/PNG, configurable resolution).POST /input— switch the panel's active a/v input (HDMI1..N, DP, OPS, …).POST /view— render any HDMI input as a fullscreen<video>inside the app, without physically switching the panel input (so the API stays alive and you can screenshot the feed).GET /input/GET /view— read current state including per-input signal-detection.GET /device— model, serial, firmware, webOS version, IDPN (useful for fleet inventory).POST /display— blank / unblank the panel with main power on (display mute), optionally auto-restoring after N minutes. The app, the API and the HDMI inputs stay up.POST /picture— set backlight / brightness / contrast, or apply anight(save + dim) /day(restore) preset.GET /display/GET /picture— read the current blanking state and picture values.GET /health— uptime, last capture, last input change, display mode, picture values.GET /— a self-contained dev control UI served straight from the service.
Full endpoint reference: docs/API.md. Driving the API from another project (or a coding-agent session) to capture HDMI output: docs/CONSUMERS.md.
Coding agents like Claude Code, Cursor, and Aider can read images. With this service running on a panel wired to your dev device, an agent working on software for an HDMI-output target — a Raspberry Pi kiosk, a NUC running signage content, a game-console homebrew app, an embedded board's UI, anything that ends in a video signal — can close its own visual feedback loop:
# Agent's tool calls, no human needed in the loop:
curl -s -X POST -H 'content-type: application/json' \
-d '{"src":"ext://hdmi:3"}' http://$PANEL:9999/view
sleep 2
curl -s "http://$PANEL:9999/screenshot?format=PNG" -o /tmp/check.png
# …then Read /tmp/check.png — modern agents see the image directly.The agent edits code, deploys, screenshots the panel, sees the result, and iterates. "I changed the layout — please tell me what's on screen" becomes a self-verifying step. docs/CONSUMERS.md is a drop-in cheat-sheet for pasting into another project's CLAUDE.md or a fresh agent session.
Why this specific tool vs. a USB capture card on the dev machine:
- The panel sees what an end user sees. What you capture is the actual production rendering pipeline, including any HDMI-handshake quirks of the real display.
- No new hardware if you already have an LG commercial display in the lab.
POST /viewdoesn't disturb the viewer — the agent can inspect HDMI3 while HDMI2 is still being shown on the panel for someone else.- LAN-only, no auth, no cloud, no API keys — drop the URL into the agent's environment and go.
- Cheap, parallel-safe-ish — ~1 capture/second sustained, plenty for an iterative agent loop. (See docs/CONSUMERS.md for measured limits.)
Working and used day-to-day for HDMI capture in a small dev lab. Verified on an LG 43UH5Q-EQ.BEUGLJP running webOS Signage 9.0.0-146. Should work on any webOS Signage 6.0+ panel where IDCAP is available.
This is a developer / lab tool: no authentication, LAN-only by design, and it installs in webOS developer mode. Do not expose port 9999 to the public internet.
- A paired LG webOS Signage display in developer mode.
- Node 20 LTS on your dev machine. ares-cli breaks on Node 22+ (
util.isDatewas removed). Pinned via.nvmrc; the build scripts auto-switch if you have nvm. - @webos-tools/cli 3.x:
npm i -g @webos-tools/cli ares-config -p signage # pick the "signage" profile ares-setup-device # pair your panel; remember the profile name
git clone https://github.com/<you>/LGLocalRemote.git
cd LGLocalRemote
# One-shot: build (if needed) + deploy by IP or DNS name.
./scripts/deploy.sh <panel-host-or-ip>
# …or, the older form: target a paired ares-cli profile by name.
export DEVICE=<your-paired-device-name> # default: "mypanel"
./scripts/build.sh # → ./com.lg.app.signage.dev_0.0.1_all.ipk
./scripts/deploy.sh # install + launch on $DEVICE
./scripts/test.sh # smoke-test /health, /input, /screenshotscripts/deploy.sh <host> looks the host up in ~/.webos/signage/novacom-devices.json (DNS-resolving to an IP if needed) and uses the first paired signage profile that matches. If no profile matches, you'll get pairing instructions — ares-setup-device once per panel, then host-based deploys work hands-off. scripts/deploy.sh POSTs /kill to the running service before re-installing, so new code takes effect on the next launch. The first ever rollout (when no /kill-capable service exists yet) needs a one-time manual reboot of the panel to clear any prior service process.
PANEL=<your-panel-host-or-ip>
# What's the panel?
curl -s http://$PANEL:9999/health | jq .
# Grab a screenshot
curl -s "http://$PANEL:9999/screenshot?format=PNG&width=1920&height=1080" -o shot.png
# Show what HDMI3 is outputting (overlay the feed inside the app, then capture)
curl -s -X POST -H 'content-type: application/json' \
-d '{"src":"ext://hdmi:3"}' http://$PANEL:9999/view
sleep 2
curl -s "http://$PANEL:9999/screenshot?format=JPEG" -o hdmi3.jpg
curl -s -X POST -H 'content-type: application/json' \
-d '{"src":null}' http://$PANEL:9999/viewFor a panel that is the HDMI sink for other devices: main power stays on, so the HDMI inputs keep presenting a connected display. Neither endpoint touches power-off, DPM, auto-standby or the 15-min-off feature.
J='content-type: application/json'
# Blank the panel (display mute); the app, the API and the input are untouched
curl -s -X POST -H "$J" -d '{"mode":"off"}' http://$PANEL:9999/display
# …or blank it and restore automatically after 10 hours
curl -s -X POST -H "$J" -d '{"mode":"off","for_minutes":600}' http://$PANEL:9999/display
# Unblank (always works, also right after a service restart)
curl -s -X POST -H "$J" -d '{"mode":"on"}' http://$PANEL:9999/display
# Dim instead: save the current backlight/brightness/contrast and go low
curl -s -X POST -H "$J" -d '{"preset":"night"}' http://$PANEL:9999/picture
# Morning: restore what "night" saved
curl -s -X POST -H "$J" -d '{"preset":"day"}' http://$PANEL:9999/picture
# Or set values directly (any subset, 0–100)
curl -s -X POST -H "$J" -d '{"backlight":30,"brightness":45}' http://$PANEL:9999/picture
curl -s http://$PANEL:9999/display; curl -s http://$PANEL:9999/pictureDetails (state persistence, error codes, overrides): docs/API.md.
Two pieces in one IPK:
- JS service (
service/) — Node-mode webOS service. Owns the HTTP listener on port 9999. Loads the IDCAP library in Node mode and calls IDCAP middleware directly for screen capture (idcap://utility/screen/capture) and input switching (idcap://externalinput/{get,set}). - Web app (
app/) — webOS web app. Mostly a thin status page; also renders a fullscreen<video src="ext://hdmi:N" type="service/webos-external" texture>overlay whenPOST /viewasks it to. Thetextureattribute is the trick that makes the external HDMI feed visible to screen capture instead of being composited on a separate hardware plane.
The web app polls the service every second via Luna (luna://com.lg.app.signage.dev.remote/ping), so the overlay reacts to POST /view within ~1s.
.
├── app/
│ ├── appinfo.json # id: com.lg.app.signage.dev
│ ├── index.html # status UI + HDMI overlay
│ ├── icon.png / largeIcon.png
│ └── js/
│ ├── webOS.js # Luna bridge for web app → service (LG-published)
│ └── idcap/idcap.js # IDCAP library, browser mode (LG-published)
├── service/
│ ├── package.json # name: com.lg.app.signage.dev.remote
│ ├── services.json # Luna service registration
│ ├── service.js # HTTP server + IDCAP calls
│ ├── index.html # dev control UI served from GET /
│ └── idcap.js # same IDCAP library, Node mode
├── scripts/
│ ├── setup.sh # no-op today (no host npm deps)
│ ├── build.sh # ares-package → *.ipk
│ ├── deploy.sh # /kill old service → ares-install → ares-launch
│ ├── test.sh # smoke-test the live HTTP API
│ └── _nvm.sh # sourced; auto-switches to .nvmrc Node version
├── docs/
│ └── API.md # HTTP endpoint spec
├── .nvmrc # pins Node 20
└── LICENSE # MIT
ares-install --device $DEVICE --list # list installed packages
ares-launch --device $DEVICE --close com.lg.app.signage.dev # stop app (doesn't stop service)
ares-inspect --device $DEVICE --app com.lg.app.signage.dev # Chrome DevTools on the web app
ares-inspect --device $DEVICE --service com.lg.app.signage.dev.remote # Node inspector on the service- JS services with open TCP listeners never idle out on webOS Signage — use the
POST /killendpoint or reboot to free the port.scripts/deploy.shhandles this for you. - Switching the panel's physical input via
POST /inputkills the custom SI app until it's relaunched (or until you register it as the panel's SI app). PreferPOST /viewfor capture, which keeps the panel in SI mode and the API alive. - HDCP-protected HDMI content cannot be captured. External HDMI from a protected source comes back black or returns an IDCAP error. For DIY devices (Pi, NUC, ESP32) HDCP is off by default.
- FHD capture + JPEG read round-trip takes ~1–3 s. IDCAP middleware deduplicates in-flight requests, so concurrent screenshot calls return duplicate frames. Keep captures serial.
- Dev-installed IPKs don't appear as Smart Home tiles — normal in dev mode.
ares-clion the signage profile lacksares-shell,ares-device -i, andares-log— quirks of the signage profile vs the TV profile.
webOS Signage developer mode whitelists exactly one app id for sideload-installable apps: com.lg.app.signage.dev. Trying to install any other id fails with Can install only 'com.lg.app.signage.dev' app on developer mode. The id sitting in com.lg.* looks like it's claiming LG's reverse-DNS namespace, but it's just LG's own dev-mode magic id — we're not free to pick our own here.
Outside developer mode you'd drop the .dev suffix and use your own app id.
This repo ships in webOS dev mode: dev-mode-reserved app id, and a POST /kill endpoint that's only intended for local development. Before any production / customer-facing deployment you should at minimum:
- Drop the
POST /killendpoint fromservice/service.js. - Add authentication or a network-level allowlist in front of port 9999.
- Move off developer mode: install the IPK through LG's regular install procedure (there is no signing step) so it doesn't depend on dev-mode renewal, can be registered as the panel's SI app (so it persists across HDMI input switches), and can use your own app id instead of
com.lg.app.signage.dev.
app/js/webOS.jsandapp/js/idcap/idcap.jsare publicly-distributed LG libraries, included here for convenience. Original sources:- webOS Signage JS:
https://res.cloudinary.com/dcsdn4mzr/raw/upload/v1689918830/webOS-Signage/assets/library/guide/webOS.zip - IDCAP JS extension:
https://res.cloudinary.com/dcsdn4mzr/raw/upload/v1/webOS-Signage/assets/library/apis/IDCAP_DOC_PORTABLE.zip
- webOS Signage JS:
- LG and webOS are trademarks of LG Electronics, Inc. This project is not affiliated with or endorsed by LG.
MIT — the project's own code (everything under app/ except app/js/, all of service/ except service/idcap.js, all of scripts/, and docs/). The bundled LG libraries listed under Acknowledgments are © LG Electronics, redistributed under LG's original terms.