SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场acestep-simplemv

acestep-simplemv

设计与创作

查看项目

更新于 10-15 10:51

技能介绍

用途

acestep-simplemv 用于从音频文件和歌词生成音乐视频（MV）。它输出带波形可视化与同步歌词的 MP4 视频，适合为歌曲快速制作可视化视频。

主要能力

  • 输入音频文件 + LRC 或 JSON 歌词 + 标题，渲染出 MP4 视频。
  • 支持波形可视化与同步歌词显示。
  • 支持自定义标题、副标题、底部署名文本。
  • 支持歌词时间偏移调整（--offset，默认 -0.5 秒）。
  • 支持自定义背景图片；未提供时使用动态渐变背景。
  • 支持选择编解码器：h264、h265、vp8、vp9（默认 h264）。
  • 支持按最大文件体积自动压缩（--max-size），使用 ffmpeg 两遍编码，适配 IM 平台上传限制。
  • 自动检测音频时长（通过 ffprobe）。
  • 在容器环境中自动检测 CJK 字体，并尝试安装 fonts-noto-cjk 等字体包，避免歌词渲染为方框。
  • 自动检测 Chromium 系浏览器用于 Remotion 渲染，并自动选择合适的 headless 模式。

使用方式

前置条件：

  • 本技能 scripts/ 目录下存在 Remotion 项目。
  • 已安装 Node.js 与 npm 依赖。
  • ffprobe 可用（用于检测音频时长）。

首次设置：

# 1. 检查 Node.js
node --version

# 2. 安装 npm 依赖
cd {project_root}/{.claude or .codex}/skills/acestep-simplemv/scripts && npm install

# 3. 检查 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"

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

脚本用法：

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

选项：

  • --audio：音频文件路径（支持绝对路径）
  • --lyrics：LRC 格式歌词文件（带时间戳）
  • --lyrics-json：JSON 歌词文件 [{start, end, text}]（替代 --lyrics）
  • --title：视频标题（默认 "Music Video"）
  • --subtitle：副标题文本
  • --credit：底部署名文本
  • --offset：歌词时间偏移（秒，默认 -0.5）
  • --output：输出文件路径（默认 out/<audio_basename>.mp4）
  • --codec：h264|h265|vp8|vp9（默认 h264）
  • --background：背景图片路径（省略则使用动态渐变）
  • --browser：自定义浏览器可执行文件路径（Chrome/Edge/Chromium）
  • --max-size：输出文件最大体积（MB，如 24），超出时自动压缩

环境变量：

  • BROWSER_EXECUTABLE：浏览器可执行文件路径（覆盖自动检测）

浏览器检测优先级：

  1. BROWSER_EXECUTABLE 环境变量
  2. --browser CLI 参数
  3. Remotion 缓存（chrome-headless-shell）
  4. 系统 Chrome
  5. 系统 Edge（Windows 10/11 预装）
  6. 系统 Chromium

注意：新版 Chrome/Edge 移除了旧 headless 模式。使用常规 Chrome/Edge/Chromium 时脚本自动设置 --chrome-mode=chrome-for-testing（使用 --headless=new）；使用 chrome-headless-shell 时使用默认 headless-shell 模式（--headless=old）。若未找到浏览器，Remotion 会尝试从 Google 服务器下载 chrome-headless-shell，网络受限时可能失败。

受限网络下的变通方法：

# 选项 1：设置环境变量
export BROWSER_EXECUTABLE="/path/to/msedge.exe"

# 选项 2：作为 CLI 参数传入
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --browser "/path/to/msedge.exe"

# 选项 3：启用代理让 Remotion 下载 chrome-headless-shell

示例：

# 基础渲染
./scripts/render-mv.sh --audio /tmp/abc123_1.mp3 --lyrics /tmp/abc123.lrc --title "夜桜"

# 自定义输出路径
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "My Song" --output /tmp/my_mv.mp4

# 带副标题和署名
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --subtitle "Artist Name" --credit "Generated by ACE-Step"

# 带背景图片
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --background /path/to/cover.jpg

# 为 Discord 上传压缩（最大 25MB）
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --max-size 24

# 为 WhatsApp 压缩（最大 16MB）
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --max-size 15

IM 平台上传限制与推荐 --max-size：

  • WhatsApp：16MB，推荐 10
  • Discord（免费）：25MB，推荐 10
  • QQ：10MB，推荐 10
  • Telegram：50MB，推荐 20
  • Slack（免费）：1GB，无

压缩使用 ffmpeg 两遍编码，在体积限制内实现最佳质量。

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

  1. 通过 fc-list 检测 CJK 字体是否可用
  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

文件命名： 建议使用音频文件的 job ID 作为输出文件名以避免覆盖。不要使用 --output my_song.mp4 这类自定义名称，让默认命名处理（从音频文件名派生）。

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

  • 音频：acestep_output/{job_id}_1.mp3
  • 歌词：acestep_output/{job_id}_1.lrc
  • 视频：传入 --output acestep_output/{job_id}.mp4（使用音频文件中的 job 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"

适用场景

  • 为歌曲快速生成带波形和同步歌词的可视化 MV。
  • 需要按 IM 平台体积限制压缩视频后分享。
  • 在容器环境中渲染含中日韩文字的歌词视频。

限制

  • 依赖 Remotion 项目、Node.js、npm 依赖和 ffprobe。
  • 渲染需要 Chromium 系浏览器；受限网络下可能无法自动下载 chrome-headless-shell。
  • 容器中若 CJK 字体缺失且自动安装失败，歌词可能显示为方框。
  • 输出分辨率为 1920x1080、30fps；90 秒歌曲典型渲染时间约 1-2 分钟。
  • 关于收费、价格、平台支持范围等更多信息，资料中暂未提供。