Audio Visualizer

A plugin-based Python tool for converting audio files into animated visualizer videos.

Features

• Plugin Architecture: Easily create, add, or remove visualizer plugins
• Multiple Visualizer Modes: Choose from several visualization styles
• Hardware Acceleration: NVENC (NVIDIA), QSV (Intel), VA-API (Linux) support
• Multiple Output Formats: MP4, MKV, WebM, AVI, MOV, FLV
• Batch Processing: Process entire directories of audio files
• Progress Tracking: Real-time progress bar with ETA
• Customizable: Adjust resolution, FPS, preset, CRF, and more

Available Visualizers

• Spectrum (default) - Classic frequency spectrum bars
• Waveform - Audio waveform visualization
• Bars - Animated bar visualization
• Radial - Radial/circular spectrum display
• Spectrogram - Time-frequency spectrogram
• Vectorscope - Psychedelic circular visualization
• Album Art - Visualizer with album art overlay

Requirements

• Python 3.10+
• FFmpeg ≥ 6.0 - Required for video encoding. The detected version is checked at startup (clear error below the project minimum); plugins may declare a higher requires_ffmpeg_version, and the selected modes are checked against the detected version before encoding starts.

Tested on Linux and macOS (macOS via the PR smoke subset). Windows is not tested and is deferred to a later release.

Installation

1. Clone the repository:

   git clone <repository-url>
   cd audio-visualizer
   

2. Install FFmpeg:

   • Ubuntu/Debian: sudo apt install ffmpeg
   • macOS: brew install ffmpeg
   • Windows: Download from ffmpeg.org

3. Install the package:

   pip install .
   

Usage

Basic Usage

audio-visualizer input.mp3

Specify a Visualizer Mode

audio-visualizer input.mp3 --mode waveform
audio-visualizer input.mp3 --mode radial

# Compose several visualizers side by side in one frame
audio-visualizer input.mp3 --mode spectrum waveform

Combo presets are available as a single --mode value — --mode spectrum+waveform is equivalent to --mode spectrum waveform — and --list-plugins shows the built-in presets under [combos]. Any combination of loaded modes works; unknown or duplicated names fail with the standard mode error.

Per-Mode Options

Append :key=value pairs to a mode name to override that mode's options in a composite — repeat --mode (or list several specs) to pair several modes:

# spectrum on a navy background, vectorscope zoomed in 1.5x
audio-visualizer input.mp3 --mode "spectrum:bg_color=navy" --mode "vectorscope:zoom=1.5"

• Keys may be the mode's full option name (spectrum-opacity) or the bare name with the mode prefix stripped (opacity). Values are validated against that mode's option schema.
• bg_color and colors are accepted per mode (useful when two modes want different backgrounds); opacity (0.0–1.0) additionally works per mode on --compose overlay — the last mode is always opaque.
• Multiple pairs are comma-separated: --mode "spectrum:bg_color=navy,colors=red,blue" (commas inside a value are fine as long as they don't form a new key=).
• Precedence: per-mode pair > global CLI flag > config file > default. A global flag still applies to modes without a pair, and unpaired shared options resolve first-mode-wins (with a warning), as before.
• --dry-run --json surfaces the resolved per-mode values under per_mode_options.

Tile Grid

--compose tile places modes in a row-major ceil(sqrt(n)) x ceil(n/cols) grid by default. --compose-grid ROWSxCOLS places the cells explicitly (e.g. --compose tile --compose-grid 2x3 --mode spectrum waveform bars puts the three modes in the first row of a 2x3 grid); a grid larger than the mode count pads the remaining cells with the background color, and a grid with fewer cells than modes is an error.

Custom Output

audio-visualizer input.mp3 -o output.mp4 --resolution 1920x1080

Hardware Acceleration

# Auto-detect (default)
audio-visualizer input.mp3

# Force NVIDIA encoding
audio-visualizer input.mp3 --accel nvenc

# Force Intel Quick Sync
audio-visualizer input.mp3 --accel qsv

# Force Linux VA-API
audio-visualizer input.mp3 --accel vaapi

# Disable hardware acceleration
audio-visualizer input.mp3 --accel disabled

Output Format

# MP4 (default)
audio-visualizer input.mp3

# MKV
audio-visualizer input.mp3 --format mkv

# WebM (VP9)
audio-visualizer input.mp3 -f webm

# AVI
audio-visualizer input.mp3 -f avi

Color Themes

--theme applies a built-in color palette to the visualizer; --list-themes shows the available themes (with color swatches when the output is a tty and the palette length, so you can compare them).

Custom themes — drop a JSON file in ~/.config/audio-visualizer/themes/<name>.json:

{"palette": ["red", "orange", "gold", "white"]}

The palette is a list of 1–12 color names (or #rrggbb hex values). The theme is then usable as --theme <name>, the AUDIO_VISUALIZER_THEME env var, or theme: in the config file. A user theme with the same name as a built-in overrides it; --list-themes shows built-in and user themes in separate sections. Malformed theme files are skipped with a warning.

Precedence: an explicit --colors always wins; otherwise CLI --theme > AUDIO_VISUALIZER_THEME env var > theme in the config file. Built-in and custom themes may each carry up to 12 colors; visualizers that accept a color list (e.g. showfreqs, showwaves) interpolate longer palettes.

Batch Processing

Process all audio files in a directory:

# Process all audio files in a directory
audio-visualizer ./my-album/ --batch

# Short form
audio-visualizer ./my-album/ -b

# With custom settings
audio-visualizer ./my-album/ -b --mode waveform --resolution 1920x1080

# Parallel encode (N ffmpeg jobs; 'auto' = CPU count)
audio-visualizer ./my-album/ -b --parallel auto

# Recursive scan + glob filters (both repeatable)
audio-visualizer ./music/ -b --recursive --include "*.mp3" --exclude "*lossless*"

# From an .m3u/.m3u8 playlist - entries run in playlist order
audio-visualizer ./my-album/list.m3u8
audio-visualizer -b ./my-album/list.m3u8

A single input that is an .m3u/.m3u8 file is expanded in order and processed as a batch (the batch report is the result); a playlist may also be passed directly as the --batch root. Comment/#EXT* lines are skipped, entries resolve against the playlist's directory, and missing entries get their own failure row in the report.

# Custom output naming - placeholders: {name} {ext} {mode} {width}
audio-visualizer ./my-album/ -b --output-template "{name}_{mode}.{ext}"

Discovery and naming:

• --recursive - scan subdirectories as well
• --include PATTERN / --exclude PATTERN - repeatable globs matched against the path relative to the batch directory; the built-in audio extension list is the default include
• --output-template TEMPLATE (default {name}_visualizer.{ext})

Every batch run writes <outdir>/batch_report.json with per-file status, output path, size, duration, failure reason, and timestamp. The exit code is non-zero only when at least one file failed (clean run -> 0, failures -> 1), so CI can gate on the batch exit code.

Supported formats: MP3, WAV, FLAC, OGG, M4A, AAC, WMA

Environment Variables

All configuration options can be set via environment variables with the AUDIO_VISUALIZER_ prefix. This is useful for Docker, CI/CD, or shell profiles.

# Set resolution and FPS via environment
export AUDIO_VISUALIZER_RESOLUTION=1920x1080
export AUDIO_VISUALIZER_FPS=60
export AUDIO_VISUALIZER_PRESET=fast

audio-visualizer input.mp3

Supported environment variables:

Precedence: CLI arguments > environment variables > config file > defaults.

Configuration File

Options can be persisted to ~/.audio_visualizer/config.yml. Use --save-config to write the current options and --config to display the file:

audio-visualizer input.mp3 --save-config
audio-visualizer --config

Per-plugin options can be set in indented sections. Values are validated against each plugin's option schema (type, choices, range):

# Global options
resolution: 1920x1080
fps: 60

# Per-plugin options
spectrum:
  mode: rainbow
  opacity: 0.8
waveform:
  mode: line
  splits: 2

Unknown plugins/options and values that fail validation are skipped with a warning, so a broken config file never crashes the tool.

List Available Plugins

audio-visualizer --list-plugins

Add --json for a machine-readable payload (plugin metadata plus full option schemas).

Diagnose the Environment

audio-visualizer --doctor

Reports the ffmpeg version against the project minimum, whether each visualizer's filters are present in your ffmpeg build, the hardware encoders available, the config file path and validity, and the plugin load report (failures include the reason). --doctor --json emits the same report as JSON; the exit code is non-zero when anything is wrong, so it is usable as a preflight check in CI.

Install Custom Plugins

audio-visualizer --install-plugin my_plugin.py

Installs the plugin to ~/.audio_visualizer/plugins, where it is auto-discovered on every run.

Load External Plugins

Plugins can be loaded without installing, either for one run or for all runs:

# From the command line (repeatable, file or directory)
audio-visualizer --plugin-path ~/plugins/my_plugin.py --mode myviz input.mp3
audio-visualizer --plugin-path ~/plugins/ --list-plugins

# For all runs, via environment variable (path-separated list)
export AUDIO_VISUALIZER_PLUGIN_PATH=~/plugins/my_plugin.py:~/plugins/other/

Third-party distributions can ship plugins too: register them under the audio-visualizer.plugins entry-point group (see Creating a New Visualizer Plugin). Installed plugins and --plugin-path plugins shadow built-ins of the same name, with a warning; --list-plugins --verbose shows each plugin's source (builtin, entrypoint, installed, or path). Plugins from path or entrypoint sources print a one-line trust warning on first load — a plugin is arbitrary Python code, so review third-party code before use (see the security model).

Full Usage

audio-visualizer input.mp3 [options]
audio-visualizer ./directory/ --batch [options]

All options can also be set via environment variables (e.g., AUDIO_VISUALIZER_RESOLUTION=1920x1080) or in the config file (see Configuration File).

The tables below are generated from the live CLI parser by scripts/generate_flag_reference.py - run python scripts/generate_flag_reference.py after changing any flag (CI runs --check and fails when the tables drift from the parser).

Positional arguments

Global options

[composite] Album Art Visualizer options

[meter] Beat Pulse options

[meter] Volume Meter options

[meter] Psychedelic Vectorscope options

[scope] Band Lissajous options

[spectrum] Classic Bars options

[spectrum] Circular Spectrum options

[spectrum] CQT Spectrum options

[spectrum] Peak-Hold Bars options

[spectrum] Mirrored Spectrum options

[spectrum] Showfreqs options

[spectrum] Spectrogram Waterfall options

[spectrum] Color Spectrum options

[waveform] Oscilloscope options

[waveform] Gradient Waveform options

Creating a New Visualizer Plugin

Scaffold a ready-to-edit plugin package (pyproject.toml with the audio-visualizer.plugins entry point, a template plugin module that doubles as the canonical minimal example, and a label-discipline test):

audio-visualizer new-plugin my-viz [--dir ~/plugins/my-viz]
pip install -e ~/plugins/my-viz

From scratch:

1. Create a Python file with a class inheriting from VisualizerPlugin in audio_visualizer/visualizers/base.py
2. Define a metadata (PluginMetadata) and an options list (PluginOption) — the CLI flags are auto-generated from this schema
3. Implement build_filter()
4. Choose how it gets discovered:

   • Built-in: place the file in the visualizers/ directory

   • Installed: audio-visualizer --install-plugin my_plugin.py

   • External path: --plugin-path or AUDIO_VISUALIZER_PLUGIN_PATH

   • Distribution: ship a package registering an entry point, e.g.

     [project.entry-points."audio-visualizer.plugins"]
     myviz = "mymypkg.plugin:MyVizPlugin"
     

All discovery paths apply the same schema validation and isolation: a broken plugin is skipped with a warning instead of crashing the run.

The build_filter() contract

build_filter() returns the filter graph for your visualization. It must produce the plugin's main output labeled with get_output_label() (default: viz) and must not produce the final [out] label — the base class composes that (overlaying your output on the background input, or relabeling it) and then applies post-processing such as the border.

def build_filter(self, width, height, fps, options, audio_index=0, video_index=1, **kwargs):
    return f"[{audio_index}:a] showspectrum=size={width}x{height}[viz]"

For multi-layer visualizations, return a dict mapping output names to filter segments (the first key is the main output):

def build_filter(self, width, height, fps, options, **kwargs):
    return {
        "viz": "[0:a] showvolume=w=1280:h=720[viz]",
        "spectrum": "[0:a] showspectrum=size=1280x720[spectrum]",
    }

Plugins that need custom inputs (image files, no background, etc.) override get_inputs(), and plugins with a custom final composition override compose_final_filter(). See albumart.py, vectorscope.py, and radial.py for examples.

For the full guide — plugin anatomy, a worked example (the built-in peakbars), packaging a plugin as an entry-point distribution, and testing — see docs/PLUGIN_DEVELOPMENT.md.

Project Structure

audio_visualizer/
├── __init__.py
├── __main__.py              # Main application entry point
└── visualizers/
    ├── __init__.py
    ├── base.py              # Base plugin class
    ├── registry.py          # Plugin registry system
    ├── spectrum.py          # Spectrum visualizer
    ├── waveform.py          # Waveform visualizer
    ├── bars.py              # Bars visualizer
    ├── radial.py            # Radial visualizer
    ├── spectrogram.py       # Spectrogram visualizer
    ├── vectorscope.py       # Vectorscope visualizer
    └── albumart.py          # Album art visualizer

License

MIT License