# Project pack: Tube Archivist @ 1cf5518

Facts about **Tube Archivist** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Tube Archivist is a self-hosted YouTube media server. You subscribe to channels and playlists, it downloads the videos and metadata with yt-dlp, and gives you a searchable library with a player, subtitles, comments and watch progress. It keeps videos watchable even if they disappear online.

## Version and source
- Repository: https://github.com/tubearchivist/tubearchivist
- Pinned commit: `1cf55183fa8c4aad7022e7c8a9b59f1069b78fbe`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/tubearchivist/tubearchivist/archive/1cf55183fa8c4aad7022e7c8a9b59f1069b78fbe.zip
- Official docs: https://docs.tubearchivist.com
- Licence: **GPL-3.0-only**. Free to use and change. If you share your changed version with other people (give them the code or app), you must share your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/tubearchivist/tubearchivist bespoke-tube-archivist
  cd bespoke-tube-archivist
  git checkout --detach 1cf55183fa8c4aad7022e7c8a9b59f1069b78fbe
  # Prepare development requirements and local configuration first.
  docker compose up -d archivist-es archivist-redis
  cd backend
  pip install -r requirements-dev.txt
  python manage.py runserver
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  curl -O https://raw.githubusercontent.com/tubearchivist/tubearchivist/master/docker-compose.yml
  # edit TA_HOST, TA_USERNAME, TA_PASSWORD and ELASTIC_PASSWORD in the file first
  docker compose up -d
  # then open http://localhost:8000
  ```

- Needs: Docker with at least 4 GB of memory and plenty of disk space; Python and Node for development
- Develop: `cd backend && python manage.py runserver`
- Test: `cd backend && pytest`
- Stack: python, typescript (Django, React, Celery, yt-dlp). Difficulty for a non-developer with an AI: **advanced**. A Django back end with a React front end, Redis and Elasticsearch. Subscriptions and download rules are settings; code changes need the full stack running.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **subscriptions** [settings]: Which channels to follow and how much to download. → `Channels and Playlists pages`
- **download-settings** [settings]: Quality, subtitles, schedules and cleanup. → `Settings → Downloads`
- **integrations** [extend]: Send downloads to Jellyfin or Plex and use the browser extension. → `Settings → Integrations and the API`
- **react-ui** [code]: Screens and player. → `frontend/src`
- **django-api** [code]: New endpoints and tasks. → `backend/`

## Must keep working
- Download and indexing tasks, which keep the library consistent.
- Elasticsearch mappings. Plan reindexing for changes.
- Authentication and user permissions.

## Staying updatable
Use settings and integrations. Put code changes in new modules and test with a very small channel.

## Data, costs and safety
- Personal data: **yes**. Stored in: Video files in a media folder plus the Elasticsearch index and a cache folder. Videos need a lot of disk space. Back up the Elasticsearch data and the media folder.
- Service: Elasticsearch and Redis (included) (required, free): Search and background jobs.
- Setting `TA_HOST`: The address people use to reach Tube Archivist.
- Setting `TA_USERNAME`: The first user's login name.
- Setting `TA_PASSWORD` (**secret**: the person enters it themselves, never in chat): The first user's password. Never paste it into an AI chat.
- Setting `ELASTIC_PASSWORD` (**secret**: the person enters it themselves, never in chat): Elasticsearch password.
- Downloading may breach YouTube's terms and creators' rights. Use it for content you are allowed to keep.
- Don't expose it to the internet without a login and HTTPS.

---

# Customising Tube Archivist

Tube Archivist is a Django back end with a React front end and Elasticsearch. Its repo includes AGENTS.md with conventions.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Django apps (channel, playlist, video, download) | backend/<app>/ |
| Task definitions | backend/task/ |
| React front end | frontend/src/ |
| Docker setup | Dockerfile, docker-compose.yml, docker_assets/ |
| Elasticsearch settings | backend/appsettings/ |
| Showcase and docs | SHOWCASE.MD |

## Use the gentlest change first

1. **Settings (no code):** subscriptions, download rules, schedules and cleanup.
2. **Extend:** API and integrations.
3. **Code:** new tasks, endpoints and screens.

## Recipes

- **New scheduled task:** define it in the task module and register it with Celery beat.
- **New field on videos:** update the Elasticsearch mapping and the serializer, and plan a reindex.

## Running and checking your changes

- Start the stack, subscribe to a tiny channel and download one video.
- Run the backend tests with `pytest`.

## Pitfalls

- Elasticsearch needs enough memory. Set `vm.max_map_count` on Linux.
- Test with tiny channels to save bandwidth.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/tube-archivist/1cf5518/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/tube-archivist/1cf5518/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/tube-archivist/1cf5518/r2/SKILL.md)