---
name: Visualizer — CLI Music Video Generator (fork)
description: 
---

# Visualizer — CLI Music Video Generator

Generate fast-cut, beat-synced music videos from text prompts. Scrapes GIFs/videos by keyword, detects beats in audio, and renders a full video with effects and transitions.

## Triggers

Use when the user asks to create a visualizer, music video, GIF compilation, beat-synced video, or visual edit. Keywords: "visualizer", "music video", "gif video", "beat sync", "fast cuts", "visual edit", "make me a video".

## Setup

First-time setup (run once):
```bash
cd /Users/black/visualizer-skill
pip install -r requirements.txt
```

Requires: Python 3.10+, FFmpeg (`brew install ffmpeg`)

## Usage

### From prompt (parse natural language):

```python
# In the skill, parse the user's prompt:
from visualizer import parse_prompt

settings = parse_prompt("punk gif visualizer, extremely fast, all effects in use")
# Returns: {query: "punk", speed: "extreme", effects: "all", ...}
```

### CLI:

```bash
cd /Users/black/visualizer-skill

# Basic — scrape GIFs and make a video
python visualizer.py --query "punk aesthetic" --audio ~/Music/track.mp3 --speed fast

# All effects, extreme speed, vertical
python visualizer.py -q "anime fight" -a beat.mp3 -s extreme -e all --aspect 9:16

# From local folder
python visualizer.py --folder ~/Downloads/gifs -a song.wav -s fast

# Specific effects only
python visualizer.py -q "vaporwave" -a track.mp3 -e mirror,invert,stutter -s extreme

# Square output, high sensitivity beat detection
python visualizer.py -q "glitch art" -a beat.wav --aspect 1:1 --sensitivity 0.8

# No beat sync, random timing
python visualizer.py -q "nature" -a ambient.mp3 --no-beat-sync -s slow
```

### Parameters:

| Flag | Description | Default |
|------|-------------|---------|
| `--query, -q` | Search keywords for assets | required (or --folder) |
| `--folder, -f` | Local asset folder | - |
| `--audio, -a` | Audio file path | required |
| `--speed, -s` | Cut speed: slow/normal/fast/extreme | fast |
| `--aspect` | Output: 9:16, 1:1, 16:9 | 9:16 |
| `--effects, -e` | Effects: all or comma-separated list | all |
| `--transitions, -t` | Transitions: all or comma-separated | all |
| `--sensitivity` | Beat detection 0.0-1.0 | 0.5 |
| `--no-beat-sync` | Disable beat sync | false |
| `--output, -o` | Output path | ~/Documents/Visualizer/ |
| `--bitrate` | Video bitrate | 8M |
| `--limit` | Max assets to scrape | 40 |
| `--sources` | Asset sources: giphy,tenor,pinterest | giphy,tenor |

### Effects:
- **clean** — normal playback
- **mirror** — horizontal flip
- **reverse** — plays backwards
- **stutter** — repeats frames rapidly
- **speed_up** — 1.5-3x speed
- **slow_down** — 0.25-0.75x speed
- **invert** — inverted colors

### Transitions:
- **hard_cut** — instant switch
- **fade** — cross-dissolve
- **flash** — white flash
- **glitch** — RGB displacement

## Example Prompts → Commands:

"punk gif visualizer, extremely fast, all effects"
→ `python visualizer.py -q "punk" -a <audio> -s extreme -e all`

"chill anime aesthetic, slow, mirror and invert"
→ `python visualizer.py -q "anime aesthetic" -a <audio> -s slow -e mirror,invert`

"glitch art beat synced, square format"
→ `python visualizer.py -q "glitch art" -a <audio> -s fast --aspect 1:1 --sensitivity 0.7`

"nature footage, no beat sync, landscape, relaxed"
→ `python visualizer.py -q "nature" -a <audio> -s slow --no-beat-sync --aspect 16:9`

## Output

Videos are saved to `~/Documents/Visualizer/visualizer_YYYYMMDD_HHMMSS.mp4`

Report the output path and file size to the user when done.