AIMusicVideoGen Music Video CLI & MCP

Local MCP server for musicians: BPM and key detection, beat-synced shot lists, Spotify Canvas export and platform video specs.

GitHub

Documentação

aimusicvideogen: free music video tools (CLI + MCP server)

Small, local tools for musicians and AI music creators who are making a music video for a song:

  • Analyze a song: BPM, musical key, Camelot code, beat and bar length, and the most energetic 15 s and 30 s windows (usually the chorus or drop, the clip you want for TikTok, Reels and Shorts).
  • Plan beat-synced shots: a shot list where every cut lands on a bar line, with a visual idea for each section.
  • Make a Spotify Canvas: turn a video clip or a still image into a silent 1080x1920 MP4 of 3 to 8 seconds.
  • Platform specs: aspect ratio, resolution, length and format for TikTok, Instagram Reels, YouTube Shorts, YouTube and Spotify Canvas.

Everything runs on your machine with ffmpeg. No account, no API key, nothing is uploaded.

It also runs as an MCP server, so Claude, Cursor, Windsurf and other MCP clients can analyze your songs and plan videos for you.

Want the whole video made for you? AIMusicVideoGen turns a song and one photo of the singer into a lip-synced, beat-cut music video. This repo is the free, open-source toolbox that grew out of it.

Install

Requires Node.js 18+ and ffmpeg (brew install ffmpeg, winget install ffmpeg, sudo apt install ffmpeg). If ffmpeg is not on your PATH, set FFMPEG_PATH.

npm install -g github:aimusicvideogen-com/music-video-cli
# or run without installing
npx github:aimusicvideogen-com/music-video-cli --help

CLI

aimusicvideogen analyze song.mp3

Duration    40.4 s (19 bars)
Tempo       119 BPM  (half 59.3, double 237)
Key         Bb major  (Camelot 6B, relative G minor)
Beat / bar  0.506 s / 2.025 s
Best 15 s   21.5s - 36.5s
Best 30 s   6.5s - 36.5s

# Shot list from a song file, or from numbers
aimusicvideogen plan song.mp3
aimusicvideogen plan --bpm 100 --duration 200 --offset 0.4

# Spotify Canvas from a video (cut 8 s from 0:12) or from an image (slow seamless zoom)
aimusicvideogen canvas clip.mp4 --start 12 --length 8
aimusicvideogen canvas cover.jpg --length 6 --out canvas.mp4

# Specs
aimusicvideogen specs spotify-canvas
aimusicvideogen specs            # all platforms

# Any command: --json for machine-readable output

MCP server

Add it to your MCP client. For Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) and most others:

{
  "mcpServers": {
    "aimusicvideogen": {
      "command": "npx",
      "args": ["-y", "github:aimusicvideogen-com/music-video-cli", "mcp"]
    }
  }
}

Claude Code:

claude mcp add aimusicvideogen -- npx -y github:aimusicvideogen-com/music-video-cli mcp

Tools

ToolWhat it does
analyze_songBPM, key, Camelot, bar length, duration, best 15 s / 30 s clip of a local audio or video file
plan_music_videoBeat-synced shot list from BPM and duration, optional song structure in bars
make_spotify_canvasSilent 1080x1920 MP4 (3-8 s) from a local video or image
video_specsUpload specs by platform
create_ai_music_videoSteps and link to generate a full lip-synced video from a song and one photo on aimusicvideogen.com

Example prompts:

  • "Analyze ~/Music/demo.mp3 and tell me which 15 seconds to use for TikTok."
  • "Plan a 16:9 music video for this song with a cut on every bar in the chorus."
  • "Make a Spotify Canvas from the first 6 seconds of ~/Videos/teaser.mov."

How it works

  • Tempo: spectral-flux onset envelope, autocorrelation, with the half and double tempo scored together and a mild preference for 120 BPM to settle octave errors. Reported between 70 and 180 BPM by default (minTempo / maxTempo to change).
  • Key: chromagram from a short-time FFT, matched against the Krumhansl-Kessler major and minor profiles.
  • Highlight: the loudest sustained window by RMS energy.

These are estimates. Check the BPM against a tap tempo if a song has tempo changes or a loose groove: free tap tempo, BPM and key finder in the browser.

Related

License

MIT