feat(timer): playing sound on time end

2026-08-31 11:59:10 +00:00 · 2024-10-07 20:31:04 +02:00
parent 265b167600
commit 4c08ca2908
10 changed files with 216 additions and 0 deletions
@@ -0,0 +1,99 @@
+import { TimerPhase } from 'ontime-types';
+import { useEffect, useRef, useState } from 'react';
+
+import { endSoundSources, type EndSound } from './timer.sound';
+import { shouldPlayEndSound } from './timer.utils';
+
+/**
+ * Plays a sound when the timer reaches its end
+ *
+ * Browsers reject playback until the document has been interacted with, and that permission
+ * is lost on every page load. Since a timer screen is typically left unattended, we prime the
+ * audio element on the first interaction and let the view prompt for one if it never comes.
+ * Safari grants the permission per element, so priming has to call play() on this element from
+ * inside the event handler, it is not enough to know that an interaction happened.
+ */
+export function useTimerSound(phase: TimerPhase, sound: EndSound): boolean {
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const previousPhaseRef = useRef<TimerPhase | null>(null);
+  const [isArmed, setIsArmed] = useState(false);
+
+  const enabled = sound !== 'none';
+
+  // Create and clean up the audio element; changing sounds requires re-arming it in Safari.
+  useEffect(() => {
+    setIsArmed(false);
+
+    if (sound === 'none') {
+      return;
+    }
+
+    const audio = new Audio(endSoundSources[sound]);
+    audioRef.current = audio;
+
+    return () => {
+      audio.pause();
+      audioRef.current = null;
+    };
+  }, [sound]);
+
+  // Listen for user interaction until muted playback succeeds and arms the selected audio element.
+  useEffect(() => {
+    if (!enabled || isArmed) {
+      return;
+    }
+
+    const controller = new AbortController();
+    const prime = () => {
+      const audio = audioRef.current;
+      if (!audio) {
+        return;
+      }
+
+      const wasMuted = audio.muted;
+      audio.muted = true;
+      audio
+        .play()
+        .then(() => {
+          if (audioRef.current !== audio) {
+            return;
+          }
+          audio.pause();
+          audio.currentTime = 0;
+          setIsArmed(true);
+        })
+        .catch(() => {
+          // playback is still blocked, a later interaction will try again
+        })
+        .finally(() => {
+          audio.muted = wasMuted;
+        });
+    };
+
+    document.addEventListener('pointerdown', prime, { capture: true, signal: controller.signal });
+    document.addEventListener('keydown', prime, { capture: true, signal: controller.signal });
+
+    return () => {
+      controller.abort();
+    };
+  }, [enabled, isArmed]);
+
+  // Track phase transitions and play only when a running timer enters overtime.
+  useEffect(() => {
+    const previousPhase = previousPhaseRef.current;
+    previousPhaseRef.current = phase;
+
+    if (!enabled || !shouldPlayEndSound(previousPhase, phase)) {
+      return;
+    }
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    audio.currentTime = 0;
+    audio.play().catch(() => {
+      // the screen has not been interacted with, the view shows a prompt for it
+    });
+  }, [enabled, phase]);
+
+  return enabled && !isArmed;
+}