use-read-aloud 1.0.1 → 1.0.2

package/README.md

@@ -1,8 +1,15 @@
 # use-read-aloud
 
-A lightweight React hook that adds text-to-speech (read aloud) functionality using the Web Speech API.
+A lightweight React hook for reliable text-to-speech (read aloud) in the browser. Designed for long-form content like blogs and articles using the Web Speech API.
 
-This hook is designed for blogs, articles, and reading-focused applications.
+This hook is designed to work around common Web Speech API issues such as:
+
+- Random failures when reading long text
+- Unreliable behavior when resuming after long pauses
+- Missing controls like fast-forward, rewind, etc.
+
+> Note : This works fully on the client side using the browser’s built-in text-to-speech engines.
+> No external APIs or dependencies are required.
 
 ## Installation
 
@@ -10,60 +17,26 @@ This hook is designed for blogs, articles, and reading-focused applications.
 npm install use-read-aloud
 ```
 
-## Peer dependency
-
-- react >= 18
-
 ## Usage
 
 ```tsx
 import { useReadAloud } from "use-read-aloud";
-import { useState } from "react";
-import {
-  FastForward,
-  Minus,
-  Pause,
-  Play,
-  Plus,
-  Rewind,
-  RotateCcw,
-  Volume2,
-} from "lucide-react";
-
-function AudioPlayer({ text }: { text: string }) {
-  const [playBackSpeed, setPlayBackSpeed] = useState<number>(1);
 
-  const { isPaused, togglePlay, fastForward, seekBackward, replay } =
-    useReadAloud(text, {
-      rate: playBackSpeed,
-    });
+function AudioPlayer() {
+  const { isPaused, togglePlay } = useReadAloud("Text to be read");
 
   return (
-    <div>
-      <button onClick={seekBackward}>
-        <Rewind />
-      </button>
-      <button onClick={togglePlay}>{isPaused ? <Play /> : <Pause />}</button>
-      <button onClick={fastForward}>
-        <FastForward />
-      </button>
-      <button onClick={replay}>
-        <RotateCcw />
-      </button>
-      <span>
-        <button onClick={() => setPlayBackSpeed(playBackSpeed - 0.25)}>
-          <Minus />
-        </button>
-        {`${playBackSpeed}x`}
-        <button onClick={() => setPlayBackSpeed(playBackSpeed + 0.25)}>
-          <Plus />
-        </button>
-      </span>
-    </div>
+    <>
+      <button onClick={togglePlay}>{isPaused ? "Play" : "Pause"}</button>
+    </>
   );
 }
 ```
 
+## Demo
+
+A live demo can be found in [this blog](https://pragmaticswe.com/post/escaping-the-new-year-resolutions-matrix), which uses this library under the hood.
+
 ## API
 
 ```
@@ -72,9 +45,9 @@ useReadAloud(text, options?)
 
 ### Parameters
 
-- text - the text to be read.
+- text - the text to be read
 
-- options - options to specify rate and pitch of the speech
+- options - additional options to change the rate and pitch of the speech
 
 ```ts
 type Options = {
@@ -97,17 +70,86 @@ type Options = {
 }
 ```
 
+## Examples
+
+1. Fast forward / seek backward
+
+```tsx
+import { useReadAloud } from "use-read-aloud";
+
+function AudioPlayer() {
+  const { isPaused, togglePlay, fastForward, seekBackward } =
+    useReadAloud("Text to be read");
+
+  return (
+    <>
+      <button onClick={seekBackward}>Rewind</button>
+      <button onClick={togglePlay}>{isPaused ? "Play" : "Pause"}</button>
+      <button onClick={fastForward}>FastForward</button>
+    </>
+  );
+}
+```
+
+2. Speed up / slow down
+
+```tsx
+import { useReadAloud } from "use-read-aloud";
+import { useState } from "react";
+
+function AudioPlayer() {
+  const [playBackSpeed, setPlayBackSpeed] = useState<number>(1);
+
+  const { isPaused, togglePlay } = useReadAloud("Text to be read", {
+    rate: playBackSpeed,
+  });
+
+  return (
+    <>
+      <button onClick={togglePlay}>{isPaused ? "Play" : "Pause"}</button>
+      <span>
+        <button onClick={() => setPlayBackSpeed(playBackSpeed - 0.25)}>
+          Minus
+        </button>
+        {`${playBackSpeed}x`}
+        <button onClick={() => setPlayBackSpeed(playBackSpeed + 0.25)}>
+          Plus
+        </button>
+      </span>
+    </>
+  );
+}
+```
+
+3. Replay from the start
+
+```tsx
+import { useReadAloud } from "use-read-aloud";
+
+function AudioPlayer() {
+  const { isPaused, togglePlay, replay } = useReadAloud("Text to be read");
+
+  return (
+    <>
+      <button onClick={togglePlay}>{isPaused ? "Play" : "Pause"}</button>
+      <button onClick={replay}>Replay</button>
+    </>
+  );
+}
+```
+
 ## Behavior
 
-- Long text is automatically split into smaller chunks for reliability
+- Long text is automatically split into smaller chunks of sentences for reliability.
+- A workaround is used as a replacement for the inconsistent `speechSynthesis.resume()` function. (This may restart the current sentence, which is generally acceptable and far more reliable.)
 
-- Speech is cancelled automatically when the component unmounts
+## Peer dependency
 
-- Pause and resume are handled safely using internal session tracking
+- react >= 18
 
 ## Browser support
 
-This hook uses the Web Speech API.
+This hook uses the browser built-in Web Speech API, which is supported by most modern browsers. But, the voice quality varies by browser.
 
 Supported:
 
@@ -119,7 +161,7 @@ Supported:
 
 Not supported:
 
-- Firefox
+- Firefox (does not support the Web Speech API)
 
 ## Changelog
 

package/dist/use-read-aloud.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("react"),m=220;function P(a){const l=[];let t="";for(const c of a.split("."))(t+c+".").length>m?(l.push(t.trim()),t=c+"."):t+=c+".";return t.trim()&&l.push(t.trim()),l}function A(a,l={}){const{rate:t=1,pitch:c=1}=l,[k,h]=e.useState(!0),u=e.useRef(!0),i=e.useRef([]),r=e.useRef(0),b=e.useCallback(()=>{i.current=[],r.current=0},[]),d=e.useCallback(()=>{if(!a.trim())return;const n=a.split(/\n+/).map(g=>g.trim()).filter(Boolean);i.current=n.flatMap(P),r.current=0},[a]),o=e.useCallback(()=>{u.current=!0,h(!0)},[]),f=e.useCallback(()=>{speechSynthesis.cancel(),b(),o()},[b,o]),p=e.useCallback(()=>{if(r.current>=i.current.length){o();return}const n=new SpeechSynthesisUtterance(i.current[r.current]);n.rate=t,n.pitch=c,speechSynthesis.speak(n),n.onend=()=>{r.current+=1,p()},n.onerror=()=>{}},[o,c,t]),C=e.useCallback(()=>{h(!0),u.current=!0,speechSynthesis.pause()},[]),s=e.useCallback(()=>{h(!1),u.current=!1,i.current.length===0&&d(),speechSynthesis.cancel(),p()},[p,d]),y=e.useCallback(()=>{f(),s()},[f,s]),S=e.useCallback(()=>{r.current=Math.max(r.current-1,0),u.current||s()},[s]),R=e.useCallback(()=>{r.current=r.current+1,u.current||s()},[s]);return e.useEffect(()=>{u.current?speechSynthesis.cancel():s()},[t,s]),e.useEffect(()=>()=>f(),[f]),{isPaused:k,play:s,pause:C,replay:y,seekBackward:S,fastForward:R,togglePlay:k?s:C}}exports.useReadAloud=A;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("react"),R=220;function M(l){const i=[];let t="";for(const c of l.split("."))(t+c+".").length>R?(i.push(t.trim()),t=c+"."):t+=c+".";return t.trim()&&i.push(t.trim()),i}function P(l,i={}){const{rate:t=1,pitch:c=1}=i,[k,h]=e.useState(!0),u=e.useRef(!0),a=e.useRef([]),r=e.useRef(0),b=e.useCallback(()=>{a.current=[],r.current=0},[]),d=e.useCallback(()=>{if(!l.trim())return;const n=l.split(/\n+/).map(m=>m.trim()).filter(Boolean);a.current=n.flatMap(M),r.current=0},[l]),o=e.useCallback(()=>{u.current=!0,h(!0),r.current=0},[]),f=e.useCallback(()=>{speechSynthesis.cancel(),b(),o()},[b,o]),p=e.useCallback(()=>{if(r.current>=a.current.length){o();return}const n=new SpeechSynthesisUtterance(a.current[r.current]);n.rate=t,n.pitch=c,speechSynthesis.speak(n),n.onend=()=>{r.current+=1,p()},n.onerror=()=>{}},[o,c,t]),C=e.useCallback(()=>{h(!0),u.current=!0,speechSynthesis.pause()},[]),s=e.useCallback(()=>{h(!1),u.current=!1,a.current.length===0&&d(),speechSynthesis.cancel(),p()},[p,d]),y=e.useCallback(()=>{f(),s()},[f,s]),S=e.useCallback(()=>{r.current=Math.max(r.current-1,0),u.current||s()},[s]),g=e.useCallback(()=>{r.current=Math.min(r.current+1,a.current.length-1),u.current||s()},[s]);return e.useEffect(()=>{u.current?speechSynthesis.cancel():s()},[t,s]),e.useEffect(()=>()=>f(),[f]),{isPaused:k,play:s,pause:C,replay:y,seekBackward:S,fastForward:g,togglePlay:k?s:C}}exports.useReadAloud=P;

package/dist/use-read-aloud.es.js

@@ -1,57 +1,60 @@
-import { useState as A, useRef as d, useCallback as r, useEffect as g } from "react";
-const M = 220;
-function b(a) {
-  const i = [];
+import { useState as w, useRef as m, useCallback as n, useEffect as g } from "react";
+const A = 220;
+function b(i) {
+  const o = [];
   let e = "";
-  for (const c of a.split("."))
-    (e + c + ".").length > M ? (i.push(e.trim()), e = c + ".") : e += c + ".";
-  return e.trim() && i.push(e.trim()), i;
+  for (const c of i.split("."))
+    (e + c + ".").length > A ? (o.push(e.trim()), e = c + ".") : e += c + ".";
+  return e.trim() && o.push(e.trim()), o;
 }
-function I(a, i = {}) {
-  const { rate: e = 1, pitch: c = 1 } = i, [m, l] = A(!0), u = d(!0), o = d([]), n = d(0), y = r(() => {
-    o.current = [], n.current = 0;
-  }, []), S = r(() => {
-    if (!a.trim())
+function I(i, o = {}) {
+  const { rate: e = 1, pitch: c = 1 } = o, [d, l] = w(!0), u = m(!0), a = m([]), t = m(0), y = n(() => {
+    a.current = [], t.current = 0;
+  }, []), S = n(() => {
+    if (!i.trim())
       return;
-    const s = a.split(/\n+/).map((w) => w.trim()).filter(Boolean);
-    o.current = s.flatMap(b), n.current = 0;
-  }, [a]), f = r(() => {
-    u.current = !0, l(!0);
-  }, []), h = r(() => {
+    const s = i.split(/\n+/).map((P) => P.trim()).filter(Boolean);
+    a.current = s.flatMap(b), t.current = 0;
+  }, [i]), f = n(() => {
+    u.current = !0, l(!0), t.current = 0;
+  }, []), h = n(() => {
     speechSynthesis.cancel(), y(), f();
-  }, [y, f]), p = r(() => {
-    if (n.current >= o.current.length) {
+  }, [y, f]), p = n(() => {
+    if (t.current >= a.current.length) {
       f();
       return;
     }
     const s = new SpeechSynthesisUtterance(
-      o.current[n.current]
+      a.current[t.current]
     );
     s.rate = e, s.pitch = c, speechSynthesis.speak(s), s.onend = () => {
-      n.current += 1, p();
+      t.current += 1, p();
     }, s.onerror = () => {
     };
-  }, [f, c, e]), k = r(() => {
+  }, [f, c, e]), k = n(() => {
     l(!0), u.current = !0, speechSynthesis.pause();
-  }, []), t = r(() => {
-    l(!1), u.current = !1, o.current.length === 0 && S(), speechSynthesis.cancel(), p();
-  }, [p, S]), R = r(() => {
-    h(), t();
-  }, [h, t]), C = r(() => {
-    n.current = Math.max(n.current - 1, 0), u.current || t();
-  }, [t]), P = r(() => {
-    n.current = n.current + 1, u.current || t();
-  }, [t]);
+  }, []), r = n(() => {
+    l(!1), u.current = !1, a.current.length === 0 && S(), speechSynthesis.cancel(), p();
+  }, [p, S]), R = n(() => {
+    h(), r();
+  }, [h, r]), C = n(() => {
+    t.current = Math.max(t.current - 1, 0), u.current || r();
+  }, [r]), M = n(() => {
+    t.current = Math.min(
+      t.current + 1,
+      a.current.length - 1
+    ), u.current || r();
+  }, [r]);
   return g(() => {
-    u.current ? speechSynthesis.cancel() : t();
-  }, [e, t]), g(() => () => h(), [h]), {
-    isPaused: m,
-    play: t,
+    u.current ? speechSynthesis.cancel() : r();
+  }, [e, r]), g(() => () => h(), [h]), {
+    isPaused: d,
+    play: r,
     pause: k,
     replay: R,
     seekBackward: C,
-    fastForward: P,
-    togglePlay: m ? t : k
+    fastForward: M,
+    togglePlay: d ? r : k
   };
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-read-aloud",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "description": "A React hook for reading text aloud using the Web Speech API",
   "author": "Siva Murugan",
@@ -9,6 +9,7 @@
     "react",
     "react-hook",
     "text-to-speech",
+    "tts",
     "speech-synthesis",
     "read-aloud",
     "web-speech-api"