Bible Door Program

Picture of the FG Logo

Bible Door software

Use the right key and the door opens to a Bible (or two)!

Bible Door (was CustomBible) is a forthcoming basic Bible display program that will make it simpler to install your custom Bibles onto Android phones and tablets. After the Bible data is processed by the Bible Drop Box and the app is installed on the device, users will simply have to enter a short 'key' code into the Bible Door to link the app to the appropriate files on the server. The module from the Bible Drop Box will then be automatically available on the app.

It will be up to the Bible Drop Box submitter to decide how widely to distribute the key code, e.g., restricted distribution for a test version of the Scriptures, or more widely for finished/approved books. (Or you can do both with two different Bible Drop Box submissions which will give different link codes.)

The Bible Door app will also allow the user to select and choose a second Bible (e.g., from here) which will scroll alongside the primary Bible (or can be turned off).

Release date: Aiming for an initial basic version of Bible Door in mid-2018. See below for a pre-release version.

Useage steps

  1. Upload Bible: The (completed or still in progress) Bible text must be uploaded by the translator(s) to the Bible Drop Box.
  2. Get user code: The translator(s) get a key code in the response email from the Bible Drop Box.
  3. Get app: Download the app from the Google Play store or side-install it from a SD card.
  4. Enter user code: Enter the key code into the Bible Door app and request it to download all the available Scriptures. (Alternatively, the app can also just download individual books as they are referenced.)
  5. Use app: Start using the Bible Door app immediately.
  6. Share with others: Share the app and the Bible data with others (who don't necessarily have Internet access). For those with good, affordable Internet access, share the key code.

Bible Door 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.
  3. Multiple versions: Bible Door1 and 2 must come from the same source code. Update: Seems easier just to have one version.
  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. Additional text: Allow access to Bible and book introductions, along with section headings.
  6. Bible helps: Allow access to footnotes, cross-references, glossary entries, and maps.
  7. Words of Jesus: May be displayed in a different colour, e.g., red, or with a reddish background.
  8. Localisation: Bible book names should be in the Bible language; prompts and menu might be in yet another (e.g., trade or area) language.
  9. 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.)
  10. Stored data: Bible data must be stored unencrypted and in a logical, easy-to-find location.
  11. Search function: (Undecided yet whether the indexing is done by the Bible Drop Box or on the mobile device, but probably the former.)
  12. Easy sharing: Must facilitate the sharing of the Bible data to peers via SD cards and Bluetooth.
  13. Start with basics: Version 1.0 only needs basic features— advanced features will come in successive versions.
  14. 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)???
  15. Going wider: Need to keep in mind the possible eventual developer 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.

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.

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.

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.

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

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:

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:

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.

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

  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.,, 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., 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., and are loosely based on USFM3, 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.
      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.

Android App Download

If you would like to test a very early alpha version of Bible Door for Android, you can download it from the Google Play Store here.

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.