UltraFrame — The Ultimate Upscaling CLI

Turn low‑res images and videos into crisp, high‑quality outputs using Real‑ESRGAN/NCNN Vulkan — with a smart, user‑friendly CLI.

• Node.js 18+
• Windows/macOS/Linux
• FFmpeg & FFprobe bundled (static builds)
• Real‑ESRGAN binary auto‑downloaded on install

Features

• Smart quality targeting with --quality (e.g., 720p, 1080p, 4k, 8k)
• Automatic scale computation and exact target dimension matching
• Profile‑aware model selection:
  • -p animation: realesr-animevideov3-x2/x3/x4 based on scale
  • -p standard: realesrgan-x4plus
• Flexible resizing with --fit: contain (default), cover, stretch, none
  • --pad-color for background (supports transparent for PNG)
• Video audio preserved by default; control with --audio
• FPS preserved by default; override with --fps or keep source
• Clean, informative CLI UX and helpful error boxes

Install

Prerequisites

First, ensure you have Node.js (v18 or higher) installed on your system.

Global Installation

You can install the CLI globally in one of two ways:

Option 1: Install from local project

# After cloning the repository
npm install -g .

This command needs to be run from the root of the project. It will build the TypeScript code and link the ultraframe command to your system.

Option 2: Install from npm registry (when published)

npm install -g ultraframe

After installation, you can use the ultraframe command from anywhere in your terminal.

Run without global install (local build)

node dist/cli.js <input> <output> [options]

Usage

ultraframe <input> <output> [options]

• <input>: Image or video file
• <output>: Output file path (PNG/JPG/WEBP/MP4, etc.)

Options

• -s, --scale <number>: Upscale factor (2, 3, or 4)
• -p, --profile <type>: Processing profile: standard | animation (default: standard)
• -q, --quality <level>: Target output quality (e.g., 720p, 1080p, 1440p, 2k, 4k, 8k)
• --fit <mode>: Resize strategy (contain | cover | stretch | none). Default: contain
• --pad-color <color>: Pad color (e.g., black, white, #000000, transparent)
• --fps <fps>: Video FPS. Number (e.g., 24, 30, 60) or source to keep original (default)
• --audio <bool>: Include audio (true/false). Default: true

Environment

• ULTRAFRAME_FIT: default fit mode (used if --fit not provided)

Quality mapping

When you pass --quality, UltraFrame computes the required scale to reach or exceed the target resolution, then applies a final resize to match the target exactly using ffmpeg.

WxH by label:

• 144p → 256×144
• 240p → 426×240
• 360p (SD) → 640×360
• 480p (SD) → 854×480
• 720p (HD) → 1280×720
• 1080p (Full HD) → 1920×1080
• 1440p (2K/QHD) → 2560×1440
• 2160p (4K/UHD) → 3840×2160
• 4320p (8K/UHD) → 7680×4320

Note: Max native upscaling factor is 4x. If your target needs more, UltraFrame uses the maximum available factor and then resizes/pads to reach the exact target dimensions.

Fit modes

• contain (default): preserve aspect ratio, pad the rest (use --pad-color)
• cover: preserve aspect ratio, crop overflow to fill the target (no black bars)
• stretch: force to exact target dimensions (can distort)
• none: skip final resize/pad (outputs whatever the upscaler produces)

Images write the final resize to a temporary file and atomically replace the output (ffmpeg can’t overwrite in place).

Transparent pads (PNG):

ultraframe in.jpg out.png -q 1080p --fit contain --pad-color transparent

Examples

Images

• Smart Full HD:

ultraframe input.jpg out.png -q 1080p -p standard

• 4K anime with cover (no black bars):

ultraframe input.jpg out.png -q 4k -p animation --fit cover

• Keep exact upscaler output (no final resize):

ultraframe input.jpg out.png -s 4 -p standard --fit none

Videos

• Full HD with no black bars (cover), keep source audio and FPS (default):

ultraframe video.mp4 out.mp4 -q 1080p -p standard --fit cover

• 4K anime + force 60 FPS + include audio:

ultraframe video.mp4 out_4k.mp4 -q 4k -p animation --fit cover --fps 60 --audio true

• Keep original FPS explicitly:

ultraframe video.mp4 out.mp4 -q 1080p -p standard --fps source

• Mute output video:

ultraframe video.mp4 out_silent.mp4 -q 1080p -p standard --audio false

Models

• standard → realesrgan-x4plus
• animation → realesr-animevideov3-x2|x3|x4 (auto‑selected by scale)

Note: The standard model is 4x. With --quality, UltraFrame still reaches your exact WxH via the final resize step. For pure --scale runs and standard, a 4x pass is used.

Requirements & Performance

• Node.js 18+
• Vulkan‑capable GPU recommended for best performance
• Binaries (Real‑ESRGAN, FFmpeg, FFprobe) are auto‑provisioned; no manual setup

Tips:

• Use SSD for temp directories (videos)
• Close background GPU workloads
• Prefer cover over contain to avoid heavy pads for very mismatched aspect ratios

Troubleshooting

• Input file not found
  • Check the path/filename; try absolute paths
• Unsupported file extension
  • Images: .png, .jpg, .jpeg, .webp
  • Videos: .mp4, .mkv, .mov, .webm, .flv
• FFmpeg cannot edit existing files in place
  • Handled automatically for images via temporary output replacement
• Permission errors on output directory
  • Try a different folder or run your terminal with elevated privileges
• Missing binaries
  • npm install fetches the NCNN Vulkan binary and static ffmpeg/ffprobe

If you run into an issue, share your command, OS, Node version, and a brief log excerpt.

Development

• Build: npm run build
• Dev (TypeScript): npm run dev
• Postinstall fetches the upscaler binary: scripts/download-binary.cjs

Project layout (excerpt):

src/
  cli.ts               # CLI entry
  lib/
    realesr.ts         # Real-ESRGAN helpers
    video.ts           # Video pipeline helpers
  utils/paths.ts       # Binary paths (realesrgan, ffmpeg, ffprobe)

License

MIT