4K Upscaling Workflow – Expert‑Level Guide with Matrix Testing

This repository contains a series of shell scripts (and one Python script) that automate our expert‑recommended 4K upscaling process. This workflow incorporates systematic matrix testing at key stages (deinterlacing, AI upscaling, final color grading) so you can experiment with multiple parameter sets on representative clips and choose the optimal settings for your project.

Our preferences are:

• No Wine or Crossover – Everything runs natively on macOS.
• CLI‑based tools preferred – For reproducibility and automation.
• Open source when quality is comparable – But we use closed‑source AI (Topaz Video AI) when it delivers significantly better results.
• Brew‑installable tools when possible.
• Flexibility in source selection (Blu‑ray vs. DVD) – Based on independent research and objective tests.
• Iterative testing (matrix of test clips) at each stage where the optimal settings aren’t obvious.

---

Pre-requisites

Before running the scripts, ensure that you have a Python environment already set up. Then install the required tools:

1. Install Homebrew (if not already installed):
   Visit brew.sh and follow the instructions.

2. Install the following tools via Homebrew:

   brew install ffmpeg mkvtoolnix vapoursynth python
   brew install vapoursynth-plugins
   brew install --cask makemkv
   brew install real-esrgan

3. Install Python packages:
   (Assuming you have a Python environment already.)

   pip3 install vapoursynth

4. Install Topaz Video AI
   Download and install from Topaz Labs.
   Ensure that the Topaz CLI command (topaz-video-ai) is available (refer to Topaz’s documentation for details).

---

Workflow Overview

The upscaling process is divided into six main steps. At each key stage, you can generate a matrix of test clips to optimize parameters.

Step 1: Research & Source Selection (Manual)

1. Research Online:
   • Use resources such as Blu‑ray.com Reviews, DVDBeaver, and forum discussions (AVSForum, Reddit’s r/dvdcollection or r/bluray).
2. Compare Samples:
   • Extract short clips from both Blu‑ray and DVD sources.
   • Evaluate color fidelity, noise, and detail.
3. Decide:
   • Choose the best source based on quality and reviews.

This step is manual and determines which extraction script to use in Step 2.

---

Step 2: Source Extraction

• For Blu‑ray Sources:
  Run:

  ./2_1_blu-ray_extraction.sh <disc_number> <output_directory>

  Preserves original quality, color grading, and bitrate.

• For DVD Sources:
  Run:

  ./2_2_dvd_extraction.sh <disc_number> <output_directory>

  DVDs are interlaced and will require deinterlacing later.

---

Step 3: Preprocessing (Deinterlacing & Cleanup)

3.1 Deinterlacing with VapourSynth (QTGMC)

• Automated Deinterlacing:
  Run:

  ./3_1_deinterlace.sh <input_mkv> <output_mp4>

  This uses the Python script 3_1_deinterlace.py with a default "Slower" preset.

• Matrix Testing for Deinterlacing:
  Run:

  ./3_2_deinterlace_matrix.sh <input_mkv> <output_directory>

  Generates 10–15-second test clips using different QTGMC presets (e.g., Faster, Medium, Slower). Manually review the clips and choose the best setting.

3.2 (Optional) Downscaling Blu‑ray Sources

• If the Blu‑ray source has undesirable artifacts (e.g., over‑sharpening), run:

  ./3_3_bluray_downscale.sh <input_mkv> <output_mkv>

---

Step 4: AI Upscaling to 4K UHD

4.1 Matrix Testing for AI Upscaling

Generate a matrix of test clips that vary not only in denoise, sharpen, and detail recovery parameters but also in the AI algorithm used (Iris, Artemis, and Proteus). Run:

./4_1_topaz_upscale_matrix.sh <input_video> <output_directory>

Review the test outputs (using a video player like mpv) and compare clarity, detail, and absence of artifacts. Choose the best combination of algorithm and settings.

4.2 Running Full Upscaling with Chosen Settings

After determining the optimal parameters, run:

./4_2_topaz_upscale.sh <input_video> <denoise> <sharpen> <detail> <output_video>

This applies your chosen settings to upscale the full video to 4K UHD.

4.3 Alternative Upscaling (Optional)

For a fully open‑source option, run:

./4_3_realesrgan_upscale.sh <input_video> <output_video>

Note: For live‑action footage, Topaz generally produces superior results.

---

Step 5: Final Color Grading & Compression

5.1 Matrix Testing for Final Grading

Generate test clips with different grading parameters:

./5_1_final_grading_matrix.sh <input_video> <output_directory>

Test variations in brightness, saturation, and unsharp filters to achieve the desired look.

5.2 Final Grading & Encoding

Once you have chosen the optimal grading parameters, run:

./5_2_final_grading.sh <input_video> <brightness> <saturation> <unsharp> <output_video>

This finalizes the color grading and encodes the video in H.265 (HEVC).

---

Step 6: Verification & Iterative Tuning

After running the final grading step, review the final output manually using your preferred video player (e.g., mpv). If issues are detected (such as AI artifacts, color shifts, or compression problems), adjust the parameters in the corresponding matrix-testing stage and re-run the affected step.

---

File List

1. 2_1_blu-ray_extraction.sh – Blu‑ray extraction using MakeMKV.
2. 2_2_dvd_extraction.sh – DVD extraction using MakeMKV.
3. 3_1_deinterlace.sh – Single deinterlacing run using VapourSynth (calls 3_1_deinterlace.py).
4. 3_1_deinterlace.py – Python script for VapourSynth deinterlacing.
5. 3_2_deinterlace_matrix.sh – Matrix testing for deinterlacing with different QTGMC presets.
6. 3_3_bluray_downscale.sh – Downscaling a Blu‑ray source if needed.
7. 4_1_topaz_upscale_matrix.sh – Matrix testing for Topaz Video AI settings (algorithm, denoise, sharpen, detail).
8. 4_2_topaz_upscale.sh – Full Topaz Video AI upscale with chosen parameters.
9. 4_3_realesrgan_upscale.sh – Alternative upscale using Real‑ESRGAN.
10. 5_1_final_grading_matrix.sh – Matrix testing for final color grading parameters.
11. 5_2_final_grading.sh – Final color grading and compression using FFmpeg.