Jump to content

Aperture - AI-Powered Recommendations for Emby


Recommended Posts

classiccollect1
Posted

Im very sorry thats not my intention i think most adults  would know that. I'm not here to be insulted so ill just bring it up with emby team. have been with  emby a long time. i only asked question  to gain knowledge.  That what this these post are for knowledge and development not petty chastising  i complimented the creator this his thread not yours if i offended him i will apologize to him  really who are you to troll some else post. GROW UP

  • Disagree 1
classiccollect1
Posted

My apologies To THEGRU i know the exchange wasnt  necessary. I truly was only looking for guidance, but you dont need your post filled  with this nonsense. Thank you anyways best of luck with your endeavors!

  • Disagree 1
TheGru
Posted
51 minutes ago, classiccollect1 said:

My apologies To THEGRU i know the exchange wasnt  necessary. I truly was only looking for guidance, but you dont need your post filled  with this nonsense. Thank you anyways best of luck with your endeavors!

Install docker desktop on Windows, go to the repo and read all the documentation, if you can't figure it out there is a Support Questionnaire in the repo you can copy, fill out and submit via PM

  • Like 1
TheGru
Posted

Aperture v0.5.0 Release Notes

Hey everyone! 👋

This is a major release with significant UI improvements, new features for content discovery, enhanced personalization, and a completely restructured documentation system.


✨ New Features

Collapsible Sidebar

The sidebar can now collapse to an icon-only view:

  • Toggle methods — Click the hamburger icon, click the Aperture logo, or use keyboard shortcut
  • Tooltips — Hover over icons in collapsed mode to see page names
  • Persistence — Your collapsed/expanded preference is saved to your account and syncs across devices
  • Responsive — Mobile drawer also respects your collapsed preference

Grid & List Views Everywhere

Most content pages now offer both Grid and List views:

Page List View Features
Browse Full metadata, synopsis, genres, ratings
Recommendations Match scores, evidence trail
Top Picks Viewer counts, play counts, watch status
Discovery Source badges, request status, genres
Watch History Last watched, play counts, progress
Shows You Watch Next episode, days until, progress

View Persistence — Your preferred view mode is saved per page and remembered across sessions.

Combined Browse Page

Movies and Series are now on a single Browse page with tabs:

  • Tab switching — Toggle between Movies and Series tabs
  • Independent filters — Each tab maintains its own filters and sort
  • Shared UI — Consistent experience across content types

Advanced Filters on Browse

The Browse page now has a powerful filtering system:

Filter Panel (click "Filters" button):

Filter Movies Series
Year Range
Runtime
Seasons
Community Rating
Rotten Tomatoes
Metacritic
Content Rating
Resolution
Status

Active filter chips appear below the filter bar showing what's applied.

Sticky filter bar stays visible as you scroll for easy access.

Sort Persistence

Your sort preferences on the Browse page are automatically saved:

  • Movies and Series have independent sort settings
  • Sort options include: Title, Year, Release Date, Rating, RT Score, Metacritic, Runtime, Seasons, Date Added
  • Settings sync to your account and persist across sessions

Filter Presets

Save your favorite filter combinations:

  • Save current filters — Name and save any filter combination
  • Load presets — One-click to apply saved filters
  • Manage presets — Rename or delete from Settings → Preferences
  • Per-content type — Movies and Series presets are stored separately

Combined Top Picks Page

Top Pick Movies and Top Pick Series are now on a single page with tabs:

  • Unified interface — Same design as Browse
  • List view — Shows viewer counts and play counts
  • Grid view — Poster grid with rank badges

Shows You Watch

A new page tracking TV series you're actively following:

  • Automatic tracking — Series appear based on your watch activity
  • Upcoming episodes — See next episode title and air date
  • Days until — Countdown to next episode
  • Progress tracking — Episodes watched vs total
  • Grid and List views — Your preference is saved
  • Frontend caching — 1-day TTL for performance

Explore Page (AI Semantic Graph)

A completely new way to discover content through visual connections:

  • Search to seed — Start with any title
  • AI-powered connections — Finds thematic relationships
  • Breadcrumb navigation — Track your exploration path
  • Hide watched toggle — Focus on new content
  • Primary node highlighting — Clear visual hierarchy
  • Color-coded edges — Blue (cast), Green (crew), Orange (genre), Purple (theme)
  • Create playlists — Save interesting discoveries

Enhanced Watcher Identity

Your taste profile is now more powerful:

  • Embedding-powered analysis — AI generates abstract taste descriptions
  • Watch history sources — Exclude specific libraries from analysis
  • Franchise weights — Adjust or delete detected franchises
  • Genre weights — Fine-tune genre influence
  • Minimum franchise items — Filter noise from small franchises
  • Reset functionality — Clear all or per-media type

Playlist Enhancements

Playlists page has been redesigned:

  • Poster collages — Cards show preview of 4 items
  • Clickable cards — View playlist contents in a dialog
  • Redesigned New Playlist dialog — Modern design language
  • Item counts and descriptions — More information at a glance

Heart Rating on All List Views

The heart rating component is now available everywhere:

  • Consistent placement — Same location on all list view items
  • Inline rating — Rate without opening detail pages
  • Grid view overlay — Hover to reveal (existing behavior preserved)
  • Fixed clickability — Resolved issues with ratings being under overlays

Navigation Improvements

  • Home → Dashboard — Renamed for clarity
  • Icon updates — Explore uses hub icon, Discover uses compass
  • Search moved — Now on right side of toolbar as icon button
  • Mobile improvements — Centered logo, hamburger on left

Discovery Improvements

  • Skeleton loaders — Shows placeholders during refresh
  • Genre preservation — Fixed missing genre names
  • Caching — Frontend caching for performance
  • List view — Full metadata display

🔧 Technical Improvements

User Sync Job

New dedicated job to automatically import users from your media server:

  • Automatic sync — Runs every 30 minutes to detect new Emby/Jellyfin users
  • Manual sync button — Click "Sync Users" on the Admin → Users page for immediate import
  • Admin status sync — Keeps admin permissions in sync with your media server

User Email Settings

Users can now manage their email in Settings → Profile:

  • Email input — Enter or update your email address
  • Auto-lock — If you manually set your email, it won't be overwritten by media server sync
  • Notification opt-out — Toggle email notifications on/off (placeholder for future features)
  • Notification system is TBD

User Algorithm Weights

Users can now customize their own recommendation algorithm weights:

  • New Settings Tab — "AI Algorithm" tab in User Settings
  • Override admin defaults — Adjust weights for Movies and Series independently
  • Auto-normalizing — Set any values you want; the backend automatically normalizes to 100%
  • Auto-save — Changes save automatically as you adjust sliders

Libraries Excluded from Global Search

AI-generated libraries are now excluded from global search in Emby/Jellyfin:

  • 🍿 AI Movie Recommendations
  • 📺 AI Series Recommendations
  • 🏆 Top Picks libraries
  • 👀 Shows You Watch libraries

Library Default Sort: Date Added

AI recommendation libraries now default to "Date Added" sort (newest first).

No Duplicates in Continue Watching

Aperture libraries no longer cause duplicate entries in Continue Watching through improved NFO file generation.


🐛 Bug Fixes

Library Options Fix (CollectionType Preservation)

Fixed a critical bug where AI-generated libraries were being created with incorrect collection types.

Metadata Sync Fix

Fixed an issue where posters and metadata wouldn't update for movies/series that already existed.

Top Picks Viewer Stats

Fixed an issue where Top Picks showed all zeros for viewer data when using MDBList source. Local watch data is now included regardless of popularity source.

Rating Timestamps

Fixed an issue where all ratings showed today's date after a Trakt sync.

AI Explanation Batch Size

The recommender now automatically adapts explanation generation based on your AI provider's context window.

Watch History Sync

Full sync is now the default, ensuring all watched items are captured.

Similar Content & Search Fix

Fixed database errors that broke similar content lists and semantic search.

Genre Names on Discovery

Fixed an issue where genre names weren't rendering in Discovery list view.


🎨 UI Improvements

Settings Page Consistency

User Settings pages redesigned with:

  • Card-based layout
  • Dynamic accent colors (indigo for movies, pink for series)
  • Debounced auto-save
  • Clean slider labels

Renamed Library Build Jobs

Old Name New Name
Sync Movie Libraries Build Aperture Movie Libraries
Sync Series Libraries Build Aperture Series Libraries

Two-Column Recently Watched

Dashboard's Recently Watched now shows Movies and Series in separate columns.

Improved Time Display

  • Recently Watched shows months/years for older items
  • Recent Ratings shows "Rated on Jan 11, 2026" format

📚 Documentation

The documentation has been completely restructured:

  • New TOC formatuser-guide.md is now a table of contents
  • Individual feature docs — 28 separate feature documentation files
  • Workflow-based organization — From setup through advanced features
  • Comprehensive coverage — Every page, setting, and feature documented

🚀 Update Instructions

For Existing Docker Users

# Pull the latest image
docker compose pull

# Restart with new version
docker compose up -d

For New Docker Users

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
Linux/Other docker-compose.prod.yml Download

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

See examples in the Docker Compose Files.

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 guided setup

Post-Update Steps

  • Clear browser cache — Ensures you get the new UI
  • Re-run library jobs — If you want the latest library improvements
  • Check your sidebar — Collapse/expand to set your preference

Enjoy the improvements! 🍿

  • Like 1
TheGru
Posted (edited)

Unless there are huge issues, I am probably going to be taking a break from working on this for a week or so. This was a marathon, and while fun the amount of money I have burned on Anthropic Claude Opus 4.5 inside of Cursor to accomplish this in a week has been quite significant. 

So if you find Aperture useful or you just want to support cool projects feel free to buy me a beer or make a donation!

Edited by TheGru
  • Thanks 3
TheGru
Posted

Aperture v0.5.1 Release Notes

Well I lied... but now I am done for a bit!!!

This is a mobile-focused release with significant improvements to the mobile browsing experience across all list views.


📱 Mobile UI Improvements

Compact Horizontal List Items

All list view items have been redesigned for mobile with a compact horizontal layout inspired by Spotify and Netflix:

Before After
Stacked vertical cards Horizontal poster + content layout
Large posters taking full width Compact 100px posters maintaining aspect ratio
Hidden or truncated content 2-line synopsis, inline metadata
Actions in separate panel Inline action buttons

Pages updated:

  • Browse (Movies & Series)
  • My Recommendations
  • Top Picks
  • Discover
  • Watch History
  • Shows You Watch

Consistent Header Layout

The grid/list toggle is now always in the upper right of the header on mobile:

[Icon] Page Title            [⊞][☰]
[Action buttons if any]
[Tabs/Filters]

This provides a consistent, predictable location for view switching across all pages.

Decluttered Mobile Headers

Mobile headers are now cleaner and more focused:

  • Subtitles hidden — Page descriptions hidden on mobile to save space
  • Icon-only action buttons — Refresh, Sync, Add buttons show icons with tooltips
  • Reduced visual noise — Focus on content, not chrome

Shows You Watch Simplification

The Shows You Watch page received special attention:

  • Stats merged into tabs — "All (70) | Airing (67) | Upcoming (23)" instead of separate chips
  • Icon-only Sync/Add buttons — Compact with tooltips
  • Full-width filter tabs — Easier to tap on mobile

Purple & Pink Tab Styling

Consistent tab styling now applied across all tabbed pages:

  • Movies tab — Purple (#6366f1) with matching count chips
  • Series tab — Pink (#ec4899) with matching count chips
  • Applied to — Discover, Recommendations, Watch History, Top Picks

Watch History Sort Icons

Sort buttons on Watch History now show icons on mobile:

  • 🕐 Recent
  • 📈 Most Played
  • 🔤 A-Z

Full labels still shown on desktop.

image.png.b49170ace334266bae9275bdadbe7c73.png.        image.png.90b62bbb1d9c50a7eea86b325a6fe6d5.png

 

image.png.ea32d6ac7b2adba7b1bf78c1ef25c113.png.         image.png.f51e82921aae89feb804d6dd1104f7d0.png

image.png.5a7d79c8390a32c18ebdc4d43a4d0154.png.          image.png.dce8f9cd5c83092479e3880a5925e887.png

 


🐛 Bug Fixes

View Mode Persistence Fixed

Fixed a bug where view mode preferences weren't loading from the database:

  • Root cause — Frontend was looking for data.preferences.viewModes but API returns data.viewModes
  • Result — Your grid/list preferences now correctly load on page refresh

No More View Mode Flash

Eliminated the brief flash of default grid view when your preference is list:

  • Solution — View modes now cache in localStorage for instant loading
  • Sync — Server remains source of truth, localStorage is just a fast cache
  • Result — Page renders immediately with your saved preference

My Recommendations View Persistence

Fixed the My Recommendations page to use the shared view mode system:

  • Before — Used local state, preference wasn't saved
  • After — Uses useViewMode('recommendations') hook
  • Result — Your grid/list preference persists across sessions

🚀 Update Instructions

For Docker Users

# Pull the latest image
docker compose pull

# Restart with new version
docker compose up -d

Post-Update Steps

  • Clear browser cache — Or hard refresh (Cmd+Shift+R / Ctrl+Shift+R)
  • Clear localStorage (optional) — If you want a fresh start on view preferences

Enjoy the mobile improvements! 📱

  • Like 2
GoldSpacer
Posted
5 hours ago, TheGru said:

No Duplicates in Continue Watching

Aperture libraries no longer cause duplicate entries in Continue Watching through improved NFO file generation.

You did it you mad lad! Amazing work!

  • Like 1
TheGru
Posted
6 hours ago, GoldSpacer said:

You did it you mad lad! Amazing work!

I did it but it causes a problem. I realized this morning that because the Aperture items are no longer connected via tmdb ids to the original items the original items won’t get updated watch history ie. It was played. This then impacts Aperture’s ability to exclude watched from future recommendations. 
 

I am going to have to undo the fix. Or make it an option and explain the downsides. 
 

the fix is the Emby team to allow exclusion of libraries from Continue Watching but until that time we may just need to live with dupes 

akacharos
Posted (edited)
21 hours ago, TheGru said:

Install docker desktop on Windows, go to the repo and read all the documentation, if you can't figure it out there is a Support Questionnaire in the repo you can copy, fill out and submit via PM

Just a confirmation: If Emby and its Libraries are on Windows (using Windows paths like F:), I cannot use the symlink mode and must rely on strm mode, correct?

My understanding is that Aperture running in Docker would create a Linux symlink pointing to a Linux path (e.g., /media/Movies/Matrix.mp4). Windows Emby cannot follow this because It doesn't recognize the Linux symlink file type. Even if it did, the target path /media/... does not exist on Windows.

Therefore, I plan to use:
- LINK_TYPE=strm
- MEDIA_PATH_MAPPING=/media:F: (to ensure the .strm file contains the valid Windows path).

Edited by akacharos
TheGru
Posted (edited)
33 minutes ago, akacharos said:

Just a confirmation: If Emby and its Libraries are on Windows (using Windows paths like F:), I cannot use the symlink mode and must rely on strm mode, correct?

My understanding is that Aperture running in Docker would create a Linux symlink pointing to a Linux path (e.g., /media/Movies/Matrix.mp4). Windows Emby cannot follow this because It doesn't recognize the Linux symlink file type. Even if it did, the target path /media/... does not exist on Windows.

Therefore, I plan to use:
- LINK_TYPE=strm
- MEDIA_PATH_MAPPING=/media:F: (to ensure the .strm file contains the valid Windows path).

Windows Docker Desktop Setup Guide

This guide covers installing and configuring Aperture using Docker Desktop on Windows when your media server (Emby) is running directly on Windows (not in a container).

Overview

┌─────────────────────────────────────────────────────────────────┐
│  Windows PC                                                     │
│                                                                 │
│  ┌─────────────────┐     ┌─────────────────────────────────┐    │
│  │  Emby Server    │     │  Docker Desktop                 │    │
│  │  (native)       │     │  ┌─────────────────────────┐    │    │
│  │                 │◄────│──│  Aperture container     │    │    │
│  │  localhost:8096 │     │  │  uses:                  │    │    │
│  │                 │     │  │  host.docker.internal   │    │    │
│  └─────────────────┘     │  └─────────────────────────┘    │    │
│          │               └─────────────────────────────────┘    │
│          ▼                                                      │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Media (Local or Network Shares)                          │  │
│  │  C:\Media\Movies\                                         │  │
│  │  D:\TV Shows\                                             │  │
│  │  \\NAS\Media\Movies\  (network share)                     │  │
│  │                                                           │  │
│  │  C:\ApertureLibraries\  ← Aperture writes here            │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Key Points

  • STRM mode required — Symlinks don't work between a Linux container and Windows host
  • No media access needed — Aperture reads everything from Emby's API
  • Only one output folder — Aperture writes STRM files to a single location
  • Works with network shares — Your media can be on NAS devices; Emby handles the paths

Prerequisites

  • Windows 10/11 (64-bit)
  • Emby installed and running on Windows - Some of what Aperture does may require the latest Emby Beta Server. 
  • Admin access to your media server (for API key)
  • At least 4GB RAM available for Docker

Step 1: Install Docker Desktop

Download

Installation

  • During installation, ensure WSL 2 is selected (recommended)
  • Click Install
  • Restart Windows when prompted

First Launch

  • Open Docker Desktop from the Start menu
  • Accept the service agreement
  • Skip or complete the optional sign-in/survey
  • Wait for Docker to start (whale icon in system tray turns solid)

Verify Installation

Open PowerShell and run:

docker --version
docker-compose --version

Both commands should return version numbers.


Step 2: Prepare Folders

Create folders for Aperture's data. Open PowerShell and run:

# Create folders (adjust paths as needed)
mkdir C:\ApertureLibraries
mkdir C:\ApertureBackups

Using Network Shares

If you want Aperture's output on a NAS:

  • Ensure the network share is mapped or accessible
  • Create the folder on your NAS (e.g., \\NAS\Media\ApertureLibraries)
  • Note the Windows path (e.g., M:\Media\ApertureLibraries if mapped to M:)

Step 3: Get Your Configuration Ready

Find Your Windows IP Address

Open PowerShell and run:

ipconfig

Look for your IPv4 Address (e.g., 192.168.1.100).

Generate a Session Secret

  • Go to randomkeygen.com
  • Copy a Fort Knox Password (or any 32+ character random string)

Get Your Emby/Jellyfin API Key

For Emby:

  • Open Emby in your browser
  • Go to Dashboard → Advanced → API Keys
  • Click New API Key
  • Name it "Aperture" and copy the key

For Jellyfin:

  • Open Jellyfin in your browser
  • Go to Dashboard → API Keys
  • Click Add
  • Name it "Aperture" and copy the key

Step 4: Create the Docker Compose File

Option A: Download the Pre-made File

Download docker-compose.windows.yml from the Aperture repository and save it to a folder like C:\Aperture\.

Option B: Create Manually

  • Create a folder: C:\Aperture
  • Create a file named docker-compose.yml in that folder
  • Copy this content:
# =============================================================================
# Aperture - Windows Docker Desktop
# =============================================================================

services:
  db:
    image: pgvector/pgvector:pg16
    container_name: aperture-db
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: aperture
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U app -d aperture']
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  app:
    image: ghcr.io/dgruhin-hrizn/aperture:latest
    container_name: aperture
    user: root
    environment:
      NODE_ENV: production
      PORT: 3456
      DATABASE_URL: postgres://app:app@db:5432/aperture
      RUN_MIGRATIONS_ON_START: 'true'
      TZ: America/New_York
      # =========================================================================
      # REQUIRED: Set these values!
      # =========================================================================
      APP_BASE_URL: http://YOUR_WINDOWS_IP:3456
      SESSION_SECRET: PASTE_YOUR_RANDOM_KEY_HERE
    ports:
      - '3456:3456'
    depends_on:
      db:
        condition: service_healthy
    volumes:
      # Aperture Libraries Output
      - C:/ApertureLibraries:/aperture-libraries
      # Database Backups
      - C:/ApertureBackups:/backups
    restart: unless-stopped

volumes:
  pgdata:

Edit the Configuration

Open the file in Notepad and update:

Setting What to Change
APP_BASE_URL Replace YOUR_WINDOWS_IP with your actual IP (e.g., http://192.168.1.100:3456)
SESSION_SECRET Paste your random key from Step 3
TZ Your timezone in IANA format (e.g., Europe/London, America/Los_Angeles)
Volume paths Adjust C:/ApertureLibraries and C:/ApertureBackups if using different locations

Volume Path Formats

Docker Desktop on Windows accepts paths in these formats:

Location Docker Compose Format
Local folder C:/ApertureLibraries:/aperture-libraries
Network share (IP) //192.168.1.50/Media/ApertureLibraries:/aperture-libraries
Network share (name) //NAS/Media/ApertureLibraries:/aperture-libraries

Note: Use forward slashes (/) in paths, not backslashes.


Step 5: Start Aperture

Open PowerShell, navigate to your Aperture folder, and start the containers:

cd C:\Aperture
docker-compose up -d

Watch the progress:

docker-compose logs -f

Press Ctrl+C to stop watching logs (containers keep running).

Verify Containers Are Running

docker ps

You should see aperture and aperture-db containers.


Step 6: Complete the Setup Wizard

Access Aperture

Open your browser and go to:

http://YOUR_WINDOWS_IP:3456

Or use http://localhost:3456 from the same machine.

Media Server Connection

Setting Value
Server Type Emby or Jellyfin
Server URL http://host.docker.internal:8096
API Key Your API key from Step 3

Important: Use host.docker.internal instead of localhost. This special hostname allows Docker containers to reach services running on the Windows host.

File Locations

Setting Value
Aperture Libraries Path The Windows path to your ApertureLibraries folder

Examples:

  • Local: C:\ApertureLibraries\
  • Network: M:\Media\ApertureLibraries\ (use drive letter, not UNC)

Output Format — CRITICAL!

Setting Value
Movies Use Symlinks OFF (use STRM)
Series Use Symlinks OFF (use STRM)

⚠️ STRM mode is required! Symlinks cannot work between a Linux container and Windows filesystem.


Step 7: Add Libraries to Emby

After Aperture generates recommendations:

  • Open Emby Dashboard
  • Go to Library → Add Media Library
  • Select Movies or TV Shows
  • Add the folder: C:\ApertureLibraries\[LibraryName]
  • Repeat for each Aperture library

How STRM Mode Works

The Problem

Aperture runs inside a Linux container, but your media files are on Windows. Linux symlinks can't point to Windows paths.

The Solution

STRM files are simple text files containing a path. When Emby sees a .strm file, it reads the path inside and plays that file.

Example STRM file content:

D:\Movies\Oppenheimer (2023)\Oppenheimer.mkv

Why This Works with Multiple NAS Devices

It doesn't matter if your movies are on drive O: and TV shows are on drive M:. Emby already has all those paths in its database. Aperture:

  • Queries Emby's API to get media info + file paths
  • Writes STRM files to ONE location (e.g., C:\ApertureLibraries\)
  • Each STRM file contains the original Windows path
  • Emby reads the STRM, follows the path, plays the file

Managing Aperture

View Logs

docker logs aperture
docker logs aperture-db

Stop Aperture

cd C:\Aperture
docker-compose down

Start Aperture

cd C:\Aperture
docker-compose up -d

Update to Latest Version

cd C:\Aperture
docker-compose pull
docker-compose up -d

Complete Reset (Delete All Data)

cd C:\Aperture
docker-compose down -v
docker-compose up -d

Warning: This deletes the database. Back up first if needed.


Troubleshooting

"Cannot connect to Emby"

"Permission denied" on network share

  • Open Docker Desktop → Settings → Resources → File Sharing
  • Add the network path
  • For authenticated shares, use IP address format: //192.168.1.50/Share
  • You may need to configure credentials in Windows Credential Manager

Container won't start

  • Ensure Docker Desktop is running (whale icon in system tray)
  • Check Docker Desktop dashboard for errors
  • Run: docker logs aperture for error details
  • Verify all paths exist and are accessible

STRM files not working

  • Open a STRM file with Notepad — verify it contains a valid Windows path
  • Test that path works: Copy the path, paste in File Explorer
  • Ensure Emby can access that path (same user account)
  • Re-scan the library in Emby

"host.docker.internal" not resolving

This should work automatically on Windows. If not:

  • Ensure Docker Desktop is using WSL 2 (Settings → General → Use WSL 2)
  • Restart Docker Desktop
  • As a workaround, use your Windows IP address instead

Example Configuration

Here's a complete example for a user with:

  • Windows IP: 192.168.1.100
  • Emby running on Windows at port 8096
  • Movies on NAS: M:\MediaNAS\Movies\
  • TV Shows on NAS: N:\MediaNAS2\TV\
  • Aperture output on NAS: M:\MediaNAS\ApertureLibraries\

docker-compose.yml

services:
  db:
    image: pgvector/pgvector:pg16
    container_name: aperture-db
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: aperture
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U app -d aperture']
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  app:
    image: ghcr.io/dgruhin-hrizn/aperture:latest
    container_name: aperture
    user: root
    environment:
      NODE_ENV: production
      PORT: 3456
      DATABASE_URL: postgres://app:app@db:5432/aperture
      RUN_MIGRATIONS_ON_START: 'true'
      TZ: Europe/Amsterdam
      APP_BASE_URL: http://192.168.1.100:3456
      SESSION_SECRET: xK9#mP2$vL5nQ8wR3tY6uI0oA7sD4fG1hJ
    ports:
      - '3456:3456'
    depends_on:
      db:
        condition: service_healthy
    volumes:
      # Using network share via UNC path
      - //192.168.1.50/MediaNAS/ApertureLibraries:/aperture-libraries
      - //192.168.1.50/MediaNAS/ApertureBackups:/backups
    restart: unless-stopped

volumes:
  pgdata:

Setup Wizard Settings

Setting Value
Media Server URL http://host.docker.internal:8096
Aperture Libraries Path M:\MediaNAS\ApertureLibraries\
Movies Use Symlinks OFF
Series Use Symlinks OFF

Next Steps

docker-compose.windows.yml

Edited by TheGru
Added Generic Windows Instructions and Windows Docker Compose Yaml
  • Thanks 1
TheGru
Posted

v0.5.2 Release Notes

🐛 Bug Fix: Playback Tracking Restored

Fixed an issue where played content wasn't being tracked correctly in Emby because of my clever concept of using fake provider IDs to decouple continue watching state

What was wrong: NFO files were using fake provider IDs (aperture1234 style) instead of real IMDB/TMDB/TVDB IDs, which broke playback state syncing.

What's fixed: NFO files now use your actual provider IDs again, so watch progress tracks properly.


📄 Windows Docker Desktop Support

Added docker-compose.windows.yml and full setup documentation for running Aperture in Docker Desktop alongside a native Windows Emby/Jellyfin installation.


Upgrade: Pull the latest image and rebuild your libraries to regenerate NFO files with correct IDs.

docker-compose pull
docker-compose up -d

Then run Admin → Jobs → Build Libraries for affected users.

Build is pushing now give it 5 minutes

GoldSpacer
Posted

Hey, I'm trying some other Ollama models but I can't seem to get the custom models to stick.

When I select Custom Model and enter the name, I can run the test successfully, but when I save it reverts the selection to whatever model was previously selected and if I try and run to generate embeddings or recommendations I get the following:

9:41:34 AM❌ Job failed: No embedding model configured or dimensions unknown

9:48:15 AM❌ Failed for user: No embedding model configured or dimensions unknown

  • Like 1
TheGru
Posted
45 minutes ago, GoldSpacer said:

Hey, I'm trying some other Ollama models but I can't seem to get the custom models to stick.

When I select Custom Model and enter the name, I can run the test successfully, but when I save it reverts the selection to whatever model was previously selected and if I try and run to generate embeddings or recommendations I get the following:

9:41:34 AM❌ Job failed: No embedding model configured or dimensions unknown

9:48:15 AM❌ Failed for user: No embedding model configured or dimensions unknown

I’ll look in to it

Jdiesel
Posted

Any chance that we'll get an unraid community template? I don't want to use docker compose on my unraid setup.

  • Agree 1
TheGru
Posted
42 minutes ago, Jdiesel said:

Any chance that we'll get an unraid community template? I don't want to use docker compose on my unraid setup.

I may get there. Docker Compose Manager in Unraid community apps make this really easy though. 

Posted

+1 with Jdiesel. For some reason, I didn't get it to work yesterday after trying several times and different ways while following the instructions provided. (Compose manager/template/portainer). Is it possible to implement the database variable to the project other than just the database url. 

Example:

Variable:
db_user, db_password, db_host, db_name etc. 

Thank you in advance. I really appreciate it. 

 

Jdiesel
Posted
20 minutes ago, TheGru said:

I may get there. Docker Compose Manager in Unraid community apps make this really easy though. 

I ended up using the Docker Compose Manager to get it up and running but might try to make up a template for Aperture and Postgres16. I don't know if the DockerMods version of Postgres will work so it will probably require a separate instance running the specific PG version.

 

Seems pretty good so far. I hope Emby devs are willing to work with your to get everything integrated more seamless without having to use workarounds. Great work!

  • Thanks 1
TheGru
Posted
8 minutes ago, Jdiesel said:

I ended up using the Docker Compose Manager to get it up and running but might try to make up a template for Aperture and Postgres16. I don't know if the DockerMods version of Postgres will work so it will probably require a separate instance running the specific PG version.

 

Seems pretty good so far. I hope Emby devs are willing to work with your to get everything integrated more seamless without having to use workarounds. Great work!

Aperture needs Postgres with pgvector in order to work with the embeddings. 
 

I don’t see why you couldn’t run it on an existing PGSQL but yeah I would need to provide users with a way to configure that connection vs the bundled current solution

Jdiesel
Posted
3 minutes ago, TheGru said:

Aperture needs Postgres with pgvector in order to work with the embeddings. 
 

I don’t see why you couldn’t run it on an existing PGSQL but yeah I would need to provide users with a way to configure that connection vs the bundled current solution

This is how Immich does it

https://docs.immich.app/install/unraid/#community-applications-template

It has a variables configured for 

DB_HOSTNAME=

DB_USERNAME=

DB_PASSWORD=

DB_DATABASE_NAME=

DB_PORT=

Jdiesel
Posted

I'm not sure if this is an issue with my symlinks but I have an issue.

I started playback of a series from my Ai Series Picks but now I have two instances in my Emby Continue watching. One from my regular Emby library and a second from my Aperture library.

TheGru
Posted
26 minutes ago, Jdiesel said:

I'm not sure if this is an issue with my symlinks but I have an issue.

I started playback of a series from my Ai Series Picks but now I have two instances in my Emby Continue watching. One from my regular Emby library and a second from my Aperture library.

This is a known unavoidable Emby issue. 
 

I hacked a workaround but it caused other issues. 
 

it is what it is until the Emby devs give us a way to exclude certain libraries from continue watching 

Jdiesel
Posted
Just now, TheGru said:

This is a known unavoidable Emby issue. 
 

I hacked a workaround but it caused other issues. 
 

it is what it is until the Emby devs give us a way to exclude certain libraries from continue watching 

I yes, I thought about disabling the libraries from continued watching but it also removes the homescreen row, which i'd like to keep.

@Luke Is this something that can be worked on in the short term?

TheGru
Posted

I’ll try and explain the Continue Watching duplicates issue as best as I understand it:

Continue Watching checks for data related to where you are in shows, but it also looks at TMDB and IMDB provider IDs for media and as such it finds all instances of media where those things are the same. 
 

This issue is not unique to Aperture. 

As an example, I maintain a movies library and a separate movies 4K library. If I playback The Matrix, both versions show up in continue watching. 
 

my workaround was to create NFO files with apertureUUID values. This worked but created the unfortunate side effect of only tracking watched information against the Aperture library files. This then becomes an issue as Aperture pulls in watch history, and it’s all whacked out because you didn’t watch the movie in a primary library. 
 

I tested like 4 permutations of this and the. Gave up.  

Jdiesel
Posted

Is it as simple as just having the option in Emby to exclude an entire library from "continued watching"? Or is there still a linkage with the "Display in secondary home screen sections such as latest media and continue watching" setting? Aperture is everything I wanted with the smart playlists functionality but even better, this little bug with Emby is a pretty significant showstopper though. I can't roll it out to users as it currently stands because I don't want to deal with the questions about duplicate entries.

 

I really hope Emby can provide a solution. 

 

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
×
×
  • Create New...