Cartwall

A soundboard-style grid for instant audio triggering. Assign audio files to buttons and fire them with a click, keyboard, OSC, or DMX.

🌐 Web UI ⌨️ CLI 🔌 HTTP API 📡 OSC

🌐 Web UI

Cartwall Overview

The cartwall displays a grid of cart buttons. Each cart can hold one audio file and has its own trigger behavior.

Assigning Audio to a Cart

Click an empty cart slot (or right-click to replace)
Select an audio file from your library
Configure cart settings:
- Name — Display name on the button
- Color — Button color for organization
- Trigger Mode — Play, Toggle, or Hold

Trigger Modes

Mode	Behavior
Play	Click starts playback. Click again restarts from beginning.
Toggle	Click plays, click again stops.
Hold	Plays while held, stops on release.
One-Shot	Plays to completion, ignores clicks during playback.

Keyboard Shortcuts

Carts can be triggered via keyboard. Assign keys in cart settings:

Number keys 1-9, 0
Letter keys A-Z
Function keys F1-F12

Pages

Organize carts into pages. Switch pages with tabs at the top or via API/OSC.

⌨️ CLI

List Carts

bpsoundscape cart list

Trigger a Cart

# By position (page 1, slot 5)
bpsoundscape cart trigger --page 1 --slot 5

# By ID
bpsoundscape cart trigger --id cart_abc123

Assign Audio to Cart

bpsoundscape cart assign --page 1 --slot 5 --file "thunder.wav" --mode toggle

Options

Option	Description
`--page`	Page number (1-based)
`--slot`	Slot number (1-based)
`--id`	Cart ID
`--file`	Audio file path or library ID
`--mode`	play, toggle, hold, oneshot
`--color`	Button color (hex or name)

Stop a Cart

bpsoundscape cart stop --page 1 --slot 5

Stop All Carts

bpsoundscape cart stopall

🔌 HTTP API

Endpoints

Method	Endpoint	Description
GET	`/api/v1/carts`	List all carts
GET	`/api/v1/carts/:id`	Get cart details
POST	`/api/v1/carts/:id/trigger`	Trigger a cart
POST	`/api/v1/carts/:id/stop`	Stop a cart
POST	`/api/v1/carts/stopall`	Stop all carts
PUT	`/api/v1/carts/:id`	Update cart settings

Trigger by Position

curl -X POST "http://localhost:8513/api/v1/carts/trigger?page=1&slot=5"

Trigger by ID

curl -X POST http://localhost:8513/api/v1/carts/cart_abc123/trigger

Assign Audio

curl -X PUT http://localhost:8513/api/v1/carts/cart_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "audioFileId": "file_xyz789",
    "name": "Thunder",
    "mode": "toggle",
    "color": "#f59e0b"
  }'

Get Cart Status

curl http://localhost:8513/api/v1/carts/cart_abc123

Response:

{
  "id": "cart_abc123",
  "name": "Thunder",
  "page": 1,
  "slot": 5,
  "mode": "toggle",
  "state": "playing",
  "position": 1.5,
  "duration": 8.2,
  "color": "#f59e0b"
}

📡 OSC

Default OSC port: 8514

Trigger Controls

Address	Args	Description
`/bpsoundscape/cart/{page}/{slot}/trigger`	none	Trigger cart
`/bpsoundscape/cart/{page}/{slot}/stop`	none	Stop cart
`/bpsoundscape/cart/{page}/{slot}/volume`	float (0-1)	Set volume
`/bpsoundscape/carts/stopall`	none	Stop all carts
`/bpsoundscape/page`	int	Switch page

Examples

# Trigger cart at page 1, slot 5
oscsend localhost 8514 /bpsoundscape/cart/1/5/trigger

# Stop that cart
oscsend localhost 8514 /bpsoundscape/cart/1/5/stop

# Set cart volume to 50%
oscsend localhost 8514 /bpsoundscape/cart/1/5/volume f 0.5

# Stop all carts (panic button!)
oscsend localhost 8514 /bpsoundscape/carts/stopall

# Switch to page 2
oscsend localhost 8514 /bpsoundscape/page i 2

QLab Integration

Create Network cues in QLab to trigger carts:

Destination: [BPSoundscape IP]:8514
Message Type: OSC

Thunder:       /bpsoundscape/cart/1/5/trigger
Rain Loop:     /bpsoundscape/cart/1/6/trigger
Stop All:      /bpsoundscape/carts/stopall

Companion Button

In Bitfocus Companion, add an OSC action:

Instance: Generic OSC
Path: /bpsoundscape/cart/1/5/trigger
Args: (none)

← Audio Library Players →