bloom-player 2.22.0-alpha.1 → 2.22.0-alpha.3

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 CHANGED
@@ -1,10 +1,12 @@
1
- # Introduction
1
+ # bloom-player
2
+
3
+ [![Ask DeepWiki](https://deepwiki.com/badge.svg)](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) / Publish / Bloom Reader tab, for previewing what the book will look like on a device.
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=path-to-your-book"
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
- Advanced: if you want to just show a spinning wheel, you can supply `url=working` and then render it again when you have an actual url.
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
- # Optional Parameters
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
- 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://material.io/design/components/app-bars-top.html),
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=path-to-your-book&initiallyShowAppBar=false&allowToggleAppBar=false"
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
- #### initiallyShowAppBar
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/design/components/app-bars-top.html) above the book when the book is first displayed.
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
- #### allowToggleAppBar
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
- #### showBackButton
67
+ ### showBackButton
56
68
 
57
- If true, displays a button in the upper left corner of the app bar. When clicked, bloom-player will post a message "backButtonClicked" that the your host can catch and respond to.
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
- > [!NOTE]
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 to 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.
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
- > Either way, 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.
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
- #### backButtonIcon
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
- #### lang
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
- #### hideFullScreenButton
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
- #### independent
105
+ ### independent
95
106
 
96
- If true, bloom-player reports its own analytics directly to segment. If false, bloom-player sends messages to its host, and the host is responsible for reporting analytics.
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
- #### host
113
+ ### host
103
114
 
104
- If set, provides a host value for analytics. If not set, bloom-player attempts to derive a value from the available information if independent is `true` (information can be limited in an iframe) and does nothing otherwise.
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
- ...or, theoretically, `host=embed@xyzzy.org` (but we haven't used that yet)
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
- Default: `nothing/undefined`
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
- # How to support books that link to other books
145
+ Example: `start-page=3&autoplay-count=2`
113
146
 
114
- 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".
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
- ```json
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 that request
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, you may need to unzip it or read the resource directly out of the archive
136
- 5. handle the incoming urls for all subsequent.
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 correct folders in this repository's `/public/testBooks` directory.
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 `volta` globally. Volta takes care of getting all the correct versions of things like node and pnpm to match what this repository expects.
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 the Bloom Editor
255
+ To build the library used by Bloom Editor:
159
256
 
160
257
  ```bash
161
258
  pnpm build:sharedlib
162
259
  ```
163
260
 
164
- After building the standalone js file, either run `pnpm storybook` (which has multiple books),
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
- or run `pnpm dev` (which will use `index-for-developing.html`).
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
- ### Testing with a book hosted on the web
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
- Both `pnpm storybook` and `pnpm dev` do this for you.
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
- ### Testing with a book hosted by Bloom
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
- ### Running unit tests
279
+ ## Running unit tests
185
280
 
186
- To run unit tests use `pnpm test`. This will run all `*.test.ts` under `src/`, which should be collocated with the thing being tested. These are vitest + jsdom tests.
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
- ### Running end-to-end (browser) tests
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
- ### Version Info
302
+ ## Version Info
203
303
 
204
- If you hold down the CTRL key, Bloom Player will display its version and build date.
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
- ### More info
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
- ## License
311
+ # License
212
312
 
213
313
  MIT