@sweet-player/core 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,211 @@
+interface QualityLevel {
+    /** 显示名称，如 "1080P" */
+    label: string;
+    /** 业务自定义值，切换时原样回传给 onQualityChange */
+    value: string | number;
+    /** 可选：该画质对应的播放地址（传入时切换会自动 load） */
+    src?: string;
+}
+interface AudioTrackInfo {
+    label: string;
+    value: string | number;
+}
+type AspectRatio = 'original' | '21:9' | '16:9' | '4:3' | (string & {});
+interface LongSeekOptions {
+    /** 长按阶梯步长（秒），按住时逐级升档，默认 [10, 30, 60] */
+    steps?: number[];
+    /** 每隔多少毫秒升一档，默认 2000 */
+    stepUpInterval?: number;
+}
+/** 播放器插件：apply 在实例化末尾调用，可返回清理函数（destroy 时执行） */
+interface SweetPlayerPlugin {
+    name: string;
+    apply(player: SweetPlayerLike): void | (() => void);
+}
+/** 插件拿到的最小接口（即 SweetPlayer 实例，避免类型循环引用） */
+interface SweetPlayerLike {
+    container: HTMLElement;
+    video: HTMLVideoElement;
+    on<K extends keyof PlayerEventMap>(event: K, fn: (payload: PlayerEventMap[K]) => void): () => void;
+}
+interface SweetPlayerOptions {
+    /** 挂载容器，元素或选择器 */
+    container: HTMLElement | string;
+    /** 视频地址，.m3u8 走 hls.js，其余直接赋给 video */
+    src: string;
+    /** 左上角标题 */
+    title?: string;
+    /** 视频唯一 ID：传入后自动记忆/恢复播放进度（断点续播） */
+    id?: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    /** 初始音量 0-100，默认 100 */
+    volume?: number;
+    /** 快进快退步长（秒），默认 10 */
+    seekStep?: number;
+    /** 长按快进快退配置 */
+    longSeek?: LongSeekOptions;
+    /** 倍速档位，默认 [0.5, 1, 1.5, 2] */
+    playbackRates?: number[];
+    /** 画面比例档位，默认 ['original', '21:9', '16:9', '4:3'] */
+    aspectRatios?: AspectRatio[];
+    /** 画质列表（预留），传入后画质菜单可选 */
+    qualities?: QualityLevel[];
+    /** 音轨列表（预留） */
+    audioTracks?: AudioTrackInfo[];
+    /**
+     * 自动从 hls.js 读取画质/音轨填充菜单（默认 true）。
+     * 业务传入 qualities/audioTracks 时以业务列表为准。
+     */
+    autoQuality?: boolean;
+    /** 记忆音量/静音/倍速到 localStorage（默认 true） */
+    persist?: boolean;
+    /** 播放结束后自动播放下一个：true = 5 秒倒计时，数字 = 自定义秒数（需配合 onNext） */
+    autoNext?: boolean | number;
+    /** UI 语言，默认 'zh-CN'，内置 'en'；可用 registerLocale 注册其他语言 */
+    locale?: string;
+    /** 覆盖部分 UI 文案 */
+    localeStrings?: Record<string, string>;
+    /** 插件列表，实例化末尾依次 apply */
+    plugins?: SweetPlayerPlugin[];
+    /** 透传给 hls.js 的配置 */
+    hlsConfig?: Record<string, unknown>;
+    /** 点击"上一个"回调（预留） */
+    onPrev?: () => void;
+    /** 点击"下一个"回调（预留） */
+    onNext?: () => void;
+    /** 画质切换回调（预留） */
+    onQualityChange?: (quality: QualityLevel) => void;
+    /** 音轨切换回调（预留） */
+    onAudioTrackChange?: (track: AudioTrackInfo) => void;
+}
+interface PlayerEventMap {
+    ready: void;
+    play: void;
+    pause: void;
+    ended: void;
+    timeupdate: {
+        currentTime: number;
+        duration: number;
+    };
+    ratechange: number;
+    volumechange: {
+        volume: number;
+        muted: boolean;
+    };
+    fullscreenchange: boolean;
+    pipchange: boolean;
+    aspectratiochange: AspectRatio;
+    qualitychange: QualityLevel;
+    audiotrackchange: AudioTrackInfo;
+    error: {
+        type: string;
+        detail?: unknown;
+    };
+    destroy: void;
+}
+type PlayerEventName = keyof PlayerEventMap;
+
+declare class SweetPlayer {
+    readonly container: HTMLElement;
+    readonly video: HTMLVideoElement;
+    private emitter;
+    private media;
+    private keyboard;
+    private gestures;
+    private controls;
+    private osd;
+    private stats;
+    private state;
+    private i18n;
+    private options;
+    private hideTimer;
+    private clickTimer;
+    private progressTimer;
+    private titleClicks;
+    private lastTitleClick;
+    private currentRatio;
+    /** 画质/音轨菜单当前是否由 hls.js 自动接管（业务 setQualities 会关闭） */
+    private hlsManagedQuality;
+    private hlsManagedAudio;
+    private disposers;
+    private pluginCleanups;
+    private destroyed;
+    constructor(options: SweetPlayerOptions);
+    play(): Promise<void>;
+    pause(): void;
+    toggle(): void;
+    seek(time: number): void;
+    /** 相对跳转；showOsd 为 false 时不显示中央提示 */
+    seekBy(delta: number, showOsd?: boolean): void;
+    setRate(rate: number): void;
+    /** 0-100 */
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setAspectRatio(ratio: AspectRatio): void;
+    get aspectRatio(): AspectRatio;
+    /** 运行时更新画质列表 */
+    setQualities(qualities: QualityLevel[], active?: QualityLevel): void;
+    /** 运行时更新音轨列表 */
+    setAudioTracks(tracks: AudioTrackInfo[], active?: AudioTrackInfo): void;
+    toggleFullscreen(): Promise<void>;
+    get fullscreen(): boolean;
+    togglePip(): Promise<void>;
+    load(src: string): void;
+    setTitle(title: string): void;
+    /** 安装插件；返回本次插件的卸载函数 */
+    use(plugin: SweetPlayerPlugin): () => void;
+    on<K extends keyof PlayerEventMap>(event: K, fn: (payload: PlayerEventMap[K]) => void): () => void;
+    off<K extends keyof PlayerEventMap>(event: K, fn: (payload: PlayerEventMap[K]) => void): void;
+    destroy(): void;
+    private applyHlsLevels;
+    private applyHlsAudioTracks;
+    private handleQualitySelect;
+    private handleAudioTrackSelect;
+    private bindPersistence;
+    private bindProgressMemory;
+    private saveProgressNow;
+    private handleTitleClick;
+    private bindMediaEvents;
+    private showErrorState;
+    private showErrorStateUi;
+    private showControls;
+    private hideControlsNow;
+    private scheduleHide;
+    private bindActivityTracking;
+}
+
+interface LocaleStrings {
+    play: string;
+    pause: string;
+    playPause: string;
+    prev: string;
+    next: string;
+    seekBack: string;
+    seekForward: string;
+    speed: string;
+    quality: string;
+    qualityAuto: string;
+    aspectRatio: string;
+    ratioOriginal: string;
+    audioTrack: string;
+    mute: string;
+    fullscreen: string;
+    pip: string;
+    empty: string;
+    closeStats: string;
+    seconds: string;
+    volume: string;
+    muted: string;
+    replay: string;
+    playNext: string;
+    autoNextIn: string;
+    cancel: string;
+    loadError: string;
+    retry: string;
+}
+type LocaleName = 'zh-CN' | 'en' | (string & {});
+/** 注册自定义语言包（全局） */
+declare function registerLocale(name: string, strings: LocaleStrings): void;
+
+export { type AspectRatio, type AudioTrackInfo, type LocaleName, type LocaleStrings, type LongSeekOptions, type PlayerEventMap, type PlayerEventName, type QualityLevel, SweetPlayer, type SweetPlayerLike, type SweetPlayerOptions, type SweetPlayerPlugin, registerLocale };

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+interface QualityLevel {
+    /** 显示名称，如 "1080P" */
+    label: string;
+    /** 业务自定义值，切换时原样回传给 onQualityChange */
+    value: string | number;
+    /** 可选：该画质对应的播放地址（传入时切换会自动 load） */
+    src?: string;
+}
+interface AudioTrackInfo {
+    label: string;
+    value: string | number;
+}
+type AspectRatio = 'original' | '21:9' | '16:9' | '4:3' | (string & {});
+interface LongSeekOptions {
+    /** 长按阶梯步长（秒），按住时逐级升档，默认 [10, 30, 60] */
+    steps?: number[];
+    /** 每隔多少毫秒升一档，默认 2000 */
+    stepUpInterval?: number;
+}
+/** 播放器插件：apply 在实例化末尾调用，可返回清理函数（destroy 时执行） */
+interface SweetPlayerPlugin {
+    name: string;
+    apply(player: SweetPlayerLike): void | (() => void);
+}
+/** 插件拿到的最小接口（即 SweetPlayer 实例，避免类型循环引用） */
+interface SweetPlayerLike {
+    container: HTMLElement;
+    video: HTMLVideoElement;
+    on<K extends keyof PlayerEventMap>(event: K, fn: (payload: PlayerEventMap[K]) => void): () => void;
+}
+interface SweetPlayerOptions {
+    /** 挂载容器，元素或选择器 */
+    container: HTMLElement | string;
+    /** 视频地址，.m3u8 走 hls.js，其余直接赋给 video */
+    src: string;
+    /** 左上角标题 */
+    title?: string;
+    /** 视频唯一 ID：传入后自动记忆/恢复播放进度（断点续播） */
+    id?: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    /** 初始音量 0-100，默认 100 */
+    volume?: number;
+    /** 快进快退步长（秒），默认 10 */
+    seekStep?: number;
+    /** 长按快进快退配置 */
+    longSeek?: LongSeekOptions;
+    /** 倍速档位，默认 [0.5, 1, 1.5, 2] */
+    playbackRates?: number[];
+    /** 画面比例档位，默认 ['original', '21:9', '16:9', '4:3'] */
+    aspectRatios?: AspectRatio[];
+    /** 画质列表（预留），传入后画质菜单可选 */
+    qualities?: QualityLevel[];
+    /** 音轨列表（预留） */
+    audioTracks?: AudioTrackInfo[];
+    /**
+     * 自动从 hls.js 读取画质/音轨填充菜单（默认 true）。
+     * 业务传入 qualities/audioTracks 时以业务列表为准。
+     */
+    autoQuality?: boolean;
+    /** 记忆音量/静音/倍速到 localStorage（默认 true） */
+    persist?: boolean;
+    /** 播放结束后自动播放下一个：true = 5 秒倒计时，数字 = 自定义秒数（需配合 onNext） */
+    autoNext?: boolean | number;
+    /** UI 语言，默认 'zh-CN'，内置 'en'；可用 registerLocale 注册其他语言 */
+    locale?: string;
+    /** 覆盖部分 UI 文案 */
+    localeStrings?: Record<string, string>;
+    /** 插件列表，实例化末尾依次 apply */
+    plugins?: SweetPlayerPlugin[];
+    /** 透传给 hls.js 的配置 */
+    hlsConfig?: Record<string, unknown>;
+    /** 点击"上一个"回调（预留） */
+    onPrev?: () => void;
+    /** 点击"下一个"回调（预留） */
+    onNext?: () => void;
+    /** 画质切换回调（预留） */
+    onQualityChange?: (quality: QualityLevel) => void;
+    /** 音轨切换回调（预留） */
+    onAudioTrackChange?: (track: AudioTrackInfo) => void;
+}
+interface PlayerEventMap {
+    ready: void;
+    play: void;
+    pause: void;
+    ended: void;
+    timeupdate: {
+        currentTime: number;
+        duration: number;
+    };
+    ratechange: number;
+    volumechange: {
+        volume: number;
+        muted: boolean;
+    };
+    fullscreenchange: boolean;
+    pipchange: boolean;
+    aspectratiochange: AspectRatio;
+    qualitychange: QualityLevel;
+    audiotrackchange: AudioTrackInfo;
+    error: {
+        type: string;
+        detail?: unknown;
+    };
+    destroy: void;
+}
+type PlayerEventName = keyof PlayerEventMap;
+
+declare class SweetPlayer {
+    readonly container: HTMLElement;
+    readonly video: HTMLVideoElement;
+    private emitter;
+    private media;
+    private keyboard;
+    private gestures;
+    private controls;
+    private osd;
+    private stats;
+    private state;
+    private i18n;
+    private options;
+    private hideTimer;
+    private clickTimer;
+    private progressTimer;
+    private titleClicks;
+    private lastTitleClick;
+    private currentRatio;
+    /** 画质/音轨菜单当前是否由 hls.js 自动接管（业务 setQualities 会关闭） */
+    private hlsManagedQuality;
+    private hlsManagedAudio;
+    private disposers;
+    private pluginCleanups;
+    private destroyed;
+    constructor(options: SweetPlayerOptions);
+    play(): Promise<void>;
+    pause(): void;
+    toggle(): void;
+    seek(time: number): void;
+    /** 相对跳转；showOsd 为 false 时不显示中央提示 */
+    seekBy(delta: number, showOsd?: boolean): void;
+    setRate(rate: number): void;
+    /** 0-100 */
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setAspectRatio(ratio: AspectRatio): void;
+    get aspectRatio(): AspectRatio;
+    /** 运行时更新画质列表 */
+    setQualities(qualities: QualityLevel[], active?: QualityLevel): void;
+    /** 运行时更新音轨列表 */
+    setAudioTracks(tracks: AudioTrackInfo[], active?: AudioTrackInfo): void;
+    toggleFullscreen(): Promise<void>;
+    get fullscreen(): boolean;
+    togglePip(): Promise<void>;
+    load(src: string): void;
+    setTitle(title: string): void;
+    /** 安装插件；返回本次插件的卸载函数 */
+    use(plugin: SweetPlayerPlugin): () => void;
+    on<K extends keyof PlayerEventMap>(event: K, fn: (payload: PlayerEventMap[K]) => void): () => void;
+    off<K extends keyof PlayerEventMap>(event: K, fn: (payload: PlayerEventMap[K]) => void): void;
+    destroy(): void;
+    private applyHlsLevels;
+    private applyHlsAudioTracks;
+    private handleQualitySelect;
+    private handleAudioTrackSelect;
+    private bindPersistence;
+    private bindProgressMemory;
+    private saveProgressNow;
+    private handleTitleClick;
+    private bindMediaEvents;
+    private showErrorState;
+    private showErrorStateUi;
+    private showControls;
+    private hideControlsNow;
+    private scheduleHide;
+    private bindActivityTracking;
+}
+
+interface LocaleStrings {
+    play: string;
+    pause: string;
+    playPause: string;
+    prev: string;
+    next: string;
+    seekBack: string;
+    seekForward: string;
+    speed: string;
+    quality: string;
+    qualityAuto: string;
+    aspectRatio: string;
+    ratioOriginal: string;
+    audioTrack: string;
+    mute: string;
+    fullscreen: string;
+    pip: string;
+    empty: string;
+    closeStats: string;
+    seconds: string;
+    volume: string;
+    muted: string;
+    replay: string;
+    playNext: string;
+    autoNextIn: string;
+    cancel: string;
+    loadError: string;
+    retry: string;
+}
+type LocaleName = 'zh-CN' | 'en' | (string & {});
+/** 注册自定义语言包（全局） */
+declare function registerLocale(name: string, strings: LocaleStrings): void;
+
+export { type AspectRatio, type AudioTrackInfo, type LocaleName, type LocaleStrings, type LongSeekOptions, type PlayerEventMap, type PlayerEventName, type QualityLevel, SweetPlayer, type SweetPlayerLike, type SweetPlayerOptions, type SweetPlayerPlugin, registerLocale };