daily-video-editor 0.0.7 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +208 -70
  2. package/dist/clip-track/composables/useAutoScroll.d.ts +4 -0
  3. package/dist/editor/VideoComposeEditor.vue.d.ts +6200 -5432
  4. package/dist/editor/asset-panel/VideoComposeAssetCard.vue.d.ts +19 -1
  5. package/dist/editor/session/useComposeEditorSession.d.ts +6027 -5259
  6. package/dist/editor/timeline/VideoComposeTimeline.vue.d.ts +3493 -1
  7. package/dist/index.js +7460 -7339
  8. package/dist/style.css +1 -1
  9. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,43 @@
1
- # daily-video-clips
1
+ # 天天视频剪辑
2
2
 
3
- 视频合成编辑器。打包后宿主只需 Vue，不必再装 Pinia、全局 Element Plus 或 Tailwind。
3
+ Vue 3 多轨视频合成编辑器（npm 包名 `daily-video-editor`）。提供素材栏、预览器、参数侧栏与时间轴。
4
4
 
5
- ## 接入
5
+ > **当前仍处于迭代阶段。** API、工程 JSON 与 UI 可能随版本调整。后续计划陆续推出：**自定义字体**、**视频画面调色**、**前端合成**等能力。字段含义以 `dist/index.d.ts` 为准。
6
+
7
+ ## 安装
8
+
9
+ 需已安装 **Vue 3.5+**（`peerDependencies`）。
10
+
11
+ ```bash
12
+ npm install daily-video-editor
13
+ ```
14
+
15
+ 也可用：
16
+
17
+ ```bash
18
+ pnpm add daily-video-editor
19
+ # 或
20
+ yarn add daily-video-editor
21
+ ```
22
+
23
+ 安装后在入口引入样式（缺一不可）：
24
+
25
+ ```ts
26
+ import "daily-video-editor/style.css";
27
+ ```
28
+
29
+ 本地联调或未发布到 registry 时，可用路径依赖：
30
+
31
+ ```bash
32
+ # 相对路径 / 绝对路径
33
+ npm install ../VIDEO-Clips
34
+ # 或 package.json
35
+ # "daily-video-editor": "file:../VIDEO-Clips"
36
+ ```
37
+
38
+ 使用源码路径依赖前，请在本仓库执行 `npm run build`，确保存在 `dist/`。monorepo 可用 workspace 协议指向本包。
39
+
40
+ ## 快速接入
6
41
 
7
42
  ```ts
8
43
  import { createApp, ref } from "vue";
@@ -11,8 +46,8 @@ import {
11
46
  VideoComposeEditor,
12
47
  type VideoComposeEditorExpose,
13
48
  type VideoComposeEditorModel,
14
- } from "video-clips";
15
- import "video-clips/style.css";
49
+ } from "daily-video-editor";
50
+ import "daily-video-editor/style.css";
16
51
 
17
52
  const model = ref<VideoComposeEditorModel>(
18
53
  createDefaultVideoComposeEditorModel({
@@ -29,110 +64,213 @@ createApp(App).mount("#app");
29
64
  <VideoComposeEditor ref="editorRef" v-model="model" />
30
65
  ```
31
66
 
32
- `peerDependencies` 只有 `vue`。`pinia`、`element-plus` 随包安装，并在编辑器内部使用：每个时间轴自建一份 Pinia，同页多个编辑器不会抢轨。
67
+ **换稿必须调用 `editorRef.reload(model)`。** 只改 `v-model` 引用不会回灌时间轴。
33
68
 
34
- 换稿必须调用 `editorRef.reload(model)`。只改 `v-model` 引用不会回灌时间轴。
69
+ `peerDependencies` 只有 `vue`。
35
70
 
36
- ## 组件 Ref（`VideoComposeEditorExpose`）
71
+ ---
37
72
 
38
- | 方法 | 说明 |
39
- | --- | --- |
40
- | `validate(): string \| null` | 导出前校验。`null` 表示通过，否则为错误文案 |
41
- | `flush(): void` | 立刻把当前轨道、喜欢态、缩放写入 `update:modelValue` |
42
- | `reload(model): Promise<void>` | 用指定工程整页重置时间轴。换稿只走这个方法 |
43
- | `exportComposePayload()` | 先 `flush`，再返回 `{ id, bizType, bizId, tracks }` |
44
- | `getMainVideoClips()` | 主轨视频片段。优先读时间轴，否则用派生列表 |
45
- | `requestUploadClip()` | 触发上传视频：有 `onRequestUploadClip` 则交给宿主，否则走内置上传 |
73
+ ## 导出数据结构
46
74
 
47
- ## 公共类型
75
+ ### `ComposeExportPayload`（成片请求快照）
48
76
 
49
- 声明在 `dist/index.d.ts`。包根导出：
77
+ 调用 `exportComposePayload()` 返回。先 `flush`，再取当前工程：
50
78
 
51
- - 组件与工厂：`VideoComposeEditor`、`createDefaultVideoComposeEditorModel`
52
- - 工程：`VideoComposeEditorModel`、`ComposeExportPayload`、`ComposeTrack`、`ComposeClip`、`MediaBizType`、`MediaRef`、`ComposeSegmentClipAssets`
53
- - 侧栏种子：`BgmItem`、`TextTemplateItem`、`VideoClipItem`
54
- - 入参与上传：`ComposeEditorProps`、`ComposeUploadAdapter`、`ComposeBgmUploadResult`、`ComposeCatalogUploadPayload`
55
- - Ref：`VideoComposeEditorExpose`
56
- - 轨道片段：`MediaClip`、`SubtitleClip`、`TextClip`、`TrackType`
57
- - 媒体地址：`createComposeMediaResolver`、`isPassthroughMediaUrl`、`mediaCorsMessage`、`ComposeMediaResolver`、`ResolveMediaUrl`
79
+ | 字段 | 类型 | 说明 |
80
+ | --------- | ------------------ | -------------------------- |
81
+ | `id` | `string` | 合成草稿主键 |
82
+ | `bizType` | `MediaBizType` | 业务类型 |
83
+ | `bizId` | `string \| number` | 业务实体 id |
84
+ | `tracks` | `ComposeTrack[]` | 多轨列表（渲染侧主要消费） |
58
85
 
59
- 字段含义以声明文件为准。
86
+ ### `VideoComposeEditorModel`（v-model / 持久化真相源）
60
87
 
61
- ## 发包
88
+ | 字段 | 类型 | 说明 |
89
+ | -------------------------- | ------------------ | ------------------------------ |
90
+ | `id` | `string` | 合成草稿主键 |
91
+ | `bizType` | `MediaBizType` | 业务类型 |
92
+ | `bizId` | `string \| number` | 业务实体 id |
93
+ | `tracks` | `ComposeTrack[]` | 多轨列表 |
94
+ | `scale?` | `number` | 时间轴显示倍率；成片渲染忽略 |
95
+ | `composeExtractAudioUrls?` | `string[]` | 兼容旧工程抽轨 URL；本地仅透传 |
62
96
 
63
- `package.json` 保持 `"private": true`。本包默认不发到公共 npm。
97
+ 侧栏视频 / 音频 / 音效 / 字幕 / 花字列表由 **Editor 内部数组**维护，**不写入** `v-model`。
64
98
 
65
- 安装方式：monorepo workspace、`file:` 依赖，或私有 registry。类型入口是 `dist/index.d.ts`（`files` 含整个 `dist`）。要公开发到 npm 时，须先去掉 `private`，再按公开发布流程处理，不走上述私有安装约定。
99
+ ### `ComposeTrack`
66
100
 
67
- 构建：
101
+ | 字段 | 类型 | 说明 |
102
+ | ------------------------------------------ | -------------------- | ------------------------------------------------------ |
103
+ | `id` | `string` | 轨道唯一 id |
104
+ | `type` | `TrackType` | 轨道类型（如 `video` / `audio` / `subtitle` / `text`） |
105
+ | `name` | `string` | 展示名 |
106
+ | `isMain?` | `boolean` | 是否主视频轨 |
107
+ | `visible` | `boolean` | 是否可见 |
108
+ | `locked` | `boolean` | 是否锁定 |
109
+ | `muted?` | `boolean` | 音频轨整轨静音 |
110
+ | `clips` | `ComposeClip[]` | 轨道片段 |
111
+ | `order` | `number` | 排序 |
112
+ | `frameAspect?` | `ComposeFrameAspect` | 视频轨画幅 |
113
+ | `nativeFrameWidth?` / `nativeFrameHeight?` | `number` | 原画像素 |
68
114
 
69
- ```bash
70
- npm run build
71
- ```
115
+ ### `ComposeClip`
72
116
 
73
- 库产物：
117
+ 本期支持：`MediaClip`（`video` \| `audio`）| `ComposeSubtitleClip` | `TextClip`。
74
118
 
75
- - `dist/index.js`
76
- - `dist/index.d.ts`
77
- - `dist/style.css`
78
- - `dist/algorithm/`
119
+ 共性字段见 `BaseClip`（`id`、`trackId`、`startTime` / `endTime`、`rect`、`visible`、`config` 等）。
79
120
 
80
- ## 产物部署
121
+ - **视频 / 音频**：`sourceUrl`、`trimStart` / `trimEnd`、`playbackRate`、`volume` 等；业务扩展在 `config`（美颜、画面变换、抽轨关联等）
122
+ - **字幕**：文案与字体样式，另含 ASS 扩展（`bold` / `italic` / `alignment` / 边距等）
123
+ - **花字（贴图）**：`text`、`fontSize`、`color`；模板资源在 `config.sourceUrl` / `config.templateId`
81
124
 
82
- 宿主必须引入样式，否则编辑器没有皮肤：
125
+ 可用 `createDefaultVideoComposeEditorModel({ bizType, bizId })` 创建空工程。
83
126
 
84
- ```ts
85
- import "video-clips/style.css";
86
- ```
127
+ ---
87
128
 
88
- 美颜预览 Worker 在 `npm run build` 时内联进 `dist/index.js`。不要单独部署 worker 文件，也不要再准备 `/assets/beautyPreview.worker-*.js`。
129
+ ## 组件 Ref 方法（`VideoComposeEditorExpose`）
89
130
 
90
- `dist/algorithm/` 仍须挂到宿主静态目录。默认从站点根路径 `/algorithm/` 读取：
131
+ | 方法 | 说明 |
132
+ | ---------------------------------------------- | ----------------------------------------------------------------- |
133
+ | `validate(): string \| null` | 导出前校验。`null` 表示通过，否则为错误文案 |
134
+ | `flush(): void` | 立刻把当前轨道、缩放等写入 `update:modelValue` |
135
+ | `reload(model): Promise<void>` | 用指定工程整页重置时间轴。换稿只走这个方法 |
136
+ | `exportComposePayload(): ComposeExportPayload` | 先 `flush`，再返回 `{ id, bizType, bizId, tracks }` |
137
+ | `getMainVideoClips(): VideoClipItem[]` | 主轨视频片段。优先读时间轴，否则用派生列表 |
138
+ | `requestUploadClip(): void` | 触发上传视频：有 `onRequestUploadClip` 则交给宿主，否则走内置上传 |
139
+ | `getEditingClip(): ComposeClip \| null` | 右栏 inspector 当前类型对应的选中 clip |
140
+ | `getSelectedClips(): ComposeClip[]` | 当前时间轴多选解析后的 clip 列表 |
91
141
 
92
- - `/algorithm/face_landmarker.task`
93
- - `/algorithm/mediapipe/`
142
+ ---
94
143
 
95
- 本地 demo 使用 `public/algorithm/`。库构建只拷贝这两项到 `dist/algorithm/`。挂好后可用 `algorithmBaseUrl` 改根路径（须是目录，并能拼出上述两个相对路径）。
144
+ ## 插槽（Slots）
96
145
 
97
- ## 侧栏素材（不进工程 JSON）
146
+ 未传入时走内置默认 UI；传入后替换对应区域。
98
147
 
99
- 视频 / 音频 / 音效 / 花字列表由 **Editor 内部数组**维护，**不写入** `v-model`（`model` 只有 tracks、likedMedia、scale 等）。
148
+ ### 素材栏操作区
100
149
 
101
- 可用 props 作种子；上传成功事件载荷为：
150
+ 替换各分类「上传 / 添加」入口（有插槽时不再渲染默认按钮）：
102
151
 
103
- ```ts
104
- { file: File; item: T; items: T[] }
105
- ```
152
+ | 插槽名 | 位置 |
153
+ | ------------------ | -------- |
154
+ | `video-actions` | 视频素材 |
155
+ | `audio-actions` | 音频 |
156
+ | `subtitle-actions` | 字幕 |
157
+ | `fancy-actions` | 花字 |
158
+ | `sfx-actions` | 音效 |
106
159
 
107
- 宿主可把 `items` 回写到自己的状态。纯 `onRequestUpload*` 由宿主自管 UX，不走该 emit。
160
+ ### 参数侧栏「应用到全局」之前
108
161
 
109
- ## 跨域媒体
162
+ 供宿主插入自定义控件：
163
+
164
+ | 插槽名 | 对应 inspector |
165
+ | ----------------------- | -------------- |
166
+ | `before-apply-video` | 视频 |
167
+ | `before-apply-audio` | 音频 |
168
+ | `before-apply-subtitle` | 字幕 |
169
+ | `before-apply-text` | 花字 / 贴图 |
170
+
171
+ ### 时间轴（透传 clip-track 具名 slot）
110
172
 
111
- 预览、缩略图和美颜抽帧都要能读取像素。编辑器会：
173
+ | 插槽名 | 位置 / 用途 | 插槽 props |
174
+ | -------------------- | ------------------------------------------- | ----------- |
175
+ | `toolbar-before` | 工具栏整条之前 | — |
176
+ | `toolbar-after` | 工具栏整条之后 | — |
177
+ | `operations-prepend` | 顶部操作按钮区前 | — |
178
+ | `operations-append` | 顶部操作按钮区后 | — |
179
+ | `track-control` | 轨道右侧操作区；追加在内置静音/向前对齐之后 | `{ track }` |
112
180
 
113
- - 给 `video` / `audio` 设置 `crossorigin="anonymous"`
114
- - 对跨域地址默认 `fetch`（`mode: "cors"`）并转成 `blob:`
115
- - 同源、`blob:`、`data:` 原样使用
181
+ 说明：
116
182
 
117
- 源站需要：
183
+ - `readonly` 时工具栏不渲染，`toolbar-*` / `operations-*` 不可见。
184
+ - `track-control` 内宿主内容不会自动跟随 `readonly` 禁用，需宿主自行处理。
118
185
 
186
+ ```vue
187
+ <VideoComposeEditor v-model="model">
188
+ <template #video-actions>
189
+ <button type="button" @click="openHostUploader">自定义上传</button>
190
+ </template>
191
+ <template #before-apply-video>
192
+ <!-- 宿主扩展控件 -->
193
+ </template>
194
+ <template #operations-append>
195
+ <!-- 工具栏操作区末尾；readonly 时不可见 -->
196
+ </template>
197
+ <template #track-control="{ track }">
198
+ <!-- 追加在静音/对齐之后；需自行处理 readonly 禁用 -->
199
+ </template>
200
+ </VideoComposeEditor>
119
201
  ```
120
- Access-Control-Allow-Origin: <页面源> 或 *
121
- Access-Control-Allow-Methods: GET
202
+
203
+ ---
204
+
205
+ ## Props / 事件（摘要）
206
+
207
+ 常用 Props：`modelValue`、`readonly`、`videoAssets` / `audioAssets` / `sfxAssets` / `subtitleAssets` / `textTemplates`、`uploadAdapter`、`onRequestUploadClip` 等、`resolveMediaUrl`、`algorithmBaseUrl`、`trackTypes`。
208
+
209
+ 常用事件：`update:modelValue`、`ready`、`remove-catalog-clip`、`toggle-like`、`video-uploaded` / `audio-uploaded` / `sfx-uploaded` / `text-template-uploaded`、`selection-changed`。
210
+
211
+ 上传成功事件载荷：`{ file: File; item: T; items: T[] }`。纯 `onRequestUpload*` 由宿主自管 UX，不走该 emit。
212
+
213
+ ---
214
+
215
+ ## 公共类型（包根导出）
216
+
217
+ - 组件与工厂：`VideoComposeEditor`、`createDefaultVideoComposeEditorModel`
218
+ - 工程：`VideoComposeEditorModel`、`ComposeExportPayload`、`ComposeTrack`、`ComposeClip`、`MediaBizType`、`MediaRef`、`ComposeSegmentClipAssets`
219
+ - 侧栏种子：`BgmItem`、`TextTemplateItem`、`VideoClipItem`
220
+ - 入参与上传：`ComposeEditorProps`、`ComposeUploadAdapter`、`ComposeBgmUploadResult`、`ComposeCatalogUploadPayload`
221
+ - Ref：`VideoComposeEditorExpose`
222
+ - 轨道片段：`MediaClip`、`SubtitleClip`、`TextClip`、`TrackType`、`TrackTypeConfig`
223
+ - 媒体地址：`createComposeMediaResolver`、`isPassthroughMediaUrl`、`mediaCorsMessage`、`ComposeMediaResolver`、`ResolveMediaUrl`
224
+
225
+ ---
226
+
227
+ ## 构建与产物
228
+
229
+ ```bash
230
+ npm run build
122
231
  ```
123
232
 
124
- 没有 CORS 头时，默认 fetch 会失败，界面提示配置 `resolveMediaUrl`。宿主把地址换成同源代理或 blob：
233
+ 库产物：`dist/index.js`、`dist/index.d.ts`、`dist/style.css`、`dist/algorithm/`。
234
+
235
+ 宿主必须引入样式：
125
236
 
126
237
  ```ts
127
- async function proxyToBlob(url: string): Promise<string> {
128
- const response = await fetch(`/api/media-proxy?url=${encodeURIComponent(url)}`);
129
- if (!response.ok) throw new Error("媒体代理失败");
130
- return URL.createObjectURL(await response.blob());
131
- }
238
+ import "daily-video-editor/style.css";
132
239
  ```
133
240
 
241
+ 美颜预览 Worker 在构建时内联进 `dist/index.js`，无需单独部署。`dist/algorithm/` 须挂到宿主静态目录（默认 `/algorithm/`）：
242
+
243
+ - `/algorithm/face_landmarker.task`
244
+ - `/algorithm/mediapipe/`
245
+
246
+ 可用 `algorithmBaseUrl` 改根路径。
247
+
248
+ ---
249
+
250
+ ## 跨域媒体
251
+
252
+ 预览、缩略图和美颜抽帧都要能读取像素。编辑器会给 `video` / `audio` 设 `crossorigin="anonymous"`，对跨域地址默认 CORS `fetch` 并转成 `blob:`。源站需允许 CORS；失败时配置 `resolveMediaUrl` 走同源代理或 blob。本仓库不实现代理服务。
253
+
134
254
  ```vue
135
255
  <VideoComposeEditor v-model="model" :resolve-media-url="proxyToBlob" />
136
256
  ```
137
257
 
138
- 本仓库不实现代理服务。
258
+ ---
259
+
260
+ ## 路线图（规划中）
261
+
262
+ | 方向 | 说明 |
263
+ | ------------ | ------------------------------------ |
264
+ | 自定义字体 | 宿主 / 用户字体接入字幕与花字 |
265
+ | 视频画面调色 | 亮度、对比度、色温等画面调整 |
266
+ | 前端合成 | 浏览器端导出成片，减少对后端渲染依赖 |
267
+
268
+ 欢迎在迭代过程中反馈接入问题；正式 API 稳定前请以类型声明与本 README 同步查阅。
269
+
270
+ ---
271
+
272
+ ## 致谢
273
+
274
+ 本项目的时间轴组件基于开源库 [vue-clip-track](https://github.com/caohongz/vue-clip-track) 衍生而来。感谢原作者与贡献者提供的多轨编辑能力——轨道交互、时间轴缩放与片段操作等，为本编辑器打下了坚实基础。
275
+
276
+ 仓库内 `src/clip-track` 已面向合成编辑场景做了定制演进，与上游并非一一对应；欢迎一并了解原项目。
package/dist/clip-track/composables/useAutoScroll.d.ts CHANGED
@@ -7,5 +7,9 @@ interface UseAutoScrollOptions {
7
7
  /** 根组件创建 Pinia 后传入。子组件可省略，改为 inject */
8
8
  pinia?: Pinia;
9
9
  }
10
+ /**
11
+ * 播放头越出当前视口时翻到下一/上一视口。
12
+ * 只响应 currentTime 变化（播放推进或用户 seek/点击），手动拖滚动条不会改时间，故不会触发翻页。
13
+ */
10
14
  export declare function useAutoScroll({ scrollLeft, tracksWidth, setScrollLeft, pinia }: UseAutoScrollOptions): void;
11
15
  export {};