更新记录

1.0.0（2026-11-11）

1.0.0（2026-11-11）

• 首次发布：uni-app x 双端本地视频合成插件
• 支持花字、字幕渲染（关键词高亮、描边、背景）
• 支持画中画图片叠加
• 支持片头封面（静态图或首帧定格 1 秒）
• 支持背景音乐混音与淡入淡出
• 支持 480p / 720p / 1080p 按短边缩放导出 MP4
• 支持合成进度回调、取消合成
• Android 基于 MediaCodec / MediaMuxer，iOS 基于 AVFoundation，无需 ffmpeg、无需自定义基座

平台兼容性

synthetic-video 本地视频合成

uni-app x 原生 UTS 插件，用于在 App 端本地完成视频合成：花字、字幕、画中画、片头封面、背景音乐混音、分辨率缩放，最终导出 H.264 MP4。

• Android：MediaCodec + MediaMuxer 硬编硬解
• iOS：AVFoundation + AVAssetExportSession
• 零第三方依赖，不需要 ffmpeg，不需要服务端参与
• 只读写 App 沙盒临时文件，不申请相册权限

平台兼容性

安装

1. 将 synthetic-video 目录放入项目的 uni_modules 下。
2. 确认项目的 uni-app x 版本不低于 5.24（见 package.json 的 engines）。
3. 不需要在 manifest.json 中额外声明权限。

快速开始

import { probeVideo, composeVideo, cancelCompose } from '@/uni_modules/synthetic-video'

// 1. 读取视频信息
const info = await probeVideo({ filePath: videoPath })
if (info.errorCode != 0) {
  console.log('读取失败', info.errorMessage)
}

// 2. 合成
let taskId = ''
const result = await composeVideo({
  videoPath,
  texts: [
    {
      text: '标题文字',
      style: titleStyle,
      startSec: 0,
      durationSec: 5,
      isTitle: true
    }
  ],
  overlays: [],
  keywords: ['关键词'],
  canvasWidth: 720,
  canvasHeight: 1280,
  bgmPath: null,
  bgmVolume: 20,
  introCoverPath: null,
  resolution: '720p',
  outputPath: null,
  onStart: (id : string) => {
    taskId = id
  },
  onProgress: (p) => {
    console.log(p.stage, p.percent)
  }
})

if (result.errorCode == 0) {
  console.log('成片路径', result.filePath)
} else {
  console.log('合成失败', result.errorCode, result.errorMessage)
}

// 3. 取消（可选）
// await cancelCompose({ taskId })

选择素材时建议使用 uni.chooseVideo({ compressed: false })。默认的 compressed: true 会先生成 360p / 540p 的临时文件，再合成也无法恢复清晰度。

API

所有 API 均返回 Promise，结果对象包含 errorCode 和 errorMessage，errorCode == 0 表示成功。业务失败通过 errorCode 返回，不会主动 reject。

probeVideo

读取视频宽高与时长，宽高已按旋转元数据校正。

返回 ProbeVideoResult：

renderTextImage

渲染单张透明花字 PNG，用于页面实时预览。样式与成片共用同一套绘制逻辑。

返回 RenderTextImageResult：

composeVideo

执行完整本地合成：渲染花字 → 叠加画中画 → 缩放 → 混音 → 插入片头 → 导出。

ComposeTextItem：

ComposeTextStyle：

overlays 每项字段：

层级顺序：正片 → 画中画 → 花字。

ComposeProgress：

返回 ComposeVideoResult：

cancelCompose

取消正在进行的合成，取消后插件会清理临时文件。

返回 CancelComposeResult：errorCode、errorMessage、ok（是否成功发出取消指令）。

compressVideo

本地受控压缩，用于上传前把素材压成统一规格。

返回 CompressVideoResult：errorCode、errorMessage、filePath、width、height、durationSec、sizeBytes。

错误码

注意事项

1. 输出尺寸以画布为准：resolution 只做合法性校验；实际输出宽高由 canvasWidth / canvasHeight 决定。
2. 不放大低分辨率素材：画布大于源视频时按 1 倍处理，不会插值放大。
3. BGM 是混音，不是替换：填入 bgmPath 后原声仍然保留，BGM 按 bgmVolume 增益叠加，并带淡入淡出。当前版本没有“静音原声”参数。
4. BGM 路径必须真实存在：路径错误或解码失败时会跳过 BGM，保留原声。
5. 片头规则：introCoverPath 为 null 时使用正片首帧定格 1 秒；传入封面时按封面图生成 1 秒片头。
6. 不自动保存相册：outputPath 为 null 时成片在 App 临时目录，需要调用方自行调用 uni.saveVideoToPhotosAlbum。
7. Android 码率：按 宽 × 高 × 帧率 × 0.2 计算，限制在 2 ~ 24 Mbps；1080p30 约 12.4 Mbps。
8. iOS 导出：使用 AVAssetExportPresetHighestQuality，由系统决定码率，通常高于 Android。
9. 临时文件：取消或失败时插件会尽力清理本次任务的临时文件，页面侧可定期清理缓存目录。
10. H5 / 小程序：不支持本地合成，调用返回 9100402。

更新日志

1.0.0（2026-11-11）

• 首次发布
• 支持花字、字幕渲染（关键词高亮、描边、背景）
• 支持画中画图片 / 视频叠加
• 支持片头封面（静态图或首帧定格 1 秒）
• 支持背景音乐混音与淡入淡出
• 支持 480p / 720p / 1080p 导出
• 支持合成进度回调与取消
• 支持本地受控压缩 compressVideo