Noisemaker CLI

The noisemaker command-line interface uses Composer Presets to generate procedural art, create animations, and apply effects to images.

Overview

The CLI includes five main commands:

  • generate - Create a single image from a preset

  • animate - Create an animation from a preset

  • apply - Apply an effect preset to an existing image

  • mashup - Blend multiple images together

  • magic-mashup - Create animated collages from directories of frames

Installation

The noisemaker command is part of the Noisemaker Python package. Install the package from a clone of the repository.

Use Python 3.11, 3.12 or 3.13. CI tests these three versions, and pyproject.toml sets requires-python = ">=3.11,<3.14". The Docker image uses Python 3.13.

To install the package, run these commands:

git clone https://github.com/noisefactorllc/noisemaker.git
cd noisemaker
python3.12 -m venv venv
source venv/bin/activate
pip install .

These commands use Python 3.12. For Python 3.11 or 3.13, change python3.12 to python3.11 or python3.13.

The pip install . command installs TensorFlow and the other dependencies. It also installs the noisemaker and mood commands. To make sure that the installation is correct, run noisemaker --help.

The animate and magic-mashup commands use ffmpeg to write MP4 and GIF files. pip does not install ffmpeg. Install ffmpeg with the package manager of your operating system. Make sure that the ffmpeg command is on your PATH. If ffmpeg is not on your PATH, these commands render all frames and then stop with an error.

The Docker image includes ffmpeg. To use the CLI in a container, see the Docker guide.

Quick Start

Generate a simple noise image:

noisemaker generate basic --filename output.png

Create an animation:

noisemaker animate acid --width 1024 --height 1024 --filename acid.mp4

Apply an effect to an existing image:

noisemaker apply glitchin-out input.jpg --filename glitched.png

Commands

generate

Generate a .png or .jpg image from a preset.

noisemaker generate PRESET_NAME [OPTIONS]

Required Arguments:

  • PRESET_NAME - Name of the preset to use (e.g., acid, voronoi, multires)

Preset Discovery:

  • --help-presets - List available generator presets (including random) and exit

  • --presets FILE - Path to a custom presets DSL file (allows user-defined presets)

Common Options:

  • --width INTEGER - Output width in pixels (default: 1024)

  • --height INTEGER - Output height in pixels (default: 1024)

  • --seed INTEGER - Random seed for reproducible results (random if omitted)

  • --filename FILE - Output filename (default: art.png)

  • --time FLOAT - Time value for Z axis (for 3D simplex noise, default: 0.0)

  • --speed FLOAT - Animation speed modifier (default: 0.25)

Quality Options:

  • --with-alpha - Include alpha channel in output

  • --with-supersample - Apply 2x supersample anti-aliasing

  • --with-fxaa - Apply FXAA anti-aliasing

AI Features (requires API keys):

  • --with-upscale - Apply 4x upscaling (requires stability.ai key)

  • --with-alt-text - Generate alt text description (requires OpenAI key)

Debug Options:

  • --debug-print - Print preset ancestry and settings to stdout

  • --debug-out FILE - Write preset ancestry and settings to file

Examples:

# Generate a basic image with custom dimensions
noisemaker generate multires --width 2048 --height 2048 --filename noise.png

# Generate with a specific seed for reproducibility
noisemaker generate acid --seed 12345 --filename acid.png

# Generate with anti-aliasing
noisemaker generate voronoi --with-fxaa --filename smooth.png

# Generate and apply AI upscaling
noisemaker generate fractal-smoke --with-upscale --filename hires.png

# Use a custom presets file
noisemaker generate my-preset --presets ~/my-presets.dsl --filename custom.png

animate

Generate an animation (MP4 or GIF) from a preset.

noisemaker animate PRESET_NAME [OPTIONS]

Required Arguments:

  • PRESET_NAME - Name of the preset to animate

Common Options:

  • --presets FILE - Path to a custom presets DSL file (allows user-defined presets)

  • --width INTEGER - Output width in pixels (default: 512)

  • --height INTEGER - Output height in pixels (default: 512)

  • --filename FILE - Output filename (default: animation.mp4)

  • --frame-count INTEGER - Number of frames to generate (default: 50)

  • --seed INTEGER - Random seed for reproducible results

  • --effect-preset NAME - Apply an additional effect preset to each frame

Advanced Options:

  • --save-frames PATH - Directory to save individual frames

  • --watermark TEXT - Add watermark text to frames. It needs the font file Nunito-VariableFont_wght.ttf in $NOISEMAKER_DIR/fonts, or in ~/.noisemaker/fonts when NOISEMAKER_DIR is not set.

  • --preview-filename PATH - Save a preview image

  • --target-duration FLOAT - Stretch MP4 output to the specified duration (seconds) using motion-compensated interpolation

Quality Options:

  • --with-supersample - Apply 2x supersample anti-aliasing

  • --with-fxaa - Apply FXAA anti-aliasing

  • --with-alt-text - Generate alt text description

Examples:

# Create a basic animation
noisemaker animate acid --frame-count 100 --filename acid-loop.mp4

# Create animation with effect applied
noisemaker animate voronoi --effect-preset glitchin-out --filename glitchy.mp4

# Save individual frames
mkdir -p frames
noisemaker animate multires --save-frames ./frames/ --filename anim.mp4

# Create animation with specific duration
noisemaker animate timeworms --target-duration 5.0 --filename timed.mp4

Strobe safety verdict

After rendering, animate prints a machine-readable strobe-warning: yes or strobe-warning: no line. Before adding any watermark, the command checks an 8×8 sampling grid against the WCAG general flash threshold. The yes verdict means that more than three flashes occur in a one-second window in either measurement:

  • The whole-frame mean

  • At least one quarter of the sampled grid cells

The command still writes the animation. Callers can use the verdict to add a photosensitivity warning or hold the output for review.

When --target-duration is set, the detector uses frame-count / target-duration as the playback rate. MP4 encoding applies the same requested timing. GIF encoding does not. For a verdict that reflects actual GIF playback, omit --target-duration.

apply

Apply an effect preset to an existing .png or .jpg image.

noisemaker apply EFFECT_PRESET INPUT_FILENAME [OPTIONS]

Required Arguments:

  • EFFECT_PRESET - Name of the effect preset to apply

  • INPUT_FILENAME - Path to input image (.png or .jpg)

Preset Discovery:

  • --help-presets - List available effect presets (including random) and exit

  • --presets FILE - Path to a custom presets DSL file (allows user-defined presets)

Options:

  • --filename FILE - Output filename (default: mangled.png)

  • --seed INTEGER - Random seed for stochastic effects (random if omitted)

  • --time FLOAT - Time value for animated effects (default: 0.0)

  • --speed FLOAT - Animation speed modifier (default: 0.25)

  • --no-resize - Don’t resize image (may break some presets)

  • --with-fxaa - Apply FXAA anti-aliasing

Examples:

# Apply a glitch effect
noisemaker apply glitchin-out photo.jpg --filename glitched.jpg

# Apply effect without resizing
noisemaker apply vignette-dark image.png --no-resize --filename output.png

# Apply with anti-aliasing
noisemaker apply bloom input.jpg --with-fxaa --filename bloomed.jpg

# Apply time-based effect
noisemaker apply worms photo.png --time 0.5 --filename warped.png

# Use a custom presets file
noisemaker apply my-effect photo.jpg --presets ~/my-presets.dsl --filename custom.png

mashup

Blend multiple images from a directory into a single composite.

noisemaker mashup [OPTIONS]

Required Options:

  • --input-dir DIRECTORY - Directory containing .png and/or .jpg images

Optional Arguments:

  • --filename FILE - Output filename (default: mashup.png)

  • --control-filename TEXT - Path to control image for blending

  • --time FLOAT - Time value for animation

  • --speed FLOAT - Animation speed

  • --seed INTEGER - Random seed

Examples:

# Blend all images in a directory
noisemaker mashup --input-dir ./images/ --filename combined.png

# Blend with control image
noisemaker mashup --input-dir ./photos/ --control-filename mask.png --filename blend.png

magic-mashup

Create an animated collage from multiple directories of image sequences.

noisemaker magic-mashup [OPTIONS]

Required Options:

  • --input-dir DIRECTORY - Directory containing subdirectories of frames

The input directory must contain at least four usable subdirectories. A usable subdirectory contains at least --frame-count PNG files. Shorter directories and non-PNG files do not count. The command exits with an error when fewer than four usable subdirectories remain.

Common Options:

  • --width INTEGER - Output width in pixels (default: 512)

  • --height INTEGER - Output height in pixels (default: 512)

  • --filename FILE - Output filename (default: mashup.mp4)

  • --frame-count INTEGER - Number of frames to generate (default: 50)

  • --seed INTEGER - Random seed

  • --effect-preset NAME - Apply an effect preset to the collage

Advanced Options:

  • --save-frames PATH - Directory to save individual frames

  • --watermark TEXT - Add watermark text. It needs the font file Nunito-VariableFont_wght.ttf in $NOISEMAKER_DIR/fonts, or in ~/.noisemaker/fonts when NOISEMAKER_DIR is not set.

  • --preview-filename PATH - Save a preview image

  • --target-duration FLOAT - Stretch MP4 output to the specified duration (seconds)

Like animate, this command prints a strobe-warning: yes|no verdict after it scores the rendered frames against the WCAG general flash threshold described above.

Examples:

# Create collage animation
noisemaker magic-mashup --input-dir ./sequences/ --filename collage.mp4

# Create collage with effect
noisemaker magic-mashup --input-dir ./frames/ --effect-preset vortex --filename magic.mp4

Working with Presets

Presets are predefined combinations of layers, effects, and settings. The share/dsl/presets.dsl file defines them.

Common generator presets include:

  • basic - Simple multi-octave noise

  • multires - Multi-resolution noise

  • voronoi - Voronoi cell patterns

  • dla - Diffusion-limited aggregation

  • fractal-smoke - Fractal smoke patterns

  • acid - Psychedelic patterns

  • timeworms - Animated worm-like patterns

Common effect presets include:

  • bloom - Glow/bloom effect

  • glitchin-out - Digital glitch artifacts

  • vignette-dark - Dark vignette

  • crt - CRT screen simulation

  • posterize - Color posterization

  • pixel-sort - Pixel sorting effect

Use random as the preset name to get a randomly selected preset.

Tips and Best Practices

Reproducibility:

Use --seed to generate reproducible results:

noisemaker generate acid --seed 42 --filename output1.png
noisemaker generate acid --seed 42 --filename output2.png
# output1.png and output2.png will be identical

Performance:

  • Start with smaller dimensions (512x512) for testing

  • Use --with-supersample or --with-fxaa for better quality at the cost of render time

  • Higher --frame-count values will increase animation render time

Output Formats:

  • Use .png for lossless output (larger files)

  • Use .jpg for smaller files with some quality loss

  • Animations are typically saved as .mp4 or .gif

Debugging:

Use --debug-print to see what settings a preset uses:

noisemaker generate acid --debug-print --filename test.png

API Keys

Some features require API keys. The CLI reads each key from a file in the Noisemaker directory:

  • Stability AI (for --with-upscale): $NOISEMAKER_DIR/.creds/.stability

  • OpenAI (for --with-alt-text): $NOISEMAKER_DIR/.creds/.openai

The Noisemaker directory is the value of the NOISEMAKER_DIR environment variable, or ~/.noisemaker when that variable is not set. Each file contains only the key.

mkdir -p ~/.noisemaker/.creds
echo "your-key-here" > ~/.noisemaker/.creds/.stability
echo "your-key-here" > ~/.noisemaker/.creds/.openai

Complete Command Reference

Usage: noisemaker [OPTIONS] COMMAND [ARGS]...

  Noisemaker - Let's make generative art with noise

  https://github.com/noisefactorllc/noisemaker

Options:
  -h, --help  Show this message and exit.

Commands:
  generate      Generate a .png or .jpg from preset
  apply         Apply an effect to a .png or .jpg image
  animate       Generate a .gif or .mp4 from preset
  magic-mashup  Animated collage from a directory of directories of frames
  mashup        Blend a directory of .png or .jpg images