Local-first RAG search over YouTube channel transcripts. Point it at channels, and it downloads audio, transcribes it locally, embeds the transcripts into a vector database, and lets you find videos by describing what was said — in your own words, not keywords.
No YouTube Data API key required. It uses:
- yt-dlp — channel catalog + audio-only download
- faster-whisper — local speech-to-text (CPU, int8)
- LanceDB — on-disk vector store for transcript chunks
- An LLM for chat + embeddings — either a local OpenAI-compatible server (LM Studio / Ollama) or a cloud provider (OpenAI, Google Gemini, Anthropic Claude)
Everything except the answer model can run fully offline.
Add channel URL
│
▼
yt-dlp catalog sync ──► SQLite (channels, videos, jobs, chat)
│
▼ (background scheduler, BATCH_MAX_VIDEOS per interval)
yt-dlp audio download ──► faster-whisper transcribe ──► chunk ──► embed
│
▼
LanceDB vectors
│
Chat: "a video about X" ──► embed query ──► vector search ──► LLM answers with links
| Component | What it does |
|---|---|
API (src.api.main) |
FastAPI + Uvicorn — serves the web UI, REST endpoints, and SSE job-progress stream. Also runs the background scheduler in-process. |
Worker (src.worker.main) |
Optional standalone transcription loop. The API already runs batches on an interval, so this is only needed if you want the worker on a separate machine/process. |
| SQLite | Channels, videos, transcript segments, indexing jobs, chat history. |
| LanceDB | 768-dim transcript-chunk embeddings (nomic by default) for semantic search. |
- Python 3.12+
- ffmpeg on
PATH(audio decoding for Whisper) - An OpenAI-compatible LLM server for embeddings (and, optionally, chat):
- (optional) A cloud API key if you want OpenAI / Gemini / Anthropic for the answer model
macOS note: transcription runs on CPU (
WHISPER_DEVICE=cpu) because CTranslate2 has no Apple-Metal backend.int8keeps it fast and small on Apple-silicon.
cd 57-YoutubeContentIndexer
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
# Edit .env — at minimum set EMBEDDING_BASE_URL / EMBEDDING_MODEL and LLM_BASE_URL / LLM_MODELStart the app (API + background scheduler) with the helper scripts:
./start.sh # launches detached, waits for health, prints the URL
./stop.sh # stops it (graceful, falls back to SIGKILL)
tail -f logs/app.log…or run it in the foreground:
python -m src.api.mainThen open http://localhost:8080.
A dedicated worker is optional (the API already processes batches):
python -m src.worker.mainThe web UI has four tabs:
- Channels — Add a channel URL (e.g.
https://www.youtube.com/@handle/videos). The full catalog is synced and videos enterdiscoveredstatus. The table shows per-channel counts and actions (refresh, pause, remove). - Progress — Live view of indexing jobs and batch runs, with start timestamps. The scheduler
processes
BATCH_MAX_VIDEOSperBATCH_INTERVAL_MINUTES. Pause a channel to skip its queue. - Chat — Describe what was said. The agent embeds your query, retrieves the closest transcript
chunks, and answers with the matching videos and full YouTube links. Answers stream
token-by-token.
- Say "search all videos" (or "every video", "whole library", …) to trigger an exhaustive sweep across the entire library instead of the default top-K retrieval.
- Settings — Edit provider, models, API keys, batch limits, and Whisper options in the UI.
Changes are saved to SQLite and apply immediately, no restart.
.envprovides defaults on first run.
The answer model is swappable at any time (it does not require re-indexing). Set these in
Settings → LLM (chat) or in .env:
| Provider | LLM_PROVIDER |
LLM_BASE_URL |
LLM_MODEL example |
LLM_API_KEY |
|---|---|---|---|---|
| Local LM Studio | openai |
http://127.0.0.1:1234/v1 |
qwen/qwen3-8b |
(blank) |
| Ollama | openai |
http://127.0.0.1:11434/v1 |
llama3.1 |
(blank) |
| OpenAI | openai |
https://api.openai.com/v1 |
gpt-4o |
sk-... |
| Google Gemini | openai |
https://generativelanguage.googleapis.com/v1beta/openai |
gemini-2.5-flash |
(your key) |
| Anthropic Claude | anthropic |
https://api.anthropic.com/v1 |
claude-haiku-4-5 |
sk-ant-... |
- LM Studio, Ollama, OpenAI, and Gemini all speak the OpenAI-compatible
/chat/completionsshape, so they shareLLM_PROVIDER=openai. A blank key means no auth header (local). - Anthropic uses its native
/v1/messagesAPI (LLM_PROVIDER=anthropic), which is why it has a dedicated provider mode.LLM_MAX_TOKENSis required there;ANTHROPIC_VERSIONsets the API version.
⚠️ Search always uses the local embedding server. Embeddings stay local by design (the existing LanceDB vectors are tied to the embedding model). Even with a cloud chat provider, theEMBEDDING_BASE_URLhost must be running for retrieval to work — switching the embedding model would invalidate every stored vector and force a full re-index.
All settings can be edited live in the Settings tab; .env only seeds the defaults on first run.
Precedence: code defaults → .env → SQLite settings table (SQLite wins). See
.env.example for the complete annotated list.
| Variable | Purpose |
|---|---|
LLM_PROVIDER |
openai (OpenAI-compatible) or anthropic (native Claude) |
LLM_BASE_URL / LLM_MODEL |
Chat endpoint + model name |
LLM_API_KEY |
Bearer key (OpenAI/Gemini) or x-api-key (Anthropic); blank for local |
LLM_MAX_TOKENS |
Answer cap (required by Anthropic; ignored locally) |
ANTHROPIC_VERSION |
API version header, only when LLM_PROVIDER=anthropic |
EMBEDDING_BASE_URL / EMBEDDING_MODEL |
Embeddings endpoint + model (keep local) |
EMBEDDING_API_KEY |
Set only if embeddings run on a cloud host |
WHISPER_MODEL |
tiny, base, small, medium, large-v3 |
WHISPER_DEVICE / WHISPER_COMPUTE_TYPE |
cpu/cuda/auto, int8/float16 |
BATCH_MAX_VIDEOS |
Videos processed per batch run |
BATCH_INTERVAL_MINUTES |
Cooldown between batches |
BATCH_ACTIVE_HOURS_START / END |
Optional processing window (e.g. 22:00 / 08:00) |
KEEP_AUDIO |
Keep downloaded audio after transcription (false saves disk) |
MAX_RETRIES |
Retry attempts per failed video |
CHUNK_TARGET_CHARS / CHUNK_OVERLAP_CHARS |
Transcript chunking |
RAG_TOP_K / RAG_VIDEOS_LIMIT |
Chunks retrieved / videos returned per chat answer |
CATALOG_REFRESH_INTERVAL_MINUTES |
How often channel catalogs re-sync |
Run LM Studio / Ollama on a beefier box and point this machine at it over the LAN:
LLM_BASE_URL=http://192.168.1.50:1234/v1
EMBEDDING_BASE_URL=http://192.168.1.50:1234/v1Make sure that host's port is reachable on your network. Whisper still runs locally.
docker compose up --buildUses host.docker.internal to reach an LM Studio / Ollama server on the host — see
docker-compose.yml.
src/
api/ FastAPI app, routes, request schemas
agent/ chat orchestration (chat.py) + retrieval (retriever.py)
vectordb/ embeddings, chunking, LanceDB store, indexer
transcriber/ yt-dlp audio download + faster-whisper engine
indexer/ channel catalog sync
worker/ batch pipeline + background scheduler
db/ SQLite connection + schema
config.py settings (env-backed)
settings_store.py live, DB-backed settings overlay
web/ static UI (index.html, app.js, styles.css)
start.sh / stop.sh run/stop the app detached, with health check + logs
Connection refused/ 502 on chat or search — the local embedding server isn't running. Start LM Studio / Ollama with the embedding model loaded. Confirm it exposes/v1/embeddings.- yt-dlp errors / age or region gates — update it:
pip install -U yt-dlp. - Slow backfill — lower
WHISPER_MODEL, reduceBATCH_MAX_VIDEOS, or restrictBATCH_ACTIVE_HOURS_*to off-hours. Transcription is the bottleneck. - Failed videos — retried up to
MAX_RETRIES; inspect the job log in the Progress tab and use the per-video retry action. - Anthropic returns 401 — set
LLM_PROVIDER=anthropic, a validLLM_API_KEY(sk-ant-…), andLLM_BASE_URL=https://api.anthropic.com/v1. - Port already in use —
./stop.sh, or changeAPI_PORT.
For personal research and search only. Respect creators' rights and the platforms' terms of service when downloading and transcribing content.