% ---------------------------------------------------------------------------------------
%   CONFIGURACIÓN DEL DOCUMENTO
% ---------------------------------------------------------------------------------------
% \documentclass define el tipo de documento y las opciones base.
% - 11pt: Tamaño de fuente base. Un buen equilibrio entre densidad y legibilidad.
% - a4paper: Define el tamaño del papel estándar internacional.
\documentclass[11pt, a4paper]{article}


% %%% --- IMPORTACIÓN DE PAQUETES --- %%%
% Los paquetes añaden nuevas funcionalidades a LaTeX.

% --- Paquetes Esenciales ---
\usepackage[utf8]{inputenc}             % Permite escribir caracteres UTF-8 (acentos, ñ) directamente.
\usepackage[T1]{fontenc}                % Codificación de fuentes moderna para una correcta visualización y copiado de PDF.
\usepackage[spanish,es-noshorthands]{babel} % Soporte para el idioma español. La opción 'es-noshorthands' es
                                            % CRÍTICA para evitar conflictos con otros paquetes.

% --- Configuración de Página y Diseño ---
\usepackage{geometry}                   % Para configurar los márgenes y el diseño de la página.
\usepackage{graphicx}                   % Para incluir imágenes (\includegraphics).
\usepackage{fancyhdr}                   % Para personalizar encabezados y pies de página.
\usepackage{xcolor}                     % Para usar colores por nombre o código (HTML, RGB, etc.).
\usepackage{float}                      % Proporciona el especificador [H] para "flotar aquí exactamente".

% --- Tipografía y Estilo de Texto ---
% \usepackage{firasans}                 % EJEMPLO: Fuente Sans-Serif moderna (mantener comentada si no está instalada).
\usepackage{textcomp}                   % Provee símbolos adicionales como el de copyright.
\usepackage{fontawesome5}               % Permite usar iconos de Font Awesome (ej: \faInfoCircle).

% --- Tablas, Listas y Cajas ---
\usepackage{booktabs}                   % Para crear tablas de aspecto profesional (\toprule, \midrule, \bottomrule).
\usepackage{longtable}                  % Para tablas que pueden ocupar varias páginas.
\usepackage{tabularx}                   % Para tablas con columnas de ancho flexible que ocupan todo el ancho del texto.
\usepackage{array}                      % Herramientas avanzadas para columnas en tablas.
\usepackage{enumitem}                   % Para un control avanzado sobre el formato de las listas (itemize, enumerate).
\usepackage{tcolorbox}                  % Para crear cajas de texto coloreadas y personalizables.
\usepackage{titlesec}                   % Para personalizar el formato de los títulos de sección (\section, \subsection).
\usepackage{titletoc}                   % Control sobre la tabla de contenidos.

% --- Utilidades y Enlaces ---
\usepackage{hyperref}                   % Para crear hipervínculos dentro del documento y a URLs externas.
                                        % Es una buena práctica cargarlo al final.


% %%% --- CONFIGURACIÓN DE GEOMETRÍA DE LA PÁGINA --- %%%
% Se definen los márgenes y espacios para el encabezado/pie de página.
\geometry{
  a4paper,          % Tamaño de papel
  margin=2.5cm,     % Margen uniforme para todos los lados
  headheight=15pt,  % Altura reservada para el encabezado
  footskip=30pt     % Distancia desde el final del texto hasta el pie de página
}


% %%% --- PALETA DE COLORES PERSONALIZADA --- %%%
% Se define una paleta de colores corporativa para mantener la consistencia visual.
% Se usa el modelo HTML para una fácil selección desde herramientas de diseño.
\definecolor{WarlockRed}{HTML}{C11919}
\definecolor{WarlockGold}{HTML}{ECD125}
\definecolor{WarlockDark}{HTML}{212325}
\definecolor{WarlockGray}{HTML}{333333}
\definecolor{WarlockLightGray}{HTML}{F5F5F5}
\definecolor{WarlockBlue}{HTML}{005A9B}
\definecolor{InfoBlue}{HTML}{E7F3FE}
\definecolor{WarnYellow}{HTML}{FFFBE6}
\definecolor{WarnBorder}{HTML}{FFBE0B}

% Se establece el color de texto por defecto para todo el documento.
\color{WarlockGray}


% %%% --- CONFIGURACIÓN DE HIPERVÍNCULOS --- %%%
% Se personaliza la apariencia de los enlaces generados por 'hyperref'.
\hypersetup{
    colorlinks=true,                  % Los enlaces serán coloreados en lugar de encajonados.
    linkcolor=WarlockRed,             % Color para enlaces internos (a secciones, figuras, etc.).
    filecolor=WarlockRed,             % Color para enlaces a archivos locales.
    urlcolor=WarlockRed,              % Color para enlaces a URLs externas.
    pdftitle={Warlock-Studio 4.0.1 Guía de Usuario \& Documentación Técnica}, % Metadatos del PDF.
    pdfauthor={Iván Eduardo Chavez Ayub (Revisado por IA)}             % Metadatos del PDF.
}


% %%% --- ESTILO DE TÍTULOS DE SECCIÓN --- %%%
% Se usa 'titlesec' para definir un estilo personalizado para las secciones.
% \titleformat{command}[forma]{formato}{etiqueta}{separación}{código-antes}
\titleformat{\section}
  {\normalfont\Large\bfseries\color{WarlockRed}} % Formato del título: Fuente normal, grande, negrita, color rojo.
  {\thesection.}                                 % Etiqueta: El número de la sección seguido de un punto.
  {1em}                                          % Separación horizontal entre la etiqueta y el título.
  {}                                             % Código a ejecutar antes del título (en este caso, ninguno).

\titleformat{\subsection}
  {\normalfont\large\bfseries\color{WarlockRed!70!black}} % Similar a \section, pero con un color más oscuro.
  {\thesubsection.}
  {1em}
  {}

% \titlespacing*{command}{espacio-izq}{espacio-arriba}{espacio-abajo}
\titlespacing*{\section}
  {0pt}                 % Espaciado a la izquierda del título.
  {3.5ex plus 1ex minus .2ex} % Espaciado vertical ANTES del título (con flexibilidad).
  {2.3ex plus .2ex}     % Espaciado vertical DESPUÉS del título (con flexibilidad).


% %%% --- DEFINICIÓN DE CAJAS DE TEXTO PERSONALIZADAS --- %%%
% Se usa 'tcolorbox' para crear entornos de "cajas" para información y advertencias.
\tcbuselibrary{skins, breakable} % Se cargan bibliotecas adicionales para más estilos.
                                          % 'breakable' permite que las cajas se dividan entre páginas.

% Caja para información general.
\newtcolorbox{infobox}{
    colback=InfoBlue,                       % Color de fondo de la caja.
    colframe=WarlockBlue,                   % Color del borde.
    fonttitle=\bfseries,                    % Fuente del título de la caja (negrita).
    coltitle=WarlockBlue,                   % Color del texto del título.
    title=\faInfoCircle\hspace{0.5em} Información, % Contenido del título (icono + texto).
    breakable,                              % Permite que la caja se parta entre páginas.
    pad at break=2mm,                       % Espaciado interno cuando la caja se rompe.
    enhanced,                               % Activa modos de renderizado avanzados.
    % drop shadow={WarlockGray!50!white}      % Efectos de sombra removidos por compatibilidad
}

% Caja para advertencias importantes.
\newtcolorbox{warnbox}{
    colback=WarnYellow,
    colframe=WarnBorder,
    fonttitle=\bfseries,
    coltitle=WarnBorder!80!black,
    title=\faExclamationTriangle\hspace{0.5em} Advertencia,
    breakable,
    pad at break=2mm,
    enhanced,
    % drop shadow={WarnBorder!50!white}    % Efectos de sombra removidos por compatibilidad
}

% Comando personalizado para formatear código en línea.
% \newcommand{nombre}[argumentos]{definición}
\newcommand{\inlinecode}[1]{\colorbox{WarlockLightGray}{\small\texttt{#1}}}


% %%% --- CONFIGURACIÓN DE ENCABEZADO Y PIE DE PÁGINA --- %%%
% Se usa 'fancyhdr' para controlar el contenido de encabezados y pies.
\pagestyle{fancy}
\fancyhf{} % Limpia todos los campos del encabezado y pie de página.

% \fancyhead[L/C/R]{...} define el contenido de la cabecera (Izquierda, Centro, Derecha).
\fancyhead[L]{\textit{Warlock-Studio 4.0.1}}
\fancyhead[R]{\leftmark} % \leftmark muestra el nombre de la sección actual.

% \fancyfoot[L/C/R]{...} define el contenido del pie de página.
\fancyfoot[L]{\includegraphics[height=0.8cm]{logo.png}} % Asume que 'logo.png' está en la misma carpeta.
\fancyfoot[C]{\thepage} % Muestra el número de página actual.
\fancyfoot[R]{\textcopyright~2025 Warlock-Studio}

% Se definen los grosores de las líneas de separación.
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0.4pt}

% Se redefine cómo se genera la marca de sección para que incluya el número.
\renewcommand{\sectionmark}[1]{\markboth{\thesection. #1}{}}


% =======================================================================================
%   INICIO DEL CUERPO DEL DOCUMENTO
% =======================================================================================
\begin{document}

% %%% --- PÁGINA DE TÍTULO --- %%%
% Se crea una portada impactante y profesional usando un 'tcolorbox' a toda página.
\begin{titlepage}
    \begin{tcolorbox}[
        %--- Estilo de la caja ---
        colback=WarlockDark,                    % Fondo oscuro.
        colframe=WarlockGold,                   % Borde dorado.
        sharp corners,                          % Esquinas rectas en lugar de redondeadas.
        boxrule=1.5pt,                          % Grosor del borde.
        %--- Alineación y Tamaño ---
        halign=center,                          % Alineación horizontal del contenido.
        valign=center,                          % Alineación vertical del contenido.
        height=\dimexpr\textheight-1cm\relax    % Altura de la caja (toda la altura del texto menos 1cm).
      ]
      %--- Contenido de la Portada ---
      \centering % Centra los elementos internos.

      \includegraphics[width=0.5\textwidth]{logo.png}\par % Logo.

      \vfill % Espacio flexible para empujar el contenido.

      \color{white} % Cambia el color del texto a blanco para contraste.

      {\Huge\bfseries Warlock-Studio\par}
      \vspace{0.7cm} % Espacio vertical fijo.
      {\Large -- Manual Técnico del Usuario y Documentación --\par}
      \vspace{0.2cm}
      {\Large Versión 4.0.1\par}

      \vfill % Otro espacio flexible.

      {\large Iván Eduardo Chavez Ayub\par}
      \href{https://github.com/Ivan-Ayub97}{\texttt{\color{WarlockGold}@Ivan-Ayub97 en GitHub}}\par % Enlace con estilo.

      \vspace{1.5cm}

      {\large \today\par} % Muestra la fecha de compilación.
    \end{tcolorbox}
    \thispagestyle{empty} % Oculta el encabezado y pie de página en la portada.
\end{titlepage}


% %%% --- RESUMEN Y TABLA DE CONTENIDOS --- %%%
\pagestyle{fancy} % Restaura el estilo de página 'fancy' después de la portada.

% El entorno 'abstract' crea un resumen del documento.
\begin{abstract}
\noindent % Evita la sangría en la primera línea.
Este documento es una guía técnica exhaustiva para Warlock-Studio 4.0.1. La información ha sido validada y enriquecida con un análisis profundo del código fuente para proporcionar detalles precisos sobre su nueva arquitectura de IA, una guía de optimización mejorada y un manual de solución de problemas robusto.
\end{abstract}

\newpage % Salto de página antes de la tabla de contenidos.
\tableofcontents % Genera la tabla de contenidos automáticamente.
\newpage % Salto de página después de la tabla de contenidos.


% %%% --- CUERPO PRINCIPAL DEL MANUAL --- %%%

% --- Sección 1: Introducción ---
\section{Introducción}
Warlock-Studio es una aplicación avanzada para la mejora y optimización de contenidos audiovisuales, que utiliza modelos IA de vanguardia para proporcionar resultados excepcionales. Su interfaz es intuitiva y accesible, adecuada tanto para principiantes como para usuarios avanzados.

La versión 4.0.1, introduce un sistema innovador de distribución de modelos IA que descarga automáticamente los componentes necesarios al iniciar, permitiendo una instalación más liviana con solo 300MB, en comparación con los previos 1.4GB. Esta versión mejora significativamente la arquitectura de IA y la estabilidad del software, fortaleciendo su presencia como una herramienta esencial para profesionales de la creación de contenido.

\textbf{Actualización v4.0.1:} El modelo SuperResolution-10 ha sido eliminado de esta versión debido a conflictos de compatibilidad. Se recomienda usar BSRGANx4 o RealESRGANx4 para necesidades de escalado extremo.

\subsection{Novedades en la Versión 4.0.1}
La última versión aporta las siguientes mejoras clave:
% Se usa 'itemize' para listas con viñetas. [leftmargin=*] alinea la lista con el margen del párrafo.
\begin{itemize}[leftmargin=*]
    \item \textbf{Soporte mejorado de modelos IA:} Nuevos modelos de última generación como Real-ESRGAN, RIFE y GFPGAN se han integrado para un superior escalado e interpolación.
    \item \textbf{Gestión avanzada de GPU:} Mejora en el manejo de errores para optimizar el rendimiento incluso en configuraciones de VRAM más bajas.
    \item \textbf{Gestión optimizada de memoria:} Incluye técnicas proactivas de optimización de memoria y mejor soporte de hilos para un procesamiento fluido.
    \item \textbf{Mejora en GUI y preferencias de usuario:} Una interfaz más amigable con opciones de configuración mejoradas y actualizaciones dinámicas en tiempo real.
    \item \textbf{Codificación de video mejorada:} Soporta múltiples codificadores acelerados por hardware de NVIDIA, AMD e Intel para un rendimiento óptimo.
    \item \textbf{Versión 4.0.1:} Se eliminó el modelo SuperResolution-10 debido a conflictos de compatibilidad. Los usuarios deben utilizar BSRGANx4 o RealESRGANx4 para escalado extremo.
\end{itemize}

\subsection{Características Principales}
\begin{itemize}[leftmargin=*]
    \item \textbf{Escalado por IA:} Utiliza modelos de última generación como Real-ESRGAN, BSRGAN y SRVGGNetCompact.
    \item \textbf{Interpolación de Fotogramas:} Aumenta los FPS o crea efectos de cámara lenta fluidos usando modelos RIFE.
    \item \textbf{Reducción de Ruido:} Incluye modelos IRCNN dedicados a la limpieza de imágenes y videos.
    \item \textbf{Restauración de Rostros:} Modelo GFPGAN para mejorar y restaurar rostros en fotos.
    \item \textbf{Aceleración por Hardware:} Usa el motor ONNX Runtime con el proveedor DirectML (\texttt{DmlExecutionProvider}) para una aceleración por GPU compatible con DirectX 12.
    \item \textbf{Codificación de Video Avanzada:} Soporte para codificadores acelerados por hardware de NVIDIA (NVENC), AMD (AMF) e Intel (QSV).
    \item \textbf{Sistema de Descarga Inteligente:} Descarga automática de modelos IA (327MB) al primer inicio, reduciendo el tamaño del instalador de 1.4GB a 300MB.
\end{itemize}


% --- Sección 2: Instalación ---
\section{Instalación y Arquitectura del Programa}

\subsection{Sistema de Distribución Inteligente de Modelos IA}
\begin{infobox}
Warlock-Studio 4.0.1 introduce un sistema revolucionario de distribución de modelos IA que descarga automáticamente los componentes necesarios durante el primer inicio de la aplicación.
\end{infobox}

\subsubsection{Ventajas del Nuevo Sistema}
\begin{itemize}[leftmargin=*]
    \item \textbf{Instalador Ligero:} Tamaño reducido del 78\% (de 1.4GB a ~300MB)
    \item \textbf{Descarga Inteligente:} Los modelos IA (327MB) se descargan automáticamente al primer uso
    \item \textbf{Múltiples Fuentes:} URLs redundantes (GitHub, SourceForge) garantizan disponibilidad
    \item \textbf{Seguimiento de Progreso:} Indicadores visuales muestran velocidad de descarga y porcentaje de completado
    \item \textbf{Recuperación de Errores:} Mecanismos automáticos de reintento y mensajes de error claros
    \item \textbf{Soporte de Reanudación:} Las descargas interrumpidas pueden reanudarse sin problemas
\end{itemize}

\subsubsection{Proceso de Descarga Automática}
Al iniciar Warlock-Studio por primera vez, el sistema realizará las siguientes operaciones:
\begin{enumerate}[leftmargin=*]
    \item \textbf{Verificación de Modelos:} Comprueba si los modelos IA están presentes
    \item \textbf{Diálogo de Confirmación:} Solicita permiso para descargar 327MB de modelos IA
    \item \textbf{Descarga Progresiva:} Muestra progreso en tiempo real con indicadores visuales
    \item \textbf{Validación de Integridad:} Verifica que los archivos descargados estén completos
    \item \textbf{Extracción Automática:} Descomprime y organiza los modelos en la estructura correcta
\end{enumerate}

\subsubsection{Configuración Offline y Manual}
Para usuarios con conectividad limitada o preferencias específicas:
\begin{description}[leftmargin=*, style=nextline]
    \item[Instalación Offline:] Los modelos pueden descargarse por separado y colocarse manualmente en la carpeta \texttt{AI-onnx}
    \item[Ubicación Manual:] Descargar \texttt{AI-onnx-models.zip} desde GitHub Releases y extraer en el directorio de instalación
    \item[Verificación de Archivos:] La aplicación verificará automáticamente la presencia de todos los modelos requeridos
\end{description}

\subsection{Requisitos del Sistema}
% Se usa 'table' para tablas que no se dividen entre páginas. [H] fuerza su posición.
\begin{table}[H]
    \centering % Centra la tabla en la página.
    % 'tabular' es el entorno que dibuja la tabla. {ll} define dos columnas alineadas a la izquierda.
    \begin{tabular}{ll}
        \toprule % Línea superior de la tabla (de booktabs).
        \textbf{Componente} 6 \textbf{Requisito} \\
        \midrule % Línea media de la tabla (de booktabs).
        Sistema Operativo 6 Windows 10 (64-bit) o posterior \\
        Memoria RAM 6 8 GB (Mínimo), 16 GB (Recomendado) \\
        Tarjeta Gráfica (GPU) 6 Compatible con \textbf{DirectX 12}. \textbf{Recomendado: 4+ GB VRAM}. \\
        Almacenamiento 6 2 GB de espacio libre. Se recomienda un SSD para un mejor rendimiento. \\
        \bottomrule % Línea inferior de la tabla (de booktabs).
    \end{tabular}
    \caption{Requisitos de hardware y software para Warlock-Studio 4.0.1.}
\end{table}

\subsection{Estructura de Archivos y Dependencias}
\begin{infobox}
Warlock-Studio es una aplicación autocontenida. Los siguientes componentes se incluyen en la instalación y no requieren acción por parte del usuario.
\end{infobox}
\begin{itemize}[leftmargin=*]
    \item \inlinecode{ffmpeg.exe:} Ubicado en la carpeta \texttt{Assets}, es el motor para toda la manipulación, codificación y decodificación de video.
    \item \inlinecode{exiftool.exe:} También en \texttt{Assets}, se utiliza para leer y escribir metadatos (EXIF, XMP), asegurando que la información original del archivo se preserve.
    \item \textbf{Modelos IA:} Los modelos en formato \texttt{.onnx} se encuentran en la carpeta \texttt{AI-onnx}.
    \item \textbf{Preferencias de Usuario:} Se guarda un archivo \inlinecode{Warlock-Studio_4.0_UserPreference.json} en la carpeta de \textbf{Documentos} del usuario.
    \item \textbf{Registros (Logs):} Los archivos de registro se almacenan en \texttt{Documentos\textbackslash Warlock-Studio_4.0_Logs}.
\end{itemize}


% --- Sección 3: Guía de Modelos ---
\section{Guía Detallada de Modelos de IA}
La elección del modelo de IA es el factor más importante para la calidad y el tiempo de procesamiento.

\subsection{Guía Avanzada de Comparación de Modelos}
La tabla siguiente ofrece un análisis detallado del consumo de VRAM, funcionalidades y casos de uso de cada modelo IA implementado en Warlock-Studio.
% Tabla con columnas ajustadas para encajar en los márgenes de la página
% Uso de anchos fijos para mejor control de columnas y ajuste de texto
\begin{longtable}{p{2.8cm} p{1.8cm} p{1.2cm} p{1.5cm} p{7.2cm}}
\toprule
\textbf{Modelo} & \textbf{Función} & \textbf{Escala} & \textbf{VRAM (GB)} & \textbf{Caso de Uso Recomendado \& Detalles Técnicos} \\
\midrule
\endhead % \endhead define el encabezado que se repetirá en cada página.

\multicolumn{5}{c}{\textit{\textbf{Modelos de Reducción de Ruido (Denoising)}}} \\
\midrule
\texttt{IRCNN\_Mx1} & Denoise & x1 & 4.0 & Reducción de ruido moderado. Excelente para limpiar fotos antiguas con niveles medios de artefactos. \\
\texttt{IRCNN\_Lx1} & Denoise & x1 & 4.0 & Reducción de ruido intenso. Óptimo para imágenes muy degradadas con artefactos severos. \\
\midrule
\multicolumn{5}{c}{\textit{\textbf{Modelos de Escalado - Alta Calidad (Procesamiento Lento)}}} \\
\midrule
\texttt{BSRGANx4} & Upscale & x4 & 0.6 & Fotografías realistas con excelente preservación de detalles finos. Ideal para retratos y escenas naturales. \\
\texttt{BSRGANx2} & Upscale & x2 & 0.7 & Calidad similar a la variante x4 pero para necesidades de escalado moderado. Procesamiento más rápido. \\
\texttt{RealESRGANx4} & Upscale & x4 & 0.6 & Modelo de propósito general. Excelente para texturas y tipos de contenido mixto. \\
\texttt{RealESRNetx4} & Upscale & x4 & 2.2 & Alternativa a RealESRGAN. Puede ofrecer mejor equilibrio velocidad-calidad en algunos sistemas. \\
\midrule
\multicolumn{5}{c}{\textit{\textbf{Modelos de Escalado - Alta Velocidad (Ligeros)}}} \\
\midrule
\texttt{RealESR\_Gx4} & Upscale & x4 & 2.2 & Procesamiento rápido ideal para videos. Buen equilibrio entre velocidad y calidad. \\
\texttt{RealESR\_Animex4} & Upscale & x4 & 2.2 & Especializado para anime, dibujos animados y contenido ilustrado. Preserva el estilo artístico. \\
\midrule
\multicolumn{5}{c}{\textit{\textbf{Modelos de Restauración de Rostros}}} \\
\midrule
\texttt{GFPGAN} & Restaurar & x1 & 1.8 & Mejora y restauración de rostros impulsada por IA. Repara rostros dañados en fotos antiguas. \\
\midrule
\multicolumn{5}{c}{\textit{\textbf{Modelos de Interpolación de Fotogramas (Solo Video)}}} \\
\midrule
\texttt{RIFE} & Interpolar & N/A & N/A & Máxima calidad de interpolación. Crea movimiento suave entre frames para altos FPS. \\
\texttt{RIFE\_Lite} & Interpolar & N/A & N/A & Versión optimizada para GPUs con VRAM limitada (< 4 GB). Procesamiento más rápido. \\
\midrule
\multicolumn{5}{c}{\textit{\textbf{Nota de Versión 4.0.1}}} \\
\midrule
\multicolumn{5}{p{14cm}}{\textbf{ELIMINADO:} El modelo SuperResolution-10 ha sido removido en la versión 4.0.1 debido a conflictos de compatibilidad. Para escalado extremo, se recomienda utilizar BSRGANx4 o RealESRGANx4 aplicados múltiples veces o en combinación con otros modelos.} \\
\bottomrule
\caption{Guía integral de selección de modelos de IA y requisitos de VRAM.}
\label{tab:modelos}
\end{longtable}


% --- Sección 4: Optimización ---
\section{Configuración y Optimización del Rendimiento}

\subsection{Parámetros Críticos de Rendimiento}
\begin{itemize}[leftmargin=*]
    \item \textbf{Input Resolution \%:} El ajuste más efectivo para la velocidad. Reduce la resolución antes de procesarla con IA. Un valor entre \textbf{50\% y 75\%} suele ser ideal.
    \item \textbf{GPU VRAM Limiter (GB):} Defina la VRAM de su GPU. Se usa para calcular el tamaño de los \textit{tiles} de procesamiento y evitar errores de memoria.
    \item \textbf{AI Multithreading:} Solo para videos. Procesa varios fotogramas en paralelo. Acelera el proceso pero consume más VRAM y CPU.
    \item \textbf{AI Blending:} Combina la imagen original con la procesada. Útil para reducir artefactos cuando se usa un \textit{Input Resolution} bajo.
    \item \textbf{Generación de fotogramas:} Para modelos RIFE, permite crear fotogramas interpolados para mayor FPS o efectos de cámara lenta.
\end{itemize}

\subsection{El Fichero de Preferencias de Usuario}
El archivo Warlock-Studio4.0UserPreference.json guarda su configuración.
% Se usa 'tabularx' para que la tabla ocupe automáticamente el 100% del ancho del texto.
% La columna 'X' es una columna flexible que se expande para llenar el espacio disponible.
\begin{table}[H]
    \centering
    \small % Reduce el tamaño de la fuente dentro de la tabla.
    \begin{tabularx}{\textwidth}{l X}
        \toprule
        \textbf{Clave JSON} 6 \textbf{Descripción} \\
        \midrule
        \texttt{default\_AI\_model} 6 El último modelo de IA seleccionado. \\
        \texttt{default\_AI\_multithreading} 6 El número de hilos de procesamiento para video. \\
        \texttt{default\_gpu} 6 La última GPU seleccionada (Auto, GPU 1, etc.). \\
        \texttt{default\_keep\_frames} 6 Si se deben conservar los fotogramas de video ("ON" o "OFF"). \\
        \texttt{default\_image\_extension} 6 Extensión de imagen por defecto (\texttt{.png}, \texttt{.jpg}, etc.). \\
        \texttt{default\_video\_extension} 6 Extensión de video por defecto (\texttt{.mp4}, \texttt{.mkv}, etc.). \\
        \texttt{default\_video\_codec} 6 El codificador de video por defecto (x264, hevc\_nvenc, etc.). \\
        \texttt{default\_blending} 6 El nivel de mezcla seleccionado (Low, Medium, High). \\
        \texttt{default\_output\_path} 6 La última ruta de salida seleccionada. \\
        \texttt{default\_input\_resize\_factor} 6 El valor del porcentaje de resolución de entrada. \\
        \texttt{default\_output\_resize\_factor} 6 El valor del porcentaje de resolución de salida. \\
        \texttt{default\_VRAM\_limiter} 6 El valor del limitador de VRAM de la GPU. \\
        \bottomrule
    \end{tabularx}
    \caption{Claves guardadas en el archivo de preferencias del usuario.}
\end{table}

% --- Sección 5: Solución de Problemas ---
\section{Guía Avanzada de Solución de Problemas}
\begin{warnbox}
La causa \textbf{Número 1} de errores son los \textbf{caracteres especiales} en rutas y nombres de archivo. Evite usar: \texttt{', ", @, \#, \$, \%, \&amp;, *, [, ], ?, etc.}.
\end{warnbox}

% 'description' es para listas de definiciones.
% [style=nextline] coloca el texto en la línea siguiente al término.
\begin{description}[leftmargin=*, style=nextline, itemsep=0.8em]
    \item[\faBan\ Error: "FFmpeg encoding failed: Invalid argument"]
        \textbf{Causa:} Nombre de archivo o ruta no válida.
        \textbf{Solución:} Renombre el archivo y/o la carpeta eliminando caracteres especiales.

    \item[\faMemory\ Error: "out of memory" o cierre inesperado]
        \textbf{Causa:} La GPU se quedó sin memoria de video (VRAM).
        \textbf{Solución:}
        % 'enumerate' es para listas numeradas. 'nosep' reduce el espacio entre ítems.
        \begin{enumerate}[nosep, leftmargin=*]
            \item Reduzca el \textbf{VRAM Limiter} a un valor igual o inferior al de su GPU.
            \item Baje el \textbf{Input Resolution \%} a 75\% o menos.
            \item Para videos, disminuya los hilos de \textbf{AI Multithreading} o apáguelo.
            \item La aplicación intentará recuperarse de este error automáticamente.
        \end{enumerate}

    \item[\faTachometerAlt\ Error: "cannot convert float NaN to integer"]
        \textbf{Causa:} Timeout del driver de la GPU, a menudo por sobrecarga o sobrecalentamiento.
        \textbf{Solución:} Reinicie el proceso \textbf{sin borrar la carpeta de fotogramas}. El programa reanudará el trabajo donde se quedó.

    \item[\faVolumeMute\ Problema: Video de salida sin audio]
        \textbf{Causa:} El video original no tenía audio, se usó un modo \textit{Slowmotion} o el códec de audio era incompatible.
        \textbf{Solución:} El programa intenta copiar el audio, si falla, lo re-codifica a AAC. Si todo falla, guarda el video sin audio. Usar \inlinecode{.mkv} en la salida puede ayudar.

    \item[\faQuestionCircle\ Problema: La aplicación no se abre]
        \textbf{Causa:} Configuración corrupta, falta de permisos o error del entorno.
        \textbf{Solución:}
        \begin{enumerate}[nosep, leftmargin=*]
            \item Elimine el archivo \inlinecode{Warlock-Studio_4.0_UserPreference.json} en su carpeta de \textbf{Documentos}.
            \item Revise los archivos de registro en \texttt{Documentos\textbackslash Warlock-Studio_4.0_Logs}.
            \item Asegúrese de que sus controladores de GPU estén actualizados.
        \end{enumerate}

    \item[\faExclamationTriangle\ Problema: La interpolación de fotogramas no funciona]
        \textbf{Causa:} Modelos RIFE no seleccionados o formato de video incompatible.
        \textbf{Solución:} Asegúrese de haber seleccionado un modelo RIFE (RIFE o RIFE\_Lite) y que la opción de generación de fotogramas esté correctamente configurada.
\end{description}

% --- Sección 6: Arquitectura ---
\section{Arquitectura y Procesos Avanzados}

\subsection{Motor de Inferencia y Aceleración por Hardware}
Warlock-Studio utiliza \textbf{ONNX Runtime} con el proveedor \textbf{DirectML} (\inlinecode{DmlExecutionProvider}). Este traduce las operaciones de IA a llamadas de \textbf{DirectX 12}, garantizando una amplia compatibilidad con GPUs de NVIDIA, AMD e Intel.

\subsection{Sistema de Tiles y Gestión de Memoria}
Para manejar archivos de alta resolución, la aplicación divide cada fotograma en fragmentos (\textit{tiles}). El tamaño de estos se calcula dinámicamente usando el \textbf{VRAM Limiter}. Además, se invoca al recolector de basura de Python (\inlinecode{gc.collect()}) para forzar la liberación de memoria y garantizar estabilidad.

\subsection{Funcionalidad de Reanudación y Checkpoints}
Si un proceso de video se interrumpe, los fotogramas procesados se guardan. Al reiniciar la tarea, la función \inlinecode{check\_video\_upscaling\_resume} detecta estos archivos y continúa el trabajo desde donde falló, ahorrando tiempo.

\subsection{Escritura Asíncrona de Fotogramas}
Durante el escalado de video, los fotogramas procesados se envían a un hilo de escritura separado. Esto permite a la GPU procesar el siguiente lote sin esperar a que la escritura en disco (más lenta) termine, maximizando el rendimiento.

\subsection{Pipeline de Interpolación de Fotogramas}
Los modelos RIFE utilizan un pipeline de interpolación especializado que analiza el movimiento entre fotogramas para generar fotogramas intermedios suaves. Esto permite mayores tasas de cuadros o efectos de cámara lenta con artefactos mínimos.

\subsection{Sistema de Logs y Diagnóstico}
Warlock-Studio implementa un sistema completo de registro que incluye:
\begin{itemize}[leftmargin=*]
    \item \textbf{Logs de Proceso:} Registran cada etapa del procesamiento de IA
    \item \textbf{Logs de Error:} Capturan errores detallados con stack traces
    \item \textbf{Logs de Rendimiento:} Miden tiempos de procesamiento y uso de recursos
\end{itemize}

\subsection{Modelos Removidos en Versión 4.0.1}
\begin{warnbox}
El modelo SuperResolution-10 ha sido eliminado de la versión 4.0.1 debido a conflictos de compatibilidad y estabilidad. Para necesidades de escalado extremo, se recomienda:
\begin{itemize}[leftmargin=*]
    \item \textbf{BSRGANx4:} Aplicar múltiples veces para escalado gradual
    \item \textbf{RealESRGANx4:} Excelente calidad para escalado de propósito general
    \item \textbf{Combinación de modelos:} Usar IRCNN para limpieza previa seguido de BSRGAN
\end{itemize}
\end{warnbox}

\section{Resolución Avanzada de Errores y Diagnósticos del Sistema}

\subsection{Gestión de Memoria GPU y Optimización de VRAM}
Warlock-Studio implementa gestión sofisticada de memoria GPU:
\begin{description}[leftmargin=*, style=nextline]
    \item[Dimensionamiento Dinámico de Tiles:] Calcula automáticamente tamaños óptimos de tiles basado en VRAM disponible
    \item[Gestión de Pool de Memoria:] Pre-asigna y reutiliza buffers de memoria para reducir overhead de asignación
    \item[Integración de Recolector de Basura:] Fuerza la recolección de basura de Python en puntos estratégicos para liberar memoria no utilizada
    \item[Monitoreo de VRAM:] Monitoreo en tiempo real del uso de memoria GPU con fallback automático a tiles más pequeños
\end{description}

\subsection{Solución de Problemas en Carga e Inicialización de Modelos}
\begin{warnbox}
Las fallas en la carga de modelos a menudo son causadas por archivos ONNX corruptos, permisos de sistema insuficientes, o errores de inicialización del proveedor DirectML.
\end{warnbox}
\begin{description}[leftmargin=*, style=nextline]
    \item[Corrupción de Archivo de Modelo:] Verificar integridad del archivo de modelo comparando tamaños con valores esperados
    \item[Fallas de Inicialización de Proveedor:] Verificar compatibilidad DirectML y asegurar que DirectX 12 esté correctamente instalado
    \item[Problemas de Permisos:] Ejecutar aplicación como administrador si la carga de modelos falla consistentemente
\end{description}

\subsection{Diagnósticos del Pipeline de Procesamiento de Video}
El pipeline de procesamiento de video consiste en varias etapas que pueden ser diagnosticadas individualmente:
\begin{enumerate}[leftmargin=*]
    \item \textbf{Extracción de Frames:} Verificar que FFmpeg pueda leer el formato de video de entrada
    \item \textbf{Procesamiento IA:} Monitorear uso de VRAM y tiempos de procesamiento por frame
    \item \textbf{Ensamblaje de Frames:} Verificar frames intermedios faltantes o corruptos
    \item \textbf{Codificación de Video:} Validar compatibilidad de codec y disponibilidad de codificador hardware
\end{enumerate}

\subsection{Guías de Optimización de Rendimiento}
\begin{table}[H]
    \centering
    \small
    \begin{tabularx}{\textwidth}{l X}
        \toprule
        \textbf{Escenario} & \textbf{Configuraciones Recomendadas} \\
        \midrule
        VRAM Baja (< 4GB) & Resolución de Entrada: 50\%, Multithreading: OFF, Usar RIFE\_Lite \\
        VRAM Media (4-8GB) & Resolución de Entrada: 75\%, Multithreading: 2-4 hilos, Modelos estándar \\
        VRAM Alta (> 8GB) & Resolución de Entrada: 100\%, Multithreading: 6-8 hilos, Modelos alta calidad \\
        Almacenamiento SSD & Mantener frames: ON para reanudación rápida, Usar multithreading alto \\
        Almacenamiento HDD & Mantener frames: OFF para ahorrar espacio, Multithreading bajo para reducir I/O \\
        \bottomrule
    \end{tabularx}
    \caption{Configuraciones de optimización basadas en configuración del sistema.}
\end{table}

\subsection{Análisis de Archivos de Log y Depuración}
Warlock-Studio genera logs comprensivos en la carpeta Documentos:
\begin{description}[leftmargin=*, style=nextline]
    \item[warlock\_studio.log:] Eventos generales de aplicación, carga de modelos, y estado de procesamiento
    \item[error\_log.txt:] Mensajes de error detallados con stack traces de Python
    \item[performance\_log.txt:] Tiempos de procesamiento, uso de memoria, y métricas de rendimiento
\end{description}

\subsection{Patrones Comunes de Error y Soluciones}
\begin{longtable}{p{4cm} p{5cm} p{6cm}}
\toprule
\textbf{Patrón de Error} & \textbf{Causa Típica} & \textbf{Estrategia de Solución} \\
\midrule
\endhead
"DirectML device not found" & Drivers de GPU desactualizados o DirectX 12 no soportado & Actualizar drivers de GPU, verificar compatibilidad DirectX 12 \\
"ONNX Runtime initialization failed" & Archivos de modelo corruptos o permisos insuficientes & Re-descargar modelos, ejecutar como administrador \\
"FFmpeg process terminated" & Codec no soportado o archivo de entrada corrupto & Convertir entrada a formato soportado (MP4, H.264) \\
"Tile processing timeout" & GPU sobrecalentada o inestabilidad de driver & Reducir tamaño de tile, verificar temperatura GPU, actualizar drivers \\
"Memory allocation failed" & RAM del sistema agotada & Cerrar otras aplicaciones, reducir multithreading \\
\bottomrule
\caption{Patrones comunes de error y estrategias de resolución.}
\end{longtable}

\subsection{Métricas de Rendimiento y Monitoreo}
La aplicación proporciona métricas detalladas de rendimiento:
\begin{description}[leftmargin=*, style=nextline]
    \item[Velocidad de Procesamiento:] Métricas de frames por segundo (FPS) e imágenes por minuto
    \item[Uso de Memoria:] Monitoreo en tiempo real de VRAM y RAM del sistema
    \item[Utilización de GPU:] Estadísticas de rendimiento del proveedor DirectML
    \item[E/S de Disco:] Velocidades de lectura/escritura para almacenamiento temporal de frames
\end{description}


% =======================================================================================
% FIN DEL MANUAL
% =======================================================================================
\end{document}
