@kromatv/sdk 0.1.40-canary.0

package/types/core/src/genre.d.ts

@@ -0,0 +1,42 @@
+import { type GenreSlug } from './genre-table';
+import { type Translate } from './i18n';
+export type { GenreRow, GenreSlug } from './genre-table';
+export { GENRES } from './genre-table';
+/** The genre a stored display name or a URL slug denotes, in any language the
+ * app ships copy for. `undefined` for a genre no provider list names, which is
+ * never guessed at. */
+export declare function findGenre(nameOrSlug: string): GenreSlug | undefined;
+export declare function genreOfTmdbId(id: number): GenreSlug | undefined;
+export type TitleGenres = {
+    readonly tmdbGenreIds?: readonly number[] | null;
+    readonly genres?: readonly string[] | null;
+};
+/** A genre's stable identity, from a display name in any language the app
+ * ships copy for or from a slug. Falls back to the folded name for a genre no
+ * provider list names, and is idempotent, so a slug resolves to itself. */
+export declare function genreSlug(nameOrSlug: string): string;
+/** How a genre is addressed in a URL: the provider id when the app knows the
+ * genre, so the link carries no language, and the folded name otherwise. */
+export declare function genreSegment(nameOrSlug: string): string;
+/** The genre a URL segment denotes, reading a provider id, a slug, or a
+ * display name a bookmark predates the ids with. Idempotent on a slug it has
+ * no id for, so an unknown genre stays reachable. */
+export declare function genreOfSegment(segment: string): string;
+/** The genre's name in the reader's language, falling back to the spelling
+ * handed in for a genre the app has no copy for. */
+export declare function genreLabel(t: Translate, nameOrSlug: string): string;
+/** The identity of each genre a title carries, read off the provider ids where
+ * enrichment stored them and off the display names otherwise. */
+export declare function genreSlugs(title: TitleGenres | null | undefined): string[];
+/** Each genre a title carries, as the slug it resolves to paired with the
+ * spelling it was stored with. Paired rather than two lists: a genre with
+ * neither a row nor a foldable name is dropped, so a caller indexing the raw
+ * `genres` array by position reads a neighbour's name. */
+export declare function genreEntries(title: TitleGenres | null | undefined): {
+    slug: string;
+    name: string;
+}[];
+/** Each of a title's genres in the reader's language, falling back to the
+ * spelling it was stored with for one the app has no copy for. */
+export declare function genreLabels(t: Translate, title: TitleGenres | null | undefined): string[];
+export declare function genreGlyph(nameOrSlug: string): string | undefined;

package/types/core/src/handoff/beacon.d.ts

@@ -0,0 +1,39 @@
+import { type DeviceId, type KromaClient } from '@kroma/client';
+import type { AuthResult } from '@kroma/client/accounts';
+import { type LanDiscoveryBridge } from './sources';
+/** What the gate screens show while the TV waits: the name a phone sees, and
+ * the check string that says which row in that list is this TV. */
+export interface HandoffBeaconView {
+    name: string;
+    check: string;
+}
+export interface HandoffLoopOptions {
+    client: KromaClient;
+    deviceId: DeviceId;
+    /** Publish the beacon on this device's own link as well, when the platform
+     * has a DNS-SD stack to publish it with. A phone that hears the record has
+     * proved it is in the room, which is worth more than any address the server
+     * can infer, so this is what makes handoff work across a routed home or a
+     * dual-stack one. Absent on a shell that cannot publish. */
+    publish?: NonNullable<LanDiscoveryBridge['publish']>;
+    /** What this TV calls itself in the phone's list. */
+    name: string;
+    platform: string;
+    /** The beacon to show, or null while there is none: announcing, or refused.
+     * A refusal the server will not take back stops the loop for good. */
+    onBeacon: (beacon: HandoffBeaconView | null) => void;
+    onAuthenticated: (result: AuthResult) => void;
+}
+/** The running beacon. */
+export interface HandoffBeaconHandle {
+    /** Take it down, rather than leave it on every nearby phone until its TTL:
+     * the TV signed in, or the screen went away. */
+    stop(): void;
+    /** Say it under another name. The platform is often slower than the first
+     * announce - webOS and Tizen both answer through a bus callback - so the
+     * beacon that went up under "webOS" has to become the one under "Salon"
+     * without a phone ever holding both. */
+    rename(next: string): void;
+}
+/** Start announcing this TV and watching for a grant. */
+export declare function startHandoff(opts: HandoffLoopOptions): HandoffBeaconHandle;

package/types/core/src/handoff/grant.d.ts

@@ -0,0 +1,20 @@
+/** How many characters a television prints as its check string. */
+export declare const HANDOFF_CHECK_LENGTH = 5;
+/** The refusals that end the row rather than the attempt: the beacon is spent,
+ * and no further code reaches it. */
+export type FinalRefusal = 'checkTooMany' | 'gone';
+/** Why a grant did not go through. Each name is also the tail of its copy's
+ * key under `handoff.`, so a picker prints one without a table of its own. */
+export type GrantRefusal = 'checkRequired' | 'checkWrong' | FinalRefusal;
+/** How a grant went. `granted` is the television signing in; `dropped` is one
+ * that was never sent, because another was already in flight. Naming those two
+ * rather than leaving a bare `null` is deliberate: a caller that reads "no
+ * refusal" as "signed in" would report a success nobody had. */
+export type GrantResult = 'granted' | 'dropped' | GrantRefusal;
+/** Read a refused `handoff.grant`. Anything the contract does not name - a
+ * dropped request, a server having a bad time - reads as `gone`, the one answer
+ * that offers the reader nothing to retry with. */
+export declare function grantRefusal(cause: unknown): GrantRefusal;
+/** True while the beacon is still standing and would take another code: keep
+ * the prompt up. False once it is spent, and the row with it. */
+export declare function checkRetryable(refusal: GrantRefusal): refusal is Exclude<GrantRefusal, FinalRefusal>;

package/types/core/src/handoff/index.d.ts

@@ -0,0 +1,8 @@
+export type { HandoffBeaconHandle, HandoffBeaconView, HandoffLoopOptions } from './beacon';
+export { startHandoff } from './beacon';
+export type { FinalRefusal, GrantRefusal, GrantResult } from './grant';
+export { checkRetryable, grantRefusal, HANDOFF_CHECK_LENGTH } from './grant';
+export type { NearbyWatchOptions } from './nearby';
+export { watchNearbyTvs } from './nearby';
+export type { BeaconRecord, DiscoveredTv, LanBeacons, LanDiscoveryBridge, LanService, NearbyReceiver, TvDiscoverySource, } from './sources';
+export { beaconTxt, lanSource, parseBeaconTxt, safeLabel, serverSource, watchLanBeacons, } from './sources';

package/types/core/src/handoff/nearby.d.ts

@@ -0,0 +1,17 @@
+import type { DiscoveredTv, TvDiscoverySource } from './sources';
+export interface NearbyWatchOptions {
+    /** Every way this device has of finding TVs. An empty list is a device that
+     * cannot look, and reports nothing rather than failing. */
+    sources: TvDiscoverySource[];
+    onRows: (rows: DiscoveredTv[]) => void;
+}
+/**
+ * Watch every source at once and report one merged list. Returns the stop
+ * function, which stops all of them.
+ *
+ * Each source reports its whole view, never a delta, so a source going quiet
+ * leaves its last view standing rather than blanking the list. That is
+ * deliberate: a dropped poll is not a TV that went away, and a list that
+ * flickers empty is worse than one a few seconds stale.
+ */
+export declare function watchNearbyTvs(opts: NearbyWatchOptions): () => void;

package/types/core/src/handoff/sources.d.ts

@@ -0,0 +1,110 @@
+import type { KromaClient } from '@kroma/client';
+import { type HandoffDevice } from '@kroma/client/handoff';
+/** One waiting TV, however it was found. */
+export interface DiscoveredTv extends HandoffDevice {
+    /** How this row arrived. `lan` was heard on this link; `server` was listed by
+     * the server from what it could tell of the two devices' addresses. */
+    via: 'lan' | 'server';
+    /** Carried only by `lan` rows: evidence this row was heard on the link, which
+     * the grant sends on so the server can accept it in place of its own
+     * address check. Never displayed. */
+    proof?: string;
+    /** Carried only by `lan` rows: which install minted `handle`. A row whose
+     * server is not the caller's own cannot be granted, and is dropped rather
+     * than offered as a tap that can only fail. */
+    server?: string;
+}
+/** One way of finding TVs. */
+export interface TvDiscoverySource {
+    readonly id: string;
+    /** Start reporting this source's whole view on every change. Returns stop. */
+    start(onRows: (rows: DiscoveredTv[]) => void): () => void;
+}
+/** One DNS-SD record, as every stack in that family describes one. */
+export interface LanService {
+    name: string;
+    txt: Record<string, string>;
+}
+/**
+ * What a platform with a real DNS-SD stack provides. Either half may be absent:
+ * a television publishes and never browses, a telephone browses and never
+ * publishes, and a shell with neither simply passes nothing.
+ *
+ * The service type is the native side's business, not this one's: Apple wants it
+ * declared in `Info.plist` before a browse is allowed at all, so it cannot be a
+ * runtime argument.
+ */
+export interface LanDiscoveryBridge {
+    publish?: (service: LanService) => () => void;
+    browse?: (onFound: (services: LanService[]) => void) => () => void;
+}
+/** What a TV puts in its record, and what a phone reads back out.
+ *
+ * One record type for both states a television can be in, because a phone
+ * looking for televisions wants both answers from one browse: the ones waiting
+ * for an account, and the ones already signed in and ready to be cast to. What
+ * the phone can DO with a row differs; that it can see the row does not. */
+export type BeaconRecord = {
+    /** Signed out, and waiting for someone to hand it an account. */
+    state: 'waiting';
+    name: string;
+    platform: string;
+    /** The install that minted `handle`, so a phone on a different server
+     * knows this row is not one it can sign in. */
+    server: string;
+    handle: string;
+    check: string;
+    proof: string;
+} | {
+    /** Signed in, on the cast roster, ready to be played to. */
+    state: 'ready';
+    name: string;
+    platform: string;
+    /** Its id on the cast roster, so a row heard here and a row listed by the
+     * server are recognised as one television. */
+    receiver: string;
+};
+/** One signed-in television heard on the link. Carries no authority: a command
+ * still travels through the server, which is the only thing that knows whose
+ * television this is. */
+export interface NearbyReceiver {
+    receiverId: string;
+    name: string;
+    platform: string;
+}
+/** A name from off-device, stripped and optionally capped, for the same reason
+ * the server strips what a device tells it: these are drawn in someone else's
+ * picker, where a raw newline could forge a line. */
+export declare function safeLabel(value: string | null | undefined, max?: number): string;
+/** The text dictionary a TV publishes. Keys are short, as DNS-SD prefers. */
+export declare function beaconTxt(record: BeaconRecord): Record<string, string>;
+/** Read a record back, or null if it is not one this build understands.
+ *
+ * Anything on the link can publish one of these, so this is a boundary: a record
+ * that is malformed, from a future version, or simply too long to be honest is
+ * dropped rather than shown half-empty or passed on to the server. */
+export declare function parseBeaconTxt(txt: Record<string, string>): BeaconRecord | null;
+/** Everything this device can hear, split by what can be done with it. */
+export interface LanBeacons {
+    /** Televisions with no account, which a phone can sign in. */
+    pairable: DiscoveredTv[];
+    /** Televisions already signed in. Discovery only: what a sender may command
+     * is still the server's to say. */
+    receivers: NearbyReceiver[];
+}
+/**
+ * Watch the link once and report both halves.
+ *
+ * One browse rather than two: a caller that wants both would otherwise stand up
+ * two browsers over the same service type, and on a phone that is two multicast
+ * listeners for one question.
+ */
+export declare function watchLanBeacons(bridge: LanDiscoveryBridge, onBeacons: (beacons: LanBeacons) => void): () => void;
+/** The TVs the server can see from the two devices' addresses. Works wherever
+ * the server does, which is everywhere, and is the only source a browser has. */
+export declare function serverSource(client: KromaClient, everyMs?: number): TvDiscoverySource;
+/** The TVs this device can hear on its own link. Stronger evidence of being in
+ * the same room than any address comparison: link-local multicast does not
+ * cross a router, so a record you heard is a TV you are next to.
+ */
+export declare function lanSource(bridge: LanDiscoveryBridge): TvDiscoverySource;

package/types/core/src/health-probe.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export declare const HealthProbe: z.ZodObject<{
+    name: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    instanceId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    version: z.ZodOptional<z.ZodString>;
+    ffprobe: z.ZodOptional<z.ZodBoolean>;
+    libraries: z.ZodOptional<z.ZodNumber>;
+    items: z.ZodOptional<z.ZodNumber>;
+    shows: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodString;
+}, z.core.$strip>;
+export type HealthProbe = z.infer<typeof HealthProbe>;
+export declare function probeFinalOrigin(fetchFn: typeof globalThis.fetch, base: string, timeoutMs: number): Promise<string | null>;
+export declare function raceForServer(urls: string[], fetchFn: typeof globalThis.fetch, timeoutMs: number, concurrency?: number): Promise<string | null>;
+export declare function probeAll(urls: string[], fetchFn: typeof globalThis.fetch, timeoutMs: number, concurrency: number): Promise<Array<{
+    url: string;
+    body: HealthProbe;
+}>>;
+export declare function stripTrailingSlash(url: string): string;

package/types/core/src/hevc/audio-support.d.ts

@@ -0,0 +1,47 @@
+import type { AudioTrack, MediaItem } from '@kroma/client/media';
+import type { MessageKey, TVars } from '../i18n';
+import { type PlaybackCapabilities } from './capabilities';
+/** Browsers cannot decode AC3/EAC3/DTS/TrueHD, which plays as video with no
+ * sound; `messageKey` is null when audio plays fine. */
+export interface AudioSupport {
+    canPlay: boolean;
+    messageKey: MessageKey | null;
+    messageVars?: TVars;
+}
+export declare function audioSupport(item: MediaItem, caps?: PlaybackCapabilities): AudioSupport;
+/** Audio codecs ffmpeg can stream-copy into the fMP4 HLS variant, preserving
+ * surround; others (DTS/TrueHD/FLAC/Opus) fall back to a stereo-AAC transcode. */
+export declare const FMP4_COPY_CODECS: Set<string>;
+/** Falls back to a single track for older payloads that only carry the
+ * representative `audio`. */
+export declare function audioTracksOf(item: MediaItem): AudioTrack[];
+/** Unknown codecs are assumed decodable. */
+export declare function canDecodeAudioCodec(codec: string | undefined, caps?: PlaybackCapabilities): boolean;
+/** Whether the single-stream HLS master can carry every audio track as an
+ * alternate rendition, making language switches in-place. */
+export declare function canSeamlessAudioSwitch(item: MediaItem, caps?: PlaybackCapabilities): boolean;
+/**
+ * For a master stream, whether audio must be transcoded to stereo AAC (true) or
+ * can be stream-copied (false). Copy preserves surround and needs EVERY track to
+ * be natively decodable and fMP4-copy-safe here. Unprobed audio must be AAC:
+ * stream-copying a codec the browser cannot decode stalls the load on
+ * `HAVE_NOTHING`.
+ */
+export declare function masterNeedsAac(item: MediaItem, caps?: PlaybackCapabilities): boolean;
+/**
+ * Track selection must key off this, never the array order: the server can serve
+ * `item.audioTracks` in a different order than the player last saw.
+ */
+export interface AudioTrackId {
+    index: number;
+    language: string | null;
+    title: string | null;
+    channels: number | null;
+}
+export declare function audioTrackId(t: AudioTrack): AudioTrackId;
+/**
+ * Resolve a wanted audio identity to the audio-relative index to select (what
+ * `hls.audioTrack` / a Safari `video.audioTracks` slot expects), tolerating a
+ * reordered track list.
+ */
+export declare function resolveAudioRelativeIndex(tracks: AudioTrack[], want: AudioTrackId): number;

package/types/core/src/hevc/capabilities.d.ts

@@ -0,0 +1,63 @@
+export interface AudioCapabilities {
+    aac: boolean;
+    ac3: boolean;
+    eac3: boolean;
+    dts: boolean;
+    truehd: boolean;
+    flac: boolean;
+    opus: boolean;
+    mp3: boolean;
+    vorbis: boolean;
+}
+export interface FrameSize {
+    width: number;
+    height: number;
+}
+/** The largest frame each video decoder accepts, keyed by the codec name an
+ * item carries (ffprobe's: `hevc`, `h264`, `av1`, `vp9`). A codec with no entry
+ * is not gated on size. */
+export type DecoderFrameLimits = Readonly<Record<string, FrameSize>>;
+export interface PlaybackCapabilities {
+    hevc: boolean;
+    hevc10bit: boolean;
+    h264: boolean;
+    av1: boolean;
+    vp9: boolean;
+    hdr: boolean;
+    /** Absent where the runtime will not say, which gates nothing. */
+    frameLimits?: DecoderFrameLimits;
+    audio: AudioCapabilities;
+    source: 'mediaSource' | 'videoElement' | 'platform-tv' | 'unknown';
+}
+/**
+ * How large a picture this device's decoders will actually accept, which no Web
+ * API reports and every platform table above guesses at: a shell that can ask
+ * the platform hands the answer over at the app root, before the first render.
+ * Null clears it. Drops the cached capabilities, so it may be called either side
+ * of the first {@link capabilities} read.
+ */
+export declare function setDecoderFrameLimits(limits: DecoderFrameLimits | null): void;
+export declare function detectCapabilities(): PlaybackCapabilities;
+/** Cached: capabilities cannot change within a session. */
+export declare function capabilities(): PlaybackCapabilities;
+/**
+ * The audio codecs this device can decode, named the way the server names them
+ * (ffprobe's `codec_name`, which is what an item's audio tracks carry).
+ *
+ * This is what a player sends as `copyCodecs`: the server stream-copies audio by
+ * default and only re-encodes what this list leaves out, so a device that never
+ * declares anything is served a copy of everything and plays whatever it cannot
+ * decode as silence.
+ */
+export declare function decodableAudioCodecs(caps?: PlaybackCapabilities): string[];
+/**
+ * The video codecs this device can decode, named the way the server names them
+ * (ffprobe's `codec_name`, which is what an item's video stream carries).
+ *
+ * This is what a player sends as `videoCodecs`: the server stream-copies video by
+ * default and only re-encodes a source this list leaves out, so a device that
+ * declares nothing is served a copy and shows a black picture for anything it
+ * cannot decode. A codec name carries no bit depth, so a caller playing a 10-bit
+ * source on a runtime whose `hevc10bit` is false declares `{ ...caps, hevc: false }`.
+ */
+export declare function decodableVideoCodecs(caps?: PlaybackCapabilities): string[];

package/types/core/src/hevc/directplay.d.ts

@@ -0,0 +1,70 @@
+import type { MediaItem } from '@kroma/client/media';
+import type { MessageKey, TVars } from '../i18n';
+import { type FrameSize, type PlaybackCapabilities } from './capabilities';
+export interface DirectPlayVerdict {
+    canDirectPlay: boolean;
+    messageKey: MessageKey;
+    messageVars?: TVars;
+    /** A second line, where knowing WHY leaves the viewer with something to do
+     * about it. Shares `messageVars` with the line above. */
+    hintKey?: MessageKey;
+}
+/** A picture larger than the decoder that would have to draw it. */
+export interface FrameOverrun {
+    frame: FrameSize;
+    limit: FrameSize;
+}
+/**
+ * The decoder ceiling this item's picture is over, or null when it fits or the
+ * device never declared one. Distinct from every other reason a title will not
+ * direct-play, because it is the one no fallback answers: another engine decodes
+ * the same frame, and the server only repackages it. The picture has to shrink,
+ * which nothing on the playback path does.
+ */
+export declare function beyondDecoder(item: MediaItem, caps?: PlaybackCapabilities): FrameOverrun | null;
+/**
+ * How a picture reads to a viewer: the tier the catalogue already names it by.
+ * Its LARGER axis decides, because a 3840x1604 scope frame is 4K at 1604 rows.
+ */
+export declare function frameLabel({ width, height }: FrameSize): string;
+/**
+ * How a decoder's ceiling reads: the largest picture that fits INSIDE it, which
+ * is not the same question. A decoder declaring 1920x1920 is a 1080p decoder,
+ * not a 1440p one - nothing 1440p wide fits in 1920 columns.
+ */
+export declare function ceilingLabel({ width, height }: FrameSize): string;
+/**
+ * The largest picture a master may deliver to this device, or undefined where it
+ * declared no ceiling. What a client sends the server as `maxFrame`: a bigger
+ * source is fitted inside the nearest rung under it, which is the one thing no
+ * player does for itself.
+ *
+ * A master arrives as a copy of `item`'s own codec or as the H.264 re-encode, so
+ * the ceiling that holds for both is the SMALLER of the two decoders. Taking the
+ * largest across every codec is what lets a device whose H.264 decoder stops
+ * below its HEVC one be handed a copy it has just refused.
+ */
+export declare function decoderMaxFrame(item?: MediaItem, caps?: PlaybackCapabilities): FrameSize | undefined;
+/**
+ * How an overrun reads to a viewer: the tier the picture is in, and the tier the
+ * decoder stops at. The two tables answer different questions, so they can land
+ * on the same name for a frame that genuinely does not fit: a 2048x858 scope
+ * print is 1080p, and so is the 1920x1920 decoder it overruns on width. The
+ * frame gives its own size there, because a sentence naming one tier twice tells
+ * the viewer nothing.
+ */
+export declare function overrunLabels({ frame, limit }: FrameOverrun): {
+    source: string;
+    ceiling: string;
+};
+export declare function canDirectPlay(item: MediaItem, caps?: PlaybackCapabilities): DirectPlayVerdict;
+/** Chromium MSE (hls.js on Chrome/Firefox/webOS): no AC3/EAC3/DTS audio, so
+ * those masters must be AAC. */
+export declare const MSE_CAPS: PlaybackCapabilities;
+/** Safari native HLS: AC3/EAC3 decode natively, so surround masters can be
+ * stream-copied. AV1 in Safari / WKWebView is hardware-only (Apple Silicon M3+)
+ * with no software fallback, hence `av1: false`; mpv is the AV1 path there. */
+export declare const SAFARI_CAPS: PlaybackCapabilities;
+/** Native TV decoder (AVPlay / native `<video>` on Tizen/webOS): decodes
+ * everything, so masters can be stream-copied. */
+export declare const NATIVE_TV_CAPS: PlaybackCapabilities;

package/types/core/src/hevc/engine.d.ts

@@ -0,0 +1,29 @@
+import type { MediaItem } from '@kroma/client/media';
+import type { PlaybackCapabilities } from './capabilities';
+export type PlayerEngineKind = 'direct' | 'web-mse' | 'tizen-avplay' | 'webos' | 'desktop-mpv';
+export interface PlayEnv {
+    platform: 'web' | 'tizen' | 'webos' | 'desktop';
+    safari: boolean;
+    runtimeCaps?: PlaybackCapabilities;
+    nativeHls?: boolean;
+}
+export interface EngineDecision {
+    kind: PlayerEngineKind;
+    aacMaster: boolean;
+}
+/** Whether Tizen's native AVPlay can play the ORIGINAL file with no server
+ * remux. Audio is not a gate; the engine falls back to the HLS master on a real
+ * playback error. */
+export declare function avplayDirectPlayable(item: MediaItem): boolean;
+/**
+ * Whether the native clients (AVPlayer on Apple TV, Media3 on Android TV) can
+ * open the ORIGINAL file rather than the server's remux. Split by platform
+ * because container support is where the two players differ.
+ */
+export declare function nativeDirectPlayable(item: MediaItem, os: 'ios' | 'android'): boolean;
+/**
+ * Pick the playback engine and master variant for an item in an environment.
+ * Engines that keep a direct→master error fallback (mpv, AVPlay, bare `<video>`)
+ * may be chosen optimistically.
+ */
+export declare function selectEngine(item: MediaItem, env: PlayEnv): EngineDecision;

package/types/core/src/hevc.d.ts

@@ -0,0 +1,4 @@
+export * from './hevc/audio-support';
+export * from './hevc/capabilities';
+export * from './hevc/directplay';
+export * from './hevc/engine';