Audio in SPFx and Teams: playback may be refused — the feature must not stop

What was measured (28 Oct 2026)

• The Content-Security-Policy header of a SharePoint Online page contained only script-src and worker-src — no media-src and no default-src. An <audio> / new Audio(url) pointing to MP3 files on a separate CDN domain played without any tenant change.
• Playback started from a click (a ▶ button) worked in Chrome on SharePoint and inside the Teams client.

Microsoft can tighten the CSP at any time, and autoplay policies differ between browsers and webviews — which is why the fallback matters more than the measurement.

Pattern

type Result = 'ended' | 'silent' | 'stopped';

function playStep(url: string | undefined, text: string, muted: boolean): Promise<Result> {
  const silentMs = Math.max(2500, text.length * 60);           // reading-speed fallback
  const silent = () => new Promise<Result>(r => setTimeout(() => r('silent'), silentMs));
  if (!url || muted) return silent();

  const audio = new Audio(url);
  return new Promise<Result>(resolve => {
    audio.onended = () => resolve('ended');
    audio.onerror = () => silent().then(resolve);               // 404, decode error, CSP block
    audio.play().catch(() => {                                   // NotAllowedError (autoplay), etc.
      markBlocked();                                             // show a "no sound" chip once
      silent().then(resolve);
    });
  });
}

• Call the first play() inside the click handler of the button that starts the narration. In our test (Chrome on SharePoint, Teams) the following steps then played without another click — but keep the fallback for every step, not just the first.
• Remember the user's mute choice per browser (localStorage, wrapped in try/catch).
• Keep a stop/pause control that cancels both the audio and the silent timer, so a superseded step never advances the flow.
• Pre-generate audio files and host them as static assets; no speech service is called at runtime, so there is no key in the bundle and nothing to rate-limit.