RetroStudio

RetroStudio is a non-destructive desktop studio for creating retro images, animated compositions, character art, demoscene-inspired graphics, and layered visual effects.

It is built with Python and supports Windows and Linux.

Sample output

These animations were created with RetroStudio using layered media, procedural generators, and per-layer effects.

Demo 1	Demo 2
Demo 3	Demo 4
Demo 5	Image to Text

TV Static and Reception

Retrowave Drive

Highlights

• Layered image, animation, video, text, character-art, sprite, vector, solid, generator, and adjustment workflows
• Background, Content, and Foreground role bands
• Independent animation, timing, transforms, masks, and effects per layer
• Ten editable procedural Retro Generators
• Sixteen animated processing effects and five masks
• Full Code Page 437 and 48 additional built-in character sets
• Installed system fonts and user-loaded TTF/OTF/TTC fonts
• Dithering, built-in/custom palettes, and palette extraction
• Timeline, keyframes, markers, curves, work area, and loop controls
• Still-image, animated-image, PNG-sequence, video, SVG, text, and PDF export
• Responsive background processing with centered progress and cancellation
• Editable JSON project, generator, preset, shader, and processing-graph data
• Undo/Redo, recovery autosave, relinking, batch processing, and watch folders

See FEATURES.md for the complete implemented feature and effect catalog.

Layer-based effects

Every layer can have its own independent, reorderable effect and mask stacks. This includes ordinary media, text, sprites, vectors, generated layers such as Matrix Rain, and solid layers.

Groups can also have effects. Adjustment layers process the already-composited layers beneath them, while a Foreground FX adjustment layer is useful for scene-wide rain, snow, scanlines, glitches, color treatments, and similar overlays. TV Reception on a Foreground FX layer distorts the complete composite beneath it.

Effects are non-destructive and support:

• Enable/disable controls
• Reordering and removal
• Per-effect parameters
• Timeline keyframes
• Automatic animation and adjustable animation speed
• Negative animation speed for reverse motion
• JSON effect-stack presets
• Matching preview and export evaluation

Retro Generator library

Use + Retro Library to create an independently animated procedural layer. The built-in library currently contains:

Generator	Description
Matrix Rain	CP437/font-selectable fixed-grid glyph rain with trails, glow, bloom, and independently cycling drops
Perspective Grid / Tunnel	Moving neon floor, corridor, rectangular, or radial perspective grids
Sine Wave	Layered luminous sine ribbons with animated phase
Demoscene Text Scroller	Font-selectable horizontal text with sine-wave baseline motion
Palette Plasma	Multi-wave color plasma with animated hue cycling
Raster / Copper Bars	Amiga-inspired color bars with independent vertical motion
Warp Starfield	Deterministic looping stars projected from a configurable center
Rotozoomer	Infinite rotating and pulsing checker texture
TV Static	Looping white noise, monochrome/color snow, scanline interference, and static bursts
Retrowave Drive	Forward-moving neon road, striped sun, and animated wireframe terrain

Every generator includes a Transparent Background toggle so lower layers can remain visible. Plasma maps wave intensity to alpha, Rotozoomer clears its Color B checker field, and Retrowave Drive removes its opaque sky, road, and ground fills while retaining configured wireframe artwork. The other generators remove their solid backdrop while retaining their generated artwork.

Generator manifests are editable JSON files loaded from built-in, user, project, and compatible plugin Library folders. Older custom manifests that use a supported built-in renderer receive the transparency option automatically.

The implemented effects catalog is documented in FEATURES.md.

Processing effects

The current processing-effect stack contains:

• Glow
• Chromatic Aberration
• Color Adjustment
• Gaussian Blur
• Pixelate
• Scanlines
• TV Reception
• Rain Overlay
• Snow Overlay
• Row Glitch
• JPEG Glitch
• Bitmap Posterize
• Sine Modulation
• Halftone
• CMYK Halftone
• Declarative Shader

Bundled declarative shader recipes provide CRT and VHS treatments without executing arbitrary shader code. Detailed explanations and suggested uses for every effect are available in FEATURES.md.

Character art and Code Page 437

Character Art mode maps image luminance to font glyphs and supports:

• Complete Code Page 437, including classic DOS graphical glyphs
• ASCII, blocks, Braille, box drawing, symbols, scripts, and density ramps
• Forty-nine built-in character sets in total
• Custom glyph strings
• Installed Windows/Linux fonts
• Loaded TTF, OTF, and TTC files, including DOS extended-character fonts
• Automatic glyph-density measurement
• Configurable cells, offsets, depth, colors, luminance range, and background
• Transparent backgrounds and UTF-8 text export

Composition and animation

RetroStudio composites RGBA layers from bottom to top using Normal, Multiply, Screen, or Add blending. Layers and recursively nested groups have independent opacity, position, scale, rotation, visibility, export inclusion, locking, effects, masks, and animation.

Composition Settings provides exact canvas dimensions and a linked 1–800% scale slider. Resize all layers with canvas scales the complete layout and its transform keyframes, while canvas-sized generators rerender directly at the new resolution.

The timeline includes:

• Frame-snapped playback and stepping
• Layer active ranges
• Source offset and playback speed
• Once, Loop, and Ping-Pong modes
• Forward and reverse playback
• Markers and work-area limits
• Draggable keyframes
• Hold, Linear, and Ease interpolation
• Numeric animation curves

Supported input and output

Input

• Still images supported by Pillow
• Animated GIF, APNG, and WebP
• Video through ffmpeg and ffprobe
• Sprite sheets
• SVG
• TTF, OTF, and TTC fonts
• Editable .retroproject projects
• Generator, shader, effect/mask preset, palette, and processing-graph JSON

Output

• PNG and JPEG
• Animated GIF, APNG, and WebP
• Numbered PNG sequences
• Silent H.264 MP4 and VP9 WebM through ffmpeg
• UTF-8 character-art text
• Crisp traced SVG
• Path Editing SVG with individually editable horizontal runs
• Flattened PDF at a selected DPI

Export respects layer and group Export switches, masks, effects, timing, animation, work area, and composition order.

Requirements

• Windows or Linux
• Python 3.11 or newer
• NumPy 2.0 or newer
• Pillow 10.0 or newer
• PyQt6 6.7 or newer
• Optional: ffmpeg and ffprobe on PATH for video input/output

macOS is not currently a supported target.

Installation

From the project root, create and activate a virtual environment.

Windows PowerShell

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Linux

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

The editable installation commands above read pyproject.toml and install the required packages automatically. To install only the runtime dependencies for running directly from the source folder, use:

python -m pip install -r requirements.txt

The requirements file installs NumPy, Pillow, and PyQt6. Video support still requires the separate ffmpeg and ffprobe system programs.

The launchers do not install dependencies automatically.

Running RetroStudio

Windows

Double-click RetroStudio.bat or run:

.\RetroStudio.bat

Linux

sh ./retrostudio.sh

With the package installed and the environment active, either platform can also run:

retrostudio

The root launchers prefer the local .venv and otherwise look for an available system Python interpreter.

Quick start

1. Open an image with File → Open Image… or add a backdrop with + Background.
2. Add normal content with + Image, + Text, or another layer button.
3. Add Matrix Rain, Perspective Tunnel, Plasma, or another procedural layer with + Retro Library.
4. Enable Transparent Background on generators that should reveal lower layers.
5. Select any layer and add processing effects from Effects / Masks.
6. Add a Foreground FX layer for scene-wide rain, snow, or scanlines.
7. Press Play, adjust the timeline, and add keyframes where needed.
8. Save the editable .retroproject.
9. Export a still image, animation, PNG sequence, or video.

See TUTORIAL.md for a guided layered example.

Command-line tools

Installing the package provides retrostudio-cli:

retrostudio-cli convert input.png output.png --palette PICO-8
retrostudio-cli batch input_folder output_folder --recursive
retrostudio-cli watch input_folder output_folder
retrostudio-cli trace-svg input.png output.svg --threshold 128
retrostudio-cli trace-svg input.png editable-paths.svg --path-editing
retrostudio-cli character-text input.png output.txt --character-set "Code Page 437"

Project data and safety

• Source media is referenced and never destructively modified.
• Projects are readable .retroproject JSON documents.
• Dirty projects receive a separate recovery autosave.
• Missing media can be relinked.
• Long operations run on background workers.
• A centered progress dialog communicates foreground work and cancellation.
• Exports use adjacent staging and atomic replacement where applicable.
• Declarative generator and shader files do not execute arbitrary code.
• Automation scripts should only be used when their source is trusted.

Development

Install the optional development dependencies:

python -m pip install -e ".[dev]"

The repository retains automated regression tests:

python -m unittest discover -s tests -v

Owner-run visual and workflow validation is documented in MANUAL_TEST_CHECKLIST.md. Packaging instructions are in RELEASE.md.

Documentation

Document	Purpose
FEATURES.md	Complete generator, effect, mask, and application feature catalog
USER_MANUAL.md	Full end-user workflows and troubleshooting
TUTORIAL.md	Short layered-composition walkthrough
REFERENCE.md	Compact technical reference
LIBRARY.md	Generator manifest format and library locations
MANUAL_TEST_CHECKLIST.md	Windows/Linux owner validation
SCRIPTING.md	Automation API
PLUGIN_API.md	Plugin manifest API
RELEASE.md	Packaging and release verification
SAMPLES.md	Included sample project
BENCHMARKS.md	Owner-run performance checks

Project status

RetroStudio is under active development. The current implementation targets Windows and Linux and uses a deterministic NumPy/Pillow CPU renderer. Optional GPU backends are an architectural extension point rather than a required dependency.

The application icon is supplied as a transparent PNG for the running PyQt application and as a nine-resolution ICO for packaged Windows executables.

License

RetroStudio is released under the MIT License.

Copyright (c) 2026 non-npc. Distributions and substantial portions of the software must retain the copyright and license notices.