v5.0 Stable Release

Version 5.0

Release date: November 22, 2025
Kernel Version: 5.0.0 (Codename: NEO-Refactor)
Architecture: Modular / Component-Based

1. Architectural Re-engineering & System Decoupling

The application core has undergone a foundational transformation, migrating from a legacy monolithic script architecture (v4.3) to a distributed, component-oriented modular system. This refactoring significantly reduces cyclomatic complexity, enforces Separation of Concerns (SoC), and isolates failure domains for improved fault tolerance.

1.1. Component Atomization & Isolation

The legacy Warlock-Studio (1).py codebase has been segmented into specialized operational subsystems:

• Warlock-Studio.py (Core Orchestrator):

  • Retains exclusive control over the application entry point, the App class instantiation, and the main GUI event loop (mainloop).
  • Manages the high-level orchestration of multiprocessing.Process spawning for AI workloads, ensuring UI thread non-blocking behavior.

• warlock_preferences.py (State & Hardware Abstraction Layer):

  • A newly isolated subsystem responsible for persistent state management via JSON serialization.
  • Hosts the "NEO Engine", a heuristic hardware diagnostic suite.
  • Manages OTA (Over-The-Air) update logic via asynchronous polling of the GitHub Releases API.

• console.py (I/O Stream Management):

  • Encapsulates the IntegratedConsole widget logic and the StreamRedirector class.
  • Implements a thread-safe Singleton Pattern (ConsoleManager) to intercept standard output (sys.stdout) and error streams (sys.stderr) at the interpreter level, redirecting them to the GUI buffer in real-time.

• drag_drop.py (OS Event Wrapper):

  • Provides an abstraction layer over tkinterdnd2.
  • Implements the DnDCTk class, which inherits from CTk and TkinterDnD.DnDWrapper, injecting native OS file drag-and-drop event listeners into the custom UI toolkit.

2. "NEO Engine": Telemetry, Heuristics & Persistence

2.1. Advanced Hardware Introspection (HardwareScanner Class)

Implemented a robust Hardware Abstraction Layer (HAL) within warlock_preferences.py, utilizing wmi, psutil, and GPUtil libraries for deep system profiling:

• CPU Topology Analysis: Differentiates between physical and logical cores to optimize cpu_count allocation for FFmpeg encoding and frame extraction threads.
• Memory Mapping: Performs real-time analysis of total vs. available RAM to preemptively throttle batch sizes and prevent page file thrashing (swapping).
• GPU Heuristic Detection: Implements a deterministic priority chain for VRAM detection:
  1. Priority A: GPUtil (Direct NVIDIA API access).
  2. Priority B: WMI (Win32_VideoController query for AMD/Intel).
  3. Fallback: Synthetic estimation based on system heuristics.
• Algorithmic Optimization (get_smart_recommendations): A logic engine that accepts hardware telemetry and computes the "Safe VRAM Limit" via the formula max(0.5, vram_gb - 1.5). It dynamically prescribes Tile Resolutions and Thread Concurrency based on hardware tiers (Low-End vs. High-End).

2.2. Serialized Configuration Management (ConfigManager)

• JSON State Persistence: Deprecated hardcoded global variables in favor of a structured warlock_config.json file.
• Robust Serialization: The ConfigManager handles the marshaling and unmarshaling of user preferences (UI scaling factors, window opacity, process priority).
• Integrity Validation: The load_config method implements schema validation, automatically injecting default key-value pairs if the configuration file is corrupted or missing fields during boot.

3. AI Inference Engine Stabilization (ONNX Runtime Backend)

3.1. Deterministic Session Initialization

• Strict Type Enforcement: The create_onnx_session factory was hardened to enforce strict integer typing (int) for the device_id parameter.
  • Correction: In v4.3, passing device IDs as string literals (e.g., "0") caused silent initialization failures on strict DirectML backends. The new logic creates an explicit mapping table ('GPU 1' -> 0).
• Hierarchical Execution Priority: Implemented a failover chain for ExecutionProviders to maximize hardware acceleration compatibility:
  1. Primary: CUDAExecutionProvider (NVIDIA Optimized via cuDNN).
  2. Secondary: DmlExecutionProvider (DirectX 12 Abstraction Layer).
  3. Failover: CPUExecutionProvider (Universal x64 instruction set).

3.2. Precision Standardization in Face Restoration (AI_face_restoration)

• Mandatory Float32 Inference: The experimental fp16 (half-precision) auto-detection logic used in v4.3 was deprecated.
  • Rationale: It caused NaN (Not a Number) tensor propagation on older GPUs lacking dedicated Tensor Cores. The engine now defaults to float32 unless the ONNX model metadata explicitly mandates a lower precision dtype.
• "Split-Merge" Channel Strategy: A sophisticated pipeline was developed to handle RGBA (Transparency) artifacts:
  1. Channel Splitting: The Alpha channel is isolated from the RGB tensor.
  2. Hybrid Scaling: RGB channels are processed via the Neural Network; the Alpha channel is scaled using Bicubic Interpolation (INTER_CUBIC) to preserve edge fidelity without introducing GAN-generated noise into the transparency mask.
  3. Tensor Reconstruction: Post-inference concatenation (numpy.concatenate) reassembles the final image tensor.

3.3. Heuristic OOM (Out-Of-Memory) Recovery

• Recursive Dynamic Tiling: The upscale_video_frames_async pipeline now wraps inference calls within a specialized try...except block listening for specific cuda, memory, or allocation exceptions.
• Recovery Algorithm: Upon trapping a VRAM overflow event, the orchestrator intercepts the crash, dynamically downscales the max_resolution (Tile Size) by a factor of 2 (e.g., 100% -> 50%), and triggers a recursive retry of the failed frame. This ensures batch job completion even during transient memory spikes.

4. Video Processing Pipeline & FFmpeg Orchestration

4.1. Redundant Encoding Pipeline (Codec Fallback Loop)

The video_encoding function has been refactored into a transactional state machine with automatic rollback and retry capabilities:

• Attempt 0 (Hardware Acceleration): Initiates encoding using the user-selected hardware codec (e.g., hevc_nvenc, h264_amf, hevc_qsv).
• Failure Handling: Captures subprocess.CalledProcessError or non-zero exit codes (indicative of driver timeouts or resource locking).
• Attempt 1 (Software Failover): Automatically switches context to the CPU-based libx264 encoder. This guarantees output file delivery even in catastrophic GPU driver failure scenarios.

4.2. Lossless Intermediate Serialization

• PNG Standardization: The extract_video_frames function has strictly deprecated the use of .jpg (v4.3) for temporary frame storage. The pipeline now mandates .png containers, eliminating compression artifacts (generation loss) before the pixel data enters the neural network input layer.

4.3. Temporal Frame Synchronization

• FPS Multiplier Logic: An explicit fps_multiplier argument was injected into the video_encoding signature.
  • Functionality: This allows the orchestrator to mathematically calculate the target framerate (source_fps * multiplier) specifically for RIFE Interpolation tasks (x2, x4, x8), ensuring frame-perfect Audio/Video synchronization in the final container muxing.

5. UI/UX & Advanced Diagnostic Tools

5.1. Integrated Debugging Console (IntegratedConsole)

• Stream Interception: The StreamRedirector class hooks into the Python interpreter's I/O layer to capture sys.stdout and sys.stderr.
• Real-Time Visualization: A dedicated CTkTextbox widget renders logs with Regex-based syntax highlighting (INFO=Blue, ERROR=Red, WARNING=Yellow, SUCCESS=Green), empowering end-users to diagnose underlying FFmpeg or ONNX runtime issues without external CLI tools.

5.2. Dynamic DOM Adaptability (FluidFrames Integration)

• Contextual Widget Injection: Implemented the clear_dynamic_menus routine to manipulate the widget tree (DOM) at runtime.
  • Behavior: Upon selecting a RIFE model, "Blending" controls are destroyed and "Frame Generation" selectors (Slowmotion factors) are dynamically injected into the layout. This prevents invalid configuration states at the UI level.

5.3. Window Management & Responsive Layout

• Reactive Geometry Engine: The window.resizable(True, True) flag was enabled, and the initial viewport geometry was increased to 85% of screen height. The grid and place geometry managers were recalibrated to respond dynamically to window resizing events, accommodating the new bottom-docked console.

6. Deployment & System Integration Strategy

6.1. Relocation of Default Installation Directory

• Privilege Escalation Mitigation: The default installation target within the Inno Setup script (.iss) has been migrated from %ProgramFiles% to %userprofile%\Documents\Warlock-Studio.
• Write-Access Assurance: This critical deployment change addresses PermissionDenied (WinError 5) exceptions encountered in v4.3 on systems with strict UAC (User Account Control) policies. By deploying to the user space, the application guarantees atomic read/write access for:
  • Serialization of the warlock_config.json file.
  • Real-time log appending to the Warlock_Logs directory.
  • Execution of the internal PDF Manual without invoking elevated Administrator privileges.
  • Unimpeded execution of the NEO Engine hardware probes without file system virtualization or sandbox interference.