Pixelcade API Documentation
Welcome to the API reference for Pixelcade LED marquee displays, Pixelcade LCD systems, and Pixelcade Pulse WS2812B devices and sub-display controllers. This REST API allows you to control your Pixelcade devices programmatically, displaying custom graphics, animations, text, and real-time information. Legacy (old) Pixelcade API docs here.
System Requirements & Setup
Pixelcade Listener Service
A Pixelcade Listener called pixelweb runs in the background and listens for REST URL calls. These are local REST calls to localhost, so an Internet connection is not required. However, if your host is reachable via the Internet, you can make these calls remotely too.
Launch Commands
- Windows:
pixelweb.exe - Linux:
pixelweb - Silent Mode: Add
-silentparameter to launch without console messages
Pixelweb Command Line Options
Basic Usage
# Windows pixelweb.exe [options] # Linux ./pixelweb [options]
Network & Binding
-b string- Optional bind address (default "0.0.0.0")-port int- Optional port to listen on (default 8080)-nomdns- Skip mDNS registration
Device Configuration
-d string- Path to pixelcade device. Set to "auto" to scan (default "auto"). On Windows use COM#-devicescan- Scan for device if not found or not specified with -d-delay int- Time in seconds to delay device init-swapbluegreen- Swap blue and green (only needed for certain panels)
Display & Startup
-image string- Optional image to display on startup (default "mame/pixelcade.png")-system-image string- Optional system image on startup (overrides -image)-text string- Optional text to display on startup (default "Welcome to Pixelcade")-nointro- Skip startup text and logo (black screen on startup)-startup- Enable startup mode
Text & Font Settings
-font string- Default font for text (default "Arial Narrow 7")-fontcolor string- Default font color for text (default "ff0000")-fontcolorrandom- Random default font color, overrides -fontcolor (default true)-fontsize int- Default font size for text (default 28)
Image Matching
-fuzzy- Enable fuzzy matching for images (default true)-fuzzydistance int- Higher number = more distance, less confidence (default 20)-fuzzymatches int- Max fuzzy matches before disregarding (default 40)
Artwork & Updates
-install-artwork- First time install of Pixelcade LED artwork-install-artwork-core- Install only the core LED files (console.csv,DOFLinx,fonts,system, about 5 MB), for setups with no LED marquee such as an LCD in LCD HDMI Mode. A later-install-artworkstill installs everything.-install-artpack string- Install paid LED art pack (requires license code)-update-artwork- Update Pixelcade LED artwork-update-doflinx- Update DOFLinx MAME files only-check-artwork- Check if LED artwork update is available-progress-installer- Alternative installer with command line progress-progress-stdout- Print progress output as stdout only
Ticker Settings
-sports-ticker-refresh float- Minutes before updating sports scores, minimum 1 (default 1)-stock-ticker-refresh int- Minutes before updating stock ticker, minimum 1 (default 1)
Logging & Debug
-silent- Silent mode, no log output-debug- Debug log level-trace- Trace log level-colorlogging- Show console and ROM in color in listener window (default true)-logfile string- Optional log file path
System & Paths
-p string- Path to pixelcade root (default varies by system)-demo- Enable demo mode-version- Show Pixelcade software version
Example Commands
# Silent mode with custom port pixelweb -silent -port 8090 # Custom font and color settings pixelweb -font "Neon 80s" -fontcolor "00ff00" -fontsize 24 # Debug mode with log file pixelweb -debug -logfile "/var/log/pixelcade.log" # Custom device path (Windows) pixelweb.exe -d "COM3" -delay 5 # Fuzzy matching disabled with custom artwork pixelweb -fuzzy=false -image "custom/startup.png" # Demo mode with custom ticker refresh rates pixelweb -demo -sports-ticker-refresh 5 -stock-ticker-refresh 10
Device Compatibility
Pixelcade LED vs LCD vs Pulse Support
Pixelcade LED: Supports all V1 REST APIs
Pixelcade LCD: Limited V1 support + exclusive V2 APIs
Pulse Sub-Displays: Dedicated API set for WS2812B LED strips, MAX7219 displays, and Mini LCD controllers
LED Limitations (V1 APIs)
- URL Format: Use
pixelcadedx-xxxxxxxx.localinstead oflocalhost(where xxxxxxxx is unique LCD ID) - USB Connection: Use
169.254.100.1:8080when connected directly via USB - No Animations: GIF animations not supported
- Text Behavior: Scrolling text loops continuously until next API call
- No Advanced Text: Font size, speed, lines, and offset not supported
- No Local Playback:
localplaybackcommand not supported - Stream Only: No write mode support
- LED Isolation: Add
&ledonlyto display only on LED (not relay to LCD)
Pulse System Requirements
- Hardware: Pixelcade V2 hardware (purple board) with firmware 23 or higher
- Components: WS2812B LED strips, MAX7219 7-segment/dot matrix displays, Mini LCD displays (1602/2004)
- Zones: Maximum 36 zones (0-35) supported for LED strip management
- Features: Zone-based control, matrix text/score display, auto-detection capabilities
API Versions & Base URLs
V1 API (LCD has limitations — see above)
- LED Base URL:
http://localhost:8080 - LCD Base URL:
http://pixelcadedx-xxxxxxxx.local:8080 - LCD USB Connection:
http://169.254.100.1:8080(when connected via USB) - Alternative URLs: IP address (
http://192.168.1.206:8080) or DNS name (http://batocera.local:8080)
V2 API (LCD Only)
- Base URL:
http://pixelcadedx-xxxxxxxx.local:8080 - USB Base URL:
http://169.254.100.1:8080 - Format: All V2 endpoints return JSON objects with Status format:
{"succeeded": true/false, "message": "..."}
Pulse API (Sub-Display Controllers)
- Base URL:
http://localhost:8080orhttp://your-hostname:8080 - Test Format:
curl localhost:8080/[endpoint] - Components: WS2812B LED strips, MAX7219 displays, Mini LCD controllers
- Requirements: Pixelcade V2 hardware with firmware 23+
Queue System & Looping
Loop Commands
Loop commands control how long content displays or how many times it repeats by adding ?l={number} (also accepted as ?loop= or ?loops=) to any /arcade/stream call:
- Video (MP4) / GIF animations: Play x times, then advance queue
- Static images (JPG/PNG): Display for x seconds, then advance queue
- Scrolling text (LED only): Loop x times
- Procedural effects (LCD mameoutput): Run animation x complete cycles, then advance queue
Queue Feature
Any /arcade/stream call with ?l={x} where x ≥ 1 enters a sequential queue — including mameoutput animation effects on LCD. l=0 is treated as immediate (same as omitting the parameter). Commands are processed one after another in order. The queue can hold an unlimited number of items in any combination.
Queue Management
- Clear Queue: Send any command without the loop parameter, or with
?l=0— immediately interrupts the current item and empties the queue - Priority: Non-loop commands (and
l=0) take over immediately - Keep last item displayed: Use
l=99999as the last item in the queue — it holds the display until interrupted by a new command (prevents blank screen after queue drains) - LED Custom Scripts: When using the Queue feature in custom scripts, ensure all calls include
&event=FEScroll
Examples
# LCD: Coin insert animation → player start animation → game marquee (holds forever) curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mameoutput/startup_coin1?l=3" curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mameoutput/1player?l=2" curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mame/galaga?l=99999" # LCD: Play 3 videos in sequence, then hold last game forever curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mame/pacman?l=3" curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mame/sf?l=3" curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mame/galaga?l=99999" # LCD: Interrupt queue immediately and take over curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mame/donkeykong" # LED: Queue sequence - text → PNG → GIF → blank curl "http://localhost:8080/text?t=Game%20Playing%20Pacman&l=1&c=blue&event=FEScroll" curl "http://localhost:8080/arcade/stream/mame/pacman?l=3&event=FEScroll" curl "http://localhost:8080/arcade/stream/mame/pacghosts.gif?l=2&event=FEScroll"
API Reference
Gaming & Arcade Display
Display Game Marquees
Stream or write game-specific artwork to your Pixelcade display.
Parameters
mode:streamorwrite- stream: Real-time display (requires Pixelcade listener), instant playback
- write: Permanent storage to microSD card (works offline), includes physical write with delay. LED only
console: Console/emulator name (e.g.,mame,nes,snes)rom: ROM/game name
Console Names: Standard console names are documented at: https://github.com/alinke/pixelcade/ Console mapping file available at: https://github.com/alinke/pixelcade/blob/master/console.csv
Query Parameters
?nogif- Display only PNG if both PNG and GIF exist, do not display the video marquee on LCD?gifonly- Display only GIF if both PNG and GIF exist?t={text}- Display scrolling text if no artwork found?l={number}- Loop GIF x times or display PNG for x seconds (LED only - see Queue System above)?event={flag}- Context flag for frontend integration?nomini- If they exist, don't send metadata to the mini displays (7segment, miniLCD, and dot matrix displays), show LED strips?nostrip- Skip LED strips, show mini displays?clearstrip- Clear & turn off LED strips, show mini displays?clearmini- Show LED strips, clear & turn off all mini displays?clearstrip&clearmini- Clear everything (strips + mini displays), only show main marquee?nostrip&nomini- Skip all effects, only show main marquee (no clearing)?minilcdonly- Show metadata only on miniLCD, skip 7segment and dot matrix displays, LED strips still active?minilcdonly&nostrip- Show metadata only on miniLCD, skip 7segment, dot matrix, and LED strips
Frontend Event Integration: Provide context for arcade frontend integration by adding event flags to your API calls.
Event Flags: (Case sensitive)
FEStart- Frontend launchedFEScroll- Scrolling through gamesGameStart- Game launched. If Companion's "Disable Pulse Effects During Gameplay" is on, the LED strips are cleared and no Pulse effects start. Read the setting from/info(ledStripOffUponGameStart); set it with/ledstrip/setgamestart?enabled=true|false. It applies only toGameStart(arcade/ROM calls), not to browsing.InGame- An event that happens in game like DOFLinx in game effects for example. Pulse zone effects are not started.FEScreenSaver- Screensaver modeFEQuit- Frontend closing
Behavior Notes
- If both PNG and GIF exist: GIF plays first, then PNG
- Multiple GIFs (e.g.,
qbert_01.gif,qbert_02.gif): Random selection per API call - Missing artwork: Shows default marquee or fallback text
- Default marquee path:
<pixelcade home folder>/console/default-marquee.png
Examples
# LED: Display Pac-Man artwork GET /arcade/stream/mame/pacman curl http://localhost:8080/arcade/stream/mame/pacman # LCD: Same command with LCD URL GET http://pixelcadedx-f26967ec.local:8080/arcade/stream/mame/pacman curl http://pixelcadedx-f26967ec.local:8080/arcade/stream/mame/pacman # LCD via USB: Direct USB connection curl http://169.254.100.1:8080/arcade/stream/mame/pacman # LED: Write 1942 to storage GET /arcade/write/mame/1942 curl http://localhost:8080/arcade/write/mame/1942 # LED: Display only PNG version GET /arcade/stream/Atari%202600/pacman?nogif curl "http://localhost:8080/arcade/stream/Atari%202600/pacman?nogif" # LED: Loop GIF 3 times, ignore PNG GET /arcade/stream/Atari%202600/pacman?l=3&gifonly curl "http://localhost:8080/arcade/stream/Atari%202600/pacman?l=3&gifonly" # LED: Stream with fallback text GET /arcade/stream/mame/Missing-Game?t=Game%20Playing%20Missing-Game&c=green curl "http://localhost:8080/arcade/stream/mame/Missing-Game?t=Game%20Playing%20Missing-Game&c=green" # LED: Stream with single loop fallback GET /arcade/stream/mame/Missing-Game?t=Game%20Playing%20Missing-Game&l=1 curl "http://localhost:8080/arcade/stream/mame/Missing-Game?t=Game%20Playing%20Missing-Game&l=1" # Complex ROM names GET /arcade/stream/nes/WURM%20-%20Journey%20to%20the%20Center%20of%20the%20World(U).zip curl "http://localhost:8080/arcade/stream/nes/WURM%20-%20Journey%20to%20the%20Center%20of%20the%20World(U).zip" # Using hostname instead of localhost GET http://pixelcade.local:8080/console/stream/nes curl http://pixelcade.local:8080/console/stream/nes
Display Console Marquees
Display console/emulator specific artwork.
Query Parameters
?t={text}- Fallback scrolling text with all text formatting options
Console Names: Use standard console names from: https://github.com/alinke/pixelcade/ Console mapping reference: https://github.com/alinke/pixelcade/blob/master/console.csv
Examples
# LED: Console display with fallback text GET /console/stream/mame?t=MAME%20Arcade%20System curl "http://localhost:8080/console/stream/mame?t=MAME%20Arcade%20System" # LCD: Same command curl "http://pixelcadedx-f26967ec.local:8080/console/stream/mame?t=MAME%20Arcade%20System" # LCD via USB: Direct connection curl "http://169.254.100.1:8080/console/stream/mame?t=MAME%20Arcade%20System"
Looping & Queue System
Control display duration and create command sequences using ?l={x} (also ?loop= or ?loops=).
Loop Commands: GET/arcade/stream/{console}/{rom}?l={x}
- Video (MP4) / GIF: Play x times, then advance to next queue item
- Static image (JPG/PNG): Display for x seconds, then advance
- mameoutput effects (LCD): Run animation x cycles, then advance
- l=99999: Hold indefinitely until interrupted (queue stays active)
- l=0: Immediate mode — same as omitting
?l=, clears queue and shows now
Queue Feature
- Commands with
?l={x}(x ≥ 1) enter a sequential queue (LED and LCD) - Queue processes commands one after another in order
- Clear queue: send any command without the loop parameter, or with
l=0— takes over immediately - Use
l=99999as the last queue item to hold the display (no blank screen after queue drains) - LED custom scripts: add
&event=FEScroll
Examples
# LCD: Coin insert → player start → game marquee holds forever curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mameoutput/startup_coin1?l=3" curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mameoutput/1player?l=2" curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mame/pacman?l=99999" # LCD: Play 3 video loops, hold result curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mame/pacman?l=3" # LED: Queue sequence - text → PNG → GIF → blank curl "http://localhost:8080/text?t=Game%20Playing%20Pacman&l=1&c=blue&event=FEScroll" curl "http://localhost:8080/arcade/stream/mame/pacman?l=3&event=FEScroll" curl "http://localhost:8080/arcade/stream/mame/pacghosts.gif?l=2&event=FEScroll" # Results: Blue text 1 loop → Pac-Man 3 loops → Ghost GIF 2 loops → blank
Cycle Mode (LED Only)
Alternate between artwork and scrolling text indefinitely.
Behavior
- PNG: Displays for x seconds
- GIF: Loops once regardless of loop parameter
- Text: Scrolls once before cycling back
- Stop: Send any command without loop parameter
Example
# LED: Cycle between Pac-Man artwork and high scores
GET /arcade/stream/mame/pacman?t=High%20Scores%20Al%20200,000%20Erin%203,000&l=5&color=green&cycle
curl "http://localhost:8080/arcade/stream/mame/pacman?t=High%20Scores%20Al%20200,000%20Erin%203,000&l=5&color=green&cycle"Text Display & Scrolling
Basic Text Display
Display custom scrolling text with full formatting control.
Required Parameters
?t={text}- Your text content (use %20 for spaces)
Optional Parameters (LED Only):
?c={color}or?color={color}- Text color?s={speed}- Scroll speed (1-150, lower = faster, capped at 150)?font={name}- TTF font name (not filename)?size={size}- Font size (14-32, default: 28)?lines={count}- Number of lines (2 or 4; overrides font and size settings)?yoffset={pixels}- Vertical offset adjustment (+/- pixels)?xoffset={pixels}- Horizontal offset adjustment (+/- pixels)?l={count}or?loop={count}or?loops={count}- Number of times to loop (-1 = infinite until next command)?scroll=false- Fixed text display (no scrolling, auto-sizes with multi-line if needed, auto-sets infinite loops)?scroll=true- Force scrolling even if text fits on screen?blink={ms}- Blink interval in milliseconds (runs until next command). Note: blinking only works when text is 9 characters or less (i.e., text does not scroll)?left=trueor?leftjustify=trueor?centered=false- Left-justify multi-line text (default is centered)?ledonly- Skip LCD, send only to LED panel (bypasses dot matrix and WS2812B routing)?system={name}- System/console name (mapped via console aliases for LCD display)- Use
\nin text for explicit line breaks (e.g.,t=Line1\nLine2)
Color Options
- Named: red, blue, cyan, gray, darkgray, green, lightgray, magenta, orange, yellow, pink, white
- Hex: 6-digit format without # (e.g.,
45B39D,ff6d00) - Default: Red (or random if configured)
Font Details
- Add custom TTF fonts to
/fontsfolder - Example fonts: "Handwriting", "Tall Films Fine", "Haunting Attraction"
- Default: "Arial Narrow 7"
- Lines 2 or 4 override font and size settings
Examples
# Basic scrolling text (LED/LCD) GET /text?t=Welcome%20to%20Pixelcade # LED: Styled text with hex color GET /text?t=Hello%20World&c=ff6d00 # LED: Multi-parameter example GET /text?t=Game%20Playing%20Pacman&l=1&c=yellow&s=50 # LED: Multi-line with offset GET /text?t=Player%201%20Score%20999,999&lines=2&c=green&yoffset=-2 # LED: Looping text (5 times) curl "http://localhost:8080/text?t=Press%20Start&l=5&c=yellow" # LED: Infinite loop (runs until next command) curl "http://localhost:8080/text?t=INSERT%20COIN&loop=-1&c=cyan" # LED: Fixed text (no scrolling, auto-sizes to fit) curl "http://localhost:8080/text?t=GAME%20OVER&scroll=false&c=red" # LED: Blinking text (500ms interval, runs until next command) # Note: blink only works with 9 chars or less (non-scrolling text) curl "http://localhost:8080/text?t=PLAYER%201&blink=500&c=green" # LED: 2-line text (static, no scrolling) curl "http://localhost:8080/text?t=HIGH%20SCORE%201000000&lines=2&c=yellow&scroll=false" # LED: 4-line text (uses smallest font for more content) curl "http://localhost:8080/text?t=P1%20999999%20P2%20888888&lines=4&c=orange" # LED: Fixed 4-line text (combines scroll=false with lines=4) curl "http://localhost:8080/text?t=GAME%20STATS%20HERE&scroll=false&lines=4&c=cyan" # LED: 4-line left-justified text curl "http://localhost:8080/text?t=PLAYER%201%20SCORE&lines=4&c=cyan&left=true" # LED: Explicit line breaks using \n (centered, default) curl "http://localhost:8080/text?t=LINE%201\nLINE%202\nLINE%203\nLINE%204&lines=4&c=green" # LED: Explicit line breaks using \n (left-justified) curl "http://localhost:8080/text?t=LINE%201\nLINE%202\nLINE%203\nLINE%204&lines=4&c=green&left=true" # Color change commands GET /text/color/green GET /text/speed/50
LCD Text Behavior
- Text scrolls continuously until next API call
- Advanced formatting not supported
- If
LCDLEDCompliment=yesin settings.ini, adds&ledparameter
Retro Achievements
RetroAchievements Integration
Display achievement notifications with custom animations.
Required Parameters
console- Console nameachievement_id- RetroAchievements achievement ID?t={text}- Achievement description text?currentgame={rom}- Current game ROM name
Behavior
- If PNG/GIF matching achievement ID exists in
<pixelcade folder>/achievements, plays that file - Shows achievement scrolling text for 1 loop
- Displays game marquee matching console and rom name
- If no achievement artwork: shows random animation (1 of 10), then text, then game marquee
Example
# LED: RetroAchievement notification GET /achievements/stream/coleco/177575?t="First Flight : Clear 3 rounds of Skill Level 1"¤tgame=zaxxon curl "http://localhost:8080/achievements/stream/coleco/177575?t=\"First Flight : Clear 3 rounds of Skill Level 1\"¤tgame=zaxxon" # LCD: Same via network curl "http://pixelcadedx-f26967ec.local:8080/achievements/stream/coleco/177575?t=\"First Flight : Clear 3 rounds of Skill Level 1\"¤tgame=zaxxon" # LCD: Same via USB curl "http://169.254.100.1:8080/achievements/stream/coleco/177575?t=\"First Flight : Clear 3 rounds of Skill Level 1\"¤tgame=zaxxon"
Animation Overlays
Overlapping Animation Effects
Display GIF animations that immediately overlay/overlap with currently running animations instead of queuing. LED only — not available on LCD.
Parameters
console- Console/emulator namerom- ROM/game name (must have corresponding GIF animation)
Use Cases: Typically used for effects that occur in rapid succession during gameplay:
- DOFLinx Integration: In-game explosions, gunfire, or impact effects
- Arcade Effects: Multiple simultaneous visual effects during gameplay
- Pinball Events: Overlapping table events that shouldn't wait for previous animations
Behavior
- Overlapping: Second request overlaps with first animation — no waiting for completion
- GIF Only: Only works with GIF animations (ignores PNG files)
- No Queue: Bypasses the queue entirely — always runs immediately
- Single Playback: Each animation plays once regardless of loop parameters
- LED Exclusive: Not available on LCD displays
- Return to game: add
?returnto go back to the current game's marquee once the GIF has played, or?return={seconds}for a fixed time. Pulse effects and mini displays aren't restarted. Any other display request in the meantime cancels the return.
curl "localhost:8080/animation/overlay/mame/explosion?return"
How It Differs from Other Animation APIs
/arcade/stream?l=N: Queued — waits for previous item to finish/animation/overlay: Immediate overlay — no queue, GIF only, LED only/animation/overlay/mameoutput(LCD): Immediate procedural effect — interrupts queue; use/arcade/stream/mameoutput?l=Ninstead to queue effects in order
Error Handling
- Returns error if no GIF found for the specified console/rom combination
- Returns "Write in progress" error if device is busy with write operations
- In LCD-only mode the LED does nothing;
mameoutputeffects are passed on to the LCD (8.0.26+)
Game Event Effects (LED and LCD)
Effects for events a game controller raises (MESH, DOFLinx and others). Each name plays on the LED marquee (a GIF in the artwork's mameoutput folder) and on the LCD (drawn live), so one call works on either. Needs pixelweb 8.0.26+, the latest LED artwork and LCD software with event effects.
| Event | Effect |
|---|---|
| Credit inserted | startup_coin1, startup_insertcoin1 |
| Player joins (Start) | startup_player1-blue, startup_player2-blue (also -green), 1player, 2players |
| Game paused / resumed | startup_pause / startup_resume |
| Game exit | startup_exit |
| Shot fired | generic_shot (0.4 s; use ?coalesce) |
| Reload / out of ammo | generic_reload / generic_outofammo |
| Player hit | generic_hit (0.5 s; use ?coalesce) |
| Life lost / player death | generic_lifelost / generic_death |
| Race winner / leader / checkpoint | racing_winner / racing_leader / racing_checkpoint |
Options (on /animation/overlay/mameoutput/{effect})
?coalesce- If the same effect is still playing, skip this request instead of restarting it. Use it for triggers that repeat quickly (shots, hits) so they never pile up.?color=RRGGBB- LCD only: draw the effect in this colour, e.g. the player's colour. The game event effects are drawn in it; other effects are tinted to it. LED GIFs keep their own colours.?lcd- On a setup with both an LED and an LCD, also play the effect on the LCD. (In LCD-only mode effects always go to the LCD.)
Examples
# Player 2 fires: LED and LCD, red on the LCD, skipped if a shot is still playing curl "localhost:8080/animation/overlay/mameoutput/generic_shot?coalesce&lcd&color=ff2020" # Race won curl "localhost:8080/animation/overlay/mameoutput/racing_winner?lcd&return"
List Effects
Every mameoutput effect name this setup can play, for a picker. led is true when the LED has the GIF; lcd is true when the connected LCD lists it (lcdListed is false when no LCD answered, e.g. none connected or older LCD software). event names the game event an effect is made for.
{
"count": 147,
"lcdListed": true,
"effects": [
{ "name": "generic_shot", "led": true, "lcd": true, "event": "shot fired",
"play": "/animation/overlay/mameoutput/generic_shot" }
]
}The LCD answers its own /effects/list (same shape, without led/lcd).
News & Information Widgets
News Ticker
Display scrolling news from RSS feeds.
Start Ticker: GET/ticker?start
Stop Ticker: GET/ticker?stop
Optional Parameters
?feed={urls}- Comma-separated RSS feed URLs?c={color}- Font color (red, green, blue, yellow, white, cyan, magenta, orange)?s={speed}- Scroll speed (integer, default: 7)?newsTickerRefresh={minutes}- Refresh interval (30-14400 minutes, default: 60)
Default Feeds
https://news.yahoo.com/rsshttps://finance.yahoo.com/news/rssindex
Examples
# Minimal start GET /ticker?start curl "http://localhost:8080/ticker?start" # LCD: Start ticker via network curl "http://pixelcadedx-f26967ec.local:8080/ticker?start" # LCD: Start ticker via USB curl "http://169.254.100.1:8080/ticker?start" # Custom configuration GET /ticker?start&feed=https://news.yahoo.com/rss,http://feeds.bbci.co.uk/news/world/rss.xml&c=blue&s=10&newsTickerRefresh=120 curl "http://localhost:8080/ticker?start&feed=https://news.yahoo.com/rss,http://feeds.bbci.co.uk/news/world/rss.xml&c=blue&s=10&newsTickerRefresh=120" # Stop ticker GET /ticker?stop curl "http://localhost:8080/ticker?stop"
Weather Display
Examples
# LED: Weather by ZIP code GET /weather?location=90210 curl "http://localhost:8080/weather?location=90210" # LCD: Weather by city via network curl "http://pixelcadedx-f26967ec.local:8080/weather?location=London,UK" # LCD: Weather via USB curl "http://169.254.100.1:8080/weather?location=New%20York"
Digital Clock
Parameters
?12h={true/false}- 12-hour format?showSeconds={true/false}- Display seconds?showMilliseconds={true/false}- Display milliseconds?timeSeparator={char}- Separator character?timeFormat={24}- Time format?color={color}- Clock color
Example
# LED: Display 12-hour clock with seconds GET /clock?12h=true&showSeconds=true&timeSeparator=:&color=blue curl "http://localhost:8080/clock?12h=true&showSeconds=true&timeSeparator=:&color=blue" # LCD: Same command via network curl "http://pixelcadedx-f26967ec.local:8080/clock?12h=true&showSeconds=true&color=blue" # LCD: Simple clock via USB curl "http://169.254.100.1:8080/clock?color=green"
Spotify Now Playing Widget
Display currently playing Spotify track with album art on your Pixelcade. Requires Spotify Premium account and one-time OAuth authorization.
Start Widget: GET/spotify
Get Now Playing: GET/spotify/now-playing
Get Settings: GET/spotify/settings
Optional Parameters
?nointerrupt- Run continuously until explicitly stopped?showAlbumArt={true/false}- Display album art (default: true)
OAuth Setup Endpoints
- GET
/oauth/spotify/config- Get OAuth configuration status - GET
/oauth/spotify/status- Check if Spotify is connected - GET
/oauth/spotify/callback- OAuth callback handler - GET
/oauth/spotify/code?code={auth_code}- Submit authorization code - GET
/oauth/spotify/disconnect- Disconnect Spotify account
Easter Egg Effects
Certain songs trigger special LED strip effects:
- 🔥 Fire - Songs with "fire" in the title
- 🎃 Halloween - "Thriller", "Monster", "Spooky"
- 🎄 Christmas - "Jingle Bells", "Silent Night", Christmas songs
- ⚡ Thunder - "Thunderstruck", "Lightning", "Electric"
- 🎉 Party - Songs with "Party", "Celebrate", "Dance"
- 💜 Purple - "Purple Rain" or any song by Prince
- 🕺 Rick Roll - "Never Gonna Give You Up"
Examples
# Start Spotify widget curl "http://localhost:8080/spotify" # Start in nointerrupt mode (for screensaver) curl "http://localhost:8080/spotify?nointerrupt" # Get currently playing track info curl "http://localhost:8080/spotify/now-playing" # Check OAuth status curl "http://localhost:8080/oauth/spotify/status" # Disconnect Spotify curl "http://localhost:8080/oauth/spotify/disconnect"
Now Playing Response
{
"playing": true,
"track": "Bohemian Rhapsody",
"artist": "Queen",
"album": "A Night at the Opera",
"year": "1975",
"albumType": "album",
"popularity": 89,
"explicit": false,
"albumArtURL": "https://i.scdn.co/image/..."
}YouTube Stats Widget
Display YouTube channel statistics. Requires Google OAuth authorization.
Start Widget: GET/youtube
Get Stats: GET/youtube/stats
Optional Parameters
?nointerrupt- Run continuously until explicitly stopped
OAuth Setup Endpoints
- GET
/oauth/youtube/config- Get OAuth configuration - GET
/oauth/youtube/status- Check connection status - GET
/oauth/youtube/callback- OAuth callback handler - GET
/oauth/youtube/disconnect- Disconnect YouTube account
Examples
# Start YouTube stats widget curl "http://localhost:8080/youtube" # Get channel statistics curl "http://localhost:8080/youtube/stats" # Check OAuth status curl "http://localhost:8080/oauth/youtube/status"
Google Calendar Widget
Display upcoming calendar events. Requires Google OAuth authorization.
Start Widget: GET/calendar
Get Settings: GET/calendar/settings
Optional Parameters
?nointerrupt- Run continuously until explicitly stopped
OAuth Setup Endpoints
- GET
/oauth/calendar/config- Get OAuth configuration - GET
/oauth/calendar/status- Check connection status - GET
/oauth/calendar/disconnect- Disconnect Calendar
Examples
# Start calendar widget curl "http://localhost:8080/calendar" # Check OAuth status curl "http://localhost:8080/oauth/calendar/status"
Pixelcade Attract Mode API
Create and manage custom playlists of marquees and widgets. Playlists can include game marquees, console images, and information widgets that cycle automatically.
Attract Mode Control
Start Playlist: GET/playlist/start
Stop Playlist: GET/playlist/stop
Get Status: GET/playlist/status
Get Settings: GET/playlist/settings
Optional Parameters
?nointerrupt- Lock playlist (attract mode), prevents interruption by other API calls?interval={seconds}- Time between items (1, 3, 5, 10, 20, 30, 60, 300)?includeAnimated={true/false}- Include animated GIFs
Examples
# Start playlist curl "http://localhost:8080/playlist/start" # Start in attract mode (locked) curl "http://localhost:8080/playlist/start?nointerrupt" # Start with custom interval curl "http://localhost:8080/playlist/start?interval=10" # Stop playlist curl "http://localhost:8080/playlist/stop" # Get current status curl "http://localhost:8080/playlist/status"
Playlist Item Management
Get Items: GET/playlist/items
Set Items: POST/playlist/items (JSON body)
Add Item: GET/playlist/item/add?type={type}&id={id}&duration={seconds}
Remove Item: GET/playlist/item/remove?index={index} or ?type={type}&id={id}
Update Duration: GET/playlist/item/duration?index={index}&duration={seconds}
Item Types
marquee- Game or console marquee (id format: "system-game", e.g., "mame-pacman")widget- Information widget (id: "clock", "weather", "sports", "stocks", "news", "spotify", "youtube", "calendar")
Examples
# Add a marquee to playlist curl "http://localhost:8080/playlist/item/add?type=marquee&id=mame-pacman&duration=10" # Add a widget to playlist curl "http://localhost:8080/playlist/item/add?type=widget&id=clock&duration=60" # Add Spotify widget curl "http://localhost:8080/playlist/item/add?type=widget&id=spotify&duration=120" # Remove item by index curl "http://localhost:8080/playlist/item/remove?index=0" # Remove item by type and id curl "http://localhost:8080/playlist/item/remove?type=marquee&id=mame-pacman" # Update item duration curl "http://localhost:8080/playlist/item/duration?index=0&duration=30" # Get all items curl "http://localhost:8080/playlist/items"
Get Items Response
{
"items": [
{"type": "marquee", "id": "mame-pacman", "duration": 10},
{"type": "widget", "id": "clock", "duration": 60},
{"type": "marquee", "id": "nes-mario", "duration": 10}
],
"itemsEnriched": [
{
"index": 0,
"type": "marquee",
"id": "mame-pacman",
"duration": 10,
"system": "mame",
"game": "pacman",
"displayName": "pacman",
"thumbnailPath": "/thumbnail/mame-pacman.jpg"
}
],
"count": 3,
"defaultInterval": 5
}Playlist Favorites
Add Favorite: GET/playlist/favorite/add?marquee={system-game}
Remove Favorite: GET/playlist/favorite/remove?marquee={system-game}
Check Favorite: GET/playlist/isfavorite?marquee={system-game}
Examples
# Add to favorites curl "http://localhost:8080/playlist/favorite/add?marquee=mame-pacman" # Remove from favorites curl "http://localhost:8080/playlist/favorite/remove?marquee=mame-pacman" # Check if favorite curl "http://localhost:8080/playlist/isfavorite?marquee=mame-pacman"
Available Widgets
Get list of available widget types for playlist.
Response
{
"widgets": [
{"id": "sports", "name": "Sports Ticker", "icon": "sports", "defaultDuration": 60},
{"id": "stocks", "name": "Stocks Ticker", "icon": "trending_up", "defaultDuration": 60},
{"id": "weather", "name": "Weather Widget", "icon": "cloud", "defaultDuration": 60},
{"id": "news", "name": "News Ticker", "icon": "article", "defaultDuration": 60},
{"id": "clock", "name": "Clock Widget", "icon": "schedule", "defaultDuration": 60},
{"id": "spotify", "name": "Spotify Now Playing", "icon": "music_note", "defaultDuration": 60},
{"id": "youtube", "name": "YouTube Stats", "icon": "smart_display", "defaultDuration": 60},
{"id": "calendar", "name": "Calendar", "icon": "calendar_today", "defaultDuration": 60}
]
}Screen Saver & Widget Integration
Integrate Pixelcade widgets and attract mode with your arcade frontend's screen saver mode. These endpoints display information widgets that run continuously until explicitly stopped.
Widget Endpoints for Screen Saver Mode
Use these endpoints when your frontend enters screen saver mode. The ?nointerrupt parameter ensures the widget continues running until explicitly stopped.
Available Widget Endpoints
| Endpoint | Widget Type | Description |
|---|---|---|
/attract?nointerrupt |
Attract Mode | Custom user-defined attract mode playlist. Recommended and show this option first as the user can define a playlist of widgets and marquees along with how long each one should display |
/clock?nointerrupt&clockType={type} |
Clock | Digital or themed arcade clock (see clock types below) |
/weather?nointerrupt |
Weather | Current weather conditions |
/news?nointerrupt |
News | RSS news ticker |
/stocks?nointerrupt |
Stocks & Crypto | Stock and cryptocurrency ticker |
/sports?nointerrupt |
Sports Scoreboard | All sports scores |
/sports/nfl?nointerrupt |
NFL Scores | NFL game scores only |
/sports/nba?nointerrupt |
NBA Scores | NBA game scores only |
/sports/mlb?nointerrupt |
MLB Scores | MLB game scores only |
/sports/nhl?nointerrupt |
NHL Scores | NHL game scores only |
/spotify?nointerrupt |
Spotify Now Playing | Currently playing Spotify track with album art |
/lastfm?nointerrupt |
Last.fm Now Playing | Currently scrobbling Last.fm track with album art |
/youtube?nointerrupt |
YouTube Stats | YouTube channel statistics |
/calendar?nointerrupt |
Google Calendar | Upcoming calendar events |
/plex?nointerrupt |
Plex Now Playing | Currently playing Plex media with cover art |
/netflix?nointerrupt |
Netflix Activity | Netflix viewing activity and recommendations |
/commute?nointerrupt |
Traffic Dashboard | Real-time commute times with traffic status indicators |
/yahoofantasy?nointerrupt |
Yahoo Fantasy Sports | Fantasy sports team scores and standings |
/horoscope?nointerrupt |
Horoscope | Daily horoscope readings with zodiac graphics |
/worldclock?nointerrupt |
World Clock | Multiple timezone clock display |
Clock Types
The clock widget supports themed arcade clocks. Use the clockType parameter to select a theme:
pacman- Pac-Man themed clockmspacman- Ms. Pac-Man themed clockgalaga- Galaga themed clockarkanoid- Arkanoid themed clocktron- Tron themed clockburgertime- Burger Time themed clockdkong- Donkey Kong themed clockinvaders- Space Invaders themed clockcentipede- Centipede themed clockasteroids- Asteroids themed clockdigdug- Dig Dug themed clockfrogger- Frogger themed clocktetris- Tetris themed clocktempest- Atari Tempest vector styleretro- Generic 80s neon arcade stylesf2- Street Fighter II themed clockmetroid- Metroid themed clockcastlevania- Castlevania themed clockpuzzlebobble- Puzzle Bobble / Bust-a-Move themed clock
Clock Examples
# Standard digital clock curl "http://localhost:8080/clock?nointerrupt" # Pac-Man themed clock curl "http://localhost:8080/clock?nointerrupt&clockType=pacman" # Galaga themed clock curl "http://localhost:8080/clock?nointerrupt&clockType=galaga" # Tron themed clock curl "http://localhost:8080/clock?nointerrupt&clockType=tron"
Stop Widgets & Pixelcade Attract Mode (Exit Screen Saver)
Call this endpoint when your frontend exits screen saver mode to stop all running widgets (including attract mode) and return Pixelcade to normal arcade marquee mode.
Example
# Stop all widgets and attract mode, return to arcade mode
curl http://localhost:8080/attract/stopFrontend Integration Example
# When screen saver starts - display Pac-Man clock curl "http://localhost:8080/clock?nointerrupt&clockType=pacman" # Or start attract mode with user playlist curl "http://localhost:8080/attract?nointerrupt" # Or display Spotify now playing curl "http://localhost:8080/spotify?nointerrupt" # Or display Plex now playing curl "http://localhost:8080/plex?nointerrupt" # Or display traffic dashboard curl "http://localhost:8080/commute?nointerrupt" # Or display daily horoscope curl "http://localhost:8080/horoscope?nointerrupt" # Or display world clock curl "http://localhost:8080/worldclock?nointerrupt" # When user exits screen saver - stop all widgets and resume normal operation curl "http://localhost:8080/widgets/stop" # Then display the current game marquee curl "http://localhost:8080/arcade/stream/mame/pacman"
Integration Notes
- Call the widget endpoint when your frontend enters screen saver/attract mode
- Call
/widgets/stopwhen the user exits screen saver mode - this stops all running widgets including attract mode - After stopping widgets, send your next marquee command to resume normal operation
- The
/attractand/playlistendpoints are interchangeable - both work identically - Configure default settings (favorite teams, stocks, clock type, etc.) using the Pixelcade Companion apps at pixelcade.org/apps
- OAuth Required: Some widgets require one-time OAuth authorization via the Companion app: Spotify, Plex, Last.fm, YouTube, Google Calendar, Google Photos, Google Tasks, and Yahoo Fantasy
- API Key Required: The Traffic/Commute widget requires a Google Maps API key configured in the Companion app
Sports Scores
Sports Ticker
Supported Leagues
nfl,nba,nhl,mlb,wnbaeng.1(Premier League),esp.1(La Liga),ger.1(Bundesliga)ita.1(Serie A),fra.1(Ligue 1),por.1(Primeira Liga)ned.1(Eredivisie),mex.1(Liga MX),usa.1(MLS)uefa.champions(Champions League)college-football,mens-college-basketball,womens-college-basketball,college-baseball
Complete Team Code Reference
NFL Teams
WSH - Washington Commanders ARI - Arizona Cardinals ATL - Atlanta Falcons BAL - Baltimore Ravens BUF - Buffalo Bills CAR - Carolina Panthers CHI - Chicago Bears CIN - Cincinnati Bengals CLE - Cleveland Browns DAL - Dallas Cowboys DEN - Denver Broncos DET - Detroit Lions GB - Green Bay Packers HOU - Houston Texans IND - Indianapolis Colts JAX - Jacksonville Jaguars KC - Kansas City Chiefs LAC - Los Angeles Chargers LAR - Los Angeles Rams LV - Las Vegas Raiders MIA - Miami Dolphins MIN - Minnesota Vikings NE - New England Patriots NO - New Orleans Saints NYG - New York Giants NYJ - New York Jets PHI - Philadelphia Eagles PIT - Pittsburgh Steelers SEA - Seattle Seahawks SF - San Francisco 49ers TB - Tampa Bay Buccaneers TEN - Tennessee Titans
NBA Teams
WSH - Washington Wizards ATL - Atlanta Hawks BKN - Brooklyn Nets BOS - Boston Celtics CHA - Charlotte Hornets CHI - Chicago Bulls CLE - Cleveland Cavaliers DAL - Dallas Mavericks DEN - Denver Nuggets DET - Detroit Pistons GS - Golden State Warriors HOU - Houston Rockets IND - Indiana Pacers LAC - Los Angeles Clippers LAL - Los Angeles Lakers MEM - Memphis Grizzlies MIA - Miami Heat MIL - Milwaukee Bucks MIN - Minnesota Timberwolves NO - New Orleans Pelicans NY - New York Knicks OKC - Oklahoma City Thunder ORL - Orlando Magic PHI - Philadelphia 76ers PHX - Phoenix Suns POR - Portland Trail Blazers SA - San Antonio Spurs SAC - Sacramento Kings TOR - Toronto Raptors UTAH- Utah Jazz
NHL Teams
WSH - Washington Capitals ANA - Anaheim Ducks ARI - Arizona Coyotes BOS - Boston Bruins BUF - Buffalo Sabres CAR - Carolina Hurricanes CBJ - Columbus Blue Jackets CGY - Calgary Flames CHI - Chicago Blackhawks COL - Colorado Avalanche DAL - Dallas Stars DET - Detroit Red Wings EDM - Edmonton Oilers FLA - Florida Panthers LA - Los Angeles Kings MIN - Minnesota Wild MTL - Montreal Canadiens NJ - New Jersey Devils NSH - Nashville Predators NYI - New York Islanders NYR - New York Rangers OTT - Ottawa Senators PHI - Philadelphia Flyers PIT - Pittsburgh Penguins SEA - Seattle Kraken SJ - San Jose Sharks STL - St. Louis Blues TB - Tampa Bay Lightning TOR - Toronto Maple Leafs VAN - Vancouver Canucks VGK - Vegas Golden Knights WPG - Winnipeg Jets
MLB Teams
ARI - Arizona Diamondbacks ATL - Atlanta Braves BAL - Baltimore Orioles BOS - Boston Red Sox CHC - Chicago Cubs CHW - Chicago White Sox CIN - Cincinnati Reds CLE - Cleveland Guardians COL - Colorado Rockies DET - Detroit Tigers HOU - Houston Astros KC - Kansas City Royals LAA - Los Angeles Angels LAD - Los Angeles Dodgers MIA - Miami Marlins MIL - Milwaukee Brewers MIN - Minnesota Twins NYM - New York Mets NYY - New York Yankees OAK - Oakland Athletics PHI - Philadelphia Phillies PIT - Pittsburgh Pirates SD - San Diego Padres SEA - Seattle Mariners SF - San Francisco Giants STL - St. Louis Cardinals TB - Tampa Bay Rays TEX - Texas Rangers TOR - Toronto Blue Jays WSH - Washington Nationals
WNBA Teams
ATL - Atlanta Dream CHI - Chicago Sky CONN- Connecticut Sun DAL - Dallas Wings IND - Indiana Fever LA - Los Angeles Sparks LV - Las Vegas Aces MIN - Minnesota Lynx NY - New York Liberty PHX - Phoenix Mercury SEA - Seattle Storm WSH - Washington Mystics
English Premier League
ARS - Arsenal AVL - Aston Villa BRE - Brentford BOU - AFC Bournemouth BHA - Brighton & Hove Albion BUR - Burnley CHE - Chelsea CRY - Crystal Palace EVE - Everton FUL - Fulham LIV - Liverpool LUT - Luton Town MCI - Manchester City MUN - Manchester United NEW - Newcastle United NFO - Nottingham Forest SHU - Sheffield United TOT - Tottenham Hotspur WHU - West Ham United WOL - Wolverhampton Wanderers
German Bundesliga
FCA - FC Augsburg FCU - FC Union Berlin BOC - VfL Bochum SVW - SV Werder Bremen BVB - Borussia Dortmund SGE - Eintracht Frankfurt SCF - SC Freiburg HEI - FC Heidenheim TSG - TSG 1899 Hoffenheim KIE - Holstein Kiel RBL - RB Leipzig B04 - Bayer 04 Leverkusen M05 - FSV Mainz 05 BMG - Borussia Mönchengladbach FCB - FC Bayern München STP - FC St. Pauli VFB - VfB Stuttgart WOB - VfL Wolfsburg
French Ligue 1
SCO - Angers SCO AJA - AJ Auxerre BRE - Stade Brestois 29 HAC - Le Havre AC LIL - Lille OSC ASM - AS Monaco MON - Montpellier HSC NAN - FC Nantes NICE- OGC Nice OL - Olympique Lyonnais OM - Olympique de Marseille PSG - Paris Saint-Germain RCL - RC Lens SR - Stade de Reims REN - Stade Rennais FC ASSE- AS Saint-Étienne STR - RC Strasbourg Alsace TFC - Toulouse FC
Spanish La Liga
ALM - Almería ATM - Atlético Madrid BAR - Barcelona BET - Real Betis CAD - Cádiz CEL - Celta Vigo EIB - Eibar ELC - Elche GET - Getafe GRN - Granada LEV - Levante LUG - Lugo MAL - Málaga RAK - Rayo Vallecano REAL- Real Madrid RSO - Real Sociedad VLL - Valladolid VAL - Valencia
Italian Serie A
ATA - Atalanta BOL - Bologna CAG - Cagliari EMP - Empoli FIO - Fiorentina GEN - Genoa INTER - Inter Milan JUVE- Juventus LAZ - Lazio LEC - Lecce MIL - Milan MON - Monza NAP - Napoli ROM - Roma SAMP- Sampdoria SPE - Spezia TOR - Torino UDI - Udinese
Portuguese Primeira Liga
ABA - Abissola BEN - Benfica BOL - Belenenses SAD FAM - Famalicão MAR - Marítimo NAC - Nacional POR - Portimonense PRA - Praiense RIO - Rio Ave SCP - Sporting CP TON - Tondela VIT - Vitória de Guimarães BRG - Braga VSC - Vitória SC PFC - Paços de Ferreira
Dutch Eredivisie
ADO - ADO Den Haag AZ - AZ Alkmaar BAS - FC Basel DEN - FC Den Bosch FCO - FC Utrecht FYN - Feyenoord HEE - FC Heerenveen HER - Heracles Almelo PEC - PEC Zwolle PSV - PSV Eindhoven RKC - RKC Waalwijk SPE - Sparta Rotterdam VIT - Vitesse WIL - Willem II GRON- FC Groningen
Mexican Liga MX
AMERICA - Club América ATLAS - Atlas FC CHIVAS - Chivas Guadalajara CRUZAZUL - Cruz Azul FCJUAREZ - FC Juárez PACHUCA - Club Pachuca PUMAS - UNAM Pumas TIGRES - Tigres UANL TOLUCA - Deportivo Toluca SANTOS - Santos Laguna LEON - Club León MORELIA - Monarcas Morelia PUEBLA - Club Puebla XALAPA - Veracruz QUERETARO - Querétaro
Major League Soccer (USA)
ATL - Atlanta United FC CHI - Chicago Fire FC CLT - Charlotte FC COL - Colorado Rapids DC - D.C. United FCB - FC Cincinnati LAFC- Los Angeles FC LAG - LA Galaxy MIA - Inter Miami CF MIN - Minnesota United FC MTL - CF Montréal NE - New England Revolution NYC - New York City FC NYRB- New York Red Bulls ORL - Orlando City SC PHI - Philadelphia Union PORT- Portland Timbers RSL - Real Salt Lake SJ - San Jose Earthquakes SEA - Seattle Sounders FC SKC - Sporting Kansas City TOR - Toronto FC VAN - Vancouver Whitecaps FC
UEFA Champions League
ARS - Arsenal ATLETI - Atlético Madrid BAR - Barcelona BAY - Bayern Munich BVB - Borussia Dortmund BENE- Benfica BRUGGE - Club Brugge CHE - Chelsea DORTMUND - Borussia Dortmund INTER - Inter Milan JUVE- Juventus LIVERPOOL - Liverpool MANC- Manchester City PSG - Paris Saint-Germain REAL- Real Madrid NAPOLI - Napoli ROMA- AS Roma
Examples
# All NFL scores GET /sports/nfl curl "http://localhost:8080/sports/nfl" # Specific teams GET /sports/nfl?teams=KC,GB,SF curl "http://localhost:8080/sports/nfl?teams=KC,GB,SF" # LCD: NBA scores via network curl "http://pixelcadedx-f26967ec.local:8080/sports/nba?teams=LAL,BOS,MIA" # LCD: Premier League via USB curl "http://169.254.100.1:8080/sports/eng.1?teams=ARS,CHE,LIV"
Financial Data
Stock & Crypto Ticker
Parameters
?tickers={symbols}- Comma-separated ticker symbols (default: "AAPL,GOOG,MSFT")?c={color}- Display color?s={speed}- Scroll speed (default: 10)
Examples
# Default stocks GET /stocks curl "http://localhost:8080/stocks" # Custom stocks with color GET /stocks?tickers=AAPL,GOOG,MSFT&c=blue&s=10 curl "http://localhost:8080/stocks?tickers=AAPL,GOOG,MSFT&c=blue&s=10" # LCD: Crypto via network curl "http://pixelcadedx-f26967ec.local:8080/stocks?tickers=BTC-USD,ETH-USD,ADA-USD&c=orange" # LCD: Stocks via USB curl "http://169.254.100.1:8080/stocks?tickers=TSLA,NVDA&c=green"
Statistics & Game Data
In-Game Statistics Display
Parameters
?label={text}&value={number}- Primary stat (required)?livesLabel={text}&livesValue={number}- Lives display?shots={number}- Shot count?hits={number}- Hit count?ratio={number}- Hit ratio percentage?separator={style}- Column separator (solid, dashed, doubledot)?return={seconds}(or?duration={seconds}) - Go back to the current game's marquee after this many seconds. Pulse effects and mini displays aren't restarted, and any other display request in the meantime cancels the return. Without it, stats stay up until something else is shown.
Examples
# LED: Display stage information GET /stats?label=STAGE&value=2 curl "http://localhost:8080/stats?label=STAGE&value=2" # LED: Full statistics with all parameters GET /stats?label=STAGE&value=2&shots=99&hits=44&ratio=20&separator=solid curl "http://localhost:8080/stats?label=STAGE&value=2&shots=99&hits=44&ratio=20&separator=solid" # LED: Lives/ships display curl "http://localhost:8080/stats?livesLabel=Ships&livesValue=5&shots=99&hits=44&ratio=20&separator=solid" # LCD: Same commands work (via network) curl "http://pixelcadedx-f26967ec.local:8080/stats?label=STAGE&value=3" # LCD: Via USB connection curl "http://169.254.100.1:8080/stats?livesLabel=Lives&livesValue=3"
Custom Content & Media
Animation Library
Endpoints
- GET
/animations/stream/{filename}- Stream specific animation - GET
/animations/stream/{filename}?r- Random animation - GET
/animations/list- List the animations in theanimatedfolder, as JSON{"count": N, "animations": [{"name": "1943battleofmidway", "play": "/arcade/stream/animated/1943battleofmidway"}, ...]}. Play one with itsplayURL (add?nostripto leave the Pulse strips alone).
Examples
# LED: Stream specific animation GET /animations/stream/0rain curl http://localhost:8080/animations/stream/0rain # LED: Loop animation 3 times (uses Queue System) GET /animations/stream/0rain?l=3 curl "http://localhost:8080/animations/stream/0rain?l=3" # LED: Random animation curl "http://localhost:8080/animations/stream/explosion?r" # LED: List all animations curl http://localhost:8080/animations/list # LCD: Stream animation via network (no loops) curl http://pixelcadedx-f26967ec.local:8080/animations/stream/0rain # LCD: Stream animation via USB curl http://169.254.100.1:8080/animations/stream/0rain
Still Images & Lists
Endpoints
- GET
/still/list- List single frame images - GET
/arcade/list- List MAME game names - GET
/currentgame- Get last selected game (format:console%game-name)
Examples
# LED: List still images curl http://localhost:8080/still/list # LED: List MAME games curl http://localhost:8080/arcade/list # LED: Get current game curl http://localhost:8080/currentgame # LCD: Same commands via network curl http://pixelcadedx-f26967ec.local:8080/still/list curl http://pixelcadedx-f26967ec.local:8080/currentgame # LCD: Same commands via USB curl http://169.254.100.1:8080/arcade/list
File Upload (Using curl/libcurl)
# Upload PNG to images folder curl -i -X POST -H "Content-Type: multipart/form-data" \ -F "upload=@/Users/al/artwork/galaga.png" \ -F "upload-type=STILL_IMAGE" \ http://localhost:8080/upload # Upload GIF to animations folder curl -i -X POST -H "Content-Type: multipart/form-data" \ -F "upload=@/Users/artwork/pacman.gif" \ -F "upload-type=ANIMATED_GIF" \ http://localhost:8080/upload # Upload to specific console without displaying curl -i -X POST -H "Content-Type: multipart/form-data" \ -F "upload=@/Users/al/artwork/pacman.PNG" \ -F "upload-type=STILL_IMAGE" \ -F "console=alu" \ -F "displaynow=0" \ http://localhost:8080/uploadplatform # Upload to MAME and display immediately curl -i -X POST -H "Content-Type: multipart/form-data" \ -F "upload=@/Users/al/artwork/pacman.gif" \ -F "upload-type=ANIMATED_GIF" \ -F "console=MAME" \ -F "displaynow=1" \ http://localhost:8080/uploadplatform
Vestaboard Integration
Pixelcade can mirror a wide range of widgets (stocks, sports, weather, trivia, clocks, and more) to a connected Vestaboard split-flap display, in addition to a direct endpoint for sending arbitrary content. Vestaboard must first be enabled and configured (Cloud API token and/or Local API key, board type) in Companion under Settings > Vestaboard — every endpoint below returns a clear error telling you what to enable/configure there if something's missing.
Direct Send Endpoint (/vestaboard)
Send arbitrary text directly to the board, independent of any widget. Useful for external automation (DOFLinx, a cron job, a custom script, or just testing) that wants to write to the board without going through a Pixelcade widget. This endpoint never touches or interrupts the LED/LCD display — it only talks to Vestaboard.
Send Content: GET · POST/vestaboard
Content is automatically wrapped, truncated, and centered (both horizontally per line and vertically as a block) to fit whichever board you have configured — a 3-row x 15-column Note or a 6-row x 22-column Flagship — so you don't need to calculate line lengths or padding yourself.
Parameters
text- The message to send. Required unlessclear=true. Supports line breaks and color/special-character markup — see below.clear-trueto blank the board instead of sending text.transition- One-off Local API animation style for this send only:classic,wave,drift, orcurtain. Doesn't change the saved setting.speed- Pairs withtransition:fastorgentle.forced-trueto bypass Vestaboard's Cloud API quiet hours. Cloud API only; ignored in Local API mode.
Parameters can be passed as a GET query string (easiest for curl/browser/automation triggers) or as a POST JSON body (recommended for longer text, or anything using {tag} markup — see the curl globbing note below).
Line Breaks
Two ways to start a new line, both equivalent:
- An actual newline character, e.g.
%0AURL-encoded in a query string. - A literal backslash-n — the two characters
\andn— which is much easier to type in a terminal or paste into a URL without encoding.
# Real newline via %0A curl "http://localhost:8080/vestaboard?text=GAME%20OVER%0AFINAL%20SCORE%0A12345" # Literal backslash-n - identical result, easier to type curl "http://localhost:8080/vestaboard?text=GAME%20OVER\nFINAL%20SCORE\n12345" # POST JSON body - best for longer or multi-line text curl -X POST http://localhost:8080/vestaboard \ -H "Content-Type: application/json" \ -d '{"text": "GAME OVER\nFINAL SCORE\n12345"}'
Colors & Special Characters
Vestaboard's color flaps and its degree/heart symbol have no plain-text representation, so they're written as inline {tag} markup instead. Each tag occupies exactly one character cell, same as a letter, so wrapping/centering/truncation all account for it correctly.
{red}{orange}{yellow}{green}{blue}{violet}{white}{black}- color flap cells{filled}- a solid/filled flap block{degree}/{heart}- the same physical character cell (code 62) on Vestaboard hardware; it renders as a degree symbol on the Flagship and a heart on the Note. Use whichever tag name reads more naturally for what you're building — both work regardless of which board you actually have.
# A colored status word curl -X POST http://localhost:8080/vestaboard \ -d '{"text": "STATUS: {green} ONLINE"}' # A colored bar built from repeated color tags curl -X POST http://localhost:8080/vestaboard \ -d '{"text": "HIGH SCORE\n{red}{orange}{yellow}{green}{blue}{violet}"}' # Temperature with a degree symbol curl -X POST http://localhost:8080/vestaboard \ -d '{"text": "72{degree}F SUNNY"}' # Heart symbol curl -X POST http://localhost:8080/vestaboard \ -d '{"text": "I {heart} PIXELCADE"}'
curl users: if you use { } braces directly in a GET URL (rather than in a POST -d body), curl's own URL-globbing feature will silently strip them before the request is even sent — e.g. {green} becomes plain text green with no color applied. Either add -g to disable globbing, percent-encode the braces as %7B/%7D, or just use a POST body as shown above (no globbing involved).
# -g disables curl's brace globbing for GET requests
curl -g "http://localhost:8080/vestaboard?text=STATUS%3A%20{green}%20ONLINE"Other Examples
# Blank the board curl "http://localhost:8080/vestaboard?clear=true" # One-off transition override (doesn't change the saved setting) curl "http://localhost:8080/vestaboard?text=HELLO&transition=wave&speed=gentle" # Bypass Cloud API quiet hours for an urgent message curl "http://localhost:8080/vestaboard?text=URGENT&forced=true"
Error Responses: the endpoint returns a specific, actionable error (HTTP 400) telling you exactly what to fix in Companion if Vestaboard isn't ready to receive content:
Vestaboard integration is not enabled — turn it on in Companion under Settings > Vestaboard.The /vestaboard endpoint is disabled — enable "Manual /vestaboard Endpoint" in Companion under Settings > Vestaboard.No Vestaboard API token or Local API key is configured — add one in Companion under Settings > Vestaboard.
Widget Mirroring
When Vestaboard is enabled, the following widgets automatically mirror their content to the board while running, each with its own enable toggle and Local API transition setting in Companion under Settings > Vestaboard: Stats, Text, Achievements, Trivia, Stock & Crypto Ticker, Earthquakes, Weather, Sports Scoreboard, This Day in Retro, Planes Overhead, RetroAchievements, YouTube Stats, What to Watch, Clock, World Clock, Yahoo Fantasy, Horoscope, and Countdown. No additional API calls are needed for these — starting the widget as usual (e.g. GET/stocks) is enough; the board updates automatically and clears itself when the widget stops.
System Management
Device Control
System Commands
- GET
/quit- Shutdown Pixelcade listener - GET
/reboot- Reboot OS (Pi/LCD only) - GET
/shutdown- Shutdown OS (Pi/LCD only) - GET
/localplayback- Local playback mode (LED only) - GET
/arcade/stream/black/dummy- Blank display
Examples
# LED: Shutdown listener curl http://localhost:8080/quit # LED: Blank display curl http://localhost:8080/arcade/stream/black/dummy # LCD: Reboot via network curl http://pixelcadedx-f26967ec.local:8080/reboot # LCD: Shutdown via USB curl http://169.254.100.1:8080/shutdown
Device Information
Returns JSON with
{
"name": "My Pixelcade LED",
"type": "LED",
"hostname": "almacbook.lan",
"ipAddress": "192.168.87.21",
"firmwareVersion": "PDXR0023",
"hardwareID": "PIXL0020",
"v2board": true,
"bootLoaderID": "SUBV0002",
"firmwareSubVersion": "SUBV0002",
"softwareVersion": "6.5.9",
"resolution": "128x32",
"pixelcadeRoot": "/Users/al/Documents/code/pixelcadeusbtools/pixelweb/dist",
"bindAddr": "0.0.0.0",
"bindPort": 8080,
"defaultFont": "/Users/al/Documents/code/pixelcadeusbtools/pixelweb/dist/fonts/Arial Narrow 7.ttf",
"defaultFontColor": "ff0000",
"defaultFontColorRandom": true,
"defaultFontSize": 28,
"devicePath": "auto",
"deviceScan": false,
"fuzzyMatching": true,
"pngFuzzyDistanceThreshold": 10,
"pngFuzzyMaxMatchesThreshold": 40,
"noIntro": false,
"startupImage": "mame/pixelcade.png",
"startupMode": false,
"startupText": "Welcome to Pixelcade",
"systemImage": "",
"debugLogging": false,
"traceLogging": false,
"noLogging": false,
"colorLogging": true,
"initDelay": 0,
"demoMode": false,
"noMdns": false,
"lcdMarquee": true,
"lcdMarqueeHostName": "",
"lcdMarqueeIPAddress": "",
"lcdLEDCompliment": true,
"lcdSearchStartUpDelay": 0,
"lcdMultiple": false,
"lcdUsbConnected": true,
"lcdOnly": false,
"lcdUsbIPAddress": "169.254.100.1",
"lcdFirmwareVersion": "6.3.0.0",
"lcdConnection": "network",
"lcdPort": "8080",
"lcdHDMIMode": false,
"lcdHDMISupported": true,
"lcdHDMIAddress": "",
"lcdHDMIPort": 0,
"linkedLCD": {
"hostname": "pixelcadedx-f8d4413c",
"port": 8080,
"connection": "network"
},
" ": true,
"hasLEDStripSupport": true,
"ledStrip": true,
"ledStripBrightness": 12,
"ledStripNumPixels": 762,
"sevenSegment": true,
"sevenSegmentNumModules": 8,
"dotMatrix": true,
"dotMatrixNumModules": 8,
"miniLCD": true,
"miniLCDType": 3,
"scoreDisplay": "dotMatrix",
"textDisplay": "pixelcadeled",
"ledStripOffUponGameStart": false,
"ledStripFrame": true,
"ledStripRanges": true,
"batchMode": true,
"sidekick": true,
"sidekick-ids": "esp32-5,esp32-oled",
"sidekick-models": "Pixelcade Sidekick 5\",Pixelcade Sidekick LILYGO T-Display S3 AMOLED"
}Key Information Fields
- Hardware:
type,firmwareVersion,hardwareID,v2board,resolution - Network:
hostname,ipAddress,bindAddr,bindPort - Display Capabilities:
ledActive,hasLEDStripSupport,sevenSegment,dotMatrix,miniLCD - LCD Integration:
lcdMarquee,lcdUsbConnected,lcdUsbIPAddress,lcdLEDCompliment,lcdPort(the port the LCD software listens on) - LCD HDMI Mode:
lcdConnection(network, orhdmiwhen the LCD bar is driven from this computer's HDMI output),lcdHDMIMode(true in LCD HDMI Mode),lcdHDMISupported(LCD HDMI Mode is available on this computer),lcdHDMIAddressandlcdHDMIPort(where to send LCD API calls in LCD HDMI Mode; empty and 0 otherwise). See LCD HDMI Mode. - Linked LCD:
linkedLCD(8.0.24+) names the Pixelcade LCD this computer drives, the way the phone and desktop apps discover it:hostname(mDNS host name, without.local),address(IP, when known),portandconnection(hdmi,usbornetwork). Absent when there's no LCD. The Pixelcade apps use it to show an LED and its LCD as one cabinet. - Settings:
fuzzyMatching,defaultFont,defaultFontColor,debugLogging - LED Strip:
ledStrip,ledStripBrightness,ledStripNumPixels,ledStripOffUponGameStart,ledStripFrameandledStripRanges(8.0.26+: true when/ledstrip/frameand/ledstrip/rangescan be used; needs LED firmware 23.11 or later; absent on older pixelweb, so treat a missing field as false) - Sub-Displays:
sevenSegmentNumModules,dotMatrixNumModules,scoreDisplay,textDisplay - Sidekick:
sidekick(true if the companion-display feature is enabled),sidekick-ids(comma-separated catalog model IDs of actively connected Sidekick devices, e.g.esp32-5,esp32-oled),sidekick-models(comma-separated display names, same order assidekick-ids, e.g.Pixelcade Sidekick 5",Pixelcade Sidekick LILYGO T-Display S3 AMOLED) — both empty strings if nothing is connected
Examples
# LED: Get device information GET /info curl http://localhost:8080/info # Using IP address curl http://192.168.1.206:8080/info # Using hostname curl http://pixelcade.local:8080/info
Settings Configuration
Valid Settings
fuzzyMatching,debugLogging,traceLogging,noLogging,colorLoggingdefaultFontColorRandom,noIntro,demoMode,noMdns,deviceScan,displayNamelcdConnection:networkorhdmi(turns LCD HDMI Mode on or off)
Response Examples
{"key": "fuzzyMatching", "value": "false"}
{"key": "error", "value": "wrongKeyName is not a valid setting key"}Software Updates
- GET
/update/artwork- Download latest LED artwork - GET
/update/doflinx- Download latest DOFLinx MAME definitions
Support Bundle
Downloads one zip with what Pixelcade support usually asks for, from every part of the cabinet. Passwords, tokens, API keys and location settings are removed. The same download is in Pixelcade Companion under Settings > Support > Download Support Bundle.
summary.txt: computer, Pixelweb version, front end, LED, LCD connection and software version, DOFLinxpixelweb/:info.json(as/info),pixelcade.ini,recent-log.txt(the last 5,000 log lines, kept in memory)lcd/: the LCD'sinfo.json,settings.json,artwork-library.json,host-status.jsonandlog.txtdoflinx/:DOFLinx.log(last 2 MB) andDOFLinx.inisystem/(Linux):uname, uptime, disk and memory,/etc/os-release,lsusb
Example
curl -o pixelcade-support.zip http://localhost:8080/support/bundle
LCD HDMI Mode
In Pixelcade LCD HDMI Mode the LCD marquee bar is plugged into the arcade computer's second HDMI output instead of having its own single board computer. Pixelweb downloads and runs the Pixelcade LCD software on the same computer, which draws to a borderless window on the bar's screen.
- Platforms: Batocera on x86-64 PCs, Batocera on a Raspberry Pi 5, and 64-bit Windows (Pixelweb 8.0.25+).
lcdHDMISupportedin/infosays whether this computer can run it. - Turning it on: Pixelcade Companion > Settings > Pixelcade LCD > LCD HDMI Mode, or GET
/settings?key=lcdConnection&value=hdmi(networkturns it off). The Batocera installer offers it when it detects an LCD bar. - The LCD software: listens on port 8090 on the same computer (Pixelweb keeps 8080). It's announced on the network as
<hostname>-lcdon port 8081 for the phone apps, and Pixelweb starts it, restarts it if it exits, and keeps it updated.lcdSoftwareChannel = betainpixelcade.iniselects the beta LCD software. - Artwork: on first start the LCD software downloads its Artwork Library (about 20 GB) into
lcdartworkin the Pixelcade folder, showing progress on the bar.
Sending LCD API Calls in LCD HDMI Mode
Front ends and Pixelweb's own APIs (/arcade/stream, /text, /console/stream, ...) work unchanged: Pixelweb forwards them to the LCD. Programs that call the LCD API directly (for example DOFLinx in-game effects) should read /info and, when lcdHDMIMode is true, send LCD calls to http://{lcdHDMIAddress}:{lcdHDMIPort} instead of the USB address 169.254.100.1:8080.
{
"lcdConnection": "hdmi",
"lcdPort": "8090",
"lcdHDMIMode": true,
"lcdHDMISupported": true,
"lcdHDMIAddress": "127.0.0.1",
"lcdHDMIPort": 8090,
"linkedLCD": {
"hostname": "batocera-lcd",
"address": "192.168.87.170",
"port": 8081,
"connection": "hdmi"
}
}# An explosion effect on the LCD, in LCD HDMI Mode (as a program on the same computer)
curl http://127.0.0.1:8090/animation/overlay/mameoutput/generic_explosion3LCD HDMI Mode License
(add ?refresh=1 to check with the License Service now)
LCD HDMI Mode is a paid feature with a 14-day free trial that starts on first use. After the trial, without a license, it runs as a free tier: the LCD shows the Pixelcade logo and console marquees only (a game selection shows its console's marquee), and text, achievements and widgets aren't sent to the LCD. An LCD with its own board (Orange Pi) isn't affected.
{
"hdmiMode": true,
"known": true,
"licensed": false,
"freeTier": false,
"trialActive": true,
"daysLeft": 14,
"trialEndsAt": "2026-11-30T02:01:24Z",
"priceCents": 7900
}known: the License Service has answered at least once (until then everything works)licensed: unlocked by a purchase, gift code or builder's codefreeTier: the trial has ended without a license
LCD Artwork Download Progress
The LCD software's Artwork Library download, relayed by Pixelweb (Pixelcade Companion shows it on its home page during the first download).
{
"hdmiMode": true,
"complete": false,
"state": "running",
"step": "downloading",
"phase": "marquees",
"first": true,
"bytesDone": 1213915969,
"bytesTotal": 21794901034,
"secondsLeft": 767,
"error": ""
}state:idle,running,done,errororcancelledphase:essentials,yourgames(artwork for the ROMs on this computer, first),marquees,videosfirst: the first download on this computer (no library yet)secondsLeft: estimate, 0 while unknown
LCD Only API Reference
Device Information
Get LCD Specifications
Example
# LCD: Get device info via network GET http://pixelcadedx-xxxxxxxx.local:8080/v2/info curl http://pixelcadedx-xxxxxxxx.local:8080/v2/info # LCD: Get device info via USB curl http://169.254.100.1:8080/v2/info
Response
{
"name": "Tricks 'n Lies",
"hostname": "pixelcadedx-xxxxxxxx",
"firmwareVersion": "2.9.0.9",
"resolution": {
"width": 1920,
"height": 360
},
"isPaired": false,
"hasJoinedNetwork": true,
"connection": "board",
"ledHostAddress": "http://desktop-5aj5v3t.local:8080"
}connection:board(the LCD's own board), orhdmiwhen it's the LCD software running in LCD HDMI Mode; thenhdmiOutputnames the HDMI output it draws on (e.g.HDMI-A-2)ledHostAddress: the main Pixelcade Companion of the cabinet this LCD belongs to, when Pixelweb has told the LCD (empty otherwise)
Device Pairing
Check Pairing Status
Response
{
"succeeded": true,
"message": "paired"
}Set Pairing State
Endpoints
- GET
/v2/utility/pairing/set/on- Set to paired - GET
/v2/utility/pairing/set/off- Set to unpaired
Example
# LCD: Set to paired via network GET http://pixelcadedx-xxxxxxxx.local:8080/v2/utility/pairing/set/on curl http://pixelcadedx-xxxxxxxx.local:8080/v2/utility/pairing/set/on # LCD: Set to paired via USB curl http://169.254.100.1:8080/v2/utility/pairing/set/on # LCD: Check pairing status curl http://pixelcadedx-xxxxxxxx.local:8080/v2/utility/pairing/
Response
{
"succeeded": true,
"message": "Device now set to Paired"
}Marquee Management
Set Default Marquee
Example
GET http://pixelcadedx-xxxxxxxx.local:8080/v2/utility/marquee/set/2
Response
{
"succeeded": true,
"message": "New Default Set@2"
}Marquee Thumbnails
Returns 640px wide thumbnail JPEG of requested marquee.
Example
GET http://pixelcadedx-xxxxxxxx.local:8080/v2/thumbnails/mame/deathsml
Marquee Editing
Display Temporary Marquee
Content-Type: image/jpg (required)
Example
curl -X POST -H "Content-Type: image/jpg" \ "http://pixelcadedx-f26967ec.local:8080/v2/marquees/mame/blazstar/display" \ --data-binary "@blazstar.jpg"
Save Marquee Permanently
Undo Marquee Changes
One level of undo available to revert recent changes.
Dot Sub-Display Scores (LCD with Dot Display)
Send Score to Dot Display
Behavior
- Displays on Pixelcade Dot sub-displays only
- Supports matrix or 7-segment displays
- Score won't scroll if under 8 characters (matrix can display 4)
- Text can also be sent in addition to numbers
- Not all characters render on 7-segment displays
Example
# LCD: Send score via network GET http://pixelcadedx-xxxxxxxx.local:8080/score?s=1000 curl "http://pixelcadedx-xxxxxxxx.local:8080/score?s=1000" # LCD: Send score via USB curl "http://169.254.100.1:8080/score?s=1000" # LCD: Send high score curl "http://pixelcadedx-xxxxxxxx.local:8080/score?s=999999"
Marquee Lists & Content
List Marquees by System
Example
GET http://pixelcadedx-xxxxxxxx.local:8080/list/image/mame
Response
{
"system": "atari2600",
"count": 693,
"files": [
"atari2600-Return to Haunted House (USA).jpg",
"atari2600-Pac-Man (Atari) (USA).jpg",
"atari2600-Combat (USA).jpg"
]
}List All Content
Endpoints
- GET
/list/image/all- All image marquees across systems - GET
/list/video- All video marquees across systems
LCD Settings Configuration
LCD-Specific Settings
LCD Settings
marqueeOverlays=yes/no- Enable/disable marquee overlaysSubDisplayScrollingOnly=yes/no- Text only on dot displays vs LCDImageMarqueesOnly=yes/no- Disable/enable video snapsUseConsoleMapping=yes/no- Server-side vs local console mappingSetSubDisplayNumModules=4/8- Dot display module countPixelcadeDotType=matrix/7segment- Dot display typeDisplayName={name}- Set LCD display nametextColor={color}- Scrolling text colorfont={fontname}- Set font
Available Fonts: "Orbitron-SemiBold", "Orbitron-Regular", "Eight-Bit-Madness", "Arial Narrow 7", "Benegraphic", "Candy Stripe (BRK)", "Casio FX-702P", "Daddy Longlegs NF", "Decoder", "DIG DUG", "dotty", "DPComic", "Early GameBoy", "Fiddums Family", "Ghastly Panic", "GilbertC", "Gnuolane", "Grapevine", "Grinched", "Handwriting", "Harry P", "Haunting Attraction", "Minimal4", "Morris Roman", "MostlyMono", "Neon 80s", "Nintendo DS BIOS", "Not So Stout Deco", "Paulistana Deco", "Pixelated", "Pixeled", "RetroBoundmini", "RM Typerighter medium", "Samba Is Dead", "Shlop", "Space Patrol NF", "Star Jedi Hollow", "Star Jedi", "Still Time", "Tall Films Fine", "taller", "techno overload (BRK)", "TR2N", "TRON", "Vectroid", "Videophreak"
Text Colors: "random", "red", "cyan", "darkgray", "lightgray", "orange", "yellow", "blue", "gray", "green", "magenta", "pink", "white"
Examples
# Enable marquee overlays GET http://pixelcadedx-xxxxxxxx.local:8080/settings?key=marqueeOverlays&value=yes # Set font GET http://pixelcadedx-xxxxxxxx.local:8080/settings?key=font&value=Neon%2080s # Set dot display type GET http://pixelcadedx-c59b51ea:8080/settings?key=PixelcadeDotType&value=7segment # Get all settings GET http://pixelcadedx-xxxxxxxx.local:8080/settings?key=getSettings
Settings Response
{
"font": "Neon 80s",
"SubDisplayScrollingOnly": false,
"ImageMarqueesOnly": false,
"SubDisplayNumModules": "8",
"FontColor": "751d7d",
"consoleMapping": false,
"marqueeOverlays": true
}Effects
Procedural Animation Effects
Trigger real-time procedural animation effects rendered directly to the LCD framebuffer. Effects are generated programmatically — no artwork files required.
Endpoints
- GET
/arcade/stream/mameoutput/{effect}?l=N— Queued (recommended): enters the sequential queue alongside marquee requests - GET
/animation/overlay/mameoutput/{effect}— Immediate: interrupts and clears the queue, runs effect right away
Query Parameters (both endpoints)
?loop=Nor?loops=Nor?l=N— Play N complete cycles (default: 1 for immediate; required for queued path). Use0or99999to loop indefinitely.
Queue Behavior (via /arcade/stream/mameoutput):
When called with ?l=N, the effect enters the same sequential queue as marquee commands. This is the correct path for MAME game-start sequences where the coin insert and player-start animations should play before the game marquee appears:
# Queued: coin insert → player start → game marquee (plays in order)
curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mameoutput/startup_coin1?l=3"
curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mameoutput/1player?l=2"
curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mame/galaga?l=99999"Immediate / Overlap Behavior (via /animation/overlay/mameoutput):
If called without a loop parameter (or via the /animation/overlay path), the effect runs immediately, interrupting any current playback. If a second effect arrives while a first is still playing, both render concurrently for a brief overlap window (~200ms). Designed for rapid back-to-back in-game events such as explosions.
Examples
# Immediate: single explosion (interrupts current display) curl "http://pixelcadedx-xxxxxxxx.local:8080/animation/overlay/mameoutput/explosion" # Immediate: loop an effect 3 times curl "http://pixelcadedx-xxxxxxxx.local:8080/animation/overlay/mameoutput/levelup?loop=3" # Immediate: two explosions in rapid succession (overlap visually) curl "http://pixelcadedx-xxxxxxxx.local:8080/animation/overlay/mameoutput/explosion" & sleep 0.1 && curl "http://pixelcadedx-xxxxxxxx.local:8080/animation/overlay/mameoutput/explosion3" # Queued: effect plays after current queue item finishes curl "http://pixelcadedx-xxxxxxxx.local:8080/arcade/stream/mameoutput/achievement?l=1"
Available Effects
Explosions — Generic Numbered
| Effect | Description |
|---|---|
explosion, generic_explosion1 |
Fiery burst with orange-red particles and trailing embers |
generic_explosion2 |
Angular vector debris explosion with shrapnel fragments |
generic_explosion3 |
Dual shockwave blast with radiating particle rings |
generic_explosion4 |
Rapid multi-burst chain explosion |
generic_explosion5 |
Large engulfing fireball with trailing embers |
generic_explosion6 |
Green plasma nova with lime energy rings and radiating debris |
Explosions — Extended Duration
| Effect | Description |
|---|---|
generic_explosion-long1 |
Fiery ember explosion at 2× normal duration |
generic_explosion-long2 |
Vector debris explosion at 2× normal duration |
Explosions — Color & Shape Variants
| Effect | Description |
|---|---|
generic_explosion-blue |
Smooth blue fireball with cyan shockwave rings |
generic_explosion-green |
Neon-green chemical fireball with smoke halo |
generic_explosion-white |
Pure white nova bloom |
generic_explosion-white2 |
Layered white glow with three expanding rings |
generic_explosion-whitepuff |
Six billowing soft cloud puffs |
generic_explosion-circle |
Concentric rings fading from white to dark red |
generic_explosion-full-horizontal |
Full-width horizontal fire band |
generic_swirl-purple |
Three spinning Archimedean spiral arms in violet to magenta |
generic_spinner |
Eight-arm rotating star in yellow and orange |
generic_pink-circle |
Magenta fireball with hot-pink expanding rings |
Player Start
| Effect | Description |
|---|---|
startup_player1-blue, player1 |
"PLAYER 1" blinking text in yellow |
startup_player1-green |
"PLAYER 1" blinking text in green |
startup_player2-blue, player1or2 |
"PLAYER 1 OR 2" blinking text in cyan |
startup_player2-green |
"PLAYER 1 OR 2" blinking text in green |
startup_exit |
"EXIT" blinking text in red |
startup_continue |
"CONTINUE" blinking text in green |
startup_pause |
"PAUSE" blinking text in cyan-blue |
startup_reset |
"RESET" blinking text in orange |
startup_cheat |
"CHEAT" blinking text in magenta |
1player |
Joystick graphic with "1 PLAYER" flash reveal animation |
2players |
Dual joystick graphic with "2 PLAYERS" flash reveal animation |
Coins
| Effect | Description |
|---|---|
startup_coin1 |
Three spinning gold coins drop and bounce with landing impact sparks |
startup_insertcoin1 |
Coin slot machine with spinning coin inserting into slot and "INSERT COIN" blinking text |
Level Up
| Effect | Description |
|---|---|
levelup, generic_milestone, generic_levelup-green |
Rising star burst with level-up particle shower |
levelup2–levelup8 |
Alternative level-up animations with varied colors and particle styles |
Achievements
| Effect | Description |
|---|---|
achievement, generic_bonus, generic_100, generic_extralife |
Achievement unlock burst with star particles |
achievement1–achievement20 |
Numbered achievement unlock variants with distinct color schemes |
Pac-Man
| Effect | Description |
|---|---|
pacman_powerpellet |
Flashing power pellet energize effect |
pacmanpower |
Power-up burst effect |
pacman_ghost200 |
Ghost eaten — 200 points |
pacman_ghost400 |
Ghost eaten — 400 points |
pacman_ghost800 |
Ghost eaten — 800 points |
pacman_ghost1600 |
Ghost eaten — 1600 points |
pacman_cherry, pacmanfruit |
Cherry bonus fruit — 100 pts |
pacman_strawberry, pacmanfruit300 |
Strawberry bonus fruit — 300 pts |
pacman_orange, pacmanfruit500 |
Orange bonus fruit — 500 pts |
pacman_apple, pacmanfruit700, mspacman_pretzel |
Apple / Ms. Pac-Man pretzel bonus — 700 pts |
pacman_melon, pacmanfruit1000, mspacman_pear |
Melon / Ms. Pac-Man pear bonus — 1000 pts |
pacman_galaxian, pacmanfruit2000, mspacman_bannana |
Galaxian flagship / Ms. Pac-Man banana bonus — 2000 pts |
pacman_bell, pacmanfruit3000 |
Bell bonus fruit — 3000 pts |
pacman_key, pacmanfruit5000 |
Key bonus — 5000 pts |
Galaga
| Effect | Description |
|---|---|
galaga_shipinflight-exploding |
Player ship exploding while captured in enemy formation |
galaga2, galaga3 |
Galaga enemy explosion variants |
galagasingle |
Single Galaga enemy destruction |
galaga_bossinflight-exploding |
Boss Galaga flagship explosion |
galagabosswing1, galagabosswing2 |
Boss Galaga wing explosion variants |
galaga_challengeperfect, galagachallengeperfect, generic_perfect |
Perfect score celebration on challenge stage |
galagaperfect |
Galaga perfect clear effect |
galagonice |
Galaga near-perfect / nice result effect |
galagafirstship |
First ship appears at stage start |
galaga_newship, galagaextraship |
Extra ship bonus awarded |
1942 / 1943
| Effect | Description |
|---|---|
1942_explosion |
WWII aerial explosion — medium burst |
1942_explosion-small |
WWII aerial explosion — small burst |
1943_explosion1 |
WWII fighter explosion with yellow-orange fireball and debris shards |
1943_explosion2 |
WWII bomber explosion with large red-orange fireball and dual shockwaves |
1943kai_explosion |
1943 Kai blue-white energy explosion with cyan sparks and rings |
1942sc30–1942sc200 |
Score card overlays for 30%–200% hit accuracy |
1942challenge |
Challenge stage clear effect |
Space Shooters
| Effect | Description |
|---|---|
invaders_green |
Space Invaders enemy explosion in green |
invaders_white |
Space Invaders enemy explosion in white |
invaders_yellow |
Space Invaders enemy explosion in yellow |
invaders_magenta |
Space Invaders enemy explosion in magenta |
rtype_explosion1 |
R-Type ship explosion — standard burst |
rtype_explosion2 |
R-Type ship explosion — large burst |
rtype_explosion3 |
R-Type ship explosion — ring shockwave |
rtype_explosion3-small |
R-Type ship explosion — small ring variant |
rtype_explosion4-bw |
R-Type explosion in black and white |
asteroids-explosion |
Asteroids: 8-vertex rock shattering into 5 spinning fragments with debris rays |
asteroidsdeluxe |
Asteroids Deluxe: smoother 3-fragment rock destruction |
blasteroids |
Blasteroids-style colorful rock explosion |
astroblaster |
Astro Blaster alien ship destruction |
tempest |
Atari Tempest vector tube zap effect |
spaceduel |
Space Duel dual-ship explosion |
gyruss |
Gyruss enemy spiral destruction |
airgallet |
Air Gallet aerial burst |
twincobra |
Twin Cobra dual helicopter explosion |
Classic Arcade
| Effect | Description |
|---|---|
frogger_home |
Frogger successfully reaching home |
centipede-explosion1 |
Centipede segment destruction — variant 1 |
centipede-explosion2 |
Centipede segment destruction — variant 2 |
digdug |
Dig Dug enemy inflate and pop explosion |
digdug_pooka |
Pooka enemy inflate and pop |
digdug_fygar |
Fygar enemy inflate and pop |
duckhunt_explosion1 |
Duck Hunt — duck shot effect 1 |
duckhunt_explosion2 |
Duck Hunt — duck shot effect 2 |
duckhunt_explosion3 |
Duck Hunt — duck shot effect 3 |
Donkey Kong
| Effect | Description |
|---|---|
dkjump |
Donkey Kong jump effect |
dkong_explosion |
Barrel or enemy explosion in Donkey Kong style |
Gorf
| Effect | Description |
|---|---|
gorf |
Gorf drone ship destruction |
gorf2 |
Gorf fighter ship explosion |
gorf3 |
Gorf laser ship destruction |
gorfflagship |
Gorf flagship explosion |
Arkanoid
| Effect | Description |
|---|---|
arkanoid_explosion1 |
Block destruction — small burst |
arkanoid_explosion2 |
Block destruction — medium burst |
arkanoid_explosion3 |
Block destruction — large burst |
arkanoid_explosion4 |
Vaus paddle destruction |
Burger Time
| Effect | Description |
|---|---|
burgerdrophotdog |
Hot dog ingredient drop |
burgerdroppickle |
Pickle ingredient drop |
burgerdropegg |
Egg ingredient drop |
burgerdrop2–burgerdrop6 |
Multi-ingredient drop combinations |
burgerbonus |
Bonus item collected |
Tetris
| Effect | Description |
|---|---|
tetromino |
Single tetromino placement flash |
tetrissingle |
Single line clear |
tetrisdouble |
Double line clear |
tetristetris |
Four-line "Tetris" clear — most spectacular variant |
tetrisbonuspuzzle |
Bonus puzzle stage complete |
tetrisbonus2p |
Two-player bonus stage |
Aliens
| Effect | Description |
|---|---|
alienchestbuster |
Chestburster xenomorph eruption |
alienblue |
Blue xenomorph attack |
alienstandard |
Standard xenomorph attack |
alienviolet |
Violet xenomorph attack |
alieninfectoid |
Infectoid alien attack |
alienbarrel |
Barrel roll alien attack |
alienboss |
Alien boss encounter |
Defender
| Effect | Description |
|---|---|
defendergundie |
Player ship destruction |
defendermarcianito |
Marcianito alien kill |
defendermystery |
Mystery bonus ship |
defenderbonus10k |
10,000 point bonus awarded |
defenderextra |
Extra life awarded |
defenderflopper |
Flopper enemy killed |
Altered Beast
| Effect | Description |
|---|---|
alteredbeastsimple |
Basic enemy death |
alteredbeastgargoyle |
Gargoyle enemy destruction |
alteredbeastblue |
Blue spirit orb collection |
alteredbeastdragon |
Dragon transformation effect |
alteredbeastwolf |
Werewolf transformation effect |
alteredbeastbonus |
Bonus stage completion |
System Updates
Update LCD System
Initiates system update checking for new artwork and firmware from private GitHub repository.
Example
GET http://pixelcadedx-xxxxxxxx.local/update
Pulse API Reference
Complete WS2812B LED Strip, MAX7219, and Mini LCD API Reference for Pixelcade V2 hardware with firmware 23+.
WS2812B APIs
LED Strip Effects
Start Effect
Start a LED strip effect with optional parameters. zone-id can be a number starting with 0 or can be a name
Common Parameters
r,g,b- Primary color (0-255)r2,g2,b2- Secondary color (0-255)speed- Effect speed (1-255)loops- Number of loops (0=infinite)intensity- Brightness (0-255)reverse- Reverse direction (true/false)duration- Duration in seconds
Supported Zones Names
left_stripright_stripleft_speaker_ringright_speaker_ringcenter_matrixleft_matrixright_matrix
Examples
curl "localhost:8080/ledstrip/zone/left_strip/effect/rainbow?speed=100&intensity=200" curl "localhost:8080/ledstrip/zone/center_matrix/effect/fire?r=255&g=100&b=0&speed=150" curl "localhost:8080/ledstrip/zone/left_matrix/effect/cyclon?speed=200"
Clear Zone Effect
Clear / blank out that zone
Example
curl localhost:8080/ledstrip/left_strip/clear
Available LED Strip Effects
Basic Effects
explosion, comet, chaser, fire, strobe, glitch, party, pulse, rainbow, scanner, wave, sparkle, twinkle, cylon
Advanced Effects
explosion_dual, explosion_multi, particle_explosion, fireworks, fire_flicker, twinklefox, marquee, meteor_rain, chase_wave, fireworks_burst, lightning, starscape
Advanced Explosion Effects
starburst_explosion, cascade_explosion, fragmentation_explosion, ring_explosion, multistage_explosion, explosion_burst
Holiday/Themed Effects
christmas, halloween, valentine, independence
Gun Game Effects
gun_flash_recoil, gun_muzzle_trail, gun_explosion_pulse, gun_laser_shot, gun_shotgun_spread, gun_reload_sequence, gun_crosshair_lock, gun_damage_indicator
Racing Effects
racing_speedometer, racing_track_lights, racing_turbo_boost, racing_drift_smoke, racing_finish_line
Retro/Arcade Ambient Effects
retro_scan, circuit_trace, pixel_cascade, neon_glow, retro_pulse, data_stream, arcade_attract, power_up, game_over, level_clear, coin_drop, neon_flicker, vintage_warmth, digital_rain, retro_grid, plasma_field, soft_breathing, ambient_flow, retro_fade, gentle_ripple
Console-Specific Effects
Arcade Systems: console_mame, console_fba, console_daphne, console_sammy_atomiswave, console_sega_naomi, console_sega_model_2, console_sega_model_3, console_taito_type_x, teknoparrot_arcade, teknoparrot_neon
Nintendo: console_nes, console_snes, console_n64, console_nintendo_gamecube, console_nintendo_wii, console_nintendo_wii_u, console_nintendo_famicom_disk_system, console_virtualboy
Sega: console_sega_sg-1000, console_mastersystem, console_genesis, console_segacd, console_sega32x, console_sega_saturn, console_dreamcast
Sony: console_psx, console_ps2, console_sony_playstation_3, console_psp
Microsoft: console_microsoft_xbox, console_xbox360
Atari: console_atari2600, console_atari5200, console_atari7800, console_atarijaguar, console_atarilynx
NEC: console_pcengine, console_nec_pc_engine-cd, console_supergrafx
Other Consoles: console_3do, console_philips_cd-i, console_vectrex, console_coleco, console_intellivision, console_amiga, console_fairchild_channel_f, console_bally_astrocade
Handhelds: console_gb, console_gbc, console_gba, console_nintendo_ds, console_nintendo_3ds, console_gamegear, console_ngp, console_ngpc
LED Strip and Ring MAME Game-Specific Effects
mame_pacman, mame_dkong, mame_galaga, mame_frogger, mame_mspacman, mame_digdug, mame_qbert, mame_polepos, mame_btime, mame_joust, mame_robotron, mame_zaxxon, mame_tron, mame_timeplt, mame_1942, mame_paperboy, mame_ghouls, mame_gauntlet, mame_commando, mame_rampage, mame_bublbobl, mame_arkanoid, mame_outrun, mame_rygar, mame_ddragon, mame_rtype, mame_shinobi, mame_contra, mame_sf, mame_opwolf, mame_aburner, mame_narc, mame_splatter, mame_goldnaxe, mame_ffight, mame_tmnt, mame_gorf, mame_centiped, mame_milliped, mame_asteroid, mame_defender, mame_stargate, mame_tempest, mame_wiz, mame_berzerk, mame_mpatrol, mame_invaders, mame_missile, mame_xevious, mame_punchout, mame_spyhunt, mame_bzone, mame_sinistar, mame_tapper, mame_elevator, mame_trackfld, mame_ikari, mame_pengo, mame_mappy, mame_jungleh, mame_nbajam, mame_simpsons, mame_timecris, mame_xmen, mame_mk, mame_hotd, mame_mslug, mame_tekken, mame_pbobble, mame_starwars, mame_raiden, mame_kchamp, mame_sfrush, mame_kof94, mame_blitz, mame_altbeast
LED Strip - LaserDisc Games
daphne_lair, daphne_ace, daphne_cliff, daphne_astron, daphne_mach3, daphne_maddog, american_laser_games_maddog, daphne_timegal, daphne_cobraab
LED Strip - Atari 2600 Games
atari2600_Haunted House (USA), atari2600_Yars' Revenge (USA), atari2600_Adventure (USA), atari2600_Pitfall, atari2600_River Raid (USA), atari2600_Berzerk (USA), atari2600_Asteroids (USA), atari2600_Centipede (USA), atari2600_Ms. Pac-Man (USA), atari2600_Pac-Man (Atari) (USA), atari2600_Pole Position (USA)
LED Strip - RCade Menu Apps
console_music, console_netsurf, console_pictures, console_2048, console_movies, console_kodi, console_menu, console_wolfenstein3d, console_tic80, console_rickdangerous, console_quake, console_mrboom, console_doom, console_doom2, console_dinothawr, console_cavestory
LED Strip Achievement Effects
achievements_1, achievements_2, achievements_3, achievements_4, achievements_5, achievements_6, achievements_7, achievements_8, achievements_9, achievements_10, achievements_11, achievements_12, achievements_13, achievements_14, achievements_15, achievements_16, achievements_17, achievements_18, achievements_19, achievements_20
MAME Output Effects
mameoutput_startup_coin1, mameoutput_1player, mameoutput_2players, mameoutput_startup_insertcoin1, mameoutput_startup_insertcoin2, mameoutput_startup_insertcoin3, mameoutput_startup_insertcoin4, mameoutput_startup_insertcoin5, mameoutput_startup_insertcoin6, mameoutput_startup_insertcoin-sf
Matrix Basic Effects
matrix_rain, pacman_chase, matrix_digital_rain, matrix_ripple, matrix_spiral, matrix_crosshatch, matrix_diamonds, matrix_plasma, matrix_fire_2d, matrix_snake, matrix_checkerboard, matrix_bouncing_ball, matrix_swirl, matrix_snowfall
Matrix Explosion Effects
matrix_explosion_radial, matrix_explosion_shockwave, matrix_explosion_fireball
Matrix Gun Effects
matrix_gun_muzzle_flash, matrix_gun_bullet_trail, matrix_gun_impact_spark, matrix_grenade_explosion, matrix_shotgun_spread, matrix_laser_blast, matrix_plasma_burst
Matrix Pulse Effects
matrix_circle_pulse, matrix_cross_pulse, matrix_diamond_pulse, matrix_square_pulse, matrix_pulsing_diamonds, matrix_pulsing_squares, matrix_pulsing_circles, matrix_diamond_pulse2, matrix_concentric_squares
Matrix Animation Effects
matrix_scrolling_text, matrix_spinning_square, matrix_horizontal_dashes, matrix_vertical_streak, matrix_shift_left_right, matrix_shift_right_left, matrix_shift_bottom_top, matrix_shift_top_bottom, matrix_splash_center, matrix_round_and_round, matrix_arrow_shift, matrix_v_line_pulse, matrix_vertical_bars, matrix_starburst, matrix_checkboard2, matrix_spiral2, matrix_laser_scan, matrix_pixel_storm
Matrix Energy/Electrical Effects
matrix_electrical_arc, matrix_electrical_power, matrix_plasma_sideways, matrix_energy_beam, matrix_lightning_storm, matrix_energy_field
Matrix Particle/Sparkle Effects
matrix_sparkle_left, matrix_sparkle_right, matrix_sparkle_corners, matrix_particle_stream, matrix_stars_field, matrix_pixel_rain
Matrix Color/Visual Effects
matrix_color_fade, matrix_color_wave, matrix_rainbow_spiral, matrix_neon_grid, matrix_scan_lines, matrix_data_cascade, matrix_circuit_board, matrix_hex_matrix, matrix_neon_pulse, matrix_glitch_noise, matrix_waveform, matrix_binary_code, matrix_radar_sweep
Matrix Score Display
matrix_score
Matrix 8×32 MAME Game-Specific Effects
matrix_8x32_mame_polepos, matrix_8x32_mame_btime, matrix_8x32_mame_zaxxon, matrix_8x32_mame_tron, matrix_8x32_mame_timeplt, matrix_8x32_mame_paperboy, matrix_8x32_mame_gng, matrix_8x32_mame_commando, matrix_8x32_mame_rampage, matrix_8x32_mame_bublbobl, matrix_8x32_mame_rygar, matrix_8x32_mame_ddragon, matrix_8x32_mame_rtype, matrix_8x32_mame_shinobi, matrix_8x32_mame_contra, matrix_8x32_mame_opwolf, matrix_8x32_mame_aburner, matrix_8x32_mame_narc, matrix_8x32_mame_splatter, matrix_8x32_mame_goldnaxe, matrix_8x32_mame_ffight, matrix_8x32_mame_gorf, matrix_8x32_mame_centiped, matrix_8x32_mame_milliped, matrix_8x32_mame_asteroid, matrix_8x32_mame_defender, matrix_8x32_mame_stargate, matrix_8x32_mame_tempest, matrix_8x32_mame_wotw, matrix_8x32_mame_berzerk, matrix_8x32_mame_mpatrol, matrix_8x32_mame_galaga, matrix_8x32_mame_1942, matrix_8x32_mame_pacman, matrix_8x32_mame_mspacman, matrix_8x32_mame_qbert, matrix_8x32_mame_digdug, matrix_8x32_mame_dkong, matrix_8x32_mame_invaders, matrix_8x32_mame_frogger, matrix_8x32_mame_tetris, matrix_8x32_mame_robotron, matrix_8x32_mame_joust, matrix_8x32_mame_vssmb
Matrix 8×8 MAME Game-Specific Effects
matrix_8x8_mame_polepos, matrix_8x8_mame_btime, matrix_8x8_mame_zaxxon, matrix_8x8_mame_tron, matrix_8x8_mame_timeplt, matrix_8x8_mame_paperboy, matrix_8x8_mame_gng, matrix_8x8_mame_commando, matrix_8x8_mame_rampage, matrix_8x8_mame_bublbobl, matrix_8x8_mame_rygar, matrix_8x8_mame_ddragon, matrix_8x8_mame_rtype, matrix_8x8_mame_shinobi, matrix_8x8_mame_contra, matrix_8x8_mame_opwolf, matrix_8x8_mame_aburner, matrix_8x8_mame_narc, matrix_8x8_mame_splatter, matrix_8x8_mame_goldnaxe, matrix_8x8_mame_ffight, matrix_8x8_mame_gorf, matrix_8x8_mame_centiped, matrix_8x8_mame_milliped, matrix_8x8_mame_asteroid, matrix_8x8_mame_defender, matrix_8x8_mame_stargate, matrix_8x8_mame_tempest, matrix_8x8_mame_wotw, matrix_8x8_mame_berzerk, matrix_8x8_mame_mpatrol, matrix_8x8_mame_galaga, matrix_8x8_mame_galaga_explosion, matrix_8x8_mame_1942_explosion, matrix_8x8_mame_dkong, matrix_8x8_mame_invaders, matrix_8x8_mame_qbert, matrix_8x8_mame_pacman, matrix_8x8_mame_mspacman, matrix_8x8_mame_1942, matrix_8x8_mame_frogger, matrix_8x8_mame_digdug
Matrix 8×32 Explosion Effects
matrix_8x32_explosion1, matrix_8x32_explosion2, matrix_8x32_explosion3, matrix_8x32_explosion4, matrix_8x32_explosion5, matrix_8x32_explosion6, matrix_8x32_explosion7, matrix_8x32_explosion8, matrix_8x32_explosion9
Matrix 8×8 Explosion Effects
matrix_8x8_explosion1, matrix_8x8_explosion2, matrix_8x8_explosion3, matrix_8x8_explosion4, matrix_8x8_explosion5, matrix_8x8_explosion6, matrix_8x8_explosion7, matrix_8x8_explosion8, matrix_8x8_explosion9
Matrix 8×8 Achievement Effects
matrix_8x8_achievements_1, matrix_8x8_achievements_2, matrix_8x8_achievements_3, matrix_8x8_achievements_4, matrix_8x8_achievements_5, matrix_8x8_achievements_6, matrix_8x8_achievements_7, matrix_8x8_achievements_8, matrix_8x8_achievements_9, matrix_8x8_achievements_10, matrix_8x8_achievements_11, matrix_8x8_achievements_12, matrix_8x8_achievements_13, matrix_8x8_achievements_14, matrix_8x8_achievements_15, matrix_8x8_achievements_16, matrix_8x8_achievements_17, matrix_8x8_achievements_18, matrix_8x8_achievements_19, matrix_8x8_achievements_20
Matrix 8×32 Achievement Effects
matrix_8x32_achievements_1, matrix_8x32_achievements_2, matrix_8x32_achievements_3, matrix_8x32_achievements_4, matrix_8x32_achievements_5, matrix_8x32_achievements_6, matrix_8x32_achievements_7, matrix_8x32_achievements_8, matrix_8x32_achievements_9, matrix_8x32_achievements_10, matrix_8x32_achievements_11, matrix_8x32_achievements_12, matrix_8x32_achievements_13, matrix_8x32_achievements_14, matrix_8x32_achievements_15, matrix_8x32_achievements_16, matrix_8x32_achievements_17, matrix_8x32_achievements_18, matrix_8x32_achievements_19, matrix_8x32_achievements_20
Matrix 8×8 MAME Output Effects
matrix_8x8_mameoutput_startup_coin1, matrix_8x8_mameoutput_1player, matrix_8x8_mameoutput_2players, matrix_8x8_mameoutput_startup_insertcoin1, matrix_8x8_mameoutput_startup_insertcoin2, matrix_8x8_mameoutput_startup_insertcoin3, matrix_8x8_mameoutput_startup_insertcoin4, matrix_8x8_mameoutput_startup_insertcoin5, matrix_8x8_mameoutput_startup_insertcoin6, matrix_8x8_mameoutput_startup_insertcoin-sf
Matrix 8×32 MAME Output Effects
matrix_8x32_mameoutput_startup_coin1, matrix_8x32_mameoutput_1player, matrix_8x32_mameoutput_2players, matrix_8x32_mameoutput_startup_insertcoin1, matrix_8x32_mameoutput_startup_insertcoin2, matrix_8x32_mameoutput_startup_insertcoin3, matrix_8x32_mameoutput_startup_insertcoin4, matrix_8x32_mameoutput_startup_insertcoin5, matrix_8x32_mameoutput_startup_insertcoin6, matrix_8x32_mameoutput_startup_insertcoin-sf
LED Strip - In Game Effects
galaga_beam, pacman_blueghost, pacman_eyes
Matrix 8×8 - In Game Effects
matrix_8x8_galaga_beam, matrix_8x8_pacman_blueghost, matrix_8x8_pacman_eyes
Matrix 8×32 - In Game Effects
matrix_8x32_galaga_beam, matrix_8x32_pacman_blueghost, matrix_8x32_pacman_eyes
Basic LED Strip Control
Set Individual Pixel
Set a specific LED pixel to a color.
Parameters
index- LED index (0-based)r,g,b- RGB color values (0-255)
Example
curl "localhost:8080/ledstrip/pixel/10?r=255&g=0&b=0"
Clear All LEDs
Clear all LEDs and stop effects.
Example
curl localhost:8080/ledstrip/clear
Zone Flood Fill
Set all LEDs in a zone to a solid color. Stops any running effects on the zone first.
Parameters
zoneid- Zone ID (number 0-35) or zone name (e.g., left_strip, center_matrix)r- Red value (0-255)g- Green value (0-255)b- Blue value (0-255)
Examples
# Flood left_strip zone with red curl "localhost:8080/ledstrip/zone/left_strip/flood?r=255&g=0&b=0" # Flood center_matrix zone with green curl "localhost:8080/ledstrip/zone/center_matrix/flood?r=0&g=255&b=0" # Flood zone 0 with blue curl "localhost:8080/ledstrip/zone/0/flood?r=0&g=0&b=255" # Flood right_strip with white curl "localhost:8080/ledstrip/zone/right_strip/flood?r=255&g=255&b=255"
Set Range
Set a range of LEDs to a color.
Example
curl "localhost:8080/ledstrip/range?start=10&count=5&r=255&g=255&b=0"
Each /ledstrip/range and /ledstrip/pixel call refreshes the whole strip. To set many LEDs at once (live lighting that recomputes every LED as a game runs), use /ledstrip/frame or /ledstrip/ranges below: they set any number of LEDs and refresh the strip once. See Custom Animations for complete examples.
Set Frame (bulk pixels)
Set a run of LEDs from raw RGB bytes and refresh the strip once. The body is 3 bytes per LED (red, green, blue) in strip order, up to 2000 LEDs. LEDs outside the run keep their colors. Nothing is started or stopped: a zone with a running effect draws over these pixels, so stop it first (/ledstrip/zone/{zone}/stop or /ledstrip/clear).
Requires pixelweb 8.0.26+ and LED firmware 23.11 or later (check ledStripFrame in /info). Older firmware returns 501.
Parameters
start- Index of the first LED to set (default 0). Absolute strip index; zones andreversedon't apply.- Body - Raw bytes, length a multiple of 3. Send it as
application/octet-stream.
Examples
# Set the first 144 LEDs from a 432-byte file curl --data-binary @frame.bin -H "Content-Type: application/octet-stream" "localhost:8080/ledstrip/frame?start=0" # Three LEDs from index 10: red, green, blue printf '\xff\x00\x00\x00\xff\x00\x00\x00\xff' | curl --data-binary @- "localhost:8080/ledstrip/frame?start=10"
Response
{
"success": true,
"start": 0,
"count": 144
}Speed: a frame of up to 168 LEDs is one command to the LED board; longer frames are sent in 168-LED pieces, then one refresh. Measured on a V2 board over USB: about 200 frames a second for 144 LEDs and about 90 for 384. Keep one HTTP connection open (keep-alive) and wait for each response before sending the next frame.
Set Ranges (several runs, one refresh)
Set several solid-color runs and refresh the strip once. Use it when a frame is mostly blocks of one color; use /ledstrip/frame when every LED differs. Same firmware requirement and same rules as /ledstrip/frame (check ledStripRanges in /info).
Parameters
set- Runs separated by;(raw or encoded as%3B). Each run isstart,count,RRGGBB: first LED index, number of LEDs, and a 6-digit hex color (a leading#is allowed, encoded as%23). Up to 2000 LEDs in total.
Example
# LEDs 0-39 red, 40-51 green, 52-71 blue
curl "localhost:8080/ledstrip/ranges?set=0,40,ff0000;40,12,00ff00;52,20,0000ff"Response
{
"success": true,
"ranges": 3,
"count": 72
}Custom Animations (stream your own frames)
The firmware's built-in effects (/ledstrip/zone/{zone}/effect/{effect}) run on the LED board by themselves: one call starts them, and they need nothing more from your program. With /ledstrip/frame, your program draws the animation itself and sends it one frame at a time, so it can be anything, and it can react to the game as it happens: a rev meter that follows the engine, a health bar that drains on each hit, lights in a player's color, effects in time with the music. No firmware update is needed for a new animation.
How it works:
- Work out every LED's color, send the frame (3 bytes per LED: red, green, blue) with
POST /ledstrip/frame, wait for the response, and repeat. 30 to 60 frames a second looks smooth; a 144-LED strip can take about 200. - Time frames to a clock (frame n is due at start + n/fps), so the time spent sending doesn't slow the animation down.
- Keep one HTTP connection open (all three examples do).
- Stop any built-in effect on those LEDs first (
/ledstrip/zone/{zone}/stopor/ledstrip/clear), or it draws over your frames. To animate one zone and leave the rest alone, send just that zone's LEDs with?start=. - If your program stops, the strip keeps its last frame: send an all-black frame (or call
/ledstrip/clear) when you finish. - Check
ledStripFramein/infofirst: it needs pixelweb 8.0.26+ and LED firmware 23.11 or later.
Set N in each example to your strip's length (GET /ledstrip/getpixelcount). Each one fakes its game values; in your program they come from the game (MAME outputs, a racing game's telemetry, your frontend's events).
Example 1: rev meter (Python)
The strip fills green to yellow to red as the engine revs, blinks white at the redline, flashes blue on each gear shift through five gears. Python 3, no extra packages: python3 rev_meter.py.
# rev_meter.py -- a racing rev meter. Python 3, no extra packages.
import http.client, time
N = 144 # LEDs on your strip (GET /ledstrip/getpixelcount)
FPS = 60
conn = http.client.HTTPConnection("localhost", 8080) # one connection, kept open
def send(pixels):
"""pixels: N (r, g, b) tuples. Sets the whole strip with one refresh."""
body = bytes(v for rgb in pixels for v in rgb)
conn.request("POST", "/ledstrip/frame", body, {"Content-Type": "application/octet-stream"})
conn.getresponse().read()
def meter_colour(f): # green -> yellow -> red along the strip
if f < 0.6:
return (int(255 * f / 0.6), 255, 0)
return (255, int(255 * (1 - (f - 0.6) / 0.4)), 0)
rpm, gear, flash = 0.15, 1, 0.0
start, frame = time.time(), 0
while gear <= 5:
dt = 1 / FPS
# A real controller reads rpm and gear from the game (MAME outputs, telemetry).
rpm += dt * 0.55 / gear ** 0.5
if rpm >= 1.0: # redline: shift up
gear, rpm, flash = gear + 1, 0.45, 1.0
lit = rpm * N
blink = rpm > 0.9 and int(time.time() * 16) % 2
px = []
for i in range(N):
c = meter_colour(i / N) if i < lit else (0, 0, 6)
if blink and i < lit:
c = (255, 255, 255)
if flash: # blue flash on a gear shift
c = (c[0], min(255, int(c[1] + 80 * flash)), min(255, int(c[2] + 255 * flash)))
px.append(c)
flash = max(0.0, flash - dt * 5)
send(px)
frame += 1
time.sleep(max(0, start + frame / FPS - time.time())) # stay on the clock
send([(0, 0, 0)] * N) # clearExample 2: health bar (JavaScript)
A fighting-game health bar: each hit flashes red, the lost health shows white and drains away, the bar turns from green to red and pulses when health is low, and at zero the strip flashes red and fades. Call hit(damage) from your own game event. Node.js 18 or later: node health_bar.mjs.
// health_bar.mjs -- a fighting-game health bar. Node.js 18 or later: node health_bar.mjs
const N = 144; // LEDs on your strip
const FPS = 60;
async function send(pixels) { // pixels: N [r, g, b] arrays
const body = new Uint8Array(N * 3);
pixels.forEach(([r, g, b], i) => body.set([r, g, b], i * 3));
await fetch("http://localhost:8080/ledstrip/frame", {
method: "POST",
headers: { "Content-Type": "application/octet-stream" },
body,
});
}
let health = 1; // 0..1
let shown = 1; // the white "damage" part drains down to health
let flash = 0;
function hit(damage) { // call this from your game event (player hit)
health = Math.max(0, health - damage);
flash = 1;
}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const start = Date.now();
let frame = 0, nextHit = 0.8, koAt = null;
while (true) {
const t = (Date.now() - start) / 1000;
if (t > nextHit && health > 0) { // fake hits for the demo
hit(0.08 + Math.random() * 0.12);
nextHit = t + 0.5 + Math.random() * 0.7;
}
if (health === 0 && koAt === null) koAt = t;
if (koAt !== null && t - koAt > 2) break;
shown = Math.max(health, shown - 0.5 / FPS);
const low = health < 0.25 ? 0.5 + 0.5 * Math.sin(t * 12) : 1; // pulse when low
const g = Math.round(255 * Math.min(1, health * 2)); // green -> red
const r = Math.round(255 * Math.min(1, (1 - health) * 2));
const px = [];
for (let i = 0; i < N; i++) {
const f = i / N;
let c = [0, 0, 8];
if (f < health) c = [Math.round(r * low), Math.round(g * low), 0];
else if (f < shown) c = [255, 255, 255];
if (flash > 0) c = c.map((v, k) => Math.min(255, Math.round(v + flash * [255, 0, 0][k])));
if (koAt !== null) { // knocked out: the strip flashes red and fades
const k = Math.max(0, 1 - (t - koAt) / 2) * (Math.floor(t * 8) % 2);
c = [Math.round(255 * k), 0, 0];
}
px.push(c);
}
flash = Math.max(0, flash - 4 / FPS);
await send(px);
frame++;
await sleep(Math.max(0, start + (frame * 1000) / FPS - Date.now()));
}
await send(Array(N).fill([0, 0, 0])); // clearExample 3: scanner (PowerShell)
A light sweeps back and forth with a fading tail for 10 seconds; change $Color for a player's color. Runs on Windows with nothing to install (Windows PowerShell 5.1 or PowerShell 7): powershell -ExecutionPolicy Bypass -File scanner.ps1.
# scanner.ps1 -- a light that sweeps back and forth with a fading tail.
# Windows PowerShell 5.1 or PowerShell 7: powershell -ExecutionPolicy Bypass -File scanner.ps1
param([string]$Server = "http://localhost:8080")
Add-Type -AssemblyName System.Net.Http
$N = 144 # LEDs on your strip
$Fps = 60
$Color = @(255, 0, 0) # red; try a player's colour
$client = New-Object System.Net.Http.HttpClient # keeps the connection open
function Send-Frame([byte[]]$frame) {
$content = New-Object System.Net.Http.ByteArrayContent(,$frame)
$content.Headers.ContentType = "application/octet-stream"
$client.PostAsync("$Server/ledstrip/frame", $content).Result.Dispose()
}
$clock = [Diagnostics.Stopwatch]::StartNew()
$frameNo = 0
while ($clock.Elapsed.TotalSeconds -lt 10) {
$t = $clock.Elapsed.TotalSeconds
$pos = ($N - 1) * (0.5 - 0.5 * [Math]::Cos($t * 2.5)) # eases at each end
$frame = New-Object byte[] ($N * 3)
for ($i = 0; $i -lt $N; $i++) {
$k = [Math]::Max(0, 1 - [Math]::Abs($i - $pos) / 12) # brightness by distance
$k = $k * $k
for ($c = 0; $c -lt 3; $c++) { $frame[$i * 3 + $c] = [byte]($Color[$c] * $k) }
}
Send-Frame $frame
$frameNo++
$wait = $frameNo * 1000 / $Fps - $clock.Elapsed.TotalMilliseconds
if ($wait -gt 0) { Start-Sleep -Milliseconds $wait }
}
Send-Frame (New-Object byte[] ($N * 3)) # clearLED Strip Configuration
Set Brightness
Set LED strip brightness (0-255).
Example
curl localhost:8080/ledstrip/brightness/128
Get Brightness
Read current LED strip brightness from device.
Example
curl localhost:8080/ledstrip/getbrightness
Response
{
"brightness": 128,
"percentage": 50,
"success": true
}Set Pixel Count
Configure total number of LEDs (1-2000).
Example
curl localhost:8080/ledstrip/numpixels/300
Get Pixel Count
Read current pixel count from device.
Example
curl localhost:8080/ledstrip/getpixelcount
Response
{
"numPixels": 762,
"success": true
}Enable/Disable LED Strip
Enable or disable the LED strip.
Example
curl "localhost:8080/ledstrip/enabled?enabled=true"
Control LED Processing
Endpoints
- GET
/ledstrip/pause- Pause Core1 (LED processing) - GET
/ledstrip/restart- Restart Core1 (LED processing)
Examples
curl localhost:8080/ledstrip/pause curl localhost:8080/ledstrip/restart
Zone Management
Configure Zone
Configure a LED zone with optional reverse direction for strip zones.
Parameters
start,end- Pixel rangename- Zone nametype- Zone type (strip/matrix/button)resolution- Matrix resolution, written heightxwidth (8x8, 8x32, 16x16, etc.).8x32is 32 wide and 8 high.reverse- Strip zones only: effects run from the zone's end back to its start. Raw/ledstrip/pixeland/ledstrip/rangewrites use absolute strip indexes and aren't affected.flip- Matrix zones only: turns the picture 180° for a matrix mounted upside down.
Matrix wiring: column by column, serpentine. With flip off, LED 0 is the bottom-right pixel of the picture and runs up that column; the next column runs down, and so on. With flip=true, LED 0 is the top-left pixel and runs down.
Examples
curl "localhost:8080/ledstrip/zone/0/setup?start=0&end=63&name=left_matrix&type=matrix&resolution=8x8" curl "localhost:8080/ledstrip/zone/1/setup?start=64&end=127&name=right_strip&type=strip&reverse=true"
Delete Zone
Delete a configured LED zone.
Example
curl localhost:8080/ledstrip/zone/0/delete
Zone Effect Control
Start an effect on a specific zone (by ID or name).
Examples
curl "localhost:8080/ledstrip/zone/0/effect/matrix_ripple?r=0&g=255&b=255" curl "localhost:8080/ledstrip/zone/left_matrix/effect/matrix_ripple?r=0&g=255&b=255"
Stop Zone Effects
Stop effects on a specific zone (by ID or name) or on all zones. Use this to take a zone over from an effect; follow it with your own pixel or range writes, or use clear to also turn the zone off.
Examples
curl localhost:8080/ledstrip/zone/0/stop curl localhost:8080/ledstrip/zone/all/stop
Clear Zone
Clear and stop effects on a specific zone.
Example
curl localhost:8080/ledstrip/zone/0/clear
Button Zone Control
Control button zone state and color.
Examples
curl "localhost:8080/ledstrip/button/0?state=on&r=255&g=0&b=0" curl "localhost:8080/ledstrip/button/0?state=off"
Get Zone Configuration
Get zone configuration. Use all=true to include inactive zones.
Examples
curl localhost:8080/ledstrip/zones/config curl "localhost:8080/ledstrip/zones/config?all=true"
Matrix Text & Score Display
Matrix Text
Display scrolling text on a matrix zone (by ID or name).
Parameters
text- Text to display (use %20 for space to clear)r,g,b- Text color (0-255)bgr,bgg,bgb- Background color (0-255)speed- Scroll speed (1-255, higher = faster)font- Font type (0=5x7_original, 1=3x5_compact, 2=4x6_balanced, 3=3x7_narrow)ltr- Left-to-right scrolling (add parameter for LTR)
Examples
curl "localhost:8080/ledstrip/zone/0/matrix/text?text=PLAYER%201&r=255&g=255&b=255&speed=120" curl "localhost:8080/ledstrip/zone/score_matrix/matrix/text?text=GAME%20OVER&font=2" curl "localhost:8080/ledstrip/zone/0/matrix/text?text=%20"
Stop Matrix Text
Stop matrix text display on a specific zone.
Example
curl localhost:8080/ledstrip/zone/0/matrix/text/stop
Matrix Score
Display static score/text on a matrix zone (by ID or name).
Parameters
text- Score/text to display (use %20 for space to clear)font- Font type (0=5x7_original, 1=3x5_compact, 2=4x6_balanced, 3=3x7_narrow)r,g,b- Text color (0-255)bgr,bgg,bgb- Background color (0-255)centerx,centery- Center alignment (default: true)offsetx,offsety- Position offset (-127 to 127)
Examples
curl "localhost:8080/ledstrip/zone/0/matrix/score?text=98765&font=3&r=0&g=255&b=0" curl "localhost:8080/ledstrip/zone/score_zone/matrix/score?text=HIGH%20SCORE¢erx=true" curl "localhost:8080/ledstrip/zone/0/matrix/score?text=%20"
Stop Matrix Score
Stop matrix score display on a specific zone.
Example
curl localhost:8080/ledstrip/zone/0/matrix/score/stop
Auto-Detection Features
Auto Score Display
Automatically finds best available display for score (dot matrix, 7-segment, or WS2812B matrix).
Examples
curl "localhost:8080/ledstrip/score?s=98765&font=2&r=0&g=255&b=0" curl "localhost:8080/ledstrip/score?s=%20"
Stop Auto Score
Stop auto-detected score display.
Example
curl localhost:8080/ledstrip/score/stop
Auto Text Display
Automatically finds best zone for text display.
Examples
curl "localhost:8080/ledstrip/text?text=PLAYER%201&r=255&g=255&b=255&speed=120" curl "localhost:8080/ledstrip/text?text=%20"
Stop Auto Text
Stop auto-detected text display.
Example
curl localhost:8080/ledstrip/text/stop
Manufacturer Display
Display manufacturer/publisher name for a MAME ROM using metadata lookup.
Parameters
rom- MAME ROM name (e.g., "pacman", "galaga")r,g,b- Text color (default: 255,255,255)speed- Scroll speed (default: 90)
Examples
curl "localhost:8080/ledstrip/manufacturer?rom=pacman" curl "localhost:8080/ledstrip/manufacturer?rom=galaga&r=0&g=255&b=255&speed=100"
Response
{
"rom": "pacman",
"publisher": "Namco",
"gameName": "Pac-Man",
"year": "1980",
"zone": 0,
"zoneName": "text_matrix",
"status": "success"
}Batch Zone Control
Send effects to multiple zones in a single API call for synchronized lighting effects. Two batch modes are available: simple (same effect on all zones) and multi-effect (different effects per zone).
Simple Batch (Same Effect on Multiple Zones)
Apply the same effect with identical parameters to multiple zones simultaneously.
Parameters
zones- Comma-separated list of zone names or IDs (required)effect- Effect name to apply to all zones (required)r,g,b- Primary color (0-255)speed- Effect speed (1-255)loops- Number of loops (0=infinite)reverse- Reverse direction (true/false)intensity- Brightness (0-255)duration- Duration in seconds
Examples
# Chase effect on left and right strips with 3 loops curl "http://localhost:8080/ledstrip/batch/simple?zones=left_strip,right_strip&effect=chase&r=0&g=255&b=255&speed=60&loops=3&reverse=false" # Rainbow effect on all speaker rings curl "http://localhost:8080/ledstrip/batch/simple?zones=left_speaker_ring,right_speaker_ring&effect=rainbow&speed=100&intensity=200" # Pulse effect on multiple zones curl "http://localhost:8080/ledstrip/batch/simple?zones=left_strip,right_strip,left_matrix,right_matrix&effect=pulse&r=255&g=0&b=128&speed=80"
Multi-Effect Batch (Different Effects Per Zone)
Apply different effects with unique parameters to each zone in a single batched command. Zone configurations are separated by @ and parameters within each zone are separated by ~.
Zone Configuration Format
zone~effect~r~g~b~speed~loops~reverse
Multiple Zones Format
zones=zone1~effect~r~g~b~speed~loops~reverse@zone2~effect~r~g~b~speed~loops~reverse@...
Parameters per zone (tilde-separated)
zone- Zone name or ID (required)effect- Effect name (required)r- Red value (0-255)g- Green value (0-255)b- Blue value (0-255)speed- Effect speed (1-255)loops- Number of loops (0=infinite)reverse- Reverse direction (true/false)
Examples
# Three zones with different effects curl "http://localhost:8080/ledstrip/batch?zones=left_strip~pulse~255~0~0~50~3~false@right_strip~chase~0~255~0~60~0~true@left_speaker_ring~fadecolor~100~100~255~40~5~false" # Left and right strips with mirrored chase effects curl "http://localhost:8080/ledstrip/batch?zones=left_strip~chase~255~128~0~70~0~false@right_strip~chase~255~128~0~70~0~true" # Matrix and strip combination curl "http://localhost:8080/ledstrip/batch?zones=center_matrix~matrix_ripple~0~255~255~100~0~false@left_strip~comet~255~0~128~80~0~false@right_strip~comet~255~0~128~80~0~true"
Notes
- Invalid zones or effects are skipped with a warning (batch continues with valid entries)
- All zones in a batch are updated in a single USB command for tight synchronization
- Default parameters from query string are used if zone-specific parameters are omitted
- Use the simple batch endpoint when applying identical effects for cleaner URLs
MAX7219 APIs
7-Segment Display
Display Text
Display text on 7-segment display. Only characters renderable on a 7-segment display are supported — unsupported characters show as blank.
Supported characters
- Digits:
0–9 - Decimal point:
.— attaches to the preceding character's segment (does not consume a digit position). Example:3.14displays as 3 digits with a dot after the 3. - Letters:
A,b,C,c,d,E/e,F,G,H/h,J,L/l,n,O/o,P/p,r,S,t,U/u,y - Minus:
- - Underscore:
_(bottom bar) - Double dash:
= - Space: blank segment
b, d, n, r) — uppercase versions render the same shape. S is identical to 5, O is identical to 0.Clock format example: HHhMM.SS — use h as an hour/minute separator and . for the decimal point on the minutes digit.
Examples
curl "localhost:8080/max7219/7seg/text?text=12h34.56&brightness=8" curl "localhost:8080/max7219/7seg/text?text=3.14" curl "localhost:8080/max7219/7seg/text?text=tEStEd" curl "localhost:8080/max7219/7seg/text?text=Error" curl "localhost:8080/max7219/7seg/text?text=-42"
Display Number
Display number on 7-segment display. Use s=%20 (space) to clear.
Examples
curl "localhost:8080/max7219/7seg/number?s=12345&brightness=10" curl "localhost:8080/max7219/7seg/number?s=%20"
Set Brightness
Set 7-segment brightness (0-15).
Example
curl "localhost:8080/max7219/7seg/brightness?brightness=12"
Clear Display
Clear 7-segment display.
Example
curl localhost:8080/max7219/7seg/clear
Configure Modules
Configure 7-segment module count (4 or 8).
Example
curl "localhost:8080/max7219/7seg/config?modules=8"
Enable/Disable
Enable or disable 7-segment display.
Example
curl "localhost:8080/max7219/7segment/enabled?enabled=true"
Reinitialize
Re-sends the hardware init signal to the 7-segment display without changing any config. Useful if the display loses state after a power cut or firmware restart.
Example
curl localhost:8080/max7219/7seg/reinit
Dot Matrix Display
Matrix Text
Display scrolling text on matrix display.
Parameters
text- Text to displaybrightness- Brightness (0-15)font- Font type (0=8x8, 1=small)loops- Number of loops (1-65535)speed- Speed in milliseconds (20-2000)
Example
curl "localhost:8080/max7219/matrix/text?text=HELLO&brightness=10&font=0&loops=3&speed=200"
Matrix Score
Display score on matrix display.
Parameters
s- Score/text to displaybrightness- Brightness (0-15)font- Font type (0=8x8, 1=small)loops- Number of loops (1-65535)speed- Speed in milliseconds (20-2000)
Example
curl "localhost:8080/max7219/matrix/score?s=98765&brightness=10&font=0&loops=1&speed=160"
Set Pixel
Set individual pixel on matrix display.
Example
curl "localhost:8080/max7219/matrix/pixel?x=4&y=3&state=on"
Matrix Configuration
Endpoints
- GET
/max7219/matrix/brightness?brightness={brightness}- Set brightness (0-15) - GET
/max7219/matrix/clear- Clear matrix display - GET
/max7219/matrix/config?modules={count}- Configure module count (4 or 8) - GET
/max7219/matrix/enabled?enabled={true/false}- Enable/disable matrix - GET
/max7219/matrix/modules?modules={count}- Set module count (4 or 8)
Examples
curl "localhost:8080/max7219/matrix/brightness?brightness=12" curl localhost:8080/max7219/matrix/clear curl "localhost:8080/max7219/matrix/config?modules=8" curl "localhost:8080/max7219/matrix/enabled?enabled=true"
Reinitialize
Re-sends the hardware init signal to the dot matrix display without changing any config. Useful if the display loses state after a power cut or firmware restart.
Example
curl localhost:8080/max7219/matrix/reinit
Reinitialize All MAX7219 Displays
Reinitializes all enabled MAX7219 displays (7-segment and/or dot matrix) in one call — identical to what Pixelcade runs at startup. No config changes are made.
Example
curl localhost:8080/max7219/reinit
Mini LCD (1602/2004) APIs
Basic Display Functions
Print Text
Print text at current cursor position.
Example
curl "localhost:8080/minilcd/print?text=Hello%20World"
Print At Position
Print text at specific position.
Example
curl "localhost:8080/minilcd/printat?text=Score&col=0&row=1"
Clear Display
Clear entire LCD display.
Example
curl localhost:8080/minilcd/clear
Set Cursor
Set cursor position for next print operation.
Example
curl "localhost:8080/minilcd/setcursor?col=5&row=1"
Advanced Functions
Center Text
Center text on specified row.
Example
curl "localhost:8080/minilcd/centertext?text=GAME%20OVER&row=1"
Clear Row
Clear a specific row.
Example
curl "localhost:8080/minilcd/clearrow?row=2"
Backlight Control
Control LCD backlight.
Examples
curl "localhost:8080/minilcd/backlight?state=on" curl "localhost:8080/minilcd/backlight?state=off"
Game Information
Display game information from metadata.
Example
curl "localhost:8080/minilcd/gameinfo?console=mame&rom=pacman"
Response
{
"status": "success",
"console": "mame",
"rom": "pacman",
"platform": "MAME",
"game": {
"id": "pacman",
"name": "Pac-Man",
"year": "1980",
"publisher": "Namco",
"genre": "Maze"
},
"message": "Game info displayed on Mini LCD"
}Mini Statistics
(also available as /minilcd/ministats)
Display up to 4 lines of game statistics on the Mini LCD. Lines are filled in order: level/stage, lives, then generic items (item1–item4), then legacy shooting stats. Any combination is valid as long as at least one line of data is provided.
Parameters
label,value- Level/stage info (line 1)livesLabel,livesValue- Lives/ships info (line 2 if level present, otherwise line 1)item1Label,item1Value— Generic item 1 (both required as a pair)item2Label,item2Value— Generic item 2 (both required as a pair)item3Label,item3Value— Generic item 3 (both required as a pair)item4Label,item4Value— Generic item 4 (both required as a pair)shots,hits,ratio- Shooting stats (legacy, label is fixed)
Items are displayed in numeric order (item1 before item2, etc.) and skip any gaps — so item1 and item4 with no item2/item3 will display on consecutive lines. The display is capped at 4 lines total; any params beyond that are silently ignored.
The response includes a lines array showing exactly what was sent to the display.
Examples
# Level and lives curl "localhost:8080/ministats?label=Level&value=5&livesLabel=Lives&livesValue=3" # Defender: ships remaining + bombs curl "localhost:8080/ministats?livesLabel=SHIPS&livesValue=3&item1Label=BOMBS&item1Value=2&ledonly" # Defender: ships + bombs + two more items curl "localhost:8080/ministats?livesLabel=SHIPS&livesValue=3&item1Label=BOMBS&item1Value=2&item2Label=SCORE&item2Value=9450&item3Label=LEVEL&item3Value=4&ledonly" # Four custom stats with no level/lives curl "localhost:8080/ministats?item1Label=SHIPS&item1Value=3&item2Label=BOMBS&item2Value=2&item3Label=SCORE&item3Value=9450&item4Label=LEVEL&item4Value=4&ledonly" # Skipping item2/item3 — item4 still fills the next available line curl "localhost:8080/ministats?livesLabel=SHIPS&livesValue=3&item4Label=BOMBS&item4Value=2&ledonly" # Mix generic items with legacy shots (items take priority, shots fills remaining slot) curl "localhost:8080/ministats?livesLabel=SHIPS&livesValue=3&item1Label=BOMBS&item1Value=2&shots=42&ledonly" # Legacy shooting stats (backwards compatible) curl "localhost:8080/ministats?label=Stage&value=12&shots=150&hits=98&ratio=65"
Configuration
Get Configuration
Get current mini LCD configuration.
Example
curl localhost:8080/minilcd/config
Response
{
"status": "enabled",
"type": "I2C LCD",
"resolution": "20x4",
"address": "0x27",
"backlight": "on"
}Enable/Disable
Enable or disable the mini LCD display.
Example
curl "localhost:8080/minilcd/setenabled?enabled=true"
Set Type
Set LCD type configuration.
LCD Types
0- 16x21- 20x22- 16x43- 20x44- 8x2
Example
curl "localhost:8080/minilcd/settype?type=3"
Response
{
"status": "success",
"type": 3,
"typeName": "20x4",
"message": "Mini LCD type set to 20x4 successfully"
}Important Pulse API Notes
- Hardware Requirements: Pixelcade V2 hardware (purple board) with firmware 23 or higher
- Color Values: RGB parameters use 0-255 range
- Zone Management: Zone IDs can be numeric (0-35) or zone names if configured
- Text Encoding: Text parameters should be URL-encoded (spaces as %20)
- Boolean Parameters: Accept true/false, 1/0, on/off, yes/no
- JSON Responses: Most APIs return JSON responses with status information
- Maximum Zones: 36 zones (0-35) supported for WS2812B LED strips
- Matrix Requirements: Matrix zones require proper resolution configuration for text/score display
- Effect Compatibility: Some effects work better with specific zone types (strip vs matrix)
- Clear Commands: Use text=%20 (URL-encoded space) to clear text/score displays
- Auto-Detection: Auto-detection APIs automatically choose the best available display type
- Zone Names: Zone names can be used instead of IDs for most zone-specific endpoints
- Strip Zones: Support optional reverse parameter during setup
- Font Types: 0=5x7_original, 1=3x5_compact, 2=4x6_balanced, 3=3x7_narrow
- Module Requirements: 7-segment and dot matrix displays require 8+ modules for score display capability
- Mini LCD Support: Multiple display types supported (16x2, 20x2, 16x4, 20x4, 8x2)
- Metadata Required: Game info and manufacturer APIs require corresponding metadata JSON files
Sidekick Custom Card
Pixelcade Sidekick is a small companion display (boards from 2.1" to 10.1" connected over USB or WiFi, plus the free Sidekick app for iPhone, iPad and Android) that shows info cards -- box art, game description, controller legend, and more -- alongside your cabinet's main display. This endpoint lets an external tool (e.g. an in-game effects engine) push a one-off custom card to a connected Sidekick display, outside the normal per-game card rotation.
Running two identical Sidekick displays on the same cabinet? Most models have no per-unit hardware serial, so model alone can't tell two of the same board apart -- assign each one a nickname in Companion's Sidekick settings (device list → "Nickname" field), then use the nickname param on /sidekick/card below to target one specific physical unit. (Not yet available on /sidekick/hud/* -- see that section's own model param note.)
Supported Devices
Every model param used throughout the Sidekick API (/sidekick/card, /sidekick/hud/*) is one of the stable IDs below -- the same list GET/sidekick/devices reports for actually-connected hardware, and the same IDs shown in Companion's own device dropdown.
| ID | Name | Resolution | Touch | WiFi | USB | MCU |
|---|---|---|---|---|---|---|
esp32-oled |
Pixelcade Sidekick LILYGO T-Display S3 AMOLED | 536×240 | No | No | Native USB — VID 303A : PID 83BB |
esp32s3 |
esp32-2 |
Pixelcade Sidekick 2.8" (Resistive) | 320×240 | Yes | Yes | CH340 USB-serial bridge | esp32 |
esp32-3 |
Pixelcade Sidekick 3.5" (Resistive) | 480×320 | Yes | Yes | CH340 USB-serial bridge | esp32 |
esp32-5 |
Pixelcade Sidekick 5" (Sunton) | 800×480 | Yes | Yes | CH340 USB-serial bridge | esp32s3 |
esp32-5-elecrow-advance |
Pixelcade Sidekick 5" (Elecrow Advance v1.3) | 800×480 | Yes | Yes | CH340 USB-serial bridge | esp32s3 |
esp32-4-elecrow-advance |
Pixelcade Sidekick 4.3" (Elecrow Advance) | 800×480 | Yes | Yes | CH340 USB-serial bridge | esp32s3 |
esp32-7-elecrow-advance |
Pixelcade Sidekick 7" (Elecrow Advance) | 800×480 | Yes | Yes | CH340 USB-serial bridge | esp32s3 |
esp32-5-elecrow-advance-v1-1 |
Pixelcade Sidekick 5" (Elecrow Advance v1.1) | 800×480 | Yes | No | CH340 USB-serial bridge | esp32s3 |
esp32-7-elecrow |
Pixelcade Sidekick 7" (Elecrow Basic) | 800×480 | Yes | Yes | CH340 USB-serial bridge | esp32s3 |
esp32-5-elecrow |
Pixelcade Sidekick 5" (Elecrow Basic) | 800×480 | Yes | Yes | CH340 USB-serial bridge | esp32s3 |
esp32-7-sunton |
Pixelcade Sidekick 7" (Sunton) | 800×480 | Yes | Yes | CH340 USB-serial bridge | esp32s3 |
esp32-tab5 |
Pixelcade Sidekick M5Stack Tab5 | 1280×720 | Yes | Yes | Native USB — VID 303A : PID 83BC |
esp32p4 |
esp32-10 |
Pixelcade Sidekick 10.1" (Guition) | 1280×800 | Yes | Yes | Native USB — VID 303A : PID 83BD |
esp32p4 |
esp32-10-guition-v1 |
Pixelcade Sidekick 10.1" (Guition V1) | 1280×800 | Yes | Yes | Native USB | esp32p4 |
esp32-10-elecrow |
Pixelcade Sidekick 10.1" (Elecrow) | 1024×600 | Yes | Yes | Native USB | esp32p4 |
esp32-7-elecrow-ai |
Pixelcade Sidekick 7" (Elecrow AI) | 1024×600 | Yes | Yes | Native USB | esp32p4 |
esp32-5-elecrow-ai-p4 |
Pixelcade Sidekick 5" (Elecrow AI) | 800×480 | Yes | Yes | Native USB | esp32p4 |
esp32-4-waveshare |
Pixelcade Sidekick 4.3" (Waveshare) | 800×480 | Yes | Yes | Native USB | esp32p4 |
esp32-4827s043c |
Pixelcade Sidekick 4.3" (Sunton) | 480×272 | Yes | Yes | CH340 USB-serial bridge | esp32s3 |
esp32-3248s035c |
Pixelcade Sidekick 3.5" (Capacitive) | 480×320 | Yes | Yes | CH340 USB-serial bridge | esp32 |
esp32-3-elecrow-advance |
Pixelcade Sidekick 3.5" (Elecrow Advance) | 480×320 | Yes | Yes | Native USB | esp32s3 |
esp32-2432s024c |
Pixelcade Sidekick 2.4" (Capacitive) | 320×240 | Yes | Yes | CH340 USB-serial bridge | esp32 |
esp32-2-elecrow-round |
Pixelcade Sidekick 2.1" Round (Elecrow) | 480×480 | Yes | Yes | Native USB | esp32s3 |
esp32-3-waveshare |
Pixelcade Sidekick 3.49" Bar (Waveshare) | 640×172 | Yes | No | Native USB | esp32s3 |
esp32-3-lilygo |
Pixelcade Sidekick 3.4" Bar (LilyGO) | 640×180 | Yes | No | Native USB | esp32s3 |
ios-phone |
Pixelcade Sidekick App (iPhone) | 1280×640 | Yes | Yes | Sidekick app over WiFi (no USB) | — |
ios-tablet |
Pixelcade Sidekick App (iPad) | 1280×920 | Yes | Yes | Sidekick app over WiFi (no USB) | — |
android-phone |
Pixelcade Sidekick App (Android Phone) | 1280×640 | Yes | Yes | Sidekick app over WiFi (no USB) | — |
android-tablet |
Pixelcade Sidekick App (Android Tablet) | 1280×800 | Yes | Yes | Sidekick app over WiFi (no USB) | — |
Notes
- Resolution is native landscape orientation (width×height); a portrait-mounted device swaps these.
- CH340 bridge boards (2.8"/3.5"/5"/7") route their serial port through a generic CH340 USB-UART chip, which has no per-unit serial number and can't be told apart from any other CH340 device sharing the same PID — only the Native USB boards (see the USB column) present a real, per-unit-distinguishable USB identity under Espressif's own VID. The Elecrow Advance 5" is a partial exception: it uses a CH340K bridge variant on a distinct PID (
7522), so it can be told apart from the other CH340 boards'7523, but not from a second Elecrow Advance unit -- and not from its own two hardware revisions either:esp32-5-elecrow-advance(HW v1.2/v1.3) andesp32-5-elecrow-advance-v1-1(HW v1.1) are electrically identical over USB, so which firmware to flash has to be picked by reading the small hardware revision marking on the board itself, not auto-detected. - If two connected devices are the same model (indistinguishable by the identity checks above), Companion lets the user assign each a nickname to tell them apart -- see the
nicknameparam on /sidekick/card below. - If a cabinet has two displays of the same model, an unfiltered (no
modelparam) Sidekick API call reaches both. - WiFi boards are set up over USB once (Companion → Sidekick → Configure WiFi) and can then run cable-free. The
ios-*/android-*entries are the Sidekick app, which always connects over WiFi;-phoneor-tabletis picked by the app itself. - GET
/sidekick/devicesreturns the live list of currently connected/configured devices (with their real serial numbers) -- this table is the static reference for what models exist at all.
Push a Custom Card
Pushes a card to one or more connected Sidekick displays. No authentication -- these devices are USB-tethered to this host. Two content modes, mutually exclusive per request: stat (a title, up to 8 label/value rows, and an optional image) or paragraph (a single block of free text). Sending text selects paragraph mode; otherwise the request is treated as stat mode.
The card stays on screen until the next real game-select event (or another /sidekick/card push) replaces it. A paragraph too long to fit one screen automatically gets a PREV/NEXT bar at the bottom, same as every other paginated card -- the physical touchscreen already knows how to page through it, no extra work needed on the caller's side.
Parameters
model— optional. Targets one Sidekick model by its ID from Supported Devices (e.g.esp32-5,esp32-7-sunton,esp32-tab5,ios-tablet— the same IDs returned by GET/sidekick/devices). Omit to broadcast to every connected, configured Sidekick display. If a cabinet has two displays of the same model, both receive the push unless narrowed further withnicknamebelow.nickname— optional. Targets the one device the user has assigned this exact nickname to in Companion's Sidekick settings (device list → "Nickname" field on that device's row) — the way to reach one specific physical unit whenmodelalone can't tell two identical boards apart (most Sidekick boards have no per-unit hardware serial). Combinable withmodel(both must match if both are given); a device with no nickname set never matches this filter.
Stat mode (ignored if text is present):
title— optional card headingimagePath— optional, a local file path already on the Pixelcade hostlabel1…label8,value1…value8— optional row pairs, shown in ordercolor— optional accent color (hex or a named color, e.g.ff6b00ororange— see Sidekick Live HUD's "Color values" note for the full accepted list/format)
At least one of title, imagePath, or a labelN/valueN pair is required in stat mode.
Paragraph mode:
text— the text to display. A literal newline in the value (URL-encode as%0A) becomes a real line break; long text word-wraps and paginates automatically.textColor— optional text color (hex or a named color, e.g.00ff00orgreen— same accepted formats ascolorabove)
Response
{
"status": "success",
"pushed": ["esp32-5-device-serial"]
}pushed lists the serial of every device the card was actually sent to (empty if nothing matched model, or nothing is connected/configured).
Examples
# Stat card: combo counter with an accent color, sent to every connected display curl "localhost:8080/sidekick/card?title=Combo&label1=Streak&value1=x5&color=ff6b00" # Stat card targeting only the 5" display, with an image curl "localhost:8080/sidekick/card?model=esp32-5&title=Boss+Incoming&imagePath=/path/to/boss.png&color=ff0000" # Paragraph card with multiple lines (%0A = newline) curl "localhost:8080/sidekick/card?model=esp32-5&text=Level%20Complete%0AScore%3A%2012450%0ATime%3A%201%3A32&textColor=00ff00" # Targeting one specific unit by nickname (e.g. two identical 5" displays, one named "Left Cabinet" in Companion) curl "localhost:8080/sidekick/card?nickname=Left+Cabinet&title=Boss+Incoming&color=ff0000"
Play a Sound
Triggers a short synthesized chime on every currently-connected speaker-equipped Sidekick display — currently M5Stack Tab5 (esp32-tab5), 10.1" Guition (esp32-10, esp32-10-guition-v1), 10.1" Elecrow (esp32-10-elecrow), 7" Elecrow AI (esp32-7-elecrow-ai) and 3.49" Bar (Waveshare) (esp32-3-waveshare, with a speaker plugged into its 2-pin connector). Silently a no-op on every model without a speaker — this includes the 5" Elecrow AI (esp32-5-elecrow-ai-p4), which has onboard audio hardware and a fully-implemented I2S sound path in firmware, but never produced audible sound on the unit tested, so it isn't treated as speaker-equipped for now. There's no model targeting param like /sidekick/card has — it always fans out to every connected speaker-equipped device.
Parameters
id(query param) orsoundId(JSON body) — required, an integer 1–12:
| id | Sound |
|---|---|
| 1 | New high score |
| 2 | Achievement unlocked |
| 3 | Big explosion |
| 4 | Big explosion #2 |
| 5 | Bonus ship |
| 6 | Next level |
| 7 | Tractor beam |
| 8 | Extra life |
| 9 | Game over |
| 10 | Coin insert |
| 11 | Player 1 button |
| 12 | Player 2 button |
Response
{
"ok": true,
"devicesSent": 1
}devicesSent is how many connected Tab5 displays actually received the chime (0 if none are connected — not an error).
Examples
# Quick manual test via query param curl "localhost:8080/sidekick/sound?id=9" # Same call as a POST with a JSON body curl -X POST localhost:8080/sidekick/sound -H "Content-Type: application/json" -d '{"soundId": 9}'
Sidekick Manual & Game Pages
The QR codes on Sidekick's Manual, History, Move List and Game Description cards — and the Expand button on those cards in the Sidekick app — link to two pages served by pixelweb itself, for reading on a phone. They're plain HTTP on pixelweb's own port with no authentication, so the phone has to be on the same network as the cabinet (guest and hotel WiFi often block this).
Link IDs: {id} is the first 10 hex characters of the SHA-1 of console/rom, e.g. for mame/galaga:
printf 'mame/galaga' | shasum | cut -c1-10
pixelweb only answers for games it has handed a link out for — ones whose card has been shown on a Sidekick, or whose manual has been looked up on ScreenScraper. Any other ID returns 404 ("Pixelcade doesn't know this game").
Game Page
A phone-friendly page for one game, with a tab for each source that has something for it:
- About (
#description) — the game description, same text as the Game Description card - History (
#history) — arcade games only: background, trivia, scoring, tips and staff from arcade-history.com's history.xml - Moves (
#moves) — arcade fighting games and beat-'em-ups: the move list from progettoSNAPS' command.dat, with a tappable list of characters - Manual (
#manual) — a link to the manual below, when ScreenScraper has one
Add the fragment to open on that tab, e.g. /g/63e96eb36e#history. Returns 404 if the game has none of the four.
Game Manual
The game's instruction manual as a PDF (for arcade games, usually the operator manual), from ScreenScraper:
- Already downloaded: served as
application/pdf, inline, with Range support (iOS Safari's viewer uses it). - Not yet: starts the download and returns a small HTML page with a progress bar, which turns into the PDF when it's done. Downloading needs the ScreenScraper login set in Companion's Sidekick settings.
- ScreenScraper has no manual for the game:
404.
Game Manual Download Status
What the progress page polls. Returns JSON, and starts the download if it isn't already running or done:
{"state": "downloading", "done": 1400360, "total": 9454449}state—lookup(asking ScreenScraper for the file),downloading,done,notfound(no manual) orerror(try again later)done/total— bytes downloaded so far and the file's size;totalis0when ScreenScraper doesn't send a size
Examples
# Galaga's game page, History tab, from a phone on the same network http://192.168.1.20:8080/g/63e96eb36e#history # Galaga's manual, and how its download is going curl -o galaga.pdf "localhost:8080/m/63e96eb36e" curl "localhost:8080/m/63e96eb36e/status"
Sidekick Live HUD
A live, incrementally-updated in-game overlay for a Sidekick display — distinct from /sidekick/card's one-shot push. Where a custom card is a single static screen you replace wholesale, the HUD is real session state on the server: init starts a session for a game, then any number of update calls patch just the fields that changed (a new score, a stat, a message) without needing to resend everything else. Built for an external game-tracking tool (e.g. an in-game effects engine) that already knows play-by-play state and wants the display to reflect it live.
Matches a real arcade flow: Insert Coin → Select 1/2 Players (full-screen prompts, before any score exists) → live gameplay HUD (marquee, score, stats, messages) once a player actually starts. The first two are just bigMessage on the same session, not a separate API — see below.
Leaving prompt mode is automatic — clearBigMessage is a convenience, not a requirement. The moment a p1score/p2score update lands, or the SAME (console, rom) gets re-pushed through the normal game-select path (e.g. via /arcade/stream/<console>/<rom> — which is exactly what a Player 1/Player 2 button press typically triggers), the server clears any active bigMessage on its own and reveals the normal HUD. A caller that never sends clearBigMessage/an empty bigMessage at all — e.g. one that only tracks score/stats and has no separate "player started" event of its own — still works correctly: the first real score update is what reveals the HUD. Call clearBigMessage explicitly only when you want the prompt gone at some OTHER specific moment (e.g. right when a player is selected, before any score exists yet) rather than waiting for the first score.
Color values: every color param on this API (and on /sidekick/card's color/textColor) accepts either a 6-digit hex code (ff4500, #ff4500 — the # is optional, and must be URL-encoded as %23 if included) or a named color: white, red, green, blue, yellow, cyan, gray, darkgray, lightgray, magenta, orange, pink (case-insensitive). Omitting a color param keeps that field's built-in default; a value that's neither a known name nor valid hex also falls back to that default rather than erroring.
Start a HUD Session
Starts (or restarts) a HUD session on the target device(s). Resolves the header logo and game name the same way a real per-game push already would — the caller never uploads an image, just names the game. Every field resets: no score/stats/message, cheat/paused off. Overrides/clears any active /sidekick/card push on the same device; the two are mutually exclusive display modes.
Parameters
console,rom— required. Same console/rom naming as the rest of the API (e.g.console=mame&rom=galaga).model— optional. Same convention as/sidekick/card'smodelparam — omit to broadcast to every connected, configured display; a device serial is never used, since it's often just an unstable OS port path. Unlike/sidekick/card, there is nonicknameparam here yet — if a cabinet has two identical-model displays,modelalone reaches both; per-unit HUD targeting isn't available.title— optional. Overrides the header's game name with this text instead of the name resolved from console/rom (which otherwise falls back through curated data to the raw rom string) — useful when the caller already knows the real display name. No extra work needed to make it fit; the header sizes its font to whatever text it's given.- Header logo: resolved automatically, no param needed — prefers the same high-res logo
/sidekick/card/box art use (sidekicklogos/) and only falls back to the lower-res marquee art if no high-res logo exists for this console/rom. bigMessage— optional. Land directly in full-screen prompt mode (e.g.INSERT COIN) with zero gap, instead of a separateupdatecall right after init. Flashes automatically — seebigMessageunder Update below.color— optional, only meaningful alongsidebigMessage. Sets that message's text color (see Color values above) — its own dedicated setting, independent ofcolor4below, so a later stats message box isn't forced to share it. Omit for the built-in amber default.flashing— optional, only meaningful alongsidebigMessage, defaults toon. The server owns a repeating blink timer, so the message flashes on its own with no further calls needed. Passflashing=offfor a steady/static message instead.color1…color4— optional, same meaning as in Update below. Worth setting at init time since a game's palette is usually already known the instant the ROM is.p1ScoreLabelColor,p1ScoreValueColor,p2ScoreLabelColor,p2ScoreValueColor,statLabelColor,statValueColor— optional, same meaning as in Update below. Also worth setting at init time alongsidecolor1…color4.
Response
{
"status": "success",
"started": ["esp32-5-device-serial"],
"gameName": "Galaga"
}Update a HUD Session
Patches only the fields present in the request against each target device's active session. A device with no active session (update called before init, or after clear) is silently skipped — update never auto-starts one.
Parameters
model— optional, same targeting convention as above.bigMessage— sending it (even as an empty string) sets/clears full-screen prompt mode. Set: marquee + game name + this message, large, centered, and flashing on its own by default (the server owns the blink timer — no need to toggle it from the caller's side; seeflashingbelow to turn that off). Every other field (scores, stats, cheat, message) keeps updating underneath but isn't drawn until cleared. Empty: reveals the normal HUD with whatever's accumulated in the meantime, and stops any blink timer.clearBigMessage— optional, not required for normal use (see the auto-clear note above). A dedicated, unambiguous alternative to sendingbigMessage=as an empty string, for when you want prompt mode to end at a specific moment of your own choosing rather than waiting for the automatic clear. Just include the param (any value, or none at all, e.g.?clearBigMessage) to leave prompt mode and reveal the normal HUD. Wins over abigMessagevalue sent in the same call, if somehow both are present.color— optional, only takes effect alongside a non-emptybigMessagein the SAME call. Sets that message's text color (see Color values above), independent ofcolor4. Omit for the built-in amber default.p1score(also acceptsp0score, zero-indexed — some callers, e.g. DOFLinx, number players from 0),p2score— sending either for the first time in a session reveals that player's score block and keeps it visible for the rest of the session, even if a later update omits it. P1 alone renders centered; once P2 has ever been sent, both render side by side. Also the trigger for the automaticbigMessageclear described above. Accepts thousands-comma-formatted values (e.g.1,420, URL-encoded as1%2C420) as well as a plain integer — either way, the display itself always renders the score with thousands-separator commas (e.g.45,600) for readability.p1ScoreLabelColor,p1ScoreValueColor,p2ScoreLabelColor,p2ScoreValueColor— optional (see Color values above), finer-grained overrides on top ofcolor1/color2for each score block's "PLAYER 1/2 SCORE" label vs. its number independently (e.g. tint the label one color and the digits another). Label falls back tocolor1/color2(then a built-in cyan/red default); value falls back to plain white if unset. Persist across calls once set, same ascolor1…color4.stat1Label…stat8Label,stat1Value…stat8Value— up to 8 generic label/value stats (credits, lives, hits, shots, ratio — whatever's actually sent), rendered as one compact row (Credits: 2 Lives: 3). Whole-block-replace: sending ANY stat param replaces the entire stat row with just what's in that call, not merged with what was there before — avoids stale leftover items from an earlier, unrelated update.statLabelColor,statValueColor— optional (see Color values above), tint the stat row's labels vs. values independently (e.g. "Credits"/"Lives" in one color, their numbers in another). Each falls back tocolor3if unset. Persists across calls once set, unlike the stat items themselves.cheat—on/off. Small indicator in the header's top-right corner, lit or unlit. Only shows once a score has been revealed (never during Insert-Coin-style prompts).paused—on/off. Draws "PAUSED" diagonally across the entire screen, on top of everything else, in both HUD and bigMessage mode.color1…color4— optional (see Color values above):color1/color2tint the P1/P2 score blocks,color3tints divider lines and the stat row,color4is the fallback for the message text below whenmsgLabelColor/msgValueColoraren't set. Omit any to keep the built-in default.msgLabel1…msgLabel6,msgValue1…msgValue6(case-insensitive —MsgLabel1/MsgValue1etc. also accepted) — up to 6 message items, plain text with no surrounding box. Layout depends on how many items are sent: exactly one item renders as flowing, word-wrapped inline text ("Label: Value", or just the value/label alone if the other half is blank) — good for a one-off update like RetroAchievements' progress line. Two or more items render as a grid instead: all labels on one row, all values on the row below, one column per item — easier to scan than several "Label: Value" pairs strung together (e.g.Shots/Hits/Ratiorenders as three labeled columns, not "Shots: 140 Hits: 90 Ratio: 55%" wrapped across lines). Same whole-block-replace rule as stats — any msg param replaces the entire message with just what's in that call.msgLabelColor,msgValueColor— optional (see Color values above), tint every message item's label half and value half independently (e.g. labels in one color, their numbers in another). Unlike the message items themselves, each of these persists across calls once set, rather than needing to be resent with every message update; falls back tocolor4, then the built-in amber default, if never set.msgDurationSec— optional, only meaningful alongside a message update. When set (>0), the message auto-clears itself after that many seconds. A newer message update always supersedes any pending clear from an older one. Omit or send 0 for a message that stays until explicitly replaced.flashing— optional, defaults toonwhen present with no value (e.g. a bare?flashing). Only takes effect alongside content in the SAME call, and means something different depending on which: alongside a non-emptybigMessage, it blinks the full-screen prompt (this is already the default forbigMessageeven without passingflashingexplicitly — see above). Alongside a message update (msgLabel*/msgValue*), it blinks the message block instead — but unlikebigMessage, a message defaults to steady/static, so it only flashes when this same call explicitly includesflashing(orflashing=on). The two blinks run on independent server-side timers, so a flashingbigMessageand a flashing message block never fight over the same clock. Passflashing=offto force either back to steady. Re-sendingmsgLabel/msgValuewithoutflashingstops any blink already running for the previous message.
Response
{
"status": "success",
"updated": ["esp32-5-device-serial"]
}Clear a HUD Session
Ends the HUD session on the target device(s). The display reverts to whatever the normal per-game rotation would show, same as a real game-select.
Parameters
model— optional, same targeting convention as above.
Response
{
"status": "success",
"cleared": ["esp32-5-device-serial"]
}Example — a full arcade session
# Game selected -- straight into a flashing Insert Coin prompt, with a # caller-supplied display name/title, the prompt in cyan, and independently # colored P1/P2 score labels vs. values + stat row set up ahead of time curl "localhost:8080/sidekick/hud/init?model=esp32-5&console=mame&rom=1942&title=1942+Loop+Master&bigMessage=INSERT+COIN&color=cyan&p1ScoreLabelColor=yellow&p2ScoreLabelColor=magenta&statLabelColor=green&statValueColor=pink" # Credit inserted -- still a full-screen prompt, now flashing in orange instead curl "localhost:8080/sidekick/hud/update?model=esp32-5&bigMessage=SELECT+1+OR+2+PLAYERS&color=orange" # Player selected -- leave prompt mode and reveal the HUD curl "localhost:8080/sidekick/hud/update?model=esp32-5&clearBigMessage" # P1 starts playing curl "localhost:8080/sidekick/hud/update?model=esp32-5&p1score=32800" # P2 joins -- score blocks switch to side-by-side curl "localhost:8080/sidekick/hud/update?model=esp32-5&p2score=15420" # Gameplay progresses curl "localhost:8080/sidekick/hud/update?model=esp32-5&p1score=45600&stat1Label=Credits&stat1Value=2&stat2Label=Lives&stat2Value=3" # A stats-style message with independently colored labels/values, flashing # to grab attention, auto-clearing after 5 seconds curl "localhost:8080/sidekick/hud/update?model=esp32-5&msgLabel1=Shots&msgValue1=140&msgLabel2=Hits&msgValue2=90&msgLabel3=Ratio&msgValue3=55%25&msgLabelColor=cyan&msgValueColor=white&flashing&msgDurationSec=5" # A later message update with no flashing param -- renders steady/static instead curl "localhost:8080/sidekick/hud/update?model=esp32-5&msgLabel1=Wave&msgValue1=4" # Cheat engaged, then disengaged curl "localhost:8080/sidekick/hud/update?model=esp32-5&cheat=on" curl "localhost:8080/sidekick/hud/update?model=esp32-5&cheat=off" # Game paused, then resumed curl "localhost:8080/sidekick/hud/update?model=esp32-5&paused=on" curl "localhost:8080/sidekick/hud/update?model=esp32-5&paused=off" # Game over curl "localhost:8080/sidekick/hud/clear?model=esp32-5"
Complete Examples Reference
Arcade Frontend Integration
# LED: Game selection browsing GET /arcade/stream/mame/pacman?event=FEScroll curl "http://localhost:8080/arcade/stream/mame/pacman?event=FEScroll" # LED: Game launch with queue GET /text?t=Game%20Playing%20Pacman&l=1&c=blue curl "http://localhost:8080/text?t=Game%20Playing%20Pacman&l=1&c=blue" GET /arcade/stream/mame/pacman curl "http://localhost:8080/arcade/stream/mame/pacman" # LCD: Same workflow (no loops) via network GET http://pixelcadedx-f26967ec.local:8080/text?t=Game%20Playing%20Pacman curl "http://pixelcadedx-f26967ec.local:8080/text?t=Game%20Playing%20Pacman" GET http://pixelcadedx-f26967ec.local:8080/arcade/stream/mame/pacman curl "http://pixelcadedx-f26967ec.local:8080/arcade/stream/mame/pacman" # LCD: Same workflow via USB curl "http://169.254.100.1:8080/text?t=Game%20Playing%20Pacman" curl "http://169.254.100.1:8080/arcade/stream/mame/pacman"
Multi-Platform Examples
# LED with hostname GET http://pixelcade.local:8080/console/stream/nes curl http://pixelcade.local:8080/console/stream/nes # LCD device management via network GET http://pixelcadedx-f26967ec.local:8080/v2/info/ curl http://pixelcadedx-f26967ec.local:8080/v2/info/ GET http://pixelcadedx-f26967ec.local:8080/v2/utility/pairing/set/on curl http://pixelcadedx-f26967ec.local:8080/v2/utility/pairing/set/on # LCD device management via USB curl http://169.254.100.1:8080/v2/info/ curl http://169.254.100.1:8080/v2/utility/pairing/set/on # Non-arcade use case (LED) GET /arcade/write/user/ curl http://localhost:8080/arcade/write/user/
Complex Display Sequences (LED Only)
# Multi-step queue example GET /text?t=Game%20Playing%20Pacman&l=1&c=blue GET /arcade/stream/mame/pacman?l=3 GET /arcade/stream/mame/pacghosts.gif?l=2 # Result: Blue text → Pac-Man PNG 3 seconds → Ghost GIF 2 loops → blank # Cycle mode with high scores GET /arcade/stream/mame/pacman?t=High%20Scores%20Al%20200,000&l=5&color=green&cycle
Advanced Technical Notes
URL Requirements
- URLs cannot contain spaces in ROM names
- Cannot accept full ROM file paths - use ROM name only
- Extensions optional (e.g.,
1942.zipor1942)
File Organization
V1 (LED/LCD) Paths
- Console art:
/console/{console-name}.png|gif - Game art:
/mame/{rom-name}.png|gif,/user/for non-arcade - Multiple GIFs:
{game}_01.gif,{game}_02.gif(random selection) - Animations:
/animations/gifsource/ - Fonts:
/fonts/(TTF format)
V2 (LCD) Paths
- Managed through V2 API endpoints
- Thumbnails available via
/v2/thumbnails/ - Upload via
POSTendpoints with proper content types
Hardware Compatibility
- LED: Full V1 API support, write mode, advanced text formatting
- LCD: Limited V1 support, exclusive V2 APIs, no loops/animations
- Dot Displays: Score display via
/scoreendpoint (LCD systems only)
Performance Notes
- Stream mode: Instant playback, requires listener running
- Write mode: Physical write delay, works offline (LED legacy only)
- Queue system: Sequential processing, unlimited commands (LED only)
- LCD text: Continuous scrolling until interrupted
Licensing
Pixelcade software, API, and artwork is licensed for Pixelcade hardware only.
For technical support, visit the Pixelcade community forums. For integration assistance, consult the hardware documentation and ensure you're using the correct API version for your device type.