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

package/index.d.ts

@@ -546,6 +546,45 @@ export interface ISubtitleConfig {
 	 * @default -
 	 */
 	list?: Array<ISubTitleItem>;
+	/** {zh}
+	 * @brief 字幕选择项的多语言映射与自定义格式化配置。
+	 * @notes 同时作用于业务配置字幕、Vid/PlayAuth 或短剧自动字幕，以及 Master M3U8 字幕。仅改变 VePlayer 字幕菜单文案，不改变字幕 ID、切换和渲染行为。iOS 系统字幕菜单不受此配置影响。
+	 * @default -
+	 * @example
+	 * ``` javascript
+	 * Subtitle: {
+	 *   label: {
+	 *     map: {
+	 *       language: {
+	 *         en: { textKey: 'SUBTITLE_EN', text: 'English' }
+	 *       }
+	 *     },
+	 *     formatter: ({ defaultLabel, item }) =>
+	 *       item.forced ? `${defaultLabel} · Forced` : defaultLabel
+	 *   }
+	 * }
+	 * ```
+	 */
+	/** {en}
+	 * @brief Localization mapping and custom formatter for subtitle option labels.
+	 * @notes Applies to business-configured subtitles, Vid/PlayAuth or short-drama automatic subtitles, and Master M3U8 subtitles. It only changes labels in VePlayer subtitle menus; subtitle IDs, switching, and rendering are unchanged. The iOS system subtitle menu is not affected.
+	 * @default -
+	 * @example
+	 * ``` javascript
+	 * Subtitle: {
+	 *   label: {
+	 *     map: {
+	 *       language: {
+	 *         en: { textKey: 'SUBTITLE_EN', text: 'English' }
+	 *       }
+	 *     },
+	 *     formatter: ({ defaultLabel, item }) =>
+	 *       item.forced ? `${defaultLabel} · Forced` : defaultLabel
+	 *   }
+	 * }
+	 * ```
+	 */
+	label?: ISubtitleLabelOptions;
 	/** {zh}
 	 * @brief 是否默认打开字幕。
 	 * @default true
@@ -577,6 +616,19 @@ export interface ISubtitleConfig {
 	 * @default external
 	 */
 	mode?: "external" | "native";
+	/** {zh}
+	 * @brief 原生字幕渲染方式。仅当 `mode` 为 `native` 且使用 iOS 原生 HLS 时生效：
+	 *        - `"system"`：由系统渲染字幕。
+	 *        - `"dom"`：内联播放时由 VePlayer 使用 DOM 渲染；原生全屏、画中画或远程播放时自动回退到系统渲染。
+	 * @default system
+	 */
+	/** {en}
+	 * @brief Native subtitle rendering mode. It only applies to iOS native HLS when `mode` is `native`:
+	 *        - `"system"`: render subtitles with the system UI.
+	 *        - `"dom"`: render subtitles in the VePlayer DOM during inline playback and fall back to system rendering in native fullscreen, picture-in-picture, or remote playback.
+	 * @default system
+	 */
+	nativeRenderMode?: "system" | "dom";
 	/**
 	 * @brief 字幕更新模式，默认vod
 	 * @default vod
@@ -769,6 +821,15 @@ export interface ISubtitleStyle {
  * @kind property
  */
 export 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 -
@@ -796,6 +857,24 @@ export interface ISubTitleItem {
 	 * @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 -
@@ -804,7 +883,7 @@ export interface ISubTitleItem {
 	 * @brief Subtitle display name.
 	 * @default -
 	 */
-	text?: string;
+	text?: ISubtitleLabelValue;
 	/** {zh}
 	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
 	 * @default -
@@ -813,7 +892,7 @@ export interface ISubTitleItem {
 	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
 	 * @default -
 	 */
-	label?: string | number;
+	label?: ISubtitleLabelValue;
 	/** {zh}
 	 * @brief 外挂字幕 URL 地址。
 	 * @default -
@@ -843,6 +922,118 @@ export interface 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 declare 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;
+}
 export declare type IAutoSubtitleSourceItem = Record<string, any> | string;
 export declare type IAutoSubtitleFormatterResult = string | number | boolean | null | undefined | {
 	label?: string | number;
@@ -3428,6 +3619,465 @@ export interface IVideoInfo {
 		Data: IGetPlayInfoRes;
 	};
 }
+/** {zh}
+ * @brief VePlayer 实际使用的 HLS 播放内核。
+ * @detail ref
+ */
+/** {en}
+ * @brief The HLS playback engine actually used by VePlayer.
+ * @detail ref
+ */
+export declare type HlsPlaybackEngine = "hlsjs" | "veplayer-hls" | "native" | "none";
+/** {zh}
+ * @brief HLS 自动码率决策引擎配置值。
+ * @detail ref
+ */
+/** {en}
+ * @brief Configurable HLS adaptive-bitrate decision engine.
+ * @detail ref
+ */
+export declare type HlsAbrEngine = "hlsjs" | "veplayer";
+/** {zh}
+ * @brief 当前播放会话最终解析出的自动码率决策引擎。
+ * @detail ref
+ */
+/** {en}
+ * @brief Adaptive-bitrate decision engine resolved for the current playback session.
+ * @detail ref
+ */
+export declare type ResolvedAbrEngine = HlsAbrEngine | "native" | "none";
+/** {zh}
+ * @brief HLS 自动码率控制模式。
+ * @detail ref
+ */
+/** {en}
+ * @brief HLS adaptive-bitrate control mode.
+ * @detail ref
+ */
+export declare 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 declare 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 declare 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 declare 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 declare 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);
+}
 export declare type TAPIRegionConfig = {
 	__PLAY_DOMAIN__: string;
 	__BACKUP_PLAY_DOMAIN__?: string;
@@ -4699,6 +5349,7 @@ export interface IPlayerConfig extends IPlayerOptions {
 	 * - **Android**：直接启用 hls.js 播放。
 	 * - **iOS**：仅在设备支持 `ManagedMediaSource`（iOS 17.1+，即 `VePlayer.isMMSSupported()` 为 `true`）时启用；
 	 *   不满足时自动回退至原生 HLS 播放。
+	 * - **`isMobile` 模拟模式**：当前浏览器支持 MSE 或 MMS 时启用 hls.js。
 	 * 开启后可在移动端解锁多音轨切换、`setAudioOption` 偏好持久化等 hls.js 特有能力。
 	 * @default false
 	 */
@@ -4707,13 +5358,82 @@ export interface IPlayerConfig extends IPlayerOptions {
 	 * - **Android**: always enables hls.js.
 	 * - **iOS**: enables hls.js only when `ManagedMediaSource` is supported (iOS 17.1+,
 	 *   i.e. `VePlayer.isMMSSupported()` returns `true`); falls back to native HLS otherwise.
+	 * - **`isMobile` simulation**: enables hls.js when the current browser supports MSE or MMS.
 	 * Unlocks hls.js-specific features such as multi-audio-track switching on mobile.
 	 * @default false
 	 */
 	enableMobileHlsPlugin?: boolean;
 	/** {zh}
-	 * @brief 是否启用 {@link https://hlsjs.video-dev.org/ hls.js} 插件播放HLS视频，默认为true，设置为false后，PC端播放HLS使用自研hls插件播放HLS视频
-	 * @default true
+	 * @brief 清晰度插件手动切换 HLS Level 时使用的切换模式。
+	 * @notes 仅在 hls.js/MSE/MMS 模式下生效；默认值为 `next-fragment`。直接调用 `setHlsLevel()` 时，以方法参数中的 `mode` 为准。
+	 * @default next-fragment
+	 * @example
+	 * ``` javascript
+	 * const playerSdkIns = new VePlayer({
+	 *   hlsLevelSwitchMode: 'smooth'
+	 * });
+	 * ```
+	 */
+	/** {en}
+	 * @brief Switching mode used when the quality plugin manually selects an HLS Level.
+	 * @notes Effective only in hls.js/MSE/MMS mode. Defaults to `next-fragment`. A `mode` passed directly to `setHlsLevel()` takes precedence for that call.
+	 * @default next-fragment
+	 * @example
+	 * ``` javascript
+	 * const playerSdkIns = new VePlayer({
+	 *   hlsLevelSwitchMode: 'smooth'
+	 * });
+	 * ```
+	 */
+	hlsLevelSwitchMode?: HlsLevelSwitchMode;
+	/** {zh}
+	 * @brief Master M3U8 的 HLS Level 标签多语言映射与自定义格式化配置。
+	 * @notes 仅影响内置清晰度插件的展示文案，不改变 Level 索引、切档行为或 ABR 决策。映射 key 为视频短边生成的标准标签，例如 `720p`、`1080p`。
+	 * @default -
+	 * @example
+	 * ``` javascript
+	 * const playerSdkIns = new VePlayer({
+	 *   lang: 'zh',
+	 *   languages: {
+	 *     zh: { HLS_LEVEL_HD: '高清' },
+	 *     en: { HLS_LEVEL_HD: 'HD' }
+	 *   },
+	 *   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 Master M3U8 HLS Level labels.
+	 * @notes Only changes labels rendered by the built-in quality plugin. It does not change Level indices, switching behavior, or ABR decisions. Mapping keys are canonical short-edge labels such as `720p` and `1080p`.
+	 * @default -
+	 * @example
+	 * ``` javascript
+	 * const playerSdkIns = new VePlayer({
+	 *   lang: 'en',
+	 *   languages: {
+	 *     zh: { HLS_LEVEL_HD: '高清' },
+	 *     en: { HLS_LEVEL_HD: 'HD' }
+	 *   },
+	 *   hlsLevelLabel: {
+	 *     map: {
+	 *       '720p': { textKey: 'HLS_LEVEL_HD', text: '720p' }
+	 *     },
+	 *     formatter: ({ defaultLabel, level }) =>
+	 *       level.videoRange === 'PQ' ? `${defaultLabel} HDR` : defaultLabel
+	 *   }
+	 * });
+	 * ```
+	 */
+	hlsLevelLabel?: IHlsLevelLabelOptions;
+	/** {zh}
+	 * @brief 是否启用 {@link https://hlsjs.video-dev.org/ hls.js} 插件播放HLS视频，默认为true，设置为false后，PC端播放HLS使用自研hls插件播放HLS视频
+	 * @default true
 	 */
 	/** {en}
 	 * @brief Whether to use the {@link https://hlsjs.video-dev.org/ hls.js} plugin for HLS playback on PC. When `false`, the built-in HLS adapter is used instead.
@@ -6588,6 +7308,238 @@ declare abstract class AbstractBaseAdapter {
 	abstract getPlugins(umdLoader: UMDLoader): Promise<XGPlugin[]>;
 	abstract setPluginConfigInVid(videoInfo: IVideoInfo, context: AuthToken): void;
 }
+/** {zh}
+ * @list Options
+ * @brief 字幕项。
+ * @kind property
+ */
+/** {en}
+ * @list Options
+ * @brief Subtitle item.
+ * @kind property
+ */
+export 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 字幕内容项。
+ * @list Options
+ * @kind property
+ * @export
+ * @interface IListItem
+ */
+/** {en}
+ * @brief Subtitle content item.
+ * @list Options
+ * @kind property
+ * @export
+ * @interface IListItem
+ */
+export 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;
+}
+/** {zh}
+ * @brief 字幕文案配置。
+ * @list Options
+ * @kind property
+ */
+/** {en}
+ * @brief Subtitle text item configuration.
+ * @list Options
+ * @kind property
+ */
+export 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 HLS 自动码率决策引擎配置值。
+ * @detail ref
+ */
+/** {en}
+ * @brief Configurable HLS adaptive-bitrate decision engine.
+ * @detail ref
+ */
+export type HlsAbrEngine = "hlsjs" | "veplayer";
+export type TLogChannel = "cn" | "va" | "sg";
 declare class PlayerData {
 	id?: string;
 	root?: HTMLElement;
@@ -6689,6 +7641,8 @@ declare class PlayerData {
 	 */
 	getCurrentStreamType(): string;
 	getStreamType(): string;
+	getConfiguredHlsAbrEngine(): HlsAbrEngine;
+	isOpenVePlayerABR(): boolean;
 	isOpenABR(): boolean;
 	showRealDefinition(): boolean;
 	isAutoDefinition(def: any): boolean;
@@ -7063,205 +8017,18 @@ export declare type IMediaInfoPrefetchFailure = {
 export declare type IMediaInfoPrefetchResult = IMediaInfoPrefetchSuccess | IMediaInfoPrefetchFailure;
 export declare type IPreloadStream = IPreloadResolvedStream | IPreloadDramaStream | IPreloadAuthTokenStream;
 /** {zh}
- * @list Options
- * @brief 字幕项。
- * @kind property
+ * @hidden
+ * h265策略配置
+ * @detail Options
  */
 /** {en}
- * @list Options
- * @brief Subtitle item.
- * @kind property
+ * @hidden
+ * @brief H.265 strategy configuration.
+ * @detail Options
  */
-export interface ISubTitleItem {
+export declare type IH265Config = {
 	/** {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 -
-	 */
-	/** {en}
-	 * @brief Subtitle display name.
-	 * @default -
-	 */
-	text?: string;
-	/** {zh}
-	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
-	 * @default -
-	 */
-	/** {en}
-	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
-	 * @default -
-	 */
-	label?: string | number;
-	/** {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 字幕内容项。
- * @list Options
- * @kind property
- * @export
- * @interface IListItem
- */
-/** {en}
- * @brief Subtitle content item.
- * @list Options
- * @kind property
- * @export
- * @interface IListItem
- */
-export 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;
-}
-/** {zh}
- * @brief 字幕文案配置。
- * @list Options
- * @kind property
- */
-/** {en}
- * @brief Subtitle text item configuration.
- * @list Options
- * @kind property
- */
-export 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;
-}
-export type TLogChannel = "cn" | "va" | "sg";
-/** {zh}
- * @hidden
- * h265策略配置
- * @detail Options
- */
-/** {en}
- * @hidden
- * @brief H.265 strategy configuration.
- * @detail Options
- */
-export declare type IH265Config = {
-	/** {zh}
-	 * @brief h265策略依赖Module
+	 * @brief h265策略依赖Module
 	 */
 	/** {en}
 	 * @brief H.265 strategy dependency module.
@@ -7757,6 +8524,14 @@ declare class VePlayer {
 	 * @memberof VePlayer
 	 */
 	private _emitter;
+	/** @hidden 当前播放内核对应的 Master M3U8 Level 控制器。 */
+	private _hlsMasterController;
+	/** @hidden 当前播放内核对应的 Master M3U8 字幕适配器。 */
+	private _hlsSubtitleAdapter;
+	/** @hidden 当前播放世代中业务显式配置的字幕列表快照。 */
+	private _explicitSubtitleListSnapshot;
+	/** @hidden 在播放会话提交后刷新 Level 快照与事件归属。 */
+	private _hlsMasterRefreshListener?;
 	/** 最近一次用户选择的音轨，用于清晰度切换后通过 setAudioOption 恢复音轨 */
 	private _lastSelectedAudioTrack;
 	/**
@@ -8315,6 +9090,14 @@ declare class VePlayer {
 	 * @memberof VePlayer
 	 */
 	afterPlayerCreate(): void;
+	/** @hidden 为当前播放内核挂载会话隔离的 Master M3U8 Level 控制器。 */
+	private _mountHlsMasterController;
+	/** @hidden 为当前 hls.js 播放会话挂载安全的 Master 字幕适配器。 */
+	private _mountHlsSubtitleAdapter;
+	/** @hidden 克隆业务字幕策略，避免由运行时注入列表反推来源。 */
+	private _cloneExplicitSubtitleList;
+	/** @hidden 返回稳定的 Level 会话刷新监听器，便于销毁时精确解绑。 */
+	private _getHlsMasterRefreshListener;
 	_setVeError(): void;
 	/**
 	 * @hidden
@@ -8629,12 +9412,177 @@ declare class VePlayer {
 	/** {en}
 	 * @brief Get the definition list. Each item has `definition`, `url`, and `selected` (true for the active level).
 	 */
-	getDefinitionList(): Array<{
-		definition: string;
-		url: IUrl;
-		selected: boolean;
-		[propName: string]: any;
-	}>;
+	getDefinitionList(): Array<{
+		definition: string;
+		url: IUrl;
+		selected: boolean;
+		[propName: string]: any;
+	}>;
+	/** {zh}
+	 * @brief 获取当前播放会话中由 Master M3U8 解析出的 HLS Level 列表。
+	 * @list Api
+	 * @returns 标准化后的 HLS Level 快照；Manifest 未就绪或当前不是 hls.js 内核时返回空数组。
+	 * @notes Level 的 `index` 只在当前 `playbackSessionId` 内有效；返回结果不包含播放地址和鉴权信息。
+	 * @example
+	 * ``` javascript
+	 * const levels = playerSdkIns.getHlsLevels();
+	 * console.log(levels.map(level => `${level.height}p`));
+	 * ```
+	 */
+	/** {en}
+	 * @brief Get HLS Levels parsed from the Master M3U8 for the current playback session.
+	 * @list Api
+	 * @returns A normalized HLS Level snapshot. Returns an empty array before the manifest is ready or when hls.js is not the active engine.
+	 * @notes A Level `index` is valid only for the current `playbackSessionId`. Playback URLs and authorization data are never returned.
+	 * @example
+	 * ``` javascript
+	 * const levels = playerSdkIns.getHlsLevels();
+	 * console.log(levels.map(level => `${level.height}p`));
+	 * ```
+	 */
+	getHlsLevels(): IHlsLevel[];
+	/** {zh}
+	 * @brief 获取当前播放会话的 HLS Level 状态。
+	 * @list Api
+	 * @returns HLS Level 状态快照，包含列表就绪状态、实际档位、手动档位和自动选档上限。
+	 * @notes `READY` 事件不表示 Level 列表已经就绪；请检查返回值的 `ready`，或监听 `HLS_LEVELS_UPDATED`。
+	 * @example
+	 * ``` javascript
+	 * const state = playerSdkIns.getHlsLevelState();
+	 * if (state.ready) {
+	 *   console.log(state.currentLevel, state.autoLevelEnabled);
+	 * }
+	 * ```
+	 */
+	/** {en}
+	 * @brief Get HLS Level state for the current playback session.
+	 * @list Api
+	 * @returns An HLS Level state snapshot including readiness, active and manual Levels, and the automatic Level cap.
+	 * @notes The `READY` event does not mean the Level list is ready. Check `ready` or listen for `HLS_LEVELS_UPDATED`.
+	 * @example
+	 * ``` javascript
+	 * const state = playerSdkIns.getHlsLevelState();
+	 * if (state.ready) {
+	 *   console.log(state.currentLevel, state.autoLevelEnabled);
+	 * }
+	 * ```
+	 */
+	getHlsLevelState(): IHlsLevelState;
+	/** {zh}
+	 * @brief 手动切换当前 Master M3U8 的 HLS Level。
+	 * @list Api
+	 * @param levelIndex 目标 Level 索引，可通过 `getHlsLevels()` 获取。
+	 * @param options 切换模式和可选的播放会话 ID。
+	 * @notes 调用后进入手动选档。目标提交时触发 `HLS_LEVEL_SWITCHING`，实际生效后触发 `HLS_LEVEL_SWITCHED`。Manifest 未就绪、内核不支持、索引越界或会话过期时抛出 {@link HlsControlError}。
+	 * @example
+	 * ``` javascript
+	 * const state = playerSdkIns.getHlsLevelState();
+	 * playerSdkIns.setHlsLevel(1, {
+	 *   mode: 'next-fragment',
+	 *   playbackSessionId: state.playbackSessionId
+	 * });
+	 * ```
+	 */
+	/** {en}
+	 * @brief Manually switch the HLS Level in the current Master M3U8.
+	 * @list Api
+	 * @param levelIndex Target Level index from `getHlsLevels()`.
+	 * @param options Switching mode and optional playback session ID.
+	 * @notes Calling this method enters manual Level selection. `HLS_LEVEL_SWITCHING` fires when submitted, and `HLS_LEVEL_SWITCHED` fires after it takes effect. A {@link HlsControlError} is thrown when the manifest is not ready, the engine is unsupported, the index is invalid, or the session has expired.
+	 * @example
+	 * ``` javascript
+	 * const state = playerSdkIns.getHlsLevelState();
+	 * playerSdkIns.setHlsLevel(1, {
+	 *   mode: 'next-fragment',
+	 *   playbackSessionId: state.playbackSessionId
+	 * });
+	 * ```
+	 */
+	setHlsLevel(levelIndex: number, options?: IHlsLevelSwitchOptions): void;
+	/** {zh}
+	 * @brief 获取当前播放会话的 HLS ABR 引擎、模式、可用性和控制能力。
+	 * @list Api
+	 * @returns 当前 HLS ABR 状态快照。
+	 * @notes `engine` 是实际解析出的决策引擎；`configuredEngine` 只表示已生效的显式配置。请使用 `decisionSource` 决定清晰度 UI 展示 Level 还是 Definition。
+	 * @example
+	 * ``` javascript
+	 * const state = playerSdkIns.getHlsAbrState();
+	 * console.log(state.engine, state.mode, state.decisionSource);
+	 * ```
+	 */
+	/** {en}
+	 * @brief Get the HLS ABR engine, mode, availability, and capabilities for the current playback session.
+	 * @list Api
+	 * @returns The current HLS ABR state snapshot.
+	 * @notes `engine` is the resolved decision engine, while `configuredEngine` only represents an effective explicit configuration. Use `decisionSource` to choose Levels or Definitions in a quality UI.
+	 * @example
+	 * ``` javascript
+	 * const state = playerSdkIns.getHlsAbrState();
+	 * console.log(state.engine, state.mode, state.decisionSource);
+	 * ```
+	 */
+	getHlsAbrState(): IHlsAbrState;
+	/** {zh}
+	 * @brief 设置当前播放会话的 HLS ABR 自动或手动模式。
+	 * @list Api
+	 * @param mode ABR 模式。
+	 * @notes 设置为 `auto` 时恢复当前已解析出的 ABR 引擎，不保证固定使用 hls.js。设置为 `manual` 本身不选择档位，需配合 `setHlsLevel()` 或 Definition API。
+	 * @example
+	 * ``` javascript
+	 * playerSdkIns.setHlsAbrMode('auto');
+	 * ```
+	 */
+	/** {en}
+	 * @brief Set automatic or manual HLS ABR mode for the current playback session.
+	 * @list Api
+	 * @param mode ABR mode.
+	 * @notes `auto` restores the resolved ABR engine and does not necessarily select hls.js. `manual` does not select a rendition by itself; use `setHlsLevel()` or a Definition API afterwards.
+	 * @example
+	 * ``` javascript
+	 * playerSdkIns.setHlsAbrMode('auto');
+	 * ```
+	 */
+	setHlsAbrMode(mode: HlsAbrMode): void;
+	/** {zh}
+	 * @brief 获取当前播放会话已设置的 HLS ABR 上限。
+	 * @list Api
+	 * @returns 当前上限的副本；未设置时返回 `null`。
+	 * @example
+	 * ``` javascript
+	 * console.log(playerSdkIns.getHlsAbrLimit());
+	 * ```
+	 */
+	/** {en}
+	 * @brief Get the HLS ABR limit configured for the current playback session.
+	 * @list Api
+	 * @returns A copy of the current limit, or `null` when no limit is set.
+	 * @example
+	 * ``` javascript
+	 * console.log(playerSdkIns.getHlsAbrLimit());
+	 * ```
+	 */
+	getHlsAbrLimit(): IHlsAbrLimit;
+	/** {zh}
+	 * @brief 设置或清除当前播放会话的 HLS ABR 上限。
+	 * @list Api
+	 * @param limit Level、码率或 Definition 上限；传入 `null` 清除上限。
+	 * @notes 是否支持某种上限取决于 `getHlsAbrState().capabilities`；无法安全映射时抛出 {@link HlsControlError}，原上限保持不变。
+	 * @example
+	 * ``` javascript
+	 * playerSdkIns.setHlsAbrLimit({ type: 'bitrate', maxBitrate: 2500000 });
+	 * ```
+	 */
+	/** {en}
+	 * @brief Set or clear the HLS ABR limit for the current playback session.
+	 * @list Api
+	 * @param limit A Level, bitrate, or Definition cap. Pass `null` to clear it.
+	 * @notes Supported limit kinds are reported by `getHlsAbrState().capabilities`. A {@link HlsControlError} is thrown when a limit cannot be mapped safely, and the previous limit remains unchanged.
+	 * @example
+	 * ``` javascript
+	 * playerSdkIns.setHlsAbrLimit({ type: 'bitrate', maxBitrate: 2500000 });
+	 * ```
+	 */
+	setHlsAbrLimit(limit: IHlsAbrLimit): void;
 	/** {zh}
 	 * @brief 获取音频轨道列表。HLS 流通过 hls.js 获取，iOS 原生播放通过 HTMLMediaElement.audioTracks 获取。
 	 * @notes 每项包含 `id`、`name`、`lang`、`channels`、`default`、`selected` 字段；轨道数量 ≤ 1 时返回空数组。
@@ -8910,16 +9858,51 @@ declare class VePlayer {
 	 */
 	getPlugin(pluginName: string): null | BasePlugin;
 	/** {zh}
-	 * @brief 获取字幕列表。需配置 `Subtitle` 插件后调用。
-	 * @return 当前字幕列表，每项包含 `id`、`language`、`text`（显示名称）等字段。列表为空时返回空数组。
-	 * @memberof VePlayer
+	 * @brief 获取当前字幕列表。
+	 * @list Api
+	 * @returns 当前字幕列表的副本；未注册 `Subtitle` 插件或列表未就绪时返回空数组。
+	 * @notes Master M3U8 字幕项的 `source` 为 `hls`，不包含播放地址或底层轨道索引；业务显式配置的非空字幕列表优先。
+	 * @example
+	 * ``` javascript
+	 * const subtitles = playerSdkIns.getSubtitleList();
+	 * console.log(subtitles.map(item => item.text));
+	 * ```
+	 */
+	/** {en}
+	 * @brief Get the current subtitle list.
+	 * @list Api
+	 * @returns A copy of the current subtitle list, or an empty array when the `Subtitle` plugin is unavailable or the list is not ready.
+	 * @notes Master M3U8 subtitle items use `source: 'hls'` and do not expose playback URLs or internal track indexes. A non-empty business-configured subtitle list takes precedence.
+	 * @example
+	 * ``` javascript
+	 * const subtitles = playerSdkIns.getSubtitleList();
+	 * console.log(subtitles.map(item => item.text));
+	 * ```
 	 */
 	getSubtitleList(): ISubTitleItem[];
 	/** {zh}
-	 * @brief 切换字幕。需配置 `Subtitle` 插件后调用。
-	 * @param subtitle 目标字幕的 id 或 language，任意一个非空即可定位字幕项。
-	 * @return 切换成功时 resolve，失败（未找到、切换被中止）时 reject。
-	 * @memberof VePlayer
+	 * @brief 切换当前字幕轨。
+	 * @list Api
+	 * @param subtitle 目标字幕的 `id` 或 `language`。优先精确匹配 `id`；仅按语言切换时必须唯一。
+	 * @returns 切换成功时 resolve；未找到、语言不唯一、切换超时或播放会话失效时 reject。
+	 * @notes hls.js 模式下，Promise 在播放内核确认目标字幕轨后才 resolve。
+	 * @example
+	 * ``` javascript
+	 * const [subtitle] = playerSdkIns.getSubtitleList();
+	 * if (subtitle) await playerSdkIns.switchSubtitle({ id: subtitle.id });
+	 * ```
+	 */
+	/** {en}
+	 * @brief Switch the active subtitle track.
+	 * @list Api
+	 * @param subtitle Target subtitle `id` or `language`. Exact `id` matching takes precedence; a language-only match must be unique.
+	 * @returns Resolves after a successful switch. Rejects when the track is missing, the language is ambiguous, the switch times out, or the playback session expires.
+	 * @notes In hls.js mode, the Promise resolves only after the playback engine confirms the target subtitle track.
+	 * @example
+	 * ``` javascript
+	 * const [subtitle] = playerSdkIns.getSubtitleList();
+	 * if (subtitle) await playerSdkIns.switchSubtitle({ id: subtitle.id });
+	 * ```
 	 */
 	switchSubtitle(subtitle: {
 		id?: string | number;
@@ -8927,12 +9910,36 @@ declare class VePlayer {
 	}): Promise<void>;
 	/** {zh}
 	 * @brief 开启字幕展示。恢复上次选中的字幕项；若从未选中过则默认选第一项。需配置 `Subtitle` 插件后调用。
-	 * @memberof VePlayer
+	 * @list Api
+	 * @example
+	 * ``` javascript
+	 * playerSdkIns.showSubtitle();
+	 * ```
+	 */
+	/** {en}
+	 * @brief Show subtitles by restoring the last selected item, or the first item when none has been selected. Requires the `Subtitle` plugin.
+	 * @list Api
+	 * @example
+	 * ``` javascript
+	 * playerSdkIns.showSubtitle();
+	 * ```
 	 */
 	showSubtitle(): void;
 	/** {zh}
 	 * @brief 关闭字幕展示。字幕数据保留，可通过 `showSubtitle` 重新开启。需配置 `Subtitle` 插件后调用。
-	 * @memberof VePlayer
+	 * @list Api
+	 * @example
+	 * ``` javascript
+	 * playerSdkIns.hideSubtitle();
+	 * ```
+	 */
+	/** {en}
+	 * @brief Hide subtitles while retaining subtitle data so it can be restored with `showSubtitle`. Requires the `Subtitle` plugin.
+	 * @list Api
+	 * @example
+	 * ``` javascript
+	 * playerSdkIns.hideSubtitle();
+	 * ```
 	 */
 	hideSubtitle(): void;
 	/** {zh}
@@ -9100,12 +10107,21 @@ export declare class LiveSubtitlesIconPlugin extends Plugin {
 	destroy(): void;
 	render(): string;
 }
+export declare type NativeSubTitleOptions = {
+	nativeRenderMode?: "system" | "dom";
+	container?: HTMLElement;
+	style?: ISubtitleStyle;
+	playbackSessionId?: string;
+	emit?: (event: string, payload: unknown) => void;
+	createOpaqueId?: () => string;
+};
 declare class NativeSubTitle extends EventEmitter {
 	_media: any;
 	_list: any[];
 	_languages: string;
 	curIndex: number;
-	constructor(media: any);
+	private _domAdapter?;
+	constructor(media: any, options?: NativeSubTitleOptions);
 	_init(): void;
 	_onChange: (e: any) => void;
 	/**
@@ -9119,6 +10135,8 @@ declare class NativeSubTitle extends EventEmitter {
 	switch(data: any): Promise<unknown>;
 	switchOff(): void;
 	destroy(): void;
+	refresh(): void;
+	setPlaybackSessionId(playbackSessionId: string): void;
 }
 export interface IPanelItem {
 	showText: string;
@@ -9150,6 +10168,7 @@ export declare class Subtitle extends Plugin {
 		};
 		isShowIcon: boolean;
 		mode: string;
+		nativeRenderMode: string;
 		updateMode: string;
 	};
 	private _delegates;
@@ -9162,6 +10181,11 @@ export declare class Subtitle extends Plugin {
 	player: Player & {
 		_subTitles?: NativeSubTitle | SubTitles;
 	};
+	private _hideListTimer;
+	private _optionListEnterHandler?;
+	private _optionListLeaveHandler?;
+	private _runtimeSubtitleSource;
+	private _runtimeSubtitleBridge?;
 	afterCreate(): void;
 	/**
 	 * @description 初始化原生字幕
@@ -9173,6 +10197,7 @@ export declare class Subtitle extends Plugin {
 	 * @param {number} defaultIndex
 	 */
 	_initExtSubTitle(defaultIndex: any): void;
+	private protectExtSubtitleCoreEvents;
 	_renderList(defaultIndex: any): void;
 	_onOff: () => void;
 	_onChange: (data: any) => void;
@@ -9180,15 +10205,30 @@ export declare class Subtitle extends Plugin {
 	updateCurItem(cIndex: any, subtitle: any): void;
 	initEvents(): void;
 	handleButtonChange: (e: any) => void;
+	private runUiSubtitleAction;
 	onEnter: (e: any) => void;
 	onLeave: (e: any) => void;
+	private clearPendingListHide;
+	private scheduleListHide;
+	private bindOptionListHoverEvents;
+	private unbindOptionListHoverEvents;
 	showList(): void;
 	hideList(): void;
 	openSubtitle(): Promise<any>;
-	getSubTitleIndex(list: any, subtitle?: {
-		id: string;
-		language: string;
-	}): number;
+	getSubTitleIndex(list: ISubTitleItem[], subtitle?: Pick<ISubTitleItem, "id" | "language">): number;
+	setRuntimeSubtitleSource(source: "config" | "hls"): void;
+	setRuntimeSubtitleBridge(bridge?: {
+		switchSubtitle: (subtitle: {
+			id?: string | number;
+			language?: string | number;
+		}) => Promise<void>;
+		hide: () => void;
+		show: () => Promise<void>;
+	}): void;
+	replaceRuntimeSubtitleList(list: ISubTitleItem[], isOpen: boolean): void;
+	confirmRuntimeSubtitleSelection(item: ISubTitleItem | null): void;
+	syncRuntimeSubtitleRenderer(runtimeIndex: number): void;
+	clearRuntimeSubtitleView(): void;
 	registerIcons(): {
 		vttSubOpen: {
 			icon: string;
@@ -9219,6 +10259,7 @@ export declare class Subtitle extends Plugin {
 			"zh-hk": string;
 		};
 	};
+	updateLang(lang: string): void;
 	creatOptionList(): void;
 	getList(): any;
 	renderOptionList(): void;
@@ -9687,285 +10728,55 @@ export declare const Events: {
 	 * @brief Triggered when mirror mode is enabled.
 	 */
 	MIRROR_CHANGE: string;
-	/** {zh}
-	 * @brief 播放器实例创建完成时触发。
-	 */
-	/** {en}
-	 * @brief Triggered when the player instance is created.
-	 */
-	READY: string;
-	/** {zh}
-	 * @brief 播放器创建 `video` 完成时触发，表示可以开始播放。
-	 */
-	/** {en}
-	 * @brief Triggered when the player has created the `video` element and playback can start.
-	 */
-	COMPLETE: string;
-	/** {zh}
-	 * @brief 播放资源发生变化。
-	 */
-	/** {en}
-	 * @brief Triggered when the playback resource changes.
-	 */
-	URL_CHANGE: string;
-	/** {zh}
-	 * @brief 播放器聚焦，同时会展示 Control 栏控件，包含播放按钮、进度条等。
-	 */
-	/** {en}
-	 * @brief Triggered when the player gains focus; the control bar is shown.
-	 */
-	PLAYER_FOCUS: string;
-	/** {zh}
-	 * @brief 播放器失焦，同时会隐藏 Control 栏控件，包含播放按钮、进度条等。
-	 */
-	/** {en}
-	 * @brief Triggered when the player loses focus; the control bar is hidden.
-	 */
-	PLAYER_BLUR: string;
-	/** {zh}
-	 * @brief 系统全屏状态切换。
-	 */
-	/** {en}
-	 * @brief Triggered when native fullscreen state changes.
-	 */
-	FULLSCREEN_CHANGE: string;
-	/** {zh}
-	 * @brief 网页全屏状态切换。
-	 */
-	/** {en}
-	 * @brief Triggered when CSS fullscreen state changes.
-	 */
-	CSS_FULLSCREEN_CHANGE: string;
-	/** {zh}
-	 * @brief 画中画模式切换。
-	 */
-	/** {en}
-	 * @brief Triggered when mini player (floating) mode changes.
-	 */
-	MINI_STATE_CHANGE: string;
-	/** {zh}
-	 * @brief 播放器销毁。
-	 */
-	/** {en}
-	 * @brief Triggered when the player is destroyed.
-	 */
-	DESTROY: string;
-	/** {zh}
-	 * @brief 播放器重新播放。
-	 */
-	/** {en}
-	 * @brief Triggered when replay starts.
-	 */
-	REPLAY: string;
-	/** {zh}
-	 * @brief 播放器重试。
-	 */
-	/** {en}
-	 * @brief Triggered when the player retries playback.
-	 */
-	RETRY: string;
-	/** {zh}
-	 * @brief 清晰度发生变化
-	 */
-	/** {en}
-	 * @brief Triggered when the definition (resolution) changes.
-	 */
-	DEFINITION_CHANGE: string;
-	/** {zh}
-	 * @hidden
-	 */
-	/** {en}
-	 * @hidden
-	 */
-	Before_DEFINITION_CHANGE: string;
-	/** {zh}
-	 * @hidden
-	 */
-	/** {en}
-	 * @hidden
-	 */
-	AFTER_DEFINITION_CHANGE: string;
-	/** {zh}
-	 * @brief 播放器容器尺寸发生变化。
-	 */
-	/** {en}
-	 * @brief Triggered when the player container size changes.
-	 */
-	VIDEO_RESIZE: string;
-	/** {zh}
-	 * @brief 画中画状态切换。
-	 */
-	/** {en}
-	 * @brief Triggered when Picture-in-Picture state changes.
-	 */
-	PIP_CHANGE: string;
-	/** {zh}
-	 * @brief 播放器发生旋转。
-	 */
-	/** {en}
-	 * @brief Triggered when the player is rotated.
-	 */
-	ROTATE: string;
-	/** {zh}
-	 * @brief 播放器内置快捷键事件被触发。
-	 */
-	/** {en}
-	 * @brief Triggered when a built-in keyboard shortcut is used.
-	 */
-	SHORTCUT: string;
-	/** {zh}
-	 * @deprecated
-	 * @brief （已废弃）SEI 信息解析。
-	 */
-	/** {en}
-	 * @deprecated
-	 * @brief (Deprecated) SEI information parsing.
-	 */
-	SEI_PARSED: string;
-	/** {zh}
-	 * @brief 内置插件用户行为触发。所有内置插件用户行为交互都会下发该事件，可用于用户行为埋点。
-	 */
-	/** {en}
-	 * @brief Triggered when user actions within plugins are performed. All plugin user actions will trigger this event, which can be used for user behavior tracking.
-	 */
-	USER_ACTION: string;
-	/** {zh}
-	 * @brief 自动播放成功时触发。
-	 */
-	/** {en}
-	 * @brief Triggered when autoplay succeeds.
-	 */
-	AUTOPLAY_STARTED: string;
-	/** {zh}
-	 * @brief 自动播放失败时触发。
-	 */
-	/** {en}
-	 * @brief Triggered when autoplay fails.
-	 */
-	AUTOPLAY_PREVENTED: string;
-	/** {zh}
-	 * @brief 播放器准备创建。
-	 */
-	READY_CREATE_PLAYER: string;
-	/** {zh}
-	 * @brief 播放器完成创建。
-	 */
-	/** {en}
-	 * @brief Triggered when player creation completes.
-	 */
-	PLAYER_CREATED_FINISH: string;
-	/** {zh}
-	 * @brief createPlayer 性能报告。与 `PLAYER_CREATED_FINISH` 几乎同时触发（略早）。
-	 */
-	/** {en}
-	 * @brief createPlayer performance report. Fired almost at the same time as `PLAYER_CREATED_FINISH` (slightly earlier).
-	 */
-	CREATE_PLAYER_PERF: string;
-	/** {zh}
-	 * @brief 播放器重建。
-	 */
-	/** {en}
-	 * @brief Triggered when the player is rebuilt.
-	 */
-	PLAYER_REBUILD: string;
-	/** {zh}
-	 * @brief 硬解不支持时触发。
-	 */
-	/** {en}
-	 * @brief Triggered when hardware decoding is not supported.
-	 */
-	NOT_SUPPORT_HARDWARE_DECODER: string;
-	/** {zh}
-	 * @brief 软解不支持时触发。
-	 */
-	/** {en}
-	 * @brief Triggered when software decoding is not supported.
-	 */
-	NOT_SUPPORT_SOFT_DECODER: string;
-	/** {zh}
-	 * @brief `playAuthToken` 过期。
-	 */
-	/** {en}
-	 * @brief Triggered when `playAuthToken` expires.
-	 */
-	TOKEN_EXPIRED: string;
-	/** {zh}
-	 * @brief UMD 加载失败。
-	 */
-	/** {en}
-	 * @brief Triggered when UMD loading fails.
-	 */
-	UMD_LOAD_FAIL: string;
-	/** {zh}
-	 * @brief 切换下一个视频。调用 `playNext` 后触发。
-	 */
-	/** {en}
-	 * @brief Triggered when switching to the next video, after calling `playNext`.
-	 */
-	PLAYNEXT: string;
-	/** {zh}
-	 * @brief 视频地址为空。
-	 */
-	/** {en}
-	 * @brief Triggered when the video URL is empty.
-	 */
-	URL_NULL: string;
-	/** {zh}
-	 * @brief 鼠标移出。
-	 */
-	/** {en}
-	 * @brief Triggered when the mouse leaves the player.
-	 */
-	LEAVE_PLAYER: string;
-	/** {zh}
-	 * @brief 鼠标移入。
-	 */
-	/** {en}
-	 * @brief Triggered when the mouse enters the player.
-	 */
-	ENTER_PLAYER: string;
-	/** {zh}
-	 * @brief 播放器状态重置。
-	 */
-	/** {en}
-	 * @brief Triggered when the player state is reset.
-	 */
-	RESET: string;
-	/** {zh}
-	 * @brief `<source>` 加载错误，表示 `<source>` 不支持或播放失败。
-	 */
-	/** {en}
-	 * @brief Triggered when a `<source>` fails to load (unsupported or playback failed).
-	 */
-	SOURCE_ERROR: string;
-	/** {zh}
-	 * @brief `<source>` 加载成功。
-	 */
-	/** {en}
-	 * @brief Triggered when a `<source>` loads successfully.
-	 */
-	SOURCE_SUCCESS: string;
-	/** {zh}
-	 * @brief license 提醒
-	 */
-	/** {en}
-	 * @brief License status warning.
-	 */
-	LICENSE_STATUS_WARNING: string;
-	/** {zh}
-	 * @brief HLS 音频轨道列表更新时触发。`data.audioTracks` 为完整轨道数组。
-	 */
-	/** {en}
-	 * @brief Triggered when the HLS audio track list updates. `data.audioTracks` is the full track array.
-	 */
-	AUDIO_TRACKS_UPDATED: string;
-	/** {zh}
-	 * @brief 音频轨道切换完成时触发。`data.id` 为新轨道 id，`data.audioTrack` 为完整轨道对象。
-	 */
-	/** {en}
-	 * @brief Triggered when audio track switching completes. `data.id` is the new track id; `data.audioTrack` is the full track object.
-	 */
-	AUDIO_TRACK_CHANGE: string;
+	READY: "ready";
+	COMPLETE: "complete";
+	URL_CHANGE: "urlchange";
+	PLAYER_FOCUS: "focus";
+	PLAYER_BLUR: "blur";
+	FULLSCREEN_CHANGE: "fullscreen_change";
+	CSS_FULLSCREEN_CHANGE: "cssFullscreen_change";
+	MINI_STATE_CHANGE: "mini_state_change";
+	DESTROY: "destroy";
+	REPLAY: "replay";
+	RETRY: "retry";
+	DEFINITION_CHANGE: "definition_change";
+	Before_DEFINITION_CHANGE: "before_definition_change";
+	AFTER_DEFINITION_CHANGE: "after_definition_change";
+	VIDEO_RESIZE: "video_resize";
+	PIP_CHANGE: "pip_change";
+	ROTATE: "rotate";
+	SHORTCUT: "shortcut";
+	SEI_PARSED: "SEI_PARSED";
+	USER_ACTION: "user_action";
+	AUTOPLAY_STARTED: "autoplay_started";
+	AUTOPLAY_PREVENTED: "autoplay_was_prevented";
+	READY_CREATE_PLAYER: "ready_create_player";
+	PLAYER_CREATED_FINISH: "player_create_finish";
+	CREATE_PLAYER_PERF: "create_player_perf";
+	PLAYER_REBUILD: "player_rebuild";
+	NOT_SUPPORT_HARDWARE_DECODER: "not_support_hardware_decoder";
+	NOT_SUPPORT_SOFT_DECODER: "not_support_soft_decoder";
+	TOKEN_EXPIRED: "playAuthToken_expired";
+	UMD_LOAD_FAIL: "umd_load_fail";
+	PLAYNEXT: "playnext";
+	URL_NULL: "urlNull";
+	LEAVE_PLAYER: "leaveplayer";
+	ENTER_PLAYER: "enterplayer";
+	RESET: "reset";
+	SOURCE_ERROR: "source_error";
+	SOURCE_SUCCESS: "source_success";
+	LICENSE_STATUS_WARNING: "license_status_warning";
+	AUDIO_TRACKS_UPDATED: "audio_tracks_updated";
+	AUDIO_TRACK_CHANGE: "audio_track_change";
+	HLS_LEVELS_UPDATED: "hls_levels_updated";
+	HLS_LEVEL_SWITCHING: "hls_level_switching";
+	HLS_LEVEL_SWITCHED: "hls_level_switched";
+	HLS_ABR_ENGINE_RESOLVED: "hls_abr_engine_resolved";
+	HLS_ABR_STATE_CHANGE: "hls_abr_state_change";
+	HLS_ABR_LIMIT_CHANGE: "hls_abr_limit_change";
+	HLS_SUBTITLE_TRACKS_UPDATED: "hls_subtitle_tracks_updated";
+	HLS_SUBTITLE_TRACK_SWITCHING: "hls_subtitle_track_switching";
+	HLS_SUBTITLE_TRACK_SWITCHED: "hls_subtitle_track_switched";
 	/** {zh}
 	 * @brief 在播放被终止时触发。例如当播放中的视频重新开始播放。
 	 */
@@ -10138,126 +10949,126 @@ export declare const Event: {
 		/** {en}
 		 * @brief Triggered when the player instance is created.
 		 */
-		READY: string;
+		readonly READY: "ready";
 		/** {zh}
 		 * @brief 播放器创建 `video` 完成时触发，表示可以开始播放。
 		 */
 		/** {en}
 		 * @brief Triggered when the player has created the `video` element and playback can start.
 		 */
-		COMPLETE: string;
+		readonly COMPLETE: "complete";
 		/** {zh}
 		 * @brief 播放资源发生变化。
 		 */
 		/** {en}
 		 * @brief Triggered when the playback resource changes.
 		 */
-		URL_CHANGE: string;
+		readonly URL_CHANGE: "urlchange";
 		/** {zh}
 		 * @brief 播放器聚焦，同时会展示 Control 栏控件，包含播放按钮、进度条等。
 		 */
 		/** {en}
 		 * @brief Triggered when the player gains focus; the control bar is shown.
 		 */
-		PLAYER_FOCUS: string;
+		readonly PLAYER_FOCUS: "focus";
 		/** {zh}
 		 * @brief 播放器失焦，同时会隐藏 Control 栏控件，包含播放按钮、进度条等。
 		 */
 		/** {en}
 		 * @brief Triggered when the player loses focus; the control bar is hidden.
 		 */
-		PLAYER_BLUR: string;
+		readonly PLAYER_BLUR: "blur";
 		/** {zh}
 		 * @brief 系统全屏状态切换。
 		 */
 		/** {en}
 		 * @brief Triggered when native fullscreen state changes.
 		 */
-		FULLSCREEN_CHANGE: string;
+		readonly FULLSCREEN_CHANGE: "fullscreen_change";
 		/** {zh}
 		 * @brief 网页全屏状态切换。
 		 */
 		/** {en}
 		 * @brief Triggered when CSS fullscreen state changes.
 		 */
-		CSS_FULLSCREEN_CHANGE: string;
+		readonly CSS_FULLSCREEN_CHANGE: "cssFullscreen_change";
 		/** {zh}
 		 * @brief 画中画模式切换。
 		 */
 		/** {en}
 		 * @brief Triggered when mini player (floating) mode changes.
 		 */
-		MINI_STATE_CHANGE: string;
+		readonly MINI_STATE_CHANGE: "mini_state_change";
 		/** {zh}
 		 * @brief 播放器销毁。
 		 */
 		/** {en}
 		 * @brief Triggered when the player is destroyed.
 		 */
-		DESTROY: string;
+		readonly DESTROY: "destroy";
 		/** {zh}
 		 * @brief 播放器重新播放。
 		 */
 		/** {en}
 		 * @brief Triggered when replay starts.
 		 */
-		REPLAY: string;
+		readonly REPLAY: "replay";
 		/** {zh}
 		 * @brief 播放器重试。
 		 */
 		/** {en}
 		 * @brief Triggered when the player retries playback.
 		 */
-		RETRY: string;
+		readonly RETRY: "retry";
 		/** {zh}
 		 * @brief 清晰度发生变化
 		 */
 		/** {en}
 		 * @brief Triggered when the definition (resolution) changes.
 		 */
-		DEFINITION_CHANGE: string;
+		readonly DEFINITION_CHANGE: "definition_change";
 		/** {zh}
 		 * @hidden
 		 */
 		/** {en}
 		 * @hidden
 		 */
-		Before_DEFINITION_CHANGE: string;
+		readonly Before_DEFINITION_CHANGE: "before_definition_change";
 		/** {zh}
 		 * @hidden
 		 */
 		/** {en}
 		 * @hidden
 		 */
-		AFTER_DEFINITION_CHANGE: string;
+		readonly AFTER_DEFINITION_CHANGE: "after_definition_change";
 		/** {zh}
 		 * @brief 播放器容器尺寸发生变化。
 		 */
 		/** {en}
 		 * @brief Triggered when the player container size changes.
 		 */
-		VIDEO_RESIZE: string;
+		readonly VIDEO_RESIZE: "video_resize";
 		/** {zh}
 		 * @brief 画中画状态切换。
 		 */
 		/** {en}
 		 * @brief Triggered when Picture-in-Picture state changes.
 		 */
-		PIP_CHANGE: string;
+		readonly PIP_CHANGE: "pip_change";
 		/** {zh}
 		 * @brief 播放器发生旋转。
 		 */
 		/** {en}
 		 * @brief Triggered when the player is rotated.
 		 */
-		ROTATE: string;
+		readonly ROTATE: "rotate";
 		/** {zh}
 		 * @brief 播放器内置快捷键事件被触发。
 		 */
 		/** {en}
 		 * @brief Triggered when a built-in keyboard shortcut is used.
 		 */
-		SHORTCUT: string;
+		readonly SHORTCUT: "shortcut";
 		/** {zh}
 		 * @deprecated
 		 * @brief （已废弃）SEI 信息解析。
@@ -10266,151 +11077,214 @@ export declare const Event: {
 		 * @deprecated
 		 * @brief (Deprecated) SEI information parsing.
 		 */
-		SEI_PARSED: string;
+		readonly SEI_PARSED: "SEI_PARSED";
 		/** {zh}
 		 * @brief 内置插件用户行为触发。所有内置插件用户行为交互都会下发该事件，可用于用户行为埋点。
 		 */
 		/** {en}
 		 * @brief Triggered when user actions within plugins are performed. All plugin user actions will trigger this event, which can be used for user behavior tracking.
 		 */
-		USER_ACTION: string;
+		readonly USER_ACTION: "user_action";
 		/** {zh}
 		 * @brief 自动播放成功时触发。
 		 */
 		/** {en}
 		 * @brief Triggered when autoplay succeeds.
 		 */
-		AUTOPLAY_STARTED: string;
+		readonly AUTOPLAY_STARTED: "autoplay_started";
 		/** {zh}
 		 * @brief 自动播放失败时触发。
 		 */
 		/** {en}
 		 * @brief Triggered when autoplay fails.
 		 */
-		AUTOPLAY_PREVENTED: string;
+		readonly AUTOPLAY_PREVENTED: "autoplay_was_prevented";
 		/** {zh}
 		 * @brief 播放器准备创建。
 		 */
-		READY_CREATE_PLAYER: string;
+		readonly READY_CREATE_PLAYER: "ready_create_player";
 		/** {zh}
 		 * @brief 播放器完成创建。
 		 */
 		/** {en}
 		 * @brief Triggered when player creation completes.
 		 */
-		PLAYER_CREATED_FINISH: string;
+		readonly PLAYER_CREATED_FINISH: "player_create_finish";
 		/** {zh}
 		 * @brief createPlayer 性能报告。与 `PLAYER_CREATED_FINISH` 几乎同时触发（略早）。
 		 */
 		/** {en}
 		 * @brief createPlayer performance report. Fired almost at the same time as `PLAYER_CREATED_FINISH` (slightly earlier).
 		 */
-		CREATE_PLAYER_PERF: string;
+		readonly CREATE_PLAYER_PERF: "create_player_perf";
 		/** {zh}
 		 * @brief 播放器重建。
 		 */
 		/** {en}
 		 * @brief Triggered when the player is rebuilt.
 		 */
-		PLAYER_REBUILD: string;
+		readonly PLAYER_REBUILD: "player_rebuild";
 		/** {zh}
 		 * @brief 硬解不支持时触发。
 		 */
 		/** {en}
 		 * @brief Triggered when hardware decoding is not supported.
 		 */
-		NOT_SUPPORT_HARDWARE_DECODER: string;
+		readonly NOT_SUPPORT_HARDWARE_DECODER: "not_support_hardware_decoder";
 		/** {zh}
 		 * @brief 软解不支持时触发。
 		 */
 		/** {en}
 		 * @brief Triggered when software decoding is not supported.
 		 */
-		NOT_SUPPORT_SOFT_DECODER: string;
+		readonly NOT_SUPPORT_SOFT_DECODER: "not_support_soft_decoder";
 		/** {zh}
 		 * @brief `playAuthToken` 过期。
 		 */
 		/** {en}
 		 * @brief Triggered when `playAuthToken` expires.
 		 */
-		TOKEN_EXPIRED: string;
+		readonly TOKEN_EXPIRED: "playAuthToken_expired";
 		/** {zh}
 		 * @brief UMD 加载失败。
 		 */
 		/** {en}
 		 * @brief Triggered when UMD loading fails.
 		 */
-		UMD_LOAD_FAIL: string;
+		readonly UMD_LOAD_FAIL: "umd_load_fail";
 		/** {zh}
 		 * @brief 切换下一个视频。调用 `playNext` 后触发。
 		 */
 		/** {en}
 		 * @brief Triggered when switching to the next video, after calling `playNext`.
 		 */
-		PLAYNEXT: string;
+		readonly PLAYNEXT: "playnext";
 		/** {zh}
 		 * @brief 视频地址为空。
 		 */
 		/** {en}
 		 * @brief Triggered when the video URL is empty.
 		 */
-		URL_NULL: string;
+		readonly URL_NULL: "urlNull";
 		/** {zh}
 		 * @brief 鼠标移出。
 		 */
 		/** {en}
 		 * @brief Triggered when the mouse leaves the player.
 		 */
-		LEAVE_PLAYER: string;
+		readonly LEAVE_PLAYER: "leaveplayer";
 		/** {zh}
 		 * @brief 鼠标移入。
 		 */
 		/** {en}
 		 * @brief Triggered when the mouse enters the player.
 		 */
-		ENTER_PLAYER: string;
+		readonly ENTER_PLAYER: "enterplayer";
 		/** {zh}
 		 * @brief 播放器状态重置。
 		 */
 		/** {en}
 		 * @brief Triggered when the player state is reset.
 		 */
-		RESET: string;
+		readonly RESET: "reset";
 		/** {zh}
 		 * @brief `<source>` 加载错误，表示 `<source>` 不支持或播放失败。
 		 */
 		/** {en}
 		 * @brief Triggered when a `<source>` fails to load (unsupported or playback failed).
 		 */
-		SOURCE_ERROR: string;
+		readonly SOURCE_ERROR: "source_error";
 		/** {zh}
 		 * @brief `<source>` 加载成功。
 		 */
 		/** {en}
 		 * @brief Triggered when a `<source>` loads successfully.
 		 */
-		SOURCE_SUCCESS: string;
+		readonly SOURCE_SUCCESS: "source_success";
 		/** {zh}
 		 * @brief license 提醒
 		 */
 		/** {en}
 		 * @brief License status warning.
 		 */
-		LICENSE_STATUS_WARNING: string;
+		readonly LICENSE_STATUS_WARNING: "license_status_warning";
 		/** {zh}
 		 * @brief HLS 音频轨道列表更新时触发。`data.audioTracks` 为完整轨道数组。
 		 */
 		/** {en}
 		 * @brief Triggered when the HLS audio track list updates. `data.audioTracks` is the full track array.
 		 */
-		AUDIO_TRACKS_UPDATED: string;
+		readonly AUDIO_TRACKS_UPDATED: "audio_tracks_updated";
 		/** {zh}
 		 * @brief 音频轨道切换完成时触发。`data.id` 为新轨道 id，`data.audioTrack` 为完整轨道对象。
 		 */
 		/** {en}
 		 * @brief Triggered when audio track switching completes. `data.id` is the new track id; `data.audioTrack` is the full track object.
 		 */
-		AUDIO_TRACK_CHANGE: string;
+		readonly AUDIO_TRACK_CHANGE: "audio_track_change";
+		/** {zh}
+		 * @brief 当前播放会话的 HLS Level 列表或状态更新。
+		 */
+		/** {en}
+		 * @brief Triggered when the HLS Level list or state updates for the current playback session.
+		 */
+		readonly HLS_LEVELS_UPDATED: "hls_levels_updated";
+		/** {zh}
+		 * @brief HLS Level 切换请求已提交给播放内核；不表示画面已经切换。
+		 */
+		/** {en}
+		 * @brief Triggered after an HLS Level switch is submitted to the playback engine; the rendered Level may not have changed yet.
+		 */
+		readonly HLS_LEVEL_SWITCHING: "hls_level_switching";
+		/** {zh}
+		 * @brief HLS Level 已实际切换。
+		 */
+		/** {en}
+		 * @brief Triggered after the active HLS Level has actually switched.
+		 */
+		readonly HLS_LEVEL_SWITCHED: "hls_level_switched";
+		/** {zh}
+		 * @brief 当前播放会话的 HLS ABR 决策引擎解析完成。
+		 */
+		/** {en}
+		 * @brief Triggered after the HLS ABR decision engine is resolved for the current playback session.
+		 */
+		readonly HLS_ABR_ENGINE_RESOLVED: "hls_abr_engine_resolved";
+		/** {zh}
+		 * @brief HLS ABR 的可用性、自动/手动模式或激活状态发生变化。
+		 */
+		/** {en}
+		 * @brief Triggered when HLS ABR availability, auto/manual mode, or active state changes.
+		 */
+		readonly HLS_ABR_STATE_CHANGE: "hls_abr_state_change";
+		/** {zh}
+		 * @brief HLS ABR 上限发生变化。
+		 */
+		/** {en}
+		 * @brief Triggered when the HLS ABR cap changes.
+		 */
+		readonly HLS_ABR_LIMIT_CHANGE: "hls_abr_limit_change";
+		/** {zh}
+		 * @brief 当前播放会话从 Master M3U8 或原生 TextTrack 获得的字幕列表更新。
+		 */
+		/** {en}
+		 * @brief Triggered when the subtitle list sourced from a Master M3U8 or native TextTracks updates for the current playback session.
+		 */
+		readonly HLS_SUBTITLE_TRACKS_UPDATED: "hls_subtitle_tracks_updated";
+		/** {zh}
+		 * @brief HLS 字幕轨切换请求已提交；不表示字幕轨已经生效。
+		 */
+		/** {en}
+		 * @brief Triggered after an HLS subtitle-track switch is submitted; the track may not be active yet.
+		 */
+		readonly HLS_SUBTITLE_TRACK_SWITCHING: "hls_subtitle_track_switching";
+		/** {zh}
+		 * @brief HLS 字幕轨切换已经生效。
+		 */
+		/** {en}
+		 * @brief Triggered after an HLS subtitle-track switch takes effect.
+		 */
+		readonly HLS_SUBTITLE_TRACK_SWITCHED: "hls_subtitle_track_switched";
 	};
 	PluginEvents: {
 		/** {zh}