use-read-aloud 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Siva Murugan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# use-read-aloud
+
+A lightweight React hook that adds text-to-speech (read aloud) functionality using the Web Speech API.
+
+This hook is designed for blogs, articles, and reading-focused applications.
+
+## Installation
+
+```bash
+npm install use-read-aloud
+```
+
+## Peer dependency
+
+- react >= 18
+
+## Usage
+
+```tsx
+import { useReadAloud } from "use-read-aloud";
+
+function AudioPlayer({ text }: { text: string }) {
+  const { isReading, isPaused, toggle, start, reset } = useReadAloud(
+    () => text,
+    { rate: 1 }
+  );
+
+  return (
+    <div>
+      <button onClick={toggle}>
+        {isReading && !isPaused ? "Pause" : "Play"}
+      </button>
+
+      {isReading && <button onClick={start}>Restart</button>}
+      <button onClick={reset}>Stop</button>
+    </div>
+  );
+}
+```
+
+## API
+
+```
+useReadAloud(getText, options?)
+```
+
+### Parameters
+
+- getText - A function that returns the text to read.
+
+- options
+
+```ts
+type Options = {
+  rate?: number; // default: 1
+  pitch?: number; // default: 1
+};
+```
+
+### Returns
+
+```ts
+{
+  isReading: boolean;
+  isPaused: boolean;
+  start: () => void;
+  toggle: () => void;
+  reset: () => void;
+}
+```
+
+## Behavior
+
+- Long text is automatically split into smaller chunks for reliability
+
+- Speech is cancelled automatically when the component unmounts
+
+- Pause and resume are handled safely using internal session tracking
+
+## Browser support
+
+This hook uses the Web Speech API.
+
+Supported:
+
+- Chrome
+
+- Edge
+
+- Safari
+
+Not supported:
+
+- Firefox
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { useReadAloud } from "./useReadAloud";
+export type { Options } from "./useReadAloud";

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

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

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

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

package/dist/useReadAloud.d.ts

@@ -0,0 +1,13 @@
+export type Options = {
+    rate?: number;
+    pitch?: number;
+};
+export declare function useReadAloud(getText: () => string, options?: Options): {
+    isReading: boolean;
+    isPaused: boolean;
+    start: () => void;
+    reset: () => void;
+    pause: () => void;
+    resume: () => void;
+    toggle: () => void;
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "use-read-aloud",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A React hook for reading text aloud using the Web Speech API",
+  "author": "Siva Murugan",
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "react-hook",
+    "text-to-speech",
+    "speech-synthesis",
+    "read-aloud",
+    "web-speech-api"
+  ],
+  "main": "./dist/use-read-aloud.cjs.js",
+  "module": "./dist/use-read-aloud.es.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "types": "tsc --emitDeclarationOnly",
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "lint": "eslint ."
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SivaMurugan17/use-read-aloud.git"
+  }
+}