Aperture

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.

¹ Windows Users: For Docker Desktop with Emby/Jellyfin running natively on Windows, see the complete setup guide.

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

# Example for Unraid - adjust paths for your platform
mkdir -p /mnt/user/Media/ApertureLibraries
mkdir -p /mnt/user/appdata/aperture/backups

docker-compose -f docker-compose.[your-platform].yml up -d

Open http://YOUR_SERVER_IP:3456 and follow the 11-step guided setup:

1. Restore (Optional) — Restore from an existing backup if migrating
2. Media Server — Connect to your Emby/Jellyfin server
3. Source Libraries — Select which libraries to analyze
4. File Locations — Configure path mappings for symlinks/STRM
5. AI Recommendations — Configure library naming and cover images
6. Validate — Verify output configuration and paths
7. Users — Select which users receive recommendations
8. Top Picks (Optional) — Configure global trending libraries
9. AI / LLM — Enter your OpenAI API key (or configure Ollama/other providers)
10. Initial Jobs — Run first-time sync with real-time progress
11. Complete — Review summary and next steps

Use your Emby/Jellyfin admin credentials to access Aperture.

docker-compose -f docker-compose.[your-platform].yml pull
docker-compose -f docker-compose.[your-platform].yml up -d

• Personalized Libraries — Creates dedicated "AI Picks" libraries for each user
• OpenAI Embeddings — Semantic vectors for all your media
• pgvector Similarity — Lightning-fast vector similarity search
• Configurable Algorithm — Tune weights for similarity, novelty, rating, and diversity

• 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

• 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

• AI Taste Profiles — Natural language descriptions of user preferences
• Match Scores — Personalized percentage scores showing recommendation fit
• Recommendation Insights — Detailed breakdown of why each title was recommended

• 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

• Full Artwork Preservation — Symlinks banner.jpg, clearlogo.png, landscape.jpg, and more
• Smart Subtitle Handling — Subtitles are symlinked and renamed to match video files
• Custom NFOs — Aperture generates NFOs with AI explanations while preserving original artwork

• Automatic Daily Backups — Database backed up at 1 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

• Setup Wizard — Guided first-time configuration
• Job Management — Real-time progress, scheduling, and history
• Configurable Schedules — All job schedules adjustable via Admin → Jobs
• User Management — Per-user recommendation settings
• Cost Estimator — Built-in OpenAI API cost estimation

All schedules are configurable in Admin → Jobs.

• Backend: Fastify, TypeScript, PostgreSQL, pgvector
• Frontend: React, Vite, MUI, React Router
• AI: OpenAI Embeddings & GPT models
• Infrastructure: Docker, pnpm workspaces

GNU Affero General Public License v3.0