Freely-Given.org CustomBible Program

Picture of the FG Logo

CustomBible software

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 code into the program to link the app to the appropriate files on the Freely-Given.org 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 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.)

Two app versions are planned:

  1. CustomBible1 will simply display the one connected Bible.
  2. CustomBible2 will also display a second Bible version, e.g., the World English Bible.

Release date: Aiming for an initial basic version of CustomBible1 in late-2017.

Meanwhile, if you look at the CustomBible-WEB app here (can be sideloaded), it should give you an idea of what the CustomBible1 app might look like (except that CustomBible accepts an entered link code and will need an Internet connection to download its initial data).

Also, if you look at the Matigsalug Bible app in the Google Play Store here, it should give you an idea of what the CustomBible1 app might look like (except that CustomBible accepts an entered link code and will need an Internet connection to download its initial data).

See SIL's Scripture App Builder for ideas of what other future features might be requested (although CustomBible was conceived a couple of years before knowing about Scripture App Builder).

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 pass 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 pass code into the 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 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 pass code.

CustomBible 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: CustomBible1 and 2 must come from the same source code.
  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) 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.

CustomBible data format

The CustomBible 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 CustomBible data here and here.

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

Secondly, the file CBHeader.json (typically around 200 bytes) may be downloaded from Links/(link code)/ and contains the following:

Thirdly, the file CBDivisionNames.1.json (typically under 1KB) may 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 an ordered array of major division names like the following:

For example:

Fourthly, the file CBBookNames.1.json (typically around 5KB) 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).

Fifthly, you can choose between compressed HTML5 data and regular JSON data.

  1. Compressed HTML5

    Found in folder BySection.1.HTML. But the compression dictionary is in CBCmprnDict.1.json. 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 CB-BCV-ix.1.json. 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 .html 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.

  2. JSON

    Found in folders ByBook.1.JSON or ByChapter.1.JSON 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."