@volcengine/veplayer 2.6.2 → 2.7.0-rc.0

package/veplayer.d.ts

@@ -1,7 +1,6 @@
 import Player from "xgplayer";
 import { IXGI18nText, Plugin, IPluginOptions, Sniffer } from "xgplayer";
 import { IPlayerOptions as PlayerOptions } from "xgplayer";
-import { IDefinition as XGDefinition } from "xgplayer";
 import { default as Player$0 } from "xgplayer";
 import { IError as XGError } from "xgplayer";
 import { IBasePluginOptions as XGPluginOptions } from "xgplayer";
@@ -164,8 +163,8 @@ interface DefinitionUrl {
     url: string;
     next: DefinitionUrl | null;
 }
-declare class Definition implements XGDefinition {
-    readonly definition: string;
+declare class Definition {
+    readonly definition?: string;
     readonly source: Source;
     readonly text?: Record<Lang, string> | string;
     readonly fallbackUrl: DefinitionUrl;
@@ -173,7 +172,7 @@ declare class Definition implements XGDefinition {
     private _currentUrlRef;
     constructor(definitionSetting: {
         url: string;
-        definition: string;
+        definition?: string;
         source: Source;
         text?: Record<Lang, string> | string;
         fallbackUrls?: string[];
@@ -211,7 +210,7 @@ interface ExposedDefinition {
      * @brief The resolution ID. This value must be unique.
      *
      */
-    definition: string;
+    definition?: string;
     /** {zh}
      * @brief 清晰度展示名称。可设置多语言 `{text: {'zh-cn': '高清', 'en': 'HD'}}`。
      */
@@ -227,6 +226,7 @@ interface ExposedDefinition {
      *
      */
     fallbackUrls?: string[];
+    type?: string;
 }
 /** {zh}
  * @list option
@@ -1613,9 +1613,10 @@ type PrepareResult = {
     options?: Partial<VePlayerBaseOptions>;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     plugins?: any[];
+    protocol?: string;
     useSrc?: boolean;
 };
-type PreparePlugins = (url: string) => Promise<PrepareResult> | undefined;
+type PreparePlugins = (url?: string) => Promise<PrepareResult | undefined> | undefined;
 /** {zh}
  * @detail option
  * @brief 视频的实际编码格式。如果您在 degradation 设置了 SoftFirst 属性（即硬解不支持降级软解），建议您传入该参数，省去探测实际编码格式的操作。
@@ -1739,6 +1740,7 @@ declare class VePlayerBase {
     private _events;
     private _customMedia?;
     private _errorCallback;
+    private _beforeFallbackError;
     /** {zh}
      * @hidden
      */
@@ -1889,7 +1891,7 @@ declare class VePlayerBase {
     /** {en}
      * @brief Gets the current resolution ID.
      */
-    get definition(): string;
+    get definition(): string | undefined;
     /** {zh}
      * @brief 获取和设置播放器的跨域配置信息，更多信息参考 [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) 属性介绍。
      */
@@ -2506,8 +2508,8 @@ declare namespace strategy {
         next: DefinitionUrl | null;
     }
     function arrayToList(urls?: string[]): DefinitionUrl;
-    class Definition implements XGDefinition {
-        readonly definition: string;
+    class Definition {
+        readonly definition?: string;
         readonly source: Source;
         readonly text?: Record<Lang, string> | string;
         readonly fallbackUrl: DefinitionUrl;
@@ -2515,7 +2517,7 @@ declare namespace strategy {
         private _currentUrlRef;
         constructor(definitionSetting: {
             url: string;
-            definition: string;
+            definition?: string;
             source: Source;
             text?: Record<Lang, string> | string;
             fallbackUrls?: string[];
@@ -2553,7 +2555,7 @@ declare namespace strategy {
          * @brief The resolution ID. This value must be unique.
          *
          */
-        definition: string;
+        definition?: string;
         /** {zh}
          * @brief 清晰度展示名称。可设置多语言 `{text: {'zh-cn': '高清', 'en': 'HD'}}`。
          */
@@ -2569,6 +2571,7 @@ declare namespace strategy {
          *
          */
         fallbackUrls?: string[];
+        type?: string;
     }
     /** {zh}
      * @list option
@@ -3956,9 +3959,10 @@ declare namespace strategy {
         options?: Partial<VePlayerBaseOptions>;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         plugins?: any[];
+        protocol?: string;
         useSrc?: boolean;
     };
-    type PreparePlugins = (url: string) => Promise<PrepareResult> | undefined;
+    type PreparePlugins = (url?: string) => Promise<PrepareResult | undefined> | undefined;
     /** {zh}
      * @detail option
      * @brief 视频的实际编码格式。如果您在 degradation 设置了 SoftFirst 属性（即硬解不支持降级软解），建议您传入该参数，省去探测实际编码格式的操作。
@@ -4138,13 +4142,6 @@ declare namespace strategy {
     function detectCodec(url: string): Promise<"unknown" | Codec>;
     function isSoftDecode(options: VePlayerBaseOptions, currentCodec?: Codec | "unknown"): Promise<boolean>;
     function combineOptions<T = VePlayerBaseOptions>(strategyList: (Strategy<T> | undefined)[]): Partial<T>;
-    const getHlsStrategy: (options: VePlayerBaseOptions) => Promise<{
-        options?: undefined;
-        plugins?: undefined;
-    } | {
-        options: Partial<VePlayerBaseOptions>;
-        plugins: any[];
-    }>;
 }
 declare function getStreamType(url: string): "unknown" | "hls" | "flv" | "rtm" | "mp4" | "dash";
 /** {zh}
@@ -5068,7 +5065,6 @@ declare class Sources extends OptionsIcon {
     };
     updateLang(): void;
     beforeCreate(args: XGPluginOptions): void;
-    afterCreate(): void;
     registerIcons(): {
         source: {
             icon: any;
@@ -5241,6 +5237,88 @@ interface LoggerConfig {
      */
     showUserIdInErrorPanel?: boolean;
 }
+declare enum FallbackKind {
+    Error = "Error",
+    Stall = "Stall"
+}
+interface ErrorFallbackStrategy {
+    type?: FallbackKind;
+    excludeList?: ErrorCode[];
+    shouldFallback?: (type: string, params: {
+        error: VeError;
+    }) => boolean;
+}
+interface StallFallbackStrategy {
+    type?: FallbackKind;
+    shouldFallback?: (type: string) => boolean;
+}
+// 播放类型抽象类 （BaseProtocol）
+declare abstract class BaseProtocol {
+    // 下一个 protocol 类
+    nextProtocol?: BaseProtocol;
+    preProtocol?: BaseProtocol;
+    protocolStrategy?: Strategy;
+    private _fallback;
+    constructor(options: VePlayerBaseOptions);
+    // 当前播放类型
+    abstract get protocolType(): string;
+    abstract get defaultFallbackStrategy(): Partial<Record<FallbackKind, StallFallbackStrategy | ErrorFallbackStrategy>>;
+    private _getKindFallbackStrategy;
+    // eslint-disable-next-line @typescript-eslint/member-ordering
+    get errorFallbackStrategy(): any;
+    // eslint-disable-next-line @typescript-eslint/member-ordering
+    get stallFallbackStrategy(): any;
+    abstract shouldFallbackWhenStall(): boolean;
+    // eslint-disable-next-line @typescript-eslint/member-ordering
+    shouldFallbackWhenError(params: {
+        error: VeError;
+    }): any;
+    // 是否支持播放
+    abstract canPlay(): Promise<{
+        canPlay: boolean;
+    }>;
+    abstract getProtocolStrategy(options: VePlayerBaseOptions, config?: {
+        player?: VePlayerBase;
+        i18n?: VeI18n;
+        enableSelector?: boolean;
+    }): Promise<Strategy> | undefined;
+    abstract getDrmStrategy(options: VePlayerBaseOptions, player?: VePlayerBase): Promise<Strategy> | undefined;
+    abstract getAbrStrategy(options: VePlayerBaseOptions): Promise<Strategy> | undefined;
+}
+type Strategy = {
+    options?: undefined;
+    plugins?: undefined;
+} | {
+    options: Partial<VePlayerBaseOptions>;
+    plugins: any[];
+};
+declare class ProtocolManager {
+    private static _protocolMap;
+    private _options;
+    private _selector?;
+    private _protocol;
+    private _playlistMap;
+    constructor(options: LiveVePlayerOptions);
+    get enableSelector(): boolean;
+    get protocol(): BaseProtocol | undefined;
+    get playlist(): ExposedSource[] | undefined;
+    static create(options: LiveVePlayerOptions): Promise<ProtocolManager>;
+    private static _generateProtocolMap;
+    getProtocol(): Promise<BaseProtocol | undefined>;
+    update({ url, playlist }: {
+        url?: string;
+        playlist?: VePlayerBaseOptions["playlist"];
+    }): Promise<void>;
+    next(): Promise<BaseProtocol | undefined>;
+    getStrategy(player: VePlayerBase | undefined, i18n: VeI18n): Promise<{
+        options: Partial<VePlayerBaseOptions>;
+        plugins: any[];
+        useSrc: boolean;
+        protocol: string | undefined;
+    }>;
+    private _init;
+    private _initSingleProtocol;
+}
 /** {zh}
  * @list option
  * @kind property
@@ -5333,6 +5411,16 @@ interface LiveVePlayerOptions extends VePlayerBaseOptions {
      * @brief Digital Rights Management (DRM) configurations.
      */
     drm?: Drm;
+    latencyMode?: "standard" | "low";
+    fallback?: Fallback;
+}
+interface Fallback {
+    enableFallback?: boolean;
+    fallbackOrder?: string[];
+    fallbackStrategy?: Record<string | "all", {
+        [FallbackKind.Error]?: ErrorFallbackStrategy;
+        [FallbackKind.Stall]?: StallFallbackStrategy;
+    }>;
 }
 /** {zh}
  * @list option
@@ -6236,12 +6324,14 @@ interface StatsSnapShoot {
 /** {zh}
  * @list option
  * @kind property
+ * @brief FLV 直播流播放信息。
  */
 /** {en}
  * @list option
  * @kind property
+ * @brief FLV live stream information.
  */
-interface Stats$0 {
+interface FlvStats {
     /** {zh}
      * @brief 音频格式。
      * @hidden
@@ -6343,45 +6433,33 @@ interface Stats$0 {
      */
     samplerate: number;
     /** {zh}
-     * @hidden
+     * @brief 总共收到的字节数。
      */
     /** {en}
-     * @hidden
+     * @brief The total number of bytes received.
      */
-    videoCodec: string;
+    totalReceivedByte: number;
     /** {zh}
-     * @brief 视频宽度。
+     * @brief 接收所有字节消耗时长。
      */
     /** {en}
-     * @brief Video wight.
+     * @brief The time consumed for receiving all bytes.
      */
-    width: number;
-}
-/** {zh}
- * @list option
- * @kind property
- * @brief FLV 直播流播放信息。
- */
-/** {en}
- * @list option
- * @kind property
- * @brief FLV live stream information.
- */
-interface FlvStats extends Stats$0 {
+    totalReceivedCost: number;
     /** {zh}
-     * @brief 总共收到的字节数。
+     * @hidden
      */
     /** {en}
-     * @brief The total number of bytes received.
+     * @hidden
      */
-    totalReceivedByte: number;
+    videoCodec: string;
     /** {zh}
-     * @brief 接收所有字节消耗时长。
+     * @brief 视频宽度。
      */
     /** {en}
-     * @brief The time consumed for receiving all bytes.
+     * @brief Video wight.
      */
-    totalReceivedCost: number;
+    width: number;
 }
 /** {zh}
  * @detail api
@@ -6394,6 +6472,7 @@ interface FlvStats extends Stats$0 {
  * @inheritdoc
  */
 declare class VePlayerLive extends VePlayerBase {
+    _protocolManager?: ProtocolManager;
     /** {zh}
      * @hidden
      * @param options
@@ -6523,14 +6602,28 @@ declare class VePlayerLive extends VePlayerBase {
      * @brief Obtain the playback information of FLV pull streaming.
      */
     getFLVStats(): FlvStats;
-    /** {zh}
-     * @brief 获取 HLS 拉流的播放信息。
-     * @returns
-     */
-    /** {en}
-     * @brief Obtain the playback information of HLS pull streaming.
-     */
-    getHLSStats(): Stats$0;
+    updatePlaylist(playlist: ExposedSource[], target?: string | {
+        /** {zh}
+         * @brief 清晰度唯一标识。
+         * @default 无
+         *
+         */
+        /** {en}
+         * @brief The resolution ID.
+         *
+         */
+        definition?: string;
+        /** {zh}
+         * @brief 线路的唯一标识。
+         * @default 无
+         *
+         */
+        /** {en}
+         * @brief The playback resource ID.
+         *
+         */
+        source?: string;
+    }, needUpdateProtocol?: boolean): Promise<void>;
 }
 /** {zh}
  * @detail api
@@ -7219,8 +7312,8 @@ declare namespace live {
         next: DefinitionUrl | null;
     }
     function arrayToList(urls?: string[]): DefinitionUrl;
-    class Definition implements XGDefinition {
-        readonly definition: string;
+    class Definition {
+        readonly definition?: string;
         readonly source: Source;
         readonly text?: Record<Lang, string> | string;
         readonly fallbackUrl: DefinitionUrl;
@@ -7228,7 +7321,7 @@ declare namespace live {
         private _currentUrlRef;
         constructor(definitionSetting: {
             url: string;
-            definition: string;
+            definition?: string;
             source: Source;
             text?: Record<Lang, string> | string;
             fallbackUrls?: string[];
@@ -7266,7 +7359,7 @@ declare namespace live {
          * @brief The resolution ID. This value must be unique.
          *
          */
-        definition: string;
+        definition?: string;
         /** {zh}
          * @brief 清晰度展示名称。可设置多语言 `{text: {'zh-cn': '高清', 'en': 'HD'}}`。
          */
@@ -7282,6 +7375,7 @@ declare namespace live {
          *
          */
         fallbackUrls?: string[];
+        type?: string;
     }
     /** {zh}
      * @list option
@@ -9270,9 +9364,10 @@ declare namespace live {
         options?: Partial<VePlayerBaseOptions>;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         plugins?: any[];
+        protocol?: string;
         useSrc?: boolean;
     };
-    type PreparePlugins = (url: string) => Promise<PrepareResult> | undefined;
+    type PreparePlugins = (url?: string) => Promise<PrepareResult | undefined> | undefined;
     /** {zh}
      * @detail option
      * @brief 视频的实际编码格式。如果您在 degradation 设置了 SoftFirst 属性（即硬解不支持降级软解），建议您传入该参数，省去探测实际编码格式的操作。
@@ -9397,6 +9492,7 @@ declare namespace live {
         private _events;
         private _customMedia?;
         private _errorCallback;
+        private _beforeFallbackError;
         /** {zh}
          * @hidden
          */
@@ -9547,7 +9643,7 @@ declare namespace live {
         /** {en}
          * @brief Gets the current resolution ID.
          */
-        get definition(): string;
+        get definition(): string | undefined;
         /** {zh}
          * @brief 获取和设置播放器的跨域配置信息，更多信息参考 [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) 属性介绍。
          */
@@ -10253,7 +10349,6 @@ declare namespace live {
         };
         updateLang(): void;
         beforeCreate(args: XGPluginOptions): void;
-        afterCreate(): void;
         registerIcons(): {
             source: {
                 icon: any;
@@ -10762,6 +10857,88 @@ declare namespace live {
         private _createTea;
         private _start;
     }
+    enum FallbackKind {
+        Error = "Error",
+        Stall = "Stall"
+    }
+    interface ErrorFallbackStrategy {
+        type?: FallbackKind;
+        excludeList?: ErrorCode$0[];
+        shouldFallback?: (type: string, params: {
+            error: VeError$1;
+        }) => boolean;
+    }
+    interface StallFallbackStrategy {
+        type?: FallbackKind;
+        shouldFallback?: (type: string) => boolean;
+    }
+    // 播放类型抽象类 （BaseProtocol）
+    abstract class BaseProtocol {
+        // 下一个 protocol 类
+        nextProtocol?: BaseProtocol;
+        preProtocol?: BaseProtocol;
+        protocolStrategy?: Strategy;
+        private _fallback;
+        constructor(options: VePlayerBaseOptions);
+        // 当前播放类型
+        abstract get protocolType(): string;
+        abstract get defaultFallbackStrategy(): Partial<Record<FallbackKind, StallFallbackStrategy | ErrorFallbackStrategy>>;
+        private _getKindFallbackStrategy;
+        // eslint-disable-next-line @typescript-eslint/member-ordering
+        get errorFallbackStrategy(): any;
+        // eslint-disable-next-line @typescript-eslint/member-ordering
+        get stallFallbackStrategy(): any;
+        abstract shouldFallbackWhenStall(): boolean;
+        // eslint-disable-next-line @typescript-eslint/member-ordering
+        shouldFallbackWhenError(params: {
+            error: VeError$1;
+        }): any;
+        // 是否支持播放
+        abstract canPlay(): Promise<{
+            canPlay: boolean;
+        }>;
+        abstract getProtocolStrategy(options: VePlayerBaseOptions, config?: {
+            player?: VePlayerBase;
+            i18n?: VeI18n;
+            enableSelector?: boolean;
+        }): Promise<Strategy> | undefined;
+        abstract getDrmStrategy(options: VePlayerBaseOptions, player?: VePlayerBase): Promise<Strategy> | undefined;
+        abstract getAbrStrategy(options: VePlayerBaseOptions): Promise<Strategy> | undefined;
+    }
+    type Strategy = {
+        options?: undefined;
+        plugins?: undefined;
+    } | {
+        options: Partial<VePlayerBaseOptions>;
+        plugins: any[];
+    };
+    class ProtocolManager {
+        private static _protocolMap;
+        private _options;
+        private _selector?;
+        private _protocol;
+        private _playlistMap;
+        constructor(options: LiveVePlayerOptions);
+        get enableSelector(): boolean;
+        get protocol(): BaseProtocol | undefined;
+        get playlist(): ExposedSource[] | undefined;
+        static create(options: LiveVePlayerOptions): Promise<ProtocolManager>;
+        private static _generateProtocolMap;
+        getProtocol(): Promise<BaseProtocol | undefined>;
+        update({ url, playlist }: {
+            url?: string;
+            playlist?: VePlayerBaseOptions["playlist"];
+        }): Promise<void>;
+        next(): Promise<BaseProtocol | undefined>;
+        getStrategy(player: VePlayerBase | undefined, i18n: VeI18n): Promise<{
+            options: Partial<VePlayerBaseOptions>;
+            plugins: any[];
+            useSrc: boolean;
+            protocol: string | undefined;
+        }>;
+        private _init;
+        private _initSingleProtocol;
+    }
     /** {zh}
      * @list option
      * @kind property
@@ -10854,6 +11031,16 @@ declare namespace live {
          * @brief Digital Rights Management (DRM) configurations.
          */
         drm?: Drm;
+        latencyMode?: "standard" | "low";
+        fallback?: Fallback;
+    }
+    interface Fallback {
+        enableFallback?: boolean;
+        fallbackOrder?: string[];
+        fallbackStrategy?: Record<string | "all", {
+            [FallbackKind.Error]?: ErrorFallbackStrategy;
+            [FallbackKind.Stall]?: StallFallbackStrategy;
+        }>;
     }
     /** {zh}
      * @list option
@@ -11757,12 +11944,14 @@ declare namespace live {
     /** {zh}
      * @list option
      * @kind property
+     * @brief FLV 直播流播放信息。
      */
     /** {en}
      * @list option
      * @kind property
+     * @brief FLV live stream information.
      */
-    interface Stats$0 {
+    interface FlvStats {
         /** {zh}
          * @brief 音频格式。
          * @hidden
@@ -11864,45 +12053,33 @@ declare namespace live {
          */
         samplerate: number;
         /** {zh}
-         * @hidden
+         * @brief 总共收到的字节数。
          */
         /** {en}
-         * @hidden
+         * @brief The total number of bytes received.
          */
-        videoCodec: string;
+        totalReceivedByte: number;
         /** {zh}
-         * @brief 视频宽度。
+         * @brief 接收所有字节消耗时长。
          */
         /** {en}
-         * @brief Video wight.
+         * @brief The time consumed for receiving all bytes.
          */
-        width: number;
-    }
-    /** {zh}
-     * @list option
-     * @kind property
-     * @brief FLV 直播流播放信息。
-     */
-    /** {en}
-     * @list option
-     * @kind property
-     * @brief FLV live stream information.
-     */
-    interface FlvStats extends Stats$0 {
+        totalReceivedCost: number;
         /** {zh}
-         * @brief 总共收到的字节数。
+         * @hidden
          */
         /** {en}
-         * @brief The total number of bytes received.
+         * @hidden
          */
-        totalReceivedByte: number;
+        videoCodec: string;
         /** {zh}
-         * @brief 接收所有字节消耗时长。
+         * @brief 视频宽度。
          */
         /** {en}
-         * @brief The time consumed for receiving all bytes.
+         * @brief Video wight.
          */
-        totalReceivedCost: number;
+        width: number;
     }
     /** {zh}
      * @detail api
@@ -11915,6 +12092,7 @@ declare namespace live {
      * @inheritdoc
      */
     class VePlayerLive extends VePlayerBase {
+        _protocolManager?: ProtocolManager;
         /** {zh}
          * @hidden
          * @param options
@@ -12044,14 +12222,28 @@ declare namespace live {
          * @brief Obtain the playback information of FLV pull streaming.
          */
         getFLVStats(): FlvStats;
-        /** {zh}
-         * @brief 获取 HLS 拉流的播放信息。
-         * @returns
-         */
-        /** {en}
-         * @brief Obtain the playback information of HLS pull streaming.
-         */
-        getHLSStats(): Stats$0;
+        updatePlaylist(playlist: ExposedSource[], target?: string | {
+            /** {zh}
+             * @brief 清晰度唯一标识。
+             * @default 无
+             *
+             */
+            /** {en}
+             * @brief The resolution ID.
+             *
+             */
+            definition?: string;
+            /** {zh}
+             * @brief 线路的唯一标识。
+             * @default 无
+             *
+             */
+            /** {en}
+             * @brief The playback resource ID.
+             *
+             */
+            source?: string;
+        }, needUpdateProtocol?: boolean): Promise<void>;
     }
     /** {zh}
      * @detail api