/**
 * Copyright (c) Double Symmetry GmbH
 * Commercial use requires a license. See https://rntp.dev/pricing
 */

/**
 * Media URL accepts any of:
 * - A remote URL — `'https://...'`, `'http://...'`
 * - A `file://` URL — `'file:///var/mobile/Containers/.../song.mp3'`
 * - A bare absolute filesystem path — `'/var/mobile/.../song.mp3'`
 *   (treated as `file://` automatically)
 * - A React Native asset reference — `require('./song.mp3')`
 * - An object with a URI, optional HTTP `headers`, and an optional iOS
 *   `bundle` name for files shipped inside an `.bundle` resource:
 *   `{ uri: 'song.mp3', bundle: 'Sounds' }` resolves to `Sounds.bundle/song.mp3`.
 *
 * Bare names without a scheme or leading `/` (e.g. `'song.mp3'`) are
 * treated as platform asset names — iOS looks in `Bundle.main`, Android
 * looks up the matching `raw`/`drawable` resource.
 */
export type MediaUrl =
  | string
  | number
  | {
      uri: string | number;
      headers?: Record<string, string>;
      /**
       * iOS-only: the name (without `.bundle` suffix) of the `.bundle`
       * resource that contains the file. Equivalent to V4's bundle prefix.
       */
      bundle?: string;
    };

export interface MediaItem {
  /**
   * Stable identifier for this media item. Should be unique within your app.
   * If not provided, the URL will be used as the mediaId.
   * This maps to Media3's MediaItem.mediaId on Android.
   */
  mediaId?: string;
  /**
   * URL or URI to the media file. Can be a string or an object with options.
   */
  url: MediaUrl;
  title?: string;
  artist?: string;
  albumTitle?: string;
  artworkUrl?: MediaUrl;
  /**
   * Duration in seconds (optional hint for UI).
   */
  duration?: number;
  /**
   * Whether this is a live stream.
   *
   * When `true`, this item bypasses the cache and is played directly from the
   * origin, and it is never preloaded. Live segments are consumed once at the
   * live edge and never replayed, so caching them would only churn the cache
   * (evicting reusable on-demand content) and waste bandwidth.
   *
   * Set this for genuine live streams (radio, live events). You do **not** need
   * it just to play HLS — on-demand `.m3u8` streams are cached and play fine
   * without it. On iOS, live HLS is additionally detected automatically (a
   * playlist with no `#EXT-X-ENDLIST` is treated as live and its segments are
   * never cached), so forgetting the flag degrades gracefully; on Android,
   * detection relies on this flag, so set it to avoid live-segment cache churn.
   */
  isLive?: boolean;
  /**
   * MIME type of the media (e.g. 'audio/mpeg', 'audio/aac', 'application/x-mpegURL').
   * On Android, this is passed to ExoPlayer and to the Chromecast receiver. Set it
   * when the URL has no file extension (e.g. bare Icecast streams) so the Cast
   * receiver can identify the format — without it the track will be skipped.
   */
  mimeType?: string;
  /**
   * App-defined payload attached to this media item. Opaque to the player —
   * stored verbatim and returned unchanged by {@link getActiveMediaItem},
   * {@link getQueue}, and the {@link Event.MediaItemTransition} event.
   *
   * Use this for app-specific metadata that should travel with the item
   * (e.g. recommendation source, ISRC, internal IDs) without polluting the
   * typed fields.
   *
   * Must be JSON-serializable. Keep payloads small — large blobs are better
   * kept in your own JS state, keyed by {@link mediaId}.
   *
   * @since 5.1.0
   */
  extras?: Record<string, unknown>;
}