⬅️ Back to Table of Contents

📄 useSpeechSynthesis

📊 Analysis Summary

Metric	Count
🔧 Functions	5
📦 Imports	14
🟢 Vue Composition API	4
📐 Interfaces	2
📑 Type Aliases	1

📚 Table of Contents

• Imports
• Vue Composition API
• Functions
• Interfaces
• Type Aliases

🛠️ File Location:

📂 packages/core/useSpeechSynthesis/index.ts

📦 Imports

Name	Source
ComputedRef	vue
MaybeRef	vue
MaybeRefOrGetter	vue
ShallowRef	vue
ConfigurableWindow	../_configurable
Supportable	../types
toRef	@vueuse/shared
tryOnScopeDispose	@vueuse/shared
computed	vue
shallowRef	vue
toValue	vue
watch	vue
defaultWindow	../_configurable
useSupported	../useSupported

---

Vue Composition API

Name	Type	Reactive Variables	Composables
computed	computed	none	none
watch	watch	none	none
watch	watch	none	none
watch	watch	none	none

---

Functions

useSpeechSynthesis(text: MaybeRefOrGetter<string>, options: UseSpeechSynthesisOptions): UseSpeechSynthesisReturn

Reactive SpeechSynthesis.

See: https://vueuse.org/useSpeechSynthesis, https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis SpeechSynthesis

Raw JSDoc

/**
 * Reactive SpeechSynthesis.
 *
 * @see https://vueuse.org/useSpeechSynthesis
 * @see https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis SpeechSynthesis
 */

Calls:

• useSupported (from ../useSupported)
• shallowRef (from vue)
• toRef (from @vueuse/shared)
• toValue (from vue)
• onBoundary
• computed (from vue)
• bindEventsForUtterance
• synth!.cancel
• synth!.speak
• watch (from vue)
• synth!.resume
• synth!.pause
• tryOnScopeDispose (from @vueuse/shared)

Code

export function useSpeechSynthesis(
  text: MaybeRefOrGetter<string>,
  options: UseSpeechSynthesisOptions = {},
): UseSpeechSynthesisReturn {
  const {
    pitch = 1,
    rate = 1,
    volume = 1,
    window = defaultWindow,
    onBoundary,
  } = options

  const synth = window && (window as any).speechSynthesis as SpeechSynthesis
  const isSupported = useSupported(() => synth)

  const isPlaying = shallowRef(false)
  const status = shallowRef<UseSpeechSynthesisStatus>('init')

  const spokenText = toRef(text || '')
  const lang = toRef(options.lang || 'en-US')
  const error = shallowRef<SpeechSynthesisErrorEvent | undefined>(undefined)

  const toggle = (value = !isPlaying.value) => {
    isPlaying.value = value
  }

  const bindEventsForUtterance = (utterance: SpeechSynthesisUtterance) => {
    utterance.lang = toValue(lang)
    utterance.voice = toValue(options.voice) || null
    utterance.pitch = toValue(pitch)
    utterance.rate = toValue(rate)
    utterance.volume = toValue(volume)

    utterance.onstart = () => {
      isPlaying.value = true
      status.value = 'play'
    }

    utterance.onpause = () => {
      isPlaying.value = false
      status.value = 'pause'
    }

    utterance.onresume = () => {
      isPlaying.value = true
      status.value = 'play'
    }

    utterance.onend = () => {
      isPlaying.value = false
      status.value = 'end'
    }

    utterance.onerror = (event) => {
      error.value = event
    }

    utterance.onboundary = (event) => {
      onBoundary?.(event)
    }
  }

  const utterance = computed(() => {
    isPlaying.value = false
    status.value = 'init'
    const newUtterance = new SpeechSynthesisUtterance(spokenText.value)
    bindEventsForUtterance(newUtterance)
    return newUtterance
  })

  const speak = () => {
    synth!.cancel()
    if (utterance)
      synth!.speak(utterance.value)
  }

  const stop = () => {
    synth!.cancel()
    isPlaying.value = false
  }

  if (isSupported.value) {
    bindEventsForUtterance(utterance.value)

    watch(lang, (lang) => {
      if (utterance.value && !isPlaying.value)
        utterance.value.lang = lang
    })

    if (options.voice) {
      watch(options.voice, () => {
        synth!.cancel()
      })
    }

    watch(isPlaying, () => {
      if (isPlaying.value)
        synth!.resume()
      else
        synth!.pause()
    })
  }

  tryOnScopeDispose(() => {
    isPlaying.value = false
  })

  return {
    isSupported,
    isPlaying,
    status,
    utterance,
    error,

    stop,
    toggle,
    speak,
  }
}

Internal helpers

Declared inside another function in this file.

toggle(value: boolean): void

Parameters:

• value boolean

Returns: void

Code

(value = !isPlaying.value) => {
    isPlaying.value = value
  }

bindEventsForUtterance(utterance: SpeechSynthesisUtterance): void

Parameters:

• utterance SpeechSynthesisUtterance

Returns: void

Calls:

• toValue (from vue)
• onBoundary

Code

(utterance: SpeechSynthesisUtterance) => {
    utterance.lang = toValue(lang)
    utterance.voice = toValue(options.voice) || null
    utterance.pitch = toValue(pitch)
    utterance.rate = toValue(rate)
    utterance.volume = toValue(volume)

    utterance.onstart = () => {
      isPlaying.value = true
      status.value = 'play'
    }

    utterance.onpause = () => {
      isPlaying.value = false
      status.value = 'pause'
    }

    utterance.onresume = () => {
      isPlaying.value = true
      status.value = 'play'
    }

    utterance.onend = () => {
      isPlaying.value = false
      status.value = 'end'
    }

    utterance.onerror = (event) => {
      error.value = event
    }

    utterance.onboundary = (event) => {
      onBoundary?.(event)
    }
  }

speak(): void

Returns: void

Calls:

• synth!.cancel
• synth!.speak

Code

() => {
    synth!.cancel()
    if (utterance)
      synth!.speak(utterance.value)
  }

stop(): void

Returns: void

Calls:

• synth!.cancel

Code

() => {
    synth!.cancel()
    isPlaying.value = false
  }

---

Interfaces

UseSpeechSynthesisOptions

Interface Code

export interface UseSpeechSynthesisOptions extends ConfigurableWindow {
  /**
   * Language for SpeechSynthesis
   *
   * @default 'en-US'
   */
  lang?: MaybeRefOrGetter<string>
  /**
   * Gets and sets the pitch at which the utterance will be spoken at.
   *
   * @default 1
   */
  pitch?: MaybeRefOrGetter<SpeechSynthesisUtterance['pitch']>
  /**
   * Gets and sets the speed at which the utterance will be spoken at.
   *
   * @default 1
   */
  rate?: MaybeRefOrGetter<SpeechSynthesisUtterance['rate']>
  /**
   * Gets and sets the voice that will be used to speak the utterance.
   */
  voice?: MaybeRef<SpeechSynthesisVoice>
  /**
   * Gets and sets the volume that the utterance will be spoken at.
   *
   * @default 1
   */
  volume?: MaybeRefOrGetter<SpeechSynthesisUtterance['volume']>
  /**
   * Callback function that is called when the boundary event is triggered.
   */
  onBoundary?: (event: SpeechSynthesisEvent) => void
}

Properties

Name	Type	Optional	Description
lang	MaybeRefOrGetter<string>	✓	not shown
pitch	MaybeRefOrGetter<SpeechSynthesisUtterance['pitch']>	✓	not shown
rate	MaybeRefOrGetter<SpeechSynthesisUtterance['rate']>	✓	not shown
voice	MaybeRef<SpeechSynthesisVoice>	✓	not shown
volume	MaybeRefOrGetter<SpeechSynthesisUtterance['volume']>	✓	not shown
onBoundary	(event: SpeechSynthesisEvent) => void	✓	not shown

UseSpeechSynthesisReturn

Interface Code

export interface UseSpeechSynthesisReturn extends Supportable {
  isPlaying: ShallowRef<boolean>
  status: ShallowRef<UseSpeechSynthesisStatus>
  utterance: ComputedRef<SpeechSynthesisUtterance>
  error: ShallowRef<SpeechSynthesisErrorEvent | undefined>
  stop: () => void
  toggle: (value?: boolean) => void
  speak: () => void
}

Properties

Name	Type	Optional	Description
isPlaying	ShallowRef<boolean>	✗	not shown
status	ShallowRef<UseSpeechSynthesisStatus>	✗	not shown
utterance	ComputedRef<SpeechSynthesisUtterance>	✗	not shown
error	ShallowRef<SpeechSynthesisErrorEvent \| undefined>	✗	not shown
stop	() => void	✗	not shown
toggle	(value?: boolean) => void	✗	not shown
speak	() => void	✗	not shown

---

Type Aliases

UseSpeechSynthesisStatus

type UseSpeechSynthesisStatus = 'init' | 'play' | 'pause' | 'end';

---

Generated by Syntax Scribe