go-upxcale

Portable AI-powered image and video upscaler with real-time web interface.

Demo videos in Indonesian: Part 1 | Part 2 | Part 3

Note

go-upxcale was made possible by using other things provided by the developers and/or companies mentioned in this guide. All credits and copyrights go to the respective owners.

Web interface with drag-and-drop upload and real-time progress tracking

---

Table of Contents

• Overview
• Features
• Requirements
• Quick Start
• Portable Distribution
• API Endpoints
• Configuration
• Development
• Architecture
• Limitations
• License

Overview

go-upxcale is a self-contained Go service that orchestrates external AI tools to upscale images and videos. It provides a clean web interface and HTTP API for processing media files using state-of-the-art AI models.

The service integrates:

• Real-ESRGAN (realesrgan-ncnn-vulkan) for general-purpose image super-resolution (2x, 3x, 4x)
• RealSR (realsr-ncnn-vulkan) for Real-World Super-Resolution (4x only)
• RIFE (rife-ncnn-vulkan) for frame interpolation and smooth motion
• FFmpeg for audio/frame extraction and re-encoding

Features

• Web-based drag-and-drop interface with real-time progress streaming
• Dual upscaling engines: Real-ESRGAN (2x/3x/4x) and RealSR (4x only)
• Support for 2x, 3x, and 4x image upscaling
• Video upscaling with audio preservation
• Frame interpolation for smoother video motion (2x, 4x FPS)
• Side-by-side before/after comparison viewer
• Automatic cleanup of temporary files
• RESTful API with Server-Sent Events for progress updates
• Single executable deployment with embedded web UI

Requirements

Runtime Dependencies

• Windows 10/11 (64-bit)
• Vulkan-compatible GPU (recommended for Real-ESRGAN and RIFE)
• 1GB+ free disk space for temporary processing files

External Tools

The following binaries must be available in the tools directory:

• ffmpeg.exe - Video processing and encoding
• ffprobe.exe - Media file analysis
• realesrgan-ncnn-vulkan.exe - AI upscaling engine (general-purpose)
• realsr-ncnn-vulkan.exe - Real-World Super-Resolution engine (4x only)
• rife-ncnn-vulkan.exe - Frame interpolation engine

AI Models

Real-ESRGAN, RealSR, and RIFE model files (.param and .bin) must be present in:

• tools/models/ for Real-ESRGAN models
• tools/models-DF2K/ for RealSR models (DF2K dataset)
• tools/models-DF2K_JPEG/ for RealSR models (JPEG artifacts)
• tools/rife-*/ for RIFE model variants

Quick Start

Using the Portable Package

Tip

The easiest way to get started is using the pre-packaged portable distribution.

1. Extract go-upxcale.zip to a folder of your choice
2. Double-click START.bat or run from PowerShell:

   .\START.bat

3. Open your browser to http://localhost:8080/ui/

The server will automatically use the bundled tools and create a work directory for temporary files.

Building from Source

Note

Building from source requires Go 1.20 or later.

1. Clone the repository and navigate to the project directory:

   cd go-upxcale

2. Copy reference models using the helper script:

   .\scripts\copy-models.ps1

3. Build the executable:

   go build -o go-upxcale.exe .\cmd\go-upxcale

4. Run the server:

   .\go-upxcale.exe -port 8080 -tools .\tools -workdir .\work

5. Access the web interface at http://localhost:8080/ui/

Portable Distribution

Creating a Portable Package

The project includes a PowerShell packaging script that creates a self-contained distribution with all required binaries and models.

Basic usage:

cd go-upxcale\scripts
.\package_portable.ps1 -OutDir "..\go-upxcale_portable"

Available options:

• -NoBuild - Skip building the Go binary (use existing executable)
• -FFmpegUrl <url> - Override FFmpeg download source URL
• -Force - Overwrite existing output directory

What gets included:

• Compiled go-upxcale.exe executable
• Web UI files (web/ directory)
• All required external tools (tools/ directory)
  • FFmpeg and FFprobe binaries
  • Real-ESRGAN executable and models
  • RealSR executable and models
  • RIFE executable and model variants
• START.bat launcher script
• Documentation (README.md)

Important

The packaging script extracts binaries from the references/ folder. If FFmpeg is not present locally, the script will attempt to download it automatically. Ensure you have internet connectivity for the first run.

Binary Sources

The packaging script locates binaries in the following order:

1. Real-ESRGAN: references/realesrgan-ncnn-vulkan-*/
2. RealSR: references/realsr-ncnn-vulkan-*/
3. RIFE: references/rife-ncnn-vulkan-*/
4. FFmpeg: references/ or auto-download from specified URL

Warning

When distributing the portable package, ensure compliance with all third-party licenses. The bundled tools (Real-ESRGAN, RealSR, RIFE, FFmpeg) have their own licensing terms.

API Endpoints

Health Check

GET /api/health

Returns server status.

Upscale Image

POST /api/upscale-image
Content-Type: multipart/form-data

Form fields:
  - file: image file (required)
  - engine: "realesrgan" or "realsr" (default: "realesrgan")
  - scale: 2, 3, or 4 for Real-ESRGAN; 4 only for RealSR (default: 2)
  - model: model name (optional)

Note: When using engine=realsr, only scale=4 is supported. The backend enforces this constraint.

Upscale Video

POST /api/upscale-video
Content-Type: multipart/form-data

Form fields:
  - file: video file (required)
  - engine: "realesrgan" or "realsr" (default: "realesrgan")
  - scale: 2, 3, or 4 for Real-ESRGAN; 4 only for RealSR (default: 2)
  - model: model name (optional)

Note: When using engine=realsr, only scale=4 is supported. The backend enforces this constraint.

Interpolate Video (RIFE)

POST /api/interpolate-video
Content-Type: multipart/form-data

Form fields:
  - file: video file (required)
  - multiplier: 2 or 4 (default: 2)
  - model: RIFE model variant (optional)

Job Status

GET /api/job/{jobId}

Returns job status, progress, and result URL.

Job Progress Stream

GET /api/job-stream/{jobId}

Server-Sent Events stream for real-time progress updates.

Configuration

Command-Line Flags

• -port - HTTP server port (default: 8080)
• -tools - Path to tools directory (default: ./tools)
• -workdir - Path to working directory for temporary files (default: ./work)

Example:

.\go-upxcale.exe -port 3000 -tools C:\AI-Tools -workdir D:\temp\upscale

Environment Variables

None currently supported. Configuration is via command-line flags only.

Development

Project Structure

go-upxcale/
├── cmd/
│   └── go-upxcale/          # Main entry point
├── internal/
│   ├── api/                 # HTTP server and handlers
│   └── orchestrator/        # External tool orchestration
├── web/                     # Static web UI files
│   ├── index.html
│   ├── bcfs-style.css
│   └── global-style.css
├── scripts/                 # Build and packaging scripts
└── tools/                   # External binaries and models

Running Tests

go test ./...

Code Style

This project follows standard Go formatting conventions. Run go fmt before committing:

go fmt ./...

Architecture

Orchestration Pattern

go-upxcale uses an orchestrator pattern to manage external tool execution:

1. Job Creation - HTTP handler creates a unique job ID and directory
2. File Upload - Input file is saved to job directory
3. Processing - Orchestrator spawns external tools with appropriate arguments
4. Progress Streaming - Real-time updates via Server-Sent Events
5. Cleanup - Empty job folders older than 10 minutes are automatically removed

Note

The cleanup mechanism only removes empty folders that are at least 10 minutes old. This prevents accidental deletion of folders from active processing jobs.

Video Processing Pipeline

Upscaling workflow:

1. Extract video frames using FFmpeg
2. Upscale each frame with Real-ESRGAN or RealSR (depending on selected engine)
3. Re-encode frames to video with FFmpeg
4. Merge original audio track

Interpolation workflow:

1. Extract video frames using FFmpeg
2. Generate intermediate frames with RIFE
3. Re-encode frames to video at higher FPS
4. Merge original audio track

Automatic Cleanup

The server performs automatic cleanup of abandoned job folders:

• Scans the work directory when any processing job starts
• Identifies empty folders matching the job-* pattern
• Only deletes folders that are both empty AND older than 10 minutes
• Prevents race conditions with active jobs

Important

The 10-minute age threshold ensures that temporary folders created during active video processing are not mistakenly deleted.

Limitations

Current Constraints

• Windows-only - Relies on Windows-specific binaries (cross-platform support planned)
• No authentication - API endpoints are unprotected (add reverse proxy with auth for production)
• Single-user - Designed for local/personal use, not multi-tenant scenarios
• Memory-intensive - Large videos may require significant RAM for frame processing
• No job persistence - Job status is lost on server restart

Known Issues

• Progress updates may lag for very large videos
• Failed jobs may leave temporary files until next cleanup cycle
• No built-in rate limiting or queue management

Warning

This is a development prototype. Do not expose the API to the internet without adding authentication and input validation.

License

This project is provided as-is for personal and educational use.

Third-party components:

• Real-ESRGAN - BSD-3-Clause License
• RealSR - MIT License
• RIFE - MIT License
• FFmpeg - LGPL v2.1+ (or GPL v2+ depending on build configuration)
• v.recipes - Web interface design adapted with permission from v.recipes and customized for go-upxcale

Refer to the individual tool repositories for complete licensing information and redistribution terms.

---

Project Status: Prototype / Development

For issues and feature requests, refer to the project repository.