Starfish

A transport-neutral realtime protocol for creative coding -- networked performance, multiplayer sketches, installations, live visuals, and distributed browser-based artworks.

Documentation

Starfish provides sessions, presence, topic pub/sub, direct and broadcast messaging, shared state operations, and event streams over WebSocket with optional WebRTC peer-to-peer data channels.

Project Structure

Directory	Description
protocol/	Protocol specification
sdks/	Client libraries (TypeScript, Python, Go, Swift, JVM/Kotlin)
servers/	Server implementations (TypeScript, Go, Python)
adapters/	Framework integrations (p5.js, Three.js, TouchDesigner)
bridges/	Signal bridge CLI proxying external protocols (MIDI, OSC, …) into topics
examples/	Demo applications for each SDK and adapter
tests/	Integration test suite
scripts/	Build and CI utility scripts
docs/	VitePress documentation site

Quick Start

Start a server, then run an example against it.

1. Start the Go server

cd servers/golang
go run .
# Listening on ws://localhost:8080/starfish

2. Run an example

TypeScript:

cd sdks/typescript && npm install && npm run build && cd ../..
cd examples/typescript && npm install && npm run build
npm run connection

Python:

cd sdks/python && pip install -e .
cd examples/python && python connection.py

Development

make help             # Show all available targets
make check            # Lint, type-check, and unit-test everything
make check-lite       # Lint and type-check only (no tests)
make test-integration # Run protocol + SDK integration tests
make format           # Auto-format all code
make install-hooks    # Install the pre-commit hook

Protocol

See the protocol specification for the full message format, transport model, and session lifecycle.