feat(useSpeechSynthesisOptions): add option onBoundary (#4960)

pkc918 · web-flow · commit c0dca935f1a2 · 2025-08-18T05:57:43.000Z
diff --git a/packages/core/useSpeechSynthesis/demo.vue b/packages/core/useSpeechSynthesis/demo.vue
@@ -1,18 +1,33 @@
 <script setup lang="ts">
 import { useSpeechSynthesis } from '@vueuse/core'
-import { ref as deepRef, onMounted, shallowRef } from 'vue'
+import { computed, ref as deepRef, onMounted, shallowRef, watch } from 'vue'
 
 const voice = deepRef<SpeechSynthesisVoice>(undefined as unknown as SpeechSynthesisVoice)
 const text = shallowRef('Hello, everyone! Good morning!')
 const pitch = shallowRef(1)
 const rate = shallowRef(1)
 const volume = shallowRef(1)
 
+const boundaryStart = shallowRef(0)
+const boundaryEnd = shallowRef(0)
+
+const textSegments = computed(() => {
+  const fullText = text.value || ''
+  const startIndex = Math.max(0, Math.min(boundaryStart.value, fullText.length))
+  const endIndex = Math.max(startIndex, Math.min(boundaryEnd.value, fullText.length))
+  return {
+    leadingText: fullText.slice(0, startIndex),
+    highlightedText: fullText.slice(startIndex, endIndex),
+    trailingText: fullText.slice(endIndex),
+  }
+})
+
 const speech = useSpeechSynthesis(text, {
   voice,
   pitch,
   rate,
   volume,
+  onBoundary,
 })
 
 let synth: SpeechSynthesis
@@ -30,12 +45,34 @@ onMounted(() => {
   }
 })
 
+function onBoundary(event: SpeechSynthesisEvent) {
+  const { charIndex, charLength } = event
+  const startIndex = charIndex
+  let endIndex = charIndex
+  if (typeof charLength === 'number' && charLength > 0) {
+    endIndex = startIndex + charLength
+  }
+  else {
+    const fullText = text.value || ''
+    const remainingText = fullText.slice(startIndex)
+    const firstWordMatch = remainingText.match(/^\S+/)
+    endIndex = startIndex + (firstWordMatch ? firstWordMatch[0].length : 0)
+  }
+  boundaryStart.value = startIndex
+  boundaryEnd.value = endIndex
+}
+
+function resetSpeakingText() {
+  boundaryStart.value = 0
+  boundaryEnd.value = 0
+}
+
 function play() {
   if (speech.status.value === 'pause') {
-    console.log('resume')
     window.speechSynthesis.resume()
   }
   else {
+    resetSpeakingText()
     speech.speak()
   }
 }
@@ -46,7 +83,14 @@ function pause() {
 
 function stop() {
   speech.stop()
+  resetSpeakingText()
 }
+
+watch(() => speech.status.value, (s) => {
+  if (s === 'end') {
+    resetSpeakingText()
+  }
+})
 </script>
 
 <template>
@@ -61,6 +105,12 @@ function stop() {
     <div v-else>
       <label class="font-bold mr-2">Spoken Text</label>
       <input v-model="text" class="!inline-block" type="text">
+      <div class="mt-2" aria-label="current-boundary-preview">
+        <label class="font-bold mr-2">Speaking Text</label>
+        <span>{{ textSegments.leadingText }}</span>
+        <span class="text-primary">{{ textSegments.highlightedText }}</span>
+        <span>{{ textSegments.trailingText }}</span>
+      </div>
 
       <br>
       <label class="font-bold mr-2">Language</label>
diff --git a/packages/core/useSpeechSynthesis/index.ts b/packages/core/useSpeechSynthesis/index.ts
@@ -36,6 +36,10 @@ export interface UseSpeechSynthesisOptions extends ConfigurableWindow {
    * @default 1
    */
   volume?: MaybeRefOrGetter<SpeechSynthesisUtterance['volume']>
+  /**
+   * Callback function that is called when the boundary event is triggered.
+   */
+  onBoundary?: (event: SpeechSynthesisEvent) => void
 }
 
 /**
@@ -53,6 +57,7 @@ export function useSpeechSynthesis(
     rate = 1,
     volume = 1,
     window = defaultWindow,
+    onBoundary,
   } = options
 
   const synth = window && (window as any).speechSynthesis as SpeechSynthesis
@@ -99,6 +104,10 @@ export function useSpeechSynthesis(
     utterance.onerror = (event) => {
       error.value = event
     }
+
+    utterance.onboundary = (event) => {
+      onBoundary?.(event)
+    }
   }
 
   const utterance = computed(() => {
