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.

Quick Start

1. Download the docker-compose file for your platform

¹ 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:

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

6. Log in

Use your Emby/Jellyfin admin credentials to access Aperture.

Updating

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
• 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

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 — Personalized percentage scores showing recommendation fit
• 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

Symlinks & Artwork

• 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

Backup & Restore

• 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

Admin Features

• 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

Default Job Schedules

All schedules are configurable in Admin → Jobs.

Documentation

Tech Stack

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

License

GNU Affero General Public License v3.0