README
¶
ViewRA
A self-hosted media server for organizing and streaming your personal media collections.
ViewRA brings a polished "Cinema at Home" experience to your movies, TV shows, and music. Stream anywhere with adaptive bitrate, get rich metadata from TMDb and MusicBrainz, and discover content with AI-powered search.
Features
Library Management
- Automatic scanning with metadata extraction (FFmpeg, NFO, ID3)
- Movies, TV Shows, and Music support
- Image caching (WebP, multiple sizes)
- Watch progress tracking (per-user)
Streaming
- HLS streaming with adaptive bitrate
- On-demand transcoding via FFmpeg
- Quality selection controls
- Subtitle extraction and delivery
Discovery
- Global search with autocomplete
- AI-powered semantic search ("movies like Blade Runner")
- Personalized recommendations ("For You", "Because You Watched")
- Home screen with customizable widgets
Metadata Enrichment
- TMDb integration (movies, TV shows, artwork)
- MusicBrainz integration (music, cover art)
- Extensible plugin system for additional sources
User Experience
- User authentication with JWT
- Per-user watch progress and ratings (up/down/favorite)
- "Cinema at Home" design aesthetic
- Stats for Nerds panel
Quick Start
Prerequisites
- Go 1.21+
- Node.js 18+
- Rust/Cargo (for subtitle-extractor)
- FFmpeg
Setup
# Clone the repository
git clone https://github.com/viewra/viewra.git
cd viewra
# Initial setup (installs Go tools, checks Rust)
make setup
# Build the subtitle extraction tool
make build-tools
# Start development server (backend :8080, frontend :5173)
make dev
Open http://localhost:5173 in your browser. Default credentials: dev / dev
Production Build
# Build everything: tools, frontend, backend
make build
# Build plugins
make build-plugins
Architecture
ViewRA uses Clean Architecture with Domain-Driven Design:
internal/
├── domain/ # Business logic (no external deps)
├── application/ # Use cases and services
├── infrastructure/ # DB, FFmpeg, filesystem
├── api/ # HTTP handlers
└── app/ # Dependency wiring
plugins/ # gRPC enrichment plugins
web/ # React frontend (TanStack Router)
- Database: SQLite (default) or PostgreSQL
- Streaming: HLS with on-demand transcoding
- Plugins: gRPC-based plugin system with SDK
Plugins
ViewRA ships with 8 plugins:
| Plugin | Purpose |
|---|---|
| TMDb | Movie/TV metadata and artwork |
| MusicBrainz | Music metadata and cover art |
| Semantic Search | AI-powered natural language search |
| Recommendations | Personalized content suggestions |
| AI Features | AI configuration + Ollama provider |
| AI Provider Anthropic | Claude integration |
| AI Provider OpenAI | GPT integration |
| AI Provider Voyage | Voyage embeddings |
Build your own plugins with the SDK in pkg/plugin/sdk/.
Documentation
- Architecture - System design and layers
- Development Conventions - Code style and patterns
- HLS Transcoding Guide - How streaming works
- Plugin Development - Building plugins
- Operations Guide - Deployment and configuration
See docs/README.md for the full documentation index.
License
MIT
Directories
¶
| Path | Synopsis |
|---|---|
|
Package swagger Code generated by swaggo/swag.
|
Package swagger Code generated by swaggo/swag. |
|
swagger
Package swagger Code generated by swaggo/swag.
|
Package swagger Code generated by swaggo/swag. |
|
proto/plugin
module
|
|
|
cmd
|
|
|
genhash
command
genhash generates bcrypt password hashes for ViewRA user accounts.
|
genhash generates bcrypt password hashes for ViewRA user accounts. |
|
sqlc-gen
command
Command sqlc-gen performs post-processing on sqlc-generated code to enable a unified database layer that works with both SQLite and PostgreSQL.
|
Command sqlc-gen performs post-processing on sqlc-generated code to enable a unified database layer that works with both SQLite and PostgreSQL. |
|
taskgen
command
Command taskgen generates scheduler task registration code.
|
Command taskgen generates scheduler task registration code. |
|
test_type
command
|
|
|
viewra
command
|
|
|
internal
|
|
|
api/handlers
Package handlers provides HTTP request handlers for the ViewRA API.
|
Package handlers provides HTTP request handlers for the ViewRA API. |
|
app/lifecycle
Package lifecycle provides server lifecycle management including graceful restart.
|
Package lifecycle provides server lifecycle management including graceful restart. |
|
application/enrichment
Package enrichment provides the unified Enricher interface for all enrichment stages in the media enrichment pipeline.
|
Package enrichment provides the unified Enricher interface for all enrichment stages in the media enrichment pipeline. |
|
application/enrichment/builtin
Package builtin contains built-in enrichers that run in-process.
|
Package builtin contains built-in enrichers that run in-process. |
|
application/library/scan
Package scan provides core types and sub-packages for library scanning.
|
Package scan provides core types and sub-packages for library scanning. |
|
application/plugins
Package plugins provides the application layer service for managing plugins.
|
Package plugins provides the application layer service for managing plugins. |
|
application/scheduler
Package scheduler provides the application-level scheduler service.
|
Package scheduler provides the application-level scheduler service. |
|
application/transcode_analytics
Package transcodeanlytics provides transcode analytics collection and querying.
|
Package transcodeanlytics provides transcode analytics collection and querying. |
|
domain/enrichment
Package enrichment defines domain types and interfaces for the media enrichment system.
|
Package enrichment defines domain types and interfaces for the media enrichment system. |
|
domain/events
Package events defines domain types for the ViewRA event system.
|
Package events defines domain types for the ViewRA event system. |
|
domain/streaming
Package streaming provides domain types for adaptive streaming quality profiles.
|
Package streaming provides domain types for adaptive streaming quality profiles. |
|
infrastructure/crypto
Package crypto provides encryption utilities for sensitive data at rest.
|
Package crypto provides encryption utilities for sensitive data at rest. |
|
infrastructure/database/unified
Package unified provides a database-agnostic interface for sqlc-generated code.
|
Package unified provides a database-agnostic interface for sqlc-generated code. |
|
infrastructure/events
Package events provides the event bus infrastructure for ViewRA.
|
Package events provides the event bus infrastructure for ViewRA. |
|
infrastructure/events/bus
Package bus provides the event bus implementation for ViewRA.
|
Package bus provides the event bus implementation for ViewRA. |
|
infrastructure/events/slog
Package slog provides slog.Handler implementations that bridge Go's structured logging with the ViewRA event bus.
|
Package slog provides slog.Handler implementations that bridge Go's structured logging with the ViewRA event bus. |
|
infrastructure/ffmpeg
Package ffmpeg provides video processing functionality using FFmpeg.
|
Package ffmpeg provides video processing functionality using FFmpeg. |
|
infrastructure/ffmpeg/hls
Package hls provides FFmpeg command building for HLS transcoding.
|
Package hls provides FFmpeg command building for HLS transcoding. |
|
infrastructure/ffmpeg/paths
Package paths provides FFmpeg binary path resolution and command preparation.
|
Package paths provides FFmpeg binary path resolution and command preparation. |
|
infrastructure/ffmpeg/probe
Package probe provides video metadata extraction using ffprobe.
|
Package probe provides video metadata extraction using ffprobe. |
|
infrastructure/ffmpeg/process
Package process provides FFmpeg process lifecycle management.
|
Package process provides FFmpeg process lifecycle management. |
|
infrastructure/ffmpeg/thumbnail
Package thumbnail provides video thumbnail generation using FFmpeg.
|
Package thumbnail provides video thumbnail generation using FFmpeg. |
|
infrastructure/filesystem
Package filesystem provides file system operations for media scanning.
|
Package filesystem provides file system operations for media scanning. |
|
infrastructure/images
Package images provides image processing and caching services.
|
Package images provides image processing and caching services. |
|
infrastructure/metadata/quality
Package quality provides heuristic quality scoring for media files.
|
Package quality provides heuristic quality scoring for media files. |
|
infrastructure/persistence/location
Package location provides persistence for user location preferences.
|
Package location provides persistence for user location preferences. |
|
infrastructure/persistence/plugins
Package plugins provides persistence for plugin management.
|
Package plugins provides persistence for plugin management. |
|
infrastructure/persistence/scheduler
Package scheduler provides persistence for scheduler task management.
|
Package scheduler provides persistence for scheduler task management. |
|
infrastructure/plugins
Package plugins provides the plugin infrastructure for ViewRA.
|
Package plugins provides the plugin infrastructure for ViewRA. |
|
infrastructure/plugins/fetcher
Package fetcher provides implementations for fetching data from plugins.
|
Package fetcher provides implementations for fetching data from plugins. |
|
infrastructure/plugins/github
Package github provides a client for fetching plugin releases from GitHub.
|
Package github provides a client for fetching plugin releases from GitHub. |
|
infrastructure/plugins/grpc
Package grpc provides gRPC plugin implementations for the go-plugin framework.
|
Package grpc provides gRPC plugin implementations for the go-plugin framework. |
|
infrastructure/plugins/host
Package host provides gRPC server implementations for host services exposed to plugins.
|
Package host provides gRPC server implementations for host services exposed to plugins. |
|
infrastructure/plugins/manager
Package manager provides the plugin Manager for loading, managing, and monitoring plugins.
|
Package manager provides the plugin Manager for loading, managing, and monitoring plugins. |
|
infrastructure/plugins/manifest
Package manifest provides parsing and validation for plugin.yml manifest files.
|
Package manifest provides parsing and validation for plugin.yml manifest files. |
|
infrastructure/plugins/proxy
Package proxy provides HTTP proxying for plugin routes.
|
Package proxy provides HTTP proxying for plugin routes. |
|
infrastructure/plugins/registry
Package registry provides route, provider, and capability registries for plugins.
|
Package registry provides route, provider, and capability registries for plugins. |
|
infrastructure/plugins/types
Package types provides shared types for the plugins infrastructure.
|
Package types provides shared types for the plugins infrastructure. |
|
infrastructure/transcoding/config
Package config provides transcoding configuration types and defaults.
|
Package config provides transcoding configuration types and defaults. |
|
infrastructure/transcoding/executor
Package executor provides FFmpeg command execution and job lifecycle management.
|
Package executor provides FFmpeg command execution and job lifecycle management. |
|
infrastructure/transcoding/logging
Package logging provides FFmpeg log management for transcoding sessions.
|
Package logging provides FFmpeg log management for transcoding sessions. |
|
infrastructure/transcoding/paths
Package paths provides HLS output path utilities for transcoding.
|
Package paths provides HLS output path utilities for transcoding. |
|
infrastructure/transcoding/profile
Package profile provides quality profile definitions and recommendations for adaptive streaming.
|
Package profile provides quality profile definitions and recommendations for adaptive streaming. |
|
infrastructure/transcoding/retry
Package retry provides retry logic with exponential backoff for transient failures.
|
Package retry provides retry logic with exponential backoff for transient failures. |
|
infrastructure/transcoding/segment
Package segment provides HLS segment number calculations and filename utilities.
|
Package segment provides HLS segment number calculations and filename utilities. |
|
infrastructure/transcoding/session
Package session provides transcode session lifecycle management.
|
Package session provides transcode session lifecycle management. |
|
infrastructure/transcoding/storage
Package storage provides disk space checking and size estimation utilities for the transcoding system.
|
Package storage provides disk space checking and size estimation utilities for the transcoding system. |
|
infrastructure/transcoding/strategy
Package strategy provides stream strategy determination for transcoding decisions.
|
Package strategy provides stream strategy determination for transcoding decisions. |
|
infrastructure/transcoding/validation
Package validation provides path validation and sanitization utilities for secure file operations in the transcoding system.
|
Package validation provides path validation and sanitization utilities for secure file operations in the transcoding system. |
|
infrastructure/transcoding/videoinfo
Package videoinfo provides video file analysis using ffprobe.
|
Package videoinfo provides video file analysis using ffprobe. |
|
infrastructure/weather
Package weather provides weather context for search features.
|
Package weather provides weather context for search features. |
|
testutil/mocks
Package mocks provides centralized mock implementations for testing.
|
Package mocks provides centralized mock implementations for testing. |
|
pkg
|
|
|
plugin/sdk
module
|
|
Click to show internal directories.
Click to hide internal directories.