TubeSync

TubeSync is a lightweight PVR (personal video recorder) designed to bridge YouTube content with local media servers such as Jellyfin or Plex. At its core, it orchestrates yt-dlp for downloading and ffmpeg for transcoding or re‑muxing, wrapped in a Go‑based web interface that exposes a RESTful API and a scheduler for periodic updates. The application is engineered to run inside containers (Docker/Podman) and supports both amd64 and arm64, making it suitable for home servers, NAS devices, or edge hardware like Raspberry Pi.

Architecture

• Language & Runtime: Written in Go (Golang) for static binaries, minimal runtime overhead, and excellent concurrency support.
• Web Layer: A lightweight HTTP server (likely using net/http or a minimal framework) serves the UI and API endpoints. The UI is rendered with server‑side templates, avoiding heavy client‑side frameworks.
• Task Scheduler: An internal cron‑style scheduler triggers yt-dlp invocations based on user‑defined intervals (e.g., hourly, daily). It implements exponential back‑off for failed downloads to ensure reliability.
• Downloader: Delegates video fetching to yt-dlp, passing user‑configured quality, format, and authentication tokens. The wrapper captures stdout/stderr for logging.
• Transcoder: Optional ffmpeg integration re‑encodes or muxes streams to match target formats, enabling consistent media server ingestion.
• Database: Uses a lightweight embedded store (likely SQLite) to persist source definitions, download history, and media metadata. This choice keeps the deployment footprint small while providing ACID guarantees.
• Media Organization: Downloads are sorted into video/ and audio/ subdirectories based on stream presence, simplifying media server library imports.

Core Capabilities & APIs

• Source Management: CRUD operations for YouTube channels, playlists, or individual URLs. Each source records metadata such as last fetched timestamp and download status.
• Media Catalog: Exposes a list of downloaded items with details (duration, resolution, format). The API can be consumed by external tools or custom UI dashboards.
• Webhooks: Allows clients to subscribe to events (e.g., new media available, download failure) for automation pipelines or notification systems.
• Quality & Format Selection: Users can specify yt-dlp format strings (e.g., bestvideo[ext=mp4]+bestaudio[ext=m4a]/best) and resolution constraints, giving fine‑grained control over local storage usage.
• Integration Hooks: After a successful download, TubeSync can trigger media server re‑scan via the Jellyfin/Plex APIs, completing the PVR loop.

Deployment & Infrastructure

• Containerization: A pre‑built image (ghcr.io/meeb/tubesync:latest) is available for both amd64 and arm64. The container expects three bind mounts: a config directory, a download destination, and optionally a media‑server integration folder.
• Scalability: While designed for single‑node use, the stateless API and external storage make it straightforward to run multiple instances behind a reverse proxy, each handling distinct source sets.
• Resource Footprint: The Go binary (~10 MB) plus minimal dependencies keeps RAM usage under 200 MiB. Disk I/O is dominated by yt-dlp and ffmpeg, which are already optimized for high‑throughput media handling.
• Backups & Persistence: The SQLite database and configuration files reside in the mounted config volume, enabling simple snapshot or replication strategies.

Integration & Extensibility

• Plugin System: Though not yet fully exposed, the architecture allows for runtime loading of custom Go modules to extend download logic or add new media server adapters.
• REST API: Full CRUD and status endpoints enable integration with CI/CD pipelines, home automation (Home Assistant), or custom monitoring dashboards.
• Webhooks & Events: External services can hook into events for real‑time notifications (e.g., Slack, email) or trigger downstream transcoding workflows.

Developer Experience

• Documentation: The README provides clear container‑based setup steps, source definitions, and configuration options. API endpoints are inferred from the UI but can be explored via tools like Swagger if generated.
• Community & Licensing: Open‑source under a permissive license, encouraging contributions. The project hosts its code on GitHub with active issue tracking and a small but engaged community around media automation.
• Configuration: Environment variables control user IDs, timezones, and media server credentials. The UI exposes most settings, reducing the need to edit YAML or JSON files directly.

Use Cases

1. Home Media Server PVR – Automatically download new uploads from favorite channels and trigger a Plex or Jellyfin re‑scan, enabling offline viewing.
2. Educational Content Curation – A teacher can curate a playlist of lecture videos, ensuring all content is locally available for students in bandwidth‑constrained environments.
3. Archival & Backup – Use TubeSync to periodically snapshot popular channels, preserving content even if it is later removed from YouTube.
4. Edge Deployment – Run on a Raspberry Pi or NAS to provide local caching for an entire household, reducing external bandwidth usage.

Advantages Over Alternatives

• Focused Feature Set: Unlike generic yt-dlp wrappers, Tube