fix(sound): share pan sampling during playback

src/bundles/sound/src/__tests__/conductorAdapters.test.ts

@@ -0,0 +1,49 @@
+import { DataType, type IDataHandler, type TypedValue } from '@sourceacademy/conductor/types';
+import { describe, expect, test } from 'vitest';
+import { rememberSoundSampler, restoreSoundSampler } from '../conductorAdapters';
+import type { Sound, SoundSampler, Wave } from '../types';
+
+function closure(id: number): TypedValue<DataType.CLOSURE> {
+  return {
+    type: DataType.CLOSURE,
+    value: id as TypedValue<DataType.CLOSURE>['value']
+  };
+}
+
+async function* silentWave(): ReturnType<Wave> {
+  return 0;
+}
+
+async function* sampler(_duration: number): ReturnType<SoundSampler> {
+  const samples = new Float32Array(0);
+  return { left: samples, right: samples };
+}
+
+function decodedSound(duration: number): Omit<Sound, 'sampleChannels'> {
+  return { leftWave: silentWave, rightWave: silentWave, duration };
+}
+
+describe('Sound sampler Conductor metadata', () => {
+  test('survives fresh closure wrappers for the same evaluator and Sound identity', () => {
+    const evaluator = {} as IDataHandler;
+    const sound = { ...decodedSound(1), sampleChannels: sampler };
+    rememberSoundSampler(evaluator, sound, closure(11), closure(12));
+
+    const restored = restoreSoundSampler(evaluator, decodedSound(1), closure(11), closure(12));
+
+    expect(restored.sampleChannels).toBe(sampler);
+  });
+
+  test('does not leak to another duration, closure pair, or evaluator', () => {
+    const evaluator = {} as IDataHandler;
+    const sound = { ...decodedSound(1), sampleChannels: sampler };
+    rememberSoundSampler(evaluator, sound, closure(11), closure(12));
+
+    expect(restoreSoundSampler(evaluator, decodedSound(2), closure(11), closure(12)).sampleChannels)
+      .toBeUndefined();
+    expect(restoreSoundSampler(evaluator, decodedSound(1), closure(11), closure(13)).sampleChannels)
+      .toBeUndefined();
+    expect(restoreSoundSampler({} as IDataHandler, decodedSound(1), closure(11), closure(12)).sampleChannels)
+      .toBeUndefined();
+  });
+});

src/bundles/sound/src/__tests__/sound.test.ts

@@ -29,6 +29,13 @@ function constantWave(value: number): Wave {
   };
 }
 
+function countedWave(value: number, calls: { count: number }): Wave {
+  return async function* () {
+    calls.count += 1;
+    return value;
+  };
+}
+
 async function sampleAt(wave: Wave, t: number): Promise<number> {
   return drain(wave(t));
 }
@@ -374,6 +381,17 @@ describe(funcs.pan, () => {
     expect(await sampleAt(funcs.get_left_wave(panned), 0)).toBeCloseTo(0.5);
     expect(await sampleAt(funcs.get_right_wave(panned), 0)).toBeCloseTo(0.5);
   });
+
+  it('samples the squashed source wave once per timestamp when played', async () => {
+    const calls = { count: 0 };
+    const duration = 5 / funcs.FS;
+    const expectedSamples = Math.ceil(funcs.FS * duration);
+    const sound = funcs.make_sound(countedWave(1, calls), duration);
+
+    await drain(funcs.play(funcs.pan(0)(sound)));
+
+    expect(calls.count).toBe(expectedSamples);
+  });
 });
 
 describe(funcs.pan_mod, () => {
@@ -384,6 +402,20 @@ describe(funcs.pan_mod, () => {
     expect(await sampleAt(funcs.get_left_wave(panned), 0)).toBeCloseTo(0);
     expect(await sampleAt(funcs.get_right_wave(panned), 0)).toBeCloseTo(1);
   });
+
+  it('samples the source and modulator waves once per timestamp when played', async () => {
+    const sourceCalls = { count: 0 };
+    const modulatorCalls = { count: 0 };
+    const duration = 5 / funcs.FS;
+    const expectedSamples = Math.ceil(funcs.FS * duration);
+    const sound = funcs.make_sound(countedWave(1, sourceCalls), duration);
+    const modulator = funcs.make_sound(countedWave(0.25, modulatorCalls), duration);
+
+    await drain(funcs.play(funcs.pan_mod(modulator)(sound)));
+
+    expect(sourceCalls.count).toBe(expectedSamples);
+    expect(modulatorCalls.count).toBe(expectedSamples);
+  });
 });
 
 describe(funcs.adsr, () => {

src/bundles/sound/src/conductorAdapters.ts

@@ -0,0 +1,55 @@
+/**
+ * Undecorated helpers for the Conductor boundary. Keeping them outside index.ts makes them
+ * importable from Vitest, whose transform does not use this bundle's standard-decorator settings.
+ */
+import type { DataType, IDataHandler, TypedValue } from '@sourceacademy/conductor/types';
+import type { Sound, SoundSampler } from './types';
+
+// sampleChannels is an internal playback optimisation and cannot be represented in the public
+// [[left_wave, right_wave], duration] Sound pair. Preserve it using stable Conductor closure ids:
+// Python round-trips recreate TypedValue/pair wrappers, while those ids still refer to the same
+// waves. The evaluator key scopes both ids and cache lifetime to a single run.
+const soundSamplerCache = new WeakMap<
+  IDataHandler,
+  Map<number, Map<number, Map<number, SoundSampler>>>
+>();
+
+export function rememberSoundSampler(
+  evaluator: IDataHandler,
+  sound: Sound,
+  leftClosure: TypedValue<DataType.CLOSURE>,
+  rightClosure: TypedValue<DataType.CLOSURE>
+): void {
+  if (!sound.sampleChannels) return;
+
+  let byLeftClosure = soundSamplerCache.get(evaluator);
+  if (!byLeftClosure) {
+    byLeftClosure = new Map();
+    soundSamplerCache.set(evaluator, byLeftClosure);
+  }
+  let byRightClosure = byLeftClosure.get(leftClosure.value);
+  if (!byRightClosure) {
+    byRightClosure = new Map();
+    byLeftClosure.set(leftClosure.value, byRightClosure);
+  }
+  let byDuration = byRightClosure.get(rightClosure.value);
+  if (!byDuration) {
+    byDuration = new Map();
+    byRightClosure.set(rightClosure.value, byDuration);
+  }
+  byDuration.set(sound.duration, sound.sampleChannels);
+}
+
+export function restoreSoundSampler(
+  evaluator: IDataHandler,
+  sound: Omit<Sound, 'sampleChannels'>,
+  leftClosure: TypedValue<DataType.CLOSURE>,
+  rightClosure: TypedValue<DataType.CLOSURE>
+): Sound {
+  const sampleChannels = soundSamplerCache
+    .get(evaluator)
+    ?.get(leftClosure.value)
+    ?.get(rightClosure.value)
+    ?.get(sound.duration);
+  return sampleChannels ? { ...sound, sampleChannels } : sound;
+}

src/bundles/sound/src/functions.ts

@@ -34,7 +34,7 @@ import { midi_note_to_frequency } from '@sourceacademy/bundle-midi/functions';
 import { EvaluatorParameterTypeError, EvaluatorRuntimeError } from '@sourceacademy/conductor/common';
 import { delay } from 'es-toolkit/promise';
 import type { SoundTabRpc } from './protocol';
-import type { Sound, SoundProducer, SoundTransformer, SyncWave, Wave } from './types';
+import type { Sound, SoundProducer, SoundSampler, SoundTransformer, StereoSamples, SyncWave, Wave } from './types';
 
 export const FS: number = 44100; // Output sample rate
 const fourier_expansion_level: number = 5;
@@ -286,21 +286,38 @@ async function* sampleWave(wave: Wave, duration: number): AsyncGenerator<void, F
     // The fast path: no generator allocation, no Promise, no microtask per sample - see
     // `Wave.sync`'s doc in types.ts. Falls back to the yield*-driven path (which threads a
     // student-supplied wave's steps up to the CSE machine) the moment `sync` is unset.
-    let temp = sync ? sync(i / FS) : yield* wave(i / FS);
-    if (temp > 1) {
-      temp = 1;
-    } else if (temp < -1) {
-      temp = -1;
-    }
-    if (temp === 0 && Math.abs(temp - prev_value) > 0.01) {
-      temp = prev_value * 0.999;
-    }
+    const temp = smoothSample(sync ? sync(i / FS) : yield* wave(i / FS), prev_value);
     channel[i] = temp;
     prev_value = temp;
   }
   return channel;
 }
 
+function smoothSample(sample: number, previousSample: number): number {
+  let temp = sample;
+  if (temp > 1) {
+    temp = 1;
+  } else if (temp < -1) {
+    temp = -1;
+  }
+  if (temp === 0 && Math.abs(temp - previousSample) > 0.01) {
+    temp = previousSample * 0.999;
+  }
+  return temp;
+}
+
+async function* sampleSound(sound: Sound): AsyncGenerator<void, StereoSamples, undefined> {
+  if (sound.sampleChannels) {
+    return yield* sound.sampleChannels(sound.duration);
+  }
+
+  const left = yield* sampleWave(sound.leftWave, sound.duration);
+  return {
+    left,
+    right: sound.rightWave === sound.leftWave ? left : yield* sampleWave(sound.rightWave, sound.duration)
+  };
+}
+
 /** Builds a Wave that linearly interpolates between recorded PCM samples. */
 function interpolatedWave(samples: Float32Array<ArrayBuffer>, sampleRate: number): Wave {
   return syncWave(t => {
@@ -502,9 +519,7 @@ export async function* play(sound: Sound): AsyncGenerator<void, Sound, undefined
   // rather than looking stalled during what can be a noticeable wait for longer sounds. Awaited
   // (not fire-and-forget) so this can't race the tab's own (possibly still in-progress) loading.
   await io().notifyConstructing();
-  const leftSamples = yield* sampleWave(sound.leftWave, duration);
-  // Mono sounds have leftWave === rightWave: sample once instead of twice.
-  const rightSamples = sound.rightWave === sound.leftWave ? leftSamples : yield* sampleWave(sound.rightWave, duration);
+  const { left: leftSamples, right: rightSamples } = yield* sampleSound(sound);
   globalVars.activePlayCount += 1;
   const generation = playGeneration;
   // Fire-and-forget from the caller's perspective (matching the original's non-blocking
@@ -883,6 +898,18 @@ function gainWave(wave: Wave, gain: number): Wave {
   };
 }
 
+function make_stereo_sound_with_sampler(
+  left_wave: Wave,
+  right_wave: Wave,
+  duration: number,
+  sampleChannels: SoundSampler
+): Sound {
+  return {
+    ...make_stereo_sound(left_wave, right_wave, duration),
+    sampleChannels
+  };
+}
+
 /**
  * Centers a Sound by averaging its left and right channels, resulting in an effectively mono
  * Sound (both channels are the same, averaged, wave).
@@ -917,17 +944,59 @@ export function pan(amount: number): SoundTransformer {
   const clamped = Math.max(-1, Math.min(1, amount));
   return sound => {
     const { leftWave: wave, duration } = squash(sound);
-    return make_stereo_sound(
+    return make_stereo_sound_with_sampler(
       gainWave(wave, (1 - clamped) / 2),
       gainWave(wave, (1 + clamped) / 2),
-      duration
+      duration,
+      duration => samplePannedChannels(wave, duration, clamped)
     );
   };
 }
 
+async function* samplePannedChannels(
+  wave: Wave,
+  duration: number,
+  amount: number
+): AsyncGenerator<void, StereoSamples, undefined> {
+  const length = Math.ceil(FS * duration);
+  const left = new Float32Array(length);
+  const right = new Float32Array(length);
+  const leftGain = (1 - amount) / 2;
+  const rightGain = (1 + amount) / 2;
+  let prevLeft = 0;
+  let prevRight = 0;
+  const sync = wave.sync;
+
+  for (let i = 0; i < length; i += 1) {
+    const t = i / FS;
+    const sample = sync ? sync(t) : yield* wave(t);
+    const leftSample = smoothSample(leftGain * sample, prevLeft);
+    const rightSample = smoothSample(rightGain * sample, prevRight);
+    left[i] = leftSample;
+    right[i] = rightSample;
+    prevLeft = leftSample;
+    prevRight = rightSample;
+  }
+
+  return { left, right };
+}
+
 /** Modulates the pan amount at time `t` using `modulator`'s two channels, clamped to [-1, 1]. */
 function panModAmountWave(modulator: Sound): Wave {
   const { leftWave, rightWave } = modulator;
+  if (leftWave === rightWave) {
+    if (leftWave.sync) {
+      const sync = leftWave.sync;
+      return syncWave(t => {
+        const output = sync(t);
+        return Math.max(-1, Math.min(1, output + output));
+      });
+    }
+    return async function* (t: number) {
+      const output = yield* leftWave(t);
+      return Math.max(-1, Math.min(1, output + output));
+    };
+  }
   if (leftWave.sync && rightWave.sync) {
     const leftSync = leftWave.sync;
     const rightSync = rightWave.sync;
@@ -953,24 +1022,54 @@ export function pan_mod(modulator: Sound): SoundTransformer {
     if (amountWave.sync && wave.sync) {
       const amountSync = amountWave.sync;
       const sync = wave.sync;
-      return make_stereo_sound(
+      return make_stereo_sound_with_sampler(
         syncWave(t => ((1 - amountSync(t)) / 2) * sync(t)),
         syncWave(t => ((1 + amountSync(t)) / 2) * sync(t)),
-        duration
+        duration,
+        duration => samplePanModChannels(wave, amountWave, duration)
       );
     }
-    return make_stereo_sound(
+    return make_stereo_sound_with_sampler(
       async function* (t: number) {
         return ((1 - (yield* amountWave(t))) / 2) * (yield* wave(t));
       },
       async function* (t: number) {
         return ((1 + (yield* amountWave(t))) / 2) * (yield* wave(t));
       },
-      duration
+      duration,
+      duration => samplePanModChannels(wave, amountWave, duration)
     );
   };
 }
 
+async function* samplePanModChannels(
+  wave: Wave,
+  amountWave: Wave,
+  duration: number
+): AsyncGenerator<void, StereoSamples, undefined> {
+  const length = Math.ceil(FS * duration);
+  const left = new Float32Array(length);
+  const right = new Float32Array(length);
+  let prevLeft = 0;
+  let prevRight = 0;
+  const amountSync = amountWave.sync;
+  const waveSync = wave.sync;
+
+  for (let i = 0; i < length; i += 1) {
+    const t = i / FS;
+    const amount = amountSync ? amountSync(t) : yield* amountWave(t);
+    const sample = waveSync ? waveSync(t) : yield* wave(t);
+    const leftSample = smoothSample(((1 - amount) / 2) * sample, prevLeft);
+    const rightSample = smoothSample(((1 + amount) / 2) * sample, prevRight);
+    left[i] = leftSample;
+    right[i] = rightSample;
+    prevLeft = leftSample;
+    prevRight = rightSample;
+  }
+
+  return { left, right };
+}
+
 // ---------------------------------------------
 // Instruments
 // ---------------------------------------------

src/bundles/sound/src/index.ts

@@ -36,6 +36,7 @@ import { BaseModulePlugin, moduleMethod } from '@sourceacademy/conductor/module'
 import type { IInterfacableEvaluator } from '@sourceacademy/conductor/runner';
 import { DataType, type IDataHandler, type TypedValue } from '@sourceacademy/conductor/types';
 
+import { rememberSoundSampler, restoreSoundSampler } from './conductorAdapters';
 import {
   adsr as adsr_func,
   bell as bell_func,
@@ -237,6 +238,7 @@ async function soundToConductor(evaluator: IDataHandler, sound: Sound): Promise<
   const rightClosure = sound.rightWave === sound.leftWave
     ? leftClosure
     : await waveToConductorClosure(evaluator, sound.rightWave);
+  rememberSoundSampler(evaluator, sound, leftClosure, rightClosure);
   const wavesPair = await evaluator.pair_make(leftClosure, rightClosure);
   return evaluator.pair_make(wavesPair, { type: DataType.NUMBER, value: sound.duration });
 }
@@ -299,7 +301,12 @@ export async function conductorToSound(evaluator: IDataHandler, value: TypedValu
   // id - if it's the same id, this is a mono Sound and should stay that way (same Wave reference)
   // rather than getting two distinct-but-identical wrappers around it.
   const rightWave = leftTv.value === rightTv.value ? leftWave : closureToWave(evaluator, rightTv);
-  return { leftWave, rightWave, duration: durationTv.value };
+  return restoreSoundSampler(
+    evaluator,
+    { leftWave, rightWave, duration: durationTv.value },
+    leftTv,
+    rightTv
+  );
 }
 
 /** Walks a Conductor LIST of Sounds (either shape - see `readListElements`) into a plain array. */