Metadata-Version: 2.4
Name: smx-youtube-app
Version: 0.1.2
Summary: Installable companion YouTube media app for SyntaxMatrix-based client ecosystems.
Author: SyntaxMatrix
License: Proprietary
Project-URL: Homepage, https://syntaxmatrix.net
Project-URL: Documentation, https://syntaxmatrix.net
Project-URL: Source, https://github.com/REPLACE_ME/REPLACE_ME
Project-URL: Issues, https://github.com/REPLACE_ME/REPLACE_ME/issues
Keywords: youtube,fastapi,react,media,syntaxmatrix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: FastAPI
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.115.12
Requires-Dist: uvicorn[standard]<1,>=0.34.0
Requires-Dist: pydantic<3,>=2.11.3
Requires-Dist: python-dotenv<2,>=1.1.0
Requires-Dist: yt-dlp>=2026.03.17
Requires-Dist: sqlalchemy<3,>=2.0.42
Requires-Dist: alembic<2,>=1.18.4
Requires-Dist: psycopg[binary]<4,>=3
Requires-Dist: google-auth[requests]<3,>=2.47.0
Requires-Dist: requests<3,>=2.32.3
Requires-Dist: itsdangerous<3,>=2.2.0
Provides-Extra: release
Requires-Dist: build>=1.2.2; extra == "release"
Requires-Dist: twine>=6.1.0; extra == "release"

# 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

```text
.
├── 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`](docs/SETUP.md)

## Docker quick start

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

```bash
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.example)
- [`.env.docker.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`](docs/OPERATIONS.md)

## Releases

See [`docs/RELEASE.md`](docs/RELEASE.md)

## Changelog

See [`CHANGELOG.md`](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

```powershell
pip install smx-youtube-app


