\documentclass[a4paper,11pt,oneside]{report}

% =========================================================
% 1. OPTIMIZED PACKAGES & CORE CONFIG
% =========================================================
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
% Slightly wider margins for a modern tech doc feel, tall header space
\usepackage[margin=1.1in, top=1.3in, bottom=1.3in, headheight=30pt, footskip=40pt]{geometry}

% --- TYPOGRAPHY & MICRO-OPTIMIZATION ---
\usepackage[bitstream-charter]{mathdesign} % XCharter: A robust, professional serif for tech docs
\usepackage[scaled=0.92]{helvet} % Clean sans-serif for headers
\usepackage{courier} % Standardized monospaced font
\usepackage{microtype} % Essential for professional text justification and kerning
\usepackage{parskip}   % Modern paragraph spacing (no indent)
\linespread{1.05}      % Slightly open up line spacing for readability

\usepackage{xcolor}
\usepackage{graphicx}
\usepackage[export]{adjustbox} % Allows 'valign=m' for inline images in footer
\usepackage[explicit]{titlesec} % 'explicit' enables advanced header designs
\usepackage{fancyhdr}
\usepackage[most]{tcolorbox}    % 'most' loads advanced skins, breakable, etc.
\usepackage{fontawesome5}
\usepackage{booktabs}           % Professional table rules
\usepackage{tabularx}
\usepackage{multirow}
\usepackage{tikz}
\usetikzlibrary{shapes.geometric, arrows.meta, positioning, shadows.blur, calc, patterns, backgrounds}
\usepackage{float}
\usepackage[hidelinks, colorlinks=true, breaklinks=true]{hyperref}
\usepackage{enumitem}
\usepackage{listings}
\usepackage{menukeys}
\usepackage{colortbl}

% =========================================================
% 2. BRANDING COLOR PALETTE (MODERNIZED)
% =========================================================
% Core Brand Colors (Preserved)
\definecolor{WarlockBg}{HTML}{050505}       % Deep Black
\definecolor{WarlockPanel}{HTML}{1A1A1A}    % Widget Background
\definecolor{WarlockRed}{HTML}{D32F2F}      % Slightly richer Red for print/screen
\definecolor{WarlockGold}{HTML}{FFA000}     % Slightly warmer Gold
\definecolor{WarlockText}{HTML}{FAFAFA}     % Off-white for dark backgrounds
\definecolor{WarlockGray}{HTML}{757575}     % Neutral Gray
\definecolor{WarlockSuccess}{HTML}{388E3C}  % Professional Green
\definecolor{WarlockBlue}{HTML}{1976D2}     % Deep professional Blue

% Functional UI Colors for the Document
\definecolor{DocInk}{HTML}{212121}          % Soft black for main text (easier on eyes than pure black)
\definecolor{DocCodeBg}{HTML}{F5F7F9}       % Very light gray-blue for code blocks
\definecolor{DocHeaderBg}{HTML}{F0F2F5}     % Light background for header bars

% Hyperlinks Setup
\hypersetup{
    linkcolor=WarlockRed,
    filecolor=WarlockGold,
    urlcolor=WarlockBlue,
    citecolor=WarlockGray,
    pdftitle={Warlock-Studio v6.0 Master Manual},
    pdfauthor={Ivan-Ayub97}
}

% =========================================================
% 3. ADVANCED STYLING MACROS
% =========================================================

% --- HEADER & FOOTER ARCHITECTURE ---
\pagestyle{fancy}
\fancyhf{}
\renewcommand{\headrulewidth}{0pt} % Remove default ugly line
\renewcommand{\footrulewidth}{0pt}

% Modern Header with colored accent bar
\fancyhead[L]{%
    \begin{tikzpicture}[overlay, remember picture]%
        \fill[WarlockRed] (current page.north west) rectangle ($(current page.north east)+(0,-4pt)$);%
    \end{tikzpicture}%
    \sffamily\bfseries\footnotesize\textcolor{DocInk!70}{WARLOCK-STUDIO \textcolor{WarlockRed}{v5.1.1}}%
}
\fancyhead[R]{\sffamily\footnotesize\textcolor{WarlockGray}{MASTER OPERATING MANUAL}}

% Clean Technical Footer
\fancyfoot[L]{\sffamily\footnotesize\textcolor{WarlockGray}{\today}}
\fancyfoot[C]{%
    \begin{tikzpicture}%
        \node[circle, fill=WarlockRed, inner sep=2pt, text=white, font=\sffamily\bfseries\footnotesize] {\thepage};%
    \end{tikzpicture}%
}
% FOOTER MODIFIED HERE: Replaced Heart with miniature logo.png
\fancyfoot[R]{\sffamily\footnotesize Developed by \textbf{Ivan-Ayub97} \ \includegraphics[height=1.3em, keepaspectratio, valign=m]{logo.png}}


% --- CHAPTER & SECTION HEADERS (ARCHITECTURAL STYLE) ---

% Chapter Header: Solid, structured, modern block
\titleformat{\chapter}[block]
{\sffamily}
{}
{0pt}
{%
  \begin{tikzpicture}[remember picture, overlay]
    % Colored structural bar
    \fill[DocHeaderBg] ($(current page.north west)+ (0,-2cm)$) rectangle ($(current page.north east)+ (0,-5.5cm)$);
    % Red accent line
    \draw[WarlockRed, line width=3pt] ($(current page.north west)+ (1.1in,-5.5cm)$) -- ($(current page.north east)+ (-1.1in,-5.5cm)$);
  \end{tikzpicture}%
  \vspace{-1.5cm}
  \begin{flushleft}
    \begin{tikzpicture}
      \node[opacity=0.1, font=\sffamily\bfseries\fontsize{80}{80}\selectfont, color=WarlockGray, anchor=south west] at (-0.5,0.2) {\thechapter};
      \node[font=\sffamily\bfseries\huge\color{DocInk}, anchor=south west, align=left, inner sep=0] at (0,0.5) {\strut #1};
    \end{tikzpicture}
  \end{flushleft}
  \vspace{1cm}
}
\titlespacing{\chapter}{0pt}{0pt}{20pt}

% Section Header: Clean and prominent
\titleformat{\section}
  {\sffamily\Large\bfseries\color{WarlockRed}}
  {\thesection \ \ $\cdot$ \ \ }{0pt}{#1}

% Subsection Header: Technical
\titleformat{\subsection}
  {\sffamily\large\bfseries\color{DocInk}}
  {\thesubsection}{0.5em}{#1}

% Subsubsection Header: Subtle
\titleformat{\subsubsection}
  {\sffamily\normalsize\bfseries\color{WarlockGray}}
  {\thesubsubsection}{0.5em}{#1}

% --- MODERNIZED UI BOXES (CARDS) ---

% Base style for all UI cards - sleek, no heavy borders, subtle shadow
\tcbset{
    mkui_card/.style={
        enhanced,
        breakable,
        frame hidden, % No full border
        interior style={fill=white}, % White background by default
        boxrule=0pt,
        leftrule=5pt, % Thick left border only
        arc=3mm, % Softer corners
        shadow={0mm}{0mm}{0mm}{0pt}{black!5}, % Reset shadow
        fuzzy shadow={0mm}{-2mm}{3mm}{0.5mm}{black!15}, % Modern soft shadow
        fonttitle=\sffamily\bfseries,
        fontupper=\small,
        toptitle=4pt, bottomtitle=4pt, left=10pt, right=10pt, top=10pt, bottom=10pt,
        before skip=1.5em, after skip=1.5em,
        title label={#1 \quad}
    }
}

% Concept Box (Gold/Yellow)
\newtcolorbox{conceptbox}[1]{
    mkui_card={\faLightbulb},
    borderline west={5pt}{0pt}{WarlockGold},
    coltitle=WarlockGold!30!black,
    title={CONCEPT: #1},
    colbacktitle=WarlockGold!10
}

% Technical Deep Dive (Gray/Dark)
\newtcolorbox{techbox}[1]{
    mkui_card={\faCogs},
    borderline west={5pt}{0pt}{WarlockPanel},
    interior style={fill=WarlockPanel!5},
    coltitle=WarlockText,
    title={TECHNICAL DEEP DIVE: #1},
    colbacktitle=WarlockPanel
}

% Warning Box (Red)
\newtcolorbox{dangerbox}[1]{
    mkui_card={\faExclamationTriangle},
    borderline west={5pt}{0pt}{WarlockRed},
    coltitle=WarlockRed!30!black,
    title={CRITICAL WARNING: #1},
    colbacktitle=WarlockRed!10
}

% Scenario/Solution Box (Blue)
\newtcolorbox{scenariobox}[1]{
    mkui_card={\faStethoscope},
    borderline west={5pt}{0pt}{WarlockBlue},
    coltitle=WarlockBlue!30!black,
    title={SCENARIO: #1},
    colbacktitle=WarlockBlue!10
}

% Tip Box (Green)
\newtcolorbox{tipbox}[1]{
    mkui_card={\faInfoCircle},
    borderline west={5pt}{0pt}{WarlockSuccess},
    coltitle=WarlockSuccess!30!black,
    title={PRO TIP: #1},
    colbacktitle=WarlockSuccess!10
}

% --- LISTINGS & CODE ---
\lstset{
    basicstyle=\ttfamily\footnotesize\color{DocInk},
    backgroundcolor=\color{DocCodeBg},
    breaklines=true,
    frame=trbl, % full thin frame
    frameround=ffff, % rounded corners
    framesep=8pt,
    framerule=0.5pt,
    rulecolor=\color{WarlockGray!30},
    keywordstyle=\color{WarlockBlue}\bfseries,
    commentstyle=\color{WarlockSuccess}\itshape,
    stringstyle=\color{WarlockGold!80!black},
    numberstyle=\tiny\sffamily\color{WarlockGray!60},
    numbers=left,
    numbersep=10pt,
    captionpos=b,
    abovecaptionskip=10pt
}

% --- MODERN TIKZ DIAGRAM STYLES ---
\tikzset{
    % Base node style with gradient and soft shadow
    base_node/.style={
        rectangle, rounded corners=4pt, minimum width=3cm, minimum height=1.2cm,
        text centered, font=\sffamily\small, line width=0.8pt,
        blur shadow={shadow xshift=0pt, shadow yshift=-2pt, shadow blur radius=4pt, shadow opacity=20}
    },
    startstop/.style={
        base_node, draw=WarlockRed!80!black,
        top color=WarlockRed!10, bottom color=WarlockRed!5, text=DocInk
    },
    process/.style={
        base_node, draw=WarlockGray!80!black,
        top color=white, bottom color=DocHeaderBg, text=DocInk
    },
    decision/.style={
        diamond, aspect=2, minimum width=3.5cm, minimum height=1.5cm,
        text centered, font=\sffamily\small\bfseries, line width=0.8pt,
        draw=WarlockBlue!80!black, top color=WarlockBlue!10, bottom color=WarlockBlue!5, text=WarlockBlue!40!black,
        blur shadow={shadow xshift=0pt, shadow yshift=-2pt, shadow blur radius=4pt, shadow opacity=20}
    },
    % Modern arrow style
    arrow/.style={
        draw=WarlockGray!80, line width=1.2pt, -{Latex[length=3mm, width=2mm]}, rounded corners=5pt
    },
    line/.style={draw, -latex', thick, color=DocInk}
}

% --- LIST STYLES ---
\setlist[itemize,1]{label={\textcolor{WarlockRed}{\faAngleRight}}, leftmargin=1.5em, itemsep=0.4em}
\setlist[itemize,2]{label={\textcolor{WarlockGray}{\faCircle[small]}}, leftmargin=1.5em, itemsep=0.2em}
\setlist[enumerate,1]{label={\sffamily\bfseries\arabic*.}, font=\color{WarlockRed}, leftmargin=1.5em, itemsep=0.4em}


% =========================================================
% DOCUMENT CONTENT
% =========================================================

\begin{document}

% --- COVER PAGE ---
\begin{titlepage}
    \pagecolor{WarlockBg}
    \color{WarlockText}
    \begin{tikzpicture}[remember picture, overlay]
        % Subtle Technical Background Pattern
        \begin{scope}[opacity=0.05, WarlockGray]
             \draw[step=2cm, very thin] (current page.south west) grid (current page.north east);
             \foreach \x in {0,10,...,\paperwidth} \draw[line width=2pt] (\x,0) -- (\x,\paperheight);
        \end{scope}
        % Dynamic diagonal accents
        \draw[WarlockRed, line width=4pt, opacity=0.8] ($(current page.north west)+(2in,0)$) -- ($(current page.south west)+(0,4in)$);
        \draw[WarlockGold, line width=2pt, opacity=0.6] ($(current page.north west)+(2.5in,0)$) -- ($(current page.south west)+(0,3.5in)$);
    \end{tikzpicture}

    \begin{center}
        \vspace*{4cm}
        % Logo Area with Glow Effect - MODIFIED TO USE logo.png
        \begin{tikzpicture}
        % The glowing container circle
        \node[circle, minimum size=4cm, fill=WarlockPanel, blur shadow={shadow blur radius=15pt, shadow opacity=40, shadow color=WarlockRed}] (logo) at (0,0) {};
        % The actual image node inside the circle
        \node at (0,0) {\includegraphics[width=3cm, height=3cm, keepaspectratio]{logo.png}};
        \end{tikzpicture}

        \vspace{2cm}

        {\sffamily\bfseries\fontsize{36}{36}\selectfont WARLOCK-STUDIO} \\[0.5cm]
        {\sffamily\Large\textcolor{WarlockGray}{\textit{The Comprehensive AI Media Enhancement Suite}}} \\[1.5cm]

        {\sffamily\bfseries\fontsize{24}{30}\selectfont MASTER OPERATING MANUAL} \\[0.5cm]
        \begin{tcolorbox}[colback=WarlockRed, colframe=WarlockRed, width=4cm, arc=5mm, boxrule=0pt, halign=center]
            \sffamily\bfseries\textcolor{WarlockText}{Version 6.0}
        \end{tcolorbox}
        \vspace{2cm}

        \begin{tcolorbox}[mkui_card, interior style={fill=WarlockPanel}, borderline west={4pt}{0pt}{WarlockGold}, width=0.9\textwidth]
            \centering
            \sffamily\textcolor{WarlockGray}{
            Architecture \ $\cdot$ \ Workflows \ $\cdot$ \ Troubleshooting \ $\cdot$ \ Advanced Config}
        \end{tcolorbox}

        \vfill

        \begin{flushright}
            \sffamily\small
            \textbf{Author:} Ivan-Ayub97 \\
            \textcolor{WarlockGray}{Generated for Documentation Purposes} \\
            \today
        \end{flushright}

    \end{center}
\end{titlepage}
\pagecolor{white}
\color{DocInk}

% --- TABLE OF CONTENTS ---
{
  \hypersetup{linkcolor=DocInk}
  \sffamily
  \tableofcontents
}
\newpage

% =========================================================
% CHAPTER 1: THE CORE PHILOSOPHY
% =========================================================
\chapter{The Core Philosophy}

\section{What is Warlock-Studio?}
Warlock-Studio is not just an "app"; it is an \textbf{AI Orchestrator}.

In the world of AI, processing a single image or video involves dozens of complex steps: managing memory buffers, tiling large images to fit in VRAM, extracting frames, running neural network inference (ONNX), and re-encoding video streams.

Warlock-Studio automates this entire pipeline. It acts as a bridge between high-performance libraries (OpenCV, MoviePy, ONNX Runtime) and the user, providing a "Drag \& Drop" experience for industrial-grade tasks.

\section{Capabilities at a Glance}
\begin{itemize}
    \item \textbf{Upscaling:} Increasing resolution while adding detail (up to 8K+).
    \item \textbf{Restoration:} Removing noise (Denoising) and fixing broken faces (GFPGAN).
    \item \textbf{FluidFrames (Interpolation):} Generating new frames to make video smoother (30fps $\to$ 60fps).
    \item \textbf{Smart Rendering:}
    \begin{itemize}
        \item \textbf{Tiling Engine:} Processes images larger than your GPU memory.
        \item \textbf{Auto-Fallback:} Automatically switches to CPU encoding if GPU encoding fails.
        \item \textbf{Resume System:} Crashed during a 2-hour render? Warlock resumes from the exact frame.
    \end{itemize}
\end{itemize}

\section{System Requirements Matrix}
Strict adherence to these requirements ensures stability.

\begin{table}[h!]
\centering
\sffamily\small
\renewcommand{\arraystretch}{1.6}
\setlength{\tabcolsep}{12pt}
% Header row styling
\rowcolors{1}{DocHeaderBg}{white}
\begin{tabularx}{\textwidth}{l l X}
\toprule
\rowcolor{WarlockPanel} \textbf{\textcolor{WarlockGold}{Component}} & \textbf{\textcolor{WarlockText}{Minimum}} & \textbf{\textcolor{WarlockText}{Recommended}} \\
\midrule
\textbf{OS} & Windows 10 (64-bit) & Windows 11 (64-bit) \\
\textbf{CPU} & Quad-Core (i5/Ryzen 5) & 8-Core+ (i7/Ryzen 7) for fast encoding \\
\textbf{RAM} & 8 GB & \textbf{16 GB - 32 GB} (Crucial for 4K video) \\
\textbf{GPU} & Integrated (Vega/Intel HD) & \textbf{NVIDIA RTX 3060} (or equivalent) with 8GB+ VRAM \\
\textbf{Storage} & HDD (Slow) & \textbf{NVMe SSD} (Required for high-speed frame extraction) \\
\textbf{Libraries} & Visual C++ Redist. & Latest GPU Drivers \\
\bottomrule
\end{tabularx}
\caption{Hardware Compatibility Specification}
\end{table}

% =========================================================
% CHAPTER 2: ANATOMY OF THE INTERFACE
% =========================================================
\chapter{Anatomy of the Interface}

This chapter breaks down every pixel of the GUI. Warlock-Studio uses a \textbf{"Top-Down"} workflow design.

\section{1. The Input Manager (File Queue)}
Located on the left/top. It has two modes:

\subsection{A. The Drop Zone}
When empty, it shows a large "Drag \& Drop" area. It accepts:
\begin{itemize}
    \item \textbf{Images:} \texttt{.jpg, .png, .bmp, .tiff, .webp}
    \item \textbf{Videos:} \texttt{.mp4, .mkv, .avi, .mov, .webm}
\end{itemize}

\subsection{B. The Active Queue}
Once files are added, it transforms into a list. Each card displays:
\begin{itemize}
    \item \textbf{Thumbnail:} Visual verification of the file.
    \item \textbf{Meta-Info:} Resolution, Duration, FPS, File Size.
    \item \textbf{Projection:} A dynamic calculation showing:
    \[ \text{Input Res} \xrightarrow{\text{Input \%}} \text{AI Input} \xrightarrow{\text{Upscale}} \text{AI Output} \xrightarrow{\text{Output \%}} \text{Final Res} \]
\end{itemize}

\begin{tipbox}{Queue Secrets}
Use the \faArrowUp\ button to prioritize urgent files. Use the \faTimes\ button to remove files. Warlock processes files \textbf{sequentially} (top to bottom).
\end{tipbox}

\section{2. The Toolbar (Global Tools)}
Floating in the top right:
\begin{itemize}
    \item \textbf{\faBook\ Manual:} Opens this specific PDF document.
    \item \textbf{\faCog\ Preferences:} Opens the \texttt{warlock\_preferences} window (See Chapter 6).
\end{itemize}

\section{3. The Control Panel (The Brain)}
This is where you program the logic for the batch.

\subsection{Row 1: AI Model Selection}
The dropdown list contains categorized models. (See Chapter 3 for details).

\subsection{Row 2: Contextual Action (Blending vs. Frame Gen)}
This menu changes dynamically based on the AI Model selected.

\begin{itemize}
    \item \textbf{Scenario A: Upscaling Model Selected}
    \begin{itemize}
        \item \textbf{Menu:} \textit{AI Blending}
        \item \textbf{Function:} Mixes the original image with the AI result to recover natural texture/grain.
        \item \textbf{Values:} OFF (0\%), Low (30\%), Medium (50\%), High (70\%).
    \end{itemize}

    \item \textbf{Scenario B: RIFE (Interpolation) Selected}
    \begin{itemize}
        \item \textbf{Menu:} \textit{Frame Generation}
        \item \textbf{Function:} Determines how many new frames to create.
        \item \textbf{Values:} x2 (Double FPS), x4 (Quadruple FPS), Slowmotion (Increase frames but slow playback).
    \end{itemize}
\end{itemize}

\subsection{Row 3: AI Multithreading}
\textbf{Function:} Controls how many video frames are processed in parallel.
\begin{itemize}
    \item \textbf{OFF (1 Thread):} Safest. Essential for 4K video or low-VRAM GPUs.
    \item \textbf{2 Threads:} Sweet spot for 1080p video on mid-range GPUs.
    \item \textbf{4-8 Threads:} High VRAM usage. Only for RTX 3090/4090 processing SD content.
\end{itemize}

\subsection{Row 4: Resolution Orchestration}
\begin{itemize}
    \item \textbf{Input Resolution \%:} Downscales \textit{before} AI.
    \item \textbf{Output Resolution \%:} Downscales \textit{after} AI.
\end{itemize}

\subsection{Row 5: Hardware Limits (The Safety Valve)}
\begin{itemize}
    \item \textbf{GPU Selection:} Choose specific card or "Auto".
    \item \textbf{VRAM Limiter (GB):} \textbf{CRITICAL.} This defines the maximum tile size.
\end{itemize}

\section{4. The Integrated Console (The Voice)}
New in v5.1.1. It provides a live feed of the backend operations.
\begin{itemize}
    \item \textcolor{WarlockSuccess}{\textbf{[SUCCESS]}}: Task completed.
    \item \textcolor{WarlockBlue}{\textbf{[INFO]}}: Progress updates (e.g., "Extracting frames 45\%").
    \item \textcolor{WarlockRed}{\textbf{[ERROR]}}: Critical failures (e.g., "Out of Memory").
    \item \textbf{[FFMPEG]}: Raw encoding logs from the video engine.
\end{itemize}

\section{5. The Processing Chain Editor}
This module lets you build multi-step workflows. Each step runs sequentially; the output of a step becomes the input to the next step automatically.

\subsection{Adding Steps}
\begin{itemize}
    \item Click \textbf{Add Step}. Choose \textbf{Model Name} from the combobox. Values are auto-discovered from \texttt{AI-onnx/}.
    \item Configure \textbf{GPU}, \textbf{Input/Output Resize}, \textbf{Blending}, \textbf{VRAM Limit}, \textbf{Extension}, and \textbf{Video Codec}.
    \item Reorder with \textbf{Up/Down}. Disable a step with \textbf{Bypass} to skip it temporarily.
\end{itemize}

\subsection{Interpolation Steps (RIFE)}
\begin{itemize}
    \item Use \textbf{Frame Generation} to select \textit{x2, x4, x8} or \textit{Slowmotion} variants.
    \item Interpolation requires \textbf{video input}. If the current file is an image, the step is skipped and logged.
    \item Intermediate containers default to \texttt{.mp4} unless the last step targets a different format.
\end{itemize}

\subsection{Output Routing}
\begin{itemize}
    \item Intermediate results go to a temporary folder per step. The final step writes to the chosen output directory.
    \item Extensions and codecs are corrected automatically based on media type to prevent invalid outputs.
    \item Optional: keep extracted frames on the final step for inspection.
\end{itemize}

\subsection{Reliability \& Performance}
\begin{itemize}
    \item VRAM-aware tiling is applied per step to avoid memory errors on large inputs.
    \item Memory is cleaned between steps to maintain stability over long chains.
    \item Face restoration uses stable float32 precision with proper alpha handling.
\end{itemize}

% =========================================================
% CHAPTER 3: THE MODEL LIBRARY
% =========================================================
\chapter{The Model Library: A Field Guide}

Warlock-Studio includes a curated selection of ONNX models. Using the wrong model for the task is the \#1 cause of poor results.

\begin{table}[h!]
\centering
\sffamily\small
\renewcommand{\arraystretch}{1.4}
\setlength{\tabcolsep}{10pt}
\rowcolors{1}{DocHeaderBg}{white}
\begin{tabularx}{\textwidth}{l l X X}
\toprule
\rowcolor{WarlockPanel}
\textbf{\textcolor{WarlockGold}{Model}} &
\textbf{\textcolor{WarlockText}{Type}} &
\textbf{\textcolor{WarlockText}{BEST Use Case}} &
\textbf{\textcolor{WarlockText}{DO NOT Use When...}} \\
\midrule

\textbf{RealESR\_Animex4} & Upscale (x4) & \textbf{2D Animation, Cartoons, Line Art.} Removes compression artifacts perfectly. & Input is a real photograph. It will turn skin into "plastic" or "oil paint". \\

\textbf{RealESR\_Gx4} & Upscale (x4) & \textbf{General Purpose.} Good balance for art and clean photos. & Input is extremely noisy or grainy. \\

\textbf{BSRGANx4} & Upscale (x4) & \textbf{Real World Video.} Adds realistic texture. Handles blur and JPEG compression well. & You need a perfectly clean, noiseless image (it generates grain). \\

\textbf{BSRGANx2} & Upscale (x2) & Same as above, but faster. Ideal for 1080p $\to$ 4K. & Same as above. \\

\textbf{RealESRGANx4} & Upscale (x4) & \textbf{Text \& Logos.} Extremely sharp edges. & Input contains faces (might look over-sharpened). \\

\textbf{IRCNN\_M|Lx1} & Denoise (x1) & \textbf{Cleaning.} Removing noise before upscaling. & You want to increase resolution (it stays at x1). \\

\textbf{GFPGAN} & Restoration & \textbf{Faces.} Restores eyes/mouths in blurry photos. & Image has no faces, or faces are already high quality (it might alter identity). \\

\textbf{RIFE|RIFELite} & Interpolation & \textbf{Smoothing Video.} Increasing frame rate. & You want to increase resolution/sharpness. \\
\bottomrule
\end{tabularx}
\caption{Comprehensive Model Usage Matrix}
\end{table}

% =========================================================
% CHAPTER 4: ADVANCED CONCEPTS
% =========================================================
\chapter{Advanced Concepts (The Engine Room)}

\section{Tiling: How to Process 8K on a 2GB Card}

\begin{conceptbox}{What is Tiling?}
Neural networks require massive amounts of memory. Processing a 4K image in one go might require 12GB of VRAM.

\textbf{The Solution:} Warlock-Studio chops the image into smaller squares (Tiles), processes each square individually, and stitches them back together seamlessly.

The \textbf{GPU VRAM (GB)} setting controls the size of these squares.
\begin{itemize}
    \item \textbf{High Setting (e.g., 8GB):} Large tiles. Fewer tiles to process. Faster speed.
    \item \textbf{Low Setting (e.g., 2GB):} Small tiles. More tiles to process. Slower, but **impossible to crash**.
\end{itemize}
\end{conceptbox}

\section{Auto-Fallback Encoding}
Video encoding is prone to driver failures. Warlock-Studio implements a "Self-Healing" mechanism.

\begin{itemize}
    \item \textbf{Attempt 1:} The user selects a Hardware Encoder (e.g., \texttt{h264\_nvenc}).
    \item \textbf{Failure:} The GPU driver crashes or is busy.
    \item \textbf{Detection:} Warlock detects the non-zero exit code from FFmpeg.
    \item \textbf{Attempt 2 (Auto):} The system immediately switches to \texttt{libx264} (CPU Encoder).
    \item \textbf{Result:} The video renders successfully (albeit slower), preventing a "wasted night" of rendering.
\end{itemize}

% =========================================================
% CHAPTER 5: WORKFLOWS
% =========================================================
\chapter{Workflows}

\section{FluidFrames (RIFE Integration)}
RIFE (Real-Time Intermediate Flow Estimation) works differently from Upscalers.

\begin{figure}[H]
\centering
\begin{tikzpicture}[node distance=2cm, auto]
    \node (frame1) [startstop, width=2.8cm] {Frame 1};
    \node (frame2) [startstop, right of=frame1, xshift=5.5cm, width=2.8cm] {Frame 2};
    \node (ai) [process, below of=frame1, xshift=3.75cm, width=4cm] {\sffamily\bfseries RIFE AI Analysis};
    \node (newframe) [decision, below of=ai, yshift=-0.5cm] {Generate Frame 1.5};

    \draw [arrow] (frame1.south) -- (ai.north);
    \draw [arrow] (frame2.south) -- (ai.north);
    \draw [arrow] (ai.south) -- (newframe.north);

    % Modern dashed indicator
    \draw [arrow, dashed, draw=WarlockBlue, line width=1.5pt] (newframe.east) -- ++(2,0) node[right, text width=2.5cm, align=left, font=\sffamily\small\color{WarlockBlue}] {Inserted seamlessly between 1 \& 2};
\end{tikzpicture}
\caption{RIFE Logic: Creating frames from thin air}
\end{figure}

\section{The Video Upscaling Pipeline}

\begin{center}
\begin{tikzpicture}[node distance=1.8cm, every node/.style={font=\sffamily\footnotesize}]
    % Define a local style for this specific chart
    \tikzset{pipe_arrow/.style={arrow, draw=WarlockGray!60, line width=2pt}}

    \node (start) [startstop] {User Clicks Start};
    \node (check) [decision, below of=start, yshift=-0.2cm] {Is Video?};

    % Image Path
    \node (img) [process, right of=check, xshift=4.5cm] {Process Image (Single Step)};

    % Video Path
    \node (extract) [process, below of=check, yshift=-0.8cm] {Extract Frames (FFmpeg)};

    % Main Loop Container
    \begin{scope}[on background layer]
        \node[rectangle, draw=WarlockGold!50, dashed, line width=2pt, rounded corners=10pt, fill=WarlockGold!5, fit=(extract)(resize)(model)(blend)(save), label={[anchor=north west, font=\sffamily\bfseries\color{WarlockGold!80!black}, xshift=10pt, yshift=-5pt]Processing Loop}] (loopbox) {};
    \end{scope}

    \node (loop) [process, below of=extract] {Loop Through Frames};
    \node (resize) [process, below of=loop] {Resize Input \%};
    \node (model) [process, below of=resize, top color=WarlockRed!5, bottom color=WarlockRed!15, draw=WarlockRed!50] {\bfseries AI Inference (Tiling)};
    \node (blend) [process, below of=model] {Blend / Post-Process};
    \node (save) [process, below of=blend] {Save Temp Frame};

    \node (checkdone) [decision, right of=save, xshift=4.5cm] {More Frames?};
    \node (encode) [process, below of=save, yshift=-1cm] {Encode Video (FFmpeg)};
    \node (done) [startstop, below of=encode] {Task Complete};

    % Connections
    \draw [pipe_arrow] (start) -- (check);
    \draw [pipe_arrow] (check) -- node[above] {\textbf{No}} (img);
    \draw [pipe_arrow] (check) -- node[right] {\textbf{Yes}} (extract);
    \draw [pipe_arrow] (extract) -- (loop);
    \draw [pipe_arrow] (loop) -- (resize);
    \draw [pipe_arrow] (resize) -- (model);
    \draw [pipe_arrow] (model) -- (blend);
    \draw [pipe_arrow] (blend) -- (save);
    \draw [pipe_arrow] (save) -- (checkdone);
    % Loop back arrow
    \draw [pipe_arrow, rounded corners=15pt] (checkdone.north) |- node[near start, right] {\textbf{Yes}} ($(loop.east)+(0.5,0)$) -- (loop.east);
    \draw [pipe_arrow] (checkdone.south) |- node[near start, right] {\textbf{No}} (encode.east);
    \draw [pipe_arrow] (encode) -- (done);
\end{tikzpicture}
\end{center}

% =========================================================
% CHAPTER 6: PREFERENCES (THE GEAR MENU)
% =========================================================
\chapter{Preferences \& Configuration}

The \texttt{warlock\_preferences.py} module handles persistent settings.

\section{General Tab}
\begin{itemize}
    \item \textbf{App Theme:} Switch between Dark, Light, or System.
    \item \textbf{UI Scaling:} Essential for 4K monitors (Set to 125\%).
    \item \textbf{Window Opacity:} Aesthetic transparency.
    \item \textbf{Auto-Close:} Shuts down the app after the queue finishes.
\end{itemize}

\section{Performance Tab}
\begin{itemize}
    \item \textbf{ONNX Provider:}
    \begin{itemize}
        \item \textit{Auto:} Recommended.
        \item \textit{CUDA:} Forces NVIDIA acceleration.
        \item \textit{DirectML:} Forces AMD/Intel acceleration.
        \item \textit{CPU:} Debug mode (Slow).
    \end{itemize}
    \item \textbf{Process Priority:} Increases the Windows priority of the FFmpeg subprocess.
\end{itemize}

\section{Integrations Tab}
Allows manual definition of paths for \texttt{ffmpeg.exe} and \texttt{exiftool.exe} if the auto-detection in \texttt{Assets/} fails.

\section{Logs \& Maintenance}
\begin{itemize}
    \item \textbf{Clean Temp Files:} A "Panic Button" to clear disk space. Deletes all \texttt{*.tmp}, \texttt{*.checkpoint}, and temporary frame folders.
    \item \textbf{Export Debug Zip:} Compresses all logs and config files into a ZIP to share with the developer for bug reporting.
\end{itemize}

% =========================================================
% CHAPTER 7: TROUBLESHOOTING GUIDE (THE MECHANIC)
% =========================================================
\chapter{Troubleshooting \& Solutions}

This section covers 90\% of user reports.

\section{Crash Scenarios}

\begin{scenariobox}{Crash: "Out of Memory" / "Allocation Failed"}
\textbf{Symptoms:} The app closes instantly or the console turns red with memory errors.
\textbf{Cause:} The AI is trying to create a Tile larger than available VRAM.
\textbf{Solution:}
\begin{enumerate}
    \item Set \textbf{AI Multithreading} to \textbf{OFF}.
    \item Lower \textbf{GPU VRAM (GB)} setting (e.g., from 4 to 2).
    \item Reduce \textbf{Input Resolution \%} (e.g., to 75\%).
\end{enumerate}
\end{scenariobox}

\begin{scenariobox}{Crash: "Timeout Detection Recovery (TDR)"}
\textbf{Symptoms:} The screen flickers, goes black for a second, and the app reports an error.
\textbf{Cause:} Windows reset the GPU driver because a single tile took too long to process.
\textbf{Solution:} Lower the \textbf{GPU VRAM (GB)} setting drastically (e.g., to 1 or 2). Smaller tiles process faster, preventing the timeout.
\end{scenariobox}

\begin{scenariobox}{Stuck: "Extracting Frames..."}
\textbf{Symptoms:} The progress bar doesn't move for minutes.
\textbf{Cause:} The input video is huge (e.g., a 2-hour movie) or stored on a slow HDD.
\textbf{Solution:} Be patient. Check the "Temp" folder in your file explorer to see if PNG files are being created. Move source files to an SSD.
\end{scenariobox}

\section{Quality Issues}

\begin{scenariobox}{Result: "Oily" or "Plastic" Faces}
\textbf{Cause:} Using \texttt{RealESR\_Animex4} on real photos.
\textbf{Solution:} Switch to \texttt{RealESR\_Gx4} or \texttt{BSRGANx4}.
\end{scenariobox}

\begin{scenariobox}{Result: Weird artifacts in Video Motion}
\textbf{Cause:} RIFE Interpolation struggles with scene cuts (sudden changes in camera).
\textbf{Solution:} This is a limitation of current AI tech. Try \texttt{RIFE\_Lite} which is sometimes less aggressive.
\end{scenariobox}

\section{The Checkpoint System}
\begin{dangerbox}{Do NOT delete Temp Files!}
If Warlock-Studio crashes at frame 1500 of 2000:
\begin{enumerate}
    \item Re-open the app.
    \item Load the \textbf{exact same video}.
    \item Choose the \textbf{exact same settings}.
    \item Click Start.
\end{enumerate}
The system will detect the existing frames and verify the \texttt{.checkpoint} file. It will output: \texttt{[INFO] Resuming video upscaling...} and start at frame 1501.
\end{dangerbox}

% =========================================================
% CHAPTER 8: CREDITS
% =========================================================
\chapter*{Credits}
\addcontentsline{toc}{chapter}{Credits}

\begin{minipage}{0.55\textwidth}
    \sffamily
    \section*{Development Team}
    \textbf{Lead Developer:} Ivan-Ayub97 \\

    \section*{Core Technologies Stack}
    We stand on the shoulders of giants.
    \begin{itemize}
        \item \textbf{UI Framework:} \textit{CustomTkinter} (TomSchimansky)
        \item \textbf{AI Inference Engine:} \textit{ONNX Runtime} (Microsoft)
        \item \textbf{Computer Vision:} \textit{OpenCV}
        \item \textbf{Video Processing Backbone:} \textit{FFmpeg}
    \end{itemize}
\end{minipage}
\hfill
\begin{minipage}{0.4\textwidth}
    \begin{tcolorbox}[mkui_card, interior style={fill=DocHeaderBg}, borderline west={4pt}{0pt}{WarlockGray}]
        \centering
        \color{DocInk}
        \sffamily
        \faCodeBranch \ \ \textbf{Open Source Philosophy} \\
        \vspace{0.5em}
        \footnotesize
        Licensed under MIT. \\
        Collaboration drives innovation.
    \end{tcolorbox}
\end{minipage}

\vfill
\begin{center}
    \sffamily
    \textcolor{WarlockGray!50}{\rule{0.7\linewidth}{1pt}} \\
    \vspace{0.8cm}
    \textcolor{WarlockGray}{\textit{Warlock-Studio v6.0 | Engineering Documentation}}
\end{center}

\end{document}
