@phont-ai/subtitles-core 0.2.2 → 0.2.4

package/dist/index.d.ts

@@ -381,8 +381,17 @@ declare class SubtitleManager {
     normalizeSubtitles(data: any): any;
     normalizeSoundbites(arr: any[]): any[];
     getAudioSegmentDuration(sequenceNumber: number): Promise<number>;
+    /**
+     * Configure the live HLS master URL at runtime. Required for SDK consumers
+     * who don't set NEXT_PUBLIC_API_LIVE_URL at build time. When set, fetches
+     * use sidecar mode against this URL.
+     */
+    setLiveMasterUrl(url: string | null): void;
     getInitialLiveSequenceNumber(): Promise<number>;
-    fetchSubtitles(sequenceNumber: number): Promise<any | null>;
+    recordSegmentDuration(sequenceNumber: number, duration: number): void;
+    recordInitialSequenceOffset(sequenceNumber: number): void;
+    fetchSubtitles(sequenceNumber: number, fragStart: number): Promise<any | null>;
+    updateLiveTimeFromVideo(videoTime: number): void;
     loadVodSubtitles(urlOrVodId: string, languageCode?: string | null): Promise<void>;
     _processVodData(data: any, url: string, languageCode: string | null, originalSubtitles?: any[]): void;
     getSubtitleForTime(time: number): any;
@@ -414,6 +423,145 @@ declare class SubtitleManager {
 }
 declare const subtitleManager: SubtitleManager;
 
+/**
+ * LiveSegmentSource — player-agnostic interface for the live subtitle
+ * pipeline.
+ *
+ * Each concrete adapter (hls.js / Shaka / Bitmovin) wraps a player
+ * instance and normalizes its segment-lifecycle events into the two
+ * callbacks below. The subtitle hook subscribes to a `LiveSegmentSource`
+ * and never imports a player SDK directly, so swapping players is a
+ * one-file change.
+ *
+ * Contract:
+ *   - `onInitialPlaylist` MUST fire exactly once, with the fragments
+ *     visible in the first playlist the player parses. Subscribers use
+ *     it for backfill.
+ *   - `onSegmentLoaded` fires once per audio-aligned segment as the
+ *     player loads it. Adapters MUST dedupe by `sn` so subscribers see
+ *     each segment at most once across the lifetime of the source.
+ *   - Sequence numbers (`sn`) are the HLS media-sequence integer. For
+ *     DASH or other manifest formats, the adapter is responsible for
+ *     synthesizing an equivalent monotonically-increasing integer.
+ */
+interface SegmentInfo {
+    /** HLS media sequence number. */
+    sn: number;
+    /** Segment duration in seconds. */
+    duration: number;
+    /**
+     * Presentation-timeline start of this fragment, in the same space as
+     * `video.currentTime`. Used to anchor subtitle cues directly to media
+     * time.
+     */
+    start?: number;
+    /** Resolved segment URL (debugging only). */
+    uri?: string;
+    /** `'main'` | `'audio'` | `'subtitle'`. */
+    type?: string;
+}
+interface InitialPlaylist {
+    /** Media-sequence of the first fragment. */
+    startSn: number;
+    /** All fragments in the initial window. */
+    fragments: SegmentInfo[];
+    /** URI of the playlist these came from. */
+    playlistUri?: string;
+}
+type SegmentListener = (info: SegmentInfo) => void;
+type InitialPlaylistListener = (info: InitialPlaylist) => void;
+interface LiveSegmentSource {
+    /**
+     * Subscribe to per-segment-loaded events. Returns a teardown function
+     * that unregisters the listener.
+     */
+    onSegmentLoaded(cb: SegmentListener): () => void;
+    /**
+     * Subscribe to the once-per-stream initial-playlist event. Returns a
+     * teardown function that unregisters the listener.
+     */
+    onInitialPlaylist(cb: InitialPlaylistListener): () => void;
+    /**
+     * Tear down the adapter — unhook all player events, clear listener
+     * sets. Safe to call multiple times.
+     */
+    destroy(): void;
+}
+/**
+ * Build a `LiveSegmentSource` with shared listener bookkeeping. Concrete
+ * adapters call `emitSegment` / `emitInitial` when their underlying
+ * player fires the corresponding event, and register cleanup hooks via
+ * `addTeardown`.
+ */
+declare function createLiveSegmentSource(): {
+    source: LiveSegmentSource;
+    emitSegment: (info: SegmentInfo) => void;
+    emitInitial: (info: InitialPlaylist) => void;
+    addTeardown: (fn: () => void) => void;
+};
+
+/**
+ * Wrap an hls.js instance into a LiveSegmentSource.
+ *
+ * Most AMS HLS output is muxed (combined A+V under one playlist,
+ * `frag.type === 'main'`) but split-audio renditions also exist
+ * (`frag.type === 'audio'`). We accept both and dedupe by `sn`, so
+ * whichever fires first per sequence wins.
+ *
+ * Initial playlist comes from `LEVEL_LOADED` (muxed) or
+ * `AUDIO_TRACK_LOADED` (split). First one with fragments wins.
+ *
+ * @param hls   The hls.js instance (from `new Hls()`).
+ * @param Hls   The hls.js namespace (for `Hls.Events`). hls.js doesn't
+ *              re-export `Events` off instances; callers pass the
+ *              imported module's default.
+ */
+declare function createHlsLiveSegmentSource(hls: any, Hls: any): LiveSegmentSource;
+
+/**
+ * Wrap a shaka.Player instance into a LiveSegmentSource.
+ *
+ * NOT YET IMPLEMENTED — placeholder so the adapter layout is in place.
+ *
+ * Implementation outline:
+ *   - Segment-loaded:
+ *       Use `player.getNetworkingEngine().registerResponseFilter((type, response) => …)`
+ *       and filter `type === shaka.net.NetworkingEngine.RequestType.SEGMENT`.
+ *       Shaka does not surface an HLS media-sequence number directly;
+ *       parse it out of `response.uri` (the AMS segment filenames carry
+ *       the sn), or compute it as
+ *       `Math.round(response.timeMs * 1000 / segmentDurationMs)`.
+ *   - Initial playlist:
+ *       Listen for the `manifestparsed` event on the player. Walk
+ *       `player.getVariantTracks()` / the parsed manifest to gather the
+ *       initial fragments. Shaka's HLS parser keeps the sn in the
+ *       segment references; you may need to dip into private API or
+ *       parse the playlist text yourself.
+ *   - Don't forget to remove the response filter in `destroy`.
+ */
+declare function createShakaLiveSegmentSource(_player: any, _shaka: any): LiveSegmentSource;
+
+/**
+ * Wrap a Bitmovin Player instance into a LiveSegmentSource.
+ *
+ * NOT YET IMPLEMENTED — placeholder so the adapter layout is in place.
+ *
+ * Implementation outline:
+ *   - Segment-loaded:
+ *       Subscribe to `PlayerEvent.SegmentRequestFinished`. The event
+ *       payload includes `mediaType` (audio/video) and a `url`. Parse
+ *       the HLS sn out of the segment URL (AMS encodes it in the
+ *       filename), or maintain a counter keyed off the playlist start
+ *       sn.
+ *   - Initial playlist:
+ *       Subscribe to `PlayerEvent.SourceLoaded` and read the parsed
+ *       manifest via the player's manifest API. Walk audio (or muxed)
+ *       segments to build the initial-window list.
+ *   - `destroy` MUST `player.off(...)` everything to avoid leaks across
+ *     hot reloads.
+ */
+declare function createBitmovinLiveSegmentSource(_player: any): LiveSegmentSource;
+
 /**
  * URL Decoder for Animation Parameters
  *
@@ -484,6 +632,8 @@ interface AnimationParameterState {
     textColor: string;
     opacity: number;
     textShadow: string;
+    shadowX?: number;
+    shadowY?: number;
     blur: number;
     outlineWidth: number;
     outlineColor: string;
@@ -739,6 +889,15 @@ declare const ANIMATION_STYLING: {
         minDisplayTime: number;
         allowOverlap: boolean;
     };
+    subtitleBackground: {
+        background: string;
+        border: string;
+        borderRadius: number;
+        boxShadow: string;
+        backdropFilter: string;
+        paddingX: number;
+        paddingY: number;
+    };
 };
 
 /**
@@ -889,6 +1048,107 @@ declare function generateTextShadow(shadowColor: string | undefined, _fontFamily
  * @returns CSS em value for marginRight
  */
 declare function calculateDynamicWordSpacing(currentScale?: number, fontFamily?: string, gtsIntensity?: number, emotion?: string): string;
+/**
+ * Tighter spacing for a single animated word in an otherwise normal line.
+ * Full calculateDynamicWordSpacing assumes the whole line scales together;
+ * per-word pops (e.g. spain-goal on one word) only need room for local overflow.
+ */
+declare function calculatePerWordSpacing(currentScale?: number, fontFamily?: string, gtsIntensity?: number, emotion?: string): string;
+
+/**
+ * Resolve which animation URL / emotion / intensity apply to a single word.
+ * Word-level fields override segment defaults when present.
+ */
+interface WordAnimationFields {
+    animation_url?: string | null;
+    emotion?: string | null;
+    emotion_intensity?: number | null;
+}
+interface WordAnimationSource {
+    animationUrl: string | null;
+    emotion: string | null;
+    emotionIntensity: number | null;
+    hasWordOverride: boolean;
+}
+declare function hasWordAnimationOverride(word: WordAnimationFields | null | undefined): boolean;
+declare function resolveWordAnimationSource(word: WordAnimationFields | null | undefined, segment: WordAnimationFields | null | undefined): WordAnimationSource;
+
+/**
+ * Helpers for author-assigned vs auto-detected subtitle animations.
+ */
+
+declare const NORMAL_ANIMATION_EMOTIONS: Set<string>;
+declare function isNormalAnimationEmotion(emotion: string | null | undefined): boolean;
+/**
+ * Segment has an explicit author animation assignment (metadata panel save).
+ * Backend-only emotion labels without author fields do not count.
+ */
+declare function hasSegmentAnimationOverride(segment: WordAnimationFields | null | undefined): boolean;
+declare function clearWordAnimationFields<T extends WordAnimationFields>(word: T): T;
+declare function clearSegmentAnimationFields<T extends WordAnimationFields>(segment: T): T;
+declare function resetSubtitleToNormal<T extends WordAnimationFields & {
+    words?: WordAnimationFields[];
+}>(subtitle: T): T;
+declare function subtitleHasAnyAnimationOverride(subtitle: WordAnimationFields & {
+    words?: WordAnimationFields[];
+} | null | undefined): boolean;
+declare function getManualAnimationsStorageKey(videoId: string | null | undefined): string | null;
+declare function readManualAnimationsPreference(videoId: string | null | undefined): boolean;
+declare function writeManualAnimationsPreference(videoId: string | null | undefined, enabled: boolean): void;
+/**
+ * "Manual soundbites only" mode: when enabled, auto-detected soundbites are
+ * suppressed (no text, no animation) and only soundbites the author added by
+ * hand (tagged `manual: true`) are shown. Mirrors the manual-animations pref.
+ */
+declare function getManualSoundbitesStorageKey(videoId: string | null | undefined): string | null;
+declare function readManualSoundbitesPreference(videoId: string | null | undefined): boolean;
+declare function writeManualSoundbitesPreference(videoId: string | null | undefined, enabled: boolean): void;
+/** Clamp and round intensity to 0–1 (3 decimal places). */
+declare function clampAnimationIntensity(value: number): number;
+/**
+ * Multiply author-set emotion_intensity on segments and words by `factor`.
+ * Only touches overrides that already have an explicit intensity (GTS-independent).
+ */
+declare function scaleAuthorAnimationIntensities<T extends WordAnimationFields & {
+    words?: WordAnimationFields[];
+}>(subtitles: T[], factor: number): {
+    segmentCount: number;
+    wordCount: number;
+};
+
+/**
+ * Word-level expressive animation scheduling.
+ *
+ * When `ANIMATION_STYLING.wordAnimation.allowOverlap` is false, each word's
+ * URL curve runs only after the previous word finishes — then returns to rest
+ * (t = 0) before the next word begins.
+ */
+interface WordTimingWindow {
+    start: number;
+    end: number;
+}
+interface SequentialWordExpressiveSlot {
+    expressiveStart: number;
+    expressiveDuration: number;
+}
+declare function getWordExpressiveDuration(word: WordTimingWindow): number;
+type WordExpressiveSchedule = Array<SequentialWordExpressiveSlot | null>;
+declare function buildSequentialExpressiveSchedule(words: WordTimingWindow[], shouldAnimate?: (word: WordTimingWindow, index: number) => boolean): WordExpressiveSchedule;
+declare function isWordAnimationOverlapAllowed(): boolean;
+/**
+ * Progress along the authored URL curve (0–1).
+ * Overlap allowed: progress follows backend word.start and holds at 1 after the curve completes.
+ * Sequential: each word waits for the previous slot, then returns to 0 after its curve completes.
+ */
+declare function calculateWordExpressiveProgress(currentTime: number, word: WordTimingWindow, slot: SequentialWordExpressiveSlot | null | undefined, allowOverlap?: boolean): number;
+declare function getSegmentAnimationPreviewTime(startTime: number | null | undefined, endTime: number | null | undefined): number;
+/**
+ * Time (seconds) at the midpoint of a word's expressive URL curve — matches playback scheduling.
+ */
+declare function getWordAnimationPreviewTime(words: WordTimingWindow[], wordIndex: number, options?: {
+    shouldAnimate?: (word: WordTimingWindow, index: number) => boolean;
+    allowOverlap?: boolean;
+}): number | null;
 
 /**
  * Prosody Weight — Natural Voice Intonation for Animations
@@ -1463,4 +1723,47 @@ declare class PhontClient {
     clearCredentials(): void;
 }
 
-export { ANIMATION_STYLING, ANIMATION_URLS, AUTHORED_PLAYBACK_OPTIONS, type AnimationFetcher, type AnimationOptions, type AnimationParameterState, type AnimationParameterStates, type AnimationRecord, type AnimationState, type CurvePoint, EMOTION_ANIMATION_URLS, type Emotion, type EmotionSelectionResult, type EmotionStyle, type EmphasisEffect, type FontAxisConfig, type FontConfig, type JoyEffect, type Letter, type LoginResponse, type ParameterState, type ParameterStates, PhontClient, type PhontClientOptions, type PublishedAnimationResolver, REFERENCE_GTS, REFERENCE_INTENSITY, RENDERING_CONTROL, type RegisterResponse, type SentenceAnimationState, type StateCallback, type StrongEmphasisData, type Stylesheet, type SubtitleEngineState, type SubtitleLine, SubtitleManager, type SubtitleSegment, type SubtitleState$1 as SubtitleState, SubtitleStateManager, type SubtitleTrack, type SubtitleWord, type VodMetadata, type VodState$1 as VodState, type Word, type WordAnimationState, type WordLetterSpacingParams, calculateAnimationParameters, calculateAnimationState, calculateDynamicWordSpacing, calculateEmphasisMultiplier, calculateGTSValues, calculateJoy, calculateJoyBulge, calculateNormalizedTime, calculateWeightFromVolume, calculateWidthFromSpeechRate, calculateWordEmphasisEffects, calculateWordLetterSpacing, capEmotionIntensity, computeProsodyWeight, createPublishedAnimationResolver, decodeAnimationUrl, ensureFont, findSubtitleForWord, generateTextShadow, getAnimationUrlForEmotion, getCombinedBlurAmount, getFontFamilyCSS, getJoyAnimationMode, getJoyFilter, getJoyTransform, getMergedSubtitles, getMotionBlurAmount, getSubtitleAnimations, getSubtitleText, getSubtitleTiming, getSubtitleWords, getWordEmphasis, hasMergedSubtitles, hockeyStickIntensity, isInEmphasisRange, isInStrongEmphasisRange, meetsEmotionThreshold, preloadAnimationFonts, processEmotionsWithImportance, resolveEffectiveGts, sampleParameterCurve, selectEmotion, selectFontFamily, shouldUseAngryFont, shouldUseJoyFont, shouldUseSadnessFont, splitTextIntoLetters, subtitleManager };
+/**
+ * Get auth token for the current active user
+ * Used by API client
+ * @returns {string | null}
+ */
+declare function getCurrentAuthToken(): string | null;
+/**
+ * Get session ID for the current active user
+ * Used by API client
+ * @returns {string | null}
+ */
+declare function getCurrentSessionId(): string | null;
+
+/**
+ * Opt-in: one pretty console dump per VOD fetch (no per-frame spam).
+ *
+ * Enable: `?debug=subtitles` or `?stage_debug=subtitles` or
+ * `localStorage.setItem('phont_debug_subtitles', '1')`
+ */
+type SubtitleDebugEntry = {
+    at: string;
+    vodId?: string | null;
+    url?: string;
+    raw: unknown;
+};
+type SubtitleDebugStore = {
+    enabled: boolean;
+    last: SubtitleDebugEntry | null;
+    dumpLast: () => SubtitleDebugEntry | null;
+    copyLast: () => Promise<string>;
+};
+declare global {
+    interface Window {
+        __phontSubtitleDebug?: SubtitleDebugStore;
+    }
+}
+declare function isSubtitleDebugEnabled(): boolean;
+/** One styled log per vodId (+ optional url key); stores payload on window.__phontSubtitleDebug */
+declare function logSubtitleData(data: unknown, meta?: {
+    vodId?: string | null;
+    url?: string;
+}): void;
+
+export { ANIMATION_STYLING, ANIMATION_URLS, AUTHORED_PLAYBACK_OPTIONS, type AnimationFetcher, type AnimationOptions, type AnimationParameterState, type AnimationParameterStates, type AnimationRecord, type AnimationState, type CurvePoint, EMOTION_ANIMATION_URLS, type Emotion, type EmotionSelectionResult, type EmotionStyle, type EmphasisEffect, type FontAxisConfig, type FontConfig, type InitialPlaylist, type InitialPlaylistListener, type JoyEffect, type Letter, type LiveSegmentSource, type LoginResponse, NORMAL_ANIMATION_EMOTIONS, type ParameterState, type ParameterStates, PhontClient, type PhontClientOptions, type PublishedAnimationResolver, REFERENCE_GTS, REFERENCE_INTENSITY, RENDERING_CONTROL, type RegisterResponse, type SegmentInfo, type SegmentListener, type SentenceAnimationState, type SequentialWordExpressiveSlot, type StateCallback, type StrongEmphasisData, type Stylesheet, type SubtitleDebugEntry, type SubtitleDebugStore, type SubtitleEngineState, type SubtitleLine, SubtitleManager, type SubtitleSegment, type SubtitleState$1 as SubtitleState, SubtitleStateManager, type SubtitleTrack, type SubtitleWord, type VodMetadata, type VodState$1 as VodState, type Word, type WordAnimationFields, type WordAnimationSource, type WordAnimationState, type WordExpressiveSchedule, type WordLetterSpacingParams, type WordTimingWindow, buildSequentialExpressiveSchedule, calculateAnimationParameters, calculateAnimationState, calculateDynamicWordSpacing, calculateEmphasisMultiplier, calculateGTSValues, calculateJoy, calculateJoyBulge, calculateNormalizedTime, calculatePerWordSpacing, calculateWeightFromVolume, calculateWidthFromSpeechRate, calculateWordEmphasisEffects, calculateWordExpressiveProgress, calculateWordLetterSpacing, capEmotionIntensity, clampAnimationIntensity, clearSegmentAnimationFields, clearWordAnimationFields, computeProsodyWeight, createBitmovinLiveSegmentSource, createHlsLiveSegmentSource, createLiveSegmentSource, createPublishedAnimationResolver, createShakaLiveSegmentSource, decodeAnimationUrl, ensureFont, findSubtitleForWord, generateTextShadow, getAnimationUrlForEmotion, getCombinedBlurAmount, getCurrentAuthToken, getCurrentSessionId, getFontFamilyCSS, getJoyAnimationMode, getJoyFilter, getJoyTransform, getManualAnimationsStorageKey, getManualSoundbitesStorageKey, getMergedSubtitles, getMotionBlurAmount, getSegmentAnimationPreviewTime, getSubtitleAnimations, getSubtitleText, getSubtitleTiming, getSubtitleWords, getWordAnimationPreviewTime, getWordEmphasis, getWordExpressiveDuration, hasMergedSubtitles, hasSegmentAnimationOverride, hasWordAnimationOverride, hockeyStickIntensity, isInEmphasisRange, isInStrongEmphasisRange, isNormalAnimationEmotion, isSubtitleDebugEnabled, isWordAnimationOverlapAllowed, logSubtitleData, meetsEmotionThreshold, preloadAnimationFonts, processEmotionsWithImportance, readManualAnimationsPreference, readManualSoundbitesPreference, resetSubtitleToNormal, resolveEffectiveGts, resolveWordAnimationSource, sampleParameterCurve, scaleAuthorAnimationIntensities, selectEmotion, selectFontFamily, shouldUseAngryFont, shouldUseJoyFont, shouldUseSadnessFont, splitTextIntoLetters, subtitleHasAnyAnimationOverride, subtitleManager, writeManualAnimationsPreference, writeManualSoundbitesPreference };