another-machine/omnichord

Purpose and runtime

Omnichord is a no-build static browser instrument: a chord grid plus playable harp strip, synthesized held/plucked voices, and programmed drum rhythms. It runs from any static HTTP server; the browser is the runtime.

The document and module bootstrap are:

• index.html

• app.js

index.html provides the import map required for bare-specifier dependencies, including @amplib/music-theory and @amplib/sound-synthesis.

Application composition

app.js is the likely top-level composition point: it connects the instrument model, rendering, controls, sound, layout, theme, and touch input into one browser application.

The core collaborating modules are:

• app.js

• controller.js

• cartridge.js

controller.js is the control/state boundary for UI actions such as menu configuration, chord editing, selection changes, and hash-driven edit mode. cartridge.js represents the selected musical setup: enabled chords and user-facing instrument/rhythm/layout choices.

Musical chord domain

Chord definitions and chord-set behavior are isolated from rendering and audio:

• chords.js

• cartridge.js

chords.js is the integration boundary for theory-derived chord data. The application presents up to the original 84-chord root/type grid, while chord editing disables entries rather than changing the underlying theory source. The resulting enabled-chord set is consumed by layout and interaction layers.

Responsive visual layout

The layout subsystem translates enabled chords and viewport orientation into instrument geometry:

• layout.js

• app.js

It supports the three documented policies: fixed slots, row-filling by chord type, and flex packing near a square grid. It also places the harp at logical first or last, adapting that choice to portrait versus landscape, and reserves the opposite edge for the menu lane. This is a primary boundary between application state and screen-specific rendering.

Rendering and themes

Visual presentation is separated into color calculation/theme state and application rendering:

• theme.js

• app.js

• layout.js

Themes derive colors from chord position—root across hue and chord type across lightness—rather than assigning fixed colors per chord. Presets and custom slider ranges therefore affect rendering without altering chord, layout, or audio data.

Audio engine and external synthesis

Audio behavior is centralized behind:

• sounds.js

• app.js

sounds.js integrates the external sound-synthesis package to create FM-based chord-pad and harp voices plus synthesized drum patterns. Voice selection changes both pad and harp as one instrument. Rhythm and BPM are audio/control inputs rather than sample playback controls, avoiding sample-loading and playback-rate dependencies.

External service/package boundaries:

• index.html — import-map resolution for @amplib/music-theory and @amplib/sound-synthesis

• Browser Web Audio capabilities used by the synthesis dependency

Pointer and touch interaction

Direct instrument gestures are handled separately from application control widgets:

• touch.js

• controller.js

• app.js

touch.js is the input boundary for tapping chord cells and sliding/playing the harp strip. controller.js distinguishes these musical interactions from configuration actions and edit-chord mode, where grid taps disable chords. URL hash state supports entering and leaving edit mode through browser navigation.