corescope-voices/README.md

corescope-voices

Seven extra audio voices for the CoreScope Live page. CoreScope can turn every incoming mesh packet into sound; a voice decides what that sounds like. Stock CoreScope ships one (constellation).

These are currently deployed to https://corescope.rickelobe.com/#/live

This pack adds:

Voice	Style
metal	Distorted drop-D guitar: power chords, palm-mute chugs, leads, bends
synthmetal	Metal guitar + supersaws, octave bass, kick/gated snare, ping-pong delay
technoir	Dark 80s synthwave: driving bass, drum machine, chorused pads
ambient	Slow FM bells and drone pads in a big hall, not tied to the beat
dub	One-drop drums, offbeat skanks into a long feedback echo, sirens
acid	TB-303 patterns from packet bytes over four-on-the-floor drums
lofi	Swung boom-bap, electric-piano jazz chords, tape wobble, crackle

The pack is front-end only: a few JavaScript files plus <script> tags in index.html. Nothing changes in CoreScope's server, database or config.

What's in here

voices/                   the files that get copied into CoreScope's public/
  audio-voices-compat.js  adds two helpers stock audio.js doesn't export yet
  audio-synthkit.js       shared instruments and effects used by the voices
  audio-v2-metal.js … audio-v8-lofi.js   the voices
install.sh                copies voices/ into a public/ dir and patches index.html
Dockerfile                stock CoreScope image + this pack
tests/                    install + smoke test against a real public/ dir
docs/writing-voices.md    how voices work, if you want to tweak or write one

install.sh adds the tags right after audio-v1-constellation.js, so constellation stays the default voice. The tags sit between <!-- corescope-voices:begin/end --> markers, so re-running the script replaces them instead of adding duplicates, and --uninstall removes them cleanly. If your CoreScope already ships the voices, the script does nothing.

Install

First get the pack. Every option below runs from this directory:

git clone https://git.rickelobe.com/rich/corescope-voices.git
cd corescope-voices

Then pick the option that matches how you run CoreScope.

Option 1: Docker, build a derived image (recommended)

This layers the pack on top of the official image, so you always get the upstream front end and back end with only the voices added.

docker build -t corescope-voices:latest .

To pin a CoreScope version instead of latest:

docker build --build-arg CORESCOPE_IMAGE=ghcr.io/kpa-clawbot/corescope:<tag> -t corescope-voices:<tag> .

Then in your docker-compose.yml (or Portainer stack), change only the image line and redeploy:

services:
  corescope:
    image: corescope-voices:latest   # was ghcr.io/kpa-clawbot/corescope:latest

When CoreScope releases an update, pull the new upstream image and rebuild: docker build --pull -t corescope-voices:latest .. Tooling that "pulls latest" for you (Watchtower, a Portainer "re-pull image" redeploy) can't pull a locally built image. Either rebuild on a schedule before it runs, or push the image to your own registry and point the stack there.

Option 2: Docker, bind-mount a patched public/

Use this if you'd rather not build images. The downside is that your mounted front end stays fixed while the image updates, so you have to redo these steps after every CoreScope upgrade.

# 1. Copy the front end out of the image you actually run
docker create --name cs-tmp ghcr.io/kpa-clawbot/corescope:latest
docker cp cs-tmp:/app/public ./corescope-public
docker rm cs-tmp

# 2. Install the voices into that copy
./install.sh ./corescope-public

# 3. Mount it over the image's copy
services:
  corescope:
    volumes:
      - /absolute/path/to/corescope-public:/app/public:ro

Then redeploy or restart the container. Don't docker cp the files into a running container: they're lost the next time it's recreated.

Option 3: Running CoreScope from source

./install.sh /path/to/CoreScope/public

Restart the CoreScope server. It reads index.html only at startup.

Turn it on

1. Open the Live page.
2. Switch on Audio. The Voice dropdown only shows after audio is enabled. That's the usual reason someone reports "no dropdown."
3. Pick a voice. Your choice is remembered in the browser.

The voices are also available in the Audio Lab (#/audio-lab).

Hard-refresh the page once after installing if your browser cached the old index.html.

Uninstall

• Option 1: point the stack back at ghcr.io/kpa-clawbot/corescope:latest.
• Option 2: remove the volume line, or run ./install.sh --uninstall ./corescope-public.
• Option 3: ./install.sh --uninstall /path/to/CoreScope/public and restart.

Test

Needs node and a CoreScope public/ dir (a checkout, or one copied out of the image as in Option 2). It works on a temp copy and never modifies the directory you pass in. Run it from the repo directory:

tests/run.sh /path/to/CoreScope/public

It checks that install is idempotent, that all seven voices register with constellation still the default, that every voice plays every packet type through the real CoreScope audio engine, and that uninstall restores index.html byte for byte.

Compatibility

Tested against CoreScope master as of 2026-10-01. The pack depends on:

• MeshAudio.registerVoice and MeshAudio.helpers in CoreScope's public/audio.js
• a <script src="audio-v1-constellation.js…"> line in index.html (used as the anchor)

If a future CoreScope release changes either one, install.sh stops with an error rather than producing a broken page.

License

GPL-3.0, same as CoreScope. See LICENSE.

AI use notice

AI was heavily used in the creation of these corescope modifications.