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 — so you can script, automate, or build your own controllers and apps.
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/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}.
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 |
accel_invert | bool | Invert accelerometer axis |
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).
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).
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.