Skip to content
Closed
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 29 additions & 4 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -49,10 +49,11 @@ TORRENTIO_API_BASE_URL=https://torrentio.strem.fun

# ── Stream Provider ───────────────────────────────────────────────
# Which addon to use for stream listings and resolution.
# torrentio → Torrentio only (default, backward-compatible)
# comet → Comet primary, Torrentio fallback
# auto → Comet if COMET_URL is set, else Torrentio; Comet first
# with Torrentio fallback when both are configured
# torrentio → Torrentio only (default, backward-compatible)
# comet → Comet primary, Torrentio fallback
# aiostreams → AIOStreams primary, Torrentio fallback
# auto → AIOStreams (if configured), Comet (if configured),
# then Torrentio
# Self-host Comet for maximum stability (no Cloudflare blocks, no rate
# limits, no peak-hour congestion). See proxy/comet/ for docker setup.
STREAM_PROVIDER=torrentio
Expand All @@ -62,6 +63,15 @@ STREAM_PROVIDER=torrentio
# Leave blank to disable Comet.
# COMET_URL=http://100.x.x.x:8000

# AIOStreams addon URL. Use the install/manifest link generated by your
# instance (the part ending in /manifest.json is optional), for example:
# https://aiostreams.example.com/stremio/<uuid>
# AIOStreams owns its source/debrid configuration, so no key is needed here.
# AIOSTREAMS_URL=https://aiostreams.example.com/stremio/<uuid>

# Forward proxy for AIOStreams requests. Leave commented to connect directly.
# AIOSTREAMS_PROXY=http://<vps-ip>:8888

# Forward proxy for Comet requests. Set if Comet needs a proxy to reach
# torrent indexers or RealDebrid. Usually blank (Comet runs on the VPS
# which has direct access). Leave commented to connect directly.
Expand All @@ -81,6 +91,21 @@ STREAM_PROVIDER=torrentio
# RealDebrid API base URL.
REALDEBRID_API_BASE_URL=https://api.real-debrid.com/rest/1.0

# Optional installation-wide debrid keys. Accounts normally enter their own
# key in Settings; when they have none these are used, and an administrator
# can also set a team key in Team settings (which takes precedence over env).
# Leave blank to require per-account keys.
# REALDEBRID_API_KEY=
# TORBOX_API_KEY=

# TorBox API base URL.
TORBOX_API_BASE_URL=https://api.torbox.app/v1/api

# Extra hosts that may serve the final media file (comma-separated).
# RealDebrid/TorBox CDNs and configured addon hosts are already allowed; use
# this when an addon proxies playback through another domain.
# STREAM_SOURCE_HOSTS=stremthru.example.com

# OMDB API key for ratings metadata. Get one at https://www.omdbapi.com/apikey.aspx
OMDB_API_KEY=

Expand Down
60 changes: 52 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,19 +110,21 @@ StreamVault relies on several external services. Here's what each one does and h

| Service | Role | Required? | How to get access |
|---------|------|-----------|-------------------|
| **RealDebrid** | Resolves selected files and provides direct streaming links | **Yes** — streaming won't work without it | Sign up at [real-debrid.com](https://real-debrid.com), then get your API key at [real-debrid.com/apitoken](https://real-debrid.com/apitoken) |
| **RealDebrid** | Resolves selected files and provides direct streaming links | One debrid service is required | Sign up at [real-debrid.com](https://real-debrid.com), then get your API key at [real-debrid.com/apitoken](https://real-debrid.com/apitoken) |
| **TorBox** | Alternative debrid resolver (preliminary support) | One debrid service is required | Sign up at [torbox.app](https://torbox.app), then get your API key at [torbox.app/settings](https://torbox.app/settings) |
| **Torrentio** | Finds available streams for a given title | Yes (default provider) | Works out of the box with the public instance. May need a proxy if your server IP is blocked (see below) |
| **Comet** | Alternative stream provider — self-hosted, independent of Torrentio | Optional (recommended) | Self-host via Docker — see [proxy/comet](proxy/comet) |
| **AIOStreams** | Aggregating stream provider — one addon over your sources and debrid services | Optional (preliminary support) | Run an instance or use one you trust, configure its sources/services, then set `AIOSTREAMS_URL` to its install link |
| **Cinemeta** | Provides content metadata (titles, posters, plots, episodes) | Yes (built-in) | No setup needed — uses the public Stremio metadata service |
| **OMDB** | Enriches content with IMDb, Rotten Tomatoes, and Metacritic ratings | Yes | Get a free API key at [omdbapi.com/apikey.aspx](https://www.omdbapi.com/apikey.aspx) |
| **TMDB** | Powers the "Recommended for You" feature using your watch history | Optional | Create an account at [themoviedb.org](https://www.themoviedb.org), then get a Read Access Token at [themoviedb.org/settings/api](https://www.themoviedb.org/settings/api) |
| **SubDL** | Provides external subtitles when embedded ones aren't available | Optional | Get a free API key at [subdl.com/panel/api](https://subdl.com/panel/api) |

### How the services work together

- **Torrentio and Comet** are both stream *providers*. They search torrent networks for available streams and return a list with quality, size, and language information. You can use either one or both — when both are configured (`STREAM_PROVIDER=auto`), StreamVault queries them in parallel and picks the best stream regardless of which provider found it. If one is down, the other fills in.
- **Torrentio, Comet and AIOStreams** are stream *providers*. They search torrent networks for available streams and return a list with quality, size, and language information. When more than one is configured (`STREAM_PROVIDER=auto`), StreamVault queries them in parallel and picks the best stream regardless of which provider found it. If one is down, the other fills in.

- **RealDebrid** is the *resolver*. Once you pick a stream, StreamVault sends its magnet link to RealDebrid, which retrieves or resolves the selected file and returns a direct HTTPS link. StreamVault does not add the source file to a persistent local media library, but its bytes pass through the server on demand and may be buffered temporarily during proxying or transcoding.
- **RealDebrid and TorBox** are the *resolvers*. Once you pick a stream, StreamVault sends its magnet link or provider URL to the selected debrid service, which retrieves the file and returns a direct HTTPS link. StreamVault does not add the source file to a persistent local media library, but its bytes pass through the server on demand and may be buffered temporarily during proxying or transcoding. Each account can use its own key, an administrator can set a team key, and `REALDEBRID_API_KEY` / `TORBOX_API_KEY` provide an installation fallback.

- **FFmpeg** is the *translator*. StreamVault bypasses it for sources the browser can play directly. Otherwise FFmpeg copies compatible video when safe, normalises audio to AAC with timestamp correction, or re-encodes incompatible/UHD video to browser-friendly 1080p H.264. It also produces HLS for iPhone playback and burns image-based subtitles that browsers cannot render.

Expand Down Expand Up @@ -151,7 +153,7 @@ The most demanding component is **FFmpeg transcoding**, which happens on-the-fly
### Prerequisites

- A server or VPS with **Docker** and **Docker Compose** installed
- A **RealDebrid subscription** (starts at ~€3/month)
- A **RealDebrid or TorBox subscription** (RealDebrid starts at ~€3/month)
- API keys for **OMDB** (free) and optionally **TMDB** (free) and **SubDL** (free)

### Quick start
Expand Down Expand Up @@ -196,9 +198,28 @@ Store the generated password in your password manager, then sign in and change i

To enable self-registration, set `ENABLE_SIGNUPS=true` in `.env` and restart.

### Configure your RealDebrid key
### Configure debrid keys

After logging in, go to **Settings** and enter your RealDebrid API key. The app verifies the key automatically and shows a confirmation. Your key is encrypted at rest using Active Record Encryption — it never appears in logs or is transmitted in plain text.
After logging in, go to **Settings** and choose RealDebrid or TorBox, then enter that service's API key. The app verifies the key automatically and shows a confirmation. Keys are encrypted at rest using Active Record Encryption — they never appear in logs or are transmitted in plain text.

Keys are resolved in this order:

1. the account's own key in Settings;
2. the team key an administrator sets under **Team settings**;
3. `REALDEBRID_API_KEY` or `TORBOX_API_KEY` from the environment.

Each account can therefore bring its own debrid subscription, while a team can share one key without putting it in every profile.

### Create your first administrator

Promote an existing account after the first sign-in:

```bash
docker compose exec web bin/rails c
> User.first.update!(admin: true)
```

Administrators see a **Team** link in the sidebar where they can set team-wide RealDebrid and TorBox keys.

### Auto-start on boot

Expand Down Expand Up @@ -231,10 +252,16 @@ docker compose up -d --build
| `POSTGRES_PASSWORD` | PostgreSQL database password (generate with `openssl rand -hex 16`) | Required |
| `POSTGRES_DB` | PostgreSQL database name | `streamvault` |
| `PORT` | Host port to expose the app on | `3000` |
| `STREAM_PROVIDER` | Which stream provider to use: `torrentio`, `comet`, or `auto` (see below) | `torrentio` |
| `STREAM_PROVIDER` | Which stream provider to use: `torrentio`, `comet`, `aiostreams`, or `auto` (see below) | `torrentio` |
| `TORRENTIO_API_BASE_URL` | Torrentio API base URL | `https://torrentio.strem.fun` |
| `COMET_URL` | URL of your self-hosted Comet instance | Optional |
| `AIOSTREAMS_URL` | AIOStreams install/manifest URL (the `/manifest.json` suffix is optional) | Optional |
| `AIOSTREAMS_PROXY` | Forward proxy URL for AIOStreams requests | Optional |
| `REALDEBRID_API_BASE_URL` | RealDebrid API base URL | `https://api.real-debrid.com/rest/1.0` |
| `REALDEBRID_API_KEY` | Installation-wide RealDebrid key for accounts without their own | Optional |
| `TORBOX_API_BASE_URL` | TorBox API base URL | `https://api.torbox.app/v1/api` |
| `TORBOX_API_KEY` | Installation-wide TorBox key for accounts without their own | Optional |
| `STREAM_SOURCE_HOSTS` | Extra comma-separated hosts allowed to serve the final media file | Optional |
| `OMDB_API_KEY` | OMDB API key for ratings metadata | Required |
| `TMDB_READ_ACCESS_TOKEN` | TMDB v4 bearer token for recommendations | Optional |
| `SUBDL_API_KEY` | SubDL API key for external subtitle fallback | Optional |
Expand Down Expand Up @@ -335,7 +362,24 @@ If you run StreamVault on your home computer (which has a residential IP that Re
|-------|---------|----------|-------------|
| `torrentio` | Torrentio | — | Default, simplest setup (no Comet needed) |
| `comet` | Comet | Torrentio | Explicit Comet-first with Torrentio fallback |
| `auto` | Comet (if `COMET_URL` set) | Torrentio | **Recommended** — best of both worlds |
| `aiostreams` | AIOStreams | Torrentio | You already run AIOStreams and want it to aggregate your sources |
| `auto` | AIOStreams (if set), then Comet (if set) | Torrentio | **Recommended** — best of both worlds |

### AIOStreams notes

AIOStreams is an addon aggregator. The install link you put in `AIOSTREAMS_URL`
already carries the sources and debrid accounts configured on that instance, so
a shared AIOStreams instance uses the keys configured there — not the
per-account RealDebrid/TorBox keys stored in StreamVault. Those per-account
keys are used by the Torrentio and Comet providers. When AIOStreams is selected
(and configured), accounts without their own key can still stream through the
instance. If every account should use its own debrid subscription, prefer
`STREAM_PROVIDER=torrentio` or `comet`, or run an AIOStreams instance per
account and point that account at its own link.

AIOStreams can return either its own proxy URL or a direct debrid CDN link.
StreamVault accepts both: direct RealDebrid and TorBox hosts are recognised, and
the RealDebrid bearer token is only ever sent to RealDebrid hosts.

## Testing

Expand Down
60 changes: 60 additions & 0 deletions app/controllers/admin/settings_controller.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# frozen_string_literal: true

module Admin
class SettingsController < ApplicationController
before_action :authenticate_user!
before_action :require_admin!

def show
@settings = AppSetting.current
end

def update
@settings = AppSetting.current
attributes = submitted_keys

# A mistyped replacement would break every account that relies on the team
# key, so a new value is verified before it replaces the working one.
failures = key_verification_failures(attributes)
if failures.any?
redirect_to admin_settings_path,
alert: "Not saved: #{failures.values.to_sentence} could not be verified. The previous key is still in use."
elsif @settings.update(attributes)
redirect_to admin_settings_path, notice: "Team settings updated."
else
render :show, status: :unprocessable_entity
end
end

private

# Blank fields keep the current team key; the remove checkbox clears it so
# the installation falls back to the environment.
def submitted_keys
submitted = settings_params.to_h
attributes = submitted.slice(*AppSetting::KEY_COLUMNS).compact_blank
AppSetting::KEY_COLUMNS.each do |column|
attributes[column] = nil if submitted["clear_#{column}"].to_s == "1"
end
attributes
end

def key_verification_failures(attributes)
failures = {}
if attributes[:realdebrid_api_key].present?
result = RealDebridService.new(attributes[:realdebrid_api_key]).verify_key
failures[:realdebrid_api_key] = "the RealDebrid key (#{result.error_message})" if result.failure?
end
if attributes[:torbox_api_key].present?
result = TorBoxService.new(attributes[:torbox_api_key]).verify_key
failures[:torbox_api_key] = "the TorBox key (#{result.error_message})" if result.failure?
end
failures
end

def settings_params
params.require(:app_setting).permit(:realdebrid_api_key, :torbox_api_key,
:clear_realdebrid_api_key, :clear_torbox_api_key)
end
end
end
15 changes: 15 additions & 0 deletions app/controllers/application_controller.rb
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,24 @@ def signups_enabled?
end

# Rating-limit policy for child accounts (no-op for regular accounts).
helper_method :debrid_access_configured?

# True when playback can resolve streams: the account has a key (own, team,
# or environment), or a shared AIOStreams instance supplies its own debrid
# credentials.
def debrid_access_configured?
current_user&.debrid_configured? || StreamProvider.keyless_provider_available?
end

private

def parental_content_policy
ParentalControls::ContentPolicy.new(current_user)
end

def require_admin!
return if current_user&.admin?

redirect_to root_path, alert: "That page is restricted to administrators."
end
end
3 changes: 2 additions & 1 deletion app/controllers/hls_controller.rb
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ def start
audio_stream: params[:audio_stream],
subtitle_stream: params[:subtitle_stream],
default_language: current_user.default_stream_language,
preferred_languages: current_user.preferred_stream_languages
preferred_languages: current_user.preferred_stream_languages,
quality: params[:quality]
)
playback_id = params[:playback_id].to_s.gsub(/[^a-zA-Z0-9_-]/, "").first(80).presence || "unknown"
Rails.logger.info("[HLS] playback_id=#{playback_id} session_id=#{session.session_id} started")
Expand Down
66 changes: 50 additions & 16 deletions app/controllers/settings_controller.rb
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# frozen_string_literal: true

class SettingsController < ApplicationController
DEBRID_KEY_COLUMNS = %w[realdebrid_api_key torbox_api_key].freeze

before_action :authenticate_user!

def show
Expand All @@ -10,10 +12,7 @@ def show
def update
@user = current_user

# Preserve existing RD key if not provided
if params[:user][:realdebrid_api_key].blank?
params[:user].delete(:realdebrid_api_key)
end
apply_key_removals

if params[:user][:password].present?
update_with_password
Expand All @@ -24,6 +23,21 @@ def update

private

# Blank key fields mean "keep the stored key"; the remove checkbox is the only
# way to clear one, so an expired key stops overriding the team key.
def apply_key_removals
submitted = params[:user]
return unless submitted

DEBRID_KEY_COLUMNS.each do |column|
if submitted["clear_#{column}"].to_s == "1"
submitted[column] = nil
elsif submitted[column].blank?
submitted.delete(column)
end
end
end

def update_with_password
if @user.update_with_password(settings_params_with_password)
bypass_sign_in @user
Expand All @@ -38,32 +52,52 @@ def update_with_password
end

def update_without_password
realdebrid_key = params.dig(:user, :realdebrid_api_key)
torbox_key = params.dig(:user, :torbox_api_key)

if @user.update(settings_params)
if params[:user][:realdebrid_api_key].present?
rd = RealDebridService.new(@user.realdebrid_api_key)
result = rd.verify_key
if result.success?
redirect_to settings_path, notice: "Settings updated. RealDebrid connection verified."
else
redirect_to settings_path, alert: "Settings saved, but RealDebrid key could not be verified: #{result.error_message}"
end
failures = key_verification_failures(realdebrid_key, torbox_key)
if failures.any?
redirect_to settings_path, alert: "Settings saved, but #{failures.to_sentence} could not be verified."
else
redirect_to settings_path, notice: "Settings updated."
redirect_to settings_path, notice: verification_notice(realdebrid_key, torbox_key)
end
else
render :show, status: :unprocessable_entity
end
end

def key_verification_failures(realdebrid_key, torbox_key)
failures = []
if realdebrid_key.present?
result = RealDebridService.new(realdebrid_key).verify_key
failures << "the RealDebrid key (#{result.error_message})" if result.failure?
end
if torbox_key.present?
result = TorBoxService.new(torbox_key).verify_key
failures << "the TorBox key (#{result.error_message})" if result.failure?
end
failures
end

def verification_notice(realdebrid_key, torbox_key)
verified = []
verified << "RealDebrid" if realdebrid_key.present?
verified << "TorBox" if torbox_key.present?
return "Settings updated." if verified.empty?

"Settings updated. #{verified.to_sentence} connection verified."
end

def settings_params_with_password
params.require(:user).permit(:realdebrid_api_key, :default_language, :password, :password_confirmation, :current_password,
params.require(:user).permit(:realdebrid_api_key, :torbox_api_key, :debrid_service, :default_language,
:password, :password_confirmation, :current_password,
:child_account, :max_rating_age, :child_lock_password, :child_lock_password_confirmation, :child_lock_current_password,
preferred_languages: [])
end


def settings_params
params.require(:user).permit(:realdebrid_api_key, :default_language,
params.require(:user).permit(:realdebrid_api_key, :torbox_api_key, :debrid_service, :default_language,
:child_account, :max_rating_age, :child_lock_password, :child_lock_password_confirmation, :child_lock_current_password,
preferred_languages: [])
end
Expand Down
Loading