A self-hosted YouTube video archiver with a modern web interface. Download, manage, and organize your YouTube videos, playlists, and channels locally.
Caution
This project is in early development (alpha stage). It may contain bugs, break unexpectedly, or have incomplete features. Use at your own risk.
Video Archiver allows you to download and organize videos from YouTube for offline viewing. The application consists of a Go backend that handles the actual downloading and management of videos, plus a modern Next.js frontend that provides a clean interface for interacting with your media collection.
- Download videos, playlists, and channels from YouTube URLs
- Real-time download progress tracking via WebSocket
- Queue management for multiple downloads
- Modern responsive web interface
- Dark/Light/System theme support
- Dashboard with comprehensive statistics about your media collection
- Complete metadata extraction and display (videos, playlists, channels)
- Quality selection (360p, 480p, 720p, 1080p, 1440p, 4K)
- Configurable concurrent downloads (1-10 simultaneous downloads)
- Video Processing Tools:
- Trim videos to specific time ranges
- Concatenate multiple videos into one
- Extract audio in various formats (MP3, AAC, FLAC, WAV)
- Convert between video formats (MP4, WebM, AVI, MKV)
- Adjust video quality and bitrate
- Rotate videos (90°, 180°, 270°)
- Create custom workflows (chain multiple operations)
- Real-time progress tracking for tool operations
- Enhanced metadata management and organization
- Advanced search and categorization
- Mobile-friendly streaming interface
- User authentication and multiple user support
- Download scheduling
- API documentation for integrations with other applications
- Playlist and channel organization features
- Backend: Go 1.23.2 with Chi router
- Frontend: Next.js 15.4.7 with TypeScript 5.8.3
- UI: shadcn/ui components with Radix UI primitives
- State Management: Zustand 5.0+
- Real-time Updates: WebSocket (Gorilla WebSocket)
- Database: SQLite 3
- Media Handling: yt-dlp and ffmpeg
- Styling: Tailwind CSS 4.1.4
- Runtime: React 19.1.0
- Docker and Docker Compose
- Git
- Bash shell (for running the management script)
- Clone the repository:
git clone https://github.com/Fx64b/video-archiver.git
cd video-archiver- Set environment variables:
cp web/.env.local.example web/.env.local- Start the application:
./run.shThe web interface will be available at http://localhost:3000
./run.sh [options]
Options:
--clear Clear the database and downloads
--build Rebuild the containers and regenerate TypeScript types
--debug Enable debug logging in backend
--backend-only Start only the backend service
--test Run backend unit tests
--test-verbose Run backend tests with verbose output
--test-coverage Run backend tests with coverage report
--help|-h Show help messageCommon use cases:
- Fresh start:
./run.sh --clear --build - Development:
./run.sh --build --debug - Production:
./run.sh - Testing:
./run.sh --testor./run.sh --test-coverage
- Go 1.23.2 or higher
- SQLite 3
- yt-dlp (latest version recommended)
- ffmpeg (latest version recommended)
- tygo (for TypeScript type generation):
go install github.com/gzuidhof/tygo@latest
- Node.js 20+ (LTS recommended)
- pnpm 9+
Refer to the backend and frontend directories for specific setup instructions.
/services/backend: Go backend service- Handles video downloads via yt-dlp
- Manages download queue and progress tracking
- Provides API endpoints and WebSocket updates
- SQLite database for metadata storage
/web: Next.js frontend application- Modern UI built with shadcn/ui
- Real-time progress tracking
- Download management interface
- Statistics dashboard
The application can be configured through environment variables:
DEBUG: Enable debug logging (default: false)DOWNLOAD_PATH: Directory for downloaded media (default: ./data/downloads)PROCESSED_PATH: Directory for processed/converted videos (default: ./data/processed)DATABASE_PATH: Path to SQLite database (default: ./data/db/video-archiver.db)PORT: API server port (default: 8080)WS_PORT: WebSocket server port (default: 8081)
NEXT_PUBLIC_SERVER_URL: URL for backend API (default: http://localhost:8080)NEXT_PUBLIC_SERVER_URL_WS: URL for WebSocket connection (default: ws://localhost:8081)
After a certain number of downloads, YouTube may block requests that are not made through the official site or app. This is a known issue: yt-dlp/yt-dlp#11868
Possible workarounds:
- Use a VPN and switch servers when the limit is reached
- Wait a few hours before attempting downloads again
- Use a different IP address if possible
Some metadata might not be properly extracted for certain types of content, particularly channels and playlists.
We welcome contributions to Video Archiver! Here's how you can help:
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes using Conventional Commits format
- Examples:
feat(ui): Add video thumbnails,fix(api): Resolve playlist download issue
- Examples:
- Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Please ensure your code follows the project's style and includes appropriate tests.
For the best development experience:
- Use
./run.sh --build --debugto start the application with debug logging - For frontend-only changes, you can run the Next.js app directly:
cd web pnpm install pnpm dev - For backend-only changes, you can use the
--backend-onlyflag:./run.sh --build --backend-only
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
See the open issues for a list of proposed features and known issues.
- ✅
Q3 2025: Media streaming interface & Tools(Tools completed) - Q4 2025: Advanced search and tagging system
- 2026: User authentication, API documentation, and mobile-friendly streaming