Aperture - AI-Powered Recommendations for Emby

[TheGru 164]

4 hours ago, TheGru said:

Good lord making this thing multi-language is a huge pain in the ass!

I am almost done, wrote some google translate scripts and i18n have made this a bit less painful... without Cursor and composer 2 fast for help I would not have ever done this.

[TheGru 164]

10 minutes ago, TheGru said:

I am almost done, wrote some google translate scripts and i18n have made this a bit less painful... without Cursor and composer 2 fast for help I would not have ever done this.

3090 hardcoded english strings

[TheGru 164]

Aperture v0.7.5 Release Notes

This release expands Discovery with JustWatch streaming charts, configurable TMDb genre strips (including exclude genres and flexible year ranges), a clearer Movies / TV browse layout, and multilingual UI improvements.

---

At a glance

Theme	What shipped
Discovery browse layout	On Movies and TV Series, sub-tabs separate TMDb popular overall (AI pool, filters, refresh) from Popular by genre (admin-configured TMDb Discover strips). Choice is remembered in the browser.
Streaming discovery	Discover → Streaming tab (when enabled): JustWatch-backed charts; admin can enable the feature and choose provider strips.
Genre strips (admin)	Per-strip genres (AND), exclude genres, from / to year (including Today for a rolling end at the current calendar year), heading, origin country, max titles, drag reorder.
Multilingual UI	Fourteen locales; RTL for Arabic and Hebrew. Deployment-wide language defaults under System settings.

---

Summary for users

Where to find things

What	Where
AI discovery pool + filters + Refresh	Discover → Movies or TV Series → sub-tab TMDb popular overall
Horizontal genre strips	Discover → Movies or TV Series → sub-tab Popular by genre
Streaming charts	Discover → Streaming (only if your admin has enabled streaming discovery for the server)
Your UI language	User settings (language / locale preferences in the app)

Grid/list view and Refresh apply to TMDb popular overall, not to the genre-strip sub-tab. Redundant info alerts about clicking titles were removed from Discovery tab content.

---

Summary for admins

Genre strips (TMDb Discover)

Path: Admin → Settings → Setup → Genre discovery (third sub-tab under Setup). TMDb must be configured; the tab is disabled until then.

Deep link (same page): /admin/settings?tab=setup&setupSub=genre-discovery

Configure Movies and TV sections separately. For each strip you can set:

• Genres — multiple genres are combined with AND (TMDb with_genres).
• Exclude genres — TMDb without_genres (e.g. Science Fiction but not Animation).
• From year / To year — optional bounds on release date (movies) or first air date (TV). To year can be No end, Today (current year) (rolling end-of-year bound at fetch time), or a specific year.
• Optional heading, origin country, and max titles per strip.
• Drag strips to reorder; use the save control on a strip (or your workflow) to persist.

Streaming discovery (JustWatch)

Path: Admin → Settings → Setup → Integrations — Streaming discovery block (enable flag, provider strip codes).

Deep link: /admin/settings?tab=setup&setupSub=integrations

The Discover → Streaming tab appears for users when streaming discovery is enabled for the deployment and their account has Discovery enabled.

Language defaults (deployment)

Path: Admin → Settings → System — Language defaults (default UI language and default AI language for new users / server-side defaults where applicable).

---

Discovery – TMDb popular overall vs Popular by genre

• TMDb popular overall — The personalized discovery pool: language/genre/year filters, Refresh, grid or list view, job progress when a discovery job runs.
• Popular by genre — Read-only horizontal strips driven by admin Genre discovery configuration. Strips load as you scroll (lazy loading).

---

Discovery – Streaming (JustWatch)

Charts are backed by JustWatch GraphQL data with server-side caching. TMDb poster paths may be resolved and cached to reduce API load. Exact provider codes depend on region; the admin UI references the bundled provider list.

---

Multilingual UI and RTL

Aperture’s web UI is multilingual. Users can work in a supported language (including via browser language detection and stored preference). We do not guarantee completeness or accuracy of translations; no promises are made as to language quality.

Supported UI locales (14): English (en), Spanish (es), German (de), French (fr), Italian (it), Portuguese (pt), Dutch (nl), Russian (ru), Japanese (ja), Chinese (zh), Korean (ko), Hindi (hi), Arabic (ar), Hebrew (he).

Right-to-left (RTL): The layout uses RTL for Arabic and Hebrew so navigation and mirroring behave correctly for those locales.

---

Update instructions

For Docker users

docker compose pull
docker compose up -d

Apply database migrations per your process (pnpm db:migrate or automatic on startup, depending on deployment).

Operator checklist

• Run migrations — 0110–0112 must apply before relying on streaming discovery or poster cache. Should happen automatically.
• TMDb — Required for genre strips and for sensible Discover behavior.
• Streaming discovery — Enable and configure provider strips under Setup → Integrations if you want the Streaming tab.
• Genre strips — Configure under Setup → Genre discovery; use Discover → Popular by genre to verify.

---

Thank you for running Aperture and feeding back on Discovery and translations in real environments.

Edited April 5 by TheGru

[dvalenci03 0]

Will this work on ARM Mac?

[filzituero 3]

During the initial setup wizard, the "Sync Movie Watch History" job fails with a 400 Bad Request error.

Error:
params/name must be equal to one of the allowed values
allowedValues: ["sync-movies","sync-series","enrich-movies","enrich-series","embed-movies","embed-series"]

Steps to reproduce:

• Fresh install, follow setup wizard
• Reach the "Initial Jobs" step
• sync-movies and sync-series complete successfully
• sync-movie-watch-history fails with the above error

Environment:

• Image: ghcr.io/dgruhin-hrizn/aperture:latest
• Media server: Emby (native install)
• Docker on Linux

[filzituero 3]

I managed to fix it:

Modify /setup/schemas.ts and replace line 362 with:

enum: ['sync-movies', 'sync-series', 'sync-movie-watch-history', 'sync-series-watch-history', 'enrich-movies', 'enrich-series', 'embed-movies', 'embed-series', 'generate-movie-embeddings', 'generate-series-embeddings', 'generate-movie-recommendations', 'generate-series-recommendations', 'sync-movie-libraries', 'sync-series-libraries', 'refresh-top-picks']

It’s now up and running.

I did run into one bug though:
if I enable recommendations for a user and then disable that user in Emby, they still keep getting recommendation updates.

Another thing (more of a feature request than an issue):
would it be possible to automatically delete the libraries created for a user when they are disabled in Emby, or when recommendations are turned off for them?

I also noticed that it creates two “Continue Watching” sections in Emby. I remember reading somewhere that it might be related to how Emby handles duplicate names or something like that, but I’m not sure if there’s a proper fix or workaround.

Anyway, thanks for this awesome tool!

[TheGru 164]

39 minutes ago, filzituero said:

I managed to fix it:

Modify /setup/schemas.ts and replace line 362 with:

enum: ['sync-movies', 'sync-series', 'sync-movie-watch-history', 'sync-series-watch-history', 'enrich-movies', 'enrich-series', 'embed-movies', 'embed-series', 'generate-movie-embeddings', 'generate-series-embeddings', 'generate-movie-recommendations', 'generate-series-recommendations', 'sync-movie-libraries', 'sync-series-libraries', 'refresh-top-picks']

It’s now up and running.

I did run into one bug though:
if I enable recommendations for a user and then disable that user in Emby, they still keep getting recommendation updates.

Another thing (more of a feature request than an issue):
would it be possible to automatically delete the libraries created for a user when they are disabled in Emby, or when recommendations are turned off for them?

I also noticed that it creates two “Continue Watching” sections in Emby. I remember reading somewhere that it might be related to how Emby handles duplicate names or something like that, but I’m not sure if there’s a proper fix or workaround.

Anyway, thanks for this awesome tool!

thanks for the feedback, I will get it fixed and redeployed

[TheGru 164]

48 minutes ago, filzituero said:

I also noticed that it creates two “Continue Watching” sections in Emby. I remember reading somewhere that it might be related to how Emby handles duplicate names or something like that, but I’m not sure if there’s a proper fix or workaround.

this is an emby thing, you can solve for it with the latest beta, and their new Dynamic Content home row, selecting just the libraries you want to include (ie do not include the aperture libraries and you wont have dupes in continue watching)

[TheGru 164]

Aperture v0.7.6 Release Notes

This release improves deployment (multi-arch Docker images for amd64 and arm64), user sync with Emby (respect disabled accounts), setup wizard job triggers, and STRM library lifecycle (automatic removal of virtual libraries and output folders when recommendations are turned off).

---

Summary for Users

• Apple Silicon Macs and 64-bit ARM servers (e.g. Raspberry Pi with a 64-bit OS) can run the same pre-built container image as x86_64; Docker pulls the matching architecture automatically.
• If your server admin disables your Emby account, Aperture stops treating you as eligible for recommendation jobs once sync-users runs (default every 30 minutes).
• Initial setup jobs such as Sync Movie Watch History no longer fail with a validation error when started from the wizard.

---

Summary for admins

Disabling recommendations and STRM output

When you turn off movies, series, or all recommendations for a user (Admin → Users), or when sync-users detects a user disabled on the media server, Aperture attempts to:

• DELETE the corresponding virtual library in Emby (by library name).
• Remove that user’s folders under /aperture-libraries/aperture and /aperture-libraries/aperture-tv (inside the Aperture container).
• Delete matching rows in strm_libraries.

Failures talking to the media server (e.g. library already removed) are logged; database and filesystem cleanup still proceed where possible. The scheduled sync-movie-libraries / sync-series-libraries jobs also run a reconciliation pass to clean up stale library records.

Docker image architectures

Published images are multi-architecture manifests. No separate tag is required per CPU; use your existing ghcr.io/.../aperture image reference.

Note: 32-bit ARM (arm/v7) is not a build target; use a 64-bit OS on Raspberry Pi for parity with dependencies (e.g. native modules).

---

API notes (operators)

• Setup jobs: POST /api/setup/jobs/:name/run — the documented allowed name values now match the server (includes watch-history, embedding, library, and related job ids).

---

Update instructions

For Docker users

docker compose pull
docker compose up -d

Apply database migrations per your process (pnpm db:migrate or automatic on startup, depending on deployment).

Operator checklist

Expect one-time sync — existing users get provider_disabled = false until sync-users runs and reads the current media-server flags.

---

Thank you for running Aperture and reporting setup and deployment edge cases in the wild.

[EmreWest 2]

Can I help you with the german translation of the UI? I just realized today that there were some updates to Aperture and I really like them so far. After changing the UI and AI language to German I also realized how bad Google or whatever you used for translation did the translation to German. I have no experience in coding etc. but pretty decent knowledge in IT in general and am fluent in German. Would be happy to help. 
 

also an additional question: is there a fix for the missing poster bug planned?

[TheGru 164]

16 hours ago, EmreWest said:

Can I help you with the german translation of the UI? I just realized today that there were some updates to Aperture and I really like them so far. After changing the UI and AI language to German I also realized how bad Google or whatever you used for translation did the translation to German. I have no experience in coding etc. but pretty decent knowledge in IT in general and am fluent in German. Would be happy to help. 
 

also an additional question: is there a fix for the missing poster bug planned?

I have taken a pass at updating the german, but feel free to update as you see fit. File is attached, it is thousands of lines of translation.

 

translation.json

Edited April 7 by TheGru

[fridgefins 7]

great work on this @TheGru, 

been kickin' the tires on aperture and noticed a couple things:

Library Configuration currently doesn't consider mixed libraries that have both movies and tv, so any movies or shows from those libraries dont get considered in the recommendations.

 

 

When aperture symlinks sidecar files it links them to a standardized name, but emby (or plugins like the bif generator) often create files that use the original filename, so emby doesnt recognize them as related to the differently named link to the media file. 

thank you for your work on this, really has the potential to add some serious functionality to the server!

 

Edited April 13 by fridgefins
formatting

[andreimike91 0]

Please add OAuth support/ Authentik.
I have an ecosystem of applications in my homelab using SSO, I don't want to ask users to re-login, as even for Emby is annoying.

[TheGru 164]

6 minutes ago, andreimike91 said:

Please add OAuth support/ Authentik.
I have an ecosystem of applications in my homelab using SSO, I don't want to ask users to re-login, as even for Emby is annoying.

this is probably not going to happen

[fabien_m2002 14]

Hello

there is a bug with last version on scheduling modalfor every job (BAD REQUEST when saving new frequency/time):

Edited May 4 by fabien_m2002

[fabien_m2002 14]

Another bug with genres strips, TMDB is well set and good test connection:

[fabien_m2002 14]

For the first bug: Looking at the network tab, the API responds with: FST_ERR_VALIDATION: body/scheduleIntervalMinutes must be equal to one of the allowed values. It seems the frontend is sending an invalid/null value for the interval parameter