Tube Archivist

Tube Archivist is a self‑hosted media streaming platform that turns a YouTube channel or playlist into an offline, searchable video library. At its core it acts as a micro‑service stack that orchestrates yt‑dlp downloads, metadata extraction from the YouTube Data API, and a web UI built on modern JavaScript frameworks. The application exposes a RESTful API for programmatic access, enabling developers to integrate video ingestion, search, and playback into custom workflows or media servers such as Jellyfin and Plex.

Architecture & Technical Stack

The stack is deliberately lightweight yet modular. The backend is a Python 3.11 application using FastAPI for routing and async I/O, wrapped in a Docker container that also runs the yt‑dlp worker. PostgreSQL (or SQLite in dev) stores video metadata, channel subscriptions, and playback state; the schema is auto‑generated via SQLAlchemy ORM. The frontend is a single‑page application built with React and Vite, communicating over JSON via the FastAPI endpoints. A Nginx reverse proxy serves static assets and provides TLS termination when deployed behind a Docker Compose stack. The entire system is container‑first, with official images published on Docker Hub and support for Podman, Unraid, and Synology packages.

Core Capabilities & APIs

• Subscription Management – CRUD operations on YouTube channels and playlists, with webhook support for new uploads.
• Download & Indexing – Triggered via a REST endpoint or scheduled job; yt‑dlp fetches video files and metadata, then populates the PostgreSQL index.
• Search & Retrieval – Full‑text search powered by PostgreSQL’s tsvector, exposed through /api/videos?search=....
• Playback & State Tracking – Video URLs are served through a secure media endpoint; the API records watched flags per user.
• Webhooks & Extensions – External services (e.g., Plex/Jellyfin) can subscribe to video_added events or poll the API for new content.

The SDK‑style documentation on docs.tubearchivist.com details request/response schemas, authentication (JWT), and rate limits.

Deployment & Infrastructure

Tube Archivist is designed for container‑native environments. A single docker-compose.yml defines three services: app, db, and nginx. The app container mounts a persistent volume for media files (/media) and another for the database. Scaling horizontally is straightforward: replicate the app service behind a load balancer; PostgreSQL can be upgraded to a HA cluster if needed. Resource requirements are modest—2 GB RAM for testing, 4 GB for production—but the Docker image is lightweight (<200 MB) and supports multi‑arch (AMD64, ARM64).

Integration & Extensibility

The plugin ecosystem is a key differentiator. Official plugins for Jellyfin and Plex expose the video library as a media server, allowing seamless playback on any client. The browser companion extension injects an “Archive” button into YouTube pages, calling the /api/archive endpoint directly. Developers can write custom plugins by extending the FastAPI router or by consuming webhooks; for example, a Slack bot could post new uploads to a channel. The API is versioned (/api/v1/...), and the project encourages community contributions via GitHub.

Developer Experience & Community

Documentation is comprehensive, with a dedicated FAQ, installation guides for Docker, Podman, Unraid, and Synology, and an interactive API reference. The project’s Discord server hosts real‑time support, while a dedicated subreddit fosters peer troubleshooting. Contributions are welcomed through pull requests; the codebase follows PEP‑8, uses GitHub Actions for CI/CD, and publishes automated Docker images. Licensing is MIT, allowing unrestricted commercial use.

Use Cases

1. Personal Media Server – Archive favorite YouTube channels and stream them on any device via the built‑in web UI or Plex/Jellyfin integration.
2. Educational Repositories – Institutions can subscribe to lecture channels, index content once, and provide offline access in bandwidth‑constrained environments.
3. Compliance & Archival – Enterprises can capture and store regulatory videos, ensuring they remain accessible even if the original channel is removed.
4. Developer Tooling – Integrate the API into custom pipelines (e.g., a CI system that downloads and indexes tutorial videos for automated testing).

Advantages Over Alternatives

• Open Source & Self‑Hosted – No vendor lock‑in; full control over data and privacy.
• Lightweight & Docker‑Ready – Quick deployment with minimal dependencies; container‑native scaling.
• Rich API & Webhooks – Enables automation and integration with third‑party media servers.
• Active Community & Plugins – Immediate access to Jellyfin/Plex plugins and a responsive support channel.
• Performance & Flexibility – FastAPI’s async engine handles concurrent downloads and queries efficiently; PostgreSQL offers robust indexing for large libraries.

In summary, Tube Archivist delivers a turnkey solution for developers who need to transform YouTube content into an offline, searchable media library while retaining full control over the stack and integration capabilities.