https://github.com/phetsims/utterance-queue
Alerting library powered by aria-live
https://github.com/phetsims/utterance-queue
scenerystack
Last synced: 4 months ago
JSON representation
Alerting library powered by aria-live
- Host: GitHub
- URL: https://github.com/phetsims/utterance-queue
- Owner: phetsims
- License: mit
- Created: 2019-10-22T18:45:04.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2025-12-17T12:39:31.000Z (6 months ago)
- Last Synced: 2025-12-21T00:58:26.271Z (5 months ago)
- Topics: scenerystack
- Language: TypeScript
- Homepage: http://scenerystack.org/
- Size: 825 KB
- Stars: 1
- Watchers: 4
- Forks: 2
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
utterance-queue
=======================================================
Alerting queue and library powered by aria-live
By PhET Interactive Simulations
https://phet.colorado.edu/
### Documentation
This is under active prototyping, so please expect any sort of API to change. Comments at this stage are very welcome.
#### Dependencies
[Grunt](http://gruntjs.com/) is used to build the source ("npm update -g grunt-cli", "npm update" and "grunt" at the top
level should build into build/). [Node.js](http://nodejs.org/) is required for this process.
Building source code requires the phetsims compiling repository: [chipper](http://github.com/phetsims/chipper/). Once
dependencies are downloaded, source is compiled by running `grunt`.
This library also depends on [lodash](https://lodash.com/). You can find the current checked in dependency for this
library in [sherpa](http://github.com/phetsims/sherpa/lib).
#### Hello World
(to be tested with a screen reader or your AT of choice)
```html
const utteranceQueue = phet.utteranceQueue.UtteranceQueue.fromFactory();
utteranceQueue.addToBack( 'hello world' );
```
`UtteranceQueue.fromFactory()` does a bit of setup work, and is a great place to start with the utterance-queue library.
If you want a bit more control you can setup like this:
```html
Hello
const ariaLiveAnnouncer = new phet.utteranceQueue.AriaLiveAnnouncer();
const utteranceQueue = new phet.utteranceQueue.UtteranceQueue( ariaLiveAnnouncer );
const container = ariaLiveAnnouncer.ariaLiveContainer;
// add the aria-live elements where ever is best
document.body.appendChild( container );
// step phet.axon.stepTimer (in seconds) each frame. This takes care of UtteranceQueue's timing
let previousTime = 0;
const step = elapsedTime => {
const dt = elapsedTime - previousTime;
previousTime = elapsedTime;
phet.axon.stepTimer.emit( dt / 1000 ); // time takes seconds
window.requestAnimationFrame( step );
};
window.requestAnimationFrame( step );
utteranceQueue.addToBack( 'Press the button to hear "hello world".' );
document.getElementById( 'hello-button' ).addEventListener( 'click', () => {
// Now you have a fully operational UtteranceQueue.
utteranceQueue.addToBack( 'hello world' );
} )
```
The [PhET Development Overview](https://github.com/phetsims/phet-info/blob/main/doc/phet-development-overview.md) is the
most complete guide to PhET Simulation Development. This guide includes how to obtain simulation code and its
dependencies, notes about architecture & design, how to test and build the sims, as well as other important information.
### License
See the [license](LICENSE)