Never miss a stream again. StreamVault automatically detects when your favorite streamers go live, records their broadcasts with Streamlink, performs post-processing with rich metadata and artwork, and serves everything through a modern Progressive Web App.
Features • Getting Started • Documentation • API Reference
- EventSub webhooks - Instant stream detection when channels go live
- Quality selection - Record in best quality or choose specific resolutions (1080p, 720p, 480p)
- H.265/AV1 codecs - Access advanced codecs and 1440p quality with browser token authentication
- Multi-hour streams - Safe 24h+ recording with automatic segmentation
- Proxy support - HTTP/HTTPS proxies with automatic audio synchronization
- Manual controls - Start and stop recordings on-demand via web interface
- Metadata generation - Comprehensive NFO files with title, description, date, and categories
- Automatic chapters - VTT and XML chapter files from stream events
- Thumbnails - Multiple quality options generated from video content
- Artwork pipeline - Poster, banner, and fanart images for media servers
- Episode numbering - Automatic episode tracking per streamer
- Media server ready - Compatible with Plex, Emby, Jellyfin, and Kodi
- Progressive Web App - Install on any device, works offline
- Real-time updates - WebSocket connections show live recording status
- Responsive design - Touch-optimized for phones and tablets
- Dark/Light themes - Automatic system theme detection
- Background queue monitor - Track post-processing tasks in real-time
- Session authentication - Secure cookie-based authentication
- Storage policies - Automatic cleanup by age, size, or file count
- Per-streamer settings - Individual recording preferences and cleanup rules
- Filename templates - Customize naming with variables (streamer, date, category, title)
- Bulk operations - Enable/disable multiple streamers at once
- Import follows - Sync your Twitch followed channels
- 100+ services - Discord, Telegram, Slack, Ntfy, Email, and more via Apprise
- Web push - Browser notifications with automatic VAPID key generation
- Event filtering - Choose which events trigger notifications
- Test system - Verify notification configuration before deploying
Before you begin, ensure you have:
- Docker & Docker Compose - Install Docker
- HTTPS domain with valid certificate - Required for Twitch EventSub webhooks
- Twitch Developer Application - Free, create one here
- Minimum 2GB RAM and 50GB storage (recordings grow 2-8GB per hour at 1080p)
Important
Twitch EventSub webhooks require a publicly accessible HTTPS endpoint with a valid SSL certificate. Use Let's Encrypt with Traefik, Caddy, Nginx, or a Cloudflare Tunnel.
-
Clone the repository:
git clone https://github.com/Serph91P/StreamVault.git cd StreamVault -
Create environment configuration:
cp .env.example .env
-
Configure Twitch application:
Create a Twitch application:
- Name: StreamVault (or your preference)
- OAuth Redirect URLs:
https://your-domain.com/auth/callback - Category: Application Integration
Copy the Client ID and Client Secret to your
.envfile:TWITCH_APP_ID=your_client_id_here TWITCH_APP_SECRET=your_client_secret_here BASE_URL=https://your-domain.com EVENTSUB_SECRET=random_secure_string_here
-
Start StreamVault:
docker compose -f docker/docker-compose.yml up -d
-
Access the web interface:
Open
https://your-domain.comin your browser (port 7000 is used internally).
Edit your .env file with these settings:
# Twitch API Configuration (Required)
TWITCH_APP_ID=your_twitch_client_id
TWITCH_APP_SECRET=your_twitch_client_secret
TWITCH_OAUTH_TOKEN= # Optional: enables H.265/1440p
# Application URLs (Required)
BASE_URL=https://your-domain.com # Must be HTTPS
EVENTSUB_SECRET=random_secure_string # Generate with: openssl rand -hex 32
# Database Configuration
POSTGRES_USER=streamvault
POSTGRES_PASSWORD=strong_secure_password_here
POSTGRES_DB=streamvault
# Optional Settings
TZ=Europe/Berlin # Your timezone
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERRORUsing Nginx:
server {
listen 443 ssl http2;
server_name your-domain.com;
ssl_certificate /path/to/certificate.crt;
ssl_certificate_key /path/to/private.key;
location / {
proxy_pass http://localhost:7000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
}
}Using Caddy:
your-domain.com {
reverse_proxy localhost:7000
}Note
Twitch restricts third-party apps to 1080p H.264. To unlock H.265/AV1 codecs and 1440p quality, add a browser authentication token.
- Log in to Twitch.tv
- Open browser DevTools (F12) → Console tab
- Run this command:
document.cookie.split("; ").find(item=>item.startsWith("auth-token="))?.split("=")[1]
- Copy the 30-character token and add to
.env:TWITCH_OAUTH_TOKEN=abc123xyz456def789ghi012jkl345
- Restart the container:
docker compose restart app
Quality comparison:
- Without token: 1080p60 H.264 only
- With token: Up to 1440p60, H.265/HEVC, AV1, smaller file sizes
See docs/BROWSER_TOKEN_SETUP.md for detailed instructions.
Comprehensive guides are available in the docs/ directory:
- User Guide - Complete setup and usage instructions
- Browser Token Setup - Enable H.265/1440p quality
- Navigate to the Streamers page
- Click Add Streamer
- Enter the Twitch username
- Configure recording preferences (optional):
- Recording quality (best, 1080p, 720p, etc.)
- Filename template
- Cleanup policies
- Enable recording for the streamer
- Go to Settings → Twitch Connection
- Click Connect Twitch Account
- Authorize StreamVault to access your followed channels
- Select channels to import
- Configure default recording settings
Manual Recording:
- Click the record button on any streamer card to start recording
- Stop recording anytime from the dashboard or streamer page
Automatic Recording:
- Enable "Auto Record" for streamers you want to monitor
- StreamVault detects when they go live via Twitch webhooks
- Recordings start automatically and stop when the stream ends
- Go to Settings → Notifications
- Add notification service URLs (see Apprise documentation)
- Select which events trigger notifications:
- Stream online/offline
- Recording started/completed/failed
- Favorite category detected
- Test your configuration with the Send Test button
Example service URLs:
Discord: discord://webhook_id/webhook_token
Telegram: tgram://bot_token/chat_id
Ntfy: ntfy://topic_name
Email: mailtos://user:password@smtp.example.com
Global Cleanup Policy:
- Go to Settings → Recording
- Enable automatic cleanup
- Set limits:
- Maximum age (days)
- Maximum storage (GB)
- Maximum file count
- Choose which limit triggers cleanup (first met or all met)
Per-Streamer Override:
- Edit any streamer's settings
- Enable custom cleanup policy
- Set streamer-specific limits
Warning
Recordings grow quickly (2-8GB per hour at 1080p). Configure cleanup policies early to prevent storage issues.
StreamVault provides a REST API for automation and integration. Interactive documentation is available at https://your-domain.com/docs.
# Streamer Management
GET /api/streamers # List all streamers
POST /api/streamers # Add new streamer
PUT /api/streamers/{id} # Update streamer settings
DELETE /api/streamers/{id} # Delete streamer
# Recording Control
POST /api/recording/start/{id} # Start manual recording
POST /api/recording/stop/{id} # Stop recording
GET /api/recording/status # Get recording status
# Video Management
GET /api/videos # List all recordings
GET /api/videos/stream/{streamer}/{filename} # Stream video
DELETE /api/videos/{id} # Delete recording
# Background Queue
GET /api/background-queue/stats # Queue statistics
GET /api/background-queue/active-tasks # Active tasks
POST /api/background-queue/cancel-stream/{id} # Cancel tasks
# System Health
GET /api/admin/test/health # Health check
POST /api/admin/test/recording-workflow # Test workflowAll API requests require session authentication. Use the same session cookie obtained through web interface login.
StreamVault supports local development without Docker:
Prerequisites:
- Python 3.12+
- Node.js 20+
- PostgreSQL 15+ (or use SQLite for testing)
Backend:
# Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Start development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000Frontend:
cd app/frontend
# Install dependencies
npm install
# Start development server (proxies API requests to backend)
npm run devQuick start script:
./dev.sh # Linux/Mac
dev.bat # Windowsstreamvault/
├── app/
│ ├── frontend/ # Vue 3 PWA
│ │ ├── src/
│ │ │ ├── components/ # Reusable components
│ │ │ ├── composables/ # Composition API logic
│ │ │ ├── views/ # Page components
│ │ │ └── styles/ # SCSS design system
│ │ └── dist/ # Built assets
│ ├── routes/ # FastAPI endpoints
│ ├── services/ # Business logic
│ │ ├── recording/ # Recording engine
│ │ ├── background_queue_service.py
│ │ └── metadata_service.py
│ ├── models.py # SQLAlchemy models
│ ├── schemas/ # Pydantic schemas
│ └── utils/ # Utilities
├── migrations/ # Database migrations
├── docker/ # Docker configuration
└── tests/ # Test suites
Backend:
- FastAPI (Python 3.12+)
- SQLAlchemy ORM
- PostgreSQL 15+
- Streamlink for recording
- FFmpeg for video processing
Frontend:
- Vue 3.5 with Composition API
- TypeScript 5.6
- Vite build system
- Pinia state management
- SCSS for styling
Infrastructure:
- Docker & Docker Compose
- GitHub Actions CI/CD
- AsyncIO task queue
# Backend tests
pytest tests/ -v
# Frontend type checking
cd app/frontend
npm run type-check
# Frontend linting
npm run lint- CPU: 2 cores
- RAM: 2GB
- Storage: 50GB
- Network: Stable internet connection
- CPU: 4+ cores
- RAM: 4GB
- Storage: 1TB+ SSD
- Network: High-speed connection for concurrent recordings
Warning
Stream recordings accumulate quickly. A single 4-hour stream at 1080p can be 8-15GB. Plan storage accordingly and configure cleanup policies.
Can I record multiple streams simultaneously?
Yes! StreamVault can record multiple streams at once. Resource usage scales with the number of concurrent recordings. Ensure adequate CPU and RAM for your recording count.
What quality options are available?
Without browser token: 160p, 360p, 480p, 720p, 1080p (H.264) With browser token: All above + 1440p (if available), H.265/HEVC, AV1 codecs
Browser token provides better compression and quality at smaller file sizes.
Can I run StreamVault without HTTPS?
No. Twitch EventSub webhooks require valid HTTPS with a trusted SSL certificate. Use Let's Encrypt (free) via Traefik, Caddy, Nginx, or Cloudflare Tunnel.
How do I migrate to a new server?
- Stop the container:
docker compose down - Copy the
recordings/directory and Docker volumes - Transfer
.envfile - Start on new server:
docker compose up -d
Database and metadata are stored in Docker volumes (app_data, app_logs, postgres_data).
Can I use this with other platforms like YouTube?
Currently StreamVault only supports Twitch. Multi-platform support is on the roadmap.
- Issues & Bugs: GitHub Issues
- Discussions: GitHub Discussions
When reporting issues, please include:
- StreamVault version
- Docker/OS version
- Relevant logs from
docker compose logs app - Steps to reproduce
StreamVault is built with excellent open-source projects:
- Streamlink - Stream extraction
- FastAPI - Modern Python web framework
- Vue.js - Progressive JavaScript framework
- FFmpeg - Video processing
- PostgreSQL - Database
- Twitch API - Stream data and webhooks
This project is licensed under the MIT License - see the LICENSE file for details.
StreamVault - Never miss a stream again