Skip to content

Whisper Subtitles Plugin v3.0.0#3

Merged
zakattack02 merged 87 commits into
masterfrom
feature/jellyfin-plugin
May 28, 2026
Merged

Whisper Subtitles Plugin v3.0.0#3
zakattack02 merged 87 commits into
masterfrom
feature/jellyfin-plugin

Conversation

@zakattack02
Copy link
Copy Markdown
Owner

@zakattack02 zakattack02 commented May 28, 2026

Complete rewrite: Original Jellyfin Template → Functional Subtitle Plugin

This PR transforms the original Jellyfin plugin template into a fully functional Whisper.cpp subtitle generation plugin for Jellyfin.

Key Features

  • Subtitle generation via whisper.cpp with multiple model sizes (tiny→large)
  • Automatic audio extraction from video files using FFmpeg
  • Chunked processing — splits audio >30min into segments to avoid OOM on low-RAM servers (4 GB tested)
  • Dual binary support — builds CPU-only (4 MB) and CUDA (1.1 GB) binaries; auto-selects based on GPU availability
  • Per-video progress reporting in the scheduled task UI
  • FFprobe auto-detection with configurable fallback path
  • GPU support via -dev 0 flag (whisper-cli target, not -ngl)
  • AVX-512 safety — binary built with GGML_NATIVE=OFF to prevent SIGILL on older CPUs (Haswell/Xeon E5-2660 v3)
  • GLIBC compatibility — Docker-based build for broad Linux compatibility
  • Security hardening — language arg quoting, temp file cleanup, process timeouts, null guards

v3.0.0 Changes (latest)

  • Version restructuring: v0.0.0.91–v0.0.0.98 remapped to semantic versions v1.0.0.0–v3.0.0.0
  • Complete README rewrite with installation, configuration, GPU setup, troubleshooting, and build-from-source guide
  • CI/CD: GitHub Actions test workflow (builds on PR/push to master)
  • Project config: .editorconfig, .vscode/settings.json, MIT LICENSE, .gitignore cleanup
  • Removed obsolete: setup.sh, batch_generate.py, download_models.py, tracked whisper.cpp source (940 MB kept on disk)
  • Branch protection ruleset added at .github/rulesets/main.json

Technical Details

  • Binary: ssh-keygen built via multi-stage Dockerfile, targets whisper-cli (not the main example)
  • Flags: Uses -ng (CPU), -dev N (GPU), -of, -ot, -l — NOT --output-dir, -vv, or -ngl N (unsupported in whisper-cli)
  • CUDA: .so files bundled from build container; LD_LIBRARY_PATH set at launch
  • Target server: Xeon E5-2660 v3, 4 GB RAM, 12 threads, NVIDIA GPU

Zak Konik and others added 30 commits November 9, 2025 22:04
- Add WhisperSubtitles controller with model download and binary installation endpoints
- Implement WhisperService and WhisperBinaryManager for binary/model management
- Add GPU detection (CUDA, Vulkan, Metal)
- Implement configuration page with UI controls
- Add comprehensive error handling and logging
- Properly implement IDisposable pattern for resource cleanup
- Add 30-minute timeout for large downloads
- Improve reflection-based method invocation with better error handling
- Restored WhisperSubtitlesController with binary installation and model download endpoints
- Restored WhisperService with proper resource disposal
- Restored WhisperBinaryManager with GPU detection
- Added PluginConfiguration with all user-configurable options
- Added Plugin.cs entry point
- Restored configuration page HTML with UI controls
- Added Directory.Build.props for version management
- Added WhisperSubtitleTask scheduled task for batch subtitle generation
- Added WhisperPostScanTask for automatic post-scan processing
- Added SubtitleDetectionService for subtitle file management
- Added ISubtitleDetectionService interface
- Added Jellyfin.Plugin.WhisperSubtitles.csproj with proper dependencies and build configuration
- Configured Jellyfin 10.11.2 SDK references
- Added Whisper.net library with runtime support
- Configured embedded resources (config page HTML, logo)
- Added post-publish target to remove non-Linux runtime libraries
Co-authored-by: Copilot <copilot@github.com>
- Removed the binary installation button from the configuration page and added instructions for manual binary setup.
- Improved library loading logic to handle both direct array and .Items wrapper responses.
- Enhanced error handling and logging for library loading and binary deployment.
- Updated the binary manager to extract the bundled whisper-cli binary from the plugin directory to the cache.
- Refactored command argument building for the whisper.cpp process to improve readability and maintainability.
- Filtered video items based on enabled libraries from configuration.
- Updated version numbers in various project files to reflect the new release version.

Co-authored-by: Copilot <copilot@github.com>
…y filtering logic

Co-authored-by: Copilot <copilot@github.com>
Removed version 0.0.0.58 entry from manifest.
…itles plugin

- Introduced .NET 9.0 assembly attributes and updated project files.
- Generated assembly info and global usings for the plugin.
- Updated dependencies and added new assets for the plugin.
- Released new plugin versions: 0.0.0.58, 0.0.0.59, and 0.0.0.60.
Zak Konik added 21 commits May 27, 2026 15:51
…-output-dir and -vv flags, added -ng for CPU-only mode
…ke so binary doesn't include AVX-512 instructions from build machine (Ryzen 9950X3D)
… doesn't support -ngl). CPU path already fixed in 0.0.0.92/93.
…OOM killer on low-RAM servers (4GB). Process each chunk separately and merge SRTs.
…ndling

- Introduced chunking for audio files to manage memory usage, processing audio in 30-minute segments.
- Added methods for running the whisper CLI and getting WAV duration.
- Enhanced logging for better debugging and tracking of subtitle generation.
- Updated dependencies and versioning to 0.0.0.95.
- Cleaned up temporary files after processing.
- Adjusted build scripts for compatibility with new configurations.
…nfig field + FindFfprobe() fallback chain + configPage.html input.
…sk now reports progress as each chunk finishes, so the percentage bar updates smoothly instead of freezing per video.
…e now builds both whisper-whisper-cli (CPU) and whisper-whisper-cli-cuda (CUDA) + bundles libcudart/libcublas. Plugin auto-selects CUDA binary when GPU is enabled and cuda binary is deployed.
- Renumber releases by content (v0.0.0.91→1.0.0.0, v0.0.0.95→2.0.0.0, v0.0.0.98→3.0.0.0)
- Trim manifest to 8 meaningful versions (remove v0.0.0.1–v0.0.0.90)
- Update make-release.sh: dirty-tree check, SHA256, CUDA split, atomic push, dry-run
- Version 3.0.0.0 (CUDA milestone)
- C1: Quote -l language arg to prevent flag injection
- D1/H2: Delete temp WAV file in finally block
- D3: Return empty list on split failure instead of passing full WAV
- D4: Push tag only after successful GitHub release creation
- D11: Don't pass -dev 0 GPU flag when falling back to CPU binary
- M6: Add 60-min timeout for whisper-cli, 30-min for ffmpeg, 30-sec for ffprobe
- D6: Wrap Directory.GetFiles in try/catch
- Add .github/rulesets/main.json for branch protection
- Full rewrite covering all features, installation methods, configuration, GPU acceleration, troubleshooting, build from source, and version history
- Add branch protection rulesets at .github/rulesets/main.json
setup.sh was for the old openai-whisper Python approach. The project
is now a Jellyfin C# plugin using whisper.cpp — completely unrelated.
batch_generate.py and download_models.py were for the old
openai-whisper Python approach. The project is now a Jellyfin
C# plugin using whisper.cpp.
- Added support for progress reporting during subtitle generation in WhisperPostScanTask and WhisperSubtitleTask.
- Updated dependencies and versioning in project files to reflect the new version 3.0.0.
- Enhanced Docker build process for better handling of CPU and CUDA binaries.
- Removed obsolete Linux x64 binaries from the output.
- Improved error handling and logging for better debugging.
@zakattack02 zakattack02 marked this pull request as draft May 28, 2026 02:52
@zakattack02 zakattack02 marked this pull request as ready for review May 28, 2026 02:52
@zakattack02 zakattack02 marked this pull request as draft May 28, 2026 02:57
@zakattack02 zakattack02 marked this pull request as ready for review May 28, 2026 02:57
@zakattack02 zakattack02 marked this pull request as draft May 28, 2026 02:58
@zakattack02 zakattack02 marked this pull request as ready for review May 28, 2026 02:58
@zakattack02 zakattack02 self-assigned this May 28, 2026
@zakattack02 zakattack02 merged commit 207396f into master May 28, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant