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

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
@@ -844,7 +883,7 @@ export interface ISubTitleItem {
 	 * @brief Subtitle display name.
 	 * @default -
 	 */
-	text?: string;
+	text?: ISubtitleLabelValue;
 	/** {zh}
 	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
 	 * @default -
@@ -853,7 +892,7 @@ export interface ISubTitleItem {
 	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
 	 * @default -
 	 */
-	label?: string | number;
+	label?: ISubtitleLabelValue;
 	/** {zh}
 	 * @brief 外挂字幕 URL 地址。
 	 * @default -
@@ -883,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;
@@ -3671,6 +3822,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
@@ -5136,6 +5373,51 @@ export interface IPlayerConfig extends IPlayerOptions {
 	 * ```
 	 */
 	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
@@ -7086,7 +7368,7 @@ export interface ISubTitleItem {
 	 * @brief Subtitle display name.
 	 * @default -
 	 */
-	text?: string;
+	text?: ISubtitleLabelValue;
 	/** {zh}
 	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
 	 * @default -
@@ -7095,7 +7377,7 @@ export interface ISubTitleItem {
 	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
 	 * @default -
 	 */
-	label?: string | number;
+	label?: ISubtitleLabelValue;
 	/** {zh}
 	 * @brief 外挂字幕 URL 地址。
 	 * @default -
@@ -7125,6 +7407,15 @@ 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 type ISubtitleLabelValue = string | number | Record<string, string | number>;
 /** {zh}
  * @brief 字幕内容项。
  * @list Options
@@ -9954,6 +10245,7 @@ export declare class Subtitle extends Plugin {
 			"zh-hk": string;
 		};
 	};
+	updateLang(lang: string): void;
 	creatOptionList(): void;
 	getList(): any;
 	renderOptionList(): void;