smx-youtube-app 0.1.0

Installable companion YouTube media app for SyntaxMatrix-based client ecosystems.

YouTube Video Downloader & Media Library

A self-hosted web application for inspecting YouTube videos, downloading permitted content, and managing a local media library.

Current status

This project currently supports:

• YouTube single-video inspection
• Resolution selection
• Non-blocking download jobs
• Progress tracking
• Saved media library
• Open / download / delete actions
• Docker-based local deployment
• PostgreSQL persistence
• Alembic migrations

Important usage note

Use this software only for content you own, control, or are otherwise permitted to download and store.

This project is intended as a self-hosted tool. Operators are responsible for ensuring their usage complies with applicable platform terms, copyright obligations, and local law.

Features

• Paste a YouTube URL and inspect metadata
• Choose a resolution before download
• Queue a download without blocking the UI
• Track job status and progress
• Prevent duplicate library entries for the same URL and resolution
• Search media and jobs
• Retry failed jobs
• View simple admin stats
• Run locally or via Docker Compose

Stack

Frontend

• React
• TypeScript
• Vite

Backend

• FastAPI
• SQLAlchemy
• Alembic
• yt-dlp
• FFmpeg

Data / Infra

• PostgreSQL
• Docker Compose

Architecture summary

The application currently uses:

• FastAPI backend API
• PostgreSQL for persistence
• Alembic for schema migrations
• Docker Compose for local container orchestration
• In-process background threading for download execution

Current limitation

Background downloads are currently executed in-process via Python threads.

That is acceptable for the current single-instance baseline, but it is not yet the final multi-worker production architecture. A dedicated worker/queue model can be introduced later.

Project structure

.
├── app/
│   ├── main.py
│   ├── config.py
│   ├── db.py
│   ├── models.py
│   ├── schemas.py
│   ├── tasks.py
│   └── services/
├── migrations/
├── web/
├── docker/
├── downloads/
├── docker-compose.yml
├── alembic.ini
├── requirements.txt
└── README.md

Local development

See docs/SETUP.md

Docker quick start

1. Copy environment file values as needed.
2. Start the stack:

docker compose up --build

3. Open:

• Frontend: http://localhost:8080
• Backend health: http://localhost:8000/health
• API docs: http://localhost:8000/docs

API overview

Health

• GET /health

Admin

• GET /admin/stats

Inspect

• POST /inspect

Downloads

• POST /download
• GET /downloads
• GET /downloads/{job_id}
• POST /downloads/{job_id}/retry

Media

• GET /media
• GET /media/{media_id}/file
• GET /media/{media_id}/download
• DELETE /media/{media_id}

Environment variables

Backend

• DATABASE_URL
• FFMPEG_LOCATION
• DOWNLOADS_DIR
• MAX_VIDEO_DURATION_SECONDS
• MAX_ACTIVE_DOWNLOADS
• ALLOWED_SOURCE_HOSTS
• CORS_ORIGINS

Frontend

• VITE_API_BASE_URL

See:

• .env.example
• .env.docker.example

Screenshots

Add screenshots here later:

• main downloader screen
• inspect result with formats table
• active job progress
• saved media library
• admin stats

Roadmap

• dedicated worker queue
• cancel active job
• pagination controls in UI
• auth and role separation
• cloud object storage support
• better operational metrics
• release automation
• test suite expansion

Troubleshooting

See docs/OPERATIONS.md

Releases

See docs/RELEASE.md

Changelog

See CHANGELOG.md

Licence

smx-youtube-app

Installable companion YouTube media app for SyntaxMatrix-based client ecosystems.

This package is intentionally separate from the SyntaxMatrix framework itself.
Client projects that need the YouTube app can install and run it as a companion service.
Client projects that do not need it do not install it.

What it provides

• FastAPI backend
• PostgreSQL persistence
• Alembic migrations
• Packaged frontend served by the backend
• CLI entry point: smx-youtube

Requirements

• Python 3.11+
• PostgreSQL
• Docker Desktop recommended for local PostgreSQL
• Node.js is only required by maintainers when rebuilding the frontend bundle

Install

pip install smx-youtube-app