153a.github.io

Web-based sound experiments for Stanford's NMP CODE Ensemble.

This repository hosts standalone HTML/Web Audio webapps and publishes them through GitHub Pages. The main entry point is the generated webapps/ index page.

Live site: https://cchafe.github.io/153a.github.io/webapps/

Overview

The repo is organized by themed collections of interactive browser instruments:

• webapps/moss/: "Life in the Boundary Layer" variations
• webapps/spiderBallooning/: spider ballooning sonification variations
• webapps/remoteControl/: remote-control / vocal synth experiment(s)

Webapps can be played together for an ensemble as a concert piece, or can be used as stand-alone solo instruments.

Most apps are self-contained HTML files with inline CSS/JS that rely on:

• Web Audio API
• Canvas and DOM APIs
• User gesture to unlock audio (AudioContext start/resume behavior)

Repository Structure

.
├── .github/workflows/
│   └── generate-indexes-of-webapp-subdirectories.yml
├── scripts/
│   └── generate-indexes-of-webapp-subdirectories.mjs
├── webapps/
│   ├── index.html                     (auto-generated)
│   ├── moss/
│   │   ├── index.html                 (auto-generated)
│   │   └── *.html                     (individual webapps)
│   ├── spiderBallooning/
│   │   ├── index.html                 (auto-generated)
│   │   └── *.html
│   └── remoteControl/
│       ├── index.html                 (auto-generated)
│       └── *.html
└── README.md

Current Collection

Check out our current work!

webapps/moss/

Multiple versions of "boundary layer / moss" sonification pieces by different contributors (for example: calvin-boundary-layer-sonification.html, kimia-boundary_layer_instrument_v3_mossfix.html, tristan-moss.html).

webapps/spiderBallooning/

Multiple spider-ballooning sonification implementations with different synthesis/interaction approaches (for example: renee-spider.html, chris-spiderBallooning.html, calvin_spider-ballooning_claudeOpus4.5.html).

webapps/remoteControl/

Remote-control inspired vocal/FM synthesis experiment (currently remoteControlWebappVolume.html).

How Navigation Pages Are Generated

The site is autogenerated under the webapps/ root directory. Index pages are generated automatically by:

• Script: scripts/generate-indexes-of-webapp-subdirectories.mjs
• Workflow: .github/workflows/generate-indexes-of-webapp-subdirectories.yml

What the script does:

1. Scans webapps/ for immediate subdirectories.
2. For each subdirectory, creates/updates index.html linking all .html files except index.html.
3. Rebuilds webapps/index.html linking each collection directory.

The GitHub Action runs on pushes to main when relevant files change, then commits any regenerated index files automatically.

Local Development

Prerequisites

• Node.js 20+ (for the index-generation script)
• Sound enabled browser (Chrome, Firefox, Safari, Edge)

Serve Locally

Because these apps use browser APIs, run them via a local server (not file:// URLs):

cd /home/.../153a.github.io
python3 -m http.server 8000

Then open:

• http://localhost:8000/webapps/

Regenerate Indexes Manually

cd /home/.../153a.github.io
node scripts/generate-indexes-of-webapp-subdirectories.mjs

Adding a New Webapp - Upload Instructions

1. Choose the appropriate collection directory under webapps/ (or create a new one).
2. Add your HTML file there.
3. Run the index generator locally:
   • node scripts/generate-indexes-of-webapp-subdirectories.mjs
4. Verify locally:
   • python3 -m http.server 8000
   • Open http://localhost:8000/webapps/
5. Commit your app file and regenerated index.html files.
6. Push to main (or open a PR). The workflow will re-check and auto-update indexes if needed.

Conventions and Notes

• webapps/**/index.html files are generated. Avoid manual edits because they will be overwritten.
• Standalone app HTML files are expected to be hand-authored and can include inline styles/scripts.
• Some historical filenames include spaces and mixed naming styles; this is supported by the generator.

Troubleshooting

• No sound:
  • Click the app's start/play button first (browser autoplay policy).
  • Check browser tab audio permissions and system output device.
• App works locally but not after push:
  • Confirm webapps/index.html and subdirectory indexes were committed or allow the workflow commit to complete.
• Link missing from index:
  • Ensure the file extension is .html or .htm and not named exactly index.html.