BlackVideo Mini Player

Lightweight cross-platform video player built in Ada + SDL2 + FFmpeg. Works standalone from the command line or via right-click on any video file. Support player for the BlackVideo Tauri v2 app.

Features

🎬 Video Playback

Plays MP4, MKV, AVI, MOV, WMV, WebM, FLV, M4V, MPEG, TS and more
Hardware-accelerated SDL2 rendering with letterbox scaling — preserves aspect ratio at any window size or fullscreen
Correct frame pacing at any FPS (24, 30, 60 fps) using real elapsed-time budgeting

🔊 Audio

Full audio playback with volume control, mute, and seek flush
Supports AAC, MP3, AC3, and other common codecs via FFmpeg
2 MB ring buffer with SDL audio lock — stable for multi-hour playback without corruption or drift

🖥️ On-Screen Controls (UI Bar)

Seek bar with scrubber — click or drag to jump anywhere
Play / Pause, Previous (seek to start), Next (jump to end)
Loop toggle, Mute / Unmute, Speed selector (0.5× / 1.0× / 1.5× / 2.0×)
Fullscreen toggle, context menu button
Auto-hides after 3 seconds of mouse inactivity; reappears on any mouse movement

Open Video File
Subtitle track selector (3 slots — load any .srt, .ass, .ssa, or .vtt file per slot)
Generate Captions (Whisper) — offline AI transcription
Translate to English (Whisper) — offline AI translation

📝 Subtitles

Load up to 3 subtitle tracks from external files
Active track renders on-screen above the control bar with a shadow box for readability
Context menu always shows the active track name — no guessing whether subtitles are on or off

🎙️ Offline Caption Generation — Whisper.cpp

Generate subtitles for any video without internet or API keys using whisper.cpp (github.com)
Transcribes in the video's original language, or translates to English
Runs in the background — player stays responsive while Whisper works
Progress banner shown in the control bar; result auto-loads into Track 1 when done
Hot-swappable models: drop in ggml-base.bin, ggml-small.bin, ggml-medium.bin, or ggml-large.bin — no rebuild needed
Translation currently outputs English only. Multi-language translation target support is planned for a future version.

⌨️ Keyboard Shortcuts

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

🪟 Windows Shell Integration

Right-click installer registers "Open with BlackVideo Player" for all common video extensions
Supports: .mp4 .mkv .avi .mov .wmv .webm .flv .m4v .mpg .mpeg .ts

Usage

Method 1 — Command Line

Step 1. Unzip blackvideo-mini-player-v2.3.0.win.zip

Step 2. Open the build\ folder, then type cmd directly in the address bar and press Enter — this opens a terminal already in that folder.

Alternatively: open Command Prompt anywhere and use cd with the copied path:

cd "C:\path\to\blackvideo-mini-player\build"

Step 3. Run the player:

blackvideo-player.exe "C:\Users\You\Videos\movie.mp4"

Method 2 — Right-Click (Recommended)

Step 1. Unzip blackvideo-mini-player-v2.3.0.win.zip

Step 2. Right-click tools\context_menu\install_context_menu.bat → Run as administrator

That's it. Now:

Right-click any video file in Explorer
Click Open with BlackVideo Player
The video plays immediately

To remove the right-click entry:

tools\context_menu\uninstall_context_menu.bat

Optional: Whisper Captions Setup

To use offline caption generation, place these files in build\ beside blackvideo-player.exe:

build\
├── whisper-cli.exe
├── whisper.dll
├── ggml.dll
├── ggml-base.dll
├── ggml-cpu.dll
└── models\
    └── ggml-base.bin

Also make sure ffmpeg.exe is on your PATH (or placed in build\).
Then right-click any video → Generate Captions (Whisper).

Release History

v2.3.0 — Offline Captions, Subtitle Rendering & Track Fix

NEW Offline caption generation via whisper.cpp (Generate Captions, Translate to English)
NEW Real subtitle text rendered on-screen from loaded .srt files
NEW srt_parser — full SRT parser (BOM, CRLF, multi-line, up to 4 096 cues)
NEW .env file support for dev-mode Whisper path overrides (silently skipped in production)
FIXED Subtitle track resetting to Off after file dialog — caused by SDL queued mouse events during PowerShell dialog blocking; fixed with a 250 ms post-close guard
FIXED Context menu "Subtitle: Off" label now updates to "Subtitle: Track N" when a track is active
FIXED srt_parser: renamed Digits (Ada reserved word) to Parse_Int
FIXED whisper_bridge: renamed system import to C_System to avoid shadowing the System package
FIXED System.Address comparisons — added System.Storage_Elements to expose the = operator in GNAT 2021

v2.2.0 — Playback Controls Fix & Audio Stability

FIXED All on-screen buttons now respond to clicks — SDL_MouseButtonEvent.button was read from byte offset 13 instead of the correct offset 16
FIXED Right-click context menu now opens correctly
FIXED Audio corruption after ~50 minutes — ring buffer race condition resolved with SDL_LockAudioDevice / SDL_UnlockAudioDevice
FIXED Ring buffer increased 256 KB → 2 MB (~12 seconds) to absorb H.264 decode bursts
FIXED Overflow strategy changed to drop-incoming (was drop-oldest, causing audible clicks)
FIXED Audio.Flush now called on all 7 seek paths — stale pre-seek audio no longer bleeds through
FIXED SDL_AUDIO_ALLOW_FREQUENCY_CHANGE removed — eliminates pitch drift on long files
FIXED ui_overlay.c moved from src/ to csrc/ — was causing duplicate symbol linker errors
FIXED GPR linker flags: -lgdi32, -lusp10, -lrpcrt4 added for SDL2_ttf HarfBuzz dependencies
FIXED build.bat uses %ROOT% (quoted absolute path) — fixes silent gcc failures on paths with spaces (e.g. Vilma E. Agripo)

v1.1.0 — Audio, Video Timing, Stability & Icon

FIXED Audio now plays for all common formats — planar audio (AV_SAMPLE_FMT_FLTP / AAC) was silent; fixed by passing all planes to swr_convert
FIXED SDL_MixAudioFormat self-mix bug — stream was mixed into itself, doubling amplitude and causing clipping every callback
FIXED Video timing — frame pacing now uses elapsed-time budgeting; 24/30/60 fps plays at correct speed
FIXED Heap exhaustion crash (STORAGE_ERROR) — pre-allocated single RGB frame buffer; was leaking ~6.5 MB per frame (~390 MB/s at 60 fps)
FIXED H.264 NAL unit spam — AVPacket.stream_index offset was hardcoded wrong for FFmpeg 8.x; audio packets were misidentified as video
FIXED GNAT 2021 linker archive has no index error — C helpers compiled separately and passed as explicit .o to the linker
NEW Custom application icon — visible in Explorer, taskbar, and title bar

v1.0.0 — Initial Release

Basic video + audio playback (Ada + SDL2 + FFmpeg)
Keyboard controls: play/pause, seek, volume, mute, fullscreen, quit
CLI usage and right-click shell integration
Windows x64, Linux, macOS

Requirements (Windows)

Windows 10 / 11 x64
All required DLLs are included in the release zip

DLL	Notes
`SDL2.dll`	SDL2 runtime
`SDL2_ttf.dll`	UI font rendering
`libfreetype-6.dll`	Required by SDL2_ttf
`zlib1.dll`	Required by SDL2_ttf
`avcodec-62.dll`	FFmpeg
`avformat-62.dll`	FFmpeg
`avutil-60.dll`	FFmpeg
`swscale-9.dll`	FFmpeg
`swresample-6.dll`	FFmpeg

Optional (Whisper captions only):

File	Notes
`whisper-cli.exe`	From whisper-bin-x64.zip
`whisper.dll`	Whisper runtime
`ggml.dll`	GGML runtime
`ggml-base.dll`	GGML base
`ggml-cpu.dll`	GGML CPU backend
`models\ggml-base.bin`	Speech model (~142 MB)

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

BlackVideo Mini Player v2.4.0

Lightweight video player built with Ada, SDL2, and FFmpeg. Works standalone,
via drag-and-drop, or as a right-click context menu handler on Windows.

Download: https://sourceforge.net/projects/blackvideo-mini-player/files/latest/download
Source: https://github.com/BlackBlazent/blackvideo-mini-player
Changes: https://github.com/BlackBlazent/blackvideo-mini-player/compare/v2.3.0...v2.4.0

What's New in v2.4.0

Welcome / Standalone mode
Launch the player with no argument. Drag and drop a video onto the window
or click anywhere to open a file dialog.

Cloud LLM caption generation
Generate timed SRT subtitles via five cloud AI providers directly from the
right-click menu. API keys are entered once via a secure dialog and saved
locally — use Ctrl+V to paste your key.

Supported providers and their key sources:

Anthropic Claude — console.anthropic.com
OpenAI — platform.openai.com
Google Gemini — aistudio.google.com
DeepSeek — platform.deepseek.com
xAI Grok — console.x.ai

Sprite thumbnail preview
Hover over the seek bar to see a frame popup at that position. Thumbnails
are extracted in the background by ffmpeg and cached between sessions.

Auto-updater
Checks for new releases from the GitHub repository at startup. Shows an
update badge and download link when a newer version is available.

Whisper progress percentage
Live progress bar and percentage shown in the control bar while caption
generation is running.

Hot-load video
Open or drop a new video while another is already playing — no restart
required, audio re-initialises automatically.

Sample Files

The following SRT files were generated using the offline Whisper caption
feature included in this release (ggml-base model, English).

Test videos and results

Elon Musk's Work Ethics Will Give You Goosebumps.mp4
Language: English — SRT generated successfully
File: samples/Elon Musk's Work Ethics Will Give You Goosebumps.mp4.srt

AURORA - Cure For Me (1080p).mp4
Language: English — SRT generated successfully
File: samples/AURORA-Cure-For-Me_Media_K17df81RL9Y_001_1080p.mp4.srt

BTS - Boy With Luv (feat. Halsey) Official MV.mp4
Language: Korean — SRT not generated
Reason: The ggml-base model does not reliably transcribe Korean or
other non-Latin-script languages. Use ggml-large-v3 for Korean,
Japanese, Arabic, and similar languages. See WHISPER_SETUP.md.

Installation

Extract blackvideo-mini-player-v2.4.0.win.zip
Open the build\ folder
Run blackvideo-player.exe

To add a right-click "Open with BlackVideo Player" entry for video files,
run the following as Administrator:

tools\context_menu\install_context_menu.bat

Supported file types: .mp4 .mkv .avi .mov .wmv .webm .flv .m4v .mpg .mpeg .ts

To remove the context menu entry:

tools\context_menu\uninstall_context_menu.bat

Requirements

Windows 10 or 11 (64-bit)
All DLLs in build\ must remain beside blackvideo-player.exe
ffmpeg.exe on PATH or in build\ for thumbnail generation and Whisper
audio extraction

For offline captions (Whisper):
Place whisper-cli.exe, ggml.dll, ggml-base.dll, ggml-cpu.dll,
whisper.dll, and ggml-base.bin inside build\ as described in
WHISPER_SETUP.md.

For cloud LLM captions:
An API key from any supported provider. Keys are stored locally in
%APPDATA%\BlackVideo\keys.cfg and sent only to the provider's own
API endpoint.

Files in This Release

blackvideo-mini-player-v2.4.0.win.zip Player binary, DLLs, context menu tools
prerequisites-setup.zip Pre-assembled lib\ and build\ for source builds
RELEASE_NOTES.md This file
WHISPER_SETUP.md Whisper setup and model upgrade guide
samples/ Example SRT files generated by Whisper

Known Limitations

Subtitle rendering supports SRT only. ASS, SSA, and VTT files load but
display without styling.
Playback speed control cycles through values (0.5x, 1.0x, 1.5x, 2.0x)
but speed change is not yet applied to the decoder pipeline.
Whisper translation always outputs English regardless of source language.
The ggml-base model produces unreliable results for Korean, Japanese,
Arabic, and other non-Latin-script languages. Use ggml-large-v3 for
those languages.

License

MIT — https://github.com/BlackBlazent/blackvideo-mini-player/blob/main/LICENSE

blackvideo-mini-player BlackVideo-mini-player Wiki

A standalone lightweight auxiliary CLI video player for BlackVideo.

Home

Project Members:

Discussion