@phont-ai/subtitles-core 0.1.10

package/dist/index.d.mts

@@ -0,0 +1,1346 @@
+/**
+ * Core types for PHONT expressive subtitles
+ * Framework-agnostic, pure TypeScript
+ */
+type Emotion = "joy" | "anger" | "sadness" | "fear" | "disgust" | "surprise" | "none";
+interface SubtitleWord {
+    text: string;
+    start: number;
+    end: number;
+    emotion?: Emotion;
+    emphasis?: number;
+}
+interface SubtitleLine {
+    speaker?: string;
+    start: number;
+    end: number;
+    words: SubtitleWord[];
+    emotion?: Emotion;
+    emotion_intensity?: number;
+}
+interface SubtitleTrack {
+    vodId: string;
+    language: string;
+    lines: SubtitleLine[];
+}
+interface EmotionStyle {
+    fontWeight?: number;
+    skew?: number;
+    jitter?: number;
+    color?: string;
+    glow?: boolean;
+    scale?: number;
+}
+interface SubtitleEngineState {
+    activeLine: SubtitleLine | null;
+    activeWords: SubtitleWord[];
+    currentWordIndex: number;
+    emotion: Emotion;
+    emotionIntensity: number;
+}
+interface PhontClientOptions {
+    apiKey?: string;
+    authToken?: string;
+    sessionId?: string;
+    apiBaseUrl?: string;
+}
+
+/**
+ * ============================================
+ * SUBTITLE STATE MANAGER
+ * ============================================
+ * Ported from app/components/subtitle/state/SubtitleStateManager.js
+ */
+interface SubtitleState$1 {
+    videoTimeSeed: number | null;
+    isVisible: boolean;
+    isKaraokeMode: boolean;
+    isSpeaker: boolean;
+    animationMode: "Sentence" | "Word";
+    currentSubtitle: string;
+    currentSequence: any | null;
+    subtitles: any[];
+    currentSubtitleData: any | null;
+    lastEndTime: number;
+    processedSequences: Set<number>;
+    initialSequenceOffset: number | null;
+    segmentDurations: Map<number, number>;
+    soundByteAll: any[];
+    soundByteImportant: any[];
+    soundByteFiltered: any[];
+    showAllSoundbites: boolean;
+    showImportantSoundbites: boolean;
+    currentTime: number;
+    liveStartTime: number | null;
+    liveCurrentTime: number;
+    soundbiteAnimations: any[];
+    showSoundbiteAnimations: boolean;
+    isClosedCaptionsEnabled: boolean;
+}
+interface VodState$1 {
+    subtitles: any[] | null;
+    soundByteAll: any[];
+    soundByteImportant: any[];
+    soundByteFiltered: any[];
+    currentLanguage: string | null;
+    videoId: string | null;
+}
+type StateCallback = (state: SubtitleState$1) => void;
+declare class SubtitleStateManager {
+    subscribers: Set<StateCallback>;
+    state: SubtitleState$1;
+    vodState: VodState$1;
+    constructor();
+    /**
+     * Subscribe to state changes
+     */
+    subscribe(callback: StateCallback): () => void;
+    /**
+     * Notify all subscribers of state changes
+     */
+    notify(): void;
+    /**
+     * Get current state (immutable copy)
+     */
+    getState(): SubtitleState$1;
+    /**
+     * Get VOD state (immutable copy)
+     */
+    getVodState(): VodState$1;
+    toggleSubtitles(isVisible: boolean): void;
+    toggleClosedCaptions(isEnabled: boolean): void;
+    toggleKaraoke(isKaraokeMode: boolean): void;
+    toggleSpeaker(isSpeaker: boolean): void;
+    toggleSoundbites(type: "all" | "important", isVisible: boolean): void;
+    toggleSoundbiteAnimations(isVisible: boolean): void;
+    setAnimationMode(mode: "Sentence" | "Word"): void;
+    updateSubtitle(text: string): void;
+    updateCurrentTime(time: number): void;
+    updateSubtitles(subtitles: any[]): void;
+    updateCurrentSubtitleData(data: any): void;
+    updateSoundbites(all?: any[], important?: any[], filtered?: any[]): void;
+    updateSoundbiteAnimations(animations: any[]): void;
+    updateVodSubtitles(subtitles: any[]): void;
+    updateVodLanguage(language: string | null): void;
+    updateVodVideoId(videoId: string | null): void;
+    updateVodSoundbites(all?: any[], important?: any[], filtered?: any[]): void;
+    updateLiveStartTime(time: number | null): void;
+    updateLiveCurrentTime(time: number): void;
+    updateVideoTimeSeed(seed: number | null): void;
+    markSequenceProcessed(sequenceNumber: number): void;
+    isSequenceProcessed(sequenceNumber: number): boolean;
+    setInitialSequenceOffset(offset: number): void;
+    setSegmentDuration(sequenceNumber: number, duration: number): void;
+    getSegmentDuration(sequenceNumber: number): number | undefined;
+    updateCurrentSequence(sequence: any): void;
+    reset(): void;
+    resetControls(): void;
+    clearLiveState(): void;
+    clearVodState(): void;
+}
+
+/**
+ * ============================================
+ * SUBTITLE MANAGER (Orchestrator)
+ * ============================================
+ *
+ * PURPOSE:
+ * Central coordinator for subtitle system. Delegates to specialized classes.
+ *
+ * USED BY:
+ * - PhontSubtitles.jsx: Gets subtitle state and data
+ * - Player components: Controls playback and timing
+ * - PhontControls.jsx: UI toggles and settings
+ *
+ * DELEGATES TO:
+ * - SubtitleStateManager: State management and subscriptions
+ * - SubtitleCache: Language caching and detection
+ * - SubtitleFetcher: API requests & data normalization
+ * - SoundbiteProcessor: Soundbite/animation processing & laughter merging
+ * - VodDataProcessor: VOD data processing, deduplication, soundbite coordination
+ * - LiveDataProcessor: LIVE data processing, timing offsets, soundbite coordination
+ * - LiveStreamCumulativeTimeGenerator: Generates cumulative time for LIVE streams
+ * - CurrentSubtitle: Gets subtitle for time (BOTH VOD & LIVE) + karaoke
+ *
+ * STATUS: Phase 2 Complete - All 8 classes extracted, clean architecture, no duplication
+ */
+type AnimationMode = "Sentence" | "Word" | string;
+interface SubtitleState {
+    isVisible: boolean;
+    isKaraokeMode: boolean;
+    isSpeaker: boolean;
+    animationMode: AnimationMode;
+    currentSubtitle: string;
+    currentSequence: number | null;
+    subtitles: any[];
+    currentSubtitleData: any | null;
+    videoTimeSeed: number | null;
+    currentTime: number;
+    liveStartTime: number | null;
+    liveCurrentTime: number;
+    lastEndTime: number;
+    processedSequences: Set<number>;
+    initialSequenceOffset: number | null;
+    segmentDurations: Map<number, number>;
+    soundByteAll: any[];
+    soundByteImportant: any[];
+    soundByteFiltered: any[];
+    showAllSoundbites: boolean;
+    showImportantSoundbites: boolean;
+    soundbiteAnimations: any[];
+    showSoundbiteAnimations: boolean;
+    isClosedCaptionsEnabled: boolean;
+    isBackgroundEffectEnabled: boolean;
+    backgroundEffect: string;
+    backgroundOpacity: number;
+    transition: boolean;
+    [key: string]: any;
+}
+interface VodState {
+    subtitles: any[] | null;
+    url: string | null;
+    currentSubtitle: string;
+    currentSubtitleData: any | null;
+    currentSequence: number | null;
+    soundByteAll: any[];
+    soundByteImportant: any[];
+    soundByteFiltered: any[];
+    currentLanguage?: string | null;
+    videoId?: string | null;
+    translation_provider?: string | null;
+    translation_model?: string | null;
+}
+type SubtitleSubscriber = (state: SubtitleState) => void;
+declare class SubtitleManager {
+    private stateManager;
+    private cache;
+    private fetcher;
+    private soundbiteProcessor;
+    private vodDataProcessor;
+    private liveTimeGenerator;
+    private liveDataProcessor;
+    private currentSubtitle;
+    constructor();
+    /**
+     * Set PhontClient for authenticated API requests
+     * This will be passed to SubtitleFetcher for use in API calls
+     */
+    setPhontClient(phontClient: any): void;
+    get state(): SubtitleState;
+    set state(value: SubtitleState);
+    get vodState(): VodState;
+    set vodState(value: VodState);
+    get subscribers(): Set<SubtitleSubscriber>;
+    subscribe(callback: SubtitleSubscriber): () => void;
+    notify(): void;
+    toggleSubtitles(isVisible: boolean): void;
+    toggleClosedCaptions(isEnabled: boolean): void;
+    toggleKaraoke(isKaraokeMode: boolean): void;
+    toggleSpeaker(isSpeaker: boolean): void;
+    toggleBackgroundEffect(isEnabled: boolean, effect?: string): void;
+    toggleSoundbites(type: "all" | "important", isVisible: boolean): void;
+    toggleSoundbiteAnimations(isVisible: boolean): void;
+    mapEventLabelToAnimation(eventLabel: string): string | null;
+    processSoundbiteAnimations(soundbites: any[]): any[];
+    setAnimationMode(mode: AnimationMode): void;
+    toggleTransition(enabled: boolean): void;
+    updateSubtitle(text: string): void;
+    updateLiveTime(videoTime?: number | null): number;
+    startLiveTiming(): void;
+    stopLiveTiming(): void;
+    pauseLiveTiming(): void;
+    resumeLiveTiming(): void;
+    resetLiveStream(videoElement: HTMLVideoElement): void;
+    getLiveTime(): number;
+    getState(): SubtitleState;
+    reset(): void;
+    resetControls(): void;
+    getCumulativeDuration(upToSequenceNumber: number): number;
+    normalizeSubtitles(data: any): any;
+    normalizeSoundbites(arr: any[]): any[];
+    getAudioSegmentDuration(sequenceNumber: number): Promise<number>;
+    getInitialLiveSequenceNumber(): Promise<number>;
+    fetchSubtitles(sequenceNumber: number): Promise<any | null>;
+    loadVodSubtitles(urlOrVodId: string, languageCode?: string | null): Promise<void>;
+    _processVodData(data: any, url: string, languageCode: string | null): void;
+    getSubtitleForTime(time: number): any;
+    getLiveSubtitleForTime(): any;
+    getCurrentSubtitleData(): any | null;
+    updateBackgroundOpacity(opacity: number): void;
+    clearOldSubtitles(currentTime: number, bufferSeconds?: number): void;
+    getQueueStatus(): {
+        totalSubtitles: number;
+        lastEndTime: number;
+        processedSequences: number[];
+        currentSequence: number | null;
+    };
+    setCurrentTime(time: number): void;
+    getActiveSoundbites(isVodMode?: boolean, vodTime?: number | null): any[];
+    getAllSoundbiteData(isVodMode?: boolean): any;
+    getActiveSoundbiteAnimations(isVodMode?: boolean): any[];
+    hasActiveAnimations(): boolean;
+    clearSoundbiteAnimations(): void;
+    clearOldAnimations(currentTime: number, bufferSeconds?: number): void;
+    getCurrentSpeaker(isVodMode?: boolean, vodTime?: number | null): string | null;
+    fetchSubtitleData(url: string, languageCode?: string | null, model?: string | null): Promise<void>;
+    switchSubtitleLanguage(languageCode: string | null, videoId: string, model?: string | null): Promise<void>;
+    _loadCachedSubtitles(data: any, url: string, languageCode: string | null): void;
+    getCurrentSubtitleLanguage(): string | null;
+    clearSubtitleCache(): void;
+    clearAudioPlaylistCache(): void;
+    updateState(): void;
+}
+declare const subtitleManager: SubtitleManager;
+
+/**
+ * Animation Types
+ *
+ * Type definitions for animation parameter states, curves, and animation state
+ */
+interface CurvePoint {
+    time: number;
+    value: number | string;
+}
+interface ParameterState {
+    points: CurvePoint[];
+    currentValue?: number | string;
+}
+interface ParameterStates {
+    [key: string]: ParameterState;
+}
+interface AnimationParameterStates {
+    parameterStates: ParameterStates;
+    duration?: number;
+    format?: 'normalized' | 'absolute';
+}
+interface AnimationState {
+    fontSize: number;
+    scale: number;
+    opacity: number;
+    slant: number;
+    weight: number;
+    width: number;
+    textColor: string;
+    translateX: number;
+    translateY: number;
+    stretchY: number;
+    rotation?: number;
+    skewX?: number;
+    fontVariationAxes?: Record<string, number>;
+    letterShake?: number;
+    letterSpacingOffsets?: number[];
+    shadowColor?: string;
+}
+interface SentenceAnimationState extends AnimationState {
+    text: string;
+    emotion: string;
+    emotionIntensity: number;
+    fontFamily: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    isActive: boolean;
+}
+interface WordAnimationState {
+    text: string;
+    words: Array<{
+        word: string;
+        start: number;
+        end: number;
+        animationEnd: number;
+        isActive: boolean;
+        emotion: string;
+        emotionIntensity: number;
+        originalEmotionIntensity?: number;
+        fontFamily: string;
+        emphasis: number;
+        emphasisEffect?: any;
+        strongEmphasis?: any;
+        animationParameters: AnimationState;
+        joyAnimationMode?: 'letter' | 'letter-bulge' | 'word' | null;
+        joyProgress?: number | null;
+    }>;
+    currentWordIndex: number;
+    emotion: string;
+    emotionIntensity: number;
+    fontFamily: string;
+    startTime: number;
+    endTime: number;
+    isActive: boolean;
+}
+interface SubtitleSegment {
+    start_time: number;
+    end_time: number;
+    text?: string;
+    subtitle?: string;
+    words?: Array<{
+        word: string;
+        start: number;
+        end: number;
+        emphasis?: number;
+    }>;
+    animations?: Record<string, number>;
+    volume?: number;
+    speech_rate?: number;
+    merged_subtitles?: SubtitleSegment[];
+}
+interface AnimationOptions {
+    maxExpression?: number;
+    threshold?: number;
+    isRTL?: boolean;
+    volume?: number;
+    speechRate?: number;
+    nextSegmentStartTime?: number;
+    extendedEndTime?: number;
+}
+
+/**
+ * Emotion Selector
+ *
+ * Pure function version of useEmotionSelector (no React)
+ * Selects the highest-value emotion from backend animations object
+ * Core emotions (anger, fear, sadness, joy) receive ×1.5 importance multiplier
+ */
+interface EmotionSelectionResult {
+    emotion: string;
+    intensity: number;
+    allEmotions: Array<[string, number, number, number, boolean]>;
+    importanceFactor: number;
+    isCore: boolean;
+}
+/**
+ * Find the highest emotion value from animations object
+ *
+ * Core emotions (anger, fear, sadness, joy, disgust) are multiplied by 1.5 before selection
+ * to prioritize fundamental emotions over secondary ones.
+ *
+ * @param animationsObject - Object with emotion keys and values (0-1)
+ * @param threshold - Minimum value to consider (GTS-controlled: 0.7 at GTS=0, 0.2 at GTS=1)
+ * @returns Emotion selection result
+ */
+declare function selectEmotion(animationsObject: Record<string, number> | null | undefined, threshold?: number): EmotionSelectionResult;
+
+/**
+ * Animation Engine
+ *
+ * Pure functions that calculate animation state from emotion curves
+ * Uses function-based EMOTION_ANIMATIONS (identical to monorepo)
+ */
+
+/**
+ * Calculate sentence animation state
+ *
+ * Pure function version of useSentenceAnimation - uses function-based EMOTION_ANIMATIONS (identical to monorepo)
+ */
+declare function calculateSentenceAnimation(segment: SubtitleSegment | null, currentTime: number, options?: AnimationOptions): SentenceAnimationState;
+/**
+ * Calculate word animation state
+ *
+ * Pure function version of useWordAnimation - uses function-based EMOTION_ANIMATIONS (identical to monorepo)
+ */
+declare function calculateWordAnimation(segment: SubtitleSegment | null, currentTime: number, options?: AnimationOptions): WordAnimationState;
+/**
+ * Main function: Calculate animation state from segment and emotion
+ *
+ * This is the main entry point that uses function-based EMOTION_ANIMATIONS (identical to monorepo)
+ */
+declare function calculateAnimationState(segment: SubtitleSegment | null, currentTime: number, mode: 'sentence' | 'word', options?: AnimationOptions): SentenceAnimationState | WordAnimationState;
+
+/**
+ * Timing Utilities
+ *
+ * Pure functions for calculating subtitle timing
+ */
+
+/**
+ * Get subtitle timing information
+ */
+declare function getSubtitleTiming(subtitle: SubtitleSegment | null): {
+    startTime: number;
+    endTime: number;
+    duration: number;
+};
+/**
+ * Get subtitle text content
+ */
+declare function getSubtitleText(subtitle: SubtitleSegment | null): string;
+/**
+ * Calculate normalized time (t: 0→1) through subtitle duration
+ */
+declare function calculateNormalizedTime(currentTime: number, startTime: number, duration: number): number;
+
+/**
+ * **EMOTION_CURVES_DEFINITION** - Animation DNA
+ *
+ * Emotion Curves - Animation Parameter Definitions
+ *
+ * These curves define how subtitle text animates over time based on emotion.
+ * Each emotion has time-based functions that return values for visual parameters.
+ *
+ * PARAMETERS:
+ * - fontSize: Always constant (ANIMATION_STYLING.fontSize) for layout stability
+ * - scale: Size multiplier applied via CSS transform (prevents text wrapping)
+ * - slant: Italic/skew effect in degrees (applied as CSS skewX)
+ * - weight: Font weight (100-900) - overridden by VariableFontContext in practice
+ * - translateX/Y: Movement in pixels (direct CSS values)
+ * - textColor: Text color (rgba)
+ * - stretchY: Vertical stretch multiplier (CSS scaleY)
+ * - letterShakeIntensity: Per-letter shake amount in pixels (fear)
+ *
+ * WHY SCALE INSTEAD OF FONTSIZE:
+ * Using transform: scale() instead of fontSize changes allows the layout engine
+ * to calculate word positions ONCE at the base fontSize, preventing words from
+ * wrapping to new lines mid-animation. Scale is GPU-accelerated and doesn't trigger reflow.
+ *
+ * ⚠️ Parameters NOT included (handled elsewhere):
+ * - opacity: Always 1.0 (fade in/out handled by controllers)
+ * - shadows: Handled by styling.js ANIMATION_STYLING.shadow (emotion-specific for disgust/angry)
+ * - font family: Handled by fontSelection.js based on emotion + intensity
+ * - transitions: Handled by styling.js ANIMATION_STYLING.transition
+ * - marginRight: Handled by calculateDynamicWordSpacing() based on current scale
+ */
+declare const EMOTION_ANIMATIONS: Record<string, any>;
+
+/**
+ * Animation Defaults - Visual Styling Layer
+ *
+ * All subtitle animation VISUAL defaults in one place
+ * This is where you edit colors, shadows, font names, and CSS values
+ *
+ * 🎯 HOW TO CONFIGURE:
+ * - Change default font size: Edit ANIMATION_STYLING.fontSize
+ * - Change default colors/shadows: Edit ANIMATION_STYLING.textColor, shadow, etc.
+ *
+ * 🔧 FOR BEHAVIOR/TIMING:
+ * - Change when Rakkas (angry) font appears: Edit RENDERING_CONTROL.emotion.angryFontThreshold
+ * - Change effect timing/intensity: Edit renderingControl.ts
+ */
+declare const ANIMATION_STYLING: {
+    fontSize: number;
+    opacity: number;
+    weight: number;
+    slant: number;
+    textColor: string;
+    translateX: number;
+    translateY: number;
+    defaultFont: string;
+    angryFont: string;
+    joyFont: string;
+    sadnessFont: string;
+    shadow: {
+        offsetX: number;
+        offsetY: number;
+        blur: number;
+        color: string;
+    };
+    angryFontStyle: {
+        color: string;
+        strokeColor: string;
+        strokeWidth: number;
+        shadowOffsetX: number;
+        shadowOffsetY: number;
+        shadowBlur: number;
+        shadowBlurMin: number;
+        shadowBlurMax: number;
+        shadowOpacityMin: number;
+        shadowOpacityMax: number;
+        shadowColor: string;
+    };
+    disgustEmotion: {
+        shadowOffsetX: number;
+        shadowOffsetY: number;
+        shadowBlur: number;
+        shadowColor: string;
+    };
+    transition: {
+        duration: number;
+        easing: string;
+    };
+    lineHeight: number;
+    letterSpacing: string;
+    wordSpacing: {
+        min: string;
+        max: string;
+    };
+    fontSpacingAdjustments: {
+        'Roboto Flex': {
+            letterSpacing: string;
+            wordSpacingMultiplier: number;
+        };
+        Parkinsans: {
+            letterSpacing: string;
+            wordSpacingMultiplier: number;
+            fontSizeOffset: number;
+        };
+        Rakkas: {
+            letterSpacing: string;
+            wordSpacingMultiplier: number;
+        };
+        Cormorant: {
+            letterSpacing: string;
+            wordSpacingMultiplier: number;
+        };
+    };
+    position: {
+        bottom: string;
+        horizontalAlign: string;
+    };
+    wordAnimation: {
+        minDisplayTime: number;
+        allowOverlap: boolean;
+    };
+};
+
+/**
+ * Rendering Configuration
+ *
+ * Central configuration for animation system timing, thresholds, and behavior
+ * This is the single source of truth for non-visual animation parameters
+ */
+declare const RENDERING_CONTROL: {
+    modes: {
+        word: string;
+        sentence: string;
+    };
+    timing: {
+        minWordDisplayTime: number;
+        breathingRoomDuration: number;
+        breathingRoomMinGap: number;
+        breathingRoomLargeGap: number;
+        timeRangeTolerance: number;
+    };
+    emotion: {
+        defaultThreshold: number;
+        maxThreshold: number;
+        angryFontThreshold: number;
+        angryEmotions: string[];
+        joyFontThreshold: number;
+        joyEmotions: string[];
+        sadnessFontThreshold: number;
+        sadnessEmotions: string[];
+    };
+    emphasis: {
+        minThreshold: number;
+        maxThreshold: number;
+        scaleMultiplier: number;
+        scaleUpFrames: number;
+        scaleDownFrames: number;
+        fps: number;
+    };
+    strongEmphasis: {
+        minThreshold: number;
+        maxScale: number;
+        maxRotation: number;
+        maxTranslateY: number;
+        maxTranslateX: number;
+        maxSkew: number;
+        maxBrightness: number;
+        maxContrast: number;
+        maxShadowBlur: number;
+        shadowOpacity: number;
+        shadowOffsetX: number;
+        shadowOffsetY: number;
+        maxZIndex: number;
+        outwardPushTranslateX: number;
+        outwardPushRotation: number;
+        outwardPushSkew: number;
+        fadeOutTailDuration: number;
+    };
+    fear: {};
+    joy: {
+        maxWordsForLetterAnimation: number;
+        minWordsForWordAnimation: number;
+        letterWave: {
+            innerWidthRatio: number;
+            outerWidthRatio: number;
+            maxScale: number;
+            maxRotation: number;
+            maxTranslateY: number;
+            maxTranslateX: number;
+            maxSkew: number;
+            maxBrightness: number;
+            maxContrast: number;
+            maxShadowBlur: number;
+            shadowOpacity: number;
+            maxZIndex: number;
+        };
+        letterBulge: {
+            innerWidthRatio: number;
+            outerWidthRatio: number;
+            maxScale: number;
+            maxStretchY: number;
+            maxCompressionX: number;
+            maxTranslateY: number;
+            maxTranslateX: number;
+            maxSkew: number;
+            maxRotation: number;
+            maxBrightness: number;
+            maxContrast: number;
+            maxShadowBlur: number;
+            shadowOpacity: number;
+            maxZIndex: number;
+        };
+        wordLevel: {
+            duration: number;
+            easeType: string;
+            maxScale: number;
+            maxRotation: number;
+            maxTranslateY: number;
+            maxTranslateX: number;
+            maxSkew: number;
+            maxBrightness: number;
+            maxContrast: number;
+            maxShadowBlur: number;
+            shadowOpacity: number;
+            maxZIndex: number;
+            transitionDuration: number;
+        };
+    };
+    debug: {
+        showBorders: boolean;
+        showTimings: boolean;
+        logRendering: boolean;
+    };
+};
+
+/**
+ * Shared Animation Parameter Calculation Utility
+ *
+ * Calculates animation parameters from emotion curves.
+ * Shared by calculateWordAnimation and calculateSentenceAnimation to eliminate duplication.
+ *
+ * This utility extracts all animation parameters defined in EMOTION_ANIMATIONS
+ * including variation axes (YOPQ, YTAS) that are separate from voice axes (wght, wdth).
+ *
+ * TERMINOLOGY:
+ * - **Voice Axes**: Font axes driven by audio analysis (volume→wght, speech_rate→wdth)
+ * - **Variation Axes**: Font axes driven by emotion animations (YOPQ, YTAS from emotion curves)
+ */
+interface VariableFontStyle {
+    fontWeight?: number;
+    fontStretch?: string;
+}
+interface AnimationParameters {
+    fontSize: number;
+    scale: number;
+    opacity: number;
+    slant: number;
+    weight: number;
+    width: number;
+    textColor: string;
+    translateX: number;
+    translateY: number;
+    stretchY: number;
+    letterShake?: number;
+    fontVariationAxes?: Record<string, number>;
+    shadowColor?: string | ((t: number, intensity: number) => string);
+}
+interface EmotionCurve {
+    fontSize?: number | ((t: number, intensity: number) => number);
+    scale?: number | ((t: number, intensity: number) => number);
+    opacity?: number | ((t: number, intensity: number) => number);
+    slant?: number | ((t: number, intensity?: number) => number);
+    weight?: number | ((t: number, intensity?: number) => number);
+    translateX?: number | ((t: number, intensity: number) => number);
+    translateY?: number | ((t: number, intensity: number) => number);
+    stretchY?: number | ((t: number, intensity: number) => number);
+    textColor?: string | ((t: number, intensity: number) => string);
+    shadowColor?: string | ((t: number, intensity: number) => string);
+    thinStroke?: (t: number, intensity: number, gtsValue: number) => number;
+    ascenderHeight?: (t: number, intensity: number, gtsValue: number) => number;
+    letterShake?: (t: number, intensity: number, gtsValue: number) => number;
+}
+/**
+ * Calculate animation parameters from emotion curve
+ *
+ * @param emotionCurve - Emotion curve from EMOTION_ANIMATIONS
+ * @param t - Normalized time (0-1) through animation
+ * @param intensity - Emotion intensity (0-1), capped by GTS (maxExpression)
+ * @param variableFontStyle - Font style from variable font calculations
+ * @param gtsValue - GTS maxExpression value (0.2-1.0) for scaling ranges
+ * @param selectedFontFamily - The selected font family (e.g., 'Cormorant', 'Roboto Flex')
+ * @returns Complete animation parameters including fontVariationAxes (variation axes, not voice axes)
+ */
+declare function calculateAnimationParameters(emotionCurve: EmotionCurve, t: number, intensity: number, variableFontStyle?: VariableFontStyle | null, gtsValue?: number, selectedFontFamily?: string): AnimationParameters;
+
+/**
+ * Shadow Generator
+ *
+ * Generates CSS text-shadow strings from shadow colors and emotion-specific styling
+ */
+/**
+ * Generate CSS text-shadow string from shadow color
+ *
+ * @param shadowColor - Shadow color in hex format (e.g., '#ff3232')
+ * @param fontFamily - Font family to determine shadow style
+ * @param emotion - Current emotion to determine shadow style
+ * @param intensity - Emotion intensity (0-1) to scale glow effects
+ * @returns CSS text-shadow value
+ */
+declare function generateTextShadow(shadowColor: string | undefined, fontFamily?: string, emotion?: string, intensity?: number): string;
+
+/**
+ * Dynamic Word Spacing Calculator
+ *
+ * Calculates word spacing that grows with animation scale and GTS intensity
+ * Ported from app/config/animation/styling.js
+ */
+/**
+ * Calculate dynamic word spacing that grows with scale
+ *
+ * @param currentScale - Current scale value from animation (e.g., 1.0 to 1.5)
+ * @param fontFamily - Font family name for spacing adjustments
+ * @param gtsIntensity - GTS intensity (0-1) - currently unused for layout preservation
+ * @param emotion - Current emotion type (for anger-specific spacing)
+ * @returns CSS em value for marginRight
+ */
+declare function calculateDynamicWordSpacing(currentScale?: number, fontFamily?: string, gtsIntensity?: number, emotion?: string): string;
+
+/**
+ * Joy Animation Effects
+ *
+ * Per-letter joy pressure effects for wave and bulge animations
+ * Ported from app/utils/animation/joy.js
+ */
+/**
+ * Determine which joy animation mode to use based on word count
+ */
+declare function getJoyAnimationMode(wordCount: number): 'letter' | 'letter-bulge' | 'word';
+interface JoyEffect {
+    pressure: number;
+    scale: number;
+    rotation: number;
+    translateX: number;
+    translateY: number;
+    skewX: number;
+    stretchY: number;
+    stretchX?: number;
+    brightness: number;
+    contrast: number;
+    shadowBlur: number;
+    shadowOpacity: number;
+    zIndex: number;
+    shadowOffsetX?: number;
+    shadowOffsetY?: number;
+    bulgeIntensity?: number;
+}
+/**
+ * Calculate per-letter joy pressure based on word progress and letter position
+ */
+declare function calculateJoy(progress: number, letterIndex: number, totalLetters: number, gtsMultiplier?: number): JoyEffect | null;
+/**
+ * Calculate joy bulge effect (for multi-word subtitles)
+ */
+declare function calculateJoyBulge(progress: number, letterIndex: number, totalLetters: number, gtsMultiplier?: number): JoyEffect | null;
+/**
+ * Generate CSS transform string from joy effect
+ */
+declare function getJoyTransform(joyEffect: JoyEffect | null): string;
+/**
+ * Generate CSS filter string from joy effect
+ */
+declare function getJoyFilter(joyEffect: JoyEffect | null): string;
+
+/**
+ * GTS (Global Text Style) Calculations
+ *
+ * Centralized logic for GTS-derived values and emotion threshold calculations
+ */
+/**
+ * Calculate all GTS-derived values from slider position
+ *
+ * GTS slider range: 0 to 1
+ * - GTS = 0 → maxExpression = 0.2, threshold = 0.7 (conservative)
+ * - GTS = 1 → maxExpression = 1.0, threshold = 0.2 (expressive)
+ *
+ * @param gts - GTS slider value (0-1)
+ * @returns All derived GTS values
+ */
+declare function calculateGTSValues(gts: number): {
+    gts: number;
+    maxExpression: number;
+    threshold: number;
+    shouldEnableAngryFont: boolean;
+};
+/**
+ * Check if emotion intensity meets the threshold
+ *
+ * @param intensity - Raw emotion intensity from backend (0-1)
+ * @param threshold - GTS-calculated threshold (0-1)
+ * @returns True if intensity is above threshold
+ */
+declare function meetsEmotionThreshold(intensity: number, threshold: number): boolean;
+/**
+ * Calculate capped emotion intensity based on GTS maxExpression
+ *
+ * @param rawIntensity - Raw emotion intensity from backend (0-1)
+ * @param maxExpression - GTS-derived max expression cap (0-1)
+ * @returns Capped emotion intensity (0-1)
+ */
+declare function capEmotionIntensity(rawIntensity: number, maxExpression: number): number;
+/**
+ * Calculate emphasis multiplier within valid emphasis range
+ *
+ * Maps emphasis value within [minThreshold, maxThreshold] to [0, 1]
+ * Used for scaling emphasis effects based on position in range
+ *
+ * @param emphasis - Word emphasis value (0-1)
+ * @returns Emphasis multiplier (0-1), or 0 if outside range
+ */
+declare function calculateEmphasisMultiplier(emphasis: number): number;
+/**
+ * Check if emphasis value is in valid range for emphasis animation
+ *
+ * @param emphasis - Word emphasis value (0-1)
+ * @returns True if in emphasis range [0.5, 0.7)
+ */
+declare function isInEmphasisRange(emphasis: number): boolean;
+/**
+ * Check if emphasis value is in valid range for strong emphasis animation
+ *
+ * @param emphasis - Word emphasis value (0-1)
+ * @returns True if in strong emphasis range [0.7, 1.0]
+ */
+declare function isInStrongEmphasisRange(emphasis: number): boolean;
+
+/**
+ * Emotion Animation URLs
+ *
+ * Config mapping emotion → animation URL
+ * Replaces hardcoded EMOTION_ANIMATIONS config with URL-based parameters
+ */
+declare const EMOTION_ANIMATION_URLS: Record<string, string>;
+
+/**
+ * Font Selection Utilities
+ *
+ * Centralized logic for selecting fonts based on emotion and intensity
+ * Eliminates duplicate font selection code across controllers
+ */
+interface Stylesheet {
+    name?: string;
+    fonts?: Record<string, string>;
+}
+/**
+ * Select font family based on emotion and GTS intensity
+ *
+ * @param emotion - Emotion name (lowercase, e.g., 'anger', 'joy', 'sadness')
+ * @param maxExpression - GTS-derived max expression (0-1)
+ * @param emotionCategory - Emotion category for children stylesheet (shout, whisper, anger, fear, neutral)
+ * @param stylesheet - Active stylesheet config (optional)
+ * @returns Font family name
+ */
+declare function selectFontFamily(emotion: string, maxExpression: number, emotionCategory?: string | null, stylesheet?: Stylesheet | null): string;
+/**
+ * Get CSS-ready font-family value
+ *
+ * @param emotion - Emotion name (lowercase)
+ * @param maxExpression - GTS-derived max expression (0-1)
+ * @param emotionCategory - Emotion category for children stylesheet
+ * @param stylesheet - Active stylesheet config (optional)
+ * @returns CSS font-family value
+ */
+declare function getFontFamilyCSS(emotion: string, maxExpression: number, emotionCategory?: string | null, stylesheet?: Stylesheet | null): string;
+/**
+ * Check if a given emotion and intensity should use Rakkas (angry) font
+ *
+ * @param emotion - Emotion name (lowercase)
+ * @param maxExpression - GTS-derived max expression (0-1)
+ * @returns True if Rakkas font should be used
+ */
+declare function shouldUseAngryFont(emotion: string, maxExpression: number): boolean;
+/**
+ * Check if a given emotion and intensity should use Parkinsans (joy) font
+ *
+ * @param emotion - Emotion name (lowercase)
+ * @param maxExpression - GTS-derived max expression (0-1)
+ * @returns True if Parkinsans font should be used
+ */
+declare function shouldUseJoyFont(emotion: string, maxExpression: number): boolean;
+/**
+ * Check if a given emotion and intensity should use Cormorant (sadness) font
+ *
+ * @param emotion - Emotion name (lowercase)
+ * @param maxExpression - GTS-derived max expression (0-1)
+ * @returns True if Cormorant font should be used
+ */
+declare function shouldUseSadnessFont(emotion: string, maxExpression: number): boolean;
+
+/**
+ * Letter Splitting Utilities
+ *
+ * Reusable utilities for splitting text into individual letters for per-letter animations
+ */
+interface Letter {
+    char: string;
+    isSpace: boolean;
+    index: number;
+}
+/**
+ * Split text into individual letters for per-letter animation
+ *
+ * Preserves spaces as non-breaking spaces to maintain layout.
+ * Each letter gets metadata for animation calculations.
+ */
+declare function splitTextIntoLetters(text: string): Letter[];
+
+/**
+ * Word Emphasis Effects
+ *
+ * Calculates emphasis effects (standard and strong) for words based on confidence levels.
+ *
+ * USED BY:
+ * - calculateWordAnimation: Main word animation orchestrator
+ *
+ * HOW IT WORKS:
+ * 1. Standard Emphasis (50-70%): Quick "pop" effect at word start
+ * 2. Strong Emphasis (70%+): Per-letter dramatic effects throughout word
+ * 3. Both scale with GTS (expressiveness level) and word confidence
+ *
+ * KEY FEATURES:
+ * - Confidence-based thresholds (50-70% vs 70%+)
+ * - GTS-scaled intensity
+ * - Emotion slant inheritance
+ * - Smooth transitions
+ */
+interface Word {
+    emphasis?: number;
+    start: number;
+    end: number;
+    animationEnd?: number;
+}
+interface EmphasisEffect {
+    scaleMultiplier: number;
+    slantAdditive: number;
+    weightBoost: number;
+    scaleProgress: number;
+    gtsMultiplier: number;
+    emphasis: number;
+    emphasisMultiplier: number;
+    elapsed: number;
+    scaleActive: boolean;
+}
+interface StrongEmphasisData {
+    emphasis: number;
+    rawEmphasis: number;
+    scale: number;
+    rotation: number;
+    translateX: number;
+    translateY: number;
+    skewX: number;
+    stretchY: number;
+    brightness: number;
+    contrast: number;
+    shadowBlur: number;
+    shadowOpacity: number;
+    zIndex: number;
+    weightBoost: number;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    gtsMultiplier: number;
+    emphasisMultiplier: number;
+    fadeFactor: number;
+    isInTail: boolean;
+}
+/**
+ * Calculate emphasis effects for a word
+ *
+ * @param params - Emphasis calculation parameters
+ * @returns Emphasis effects { emphasisEffect, strongEmphasisData }
+ */
+declare function calculateWordEmphasisEffects({ word, currentTime, maxExpression, emotionAnimationDuration, wordBaseSlant, isActive, wordEmotion, }: {
+    word: Word;
+    currentTime: number;
+    maxExpression: number;
+    emotionAnimationDuration: number;
+    wordBaseSlant: number;
+    isActive: boolean;
+    wordEmotion?: string;
+}): {
+    emphasisEffect: EmphasisEffect | null;
+    strongEmphasisData: StrongEmphasisData | null;
+};
+
+/**
+ * ============================================
+ * WORD LETTER SPACING
+ * ============================================
+ *
+ * PURPOSE:
+ * Calculates per-letter translateX offsets for GPU-accelerated spacing (no layout reflow).
+ * Extracted from animationEngine for better maintainability.
+ *
+ * USED BY:
+ * - animationEngine: Main word animation orchestrator
+ *
+ * HOW IT WORKS:
+ * 1. Detects active effects (fear shake only - emphasis spacing is disabled)
+ * 2. Calculates per-letter translateX offsets to create spacing between letters
+ * 3. Returns array of translateX values in pixels (one per letter)
+ *
+ * KEY FEATURES:
+ * - Transform-based spacing (GPU-accelerated, no layout reflow)
+ * - Letter spacing disabled for emphasis effects (standard and strong)
+ * - Only fear shake effects get letter spacing (if needed)
+ * - Zero baseline for clean transitions
+ *
+ * PERFORMANCE BENEFITS:
+ * - Uses translateX (compositor property) instead of letter-spacing (layout property)
+ * - Smooth CSS transitions without triggering layout reflow
+ * - All spacing animations run on GPU compositor layer
+ */
+interface WordLetterSpacingParams {
+    strongEmphasisData?: any;
+    emphasisEffect?: any;
+    wordLetterShakeIntensity: number | null;
+    wordFontFamily: string;
+    currentTime: number;
+    word: any;
+    emotionAnimationDuration: number;
+    wordEmotion?: string;
+    totalLetters: number;
+    fontSize: number;
+}
+/**
+ * Calculate per-letter translateX offsets for GPU-accelerated spacing
+ *
+ * @param params - Spacing calculation parameters
+ * @returns Array of translateX offsets in pixels (one per letter)
+ */
+declare function calculateWordLetterSpacing({ strongEmphasisData, emphasisEffect, wordLetterShakeIntensity, wordFontFamily, currentTime, word, emotionAnimationDuration, wordEmotion, totalLetters, fontSize, }: WordLetterSpacingParams): number[];
+
+/**
+ * Backend Data Accessors
+ *
+ * Type-safe helpers for accessing backend subtitle data
+ * Provides consistent interface and handles edge cases
+ * Identical to monorepo app/utils/data/backendDataAccessors.js
+ */
+
+/**
+ * Get subtitle words array
+ */
+declare function getSubtitleWords(subtitle: SubtitleSegment | null): any[];
+/**
+ * Get subtitle animations/emotions
+ */
+declare function getSubtitleAnimations(subtitle: SubtitleSegment | null): Record<string, number>;
+/**
+ * Check if subtitle has merged subtitles
+ */
+declare function hasMergedSubtitles(subtitle: SubtitleSegment | null): boolean;
+/**
+ * Get merged subtitles array
+ */
+declare function getMergedSubtitles(subtitle: SubtitleSegment | null): SubtitleSegment[];
+/**
+ * Find subtitle containing a specific word based on timing
+ *
+ * Used for merged_subtitles to find which subtitle a word belongs to
+ */
+declare function findSubtitleForWord(subtitles: SubtitleSegment[], word: any): SubtitleSegment | null;
+
+/**
+ * Emotion Importance Processing
+ *
+ * Core emotions (anger, fear, sadness, joy) are prioritized over secondary emotions
+ * by multiplying their intensity by 1.5 before selection.
+ * Identical to monorepo app/utils/data/emotionImportance.js
+ */
+/**
+ * Process emotions with importance factors
+ *
+ * Core emotions (anger, fear, sadness, joy) get ×1.5 multiplier
+ * Secondary emotions get ×1.0 multiplier
+ *
+ * @param emotions - Array of [emotion, intensity] tuples
+ * @returns Array of [emotion, originalIntensity, adjustedIntensity, importanceFactor, isCore] tuples
+ */
+declare function processEmotionsWithImportance(emotions: Array<[string, number]>): Array<[string, number, number, number, boolean]>;
+
+/**
+ * Variable Font Calculations
+ *
+ * Pure functions for calculating font weight/width from volume/speechRate
+ * Extracted from app/utils/font/variableFontCalculations.js
+ */
+interface FontAxisConfig {
+    min: number;
+    max: number;
+    default: number;
+}
+interface FontConfig {
+    axes?: {
+        weight?: FontAxisConfig;
+        width?: FontAxisConfig;
+    };
+    mapping?: {
+        volume?: {
+            min: number;
+            max: number;
+        };
+    };
+}
+/**
+ * Calculate font weight from volume
+ * Maps volume (0-1) to weight range
+ *
+ * @param volume - Volume value (0-1)
+ * @param weightAxis - Weight axis config from font
+ * @param fontConfig - Font configuration object (optional)
+ * @param baseWeight - Optional base weight from URL (if provided, volume variation is applied on top)
+ * @returns Calculated font weight
+ */
+declare function calculateWeightFromVolume(volume: number | undefined, weightAxis: FontAxisConfig | undefined, fontConfig?: FontConfig | null, baseWeight?: number): number;
+/**
+ * Calculate font width from speech rate
+ * Uses inverse relationship: slower speech = wider font
+ * Maps speech rate (0-1) to width range
+ *
+ * @param speechRate - Speech rate value (0-1)
+ * @param widthAxis - Width axis config from font
+ * @param baseWidth - Optional base width from URL (if provided, speechRate variation is applied on top)
+ * @returns Calculated font width
+ */
+declare function calculateWidthFromSpeechRate(speechRate: number | undefined, widthAxis: FontAxisConfig | undefined, baseWidth?: number): number;
+
+/**
+ * Subtitle Engine
+ *
+ * TODO: Extract from app/hooks/subtitle/useSentenceAnimation.js and useWordAnimation.js
+ *
+ * This module should provide:
+ * - createSubtitleEngine(track) - creates engine instance
+ * - engine.at(time) - returns SubtitleEngineState for given time
+ * - Handle karaoke mode (word-by-word) and sentence mode
+ * - Handle edge cases: gaps, overlaps, end-of-video
+ */
+
+declare function createSubtitleEngine(track: SubtitleTrack): {
+    at(time: number): SubtitleEngineState;
+};
+
+/**
+ * Emotion → Style Mapper
+ *
+ * TODO: Extract from app/config/animation/ directory
+ *
+ * This module should provide:
+ * - getEmotionStyle(emotion, intensity) - maps emotion to CSS styles
+ * - Handle all 6 emotions: joy, anger, sadness, fear, disgust, surprise
+ * - Support intensity scaling (0-1)
+ */
+
+declare function getEmotionStyle(emotion: Emotion, intensity: number): EmotionStyle;
+
+/**
+ * PHONT API Client
+ *
+ * Supports both authentication methods:
+ * - API Keys: For server-side/programmatic access (POST/DELETE /vods, GET /vods/status)
+ * - Session Tokens: For frontend/user access (GET /vods, GET /vods/{id}, GET /vod-subtitles/{id})
+ *
+ * Tenant isolation is handled automatically by the backend based on credentials.
+ */
+
+interface LoginResponse {
+    tenant_id: string;
+    username: string;
+    email: string;
+    session_id: string;
+    auth_token: string;
+}
+interface RegisterResponse {
+    tenant_id: string;
+    username: string;
+    email: string;
+}
+interface VodMetadata {
+    _id: string;
+    tenant_id: string;
+    manifest: string;
+    thumbnail?: string;
+    audio_url?: string;
+    name: string;
+    subtitle_available: boolean;
+    created_at: string;
+}
+declare class PhontClient {
+    private apiKey?;
+    private authToken?;
+    private sessionId?;
+    readonly apiBaseUrl: string;
+    constructor(options: PhontClientOptions);
+    /**
+     * Get authentication headers based on configured auth method
+     */
+    getAuthHeaders(): Record<string, string>;
+    /**
+     * Make an authenticated request
+     */
+    private request;
+    /**
+     * Login with credentials (for frontend/user access)
+     * Returns session_id and auth_token for subsequent requests
+     */
+    login(identifier: string, password: string): Promise<LoginResponse>;
+    /**
+     * Register a new user
+     */
+    register(username: string, email: string, password: string): Promise<RegisterResponse>;
+    /**
+     * Get subtitle track for a VOD
+     * Requires: Session token authentication
+     * @param vodId - VOD ID
+     * @param lang - Language code (optional). If not provided, returns original language subtitles.
+     *               Use null/undefined for original, or a valid language code for translations.
+     * @param model - Model name for LLM translation (optional)
+     */
+    getSubtitleTrack(vodId: string, lang?: string | null, model?: string | null): Promise<any>;
+    /**
+     * Get VOD metadata
+     * Requires: Session token authentication
+     */
+    getVod(vodId: string): Promise<VodMetadata>;
+    /**
+     * List user's VODs (tenant-isolated)
+     * Requires: Session token authentication
+     */
+    listVods(skip?: number, limit?: number): Promise<VodMetadata[]>;
+    /**
+     * Create a new VOD
+     * Requires: API key authentication
+     */
+    createVod(data: {
+        manifest: string;
+        thumbnail?: string;
+        name: string;
+    }): Promise<VodMetadata>;
+    /**
+     * Delete a VOD
+     * Requires: API key authentication
+     */
+    deleteVod(vodId: string): Promise<void>;
+    /**
+     * Get VOD processing status
+     * Requires: API key authentication
+     */
+    getVodStatus(vodId: string): Promise<{
+        vod_id: string;
+        status: string;
+    }>;
+    /**
+     * Update credentials (useful after login)
+     */
+    setCredentials(options: {
+        apiKey?: string;
+        authToken?: string;
+        sessionId?: string;
+    }): void;
+    /**
+     * Clear credentials (for logout)
+     */
+    clearCredentials(): void;
+}
+
+export { ANIMATION_STYLING, type AnimationOptions, type AnimationParameterStates, type AnimationParameters, type AnimationState, type CurvePoint, EMOTION_ANIMATIONS, EMOTION_ANIMATION_URLS, type Emotion, type EmotionCurve, type EmotionSelectionResult, type EmotionStyle, type EmphasisEffect, type FontAxisConfig, type FontConfig, type JoyEffect, type Letter, type LoginResponse, type ParameterState, type ParameterStates, PhontClient, type PhontClientOptions, 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 VariableFontStyle, type VodMetadata, type VodState$1 as VodState, type Word, type WordAnimationState, type WordLetterSpacingParams, calculateAnimationParameters, calculateAnimationState, calculateDynamicWordSpacing, calculateEmphasisMultiplier, calculateGTSValues, calculateJoy, calculateJoyBulge, calculateNormalizedTime, calculateSentenceAnimation, calculateWeightFromVolume, calculateWidthFromSpeechRate, calculateWordAnimation, calculateWordEmphasisEffects, calculateWordLetterSpacing, capEmotionIntensity, createSubtitleEngine, findSubtitleForWord, generateTextShadow, getEmotionStyle, getFontFamilyCSS, getJoyAnimationMode, getJoyFilter, getJoyTransform, getMergedSubtitles, getSubtitleAnimations, getSubtitleText, getSubtitleTiming, getSubtitleWords, hasMergedSubtitles, isInEmphasisRange, isInStrongEmphasisRange, meetsEmotionThreshold, processEmotionsWithImportance, selectEmotion, selectFontFamily, shouldUseAngryFont, shouldUseJoyFont, shouldUseSadnessFont, splitTextIntoLetters, subtitleManager };