BlackVideo Mini Player v2.3.0 — Offline Captions (Whisper), Subtitle Rendering & Track Fix

[LoneStamp]

✅ What's in This Release

🎙️ Offline Caption Generation — Whisper.cpp Integration

Generate subtitles for any video without an internet connection or API key.

• Right-click → Generate Captions (Whisper) — transcribes the video's spoken audio and writes a .srt file beside the video. The result is auto-loaded into Track 1 when complete.
• Right-click → Translate to English (Whisper) — same pipeline with Whisper's --translate flag, which outputs English subtitles regardless of the spoken language. Useful for non-English films with no existing subtitle file.
• Player stays responsive while Whisper runs — the job is launched as a detached background process via WinExec. The player polls for the output .srt file each frame and loads it the moment it appears.
• Status banner in the control bar — shows Whisper: generating captions... or Whisper: translating... while the job is running, and clears automatically when done.
• Zero build-time dependency — whisper_bridge.adb shells out to whisper-cli.exe rather than linking against whisper.h. No whisper headers or import libraries needed in lib/.
• Hot-swappable models — place ggml-base.bin, ggml-small.bin, ggml-medium.bin, or ggml-large.bin in build\models\ and the next job picks it up automatically. No rebuild required.
• Auto-discovery — whisper-cli.exe and the model are resolved in order: BLACKVIDEO_WHISPER_PATH / BLACKVIDEO_WHISPER_MODEL env vars → build\ beside the exe → system PATH. No config file needed in production.

Translation language: Currently translates to English only. Whisper.cpp's --translate flag always targets English as the fixed output language. Support for translating to other target languages (Spanish, Japanese, Filipino, etc.) is planned for a future version.

---

📝 Real Subtitle Text Rendering

Loaded .srt files now display on-screen during playback — not just track labels in the menu.

• srt_parser.adb — new module that parses .srt files at load time (handles UTF-8 BOM, Windows CRLF, multi-line cues, up to 4 096 cues). Stores all cues in memory for O(n) per-frame lookup.
• Cue text pushed every frame — player.adb calls SRT_Parser.Current_Text(pos) each frame and pushes the result to the C overlay via bv_ui_set_sub_text.
• Subtitle overlay in ui_overlay.c — draws the current cue horizontally centred just above the control bar, with a semi-transparent shadow box for readability against any background colour.
• Works with any externally loaded .srt file and with Whisper-generated .srt files (auto-loaded from Track 1).

---

🐛 Subtitle Track State Bug Fixed

The subtitle track was silently resetting to Off immediately after a track was selected or a file was loaded.

• Root cause — when Open_Dialog (the PowerShell file picker) blocks via popen, SDL queues SDL_MOUSEBUTTONDOWN events in the background. When the dialog closes and the event pump resumes, those queued events fire Handle_Button_Down again. If the mouse had drifted over the Subtitle: Off row, CTX_SUB_NONE was triggered automatically, setting Sub_Active = -1 right after the user's selection.
• Fix — Ctx_Close_Tick records the SDL tick whenever the context menu closes. Any SDL_MOUSEBUTTONDOWN arriving within 250 ms of that moment is discarded. This absorbs all queued dialog-close events without affecting normal clicks.
• Context menu label fixed — the Subtitle: Off label in the context menu now updates to Subtitle: Track N (in red) when a track is active, so the current state is always visible without opening anything else.

---

⚙️ .env File — Dev / Production Path Override System

• main.adb loads .env at startup using SetEnvironmentVariableA for each KEY=VALUE line found in the file beside the exe. Blank lines and # comments are skipped.
• Production mode — no .env file needed in a release package. Whisper paths resolve automatically from build\. The player silently skips the load step if the file is absent.
• Dev mode — rename .env.example to .env and set BLACKVIDEO_WHISPER_PATH and BLACKVIDEO_WHISPER_MODEL to override the search paths during development (e.g. pointing to a whisper-bin-x64 folder outside the project).
• Never commit .env — it is listed in .gitignore and contains local machine paths only.

---

🏗️ Build System

• build.bat checks for Whisper assets (non-fatal) — prints [OK] if whisper-cli.exe and ggml-base.bin are found in build\, otherwise prints a setup reminder. Build continues regardless.
• build.bat generates .env.example if none exists — creates a ready-to-rename template with commented-out BLACKVIDEO_WHISPER_PATH and BLACKVIDEO_WHISPER_MODEL lines.
• build.bat copies Whisper DLLs (whisper.dll, ggml.dll, ggml-base.dll, ggml-cpu.dll) from lib\ to build\ alongside the other runtime DLLs, if present.

---

🎮 Controls

Keyboard

Key	Action
SPACE	Play / Pause
← / →	Seek −5 / +5 seconds
↑ / ↓	Volume +10 / −10
M	Mute / Unmute
L	Loop toggle
F	Fullscreen toggle
ESC or Q	Quit

UI Bar

Control	Action
Seek bar	Click or drag to jump/scrub
⏮ Prev	Seek to start
⏯ Play/Pause	Toggle playback
⏭ Next	Jump near end
🔁 Loop	Toggle loop
🔊 Volume	Mute/unmute
1.0x Speed	Cycle 0.5× / 1× / 1.5× / 2×
⛶ Fullscreen	Toggle fullscreen
⋮ Menu	Context menu

Context Menu (Right-click)

Item	Action
Open Video File...	Swap video (restart with new file)
Subtitle: Off / Track N	Toggle subtitles off, shows active track name
Track 1 / 2 / 3	Activate loaded track, or pick a file for empty slots
Generate Captions (Whisper)	Transcribe audio → .srt (auto-loaded)
Translate to English (Whisper)	Transcribe + translate to English → .srt (auto-loaded)

---

📦 Requirements (Windows)

• Windows 10 / 11 x64
• ffmpeg.exe on PATH or in build\ (for Whisper audio extraction)
• Runtime DLLs in build\:

DLL	Source
SDL2.dll	SDL2 release page (MinGW)
SDL2_ttf.dll	SDL2_ttf-devel-2.0.12-VC
libfreetype-6.dll	Bundled with SDL2_ttf-devel-2.0.12-VC
zlib1.dll	Bundled with SDL2_ttf-devel-2.0.12-VC
avcodec-62.dll	FFmpeg shared build
avdevice-62.dll	FFmpeg shared build
avfilter-11.dll	FFmpeg shared build
avformat-62.dll	FFmpeg shared build
avutil-60.dll	FFmpeg shared build
swresample-6.dll	FFmpeg shared build
swscale-9.dll	FFmpeg shared build

Optional — Whisper DLLs (only needed for caption generation):

DLL	Source
whisper.dll	whisper-bin-x64.zip
ggml.dll	whisper-bin-x64.zip
ggml-base.dll	whisper-bin-x64.zip
ggml-cpu.dll	whisper-bin-x64.zip

• GNAT Community 2021 (build-time only)

---

🚀 Usage

build\blackvideo-player.exe "C:\path\to\video.mp4"

Generate captions after opening:

1. Right-click anywhere on the video
2. Click Generate Captions (Whisper) or Translate to English (Whisper)
3. Wait for the status banner to clear — subtitle is auto-loaded into Track 1

---

📁 New Files in This Release

File	Purpose
src/srt_parser.ads/.adb	SRT subtitle parser (BOM, CRLF, multi-line, up to 4 096 cues)
src/whisper_bridge.ads/.adb	Whisper.cpp offline caption bridge (no whisper.h at build time)
.env.example	Template for dev path overrides — rename to .env
WHISPER_SETUP.md	Full Whisper setup guide, model upgrade table, troubleshooting

---

Built with Ada 2012 · FFmpeg 8.x · SDL2 · SDL2_ttf · whisper.cpp · GNAT Community 2021

Full Changelog: v2.2.0...v2.3.0

---

This discussion was created from the release BlackVideo Mini Player v2.3.0 — Offline Captions (Whisper), Subtitle Rendering & Track Fix.