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

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
@@ -6908,6 +7190,7 @@ declare class AuthToken extends SdkPlugin {
 	beforePlayerCreate(): Promise<void>;
 	getVideoInfo(sourceConfigs?: IPlayerConfig): Promise<{
 		vid: string;
+		__mediaInfoCacheHit: boolean;
 		playList: Stream[];
 		codec: ICodecType;
 		defaultDefinition: string;
@@ -7086,7 +7369,7 @@ export interface ISubTitleItem {
 	 * @brief Subtitle display name.
 	 * @default -
 	 */
-	text?: string;
+	text?: ISubtitleLabelValue;
 	/** {zh}
 	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
 	 * @default -
@@ -7095,7 +7378,7 @@ export interface ISubTitleItem {
 	 * @brief 字幕名称。兼容 xgplayer-subtitles 的 label 字段。
 	 * @default -
 	 */
-	label?: string | number;
+	label?: ISubtitleLabelValue;
 	/** {zh}
 	 * @brief 外挂字幕 URL 地址。
 	 * @default -
@@ -7125,6 +7408,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 +10246,7 @@ export declare class Subtitle extends Plugin {
 			"zh-hk": string;
 		};
 	};
+	updateLang(lang: string): void;
 	creatOptionList(): void;
 	getList(): any;
 	renderOptionList(): void;
@@ -10422,348 +10715,55 @@ export declare const Events: {
 	 * @brief Triggered when mirror mode is enabled.
 	 */
 	MIRROR_CHANGE: string;
-	/** {zh}
-	 * @brief 播放器实例创建完成时触发。
-	 */
-	/** {en}
-	 * @brief Triggered when the player instance is created.
-	 */
-	READY: string;
-	/** {zh}
-	 * @brief 播放器创建 `video` 完成时触发，表示可以开始播放。
-	 */
-	/** {en}
-	 * @brief Triggered when the player has created the `video` element and playback can start.
-	 */
-	COMPLETE: string;
-	/** {zh}
-	 * @brief 播放资源发生变化。
-	 */
-	/** {en}
-	 * @brief Triggered when the playback resource changes.
-	 */
-	URL_CHANGE: string;
-	/** {zh}
-	 * @brief 播放器聚焦，同时会展示 Control 栏控件，包含播放按钮、进度条等。
-	 */
-	/** {en}
-	 * @brief Triggered when the player gains focus; the control bar is shown.
-	 */
-	PLAYER_FOCUS: string;
-	/** {zh}
-	 * @brief 播放器失焦，同时会隐藏 Control 栏控件，包含播放按钮、进度条等。
-	 */
-	/** {en}
-	 * @brief Triggered when the player loses focus; the control bar is hidden.
-	 */
-	PLAYER_BLUR: string;
-	/** {zh}
-	 * @brief 系统全屏状态切换。
-	 */
-	/** {en}
-	 * @brief Triggered when native fullscreen state changes.
-	 */
-	FULLSCREEN_CHANGE: string;
-	/** {zh}
-	 * @brief 网页全屏状态切换。
-	 */
-	/** {en}
-	 * @brief Triggered when CSS fullscreen state changes.
-	 */
-	CSS_FULLSCREEN_CHANGE: string;
-	/** {zh}
-	 * @brief 画中画模式切换。
-	 */
-	/** {en}
-	 * @brief Triggered when mini player (floating) mode changes.
-	 */
-	MINI_STATE_CHANGE: string;
-	/** {zh}
-	 * @brief 播放器销毁。
-	 */
-	/** {en}
-	 * @brief Triggered when the player is destroyed.
-	 */
-	DESTROY: string;
-	/** {zh}
-	 * @brief 播放器重新播放。
-	 */
-	/** {en}
-	 * @brief Triggered when replay starts.
-	 */
-	REPLAY: string;
-	/** {zh}
-	 * @brief 播放器重试。
-	 */
-	/** {en}
-	 * @brief Triggered when the player retries playback.
-	 */
-	RETRY: string;
-	/** {zh}
-	 * @brief 清晰度发生变化
-	 */
-	/** {en}
-	 * @brief Triggered when the definition (resolution) changes.
-	 */
-	DEFINITION_CHANGE: string;
-	/** {zh}
-	 * @hidden
-	 */
-	/** {en}
-	 * @hidden
-	 */
-	Before_DEFINITION_CHANGE: string;
-	/** {zh}
-	 * @hidden
-	 */
-	/** {en}
-	 * @hidden
-	 */
-	AFTER_DEFINITION_CHANGE: string;
-	/** {zh}
-	 * @brief 播放器容器尺寸发生变化。
-	 */
-	/** {en}
-	 * @brief Triggered when the player container size changes.
-	 */
-	VIDEO_RESIZE: string;
-	/** {zh}
-	 * @brief 画中画状态切换。
-	 */
-	/** {en}
-	 * @brief Triggered when Picture-in-Picture state changes.
-	 */
-	PIP_CHANGE: string;
-	/** {zh}
-	 * @brief 播放器发生旋转。
-	 */
-	/** {en}
-	 * @brief Triggered when the player is rotated.
-	 */
-	ROTATE: string;
-	/** {zh}
-	 * @brief 播放器内置快捷键事件被触发。
-	 */
-	/** {en}
-	 * @brief Triggered when a built-in keyboard shortcut is used.
-	 */
-	SHORTCUT: string;
-	/** {zh}
-	 * @deprecated
-	 * @brief （已废弃）SEI 信息解析。
-	 */
-	/** {en}
-	 * @deprecated
-	 * @brief (Deprecated) SEI information parsing.
-	 */
-	SEI_PARSED: string;
-	/** {zh}
-	 * @brief 内置插件用户行为触发。所有内置插件用户行为交互都会下发该事件，可用于用户行为埋点。
-	 */
-	/** {en}
-	 * @brief Triggered when user actions within plugins are performed. All plugin user actions will trigger this event, which can be used for user behavior tracking.
-	 */
-	USER_ACTION: string;
-	/** {zh}
-	 * @brief 自动播放成功时触发。
-	 */
-	/** {en}
-	 * @brief Triggered when autoplay succeeds.
-	 */
-	AUTOPLAY_STARTED: string;
-	/** {zh}
-	 * @brief 自动播放失败时触发。
-	 */
-	/** {en}
-	 * @brief Triggered when autoplay fails.
-	 */
-	AUTOPLAY_PREVENTED: string;
-	/** {zh}
-	 * @brief 播放器准备创建。
-	 */
-	READY_CREATE_PLAYER: string;
-	/** {zh}
-	 * @brief 播放器完成创建。
-	 */
-	/** {en}
-	 * @brief Triggered when player creation completes.
-	 */
-	PLAYER_CREATED_FINISH: string;
-	/** {zh}
-	 * @brief createPlayer 性能报告。与 `PLAYER_CREATED_FINISH` 几乎同时触发（略早）。
-	 */
-	/** {en}
-	 * @brief createPlayer performance report. Fired almost at the same time as `PLAYER_CREATED_FINISH` (slightly earlier).
-	 */
-	CREATE_PLAYER_PERF: string;
-	/** {zh}
-	 * @brief 播放器重建。
-	 */
-	/** {en}
-	 * @brief Triggered when the player is rebuilt.
-	 */
-	PLAYER_REBUILD: string;
-	/** {zh}
-	 * @brief 硬解不支持时触发。
-	 */
-	/** {en}
-	 * @brief Triggered when hardware decoding is not supported.
-	 */
-	NOT_SUPPORT_HARDWARE_DECODER: string;
-	/** {zh}
-	 * @brief 软解不支持时触发。
-	 */
-	/** {en}
-	 * @brief Triggered when software decoding is not supported.
-	 */
-	NOT_SUPPORT_SOFT_DECODER: string;
-	/** {zh}
-	 * @brief `playAuthToken` 过期。
-	 */
-	/** {en}
-	 * @brief Triggered when `playAuthToken` expires.
-	 */
-	TOKEN_EXPIRED: string;
-	/** {zh}
-	 * @brief UMD 加载失败。
-	 */
-	/** {en}
-	 * @brief Triggered when UMD loading fails.
-	 */
-	UMD_LOAD_FAIL: string;
-	/** {zh}
-	 * @brief 切换下一个视频。调用 `playNext` 后触发。
-	 */
-	/** {en}
-	 * @brief Triggered when switching to the next video, after calling `playNext`.
-	 */
-	PLAYNEXT: string;
-	/** {zh}
-	 * @brief 视频地址为空。
-	 */
-	/** {en}
-	 * @brief Triggered when the video URL is empty.
-	 */
-	URL_NULL: string;
-	/** {zh}
-	 * @brief 鼠标移出。
-	 */
-	/** {en}
-	 * @brief Triggered when the mouse leaves the player.
-	 */
-	LEAVE_PLAYER: string;
-	/** {zh}
-	 * @brief 鼠标移入。
-	 */
-	/** {en}
-	 * @brief Triggered when the mouse enters the player.
-	 */
-	ENTER_PLAYER: string;
-	/** {zh}
-	 * @brief 播放器状态重置。
-	 */
-	/** {en}
-	 * @brief Triggered when the player state is reset.
-	 */
-	RESET: string;
-	/** {zh}
-	 * @brief `<source>` 加载错误，表示 `<source>` 不支持或播放失败。
-	 */
-	/** {en}
-	 * @brief Triggered when a `<source>` fails to load (unsupported or playback failed).
-	 */
-	SOURCE_ERROR: string;
-	/** {zh}
-	 * @brief `<source>` 加载成功。
-	 */
-	/** {en}
-	 * @brief Triggered when a `<source>` loads successfully.
-	 */
-	SOURCE_SUCCESS: string;
-	/** {zh}
-	 * @brief license 提醒
-	 */
-	/** {en}
-	 * @brief License status warning.
-	 */
-	LICENSE_STATUS_WARNING: string;
-	/** {zh}
-	 * @brief HLS 音频轨道列表更新时触发。`data.audioTracks` 为完整轨道数组。
-	 */
-	/** {en}
-	 * @brief Triggered when the HLS audio track list updates. `data.audioTracks` is the full track array.
-	 */
-	AUDIO_TRACKS_UPDATED: string;
-	/** {zh}
-	 * @brief 音频轨道切换完成时触发。`data.id` 为新轨道 id，`data.audioTrack` 为完整轨道对象。
-	 */
-	/** {en}
-	 * @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;
+	READY: "ready";
+	COMPLETE: "complete";
+	URL_CHANGE: "urlchange";
+	PLAYER_FOCUS: "focus";
+	PLAYER_BLUR: "blur";
+	FULLSCREEN_CHANGE: "fullscreen_change";
+	CSS_FULLSCREEN_CHANGE: "cssFullscreen_change";
+	MINI_STATE_CHANGE: "mini_state_change";
+	DESTROY: "destroy";
+	REPLAY: "replay";
+	RETRY: "retry";
+	DEFINITION_CHANGE: "definition_change";
+	Before_DEFINITION_CHANGE: "before_definition_change";
+	AFTER_DEFINITION_CHANGE: "after_definition_change";
+	VIDEO_RESIZE: "video_resize";
+	PIP_CHANGE: "pip_change";
+	ROTATE: "rotate";
+	SHORTCUT: "shortcut";
+	SEI_PARSED: "SEI_PARSED";
+	USER_ACTION: "user_action";
+	AUTOPLAY_STARTED: "autoplay_started";
+	AUTOPLAY_PREVENTED: "autoplay_was_prevented";
+	READY_CREATE_PLAYER: "ready_create_player";
+	PLAYER_CREATED_FINISH: "player_create_finish";
+	CREATE_PLAYER_PERF: "create_player_perf";
+	PLAYER_REBUILD: "player_rebuild";
+	NOT_SUPPORT_HARDWARE_DECODER: "not_support_hardware_decoder";
+	NOT_SUPPORT_SOFT_DECODER: "not_support_soft_decoder";
+	TOKEN_EXPIRED: "playAuthToken_expired";
+	UMD_LOAD_FAIL: "umd_load_fail";
+	PLAYNEXT: "playnext";
+	URL_NULL: "urlNull";
+	LEAVE_PLAYER: "leaveplayer";
+	ENTER_PLAYER: "enterplayer";
+	RESET: "reset";
+	SOURCE_ERROR: "source_error";
+	SOURCE_SUCCESS: "source_success";
+	LICENSE_STATUS_WARNING: "license_status_warning";
+	AUDIO_TRACKS_UPDATED: "audio_tracks_updated";
+	AUDIO_TRACK_CHANGE: "audio_track_change";
+	HLS_LEVELS_UPDATED: "hls_levels_updated";
+	HLS_LEVEL_SWITCHING: "hls_level_switching";
+	HLS_LEVEL_SWITCHED: "hls_level_switched";
+	HLS_ABR_ENGINE_RESOLVED: "hls_abr_engine_resolved";
+	HLS_ABR_STATE_CHANGE: "hls_abr_state_change";
+	HLS_ABR_LIMIT_CHANGE: "hls_abr_limit_change";
+	HLS_SUBTITLE_TRACKS_UPDATED: "hls_subtitle_tracks_updated";
+	HLS_SUBTITLE_TRACK_SWITCHING: "hls_subtitle_track_switching";
+	HLS_SUBTITLE_TRACK_SWITCHED: "hls_subtitle_track_switched";
 	/** {zh}
 	 * @brief 在播放被终止时触发。例如当播放中的视频重新开始播放。
 	 */
@@ -10936,126 +10936,126 @@ export declare const Event: {
 		/** {en}
 		 * @brief Triggered when the player instance is created.
 		 */
-		READY: string;
+		readonly READY: "ready";
 		/** {zh}
 		 * @brief 播放器创建 `video` 完成时触发，表示可以开始播放。
 		 */
 		/** {en}
 		 * @brief Triggered when the player has created the `video` element and playback can start.
 		 */
-		COMPLETE: string;
+		readonly COMPLETE: "complete";
 		/** {zh}
 		 * @brief 播放资源发生变化。
 		 */
 		/** {en}
 		 * @brief Triggered when the playback resource changes.
 		 */
-		URL_CHANGE: string;
+		readonly URL_CHANGE: "urlchange";
 		/** {zh}
 		 * @brief 播放器聚焦，同时会展示 Control 栏控件，包含播放按钮、进度条等。
 		 */
 		/** {en}
 		 * @brief Triggered when the player gains focus; the control bar is shown.
 		 */
-		PLAYER_FOCUS: string;
+		readonly PLAYER_FOCUS: "focus";
 		/** {zh}
 		 * @brief 播放器失焦，同时会隐藏 Control 栏控件，包含播放按钮、进度条等。
 		 */
 		/** {en}
 		 * @brief Triggered when the player loses focus; the control bar is hidden.
 		 */
-		PLAYER_BLUR: string;
+		readonly PLAYER_BLUR: "blur";
 		/** {zh}
 		 * @brief 系统全屏状态切换。
 		 */
 		/** {en}
 		 * @brief Triggered when native fullscreen state changes.
 		 */
-		FULLSCREEN_CHANGE: string;
+		readonly FULLSCREEN_CHANGE: "fullscreen_change";
 		/** {zh}
 		 * @brief 网页全屏状态切换。
 		 */
 		/** {en}
 		 * @brief Triggered when CSS fullscreen state changes.
 		 */
-		CSS_FULLSCREEN_CHANGE: string;
+		readonly CSS_FULLSCREEN_CHANGE: "cssFullscreen_change";
 		/** {zh}
 		 * @brief 画中画模式切换。
 		 */
 		/** {en}
 		 * @brief Triggered when mini player (floating) mode changes.
 		 */
-		MINI_STATE_CHANGE: string;
+		readonly MINI_STATE_CHANGE: "mini_state_change";
 		/** {zh}
 		 * @brief 播放器销毁。
 		 */
 		/** {en}
 		 * @brief Triggered when the player is destroyed.
 		 */
-		DESTROY: string;
+		readonly DESTROY: "destroy";
 		/** {zh}
 		 * @brief 播放器重新播放。
 		 */
 		/** {en}
 		 * @brief Triggered when replay starts.
 		 */
-		REPLAY: string;
+		readonly REPLAY: "replay";
 		/** {zh}
 		 * @brief 播放器重试。
 		 */
 		/** {en}
 		 * @brief Triggered when the player retries playback.
 		 */
-		RETRY: string;
+		readonly RETRY: "retry";
 		/** {zh}
 		 * @brief 清晰度发生变化
 		 */
 		/** {en}
 		 * @brief Triggered when the definition (resolution) changes.
 		 */
-		DEFINITION_CHANGE: string;
+		readonly DEFINITION_CHANGE: "definition_change";
 		/** {zh}
 		 * @hidden
 		 */
 		/** {en}
 		 * @hidden
 		 */
-		Before_DEFINITION_CHANGE: string;
+		readonly Before_DEFINITION_CHANGE: "before_definition_change";
 		/** {zh}
 		 * @hidden
 		 */
 		/** {en}
 		 * @hidden
 		 */
-		AFTER_DEFINITION_CHANGE: string;
+		readonly AFTER_DEFINITION_CHANGE: "after_definition_change";
 		/** {zh}
 		 * @brief 播放器容器尺寸发生变化。
 		 */
 		/** {en}
 		 * @brief Triggered when the player container size changes.
 		 */
-		VIDEO_RESIZE: string;
+		readonly VIDEO_RESIZE: "video_resize";
 		/** {zh}
 		 * @brief 画中画状态切换。
 		 */
 		/** {en}
 		 * @brief Triggered when Picture-in-Picture state changes.
 		 */
-		PIP_CHANGE: string;
+		readonly PIP_CHANGE: "pip_change";
 		/** {zh}
 		 * @brief 播放器发生旋转。
 		 */
 		/** {en}
 		 * @brief Triggered when the player is rotated.
 		 */
-		ROTATE: string;
+		readonly ROTATE: "rotate";
 		/** {zh}
 		 * @brief 播放器内置快捷键事件被触发。
 		 */
 		/** {en}
 		 * @brief Triggered when a built-in keyboard shortcut is used.
 		 */
-		SHORTCUT: string;
+		readonly SHORTCUT: "shortcut";
 		/** {zh}
 		 * @deprecated
 		 * @brief （已废弃）SEI 信息解析。
@@ -11064,214 +11064,214 @@ export declare const Event: {
 		 * @deprecated
 		 * @brief (Deprecated) SEI information parsing.
 		 */
-		SEI_PARSED: string;
+		readonly SEI_PARSED: "SEI_PARSED";
 		/** {zh}
 		 * @brief 内置插件用户行为触发。所有内置插件用户行为交互都会下发该事件，可用于用户行为埋点。
 		 */
 		/** {en}
 		 * @brief Triggered when user actions within plugins are performed. All plugin user actions will trigger this event, which can be used for user behavior tracking.
 		 */
-		USER_ACTION: string;
+		readonly USER_ACTION: "user_action";
 		/** {zh}
 		 * @brief 自动播放成功时触发。
 		 */
 		/** {en}
 		 * @brief Triggered when autoplay succeeds.
 		 */
-		AUTOPLAY_STARTED: string;
+		readonly AUTOPLAY_STARTED: "autoplay_started";
 		/** {zh}
 		 * @brief 自动播放失败时触发。
 		 */
 		/** {en}
 		 * @brief Triggered when autoplay fails.
 		 */
-		AUTOPLAY_PREVENTED: string;
+		readonly AUTOPLAY_PREVENTED: "autoplay_was_prevented";
 		/** {zh}
 		 * @brief 播放器准备创建。
 		 */
-		READY_CREATE_PLAYER: string;
+		readonly READY_CREATE_PLAYER: "ready_create_player";
 		/** {zh}
 		 * @brief 播放器完成创建。
 		 */
 		/** {en}
 		 * @brief Triggered when player creation completes.
 		 */
-		PLAYER_CREATED_FINISH: string;
+		readonly PLAYER_CREATED_FINISH: "player_create_finish";
 		/** {zh}
 		 * @brief createPlayer 性能报告。与 `PLAYER_CREATED_FINISH` 几乎同时触发（略早）。
 		 */
 		/** {en}
 		 * @brief createPlayer performance report. Fired almost at the same time as `PLAYER_CREATED_FINISH` (slightly earlier).
 		 */
-		CREATE_PLAYER_PERF: string;
+		readonly CREATE_PLAYER_PERF: "create_player_perf";
 		/** {zh}
 		 * @brief 播放器重建。
 		 */
 		/** {en}
 		 * @brief Triggered when the player is rebuilt.
 		 */
-		PLAYER_REBUILD: string;
+		readonly PLAYER_REBUILD: "player_rebuild";
 		/** {zh}
 		 * @brief 硬解不支持时触发。
 		 */
 		/** {en}
 		 * @brief Triggered when hardware decoding is not supported.
 		 */
-		NOT_SUPPORT_HARDWARE_DECODER: string;
+		readonly NOT_SUPPORT_HARDWARE_DECODER: "not_support_hardware_decoder";
 		/** {zh}
 		 * @brief 软解不支持时触发。
 		 */
 		/** {en}
 		 * @brief Triggered when software decoding is not supported.
 		 */
-		NOT_SUPPORT_SOFT_DECODER: string;
+		readonly NOT_SUPPORT_SOFT_DECODER: "not_support_soft_decoder";
 		/** {zh}
 		 * @brief `playAuthToken` 过期。
 		 */
 		/** {en}
 		 * @brief Triggered when `playAuthToken` expires.
 		 */
-		TOKEN_EXPIRED: string;
+		readonly TOKEN_EXPIRED: "playAuthToken_expired";
 		/** {zh}
 		 * @brief UMD 加载失败。
 		 */
 		/** {en}
 		 * @brief Triggered when UMD loading fails.
 		 */
-		UMD_LOAD_FAIL: string;
+		readonly UMD_LOAD_FAIL: "umd_load_fail";
 		/** {zh}
 		 * @brief 切换下一个视频。调用 `playNext` 后触发。
 		 */
 		/** {en}
 		 * @brief Triggered when switching to the next video, after calling `playNext`.
 		 */
-		PLAYNEXT: string;
+		readonly PLAYNEXT: "playnext";
 		/** {zh}
 		 * @brief 视频地址为空。
 		 */
 		/** {en}
 		 * @brief Triggered when the video URL is empty.
 		 */
-		URL_NULL: string;
+		readonly URL_NULL: "urlNull";
 		/** {zh}
 		 * @brief 鼠标移出。
 		 */
 		/** {en}
 		 * @brief Triggered when the mouse leaves the player.
 		 */
-		LEAVE_PLAYER: string;
+		readonly LEAVE_PLAYER: "leaveplayer";
 		/** {zh}
 		 * @brief 鼠标移入。
 		 */
 		/** {en}
 		 * @brief Triggered when the mouse enters the player.
 		 */
-		ENTER_PLAYER: string;
+		readonly ENTER_PLAYER: "enterplayer";
 		/** {zh}
 		 * @brief 播放器状态重置。
 		 */
 		/** {en}
 		 * @brief Triggered when the player state is reset.
 		 */
-		RESET: string;
+		readonly RESET: "reset";
 		/** {zh}
 		 * @brief `<source>` 加载错误，表示 `<source>` 不支持或播放失败。
 		 */
 		/** {en}
 		 * @brief Triggered when a `<source>` fails to load (unsupported or playback failed).
 		 */
-		SOURCE_ERROR: string;
+		readonly SOURCE_ERROR: "source_error";
 		/** {zh}
 		 * @brief `<source>` 加载成功。
 		 */
 		/** {en}
 		 * @brief Triggered when a `<source>` loads successfully.
 		 */
-		SOURCE_SUCCESS: string;
+		readonly SOURCE_SUCCESS: "source_success";
 		/** {zh}
 		 * @brief license 提醒
 		 */
 		/** {en}
 		 * @brief License status warning.
 		 */
-		LICENSE_STATUS_WARNING: string;
+		readonly LICENSE_STATUS_WARNING: "license_status_warning";
 		/** {zh}
 		 * @brief HLS 音频轨道列表更新时触发。`data.audioTracks` 为完整轨道数组。
 		 */
 		/** {en}
 		 * @brief Triggered when the HLS audio track list updates. `data.audioTracks` is the full track array.
 		 */
-		AUDIO_TRACKS_UPDATED: string;
+		readonly AUDIO_TRACKS_UPDATED: "audio_tracks_updated";
 		/** {zh}
 		 * @brief 音频轨道切换完成时触发。`data.id` 为新轨道 id，`data.audioTrack` 为完整轨道对象。
 		 */
 		/** {en}
 		 * @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;
+		readonly AUDIO_TRACK_CHANGE: "audio_track_change";
 		/** {zh}
 		 * @brief 当前播放会话的 HLS Level 列表或状态更新。
 		 */
 		/** {en}
 		 * @brief Triggered when the HLS Level list or state updates for the current playback session.
 		 */
-		HLS_LEVELS_UPDATED: string;
+		readonly HLS_LEVELS_UPDATED: "hls_levels_updated";
 		/** {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;
+		readonly HLS_LEVEL_SWITCHING: "hls_level_switching";
 		/** {zh}
 		 * @brief HLS Level 已实际切换。
 		 */
 		/** {en}
 		 * @brief Triggered after the active HLS Level has actually switched.
 		 */
-		HLS_LEVEL_SWITCHED: string;
+		readonly HLS_LEVEL_SWITCHED: "hls_level_switched";
 		/** {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;
+		readonly HLS_ABR_ENGINE_RESOLVED: "hls_abr_engine_resolved";
 		/** {zh}
 		 * @brief HLS ABR 的可用性、自动/手动模式或激活状态发生变化。
 		 */
 		/** {en}
 		 * @brief Triggered when HLS ABR availability, auto/manual mode, or active state changes.
 		 */
-		HLS_ABR_STATE_CHANGE: string;
+		readonly HLS_ABR_STATE_CHANGE: "hls_abr_state_change";
 		/** {zh}
 		 * @brief HLS ABR 上限发生变化。
 		 */
 		/** {en}
 		 * @brief Triggered when the HLS ABR cap changes.
 		 */
-		HLS_ABR_LIMIT_CHANGE: string;
+		readonly HLS_ABR_LIMIT_CHANGE: "hls_abr_limit_change";
 		/** {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;
+		readonly HLS_SUBTITLE_TRACKS_UPDATED: "hls_subtitle_tracks_updated";
 		/** {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;
+		readonly HLS_SUBTITLE_TRACK_SWITCHING: "hls_subtitle_track_switching";
 		/** {zh}
 		 * @brief HLS 字幕轨切换已经生效。
 		 */
 		/** {en}
 		 * @brief Triggered after an HLS subtitle-track switch takes effect.
 		 */
-		HLS_SUBTITLE_TRACK_SWITCHED: string;
+		readonly HLS_SUBTITLE_TRACK_SWITCHED: "hls_subtitle_track_switched";
 	};
 	PluginEvents: {
 		/** {zh}