@volcengine/veplayer 1.17.0-rc.1 → 1.17.0-rc.10

package/index.d.ts

@@ -897,6 +897,35 @@ export declare class DefinitionDemotePlugin extends Plugin {
 	showToast(definition: Stream): void;
 	destroy(): void;
 }
+/**
+ * 音轨选择选项。
+ * 对应 hls.js `AudioSelectionOption` 的所有字段，所有字段均可选。
+ * 用于 `switchAudioTrack()` 参数（配合 `id` 使用）以及 `audioPreference` 配置。
+ */
+export interface AudioTrackOption {
+	lang?: string;
+	assocLang?: string;
+	characteristics?: string;
+	channels?: string;
+	name?: string;
+	audioCodec?: string;
+	groupId?: string;
+	default?: boolean;
+	[key: string]: unknown;
+}
+export interface AudioTrack extends AudioTrackOption {
+	id: number;
+	name: string;
+	default: boolean;
+}
+/**
+ * `getAudioTracks()` / `getCurrentAudioTrack()` 的返回项类型。
+ * 是 `switchAudioTrack()` 参数类型的子类型，可直接传入。
+ */
+export interface AudioTrackInfo extends AudioTrack {
+	/** 是否为当前激活轨道。`getCurrentAudioTrack()` 返回时始终为 `true`。 */
+	selected: boolean;
+}
 export interface IAudioTrackConfig {
 	/** 控件在控制栏中的排列顺序，数值越小越靠左。@default 5 */
 	index?: number;
@@ -904,12 +933,16 @@ export interface IAudioTrackConfig {
 	isShowIcon?: boolean;
 	/** 竖屏时是否隐藏控件。@default false */
 	hidePortrait?: boolean;
+	/** 音轨列表中是否在语言名称后显示括号内的原始轨道名，如 `日本語 (Stereo AudioTrack1)`。@default true */
+	showNameSuffix?: boolean;
 }
 export interface IAudioTrackMobileConfig {
 	/** 控件在控制栏中的排列顺序，数值越小越靠左。@default 2.6 */
 	index?: number;
 	/** 是否显示图标按钮。@default true */
 	isShowIcon?: boolean;
+	/** 音轨列表中是否在语言名称后显示括号内的原始轨道名，如 `日本語 (Stereo AudioTrack1)`。@default true */
+	showNameSuffix?: boolean;
 }
 /**
  * @brief DASH 播放配置。
@@ -3345,6 +3378,23 @@ export interface IPlayerConfig extends IPlayerOptions {
 	 * @default false
 	 */
 	enableHlsMSE?: boolean;
+	/** {zh}
+	 * @brief 移动端播放 HLS 时优先使用 hls.js 插件（MSE/MMS）：
+	 * - **Android**：直接启用 hls.js 播放。
+	 * - **iOS**：仅在设备支持 `ManagedMediaSource`（iOS 17.1+，即 `VePlayer.isMMSSupported()` 为 `true`）时启用；
+	 *   不满足时自动回退至原生 HLS 播放。
+	 * 开启后可在移动端解锁多音轨切换、`setAudioOption` 偏好持久化等 hls.js 特有能力。
+	 * @default false
+	 */
+	/** {en}
+	 * @brief Prefer hls.js (MSE/MMS) for HLS playback on mobile:
+	 * - **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.
+	 * 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
@@ -3393,16 +3443,19 @@ export interface IPlayerConfig extends IPlayerOptions {
 	 */
 	defaultDefinition?: string;
 	/** {zh}
-	 * @brief 起播默认音频轨道的语言代码（BCP-47，如 `"zh-cn"`、`"en"`）。
-	 * @notes HLS 流匹配 `audioTrack.lang`；iOS 原生播放匹配 `audioTrack.language`。
-	 *        多条轨道语言相同时取第一条。未匹配到时沿用 manifest 默认轨道。
+	 * @brief 起播默认音轨偏好。字段与 `switchAudioTrack()` 参数一致，按需填写一个或多个字段进行匹配。
+	 * hls.js 路径下通过 `hls.setAudioOption()` 应用，支持跨清晰度自动持久化；
+	 * iOS 原生路径按 `lang` 字段匹配。未匹配到时沿用 manifest 默认轨道。
 	 * @default -
 	 */
 	/** {en}
-	 * @brief Default audio track language code (BCP-47, e.g. `"zh-cn"`, `"en"`) at playback start. Falls back to the manifest default when no match is found.
+	 * @brief Default audio track preference at playback start. Accepts the same fields as
+	 * `switchAudioTrack()`. Applied via `hls.setAudioOption()` on the hls.js path (persists
+	 * across quality switches); matched by `lang` on the iOS native path.
+	 * Falls back to the manifest default when no match is found.
 	 * @default -
 	 */
-	defaultAudioLang?: string;
+	audioPreference?: AudioTrackOption;
 	/** {zh}
 	 * @brief 插件，可自行选择安装的插件，支持{@link https://h5player.bytedance.com/plugins/ 西瓜播放器插件}。
 	 * @default -
@@ -5528,8 +5581,17 @@ declare class VePlayer {
 	 * @memberof VePlayer
 	 */
 	private _emitter;
-	/** 最近一次用户主动（或 defaultAudioLang）选中的音轨语言代码，用于清晰度切换后恢复音轨 */
-	private _lastSelectedAudioLang;
+	/** 最近一次用户选择的音轨，用于清晰度切换后通过 setAudioOption 恢复音轨 */
+	private _lastSelectedAudioTrack;
+	/**
+	 * `_applyAudioPreference` 发起恢复时置 true，hls.js 随后触发的 hlsAudioTrackSwitched
+	 * 属于自动切轨，不应覆盖 `_lastSelectedAudioTrack`；事件触发后自动清除。
+	 * 使用 timeout 兜底，防止 hls.js 未触发事件时标志永久残留。
+	 */
+	private _suppressAudioTrackMemory;
+	private _suppressAudioTrackMemoryTimer;
+	/** playNext 后置为 true，直到新视频首个 addtrack 到达前屏蔽旧视频 change 事件的干扰 */
+	private _playNextPending;
 	/**
 	 *
 	 *
@@ -5954,10 +6016,12 @@ declare class VePlayer {
 	 */
 	/** @hidden 获取 HLS 实例（兼容加密和普通 HLS 插件） */
 	private _getHlsInstance;
-	/** @hidden 在 HLS 音轨列表就绪或清晰度切换后，恢复上次选中的音轨；找不到时 fallback 到 defaultAudioLang */
-	private _applyDefaultAudioLang;
-	/** @hidden 在 native AudioTrackList 就绪后，恢复上次选中的音轨；找不到时 fallback 到 defaultAudioLang */
-	private _applyDefaultAudioLangNative;
+	/** @hidden 在 HLS 音轨列表就绪或清晰度切换后，恢复上次选中的音轨；找不到时应用 audioPreference 配置 */
+	private _applyAudioPreference;
+	private _setSuppressAudioTrackMemory;
+	private _clearSuppressAudioTrackMemory;
+	/** @hidden 在 native AudioTrackList 就绪后，恢复上次选中的音轨；找不到时 fallback 到 audioPreference */
+	private _applyAudioPreferenceNative;
 	private _offPlayerEvents;
 	/** {zh}
 	 * @hidden 切换插件展示
@@ -6101,46 +6165,34 @@ declare class VePlayer {
 	 * @brief 获取音频轨道列表。HLS 流通过 hls.js 获取，iOS 原生播放通过 HTMLMediaElement.audioTracks 获取。
 	 * @notes 每项包含 `id`、`name`、`lang`、`channels`、`default`、`selected` 字段；轨道数量 ≤ 1 时返回空数组。
 	 */
-	getAudioTracks(): Array<{
-		id: string | number;
-		name: string;
-		lang?: string;
-		channels?: string;
-		default: boolean;
-		selected: boolean;
-		[key: string]: unknown;
-	}>;
+	getAudioTracks(): AudioTrackInfo[];
 	/** {zh}
 	 * @brief 获取当前激活的音频轨道。
 	 * @notes HLS 流通过 hls.js 获取，iOS 原生播放通过 HTMLMediaElement.audioTracks 获取；无激活轨道时返回 null。
 	 */
-	getCurrentAudioTrack(): {
-		id: string | number;
-		name: string;
-		lang?: string;
-		channels?: string;
-		default: boolean;
-		selected: boolean;
-		[key: string]: unknown;
-	} | null;
+	getCurrentAudioTrack(): AudioTrackInfo | null;
 	/** {zh}
 	 * @brief 切换音频轨道。
 	 * @param id 目标轨道的 id，可通过 `getAudioTracks()` 获取。
+	 * @param lang 目标轨道的语言代码（BCP-47）。若提供，则 id 与 lang 同时匹配时才执行切换，
+	 *             可用于 iOS 原生 audioTracks 中存在重复 id 的场景。
 	 * @notes 切换完成后会触发 `Events.AUDIO_TRACK_CHANGE` 事件；
 	 *        同时 PC 端和移动端音频轨道插件的选中状态会自动更新。
 	 */
-	switchAudioTrack(id: string | number): void;
+	switchAudioTrack(track: AudioTrackInfo): void;
 	/** {zh}
-	 * @brief 当前播放是否命中预加载缓存
-	 * @memberof VePlayer
-	 * @return {boolean} 是否命中预加载
+	 * @brief 当前播放器命中预加载的情况
+	 * @type {{
+	 *  hit: number, // 0-未命中 1-命中
+	 *  duration: 0, // 预加载时长
+	 *  length: 0 // 预加载数据长度
+	 * }}
 	 */
-	/** {en}
-	 * @brief Whether the current playback hits the preloaded cache
-	 * @memberof VePlayer
-	 * @return {boolean} Whether the current playback hits the preloaded cache
-	 */
-	get hitPreload(): boolean;
+	get preLoadData(): {
+		hit: number;
+		duration?: number;
+		length?: number;
+	};
 	/** {zh}
 	 * @brief 初始化多语言词典
 	 *