Skip to content

Web: metadata callbacks are declared but never invoked — wire Shaka timed metadata and chapters #118

Description

@puckey

What

src/web/NativeAudioBrowser.ts:160-162 declares three metadata callbacks as no-op defaults:

onChapterMetadata: (chapters: ChapterMetadata[]) => void = () => {}
onTrackMetadata: (metadata: TrackMetadata) => void = () => {}
onTimedMetadata: (metadata: TimedMetadata) => void = () => {}

Nothing in src/web/ ever calls them. src/features/metadata.ts documents all three unconditionally, so a consumer targeting web subscribes to an emitter that can never fire, with nothing to indicate that. The now-playing formatter's timedMetadata parameter is undefined on web for the same reason.

What's feasible

The web player is Shaka 4.x (src/web/TrackPlayer/Player.ts), attached to an <audio> element:

  • Timed metadata (HLS ID3 / DASH EMSG) — Shaka dispatches a metadata event. Map it to onTimedMetadata. (Present in the shipped bundle; the typed .d.ts has no typed event map for it, so confirm the payload shape against Shaka's docs when implementing.)
  • Chaptersplayer.getChapters(language) / getChaptersAsync(), plus Shaka's handling of chapters text tracks. Map to onChapterMetadata.
  • Static track metadata — no clean Shaka equivalent. ID3 frames observed at load could approximate it, but the semantics wouldn't match the native side.

What's not feasible

ICY (Icecast/Shoutcast) metadata on progressive HTTP streams. Those play through the browser's own pipeline, which strips the interleaved metadata and exposes no API for it. Supporting it would mean:

  1. fetching the stream with Icy-MetaData: 1;
  2. reading icy-metaint, which requires the origin to send Access-Control-Expose-Headers: icy-metaint;
  3. de-interleaving metadata blocks from the audio byte stream;
  4. feeding the remaining audio through MSE — ManagedMediaSource on iOS Safari.

That's a substantial subsystem whose success depends on per-origin CORS cooperation the library can't require. For consumers whose sources are predominantly ICY, this issue buys little — worth weighing before picking it up.

Proposal

  1. Wire onTimedMetadata and onChapterMetadata from Shaka.
  2. Add @platform documentation to all three, stating what does and doesn't arrive on web — specifically that ICY timed metadata never does.
  3. Leave onTrackMetadata inert but documented.

Verification

Needs an HLS stream carrying ID3 timed metadata; there's no such fixture in the repo today.


Relates to #97 (task 4).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions