Audio Version Cue Markers

[benkaiser]

There are some audio Bibles that offer synced narration, where the verse is highlighted as the audio is read. Would it be possible to offer this through the API in some way, I notice that thisChapterAudioLinks links to the audio in the BSB example, could it perhaps also link to the timings in a separate API call?

An example of the sync narration with BSB:
https://biblehub.com/audio/chapter/genesis/1.htm

How they internally load it, is through a JS file with the entire Bibles verse timings for each narrator:

https://tim.z73.com/haysframe/hays.js
https://tim.z73.com/souer/souer.js

I can't find the timings for the Jordan Gilbert readings, so maybe those weren't produced / not available, I'm not sure.

[KallynGowdy]

Yeah that would be totally possible. It would have to be hardcoded into the API for the BSB, but I think having a /api/{translation}/{book}/{chapter}.{reader}.audioTimings.json endpoint would be nice and including thisChapterAudioTimings, previousChapterAudioTimings, and nextChapterAudioTimings would be very helpful.

I guess the types for GET /api/{translation}/{book}/{chapter}.json would look something like this:

export interface TranslationBookChapter {
    // ...

    /**
     * The links to the timings for different audio versions for the chapter.
     * Audio timings make it possible to determine when each verse in the chapter is being spoken in the audio.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsLinks;

    /**
     * The links to the timings for different audio versions for the previous chapter.
     * Audio timings make it possible to determine when each verse in the chapter is being spoken in the audio.
     */
    previousChapterAudioTimings: TranslationBookChapterAudioTimingsLinks;

    /**
     * The links to the timings for different audio versions for the next chapter.
     * Audio timings make it possible to determine when each verse in the chapter is being spoken in the audio.
     */
    nextChapterAudioTimings: TranslationBookChapterAudioTimingsLinks;
    // ...
}

/**
 * The links to the timings for the different audio versions for a chapter.
 * 
 * Audio timings make it possible to determine when a verse is being spoken in the audio recording.
 */
interface TranslationBookChapterAudioTimingsLinks {

    /**
     * The reader for the chapter and the URL link to the timing file.
     */
    [reader]: string;
}

And there would be another endpoint:

GET /api/{translation}/{book}/{chapter}.{reader}.audioTimings.json

• translation is the ID of the translation (e.g. BSB)
• book is the ID of the book. (e.g. GEN for Genesis)
• chapter is the numerical chapter (e.g. 1 for the first chapter)
• reader is the reader for the chapter.

Structure:

export interface TranslationBookChapterAudioTimings {
    /**
     * The ID of the translation.
     */
    translationId: string;

    /**
     * The ID of the book.
     */
    bookId: string;

    /**
     * The number of the chapter.
     */
    chapterNumber: number;

    /**
     * The reader for the chapter.
     */
    reader: string;

    /**
     * The link to the audio for these timings.
     */
    audioLink: string;

    /**
     * The link to the information for this chapter.
     */
    thisChapterLink: string;

    /**
     * The link to the information for the next chapter.
     */
    nextChapterLink: string | null;

    /**
     * The link to the information for the previous chapter.
     */
    previousChapterLink: string | null;

    /**
     * The link to this audio timings file.
     */
    thisChapterAudioTimingsLink: string;

    /**
     * The link to the timings for the next chapter.
     */
    nextChapterAudioTimingsLink: string | null;

    /**
     * The link to the timings for the previous chapter.
     */
    previousChapterAudioTimingsLink: string | null;

    /**
     * The times in seconds at which each verse starts, in order.
     * 
     * The first number (index 0) is the time in the recording at which the first verse starts.
     * The second number (index 1) is the time in the recording at which the second verse starts.
     */
    verses: number[];
}

Example:

{
    "translationId": "BSB",
    "bookId": "GEN",
    "chapterNumber": 1,
    "reader": "hays",
    "audioLink": "https://openbible.com/audio/hays/BSB_01_Gen_001_H.mp3",
    "thisChapterLink": "/api/BSB/GEN/1.json",
    "nextChapterLink": "/api/BSB/GEN/2.json",
    "previousChapterLink": null,
    "thisChapterAudioTimingsLink": "/api/BSB/GEN/1.hays.audioTimings.json",
    "nextChapterAudioTimingsLink": "/api/BSB/GEN/2.hays.audioTimings.json",
    "previousChapterAudioTimingsLink": null,
    "verses": [3, 4.12, 10.4, 4.84, 5.76, 10.4, 7.32, 7.64, 8.72, 9.52, 10, 12.36, 11.72, 5.16, 12.24, 7.36, 10.68, 4.56, 9.6, 4.6, 8.68, 14.84, 9.64, 5.12, 12.4, 12.96, 16.44, 10, 14.56, 12.76, 15]
}