@volcengine/veplayer 1.19.0-rc.1 → 1.19.0-rc.11

package/lite.d.ts

@@ -85,7 +85,7 @@ interface ISubTitleItem {
 	 * @brief Subtitle display name.
 	 * @default -
 	 */
-	text?: string;
+	text?: ISubtitleLabelValue;
 	/** {zh}
 	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
 	 * @default -
@@ -94,7 +94,7 @@ interface ISubTitleItem {
 	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
 	 * @default -
 	 */
-	label?: string | number;
+	label?: ISubtitleLabelValue;
 	/** {zh}
 	 * @brief 外挂字幕 URL 地址。
 	 * @default -
@@ -124,6 +124,118 @@ 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 type ISubtitleLabelValue = string | number | Record<string, string | number>;
+/** {zh}
+ * @brief 字幕标签映射项。
+ * @detail ref
+ */
+/** {en}
+ * @brief Mapping item used to customize a subtitle label.
+ * @detail ref
+ */
+export interface ISubtitleLabelItem {
+	/** {zh} @brief 多语言 key 无法解析时使用的回退文案。 */
+	/** {en} @brief Fallback text used when the i18n key cannot be resolved. */
+	text?: string;
+	/** {zh} @brief 从播放器当前多语言词典中读取文案的 key。 */
+	/** {en} @brief Key resolved from the player's active i18n dictionary. */
+	textKey?: string;
+}
+/** {zh}
+ * @brief 字幕标签映射表。匹配优先级为 `id`、完整 `language`、基础 `language`、原始 `text`。
+ * @detail ref
+ */
+/** {en}
+ * @brief Subtitle label maps. Match order is `id`, full `language`, base `language`, then source `text`.
+ * @detail ref
+ */
+export interface ISubtitleLabelMap {
+	/** {zh} @brief 按稳定字幕 ID 映射；不建议用于会话内生成 ID 的 Master M3U8 字幕。 */
+	/** {en} @brief Maps stable subtitle IDs; not recommended for session-scoped Master M3U8 IDs. */
+	id?: Record<string, ISubtitleLabelItem>;
+	/** {zh} @brief 按字幕语言映射，忽略大小写并兼容 `_` 与 `-`。 */
+	/** {en} @brief Maps subtitle languages case-insensitively, treating `_` and `-` as equivalent. */
+	language?: Record<string, ISubtitleLabelItem>;
+	/** {zh} @brief 按字幕原始名称映射。 */
+	/** {en} @brief Maps the source subtitle name. */
+	text?: Record<string, ISubtitleLabelItem>;
+}
+/** {zh}
+ * @brief 传给字幕标签 formatter 的只读安全字幕快照，不包含 URL 或字幕内容。
+ * @detail ref
+ */
+/** {en}
+ * @brief Read-only safe subtitle snapshot passed to the label formatter, excluding URLs and subtitle content.
+ * @detail ref
+ */
+export interface ISubtitleLabelTrack {
+	source?: "config" | "hls";
+	id?: string | number;
+	language?: string | number;
+	isDefault?: boolean;
+	forced?: boolean;
+	characteristics?: string;
+	text?: string | number;
+	label?: string | number;
+}
+/** {zh}
+ * @brief 字幕标签格式化上下文。
+ * @detail ref
+ */
+/** {en}
+ * @brief Context passed to the subtitle label formatter.
+ * @detail ref
+ */
+export interface ISubtitleLabelContext {
+	/** {zh} @brief 当前字幕项的只读安全快照。 */
+	/** {en} @brief Read-only safe snapshot of the current subtitle item. */
+	item: Readonly<ISubtitleLabelTrack>;
+	/** {zh} @brief 当前字幕列表的只读安全快照。 */
+	/** {en} @brief Read-only safe snapshots of the current subtitle list. */
+	items: ReadonlyArray<Readonly<ISubtitleLabelTrack>>;
+	/** {zh} @brief 当前字幕项在列表中的位置。 */
+	/** {en} @brief Position of the current subtitle item in the list. */
+	index: number;
+	/** {zh} @brief 应用标签映射前的原始回退文案。 */
+	/** {en} @brief Source fallback text before applying label mappings. */
+	canonicalLabel: string;
+	/** {zh} @brief 应用 `textKey` 或 `text` 后的文案。 */
+	/** {en} @brief Label after applying `textKey` or `text`. */
+	localizedLabel: string;
+	/** {zh} @brief formatter 返回空值或抛出异常时使用的文案。 */
+	/** {en} @brief Label used when the formatter returns an empty value or throws. */
+	defaultLabel: string;
+	/** {zh} @brief 播放器当前语言。 */
+	/** {en} @brief Current player language. */
+	lang: string;
+	/** {zh} @brief 本地化后的文案是否在当前字幕列表中重复。 */
+	/** {en} @brief Whether the localized label is duplicated in the current subtitle list. */
+	duplicated: boolean;
+}
+/** {zh}
+ * @brief 字幕标签多语言映射与自定义格式化配置。
+ * @detail ref
+ */
+/** {en}
+ * @brief Localization mapping and custom formatter for subtitle labels.
+ * @detail ref
+ */
+export interface ISubtitleLabelOptions {
+	/** {zh} @brief 按字幕 ID、语言或原始名称配置展示文案。 */
+	/** {en} @brief Display-label mappings keyed by subtitle ID, language, or source name. */
+	map?: ISubtitleLabelMap;
+	/** {zh} @brief 同步格式化最终标签；返回空值、Promise 或抛出异常时回退到 `defaultLabel`。 */
+	/** {en} @brief Synchronously formats the final label; empty values, Promises, or exceptions fall back to `defaultLabel`. */
+	formatter?: (context: ISubtitleLabelContext) => string | null | undefined;
+}
 interface IListItem {
 	/** {zh}
 	 * @brief 开始时间，单位为秒。
@@ -417,6 +529,92 @@ export interface IHlsLevel {
 	/** {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
@@ -645,6 +843,71 @@ export interface IAutoBitrateOpts {
 	 */
 	module?: unknown;
 }
+interface AudioTrackOption {
+	/** {zh}
+	 * @brief 音轨主要语言，BCP-47 格式（如 `zh`、`en`）。对应 `#EXT-X-MEDIA` 的 `LANGUAGE`。
+	 */
+	/** {en}
+	 * @brief Primary track language in BCP-47 format (e.g. `zh`, `en`). Maps to `#EXT-X-MEDIA` `LANGUAGE`.
+	 */
+	lang?: string;
+	/** {zh}
+	 * @brief 关联语言代码。对应 `#EXT-X-MEDIA` 的 `ASSOC-LANGUAGE`。
+	 */
+	/** {en}
+	 * @brief Associated language code. Maps to `#EXT-X-MEDIA` `ASSOC-LANGUAGE`.
+	 */
+	assocLang?: string;
+	/** {zh}
+	 * @brief 轨道特征描述字符串。对应 `#EXT-X-MEDIA` 的 `CHARACTERISTICS`（如 `public.accessibility.describes-video`）。
+	 */
+	/** {en}
+	 * @brief Track characteristics string. Maps to `#EXT-X-MEDIA` `CHARACTERISTICS`.
+	 */
+	characteristics?: string;
+	/** {zh}
+	 * @brief 声道数。对应 `#EXT-X-MEDIA` 的 `CHANNELS`（如 `"2"`）。
+	 */
+	/** {en}
+	 * @brief Number of audio channels. Maps to `#EXT-X-MEDIA` `CHANNELS` (e.g. `"2"`).
+	 */
+	channels?: string;
+	/** {zh}
+	 * @brief 音轨名称，用于展示或精确匹配（如 `Stereo`）。hls.js 路径下与 `lang` 组合可唯一定位轨道。
+	 */
+	/** {en}
+	 * @brief Track name for display or precise matching (e.g. `Stereo`). With `lang`, uniquely identifies a track on the hls.js path.
+	 */
+	name?: string;
+	/** {zh}
+	 * @brief 音频编解码器标识（如 `mp4a.40.2`）。
+	 */
+	/** {en}
+	 * @brief Audio codec identifier (e.g. `mp4a.40.2`).
+	 */
+	audioCodec?: string;
+	/** {zh}
+	 * @brief 音频组 ID。对应 `#EXT-X-MEDIA` 的 `GROUP-ID`。
+	 */
+	/** {en}
+	 * @brief Audio group ID. Maps to `#EXT-X-MEDIA` `GROUP-ID`.
+	 */
+	groupId?: string;
+	/** {zh}
+	 * @brief 是否为 manifest 中的默认音轨。
+	 */
+	/** {en}
+	 * @brief Whether this is the default track declared in the manifest.
+	 */
+	default?: boolean;
+	/** {zh}
+	 * @hidden
+	 */
+	/** {en}
+	 * @hidden
+	 */
+	[key: string]: unknown;
+}
 /** Video and audio codec names supported by the player. */
 export declare const CodecType: {
 	readonly H264: "h264";
@@ -694,6 +957,9 @@ export declare const enum POSITIONS {
 /** Public event-name map shared by Lite and Full UMD constructors. */
 export interface LiteEvents {
 	readonly READY: "ready";
+	readonly HLS_LEVEL_SWITCHING: "hls_level_switching";
+	readonly HLS_LEVEL_SWITCHED: "hls_level_switched";
+	readonly HLS_ABR_LIMIT_CHANGE: "hls_abr_limit_change";
 	readonly [eventName: string]: string;
 }
 /** Legacy grouped event-name map. */
@@ -994,6 +1260,7 @@ export interface LiteStream<MediaUrl extends LiteMediaUrl = LiteMediaUrl> {
 }
 export interface LiteSubtitleConfig {
 	list?: LiteSubtitleItem[];
+	label?: ISubtitleLabelOptions;
 	defaultSubtitleId?: string | number;
 	defaultSubtitleLanguage?: string | number;
 	mode?: "external" | "native";
@@ -1158,10 +1425,13 @@ export interface LitePlayerConfig<MediaUrl extends LiteMediaUrl = LiteMediaUrl,
 	mobile?: LiteMobileConfig;
 	start?: LiteStartConfig;
 	enableHlsMSE?: boolean;
+	enableMobileHlsPlugin?: boolean;
+	enableHlsJs?: boolean;
 	hlsLevelSwitchMode?: HlsLevelSwitchMode;
 	useHlsPluginForSafari?: boolean;
 	enableMp4MSE?: boolean;
 	defaultDefinition?: string;
+	audioPreference?: AudioTrackOption;
 	plugins?: unknown[];
 	presets?: unknown[];
 	ignores?: string[];
@@ -1216,8 +1486,8 @@ export interface LiteDefinition {
 export interface LiteSubtitleItem {
 	id?: string | number;
 	language?: string | number;
-	label?: string | number;
-	text?: string;
+	label?: ISubtitleLabelValue;
+	text?: ISubtitleLabelValue;
 	url?: string;
 	isDefault?: boolean;
 	source?: "config" | "hls";
@@ -1231,6 +1501,11 @@ export interface LitePluginConstructor<Instance extends LitePluginInstance = Lit
 	readonly pluginName?: string;
 	new (...args: unknown[]): Instance;
 }
+type LiteHlsEventPayloadMap = {
+	hls_abr_limit_change: IHlsAbrLimitChangeEvent;
+	hls_level_switching: IHlsLevelSwitchEvent;
+	hls_level_switched: IHlsLevelSwitchEvent;
+};
 export interface LiteVePlayer {
 	readonly preLoadData: {
 		hit: number;
@@ -1257,6 +1532,7 @@ export interface LiteVePlayer {
 	hideSubtitle(): void;
 	next<MediaUrl extends LiteMediaUrl, StreamUrl extends LiteMediaUrl>(config: LitePlayerConfig<MediaUrl, StreamUrl>, isNewVideo?: boolean): Promise<void>;
 	off(action: string, func: (...args: unknown[]) => void): void;
+	on<EventName extends keyof LiteHlsEventPayloadMap>(action: EventName, func: (payload: LiteHlsEventPayloadMap[EventName]) => void): void;
 	on(action: string, func: (...args: unknown[]) => void): void;
 	once(action: string, func: (...args: unknown[]) => void): void;
 	playNext<MediaUrl extends LiteMediaUrl, StreamUrl extends LiteMediaUrl>(config: LitePlayerConfig<MediaUrl, StreamUrl>, isNewVideo?: boolean): Promise<unknown>;