# corescope-voices

Seven extra **audio voices** for the [CoreScope](https://github.com/Kpa-clawbot/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:

```bash
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.

```bash
docker build -t corescope-voices:latest .
```

To pin a CoreScope version instead of `latest`:

```bash
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:

```yaml
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.

```bash
# 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
```

```yaml
# 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

```bash
./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:

```bash
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.