@byteplus/veplayer 1.19.0-rc.4 → 1.19.0-rc.6

package/lite.d.ts

@@ -22,6 +22,892 @@ export declare enum UmdKeys {
 }
 /** Resolved UMD module values keyed by their public UMD key. */
 export type UmdModules = Partial<Record<UmdKeys, unknown>>;
+interface ISubTitleItem {
+	/** {zh}
+	 * @brief 字幕来源。业务配置字幕为 `config`，Master M3U8 或原生 HLS 字幕为 `hls`。
+	 * @default config
+	 */
+	/** {en}
+	 * @brief Subtitle source. Business-configured subtitles use `config`; Master M3U8 or native HLS subtitles use `hls`.
+	 * @default config
+	 */
+	source?: "config" | "hls";
+	/** {zh}
+	 * @brief 字幕语言。
+	 * @default -
+	 */
+	/** {en}
+	 * @brief Subtitle language.
+	 * @default -
+	 */
+	language?: string | number;
+	/** {zh}
+	 * @brief 字幕 ID。
+	 * @default -
+	 */
+	/** {en}
+	 * @brief Subtitle ID.
+	 * @default -
+	 */
+	id?: number | string;
+	/** {zh}
+	 * @brief 是否为默认选择的字幕。
+	 * @default false
+	 */
+	/** {en}
+	 * @brief Whether this is the default selected subtitle.
+	 * @default false
+	 */
+	isDefault?: boolean;
+	/** {zh}
+	 * @brief 是否为强制字幕轨。
+	 * @default false
+	 */
+	/** {en}
+	 * @brief Whether the subtitle track is forced.
+	 * @default false
+	 */
+	forced?: boolean;
+	/** {zh}
+	 * @brief HLS 字幕轨的特征标识，例如无障碍字幕特征；未声明时为空。
+	 * @default -
+	 */
+	/** {en}
+	 * @brief HLS subtitle-track characteristics, such as accessibility traits; absent when not declared.
+	 * @default -
+	 */
+	characteristics?: string;
+	/** {zh}
+	 * @brief 字幕名称。
+	 * @default -
+	 */
+	/** {en}
+	 * @brief Subtitle display name.
+	 * @default -
+	 */
+	text?: ISubtitleLabelValue;
+	/** {zh}
+	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
+	 * @default -
+	 */
+	/** {en}
+	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
+	 * @default -
+	 */
+	label?: ISubtitleLabelValue;
+	/** {zh}
+	 * @brief 外挂字幕 URL 地址。
+	 * @default -
+	 */
+	/** {en}
+	 * @brief External subtitle URL.
+	 * @default -
+	 */
+	url?: string;
+	/**
+	 * @hidden
+	 * @type {string}
+	 * @memberof ISubTitleItem
+	 */
+	stringContent?: string;
+	/** {zh}
+	 * @brief 字幕内容列表。非 `url` 形式时使用。
+	 * @default -
+	 * @type {Array<Object>}
+	 * @memberof ISubTitleItem
+	 */
+	/** {en}
+	 * @brief Subtitle content list when not using URL.
+	 * @default -
+	 * @type {Array<Object>}
+	 * @memberof ISubTitleItem
+	 */
+	list?: IListItem[];
+}
+/** {zh}
+ * @brief 字幕项名称，可为静态文案或按播放器语言配置的文案表。
+ * @detail ref
+ */
+/** {en}
+ * @brief Subtitle item name as static text or a text map keyed by player language.
+ * @detail ref
+ */
+export type ISubtitleLabelValue = string | number | Record<string, string | number>;
+/** {zh}
+ * @brief 字幕标签映射项。
+ * @detail ref
+ */
+/** {en}
+ * @brief Mapping item used to customize a subtitle label.
+ * @detail ref
+ */
+export interface ISubtitleLabelItem {
+	/** {zh} @brief 多语言 key 无法解析时使用的回退文案。 */
+	/** {en} @brief Fallback text used when the i18n key cannot be resolved. */
+	text?: string;
+	/** {zh} @brief 从播放器当前多语言词典中读取文案的 key。 */
+	/** {en} @brief Key resolved from the player's active i18n dictionary. */
+	textKey?: string;
+}
+/** {zh}
+ * @brief 字幕标签映射表。匹配优先级为 `id`、完整 `language`、基础 `language`、原始 `text`。
+ * @detail ref
+ */
+/** {en}
+ * @brief Subtitle label maps. Match order is `id`, full `language`, base `language`, then source `text`.
+ * @detail ref
+ */
+export interface ISubtitleLabelMap {
+	/** {zh} @brief 按稳定字幕 ID 映射；不建议用于会话内生成 ID 的 Master M3U8 字幕。 */
+	/** {en} @brief Maps stable subtitle IDs; not recommended for session-scoped Master M3U8 IDs. */
+	id?: Record<string, ISubtitleLabelItem>;
+	/** {zh} @brief 按字幕语言映射，忽略大小写并兼容 `_` 与 `-`。 */
+	/** {en} @brief Maps subtitle languages case-insensitively, treating `_` and `-` as equivalent. */
+	language?: Record<string, ISubtitleLabelItem>;
+	/** {zh} @brief 按字幕原始名称映射。 */
+	/** {en} @brief Maps the source subtitle name. */
+	text?: Record<string, ISubtitleLabelItem>;
+}
+/** {zh}
+ * @brief 传给字幕标签 formatter 的只读安全字幕快照，不包含 URL 或字幕内容。
+ * @detail ref
+ */
+/** {en}
+ * @brief Read-only safe subtitle snapshot passed to the label formatter, excluding URLs and subtitle content.
+ * @detail ref
+ */
+export interface ISubtitleLabelTrack {
+	source?: "config" | "hls";
+	id?: string | number;
+	language?: string | number;
+	isDefault?: boolean;
+	forced?: boolean;
+	characteristics?: string;
+	text?: string | number;
+	label?: string | number;
+}
+/** {zh}
+ * @brief 字幕标签格式化上下文。
+ * @detail ref
+ */
+/** {en}
+ * @brief Context passed to the subtitle label formatter.
+ * @detail ref
+ */
+export interface ISubtitleLabelContext {
+	/** {zh} @brief 当前字幕项的只读安全快照。 */
+	/** {en} @brief Read-only safe snapshot of the current subtitle item. */
+	item: Readonly<ISubtitleLabelTrack>;
+	/** {zh} @brief 当前字幕列表的只读安全快照。 */
+	/** {en} @brief Read-only safe snapshots of the current subtitle list. */
+	items: ReadonlyArray<Readonly<ISubtitleLabelTrack>>;
+	/** {zh} @brief 当前字幕项在列表中的位置。 */
+	/** {en} @brief Position of the current subtitle item in the list. */
+	index: number;
+	/** {zh} @brief 应用标签映射前的原始回退文案。 */
+	/** {en} @brief Source fallback text before applying label mappings. */
+	canonicalLabel: string;
+	/** {zh} @brief 应用 `textKey` 或 `text` 后的文案。 */
+	/** {en} @brief Label after applying `textKey` or `text`. */
+	localizedLabel: string;
+	/** {zh} @brief formatter 返回空值或抛出异常时使用的文案。 */
+	/** {en} @brief Label used when the formatter returns an empty value or throws. */
+	defaultLabel: string;
+	/** {zh} @brief 播放器当前语言。 */
+	/** {en} @brief Current player language. */
+	lang: string;
+	/** {zh} @brief 本地化后的文案是否在当前字幕列表中重复。 */
+	/** {en} @brief Whether the localized label is duplicated in the current subtitle list. */
+	duplicated: boolean;
+}
+/** {zh}
+ * @brief 字幕标签多语言映射与自定义格式化配置。
+ * @detail ref
+ */
+/** {en}
+ * @brief Localization mapping and custom formatter for subtitle labels.
+ * @detail ref
+ */
+export interface ISubtitleLabelOptions {
+	/** {zh} @brief 按字幕 ID、语言或原始名称配置展示文案。 */
+	/** {en} @brief Display-label mappings keyed by subtitle ID, language, or source name. */
+	map?: ISubtitleLabelMap;
+	/** {zh} @brief 同步格式化最终标签；返回空值、Promise 或抛出异常时回退到 `defaultLabel`。 */
+	/** {en} @brief Synchronously formats the final label; empty values, Promises, or exceptions fall back to `defaultLabel`. */
+	formatter?: (context: ISubtitleLabelContext) => string | null | undefined;
+}
+interface IListItem {
+	/** {zh}
+	 * @brief 开始时间，单位为秒。
+	 * @type {number}
+	 */
+	/** {en}
+	 * @brief Start time in seconds.
+	 * @type {number}
+	 */
+	start: number;
+	/** {zh}
+	 * @brief 结束时间，单位为秒。
+	 * @type {number}
+	 */
+	/** {en}
+	 * @brief End time in seconds.
+	 * @type {number}
+	 */
+	end: number;
+	/** {zh}
+	 * @brief 字幕数据列表。
+	 * @type {Array<ITextItem>}
+	 */
+	/** {en}
+	 * @brief Subtitle cue data list.
+	 * @type {Array<ITextItem>}
+	 */
+	list: Array<ITextItem>;
+	/**
+	 * @hidden
+	 * @type {any}
+	 */
+	[propName: string]: any;
+}
+interface ITextItem {
+	/**
+	 * @hidden
+	 * @type {any}
+	 */
+	[propName: string]: any;
+	/** {zh}
+	 * @brief 开始时间，单位为秒。
+	 * @type {number}
+	 */
+	/** {en}
+	 * @brief Start time in seconds.
+	 * @type {number}
+	 */
+	start: number;
+	/** {zh}
+	 * @brief 结束时间，单位为秒。
+	 * @type {number}
+	 */
+	/** {en}
+	 * @brief End time in seconds.
+	 * @type {number}
+	 */
+	end: number;
+	/** {zh}
+	 * @brief 字幕文案数组。
+	 * @type {string[]}
+	 */
+	/** {en}
+	 * @brief Subtitle text array.
+	 * @type {string[]}
+	 */
+	text: string[];
+	/** {zh}
+	 * @brief 字幕顺序。
+	 * @type {number}
+	 */
+	/** {en}
+	 * @brief Subtitle display order.
+	 * @type {number}
+	 */
+	index?: number;
+}
+/** {zh}
+ * @brief VePlayer 实际使用的 HLS 播放内核。
+ * @detail ref
+ */
+/** {en}
+ * @brief The HLS playback engine actually used by VePlayer.
+ * @detail ref
+ */
+export type HlsPlaybackEngine = "hlsjs" | "veplayer-hls" | "native" | "none";
+/** {zh}
+ * @brief HLS 自动码率决策引擎配置值。
+ * @detail ref
+ */
+/** {en}
+ * @brief Configurable HLS adaptive-bitrate decision engine.
+ * @detail ref
+ */
+export type HlsAbrEngine = "hlsjs" | "veplayer";
+/** {zh}
+ * @brief 当前播放会话最终解析出的自动码率决策引擎。
+ * @detail ref
+ */
+/** {en}
+ * @brief Adaptive-bitrate decision engine resolved for the current playback session.
+ * @detail ref
+ */
+export type ResolvedAbrEngine = HlsAbrEngine | "native" | "none";
+/** {zh}
+ * @brief HLS 自动码率控制模式。
+ * @detail ref
+ */
+/** {en}
+ * @brief HLS adaptive-bitrate control mode.
+ * @detail ref
+ */
+export type HlsAbrMode = "auto" | "manual";
+/** {zh}
+ * @brief 当前播放会话无法使用 HLS ABR 的原因。
+ * @detail ref
+ */
+/** {en}
+ * @brief Reason why HLS ABR is unavailable for the current playback session.
+ * @detail ref
+ */
+export type HlsAbrUnavailableReason = "NOT_HLS" | "NOT_HLSJS_ENGINE" | "MANIFEST_NOT_READY" | "MULTI_LEVEL_MASTER_REQUIRED" | "DEFINITION_LIST_REQUIRED" | "ABR_MODULE_UNAVAILABLE" | "ABR_RUNTIME_UNAVAILABLE" | "LICENSE_UNAVAILABLE" | "NO_ABR_VARIANTS";
+/** {zh}
+ * @brief 当前 HLS 播放会话支持的 ABR 能力。
+ * @detail ref
+ */
+/** {en}
+ * @brief ABR capabilities supported by the current HLS playback session.
+ * @detail ref
+ */
+export interface IHlsAbrCapabilities {
+	/** {zh} @brief 是否可读取 HLS Level 列表。 */
+	/** {en} @brief Whether the HLS Level list is available. */
+	levelList: boolean;
+	/** {zh} @brief 是否支持手动切换 HLS Level。 */
+	/** {en} @brief Whether manual HLS Level switching is supported. */
+	manualLevelSwitch: boolean;
+	/** {zh} @brief 是否支持恢复当前 ABR 引擎的自动模式。 */
+	/** {en} @brief Whether automatic mode can be restored for the resolved ABR engine. */
+	restoreAuto: boolean;
+	/** {zh} @brief 是否支持按 Level 设置自动码率上限。 */
+	/** {en} @brief Whether an automatic bitrate cap can be set by Level. */
+	levelCap: boolean;
+	/** {zh} @brief 是否支持按码率设置自动码率上限。 */
+	/** {en} @brief Whether an automatic bitrate cap can be set by bitrate. */
+	bitrateCap: boolean;
+	/** {zh} @brief 是否支持按 VePlayer 清晰度设置自动码率上限。 */
+	/** {en} @brief Whether an automatic bitrate cap can be set by VePlayer definition. */
+	definitionCap: boolean;
+}
+/** {zh}
+ * @brief 当前播放会话的 HLS ABR 状态快照。
+ * @detail ref
+ */
+/** {en}
+ * @brief HLS ABR state snapshot for the current playback session.
+ * @detail ref
+ */
+export interface IHlsAbrState {
+	/** {zh} @brief 播放会话 ID，用于识别过期状态和事件。 */
+	/** {en} @brief Playback session ID used to reject stale state and events. */
+	playbackSessionId: string;
+	/** {zh} @brief VePlayer 实际使用的 HLS 播放内核。 */
+	/** {en} @brief HLS playback engine actually used by VePlayer. */
+	playbackEngine: HlsPlaybackEngine;
+	/** {zh} @brief 业务显式配置的 ABR 引擎；未配置时为 `null`。 */
+	/** {en} @brief Explicitly configured ABR engine, or `null` when omitted. */
+	configuredEngine: HlsAbrEngine | null;
+	/** {zh} @brief 当前播放会话最终解析出的 ABR 决策引擎。 */
+	/** {en} @brief ABR decision engine resolved for the current playback session. */
+	engine: ResolvedAbrEngine;
+	/** {zh} @brief 当前清晰度决策使用的数据源。 */
+	/** {en} @brief Data source used for the current rendition decision. */
+	decisionSource: "hls-levels" | "definition-list" | "native" | "none";
+	/** {zh} @brief 当前播放会话是否具备所选 ABR 引擎所需条件。 */
+	/** {en} @brief Whether the selected ABR engine is available in the current session. */
+	available: boolean;
+	/** {zh} @brief 当前 ABR 决策引擎是否正在自动选档。 */
+	/** {en} @brief Whether the resolved ABR engine is actively selecting renditions. */
+	active: boolean;
+	/** {zh} @brief 当前为自动模式还是手动模式。 */
+	/** {en} @brief Whether the current mode is automatic or manual. */
+	mode: HlsAbrMode;
+	/** {zh} @brief hls.js 当前实际播放的 Level 索引。 */
+	/** {en} @brief Current hls.js Level index being rendered. */
+	currentLevel?: number;
+	/** {zh} @brief VePlayer ABR 当前实际播放的清晰度。 */
+	/** {en} @brief Current definition rendered by VePlayer ABR. */
+	currentDefinition?: string;
+	/** {zh} @brief ABR 不可用时的稳定原因码。 */
+	/** {en} @brief Stable reason code when ABR is unavailable. */
+	reason?: HlsAbrUnavailableReason;
+	/** {zh} @brief 当前播放会话支持的 ABR 控制能力。 */
+	/** {en} @brief ABR control capabilities supported by the current session. */
+	capabilities: IHlsAbrCapabilities;
+}
+/** {zh}
+ * @brief HLS ABR 上限；`null` 表示清除上限。
+ * @detail ref
+ */
+/** {en}
+ * @brief HLS ABR limit; `null` clears the active limit.
+ * @detail ref
+ */
+export type IHlsAbrLimit = {
+	type: "level";
+	maxLevel: number;
+} | {
+	type: "bitrate";
+	maxBitrate: number;
+} | {
+	type: "definition";
+	maxDefinition: string;
+} | null;
+/** {zh}
+ * @brief `HLS_ABR_ENGINE_RESOLVED` 事件数据。
+ * @detail ref
+ */
+/** {en}
+ * @brief Payload of the `HLS_ABR_ENGINE_RESOLVED` event.
+ * @detail ref
+ */
+export interface IHlsAbrEngineResolvedEvent extends IHlsAbrState {
+}
+/** {zh}
+ * @brief `HLS_ABR_STATE_CHANGE` 事件数据。
+ * @detail ref
+ */
+/** {en}
+ * @brief Payload of the `HLS_ABR_STATE_CHANGE` event.
+ * @detail ref
+ */
+export interface IHlsAbrStateChangeEvent extends IHlsAbrState {
+}
+/** {zh}
+ * @brief `HLS_ABR_LIMIT_CHANGE` 事件数据。
+ * @detail ref
+ */
+/** {en}
+ * @brief Payload of the `HLS_ABR_LIMIT_CHANGE` event.
+ * @detail ref
+ */
+export interface IHlsAbrLimitChangeEvent {
+	/** {zh} @brief 事件所属的播放会话 ID。 */
+	/** {en} @brief Playback session ID that owns the event. */
+	playbackSessionId: string;
+	/** {zh} @brief 当前播放会话最终解析出的 ABR 决策引擎。 */
+	/** {en} @brief ABR decision engine resolved for the current playback session. */
+	engine: ResolvedAbrEngine;
+	/** {zh} @brief 已生效的 ABR 上限；`null` 表示上限已清除。 */
+	/** {en} @brief Applied ABR limit, or `null` when the limit has been cleared. */
+	limit: IHlsAbrLimit;
+}
+/** {zh}
+ * @brief Master M3U8 中一个标准化的 HLS Level；`index` 仅在当前播放会话内有效。
+ * @detail ref
+ */
+/** {en}
+ * @brief A normalized HLS Level from a Master M3U8; `index` is valid only in the current playback session.
+ * @detail ref
+ */
+export interface IHlsLevel {
+	/** {zh} @brief 当前播放会话内的 Level 索引。 */
+	/** {en} @brief Level index within the current playback session. */
+	index: number;
+	/** {zh} @brief 峰值码率，单位为 bit/s。 */
+	/** {en} @brief Peak bitrate in bits per second. */
+	bitrate: number;
+	/** {zh} @brief 平均码率，单位为 bit/s。 */
+	/** {en} @brief Average bitrate in bits per second. */
+	averageBitrate?: number;
+	/** {zh} @brief 视频宽度，单位为像素。 */
+	/** {en} @brief Video width in pixels. */
+	width?: number;
+	/** {zh} @brief 视频高度，单位为像素。 */
+	/** {en} @brief Video height in pixels. */
+	height?: number;
+	/** {zh} @brief 视频帧率。 */
+	/** {en} @brief Video frame rate. */
+	frameRate?: number;
+	/** {zh} @brief 视频编码标识。 */
+	/** {en} @brief Video codec identifier. */
+	videoCodec?: string;
+	/** {zh} @brief 音频编码标识。 */
+	/** {en} @brief Audio codec identifier. */
+	audioCodec?: string;
+	/** {zh} @brief 视频动态范围标识。 */
+	/** {en} @brief Video dynamic-range identifier. */
+	videoRange?: string;
+	/** {zh} @brief Manifest 声明的 Level 名称。 */
+	/** {en} @brief Level name declared by the manifest. */
+	name?: string;
+}
+/** {zh}
+ * @brief HLS Level 标签映射项。
+ * @detail ref
+ */
+/** {en}
+ * @brief Mapping item used to customize an HLS Level label.
+ * @detail ref
+ */
+export interface IHlsLevelLabelItem {
+	/** {zh} @brief 当多语言 key 无法解析时使用的回退文案。 */
+	/** {en} @brief Fallback text used when the i18n key cannot be resolved. */
+	text?: string;
+	/** {zh} @brief 从播放器当前多语言词典中读取文案的 key。 */
+	/** {en} @brief Key resolved from the player's active i18n dictionary. */
+	textKey?: string;
+}
+/** {zh}
+ * @brief HLS Level 标签格式化上下文。
+ * @detail ref
+ */
+/** {en}
+ * @brief Context passed to the HLS Level label formatter.
+ * @detail ref
+ */
+export interface IHlsLevelLabelContext {
+	/** {zh} @brief 当前 Level 的只读安全快照。 */
+	/** {en} @brief Read-only safe snapshot of the current Level. */
+	level: Readonly<IHlsLevel>;
+	/** {zh} @brief 当前播放会话全部 Level 的只读安全快照。 */
+	/** {en} @brief Read-only safe snapshots of all Levels in the current playback session. */
+	levels: ReadonlyArray<Readonly<IHlsLevel>>;
+	/** {zh} @brief 视频短边像素值；Manifest 未提供分辨率时为空。 */
+	/** {en} @brief Video short edge in pixels, or undefined when dimensions are unavailable. */
+	shortEdge?: number;
+	/** {zh} @brief 未本地化、未消歧的标准标签。 */
+	/** {en} @brief Canonical label before localization and disambiguation. */
+	canonicalLabel: string;
+	/** {zh} @brief 应用 `textKey` 或 `text` 后的基础标签。 */
+	/** {en} @brief Base label after applying `textKey` or `text`. */
+	localizedLabel: string;
+	/** {zh} @brief 完成 SDK 默认重名消歧后的标签。 */
+	/** {en} @brief Label after the SDK's default duplicate disambiguation. */
+	defaultLabel: string;
+	/** {zh} @brief 播放器当前语言。 */
+	/** {en} @brief Current player language. */
+	lang: string;
+	/** {zh} @brief 当前标准标签是否在 Level 列表中重复。 */
+	/** {en} @brief Whether the canonical label is duplicated in the Level list. */
+	duplicated: boolean;
+}
+/** {zh}
+ * @brief HLS Level 标签的多语言映射与自定义格式化配置。
+ * @detail ref
+ * @example
+ * ``` javascript
+ * hlsLevelLabel: {
+ *   map: {
+ *     '720p': { textKey: 'HLS_LEVEL_HD', text: '720p' }
+ *   },
+ *   formatter: ({ defaultLabel, level }) =>
+ *     level.videoRange === 'PQ' ? `${defaultLabel} HDR` : defaultLabel
+ * }
+ * ```
+ */
+/** {en}
+ * @brief Localization mapping and custom formatter for HLS Level labels.
+ * @detail ref
+ * @example
+ * ``` javascript
+ * hlsLevelLabel: {
+ *   map: {
+ *     '720p': { textKey: 'HLS_LEVEL_HD', text: '720p' }
+ *   },
+ *   formatter: ({ defaultLabel, level }) =>
+ *     level.videoRange === 'PQ' ? `${defaultLabel} HDR` : defaultLabel
+ * }
+ * ```
+ */
+export interface IHlsLevelLabelOptions {
+	/** {zh} @brief 按标准标签（如 `720p`、`1080p`）配置展示文案。 */
+	/** {en} @brief Display-label mappings keyed by canonical labels such as `720p` and `1080p`. */
+	map?: Record<string, IHlsLevelLabelItem>;
+	/** {zh} @brief 同步格式化最终标签；返回空值或抛出异常时回退到 `defaultLabel`。 */
+	/** {en} @brief Synchronously formats the final label; empty returns or exceptions fall back to `defaultLabel`. */
+	formatter?: (context: IHlsLevelLabelContext) => string | null | undefined;
+}
+/** {zh}
+ * @brief 当前播放会话的 HLS Level 状态快照。
+ * @detail ref
+ */
+/** {en}
+ * @brief HLS Level state snapshot for the current playback session.
+ * @detail ref
+ */
+export interface IHlsLevelState {
+	/** {zh} @brief 播放会话 ID，用于识别过期状态和事件。 */
+	/** {en} @brief Playback session ID used to reject stale state and events. */
+	playbackSessionId: string;
+	/** {zh} @brief Level 列表是否已就绪。 */
+	/** {en} @brief Whether the Level list is ready. */
+	ready: boolean;
+	/** {zh} @brief 当前播放会话内的标准化 Level 列表。 */
+	/** {en} @brief Normalized Level list for the current playback session. */
+	levels: IHlsLevel[];
+	/** {zh} @brief 当前实际播放的 Level 索引，未知时为 `-1`。 */
+	/** {en} @brief Currently rendered Level index, or `-1` when unknown. */
+	currentLevel: number;
+	/** {zh} @brief 当前加载的 Level 索引，未知时为 `-1`。 */
+	/** {en} @brief Currently loaded Level index, or `-1` when unknown. */
+	loadLevel: number;
+	/** {zh} @brief 下一个分片使用的 Level 索引，未知时为 `-1`。 */
+	/** {en} @brief Level index for the next fragment, or `-1` when unknown. */
+	nextLevel: number;
+	/** {zh} @brief 手动 Level 索引；自动模式下为 `-1`。 */
+	/** {en} @brief Manual Level index; `-1` in automatic mode. */
+	manualLevel: number;
+	/** {zh} @brief hls.js 是否处于自动选档模式。 */
+	/** {en} @brief Whether hls.js automatic Level selection is enabled. */
+	autoLevelEnabled: boolean;
+	/** {zh} @brief hls.js 自动选档的 Level 上限；未设置时为 `-1`。 */
+	/** {en} @brief hls.js automatic Level cap; `-1` when unset. */
+	autoLevelCapping: number;
+}
+/** {zh}
+ * @brief HLS Level 手动切换模式。
+ * @detail ref
+ */
+/** {en}
+ * @brief Manual HLS Level switching mode.
+ * @detail ref
+ */
+export type HlsLevelSwitchMode = "immediate" | "next-fragment" | "smooth";
+/** {zh}
+ * @brief 手动切换 HLS Level 的选项。
+ * @detail ref
+ */
+/** {en}
+ * @brief Options for manually switching an HLS Level.
+ * @detail ref
+ */
+export interface IHlsLevelSwitchOptions {
+	/** {zh} @brief 切换模式，默认为 `next-fragment`。 */
+	/** {en} @brief Switching mode. Defaults to `next-fragment`. */
+	mode?: HlsLevelSwitchMode;
+	/** {zh} @brief 可选的播放会话 ID；不匹配时拒绝本次切换。 */
+	/** {en} @brief Optional playback session ID; a mismatch rejects the switch. */
+	playbackSessionId?: string;
+}
+/** {zh}
+ * @brief HLS Level 切换事件数据。
+ * @detail ref
+ */
+/** {en}
+ * @brief HLS Level switching event payload.
+ * @detail ref
+ */
+export interface IHlsLevelSwitchEvent {
+	/** {zh} @brief 事件所属的播放会话 ID。 */
+	/** {en} @brief Playback session ID that owns the event. */
+	playbackSessionId: string;
+	/** {zh} @brief 切换前的 Level 索引。 */
+	/** {en} @brief Level index before switching. */
+	from: number;
+	/** {zh} @brief 目标或已切换到的 Level 索引。 */
+	/** {en} @brief Target or switched-to Level index. */
+	to: number;
+	/** {zh} @brief 本次切换由手动操作还是 ABR 触发。 */
+	/** {en} @brief Whether the switch was triggered manually or by ABR. */
+	reason: "manual" | "abr";
+	/** {zh} @brief 当前播放会话的 ABR 决策引擎。 */
+	/** {en} @brief ABR decision engine for the current playback session. */
+	abrEngine: ResolvedAbrEngine;
+	/** {zh} @brief 目标或已生效的安全 Level 快照。 */
+	/** {en} @brief Safe snapshot of the target or active Level. */
+	level?: IHlsLevel;
+}
+/** {zh}
+ * @brief `HLS_SUBTITLE_TRACKS_UPDATED` 事件数据。
+ * @detail ref
+ */
+/** {en}
+ * @brief Payload of the `HLS_SUBTITLE_TRACKS_UPDATED` event.
+ * @detail ref
+ */
+export interface IHlsSubtitleTracksUpdatedEvent {
+	/** {zh} @brief 事件所属的播放会话 ID。 */
+	/** {en} @brief Playback session ID that owns the event. */
+	playbackSessionId: string;
+	/** {zh} @brief 当前实际使用的 HLS 播放内核。 */
+	/** {en} @brief HLS playback engine actually used by the session. */
+	playbackEngine: HlsPlaybackEngine;
+	/** {zh} @brief 不含播放地址和底层轨道索引的安全字幕列表。 */
+	/** {en} @brief Safe subtitle list without media URLs or internal track indexes. */
+	tracks: ReadonlyArray<ISubTitleItem>;
+}
+/** {zh}
+ * @brief HLS 字幕轨切换事件数据。
+ * @detail ref
+ */
+/** {en}
+ * @brief HLS subtitle-track switching event payload.
+ * @detail ref
+ */
+export interface IHlsSubtitleTrackSwitchEvent {
+	/** {zh} @brief 事件所属的播放会话 ID。 */
+	/** {en} @brief Playback session ID that owns the event. */
+	playbackSessionId: string;
+	/** {zh} @brief 当前实际使用的 HLS 播放内核。 */
+	/** {en} @brief HLS playback engine actually used by the session. */
+	playbackEngine: HlsPlaybackEngine;
+	/** {zh} @brief 切换前的安全字幕 ID；关闭状态为 `null`。 */
+	/** {en} @brief Safe subtitle ID before switching, or `null` when disabled. */
+	from: string | number | null;
+	/** {zh} @brief 目标或已生效的安全字幕 ID；关闭状态为 `null`。 */
+	/** {en} @brief Target or active safe subtitle ID, or `null` when disabled. */
+	to: string | number | null;
+	/** {zh} @brief 目标或已生效的安全字幕快照。 */
+	/** {en} @brief Safe snapshot of the target or active subtitle track. */
+	track?: ISubTitleItem;
+}
+/** {zh}
+ * @brief HLS 控制 API 的标准错误码。
+ * @detail ref
+ */
+/** {en}
+ * @brief Standard error codes for HLS control APIs.
+ * @detail ref
+ */
+export type HlsControlErrorCode = "HLS_MANIFEST_NOT_READY" | "HLS_ENGINE_UNSUPPORTED" | "HLS_LEVEL_OUT_OF_RANGE" | "HLS_PLAYBACK_SESSION_EXPIRED" | "HLS_ABR_UNAVAILABLE" | "HLS_ABR_LIMIT_UNSUPPORTED" | "HLS_SUBTITLE_TRACK_NOT_FOUND" | "HLS_SUBTITLE_TRACK_AMBIGUOUS" | "HLS_SUBTITLE_SWITCH_FAILED" | "HLS_SUBTITLE_SWITCH_TIMEOUT";
+/** {zh}
+ * @brief HLS Level、ABR 或字幕控制失败时抛出的标准错误。
+ * @detail Api
+ */
+/** {en}
+ * @brief Standard error thrown when HLS Level, ABR, or subtitle control fails.
+ * @detail Api
+ */
+export declare class HlsControlError extends Error {
+	/** {zh} @brief 稳定的 HLS 控制错误码。 */
+	/** {en} @brief Stable HLS control error code. */
+	readonly code: HlsControlErrorCode;
+	constructor(code: HlsControlErrorCode, message: string);
+}
+/** {zh}
+ * @list Options
+ * @brief 自适应码率配置。
+ * @kind property
+ */
+/** {en}
+ * @list Options
+ * @brief Adaptive bitrate (ABR) playback configuration.
+ * @kind property
+ */
+export interface IAutoBitrateOpts {
+	/** {zh}
+	 * @brief 是否开启自适应码率功能。
+	 * @default false
+	 */
+	/** {en}
+	 * @brief Whether to enable adaptive bitrate (ABR).
+	 * @default false
+	 */
+	enable: boolean;
+	/** {zh}
+	 * @brief HLS 自动码率决策引擎。仅对 HLS 生效；开启 ABR 但不设置时，为兼容旧版本使用 VePlayer ABR。
+	 * @default veplayer
+	 */
+	/** {en}
+	 * @brief HLS adaptive-bitrate decision engine. Applies only to HLS; when ABR is enabled and this field is omitted, VePlayer ABR is used for backward compatibility.
+	 * @default veplayer
+	 */
+	engine?: HlsAbrEngine;
+	/** {zh}
+	 * @brief 是否以自动清晰度档位起播。开启自适应码率功能且 `defaultDefinition` 为 `auto` 时，才会以自动清晰度档位起播。
+	 * @default false
+	 */
+	/** {en}
+	 * @brief Whether to start playback with the auto definition level. Takes effect only when ABR is enabled and `defaultDefinition` is `auto`.
+	 * @default false
+	 */
+	startWithAuto?: boolean;
+	/** {zh}
+	 * @brief 自动清晰度档位是否展示当前实际清晰度，如自动（720p）。
+	 * @default false
+	 */
+	/** {en}
+	 * @brief Whether the auto definition label shows the actual resolution, e.g. Auto (720p).
+	 * @default false
+	 */
+	showRealDefinition?: boolean;
+	/** {zh}
+	 * @brief 自动清晰度档位的显示文案。
+	 * @default 自动
+	 */
+	/** {en}
+	 * @brief Display text for the auto definition level.
+	 * @default auto
+	 */
+	autoDefinitionText?: string;
+	/** {zh}
+	 * @brief 自动清晰度档位的多语言 key。
+	 * @default DEFINITION_AUTO
+	 */
+	/** {en}
+	 * @brief i18n key for the auto definition level label.
+	 * @default DEFINITION_AUTO
+	 */
+	definitionTextKey?: string;
+	/**
+	 * @hidden
+	 * @brief 软解module
+	 */
+	module?: unknown;
+}
+interface AudioTrackOption {
+	/** {zh}
+	 * @brief 音轨主要语言，BCP-47 格式（如 `zh`、`en`）。对应 `#EXT-X-MEDIA` 的 `LANGUAGE`。
+	 */
+	/** {en}
+	 * @brief Primary track language in BCP-47 format (e.g. `zh`, `en`). Maps to `#EXT-X-MEDIA` `LANGUAGE`.
+	 */
+	lang?: string;
+	/** {zh}
+	 * @brief 关联语言代码。对应 `#EXT-X-MEDIA` 的 `ASSOC-LANGUAGE`。
+	 */
+	/** {en}
+	 * @brief Associated language code. Maps to `#EXT-X-MEDIA` `ASSOC-LANGUAGE`.
+	 */
+	assocLang?: string;
+	/** {zh}
+	 * @brief 轨道特征描述字符串。对应 `#EXT-X-MEDIA` 的 `CHARACTERISTICS`（如 `public.accessibility.describes-video`）。
+	 */
+	/** {en}
+	 * @brief Track characteristics string. Maps to `#EXT-X-MEDIA` `CHARACTERISTICS`.
+	 */
+	characteristics?: string;
+	/** {zh}
+	 * @brief 声道数。对应 `#EXT-X-MEDIA` 的 `CHANNELS`（如 `"2"`）。
+	 */
+	/** {en}
+	 * @brief Number of audio channels. Maps to `#EXT-X-MEDIA` `CHANNELS` (e.g. `"2"`).
+	 */
+	channels?: string;
+	/** {zh}
+	 * @brief 音轨名称，用于展示或精确匹配（如 `Stereo`）。hls.js 路径下与 `lang` 组合可唯一定位轨道。
+	 */
+	/** {en}
+	 * @brief Track name for display or precise matching (e.g. `Stereo`). With `lang`, uniquely identifies a track on the hls.js path.
+	 */
+	name?: string;
+	/** {zh}
+	 * @brief 音频编解码器标识（如 `mp4a.40.2`）。
+	 */
+	/** {en}
+	 * @brief Audio codec identifier (e.g. `mp4a.40.2`).
+	 */
+	audioCodec?: string;
+	/** {zh}
+	 * @brief 音频组 ID。对应 `#EXT-X-MEDIA` 的 `GROUP-ID`。
+	 */
+	/** {en}
+	 * @brief Audio group ID. Maps to `#EXT-X-MEDIA` `GROUP-ID`.
+	 */
+	groupId?: string;
+	/** {zh}
+	 * @brief 是否为 manifest 中的默认音轨。
+	 */
+	/** {en}
+	 * @brief Whether this is the default track declared in the manifest.
+	 */
+	default?: boolean;
+	/** {zh}
+	 * @hidden
+	 */
+	/** {en}
+	 * @hidden
+	 */
+	[key: string]: unknown;
+}
 /** Video and audio codec names supported by the player. */
 export declare const CodecType: {
 	readonly H264: "h264";
@@ -71,6 +957,9 @@ export declare const enum POSITIONS {
 /** Public event-name map shared by Lite and Full UMD constructors. */
 export interface LiteEvents {
 	readonly READY: "ready";
+	readonly HLS_LEVEL_SWITCHING: "hls_level_switching";
+	readonly HLS_LEVEL_SWITCHED: "hls_level_switched";
+	readonly HLS_ABR_LIMIT_CHANGE: "hls_abr_limit_change";
 	readonly [eventName: string]: string;
 }
 /** Legacy grouped event-name map. */
@@ -204,6 +1093,7 @@ export interface LitePlayerPlaybackStateSnapshot {
 	isBeforePlayerCreate: boolean;
 	albumId: string | null;
 	episodeId: string | null;
+	vid: string | null;
 	playbackSessionId: string;
 	duration: number;
 	currentTime: number;
@@ -334,6 +1224,19 @@ export interface LiteTTDramaEnv {
 	getDramaInfo: (callback: (res: LiteDramaInfoResponse) => void, options: LiteDramaInfoRequest) => void;
 	videoSecurityModule?: unknown;
 	sendLog: (eventName: string, params: Record<string, unknown>) => void;
+	/** {zh}
+	 * @hidden
+	 * @brief 当前在播短剧身份变化通知，由宿主集成层消费。
+	 */
+	/** {en}
+	 * @hidden
+	 * @brief Notifies the host integration when the current drama playback identity changes.
+	 */
+	onCurrentDramaPlaybackContextChange?: (context: {
+		albumId: string | null;
+		episodeId: string | null;
+		vid: string | null;
+	} | null) => boolean | void;
 	getTokenVerifySecret?: () => Promise<string>;
 }
 export interface LiteDefaultConfig {
@@ -371,8 +1274,11 @@ export interface LiteStream<MediaUrl extends LiteMediaUrl = LiteMediaUrl> {
 }
 export interface LiteSubtitleConfig {
 	list?: LiteSubtitleItem[];
+	label?: ISubtitleLabelOptions;
 	defaultSubtitleId?: string | number;
 	defaultSubtitleLanguage?: string | number;
+	mode?: "external" | "native";
+	nativeRenderMode?: "system" | "dom";
 	updateMode?: "vod";
 	[key: string]: unknown;
 }
@@ -533,9 +1439,13 @@ export interface LitePlayerConfig<MediaUrl extends LiteMediaUrl = LiteMediaUrl,
 	mobile?: LiteMobileConfig;
 	start?: LiteStartConfig;
 	enableHlsMSE?: boolean;
+	enableMobileHlsPlugin?: boolean;
+	enableHlsJs?: boolean;
+	hlsLevelSwitchMode?: HlsLevelSwitchMode;
 	useHlsPluginForSafari?: boolean;
 	enableMp4MSE?: boolean;
 	defaultDefinition?: string;
+	audioPreference?: AudioTrackOption;
 	plugins?: unknown[];
 	presets?: unknown[];
 	ignores?: string[];
@@ -590,9 +1500,13 @@ export interface LiteDefinition {
 export interface LiteSubtitleItem {
 	id?: string | number;
 	language?: string | number;
-	label?: string | number;
-	text?: string;
+	label?: ISubtitleLabelValue;
+	text?: ISubtitleLabelValue;
 	url?: string;
+	isDefault?: boolean;
+	source?: "config" | "hls";
+	forced?: boolean;
+	characteristics?: string;
 }
 export interface LitePluginInstance {
 	readonly pluginName?: string;
@@ -601,6 +1515,11 @@ export interface LitePluginConstructor<Instance extends LitePluginInstance = Lit
 	readonly pluginName?: string;
 	new (...args: unknown[]): Instance;
 }
+type LiteHlsEventPayloadMap = {
+	hls_abr_limit_change: IHlsAbrLimitChangeEvent;
+	hls_level_switching: IHlsLevelSwitchEvent;
+	hls_level_switched: IHlsLevelSwitchEvent;
+};
 export interface LiteVePlayer {
 	readonly preLoadData: {
 		hit: number;
@@ -615,6 +1534,10 @@ export interface LiteVePlayer {
 	emit(action: string, payload?: unknown): void;
 	getCurrentPlayerConfig(): LiteDefaultConfig;
 	getDefinitionList(): LiteDefinition[];
+	getHlsAbrLimit(): IHlsAbrLimit;
+	getHlsAbrState(): IHlsAbrState;
+	getHlsLevels(): IHlsLevel[];
+	getHlsLevelState(): IHlsLevelState;
 	getLogUserId(): string | undefined;
 	getPlayerInstance(): unknown;
 	getPlugin(pluginName: string): LitePluginInstance | null;
@@ -623,10 +1546,14 @@ export interface LiteVePlayer {
 	hideSubtitle(): void;
 	next<MediaUrl extends LiteMediaUrl, StreamUrl extends LiteMediaUrl>(config: LitePlayerConfig<MediaUrl, StreamUrl>, isNewVideo?: boolean): Promise<void>;
 	off(action: string, func: (...args: unknown[]) => void): void;
+	on<EventName extends keyof LiteHlsEventPayloadMap>(action: EventName, func: (payload: LiteHlsEventPayloadMap[EventName]) => void): void;
 	on(action: string, func: (...args: unknown[]) => void): void;
 	once(action: string, func: (...args: unknown[]) => void): void;
 	playNext<MediaUrl extends LiteMediaUrl, StreamUrl extends LiteMediaUrl>(config: LitePlayerConfig<MediaUrl, StreamUrl>, isNewVideo?: boolean): Promise<unknown>;
 	showSubtitle(): void;
+	setHlsAbrLimit(limit: IHlsAbrLimit): void;
+	setHlsAbrMode(mode: HlsAbrMode): void;
+	setHlsLevel(levelIndex: number, options?: IHlsLevelSwitchOptions): void;
 	switchAuthToken(config: LitePlayAuthTokenConfig, isNewVideo?: boolean): Promise<void>;
 	switchSubtitle(subtitle: {
 		id?: string | number;