docs/api/app/components_Tts.js.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>JSDoc: Source: components/Tts.js</title>

    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>

<body>

<div id="main">

    <h1 class="page-title">Source: components/Tts.js</h1>

    
    <section>
        <article>
            <pre class="prettyprint source linenums"><code>import React, { useState, useEffect, useCallback } from 'react'
import { View, Pressable } from 'react-native'
import { Button } from 'react-native-elements'
import { Colors } from '../constants/Colors'
import { asyncTimeout } from '../utils/asyncTimeout'
import { createStyleSheet } from '../styles/createStyleSheet'
import { LeaText } from './LeaText'
import { Log } from '../infrastructure/Log'
import { SoundIcon } from './SoundIcon'
import { isValidNumber } from '../utils/number/isValidNumber'
import { createTimedPromise } from '../utils/createTimedPromise'

// TODO we should extract TTSEngine into an own testable entity

/** @private **/
let Speech = null

/** @private **/
const styles = createStyleSheet({
  container: {
    flex: 0,
    flexDirection: 'row',
    alignItems: 'flex-start',
    justifyContent: 'flex-start'
  },
  ttsButton: {
    borderColor: '#0f0'
  },
  text: {},
  icon: { padding: 5 }
})

const globalDebug = Log.create('tts', 'debug')
const handlers = {}
const runHandlers = name => {
  if (!handlers[name]) { return }
  handlers[name].forEach(fn => fn())
}

/**
 * Tts stands for Text-To-Speech. It contains an icon and the text to be spoken.
 *
 * @category Components
 * @param {string} props.text: The displayed and spoken text
 * @param {string} props.ttsText: The spoken text, use this if it differs from written text
 * @param {boolean} props.dontShowText: Determines whether the text is displayed (Default 'true')
 * @param {boolean} props.smallButton: Changes the button size from 20 to 15 (Default 'false')
 * @param {boolean=} props.block: Makes the container flexGrow. If this causes problems, use style instead.
 * @param {boolean=} props.asButton: Makes the container a block-sized button
 * @param {boolean=} props.disabled: Makes the button disabled
 * @param {string=} props.color: The color of the icon and the text, in hexadecimal format. Default: Colors.secondary
 *   (examples in ./constants/Colors.js)
 * @param {string=} props.iconColor: The color of the icon in hexadecimal format. Default: Colors.secondary   (examples
 *   in ./constants/Colors.js)
 * @param {string=} props.activeIconColor: The color of the icon when speaking is active
 * @param {number} props.shrink: The parameter to shrink the text. Default: 1
 * @param {number} props.fontSize: The parameter to change the font size of the text. Default: 18
 * @param {string} props.fontStyle: The parameter to change the font style of the text. Default: 'normal' ('italic')
 * @param {object=} props.style: The parameter to change the font style of the text. Default: 'normal' ('italic')
 * @param {string} props.align Defines the vertical alignment of the button and text
 * @param {number} props.paddingTop: Determines the top padding of the text. Default: 8
 * @param {number} props.speed: Determines the speed rate of the voice to speak. Default: 1.0
 * @param {string|number} props.id: The parameter to identify the buttons
 * @returns {JSX.Element}
 * @component
 */
const TtsComponent = props => {
  // TODO use useReducer to implement complex state logic?
  const [isSpeaking, setIsSpeaking] = useState(false)
  const [isDone, setIsDone] = useState(false)
  const [speakingId, setSpeakingId] = useState(0)
  const [boundary, setBoundary] = useState({ charIndex: -1, charLength: -1 })
  const [iconColor, setIconColor] = useState(props.iconColor || props.color || Colors.secondary)

  const getIdleIconColor = () => props.iconColor || props.color || Colors.secondary
  const getIdleTextColor = () => props.color || Colors.secondary
  const debug = props.debug || TTSengine.debug
    ? globalDebug
    : () => {}

  useEffect(() => {
    debug('set isSpeaking', isSpeaking)
    TTSengine.isSpeaking = isSpeaking
  }, [isSpeaking])

  useEffect(() => {
    debug('set speakingId', speakingId)
    TTSengine.speakId = speakingId
  }, [speakingId])

  useEffect(() => {
    debug('set icon color', iconColor)
    TTSengine.iconColor = iconColor
  }, [iconColor])

  useEffect(() => {
    if (isDone) {
      debug('reset after done')
      setIconColor(getIdleIconColor())
      setIsSpeaking(false)
      setSpeakingId(0)
    }
  }, [isDone])

  /**
   * Starts speaking props.text. At startup it calls the function startSpeak() and at the end its calls stopSpeak()
   */
  const speak = useCallback(async () => {
    runHandlers('beforeSpeak')

    const isSpeaking = await Speech.isSpeakingAsync()
    debug('speak', { isSpeaking })

    if (isSpeaking) {
      stopSpeak()
      await asyncTimeout(5)
      return await speak()
    }

    const textToSpeak = props.ttsText ?? props.text

    Speech.speak(textToSpeak, {
      language: 'ger',
      pitch: 1,
      rate: props.speed || TTSengine.currentSpeed,
      voice: props.voice || TTSengine.currentVoice,
      onStart: () => {
        debug('speak', textToSpeak)
        startSpeak()
      },
      onStopped: () => {
        debug('stopped', textToSpeak)
        stopSpeak()
      },
      onDone: () => {
        debug('finished', textToSpeak)
        // TODO call stopSpeak and update tests to fix state bug
        stopSpeak()
        setIsDone(true)
      },
      // XXX: incubating feature, we will not use it on the next releases
      onBoundary: props.boundary === true &amp;&amp; ((e) => {
        if (isValidNumber(e.charIndex) &amp;&amp; isValidNumber(e.charLength)) {
          setBoundary({
            charIndex: e.charIndex,
            charLength: e.charLength
          })
        }
      })
    })
  }, [])
  /**
   * Stops expo-speech and changes the color back to props.color and sets CurrentlyPlaying to false
   */
  const stopSpeak = () => {
    debug('stop')
    setIconColor(getIdleIconColor())
    setIsSpeaking(false)
    setSpeakingId(0)
    setIsDone(false)
    setBoundary({ charIndex: -1, charLength: -1 })
    Speech.stop()
  }
  /**
   * Changes the color of the icon to green and sets CurrentlyPlaying to true, at the start
   */
  const startSpeak = () => {
    debug('start')
    setIsSpeaking(true)
    setSpeakingId(props.testId ?? props.id)
    setIconColor(props.activeIconColor ?? Colors.primary)
    if (props.onStart) {
      props.onStart({ isDone, isSpeaking, speakingId })
    }
  }

  /**
   * Displays the spoken text if "dontShowText" is false.
   */
  const displayedText = () => {
    if (props.dontShowText) { return null }

    // color always defaults to secondary
    const textStyleProps = { color: getIdleTextColor(), marginLeft: 10 }

    if (props.block) {
      textStyleProps.flex = 1
      textStyleProps.flexGrow = 1
    }

    if (props.fontStyle) {
      Object.assign(textStyleProps, props.fontStyle)
    }

    // if we receive a boundary update then we need to tokenize
    // the text and let the text component render, based on token
    let token

    if (boundary.charIndex > -1 &amp;&amp; boundary.charLength > -1) {
      const start = boundary.charIndex
      const end = start + boundary.charLength
      token = []

      if (start > 0) {
        token.push({ key: 'before', text: props.text.slice(0, start) })
      }

      token.push({ key: 'word', text: props.text.slice(start, end), style: { color: props.activeIconColor ?? Colors.primary } })

      if (end &lt; props.text.length) {
        token.push({ key: 'after', text: props.text.slice(end, props.text.length) })
      }
    }

    return (&lt;LeaText style={textStyleProps} fitSize={props.fitSize} token={token}>{props.text}&lt;/LeaText>)
  }

  const ttsContainerStyle = { ...styles.container }
  if (props.align) {
    ttsContainerStyle.alignItems = props.align
  }
  if (props.style) {
    Object.assign(ttsContainerStyle, props.style)
  }
  const iconSize = props.smallButton ? 20 : 30
  const onPress = () => ((speakingId === props.id) &amp;&amp; isSpeaking) ? stopSpeak() : speak()
  const rippleConfig = {
    color: iconColor,
    borderless: true,
    radius: iconSize
  }

  const renderIcon = () => {
    const currentIconColor = props.asButton &amp;&amp; !isSpeaking
      ? Colors.white
      : props.disabled
        ? Colors.gray
        : iconColor
    return (
      &lt;SoundIcon
        animated={isSpeaking}
        color={currentIconColor}
        size={iconSize}
        style={styles.icon}
      />
    )
  }

  if (props.asButton) {
    const buttonStyle = {
      backgroundColor: isSpeaking
        ? Colors.white
        : iconColor
    }
    if (props.block) {
      buttonStyle.flexGrow = 1
    }
    return (
      &lt;Button
        accessibilityRole='button'
        testID={props.testId}
        containerStyle={ttsContainerStyle}
        buttonStyle={[styles.ttsButton, buttonStyle]}
        onPress={onPress}
        type='solid'
        raised
        disabled={props.disabled}
        title={renderIcon()}
      />
    )
  }

  return (
    &lt;View style={ttsContainerStyle}>
      &lt;Pressable
        accessibilityRole='button'
        disabled={props.disabled}
        android_ripple={rippleConfig}
        onPress={onPress}
        testID={props.testId}
      >
        {renderIcon()}
      &lt;/Pressable>
      {displayedText()}
    &lt;/View>
  )
}

/**
 * Global Text-To-Speech engine. The actual tts-processor engine is injected,
 * this is only a wrapper to connect it with react components.
 *
 * Designed to have always only one instance of speech being active.
 *
 *
 * @property setSpeech {function} use to inject tts implementation
 * @property stop {function} use to stop tts speech
 * @property isSpeaking {boolean} indicate if currently there is a speech ongoing
 * @property speakId {number} id of the target that is used for tts
 * @property iconColor {null} current color of the speech icon
 * @property component {function} returns the react component {ttsComponent}
 * @property debug {boolean} debugs all internal tts events if true
 */
export const TTSengine = {
  /**
   *
   * @param speechProvider {object}
   * @param {boolean} [speakImmediately=false]
   * @param text {string}
   * @param timeout {number=}
   * @return {Promise&lt;*>}
   */
  setSpeech (speechProvider, { speakImmediately = false, text = '', timeout = 500 } = {}) {
    globalDebug('set speech', { speakImmediately, timeout, text })
    Speech = speechProvider

    if (speakImmediately) {
      return createTimedPromise(new Promise((resolve) => {
        Speech.speak(text, {
          language: 'ger',
          pitch: 1,
          rate: 1,
          volume: 0,
          onDone: resolve,
          onError: resolve
        })
      }), { timeout })
    }
    else {
      return Promise.resolve()
    }
  },
  /**
   * Adds a new global hook
   * @param name {string}
   * @param fn {function}
   */
  on: (name, fn) => {
    globalDebug('add global listener', name)
    handlers[name] = handlers[name] || []
    handlers[name].push(fn)
  },
  /**
   * Removes global hook
   * @param name {string}
   * @param fn {function}
   * @return {boolean}
   */
  off: (name, fn) => {
    globalDebug('add global listener', name)
    const list = handlers[name] ?? []
    const index = list.findIndex(value => value === fn)
    if (index === -1) {
      return false
    }
    list.splice(index, 1)
    return true
  },
  /**
   * Stops speaking
   * @return {*}
   */
  stop () {
    return Speech.stop()
  },
  availableVoices: null,
  isSpeaking: false,
  speakId: 0,
  iconColor: null,
  debug: false,
  defaultSpeed: 1,
  currentSpeed: 1,
  currentVoice: undefined,
  /**
   * Returns the TTS React component
   * @return {function():JSX.Element}
   */
  component: () => TtsComponent,
  /**
   * Sets a new speed, valid values are 0.1 &lt;= x &lt;= 2.0
   * @param newSpeed {number}
   */
  updateSpeed: newSpeed => {
    globalDebug('set new speed', newSpeed)
    if (newSpeed &lt; 0.1 || newSpeed > 2.0) {
      throw new Error(`New speed not in range, expected ${newSpeed} between 0.1 and 2.0`)
    }
    TTSengine.currentSpeed = newSpeed
  },
  /**
   * Sets a new voice by given identifier
   * @param identifier {string}
   */
  setVoice: identifier => {
    globalDebug('set default voice', identifier)
    TTSengine.currentVoice = identifier
  },
  /**
   * Speaks a new text immediately, stops
   * all speech
   * @param text
   */
  speakImmediately: text => {
    globalDebug('speak immediately', text)
    Speech.stop()
    Speech.speak(text, {
      language: 'ger',
      pitch: 1,
      rate: TTSengine.currentSpeed,
      volume: 1.0,
      voice: TTSengine.currentVoice
    })
  },
  /**
   * Returns all available voices
   * @return {Promise&lt;Array&lt;Object>>}
   */
  getVoices: () => new Promise((resolve, reject) => {
    globalDebug('get voices')
    if (TTSengine.availableVoices !== null) {
      return resolve(TTSengine.availableVoices)
    }

    const onComplete = loaded => {
      TTSengine.availableVoices = loaded
      return resolve(loaded)
    }

    loadVoices({ count: 5, onComplete, onError: reject })
  })
}

const loadVoices = ({ counter, onComplete, onError }) => {
  globalDebug('load voices', { counter })
  const langPattern = /de[-_]+/i

  setTimeout(async () => {
    let voices
    try {
      voices = await Speech.getAvailableVoicesAsync()
    }
    catch (err) {
      return onError(err)
    }

    if (voices.length > 0) {
      const filtered = voices.filter(v => {
        return (
          langPattern.test(v.language) &amp;&amp;
          !(v.identifier ?? '').includes('eloquence')
        )
      })

      onComplete(filtered)
    }
    else {
      if (!counter || counter &lt; 10) {
        loadVoices({
          count: (counter ?? 0) + 1,
          onComplete,
          onError
        })
      }
      else {
        onComplete([])
      }
    }
  }, (counter ?? 1) * 300)
}

export const useTts = () => ({ Tts: TtsComponent })
</code></pre>
        </article>
    </section>


</div>

<nav>
    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="AuthenticationError.html">AuthenticationError</a></li><li><a href="ClozeRenderer.html">ClozeRenderer</a></li><li><a href="ConnectItemRenderer.html">ConnectItemRenderer</a></li><li><a href="ConnectionError.html">ConnectionError</a></li><li><a href="ImageRenderer.html">ImageRenderer</a></li><li><a href="LeaCollection.html">LeaCollection</a></li><li><a href="MeteorError_MeteorError.html">MeteorError</a></li><li><a href="SyncScreen.html">SyncScreen</a></li><li><a href="UnitContentElementFactory.html">UnitContentElementFactory</a></li></ul><h3>Global</h3><ul><li><a href="global.html#AccountInfo">AccountInfo</a></li><li><a href="global.html#AchievementsScreen">AchievementsScreen</a></li><li><a href="global.html#ActionButton">ActionButton</a></li><li><a href="global.html#App">App</a></li><li><a href="global.html#AppSession">AppSession</a></li><li><a href="global.html#CharacterInput">CharacterInput</a></li><li><a href="global.html#Checkbox">Checkbox</a></li><li><a href="global.html#ChoiceRenderer">ChoiceRenderer</a></li><li><a href="global.html#CircularProgress">CircularProgress</a></li><li><a href="global.html#ClozeRendererBlank">ClozeRendererBlank</a></li><li><a href="global.html#ClozeRendererSelect">ClozeRendererSelect</a></li><li><a href="global.html#Colors">Colors</a></li><li><a href="global.html#CompareState">CompareState</a></li><li><a href="global.html#CompleteScreen">CompleteScreen</a></li><li><a href="global.html#Config">Config</a></li><li><a href="global.html#Confirm">Confirm</a></li><li><a href="global.html#Connecting">Connecting</a></li><li><a href="global.html#ConnectorComponent">ConnectorComponent</a></li><li><a href="global.html#ContentRenderer">ContentRenderer</a></li><li><a href="global.html#CurrentProgress">CurrentProgress</a></li><li><a href="global.html#DeveloperScreen">DeveloperScreen</a></li><li><a href="global.html#Diamond">Diamond</a></li><li><a href="global.html#DimensionScreen">DimensionScreen</a></li><li><a href="global.html#ErrorMessage">ErrorMessage</a></li><li><a href="global.html#FadePanel">FadePanel</a></li><li><a href="global.html#HomeScreen">HomeScreen</a></li><li><a href="global.html#InstructionsGraphicsRendererOriginal">InstructionsGraphicsRendererOriginal</a></li><li><a href="global.html#InteractionGraph">InteractionGraph</a></li><li><a href="global.html#LeaButton">LeaButton</a></li><li><a href="global.html#LeaButtonGroup">LeaButtonGroup</a></li><li><a href="global.html#LeaLogo">LeaLogo</a></li><li><a href="global.html#LeaText">LeaText</a></li><li><a href="global.html#MapScreen">MapScreen</a></li><li><a href="global.html#Markdown">Markdown</a></li><li><a href="global.html#MarkdownRenderer">MarkdownRenderer</a></li><li><a href="global.html#MilestoneComponent">MilestoneComponent</a></li><li><a href="global.html#NullComponent">NullComponent</a></li><li><a href="global.html#PlainTextRenderer">PlainTextRenderer</a></li><li><a href="global.html#ProfileScreen">ProfileScreen</a></li><li><a href="global.html#RegistrationScreen">RegistrationScreen</a></li><li><a href="global.html#RenderScreenBase">RenderScreenBase</a></li><li><a href="global.html#RouteButton">RouteButton</a></li><li><a href="global.html#SoundIcon">SoundIcon</a></li><li><a href="global.html#Stack">Stack</a></li><li><a href="global.html#Stage">Stage</a></li><li><a href="global.html#Sync">Sync</a></li><li><a href="global.html#TTSVoiceConfig">TTSVoiceConfig</a></li><li><a href="global.html#TTSengine">TTSengine</a></li><li><a href="global.html#TermsAndConditionsScreen">TermsAndConditionsScreen</a></li><li><a href="global.html#TtsComponent">TtsComponent</a></li><li><a href="global.html#UnitRenderer">UnitRenderer</a></li><li><a href="global.html#UnitSetRenderer">UnitSetRenderer</a></li><li><a href="global.html#UserProgress">UserProgress</a></li><li><a href="global.html#WelcomeScreen">WelcomeScreen</a></li><li><a href="global.html#addCollection">addCollection</a></li><li><a href="global.html#asyncTimeout">asyncTimeout</a></li><li><a href="global.html#byDocId">byDocId</a></li><li><a href="global.html#byOrderedIds">byOrderedIds</a></li><li><a href="global.html#callMeteor">callMeteor</a></li><li><a href="global.html#checkResponse">checkResponse</a></li><li><a href="global.html#clearObject">clearObject</a></li><li><a href="global.html#collectionExists">collectionExists</a></li><li><a href="global.html#collectionNotInitialized">collectionNotInitialized</a></li><li><a href="global.html#completeUnit">completeUnit</a></li><li><a href="global.html#correctDiamondProgress">correctDiamondProgress</a></li><li><a href="global.html#createCollection">createCollection</a></li><li><a href="global.html#createRepository">createRepository</a></li><li><a href="global.html#createRoutableComponent">createRoutableComponent</a></li><li><a href="global.html#createSchema">createSchema</a></li><li><a href="global.html#createScoringSummaryForInput">createScoringSummaryForInput</a></li><li><a href="global.html#createSimpleTokenizer">createSimpleTokenizer</a></li><li><a href="global.html#createStorageAPI">createStorageAPI</a></li><li><a href="global.html#createStyleSheet">createStyleSheet</a></li><li><a href="global.html#createTimedPromise">createTimedPromise</a></li><li><a href="global.html#ensureConnected">ensureConnected</a></li><li><a href="global.html#getChoiceEntryScoreColor">getChoiceEntryScoreColor</a></li><li><a href="global.html#getCollection">getCollection</a></li><li><a href="global.html#getCompareValuesForSelectableItems">getCompareValuesForSelectableItems</a></li><li><a href="global.html#getDimensionColor">getDimensionColor</a></li><li><a href="global.html#getName">getName</a></li><li><a href="global.html#getPositionOnCircle">getPositionOnCircle</a></li><li><a href="global.html#getScoring">getScoring</a></li><li><a href="global.html#hasOwnProp">hasOwnProp</a></li><li><a href="global.html#isDefined">isDefined</a></li><li><a href="global.html#isSafeInteger">isSafeInteger</a></li><li><a href="global.html#isUndefinedResponse">isUndefinedResponse</a></li><li><a href="global.html#isValidNumber">isValidNumber</a></li><li><a href="global.html#isWord">isWord</a></li><li><a href="global.html#loadAchievementsData">loadAchievementsData</a></li><li><a href="global.html#loadDevData">loadDevData</a></li><li><a href="global.html#loadMapData">loadMapData</a></li><li><a href="global.html#loadSettingsFromUserProfile">loadSettingsFromUserProfile</a></li><li><a href="global.html#randomArrayElement">randomArrayElement</a></li><li><a href="global.html#randomIntInclusive">randomIntInclusive</a></li><li><a href="global.html#resetSyncData">resetSyncData</a></li><li><a href="global.html#setNewVoice">setNewVoice</a></li><li><a href="global.html#shouldRenderStory">shouldRenderStory</a></li><li><a href="global.html#simpleRandomHex">simpleRandomHex</a></li><li><a href="global.html#toArrayIfNot">toArrayIfNot</a></li><li><a href="global.html#toDocId">toDocId</a></li><li><a href="global.html#toInteger">toInteger</a></li><li><a href="global.html#toPrecisionNumber">toPrecisionNumber</a></li><li><a href="global.html#updateUserProfile">updateUserProfile</a></li><li><a href="global.html#useBackHandler">useBackHandler</a></li><li><a href="global.html#useConnection">useConnection</a></li><li><a href="global.html#useContentElementFactory">useContentElementFactory</a></li><li><a href="global.html#useDocs">useDocs</a></li><li><a href="global.html#useLogin">useLogin</a></li><li><a href="global.html#validateSettingsSchema">validateSettingsSchema</a></li></ul>
</nav>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Wed Oct 25 2023 09:40:55 GMT+0200 (Central European Summer Time)
</footer>

<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>