@ngxsp/core 0.0.1-next.0 → 0.1.0

package/index.d.cts

@@ -140,6 +140,11 @@ interface PlayerSource {
      * Optional identifier for progress/metadata/subtitles lookup.
      */
     contentId?: string;
+    /** Optional display metadata, used by UI skins (especially audio mode). */
+    title?: string;
+    subtitle?: string;
+    artist?: string;
+    album?: string;
     /**
      * Optional sidecar URL for local metadata (json/txt) or subtitles.
      */
@@ -170,9 +175,15 @@ interface NextEpisodeHint {
 }
 interface UiConfig {
     /** Optional UI skin preset (default: classic) */
-    skin?: 'classic' | 'netflix';
+    skin?: 'classic' | 'vod' | 'edition';
     /** Optional display title used by some skins */
     title?: string;
+    /** Optional alternate display title (falls back from `title`). */
+    displayTitle?: string;
+    /** Optional subtitle shown under the title (e.g. audio "now playing"). */
+    subtitle?: string;
+    /** Optional longer description shown by some skins. */
+    description?: string;
     ratios: AspectRatioMode[];
     defaultRatio: AspectRatioMode;
     keyboardShortcuts: boolean;
@@ -395,6 +406,40 @@ type PlayerEvent = {
     id?: string;
 };
 
+/**
+ * Sensible, framework-agnostic defaults for the mandatory sub-configs of
+ * {@link PlayerConfig}. They mirror the values used by the existing
+ * consumers (local audio/video players) so a brand new integration can get a
+ * valid config without restating every field.
+ */
+declare const DEFAULT_PROGRESS_CONFIG: ProgressConfig;
+declare const DEFAULT_UI_CONFIG: UiConfig;
+declare const DEFAULT_RESILIENCE_CONFIG: ResilienceConfig;
+declare const DEFAULT_SUBTITLES_CONFIG: SubtitlesConfig;
+declare const DEFAULT_METADATA_CONFIG: MetadataConfig;
+declare const DEFAULT_ADS_CONFIG: AdsConfig;
+/**
+ * Build a complete, type-safe {@link PlayerConfig} from a minimal set of
+ * overrides. Only `source` is required; the mandatory sub-configs
+ * (`progress`, `ui`, `resilience`, `subtitles`, `metadata`, `ads`) are filled
+ * with the defaults above and shallow-merged with any override provided.
+ *
+ * Optional top-level fields (`profile`, `drm`, `series`, `playlist`,
+ * `offline`, `remoteConfig`, ...) are passed through untouched when present.
+ *
+ * @example
+ * ```ts
+ * const config = createDefaultConfig({
+ *   source: { type: 'hls', url: 'https://cdn.example.com/movie.m3u8' },
+ *   drm: { keySystems: { 'com.widevine.alpha': { licenseServerUrl: 'https://drm/widevine' } } },
+ *   subtitles: { enabled: true, providers: ['local'], preferredLang: 'fr' },
+ * });
+ * ```
+ */
+declare function createDefaultConfig(overrides: Partial<PlayerConfig> & {
+    source: PlayerSource;
+}): PlayerConfig;
+
 type EngineEvent = {
     type: 'timeupdate';
     currentTime: number;
@@ -545,7 +590,6 @@ interface PlayerSnapshot {
  */
 type PlayerDiagnostics = DiagnosticsSnapshot;
 declare class PlayerFacade {
-    private chooseEngine;
     private ports;
     private engineFactories;
     private engineId;
@@ -578,10 +622,24 @@ declare class PlayerFacade {
     readonly playlistIndex$: Observable<number | null>;
     private playlist;
     private playlistKey;
-    private externalVttUrl?;
-    constructor(chooseEngine?: (cfg: PlayerConfig) => PlaybackEngine, ports?: PlayerPorts);
+    /** Subtitles loaded from files, shown by the host from `captionCues$` rather than by the browser. */
+    private externalTexts;
+    private externalTextCount;
+    /** The text track picked here; undefined while the engine's own choice stands. */
+    private textSelection;
+    private engineTracks;
+    private offCueChange?;
+    private captionCuesSub;
+    /** The cues of the loaded subtitles to show now: the host draws them over the video. */
+    readonly captionCues$: Observable<TextTrackCue[]>;
+    constructor(ports?: PlayerPorts);
     attach(videoEl: HTMLVideoElement, plugins: PlayerPlugin[] | undefined, config: PlayerConfig, ports?: Partial<PlayerPorts>, engines?: EngineFactory[]): void;
     load(config: PlayerConfig, opts?: LoadOptions): Promise<void>;
+    /**
+     * Replaces the engines the next load chooses from (a remote device session starting or ending). The native engine is
+     * always kept as fallback so progressive and local playback never breaks; call `load` or `reload` to switch now.
+     */
+    setEngines(engines?: EngineFactory[]): void;
     reload(opts?: LoadOptions): Promise<void>;
     next(): Promise<void>;
     previous(): Promise<void>;
@@ -598,10 +656,24 @@ declare class PlayerFacade {
     private toPlayerError;
     play(): Promise<void>;
     pause(): Promise<void>;
-    seekTo(timeSec: number): Promise<void>;
+    /**
+     * Seeks the attached engine. Resolves to false when no engine can take the request yet (a load is replacing it), so
+     * callers keep the position and apply it once the media is ready instead of assuming it happened.
+     */
+    seekTo(timeSec: number): Promise<boolean>;
     setRate(rate: number): Promise<void>;
     setVolume(volume: number): Promise<void>;
+    /**
+     * Shows a text track: one of the engine's, one loaded from a file (`addExternalTextTrack`), or none (null).
+     * "external" still names the last file loaded.
+     */
     setTextTrack(trackId: string | null): Promise<void>;
+    /** Adds subtitles read from a file (WebVTT) to the media playing, and shows them; resolves to the new track's id. */
+    addExternalTextTrack(text: {
+        label: string;
+        language?: string;
+        vtt: string;
+    }): Promise<string>;
     setAudioTrack(trackId: string | null): Promise<void>;
     setVideoTrack(trackId: string | null): Promise<void>;
     setAspectRatio(_mode: AspectRatioMode): void;
@@ -613,7 +685,11 @@ declare class PlayerFacade {
     diagnostics(): PlayerDiagnostics;
     setExternalVttTrack(lang: string, vtt: string): Promise<void>;
     setMetadata(meta: VideoMetadata): void;
-    private ensureExternalTrack;
+    /** Shows `shown` (its cues go to `captionCues$`, the browser draws none) and turns the other files' subtitles off. */
+    private showExternalText;
+    private clearExternalTextTracks;
+    /** The engine's tracks and the loaded subtitles, the text track picked here marked active. */
+    private emitTracks;
     private handleEngineEvent;
     private tryRestoreStartTime;
 }
@@ -640,6 +716,7 @@ declare class NativeEngine implements PlaybackEngine {
     readonly id = "native";
     private video?;
     private listeners;
+    private emit;
     attach(videoEl: HTMLVideoElement): Promise<void>;
     load(source: PlayerSource, opts?: {
         startTimeSec?: number;
@@ -700,6 +777,21 @@ declare class LocalSubtitleProvider implements SubtitleProvider {
     fetch(candidate: SubtitleCandidate): Promise<string | ArrayBuffer>;
 }
 
+/**
+ * Subtitle files the viewer loads next to a video: SubRip (.srt) or WebVTT (.vtt), in whatever encoding they were
+ * saved (UTF-8 today, Windows-1252 for many older French files). The player reads WebVTT only, so SubRip is turned
+ * into it.
+ */
+/** The text of a subtitle file: UTF-8 (with or without its byte order mark), else Windows-1252. */
+declare function decodeSubtitleBytes(bytes: Uint8Array): string;
+/** WebVTT from the text of a .vtt or .srt file. */
+declare function subtitleTextToVtt(text: string): string;
+/** The subtitle's name and language, from its file name: "Film.fr.srt" is "Film", in French. */
+declare function describeSubtitleFile(fileName: string): {
+    label: string;
+    language?: string;
+};
+
 interface CacheStore {
     get<T>(key: string): Promise<T | null>;
     set<T>(key: string, value: T, ttlMs: number): Promise<void>;
@@ -783,6 +875,8 @@ declare class ResiliencePlugin implements PlayerPlugin {
     readonly id = "resilience";
     private attempts;
     private recovering;
+    /** Bumped by every load: a retry only reloads the media that failed, never one loaded since. */
+    private loadGeneration;
     onLoadStart(ctx: PlayerContext): Promise<void>;
     onError(ctx: PlayerContext, err: PlayerError): Promise<void>;
     private health;
@@ -803,7 +897,7 @@ interface SsaiManifestRewriteConfig {
 declare function createSsaiManifestRewritePlugin(): PlayerPlugin;
 
 type TelemetryLevel = 'debug' | 'info' | 'warn' | 'error';
-type TelemetryEvent = 'player:init' | 'player:attach' | 'player:source_set' | 'player:engine_selected' | 'player:load_start' | 'player:load_ok' | 'player:load_fail' | 'player:play_request' | 'player:play_ok' | 'player:play_fail' | 'player:pause' | 'player:timeupdate' | 'player:ended' | 'player:error_nonfatal' | 'player:error_fatal' | 'player:playing' | 'qoe:first_frame' | 'qoe:rebuffer_start' | 'qoe:rebuffer_end' | 'qoe:summary' | 'player:auto_next' | 'player:playlist_index' | 'ads:break_start' | 'ads:break_end' | 'ads:ad_start' | 'ads:ad_end' | 'ssai:manifest_rewrite';
+type TelemetryEvent = 'player:init' | 'player:attach' | 'player:source_set' | 'player:engine_selected' | 'player:load_start' | 'player:load_ok' | 'player:load_fail' | 'player:play_request' | 'player:play_ok' | 'player:play_fail' | 'player:play_aborted' | 'player:pause' | 'player:timeupdate' | 'player:ended' | 'player:error_nonfatal' | 'player:error_fatal' | 'player:playing' | 'qoe:first_frame' | 'qoe:rebuffer_start' | 'qoe:rebuffer_end' | 'qoe:summary' | 'player:auto_next' | 'player:playlist_index' | 'ads:break_start' | 'ads:break_end' | 'ads:ad_start' | 'ads:ad_end' | 'ssai:manifest_rewrite';
 interface TelemetrySample {
     ts: number;
     level: TelemetryLevel;
@@ -843,6 +937,163 @@ declare function applyEngineProfileToSource(source: PlayerSource, profile?: Engi
 
 declare function createNativeEngineFactory(): EngineFactory;
 
+/**
+ * Playing on another device of the local network: a DLNA renderer (TV, network speaker), a Chromecast, an AirPlay
+ * receiver. Each protocol exposes the same session, so the apps drive a remote device like their own player.
+ */
+type RemotePlaybackKind = 'dlna' | 'chromecast' | 'airplay';
+/** What is sent to the device. The address must be reachable from the device itself, not only from the app. */
+interface RemotePlaybackMedia {
+    url: string;
+    contentType: string;
+    kind: 'audio' | 'video';
+    title: string;
+    artist?: string;
+    album?: string;
+    artworkUrl?: string;
+    durationSec?: number;
+    /** Position to start from, to continue what the app was playing. */
+    startSec?: number;
+    /** Radios and live streams: no duration, no seeking. */
+    live?: boolean;
+    /**
+     * A stream the app converts on the fly into a format the device reads. It cannot seek: it starts where it is asked
+     * to, at `at(position)`, and the device counts from there.
+     */
+    conversion?: {
+        at(startSec: number): string;
+    };
+}
+type RemotePlayerState = 'idle' | 'loading' | 'buffering' | 'playing' | 'paused' | 'stopped';
+/**
+ * Why a device did not play a media, for the apps to explain it in their own words:
+ * - `unsupported-format`: the device does not read this format at all; nothing was sent (`format` names it);
+ * - `load-failed`: the device tried and gave up (codec it cannot decode, address it cannot reach);
+ * - `timeout`: the device did not answer.
+ */
+type RemotePlaybackErrorCode = 'unsupported-format' | 'load-failed' | 'timeout';
+declare class RemotePlaybackError extends Error {
+    readonly code: RemotePlaybackErrorCode;
+    readonly format?: string | undefined;
+    constructor(code: RemotePlaybackErrorCode, message: string, format?: string | undefined);
+}
+/** The player error code a device failure is reported under: `REMOTE_UNSUPPORTED_FORMAT`, `REMOTE_LOAD_FAILED`… */
+declare function remotePlaybackErrorCode(code: RemotePlaybackErrorCode): string;
+/**
+ * The device failure behind a player error, if it is one: raised when the media was sent (a `RemotePlaybackError`),
+ * or reported later by the device while playing (`REMOTE_PLAYBACK`, which means it gave up on the media).
+ */
+declare function remotePlaybackFailure(error: {
+    code?: string;
+    details?: unknown;
+} | null | undefined): {
+    code: RemotePlaybackErrorCode;
+    format?: string;
+} | null;
+interface RemotePlaybackStatus {
+    state: RemotePlayerState;
+    positionSec?: number;
+    durationSec?: number;
+    /** 0 to 1. */
+    volume?: number;
+    /** Set when the device gave up on the media (unreachable address, unsupported format). */
+    error?: string;
+    /** The media played to its end (devices that tell it apart from a stop). */
+    ended?: boolean;
+}
+interface RemotePlaybackSession {
+    readonly kind: RemotePlaybackKind;
+    load(media: RemotePlaybackMedia): Promise<void>;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    seek(positionSec: number): Promise<void>;
+    /** 0 to 1. */
+    setVolume(level: number): Promise<void>;
+    /** Ends playback on the device. */
+    stop(): Promise<void>;
+    status(): Promise<RemotePlaybackStatus>;
+    /** Leaves the device; what it plays keeps playing unless `stop` was called. */
+    close(): Promise<void>;
+}
+/** `H:MM:SS` as UPnP and most devices write positions. */
+declare function formatRemoteClock(seconds: number): string;
+/** `H+:MM:SS[.F+]` to seconds; undefined for "NOT_IMPLEMENTED" and other placeholders. */
+declare function parseRemoteClock(value: string | undefined): number | undefined;
+
+interface RemotePlaybackEngineOptions {
+    /** The device session media goes to; the engine only claims sources while one is set. */
+    session: () => RemotePlaybackSession | null;
+    /** What to send for a source: an address the device can reach, its type and display metadata. */
+    media: (source: PlayerSource, startSec: number) => RemotePlaybackMedia | Promise<RemotePlaybackMedia>;
+    /**
+     * The same media converted on the fly (`conversion`), for a device that refuses it as it is: a format or a codec
+     * it does not read. Only where the app can convert; the device gets it once it has refused the original.
+     */
+    convertedMedia?: (source: PlayerSource, startSec: number) => Promise<RemotePlaybackMedia>;
+    /** How often the device is asked where it is. */
+    pollMs?: number;
+    /** Above the native (0) and adaptive engines, so a session takes every source. */
+    priority?: number;
+}
+/**
+ * Plays through a remote device (DLNA renderer, Cast device) with the player's own controls. Like a media element,
+ * loading prepares the media and playing starts it: the device receives it on the first `play`, from the position
+ * reached until then. The device's position and state come back by polling. A device that refuses a media gets it
+ * converted when the app can convert it; a converted stream seeks by starting again from the new position.
+ */
+declare function createRemotePlaybackEngineFactory(options: RemotePlaybackEngineOptions): EngineFactory;
+declare class RemotePlaybackEngine implements PlaybackEngine {
+    private readonly options;
+    readonly id = "remote";
+    private readonly listeners;
+    private session;
+    private source;
+    /** What the device plays, as the app described it. */
+    private media;
+    private startSec;
+    private sent;
+    /** The device played the media to its end: it closed it, and only takes it again sent anew. */
+    private finished;
+    private durationSec;
+    private positionSec;
+    /** Where a converted stream starts in the media: the device counts from there. */
+    private offsetSec;
+    /** Furthest position the device reported since the media was sent: an end before any progress is a refusal. */
+    private furthestSec;
+    private conversionTried;
+    private lastState;
+    private timer;
+    private polling;
+    private failures;
+    private destroyed;
+    constructor(options: RemotePlaybackEngineOptions);
+    attach(videoEl: HTMLVideoElement): Promise<void>;
+    load(source: PlayerSource, opts?: LoadOptions): Promise<void>;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    seekTo(timeSec: number): Promise<void>;
+    setVolume(volume: number): Promise<void>;
+    setPlaybackRate(_rate: number): Promise<void>;
+    setTextTrack(_trackId: string | null): Promise<void>;
+    setAudioTrack(_trackId: string | null): Promise<void>;
+    setVideoTrack(_trackId: string | null): Promise<void>;
+    getTracks(): Promise<MediaTrack[]>;
+    onEvent(cb: (event: EngineEvent) => void): () => void;
+    /** Stops following the device; the session stays open for the next media. */
+    destroy(): Promise<void>;
+    /** Reads the device once; exposed for hosts and tests that do not want to wait for the timer. */
+    poll(): Promise<void>;
+    private restartAt;
+    /** Sends a media to the device from a position of it; a converted stream starts there and counts from 0. */
+    private send;
+    private convertible;
+    /** The device gave up on the media as it is: it gets it converted, from where it was. */
+    private convertAfterRefusal;
+    private startPolling;
+    private requireSession;
+    private emit;
+}
+
 declare function applyRemoteConfig(cfg: PlayerConfig, ports: Partial<PlayerPorts>): Promise<{
     config: PlayerConfig;
     applied: boolean;
@@ -850,4 +1101,1391 @@ declare function applyRemoteConfig(cfg: PlayerConfig, ports: Partial<PlayerPorts
     source: 'cache' | 'network' | 'none';
 }>;
 
-export { type AdsConfig, type AdsMode, type AspectRatioMode, type CacheStore, type CapabilityReport, ConsoleLogPort, DefaultCacheStore, type DiagnosticsEngineInfo, type DiagnosticsSnapshot, type DrmConfig, type EngineEvent, type EngineFactory, type EngineProfileHints, type EngineProfileId, type EpisodeItem, type HttpPort, type LoadOptions, LocalMetadataProvider, LocalSubtitleProvider, type LogPort, type MediaTrack, MemoryStoragePort, type MetadataConfig, type MetadataHint, type MetadataMatch, type MetadataProvider, NativeEngine, type NextEpisodeHint, NoopTelemetryPort, type PlaybackCapabilities, type PlaybackEngine, type PlayerCommand, type PlayerConfig, type PlayerContext, type PlayerDiagnostics, type PlayerError, type PlayerErrorCode, type PlayerEvent, type PlayerEventBus, PlayerFacade, type PlayerPlugin, type PlayerPorts, type PlayerSnapshot, type PlayerSource, type PlayerState, type PlayerTime, type ProgressConfig, type ProgressMode, ProgressPlugin, type RemoteConfigConfig, type RemoteConfigPayload, type ResilienceConfig, ResiliencePlugin, type SeriesConfig, SimpleEventBus, type SkipSegment, type SourceType, type SsaiManifestRewriteConfig, type StoragePort, type SubtitleCandidate, type SubtitleHint, type SubtitleProvider, type SubtitleQuery, type SubtitlesConfig, type TelemetryEvent, type TelemetryLevel, type TelemetryPort, type TelemetrySample, type UiConfig, type Unsubscribe, type VideoMetadata, applyEngineProfileToSource, applyRemoteConfig, createCapabilityReport, createDefaultCapabilities, createDefaultPorts, createMediaDecodingReport, createNativeEngineFactory, createSsaiManifestRewritePlugin, detectPlaybackCapabilities, getEngineProfileHints, isCategorizedEventType, selectEngine };
+type MediaKind = 'audio' | 'video';
+interface MediaArtwork {
+    src: string;
+    kind?: 'cover' | 'poster' | 'backdrop' | 'thumbnail';
+}
+interface MediaProgress {
+    currentTimeSec: number;
+    durationSec?: number;
+    updatedAt: number;
+}
+interface MediaItem {
+    id: string;
+    kind: MediaKind;
+    title: string;
+    path?: string;
+    url?: string;
+    subtitle?: string;
+    artwork?: MediaArtwork[];
+    durationSec?: number;
+    sizeBytes?: number;
+    mtimeMs?: number;
+}
+
+interface AudioTrack extends MediaItem {
+    kind: 'audio';
+    artist?: string;
+    album?: string;
+    albumArtist?: string;
+    genre?: string;
+    trackNo?: number;
+    discNo?: number;
+    year?: number;
+}
+interface AudioAlbum<TTrack extends AudioTrack = AudioTrack> {
+    id: string;
+    title: string;
+    artist?: string;
+    artwork?: string;
+    year?: number;
+    tracks: TTrack[];
+}
+interface AudioArtist<TTrack extends AudioTrack = AudioTrack> {
+    id: string;
+    name: string;
+    artwork?: string;
+    tracks: TTrack[];
+}
+interface AudioGenre<TTrack extends AudioTrack = AudioTrack> {
+    id: string;
+    name: string;
+    tracks: TTrack[];
+}
+interface AudioPlaylist {
+    id: string;
+    name: string;
+    description?: string;
+    artwork?: string;
+    trackIds: string[];
+}
+type AudioPlaylistRef = AudioPlaylist;
+interface AudioLibrarySnapshot<TTrack extends AudioTrack = AudioTrack> {
+    tracks: TTrack[];
+    albums: AudioAlbum<TTrack>[];
+    artists: AudioArtist<TTrack>[];
+    genres: AudioGenre<TTrack>[];
+    playlists: AudioPlaylist[];
+}
+interface AudioLibrarySearchResult<TTrack extends AudioTrack = AudioTrack> extends AudioLibrarySnapshot<TTrack> {
+    active: boolean;
+    query: string;
+    directTrackIds: string[];
+    matchedTrackIds: string[];
+    matchedAlbumIds: string[];
+    matchedArtistIds: string[];
+    matchedGenreIds: string[];
+    matchedPlaylistIds: string[];
+}
+declare function createAudioLibrarySnapshot<TTrack extends AudioTrack>(tracks: readonly TTrack[], playlists?: readonly AudioPlaylist[]): AudioLibrarySnapshot<TTrack>;
+declare function searchAudioLibrarySnapshot<TTrack extends AudioTrack>(snapshot: AudioLibrarySnapshot<TTrack>, searchTerm: string): AudioLibrarySearchResult<TTrack>;
+declare function normalizeAudioSearchText(value: string): string;
+declare function audioTrackMatchesSearch(track: AudioTrack, searchTerm: string): boolean;
+
+/** Number of tracks whose metadata was changed, per kind of correction. */
+interface AudioMetadataCorrections {
+    /** Artist or album artist spelled differently from the rest of the library, or prefixed by a track number. */
+    artists: number;
+    /** Album titles unified within the same album, disc suffixes moved to the disc number. */
+    albums: number;
+    /** Genres merged with their other spellings. */
+    genres: number;
+    /** Titles freed from a track number or artist prefix. */
+    titles: number;
+    /** Missing album artist, year, genre or track number filled from the rest of the same album. */
+    filled: number;
+}
+interface AudioMetadataHarmony<TTrack extends AudioTrack> {
+    tracks: TTrack[];
+    corrections: AudioMetadataCorrections;
+    /** Tracks with at least one correction. */
+    correctedTracks: number;
+}
+/**
+ * Makes a library consistent without inventing information: spellings of the same artist, album or genre are
+ * unified on their most frequent form, and gaps are only filled from other tracks of the same album.
+ */
+declare function harmonizeAudioMetadata<TTrack extends AudioTrack>(tracks: readonly TTrack[]): AudioMetadataHarmony<TTrack>;
+/** Removes track-number prefixes (`01.Corneille`, `03 - Corneille`) and file-name underscores from a name. */
+declare function cleanAudioArtistName(value: string | undefined): string | undefined;
+/** Case, accent and punctuation insensitive key: `Jay-Z`, `JAY Z` and `jay z` share one key. Works for any media name. */
+declare function mediaMetadataKey(value: string): string;
+
+/**
+ * Transport used by the online catalogs: resolves a JSON document or throws.
+ * Applications plug their HTTP client here (cache, retries, telemetry); the default uses `fetch`.
+ */
+interface OnlineJsonHttp {
+    getJson(url: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+declare function createFetchOnlineJsonHttp(fetchFn?: typeof fetch): OnlineJsonHttp;
+
+/** AcoustID open fingerprint database (MIT server, CC BY-SA data). Free application keys for non-commercial use. */
+declare const ACOUSTID_ORIGIN = "https://api.acoustid.org";
+interface AcoustIdLookupQuery {
+    /** Application key registered at acoustid.org. */
+    clientKey: string;
+    /** Compressed Chromaprint fingerprint (`AQAB…`). */
+    fingerprint: string;
+    durationSec: number;
+}
+interface AcoustIdRequestOptions {
+    http?: OnlineJsonHttp;
+    signal?: AbortSignal;
+    origin?: string;
+}
+interface AcoustIdRecording {
+    id: string;
+    title?: string;
+    artist?: string;
+    durationSec?: number;
+}
+interface AcoustIdResult {
+    id: string;
+    /** Fingerprint similarity, 0 to 1. */
+    score: number;
+    recordings: AcoustIdRecording[];
+}
+declare function buildAcoustIdLookupUrl(query: AcoustIdLookupQuery, origin?: string): string;
+declare function lookupAcoustId(query: AcoustIdLookupQuery, request?: AcoustIdRequestOptions): Promise<AcoustIdResult[]>;
+
+/** MusicBrainz open music encyclopedia (GPL server, CC0 core data). No key; one request per second per client. */
+declare const MUSICBRAINZ_ORIGIN = "https://musicbrainz.org";
+interface MusicBrainzRecordingQuery {
+    title: string;
+    artist?: string;
+    durationSec?: number;
+    /** Tolerance around `durationSec`, in seconds. */
+    durationToleranceSec?: number;
+    limit?: number;
+}
+interface MusicBrainzRequestOptions {
+    /** Defaults to plain `fetch`; desktop shells should send a descriptive User-Agent and rate limit requests. */
+    http?: OnlineJsonHttp;
+    signal?: AbortSignal;
+    origin?: string;
+}
+interface MusicBrainzRelease {
+    id: string;
+    title: string;
+    artist?: string;
+    status?: string;
+    primaryType?: string;
+    year?: number;
+    discNo?: number;
+    trackNo?: number;
+}
+interface MusicBrainzRecording {
+    id: string;
+    /** Search relevance, 0 to 100. */
+    score: number;
+    title: string;
+    artist?: string;
+    durationSec?: number;
+    releases: MusicBrainzRelease[];
+}
+declare function buildMusicBrainzRecordingSearchUrl(query: MusicBrainzRecordingQuery, origin?: string): string;
+declare function searchMusicBrainzRecordings(query: MusicBrainzRecordingQuery, request?: MusicBrainzRequestOptions): Promise<MusicBrainzRecording[]>;
+/** Recording details by MusicBrainz id, with its releases, release groups and track positions. */
+declare function lookupMusicBrainzRecording(id: string, request?: MusicBrainzRequestOptions): Promise<MusicBrainzRecording | null>;
+declare function parseMusicBrainzRecording(entry: unknown): MusicBrainzRecording | null;
+
+/** Bump when the matching rules change: tracks left unmatched by an older version are checked again once. */
+declare const AUDIO_IDENTIFICATION_VERSION = 1;
+/** Unmatched tracks are retried after 30 days, failed checks (offline, service down) after an hour. */
+declare const AUDIO_IDENTIFICATION_RETRY_MS: {
+    readonly unmatched: number;
+    readonly error: 3600000;
+};
+type AudioIdentifiableField = 'title' | 'artist' | 'albumArtist' | 'album' | 'year' | 'trackNo';
+interface AudioIdentificationInput {
+    title: string;
+    artist?: string;
+    albumArtist?: string;
+    album?: string;
+    year?: number;
+    trackNo?: number;
+    durationSec?: number;
+    /** Fields guessed from file and folder names instead of read from tags. */
+    inferredFields?: readonly AudioIdentifiableField[];
+}
+/**
+ * - `trusted`: tags were complete, nothing to look up.
+ * - `matched`: an online source confirmed the track; its fields fill what the tags lacked.
+ * - `unmatched`: no reliable answer; retried much later.
+ * - `error`: the check could not run; retried soon.
+ */
+type AudioIdentificationStatus = 'trusted' | 'matched' | 'unmatched' | 'error';
+/** `fingerprint`: Chromaprint + AcoustID recognise the sound itself; `text`: MusicBrainz search on title, artist and duration. */
+type AudioIdentificationMethod = 'fingerprint' | 'text';
+interface AudioIdentification {
+    version: number;
+    status: AudioIdentificationStatus;
+    checkedAt: number;
+    /** File size and modification time at check time: a changed file is checked again. */
+    fileKey: string;
+    source?: 'musicbrainz';
+    /** Strongest method used for this check; a track left unmatched by text search is retried once fingerprints are available. */
+    method?: AudioIdentificationMethod;
+    recordingId?: string;
+    releaseId?: string;
+    confidence?: number;
+    fields?: Partial<Pick<AudioIdentificationInput, AudioIdentifiableField>>;
+}
+interface AudioIdentificationMatch {
+    status: 'matched' | 'unmatched';
+    method?: AudioIdentificationMethod;
+    recordingId?: string;
+    releaseId?: string;
+    confidence: number;
+    fields: Partial<Pick<AudioIdentificationInput, AudioIdentifiableField>>;
+}
+/** Fields worth checking online: guessed from names or missing. Empty when tags are complete. */
+declare function audioIdentificationDoubts(input: AudioIdentificationInput): AudioIdentifiableField[];
+/**
+ * Up-to-date tracks (trusted or matched) are never checked again while their file is unchanged. Unmatched tracks are
+ * retried when a stronger method or newer rules become available, or after a long delay; failed checks soon.
+ */
+declare function needsAudioIdentification(previous: AudioIdentification | undefined, fileKey: string, now: number, methods?: readonly AudioIdentificationMethod[]): boolean;
+/**
+ * Picks the MusicBrainz recording behind a fingerprint. The sound decides; names only break ties between the
+ * recordings AcoustID links to the same fingerprint.
+ */
+declare function pickAcoustIdRecording(input: AudioIdentificationInput, results: readonly AcoustIdResult[]): {
+    recordingId: string;
+    confidence: number;
+} | null;
+/** Metadata of a recording recognised by its fingerprint; album rules are the same as for text matches. */
+declare function matchFingerprintedRecording(input: AudioIdentificationInput, recording: MusicBrainzRecording | null, confidence: number): AudioIdentificationMatch;
+/**
+ * Accepts a recording only when title, artist and duration agree with the file. Without an artist a name search is
+ * never trusted ("Track 07" exists many times over): only a fingerprint can identify such files. Album data is taken from a release
+ * with the same album title, or from the artist's own album when the file has no album at all, so folders stay
+ * grouped the way the user organised them.
+ */
+declare function matchMusicBrainzRecording(input: AudioIdentificationInput, recordings: readonly MusicBrainzRecording[]): AudioIdentificationMatch;
+/** Identification fills guessed or missing fields only: values read from tags are never overwritten. */
+declare function applyAudioIdentification<TItem extends AudioIdentificationInput>(item: TItem, identification: AudioIdentification | undefined): TItem;
+
+/** A library item as the routine reads it: the identification state and what tells a changed file apart. */
+interface IdentifiableItem extends AudioIdentificationInput {
+    id: string;
+    identification?: AudioIdentification;
+    size: number;
+    /** Modification time in milliseconds; with the size it says whether the file changed. */
+    mtimeMs: number;
+}
+/** What the routine needs from a library, on the desktop as on a phone. */
+interface IdentificationLibrary<TItem extends IdentifiableItem = IdentifiableItem> {
+    identificationCandidates(): readonly TItem[];
+    recordIdentification(id: string, identification: AudioIdentification): void;
+    setIdentificationProgress(progress: {
+        identifying: boolean;
+        identified: number;
+        identifyTotal: number;
+    }): void;
+    notifyChanged(): void;
+    /** Writes the index; the routine calls it once a run is over. */
+    flush(): Promise<void> | void;
+}
+interface IdentificationRoutineOptions<TItem extends IdentifiableItem = IdentifiableItem> {
+    library: IdentificationLibrary<TItem>;
+    identify(item: TItem): Promise<AudioIdentificationMatch>;
+    /** Methods available now; unmatched tracks are tried again when a stronger one appears (fingerprints). */
+    methods?: readonly AudioIdentificationMethod[];
+    source?: AudioIdentification['source'];
+    now?: () => number;
+    retryIntervalMs?: number;
+    /** Offline or service down: a run stops after this many failures in a row. */
+    maxConsecutiveErrors?: number;
+    onError?: (error: unknown) => void;
+}
+interface IdentificationRoutine {
+    /** Runs once now; a call during a run schedules another pass, so new files are never missed. */
+    run(): Promise<void>;
+    /** Runs now and then every `retryIntervalMs`. */
+    start(): void;
+    dispose(): void;
+}
+/** `size:mtime`, which changes when the file behind an item changes. */
+declare function fileKeyFor(item: {
+    size: number;
+    mtimeMs: number;
+}): string;
+declare function createIdentificationRoutine<TItem extends IdentifiableItem>(options: IdentificationRoutineOptions<TItem>): IdentificationRoutine;
+
+/**
+ * Media library model shared by the desktop and mobile shells: file filtering, title cleanup and audio/video
+ * classification from tags, file names and folders. Paths are relative to the library folder and use "/".
+ */
+/** Bump when classification changes: indexed files are read again once. */
+declare const MEDIA_LIBRARY_MODEL_VERSION = 3;
+type MediaLibraryKind = 'audio' | 'video';
+type AudioInferredField = 'title' | 'artist' | 'albumArtist' | 'album' | 'trackNo';
+/** The subset of music-metadata results the model reads. */
+interface MediaTags {
+    title?: string;
+    artist?: string;
+    artists?: string[];
+    albumartist?: string;
+    album?: string;
+    genre?: string | string[];
+    track?: {
+        no?: number | null;
+    };
+    disk?: {
+        no?: number | null;
+    };
+    year?: number;
+    stik?: number;
+    tvShow?: string;
+    tvSeason?: number;
+    tvEpisode?: number;
+}
+interface MediaFormat {
+    duration?: number;
+}
+interface MediaTagsInput {
+    /** Path of the file inside the library folder, e.g. `Artist/Album/01 - Song.mp3`. */
+    relativePath: string;
+    common?: MediaTags;
+    format?: MediaFormat;
+}
+interface AudioLibraryFields {
+    title: string;
+    artist?: string;
+    albumArtist?: string;
+    album?: string;
+    genre?: string;
+    trackNo?: number;
+    discNo?: number;
+    year?: number;
+    durationSec?: number;
+    /** Fields guessed from file and folder names: identification may correct them, never tagged values. */
+    inferredFields?: AudioInferredField[];
+}
+interface VideoLibraryFields {
+    category: 'movie' | 'episode' | 'other';
+    title: string;
+    series?: string;
+    season?: number;
+    episode?: number;
+    year?: number;
+    durationSec?: number;
+}
+declare function mediaFileExtension(fileName: string): string;
+declare function isMediaFileName(fileName: string, kind: MediaLibraryKind): boolean;
+declare function isImageFileName(fileName: string): boolean;
+declare function isIgnoredDirectoryName(name: string): boolean;
+declare function mediaContentType(fileName: string): string;
+/** Rank of a folder image as album or poster art (0 is best), -1 when it is not one. */
+declare function folderArtworkRank(fileName: string): number;
+declare function cleanMediaTitle(fileStemValue: string): string;
+declare function parseEpisodeFileName(stem: string): {
+    series?: string;
+    season?: number;
+    episode?: number;
+    episodeTitle?: string;
+} | null;
+declare function audioFieldsFromTags({ relativePath, common, format }: MediaTagsInput): AudioLibraryFields;
+declare function videoFieldsFromTags({ relativePath, common, format }: MediaTagsInput): VideoLibraryFields;
+
+/**
+ * Media servers the apps can browse and play from: a home server (Jellyfin), a UPnP/DLNA server, a Subsonic music
+ * server or a plain WebDAV share. Connectors translate each protocol into the same containers and items, so the
+ * library views and the queue treat every source alike.
+ */
+type MediaSourceKind = 'jellyfin' | 'dlna' | 'subsonic' | 'webdav';
+/** What the listener fills in to connect a server. */
+interface MediaSourceInput {
+    kind: MediaSourceKind;
+    /** Address of the server, with or without scheme; connectors normalise it. */
+    address: string;
+    name?: string;
+    username?: string;
+    password?: string;
+}
+/**
+ * A connected server. `secret` is the credential kept to reach it again (an access token when the server issues one,
+ * the password otherwise); applications store it with their own preferences and never send it anywhere else.
+ */
+interface MediaSourceAccount {
+    id: string;
+    kind: MediaSourceKind;
+    name: string;
+    baseUrl: string;
+    username?: string;
+    secret?: string;
+    /** Account identifier on the server, when it has one. */
+    userId?: string;
+}
+/** A browsable node: a library, a folder, an album, a series. */
+interface MediaSourceContainer {
+    id: string;
+    title: string;
+    subtitle?: string;
+    artworkUrl?: string;
+    /** What it holds, when the server says so. */
+    kind?: 'audio' | 'video' | 'mixed';
+    childCount?: number;
+}
+/** A playable file, in the shape the libraries already use. */
+interface MediaSourceItem {
+    id: string;
+    kind: 'audio' | 'video';
+    title: string;
+    url: string;
+    artworkUrl?: string;
+    durationSec?: number;
+    artist?: string;
+    albumArtist?: string;
+    album?: string;
+    genre?: string;
+    year?: number;
+    trackNo?: number;
+    discNo?: number;
+    series?: string;
+    season?: number;
+    episode?: number;
+    container?: string;
+}
+interface MediaSourcePage {
+    containers: MediaSourceContainer[];
+    items: MediaSourceItem[];
+    /** Total number of items in the container, when the server reports it. */
+    total?: number;
+}
+interface MediaSourceRequest {
+    url: string;
+    method?: 'GET' | 'POST' | 'PROPFIND';
+    headers?: Record<string, string>;
+    json?: unknown;
+    body?: string;
+    signal?: AbortSignal;
+    /** For a request that waits on purpose (another device asking its user); transports keep their own otherwise. */
+    timeoutMs?: number;
+}
+interface MediaSourceResponse {
+    status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/** Transport used by connectors; applications plug their HTTP client here. */
+interface MediaSourceHttp {
+    send(request: MediaSourceRequest): Promise<MediaSourceResponse>;
+}
+interface MediaSourceBrowseOptions {
+    containerId?: string;
+    /** Filters what the container returns, for apps that only play one kind. */
+    kind?: 'audio' | 'video';
+    search?: string;
+    startIndex?: number;
+    limit?: number;
+    signal?: AbortSignal;
+}
+interface MediaSourceConnector {
+    kind: MediaSourceKind;
+    /** Checks the address and credentials, and returns the account to keep. */
+    connect(input: MediaSourceInput, http: MediaSourceHttp): Promise<MediaSourceAccount>;
+    /** Libraries and folders at the root, then their contents. */
+    browse(account: MediaSourceAccount, options: MediaSourceBrowseOptions, http: MediaSourceHttp): Promise<MediaSourcePage>;
+    /**
+     * Lyrics the server holds for a track, as LRC text or plain words, or null when it has none. Servers that keep
+     * no lyrics leave this out.
+     */
+    lyrics?(account: MediaSourceAccount, item: MediaSourceItem, http: MediaSourceHttp): Promise<string | null>;
+}
+/** `https://host:port/path` without a trailing slash; plain http is kept for servers on a local network. */
+declare function normalizeMediaSourceAddress(address: string): string;
+/** Stable id of an item or container inside an account, so queues and playlists survive a restart. */
+declare function mediaSourceItemId(accountId: string, remoteId: string): string;
+declare function parseMediaSourceItemId(id: string): {
+    accountId: string;
+    remoteId: string;
+} | null;
+/** Ticks used by Jellyfin and Emby (100 ns units) to seconds. */
+declare function ticksToSeconds(ticks: unknown): number | undefined;
+
+type RepeatMode = 'off' | 'one' | 'all';
+interface QueueItem<TItem = unknown> {
+    id: string;
+    item: TItem;
+}
+interface QueueSnapshot<TItem = unknown> {
+    items: QueueItem<TItem>[];
+    currentIndex: number;
+    shuffle: boolean;
+    repeat: RepeatMode;
+    history: number[];
+}
+
+/**
+ * Cutting a piece of a track to use as a ringtone.
+ *
+ * The piece is taken from where the listener is: they were listening to the part they want, and
+ * asking them to find it again in a waveform is asking them to do the work twice. So the start
+ * is the playhead, the length is a choice between a few, and what comes out is a real file.
+ *
+ * Both edges are faded. A ringtone cut straight out of the middle of a track starts with a click
+ * and ends with one, which is the difference between something made and something taken.
+ */
+/** How long a ringtone may be. Android accepts more; a phone that rings for half a minute is enough. */
+declare const RINGTONE_MAX_SEC = 30;
+/** Long enough not to click, short enough not to be heard as a fade. */
+declare const RINGTONE_FADE_SEC = 0.05;
+interface RingtoneSegment {
+    startSec: number;
+    lengthSec: number;
+}
+/**
+ * Where the piece starts and how long it runs, kept inside the track.
+ *
+ * A playhead near the end would give a piece that runs off it, so the start slides back to make
+ * room; a track shorter than the length asked for simply gives all of itself.
+ */
+declare function ringtoneSegment(options: {
+    positionSec: number;
+    trackDurationSec: number;
+    lengthSec: number;
+}): RingtoneSegment;
+/**
+ * Fades both edges in place, so the piece does not begin or end on a click.
+ *
+ * A piece too short to hold two fades gets shorter ones rather than none: the click is what is
+ * being removed, and half a fade removes it just as well.
+ */
+declare function fadeEdges(channels: Float32Array[], sampleRate: number, fadeSec?: number): void;
+/**
+ * Writes audio as a WAV file: 16-bit PCM, the one encoding a page can produce on its own.
+ *
+ * It is not small, and it is not meant to be kept — it is what is handed to the system, which
+ * stores a ringtone however it likes. What matters is that no library has to be shipped to make
+ * one, and that every platform reads it.
+ */
+declare function encodeWav(channels: Float32Array[], sampleRate: number): ArrayBuffer;
+/** A file name from a track's title: what a viewer will look for in their files. */
+declare function ringtoneFileName(title: string, extension?: string): string;
+
+/**
+ * Shaking the device, read from its accelerometer.
+ *
+ * A shake is not one movement but several: the hand throws the device one way and pulls it back,
+ * and does it again. So what is counted is not force but **reversals** — the number of times the
+ * movement changed its mind inside a short window. That is what tells a shake apart from setting
+ * the phone down hard, from a pocket, from a car going over a kerb.
+ *
+ * Direction is deliberately not read. A sideways shake does carry a first impulse one way or the
+ * other, but which way that is depends on how the device is being held, and a control that works
+ * most of the time is worse than one that works the same way every time. So a shake means one
+ * thing, and two shakes in a row mean the other — the same bargain a double click makes.
+ *
+ * One thing follows from that and is worth saying rather than hiding: a shake that simply goes
+ * on long enough crosses the rest and is heard as a second one. Someone still shaking after a
+ * second and a half meant more than "the next one", so reading it as the other gesture is the
+ * least surprising of the available wrong answers.
+ */
+/** One reading of the accelerometer, in m/s², gravity included or not — only the changes are read. */
+interface ShakeSample {
+    x: number;
+    y: number;
+    z: number;
+    /** When it was taken, in milliseconds. */
+    at: number;
+}
+type ShakeGesture = 'single' | 'double';
+interface ShakeOptions {
+    /** How hard a movement has to be before it counts as one, in m/s² of change. */
+    force?: number;
+    /** How many changes of direction make a shake. */
+    reversals?: number;
+    /** How long those changes have to happen inside, in milliseconds. */
+    window?: number;
+    /** How long to ignore the accelerometer after a shake, so one shake is not read as three. */
+    rest?: number;
+    /**
+     * How long a second shake has to arrive within to mean "the other way", counted from the first.
+     * It has to leave room for the rest above, or a second shake would be swallowed before it could
+     * be heard — so the two are set together, not one at a time.
+     */
+    pairWindow?: number;
+}
+/**
+ * Reads samples and says when a shake happened.
+ *
+ * A single shake is reported only once it is clear no second one is coming, so that a double
+ * shake never arrives as a single one first and is then contradicted.
+ */
+declare function createShakeDetector(options?: ShakeOptions): {
+    read: (sample: ShakeSample) => ShakeGesture | null;
+    settle: (now: number) => ShakeGesture | null;
+    pendingFor: (now: number) => number;
+    reset: () => void;
+};
+
+/**
+ * Media kept behind a lock.
+ *
+ * What is locked is not merely refused: it is **absent**. It is in no shelf, no search, no
+ * history, no queue, until the vault is opened. Anything less tells whoever is holding the
+ * device that there is something to look for, which is the thing a lock is meant to avoid.
+ *
+ * The code is never kept. What is kept is a salt and the result of stretching the code through
+ * PBKDF2 with it, so the stored record cannot be read backwards, and the same code typed twice
+ * on two devices does not produce the same record.
+ */
+/** What is written down about the code. The code itself never is. */
+interface VaultPasscode {
+    /** Random, per vault, so two vaults with the same code do not look alike. */
+    salt: string;
+    /** The stretched code, base64. */
+    hash: string;
+    /** How many rounds produced it, so a record made today still opens after the cost is raised. */
+    rounds: number;
+}
+/** The parts of Web Crypto this needs, named so a test can stand in for them. */
+interface VaultCrypto {
+    getRandomValues(array: Uint8Array): Uint8Array;
+    subtle: Pick<SubtleCrypto, 'importKey' | 'deriveBits'>;
+}
+declare const VAULT_ROUNDS = 310000;
+/**
+ * Stretches a code into something that can be written down.
+ *
+ * The rounds are the cost of one guess. They are stored with the record rather than assumed, so
+ * raising them later does not lock anyone out of a vault they already have.
+ */
+declare function hashPasscode(code: string, crypto: VaultCrypto, options?: {
+    salt?: string;
+    rounds?: number;
+}): Promise<VaultPasscode>;
+/**
+ * Whether a code opens a record. Compared in constant time, so the time an answer takes says
+ * nothing about how much of the code was right.
+ */
+declare function verifyPasscode(code: string, record: VaultPasscode | null, crypto: VaultCrypto): Promise<boolean>;
+/** A code short enough to guess is not a code. Four is the floor every phone uses. */
+declare function isUsablePasscode(code: string): boolean;
+/**
+ * The ids that must not be shown.
+ *
+ * Nothing is hidden while the vault is open, and nothing is hidden when there is no code — a
+ * vault nobody can open is a way of losing media, not of protecting it.
+ */
+declare function hiddenIds(locked: Iterable<string>, state: {
+    open: boolean;
+    hasPasscode: boolean;
+}): Set<string>;
+/** Keeps only what may be seen, in the order it was given. */
+declare function withoutHidden<T>(items: readonly T[], idOf: (item: T) => string, hidden: ReadonlySet<string>): T[];
+
+type DevicePlaybackKind = RemotePlaybackKind;
+type DevicePlaybackStatus = 'idle' | 'connecting' | 'playing' | 'failed';
+interface PlaybackDevice {
+    id: string;
+    name: string;
+    kind: DevicePlaybackKind;
+    address: string;
+    model?: string;
+    connected?: boolean;
+}
+interface DevicePlaybackState {
+    status: DevicePlaybackStatus;
+    activeDeviceId: string | null;
+    activeDeviceName: string | null;
+    targetUrl?: string;
+    message?: string;
+    error?: string;
+}
+type DevicePlaybackEvent = {
+    type: 'connect';
+    device: PlaybackDevice;
+    targetUrl: string;
+    message?: string;
+} | {
+    type: 'playing';
+    deviceId: string;
+    message?: string;
+} | {
+    type: 'fail';
+    deviceId: string;
+    error: string;
+    message?: string;
+} | {
+    type: 'stop';
+    deviceId?: string;
+    message?: string;
+};
+declare function createIdleDevicePlaybackState(message?: string): DevicePlaybackState;
+declare function reduceDevicePlaybackState(state: DevicePlaybackState, event: DevicePlaybackEvent): DevicePlaybackState;
+
+/**
+ * Local copies of online media (Internet Archive tracks): instant starts, seamless queue transitions and playback
+ * through network drops. Downloads run one at a time in the background and the cache stays under a byte budget by
+ * evicting the least recently used copies, never the ones the queue still needs.
+ */
+interface MediaCacheEntry {
+    key: string;
+    url: string;
+    size: number;
+    contentType: string;
+    storedAt: number;
+    lastUsedAt: number;
+}
+/** Persistence of cached media; browsers implement it with IndexedDB. */
+interface MediaCacheStore {
+    entries(): Promise<MediaCacheEntry[]>;
+    read(key: string): Promise<Blob | null>;
+    write(entry: MediaCacheEntry, data: Blob): Promise<void>;
+    touch(key: string, lastUsedAt: number): Promise<void>;
+    remove(keys: readonly string[]): Promise<void>;
+}
+interface MediaCacheRequest {
+    key: string;
+    url: string;
+    /** Tried in order when `url` cannot be downloaded (network, HTTP or CORS failure). */
+    alternateUrls?: readonly string[];
+}
+interface MediaCacheUsage {
+    bytes: number;
+    count: number;
+    budgetBytes: number;
+}
+interface MediaCacheOptions {
+    store: MediaCacheStore;
+    budgetBytes: number;
+    /** Larger media are streamed only. Defaults to a quarter of the budget. */
+    maxEntryBytes?: number;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** Background downloads wait while this returns false (data saver, slow connection). */
+    canDownload?: () => boolean;
+}
+interface MediaCache {
+    /** Resolves once the stored index is loaded; `has` answers false before. */
+    readonly ready: Promise<void>;
+    has(key: string): boolean;
+    /** The local copy, marked as recently used; null when absent or unreadable. */
+    open(key: string): Promise<Blob | null>;
+    /**
+     * Media the player needs next, most urgent first. Missing ones are downloaded in that order; a download no longer
+     * requested is cancelled. Requested keys are protected from eviction until the next call.
+     */
+    keep(requests: readonly MediaCacheRequest[]): void;
+    usage(): MediaCacheUsage;
+    clear(): Promise<void>;
+    /** Called after downloads, evictions and clears. */
+    onChange(listener: () => void): () => void;
+}
+/** Keys to evict, least recently used first, so that `incomingBytes` fits in the budget; null when it cannot fit. */
+declare function planMediaCacheEviction(entries: readonly MediaCacheEntry[], budgetBytes: number, incomingBytes: number, protectedKeys?: ReadonlySet<string>): string[] | null;
+declare function createMediaCache(options: MediaCacheOptions): MediaCache;
+
+/**
+ * Jellyfin, the free software home media server (GPL). One account gives music and videos with their covers,
+ * artists, series and seasons; files are played as they are stored, so seeking works through byte ranges.
+ */
+declare const JELLYFIN_CLIENT: {
+    readonly name: "NGXSP";
+    readonly version: "1.0.0";
+};
+declare function createJellyfinConnector(deviceId?: string): MediaSourceConnector;
+/** Signs in and keeps the access token the server issues; the password is not stored. */
+declare function connectJellyfin(input: MediaSourceInput, http: MediaSourceHttp, deviceId?: string): Promise<MediaSourceAccount>;
+/** Libraries at the root, then albums, series and seasons, then the files they hold. */
+declare function browseJellyfin(account: MediaSourceAccount, options: MediaSourceBrowseOptions, http: MediaSourceHttp): Promise<MediaSourcePage>;
+/**
+ * Lyrics stored next to the track on the server (Jellyfin 10.9 and later). Timed lines come back as ticks of a
+ * hundred nanoseconds and are written as LRC, so the player reads them with its own parser.
+ */
+declare function readJellyfinLyrics(account: MediaSourceAccount, item: MediaSourceItem, http: MediaSourceHttp): Promise<string | null>;
+/** Plays the file as stored on the server; the browser asks for the byte ranges it needs. */
+declare function jellyfinStreamUrl(account: MediaSourceAccount, itemId: string, kind: 'audio' | 'video'): string;
+declare function jellyfinImageUrl(account: MediaSourceAccount, itemId: string, tag?: string, maxHeight?: number): string;
+declare function jellyfinClientHeader(deviceId: string, token?: string): string;
+declare function parseJellyfinItem(account: MediaSourceAccount, entry: unknown, kind: 'audio' | 'video'): MediaSourceItem | null;
+
+/**
+ * UPnP AV / DLNA media servers (ReadyMedia/MiniDLNA, Gerbera, Kodi, Jellyfin's DLNA plugin, most NAS): the device
+ * description names the server and its ContentDirectory service, which is browsed with SOAP `Browse` requests that
+ * answer DIDL-Lite documents. Files are served over plain HTTP without credentials.
+ *
+ * Servers answer neither web pages (no CORS) nor discovery from a browser: applications find them with SSDP through
+ * their native shell, using `DLNA_MEDIA_SERVER_SEARCH_TARGET`, or take the address of the description document.
+ */
+declare const DLNA_MEDIA_SERVER_SEARCH_TARGET = "urn:schemas-upnp-org:device:MediaServer:1";
+interface DidlResource {
+    url: string;
+    mimeType?: string;
+    durationSec?: number;
+    size?: number;
+}
+interface DidlObject {
+    id: string;
+    parentId?: string;
+    container: boolean;
+    title: string;
+    upnpClass: string;
+    childCount?: number;
+    artists: Array<{
+        name: string;
+        role?: string;
+    }>;
+    creator?: string;
+    album?: string;
+    genre?: string;
+    date?: string;
+    trackNo?: number;
+    artworkUrl?: string;
+    seriesTitle?: string;
+    season?: number;
+    episode?: number;
+    resources: DidlResource[];
+}
+declare function createDlnaConnector(): MediaSourceConnector;
+/** Reads the device description (typed, or found on the network) and checks the device serves media. */
+declare function connectDlna(input: MediaSourceInput, http: MediaSourceHttp): Promise<MediaSourceAccount>;
+/**
+ * Children of a container, the root when none is given. Folders come first, then the files the app plays; a search
+ * asks the server for matching titles when it supports it.
+ */
+declare function browseDlna(account: MediaSourceAccount, options: MediaSourceBrowseOptions, http: MediaSourceHttp): Promise<MediaSourcePage>;
+/** Containers and items of a DIDL-Lite document, with relative links resolved against `baseUrl`. */
+declare function parseDidlLite(xml: string, baseUrl: string): DidlObject[];
+
+/** A service of a UPnP device (ContentDirectory, AVTransport, RenderingControl…) and where to send its actions. */
+interface UpnpService {
+    serviceType: string;
+    controlUrl: string;
+}
+interface UpnpDeviceDescription {
+    udn?: string;
+    friendlyName: string;
+    deviceType?: string;
+    manufacturer?: string;
+    modelName?: string;
+    iconUrl?: string;
+    /** Every service the device and its embedded devices offer. */
+    services: UpnpService[];
+    contentDirectory?: UpnpService;
+}
+/** A UPnP action the device refused; `code` is its UPnP error code when it gave one. */
+declare class UpnpActionError extends Error {
+    readonly action: string;
+    readonly code: string | undefined;
+    readonly status: number;
+    constructor(action: string, code: string | undefined, status: number);
+}
+declare function parseUpnpDeviceDescription(xml: string, descriptionUrl: string): UpnpDeviceDescription;
+/** The first service of this kind (`AVTransport`, `RenderingControl`…), whatever its version. */
+declare function findUpnpService(services: readonly UpnpService[], name: string): UpnpService | undefined;
+/** Sends a SOAP action and returns the answer; a refusal throws `UpnpActionError`. */
+declare function upnpAction(http: MediaSourceHttp, service: UpnpService, action: string, soapArguments: Record<string, string>, signal?: AbortSignal): Promise<string>;
+
+/**
+ * UPnP AV / DLNA renderers (smart TVs, network speakers, Kodi, gmrender): media is handed over with AVTransport
+ * `SetAVTransportURI` and driven with `Play`, `Pause`, `Seek` and `Stop`; RenderingControl sets the volume. Renderers
+ * fetch the media themselves, over plain HTTP.
+ */
+declare const DLNA_MEDIA_RENDERER_SEARCH_TARGET = "urn:schemas-upnp-org:device:MediaRenderer:1";
+interface DlnaRendererInfo {
+    name: string;
+    udn?: string;
+    modelName?: string;
+    avTransport: UpnpService;
+    renderingControl?: UpnpService;
+}
+/** Reads a renderer's description; devices without AVTransport cannot play what they are sent. */
+declare function readDlnaRenderer(descriptionUrl: string, http: MediaSourceHttp): Promise<DlnaRendererInfo>;
+declare function createDlnaRendererSession(descriptionUrl: string, http: MediaSourceHttp): Promise<RemotePlaybackSession>;
+
+/**
+ * Chromecast and Cast-enabled speakers and TVs, spoken without Google's SDK: CASTV2 messages (protobuf `CastMessage`
+ * frames carrying JSON) over a TLS connection to port 8009. Media plays in the Default Media Receiver, the player
+ * every Cast device ships. The apps' native shells open the TLS connection and find devices with mDNS
+ * (`CAST_MDNS_SERVICE`); everything else happens here.
+ */
+declare const CAST_MDNS_SERVICE = "_googlecast._tcp";
+declare const CAST_PORT = 8009;
+declare const CAST_DEFAULT_MEDIA_RECEIVER = "CC1AD845";
+/** The type to send a media to a Cast receiver with, or the format it cannot read. */
+declare function castContentType(contentType: string): {
+    contentType: string;
+} | {
+    unsupported: string;
+};
+/** A Cast device found on the network. */
+interface CastDeviceInfo {
+    id: string;
+    name: string;
+    model?: string;
+    address: string;
+    port: number;
+    /** Speakers and speaker groups have no screen. */
+    video: boolean;
+}
+/** Cast devices in the answers to an mDNS question for `CAST_MDNS_SERVICE`, one per device id. */
+declare function castDevicesFromMdns(answers: ReadonlyArray<{
+    from?: string;
+    bytes: Uint8Array;
+}>): CastDeviceInfo[];
+/** A TLS connection to a Cast device, opened by the native shell. */
+interface CastSocket {
+    send(frame: Uint8Array): void | Promise<void>;
+    onData(listener: (chunk: Uint8Array) => void): () => void;
+    onClose(listener: (reason?: string) => void): () => void;
+    close(): void;
+}
+interface CastMessage {
+    sourceId: string;
+    destinationId: string;
+    namespace: string;
+    payload: string;
+}
+interface CastSessionOptions {
+    appId?: string;
+    senderId?: string;
+    requestTimeoutMs?: number;
+    /** How long a LOAD may take: a receiver that has just started loads its player first (over 10 s on a TV). */
+    loadTimeoutMs?: number;
+    /** Interval of the keep-alive PING; 0 disables it (tests). */
+    heartbeatMs?: number;
+}
+/** One length-prefixed protobuf `CastMessage` with a UTF-8 payload. */
+declare function encodeCastMessage(message: CastMessage): Uint8Array;
+/** Splits received bytes into messages; returns the messages and the bytes of an incomplete frame. */
+declare function decodeCastFrames(buffer: Uint8Array): {
+    messages: CastMessage[];
+    rest: Uint8Array;
+};
+/** Connects to the device; media is sent with `load`, which starts the Default Media Receiver when needed. */
+declare function createCastSession(socket: CastSocket, options?: CastSessionOptions): RemotePlaybackSession;
+
+/**
+ * Just enough DNS for mDNS service discovery (RFC 6762/6763): a PTR question for a service type, and the PTR, SRV,
+ * TXT and A records devices answer with. Apps send the question from an ordinary UDP port to 224.0.0.251:5353
+ * ("legacy unicast" query), so devices answer that port directly and no process has to share port 5353. An app that
+ * advertises a service of its own reads the questions (`parseMdnsQuestions`) and answers them (`encodeMdnsResponse`).
+ */
+declare const MDNS_ADDRESS = "224.0.0.251";
+declare const MDNS_PORT = 5353;
+type MdnsRecord = {
+    type: 'PTR';
+    name: string;
+    target: string;
+} | {
+    type: 'SRV';
+    name: string;
+    target: string;
+    port: number;
+} | {
+    type: 'TXT';
+    name: string;
+    entries: Record<string, string>;
+} | {
+    type: 'A';
+    name: string;
+    address: string;
+};
+/** A service instance put together from the records of one or more answers. */
+interface MdnsService {
+    /** Full instance name, e.g. `Kitchen._googlecast._tcp.local`. */
+    instance: string;
+    host?: string;
+    address?: string;
+    port?: number;
+    txt: Record<string, string>;
+}
+/** A PTR question for a service type (`_googlecast._tcp.local`). */
+declare function encodeMdnsQuery(serviceType: string, id?: number): Uint8Array;
+/** The questions of a DNS query (not of a response); malformed messages give none. */
+declare function parseMdnsQuestions(bytes: Uint8Array): Array<{
+    name: string;
+    type: number;
+}>;
+/**
+ * A response carrying `records`: what a service advertises (PTR to its instance, SRV, TXT, A). `ttl` 0 says goodbye.
+ * `id` and `question` echo a legacy unicast query, which expects them back.
+ */
+declare function encodeMdnsResponse(records: readonly MdnsRecord[], options?: {
+    id?: number;
+    ttl?: number;
+    question?: {
+        name: string;
+        type: number;
+    };
+}): Uint8Array;
+/** Answer and additional records of a DNS message; malformed messages give no records. */
+declare function parseMdnsMessage(bytes: Uint8Array): MdnsRecord[];
+/** Instances of a service type found in a set of answers, with their port, TXT entries and IPv4 address. */
+declare function mdnsServices(serviceType: string, answers: ReadonlyArray<{
+    from?: string;
+    bytes: Uint8Array;
+}>): MdnsService[];
+
+/**
+ * Playback transfer between NGXSP apps of a local network: an app hands what it plays (the queue, the item, the
+ * position) to another app of the same kind, which carries on from there.
+ *
+ * - Apps advertise themselves over mDNS as `_ngxsp._tcp` services; TXT entries say which app they are.
+ * - The sender POSTs a `PlaybackTransfer` to `/ngxsp/transfer` on the receiver. Its media addresses are ones the
+ *   receiver can fetch: web addresses as they are, the sender's own media shared on the network.
+ * - The first transfer from an app asks on the receiving device (refuse or allow). Allowed, the sender gets a token
+ *   it presents from then on, and later transfers go through without asking ("accept once").
+ */
+declare const NGXSP_SERVICE_TYPE = "_ngxsp._tcp.local";
+declare const PLAYBACK_TRANSFER_PATH = "/ngxsp/transfer";
+declare const PLAYBACK_TRANSFER_VERSION = 1;
+/** How long the receiving device waits for its user to answer. */
+declare const PLAYBACK_TRANSFER_PROMPT_MS = 60000;
+type NgxspAppKind = 'audio' | 'video';
+/** An NGXSP app as the others know it. */
+interface NgxspAppIdentity {
+    /** Random, kept by the app for good. */
+    id: string;
+    /** The device's name, as its user knows it. */
+    name: string;
+    app: NgxspAppKind;
+}
+/** Another NGXSP app of the network. */
+interface NgxspPeer extends NgxspAppIdentity {
+    address: string;
+    port: number;
+}
+interface PlaybackTransferItem {
+    url: string;
+    title: string;
+    artist?: string;
+    album?: string;
+    artworkUrl?: string;
+    durationSec?: number;
+    /** Radios and live streams. */
+    live?: boolean;
+}
+interface PlaybackTransfer {
+    version: number;
+    from: NgxspAppIdentity;
+    items: PlaybackTransferItem[];
+    /** The item playing, in `items`. */
+    index: number;
+    positionSec: number;
+    playing: boolean;
+}
+interface TrustedSender {
+    id: string;
+    name: string;
+    /** SHA-256 of the token the sender presents, in hex. */
+    tokenHash: string;
+    since: number;
+}
+type PlaybackTransferOutcome = {
+    accepted: true;
+    token?: string;
+} | {
+    accepted: false;
+    reason: 'refused' | 'busy' | 'timeout' | 'disabled' | 'other-app' | 'invalid' | 'unreachable';
+};
+/** The TXT entries an app advertises. */
+declare function ngxspTxt(identity: NgxspAppIdentity): Record<string, string>;
+/** The records an app answers `_ngxsp._tcp` questions with, for each of its addresses. */
+declare function ngxspServiceRecords(identity: NgxspAppIdentity, port: number, addresses: readonly string[]): MdnsRecord[];
+/** NGXSP apps of kind `app` found in mDNS answers, this one aside. */
+declare function ngxspPeersFromMdns(answers: ReadonlyArray<{
+    from?: string;
+    bytes: Uint8Array;
+}>, self: Pick<NgxspAppIdentity, 'id' | 'app'>): NgxspPeer[];
+/** A transfer as received, checked and trimmed; null when it is not one. */
+declare function readPlaybackTransfer(value: unknown): PlaybackTransfer | null;
+interface PlaybackTransferReceiverOptions {
+    app: NgxspAppKind;
+    /** Off, the app refuses every transfer without asking. */
+    enabled: () => boolean;
+    trusted: () => readonly TrustedSender[];
+    saveTrusted: (senders: TrustedSender[]) => void;
+    /** Asks the user whether `from` may send its playback here: true to allow. */
+    ask: (from: NgxspAppIdentity) => Promise<boolean>;
+    /** Plays what was transferred. */
+    apply: (transfer: PlaybackTransfer) => void;
+    sha256Hex: (value: string) => Promise<string>;
+    randomToken: () => string;
+    promptMs?: number;
+}
+/** A transfer request as the app's HTTP endpoint hands it over, and what it answers. */
+interface PlaybackTransferRequest {
+    method: string;
+    body: string;
+    /** The `Authorization` header: `NGXSP <token>` from a sender allowed before. */
+    authorization?: string;
+}
+interface PlaybackTransferResponse {
+    status: number;
+    body: Record<string, unknown>;
+}
+/** Decides on the transfers an app receives, asking its user the first time an app sends one. */
+declare function createPlaybackTransferReceiver(options: PlaybackTransferReceiverOptions): {
+    handle: (request: PlaybackTransferRequest) => Promise<PlaybackTransferResponse>;
+};
+/** Sends a transfer to a peer, with the token it gave the last time if there is one. */
+declare function sendPlaybackTransfer(http: MediaSourceHttp, peer: Pick<NgxspPeer, 'address' | 'port'>, transfer: PlaybackTransfer, token?: string): Promise<PlaybackTransferOutcome>;
+
+/**
+ * Subsonic API, spoken by Navidrome, Airsonic-Advanced, Gonic and others (all open source): a music server with
+ * albums, artists and covers. Every request is signed with md5(password + salt), so the account keeps that signature
+ * and its salt instead of the password.
+ */
+declare const SUBSONIC_API_VERSION = "1.16.1";
+declare const SUBSONIC_CLIENT = "NGXSP";
+declare function createSubsonicConnector(salt?: () => string): MediaSourceConnector;
+/** Checks the credentials with `ping` and keeps the request signature, never the password. */
+declare function connectSubsonic(input: MediaSourceInput, http: MediaSourceHttp, salt?: () => string): Promise<MediaSourceAccount>;
+/** Albums at the root (with their covers), then the tracks of an album; searches look up tracks directly. */
+declare function browseSubsonic(account: MediaSourceAccount, options: MediaSourceBrowseOptions, http: MediaSourceHttp): Promise<MediaSourcePage>;
+declare function subsonicStreamUrl(account: MediaSourceAccount, songId: string): string;
+declare function subsonicCoverUrl(account: MediaSourceAccount, coverArtId: string, size?: number): string;
+declare function parseSubsonicSong(account: MediaSourceAccount, entry: unknown): MediaSourceItem | null;
+
+interface WebDavEntry {
+    /** Decoded path of the entry on the server, starting with `/`. */
+    path: string;
+    name: string;
+    collection: boolean;
+    size?: number;
+    contentType?: string;
+    lastModified?: number;
+}
+declare function createWebDavConnector(): MediaSourceConnector;
+/** Checks that the address is a WebDAV folder the credentials can read. */
+declare function connectWebDav(input: MediaSourceInput, http: MediaSourceHttp): Promise<MediaSourceAccount>;
+/** Sub-folders of a folder, then the media files it holds for the kind the app plays. */
+declare function browseWebDav(account: MediaSourceAccount, options: MediaSourceBrowseOptions, http: MediaSourceHttp): Promise<MediaSourcePage>;
+/** Parses a WebDAV multistatus document; prefixes and namespaces vary between servers, so tags are matched by name. */
+declare function parseWebDavMultistatus(xml: string): WebDavEntry[];
+/** Value for the `Authorization` header of an account, or undefined for anonymous shares. */
+declare function webDavAuthorization(account: MediaSourceAccount): string | undefined;
+/** Reads the `.lrc` file sitting next to the track, the way a music folder usually keeps its lyrics. */
+declare function readWebDavLyrics(account: MediaSourceAccount, item: MediaSourceItem, http: MediaSourceHttp): Promise<string | null>;
+
+/**
+ * MD5 of a UTF-8 string, as lowercase hex (RFC 1321). Only for protocols that require it, such as Subsonic request
+ * signing; never as a security primitive of its own. WebCrypto does not offer MD5, hence this implementation.
+ */
+declare function md5Hex(input: string): string;
+
+/** Internet Archive public APIs: advanced search, item metadata and file downloads. No key required. */
+declare const INTERNET_ARCHIVE_ORIGIN = "https://archive.org";
+type InternetArchiveMediaType = 'movies' | 'audio';
+interface InternetArchiveRequestOptions {
+    /** Defaults to plain `fetch`. */
+    http?: OnlineJsonHttp;
+    signal?: AbortSignal;
+    origin?: string;
+}
+interface InternetArchiveSearchOptions {
+    mediaType: InternetArchiveMediaType;
+    /** Extra Lucene clauses joined with AND, e.g. `collection:(prelinger)`. */
+    filters?: readonly string[];
+    /** Free text matched against title, creator and subject. */
+    text?: string;
+    rows?: number;
+    page?: number;
+    /** Defaults to the most downloaded items first. */
+    sort?: string;
+    origin?: string;
+}
+interface InternetArchiveSearchItem {
+    identifier: string;
+    title: string;
+    creator?: string;
+    year?: number;
+    licenseUrl?: string;
+    thumbnailUrl: string;
+    detailsUrl: string;
+}
+interface InternetArchiveSearchResult {
+    total: number;
+    page: number;
+    items: InternetArchiveSearchItem[];
+}
+interface InternetArchiveFile {
+    name: string;
+    format?: string;
+    source?: string;
+    /** For derivatives, the name of the file they were generated from. */
+    original?: string;
+    title?: string;
+    creator?: string;
+    album?: string;
+    track?: string;
+    length?: string;
+    size?: string;
+}
+interface InternetArchiveItem {
+    identifier: string;
+    title: string;
+    creator?: string;
+    year?: number;
+    description?: string;
+    licenseUrl?: string;
+    /** Lending, stream-only or dark items cannot be played from their download URLs. */
+    restricted: boolean;
+    thumbnailUrl: string;
+    detailsUrl: string;
+    /**
+     * Storage servers holding the item (`https://<server>/<dir>`). `/download` redirects to a nearby mirror that may omit
+     * CORS headers; these servers send them, so apps download files from here and keep `/download` for streaming.
+     */
+    storageUrls: string[];
+    files: InternetArchiveFile[];
+}
+interface InternetArchiveVideoSource {
+    fileName: string;
+    format: string;
+    url: string;
+    /** Same file on the item's storage servers, readable with `fetch` from other origins. */
+    storageUrls: string[];
+    durationSec?: number;
+}
+interface InternetArchiveAudioTrack {
+    /** `<identifier>/<file name>`, unique across the archive. */
+    id: string;
+    identifier: string;
+    fileName: string;
+    title: string;
+    artist?: string;
+    album: string;
+    trackNo?: number;
+    durationSec?: number;
+    url: string;
+    /** Same file on the item's storage servers, readable with `fetch` from other origins. */
+    storageUrls: string[];
+    artworkUrl: string;
+}
+/** Clauses that keep results playable without an account. */
+declare const INTERNET_ARCHIVE_PLAYABLE_FILTERS: readonly string[];
+declare function buildInternetArchiveSearchUrl(options: InternetArchiveSearchOptions): string;
+declare function searchInternetArchive(options: InternetArchiveSearchOptions, request?: InternetArchiveRequestOptions): Promise<InternetArchiveSearchResult>;
+declare function fetchInternetArchiveItem(identifier: string, request?: InternetArchiveRequestOptions): Promise<InternetArchiveItem>;
+declare function parseInternetArchiveItem(identifier: string, body: unknown, origin?: string): InternetArchiveItem;
+/** Picks the most widely playable video derivative of an item. */
+declare function selectInternetArchiveVideo(item: InternetArchiveItem, origin?: string): InternetArchiveVideoSource | null;
+/** Tracks of an audio item, using a single format so derivatives are not listed twice. */
+declare function internetArchiveAudioTracks(item: InternetArchiveItem, origin?: string): InternetArchiveAudioTrack[];
+declare function internetArchiveDownloadUrl(identifier: string, fileName: string, origin?: string): string;
+declare function internetArchiveThumbnailUrl(identifier: string, origin?: string): string;
+declare function internetArchiveDetailsUrl(identifier: string, origin?: string): string;
+/** Accepts `240.9` seconds as well as `02:31` or `1:31:44`. */
+declare function parseInternetArchiveLength(length: string | undefined): number | undefined;
+
+/** Radio Browser community directory of internet radio stations. No key required. */
+declare const RADIO_BROWSER_ORIGIN = "https://de1.api.radio-browser.info";
+interface RadioBrowserSearchOptions {
+    /** ISO 3166-1 alpha-2 country code, e.g. `CM`. */
+    countryCode?: string;
+    name?: string;
+    tag?: string;
+    limit?: number;
+    offset?: number;
+    /** Defaults to true: stations failing the directory checks are skipped. */
+    hideBroken?: boolean;
+    /** Defaults to the most listened stations first. */
+    order?: 'clickcount' | 'votes' | 'name' | 'bitrate' | 'lastcheckok';
+    origin?: string;
+}
+interface RadioBrowserRequestOptions {
+    /** Defaults to plain `fetch`. */
+    http?: OnlineJsonHttp;
+    signal?: AbortSignal;
+    origin?: string;
+}
+interface RadioStation {
+    id: string;
+    name: string;
+    streamUrl: string;
+    homepageUrl?: string;
+    faviconUrl?: string;
+    country?: string;
+    countryCode?: string;
+    language?: string;
+    tags: string[];
+    codec?: string;
+    bitrateKbps?: number;
+    /** HLS playlists need an adaptive engine; other streams play in a media element. */
+    hls: boolean;
+    /** Plain http streams are blocked as mixed content on https pages. */
+    secure: boolean;
+}
+declare function buildRadioBrowserSearchUrl(options?: RadioBrowserSearchOptions): string;
+declare function searchRadioStations(options?: RadioBrowserSearchOptions, request?: RadioBrowserRequestOptions): Promise<RadioStation[]>;
+declare function parseRadioStation(entry: unknown): RadioStation | null;
+
+/**
+ * Lyrics of a track, timed or plain. They come from the file itself (tags), from an `.lrc` file beside it, or from
+ * LRCLIB, an open lyrics database (no key, no account). Timed lines let the player follow the words while it plays.
+ */
+declare const LRCLIB_ORIGIN = "https://lrclib.net";
+type LyricsSource = 'tags' | 'file' | 'lrclib';
+interface LyricsLine {
+    /** Start of the line in the track. */
+    timeSec: number;
+    text: string;
+}
+interface Lyrics {
+    source: LyricsSource;
+    /** Timed lines, when the source has them. */
+    lines?: LyricsLine[];
+    /** The whole text, always present when anything was found. */
+    plain: string;
+    /** What the source says it is, to show which version was picked. */
+    title?: string;
+    artist?: string;
+    /** LRCLIB record, to fetch it again or report a wrong match. */
+    id?: number;
+}
+interface LyricsQuery {
+    title: string;
+    artist?: string;
+    album?: string;
+    durationSec?: number;
+}
+interface LyricsRequestOptions {
+    /** Defaults to plain `fetch`; apps plug their HTTP client (cache, retries). */
+    http?: OnlineJsonHttp;
+    signal?: AbortSignal;
+    origin?: string;
+}
+/** `[mm:ss.xx]` lines, `[offset:±ms]` and the usual `[ti:]`/`[ar:]` tags; text without timestamps stays plain. */
+declare function parseLrc(text: string, source?: LyricsSource): Lyrics | null;
+/** Lyrics tags of a file (ID3 USLT/SYLT, Vorbis LYRICS), as music-metadata reports them. */
+interface TaggedLyrics {
+    text?: string;
+    syncText?: Array<{
+        text?: string;
+        timestamp?: number;
+    }>;
+}
+/** Lyrics carried by the file itself; timed words win over a plain block. */
+declare function lyricsFromTags(tags: readonly TaggedLyrics[] | TaggedLyrics | undefined | null): Lyrics | null;
+/** Index of the line being sung at this position, or -1 before the first one. */
+declare function lyricsLineIndexAt(lines: readonly LyricsLine[] | undefined, positionSec: number): number;
+interface LrclibRecord {
+    id?: number;
+    trackName?: string;
+    artistName?: string;
+    duration?: number;
+    instrumental?: boolean;
+    plainLyrics?: string | null;
+    syncedLyrics?: string | null;
+}
+declare function buildLrclibGetUrl(query: LyricsQuery, origin?: string): string;
+declare function buildLrclibSearchUrl(query: LyricsQuery, origin?: string): string;
+/**
+ * Lyrics for a track from LRCLIB: the exact record when the track, artist, album and duration match, otherwise the
+ * closest of the search results. Returns null when the database has nothing, and for instrumental tracks.
+ */
+declare function fetchLrclibLyrics(query: LyricsQuery, options?: LyricsRequestOptions): Promise<Lyrics | null>;
+/** Closest record: a duration within 5 seconds first, then the title and artist that look most alike. */
+declare function bestLrclibMatch(records: readonly LrclibRecord[], query: LyricsQuery): LrclibRecord | null;
+
+export { ACOUSTID_ORIGIN, AUDIO_IDENTIFICATION_RETRY_MS, AUDIO_IDENTIFICATION_VERSION, type AcoustIdLookupQuery, type AcoustIdRecording, type AcoustIdRequestOptions, type AcoustIdResult, type AdsConfig, type AdsMode, type AspectRatioMode, type AudioAlbum, type AudioArtist, type AudioGenre, type AudioIdentifiableField, type AudioIdentification, type AudioIdentificationInput, type AudioIdentificationMatch, type AudioIdentificationMethod, type AudioIdentificationStatus, type AudioInferredField, type AudioLibraryFields, type AudioLibrarySearchResult, type AudioLibrarySnapshot, type AudioMetadataCorrections, type AudioMetadataHarmony, type AudioPlaylist, type AudioPlaylistRef, type AudioTrack, CAST_DEFAULT_MEDIA_RECEIVER, CAST_MDNS_SERVICE, CAST_PORT, type CacheStore, type CapabilityReport, type CastDeviceInfo, type CastMessage, type CastSessionOptions, type CastSocket, ConsoleLogPort, DEFAULT_ADS_CONFIG, DEFAULT_METADATA_CONFIG, DEFAULT_PROGRESS_CONFIG, DEFAULT_RESILIENCE_CONFIG, DEFAULT_SUBTITLES_CONFIG, DEFAULT_UI_CONFIG, DLNA_MEDIA_RENDERER_SEARCH_TARGET, DLNA_MEDIA_SERVER_SEARCH_TARGET, DefaultCacheStore, type DevicePlaybackEvent, type DevicePlaybackKind, type DevicePlaybackState, type DevicePlaybackStatus, type DiagnosticsEngineInfo, type DiagnosticsSnapshot, type DidlObject, type DidlResource, type DlnaRendererInfo, type DrmConfig, type EngineEvent, type EngineFactory, type EngineProfileHints, type EngineProfileId, type EpisodeItem, type HttpPort, INTERNET_ARCHIVE_ORIGIN, INTERNET_ARCHIVE_PLAYABLE_FILTERS, type IdentifiableItem, type IdentificationLibrary, type IdentificationRoutine, type IdentificationRoutineOptions, type InternetArchiveAudioTrack, type InternetArchiveFile, type InternetArchiveItem, type InternetArchiveMediaType, type InternetArchiveRequestOptions, type InternetArchiveSearchItem, type InternetArchiveSearchOptions, type InternetArchiveSearchResult, type InternetArchiveVideoSource, JELLYFIN_CLIENT, LRCLIB_ORIGIN, type LoadOptions, LocalMetadataProvider, LocalSubtitleProvider, type LogPort, type Lyrics, type LyricsLine, type LyricsQuery, type LyricsRequestOptions, type LyricsSource, MDNS_ADDRESS, MDNS_PORT, MEDIA_LIBRARY_MODEL_VERSION, MUSICBRAINZ_ORIGIN, type MdnsRecord, type MdnsService, type MediaArtwork, type MediaCache, type MediaCacheEntry, type MediaCacheOptions, type MediaCacheRequest, type MediaCacheStore, type MediaCacheUsage, type MediaFormat, type MediaItem, type MediaKind, type MediaLibraryKind, type MediaProgress, type MediaSourceAccount, type MediaSourceBrowseOptions, type MediaSourceConnector, type MediaSourceContainer, type MediaSourceHttp, type MediaSourceInput, type MediaSourceItem, type MediaSourceKind, type MediaSourcePage, type MediaSourceRequest, type MediaSourceResponse, type MediaTags, type MediaTagsInput, type MediaTrack, MemoryStoragePort, type MetadataConfig, type MetadataHint, type MetadataMatch, type MetadataProvider, type MusicBrainzRecording, type MusicBrainzRecordingQuery, type MusicBrainzRelease, type MusicBrainzRequestOptions, NGXSP_SERVICE_TYPE, NativeEngine, type NextEpisodeHint, type NgxspAppIdentity, type NgxspAppKind, type NgxspPeer, NoopTelemetryPort, type OnlineJsonHttp, PLAYBACK_TRANSFER_PATH, PLAYBACK_TRANSFER_PROMPT_MS, PLAYBACK_TRANSFER_VERSION, type PlaybackCapabilities, type PlaybackDevice, type PlaybackEngine, type PlaybackTransfer, type PlaybackTransferItem, type PlaybackTransferOutcome, type PlaybackTransferReceiverOptions, type PlaybackTransferRequest, type PlaybackTransferResponse, type PlayerCommand, type PlayerConfig, type PlayerContext, type PlayerDiagnostics, type PlayerError, type PlayerErrorCode, type PlayerEvent, type PlayerEventBus, PlayerFacade, type PlayerPlugin, type PlayerPorts, type PlayerSnapshot, type PlayerSource, type PlayerState, type PlayerTime, type ProgressConfig, type ProgressMode, ProgressPlugin, type QueueItem, type QueueSnapshot, RADIO_BROWSER_ORIGIN, RINGTONE_FADE_SEC, RINGTONE_MAX_SEC, type RadioBrowserRequestOptions, type RadioBrowserSearchOptions, type RadioStation, type RemoteConfigConfig, type RemoteConfigPayload, RemotePlaybackEngine, type RemotePlaybackEngineOptions, RemotePlaybackError, type RemotePlaybackErrorCode, type RemotePlaybackKind, type RemotePlaybackMedia, type RemotePlaybackSession, type RemotePlaybackStatus, type RemotePlayerState, type RepeatMode, type ResilienceConfig, ResiliencePlugin, type RingtoneSegment, SUBSONIC_API_VERSION, SUBSONIC_CLIENT, type SeriesConfig, type ShakeGesture, type ShakeOptions, type ShakeSample, SimpleEventBus, type SkipSegment, type SourceType, type SsaiManifestRewriteConfig, type StoragePort, type SubtitleCandidate, type SubtitleHint, type SubtitleProvider, type SubtitleQuery, type SubtitlesConfig, type TaggedLyrics, type TelemetryEvent, type TelemetryLevel, type TelemetryPort, type TelemetrySample, type TrustedSender, type UiConfig, type Unsubscribe, UpnpActionError, type UpnpDeviceDescription, type UpnpService, VAULT_ROUNDS, type VaultCrypto, type VaultPasscode, type VideoLibraryFields, type VideoMetadata, type WebDavEntry, applyAudioIdentification, applyEngineProfileToSource, applyRemoteConfig, audioFieldsFromTags, audioIdentificationDoubts, audioTrackMatchesSearch, bestLrclibMatch, browseDlna, browseJellyfin, browseSubsonic, browseWebDav, buildAcoustIdLookupUrl, buildInternetArchiveSearchUrl, buildLrclibGetUrl, buildLrclibSearchUrl, buildMusicBrainzRecordingSearchUrl, buildRadioBrowserSearchUrl, castContentType, castDevicesFromMdns, cleanAudioArtistName, cleanMediaTitle, connectDlna, connectJellyfin, connectSubsonic, connectWebDav, createAudioLibrarySnapshot, createCapabilityReport, createCastSession, createDefaultCapabilities, createDefaultConfig, createDefaultPorts, createDlnaConnector, createDlnaRendererSession, createFetchOnlineJsonHttp, createIdentificationRoutine, createIdleDevicePlaybackState, createJellyfinConnector, createMediaCache, createMediaDecodingReport, createNativeEngineFactory, createPlaybackTransferReceiver, createRemotePlaybackEngineFactory, createShakeDetector, createSsaiManifestRewritePlugin, createSubsonicConnector, createWebDavConnector, decodeCastFrames, decodeSubtitleBytes, describeSubtitleFile, detectPlaybackCapabilities, encodeCastMessage, encodeMdnsQuery, encodeMdnsResponse, encodeWav, fadeEdges, fetchInternetArchiveItem, fetchLrclibLyrics, fileKeyFor, findUpnpService, folderArtworkRank, formatRemoteClock, getEngineProfileHints, harmonizeAudioMetadata, hashPasscode, hiddenIds, internetArchiveAudioTracks, internetArchiveDetailsUrl, internetArchiveDownloadUrl, internetArchiveThumbnailUrl, isCategorizedEventType, isIgnoredDirectoryName, isImageFileName, isMediaFileName, isUsablePasscode, jellyfinClientHeader, jellyfinImageUrl, jellyfinStreamUrl, lookupAcoustId, lookupMusicBrainzRecording, lyricsFromTags, lyricsLineIndexAt, matchFingerprintedRecording, matchMusicBrainzRecording, md5Hex, mdnsServices, mediaContentType, mediaFileExtension, mediaMetadataKey, mediaSourceItemId, needsAudioIdentification, ngxspPeersFromMdns, ngxspServiceRecords, ngxspTxt, normalizeAudioSearchText, normalizeMediaSourceAddress, parseDidlLite, parseEpisodeFileName, parseInternetArchiveItem, parseInternetArchiveLength, parseJellyfinItem, parseLrc, parseMdnsMessage, parseMdnsQuestions, parseMediaSourceItemId, parseMusicBrainzRecording, parseRadioStation, parseRemoteClock, parseSubsonicSong, parseUpnpDeviceDescription, parseWebDavMultistatus, pickAcoustIdRecording, planMediaCacheEviction, readDlnaRenderer, readJellyfinLyrics, readPlaybackTransfer, readWebDavLyrics, reduceDevicePlaybackState, remotePlaybackErrorCode, remotePlaybackFailure, ringtoneFileName, ringtoneSegment, searchAudioLibrarySnapshot, searchInternetArchive, searchMusicBrainzRecordings, searchRadioStations, selectEngine, selectInternetArchiveVideo, sendPlaybackTransfer, subsonicCoverUrl, subsonicStreamUrl, subtitleTextToVtt, ticksToSeconds, upnpAction, verifyPasscode, videoFieldsFromTags, webDavAuthorization, withoutHidden };