@kromatv/sdk 0.1.40-canary.0

package/types/client/src/api/media/client.d.ts

@@ -0,0 +1,2160 @@
+import type { Query, RequestContext } from '../../core/client';
+import type { ItemId, LibraryId, ShowId } from './ids';
+import { MediaItem, Show, SplashEntry } from './schemas';
+import { type HlsAudioFilter, StoryboardManifest } from './tracks';
+/** What this device can decode, for the HLS master builder.
+ *
+ * `copyCodecs` names the audio and `videoCodecs` the video, letting the server
+ * override a stream copy it would play silent or black; omitted means no
+ * declaration, an empty array means none. `copyCodecs` is read only for a copy
+ * request, `videoCodecs` for every mode. `maxFrame` is the largest picture this
+ * decoder accepts: a bigger source is fitted inside the nearest rung under it.
+ * Both axes, because a scope frame breaks the width limit while clearing the
+ * height one. */
+export interface HlsMasterDeclaration {
+    filter?: HlsAudioFilter;
+    copyCodecs?: string[];
+    videoCodecs?: string[];
+    maxFrame?: {
+        width: number;
+        height: number;
+    };
+}
+/** The `?copy=&video=&maxw=&maxh=` a stream request carries: what this device can
+ * decode, and the largest picture it accepts. An EMPTY codec list is itself a
+ * declaration ("decode none"), which is why it is not the same as no list. */
+export declare function streamQuery({ copyCodecs, videoCodecs, maxFrame }: HlsMasterDeclaration): Query;
+/** The catalogue: what the library holds, and the URLs that play it. */
+export default function mediaApi(ctx: RequestContext): {
+    artwork: {
+        resolve: (url?: string | null, width?: number) => string | null;
+        posterUrl: (id: ItemId) => string;
+        showPosterUrl: (id: ShowId) => string;
+        posterFor: (x: {
+            id: ItemId;
+            metadata?: import("./credits").Metadata | null;
+        }, width?: number) => string;
+        showPosterFor: (x: Pick<Show, 'id' | 'metadata'>, width?: number) => string;
+        backdropFor: (x: {
+            metadata?: import("./credits").Metadata | null;
+        }, width?: number) => string | null;
+        themeFor: (x: {
+            metadata?: import("./credits").Metadata | null;
+        }) => string | null;
+        posterBlob: (item: Pick<MediaItem, 'id' | 'metadata'>) => Promise<Blob>;
+    };
+    rematch: {
+        candidates: (kind: import("./schemas").RematchKind, id: import("./ids").SubjectId, query?: string) => Promise<{
+            query: string;
+            year?: number | null | undefined;
+            currentTmdbId?: number | null | undefined;
+            pinned: boolean;
+            results: {
+                tmdbId: number;
+                title: string;
+                originalTitle?: string | null | undefined;
+                year?: number | null | undefined;
+                posterUrl?: string | null | undefined;
+                overview?: string | null | undefined;
+                rating?: number | null | undefined;
+                score: number;
+                current: boolean;
+            }[];
+        }>;
+        set: (kind: import("./schemas").RematchKind, id: import("./ids").SubjectId, tmdbId: number | null) => Promise<void>;
+    };
+    /** Server liveness + counts. Takes a `signal` so a client-side heartbeat can
+     * bound the probe with a short timeout. */
+    health: (opts?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        status: string;
+        name?: string | undefined;
+        instanceId?: string | undefined;
+        version: string;
+        ffprobe: boolean;
+        libraries: number;
+        items: number;
+        shows: number;
+    }>;
+    /** Anonymous sign-in splash: a small random sample of backdrop art with
+     * captions, art URLs resolved against the server base like every poster. */
+    splash: () => Promise<SplashEntry[]>;
+    libraries: () => Promise<{
+        id: string & import("zod").$brand<"LibraryId">;
+        name: string;
+        kind: "mixed" | "movies" | "shows";
+        path: string;
+        itemCount: number;
+    }[]>;
+    /** All playable items (movies + episodes). */
+    items: (library?: LibraryId) => Promise<{
+        container: string;
+        durationMs: number | null;
+        relPath: string | null;
+        video: {
+            codec: string;
+            width: number | null;
+            height: number | null;
+            hdr: boolean;
+            bitDepth: number | null;
+        } | null;
+        audio: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        } | null;
+        audioTracks: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        }[];
+        subtitles: {
+            language: string | null;
+            codec: string;
+        }[];
+        title: string;
+        year: number | null;
+        library: string & import("zod").$brand<"LibraryId">;
+        addedAt: string;
+        metadata?: {
+            provider: string;
+            tmdbId: number;
+            imdbId?: string | null | undefined;
+            title: string | null;
+            tagline?: string | null | undefined;
+            overview: string | null;
+            releaseDate?: string | null | undefined;
+            genres: string[];
+            tmdbGenreIds?: number[] | null | undefined;
+            rating?: number | null | undefined;
+            certification?: string | null | undefined;
+            posterUrl?: string | null | undefined;
+            backdropUrl?: string | null | undefined;
+            logoUrl?: string | null | undefined;
+            themeUrl?: string | null | undefined;
+            cast?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                character?: string | null | undefined;
+            }[] | null | undefined;
+            crew?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                job: string;
+            }[] | null | undefined;
+            tmdbUrl: string;
+        } | null | undefined;
+        id: string & import("zod").$brand<"ItemId">;
+        kind: "episode" | "movie" | "video";
+        showId: (string & import("zod").$brand<"ShowId">) | null;
+        showTitle: string | null;
+        season: number | null;
+        episode: number | null;
+        episodeEnd: number | null;
+        episodeTitle: string | null;
+        files: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            id: string & import("zod").$brand<"MediaFileId">;
+            size: number | null;
+            edition?: string | null | undefined;
+            probed: boolean;
+        }[];
+        defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+        markers?: {
+            kind: "credits" | "intro";
+            startMs: number;
+            endMs: number;
+        }[] | null | undefined;
+        audioAnalysis?: {
+            lufsI: number;
+            lra: number;
+            truePeak: number;
+            dialogLufs?: number | null | undefined;
+            verdict: "highDynamics" | "ok" | "quietDialog";
+        } | null | undefined;
+    }[]>;
+    /** Movies only (excludes episodes). */
+    movies: (library?: LibraryId) => Promise<{
+        container: string;
+        durationMs: number | null;
+        relPath: string | null;
+        video: {
+            codec: string;
+            width: number | null;
+            height: number | null;
+            hdr: boolean;
+            bitDepth: number | null;
+        } | null;
+        audio: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        } | null;
+        audioTracks: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        }[];
+        subtitles: {
+            language: string | null;
+            codec: string;
+        }[];
+        title: string;
+        year: number | null;
+        library: string & import("zod").$brand<"LibraryId">;
+        addedAt: string;
+        metadata?: {
+            provider: string;
+            tmdbId: number;
+            imdbId?: string | null | undefined;
+            title: string | null;
+            tagline?: string | null | undefined;
+            overview: string | null;
+            releaseDate?: string | null | undefined;
+            genres: string[];
+            tmdbGenreIds?: number[] | null | undefined;
+            rating?: number | null | undefined;
+            certification?: string | null | undefined;
+            posterUrl?: string | null | undefined;
+            backdropUrl?: string | null | undefined;
+            logoUrl?: string | null | undefined;
+            themeUrl?: string | null | undefined;
+            cast?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                character?: string | null | undefined;
+            }[] | null | undefined;
+            crew?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                job: string;
+            }[] | null | undefined;
+            tmdbUrl: string;
+        } | null | undefined;
+        id: string & import("zod").$brand<"ItemId">;
+        kind: "episode" | "movie" | "video";
+        showId: (string & import("zod").$brand<"ShowId">) | null;
+        showTitle: string | null;
+        season: number | null;
+        episode: number | null;
+        episodeEnd: number | null;
+        episodeTitle: string | null;
+        files: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            id: string & import("zod").$brand<"MediaFileId">;
+            size: number | null;
+            edition?: string | null | undefined;
+            probed: boolean;
+        }[];
+        defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+        markers?: {
+            kind: "credits" | "intro";
+            startMs: number;
+            endMs: number;
+        }[] | null | undefined;
+        audioAnalysis?: {
+            lufsI: number;
+            lra: number;
+            truePeak: number;
+            dialogLufs?: number | null | undefined;
+            verdict: "highDynamics" | "ok" | "quietDialog";
+        } | null | undefined;
+    }[]>;
+    /** TV shows (aggregates). */
+    shows: (library?: LibraryId) => Promise<{
+        title: string;
+        year: number | null;
+        library: string & import("zod").$brand<"LibraryId">;
+        video: {
+            codec: string;
+            width: number | null;
+            height: number | null;
+            hdr: boolean;
+            bitDepth: number | null;
+        } | null;
+        addedAt: string;
+        metadata?: {
+            provider: string;
+            tmdbId: number;
+            imdbId?: string | null | undefined;
+            title: string | null;
+            tagline?: string | null | undefined;
+            overview: string | null;
+            releaseDate?: string | null | undefined;
+            genres: string[];
+            tmdbGenreIds?: number[] | null | undefined;
+            rating?: number | null | undefined;
+            certification?: string | null | undefined;
+            posterUrl?: string | null | undefined;
+            backdropUrl?: string | null | undefined;
+            logoUrl?: string | null | undefined;
+            themeUrl?: string | null | undefined;
+            cast?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                character?: string | null | undefined;
+            }[] | null | undefined;
+            crew?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                job: string;
+            }[] | null | undefined;
+            tmdbUrl: string;
+        } | null | undefined;
+        id: string & import("zod").$brand<"ShowId">;
+        seasonCount: number;
+        episodeCount: number;
+        progress?: number | null | undefined;
+    }[]>;
+    /** One show with its seasons + episodes. */
+    show: (id: ShowId) => Promise<{
+        show: {
+            title: string;
+            year: number | null;
+            library: string & import("zod").$brand<"LibraryId">;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            addedAt: string;
+            metadata?: {
+                provider: string;
+                tmdbId: number;
+                imdbId?: string | null | undefined;
+                title: string | null;
+                tagline?: string | null | undefined;
+                overview: string | null;
+                releaseDate?: string | null | undefined;
+                genres: string[];
+                tmdbGenreIds?: number[] | null | undefined;
+                rating?: number | null | undefined;
+                certification?: string | null | undefined;
+                posterUrl?: string | null | undefined;
+                backdropUrl?: string | null | undefined;
+                logoUrl?: string | null | undefined;
+                themeUrl?: string | null | undefined;
+                cast?: {
+                    name: string;
+                    tmdbId?: number | null | undefined;
+                    profileUrl?: string | null | undefined;
+                    character?: string | null | undefined;
+                }[] | null | undefined;
+                crew?: {
+                    name: string;
+                    tmdbId?: number | null | undefined;
+                    profileUrl?: string | null | undefined;
+                    job: string;
+                }[] | null | undefined;
+                tmdbUrl: string;
+            } | null | undefined;
+            id: string & import("zod").$brand<"ShowId">;
+            seasonCount: number;
+            episodeCount: number;
+            progress?: number | null | undefined;
+        };
+        seasons: {
+            number: number;
+            episodes: {
+                container: string;
+                durationMs: number | null;
+                relPath: string | null;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                audio: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                } | null;
+                audioTracks: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                }[];
+                subtitles: {
+                    language: string | null;
+                    codec: string;
+                }[];
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ItemId">;
+                kind: "episode" | "movie" | "video";
+                showId: (string & import("zod").$brand<"ShowId">) | null;
+                showTitle: string | null;
+                season: number | null;
+                episode: number | null;
+                episodeEnd: number | null;
+                episodeTitle: string | null;
+                files: {
+                    container: string;
+                    durationMs: number | null;
+                    relPath: string | null;
+                    video: {
+                        codec: string;
+                        width: number | null;
+                        height: number | null;
+                        hdr: boolean;
+                        bitDepth: number | null;
+                    } | null;
+                    audio: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    } | null;
+                    audioTracks: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    }[];
+                    subtitles: {
+                        language: string | null;
+                        codec: string;
+                    }[];
+                    id: string & import("zod").$brand<"MediaFileId">;
+                    size: number | null;
+                    edition?: string | null | undefined;
+                    probed: boolean;
+                }[];
+                defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+                markers?: {
+                    kind: "credits" | "intro";
+                    startMs: number;
+                    endMs: number;
+                }[] | null | undefined;
+                audioAnalysis?: {
+                    lufsI: number;
+                    lra: number;
+                    truePeak: number;
+                    dialogLufs?: number | null | undefined;
+                    verdict: "highDynamics" | "ok" | "quietDialog";
+                } | null | undefined;
+            }[];
+            cast?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                character?: string | null | undefined;
+            }[] | null | undefined;
+        }[];
+    }>;
+    item: (id: ItemId) => Promise<{
+        container: string;
+        durationMs: number | null;
+        relPath: string | null;
+        video: {
+            codec: string;
+            width: number | null;
+            height: number | null;
+            hdr: boolean;
+            bitDepth: number | null;
+        } | null;
+        audio: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        } | null;
+        audioTracks: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        }[];
+        subtitles: {
+            language: string | null;
+            codec: string;
+        }[];
+        title: string;
+        year: number | null;
+        library: string & import("zod").$brand<"LibraryId">;
+        addedAt: string;
+        metadata?: {
+            provider: string;
+            tmdbId: number;
+            imdbId?: string | null | undefined;
+            title: string | null;
+            tagline?: string | null | undefined;
+            overview: string | null;
+            releaseDate?: string | null | undefined;
+            genres: string[];
+            tmdbGenreIds?: number[] | null | undefined;
+            rating?: number | null | undefined;
+            certification?: string | null | undefined;
+            posterUrl?: string | null | undefined;
+            backdropUrl?: string | null | undefined;
+            logoUrl?: string | null | undefined;
+            themeUrl?: string | null | undefined;
+            cast?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                character?: string | null | undefined;
+            }[] | null | undefined;
+            crew?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                job: string;
+            }[] | null | undefined;
+            tmdbUrl: string;
+        } | null | undefined;
+        id: string & import("zod").$brand<"ItemId">;
+        kind: "episode" | "movie" | "video";
+        showId: (string & import("zod").$brand<"ShowId">) | null;
+        showTitle: string | null;
+        season: number | null;
+        episode: number | null;
+        episodeEnd: number | null;
+        episodeTitle: string | null;
+        files: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            id: string & import("zod").$brand<"MediaFileId">;
+            size: number | null;
+            edition?: string | null | undefined;
+            probed: boolean;
+        }[];
+        defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+        markers?: {
+            kind: "credits" | "intro";
+            startMs: number;
+            endMs: number;
+        }[] | null | undefined;
+        audioAnalysis?: {
+            lufsI: number;
+            lra: number;
+            truePeak: number;
+            dialogLufs?: number | null | undefined;
+            verdict: "highDynamics" | "ok" | "quietDialog";
+        } | null | undefined;
+    }>;
+    /** "More like this": content-embedding neighbours of a title (public). */
+    similar: (id: ItemId) => Promise<{
+        container: string;
+        durationMs: number | null;
+        relPath: string | null;
+        video: {
+            codec: string;
+            width: number | null;
+            height: number | null;
+            hdr: boolean;
+            bitDepth: number | null;
+        } | null;
+        audio: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        } | null;
+        audioTracks: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        }[];
+        subtitles: {
+            language: string | null;
+            codec: string;
+        }[];
+        title: string;
+        year: number | null;
+        library: string & import("zod").$brand<"LibraryId">;
+        addedAt: string;
+        metadata?: {
+            provider: string;
+            tmdbId: number;
+            imdbId?: string | null | undefined;
+            title: string | null;
+            tagline?: string | null | undefined;
+            overview: string | null;
+            releaseDate?: string | null | undefined;
+            genres: string[];
+            tmdbGenreIds?: number[] | null | undefined;
+            rating?: number | null | undefined;
+            certification?: string | null | undefined;
+            posterUrl?: string | null | undefined;
+            backdropUrl?: string | null | undefined;
+            logoUrl?: string | null | undefined;
+            themeUrl?: string | null | undefined;
+            cast?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                character?: string | null | undefined;
+            }[] | null | undefined;
+            crew?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                job: string;
+            }[] | null | undefined;
+            tmdbUrl: string;
+        } | null | undefined;
+        id: string & import("zod").$brand<"ItemId">;
+        kind: "episode" | "movie" | "video";
+        showId: (string & import("zod").$brand<"ShowId">) | null;
+        showTitle: string | null;
+        season: number | null;
+        episode: number | null;
+        episodeEnd: number | null;
+        episodeTitle: string | null;
+        files: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            id: string & import("zod").$brand<"MediaFileId">;
+            size: number | null;
+            edition?: string | null | undefined;
+            probed: boolean;
+        }[];
+        defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+        markers?: {
+            kind: "credits" | "intro";
+            startMs: number;
+            endMs: number;
+        }[] | null | undefined;
+        audioAnalysis?: {
+            lufsI: number;
+            lra: number;
+            truePeak: number;
+            dialogLufs?: number | null | undefined;
+            verdict: "highDynamics" | "ok" | "quietDialog";
+        } | null | undefined;
+    }[]>;
+    /** Zero-shot themed row: titles matching a free-text phrase (e.g. "christmas
+     * movie", "action"), ranked by content-embedding similarity (public). */
+    themed: (query: string) => Promise<{
+        container: string;
+        durationMs: number | null;
+        relPath: string | null;
+        video: {
+            codec: string;
+            width: number | null;
+            height: number | null;
+            hdr: boolean;
+            bitDepth: number | null;
+        } | null;
+        audio: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        } | null;
+        audioTracks: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        }[];
+        subtitles: {
+            language: string | null;
+            codec: string;
+        }[];
+        title: string;
+        year: number | null;
+        library: string & import("zod").$brand<"LibraryId">;
+        addedAt: string;
+        metadata?: {
+            provider: string;
+            tmdbId: number;
+            imdbId?: string | null | undefined;
+            title: string | null;
+            tagline?: string | null | undefined;
+            overview: string | null;
+            releaseDate?: string | null | undefined;
+            genres: string[];
+            tmdbGenreIds?: number[] | null | undefined;
+            rating?: number | null | undefined;
+            certification?: string | null | undefined;
+            posterUrl?: string | null | undefined;
+            backdropUrl?: string | null | undefined;
+            logoUrl?: string | null | undefined;
+            themeUrl?: string | null | undefined;
+            cast?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                character?: string | null | undefined;
+            }[] | null | undefined;
+            crew?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                job: string;
+            }[] | null | undefined;
+            tmdbUrl: string;
+        } | null | undefined;
+        id: string & import("zod").$brand<"ItemId">;
+        kind: "episode" | "movie" | "video";
+        showId: (string & import("zod").$brand<"ShowId">) | null;
+        showTitle: string | null;
+        season: number | null;
+        episode: number | null;
+        episodeEnd: number | null;
+        episodeTitle: string | null;
+        files: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            id: string & import("zod").$brand<"MediaFileId">;
+            size: number | null;
+            edition?: string | null | undefined;
+            probed: boolean;
+        }[];
+        defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+        markers?: {
+            kind: "credits" | "intro";
+            startMs: number;
+            endMs: number;
+        }[] | null | undefined;
+        audioAnalysis?: {
+            lufsI: number;
+            lra: number;
+            truePeak: number;
+            dialogLufs?: number | null | undefined;
+            verdict: "highDynamics" | "ok" | "quietDialog";
+        } | null | undefined;
+    }[]>;
+    /** The generated home screen (Bearer): an ordered, server-assembled list of
+     * section rails already localized and de-duplicated. Rendered generically. */
+    home: () => Promise<{
+        id: string;
+        title: string;
+        reason?: string | null | undefined;
+        items: ({
+            type: "movie";
+            item: {
+                container: string;
+                durationMs: number | null;
+                relPath: string | null;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                audio: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                } | null;
+                audioTracks: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                }[];
+                subtitles: {
+                    language: string | null;
+                    codec: string;
+                }[];
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ItemId">;
+                kind: "episode" | "movie" | "video";
+                showId: (string & import("zod").$brand<"ShowId">) | null;
+                showTitle: string | null;
+                season: number | null;
+                episode: number | null;
+                episodeEnd: number | null;
+                episodeTitle: string | null;
+                files: {
+                    container: string;
+                    durationMs: number | null;
+                    relPath: string | null;
+                    video: {
+                        codec: string;
+                        width: number | null;
+                        height: number | null;
+                        hdr: boolean;
+                        bitDepth: number | null;
+                    } | null;
+                    audio: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    } | null;
+                    audioTracks: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    }[];
+                    subtitles: {
+                        language: string | null;
+                        codec: string;
+                    }[];
+                    id: string & import("zod").$brand<"MediaFileId">;
+                    size: number | null;
+                    edition?: string | null | undefined;
+                    probed: boolean;
+                }[];
+                defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+                markers?: {
+                    kind: "credits" | "intro";
+                    startMs: number;
+                    endMs: number;
+                }[] | null | undefined;
+                audioAnalysis?: {
+                    lufsI: number;
+                    lra: number;
+                    truePeak: number;
+                    dialogLufs?: number | null | undefined;
+                    verdict: "highDynamics" | "ok" | "quietDialog";
+                } | null | undefined;
+            };
+        } | {
+            type: "show";
+            show: {
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ShowId">;
+                seasonCount: number;
+                episodeCount: number;
+                progress?: number | null | undefined;
+            };
+        })[];
+    }[]>;
+    /** Today's "En vedette" hero for the caller (Bearer): one movie or show
+     * picked server-side with a deterministic daily rotation. `null` only when
+     * the catalogue is empty; clients keep a local fallback for that case. */
+    featured: () => Promise<{
+        type: "movie";
+        item: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            title: string;
+            year: number | null;
+            library: string & import("zod").$brand<"LibraryId">;
+            addedAt: string;
+            metadata?: {
+                provider: string;
+                tmdbId: number;
+                imdbId?: string | null | undefined;
+                title: string | null;
+                tagline?: string | null | undefined;
+                overview: string | null;
+                releaseDate?: string | null | undefined;
+                genres: string[];
+                tmdbGenreIds?: number[] | null | undefined;
+                rating?: number | null | undefined;
+                certification?: string | null | undefined;
+                posterUrl?: string | null | undefined;
+                backdropUrl?: string | null | undefined;
+                logoUrl?: string | null | undefined;
+                themeUrl?: string | null | undefined;
+                cast?: {
+                    name: string;
+                    tmdbId?: number | null | undefined;
+                    profileUrl?: string | null | undefined;
+                    character?: string | null | undefined;
+                }[] | null | undefined;
+                crew?: {
+                    name: string;
+                    tmdbId?: number | null | undefined;
+                    profileUrl?: string | null | undefined;
+                    job: string;
+                }[] | null | undefined;
+                tmdbUrl: string;
+            } | null | undefined;
+            id: string & import("zod").$brand<"ItemId">;
+            kind: "episode" | "movie" | "video";
+            showId: (string & import("zod").$brand<"ShowId">) | null;
+            showTitle: string | null;
+            season: number | null;
+            episode: number | null;
+            episodeEnd: number | null;
+            episodeTitle: string | null;
+            files: {
+                container: string;
+                durationMs: number | null;
+                relPath: string | null;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                audio: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                } | null;
+                audioTracks: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                }[];
+                subtitles: {
+                    language: string | null;
+                    codec: string;
+                }[];
+                id: string & import("zod").$brand<"MediaFileId">;
+                size: number | null;
+                edition?: string | null | undefined;
+                probed: boolean;
+            }[];
+            defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+            markers?: {
+                kind: "credits" | "intro";
+                startMs: number;
+                endMs: number;
+            }[] | null | undefined;
+            audioAnalysis?: {
+                lufsI: number;
+                lra: number;
+                truePeak: number;
+                dialogLufs?: number | null | undefined;
+                verdict: "highDynamics" | "ok" | "quietDialog";
+            } | null | undefined;
+        };
+    } | {
+        type: "show";
+        show: {
+            title: string;
+            year: number | null;
+            library: string & import("zod").$brand<"LibraryId">;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            addedAt: string;
+            metadata?: {
+                provider: string;
+                tmdbId: number;
+                imdbId?: string | null | undefined;
+                title: string | null;
+                tagline?: string | null | undefined;
+                overview: string | null;
+                releaseDate?: string | null | undefined;
+                genres: string[];
+                tmdbGenreIds?: number[] | null | undefined;
+                rating?: number | null | undefined;
+                certification?: string | null | undefined;
+                posterUrl?: string | null | undefined;
+                backdropUrl?: string | null | undefined;
+                logoUrl?: string | null | undefined;
+                themeUrl?: string | null | undefined;
+                cast?: {
+                    name: string;
+                    tmdbId?: number | null | undefined;
+                    profileUrl?: string | null | undefined;
+                    character?: string | null | undefined;
+                }[] | null | undefined;
+                crew?: {
+                    name: string;
+                    tmdbId?: number | null | undefined;
+                    profileUrl?: string | null | undefined;
+                    job: string;
+                }[] | null | undefined;
+                tmdbUrl: string;
+            } | null | undefined;
+            id: string & import("zod").$brand<"ShowId">;
+            seasonCount: number;
+            episodeCount: number;
+            progress?: number | null | undefined;
+        };
+    } | null>;
+    /** AI-curated suggestions for one title's detail page (Bearer). Generated
+     * lazily and cached server-side, so the first call for a title answers `null`
+     * and the caller polls; an arriving section may have empty `items` when the
+     * model found nothing worth showing. */
+    aiSuggest: (id: ItemId) => Promise<{
+        id: string;
+        title: string;
+        reason?: string | null | undefined;
+        items: ({
+            type: "movie";
+            item: {
+                container: string;
+                durationMs: number | null;
+                relPath: string | null;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                audio: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                } | null;
+                audioTracks: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                }[];
+                subtitles: {
+                    language: string | null;
+                    codec: string;
+                }[];
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ItemId">;
+                kind: "episode" | "movie" | "video";
+                showId: (string & import("zod").$brand<"ShowId">) | null;
+                showTitle: string | null;
+                season: number | null;
+                episode: number | null;
+                episodeEnd: number | null;
+                episodeTitle: string | null;
+                files: {
+                    container: string;
+                    durationMs: number | null;
+                    relPath: string | null;
+                    video: {
+                        codec: string;
+                        width: number | null;
+                        height: number | null;
+                        hdr: boolean;
+                        bitDepth: number | null;
+                    } | null;
+                    audio: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    } | null;
+                    audioTracks: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    }[];
+                    subtitles: {
+                        language: string | null;
+                        codec: string;
+                    }[];
+                    id: string & import("zod").$brand<"MediaFileId">;
+                    size: number | null;
+                    edition?: string | null | undefined;
+                    probed: boolean;
+                }[];
+                defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+                markers?: {
+                    kind: "credits" | "intro";
+                    startMs: number;
+                    endMs: number;
+                }[] | null | undefined;
+                audioAnalysis?: {
+                    lufsI: number;
+                    lra: number;
+                    truePeak: number;
+                    dialogLufs?: number | null | undefined;
+                    verdict: "highDynamics" | "ok" | "quietDialog";
+                } | null | undefined;
+            };
+        } | {
+            type: "show";
+            show: {
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ShowId">;
+                seasonCount: number;
+                episodeCount: number;
+                progress?: number | null | undefined;
+            };
+        })[];
+    } | null>;
+    /** Full-text catalogue search (movies, shows, episodes). Server-side
+     * field-weighted, typo-tolerant ranking well suited to imperfect voice
+     * transcripts. `limit` caps results (the server clamps to 60). */
+    search: (query: string, opts?: {
+        library?: LibraryId;
+        limit?: number;
+    }) => Promise<{
+        query: string;
+        results: ({
+            type: "movie";
+            item: {
+                container: string;
+                durationMs: number | null;
+                relPath: string | null;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                audio: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                } | null;
+                audioTracks: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                }[];
+                subtitles: {
+                    language: string | null;
+                    codec: string;
+                }[];
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ItemId">;
+                kind: "episode" | "movie" | "video";
+                showId: (string & import("zod").$brand<"ShowId">) | null;
+                showTitle: string | null;
+                season: number | null;
+                episode: number | null;
+                episodeEnd: number | null;
+                episodeTitle: string | null;
+                files: {
+                    container: string;
+                    durationMs: number | null;
+                    relPath: string | null;
+                    video: {
+                        codec: string;
+                        width: number | null;
+                        height: number | null;
+                        hdr: boolean;
+                        bitDepth: number | null;
+                    } | null;
+                    audio: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    } | null;
+                    audioTracks: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    }[];
+                    subtitles: {
+                        language: string | null;
+                        codec: string;
+                    }[];
+                    id: string & import("zod").$brand<"MediaFileId">;
+                    size: number | null;
+                    edition?: string | null | undefined;
+                    probed: boolean;
+                }[];
+                defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+                markers?: {
+                    kind: "credits" | "intro";
+                    startMs: number;
+                    endMs: number;
+                }[] | null | undefined;
+                audioAnalysis?: {
+                    lufsI: number;
+                    lra: number;
+                    truePeak: number;
+                    dialogLufs?: number | null | undefined;
+                    verdict: "highDynamics" | "ok" | "quietDialog";
+                } | null | undefined;
+            };
+        } | {
+            type: "show";
+            show: {
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ShowId">;
+                seasonCount: number;
+                episodeCount: number;
+                progress?: number | null | undefined;
+            };
+        } | {
+            type: "episode";
+            item: {
+                container: string;
+                durationMs: number | null;
+                relPath: string | null;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                audio: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                } | null;
+                audioTracks: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                }[];
+                subtitles: {
+                    language: string | null;
+                    codec: string;
+                }[];
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ItemId">;
+                kind: "episode" | "movie" | "video";
+                showId: (string & import("zod").$brand<"ShowId">) | null;
+                showTitle: string | null;
+                season: number | null;
+                episode: number | null;
+                episodeEnd: number | null;
+                episodeTitle: string | null;
+                files: {
+                    container: string;
+                    durationMs: number | null;
+                    relPath: string | null;
+                    video: {
+                        codec: string;
+                        width: number | null;
+                        height: number | null;
+                        hdr: boolean;
+                        bitDepth: number | null;
+                    } | null;
+                    audio: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    } | null;
+                    audioTracks: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    }[];
+                    subtitles: {
+                        language: string | null;
+                        codec: string;
+                    }[];
+                    id: string & import("zod").$brand<"MediaFileId">;
+                    size: number | null;
+                    edition?: string | null | undefined;
+                    probed: boolean;
+                }[];
+                defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+                markers?: {
+                    kind: "credits" | "intro";
+                    startMs: number;
+                    endMs: number;
+                }[] | null | undefined;
+                audioAnalysis?: {
+                    lufsI: number;
+                    lra: number;
+                    truePeak: number;
+                    dialogLufs?: number | null | undefined;
+                    verdict: "highDynamics" | "ok" | "quietDialog";
+                } | null | undefined;
+            };
+        })[];
+    }>;
+    /** Every movie + show one person is credited in (cast or key crew),
+     * best-known work first. `name` is a display name or the slug a person URL
+     * carries; the server answers with the spelling the catalogue holds. */
+    people: (name: string, opts?: {
+        library?: LibraryId;
+    }) => Promise<{
+        name: string;
+        results: ({
+            type: "movie";
+            item: {
+                container: string;
+                durationMs: number | null;
+                relPath: string | null;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                audio: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                } | null;
+                audioTracks: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                }[];
+                subtitles: {
+                    language: string | null;
+                    codec: string;
+                }[];
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ItemId">;
+                kind: "episode" | "movie" | "video";
+                showId: (string & import("zod").$brand<"ShowId">) | null;
+                showTitle: string | null;
+                season: number | null;
+                episode: number | null;
+                episodeEnd: number | null;
+                episodeTitle: string | null;
+                files: {
+                    container: string;
+                    durationMs: number | null;
+                    relPath: string | null;
+                    video: {
+                        codec: string;
+                        width: number | null;
+                        height: number | null;
+                        hdr: boolean;
+                        bitDepth: number | null;
+                    } | null;
+                    audio: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    } | null;
+                    audioTracks: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    }[];
+                    subtitles: {
+                        language: string | null;
+                        codec: string;
+                    }[];
+                    id: string & import("zod").$brand<"MediaFileId">;
+                    size: number | null;
+                    edition?: string | null | undefined;
+                    probed: boolean;
+                }[];
+                defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+                markers?: {
+                    kind: "credits" | "intro";
+                    startMs: number;
+                    endMs: number;
+                }[] | null | undefined;
+                audioAnalysis?: {
+                    lufsI: number;
+                    lra: number;
+                    truePeak: number;
+                    dialogLufs?: number | null | undefined;
+                    verdict: "highDynamics" | "ok" | "quietDialog";
+                } | null | undefined;
+            };
+        } | {
+            type: "show";
+            show: {
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ShowId">;
+                seasonCount: number;
+                episodeCount: number;
+                progress?: number | null | undefined;
+            };
+        } | {
+            type: "episode";
+            item: {
+                container: string;
+                durationMs: number | null;
+                relPath: string | null;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                audio: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                } | null;
+                audioTracks: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                }[];
+                subtitles: {
+                    language: string | null;
+                    codec: string;
+                }[];
+                title: string;
+                year: number | null;
+                library: string & import("zod").$brand<"LibraryId">;
+                addedAt: string;
+                metadata?: {
+                    provider: string;
+                    tmdbId: number;
+                    imdbId?: string | null | undefined;
+                    title: string | null;
+                    tagline?: string | null | undefined;
+                    overview: string | null;
+                    releaseDate?: string | null | undefined;
+                    genres: string[];
+                    tmdbGenreIds?: number[] | null | undefined;
+                    rating?: number | null | undefined;
+                    certification?: string | null | undefined;
+                    posterUrl?: string | null | undefined;
+                    backdropUrl?: string | null | undefined;
+                    logoUrl?: string | null | undefined;
+                    themeUrl?: string | null | undefined;
+                    cast?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        character?: string | null | undefined;
+                    }[] | null | undefined;
+                    crew?: {
+                        name: string;
+                        tmdbId?: number | null | undefined;
+                        profileUrl?: string | null | undefined;
+                        job: string;
+                    }[] | null | undefined;
+                    tmdbUrl: string;
+                } | null | undefined;
+                id: string & import("zod").$brand<"ItemId">;
+                kind: "episode" | "movie" | "video";
+                showId: (string & import("zod").$brand<"ShowId">) | null;
+                showTitle: string | null;
+                season: number | null;
+                episode: number | null;
+                episodeEnd: number | null;
+                episodeTitle: string | null;
+                files: {
+                    container: string;
+                    durationMs: number | null;
+                    relPath: string | null;
+                    video: {
+                        codec: string;
+                        width: number | null;
+                        height: number | null;
+                        hdr: boolean;
+                        bitDepth: number | null;
+                    } | null;
+                    audio: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    } | null;
+                    audioTracks: {
+                        index: number;
+                        codec: string;
+                        channels: number | null;
+                        language: string | null;
+                        title?: string | null | undefined;
+                        default: boolean;
+                    }[];
+                    subtitles: {
+                        language: string | null;
+                        codec: string;
+                    }[];
+                    id: string & import("zod").$brand<"MediaFileId">;
+                    size: number | null;
+                    edition?: string | null | undefined;
+                    probed: boolean;
+                }[];
+                defaultFileId?: (string & import("zod").$brand<"MediaFileId">) | null | undefined;
+                markers?: {
+                    kind: "credits" | "intro";
+                    startMs: number;
+                    endMs: number;
+                }[] | null | undefined;
+                audioAnalysis?: {
+                    lufsI: number;
+                    lra: number;
+                    truePeak: number;
+                    dialogLufs?: number | null | undefined;
+                    verdict: "highDynamics" | "ok" | "quietDialog";
+                } | null | undefined;
+            };
+        })[];
+    }>;
+    /** The person behind a credit: biography, birth, birthplace. */
+    person: (name: string) => Promise<{
+        name: string;
+        person?: {
+            tmdbId: number;
+            name: string;
+            biography?: string | null | undefined;
+            birthday?: string | null | undefined;
+            deathday?: string | null | undefined;
+            placeOfBirth?: string | null | undefined;
+            knownFor?: string | null | undefined;
+            profileUrl?: string | null | undefined;
+            tmdbUrl: string;
+        } | null | undefined;
+        credits: {
+            tmdbId: number;
+            title: string;
+            mediaType: "movie" | "tv";
+            year?: number | null | undefined;
+            posterUrl?: string | null | undefined;
+            backdropUrl?: string | null | undefined;
+            overview?: string | null | undefined;
+            character?: string | null | undefined;
+            job?: string | null | undefined;
+        }[];
+    }>;
+    scan: () => Promise<{
+        runId: string & import("zod").$brand<"JobRunId">;
+    }>;
+    /** The last `tail` lines of the server log, as plain text. */
+    logs: (tail?: number) => Promise<string>;
+    /** URL of the server's recent log lines (text/plain). */
+    logsUrl: (tail?: number) => string;
+    /** Direct-play stream URL for a `<video>` src. Range requests are served. */
+    streamUrl: (id: ItemId) => string;
+    /** One-file offline download: video stream-copied, every audio track copied
+     * or AAC-transcoded server-side. `copyCodecs`/`videoCodecs` must distinguish
+     * omitted (no preference, full copy set) from an empty array (decode none,
+     * transcode everything) - collapsing the two would hand a device Dolby/AV1
+     * tracks it can't decode with no fallback once offline. */
+    downloadUrl: (id: ItemId, copyCodecs?: string[], videoCodecs?: string[]) => string;
+    /** HLS master playlist for one continuous remux, with the `audio` track muxed
+     * in. `aac=true` transcodes it to stereo AAC for runtimes that can't decode the
+     * source codec via MSE; `aac=false` stream-copies it. */
+    hlsMasterUrl: (id: ItemId, aac?: boolean, startSec?: number, audio?: number, declaration?: HlsMasterDeclaration) => string;
+    /** WebVTT URL for the n-th embedded subtitle track. The server extracts text
+     * subtitles on demand. */
+    subtitleUrl: (id: ItemId, index: number) => string;
+    /** Manifest endpoint for an item's storyboard. */
+    storyboardUrl: (id: ItemId) => string;
+    /** The storyboard manifest. The server generates the sheet lazily, so this
+     * answers `'pending'` (HTTP 202) while it is being built and `null` when the
+     * item has no usable file or duration (404). */
+    storyboard: (id: ItemId) => Promise<StoryboardManifest | 'pending' | null>;
+};
+declare module '../../core/client' {
+    interface Domains {
+        media: ReturnType<typeof mediaApi>;
+    }
+}