Aperture
Docker app from grtgbln's Repository
Aperture creates personalized recommendation libraries for your Emby and Jellyfin media server users using OpenAI embeddings and pgvector similarity search.
Requirements
Requires separate Jellyin/Emby media servers and pgvector database instances.
Overview
Readme
View on GitHubAperture
Version Docker Image License: AGPL v3
Aperture — AI-powered media recommendations for Emby & Jellyfin.
Aperture creates personalized recommendation libraries for your media server users using OpenAI embeddings and pgvector similarity search. Recommendations appear as virtual libraries in your media server's home screen, with support for both movies and TV series.
Quick Start
1. Download the docker-compose file for your platform
| Platform | File | Download |
|---|---|---|
| Unraid | docker-compose.unraid.yml |
Download |
| QNAP | docker-compose.qnap.yml |
Download |
| Synology | docker-compose.synology.yml |
Download |
| Windows | docker-compose.windows.yml |
Download ¹ |
| Linux/Other | docker-compose.prod.yml |
Download |
¹ Windows Users: For Docker Desktop with Emby/Jellyfin running natively on Windows, see the complete setup guide.
2. Configure the file
Edit the docker-compose file and set:
APP_BASE_URL— Your server's IP address (e.g.,http://192.168.1.100:3456)SESSION_SECRET— A random string (32+ characters)- Volume paths — Adjust to match your media folder locations
3. Create required folders
# Example for Unraid - adjust paths for your platform
mkdir -p /mnt/user/Media/ApertureLibraries
mkdir -p /mnt/user/appdata/aperture/backups
4. Start Aperture
docker-compose -f docker-compose.[your-platform].yml up -d
5. Complete the Setup Wizard
Open http://YOUR_SERVER_IP:3456 and follow the 11-step guided setup:
- Restore (Optional) — Restore from an existing backup if migrating
- Media Server — Connect to your Emby/Jellyfin server
- Source Libraries — Select which libraries to analyze
- File Locations — Configure path mappings for symlinks/STRM
- AI Recommendations — Configure library naming and cover images
- Validate — Verify output configuration and paths
- Users — Select which users receive recommendations
- Top Picks (Optional) — Configure global trending libraries
- AI / LLM — Enter your OpenAI API key (or configure Ollama/other providers)
- Initial Jobs — Run first-time sync with real-time progress
- Complete — Review summary and next steps
6. Log in
Use your Emby/Jellyfin admin credentials to access Aperture.
Updating
Use ghcr.io/dgruhin-hrizn/aperture:latest for published stable releases, or pin this release with ghcr.io/dgruhin-hrizn/aperture:1.0.3. Use :dev only to follow published development builds. To switch channels, change the image tag before pulling and recreating the app. Changing branches or restarting an existing container does not pull a new image.
Back up PostgreSQL and uploaded artwork, keep the existing database/mounts, pull the selected app image and recreate the app container. Refresh the page and check /health for the version and database connection. Supplied production configurations apply pending migrations at startup.
docker-compose -f docker-compose.[your-platform].yml pull
docker-compose -f docker-compose.[your-platform].yml up -d
Features
AI Recommendations
- Personalized Libraries — Creates dedicated "AI Picks" libraries for each user
- Configurable Embeddings — Semantic vectors for all your media
- pgvector Similarity — Vector similarity retrieval
- Configurable Algorithm — Tune weights for similarity, novelty, rating, and diversity
Media Support
- Movies — Full movie library sync with metadata, ratings, and watch history
- TV Series — Complete series and episode tracking with per-show recommendations
- Watch History — Automatic sync of viewing history including play counts and favorites
Rating System
- 10-Heart Ratings — Rate content from 1-10 hearts (Trakt.tv compatible)
- Rate from Any Poster — Click the heart icon on any poster
- Trakt.tv Sync — Bidirectional sync of ratings with Trakt
Personalization
- AI Taste Profiles — Natural language descriptions of user preferences
- Match Scores — Ranking signals for recommendation fit, not a calibrated probability of enjoyment
- Recommendation Insights — Detailed breakdown of why each title was recommended
Top Picks (Global)
- Popularity-Based Content — Trending content across all users
- Multiple Output Modes — Libraries, Collections, and/or Playlists
- Rank Badges — Gold, silver, bronze badges for top 3 on posters
Output compatibility
Generated libraries can use STRM pointers or symlinks. Choose according to the media-server deployment and output storage; symlinks are not universally recommended. Native Windows Emby with Aperture in Linux Docker should use STRM. FAT32/exFAT output cannot store native symlinks. Original media can be on another filesystem if its target remains readable. Neither format guarantees Direct Play.
Read output formats and compatibility and file locations. Version 1.0.2 adds shared guidance and compatibility checks at setup and output settings. A successful filesystem check still needs an actual movie/episode playback test.
Symlinks & Artwork
- Source Artwork Links — Symlinks banner.jpg, clearlogo.png, landscape.jpg, and more
- Optional Subtitle Sidecars — Accessible supported sidecars can be linked and renamed; source mounts and symlink support are required
- Custom NFOs — Aperture generates NFOs with AI explanations while preserving original artwork
Backup & Restore
- Automatic Daily Backups — Database backed up at 2 AM (configurable)
- Restore During Setup — Restore from backup when setting up a new instance
- Admin Panel Restore — Restore from the Admin → Settings → System tab
- Configurable Retention — Set how many backups to keep
Admin Features
- Setup Wizard — Guided first-time configuration
- Job Management — Real-time progress, scheduling, and history
- Encore Workspace — Conversations, memory, watch plans, approved Emby playlist actions, MCP connections and opt-in recurring curation
- Configurable Schedules — All job schedules adjustable via Admin → Jobs
- User Management — Per-user recommendation settings
- Cost Estimator — Built-in OpenAI API cost estimation
Default Job Schedules
All schedules are configurable in Admin → Jobs.
| Job | Default Schedule |
|---|---|
| Database Backup | Daily at 2 AM |
| User Sync | Every 30 minutes |
| Movie / TV Catalog | Every 3 hours at :00 / :10 |
| Movie / TV Publishing | Every 3 hours at :20 / :30 |
| Movie / TV Embeddings | Every 6 hours at :10 / :20 |
| AI Recommendations | Weekly on Sunday at 4 AM |
| Top Picks | Daily at 5 AM |
| Movie Watch History | Every 2 hours at :15 |
| TV Watch History | Every hour at :05 |
| Watching / Favorites | Every hour at :45 |
| Metadata Enrichment | Every 6 hours |
Documentation
| Guide | Description |
|---|---|
| 1.0.3 release notes | Encore chat agent overlay, readable conversations, and chat deletion fix |
| 1.0.2 release notes | STRM/symlink guidance, output compatibility checks, and current documentation |
| 1.0.1 release notes | Emby stability, accurate job schedules, search, recommendations, and Encore styles |
| 1.0.0 release notes | Encore, mobile and Home Screen updates, and upgrade notes |
| 0.7.11 release notes | Emby publishing, recommendation freshness, and upgrade notes |
| Admin Guide | Setup walkthrough, job management, algorithm tuning |
| User Guide | Features for end users, ratings, channels |
| Configuration | Volume setup, reverse proxy, Trakt integration |
| API Reference | Complete API endpoint documentation |
| Architecture | Technical overview, recommendation pipeline, database schema |
| Development | Local dev setup, scripts, contribution guidelines |
Tech Stack
- Backend: Fastify, TypeScript, PostgreSQL, pgvector
- Frontend: React, Vite, MUI, React Router
- AI: Configurable embedding and language providers, with shared Encore tools
- Infrastructure: Docker, pnpm workspaces
License
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/dgruhin-hrizn/aperture:latestRuntime arguments
- Web UI
http://[IP]:[PORT:3456]/- Network
bridge- Privileged
- false
- Extra Params
--user 099:100
Template configuration
Container Port: 3456
- Target
- 3456
- Default
- 3456
- Value
- 3456
Database connection URL
- Target
- DATABASE_URL
- Default
- postgresql://aperture:password@IP_ADDRESS:5432/aperture
- Value
- postgresql://aperture:password@IP_ADDRESS:5432/aperture
Base URL for accessing the application
- Target
- APP_BASE_URL
- Default
- http://IP_ADDRESS:3456
- Value
- http://IP_ADDRESS:3456
Secret key, at least 32 characters
- Target
- SESSION_SECRET
Path where Aperture libraries will be stored. Should be inside your existing media server's library path.
- Target
- /aperture-libraries
Path to the root of your media library.
- Target
- /media
Path where backups will be stored
- Target
- /backups
- Default
- /mnt/user/appdata/aperture/backups
- Value
- /mnt/user/appdata/aperture/backups
Whether to run database migrations on container start
- Target
- RUN_MIGRATIONS_ON_START
- Default
- true|false
Set the Node environment. Not recommended to change.
- Target
- NODE_ENV
- Default
- production
- Value
- production
Internal port the application listens on. Not recommended to change.
- Target
- PORT
- Default
- 3456
- Value
- 3456