SlidyReplay

Generates MP4 videos of sliding puzzle replays from slidysim replay URLs, input files, or manual solution strings.

Installation

pip install slidyreplay
pip install torch --index-url https://download.pytorch.org/whl/cu124   # optional GPU

Make sure that you have ffmpeg installed in your system.

On Windows you can use latest release with ffmpeg already bundled in (no CUDA support)

Quick Start

GUI

slidyreplay

Launches a fully functional GUI with nearly all custom options, backed by the same CLI interface.

CLI

slidyreplay --solution R2D2L2U2 --size 3x3 --tps 10          # auto-named in replays/
slidyreplay -u "https://slidysim.github.io/?replay=..."     # auto-named in replays/
slidyreplay -f input.txt                                     # auto-named in replays/
slidyreplay -b solutions.txt -q 2160                         # batch, auto-named in replays/
slidyreplay --solution R2D2L2U2 --time 30 -c 28 --slow-render -o small.mp4
slidyreplay --solution R2D2L2U2 --no-layout --no-numbers -o clean.mp4
slidyreplay --solution R2D2L2U2 --upscale --encoder libx265 -o high_quality.mp4
slidyreplay --solution R2D2L2U2 -q 720 -s 2.0 -o fast.mp4
slidyreplay --solution R2D2L2U2 --no-header                 # hide timer bar, keep stats panel
slidyreplay --solution R2D2L2U2 --no-details                # hide stats panel, keep timer
slidyreplay --solution R2D2L2U2 --dynamic-md                # show right-side MD timer
slidyreplay --solution R2D2L2U2 --no-header --no-details    # puzzle grid only (= --no-layout)
slidyreplay --solution R2D2L2U2 --saturation 0.5          # set both min/max saturation to 0.5
slidyreplay --solution R2D2L2U2 --saturation-min 0.3 --saturation-max 0.9  # gradient across tiles
slidyreplay --solution R2D2L2U2 --brightness-min 0.2 --brightness-max 0.8  # brightness gradient
slidyreplay --settings my_settings.json --solution R2D2L2U2   # load settings from JSON
slidyreplay --solution R2D2L2U2 --font-family Arial --font-bold --font-size 36  # custom tile font

slidyreplay --image --size 4x4                                 # solved puzzle image
slidyreplay --image --size 4x4 --scramble "4 1 2/7 8 3/6 5 0" # custom scramble image
slidyreplay --image --solution R2D2L2U2 --size 3x3            # scrambled + solved images
slidyreplay --image --size 5x5 --no-numbers --main-scheme rows
slidyreplay --image -f replay.txt --size 4x4 -o output.png    # explicit output path

CLI Reference

Cursor Dance

The --cursor-dance <path> option places a cursor image over the puzzle that moves from tile to tile along the blank's path. The cursor follows a smooth Bézier arc, arriving at each tile at the exact moment that tile moves (or starts animating if --animate-moves is set). The cursor always moves in time with the move timings (movetimes speed).

• The image is converted to RGBA — transparency is preserved.
• If no cursor file is provided, no cursor is rendered.
• The cursor scales proportionally to tile size (min 24px).
• In the GUI, use the CURSOR section to Browse... or Clear the cursor image.

Example

slidyreplay --solution R2D2L2U2 --size 3x3 --tps 10 --cursor-dance my_cursor.png -o replay.mp4

Settings Management

The GUI includes three settings controls at the bottom of the Settings panel:

• Reset to Defaults — resets all controls to their default values (render options, colors, sliders, etc.)
• Save Settings... — exports all current settings to a JSON file. Output folder is excluded.
• Load Settings... — imports settings from a previously saved JSON file and applies them to the GUI.

CLI --settings

Use a settings file saved from the GUI directly on the command line:

slidyreplay --settings my_settings.json --solution R2D2L2U2 --size 4x4

Explicit CLI flags override values from the settings file, so you can use a base config and tweak individual parameters:

slidyreplay --settings base.json --solution R2D2L2U2 --fps 120 --hue-start 180

JSON format

Settings files use a simple flat JSON structure. Example:

{
  "quality": "1080p",
  "fps": 60,
  "compression": 18,
  "speed_factor": "1",
  "use_gpu": true,
  "slow_render": false,
  "upscale": false,
  "encoder": "Auto",
  "main_scheme": "fringe",
  "force_main": false,
  "no_layout": false,
  "no_border": false,
  "no_secondary_border": false,
  "no_grid_bars": false,
  "no_numbers": false,
  "no_header": false,
  "no_details": false,
  "dynamic_md": false,
  "cycles_detection": false,
  "adjust_height": false,
  "animate_moves": false,
  "hue_start": 0.0,
  "hue_end": 330.0,
  "saturation_min": 78,
  "saturation_max": 78,
  "brightness_min": 60,
  "brightness_max": 60,
  "grid1_color": "C86767",
  "grid2_color": "8DB3FF",
  "tile_bg_color": "454545",
  "font_family": "",
  "font_bold": false,
  "font_size_override": 0
}

Saturation and brightness values are stored at GUI scale (0–100), they are automatically converted to the 0–1 range when used via --settings.

Encoder Options

Available encoders are auto-detected in priority order — the first supported encoder is used:

• --compression (-c) maps to the encoder's quality flag with an offset to normalize across encoders (the value 10–40 is translated per-encoder).
• --slow-render switches to a slower preset: p7 for NVENC, quality for AMF, veryslow for QSV, slow for libx264/libx265. This typically reduces file size by ~33% at the cost of ~33% longer encode time.
• --encoder overrides auto-detection to force a specific encoder. Useful when multiple GPUs are present or you want software encoding on a GPU-capable system.

Debug logging is disabled by default. Pass --log (-l) to enable:

slidyreplay -l                               # GUI with logging
slidyreplay --solution R2D2L2U2 -l          # CLI with logging

Logs are written to logs/debug_YYYYMMDD_HHMMSS.log.

Image Mode

The --image flag renders single-frame PNG images rather than videos. Images always render the puzzle grid only.

Behavior by input

GUI "Render Image" button

Located in the Override section of the GUI (next to the Scramble and Movetimes fields). Behavior:

• With a queue item selected: generates two images (scrambled + solved with analysis) using current color/display settings, saved to the output folder and listed in the Generated Replays panel
• No queue item selected: generates a single image from the override fields — custom scramble if entered, otherwise a solved puzzle of the given size

Output Format

By default, files are saved to the replays/ folder with auto-generated names following the pattern: <size>_<total_time>_<moves>_<tps>_movetimes.mp4

Example: 8x8_23.564_707_30.003_movetimes_5.mp4

Use -o <path> to save to a custom location with a specific filename.

GPU Acceleration

The GUI shows the GPU name when available, or "Not available — install CUDA" when PyTorch/CUDA is missing. GPU is enabled by default when available and falls back to CPU automatically.

Benchmarks (NVIDIA GeForce GTX 1660 SUPER)

Settings: quality=720, 60 FPS.

Run your own benchmarks with python benchmark.py. "Unique" = number of distinct puzzle states rendered (video may duplicate frames via frame mapping).

Installing GPU support

1. Check your NVIDIA driver supports CUDA 12.x:

   nvidia-smi
   

   Look for "CUDA Version" in the output (top-right).

2. Install PyTorch with CUDA:

   pip install torch --index-url https://download.pytorch.org/whl/cu124
   

3. Verify:

   python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"
   

Benchmark script

python benchmark.py                 # full benchmark run
python benchmark.py --gpu-only      # GPU only (both layout and no-layout)
python benchmark.py --cpu-only      # CPU only
python benchmark.py --layout        # layout only (both GPU and CPU)
python benchmark.py --no-layout     # no-layout only
python benchmark.py --quality-test  # test 10×10 at all quality presets

All outputs saved to logs/<timestamp>/ folder.

Build (Windows)

Builds a standalone dist\slidyreplay.exe (CPU-only):

build_no_gpu.bat

Requires ffmpeg\ffmpeg.exe.

For GPU acceleration, use the repository directly (python main.py) instead of the standalone build.

Dependencies

• Python 3.9+
• ttkbootstrap, Pillow, tabulate, numpy, psutil (optional — for RAM logging with --log)
• torch (optional — for GPU acceleration)
• ffmpeg — must be installed and available in your PATH (or same folder as the script)

Tested on Windows 11 with Python 3.13.5.