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

acestep-simplemv

设计与创作

查看项目

更新于 10-15 11:31

技能介绍

acestep-simplemv 是一个音乐视频（MV）渲染技能，核心目标是根据音频文件和歌词生成带波形可视化与同步歌词的 MP4 视频。它使用 Remotion 作为渲染引擎。

用途 该技能用于把一首歌的音频与对应歌词合成为音乐视频。输出视频包含波形可视化与同步歌词，默认输出分辨率 1920x1080，帧率 30fps。

主要能力

  • 接受音频 + LRC/JSON 歌词 + 标题作为输入，生成 MP4 视频。
  • 支持 LRC 格式（带时间戳）歌词，也支持 JSON 格式歌词（[{start, end, text}]）。
  • 可配置标题、副标题、底部署名文字。
  • 支持歌词时间偏移（--offset，默认 -0.5 秒）。
  • 可指定输出文件路径、编码格式（h264|h265|vp8|vp9，默认 h264）。
  • 可指定背景图片；若省略则使用动态渐变背景。
  • 支持输出文件大小上限（--max-size，单位 MB），超限时自动用 ffmpeg 两遍编码压缩。
  • 自动通过 ffprobe 探测音频时长。
  • 自动检测并选择合适的 Chromium 系浏览器进行渲染。
  • 在容器环境中可检测并尝试自动安装 CJK 字体，避免歌词显示为方框。

使用方式 前置条件：

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

首次使用前检查与安装依赖：

  • 检查 Node.js：node --version
  • 安装 npm 依赖：cd {project_root}/{.claude 或 .codex}/skills/acestep-simplemv/scripts && npm install
  • 检查 ffprobe：ffprobe -version
  • 若 ffprobe 不可用，需安装 ffmpeg（包含 ffprobe）：Windows 可用 choco install ffmpeg 或从 https://ffmpeg.org/download.html 下载并加入 PATH；macOS 用 brew install ffmpeg；Linux（Debian/Ubuntu）用 sudo apt-get install ffmpeg，（Fedora）用 sudo dnf install ffmpeg。

快速开始： cd {project_root}/{.claude 或 .codex}/skills/acestep-simplemv/ ./scripts/render-mv.sh --audio /path/to/song.mp3 --lyrics /path/to/song.lrc --title "Song Title" 输出为 out/<音频文件名>.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/<音频文件名>.mp4）
  • --codec h264|h265|vp8|vp9（默认 h264）
  • --background 背景图片路径（省略则使用动态渐变）
  • --browser 自定义浏览器可执行文件路径（Chrome/Edge/Chromium）
  • --max-size 输出文件大小上限（MB，例如 24），超限自动压缩，适用于 IM 平台（WhatsApp≤16MB，Discord≤25MB，Telegram≤50MB）

环境变量：

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

浏览器检测： Remotion 需要 Chromium 系浏览器进行渲染。脚本按以下优先级自动检测：BROWSER_EXECUTABLE 环境变量、--browser 参数、Remotion 缓存（chrome-headless-shell，由 Remotion 下载）、系统 Chrome（自动使用 --chrome-mode=chrome-for-testing）、系统 Edge（Windows 10/11 预装，自动使用 --chrome-mode=chrome-for-testing）、系统 Chromium（自动使用 --chrome-mode=chrome-for-testing）。新版 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；若网络无法访问 Google 服务器则失败。受限网络下的变通方法：Windows 10/11 预装 Edge 应可自动检测；若失败可设置 export BROWSER_EXECUTABLE="/path/to/msedge.exe"，或作为 CLI 参数传入 --browser "/path/to/msedge.exe"，或启用代理让 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 平台上传限制：向聊天平台发送 MV 时可用 --max-size 自动压缩。平台限制与推荐的 --max-size：WhatsApp 16MB / 15；Discord（免费）25MB / 24；Telegram 50MB / 48；Slack（免费）1GB / -。压缩使用 ffmpeg 两遍编码，在体积约束下取得最佳质量。

容器 / Docker 字体支持：在容器（如 OpenClaw）中运行时可能未预装 CJK 字体，导致歌词显示为 □ 方框。脚本会自动：通过 fc-list 检测 CJK 字体是否可用；尝试安装 fonts-noto-cjk（Debian/Ubuntu）、font-noto-cjk（Alpine）或 google-noto-sans-cjk-fonts（Fedora/RHEL）；若自动安装失败则给出警告和手动安装说明。手动安装：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。若音频为 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"。

适用场景

  • 将歌曲音频与歌词快速制作成带波形与同步歌词的 MP4。
  • 需要按聊天平台体积限制压缩后再分享的 MV。
  • 需要自定义标题、副标题、署名或背景图片的 MV 渲染。

限制与注意事项

  • 需要 Remotion 项目、Node.js 与 npm 依赖、ffprobe。
  • 渲染需要 Chromium 系浏览器；受限网络下若无法访问 Google 服务器可能无法自动下载 chrome-headless-shell。
  • 容器环境中若无法自动安装 CJK 字体，歌词可能显示为方框。
  • 典型渲染时间约为 90 秒歌曲 1-2 分钟。
  • 文件中未提供收费、价格或其它未提及的平台信息。