Bloom Reader

Bloom is award-winning open source desktop software for Windows and Linux that communities, NGOs, and Education ministries around the world are using to create books in the world's thousands of minority languages. These books are mostly distributed via paper, though some people are making ePUBs. We can now also use SIL's Reading Application Builder to package books as Android apps that can be downloaded from the Play Store.

So what's this "Bloom Reader" about? Bloom users tell us that it's difficult to find ePUB readers that are simple to use and that can reliably display Bloom books and play audio from Bloom Talking books. They want the simplicity of apps. But they don't want to have to create apps or have people download apps for each book that gets published. Instead, they want an app, kind of like a Kindle app, which people can use to read and share Bloom books.

Bloom Reader is a native java app with a WebView for displaying Bloom books (which are HTML). We want to support the older Android versions and devices that are common in the developing world.

Distribution

Bloom Reader is distributed through the Google Play Store. Try it out.

Apks are also distributed through our website.

Road map

Prototype

• Shows a list of books on the device's storage
• User can swipe through pages to read the book

Books get onto the device by plugging into a computer and transferring files over to some known location.

MVP

• Works well with 3rd party file sharing apps.
• Works with Android 4.4 (KitKat) and up
• Comes with SIL's Andika literacy font
• Book scales to fit device screen
• Bloom desktop Publish tab offers a "Publish to Android Phone" option (Bloom version 4.0). That may have to reduce image resolution.

At this point, literacy projects can seed books into the community and let the community distribute them virally.

Needed for SIL PNG literacy research project

• Plays talking books
• Book thumbnails

Tie into BloomLibrary.org

• BloomLibrary.org publishes an OPDS catalog of all its books.
• User can see a list of all the books in her language that are on BloomLibrary.org.
• User can preview books, perhaps in a very low-bandwidth form.
• User can choose to download books to her device.
• User gets notifications when new or updated books are available.

At this point, anyone can publish a book using the existing Bloom mechanism, and have it immediately downloadable by anyone with Bloom Reader. Books still spread mostly from person to person in expensive internet areas.

Other things on the radar

• Support Ken Burns animation.
• Support background music that works across pages.
• In-app sharing/synchronization via bluetooth and wifi-direct.

Building

Setting up the build environment

1. Install Android Studio, the IDE used by the Bloom Reader team for developing the app.
2. Install Open JDK 21. A later version such as the one that comes with Android Studio may work, but Open JDK 21 is the most recent one used by Bloom Reader team and known to work. The installation should adjust the PATH environment variable to make the java command available and set the JAVA_HOME environment variable. If not, you need to do this yourself.
3. Install volta. This makes yarn available with the proper version for BloomReader.
4. Clone the Bloom Reader code onto your local machine using git as follows.

     git clone https://github.com/BloomBooks/BloomReader

If you clone from a fork of the project, make sure that the fork is up to date with the main repository (BloomBooks/BloomReader). 5. Obtain build and runtime dependencies for Bloom Reader as follows.

     cd BloomReader/app
     yarn
     cd ..
     ./gradlew copyBloomPlayerAssets

6. Start Android Studio and open the Bloom Reader project (BloomReader folder).

7. Invoke the Sync Project with Gradle Files command in the File menu or the corresponding button from the command button bar. (This has the effect of limiting the default build inside Android Studio to the debug configuration of the alpha flavor of the app, which is usually what you want.)

8. Build Bloom Reader with the Assemble Project command in the Build menu or the corresponding button from the command button bar. This should complete successfully, running the assembleAlphaDebug build.

9. Run the newly built app with the Run 'app' command in the Run menu or the corresponding button from the command button bar. This should prompt you to set up an Android device emulator. Choose a device and then choose a version of Android to download to use on that device. Following all the program prompts, in a few minutes (depending on your internet download speed), you should see Bloom Reader running in the device emulator.

   Running the Android device emulator on Linux may require a few more setup steps dealing with /dev/kvm: Internet search engines will help with that complication.

Getting the Bloom Reader code dependencies

BloomReader requires a number of files from the bloom-player project. By default, and in the CI build, these are obtained using yarn from the npm output of bloom-player.

When building locally, if you need to make changes to bloom-player, you can use yarn link.

If you don't need to make changes in bloom-player, get these files using the yarn and copy commands above.

If you want the latest version of bloom-player, rather than the one active when BloomReader was last updated, replace yarn with yarn upgrade bloom-player. You can also edit the app/packages.json file to update the version number of bloom-player if needed.

Signing and Deployment

Flavors

We build two flavors of the app:

• alpha (org.sil.bloom.reader.alpha)
• production (org.sil.bloom.reader)

(There was formerly a beta flavor (org.sil.bloom.reader.beta), but the Play Store shut down the BR Beta app; its definition is commented out in app/build.gradle.)

Debug builds

Each flavor can also build a debug configuration which appends .debug to the package name. The main reason for this is to prevent debug builds from polluting crash reports. See https://issuetracker.google.com/issues/64929012.

Signing a release build

To sign a release build, you need the following file.

{UserHome}/keystore/keystore_bloom_reader.properties

The contents of this file are:

storeFile=
storePassword=
keyAlias=
keyPassword=

where storeFile is an absolute path to keystore_bloom_reader.keystore. This file and the other values must be shared with you by a member of the team who has them.

Deploying to the Play Store

To publish to the Play Store, we use a gradle plugin: https://github.com/Triple-T/gradle-play-publisher. To use the plugin locally, you must add serviceAccountJsonFile= to the .properties file described above. Set the value as an absolute path to the Google Play Android Developer-cf6d1afc73be.json file which you must obtain from a member of the team.

Gradle tasks which can be called with the plugin include:

• publish{Alpha/Beta/Production}Release
  • pushes both the apk and listing metadata to the Play Store
• publish{Alpha/Beta/Production}ReleaseApk
  • pushes only the apk to the Play Store
• publish{Alpha/Beta/Production}ReleaseListing
  • pushes only the listing metadata to the Play Store

CI/CD (GitHub Actions)

Publishing is automated by the GitHub Actions workflow .github/workflows/play-publish.yml:

• Every push to master builds the alpha flavor — first upgrading to the latest bloom-player@alpha — runs the full build (deliberately compiling, linting, and unit-testing every flavor and build type, so each alpha run verifies nothing is broken even in variants we don't publish), publishes to the internal track of the "BR Alpha" Play app, and then promotes it per the play {} config in app/build.gradle.
• Every push to release runs lint and unit tests, builds the production flavor (using the bloom-player version pinned in app/yarn.lock), publishes the APK (only — the store listing is managed in the Play Console, not the repo) to the internal track of the "Bloom Reader" Play app, uploads the APK and a version-number file to the bloomlibrary.org S3 bucket (which serves the APK for direct download), and tags the commit vX.Y.Z. Promoting from the internal track to production is still a manual step in the Play Console.
• The workflow can also be dispatched manually from the Actions tab (choose a flavor; optionally override the patch number). A real publish must be dispatched from the flavor's own branch; dry runs may run from any branch.

Version numbers

versionMajor and versionMinor are defined in app/build.gradle. CI derives the patch number (the x in 3.4.x) by counting the commits since the last commit that changed those two lines. Consequences:

• Bumping the version resets the patch to 0 automatically — to start 3.5, just change versionMinor and commit. (But don't touch those lines for any other reason, e.g. reformatting: that also resets the patch counter.)
• master (alpha) and release (production) have independent patch numbers.
• versionCode = major*100000 + minor*1000 + patch, so the patch must stay below 1000; the workflow fails if it would overflow.
• Until the next version bump, alpha patch numbers include a hardcoded +77 offset for continuity with the old TeamCity build counter. It is keyed to the 3.4 bump commit and expires on its own (see the workflow).

The legacy 1.4 APK

Every production release retains the legacy 1.4 APK (versionCode 104001) so that devices below the current minSdkVersion keep a working app (see playConfigs in app/build.gradle). A production release must never be published without it: re-adding an APK that targets an old API level may not be possible under current Play requirements.

Secrets and configuration

The workflow requires these GitHub repository secrets:

• KEYSTORE_BASE64 — base64 of keystore_bloom_reader.keystore
• KEYSTORE_STORE_PASSWORD, KEYSTORE_KEY_ALIAS, KEYSTORE_KEY_PASSWORD — the corresponding values from keystore_bloom_reader.properties
• PLAY_SERVICE_ACCOUNT_JSON — the contents of the service account json file
• BLOOMLIBRARY_AWS_ACCESS_KEY_ID, BLOOMLIBRARY_AWS_SECRET_ACCESS_KEY — credentials of the BloomLibrary AWS profile, used to upload the production APK and version file to the bloomlibrary.org S3 bucket

Setting the repository variable PLAY_DRY_RUN to true makes every run build, sign, and upload to a Play edit without committing it, so nothing becomes visible in the Play Console. Use it when verifying changes to the workflow; delete the variable to resume real publishing.

Localization

See ./l10n/README.md

Development

Testing local BloomLibrary

To test your local BloomLibrary code in Bloom Reader, see the commented host = "http:// line in BloomLibraryActivity.java, onCreate.

Sample book

To update the sample book, The Moon and the Cap:

• In {BloomDesktop}/BloomExe/Book/BookInfo.cs, find the line that reads 'set { MetaData.SubscriptionDescriptor = value; }' and replace it with 'set { MetaData.SubscriptionDescriptor = "Sample-Book"; }'
• Open an English collection in the latest version of Bloom. Vernacular and National language should be English.
• Set xMatter to Device.
• Set Enterprise to SIL subscription so we don't lose the quiz pages.
• Create a book using the sample shell.
• Set the layout to Device16x9Portrait.
• Publish -> Bloom Reader
  • Make sure all languages are selected.
    • Unfortunately, this currently means the Tibetan quiz is blank. Not sure what to do about that...
  • Save Bloom Reader File
• Save to {BloomReader}/app/src/main/assets/sample books/The Moon and the Cap.bloompub
• Go back to {BloomDesktop}/BloomExe/Book/BookInfo.cs and change the modified line back to its original state.

Contributions

We welcome contributions, particularly if we pre-agree on UX.