bloom-player 2.22.0 → 2.23.0-alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +157 -57
- package/dist/{bloomPlayer.aSwt1opT.js → bloomPlayer.COPDbsaZ.js} +22 -22
- package/dist/bloomplayer.htm +1 -1
- package/lib/narration.d.ts +4 -0
- package/lib/shared.es.js +1663 -1620
- package/lib/shared.es.js.map +1 -1
- package/package.json +1 -1
- package/src/shared/dragActivityRuntime.ts +82 -17
- package/src/shared/narration.ts +74 -0
package/README.md
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# bloom-player
|
|
2
|
+
|
|
3
|
+
[](https://deepwiki.com/bloombooks/bloom-player)
|
|
2
4
|
|
|
3
5
|
This project, _bloom-player_, lets users view and interact with [Bloom](https://bloomlibrary.org) books in any browser.
|
|
4
6
|
|
|
5
7
|
The Bloom project uses _bloom-player_ in the following places:
|
|
6
8
|
|
|
7
|
-
- In [Bloom Editor](https://github.com/bloombooks/bloomdesktop)
|
|
9
|
+
- In [Bloom Editor](https://github.com/bloombooks/bloomdesktop), on the Publish tab, for previewing what the book will look like on a device.
|
|
8
10
|
- In the [Bloom Reader](https://github.com/bloombooks/bloomreader) Android app
|
|
9
11
|
- On [BloomLibrary.org](https://bloomlibrary.org)
|
|
10
12
|
- In [BloomPUB Viewer](https://github.com/bloombooks/bloompub-viewer)
|
|
@@ -20,31 +22,41 @@ So to embed a book in your website, you just need an iframe element that points
|
|
|
20
22
|
|
|
21
23
|
```html
|
|
22
24
|
<iframe
|
|
23
|
-
src="https://bloomlibrary.org/bloom-player/bloomplayer.htm?url=
|
|
25
|
+
src="https://bloomlibrary.org/bloom-player/bloomplayer.htm?url=https%3A%2F%2Fexample.org%2Fbooks%2Fmy-book%2Findex.htm"
|
|
26
|
+
allow="autoplay; fullscreen"
|
|
27
|
+
style="width: 100%; height: 600px; border: none"
|
|
24
28
|
></iframe>
|
|
25
29
|
```
|
|
26
30
|
|
|
27
|
-
|
|
31
|
+
The player grows to fill the iframe, so give the iframe a size; otherwise the browser makes it 300×150 pixels.
|
|
32
|
+
|
|
33
|
+
The `allow` attribute lets the book play narration without a click first (where the browser permits it) and lets the user switch to full screen.
|
|
28
34
|
|
|
29
|
-
|
|
35
|
+
The `url` parameter is the absolute http(s) URL of the book's HTML file, URL-encoded with `encodeURIComponent`. The file name must end in `.htm` (not `.html`); a URL that doesn't is treated as a folder. So the `url` can instead be the URL of the book's folder, if the HTML file in it has the folder's name plus `.htm`. A relative URL is resolved against the root of the player's origin (e.g. `https://bloomlibrary.org/`), not against your page or the player's folder. If the book is not on the same origin as the player, its server must send CORS headers that allow it. See [README-advanced.md](README-advanced.md) for more on folder URLs and CORS.
|
|
30
36
|
|
|
31
|
-
|
|
37
|
+
## Optional parameters
|
|
38
|
+
|
|
39
|
+
You can customize some aspects of the bloom-player to fit your context. For example, if you never want to show the [app bar](https://m2.material.io/components/app-bars-top), use:
|
|
32
40
|
|
|
33
41
|
```html
|
|
34
42
|
<iframe
|
|
35
|
-
src="https://bloomlibrary.org/bloom-player/bloomplayer.htm?url=
|
|
43
|
+
src="https://bloomlibrary.org/bloom-player/bloomplayer.htm?url=https%3A%2F%2Fexample.org%2Fbooks%2Fmy-book%2Findex.htm&initiallyShowAppBar=false&allowToggleAppBar=false"
|
|
44
|
+
allow="autoplay; fullscreen"
|
|
45
|
+
style="width: 100%; height: 600px; border: none"
|
|
36
46
|
></iframe>
|
|
37
47
|
```
|
|
38
48
|
|
|
39
|
-
|
|
49
|
+
Boolean parameters are true only when set to `true` (in any case). Anything else, such as `1` or `yes`, counts as false.
|
|
50
|
+
|
|
51
|
+
### initiallyShowAppBar
|
|
40
52
|
|
|
41
|
-
Show the [app bar](https://material.io/
|
|
53
|
+
Show the [app bar](https://m2.material.io/components/app-bars-top) above the book when the book is first displayed.
|
|
42
54
|
|
|
43
55
|
Example: `initiallyShowAppBar=false`
|
|
44
56
|
|
|
45
57
|
Default: `true`
|
|
46
58
|
|
|
47
|
-
|
|
59
|
+
### allowToggleAppBar
|
|
48
60
|
|
|
49
61
|
If the user clicks in a content area of the page, toggle display of the app bar.
|
|
50
62
|
|
|
@@ -52,22 +64,21 @@ Example: `allowToggleAppBar=true`
|
|
|
52
64
|
|
|
53
65
|
Default: `false`
|
|
54
66
|
|
|
55
|
-
|
|
67
|
+
### showBackButton
|
|
56
68
|
|
|
57
|
-
If true, displays a button in the upper left corner of the app bar. When clicked, bloom-player
|
|
69
|
+
If true, displays a button in the upper left corner of the app bar. When clicked, bloom-player posts a message "backButtonClicked" that your host can catch and respond to.
|
|
58
70
|
|
|
59
71
|
Example: `showBackButton=true`
|
|
60
72
|
|
|
61
73
|
Default: `false`
|
|
62
74
|
|
|
63
|
-
>
|
|
64
|
-
> If bloom-player is the top level window (e.g. in Bloom Reader), this button will be a left arrow. However if bloom-player is embedded in another page (e.g. in an iframe), it will show as an ellipsis, unless `backButtonIcon` says otherwise.
|
|
75
|
+
> **Note:** If bloom-player is the top level window (e.g. in Bloom Reader), this button will be a left arrow. However if bloom-player is embedded in another page (e.g. in an iframe), it will show as an ellipsis, unless `backButtonIcon` says otherwise.
|
|
65
76
|
>
|
|
66
|
-
> The ellipsis is used in BloomLibrary.org when the user has used a link from somewhere else to jump directly into
|
|
77
|
+
> The ellipsis is used in BloomLibrary.org when the user has used a link from somewhere else to jump directly into reading a book. In that case, this button isn't really taking them "back", it's instead taking them to the "Detail" page for that same book on BloomLibrary.org.
|
|
67
78
|
>
|
|
68
|
-
>
|
|
79
|
+
> Once the user has followed a link within the book to another page or book, the button is an arrow that returns them to where they came from, and clicking it posts no message. This arrow appears even when `showBackButton` is false.
|
|
69
80
|
|
|
70
|
-
|
|
81
|
+
### backButtonIcon
|
|
71
82
|
|
|
72
83
|
Which icon to show on the button that `showBackButton` adds: `arrow` or `ellipsis`. Use this when embedding bloom-player in an iframe in an app whose back button really does go back, so it should be an arrow.
|
|
73
84
|
|
|
@@ -75,7 +86,7 @@ Example: `showBackButton=true&backButtonIcon=arrow`
|
|
|
75
86
|
|
|
76
87
|
Default: none (bloom-player chooses, as described under `showBackButton`)
|
|
77
88
|
|
|
78
|
-
|
|
89
|
+
### lang
|
|
79
90
|
|
|
80
91
|
If set, determines the initial language to be displayed. The user can still change the display language using the language picker.
|
|
81
92
|
|
|
@@ -83,69 +94,155 @@ Example: `lang=fr`
|
|
|
83
94
|
|
|
84
95
|
Default: none (The initial language will be the vernacular language when the book was published.)
|
|
85
96
|
|
|
86
|
-
|
|
97
|
+
### hideFullScreenButton
|
|
87
98
|
|
|
88
|
-
If true, the Full Screen icon button will not appear in the upper right hand corner of the window. Otherwise, a Full Screen icon button is displayed and allows the user to toggle between full screen and window mode.
|
|
99
|
+
If true, the Full Screen icon button will not appear in the upper right hand corner of the window. Otherwise, a Full Screen icon button is displayed and allows the user to toggle between full screen and window mode, as long as the browser allows full screen. In an iframe, that requires `allow="fullscreen"`.
|
|
89
100
|
|
|
90
101
|
Example: `hideFullScreenButton=true`
|
|
91
102
|
|
|
92
103
|
Default: `false`
|
|
93
104
|
|
|
94
|
-
|
|
105
|
+
### independent
|
|
95
106
|
|
|
96
|
-
If true, bloom-player reports its own analytics directly to
|
|
107
|
+
If true, bloom-player reports its own analytics directly to Segment (through Bloom's analytics proxy). If false, bloom-player sends messages to its host, and the host is responsible for reporting analytics.
|
|
97
108
|
|
|
98
109
|
Example: `independent=false`
|
|
99
110
|
|
|
100
111
|
Default: `true`
|
|
101
112
|
|
|
102
|
-
|
|
113
|
+
### host
|
|
103
114
|
|
|
104
|
-
|
|
115
|
+
Identifies the host in analytics. If it is not set, no host is reported (except `testing` when bloom-player runs on localhost).
|
|
116
|
+
|
|
117
|
+
When the player is not served from bloomlibrary.org, the host's name also appears in the message telling the user that a book needs a newer version of the host.
|
|
118
|
+
|
|
119
|
+
With `independent=false`, the `updateBookProgressReport` messages sent to the host include `readDuration` only when `host=bloomlibrary`.
|
|
105
120
|
|
|
106
121
|
Examples: `host=bloomlibrary` or `host=bloomreader` or `host=bloompubviewer` or `host=readerapp`
|
|
107
122
|
|
|
108
|
-
|
|
123
|
+
Default: none
|
|
124
|
+
|
|
125
|
+
### autoplay
|
|
126
|
+
|
|
127
|
+
Whether bloom-player advances through the pages on its own. `yes` autoplays any book, `motion` autoplays only motion books, and only when they are shown in landscape, and `no` never autoplays. This doesn't control narration, which plays on each page whether or not the book advances (if the browser allows it); use `paused=true` to keep it from starting.
|
|
128
|
+
|
|
129
|
+
Example: `autoplay=yes`
|
|
130
|
+
|
|
131
|
+
Default: `motion`
|
|
132
|
+
|
|
133
|
+
### start-page
|
|
134
|
+
|
|
135
|
+
Open the book at this page. It is a 0-based index into the list of pages and ignores the page numbers printed on them. In a collection of linked books, it applies only to the first book.
|
|
136
|
+
|
|
137
|
+
Example: `start-page=3`
|
|
138
|
+
|
|
139
|
+
Default: the first page
|
|
140
|
+
|
|
141
|
+
### autoplay-count
|
|
109
142
|
|
|
110
|
-
|
|
143
|
+
How many pages to autoplay before stopping. Only takes effect when `start-page` is also given, and only when the book is autoplaying.
|
|
111
144
|
|
|
112
|
-
|
|
145
|
+
Example: `start-page=3&autoplay-count=2`
|
|
113
146
|
|
|
114
|
-
|
|
147
|
+
Default: none (play to the end)
|
|
148
|
+
|
|
149
|
+
### paused
|
|
150
|
+
|
|
151
|
+
Start with playback paused.
|
|
152
|
+
|
|
153
|
+
Example: `paused=true`
|
|
154
|
+
|
|
155
|
+
Default: `false`
|
|
156
|
+
|
|
157
|
+
### defaultDuration
|
|
158
|
+
|
|
159
|
+
How many seconds autoplay stays on a page that has no narration.
|
|
160
|
+
|
|
161
|
+
Example: `defaultDuration=5`
|
|
162
|
+
|
|
163
|
+
Default: `3.0`
|
|
164
|
+
|
|
165
|
+
### hideNavButtons
|
|
166
|
+
|
|
167
|
+
Hide the next and previous page buttons. Mainly useful with `autoplay=yes`.
|
|
168
|
+
|
|
169
|
+
Example: `hideNavButtons=true`
|
|
170
|
+
|
|
171
|
+
Default: `false`
|
|
172
|
+
|
|
173
|
+
### skipActivities
|
|
174
|
+
|
|
175
|
+
Leave out interactive (activity) pages. Useful for non-interactive uses such as autoplaying a book to record a video.
|
|
176
|
+
|
|
177
|
+
Example: `skipActivities=true`
|
|
178
|
+
|
|
179
|
+
Default: `false`
|
|
180
|
+
|
|
181
|
+
### centerVertically
|
|
182
|
+
|
|
183
|
+
Center the page vertically in the available space.
|
|
184
|
+
|
|
185
|
+
Example: `centerVertically=false`
|
|
186
|
+
|
|
187
|
+
Default: `true`
|
|
188
|
+
|
|
189
|
+
### extraButtons
|
|
190
|
+
|
|
191
|
+
Extra buttons to add to the app bar, as URL-encoded JSON. Each button has an `id`, an `iconUrl` and an optional `description` (its tooltip and accessible label). When the user clicks a button, bloom-player posts a message whose `messageType` is that button's `id`.
|
|
192
|
+
|
|
193
|
+
```js
|
|
194
|
+
const buttons = [
|
|
195
|
+
{ id: "fullScreen", iconUrl: "https://example.org/fullscreen.svg", description: "Full screen" },
|
|
196
|
+
];
|
|
197
|
+
const param = "extraButtons=" + encodeURIComponent(JSON.stringify(buttons));
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Default: none
|
|
201
|
+
|
|
202
|
+
### Parameters used by Bloom Editor
|
|
203
|
+
|
|
204
|
+
Bloom Editor uses these when it previews a book or records it as a video. Other hosts shouldn't need them: `videoPreviewMode`, `videoSettings`, `reportSoundLog`, `useOriginalPageSize`, `roundPageWidthToNearestK` and `roundMarginToNearestK`.
|
|
205
|
+
|
|
206
|
+
## How to support books that link to other books
|
|
207
|
+
|
|
208
|
+
Some books are designed to be published together as a collection. These books may link to each other using underlined phrases or buttons. Users can click on these links and also backtrack. You can see examples of this in the Storybook stories under "MultiBook".
|
|
115
209
|
|
|
116
210
|
Instead of asking your host to handle the navigation, history, etc., this navigation happens within the one instance of Bloom Player. However, Bloom Player needs your help, because it does not have a way to know what the URL to each book is in the context of your host, which could be a website, an app, a desktop program, etc. So if you want to support these collections of linked books, your host has to do some extra work.
|
|
117
211
|
|
|
118
212
|
Bloom books link to each other using each book's "Instance ID". This is a guid that is given as a property in the `meta.json` file:
|
|
119
213
|
|
|
120
|
-
```
|
|
214
|
+
```jsonc
|
|
121
215
|
{
|
|
122
216
|
"bookInstanceId":"0b82aab3-61fb-429e-864f-ce7671a3d372",
|
|
123
217
|
"title":"หมู่บ้านแห่งความดี\r\nVillage of good",
|
|
124
218
|
"credits":"มิได้จัดจำหน่าย แต่จัดทำเพื่อส่งเสริมการเรียนรู้",
|
|
125
219
|
"tags":["topic:Fiction"],
|
|
126
|
-
"pageCount":16
|
|
127
|
-
...
|
|
220
|
+
"pageCount":16
|
|
221
|
+
// ...and other properties
|
|
222
|
+
}
|
|
128
223
|
```
|
|
129
224
|
|
|
225
|
+
(To see a book's Instance ID while it is open in Bloom Player, click in the player and hold down the CTRL key.)
|
|
226
|
+
|
|
227
|
+
When Bloom Player wants to switch to a different book, it starts requesting that book's files under `/book/THE-INSTANCE-ID/` on the same origin the current book was loaded from, e.g. `/book/THE-INSTANCE-ID/.distribution`, `/book/THE-INSTANCE-ID/meta.json` and `/book/THE-INSTANCE-ID/index.htm`. Be prepared to receive several of these before you've handled the first one.
|
|
228
|
+
|
|
130
229
|
To support this, your host needs to:
|
|
131
230
|
|
|
132
|
-
1. intercept
|
|
231
|
+
1. intercept those requests
|
|
133
232
|
2. extract the Instance ID
|
|
134
233
|
3. figure out the path to that book in your system
|
|
135
|
-
4. if the target is still zipped in a BloomPUB,
|
|
136
|
-
5.
|
|
137
|
-
|
|
138
|
-
Note that when Bloom Player wants to switch to a different book, it will start requesting resources, e.g. `/book/THE-INSTANCE-ID/.distribution`, `/book/THE-INSTANCE-ID/meta.json` and `/book/THE-INSTANCE-ID/index.htm`. Be prepared to receive several of these before you've handled the first one.
|
|
234
|
+
4. if the target is still zipped in a BloomPUB, unzip it or read the resource directly out of the archive
|
|
235
|
+
5. return the requested file (and do the same for every later request for that book's files). The book's main HTML file must be reachable as `/book/THE-INSTANCE-ID/index.htm`.
|
|
139
236
|
|
|
140
237
|
Depending on your situation, you may find handling this as simple as doing a 302 redirect (as Bloom Editor does), or you may want to take each incoming URL and return the contents of that file (as BloomPUB Viewer does).
|
|
141
238
|
|
|
142
239
|
If step (3) is slow, you might need to cache or even pre-prepare an index for use at runtime.
|
|
143
240
|
|
|
144
|
-
As an example, in this repository, the file `.storybook/main.ts` sets up Storybook's vite dev server to proxy a couple instance ids to
|
|
241
|
+
As an example, in this repository, the file `.storybook/main.ts` sets up Storybook's vite dev server to proxy a couple of instance ids to the right folders in this repository's `public/testBooks` directory.
|
|
145
242
|
|
|
146
243
|
# Development
|
|
147
244
|
|
|
148
|
-
If you haven't already, install
|
|
245
|
+
If you haven't already, install [Volta](https://volta.sh) globally. Volta takes care of getting all the correct versions of things like node and pnpm to match what this repository expects.
|
|
149
246
|
|
|
150
247
|
Run `pnpm install` to get the dependencies.
|
|
151
248
|
|
|
@@ -155,40 +252,44 @@ To build the standalone js file that can be used from an html file:
|
|
|
155
252
|
pnpm build:standalone
|
|
156
253
|
```
|
|
157
254
|
|
|
158
|
-
To build the library used by
|
|
255
|
+
To build the library used by Bloom Editor:
|
|
159
256
|
|
|
160
257
|
```bash
|
|
161
258
|
pnpm build:sharedlib
|
|
162
259
|
```
|
|
163
260
|
|
|
164
|
-
|
|
261
|
+
To try your changes, run `pnpm dev`. It serves the source directly (no build needed), watches it, and opens `index-for-developing.html`; edit that file to point to a different book.
|
|
165
262
|
|
|
166
|
-
|
|
263
|
+
Or run `pnpm storybook`, which has many test books. Storybook won't start without a `dist/` folder, so run `pnpm build:standalone` once first. Most stories run from source and update as you edit. The ones that embed `bloomplayer.htm` in an iframe (MultiBook and Automated/Navigation) use `dist/`, so rebuild for those after changing the code, or keep `pnpm watchForStorybook` running.
|
|
167
264
|
|
|
168
265
|
See package.json for other scripts.
|
|
169
266
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
Depending on what book you are loading, if the book is on bloomlibrary.org or dev.bloomlibrary.org, CORS headers there will normally prevent your local bloom-player from loading the book, because it is not in the right domain. To get around this, you need to run your browser in a special low-security mode.
|
|
267
|
+
## Testing with a book hosted on the web
|
|
173
268
|
|
|
174
|
-
|
|
269
|
+
Depending on what book you are loading, if the book is on bloomlibrary.org or dev.bloomlibrary.org, CORS headers there may prevent your local bloom-player from loading the book, because it is not in the right domain. To get around this, `pnpm dev` and `pnpm storybook` run a proxy (configured in `vite.config.ts`) that fetches the book for you. With it, refer to a book on Bloom Library's S3 storage with a URL that starts with `s3/` in place of `https://s3.amazonaws.com/`.
|
|
175
270
|
|
|
176
|
-
|
|
271
|
+
## Testing with a book hosted by Bloom
|
|
177
272
|
|
|
178
273
|
To test Bloom Player on a book in the Bloom Editor, follow these steps:
|
|
179
274
|
|
|
180
275
|
1. Go to the Publish tab in Bloom, choose "BloomPUB", and click "Preview".
|
|
181
276
|
2. Back in this repository, run storybook (`pnpm storybook`).
|
|
182
|
-
3. Choose the "Live From Bloom Editor" story.
|
|
277
|
+
3. Choose the "Live From Bloom Editor" story (under "Various books").
|
|
183
278
|
|
|
184
|
-
|
|
279
|
+
## Running unit tests
|
|
185
280
|
|
|
186
|
-
To run unit tests use `pnpm test
|
|
281
|
+
To run unit tests use `pnpm test` (it keeps watching for changes; `pnpm test run` runs once). This runs all `*.test.ts` and `*.test.tsx` files under `src/`, which should be colocated with the thing being tested. These are vitest + jsdom tests.
|
|
187
282
|
|
|
188
|
-
|
|
283
|
+
## Running end-to-end (browser) tests
|
|
189
284
|
|
|
190
285
|
The vitest tests run in jsdom, which can't exercise real-browser behavior such as swiper page-turning geometry, the audio autoplay policy, or the actual built `dist/bloomplayer.htm` artifact that hosts embed. Those are covered by a Playwright suite under `e2e/`.
|
|
191
286
|
|
|
287
|
+
The first time, install the browser the tests use:
|
|
288
|
+
|
|
289
|
+
```bash
|
|
290
|
+
pnpm exec playwright install chromium
|
|
291
|
+
```
|
|
292
|
+
|
|
192
293
|
Because the e2e tests run against the built standalone bundle, build it first:
|
|
193
294
|
|
|
194
295
|
```bash
|
|
@@ -196,18 +297,17 @@ pnpm build:standalone
|
|
|
196
297
|
pnpm test:e2e
|
|
197
298
|
```
|
|
198
299
|
|
|
199
|
-
`pnpm test:e2e:build` does both in one step, and `pnpm test:e2e:ui` opens the Playwright UI. The suite serves `dist/` plus the hermetic `public/testBooks/` fixtures via `e2e/server.mjs`; no network access or external books are required. See [E2E-TESTING-PLAN.md](E2E-TESTING-PLAN.md) for the design and the list of specs.
|
|
200
|
-
|
|
300
|
+
`pnpm test:e2e:build` does both in one step, and `pnpm test:e2e:ui` opens the Playwright UI. The suite serves `dist/` plus the hermetic `public/testBooks/` fixtures via `e2e/server.mjs`; no network access or external books are required. See [E2E-TESTING-PLAN.md](E2E-TESTING-PLAN.md) for the design and the initial list of specs.
|
|
201
301
|
|
|
202
|
-
|
|
302
|
+
## Version Info
|
|
203
303
|
|
|
204
|
-
If you hold down the CTRL key, Bloom Player will display its version and
|
|
304
|
+
If you click in the player and hold down the CTRL key, Bloom Player will display its version, build date and the book's Instance ID.
|
|
205
305
|
|
|
206
|
-
|
|
306
|
+
# More info
|
|
207
307
|
|
|
208
|
-
See README-advanced.md for more information on embedding bloom-player into other projects and
|
|
308
|
+
See [README-advanced.md](README-advanced.md) for more information on embedding bloom-player into other projects and
|
|
209
309
|
on using shared code functions in other projects.
|
|
210
310
|
|
|
211
|
-
|
|
311
|
+
# License
|
|
212
312
|
|
|
213
313
|
MIT
|