远程控制与 API

From the network: web viewer + REST API#

Utility → Remote → Web Server switches on a web server for the whole app:

• Web viewer: Open the address shown under Status (http://<mac>:8090/) in any browser on the network: the Viewer window's deck strips (scrolling wave, beat grid, structure + phrase bands, hot cues, cue-list cues and highlights, loop, info row, overview) and its info deck, live. Zoom (+ / −, pinch, Ctrl-wheel) and REMAIN/TIME (click the time) are local to that browser; click the zoom readout to follow the Viewer node again.
• Web pages: The top bar switches between VIEWER (the deck strips and info deck), BOOTH (the DJ-booth screen: clock, what's on now with a progress bar, a big countdown to the next scheduled item, the run of the day (it follows the Program window), LIVE (the Live window's router strips with the meter column, timecode, BPM / TEMPO / ON AIR and the input buttons) a tap switches the router), CUE LIST (what fires next, with progress), DATA (play history) and REMOTE: A control surface built from the show itself,

every router's inputs and every matrix's presets as one-tap buttons, then every node and every app setting with its parameters as controls (a change is the same as editing it in the inspector), plus BYPASS / STOP / FIRE. REMOTE needs Allow Remote Control and an Access Token; without them the REMOTE button and page are hidden. A page opened on a protected server shows a sign-in page: enter the token once and that device stays signed in (UTILITY → Sign Out ends it). The pages carry the app's own top strip (TC Supply / SHOWKONTROL logos, the switch-screen icon at the right = full screen) and the UTILITY button (top right) shares the server as a QR code, copies the link, zooms and goes full screen; pages go full screen on the first tap anyway. Every page carries the app's six side buttons (left column; a row under the top bar on phones): the top row is DATA · VIEWER · LIVE · MASTER (· REMOTE), the side buttons pick a page's views, MASTER > CUE LIST / BOOTH, DATA > PLAY LOG / INSIGHTS / MIXER (the DJM's face live: knobs, faders, meters, crossfader) / STATUS (health of the decks: the link, and per player how regularly it reported over the last 60 s with model, interface and what it is doing). The Web Server page in Utility shows the same QR code under Scan to Open. On a Mac with several network adapters, Interface picks whose address goes into the QR code, Open in Browser, the Status line and the Share link (Auto = the first real IPv4); the server listens on every adapter regardless.

• Notifications: The Notify action (Application category, next to Beep and Flash Screen): a title and message with $VARIABLES, a priority (normal / high / urgent) and two roads: a card on every open web page (tablets, phones, screens showing the viewer, with a sound; urgent pulses red) and a push to phones through ntfy, which reaches a locked phone. For the push: Utility → Web Server → Push Notifications, switch on, keep ntfy.sh or enter your own ntfy server, choose a long random topic, then install the ntfy app on each phone and subscribe to that topic. Send Test Notification checks both roads. Anything with the token can also raise a page card over the API (POST /api/v1/notify).
• REST API under /api/v1, live state as an event stream or JSON, deck data frames, waveforms, beat grids, artwork, application settings, and every node parameter (read, and with Allow Remote Control + an Access Token: Write). Full contract: REST_API.md in the project folder.

curl http://10.0.0.5:8090/api/v1/state
curl -H "Authorization: Bearer $TOKEN" -X PUT -d '{"value":"Input 2"}' \
     http://10.0.0.5:8090/api/v1/nodes/Deck%20Router/params/router.active

The web server runs alongside ShowKontrol, so the number of viewers, slow Wi-Fi or a busy API client can never cost the show a frame. Different from the HTTP output node (§8), which serves ONE node's frame from inside the Patch.

Stream Deck#

An Elgato Stream Deck plugin (keys and Stream Deck + dials) that shows and controls the show. It is a client of the Web Server above, the server must be on; the keys cost the show nothing beyond what a browser does.

Install: Utility → Remote → Stream Deck → Install Stream Deck Plugin (the Stream Deck app asks, then installs it, needs Stream Deck 7.1 or newer). The ShowKontrol keys are then in the Stream Deck actions list under ShowKontrol.

Connecting: On the ShowKontrol Mac itself nothing needs typing, with Pair Plugins on This Mac on (default), the plugin connects by itself (also when the port or token change). For a Stream Deck on another computer: open any ShowKontrol key's settings → the connection line at the top → On another computer → host / port / Access Token. The dot on that line is green (connected, remote control allowed), amber (read-only: Allow Remote Control is off) or red. Keys that change the show need Allow Remote Control and an Access Token, like the web REMOTE page.

A key that cannot do its job says so for a moment: NO CONTROL (remote control is off), TOKEN?, NOT FOUND (node renamed / deleted), BUSY (the server's 40 requests/s limit). Keys pick nodes by id, so renaming a node does not break them.