Tubearr

Meta	Value
Repo	`xpltdco/tubearr`
Page	`Home`
Audience	developers, agents, newcomers
Last Updated	2026-04-04
Status	current

What is Tubearr?

Tubearr is a self-hosted content archival and monitoring application in the *arr family style (Sonarr, Radarr, Lidarr). It automatically monitors YouTube channels and SoundCloud artists for new content, downloads media using configurable quality profiles, and organizes files into a structured library. Think of it as an automated media librarian that watches your favorite creators and grabs their content before it disappears.

Current Status

Actively developed. Through M004 — feature parity with competing tools (Youtarr, TubeSync, Pinchflat, Tube Archivist). Core monitoring, downloading, queue management, media server integration, and library management features are production-ready.

Key URLs

Resource	URL
Application	`https://tubearr.xpltd.co`
Repository	`https://git.xpltd.co/xpltdco/tubearr`
Health Check	`https://tubearr.xpltd.co/ping`
RSS Feed	`https://tubearr.xpltd.co/api/v1/feed/rss`

Core Features

Channel Monitoring — Add YouTube channels or SoundCloud artists; Tubearr periodically scans for new content
Smart Queue — Concurrent download queue with retry logic, priority ordering, rate limiting, pause/resume per item
Format Profiles — Configurable quality presets (resolution, codec, bitrate, subtitles, SponsorBlock) with output path templates
Multi-Platform — YouTube, SoundCloud, and any URL supported by yt-dlp (1000+ sites)
Ad-hoc URL Downloads — Paste any URL, preview metadata (title, thumbnail, duration), confirm to download
Keyword Filtering — Per-channel include/exclude patterns (plain text, glob, regex) to skip unwanted content
Media Server Integration — Plex and Jellyfin auto-scan on download completion with connection testing
NFO Metadata — Kodi-compatible episodedetails XML sidecars with content ratings (item → channel → global cascade)
Missing File Detection — Scans for removed media files, shows 'missing' badge, one-click re-download
Content Type Tabs — Filter channel content by type (Videos, Shorts, Streams) with count badges
Real-Time Progress — WebSocket-based live download progress in the browser UI
Notifications — Discord, email, Pushover, and Telegram alerts on grab/download/failure events
Back-Catalog Import — Bulk import existing media files into the library
Output Path Templates — Configurable {platform}/{channel}/{year}/{title}.{ext} variable syntax with live preview
Timezone & Theme — User-selectable timezone for all timestamps, dark/light theme with flash-free switching
RSS Feed — Podcast-compatible RSS 2.0 feed for downloaded audio content
REST API — Full API with key-based authentication for external integrations

Tech Stack

Component	Technology
Backend	Node.js 22, TypeScript, Fastify 5
Frontend	React 19, React Router 7, TanStack Query
Database	SQLite (LibSQL) with Drizzle ORM
Downloader	yt-dlp + ffmpeg
Build Tool	Vite
Testing	Vitest (830+ tests)
Deployment	Docker (multi-stage build)

Wiki Pages

Page	Description
Architecture	System design, tech stack, directory structure, design decisions
Getting Started	Local dev setup, prerequisites, first run
Data Model	Database schema, tables, relationships, migrations
API Reference	Complete HTTP endpoint inventory with examples
Deployment	Docker setup, volumes, nginx config, health checks
Configuration	All environment variables and config knobs
Development Guide	Code patterns, testing, CI/CD, contribution workflow
Agent Context	Structured metadata for LLM agents working on this codebase

Glossary

Term	Definition
Channel	A monitored content source — a YouTube channel, SoundCloud artist, or generic URL
Content Item	A single piece of downloadable media (video, audio, or livestream)
Format Profile	A reusable quality preset defining resolution, codec, subtitles, output path template, and post-processing options
Queue Item	A content item that has been enqueued for download, with status tracking, retry logic, and pause/resume
Monitoring Mode	Controls what content Tubearr grabs: `all`, `future` (new only), `existing` (backlog only), or `none`
Platform Source	An adapter for a specific content platform (YouTube, SoundCloud, Generic)
yt-dlp	The command-line tool that handles actual media downloading from 1000+ platforms
SponsorBlock	Community-sourced sponsor segment data; Tubearr can auto-remove sponsor segments during download
Media Server	A configured Plex or Jellyfin instance that receives automatic library scan triggers after downloads
NFO Sidecar	A Kodi-compatible XML metadata file generated alongside downloaded media
Content Rating	A per-item or per-channel rating (TV-Y through NC-17) written into NFO files for media server library categorization
Keyword Filter	Per-channel include/exclude patterns (plain text, glob, regex) applied during scheduled scans
*arr family	A category of self-hosted media management apps (Sonarr for TV, Radarr for movies, Lidarr for music)

Infrastructure Context

For newcomers to the xpltd infrastructure:

ub01 (10.0.0.10) — The primary server where all Docker services run
nginx01 (10.0.0.9) — Reverse proxy handling TLS termination for all *.xpltd.co subdomains
AdGuard Home — Internal DNS with rewrite rules pointing *.xpltd.co to nginx01
Cloudflare — External DNS with CNAME to dyndns.xpltd.co for public access