Bible Brain logo
Core Concepts
Sign Up

Core Concepts

What you need to know to get started

The Bible Brain API (also referred to as “Digital Bible Platform” or “DBP”) is a RESTful API that returns JSON formatted responses. All requests made by reader applications use the HTML GET method. All requests require a developer API key to be provided. This key is provided at the time your developer account is created.  

If you already have an API key and have used it within the last year on an earlier version of DBP, the key will still be available for use on DBP4.

In order to use DBP, here are some core concepts to understand.

BibleId

A single Bible Version can have multiple filesets (text, audio, video, drama, non-drama, etc).  In BibleBrain, related filesets are grouped by having the same BibleId, which is usually six-characters long, and usually matches the first six characters of the related FilesetIds.  There are some cases however where the characters do not match exactly, so it is NOT safe to make that assumption. So a BibleId will usually have the format LLLVVV where LLL is the language ISO 639 code and VVV identifies the Bible version.

Filesets

Each Bible consists of one or more filesets. A fileset is a logical grouping of contents for a specific Bible, in a particular size, drama type, and media type. Each fileset is identified by a FilesetId. If you are familiar with the earlier version of DBP, FilesetId is functionally equivalent to DAMID’s (and most 10-character FilesetId’s exactly match the corresponding v2 DAMID, with FilesetId’s longer than 10 characters being unique to DBP v4).

FilesetId

The filesetid is your key to delivering Bible content. Most of the other endpoints are intended to help you answer the question: which filesetid am I looking for?

The filesetId naming convention is LLLVVV[CDMM-xxxxx], with the first six characters usually matching the BibleId and the square brackets indicating optional characters. Optional characters after the dash describe the media encoding used to produce the audio or video fileset. 

  • LLL - “language code”, which usually matches SIL’s Ethnologue (which usually matches ISO 639-3). 
  • VVV - “version”, an abbreviation of the translation name
    Note: If a filesetid has only the first six characters, the fileset contains plain text.
  • C - “collection”, allowed values are:
    - C - Complete (all books and chapters of both testaments)
    - N - New Testament (all books and chapters)
    - O - Old Testament (all books and chapters)
    - P - Partial (incomplete set of books or chapters)
    - S - Story (Bible-related content, not a formal translation, not usually organized by book or chapter)
  • D - “drama type”, allowed values are:
    - 1 - “non-drama”, usually multi-voice without background music, but sometimes single-voice
    - 2 - “drama”, meaning that it is multi-voice with background music
  • MM - “media type”, allowed values are:
    - DA - “digital audio”, mp3 files, encoded at constant 64kbps bitrate 
    - DV - “digital video”, mp4 files delivered as multi-bitrate HLS streams  
    - SA - “streaming audio”, a HLS stream of the corresponding DA fileset (there are only a small number of these, and will be replaced by the below...])
  • xxxxx (an arbitrary number of additional characters)
    - opus16 - constant-bitrate 16kbps opus in webm container files 
    - Naming convention is: 
       - lower-case letters indicate codec name
        - numbers indicating bitrate (eg 16, 32, 64)
        - upper-case letters indicate streaming protocol 
    - Below are planned for later:
        - aac32 - constant-bitrate 32kbps aac in mp4 container files 
        - aac64 - constant-bitrate 64kbps aac in mp4 container files 
        - aacHLS - all available aac’s delivered via HLS 

For example, ENGESVN2DA would be a fileset containing 
    - English (ENG)
    - ESV version (ESV) 
    - New Testament (N) 
    - multi-voice with background music (2)
    - audio (DA), as mp3 files encoded at constant 64kbps bitrate

In general, filesets which start with the same first 6 characters are different formats of the same Bible. We offer as many fileset types as we can for each Bible, subject to license or technical limitations.

A six-character fileset is used for Bible Texts (which contain all available books across both testaments).

Note: filesetid values are purely conventional, intended to make it easier for a human to get a general idea of what content is associated with the id. DBP4 always provides additional information which exactly describes the content (eg, media type, drama/non-drama, etc.). 

There are filesets that do not exactly match the convention. So unlike DBP2 DAMID, client decoding of filesetId is not necessary and is explicitly discouraged.  

Gospel Films

These full-length feature films use the actual Gospel texts as their scripts—word-for-word. Created by LUMO using extensive theological, historical, and archaeological research, each film has been adapted with Faith Comes By Hearing's audio Scripture in the languages of the world.

Language Codes

Each language is identified by a unique three-character language code. These language codes are intended to always match the ISO 639-3 language set, and is documented fully in SIL's Ethnologue.

Languages returned by DBP contain both a language_name and an english_name field. In many cases, these fields contain the same value, but generally, the language_name field will contain the localized name. For example, for language code “CHN”, the english_name field returns “Chinese, Mandarin”, whereas the language_name field returns “中文”.

Version Codes

Each version of the Bible has a unique version code. Versions are not directly related to languages, and a single version code can appear in more than one language. For instance, the King James Version (KJV) appears in both English and Thai.

Content Delivery Network

Text content is returned directly in API call response payloads. Audio and Video content are stored in a Content Delivery Network, and API response payloads will return signed URLS to specific audio or video files.

Audio Timing

When available, DBP can provide the approximate starting time for each verse. This can be helpful if you are planning to present a combination of text and audio “karaoke-style”. This information is also useful when you want to play audio in response to a keyword search. 

Postman

We have created a series of API request examples to help you be productive more quickly. The requests are organized as Postman collections. Once you add your API key, you can submit requests directly from Postman. If you wish to download Postman, click on this link. You will also have an opportunity to download when you access the Example Workflows collection, which is located here.  

To run the collection, import it into a personal workspace and configure the API key once, at the root level, under Authorization (provide snapshot or two on how to do this). The key will then be used for all requests in the collection.

To request an API key, click here and provide some basic information.

Faith Come By Hearing
Please Upgrade Your Browser

Unfortunately, Internet Explorer is an outdated browser and we do not currently support it. To have the best browsing experience, please upgrade to Microsoft Edge, Google Chrome or Safari.

Upgrade