From e3324e8b81743da6c5d2920dc23f4ba65029ad44 Mon Sep 17 00:00:00 2001
From: veltsonbastien <bastienveltson@outlook.com>
Date: Tue, 11 Aug 2026 15:04:46 -0700
Subject: [PATCH 1/2] feat: expose the assistant audio element for playback
 volume control

## Problem

The SDK creates an `<audio>` element per remote track in `buildAudioPlayer`
and discards the reference, so there is no supported way to reach it. There is
no way to set playback volume at all: `volume-level` only reports measured
loudness, and `setMuted` affects the user's microphone.

Consumers work around this by querying the DOM for
`audio[data-participant-id]`, which relies on an internal detail and can match
an orphaned element from a previous call (#161). Requested in #37.

## What this adds

- `setVolume(volume)` for assistant playback volume, 0 to 1. The value is
  remembered, so it can be set before the track arrives and it survives across
  calls and mid-call track replacement. Out-of-range values are clamped and
  non-finite values ignored, since the DOM rejects both rather than saturating.
- `getAudioPlayer()` returning the element, or null before its track arrives.
- An `audio` event carrying the element the moment it exists, mirroring how
  `video` already emits one line above in the same handler.
- An `error` of type `audio-start-failed` when the browser blocks playback,
  which is usually autoplay policy and is recoverable by prompting for a
  gesture. Previously this surfaced only as an unhandled rejection.

Pairing a getter with an event matches `getLocalAudioLevel` alongside
`local-volume-level`.

## Lifecycle correctness

`buildAudioPlayer` awaits `play()`, which pends for the whole of media startup,
so several players can be in flight, they can finish out of order, and the call
or the participant can go away underneath them. Each build now takes a sequence
number and records its participant while pending, so that:

- a player built for a call that has since ended or been replaced is discarded
- a teardown invalidates only the departing participant's builds, so an
  unrelated participant leaving cannot cost us the assistant's audio
- a build that started before the one currently attached cannot overwrite it
- a superseded element is removed when its replacement is adopted, which
  matters because renegotiation reuses the participant id and both elements
  would otherwise match the selector teardown uses
- the reference is dropped in `stop()`, `cleanup()` and on `participant-left`,
  so `setVolume` can never write to a torn-down player

Consumer emits are routed through `emitToConsumer`, because a listener that
threw previously propagated out of the `track-started` handler and skipped
`sendAppMessage('playable')`, stalling the call. This applied to the existing
`video` emit too.

`handleTrackStarted` is extracted so the initial and reconnect paths share it
rather than being two byte-identical copies.

## Not addressed

The orphaned elements themselves (#161). This ensures the new API never hands
back an orphan, but does not stop them accumulating. Relatedly, `playable` is
still not sent when playback genuinely fails, which is unchanged behavior and a
question about what that signal means server-side.

## Testing

46 tests, `tsc`, `npm run build` and `npm run test:example` all pass. No
dependency, lockfile, tsconfig, packaging or CI changes.

The two functions that touch the DOM are reached through thin private wrappers
so the lifecycle logic around them is covered in the existing node test
environment without adding a DOM dependency. Every fix above was mutation
tested: reverting it fails the suite. Still uncovered, as on main: the DOM
calls themselves.

Also verified by hand on two live calls, confirming a volume set before the
call is applied to the real element and persists into the next call.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                     |  46 ++++
 __tests__/audioPlayer.test.ts | 432 ++++++++++++++++++++++++++++++++++
 __tests__/vapi.test.ts        | 106 +++++++++
 vapi.ts                       | 286 +++++++++++++++++++---
 4 files changed, 831 insertions(+), 39 deletions(-)
 create mode 100644 __tests__/audioPlayer.test.ts

diff --git a/README.md b/README.md
index 308a15657..d62ffa300 100644
--- a/README.md
+++ b/README.md
@@ -105,6 +105,47 @@ The `say(message: string, endCallAfterSpoken?: boolean)` can be used to invoke s
 vapi.say("Our time's up, goodbye!", true)
 ```
 
+The `setVolume(volume: number)` controls how loudly the assistant plays, from
+`0` to `1`. This is playback only: it does not change what the assistant hears,
+and it does not affect the levels reported by the `volume-level` event.
+
+```javascript
+vapi.setVolume(0.5);
+```
+
+The setting is remembered, so you can call it before a call has started and it
+will be applied as soon as the assistant's audio arrives. It also persists
+across calls, so a volume your user picked once is not reset by hanging up.
+Values outside `0` to `1` are clamped, and non-finite values are ignored.
+
+The `getAudioPlayer()` returns the `<audio>` element the SDK uses to play the
+assistant, or `null` before its track has arrived. Use it for anything the
+setter doesn't cover, such as driving a waveform visualizer.
+
+```javascript
+const player = vapi.getAudioPlayer();
+```
+
+Pair it with the `audio` event when you need the element the moment it exists:
+
+```javascript
+vapi.on('audio', (player) => {
+  // e.g. new AudioContext().createMediaElementSource(player)
+});
+```
+
+If the browser blocks playback, usually its autoplay policy when the call was
+not started from a user gesture, no player is attached and an `error` is
+emitted instead. Listen for it to prompt the user:
+
+```javascript
+vapi.on('error', (e) => {
+  if (e.type === 'audio-start-failed') {
+    // show a "tap to enable audio" affordance
+  }
+});
+```
+
 ## Events
 
 You can listen to the following events:
@@ -130,6 +171,11 @@ vapi.on('volume-level', (volume) => {
   console.log(`Assistant volume level: ${volume}`);
 });
 
+// The <audio> element playing the assistant, as soon as it exists
+vapi.on('audio', (player) => {
+  console.log(`Assistant audio attached at volume ${player.volume}`);
+});
+
 // Function calls and transcripts will be sent via messages
 vapi.on('message', (message) => {
   console.log(message);
diff --git a/__tests__/audioPlayer.test.ts b/__tests__/audioPlayer.test.ts
new file mode 100644
index 000000000..92d351d15
--- /dev/null
+++ b/__tests__/audioPlayer.test.ts
@@ -0,0 +1,432 @@
+import Vapi from "../vapi";
+
+/**
+ * Covers the track-started path that feeds getAudioPlayer/setVolume, which is
+ * where the lifecycle bugs live. The two functions that actually touch the DOM
+ * are substituted, so this runs in the repo's existing node environment with no
+ * extra dependency. What is deliberately not covered here: the DOM calls
+ * themselves, and the fact that volume is applied before play() is invoked.
+ */
+
+type FakePlayer = HTMLAudioElement & { removed: boolean };
+
+const fakePlayer = (participantId: string): FakePlayer => {
+  const player = {
+    volume: 1,
+    dataset: { participantId },
+    removed: false,
+    remove() {
+      this.removed = true;
+    },
+  };
+  return player as unknown as FakePlayer;
+};
+
+const trackStartedEvent = (
+  kind: "audio" | "video" = "audio",
+  sessionId = "bot-1",
+) =>
+  ({
+    action: "track-started",
+    type: kind,
+    callClientId: "test-client",
+    participant: {
+      local: false,
+      user_name: "Vapi Speaker",
+      session_id: sessionId,
+    },
+    track: { kind },
+  }) as unknown as Parameters<Vapi["handleTrackStarted"]>[0];
+
+describe("assistant audio player", () => {
+  let vapi: Vapi;
+  let mockCall: any;
+  let built: FakePlayer[];
+  let destroyed: string[];
+  /** Resolvers for in-flight builds, so tests can settle them out of order. */
+  let releases: Array<(player: FakePlayer) => void>;
+  let autoRelease: boolean;
+  /** Volume argument each build was handed, so the normalizing is observable. */
+  let builtWithVolume: Array<number | null | undefined>;
+
+  beforeEach(() => {
+    built = [];
+    destroyed = [];
+    releases = [];
+    builtWithVolume = [];
+    autoRelease = true;
+
+    mockCall = {
+      setLocalAudio: jest.fn(),
+      localAudio: jest.fn(),
+      sendAppMessage: jest.fn(),
+      destroy: jest.fn().mockResolvedValue(undefined),
+    };
+    vapi = new Vapi("dummy_token");
+    vapi["call"] = mockCall;
+
+    vapi["audioPlayerBuild"] = ((
+      _track: MediaStreamTrack,
+      participantId: string,
+      volume?: number | null,
+    ) => {
+      const player = fakePlayer(participantId);
+      built.push(player);
+      builtWithVolume.push(volume);
+      if (typeof volume === "number") player.volume = volume;
+      if (autoRelease) return Promise.resolve(player);
+      return new Promise<FakePlayer>((resolve) => {
+        releases.push(resolve);
+      });
+    }) as typeof vapi["audioPlayerBuild"];
+
+    vapi["audioPlayerDestroy"] = ((participantId: string) => {
+      destroyed.push(participantId);
+    }) as typeof vapi["audioPlayerDestroy"];
+  });
+
+  it("attaches the player when the assistant's track starts", async () => {
+    await vapi["handleTrackStarted"](trackStartedEvent());
+
+    expect(vapi.getAudioPlayer()).toBe(built[0]);
+    expect(mockCall.sendAppMessage).toHaveBeenCalledWith("playable");
+  });
+
+  it("ignores the local participant's own track", async () => {
+    const event = trackStartedEvent();
+    (event as any).participant.local = true;
+
+    await vapi["handleTrackStarted"](event);
+
+    expect(vapi.getAudioPlayer()).toBeNull();
+    expect(built).toHaveLength(0);
+  });
+
+  it("ignores tracks from participants that are not the assistant", async () => {
+    const event = trackStartedEvent();
+    (event as any).participant.user_name = "Someone Else";
+
+    await vapi["handleTrackStarted"](event);
+
+    expect(vapi.getAudioPlayer()).toBeNull();
+  });
+
+  describe("a consumer listener that throws", () => {
+    // playable is signalled on the same path, one statement after the emit.
+    it("does not stop playable being signalled from the audio emit", async () => {
+      const reported = jest
+        .spyOn(console, "error")
+        .mockImplementation(() => {});
+      vapi.on("audio", () => {
+        throw new Error("consumer bug");
+      });
+
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      expect(mockCall.sendAppMessage).toHaveBeenCalledWith("playable");
+      expect(reported).toHaveBeenCalled();
+      reported.mockRestore();
+    });
+
+    it("does not stop playable being signalled from the video emit", async () => {
+      const reported = jest
+        .spyOn(console, "error")
+        .mockImplementation(() => {});
+      vapi.on("video", () => {
+        throw new Error("consumer bug");
+      });
+
+      await vapi["handleTrackStarted"](trackStartedEvent("video"));
+
+      expect(mockCall.sendAppMessage).toHaveBeenCalledWith("playable");
+      expect(reported).toHaveBeenCalled();
+      reported.mockRestore();
+    });
+  });
+
+  describe("builds that outlive what they were built for", () => {
+    beforeEach(() => {
+      autoRelease = false;
+    });
+
+    it("discards a player built for a call that has ended", async () => {
+      const inFlight = vapi["handleTrackStarted"](trackStartedEvent());
+      await vapi.stop();
+      releases[0](built[0]);
+      await inFlight;
+
+      expect(vapi.getAudioPlayer()).toBeNull();
+      expect(built[0].removed).toBe(true);
+    });
+
+    // Isolates the call-identity check: the call object is swapped without
+    // going through stop(), so the pending-build bookkeeping is untouched and
+    // only the identity comparison can catch this.
+    it("discards a player built for a call that was replaced", async () => {
+      const inFlight = vapi["handleTrackStarted"](trackStartedEvent());
+      vapi["call"] = { ...mockCall, sendAppMessage: jest.fn() };
+      releases[0](built[0]);
+      await inFlight;
+
+      expect(vapi.getAudioPlayer()).toBeNull();
+      expect(built[0].removed).toBe(true);
+    });
+
+    it("discards a player whose participant left while it was building", async () => {
+      const inFlight = vapi["handleTrackStarted"](trackStartedEvent());
+      vapi["detachAudioPlayer"]("bot-1");
+      releases[0](built[0]);
+      await inFlight;
+
+      expect(vapi.getAudioPlayer()).toBeNull();
+      expect(built[0].removed).toBe(true);
+    });
+
+    // Scoped to the departing participant: anyone else leaving must not cost
+    // us the assistant's audio.
+    it("keeps a player when an unrelated participant leaves", async () => {
+      const inFlight = vapi["handleTrackStarted"](trackStartedEvent());
+      vapi["detachAudioPlayer"]("some-other-participant");
+      releases[0](built[0]);
+      await inFlight;
+
+      expect(vapi.getAudioPlayer()).toBe(built[0]);
+      expect(mockCall.sendAppMessage).toHaveBeenCalledWith("playable");
+    });
+
+    // Two builds settle independently, so the second can finish first.
+    it("does not let an earlier build overwrite a later one", async () => {
+      const first = vapi["handleTrackStarted"](trackStartedEvent());
+      const second = vapi["handleTrackStarted"](trackStartedEvent());
+      releases[1](built[1]);
+      releases[0](built[0]);
+      await Promise.all([first, second]);
+
+      expect(vapi.getAudioPlayer()).toBe(built[1]);
+      expect(built[0].removed).toBe(true);
+      expect(built[1].removed).toBe(false);
+    });
+
+    it("forgets builds still in flight when the call is stopped", async () => {
+      const inFlight = vapi["handleTrackStarted"](trackStartedEvent());
+      expect(vapi["pendingAudioBuilds"].size).toBe(1);
+
+      await vapi.stop();
+
+      expect(vapi["pendingAudioBuilds"].size).toBe(0);
+      releases[0](built[0]);
+      await inFlight;
+    });
+  });
+
+  // Renegotiation reuses the participant id, so a superseded element would
+  // still match the selector teardown uses.
+  it("removes the element it supersedes when the track is renegotiated", async () => {
+    await vapi["handleTrackStarted"](trackStartedEvent());
+    await vapi["handleTrackStarted"](trackStartedEvent());
+
+    expect(vapi.getAudioPlayer()).toBe(built[1]);
+    expect(built[0].removed).toBe(true);
+    expect(built[1].removed).toBe(false);
+  });
+
+  describe("when playback fails to start", () => {
+    // A browser autoplay block rejects with a DOMException, whose defining
+    // trait for our purposes is `name`. We do NOT construct a real DOMException
+    // here: jest's node environment supplies it from the parent realm while
+    // Error is the sandbox's own, so `instanceof Error` is false and
+    // serializeError would take a branch it never takes in a browser. An
+    // in-realm Error carrying the same name is the faithful stand-in.
+    const autoplayBlocked = () => {
+      const error = new Error(
+        "play() failed because the user didn't interact with the document first.",
+      );
+      error.name = "NotAllowedError";
+      return error;
+    };
+
+    beforeEach(() => {
+      vapi["audioPlayerBuild"] = (() =>
+        Promise.reject(autoplayBlocked())) as typeof vapi["audioPlayerBuild"];
+    });
+
+    it("reports rather than leaving an unhandled rejection", async () => {
+      const reported = jest
+        .spyOn(console, "error")
+        .mockImplementation(() => {});
+
+      await expect(
+        vapi["handleTrackStarted"](trackStartedEvent()),
+      ).resolves.toBeUndefined();
+
+      expect(reported).toHaveBeenCalled();
+      expect(vapi.getAudioPlayer()).toBeNull();
+      reported.mockRestore();
+    });
+
+    // Autoplay policy is the usual cause and it is recoverable, so consumers
+    // need a signal to prompt for a gesture on.
+    it("emits a serialized error consumers can act on", async () => {
+      jest.spyOn(console, "error").mockImplementation(() => {});
+      const errors: any[] = [];
+      vapi.on("error", (e) => errors.push(e));
+
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      expect(errors).toHaveLength(1);
+      expect(errors[0].type).toBe("audio-start-failed");
+      expect(errors[0].error.name).toBe("NotAllowedError");
+      // Serialized, not the raw exception: consumers forward this to loggers
+      // and workers, and Error properties are not enumerable.
+      expect(errors[0].error).not.toBeInstanceOf(Error);
+      expect(JSON.parse(JSON.stringify(errors[0].error)).name).toBe(
+        "NotAllowedError",
+      );
+      jest.restoreAllMocks();
+    });
+
+    it("does not throw with no error listener attached", async () => {
+      const reported = jest
+        .spyOn(console, "error")
+        .mockImplementation(() => {});
+
+      await expect(
+        vapi["handleTrackStarted"](trackStartedEvent()),
+      ).resolves.toBeUndefined();
+
+      expect(reported).toHaveBeenCalled();
+      reported.mockRestore();
+    });
+
+    it("forgets the failed build", async () => {
+      jest.spyOn(console, "error").mockImplementation(() => {});
+
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      expect(vapi["pendingAudioBuilds"].size).toBe(0);
+      jest.restoreAllMocks();
+    });
+  });
+
+  describe("teardown", () => {
+    it("drops the reference and destroys the element when the assistant leaves", async () => {
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      vapi["detachAudioPlayer"]("bot-1");
+
+      expect(vapi.getAudioPlayer()).toBeNull();
+      expect(destroyed).toContain("bot-1");
+    });
+
+    it("keeps the reference when a different participant leaves", async () => {
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      vapi["detachAudioPlayer"]("someone-else");
+
+      expect(vapi.getAudioPlayer()).toBe(built[0]);
+    });
+
+    it("clears the reference on cleanup, not just on stop", async () => {
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      await vapi["cleanup"]();
+
+      expect(vapi.getAudioPlayer()).toBeNull();
+    });
+  });
+
+  describe("volume", () => {
+    it("applies a volume chosen before the track arrived", async () => {
+      vapi.setVolume(0.2);
+
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      expect(vapi.getAudioPlayer()?.volume).toBe(0.2);
+    });
+
+    it("keeps the chosen volume across calls", async () => {
+      await vapi["handleTrackStarted"](trackStartedEvent());
+      vapi.setVolume(0.1);
+      await vapi.stop();
+
+      vapi["call"] = mockCall;
+      await vapi["handleTrackStarted"](trackStartedEvent("audio", "bot-2"));
+
+      expect(vapi.getAudioPlayer()?.volume).toBe(0.1);
+    });
+
+    it("keeps the chosen volume when the track is replaced mid-call", async () => {
+      await vapi["handleTrackStarted"](trackStartedEvent());
+      vapi.setVolume(0.3);
+
+      await vapi["handleTrackStarted"](trackStartedEvent("audio", "bot-2"));
+
+      expect(vapi.getAudioPlayer()?.volume).toBe(0.3);
+    });
+
+    it("defaults to full volume when the caller never set one", async () => {
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      expect(vapi.getAudioPlayer()?.volume).toBe(1);
+    });
+
+    // The build is handed an already-normalized value, so the element is never
+    // constructed at the wrong volume and then corrected.
+    it("hands the build an already-clamped volume", async () => {
+      vapi["desiredVolume"] = 5;
+
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      expect(builtWithVolume).toEqual([1]);
+    });
+
+    it("hands the build nothing when the remembered volume is non-finite", async () => {
+      vapi["desiredVolume"] = NaN;
+
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      expect(builtWithVolume).toEqual([null]);
+    });
+
+    // The build is handed the volume as it was when the build started. If the
+    // caller changes it while play() is still pending, only the reapply at
+    // attach time catches that.
+    it("applies a volume changed while the player was still building", async () => {
+      autoRelease = false;
+      vapi.setVolume(0.2);
+      const inFlight = vapi["handleTrackStarted"](trackStartedEvent());
+
+      vapi.setVolume(0.7);
+      releases[0](built[0]);
+      await inFlight;
+
+      expect(builtWithVolume).toEqual([0.2]);
+      expect(vapi.getAudioPlayer()?.volume).toBe(0.7);
+    });
+
+    it("hands the build the chosen volume", async () => {
+      vapi.setVolume(0.35);
+
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      expect(builtWithVolume).toEqual([0.35]);
+    });
+
+    // setVolume validates, so these guard the field being written directly.
+    it("ignores a non-finite remembered volume", async () => {
+      vapi["desiredVolume"] = NaN;
+
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      expect(vapi.getAudioPlayer()?.volume).toBe(1);
+    });
+
+    it("clamps an out-of-range remembered volume", async () => {
+      vapi["desiredVolume"] = 5;
+
+      await vapi["handleTrackStarted"](trackStartedEvent());
+
+      expect(vapi.getAudioPlayer()?.volume).toBe(1);
+    });
+  });
+});
diff --git a/__tests__/vapi.test.ts b/__tests__/vapi.test.ts
index 63822586a..143b3b470 100644
--- a/__tests__/vapi.test.ts
+++ b/__tests__/vapi.test.ts
@@ -9,6 +9,7 @@ describe("Vapi", () => {
     mockCall = {
       setLocalAudio: jest.fn(),
       localAudio: jest.fn(),
+      destroy: jest.fn().mockResolvedValue(undefined),
     };
     // Initialize Vapi instance and inject the mock
     vapi = new Vapi("dummy_token");
@@ -53,4 +54,109 @@ describe("Vapi", () => {
       expect(res).toBe(false);
     });
   });
+
+  describe("audio player access", () => {
+    // The real element is built by buildAudioPlayer, which needs a DOM. These
+    // tests cover everything downstream of that, which is where the reference
+    // is kept, handed out, and dropped.
+    const fakePlayer = () => ({ volume: 1 }) as HTMLAudioElement;
+
+    it("should return null before any audio track has arrived", () => {
+      expect(vapi.getAudioPlayer()).toBeNull();
+    });
+
+    it("should return the player once an audio track has arrived", () => {
+      const player = fakePlayer();
+      vapi["attachAudioPlayer"](player);
+      expect(vapi.getAudioPlayer()).toBe(player);
+    });
+
+    it("should emit the player on the audio event", () => {
+      const player = fakePlayer();
+      const listener = jest.fn();
+      vapi.on("audio", listener);
+
+      vapi["attachAudioPlayer"](player);
+
+      expect(listener).toHaveBeenCalledWith(player);
+    });
+
+    it("should store the player before emitting, so listeners can use it", () => {
+      const player = fakePlayer();
+      let seenDuringEvent: HTMLAudioElement | null = null;
+      vapi.on("audio", () => {
+        seenDuringEvent = vapi.getAudioPlayer();
+      });
+
+      vapi["attachAudioPlayer"](player);
+
+      expect(seenDuringEvent).toBe(player);
+    });
+  });
+
+  describe("setVolume", () => {
+    it("should set the volume on the attached player", () => {
+      const player = { volume: 1 } as HTMLAudioElement;
+      vapi["attachAudioPlayer"](player);
+
+      vapi.setVolume(0.25);
+
+      expect(player.volume).toBe(0.25);
+    });
+
+    it("should do nothing when no audio track has arrived", () => {
+      expect(() => vapi.setVolume(0.5)).not.toThrow();
+    });
+
+    // The DOM throws IndexSizeError outside 0-1, so clamp rather than hand
+    // callers a browser exception from a setter.
+    it("should clamp values above 1", () => {
+      const player = { volume: 0.5 } as HTMLAudioElement;
+      vapi["attachAudioPlayer"](player);
+
+      vapi.setVolume(1.5);
+
+      expect(player.volume).toBe(1);
+    });
+
+    it("should clamp values below 0", () => {
+      const player = { volume: 0.5 } as HTMLAudioElement;
+      vapi["attachAudioPlayer"](player);
+
+      vapi.setVolume(-2);
+
+      expect(player.volume).toBe(0);
+    });
+
+    // Clamping alone lets NaN through, and the DOM rejects a non-finite volume
+    // with a TypeError. Untyped callers reach this via parseFloat("") and friends.
+    it("should ignore NaN rather than writing it to the player", () => {
+      const player = { volume: 0.5 } as HTMLAudioElement;
+      vapi["attachAudioPlayer"](player);
+
+      vapi.setVolume(NaN);
+
+      expect(player.volume).toBe(0.5);
+    });
+
+    it("should ignore undefined from untyped callers", () => {
+      const player = { volume: 0.5 } as HTMLAudioElement;
+      vapi["attachAudioPlayer"](player);
+
+      vapi.setVolume(undefined as unknown as number);
+
+      expect(player.volume).toBe(0.5);
+    });
+
+    it("should not write to the player from a previous call after stop", async () => {
+      const player = { volume: 1 } as HTMLAudioElement;
+      vapi["attachAudioPlayer"](player);
+
+      await vapi.stop();
+      vapi.setVolume(0.25);
+
+      expect(player.volume).toBe(1);
+      expect(vapi.getAudioPlayer()).toBeNull();
+    });
+  });
 });
diff --git a/vapi.ts b/vapi.ts
index f34de5b5b..230b6a599 100644
--- a/vapi.ts
+++ b/vapi.ts
@@ -8,6 +8,7 @@ import DailyIframe, {
   DailyEventObjectLocalAudioLevel,
   DailyEventObjectNoPayload,
   DailyEventObjectParticipant,
+  DailyEventObjectTrack,
   DailyEventObjectRecordingError,
   DailyEventObjectRecordingStarted,
   DailyEventObjectRecordingStopped,
@@ -73,6 +74,7 @@ type VapiEventNames =
   | 'speech-end'
   | 'message'
   | 'video'
+  | 'audio'
   | 'error'
   | 'camera-error'
   | 'network-quality-change'
@@ -186,6 +188,7 @@ type VapiEventListeners = {
   'speech-start': () => void;
   'speech-end': () => void;
   video: (track: MediaStreamTrack) => void;
+  audio: (player: HTMLAudioElement) => void;
   message: (message: any) => void;
   error: (error: any) => void;
   'camera-error': (error: any) => void;
@@ -254,11 +257,25 @@ async function startAudioPlayer(
 async function buildAudioPlayer(
   track: MediaStreamTrack,
   participantId: string,
+  volume?: number | null,
 ) {
   const player = document.createElement('audio');
   player.dataset.participantId = participantId;
+  // Set before play() rather than after the element is handed back, so a track
+  // that is already flowing never gets a window at full volume.
+  // Already bounded by desiredVolumeResolve, so assigned as given.
+  if (typeof volume === 'number') {
+    player.volume = volume;
+  }
   document.body.appendChild(player);
-  await startAudioPlayer(player, track);
+  try {
+    await startAudioPlayer(player, track);
+  } catch (error) {
+    // The element is appended before playback is attempted, so a failure here
+    // would otherwise strand it in the page for the rest of the session.
+    player.remove();
+    throw error;
+  }
   return player;
 }
 
@@ -322,6 +339,17 @@ class VapiEventEmitter extends EventEmitter {
 export default class Vapi extends VapiEventEmitter {
   private started: boolean = false;
   private call: DailyCall | null = null;
+  private audioPlayer: HTMLAudioElement | null = null;
+  // Outlives any single player, so the caller's choice survives teardown and
+  // gets reapplied to whatever element the next track builds.
+  private desiredVolume: number | null = null;
+  // Builds are identified individually rather than by a single counter: a
+  // player takes the whole of media startup to build, so several can be in
+  // flight, they can finish out of order, and a teardown must invalidate only
+  // the builds for the participant that actually left.
+  private audioBuildSequence = 0;
+  private pendingAudioBuilds = new Map<number, string>();
+  private attachedAudioBuild = 0;
   private speakingTimeout: NodeJS.Timeout | null = null;
   private dailyCallConfig: DailyAdvancedConfig = {};
   private dailyCallObject: DailyFactoryOptions = {};
@@ -351,6 +379,12 @@ export default class Vapi extends VapiEventEmitter {
       await this.call.destroy();
       this.call = null;
     }
+    // Dropped with the call: the element it points at is torn down, and holding
+    // it would let setVolume write to a dead player on the next call.
+    this.audioPlayer = null;
+    // Builds that never settle would otherwise keep their entry for the life
+    // of the page. Call identity already rejects them, so this only bounds it.
+    this.pendingAudioBuilds.clear();
     this.speakingTimeout = null;
   }
 
@@ -578,24 +612,7 @@ export default class Vapi extends VapiEventEmitter {
         if (event) this.emit('recording-upload-completed', event);
       });
 
-      this.call.on('track-started', async (e) => {
-        if (!e || !e.participant) {
-          return;
-        }
-        if (e.participant?.local) {
-          return;
-        }
-        if (e.participant?.user_name !== 'Vapi Speaker') {
-          return;
-        }
-        if (e.track.kind === 'video') {
-          this.emit('video', e.track);
-        }
-        if (e.track.kind === 'audio') {
-          await buildAudioPlayer(e.track, e.participant.session_id);
-        }
-        this.call?.sendAppMessage('playable');
-      });
+      this.call.on('track-started', (e) => this.handleTrackStarted(e));
 
       this.call.on('participant-joined', (e) => {
         if (!e || !this.call) return;
@@ -618,7 +635,7 @@ export default class Vapi extends VapiEventEmitter {
         if (!e) {
           return;
         }
-        destroyAudioPlayer(e.participant.session_id);
+        this.detachAudioPlayer(e.participant.session_id);
       });
 
       // Stage 3: Mobile device handling and permissions
@@ -990,6 +1007,12 @@ export default class Vapi extends VapiEventEmitter {
       await this.call.destroy();
       this.call = null;
     }
+    // Dropped with the call: the element it points at is torn down, and holding
+    // it would let setVolume write to a dead player on the next call.
+    this.audioPlayer = null;
+    // Builds that never settle would otherwise keep their entry for the life
+    // of the page. Call identity already rejects them, so this only bounds it.
+    this.pendingAudioBuilds.clear();
     this.speakingTimeout = null;
   }
 
@@ -1002,6 +1025,208 @@ export default class Vapi extends VapiEventEmitter {
     this.call?.sendAppMessage(JSON.stringify(message));
   }
 
+  /**
+   * The two seams where this class touches the DOM. Kept as thin indirections
+   * so the lifecycle logic around them, which is where the bugs live, can be
+   * exercised without a browser environment.
+   */
+  private audioPlayerBuild(
+    track: MediaStreamTrack,
+    participantId: string,
+    volume?: number | null,
+  ): Promise<HTMLAudioElement> {
+    return buildAudioPlayer(track, participantId, volume);
+  }
+
+  private audioPlayerDestroy(participantId: string): void {
+    destroyAudioPlayer(participantId);
+  }
+
+  /**
+   * The remembered volume, bounded and sanity-checked, or null if there is
+   * nothing valid to apply.
+   *
+   * setVolume already validates, so this only matters if the field is reached
+   * another way. It lives here rather than at each write so the two callers
+   * cannot disagree, and so the bounding is observable in tests: the DOM
+   * rejects a non-finite or out-of-range volume, and that throw would land
+   * mid-attach and stall the call.
+   */
+  private desiredVolumeResolve(): number | null {
+    if (this.desiredVolume === null || !Number.isFinite(this.desiredVolume)) {
+      return null;
+    }
+    return Math.min(1, Math.max(0, this.desiredVolume));
+  }
+
+  /**
+   * Builds the assistant's audio player and hands it to consumers.
+   *
+   * Shared by the initial and reconnect paths so the two cannot drift.
+   */
+  private async handleTrackStarted(e?: DailyEventObjectTrack) {
+    if (!e || !e.participant) {
+      return;
+    }
+    if (e.participant?.local) {
+      return;
+    }
+    if (e.participant?.user_name !== 'Vapi Speaker') {
+      return;
+    }
+    if (e.track.kind === 'video') {
+      this.emitToConsumer('video', e.track);
+    }
+    if (e.track.kind === 'audio') {
+      // buildAudioPlayer awaits play(), which pends for the whole of media
+      // startup, so the call can end or the participant can leave underneath
+      // us. Anything built for a call we have since left, or for a participant
+      // that has since gone, is discarded rather than adopted.
+      const call = this.call;
+      const build = ++this.audioBuildSequence;
+      this.pendingAudioBuilds.set(build, e.participant.session_id);
+
+      let player: HTMLAudioElement;
+      try {
+        player = await this.audioPlayerBuild(
+          e.track,
+          e.participant.session_id,
+          this.desiredVolumeResolve(),
+        );
+      } catch (error) {
+        // Autoplay policy and a missing user gesture both land here. Reported
+        // rather than left as an unhandled rejection, and the element the
+        // build already appended is cleaned up by buildAudioPlayer.
+        this.pendingAudioBuilds.delete(build);
+        console.error('[vapi] could not start assistant audio', error);
+        // Autoplay policy is the usual cause and it is recoverable, so give
+        // consumers a signal they can prompt for a user gesture on. Safe with
+        // no listener attached: emitToConsumer catches EventEmitter's
+        // unlistened-'error' throw.
+        this.emitToConsumer('error', {
+          type: 'audio-start-failed',
+          error: serializeError(error),
+        });
+        return;
+      }
+
+      // Still wanted only if the call is the same one, this build was not
+      // invalidated by its participant leaving, and no later build has already
+      // attached. Builds finish in whatever order play() resolves.
+      const stillPending = this.pendingAudioBuilds.delete(build);
+      if (
+        !call ||
+        this.call !== call ||
+        !stillPending ||
+        build < this.attachedAudioBuild
+      ) {
+        player.remove();
+        return;
+      }
+      this.attachedAudioBuild = build;
+      this.attachAudioPlayer(player);
+    }
+    this.call?.sendAppMessage('playable');
+  }
+
+  /**
+   * Applies the caller's volume, keeps the player, then announces it.
+   *
+   * Volume is applied before the element is handed out so a fresh player never
+   * plays a moment at full volume after the caller has turned it down.
+   * Assigning before emitting means a listener that calls setVolume or
+   * getAudioPlayer during the event sees it, since emit is synchronous.
+   */
+  private attachAudioPlayer(player: HTMLAudioElement) {
+    // Renegotiation reuses the participant id, so a superseded element would
+    // still match the selector teardown uses and could be removed in its
+    // place, leaving the live one behind.
+    if (this.audioPlayer && this.audioPlayer !== player) {
+      this.audioPlayer.remove();
+    }
+    // Reapplied to catch a volume changed while the player was still building.
+    const volume = this.desiredVolumeResolve();
+    if (volume !== null) {
+      player.volume = volume;
+    }
+    this.audioPlayer = player;
+    this.emitToConsumer('audio', player);
+  }
+
+  /**
+   * Emits to consumers without letting a listener that throws take down the
+   * caller. track-started still has to signal that playback is ready, and a
+   * thrown listener there would stall the call.
+   *
+   * Not routed to the `error` event: EventEmitter throws when `error` is
+   * emitted with no listener, which would reintroduce the same failure.
+   */
+  private emitToConsumer<E extends VapiEventNames>(
+    event: E,
+    ...args: Parameters<VapiEventListeners[E]>
+  ) {
+    try {
+      this.emit(event, ...args);
+    } catch (error) {
+      console.error(`[vapi] ${event} event listener threw`, error);
+    }
+  }
+
+  /**
+   * Tears down the player for a departing participant, dropping our reference
+   * to it first so nothing hands out an element that is no longer in the page.
+   */
+  private detachAudioPlayer(participantId: string) {
+    if (this.audioPlayer?.dataset.participantId === participantId) {
+      this.audioPlayer = null;
+    }
+    // Invalidates players still being built for this participant, which the
+    // call check cannot see because the call itself has not changed. Scoped to
+    // the departing participant so an unrelated leave cannot cost us the
+    // assistant's audio.
+    for (const [build, id] of this.pendingAudioBuilds) {
+      if (id === participantId) {
+        this.pendingAudioBuilds.delete(build);
+      }
+    }
+    this.audioPlayerDestroy(participantId);
+  }
+
+  /**
+   * The <audio> element playing the assistant, or null before its track has
+   * arrived. Pair with the `audio` event when you need it the moment it exists.
+   */
+  public getAudioPlayer(): HTMLAudioElement | null {
+    return this.audioPlayer;
+  }
+
+  /**
+   * Sets assistant playback volume, 0 to 1.
+   *
+   * The setting is remembered, so it can be applied before the assistant's
+   * audio track has arrived and it survives across calls and mid-call track
+   * replacement. Callers do not have to race the start of the call.
+   *
+   * Values outside 0 to 1 are clamped and non-finite values are ignored, since
+   * the DOM rejects both rather than saturating.
+   *
+   * Only volume set through this method is remembered. Writing `volume`
+   * directly on the element from getAudioPlayer() or the `audio` event applies
+   * to that element alone, and is overwritten the next time one is attached.
+   *
+   * This is playback only. It does not change what the assistant hears, and it
+   * does not affect the levels reported by the `volume-level` event.
+   */
+  public setVolume(volume: number) {
+    if (!Number.isFinite(volume)) {
+      return;
+    }
+    this.desiredVolume = Math.min(1, Math.max(0, volume));
+    if (this.audioPlayer) {
+      this.audioPlayer.volume = this.desiredVolume;
+    }
+  }
+
   public setMuted(mute: boolean) {
     safeSetLocalAudio(this.call, !mute);
   }
@@ -1283,24 +1508,7 @@ export default class Vapi extends VapiEventEmitter {
         if (event) this.emit('recording-upload-completed', event);
       });
 
-      this.call.on('track-started', async (e) => {
-        if (!e || !e.participant) {
-          return;
-        }
-        if (e.participant?.local) {
-          return;
-        }
-        if (e.participant?.user_name !== 'Vapi Speaker') {
-          return;
-        }
-        if (e.track.kind === 'video') {
-          this.emit('video', e.track);
-        }
-        if (e.track.kind === 'audio') {
-          await buildAudioPlayer(e.track, e.participant.session_id);
-        }
-        this.call?.sendAppMessage('playable');
-      });
+      this.call.on('track-started', (e) => this.handleTrackStarted(e));
 
       this.call.on('participant-joined', (e) => {
         if (!e || !this.call) return;
@@ -1323,7 +1531,7 @@ export default class Vapi extends VapiEventEmitter {
         if (!e) {
           return;
         }
-        destroyAudioPlayer(e.participant.session_id);
+        this.detachAudioPlayer(e.participant.session_id);
       });
 
       this.call.on('remote-participants-audio-level', (e) => {

From d10a1282d1903b0b3fee1f1c99d9d1a09c034186 Mon Sep 17 00:00:00 2001
From: veltsonbastien <bastienveltson@outlook.com>
Date: Tue, 11 Aug 2026 15:52:03 -0700
Subject: [PATCH 2/2] style: trim comments to the ones that carry non-obvious
 rationale

The change raised comment density in vapi.ts from 8% to 12% and used
multi-line paragraph blocks where the file's own style is short single lines.

Removed comments that restate the code (teardown nulling fields, the guard
condition in handleTrackStarted, method docs that repeat the method name) and
comments duplicated between production and tests. Compressed the rest, keeping
only what a reader cannot get from the code: why builds are tracked
individually, why the emit is guarded and not routed to the error event, why
volume is set before play(), why the DOMException fixture is not a real
DOMException.

vapi.ts is now 10%, and the test file 6%, against main's 8%.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 __tests__/audioPlayer.test.ts |  16 ++----
 vapi.ts                       | 100 ++++++++++------------------------
 2 files changed, 32 insertions(+), 84 deletions(-)

diff --git a/__tests__/audioPlayer.test.ts b/__tests__/audioPlayer.test.ts
index 92d351d15..acf2b60a0 100644
--- a/__tests__/audioPlayer.test.ts
+++ b/__tests__/audioPlayer.test.ts
@@ -219,8 +219,6 @@ describe("assistant audio player", () => {
     });
   });
 
-  // Renegotiation reuses the participant id, so a superseded element would
-  // still match the selector teardown uses.
   it("removes the element it supersedes when the track is renegotiated", async () => {
     await vapi["handleTrackStarted"](trackStartedEvent());
     await vapi["handleTrackStarted"](trackStartedEvent());
@@ -231,12 +229,10 @@ describe("assistant audio player", () => {
   });
 
   describe("when playback fails to start", () => {
-    // A browser autoplay block rejects with a DOMException, whose defining
-    // trait for our purposes is `name`. We do NOT construct a real DOMException
-    // here: jest's node environment supplies it from the parent realm while
-    // Error is the sandbox's own, so `instanceof Error` is false and
-    // serializeError would take a branch it never takes in a browser. An
-    // in-realm Error carrying the same name is the faithful stand-in.
+    // Not a real DOMException: jest's node environment supplies it from the
+    // parent realm, so `instanceof Error` is false and serializeError would
+    // take a branch it never takes in a browser. An in-realm Error with the
+    // same `name` is the faithful stand-in.
     const autoplayBlocked = () => {
       const error = new Error(
         "play() failed because the user didn't interact with the document first.",
@@ -264,8 +260,6 @@ describe("assistant audio player", () => {
       reported.mockRestore();
     });
 
-    // Autoplay policy is the usual cause and it is recoverable, so consumers
-    // need a signal to prompt for a gesture on.
     it("emits a serialized error consumers can act on", async () => {
       jest.spyOn(console, "error").mockImplementation(() => {});
       const errors: any[] = [];
@@ -370,8 +364,6 @@ describe("assistant audio player", () => {
       expect(vapi.getAudioPlayer()?.volume).toBe(1);
     });
 
-    // The build is handed an already-normalized value, so the element is never
-    // constructed at the wrong volume and then corrected.
     it("hands the build an already-clamped volume", async () => {
       vapi["desiredVolume"] = 5;
 
diff --git a/vapi.ts b/vapi.ts
index 230b6a599..eac3c5a62 100644
--- a/vapi.ts
+++ b/vapi.ts
@@ -261,9 +261,7 @@ async function buildAudioPlayer(
 ) {
   const player = document.createElement('audio');
   player.dataset.participantId = participantId;
-  // Set before play() rather than after the element is handed back, so a track
-  // that is already flowing never gets a window at full volume.
-  // Already bounded by desiredVolumeResolve, so assigned as given.
+  // Before play(), so an already-flowing track never plays at full volume first.
   if (typeof volume === 'number') {
     player.volume = volume;
   }
@@ -271,8 +269,7 @@ async function buildAudioPlayer(
   try {
     await startAudioPlayer(player, track);
   } catch (error) {
-    // The element is appended before playback is attempted, so a failure here
-    // would otherwise strand it in the page for the rest of the session.
+    // Appended before playback was attempted, so a failure would strand it.
     player.remove();
     throw error;
   }
@@ -340,13 +337,11 @@ export default class Vapi extends VapiEventEmitter {
   private started: boolean = false;
   private call: DailyCall | null = null;
   private audioPlayer: HTMLAudioElement | null = null;
-  // Outlives any single player, so the caller's choice survives teardown and
-  // gets reapplied to whatever element the next track builds.
+  // Survives teardown so the caller's choice persists across calls.
   private desiredVolume: number | null = null;
-  // Builds are identified individually rather than by a single counter: a
-  // player takes the whole of media startup to build, so several can be in
-  // flight, they can finish out of order, and a teardown must invalidate only
-  // the builds for the participant that actually left.
+  // Builds are tracked individually, not by one counter: several can be in
+  // flight, they finish out of order, and a teardown must invalidate only the
+  // builds belonging to the participant that left.
   private audioBuildSequence = 0;
   private pendingAudioBuilds = new Map<number, string>();
   private attachedAudioBuild = 0;
@@ -379,11 +374,7 @@ export default class Vapi extends VapiEventEmitter {
       await this.call.destroy();
       this.call = null;
     }
-    // Dropped with the call: the element it points at is torn down, and holding
-    // it would let setVolume write to a dead player on the next call.
     this.audioPlayer = null;
-    // Builds that never settle would otherwise keep their entry for the life
-    // of the page. Call identity already rejects them, so this only bounds it.
     this.pendingAudioBuilds.clear();
     this.speakingTimeout = null;
   }
@@ -1007,11 +998,7 @@ export default class Vapi extends VapiEventEmitter {
       await this.call.destroy();
       this.call = null;
     }
-    // Dropped with the call: the element it points at is torn down, and holding
-    // it would let setVolume write to a dead player on the next call.
     this.audioPlayer = null;
-    // Builds that never settle would otherwise keep their entry for the life
-    // of the page. Call identity already rejects them, so this only bounds it.
     this.pendingAudioBuilds.clear();
     this.speakingTimeout = null;
   }
@@ -1026,9 +1013,8 @@ export default class Vapi extends VapiEventEmitter {
   }
 
   /**
-   * The two seams where this class touches the DOM. Kept as thin indirections
-   * so the lifecycle logic around them, which is where the bugs live, can be
-   * exercised without a browser environment.
+   * The two places this class touches the DOM, behind indirections so the
+   * lifecycle logic around them is testable without a browser.
    */
   private audioPlayerBuild(
     track: MediaStreamTrack,
@@ -1043,14 +1029,9 @@ export default class Vapi extends VapiEventEmitter {
   }
 
   /**
-   * The remembered volume, bounded and sanity-checked, or null if there is
-   * nothing valid to apply.
-   *
-   * setVolume already validates, so this only matters if the field is reached
-   * another way. It lives here rather than at each write so the two callers
-   * cannot disagree, and so the bounding is observable in tests: the DOM
-   * rejects a non-finite or out-of-range volume, and that throw would land
-   * mid-attach and stall the call.
+   * The remembered volume, bounded, or null if there is nothing to apply.
+   * Shared by both callers so they cannot disagree: the DOM throws on a
+   * non-finite or out-of-range volume, and that throw would stall the call.
    */
   private desiredVolumeResolve(): number | null {
     if (this.desiredVolume === null || !Number.isFinite(this.desiredVolume)) {
@@ -1059,11 +1040,7 @@ export default class Vapi extends VapiEventEmitter {
     return Math.min(1, Math.max(0, this.desiredVolume));
   }
 
-  /**
-   * Builds the assistant's audio player and hands it to consumers.
-   *
-   * Shared by the initial and reconnect paths so the two cannot drift.
-   */
+  /** Shared by the initial and reconnect paths so the two cannot drift. */
   private async handleTrackStarted(e?: DailyEventObjectTrack) {
     if (!e || !e.participant) {
       return;
@@ -1078,10 +1055,8 @@ export default class Vapi extends VapiEventEmitter {
       this.emitToConsumer('video', e.track);
     }
     if (e.track.kind === 'audio') {
-      // buildAudioPlayer awaits play(), which pends for the whole of media
-      // startup, so the call can end or the participant can leave underneath
-      // us. Anything built for a call we have since left, or for a participant
-      // that has since gone, is discarded rather than adopted.
+      // play() pends for the whole of media startup, so the call can end or
+      // the participant can leave while the player is still being built.
       const call = this.call;
       const build = ++this.audioBuildSequence;
       this.pendingAudioBuilds.set(build, e.participant.session_id);
@@ -1094,15 +1069,11 @@ export default class Vapi extends VapiEventEmitter {
           this.desiredVolumeResolve(),
         );
       } catch (error) {
-        // Autoplay policy and a missing user gesture both land here. Reported
-        // rather than left as an unhandled rejection, and the element the
-        // build already appended is cleaned up by buildAudioPlayer.
+        // Usually autoplay policy, which is recoverable, so consumers get a
+        // signal to prompt for a gesture. Safe with no 'error' listener:
+        // emitToConsumer catches EventEmitter's unlistened-'error' throw.
         this.pendingAudioBuilds.delete(build);
         console.error('[vapi] could not start assistant audio', error);
-        // Autoplay policy is the usual cause and it is recoverable, so give
-        // consumers a signal they can prompt for a user gesture on. Safe with
-        // no listener attached: emitToConsumer catches EventEmitter's
-        // unlistened-'error' throw.
         this.emitToConsumer('error', {
           type: 'audio-start-failed',
           error: serializeError(error),
@@ -1110,9 +1081,6 @@ export default class Vapi extends VapiEventEmitter {
         return;
       }
 
-      // Still wanted only if the call is the same one, this build was not
-      // invalidated by its participant leaving, and no later build has already
-      // attached. Builds finish in whatever order play() resolves.
       const stillPending = this.pendingAudioBuilds.delete(build);
       if (
         !call ||
@@ -1130,21 +1098,16 @@ export default class Vapi extends VapiEventEmitter {
   }
 
   /**
-   * Applies the caller's volume, keeps the player, then announces it.
-   *
-   * Volume is applied before the element is handed out so a fresh player never
-   * plays a moment at full volume after the caller has turned it down.
-   * Assigning before emitting means a listener that calls setVolume or
-   * getAudioPlayer during the event sees it, since emit is synchronous.
+   * Assigns before emitting, since emit is synchronous and a listener may call
+   * getAudioPlayer or setVolume during the event.
    */
   private attachAudioPlayer(player: HTMLAudioElement) {
     // Renegotiation reuses the participant id, so a superseded element would
-    // still match the selector teardown uses and could be removed in its
-    // place, leaving the live one behind.
+    // still match the selector teardown uses and be removed in its place.
     if (this.audioPlayer && this.audioPlayer !== player) {
       this.audioPlayer.remove();
     }
-    // Reapplied to catch a volume changed while the player was still building.
+    // Reapplied in case the volume changed while the player was building.
     const volume = this.desiredVolumeResolve();
     if (volume !== null) {
       player.volume = volume;
@@ -1154,12 +1117,9 @@ export default class Vapi extends VapiEventEmitter {
   }
 
   /**
-   * Emits to consumers without letting a listener that throws take down the
-   * caller. track-started still has to signal that playback is ready, and a
-   * thrown listener there would stall the call.
-   *
-   * Not routed to the `error` event: EventEmitter throws when `error` is
-   * emitted with no listener, which would reintroduce the same failure.
+   * A listener that throws must not take down the caller: track-started still
+   * has to signal that playback is ready. Not routed to the `error` event,
+   * which EventEmitter throws on when nothing is listening.
    */
   private emitToConsumer<E extends VapiEventNames>(
     event: E,
@@ -1172,18 +1132,14 @@ export default class Vapi extends VapiEventEmitter {
     }
   }
 
-  /**
-   * Tears down the player for a departing participant, dropping our reference
-   * to it first so nothing hands out an element that is no longer in the page.
-   */
+  /** Drops the reference before removing, so nothing hands out a detached element. */
   private detachAudioPlayer(participantId: string) {
     if (this.audioPlayer?.dataset.participantId === participantId) {
       this.audioPlayer = null;
     }
-    // Invalidates players still being built for this participant, which the
-    // call check cannot see because the call itself has not changed. Scoped to
-    // the departing participant so an unrelated leave cannot cost us the
-    // assistant's audio.
+    // Scoped to this participant: the call check cannot catch these, since the
+    // call itself has not changed, and an unrelated leave must not invalidate
+    // the assistant's build.
     for (const [build, id] of this.pendingAudioBuilds) {
       if (id === participantId) {
         this.pendingAudioBuilds.delete(build);