RTS Command Deck

A StarCraft-inspired sound effects board. Chunky console keys press down and light up as they play. It has hotkeys and quick filters, every key can play your own sound file, and your keys (stored in a Postgres database) and clips (stored in Vercel Blob) can sync across devices.

Run it locally

npm install
npm run dev          # vercel dev: the page plus the /api storage routes
npm run dev:static   # the page only, no cloud sync, at http://localhost:3000

npm run dev needs the Vercel CLI linked to the project (npx vercel link) and the environment variables below (npx vercel env pull).

Deploy to Vercel

At vercel.com/new, import this GitHub repo. Leave Framework Preset on Other with no build command and no output directory. Every push to main redeploys. From the command line, npm run deploy runs vercel --prod.

vercel.json sets security headers, keeps sw.js and the manifest uncached so updates reach users, and caches icons for a week.

Set up cloud storage

Without these steps the board still works; keys and clips just stay in each browser.

1. Create a database for the keys. In the Vercel project, open Storage → Create Database → Neon (Postgres) and connect it to the project for all environments. This adds DATABASE_URL automatically (POSTGRES_URL also works). The tables are created on first use; db/schema.sql documents them.
2. Create a Blob store for the clips. In the Vercel project, open Storage → Create Database → Blob. Choose Private access and connect it to the project for all environments. This adds the store credentials automatically (BLOB_STORE_ID, or BLOB_READ_WRITE_TOKEN on older connections).
3. Set a passcode. Under Settings → Environment Variables, add DECK_PASSWORD with a passcode of your choice, for all environments.
4. Redeploy so the functions pick up the new variables (Deployments → ⋯ → Redeploy).
5. Connect. On the site, click Cloud, enter the passcode and click Connect. Repeat on each device.

If you created the Blob store with Public access instead, also set DECK_BLOB_ACCESS=public. Private is recommended: clips are only served through the app, to someone who has the passcode.

How sync works

• Each key is a row in the deck_keys table: label, faction, sound (synth preset, spoken line or clips), hotkey, colour, volume, pitch, favourite, its clips in play order (clips, a JSON list) and whether they play in order or at random (play_mode), in board order. The master volume and last-saved time are in deck_settings. Rows saved before multi-clip keys (single file_id / clip_path) are read as a one-clip list.
• Every change sends the board; the server updates changed keys, adds new ones and deletes removed ones in one transaction. Keys that didn't change are left alone. The last save wins.
• A board saved before the database existed (layout.json in Blob storage) is imported automatically the first time the database is read while empty.
• Each uploaded clip is stored once under clips/. Removing or replacing a clip in the editor, switching the key to a built-in sound, or removing the key deletes the clip from the store when no other key uses it.
• Clips are also cached in the browser (IndexedDB), so playback is instant and works offline. A new device downloads them in the background after connecting.
• The cloud limit is 4 MB per clip, set by Vercel's 4.5 MB request size for functions. Larger files still work but stay in the browser that added them.
• When a browser connects with unsaved changes, those changes are saved to the cloud. Otherwise the cloud board replaces the browser's board. A tab that comes back into view picks up changes made on another device.
• The passcode is remembered in the browser after connecting. Disconnect forgets it without deleting anything.

API

All routes require the passcode in an x-deck-pass header.

Route	Purpose
GET /api/layout	Saved board from the database: { layout: { pads, master } | null, savedAt }
PUT /api/layout	Save the board to the database (JSON body { pads, master }, up to 500 keys)
POST /api/clips	Upload one clip: raw audio body, Content-Type: audio/*, X-File-Name header → { path }
GET /api/clips?path=clips/…	Stream one clip
GET /api/clips	List stored clips from the catalogue, each with inUse (whether any key plays it)
DELETE /api/clips?path=clips/…	Delete one clip

Install as an app

The site is a Progressive Web App. In Chrome or Edge, use the install icon in the address bar. On iPhone or iPad, use Share → Add to Home Screen. Once installed it opens in its own window and works offline. Fonts are cached after the first online visit.

When you change index.html or the icons, bump VERSION in sw.js so installed copies fetch the new files.

Files

File	Purpose
index.html	The app: markup, styles and script
api/layout.js	Load and save the board's keys in Postgres
api/_db.js	Database connection, table setup and key ↔ row mapping (not a route)
db/schema.sql	Table definitions for reference
api/clips.js	Upload, stream, list and delete clips in Blob storage
api/_lib.js	Passcode check and shared helpers (not a route)
sw.js	Service worker for offline use
manifest.webmanifest	App name, colours and icons for install
icons/	App icon (SVG source plus 192 and 512 px PNGs)
vercel.json	Headers and URL settings for Vercel
package.json	@vercel/blob and @neondatabase/serverless dependencies, dev/deploy scripts

Features

• 24 keys across Terran, Protoss and Zerg: 11 Terran and 5 Protoss units each speak their line ("You want a piece of me, boy?", "My life for Aiur!"), 4 Zerg units use creature sounds since Zerg units don't talk, and 4 advisor alerts sit with their race ("Nuclear launch detected.", "You must construct additional pylons.", "Spawn more overlords.").
• Stand-in audio: unit lines are spoken by the browser's text-to-speech and Zerg sounds are synthesized with the Web Audio API. Upload the original clip on any key to replace them.
• Boards saved before the unit set are migrated automatically on load: the old effect keys are replaced, and keys you added or gave an uploaded clip are kept.
• Quick filters by faction (Terran, Protoss, Zerg), plus search, ★ Favorites and My clips.
• Hotkeys: each key shows its letter. Space stops all sounds, / focuses search, Esc clears filters.
• Several clips per key: open a key with ✎, choose Audio clips and use + Add clips (several files at once, up to 20 per key). Each clip in the list can be played (▶), moved up or down (↑ ↓), replaced, or removed (✕). With two or more clips, pick Play in order (cycles through the list) or Random (never the same clip twice in a row). Dropping audio files onto a key adds them to the end of its list.
• To go back to the built-in sound, open the key with ✎ and pick Synth preset or Voice line.
• Load clips adds many files at once. A file whose name matches a key's label or spoken line (for example nuclear-launch-detected.mp3) is added to that key's clips, so marine-1.mp3 and marine-2.mp3 both land on Marine. Any other file becomes a new key.
• Every key is editable: ✎ under any key, the built-in ones included, changes its label, faction, sound (voice line text, synth preset or your own clip), light colour, hotkey, volume and pitch.
• Add and remove keys at will: + Add key in the header, or the Add key tile at the end of the board, creates a new one. Remove key in a key's editor deletes it, with Undo for a few seconds afterwards. Layout → Reset to defaults brings back the original set.
• Layout copies the board setup as JSON, pastes one back in, or resets to defaults.
• Cloud syncs the board and clips across devices (see above).

Mission tracker

Paused. The Mission tracker tab is hidden for now; the Soundboard is always shown. The code is still in index.html and saved tracker data is kept (and still syncs). To bring it back, set TRACKER_ENABLED = true in index.html.

Switch to Mission tracker with the tab under the header (or open the site with #mission). It follows one tabletop game at a time, for StarCraft: The Miniatures Game or any similar skirmish game, through its rounds and phases.

Game flow

• Phases in order: Next phase steps through the mission's phases. Only on the last phase does the button become End round & score, which gives each objective's VP to its holder and starts the next round. Both buttons show how many checklist steps are still open in the current phase.
• Phase checklists: each phase can list steps (for example "Collect resources", "Remove casualties"). They show only during their phase and are cleared at the start of every round.
• Items shown only when they apply: the victory point counters, each resource, each objective and the initiative control can be limited to certain phases. The starter mission shows VP and objectives only in its Scoring phase. Hidden VP still count: End round & score adds them as usual, and the final result shows on the Mission complete banner. Outside those phases they're hidden, and the header says how many items are hidden. Show all reveals them for corrections, marked "other phase".
• Start of each round: the tracker applies the mission's round-start rules and writes them to the log:
  • resources: keep their value, reset to a number (such as supply), or add a number (such as income);
  • objectives marked "Nobody holds it at the start of each round" lose their controller;
  • initiative stays, passes to the other player, or is decided again (the tracker then asks who has it).
• End of the mission: after the last round, or as soon as a player reaches the VP target. A "Mission complete" banner shows the result.
• ◀ Back steps back one phase, or into the previous round's last phase. Scores and round-start changes aren't undone, so adjust them by hand if needed. On a finished game it reopens the mission.

Players, objectives, log and sounds

• Two players: name, faction, initiative, victory points (±1) and resource counters (±1/±5).
• Objectives: set who holds each one (None / player 1 / player 2).
• Battle log: scoring, captures, VP changes, round starts and your own notes, each stamped with round and time.
• Sound cues: pick keys from your board to play on a new round, next phase, objective taken and mission complete. Starred keys (★) show under Quick sounds, and hotkeys keep working on this screen.

Missions

Mission setup edits the whole mission: name, rounds, VP target, phases (with steps, reorderable), resources and their round-start rule, objectives with VP per round, and the phases each item is shown in, plus initiative and sound cues. Save as mission keeps it for reuse; pick it later from Start from a saved mission. The app ships only a generic starter mission, so enter the official mission's phases, objectives and round rules from your rulebook or mission cards.

To start a new game: pick the mission in Mission setup and Apply, then click New game twice. That resets round, scores, resources, objectives and the log, keeping player names, and applies the round-start rules for round 1.

The tracker is saved in the browser (rtsdeck.tracker) and, when Cloud is connected, with the board in the database (deck_settings.tracker), so a phone at the table and a laptop see the same game. Missions saved by earlier versions are converted automatically.

Where your data lives

With Cloud connected, everything that describes your board is saved in the database, and the audio files in Blob storage:

Data	Where
Keys: label, faction, sound (synth preset, spoken line or clips), hotkey, colour, volume, pitch, favourite, play mode, board order	deck_keys (one row per key)
Which clips each key plays, in order	deck_keys.clips
Master volume, last-saved time	deck_settings
Mission tracker (paused): missions, saved missions, current game	deck_settings.tracker
Every uploaded audio file: name, type, size, upload time	deck_clips (catalogue)
The audio files themselves	Blob storage, clips/…

Kept on each device only, on purpose:

• the Cloud passcode and sync bookkeeping (localStorage rtsdeck.cloud);
• current filters and search, and the last view (they belong to the screen you're using);
• a cache of the board (rtsdeck.v1, rtsdeck.tracker) and of the audio (IndexedDB rtsdeck), so playback is instant and the app works offline.

Saving is reliable: changes are saved to the database within a second. If the network or server fails, saves retry on their own with growing waits (the Cloud button shows Cloud • until they land). Changes made offline are saved when the connection returns, a change made just before closing the tab is sent on the way out, and an app opened while the server is unreachable connects once it's back. Failed clip uploads are retried too. Clips over 4 MB stay on the device that added them.

You can see it happen: every action that reads from or writes to the server shows a small toast in the corner (top of the screen on phones): a spinner while it runs (Saving changes…, Uploading marine.wav…, Loading clip…, Downloading clips · 3 of 8, Syncing with cloud…), then a brief tick when it's done (Saved, Clip removed from cloud), or a red note if it failed (Not saved yet · retrying). The Cloud button's light pulses while the server is busy, Connect shows a spinner while connecting, and a key's light pulses while its clip is fetched from the cloud.

The clip catalogue (deck_clips) is updated on every upload and delete, and resynced with Blob storage (files added or removed outside the app are picked up). GET /api/clips lists every stored file with whether a key still uses it.

About the sounds

This repo ships no game audio. The built-in effects are original synthesized imitations. To use the real game sounds, extract them from your own StarCraft install (for example with CascView) and load them with ⇪ Upload or Load clips. Keep those files out of this repo, since the game audio is Blizzard's copyrighted material. A private Blob store keeps them behind your passcode.

Fan-made project, not affiliated with Blizzard Entertainment.