⚠️ ARCHIVED — This repository has been consolidated into metasystem-master. All active development has moved there. This repository is preserved for historical reference only.
The centralized documentation hub for the Omni-Dromenon performance system — where artistic intent meets technical specification.
This repository is the single point of entry for understanding, using, and contributing to the ORGAN-II ecosystem. It houses architectural specifications, API references, artist and performer guides, theoretical manifestos, and research precedents — everything needed to move from first encounter to production deployment of a living, audience-responsive performance system.
- Why a Dedicated Documentation Repository
- Repository Structure
- Architecture Documentation
- API Reference
- Guides
- Deployment
- Conceptual Framework
- Cross-Repository Map
- Theory Implemented from ORGAN-I
- Documentation Philosophy
- Documentation Status and Roadmap
- Contributing
- License
- Author
Most software projects scatter their documentation across READMEs, wiki pages, inline comments, and Notion boards. The Omni-Dromenon system resists that pattern for three reasons:
-
The system is inherently interdisciplinary. A performer learning override controls needs to understand the consensus algorithm that governs how their inputs are weighted. An engineer debugging WebSocket latency needs to grasp the artistic model of "reciprocal creation" that determines message priority. Colocated documentation forces these perspectives into conversation.
-
The documentation is itself a creative artifact. In a system where the stage breathes, where audience biometrics shape lighting and sound in real time, the written account of how that breathing works is not a secondary byproduct. It is part of the artistic statement. The manifestos in
theory/are not marketing copy — they are design specifications expressed in artistic language. -
ORGAN-II spans multiple runtime repositories. The
core-enginehandles real-time signal processing in TypeScript. Themetasystem-mastermonorepo orchestrates builds and shared configuration in Python. Theperformance-sdkexposes TypeScript bindings for live show control. Theclient-sdkprovides audience-facing interfaces. No single repo can host documentation that spans all four — that is whatdocsis for.
This repository is the canonical reference. When specifications here conflict with inline comments elsewhere, docs wins.
docs/
├── guides/
│ ├── getting-started/
│ │ ├── installation.md # Environment setup and dependency installation
│ │ └── quick-start.md # First performance in under 10 minutes
│ ├── artist-guide/
│ │ ├── customization.md # Adapting system parameters to artistic vision
│ │ └── genre-adaptation.md # Tuning the system for different performance genres
│ └── performer-guide/
│ ├── dashboard.md # Real-time monitoring and visualization
│ └── override-controls.md # Manual intervention during live performance
├── specifications/
│ ├── architecture/
│ │ ├── consensus-algorithm.md # How multiple input streams resolve to system state
│ │ └── parameter-bus.md # Pub/sub message routing between subsystems
│ ├── api/
│ │ ├── rest-endpoints.md # HTTP API for configuration and state queries
│ │ ├── websocket-events.md # Real-time bidirectional event protocol
│ │ └── osc-protocol.md # Open Sound Control integration for hardware
│ └── deployment/
│ ├── docker.md # Container-based deployment for development and CI
│ ├── cloud-platforms.md # AWS/GCP/Azure deployment patterns
│ └── venue-setup.md # Physical venue hardware and network configuration
├── theory/
│ ├── manifestos/
│ │ ├── reciprocal-creation.md # The philosophical foundation: audience as co-creator
│ │ └── stage-that-breathes.md # Responsive environments as living systems
│ ├── philosophy/
│ │ └── everything-is-change.md # Heraclitean flux as system design principle
│ └── glossary/
│ └── terms.md # Canonical definitions for system-specific vocabulary
├── research/
│ ├── precedents/
│ │ └── prior-art.md # Survey of related systems and artistic practices
│ └── evaluation/
│ └── metrics.md # How we measure system and artistic performance
├── assets/ # Diagrams, images, and media assets
└── mkdocs.yml # MkDocs configuration for static site generation
Every directory serves a distinct audience. guides/ is for practitioners (artists, performers, technicians). specifications/ is for engineers and integrators. theory/ is for researchers, grant reviewers, and collaborators seeking the conceptual foundations. research/ bridges the practical and the academic.
Path: specifications/architecture/consensus-algorithm.md
The Omni-Dromenon system ingests multiple simultaneous input streams — audience biometrics, performer gestures, environmental sensors, pre-programmed sequences — and must resolve them into a single coherent system state at performance-time frame rates. The consensus algorithm defines how these competing signals are weighted, prioritized, and merged.
Key design decisions documented here:
- Weighted voting model — each input source carries a configurable weight that the artistic director sets before the performance begins
- Conflict resolution — when two sources demand contradictory state changes (e.g., "increase intensity" vs. "decrease intensity"), the algorithm applies a momentum-aware blending function rather than a hard winner-take-all cutoff
- Latency budget — consensus must resolve within a configurable frame window (default: 16ms for 60fps rendering) to maintain the illusion of immediate responsiveness
- Override semantics — performer overrides bypass the voting model entirely, with configurable fade-in curves to avoid jarring transitions
Path: specifications/architecture/parameter-bus.md
The parameter bus is the internal messaging backbone that connects input processors, the consensus engine, and output renderers. It implements a topic-based publish/subscribe pattern optimized for high-frequency, low-latency parameter updates.
Documented topics include:
- Topic naming conventions — hierarchical namespaces like
audience.biometric.heartrateandperformer.gesture.left-hand.velocity - Message format — typed parameter messages with timestamps, source identifiers, and confidence scores
- Subscription filtering — consumers can subscribe to topic prefixes (wildcards) to receive all messages in a namespace
- Backpressure handling — what happens when a slow consumer cannot keep up with parameter update rates
- Cross-process communication — how the bus bridges between the TypeScript
core-engineand Pythonmetasystem-masterprocesses
While no single diagram can capture every deployment variant, the architecture documentation provides reference topologies for:
- Solo performer — single machine running
core-engine, audience input via mobile web client - Ensemble — multiple performer stations connected via local network, shared consensus
- Venue-scale — dedicated hardware for sensing, processing, and rendering, with redundancy and failover
Path: specifications/api/rest-endpoints.md
The REST API handles configuration, state queries, and non-real-time operations. It is served by core-engine and consumed by dashboards, management tools, and the client-sdk.
Documented endpoint categories:
- Configuration (
/api/config/*) — read and write system parameters, input weights, output mappings - State (
/api/state/*) — current system state snapshot, input source health, consensus output - Sessions (
/api/sessions/*) — performance session lifecycle (create, start, pause, end) - History (
/api/history/*) — post-performance data retrieval for analysis and archiving
Path: specifications/api/websocket-events.md
WebSocket connections carry real-time bidirectional events between clients and the core-engine. This is the primary channel for live parameter updates during a performance.
Documented event types:
- Parameter updates — continuous stream of resolved consensus output values
- Input source events — notifications when input sources connect, disconnect, or change status
- Override events — performer override activations and deactivations
- Audience interaction events — aggregated audience response data for visualization
- System health events — latency measurements, frame timing, resource utilization
Path: specifications/api/osc-protocol.md
Open Sound Control (OSC) integration enables the Omni-Dromenon system to communicate with industry-standard performance hardware: lighting consoles (e.g., MA Lighting grandMA), sound systems (e.g., Ableton Live, Max/MSP), and projection mapping software (e.g., TouchDesigner, Resolume).
The OSC specification documents:
- Address space mapping — how internal parameter bus topics translate to OSC addresses
- Bidirectional flow — receiving OSC from external hardware (MIDI controllers, sensor arrays) and sending OSC to output devices
- Bundle timing — synchronization semantics for OSC bundles in performance-critical contexts
- Discovery — how the system advertises available OSC endpoints on the local network
Paths: guides/getting-started/installation.md, guides/getting-started/quick-start.md
The getting-started guides are designed to take a new user from zero to a running local instance in under ten minutes. The installation guide covers environment prerequisites (Node.js, Python, Docker), dependency installation, and verification. The quick-start guide walks through launching a minimal performance session with simulated audience input, demonstrating the core feedback loop without requiring physical hardware.
These guides assume comfort with the terminal but make no assumptions about prior experience with real-time systems or performance technology.
Paths: guides/artist-guide/customization.md, guides/artist-guide/genre-adaptation.md
The artist guide addresses the creative practitioner who will shape the system's behavior for a specific artistic vision. Customization covers parameter tuning — adjusting input weights, output mappings, and transition curves to match the desired aesthetic. Genre adaptation provides concrete examples of configuration profiles for different performance contexts: immersive theatre, generative music, dance, gallery installations, and hybrid forms.
The artist guide deliberately avoids implementation details. It speaks in terms of artistic intent ("I want the lighting to respond more aggressively to sudden audience movement") and translates those intentions into configuration actions.
Paths: guides/performer-guide/dashboard.md, guides/performer-guide/override-controls.md
The performer guide serves the person operating the system during a live performance. The dashboard documentation explains the real-time monitoring interface — what each visualization represents, how to read system health indicators, and how to spot problems before they affect the audience experience. The override controls documentation explains the manual intervention system — how to take temporary control of specific parameters, how overrides interact with the consensus algorithm, and how to release control gracefully.
This is the documentation that matters most at show time. It is written for speed of reference: short sections, clear headings, visual examples.
Path: specifications/deployment/docker.md
Container-based deployment is the recommended approach for development, CI/CD, and small-scale productions. The Docker documentation covers the multi-container architecture (separate containers for core-engine, metasystem-master orchestration, and optional monitoring), Docker Compose configuration, volume mounts for persistent session data, and environment variable reference.
Path: specifications/deployment/cloud-platforms.md
For productions that require elastic scaling, remote monitoring, or multi-venue coordination, the cloud deployment guide provides reference architectures for AWS, GCP, and Azure. Key topics include WebSocket connection management at scale, latency-sensitive container orchestration, and cost modeling for different production sizes.
Path: specifications/deployment/venue-setup.md
Physical venue deployment introduces hardware concerns that pure-software documentation cannot address. The venue setup guide covers network topology (dedicated performance VLAN, audience WiFi isolation), hardware inventory (recommended sensor arrays, compute nodes, display controllers), cable management and signal flow, and pre-show checklist procedures.
This guide bridges the gap between software documentation and the physical reality of staging a technology-driven performance.
The theory/ directory contains the conceptual foundations that distinguish the Omni-Dromenon system from conventional stage technology. These documents are not afterthoughts — they preceded and informed the technical architecture.
Reciprocal Creation (theory/manifestos/reciprocal-creation.md) articulates the core premise: the audience is not a passive consumer of a performance but an active co-creator whose presence and responses shape the artistic output in real time. This is not metaphorical. The system literally reads audience biometric and behavioral signals and feeds them into the consensus algorithm that drives lighting, sound, and visual output.
The Stage That Breathes (theory/manifestos/stage-that-breathes.md) extends the reciprocal creation model to the physical environment itself. A responsive stage is not simply one that reacts to cues. It is one that exhibits emergent behavior — rhythms, patterns, and moments of surprise that neither the artist nor the audience fully control. The document describes what it means for a performance environment to function as a living system rather than a programmable machine.
Everything Is Change (theory/philosophy/everything-is-change.md) grounds the system's design philosophy in Heraclitean flux. The system is optimized not for steady-state operation but for continuous transformation. Stability, in this framework, is not a desirable default — it is a failure mode. The philosophy document explains how this principle manifests in specific architectural choices: why the parameter bus favors velocity over position, why the consensus algorithm is momentum-aware, and why the deployment architecture assumes impermanence.
Path: theory/glossary/terms.md
The system operates at the intersection of multiple disciplinary vocabularies — computer science, performance theory, sensor engineering, artistic practice. The glossary provides canonical definitions for terms that carry specific meaning within the Omni-Dromenon context, resolving ambiguities that arise when the same word means different things in different fields.
Paths: research/precedents/prior-art.md, research/evaluation/metrics.md
The prior art survey documents related systems, artistic practices, and academic research that inform the Omni-Dromenon approach. This includes responsive architecture projects, interactive installation systems, algorithmic composition tools, and biometric feedback experiments.
The evaluation metrics document defines how the system's performance is measured — both technical metrics (latency, throughput, frame timing consistency) and artistic metrics (audience engagement patterns, performer override frequency, emergent behavior complexity). This is critical for grant applications and academic publications where quantitative evaluation of artistic systems is expected.
docs is the documentation hub for a constellation of ORGAN-II repositories. Here is how the pieces fit together:
| Repository | Language | Role | Docs Coverage |
|---|---|---|---|
metasystem-master |
Python | Monorepo — orchestration, shared config, build system | Architecture, deployment |
core-engine |
TypeScript | Real-time signal processing and consensus engine | Architecture, API reference |
performance-sdk |
TypeScript | SDK for live show control and performer interfaces | Performer guide, API reference |
client-sdk |
— | Audience-facing client interfaces | Getting started, API reference |
audio-synthesis-bridge |
— | Audio pipeline integration (Ableton, Max/MSP) | OSC protocol, deployment |
artist-toolkits-templates |
— | Pre-built configuration profiles for common genres | Artist guide |
example-generative-music |
— | Example: generative music performance | Quick start |
example-generative-visual |
— | Example: generative visual performance | Quick start |
example-choreographic-interface |
— | Example: dance and movement-driven performance | Artist guide |
example-theatre-dialogue |
— | Example: interactive theatre dialogue system | Artist guide |
academic-publication |
— | Academic papers and conference submissions | Research |
docs (this repo) |
— | You are here | All of the above |
The docs repository does not duplicate content from individual repo READMEs. Instead, it provides the cross-cutting narrative — the architectural whole that no single repo can tell by itself.
ORGAN-II (Poiesis) draws on theoretical foundations developed in ORGAN-I (Theoria). The dependency is intentional: theory precedes practice, and the flow between organs is strictly forward (I -> II, never II -> I).
Key theoretical imports:
- Recursive self-reference — the system's ability to observe its own output and feed it back as input. ORGAN-I's
recursive-engineprovides the formal model; ORGAN-II's consensus algorithm implements it in a performance context. - Ontological layering — the stratified model of reality (world -> realm -> organ -> repo) that governs how the system organizes itself. This model is documented in ORGAN-I and operationalized in ORGAN-II's parameter bus topic hierarchy.
- Observer-dependent state — the principle that system state is not objective but varies depending on the observer's position (performer, audience member, engineer, system itself). This principle shapes the multi-perspective documentation strategy in this very repository.
The docs repository makes these theoretical connections explicit. Each specification and guide includes, where relevant, a brief note on which ORGAN-I concept it implements and how.
This repository operates under a specific set of beliefs about what documentation should be:
Documentation is a first-class creative artifact. In a system devoted to artistic creation, treating documentation as an afterthought would be a contradiction. The manifestos in theory/ are as carefully written as any code in core-engine. The getting-started guides are as deliberately designed as any user interface.
Documentation should serve multiple audiences simultaneously. A grant reviewer needs to understand the system's conceptual ambition. An engineer needs to understand its API contracts. A performer needs to find the override control reference in thirty seconds during a live show. These are not competing requirements — they are addressed by different sections of the same corpus.
Documentation should be honest about incompleteness. Files in this repository that are currently empty (0 bytes) represent known documentation needs. They are not placeholders waiting for filler text — they are structural commitments to future work. The directory tree itself is a specification of what the documentation will eventually contain.
Documentation should survive the system it describes. If every line of code in ORGAN-II were deleted tomorrow, this repository should still be legible and valuable as an account of what was attempted, why it was designed the way it was, and what was learned.
The repository currently contains the complete directory structure — every file and folder represents a planned documentation deliverable. Content population is proceeding through the project's phased implementation plan:
| Status | Description |
|---|---|
| Structure deployed | Directory tree, file names, and organizational hierarchy are final |
| Content pending | Individual .md files are awaiting content generation |
| MkDocs configured | mkdocs.yml is present for eventual static site generation |
- Phase 1 (Current): Populate specification files — architecture and API reference documents take priority because they are dependencies for downstream guide writing
- Phase 2: Populate guides — getting started, artist, and performer guides, informed by the specifications written in Phase 1
- Phase 3: Populate theory and research — manifestos, philosophy, glossary, and prior art survey
- Phase 4: MkDocs build pipeline — configure
mkdocs.yml, deploy to GitHub Pages or similar static host, integrate with CI/CD - Phase 5: Cross-validation — verify all cross-references between
docsand sibling repo READMEs, ensure link integrity across the ORGAN-II ecosystem
Contributions to documentation are welcome and are held to the same standards as code contributions:
- File an issue first describing the documentation gap or improvement
- Follow the directory conventions — new files go in the appropriate subdirectory (
guides/,specifications/,theory/,research/) - Write for the intended audience of that section (see the Documentation Philosophy section)
- Cross-reference generously — link to related files within this repo and to relevant sibling repos
- Maintain the glossary — if you introduce a new term, add it to
theory/glossary/terms.md
For questions about the overall documentation strategy, open a discussion in this repository or reach out to the maintainer.
Part of the ORGAN-II: Poiesis organization within the ORGANVM eight-organ creative-institutional system.