Add a spoken countdown between frames

A 🔊 toggle on the home screen counts you into each frame - "five, four,
three, two, one" - plus start and finish announcements. Useful when you're in
front of the camera rather than at the laptop. Uses the Web Speech API, so
it's local and needs no configuration.

The narrator runs off the intervalometer's state updates rather than a timer
of its own, so it can't drift away from what the sequence is doing; each
second is spoken at most once even though state arrives ~5x/sec.

The count is capped at one second under the interval, so a 3s interval says
"two, one" instead of talking over the previous frame, and a 1s interval stays
silent. A start delay isn't clamped, since that gap is whatever you set.

Countdown length, voice choice and frame-number announcements live in the
settings drawer; only the toggle is on the home screen.

Also:
- The toggle sits in the status card rather than the button row: three buttons
  don't fit a 400px column, and it wrapped onto its own flex line where it
  stretched to the wrong height.
- tsconfig excludes dist/, which build-dist.sh fills with copies of these same
  files and which otherwise gets type-checked twice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QK7PKpRVoy69Fpa32R8abb

examples/preact/home.js

@@ -89,9 +89,14 @@ function sequenceWarnings(prefs, config, hasFolder) {
 }
 
 /**
- * @param {{ state: SequenceState, prefs: Prefs }} props
+ * @param {{
+ *   state: SequenceState,
+ *   prefs: Prefs,
+ *   voiceSupported: boolean,
+ *   onToggleVoice: () => void
+ * }} props
  */
-function SequenceStatus({ state, prefs }) {
+function SequenceStatus({ state, prefs, voiceSupported, onToggleVoice }) {
   let { phase, taken, total } = state;
   let headline;
   let detail;
@@ -135,8 +140,31 @@ function SequenceStatus({ state, prefs }) {
   return h(
     'div',
     { class: `sequence-status phase-${phase}` },
-    h('div', { class: 'headline' }, headline),
-    h('div', { class: 'detail' }, detail),
+    h(
+      'div',
+      { class: 'status-head' },
+      h(
+        'div',
+        { class: 'status-text' },
+        h('div', { class: 'headline' }, headline),
+        h('div', { class: 'detail' }, detail)
+      ),
+      // Sits with the countdown it speaks, rather than crowding the button row.
+      voiceSupported
+        ? h(
+            'button',
+            {
+              type: 'button',
+              class: `voice-toggle ${prefs.voice ? 'on' : ''}`,
+              onclick: onToggleVoice,
+              title: prefs.voice
+                ? 'Voice countdown on — click to mute'
+                : 'Voice countdown off — click to speak the countdown before each frame'
+            },
+            prefs.voice ? '🔊' : '🔇'
+          )
+        : undefined
+    ),
     total
       ? h(
           'div',
@@ -166,7 +194,9 @@ function SequenceStatus({ state, prefs }) {
  *   config: import('web-gphoto2').Config | undefined,
  *   hasFolder: boolean,
  *   canCapture: boolean,
- *   log: { id: number, message: string, kind: string, at: number }[]
+ *   log: { id: number, message: string, kind: string, at: number }[],
+ *   voiceSupported: boolean,
+ *   onToggleVoice: () => void
  * }} props
  */
 export function Home({
@@ -181,7 +211,9 @@ export function Home({
   config,
   hasFolder,
   canCapture,
-  log
+  log,
+  voiceSupported,
+  onToggleVoice
 }) {
   let warnings = running ? [] : sequenceWarnings(prefs, config, hasFolder);
   let plannedSeconds = prefs.unlimited
@@ -198,7 +230,7 @@ export function Home({
   return h(
     'div',
     { id: 'home' },
-    h(SequenceStatus, { state, prefs }),
+    h(SequenceStatus, { state, prefs, voiceSupported, onToggleVoice }),
 
     h(
       'div',

examples/preact/index.html

@@ -353,14 +353,44 @@
 
       .actions {
         display: flex;
+        flex-wrap: wrap;
         gap: 8px;
         margin-top: 12px;
       }
 
+      /* Labels shouldn't fold onto a second line to make room for a sibling -
+         the row wraps instead. */
+      .actions button {
+        white-space: nowrap;
+      }
+
       .actions .big {
         flex: 1;
       }
 
+      .status-head {
+        display: flex;
+        align-items: flex-start;
+        justify-content: space-between;
+        gap: 10px;
+      }
+
+      .status-text {
+        min-width: 0;
+      }
+
+      .voice-toggle {
+        flex: none;
+        padding: 6px 10px;
+        font-size: 18px;
+        line-height: 1.2;
+      }
+
+      .voice-toggle.on {
+        border-color: var(--accent);
+        background: color-mix(in srgb, var(--accent) 14%, transparent);
+      }
+
       /* ---------- readout & log ---------- */
 
       .readout {

examples/preact/index.js

@@ -24,6 +24,7 @@ import { SettingsDrawer, loadPrefs, savePrefs } from './settings.js';
 import { Intervalometer, formatDuration } from './intervalometer.js';
 import { FrameSaver, WakeLock } from './storage.js';
 import { detectBulbSupport, configValue } from './config-utils.js';
+import { Narrator, supportsSpeech } from './voice.js';
 
 export const isDebug = new URLSearchParams(location.search).has('debug');
 
@@ -42,6 +43,7 @@ class App extends Component {
 
   saver = new FrameSaver();
   wakeLock = new WakeLock();
+  narrator = new Narrator();
 
   intervalometer = new Intervalometer({
     capture: index => this.captureFrame(index),
@@ -67,6 +69,7 @@ class App extends Component {
 
   componentDidMount() {
     this.saver.mode = this.state.prefs.saveMode;
+    this.syncNarrator(this.state.prefs);
 
     addEventListener('error', ({ message }) =>
       this.log(`Uncaught error: ${message}`, 'error')
@@ -108,17 +111,47 @@ class App extends Component {
     }));
   }
 
+  /** @param {import('./settings.js').Prefs} prefs */
+  syncNarrator(prefs) {
+    Object.assign(this.narrator, {
+      enabled: prefs.voice,
+      countFrom: prefs.voiceCountFrom,
+      voiceURI: prefs.voiceURI,
+      announceFrames: prefs.voiceAnnounceFrames
+    });
+  }
+
   /** @param {Partial<import('./settings.js').Prefs>} patch */
   setPref = patch => {
     this.setState(({ prefs }) => {
       let next = { ...prefs, ...patch };
       savePrefs(next);
       this.saver.mode = next.saveMode;
+      this.syncNarrator(next);
       if (!next.keepAwake) this.wakeLock.release();
       return { prefs: next };
     });
   };
 
+  toggleVoice = () => {
+    let on = !this.state.prefs.voice;
+    // Applied straight away rather than waiting for the state update, so a
+    // countdown can't slip out between the click and the commit.
+    this.narrator.enabled = on;
+    this.setPref({ voice: on });
+    // Speaking here also gets the user gesture Chrome wants before it will
+    // let a page talk at all.
+    if (on) this.narrator.say('Voice countdown on');
+    else this.narrator.cancel();
+  };
+
+  testVoice = () => {
+    let wasEnabled = this.narrator.enabled;
+    this.narrator.enabled = true;
+    this.narrator.say('Three. Two. One.', { interrupt: true });
+    this.narrator.enabled = wasEnabled;
+  };
+
   selectDevice = async () => {
     // @ts-ignore
     await Camera.showPicker();
@@ -259,6 +292,7 @@ class App extends Component {
   /** @param {import('./intervalometer.js').SequenceState} seq */
   handleSequenceChange(seq) {
     let running = this.intervalometer.running;
+    this.narrator.update(seq);
     this.setState({ seq });
     if (this.#wasRunning && !running) {
       this.wakeLock.release();
@@ -305,6 +339,8 @@ class App extends Component {
           : ''
       }.`
     );
+    this.narrator.reset();
+    this.narrator.say('Starting');
     this.intervalometer.start({
       intervalMs: prefs.intervalSeconds * 1000,
       count,
@@ -439,7 +475,9 @@ class App extends Component {
               config: state.config,
               hasFolder: this.saver.hasFolder,
               canCapture: !!state.supportedOps?.captureImage,
-              log: state.log
+              log: state.log,
+              voiceSupported: supportsSpeech,
+              onToggleVoice: this.toggleVoice
             })
           ),
           h(SettingsDrawer, {
@@ -452,7 +490,9 @@ class App extends Component {
             folderName: this.saver.folderName,
             chooseFolder: this.chooseFolder,
             bulbSupport: this.bulbSupport,
-            locked: running
+            locked: running,
+            voices: this.narrator.voices,
+            testVoice: this.testVoice
           })
         );
       }

examples/preact/settings.js

@@ -19,6 +19,7 @@
 import { h, Component, Fragment } from 'preact';
 import { Widget } from './widget.js';
 import { supportsFolderSaving } from './storage.js';
+import { supportsSpeech } from './voice.js';
 
 const PREFS_KEY = 'web-dslr.prefs';
 
@@ -38,7 +39,12 @@ export const DEFAULT_PREFS = {
   liveViewBetweenFrames: true,
   keepAwake: true,
   bulbEnabled: false,
-  bulbSeconds: 30
+  bulbSeconds: 30,
+  // Toggled from the home screen; the rest live in this drawer.
+  voice: false,
+  voiceCountFrom: 5,
+  voiceURI: '',
+  voiceAnnounceFrames: false
 };
 
 /** @typedef {typeof DEFAULT_PREFS} Prefs */
@@ -95,7 +101,9 @@ function Row({ label, hint, children }) {
  *   folderName: string | undefined,
  *   chooseFolder: () => void,
  *   bulbSupport: ReturnType<typeof import('./config-utils.js').detectBulbSupport>,
- *   locked: boolean
+ *   locked: boolean,
+ *   voices: SpeechSynthesisVoice[],
+ *   testVoice: () => void
  * }>
  */
 export class SettingsDrawer extends Component {
@@ -122,7 +130,9 @@ export class SettingsDrawer extends Component {
       folderName,
       chooseFolder,
       bulbSupport,
-      locked
+      locked,
+      voices,
+      testVoice
     } = props;
 
     return h(
@@ -255,6 +265,83 @@ export class SettingsDrawer extends Component {
             )
           ),
 
+          h(
+            'section',
+            null,
+            h('h3', null, 'Voice countdown'),
+            supportsSpeech
+              ? h(
+                  Fragment,
+                  null,
+                  h(
+                    'p',
+                    { class: 'notice' },
+                    'Switched on and off with the 🔊 button on the home screen.'
+                  ),
+                  h(
+                    Row,
+                    {
+                      label: 'Start counting at',
+                      hint: 'Capped at one second less than the interval, so it never talks over the previous frame.'
+                    },
+                    h('input', {
+                      type: 'number',
+                      min: '1',
+                      max: '30',
+                      step: '1',
+                      value: prefs.voiceCountFrom,
+                      onChange: e =>
+                        setPref({
+                          voiceCountFrom: Math.min(
+                            30,
+                            Math.max(1, e.currentTarget.valueAsNumber || 1)
+                          )
+                        })
+                    }),
+                    h('span', { class: 'unit' }, 'sec')
+                  ),
+                  h(
+                    Row,
+                    { label: 'Announce frame number' },
+                    h('input', {
+                      type: 'checkbox',
+                      checked: prefs.voiceAnnounceFrames,
+                      onChange: e =>
+                        setPref({ voiceAnnounceFrames: e.currentTarget.checked })
+                    })
+                  ),
+                  h(
+                    Row,
+                    { label: 'Voice' },
+                    h(
+                      'select',
+                      {
+                        value: prefs.voiceURI,
+                        onChange: e => setPref({ voiceURI: e.currentTarget.value })
+                      },
+                      h('option', { value: '' }, 'Browser default'),
+                      voices.map(v =>
+                        h('option', { key: v.voiceURI, value: v.voiceURI }, `${v.name} (${v.lang})`)
+                      )
+                    )
+                  ),
+                  h(
+                    Row,
+                    { label: 'Test' },
+                    h(
+                      'button',
+                      { type: 'button', class: 'secondary', onclick: testVoice },
+                      '🔊 Say “three, two, one”'
+                    )
+                  )
+                )
+              : h(
+                  'p',
+                  { class: 'notice' },
+                  'This browser has no speech synthesis, so the voice countdown is unavailable.'
+                )
+          ),
+
           h(
             'section',
             null,

examples/preact/tsconfig.json

@@ -1,4 +1,7 @@
 {
+  // dist/ is a copy of these same files assembled for deploy; checking it too
+  // just reports every error twice, against stale copies.
+  "exclude": ["dist", "node_modules"],
   "compilerOptions": {
     "checkJs": true,
     "target": "ESNext",

examples/preact/voice.js

@@ -0,0 +1,157 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+
+/** @typedef {import('./intervalometer.js').SequenceState} SequenceState */
+
+export const supportsSpeech = 'speechSynthesis' in globalThis;
+
+/**
+ * Speaks the run out loud: a countdown into each frame, and the odd status
+ * announcement. Useful when you're in front of the camera rather than at the
+ * laptop, or holding still for a long exposure.
+ *
+ * Driven from the intervalometer's state updates (~5/s) rather than its own
+ * timer, so it can't drift away from what the sequence is actually doing. Each
+ * second is spoken at most once, tracked by the second it belongs to.
+ */
+export class Narrator {
+  enabled = false;
+  /** Seconds before a frame to start counting. */
+  countFrom = 5;
+  announceFrames = false;
+  /** Empty means the browser's default voice. */
+  voiceURI = '';
+
+  /** @type {number | null} */
+  #lastSecond = null;
+  #lastNextAt = 0;
+  /** @type {string} */
+  #lastPhase = 'idle';
+  /** @type {SpeechSynthesisVoice[]} */
+  #voices = [];
+
+  constructor() {
+    if (!supportsSpeech) return;
+    this.#loadVoices();
+    // Voices arrive asynchronously, and on some platforms only after this fires.
+    speechSynthesis.onvoiceschanged = () => this.#loadVoices();
+  }
+
+  #loadVoices() {
+    this.#voices = speechSynthesis.getVoices();
+  }
+
+  get voices() {
+    return this.#voices;
+  }
+
+  /**
+   * @param {string} text
+   * @param {{ interrupt?: boolean }} [options]
+   */
+  say(text, { interrupt = false } = {}) {
+    if (!supportsSpeech || !this.enabled) return;
+    // A countdown that queues up behind a stale announcement is worse than
+    // silence, so anything time-critical clears the queue first.
+    if (interrupt) speechSynthesis.cancel();
+    let utterance = new SpeechSynthesisUtterance(text);
+    let voice = this.#voices.find(v => v.voiceURI === this.voiceURI);
+    if (voice) utterance.voice = voice;
+    // Slightly quick, so a spoken "three" lands nearer the second it names.
+    utterance.rate = 1.1;
+    speechSynthesis.speak(utterance);
+  }
+
+  cancel() {
+    if (supportsSpeech) speechSynthesis.cancel();
+  }
+
+  /** Forget what's been spoken, e.g. when a new sequence starts. */
+  reset() {
+    this.#lastSecond = null;
+    this.#lastNextAt = 0;
+    this.#lastPhase = 'idle';
+    this.cancel();
+  }
+
+  /**
+   * Called on every sequence state update.
+   * @param {SequenceState} state
+   */
+  update(state) {
+    if (!this.enabled || !supportsSpeech) {
+      this.#lastPhase = state.phase;
+      return;
+    }
+
+    // A new target time means a new frame to count into.
+    if (state.nextAt !== this.#lastNextAt) {
+      this.#lastNextAt = state.nextAt;
+      this.#lastSecond = null;
+    }
+
+    if (state.phase === 'waiting' || state.phase === 'delay') {
+      // Never start counting from further out than the gap actually is - with a
+      // 3s interval and a count of 5 you'd otherwise talk over the last frame.
+      let gapSeconds =
+        state.phase === 'delay'
+          ? Infinity
+          : Math.round(state.intervalMs / 1000) - 1;
+      let limit = Math.max(0, Math.min(this.countFrom, gapSeconds));
+      let remaining = Math.ceil((state.nextAt - Date.now()) / 1000);
+      if (remaining >= 1 && remaining <= limit && remaining !== this.#lastSecond) {
+        this.#lastSecond = remaining;
+        this.say(String(remaining));
+      }
+    }
+
+    if (state.phase !== this.#lastPhase) {
+      this.#announcePhase(state);
+      this.#lastPhase = state.phase;
+    }
+  }
+
+  /** @param {SequenceState} state */
+  #announcePhase(state) {
+    switch (state.phase) {
+      case 'capturing':
+        if (this.announceFrames) {
+          this.say(
+            state.total
+              ? `Frame ${state.taken + 1} of ${state.total}`
+              : `Frame ${state.taken + 1}`
+          );
+        }
+        break;
+      case 'done':
+        this.say(
+          `Sequence complete. ${state.taken} frame${
+            state.taken === 1 ? '' : 's'
+          }.`,
+          { interrupt: true }
+        );
+        break;
+      case 'stopped':
+        this.say('Sequence stopped.', { interrupt: true });
+        break;
+      case 'failed':
+        this.say('Sequence failed.', { interrupt: true });
+        break;
+    }
+  }
+}