fix: implement mobile-safe speaker fade-in

hburgund · hburgund · commit 1377ef33f91d · 2025-09-24T11:16:52.000-04:00
- Use setValueAtTime + linearRampToValueAtTime instead of cancelAndHoldAtTime
- Add 20ms scheduling epsilon to prevent "in the past" errors on mobile
- Start new speakers at NEARLY_ZERO and fade to target volume over 2s
- Make fade-in duration configurable via newSpeakerFadeInDurationMs
diff --git a/src/speaker/speaker_engine.test.ts b/src/speaker/speaker_engine.test.ts
@@ -427,6 +427,7 @@ describe("SpeakerEngine - repeatLoopOnLoopPoint", () => {
       offset: 0,
       pan: mockSpeakerTrack.loopConfig.pan,
       times: expect.any(Number),
+      isNewSpeaker: false, // This is a track repetition, not a new speaker
     });
   });
 
@@ -841,3 +842,182 @@ describe("SpeakerEngine - repeatLoopOnLoopPoint", () => {
     expect(secondCall.offset).toBe(0); // 25 % 10 = 5
   });
 });
+
+describe("SpeakerTrack - New Speaker Fade-In", () => {
+  let mockAudioContext: IAudioContext;
+  let mockSpeakerData: ISpeakerData;
+  let mockConfig: SpeakerConfig;
+
+  beforeEach(() => {
+    // Create mock audio context
+    mockAudioContext = {
+      currentTime: 0,
+      createBufferSource: jest.fn(() => ({
+        buffer: null,
+        loop: false,
+        start: jest.fn(),
+        stop: jest.fn(),
+        onended: null,
+        connect: jest.fn(),
+        disconnect: jest.fn(),
+      })),
+      createGain: jest.fn(() => ({
+        gain: {
+          value: 0,
+          cancelAndHoldAtTime: jest.fn(),
+          exponentialRampToValueAtTime: jest.fn(),
+          linearRampToValueAtTime: jest.fn(),
+          setValueAtTime: jest.fn(),
+        },
+        connect: jest.fn(),
+        disconnect: jest.fn(),
+      })),
+      createStereoPanner: jest.fn(() => ({
+        pan: { value: 0 },
+        connect: jest.fn(),
+        disconnect: jest.fn(),
+      })),
+      createBuffer: jest.fn(() => ({
+        duration: 10,
+        sampleRate: 44100,
+        numberOfChannels: 2,
+        length: 441000,
+        getChannelData: jest.fn(() => new Float32Array(441000)),
+      })),
+      destination: {},
+    } as any;
+
+    // Create mock speaker data
+    mockSpeakerData = {
+      id: 1,
+      maxvolume: 0.8,
+      minvolume: 0.1,
+      uri: "test-audio.mp3",
+      varianturis: [],
+      attenuation_distance: 50,
+      shape: {
+        type: "Feature",
+        geometry: {
+          type: "Polygon",
+          coordinates: [
+            [
+              [0, 0],
+              [1, 0],
+              [1, 1],
+              [0, 1],
+              [0, 0],
+            ],
+          ],
+        },
+        properties: {},
+      } as any,
+    };
+
+    // Create mock config with new speaker fade-in duration
+    mockConfig = {
+      mode: "progressive-sync-basePlusMax5Random",
+      newSpeakerFadeInDurationMs: 2000, // 2 seconds
+    };
+  });
+
+  it("should use configured fade-in duration", () => {
+    const speakerTrack = new SpeakerTrack({
+      data: mockSpeakerData,
+      config: mockConfig,
+      audioContext: mockAudioContext,
+      groupId: 1,
+    });
+
+    // Mock gain node
+    const mockGainNode = {
+      gain: {
+        value: 0,
+        cancelAndHoldAtTime: jest.fn(),
+        exponentialRampToValueAtTime: jest.fn(),
+        linearRampToValueAtTime: jest.fn(),
+        setValueAtTime: jest.fn(),
+      },
+    };
+    (speakerTrack as any).gainNode = mockGainNode;
+    (speakerTrack as any).calculatedVolume = 0.5;
+
+    // Call fadeInNewSpeaker
+    speakerTrack.fadeInNewSpeaker();
+
+    // Verify it uses configured 2000ms (2 seconds)
+    expect(mockGainNode.gain.setValueAtTime).toHaveBeenCalledWith(0.05, 0); // NEARLY_ZERO at current time
+    expect(mockGainNode.gain.linearRampToValueAtTime).toHaveBeenCalledWith(
+      0.5, // target volume
+      0 + 2 + 0.02 // current time + 2 seconds + epsilon
+    );
+  });
+
+  it("should use default fade-in duration when not configured", () => {
+    // Create config without newSpeakerFadeInDurationMs
+    const configWithoutFadeIn = {
+      mode: "progressive-sync-basePlusMax5Random" as const,
+    };
+
+    const speakerTrack = new SpeakerTrack({
+      data: mockSpeakerData,
+      config: configWithoutFadeIn,
+      audioContext: mockAudioContext,
+      groupId: 1,
+    });
+
+    // Mock gain node
+    const mockGainNode = {
+      gain: {
+        value: 0,
+        cancelAndHoldAtTime: jest.fn(),
+        exponentialRampToValueAtTime: jest.fn(),
+        linearRampToValueAtTime: jest.fn(),
+        setValueAtTime: jest.fn(),
+      },
+    };
+    (speakerTrack as any).gainNode = mockGainNode;
+    (speakerTrack as any).calculatedVolume = 0.5;
+
+    // Call fadeInNewSpeaker
+    speakerTrack.fadeInNewSpeaker();
+
+    // Verify it uses default 2000ms (2 seconds)
+    expect(mockGainNode.gain.setValueAtTime).toHaveBeenCalledWith(0.05, 0); // NEARLY_ZERO at current time
+    expect(mockGainNode.gain.linearRampToValueAtTime).toHaveBeenCalledWith(
+      0.5, // target volume
+      0 + 2 + 0.02 // current time + 2 seconds + epsilon
+    );
+  });
+
+  it("should start gain at 0 and fade to target volume", () => {
+    const speakerTrack = new SpeakerTrack({
+      data: mockSpeakerData,
+      config: mockConfig,
+      audioContext: mockAudioContext,
+      groupId: 1,
+    });
+
+    // Mock gain node
+    const mockGainNode = {
+      gain: {
+        value: 0,
+        cancelAndHoldAtTime: jest.fn(),
+        exponentialRampToValueAtTime: jest.fn(),
+        linearRampToValueAtTime: jest.fn(),
+        setValueAtTime: jest.fn(),
+      },
+    };
+    (speakerTrack as any).gainNode = mockGainNode;
+    (speakerTrack as any).calculatedVolume = 0.8;
+
+    // Call fadeInNewSpeaker
+    speakerTrack.fadeInNewSpeaker();
+
+    // Verify it fades from current volume to target volume
+    expect(mockGainNode.gain.setValueAtTime).toHaveBeenCalledWith(0.05, 0); // NEARLY_ZERO at current time
+    expect(mockGainNode.gain.linearRampToValueAtTime).toHaveBeenCalledWith(
+      0.8, // target volume (calculatedVolume)
+      0 + 2 + 0.02 // current time + 2 seconds + epsilon
+    );
+  });
+});
diff --git a/src/speaker/speaker_engine.ts b/src/speaker/speaker_engine.ts
@@ -631,6 +631,7 @@ export class SpeakerEngine extends EventEmitter<{
       fadeInDuration: isContinued ? 0 : FADE_IN_DURATION_SECONDS,
       times: 1,
       pan: 0,
+      isNewSpeaker: false, // Base track is not a new speaker
     });
     if (!isContinued) {
       track.on("trackFinished", this.onLoopPointBound);
@@ -947,6 +948,7 @@ export class SpeakerEngine extends EventEmitter<{
           fadeInDuration: 0, // No fade since it's continuing
           pan: panPosition,
           isReverse,
+          isNewSpeaker: false, // This is a continuation, not a new speaker
         });
         continue;
       }
@@ -1063,6 +1065,7 @@ export class SpeakerEngine extends EventEmitter<{
               times: Math.ceil(baseTrackDuration / duration),
               pan: panPosition,
               isReverse,
+              isNewSpeaker: true,
             });
           };
           newSpeaker.on("loaded", onLoaded);
@@ -1077,6 +1080,7 @@ export class SpeakerEngine extends EventEmitter<{
             fadeInDuration: FADE_IN_DURATION_SECONDS,
             pan: panPosition,
             isReverse,
+            isNewSpeaker: true,
           });
       } else {
         this.playingTracks[i] = null;
@@ -1118,6 +1122,7 @@ export class SpeakerEngine extends EventEmitter<{
       pan: speaker.loopConfig.pan,
       times: 1,
       isReverse: speaker.loopConfig.isReverse,
+      isNewSpeaker: false, // This is a fade-out scenario, not a new speaker
     });
     if (speaker.bufferSourcePlaying) speaker.fadeOutAndStopBufferSource();
   }
@@ -1223,6 +1228,7 @@ export class SpeakerEngine extends EventEmitter<{
         pan: track.loopConfig.pan,
         times: newTimes,
         isReverse: track.loopConfig.isReverse,
+        isNewSpeaker: false, // This is a track repetition, not a new speaker
       });
     } else {
       this.emit("repeatingTrack", {
@@ -1237,6 +1243,7 @@ export class SpeakerEngine extends EventEmitter<{
         pan: track.loopConfig.pan,
         times: baseTrackDuration / track.loopConfig.duration,
         isReverse: track.loopConfig.isReverse,
+        isNewSpeaker: false, // This is a track repetition, not a new speaker
       });
     }
   }
@@ -1413,6 +1420,7 @@ export class SpeakerEngine extends EventEmitter<{
               times: Math.ceil(baseTrackDuration / duration),
               pan: panPosition,
               isReverse,
+              isNewSpeaker: true,
             });
           };
           speaker.on("loaded", onLoaded);
@@ -1425,6 +1433,7 @@ export class SpeakerEngine extends EventEmitter<{
             fadeInDuration: FADE_IN_DURATION_SECONDS,
             pan: panPosition,
             isReverse,
+            isNewSpeaker: true,
           });
         }
       }
diff --git a/src/speaker/speaker_track.ts b/src/speaker/speaker_track.ts
@@ -288,13 +288,15 @@ export class SpeakerTrack extends EventEmitter<{
     fadeInDuration,
     pan,
     isReverse = false,
+    isNewSpeaker = false,
   }: {
     duration: number;
     offset: number;
     times: number;
     fadeInDuration: number;
     pan: number;
     isReverse?: boolean;
+    isNewSpeaker?: boolean;
   }) {
     this.loopConfig.duration = duration;
     this.loopConfig.times = times;
@@ -373,13 +375,17 @@ export class SpeakerTrack extends EventEmitter<{
 
     if (!this.gainNode) {
       this.gainNode = this.audioContext.createGain();
-      const MIN_AUDIBLE = 0.05;
-      const initial = Number.isFinite(this.calculatedVolume)
-        ? Math.max(MIN_AUDIBLE, this.calculatedVolume)
-        : MIN_AUDIBLE;
-      this.gainNode.gain.value = initial;
     }
 
+    const MIN_AUDIBLE = 0.05;
+    const initial = Number.isFinite(this.calculatedVolume)
+      ? Math.max(MIN_AUDIBLE, this.calculatedVolume)
+      : MIN_AUDIBLE;
+
+    // For new speakers, always start at NEARLY_ZERO to enable fade-in
+    // For existing speakers, start at calculated volume
+    this.gainNode.gain.value = isNewSpeaker ? NEARLY_ZERO : initial;
+
     // connections:
     this.bufferSource.connect(this.gainNode);
     // TEMP: bypass panning to test if StereoPannerNode churn contributes to dropouts
@@ -407,6 +413,14 @@ export class SpeakerTrack extends EventEmitter<{
 
     this.startBufferSource(this.audioContext.currentTime, offset || 0);
 
+    // Apply new speaker fade-in if this is a new speaker
+    if (isNewSpeaker) {
+      console.debug(
+        `Speaker ${this.data.id} starting as new speaker (audio context state: ${this.audioContext.state})`
+      );
+      this.fadeInNewSpeaker();
+    }
+
     const startedAtContextTime = this.startedAtContextTime;
 
     this.bufferSource.onended = () => {
@@ -481,6 +495,54 @@ export class SpeakerTrack extends EventEmitter<{
     }, FADE_DURATION_SECONDS * 1000);
   }
 
+  /**
+   * Start a graceful fade-in for a new speaker
+   * This applies a gain-node level fade-in over the specified duration
+   */
+  fadeInNewSpeaker() {
+    if (!this.gainNode) {
+      throw new Error("Gain node not found");
+    }
+
+    // Check audio context state before attempting fade-in
+    if (this.audioContext.state === "suspended") {
+      console.warn(
+        `Speaker ${this.data.id} fade-in aborted: Audio context is suspended`
+      );
+      return;
+    }
+
+    // Get fade-in duration from config, default to 2 seconds
+    const fadeInDurationMs = this.config?.newSpeakerFadeInDurationMs ?? 2000;
+    const fadeInDurationSeconds = fadeInDurationMs / 1000;
+
+    // Calculate target volume
+    const MIN_AUDIBLE = 0.05;
+    const targetVolume = Number.isFinite(this.calculatedVolume)
+      ? Math.max(MIN_AUDIBLE, this.calculatedVolume)
+      : MIN_AUDIBLE;
+
+    // Fade in from current volume (NEARLY_ZERO) to target volume
+    // Mobile-safe: avoid cancelAndHoldAtTime; explicitly set starting value and schedule a linear ramp with a tiny epsilon
+    const now = this.audioContext.currentTime;
+    const EPSILON_S = 0.02; // 20ms scheduling guard
+    this.gainNode.gain.setValueAtTime(NEARLY_ZERO, now);
+    this.gainNode.gain.linearRampToValueAtTime(
+      targetVolume,
+      now + fadeInDurationSeconds + EPSILON_S
+    );
+
+    console.debug(
+      `Speaker ${
+        this.data.id
+      } fading in from ${NEARLY_ZERO} to ${targetVolume.toFixed(
+        3
+      )} over ${fadeInDurationSeconds}s (audio context state: ${
+        this.audioContext.state
+      })`
+    );
+  }
+
   startBufferSource(when: number, offset: number) {
     if (this.bufferSource) {
       this.bufferSource.start(when, offset);
diff --git a/src/types/roundware.ts b/src/types/roundware.ts
@@ -84,4 +84,7 @@ export type SpeakerConfig = {
 
   // always-on speakers - these speakers will always play when available (in range)
   alwaysOnWhenAvailable?: number[]; // array of speaker IDs that should always play when available
+
+  // new speaker fade-in configuration
+  newSpeakerFadeInDurationMs?: number; // default: 2000 (2 seconds)
 };
