banSimulator Operation Manual

This document outlines the operational controls and theoretical underpinnings of the banSimulator, a hyper-organological web instrument designed for the ubiquitous browser environment.

Bellows Control

The breath of the instrument. In the default Rheinische 142 layout, direction determines the pitch set because the manual is bi-sonoric. In Peguri and Crosio Caliero, direction remains a gestural/air state but the pitch map stays fixed because those layouts are unisonoric.

` / g / G / § : Toggle Bellows Direction (Opening / Closing)

Layout Systems

The HUD includes a layouts selector above the lesson dropdown. Three systems are currently available:

1. Rheinische 142 (default): bi-sonoric. Opening and closing the bellows produce different pitch assignments on the same button.
2. Peguri: unisonoric. Opening and closing keep the same pitch on each button.
3. Crosio Caliero: unisonoric. Opening and closing keep the same pitch on each button.

The Peguri and Crosio Caliero mappings were transcribed from the keyboard document organized by Omar Caccia. In the simulator they are projected onto the existing SVG geometry, which means some extreme outer-edge positions present in the source diagrams are reduced to the nearest shared positions of the current interface rather than rebuilt as a different physical keyboard shell.

Lessons And Generative Studies

The second HUD selector now contains both scalar lessons and a GENERATIVE group. When any lesson or study is selected, a minimal transport appears:

L : loop left hand only

R : loop right hand only

Play / Stop : toggle both hands in sync

Space : same as the Play / Stop transport toggle

BPM : tempo control for both scalar lessons and generative studies

Operational notes:

1. Scalar lessons advance in eighth notes (two notes per beat).
2. Negative BPM reverses the traversal direction.
3. Generative studies keep their internal formal proportions, but BPM scales the whole cycle speed.
4. In generative studies, negative BPM reverses the event timeline.

Generative Studies

Random 5

Sparse five-second base cycle. Up to three events distributed between pitch, mode, and dynamic changes. Every 4-5 loop iterations it inserts a short silence window.

Random 10

Dense ten-second base cycle. Higher event density, at least one silence window per cycle, suitable for continuous agitation.

Random 20

Ultradense twenty-second base cycle. Three silence zones plus one explicit two-hand tutti convergence event per cycle.

Bjorklund

Deterministic Euclidean study. Left and right hands distribute different pulse counts across the same step grid, producing structured asymmetry and stable counterpoint.

Phi Spiral

Deterministic growth study. Event spacing expands and contracts according to golden-ratio logic, while pitch motion moves from the center outward and back as a spiral gesture.

Kelvin-Helmholtz

Deterministic shear-flow study. Two drifting rhythmic layers move with phase offsets and periodic vortical alignments, generating audible turbulence between the hands.

Left Hand Manual (Bass)

Mapped to the left side of the QWERTY keyboard.

Primary Layer

1 2 3 : Buttons 33, 32, 31 q w e r : Buttons 30, 29, 28, 27 a s d f g : Buttons 26, 25, 24, 23, 22 z x c v : Buttons 21, 20, 19, 18

Secondary Layer (Hold Control)

Ctrl + 1..5 : Buttons 16..12 Ctrl + q..t : Buttons 11..7 Ctrl + a..g : Buttons 6..2 Ctrl + c : Button 1

Right Hand Manual (Treble)

Mapped to the right side of the QWERTY keyboard.

Primary Layer

6 7 8 9 0 : Buttons 1, 2, 3, 4, 11 t y u i o p : Buttons 6, 7, 8, 9, 10, 5 h j k l ; \ : Buttons 12, 13, 14, 15, 16, 17 b n m , . / : Buttons 18, 19, 20, 21, 22, 23

Secondary Layer (Hold Control)

Ctrl + 6..0 : Buttons 24..28 Ctrl + y..o : Buttons 29..32 Ctrl + h j k : Buttons 33..35 Ctrl + b n : Buttons 36..37 Ctrl + m : Button 38

Articulation Modes

Instantaneous switching of sample sets and envelope behaviors.

Shift + Z : SUSTAIN (Standard) Shift + X : OCTAVE (Doubling) Shift + C : TREM OCT (Tremolo Octave) Shift + V : WHOLE TONE TREM Shift + B : HALF TONE TREM Shift + N : SALTOS (Jumps) Shift + M : REP (Repetition) Shift + , : STACC (Staccato)

Dynamics

Control the intensity of the samples. Note that STACC mode bypasses the mezzo-forte (mf) dynamic.

Arrow Up : Increase Dynamic (p -> mf -> f) Arrow Down : Decrease Dynamic

Extended Techniques (FX)

Percussive and mechanical sounds inherent to the instrument’s physicality.

Shift + A : Button Noise Left Shift + S : Button Noise Right Shift + D : Breath Shift + F : Blow Shift + G : Sandpaper (Lija) Shift + J : Heel (Tacon) Shift + K : Bellows Shake (Vomito)

Interface Controls

Shift + H : Toggle Heads-Up Display (HUD) E : Toggle Edit Mode (Drag buttons to reposition) Shift + = : Export Button Coordinates to Console Space : Toggle lesson / generative transport

Mobile/Tablet Touch-Zone Expansion

For touch and pen pointers, each pitched button uses an expanded virtual hit radius. This is controlled by:

touchZonePercentage = 50

The expansion is intentionally allowed to overlap neighboring buttons. When overlap occurs, a single finger contact can activate more than one button at the same time. This reproduces a real bandoneon condition: one non-surgical finger gesture may legitimately produce clustered/chordal button activation.

Design notes:

1. Mouse behavior is kept strict (no expanded zone).
2. FX buttons are excluded from the expanded overlap logic.
3. In gliss/hover interaction, the active touch-set updates continuously as the finger moves.

Real-time Score Visualization

The left side of the HUD features a real-time musical score generated with VexFlow. Notes played on the right-hand manual appear on a treble clef, and notes from the left-hand manual appear on a bass clef. This provides immediate visual feedback on the harmonies being performed.

Chord Notation for Sibelius

A dedicated text field in the HUD generates a character string corresponding to the currently held notes. This string is mapped to the bandoneon.ttf font, allowing for direct copy-pasting into scoring software like Sibelius for professional notation. A copy icon is provided for quick clipboard access.

Architectural Design Patterns

The emulator is built upon a robust set of software design patterns to ensure performance and maintainability in the single-threaded browser environment.

Singleton State Management

The application utilizes a singleton pattern for the audio context and global keyboard manager. This ensures that resource-heavy audio graphs are instantiated only once and that event listeners do not proliferate during navigation, maintaining a clean memory footprint.

Flyweight Resource Pooling

To handle the massive library of high-fidelity Opus samples without latency, a Flyweight pattern is employed via a buffer cache. Samples are loaded and decoded on demand but stored in a shared pool. Subsequent requests for the same note—even across different articulation modes if shared—retrieve the pre-decoded buffer instantly.

Data-Driven Organology

The UI and logic are decoupled through a data-driven approach. The visual layout (SVG) and the logical mapping (MIDI notes per bellows direction) are generated dynamically from a central configuration array. This allows for rapid iteration on the instrument’s geometry and tuning systems without altering the core engine code.

Technical Implementation Details

Unlike a purely synthetic instrument, the banSimulator is a high-fidelity sampler that leverages real audio recordings for its sound engine.

Dynamic Sample Catalog

On initialization, the instrument builds a catalog of all available sounds by parsing the filenames of the .opus samples. A regex-based system extracts three key pieces of metadata from each filename:

1. The base musical pitch (e.g., C#4).
2. The articulation mode (e.g., SUSTAIN, STACC, TREM OCT).
3. The performance dynamic (e.g., p, mf, f).

This automated cataloging allows the sample library to be expanded without any changes to the application code.

Closest-Match Sample Selection

When a note is played, the findSample algorithm performs a multi-stage search to find the most appropriate audio sample:

1. It first filters the entire catalog by the currently active articulation mode.
2. If the mode is SUSTAIN or STACC, it performs a secondary filter based on the selected dynamic (p, mf, f).
3. From the remaining candidates, it selects the sample with the smallest absolute MIDI distance to the target note.

This ensures that the played sound is as close as possible to the intended pitch and timbre.

Real-time Pitch Shifting

To play notes that do not have a dedicated sample, the engine uses real-time pitch shifting. The playback rate of the selected sample’s AudioBufferSourceNode is adjusted based on the semitone difference between the sample’s native pitch and the target pitch. The formula used is:

playbackRate = 2^(semitones / 12)

This allows for a full chromatic range while maintaining a manageable sample library size.

Convolution Reverb

To create a sense of space, all sounds are routed through a Web Audio graph containing a convolution reverb. The impulse response for the reverb is generated synthetically by creating decaying noise, providing a unique ambient character. The final output is a mix of the ‘dry’ (unprocessed) signal and the ‘wet’ (reverberated) signal, with the mix ratio being adjustable via constants in the code.

Concepts in Web-Based Organology

Ubiquitous Spectral Interface

The banSimulator represents a shift towards the Ubiquitous Spectral Interface, where high-fidelity spectral manipulation is no longer bound to compiled binaries or dedicated hardware. By leveraging the Web Audio API, the instrument exists purely as a URL, democratizing access to complex timbral textures and allowing the browser to act as a resonant chamber for historic instrumentation.

Hyper-Organology via Virtual Constraints

While the simulation respects the physical limitations of the bandoneon (bi-sonoric layout, air management), it selectively transcends them. The ability to switch articulation modes (e.g., from natural sustain to impossible tremolos) instantaneously via the Shift modifier creates a hyper-organology. It retains the haptic cognitive map of the original instrument while superimposing a layer of digital plasticity that physical physics cannot support.

Semantic Audio-Visual Feedback Loops

The integration of real-time VexFlow notation and a reactive HUD creates a semantic feedback loop. Unlike a traditional instrument where feedback is purely auditory and tactile, this system provides immediate theoretical validation (visualizing the chord on a staff) and state awareness (filename, dynamic level). This multi-modal feedback accelerates the internalization of the instrument’s complex logic, bridging the gap between performance and analysis in real-time.

Interface Theory: Overlap as Musical Affordance

The touch-zone model treats motor imprecision as an expressive resource, not as an error state. Three concepts are central here:

1. Fitts-informed targeting: on small screens, larger effective targets reduce acquisition cost and increase playability under live pressure.
2. Probabilistic gesture capture: finger pads are broad and dynamic; the interface therefore models contact as an area, not a point.
3. Embodied poly-activation: overlap enables one-touch multi-button events, aligning digital interaction with the physical ergonomics of acoustic bandoneon technique.

This is a deliberate shift from strict UI button semantics toward organological semantics: the interface privileges performative plausibility over pixel-perfect control.