Upscaling

mold supports image upscaling using Real-ESRGAN super-resolution models. Upscale generated images or existing photos to 2x or 4x their original resolution with AI-enhanced detail.

RRDB models use float32 scalar arithmetic for their half-precision residuals and activations, matching upstream Torch. This precision correction can change pixels produced by earlier mold versions.

When cuDNN is selected, the first convolution also stays on cuDNN, avoiding a rounding difference from the small-input im2col shortcut that accumulates through the network.

Cancellation is checked between RRDB blocks and tiles, and before returning the encoded image. A GPU convolution already in progress must finish before the next cancellation check.

Quick Start

# Upscale an image with the default model (Real-ESRGAN x4+)
mold upscale photo.png

# Specify a model
mold upscale photo.png -m real-esrgan-anime-v3:fp32

# Upscale and save to a specific path
mold upscale photo.png -o photo_hires.png

# Pipe from generation to upscale
mold run "a cat" | mold upscale -

Available Models

Model	Architecture	Scale	Size	Speed	Quality
real-esrgan-x4plus:fp16	RRDBNet (23 blocks)	4x	32 MB	Medium	Best
real-esrgan-x4plus:fp32	RRDBNet (23 blocks)	4x	64 MB	Medium	Best
real-esrgan-x2plus:fp16	RRDBNet (23 blocks)	2x	32 MB	Medium	Best
real-esrgan-x2plus:fp32	RRDBNet (23 blocks)	2x	64 MB	Medium	Best
real-esrgan-x4plus-anime:fp16	RRDBNet (6 blocks)	4x	8.5 MB	Fast	Great (anime)
real-esrgan-x4plus-anime:fp32	RRDBNet (6 blocks)	4x	17 MB	Fast	Great (anime)
real-esrgan-anime-v3:fp32	SRVGGNetCompact	4x	2.4 MB	Fastest	Good (anime)

These seven are the whole upscaler catalog; see Upscalers for sources, licenses, and per-file detail.

Choosing a Model

• Photos and realistic images: real-esrgan-x4plus:fp16; the full 23-block RRDBNet produces the sharpest detail recovery on photographs, textures, and AI-generated photorealistic output. Use fp32 only if you see precision artifacts on Metal.
• Anime, illustrations, and flat art: real-esrgan-x4plus-anime:fp16; trained on anime data, preserves clean lines and flat color regions without adding unwanted texture. Lighter than x4plus (6 blocks vs 23) so it's faster too.
• Batch processing or quick previews: real-esrgan-anime-v3:fp32; the SRVGGNetCompact architecture is ~3x faster than RRDBNet and only 2.4 MB. Quality is lower but adequate for bulk upscaling or when speed matters more than fine detail.
• Subtle 2x enhancement: real-esrgan-x2plus:fp16 when 4x magnification is too aggressive. Good for upscaling already high-res images (e.g. 1024px → 2048px) where you want sharpening without extreme enlargement.

CLI Reference

mold upscale <IMAGE> [OPTIONS]

Arguments:
  <IMAGE>  Input image file path (or - for stdin)

Options:
  -m, --model <MODEL>      Upscaler model (see below for the resolved default)
  -o, --output <PATH>      Output file path [default: <input>_upscaled.<ext>]
      --format <FORMAT>     Output format: png or jpeg [default: png]
      --tile-size <N>       Tile size for tiled inference (0 to disable) [default: 512]
      --host <URL>          Server URL override
      --local               Skip server, run inference locally
      --preview             Display the upscaled image inline in the terminal

--model has no fixed default. Mold resolves it in three steps: MOLD_UPSCALE_MODEL if it is set, otherwise the first already-downloaded upscaler in manifest order, and only then real-esrgan-x4plus:fp16. On a machine that has only real-esrgan-anime-v3:fp32 installed, that is what runs.

Tiled Inference

Large images are automatically split into overlapping tiles for memory-efficient processing. The default tile size is 512 pixels with 32 pixels of overlap. Tiles are blended using linear gradient weights to eliminate visible seams.

# Custom tile size (smaller = less VRAM, slower)
mold upscale large_photo.png --tile-size 256

# Disable tiling (process entire image at once: needs more VRAM)
mold upscale small_image.png --tile-size 0

Memory Requirements

Upscaler models are lightweight compared to diffusion models:

• RRDBNet (x4plus): ~32-64 MB model + ~200 MB activations per 512x512 tile
• SRVGGNetCompact: ~2-5 MB model + ~50 MB activations per 512x512 tile

With the default 512px tiling, any GPU with 1 GB+ VRAM can upscale images of any size.

Post-Generation Upscaling

The --upscale flag on mold run upscales images immediately after generation:

mold run "a cat" \
  --upscale real-esrgan-x4plus:fp16

This will generate at the model's native resolution (e.g. 1024x1024) and then upscale it (to 4096x4096 at 4x). Both files are retained in the gallery with -original and -upscaled suffixes. Reusing either entry restores the native 1024x1024 generation canvas and keeps the selected upscaler enabled. If post-generation upscaling fails, Mold keeps the successful original as a single gallery artifact instead of failing the entire generation.

Piping

mold upscale is fully pipe-compatible:

# Generate and upscale in a pipeline
mold run "a sunset" | mold upscale - | viu -

# Read from stdin, write to file
cat photo.png | mold upscale - -o upscaled.png

# Chain with other tools
mold upscale photo.png | convert - -resize 50% final.png

Server API

When a mold server is running, the upscale command uses the server for inference:

# Server handles the upscaling
MOLD_HOST=http://gpu-server:7680 mold upscale photo.png

# Direct API call
curl -X POST http://localhost:7680/api/upscale \
  -H "Content-Type: application/json" \
  -d '{"model": "real-esrgan-x4plus:fp16", "image": "<base64>"}'

The web, desktop, and mobile Library surfaces expose the same operation from both the tile context menu and full-media/info view. Existing images publish a new Library image through POST /api/gallery/upscale; upscaler weights download automatically on first use.

For video generation, the same Advanced upscaler picker publishes the original clip first and then queues a durable Framewise job. It continues without the UI remaining open and can be paused, resumed, or cancelled. See Framewise video upscale for media limits.

Environment Variables

Variable	Default	Description
MOLD_UPSCALE_MODEL	real-esrgan-x4plus:fp16	Default upscaler model
MOLD_UPSCALE_TILE_SIZE	512	Default tile size

Framewise video upscale shells out to ffmpeg and ffprobe. Release recipes that bundle those binaries pin their paths at build time through the MOLD_BUNDLED_FFMPEG and MOLD_BUNDLED_FFPROBE compile-time variables; a build without them uses the tools found on PATH, and a host with neither reports Framewise as unavailable.