Skip to content

Add audio timings API endpoint and documentation - #66

Open
KallynGowdy wants to merge 1 commit into
mainfrom
claude/audio-timings-docs-2qrxey
Open

KallynGowdy wants to merge 1 commit into
mainfrom
claude/audio-timings-docs-2qrxey

Conversation

@KallynGowdy

Copy link
Copy Markdown
Collaborator

Summary

This PR adds comprehensive support for audio timings across the Bible API documentation. It introduces a new endpoint for retrieving per-verse audio timing data and updates all related chapter endpoints to include audio timing links and data.

Key Changes

  • New Endpoint: Added "Get the Audio Timings for a Chapter" endpoint (GET /api/{translation}/{book}/{chapter}.{reader}.audioTimings.json) that returns per-verse start times in seconds for a specific reader's narration

    • Includes full TypeScript interface definition (TranslationBookChapterAudioTimings)
    • Provides code examples and JSON response examples
    • Enables clients to highlight verses during audio playback
  • Standard Format Updates (docs/reference/translations/standard.md):

    • Added thisChapterAudioTimings, nextChapterAudioTimings, and previousChapterAudioTimings fields to TranslationBookChapter interface
    • Created new TranslationBookChapterAudioTimingsLinks interface to map reader IDs to audio timing file URLs
    • Updated TranslationCompleteChapter to include embedded audio timings data via new TranslationBookChapterAudioTimingsMap interface
    • Updated example JSON responses to show audio timing links and data
  • Simplified Format Updates (docs/reference/translations/simplified.md):

    • Added thisChapterAudioTimings, nextChapterAudioTimings, and previousChapterAudioTimings fields to SimpleTranslationBookChapter interface
    • Updated documentation to clarify that audio timings are the same regardless of chapter format
    • Updated example JSON responses to show audio timing links
    • Fixed type reference in SimpleTranslationCompleteChapter to use TranslationBookChapterAudioTimingsMap

Notable Implementation Details

  • Audio timings are reader-specific and stored separately from chapter data, allowing efficient reuse across different chapter formats
  • The complete translation download embeds actual timing arrays rather than links, maintaining the design principle of having all data in one file
  • Timing data is format-agnostic (same file for both standard and simplified chapter formats)
  • Verse end times are implicit (start of next verse or end of audio file), reducing data redundancy

https://claude.ai/code/session_01M4cbAY2rUoVD6LqXaHTXcg

Add a "Get the Audio Timings for a Chapter" section covering
/api/{translation}/{book}/{chapter}.{reader}.audioTimings.json, and fill in
the thisChapterAudioTimings/next/previous link fields that were already part
of the chapter and simplified-chapter response schemas but missing from the
docs. Also document the raw per-verse timings embedded in the complete
translation downloads (renamed to TranslationBookChapterAudioTimingsMap to
avoid colliding with the new per-endpoint type name), correcting the
complete-chapter interface to list its actual fields instead of extending
the full per-chapter type.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M4cbAY2rUoVD6LqXaHTXcg
@KallynGowdy
KallynGowdy force-pushed the claude/audio-timings-docs-2qrxey branch from 7a2bbfe to 41860b3 Compare September 4, 2026 15:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants