Music Video

# Music Video

Use this skill when the user wants to generate a Freebeat music video from a song, prompt, and optional references.

## Before running CLI commands

Freebeat CLI is an npm package and authenticated API client. Install or refresh it first:

~~~bash
npm install -g freebeat-cli@latest
freebeat --help
~~~

The user must provide a Freebeat API key before generation. Use one of these patterns:

~~~bash
freebeat auth set-api-key
printf '%s' "$FREEBEAT_API_KEY" | freebeat auth set-api-key --stdin
freebeat --api-key <apiKey> <command>
~~~

Validate credentials before starting a paid or long-running workflow:

~~~bash
freebeat auth show
freebeat auth test
~~~

Do not paste or log the raw API key. Ask the user to provide it in their terminal, secret store, or environment variable.

## Prepare assets

~~~bash
freebeat assets upload-audio --file song.mp3
freebeat assets upload-audio --url https://www.youtube.com/watch?v=abc123
freebeat assets upload-image ref-a.jpg ref-b.jpg
~~~

## Submit an MV task from uploaded assets

~~~bash
freebeat mv submit --music-id <musicId> --prompt "neon city, fast cuts" --image-url <imageUrl> --aspect-ratio 9:16 --wait
~~~

## Run an MV task from local assets

~~~bash
freebeat mv run --audio song.mp3 --image ref.png --prompt "neon city, fast cuts" --aspect-ratio 9:16 --wait
~~~

MV commands support options such as --image-url, --image, --mv-type, --style, --aspect-ratio, --resolution, --watermark, --start-ms, --end-ms, and --wait.

## Check progress

Open RPC image and video commands return a batch id and serial number. Legacy MV and effect commands return a task id.

~~~bash
freebeat task status <batch-id>
freebeat task status <batch-id> --serial-no <serial-no>
freebeat task wait <batch-id> --serial-no <serial-no>
freebeat task status <task-id>
freebeat task wait <task-id>
freebeat task result <task-id>
~~~

Use --json when another agent, script, or CI job needs to parse task ids, batch ids, serial numbers, result URLs, credits, or statuses.