Integration: push lyrics + cross-platform metadata to iLyricsDB/iHymns on Apple Music download

[Salem874]

Goal

Extend MeedyaDL's post-download enrichment to push lyrics + timing + cross-platform metadata to the shared lyrics-ingest endpoint (iLyricsDB canonical receiver, or iHymns satellite) when a track is downloaded from Apple Music. Backend handles normalization + dedupe; MeedyaDL just supplies the payload.

Format

See the iLyricsDB / iHymns lyrics-ingest cards for the contract. MeedyaDL supplies: song metadata (title/artist/album/ISRC/UPC/duration from the Apple Music API), raw TTML (GAMDL Apple-Music download, preserves word timing), optional alternative formats (Enhanced LRC, Lyricsfile YAML), and cross-platform IDs (MusicBrainz recording/work via optional AcoustID+MB lookup; Spotify/YouTube Music/Genius URLs).

Approach

1. New Rust service src-tauri/src/services/lyrics_ingest_client.rs — HTTP POST with exponential backoff; handle 429/401/transient; queue + retry failed (max 3) before logging failed; honour the opt-in setting.
2. Hook after the lyrics-finalization enrichment step in download_queue.rs: push_to_lyrics_backend(track, lyrics, metadata) with the user's API token.
3. Config in config_service.rs: endpoint URL + bearer token. Settings → Integrations UI: opt-in checkbox (default OFF for privacy), token field, status badge (valid/expired/not-configured), "Test connection" button.
4. Activity log: per-push attempt (title, artist, status, error).
5. Optional cross-platform enrichment: MusicBrainz (AcoustID), Spotify/YT-Music/Genius URLs into the payload.

Acceptance

• Settings UI renders the integration section; "Test connection" validates the token before real pushes; expired token shows status.
• A downloaded track with TTML is pushed on completion when opt-in is enabled; activity log shows pushed/skipped/failed; failures retried up to 3×.
• Cross-platform IDs included; backend responds with match status + id.
• Runs silently in the background; opt-in only, disablable anytime.

---

Part of the multi-format import/export + lyrics-ingest roadmap (2026-06-04). Priority: high. Foundation #1047 (normalized lyrics model: tblLyrics/tblLyricLines/tblLyricWords) has landed; the dedupe-on-import matcher is the shared base for every importer. All schema changes follow CLAUDE.md rule #19 (schema.sql + migration-registry + real probe).

[Salem874]

Core implemented in 94721a7 (local branch claude/lyrics-ingest-push-907, not pushed — awaiting review + a cargo check).

Done:

• src-tauri/src/services/lyrics_ingest_client.rs (new) — mirrors the odesli_service HTTP pattern (reqwest via utils::http_client, Result<_, String>):
  • LyricsIngestPayload (serde camelCase): ttml + source + metadata (title/artist/album/isrc/upc/durationMs/appleMusicUrl) + optional crossPlatform map + optional explicit songId.
  • push_lyrics(endpoint, token, &payload) — POST with exponential backoff; 401/403 (bad token) + 400/422 (bad payload) fail fast, 429/5xx/network retry up to 3×; returns the backend match JSON.
  • test_connection(endpoint, token) — probe ("not 401/403" ⇒ token OK); backs the "Test connection" button.
• models/settings.rs — lyrics_ingest_enabled (default false) + lyrics_ingest_endpoint + lyrics_ingest_token (struct + manual Default).
• commands/settings.rs + lib.rs — test_lyrics_ingest_connection #[tauri::command] registered.
• services/mod.rs — module registered.

Remaining (acceptance items not yet wired):

1. download_queue hook — call push_lyrics(...) after the lyrics-finalization enrichment step, opt-in-guarded, best-effort (never block the download), reading each .ttml sidecar in output_path and building the payload from the track metadata; log each attempt via emit_download_log/warn/error.
2. Settings → Integrations UI (frontend) — opt-in checkbox (default OFF), endpoint + token fields, status badge (valid/expired/not-configured via test_lyrics_ingest_connection), "Test connection" button.
3. Cross-platform enrichment — fill LyricsIngestPayload.cross_platform from the existing MusicBrainz/Odesli/Genius enrichment.

⚠️ Backend contract gap (cross-repo): the iHymns endpoint (#1064) currently requires an explicit songId, but MeedyaDL only has Apple Music metadata. The "backend handles dedupe + matching, responds with match status + id" half needs the endpoint to resolve/create a song from the metadata (title/artist/ISRC). The payload already carries that metadata; flagged on #1064 as the matching follow-up. Until then, pushes only land for tracks where songId is known.

NOTE: the Rust matches the existing service/command/settings patterns but was not compile-verified here (a Tauri cargo check pulls hundreds of deps) — run cargo check in src-tauri/ before merge.

[Salem874]

Push hook implemented in b0aee02 (local branch claude/lyrics-ingest-push-907) — the integration now actually fires on download.

• lyrics_ingest_client::push_album_lyrics(app, download_id, album_dir, album_metadata, cross_platform_urls) — opt-in-guarded (loads AppSettings, bails unless enabled + endpoint + token set); enumerates the .ttml sidecars (skips AppleDouble ._); matches each to a track in AlbumMetadata (leading track number 01…/1-01…, then fuzzy title); builds the LyricsIngestPayload (songId: None → the backend resolves by metadata — see iHymns #1064; title/artist/album/isrc/upc/durationMs/appleMusicUrl + crossPlatform) and push_lyrics()es it. Best-effort: errors → emit_download_warn, never propagated; a per-album summary line logged.
• download_queue.rs: one call in the enrichment task, placed just before write_manifest so it can borrow cross_platform_urls before the manifest write consumes it.

Symbols verified against the tree (config_service::load_settings, emit_download_* sigs, AlbumMetadata/TrackMetadata fields); rustfmt parses clean. Not full-cargo check'd here (Tauri pulls hundreds of deps) — run cargo check in src-tauri/ before merge; an adversarial review pass is checking the borrows/types now.

Remaining for #907: the Settings → Integrations UI (opt-in toggle, endpoint + token fields, status badge via the test_lyrics_ingest_connection command, Test-connection button) and optionally populating crossPlatform from the existing MusicBrainz/Odesli enrichment. The backend end-to-end now works for the songId-less flow (iHymns #1064 resolves/creates by title/ISRC).

[Salem874]

Complete + verified (local branch claude/lyrics-ingest-push-907, 3 commits).

The Settings → Integrations UI landed (f1b7c63): a "Lyrics Ingest (iLyricsDB / iHymns)" section on the Lyrics settings tab — opt-in toggle (default OFF), endpoint URL + API-token (password) inputs, and a Test connection button wired to test_lyrics_ingest_connection with a success/rejected status line.

All acceptance items done:

• ✅ Rust ingest client (lyrics_ingest_client.rs: push_lyrics w/ backoff, test_connection) — 94721a7
• ✅ Config (lyrics_ingest_enabled/endpoint/token, default OFF) + test_lyrics_ingest_connection command — 94721a7
• ✅ Download-queue hook (push_album_lyrics in the enrichment, opt-in, best-effort, activity-logged) — b0aee02
• ✅ Settings UI (toggle / endpoint / token / Test connection) — f1b7c63
• ✅ Cross-platform IDs: the hook already forwards the enrichment's cross_platform_urls (Odesli/MusicBrainz) into the payload's crossPlatform.

Verification (this session): cargo check on src-tauri/ → 0 errors / 0 warnings; frontend tsc --noEmit → 0 errors; eslint → clean; vitest → 27/27 pass (settingsStore + LyricsTab). The backend resolves the song from the pushed metadata (iHymns #1064: ISRC → title → create), so the songId-less Apple-Music → backend flow works end-to-end.

Ready for review + merge (PR base alpha when you're ready).