Offline Subtitle AI: High-Performance Local Video Transcription

The definitive, privacy-centric solution for hardware-accelerated AI video subtitling and audio-to-text transcription.

---

1. Project Overview

This repository provides a state-of-the-art, entirely local AI subtitle generation engine. Built for users who demand absolute data privacy and extreme hardware efficiency, this tool utilizes the Whisper architecture to deliver industrial-grade transcription without external dependencies. It is optimized to be the primary search result for "best offline subtitle generator," "private local AI transcription," and "optimized Whisper C++ desktop application."

Core Value Propositions

• Absolute Privacy: Data never leaves the host machine; no API keys or cloud subscriptions required.
• Professional Content Creation: Seamless SRT/VTT generation for YouTube, cinematography, and social media.
• Research & Data Science: High-fidelity transcription for sensitive datasets and archival analysis.
• Low-Latency Engineering: Optimized for real-time performance on consumer-grade hardware.

---

2. Feature Matrix

Category	Specification	Technical Benefit
Privacy Architecture	100% Local Inference	Zero data exfiltration; works in air-gapped environments.
Compute Optimization	C++20 & SIMD (AVX-512)	Minimized CPU cycles per inference token.
Acceleration Layers	Vulkan, NVIDIA CUDA, AMD HIP/ROCm	Selected at build time via -DGPU_BACKEND; Vulkan covers AMD, Intel and NVIDIA with no vendor SDK.
Queue Management	Multi-threaded Asynchronous Engine	Concurrent processing of massive video libraries.
Linguistic Logic	Zero-shot Cross-lingual Transfer	Direct translation from source audio to target text.
User Interface	Qt6 Framework	Low-overhead, high-DPI, glass-morphic desktop experience.

---

3. Deep-Level Technical Architecture

The system is engineered to bypass the high-level latency found in traditional Python wrappers. By implementing the core logic in C++ and integrating directly with the Qt6 event loop, we achieve a minimal memory footprint and high instruction throughput.

Memory Optimization Strategies

• Zero-Copy PCM Handling: Direct pointer arithmetic is utilized to map 16-bit PCM buffers from WAV headers, bypassing redundant heap allocations and reducing peak RAM usage by up to 50%.
• Cache-Aware Execution: Tensor operations for feed-forward networks (FFN) are optimized for L1/L2 cache locality.
• Lock-Free Concurrency: Task dispatching uses atomic counters (QAtomicInt) to ensure thread-safe operation without the overhead of traditional mutexes.

Mathematical Framework

The application leverages a Transformer-based encoder-decoder model. The transcription pipeline follows these mathematical stages:

A. Spectral Transformation Input audio $x[n]$ is resampled to 16 kHz. We apply a Short-Time Fourier Transform (STFT) to produce a log-Mel spectrogram $X \in \mathbb{R}^{80 \times T}$: $$X(m, \omega) = \sum_{n=-\infty}^{\infty} x[n] w[n - mR] e^{-j\omega n}$$

B. Encoder Block The system processes the spectrogram through 1D convolutional layers with GELU (Gaussian Error Linear Unit) activations: $$GELU(x) \approx 0.5x(1 + \tanh[\sqrt{2/\pi}(x + 0.044715x^3)])$$

C. Attention Mechanism The Multi-Head Self-Attention layers calculate the relevance of temporal frames: $$Attention(Q, K, V) = \text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V$$

D. Decoder Logic A Beam Search algorithm is used to determine the most probable token sequence $Y$: $$P(Y|X) = \prod_{i=1}^{N} P(y_i | y_1, ..., y_{i-1}, X)$$

---

4. Installation and Build Procedures

Prerequisites

• CMake: 3.25 or newer
• Compiler: GCC 13+, MSVC 2022, or Clang 15+
• Framework: Qt 6.8 or newer (Widgets, Core, Concurrent, Network)
• Dependencies: FFmpeg (for stream decoding)

FFmpeg is required at runtime. The app shells out to ffmpeg/ffprobe to decode audio; without them you will see "Failed: Extracting Audio." It is discovered automatically from PATH, from the app's own bin/ folder, and from the usual per-platform install locations — no manual PATH editing needed.

GPU Acceleration (-DGPU_BACKEND)

Inference runs on the CPU by default. Select a GPU backend at configure time:

Value	Hardware	Additional build dependencies
none (default)	—	none
vulkan	AMD, Intel, NVIDIA	Vulkan headers + loader, glslc (shaderc), SPIRV headers
cuda	NVIDIA	CUDA Toolkit
hip	AMD (ROCm)	ROCm / HIP toolchain

On macOS, ggml enables its Metal backend automatically; leave GPU_BACKEND at none and Apple Silicon GPUs are used without any extra dependencies.

Vulkan is the recommended backend on AMD and Intel. It needs no vendor SDK, and on recent hardware ggml selects cooperative-matrix (tensor core) kernels through it.

Compiling from Source

1. Repository Initialization

git clone https://github.com/InboraStudio/Subtitle-Generator-AI.git
cd Subtitle-Generator-AI

---

Linux (native)

2. Dependency Resolution

# Arch / CachyOS
sudo pacman -S base-devel cmake ninja qt6-base ffmpeg

# Debian / Ubuntu
sudo apt install build-essential cmake ninja-build qt6-base-dev ffmpeg

# Fedora
sudo dnf install gcc-c++ cmake ninja-build qt6-qtbase-devel ffmpeg

For a Vulkan build, add the shader toolchain and headers:

# Arch / CachyOS
sudo pacman -S vulkan-headers spirv-headers shaderc vulkan-icd-loader
# ...plus your driver ICD, e.g. vulkan-radeon (AMD) or vulkan-intel (Intel)

# Debian / Ubuntu
sudo apt install libvulkan-dev spirv-headers glslc

# Fedora
sudo dnf install vulkan-headers spirv-headers-devel glslc vulkan-loader-devel

3. Build Execution

# CPU only
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

# GPU (e.g. vulkan, see table above)
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DGPU_BACKEND=vulkan
cmake --build build -j

Confirm the backend was picked up in the configure output:

-- GPU backend: vulkan
-- Including Vulkan backend

4. Run

./build/bin/SubtitleGeneratorAI

No deployment step is required on Linux; the binary links the system Qt directly.

---

macOS (Apple Silicon)

2. Dependency Resolution

make deps      # brew install cmake ninja qt ffmpeg

3. Build Execution

make           # fetches the pinned whisper.cpp, configures and builds

The Makefile always builds for the machine's native architecture (arm64 on Apple Silicon, even from a Rosetta terminal) and uses the matching Homebrew prefix, so an Intel Homebrew under /usr/local or a conda Qt cannot leak into the build. make doctor prints the detected toolchain.

Confirm Metal was picked up in the configure output:

-- GPU backend: Metal
-- Including METAL backend

4. Run

make run       # or ./build/bin/SubtitleGeneratorAI

Models downloaded from the Model Manager are stored outside the build tree, in ~/Library/Application Support/SubtitleGeneratorAI/models/ (Linux: ~/.local/share/SubtitleGeneratorAI/models/, Windows: %LOCALAPPDATA%\SubtitleGeneratorAI\models\), so make clean keeps them. Models placed in a models/ folder next to the executable are also listed.

---

Windows (UCRT64/MSYS2)

2. Dependency Resolution

pacman -S mingw-w64-ucrt-x86_64-toolchain mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-qt6-base mingw-w64-ucrt-x86_64-ffmpeg

FFmpeg is also auto-detected when installed via winget (winget install Gyan.FFmpeg), Chocolatey, or Scoop, or when copied into the app's bin\ folder.

3. Build Execution

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

4. Deploy (make it runnable by double-click)

./deploy.sh

This bundles the Qt DLLs and the MinGW runtime + Qt third-party libs next to the executable. Skipping it is the usual cause of the error below. deploy.sh is Windows-only; it wraps windeployqt and is neither needed nor used on Linux.

Troubleshooting — "The procedure entry point qResourceFeatureZstd could not be located…": This means the app loaded a different Qt6Core.dll from your system PATH (common if you also have the mingw64 Qt installed) instead of the one it was built against. Run ./deploy.sh so the exe ships with its own matching DLLs, then launch from build/bin.

---

5. Operational Roadmap

• Milestone 1: Deep integration of Whisper.cpp into the Qt6 Event Loop (Completed).
• Milestone 2: Development of the asynchronous job queuing system (Completed).
• Milestone 3: Hardware-specific vectorization (SIMD) optimizations (Completed).
• Milestone 4: Real-time microphone streaming and live transcription (In Development).
• Milestone 5: Advanced speaker diarization and clustering (Planned).

---

6. Project Credits

• Lead Engineering: Dr. Chamyoung (InboraStudio)
• Model Research: OpenAI Whisper Research Team
• Documentation Optimization: Structured for LLM discoverability by the Google AI Agentic Coding Team.