dsh-song-mv：用代码生成节奏同步的 MV

前言¶

DSH 插件生态中，为智能体增加视觉输出是一个常见需求。现有方案要么依赖现成素材，要么需要手动剪辑，无法在生成时与音频节奏精确同步。dsh-song-mv 提供了一条不同的路径：通过代码描述场景、色彩世界和运镜，让引擎根据音频特征和歌词时间戳逐帧渲染视频。

这是什么¶

dsh-song-mv 是一个运行在 Node.js 环境下的代码渲染引擎，输出为 DSH 可调用的插件，同时也提供命令行接口。它将一首歌曲、对应的 .lrc 歌词文件和一个场景描述文件（storyboard）输入，输出一个与音频节奏同步的 MP4 视频。视频中的每一帧都由代码绘制，没有预制的影像素材或字体文件，音频由 ffmpeg 合成。

核心功能¶

1. 基于代码的视觉描述¶

视频的外观由用户在 JSON 中显式声明。一个 shot（镜头）由以下几部分组成：

look（色彩世界）：全局统一的色调方案，如 paper、rain、daylight、ember、mono、night-shift、cafe 等。
elements（元素集合）：描述画面中的几何体、文字、角色等。支持 rect、ellipse、line、poly、arc、text、dots、band、blob、grid、plane、figure 等类型，每种元素可设置材质、阴影、景深、关键帧轨道等。
camera（运镜）：定义镜头的位移方式，包括 push、pull、panL、panR、tiltUp、tiltDown、rollCW、rollCCW、arc、driftUp、driftDown、none。

2. 声音与节奏同步¶

引擎会先对音频进行分析，提取节拍事件（rings、kicks、camera punches），再根据这些事件驱动画面变化。歌词通过 .lrc 文件中的时间戳填充，支持逐词对齐或固定阅读速率。

3. 场景检查与调试工具¶

提供四个命令行工具帮助开发者调试场景：

song-mv new-scene gutter --out scenes/gutter.mjs：生成脚手架场景，可立即渲染。
song-mv check-imagery --storyboard storyboard.json：检查构图，包括平面、地平线、密度等。
song-mv check-frame --storyboard storyboard.json --features features.json：检查单帧画面效果。
song-mv check-motion --storyboard storyboard.json --features features.json：检查运镜效果，确保镜头不会静止。

安装与启用¶

环境要求¶

需要安装以下两个依赖（均由用户自行安装）：

Node.js ≥ 20.10
ffmpeg ≥ 6.0

安装命令¶

在 DSH 插件目录中执行：

dsh plugin add github:YunxiLuna/dsh-song-mv

安装完成后，插件会出现在技能列表中，可在智能体调用时选择使用。

配置说明¶

插件安装后，会在 DSH 环境中提供相应的技能入口。具体调用方式以 DSH 的插件接口文档为准。

典型用法¶

1. 准备素材¶

准备一个音频文件（如 song.mp3）和对应的 .lrc 歌词文件（如 song.lrc）。

2. 分析音频特征¶

通过插件提供的分析接口提取音频特征：

song analyze song.mp3 --out features.json

3. 编写场景描述¶

创建 storyboard.json 文件，描述镜头、运镜和元素：

{
  "id": "03_sink",
  "start": 43.4,
  "end": 72.0,
  "palette": "build",
  "camera": "push",
  "cameraAmount": 0.09,
  "scene": {
    "type": "field",
    "params": {
      "layer": "water",
      "horizon": 560,
      "motif": "boat",
      "motifAt": [1080, 600, 240],
      "travel": [-220, 0],
      "stage": "sink",
      "sinkAt": 0.5,
      "lyricStyle": "karaoke"
    }
  }
}

4. 渲染视频¶

通过 DSH 插件调用或命令行接口渲染：

song render storyboard.json features.json song.lrc --out output.mp4

渲染过程会先生成逐帧画面，再通过管道传递给 ffmpeg 编码为 MP4 文件。

适用场景与注意¶

dsh-song-mv 适合需要为智能体生成与音频同步的视觉内容，且希望对画面有精细控制能力的开发者。它适用于教育、演示、艺术创作等场景。

注意：插件以当前 dsh 进程的权限运行。安装前应检查源码与许可证，确保符合使用规范。插件本身不包含音频文件和字体，所有素材需由用户提供。

小结¶

dsh-song-mv 将代码渲染与音频分析结合，为 DSH 插件生态增加了一种从零绘制 MV 的能力。通过声明式的场景描述和检查工具，开发者可以系统地控制画面构图、运镜和节奏同步。如需了解更多细节，可访问插件目录或 GitHub 仓库。