Read Aloud Client

Multi-vendor Text-To-Speech client for TAO.

-

Installation

npm i @oat-sa/read-aloud-client

Usage

import getReadAloudClient from '@oat-sa/read-aloud-client';

getReadAloudClient('native', {})
    .then(client => {
        client.ignoreElements('.do-not-read');

        client.playSelection();
    })
    .catch(err => window.console.error(err));

Client API

Main methods, available in all providers:

• play(HTMLElement: element) : Starts reading from the given element.
• playSelection() : Starts reading the selected text.
• stop() : Stops any ongoing plays.
• destroy(): Destroy provider

Optional methods that may not be implemented by every provider:

• pause() : Pauses ongoing playing (resumable).
• resume() : Resumes current paused playing.
• boolean: isReading() : Returns true if any reading is ongoing.
• onReadStart(function: handler) : calls back the handler when reading starts
• onReadEnd(function: handler) : calls back the handler when reading ends
• boolean: toggleClickToSpeak() : Toggles the state of a "click-to-speak" mode, if supported.
• setPreferences( { string: speed, string: pitch, string: volume, string: voice }) : Change the reading preferences. See the [available values for the preferences].(./lib/preferences.js).
• ignoreElements(string: selector) : do not read the elements matching the given DOM selector.
• getSupport() : Returns the structure with configuration options available for provider

Supported Providers

Native

| | | | ------------- | ----------------------------------------------------------- | | id | native | | support level | experimental | | availability | native, browser/OS based | | browsers | Firefox Desktop and Chrome Desktop & Android (not Chromium) | | i18n modes | detect from DOM |

Readweb

| | | | ------------- | -------------------------------------------------------------- | | id | readweb | | support level | testing | | availability | licensed per domain | | browsers | all | | i18n modes | detect from DOM | | configuration | - url: the service base url - license: the license key | | prerequisite | configure it through the ReadWeb Control Panel |

TextHelp

| | | | ------------- | ----------------------------------------------------------------------------------- | | id | texthelp | | support level | testing | | availability | licensed per domain | | browsers | all | | i18n modes | detect from DOM, configuration override | | configuration | - url: the service base url - speechStreamConfig: name of the remote config | | prerequisite | remote script & configuration file set up on TextHelp's servers |

Development

The project should be run with Node >= 18 and npm >= 9.

Clone the repository and install it:

git clone https://github.com/oat-sa/read-aloud-client-fe
cd read-aloud-client-fe
npm ci

Sandbox

A sandbox is available to test the client.

First generate some SSL certificates:

mkcert -install
cd keys
mkcert -cert-file localhost-cert.pem -key-file localhost-key.pem localhost 127.0.0.1 ::1

Run the sandbox:

npm run dev:sandbox

Add a new provider

A provider is an async factory function that resolves with the implementation. A minimal provider looks like:

export default function fancyProvider(config = {}) {
    return Promise.resolve({
        play(element) {},

        playSelection() {},

        stop() {},

        destroy() {}
    });
}

All optional methods can be added too.

Then the provider must be exported in lib/providers/index.js:

export { default as fancy } from './pathToFancy.js';

Please note the export named will be used as provider id (fancy in the example).

Tests

Run the test suite

npm run test

With coverage

npm run test:cov

During the development, jest can be called directly:

npx jest --watch

License

Copyright (c) 2021-2026 Open Assessment Technologies SA

Licensed under the terms of the GNU GPL v2