DTube

DTube is a local-first video streaming app built with FastAPI. It scans your configured folders, indexes supported video files, and serves a web interface for browsing, watching, liking, and commenting.

• Automatic local video indexing (.mp4, .mkv, .webm, .mov)
• Home page with search and sorting
• Dedicated watch page with sidebar recommendations
• HTTP range-based streaming (seek support)
• Video download endpoint
• Auto thumbnail generation (when ffmpeg is available)
• View tracking
• Video like/unlike
• Nested comments and comment like/unlike
• SQLite-backed persistence (data/dtube.db)
• JSON metadata cache with migration support (data/video_meta.json)
• Basic security headers (CSP, X-Frame-Options, etc.)

• Python 3.10+
• FastAPI
• Uvicorn
• SQLAlchemy
• Jinja2
• SQLite
• Optional: ffmpeg / ffprobe

DTube/
├─ app/
│  ├─ main.py               # FastAPI app bootstrap
│  ├─ core/database.py      # DB init + migration helpers
│  ├─ routes/video.py       # Web routes + API endpoints
│  └─ models/               # SQLAlchemy models
├─ templates/               # HTML templates
├─ static/                  # CSS, JS, assets
├─ data/
│  ├─ dtube.db              # SQLite database
│  ├─ video_meta.json       # Video metadata cache
│  ├─ thumbnails/           # Generated thumbnails
│  └─ transcoded/           # Reserved transcoded outputs
├─ config.py                # Video directories config
└─ run.py                   # Local run entrypoint

python3 -m venv .venv
source .venv/bin/activate

pip install fastapi uvicorn sqlalchemy jinja2 python-multipart

ffmpeg and ffprobe improve thumbnail generation and duration detection.

Ubuntu/Debian:

sudo apt update
sudo apt install -y ffmpeg

Set VIDEO_DIR in config.py. It can be either a string or a list of directories.

VIDEO_DIR = [
    "/home/your-user/Videos",
    "/home/your-user/Temporary"
]

Notes:

• Non-existing directories are skipped.
• Only files under configured roots with supported extensions are indexed.

python run.py

The server runs on port 8000 and binds to your detected local/LAN IP.

Open in browser:

• http://127.0.0.1:8000 (same machine)
• http://<your-local-ip>:8000 (same network)

• GET / - Home page (video listing)
• GET /watch?id=<video_id> or /watch?v=<relative_name> - Watch page
• GET /thumb/{video_id} - Thumbnail image
• GET /stream/{video_id} - Streaming endpoint
• GET /download/{video_id} - Download endpoint
• GET /settings - Settings page
• GET /help - Help page

• GET /api/list?q= - List videos
• GET /api/meta?id=<id> - Video metadata and comments
• POST /api/view?id=<id> - Increment view count
• POST /api/like?id=<id> - Toggle video like (X-Actor-Id optional)
• POST /api/comment?id=<id> - Add comment/reply (Form: author, text, parent_id)
• POST /api/comment-like?comment_id=<id> - Toggle comment like (X-Actor-Id optional)

• data/video_meta.json
  • Path-to-ID mapping
  • Cached metadata and counters
  • Schema-aware migration in route logic
• data/dtube.db
  • Relational storage for videos, comments, and likes
  • Automatic table creation and lightweight schema migration at startup

• Quality switching is currently present as an interface parameter, but streaming is currently served from the original source file.
• Initial scanning can take time for very large media folders.
• The app is optimized for local/home-network usage; do not expose publicly without adding authentication and hardening.

• No videos shown: verify VIDEO_DIR paths in config.py.
• Thumbnail missing: ensure ffmpeg is installed and available in PATH.
• Duration is 0: ensure ffprobe is installed.
• Port conflict: change the port in run.py.
• Permission errors: verify read permissions for configured video directories.

• Authentication and user profiles
• Playlists and watch history
• Real transcoding queue + adaptive quality
• Better indexing/caching strategy for very large libraries
• Admin dashboard for media management