‹ Plugin Player docs

FOR YOUR AI — Plugin Player in one page

Paste this file, or the whole docs/buyer/ folder, into your AI assistant. It then knows the app. Facts below are for Plugin Player v0.2.0 (Windows), 2026-11-04. Items marked [coming] are not built; items marked [to confirm at beta] were true at writing but not yet verified on a shipped build.

Purpose

Windows desktop app (Electron) that plays RexAffects scenes without Resolume. A scene is a self-contained generative visual with named presets and a few live sliders. The user builds an ordered show from a library, crossfades between scenes, steps presets with an 8BitDo Micro or the keyboard, outputs fullscreen to a projector, or publishes the picture to Resolume via Spout. Scenes that use a picture run on a built-in moving pattern until the webcam is turned on (V or the header's CAM chip; docs/buyer/CAMERA.md); clip (video file) input [coming]. Audio reaction [coming]. Scenes a user owns unlock on login; unowned ones carry a watermark [coming].

Folder map (what the buyer has)

Command-line flags

--scene <slug> start scene · --windowed · --size WxH render size (default 1920x1080) · --display N display index (default: first non-primary) · --show <name> load this show at boot · --cycle N auto-crossfade every N s · --secs N auto-quit · --inputlog print every gamepad event · --spout (not in the beta installer: logs "not included") · --no-window (with --spout) · --camera start with the webcam on · --camera-device <substring> pick the camera by part of its label no visible window · --spout-size WxH · --spout-fps N (≤60) · --spout-name · --spout-invert · --plate full|undocked|docked · --webgl1 (diagnostic). Log goes to the terminal, lines prefixed [renderer], [player], [spout], [shows]. Log file: %APPDATA%\rexaffects-player\logs\player.log. An installed build ignores developer/test flags (it logs [args] ignored in an installed build: …).

Controller grammar (one press, one action)

Global (grammar v4, "triggers navigate, everything else plays the scene"): L2 (Xbox LT) tap = next scene in the show (library when show empty), hold L2 + d-pad ◀ ▶ = choose previous / next scene · R2 (RT) tap = next favorite preset, double-tap R2 = previous favorite preset, hold R2 + ◀ ▶ = choose previous / next favorite, hold R2 + ▲ = save the preset (while a trigger is held the d-pad never reaches the scene) · ⊡ capture / PlayStation touchpad = tap next scene, hold ½ s previous · the d-pad, A B X Y, L, R = the playing scene's own moves (legend says what; if the scene leaves them free: X next preset, B previous preset, Y reset preset, the rest nothing) · + = tap camera IN (the input crossfades to the live camera, the scene keeps playing), hold 1 s next tab (PERFORM → MAP → CONTROLS) · − = tap camera OUT (crossfade to black by default; CAM menu: demo clip / test pattern), hold 1 s MAP tab · HUD = keyboard H · ★ = nothing (D-mode hardware). There is no scene-button setting any more. Presets: PRESETS strip shows FAVORITES (★ to add/remove; your stars replace the shipped list), ▾ opens EVERY PRESET + MINE; SAVE PRESET (Ctrl+P, hold R2 + ▲) keeps the current dials as Mine N, starred (on R2 at once) and selected, toast SAVED · MINE N; double-click the name to rename; persists; × deletes (presets saved before Oct 28 keep their My look N names); Custom Particles' word: PARAMS shelf → MAIN → CUSTOM TEXT box at the top (up to 16 letters, A–Z and spaces, digits / symbols become spaces; typing previews live and switches ASCII Source to Custom Text + Style to ASCII; Enter / click away keeps, Esc reverts, empty = YOUR TEXT); remembered per computer, spelled on every shipped preset instead of the shipped word YOUR TEXT, saved inside SAVE PRESET (loading that preset brings its word back); keyboard shortcuts and F11 are off while the box has focus; RANDOM on scenes with a random-look button (a near-black roll is re-rolled up to 4 times, moody dark rolls kept). LIGHT (keys only since Nov 9: L / K / Shift+L, 0.5–2.5×, per scene, remembered; no buttons on the monitor) lifts the picture's dark parts, not the projector levels (MAP); AUTO (on for Cube Bloom, Shift+K) is a soft floor that slowly lifts a picture too dark to read and eases back when it brightens (AUTO 1.6× while lifting). Per-scene: a playing scene may re-map A, B, X, Y, L2, R2 (never ⊡, d-pad, L, R, −, +); the footer legend and CONTROLLER card show the live meaning. Example Cube Bloom: A RANDOM PRESET, B SPIN (grouped) / BARREL ROLL, hold to keep rolling (fly-through), Y SPIN each cube ↔ whole block, L2 CLONER ↔ FLY-THROUGH, R2 INVERT (dice). Keyboard: arrows/WASD focus · Enter play · Shift+Enter add/remove from show · Delete remove show card · , / . previous/next favorite preset · Ctrl+S save the show (unnamed = SAVE AS; Ctrl+Shift+S = SAVE AS) · Ctrl+P save preset (never prints) · L / K / Shift+L LIGHT up / down / 1× · Shift+K AUTO light · X/Space next preset · Z prev · 0 reset · N/P scene · V camera on/off · [ ] fade ±0.25 s · C curve · Tab family tab · H HUD · G chrome off · F fullscreen canvas · Shift+P big plate · F1–F3 tabs · Esc quit. Controller identity in D mode: Bluetooth Wireless Controller (Vendor: 2dc8 Product: 9020); Windows device 8BitDo Micro gamepad with a child HID-compliant game controller, PID 9020. PID 9021 with no game-controller child = K mode = wrong.

On-screen vocabulary

Header: at the far left the wordmark Plugin Player ▾, a button that opens the SHOW FILE menu, with the show's name under it (• = unsaved), mode tabs PERFORM / MAP / CONTROLS (F1 F2 F3; MAP turns amber while mapping, CONTROLS orange), ⋯ right after ⧉ OUTPUT only when a chip has to fold (a narrow window), the family filters ALL/FLUID/CUBES/STACKS + ★ MINE (inert) sit in the LIBRARY row, chips OUT WxH, SPOUT NOT IN THIS BUILD, CH SCENE|FX, CAM …, CHECK <n> TO FIX|READY, REC OFF|<clock>; on a narrow window long values shorten to the prefix + dot (CHECK ●) and the least important chips move into a ⋯ N menu right after ⧉ OUTPUT, on a narrow window only (every chip's tooltip has its full text). Monitor badges: LIVE, OUT WxH, COMPILING, SHADER ERROR. PERFORM layout (default): monitor alone on the left; right column = PRESETS (top, full width), EFFECT LAYER, CONTROLLER; bottom band = SHOW strip + LIBRARY, sized so two library rows fit; TRANSITION and SCENE cards are hidden by default and come back from the VIEW menu (right-edge rail, or VIEW ▾ in the PARAMS shelf; RESET LAYOUT = this default). Every card can be dragged by its header, resized from the splitters, and the line above SHOW moves the split between them; the layout is remembered (a layout saved by an earlier version keeps its arrangement, with TRANSITION + SCENE hidden). The monitor's lower line FADE 1.20 S MIX is the quick fade control: click FADE = TRANSITION card on/off, click the curve = next curve; keys [ ] and C. Library cards: hover tooltip = title · family · N presets. PRESETS rail: numbered presets, counter −/28 → 03/28, SAVE PRESET in orange. TRANSITION card (when shown): FADE dial 0–10 s, MIX/ADD/DIP TO BLACK, CROSSFADE ON PLAY. CONTROLLER card: mini plate, legend, NO CONTROLLER (or CONNECTED · PRESS ANY BUTTON when Windows has the controller but Plugin Player has not seen a press yet), OVERLAY ON OUTPUT toggle [coming]. SCENE card (clip panel, when shown): title, family, N PRESETS · N PASSES · COMPILED N MS, description, FEATURED sliders, ALL PARAMETERS · N, A PLAY, + ADD TO SHOW / IN SHOW ✓. SHOW strip: SHOW · <NAME> · N SCENES · L2 NEXT · HOLD + ◀ ▶ CHOOSE · DRAG TO REORDER. LIBRARY: LIBRARY · 8 CARTRIDGES · … · + ADD TO SHOW ON HOVER. Footer: scene legend, <fps> FPS · WxH · PLUGIN PLAYER · V0.1.0-beta.1 · WIN.

File formats

Show file <shows>/<slug>.json (slug = name lower-cased, non-alphanumerics → -):

{ "name": "Friday Main Room", "scenes": ["plane-drift-fluid", "cube-bloom"], "fadeSecs": 1.5, "fadeCurve": 0, "updatedAt": "ISO-8601" }

fadeCurve: 0 MIX, 1 ADD, 2 DIP TO BLACK. Unknown scene slugs are dropped on load. Slider values are not stored.

Scene package (read-only to the buyer; shipped encrypted, never edit): a folder per scene with a manifest (slug, title, description, tags, presets[] {name, params}, heavy, transition.seconds, per-scene gamepad bindings), a poster image, optional hover preview. Scene internals are not documented and not needed to operate the app.

Installed scenes in the beta (slug → title → presets): cube-bloom Cube Bloom (32) · frame-stack Frame Stack (13) · fluid-force Goop (fluid dynamics; 10 favorite presets) · plane-drift-fluid Plane Drift (22) · corridor-panels Corridor Panels (12) · cube-stack Cube Stack (1) · custom-particles Custom Particles (13; opens on Data Storm) · blob-tracking-v3 Blob Tracking v3 (13) · pixel-advection Pixel Smear (5) · flashpoint Flashpoint (fire from your motion; watermarked, COMING SOON) · machine-vision Machine Vision (7; a tracking HUD over your picture, opens on Favorite Overlay) · typewriter-terrain Typewriter Terrain (26; 8 favorites, opens on Hero; a CUSTOM TEXT box spells every look). With the camera off, scenes play the demo clip (a loop of someone waving at a webcam); TEST PATTERN is in the CAM menu.

Known limits (today)

• One window for the operator. The orange ⧉ OUTPUT button sends the picture to one or more other screens at 1920×1080, no reload; a non-16:9 screen gets black bars. G = chrome off is the show mode.
• Default launch is a normal maximized window with a title bar (minimize / maximize / close); F11 toggles fullscreen, Esc leaves it. --fullscreen starts fullscreen; --windowed gives a plain window at exactly --size.
• Min spec: Windows 10/11, GPU with WebGL2 + float render targets; discrete GPU recommended. App requests high-performance GPU itself.
• First launch compiles all scenes in background; heavy ones up to ~20 s cold, in a hidden helper copy of the app (it saves them for the next launch; antivirus may ask about it). COMPILING badge while pending.
• Spout is built in, both directions, no Python: the SPOUT switch at the bottom of the ⧉ OUTPUT box (remembered on this computer, works with one screen) or --spout sends the unmapped program as the Spout sender "Plugin Player" (the button then says SPOUT ON); ⧉ INPUT › SPOUT lists every Spout sender as an input picture. SPOUT · UNAVAILABLE = the built-in Spout did not load (reinstall; send the log).
• Input: a webcam (≤ 1280×720 feed, remembered between launches), a Spout sender, a video file, or the demo clip, always switchable at the monitor (INPUT ▾ and CAMERA · SPOUT · VIDEO FILE · DEMO). Built in: mapping (MAPPING.md), REC, audio reaction (AUDIO.md), game controllers (CONTROLLER.md), MIDI / OSC (MIDI_OSC.md), and sign-in + STORE + LIBRARY (UNLOCK.md). Unowned scenes play clean on the monitor; on output they are 720p with a watermark. Owned and free scenes are 1080p, no watermark. 4K output is [coming] after the beta.
• Only one copy of Plugin Player should run at a time.
• No quit confirmation for an unsaved show [to confirm at beta].

How to answer the ten most likely questions

1. "NO CONTROLLER / controller not detected." Switch must be on D; press a button after pairing; remove K-mode pairing. → PAIRING_8BITDO.md, TROUBLESHOOTING.md rows 1–6.
2. "What does button X do?" Global table in CONTROLLER.md §3; if a scene is playing, the footer legend wins (§4).
3. "How do I get it on the projector?" Extend displays, launch, click ⧉ OUTPUT, click the screen (OUTPUT is always off at launch; the last screen is on top, marked LAST USED). --display N to force. → OUTPUT.md §1–2.
4. "Screen is black." Read the monitor badge: COMPILING = wait; SHADER ERROR = that scene fails on this GPU, play another and report SHADER INVALID line; no badge + 0 fps = restart. → TROUBLESHOOTING.md.
5. "It's slow / stuttering." Check HUD gl: line for WebGL2 and float RT, force high-performance GPU in Windows Graphics settings, lower --size, pre-play the show. → TROUBLESHOOTING.md low-fps rows.
6. "How do I save tonight's set?" Add scenes (hover → + ADD TO SHOW), Plugin Player ▾ → SAVE AS…, name, Enter. Files in %APPDATA%\rexaffects-player\shows\. → SHOWS.md §2–3.
7. "My show is gone." Plugin Player ▾ → LOAD; check the shows folder; show not found means wrong slug. → TROUBLESHOOTING.md show rows.
8. "Can I use it inside Resolume?" Yes, over Spout, both directions: turn SPOUT on and pick Plugin Player under Sources › Spout in Resolume; send Resolume back in with ⧉ INPUT › SPOUT. Buying a scene also includes its Resolume plugin (.cwired). → OUTPUT.md, UNLOCK.md.
9. "Does it react to music / my webcam?" Both. Webcam: press V or use INPUT ▾ at the monitor. Music: not yet, audio reactivity is coming in a later beta update (the ♪ AUDIO chip is gray).
10. "How do I fit the picture to the wall / fix keystone?" The MAP tab (or hold −), Y for the grid, drag or d-pad the corners (X = 1 px steps), click an edge + SOFT to fade spill, DONE · SAVE. Blends / second projector / meshes → Spout into Arena. → MAPPING.md.
11. "Windows says the installer is unsafe." SmartScreen on an unsigned installer: More info → Run anyway. → FIRST_RUN.md §2.

Do not try to explain how a scene is built or what runs inside it; describe what it does (see the family table in SHOWS.md §1) and how to drive it.