@byteplus/amk-editor 0.0.0-beta.1

package/dist/types.d.ts

@@ -0,0 +1,344 @@
+import type { VeVeditorI18nOptions, VeVeditorMaterialItem, VeVeditorMaterialOptions, VeVeditorOptions, VeVeditorTheme, VeVeditorDecodeOptions } from './public-types';
+export type Theme = VeVeditorTheme;
+export interface MaterialItem extends VeVeditorMaterialItem {
+    /** 业务侧素材主键；上传 / 更新 / 删除必填。 */
+    source_material_id: string;
+    /** Editing API 生成的服务端 id；业务方不必传，传了也不会入库。 */
+    material_id?: string;
+    /** poster 抽帧任务 ID；任务完成或不再使用时显式写回 null。 */
+    poster_task_id?: string | null;
+    /** sprite 抽帧任务 ID；任务完成或不再使用时显式写回 null。 */
+    sprite_task_id?: string | null;
+}
+export type SystemMaterialItem = Omit<Partial<MaterialItem>, 'source_material_id' | 'source'> & {
+    source_material_id: string;
+    source?: string;
+    type: NonNullable<MaterialItem['type']>;
+    name?: string;
+};
+/** 可由外部工具栏复用的素材导入入口。 */
+export type AmkMaterialImportType = 'local' | 'url' | 'system';
+/** Optional callbacks scoped to one externally triggered material import. */
+export interface AmkMaterialImportRequestOptions {
+    /** Called with persisted materials only for this request. */
+    onMaterialsImported?: (materials: MaterialItem[]) => void | Promise<void>;
+}
+/**
+ * 抽帧产物的稳定存储身份。TOS 产物会保存完整 `tos://bucket/key`，
+ * SDK 用它在签名 URL 过期后重新签发；非 TOS 业务仍可使用自定义字段。
+ */
+export interface RecommendedExtractStorageFields {
+    /** 封面图稳定身份；内置 TOS 链路保存 `tos://bucket/key`。 */
+    poster_storage_key?: string;
+    /** 与 sprite.storeurls 等长的稳定身份数组；内置链路保存 tos:// 或 vod:// 地址。 */
+    sprite_storage_keys?: string[];
+}
+export interface PersistExtractUrlsResult {
+    /** 转存后的长期可访问 URL，须与回调入参 urls 等长。 */
+    urls: string[];
+    /**
+     * 随转存结果写回素材的业务字段，SDK 原样合并并持久化。
+     * 字段名和结构完全由业务决定；SDK 不读取推荐字段，也不限制自定义嵌套结构。
+     */
+    materialPatch?: Partial<MaterialItem>;
+}
+export interface MaterialConfig extends VeVeditorMaterialOptions<MaterialItem> {
+    /**
+     * 本地单文件上传流程的并发上限（正整数）；未配置时保持不限并发。
+     * 同一编辑器跨批次共享；覆盖上传、元信息补齐及入库，不含后台抽帧。
+     * 适用于 onUploadFile 和内置上传，不控制旧 onUploadMaterial 的内部并发。
+     * 此值不是每秒请求数，也不控制单文件分片并发。
+     */
+    uploadConcurrency?: number;
+    uploadAccept?: string;
+    /** Fires when any material import flow enters or leaves its uploading phase. */
+    onUploadStatusChange?: (uploading: boolean) => void;
+    /**
+     * 上传单个本地文件并返回一条待入库素材。
+     * 多文件选择时由 SDK 并发调用；每个文件完成后会立即入库并替换对应占位卡。
+     * 单项失败不会回滚已成功的其他文件。
+     * 视频缺 duration / width / height、音频缺 duration、图片缺 width / height 时，
+     * SDK 会在入库前使用返回素材中的 HTTP(S) 地址自动探测并补齐。
+     */
+    onUploadFile?: (file: File) => Promise<MaterialItem> | MaterialItem;
+    /**
+     * @deprecated 请使用 onUploadFile。旧回调仍可用，但只能在整批返回后统一入库。
+     * 返回素材缺少必需元信息时，SDK 同样会在入库前自动探测并补齐。
+     */
+    onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
+    /** 返回素材缺少必需元信息时，SDK 会在入库前按媒体类型自动探测并补齐。 */
+    onUploadUrlMaterial?: (urls: string[]) => Promise<MaterialItem[]> | MaterialItem[];
+    /**
+     * 从业务资产库选择素材。业务方自行实现弹窗、列表查询与勾选，只返回选中数组。
+     * 同时配置 TOS `storage.media_output_destination` 与 `storage.getUploadSTS` 时，
+     * `tos://bucket/key` 条目会由 SDK 自动签名和补齐元信息；否则使用业务提供的
+     * HTTP(S) 长期地址，缺少地址时交给 `onRefreshPlayInfo` 补齐。
+     * 非 TOS 条目缺少必需元信息时，也会使用其 HTTP(S) 地址自动探测并补齐。
+     * 返回 `undefined` / `null` / `[]` 视为取消或未选择，不提示失败。
+     */
+    onUploadFromSystem?: () => Promise<SystemMaterialItem[] | undefined | null> | SystemMaterialItem[] | undefined | null;
+    /**
+     * 素材成功入库后回调（已合并 Editing API 返回的 `material_id`）。
+     * 本地 / URL / 资产库三条导入链路都会走到这里；失败或用户取消不会触发。
+     */
+    onMaterialsImported?: (materials: MaterialItem[]) => void | Promise<void>;
+    /**
+     * 刷新播放信息。未配置时用素材库已有字段；
+     * 配置后：入参为待刷新素材列表，支持批量；返回补丁优先按 material_id 匹配，
+     * source_material_id 次之，两者都未返回时才按数组顺序兜底，
+     * 返回单条或数组补丁覆盖原素材的播放字段（url / poster / sprite / source_material_id 等）。
+     * 补丁不得改写 material_id（服务端字段，业务传了也不入库）。
+     */
+    onRefreshPlayInfo?: (materials: MaterialItem[]) => Partial<MaterialItem> | Partial<MaterialItem>[] | Promise<Partial<MaterialItem> | Partial<MaterialItem>[]>;
+    /**
+     * 抽帧得到的临时 http（约 24h）转存成长效地址。
+     * SDK 会先用临时链上屏/落盘，再后台调用本回调换链；失败则保留临时链。
+     * 未配置则只落盘临时链；签名明确过期且图片加载失败时，SDK 最多刷新一次播放地址，不重抽。
+     * 推荐返回 urls + materialPatch，把刷新 URL 所需的 storage key 或其他业务字段写入素材。
+     * SDK 不限制其他 materialPatch 字段；poster_storage_key / sprite_storage_keys
+     * 中的 `tos://` 地址会作为后续自动重签依据。
+     * 兼容只返回 string[]，但该形式无法附带业务字段。
+     */
+    onPersistExtractUrls?: (params: {
+        kind: 'poster' | 'sprite';
+        urls: string[];
+        material: MaterialItem;
+    }) => Promise<PersistExtractUrlsResult | string[]> | PersistExtractUrlsResult | string[];
+}
+export interface AmkEditorHeaderTitleUpdateSuccess {
+    readonly projectId: string;
+    /** Project title persisted successfully by the Editing API. */
+    readonly title: string;
+}
+export interface AmkEditorHeaderConfig {
+    show?: boolean;
+    /** 是否展示导出任务列表入口，默认开启。 */
+    exportTaskList?: boolean;
+    /**
+     * When set, the header is rendered into this element instead of inside the
+     * editor root. Use this to place a full-width header above a host split layout.
+     */
+    mount?: HTMLElement;
+    onBack?: () => void;
+    onClose?: () => void;
+    /** Fired only after the project title is persisted successfully. */
+    onTitleUpdateSuccess?: (change: AmkEditorHeaderTitleUpdateSuccess) => void;
+}
+export interface AmkEditorExportConfig {
+    /** 临时兼容旧 vibe-editing-common 导出；默认 false，后续可移除。 */
+    legacy?: boolean;
+    /**
+     * 导出弹窗是否展示「视频画质增强」。
+     * 默认 false（不展示）；设为 true 后用户可在弹窗内开关增强。
+     */
+    qualityEnhancement?: boolean;
+    /** 每次导出任务成功创建后触发。 */
+    onTaskCreated?: (event: AmkExportTaskCreatedEvent) => void | Promise<void>;
+}
+/** 浏览器直传 TOS 使用的临时凭证；字段可直接用于初始化 TOS Browser SDK。 */
+export interface AmkEditorUploadSTSCredentials {
+    accessKeyId: string;
+    accessKeySecret: string;
+    /** 临时凭证必填；使用长期 AK/SK 做本地联调时可省略。 */
+    stsToken?: string;
+    /** 凭证过期时间，支持 ISO 8601、秒时间戳或毫秒时间戳；用于限制签名 URL 有效期。 */
+    expiration?: string | number;
+}
+/** 点播 Web 上传及 OpenAPI 发布/播放查询共用的短期 STS 凭证。 */
+export interface AmkEditorVodUploadToken {
+    AccessKeyId: string;
+    SecretAccessKey: string;
+    SessionToken: string;
+    ExpiredTime: string;
+    CurrentTime: string;
+}
+/** 按 Vid 解析的可播放信息。 */
+export interface AmkEditorVodPlayInfo {
+    url: string;
+    poster?: string;
+    duration?: number;
+    width?: number;
+    height?: number;
+}
+/** SDK 内部点播上传与播放地址解析配置，由 storage 目标和临时凭证回调生成。 */
+export interface AmkEditorVodUploadConfig {
+    /** 应用云平台分配的 appId，仅用于上传质量监控。 */
+    appId: number;
+    /** 火山引擎点播空间名。 */
+    spaceName: string;
+    /** 当前用户稳定标识，用于上传任务隔离与断点续传。 */
+    userId: string;
+    /** 由宿主服务端签发短期点播 STS。 */
+    getUploadToken: () => AmkEditorVodUploadToken | Promise<AmkEditorVodUploadToken>;
+    /**
+     * 由宿主服务端发布媒资（如需要）并按 Vid 返回 HTTP(S) 播放地址。
+     * SDK 会用该回调处理新上传素材、已入库 VOD 素材和 VOD 导出结果的播放地址。
+     */
+    getPlayInfo: (vid: string, kind?: 'vid') => AmkEditorVodPlayInfo | Promise<AmkEditorVodPlayInfo>;
+}
+/**
+ * 产物 / 主动上传的存储目标。
+ * `media_output_destination` 用于 SDK 内置上传的目标定位。火山版会默认将其写入会产生媒体产物的
+ * AMK tools 请求体以启用产物转存；BytePlus AMK 暂不支持产物转存，因此 BytePlus 构建不会把
+ * 该字段发送给 AMK 接口；该配置仍用于内置 BytePlus VOD 上传与播放地址解析，
+ * 并作为后续 BytePlus TOS 接入入口。
+ * @see https://docs.volcengine.com/docs/6448/2386113
+ */
+export interface AmkEditorStorageConfig {
+    /**
+     * 处理产物存储目标。支持 `vod://<空间名>` 或 `tos://<桶名>/<可选子目录>`。
+     * TOS 本地上传及自动封面/雪碧图产物使用配置的目录，不自动追加项目 ID。
+     * 必须与 `getUploadSTS` 同时配置；只配置其中任意一个都会在初始化时报错。
+     * 配置后任务结果中的 url 为对应资源地址，而不是临时下载链；当返回
+     * `tos://bucket/key` 或 `vod://space/Vid` 时，SDK 会分别通过 TOS 签名或
+     * VOD 播放信息接口换取 HTTP(S) 预览地址。
+     */
+    media_output_destination?: string;
+    /**
+     * TOS 目标返回 TOS STS，VOD 目标返回含上传、发布和播放查询权限的短期 STS；
+     * 必须与 media_output_destination 同时配置；只配置其中任意一个都会在初始化时报错。
+     * SDK 按目标协议选择内置上传与播放地址刷新链路。
+     * 本地上传优先使用业务配置的 `material.onUploadFile` / `material.onUploadMaterial`；
+     * 两者均未配置时，SDK 才按目标协议使用内置 VOD / TOS 上传。
+     * 业务服务端应返回最小权限、短有效期凭证，
+     * 浏览器端不得保存客户长期 AK/SK。
+     * 未同时配置 TOS `media_output_destination` 时，SDK 不会仅凭素材
+     * `source_material_id` 或兜底 `source` 的 `tos://` 前缀接管播放地址；业务长期 URL 会原样使用，
+     * 缺少 URL 时可由 `material.onRefreshPlayInfo` 补齐。
+     */
+    getUploadSTS?: () => AmkEditorUploadSTSCredentials | AmkEditorVodUploadToken | Promise<AmkEditorUploadSTSCredentials | AmkEditorVodUploadToken>;
+}
+export interface ExportVideoParams {
+    videoName: string;
+    qualityEnhancement: boolean;
+    /** 画质增强完成后是否同时保留未增强的原始导出成片。 */
+    keepOriginal?: boolean;
+    enhancementVersion: 'standard' | 'professional' | 'large-model';
+    resolution: 'original' | '720p' | '1080p' | '2k' | '4k';
+    frameRate: number;
+    format: 'mp4' | 'mp3';
+    codec: 'h264' | 'h265' | 'vp9' | 'mp3';
+}
+/** Result of {@link AmkEditor.requestExport} for Agent/frontend-tool callers. */
+export type AmkExportRequestResult = {
+    status: 'success';
+    taskId: string;
+} | {
+    status: 'cancel';
+} | {
+    status: 'failed';
+    error: string;
+};
+export interface AmkExportTaskCreatedEvent {
+    taskId: string;
+    params: ExportVideoParams;
+    requestId?: string;
+}
+export interface VeVeditorInstance {
+    destroy: () => void;
+    on?: (eventName: string, handler: (...args: any[]) => void) => void;
+    off?: (eventName: string, handler: (...args: any[]) => void) => void;
+    getTrack?: () => any[];
+    /** 获取当前合成画布的 data URL；未初始化时返回 null，native 渲染模式下抛错。 */
+    getFrame?: (options?: {
+        type?: string;
+        quality?: number;
+    }) => string | null;
+    setCanvas?: (canvas: {
+        Width: number;
+        Height: number;
+        BackgroundColor?: string;
+    }) => Promise<void>;
+    setTrack?: (track: any[], options?: {
+        recordHistory?: boolean;
+    }) => Promise<void>;
+    setTrackElementMarker?: (elementId: string, marker: {
+        key?: string;
+        content: string;
+        position?: number;
+        loading?: boolean;
+    } | null, options?: {
+        clearKey?: string;
+    }) => void;
+    getTrackElementMarkers?: (elementId: string) => Array<{
+        key?: string;
+        content: string;
+        position?: number;
+        loading?: boolean;
+    }>;
+    setTrackElementBadge?: (elementId: string, badge: {
+        type: 'spinner';
+        content?: string;
+        position?: number;
+    } | null) => void;
+    getTrackElementBadge?: (elementId: string) => unknown;
+    getSketchItems?: () => MaterialItem[];
+    getEditParam?: () => Record<string, unknown>;
+    decodeVideoPoster?: (url: string, options?: {
+        signal?: AbortSignal;
+        imageWidth?: number;
+    }) => Promise<Blob | null>;
+    addSketchItems?: (items: MaterialItem[]) => void;
+    setSketchItems?: (items: MaterialItem[]) => void;
+    [key: string]: unknown;
+}
+/** 内置 get/update 工程快照（不导出给宿主配置） */
+/** 工程接口返回的元信息；保留服务端扩展字段，供宿主及后续 UI 使用。 */
+export type AmkProjectInfo = {
+    project_id: string;
+    name: string;
+    description?: string;
+    [key: string]: unknown;
+};
+export type AmkProjectSnapshot = {
+    projectInfo?: AmkProjectInfo;
+    projectName?: string;
+    materials?: MaterialItem[];
+    editParam?: Record<string, unknown>;
+};
+/** AMK 资源面板开关：false=关闭（不透传）；true/不传=展示（透传 AMK 内置资源）。 */
+type AmkResourceOptionTypes = {
+    font: boolean;
+    wordArt: boolean;
+    textAnimation: boolean;
+    transition: boolean;
+    filter: boolean;
+    effect: boolean;
+};
+type AmkInheritedVeVeditorOptions = Omit<VeVeditorOptions<MaterialConfig, VeVeditorI18nOptions, AmkResourceOptionTypes>, 'initialData' | 'recording' | 'onSketchItemsChange' | 'onNodePreviewError' | 'onPreviewNodeRefresh' | 'onBeforeUndo' | 'onBeforeRedo' | 'onBeforeTimestampMount' | 'onBeforeKeyframeMount' | 'onTrackChanged' | 'onRecordingUpload' | 'decode'>;
+export type AmkEditorDecodeOptions = VeVeditorDecodeOptions;
+/** 每次 AMK 请求前动态获取、原样透传给 endpoint 的业务请求头。 */
+export type AmkEditorGetHeaders = () => Readonly<Record<string, string>> | undefined | Promise<Readonly<Record<string, string>> | undefined>;
+export interface AmkEditorOptions extends AmkInheritedVeVeditorOptions {
+    toolbar?: AmkInheritedVeVeditorOptions['toolbar'] & {
+        /** 字幕识别后端：火山默认 asr-subtitles，BytePlus 默认 maas。 */
+        asr?: {
+            provider?: import('./asr-provider').AmkAsrProvider;
+        };
+    };
+    projectId: string;
+    /** AMK Editing API 的业务代理地址。 */
+    endpoint: string;
+    /** 接入方标识，用于埋点来源和问题归因；缺省时使用 sdk。 */
+    source?: string;
+    /** 每次请求前调用；返回值不解析、不改写，仅透传给 endpoint。 */
+    getHeaders?: AmkEditorGetHeaders;
+    header?: AmkEditorHeaderConfig;
+    export?: AmkEditorExportConfig;
+    /** @deprecated 请改用 export.onTaskCreated。 */
+    onExportTaskCreated?: (event: AmkExportTaskCreatedEvent) => void | Promise<void>;
+    getLicenseUrl?: string | (() => string | Promise<string>);
+    decode?: AmkEditorDecodeOptions;
+    /** 产物 / 主动上传的存储目标，包括 TOS / VOD。 */
+    storage?: AmkEditorStorageConfig;
+}
+export interface AmkEditorInternalConfig {
+    projectId: string;
+    endpoint: string;
+}
+/** 挂载 veveditor 用的内部配置（含组装后的 initialData 等，不作为宿主 API） */
+export interface AmkEditorConfig extends AmkEditorOptions {
+    initialData?: AmkProjectSnapshot;
+    __amkEditor: AmkEditorInternalConfig;
+}
+export {};

package/dist/upload-queue.d.ts

@@ -0,0 +1,6 @@
+/** 文件级 FIFO 队列；一个名额覆盖上传、元信息补齐和入库。 */
+export declare function createUploadQueue(concurrency?: number): {
+    run<T>(task: () => Promise<T> | T): Promise<T>;
+    destroy(): void;
+};
+export type UploadQueue = ReturnType<typeof createUploadQueue>;

package/dist/url-upload-modal-view.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { AmkI18nInstance } from './i18n';
+export interface UrlUploadModalViewProps {
+    visible: boolean;
+    popupContainer: HTMLElement;
+    t: AmkI18nInstance['t'];
+    /** 确认后弹窗立即关闭；上传过程由外部 Message 提示 */
+    onConfirm: (urls: string[]) => void;
+    onClose: () => void;
+}
+/** 支持逗号 / 换行分隔，得到回调给业务方的 url 数组 */
+export declare function splitUrls(input: string): string[];
+export declare function UrlUploadModalView({ visible, popupContainer, t, onConfirm, onClose, }: UrlUploadModalViewProps): React.ReactElement;

package/dist/url-upload-modal.d.ts

@@ -0,0 +1,12 @@
+import type { AmkI18nInstance } from './i18n';
+export interface CreateUrlUploadModalOptions {
+    container: HTMLElement;
+    t: AmkI18nInstance['t'];
+    onConfirm: (urls: string[]) => void;
+}
+export interface UrlUploadModalController {
+    open: () => void;
+    close: () => void;
+    destroy: () => void;
+}
+export declare function createUrlUploadModal(options: CreateUrlUploadModalOptions): UrlUploadModalController;

package/dist/utils/material-extract.d.ts

@@ -0,0 +1,62 @@
+import type { MaterialItem } from '../types';
+export declare const VIDEO_POSTER_EXTRACT_PARAMS: {
+    readonly snapshot_type: "SpecifiedFrames";
+    readonly specified_frames: readonly [0];
+    readonly scale_long: 1280;
+    readonly scale_short: 720;
+};
+export declare function resolveSpriteTimeInterval(duration: unknown): number;
+export declare function buildSpriteExtractParams(duration: unknown): {
+    snapshot_type: string;
+    time_interval: number;
+    snapshot_limit: number;
+    scale_long: number;
+    enable_sprite: boolean;
+    sprite_rows: number;
+    sprite_cols: number;
+};
+export type SpriteState = {
+    ready: boolean;
+    pendingTaskId?: string;
+};
+/**
+ * 素材 `sprite`：
+ * - object `{ storeurls, capturenum }`：已完成；链接是否失效由实际网络请求判断
+ * - 进行中任务放在 `sprite_task_id`；旧 `sprite` 字符串仅用于一次性迁移
+ * - 缺省：需要新建任务
+ */
+export declare function resolveSpriteState(material: MaterialItem): SpriteState;
+/** 可落盘的封面：接口返回的 http(s) URL */
+export declare function isPersistablePosterUrl(value: unknown): boolean;
+/** 仅会话内使用的封面：前端解码 dataURL，不落盘 */
+export declare function isRuntimeOnlyPosterUrl(value: unknown): boolean;
+/** http poster；有效性由实际网络请求判断 */
+export declare function isPosterAssetReady(material: MaterialItem): boolean;
+/** poster 任务只能存在独立字段；旧 poster 非 http/dataURL 字符串仅用于一次性迁移。 */
+export declare function resolvePosterTaskId(material: MaterialItem): string | undefined;
+export declare function isExtractableVideoMaterial(material: MaterialItem): boolean;
+export declare function resolveMaterialMediaUrl(material: MaterialItem): string;
+export type MaterialExtractActions = {
+    url: string;
+    /** 需要新建 sprite 抽帧任务，任务 ID 写入 sprite_task_id */
+    createSpriteTask: boolean;
+    /** 已有 taskId，从 sprite_task_id 继续轮询 */
+    resumeSpriteTaskId?: string;
+    /** 已有 poster 任务，从 poster_task_id 继续轮询。 */
+    resumePosterTaskId?: string;
+    /**
+     * 需要抓封面：缺有效 http poster，或需恢复进行中的 poster_task_id。
+     * 前端 DataURL 仅作会话预览，不单独驱动 capturePoster。
+     */
+    capturePoster: boolean;
+};
+/**
+ * 纯判断：单个素材要不要建 sprite 任务 / 恢复轮询 / 抓封面。
+ * - enableThumbnailDecode（前端缩略图）开启时不发起 sprite 接口任务
+ * - poster / sprite 缺省时触发重抽；已有 URL 的有效性由实际网络请求判断
+ */
+export declare function planMaterialExtractActions(params: {
+    material: MaterialItem;
+    useFrontendThumbnails: boolean;
+    hasPosterCache: boolean;
+}): MaterialExtractActions | null;

package/dist/utils/signed-media-url-expiration.d.ts

@@ -0,0 +1,2 @@
+/** 只根据签名参数判断明确过期；图片 onerror 本身无法可靠区分 403/404/CORS。 */
+export declare function isSignedMediaUrlExpired(urlValue: unknown, now?: number): boolean;