@byteplus/veplayer 1.17.0-rc.8 → 1.17.0-rc.9

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;
@@ -3414,16 +3443,19 @@ export interface IPlayerConfig extends IPlayerOptions {
 	 */
 	defaultDefinition?: string;
 	/** {zh}
-	 * @brief 起播默认音频轨道的语言代码（BCP-47，如 `"zh"`、`"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"`, `"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 -
@@ -5549,8 +5581,15 @@ 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;
 	/**
@@ -5977,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 切换插件展示
@@ -6124,28 +6165,12 @@ 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()` 获取。
@@ -6154,18 +6179,7 @@ declare class VePlayer {
 	 * @notes 切换完成后会触发 `Events.AUDIO_TRACK_CHANGE` 事件；
 	 *        同时 PC 端和移动端音频轨道插件的选中状态会自动更新。
 	 */
-	switchAudioTrack(track: {
-		id: string | number;
-		lang?: string;
-		assocLang?: string;
-		characteristics?: string;
-		channels?: string;
-		name?: string;
-		audioCodec?: string;
-		groupId?: string;
-		default?: boolean;
-		[key: string]: unknown;
-	}): void;
+	switchAudioTrack(track: AudioTrackInfo): void;
 	/** {zh}
 	 * @brief 当前播放器命中预加载的情况
 	 * @type {{