@byteplus/veplayer 1.19.0-rc.0 → 1.19.0-rc.2

package/index.d.ts

@@ -577,6 +577,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 +782,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 +818,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 -
@@ -3415,6 +3455,379 @@ 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 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;
@@ -4686,6 +5099,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
 	 */
@@ -4694,10 +5108,34 @@ 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 清晰度插件手动切换 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 是否启用 {@link https://hlsjs.video-dev.org/ hls.js} 插件播放HLS视频，默认为true，设置为false后，PC端播放HLS使用自研hls插件播放HLS视频
 	 * @default true
@@ -6575,71 +7013,294 @@ declare abstract class AbstractBaseAdapter {
 	abstract getPlugins(umdLoader: UMDLoader): Promise<XGPlugin[]>;
 	abstract setPluginConfigInVid(videoInfo: IVideoInfo, context: AuthToken): void;
 }
-declare class PlayerData {
-	id?: string;
-	root?: HTMLElement;
-	configs: IPlayerConfig;
-	type: string;
-	isLive: boolean;
-	options: any;
-	isMobile: boolean;
-	playList: Stream[];
-	plugins: any[];
-	openSoftDecoding: boolean;
-	defaultConfig: IDefaultConfig | undefined;
-	isHitDefault: boolean;
-	codec?: ICodecType;
-	enableH265Degrade: boolean;
-	languageData: {
-		extraLangList: IXGI18nText[];
-		extendLangList: IXGI18nText[];
-	};
-	current: Current;
-	onMediaExpired: () => Promise<SourceConfig>;
-	onTokenExpired: () => Promise<IPlayAuthTokenConfig>;
-	unionId?: string;
-	unionInfo?: string;
-	isMusic?: boolean;
-	sdkPlugins: any[];
-	useHlsPluginForSafari: boolean;
-	enableHlsJs: boolean;
-	enableMenu: boolean;
-	region: TRegionType;
-	userRegion: TRegionType;
-	playDomainDegrade: boolean;
-	strategiesPlugins: any[];
-	strategiesPluginConfigs: any;
-	/**
-	 * @default playList第一项
-	 */
-	defaultDefinition: string;
-	urlCheckData: {
-		enableUrlExpireCheck: boolean;
-		urlExpireTimestamp: number;
-		urlExpireDiff: number;
-		urlCheckExpireInterval: number;
-	};
-	private isAutoBitrateEnable;
-	adapter: AbstractBaseAdapter;
-	/**
-	 * @breif 是否vid模式的加密播放
+/** {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
 	 */
-	isVidEncrypt: boolean;
-	dashOpts: {
-		Data: IGetPlayInfoRes;
-	};
-	/**
-	 * @brief 播放器sdk实例
+	/** {en}
+	 * @brief Subtitle source. Business-configured subtitles use `config`; Master M3U8 or native HLS subtitles use `hls`.
+	 * @default config
 	 */
-	sdk: VePlayer;
-	/**
-	 * @brief 当前加密播放类型，为空则表示非加密
+	source?: "config" | "hls";
+	/** {zh}
+	 * @brief 字幕语言。
+	 * @default -
 	 */
-	drmType: EDRMTYPE;
-	/**
-	 * @brief 私有加密会话id
+	/** {en}
+	 * @brief Subtitle language.
+	 * @default -
 	 */
-	encryptSessionId?: string;
+	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?: 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;
+}
+/** {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;
+	configs: IPlayerConfig;
+	type: string;
+	isLive: boolean;
+	options: any;
+	isMobile: boolean;
+	playList: Stream[];
+	plugins: any[];
+	openSoftDecoding: boolean;
+	defaultConfig: IDefaultConfig | undefined;
+	isHitDefault: boolean;
+	codec?: ICodecType;
+	enableH265Degrade: boolean;
+	languageData: {
+		extraLangList: IXGI18nText[];
+		extendLangList: IXGI18nText[];
+	};
+	current: Current;
+	onMediaExpired: () => Promise<SourceConfig>;
+	onTokenExpired: () => Promise<IPlayAuthTokenConfig>;
+	unionId?: string;
+	unionInfo?: string;
+	isMusic?: boolean;
+	sdkPlugins: any[];
+	useHlsPluginForSafari: boolean;
+	enableHlsJs: boolean;
+	enableMenu: boolean;
+	region: TRegionType;
+	userRegion: TRegionType;
+	playDomainDegrade: boolean;
+	strategiesPlugins: any[];
+	strategiesPluginConfigs: any;
+	/**
+	 * @default playList第一项
+	 */
+	defaultDefinition: string;
+	urlCheckData: {
+		enableUrlExpireCheck: boolean;
+		urlExpireTimestamp: number;
+		urlExpireDiff: number;
+		urlCheckExpireInterval: number;
+	};
+	private isAutoBitrateEnable;
+	adapter: AbstractBaseAdapter;
+	/**
+	 * @breif 是否vid模式的加密播放
+	 */
+	isVidEncrypt: boolean;
+	dashOpts: {
+		Data: IGetPlayInfoRes;
+	};
+	/**
+	 * @brief 播放器sdk实例
+	 */
+	sdk: VePlayer;
+	/**
+	 * @brief 当前加密播放类型，为空则表示非加密
+	 */
+	drmType: EDRMTYPE;
+	/**
+	 * @brief 私有加密会话id
+	 */
+	encryptSessionId?: string;
 	constructor(configs: IPlayerConfig, sdk: VePlayer);
 	/**
 	 * 初始化播放数据
@@ -6676,6 +7337,8 @@ declare class PlayerData {
 	 */
 	getCurrentStreamType(): string;
 	getStreamType(): string;
+	getConfiguredHlsAbrEngine(): HlsAbrEngine;
+	isOpenVePlayerABR(): boolean;
 	isOpenABR(): boolean;
 	showRealDefinition(): boolean;
 	isAutoDefinition(def: any): boolean;
@@ -7044,198 +7707,11 @@ export declare type IMediaInfoPrefetchFailure = {
  * @detail ref
  */
 /** {en}
- * @brief Result for one media info prefetch item. Batch results preserve input order, and one failure does not interrupt other items.
- * @detail ref
- */
-export declare type IMediaInfoPrefetchResult = IMediaInfoPrefetchSuccess | IMediaInfoPrefetchFailure;
-export declare type IPreloadStream = IPreloadResolvedStream | IPreloadDramaStream | IPreloadAuthTokenStream;
-/** {zh}
- * @list Options
- * @brief 字幕项。
- * @kind property
- */
-/** {en}
- * @list Options
- * @brief Subtitle item.
- * @kind property
- */
-export interface ISubTitleItem {
-	/** {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
+ * @brief Result for one media info prefetch item. Batch results preserve input order, and one failure does not interrupt other items.
+ * @detail ref
  */
-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";
+export declare type IMediaInfoPrefetchResult = IMediaInfoPrefetchSuccess | IMediaInfoPrefetchFailure;
+export declare type IPreloadStream = IPreloadResolvedStream | IPreloadDramaStream | IPreloadAuthTokenStream;
 /** {zh}
  * @hidden
  * h265策略配置
@@ -7743,6 +8219,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;
 	/**
@@ -8301,6 +8785,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
@@ -8621,6 +9113,171 @@ declare class VePlayer {
 		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 时返回空数组。
@@ -8896,16 +9553,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;
@@ -8913,12 +9605,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}
@@ -9086,12 +9802,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;
 	/**
@@ -9105,6 +9830,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;
@@ -9136,6 +9863,7 @@ export declare class Subtitle extends Plugin {
 		};
 		isShowIcon: boolean;
 		mode: string;
+		nativeRenderMode: string;
 		updateMode: string;
 	};
 	private _delegates;
@@ -9148,6 +9876,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 初始化原生字幕
@@ -9159,6 +9892,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;
@@ -9166,15 +9900,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;
@@ -9952,6 +10701,69 @@ export declare const Events: {
 	 * @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;
+	/** {zh}
+	 * @brief 当前播放会话的 HLS Level 列表或状态更新。
+	 */
+	/** {en}
+	 * @brief Triggered when the HLS Level list or state updates for the current playback session.
+	 */
+	HLS_LEVELS_UPDATED: string;
+	/** {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.
+	 */
+	HLS_LEVEL_SWITCHING: string;
+	/** {zh}
+	 * @brief HLS Level 已实际切换。
+	 */
+	/** {en}
+	 * @brief Triggered after the active HLS Level has actually switched.
+	 */
+	HLS_LEVEL_SWITCHED: string;
+	/** {zh}
+	 * @brief 当前播放会话的 HLS ABR 决策引擎解析完成。
+	 */
+	/** {en}
+	 * @brief Triggered after the HLS ABR decision engine is resolved for the current playback session.
+	 */
+	HLS_ABR_ENGINE_RESOLVED: string;
+	/** {zh}
+	 * @brief HLS ABR 的可用性、自动/手动模式或激活状态发生变化。
+	 */
+	/** {en}
+	 * @brief Triggered when HLS ABR availability, auto/manual mode, or active state changes.
+	 */
+	HLS_ABR_STATE_CHANGE: string;
+	/** {zh}
+	 * @brief HLS ABR 上限发生变化。
+	 */
+	/** {en}
+	 * @brief Triggered when the HLS ABR cap changes.
+	 */
+	HLS_ABR_LIMIT_CHANGE: string;
+	/** {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.
+	 */
+	HLS_SUBTITLE_TRACKS_UPDATED: string;
+	/** {zh}
+	 * @brief HLS 字幕轨切换请求已提交；不表示字幕轨已经生效。
+	 */
+	/** {en}
+	 * @brief Triggered after an HLS subtitle-track switch is submitted; the track may not be active yet.
+	 */
+	HLS_SUBTITLE_TRACK_SWITCHING: string;
+	/** {zh}
+	 * @brief HLS 字幕轨切换已经生效。
+	 */
+	/** {en}
+	 * @brief Triggered after an HLS subtitle-track switch takes effect.
+	 */
+	HLS_SUBTITLE_TRACK_SWITCHED: string;
 	/** {zh}
 	 * @brief 在播放被终止时触发。例如当播放中的视频重新开始播放。
 	 */
@@ -10397,6 +11209,69 @@ export declare const Event: {
 		 * @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;
+		/** {zh}
+		 * @brief 当前播放会话的 HLS Level 列表或状态更新。
+		 */
+		/** {en}
+		 * @brief Triggered when the HLS Level list or state updates for the current playback session.
+		 */
+		HLS_LEVELS_UPDATED: string;
+		/** {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.
+		 */
+		HLS_LEVEL_SWITCHING: string;
+		/** {zh}
+		 * @brief HLS Level 已实际切换。
+		 */
+		/** {en}
+		 * @brief Triggered after the active HLS Level has actually switched.
+		 */
+		HLS_LEVEL_SWITCHED: string;
+		/** {zh}
+		 * @brief 当前播放会话的 HLS ABR 决策引擎解析完成。
+		 */
+		/** {en}
+		 * @brief Triggered after the HLS ABR decision engine is resolved for the current playback session.
+		 */
+		HLS_ABR_ENGINE_RESOLVED: string;
+		/** {zh}
+		 * @brief HLS ABR 的可用性、自动/手动模式或激活状态发生变化。
+		 */
+		/** {en}
+		 * @brief Triggered when HLS ABR availability, auto/manual mode, or active state changes.
+		 */
+		HLS_ABR_STATE_CHANGE: string;
+		/** {zh}
+		 * @brief HLS ABR 上限发生变化。
+		 */
+		/** {en}
+		 * @brief Triggered when the HLS ABR cap changes.
+		 */
+		HLS_ABR_LIMIT_CHANGE: string;
+		/** {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.
+		 */
+		HLS_SUBTITLE_TRACKS_UPDATED: string;
+		/** {zh}
+		 * @brief HLS 字幕轨切换请求已提交；不表示字幕轨已经生效。
+		 */
+		/** {en}
+		 * @brief Triggered after an HLS subtitle-track switch is submitted; the track may not be active yet.
+		 */
+		HLS_SUBTITLE_TRACK_SWITCHING: string;
+		/** {zh}
+		 * @brief HLS 字幕轨切换已经生效。
+		 */
+		/** {en}
+		 * @brief Triggered after an HLS subtitle-track switch takes effect.
+		 */
+		HLS_SUBTITLE_TRACK_SWITCHED: string;
 	};
 	PluginEvents: {
 		/** {zh}