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 presetanimate- Create an animation from a presetapply- Apply an effect preset to an existing imagemashup- Blend multiple images togethermagic-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 (includingrandom) 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 fileNunito-VariableFont_wght.ttfin$NOISEMAKER_DIR/fonts, or in~/.noisemaker/fontswhenNOISEMAKER_DIRis 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 applyINPUT_FILENAME- Path to input image (.png or .jpg)
Preset Discovery:
--help-presets- List available effect presets (includingrandom) 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 fileNunito-VariableFont_wght.ttfin$NOISEMAKER_DIR/fonts, or in~/.noisemaker/fontswhenNOISEMAKER_DIRis 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 noisemultires- Multi-resolution noisevoronoi- Voronoi cell patternsdla- Diffusion-limited aggregationfractal-smoke- Fractal smoke patternsacid- Psychedelic patternstimeworms- Animated worm-like patterns
Common effect presets include:
bloom- Glow/bloom effectglitchin-out- Digital glitch artifactsvignette-dark- Dark vignettecrt- CRT screen simulationposterize- Color posterizationpixel-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-supersampleor--with-fxaafor better quality at the cost of render timeHigher
--frame-countvalues will increase animation render time
Output Formats:
Use
.pngfor lossless output (larger files)Use
.jpgfor smaller files with some quality lossAnimations are typically saved as
.mp4or.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/.stabilityOpenAI (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