SciFi-XZBT/telemetry_elements.md

# Telemetry Audio Elements

Catalog of the discrete telemetry sounds the application produces. All of them
live in `TelemetrySynth` (`js/audio.js`, ~line 715) and are **synthesized at
runtime** from Web Audio oscillators, envelopes and filters — there are no
samples anywhere in this project.

Telemetry is the "computer chatter" layer: short, non-musical-foreground blips
that sit on top of the continuous hull / warp / life-support beds. It is the
only audio layer with a **density** parameter, because it fires as discrete
events rather than running continuously.

---

## Element catalog

| Element | Method | Description | Where used |
| --- | --- | --- | --- |
| **LCARS Single Chirp** | `synthesizeLCARSSingleChirp(pitch?)` | Soft sine touch tone, ~90 ms, gentle 8 ms attack into exponential decay, with a subtle 2% downward pitch glide and a 3.2 kHz lowpass to kill the click. Accepts an optional pitch, which makes it the building block for the other LCARS elements. | TNG auto-scheduler (45%), DS9 (50%), soundboard `btn-chirp-single` / `btn-switch-pop`, preset-change confirmation while playing, **default fallback** for any unmapped soundboard or event id |
| **LCARS Double Chirp** | `synthesizeLCARSDoubleChirp()` | Two single chirps 65 ms apart, second pitch two steps up the LCARS scale (minor third / fourth). The iconic "acknowledged" tone. | TNG auto-scheduler (30%), Voyager (60%), soundboard `btn-chirp-double`, **engage/play confirmation** for non-Whoniverse, non-bioship universes |
| **LCARS Acknowledgment Sequence** | `synthesizeLCARSSequence()` | Three chirps at 75 ms spacing drawn from overlapping windows of the LCARS scale — reads as a short data-accept run rather than a single button press. | TNG auto-scheduler (15%), soundboard `btn-chirp-ack` |
| **Sensor Sweep** | `synthesizeSensorSweep()` | 380 ms sine glide from 1200–2000 Hz, ramping either up ×1.6 or down ×0.65 at random. Longer and more "scanning" than the chirps. | TNG auto-scheduler (10%), Voyager (40%), soundboard `btn-chirp-sweep`, layered under `btn-scanner` |
| **TOS Computer Warble** | `synthesizeTOSWarble()` | 450 ms of detuned triangle + sawtooth (fundamental and its fifth) under a 14–22 Hz vibrato LFO, through a Q=3.5 bandpass at 1.2× the fundamental. Vintage 1960s analog computer voice. | TOS auto-scheduler (60%) |
| **TOS Relay Click** | `synthesizeTOSRelayClick()` | 25 ms square wave falling 1400 → 300 Hz. A mechanical solenoid snap, not a tone. | TOS auto-scheduler (40%) |
| **Cardassian Sensor Tone** | `synthesizeCardassianSensor()` | 550 ms pair of sines a tritone apart (×1.414) for deliberate metallic dissonance, base 420–620 Hz. Cavernous, alien, unresolved. | DS9 auto-scheduler (50%) |
| **NX Hydraulic Relay** | `synthesizeNXRelay()` | 40 ms triangle falling 750 → 120 Hz. Heavier and duller than the TOS click — 22nd-century industrial rather than mid-century electrical. | NX auto-scheduler (50%) |
| **NX Indicator Beep** | `synthesizeNXIndicatorBeep()` | 80 ms 950 Hz sine with a flat sustain plateau and a fast tail. Plain and utilitarian; no glide, no scale membership. | NX auto-scheduler (50%) |
| **TNG Door Chime** | `synthesizeDoorChime()` | Two overlapping sines, A5 (880 Hz) then D6 (1174.66 Hz) at +160 ms, each with a long 450–700 ms decay. The "come in" chime. | Soundboard `btn-chirp-door` only — **never** fired by the auto-scheduler |

---

## The auto-scheduler

`startAutoTelemetryScheduler()` self-reschedules after every sound:

```
baseDelay = 12000 * (1.05 - density)   // ms
interval  = max(800, baseDelay + random(0..4000))
```

- `density` 0 → scheduler does not arm at all (`<= 0.01` returns early).
- `density` 1 → ~0.6 s base + jitter, floored at 800 ms — a busy bridge.
- Mid values land in the 2–12 s range the parameter comment describes.
- Density comes from the active preset's `telemetry.density` and is also live
  on the `slider-telemetry-density` UI control.

### Era routing

`playRandomTelemetrySound()` picks an element by `params.era`. Each era draws
from **exactly two or four** elements — this is the table to extend when adding
an era or a new element.

| Era | Elements and weights |
| --- | --- |
| `tng` (also the default) | Single Chirp 45% · Double Chirp 30% · Acknowledgment Sequence 15% · Sensor Sweep 10% |
| `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| `tos` | Computer Warble 60% · Relay Click 40% |
| `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| `nx` | Hydraulic Relay 50% · Indicator Beep 50% |

Note the era is a **telemetry** property, not a universe property: it is set
per preset in `js/config.js` (`telemetry.era`) and is independent of the
universe that governs the visuals. In practice every preset in every universe
uses one of these five Trek eras, so non-Trek themes play Trek telemetry — see
[Preset → telemetry era reference](#preset--telemetry-era-reference) for the
full per-preset mapping.

---

## The activity event contract

Every scheduled telemetry sound dispatches a window event **after** it plays:

```js
window.dispatchEvent(new CustomEvent('scifi-telemetry-activity', {
  detail: { era, density, firedAt }
}));
```

`js/app.js` listens for this and calls `triggerObservationActivity('telemetry')`,
which is what synchronizes observation-mode transient visuals to the audio.
The visual side deliberately treats the pulse as **abstract activity** — no
specific beep means a specific thing on screen. The observation activity slider
then gates whether a given pulse becomes visible:

```
responseChance = 0.18 + activity * 0.82
```

Important: only `playRandomTelemetrySound()` dispatches the event. Elements
triggered directly (soundboard, play/stop, preset change) are silent as far as
the visual layer is concerned. If a new element should drive visuals, it must
either be reachable through the era router or dispatch the event itself.

---

## Pitch material

Two fixed scales are the source of all pitched telemetry. Reuse them rather
than inventing loose frequencies — they are what makes the layer sound coherent.

- **`lcarsPitches`** — 12 entries, 880 Hz → 2637 Hz, a pentatonic-flavored set
  built on perfect fourths and fifths. Used by every LCARS element.
- **`tosFrequencies`** — 9 entries, 440 Hz → 2217 Hz, wider and more angular,
  matching the era's less "designed" sound.

Unpitched elements (relay clicks, sweeps, the Cardassian tone) generate their
own frequencies and intentionally sit outside both scales.

---

## Signal-chain conventions

Every element follows the same shape. Match it when adding one:

1. Bail out early on `!ctx || !this.gainNode`.
2. Capture `const now = ctx.currentTime` once and schedule everything relative
   to it — never use `setTimeout` for sample-accurate timing (it is used only
   for the deliberate multi-note spacing in the double chirp and sequence).
3. Build oscillator → per-voice envelope gain → optional filter → `this.gainNode`.
4. Envelopes start at `0.001`, `linearRampToValueAtTime` up, then
   `exponentialRampToValueAtTime` down to `~0.0001`. Never ramp exponentially
   to or from exactly zero.
5. Peak envelope gain stays in the **0.18–0.35** band so no element dominates
   the bed. Clicks sit at the top of that range because they are so short.
6. Explicitly `stop()` every node at the end of its life. Nothing here loops.

`this.gainNode` carries the layer volume and connects to `am.compressor`, so
individual elements should never touch master volume or the destination.

---

## Related but not telemetry

Short event sounds for non-Starfleet universes live in sibling classes and are
routed by `handleSoundboardTrigger()` in `js/app.js`. Check these before adding
a new telemetry element — the sound you want may already exist:

- **`WhoniverseAudioSynth`** — sonic screwdriver, fast return, demat switch,
  telepathic chime, cloister strike.
- **`ExpandedSciFiAudioSynth`** — DRADIS ping, HAL chime, Geiger burst, docking
  clamp, improbability flip, cheerful door, and the various drive effects.
- **`AlertSynth`** — red/yellow alert cycles and the warp jump swell. Alerts are
  a separate layer with its own trigger path, not telemetry. **They are not
  purely user-triggered:** in Observation Mode the cinematic director's Hull
  Breach sequence calls `alerts.triggerRedAlert('tng')` on its own, roughly
  6.5 s before restoring the previous state. It is in the sequence pool for the
  `military`, `outlaw` and `industrial` universes and fires on a random timer
  (45–75 s for the first sequence, 90–180 s between later ones). This is the
  only non-telemetry sound in the app that can start without user action.

Preset changes and play/stop pick between these three families by
`activeUniverseId` — see `js/app.js` around lines 305–365.

---

## Adding or reusing an element

Reuse an existing element when the need is **generic UI feedback** — the Single
Chirp and Double Chirp are explicitly the neutral confirm/acknowledge sounds and
are already the fallbacks for unmapped ids. Reaching for them costs nothing.

Invent a new element when the sound must carry **era or universe identity** that
no existing element has. In that case:

1. Add the method to `TelemetrySynth` following the signal-chain conventions.
2. Give it a doc comment naming the era and the physical thing it imitates —
   every existing element has one.
3. Wire it into the `playRandomTelemetrySound()` era switch with an explicit
   probability, or leave it manual-only (like the Door Chime) if it is too
   characterful to fire unattended.
4. If it is manual-only, add a soundboard case in `handleSoundboardTrigger()`
   and a button in `index.html`.
5. Reuse `lcarsPitches` / `tosFrequencies` if the element is pitched and belongs
   to those eras.
6. Keep the duration under ~600 ms. This is an ambient layer; anything longer
   reads as a foreground event and belongs in `AlertSynth` instead.

---

## Preset → telemetry era reference

`telemetry.era` is assigned **per preset**, and it is the only thing that
decides which elements the auto-scheduler fires. It is *not* derived from the
universe. All 70 presets across all 10 universes currently use one of the five
Star Trek eras, so non-Trek universes play Trek telemetry: a retrofuture profile
can chatter in TOS warbles, and a living-ship profile can ring with the
Cardassian sensor tone. If you hear a sound that seems foreign to the theme you
are on, this table is where to look it up.

| Era | Elements fired |
| --- | --- |
| `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |

### Starfleet Command (10 presets — ds9 ×2 · nx ×1 · tng ×3 · tos ×2 · voyager ×2)

| Preset | Era | Elements heard |
| --- | --- | --- |
| Enterprise-D: Main Bridge | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| Enterprise-D: Main Engineering | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| Enterprise-D: Crew Quarters | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| USS Voyager: Bridge | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| USS Voyager: Class-9 Warp Core | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| USS Defiant: Tactical Bridge | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| Deep Space 9: Ops Center | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| Enterprise NCC-1701: Bridge (TOS) | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| Enterprise NCC-1701: Engineering (TOS) | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| Enterprise NX-01: Command Bridge | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |

### The Whoniverse (7 presets — ds9 ×1 · nx ×1 · tng ×2 · tos ×1 · voyager ×2)

| Preset | Era | Elements heard |
| --- | --- | --- |
| 1963 Classic Console (1st / 2nd Doctors) | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| Victorian Secondary Console (4th Doctor) | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| The Coral Living TARDIS (9th / 10th Doctors) | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| The Copper Workshop (11th Doctor) | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| The Cold Machine (12th Doctor) | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| The Singing Crystal Console (13th Doctor) | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| The Infinite White (14th / 15th Doctors) | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |

### Industrial (8 presets — ds9 ×1 · nx ×3 · tos ×3 · voyager ×1)

| Preset | Era | Elements heard |
| --- | --- | --- |
| USCSS Nostromo: Ore Refinery Bridge | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Serenity: Firefly-Class Cargo Hold | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| Red Dwarf: Main Drive Corridor | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Starbug 1: Cockpit Environment | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| The Raza: Dark Matter Bridge | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| Rocinante: Combat Ops & Epstein Drive | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| Eagle Transporter: Command Module | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| Valley Forge: Agro-Dome Forest Hub | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |

### Bioships (6 presets — ds9 ×1 · nx ×2 · tng ×1 · voyager ×2)

| Preset | Era | Elements heard |
| --- | --- | --- |
| Moya: Leviathan Central Nexus | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| Talyn: Gunship Neural Bridge | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| The Lexx: Primary Organ Bridge | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Vorlon Cruiser: Sentient Core | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| Wraith Hive Ship: Throne Chamber | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Species 8472: Fluidic Bioship | `voyager` | Double Chirp 60% · Sensor Sweep 40% |

### Retrofuture (8 presets — nx ×2 · tng ×2 · tos ×3 · voyager ×1)

| Preset | Era | Elements heard |
| --- | --- | --- |
| Jupiter 2: Upper Deck Astrogator | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| The Liberator: Zen Flight Bridge | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| USS Cygnus: Victorian Engine Hall | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| USS Palomino: Deep Research Pod | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Discovery One: Habitation Centrifuge | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| Dark Star: Bomb Bay & Quarters | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| Gunstar: Tactical Combat Cockpit | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| The Searcher: 25th Century Flagship | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |

### Military (7 presets — ds9 ×3 · nx ×1 · tng ×1 · voyager ×2)

| Preset | Era | Elements heard |
| --- | --- | --- |
| USS Sulaco: Conestoga Hangar Deck | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Battlestar Galactica: Combat Information Center (CIC) | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| White Star: Minbari/Vorlon Hybrid Bridge | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| EAS Agamemnon: Omega Destroyer Bridge | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| Andromeda Ascendant: Command Deck | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| Excalibur: Victory-Class Heavy Combat Core | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| Colonial Viper Mk II: Cockpit Atmosphere | `voyager` | Double Chirp 60% · Sensor Sweep 40% |

### Deep Space (7 presets — ds9 ×2 · nx ×2 · tng ×2 · voyager ×1)

| Preset | Era | Elements heard |
| --- | --- | --- |
| The Avalon: Interstellar Cruise Concourse | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| The Nightflyer: Telepathic Corridor | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| USS Ascension: Generation Ship Promenade | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Ark One: Evacuation Ark Bridge | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| Icarus II: Solar Shield Core | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| Event Horizon: Gravity Singularity Core | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Lewis & Clark: Rescue Cutter Bridge | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |

### Outlaw (6 presets — ds9 ×1 · nx ×1 · tos ×2 · voyager ×2)

| Preset | Era | Elements heard |
| --- | --- | --- |
| The Betty: Salvage Freighter Mess | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Bebop: Living Quarters & Hangar | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| Outlaw Star: Grappler Bridge | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| Scorpio: Wanderer Salvage Vessel | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| The Marauder: Havoc Shuttle Bridge | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| The Milano: M-Ship Cockpit Lounge | `voyager` | Double Chirp 60% · Sensor Sweep 40% |

### Space Stations (6 presets — ds9 ×1 · nx ×2 · tng ×1 · tos ×1 · voyager ×1)

| Preset | Era | Elements heard |
| --- | --- | --- |
| Babylon 5: Core Control & Zocalo | `ds9` | Cardassian Sensor 50% · Single Chirp 50% |
| Moonbase Alpha: Main Mission Control | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |
| Sevastopol Station: Habitation Deck | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Tycho Station: Asteroid Construction Bay | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| Ceres Station: Sub-Crustal Tunnels | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Gateway Station: Quarantine Transfer Deck | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |

### Comedy (5 presets — nx ×1 · tng ×2 · tos ×1 · voyager ×1)

| Preset | Era | Elements heard |
| --- | --- | --- |
| USS Orville: Command Bridge | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| NSEA Protector: Beryllium Engine Room | `voyager` | Double Chirp 60% · Sensor Sweep 40% |
| Heart of Gold: Improbability Bridge | `tng` | Single Chirp 45% · Double Chirp 30% · Ack Sequence 15% · Sensor Sweep 10% |
| HMS Camden Lock: Flight Deck & Mess | `nx` | NX Hydraulic Relay 50% · NX Indicator Beep 50% |
| Spaceball One: Mega-Warship Bridge | `tos` | TOS Computer Warble 60% · TOS Relay Click 40% |

### Notes on the spread

- **Starfleet** is the only universe where the era always matches the fiction.
- **Whoniverse** spans all five eras across its seven presets — the widest
  spread of any universe, and the most likely place to hear something
  unexpected.
- **Retrofuture** leans on `tos` (3 of 8), which is at least era-plausible for
  mid-century-styled ships, but `Discovery One` and `The Searcher` are on full
  TNG LCARS.
- **Bioships** has no acoustic relationship to any Trek era; `Talyn` on `ds9`
  produces the Cardassian tritone tone inside a living-ship profile.
- **Comedy** and **Spaceball One** on `tos` produce the analog warble.

Two consequences worth keeping in mind when editing:

1. Changing a preset's `telemetry.era` silently changes which sounds it makes.
   There is no UI anywhere that names the active era, so the change is audible
   but not visible.
2. Any era value outside the five above falls through the `switch` in
   `playRandomTelemetrySound()` to the `tng` default. A typo does not fail
   loudly — it just produces LCARS chirps.

If a universe should stop borrowing Trek telemetry, the fix is a new era
vocabulary (new elements plus a new `case` in the era router), not a change to
these preset assignments alone — the router has nothing else to offer them.