CasaTube

---

Why

Most self-hosted downloaders run the download inside the browser session, or lose it when the container restarts. CasaTube is built around one requirement: a job survives the browser closing and the service restarting. The browser only watches; the server owns the queue. Close the tab, lock the iPad, redeploy mid-download — the job carries on, or goes back to the queue and resumes.

Features

• A durable queue. Six visible stages per job (validate → analyze → download → postprocess → metadata → move), live over SSE, with automatic retries, priorities and per-job logs. In-flight work returns to the queue on restart.
• Choose before you download. Paste a URL and the form shows the resolutions, codecs, audio tracks and subtitles that video actually has — not a generic list that silently falls back to something else.
• Audio and subtitle languages are independent, and the output is language-tagged correctly, so Jellyfin and Plex show the right names.
• Never overwrites. Choose the file name; a name that is taken is reported before queueing, and sidecars (subtitles, thumbnail) always follow the final name.
• A library with a player. Browse what was downloaded, play it in the browser with real seeking (HLS remux on demand), switch audio tracks and subtitles, download a bundle, or move things to a trash you can restore from.
• Subscriptions. Follow channels and playlists; new uploads are queued on a schedule, without re-downloading the back catalogue.
• Sources yt-dlp cannot reach:
  • Private Telegram channels, through your own signed-in session (MTProto).
  • Google Drive files, without the shared API key yt-dlp depends on.
  • Anything else yt-dlp supports — YouTube, Vimeo, Odysee, Dailymotion and a thousand more.
• Plugins in TypeScript, written in an in-app editor and loaded without a restart: rewrite URLs before download, notify a webhook, ask Jellyfin to scan when a file lands. Jellyfin, webhook, URL-unshortener and Vidarro plugins ship with it.
• Credentials for sites that need a login (cookies, passwords, API keys), encrypted at rest when you set a key.
• Storage, analytics and notifications, optional transcoding presets, and a UI that works on a phone or an iPad, in light and dark.

Quick start

mkdir casatube && cd casatube
curl -fsSLO https://raw.githubusercontent.com/xantiagoma/casatube/main/docker-compose.yml
docker compose up -d

Open http://localhost:8520. Downloads land in ./library, the database in ./data. Put the settings in a .env next to the compose file:

CASATUBE_LIBRARY=/mnt/media/videos   # where your media server looks
PUID=1000                            # the owner of that library
PGID=1000
TZ=Europe/Madrid
CREDENTIALS_KEY=                     # openssl rand -base64 48 — see below

Or with plain Docker:

docker run -d --name casatube --restart unless-stopped \
  -p 8520:8520 \
  -e PUID=1000 -e PGID=1000 \
  -v ./data:/data \
  -v /mnt/media/videos:/library \
  ghcr.io/xantiagoma/casatube:latest

CasaOS: App Store → Custom Install → Import, and paste docker-compose.casaos.yml.

Everything else — every environment variable, network-mounted libraries, permissions, updating yt-dlp, troubleshooting — is in docs/DEPLOY.md.

Images

ghcr.io/xantiagoma/casatube, for amd64 and arm64. yt-dlp and ffmpeg are inside; nothing is needed on the host.

Tag
latest	The newest release with the newest yt-dlp. Rebuilt weekly.
0.1.0	That version with the newest yt-dlp. Rebuilt weekly.
0.1.0-ytdlp-2026.08.19	Immutable: exactly that app and that yt-dlp.
main	The tip of the main branch; sha-<short> pins one commit of it. Not a release.

yt-dlp is the part that rots — sites change and it follows them — so the weekly rebuild is what keeps a release downloading. Pin the immutable tag if you would rather update on purpose.

⚠️ Security: put it behind something

CasaTube has no login of its own. It is built for one household on a private network, and anyone who can reach the port can use it — including the plugin editor, which runs code on the server by design. Do not expose it to the internet directly. docs/SECURING.md walks through the options, with configurations: Tailscale (recommended), Cloudflare Tunnel with Access, or a reverse proxy that authenticates (Caddy, nginx, Authelia, Authentik).

Set CREDENTIALS_KEY before storing a cookie, a password or a Telegram session. Without it they are stored in plain text — the app says so at every start and on the Settings screen — and a Telegram session is your whole account. Keep a copy of the key: credentials sealed with it cannot be read without it.

See SECURITY.md for reporting a vulnerability.

Telegram

To download from a private channel you are a member of:

1. Create an app at my.telegram.org → API development tools and note the api_id and api_hash. (The RSA public key on that page is not needed.)
2. In CasaTube: Settings → Credentials → Telegram, enter both and your phone number, then the code Telegram sends you (and your two-step password if you have one).
3. Paste links like https://t.me/c/1234567890/42.

The session is stored as a credential scoped to t.me and never sent back to the browser. Revoke it from Telegram → Settings → Devices.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗