Aperture - AI-Powered Recommendations for Emby

[akacharos 34]

same applies for /studio btw

[akacharos 34]

On 1/26/2026 at 9:51 PM, camaban said:

 

AI edit of what I’d written above (it was ~5am, just waking up).

Also, just to be clear (because the AI flagged it and it definitely wasn’t my intention):

That wasn’t meant as snark. It was genuinely funny. I love how LLMs will find a way to justify whatever they’re told.

I’m working on a code review tool at work, and the prompting side has been… an experience.

For context: last night I spent a few hours going through and spamming “like” on the things I actually want included in the signal, plus marking the stuff I’d watched on Plex as watched in Emby. That improved things a lot. The only downside now is waiting for that huge burst of “watched” events to age out so it can be weighted appropriately.

Then this morning I spent another hour or two setting ratings on various titles (including 1-star ratings for things I only have because it’s a shared library with a friend of dubious taste). Big improvement again.

Anyway, the more coherent redo of the above:

Explicit likes/favourites weighting: If favourites are used as a strong positive signal, it may overweight sparse explicit feedback. Consider scaling the “favourite/like” signal by how much a user actually uses it (e.g., favourite-rate), and/or treating rewatches as a stronger implicit preference signal.

Respect profile restrictions: Filter candidates to only items the user profile can actually see (parental controls / rating limits), so picks aren’t wasted and explanations don’t reference inaccessible titles.

Reduce repeat surfacing: Add exposure tracking + cooldowns. If a title has been recommended multiple runs without being played, apply a penalty or hide it for N runs/days to keep the list moving (large libraries have plenty of variety).

Add a recency factor: Consider an optional “freshness” weight (newly released and/or newly added to library) to bias toward newer content when desired.

Cold-start onboarding: Optional “taste seeding” flow for new users (bulk rate titles) to establish preferences quickly.

Since you already ingest Emby heart ratings, a lightweight onboarding could just be a bulk ‘Rate/Review signals’ page that shows all rated + unrated titles with fast inline heart controls and filters (unrated, watched-but-unrated, frequently recommended-but-ignored). No new data model needed, just less clicking.

Add a per-profile Blacklist / Never recommend action that hard-excludes titles from future runs (with a manage/undo list). This is different from 1-star/dislike, which should remain a soft negative

 

Regarding the points raised about the Recency Factor, I would hesitate to enforce this strictly.

In Emby, "Recently Added" items are already in the spotlight, as most users sort by date added or have "Recently Added/Released" sections on their home screens. To me, the primary value of an AI recommendation engine is discovery—finding content I wouldn't normally see without scrolling endlessly through the library.

While a bias toward recent releases might suit general audiences, it doesn't apply to everyone. I think it makes more sense to profile a user's watch history based on preferred decades and adjust suggestions accordingly. For example, it doesn't make sense to apply a heavy weight to a new John Wick movie just because it’s "new," especially if that user has a long history of watching exclusively 60s Film Noir or 80s Horror B-movies.

Regarding Reducing Repeat Surfacing: This could be problematic depending on the user's viewing habits. Not everyone binges content. Many family members might only watch a couple of movies a week at most; some might not log in for weeks, while others watch daily.
If the scheduler runs every few days and applies a "cooldown" penalty to items just because they were suggested in a previous run, who wins? The casual viewer might miss out on a great recommendation simply because they didn't log in fast enough to see it before the system cycled it out.

[camaban 3]

This is true. There's endless tweak potential in the entire lot. Most hard set things are going to be bad at some level.

Utility of that really depends on size. I get more stuff coming in than I do spam, mostly added by people who aren't me (I'm just the storage enthusiast/hoarder) so this would help highlight the roughly 1:20 things I might care about.

Also helps keep the list fresh. Preferences aren't really going to change much, and if everything is equal, you're eventually getting to having the same recommendations week after week. Same weightings, roughly the same collection, same basic interests, same/similar results.

On a side note, I found when I moved away from OpenAI to a locally hosted model, I saw a large uptick in variety in everyone's recommendations. Prior to that it was fairly similar for everyone.

And because it's a less moral model, it was able to give me useful advice on how to argue for a Tarantino day at a kindergarten.

OpenAI just tried to make me feel like I was a bad person for even suggesting the idea. As if I wanted a priest rather than an enabler.

Edited January 29 by camaban

[DaMoekster 5]

Is it feasible to run aperture on a raspberry pi 5?
I tried installing but get the error:Error response from daemon: no matching manifest for linux/arm64/v8 in the manifest list entries: no match for platform in manifest: not found.
Not being an expert on docker I'm not sure if this means a complete no or something has to be changed/added to get it working.

[farfetchedchild 0]

Hey, 

First off, thank you for making this! It's been amazing! 

Now, I'm running Aperture in Docker on Windows (well, in Docker in WSL2 on Windows). I've got it working mostly ok, but when I try to analyze watch history I get an error. Also, when I try to auto detect paths I get "Unable to find media server files in Aperture's /media/ mount. Make sure your media folder is mounted at /media in Aperture's container." I have media libraries across multiple drives. Could this be the problem? They're all mounted, but I don't know of a way to enter them all as a path prefix (though I use STRM). 

Also, would it be possible to create virtual libraries (or playlists/collections) from user personalized Discovery recommendations for movies not in your libraries? From there Jellyseerr could be used either in the Emby client if on the web, or at the least by adding library items you don't to a watchlist monitored by Radarr or Sonarr. It'd be great to be able to request from Emby. 

[TheGru 158]

On 2/3/2026 at 3:51 AM, DaMoekster said:

Is it feasible to run aperture on a raspberry pi 5?
I tried installing but get the error:Error response from daemon: no matching manifest for linux/arm64/v8 in the manifest list entries: no match for platform in manifest: not found.
Not being an expert on docker I'm not sure if this means a complete no or something has to be changed/added to get it working.

I didn't build it against ARM and have been tied up with work. I will work on this at some point.

[DaMoekster 5]

10 hours ago, TheGru said:

I didn't build it against ARM and have been tied up with work. I will work on this at some point.

Thanks and good luck with work!

[SultanOfTux 5]

Hi,

I disabled the "Enable Watching Libraries" option in the admin panel (see screenshot), but it's still displayed for regular users—only hidden for the admin account.

How can I disable it globally for all users?

Thanks!

[olli1806 8]

Hello everyone,

I urgently need help with the installation on my Synology NAS.
Unfortunately, I am not very familiar with Docker, so I am unable to complete the installation on my own.

Could someone please explain step by step how to set this up correctly on a Synology system, or point out what I need to pay special attention to?

Thank you very much in advance for your support.

Best regards
Oliver

[SultanOfTux 5]

This is my YAML,
 

But if yout want to Bind the Library Folders you have to add the Path to the Library. You should check the YAML from the Github Repo https://github.com/dgruhin-hrizn/aperture.

First you add all the Folders you need in volume1, then add a new Project in Containermanager, and start the Docker.

version: "3.7"

services:

aperture-db:

image: pgvector/pgvector:pg16

container_name: aperture-db

environment:

POSTGRES_USER: app

POSTGRES_PASSWORD: app

POSTGRES_DB: aperture

volumes:

- /volume1/docker/aperture/db:/var/lib/postgresql/data

healthcheck:

test: ['CMD-SHELL', 'pg_isready -U app -d aperture']

interval: 5s

timeout: 5s

retries: 5

restart: unless-stopped

 

aperture:

image: ghcr.io/dgruhin-hrizn/aperture:latest

container_name: aperture

user: root

ports:

- 3456:3456

environment:

NODE_ENV: production

DATABASE_URL: postgres://app:app@aperture-db:5432/aperture

RUN_MIGRATIONS_ON_START: 'true'

APP_BASE_URL: https://aperture.yourdomain.ch or IP

SESSION_SECRET: 'X7kP9mW3qR8tY2uV5nL6jH4fD1sA0eZ9bC2xM7nK3pQ4wE6rT8yU1iO5aN9vB2cL'

OPENROUTER_API_KEY: "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"

DISABLE_STRM_GENERATION: 'true'

DISABLE_EMBY_COLLECTIONS: 'true'

depends_on:

- aperture-db

volumes:

- /volume1/docker/emby/config:/emby-config:ro

- /volume1/docker/aperture/backups:/backups

restart: unless-stopped

Edited February 17 by SultanOfTux

[gihayes 47]

Any chance this might ever work for Emby running in Docker on Windows 11?

[SultanOfTux 5]

I think so, theres an extra windows docker compose on GitHub

[DaMoekster 5]

1 hour ago, SultanOfTux said:

This is my YAML,
 

But if yout want to Bind the Library Folders you have to add the Path to the Library. You should check the YAML from the Github Repo https://github.com/dgruhin-hrizn/aperture.

First you add all the Folders you need in volume1, then add a new Project in Containermanager, and start the Docker.

version: "3.7"

services:

aperture-db:

image: pgvector/pgvector:pg16

container_name: aperture-db

environment:

POSTGRES_USER: app

POSTGRES_PASSWORD: app

POSTGRES_DB: aperture

volumes:

- /volume1/docker/aperture/db:/var/lib/postgresql/data

healthcheck:

test: ['CMD-SHELL', 'pg_isready -U app -d aperture']

interval: 5s

timeout: 5s

retries: 5

restart: unless-stopped

 

aperture:

image: ghcr.io/dgruhin-hrizn/aperture:latest

container_name: aperture

user: root

ports:

- 3456:3456

environment:

NODE_ENV: production

DATABASE_URL: postgres://app:app@aperture-db:5432/aperture

RUN_MIGRATIONS_ON_START: 'true'

APP_BASE_URL: https://aperture.yourdomain.ch or IP

SESSION_SECRET: 'X7kP9mW3qR8tY2uV5nL6jH4fD1sA0eZ9bC2xM7nK3pQ4wE6rT8yU1iO5aN9vB2cL'

OPENROUTER_API_KEY: "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"

DISABLE_STRM_GENERATION: 'true'

DISABLE_EMBY_COLLECTIONS: 'true'

depends_on:

- aperture-db

volumes:

- /volume1/docker/emby/config:/emby-config:ro

- /volume1/docker/aperture/backups:/backups

restart: unless-stopped

Your session secret and api key are visible. Did you change them first? Otherwise I would change these as soon as possible. 

[SultanOfTux 5]

Thank you but i have changed it before:)

[DaMoekster 5]

[TheGru 158]

Ok I am just about in a place where I can jump back in on Aperture, stay tuned!

[Jdiesel 1439]

I've had some time to play around with the new home screen sections a bit over the past few weeks and found that a mix of views using tags and playlists work best.

For things like Trakt and MdbList tags work best as they are universal and are the same across all users. Also list ordering is less critical as most people, I suspect, will want some variability in what they see on the list and not just the top 10 over and over. I've been using the AutoTag plugin for this.

For user specific recommendations and server specific popular/trending lists, playlists are the way to go. The ordering is more important in this case and there is no way to define the order when using tags other than the title, release date, added on, etc.

I don't know that there is a way to create home section via the API yet. You can copy setting manually between users though. This might be a barrier to making things completely seem less. I personally don't mind setting things up once as long as the tags and playlists continue to update.

 

[TheGru 158]

On 3/2/2026 at 12:44 PM, Jdiesel said:

I've had some time to play around with the new home screen sections a bit over the past few weeks and found that a mix of views using tags and playlists work best.

For things like Trakt and MdbList tags work best as they are universal and are the same across all users. Also list ordering is less critical as most people, I suspect, will want some variability in what they see on the list and not just the top 10 over and over. I've been using the AutoTag plugin for this.

For user specific recommendations and server specific popular/trending lists, playlists are the way to go. The ordering is more important in this case and there is no way to define the order when using tags other than the title, release date, added on, etc.

I don't know that there is a way to create home section via the API yet. You can copy setting manually between users though. This might be a barrier to making things completely seem less. I personally don't mind setting things up once as long as the tags and playlists continue to update.

 

I setup my homescreen and then quickly copied the setting to all other users, so far no complaints. One additional setting is apparently incoming on an upcoming beta, where individual dynamic rows can either hide or show played items. For me this completes things as you can build a pseudo DVR home row for shows or episodes now that are your shows you can about via aperture or just favorites, and hide watched, while still allowing watched to show for other rows where hiding things would potentially break Top Pick ordering and numbered display. I am looking forward to that. Then I will jump back in on aperture updates and upgrades based on user feedback

[graytinc 1]

How do I permanently fix that (Missing posters)

[fabien_m2002 8]

Hello

i have an Gemini AI sub but when i set my API ket and test, i have this error. What's wrong?

Connection failed: models/text-embedding-004 is not found for API version v1beta, or is not supported for embedContent. Call ListModels to see the list of available models and their supported methods

[sayschia 0]

Hi, thank you for developing this. It is working perfectly!
Is it possible to change  the AI explanation language to german?

[akacharos 34]

Well, in case you TheGru run out of ideas when you jump back into further development of  existing features in Aperture, here is just some feedback and ideas which are merely suggestions:

• I mentioned this earlier:

• Create Collections the same way we can create custom recommendation playlists with genres and example movies. Given the new revamped home logic in Emby, Collections are back in fashion! With that being a permission, admins can grant Collection creation to non-admins in Emby.If that's not technically possible, at least let admins create Collections.
• Add "Favorites" functionality in Aperture while browsing items that syncs to Emby (when you add an item to Favorites in Aperture, is also added to Favorites in Emby".
• Align Graph and List Similar Movies items: Currently Graph has more items than in the List (more of a bug maybe?). Also personal preference would be to have the List as the default instead of Graph or maybe make the default a configuration option. And maybe the List view can also benefit from the relation data (eg. Same Director, Shared Actor etc.).
• More filters in Browse (eg. country, watched/unwatched, household reach)
• Add Person (next to Movies and Series). Given /person endpoint exists already, it's a same not to easily browse/search for it.
   

[akacharos 34]

And a minor api endpoint modification request: pass user id on /api/assistant/chat
When calling /api/assistant/chat,  there is no way to specify which user the request is on behalf of. All calls made with a single service API key are attributed to the key owner, making it impossible to maintain per-user context (recommendations, history, preferences).
I believe is due to const user = request.user as SessionUser (API key owner) and const { messages } = request.body  (no userId accepted).

On a high level, it would be something like this on src/routes/assistant/handlers/chat.ts 
 

// NOW:
interface ChatBody {
  messages: UIMessage[]
  system?: string
}

// AFTER Add userId? to the body interface:
interface ChatBody {
  messages: UIMessage[]
  system?: string
  userId?: string  // optional override from external system
}

  
  
// NOW:
const user = request.user as SessionUser
const { messages } = request.body

// AFTER Resolve the effective user right after const user = ...:
const user = request.user as SessionUser
const { messages, userId: requestedUserId } = request.body
const effectiveUserId = requestedUserId ?? user.id
// ?? means: use requestedUserId if provided, otherwise fall back to user.id




// NOW:
const systemPrompt = await buildSystemPrompt(user.id, user.isAdmin)
const toolContext = {
    userId: user.id,
    ...
}

// AFTER  Replace the two occurrences of user.id downstream:
const systemPrompt = await buildSystemPrompt(effectiveUserId, user.isAdmin)
const toolContext = {
    userId: effectiveUserId,  // ← this is what scopes recommendations/history to the right user
    ...
}

 

[Iceburnmarko 0]

Read through all the comments , first what an excellent plug-in…. One thing I was thinking, could it be possible to add “JustWatch api” into it.  Thinking to capture what ppl watched / like / hate outside of emby.

[TheGru 158]

Aperture v0.7.0 Release Notes

Hey everyone I'm back!!!!

This one is almost entirely feedback from the comments while I have been busy working on the stuff that pays the bills.

This release is a big step for people and discovery: Browse → People, credits gap (GAP) on person pages, richer browse filters, and full Seerr integration improvements. Shows You Watch now syncs with Emby/Jellyfin series favorites instead of building STRM files or virtual libraries—see Breaking changes for what to change on your media server.

Baseline: follows v0.6.5 (commit f97f574). Commit range: f97f574..6893d05 (13 commits).

---

At a glance

Theme	What shipped
People & credits gap (GAP)	GAP = TMDb filmography titles not in your library, grouped by role and media type; person browse, discover APIs (getPersonCreditsGap), filters, TMDb detail modals, profile cache, actor personId linking
Browse	Country, watch status, watcher reach filters; preset save/load; countries list endpoints; view mode persistence
Seerr	User ↔ Seerr mapping, attributed requests, My Requests, rename Jellyseerr → Seerr, settings and migrations
Shows You Watch	Bidirectional favorites sync; scheduled sync-watching-favorites job; removal of STRM/virtual-library pipeline and sync-watching-libraries
Quality	SQL fix for movie resolution filter; carousel alignment fix

---

Summary for users

• Browse has a People tab: open people like titles, with grid/list view modes remembered per area.
• People GAP (credits gap): on each person page, Aperture compares TMDb combined credits to your library and shows what’s missing—grouped by movie vs TV and by role (e.g. director vs actor), with filters. Open a TMDb detail modal from gap rows (backdrop, metadata, request flow where applicable).
• Movies and series lists support country, watch status (via your history), and watcher reach (how many users on this instance have watched an item), plus saved filter presets.
• Seerr: requests can map to your Seerr user; My Requests and clearer Seerr naming (replacing “Jellyseerr” in the product).
• Shows You Watch stays a list in Aperture but syncs with series favorites on the server. Remove old watching virtual libraries in Emby and use a Home row (see below).

---

People & credits gap (GAP)

What GAP is

For a given person (actor, director, writer, etc.), GAP is the set of TMDb-credited movies and TV shows that do not map to an item in your Aperture-managed library—“on TMDb but not in your server’s library.” It answers: what am I missing from this person’s filmography?

How it works

• Core: getPersonCreditsGap loads combined TMDb credits (cached via person_tmdb_profile_cache), compares to catalog coverage, and returns role-grouped missing titles (f4cc40c).
• API: Discover routes expose the credits gap payload (with person browse, portrait push, TMDb movie/TV detail) using Zod schemas (1211fe6).
• Web: Person page: missing credits grouped by media type and role, filters, TMDb detail modals (cb83c66). MediaPosterCard compact meta for dense rows (d0904e3).

Technical summary

• Migration: person_tmdb_profile_cache for TMDb profile images and combined credits.
• Helpers: listPeopleForBrowse, getPersonCreditsGap (GAP engine), findPersonMediaServerItemId for portrait push; getTVCredits / getTVExternalIds exported.
• Media server sync: personId on Emby/Jellyfin actor sync for TMDb linking.
• Browse → People: TMDb-backed grid, fallbacks, browsePeople + useViewMode (044b636).
• UI: Carousel align-items: flex-start for mixed-height poster rows (2bc5ba2).

---

Browse filters (movies & series)

API (59e5b01 Query params country, watchStatus, minWatchers, maxWatchers on movie and series lists; GET /api/movies/countries and GET /api/series/countries. Watch status uses watch_history; watcher reach uses distinct user counts on the instance.

Web (961cd33 FilterPopper — production countries, watch status toggles, min/max watchers; wired to Browse fetch, chips, and preset save/load.

---

Seerr (formerly “Jellyseerr” in-product)

• User mapping to Seerr user ids (email / username / Jellyfin match, admin override).
• Settings: optional seerr_require_user_mapping; migrations for seerr_user_id and 0104_rename_jellyseerr_to_seerr.
• API: /api/seerr — POST /api/seerr/request with userId; GET /api/seerr/requests; admin PUT for seerrUserId on users.
• Web: My Requests, navigation and settings renamed for Seerr.
• Core: seerr module, userMapping, listAllSeerrUsers; docs/OpenAPI updated.

---

Breaking changes: Shows You Watch STRM / virtual libraries

Aperture no longer:

• Writes STRM files, symlinks, or NFOs for Shows You Watch.
• Creates or updates Emby/Jellyfin virtual libraries for per-user watching output.
• Exposes sync-watching-libraries, STRM vs symlink settings, or the library cover image admin block for that virtual library.

Database: strm_libraries rows with library_type = 'watching' and watching_library_use_symlinks are removed by migration (see Database migrations).

Emby / Jellyfin: recommended Home screen row

• Remove the old virtual folder / library that pointed at Aperture’s watching output, and clean up aperture-watching (or similar) on disk if present.
• Add a Home row with Dynamic Content:

  Libraries: all TV Series libraries you use.

  Sort: Date last content added (wording may vary by server version).

  Sort order: Descending.

  Playstate: Unplayed.

  Favorite: Enabled.

That surfaces favorited, unplayed series aligned with server favorites instead of a synthetic library.

What stays in Aperture

• user_watching_series and /api/watching CRUD.
• Favorites reconcile (reconcileWatchingFavoritesForUser).
• POST /api/watching/refresh — reconcile only (skipped, reason, pushedToServer, removedFromDb, pulledIntoDb, pushErrors).
• Job sync-watching-favorites; web Shows You Watch with Sync favorites.

---

Bug fixes

• Movies — resolution filter (b92cdf1 resolution counts use a subquery so GROUP BY stays valid when filtering by resolution.

---

Database migrations

Run your usual migration command so these apply in order:

Migration	Purpose
0101_person_tmdb_profile_cache.sql	TMDb person profile / credits cache
0102_users_jellyseerr_user_id.sql	Seerr user id on users
0103_jellyseerr_require_user_mapping.sql	Optional require-mapping flag
0104_rename_jellyseerr_to_seerr.sql	Rename identifiers and system_settings keys to Seerr
0105_remove_watching_strm_libraries.sql	Remove watching strm_libraries rows and watching_library_use_symlinks

(If some migrations already ran before you tag 0.7.0, confirm db/migrations state for your environment.)

---

Update instructions

For Docker users

docker compose pull
docker compose up -d

Database migrations run on startup (or use your usual pnpm db:migrate / deployment process).

Operator checklist

• Migrate the database before API/web versions that need new columns and caches.
• Emby: remove old watching virtual libraries and configure the Home row above if you used STRM watching.
• Seerr: confirm URL/API keys and user mapping; set admin seerrUserId overrides when auto-match fails.
• Jobs: schedule sync-watching-favorites; remove any references to sync-watching-libraries.

---

API quick reference

• Browse filters: country, watchStatus, minWatchers, maxWatchers; GET /api/movies/countries, GET /api/series/countries.
• Discover (people): browse; credits gap (GAP); portrait push; TMDb movie/TV detail (see OpenAPI under discover).
• Watching: POST /api/watching/refresh — favorites reconcile (no written / libraryCreated).
• Seerr: /api/seerr/* — request, requests list, user mapping admin.

---

Full changelog (commits since v0.6.5)

f4cc40c feat(core): TMDb person cache, people browse, credits gap, portrait helpers
b92cdf1 fix(api): movie resolutions filter after GROUP BY
1211fe6 feat(api): discover person routes and TMDb movie/TV detail
2bc5ba2 fix(ui): align carousel items to flex-start
d0904e3 feat(web): MediaPosterCard compact meta layout
044b636 feat(web): browse people tab and view mode persistence
cb83c66 feat(web): person page credits gap, filters, TMDb detail modal
59e5b01 feat(api): browse filters — country, watch status, watcher reach
961cd33 feat(web): browse filter UI for country, audience, and presets
10c58ed feat(seerr): attribute requests to users, My Requests, rename Jellyseerr to Seerr
764f9ec feat(watching): sync Shows you watch with Emby/Jellyfin favorites
db84e48 feat(jobs): add sync-watching-favorites as separate scheduled job
6893d05 Remove Shows You Watch STRM libraries; keep favorites sync