React Readalong Component
2 |
3 | [](LICENSE)
4 | [](https://www.npmjs.com/package/react-readalong-component)
5 | [](bower.json)
6 | [](https://david-dm.org/TalkingBibles/react-readalong-component)
7 |
8 |
9 | A React component that uses the Speech Synthesis API to read text out loud by sentence or word while the user follows
10 | along with their mouse or finger
11 |
12 |
13 | ## Demo & Examples
14 |
15 | Live demo: [Github Pages](http://talkingbibles.github.io/react-readalong-component/)
16 |
17 | To build the examples locally, run:
18 |
19 | ```
20 | npm install
21 | gulp dev
22 | ```
23 |
24 | Then open [`localhost:8000`](http://localhost:8000) in a browser.
25 |
26 |
27 | ## Installation
28 |
29 | The easiest way to use Readalong is to install it from NPM and include it in your own React build process (using
30 | [Browserify](http://browserify.org), [Webpack](http://webpack.github.io/), etc).
31 |
32 | You can also use the standalone build by including `dist/react-readalong-component.js` in your page. If you use this,
33 | make sure you have already included React, and it is available as a global variable.
34 |
35 | ```
36 | npm install react-readalong-component --save
37 | ```
38 |
39 | ## Usage
40 |
41 | The component provides a single element, `Readalong`, that takes three properties and some text content. The properties
42 | of `lang` and `delimiter` can be provided as attributes, while `voiceName` should be passed after the browser registers
43 | the available Speech Synthesis voices. The browser will use its default voice until a valid, different voice is passed.
44 | The component will attempt to choose a default voice based on the passed `lang` property, but this is hit-or-miss.
45 |
46 | 48 |59 |This sentence has five words. Here are five more words. Five-word sentences are fine. But several together 49 | become monotonous. Listen to what is happening. The writing is getting boring. The sound of it drones. It’s 50 | like a stuck record. The ear demands some variety. Now listen. I vary the sentence length, and I create 51 | music. Music. The writing sings. It has a pleasant rhythm, a lilt, a harmony. I use short sentences. And I 52 | use sentences of medium length. And sometimes, when I am certain the reader is rested, I will engage him 53 | with a sentence of considerable length, a sentence that burns with energy and builds with all the impetus of 54 | a crescendo, the roll of the drums, the crash of the cymbals–sounds that say listen to this, it is 55 | important.
56 | 57 | 58 |
In the beginning was the Word, and the Word was 65 | with God, and the Word was God. The same was in 66 | the beginning with God. All things were made 67 | through him. Without him, nothing was made that has been made. 68 | In him was life, and the life was the light of 69 | men. The light shines in the darkness, and the 70 | darkness hasn’t overcome it.
71 | 72 |There came a man, 73 | sent from God, whose name was John. The same came 74 | as a witness, that he might testify about the light, that all might 75 | believe through him. He was not the light, but was 76 | sent that he might testify about the light. The 77 | true light that enlightens everyone was coming into the world.
78 | 79 | 80 |111 | 1太 初 有 道 ， 道 与 神 同 在 ， 道 就 是 神 。 112 | 2这 道 太 初 与 神 同 在 。 3万 物 是 113 | 藉 着 他 造 的 ； 凡 被 造 的 ， 没 有 一 样 不 是 藉 着 他 造 的 。 114 | 4生 命 在 他 里 头 ， 这 生 命 就 是 人 的 光 。 115 | 5光 照 在 黑 暗 里 ， 黑 暗 却 不 接 受 光 。 116 | 6有 一 个 人 ， 是 从 神 那 里 差 来 的 ， 名 叫 约 翰 。 117 | 7这 人 来 ， 为 要 作 见 证 ， 就 是 为 光 作 见 证 ， 118 | 叫 众 人 因 他 可 以 信 。 8他 不 是 那 光 ， 乃 是 要 119 | 为 光 作 见 证 。 9那 光 是 真 光 ， 照 亮 一 切 生 120 | 在 世 上 的 人 。 121 |
122 |44 | A React component that uses the Speech Synthesis API to read text out loud by sentence or word 45 | while the user follows along with their mouse or finger 46 |
47 | 48 |49 | Github 51 | Talking Bibles 53 |
54 |63 | The easiest way to use Readalong is to install it from NPM and include it in your own React build process (using 64 | Browserify, Webpack, etc). 65 |
66 | 67 |68 | You can also use the standalone build by including dist/react-readalong-component.js in your page. 69 | If you use this, make sure you have already included React, and it is available as a global variable. 70 |
71 | 72 |
73 | npm install react-readalong-component --save
74 |
79 | The component provides a single React element, Readalong, that takes three properties and some text
80 | content. The properties of lang and delimiter can be provided as attributes. The property
81 | voiceName should be passed after the browser registers the available Speech Synthesis voices. The
82 | browser will use its default voice until a valid, different voice is passed. The component will attempt to choose a
83 | default voice based on the passed lang property, but this is hit-or-miss.
84 |
87 | The output of the component receives three classes for use with styling. The outer wrapper has the class,
88 | readalong. Every readable phrase is wrapped in a span with the readalong-phrase class.
89 | While a phrase is being spoken, the corresponding span also receives a readalong-active class. This
90 | can be used, as in the examples below, to keep the phrase highlighted after the user moves off or releases her
91 | finger.
92 |
95 | It is advisable to make the font size as large as possible for the contents of a Readalong element. This is
96 | especially true if the delimiter is set to word.
97 |
102 | This component depends on two experimental, draft APIs: Pointer 103 | Events and Speech Synthesis. 104 |
105 | 106 |107 | As of July 12, 2015, the Web Speech API is still an unofficial proposal. As such, right out 108 | of the box this component will only work in about half of all browsers. Those include recent versions of Chrome, 109 | Opera, and Safari. Ostensibly, iOS Safari is supported, but Speech Synthesis seems to work in that browser only 110 | sporadically. All other browsers will need a polyfill. There is no polyfill for Speech Synthesis currently 111 | installed on this demonstration page. 112 |
113 | 114 |115 | Again, as of the time of this commit, the Pointer Events API is very poorly supported across all browsers. Only 116 | IE and very late version Firefox have implemented it. There's no getting away without a polyfill for Pointer 117 | Events. They power the cursor/finger recognition. Fortunately, Google/jQuery have put together a fantastic 118 | polyfill called PEP, which is providing cross-browser capability for 119 | this page. It does not require jQuery as a dependency. 120 |
121 | 122 |
123 | This component intentionally does not include polyfills. There are many polyfill options, and the one you choose
124 | will depend on the needs of your project. The component also intentionally does check whether the Speech Synthesis
125 | API is available. Readalong assumes that both window.speechSynthesis and the
126 | SpeechSynthesisUtterance object are available, and that they are up-to-date with the unofficial
127 | proposal.
128 |
133 | The constants, regular expressions, and punctuation encoding used in this project were originally lifted from 134 | Blast.js, built by Julian Shapiro. These have been modified 135 | to fit the particular requirements of this project, including the addition of the Chinese punctuation. 136 |
137 | 138 |
148 | This delimiter and voice selection form that is shown in some of the following examples is not
149 | included in the Readalong component. Consult the DelimitedParagraph component in the
150 | examples directory for ideas about implementing something similar in your app.
151 |
156 | Hover over or tap any word to hear it read out loud by your browser. The speech will continue even if the user 157 | moves away or releases her finger. 158 |
159 | 160 |
166 | <Readalong lang="en-US" delimiter="word">
167 | There once was an old woman who lived in a shoe.
168 | She was underwater on her mortgage. What would she do?
169 | </Readalong>
170 | Readalong will ignore any text wrapped in an element with the silent attribute.
182 | <Readalong lang="en-US" delimiter="word">
183 | <blockquote>
184 | <p>
185 | This sentence has five words. Here are five more words. Five-
186 | word sentences are fine. But several together become monotonous.
187 | Listen to what is happening. The writing is getting boring. The
188 | sound of it drones. It’s like a stuck record. The ear
189 | demands some variety. Now listen. I vary the sentence length,
190 | and I create music. Music. The writing sings. It has a pleasant
191 | rhythm, a lilt, a harmony. I use short sentences. And I use
192 | sentences of medium length. And sometimes, when I am certain the
193 | reader is rested, I will engage him with a sentence of
194 | considerable length, a sentence that burns with energy and
195 | builds with all the impetus of a crescendo, the roll of the
196 | drums, the crash of the cymbals–sounds that say listen to
197 | this, it is important.
198 | </p>
199 |
200 | <footer silent><cite>Gary Provost</cite></footer>
201 | </blockquote>
202 | </Readalong>
203 | 209 | Readalong can process multiple blocks of text in the same component. Attributes on those inner elements will be 210 | passed through to the final output. 211 |
212 | 213 |
219 | <Readalong lang="en-US" delimiter="word">
220 | <p>
221 | <span data-verse="1">In the beginning was the Word, and the
222 | Word was with God, and the Word was God.</span> <span data-
223 | <verse="2">The same was in the beginning with God.</span>
224 | <span data-verse="3">All things were made through him.
225 | Without him, nothing was made that has been made.</span>
226 | <span data-verse="4">In him was life, and the life was the
227 | light of men.</span> <span data-verse="5">The light shines in
228 | the darkness, and the darkness hasn’t overcome it.</span>
229 | </p>
230 |
231 | <p>
232 | <span data-verse="6">There came a man, sent from God, whose
233 | name was John.</span> <span data-verse="7">The same came as
234 | a witness, that he might testify about the light, that all
235 | might believe through him.</span> <span data-verse="8">He was
236 | not the light, but was sent that he might testify about the
237 | light.</span> <span data-verse="9">The true light that
238 | enlightens everyone was coming into the world.</span>
239 | </p>
240 | </Readalong>
241 | Readalong supports any language that uses European or Chinese punctuation marks and is also supported 247 | by the browser's Speech Synthesis API.
248 | 249 |
257 | <Readalong lang="es" delimiter="sentence">
258 | <p>
259 | En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
260 | no ha mucho tiempo que vivía un hidalgo de los de lanza en
261 | astillero, adarga antigua, rocín flaco y galgo corredor. Una
262 | olla de algo más vaca que carnero, salpicón las más noches,
263 | duelos y quebrantos los sábados, lentejas los viernes, algún
264 | palomino de añadidura los domingos, consumían las tres partes
265 | de su hacienda. El resto della concluían sayo de velarte,
266 | calzas de velludo para las fiestas con sus pantuflos de lo
267 | mismo, los días de entre semana se honraba con su vellori de
268 | lo más fino. Tenía en su casa una ama que pasaba de los
269 | cuarenta, y una sobrina que no llegaba a los veinte, y un mozo
270 | de campo y plaza, que así ensillaba el rocín como tomaba la
271 | podadera. Frisaba la edad de nuestro hidalgo con los cincuenta
272 | años, era de complexión recia, seco de carnes, enjuto de
273 | rostro; gran madrugador y amigo de la caza. Quieren decir que
274 | tenía el sobrenombre de Quijada o Quesada (que en esto hay
275 | alguna diferencia en los autores que deste caso escriben),
276 | aunque por conjeturas verosímiles se deja entender que se
277 | llama Quijana; pero esto importa poco a nuestro cuento; basta
278 | que en la narración dél no se salga un punto de la verdad.
279 | </p>
280 | </Readalong>
281 |
290 | <Readalong lang="es" delimiter="sentence">
291 | <p>
292 | <i silent>1</i>太 初 有 道 ， 道 与 神 同 在 ， 道 就 是 神 。
293 | <i silent>2</i>这 道 太 初 与 神 同 在 。 <i silent>3</i>万 物 是
294 | 藉 着 他 造 的 ； 凡 被 造 的 ， 没 有 一 样 不 是 藉 着 他 造 的 。
295 | <i silent>4</i>生 命 在 他 里 头 ， 这 生 命 就 是 人 的 光 。
296 | <i silent>5</i>光 照 在 黑 暗 里 ， 黑 暗 却 不 接 受 光 。
297 | <i silent>6</i>有 一 个 人 ， 是 从 神 那 里 差 来 的 ， 名 叫 约 翰 。
298 | <i silent>7</i>这 人 来 ， 为 要 作 见 证 ， 就 是 为 光 作 见 证 ，
299 | 叫 众 人 因 他 可 以 信 。 <i silent>8</i>他 不 是 那 光 ， 乃 是 要
300 | 为 光 作 见 证 。 <i silent>9</i>那 光 是 真 光 ， 照 亮 一 切 生
301 | 在 世 上 的 人 。
302 | </p>
303 | </Readalong>
304 |