MV Render

Render music videos with waveform visualization and synced lyrics from audio + lyrics input.

Prerequisites

• Remotion project at

  scripts/

  directory within this skill
• Node.js + npm dependencies installed
• ffprobe available (for audio duration detection)

First-Time Setup

Before first use, check and install dependencies:

# 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

If ffprobe is not available, install ffmpeg (which includes ffprobe):

• Windows:

  choco install ffmpeg

  or download from https://ffmpeg.org/download.html and add to PATH
• macOS:

  brew install ffmpeg

• Linux:

  sudo apt-get install ffmpeg

  (Debian/Ubuntu) or

  sudo dnf install ffmpeg

  (Fedora)

Quick Start

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"

Output: MP4 file at

out/<audio_basename>.mp4

(or custom

--output

path).

Script Usage

./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)
  --browser      Custom browser executable path (Chrome/Edge/Chromium)

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

Browser Detection

Remotion requires a Chromium-based browser for rendering. The script auto-detects browsers in this priority order:

1. BROWSER_EXECUTABLE

   environment variable

2. --browser

   CLI argument
3. Remotion cache (

   chrome-headless-shell

   , downloaded by Remotion)
4. System Chrome (auto-uses

   --chrome-mode=chrome-for-testing

   )
5. System Edge (pre-installed on Windows 10/11, auto-uses

   --chrome-mode=chrome-for-testing

   )
6. System Chromium (auto-uses

   --chrome-mode=chrome-for-testing

   )

Important: New versions of Chrome/Edge removed the old headless mode. When using regular Chrome/Edge/Chromium, the script automatically sets

--chrome-mode=chrome-for-testing

(which uses

--headless=new

). When using

chrome-headless-shell

, it uses the default

headless-shell

mode (which uses

--headless=old

). This is handled transparently.

If no browser is found, Remotion will attempt to download

chrome-headless-shell

from Google servers. This will fail if Google servers are inaccessible from your network.

Workarounds for restricted networks

Since Edge is pre-installed on Windows 10/11, it should be auto-detected without any manual configuration. The script automatically detects Chrome/Edge and uses the correct headless mode. If auto-detection fails:

# 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

Examples

# 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"

File Naming

IMPORTANT: Use the audio file's job ID as the output filename to avoid overwriting. Do NOT use custom names like

--output my_song.mp4

. Let the default naming handle it (derives from audio filename).

Default output uses the audio filename as base:

• Audio:

  acestep_output/{job_id}_1.mp3

• Lyrics:

  acestep_output/{job_id}_1.lrc

• Video: Pass

  --output acestep_output/{job_id}.mp4

  (use the job ID from the audio file)

Example: if audio is

chatcmpl-abc123_1.mp3

, pass

--output acestep_output/chatcmpl-abc123.mp4

Title Guidelines

• Keep

  --title

  short and single-line (max ~50 chars, auto-truncated)
• Use

  --subtitle

  for additional info
• Do NOT put newlines in

  --title

Good:

--title "Open Source" --subtitle "ACE-Step v1.5"

Bad:

--title "Open Source - ACE-Step v1.5\nCelebrating Music AI"

Notes

• Audio files with absolute paths are auto-copied to

  public/

  by render.mjs
• Duration is auto-detected via ffprobe
• Typical render time: ~1-2 minutes for a 90s song
• Output resolution: 1920x1080, 30fps