• Installation
• Quick Start
• Update
• Login
• Downloaders
• Configuration
• Usage Examples
• Global Search
• Advanced Features
• ARR Integration
• Docker
• Gui
• Known Issues
• Related Projects

git clone https://github.com/AstraeLabs/VibraVid.git
cd VibraVid

Then install and run with either pip or uv:

pip:

pip install -r requirements.txt   # install
python manual.py                  # run
pip install -r requirements.txt --upgrade  # sync deps

uv:

uv sync              # install
uv run manual.py     # run
uv sync --upgrade    # sync deps

You can find the app in the Community Application

Once you have installed Termux, open the app, copy the command below, paste it into the terminal, and press Enter to run the automatic installation (it will download VibraVid, compile all necessary components including Velora, and configure the storage folder):

curl -sL https://raw.githubusercontent.com/ManoloZocco/StreamingCommunity/main/termux_install.sh | bash

Once the installation is complete, you can launch the app at any time by simply typing:

vibravid

• 📝 Login Guide — Authentication for supported services
• 🖥️ NAS Deployment Guide — Docker setup on Synology, TrueNAS, and other NAS devices

python manual.py

VibraVid -UP

git fetch origin
git reset --hard origin/main

Then sync dependencies:

pip:

pip install -r requirements.txt --upgrade

uv:

uv sync --upgrade

If the folder is not yet an initialized Git repository:

git init
git remote add origin https://github.com/AstraeLabs/VibraVid.git
git fetch origin
git reset --hard origin/main

⚠️ Folders ignored by .gitignore (e.g. Video/) will not be deleted.

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

All settings live in config.json. The sections below cover each configuration block.

{
  "DEFAULT": {
    "debug_track_json": false,
    "log_level": "INFO",
    "close_console": true,
    "show_message": false,
    "fetch_domain_online": true,
    "auto_update_check": true,
    "imp_service": ["default"],
    "installation": "essential"
  }
}

Custom imp_service example:

"imp_service": ["default", "/home/user/my_custom_sites"]

{
  "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
• Docker / NAS: set the VIBRAVID_OUTPUT_ROOT environment variable instead of editing config.json — the value is applied at startup and overrides this field without touching the persisted config file. Example: VIBRAVID_OUTPUT_ROOT=/app/Video (container path matching the bind-mount target).

movie_folder_name, serie_folder_name, anime_folder_name — Subfolder names for each content type (defaults: "Movie", "Serie", "Anime"). All support the %{site_name} placeholder:

"Movie/%{site_name}"  →  "Movie/Crunchyroll"
"Serie/%{site_name}"  →  "Serie/Crunchyroll"

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

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

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

%(series_name)/     →  series folder   Breaking Bad/
S%(season:02d)/     →  season folder   S01/
%(episode_name)...  →  filename        Pilot S01E05.mkv

Inline padding syntax (for season and episode):

{
  "DOWNLOAD": {
    "auto_select": true,
    "delay_after_download": 1,
    "skip_download": false,
    "thread_count": 12,
    "concurrent_download": true,
    "select_video": "1920",
    "select_audio": "ita|Ita",
    "select_subtitle": "ita|eng|Ita|Eng",
    "cleanup_tmp_folder": true,
    "engine": "ffmpeg"
  }
}

Use select_video, select_audio, and select_subtitle to control which tracks are downloaded.

Video (select_video):

Audio (select_audio):

Subtitle (select_subtitle):

Companion Dolby Vision (select_video only):

Add &dv=<quality> to the video filter to also download a Dolby Vision companion alongside the main (non-DV) video. <quality> is best/worst (default worst):

The DV track is muxed as an additional video track via mkvmerge.

{
  "PROCESS": {
    "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"
  }
}

force_subtitle — Controls how subtitles are handled before remuxing:

See VibraVid/core/processors/helper/ex_sub.py for conversion logic.

{
  "REQUESTS": {
    "timeout": 30,
    "max_retry": 10,
    "use_proxy": false,
    "proxy": {
      "http": "http://localhost:8888",
      "https": "http://localhost:8888"
    }
  }
}

The ARR block enables VibraVid to work as an automation layer between Seerr/Jellyseerr, Sonarr, Radarr, and the final media library. When enabled, VibraVid polls Sonarr/Radarr for missing media, receives webhook events, downloads through its provider pipeline, and reports the resulting files back so that Sonarr/Radarr can import them.

The ARR integration requires the VibraVid web GUI to be running. All polling loops, webhook listeners, and download workers are managed by the Django application server. The CLI (vibraNid / python -m VibraVid) does not start the ARR stack.

{
  "ARR": {
    "enabled": false,
    "enable_polling": false,
    "enable_seerr_webhook": false,
    "enable_sonarr_webhook": false,
    "enable_radarr_webhook": false,
    "polling_interval": 300,
    "full_resync_interval": 21600,
    "max_concurrent_downloads": 1,
    "webhook_priority_enabled": true,
    "native_webhook_priority_window_seconds": 120,
    "seerr_fallback_delay_seconds": 20,
    "download_italian_anime_default": true,
    "provider_fallback": ["streamingcommunity", "animeunity"],
    "path_mapping": {},
    "sonarr": { "url": "", "api_key": "" },
    "radarr": { "url": "", "api_key": "" },
    "seerr": { "webhook_secret": "" },
    "sonarr_webhook": { "webhook_secret": "" },
    "radarr_webhook": { "webhook_secret": "" }
  }
}

All ARR settings can also be edited directly from the VibraVid web GUI under Settings → Configuration editor, without touching config.json manually.

These keys can also be set via environment variables (useful in Docker):

USE_ARR_SERVICES=true
SONARR_URL=http://sonarr:8989
SONARR_API_KEY=your-key
RADARR_URL=http://radarr:7878
RADARR_API_KEY=your-key
SEERR_WEBHOOK_SECRET=your-secret
SONARR_WEBHOOK_SECRET=your-secret
RADARR_WEBHOOK_SECRET=your-secret

VibraVid exposes one webhook endpoint per ARR application. Add one connection only per app — adding multiple webhooks for the same app causes duplicate processing.

Radarr → Settings → Connect → Webhook

Sonarr → Settings → Connect → Webhook

Then enable in config.json:

"enable_sonarr_webhook": true,
"enable_radarr_webhook": true

Webhooks and polling can be used together: webhooks trigger an immediate download when media is added, polling acts as a safety net for items that arrive without a webhook event.

VibraVid determines which provider to use for each item through two mechanisms — you can use one or both.

Method 1 — Per-item tag (advanced, requires tagging each title)

Add a tag directly to the movie or series in Sonarr/Radarr using the format provider-<site>. VibraVid reads the tag at download time and uses that provider regardless of the fallback list. This is useful when specific titles are only available on a particular service.

Tags are created in Sonarr/Radarr under Settings → Tags, then assigned to individual series or movies from their edit page.

Method 2 — Global fallback list (recommended, zero per-title configuration)

Configure provider_fallback with an ordered list of providers. VibraVid tries them in sequence and stops at the first that finds a matching title. No tagging required — add as many providers as you want as safety nets.

Recommended full configuration (covers general content, anime, and niche services):

"provider_fallback": [
    "streamingcommunity",
    "animeunity",
    "discoveryplus",
    "discovery",
    "dmax",
    "nove",
    "realtime",
    "mediasetinfinity",
    "raiplay",
    "homegardentv",
    "foodnetwork",
    "animeworld",
    "crunchyroll",
    "primevideo",
    "tubitv",
    "cinezo",
    "mostraguarda"
]

If provider_fallback is empty or omitted, VibraVid tries streamingcommunity only and fails if the title is not found there.

Italian dub preference (download_italian_anime_default)

When true, if the selected provider returns both an original-language version and an (ITA) dubbed version of the same title, VibraVid automatically picks the Italian dub. This applies regardless of which method selected the provider.

"download_italian_anime_default": true

path_mapping is one of the most important settings when Radarr/Sonarr run in Docker while VibraVid runs on the host (or vice versa). After a download completes, VibraVid must tell Radarr/Sonarr exactly where the file is so they can import it. If the two services see the same physical folder under different paths, Radarr/Sonarr will receive a path they cannot resolve and the import will fail.

Example: VibraVid on the host sees /media/Media/Film. Radarr's Docker Compose mounts the same folder at a different path:

volumes:
  - /media/Media/Film:/media/Film
  - /media/Media/Anime:/media/Anime
  - /media/Media/Series:/media/Series

Without path_mapping, VibraVid reports /media/Media/Film/my-movie to Radarr. Radarr looks for that path inside its container — it does not exist there — and the import fails. With the mapping configured, VibraVid automatically translates the path before every API call:

"path_mapping": {
    "/media/Media/Film":   "/media/Film",
    "/media/Media/Anime":  "/media/Anime",
    "/media/Media/Series": "/media/Series"
}

Each key is a prefix as seen by VibraVid; the value is the equivalent prefix inside the Radarr/Sonarr container. Entries are checked in order and the first matching prefix is replaced. Leave path_mapping as {} when both services share the same filesystem view.

{
  "DRM": {
    "use_cdm": true,
    "prefer_remote_cdm": true,
    "vault": {
      "supa": {
        "url": "https://crqczuxpqjmrjvdvqvlx.supabase.co",
        "token": ""
      }
    }
  }
}

When remote CDM services are available, add one or both of the following blocks to config.json:

Widevine:

"widevine": {
  "device_type": "ANDROID",
  "system_id": 22590,
  "security_level": 3,
  "host": "https://cdrm-project.com/remotecdm/widevine",
  "secret": "CDRM",
  "device_name": "public"
}

PlayReady:

"playready": {
  "device_name": "public",
  "security_level": 3000,
  "host": "https://cdrm-project.com/remotecdm/playready",
  "secret": "CDRM"
}

To use local CDM device files instead of remote services, place them in the binary directory resolved at runtime:

• Default on Linux: ~/.local/bin/binary

• Override with VIBRAVID_BINARY_DIR if you need a different path, for example /home/user_name/.local/bin/binary

• Widevine: .wvd file (from pywidevine)

• PlayReady: .prd file (from pyplayready)

Set prefer_remote_cdm to false and local devices will be picked up automatically.

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

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

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

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

Use --season and --episode to skip interactive prompts:

# Specific episode
python manual.py --site streamingcommunity --search "breaking bad" --auto-first --season 1 --episode 3

# Range of episodes
python manual.py --site streamingcommunity --search "breaking bad" --auto-first --season 1 --episode "1-5"

# All episodes of a season
python manual.py --site streamingcommunity --search "breaking bad" --auto-first --season 1 --episode "*"

# All episodes of all seasons
python manual.py --site streamingcommunity --search "breaking bad" --auto-first --season "*"

# Multiple seasons
python manual.py --site streamingcommunity --search "breaking bad" --auto-first --season "1-3"

# Exact year
python manual.py --site streamingcommunity --search "dune" --year 2021

# Year range
python manual.py --site streamingcommunity --search "batman" --year "1990-2015"

# Video resolution
python manual.py --site streamingcommunity --search "interstellar" -sv 1080

# Audio language
python manual.py --site streamingcommunity --search "interstellar" -sa "eng"

# Subtitles
python manual.py --site streamingcommunity --search "interstellar" -ss "eng"

# Keep console open (loop mode)
python manual.py --close-console false

# Close console after download
python manual.py --site streamingcommunity --search "interstellar" --close-console true

python manual.py --site streamingcommunity --search "interstellar" --use_proxy

python manual.py --dep

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

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

Execute custom scripts at specific points in the download lifecycle. Hooks are configured in config.json under the HOOKS key.

Available stages:

• pre_run — runs before the main flow starts
• post_download — runs after each individual download completes (in the GUI, once per item)
• post_run — runs once when the overall execution ends

{
  "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'"
      }
    ]
  }
}

• Python: runs with the current Python interpreter
• Bash / sh / shell: executed via /bin/bash -c on macOS/Linux
• Bat / cmd / shell: executed via cmd /c on Windows
• Inline commands: use command instead of path for simple one-liners

The same values are also exposed as environment variables with the SC_ prefix (e.g. SC_DOWNLOAD_PATH, SC_DOWNLOAD_SUCCESS, SC_HOOK_STAGE).

VibraVid can be used as an automation component in a media-server stack with Seerr/Jellyseerr, Sonarr, and Radarr.

Typical flow:

Seerr / Jellyseerr
    ↓ user requests a movie or series
Sonarr / Radarr
    ↓ media is added and marked as missing
VibraVid ARR
    ↓ detects missing media through polling or webhooks
VibraVid downloader
    ↓ searches and downloads through the configured provider or through the provider selected by tag
Sonarr / Radarr
    ↓ rescans/imports the downloaded file
Media library
    ↓ Jellyfin/Plex can detect the final file

When the GUI/Django server is running, the ARR integration exposes dedicated webhook endpoints:

POST /api/arr/webhook/seerr/
POST /api/arr/webhook/sonarr/
POST /api/arr/webhook/radarr/

Each endpoint can be protected with its own webhook secret. Configure the same secret both in VibraVid and in the corresponding external service.

ARR can process media in two ways:

1. Polling — VibraVid periodically asks Sonarr/Radarr for wanted or missing media.
2. Webhooks — VibraVid reacts immediately when Seerr, Sonarr or Radarr sends an event.

Both modes can be enabled together. Native Sonarr/Radarr webhooks can be prioritized over Seerr events to reduce duplicate processing.

For series, VibraVid ARR can:

• read missing episodes from Sonarr;
• resolve series, season and episode metadata;
• download the requested episode into the expected series path;
• trigger a Sonarr rescan/import;
• verify whether the episode was imported;
• optionally mark the episode as unmonitored after successful import.

For movies, VibraVid ARR can:

• read missing movies from Radarr;
• resolve title, year and TMDB metadata;
• download the requested movie into the expected movie path;
• trigger a Radarr rescan/import;
• verify whether the movie was imported;
• optionally mark the movie as unmonitored after successful import.

Use shared volumes so VibraVid and Sonarr/Radarr see the same filesystem paths. If containers use different internal paths for the same media folder, imports may fail because Sonarr/Radarr will not find the downloaded files.

Example Docker path layout:

/media
├── movies
├── series
└── downloads

Mount the same media root into VibraVid, Sonarr and Radarr whenever possible.

docker-compose up -d        # Start
docker-compose logs -f      # View logs
docker-compose down         # Stop (data persists)

For NAS users (Synology, TrueNAS, Unraid, etc.), see docs/NAS.md for a step-by-step setup guide including bind mounts and permission configuration.

Copy the provided template and edit the values you need:

cp .env.example .env

Key variables (full list in .env.example):

NAS example — store downloads on a NAS share, expose on port 9000:

VIBRAVID_PORT=9000
VIBRAVID_VIDEO_DIR=/volume2/Movies
VIBRAVID_DB_DIR=/volume1/docker/vibravid/db
VIBRAVID_CONFIG_DIR=/volume1/docker/vibravid/conf
VIBRAVID_LOGS_DIR=/volume1/docker/vibravid/logs
ALLOWED_HOSTS=localhost,127.0.0.1,192.168.1.100
CSRF_TRUSTED_ORIGINS=http://192.168.1.100:9000

Then start normally:

docker-compose up -d

Uncomment and edit the environment section in docker-compose.yml:

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"

ARR-related variables can be added to the same environment block:

environment:
  USE_ARR_SERVICES: "true"
  SONARR_URL: "http://sonarr:8989"
  SONARR_API_KEY: "your-sonarr-api-key"
  RADARR_URL: "http://radarr:7878"
  RADARR_API_KEY: "your-radarr-api-key"
  SEERR_WEBHOOK_SECRET: "your-seerr-secret"
  SONARR_WEBHOOK_SECRET: "your-sonarr-secret"
  RADARR_WEBHOOK_SECRET: "your-radarr-secret"

docker build -t vibravid .

docker run -d \
  --name vibravid \
  -p 8000:8000 \
  -v vibravid_db:/app/data \
  -v vibravid_videos:/app/Video \
  -v vibravid_logs:/app/logs \
  -v vibravid_config:/app/Conf \
  --restart unless-stopped \
  vibravid

# 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

When a new version is released, VibraVid shows an update banner in the web UI. Click Update now to update in place.

One-click update requires the Docker socket to be mounted (it is in the default docker-compose.yml):

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

With the socket mounted, Update now drives the host Docker daemon directly: it launches a short-lived helper container that runs docker compose pull && docker compose up -d, pulling the published image (ghcr.io/astraelabs/vibravid:latest) and recreating the container. No host-side script is required.

Security note: mounting the Docker socket grants the container control of the host Docker daemon. If you'd rather not, comment out the socket volume — the button will then tell you to update manually.

Manual update (always works, socket or not):

docker compose pull
docker compose up -d

The following issues are known and are expected to be addressed in upcoming releases. They do not affect the core download functionality but may impact the user experience in specific scenarios.

Download progress not shown for some providers

For certain providers the download progress bar in the GUI may not update or may remain at 0% for the duration of the download. The download is still running in the background and will complete normally — the issue is limited to the progress display. This typically affects providers that stream through intermediate layers rather than exposing direct segment URLs.

Velora Bridge console errors (connection / rate limit)

During downloads that go through Velora Bridge you may see warnings or errors in the console such as connection timeouts, stream read failures, or retry messages. These are caused by transient network conditions, proxy rate limiting, or per-session connection limits on the provider side. Velora Bridge retries automatically and the download usually completes successfully. If errors persist, check your proxy configuration and ensure the provider is not applying a rate limit to your IP.

• 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)

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 applicable laws and confirm you have rights to any content you process. No warranty is provided.