Add audio to sunder gutka

[indersinghkhalis]

Surface and cache audio for every bani ID in Sunder Gutka, map each verse ID to its start/end timestamp, and support multiple artist renditions. On first Play tap, the app should:

1. Quickly render UI by fetching only the lightweight manifest.
2. Download audio + verse-map via CDN-backed URLs in the background.
3. Cache with LRU + pin policy, guided by manifest version checks.
4. Stream fallback & adaptive chunked playback (HLS/DASH) until download completes.
5. Lazy-load non-default artist renditions on explicit user selection.

UI MOCKUPS COMING SOON.....

---

1. Metadata vs. Media Endpoints

• Manifest endpoint

  • GET /media/bani/:baniId/manifest → returns for each rendition:

    { "artist": "...", "versionHash": "...", "audioUrl": "...", "qualityLevels": [...] }

  • Extremely lightweight (≈1–2 KB), cacheable at edge.

• Verse-map endpoint

  • GET /media/bani/:baniId/verses?artist=…&version=… → ordered [ { verseId, startMs, endMs } ] JSON.

• Audio streaming

  • HLS/DASH playlist URLs via CDN for adaptive streaming until local download finishes.

2. CDN & Edge Caching

• Front both manifest and media files behind a global CDN.
• Pre-warm “hot” banis via analytics.
• Enable HTTP/2/3 + gzip.

3. Client-Side Architecture

• UI flow:

  1. On opening a Bani screen, fetch only the manifest.

  2. Render artist/quality selector + disabled “Play” button until manifest arrives.

  3. When user taps “Play Audio”:

     • Spawn background download tasks for chosen rendition’s audio & verse-map.
     • Immediately start streaming playback from CDN (HLS/DASH) while download proceeds.
     • Upon download completion, switch to local file for all subsequent plays.

• Cache layer:

  • Store paired assets (.mp3 + verse-map JSON) under one key.
  • Enforce max total size (e.g. 100 MB) with LRU eviction.
  • Allow “pin” on favorites to exempt from eviction.

• Versioning:

  • Compare local versionHash against manifest; auto-refresh if changed.

4. Multi-Artist & Quality Support

• Load only the default artist’s manifest; fetch other artists’ manifests on demand.
• Support bitrate selection (low/medium/high) before download starts.
• Seek logic by verse index (not raw time) so rendition switches stay in sync.

5. Offline & Error Handling

• Use background workers (iOS URLSession background, Android WorkManager).
• Graceful retry with exponential back-off on download failure; surface status to user.
• “Clear downloads” option removes all cached audio + verse maps.

6. Monitoring & Metrics

• Track manifest fetch vs. download counts, cache hit ratio, failure rates, storage used.
• Roll out via feature-flagged canary to 1% of users; monitor before full release.

---

Possible Subtasks

Backend / API / CDN

• Define & document /manifest and /verses endpoints in OpenAPI / Swagger. We are going to combine this with existing API that gives us audio files for sttm-web.
• Implement manifest generator including versionHash & multi-quality URLs.
• Store verse-map blobs in a document store.
• Configure CDN edge-caching rules & pre-warm hot banis.
• Add automated manifest pre-warm job based on analytics.

Client (iOS, Android)

• Fetch only manifest on Bani screen open; render artist/quality UI.

• On “Play Audio” tap:

  • Download audio + verse-map off-main-thread; start streaming fallback immediately.
  • Switch to local playback once download completes.

• Implement LRU + pin-to-keep cache logic with max-size enforcement.

• Verse sync & highlighting by verse index; tapping a verse seeks playback.

• On rendition switch: compare verse indices, fetch verse-map if needed, seek.

• Expose “Clear all downloads” in Settings.

Streaming & Quality

• Integrate HLS/DASH player fallback for streaming before/after download.
• Expose quality selector; map to playlist URLs in manifest.

Testing & QA

• Unit/API tests for manifest versioning & verse-map integrity.
• Integration tests: manifest → Play tap → download + streaming → offline play + highlight + seek.
• E2E canary test on 1% of users; monitor metrics for errors & cache use.

Docs & Rollout

• Publish API docs with manifest/verses schemas.

• Update client-SDK README for audio feature.

• Draft release notes emphasizing:

  • “On-demand download on Play tap”
  • “Adaptive streaming + background downloads”
    More marketing level updates coming soon

---

This ensures that audio assets are only fetched when needed, minimizes wasted bandwidth, and keeps the core app flow lean for users who choose to ignore audio.

[amitojsingh]

@MySmilingTurban @indersinghkhalis Are we using this repository for audio files.

https://github.com/KhalisFoundation/sikhiFM

[MySmilingTurban]

@amitojsingh veerji, this is the one deployed at audio.sikhitothemax.org

https://github.com/KhalisFoundation/sttm-audio-api (docker branch is deployed)

[amitojsingh]

@MySmilingTurban Veer Ji, which database is being used for this? I see sttm_web_media—is that the correct one?

[MySmilingTurban]

yes, that's the one

[amitojsingh]

Are we currently using AWS SkySQL for this?
It looks like this hasn’t been migrated to Azure yet — the audio is still being served from:

https://sikhifm-audio.s3.us-west-1.amazonaws.com/

Can you please confirm?
@MySmilingTurban @indersinghkhalis

[MySmilingTurban]

Hanji, the audio urls are hosted on that s3 bucket

[amitojsingh]

@indersinghkhalis Veer ji, I’ve prepared the schema for the audio feature in Sundar Gutka. We’ll need to add three additional tables to support it.

① artists — List of all raagis / narrators
CREATE TABLE artists (
    artist_id        INTEGER PRIMARY KEY,
    display_name     TEXT    NOT NULL,
    version_hash     TEXT    NOT NULL,
    base_audio_url   TEXT    NOT NULL,
    quality_levels   TEXT    NOT NULL
);

This is where we store info about each artist.

② shabad_renditions — Which artist recorded which Shabad
CREATE TABLE shabad_renditions (
    shabad_id        INTEGER NOT NULL,
    artist_id        INTEGER NOT NULL,
    PRIMARY KEY (shabad_id, artist_id),
    FOREIGN KEY (shabad_id)  REFERENCES shabads(shabad_id),
    FOREIGN KEY (artist_id)  REFERENCES artists(artist_id)
);

③ verse_timings — Start and end times for each verse (per artist)
CREATE TABLE verse_timings (
    verse_id         INTEGER NOT NULL,
    artist_id        INTEGER NOT NULL,
    start_ms         INTEGER NOT NULL,
    end_ms           INTEGER NOT NULL,
    PRIMARY KEY (verse_id, artist_id),
    FOREIGN KEY (verse_id)   REFERENCES verses(verse_id),
    FOREIGN KEY (artist_id)  REFERENCES artists(artist_id)
);

This stores timing info for each verse, specific to the artist’s rendition.
This makes it easy to highlight lines, auto-scroll, or seek to a specific verse during playback.

Let me know if you have any suggestions.