@volcengine/amk-editor 0.0.1-beta.4 → 0.0.1

package/README.md

@@ -1,139 +1,43 @@
 # @volcengine/amk-editor
-
-AMK 场景官方接入包：发布构建会内联底层编辑器运行时 UMD 与样式。公网业务方/demo **只需安装本包**，无需安装或访问内部编辑器包。弹层挂载使用 React 18/19 的 `createRoot`（兼容 React 19，不再使用已弃用的 `ReactDOM.render`）。
-
-## License
-
-AMK Editor SDK 是火山引擎 AI MediaKit 的商业配套软件。使用本 SDK 需要获得有效的火山引擎商业授权，具体条款参见 [LICENSE](./LICENSE)。商业授权咨询请联系 `service@volcengine.com`。
-
-本 SDK 使用的第三方开源组件仍分别适用其各自的许可证，第三方许可证不因本商业许可证而被替代。
-
+火山引擎 AI MediaKit 官方 Web 视频编辑器 SDK。
+## 安装
+```bash
+npm install @volcengine/amk-editor
+```
+需要 React 18 或 19。使用本 SDK 须获得有效的火山引擎商业授权，条款见 [LICENSE](./LICENSE)。
+本 SDK 使用的第三方开源组件仍分别适用其各自的许可证。
+## 快速开始
 ```ts
 import { AmkEditor } from '@volcengine/amk-editor';
-
 const editor = new AmkEditor({
   container,
-  projectId: 'xxx',
-  endpoint: 'https://your-proxy.example.com',
-  getLicenseUrl: 'https://license.example.com',
+  projectId: 'your-project-id',
+  endpoint: 'https://your-backend.example.com',
   material: {
-    // 本地上传：入参 File[]，返回 MaterialItem[]；每项必须带 source_material_id，不必传 material_id
-    onUploadMaterial: async files => [],
-    // URL 上传：入参 string[]（弹窗内逗号/换行分隔），返回契约同上
-    onUploadUrlMaterial: async urls => [],
+    onUploadMaterial: async files => {
+      // 上传到业务存储后返回素材列表，每项必须带 source_material_id
+      return [];
+    },
+    onUploadUrlMaterial: async urls => {
+      return [];
+    },
     onRefreshPlayInfo: async materials =>
       materials.map(item => ({
         material_id: item.material_id, // 仅用于匹配，不要改写
-        url: '...', // 业务方按自己字段映射
-        // 以下 key 名只是推荐示例；使用自定义字段时读取自己的字段即可。
-        poster: item.poster_storage_key ? 'https://signed-poster-url' : item.poster,
-        sprite: item.sprite_storage_keys
-          ? { ...item.sprite, storeurls: ['https://signed-sprite-url'] }
-          : item.sprite,
+        url: '...',
+        poster: item.poster,
+        sprite: item.sprite,
       })),
-    // 抽帧临时链转存成长效地址（可选）；URL 和 key 会一起写回素材
-    onPersistExtractUrls: async ({ kind, urls, material }) => {
-      const result = await persistToBusinessStorage({ kind, urls, material });
-      return {
-        urls: result.urls,
-        // SDK 会把 materialPatch 原样合并并写回素材；字段名由业务决定。
-        materialPatch:
-          kind === 'poster'
-            ? { poster_storage_key: result.storageKeys[0] }
-            : { sprite_storage_keys: result.storageKeys },
-      };
-    },
   },
 });
-
-// 两种上传返回素材后，SDK 统一：
-// 1. addSketchItems → 素材面板
-// 2. createAmkMaterials → POST 远端仓库，并把服务端返回的 material_id 记到面板
-// 3. ensureMaterialExtractTasks → 缺/过期 poster/sprite 时抽帧；临时链上屏后可后台转存再 PUT
-
-// 转存完成后素材会保存：
-// - poster + poster_storage_key（推荐字段，可自定义）
-// - sprite.storeurls + sprite_storage_keys（推荐字段，可自定义）
-// 下一次 onRefreshPlayInfo 会收到这些 key，业务可据此重新生成有时效的访问 URL。
-// SDK 不读取上述两个 key，也不把它们当作固定 Schema。业务也可以返回：
-// materialPatch: {
-//   biz_storage: { poster_key: '...', sprite_keys: ['...'] },
-// }
-// 只需在 onRefreshPlayInfo 中按同一套自定义结构读取即可。
-
-// 导出：invokeTool('vibe-editing-common', { edit_param, callback_args? })
-// 开启画质增强时附带 callback_args（JSON 字符串），供代理后续调增强：
-// - standard/professional → { tool:"enhance-video", tool_version, resolution, fps }
-// - large-model → { tool:"enhance-video-generative", resolution, fps }
-// SDK 不负责增强任务本身。
-
-// 工程会从 {endpoint}/api/v1/editing/projects/{projectId} 加载并自动保存。
-// 通用 MediaKit 工具仍通过 POST {endpoint}/api/v1/tools/{toolName} 调用。
-await editor.invokeTool({
-  toolName: 'asr-subtitles',
-  params: {
-    input: {
-      type: 'video',
-      url: 'https://example.com/demo.mp4',
-    },
-  },
-});
-```
-
-## 构建
-
-先构建 SDK，再构建本包：
-
-```bash
-pnpm build-veveditor
-pnpm --filter @volcengine/amk-editor run build
-```
-
-产物位于 `dist/index.js`（含 veveditor 运行时）与 `dist/veveditor.css`（样式 side-effect）。
-
-- `projectId` / `endpoint` 均为必传；鉴权密钥留在业务服务端，由 `endpoint` 代理注入
-- 发布包不声明底层编辑器为运行时依赖；底层编辑器和 `video-editor` 已在构建阶段内联到 `dist/index.js`，类型声明也不依赖内部包。
-- 发布前必须使用 `npm pack --dry-run` 检查 tarball；公网用户只需要能访问 npm 公网源和业务方提供的 `endpoint`。
-
-## Editing API 对接
-
-初始化时，AMK Editor 会组合以下接口：
-
-- `GET /api/v1/editing/projects/:project_id`
-- `GET /api/v1/editing/projects/:project_id/materials`
-- `GET /api/v1/editing/projects/:project_id/editor`
-
-编辑过程中按资源分别写回：
-
-- 标题变更：`PATCH /projects/:project_id`
-- 素材变更：`PUT/DELETE /projects/:project_id/materials`
-- 剪辑参数变更：`PUT /projects/:project_id/editor`
-
-Editor 保存携带服务端 `revision`，SDK 内部串行提交保存请求，避免同一页面内的并发保存互相覆盖。素材身份字段分工：
-
-- `source_material_id`：业务必填主键。POST / PUT 请求体、DELETE 都用它；DELETE body 为 `{ source_material_ids: string[] }`
-- `material_id`：Editing API 自己生成的服务端 id。业务方不用传，传了也不会入库；SDK 只在 POST 成功后把返回值记到面板，供轨道内部关联
-- `source`：VeVEditor 轨道 `Source` / 加密 vid 等资源标识。Editing API 请求体里的 `source` 是 origin url，与面板 `source` 不是同一语义
-
-服务端响应缺少 `source` 时，加载工程仅使用 `material_id` 作为 `source` fallback。
-
-浏览器不应持有 AMK API Key。`endpoint` 应指向业务代理，由代理向 Editing API 注入：
-
-```http
-Authorization: Bearer <AMK_API_KEY>
-```
-
-`amkeditordemo` 默认使用与 Editing API 契约一致的内存 mock。联调真实服务时，在启动 demo 的服务端环境设置：
-
-```bash
-EDITING_API_UPSTREAM='https://your-editing-api.example.com' \
-AMK_API_KEY='<your-api-key>' \
-VITE_AMK_PROJECT_ID='<existing-project-id>' \
-pnpm --dir packages/amkeditordemo/fe dev
 ```
-
-卸载时销毁：
-
+页面卸载时销毁：
 ```ts
 editor.destroy();
 ```
+## 接入说明
+- `projectId`、`endpoint` 必填。`endpoint` 指向你的业务服务，由服务端转发并注入鉴权，不要把 API Key 放到浏览器。
+- 本地上传、URL 导入由业务回调完成。返回的素材必须带业务主键 `source_material_id`，不必填写 `material_id`。
+- 播放地址、封面、雪碧图可能有时效。通过 `onRefreshPlayInfo` 返回新的访问地址。
+- 可选实现 `onPersistExtractUrls`：把抽帧得到的临时地址转存为业务长期地址，并随 `materialPatch` 写回自定义存储字段。
+- 可选配置 `export.qualityEnhancement: true` 以在导出弹窗展示「视频画质增强」；默认不展示。

package/dist/export-modal-view.d.ts

@@ -5,7 +5,8 @@ export interface ExportModalViewProps {
     videoName: string;
     visible: boolean;
     t: AmkI18nInstance['t'];
+    showQualityEnhancement?: boolean;
     onConfirm: (params: ExportVideoParams) => Promise<void> | void;
     onClose: () => void;
 }
-export declare function ExportModalView({ videoName, visible, t, onConfirm, onClose, }: ExportModalViewProps): React.ReactElement;
+export declare function ExportModalView({ videoName, visible, t, showQualityEnhancement, onConfirm, onClose, }: ExportModalViewProps): React.ReactElement;

package/dist/export-modal.d.ts

@@ -5,6 +5,8 @@ export interface CreateExportModalOptions {
     videoName: string;
     onConfirm: (params: ExportVideoParams) => Promise<void> | void;
     t?: AmkI18nInstance['t'];
+    /** 是否展示「视频画质增强」。默认不展示。 */
+    showQualityEnhancement?: boolean;
 }
 export interface ExportModalController {
     open: () => void;

package/dist/index.d.ts

@@ -4,4 +4,4 @@ export type { AmkApiClientOptions, AmkInvokeToolParams } from './api/client';
 export type { PresetLibrary, PresetLibraryItem, PresetLibraryResourceKey, } from './api/preset-library';
 export { AMK_I18N_KEYS, createAmkI18n, tAmk, getGlobalAmkI18n, setGlobalAmkI18n, } from './i18n';
 export type { AmkI18nInstance, AmkI18nOptions, Locale, LocaleMessages, Messages, } from './i18n';
-export type { AmkEditorOptions, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorHeaderConfig, AmkEditorInternalConfig, AmkProjectSnapshot, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, Theme, VeVeditorInstance, } from './types';
+export type { AmkEditorOptions, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorExportConfig, AmkEditorHeaderConfig, AmkEditorInternalConfig, AmkProjectSnapshot, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, Theme, VeVeditorInstance, } from './types';