Fix: throw on max text length exceeded

FAQ.md

@@ -0,0 +1,139 @@
+# FAQ
+
+> Please read this carefully before opening a new issue.
+
+## Overview
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [How can I use / install different voices?](#how-can-i-use--install-different-voices)
+- [Why does this library exists if I can use TTS natively in the browser?](#why-does-this-library-exists-if-i-can-use-tts-natively-in-the-browser)
+- [Why not using a cloud-based tts service?](#why-not-using-a-cloud-based-tts-service)
+- [Can I include service xyz with this library?](#can-i-include-service-xyz-with-this-library)
+- [Can I load my own / custom trained voices?](#can-i-load-my-own--custom-trained-voices)
+- [My or my users voices sound all terrible, what can I do?](#my-or-my-users-voices-sound-all-terrible-what-can-i-do)
+- [My voices play faster on a Mac M1 than on other machines](#my-voices-play-faster-on-a-mac-m1-than-on-other-machines)
+- [Init failed with "EasySpeech: browser has no voices (timeout)"](#init-failed-with-easyspeech-browser-has-no-voices-timeout)
+- [Error 'EasySpeech: not initialized. Run EasySpeech.init() first'](#error-easyspeech-not-initialized-run-easyspeechinit-first)
+- [Some specific voices are missing, although they are installed on OS-level](#some-specific-voices-are-missing-although-they-are-installed-on-os-level)
+- [My voices are gone or have changed after I updated my OS](#my-voices-are-gone-or-have-changed-after-i-updated-my-os)
+- [Error 'EasySpeech: text exceeds max length of 4096 bytes.'](#error-easyspeech-text-exceeds-max-length-of-4096-bytes)
+- [Safari plays speech delayed after interaction with other audio](#safari-plays-speech-delayed-after-interaction-with-other-audio)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## How can I use / install different voices?
+
+> Note: the following cannot be influenced by this tool or JavaScript in general
+> and requires active measures by the user who wants to different/better voices.
+> This is by design and can only be changed if the Web Speech API standard improves.
+
+- Browser-level: switch to Google Chrome as it delivers a set of Google Voices, which all sound pretty decent
+- OS-level: install new voices, which is an OS-specific procedure
+    - [Windows](https://support.microsoft.com/en-us/topic/download-languages-and-voices-for-immersive-reader-read-mode-and-read-aloud-4c83a8d8-7486-42f7-8e46-2b0fdf753130)
+    - [MacOS](https://support.apple.com/guide/mac-help/change-the-voice-your-mac-uses-to-speak-text-mchlp2290/mac)
+    - [Ubuntu](https://github.com/espeak-ng/espeak-ng/blob/master/docs/mbrola.md#installation-of-standard-packages)
+    - [Android](https://support.google.com/accessibility/android/answer/6006983?hl=en&sjid=9301509494880612166-EU)
+    - [iOS](https://support.apple.com/en-us/HT202362)
+
+Please let me know if the guides are outdated or open a PR with updated links.
+
+## Why does this library exists if I can use TTS natively in the browser?
+
+Every browser vendor implements the [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis)
+differently and there a multiple nuances that make it difficult to provide similar functionality across major browsers.
+
+## Why not using a cloud-based tts service?
+
+Sure you can do that. However, different projects have different requirements.
+If you can't afford a cloud-based service or are prohibited to do so then this
+tool might be something for you.
+
+## Can I include service xyz with this library?
+
+No, it's solely a wrapper for the [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis) "
+standard".
+
+## Can I load my own / custom trained voices?
+
+Unfortunately, no. This is a current limitation of the Web Speech API itself
+and there is nothing we can do about it.
+
+If you want to this to become reality one day, you have to get in contact
+with browser vendors and the [Web Incubator Community Group](https://github.com/WICG/speech-api).
+
+## My or my users voices sound all terrible, what can I do?
+
+Sometimes this is the result of bad settings, like `pitch` and `rate`.
+Please check these value and try to run with explicit values of `1` for both of them.
+
+If this has no effect, then is not an issue of bad pitch/rate. It's very likely that the installed voices
+are simply bad / bad trained or old.
+
+Please read on ["How can I use / install different voices?"](#how-can-i-use--install-different-voices)
+
+## My voices play faster on a Mac M1 than on other machines
+
+This is unfortunately a vendor-specific issue and also supposedly a bug in Safari.
+
+Related issues:
+- https://github.com/jankapunkt/easy-speech/issues/116
+
+## Init failed with "EasySpeech: browser has no voices (timeout)"
+
+This means your browser supports the minimum requirements for speech synthesis,
+but you / your users have no voices installed on your / their system.
+
+Please read on ["How can I use / install different voices?"](#how-can-i-use--install-different-voices)
+
+## Error 'EasySpeech: not initialized. Run EasySpeech.init() first'
+
+This means you haven't run `EasySpeech.init` yet. It's required to set up everything.
+See the [API Docs](./API.md) on how to use it.
+
+## Some specific voices are missing, although they are installed on OS-level
+
+This is something I found on newer iOS versions (16+) to be the case.
+While I have the Siri voice installed, it's not available in the browser.
+This seems to be a vendor-specific issue, so you need to contact your OS vendor (in this case Apple).
+
+## My voices are gone or have changed after I updated my OS
+
+This seems to be a vendor-specific issue, so you need to contact your operating system vendor (Apple, Microsoft).
+
+Related issues:
+- https://github.com/jankapunkt/easy-speech/issues/209
+
+## Error 'EasySpeech: text exceeds max length of 4096 bytes.'
+
+Your text is too long for some voices to process it. You might want to split
+it into smaller chunks and play the next one either by user invocation or
+automatically. A small example:
+
+```js
+let index = 0
+const text = [
+  'This is the first sentence.',
+  'This is the second sentence.',
+]
+
+
+async function playToEnd () {
+  const chunk = text[index++]
+  if (!chunk) { return true } // done
+
+  await EasySpeech.speak({ text: chunk })
+  return playToEnd()
+}
+```
+
+Related issues:
+- https://github.com/jankapunkt/easy-speech/issues/227
+
+## Safari plays speech delayed after interaction with other audio
+
+You can try to speak with `volume=0` before your actual voice is intended to speak.
+
+Related issues:
+- https://github.com/jankapunkt/easy-speech/issues/51

README.md

@@ -20,7 +20,6 @@ Cross browser Speech Synthesis; no dependencies.
 ![npm bundle size](https://img.shields.io/bundlephobia/minzip/easy-speech)
 
 
-
 ## ⭐️ Why EasySpeech?
 
 This project was created, because it's always a struggle to get the synthesis
@@ -41,13 +40,32 @@ part of `Web Speech API` running on most major browsers.
 **Note:** this is not a polyfill package, if your target browser does not  support speech synthesis or the Web Speech
 API, this package is not usable.
 
+
 ## 🚀 Live Demo
 
 The live demo is available at https://jankapunkt.github.io/easy-speech/
 You can use it to test your browser for `speechSynthesis` support and functionality.
 
 [![live demo screenshot](./docs/demo_screenshot.png)](https://jankapunkt.github.io/easy-speech/)
-
+
+## Table of Contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [📦 Installation](#-installation)
+- [👨‍💻 Usage](#-usage)
+  - [🚀 Initialize](#-initialize)
+  - [📢 Speak a voice](#-speak-a-voice)
+  - [😵‍💫 Troubleshooting / FAQ](#-troubleshooting--faq)
+- [🔬 API](#-api)
+- [⌨️ Contribution and development](#-contribution-and-development)
+- [📖 Resources](#-resources)
+- [⚖️ License](#-license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## 📦 Installation
 
 Install from npm via
@@ -115,7 +133,7 @@ If at least `SpeechSynthesis` and `SpeechSynthesisUtterance` are defined you
 are good to go.
 
 
-### Initialize
+### 🚀 Initialize
 
 Preparing everything to work is not as clear as it should, especially when 
 targeting cross-browser functionality. The asynchronous init function will help
@@ -127,7 +145,7 @@ EasySpeech.init({ maxTimeout: 5000, interval: 250 })
     .catch(e => console.error(e))
 ``` 
 
-#### Loading voices
+#### 💽 Loading voices
 
 The init-routine will go through several stages to setup the environment:
 
@@ -156,7 +174,7 @@ Note: This fallback voice is not overridden by `EasySpeech.defaults()`, your
 default voice will be used in favor but the fallback voice will always be there
 in case no voice is found when calling `EasySpeech.speak()`
 
-### Speak a voice
+### 📢 Speak a voice
 
 This is as easy as it gets:
 
@@ -177,6 +195,10 @@ an error occurred. You can additionally attach these event listeners if you like
 or use `EasySpeech.on` to attach default listeners to every time you call 
 `EasySpeech.speak`.
 
+### 😵‍💫 Troubleshooting / FAQ
+
+There is an own [FAQ section](./FAQ.md) available that aims to help with common issues.
+
 ## 🔬 API
 
 There is a full API documentation available: [api docs](./API.md)
@@ -206,6 +228,6 @@ This project used several resources to gain insights about how to get the best c
 - https://bugs.chromium.org/p/chromium/issues/detail?id=582455
 - https://stackoverflow.com/a/65883556
 
-## License
+## ⚖️ License
 
 MIT, see [license file](./LICENSE)

dist/EasySpeech.cjs.js

@@ -682,6 +682,9 @@ EasySpeech.speak = function (_ref3) {
   if (!validate.text(text)) {
     throw new Error('EasySpeech: at least some valid text is required to speak');
   }
+  if (new TextEncoder().encode(text).length > 4096) {
+    throw new Error('EasySpeech: text exceeds max length of 4096 bytes.');
+  }
   var getValue = function getValue(options) {
     var _internal$defaults2;
     var _Object$entries$ = _slicedToArray(Object.entries(options)[0], 2),

dist/EasySpeech.es5.js

@@ -680,6 +680,9 @@ EasySpeech.speak = function (_ref3) {
   if (!validate.text(text)) {
     throw new Error('EasySpeech: at least some valid text is required to speak');
   }
+  if (new TextEncoder().encode(text).length > 4096) {
+    throw new Error('EasySpeech: text exceeds max length of 4096 bytes.');
+  }
   var getValue = function getValue(options) {
     var _internal$defaults2;
     var _Object$entries$ = _slicedToArray(Object.entries(options)[0], 2),

dist/EasySpeech.iife.js

@@ -795,6 +795,9 @@ var EasySpeech = (function () {
     if (!validate.text(text)) {
       throw new Error('EasySpeech: at least some valid text is required to speak');
     }
+    if (new TextEncoder().encode(text).length > 4096) {
+      throw new Error('EasySpeech: text exceeds max length of 4096 bytes.');
+    }
     var getValue = function getValue(options) {
       var _internal$defaults2;
       var _Object$entries$ = _slicedToArray(Object.entries(options)[0], 2),

dist/EasySpeech.js

@@ -645,6 +645,9 @@ EasySpeech.speak = ({ text, voice, pitch, rate, volume, force, infiniteResume, .
   if (!validate.text(text)) {
     throw new Error('EasySpeech: at least some valid text is required to speak')
   }
+  if ((new TextEncoder().encode(text)).length > 4096) {
+    throw new Error('EasySpeech: text exceeds max length of 4096 bytes.')
+  }
 
   const getValue = options => {
     const [name, value] = Object.entries(options)[0];

src/EasySpeech.js

@@ -645,6 +645,9 @@ EasySpeech.speak = ({ text, voice, pitch, rate, volume, force, infiniteResume, .
   if (!validate.text(text)) {
     throw new Error('EasySpeech: at least some valid text is required to speak')
   }
+  if ((new TextEncoder().encode(text)).length > 4096) {
+    throw new Error('EasySpeech: text exceeds max length of 4096 bytes.')
+  }
 
   const getValue = options => {
     const [name, value] = Object.entries(options)[0]

tests/unit.tests.js

@@ -7,6 +7,7 @@ import {
   initScope,
   createUtteranceClass
 } from './test-helpers.js'
+import crypto from 'crypto'
 
 describe('unit tests', function () {
   afterEach(function () {
@@ -510,6 +511,34 @@ describe('unit tests', function () {
           done()
         })
     })
+    it('throws if text exceeds 4096 bytes lengtgh', function (done) {
+      const SpeechSynthesisUtterance = createUtteranceClass()
+
+      const speechSynthesis = {
+        getVoices: () => [{}],
+        speak: function () {
+          done(new Error('should not reach'))
+        },
+        cancel: () => {}
+      }
+      globalThis.SpeechSynthesisUtterance = SpeechSynthesisUtterance
+      globalThis.speechSynthesis = speechSynthesis
+
+      crypto.randomBytes(4096, (err, buf) => {
+        if (err) {
+          return done(err)
+        }
+
+        const text = buf.toString('utf-8')
+        EasySpeech.init()
+          .catch(e => done(e))
+          .then(() => {
+            expect(() => EasySpeech.speak({ text }))
+              .to.throw('EasySpeech: text exceeds max length of 4096 bytes.')
+            done()
+          })
+      })
+    })
     it('speaks, if at least some text is given', function (done) {
       const SpeechSynthesisUtterance = class SpeechSynthesisUtterance {
         constructor (text) {