Lucent Cube — Local API

The Lucent Cube runs an HTTP service (cubed) on your local network. Everything the companion app does is available over this open, JSON API — playback, settings, playlists, the parameters of any running app, casting, emulators, shaders and smart-home — so you can script, automate, or build your own controllers and apps. The cube also speaks Art-Net and sACN for lighting rigs.

cubed v1.0.0

Basics

Calls go to your cube on your LAN. Responses are JSON; errors return a non-2xx status with {"error":"…"}.

Item	Value
Base URL	`http://<cube-ip>:8000` (port configurable)
Format	JSON request bodies and responses
CORS	Open (`Access-Control-Allow-Origin: *`) — callable from browser apps
Auth	None — access is scoped to your local network

curl http://<cube-ip>:8000/status
curl -X POST http://<cube-ip>:8000/brightness -d '{"brightness":60}'

SystemService info and device state

GET/

Service identity — {"service":"cubed","version":"1.0.0"}.

GET/status

Current playback state (what's showing, playlist position, mode).

GET/battery

Battery telemetry: voltage, soc, temp_c, chip, psu_present (or null values + error if no reading yet).

PlaybackShow content and control the display

POST/play

Play one or more images/clips.

Field	Type	Notes
`images`	string or string[]	Required. A path/glob, or an array of them.
`brightness`	number	Optional. Omit to keep current.
`random`	bool / 0–1	Optional. Shuffle the set.

POST/stop

Stop playback.

POST/play/skip

Skip within the current playlist. Body: offset (int, default 1; negatives go back).

POST/brightness

Set display brightness. Body: brightness (required).

POST/reset-horizon

Capture the current orientation as "level" for the accelerometer-driven horizon. Returns {"ok":true}.

POST/boot-anim

Play a boot animation on demand. Body: which — welcome or wifi.

SettingsLive configuration

GET/settings

Read all current settings.

POST/settings

Update any subset of fields; returns the updated settings. Common fields:

Field	Range	Meaning
`brightness`	0–100	Display brightness (%)
`transition_ms`	0–10000	Crossfade/transition duration
`crossfade`	bool	Enable crossfade between items
`seconds_per_entry`	0–3600	Dwell time per playlist item
`pingpong`	bool	Bounce playlists instead of looping
`face_mask`	0–63	Bitmask of active faces
`cub_display_mode`	0–2	Standard / Vertex / Flat wrap
`ar_mode` · `ar_intensity`	—	Audio-reactivity mode and strength
`audio_gain` · `audio_noise_gate`	—	Audio input tuning
`viz_mode`	-1–999	Active visualiser (-1 = off/auto)
`viz_gain_bass` · `_lowmid` · `_highmid` · `_highs`	—	Per-band visualiser gain
`viz_cube_mode`	0–3	How a visualiser maps across faces
`viz_cycle_secs`	0–3600	Auto-cycle interval for visualisers
`viz_text`	string	Typography visualiser's display text
`accel_invert`	bool	Invert accelerometer axis
`volume` · `volume_precise`	0–100	Output volume (coarse / fine)
`sound_mono`	bool	Downmix game/app SFX to mono
`boot_anim`	bool	Play the boot animation on startup
`startup`	string	Name of the app/game to launch on boot
`startup_schedule_enabled`	bool	Restrict the startup app to a daily time window
`startup_from_min` · `startup_to_min`	0–1439	Window start/end, minutes since midnight
`led_rgb_sequence`	string	Panel colour-channel order (e.g. `BGR`)
`game_difficulty`	int	Default difficulty for games that support it
`audio_device`	string	ALSA capture device for audio-reactivity

Content catalogDiscover and launch what's installed

GET/visualisations

List built-in visualisers: index, name, description, tags, date_added.

GET/games

List games: name, path, description, tags, thumbnail, type, date_added.

GET/apps

List installed apps (same shape as games).

POST/launch

Launch a game/app. Body: name and/or path (name is resolved against games then apps).

POST/viz-sequence

Play a sequence of visualiser modes. Body: modes (int[], required), random (optional).

App parametersDrive any app's controls from your own code

Apps declare their own controls (sliders, toggles, selects, buttons) and can publish live values back. This is the same channel the companion's settings pages use, so anything you can change by hand you can change from a script — including the DMX app, Orbi, Aquarium and the rest.

GET/app-params

The running app's parameter state: app (empty if the current activity has no controls), launch_seq, plus controls and status arrays. Each slot carries:

Field	Meaning
`id`	Control id, as used by `/app-param`
`kind`	1 trigger · 2 bool · 3 int/select · 4 float/slider · 5 string/label
`int` · `float` · `text`	Current value, by kind
`trigger_seq`	Increments each time a button fires

status holds values the app publishes back — live readouts rather than settings.

POST/app-param

Set one control on the running app. Body needs id plus a value. Use value and the cube coerces it to the control's declared type, or name the type explicitly:

Field	Type	Notes
`id`	string	Required. Must match a control on the running app.
`value`	any	Coerced to the control's kind. Easiest option.
`bool` · `int` · `float` · `text`	typed	Explicit alternatives to `value`.
`trigger`	any	Presence fires a button control.

# what can I change on whatever is running?
curl http://<cube-ip>:8000/app-params

# put the DMX app into 16x16 pixel mode, then run a demo look
curl -X POST http://<cube-ip>:8000/app-param -d '{"id":"mode","value":3}'
curl -X POST http://<cube-ip>:8000/app-param -d '{"id":"testpat","value":15}'

POST/app-image

Push a raw RGB image to the running app (photo frame, drawing). Query: w, h (16–512, default 256×192); pixel data in the body.

GET/app-photos

How many photos are stored for the photo app — {"count":n}.

Library & uploadsManage media on the cube

GET/library

List media. Query: images (required path/glob); optional thumbnails via thumb_frame, thumb_size (max 128), thumb_block (0 standard / 1 vertex / 2 flat).

POST/upload

Chunked file upload (parameters via query string, data in the body).

POST/upload-abort

Discard an interrupted upload. Body: filename (required).

POST/prune-uploads

Remove leftover temp files from interrupted uploads.

POSTDELETE/delete

Delete one file. Body: path (required).

POST/delete-many

Delete multiple files. Body: paths (string[], required).

PlaylistsCreate and play sequences

GET/playlists

List playlists (optional thumbnail params as on /library).

GET/playlists/get

Get one playlist. Query: id (required).

POST/playlists/save

Create/update a playlist. Body: id, name, type, items (string[]), action (default set).

POST/playlists/play

Play a playlist. Body: id (required), random (optional).

POST/playlists/delete

Delete a playlist. Body: id (required).

Emulators & shadersRetro systems and user-written GLSL

The cube serves two of its own browser UIs — /roms (ROM manager) and /shaders (shader editor). Both return HTML, not JSON; the endpoints below are the JSON API behind them.

GET/roms-list

Installed ROMs per emulated system. Optional query system to filter to one.

POST/rom-fetch

Download a ROM straight to the cube. Body: system, url (http/https only).

POST/rom-upload

Upload a ROM. Query: system, name (extension must match the system); file in the body.

POST/rom-delete

Delete a ROM. Body: system, file.

GET/shader-files

List uploaded fragment shaders.

GET/shader-content

Source of one shader as text/plain. Query: name.

POST/shader-upload

Upload a shader. Query: name (must end .frag); GLSL in the body, 64 KB max.

POST/shader-delete

Delete a shader. Body: file.

Audio & castingStreaming receivers and Bluetooth output

GETPOST/cast-background

Whether each receiver (receiver, spotify, airplay, youtube) keeps advertising in the background. POST body: app, enabled.

POST/cast-autostart

Whether a receiver launches automatically when a device connects. Body: app, enabled.

GETPOST/cast-eq

Four-band EQ applied to streamed audio. POST any of bass, lowmid, highmid, treble.

POST/cast-release

Body: released. When true, drops live cast sessions and stops advertising — how "off" is made to stick.

GETPOST/bt-output

Send the cube's audio to a paired Bluetooth speaker. POST body: enabled, mac, name.

GETPOST/bt-output/scan

POST starts a scan; GET returns discovered devices.

POST/bt-output/forget

Forget a paired speaker. Body: mac.

Smart homeAlexa, Google Home and Apple Home over Matter

The cube can appear as a Matter device on your local network — no cloud, no account linking, no skill to enable.

GET/smarthome

Bridge state — {"enabled":bool,"control_port":8090}.

POST/smarthome/enable

Turn the bridge on or off (persists across reboots). Body: enabled.

GETPOST/smarthome/exposed

Which playlists and apps are exposed as individually voice-addressable devices. Opt-in, so a large library doesn't flood your assistant.

Controllers & inputGamepads, and driving games from code

POST/gamepad-event

Broadcast an event to connected gamepad clients. Body: event (string, 24 chars max). Lets your own code stand in for a controller.

GET/bt/controllers

How many Bluetooth controllers are connected — {"count":n}.

POST/bt/pair

Start a 45-second controller pairing scan. Returns immediately; poll for progress.

GET/bt/pair-status

Progress of the current pairing attempt, plus the live controller count.

Beyond HTTP — DMXArt-Net and sACN, for lighting rigs

The cube also speaks the lighting industry's own protocols, which are not part of this HTTP API. Run the DMX app and the cube listens for Art-Net (UDP 6454) and sACN / E1.31 (UDP 5568), so any lighting console or media server can drive it — as a fixture with a 21-channel personality, as six colour zones, or as a pixel-mapped display up to 32×32 per face. It answers Art-Net polls, so it appears by name in a console's node list. Configure it from the app's own settings page; there is nothing to set up here.

Device & hardwareAdvanced — changes restart the renderer

GETPOST/admin

Read or update low-level LED init. GET reports current values plus the detected hw_model. POST fields (all trigger a renderer restart):

Field	Range	Meaning
`led_slowdown_gpio`	0–4 (-1 = auto)	GPIO timing for the panel chain
`led_pwm_bits`	1–11	Colour depth vs refresh trade-off
`render_cpu`	-1–3	CPU core pinning for the render thread
`rt_priority`	1–99	Real-time scheduling priority
`enable_thread_pinning`	bool	Pin render thread to a core

Note: This is the cube's on-device control API, served on your local network — designed for owners scripting their own cube, home-automation integrations, and custom controllers. The hardware & coordinate model for writing native pixel apps is in the hardware & development reference. Questions? info@lucentcube.com.