mcpField
A
acestep-simplemv

acestep-simplemv

github.com/ace-step创意与媒体14.1k74 次安装9 周前更新
代码仓库

关于 acestep-simplemv

将音频与带时间戳的歌词渲染为音乐视频的技能，使用 Remotion 添加波形可视化和同步歌词，并可设置标题、副标题、输出路径及压缩。

主要功能

  1. 01渲染带波形的音乐视频
  2. 02将时间戳歌词与音频同步
  3. 03支持 LRC 或 JSON 歌词
  4. 04设置视频标题和副标题
  5. 05按大小限制压缩输出

适用场景

  1. 01根据歌曲制作歌词视频
  2. 02渲染带波形可视化的视频
  3. 03准备便于分享的小体积视频

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ace-step/ace-step-1.5 --skill acestep-simplemv

安装后在 Claude Code 中输入/acestep-simplemv确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

scripts/
package-lock.json
package.json
remotion.config.ts
render-mv.sh
render.mjs
render.sh
tsconfig.json
scripts/src/
AudioVisualization.tsx
index.ts
parseLrc.ts
Root.tsx
types.ts

详细介绍

MV Render

根据音频和歌词输入，渲染带有波形可视化和同步歌词的音乐视频。

前置条件

  • 此技能目录中的 scripts/ 内包含 Remotion 项目
  • 已安装 Node.js 和 npm 依赖项
  • 可用的 ffprobe（用于检测音频时长）
首次设置

首次使用前，请检查并安装依赖项：

# 1. Check Node.js
node --version

# 2. Install npm dependencies
cd {project_root}/{.claude or .codex}/skills/acestep-simplemv/scripts && npm install

# 3. Check ffprobe
ffprobe -version

如果没有 ffprobe，请安装 ffmpeg（其中包含 ffprobe）：

  • Windows：choco install ffmpeg，或从 https://ffmpeg.org/download.html 下载并添加到 PATH
  • macOS：brew install ffmpeg
  • Linux：sudo apt-get install ffmpeg（Debian/Ubuntu）或 sudo dnf install ffmpeg（Fedora）

快速开始

cd {project_root}/{.claude or .codex}/skills/acestep-simplemv/
./scripts/render-mv.sh --audio /path/to/song.mp3 --lyrics /path/to/song.lrc --title "Song Title"

输出：位于 out/<audio_basename>.mp4 的 MP4 文件（或自定义的 --output 路径）。

脚本用法

./scripts/render-mv.sh --audio <file> --lyrics <lrc_file> --title "Title" [options]

Options:
  --audio        Audio file path (absolute paths supported)
  --lyrics       LRC format lyrics file (timestamped)
  --lyrics-json  JSON lyrics file [{start, end, text}] (alternative to --lyrics)
  --title        Video title (default: "Music Video")
  --subtitle     Subtitle text
  --credit       Bottom credit text
  --offset       Lyric timing offset in seconds (default: -0.5)
  --output       Output file path (default: out/<audio_basename>.mp4)
  --codec        h264|h265|vp8|vp9 (default: h264)
  --background   Background image file path (if omitted, uses animated gradient)
  --browser      Custom browser executable path (Chrome/Edge/Chromium)
  --max-size     Max output file size in MB (e.g. 24). Auto-compresses if exceeded.
                 Use for IM platforms (WhatsApp≤16MB, Discord≤25MB, Telegram≤50MB)

Environment variables:
  BROWSER_EXECUTABLE  Path to browser executable (overrides auto-detection)

浏览器检测

Remotion 需要基于 Chromium 的浏览器才能渲染。脚本会按以下优先级自动检测浏览器：

  1. BROWSER_EXECUTABLE 环境变量
  2. --browser CLI 参数
  3. Remotion 缓存（由 Remotion 下载的 chrome-headless-shell）
  4. 系统 Chrome（自动使用 --chrome-mode=chrome-for-testing）
  5. 系统 Edge（Windows 10/11 预装，自动使用 --chrome-mode=chrome-for-testing）
  6. 系统 Chromium（自动使用 --chrome-mode=chrome-for-testing）

重要提示：新版 Chrome/Edge 移除了旧版无头模式。使用常规 Chrome/Edge/Chromium 时，脚本会自动设置 --chrome-mode=chrome-for-testing（使用 --headless=new）。使用 chrome-headless-shell 时，则采用默认的 headless-shell 模式（使用 --headless=old）。此过程会透明处理。

如果未找到浏览器，Remotion 将尝试从 Google 服务器下载 chrome-headless-shell。如果你的网络无法访问 Google 服务器，下载将会失败。

受限网络的解决方法

由于 Windows 10/11 预装了 Edge，因此无需手动配置即可自动检测到。脚本会自动检测 Chrome/Edge 并使用正确的无头模式。如果自动检测失败：

# Option 1: Set environment variable
export BROWSER_EXECUTABLE="/path/to/msedge.exe"

# Option 2: Pass as CLI argument
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --browser "/path/to/msedge.exe"

# Option 3: Enable proxy and let Remotion download chrome-headless-shell

示例

# Basic render
./scripts/render-mv.sh --audio /tmp/abc123_1.mp3 --lyrics /tmp/abc123.lrc --title "夜桜"

# Custom output path
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "My Song" --output /tmp/my_mv.mp4

# With subtitle and credit
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --subtitle "Artist Name" --credit "Generated by ACE-Step"

# With background image
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --background /path/to/cover.jpg

# Compress for Discord upload (max 25MB)
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --max-size 24

# Compress for WhatsApp (max 16MB)
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --max-size 15

即时通信平台上传限制

向聊天平台发送 MV 时，使用 --max-size 自动压缩：

平台限制建议的 --max-size
WhatsApp16MB10
Discord（免费版）25MB10
QQ10MB10
Telegram50MB20
Slack（免费版）1GB-

压缩使用 ffmpeg 双遍编码，以在大小限制内实现最佳画质。

容器 / Docker 字体支持

在容器中运行时（例如 OpenClaw），可能未预装 CJK 字体，导致歌词渲染为 □ 方框。脚本会自动：

  1. 检测是否有可用的 CJK 字体（通过 fc-list）
  2. 尝试安装 fonts-noto-cjk（Debian/Ubuntu）、font-noto-cjk（Alpine）或 google-noto-sans-cjk-fonts（Fedora/RHEL）
  3. 如果自动安装失败，则回退并显示警告和手动安装说明

如果自动安装不起作用，请在渲染前手动安装字体：

# Debian/Ubuntu
apt-get install -y fonts-noto-cjk

# Alpine
apk add font-noto-cjk

# Fedora/RHEL
dnf install -y google-noto-sans-cjk-fonts

文件命名

重要提示：使用音频文件的作业 ID 作为输出文件名，以避免覆盖文件。不要使用 --output my_song.mp4 这样的自定义名称。使用默认命名方式（根据音频文件名生成）。

默认输出以音频文件名为基础：

  • 音频：acestep_output/{job_id}_1.mp3
  • 歌词：acestep_output/{job_id}_1.lrc
  • 视频：传入 --output acestep_output/{job_id}.mp4（使用音频文件中的作业 ID）

示例：如果音频文件为 chatcmpl-abc123_1.mp3，则传入 --output acestep_output/chatcmpl-abc123.mp4

标题指南

  • --title 应简短且为单行（最多约 50 个字符，超出部分会自动截断）
  • 其他信息请使用 --subtitle
  • --title 中不要包含换行符

建议：--title "Open Source" --subtitle "ACE-Step v1.5" 不建议：--title "Open Source - ACE-Step v1.5\nCelebrating Music AI"

注意事项

  • render.mjs 会自动将绝对路径的音频文件复制到 public/
  • 时长由 ffprobe 自动检测
  • 典型渲染时间：90 秒歌曲约需 1-2 分钟
  • 输出分辨率：1920x1080，30fps

评论

支持 Markdown