Add Hold checkbox for envelopes with no natural end

The Hold checkbox in the transport row sets the SOUND BASIC line to
duration -1 (BBC syntax for "envelope keeps running until interrupted")
and makes expand() generate ~15 s of samples without ever transitioning
to release. Pitch and amp envelopes keep evolving exactly as they would
inside the SOUND duration.

UG #8 sweep and UG #9 ramp default to hold on, since their AR=0 means
they never naturally terminate; loadPreset reads a new optional
Preset.hold flag. Other presets clear it on load.

Persisted in the URL via &hold=1 so shared links carry the state.

Initially named "Loop" but Loop conflicts with the pitch envelope's
own loop (T<128) and implies the audio repeats from the start, which
is not what BBC -1 does. Renamed to Hold throughout.

Author: kieranhj

index.html

@@ -46,6 +46,7 @@ <h2>Visualisation</h2>
             <div class="transport">
               <button id="play">Play</button>
               <button id="stop">Stop</button>
+              <label class="hold-toggle" title="Hold the note indefinitely (BBC SOUND duration -1)"><input type="checkbox" id="hold" /> Hold</label>
               <button id="share-link" title="Copy a shareable URL with auto-play that reproduces the current envelope and sound">Copy share link</button>
               <button id="run-emulator" title="Open bbc.xania.org with the current ENVELOPE and SOUND auto-running">Run in BBC emulator ↗</button>
             </div>

src/envelope.ts

@@ -56,7 +56,7 @@ const PITCH_NO_REPEAT_BIT = 0x80;
  * The returned stream covers attack + decay + sustain + release, i.e. the
  * full audible lifetime of the note.
  */
-export function expand(env: Envelope, soundAmplitude: number, soundDuration: number): Sample[] {
+export function expand(env: Envelope, soundAmplitude: number, soundDuration: number, hold = false): Sample[] {
   const samples: Sample[] = [];
 
   // SOUND amplitude argument: 0 = silence, -15..-1 = static volume, 1..4 = envelope number.
@@ -65,6 +65,14 @@ export function expand(env: Envelope, soundAmplitude: number, soundDuration: num
   // the envelope is bypassed entirely; we still let callers preview the envelope shape.
   const useEnvelope = soundAmplitude > 0;
 
+  // Hold mode mirrors BBC SOUND duration -1: the envelope keeps running its
+  // attack/decay/sustain phases without ever transitioning to release. Amp,
+  // pitch and the looping pitch envelope all keep evolving exactly as they
+  // would within the SOUND duration; the note just doesn't terminate. We
+  // generate ~15 s of audio so the cycling state is audible/visible — the
+  // user can press Stop or replay to extend.
+  const HOLD_NOTE_CS = 1500;
+
   // Pitch envelope state.
   const tStep = env.t & 0x7f;          // step length in centiseconds
   const repeat = (env.t & PITCH_NO_REPEAT_BIT) === 0;
@@ -118,7 +126,7 @@ export function expand(env: Envelope, soundAmplitude: number, soundDuration: num
 
   // Amplitude envelope state.
   // Phases run in order: attack -> decay -> sustain (until note ends) -> release (to 0).
-  const noteCentiseconds = soundDuration * 5; // 1/20s -> 1/100s
+  const noteCentiseconds = hold ? HOLD_NOTE_CS : soundDuration * 5; // 1/20s -> 1/100s
   let amplitude = 0;
   let phase: Sample["phase"] = "attack";
   let csElapsed = 0;
@@ -143,9 +151,18 @@ export function expand(env: Envelope, soundAmplitude: number, soundDuration: num
     // SOUND duration end forces release from any non-release phase. The check
     // is per-cs so release starts at the right cs even if it's between
     // envelope ticks; the actual release amp change happens on the next tick.
-    if (useEnvelope && phase !== "release" && csElapsed + 1 >= noteCentiseconds) {
-      phase = "release";
-      if (releaseStartedAt < 0) releaseStartedAt = csElapsed;
+    // In hold mode (BBC SOUND duration -1) the envelope keeps running its
+    // attack/decay/sustain phases without ever transitioning to release —
+    // we just stop emitting samples at the bound.
+    if (useEnvelope && csElapsed + 1 >= noteCentiseconds) {
+      if (hold) {
+        samples.push({ pitchOffset, amplitude: clamp(amplitude, 0, 126), phase });
+        return samples;
+      }
+      if (phase !== "release") {
+        phase = "release";
+        if (releaseStartedAt < 0) releaseStartedAt = csElapsed;
+      }
     }
 
     // Envelope tick: pitch step *and* amplitude envelope advance every T cs.
@@ -237,9 +254,13 @@ export function formatBasic(env: Envelope): string {
   return `ENVELOPE ${parts.join(",")}`;
 }
 
-/** Format a BBC BASIC `SOUND` statement. */
-export function formatSound(channel: number, amplitude: number, pitch: number, duration: number): string {
-  return `SOUND ${channel},${amplitude},${pitch},${duration}`;
+/**
+ * Format a BBC BASIC `SOUND` statement. `hold=true` emits duration -1, which
+ * is BBC BASIC syntax for "envelope keeps running until interrupted".
+ */
+export function formatSound(channel: number, amplitude: number, pitch: number, duration: number, hold = false): string {
+  const dur = hold ? -1 : duration;
+  return `SOUND ${channel},${amplitude},${pitch},${dur}`;
 }
 
 /**

src/main.ts

@@ -61,6 +61,8 @@ const SOUND_FIELDS: { key: keyof SoundParams; code: string; label: string; min:
 const env: Envelope = { ...DEFAULT_ENVELOPE };
 const sound: SoundParams = { ...DEFAULT_SOUND };
 
+let holdEnabled = false;
+
 // Capture before refresh() rewrites the URL via history.replaceState (which
 // strips presence-only params like `play`).
 const autoplayRequested = new URLSearchParams(location.search).has("play");
@@ -70,10 +72,14 @@ const canvas = document.getElementById("viz") as HTMLCanvasElement;
 const envelopeLine = document.getElementById("envelope-line") as HTMLInputElement;
 const soundLine = document.getElementById("sound-line") as HTMLInputElement;
 const envNInput = document.getElementById("env-n") as HTMLInputElement;
+const holdInput = document.getElementById("hold") as HTMLInputElement;
 const pitchGrid = document.getElementById("pitch-grid") as HTMLElement;
 const ampGrid = document.getElementById("amp-grid") as HTMLElement;
 const soundGrid = document.getElementById("sound-grid") as HTMLElement;
 
+// Sync the checkbox to whatever loadFromUrlParams() may have set above.
+holdInput.checked = holdEnabled;
+
 const envInputs = new Map<keyof Envelope, HTMLInputElement>();
 const soundInputs = new Map<keyof SoundParams, HTMLInputElement>();
 
@@ -103,10 +109,10 @@ function setEnvelopeNumber(n: number): void {
 }
 
 function refresh(skipLine?: "envelope" | "sound"): void {
-  currentSamples = expand(env, sound.amplitude, sound.duration);
+  currentSamples = expand(env, sound.amplitude, sound.duration, holdEnabled);
   render(canvas, currentSamples, sound.pitch, playheadFraction());
   if (skipLine !== "envelope") envelopeLine.value = formatBasic(env);
-  if (skipLine !== "sound") soundLine.value = formatSound(sound.channel, sound.amplitude, sound.pitch, sound.duration);
+  if (skipLine !== "sound") soundLine.value = formatSound(sound.channel, sound.amplitude, sound.pitch, sound.duration, holdEnabled);
   updateUrlParams();
   // Any state change clears the active preset; loadPreset re-sets it after
   // its own refresh() call.
@@ -123,6 +129,7 @@ function updateUrlParams(): void {
                      env.aa, env.ad, env.as, env.ar, env.ala, env.ald].join(",");
   const soundValues = [sound.channel, sound.amplitude, sound.pitch, sound.duration].join(",");
   const params = new URLSearchParams({ env: envValues, sound: soundValues });
+  if (holdEnabled) params.set("hold", "1");
   history.replaceState(null, "", `?${params.toString()}`);
 }
 
@@ -142,6 +149,7 @@ function loadFromUrlParams(): void {
     const parsed = parseSound(soundStr);
     if (parsed) Object.assign(sound, parsed);
   }
+  if (params.has("hold")) holdEnabled = true;
 }
 
 function animatePlayhead(): void {
@@ -253,6 +261,17 @@ soundLine.addEventListener("input", () => {
     return;
   }
   soundLine.classList.remove("invalid");
+  // BBC BASIC duration -1 means "play forever". Map that to our loop flag
+  // and keep a reasonable per-cycle duration so the visualisation has
+  // something to show.
+  if (parsed.duration < 0) {
+    holdEnabled = true;
+    holdInput.checked = true;
+    parsed.duration = sound.duration > 0 ? sound.duration : 20;
+  } else {
+    holdEnabled = false;
+    holdInput.checked = false;
+  }
   Object.assign(sound, parsed);
   setEnvelopeNumber(sound.amplitude);
   for (const f of SOUND_FIELDS) {
@@ -273,6 +292,10 @@ function setActivePreset(idx: number | null): void {
 function loadPreset(p: Preset, idx: number): void {
   Object.assign(env, p.env);
   Object.assign(sound, p.sound);
+  // Apply the preset's hold flag (defaults to false). UG #8/#9 set it
+  // because their envelopes don't naturally terminate.
+  holdEnabled = p.hold === true;
+  holdInput.checked = holdEnabled;
   setEnvelopeNumber(sound.amplitude);
   for (const f of ENV_FIELDS) {
     const input = envInputs.get(f.key);
@@ -300,18 +323,37 @@ PRESETS.forEach((p, idx) => {
   presetButtons.push(btn);
 });
 
-document.getElementById("play")!.addEventListener("click", () => {
+function playOnce(): void {
+  // The sample stream itself is long when holdEnabled (expand returns a
+  // ~15 s buffer with the envelope's pitch and amp continuing to evolve),
+  // so audio playback is just a single play() call — no setTimeout-based
+  // re-trigger. Mirrors BBC SOUND duration -1 semantics: envelope keeps
+  // running, doesn't restart from the top.
   play(currentSamples, sound.pitch);
   animatePlayhead();
-});
+}
 
-document.getElementById("stop")!.addEventListener("click", () => {
+function stopAll(): void {
   stop();
   if (playheadRaf !== null) {
     cancelAnimationFrame(playheadRaf);
     playheadRaf = null;
   }
   render(canvas, currentSamples, sound.pitch, null);
+}
+
+document.getElementById("play")!.addEventListener("click", () => {
+  playOnce();
+});
+
+document.getElementById("stop")!.addEventListener("click", () => {
+  stopAll();
+});
+
+holdInput.addEventListener("change", () => {
+  holdEnabled = holdInput.checked;
+  // Reflect in the SOUND BASIC line and URL.
+  refresh();
 });
 
 document.getElementById("share-link")!.addEventListener("click", async (e) => {
@@ -337,7 +379,7 @@ document.getElementById("run-emulator")!.addEventListener("click", () => {
   // jsbeeb (bbc.xania.org) takes URL-encoded BASIC via embedBasic, with
   // &autorun to type RUN after tokenising. Two numbered lines are enough:
   // ENVELOPE registers the envelope, SOUND queues the note.
-  const program = `10 ${formatBasic(env)}\n20 ${formatSound(sound.channel, sound.amplitude, sound.pitch, sound.duration)}\n`;
+  const program = `10 ${formatBasic(env)}\n20 ${formatSound(sound.channel, sound.amplitude, sound.pitch, sound.duration, holdEnabled)}\n`;
   const url = `https://bbc.xania.org/?embedBasic=${encodeURIComponent(program)}&autorun`;
   window.open(url, "_blank", "noopener,noreferrer");
 });

src/presets.ts

@@ -12,6 +12,9 @@ export interface Preset {
   description: string;
   env: Envelope;
   sound: SoundPreset;
+  /** True for envelopes that don't naturally terminate — sets the Hold
+   *  checkbox so the audio keeps the envelope running indefinitely. */
+  hold?: boolean;
 }
 
 // `T` in 1..127 auto-repeats the pitch envelope for the duration of the
@@ -240,12 +243,14 @@ export const PRESETS: Preset[] = [
     env: { n: 1, t: 1, pi1: -26, pi2: -36, pi3: -45, pn1: 255, pn2: 255, pn3: 255,
            aa: 127, ad: 0, as: 0, ar: 0, ala: 126, ald: 0 },
     sound: { channel: 1, amplitude: 1, pitch: 1, duration: 1 },
+    hold: true,
   },
   {
     name: "UG #9 ramp",
     description: "BBC User Guide example — three-section pitch envelope with large excursions (rise +100, drop -200, rise +200 per loop). Net +100 per loop produces an upward-drifting sweep over a long held-loud tone.",
     env: { n: 2, t: 3, pi1: 2, pi2: -4, pi3: 4, pn1: 50, pn2: 50, pn3: 50,
            aa: 127, ad: 0, as: 0, ar: 0, ala: 126, ald: 0 },
     sound: { channel: 1, amplitude: 2, pitch: 1, duration: 10 },
+    hold: true,
   },
 ];

src/style.css

@@ -198,7 +198,18 @@ canvas {
   display: flex;
   gap: 8px;
   margin: 12px 0;
+  align-items: center;
+}
+.hold-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 0.85rem;
+  color: #c9d1d9;
+  cursor: pointer;
+  user-select: none;
 }
+.hold-toggle input { cursor: pointer; }
 
 .presets {
   display: flex;