Freely-Given.org Bible Door Program Specifications

Picture of the FG Logo

Bible Door software

You should have read this user overview page first as a background before reading these detailed specifications.

Overview

  1. Bible Door is Freely-Given.org’s name for a family of open-licensed Bible reader apps which uses a short key code (like concrete-402-625) to open the door to display a particular Bible version.
  2. There are two main use cases for the app:
    • For community testing of an in-progress Bible translation that has been submitted to our Bible Drop Box.
    • To display freely-available/open-licensed Bibles which have already been pre-compiled on Freely-Given-org and have publicly available key codes
    • Could also be used for private distribution of a non-open Bible translation to a restricted audience (as long as they don’t publicly post the key code)
  3. There will be multiple versions of the app in the Bible Door family (with slightly different names like Bible Door1 and Bible Door2 or Bible Door (ASV) and Bible Door (YLT), and eventually maybe Bible Door Plus or Bible Door Study).
  4. The initial versions of the app will only be a code shell without any Bible data included, i.e., they will require either both a key code and internet access, or else access to sideloading a friend’s files before a Bible will be able to be displayed inside the app.
  5. The source code will be publicly available on GitHub and anyone will be able to fork this repo and/or release their own versions with the app name changed. However, of course, we would prefer general improvements to be upstreamed to our own app.
  6. This page is, in fact, a request for help and an admission that we are unable to devote enough dedicated time and focus to continue to develop the app ourselves. Thus we are looking for volunteer programmers to partner with us in producing this family of apps.

Key distinctives of this app family

  1. They display pre-compiled Bible data which is normally downloaded from Freely-Given-org, although some versions of the app may have one or more Bibles included with the app distribution.
  2. Once downloaded, the Bible data may normally be easily shared peer-to-peer.
  3. Defaults to downplaying of chapter/verse containers, i.e., saying "this verse says." (We teach that verse numbers should be used to help you find content, i.e., as an index into the Bible, not used as containers that "contain" text. This "container" view has led to the unfortunately common practice of Bible readers quoting "verses" -- even partial sentences -- out of context. Even chapter divisions are not always in sensible places in the discourse.)
  4. Defaults to displaying by section (not chapter or book) whenever the translation has section headings. Also has navigation by topic / section heading.
  5. At least some versions of the Bible Door apps are designed to showcase our forthcoming Open English Translation (OET) of the Bible. In fact, this is also another major driver behind the entire family of apps. The OET has a Literal Version (LV) and a Readers’ Version (RV) that are designed to be displayed (and thus scroll) together. Most of the time the LV will be shorter than the RV, so can be displayed in a slightly smaller window.

Developers’ Overview

  1. Anyone who helps or volunteers must first agree in writing that their contribution is donated to Freely-Given-org, who in turn strive to make it freely available to all via an open licence.
  2. A list of contributors is to be maintained in the code repository in a separate text or markdown file or similar, and will be displayable via the About feature of the app. Alternatively the list can be determined by something like this.
  3. At this stage, we are inclined towards a Flutter3/Dart2 app, which would run on Android, iOS, and on Ubuntu and possibly Windows desktop. If desperate enough, we would also accept help from those with expertise in Java/Kotlin traditional Android apps, and maybe even in React Native or similar. If there was enough interest, we would even entertain the possibility of multiple competing app designs in order to then allow consumers to choose the one that they find most helpful.
  4. We wish to make full use of modern testing frameworks and use automated checking features to check code quality before it is committed.
  5. Anyone wishing to help should first become familiar with other open Bible apps, including one of our favourites here. You should also read about Scripture App Builder to see the kinds of features that Bible translators may want, although Bible Door is intended to remain much, much simpler to deploy.

General specifications

  1. Open source: Source code will be open source and freely available. It must be logical and commented to make it as easy to understand as possible.
  2. Native Android: Must be a native Android app that will run nicely on modern phones and tablets, as well as on devices released within the last five years. iOS may follow.
  3. Multiple versions: Bible Door1 and 2 must come from the same source code. Update: Seems easier just to have one version and allow the user to enter either one or two key codes. This also has the advantage of being able to do a split screen even with just one version, and to display different two parts of the Bible at once.
  4. Downplay chapters and verses: Unlike most Bible apps, don’t display by chapter (except for books like Psalms and Lamentations where chapter breaks match the original text breaks) but rather by section.
  5. Handle missing verses: Remember that some Bible translations might not include a particular verse (or part of a verse, or series of verses). This can happen either a/ if the original text is disputed, or b/ if the translation of a Bible book is not yet fully completed.
  6. Additional text: Allow access to Bible and book introductions, along with section headings.
  7. Bible helps: Allow access to footnotes, cross-references, glossary entries, and maps.
  8. Words of Jesus: May be displayed in a different colour, e.g., red, or with a reddish background (although we don’t actually recommend it).
  9. Localisation: Bible book names should be in the Bible language; prompts and menu might be in yet another (e.g., trade or area) language.
  10. Easy to use: The basic functionality must be easily/quickly accessible and not complex for an unskilled user. (Advanced features can be accessed by menus.)
  11. Stored data: Bible data must be stored unencrypted and in a logical, easy-to-find location. If multiple apps are installed from the Bible Door family, they should all be able to share the same downloaded Bibles.
  12. Search function: (Undecided yet whether the indexing is done by the Bible Drop Box or on the mobile device, but probably the former.)
  13. Easy sharing: Must facilitate the sharing of the Bible data to peers via SD cards and Bluetooth.
  14. Start with basics: Version 1.0 only needs basic features— advanced features will come in successive versions.
  15. Possible future features:
    • Allow custom notes stored to the cloud???
    • Facilitate sharing Scriptures or notes on social networks???
    • Morph into a Bible editor (or maybe a separate app)???
  16. Going wider: Need to keep in mind the possible development for iOS, plus smaller or newer operating systems if they catch on (perhaps even just in third-world markets) such as Ubuntu Phone, Amazon Fire Phone, etc.
  17. No analytics: We have no desire to track the users’ use of the app, in fact it might be dangerous for users in some environments (although of course, some versions of the app can be tracked fetching data from our server), and so we don’t perceive any need to include any analytics in the app.

Tentative release schedule

  1. v0.1:App runs, has setup screen to accept key code, opens at a small book like Titus 1:1, downloads and saves the book file, and displays the whole book as a scrolling (portrait mode) document below a header line. Available on Google Play as a limited test app.
  2. v0.2:Adds BCV=book, chapter, and optional verse (i.e., if skipped, go to v1) navigation and can do the above for any Bible book available in the requested version. (Remember for the future that book names will differ in different languages, that translations may have different numbers of books, and some translations may display the books in a different order.) When text is scrolled up/down, BCV display in top heading line updates to match the first verse being displayed. Publicly available on Google Play. Left/right flicks to previous/next chapters then previous/next book.
  3. v0.3:When entering the key code, allow the user to request the entire translation to be downloaded in the background. Switches smoothly back and forth between portrait and landscape modes.
  4. v0.4:Adds a slide-in menu which allows the user to display the program about page and list of contributors.
  5. v0.5:Adds an options menu which allows the user to select the font, and the font-size on a sliding scale. Dark mode and foreground text and background colours can be selected. Also words of Jesus in red (even though we don’t recommend it).
  6. v0.6:Add a way to navigate to and display a/ the Bible introduction, b/ introductions for each book, and c/ a text appendix.
  7. v0.7:Add book then section (heading) navigation. Left/right flicks to previous/next sections then previous/next book. Ensure back button works for both BCV and section navigation. On all navigation pages, display recent books, e.g., if was in Matthew, then in Ruth, then in Genesis, when selecting a new book, show those three recent books above the full matrix of books available to be selected.
  8. v0.8: Takes full advantage of increased screen area on tablets and for desktop situations.
  9. v0.9: Handles Greek original Bibles (NT & LXX)
  10. v1.0: Word search added. (Requires indexing of the text.)
  11. v2.0:Handles Hebrew (a RTL language)
  12. v3.0:Handles two Bibles with different versifications via mapping files, e.g., Psalm a:b in one, might be Psalm a+1:d in another.
  13. v4.0:Lexicon lookups added
  14. v5.0:Allow syncing of options and Bibles between devices. Note-taking works and saves to the cloud

History

Bible Door (was CustomBible) was first planned around 2013 to make it simpler to install your custom Bibles onto Android phones and tablets via the Bible Drop Box service. It was originally envisioned in order to allow Bible translators to easily do community testing on mobile devices without needing to first install any software development environment.

Bible Door data format

The Bible Door export from the Bible Drop Box may also be usuable by other software, including web software, since it is JSON (see also here) and HTML5 based.

Please note that this particular JSON format is still tentative and subject to revision.

You can see some sample Bible Door data here and here.

All files are UTF-8 encoded (without BOMs), and using Linux/Unix-style (\n) line-endings. Update: We might be adding BOMs.

Server alive response

Firstly, the five-byte text file Links/FG_BD_Header.txt simply contains the word Alive, and may be downloaded to verify successful contact with our server.

Bible header

Secondly, the file BDHeader.json (typically under 250 bytes) may be downloaded from Links/(link code)/ e.g., Links/wycliffe-123-456/ and contains the following information:

File checksums

Thirdly, the file BDChecksums.1.json (typically around 8KB) may optionally be downloaded from the same location. Note that the .1 before the file extension (and at the end of the folder names below) matches the Data Format Version above. This file contains a dictionary/map of filenames and md5 checksums in hexadecimal. Each md5 checksum is a string containing 32 hexadecimal characters.

For example:

Division names

Fourthly, the file BDDivisionNames.1.json (typically under 100 bytes) may be downloaded from the same location. This file contains an ordered array of major division names like the following (but often only with two entries being Old and New Testament names):

There are no parentheses in the actual data, for example:

Book names

Fifthly, the file BDBookNames.1.json (typically around 6KB) may be downloaded from the same location. This file contains an ordered array of array entries (for each included book) like the following:

For example:

where BBB is the three-character book code from the Bible Organisational System (BOS).

Note that the number of sections should equal the number of chapters if the translation does not include section headings.

Book data

Sixthly, you can choose between our compressed HTML5 data, regular JSON data, and (recommended) our newer TEXT data (loosely based on ESFM).

  1. Text (recommended)

    Found in folders ByBook.1.BDTXT. There are lots of pairs of .bd.idx and .bd.txt files, one for each book, e.g., DAN.1.bd.txt, typically around 4MB in total.

    Alternatively, the file AllBDTextFiles.bz2 is a compressed collection of all the text and index files, typically about 1MB to download. (The files are all together in a folder named AllBDTextFilesinside the .bz2 file.)

    1. Index files: These are named per book, e.g., GEN.1.bd.idx. These are JSON files, containing a list of lists. Each inner list entry contains either five or six integers:
      1. Start chapter number (-1 for book introduction)
      2. Start verse number (or line number for the introduction)
      3. File offset (to find the start of the section in the text file)
      4. Length of the text section
      5. End verse/line number
      6. (OPTIONAL) End chapter number (only if it’s different from the start chapter number).
    2. Text files: These are named per book, e.g., CO2.1.bd.txt and are loosely based on ESFM, but modified to allow for easier text processing.
      Each segment (section or chapter) can be extracted via the file offset and length from the index file.
      Each segment begins with a paragraph marker followed by an equals sign, e.g., q1=.
      Paragraph markers are normalised, i.e., always s1, never s.
      Chapter and verse numbers are surrounded by braces, are prefixed by a letter, are NOT surrounded by spaces, and are in the expected display position, e.g., p={c1}{v1}In the beginning.
      Only new paragraphs (if any) inside a segment (section or chapter) begin on new lines.
      ESFM/USFM character markers and footnotes and cross-references remain unaltered (as these have nice start/end markers), e.g., p={v3}Blessed \add be\add* the God and Father of our Lord Jesus Christ, the Father of mercies and God of all comfort;{v4}who comforteth us...
  2. JSON (deprecated)

    Found in folders ByBook.1.JSON or ByChapter.1.JSON (each typically around 9MB for an entire Bible) depending on the needs (and size/memory limitations) of your application or device.

    The book files are called BBB.1.json, e.g., PE1.1.json. The chapter files are called BBB_C.1.json, e.g., ACT_26.1.json, where BBB is the three-character book code from the Bible Organisational System (BOS).

    Each file contains an array of entries (lines), each containing one, two, or three entries:

    1. The first (string) entry is the BOS internal field marker, e.g., ip or s1 or v or v~. Note that BOS end markers are converted from starting with ¬ to ~, so ~v instead of ¬v. (This encodes cleaner in json files.)
    2. The second (string) entry is the contents of the field. It can be an empty string. If there’s no second entry, it’s None (or null in json).
    3. The third (array) entry if present, are the BOS extras, which include things like footnotes and cross-references. Each entry has three fields:
      1. The marker (string), e.g., f for footnotes and x for cross-references.
      2. The (integer) index of the character (starting at zero) to insert the extra field before.
      3. The (string) contents of the extra field (which may include internal USFM markers.
      e.g., "xr", 0, "- \\xo 1:13: \\xt Mat 10:2-4; Mar 3:16-19; Luk 6:14-16."
  3. Compressed HTML5 (deprecated)

    Found in folder BySection.1.CHTML (typically around 6MB for an entire Bible). But the compression dictionary is in BDCmprnDict.1.json (typically around 3KB). It consists of an array of array entries like the following:

    • [
    • "shortString",
    • "long uncompressed string of characters"
    • ],

    For example:

    • [
    • "@H",
    • "<section class=\"regularSection\"><h3 class=\"sectionHeading1\">"
    • ],

    You simply have to replace all occurrences of the first/short string with the second/long string. You should do these replacements in the order that the pairs of strings are given.

    You will also need a stylesheet. You can see a sample one here.

    You also need to load the index from BD-BCV-Index.1.json (typically around 150KB). This contains an array of array entries like the following:

    • [
    • "BBB",
    • chapterNumber of start of section,
    • verseNumber of start of section,
    • chapterNumber of end of section,
    • verseNumber of end of section,
    • file offset to compressed section,
    • length of compressed section
    • ],

    For example:

    • [
    • "GEN",
    • 2,
    • 4,
    • 2,
    • 25,
    • 7568,
    • 3550
    • ],

    Note that the .chtml files may contain newline markers after each paragraph if they were built in debug mode. (Most web browsers ignore these anyway—but they make the files slightly more human-readable.) Normally the (compressed) html is given as one big long string with no newline markers.

Old Android App Download

If you would like to test a very early alpha version of Bible Door for Android, you can download it from our Apps page.

NOTE: An iOS version of Bible Door is planned in the future once it is slightly more polished. (The app is written using the Google cross-platform Flutter/Dart framework.)

NOTE: Bible Door is an open source app and it’s planned to make the source available somewhere soon. Bible Door is written in the Dart language (now v2) using the still-maturing cross-platform Flutter framework.