@meframe/server 0.0.5 → 0.0.6

package/docs/INTEGRATION.md

@@ -18,6 +18,10 @@
 
 其他（draft 获取方式、存储 SDK、配置系统、队列/超时/重试）都由上层应用自行决定。
 
+> 可选但强烈建议（生产环境常见需求）：
+>
+> - **FFmpeg（用于音频后处理兜底）**：当浏览器运行时不支持 AAC 编码时，`@meframe/core` 会跳过音频导出；此时可由 `@meframe/server` 触发 FFmpeg 后处理，把音频混合并 remux 回 MP4。
+
 ### 1. 安装依赖
 
 ```bash
@@ -56,6 +60,16 @@ WebCodecs 等 API 需要 secure/trustworthy origin。`exportToStore({ pageUrl })
 
 > 核心原则：`CompositionModelData.resources[*].uri`、`workerPath` 指向的文件，都必须能在 Chromium 里直接 `fetch()`/加载到。
 
+#### 2.4 音频（AAC）能力说明（强烈建议阅读）
+
+当前 `mp4` 输出的音频轨 **只能是 AAC**（对应 WebCodecs `AudioEncoder` 的 `codec: 'mp4a.40.2'`）。
+
+- 在某些 Linux Chrome/Chromium 运行时（尤其是容器/精简发行版），**可能存在 `AudioEncoder` 可用但 AAC encode 不支持** 的情况。
+  - 这会导致 `@meframe/core` 在导出阶段 emit 一条包含 `Audio skipped:` 的 progress message，并继续导出 **video-only MP4**。
+- 如果你的业务 **必须输出带音频的 MP4**，建议启用 `@meframe/server` 的 **FFmpeg 音频后处理兜底**（见下文 5.x）。
+
+> 重要：这是运行时能力差异，不是业务代码“参数写错”。在不支持 AAC encode 的环境里，单纯升/降 Chrome 版本通常不可靠；生产上更稳的是启用 FFmpeg 兜底。
+
 ### 3. 用 `@meframe/adapter-medeo`：Draft → `CompositionModelData`
 
 `@meframe/server` 不关心你的业务数据长什么样，它只吃 `CompositionModelData`。
@@ -345,6 +359,41 @@ export async function exportMedeoDraftToMp4(input: {
       partSizeBytes: 16 * 1024 * 1024,
       contentType: 'video/mp4',
     },
+    // 可选：FFmpeg 音频后处理兜底（建议生产开启，尤其是 Linux 运行时）
+    //
+    // 触发条件：
+    // - 浏览器不支持 AAC encode → @meframe/core 会 emit `Audio skipped: ...`
+    // - @meframe/server 捕获到该 message 后，在 MP4 已上传完成的基础上运行 FFmpeg
+    //
+    // 返回值/时序：
+    // - 默认会等待后处理完成后才 resolve 并返回最终 key
+    // - 如果后处理失败：
+    //   - onFailure='fallback'（默认）：返回原始 video-only MP4 的 key
+    //   - onFailure='throw'：直接 fail 整个任务
+    //
+    // 依赖：
+    // - 运行环境需要可执行的 ffmpeg/ffprobe（默认从 PATH 解析）
+    postProcess: {
+      ffmpegAudioMix: {
+        enabled: true,
+        // 可选：覆盖输出 key（默认覆盖原 key）
+        // outputKey: outputKey.replace(/\.mp4$/, '.with-audio.mp4'),
+        // 可选：失败策略（默认 fallback）
+        // onFailure: 'fallback',
+        // 可选：ffmpeg/ffprobe 路径
+        // ffmpegPath: 'ffmpeg',
+        // ffprobePath: 'ffprobe',
+        // 必填：提供一种方式让 FFmpeg 能“读回”刚上传的 video-only MP4
+        // - 推荐：返回一个可直连的 GET URL（例如 S3 presigned GET）
+        // - 或者：如果你的存储可以落盘，返回本地 filePath
+        resolveUploadedInput: async ({ key }) => {
+          // 示例（伪代码）：生成一个供 FFmpeg 使用的 presigned GET URL
+          // const url = await presignGetObjectUrl({ key, expiresInSeconds: 3600 });
+          // return { kind: 'url', url };
+          throw new Error(`resolveUploadedInput is not implemented for key: ${key}`);
+        },
+      },
+    },
     onProgress: (evt) => {
       // evt: { jobId, progress, stage, timeUs? }
       // 这里建议你把进度转发到任务系统/日志/指标
@@ -366,6 +415,23 @@ export async function exportMedeoDraftToMp4(input: {
 }
 ```
 
+#### 5.1 `resolveUploadedInput` 的设计建议（生产强相关）
+
+`ffmpegAudioMix.resolveUploadedInput()` 的目标是：**让 FFmpeg/FFprobe 能读取到已经上传完成的 video-only MP4**。
+
+推荐两种实现：
+
+- **URL 方式（推荐）**：返回 `{ kind: 'url', url, headers? }`
+  - 典型实现：对象存储的 presigned GET URL（必要时附带 headers）
+  - 优点：不依赖本地磁盘、适合多机/容器部署
+- **文件方式**：返回 `{ kind: 'file', filePath }`
+  - 适合你本来就会把导出结果落盘的场景
+
+注意：
+
+- 这是 Node 侧的读取路径，与 runner 的 multipart PUT 上传是两条独立链路
+- 对 URL 方式，确保运行环境网络可达，且必要时带上鉴权 headers
+
 ### 6. 取消与超时（建议）
 
 `exportToStore` 支持 `AbortSignal`（best-effort）：
@@ -400,3 +466,16 @@ multipart 上传必须满足：
 - 每个 part 都完整、连续覆盖；runner 已做 range 覆盖校验
 - `ETag` 必须正确回传给 Node 并用于 complete
 - 对象存储端的 `CompleteMultipartUpload` parts 顺序必须正确（按 partNumber）
+
+#### 7.4 “导出成功但没声音”（Linux 上常见）
+
+如果你看到进度里出现类似 message：
+
+- `Audio skipped: WebCodecs AAC (mp4a.40.2) AudioEncoder is not supported in this browser/runtime.`
+
+那么这是运行时不支持 AAC encode 导致的正常行为，结果会是 **video-only MP4**。
+
+解决建议：
+
+- **推荐**：启用 `postProcess.ffmpegAudioMix`，用 FFmpeg 生成 AAC 并 remux（见 5.x）
+- 如果你不想引入 FFmpeg：只能更换运行时/镜像/发行版，确保 WebCodecs AAC encode 可用（不建议依赖“碰巧某个版本可用”）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meframe/server",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Server-side exporter for @meframe/core (browser-driven, multipart upload via injected store)",
   "type": "module",
   "main": "./dist/esm/index.js",