A self-hosted media aggregation application built with Phoenix + LiveView for organizing external catalogs, protected playback, personal libraries, and shared viewing in one web experience.

Português

Highlights   |    Architecture   |    Runtime Surfaces   |    Stack   |    Quick Start   |    Project Notes

Streamix is a self-hosted aggregation layer for external media sources. It normalizes provider data into a relational catalog, serves it through a responsive LiveView interface and API, and keeps upstream credentials behind signed, server-validated playback URLs.

A fresh installation is intentionally empty: the application and local infrastructure will start, but catalog content only appears after an authorized Xtream, GIndex, or torrent source is configured and synchronized.

• Personal Xtream Codes providers plus an optional system-wide provider
• Optional GIndex ingestion for Google Drive-backed movie, series, and anime libraries
• Optional torrent catalog and playback through an operator-managed rqbit sidecar
• Live channels, movies, series, seasons, episodes, and anime
• EPG now/next data, favorites, history, and resumable watch progress
• Optional TMDB enrichment and external subtitle lookup
• Signed stream tokens and server-side source resolution that keep provider credentials out of browser payloads
• HLS, transport stream, and VOD playback paths, with actual codec support depending on the source and browser

• Password authentication with role- and permission-based access
• Public catalog entry surface with authenticated browsing and playback
• Plans, subscriptions, and access entitlements, with Stripe checkout enabled only when configured
• Watch parties with synchronized playback, presence, and room chat
• Responsive dark-first UI with an optional light theme
• Installable PWA with an offline application shell and metadata caching — not offline video downloads

• Oban-backed synchronization and maintenance jobs
• Optional RabbitMQ + Broadway path for distributed queue processing
• ConCache L1 + Redis L2 caching
• Provider health sampling, circuit breaking, and bounded HTTP pools
• Liveness, readiness, Prometheus metrics, and playback diagnostics
• Optional semantic search and recommendations through Gemini or NVIDIA embeddings plus Qdrant

Many IPTV interfaces render an upstream response directly. Streamix instead persists a normalized catalog and places accounts, permissions, favorites, progress, billing rules, background synchronization, and playback delivery around that data.

That makes the application useful as a long-running service, but it also means external systems remain real operational dependencies. Provider availability, rate limits, redirect behavior, source quality, and browser codec support can all affect the final playback experience.

graph TD
    CLIENTS[Web / PWA / API clients]

    subgraph APP["Streamix application"]
        WEB[Phoenix + LiveView]
        API[REST API v1]
        AUTH[Accounts + Access]
        CATALOG[IPTV / GIndex / Torrent]
        BILL[Billing]
        PARTY[Watch Party]
        AI[AI discovery]
        TOKEN[Signed stream tokens]
        DELIVERY[Resolver / stream proxy]
        JOBS[Oban workers]
        L1[ConCache L1]
    end

    subgraph DATA["Data and optional infrastructure"]
        DB[(TimescaleDB / PostgreSQL 17)]
        REDIS[(Redis)]
        QDRANT[(Qdrant)]
        RMQ[(RabbitMQ)]
    end

    subgraph SOURCES["Operator-configured services"]
        XT[Xtream providers]
        GIDX[GIndex endpoints]
        RQBIT[rqbit]
        TMDB[TMDB / subtitle APIs]
        EMB[Gemini / NVIDIA]
    end

    CLIENTS --> WEB
    CLIENTS --> API
    WEB --> AUTH
    WEB --> CATALOG
    WEB --> BILL
    WEB --> PARTY
    API --> AUTH
    API --> CATALOG
    CATALOG --> DB
    CATALOG --> L1
    CATALOG --> REDIS
    CATALOG --> XT
    CATALOG --> GIDX
    CATALOG --> RQBIT
    CATALOG --> TMDB
    WEB --> TOKEN
    API --> TOKEN
    TOKEN --> DELIVERY
    DELIVERY --> XT
    DELIVERY --> GIDX
    DELIVERY --> RQBIT
    AI --> EMB
    AI --> QDRANT
    JOBS --> DB
    JOBS -. optional .-> RMQ

sequenceDiagram
    participant User
    participant UI as LiveView / API
    participant Access as Access rules
    participant Token as StreamToken
    participant Gateway as Resolver / Proxy
    participant Source as Configured source

    User->>UI: Request playback
    UI->>Access: Check identity and content access
    Access-->>UI: Authorized
    UI->>Token: Sign a source-bound playback token
    Token-->>User: Short-lived playback URL
    User->>Gateway: Request signed URL
    Gateway->>Gateway: Validate token and resolve source
    Gateway->>Source: Fetch or redirect using server-held credentials
    Source-->>Gateway: HLS / TS / VOD response
    Gateway-->>User: Browser-safe playback response

• Public: /, /plans, /tv, /login, /register
• Catalog: /browse, /browse/movies, /browse/series, /browse/animes, /search, /torrent
• Personal providers: /providers, /providers/:provider_id/...
• Library: /favorites, /history
• GIndex: /gindex/...
• Shared viewing: /party, /party/:invite_code, /party/:invite_code/watch
• Playback: /watch/:type/:id
• Account and access: /settings, /billing
• Administration: /admin, /admin/plans, /admin/billing, /admin/users

The main integration surface lives under /api/v1. Production clients should send a configured X-API-Key; user resources additionally validate the relevant user token in their controllers.

At runtime, the provider-aware catalog contract is available as OpenAPI JSON at /api/v1/openapi.json and through the interactive UI at /api/v1/docs. Catalog successes consistently return data plus optional meta; errors return stable error.code and error.message fields. See docs/api-v1.md for filters, pagination, examples, and the current breaking-change note.

• auth — register, login, logout, and current user
• catalog — provider discovery; aggregated and filterable movies, series, channels, and categories; home, search, details, and signed stream URLs
• search — semantic search, similarity, and capability status
• recommendations — personalized items, channels, insights, and profile refresh
• favorites, history, epg, and telemetry/playback
• providers — personal provider management and synchronization

• GET /api/health — shallow process liveness
• GET /api/health/ready — database, Redis, providers, semantic search, and torrent readiness
• GET /metrics — Prometheus metrics protected by operator credentials

• Docker with Compose
• Elixir 1.20 and Erlang/OTP 29
• Node.js 26 and npm 12

The repository includes .tool-versions for runtime managers such as mise.

docker compose up -d

The default Compose stack starts PostgreSQL, Redis, RabbitMQ, Qdrant, and rqbit. RabbitMQ, Qdrant-backed discovery, and torrent ingestion remain application-level opt-ins even when their local containers are running.

cp .env.example .env

Set at least:

• ADMIN_PASSWORD — password for the seeded administrator
• PROVIDER_ENCRYPTION_KEY — encrypts stored provider credentials

The example file already points DATABASE_URL and REDIS_URL at the local Compose services.

cd assets && npm ci && cd ..

mix setup

This installs Mix dependencies, creates and migrates the database, runs seeds, installs asset tooling, and builds the frontend.

mix phx.server

Open http://localhost:4000, sign in with the configured admin account, and add an authorized provider or enable one of the system catalog sources.

See .env.example for the complete, commented contract.

# Backend
mix test
mix test path/to/test.exs
mix test --cover
mix quality
mix precommit

# Frontend
npm --prefix assets run lint
npm --prefix assets test
npm --prefix assets run budget:assets

# Browser and PWA
PLAYWRIGHT_BROWSER=chromium bash scripts/test-playwright-docker.sh
PLAYWRIGHT_BROWSER=firefox bash scripts/test-playwright-docker.sh
PLAYWRIGHT_BROWSER=webkit bash scripts/test-playwright-docker.sh
bash scripts/test-pwa-chromium.sh

The Playwright suite requires ffmpeg and generates temporary MPEG-TS fixtures locally. Cross-browser playback therefore stays independent from external IPTV provider availability.

Test commands deliberately ignore the repository .env. Without exported overrides they use the local Compose streamix_test database and Redis database 15. Export TEST_DATABASE_URL or TEST_REDIS_URL for alternate test infrastructure; remote hosts and non-*_test database names still fail closed unless explicitly authorized.

CI runs compilation, Credo, security and dependency audits, coverage floors, Dialyzer, frontend tests, the three Playwright browser engines, mobile/PWA smoke tests, image scanning, and immutable-image provenance checks.

• Production deployment is digest-based and uses the versioned contract in deploy/docker-compose.production.yml. See docs/deployment.md.
• The player protects credentials and provides several delivery engines, but it cannot make an unsupported codec, malformed source, or unavailable upstream playable.
• PWA offline support covers the application shell and selected metadata; media playback still requires a reachable source.
• GIndex and external provider synchronization must respect upstream quotas and token behavior.
• The TV-facing API remains here, while standalone TV applications are intentionally maintained outside this repository.

• CONTRIBUTING.md
• SECURITY.md
• AGENTS.md
• LICENSE

Crafted by Gabriel Maia
gabrielmaialva33@gmail.com · GitHub