Skip to content

AstraeLabs/VibraVid

BranchesTags

Repository files navigation

PyPI Version Sponsor

Windows macOS Linux

⚡ Quick Start: pip install VibraVid && VibraVid

📖 Table of Contents

Installation

Manual Clone

git clone https://github.com/AstraeLabs/VibraVid.git
cd VibraVid
pip install -r requirements.txt
python manual.py

Update

python update.py

Additional Documentation

  • 📝 Login Guide - Authentication for supported services

Quick Start

# If installed via PyPI
VibraVid

# If cloned manually
python manual.py

Downloaders

Type Description Example
HLS HTTP Live Streaming (m3u8) View example
MP4 Direct MP4 download View example
DASH MPEG-DASH with DRM bypass* View example

*DASH with DRM bypass: Requires a valid L3 CDM (Content Decryption Module). This project does not provide or facilitate obtaining CDMs. Users must ensure compliance with applicable laws.

Configuration

Key configuration parameters in config.json:

Output Directories

{
	"OUTPUT": {
		"root_path": "Video",
		"movie_folder_name": "Movie",
		"serie_folder_name": "Serie",
		"anime_folder_name": "Anime",
		"movie_format": "%(title_name) (%(title_year))/%(title_name) (%(title_year))",
		"episode_format": "%(series_name)/S%(season:02d)/%(episode_name) S%(season:02d)E%(episode:02d)"
	}
}

  • root_path: Base directory where videos are saved

    • Windows: C:\\MyLibrary\\Folder or \\\\MyServer\\Share
    • Linux/MacOS: Desktop/MyLibrary/Folder

  • movie_folder_name: Subfolder name for movies (default: "Movie")

    • Supports %{site_name} placeholder: "Movie/%{site_name}" → "Movie/Crunchyroll"
    • Example with year: "Movie (%{site_name})"

  • serie_folder_name: Subfolder name for TV series (default: "Serie")

    • Supports %{site_name} placeholder: "Serie/%{site_name}" → "Serie/Crunchyroll"
    • Example with year: "Series by %{site_name}"

  • anime_folder_name: Subfolder name for anime (default: "Anime")

    • Supports %{site_name} placeholder: "Anime/%{site_name}" → "Anime/Crunchyroll"

Movie Format Configuration

Default format: "%(title_name) (%(title_year))/%(title_name) (%(title_year))"

Results in:

%(title_name) (%(title_year))/  → Movie folder  (Inception (2010))
%(title_name) (%(title_year))   → Filename      (Inception (2010).mkv)

Format variables:

  • %(title_name): Movie title
  • %(title_name_slug): Movie title as slug
  • %(title_year): Movie release year (optional, removed if not available)
  • %(quality): Video resolution
  • %(language): Audio languages
  • %(video_codec): Video codec
  • %(audio_codec): Audio codec

Episode Format Configuration

Default format: "%(series_name)/S%(season:02d)/%(episode_name) S%(season:02d)E%(episode:02d)"

Results in:

%(series_name)/      → Series folder  (Breaking Bad)
S%(season:02d)/      → Season folder  (S01, S02, ...)
%(episode_name)...   → Filename       (Pilot S01E05.mkv)

Format variables:

  • %(series_name): Series name
  • %(series_name_slug): Series name as slug
  • %(series_year): Series release year
  • %(season:FORMAT): Season number — padding controlled inline (see table below)
  • %(episode:FORMAT): Episode number — padding controlled inline (see table below)
  • %(episode_name): Episode title (sanitized)
  • %(episode_name_slug): Episode title as slug
  • %(quality): Video resolution
  • %(language): Audio languages
  • %(video_codec): Video codec
  • %(audio_codec): Audio codec

Inline Padding Syntax:

Token Result (n=1) Description
%(season:02d) 01 Zero-pad to 2 digits
%(season:03d) 001 Zero-pad to 3 digits
%(season:d) 1 No padding

Note: The legacy add_siteName option has been removed. Use %{site_name} placeholder in folder names instead:

"movie_folder_name": "Movie/%{site_name}",
"serie_folder_name": "Serie/%{site_name}"

Download Settings

{
	"DOWNLOAD": {
		"thread_count": 12,
		"retry_count": 40,
		"concurrent_download": true,
		"max_speed": "30MB",
		"select_video": "1920",
		"select_audio": "ita|Ita",
		"select_subtitle": "ita|eng|Ita|Eng",
		"cleanup_tmp_folder": true
	}
}

Performance Settings

  • skip_download: Skip the download step and process existing files (default: false)
  • thread_count: Number of parallel download threads (default: 12)
  • retry_count: Maximum retry attempts for failed segments (default: 40)
  • concurrent_download: Enable parallel download queue for films and series episodes (default: true). When true, downloads are queued and processed by a thread pool with a live Download Monitor table. When false, downloads run sequentially. When only one item is in the queue, it will download immediately regardless of this setting.
  • max_speed: Speed limit per stream (e.g., "30MB", "10MB")
  • cleanup_tmp_folder: Remove temporary files after download (default: true)

Stream Selection Filters

Control which streams are downloaded using select_video, select_audio, and select_subtitle:

Video Filter Syntax (select_video):

Format Description
"best" Best available resolution
"worst" Worst available resolution
"1080" Exact height (fallback to worst if not found)
"1080,H265" Height + codec constraint
`"1080 best"`
`"1080 best,H265"`
"false" Skip video (download)

Audio Filter Syntax (select_audio):

Format Description Behavior if not found
"best" Best available bitrate per language Selects best across all languages
"worst" Worst available bitrate per language Selects worst across all languages
"all" All audio tracks Downloads all
"default" Only streams marked as default DROP if no default stream exists
"non-default" Only streams NOT marked as default DROP if no non-default streams exist
"ita" Find Italian audio DROP (no download)
"ita" + other language tokens Find specified languages (pipe-separated) DROP if none found
"ita,MP4A" Find Italian + MP4A codec DROP if combination not found
"false" Skip audio Does not download

Subtitle Filter Syntax (select_subtitle):

Format Description
"all" All subtitles
"default" Only streams marked as default
"non-default" Only streams NOT marked as default
`"ita eng"`
"ita_forced" Language with flag (forced/cc/sdh)
`"ita_forced eng_cc"`
"false" Skip subtitles

Processing Settings

{
	"PROCESS": {
		"generate_nfo": false,
		"use_gpu": false,
		"param_video": ["-c:v", "libx265", "-crf", "28", "-preset", "medium"],
		"param_audio": ["-c:a", "libopus", "-b:a", "128k"],
		"param_final": ["-c", "copy"],
		"audio_order": ["ita", "eng"],
		"subtitle_order": ["ita", "eng"],
		"merge_audio": true,
		"merge_subtitle": true,
		"subtitle_disposition_language": "ita_forced",
		"extension": "mkv"
	}
}
  • generate_nfo: Generate .nfo metadata file alongside the video (default: false)
  • use_gpu: Enable hardware acceleration (default: false)
  • param_video: FFmpeg video encoding parameters
    • Example: ["-c:v", "libx265", "-crf", "28", "-preset", "medium"] (H.265/HEVC encoding)
  • param_audio: FFmpeg audio encoding parameters
    • Example: ["-c:a", "libopus", "-b:a", "128k"] (Opus audio at 128kbps)
  • param_final: Final FFmpeg parameters (default: ["-c", "copy"] for stream copy)
  • audio_order: List of strings to order audio tracks (e.g., ["ita", "eng"])
  • subtitle_order: List of strings to order subtitle tracks (e.g., ["ita", "eng"])
  • merge_audio: Merge all audio tracks into a single output file (default: true)
  • merge_subtitle: Merge all subtitle tracks into a single output file (default: true)
  • subtitle_disposition_language: Mark a specific subtitle as default/forced
  • force_subtitle: How subtitles are handled before remuxing
    • "auto" (default): subtitles are renamed/converted according to their detected format; VTT files are also sanitized (unmatched < replaced) to avoid data loss when muxed as SRT.
    • "copy": do not convert or rename, just mux the original file as-is (useful if you want to preserve VTT output). This also skips the VTT sanitization step, so any problematic < characters remain untouched.
    • "srt", "vtt", "ass": force-convert all subtitle tracks to the specified format using ffmpeg, applying sanitization for vtt as needed.
    • See VibraVid/core/processors/helper/ex_sub.py for conversion logic.
  • extension: Output file format ("mkv" or "mp4")

Request Settings

{
	"REQUESTS": {
		"timeout": 30,
		"max_retry": 10,
		"use_proxy": false,
		"proxy": {
			"http": "http://localhost:8888",
			"https": "http://localhost:8888"
		}
	}
}
  • timeout: Request timeout in seconds (default: 30)
  • max_retry: Maximum retry attempts for failed requests (default: 10)
  • use_proxy: Enable proxy support for HTTP requests (default: false)
  • proxy: Proxy configuration for HTTP and HTTPS connections
    • http: HTTP proxy URL (e.g., "http://localhost:8888")
    • https: HTTPS proxy URL (e.g., "http://localhost:8888")

Default Settings

{
	"DEFAULT": {
		"close_console": true,
		"show_message": false,
		"fetch_domain_online": true,
		"auto_update_check": true
	}
}
  • close_console: Automatically close console after download completion (default: true)
  • show_message: Display debug messages (default: false)
  • fetch_domain_online: Automatically fetch latest domains from GitHub (default: true)
  • auto_update_check: Check for new VibraVid updates automatically at startup (default: true). If enabled, notifies you when a new version is available.

Usage Examples

Basic Commands

# Show help and available sites
python manual.py -h

# Search and download
python manual.py --site streamingcommunity --search "interstellar"

# Auto-download first result
python manual.py --site streamingcommunity --search "interstellar" --auto-first

# Use site by index
python manual.py --site 0 --search "interstellar"

Global Search

Search across multiple streaming sites simultaneously:

# Global search
python manual.py --global -s "cars"

# Search by category
python manual.py --category 1    # Anime
python manual.py --category 2    # Movies & Series
python manual.py --category 3    # Series only

Results display title, media type, and source site in a consolidated table.

Advanced Features

Hook System

Execute custom scripts before/after downloads. Configure in config.json:

{
	"HOOKS": {
		"pre_run": [
			{
				"name": "prepare-env",
				"type": "python",
				"path": "scripts/prepare.py",
				"args": ["--clean"],
				"env": { "MY_FLAG": "1" },
				"cwd": "~",
				"os": ["linux", "darwin"],
				"timeout": 60,
				"enabled": true,
				"continue_on_error": true
			}
		],
		"post_download": [
			{
				"name": "post-download-env",
				"type": "python",
				"path": "/app/script.py",
				"args": ["{download_path}"],
				"env": {
					"MY_FLAG": "1"
				},
				"cwd": "~",
				"os": ["linux"],
				"timeout": 60,
				"enabled": true,
				"continue_on_error": true
			}
		],
		"post_run": [
			{
				"name": "notify",
				"type": "bash",
				"command": "echo 'Download completed'"
			}
		]
	}
}

Hook Configuration Options

  • Stages available: pre_run, post_download, post_run
  • name: Descriptive name for the hook
  • type: Script type - python, bash, sh, shell, bat, cmd
  • path: Path to script file (alternative to command)
  • command: Inline command to execute (alternative to path)
  • args: List of arguments passed to the script
  • env: Additional environment variables as key-value pairs
  • cwd: Working directory for script execution (supports ~ and environment variables)
  • os: Optional OS filter - ["windows"], ["darwin"] (macOS), ["linux"], or combinations
  • timeout: Maximum execution time in seconds (hook fails if exceeded)
  • enabled: Enable/disable the hook without removing configuration
  • continue_on_error: If false, stops execution when hook fails

Hook Types

  • Python hooks: Run with current Python interpreter
  • Bash/sh/shell hooks: All three types execute via /bin/bash -c on macOS/Linux
  • Bat/cmd/shell hooks: Execute via cmd /c on Windows
  • Inline commands: Use command instead of path for simple one-liners. Note: args are ignored when using command; they only apply when using path.

Hook Context Placeholders

Hooks can interpolate download context in path, command, args, env, and cwd.

  • {download_path}: Absolute path of the downloaded file
  • {download_dir}: Directory containing the downloaded file
  • {download_filename}: Filename of the downloaded file
  • {download_id}: Internal download identifier
  • {download_title}: Download title
  • {download_site}: Source site name
  • {download_media_type}: Media type
  • {download_status}: Final download status
  • {download_error}: Error message, if present
  • {download_success}: 1 on success, 0 on failure
  • {stage}: Current hook stage

The same values are also exposed as environment variables with the SC_ prefix, such as SC_DOWNLOAD_PATH, SC_DOWNLOAD_FILENAME, SC_DOWNLOAD_SUCCESS, and SC_HOOK_STAGE.

Hooks are automatically executed before the main flow (pre_run), after each completed download (post_download), and at the end of the main execution flow (post_run). In the GUI, post_download runs for every individual completed item, while post_run is triggered once when the overall execution ends.

Docker

Recommended: Docker Compose (Production Ready)

Use docker-compose.yml for best results with persistent data:

# Start the container
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container (data persists)
docker-compose down

# Restart the container
docker-compose up -d

Private Network Deployment

For deployments with a custom domain and private IP (e.g., LAN streaming):

Edit docker-compose.yml and uncomment the environment section, then update:

environment:
  DJANGO_DEBUG: "false"
  ALLOWED_HOSTS: "streaming.example.local,localhost,127.0.0.1,192.168.1.50"
  CSRF_TRUSTED_ORIGINS: "https://streaming.example.local"
  USE_X_FORWARDED_HOST: "true"
  SECURE_PROXY_SSL_HEADER_ENABLED: "true"
  CSRF_COOKIE_SECURE: "true"
  SESSION_COOKIE_SECURE: "true"
  DJANGO_SECRET_KEY: "your-secure-secret-key-here"

Replace the domain and IP with your actual values.

Manual Docker Build & Run

If you prefer not to use docker-compose:

# Build image
docker build -t vibravid .

# Run with persistent volumes (recommended)
docker run -d \
  --name vibravid \
  -p 8000:8000 \
  -v vibravid_db:/app/GUI \
  -v vibravid_videos:/app/Video \
  -v vibravid_logs:/app/logs \
  -v vibravid_config:/app/Conf \
  --restart unless-stopped \
  vibravid

Binding Local Folders

To save downloads to a specific folder on your host machine:

# Linux/macOS
docker run -d --name vibravid -p 8000:8000 \
  -v ~/Downloads/Videos:/app/Video \
  vibravid

# Windows (PowerShell)
docker run -d --name vibravid -p 8000:8000 `
  -v "D:\Video:/app/Video" `
  vibravid

Note: Path separators differ by OS. Use / for Linux/macOS and \ for Windows paths.

Related Projects

  • MammaMia - Stremio addon for Italian streaming (by UrloMythus)
  • Unit3Dup - Torrent automation for Unit3D tracker (by 31December99)
  • N_m3u8DL-RE - Universal downloader for HLS/DASH/ISM (by nilaoda)
  • pywidevine - Widevine L3 decryption library (by devine-dl)
  • pyplayready - PlayReady decryption library (by ready-dl)

Disclaimer

This software is for educational and research purposes only. The authors:

  • DO NOT assume responsibility for illegal use
  • DO NOT provide or facilitate DRM circumvention tools, CDMs, or decryption keys
  • DO NOT endorse piracy or copyright infringement

By using this software, you agree to comply with all laws and have rights to any content you process. No warranty is provided. If you do not agree, do not use this software.

**Made with ❤️ for streaming lovers** *If you find this project useful, consider starring it! ⭐**

About

Downloader for Movie, TV Series and anime.

discord.com/invite/8vV68UGRc7

Topics

python cli gui downloader mpd hls m3u8 dash drm widevine playready hls-downloader mega-downloader widevine-drm mp4-downloader streamingcommunity drm-removal playready-drm streamingunity

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

1k stars

Watchers

11 watching

Forks

131 forks
Report repository

Releases 12

v1.1.2 Latest
Mar 21, 2026
+ 11 releases

Sponsor this project

Packages

 
 
 

Contributors

Languages