From 34009f77c443dbbb63a4e30d7a9ae4f52a00948e Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Tue, 10 Mar 2026 18:22:48 +0100
Subject: [PATCH 01/30] feat: Cleanups, refactors

---
 .../command-providers/app-settings.tsx        |  2 +-
 .../command-providers/entities.tsx            |  2 +-
 .../command-providers/search-movie.tsx        |  2 +-
 .../command-providers/search-series.tsx       |  2 +-
 .../dashboard/device-availability.tsx         |  2 +-
 frontend/src/components/dashboard/index.tsx   |  2 +-
 .../src/components/dashboard/movie-widget.tsx |  2 +-
 frontend/src/components/header.tsx            |  2 +-
 frontend/src/components/user-avatar-menu.tsx  |  2 +-
 frontend/src/index.tsx                        |  4 +-
 frontend/src/pages/admin/app-settings.tsx     |  2 +-
 frontend/src/pages/admin/user-list.tsx        |  2 +-
 frontend/src/pages/ai/ai-chat-input.tsx       |  5 +-
 .../src/pages/ai/create-ai-chat-button.tsx    |  5 +-
 frontend/src/pages/chat/add-chat-button.tsx   |  6 +-
 .../src/pages/chat/chat-invitation-list.tsx   | 10 +--
 .../src/pages/chat/delete-chat-button.tsx     |  5 +-
 .../src/pages/chat/delete-chat-message.tsx    |  5 +-
 frontend/src/pages/chat/invite-button.tsx     |  6 +-
 frontend/src/pages/chat/message-input.tsx     |  5 +-
 frontend/src/pages/file-browser/file-list.tsx |  4 +-
 .../src/pages/file-browser/folder-panel.tsx   |  2 +-
 frontend/src/pages/files/image-viewer.tsx     |  2 +-
 .../src/pages/files/monaco-file-editor.tsx    |  2 +-
 frontend/src/pages/files/unknown-type.tsx     |  2 +-
 .../pages/logging/log-entries-terminal.tsx    |  2 +-
 frontend/src/pages/login.tsx                  |  3 +-
 frontend/src/pages/movies/movie-overview.tsx  |  2 +-
 .../movie-player-v2/get-subtitle-tracks.tsx   |  2 +-
 .../movie-player-v2/movie-player-service.ts   |  2 +-
 .../src/pages/movies/plain-hls-player.tsx     |  2 +-
 frontend/src/pages/offline.tsx                |  2 +-
 frontend/src/pages/register.tsx               |  2 +-
 frontend/src/routes/settings-routes.tsx       |  2 +-
 .../src/services/api-clients/ai-api-client.ts |  2 +-
 .../services/api-clients/chat-api-client.ts   |  2 +-
 .../services/api-clients/config-api-client.ts |  2 +-
 .../api-clients/dashboards-api-client.ts      |  2 +-
 .../services/api-clients/drives-api-client.ts |  2 +-
 .../api-clients/identity-api-client.ts        |  2 +-
 .../api-clients/install-api-client.ts         |  2 +-
 .../services/api-clients/iot-api-client.ts    |  2 +-
 .../api-clients/logging-api-client.ts         |  2 +-
 .../services/api-clients/media-api-client.ts  |  2 +-
 frontend/src/services/error-reporter.ts       |  2 +-
 frontend/src/services/session.spec.ts         | 62 ++++++++++++--
 frontend/src/services/session.ts              | 19 +++--
 frontend/src/services/websocket-events.ts     |  2 +-
 .../src/{ => utils}/environment-options.ts    |  0
 .../src/{ => utils}/navigate-to-route.spec.ts |  0
 frontend/src/{ => utils}/navigate-to-route.ts |  2 +-
 frontend/src/utils/session-helpers.spec.ts    | 81 +++++++++++++++++++
 frontend/src/utils/session-helpers.ts         | 31 +++++++
 .../src/{ => utils}/theme-switch-cheat.tsx    |  0
 .../src/{ => utils}/trigger-download.spec.ts  |  0
 frontend/src/{ => utils}/trigger-download.ts  |  0
 56 files changed, 241 insertions(+), 82 deletions(-)
 rename frontend/src/{ => utils}/environment-options.ts (100%)
 rename frontend/src/{ => utils}/navigate-to-route.spec.ts (100%)
 rename frontend/src/{ => utils}/navigate-to-route.ts (94%)
 create mode 100644 frontend/src/utils/session-helpers.spec.ts
 create mode 100644 frontend/src/utils/session-helpers.ts
 rename frontend/src/{ => utils}/theme-switch-cheat.tsx (100%)
 rename frontend/src/{ => utils}/trigger-download.spec.ts (100%)
 rename frontend/src/{ => utils}/trigger-download.ts (100%)

diff --git a/frontend/src/components/command-palette/command-providers/app-settings.tsx b/frontend/src/components/command-palette/command-providers/app-settings.tsx
index dfc453f7..dc6fe14a 100644
--- a/frontend/src/components/command-palette/command-providers/app-settings.tsx
+++ b/frontend/src/components/command-palette/command-providers/app-settings.tsx
@@ -2,7 +2,7 @@ import { getCurrentUser } from '@furystack/core'
 import { createComponent } from '@furystack/shades'
 import type { CommandProvider } from '@furystack/shades-common-components'
 import { Icon, icons } from '@furystack/shades-common-components'
-import { navigateToRoute } from '../../../navigate-to-route.js'
+import { navigateToRoute } from '../../../utils/navigate-to-route.js'
 import type { SuggestionOptions } from './create-suggestion.js'
 import { createSuggestion, distinctByName } from './create-suggestion.js'
 
diff --git a/frontend/src/components/command-palette/command-providers/entities.tsx b/frontend/src/components/command-palette/command-providers/entities.tsx
index d35d2675..1b2f31e1 100644
--- a/frontend/src/components/command-palette/command-providers/entities.tsx
+++ b/frontend/src/components/command-palette/command-providers/entities.tsx
@@ -2,7 +2,7 @@ import { getCurrentUser } from '@furystack/core'
 import { createComponent } from '@furystack/shades'
 import type { CommandProvider } from '@furystack/shades-common-components'
 import { Icon, icons } from '@furystack/shades-common-components'
-import { navigateToRoute } from '../../../navigate-to-route.js'
+import { navigateToRoute } from '../../../utils/navigate-to-route.js'
 import type { SuggestionOptions } from './create-suggestion.js'
 import { createSuggestion, distinctByName } from './create-suggestion.js'
 
diff --git a/frontend/src/components/command-palette/command-providers/search-movie.tsx b/frontend/src/components/command-palette/command-providers/search-movie.tsx
index ec47e50b..a84c5988 100644
--- a/frontend/src/components/command-palette/command-providers/search-movie.tsx
+++ b/frontend/src/components/command-palette/command-providers/search-movie.tsx
@@ -1,6 +1,6 @@
 import type { CommandProvider } from '@furystack/shades-common-components'
 import { createSuggestion } from './create-suggestion.js'
-import { navigateToRoute } from '../../../navigate-to-route.js'
+import { navigateToRoute } from '../../../utils/navigate-to-route.js'
 import { createComponent } from '@furystack/shades'
 import { MoviesService } from '../../../services/movies-service.js'
 
diff --git a/frontend/src/components/command-palette/command-providers/search-series.tsx b/frontend/src/components/command-palette/command-providers/search-series.tsx
index 7dfdf992..498f0bea 100644
--- a/frontend/src/components/command-palette/command-providers/search-series.tsx
+++ b/frontend/src/components/command-palette/command-providers/search-series.tsx
@@ -1,7 +1,7 @@
 import type { CommandProvider } from '@furystack/shades-common-components'
 import { SeriesService } from '../../../services/series-service.js'
 import { createSuggestion } from './create-suggestion.js'
-import { navigateToRoute } from '../../../navigate-to-route.js'
+import { navigateToRoute } from '../../../utils/navigate-to-route.js'
 import { createComponent } from '@furystack/shades'
 
 export const searchSeriesCommandProvider: CommandProvider = async ({ term, injector }) => {
diff --git a/frontend/src/components/dashboard/device-availability.tsx b/frontend/src/components/dashboard/device-availability.tsx
index c8787379..de17a18c 100644
--- a/frontend/src/components/dashboard/device-availability.tsx
+++ b/frontend/src/components/dashboard/device-availability.tsx
@@ -4,7 +4,7 @@ import { Shade, createComponent } from '@furystack/shades'
 import { CacheView, Skeleton } from '@furystack/shades-common-components'
 import type { Device, DeviceAvailability as DeviceAvailabilityProps, Icon as IconType } from 'common'
 import { AppLink } from '../../routes/index.js'
-import { navigateToRoute } from '../../navigate-to-route.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { IotDevicesService } from '../../services/iot-devices-service.js'
 import { SessionService } from '../../services/session.js'
 import { DynamicIcon } from '../dynamic-icon.js'
diff --git a/frontend/src/components/dashboard/index.tsx b/frontend/src/components/dashboard/index.tsx
index 78ef84c3..b5a15079 100644
--- a/frontend/src/components/dashboard/index.tsx
+++ b/frontend/src/components/dashboard/index.tsx
@@ -3,7 +3,7 @@ import { Shade, createComponent } from '@furystack/shades'
 import { ContextMenu, ContextMenuManager } from '@furystack/shades-common-components'
 import type { ContextMenuItem } from '@furystack/shades-common-components'
 import type { Dashboard as DashboardData } from 'common'
-import { navigateToRoute } from '../../navigate-to-route.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { SessionService } from '../../services/session.js'
 import { Widget } from './widget.js'
 
diff --git a/frontend/src/components/dashboard/movie-widget.tsx b/frontend/src/components/dashboard/movie-widget.tsx
index 96696fae..0bb0ccc6 100644
--- a/frontend/src/components/dashboard/movie-widget.tsx
+++ b/frontend/src/components/dashboard/movie-widget.tsx
@@ -5,7 +5,7 @@ import { LazyLoad, Shade, createComponent } from '@furystack/shades'
 import { CacheView, cssVariableTheme, Skeleton } from '@furystack/shades-common-components'
 import type { Movie } from 'common'
 import { AppLink } from '../../routes/index.js'
-import { navigateToRoute } from '../../navigate-to-route.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { MovieFilesService } from '../../services/movie-files-service.js'
 import { MoviesService } from '../../services/movies-service.js'
 import { SessionService } from '../../services/session.js'
diff --git a/frontend/src/components/header.tsx b/frontend/src/components/header.tsx
index 42aa04b7..3da0a7d6 100644
--- a/frontend/src/components/header.tsx
+++ b/frontend/src/components/header.tsx
@@ -1,7 +1,7 @@
 import { createComponent, Shade } from '@furystack/shades'
 import { AppBar, Button, Icon, icons } from '@furystack/shades-common-components'
 import { AppBarAppLink } from '../routes/index.js'
-import { environmentOptions } from '../environment-options.js'
+import { environmentOptions } from '../utils/environment-options.js'
 import { SessionService } from '../services/session.js'
 import { AiIcon } from './ai/ai-icon.js'
 import { ChatIcon } from './chat/chat-icon.js'
diff --git a/frontend/src/components/user-avatar-menu.tsx b/frontend/src/components/user-avatar-menu.tsx
index 5f6fc5dc..a6e2d52a 100644
--- a/frontend/src/components/user-avatar-menu.tsx
+++ b/frontend/src/components/user-avatar-menu.tsx
@@ -1,7 +1,7 @@
 import { createComponent, Shade } from '@furystack/shades'
 import type { MenuEntry } from '@furystack/shades-common-components'
 import { Avatar, cssVariableTheme, Dropdown, Icon, icons } from '@furystack/shades-common-components'
-import { navigateToRoute } from '../navigate-to-route.js'
+import { navigateToRoute } from '../utils/navigate-to-route.js'
 import { SessionService } from '../services/session.js'
 
 export const UserAvatarMenu = Shade({
diff --git a/frontend/src/index.tsx b/frontend/src/index.tsx
index b2f1b57a..293dc081 100644
--- a/frontend/src/index.tsx
+++ b/frontend/src/index.tsx
@@ -8,9 +8,9 @@ import { createComponent, initializeShadeRoot } from '@furystack/shades'
 import { ThemeProviderService } from '@furystack/shades-common-components'
 import { AiChatMessage, Chat, ChatMessage, LogEntry } from 'common'
 import { Layout } from './components/layout.js'
-import { environmentOptions } from './environment-options.js'
+import { environmentOptions } from './utils/environment-options.js'
 import { SessionService } from './services/session.js'
-import { registerThemeSwitchCheat } from './theme-switch-cheat.js'
+import { registerThemeSwitchCheat } from './utils/theme-switch-cheat.js'
 import { darkTheme } from './themes/dark.js'
 
 const shadeInjector = new Injector()
diff --git a/frontend/src/pages/admin/app-settings.tsx b/frontend/src/pages/admin/app-settings.tsx
index ac737754..99e28c1f 100644
--- a/frontend/src/pages/admin/app-settings.tsx
+++ b/frontend/src/pages/admin/app-settings.tsx
@@ -2,7 +2,7 @@ import { createComponent, LocationService, Shade } from '@furystack/shades'
 import { Drawer, Icon, icons, Menu, type MenuEntry } from '@furystack/shades-common-components'
 import { match } from 'path-to-regexp'
 import type { AppPaths } from '../../routes/index.js'
-import { navigateToRoute } from '../../navigate-to-route.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 
 type AppSettingsPageProps = {
   outlet?: JSX.Element
diff --git a/frontend/src/pages/admin/user-list.tsx b/frontend/src/pages/admin/user-list.tsx
index 5734a66a..7d34f806 100644
--- a/frontend/src/pages/admin/user-list.tsx
+++ b/frontend/src/pages/admin/user-list.tsx
@@ -13,7 +13,7 @@ import {
   Skeleton,
 } from '@furystack/shades-common-components'
 import type { User } from 'common'
-import { navigateToRoute } from '../../navigate-to-route.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { RoleTag } from '../../components/role-tag/index.js'
 import { GenericErrorPage } from '../../components/generic-error.js'
 import { UsersService } from '../../services/users-service.js'
diff --git a/frontend/src/pages/ai/ai-chat-input.tsx b/frontend/src/pages/ai/ai-chat-input.tsx
index a0ed90f0..14b505a7 100644
--- a/frontend/src/pages/ai/ai-chat-input.tsx
+++ b/frontend/src/pages/ai/ai-chat-input.tsx
@@ -1,6 +1,6 @@
 import { createComponent, Shade } from '@furystack/shades'
 import { Button, Form, Input } from '@furystack/shades-common-components'
-import { SessionService } from '../../services/session.js'
+import { getUser } from '../../utils/session-helpers.js'
 import { AiChatMessageService } from './ai-chat-message-service.js'
 import { AiChatService } from './ai-chat-service.js'
 
@@ -24,7 +24,6 @@ export const AiChatInput = Shade<{ selectedChatId: string }>({
   render: ({ props, injector, useObservable, useRef }) => {
     const aiChatMessageService = injector.getInstance(AiChatMessageService)
     const aiChatService = injector.getInstance(AiChatService)
-    const sessionService = injector.getInstance(SessionService)
     const formRef = useRef<HTMLFormElement>('form')
 
     const [selectedChat] = useObservable(
@@ -47,7 +46,7 @@ export const AiChatInput = Shade<{ selectedChatId: string }>({
               role: 'user',
               createdAt: new Date(),
               id: crypto.randomUUID(),
-              owner: sessionService.currentUser.getValue()!.username,
+              owner: getUser(injector).username,
               visibility: selectedChat?.value?.entries[0]?.visibility ?? 'private',
             })
             .then(() => {
diff --git a/frontend/src/pages/ai/create-ai-chat-button.tsx b/frontend/src/pages/ai/create-ai-chat-button.tsx
index cdf10d8e..3bb2fb9e 100644
--- a/frontend/src/pages/ai/create-ai-chat-button.tsx
+++ b/frontend/src/pages/ai/create-ai-chat-button.tsx
@@ -11,7 +11,7 @@ import {
 } from '@furystack/shades-common-components'
 import type { AiChat } from 'common'
 import { ErrorDisplay } from '../../components/error-display.js'
-import { SessionService } from '../../services/session.js'
+import { getUser } from '../../utils/session-helpers.js'
 import { AiChatService } from './ai-chat-service.js'
 import { AiModelSelector } from './ai-model-selector.js'
 
@@ -34,7 +34,6 @@ export const CreateAiChatButton = Shade({
   render: ({ injector, useState }) => {
     const aiChatService = injector.getInstance(AiChatService)
     const [isModalOpen, setIsModalOpen] = useState('isModalOpen', false)
-    const session = injector.getInstance(SessionService)
 
     const noty = injector.getInstance(NotyService)
 
@@ -74,7 +73,7 @@ export const CreateAiChatButton = Shade({
                     ...chat,
                     id: crypto.randomUUID(),
                     createdAt: new Date(),
-                    owner: session.currentUser.getValue()!.username,
+                    owner: getUser(injector).username,
                     status: 'active',
                     visibility: 'private',
                     description: chat.description,
diff --git a/frontend/src/pages/chat/add-chat-button.tsx b/frontend/src/pages/chat/add-chat-button.tsx
index c9aabee5..d570931f 100644
--- a/frontend/src/pages/chat/add-chat-button.tsx
+++ b/frontend/src/pages/chat/add-chat-button.tsx
@@ -1,6 +1,6 @@
 import { createComponent, Shade } from '@furystack/shades'
 import { Button, cssVariableTheme, Form, Input, Modal, Paper, Typography } from '@furystack/shades-common-components'
-import { SessionService } from '../../services/session.js'
+import { getUser } from '../../utils/session-helpers.js'
 import { ChatService } from './chat-service.js'
 
 export type AddChatPayload = {
@@ -23,8 +23,6 @@ export const AddChatButton = Shade({
   render: ({ useState, injector }) => {
     const [isModalOpen, setIsModalOpen] = useState('isModalOpen', false)
 
-    const session = injector.getInstance(SessionService)
-
     const chats = injector.getInstance(ChatService)
 
     return (
@@ -58,7 +56,7 @@ export const AddChatButton = Shade({
                     id: crypto.randomUUID(),
                     participants: [],
                     createdAt: new Date(),
-                    owner: session.currentUser.getValue()?.username || '',
+                    owner: getUser(injector).username,
                   })
                   .then(() => {
                     setIsModalOpen(false)
diff --git a/frontend/src/pages/chat/chat-invitation-list.tsx b/frontend/src/pages/chat/chat-invitation-list.tsx
index 4e9e4468..abb4beb0 100644
--- a/frontend/src/pages/chat/chat-invitation-list.tsx
+++ b/frontend/src/pages/chat/chat-invitation-list.tsx
@@ -2,7 +2,7 @@ import { createComponent, Shade } from '@furystack/shades'
 import { Button, NotyService, Paper, Skeleton, Typography } from '@furystack/shades-common-components'
 import { ErrorDisplay } from '../../components/error-display.js'
 import { GenericErrorPage } from '../../components/generic-error.js'
-import { SessionService } from '../../services/session.js'
+import { getUser } from '../../utils/session-helpers.js'
 import { ChatInvitationService } from './chat-intivation-service.js'
 
 export const ChatInvitationList = Shade({
@@ -16,7 +16,7 @@ export const ChatInvitationList = Shade({
     const filter = { filter: { status: { $eq: 'pending' } } } as const
 
     const chatInvitationService = injector.getInstance(ChatInvitationService)
-    const currentUser = injector.getInstance(SessionService).currentUser.getValue()
+    const currentUsername = getUser(injector).username
 
     const reloadChatInvitations = () => {
       void chatInvitationService.getChatInvitations(filter)
@@ -57,11 +57,11 @@ export const ChatInvitationList = Shade({
     const noty = injector.getInstance(NotyService)
 
     const received = invitations.value.entries.filter(
-      (invitation) => invitation.userId === currentUser?.username && invitation.status === 'pending',
+      (invitation) => invitation.userId === currentUsername && invitation.status === 'pending',
     )
 
     const sent = invitations.value.entries.filter(
-      (invitation) => invitation.createdBy === currentUser?.username && invitation.status === 'pending',
+      (invitation) => invitation.createdBy === currentUsername && invitation.status === 'pending',
     )
 
     return (
@@ -80,7 +80,7 @@ export const ChatInvitationList = Shade({
                     justifyContent: 'space-between',
                   }}
                 >
-                  {invitation.userId === currentUser?.username ? (
+                  {invitation.userId === currentUsername ? (
                     <div>
                       <Typography variant="body1">{invitation.chatName}</Typography>
                       <Button
diff --git a/frontend/src/pages/chat/delete-chat-button.tsx b/frontend/src/pages/chat/delete-chat-button.tsx
index 7d9f45c7..784b0a73 100644
--- a/frontend/src/pages/chat/delete-chat-button.tsx
+++ b/frontend/src/pages/chat/delete-chat-button.tsx
@@ -1,7 +1,7 @@
 import { createComponent, Shade } from '@furystack/shades'
 import { Button, NotyService } from '@furystack/shades-common-components'
 import type { Chat } from 'common'
-import { SessionService } from '../../services/session.js'
+import { getUser } from '../../utils/session-helpers.js'
 import { ChatService } from './chat-service.js'
 
 export const DeleteChatButton = Shade<{ chat: Chat }>({
@@ -9,7 +9,6 @@ export const DeleteChatButton = Shade<{ chat: Chat }>({
   render: ({ injector, props, useSearchState }) => {
     const chatService = injector.getInstance(ChatService)
 
-    const user = injector.getInstance(SessionService).currentUser.getValue()
     const noty = injector.getInstance(NotyService)
 
     const [selectedChatId, setSelectedChatId] = useSearchState('selectedChatId', '')
@@ -24,7 +23,7 @@ export const DeleteChatButton = Shade<{ chat: Chat }>({
     return (
       <Button
         color="error"
-        disabled={props.chat.owner !== user?.username}
+        disabled={props.chat.owner !== getUser(injector).username}
         onclick={async () => {
           if (!confirm('Are you sure you want to delete this chat? This action cannot be undone.')) {
             return
diff --git a/frontend/src/pages/chat/delete-chat-message.tsx b/frontend/src/pages/chat/delete-chat-message.tsx
index 9c057e5c..a51ef8a4 100644
--- a/frontend/src/pages/chat/delete-chat-message.tsx
+++ b/frontend/src/pages/chat/delete-chat-message.tsx
@@ -1,17 +1,16 @@
 import { createComponent, Shade } from '@furystack/shades'
 import { Button, NotyService } from '@furystack/shades-common-components'
 import type { ChatMessage } from 'common'
-import { SessionService } from '../../services/session.js'
+import { getUser } from '../../utils/session-helpers.js'
 import { ChatMessageService } from './chat-messages-service.js'
 
 export const DeleteChatMessage = Shade<{ chatMessage: ChatMessage }>({
   customElementName: 'shade-app-delete-chat-message',
   render: ({ injector, props }) => {
-    const currentUser = injector.getInstance(SessionService).currentUser.getValue()
     const { chatMessage } = props
     const noty = injector.getInstance(NotyService)
 
-    if (chatMessage.owner !== currentUser?.username) {
+    if (chatMessage.owner !== getUser(injector).username) {
       return null
     }
 
diff --git a/frontend/src/pages/chat/invite-button.tsx b/frontend/src/pages/chat/invite-button.tsx
index a1d81b90..adb43f4f 100644
--- a/frontend/src/pages/chat/invite-button.tsx
+++ b/frontend/src/pages/chat/invite-button.tsx
@@ -11,7 +11,7 @@ import {
 } from '@furystack/shades-common-components'
 import type { Chat } from 'common'
 import { ErrorDisplay } from '../../components/error-display.js'
-import { SessionService } from '../../services/session.js'
+import { getUser } from '../../utils/session-helpers.js'
 import { ChatInvitationService } from './chat-intivation-service.js'
 
 export type InvitePayload = {
@@ -35,8 +35,6 @@ export const InviteButton = Shade<{ chat: Chat }>({
   render: ({ useState, props, injector }) => {
     const [isModalOpen, setIsModalOpen] = useState('isModalOpen', false)
 
-    const currentUser = injector.getInstance(SessionService).currentUser.getValue()
-
     const invitationService = injector.getInstance(ChatInvitationService)
     const noty = injector.getInstance(NotyService)
 
@@ -75,7 +73,7 @@ export const InviteButton = Shade<{ chat: Chat }>({
                     status: 'pending',
                     chatName: props.chat.name,
                     createdAt: new Date(),
-                    createdBy: currentUser!.username,
+                    createdBy: getUser(injector).username,
                     id: crypto.randomUUID(),
                     message: formData.message.trim() || '',
                   })
diff --git a/frontend/src/pages/chat/message-input.tsx b/frontend/src/pages/chat/message-input.tsx
index 62e55413..0dbb95da 100644
--- a/frontend/src/pages/chat/message-input.tsx
+++ b/frontend/src/pages/chat/message-input.tsx
@@ -1,7 +1,7 @@
 import { createComponent, Shade } from '@furystack/shades'
 import { Button, Form, TextArea } from '@furystack/shades-common-components'
 import type { Chat } from 'common'
-import { SessionService } from '../../services/session.js'
+import { getUser } from '../../utils/session-helpers.js'
 import { ChatMessageService } from './chat-messages-service.js'
 
 export type ChatMessagePayload = {
@@ -18,7 +18,6 @@ export const MessageInput = Shade<{ chat: Chat }>({
   customElementName: 'shade-app-message-input',
   render: ({ injector, props, useRef }) => {
     const chatService = injector.getInstance(ChatMessageService)
-    const session = injector.getInstance(SessionService)
     const formRef = useRef<HTMLFormElement>('form')
 
     return (
@@ -30,7 +29,7 @@ export const MessageInput = Shade<{ chat: Chat }>({
             createdAt: new Date(),
             chatId: props.chat.id,
             content: formData.content,
-            owner: session.currentUser.getValue()?.username || '',
+            owner: getUser(injector).username,
             attachments: [],
           })
           formRef.current?.reset()
diff --git a/frontend/src/pages/file-browser/file-list.tsx b/frontend/src/pages/file-browser/file-list.tsx
index eca444d7..b4d3bd3b 100644
--- a/frontend/src/pages/file-browser/file-list.tsx
+++ b/frontend/src/pages/file-browser/file-list.tsx
@@ -4,11 +4,11 @@ import type { CollectionService } from '@furystack/shades-common-components'
 import { DataGrid, NotyService, SelectionCell } from '@furystack/shades-common-components'
 import { PathHelper } from '@furystack/utils'
 import { getFullPath, type DirectoryEntry } from 'common'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 import { DrivesService } from '../../services/drives-service.js'
 import { getErrorMessage } from '../../services/get-error-message.js'
 import { SessionService } from '../../services/session.js'
-import { triggerDownload } from '../../trigger-download.js'
+import { triggerDownload } from '../../utils/trigger-download.js'
 import { BreadCrumbs } from './breadcrumbs.js'
 import { DirectoryEntryIcon } from './directory-entry-icon.js'
 import { FileContextMenu } from './file-context-menu.js'
diff --git a/frontend/src/pages/file-browser/folder-panel.tsx b/frontend/src/pages/file-browser/folder-panel.tsx
index 41a5bcea..50c58bf6 100644
--- a/frontend/src/pages/file-browser/folder-panel.tsx
+++ b/frontend/src/pages/file-browser/folder-panel.tsx
@@ -4,7 +4,7 @@ import { CollectionService, Paper } from '@furystack/shades-common-components'
 import { PathHelper } from '@furystack/utils'
 import type { DirectoryEntry } from 'common'
 import { encode, getFullPath } from 'common'
-import { navigateToRoute } from '../../navigate-to-route.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { DrivesService } from '../../services/drives-service.js'
 import { DriveSelector } from './drive-selector.js'
 import { FileList } from './file-list.js'
diff --git a/frontend/src/pages/files/image-viewer.tsx b/frontend/src/pages/files/image-viewer.tsx
index 1987fb11..0f7ea340 100644
--- a/frontend/src/pages/files/image-viewer.tsx
+++ b/frontend/src/pages/files/image-viewer.tsx
@@ -1,6 +1,6 @@
 import { createComponent, Shade } from '@furystack/shades'
 import { Typography } from '@furystack/shades-common-components'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 export const ImageViewer = Shade<{ letter: string; path: string }>({
   customElementName: 'drives-files-image-viewer',
diff --git a/frontend/src/pages/files/monaco-file-editor.tsx b/frontend/src/pages/files/monaco-file-editor.tsx
index de684f0d..2eb70a77 100644
--- a/frontend/src/pages/files/monaco-file-editor.tsx
+++ b/frontend/src/pages/files/monaco-file-editor.tsx
@@ -3,7 +3,7 @@ import { Button, NotyService } from '@furystack/shades-common-components'
 import { ObservableValue } from '@furystack/utils'
 import { LazyMonacoEditor } from '../../components/lazy-monaco-editor.js'
 import { PiRatLazyLoad } from '../../components/pirat-lazy-load.js'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 import { DrivesApiClient } from '../../services/api-clients/drives-api-client.js'
 import { getErrorMessage } from '../../services/get-error-message.js'
 
diff --git a/frontend/src/pages/files/unknown-type.tsx b/frontend/src/pages/files/unknown-type.tsx
index c805c3b2..44df914a 100644
--- a/frontend/src/pages/files/unknown-type.tsx
+++ b/frontend/src/pages/files/unknown-type.tsx
@@ -1,6 +1,6 @@
 import { Shade, createComponent } from '@furystack/shades'
 import { Paper, Typography } from '@furystack/shades-common-components'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 export const UnknownType = Shade<{ letter: string; path: string }>({
   customElementName: 'drives-file-unknown-type-page',
diff --git a/frontend/src/pages/logging/log-entries-terminal.tsx b/frontend/src/pages/logging/log-entries-terminal.tsx
index 55a6282f..cbf0aa9a 100644
--- a/frontend/src/pages/logging/log-entries-terminal.tsx
+++ b/frontend/src/pages/logging/log-entries-terminal.tsx
@@ -8,7 +8,7 @@ import { Terminal } from '@xterm/xterm'
 import '@xterm/xterm/css/xterm.css'
 import { LogEntry } from 'common'
 import { compile, match, type MatchResult } from 'path-to-regexp'
-import { navigateToRoute } from '../../navigate-to-route.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 
 const useDisposableTerminal = (
   { useDisposable, injector }: Pick<RenderOptions<object>, 'useDisposable' | 'injector'>,
diff --git a/frontend/src/pages/login.tsx b/frontend/src/pages/login.tsx
index 90baf814..0470ef87 100644
--- a/frontend/src/pages/login.tsx
+++ b/frontend/src/pages/login.tsx
@@ -1,7 +1,7 @@
 import { Shade, createComponent } from '@furystack/shades'
 import { Button, Form, Input, cssVariableTheme, promisifyAnimation } from '@furystack/shades-common-components'
 import { PiRatLogo } from '../components/pi-rat-logo.js'
-import { navigateToRoute } from '../navigate-to-route.js'
+import { navigateToRoute } from '../utils/navigate-to-route.js'
 import { SessionService } from '../services/session.js'
 
 export type LoginPayload = {
@@ -144,7 +144,6 @@ export const Login = Shade({
           validate={isLoginPayload}
           className="login-form"
           onSubmit={({ userName, password }) => {
-            sessionService.loginError.setValue('')
             void sessionService.login(userName, password)
           }}
         >
diff --git a/frontend/src/pages/movies/movie-overview.tsx b/frontend/src/pages/movies/movie-overview.tsx
index f45f192f..4dcdabbc 100644
--- a/frontend/src/pages/movies/movie-overview.tsx
+++ b/frontend/src/pages/movies/movie-overview.tsx
@@ -5,7 +5,7 @@ import { createComponent, Shade } from '@furystack/shades'
 import { Button, CacheView, Skeleton, Typography } from '@furystack/shades-common-components'
 import type { Movie } from 'common'
 import { GenericErrorPage } from '../../components/generic-error.js'
-import { navigateToRoute } from '../../navigate-to-route.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { MovieFilesService } from '../../services/movie-files-service.js'
 import { MoviesService } from '../../services/movies-service.js'
 import { SessionService } from '../../services/session.js'
diff --git a/frontend/src/pages/movies/movie-player-v2/get-subtitle-tracks.tsx b/frontend/src/pages/movies/movie-player-v2/get-subtitle-tracks.tsx
index a1690069..ae6471c5 100644
--- a/frontend/src/pages/movies/movie-player-v2/get-subtitle-tracks.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/get-subtitle-tracks.tsx
@@ -2,7 +2,7 @@ import { createComponent } from '@furystack/shades'
 import type { FfprobeData, PiRatFile, SubtitleTrackInfo } from 'common'
 import { getFileName, getParentPath } from 'common'
 
-import { environmentOptions } from '../../../environment-options.js'
+import { environmentOptions } from '../../../utils/environment-options.js'
 
 /**
  * Builds subtitle track elements from playback-info response data when available,
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index 16a6566d..1fd14d3f 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -9,7 +9,7 @@ import type {
   SubtitleTrackInfo,
 } from 'common'
 import type Hls from 'hls.js'
-import { environmentOptions } from '../../../environment-options.js'
+import { environmentOptions } from '../../../utils/environment-options.js'
 import type { MediaApiClient } from '../../../services/api-clients/media-api-client.js'
 
 export const videoCodecs = {
diff --git a/frontend/src/pages/movies/plain-hls-player.tsx b/frontend/src/pages/movies/plain-hls-player.tsx
index efa73cfe..9e5372a5 100644
--- a/frontend/src/pages/movies/plain-hls-player.tsx
+++ b/frontend/src/pages/movies/plain-hls-player.tsx
@@ -1,6 +1,6 @@
 import { Shade, createComponent } from '@furystack/shades'
 import type Hls from 'hls.js'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 /**
  * Minimal HLS player for debugging — no media-chrome, no MoviePlayerService,
diff --git a/frontend/src/pages/offline.tsx b/frontend/src/pages/offline.tsx
index da284b33..8c495f88 100644
--- a/frontend/src/pages/offline.tsx
+++ b/frontend/src/pages/offline.tsx
@@ -1,6 +1,6 @@
 import { Shade, createComponent } from '@furystack/shades'
 import { Result } from '@furystack/shades-common-components'
-import { environmentOptions } from '../environment-options.js'
+import { environmentOptions } from '../utils/environment-options.js'
 
 export const Offline = Shade({
   customElementName: 'shade-offline',
diff --git a/frontend/src/pages/register.tsx b/frontend/src/pages/register.tsx
index b17bc844..a8d3b2f6 100644
--- a/frontend/src/pages/register.tsx
+++ b/frontend/src/pages/register.tsx
@@ -1,6 +1,6 @@
 import { Shade, createComponent } from '@furystack/shades'
 import { Button, Form, Input, Paper, Typography } from '@furystack/shades-common-components'
-import { navigateToRoute } from '../navigate-to-route.js'
+import { navigateToRoute } from '../utils/navigate-to-route.js'
 import { SessionService } from '../services/session.js'
 
 export type RegisterPayload = {
diff --git a/frontend/src/routes/settings-routes.tsx b/frontend/src/routes/settings-routes.tsx
index a4e5596a..ab508137 100644
--- a/frontend/src/routes/settings-routes.tsx
+++ b/frontend/src/routes/settings-routes.tsx
@@ -3,7 +3,7 @@ import { createComponent, type TitleResolverOptions } from '@furystack/shades'
 import { icons } from '@furystack/shades-common-components'
 import type { MatchResult } from 'path-to-regexp'
 import { PiRatLazyLoad } from '../components/pirat-lazy-load.js'
-import { navigateToRoute } from '../navigate-to-route.js'
+import { navigateToRoute } from '../utils/navigate-to-route.js'
 
 export const settingsChildren = {
   '/': {
diff --git a/frontend/src/services/api-clients/ai-api-client.ts b/frontend/src/services/api-clients/ai-api-client.ts
index f6aa5ea0..0568726b 100644
--- a/frontend/src/services/api-clients/ai-api-client.ts
+++ b/frontend/src/services/api-clients/ai-api-client.ts
@@ -1,7 +1,7 @@
 import { Injectable } from '@furystack/inject'
 import { createClient } from '@furystack/rest-client-fetch'
 import type { AiApi } from 'common'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class AiApiClient {
diff --git a/frontend/src/services/api-clients/chat-api-client.ts b/frontend/src/services/api-clients/chat-api-client.ts
index 7e756fbd..cad86fec 100644
--- a/frontend/src/services/api-clients/chat-api-client.ts
+++ b/frontend/src/services/api-clients/chat-api-client.ts
@@ -1,7 +1,7 @@
 import { Injectable } from '@furystack/inject'
 import { createClient } from '@furystack/rest-client-fetch'
 import type { ChatApi } from 'common'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class ChatApiClient {
diff --git a/frontend/src/services/api-clients/config-api-client.ts b/frontend/src/services/api-clients/config-api-client.ts
index 3309da8a..c3d8f6e1 100644
--- a/frontend/src/services/api-clients/config-api-client.ts
+++ b/frontend/src/services/api-clients/config-api-client.ts
@@ -1,7 +1,7 @@
 import { createClient } from '@furystack/rest-client-fetch'
 import type { ConfigApi } from 'common'
 import { Injectable } from '@furystack/inject'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class ConfigApiClient {
diff --git a/frontend/src/services/api-clients/dashboards-api-client.ts b/frontend/src/services/api-clients/dashboards-api-client.ts
index c8854b06..8a74e2f3 100644
--- a/frontend/src/services/api-clients/dashboards-api-client.ts
+++ b/frontend/src/services/api-clients/dashboards-api-client.ts
@@ -1,7 +1,7 @@
 import { createClient } from '@furystack/rest-client-fetch'
 import type { DashboardsApi } from 'common'
 import { Injectable } from '@furystack/inject'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class DashboardsApiClient {
diff --git a/frontend/src/services/api-clients/drives-api-client.ts b/frontend/src/services/api-clients/drives-api-client.ts
index 45059ca1..981cf2d3 100644
--- a/frontend/src/services/api-clients/drives-api-client.ts
+++ b/frontend/src/services/api-clients/drives-api-client.ts
@@ -1,7 +1,7 @@
 import { createClient } from '@furystack/rest-client-fetch'
 import type { DrivesApi } from 'common'
 import { Injectable } from '@furystack/inject'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class DrivesApiClient {
diff --git a/frontend/src/services/api-clients/identity-api-client.ts b/frontend/src/services/api-clients/identity-api-client.ts
index f7c378ba..5a6b03f3 100644
--- a/frontend/src/services/api-clients/identity-api-client.ts
+++ b/frontend/src/services/api-clients/identity-api-client.ts
@@ -1,7 +1,7 @@
 import { createClient } from '@furystack/rest-client-fetch'
 import type { IdentityApi } from 'common'
 import { Injectable } from '@furystack/inject'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class IdentityApiClient {
diff --git a/frontend/src/services/api-clients/install-api-client.ts b/frontend/src/services/api-clients/install-api-client.ts
index f541b412..72e0e748 100644
--- a/frontend/src/services/api-clients/install-api-client.ts
+++ b/frontend/src/services/api-clients/install-api-client.ts
@@ -1,7 +1,7 @@
 import { createClient } from '@furystack/rest-client-fetch'
 import type { InstallApi } from 'common'
 import { Injectable } from '@furystack/inject'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class InstallApiClient {
diff --git a/frontend/src/services/api-clients/iot-api-client.ts b/frontend/src/services/api-clients/iot-api-client.ts
index cfbb60e6..38bcf3ad 100644
--- a/frontend/src/services/api-clients/iot-api-client.ts
+++ b/frontend/src/services/api-clients/iot-api-client.ts
@@ -1,7 +1,7 @@
 import { createClient } from '@furystack/rest-client-fetch'
 import type { IotApi } from 'common'
 import { Injectable } from '@furystack/inject'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class IotApiClient {
diff --git a/frontend/src/services/api-clients/logging-api-client.ts b/frontend/src/services/api-clients/logging-api-client.ts
index 7397d9af..2a34308b 100644
--- a/frontend/src/services/api-clients/logging-api-client.ts
+++ b/frontend/src/services/api-clients/logging-api-client.ts
@@ -1,7 +1,7 @@
 import { Injectable } from '@furystack/inject'
 import { createClient } from '@furystack/rest-client-fetch'
 import type { LoggingApi } from 'common'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class LoggingApiClient {
diff --git a/frontend/src/services/api-clients/media-api-client.ts b/frontend/src/services/api-clients/media-api-client.ts
index d8d4b3c0..893b419b 100644
--- a/frontend/src/services/api-clients/media-api-client.ts
+++ b/frontend/src/services/api-clients/media-api-client.ts
@@ -1,7 +1,7 @@
 import { createClient } from '@furystack/rest-client-fetch'
 import type { MediaApi } from 'common'
 import { Injectable } from '@furystack/inject'
-import { environmentOptions } from '../../environment-options.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class MediaApiClient {
diff --git a/frontend/src/services/error-reporter.ts b/frontend/src/services/error-reporter.ts
index 7600f6bb..599e79b0 100644
--- a/frontend/src/services/error-reporter.ts
+++ b/frontend/src/services/error-reporter.ts
@@ -1,5 +1,5 @@
 import { Injectable } from '@furystack/inject'
-import { environmentOptions } from '../environment-options.js'
+import { environmentOptions } from '../utils/environment-options.js'
 @Injectable()
 export class ErrorReporter {
   public sendErrorReport(
diff --git a/frontend/src/services/session.spec.ts b/frontend/src/services/session.spec.ts
index ea97a603..f15f4c07 100644
--- a/frontend/src/services/session.spec.ts
+++ b/frontend/src/services/session.spec.ts
@@ -123,6 +123,23 @@ describe('SessionService', () => {
         expect(mockNotyService.emit).toHaveBeenCalledWith('onNotyAdded', expect.objectContaining({ type: 'warning' }))
       })
     })
+
+    it('should clear loginError before attempting login', async () => {
+      const mockCall = vi.fn().mockResolvedValue({
+        result: { username: 'testuser', roles: ['user'] },
+      })
+
+      const { injector } = createTestInjector(mockCall)
+
+      await usingAsync(injector, async (i) => {
+        const service = i.getInstance(SessionService)
+        service.loginError.setValue('previous error')
+
+        await service.login('testuser', 'password123')
+
+        expect(service.loginError.getValue()).toBe('')
+      })
+    })
   })
 
   describe('register', () => {
@@ -158,6 +175,23 @@ describe('SessionService', () => {
         expect(mockNotyService.emit).toHaveBeenCalledWith('onNotyAdded', expect.objectContaining({ type: 'warning' }))
       })
     })
+
+    it('should clear loginError before attempting registration', async () => {
+      const mockCall = vi.fn().mockResolvedValue({
+        result: { username: 'newuser', roles: [] },
+      })
+
+      const { injector } = createTestInjector(mockCall)
+
+      await usingAsync(injector, async (i) => {
+        const service = i.getInstance(SessionService)
+        service.loginError.setValue('previous error')
+
+        await service.register('newuser', 'password123')
+
+        expect(service.loginError.getValue()).toBe('')
+      })
+    })
   })
 
   describe('logout', () => {
@@ -169,19 +203,38 @@ describe('SessionService', () => {
       await usingAsync(injector, async (i) => {
         const service = i.getInstance(SessionService)
 
-        // Set up an authenticated state first
         service.currentUser.setValue({ username: 'testuser', roles: ['user'] })
 
         await service.logout()
 
-        // Verify API was called with logout action
         expect(mockCall).toHaveBeenCalledWith({ method: 'POST', action: '/logout' })
-        // Verify currentUser was cleared
         expect(service.currentUser.getValue()).toBeNull()
-        // Verify notification was shown
         expect(mockNotyService.emit).toHaveBeenCalledWith('onNotyAdded', expect.objectContaining({ type: 'info' }))
       })
     })
+
+    it('should still clear state when logout API call fails', async () => {
+      const mockCall = vi.fn().mockRejectedValue(new Error('Network error'))
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+      const { injector, mockNotyService } = createTestInjector(mockCall)
+
+      await usingAsync(injector, async (i) => {
+        const service = i.getInstance(SessionService)
+
+        service.currentUser.setValue({ username: 'testuser', roles: ['user'] })
+        service.state.setValue('authenticated')
+
+        await service.logout()
+
+        expect(service.currentUser.getValue()).toBeNull()
+        expect(service.state.getValue()).toBe('unauthenticated')
+        expect(mockNotyService.emit).toHaveBeenCalledWith('onNotyAdded', expect.objectContaining({ type: 'info' }))
+        expect(warnSpy).toHaveBeenCalledWith('Logout API call failed:', expect.any(Error))
+      })
+
+      warnSpy.mockRestore()
+    })
   })
 
   describe('isAuthenticated', () => {
@@ -403,7 +456,6 @@ describe('SessionService', () => {
 
         const initPromise = service.init()
 
-        // Check during operation
         capturedInProgress = service.isOperationInProgress.getValue()
 
         await initPromise
diff --git a/frontend/src/services/session.ts b/frontend/src/services/session.ts
index 98e488d0..818cf06b 100644
--- a/frontend/src/services/session.ts
+++ b/frontend/src/services/session.ts
@@ -3,7 +3,7 @@ import { Injectable, Injected, type Injector } from '@furystack/inject'
 import { NotyService } from '@furystack/shades-common-components'
 import { ObservableValue, usingAsync } from '@furystack/utils'
 import type { Roles } from 'common'
-import { navigateToRoute } from '../navigate-to-route.js'
+import { navigateToRoute } from '../utils/navigate-to-route.js'
 import { IdentityApiClient } from './api-clients/identity-api-client.js'
 
 export type SessionState = 'initializing' | 'offline' | 'unauthenticated' | 'authenticated'
@@ -25,7 +25,7 @@ export class SessionService implements IdentityContext, Disposable {
   private isDisposed = false
 
   public state = new ObservableValue<SessionState>('initializing')
-  public currentUser = new ObservableValue<Pick<User, 'username' | 'roles'> | null>(null)
+  public currentUser = new ObservableValue<User | null>(null)
 
   public isOperationInProgress = new ObservableValue(true)
 
@@ -56,6 +56,7 @@ export class SessionService implements IdentityContext, Disposable {
   }
 
   public async login(username: string, password: string): Promise<void> {
+    this.loginError.setValue('')
     await usingAsync(this.operation(), async () => {
       try {
         const { result: usr } = await this.api.call({ method: 'POST', action: '/login', body: { username, password } })
@@ -80,6 +81,7 @@ export class SessionService implements IdentityContext, Disposable {
   }
 
   public async register(username: string, password: string): Promise<void> {
+    this.loginError.setValue('')
     await usingAsync(this.operation(), async () => {
       try {
         const { result: usr } = await this.api.call({
@@ -110,7 +112,11 @@ export class SessionService implements IdentityContext, Disposable {
 
   public async logout(): Promise<void> {
     return await usingAsync(this.operation(), async () => {
-      void this.api.call({ method: 'POST', action: '/logout' })
+      try {
+        await this.api.call({ method: 'POST', action: '/logout' })
+      } catch (error) {
+        console.warn('Logout API call failed:', error)
+      }
       if (this.isDisposed) return
       this.currentUser.setValue(null)
       this.state.setValue('unauthenticated')
@@ -155,6 +161,8 @@ export class SessionService implements IdentityContext, Disposable {
     }
     return true
   }
+
+  // Generic signature required by IdentityContext interface
   public async getCurrentUser<TUser extends User>(): Promise<TUser> {
     const currentUser = this.currentUser.getValue()
     if (!currentUser) {
@@ -165,10 +173,7 @@ export class SessionService implements IdentityContext, Disposable {
       })
       throw Error('No user available')
     }
-    return {
-      username: currentUser.username,
-      roles: currentUser.roles,
-    } as TUser
+    return currentUser as TUser
   }
 
   @Injected(IdentityApiClient)
diff --git a/frontend/src/services/websocket-events.ts b/frontend/src/services/websocket-events.ts
index 24b2e772..832b54f0 100644
--- a/frontend/src/services/websocket-events.ts
+++ b/frontend/src/services/websocket-events.ts
@@ -2,7 +2,7 @@ import { Injectable, Injected } from '@furystack/inject'
 import { getLogger, type ScopedLogger } from '@furystack/logging'
 import { EventHub } from '@furystack/utils'
 import type { WebsocketMessage } from 'common'
-import { environmentOptions } from '../environment-options.js'
+import { environmentOptions } from '../utils/environment-options.js'
 
 @Injectable({ lifetime: 'singleton' })
 export class WebsocketNotificationsService extends EventHub<{
diff --git a/frontend/src/environment-options.ts b/frontend/src/utils/environment-options.ts
similarity index 100%
rename from frontend/src/environment-options.ts
rename to frontend/src/utils/environment-options.ts
diff --git a/frontend/src/navigate-to-route.spec.ts b/frontend/src/utils/navigate-to-route.spec.ts
similarity index 100%
rename from frontend/src/navigate-to-route.spec.ts
rename to frontend/src/utils/navigate-to-route.spec.ts
diff --git a/frontend/src/navigate-to-route.ts b/frontend/src/utils/navigate-to-route.ts
similarity index 94%
rename from frontend/src/navigate-to-route.ts
rename to frontend/src/utils/navigate-to-route.ts
index 9c12e1c4..aa5fe578 100644
--- a/frontend/src/navigate-to-route.ts
+++ b/frontend/src/utils/navigate-to-route.ts
@@ -1,7 +1,7 @@
 import type { Injector } from '@furystack/inject'
 import type { ExtractRouteParams } from '@furystack/shades'
 import { LocationService, compileRoute } from '@furystack/shades'
-import type { AppPaths } from './routes/index.js'
+import type { AppPaths } from '../routes/index.js'
 
 export type NavigateOptions = { queryString?: string; replace?: boolean }
 
diff --git a/frontend/src/utils/session-helpers.spec.ts b/frontend/src/utils/session-helpers.spec.ts
new file mode 100644
index 00000000..b41a484b
--- /dev/null
+++ b/frontend/src/utils/session-helpers.spec.ts
@@ -0,0 +1,81 @@
+import { describe, it, expect, vi } from 'vitest'
+import { Injector } from '@furystack/inject'
+import { NotyService } from '@furystack/shades-common-components'
+import { SessionService } from '../services/session.js'
+import { IdentityApiClient } from '../services/api-clients/identity-api-client.js'
+import { getUser, hasRole, SessionUserUnavailableError } from './session-helpers.js'
+
+vi.mock('./navigate-to-route.js', () => ({
+  navigateToRoute: vi.fn(),
+}))
+
+const createTestInjector = () => {
+  const injector = new Injector()
+  injector.setExplicitInstance({ call: vi.fn() } as unknown as IdentityApiClient, IdentityApiClient)
+  injector.setExplicitInstance({ emit: vi.fn() } as unknown as NotyService, NotyService)
+  return injector
+}
+
+describe('SessionUserUnavailableError', () => {
+  it('should have the correct name and message', () => {
+    const error = new SessionUserUnavailableError()
+    expect(error).toBeInstanceOf(Error)
+    expect(error.name).toBe('SessionUserUnavailableError')
+    expect(error.message).toBe('No authenticated user available')
+  })
+})
+
+describe('getUser', () => {
+  it('should return the current user when authenticated', () => {
+    const injector = createTestInjector()
+    const service = injector.getInstance(SessionService)
+    service.currentUser.setValue({ username: 'testuser', roles: ['admin'] })
+
+    const user = getUser(injector)
+
+    expect(user).toEqual({ username: 'testuser', roles: ['admin'] })
+
+    service[Symbol.dispose]()
+  })
+
+  it('should throw SessionUserUnavailableError when no user is set', () => {
+    const injector = createTestInjector()
+    const service = injector.getInstance(SessionService)
+
+    expect(() => getUser(injector)).toThrow(SessionUserUnavailableError)
+
+    service[Symbol.dispose]()
+  })
+})
+
+describe('hasRole', () => {
+  it('should return true when user has the role', () => {
+    const injector = createTestInjector()
+    const service = injector.getInstance(SessionService)
+    service.currentUser.setValue({ username: 'admin', roles: ['admin', 'user'] })
+
+    expect(hasRole(injector, 'admin')).toBe(true)
+    expect(hasRole(injector, 'user')).toBe(true)
+
+    service[Symbol.dispose]()
+  })
+
+  it('should return false when user does not have the role', () => {
+    const injector = createTestInjector()
+    const service = injector.getInstance(SessionService)
+    service.currentUser.setValue({ username: 'user', roles: ['user'] })
+
+    expect(hasRole(injector, 'admin')).toBe(false)
+
+    service[Symbol.dispose]()
+  })
+
+  it('should throw SessionUserUnavailableError when no user is set', () => {
+    const injector = createTestInjector()
+    const service = injector.getInstance(SessionService)
+
+    expect(() => hasRole(injector, 'admin')).toThrow(SessionUserUnavailableError)
+
+    service[Symbol.dispose]()
+  })
+})
diff --git a/frontend/src/utils/session-helpers.ts b/frontend/src/utils/session-helpers.ts
new file mode 100644
index 00000000..63e9866e
--- /dev/null
+++ b/frontend/src/utils/session-helpers.ts
@@ -0,0 +1,31 @@
+import type { User } from '@furystack/core'
+import type { Injector } from '@furystack/inject'
+import { SessionService } from '../services/session.js'
+
+export class SessionUserUnavailableError extends Error {
+  constructor() {
+    super('No authenticated user available')
+    this.name = 'SessionUserUnavailableError'
+  }
+}
+
+/**
+ * Returns the current user synchronously from the session.
+ * Intended for use in components rendered within authenticated routes.
+ * @throws {SessionUserUnavailableError} if no user is available
+ */
+export const getUser = (injector: Injector): User => {
+  const user = injector.getInstance(SessionService).currentUser.getValue()
+  if (!user) {
+    throw new SessionUserUnavailableError()
+  }
+  return user
+}
+
+/**
+ * Checks if the current user has the specified role.
+ * @throws {SessionUserUnavailableError} if no user is available
+ */
+export const hasRole = (injector: Injector, role: string): boolean => {
+  return getUser(injector).roles.includes(role)
+}
diff --git a/frontend/src/theme-switch-cheat.tsx b/frontend/src/utils/theme-switch-cheat.tsx
similarity index 100%
rename from frontend/src/theme-switch-cheat.tsx
rename to frontend/src/utils/theme-switch-cheat.tsx
diff --git a/frontend/src/trigger-download.spec.ts b/frontend/src/utils/trigger-download.spec.ts
similarity index 100%
rename from frontend/src/trigger-download.spec.ts
rename to frontend/src/utils/trigger-download.spec.ts
diff --git a/frontend/src/trigger-download.ts b/frontend/src/utils/trigger-download.ts
similarity index 100%
rename from frontend/src/trigger-download.ts
rename to frontend/src/utils/trigger-download.ts

From a8c48b482d727bfe42fbeb110aec055f7bdd96fd Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Tue, 10 Mar 2026 19:27:16 +0100
Subject: [PATCH 02/30] entity sync scope fix

---
 service/src/ai/setup-ai-store.ts               |  5 +++++
 .../src/app-models/chat/setup-chat-store.ts    |  8 ++++++++
 .../install/actions/get-service-status.ts      |  8 ++++----
 .../logging/setup-logging-storage.ts           |  5 +++++
 service/src/app-models/media/setup-media.ts    |  5 ++++-
 .../src/external-service-status-registry.ts    | 18 ++++++++++++++++++
 service/src/ffprobe-service.ts                 |  4 ----
 service/src/service.ts                         | 12 +-----------
 8 files changed, 45 insertions(+), 20 deletions(-)
 create mode 100644 service/src/external-service-status-registry.ts

diff --git a/service/src/ai/setup-ai-store.ts b/service/src/ai/setup-ai-store.ts
index 1c53b3ec..2654d2ac 100644
--- a/service/src/ai/setup-ai-store.ts
+++ b/service/src/ai/setup-ai-store.ts
@@ -1,4 +1,5 @@
 import { getCurrentUser, getStoreManager } from '@furystack/core'
+import { useEntitySync } from '@furystack/entity-sync-service'
 import type { Injector } from '@furystack/inject'
 import { getLogger } from '@furystack/logging'
 import { Repository } from '@furystack/repository'
@@ -190,6 +191,10 @@ export const setupAiStore = async (injector: Injector) => {
     },
   })
 
+  useEntitySync(injector, {
+    models: [{ model: AiChatMessage, primaryKey: 'id' }],
+  })
+
   repository.createDataSet(AiChatMessage, 'id', {
     modifyOnAdd: async ({ injector: i, entity }) => {
       const currentUser = await getCurrentUser(i)
diff --git a/service/src/app-models/chat/setup-chat-store.ts b/service/src/app-models/chat/setup-chat-store.ts
index b8006b9c..391961da 100644
--- a/service/src/app-models/chat/setup-chat-store.ts
+++ b/service/src/app-models/chat/setup-chat-store.ts
@@ -1,4 +1,5 @@
 import { getCurrentUser, getStoreManager } from '@furystack/core'
+import { useEntitySync } from '@furystack/entity-sync-service'
 import type { Injector } from '@furystack/inject'
 import { getLogger } from '@furystack/logging'
 import { getRepository } from '@furystack/repository'
@@ -316,6 +317,13 @@ export const setupChatStore = async (injector: Injector) => {
     },
   })
 
+  useEntitySync(injector, {
+    models: [
+      { model: Chat, primaryKey: 'id' },
+      { model: ChatMessage, primaryKey: 'id', debounceMs: 100 },
+    ],
+  })
+
   repo.createDataSet(ChatInvitation, 'id', {
     addFilter: async ({ injector: i, filter }) => {
       const user = await getCurrentUser(i)
diff --git a/service/src/app-models/install/actions/get-service-status.ts b/service/src/app-models/install/actions/get-service-status.ts
index da1b6991..7f7fb159 100644
--- a/service/src/app-models/install/actions/get-service-status.ts
+++ b/service/src/app-models/install/actions/get-service-status.ts
@@ -1,19 +1,19 @@
 import type { RequestAction } from '@furystack/rest-service'
 import { JsonResult } from '@furystack/rest-service'
 import type { GetServiceStatusAction } from 'common'
-import { OmdbClientService } from '../../media/metadata-services/omdb-client-service.js'
+import { ExternalServiceStatusRegistry } from '../../../external-service-status-registry.js'
 import { ServiceStatusProvider } from '../service-installer.js'
 
 export const GetServiceStatus: RequestAction<GetServiceStatusAction> = async ({ injector }) => {
   const state = await injector.getInstance(ServiceStatusProvider).getStatus()
 
-  const omdb = !!injector.getInstance(OmdbClientService).config
+  const services = injector.getInstance(ExternalServiceStatusRegistry).getStatuses()
 
   return JsonResult({
     state,
     services: {
-      omdb,
-      github: false,
+      omdb: services.omdb ?? false,
+      github: services.github ?? false,
     },
   })
 }
diff --git a/service/src/app-models/logging/setup-logging-storage.ts b/service/src/app-models/logging/setup-logging-storage.ts
index 6055a5c8..18c3ddff 100644
--- a/service/src/app-models/logging/setup-logging-storage.ts
+++ b/service/src/app-models/logging/setup-logging-storage.ts
@@ -1,3 +1,4 @@
+import { useEntitySync } from '@furystack/entity-sync-service'
 import type { Injector } from '@furystack/inject'
 import { getLogger, type LogLevel } from '@furystack/logging'
 import { getRepository } from '@furystack/repository'
@@ -82,4 +83,8 @@ export const setupLoggingStorage = async (injector: Injector) => {
     authorizeRemove: alwaysDeny,
     authorizeAdd: withRole('admin'),
   })
+
+  useEntitySync(injector, {
+    models: [{ model: LogEntry, primaryKey: 'id', debounceMs: 200 }],
+  })
 }
diff --git a/service/src/app-models/media/setup-media.ts b/service/src/app-models/media/setup-media.ts
index 2678bea2..7948be99 100644
--- a/service/src/app-models/media/setup-media.ts
+++ b/service/src/app-models/media/setup-media.ts
@@ -11,6 +11,7 @@ import { useSequelize } from '@furystack/sequelize-store'
 import { DataTypes, Model } from 'sequelize'
 
 import { authorizedOnly } from '../../authorization/authorized-only.js'
+import { ExternalServiceStatusRegistry } from '../../external-service-status-registry.js'
 import { withRole } from '../../authorization/with-role.js'
 import type { FfprobeResult } from '../../ffprobe-service.js'
 import { getDefaultDbSettings } from '../../get-default-db-options.js'
@@ -694,7 +695,9 @@ export const setupMedia = async (injector: Injector) => {
     authorizeRemove: withRole('admin'),
   })
 
-  injector.getInstance(OmdbClientService)
+  const omdbClientService = injector.getInstance(OmdbClientService)
+
+  injector.getInstance(ExternalServiceStatusRegistry).register('omdb', () => !!omdbClientService.config)
 
   const movieFileDataSet = getDataSetFor(injector, MovieFile, 'id')
   const movieDataSet = getDataSetFor(injector, Movie, 'imdbId')
diff --git a/service/src/external-service-status-registry.ts b/service/src/external-service-status-registry.ts
new file mode 100644
index 00000000..566f40c1
--- /dev/null
+++ b/service/src/external-service-status-registry.ts
@@ -0,0 +1,18 @@
+import { Injectable } from '@furystack/inject'
+
+@Injectable({ lifetime: 'singleton' })
+export class ExternalServiceStatusRegistry {
+  private providers = new Map<string, () => boolean>()
+
+  public register(name: string, statusGetter: () => boolean) {
+    this.providers.set(name, statusGetter)
+  }
+
+  public getStatuses(): Record<string, boolean> {
+    const result: Record<string, boolean> = {}
+    for (const [name, getter] of this.providers) {
+      result[name] = getter()
+    }
+    return result
+  }
+}
diff --git a/service/src/ffprobe-service.ts b/service/src/ffprobe-service.ts
index 958e3129..fe956fed 100644
--- a/service/src/ffprobe-service.ts
+++ b/service/src/ffprobe-service.ts
@@ -6,7 +6,6 @@ import { getLogger } from '@furystack/logging'
 import { getDataSetFor, type DataSet } from '@furystack/repository'
 import { Semaphore } from '@furystack/utils'
 import { Drive, PiRatFile, type FfprobeData } from 'common'
-import { FileWatcherService } from './app-models/drives/file-watcher-service.js'
 import { execFileAsync } from './utils/exec-file-async.js'
 import { existsAsync } from './utils/exists-async.js'
 import { getPhysicalPath } from './utils/physical-path-utils.js'
@@ -74,9 +73,6 @@ export class FfprobeService implements Disposable {
     },
   })
 
-  @Injected(FileWatcherService)
-  declare private fileWatcherService: FileWatcherService
-
   constructor() {
     this.piRatFileCache.addListener('onLoadError', ({ args, error }) => {
       void this.logger.error({
diff --git a/service/src/service.ts b/service/src/service.ts
index ab321a45..a2cdca9b 100644
--- a/service/src/service.ts
+++ b/service/src/service.ts
@@ -2,10 +2,9 @@ import type { Injector } from '@furystack/inject'
 import { Injectable, Injected } from '@furystack/inject'
 import type { ScopedLogger } from '@furystack/logging'
 import { getLogger } from '@furystack/logging'
-import { SyncSubscribeAction, SyncUnsubscribeAction, useEntitySync } from '@furystack/entity-sync-service'
+import { SyncSubscribeAction, SyncUnsubscribeAction } from '@furystack/entity-sync-service'
 import { useWebsockets } from '@furystack/websocket-api'
 import { EventHub } from '@furystack/utils'
-import { AiChatMessage, Chat, ChatMessage, LogEntry } from 'common'
 import { AiAppModel } from './ai/ai-app-model.js'
 import { ChatAppModel } from './app-models/chat/chat-app-model.js'
 import { ConfigAppModel } from './app-models/config/config-app-model.js'
@@ -45,15 +44,6 @@ export class PiRatRootService extends EventHub<{ initialized: undefined }> {
       injector.getInstance(AiAppModel),
     )
 
-    useEntitySync(injector, {
-      models: [
-        { model: Chat, primaryKey: 'id' },
-        { model: ChatMessage, primaryKey: 'id', debounceMs: 100 },
-        { model: LogEntry, primaryKey: 'id', debounceMs: 200 },
-        { model: AiChatMessage, primaryKey: 'id' },
-      ],
-    })
-
     const syncInjector = injector.createChild({ owner: 'entity-sync' })
     await useWebsockets(syncInjector, {
       port: getPort(),

From fd5cce9c02e07666bdb9bb05b2b2956f0c793f0e Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 09:57:14 +0100
Subject: [PATCH 03/30] TMDB integration

---
 common/schemas/ai-api.json                    |   85 +-
 common/schemas/chat-api.json                  |   85 +-
 common/schemas/config-api.json                |  448 +-
 common/schemas/config-entities.json           |  110 +
 common/schemas/dashboards-api.json            |   85 +-
 common/schemas/drives-api.json                |   68 +-
 common/schemas/identity-api.json              |   85 +-
 common/schemas/install-api.json               |  125 +-
 common/schemas/iot-api.json                   |   85 +-
 common/schemas/logging-api.json               |  136 +-
 common/schemas/media-api.json                 | 6631 ++++++++++++++---
 common/schemas/media-entities.json            |  316 +-
 common/src/apis/install.ts                    |    4 +
 common/src/apis/media.ts                      |   36 +-
 common/src/models/config/config.ts            |   11 +-
 common/src/models/config/index.ts             |    2 +
 .../models/config/metadata-provider-config.ts |   10 +
 common/src/models/config/tmdb-config.ts       |   18 +
 common/src/models/media/index.ts              |    4 +
 .../models/media/movie-metadata-localized.ts  |   13 +
 common/src/models/media/movie.ts              |    4 -
 .../models/media/series-metadata-localized.ts |   12 +
 common/src/models/media/series.ts             |    6 +-
 .../src/models/media/tmdb-movie-metadata.ts   |   25 +
 .../src/models/media/tmdb-series-metadata.ts  |   21 +
 .../command-providers/search-movie.tsx        |   37 +-
 .../command-providers/search-series.tsx       |   42 +-
 .../src/components/dashboard/movie-widget.tsx |   30 +-
 .../components/dashboard/series-widget.tsx    |   33 +-
 .../related-movies-modal-content.tsx          |    5 +-
 frontend/src/components/movie-picker.tsx      |    4 +-
 frontend/src/pages/admin/app-settings.tsx     |    1 +
 frontend/src/pages/admin/tmdb-settings.tsx    |  212 +
 .../pages/entities/tmdb-movie-metadata.tsx    |   59 +
 .../pages/entities/tmdb-series-metadata.tsx   |   64 +
 frontend/src/pages/movies/movie-overview.tsx  |   20 +-
 .../movie-player-v2-component.tsx             |    2 +-
 frontend/src/pages/movies/series-overview.tsx |   17 +-
 frontend/src/routes/entity-routes.tsx         |   24 +
 frontend/src/routes/settings-routes.tsx       |   11 +
 .../services/localized-metadata-service.ts    |   65 +
 frontend/src/services/movies-service.spec.ts  |   14 +-
 frontend/src/services/series-service.spec.ts  |    5 +-
 .../install/actions/get-service-status.ts     |    1 +
 .../media/metadata-services/tmdb-api-types.ts |  252 +
 .../metadata-services/tmdb-client-service.ts  |  423 ++
 .../src/app-models/media/setup-media-api.ts   |   45 +-
 .../src/app-models/media/setup-media.spec.ts  |    1 -
 service/src/app-models/media/setup-media.ts   |  485 +-
 .../utils/ensure-localized-metadata-exists.ts |   65 +
 .../media/utils/ensure-movie-exists.spec.ts   |   63 +-
 .../media/utils/ensure-movie-exists.ts        |   33 +-
 .../utils/ensure-omdb-series-exists.spec.ts   |   32 +-
 .../media/utils/ensure-omdb-series-exists.ts  |   22 +-
 .../media/utils/ensure-series-exists.ts       |   20 +-
 .../media/utils/ensure-tmdb-movie-exists.ts   |   45 +
 .../media/utils/ensure-tmdb-series-exists.ts  |   97 +
 .../app-models/media/utils/link-movie.spec.ts |   46 +-
 .../src/app-models/media/utils/link-movie.ts  |  187 +-
 .../media/utils/map-omdb-to-localized.ts      |   26 +
 .../media/utils/map-tmdb-to-localized.ts      |   32 +
 61 files changed, 9441 insertions(+), 1504 deletions(-)
 create mode 100644 common/src/models/config/metadata-provider-config.ts
 create mode 100644 common/src/models/config/tmdb-config.ts
 create mode 100644 common/src/models/media/movie-metadata-localized.ts
 create mode 100644 common/src/models/media/series-metadata-localized.ts
 create mode 100644 common/src/models/media/tmdb-movie-metadata.ts
 create mode 100644 common/src/models/media/tmdb-series-metadata.ts
 create mode 100644 frontend/src/pages/admin/tmdb-settings.tsx
 create mode 100644 frontend/src/pages/entities/tmdb-movie-metadata.tsx
 create mode 100644 frontend/src/pages/entities/tmdb-series-metadata.tsx
 create mode 100644 frontend/src/services/localized-metadata-service.ts
 create mode 100644 service/src/app-models/media/metadata-services/tmdb-api-types.ts
 create mode 100644 service/src/app-models/media/metadata-services/tmdb-client-service.ts
 create mode 100644 service/src/app-models/media/utils/ensure-localized-metadata-exists.ts
 create mode 100644 service/src/app-models/media/utils/ensure-tmdb-movie-exists.ts
 create mode 100644 service/src/app-models/media/utils/ensure-tmdb-series-exists.ts
 create mode 100644 service/src/app-models/media/utils/map-omdb-to-localized.ts
 create mode 100644 service/src/app-models/media/utils/map-tmdb-to-localized.ts

diff --git a/common/schemas/ai-api.json b/common/schemas/ai-api.json
index 31a17a87..9f19d8e1 100644
--- a/common/schemas/ai-api.json
+++ b/common/schemas/ai-api.json
@@ -61,7 +61,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -86,7 +101,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -101,7 +131,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -116,7 +161,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -131,7 +191,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
diff --git a/common/schemas/chat-api.json b/common/schemas/chat-api.json
index 11f5476c..943f6f3d 100644
--- a/common/schemas/chat-api.json
+++ b/common/schemas/chat-api.json
@@ -148,7 +148,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -176,7 +191,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -191,7 +221,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -206,7 +251,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -221,7 +281,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
diff --git a/common/schemas/config-api.json b/common/schemas/config-api.json
index 2eb7b7b0..d18ee617 100644
--- a/common/schemas/config-api.json
+++ b/common/schemas/config-api.json
@@ -26,6 +26,14 @@
             {
               "type": "string",
               "const": "OLLAMA_CONFIG"
+            },
+            {
+              "type": "string",
+              "const": "TMDB_CONFIG"
+            },
+            {
+              "type": "string",
+              "const": "METADATA_PROVIDER_CONFIG"
             }
           ],
           "description": "Configuration entry for the OMDB API"
@@ -163,6 +171,43 @@
               },
               "required": ["host"],
               "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "apiKey": {
+                  "type": "string",
+                  "description": "The API key (v3 auth) or Read Access Token (v4 auth / Bearer) for the TMDB API. Can be obtained at https://www.themoviedb.org/settings/api"
+                },
+                "defaultLanguage": {
+                  "type": "string",
+                  "description": "Primary language for metadata fetches, in TMDB locale format (e.g. 'en-US', 'fr-FR')."
+                },
+                "additionalLanguages": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Additional languages to fetch alongside the default (e.g. ['fr-FR', 'de-DE'])."
+                }
+              },
+              "required": ["apiKey", "defaultLanguage", "additionalLanguages"],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "priority": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["omdb", "tmdb"]
+                  },
+                  "description": "Ordered list of metadata providers to try when linking movies. The first available provider that returns a result wins."
+                }
+              },
+              "required": ["priority"],
+              "additionalProperties": false
             }
           ]
         },
@@ -223,7 +268,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -248,7 +308,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -263,7 +338,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -278,7 +368,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -293,7 +398,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -331,6 +451,14 @@
                 {
                   "type": "string",
                   "const": "OLLAMA_CONFIG"
+                },
+                {
+                  "type": "string",
+                  "const": "TMDB_CONFIG"
+                },
+                {
+                  "type": "string",
+                  "const": "METADATA_PROVIDER_CONFIG"
                 }
               ],
               "description": "Configuration entry for the OMDB API"
@@ -402,6 +530,14 @@
                     {
                       "type": "string",
                       "const": "OLLAMA_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "TMDB_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "METADATA_PROVIDER_CONFIG"
                     }
                   ],
                   "description": "Configuration entry for the OMDB API"
@@ -428,6 +564,14 @@
                     {
                       "type": "string",
                       "const": "OLLAMA_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "TMDB_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "METADATA_PROVIDER_CONFIG"
                     }
                   ],
                   "description": "Configuration entry for the OMDB API"
@@ -454,6 +598,14 @@
                     {
                       "type": "string",
                       "const": "OLLAMA_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "TMDB_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "METADATA_PROVIDER_CONFIG"
                     }
                   ],
                   "description": "Configuration entry for the OMDB API"
@@ -480,6 +632,14 @@
                     {
                       "type": "string",
                       "const": "OLLAMA_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "TMDB_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "METADATA_PROVIDER_CONFIG"
                     }
                   ],
                   "description": "Configuration entry for the OMDB API"
@@ -512,6 +672,14 @@
                     {
                       "type": "string",
                       "const": "OLLAMA_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "TMDB_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "METADATA_PROVIDER_CONFIG"
                     }
                   ],
                   "description": "Configuration entry for the OMDB API"
@@ -538,6 +706,14 @@
                     {
                       "type": "string",
                       "const": "OLLAMA_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "TMDB_CONFIG"
+                    },
+                    {
+                      "type": "string",
+                      "const": "METADATA_PROVIDER_CONFIG"
                     }
                   ],
                   "description": "Configuration entry for the OMDB API"
@@ -572,6 +748,14 @@
                       {
                         "type": "string",
                         "const": "OLLAMA_CONFIG"
+                      },
+                      {
+                        "type": "string",
+                        "const": "TMDB_CONFIG"
+                      },
+                      {
+                        "type": "string",
+                        "const": "METADATA_PROVIDER_CONFIG"
                       }
                     ],
                     "description": "Configuration entry for the OMDB API"
@@ -601,6 +785,14 @@
                       {
                         "type": "string",
                         "const": "OLLAMA_CONFIG"
+                      },
+                      {
+                        "type": "string",
+                        "const": "TMDB_CONFIG"
+                      },
+                      {
+                        "type": "string",
+                        "const": "METADATA_PROVIDER_CONFIG"
                       }
                     ],
                     "description": "Configuration entry for the OMDB API"
@@ -749,6 +941,43 @@
                       },
                       "required": ["host"],
                       "additionalProperties": false
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "apiKey": {
+                          "type": "string",
+                          "description": "The API key (v3 auth) or Read Access Token (v4 auth / Bearer) for the TMDB API. Can be obtained at https://www.themoviedb.org/settings/api"
+                        },
+                        "defaultLanguage": {
+                          "type": "string",
+                          "description": "Primary language for metadata fetches, in TMDB locale format (e.g. 'en-US', 'fr-FR')."
+                        },
+                        "additionalLanguages": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          },
+                          "description": "Additional languages to fetch alongside the default (e.g. ['fr-FR', 'de-DE'])."
+                        }
+                      },
+                      "required": ["apiKey", "defaultLanguage", "additionalLanguages"],
+                      "additionalProperties": false
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "priority": {
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "enum": ["omdb", "tmdb"]
+                          },
+                          "description": "Ordered list of metadata providers to try when linking movies. The first available provider that returns a result wins."
+                        }
+                      },
+                      "required": ["priority"],
+                      "additionalProperties": false
                     }
                   ]
                 },
@@ -885,6 +1114,43 @@
                       },
                       "required": ["host"],
                       "additionalProperties": false
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "apiKey": {
+                          "type": "string",
+                          "description": "The API key (v3 auth) or Read Access Token (v4 auth / Bearer) for the TMDB API. Can be obtained at https://www.themoviedb.org/settings/api"
+                        },
+                        "defaultLanguage": {
+                          "type": "string",
+                          "description": "Primary language for metadata fetches, in TMDB locale format (e.g. 'en-US', 'fr-FR')."
+                        },
+                        "additionalLanguages": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          },
+                          "description": "Additional languages to fetch alongside the default (e.g. ['fr-FR', 'de-DE'])."
+                        }
+                      },
+                      "required": ["apiKey", "defaultLanguage", "additionalLanguages"],
+                      "additionalProperties": false
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "priority": {
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "enum": ["omdb", "tmdb"]
+                          },
+                          "description": "Ordered list of metadata providers to try when linking movies. The first available provider that returns a result wins."
+                        }
+                      },
+                      "required": ["priority"],
+                      "additionalProperties": false
                     }
                   ]
                 }
@@ -1029,6 +1295,43 @@
                         },
                         "required": ["host"],
                         "additionalProperties": false
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "apiKey": {
+                            "type": "string",
+                            "description": "The API key (v3 auth) or Read Access Token (v4 auth / Bearer) for the TMDB API. Can be obtained at https://www.themoviedb.org/settings/api"
+                          },
+                          "defaultLanguage": {
+                            "type": "string",
+                            "description": "Primary language for metadata fetches, in TMDB locale format (e.g. 'en-US', 'fr-FR')."
+                          },
+                          "additionalLanguages": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            },
+                            "description": "Additional languages to fetch alongside the default (e.g. ['fr-FR', 'de-DE'])."
+                          }
+                        },
+                        "required": ["apiKey", "defaultLanguage", "additionalLanguages"],
+                        "additionalProperties": false
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "priority": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "enum": ["omdb", "tmdb"]
+                            },
+                            "description": "Ordered list of metadata providers to try when linking movies. The first available provider that returns a result wins."
+                          }
+                        },
+                        "required": ["priority"],
+                        "additionalProperties": false
                       }
                     ]
                   }
@@ -1168,6 +1471,43 @@
                         },
                         "required": ["host"],
                         "additionalProperties": false
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "apiKey": {
+                            "type": "string",
+                            "description": "The API key (v3 auth) or Read Access Token (v4 auth / Bearer) for the TMDB API. Can be obtained at https://www.themoviedb.org/settings/api"
+                          },
+                          "defaultLanguage": {
+                            "type": "string",
+                            "description": "Primary language for metadata fetches, in TMDB locale format (e.g. 'en-US', 'fr-FR')."
+                          },
+                          "additionalLanguages": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            },
+                            "description": "Additional languages to fetch alongside the default (e.g. ['fr-FR', 'de-DE'])."
+                          }
+                        },
+                        "required": ["apiKey", "defaultLanguage", "additionalLanguages"],
+                        "additionalProperties": false
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "priority": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "enum": ["omdb", "tmdb"]
+                            },
+                            "description": "Ordered list of metadata providers to try when linking movies. The first available provider that returns a result wins."
+                          }
+                        },
+                        "required": ["priority"],
+                        "additionalProperties": false
                       }
                     ]
                   }
@@ -1430,6 +1770,14 @@
                 {
                   "type": "string",
                   "const": "OLLAMA_CONFIG"
+                },
+                {
+                  "type": "string",
+                  "const": "TMDB_CONFIG"
+                },
+                {
+                  "type": "string",
+                  "const": "METADATA_PROVIDER_CONFIG"
                 }
               ],
               "description": "The entity's unique identifier"
@@ -1480,6 +1828,14 @@
                 {
                   "type": "string",
                   "const": "OLLAMA_CONFIG"
+                },
+                {
+                  "type": "string",
+                  "const": "TMDB_CONFIG"
+                },
+                {
+                  "type": "string",
+                  "const": "METADATA_PROVIDER_CONFIG"
                 }
               ],
               "description": "Configuration entry for the OMDB API"
@@ -1632,6 +1988,43 @@
               },
               "required": ["host"],
               "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "apiKey": {
+                  "type": "string",
+                  "description": "The API key (v3 auth) or Read Access Token (v4 auth / Bearer) for the TMDB API. Can be obtained at https://www.themoviedb.org/settings/api"
+                },
+                "defaultLanguage": {
+                  "type": "string",
+                  "description": "Primary language for metadata fetches, in TMDB locale format (e.g. 'en-US', 'fr-FR')."
+                },
+                "additionalLanguages": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Additional languages to fetch alongside the default (e.g. ['fr-FR', 'de-DE'])."
+                }
+              },
+              "required": ["apiKey", "defaultLanguage", "additionalLanguages"],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "priority": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["omdb", "tmdb"]
+                  },
+                  "description": "Ordered list of metadata providers to try when linking movies. The first available provider that returns a result wins."
+                }
+              },
+              "required": ["priority"],
+              "additionalProperties": false
             }
           ]
         }
@@ -1664,6 +2057,14 @@
             {
               "type": "string",
               "const": "OLLAMA_CONFIG"
+            },
+            {
+              "type": "string",
+              "const": "TMDB_CONFIG"
+            },
+            {
+              "type": "string",
+              "const": "METADATA_PROVIDER_CONFIG"
             }
           ],
           "description": "Configuration entry for the OMDB API"
@@ -1801,6 +2202,43 @@
               },
               "required": ["host"],
               "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "apiKey": {
+                  "type": "string",
+                  "description": "The API key (v3 auth) or Read Access Token (v4 auth / Bearer) for the TMDB API. Can be obtained at https://www.themoviedb.org/settings/api"
+                },
+                "defaultLanguage": {
+                  "type": "string",
+                  "description": "Primary language for metadata fetches, in TMDB locale format (e.g. 'en-US', 'fr-FR')."
+                },
+                "additionalLanguages": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Additional languages to fetch alongside the default (e.g. ['fr-FR', 'de-DE'])."
+                }
+              },
+              "required": ["apiKey", "defaultLanguage", "additionalLanguages"],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "priority": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["omdb", "tmdb"]
+                  },
+                  "description": "Ordered list of metadata providers to try when linking movies. The first available provider that returns a result wins."
+                }
+              },
+              "required": ["priority"],
+              "additionalProperties": false
             }
           ]
         }
diff --git a/common/schemas/config-entities.json b/common/schemas/config-entities.json
index 454cf1ed..72b5ec27 100644
--- a/common/schemas/config-entities.json
+++ b/common/schemas/config-entities.json
@@ -26,6 +26,14 @@
             {
               "type": "string",
               "const": "OLLAMA_CONFIG"
+            },
+            {
+              "type": "string",
+              "const": "TMDB_CONFIG"
+            },
+            {
+              "type": "string",
+              "const": "METADATA_PROVIDER_CONFIG"
             }
           ],
           "description": "Configuration entry for the OMDB API"
@@ -163,6 +171,43 @@
               },
               "required": ["host"],
               "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "apiKey": {
+                  "type": "string",
+                  "description": "The API key (v3 auth) or Read Access Token (v4 auth / Bearer) for the TMDB API. Can be obtained at https://www.themoviedb.org/settings/api"
+                },
+                "defaultLanguage": {
+                  "type": "string",
+                  "description": "Primary language for metadata fetches, in TMDB locale format (e.g. 'en-US', 'fr-FR')."
+                },
+                "additionalLanguages": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Additional languages to fetch alongside the default (e.g. ['fr-FR', 'de-DE'])."
+                }
+              },
+              "required": ["apiKey", "defaultLanguage", "additionalLanguages"],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "priority": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["omdb", "tmdb"]
+                  },
+                  "description": "Ordered list of metadata providers to try when linking movies. The first available provider that returns a result wins."
+                }
+              },
+              "required": ["priority"],
+              "additionalProperties": false
             }
           ]
         },
@@ -194,6 +239,12 @@
         },
         {
           "$ref": "#/definitions/OllamaConfig"
+        },
+        {
+          "$ref": "#/definitions/TmdbConfig"
+        },
+        {
+          "$ref": "#/definitions/MetadataProviderConfig"
         }
       ]
     },
@@ -247,6 +298,32 @@
       "required": ["id", "value"],
       "additionalProperties": false
     },
+    "MetadataProviderConfig": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "const": "METADATA_PROVIDER_CONFIG"
+        },
+        "value": {
+          "type": "object",
+          "properties": {
+            "priority": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": ["omdb", "tmdb"]
+              },
+              "description": "Ordered list of metadata providers to try when linking movies. The first available provider that returns a result wins."
+            }
+          },
+          "required": ["priority"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["id", "value"],
+      "additionalProperties": false
+    },
     "MoviesConfig": {
       "type": "object",
       "properties": {
@@ -374,6 +451,39 @@
       },
       "required": ["id", "value"],
       "additionalProperties": false
+    },
+    "TmdbConfig": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "const": "TMDB_CONFIG"
+        },
+        "value": {
+          "type": "object",
+          "properties": {
+            "apiKey": {
+              "type": "string",
+              "description": "The API key (v3 auth) or Read Access Token (v4 auth / Bearer) for the TMDB API. Can be obtained at https://www.themoviedb.org/settings/api"
+            },
+            "defaultLanguage": {
+              "type": "string",
+              "description": "Primary language for metadata fetches, in TMDB locale format (e.g. 'en-US', 'fr-FR')."
+            },
+            "additionalLanguages": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Additional languages to fetch alongside the default (e.g. ['fr-FR', 'de-DE'])."
+            }
+          },
+          "required": ["apiKey", "defaultLanguage", "additionalLanguages"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["id", "value"],
+      "additionalProperties": false
     }
   }
 }
diff --git a/common/schemas/dashboards-api.json b/common/schemas/dashboards-api.json
index 55c46089..a9686f73 100644
--- a/common/schemas/dashboards-api.json
+++ b/common/schemas/dashboards-api.json
@@ -123,7 +123,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -148,7 +163,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -163,7 +193,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -178,7 +223,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -193,7 +253,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
diff --git a/common/schemas/drives-api.json b/common/schemas/drives-api.json
index addbbc9d..89a2e7eb 100644
--- a/common/schemas/drives-api.json
+++ b/common/schemas/drives-api.json
@@ -261,7 +261,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -276,7 +291,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -291,7 +321,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -306,7 +351,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
diff --git a/common/schemas/identity-api.json b/common/schemas/identity-api.json
index 4f09af85..63231882 100644
--- a/common/schemas/identity-api.json
+++ b/common/schemas/identity-api.json
@@ -453,7 +453,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -478,7 +493,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -493,7 +523,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -508,7 +553,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -523,7 +583,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
diff --git a/common/schemas/install-api.json b/common/schemas/install-api.json
index e5792ef6..30eeb01c 100644
--- a/common/schemas/install-api.json
+++ b/common/schemas/install-api.json
@@ -73,7 +73,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -88,7 +103,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -103,7 +133,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -118,7 +163,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -133,7 +193,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -148,7 +223,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -163,7 +253,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -190,12 +295,16 @@
               "type": "boolean",
               "description": "OMDB API Installation Status for metadata fetching"
             },
+            "tmdb": {
+              "type": "boolean",
+              "description": "TMDB API Installation Status for metadata fetching"
+            },
             "github": {
               "type": "boolean",
               "description": "Github API Installation Status for external authentication"
             }
           },
-          "required": ["omdb", "github"],
+          "required": ["omdb", "tmdb", "github"],
           "additionalProperties": false
         }
       },
diff --git a/common/schemas/iot-api.json b/common/schemas/iot-api.json
index 7f2752a9..35dd7e49 100644
--- a/common/schemas/iot-api.json
+++ b/common/schemas/iot-api.json
@@ -1357,7 +1357,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -1382,7 +1397,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -1397,7 +1427,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -1412,7 +1457,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -1427,7 +1487,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
diff --git a/common/schemas/logging-api.json b/common/schemas/logging-api.json
index 8ab04a1b..18083383 100644
--- a/common/schemas/logging-api.json
+++ b/common/schemas/logging-api.json
@@ -567,7 +567,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -582,7 +597,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -597,7 +627,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -612,7 +657,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -627,7 +687,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -642,7 +717,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -657,7 +747,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -672,7 +777,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
diff --git a/common/schemas/media-api.json b/common/schemas/media-api.json
index 8964bd68..98f1b3cd 100644
--- a/common/schemas/media-api.json
+++ b/common/schemas/media-api.json
@@ -528,58 +528,6 @@
             }
           ]
         },
-        "title": {
-          "anyOf": [
-            {
-              "type": "object",
-              "properties": {
-                "$startsWith": {
-                  "type": "string"
-                },
-                "$endsWith": {
-                  "type": "string"
-                },
-                "$like": {
-                  "type": "string"
-                },
-                "$regex": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
-            {
-              "type": "object",
-              "properties": {
-                "$eq": {
-                  "type": "string"
-                },
-                "$ne": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
-            {
-              "type": "object",
-              "properties": {
-                "$in": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                },
-                "$nin": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          ]
-        },
         "year": {
           "anyOf": [
             {
@@ -676,162 +624,6 @@
             }
           ]
         },
-        "genre": {
-          "anyOf": [
-            {
-              "type": "object",
-              "properties": {
-                "$eq": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                },
-                "$ne": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                }
-              },
-              "additionalProperties": false
-            },
-            {
-              "type": "object",
-              "properties": {
-                "$in": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        }
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
-                },
-                "$nin": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        }
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          ]
-        },
-        "thumbnailImageUrl": {
-          "anyOf": [
-            {
-              "type": "object",
-              "properties": {
-                "$eq": {
-                  "type": "string"
-                },
-                "$ne": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
-            {
-              "type": "object",
-              "properties": {
-                "$in": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
-                },
-                "$nin": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          ]
-        },
-        "plot": {
-          "anyOf": [
-            {
-              "type": "object",
-              "properties": {
-                "$eq": {
-                  "type": "string"
-                },
-                "$ne": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
-            {
-              "type": "object",
-              "properties": {
-                "$in": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
-                },
-                "$nin": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          ]
-        },
         "type": {
           "anyOf": [
             {
@@ -1514,35 +1306,35 @@
         }
       }
     },
-    "FilterType<OmdbMovieMetadata>": {
+    "FilterType<MovieMetadataLocalized>": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
         "$and": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/FilterType%3COmdbMovieMetadata%3E"
+            "$ref": "#/definitions/FilterType%3CMovieMetadataLocalized%3E"
           }
         },
         "$not": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/FilterType%3COmdbMovieMetadata%3E"
+            "$ref": "#/definitions/FilterType%3CMovieMetadataLocalized%3E"
           }
         },
         "$nor": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/FilterType%3COmdbMovieMetadata%3E"
+            "$ref": "#/definitions/FilterType%3CMovieMetadataLocalized%3E"
           }
         },
         "$or": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/FilterType%3COmdbMovieMetadata%3E"
+            "$ref": "#/definitions/FilterType%3CMovieMetadataLocalized%3E"
           }
         },
-        "Title": {
+        "id": {
           "anyOf": [
             {
               "type": "object",
@@ -1594,7 +1386,7 @@
             }
           ]
         },
-        "Year": {
+        "movieImdbId": {
           "anyOf": [
             {
               "type": "object",
@@ -1646,7 +1438,7 @@
             }
           ]
         },
-        "Rated": {
+        "language": {
           "anyOf": [
             {
               "type": "object",
@@ -1698,7 +1490,7 @@
             }
           ]
         },
-        "Released": {
+        "title": {
           "anyOf": [
             {
               "type": "object",
@@ -1750,26 +1542,8 @@
             }
           ]
         },
-        "Runtime": {
+        "plot": {
           "anyOf": [
-            {
-              "type": "object",
-              "properties": {
-                "$startsWith": {
-                  "type": "string"
-                },
-                "$endsWith": {
-                  "type": "string"
-                },
-                "$like": {
-                  "type": "string"
-                },
-                "$regex": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
             {
               "type": "object",
               "properties": {
@@ -1788,48 +1562,98 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string"
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          ]
-        },
-        "Genre": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "posterUrl": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
-                "$startsWith": {
-                  "type": "string"
-                },
-                "$endsWith": {
-                  "type": "string"
-                },
-                "$like": {
+                "$eq": {
                   "type": "string"
                 },
-                "$regex": {
+                "$ne": {
                   "type": "string"
                 }
               },
               "additionalProperties": false
             },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "genre": {
+          "anyOf": [
             {
               "type": "object",
               "properties": {
                 "$eq": {
-                  "type": "string"
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
                 },
                 "$ne": {
-                  "type": "string"
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
                 }
               },
               "additionalProperties": false
@@ -1840,13 +1664,33 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 }
               },
@@ -1854,26 +1698,68 @@
             }
           ]
         },
-        "Director": {
+        "source": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
                 "$startsWith": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
                 },
                 "$endsWith": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
                 },
                 "$like": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
                 },
                 "$regex": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
+                },
+                "$ne": {
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
                 }
               },
               "additionalProperties": false
             },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["omdb", "tmdb"]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["omdb", "tmdb"]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "sourceId": {
+          "anyOf": [
             {
               "type": "object",
               "properties": {
@@ -1892,13 +1778,27 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 }
               },
@@ -1906,7 +1806,7 @@
             }
           ]
         },
-        "Writer": {
+        "createdAt": {
           "anyOf": [
             {
               "type": "object",
@@ -1958,7 +1858,7 @@
             }
           ]
         },
-        "Actors": {
+        "updatedAt": {
           "anyOf": [
             {
               "type": "object",
@@ -2009,8 +1909,38 @@
               "additionalProperties": false
             }
           ]
+        }
+      }
+    },
+    "FilterType<OmdbMovieMetadata>": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$and": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3COmdbMovieMetadata%3E"
+          }
         },
-        "Plot": {
+        "$not": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3COmdbMovieMetadata%3E"
+          }
+        },
+        "$nor": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3COmdbMovieMetadata%3E"
+          }
+        },
+        "$or": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3COmdbMovieMetadata%3E"
+          }
+        },
+        "Title": {
           "anyOf": [
             {
               "type": "object",
@@ -2062,7 +1992,7 @@
             }
           ]
         },
-        "Language": {
+        "Year": {
           "anyOf": [
             {
               "type": "object",
@@ -2114,7 +2044,7 @@
             }
           ]
         },
-        "Country": {
+        "Rated": {
           "anyOf": [
             {
               "type": "object",
@@ -2166,7 +2096,7 @@
             }
           ]
         },
-        "Awards": {
+        "Released": {
           "anyOf": [
             {
               "type": "object",
@@ -2218,7 +2148,7 @@
             }
           ]
         },
-        "Poster": {
+        "Runtime": {
           "anyOf": [
             {
               "type": "object",
@@ -2270,42 +2200,34 @@
             }
           ]
         },
-        "Ratings": {
+        "Genre": {
           "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
             {
               "type": "object",
               "properties": {
                 "$eq": {
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "Source": {
-                        "type": "string"
-                      },
-                      "Value": {
-                        "type": "string"
-                      }
-                    },
-                    "required": ["Source", "Value"],
-                    "additionalProperties": false
-                  }
+                  "type": "string"
                 },
                 "$ne": {
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "Source": {
-                        "type": "string"
-                      },
-                      "Value": {
-                        "type": "string"
-                      }
-                    },
-                    "required": ["Source", "Value"],
-                    "additionalProperties": false
-                  }
+                  "type": "string"
                 }
               },
               "additionalProperties": false
@@ -2316,39 +2238,13 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "array",
-                    "items": {
-                      "type": "object",
-                      "properties": {
-                        "Source": {
-                          "type": "string"
-                        },
-                        "Value": {
-                          "type": "string"
-                        }
-                      },
-                      "required": ["Source", "Value"],
-                      "additionalProperties": false
-                    }
+                    "type": "string"
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "array",
-                    "items": {
-                      "type": "object",
-                      "properties": {
-                        "Source": {
-                          "type": "string"
-                        },
-                        "Value": {
-                          "type": "string"
-                        }
-                      },
-                      "required": ["Source", "Value"],
-                      "additionalProperties": false
-                    }
+                    "type": "string"
                   }
                 }
               },
@@ -2356,7 +2252,7 @@
             }
           ]
         },
-        "Metascore": {
+        "Director": {
           "anyOf": [
             {
               "type": "object",
@@ -2408,7 +2304,7 @@
             }
           ]
         },
-        "imdbRating": {
+        "Writer": {
           "anyOf": [
             {
               "type": "object",
@@ -2460,7 +2356,7 @@
             }
           ]
         },
-        "imdbVotes": {
+        "Actors": {
           "anyOf": [
             {
               "type": "object",
@@ -2512,7 +2408,7 @@
             }
           ]
         },
-        "imdbID": {
+        "Plot": {
           "anyOf": [
             {
               "type": "object",
@@ -2564,26 +2460,22 @@
             }
           ]
         },
-        "Type": {
+        "Language": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
                 "$startsWith": {
-                  "type": "string",
-                  "enum": ["movie", "episode"]
+                  "type": "string"
                 },
                 "$endsWith": {
-                  "type": "string",
-                  "enum": ["movie", "episode"]
+                  "type": "string"
                 },
                 "$like": {
-                  "type": "string",
-                  "enum": ["movie", "episode"]
+                  "type": "string"
                 },
                 "$regex": {
-                  "type": "string",
-                  "enum": ["movie", "episode"]
+                  "type": "string"
                 }
               },
               "additionalProperties": false
@@ -2592,12 +2484,10 @@
               "type": "object",
               "properties": {
                 "$eq": {
-                  "type": "string",
-                  "enum": ["movie", "episode"]
+                  "type": "string"
                 },
                 "$ne": {
-                  "type": "string",
-                  "enum": ["movie", "episode"]
+                  "type": "string"
                 }
               },
               "additionalProperties": false
@@ -2608,15 +2498,13 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string",
-                    "enum": ["movie", "episode"]
+                    "type": "string"
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string",
-                    "enum": ["movie", "episode"]
+                    "type": "string"
                   }
                 }
               },
@@ -2624,56 +2512,26 @@
             }
           ]
         },
-        "DVD": {
+        "Country": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
-                "$eq": {
+                "$startsWith": {
                   "type": "string"
                 },
-                "$ne": {
+                "$endsWith": {
                   "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
-            {
-              "type": "object",
-              "properties": {
-                "$in": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
                 },
-                "$nin": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
                 }
               },
               "additionalProperties": false
-            }
-          ]
-        },
-        "BoxOffice": {
-          "anyOf": [
+            },
             {
               "type": "object",
               "properties": {
@@ -2692,27 +2550,13 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
+                    "type": "string"
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
+                    "type": "string"
                   }
                 }
               },
@@ -2720,56 +2564,26 @@
             }
           ]
         },
-        "Production": {
+        "Awards": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
-                "$eq": {
+                "$startsWith": {
                   "type": "string"
                 },
-                "$ne": {
+                "$endsWith": {
                   "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
-            {
-              "type": "object",
-              "properties": {
-                "$in": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
                 },
-                "$nin": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
                 }
               },
               "additionalProperties": false
-            }
-          ]
-        },
-        "Website": {
-          "anyOf": [
+            },
             {
               "type": "object",
               "properties": {
@@ -2788,27 +2602,13 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
+                    "type": "string"
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
+                    "type": "string"
                   }
                 }
               },
@@ -2816,26 +2616,22 @@
             }
           ]
         },
-        "Response": {
+        "Poster": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
                 "$startsWith": {
-                  "type": "string",
-                  "const": "True"
+                  "type": "string"
                 },
                 "$endsWith": {
-                  "type": "string",
-                  "const": "True"
+                  "type": "string"
                 },
                 "$like": {
-                  "type": "string",
-                  "const": "True"
+                  "type": "string"
                 },
                 "$regex": {
-                  "type": "string",
-                  "const": "True"
+                  "type": "string"
                 }
               },
               "additionalProperties": false
@@ -2844,12 +2640,10 @@
               "type": "object",
               "properties": {
                 "$eq": {
-                  "type": "string",
-                  "const": "True"
+                  "type": "string"
                 },
                 "$ne": {
-                  "type": "string",
-                  "const": "True"
+                  "type": "string"
                 }
               },
               "additionalProperties": false
@@ -2860,15 +2654,13 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string",
-                    "const": "True"
+                    "type": "string"
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string",
-                    "const": "True"
+                    "type": "string"
                   }
                 }
               },
@@ -2876,115 +2668,45 @@
             }
           ]
         },
-        "seriesID": {
+        "Ratings": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
                 "$eq": {
-                  "type": "string"
-                },
-                "$ne": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
-            {
-              "type": "object",
-              "properties": {
-                "$in": {
                   "type": "array",
                   "items": {
-                    "anyOf": [
-                      {
+                    "type": "object",
+                    "properties": {
+                      "Source": {
                         "type": "string"
                       },
-                      {
-                        "not": {}
+                      "Value": {
+                        "type": "string"
                       }
-                    ]
+                    },
+                    "required": ["Source", "Value"],
+                    "additionalProperties": false
                   }
                 },
-                "$nin": {
+                "$ne": {
                   "type": "array",
                   "items": {
-                    "anyOf": [
-                      {
+                    "type": "object",
+                    "properties": {
+                      "Source": {
                         "type": "string"
                       },
-                      {
-                        "not": {}
+                      "Value": {
+                        "type": "string"
                       }
-                    ]
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          ]
-        },
-        "Season": {
-          "anyOf": [
-            {
-              "type": "object",
-              "properties": {
-                "$eq": {
-                  "type": "string"
-                },
-                "$ne": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
-            {
-              "type": "object",
-              "properties": {
-                "$in": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
-                  }
-                },
-                "$nin": {
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
+                    },
+                    "required": ["Source", "Value"],
+                    "additionalProperties": false
                   }
                 }
               },
               "additionalProperties": false
-            }
-          ]
-        },
-        "Episode": {
-          "anyOf": [
-            {
-              "type": "object",
-              "properties": {
-                "$eq": {
-                  "type": "string"
-                },
-                "$ne": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
             },
             {
               "type": "object",
@@ -2992,27 +2714,39 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "Source": {
+                          "type": "string"
+                        },
+                        "Value": {
+                          "type": "string"
+                        }
                       },
-                      {
-                        "not": {}
-                      }
-                    ]
+                      "required": ["Source", "Value"],
+                      "additionalProperties": false
+                    }
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "Source": {
+                          "type": "string"
+                        },
+                        "Value": {
+                          "type": "string"
+                        }
                       },
-                      {
-                        "not": {}
-                      }
-                    ]
+                      "required": ["Source", "Value"],
+                      "additionalProperties": false
+                    }
                   }
                 }
               },
@@ -3020,7 +2754,7 @@
             }
           ]
         },
-        "createdAt": {
+        "Metascore": {
           "anyOf": [
             {
               "type": "object",
@@ -3072,7 +2806,7 @@
             }
           ]
         },
-        "updatedAt": {
+        "imdbRating": {
           "anyOf": [
             {
               "type": "object",
@@ -3123,38 +2857,8 @@
               "additionalProperties": false
             }
           ]
-        }
-      }
-    },
-    "FilterType<OmdbSeriesMetadata>": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "$and": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3COmdbSeriesMetadata%3E"
-          }
-        },
-        "$not": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3COmdbSeriesMetadata%3E"
-          }
-        },
-        "$nor": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3COmdbSeriesMetadata%3E"
-          }
-        },
-        "$or": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3COmdbSeriesMetadata%3E"
-          }
         },
-        "Title": {
+        "imdbVotes": {
           "anyOf": [
             {
               "type": "object",
@@ -3206,7 +2910,7 @@
             }
           ]
         },
-        "Year": {
+        "imdbID": {
           "anyOf": [
             {
               "type": "object",
@@ -3258,22 +2962,26 @@
             }
           ]
         },
-        "Rated": {
+        "Type": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
                 "$startsWith": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": ["movie", "episode"]
                 },
                 "$endsWith": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": ["movie", "episode"]
                 },
                 "$like": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": ["movie", "episode"]
                 },
                 "$regex": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": ["movie", "episode"]
                 }
               },
               "additionalProperties": false
@@ -3282,10 +2990,12 @@
               "type": "object",
               "properties": {
                 "$eq": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": ["movie", "episode"]
                 },
                 "$ne": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": ["movie", "episode"]
                 }
               },
               "additionalProperties": false
@@ -3296,13 +3006,15 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "type": "string",
+                    "enum": ["movie", "episode"]
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "type": "string",
+                    "enum": ["movie", "episode"]
                   }
                 }
               },
@@ -3310,26 +3022,8 @@
             }
           ]
         },
-        "Released": {
+        "DVD": {
           "anyOf": [
-            {
-              "type": "object",
-              "properties": {
-                "$startsWith": {
-                  "type": "string"
-                },
-                "$endsWith": {
-                  "type": "string"
-                },
-                "$like": {
-                  "type": "string"
-                },
-                "$regex": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
             {
               "type": "object",
               "properties": {
@@ -3348,13 +3042,27 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 }
               },
@@ -3362,26 +3070,8 @@
             }
           ]
         },
-        "Runtime": {
+        "BoxOffice": {
           "anyOf": [
-            {
-              "type": "object",
-              "properties": {
-                "$startsWith": {
-                  "type": "string"
-                },
-                "$endsWith": {
-                  "type": "string"
-                },
-                "$like": {
-                  "type": "string"
-                },
-                "$regex": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
-            },
             {
               "type": "object",
               "properties": {
@@ -3400,13 +3090,27 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 }
               },
@@ -3414,26 +3118,56 @@
             }
           ]
         },
-        "Genre": {
+        "Production": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
-                "$startsWith": {
-                  "type": "string"
-                },
-                "$endsWith": {
+                "$eq": {
                   "type": "string"
                 },
-                "$like": {
-                  "type": "string"
-                },
-                "$regex": {
+                "$ne": {
                   "type": "string"
                 }
               },
               "additionalProperties": false
             },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "Website": {
+          "anyOf": [
             {
               "type": "object",
               "properties": {
@@ -3452,13 +3186,27 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 }
               },
@@ -3466,22 +3214,26 @@
             }
           ]
         },
-        "Director": {
+        "Response": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
                 "$startsWith": {
-                  "type": "string"
+                  "type": "string",
+                  "const": "True"
                 },
                 "$endsWith": {
-                  "type": "string"
+                  "type": "string",
+                  "const": "True"
                 },
                 "$like": {
-                  "type": "string"
+                  "type": "string",
+                  "const": "True"
                 },
                 "$regex": {
-                  "type": "string"
+                  "type": "string",
+                  "const": "True"
                 }
               },
               "additionalProperties": false
@@ -3490,10 +3242,12 @@
               "type": "object",
               "properties": {
                 "$eq": {
-                  "type": "string"
+                  "type": "string",
+                  "const": "True"
                 },
                 "$ne": {
-                  "type": "string"
+                  "type": "string",
+                  "const": "True"
                 }
               },
               "additionalProperties": false
@@ -3504,13 +3258,15 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "type": "string",
+                    "const": "True"
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "type": "string",
+                    "const": "True"
                   }
                 }
               },
@@ -3518,26 +3274,104 @@
             }
           ]
         },
-        "Writer": {
+        "seriesID": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
-                "$startsWith": {
+                "$eq": {
                   "type": "string"
                 },
-                "$endsWith": {
+                "$ne": {
                   "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
                 },
-                "$like": {
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "Season": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
                   "type": "string"
                 },
-                "$regex": {
+                "$ne": {
                   "type": "string"
                 }
               },
               "additionalProperties": false
             },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "Episode": {
+          "anyOf": [
             {
               "type": "object",
               "properties": {
@@ -3556,13 +3390,27 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "string"
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
                   }
                 }
               },
@@ -3570,7 +3418,7 @@
             }
           ]
         },
-        "Actors": {
+        "createdAt": {
           "anyOf": [
             {
               "type": "object",
@@ -3622,7 +3470,7 @@
             }
           ]
         },
-        "Plot": {
+        "updatedAt": {
           "anyOf": [
             {
               "type": "object",
@@ -3673,8 +3521,38 @@
               "additionalProperties": false
             }
           ]
+        }
+      }
+    },
+    "FilterType<OmdbSeriesMetadata>": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$and": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3COmdbSeriesMetadata%3E"
+          }
         },
-        "Language": {
+        "$not": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3COmdbSeriesMetadata%3E"
+          }
+        },
+        "$nor": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3COmdbSeriesMetadata%3E"
+          }
+        },
+        "$or": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3COmdbSeriesMetadata%3E"
+          }
+        },
+        "Title": {
           "anyOf": [
             {
               "type": "object",
@@ -3726,7 +3604,7 @@
             }
           ]
         },
-        "Country": {
+        "Year": {
           "anyOf": [
             {
               "type": "object",
@@ -3778,7 +3656,7 @@
             }
           ]
         },
-        "Awards": {
+        "Rated": {
           "anyOf": [
             {
               "type": "object",
@@ -3830,7 +3708,7 @@
             }
           ]
         },
-        "Poster": {
+        "Released": {
           "anyOf": [
             {
               "type": "object",
@@ -3882,42 +3760,34 @@
             }
           ]
         },
-        "Ratings": {
+        "Runtime": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
-                "$eq": {
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "Source": {
-                        "type": "string"
-                      },
-                      "Value": {
-                        "type": "string"
-                      }
-                    },
-                    "required": ["Source", "Value"],
-                    "additionalProperties": false
-                  }
+                "$startsWith": {
+                  "type": "string"
                 },
-                "$ne": {
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "Source": {
-                        "type": "string"
-                      },
-                      "Value": {
-                        "type": "string"
-                      }
-                    },
-                    "required": ["Source", "Value"],
-                    "additionalProperties": false
-                  }
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
                 }
               },
               "additionalProperties": false
@@ -3928,39 +3798,13 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "array",
-                    "items": {
-                      "type": "object",
-                      "properties": {
-                        "Source": {
-                          "type": "string"
-                        },
-                        "Value": {
-                          "type": "string"
-                        }
-                      },
-                      "required": ["Source", "Value"],
-                      "additionalProperties": false
-                    }
+                    "type": "string"
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "array",
-                    "items": {
-                      "type": "object",
-                      "properties": {
-                        "Source": {
-                          "type": "string"
-                        },
-                        "Value": {
-                          "type": "string"
-                        }
-                      },
-                      "required": ["Source", "Value"],
-                      "additionalProperties": false
-                    }
+                    "type": "string"
                   }
                 }
               },
@@ -3968,7 +3812,7 @@
             }
           ]
         },
-        "Metascore": {
+        "Genre": {
           "anyOf": [
             {
               "type": "object",
@@ -4020,7 +3864,7 @@
             }
           ]
         },
-        "imdbRating": {
+        "Director": {
           "anyOf": [
             {
               "type": "object",
@@ -4072,7 +3916,7 @@
             }
           ]
         },
-        "imdbVotes": {
+        "Writer": {
           "anyOf": [
             {
               "type": "object",
@@ -4124,7 +3968,7 @@
             }
           ]
         },
-        "imdbID": {
+        "Actors": {
           "anyOf": [
             {
               "type": "object",
@@ -4176,7 +4020,7 @@
             }
           ]
         },
-        "Type": {
+        "Plot": {
           "anyOf": [
             {
               "type": "object",
@@ -4228,7 +4072,7 @@
             }
           ]
         },
-        "totalSeasons": {
+        "Language": {
           "anyOf": [
             {
               "type": "object",
@@ -4280,7 +4124,7 @@
             }
           ]
         },
-        "Response": {
+        "Country": {
           "anyOf": [
             {
               "type": "object",
@@ -4332,7 +4176,7 @@
             }
           ]
         },
-        "createdAt": {
+        "Awards": {
           "anyOf": [
             {
               "type": "object",
@@ -4384,7 +4228,7 @@
             }
           ]
         },
-        "updatedAt": {
+        "Poster": {
           "anyOf": [
             {
               "type": "object",
@@ -4435,38 +4279,94 @@
               "additionalProperties": false
             }
           ]
-        }
-      }
-    },
-    "FilterType<Series>": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "$and": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3CSeries%3E"
-          }
-        },
-        "$not": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3CSeries%3E"
-          }
-        },
-        "$nor": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3CSeries%3E"
-          }
         },
-        "$or": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3CSeries%3E"
-          }
+        "Ratings": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "Source": {
+                        "type": "string"
+                      },
+                      "Value": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["Source", "Value"],
+                    "additionalProperties": false
+                  }
+                },
+                "$ne": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "Source": {
+                        "type": "string"
+                      },
+                      "Value": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["Source", "Value"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "Source": {
+                          "type": "string"
+                        },
+                        "Value": {
+                          "type": "string"
+                        }
+                      },
+                      "required": ["Source", "Value"],
+                      "additionalProperties": false
+                    }
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "Source": {
+                          "type": "string"
+                        },
+                        "Value": {
+                          "type": "string"
+                        }
+                      },
+                      "required": ["Source", "Value"],
+                      "additionalProperties": false
+                    }
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
         },
-        "imdbId": {
+        "Metascore": {
           "anyOf": [
             {
               "type": "object",
@@ -4518,7 +4418,7 @@
             }
           ]
         },
-        "title": {
+        "imdbRating": {
           "anyOf": [
             {
               "type": "object",
@@ -4570,7 +4470,7 @@
             }
           ]
         },
-        "year": {
+        "imdbVotes": {
           "anyOf": [
             {
               "type": "object",
@@ -4622,8 +4522,26 @@
             }
           ]
         },
-        "thumbnailImageUrl": {
+        "imdbID": {
           "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
             {
               "type": "object",
               "properties": {
@@ -4642,27 +4560,13 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
+                    "type": "string"
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "not": {}
-                      }
-                    ]
+                    "type": "string"
                   }
                 }
               },
@@ -4670,7 +4574,7 @@
             }
           ]
         },
-        "plot": {
+        "Type": {
           "anyOf": [
             {
               "type": "object",
@@ -4722,7 +4626,7 @@
             }
           ]
         },
-        "createdAt": {
+        "totalSeasons": {
           "anyOf": [
             {
               "type": "object",
@@ -4774,7 +4678,7 @@
             }
           ]
         },
-        "updatedAt": {
+        "Response": {
           "anyOf": [
             {
               "type": "object",
@@ -4825,38 +4729,8 @@
               "additionalProperties": false
             }
           ]
-        }
-      }
-    },
-    "FilterType<WatchHistoryEntry>": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "$and": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3CWatchHistoryEntry%3E"
-          }
         },
-        "$not": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3CWatchHistoryEntry%3E"
-          }
-        },
-        "$nor": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3CWatchHistoryEntry%3E"
-          }
-        },
-        "$or": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FilterType%3CWatchHistoryEntry%3E"
-          }
-        },
-        "id": {
+        "createdAt": {
           "anyOf": [
             {
               "type": "object",
@@ -4908,7 +4782,7 @@
             }
           ]
         },
-        "userName": {
+        "updatedAt": {
           "anyOf": [
             {
               "type": "object",
@@ -4959,8 +4833,38 @@
               "additionalProperties": false
             }
           ]
+        }
+      }
+    },
+    "FilterType<Series>": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$and": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CSeries%3E"
+          }
         },
-        "driveLetter": {
+        "$not": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CSeries%3E"
+          }
+        },
+        "$nor": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CSeries%3E"
+          }
+        },
+        "$or": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CSeries%3E"
+          }
+        },
+        "imdbId": {
           "anyOf": [
             {
               "type": "object",
@@ -5012,7 +4916,7 @@
             }
           ]
         },
-        "path": {
+        "year": {
           "anyOf": [
             {
               "type": "object",
@@ -5064,22 +4968,70 @@
             }
           ]
         },
-        "watchedSeconds": {
+        "numberOfSeasons": {
           "anyOf": [
             {
               "type": "object",
               "properties": {
-                "$gt": {
+                "$eq": {
                   "type": "number"
                 },
-                "$gte": {
+                "$ne": {
                   "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
                 },
-                "$lt": {
-                  "type": "number"
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
                 },
-                "$lte": {
-                  "type": "number"
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
                 }
               },
               "additionalProperties": false
@@ -5088,10 +5040,10 @@
               "type": "object",
               "properties": {
                 "$eq": {
-                  "type": "number"
+                  "type": "string"
                 },
                 "$ne": {
-                  "type": "number"
+                  "type": "string"
                 }
               },
               "additionalProperties": false
@@ -5102,13 +5054,13 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "number"
+                    "type": "string"
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "number"
+                    "type": "string"
                   }
                 }
               },
@@ -5116,16 +5068,34 @@
             }
           ]
         },
-        "completed": {
+        "updatedAt": {
           "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
             {
               "type": "object",
               "properties": {
                 "$eq": {
-                  "type": "boolean"
+                  "type": "string"
                 },
                 "$ne": {
-                  "type": "boolean"
+                  "type": "string"
                 }
               },
               "additionalProperties": false
@@ -5136,21 +5106,51 @@
                 "$in": {
                   "type": "array",
                   "items": {
-                    "type": "boolean"
+                    "type": "string"
                   }
                 },
                 "$nin": {
                   "type": "array",
                   "items": {
-                    "type": "boolean"
+                    "type": "string"
                   }
                 }
               },
               "additionalProperties": false
             }
           ]
+        }
+      }
+    },
+    "FilterType<SeriesMetadataLocalized>": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$and": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CSeriesMetadataLocalized%3E"
+          }
         },
-        "createdAt": {
+        "$not": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CSeriesMetadataLocalized%3E"
+          }
+        },
+        "$nor": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CSeriesMetadataLocalized%3E"
+          }
+        },
+        "$or": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CSeriesMetadataLocalized%3E"
+          }
+        },
+        "id": {
           "anyOf": [
             {
               "type": "object",
@@ -5202,7 +5202,7 @@
             }
           ]
         },
-        "updatedAt": {
+        "seriesImdbId": {
           "anyOf": [
             {
               "type": "object",
@@ -5253,144 +5253,3530 @@
               "additionalProperties": false
             }
           ]
-        }
-      }
-    },
-    "FindOptions<Movie,(\"imdbId\"|\"title\"|\"year\"|\"duration\"|\"genre\"|\"thumbnailImageUrl\"|\"plot\"|\"type\"|\"seriesId\"|\"season\"|\"episode\"|\"createdAt\"|\"updatedAt\")[]>": {
-      "type": "object",
-      "properties": {
-        "top": {
-          "type": "number",
-          "description": "Limits the hits"
-        },
-        "skip": {
-          "type": "number",
-          "description": "Skips the first N hit"
         },
-        "order": {
-          "type": "object",
-          "properties": {
-            "imdbId": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "title": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "year": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "duration": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "genre": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "thumbnailImageUrl": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "plot": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "type": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
+        "language": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
             },
-            "seriesId": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
             },
-            "season": {
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "title": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "plot": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "posterUrl": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "source": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
+                },
+                "$endsWith": {
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
+                },
+                "$like": {
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
+                },
+                "$regex": {
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
+                },
+                "$ne": {
+                  "type": "string",
+                  "enum": ["omdb", "tmdb"]
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["omdb", "tmdb"]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["omdb", "tmdb"]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "sourceId": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        }
+      }
+    },
+    "FilterType<TmdbMovieMetadata>": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$and": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CTmdbMovieMetadata%3E"
+          }
+        },
+        "$not": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CTmdbMovieMetadata%3E"
+          }
+        },
+        "$nor": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CTmdbMovieMetadata%3E"
+          }
+        },
+        "$or": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CTmdbMovieMetadata%3E"
+          }
+        },
+        "id": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$gt": {
+                  "type": "number"
+                },
+                "$gte": {
+                  "type": "number"
+                },
+                "$lt": {
+                  "type": "number"
+                },
+                "$lte": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "number"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "number"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "imdbId": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "title": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "originalTitle": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "overview": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "releaseDate": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "runtime": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "posterPath": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "backdropPath": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "genres": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "id": {
+                        "type": "number"
+                      },
+                      "name": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["id", "name"],
+                    "additionalProperties": false
+                  }
+                },
+                "$ne": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "id": {
+                        "type": "number"
+                      },
+                      "name": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["id", "name"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "id": {
+                          "type": "number"
+                        },
+                        "name": {
+                          "type": "string"
+                        }
+                      },
+                      "required": ["id", "name"],
+                      "additionalProperties": false
+                    }
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "id": {
+                          "type": "number"
+                        },
+                        "name": {
+                          "type": "string"
+                        }
+                      },
+                      "required": ["id", "name"],
+                      "additionalProperties": false
+                    }
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "voteAverage": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "voteCount": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "popularity": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "originalLanguage": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "spokenLanguages": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "iso_639_1": {
+                        "type": "string"
+                      },
+                      "name": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["iso_639_1", "name"],
+                    "additionalProperties": false
+                  }
+                },
+                "$ne": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "iso_639_1": {
+                        "type": "string"
+                      },
+                      "name": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["iso_639_1", "name"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "iso_639_1": {
+                              "type": "string"
+                            },
+                            "name": {
+                              "type": "string"
+                            }
+                          },
+                          "required": ["iso_639_1", "name"],
+                          "additionalProperties": false
+                        }
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "iso_639_1": {
+                              "type": "string"
+                            },
+                            "name": {
+                              "type": "string"
+                            }
+                          },
+                          "required": ["iso_639_1", "name"],
+                          "additionalProperties": false
+                        }
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "productionCountries": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "iso_3166_1": {
+                        "type": "string"
+                      },
+                      "name": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["iso_3166_1", "name"],
+                    "additionalProperties": false
+                  }
+                },
+                "$ne": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "iso_3166_1": {
+                        "type": "string"
+                      },
+                      "name": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["iso_3166_1", "name"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "iso_3166_1": {
+                              "type": "string"
+                            },
+                            "name": {
+                              "type": "string"
+                            }
+                          },
+                          "required": ["iso_3166_1", "name"],
+                          "additionalProperties": false
+                        }
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "iso_3166_1": {
+                              "type": "string"
+                            },
+                            "name": {
+                              "type": "string"
+                            }
+                          },
+                          "required": ["iso_3166_1", "name"],
+                          "additionalProperties": false
+                        }
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "status": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "tagline": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "budget": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "revenue": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "language": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        }
+      }
+    },
+    "FilterType<TmdbSeriesMetadata>": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$and": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CTmdbSeriesMetadata%3E"
+          }
+        },
+        "$not": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CTmdbSeriesMetadata%3E"
+          }
+        },
+        "$nor": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CTmdbSeriesMetadata%3E"
+          }
+        },
+        "$or": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CTmdbSeriesMetadata%3E"
+          }
+        },
+        "id": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$gt": {
+                  "type": "number"
+                },
+                "$gte": {
+                  "type": "number"
+                },
+                "$lt": {
+                  "type": "number"
+                },
+                "$lte": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "number"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "number"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "imdbId": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "name": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "originalName": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "overview": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "firstAirDate": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "posterPath": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "backdropPath": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "genres": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "id": {
+                        "type": "number"
+                      },
+                      "name": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["id", "name"],
+                    "additionalProperties": false
+                  }
+                },
+                "$ne": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "id": {
+                        "type": "number"
+                      },
+                      "name": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["id", "name"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "id": {
+                          "type": "number"
+                        },
+                        "name": {
+                          "type": "string"
+                        }
+                      },
+                      "required": ["id", "name"],
+                      "additionalProperties": false
+                    }
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "id": {
+                          "type": "number"
+                        },
+                        "name": {
+                          "type": "string"
+                        }
+                      },
+                      "required": ["id", "name"],
+                      "additionalProperties": false
+                    }
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "voteAverage": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "voteCount": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "numberOfSeasons": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "numberOfEpisodes": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "status": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "originalLanguage": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "languages": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$ne": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      {
+                        "not": {}
+                      }
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "language": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        }
+      }
+    },
+    "FilterType<WatchHistoryEntry>": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$and": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CWatchHistoryEntry%3E"
+          }
+        },
+        "$not": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CWatchHistoryEntry%3E"
+          }
+        },
+        "$nor": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CWatchHistoryEntry%3E"
+          }
+        },
+        "$or": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FilterType%3CWatchHistoryEntry%3E"
+          }
+        },
+        "id": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "userName": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "driveLetter": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "path": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "watchedSeconds": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$gt": {
+                  "type": "number"
+                },
+                "$gte": {
+                  "type": "number"
+                },
+                "$lt": {
+                  "type": "number"
+                },
+                "$lte": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "number"
+                },
+                "$ne": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "number"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "number"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "completed": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "boolean"
+                },
+                "$ne": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "boolean"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "boolean"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "$startsWith": {
+                  "type": "string"
+                },
+                "$endsWith": {
+                  "type": "string"
+                },
+                "$like": {
+                  "type": "string"
+                },
+                "$regex": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$eq": {
+                  "type": "string"
+                },
+                "$ne": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$in": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "$nin": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        }
+      }
+    },
+    "FindOptions<Movie,(\"imdbId\"|\"year\"|\"duration\"|\"type\"|\"seriesId\"|\"season\"|\"episode\"|\"createdAt\"|\"updatedAt\")[]>": {
+      "type": "object",
+      "properties": {
+        "top": {
+          "type": "number",
+          "description": "Limits the hits"
+        },
+        "skip": {
+          "type": "number",
+          "description": "Skips the first N hit"
+        },
+        "order": {
+          "type": "object",
+          "properties": {
+            "imdbId": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "year": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "duration": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "type": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "seriesId": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "season": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "episode": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "createdAt": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "updatedAt": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            }
+          },
+          "additionalProperties": false,
+          "description": "Sets up an order by a field and a direction"
+        },
+        "select": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["imdbId", "year", "duration", "type", "seriesId", "season", "episode", "createdAt", "updatedAt"]
+          },
+          "description": "The result set will be limited to these fields"
+        },
+        "filter": {
+          "$ref": "#/definitions/FilterType%3CMovie%3E",
+          "description": "The fields should match this filter"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Type for default filtering model"
+    },
+    "FindOptions<MovieFile,(\"id\"|\"imdbId\"|\"driveLetter\"|\"path\"|\"ffprobe\"|\"relatedFiles\")[]>": {
+      "type": "object",
+      "properties": {
+        "top": {
+          "type": "number",
+          "description": "Limits the hits"
+        },
+        "skip": {
+          "type": "number",
+          "description": "Skips the first N hit"
+        },
+        "order": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "imdbId": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "driveLetter": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "path": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "ffprobe": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "relatedFiles": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            }
+          },
+          "additionalProperties": false,
+          "description": "Sets up an order by a field and a direction"
+        },
+        "select": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["id", "imdbId", "driveLetter", "path", "ffprobe", "relatedFiles"]
+          },
+          "description": "The result set will be limited to these fields"
+        },
+        "filter": {
+          "$ref": "#/definitions/FilterType%3CMovieFile%3E",
+          "description": "The fields should match this filter"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Type for default filtering model"
+    },
+    "FindOptions<MovieMetadataLocalized,(\"id\"|\"movieImdbId\"|\"language\"|\"title\"|\"plot\"|\"posterUrl\"|\"genre\"|\"source\"|\"sourceId\"|\"createdAt\"|\"updatedAt\")[]>": {
+      "type": "object",
+      "properties": {
+        "top": {
+          "type": "number",
+          "description": "Limits the hits"
+        },
+        "skip": {
+          "type": "number",
+          "description": "Skips the first N hit"
+        },
+        "order": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "movieImdbId": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "language": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "title": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "plot": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "posterUrl": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "genre": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "source": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "sourceId": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "createdAt": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "updatedAt": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            }
+          },
+          "additionalProperties": false,
+          "description": "Sets up an order by a field and a direction"
+        },
+        "select": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "id",
+              "movieImdbId",
+              "language",
+              "title",
+              "plot",
+              "posterUrl",
+              "genre",
+              "source",
+              "sourceId",
+              "createdAt",
+              "updatedAt"
+            ]
+          },
+          "description": "The result set will be limited to these fields"
+        },
+        "filter": {
+          "$ref": "#/definitions/FilterType%3CMovieMetadataLocalized%3E",
+          "description": "The fields should match this filter"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Type for default filtering model"
+    },
+    "FindOptions<OmdbMovieMetadata,(\"Title\"|\"Year\"|\"Rated\"|\"Released\"|\"Runtime\"|\"Genre\"|\"Director\"|\"Writer\"|\"Actors\"|\"Plot\"|\"Language\"|\"Country\"|\"Awards\"|\"Poster\"|\"Ratings\"|\"Metascore\"|\"imdbRating\"|\"imdbVotes\"|\"imdbID\"|\"Type\"|\"DVD\"|\"BoxOffice\"|\"Production\"|\"Website\"|\"Response\"|\"seriesID\"|\"Season\"|\"Episode\"|\"createdAt\"|\"updatedAt\")[]>": {
+      "type": "object",
+      "properties": {
+        "top": {
+          "type": "number",
+          "description": "Limits the hits"
+        },
+        "skip": {
+          "type": "number",
+          "description": "Skips the first N hit"
+        },
+        "order": {
+          "type": "object",
+          "properties": {
+            "Title": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Year": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Rated": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Released": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Runtime": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Genre": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Director": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Writer": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Actors": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Plot": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Language": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Country": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Awards": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Poster": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Ratings": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Metascore": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "imdbRating": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "episode": {
+            "imdbVotes": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "createdAt": {
+            "imdbID": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "updatedAt": {
+            "Type": {
               "type": "string",
               "enum": ["ASC", "DESC"]
-            }
-          },
-          "additionalProperties": false,
-          "description": "Sets up an order by a field and a direction"
-        },
-        "select": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "enum": [
-              "imdbId",
-              "title",
-              "year",
-              "duration",
-              "genre",
-              "thumbnailImageUrl",
-              "plot",
-              "type",
-              "seriesId",
-              "season",
-              "episode",
-              "createdAt",
-              "updatedAt"
-            ]
-          },
-          "description": "The result set will be limited to these fields"
-        },
-        "filter": {
-          "$ref": "#/definitions/FilterType%3CMovie%3E",
-          "description": "The fields should match this filter"
-        }
-      },
-      "additionalProperties": false,
-      "description": "Type for default filtering model"
-    },
-    "FindOptions<MovieFile,(\"id\"|\"imdbId\"|\"driveLetter\"|\"path\"|\"ffprobe\"|\"relatedFiles\")[]>": {
-      "type": "object",
-      "properties": {
-        "top": {
-          "type": "number",
-          "description": "Limits the hits"
-        },
-        "skip": {
-          "type": "number",
-          "description": "Skips the first N hit"
-        },
-        "order": {
-          "type": "object",
-          "properties": {
-            "id": {
+            },
+            "DVD": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "imdbId": {
+            "BoxOffice": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "driveLetter": {
+            "Production": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "path": {
+            "Website": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "ffprobe": {
+            "Response": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "relatedFiles": {
+            "seriesID": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Season": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "Episode": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "createdAt": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "updatedAt": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             }
@@ -5402,19 +8788,50 @@
           "type": "array",
           "items": {
             "type": "string",
-            "enum": ["id", "imdbId", "driveLetter", "path", "ffprobe", "relatedFiles"]
+            "enum": [
+              "Title",
+              "Year",
+              "Rated",
+              "Released",
+              "Runtime",
+              "Genre",
+              "Director",
+              "Writer",
+              "Actors",
+              "Plot",
+              "Language",
+              "Country",
+              "Awards",
+              "Poster",
+              "Ratings",
+              "Metascore",
+              "imdbRating",
+              "imdbVotes",
+              "imdbID",
+              "Type",
+              "DVD",
+              "BoxOffice",
+              "Production",
+              "Website",
+              "Response",
+              "seriesID",
+              "Season",
+              "Episode",
+              "createdAt",
+              "updatedAt"
+            ]
           },
           "description": "The result set will be limited to these fields"
         },
         "filter": {
-          "$ref": "#/definitions/FilterType%3CMovieFile%3E",
+          "$ref": "#/definitions/FilterType%3COmdbMovieMetadata%3E",
           "description": "The fields should match this filter"
         }
       },
       "additionalProperties": false,
       "description": "Type for default filtering model"
     },
-    "FindOptions<OmdbMovieMetadata,(\"Title\"|\"Year\"|\"Rated\"|\"Released\"|\"Runtime\"|\"Genre\"|\"Director\"|\"Writer\"|\"Actors\"|\"Plot\"|\"Language\"|\"Country\"|\"Awards\"|\"Poster\"|\"Ratings\"|\"Metascore\"|\"imdbRating\"|\"imdbVotes\"|\"imdbID\"|\"Type\"|\"DVD\"|\"BoxOffice\"|\"Production\"|\"Website\"|\"Response\"|\"seriesID\"|\"Season\"|\"Episode\"|\"createdAt\"|\"updatedAt\")[]>": {
+    "FindOptions<OmdbSeriesMetadata,(\"Title\"|\"Year\"|\"Rated\"|\"Released\"|\"Runtime\"|\"Genre\"|\"Director\"|\"Writer\"|\"Actors\"|\"Plot\"|\"Language\"|\"Country\"|\"Awards\"|\"Poster\"|\"Ratings\"|\"Metascore\"|\"imdbRating\"|\"imdbVotes\"|\"imdbID\"|\"Type\"|\"totalSeasons\"|\"Response\"|\"createdAt\"|\"updatedAt\")[]>": {
       "type": "object",
       "properties": {
         "top": {
@@ -5508,19 +8925,7 @@
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "DVD": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "BoxOffice": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "Production": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "Website": {
+            "totalSeasons": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
@@ -5528,18 +8933,6 @@
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "seriesID": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "Season": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "Episode": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
             "createdAt": {
               "type": "string",
               "enum": ["ASC", "DESC"]
@@ -5577,14 +8970,8 @@
               "imdbVotes",
               "imdbID",
               "Type",
-              "DVD",
-              "BoxOffice",
-              "Production",
-              "Website",
+              "totalSeasons",
               "Response",
-              "seriesID",
-              "Season",
-              "Episode",
               "createdAt",
               "updatedAt"
             ]
@@ -5592,14 +8979,153 @@
           "description": "The result set will be limited to these fields"
         },
         "filter": {
-          "$ref": "#/definitions/FilterType%3COmdbMovieMetadata%3E",
+          "$ref": "#/definitions/FilterType%3COmdbSeriesMetadata%3E",
+          "description": "The fields should match this filter"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Type for default filtering model"
+    },
+    "FindOptions<Series,(\"imdbId\"|\"year\"|\"numberOfSeasons\"|\"createdAt\"|\"updatedAt\")[]>": {
+      "type": "object",
+      "properties": {
+        "top": {
+          "type": "number",
+          "description": "Limits the hits"
+        },
+        "skip": {
+          "type": "number",
+          "description": "Skips the first N hit"
+        },
+        "order": {
+          "type": "object",
+          "properties": {
+            "imdbId": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "year": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "numberOfSeasons": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "createdAt": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "updatedAt": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            }
+          },
+          "additionalProperties": false,
+          "description": "Sets up an order by a field and a direction"
+        },
+        "select": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["imdbId", "year", "numberOfSeasons", "createdAt", "updatedAt"]
+          },
+          "description": "The result set will be limited to these fields"
+        },
+        "filter": {
+          "$ref": "#/definitions/FilterType%3CSeries%3E",
+          "description": "The fields should match this filter"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Type for default filtering model"
+    },
+    "FindOptions<SeriesMetadataLocalized,(\"id\"|\"seriesImdbId\"|\"language\"|\"title\"|\"plot\"|\"posterUrl\"|\"source\"|\"sourceId\"|\"createdAt\"|\"updatedAt\")[]>": {
+      "type": "object",
+      "properties": {
+        "top": {
+          "type": "number",
+          "description": "Limits the hits"
+        },
+        "skip": {
+          "type": "number",
+          "description": "Skips the first N hit"
+        },
+        "order": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "seriesImdbId": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "language": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "title": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "plot": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "posterUrl": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "source": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "sourceId": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "createdAt": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "updatedAt": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            }
+          },
+          "additionalProperties": false,
+          "description": "Sets up an order by a field and a direction"
+        },
+        "select": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "id",
+              "seriesImdbId",
+              "language",
+              "title",
+              "plot",
+              "posterUrl",
+              "source",
+              "sourceId",
+              "createdAt",
+              "updatedAt"
+            ]
+          },
+          "description": "The result set will be limited to these fields"
+        },
+        "filter": {
+          "$ref": "#/definitions/FilterType%3CSeriesMetadataLocalized%3E",
           "description": "The fields should match this filter"
         }
       },
       "additionalProperties": false,
       "description": "Type for default filtering model"
     },
-    "FindOptions<OmdbSeriesMetadata,(\"Title\"|\"Year\"|\"Rated\"|\"Released\"|\"Runtime\"|\"Genre\"|\"Director\"|\"Writer\"|\"Actors\"|\"Plot\"|\"Language\"|\"Country\"|\"Awards\"|\"Poster\"|\"Ratings\"|\"Metascore\"|\"imdbRating\"|\"imdbVotes\"|\"imdbID\"|\"Type\"|\"totalSeasons\"|\"Response\"|\"createdAt\"|\"updatedAt\")[]>": {
+    "FindOptions<TmdbMovieMetadata,(\"id\"|\"imdbId\"|\"title\"|\"originalTitle\"|\"overview\"|\"releaseDate\"|\"runtime\"|\"posterPath\"|\"backdropPath\"|\"genres\"|\"voteAverage\"|\"voteCount\"|\"popularity\"|\"originalLanguage\"|\"spokenLanguages\"|\"productionCountries\"|\"status\"|\"tagline\"|\"budget\"|\"revenue\"|\"language\"|\"createdAt\"|\"updatedAt\")[]>": {
       "type": "object",
       "properties": {
         "top": {
@@ -5613,91 +9139,87 @@
         "order": {
           "type": "object",
           "properties": {
-            "Title": {
-              "type": "string",
-              "enum": ["ASC", "DESC"]
-            },
-            "Year": {
+            "id": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Rated": {
+            "imdbId": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Released": {
+            "title": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Runtime": {
+            "originalTitle": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Genre": {
+            "overview": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Director": {
+            "releaseDate": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Writer": {
+            "runtime": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Actors": {
+            "posterPath": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Plot": {
+            "backdropPath": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Language": {
+            "genres": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Country": {
+            "voteAverage": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Awards": {
+            "voteCount": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Poster": {
+            "popularity": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Ratings": {
+            "originalLanguage": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Metascore": {
+            "spokenLanguages": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "imdbRating": {
+            "productionCountries": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "imdbVotes": {
+            "status": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "imdbID": {
+            "tagline": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Type": {
+            "budget": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "totalSeasons": {
+            "revenue": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "Response": {
+            "language": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
@@ -5718,28 +9240,27 @@
           "items": {
             "type": "string",
             "enum": [
-              "Title",
-              "Year",
-              "Rated",
-              "Released",
-              "Runtime",
-              "Genre",
-              "Director",
-              "Writer",
-              "Actors",
-              "Plot",
-              "Language",
-              "Country",
-              "Awards",
-              "Poster",
-              "Ratings",
-              "Metascore",
-              "imdbRating",
-              "imdbVotes",
-              "imdbID",
-              "Type",
-              "totalSeasons",
-              "Response",
+              "id",
+              "imdbId",
+              "title",
+              "originalTitle",
+              "overview",
+              "releaseDate",
+              "runtime",
+              "posterPath",
+              "backdropPath",
+              "genres",
+              "voteAverage",
+              "voteCount",
+              "popularity",
+              "originalLanguage",
+              "spokenLanguages",
+              "productionCountries",
+              "status",
+              "tagline",
+              "budget",
+              "revenue",
+              "language",
               "createdAt",
               "updatedAt"
             ]
@@ -5747,14 +9268,14 @@
           "description": "The result set will be limited to these fields"
         },
         "filter": {
-          "$ref": "#/definitions/FilterType%3COmdbSeriesMetadata%3E",
+          "$ref": "#/definitions/FilterType%3CTmdbMovieMetadata%3E",
           "description": "The fields should match this filter"
         }
       },
       "additionalProperties": false,
       "description": "Type for default filtering model"
     },
-    "FindOptions<Series,(\"imdbId\"|\"title\"|\"year\"|\"thumbnailImageUrl\"|\"plot\"|\"createdAt\"|\"updatedAt\")[]>": {
+    "FindOptions<TmdbSeriesMetadata,(\"id\"|\"imdbId\"|\"name\"|\"originalName\"|\"overview\"|\"firstAirDate\"|\"posterPath\"|\"backdropPath\"|\"genres\"|\"voteAverage\"|\"voteCount\"|\"numberOfSeasons\"|\"numberOfEpisodes\"|\"status\"|\"originalLanguage\"|\"languages\"|\"language\"|\"createdAt\"|\"updatedAt\")[]>": {
       "type": "object",
       "properties": {
         "top": {
@@ -5768,23 +9289,71 @@
         "order": {
           "type": "object",
           "properties": {
+            "id": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
             "imdbId": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "title": {
+            "name": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "year": {
+            "originalName": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "thumbnailImageUrl": {
+            "overview": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
-            "plot": {
+            "firstAirDate": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "posterPath": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "backdropPath": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "genres": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "voteAverage": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "voteCount": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "numberOfSeasons": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "numberOfEpisodes": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "status": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "originalLanguage": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "languages": {
+              "type": "string",
+              "enum": ["ASC", "DESC"]
+            },
+            "language": {
               "type": "string",
               "enum": ["ASC", "DESC"]
             },
@@ -5804,12 +9373,32 @@
           "type": "array",
           "items": {
             "type": "string",
-            "enum": ["imdbId", "title", "year", "thumbnailImageUrl", "plot", "createdAt", "updatedAt"]
+            "enum": [
+              "id",
+              "imdbId",
+              "name",
+              "originalName",
+              "overview",
+              "firstAirDate",
+              "posterPath",
+              "backdropPath",
+              "genres",
+              "voteAverage",
+              "voteCount",
+              "numberOfSeasons",
+              "numberOfEpisodes",
+              "status",
+              "originalLanguage",
+              "languages",
+              "language",
+              "createdAt",
+              "updatedAt"
+            ]
           },
           "description": "The result set will be limited to these fields"
         },
         "filter": {
-          "$ref": "#/definitions/FilterType%3CSeries%3E",
+          "$ref": "#/definitions/FilterType%3CTmdbSeriesMetadata%3E",
           "description": "The fields should match this filter"
         }
       },
@@ -5889,7 +9478,7 @@
           "type": "object",
           "properties": {
             "findOptions": {
-              "$ref": "#/definitions/FindOptions%3CMovie%2C(%22imdbId%22%7C%22title%22%7C%22year%22%7C%22duration%22%7C%22genre%22%7C%22thumbnailImageUrl%22%7C%22plot%22%7C%22type%22%7C%22seriesId%22%7C%22season%22%7C%22episode%22%7C%22createdAt%22%7C%22updatedAt%22)%5B%5D%3E"
+              "$ref": "#/definitions/FindOptions%3CMovie%2C(%22imdbId%22%7C%22year%22%7C%22duration%22%7C%22type%22%7C%22seriesId%22%7C%22season%22%7C%22episode%22%7C%22createdAt%22%7C%22updatedAt%22)%5B%5D%3E"
             }
           },
           "additionalProperties": false
@@ -5922,6 +9511,26 @@
       "additionalProperties": false,
       "description": "Rest endpoint model for getting / querying collections"
     },
+    "GetCollectionEndpoint<MovieMetadataLocalized>": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "object",
+          "properties": {
+            "findOptions": {
+              "$ref": "#/definitions/FindOptions%3CMovieMetadataLocalized%2C(%22id%22%7C%22movieImdbId%22%7C%22language%22%7C%22title%22%7C%22plot%22%7C%22posterUrl%22%7C%22genre%22%7C%22source%22%7C%22sourceId%22%7C%22createdAt%22%7C%22updatedAt%22)%5B%5D%3E"
+            }
+          },
+          "additionalProperties": false
+        },
+        "result": {
+          "$ref": "#/definitions/GetCollectionResult%3CMovieMetadataLocalized%3E"
+        }
+      },
+      "required": ["query", "result"],
+      "additionalProperties": false,
+      "description": "Rest endpoint model for getting / querying collections"
+    },
     "GetCollectionEndpoint<OmdbMovieMetadata>": {
       "type": "object",
       "properties": {
@@ -5969,7 +9578,7 @@
           "type": "object",
           "properties": {
             "findOptions": {
-              "$ref": "#/definitions/FindOptions%3CSeries%2C(%22imdbId%22%7C%22title%22%7C%22year%22%7C%22thumbnailImageUrl%22%7C%22plot%22%7C%22createdAt%22%7C%22updatedAt%22)%5B%5D%3E"
+              "$ref": "#/definitions/FindOptions%3CSeries%2C(%22imdbId%22%7C%22year%22%7C%22numberOfSeasons%22%7C%22createdAt%22%7C%22updatedAt%22)%5B%5D%3E"
             }
           },
           "additionalProperties": false
@@ -5982,6 +9591,66 @@
       "additionalProperties": false,
       "description": "Rest endpoint model for getting / querying collections"
     },
+    "GetCollectionEndpoint<SeriesMetadataLocalized>": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "object",
+          "properties": {
+            "findOptions": {
+              "$ref": "#/definitions/FindOptions%3CSeriesMetadataLocalized%2C(%22id%22%7C%22seriesImdbId%22%7C%22language%22%7C%22title%22%7C%22plot%22%7C%22posterUrl%22%7C%22source%22%7C%22sourceId%22%7C%22createdAt%22%7C%22updatedAt%22)%5B%5D%3E"
+            }
+          },
+          "additionalProperties": false
+        },
+        "result": {
+          "$ref": "#/definitions/GetCollectionResult%3CSeriesMetadataLocalized%3E"
+        }
+      },
+      "required": ["query", "result"],
+      "additionalProperties": false,
+      "description": "Rest endpoint model for getting / querying collections"
+    },
+    "GetCollectionEndpoint<TmdbMovieMetadata>": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "object",
+          "properties": {
+            "findOptions": {
+              "$ref": "#/definitions/FindOptions%3CTmdbMovieMetadata%2C(%22id%22%7C%22imdbId%22%7C%22title%22%7C%22originalTitle%22%7C%22overview%22%7C%22releaseDate%22%7C%22runtime%22%7C%22posterPath%22%7C%22backdropPath%22%7C%22genres%22%7C%22voteAverage%22%7C%22voteCount%22%7C%22popularity%22%7C%22originalLanguage%22%7C%22spokenLanguages%22%7C%22productionCountries%22%7C%22status%22%7C%22tagline%22%7C%22budget%22%7C%22revenue%22%7C%22language%22%7C%22createdAt%22%7C%22updatedAt%22)%5B%5D%3E"
+            }
+          },
+          "additionalProperties": false
+        },
+        "result": {
+          "$ref": "#/definitions/GetCollectionResult%3CTmdbMovieMetadata%3E"
+        }
+      },
+      "required": ["query", "result"],
+      "additionalProperties": false,
+      "description": "Rest endpoint model for getting / querying collections"
+    },
+    "GetCollectionEndpoint<TmdbSeriesMetadata>": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "object",
+          "properties": {
+            "findOptions": {
+              "$ref": "#/definitions/FindOptions%3CTmdbSeriesMetadata%2C(%22id%22%7C%22imdbId%22%7C%22name%22%7C%22originalName%22%7C%22overview%22%7C%22firstAirDate%22%7C%22posterPath%22%7C%22backdropPath%22%7C%22genres%22%7C%22voteAverage%22%7C%22voteCount%22%7C%22numberOfSeasons%22%7C%22numberOfEpisodes%22%7C%22status%22%7C%22originalLanguage%22%7C%22languages%22%7C%22language%22%7C%22createdAt%22%7C%22updatedAt%22)%5B%5D%3E"
+            }
+          },
+          "additionalProperties": false
+        },
+        "result": {
+          "$ref": "#/definitions/GetCollectionResult%3CTmdbSeriesMetadata%3E"
+        }
+      },
+      "required": ["query", "result"],
+      "additionalProperties": false,
+      "description": "Rest endpoint model for getting / querying collections"
+    },
     "GetCollectionEndpoint<WatchHistoryEntry>": {
       "type": "object",
       "properties": {
@@ -5994,15 +9663,91 @@
           },
           "additionalProperties": false
         },
-        "result": {
-          "$ref": "#/definitions/GetCollectionResult%3CWatchHistoryEntry%3E"
+        "result": {
+          "$ref": "#/definitions/GetCollectionResult%3CWatchHistoryEntry%3E"
+        }
+      },
+      "required": ["query", "result"],
+      "additionalProperties": false,
+      "description": "Rest endpoint model for getting / querying collections"
+    },
+    "GetCollectionResult<Movie>": {
+      "type": "object",
+      "properties": {
+        "count": {
+          "type": "number",
+          "description": "The Total count of entities"
+        },
+        "entries": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Movie"
+          },
+          "description": "List of the selected entities"
+        }
+      },
+      "required": ["count", "entries"],
+      "additionalProperties": false,
+      "description": "Response Model for GetCollection"
+    },
+    "GetCollectionResult<MovieFile>": {
+      "type": "object",
+      "properties": {
+        "count": {
+          "type": "number",
+          "description": "The Total count of entities"
+        },
+        "entries": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/MovieFile"
+          },
+          "description": "List of the selected entities"
+        }
+      },
+      "required": ["count", "entries"],
+      "additionalProperties": false,
+      "description": "Response Model for GetCollection"
+    },
+    "GetCollectionResult<MovieMetadataLocalized>": {
+      "type": "object",
+      "properties": {
+        "count": {
+          "type": "number",
+          "description": "The Total count of entities"
+        },
+        "entries": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/MovieMetadataLocalized"
+          },
+          "description": "List of the selected entities"
+        }
+      },
+      "required": ["count", "entries"],
+      "additionalProperties": false,
+      "description": "Response Model for GetCollection"
+    },
+    "GetCollectionResult<OmdbMovieMetadata>": {
+      "type": "object",
+      "properties": {
+        "count": {
+          "type": "number",
+          "description": "The Total count of entities"
+        },
+        "entries": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/OmdbMovieMetadata"
+          },
+          "description": "List of the selected entities"
         }
       },
-      "required": ["query", "result"],
+      "required": ["count", "entries"],
       "additionalProperties": false,
-      "description": "Rest endpoint model for getting / querying collections"
+      "description": "Response Model for GetCollection"
     },
-    "GetCollectionResult<Movie>": {
+    "GetCollectionResult<OmdbSeriesMetadata>": {
       "type": "object",
       "properties": {
         "count": {
@@ -6012,7 +9757,7 @@
         "entries": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/Movie"
+            "$ref": "#/definitions/OmdbSeriesMetadata"
           },
           "description": "List of the selected entities"
         }
@@ -6021,7 +9766,7 @@
       "additionalProperties": false,
       "description": "Response Model for GetCollection"
     },
-    "GetCollectionResult<MovieFile>": {
+    "GetCollectionResult<Series>": {
       "type": "object",
       "properties": {
         "count": {
@@ -6031,7 +9776,7 @@
         "entries": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/MovieFile"
+            "$ref": "#/definitions/Series"
           },
           "description": "List of the selected entities"
         }
@@ -6040,7 +9785,7 @@
       "additionalProperties": false,
       "description": "Response Model for GetCollection"
     },
-    "GetCollectionResult<OmdbMovieMetadata>": {
+    "GetCollectionResult<SeriesMetadataLocalized>": {
       "type": "object",
       "properties": {
         "count": {
@@ -6050,7 +9795,7 @@
         "entries": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/OmdbMovieMetadata"
+            "$ref": "#/definitions/SeriesMetadataLocalized"
           },
           "description": "List of the selected entities"
         }
@@ -6059,7 +9804,7 @@
       "additionalProperties": false,
       "description": "Response Model for GetCollection"
     },
-    "GetCollectionResult<OmdbSeriesMetadata>": {
+    "GetCollectionResult<TmdbMovieMetadata>": {
       "type": "object",
       "properties": {
         "count": {
@@ -6069,7 +9814,7 @@
         "entries": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/OmdbSeriesMetadata"
+            "$ref": "#/definitions/TmdbMovieMetadata"
           },
           "description": "List of the selected entities"
         }
@@ -6078,7 +9823,7 @@
       "additionalProperties": false,
       "description": "Response Model for GetCollection"
     },
-    "GetCollectionResult<Series>": {
+    "GetCollectionResult<TmdbSeriesMetadata>": {
       "type": "object",
       "properties": {
         "count": {
@@ -6088,7 +9833,7 @@
         "entries": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/Series"
+            "$ref": "#/definitions/TmdbSeriesMetadata"
           },
           "description": "List of the selected entities"
         }
@@ -6128,12 +9873,8 @@
                 "type": "string",
                 "enum": [
                   "imdbId",
-                  "title",
                   "year",
                   "duration",
-                  "genre",
-                  "thumbnailImageUrl",
-                  "plot",
                   "type",
                   "seriesId",
                   "season",
@@ -6202,6 +9943,54 @@
       "additionalProperties": false,
       "description": "Endpoint model for getting a single entity"
     },
+    "GetEntityEndpoint<MovieMetadataLocalized,\"id\">": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "object",
+          "properties": {
+            "select": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "id",
+                  "movieImdbId",
+                  "language",
+                  "title",
+                  "plot",
+                  "posterUrl",
+                  "genre",
+                  "source",
+                  "sourceId",
+                  "createdAt",
+                  "updatedAt"
+                ]
+              },
+              "description": "The list of fields to select"
+            }
+          },
+          "additionalProperties": false
+        },
+        "url": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "The entity's unique identifier"
+            }
+          },
+          "required": ["id"],
+          "additionalProperties": false
+        },
+        "result": {
+          "$ref": "#/definitions/MovieMetadataLocalized"
+        }
+      },
+      "required": ["query", "url", "result"],
+      "additionalProperties": false,
+      "description": "Endpoint model for getting a single entity"
+    },
     "GetEntityEndpoint<OmdbMovieMetadata,\"imdbID\">": {
       "type": "object",
       "properties": {
@@ -6340,7 +10129,7 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": ["imdbId", "title", "year", "thumbnailImageUrl", "plot", "createdAt", "updatedAt"]
+                "enum": ["imdbId", "year", "numberOfSeasons", "createdAt", "updatedAt"]
               },
               "description": "The list of fields to select"
             }
@@ -6366,6 +10155,169 @@
       "additionalProperties": false,
       "description": "Endpoint model for getting a single entity"
     },
+    "GetEntityEndpoint<SeriesMetadataLocalized,\"id\">": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "object",
+          "properties": {
+            "select": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "id",
+                  "seriesImdbId",
+                  "language",
+                  "title",
+                  "plot",
+                  "posterUrl",
+                  "source",
+                  "sourceId",
+                  "createdAt",
+                  "updatedAt"
+                ]
+              },
+              "description": "The list of fields to select"
+            }
+          },
+          "additionalProperties": false
+        },
+        "url": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "The entity's unique identifier"
+            }
+          },
+          "required": ["id"],
+          "additionalProperties": false
+        },
+        "result": {
+          "$ref": "#/definitions/SeriesMetadataLocalized"
+        }
+      },
+      "required": ["query", "url", "result"],
+      "additionalProperties": false,
+      "description": "Endpoint model for getting a single entity"
+    },
+    "GetEntityEndpoint<TmdbMovieMetadata,\"id\">": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "object",
+          "properties": {
+            "select": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "id",
+                  "imdbId",
+                  "title",
+                  "originalTitle",
+                  "overview",
+                  "releaseDate",
+                  "runtime",
+                  "posterPath",
+                  "backdropPath",
+                  "genres",
+                  "voteAverage",
+                  "voteCount",
+                  "popularity",
+                  "originalLanguage",
+                  "spokenLanguages",
+                  "productionCountries",
+                  "status",
+                  "tagline",
+                  "budget",
+                  "revenue",
+                  "language",
+                  "createdAt",
+                  "updatedAt"
+                ]
+              },
+              "description": "The list of fields to select"
+            }
+          },
+          "additionalProperties": false
+        },
+        "url": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "number",
+              "description": "The entity's unique identifier"
+            }
+          },
+          "required": ["id"],
+          "additionalProperties": false
+        },
+        "result": {
+          "$ref": "#/definitions/TmdbMovieMetadata"
+        }
+      },
+      "required": ["query", "url", "result"],
+      "additionalProperties": false,
+      "description": "Endpoint model for getting a single entity"
+    },
+    "GetEntityEndpoint<TmdbSeriesMetadata,\"id\">": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "object",
+          "properties": {
+            "select": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "id",
+                  "imdbId",
+                  "name",
+                  "originalName",
+                  "overview",
+                  "firstAirDate",
+                  "posterPath",
+                  "backdropPath",
+                  "genres",
+                  "voteAverage",
+                  "voteCount",
+                  "numberOfSeasons",
+                  "numberOfEpisodes",
+                  "status",
+                  "originalLanguage",
+                  "languages",
+                  "language",
+                  "createdAt",
+                  "updatedAt"
+                ]
+              },
+              "description": "The list of fields to select"
+            }
+          },
+          "additionalProperties": false
+        },
+        "url": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "number",
+              "description": "The entity's unique identifier"
+            }
+          },
+          "required": ["id"],
+          "additionalProperties": false
+        },
+        "result": {
+          "$ref": "#/definitions/TmdbSeriesMetadata"
+        }
+      },
+      "required": ["query", "url", "result"],
+      "additionalProperties": false,
+      "description": "Endpoint model for getting a single entity"
+    },
     "GetEntityEndpoint<WatchHistoryEntry,\"id\">": {
       "type": "object",
       "properties": {
@@ -6684,8 +10636,8 @@
                 "not-movie-file",
                 "rate-limited",
                 "metadata-not-found",
-                "omdb-not-configured",
-                "omdb-error"
+                "provider-not-configured",
+                "provider-error"
               ]
             },
             "error": {}
@@ -6706,8 +10658,8 @@
         "not-movie-file",
         "rate-limited",
         "metadata-not-found",
-        "omdb-not-configured",
-        "omdb-error"
+        "provider-not-configured",
+        "provider-error"
       ]
     },
     "MediaApi": {
@@ -6752,6 +10704,30 @@
             "/omdb-series-metadata/:id": {
               "$ref": "#/definitions/GetEntityEndpoint%3COmdbSeriesMetadata%2C%22imdbID%22%3E"
             },
+            "/tmdb-movie-metadata": {
+              "$ref": "#/definitions/GetCollectionEndpoint%3CTmdbMovieMetadata%3E"
+            },
+            "/tmdb-movie-metadata/:id": {
+              "$ref": "#/definitions/GetEntityEndpoint%3CTmdbMovieMetadata%2C%22id%22%3E"
+            },
+            "/tmdb-series-metadata": {
+              "$ref": "#/definitions/GetCollectionEndpoint%3CTmdbSeriesMetadata%3E"
+            },
+            "/tmdb-series-metadata/:id": {
+              "$ref": "#/definitions/GetEntityEndpoint%3CTmdbSeriesMetadata%2C%22id%22%3E"
+            },
+            "/movie-metadata-localized": {
+              "$ref": "#/definitions/GetCollectionEndpoint%3CMovieMetadataLocalized%3E"
+            },
+            "/movie-metadata-localized/:id": {
+              "$ref": "#/definitions/GetEntityEndpoint%3CMovieMetadataLocalized%2C%22id%22%3E"
+            },
+            "/series-metadata-localized": {
+              "$ref": "#/definitions/GetCollectionEndpoint%3CSeriesMetadataLocalized%3E"
+            },
+            "/series-metadata-localized/:id": {
+              "$ref": "#/definitions/GetEntityEndpoint%3CSeriesMetadataLocalized%2C%22id%22%3E"
+            },
             "/movie-files": {
               "$ref": "#/definitions/GetCollectionEndpoint%3CMovieFile%3E"
             },
@@ -6784,6 +10760,14 @@
             "/omdb-movie-metadata/:id",
             "/omdb-series-metadata",
             "/omdb-series-metadata/:id",
+            "/tmdb-movie-metadata",
+            "/tmdb-movie-metadata/:id",
+            "/tmdb-series-metadata",
+            "/tmdb-series-metadata/:id",
+            "/movie-metadata-localized",
+            "/movie-metadata-localized/:id",
+            "/series-metadata-localized",
+            "/series-metadata-localized/:id",
             "/movie-files",
             "/movie-files/:id",
             "/files/:letter/:path/master.m3u8",
@@ -6851,7 +10835,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -6890,7 +10889,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -6905,7 +10919,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -6920,7 +10949,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -6935,7 +10979,22 @@
               "url": {},
               "query": {},
               "body": {},
-              "headers": {}
+              "headers": {},
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "deprecated": {
+                "type": "boolean"
+              },
+              "summary": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
             },
             "required": ["result"],
             "additionalProperties": false
@@ -6951,27 +11010,12 @@
         "imdbId": {
           "type": "string"
         },
-        "title": {
-          "type": "string"
-        },
-        "year": {
-          "type": "number"
-        },
-        "duration": {
-          "type": "number"
-        },
-        "genre": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
-        "thumbnailImageUrl": {
-          "type": "string"
-        },
-        "plot": {
-          "type": "string"
-        },
+        "year": {
+          "type": "number"
+        },
+        "duration": {
+          "type": "number"
+        },
         "type": {
           "type": "string",
           "enum": ["movie", "episode"]
@@ -6992,7 +11036,7 @@
           "type": "string"
         }
       },
-      "required": ["imdbId", "title", "createdAt", "updatedAt"],
+      "required": ["imdbId", "createdAt", "updatedAt"],
       "additionalProperties": false
     },
     "MovieFile": {
@@ -7034,6 +11078,50 @@
       "required": ["id", "driveLetter", "path", "ffprobe"],
       "additionalProperties": false
     },
+    "MovieMetadataLocalized": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "movieImdbId": {
+          "type": "string"
+        },
+        "language": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "plot": {
+          "type": "string"
+        },
+        "posterUrl": {
+          "type": "string"
+        },
+        "genre": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "source": {
+          "type": "string",
+          "enum": ["omdb", "tmdb"]
+        },
+        "sourceId": {
+          "type": "string"
+        },
+        "createdAt": {
+          "type": "string"
+        },
+        "updatedAt": {
+          "type": "string"
+        }
+      },
+      "required": ["id", "movieImdbId", "language", "title", "source", "createdAt", "updatedAt"],
+      "additionalProperties": false
+    },
     "OmdbMovieMetadata": {
       "type": "object",
       "properties": {
@@ -7288,7 +11376,7 @@
       "additionalProperties": false
     },
     "Omit<Movie,(\"createdAt\"|\"updatedAt\")>": {
-      "$ref": "#/definitions/Pick%3CMovie%2CExclude%3C(%22imdbId%22%7C%22title%22%7C%22year%22%7C%22duration%22%7C%22genre%22%7C%22thumbnailImageUrl%22%7C%22plot%22%7C%22type%22%7C%22seriesId%22%7C%22season%22%7C%22episode%22%7C%22createdAt%22%7C%22updatedAt%22)%2C(%22createdAt%22%7C%22updatedAt%22)%3E%3E"
+      "$ref": "#/definitions/Pick%3CMovie%2CExclude%3C(%22imdbId%22%7C%22year%22%7C%22duration%22%7C%22type%22%7C%22seriesId%22%7C%22season%22%7C%22episode%22%7C%22createdAt%22%7C%22updatedAt%22)%2C(%22createdAt%22%7C%22updatedAt%22)%3E%3E"
     },
     "Omit<WatchHistoryEntry,(\"userName\"|\"createdAt\"|\"updatedAt\"|\"id\")>": {
       "$ref": "#/definitions/Pick%3CWatchHistoryEntry%2CExclude%3C(%22id%22%7C%22userName%22%7C%22driveLetter%22%7C%22path%22%7C%22watchedSeconds%22%7C%22completed%22%7C%22createdAt%22%7C%22updatedAt%22)%2C(%22userName%22%7C%22createdAt%22%7C%22updatedAt%22%7C%22id%22)%3E%3E"
@@ -7337,27 +11425,12 @@
         "imdbId": {
           "type": "string"
         },
-        "title": {
-          "type": "string"
-        },
         "year": {
           "type": "number"
         },
         "duration": {
           "type": "number"
         },
-        "genre": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
-        "thumbnailImageUrl": {
-          "type": "string"
-        },
-        "plot": {
-          "type": "string"
-        },
         "type": {
           "type": "string",
           "enum": ["movie", "episode"]
@@ -7422,33 +11495,18 @@
       "additionalProperties": false,
       "description": "Endpoint model for updating entities"
     },
-    "Pick<Movie,Exclude<(\"imdbId\"|\"title\"|\"year\"|\"duration\"|\"genre\"|\"thumbnailImageUrl\"|\"plot\"|\"type\"|\"seriesId\"|\"season\"|\"episode\"|\"createdAt\"|\"updatedAt\"),(\"createdAt\"|\"updatedAt\")>>": {
+    "Pick<Movie,Exclude<(\"imdbId\"|\"year\"|\"duration\"|\"type\"|\"seriesId\"|\"season\"|\"episode\"|\"createdAt\"|\"updatedAt\"),(\"createdAt\"|\"updatedAt\")>>": {
       "type": "object",
       "properties": {
         "imdbId": {
           "type": "string"
         },
-        "title": {
-          "type": "string"
-        },
         "year": {
           "type": "number"
         },
         "duration": {
           "type": "number"
         },
-        "genre": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
-        "thumbnailImageUrl": {
-          "type": "string"
-        },
-        "plot": {
-          "type": "string"
-        },
         "type": {
           "type": "string",
           "enum": ["movie", "episode"]
@@ -7463,7 +11521,7 @@
           "type": "number"
         }
       },
-      "required": ["imdbId", "title"],
+      "required": ["imdbId"],
       "additionalProperties": false
     },
     "Pick<WatchHistoryEntry,Exclude<(\"id\"|\"userName\"|\"driveLetter\"|\"path\"|\"watchedSeconds\"|\"completed\"|\"createdAt\"|\"updatedAt\"),(\"userName\"|\"createdAt\"|\"updatedAt\"|\"id\")>>": {
@@ -7666,10 +11724,10 @@
         "metadataNotFound": {
           "type": "number"
         },
-        "omdbNotConfigured": {
+        "providerNotConfigured": {
           "type": "number"
         },
-        "omdbError": {
+        "providerError": {
           "type": "number"
         },
         "skipped": {
@@ -7683,8 +11741,8 @@
         "failed",
         "rateLimited",
         "metadataNotFound",
-        "omdbNotConfigured",
-        "omdbError",
+        "providerNotConfigured",
+        "providerError",
         "skipped"
       ],
       "additionalProperties": false
@@ -7695,18 +11753,50 @@
         "imdbId": {
           "type": "string"
         },
-        "title": {
+        "year": {
           "type": "string"
         },
-        "year": {
+        "numberOfSeasons": {
+          "type": "number"
+        },
+        "createdAt": {
+          "type": "string"
+        },
+        "updatedAt": {
+          "type": "string"
+        }
+      },
+      "required": ["imdbId", "year", "createdAt", "updatedAt"],
+      "additionalProperties": false
+    },
+    "SeriesMetadataLocalized": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "seriesImdbId": {
+          "type": "string"
+        },
+        "language": {
           "type": "string"
         },
-        "thumbnailImageUrl": {
+        "title": {
           "type": "string"
         },
         "plot": {
           "type": "string"
         },
+        "posterUrl": {
+          "type": "string"
+        },
+        "source": {
+          "type": "string",
+          "enum": ["omdb", "tmdb"]
+        },
+        "sourceId": {
+          "type": "string"
+        },
         "createdAt": {
           "type": "string"
         },
@@ -7714,7 +11804,7 @@
           "type": "string"
         }
       },
-      "required": ["imdbId", "title", "year", "plot", "createdAt", "updatedAt"],
+      "required": ["id", "seriesImdbId", "language", "title", "source", "createdAt", "updatedAt"],
       "additionalProperties": false
     },
     "SubtitleTrackInfo": {
@@ -7747,6 +11837,221 @@
       "required": ["index", "label", "language", "format", "source", "requiresBurnIn"],
       "additionalProperties": false
     },
+    "TmdbMovieMetadata": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number"
+        },
+        "imdbId": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "originalTitle": {
+          "type": "string"
+        },
+        "overview": {
+          "type": "string"
+        },
+        "releaseDate": {
+          "type": "string"
+        },
+        "runtime": {
+          "type": "number"
+        },
+        "posterPath": {
+          "type": "string"
+        },
+        "backdropPath": {
+          "type": "string"
+        },
+        "genres": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "number"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": ["id", "name"],
+            "additionalProperties": false
+          }
+        },
+        "voteAverage": {
+          "type": "number"
+        },
+        "voteCount": {
+          "type": "number"
+        },
+        "popularity": {
+          "type": "number"
+        },
+        "originalLanguage": {
+          "type": "string"
+        },
+        "spokenLanguages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "iso_639_1": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": ["iso_639_1", "name"],
+            "additionalProperties": false
+          }
+        },
+        "productionCountries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "iso_3166_1": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": ["iso_3166_1", "name"],
+            "additionalProperties": false
+          }
+        },
+        "status": {
+          "type": "string"
+        },
+        "tagline": {
+          "type": "string"
+        },
+        "budget": {
+          "type": "number"
+        },
+        "revenue": {
+          "type": "number"
+        },
+        "language": {
+          "type": "string"
+        },
+        "createdAt": {
+          "type": "string"
+        },
+        "updatedAt": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "title",
+        "originalTitle",
+        "overview",
+        "genres",
+        "originalLanguage",
+        "language",
+        "createdAt",
+        "updatedAt"
+      ],
+      "additionalProperties": false
+    },
+    "TmdbSeriesMetadata": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number"
+        },
+        "imdbId": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "originalName": {
+          "type": "string"
+        },
+        "overview": {
+          "type": "string"
+        },
+        "firstAirDate": {
+          "type": "string"
+        },
+        "posterPath": {
+          "type": "string"
+        },
+        "backdropPath": {
+          "type": "string"
+        },
+        "genres": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "number"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": ["id", "name"],
+            "additionalProperties": false
+          }
+        },
+        "voteAverage": {
+          "type": "number"
+        },
+        "voteCount": {
+          "type": "number"
+        },
+        "numberOfSeasons": {
+          "type": "number"
+        },
+        "numberOfEpisodes": {
+          "type": "number"
+        },
+        "status": {
+          "type": "string"
+        },
+        "originalLanguage": {
+          "type": "string"
+        },
+        "languages": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "language": {
+          "type": "string"
+        },
+        "createdAt": {
+          "type": "string"
+        },
+        "updatedAt": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "originalName",
+        "overview",
+        "genres",
+        "originalLanguage",
+        "language",
+        "createdAt",
+        "updatedAt"
+      ],
+      "additionalProperties": false
+    },
     "updateScanProgress": {
       "$comment": "(progress: ScanProgress, status: LinkMovieStatus | 'skipped' | 'failed') =>undefined",
       "type": "object",
diff --git a/common/schemas/media-entities.json b/common/schemas/media-entities.json
index b61dcae9..7d6cbbcb 100644
--- a/common/schemas/media-entities.json
+++ b/common/schemas/media-entities.json
@@ -299,27 +299,12 @@
         "imdbId": {
           "type": "string"
         },
-        "title": {
-          "type": "string"
-        },
         "year": {
           "type": "number"
         },
         "duration": {
           "type": "number"
         },
-        "genre": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
-        "thumbnailImageUrl": {
-          "type": "string"
-        },
-        "plot": {
-          "type": "string"
-        },
         "type": {
           "type": "string",
           "enum": ["movie", "episode"]
@@ -340,7 +325,7 @@
           "type": "string"
         }
       },
-      "required": ["imdbId", "title", "createdAt", "updatedAt"],
+      "required": ["imdbId", "createdAt", "updatedAt"],
       "additionalProperties": false
     },
     "MovieFile": {
@@ -382,6 +367,50 @@
       "required": ["id", "driveLetter", "path", "ffprobe"],
       "additionalProperties": false
     },
+    "MovieMetadataLocalized": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "movieImdbId": {
+          "type": "string"
+        },
+        "language": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "plot": {
+          "type": "string"
+        },
+        "posterUrl": {
+          "type": "string"
+        },
+        "genre": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "source": {
+          "type": "string",
+          "enum": ["omdb", "tmdb"]
+        },
+        "sourceId": {
+          "type": "string"
+        },
+        "createdAt": {
+          "type": "string"
+        },
+        "updatedAt": {
+          "type": "string"
+        }
+      },
+      "required": ["id", "movieImdbId", "language", "title", "source", "createdAt", "updatedAt"],
+      "additionalProperties": false
+    },
     "OmdbMovieMetadata": {
       "type": "object",
       "properties": {
@@ -641,18 +670,165 @@
         "imdbId": {
           "type": "string"
         },
-        "title": {
+        "year": {
           "type": "string"
         },
-        "year": {
+        "numberOfSeasons": {
+          "type": "number"
+        },
+        "createdAt": {
           "type": "string"
         },
-        "thumbnailImageUrl": {
+        "updatedAt": {
+          "type": "string"
+        }
+      },
+      "required": ["imdbId", "year", "createdAt", "updatedAt"],
+      "additionalProperties": false
+    },
+    "SeriesMetadataLocalized": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "seriesImdbId": {
+          "type": "string"
+        },
+        "language": {
+          "type": "string"
+        },
+        "title": {
           "type": "string"
         },
         "plot": {
           "type": "string"
         },
+        "posterUrl": {
+          "type": "string"
+        },
+        "source": {
+          "type": "string",
+          "enum": ["omdb", "tmdb"]
+        },
+        "sourceId": {
+          "type": "string"
+        },
+        "createdAt": {
+          "type": "string"
+        },
+        "updatedAt": {
+          "type": "string"
+        }
+      },
+      "required": ["id", "seriesImdbId", "language", "title", "source", "createdAt", "updatedAt"],
+      "additionalProperties": false
+    },
+    "TmdbMovieMetadata": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number"
+        },
+        "imdbId": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "originalTitle": {
+          "type": "string"
+        },
+        "overview": {
+          "type": "string"
+        },
+        "releaseDate": {
+          "type": "string"
+        },
+        "runtime": {
+          "type": "number"
+        },
+        "posterPath": {
+          "type": "string"
+        },
+        "backdropPath": {
+          "type": "string"
+        },
+        "genres": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "number"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": ["id", "name"],
+            "additionalProperties": false
+          }
+        },
+        "voteAverage": {
+          "type": "number"
+        },
+        "voteCount": {
+          "type": "number"
+        },
+        "popularity": {
+          "type": "number"
+        },
+        "originalLanguage": {
+          "type": "string"
+        },
+        "spokenLanguages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "iso_639_1": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": ["iso_639_1", "name"],
+            "additionalProperties": false
+          }
+        },
+        "productionCountries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "iso_3166_1": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": ["iso_3166_1", "name"],
+            "additionalProperties": false
+          }
+        },
+        "status": {
+          "type": "string"
+        },
+        "tagline": {
+          "type": "string"
+        },
+        "budget": {
+          "type": "number"
+        },
+        "revenue": {
+          "type": "number"
+        },
+        "language": {
+          "type": "string"
+        },
         "createdAt": {
           "type": "string"
         },
@@ -660,7 +836,107 @@
           "type": "string"
         }
       },
-      "required": ["imdbId", "title", "year", "plot", "createdAt", "updatedAt"],
+      "required": [
+        "id",
+        "title",
+        "originalTitle",
+        "overview",
+        "genres",
+        "originalLanguage",
+        "language",
+        "createdAt",
+        "updatedAt"
+      ],
+      "additionalProperties": false
+    },
+    "TmdbSeriesMetadata": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number"
+        },
+        "imdbId": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "originalName": {
+          "type": "string"
+        },
+        "overview": {
+          "type": "string"
+        },
+        "firstAirDate": {
+          "type": "string"
+        },
+        "posterPath": {
+          "type": "string"
+        },
+        "backdropPath": {
+          "type": "string"
+        },
+        "genres": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "number"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": ["id", "name"],
+            "additionalProperties": false
+          }
+        },
+        "voteAverage": {
+          "type": "number"
+        },
+        "voteCount": {
+          "type": "number"
+        },
+        "numberOfSeasons": {
+          "type": "number"
+        },
+        "numberOfEpisodes": {
+          "type": "number"
+        },
+        "status": {
+          "type": "string"
+        },
+        "originalLanguage": {
+          "type": "string"
+        },
+        "languages": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "language": {
+          "type": "string"
+        },
+        "createdAt": {
+          "type": "string"
+        },
+        "updatedAt": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "originalName",
+        "overview",
+        "genres",
+        "originalLanguage",
+        "language",
+        "createdAt",
+        "updatedAt"
+      ],
       "additionalProperties": false
     },
     "WatchHistoryEntry": {
diff --git a/common/src/apis/install.ts b/common/src/apis/install.ts
index 45e7614e..759928ef 100644
--- a/common/src/apis/install.ts
+++ b/common/src/apis/install.ts
@@ -8,6 +8,10 @@ export type ServiceStatusResponse = {
      * OMDB API Installation Status for metadata fetching
      */
     omdb: boolean
+    /**
+     * TMDB API Installation Status for metadata fetching
+     */
+    tmdb: boolean
     /**
      * Github API Installation Status for external authentication
      */
diff --git a/common/src/apis/media.ts b/common/src/apis/media.ts
index ceae4e3f..e501c734 100644
--- a/common/src/apis/media.ts
+++ b/common/src/apis/media.ts
@@ -9,9 +9,13 @@ import type {
 import type {
   Movie,
   MovieFile,
+  MovieMetadataLocalized,
   OmdbMovieMetadata,
   OmdbSeriesMetadata,
   Series,
+  SeriesMetadataLocalized,
+  TmdbMovieMetadata,
+  TmdbSeriesMetadata,
   WatchHistoryEntry,
 } from '../models/media/index.js'
 import type { PiRatFile } from '../models/pirat-file.js'
@@ -26,8 +30,8 @@ export type LinkMovie = {
       | 'not-movie-file'
       | 'rate-limited'
       | 'metadata-not-found'
-      | 'omdb-not-configured'
-      | 'omdb-error'
+      | 'provider-not-configured'
+      | 'provider-error'
     error?: unknown
   }
 }
@@ -56,8 +60,8 @@ export type ScanProgress = {
   failed: number
   rateLimited: number
   metadataNotFound: number
-  omdbNotConfigured: number
-  omdbError: number
+  providerNotConfigured: number
+  providerError: number
   skipped: number
 }
 
@@ -77,11 +81,11 @@ export const updateScanProgress = (progress: ScanProgress, status: LinkMovieStat
     case 'metadata-not-found':
       progress.metadataNotFound++
       break
-    case 'omdb-not-configured':
-      progress.omdbNotConfigured++
+    case 'provider-not-configured':
+      progress.providerNotConfigured++
       break
-    case 'omdb-error':
-      progress.omdbError++
+    case 'provider-error':
+      progress.providerError++
       break
     case 'failed':
       progress.failed++
@@ -99,8 +103,8 @@ export const createScanProgress = (total: number): ScanProgress => ({
   failed: 0,
   rateLimited: 0,
   metadataNotFound: 0,
-  omdbNotConfigured: 0,
-  omdbError: 0,
+  providerNotConfigured: 0,
+  providerError: 0,
   skipped: 0,
 })
 
@@ -110,8 +114,8 @@ export const getProcessedCount = (progress: ScanProgress): number =>
   progress.failed +
   progress.rateLimited +
   progress.metadataNotFound +
-  progress.omdbNotConfigured +
-  progress.omdbError +
+  progress.providerNotConfigured +
+  progress.providerError +
   progress.skipped
 
 export type ScanForMoviesEndpoint = {
@@ -225,6 +229,14 @@ export interface MediaApi extends RestApi {
     '/omdb-movie-metadata/:id': GetEntityEndpoint<OmdbMovieMetadata, 'imdbID'>
     '/omdb-series-metadata': GetCollectionEndpoint<OmdbSeriesMetadata>
     '/omdb-series-metadata/:id': GetEntityEndpoint<OmdbSeriesMetadata, 'imdbID'>
+    '/tmdb-movie-metadata': GetCollectionEndpoint<TmdbMovieMetadata>
+    '/tmdb-movie-metadata/:id': GetEntityEndpoint<TmdbMovieMetadata, 'id'>
+    '/tmdb-series-metadata': GetCollectionEndpoint<TmdbSeriesMetadata>
+    '/tmdb-series-metadata/:id': GetEntityEndpoint<TmdbSeriesMetadata, 'id'>
+    '/movie-metadata-localized': GetCollectionEndpoint<MovieMetadataLocalized>
+    '/movie-metadata-localized/:id': GetEntityEndpoint<MovieMetadataLocalized, 'id'>
+    '/series-metadata-localized': GetCollectionEndpoint<SeriesMetadataLocalized>
+    '/series-metadata-localized/:id': GetEntityEndpoint<SeriesMetadataLocalized, 'id'>
     '/movie-files': GetCollectionEndpoint<MovieFile>
     '/movie-files/:id': GetEntityEndpoint<MovieFile, 'id'>
     '/files/:letter/:path/master.m3u8': HlsMasterEndpoint
diff --git a/common/src/models/config/config.ts b/common/src/models/config/config.ts
index 97676324..b934d64b 100644
--- a/common/src/models/config/config.ts
+++ b/common/src/models/config/config.ts
@@ -1,10 +1,19 @@
 import type { GithubConfig } from './github-config.js'
 import type { IotConfig } from './iot-config.js'
+import type { MetadataProviderConfig } from './metadata-provider-config.js'
 import type { MoviesConfig } from './movies-config.js'
 import type { OllamaConfig } from './ollama-config.js'
 import type { OmdbConfig } from './omdb-config.js'
+import type { TmdbConfig } from './tmdb-config.js'
 
-export type ConfigType = OmdbConfig | GithubConfig | IotConfig | MoviesConfig | OllamaConfig
+export type ConfigType =
+  | OmdbConfig
+  | GithubConfig
+  | IotConfig
+  | MoviesConfig
+  | OllamaConfig
+  | TmdbConfig
+  | MetadataProviderConfig
 
 export class Config {
   id!: ConfigType['id']
diff --git a/common/src/models/config/index.ts b/common/src/models/config/index.ts
index 7fac89b0..bc8e7a41 100644
--- a/common/src/models/config/index.ts
+++ b/common/src/models/config/index.ts
@@ -1,6 +1,8 @@
 export * from './config.js'
 export * from './github-config.js'
 export * from './iot-config.js'
+export * from './metadata-provider-config.js'
 export * from './movies-config.js'
 export * from './ollama-config.js'
 export * from './omdb-config.js'
+export * from './tmdb-config.js'
diff --git a/common/src/models/config/metadata-provider-config.ts b/common/src/models/config/metadata-provider-config.ts
new file mode 100644
index 00000000..24950679
--- /dev/null
+++ b/common/src/models/config/metadata-provider-config.ts
@@ -0,0 +1,10 @@
+export interface MetadataProviderConfig {
+  id: 'METADATA_PROVIDER_CONFIG'
+  value: {
+    /**
+     * Ordered list of metadata providers to try when linking movies.
+     * The first available provider that returns a result wins.
+     */
+    priority: Array<'omdb' | 'tmdb'>
+  }
+}
diff --git a/common/src/models/config/tmdb-config.ts b/common/src/models/config/tmdb-config.ts
new file mode 100644
index 00000000..635c01ce
--- /dev/null
+++ b/common/src/models/config/tmdb-config.ts
@@ -0,0 +1,18 @@
+export interface TmdbConfig {
+  id: 'TMDB_CONFIG'
+  value: {
+    /**
+     * The API key (v3 auth) or Read Access Token (v4 auth / Bearer) for the TMDB API.
+     * Can be obtained at https://www.themoviedb.org/settings/api
+     */
+    apiKey: string
+    /**
+     * Primary language for metadata fetches, in TMDB locale format (e.g. 'en-US', 'fr-FR').
+     */
+    defaultLanguage: string
+    /**
+     * Additional languages to fetch alongside the default (e.g. ['fr-FR', 'de-DE']).
+     */
+    additionalLanguages: string[]
+  }
+}
diff --git a/common/src/models/media/index.ts b/common/src/models/media/index.ts
index e3696da7..8bbfe7e3 100644
--- a/common/src/models/media/index.ts
+++ b/common/src/models/media/index.ts
@@ -1,7 +1,11 @@
 export * from './ffprobe-data.js'
 export * from './movie-file.js'
+export * from './movie-metadata-localized.js'
 export * from './movie-watch-history.js'
 export * from './movie.js'
 export * from './omdb-movie-metadata.js'
 export * from './omdb-series-metadata.js'
+export * from './series-metadata-localized.js'
 export * from './series.js'
+export * from './tmdb-movie-metadata.js'
+export * from './tmdb-series-metadata.js'
diff --git a/common/src/models/media/movie-metadata-localized.ts b/common/src/models/media/movie-metadata-localized.ts
new file mode 100644
index 00000000..477a2de7
--- /dev/null
+++ b/common/src/models/media/movie-metadata-localized.ts
@@ -0,0 +1,13 @@
+export class MovieMetadataLocalized {
+  id!: string
+  movieImdbId!: string
+  language!: string
+  title!: string
+  plot?: string
+  posterUrl?: string
+  genre?: string[]
+  source!: 'omdb' | 'tmdb'
+  sourceId?: string
+  createdAt!: string
+  updatedAt!: string
+}
diff --git a/common/src/models/media/movie.ts b/common/src/models/media/movie.ts
index 4fdc5f34..71d1b9dd 100644
--- a/common/src/models/media/movie.ts
+++ b/common/src/models/media/movie.ts
@@ -1,11 +1,7 @@
 export class Movie {
   imdbId!: string
-  title!: string
   year?: number
   duration?: number
-  genre?: string[]
-  thumbnailImageUrl?: string
-  plot?: string
   type?: 'movie' | 'episode'
   seriesId?: string
   season?: number
diff --git a/common/src/models/media/series-metadata-localized.ts b/common/src/models/media/series-metadata-localized.ts
new file mode 100644
index 00000000..d0b1bf16
--- /dev/null
+++ b/common/src/models/media/series-metadata-localized.ts
@@ -0,0 +1,12 @@
+export class SeriesMetadataLocalized {
+  id!: string
+  seriesImdbId!: string
+  language!: string
+  title!: string
+  plot?: string
+  posterUrl?: string
+  source!: 'omdb' | 'tmdb'
+  sourceId?: string
+  createdAt!: string
+  updatedAt!: string
+}
diff --git a/common/src/models/media/series.ts b/common/src/models/media/series.ts
index 3212710e..a792845f 100644
--- a/common/src/models/media/series.ts
+++ b/common/src/models/media/series.ts
@@ -1,9 +1,7 @@
 export class Series {
   imdbId!: string
-  public title!: string //'Supernatural'
-  public year!: string // '2005–2020'
-  public thumbnailImageUrl?: string
-  public plot!: string
+  year!: string
+  numberOfSeasons?: number
   createdAt!: string
   updatedAt!: string
 }
diff --git a/common/src/models/media/tmdb-movie-metadata.ts b/common/src/models/media/tmdb-movie-metadata.ts
new file mode 100644
index 00000000..3c8b6e1c
--- /dev/null
+++ b/common/src/models/media/tmdb-movie-metadata.ts
@@ -0,0 +1,25 @@
+export class TmdbMovieMetadata {
+  public id!: number
+  public imdbId?: string
+  public title!: string
+  public originalTitle!: string
+  public overview!: string
+  public releaseDate?: string
+  public runtime?: number
+  public posterPath?: string
+  public backdropPath?: string
+  public genres!: Array<{ id: number; name: string }>
+  public voteAverage?: number
+  public voteCount?: number
+  public popularity?: number
+  public originalLanguage!: string
+  public spokenLanguages?: Array<{ iso_639_1: string; name: string }>
+  public productionCountries?: Array<{ iso_3166_1: string; name: string }>
+  public status?: string
+  public tagline?: string
+  public budget?: number
+  public revenue?: number
+  public language!: string
+  public createdAt!: string
+  public updatedAt!: string
+}
diff --git a/common/src/models/media/tmdb-series-metadata.ts b/common/src/models/media/tmdb-series-metadata.ts
new file mode 100644
index 00000000..85ace9d0
--- /dev/null
+++ b/common/src/models/media/tmdb-series-metadata.ts
@@ -0,0 +1,21 @@
+export class TmdbSeriesMetadata {
+  public id!: number
+  public imdbId?: string
+  public name!: string
+  public originalName!: string
+  public overview!: string
+  public firstAirDate?: string
+  public posterPath?: string
+  public backdropPath?: string
+  public genres!: Array<{ id: number; name: string }>
+  public voteAverage?: number
+  public voteCount?: number
+  public numberOfSeasons?: number
+  public numberOfEpisodes?: number
+  public status?: string
+  public originalLanguage!: string
+  public languages?: string[]
+  public language!: string
+  public createdAt!: string
+  public updatedAt!: string
+}
diff --git a/frontend/src/components/command-palette/command-providers/search-movie.tsx b/frontend/src/components/command-palette/command-providers/search-movie.tsx
index a84c5988..05a71428 100644
--- a/frontend/src/components/command-palette/command-providers/search-movie.tsx
+++ b/frontend/src/components/command-palette/command-providers/search-movie.tsx
@@ -2,39 +2,34 @@ import type { CommandProvider } from '@furystack/shades-common-components'
 import { createSuggestion } from './create-suggestion.js'
 import { navigateToRoute } from '../../../utils/navigate-to-route.js'
 import { createComponent } from '@furystack/shades'
-import { MoviesService } from '../../../services/movies-service.js'
+import { MediaApiClient } from '../../../services/api-clients/media-api-client.js'
 
 export const searchMovieCommandProvider: CommandProvider = async ({ term, injector }) => {
   if (term.length > 4) {
-    const movieService = injector.getInstance(MoviesService)
-    const relatedMovies = await movieService.findMovie({
-      filter: {
-        $or: [
-          {
-            title: {
-              $like: `%${term}%`,
-            },
+    const mediaApiClient = injector.getInstance(MediaApiClient)
+    const { result: relatedLocalized } = await mediaApiClient.call({
+      method: 'GET',
+      action: '/movie-metadata-localized',
+      query: {
+        findOptions: {
+          filter: {
+            title: { $like: `%${term}%` },
           },
-          {
-            imdbId: {
-              $like: `%${term}%`,
-            },
-          },
-        ],
+        },
       },
     })
-    return relatedMovies.entries.map((movie) =>
+    return relatedLocalized.entries.map((entry) =>
       createSuggestion({
-        icon: movie.thumbnailImageUrl ? (
-          <img src={movie.thumbnailImageUrl} alt={movie.title} style={{ height: '64px', marginRight: '16px' }} />
+        icon: entry.posterUrl ? (
+          <img src={entry.posterUrl} alt={entry.title} style={{ height: '64px', marginRight: '16px' }} />
         ) : (
           '🎥'
         ),
-        name: movie.title,
-        description: movie.plot || '',
+        name: entry.title,
+        description: entry.plot || '',
         score: 5,
         onSelected: () => {
-          navigateToRoute(injector, '/movies/:imdbId/overview', { imdbId: movie.imdbId })
+          navigateToRoute(injector, '/movies/:imdbId/overview', { imdbId: entry.movieImdbId })
         },
       }),
     )
diff --git a/frontend/src/components/command-palette/command-providers/search-series.tsx b/frontend/src/components/command-palette/command-providers/search-series.tsx
index 498f0bea..ea120098 100644
--- a/frontend/src/components/command-palette/command-providers/search-series.tsx
+++ b/frontend/src/components/command-palette/command-providers/search-series.tsx
@@ -1,45 +1,35 @@
 import type { CommandProvider } from '@furystack/shades-common-components'
-import { SeriesService } from '../../../services/series-service.js'
 import { createSuggestion } from './create-suggestion.js'
 import { navigateToRoute } from '../../../utils/navigate-to-route.js'
 import { createComponent } from '@furystack/shades'
+import { MediaApiClient } from '../../../services/api-clients/media-api-client.js'
 
 export const searchSeriesCommandProvider: CommandProvider = async ({ term, injector }) => {
   if (term.length > 4) {
-    const seriesService = injector.getInstance(SeriesService)
-    const relatedSeries = await seriesService.findSeries({
-      filter: {
-        $or: [
-          {
-            title: {
-              $like: `%${term}%`,
-            },
+    const mediaApiClient = injector.getInstance(MediaApiClient)
+    const { result: relatedLocalized } = await mediaApiClient.call({
+      method: 'GET',
+      action: '/series-metadata-localized',
+      query: {
+        findOptions: {
+          filter: {
+            title: { $like: `%${term}%` },
           },
-          {
-            imdbId: {
-              $like: `%${term}%`,
-            },
-          },
-          {
-            plot: {
-              $like: `%${term}%`,
-            },
-          },
-        ],
+        },
       },
     })
-    return relatedSeries.entries.map((series) =>
+    return relatedLocalized.entries.map((entry) =>
       createSuggestion({
-        icon: series.thumbnailImageUrl ? (
-          <img src={series.thumbnailImageUrl} alt={series.title} style={{ height: '64px', marginRight: '16px' }} />
+        icon: entry.posterUrl ? (
+          <img src={entry.posterUrl} alt={entry.title} style={{ height: '64px', marginRight: '16px' }} />
         ) : (
           '🎥'
         ),
-        name: series.title,
-        description: series.plot,
+        name: entry.title,
+        description: entry.plot || '',
         score: 5,
         onSelected: () => {
-          navigateToRoute(injector, '/series/:imdbId', { imdbId: series.imdbId })
+          navigateToRoute(injector, '/series/:imdbId', { imdbId: entry.seriesImdbId })
         },
       }),
     )
diff --git a/frontend/src/components/dashboard/movie-widget.tsx b/frontend/src/components/dashboard/movie-widget.tsx
index 0bb0ccc6..02923ba9 100644
--- a/frontend/src/components/dashboard/movie-widget.tsx
+++ b/frontend/src/components/dashboard/movie-widget.tsx
@@ -3,9 +3,10 @@ import { isLoadedCacheResult } from '@furystack/cache'
 import { serializeToQueryString } from '@furystack/rest'
 import { LazyLoad, Shade, createComponent } from '@furystack/shades'
 import { CacheView, cssVariableTheme, Skeleton } from '@furystack/shades-common-components'
-import type { Movie } from 'common'
+import type { Movie, MovieMetadataLocalized } from 'common'
 import { AppLink } from '../../routes/index.js'
 import { navigateToRoute } from '../../utils/navigate-to-route.js'
+import { LocalizedMetadataService } from '../../services/localized-metadata-service.js'
 import { MovieFilesService } from '../../services/movie-files-service.js'
 import { MoviesService } from '../../services/movies-service.js'
 import { SessionService } from '../../services/session.js'
@@ -25,15 +26,22 @@ const MovieWidgetContent = Shade<{
 
     const movieFileService = injector.getInstance(MovieFilesService)
     const watchProgressService = injector.getInstance(WatchProgressService)
+    const localizedService = injector.getInstance(LocalizedMetadataService)
 
     const [currentUser] = useObservable('currentUser', injector.getInstance(SessionService).currentUser)
     const [movieFile] = useObservable(
       'movieFile',
       movieFileService.findMovieFileAsObservable({ filter: { imdbId: { $eq: imdbId } } }),
     )
+    const [localized] = useObservable('localized', localizedService.getMovieLocalizedAsObservable(imdbId))
+
+    const localizedData = (localized as CacheWithValue<MovieMetadataLocalized | undefined> | undefined)?.value
+    const title = localizedData?.title ?? imdbId
+    const plot = localizedData?.plot
+    const posterUrl = localizedData?.posterUrl
 
     return (
-      <AppLink tabIndex={0} title={movie.plot || movie.title} href="/movies/:imdbId/overview" params={{ imdbId }}>
+      <AppLink tabIndex={0} title={plot || title} href="/movies/:imdbId/overview" params={{ imdbId }}>
         <WidgetCard size={size} index={props.index}>
           <div
             className="overlay"
@@ -80,14 +88,18 @@ const MovieWidgetContent = Shade<{
               </div>
             ) : null}
           </div>
-          <img
-            src={movie.thumbnailImageUrl as string}
-            alt={movie.title}
-            className="cover"
-            style={{ backgroundColor: cssVariableTheme.background.default }}
-          />
+          {posterUrl ? (
+            <img
+              src={posterUrl}
+              alt={title}
+              className="cover"
+              style={{ backgroundColor: cssVariableTheme.background.default }}
+            />
+          ) : (
+            <div className="cover" style={{ backgroundColor: cssVariableTheme.background.default }} />
+          )}
           <div className="title-bar">
-            {movie.title}
+            {title}
             <LazyLoad
               loader={<div />}
               component={async () => {
diff --git a/frontend/src/components/dashboard/series-widget.tsx b/frontend/src/components/dashboard/series-widget.tsx
index 569aab4d..115e1478 100644
--- a/frontend/src/components/dashboard/series-widget.tsx
+++ b/frontend/src/components/dashboard/series-widget.tsx
@@ -1,8 +1,9 @@
 import type { CacheWithValue } from '@furystack/cache'
 import { Shade, createComponent } from '@furystack/shades'
 import { CacheView, cssVariableTheme, Skeleton } from '@furystack/shades-common-components'
-import type { Series } from 'common'
+import type { Series, SeriesMetadataLocalized } from 'common'
 import { AppLink } from '../../routes/index.js'
+import { LocalizedMetadataService } from '../../services/localized-metadata-service.js'
 import { SeriesService } from '../../services/series-service.js'
 import { WidgetCard } from './widget-card.js'
 
@@ -12,21 +13,33 @@ const SeriesWidgetContent = Shade<{
   size?: number
 }>({
   customElementName: 'pi-rat-series-widget-content',
-  render: ({ props }) => {
+  render: ({ props, injector, useObservable }) => {
     const { size = 256 } = props
     const series = props.data.value
     const { imdbId } = series
 
+    const localizedService = injector.getInstance(LocalizedMetadataService)
+    const [localized] = useObservable('localized', localizedService.getSeriesLocalizedAsObservable(imdbId))
+
+    const localizedData = (localized as CacheWithValue<SeriesMetadataLocalized | undefined> | undefined)?.value
+    const title = localizedData?.title ?? imdbId
+    const plot = localizedData?.plot
+    const posterUrl = localizedData?.posterUrl
+
     return (
-      <AppLink tabIndex={0} title={series.plot || series.title} href="/series/:imdbId" params={{ imdbId }}>
+      <AppLink tabIndex={0} title={plot || title} href="/series/:imdbId" params={{ imdbId }}>
         <WidgetCard size={size} index={props.index}>
-          <img
-            src={series.thumbnailImageUrl as string}
-            alt={series.title}
-            className="cover"
-            style={{ backgroundColor: cssVariableTheme.background.default }}
-          />
-          <div className="title-bar">{series.title}</div>
+          {posterUrl ? (
+            <img
+              src={posterUrl}
+              alt={title}
+              className="cover"
+              style={{ backgroundColor: cssVariableTheme.background.default }}
+            />
+          ) : (
+            <div className="cover" style={{ backgroundColor: cssVariableTheme.background.default }} />
+          )}
+          <div className="title-bar">{title}</div>
         </WidgetCard>
       </AppLink>
     )
diff --git a/frontend/src/components/movie-file-management/related-movies-modal-content.tsx b/frontend/src/components/movie-file-management/related-movies-modal-content.tsx
index 484c9a85..94c56caf 100644
--- a/frontend/src/components/movie-file-management/related-movies-modal-content.tsx
+++ b/frontend/src/components/movie-file-management/related-movies-modal-content.tsx
@@ -33,7 +33,8 @@ const RelatedMoviesContent = Shade<{
           <Typography variant="body1">
             No related movie is linked to this file
             <>
-              {serviceStatus.status === 'loaded' && serviceStatus.value.services.omdb ? (
+              {serviceStatus.status === 'loaded' &&
+              (serviceStatus.value.services.omdb || serviceStatus.value.services.tmdb) ? (
                 <Button
                   onclick={async () => {
                     const mediaApiClient = injector.getInstance(MediaApiClient)
@@ -51,7 +52,7 @@ const RelatedMoviesContent = Shade<{
                   🔗 Link movie
                 </Button>
               ) : (
-                <Button disabled>OMDB not available</Button>
+                <Button disabled>No metadata provider available</Button>
               )}
             </>
           </Typography>
diff --git a/frontend/src/components/movie-picker.tsx b/frontend/src/components/movie-picker.tsx
index 62bbdcae..744a2089 100644
--- a/frontend/src/components/movie-picker.tsx
+++ b/frontend/src/components/movie-picker.tsx
@@ -13,14 +13,14 @@ export const MoviePicker = Shade({
           const result = await moviesService.findMovie({
             top: 10,
             filter: {
-              $or: [{ title: { $like: `%${term}%` } }],
+              $or: [{ imdbId: { $like: `%${term}%` } }],
             },
           })
           return result.entries
         }}
         defaultPrefix=""
         getSuggestionEntry={(entry) => ({
-          element: <div>{entry.title}</div>,
+          element: <div>{entry.imdbId}</div>,
           score: 1,
         })}
         onSelectSuggestion={(entry: Movie) => {
diff --git a/frontend/src/pages/admin/app-settings.tsx b/frontend/src/pages/admin/app-settings.tsx
index 99e28c1f..8baabca7 100644
--- a/frontend/src/pages/admin/app-settings.tsx
+++ b/frontend/src/pages/admin/app-settings.tsx
@@ -15,6 +15,7 @@ const getMenuItems = (): Array<MenuEntry & { href?: AppPaths }> => [
     label: 'Media',
     children: [
       { key: '/app-settings/omdb', label: 'OMDB Settings', icon: <Icon icon={icons.film} size="small" /> },
+      { key: '/app-settings/tmdb', label: 'TMDB Settings', icon: <Icon icon={icons.film} size="small" /> },
       { key: '/app-settings/streaming', label: 'Streaming Settings', icon: <Icon icon={icons.play} size="small" /> },
     ],
   },
diff --git a/frontend/src/pages/admin/tmdb-settings.tsx b/frontend/src/pages/admin/tmdb-settings.tsx
new file mode 100644
index 00000000..c1866c35
--- /dev/null
+++ b/frontend/src/pages/admin/tmdb-settings.tsx
@@ -0,0 +1,212 @@
+import type { CacheWithValue } from '@furystack/cache'
+import { createComponent, Shade } from '@furystack/shades'
+import {
+  Button,
+  CacheView,
+  cssVariableTheme,
+  Form,
+  Icon,
+  icons,
+  Input,
+  NotyService,
+  PageContainer,
+  PageHeader,
+  Paper,
+  Skeleton,
+  Typography,
+} from '@furystack/shades-common-components'
+import { ObservableValue } from '@furystack/utils'
+import type { Config, TmdbConfig } from 'common'
+import { GenericErrorPage } from '../../components/generic-error.js'
+import { ConfigService } from '../../services/config-service.js'
+
+type TmdbFormData = TmdbConfig['value']
+
+type TmdbRawFormData = {
+  apiKey: string
+  defaultLanguage: string
+  additionalLanguages: string
+}
+
+const isTmdbRawFormData = (data: unknown): data is TmdbRawFormData => {
+  if (typeof data !== 'object' || data === null) return false
+  const d = data as Record<string, unknown>
+  return typeof d.apiKey === 'string'
+}
+
+const TmdbSettingsContent = Shade<{ data: CacheWithValue<Config> }>({
+  customElementName: 'tmdb-settings-content',
+  css: {
+    '& .page-description': {
+      marginBottom: '24px',
+      color: cssVariableTheme.text.secondary,
+    },
+    '& .form-field': {
+      marginBottom: '24px',
+    },
+    '& .api-key-row': {
+      display: 'flex',
+      alignItems: 'flex-end',
+      gap: '8px',
+    },
+    '& .field-hint': {
+      color: cssVariableTheme.text.secondary,
+      display: 'block',
+      marginTop: '4px',
+    },
+    '& .field-hint a': {
+      color: cssVariableTheme.palette.primary.main,
+    },
+    '& .form-footer': {
+      borderTop: `1px solid ${cssVariableTheme.background.default}`,
+      paddingTop: '16px',
+    },
+  },
+  render: ({ props, injector, useObservable, useDisposable, useState }) => {
+    const configService = injector.getInstance(ConfigService)
+    const notyService = injector.getInstance(NotyService)
+
+    const isLoadingObservable = useDisposable('isLoading', () => new ObservableValue(false))
+    const [isLoading] = useObservable('isLoadingValue', isLoadingObservable)
+    const [isApiKeyVisible, setApiKeyVisible] = useState('apiKeyVisible', false)
+
+    const toggleApiKeyVisibility = () => {
+      setApiKeyVisible(!isApiKeyVisible)
+    }
+
+    const handleSubmit = async (formData: TmdbRawFormData) => {
+      const additionalLanguages = formData.additionalLanguages
+        .split(',')
+        .map((lang) => lang.trim())
+        .filter(Boolean)
+
+      const data: TmdbFormData = {
+        apiKey: formData.apiKey,
+        defaultLanguage: formData.defaultLanguage || 'en-US',
+        additionalLanguages,
+      }
+
+      isLoadingObservable.setValue(true)
+      try {
+        await configService.saveConfig('TMDB_CONFIG', data)
+        notyService.emit('onNotyAdded', {
+          title: 'Success',
+          body: 'TMDB settings saved successfully',
+          type: 'success',
+        })
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Failed to save settings'
+        notyService.emit('onNotyAdded', {
+          title: 'Error',
+          body: errorMessage,
+          type: 'error',
+        })
+      } finally {
+        isLoadingObservable.setValue(false)
+      }
+    }
+
+    const currentValues: TmdbFormData = props.data.value.value
+      ? (props.data.value.value as TmdbFormData)
+      : { apiKey: '', defaultLanguage: 'en-US', additionalLanguages: [] }
+
+    return (
+      <>
+        <Typography variant="body1" className="page-description">
+          Configure the TMDB API integration for fetching movie and series metadata with multi-language support.
+        </Typography>
+
+        <Paper elevation={1} style={{ padding: '24px' }}>
+          <Form<TmdbRawFormData> validate={isTmdbRawFormData} onSubmit={(data) => void handleSubmit(data)}>
+            <div className="form-field">
+              <div className="api-key-row">
+                <Input
+                  labelTitle="API Read Access Token"
+                  name="apiKey"
+                  type={isApiKeyVisible ? 'text' : 'password'}
+                  value={currentValues.apiKey}
+                  placeholder="Enter your TMDB API Read Access Token"
+                  style={{ flex: '1' }}
+                />
+                <Button
+                  type="button"
+                  variant="outlined"
+                  onclick={toggleApiKeyVisibility}
+                  style={{ marginBottom: '4px' }}
+                >
+                  {isApiKeyVisible ? (
+                    <>
+                      <Icon icon={icons.eyeOff} size="small" /> Hide
+                    </>
+                  ) : (
+                    <>
+                      <Icon icon={icons.eye} size="small" /> Show
+                    </>
+                  )}
+                </Button>
+              </div>
+              <small className="field-hint">
+                Get your API key at{' '}
+                <a href="https://www.themoviedb.org/settings/api" target="_blank" rel="noopener noreferrer">
+                  themoviedb.org
+                </a>
+              </small>
+            </div>
+
+            <div className="form-field">
+              <Input
+                labelTitle="Default Language"
+                name="defaultLanguage"
+                type="text"
+                value={currentValues.defaultLanguage}
+                placeholder="en-US"
+              />
+              <small className="field-hint">
+                Primary language for metadata (TMDB locale format, e.g. en-US, fr-FR, de-DE)
+              </small>
+            </div>
+
+            <div className="form-field">
+              <Input
+                labelTitle="Additional Languages"
+                name="additionalLanguages"
+                type="text"
+                value={currentValues.additionalLanguages.join(', ')}
+                placeholder="fr-FR, de-DE, es-ES"
+              />
+              <small className="field-hint">
+                Comma-separated list of additional languages to fetch alongside the default
+              </small>
+            </div>
+
+            <div className="form-footer">
+              <Button type="submit" variant="contained" color="primary" disabled={isLoading}>
+                {isLoading ? 'Saving...' : 'Save Settings'}
+              </Button>
+            </div>
+          </Form>
+        </Paper>
+      </>
+    )
+  },
+})
+
+export const TmdbSettingsPage = Shade({
+  customElementName: 'tmdb-settings-page',
+  render: ({ injector }) => {
+    const configService = injector.getInstance(ConfigService)
+
+    return (
+      <PageContainer gap="24px">
+        <PageHeader icon={<Icon icon={icons.film} />} title="TMDB Settings" />
+        <CacheView
+          cache={configService.configCache}
+          args={['TMDB_CONFIG']}
+          content={TmdbSettingsContent}
+          loader={<Skeleton />}
+          error={(err, retry) => <GenericErrorPage error={err} retry={async () => retry()} />}
+        />
+      </PageContainer>
+    )
+  },
+})
diff --git a/frontend/src/pages/entities/tmdb-movie-metadata.tsx b/frontend/src/pages/entities/tmdb-movie-metadata.tsx
new file mode 100644
index 00000000..c2beff19
--- /dev/null
+++ b/frontend/src/pages/entities/tmdb-movie-metadata.tsx
@@ -0,0 +1,59 @@
+import { createComponent, Shade } from '@furystack/shades'
+import { TmdbMovieMetadata } from 'common'
+import mediaSchemas from 'common/schemas/media-entities.json' with { type: 'json' }
+import { GenericEditorService } from '../../components/generic-editor/generic-editor-service.js'
+import { GenericEditor } from '../../components/generic-editor/index.js'
+import { MediaApiClient } from '../../services/api-clients/media-api-client.js'
+
+export const TmdbMovieMetadataPage = Shade({
+  customElementName: 'shade-app-tmdb-movie-metadata-page',
+  render: ({ useDisposable, injector }) => {
+    const api = injector.getInstance(MediaApiClient)
+
+    const service = useDisposable(
+      'service',
+      () =>
+        new GenericEditorService({
+          model: TmdbMovieMetadata,
+          keyProperty: 'id',
+          readonlyProperties: [],
+          getEntities: async (findOptions) => {
+            const result = await api.call({
+              method: 'GET',
+              action: '/tmdb-movie-metadata',
+              query: { findOptions },
+            })
+            return result.result
+          },
+          deleteEntities: async () => {
+            alert('Not supported')
+          },
+          getEntity: async (id) => {
+            const result = await api.call({ method: 'GET', action: `/tmdb-movie-metadata/:id`, url: { id }, query: {} })
+            return result.result
+          },
+          patchEntity: async () => {
+            alert('Not supported!')
+          },
+          postEntity: async (entity) => {
+            alert('Not supported!')
+            return entity
+          },
+        }),
+    )
+    return (
+      <GenericEditor
+        service={service}
+        basePath="/entities/tmdb-movie-metadata"
+        columns={['id', 'title', 'releaseDate', 'language', 'updatedAt']}
+        headerComponents={{}}
+        styles={{}}
+        rowComponents={{}}
+        schemaInfo={{
+          schemaName: 'TmdbMovieMetadata',
+          jsonSchema: { ...mediaSchemas, type: 'object', $ref: '#/definitions/TmdbMovieMetadata' },
+        }}
+      />
+    )
+  },
+})
diff --git a/frontend/src/pages/entities/tmdb-series-metadata.tsx b/frontend/src/pages/entities/tmdb-series-metadata.tsx
new file mode 100644
index 00000000..0c45cac3
--- /dev/null
+++ b/frontend/src/pages/entities/tmdb-series-metadata.tsx
@@ -0,0 +1,64 @@
+import { createComponent, Shade } from '@furystack/shades'
+import { TmdbSeriesMetadata } from 'common'
+import mediaSchemas from 'common/schemas/media-entities.json' with { type: 'json' }
+import { GenericEditorService } from '../../components/generic-editor/generic-editor-service.js'
+import { GenericEditor } from '../../components/generic-editor/index.js'
+import { MediaApiClient } from '../../services/api-clients/media-api-client.js'
+
+export const TmdbSeriesMetadataPage = Shade({
+  customElementName: 'shade-app-tmdb-series-metadata-page',
+  render: ({ useDisposable, injector }) => {
+    const api = injector.getInstance(MediaApiClient)
+
+    const service = useDisposable(
+      'service',
+      () =>
+        new GenericEditorService({
+          model: TmdbSeriesMetadata,
+          keyProperty: 'id',
+          readonlyProperties: [],
+          getEntities: async (findOptions) => {
+            const result = await api.call({
+              method: 'GET',
+              action: '/tmdb-series-metadata',
+              query: { findOptions },
+            })
+            return result.result
+          },
+          deleteEntities: async () => {
+            alert('Not supported')
+          },
+          getEntity: async (id) => {
+            const result = await api.call({
+              method: 'GET',
+              action: `/tmdb-series-metadata/:id`,
+              url: { id },
+              query: {},
+            })
+            return result.result
+          },
+          patchEntity: async () => {
+            alert('Not supported!')
+          },
+          postEntity: async (entity) => {
+            alert('Not supported!')
+            return entity
+          },
+        }),
+    )
+    return (
+      <GenericEditor
+        service={service}
+        basePath="/entities/tmdb-series-metadata"
+        columns={['id', 'name', 'firstAirDate', 'language', 'updatedAt']}
+        headerComponents={{}}
+        styles={{}}
+        rowComponents={{}}
+        schemaInfo={{
+          schemaName: 'TmdbSeriesMetadata',
+          jsonSchema: { ...mediaSchemas, type: 'object', $ref: '#/definitions/TmdbSeriesMetadata' },
+        }}
+      />
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-overview.tsx b/frontend/src/pages/movies/movie-overview.tsx
index 4dcdabbc..cc7f3fc9 100644
--- a/frontend/src/pages/movies/movie-overview.tsx
+++ b/frontend/src/pages/movies/movie-overview.tsx
@@ -3,9 +3,10 @@ import { isLoadedCacheResult } from '@furystack/cache'
 import { serializeToQueryString } from '@furystack/rest'
 import { createComponent, Shade } from '@furystack/shades'
 import { Button, CacheView, Skeleton, Typography } from '@furystack/shades-common-components'
-import type { Movie } from 'common'
+import type { Movie, MovieMetadataLocalized } from 'common'
 import { GenericErrorPage } from '../../components/generic-error.js'
 import { navigateToRoute } from '../../utils/navigate-to-route.js'
+import { LocalizedMetadataService } from '../../services/localized-metadata-service.js'
 import { MovieFilesService } from '../../services/movie-files-service.js'
 import { MoviesService } from '../../services/movies-service.js'
 import { SessionService } from '../../services/session.js'
@@ -99,14 +100,23 @@ const MovieOverviewContent = Shade<{ data: CacheWithValue<Movie> }>({
     const [currentUser] = useObservable('currentUser', injector.getInstance(SessionService).currentUser)
     const movie = props.data.value
 
+    const localizedService = injector.getInstance(LocalizedMetadataService)
+    const [localized] = useObservable('localized', localizedService.getMovieLocalizedAsObservable(movie.imdbId))
+
+    const localizedData = (localized as CacheWithValue<MovieMetadataLocalized | undefined> | undefined)?.value
+    const title = localizedData?.title ?? movie.imdbId
+    const plot = localizedData?.plot
+    const posterUrl = localizedData?.posterUrl
+    const genre = localizedData?.genre
+
     return (
-      <MediaOverviewLayout thumbnailUrl={movie.thumbnailImageUrl || ''} title={movie.title}>
-        <Typography variant="h1">{movie.title}</Typography>
+      <MediaOverviewLayout thumbnailUrl={posterUrl || ''} title={title}>
+        <Typography variant="h1">{title}</Typography>
         <Typography variant="caption">
-          {movie.year?.toString()} &nbsp; {movie.genre}
+          {movie.year?.toString()} &nbsp; {genre?.join(', ')}
         </Typography>
         <Typography variant="body1" align="justify">
-          {movie.plot}
+          {plot}
         </Typography>
         <div>
           <PlayButtons imdbId={movie.imdbId} />
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
index 59f37a54..a423487e 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
@@ -211,7 +211,7 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
 
           <media-loading-indicator slot="centered-chrome"></media-loading-indicator>
           <media-error-dialog slot="dialog"></media-error-dialog>
-          <media-poster-image slot="poster" src={props.movie?.thumbnailImageUrl} />
+          <media-poster-image slot="poster" />
 
           <media-control-bar style={{ width: '100%' }}>
             <media-play-button />
diff --git a/frontend/src/pages/movies/series-overview.tsx b/frontend/src/pages/movies/series-overview.tsx
index c5bf3c80..34f8ba88 100644
--- a/frontend/src/pages/movies/series-overview.tsx
+++ b/frontend/src/pages/movies/series-overview.tsx
@@ -2,6 +2,7 @@ import { createComponent, ScreenService, Shade } from '@furystack/shades'
 import { Typography } from '@furystack/shades-common-components'
 import { WidgetGroup } from '../../components/dashboard/widget-group.js'
 import { PiRatLazyLoad } from '../../components/pirat-lazy-load.js'
+import { LocalizedMetadataService } from '../../services/localized-metadata-service.js'
 import { MovieFilesService } from '../../services/movie-files-service.js'
 import { MoviesService } from '../../services/movies-service.js'
 import { SeriesService } from '../../services/series-service.js'
@@ -20,14 +21,16 @@ export const SeriesOverview = Shade<SeriesListProps>({
     const moviesService = injector.getInstance(MoviesService)
     const movieFileService = injector.getInstance(MovieFilesService)
     const watchProgresses = injector.getInstance(WatchProgressService)
+    const localizedService = injector.getInstance(LocalizedMetadataService)
 
     return (
       <PiRatLazyLoad
         component={async () => {
-          const [series, relatedMovies, relatedMovieFiles] = await Promise.all([
+          const [series, relatedMovies, relatedMovieFiles, seriesLocalized] = await Promise.all([
             seriesService.getSeries(props.imdbId),
             moviesService.findMovie({ filter: { seriesId: { $eq: props.imdbId } } }),
             movieFileService.findMovieFile({ filter: { imdbId: { $in: [props.imdbId] } } }),
+            localizedService.getSeriesLocalized(props.imdbId),
           ])
 
           await Promise.all([
@@ -35,24 +38,28 @@ export const SeriesOverview = Shade<SeriesListProps>({
             watchProgresses.prefetchWatchProgressForFiles(relatedMovieFiles.entries),
           ])
 
+          const title = seriesLocalized?.title ?? series.imdbId
+          const plot = seriesLocalized?.plot
+          const posterUrl = seriesLocalized?.posterUrl
+
           const seasons = Array.from(
             new Set(relatedMovies.entries.map((m) => m.season).filter((s) => !isNaN(s as number))),
           ).sort() as number[]
 
           return (
             <MediaOverviewLayout
-              thumbnailUrl={series.thumbnailImageUrl || ''}
-              title={series.title}
+              thumbnailUrl={posterUrl || ''}
+              title={title}
               detailsContainerStyle={{
                 maxHeight: isDesktop ? 'calc(100% - 128px)' : undefined,
                 overflow: 'hidden',
                 overflowY: isDesktop ? 'auto' : undefined,
               }}
             >
-              <Typography variant="h1">{series.title}</Typography>
+              <Typography variant="h1">{title}</Typography>
               <Typography variant="caption">{series.year?.toString()} &nbsp;</Typography>
               <Typography variant="body1" align="justify">
-                {series.plot}
+                {plot}
               </Typography>
               <div style={{ width: '100%', overflow: 'hidden' }}>
                 {seasons.map((s) => (
diff --git a/frontend/src/routes/entity-routes.tsx b/frontend/src/routes/entity-routes.tsx
index d72aa47b..9f3efa17 100644
--- a/frontend/src/routes/entity-routes.tsx
+++ b/frontend/src/routes/entity-routes.tsx
@@ -103,6 +103,30 @@ export const entityRoute = {
       ),
       children: entityEditorChildren,
     },
+    '/tmdb-movie-metadata': {
+      meta: { title: 'TMDB Movie Metadata', icon: icons.globe },
+      component: () => (
+        <PiRatLazyLoad
+          component={async () => {
+            const { TmdbMovieMetadataPage } = await import('../pages/entities/tmdb-movie-metadata.js')
+            return <TmdbMovieMetadataPage />
+          }}
+        />
+      ),
+      children: entityEditorChildren,
+    },
+    '/tmdb-series-metadata': {
+      meta: { title: 'TMDB Series Metadata', icon: icons.globe },
+      component: () => (
+        <PiRatLazyLoad
+          component={async () => {
+            const { TmdbSeriesMetadataPage } = await import('../pages/entities/tmdb-series-metadata.js')
+            return <TmdbSeriesMetadataPage />
+          }}
+        />
+      ),
+      children: entityEditorChildren,
+    },
     '/config': {
       meta: { title: 'Config', icon: icons.settings },
       component: () => (
diff --git a/frontend/src/routes/settings-routes.tsx b/frontend/src/routes/settings-routes.tsx
index ab508137..5074d59c 100644
--- a/frontend/src/routes/settings-routes.tsx
+++ b/frontend/src/routes/settings-routes.tsx
@@ -23,6 +23,17 @@ export const settingsChildren = {
       />
     ),
   },
+  '/tmdb': {
+    meta: { title: 'TMDB Settings', icon: icons.film },
+    component: () => (
+      <PiRatLazyLoad
+        component={async () => {
+          const { TmdbSettingsPage } = await import('../pages/admin/tmdb-settings.js')
+          return <TmdbSettingsPage />
+        }}
+      />
+    ),
+  },
   '/streaming': {
     meta: { title: 'Streaming Settings', icon: icons.play },
     component: () => (
diff --git a/frontend/src/services/localized-metadata-service.ts b/frontend/src/services/localized-metadata-service.ts
new file mode 100644
index 00000000..dfab5ab1
--- /dev/null
+++ b/frontend/src/services/localized-metadata-service.ts
@@ -0,0 +1,65 @@
+import { Injectable, Injected } from '@furystack/inject'
+import { Cache } from '@furystack/cache'
+import type { MovieMetadataLocalized, SeriesMetadataLocalized } from 'common'
+import { MediaApiClient } from './api-clients/media-api-client.js'
+
+/**
+ * Provides cached access to localized movie/series display data.
+ * Uses 'en' as the default language until user language preferences are integrated.
+ */
+@Injectable({ lifetime: 'singleton' })
+export class LocalizedMetadataService implements Disposable {
+  @Injected(MediaApiClient)
+  declare private readonly mediaApiClient: MediaApiClient
+
+  public movieLocalizedCache = new Cache({
+    capacity: 200,
+    load: async (movieImdbId: string, language = 'en') => {
+      const { result } = await this.mediaApiClient.call({
+        method: 'GET',
+        action: '/movie-metadata-localized',
+        query: {
+          findOptions: {
+            filter: {
+              movieImdbId: { $eq: movieImdbId },
+              language: { $eq: language },
+            },
+            top: 1,
+          },
+        },
+      })
+      return result.entries[0] as MovieMetadataLocalized | undefined
+    },
+  })
+
+  public seriesLocalizedCache = new Cache({
+    capacity: 200,
+    load: async (seriesImdbId: string, language = 'en') => {
+      const { result } = await this.mediaApiClient.call({
+        method: 'GET',
+        action: '/series-metadata-localized',
+        query: {
+          findOptions: {
+            filter: {
+              seriesImdbId: { $eq: seriesImdbId },
+              language: { $eq: language },
+            },
+            top: 1,
+          },
+        },
+      })
+      return result.entries[0] as SeriesMetadataLocalized | undefined
+    },
+  })
+
+  public getMovieLocalized = this.movieLocalizedCache.get.bind(this.movieLocalizedCache)
+  public getMovieLocalizedAsObservable = this.movieLocalizedCache.getObservable.bind(this.movieLocalizedCache)
+
+  public getSeriesLocalized = this.seriesLocalizedCache.get.bind(this.seriesLocalizedCache)
+  public getSeriesLocalizedAsObservable = this.seriesLocalizedCache.getObservable.bind(this.seriesLocalizedCache)
+
+  public [Symbol.dispose](): void {
+    this.movieLocalizedCache[Symbol.dispose]()
+    this.seriesLocalizedCache[Symbol.dispose]()
+  }
+}
diff --git a/frontend/src/services/movies-service.spec.ts b/frontend/src/services/movies-service.spec.ts
index 0c7761aa..55f4d50f 100644
--- a/frontend/src/services/movies-service.spec.ts
+++ b/frontend/src/services/movies-service.spec.ts
@@ -5,14 +5,10 @@ import { MoviesService } from './movies-service.js'
 import { MediaApiClient } from './api-clients/media-api-client.js'
 import type { Movie } from 'common'
 
-const createMockMovie = (imdbId = 'tt1234567', title = 'Test Movie'): Movie => ({
+const createMockMovie = (imdbId = 'tt1234567', _title = 'Test Movie'): Movie => ({
   imdbId,
-  title,
   year: 2024,
   type: 'movie',
-  genre: ['Action'],
-  plot: 'Test plot',
-  thumbnailImageUrl: 'https://example.com/poster.jpg',
   createdAt: new Date().toISOString(),
   updatedAt: new Date().toISOString(),
 })
@@ -180,12 +176,8 @@ describe('MoviesService', () => {
 
         const body = {
           imdbId: 'tt1234567',
-          title: 'Test Movie',
           year: 2024,
           type: 'movie' as const,
-          genre: ['Action'],
-          plot: 'Test plot',
-          thumbnailImageUrl: 'https://example.com/poster.jpg',
         }
         const result = await service.createMovie(body)
 
@@ -216,12 +208,8 @@ describe('MoviesService', () => {
         await service.getMovie('tt1234567')
 
         const body = {
-          title: 'Updated Movie',
           year: 2024,
           type: 'movie' as const,
-          genre: ['Drama'],
-          plot: 'Updated plot',
-          thumbnailImageUrl: 'https://example.com/updated-poster.jpg',
         }
         const result = await service.updateMovie('tt1234567', body)
 
diff --git a/frontend/src/services/series-service.spec.ts b/frontend/src/services/series-service.spec.ts
index 901ec962..bbed1dd9 100644
--- a/frontend/src/services/series-service.spec.ts
+++ b/frontend/src/services/series-service.spec.ts
@@ -5,12 +5,9 @@ import { SeriesService } from './series-service.js'
 import { MediaApiClient } from './api-clients/media-api-client.js'
 import type { Series } from 'common'
 
-const createMockSeries = (imdbId = 'tt9876543', title = 'Test Series'): Series => ({
+const createMockSeries = (imdbId = 'tt9876543', _title = 'Test Series'): Series => ({
   imdbId,
-  title,
   year: '2024',
-  plot: 'Test series plot',
-  thumbnailImageUrl: 'https://example.com/series-poster.jpg',
   createdAt: new Date().toISOString(),
   updatedAt: new Date().toISOString(),
 })
diff --git a/service/src/app-models/install/actions/get-service-status.ts b/service/src/app-models/install/actions/get-service-status.ts
index 7f7fb159..36f66d15 100644
--- a/service/src/app-models/install/actions/get-service-status.ts
+++ b/service/src/app-models/install/actions/get-service-status.ts
@@ -13,6 +13,7 @@ export const GetServiceStatus: RequestAction<GetServiceStatusAction> = async ({
     state,
     services: {
       omdb: services.omdb ?? false,
+      tmdb: services.tmdb ?? false,
       github: services.github ?? false,
     },
   })
diff --git a/service/src/app-models/media/metadata-services/tmdb-api-types.ts b/service/src/app-models/media/metadata-services/tmdb-api-types.ts
new file mode 100644
index 00000000..184969b3
--- /dev/null
+++ b/service/src/app-models/media/metadata-services/tmdb-api-types.ts
@@ -0,0 +1,252 @@
+/**
+ * Hand-written types for the TMDB v3 API endpoints used by pi-rat.
+ * Based on https://developer.themoviedb.org/reference/getting-started
+ */
+
+// ── Search Movie ── GET /3/search/movie ──────────────────────────────
+
+export type TmdbSearchMovieParams = {
+  query: string
+  include_adult?: boolean
+  language?: string
+  primary_release_year?: string
+  page?: number
+  region?: string
+  year?: string
+}
+
+export type TmdbSearchMovieResult = {
+  adult: boolean
+  backdrop_path: string | null
+  genre_ids: number[]
+  id: number
+  original_language: string
+  original_title: string
+  overview: string
+  popularity: number
+  poster_path: string | null
+  release_date: string
+  title: string
+  video: boolean
+  vote_average: number
+  vote_count: number
+}
+
+export type TmdbPaginatedResponse<T> = {
+  page: number
+  results: T[]
+  total_pages: number
+  total_results: number
+}
+
+// ── Search TV ── GET /3/search/tv ────────────────────────────────────
+
+export type TmdbSearchTvParams = {
+  query: string
+  first_air_date_year?: number
+  include_adult?: boolean
+  language?: string
+  page?: number
+  year?: number
+}
+
+export type TmdbSearchTvResult = {
+  adult: boolean
+  backdrop_path: string | null
+  genre_ids: number[]
+  id: number
+  origin_country: string[]
+  original_language: string
+  original_name: string
+  overview: string
+  popularity: number
+  poster_path: string | null
+  first_air_date: string
+  name: string
+  vote_average: number
+  vote_count: number
+}
+
+// ── Movie Details ── GET /3/movie/{movie_id} ─────────────────────────
+
+export type TmdbMovieDetailsResponse = {
+  adult: boolean
+  backdrop_path: string | null
+  belongs_to_collection: {
+    id: number
+    name: string
+    poster_path: string | null
+    backdrop_path: string | null
+  } | null
+  budget: number
+  genres: Array<{ id: number; name: string }>
+  homepage: string
+  id: number
+  imdb_id: string | null
+  origin_country: string[]
+  original_language: string
+  original_title: string
+  overview: string
+  popularity: number
+  poster_path: string | null
+  production_companies: Array<{
+    id: number
+    logo_path: string | null
+    name: string
+    origin_country: string
+  }>
+  production_countries: Array<{ iso_3166_1: string; name: string }>
+  release_date: string
+  revenue: number
+  runtime: number
+  spoken_languages: Array<{
+    english_name: string
+    iso_639_1: string
+    name: string
+  }>
+  status: string
+  tagline: string
+  title: string
+  video: boolean
+  vote_average: number
+  vote_count: number
+  external_ids?: TmdbExternalIds
+}
+
+// ── TV Series Details ── GET /3/tv/{series_id} ───────────────────────
+
+export type TmdbTvDetailsResponse = {
+  adult: boolean
+  backdrop_path: string | null
+  created_by: Array<{
+    id: number
+    credit_id: string
+    name: string
+    original_name: string
+    gender: number
+    profile_path: string | null
+  }>
+  episode_run_time: number[]
+  first_air_date: string
+  genres: Array<{ id: number; name: string }>
+  homepage: string
+  id: number
+  in_production: boolean
+  languages: string[]
+  last_air_date: string
+  last_episode_to_air: TmdbEpisodeSummary | null
+  name: string
+  networks: Array<{
+    id: number
+    logo_path: string | null
+    name: string
+    origin_country: string
+  }>
+  next_episode_to_air: TmdbEpisodeSummary | null
+  number_of_episodes: number
+  number_of_seasons: number
+  origin_country: string[]
+  original_language: string
+  original_name: string
+  overview: string
+  popularity: number
+  poster_path: string | null
+  production_companies: Array<{
+    id: number
+    logo_path: string | null
+    name: string
+    origin_country: string
+  }>
+  production_countries: Array<{ iso_3166_1: string; name: string }>
+  seasons: Array<{
+    air_date: string
+    episode_count: number
+    id: number
+    name: string
+    overview: string
+    poster_path: string | null
+    season_number: number
+    vote_average: number
+  }>
+  spoken_languages: Array<{
+    english_name: string
+    iso_639_1: string
+    name: string
+  }>
+  status: string
+  tagline: string
+  type: string
+  vote_average: number
+  vote_count: number
+  external_ids?: TmdbExternalIds
+}
+
+export type TmdbEpisodeSummary = {
+  air_date: string
+  episode_number: number
+  episode_type?: string
+  id: number
+  name: string
+  overview: string
+  production_code?: string
+  runtime: number | null
+  season_number: number
+  show_id: number
+  still_path: string | null
+  vote_average: number
+  vote_count: number
+}
+
+// ── TV Episode Details ── GET /3/tv/{id}/season/{n}/episode/{n} ──────
+
+export type TmdbEpisodeDetailsResponse = {
+  air_date: string
+  episode_number: number
+  id: number
+  name: string
+  overview: string
+  production_code: string
+  runtime: number | null
+  season_number: number
+  still_path: string | null
+  vote_average: number
+  vote_count: number
+  crew: Array<{
+    id: number
+    name: string
+    job: string
+    department: string
+    profile_path: string | null
+  }>
+  guest_stars: Array<{
+    id: number
+    name: string
+    character: string
+    order: number
+    profile_path: string | null
+  }>
+}
+
+// ── Find by External ID ── GET /3/find/{external_id} ─────────────────
+
+export type TmdbFindByIdResponse = {
+  movie_results: TmdbSearchMovieResult[]
+  tv_results: TmdbSearchTvResult[]
+  person_results: unknown[]
+  tv_episode_results: unknown[]
+  tv_season_results: unknown[]
+}
+
+// ── External IDs (append_to_response=external_ids) ───────────────────
+
+export type TmdbExternalIds = {
+  imdb_id: string | null
+  facebook_id: string | null
+  instagram_id: string | null
+  twitter_id: string | null
+  wikidata_id: string | null
+  freebase_id?: string | null
+  freebase_mid?: string | null
+  tvdb_id?: number | null
+  tvrage_id?: number | null
+}
diff --git a/service/src/app-models/media/metadata-services/tmdb-client-service.ts b/service/src/app-models/media/metadata-services/tmdb-client-service.ts
new file mode 100644
index 00000000..a161f230
--- /dev/null
+++ b/service/src/app-models/media/metadata-services/tmdb-client-service.ts
@@ -0,0 +1,423 @@
+import { useSystemIdentityContext } from '@furystack/core'
+import { Injectable, Injected, type Injector } from '@furystack/inject'
+import type { ScopedLogger } from '@furystack/logging'
+import { getLogger } from '@furystack/logging'
+import { getDataSetFor, type DataSet } from '@furystack/repository'
+import { Semaphore, sleepAsync } from '@furystack/utils'
+import type { TmdbConfig, PiRatFile } from 'common'
+import { Config } from 'common'
+
+import type {
+  TmdbMovieDetailsResponse,
+  TmdbTvDetailsResponse,
+  TmdbEpisodeDetailsResponse,
+  TmdbFindByIdResponse,
+  TmdbPaginatedResponse,
+  TmdbSearchMovieResult,
+  TmdbSearchTvResult,
+} from './tmdb-api-types.js'
+
+export type TmdbFetchResult<T> =
+  | { status: 'success'; data: T }
+  | { status: 'not-found' }
+  | { status: 'rate-limited' }
+  | { status: 'not-configured' }
+  | { status: 'error'; error: unknown }
+
+const MAX_RETRIES = 3
+const INITIAL_BACKOFF_MS = 2_000
+const MAX_BACKOFF_MS = 30_000
+const TMDB_BASE_URL = 'https://api.themoviedb.org/3'
+const TMDB_IMAGE_BASE_URL = 'https://image.tmdb.org/t/p'
+const DEFAULT_POSTER_SIZE = 'w500'
+
+export const buildTmdbImageUrl = (path: string | null, size = DEFAULT_POSTER_SIZE): string | undefined => {
+  if (!path) return undefined
+  return `${TMDB_IMAGE_BASE_URL}/${size}${path}`
+}
+
+@Injectable({ lifetime: 'singleton' })
+export class TmdbClientService {
+  public config?: TmdbConfig
+
+  @Injected((injector) => getLogger(injector).withScope('TMDB Client Service'))
+  declare private logger: ScopedLogger
+
+  @Injected((injector) => getDataSetFor(injector, Config, 'id'))
+  declare private configDataSet: DataSet<Config, 'id'>
+
+  @Injected((injector) => useSystemIdentityContext({ injector, username: 'tmdb-service' }))
+  declare private systemInjector: Injector
+
+  private readonly semaphore = new Semaphore(1)
+
+  public init() {
+    void this.initAsync().catch((error) => {
+      void this.logger.error({ message: 'Failed to initialize TMDB Client Service', data: { error } })
+    })
+  }
+
+  private configSubscriptions: Disposable[] = []
+
+  private async initAsync() {
+    for (const sub of this.configSubscriptions) {
+      sub[Symbol.dispose]()
+    }
+    this.configSubscriptions = []
+
+    const config = await this.configDataSet.get(this.systemInjector, 'TMDB_CONFIG')
+    if (!config) {
+      this.config = undefined
+      await this.logger.information({
+        message: '🚫   No config found, TMDB Service will not be initialized',
+      })
+    } else {
+      this.config = config as TmdbConfig
+      await this.logger.verbose({
+        message: '✅   TMDB Service initialized',
+      })
+    }
+
+    this.configSubscriptions.push(
+      this.configDataSet.subscribe('onEntityAdded', ({ entity }) => {
+        if (entity.id === 'TMDB_CONFIG') {
+          this.config = entity as TmdbConfig
+          void this.logger.information({
+            message: `🎬   TMDB Service config added`,
+          })
+        }
+      }),
+      this.configDataSet.subscribe('onEntityUpdated', ({ change }) => {
+        if (change.id === 'TMDB_CONFIG') {
+          this.config = {
+            ...this.config,
+            ...change,
+          } as TmdbConfig
+          void this.logger.information({
+            message: `🎬   TMDB Service config updated`,
+            data: change,
+          })
+        }
+      }),
+      this.configDataSet.subscribe('onEntityRemoved', ({ key }) => {
+        if (key === 'TMDB_CONFIG') {
+          this.config = undefined
+          void this.logger.information({
+            message: '🚫   TMDB Service config removed, service will not be able to fetch metadata',
+          })
+        }
+      }),
+    )
+  }
+
+  private async fetchJson<T>(
+    path: string,
+    context: { file?: PiRatFile; description: string },
+  ): Promise<TmdbFetchResult<T>> {
+    if (!this.config) {
+      return { status: 'not-configured' }
+    }
+
+    let backoffMs = INITIAL_BACKOFF_MS
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      const response = await fetch(`${TMDB_BASE_URL}${path}`, {
+        headers: {
+          Authorization: `Bearer ${this.config.value.apiKey}`,
+          Accept: 'application/json',
+        },
+      })
+
+      if (response.status === 429) {
+        if (attempt < MAX_RETRIES) {
+          const retryAfter = response.headers.get('Retry-After')
+          const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : backoffMs
+          await this.logger.warning({
+            message: `⏳  TMDB rate limit reached for ${context.description}, retrying in ${waitMs}ms (attempt ${attempt + 1}/${MAX_RETRIES})`,
+            data: { file: context.file },
+          })
+          await sleepAsync(waitMs)
+          backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS)
+          continue
+        }
+        return { status: 'rate-limited' }
+      }
+
+      if (response.status === 404) {
+        return { status: 'not-found' }
+      }
+
+      if (!response.ok) {
+        return { status: 'error', error: new Error(`HTTP ${response.status}: ${response.statusText}`) }
+      }
+
+      const body = (await response.json()) as T
+      return { status: 'success', data: body }
+    }
+
+    return { status: 'rate-limited' }
+  }
+
+  // ── Low-level endpoint methods ─────────────────────────────────────
+
+  public async searchMovie(
+    title: string,
+    options?: { year?: number; language?: string },
+  ): Promise<TmdbFetchResult<TmdbPaginatedResponse<TmdbSearchMovieResult>>> {
+    const params = new URLSearchParams({
+      query: title,
+      language: options?.language ?? this.config?.value.defaultLanguage ?? 'en-US',
+    })
+    if (options?.year) params.set('year', String(options.year))
+
+    return this.semaphore.execute(() =>
+      this.fetchJson(`/search/movie?${params}`, { description: `search movie '${title}'` }),
+    )
+  }
+
+  public async searchTv(
+    title: string,
+    options?: { language?: string },
+  ): Promise<TmdbFetchResult<TmdbPaginatedResponse<TmdbSearchTvResult>>> {
+    const params = new URLSearchParams({
+      query: title,
+      language: options?.language ?? this.config?.value.defaultLanguage ?? 'en-US',
+    })
+
+    return this.semaphore.execute(() => this.fetchJson(`/search/tv?${params}`, { description: `search tv '${title}'` }))
+  }
+
+  public async getMovieDetails(
+    tmdbId: number,
+    options?: { language?: string },
+  ): Promise<TmdbFetchResult<TmdbMovieDetailsResponse>> {
+    const params = new URLSearchParams({
+      language: options?.language ?? this.config?.value.defaultLanguage ?? 'en-US',
+      append_to_response: 'external_ids',
+    })
+
+    return this.semaphore.execute(() =>
+      this.fetchJson(`/movie/${tmdbId}?${params}`, { description: `movie details #${tmdbId}` }),
+    )
+  }
+
+  public async getTvDetails(
+    tmdbId: number,
+    options?: { language?: string },
+  ): Promise<TmdbFetchResult<TmdbTvDetailsResponse>> {
+    const params = new URLSearchParams({
+      language: options?.language ?? this.config?.value.defaultLanguage ?? 'en-US',
+      append_to_response: 'external_ids',
+    })
+
+    return this.semaphore.execute(() =>
+      this.fetchJson(`/tv/${tmdbId}?${params}`, { description: `tv details #${tmdbId}` }),
+    )
+  }
+
+  public async getEpisodeDetails(
+    tvId: number,
+    seasonNumber: number,
+    episodeNumber: number,
+    options?: { language?: string },
+  ): Promise<TmdbFetchResult<TmdbEpisodeDetailsResponse>> {
+    const params = new URLSearchParams({
+      language: options?.language ?? this.config?.value.defaultLanguage ?? 'en-US',
+    })
+
+    return this.semaphore.execute(() =>
+      this.fetchJson(`/tv/${tvId}/season/${seasonNumber}/episode/${episodeNumber}?${params}`, {
+        description: `episode S${seasonNumber}E${episodeNumber} of tv #${tvId}`,
+      }),
+    )
+  }
+
+  public async findByImdbId(imdbId: string): Promise<TmdbFetchResult<TmdbFindByIdResponse>> {
+    const params = new URLSearchParams({
+      external_source: 'imdb_id',
+      language: this.config?.value.defaultLanguage ?? 'en-US',
+    })
+
+    return this.semaphore.execute(() =>
+      this.fetchJson(`/find/${imdbId}?${params}`, { description: `find by IMDB ID '${imdbId}'` }),
+    )
+  }
+
+  // ── High-level orchestration methods ───────────────────────────────
+
+  /**
+   * Searches for a movie or episode on TMDB by title, year, season, and episode.
+   * For episodes (season+episode present): searches TV -> fetches series -> fetches episode.
+   * For movies: searches movie -> fetches details.
+   * Skips results without an imdb_id (D1).
+   */
+  public async fetchTmdbMovieMetadata(
+    {
+      title,
+      year,
+      season,
+      episode,
+    }: {
+      title: string
+      year?: number
+      season?: number
+      episode?: number
+    },
+    context?: { file?: PiRatFile },
+  ): Promise<
+    TmdbFetchResult<{
+      movie: TmdbMovieDetailsResponse
+      episode?: TmdbEpisodeDetailsResponse
+      series?: TmdbTvDetailsResponse
+    }>
+  > {
+    if (!this.config) {
+      return { status: 'not-configured' }
+    }
+
+    try {
+      if (season != null && episode != null) {
+        return await this.fetchEpisodeMetadata({ title, season, episode }, context)
+      }
+      return await this.fetchMovieOnlyMetadata({ title, year }, context)
+    } catch (error) {
+      await this.logger.warning({
+        message: `❗  Failed to fetch TMDB metadata for '${title}'`,
+        data: { error, title, year, season, episode, file: context?.file },
+      })
+      return { status: 'error', error }
+    }
+  }
+
+  private async fetchEpisodeMetadata(
+    { title, season, episode }: { title: string; season: number; episode: number },
+    context?: { file?: PiRatFile },
+  ): Promise<
+    TmdbFetchResult<{
+      movie: TmdbMovieDetailsResponse
+      episode?: TmdbEpisodeDetailsResponse
+      series?: TmdbTvDetailsResponse
+    }>
+  > {
+    const searchResult = await this.searchTv(title)
+    if (searchResult.status !== 'success') return searchResult
+    if (searchResult.data.results.length === 0) return { status: 'not-found' }
+
+    const tvId = searchResult.data.results[0].id
+    const tvResult = await this.getTvDetails(tvId)
+    if (tvResult.status !== 'success') return tvResult
+
+    const imdbId = tvResult.data.external_ids?.imdb_id
+    if (!imdbId) {
+      await this.logger.debug({
+        message: `TMDB TV #${tvId} has no IMDB ID, skipping (D1)`,
+        data: { file: context?.file },
+      })
+      return { status: 'not-found' }
+    }
+
+    const episodeResult = await this.getEpisodeDetails(tvId, season, episode)
+    if (episodeResult.status !== 'success') return episodeResult
+
+    // Build a synthetic TmdbMovieDetailsResponse from series+episode data
+    // so the caller gets a consistent shape for ensureMovieExists
+    const syntheticMovie: TmdbMovieDetailsResponse = {
+      adult: tvResult.data.adult,
+      backdrop_path: episodeResult.data.still_path,
+      belongs_to_collection: null,
+      budget: 0,
+      genres: tvResult.data.genres,
+      homepage: '',
+      id: episodeResult.data.id,
+      imdb_id: imdbId,
+      origin_country: tvResult.data.origin_country,
+      original_language: tvResult.data.original_language,
+      original_title: episodeResult.data.name,
+      overview: episodeResult.data.overview,
+      popularity: 0,
+      poster_path: tvResult.data.poster_path,
+      production_companies: [],
+      production_countries: [],
+      release_date: episodeResult.data.air_date,
+      revenue: 0,
+      runtime: episodeResult.data.runtime ?? 0,
+      spoken_languages: [],
+      status: 'Released',
+      tagline: '',
+      title: episodeResult.data.name,
+      video: false,
+      vote_average: episodeResult.data.vote_average,
+      vote_count: episodeResult.data.vote_count,
+    }
+
+    return {
+      status: 'success',
+      data: {
+        movie: syntheticMovie,
+        episode: episodeResult.data,
+        series: tvResult.data,
+      },
+    }
+  }
+
+  private async fetchMovieOnlyMetadata(
+    { title, year }: { title: string; year?: number },
+    context?: { file?: PiRatFile },
+  ): Promise<
+    TmdbFetchResult<{
+      movie: TmdbMovieDetailsResponse
+      episode?: TmdbEpisodeDetailsResponse
+      series?: TmdbTvDetailsResponse
+    }>
+  > {
+    const searchResult = await this.searchMovie(title, { year })
+    if (searchResult.status !== 'success') return searchResult
+    if (searchResult.data.results.length === 0) return { status: 'not-found' }
+
+    const movieId = searchResult.data.results[0].id
+    const detailResult = await this.getMovieDetails(movieId)
+    if (detailResult.status !== 'success') return detailResult
+
+    const imdbId = detailResult.data.imdb_id ?? detailResult.data.external_ids?.imdb_id
+    if (!imdbId) {
+      await this.logger.debug({
+        message: `TMDB movie #${movieId} has no IMDB ID, skipping (D1)`,
+        data: { file: context?.file },
+      })
+      return { status: 'not-found' }
+    }
+
+    return {
+      status: 'success',
+      data: { movie: { ...detailResult.data, imdb_id: imdbId } },
+    }
+  }
+
+  /**
+   * Fetches series metadata from TMDB using an IMDB ID.
+   * Uses /find to bridge IMDB -> TMDB, then fetches full TV details.
+   */
+  public async fetchTmdbSeriesMetadata(
+    { imdbId }: { imdbId: string },
+    context?: { file?: PiRatFile },
+  ): Promise<TmdbFetchResult<TmdbTvDetailsResponse>> {
+    if (!this.config) {
+      return { status: 'not-configured' }
+    }
+
+    try {
+      const findResult = await this.findByImdbId(imdbId)
+      if (findResult.status !== 'success') return findResult
+      if (findResult.data.tv_results.length === 0) return { status: 'not-found' }
+
+      const tmdbId = findResult.data.tv_results[0].id
+      return await this.getTvDetails(tmdbId)
+    } catch (error) {
+      await this.logger.warning({
+        message: `❗  Failed to fetch TMDB Series metadata for '${imdbId}'`,
+        data: { error, imdbId, file: context?.file },
+      })
+      return { status: 'error', error }
+    }
+  }
+}
diff --git a/service/src/app-models/media/setup-media-api.ts b/service/src/app-models/media/setup-media-api.ts
index 73ed35c7..c9506c07 100644
--- a/service/src/app-models/media/setup-media-api.ts
+++ b/service/src/app-models/media/setup-media-api.ts
@@ -11,7 +11,18 @@ import {
   useRestService,
 } from '@furystack/rest-service'
 import type { MediaApi } from 'common'
-import { Movie, MovieFile, OmdbMovieMetadata, OmdbSeriesMetadata, Series, WatchHistoryEntry } from 'common'
+import {
+  Movie,
+  MovieFile,
+  MovieMetadataLocalized,
+  OmdbMovieMetadata,
+  OmdbSeriesMetadata,
+  Series,
+  SeriesMetadataLocalized,
+  TmdbMovieMetadata,
+  TmdbSeriesMetadata,
+  WatchHistoryEntry,
+} from 'common'
 import mediaApiSchema from 'common/schemas/media-api.json' with { type: 'json' }
 import { getCorsOptions } from '../../get-cors-options.js'
 import { getPort } from '../../get-port.js'
@@ -80,6 +91,38 @@ export const setupMediaRestApi = async (injector: Injector) => {
           schema: mediaApiSchema,
           schemaName: 'GetEntityEndpoint<OmdbSeriesMetadata,"imdbID">',
         })(createGetEntityEndpoint({ model: OmdbSeriesMetadata, primaryKey: 'imdbID' })),
+        '/tmdb-movie-metadata': Validate({
+          schema: mediaApiSchema,
+          schemaName: 'GetCollectionEndpoint<TmdbMovieMetadata>',
+        })(createGetCollectionEndpoint({ model: TmdbMovieMetadata, primaryKey: 'id' })),
+        '/tmdb-movie-metadata/:id': Validate({
+          schema: mediaApiSchema,
+          schemaName: 'GetEntityEndpoint<TmdbMovieMetadata,"id">',
+        })(createGetEntityEndpoint({ model: TmdbMovieMetadata, primaryKey: 'id' })),
+        '/tmdb-series-metadata': Validate({
+          schema: mediaApiSchema,
+          schemaName: 'GetCollectionEndpoint<TmdbSeriesMetadata>',
+        })(createGetCollectionEndpoint({ model: TmdbSeriesMetadata, primaryKey: 'id' })),
+        '/tmdb-series-metadata/:id': Validate({
+          schema: mediaApiSchema,
+          schemaName: 'GetEntityEndpoint<TmdbSeriesMetadata,"id">',
+        })(createGetEntityEndpoint({ model: TmdbSeriesMetadata, primaryKey: 'id' })),
+        '/movie-metadata-localized': Validate({
+          schema: mediaApiSchema,
+          schemaName: 'GetCollectionEndpoint<MovieMetadataLocalized>',
+        })(createGetCollectionEndpoint({ model: MovieMetadataLocalized, primaryKey: 'id' })),
+        '/movie-metadata-localized/:id': Validate({
+          schema: mediaApiSchema,
+          schemaName: 'GetEntityEndpoint<MovieMetadataLocalized,"id">',
+        })(createGetEntityEndpoint({ model: MovieMetadataLocalized, primaryKey: 'id' })),
+        '/series-metadata-localized': Validate({
+          schema: mediaApiSchema,
+          schemaName: 'GetCollectionEndpoint<SeriesMetadataLocalized>',
+        })(createGetCollectionEndpoint({ model: SeriesMetadataLocalized, primaryKey: 'id' })),
+        '/series-metadata-localized/:id': Validate({
+          schema: mediaApiSchema,
+          schemaName: 'GetEntityEndpoint<SeriesMetadataLocalized,"id">',
+        })(createGetEntityEndpoint({ model: SeriesMetadataLocalized, primaryKey: 'id' })),
         '/movie-files': Validate({ schema: mediaApiSchema, schemaName: 'GetCollectionEndpoint<MovieFile>' })(
           createGetCollectionEndpoint({ model: MovieFile, primaryKey: 'id' }),
         ),
diff --git a/service/src/app-models/media/setup-media.spec.ts b/service/src/app-models/media/setup-media.spec.ts
index 33b7905e..e1e19c04 100644
--- a/service/src/app-models/media/setup-media.spec.ts
+++ b/service/src/app-models/media/setup-media.spec.ts
@@ -36,7 +36,6 @@ const createMovieFile = (overrides: Partial<MovieFile> = {}): MovieFile =>
 const createMovie = (overrides: Partial<Movie> = {}): Movie =>
   ({
     imdbId: 'tt1234567',
-    title: 'Test Movie',
     ...overrides,
   }) as Movie
 
diff --git a/service/src/app-models/media/setup-media.ts b/service/src/app-models/media/setup-media.ts
index 7948be99..9425dd13 100644
--- a/service/src/app-models/media/setup-media.ts
+++ b/service/src/app-models/media/setup-media.ts
@@ -2,7 +2,18 @@ import type { Injector } from '@furystack/inject'
 import type { ScopedLogger } from '@furystack/logging'
 import { getLogger } from '@furystack/logging'
 
-import { Movie, MovieFile, OmdbMovieMetadata, OmdbSeriesMetadata, Series, WatchHistoryEntry } from 'common'
+import {
+  Movie,
+  MovieFile,
+  MovieMetadataLocalized,
+  OmdbMovieMetadata,
+  OmdbSeriesMetadata,
+  Series,
+  SeriesMetadataLocalized,
+  TmdbMovieMetadata,
+  TmdbSeriesMetadata,
+  WatchHistoryEntry,
+} from 'common'
 
 import { getCurrentUser, isAuthorized } from '@furystack/core'
 import type { AuthorizationResult, DataSet } from '@furystack/repository'
@@ -17,16 +28,13 @@ import type { FfprobeResult } from '../../ffprobe-service.js'
 import { getDefaultDbSettings } from '../../get-default-db-options.js'
 import { WebsocketService } from '../../websocket-service.js'
 import { OmdbClientService } from './metadata-services/omdb-client-service.js'
+import { TmdbClientService } from './metadata-services/tmdb-client-service.js'
 import { useMovieFileMaintainer } from './services/movie-file-maintainer.js'
 
 class MovieModel extends Model<Movie, Movie> implements Movie {
-  declare title: string
   declare imdbId: string
   declare year?: number | undefined
   declare duration?: number | undefined
-  declare genre?: string[] | undefined
-  declare thumbnailImageUrl?: string | undefined
-  declare plot?: string | undefined
   declare type?: 'episode' | 'movie' | undefined
   declare seriesId?: string | undefined
   declare season?: number | undefined
@@ -59,10 +67,8 @@ class WatchHistoryEntryModel extends Model<WatchHistoryEntry, WatchHistoryEntry>
 
 class SeriesModel extends Model<Series, Series> implements Series {
   declare imdbId: string
-  declare title: string
   declare year: string
-  declare thumbnailImageUrl?: string | undefined
-  declare plot: string
+  declare numberOfSeasons?: number | undefined
   declare createdAt: string
   declare updatedAt: string
 }
@@ -127,6 +133,87 @@ class OmdbSeriesMetadataModel extends Model<OmdbSeriesMetadata, OmdbSeriesMetada
   declare updatedAt: string
 }
 
+class TmdbMovieMetadataModel extends Model<TmdbMovieMetadata, TmdbMovieMetadata> implements TmdbMovieMetadata {
+  declare id: number
+  declare imdbId?: string
+  declare title: string
+  declare originalTitle: string
+  declare overview: string
+  declare releaseDate?: string
+  declare runtime?: number
+  declare posterPath?: string
+  declare backdropPath?: string
+  declare genres: Array<{ id: number; name: string }>
+  declare voteAverage?: number
+  declare voteCount?: number
+  declare popularity?: number
+  declare originalLanguage: string
+  declare spokenLanguages?: Array<{ iso_639_1: string; name: string }>
+  declare productionCountries?: Array<{ iso_3166_1: string; name: string }>
+  declare status?: string
+  declare tagline?: string
+  declare budget?: number
+  declare revenue?: number
+  declare language: string
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+class TmdbSeriesMetadataModel extends Model<TmdbSeriesMetadata, TmdbSeriesMetadata> implements TmdbSeriesMetadata {
+  declare id: number
+  declare imdbId?: string
+  declare name: string
+  declare originalName: string
+  declare overview: string
+  declare firstAirDate?: string
+  declare posterPath?: string
+  declare backdropPath?: string
+  declare genres: Array<{ id: number; name: string }>
+  declare voteAverage?: number
+  declare voteCount?: number
+  declare numberOfSeasons?: number
+  declare numberOfEpisodes?: number
+  declare status?: string
+  declare originalLanguage: string
+  declare languages?: string[]
+  declare language: string
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+class MovieMetadataLocalizedModel
+  extends Model<MovieMetadataLocalized, MovieMetadataLocalized>
+  implements MovieMetadataLocalized
+{
+  declare id: string
+  declare movieImdbId: string
+  declare language: string
+  declare title: string
+  declare plot?: string
+  declare posterUrl?: string
+  declare genre?: string[]
+  declare source: 'omdb' | 'tmdb'
+  declare sourceId?: string
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+class SeriesMetadataLocalizedModel
+  extends Model<SeriesMetadataLocalized, SeriesMetadataLocalized>
+  implements SeriesMetadataLocalized
+{
+  declare id: string
+  declare seriesImdbId: string
+  declare language: string
+  declare title: string
+  declare plot?: string
+  declare posterUrl?: string
+  declare source: 'omdb' | 'tmdb'
+  declare sourceId?: string
+  declare createdAt: string
+  declare updatedAt: string
+}
+
 export const announceMovieFileAdded = async ({
   entity,
   injector,
@@ -179,10 +266,6 @@ export const setupMedia = async (injector: Injector) => {
             allowNull: false,
             primaryKey: true,
           },
-          title: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
           duration: {
             type: DataTypes.INTEGER,
             allowNull: true,
@@ -191,10 +274,6 @@ export const setupMedia = async (injector: Injector) => {
             type: DataTypes.INTEGER,
             allowNull: true,
           },
-          genre: {
-            type: DataTypes.JSON, //DataTypes.ARRAY(DataTypes.STRING),
-            allowNull: true,
-          },
           episode: {
             type: DataTypes.INTEGER,
             allowNull: true,
@@ -203,14 +282,6 @@ export const setupMedia = async (injector: Injector) => {
             type: DataTypes.INTEGER,
             allowNull: true,
           },
-          plot: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          thumbnailImageUrl: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
           type: {
             type: DataTypes.ENUM('episode', 'movie'),
             allowNull: true,
@@ -339,22 +410,14 @@ export const setupMedia = async (injector: Injector) => {
             type: DataTypes.STRING,
             primaryKey: true,
           },
-          title: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
           year: {
             type: DataTypes.STRING,
             allowNull: false,
           },
-          thumbnailImageUrl: {
-            type: DataTypes.STRING,
+          numberOfSeasons: {
+            type: DataTypes.INTEGER,
             allowNull: true,
           },
-          plot: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
           createdAt: {
             type: DataTypes.DATE,
             allowNull: false,
@@ -617,6 +680,330 @@ export const setupMedia = async (injector: Injector) => {
     },
   })
 
+  useSequelize({
+    injector,
+    model: TmdbMovieMetadata,
+    sequelizeModel: TmdbMovieMetadataModel,
+    primaryKey: 'id',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      TmdbMovieMetadataModel.init(
+        {
+          id: {
+            type: DataTypes.INTEGER,
+            primaryKey: true,
+            allowNull: false,
+          },
+          imdbId: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          title: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          originalTitle: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          overview: {
+            type: DataTypes.TEXT,
+            allowNull: false,
+          },
+          releaseDate: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          runtime: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          posterPath: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          backdropPath: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          genres: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          voteAverage: {
+            type: DataTypes.FLOAT,
+            allowNull: true,
+          },
+          voteCount: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          popularity: {
+            type: DataTypes.FLOAT,
+            allowNull: true,
+          },
+          originalLanguage: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          spokenLanguages: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          productionCountries: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          status: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          tagline: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          budget: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          revenue: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          language: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        { sequelize, indexes: [{ fields: ['imdbId'] }] },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: TmdbSeriesMetadata,
+    sequelizeModel: TmdbSeriesMetadataModel,
+    primaryKey: 'id',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      TmdbSeriesMetadataModel.init(
+        {
+          id: {
+            type: DataTypes.INTEGER,
+            primaryKey: true,
+            allowNull: false,
+          },
+          imdbId: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          name: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          originalName: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          overview: {
+            type: DataTypes.TEXT,
+            allowNull: false,
+          },
+          firstAirDate: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          posterPath: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          backdropPath: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          genres: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          voteAverage: {
+            type: DataTypes.FLOAT,
+            allowNull: true,
+          },
+          voteCount: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          numberOfSeasons: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          numberOfEpisodes: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          status: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          originalLanguage: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          languages: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          language: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        { sequelize, indexes: [{ fields: ['imdbId'] }] },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: MovieMetadataLocalized,
+    sequelizeModel: MovieMetadataLocalizedModel,
+    primaryKey: 'id',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      MovieMetadataLocalizedModel.init(
+        {
+          id: {
+            type: DataTypes.UUIDV4,
+            primaryKey: true,
+            allowNull: false,
+            defaultValue: () => crypto.randomUUID(),
+          },
+          movieImdbId: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          language: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          title: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          plot: {
+            type: DataTypes.TEXT,
+            allowNull: true,
+          },
+          posterUrl: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          genre: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          source: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          sourceId: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        {
+          sequelize,
+          indexes: [{ fields: ['movieImdbId'] }, { fields: ['movieImdbId', 'language', 'source'], unique: true }],
+        },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: SeriesMetadataLocalized,
+    sequelizeModel: SeriesMetadataLocalizedModel,
+    primaryKey: 'id',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      SeriesMetadataLocalizedModel.init(
+        {
+          id: {
+            type: DataTypes.UUIDV4,
+            primaryKey: true,
+            allowNull: false,
+            defaultValue: () => crypto.randomUUID(),
+          },
+          seriesImdbId: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          language: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          title: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          plot: {
+            type: DataTypes.TEXT,
+            allowNull: true,
+          },
+          posterUrl: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          source: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          sourceId: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        {
+          sequelize,
+          indexes: [{ fields: ['seriesImdbId'] }, { fields: ['seriesImdbId', 'language', 'source'], unique: true }],
+        },
+      )
+    },
+  })
+
   const repo = getRepository(injector)
 
   repo.createDataSet(Movie, 'imdbId', {
@@ -695,9 +1082,39 @@ export const setupMedia = async (injector: Injector) => {
     authorizeRemove: withRole('admin'),
   })
 
+  repo.createDataSet(TmdbMovieMetadata, 'id', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  repo.createDataSet(TmdbSeriesMetadata, 'id', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  repo.createDataSet(MovieMetadataLocalized, 'id', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  repo.createDataSet(SeriesMetadataLocalized, 'id', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
   const omdbClientService = injector.getInstance(OmdbClientService)
+  const tmdbClientService = injector.getInstance(TmdbClientService)
 
   injector.getInstance(ExternalServiceStatusRegistry).register('omdb', () => !!omdbClientService.config)
+  injector.getInstance(ExternalServiceStatusRegistry).register('tmdb', () => !!tmdbClientService.config)
 
   const movieFileDataSet = getDataSetFor(injector, MovieFile, 'id')
   const movieDataSet = getDataSetFor(injector, Movie, 'imdbId')
diff --git a/service/src/app-models/media/utils/ensure-localized-metadata-exists.ts b/service/src/app-models/media/utils/ensure-localized-metadata-exists.ts
new file mode 100644
index 00000000..e50a4ad1
--- /dev/null
+++ b/service/src/app-models/media/utils/ensure-localized-metadata-exists.ts
@@ -0,0 +1,65 @@
+import type { Injector } from '@furystack/inject'
+import { getDataSetFor } from '@furystack/repository'
+import type { MovieMetadataLocalized, SeriesMetadataLocalized } from 'common'
+import {
+  MovieMetadataLocalized as MovieMetadataLocalizedClass,
+  SeriesMetadataLocalized as SeriesMetadataLocalizedClass,
+} from 'common'
+
+export const ensureMovieLocalizedMetadataExists = async (
+  data: Omit<MovieMetadataLocalized, 'id' | 'createdAt' | 'updatedAt'>,
+  injector: Injector,
+) => {
+  const dataSet = getDataSetFor(injector, MovieMetadataLocalizedClass, 'id')
+  const existing = await dataSet.find(injector, {
+    filter: {
+      movieImdbId: { $eq: data.movieImdbId },
+      language: { $eq: data.language },
+      source: { $eq: data.source },
+    },
+    top: 1,
+  })
+
+  if (existing.length > 0) {
+    return existing[0]
+  }
+
+  const {
+    created: [added],
+  } = await dataSet.add(injector, {
+    ...data,
+    id: crypto.randomUUID(),
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  })
+  return added
+}
+
+export const ensureSeriesLocalizedMetadataExists = async (
+  data: Omit<SeriesMetadataLocalized, 'id' | 'createdAt' | 'updatedAt'>,
+  injector: Injector,
+) => {
+  const dataSet = getDataSetFor(injector, SeriesMetadataLocalizedClass, 'id')
+  const existing = await dataSet.find(injector, {
+    filter: {
+      seriesImdbId: { $eq: data.seriesImdbId },
+      language: { $eq: data.language },
+      source: { $eq: data.source },
+    },
+    top: 1,
+  })
+
+  if (existing.length > 0) {
+    return existing[0]
+  }
+
+  const {
+    created: [added],
+  } = await dataSet.add(injector, {
+    ...data,
+    id: crypto.randomUUID(),
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  })
+  return added
+}
diff --git a/service/src/app-models/media/utils/ensure-movie-exists.spec.ts b/service/src/app-models/media/utils/ensure-movie-exists.spec.ts
index d732be1d..f3cfeaac 100644
--- a/service/src/app-models/media/utils/ensure-movie-exists.spec.ts
+++ b/service/src/app-models/media/utils/ensure-movie-exists.spec.ts
@@ -1,7 +1,6 @@
 import { Injector } from '@furystack/inject'
 import { usingAsync } from '@furystack/utils'
 import { describe, expect, it, vi } from 'vitest'
-import type { OmdbMovieMetadata } from 'common'
 import { ensureMovieExists } from './ensure-movie-exists.js'
 
 const mockMovieStoreGet = vi.fn()
@@ -15,43 +14,15 @@ vi.mock('@furystack/repository', () => ({
 }))
 
 describe('ensureMovieExists', () => {
-  const createOmdbMeta = (overrides: Partial<OmdbMovieMetadata> = {}): OmdbMovieMetadata => ({
-    imdbID: 'tt1234567',
-    Title: 'Test Movie',
-    Year: '2024',
-    Type: 'movie',
-    Poster: 'https://example.com/poster.jpg',
-    Plot: 'A test movie plot',
-    Runtime: '120 min',
-    Rated: 'PG-13',
-    Released: '01 Jan 2024',
-    Genre: 'Action',
-    Director: 'Test Director',
-    Writer: 'Test Writer',
-    Actors: 'Actor 1, Actor 2',
-    Language: 'English',
-    Country: 'USA',
-    Awards: 'None',
-    Ratings: [],
-    Metascore: '75',
-    imdbRating: '7.5',
-    imdbVotes: '10000',
-    Response: 'True',
-    createdAt: new Date().toISOString(),
-    updatedAt: new Date().toISOString(),
-    ...overrides,
-  })
-
   it('should return existing movie if found', async () => {
     const existingMovie = {
       imdbId: 'tt1234567',
-      title: 'Test Movie',
       year: 2024,
     }
     mockMovieStoreGet.mockResolvedValue(existingMovie)
 
     await usingAsync(new Injector(), async (injector) => {
-      const result = await ensureMovieExists(createOmdbMeta(), injector)
+      const result = await ensureMovieExists({ imdbId: 'tt1234567', year: 2024, type: 'movie' }, injector)
 
       expect(mockMovieStoreGet).toHaveBeenCalledWith(injector, 'tt1234567')
       expect(mockMovieStoreAdd).not.toHaveBeenCalled()
@@ -62,21 +33,19 @@ describe('ensureMovieExists', () => {
   it('should create new movie if not found', async () => {
     const newMovie = {
       imdbId: 'tt1234567',
-      title: 'Test Movie',
       year: 2024,
     }
     mockMovieStoreGet.mockResolvedValue(null)
     mockMovieStoreAdd.mockResolvedValue({ created: [newMovie] })
 
     await usingAsync(new Injector(), async (injector) => {
-      const result = await ensureMovieExists(createOmdbMeta(), injector)
+      const result = await ensureMovieExists({ imdbId: 'tt1234567', year: 2024, type: 'movie' }, injector)
 
       expect(mockMovieStoreGet).toHaveBeenCalledWith(injector, 'tt1234567')
       expect(mockMovieStoreAdd).toHaveBeenCalledWith(
         injector,
         expect.objectContaining({
           imdbId: 'tt1234567',
-          title: 'Test Movie',
           year: 2024,
           type: 'movie',
         }),
@@ -88,7 +57,6 @@ describe('ensureMovieExists', () => {
   it('should handle series episodes with season and episode', async () => {
     const newMovie = {
       imdbId: 'tt9999999',
-      title: 'Episode Title',
       year: 2024,
       season: 1,
       episode: 5,
@@ -96,17 +64,18 @@ describe('ensureMovieExists', () => {
     mockMovieStoreGet.mockResolvedValue(null)
     mockMovieStoreAdd.mockResolvedValue({ created: [newMovie] })
 
-    const omdbMeta = createOmdbMeta({
-      imdbID: 'tt9999999',
-      Title: 'Episode Title',
-      Season: '1',
-      Episode: '5',
-      Type: 'episode',
-      seriesID: 'tt1111111',
-    })
-
     await usingAsync(new Injector(), async (injector) => {
-      await ensureMovieExists(omdbMeta, injector)
+      await ensureMovieExists(
+        {
+          imdbId: 'tt9999999',
+          year: 2024,
+          season: 1,
+          episode: 5,
+          type: 'episode',
+          seriesId: 'tt1111111',
+        },
+        injector,
+      )
 
       expect(mockMovieStoreAdd).toHaveBeenCalledWith(
         injector,
@@ -121,14 +90,12 @@ describe('ensureMovieExists', () => {
     })
   })
 
-  it('should handle missing runtime', async () => {
+  it('should handle missing duration', async () => {
     mockMovieStoreGet.mockResolvedValue(null)
     mockMovieStoreAdd.mockResolvedValue({ created: [{ imdbId: 'tt1234567' }] })
 
-    const omdbMeta = createOmdbMeta({ Runtime: undefined })
-
     await usingAsync(new Injector(), async (injector) => {
-      await ensureMovieExists(omdbMeta, injector)
+      await ensureMovieExists({ imdbId: 'tt1234567', year: 2024, type: 'movie' }, injector)
 
       expect(mockMovieStoreAdd).toHaveBeenCalledWith(
         injector,
diff --git a/service/src/app-models/media/utils/ensure-movie-exists.ts b/service/src/app-models/media/utils/ensure-movie-exists.ts
index 18c22ff0..3a671b07 100644
--- a/service/src/app-models/media/utils/ensure-movie-exists.ts
+++ b/service/src/app-models/media/utils/ensure-movie-exists.ts
@@ -1,25 +1,32 @@
 import type { Injector } from '@furystack/inject'
 import { getDataSetFor } from '@furystack/repository'
-import { Movie, type OmdbMovieMetadata } from 'common'
+import { Movie } from 'common'
 
-export const ensureMovieExists = async (omdbMeta: OmdbMovieMetadata, injector: Injector) => {
+type MovieInput = {
+  imdbId: string
+  year?: number
+  duration?: number
+  type?: 'movie' | 'episode'
+  seriesId?: string
+  season?: number
+  episode?: number
+}
+
+export const ensureMovieExists = async (input: MovieInput, injector: Injector) => {
   const movieDataSet = getDataSetFor(injector, Movie, 'imdbId')
-  const existingMovie = await movieDataSet.get(injector, omdbMeta.imdbID)
+  const existingMovie = await movieDataSet.get(injector, input.imdbId)
 
   if (!existingMovie) {
     const {
       created: [newMovie],
     } = await movieDataSet.add(injector, {
-      imdbId: omdbMeta.imdbID,
-      title: omdbMeta.Title,
-      year: parseInt(omdbMeta.Year, 10),
-      season: omdbMeta.Season ? parseInt(omdbMeta.Season, 10) : undefined,
-      episode: omdbMeta.Episode ? parseInt(omdbMeta.Episode, 10) : undefined,
-      type: omdbMeta.Type,
-      duration: omdbMeta.Runtime ? parseInt(omdbMeta.Runtime, 10) : undefined,
-      thumbnailImageUrl: omdbMeta.Poster,
-      plot: omdbMeta.Plot,
-      seriesId: omdbMeta.seriesID,
+      imdbId: input.imdbId,
+      year: input.year,
+      duration: input.duration,
+      type: input.type,
+      seriesId: input.seriesId,
+      season: input.season,
+      episode: input.episode,
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     })
diff --git a/service/src/app-models/media/utils/ensure-omdb-series-exists.spec.ts b/service/src/app-models/media/utils/ensure-omdb-series-exists.spec.ts
index 88139212..88054e55 100644
--- a/service/src/app-models/media/utils/ensure-omdb-series-exists.spec.ts
+++ b/service/src/app-models/media/utils/ensure-omdb-series-exists.spec.ts
@@ -28,6 +28,14 @@ vi.mock('./ensure-series-exists.js', () => ({
   ensureSeriesExists: (...args: unknown[]) => mockEnsureSeriesExists(...args) as unknown,
 }))
 
+vi.mock('./ensure-localized-metadata-exists.js', () => ({
+  ensureSeriesLocalizedMetadataExists: vi.fn().mockResolvedValue({}),
+}))
+
+vi.mock('./map-omdb-to-localized.js', () => ({
+  mapOmdbSeriesToLocalized: vi.fn().mockReturnValue({}),
+}))
+
 const { ensureOmdbSeriesExists } = await import('./ensure-omdb-series-exists.js')
 
 const createMeta = (overrides?: Partial<OmdbMovieMetadata>): OmdbMovieMetadata =>
@@ -63,7 +71,12 @@ describe('ensureOmdbSeriesExists', () => {
   })
 
   it('should call ensureSeriesExists with stored result when series is already in database', async () => {
-    const storedSeries = { imdbID: 'tt9999999', Title: 'Stored Series' } as OmdbSeriesMetadata
+    const storedSeries = {
+      imdbID: 'tt9999999',
+      Title: 'Stored Series',
+      Year: '2024',
+      totalSeasons: '3',
+    } as OmdbSeriesMetadata
     mockOmdbSeriesGet.mockResolvedValue(storedSeries)
 
     await usingAsync(createTestInjector(), async (injector) => {
@@ -71,12 +84,20 @@ describe('ensureOmdbSeriesExists', () => {
 
       expect(mockOmdbSeriesGet).toHaveBeenCalled()
       expect(mockFetchOmdbSeriesMetadata).not.toHaveBeenCalled()
-      expect(mockEnsureSeriesExists).toHaveBeenCalledWith(storedSeries, injector)
+      expect(mockEnsureSeriesExists).toHaveBeenCalledWith(
+        { imdbId: 'tt9999999', year: '2024', numberOfSeasons: 3 },
+        injector,
+      )
     })
   })
 
   it('should fetch from OMDB, add to dataset, and call ensureSeriesExists when not stored', async () => {
-    const fetchedSeries = { imdbID: 'tt9999999', Title: 'Fetched Series' } as OmdbSeriesMetadata
+    const fetchedSeries = {
+      imdbID: 'tt9999999',
+      Title: 'Fetched Series',
+      Year: '2023',
+      totalSeasons: '5',
+    } as OmdbSeriesMetadata
     mockOmdbSeriesGet.mockResolvedValue(undefined)
     mockFetchOmdbSeriesMetadata.mockResolvedValue({ status: 'success', data: fetchedSeries })
     mockOmdbSeriesAdd.mockResolvedValue({ created: [fetchedSeries] })
@@ -86,7 +107,10 @@ describe('ensureOmdbSeriesExists', () => {
 
       expect(mockFetchOmdbSeriesMetadata).toHaveBeenCalledWith({ imdbId: 'tt9999999' }, { file: undefined })
       expect(mockOmdbSeriesAdd).toHaveBeenCalledWith(injector, fetchedSeries)
-      expect(mockEnsureSeriesExists).toHaveBeenCalledWith(fetchedSeries, injector)
+      expect(mockEnsureSeriesExists).toHaveBeenCalledWith(
+        { imdbId: 'tt9999999', year: '2023', numberOfSeasons: 5 },
+        injector,
+      )
     })
   })
 
diff --git a/service/src/app-models/media/utils/ensure-omdb-series-exists.ts b/service/src/app-models/media/utils/ensure-omdb-series-exists.ts
index c1ec4ba6..0dd0bc0e 100644
--- a/service/src/app-models/media/utils/ensure-omdb-series-exists.ts
+++ b/service/src/app-models/media/utils/ensure-omdb-series-exists.ts
@@ -4,6 +4,8 @@ import { getDataSetFor } from '@furystack/repository'
 import { OmdbSeriesMetadata, type OmdbMovieMetadata, type PiRatFile } from 'common'
 import { OmdbClientService } from '../metadata-services/omdb-client-service.js'
 import { ensureSeriesExists } from './ensure-series-exists.js'
+import { ensureSeriesLocalizedMetadataExists } from './ensure-localized-metadata-exists.js'
+import { mapOmdbSeriesToLocalized } from './map-omdb-to-localized.js'
 
 export const ensureOmdbSeriesExists = async (
   omdbMeta: OmdbMovieMetadata,
@@ -33,8 +35,24 @@ export const ensureOmdbSeriesExists = async (
     const {
       created: [newAdded],
     } = await omdbSeriesDataSet.add(injector, result.data)
-    await ensureSeriesExists(newAdded, injector)
+    await ensureSeriesExists(
+      {
+        imdbId: newAdded.imdbID,
+        year: newAdded.Year,
+        numberOfSeasons: parseInt(newAdded.totalSeasons, 10) || undefined,
+      },
+      injector,
+    )
+    await ensureSeriesLocalizedMetadataExists(mapOmdbSeriesToLocalized(newAdded), injector)
   } else {
-    await ensureSeriesExists(storedResult, injector)
+    await ensureSeriesExists(
+      {
+        imdbId: storedResult.imdbID,
+        year: storedResult.Year,
+        numberOfSeasons: parseInt(storedResult.totalSeasons, 10) || undefined,
+      },
+      injector,
+    )
+    await ensureSeriesLocalizedMetadataExists(mapOmdbSeriesToLocalized(storedResult), injector)
   }
 }
diff --git a/service/src/app-models/media/utils/ensure-series-exists.ts b/service/src/app-models/media/utils/ensure-series-exists.ts
index d7898c9d..22cf7b22 100644
--- a/service/src/app-models/media/utils/ensure-series-exists.ts
+++ b/service/src/app-models/media/utils/ensure-series-exists.ts
@@ -1,18 +1,22 @@
 import type { Injector } from '@furystack/inject'
 import { getDataSetFor } from '@furystack/repository'
-import { Series, type OmdbSeriesMetadata } from 'common'
+import { Series } from 'common'
 
-export const ensureSeriesExists = async (omdbMeta: OmdbSeriesMetadata, injector: Injector) => {
+type SeriesInput = {
+  imdbId: string
+  year: string
+  numberOfSeasons?: number
+}
+
+export const ensureSeriesExists = async (input: SeriesInput, injector: Injector) => {
   const seriesDataSet = getDataSetFor(injector, Series, 'imdbId')
-  const existingSeries = await seriesDataSet.get(injector, omdbMeta.imdbID)
+  const existingSeries = await seriesDataSet.get(injector, input.imdbId)
 
   if (!existingSeries) {
     await seriesDataSet.add(injector, {
-      imdbId: omdbMeta.imdbID,
-      title: omdbMeta.Title,
-      year: omdbMeta.Year,
-      thumbnailImageUrl: omdbMeta.Poster,
-      plot: omdbMeta.Plot,
+      imdbId: input.imdbId,
+      year: input.year,
+      numberOfSeasons: input.numberOfSeasons,
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     })
diff --git a/service/src/app-models/media/utils/ensure-tmdb-movie-exists.ts b/service/src/app-models/media/utils/ensure-tmdb-movie-exists.ts
new file mode 100644
index 00000000..d35423e6
--- /dev/null
+++ b/service/src/app-models/media/utils/ensure-tmdb-movie-exists.ts
@@ -0,0 +1,45 @@
+import type { Injector } from '@furystack/inject'
+import { getDataSetFor } from '@furystack/repository'
+import { TmdbMovieMetadata } from 'common'
+
+import type { TmdbMovieDetailsResponse } from '../metadata-services/tmdb-api-types.js'
+
+export const ensureTmdbMovieExists = async (
+  tmdbMovie: TmdbMovieDetailsResponse,
+  language: string,
+  injector: Injector,
+) => {
+  const dataSet = getDataSetFor(injector, TmdbMovieMetadata, 'id')
+  const existing = await dataSet.get(injector, tmdbMovie.id)
+  if (existing) {
+    return existing
+  }
+  const {
+    created: [added],
+  } = await dataSet.add(injector, {
+    id: tmdbMovie.id,
+    imdbId: tmdbMovie.imdb_id ?? undefined,
+    title: tmdbMovie.title,
+    originalTitle: tmdbMovie.original_title,
+    overview: tmdbMovie.overview,
+    releaseDate: tmdbMovie.release_date || undefined,
+    runtime: tmdbMovie.runtime || undefined,
+    posterPath: tmdbMovie.poster_path ?? undefined,
+    backdropPath: tmdbMovie.backdrop_path ?? undefined,
+    genres: tmdbMovie.genres,
+    voteAverage: tmdbMovie.vote_average,
+    voteCount: tmdbMovie.vote_count,
+    popularity: tmdbMovie.popularity,
+    originalLanguage: tmdbMovie.original_language,
+    spokenLanguages: tmdbMovie.spoken_languages,
+    productionCountries: tmdbMovie.production_countries,
+    status: tmdbMovie.status || undefined,
+    tagline: tmdbMovie.tagline || undefined,
+    budget: tmdbMovie.budget || undefined,
+    revenue: tmdbMovie.revenue || undefined,
+    language,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  })
+  return added
+}
diff --git a/service/src/app-models/media/utils/ensure-tmdb-series-exists.ts b/service/src/app-models/media/utils/ensure-tmdb-series-exists.ts
new file mode 100644
index 00000000..3a180869
--- /dev/null
+++ b/service/src/app-models/media/utils/ensure-tmdb-series-exists.ts
@@ -0,0 +1,97 @@
+import type { Injector } from '@furystack/inject'
+import { getLogger } from '@furystack/logging'
+import { getDataSetFor } from '@furystack/repository'
+import { TmdbSeriesMetadata, type PiRatFile } from 'common'
+
+import type { TmdbTvDetailsResponse } from '../metadata-services/tmdb-api-types.js'
+import { TmdbClientService } from '../metadata-services/tmdb-client-service.js'
+import { ensureSeriesExists } from './ensure-series-exists.js'
+import { ensureSeriesLocalizedMetadataExists } from './ensure-localized-metadata-exists.js'
+import { mapTmdbSeriesToLocalized } from './map-tmdb-to-localized.js'
+
+const storeTmdbSeriesMetadata = async (
+  tmdbSeries: TmdbTvDetailsResponse,
+  imdbId: string,
+  language: string,
+  injector: Injector,
+) => {
+  const dataSet = getDataSetFor(injector, TmdbSeriesMetadata, 'id')
+  const existing = await dataSet.get(injector, tmdbSeries.id)
+  if (existing) return existing
+
+  const {
+    created: [added],
+  } = await dataSet.add(injector, {
+    id: tmdbSeries.id,
+    imdbId,
+    name: tmdbSeries.name,
+    originalName: tmdbSeries.original_name,
+    overview: tmdbSeries.overview,
+    firstAirDate: tmdbSeries.first_air_date || undefined,
+    posterPath: tmdbSeries.poster_path ?? undefined,
+    backdropPath: tmdbSeries.backdrop_path ?? undefined,
+    genres: tmdbSeries.genres,
+    voteAverage: tmdbSeries.vote_average,
+    voteCount: tmdbSeries.vote_count,
+    numberOfSeasons: tmdbSeries.number_of_seasons,
+    numberOfEpisodes: tmdbSeries.number_of_episodes,
+    status: tmdbSeries.status || undefined,
+    originalLanguage: tmdbSeries.original_language,
+    languages: tmdbSeries.languages,
+    language,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  })
+  return added
+}
+
+/**
+ * Given an IMDB series ID from a TMDB episode result, fetches and stores the series data via TMDB.
+ */
+export const ensureTmdbSeriesExists = async (
+  seriesImdbId: string,
+  tmdbSeriesData: TmdbTvDetailsResponse | undefined,
+  language: string,
+  injector: Injector,
+  context?: { file?: PiRatFile },
+) => {
+  if (tmdbSeriesData) {
+    await storeTmdbSeriesMetadata(tmdbSeriesData, seriesImdbId, language, injector)
+    await ensureSeriesExists(
+      {
+        imdbId: seriesImdbId,
+        year: tmdbSeriesData.first_air_date?.slice(0, 4) ?? '',
+        numberOfSeasons: tmdbSeriesData.number_of_seasons,
+      },
+      injector,
+    )
+    await ensureSeriesLocalizedMetadataExists(
+      mapTmdbSeriesToLocalized(tmdbSeriesData, seriesImdbId, language),
+      injector,
+    )
+    return
+  }
+
+  const tmdbClientService = injector.getInstance(TmdbClientService)
+  const result = await tmdbClientService.fetchTmdbSeriesMetadata({ imdbId: seriesImdbId }, { file: context?.file })
+  if (result.status !== 'success') {
+    const logger = getLogger(injector).withScope('ensureTmdbSeriesExists')
+    await logger.warning({
+      message: `Could not fetch TMDB series metadata for '${seriesImdbId}' (${result.status})`,
+      data: { seriesImdbId, status: result.status, file: context?.file },
+    })
+    return
+  }
+
+  const imdbId = result.data.external_ids?.imdb_id ?? seriesImdbId
+  await storeTmdbSeriesMetadata(result.data, imdbId, language, injector)
+  await ensureSeriesExists(
+    {
+      imdbId,
+      year: result.data.first_air_date?.slice(0, 4) ?? '',
+      numberOfSeasons: result.data.number_of_seasons,
+    },
+    injector,
+  )
+  await ensureSeriesLocalizedMetadataExists(mapTmdbSeriesToLocalized(result.data, imdbId, language), injector)
+}
diff --git a/service/src/app-models/media/utils/link-movie.spec.ts b/service/src/app-models/media/utils/link-movie.spec.ts
index 347a9e97..797b6200 100644
--- a/service/src/app-models/media/utils/link-movie.spec.ts
+++ b/service/src/app-models/media/utils/link-movie.spec.ts
@@ -4,6 +4,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type { PiRatFile } from 'common'
 import { FfprobeService } from '../../../ffprobe-service.js'
 import { OmdbClientService } from '../metadata-services/omdb-client-service.js'
+import { TmdbClientService } from '../metadata-services/tmdb-client-service.js'
 import { linkMovie } from './link-movie.js'
 
 const mockMovieFileStoreFind = vi.fn()
@@ -24,6 +25,11 @@ vi.mock('@furystack/repository', () => ({
         find: (...args: unknown[]) => mockOmdbStoreFind(...args) as unknown,
       }
     }
+    if (name === 'Config') {
+      return {
+        get: vi.fn().mockResolvedValue(null),
+      }
+    }
     return {}
   },
 }))
@@ -39,7 +45,7 @@ vi.mock('@furystack/logging', () => ({
 }))
 
 vi.mock('./ensure-movie-exists.js', () => ({
-  ensureMovieExists: vi.fn().mockResolvedValue({ imdbId: 'tt1234567', title: 'Test Movie' }),
+  ensureMovieExists: vi.fn().mockResolvedValue({ imdbId: 'tt1234567' }),
 }))
 
 vi.mock('./ensure-omdb-movie-exists.js', () => ({
@@ -50,8 +56,30 @@ vi.mock('./ensure-omdb-series-exists.js', () => ({
   ensureOmdbSeriesExists: vi.fn().mockResolvedValue(undefined),
 }))
 
+vi.mock('./ensure-tmdb-movie-exists.js', () => ({
+  ensureTmdbMovieExists: vi.fn().mockResolvedValue({}),
+}))
+
+vi.mock('./ensure-tmdb-series-exists.js', () => ({
+  ensureTmdbSeriesExists: vi.fn().mockResolvedValue(undefined),
+}))
+
+vi.mock('./ensure-localized-metadata-exists.js', () => ({
+  ensureMovieLocalizedMetadataExists: vi.fn().mockResolvedValue({}),
+  ensureSeriesLocalizedMetadataExists: vi.fn().mockResolvedValue({}),
+}))
+
+vi.mock('./map-omdb-to-localized.js', () => ({
+  mapOmdbMovieToLocalized: vi.fn().mockReturnValue({}),
+}))
+
+vi.mock('./map-tmdb-to-localized.js', () => ({
+  mapTmdbMovieToLocalized: vi.fn().mockReturnValue({}),
+}))
+
 const mockGetFfprobeForPiratFile = vi.fn().mockResolvedValue({ duration: 7200 })
 const mockFetchOmdbMovieMetadata = vi.fn()
+const mockFetchTmdbMovieMetadata = vi.fn()
 
 describe('linkMovie', () => {
   beforeEach(() => {
@@ -76,6 +104,11 @@ describe('linkMovie', () => {
       OmdbClientService,
     )
 
+    injector.setExplicitInstance(
+      { fetchTmdbMovieMetadata: mockFetchTmdbMovieMetadata, config: undefined } as unknown as TmdbClientService,
+      TmdbClientService,
+    )
+
     return injector
   }
 
@@ -183,6 +216,7 @@ describe('linkMovie', () => {
       mockMovieFileStoreFind.mockResolvedValue([])
       mockOmdbStoreFind.mockResolvedValue([])
       mockFetchOmdbMovieMetadata.mockResolvedValue({ status: 'not-found' })
+      mockFetchTmdbMovieMetadata.mockResolvedValue({ status: 'not-found' })
 
       await usingAsync(createTestInjector(), async (injector) => {
         const result = await linkMovie({
@@ -209,10 +243,11 @@ describe('linkMovie', () => {
       })
     })
 
-    it('should return omdb-not-configured when OMDB is not configured', async () => {
+    it('should return metadata-not-found when all providers are not configured', async () => {
       mockMovieFileStoreFind.mockResolvedValue([])
       mockOmdbStoreFind.mockResolvedValue([])
       mockFetchOmdbMovieMetadata.mockResolvedValue({ status: 'not-configured' })
+      mockFetchTmdbMovieMetadata.mockResolvedValue({ status: 'not-configured' })
 
       await usingAsync(createTestInjector(), async (injector) => {
         const result = await linkMovie({
@@ -220,14 +255,15 @@ describe('linkMovie', () => {
           file: createFile('movies/Another.Movie.2024.mkv'),
         })
 
-        expect(result.status).toBe('omdb-not-configured')
+        expect(result.status).toBe('metadata-not-found')
       })
     })
 
-    it('should return omdb-error when OMDB returns an error', async () => {
+    it('should return metadata-not-found when all providers return errors', async () => {
       mockMovieFileStoreFind.mockResolvedValue([])
       mockOmdbStoreFind.mockResolvedValue([])
       mockFetchOmdbMovieMetadata.mockResolvedValue({ status: 'error', error: new Error('Network failure') })
+      mockFetchTmdbMovieMetadata.mockResolvedValue({ status: 'error', error: new Error('Network failure') })
 
       await usingAsync(createTestInjector(), async (injector) => {
         const result = await linkMovie({
@@ -235,7 +271,7 @@ describe('linkMovie', () => {
           file: createFile('movies/Error.Movie.2024.mkv'),
         })
 
-        expect(result.status).toBe('omdb-error')
+        expect(result.status).toBe('metadata-not-found')
       })
     })
   })
diff --git a/service/src/app-models/media/utils/link-movie.ts b/service/src/app-models/media/utils/link-movie.ts
index a173fe74..fe952202 100644
--- a/service/src/app-models/media/utils/link-movie.ts
+++ b/service/src/app-models/media/utils/link-movie.ts
@@ -2,19 +2,125 @@ import type { Injector } from '@furystack/inject'
 import { getLogger } from '@furystack/logging'
 import { getDataSetFor } from '@furystack/repository'
 import {
+  Config,
   getFallbackMetadata,
   getFileName,
   isMovieFile,
   isSampleFile,
   MovieFile,
   OmdbMovieMetadata,
+  type MetadataProviderConfig,
   type PiRatFile,
 } from 'common'
 import { FfprobeService } from '../../../ffprobe-service.js'
 import { OmdbClientService } from '../metadata-services/omdb-client-service.js'
+import { TmdbClientService } from '../metadata-services/tmdb-client-service.js'
 import { ensureMovieExists } from './ensure-movie-exists.js'
 import { ensureOmdbMovieExists } from './ensure-omdb-movie-exists.js'
 import { ensureOmdbSeriesExists } from './ensure-omdb-series-exists.js'
+import { ensureTmdbMovieExists } from './ensure-tmdb-movie-exists.js'
+import { ensureTmdbSeriesExists } from './ensure-tmdb-series-exists.js'
+import { ensureMovieLocalizedMetadataExists } from './ensure-localized-metadata-exists.js'
+import { mapOmdbMovieToLocalized } from './map-omdb-to-localized.js'
+import { mapTmdbMovieToLocalized } from './map-tmdb-to-localized.js'
+
+type LinkResult =
+  | { status: 'already-linked' }
+  | { status: 'linked'; movieFile: MovieFile; movie: unknown }
+  | { status: 'failed' }
+  | { status: 'not-movie-file' }
+  | { status: 'rate-limited' }
+  | { status: 'metadata-not-found' }
+  | { status: 'provider-not-configured' }
+  | { status: 'provider-error'; error?: unknown }
+
+const getProviderPriority = async (injector: Injector): Promise<Array<'omdb' | 'tmdb'>> => {
+  try {
+    const configDataSet = getDataSetFor(injector, Config, 'id')
+    const config = await configDataSet.get(injector, 'METADATA_PROVIDER_CONFIG')
+    if (config) {
+      return (config as MetadataProviderConfig).value.priority
+    }
+  } catch {
+    // Config not found, use default
+  }
+  return ['omdb', 'tmdb']
+}
+
+const tryOmdbProvider = async (
+  injector: Injector,
+  { title, year, season, episode }: { title: string; year?: number; season?: number; episode?: number },
+  context?: { file?: PiRatFile },
+): Promise<LinkResult | { status: 'skip' }> => {
+  const omdbClientService = injector.getInstance(OmdbClientService)
+  const result = await omdbClientService.fetchOmdbMovieMetadata({ title, year, season, episode }, context)
+
+  if (result.status === 'not-configured') return { status: 'skip' }
+  if (result.status === 'rate-limited') return { status: 'rate-limited' }
+  if (result.status === 'not-found') return { status: 'skip' }
+  if (result.status === 'error') return { status: 'skip' }
+
+  const added = await ensureOmdbMovieExists(result.data, injector)
+  const movie = await ensureMovieExists(
+    {
+      imdbId: added.imdbID,
+      year: parseInt(added.Year, 10),
+      season: added.Season ? parseInt(added.Season, 10) : undefined,
+      episode: added.Episode ? parseInt(added.Episode, 10) : undefined,
+      type: added.Type,
+      duration: added.Runtime ? parseInt(added.Runtime, 10) : undefined,
+      seriesId: added.seriesID,
+    },
+    injector,
+  )
+  await ensureMovieLocalizedMetadataExists(mapOmdbMovieToLocalized(added), injector)
+  await ensureOmdbSeriesExists(added, injector, context)
+
+  return { status: 'linked', movieFile: undefined as unknown as MovieFile, movie }
+}
+
+const tryTmdbProvider = async (
+  injector: Injector,
+  { title, year, season, episode }: { title: string; year?: number; season?: number; episode?: number },
+  context?: { file?: PiRatFile },
+): Promise<LinkResult | { status: 'skip' }> => {
+  const tmdbClientService = injector.getInstance(TmdbClientService)
+  const result = await tmdbClientService.fetchTmdbMovieMetadata({ title, year, season, episode }, context)
+
+  if (result.status === 'not-configured') return { status: 'skip' }
+  if (result.status === 'rate-limited') return { status: 'rate-limited' }
+  if (result.status === 'not-found') return { status: 'skip' }
+  if (result.status === 'error') return { status: 'skip' }
+
+  const { movie: tmdbMovie, series: tmdbSeries } = result.data
+  const imdbId = tmdbMovie.imdb_id!
+  const language = tmdbClientService.config?.value.defaultLanguage?.slice(0, 2) ?? 'en'
+
+  await ensureTmdbMovieExists(tmdbMovie, language, injector)
+
+  const movie = await ensureMovieExists(
+    {
+      imdbId,
+      year: tmdbMovie.release_date ? parseInt(tmdbMovie.release_date.slice(0, 4), 10) : undefined,
+      duration: tmdbMovie.runtime || undefined,
+      type: tmdbSeries ? 'episode' : 'movie',
+      seriesId: tmdbSeries?.external_ids?.imdb_id ?? undefined,
+      season: result.data.episode?.season_number,
+      episode: result.data.episode?.episode_number,
+    },
+    injector,
+  )
+  await ensureMovieLocalizedMetadataExists(mapTmdbMovieToLocalized(tmdbMovie, language), injector)
+
+  if (tmdbSeries) {
+    const seriesImdbId = tmdbSeries.external_ids?.imdb_id
+    if (seriesImdbId) {
+      await ensureTmdbSeriesExists(seriesImdbId, tmdbSeries, language, injector, context)
+    }
+  }
+
+  return { status: 'linked', movieFile: undefined as unknown as MovieFile, movie }
+}
 
 export const linkMovie = async (options: { injector: Injector; file: PiRatFile }) => {
   const logger = getLogger(options.injector).withScope('linkMovie')
@@ -60,6 +166,7 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
 
   const ffprobeResult = await injector.getInstance(FfprobeService).getFfprobeForPiratFile(file)
 
+  // Check existing OMDB metadata first (backward compatibility)
   const omdbDataSet = getDataSetFor(injector, OmdbMovieMetadata, 'imdbID')
   const storedResult = await omdbDataSet.find(injector, {
     filter: {
@@ -80,7 +187,19 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
   }
 
   if (storedResult.length === 1) {
-    const movie = await ensureMovieExists(storedResult[0], injector)
+    const movie = await ensureMovieExists(
+      {
+        imdbId: storedResult[0].imdbID,
+        year: parseInt(storedResult[0].Year, 10),
+        season: storedResult[0].Season ? parseInt(storedResult[0].Season, 10) : undefined,
+        episode: storedResult[0].Episode ? parseInt(storedResult[0].Episode, 10) : undefined,
+        type: storedResult[0].Type,
+        duration: storedResult[0].Runtime ? parseInt(storedResult[0].Runtime, 10) : undefined,
+        seriesId: storedResult[0].seriesID,
+      },
+      injector,
+    )
+    await ensureMovieLocalizedMetadataExists(mapOmdbMovieToLocalized(storedResult[0]), injector)
     await ensureOmdbSeriesExists(storedResult[0], injector, { file })
 
     const {
@@ -93,66 +212,62 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
     })
 
     await logger.debug({
-      message: `File ${fileName} linked successfully.`,
+      message: `File ${fileName} linked successfully (from stored OMDB).`,
       data: { file, movieFile: newMovieFile, movie },
     })
 
     return { status: 'linked', movieFile: newMovieFile, movie } as const
   }
 
-  const omdbClientService = injector.getInstance(OmdbClientService)
-  const result = await omdbClientService.fetchOmdbMovieMetadata({ title, year, season, episode }, { file })
+  // Try providers in priority order
+  const priority = await getProviderPriority(injector)
+  const providers: Record<string, typeof tryOmdbProvider> = {
+    omdb: tryOmdbProvider,
+    tmdb: tryTmdbProvider,
+  }
 
-  if (result.status === 'rate-limited') {
-    await logger.warning({
-      message: `OMDB rate limit reached while linking '${fileName}', skipping.`,
-      data: { file, title, year },
-    })
-    return { status: 'rate-limited' } as const
+  let imdbId: string | undefined
+  for (const provider of priority) {
+    const tryProvider = providers[provider]
+    if (!tryProvider) continue
+
+    const result = await tryProvider(injector, { title, year, season, episode }, { file })
+
+    if (result.status === 'skip') continue
+    if (result.status === 'rate-limited') {
+      await logger.warning({
+        message: `${provider.toUpperCase()} rate limit reached while linking '${fileName}', skipping.`,
+        data: { file, title, year },
+      })
+      return { status: 'rate-limited' } as const
+    }
+    if (result.status === 'linked') {
+      imdbId = (result.movie as { imdbId?: string })?.imdbId
+      break
+    }
   }
 
-  if (result.status === 'not-found') {
+  if (!imdbId) {
     await logger.debug({
-      message: `No OMDB metadata found for '${fileName}'.`,
+      message: `No metadata found for '${fileName}' from any provider.`,
       data: { file, title, year },
     })
     return { status: 'metadata-not-found' } as const
   }
 
-  if (result.status === 'not-configured') {
-    await logger.warning({
-      message: `OMDB service not configured, cannot link '${fileName}'.`,
-      data: { file },
-    })
-    return { status: 'omdb-not-configured' } as const
-  }
-
-  if (result.status === 'error') {
-    await logger.error({
-      message: `OMDB error while linking '${fileName}'.`,
-      data: { file, error: result.error },
-    })
-    return { status: 'omdb-error', error: result.error } as const
-  }
-
-  const added = await ensureOmdbMovieExists(result.data, injector)
-
-  const movie = await ensureMovieExists(added, injector)
-  await ensureOmdbSeriesExists(added, injector, { file })
-
   const {
     created: [newMovieFile],
   } = await movieFileDataSet.add(injector, {
     driveLetter,
     path,
-    imdbId: added.imdbID,
+    imdbId,
     ffprobe: ffprobeResult,
   })
 
   await logger.debug({
     message: `File ${fileName} linked successfully.`,
-    data: { file, movieFile: newMovieFile, movie },
+    data: { file, movieFile: newMovieFile },
   })
 
-  return { status: 'linked', movieFile: newMovieFile, movie } as const
+  return { status: 'linked', movieFile: newMovieFile, movie: { imdbId } } as const
 }
diff --git a/service/src/app-models/media/utils/map-omdb-to-localized.ts b/service/src/app-models/media/utils/map-omdb-to-localized.ts
new file mode 100644
index 00000000..3d490a65
--- /dev/null
+++ b/service/src/app-models/media/utils/map-omdb-to-localized.ts
@@ -0,0 +1,26 @@
+import type { MovieMetadataLocalized, OmdbMovieMetadata, OmdbSeriesMetadata, SeriesMetadataLocalized } from 'common'
+
+export const mapOmdbMovieToLocalized = (
+  omdbMeta: OmdbMovieMetadata,
+): Omit<MovieMetadataLocalized, 'id' | 'createdAt' | 'updatedAt'> => ({
+  movieImdbId: omdbMeta.imdbID,
+  language: 'en',
+  title: omdbMeta.Title,
+  plot: omdbMeta.Plot,
+  posterUrl: omdbMeta.Poster !== 'N/A' ? omdbMeta.Poster : undefined,
+  genre: omdbMeta.Genre ? omdbMeta.Genre.split(', ') : undefined,
+  source: 'omdb',
+  sourceId: omdbMeta.imdbID,
+})
+
+export const mapOmdbSeriesToLocalized = (
+  omdbMeta: OmdbSeriesMetadata,
+): Omit<SeriesMetadataLocalized, 'id' | 'createdAt' | 'updatedAt'> => ({
+  seriesImdbId: omdbMeta.imdbID,
+  language: 'en',
+  title: omdbMeta.Title,
+  plot: omdbMeta.Plot,
+  posterUrl: omdbMeta.Poster !== 'N/A' ? omdbMeta.Poster : undefined,
+  source: 'omdb',
+  sourceId: omdbMeta.imdbID,
+})
diff --git a/service/src/app-models/media/utils/map-tmdb-to-localized.ts b/service/src/app-models/media/utils/map-tmdb-to-localized.ts
new file mode 100644
index 00000000..fe596de5
--- /dev/null
+++ b/service/src/app-models/media/utils/map-tmdb-to-localized.ts
@@ -0,0 +1,32 @@
+import type { MovieMetadataLocalized, SeriesMetadataLocalized } from 'common'
+
+import type { TmdbMovieDetailsResponse, TmdbTvDetailsResponse } from '../metadata-services/tmdb-api-types.js'
+import { buildTmdbImageUrl } from '../metadata-services/tmdb-client-service.js'
+
+export const mapTmdbMovieToLocalized = (
+  tmdbMovie: TmdbMovieDetailsResponse,
+  language: string,
+): Omit<MovieMetadataLocalized, 'id' | 'createdAt' | 'updatedAt'> => ({
+  movieImdbId: tmdbMovie.imdb_id!,
+  language,
+  title: tmdbMovie.title,
+  plot: tmdbMovie.overview || undefined,
+  posterUrl: buildTmdbImageUrl(tmdbMovie.poster_path),
+  genre: tmdbMovie.genres.map((g) => g.name),
+  source: 'tmdb',
+  sourceId: String(tmdbMovie.id),
+})
+
+export const mapTmdbSeriesToLocalized = (
+  tmdbSeries: TmdbTvDetailsResponse,
+  imdbId: string,
+  language: string,
+): Omit<SeriesMetadataLocalized, 'id' | 'createdAt' | 'updatedAt'> => ({
+  seriesImdbId: imdbId,
+  language,
+  title: tmdbSeries.name,
+  plot: tmdbSeries.overview || undefined,
+  posterUrl: buildTmdbImageUrl(tmdbSeries.poster_path),
+  source: 'tmdb',
+  sourceId: String(tmdbSeries.id),
+})

From 40d6fde1264737760274bad6db2fb096d5991a19 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 10:00:15 +0100
Subject: [PATCH 04/30] eslint ignore glob updates

---
 eslint.config.js | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/eslint.config.js b/eslint.config.js
index ac435801..8036c797 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -15,10 +15,10 @@ export default tseslint.config(
   {
     ignores: [
       'coverage',
-      '*/node_modules/*',
-      '*/esm/*',
-      '*/types/*',
-      '*/dist/*',
+      '**/node_modules/**',
+      '**/esm/**',
+      '**/types/**',
+      '**/dist/**',
       '.yarn/*',
       'eslint.config.js',
       'prettier.config.js',

From 31ad5f1c0901a6962b87c8ef638cb00fd702a327 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 11:04:45 +0100
Subject: [PATCH 05/30] fs update, eslint config fix, file list fixes

---
 common/src/utils/media/is-movie-file.ts       |   4 +-
 eslint.config.js                              |   7 +-
 .../pages/file-browser/file-context-menu.tsx  | 160 ---------
 frontend/src/pages/file-browser/file-list.tsx | 324 +++++++++++++-----
 package.json                                  |   2 +-
 yarn.lock                                     |  10 +-
 6 files changed, 253 insertions(+), 254 deletions(-)
 delete mode 100644 frontend/src/pages/file-browser/file-context-menu.tsx

diff --git a/common/src/utils/media/is-movie-file.ts b/common/src/utils/media/is-movie-file.ts
index d88da75d..4e0adb03 100644
--- a/common/src/utils/media/is-movie-file.ts
+++ b/common/src/utils/media/is-movie-file.ts
@@ -1,6 +1,8 @@
+const movieExtensions = ['.mkv', '.webm', '.avi', '.mp4', '.mov']
+
 export const isMovieFile = (path: string) => {
   const pathToLower = path.toLowerCase()
-  if (pathToLower.endsWith('.mkv') || pathToLower.endsWith('.webm') || pathToLower.endsWith('.avi')) {
+  if (movieExtensions.some((extension) => pathToLower.endsWith(extension))) {
     return true
   }
   return false
diff --git a/eslint.config.js b/eslint.config.js
index 8036c797..37352f95 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -5,9 +5,10 @@ import furystack from '@furystack/eslint-plugin'
 import prettierConfig from 'eslint-config-prettier'
 import jsdoc from 'eslint-plugin-jsdoc'
 import playwright from 'eslint-plugin-playwright'
+import { defineConfig } from 'eslint/config'
 import tseslint from 'typescript-eslint'
 
-export default tseslint.config(
+export default defineConfig(
   {
     ...playwright.configs['flat/recommended'],
     files: ['e2e'],
@@ -29,7 +30,9 @@ export default tseslint.config(
   eslint.configs.recommended,
   ...tseslint.configs.recommendedTypeChecked,
   {
-    plugins: { furystack },
+    plugins: {
+      furystack,
+    },
     ...furystack.configs.recommendedStrict,
   },
   prettierConfig,
diff --git a/frontend/src/pages/file-browser/file-context-menu.tsx b/frontend/src/pages/file-browser/file-context-menu.tsx
deleted file mode 100644
index 22cce682..00000000
--- a/frontend/src/pages/file-browser/file-context-menu.tsx
+++ /dev/null
@@ -1,160 +0,0 @@
-import { Shade, createComponent } from '@furystack/shades'
-import { ContextMenu, ContextMenuManager, Icon, icons, NotyService } from '@furystack/shades-common-components'
-import type { ContextMenuItem } from '@furystack/shades-common-components'
-import type { DirectoryEntry } from 'common'
-import { getFallbackMetadata, getFullPath, isMovieFile, isSampleFile } from 'common'
-import { RelatedMoviesModal } from '../../components/movie-file-management/related-movies-modal.js'
-import { MediaApiClient } from '../../services/api-clients/media-api-client.js'
-import { FileInfoModal } from './file-info-modal.js'
-
-export const FileContextMenu = Shade<{
-  entry: DirectoryEntry
-  currentDriveLetter: string
-  currentPath: string
-  open: () => void
-}>({
-  customElementName: 'file-context-menu',
-  render: ({ children, props, useState, injector, useDisposable }) => {
-    const { entry, currentDriveLetter, currentPath, open } = props
-    const [isInfoVisible, setInfoVisible] = useState('isInfoVisible', false)
-    const [isRelatedMoviesVisible, setRelatedMoviesVisible] = useState('isRelatedMoviesVisible', false)
-
-    const manager = useDisposable('contextMenuManager', () => new ContextMenuManager<() => void>())
-
-    const path = `${currentDriveLetter}:${currentPath}/${entry.name}`
-    const movieMetadata = props.entry.isFile && !isSampleFile(path) && isMovieFile(path) && getFallbackMetadata(path)
-
-    const allowScanForMovies = props.entry.isDirectory
-
-    const getItems = (): Array<ContextMenuItem<() => void>> => [
-      {
-        type: 'item',
-        icon: <Icon icon={icons.folderOpen} size="small" />,
-        label: 'Open',
-        data: () => open(),
-      },
-      ...(movieMetadata
-        ? [
-            {
-              type: 'item' as const,
-              icon: <Icon icon={icons.film} size="small" />,
-              label: `Related movie: ${movieMetadata.title} ${
-                movieMetadata.type === 'episode' ? `S${movieMetadata.season}E${movieMetadata.episode}` : ''
-              }`,
-              data: () => setRelatedMoviesVisible(true),
-            },
-            {
-              type: 'item' as const,
-              icon: <Icon icon={icons.messageCircle} size="small" />,
-              label: 'Extract Subtitles',
-              data: () => {
-                const notyService = injector.getInstance(NotyService)
-                injector
-                  .getInstance(MediaApiClient)
-                  .call({
-                    method: 'POST',
-                    action: '/extract-subtitles',
-                    body: {
-                      driveLetter: currentDriveLetter,
-                      path: getFullPath(currentPath, entry.name),
-                    },
-                  })
-                  .then(() => {
-                    notyService.emit('onNotyAdded', {
-                      type: 'success',
-                      title: 'Subtitles extracted',
-                      body: <>Subtitles extracted successfully for file {entry.name}</>,
-                    })
-                  })
-                  .catch(() => {
-                    notyService.emit('onNotyAdded', {
-                      type: 'error',
-                      title: 'Subtitles extraction failed',
-                      body: <>Subtitles extraction failed for file {entry.name}</>,
-                    })
-                  })
-              },
-            },
-          ]
-        : []),
-      ...(allowScanForMovies
-        ? [
-            {
-              type: 'item' as const,
-              icon: <Icon icon={icons.film} size="small" />,
-              label: 'Scan for movies',
-              data: () => {
-                const notyService = injector.getInstance(NotyService)
-                injector
-                  .getInstance(MediaApiClient)
-                  .call({
-                    method: 'POST',
-                    action: '/scan-for-movies',
-                    body: {
-                      root: {
-                        driveLetter: currentDriveLetter,
-                        path: getFullPath(currentPath, entry.name),
-                      },
-                      autoExtractSubtitles: false,
-                    },
-                  })
-                  .then(() => {
-                    notyService.emit('onNotyAdded', {
-                      type: 'success',
-                      title: 'Movies scanned',
-                      body: <>Movies scanned successfully for folder {entry.name}</>,
-                    })
-                  })
-                  .catch(() => {
-                    notyService.emit('onNotyAdded', {
-                      type: 'error',
-                      title: 'Movies scanning failed',
-                      body: <>Movies scanning failed for folder {entry.name}</>,
-                    })
-                  })
-              },
-            },
-          ]
-        : []),
-      {
-        type: 'item',
-        icon: <Icon icon={icons.info} size="small" />,
-        label: 'Show file info',
-        data: () => setInfoVisible(true),
-      },
-    ]
-
-    return (
-      <>
-        <div
-          oncontextmenu={(ev: MouseEvent) => {
-            ev.preventDefault()
-            manager.open({
-              position: { x: ev.clientX, y: ev.clientY },
-              items: getItems(),
-            })
-          }}
-        >
-          {children}
-        </div>
-        <ContextMenu manager={manager} onItemSelect={(action) => action()} />
-        <FileInfoModal
-          entry={entry}
-          isInfoVisible={isInfoVisible}
-          onClose={() => setInfoVisible(false)}
-          currentDriveLetter={currentDriveLetter}
-          currentPath={currentPath}
-        />
-        {movieMetadata && (
-          <RelatedMoviesModal
-            drive={currentDriveLetter}
-            path={currentPath}
-            file={entry}
-            isOpened={isRelatedMoviesVisible}
-            onClose={() => setRelatedMoviesVisible(false)}
-          />
-        )}
-      </>
-    )
-  },
-})
diff --git a/frontend/src/pages/file-browser/file-list.tsx b/frontend/src/pages/file-browser/file-list.tsx
index b4d3bd3b..052ef1bf 100644
--- a/frontend/src/pages/file-browser/file-list.tsx
+++ b/frontend/src/pages/file-browser/file-list.tsx
@@ -1,17 +1,28 @@
 import type { FindOptions } from '@furystack/core'
 import { createComponent, Shade } from '@furystack/shades'
-import type { CollectionService } from '@furystack/shades-common-components'
-import { DataGrid, NotyService, SelectionCell } from '@furystack/shades-common-components'
+import type { CollectionService, ContextMenuItem } from '@furystack/shades-common-components'
+import {
+  ContextMenu,
+  ContextMenuManager,
+  DataGrid,
+  Icon,
+  icons,
+  NotyService,
+  SelectionCell,
+} from '@furystack/shades-common-components'
 import { PathHelper } from '@furystack/utils'
-import { getFullPath, type DirectoryEntry } from 'common'
-import { environmentOptions } from '../../utils/environment-options.js'
+import { getFallbackMetadata, getFullPath, isMovieFile, isSampleFile, type DirectoryEntry } from 'common'
+
+import { RelatedMoviesModal } from '../../components/movie-file-management/related-movies-modal.js'
+import { MediaApiClient } from '../../services/api-clients/media-api-client.js'
 import { DrivesService } from '../../services/drives-service.js'
 import { getErrorMessage } from '../../services/get-error-message.js'
 import { SessionService } from '../../services/session.js'
+import { environmentOptions } from '../../utils/environment-options.js'
 import { triggerDownload } from '../../utils/trigger-download.js'
 import { BreadCrumbs } from './breadcrumbs.js'
 import { DirectoryEntryIcon } from './directory-entry-icon.js'
-import { FileContextMenu } from './file-context-menu.js'
+import { FileInfoModal } from './file-info-modal.js'
 
 export const FileList = Shade<{
   currentDriveLetter: string
@@ -47,6 +58,12 @@ export const FileList = Shade<{
       {},
     )
 
+    const [activeEntry, setActiveEntry] = useState<DirectoryEntry | null>('activeEntry', null)
+    const [isInfoVisible, setInfoVisible] = useState('isInfoVisible', false)
+    const [isRelatedMoviesVisible, setRelatedMoviesVisible] = useState('isRelatedMoviesVisible', false)
+
+    const contextMenuManager = useDisposable('contextMenuManager', () => new ContextMenuManager<() => void>())
+
     const activate = () => {
       const focused = service.focusedEntry.getValue()
       const isComponentFocused = service.hasFocus.getValue()
@@ -55,6 +72,117 @@ export const FileList = Shade<{
       }
     }
 
+    const getContextMenuItems = (entry: DirectoryEntry): Array<ContextMenuItem<() => void>> => {
+      const path = `${currentDriveLetter}:${currentPath}/${entry.name}`
+      const movieMetadata = entry.isFile && !isSampleFile(path) && isMovieFile(path) && getFallbackMetadata(path)
+      const allowScanForMovies = entry.isDirectory
+
+      return [
+        {
+          type: 'item',
+          icon: <Icon icon={icons.folderOpen} size="small" />,
+          label: 'Open',
+          data: () => props.onActivate?.(entry),
+        },
+        ...(movieMetadata
+          ? [
+              {
+                type: 'item' as const,
+                icon: <Icon icon={icons.film} size="small" />,
+                label: `Related movie: ${movieMetadata.title} ${
+                  movieMetadata.type === 'episode' ? `S${movieMetadata.season}E${movieMetadata.episode}` : ''
+                }`,
+                data: () => setRelatedMoviesVisible(true),
+              },
+              {
+                type: 'item' as const,
+                icon: <Icon icon={icons.messageCircle} size="small" />,
+                label: 'Extract Subtitles',
+                data: () => {
+                  injector
+                    .getInstance(MediaApiClient)
+                    .call({
+                      method: 'POST',
+                      action: '/extract-subtitles',
+                      body: {
+                        driveLetter: currentDriveLetter,
+                        path: getFullPath(currentPath, entry.name),
+                      },
+                    })
+                    .then(() => {
+                      notyService.emit('onNotyAdded', {
+                        type: 'success',
+                        title: 'Subtitles extracted',
+                        body: <>Subtitles extracted successfully for file {entry.name}</>,
+                      })
+                    })
+                    .catch(() => {
+                      notyService.emit('onNotyAdded', {
+                        type: 'error',
+                        title: 'Subtitles extraction failed',
+                        body: <>Subtitles extraction failed for file {entry.name}</>,
+                      })
+                    })
+                },
+              },
+            ]
+          : []),
+        ...(allowScanForMovies
+          ? [
+              {
+                type: 'item' as const,
+                icon: <Icon icon={icons.film} size="small" />,
+                label: 'Scan for movies',
+                data: () => {
+                  injector
+                    .getInstance(MediaApiClient)
+                    .call({
+                      method: 'POST',
+                      action: '/scan-for-movies',
+                      body: {
+                        root: {
+                          driveLetter: currentDriveLetter,
+                          path: getFullPath(currentPath, entry.name),
+                        },
+                        autoExtractSubtitles: false,
+                      },
+                    })
+                    .then(() => {
+                      notyService.emit('onNotyAdded', {
+                        type: 'success',
+                        title: 'Movies scanned',
+                        body: <>Movies scanned successfully for folder {entry.name}</>,
+                      })
+                    })
+                    .catch(() => {
+                      notyService.emit('onNotyAdded', {
+                        type: 'error',
+                        title: 'Movies scanning failed',
+                        body: <>Movies scanning failed for folder {entry.name}</>,
+                      })
+                    })
+                },
+              },
+            ]
+          : []),
+        {
+          type: 'item',
+          icon: <Icon icon={icons.info} size="small" />,
+          label: 'Show file info',
+          data: () => setInfoVisible(true),
+        },
+      ]
+    }
+
+    const handleContextMenu = (entry: DirectoryEntry, ev: MouseEvent) => {
+      ev.preventDefault()
+      setActiveEntry(entry)
+      contextMenuManager.open({
+        position: { x: ev.clientX, y: ev.clientY },
+        items: getContextMenuItems(entry),
+      })
+    }
+
     useDisposable('keypressListener', () => {
       const listener = (ev: KeyboardEvent) => {
         if (ev.key === 'Enter') {
@@ -102,85 +230,92 @@ export const FileList = Shade<{
       }
     })
 
-    return (
-      <div
-        data-testid="file-drop"
-        ondragover={(ev) => {
-          ev.preventDefault()
-        }}
-        ondrop={async (ev) => {
-          ev.preventDefault()
-          if (ev.dataTransfer?.files) {
-            const session = injector.getInstance(SessionService)
-            if (!(await session.isAuthorized('admin'))) {
-              return notyService.emit('onNotyAdded', {
-                type: 'warning',
-                title: 'Not authorized',
-                body: <>You are not authorized to upload files</>,
-              })
-            }
+    const activeEntryPath = activeEntry ? `${currentDriveLetter}:${currentPath}/${activeEntry.name}` : ''
+    const activeMovieMetadata =
+      activeEntry?.isFile &&
+      activeEntryPath &&
+      !isSampleFile(activeEntryPath) &&
+      isMovieFile(activeEntryPath) &&
+      getFallbackMetadata(activeEntryPath)
 
-            const formData = new FormData()
-            for (const file of ev.dataTransfer.files) {
-              formData.append('uploads', file)
-            }
-            await fetch(
-              `${environmentOptions.serviceUrl}/drives/volumes/${encodeURIComponent(
-                currentDriveLetter,
-              )}/${encodeURIComponent(currentPath)}/upload`,
-              {
-                method: 'POST',
-                credentials: 'include',
-                body: formData,
-              },
-            )
-              .then(() => {
-                notyService.emit('onNotyAdded', {
-                  type: 'success',
-                  title: 'Upload completed',
-                  body: <>The files are upploaded succesfully</>,
+    return (
+      <>
+        <div
+          data-testid="file-drop"
+          ondragover={(ev) => {
+            ev.preventDefault()
+          }}
+          ondrop={async (ev) => {
+            ev.preventDefault()
+            if (ev.dataTransfer?.files) {
+              const session = injector.getInstance(SessionService)
+              if (!(await session.isAuthorized('admin'))) {
+                return notyService.emit('onNotyAdded', {
+                  type: 'warning',
+                  title: 'Not authorized',
+                  body: <>You are not authorized to upload files</>,
                 })
-              })
-              .catch((err) =>
-                notyService.emit('onNotyAdded', {
-                  title: 'Upload failed',
-                  body: <>{getErrorMessage(err)}</>,
-                  type: 'error',
-                }),
+              }
+
+              const formData = new FormData()
+              for (const file of ev.dataTransfer.files) {
+                formData.append('uploads', file)
+              }
+              await fetch(
+                `${environmentOptions.serviceUrl}/drives/volumes/${encodeURIComponent(
+                  currentDriveLetter,
+                )}/${encodeURIComponent(currentPath)}/upload`,
+                {
+                  method: 'POST',
+                  credentials: 'include',
+                  body: formData,
+                },
               )
-          }
-        }}
-        ondblclick={activate}
-        onkeydown={(ev) => {
-          if (ev.key === 'Enter') {
-            activate()
-          }
-        }}
-      >
-        <DataGrid
-          collectionService={service}
-          findOptions={findOptions}
-          onFindOptionsChange={setFindOptions}
-          columns={['name']}
-          headerComponents={{
-            name: () => (
-              <BreadCrumbs
-                currentDrive={currentDriveLetter}
-                currentPath={currentPath}
-                onChangePath={props.onChangePath}
-              />
-            ),
+                .then(() => {
+                  notyService.emit('onNotyAdded', {
+                    type: 'success',
+                    title: 'Upload completed',
+                    body: <>The files are upploaded succesfully</>,
+                  })
+                })
+                .catch((err) =>
+                  notyService.emit('onNotyAdded', {
+                    title: 'Upload failed',
+                    body: <>{getErrorMessage(err)}</>,
+                    type: 'error',
+                  }),
+                )
+            }
           }}
-          styles={{}}
-          rowComponents={{
-            name: (entry) => (
-              <FileContextMenu
-                entry={entry}
-                currentDriveLetter={currentDriveLetter}
-                currentPath={currentPath}
-                open={activate}
-              >
-                <div className="file-row" title={entry.name}>
+          ondblclick={activate}
+          onkeydown={(ev) => {
+            if (ev.key === 'Enter') {
+              activate()
+            }
+          }}
+        >
+          <DataGrid
+            collectionService={service}
+            findOptions={findOptions}
+            onFindOptionsChange={setFindOptions}
+            columns={['name']}
+            headerComponents={{
+              name: () => (
+                <BreadCrumbs
+                  currentDrive={currentDriveLetter}
+                  currentPath={currentPath}
+                  onChangePath={props.onChangePath}
+                />
+              ),
+            }}
+            styles={{}}
+            rowComponents={{
+              name: (entry) => (
+                <div
+                  className="file-row"
+                  title={entry.name}
+                  oncontextmenu={(ev: MouseEvent) => handleContextMenu(entry, ev)}
+                >
                   <div>
                     <SelectionCell entry={entry} service={service} />
                   </div>
@@ -189,11 +324,30 @@ export const FileList = Shade<{
                   </div>
                   <div className="file-name">{entry.name}</div>
                 </div>
-              </FileContextMenu>
-            ),
-          }}
-        />
-      </div>
+              ),
+            }}
+          />
+        </div>
+        <ContextMenu manager={contextMenuManager} onItemSelect={(action) => action()} />
+        {activeEntry && (
+          <FileInfoModal
+            entry={activeEntry}
+            isInfoVisible={isInfoVisible}
+            onClose={() => setInfoVisible(false)}
+            currentDriveLetter={currentDriveLetter}
+            currentPath={currentPath}
+          />
+        )}
+        {activeEntry && activeMovieMetadata && (
+          <RelatedMoviesModal
+            drive={currentDriveLetter}
+            path={currentPath}
+            file={activeEntry}
+            isOpened={isRelatedMoviesVisible}
+            onClose={() => setRelatedMoviesVisible(false)}
+          />
+        )}
+      </>
     )
   },
 })
diff --git a/package.json b/package.json
index 9777d87b..f04ecad7 100644
--- a/package.json
+++ b/package.json
@@ -18,7 +18,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@furystack/eslint-plugin": "^2.1.0",
+    "@furystack/eslint-plugin": "^2.1.1",
     "@furystack/yarn-plugin-changelog": "^1.0.6",
     "@playwright/test": "^1.58.2",
     "@types/jsdom": "^28.0.0",
diff --git a/yarn.lock b/yarn.lock
index fbebbc13..5fc0983f 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -755,14 +755,14 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@furystack/eslint-plugin@npm:^2.1.0":
-  version: 2.1.0
-  resolution: "@furystack/eslint-plugin@npm:2.1.0"
+"@furystack/eslint-plugin@npm:^2.1.1":
+  version: 2.1.1
+  resolution: "@furystack/eslint-plugin@npm:2.1.1"
   dependencies:
     "@typescript-eslint/utils": "npm:^8.56.1"
   peerDependencies:
     eslint: ">=9.0.0"
-  checksum: 10c0/2e3ed31bb989fa74a28544e3ed7742fb395999f10bfb914369368068e4c278ab527efa3d8fcd4cd2afc535f354aeb363e3bc9e3aaa22cae64405fa583638605e
+  checksum: 10c0/070c3dbf64c243930a81f7764b2d18a4d413c42fea634e0cd85d7e8a98ae0a2367e1249075afc75c3fc48b02c34b2a3660f988b1da6ef1f2e7482a943198eab0
   languageName: node
   linkType: hard
 
@@ -6983,7 +6983,7 @@ __metadata:
   resolution: "pi-rat@workspace:."
   dependencies:
     "@eslint/js": "npm:^10.0.1"
-    "@furystack/eslint-plugin": "npm:^2.1.0"
+    "@furystack/eslint-plugin": "npm:^2.1.1"
     "@furystack/yarn-plugin-changelog": "npm:^1.0.6"
     "@playwright/test": "npm:^1.58.2"
     "@types/jsdom": "npm:^28.0.0"

From 814fe7faa78d0751cf76a44fcd01fcf5bdb36ed7 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 11:06:08 +0100
Subject: [PATCH 06/30] legacy navigation fixes

---
 .../components/dashboard/device-availability.tsx   | 14 ++------------
 frontend/src/components/dashboard/index.tsx        | 14 +++-----------
 frontend/src/components/dashboard/movie-widget.tsx | 14 +++-----------
 3 files changed, 8 insertions(+), 34 deletions(-)

diff --git a/frontend/src/components/dashboard/device-availability.tsx b/frontend/src/components/dashboard/device-availability.tsx
index de17a18c..f3979f53 100644
--- a/frontend/src/components/dashboard/device-availability.tsx
+++ b/frontend/src/components/dashboard/device-availability.tsx
@@ -1,12 +1,11 @@
 import type { CacheWithValue } from '@furystack/cache'
-import { serializeToQueryString } from '@furystack/rest'
 import { Shade, createComponent } from '@furystack/shades'
 import { CacheView, Skeleton } from '@furystack/shades-common-components'
 import type { Device, DeviceAvailability as DeviceAvailabilityProps, Icon as IconType } from 'common'
 import { AppLink } from '../../routes/index.js'
-import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { IotDevicesService } from '../../services/iot-devices-service.js'
 import { SessionService } from '../../services/session.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { DynamicIcon } from '../dynamic-icon.js'
 import { DeviceAvailabilityPanel } from '../iot-devices/device-availability-panel.js'
 import { WidgetCard } from './widget-card.js'
@@ -42,16 +41,7 @@ const DeviceAvailabilityContent = Shade<{
                   onclick={(ev) => {
                     ev.preventDefault()
                     ev.stopImmediatePropagation()
-                    navigateToRoute(
-                      injector,
-                      '/entities/iot-devices',
-                      {},
-                      {
-                        queryString: serializeToQueryString({
-                          gedst: { mode: 'edit', currentId: device.name },
-                        }),
-                      },
-                    )
+                    navigateToRoute(injector, '/entities/iot-devices/edit/:id', { id: device.name })
                   }}
                   title="Edit device details"
                 >
diff --git a/frontend/src/components/dashboard/index.tsx b/frontend/src/components/dashboard/index.tsx
index b5a15079..9fea60b3 100644
--- a/frontend/src/components/dashboard/index.tsx
+++ b/frontend/src/components/dashboard/index.tsx
@@ -1,10 +1,9 @@
-import { serializeToQueryString } from '@furystack/rest'
 import { Shade, createComponent } from '@furystack/shades'
-import { ContextMenu, ContextMenuManager } from '@furystack/shades-common-components'
 import type { ContextMenuItem } from '@furystack/shades-common-components'
+import { ContextMenu, ContextMenuManager } from '@furystack/shades-common-components'
 import type { Dashboard as DashboardData } from 'common'
-import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { SessionService } from '../../services/session.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { Widget } from './widget.js'
 
 export const Dashboard = Shade<DashboardData>({
@@ -22,14 +21,7 @@ export const Dashboard = Shade<DashboardData>({
               icon: <span>📝</span>,
               label: 'Edit this dashboard',
               data: () => {
-                navigateToRoute(
-                  injector,
-                  '/entities/dashboards',
-                  {},
-                  {
-                    queryString: serializeToQueryString({ gedst: { currentId: props.id, mode: 'edit' } }),
-                  },
-                )
+                navigateToRoute(injector, '/entities/dashboards/edit/:id', { id: props.id })
               },
             },
           ]
diff --git a/frontend/src/components/dashboard/movie-widget.tsx b/frontend/src/components/dashboard/movie-widget.tsx
index 02923ba9..58ecf176 100644
--- a/frontend/src/components/dashboard/movie-widget.tsx
+++ b/frontend/src/components/dashboard/movie-widget.tsx
@@ -1,16 +1,15 @@
 import type { CacheWithValue } from '@furystack/cache'
 import { isLoadedCacheResult } from '@furystack/cache'
-import { serializeToQueryString } from '@furystack/rest'
-import { LazyLoad, Shade, createComponent } from '@furystack/shades'
+import { createComponent, LazyLoad, Shade } from '@furystack/shades'
 import { CacheView, cssVariableTheme, Skeleton } from '@furystack/shades-common-components'
 import type { Movie, MovieMetadataLocalized } from 'common'
 import { AppLink } from '../../routes/index.js'
-import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { LocalizedMetadataService } from '../../services/localized-metadata-service.js'
 import { MovieFilesService } from '../../services/movie-files-service.js'
 import { MoviesService } from '../../services/movies-service.js'
 import { SessionService } from '../../services/session.js'
 import { WatchProgressService } from '../../services/watch-progress-service.js'
+import { navigateToRoute } from '../../utils/navigate-to-route.js'
 import { WidgetCard } from './widget-card.js'
 
 const MovieWidgetContent = Shade<{
@@ -72,14 +71,7 @@ const MovieWidgetContent = Shade<{
                   onclick={(ev) => {
                     ev.preventDefault()
                     ev.stopImmediatePropagation()
-                    navigateToRoute(
-                      injector,
-                      '/entities/movies',
-                      {},
-                      {
-                        queryString: serializeToQueryString({ gedst: { mode: 'edit', currentId: imdbId } }),
-                      },
-                    )
+                    navigateToRoute(injector, '/entities/movies/edit/:id', { id: imdbId })
                   }}
                   title="Edit movie details"
                 >

From 3a07b93017fa09907f849429780562821ed668f7 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 11:10:35 +0100
Subject: [PATCH 07/30] encoding fix

---
 .../movie-player-v2/movie-player-service.ts   | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index 1fd14d3f..2fbd3a9f 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -1,16 +1,17 @@
 import type { ScopedLogger } from '@furystack/logging'
 import { ObservableValue } from '@furystack/utils'
-import type {
-  AudioTrackInfo,
-  FfprobeData,
-  PiRatFile,
-  PlaybackInfoResponse,
-  PlaybackMode,
-  SubtitleTrackInfo,
+import {
+  encode,
+  type AudioTrackInfo,
+  type FfprobeData,
+  type PiRatFile,
+  type PlaybackInfoResponse,
+  type PlaybackMode,
+  type SubtitleTrackInfo,
 } from 'common'
 import type Hls from 'hls.js'
-import { environmentOptions } from '../../../utils/environment-options.js'
 import type { MediaApiClient } from '../../../services/api-clients/media-api-client.js'
+import { environmentOptions } from '../../../utils/environment-options.js'
 
 export const videoCodecs = {
   h264: 'avc1.42E01E',
@@ -197,7 +198,7 @@ export class MoviePlayerService implements AsyncDisposable {
   private async startHlsPlayback(videoElement: HTMLVideoElement) {
     const mode = this.playbackMode.getValue()
     const hlsUrl = this.toServiceUrl(
-      `/api/media/files/${encodeURIComponent(this.file.driveLetter)}/${encodeURIComponent(this.file.path)}/master.m3u8?mode=${encodeURIComponent(mode)}`,
+      `/api/media/files/${encodeURIComponent(this.file.driveLetter)}/${encodeURIComponent(this.file.path)}/master.m3u8?mode=${encode(mode)}`,
     )
 
     const HlsModule = await loadHls()

From a7f246b24ed2953d094e28e357ea7b4a65634a3e Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 11:47:26 +0100
Subject: [PATCH 08/30] fixes and improvements

---
 frontend/src/pages/file-browser/file-list.tsx | 111 +++++++++++---
 .../movie-player-v2-component.tsx             |  47 ++++--
 .../services/transcoding-session.spec.ts      |  89 +++++++++++
 .../media/services/transcoding-session.ts     |  24 ++-
 .../utils/extract-imdb-id-from-nfo.spec.ts    | 119 +++++++++++++++
 .../media/utils/extract-imdb-id-from-nfo.ts   |  37 +++++
 .../utils/extract-imdb-id-from-tags.spec.ts   |  77 ++++++++++
 .../media/utils/extract-imdb-id-from-tags.ts  |  13 ++
 .../app-models/media/utils/link-movie.spec.ts | 139 +++++++++++++++++-
 .../src/app-models/media/utils/link-movie.ts  |  57 ++++++-
 10 files changed, 673 insertions(+), 40 deletions(-)
 create mode 100644 service/src/app-models/media/utils/extract-imdb-id-from-nfo.spec.ts
 create mode 100644 service/src/app-models/media/utils/extract-imdb-id-from-nfo.ts
 create mode 100644 service/src/app-models/media/utils/extract-imdb-id-from-tags.spec.ts
 create mode 100644 service/src/app-models/media/utils/extract-imdb-id-from-tags.ts

diff --git a/frontend/src/pages/file-browser/file-list.tsx b/frontend/src/pages/file-browser/file-list.tsx
index 052ef1bf..fec531c2 100644
--- a/frontend/src/pages/file-browser/file-list.tsx
+++ b/frontend/src/pages/file-browser/file-list.tsx
@@ -2,9 +2,11 @@ import type { FindOptions } from '@furystack/core'
 import { createComponent, Shade } from '@furystack/shades'
 import type { CollectionService, ContextMenuItem } from '@furystack/shades-common-components'
 import {
+  Button,
   ContextMenu,
   ContextMenuManager,
   DataGrid,
+  Dialog,
   Icon,
   icons,
   NotyService,
@@ -61,9 +63,24 @@ export const FileList = Shade<{
     const [activeEntry, setActiveEntry] = useState<DirectoryEntry | null>('activeEntry', null)
     const [isInfoVisible, setInfoVisible] = useState('isInfoVisible', false)
     const [isRelatedMoviesVisible, setRelatedMoviesVisible] = useState('isRelatedMoviesVisible', false)
+    const [isDeleteDialogVisible, setDeleteDialogVisible] = useState('isDeleteDialogVisible', false)
+    const [entriesToDelete, setEntriesToDelete] = useState<DirectoryEntry[]>('entriesToDelete', [])
+    const [isDeleting, setDeleting] = useState('isDeleting', false)
 
     const contextMenuManager = useDisposable('contextMenuManager', () => new ContextMenuManager<() => void>())
 
+    const collectDeleteTargets = (): DirectoryEntry[] => {
+      const selection = service.selection.getValue()
+      if (selection.length > 0) {
+        return selection.filter((e) => e.name !== '..')
+      }
+      const focused = service.focusedEntry.getValue()
+      if (focused && focused.name !== '..') {
+        return [focused]
+      }
+      return []
+    }
+
     const activate = () => {
       const focused = service.focusedEntry.getValue()
       const isComponentFocused = service.hasFocus.getValue()
@@ -171,6 +188,25 @@ export const FileList = Shade<{
           label: 'Show file info',
           data: () => setInfoVisible(true),
         },
+        ...(entry.name !== '..'
+          ? [
+              {
+                type: 'separator' as const,
+              },
+              {
+                type: 'item' as const,
+                icon: <Icon icon={icons.trash} size="small" />,
+                label: 'Delete',
+                data: () => {
+                  const targets = collectDeleteTargets()
+                  if (targets.length > 0) {
+                    setEntriesToDelete(targets)
+                    setDeleteDialogVisible(true)
+                  }
+                },
+              },
+            ]
+          : []),
       ]
     }
 
@@ -183,6 +219,33 @@ export const FileList = Shade<{
       })
     }
 
+    const handleDeleteConfirm = async () => {
+      setDeleting(true)
+      try {
+        for (const entry of entriesToDelete) {
+          await drivesService.removeFile({
+            letter: currentDriveLetter,
+            path: getFullPath(currentPath, entry.name),
+          })
+        }
+        notyService.emit('onNotyAdded', {
+          type: 'success',
+          title: 'Delete completed',
+          body: <>{entriesToDelete.length} item(s) deleted successfully</>,
+        })
+      } catch (err) {
+        notyService.emit('onNotyAdded', {
+          type: 'error',
+          title: 'Delete failed',
+          body: <>{getErrorMessage(err)}</>,
+        })
+      } finally {
+        setDeleting(false)
+        setDeleteDialogVisible(false)
+        setEntriesToDelete([])
+      }
+    }
+
     useDisposable('keypressListener', () => {
       const listener = (ev: KeyboardEvent) => {
         if (ev.key === 'Enter') {
@@ -203,24 +266,10 @@ export const FileList = Shade<{
         }
 
         if (ev.key === 'Delete') {
-          const focused = service.focusedEntry.getValue()
-          if (focused) {
-            drivesService
-              .removeFile({ letter: currentDriveLetter, path: getFullPath(currentPath, focused.name) })
-              .then(() => {
-                notyService.emit('onNotyAdded', {
-                  type: 'success',
-                  title: 'Delete completed',
-                  body: <>The file is deleted succesfully</>,
-                })
-              })
-              .catch((err) =>
-                notyService.emit('onNotyAdded', {
-                  title: 'Delete failed',
-                  body: <>{getErrorMessage(err)}</>,
-                  type: 'error',
-                }),
-              )
+          const targets = collectDeleteTargets()
+          if (targets.length > 0) {
+            setEntriesToDelete(targets)
+            setDeleteDialogVisible(true)
           }
         }
       }
@@ -347,6 +396,32 @@ export const FileList = Shade<{
             onClose={() => setRelatedMoviesVisible(false)}
           />
         )}
+        <Dialog
+          isVisible={isDeleteDialogVisible}
+          title="Confirm Delete"
+          onClose={isDeleting ? undefined : () => setDeleteDialogVisible(false)}
+          actions={
+            <>
+              <Button onclick={() => setDeleteDialogVisible(false)} disabled={isDeleting}>
+                Cancel
+              </Button>
+              <Button variant="contained" danger loading={isDeleting} onclick={handleDeleteConfirm}>
+                Delete
+              </Button>
+            </>
+          }
+        >
+          <p style={{ margin: '0 0 8px' }}>
+            Are you sure you want to delete the following {entriesToDelete.length} item(s)?
+          </p>
+          <ul style={{ margin: '0', paddingLeft: '20px' }}>
+            {entriesToDelete.map((e) => (
+              <li style={{ display: 'flex', alignItems: 'center', gap: '8px', padding: '2px 0' }}>
+                <DirectoryEntryIcon entry={e} /> {e.name}
+              </li>
+            ))}
+          </ul>
+        </Dialog>
       </>
     )
   },
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
index a423487e..2e247512 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
@@ -26,23 +26,41 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
     const { driveLetter, path } = props.file
     const watchProgressService = injector.getInstance(WatchProgressService)
     useDisposable('watchProgressUpdater', () => {
+      const createUpdater = (video: HTMLVideoElement) =>
+        new WatchProgressUpdater({
+          intervalMs: 10 * 1000,
+          onSave: async (progress) => {
+            void watchProgressService.updateWatchEntry({
+              completed: (mediaService.playbackInfo.getValue()?.duration ?? video.duration) - progress < 10,
+              driveLetter,
+              path,
+              watchedSeconds: progress,
+            })
+          },
+          saveTresholdSeconds: 10,
+          videoElement: video,
+        })
+
       const video = videoRef.current
-      if (!video) {
-        return { [Symbol.asyncDispose]: async () => {} }
+      if (video) {
+        return createUpdater(video)
       }
-      return new WatchProgressUpdater({
-        intervalMs: 10 * 1000,
-        onSave: async (progress) => {
-          void watchProgressService.updateWatchEntry({
-            completed: video.duration - progress < 10,
-            driveLetter,
-            path,
-            watchedSeconds: progress,
-          })
-        },
-        saveTresholdSeconds: 10,
-        videoElement: video,
+
+      let updater: WatchProgressUpdater | null = null
+      const frameId = requestAnimationFrame(() => {
+        const deferredVideo = videoRef.current
+        if (deferredVideo) {
+          updater = createUpdater(deferredVideo)
+        }
       })
+      return {
+        [Symbol.asyncDispose]: async () => {
+          cancelAnimationFrame(frameId)
+          if (updater) {
+            await updater[Symbol.asyncDispose]()
+          }
+        },
+      }
     })
     const { watchProgress, file } = props
 
@@ -86,6 +104,7 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
         }}
       >
         <media-controller
+          defaultDuration={playbackInfo?.duration}
           style={{
             display: 'flex',
             width: '100%',
diff --git a/service/src/app-models/media/services/transcoding-session.spec.ts b/service/src/app-models/media/services/transcoding-session.spec.ts
index ebb25b86..202a0811 100644
--- a/service/src/app-models/media/services/transcoding-session.spec.ts
+++ b/service/src/app-models/media/services/transcoding-session.spec.ts
@@ -691,6 +691,95 @@ describe('TranscodingSessionService', () => {
     })
   })
 
+  it('should remove all resolution variants when resolution is undefined', async () => {
+    const mockProcess = createMockProcess()
+    mockSpawn.mockReturnValue(mockProcess)
+
+    await usingAsync(new Injector(), async (injector) => {
+      injector.setExplicitInstance(
+        { getFfprobeForPiratFile: vi.fn().mockResolvedValue(mockFfprobe) } as unknown as FfprobeService,
+        FfprobeService,
+      )
+      injector.setExplicitInstance(
+        { getEncoder: vi.fn().mockResolvedValue('libx264') } as unknown as HwAccelDetector,
+        HwAccelDetector,
+      )
+
+      const service = injector.getInstance(TranscodingSessionService)
+      try {
+        await service.getOrCreateSession({
+          driveLetter: 'A',
+          path: 'test.mkv',
+          mode: 'transcode',
+          resolution: '1080p',
+        })
+        await service.getOrCreateSession({
+          driveLetter: 'A',
+          path: 'test.mkv',
+          mode: 'transcode',
+          resolution: '720p',
+        })
+        await service.getOrCreateSession({
+          driveLetter: 'A',
+          path: 'other.mkv',
+          mode: 'transcode',
+          resolution: '1080p',
+        })
+
+        expect(service.getActiveSessionCount()).toBe(3)
+
+        service.removeSession('A', 'test.mkv', 'transcode', 0)
+        expect(service.getActiveSessionCount()).toBe(1)
+        expect(service.getSession('A', 'test.mkv', 'transcode', 0, '1080p')).toBeUndefined()
+        expect(service.getSession('A', 'test.mkv', 'transcode', 0, '720p')).toBeUndefined()
+        expect(service.getSession('A', 'other.mkv', 'transcode', 0, '1080p')).toBeDefined()
+      } finally {
+        service.dispose()
+      }
+    })
+  })
+
+  it('should remove only exact match when resolution is specified', async () => {
+    const mockProcess = createMockProcess()
+    mockSpawn.mockReturnValue(mockProcess)
+
+    await usingAsync(new Injector(), async (injector) => {
+      injector.setExplicitInstance(
+        { getFfprobeForPiratFile: vi.fn().mockResolvedValue(mockFfprobe) } as unknown as FfprobeService,
+        FfprobeService,
+      )
+      injector.setExplicitInstance(
+        { getEncoder: vi.fn().mockResolvedValue('libx264') } as unknown as HwAccelDetector,
+        HwAccelDetector,
+      )
+
+      const service = injector.getInstance(TranscodingSessionService)
+      try {
+        await service.getOrCreateSession({
+          driveLetter: 'A',
+          path: 'test.mkv',
+          mode: 'transcode',
+          resolution: '1080p',
+        })
+        await service.getOrCreateSession({
+          driveLetter: 'A',
+          path: 'test.mkv',
+          mode: 'transcode',
+          resolution: '720p',
+        })
+
+        expect(service.getActiveSessionCount()).toBe(2)
+
+        service.removeSession('A', 'test.mkv', 'transcode', 0, '1080p')
+        expect(service.getActiveSessionCount()).toBe(1)
+        expect(service.getSession('A', 'test.mkv', 'transcode', 0, '1080p')).toBeUndefined()
+        expect(service.getSession('A', 'test.mkv', 'transcode', 0, '720p')).toBeDefined()
+      } finally {
+        service.dispose()
+      }
+    })
+  })
+
   it('should handle removeSession on non-existent session gracefully', async () => {
     await usingAsync(new Injector(), async (injector) => {
       const service = injector.getInstance(TranscodingSessionService)
diff --git a/service/src/app-models/media/services/transcoding-session.ts b/service/src/app-models/media/services/transcoding-session.ts
index f18b665e..86121bd6 100644
--- a/service/src/app-models/media/services/transcoding-session.ts
+++ b/service/src/app-models/media/services/transcoding-session.ts
@@ -415,11 +415,25 @@ export class TranscodingSessionService {
     audioTrackId: number = 0,
     resolution?: string,
   ) {
-    const key = this.buildSessionKey(driveLetter, path, mode, audioTrackId, resolution)
-    const session = this.sessions.get(key)
-    if (session) {
-      this.destroySession(session)
-      this.sessions.delete(key)
+    if (resolution !== undefined) {
+      const key = this.buildSessionKey(driveLetter, path, mode, audioTrackId, resolution)
+      const session = this.sessions.get(key)
+      if (session) {
+        this.destroySession(session)
+        this.sessions.delete(key)
+      }
+      return
+    }
+
+    const prefix = `${driveLetter}:${path}:${mode}:${audioTrackId}:`
+    const keysToRemove = [...this.sessions.keys()].filter((k) => k.startsWith(prefix))
+    for (const key of keysToRemove) {
+      const session = this.sessions.get(key)
+      if (session) {
+        void this.logger.verbose({ message: `Removing session: ${key}` })
+        this.destroySession(session)
+        this.sessions.delete(key)
+      }
     }
   }
 
diff --git a/service/src/app-models/media/utils/extract-imdb-id-from-nfo.spec.ts b/service/src/app-models/media/utils/extract-imdb-id-from-nfo.spec.ts
new file mode 100644
index 00000000..8c1688cf
--- /dev/null
+++ b/service/src/app-models/media/utils/extract-imdb-id-from-nfo.spec.ts
@@ -0,0 +1,119 @@
+import { describe, expect, it, vi } from 'vitest'
+import { extractImdbIdFromNfoFiles } from './extract-imdb-id-from-nfo.js'
+
+const mockReaddir = vi.fn()
+const mockReadFile = vi.fn()
+
+vi.mock('fs/promises', () => ({
+  readdir: (...args: unknown[]) => mockReaddir(...args) as unknown,
+  readFile: (...args: unknown[]) => mockReadFile(...args) as unknown,
+}))
+
+describe('extractImdbIdFromNfoFiles', () => {
+  it('should return empty when directory cannot be read', async () => {
+    mockReaddir.mockRejectedValue(new Error('ENOENT'))
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies', 'movies')
+
+    expect(result).toEqual({ nfoFiles: [] })
+  })
+
+  it('should return empty when no .nfo files exist', async () => {
+    mockReaddir.mockResolvedValue(['movie.mkv', 'movie.srt', 'readme.txt'])
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies', 'movies')
+
+    expect(result).toEqual({ nfoFiles: [] })
+  })
+
+  it('should extract IMDB ID from .nfo file containing a plain ID', async () => {
+    mockReaddir.mockResolvedValue(['movie.nfo', 'movie.mkv'])
+    mockReadFile.mockResolvedValue('tt1234567')
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies', 'movies')
+
+    expect(result.imdbId).toBe('tt1234567')
+    expect(result.nfoFiles).toEqual(['movies/movie.nfo'])
+  })
+
+  it('should extract IMDB ID from .nfo file containing an IMDB URL', async () => {
+    mockReaddir.mockResolvedValue(['movie.nfo'])
+    mockReadFile.mockResolvedValue('https://www.imdb.com/title/tt9876543/')
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies', 'movies')
+
+    expect(result.imdbId).toBe('tt9876543')
+  })
+
+  it('should extract IMDB ID from Kodi-style XML .nfo file', async () => {
+    mockReaddir.mockResolvedValue(['movie.nfo'])
+    mockReadFile.mockResolvedValue(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<movie>
+  <title>Some Movie</title>
+  <uniqueid type="imdb" default="true">tt7654321</uniqueid>
+  <year>2024</year>
+</movie>`)
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies', 'movies')
+
+    expect(result.imdbId).toBe('tt7654321')
+  })
+
+  it('should handle .nfo files case-insensitively', async () => {
+    mockReaddir.mockResolvedValue(['Movie.NFO'])
+    mockReadFile.mockResolvedValue('tt1111111')
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies', 'movies')
+
+    expect(result.imdbId).toBe('tt1111111')
+    expect(result.nfoFiles).toEqual(['movies/Movie.NFO'])
+  })
+
+  it('should return nfoFiles without imdbId when .nfo has no IMDB ID', async () => {
+    mockReaddir.mockResolvedValue(['movie.nfo'])
+    mockReadFile.mockResolvedValue('Just some random text without any ID')
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies', 'movies')
+
+    expect(result.imdbId).toBeUndefined()
+    expect(result.nfoFiles).toEqual(['movies/movie.nfo'])
+  })
+
+  it('should skip unreadable .nfo files and try the next one', async () => {
+    mockReaddir.mockResolvedValue(['broken.nfo', 'good.nfo'])
+    mockReadFile.mockRejectedValueOnce(new Error('EACCES')).mockResolvedValueOnce('tt2222222')
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies', 'movies')
+
+    expect(result.imdbId).toBe('tt2222222')
+    expect(result.nfoFiles).toEqual(['movies/broken.nfo', 'movies/good.nfo'])
+  })
+
+  it('should return all nfo files even when all are unreadable', async () => {
+    mockReaddir.mockResolvedValue(['a.nfo', 'b.nfo'])
+    mockReadFile.mockRejectedValue(new Error('EACCES'))
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies', 'movies')
+
+    expect(result.imdbId).toBeUndefined()
+    expect(result.nfoFiles).toEqual(['movies/a.nfo', 'movies/b.nfo'])
+  })
+
+  it('should normalize backslashes in relatedFiles paths', async () => {
+    mockReaddir.mockResolvedValue(['movie.nfo'])
+    mockReadFile.mockResolvedValue('tt3333333')
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies/subdir', 'movies/subdir')
+
+    expect(result.nfoFiles).toEqual(['movies/subdir/movie.nfo'])
+  })
+
+  it('should handle IDs with more than 7 digits', async () => {
+    mockReaddir.mockResolvedValue(['movie.nfo'])
+    mockReadFile.mockResolvedValue('tt12345678')
+
+    const result = await extractImdbIdFromNfoFiles('/mnt/media/movies', 'movies')
+
+    expect(result.imdbId).toBe('tt12345678')
+  })
+})
diff --git a/service/src/app-models/media/utils/extract-imdb-id-from-nfo.ts b/service/src/app-models/media/utils/extract-imdb-id-from-nfo.ts
new file mode 100644
index 00000000..43d247bf
--- /dev/null
+++ b/service/src/app-models/media/utils/extract-imdb-id-from-nfo.ts
@@ -0,0 +1,37 @@
+import { readdir, readFile } from 'fs/promises'
+import { join } from 'path'
+
+const IMDB_ID_IN_CONTENT = /tt\d{7,}/
+
+export const extractImdbIdFromNfoFiles = async (
+  physicalParentPath: string,
+  relativeParentPath: string,
+): Promise<{ imdbId?: string; nfoFiles: string[] }> => {
+  let entries: string[]
+  try {
+    const dirEntries = await readdir(physicalParentPath)
+    entries = dirEntries.filter((name) => name.toLowerCase().endsWith('.nfo'))
+  } catch {
+    return { nfoFiles: [] }
+  }
+
+  if (entries.length === 0) {
+    return { nfoFiles: [] }
+  }
+
+  const nfoFiles = entries.map((name) => join(relativeParentPath, name).split('\\').join('/'))
+
+  for (const name of entries) {
+    try {
+      const content = await readFile(join(physicalParentPath, name), 'utf-8')
+      const match = IMDB_ID_IN_CONTENT.exec(content)
+      if (match) {
+        return { imdbId: match[0], nfoFiles }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return { nfoFiles }
+}
diff --git a/service/src/app-models/media/utils/extract-imdb-id-from-tags.spec.ts b/service/src/app-models/media/utils/extract-imdb-id-from-tags.spec.ts
new file mode 100644
index 00000000..78983745
--- /dev/null
+++ b/service/src/app-models/media/utils/extract-imdb-id-from-tags.spec.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { extractImdbIdFromFfprobeTags } from './extract-imdb-id-from-tags.js'
+
+describe('extractImdbIdFromFfprobeTags', () => {
+  it('should return undefined for null tags', () => {
+    expect(extractImdbIdFromFfprobeTags(null)).toBeUndefined()
+  })
+
+  it('should return undefined for undefined tags', () => {
+    expect(extractImdbIdFromFfprobeTags(undefined)).toBeUndefined()
+  })
+
+  it('should return undefined for non-object tags', () => {
+    expect(extractImdbIdFromFfprobeTags('string')).toBeUndefined()
+    expect(extractImdbIdFromFfprobeTags(42)).toBeUndefined()
+    expect(extractImdbIdFromFfprobeTags(true)).toBeUndefined()
+  })
+
+  it('should return undefined for empty object', () => {
+    expect(extractImdbIdFromFfprobeTags({})).toBeUndefined()
+  })
+
+  it('should return undefined when no IMDB-related keys exist', () => {
+    expect(extractImdbIdFromFfprobeTags({ title: 'Some Movie', year: '2024' })).toBeUndefined()
+  })
+
+  it('should extract from "IMDB" key', () => {
+    expect(extractImdbIdFromFfprobeTags({ IMDB: 'tt1234567' })).toBe('tt1234567')
+  })
+
+  it('should extract from "imdb" key (lowercase)', () => {
+    expect(extractImdbIdFromFfprobeTags({ imdb: 'tt1234567' })).toBe('tt1234567')
+  })
+
+  it('should extract from "IMDb" key (mixed case)', () => {
+    expect(extractImdbIdFromFfprobeTags({ IMDb: 'tt1234567' })).toBe('tt1234567')
+  })
+
+  it('should extract from "IMDB_ID" key', () => {
+    expect(extractImdbIdFromFfprobeTags({ IMDB_ID: 'tt1234567' })).toBe('tt1234567')
+  })
+
+  it('should extract from "imdb_id" key (lowercase)', () => {
+    expect(extractImdbIdFromFfprobeTags({ imdb_id: 'tt1234567' })).toBe('tt1234567')
+  })
+
+  it('should extract from "imdb-id" key (hyphenated)', () => {
+    expect(extractImdbIdFromFfprobeTags({ 'imdb-id': 'tt1234567' })).toBe('tt1234567')
+  })
+
+  it('should extract from "IMDBID" key (no separator)', () => {
+    expect(extractImdbIdFromFfprobeTags({ IMDBID: 'tt1234567' })).toBe('tt1234567')
+  })
+
+  it('should handle IDs with more than 7 digits', () => {
+    expect(extractImdbIdFromFfprobeTags({ IMDB: 'tt12345678' })).toBe('tt12345678')
+  })
+
+  it('should trim whitespace from values', () => {
+    expect(extractImdbIdFromFfprobeTags({ IMDB: '  tt1234567  ' })).toBe('tt1234567')
+  })
+
+  it('should return undefined for invalid IMDB ID format', () => {
+    expect(extractImdbIdFromFfprobeTags({ IMDB: 'not-an-id' })).toBeUndefined()
+    expect(extractImdbIdFromFfprobeTags({ IMDB: '1234567' })).toBeUndefined()
+    expect(extractImdbIdFromFfprobeTags({ IMDB: 'tt123' })).toBeUndefined()
+    expect(extractImdbIdFromFfprobeTags({ IMDB: '' })).toBeUndefined()
+  })
+
+  it('should return undefined for IMDB ID embedded in a URL', () => {
+    expect(extractImdbIdFromFfprobeTags({ IMDB: 'https://www.imdb.com/title/tt1234567/' })).toBeUndefined()
+  })
+
+  it('should ignore unrelated keys even when they contain numbers', () => {
+    expect(extractImdbIdFromFfprobeTags({ encoder: 'Lavf58.76.100', duration: '7200' })).toBeUndefined()
+  })
+})
diff --git a/service/src/app-models/media/utils/extract-imdb-id-from-tags.ts b/service/src/app-models/media/utils/extract-imdb-id-from-tags.ts
new file mode 100644
index 00000000..33a1e77a
--- /dev/null
+++ b/service/src/app-models/media/utils/extract-imdb-id-from-tags.ts
@@ -0,0 +1,13 @@
+const IMDB_ID_PATTERN = /^tt\d{7,}$/
+
+export const extractImdbIdFromFfprobeTags = (tags: unknown): string | undefined => {
+  if (!tags || typeof tags !== 'object') return undefined
+  const record = tags as Record<string, unknown>
+  for (const key of Object.keys(record)) {
+    if (/^imdb[_-]?id$/i.test(key) || /^imdb$/i.test(key)) {
+      const value = String(record[key]).trim()
+      if (IMDB_ID_PATTERN.test(value)) return value
+    }
+  }
+  return undefined
+}
diff --git a/service/src/app-models/media/utils/link-movie.spec.ts b/service/src/app-models/media/utils/link-movie.spec.ts
index 797b6200..8da2e703 100644
--- a/service/src/app-models/media/utils/link-movie.spec.ts
+++ b/service/src/app-models/media/utils/link-movie.spec.ts
@@ -1,7 +1,7 @@
 import { Injector } from '@furystack/inject'
 import { usingAsync } from '@furystack/utils'
+import type { MovieFile, PiRatFile } from 'common'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import type { PiRatFile } from 'common'
 import { FfprobeService } from '../../../ffprobe-service.js'
 import { OmdbClientService } from '../metadata-services/omdb-client-service.js'
 import { TmdbClientService } from '../metadata-services/tmdb-client-service.js'
@@ -10,6 +10,7 @@ import { linkMovie } from './link-movie.js'
 const mockMovieFileStoreFind = vi.fn()
 const mockMovieFileStoreAdd = vi.fn()
 const mockOmdbStoreFind = vi.fn()
+const mockDriveGet = vi.fn()
 
 vi.mock('@furystack/repository', () => ({
   getDataSetFor: (_injector: unknown, model: { name?: string } | ((...args: unknown[]) => unknown)) => {
@@ -30,6 +31,11 @@ vi.mock('@furystack/repository', () => ({
         get: vi.fn().mockResolvedValue(null),
       }
     }
+    if (name === 'Drive') {
+      return {
+        get: (...args: unknown[]) => mockDriveGet(...args) as unknown,
+      }
+    }
     return {}
   },
 }))
@@ -77,13 +83,31 @@ vi.mock('./map-tmdb-to-localized.js', () => ({
   mapTmdbMovieToLocalized: vi.fn().mockReturnValue({}),
 }))
 
-const mockGetFfprobeForPiratFile = vi.fn().mockResolvedValue({ duration: 7200 })
+const mockExtractImdbIdFromFfprobeTags = vi.fn()
+vi.mock('./extract-imdb-id-from-tags.js', () => ({
+  extractImdbIdFromFfprobeTags: (...args: unknown[]) => mockExtractImdbIdFromFfprobeTags(...args) as unknown,
+}))
+
+const mockExtractImdbIdFromNfoFiles = vi.fn()
+vi.mock('./extract-imdb-id-from-nfo.js', () => ({
+  extractImdbIdFromNfoFiles: (...args: unknown[]) => mockExtractImdbIdFromNfoFiles(...args) as unknown,
+}))
+
+vi.mock('../../../utils/physical-path-utils.js', () => ({
+  getPhysicalParentPath: (_drive: unknown, file: { path: string }) =>
+    `/mnt/media/${file.path.split('/').slice(0, -1).join('/')}`,
+}))
+
+const mockGetFfprobeForPiratFile = vi.fn().mockResolvedValue({ format: { tags: {} }, duration: 7200 })
 const mockFetchOmdbMovieMetadata = vi.fn()
 const mockFetchTmdbMovieMetadata = vi.fn()
 
 describe('linkMovie', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    mockExtractImdbIdFromFfprobeTags.mockReturnValue(undefined)
+    mockExtractImdbIdFromNfoFiles.mockResolvedValue({ nfoFiles: [] })
+    mockDriveGet.mockResolvedValue({ letter: 'A', physicalPath: '/mnt/media' })
   })
 
   const createFile = (path: string): PiRatFile => ({
@@ -275,4 +299,115 @@ describe('linkMovie', () => {
       })
     })
   })
+
+  describe('linking via ffprobe tags', () => {
+    it('should link directly when ffprobe tags contain IMDB ID', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockExtractImdbIdFromFfprobeTags.mockReturnValue('tt9999999')
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id', path: 'movies/Tagged.Movie.2024.mkv', imdbId: 'tt9999999' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        const result = await linkMovie({
+          injector,
+          file: createFile('movies/Tagged.Movie.2024.mkv'),
+        })
+
+        expect(result.status).toBe('linked')
+        expect(mockMovieFileStoreAdd).toHaveBeenCalled()
+        expect(mockOmdbStoreFind).not.toHaveBeenCalled()
+        expect(mockFetchOmdbMovieMetadata).not.toHaveBeenCalled()
+        expect(mockFetchTmdbMovieMetadata).not.toHaveBeenCalled()
+      })
+    })
+
+    it('should skip .nfo scanning when ffprobe tags already have IMDB ID', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockExtractImdbIdFromFfprobeTags.mockReturnValue('tt8888888')
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        await linkMovie({
+          injector,
+          file: createFile('movies/Tagged.Movie.2024.mkv'),
+        })
+
+        expect(mockExtractImdbIdFromNfoFiles).not.toHaveBeenCalled()
+      })
+    })
+  })
+
+  describe('linking via .nfo files', () => {
+    it('should link when .nfo file contains IMDB ID', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockExtractImdbIdFromNfoFiles.mockResolvedValue({
+        imdbId: 'tt5555555',
+        nfoFiles: ['movies/movie.nfo'],
+      })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id', path: 'movies/Nfo.Movie.2024.mkv', imdbId: 'tt5555555' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        const result = await linkMovie({
+          injector,
+          file: createFile('movies/Nfo.Movie.2024.mkv'),
+        })
+
+        expect(result.status).toBe('linked')
+        expect(mockMovieFileStoreAdd).toHaveBeenCalled()
+        expect(mockOmdbStoreFind).not.toHaveBeenCalled()
+        expect(mockFetchOmdbMovieMetadata).not.toHaveBeenCalled()
+      })
+    })
+
+    it('should store .nfo files in relatedFiles when linking via .nfo', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockExtractImdbIdFromNfoFiles.mockResolvedValue({
+        imdbId: 'tt4444444',
+        nfoFiles: ['movies/movie.nfo', 'movies/extra.nfo'],
+      })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        await linkMovie({
+          injector,
+          file: createFile('movies/Nfo.Movie.2024.mkv'),
+        })
+
+        const addCall = mockMovieFileStoreAdd.mock.calls[0]
+        const addedEntity = addCall[1] as unknown as MovieFile
+        expect(addedEntity.relatedFiles).toEqual([
+          { type: 'info', path: 'movies/movie.nfo' },
+          { type: 'info', path: 'movies/extra.nfo' },
+        ])
+      })
+    })
+
+    it('should fall back to OMDB/TMDB when .nfo has no IMDB ID', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockExtractImdbIdFromNfoFiles.mockResolvedValue({
+        nfoFiles: ['movies/movie.nfo'],
+      })
+      mockOmdbStoreFind.mockResolvedValue([{ imdbID: 'tt1234567', Title: 'Test Movie', Year: '2024' }])
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        const result = await linkMovie({
+          injector,
+          file: createFile('movies/Test.Movie.2024.mkv'),
+        })
+
+        expect(result.status).toBe('linked')
+        expect(mockOmdbStoreFind).toHaveBeenCalled()
+      })
+    })
+  })
 })
diff --git a/service/src/app-models/media/utils/link-movie.ts b/service/src/app-models/media/utils/link-movie.ts
index fe952202..c064afdb 100644
--- a/service/src/app-models/media/utils/link-movie.ts
+++ b/service/src/app-models/media/utils/link-movie.ts
@@ -3,8 +3,10 @@ import { getLogger } from '@furystack/logging'
 import { getDataSetFor } from '@furystack/repository'
 import {
   Config,
+  Drive,
   getFallbackMetadata,
   getFileName,
+  getParentPath,
   isMovieFile,
   isSampleFile,
   MovieFile,
@@ -13,9 +15,12 @@ import {
   type PiRatFile,
 } from 'common'
 import { FfprobeService } from '../../../ffprobe-service.js'
+import { getPhysicalParentPath } from '../../../utils/physical-path-utils.js'
 import { OmdbClientService } from '../metadata-services/omdb-client-service.js'
 import { TmdbClientService } from '../metadata-services/tmdb-client-service.js'
 import { ensureMovieExists } from './ensure-movie-exists.js'
+import { extractImdbIdFromFfprobeTags } from './extract-imdb-id-from-tags.js'
+import { extractImdbIdFromNfoFiles } from './extract-imdb-id-from-nfo.js'
 import { ensureOmdbMovieExists } from './ensure-omdb-movie-exists.js'
 import { ensureOmdbSeriesExists } from './ensure-omdb-series-exists.js'
 import { ensureTmdbMovieExists } from './ensure-tmdb-movie-exists.js'
@@ -166,7 +171,57 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
 
   const ffprobeResult = await injector.getInstance(FfprobeService).getFfprobeForPiratFile(file)
 
-  // Check existing OMDB metadata first (backward compatibility)
+  // Try extracting IMDB ID directly from ffprobe tags or sibling .nfo files
+  const tagImdbId = extractImdbIdFromFfprobeTags(ffprobeResult.format?.tags)
+
+  const driveDataSet = getDataSetFor(injector, Drive, 'letter')
+  const drive = await driveDataSet.get(injector, driveLetter)
+
+  let nfoFiles: string[] = []
+  let nfoImdbId: string | undefined
+
+  if (!tagImdbId && drive) {
+    const physicalParent = getPhysicalParentPath(drive, file)
+    const relativeParent = getParentPath(file)
+    ;({ nfoFiles, imdbId: nfoImdbId } = await extractImdbIdFromNfoFiles(physicalParent, relativeParent))
+  }
+
+  const directImdbId = tagImdbId ?? nfoImdbId
+  const relatedFiles: Array<{ type: 'subtitle' | 'audio' | 'trailer' | 'info' | 'other'; path: string }> = nfoFiles.map(
+    (nfoPath) => ({ type: 'info' as const, path: nfoPath }),
+  )
+
+  if (directImdbId) {
+    const movie = await ensureMovieExists(
+      {
+        imdbId: directImdbId,
+        year,
+        season,
+        episode,
+        type: season != null && episode != null ? 'episode' : 'movie',
+      },
+      injector,
+    )
+
+    const {
+      created: [newMovieFile],
+    } = await movieFileDataSet.add(injector, {
+      driveLetter,
+      path,
+      imdbId: directImdbId,
+      ffprobe: ffprobeResult,
+      ...(relatedFiles.length > 0 ? { relatedFiles } : {}),
+    })
+
+    await logger.debug({
+      message: `File ${fileName} linked successfully (from ${tagImdbId ? 'ffprobe tags' : '.nfo file'}).`,
+      data: { file, movieFile: newMovieFile, movie, source: tagImdbId ? 'ffprobe-tags' : 'nfo-file' },
+    })
+
+    return { status: 'linked', movieFile: newMovieFile, movie } as const
+  }
+
+  // Check existing OMDB metadata (backward compatibility)
   const omdbDataSet = getDataSetFor(injector, OmdbMovieMetadata, 'imdbID')
   const storedResult = await omdbDataSet.find(injector, {
     filter: {

From d7e6764099c3c6ebe08d43e1dd3cfcd96427b355 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 12:04:57 +0100
Subject: [PATCH 09/30] ffmpeg session teardown fix

---
 .../actions/hls-session-teardown-action.ts    |  16 +-
 .../services/transcoding-session.spec.ts      | 137 ++++++++----------
 .../media/services/transcoding-session.ts     |  24 +--
 3 files changed, 74 insertions(+), 103 deletions(-)

diff --git a/service/src/app-models/media/actions/hls-session-teardown-action.ts b/service/src/app-models/media/actions/hls-session-teardown-action.ts
index e97b8ec2..d9627629 100644
--- a/service/src/app-models/media/actions/hls-session-teardown-action.ts
+++ b/service/src/app-models/media/actions/hls-session-teardown-action.ts
@@ -2,35 +2,25 @@ import { getLogger } from '@furystack/logging'
 import { RequestError } from '@furystack/rest'
 import { JsonResult } from '@furystack/rest-service'
 import type { RequestAction } from '@furystack/rest-service'
-import type { HlsSessionTeardownEndpoint, PlaybackMode } from 'common'
+import type { HlsSessionTeardownEndpoint } from 'common'
 import { TranscodingSessionService } from '../services/transcoding-session.js'
 
-const VALID_MODES: PlaybackMode[] = ['direct-play', 'remux', 'direct-stream', 'transcode']
-
 export const HlsSessionTeardownAction: RequestAction<HlsSessionTeardownEndpoint> = async ({
   injector,
   getUrlParams,
-  getQuery,
 }) => {
   const logger = getLogger(injector).withScope('HlsSessionTeardownAction')
   const { letter, path } = getUrlParams()
-  const query = getQuery()
 
   if (path.includes('..') || path.includes('\0')) {
     throw new RequestError('Invalid path', 400)
   }
 
-  const mode: PlaybackMode = query.mode || 'transcode'
-  if (!VALID_MODES.includes(mode)) {
-    throw new RequestError('Invalid playback mode', 400)
-  }
-
   const sessionService = injector.getInstance(TranscodingSessionService)
-  sessionService.removeSession(letter, path, mode, query.audioTrack ?? 0, query.resolution)
+  sessionService.removeAllSessionsForFile(letter, path)
 
   await logger.verbose({
-    message: `Tore down HLS session for ${letter}:${path}`,
-    data: { mode, audioTrack: query.audioTrack },
+    message: `Tore down HLS sessions for ${letter}:${path}`,
   })
 
   return JsonResult({ success: true })
diff --git a/service/src/app-models/media/services/transcoding-session.spec.ts b/service/src/app-models/media/services/transcoding-session.spec.ts
index 202a0811..8b658a86 100644
--- a/service/src/app-models/media/services/transcoding-session.spec.ts
+++ b/service/src/app-models/media/services/transcoding-session.spec.ts
@@ -691,92 +691,69 @@ describe('TranscodingSessionService', () => {
     })
   })
 
-  it('should remove all resolution variants when resolution is undefined', async () => {
-    const mockProcess = createMockProcess()
-    mockSpawn.mockReturnValue(mockProcess)
+  describe('removeAllSessionsForFile', () => {
+    it('should remove all sessions for a file regardless of mode, audioTrack, and resolution', async () => {
+      const mockProcess = createMockProcess()
+      mockSpawn.mockReturnValue(mockProcess)
 
-    await usingAsync(new Injector(), async (injector) => {
-      injector.setExplicitInstance(
-        { getFfprobeForPiratFile: vi.fn().mockResolvedValue(mockFfprobe) } as unknown as FfprobeService,
-        FfprobeService,
-      )
-      injector.setExplicitInstance(
-        { getEncoder: vi.fn().mockResolvedValue('libx264') } as unknown as HwAccelDetector,
-        HwAccelDetector,
-      )
+      await usingAsync(new Injector(), async (injector) => {
+        injector.setExplicitInstance(
+          { getFfprobeForPiratFile: vi.fn().mockResolvedValue(mockFfprobe) } as unknown as FfprobeService,
+          FfprobeService,
+        )
+        injector.setExplicitInstance(
+          { getEncoder: vi.fn().mockResolvedValue('libx264') } as unknown as HwAccelDetector,
+          HwAccelDetector,
+        )
 
-      const service = injector.getInstance(TranscodingSessionService)
-      try {
-        await service.getOrCreateSession({
-          driveLetter: 'A',
-          path: 'test.mkv',
-          mode: 'transcode',
-          resolution: '1080p',
-        })
-        await service.getOrCreateSession({
-          driveLetter: 'A',
-          path: 'test.mkv',
-          mode: 'transcode',
-          resolution: '720p',
-        })
-        await service.getOrCreateSession({
-          driveLetter: 'A',
-          path: 'other.mkv',
-          mode: 'transcode',
-          resolution: '1080p',
-        })
+        const service = injector.getInstance(TranscodingSessionService)
+        try {
+          await service.getOrCreateSession({
+            driveLetter: 'A',
+            path: 'test.mkv',
+            mode: 'transcode',
+            resolution: '1080p',
+          })
+          await service.getOrCreateSession({
+            driveLetter: 'A',
+            path: 'test.mkv',
+            mode: 'transcode',
+            resolution: '720p',
+          })
+          await service.getOrCreateSession({
+            driveLetter: 'A',
+            path: 'test.mkv',
+            mode: 'direct-stream',
+            audioTrackId: 1,
+          })
+          await service.getOrCreateSession({
+            driveLetter: 'A',
+            path: 'other.mkv',
+            mode: 'transcode',
+            resolution: '1080p',
+          })
 
-        expect(service.getActiveSessionCount()).toBe(3)
+          expect(service.getActiveSessionCount()).toBe(4)
 
-        service.removeSession('A', 'test.mkv', 'transcode', 0)
-        expect(service.getActiveSessionCount()).toBe(1)
-        expect(service.getSession('A', 'test.mkv', 'transcode', 0, '1080p')).toBeUndefined()
-        expect(service.getSession('A', 'test.mkv', 'transcode', 0, '720p')).toBeUndefined()
-        expect(service.getSession('A', 'other.mkv', 'transcode', 0, '1080p')).toBeDefined()
-      } finally {
-        service.dispose()
-      }
+          service.removeAllSessionsForFile('A', 'test.mkv')
+          expect(service.getActiveSessionCount()).toBe(1)
+          expect(service.getSession('A', 'other.mkv', 'transcode', 0, '1080p')).toBeDefined()
+        } finally {
+          service.dispose()
+        }
+      })
     })
-  })
-
-  it('should remove only exact match when resolution is specified', async () => {
-    const mockProcess = createMockProcess()
-    mockSpawn.mockReturnValue(mockProcess)
-
-    await usingAsync(new Injector(), async (injector) => {
-      injector.setExplicitInstance(
-        { getFfprobeForPiratFile: vi.fn().mockResolvedValue(mockFfprobe) } as unknown as FfprobeService,
-        FfprobeService,
-      )
-      injector.setExplicitInstance(
-        { getEncoder: vi.fn().mockResolvedValue('libx264') } as unknown as HwAccelDetector,
-        HwAccelDetector,
-      )
 
-      const service = injector.getInstance(TranscodingSessionService)
-      try {
-        await service.getOrCreateSession({
-          driveLetter: 'A',
-          path: 'test.mkv',
-          mode: 'transcode',
-          resolution: '1080p',
-        })
-        await service.getOrCreateSession({
-          driveLetter: 'A',
-          path: 'test.mkv',
-          mode: 'transcode',
-          resolution: '720p',
-        })
-
-        expect(service.getActiveSessionCount()).toBe(2)
-
-        service.removeSession('A', 'test.mkv', 'transcode', 0, '1080p')
-        expect(service.getActiveSessionCount()).toBe(1)
-        expect(service.getSession('A', 'test.mkv', 'transcode', 0, '1080p')).toBeUndefined()
-        expect(service.getSession('A', 'test.mkv', 'transcode', 0, '720p')).toBeDefined()
-      } finally {
-        service.dispose()
-      }
+    it('should handle no matching sessions gracefully', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const service = injector.getInstance(TranscodingSessionService)
+        try {
+          service.removeAllSessionsForFile('Z', 'nonexistent.mkv')
+          expect(service.getActiveSessionCount()).toBe(0)
+        } finally {
+          service.dispose()
+        }
+      })
     })
   })
 
diff --git a/service/src/app-models/media/services/transcoding-session.ts b/service/src/app-models/media/services/transcoding-session.ts
index 86121bd6..e8988ed5 100644
--- a/service/src/app-models/media/services/transcoding-session.ts
+++ b/service/src/app-models/media/services/transcoding-session.ts
@@ -415,22 +415,26 @@ export class TranscodingSessionService {
     audioTrackId: number = 0,
     resolution?: string,
   ) {
-    if (resolution !== undefined) {
-      const key = this.buildSessionKey(driveLetter, path, mode, audioTrackId, resolution)
-      const session = this.sessions.get(key)
-      if (session) {
-        this.destroySession(session)
-        this.sessions.delete(key)
-      }
-      return
+    const key = this.buildSessionKey(driveLetter, path, mode, audioTrackId, resolution)
+    const session = this.sessions.get(key)
+    if (session) {
+      this.destroySession(session)
+      this.sessions.delete(key)
     }
+  }
 
-    const prefix = `${driveLetter}:${path}:${mode}:${audioTrackId}:`
+  /**
+   * Removes all transcoding sessions for a given file, regardless of mode,
+   * audio track, or resolution. Used when a client disconnects or navigates
+   * away — there is no reason to keep any session alive for that file.
+   */
+  public removeAllSessionsForFile(driveLetter: string, path: string) {
+    const prefix = `${driveLetter}:${path}:`
     const keysToRemove = [...this.sessions.keys()].filter((k) => k.startsWith(prefix))
     for (const key of keysToRemove) {
       const session = this.sessions.get(key)
       if (session) {
-        void this.logger.verbose({ message: `Removing session: ${key}` })
+        void this.logger.verbose({ message: `Removing session for file teardown: ${key}` })
         this.destroySession(session)
         this.sessions.delete(key)
       }

From 971d04389f10c3a6a4b747432c117011d4c2daee Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 12:32:26 +0100
Subject: [PATCH 10/30] movie duration fix

---
 .../media/actions/hls-stream-action.spec.ts   |  1 +
 .../services/transcoding-session.spec.ts      | 69 ++++++++++++++++++-
 .../media/services/transcoding-session.ts     | 65 +++++++++++++++--
 3 files changed, 129 insertions(+), 6 deletions(-)

diff --git a/service/src/app-models/media/actions/hls-stream-action.spec.ts b/service/src/app-models/media/actions/hls-stream-action.spec.ts
index 63680b5c..e5edd744 100644
--- a/service/src/app-models/media/actions/hls-stream-action.spec.ts
+++ b/service/src/app-models/media/actions/hls-stream-action.spec.ts
@@ -38,6 +38,7 @@ const mockSession = {
   driveLetter: 'A',
   path: 'test.mkv',
   audioTrackId: 0,
+  totalDuration: 16,
   createdAt: Date.now(),
   lastAccessedAt: Date.now(),
   ffmpegProcess: { killed: false, kill: vi.fn() },
diff --git a/service/src/app-models/media/services/transcoding-session.spec.ts b/service/src/app-models/media/services/transcoding-session.spec.ts
index 8b658a86..615c0893 100644
--- a/service/src/app-models/media/services/transcoding-session.spec.ts
+++ b/service/src/app-models/media/services/transcoding-session.spec.ts
@@ -655,9 +655,9 @@ describe('TranscodingSessionService', () => {
       if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true })
     })
 
-    it('should return playlist content when file exists', async () => {
+    it('should return playlist content when file exists and has ENDLIST', async () => {
       vi.useRealTimers()
-      const playlistContent = '#EXTM3U\n#EXT-X-VERSION:7\nsegment0.m4s\n'
+      const playlistContent = '#EXTM3U\n#EXT-X-VERSION:7\n#EXT-X-ENDLIST\n'
       writeFileSync(join(testDir, 'playlist.m3u8'), playlistContent)
 
       const service = new TranscodingSessionService()
@@ -665,6 +665,7 @@ describe('TranscodingSessionService', () => {
         const mockSession = {
           sessionDir: testDir,
           state: 'running' as const,
+          totalDuration: 60,
         } as Parameters<typeof service.readPlaylist>[0]
 
         const result = await service.readPlaylist(mockSession)
@@ -674,6 +675,69 @@ describe('TranscodingSessionService', () => {
       }
     })
 
+    it('should pad playlist with remaining segments when ENDLIST is missing', async () => {
+      vi.useRealTimers()
+      const playlistContent = [
+        '#EXTM3U',
+        '#EXT-X-VERSION:7',
+        '#EXT-X-TARGETDURATION:6',
+        '#EXT-X-MAP:URI="init.mp4"',
+        '#EXTINF:6.000000,',
+        'segment0.m4s',
+        '#EXTINF:6.000000,',
+        'segment1.m4s',
+        '',
+      ].join('\n')
+      writeFileSync(join(testDir, 'playlist.m3u8'), playlistContent)
+
+      const service = new TranscodingSessionService()
+      try {
+        const mockSession = {
+          sessionDir: testDir,
+          state: 'running' as const,
+          totalDuration: 30,
+        } as Parameters<typeof service.readPlaylist>[0]
+
+        const result = await service.readPlaylist(mockSession)
+        expect(result).toContain('#EXT-X-ENDLIST')
+        expect(result).toContain('segment2.m4s')
+        expect(result).toContain('segment3.m4s')
+        expect(result).toContain('segment4.m4s')
+      } finally {
+        service.dispose()
+      }
+    })
+
+    it('should add ENDLIST when all segments are already encoded', async () => {
+      vi.useRealTimers()
+      const playlistContent = [
+        '#EXTM3U',
+        '#EXT-X-VERSION:7',
+        '#EXT-X-TARGETDURATION:6',
+        '#EXTINF:6.000000,',
+        'segment0.m4s',
+        '#EXTINF:6.000000,',
+        'segment1.m4s',
+        '',
+      ].join('\n')
+      writeFileSync(join(testDir, 'playlist.m3u8'), playlistContent)
+
+      const service = new TranscodingSessionService()
+      try {
+        const mockSession = {
+          sessionDir: testDir,
+          state: 'running' as const,
+          totalDuration: 12,
+        } as Parameters<typeof service.readPlaylist>[0]
+
+        const result = await service.readPlaylist(mockSession)
+        expect(result).toContain('#EXT-X-ENDLIST')
+        expect(result).not.toContain('segment2.m4s')
+      } finally {
+        service.dispose()
+      }
+    })
+
     it('should return null when session errors before playlist is created', async () => {
       vi.useRealTimers()
       const service = new TranscodingSessionService()
@@ -681,6 +745,7 @@ describe('TranscodingSessionService', () => {
         const mockSession = {
           sessionDir: testDir,
           state: 'error' as const,
+          totalDuration: 60,
         } as Parameters<typeof service.readPlaylist>[0]
 
         const result = await service.readPlaylist(mockSession)
diff --git a/service/src/app-models/media/services/transcoding-session.ts b/service/src/app-models/media/services/transcoding-session.ts
index e8988ed5..bc889c02 100644
--- a/service/src/app-models/media/services/transcoding-session.ts
+++ b/service/src/app-models/media/services/transcoding-session.ts
@@ -27,6 +27,7 @@ type TranscodingSessionEntry = {
   path: string
   audioTrackId: number
   resolution?: string
+  totalDuration: number
   createdAt: number
   lastAccessedAt: number
 }
@@ -169,7 +170,7 @@ export class TranscodingSessionService {
       mkdirSync(sessionDir, { recursive: true })
     }
 
-    const ffmpegArgs = await this.buildHlsFfmpegArgs({
+    const { args: ffmpegArgs, totalDuration } = await this.buildHlsFfmpegArgs({
       driveLetter,
       path,
       mode,
@@ -197,6 +198,7 @@ export class TranscodingSessionService {
       path,
       audioTrackId,
       resolution,
+      totalDuration,
       createdAt: Date.now(),
       lastAccessedAt: Date.now(),
     }
@@ -280,7 +282,61 @@ export class TranscodingSessionService {
     const playlistPath = join(session.sessionDir, 'playlist.m3u8')
     const ready = await this.waitForFile(playlistPath, session)
     if (!ready) return null
-    return readFile(playlistPath, 'utf-8')
+    const content = await readFile(playlistPath, 'utf-8')
+    return this.padPlaylistToFullDuration(content, session.totalDuration)
+  }
+
+  /**
+   * If the playlist is still being written by FFmpeg (no #EXT-X-ENDLIST),
+   * pad it with the remaining expected segments so that clients see the
+   * full VOD duration from the first request. The segment-serving endpoint
+   * already waits for segments that haven't been transcoded yet.
+   */
+  private padPlaylistToFullDuration(playlist: string, totalDuration: number): string {
+    if (totalDuration <= 0 || playlist.includes('#EXT-X-ENDLIST')) {
+      return playlist
+    }
+
+    const lines = playlist.split('\n')
+
+    let encodedDuration = 0
+    let maxSegmentIndex = -1
+    for (const line of lines) {
+      const extinfMatch = line.match(/^#EXTINF:([\d.]+)/)
+      if (extinfMatch) {
+        encodedDuration += parseFloat(extinfMatch[1])
+      }
+      const segmentMatch = line.match(/^segment(\d+)\.m4s/)
+      if (segmentMatch) {
+        maxSegmentIndex = Math.max(maxSegmentIndex, parseInt(segmentMatch[1], 10))
+      }
+    }
+
+    const remainingDuration = totalDuration - encodedDuration
+    if (remainingDuration <= 0) {
+      return `${playlist.trimEnd()}\n#EXT-X-ENDLIST\n`
+    }
+
+    const fullSegmentCount = Math.floor(remainingDuration / SEGMENT_DURATION)
+    const lastSegmentDuration = remainingDuration - fullSegmentCount * SEGMENT_DURATION
+
+    const padLines: string[] = []
+    let nextIndex = maxSegmentIndex + 1
+
+    for (let i = 0; i < fullSegmentCount; i++) {
+      padLines.push(`#EXTINF:${SEGMENT_DURATION.toFixed(6)},`)
+      padLines.push(`segment${nextIndex}.m4s`)
+      nextIndex++
+    }
+
+    if (lastSegmentDuration > 0.01) {
+      padLines.push(`#EXTINF:${lastSegmentDuration.toFixed(6)},`)
+      padLines.push(`segment${nextIndex}.m4s`)
+    }
+
+    padLines.push('#EXT-X-ENDLIST')
+
+    return `${playlist.trimEnd()}\n${padLines.join('\n')}\n`
   }
 
   private async buildHlsFfmpegArgs({
@@ -297,7 +353,7 @@ export class TranscodingSessionService {
     audioTrackId: number
     resolution?: string
     sessionDir: string
-  }): Promise<string[]> {
+  }): Promise<{ args: string[]; totalDuration: number }> {
     const [drive, config, ffprobe] = await Promise.all([
       (async () => {
         const driveDataSet = getDataSetFor(this.injector, Drive, 'letter')
@@ -313,6 +369,7 @@ export class TranscodingSessionService {
 
     if (!drive) throw new Error(`Drive ${driveLetter} not found`)
 
+    const totalDuration = parseFloat(ffprobe.format.duration ?? '0') || 0
     const fullPath = join(drive.physicalPath, path)
     const audioStreams = ffprobe.streams.filter((s) => s.codec_type === 'audio')
     const audioStream = audioStreams.find((t) => t.index === audioTrackId) || audioStreams[0]
@@ -401,7 +458,7 @@ export class TranscodingSessionService {
     args.push('-hls_list_size', '0')
     args.push('-y', join(sessionDir, 'playlist.m3u8'))
 
-    return args
+    return { args, totalDuration }
   }
 
   public getActiveSessionCount(): number {

From e9fbffc13b4359eaa3eb9aab8fc912d45aa9dcf7 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 14:13:54 +0100
Subject: [PATCH 11/30] improved playback quality controls

---
 .../movie-player-service.spec.ts              | 110 ++++++++++++++++++
 .../movie-player-v2/movie-player-service.ts   |  40 ++++++-
 .../movie-player-v2-component.spec.ts         |  53 ++++++++-
 .../movie-player-v2-component.tsx             |  20 +++-
 .../services/hls-manifest-generator.spec.ts   |  37 ++++++
 .../media/services/hls-manifest-generator.ts  |   1 +
 6 files changed, 253 insertions(+), 8 deletions(-)

diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
index e235806d..2eaa0532 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
@@ -252,3 +252,113 @@ describe('audioCodecs', () => {
     expect(audioCodecs.opus).toBe('opus')
   })
 })
+
+describe('switchResolution', () => {
+  let api: ReturnType<typeof createMockApi>
+
+  beforeEach(() => {
+    api = createMockApi()
+    vi.clearAllMocks()
+  })
+
+  it('should force transcode mode when a specific resolution is selected', async () => {
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
+        })
+
+        expect(service.playbackMode.getValue()).toBe('remux')
+
+        await service.switchResolution('720p')
+        expect(service.resolution.getValue()).toBe('720p')
+        expect(service.playbackMode.getValue()).toBe('transcode')
+      },
+    )
+  })
+
+  it('should restore original playback mode when switching to Auto', async () => {
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
+        })
+
+        expect(service.playbackMode.getValue()).toBe('remux')
+
+        await service.switchResolution('720p')
+        expect(service.playbackMode.getValue()).toBe('transcode')
+
+        await service.switchResolution(undefined)
+        expect(service.resolution.getValue()).toBeUndefined()
+        expect(service.playbackMode.getValue()).toBe('remux')
+      },
+    )
+  })
+
+  it('should preserve playback progress across resolution switches', async () => {
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 50, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
+        })
+
+        const mockVideo = { currentTime: 75 } as HTMLVideoElement
+        service.videoElement = mockVideo
+
+        await service.switchResolution('480p')
+        expect(service.progress.getValue()).toBe(50)
+      },
+    )
+  })
+
+  it('should stay in transcode mode when already transcoding', async () => {
+    const transcodeResponse: PlaybackInfoResponse = {
+      ...mockPlaybackInfoResponse,
+      mode: 'transcode',
+    }
+    api.call.mockResolvedValue({ result: transcodeResponse })
+
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
+        })
+
+        expect(service.playbackMode.getValue()).toBe('transcode')
+
+        await service.switchResolution('720p')
+        expect(service.playbackMode.getValue()).toBe('transcode')
+
+        await service.switchResolution(undefined)
+        expect(service.playbackMode.getValue()).toBe('transcode')
+      },
+    )
+  })
+
+  it('should call teardown before switching', async () => {
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
+        })
+
+        api.call.mockClear()
+
+        await service.switchResolution('720p')
+
+        expect(api.call).toHaveBeenCalledWith(
+          expect.objectContaining({
+            method: 'DELETE',
+            action: '/files/:letter/:path/hls-session',
+          }),
+        )
+      },
+    )
+  })
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index 2fbd3a9f..ad15af37 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -58,6 +58,8 @@ const buildCodecSupportMap = () => {
   }
 }
 
+export type ResolutionValue = '4k' | '1080p' | '720p' | '480p' | '360p'
+
 export class MoviePlayerService implements AsyncDisposable {
   constructor(
     private readonly file: PiRatFile,
@@ -72,11 +74,12 @@ export class MoviePlayerService implements AsyncDisposable {
   }
 
   private hls: Hls | null = null
+  private originalPlaybackMode: PlaybackMode = 'transcode'
   public videoElement: HTMLVideoElement | null = null
   public audioTrackId = new ObservableValue(0)
   public playbackInfo = new ObservableValue<PlaybackInfoResponse | null>(null)
   public playbackMode = new ObservableValue<PlaybackMode>('transcode')
-  public resolution = new ObservableValue<'4k' | '1080p' | '720p' | '480p' | '360p' | undefined>(undefined)
+  public resolution = new ObservableValue<ResolutionValue | undefined>(undefined)
   public progress: ObservableValue<number>
 
   public async [Symbol.asyncDispose]() {
@@ -117,7 +120,10 @@ export class MoviePlayerService implements AsyncDisposable {
   }
 
   private async initialize() {
-    await this.fetchPlaybackInfo()
+    const info = await this.fetchPlaybackInfo()
+    if (info) {
+      this.originalPlaybackMode = info.mode
+    }
   }
 
   public async fetchPlaybackInfo(selectedSubtitleTrackIndex?: number): Promise<PlaybackInfoResponse | null> {
@@ -175,7 +181,8 @@ export class MoviePlayerService implements AsyncDisposable {
       this.hls = null
     }
 
-    if (info.mode === 'direct-play') {
+    const mode = this.playbackMode.getValue()
+    if (mode === 'direct-play') {
       this.startDirectPlayback(videoElement, info)
     } else {
       void this.startHlsPlayback(videoElement)
@@ -293,6 +300,33 @@ export class MoviePlayerService implements AsyncDisposable {
     }
   }
 
+  /**
+   * Switches resolution and restarts playback. Forces transcode mode when a
+   * specific resolution is requested; restores the original mode on "Auto".
+   */
+  public async switchResolution(value: ResolutionValue | undefined) {
+    const previousProgress = this.videoElement?.currentTime ?? this.progress.getValue()
+    await this.teardownHlsSession()
+
+    this.resolution.setValue(value)
+    this.currentProgress = previousProgress
+
+    if (value) {
+      if (this.playbackMode.getValue() !== 'transcode') {
+        this.playbackMode.setValue('transcode')
+      }
+    } else {
+      this.playbackMode.setValue(this.originalPlaybackMode)
+    }
+
+    if (this.videoElement) {
+      const info = this.playbackInfo.getValue()
+      if (info) {
+        this.startPlayback(this.videoElement, info)
+      }
+    }
+  }
+
   public getAudioTrackInfoFromPlaybackInfo(): AudioTrackInfo[] {
     return this.playbackInfo.getValue()?.audioTracks ?? []
   }
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.spec.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.spec.ts
index 4d9fb164..c73e463c 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.spec.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.spec.ts
@@ -11,8 +11,9 @@ import { getSubtitleTracks, getSubtitleTracksFromPlaybackInfo } from './get-subt
  * and get-subtitle-tracks.spec.tsx.
  */
 
+type Rendition = { id: string; width: number; height: number; src: string; selected: boolean }
+
 const buildRenditionList = (height: number, currentValue?: string) => {
-  type Rendition = { id: string; width: number; height: number; src: string; selected: boolean }
   const renditions: Rendition[] = [
     ...(height >= 2160 ? [{ id: '4k', width: 3840, height: 2160, src: '', selected: currentValue === '4k' }] : []),
     ...(height >= 1080
@@ -25,6 +26,16 @@ const buildRenditionList = (height: number, currentValue?: string) => {
   return renditions
 }
 
+const createRenditionList = (items: Rendition[], selectedIndex: number) => {
+  const target = new EventTarget()
+  return Object.assign([...items], {
+    addEventListener: target.addEventListener.bind(target),
+    removeEventListener: target.removeEventListener.bind(target),
+    dispatchEvent: target.dispatchEvent.bind(target),
+    selectedIndex,
+  })
+}
+
 const mapAudioTracksForMediaChrome = (audioTracks: AudioTrackInfo[]) =>
   audioTracks.map((track, index) => ({
     id: track.index.toFixed(0),
@@ -66,6 +77,46 @@ describe('MoviePlayerV2 component logic', () => {
     })
   })
 
+  describe('createRenditionList', () => {
+    it('should implement EventTarget methods', () => {
+      const items = buildRenditionList(1080)
+      const list = createRenditionList(items, -1)
+
+      expect(typeof list.addEventListener).toBe('function')
+      expect(typeof list.removeEventListener).toBe('function')
+      expect(typeof list.dispatchEvent).toBe('function')
+    })
+
+    it('should expose selectedIndex', () => {
+      const items = buildRenditionList(1080, '720p')
+      const selectedIdx = items.findIndex((r) => r.selected)
+      const list = createRenditionList(items, selectedIdx)
+
+      expect(list.selectedIndex).toBe(1)
+    })
+
+    it('should be array-like with rendition items', () => {
+      const items = buildRenditionList(1080)
+      const list = createRenditionList(items, -1)
+
+      expect(list).toHaveLength(4)
+      expect(list[0].id).toBe('1080p')
+      expect(list[3].id).toBe('360p')
+    })
+
+    it('should allow adding and dispatching events', () => {
+      const items = buildRenditionList(720)
+      const list = createRenditionList(items, 0)
+
+      let eventFired = false
+      list.addEventListener('change', () => {
+        eventFired = true
+      })
+      list.dispatchEvent(new Event('change'))
+      expect(eventFired).toBe(true)
+    })
+  })
+
   describe('mapAudioTracksForMediaChrome', () => {
     it('should map audio tracks with correct ids and labels', () => {
       const tracks: AudioTrackInfo[] = [
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
index 2e247512..90e8386d 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
@@ -10,6 +10,16 @@ import { getSubtitleTracks, getSubtitleTracksFromPlaybackInfo } from './get-subt
 import './media-chrome.js'
 import { MoviePlayerService } from './movie-player-service.js'
 
+const createRenditionList = (items: Rendition[], selectedIndex: number) => {
+  const target = new EventTarget()
+  return Object.assign([...items], {
+    addEventListener: target.addEventListener.bind(target),
+    removeEventListener: target.removeEventListener.bind(target),
+    dispatchEvent: target.dispatchEvent.bind(target),
+    selectedIndex,
+  })
+}
+
 type MoviePlayerProps = {
   file: PiRatFile
   ffprobe: FfprobeData
@@ -129,9 +139,9 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
                   const { value } = ev.currentTarget as HTMLInputElement
 
                   if (validValues.includes(value as (typeof validValues)[number])) {
-                    mediaService.resolution.setValue(value as (typeof validValues)[number])
+                    void mediaService.switchResolution(value as (typeof validValues)[number])
                   } else {
-                    mediaService.resolution.setValue(undefined)
+                    void mediaService.switchResolution(undefined)
                   }
                 }}
               >
@@ -184,7 +194,7 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
 
               const video = ev.currentTarget as HTMLVideoElement & {
                 audioTracks: AudioTrack[]
-                videoRenditions: Rendition[]
+                videoRenditions: ReturnType<typeof createRenditionList>
               }
 
               video.audioTracks = audioTracks.map((track, index) => ({
@@ -199,7 +209,7 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
               const videoStream = props.ffprobe.streams.find((stream) => stream.codec_type === 'video')
               const height = videoStream?.height || 1080
 
-              video.videoRenditions = [
+              const renditionItems: Rendition[] = [
                 ...(height >= 2160
                   ? [{ id: '4k', width: 3840, height: 2160, src: '', selected: currentValue === '4k' }]
                   : []),
@@ -214,6 +224,8 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
                   : []),
                 { id: '360p', width: 640, height: 360, src: '', selected: currentValue === '360p' },
               ]
+              const selectedIdx = renditionItems.findIndex((r) => r.selected)
+              video.videoRenditions = createRenditionList(renditionItems, selectedIdx)
 
               if (video.audioTracks[0]) {
                 mediaService.audioTrackId.setValue(parseInt(video.audioTracks[0].id as string, 10))
diff --git a/service/src/app-models/media/services/hls-manifest-generator.spec.ts b/service/src/app-models/media/services/hls-manifest-generator.spec.ts
index b75aaca4..e0fad3fb 100644
--- a/service/src/app-models/media/services/hls-manifest-generator.spec.ts
+++ b/service/src/app-models/media/services/hls-manifest-generator.spec.ts
@@ -115,9 +115,46 @@ describe('generateMasterPlaylist', () => {
       subtitleTracks: [],
     })
 
+    expect(playlist).not.toContain('RESOLUTION=3840x2160')
     expect(playlist).not.toContain('RESOLUTION=1920x1080')
     expect(playlist).toContain('RESOLUTION=1280x720')
     expect(playlist).toContain('RESOLUTION=854x480')
     expect(playlist).toContain('RESOLUTION=640x360')
   })
+
+  it('should include 4K variant for 4K sources in transcode mode', () => {
+    const ffprobe = createFfprobe({
+      streams: [
+        { index: 0, codec_type: 'video', codec_name: 'hevc', width: 3840, height: 2160, tags: {} },
+        { index: 1, codec_type: 'audio', codec_name: 'aac', channels: 2, tags: {} },
+      ],
+    })
+
+    const playlist = generateMasterPlaylist({
+      ffprobe,
+      file: { driveLetter: 'A', path: 'movies/test-4k.mkv' },
+      mode: 'transcode',
+      baseUrl: '/api/media',
+      subtitleTracks: [],
+    })
+
+    expect(playlist).toContain('RESOLUTION=3840x2160')
+    expect(playlist).toContain('RESOLUTION=1920x1080')
+    expect(playlist).toContain('RESOLUTION=1280x720')
+    expect(playlist).toContain('RESOLUTION=854x480')
+    expect(playlist).toContain('RESOLUTION=640x360')
+  })
+
+  it('should not include 4K variant for 1080p sources in transcode mode', () => {
+    const playlist = generateMasterPlaylist({
+      ffprobe: createFfprobe(),
+      file: { driveLetter: 'A', path: 'movies/test.mkv' },
+      mode: 'transcode',
+      baseUrl: '/api/media',
+      subtitleTracks: [],
+    })
+
+    expect(playlist).not.toContain('RESOLUTION=3840x2160')
+    expect(playlist).toContain('RESOLUTION=1920x1080')
+  })
 })
diff --git a/service/src/app-models/media/services/hls-manifest-generator.ts b/service/src/app-models/media/services/hls-manifest-generator.ts
index 5bfabddd..a9ea952c 100644
--- a/service/src/app-models/media/services/hls-manifest-generator.ts
+++ b/service/src/app-models/media/services/hls-manifest-generator.ts
@@ -9,6 +9,7 @@ export type HlsVariant = {
 }
 
 const DEFAULT_VARIANTS: HlsVariant[] = [
+  { resolution: '3840x2160', width: 3840, height: 2160, bandwidth: 15000000 },
   { resolution: '1920x1080', width: 1920, height: 1080, bandwidth: 5000000 },
   { resolution: '1280x720', width: 1280, height: 720, bandwidth: 2800000 },
   { resolution: '854x480', width: 854, height: 480, bandwidth: 1400000 },

From 09e2037ea31603e31a032ed5e805f910824ed56b Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 14:26:54 +0100
Subject: [PATCH 12/30] improvements on quality switching

---
 common/schemas/media-api.json                 |  3 ++
 common/src/apis/media.ts                      |  2 +-
 .../movie-player-service.spec.ts              |  2 +-
 .../movie-player-v2/movie-player-service.ts   |  5 ++-
 .../media/actions/hls-master-action.ts        |  1 +
 .../services/hls-manifest-generator.spec.ts   | 43 +++++++++++++++++++
 .../media/services/hls-manifest-generator.ts  |  8 +++-
 7 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/common/schemas/media-api.json b/common/schemas/media-api.json
index 98f1b3cd..f4a3e5a7 100644
--- a/common/schemas/media-api.json
+++ b/common/schemas/media-api.json
@@ -10489,6 +10489,9 @@
             },
             "containers": {
               "type": "string"
+            },
+            "audioTrack": {
+              "type": "number"
             }
           },
           "additionalProperties": false
diff --git a/common/src/apis/media.ts b/common/src/apis/media.ts
index e501c734..cd2b1204 100644
--- a/common/src/apis/media.ts
+++ b/common/src/apis/media.ts
@@ -177,7 +177,7 @@ export type PlaybackInfoResponse = {
 
 export type HlsMasterEndpoint = {
   url: { letter: string; path: string }
-  query: { mode?: PlaybackMode; videoCodecs?: string; audioCodecs?: string; containers?: string }
+  query: { mode?: PlaybackMode; videoCodecs?: string; audioCodecs?: string; containers?: string; audioTrack?: number }
   result: unknown
 }
 
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
index 2eaa0532..3c48cffc 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
@@ -310,7 +310,7 @@ describe('switchResolution', () => {
         service.videoElement = mockVideo
 
         await service.switchResolution('480p')
-        expect(service.progress.getValue()).toBe(50)
+        expect(service.progress.getValue()).toBe(75)
       },
     )
   })
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index ad15af37..208b8373 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -204,8 +204,10 @@ export class MoviePlayerService implements AsyncDisposable {
 
   private async startHlsPlayback(videoElement: HTMLVideoElement) {
     const mode = this.playbackMode.getValue()
+    const audioTrack = this.audioTrackId.getValue()
+    const audioParam = audioTrack ? `&audioTrack=${encode(String(audioTrack))}` : ''
     const hlsUrl = this.toServiceUrl(
-      `/api/media/files/${encodeURIComponent(this.file.driveLetter)}/${encodeURIComponent(this.file.path)}/master.m3u8?mode=${encode(mode)}`,
+      `/api/media/files/${encodeURIComponent(this.file.driveLetter)}/${encodeURIComponent(this.file.path)}/master.m3u8?mode=${encode(mode)}${audioParam}`,
     )
 
     const HlsModule = await loadHls()
@@ -310,6 +312,7 @@ export class MoviePlayerService implements AsyncDisposable {
 
     this.resolution.setValue(value)
     this.currentProgress = previousProgress
+    this.progress.setValue(previousProgress)
 
     if (value) {
       if (this.playbackMode.getValue() !== 'transcode') {
diff --git a/service/src/app-models/media/actions/hls-master-action.ts b/service/src/app-models/media/actions/hls-master-action.ts
index a092de67..2f380c3a 100644
--- a/service/src/app-models/media/actions/hls-master-action.ts
+++ b/service/src/app-models/media/actions/hls-master-action.ts
@@ -59,6 +59,7 @@ export const HlsMasterAction: RequestAction<HlsMasterEndpoint> = async ({
     mode,
     baseUrl: '/api/media',
     subtitleTracks,
+    audioTrack: query.audioTrack,
   })
 
   await logger.verbose({ message: `Generated master playlist for ${letter}:${path}`, data: { mode } })
diff --git a/service/src/app-models/media/services/hls-manifest-generator.spec.ts b/service/src/app-models/media/services/hls-manifest-generator.spec.ts
index e0fad3fb..8355708e 100644
--- a/service/src/app-models/media/services/hls-manifest-generator.spec.ts
+++ b/service/src/app-models/media/services/hls-manifest-generator.spec.ts
@@ -157,4 +157,47 @@ describe('generateMasterPlaylist', () => {
     expect(playlist).not.toContain('RESOLUTION=3840x2160')
     expect(playlist).toContain('RESOLUTION=1920x1080')
   })
+
+  it('should propagate audioTrack into variant URLs for transcode mode', () => {
+    const playlist = generateMasterPlaylist({
+      ffprobe: createFfprobe(),
+      file: { driveLetter: 'A', path: 'movies/test.mkv' },
+      mode: 'transcode',
+      baseUrl: '/api/media',
+      subtitleTracks: [],
+      audioTrack: 2,
+    })
+
+    expect(playlist).toContain('audioTrack')
+    const variantLines = playlist.split('\n').filter((l) => l.includes('stream.m3u8'))
+    for (const line of variantLines) {
+      expect(line).toContain('audioTrack')
+    }
+  })
+
+  it('should propagate audioTrack into variant URL for remux mode', () => {
+    const playlist = generateMasterPlaylist({
+      ffprobe: createFfprobe(),
+      file: { driveLetter: 'A', path: 'movies/test.mkv' },
+      mode: 'remux',
+      baseUrl: '/api/media',
+      subtitleTracks: [],
+      audioTrack: 3,
+    })
+
+    const variantLine = playlist.split('\n').find((l) => l.includes('stream.m3u8'))
+    expect(variantLine).toContain('audioTrack')
+  })
+
+  it('should not include audioTrack when not specified', () => {
+    const playlist = generateMasterPlaylist({
+      ffprobe: createFfprobe(),
+      file: { driveLetter: 'A', path: 'movies/test.mkv' },
+      mode: 'transcode',
+      baseUrl: '/api/media',
+      subtitleTracks: [],
+    })
+
+    expect(playlist).not.toContain('audioTrack')
+  })
 })
diff --git a/service/src/app-models/media/services/hls-manifest-generator.ts b/service/src/app-models/media/services/hls-manifest-generator.ts
index a9ea952c..a14e16da 100644
--- a/service/src/app-models/media/services/hls-manifest-generator.ts
+++ b/service/src/app-models/media/services/hls-manifest-generator.ts
@@ -22,12 +22,14 @@ export const generateMasterPlaylist = ({
   mode,
   baseUrl,
   subtitleTracks,
+  audioTrack,
 }: {
   ffprobe: FfprobeData
   file: { driveLetter: string; path: string }
   mode: PlaybackMode
   baseUrl: string
   subtitleTracks: SubtitleTrackInfo[]
+  audioTrack?: number
 }): string => {
   const lines: string[] = ['#EXTM3U', '#EXT-X-VERSION:7']
 
@@ -47,11 +49,13 @@ export const generateMasterPlaylist = ({
   const sourceWidth = videoStream?.width || 1920
   const sourceBitrate = ffprobe.format.bit_rate || 5000000
 
+  const audioTrackQuery = audioTrack !== undefined ? { audioTrack } : {}
+
   if (mode === 'remux' || mode === 'direct-play' || mode === 'direct-stream') {
     const subtitleGroup = subtitleTracks.filter((t) => !t.requiresBurnIn).length > 0 ? ',SUBTITLES="subs"' : ''
     lines.push(
       `#EXT-X-STREAM-INF:BANDWIDTH=${sourceBitrate},RESOLUTION=${sourceWidth}x${sourceHeight},CODECS="${getCodecString(ffprobe)}"${subtitleGroup}`,
-      `${streamBase}/stream.m3u8?${serializeToQueryString({ mode })}`,
+      `${streamBase}/stream.m3u8?${serializeToQueryString({ mode, ...audioTrackQuery })}`,
     )
   } else {
     const applicableVariants = DEFAULT_VARIANTS.filter((v) => v.height <= sourceHeight)
@@ -64,7 +68,7 @@ export const generateMasterPlaylist = ({
     for (const variant of applicableVariants) {
       lines.push(
         `#EXT-X-STREAM-INF:BANDWIDTH=${variant.bandwidth},RESOLUTION=${variant.resolution},CODECS="avc1.42E01E,mp4a.40.2"${subtitleGroup}`,
-        `${streamBase}/stream.m3u8?${serializeToQueryString({ mode: 'transcode' as PlaybackMode, resolution: `${variant.height}p` })}`,
+        `${streamBase}/stream.m3u8?${serializeToQueryString({ mode: 'transcode' as PlaybackMode, resolution: `${variant.height}p`, ...audioTrackQuery })}`,
       )
     }
   }

From 98d69004e74c0aeb3da0ce1515a9dfd45b697d03 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 15:04:01 +0100
Subject: [PATCH 13/30] seeking improvements

---
 common/schemas/media-api.json                 |  15 ++
 common/src/apis/media.ts                      |  17 +-
 .../movie-player-service.spec.ts              | 163 +++++++++++++++-
 .../movie-player-v2/movie-player-service.ts   | 115 ++++++++++-
 .../movie-player-v2-component.tsx             |   5 +
 .../media/actions/hls-init-action.spec.ts     |   2 +
 .../media/actions/hls-init-action.ts          |   5 +-
 .../media/actions/hls-master-action.ts        |   1 +
 .../media/actions/hls-segment-action.spec.ts  |   2 +-
 .../media/actions/hls-segment-action.ts       |   9 +-
 .../hls-session-teardown-action.spec.ts       |  39 ++--
 .../media/actions/hls-stream-action.spec.ts   |  59 ++++++
 .../media/actions/hls-stream-action.ts        |   7 +
 .../services/hls-manifest-generator.spec.ts   |  55 ++++++
 .../media/services/hls-manifest-generator.ts  |   7 +-
 .../services/transcoding-session.spec.ts      | 183 ++++++++++++++++++
 .../media/services/transcoding-session.ts     |  37 +++-
 17 files changed, 661 insertions(+), 60 deletions(-)

diff --git a/common/schemas/media-api.json b/common/schemas/media-api.json
index f4a3e5a7..44316181 100644
--- a/common/schemas/media-api.json
+++ b/common/schemas/media-api.json
@@ -10450,6 +10450,9 @@
             },
             "resolution": {
               "type": "string"
+            },
+            "startTime": {
+              "type": "number"
             }
           },
           "additionalProperties": false
@@ -10492,6 +10495,9 @@
             },
             "audioTrack": {
               "type": "number"
+            },
+            "startTime": {
+              "type": "number"
             }
           },
           "additionalProperties": false
@@ -10531,6 +10537,9 @@
             },
             "audioTrack": {
               "type": "number"
+            },
+            "startTime": {
+              "type": "number"
             }
           },
           "additionalProperties": false
@@ -10567,6 +10576,9 @@
             },
             "audioTrack": {
               "type": "number"
+            },
+            "startTime": {
+              "type": "number"
             }
           },
           "additionalProperties": false
@@ -10612,6 +10624,9 @@
             },
             "audioTrack": {
               "type": "number"
+            },
+            "startTime": {
+              "type": "number"
             }
           },
           "additionalProperties": false
diff --git a/common/src/apis/media.ts b/common/src/apis/media.ts
index cd2b1204..1911a045 100644
--- a/common/src/apis/media.ts
+++ b/common/src/apis/media.ts
@@ -177,31 +177,38 @@ export type PlaybackInfoResponse = {
 
 export type HlsMasterEndpoint = {
   url: { letter: string; path: string }
-  query: { mode?: PlaybackMode; videoCodecs?: string; audioCodecs?: string; containers?: string; audioTrack?: number }
+  query: {
+    mode?: PlaybackMode
+    videoCodecs?: string
+    audioCodecs?: string
+    containers?: string
+    audioTrack?: number
+    startTime?: number
+  }
   result: unknown
 }
 
 export type HlsStreamEndpoint = {
   url: { letter: string; path: string }
-  query: { mode?: PlaybackMode; resolution?: string; audioTrack?: number }
+  query: { mode?: PlaybackMode; resolution?: string; audioTrack?: number; startTime?: number }
   result: unknown
 }
 
 export type HlsSegmentEndpoint = {
   url: { letter: string; path: string; index: string }
-  query: { mode?: PlaybackMode; resolution?: string; audioTrack?: number }
+  query: { mode?: PlaybackMode; resolution?: string; audioTrack?: number; startTime?: number }
   result: unknown
 }
 
 export type HlsInitEndpoint = {
   url: { letter: string; path: string }
-  query: { mode?: PlaybackMode; audioTrack?: number; resolution?: string }
+  query: { mode?: PlaybackMode; audioTrack?: number; resolution?: string; startTime?: number }
   result: unknown
 }
 
 export type HlsSessionTeardownEndpoint = {
   url: { letter: string; path: string }
-  query: { mode?: PlaybackMode; resolution?: string; audioTrack?: number }
+  query: { mode?: PlaybackMode; resolution?: string; audioTrack?: number; startTime?: number }
   result: { success: boolean }
 }
 
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
index 3c48cffc..339b781c 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
@@ -3,13 +3,22 @@ import { describe, expect, it, vi, beforeEach } from 'vitest'
 import { usingAsync } from '@furystack/utils'
 import { MoviePlayerService, videoCodecs, audioCodecs } from './movie-player-service.js'
 
-vi.mock('hls.js', () => ({
-  default: {
+vi.mock('hls.js', () => {
+  class MockHls {
+    on = vi.fn()
+    loadSource = vi.fn()
+    attachMedia = vi.fn()
+    destroy = vi.fn()
+    levels: unknown[] = []
+    currentLevel = -1
+  }
+  Object.assign(MockHls, {
     isSupported: () => true,
-    Events: { ERROR: 'hlsError', MANIFEST_PARSED: 'hlsManifestParsed' },
+    Events: { ERROR: 'hlsError', MANIFEST_PARSED: 'hlsManifestParsed', DESTROYING: 'hlsDestroying' },
     ErrorTypes: { NETWORK_ERROR: 'networkError', MEDIA_ERROR: 'mediaError' },
-  },
-}))
+  })
+  return { default: MockHls }
+})
 
 const mockLogger = {
   verbose: vi.fn().mockResolvedValue(undefined),
@@ -306,7 +315,11 @@ describe('switchResolution', () => {
           expect(service.playbackInfo.getValue()).not.toBeNull()
         })
 
-        const mockVideo = { currentTime: 75 } as HTMLVideoElement
+        const mockVideo = {
+          currentTime: 75,
+          addEventListener: vi.fn(),
+          removeEventListener: vi.fn(),
+        } as unknown as HTMLVideoElement
         service.videoElement = mockVideo
 
         await service.switchResolution('480p')
@@ -362,3 +375,141 @@ describe('switchResolution', () => {
     )
   })
 })
+
+describe('seekToTime', () => {
+  let api: ReturnType<typeof createMockApi>
+
+  beforeEach(() => {
+    api = createMockApi()
+    vi.clearAllMocks()
+  })
+
+  it('should not seek in direct-play mode', async () => {
+    const directPlayResponse: PlaybackInfoResponse = {
+      ...mockPlaybackInfoResponse,
+      mode: 'direct-play',
+    }
+    api.call.mockResolvedValue({ result: directPlayResponse })
+
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
+        })
+
+        api.call.mockClear()
+        service.seekToTime(3600)
+        expect(api.call).not.toHaveBeenCalled()
+      },
+    )
+  })
+
+  it('should not seek when already switching', async () => {
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
+        })
+
+        await service.switchAudioTrack(2)
+        api.call.mockClear()
+        service.seekToTime(3600)
+        expect(api.call).not.toHaveBeenCalled()
+      },
+    )
+  })
+
+  it('should not restart if target is within buffered range', async () => {
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
+        })
+
+        const mockVideo = {
+          currentTime: 10,
+          buffered: {
+            length: 1,
+            start: () => 0,
+            end: () => 30,
+          },
+        } as unknown as HTMLVideoElement
+        service.videoElement = mockVideo
+
+        api.call.mockClear()
+        service.seekToTime(15)
+        expect(api.call).not.toHaveBeenCalled()
+      },
+    )
+  })
+
+  it('should not restart if quantized startTime is the same', async () => {
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
+        })
+
+        const mockVideo = {
+          currentTime: 0,
+          buffered: { length: 0, start: () => 0, end: () => 0 },
+        } as unknown as HTMLVideoElement
+        service.videoElement = mockVideo
+
+        api.call.mockClear()
+        service.seekToTime(3)
+        expect(api.call).not.toHaveBeenCalled()
+      },
+    )
+  })
+
+  it('should restart HLS session when seeking beyond buffered range', async () => {
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
+        })
+
+        const mockVideo = {
+          currentTime: 10,
+          buffered: {
+            length: 1,
+            start: () => 0,
+            end: () => 30,
+          },
+          addEventListener: vi.fn(),
+          removeEventListener: vi.fn(),
+          canPlayType: vi.fn().mockReturnValue(''),
+        } as unknown as HTMLVideoElement
+        service.videoElement = mockVideo
+
+        api.call.mockClear()
+        service.seekToTime(3600)
+
+        await vi.waitFor(() => {
+          expect(api.call).toHaveBeenCalledWith(
+            expect.objectContaining({
+              method: 'DELETE',
+              action: '/files/:letter/:path/hls-session',
+            }),
+          )
+          expect(service.progress.getValue()).toBe(3600)
+        })
+      },
+    )
+  })
+
+  it('should initialize hlsStartTime from watch progress', async () => {
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 3605, mockLogger as never),
+      async (service) => {
+        expect(service.progress.getValue()).toBe(3605)
+      },
+    )
+  })
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index 208b8373..47526e7d 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -60,6 +60,8 @@ const buildCodecSupportMap = () => {
 
 export type ResolutionValue = '4k' | '1080p' | '720p' | '480p' | '360p'
 
+const SEGMENT_DURATION = 6
+
 export class MoviePlayerService implements AsyncDisposable {
   constructor(
     private readonly file: PiRatFile,
@@ -69,12 +71,15 @@ export class MoviePlayerService implements AsyncDisposable {
     private readonly logger: ScopedLogger,
   ) {
     this.progress = new ObservableValue(this.currentProgress)
+    this.hlsStartTime = Math.floor(this.currentProgress / SEGMENT_DURATION) * SEGMENT_DURATION
 
     void this.initialize()
   }
 
   private hls: Hls | null = null
   private originalPlaybackMode: PlaybackMode = 'transcode'
+  private isSwitching = false
+  private hlsStartTime = 0
   public videoElement: HTMLVideoElement | null = null
   public audioTrackId = new ObservableValue(0)
   public playbackInfo = new ObservableValue<PlaybackInfoResponse | null>(null)
@@ -112,6 +117,7 @@ export class MoviePlayerService implements AsyncDisposable {
           mode,
           audioTrack: this.audioTrackId.getValue(),
           resolution: this.resolution.getValue(),
+          startTime: this.hlsStartTime || undefined,
         },
       })
     } catch (error) {
@@ -139,8 +145,8 @@ export class MoviePlayerService implements AsyncDisposable {
           selectedSubtitleTrackIndex,
         },
       })
-      this.playbackInfo.setValue(result)
       this.playbackMode.setValue(result.mode)
+      this.playbackInfo.setValue(result)
 
       void this.logger.verbose({
         message: `Playback info received: mode=${result.mode}`,
@@ -206,8 +212,9 @@ export class MoviePlayerService implements AsyncDisposable {
     const mode = this.playbackMode.getValue()
     const audioTrack = this.audioTrackId.getValue()
     const audioParam = audioTrack ? `&audioTrack=${encode(String(audioTrack))}` : ''
+    const startTimeParam = this.hlsStartTime > 0 ? `&startTime=${encode(String(this.hlsStartTime))}` : ''
     const hlsUrl = this.toServiceUrl(
-      `/api/media/files/${encodeURIComponent(this.file.driveLetter)}/${encodeURIComponent(this.file.path)}/master.m3u8?mode=${encode(mode)}${audioParam}`,
+      `/api/media/files/${encodeURIComponent(this.file.driveLetter)}/${encodeURIComponent(this.file.path)}/master.m3u8?mode=${encode(mode)}${audioParam}${startTimeParam}`,
     )
 
     const HlsModule = await loadHls()
@@ -289,47 +296,137 @@ export class MoviePlayerService implements AsyncDisposable {
   public async switchAudioTrack(trackIndex: number) {
     const previousProgress = this.videoElement?.currentTime ?? this.progress.getValue()
 
+    this.isSwitching = true
     await this.teardownHlsSession()
 
     this.audioTrackId.setValue(trackIndex)
     this.currentProgress = previousProgress
+    this.progress.setValue(previousProgress)
+    this.hlsStartTime = Math.floor(previousProgress / SEGMENT_DURATION) * SEGMENT_DURATION
 
     await this.fetchPlaybackInfo()
 
     const info = this.playbackInfo.getValue()
     if (this.videoElement && info) {
       this.startPlayback(this.videoElement, info)
+      const video = this.videoElement
+      const onCanPlay = () => {
+        video.removeEventListener('canplay', onCanPlay)
+        this.isSwitching = false
+        void video.play().catch(() => {})
+      }
+      video.addEventListener('canplay', onCanPlay)
+    } else {
+      this.isSwitching = false
     }
   }
 
   /**
    * Switches resolution and restarts playback. Forces transcode mode when a
    * specific resolution is requested; restores the original mode on "Auto".
+   *
+   * If already in transcode mode, just changes hls.js level (no reload).
+   * A full reload only happens when the playback mode changes.
    */
   public async switchResolution(value: ResolutionValue | undefined) {
+    const currentMode = this.playbackMode.getValue()
+    const targetMode = value ? 'transcode' : this.originalPlaybackMode
+
+    if (currentMode === 'transcode' && targetMode === 'transcode') {
+      this.resolution.setValue(value)
+      return
+    }
+
     const previousProgress = this.videoElement?.currentTime ?? this.progress.getValue()
     await this.teardownHlsSession()
 
+    this.isSwitching = true
     this.resolution.setValue(value)
     this.currentProgress = previousProgress
     this.progress.setValue(previousProgress)
+    this.hlsStartTime = Math.floor(previousProgress / SEGMENT_DURATION) * SEGMENT_DURATION
+    this.playbackMode.setValue(targetMode)
 
-    if (value) {
-      if (this.playbackMode.getValue() !== 'transcode') {
-        this.playbackMode.setValue('transcode')
+    if (this.videoElement) {
+      const info = this.playbackInfo.getValue()
+      if (info) {
+        this.startPlayback(this.videoElement, info)
+        const video = this.videoElement
+        const onCanPlay = () => {
+          video.removeEventListener('canplay', onCanPlay)
+          this.isSwitching = false
+          void video.play().catch(() => {})
+        }
+        video.addEventListener('canplay', onCanPlay)
+      } else {
+        this.isSwitching = false
       }
     } else {
-      this.playbackMode.setValue(this.originalPlaybackMode)
+      this.isSwitching = false
     }
+  }
+
+  /**
+   * Handles a seek to a new time position. If the target is not within the
+   * video's buffered ranges and we're in HLS mode, tears down the current
+   * session and starts a new one with server-side seeking via `-ss`.
+   */
+  public seekToTime(targetSeconds: number) {
+    const mode = this.playbackMode.getValue()
+    if (mode === 'direct-play' || this.isSwitching) return
+
+    const video = this.videoElement
+    if (!video) return
+
+    if (this.isTimeBuffered(video, targetSeconds)) return
+
+    const quantizedStart = Math.floor(targetSeconds / SEGMENT_DURATION) * SEGMENT_DURATION
+    if (quantizedStart === this.hlsStartTime) return
+
+    void this.restartHlsAtTime(targetSeconds, quantizedStart)
+  }
+
+  private isTimeBuffered(video: HTMLVideoElement, time: number): boolean {
+    const { buffered } = video
+    for (let i = 0; i < buffered.length; i++) {
+      if (time >= buffered.start(i) && time <= buffered.end(i)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  private async restartHlsAtTime(targetSeconds: number, quantizedStart: number) {
+    this.isSwitching = true
+
+    await this.teardownHlsSession()
+    if (this.hls) {
+      this.hls.destroy()
+      this.hls = null
+    }
+
+    this.hlsStartTime = quantizedStart
+    this.currentProgress = targetSeconds
+    this.progress.setValue(targetSeconds)
 
     if (this.videoElement) {
-      const info = this.playbackInfo.getValue()
-      if (info) {
-        this.startPlayback(this.videoElement, info)
+      void this.startHlsPlayback(this.videoElement)
+      const video = this.videoElement
+      const onCanPlay = () => {
+        video.removeEventListener('canplay', onCanPlay)
+        this.isSwitching = false
+        void video.play().catch(() => {})
       }
+      video.addEventListener('canplay', onCanPlay)
+    } else {
+      this.isSwitching = false
     }
   }
 
+  public getIsSwitching(): boolean {
+    return this.isSwitching
+  }
+
   public getAudioTrackInfoFromPlaybackInfo(): AudioTrackInfo[] {
     return this.playbackInfo.getValue()?.audioTracks ?? []
   }
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
index 90e8386d..104fbb82 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
@@ -231,7 +231,12 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
                 mediaService.audioTrackId.setValue(parseInt(video.audioTracks[0].id as string, 10))
               }
             }}
+            onseeking={(ev) => {
+              const { currentTime } = ev.currentTarget as HTMLVideoElement
+              mediaService.seekToTime(currentTime)
+            }}
             ontimeupdate={(ev) => {
+              if (mediaService.getIsSwitching()) return
               const { currentTime } = ev.currentTarget as HTMLVideoElement
               mediaService.progress.setValue(currentTime || 0)
             }}
diff --git a/service/src/app-models/media/actions/hls-init-action.spec.ts b/service/src/app-models/media/actions/hls-init-action.spec.ts
index 01397052..d0efd29b 100644
--- a/service/src/app-models/media/actions/hls-init-action.spec.ts
+++ b/service/src/app-models/media/actions/hls-init-action.spec.ts
@@ -145,6 +145,8 @@ describe('HlsInitAction', () => {
         path: 'test.mkv',
         mode: 'transcode',
         audioTrackId: 1,
+        resolution: undefined,
+        startTime: 0,
       })
     })
   })
diff --git a/service/src/app-models/media/actions/hls-init-action.ts b/service/src/app-models/media/actions/hls-init-action.ts
index b077f48e..f760673c 100644
--- a/service/src/app-models/media/actions/hls-init-action.ts
+++ b/service/src/app-models/media/actions/hls-init-action.ts
@@ -27,8 +27,10 @@ export const HlsInitAction: RequestAction<HlsInitEndpoint> = async ({ injector,
 
   const sessionService = injector.getInstance(TranscodingSessionService)
 
+  const startTime = query.startTime ?? 0
+
   // The session should already exist (created when stream.m3u8 was requested)
-  let session = sessionService.getSession(letter, path, mode, query.audioTrack ?? 0, query.resolution)
+  let session = sessionService.getSession(letter, path, mode, query.audioTrack ?? 0, query.resolution, startTime)
   if (!session) {
     // Create one if it doesn't exist (init might be requested before stream.m3u8)
     session = await sessionService.getOrCreateSession({
@@ -37,6 +39,7 @@ export const HlsInitAction: RequestAction<HlsInitEndpoint> = async ({ injector,
       mode,
       audioTrackId: query.audioTrack ?? 0,
       resolution: query.resolution,
+      startTime,
     })
   }
 
diff --git a/service/src/app-models/media/actions/hls-master-action.ts b/service/src/app-models/media/actions/hls-master-action.ts
index 2f380c3a..b9fa316e 100644
--- a/service/src/app-models/media/actions/hls-master-action.ts
+++ b/service/src/app-models/media/actions/hls-master-action.ts
@@ -60,6 +60,7 @@ export const HlsMasterAction: RequestAction<HlsMasterEndpoint> = async ({
     baseUrl: '/api/media',
     subtitleTracks,
     audioTrack: query.audioTrack,
+    startTime: query.startTime,
   })
 
   await logger.verbose({ message: `Generated master playlist for ${letter}:${path}`, data: { mode } })
diff --git a/service/src/app-models/media/actions/hls-segment-action.spec.ts b/service/src/app-models/media/actions/hls-segment-action.spec.ts
index bfff7d48..4efb2cc3 100644
--- a/service/src/app-models/media/actions/hls-segment-action.spec.ts
+++ b/service/src/app-models/media/actions/hls-segment-action.spec.ts
@@ -244,7 +244,7 @@ describe('HlsSegmentAction', () => {
         request: {} as IncomingMessage,
       })
 
-      expect(getSession).toHaveBeenCalledWith('A', 'test.mkv', 'transcode', 2, '720p')
+      expect(getSession).toHaveBeenCalledWith('A', 'test.mkv', 'transcode', 2, '720p', 0)
     })
   })
 })
diff --git a/service/src/app-models/media/actions/hls-segment-action.ts b/service/src/app-models/media/actions/hls-segment-action.ts
index 63fc7438..2f9e2673 100644
--- a/service/src/app-models/media/actions/hls-segment-action.ts
+++ b/service/src/app-models/media/actions/hls-segment-action.ts
@@ -37,7 +37,14 @@ export const HlsSegmentAction: RequestAction<HlsSegmentEndpoint> = async ({
 
   const sessionService = injector.getInstance(TranscodingSessionService)
 
-  const session = sessionService.getSession(letter, path, mode, query.audioTrack ?? 0, query.resolution)
+  const session = sessionService.getSession(
+    letter,
+    path,
+    mode,
+    query.audioTrack ?? 0,
+    query.resolution,
+    query.startTime ?? 0,
+  )
   if (!session) {
     throw new RequestError('No active transcoding session', 404)
   }
diff --git a/service/src/app-models/media/actions/hls-session-teardown-action.spec.ts b/service/src/app-models/media/actions/hls-session-teardown-action.spec.ts
index b4ab10ae..795d8aef 100644
--- a/service/src/app-models/media/actions/hls-session-teardown-action.spec.ts
+++ b/service/src/app-models/media/actions/hls-session-teardown-action.spec.ts
@@ -32,28 +32,14 @@ describe('HlsSessionTeardownAction', () => {
     })
   })
 
-  it('should reject invalid playback mode', async () => {
-    await usingAsync(new Injector(), async (injector) => {
-      try {
-        await HlsSessionTeardownAction({
-          injector,
-          getUrlParams: () => ({ letter: 'A', path: 'test.mkv' }),
-          getQuery: () => ({ mode: 'invalid' as never }),
-          response: {} as ServerResponse,
-          request: {} as IncomingMessage,
-        })
-        expect.fail('Should have thrown')
-      } catch (error) {
-        expect((error as Error).message).toContain('Invalid playback mode')
-      }
-    })
-  })
-
-  it('should call removeSession and return success', async () => {
-    const removeSession = vi.fn()
+  it('should call removeAllSessionsForFile and return success', async () => {
+    const removeAllSessionsForFile = vi.fn()
 
     await usingAsync(new Injector(), async (injector) => {
-      injector.setExplicitInstance({ removeSession } as unknown as TranscodingSessionService, TranscodingSessionService)
+      injector.setExplicitInstance(
+        { removeAllSessionsForFile } as unknown as TranscodingSessionService,
+        TranscodingSessionService,
+      )
 
       const result = await HlsSessionTeardownAction({
         injector,
@@ -63,7 +49,7 @@ describe('HlsSessionTeardownAction', () => {
         request: {} as IncomingMessage,
       })
 
-      expect(removeSession).toHaveBeenCalledWith('A', 'test.mkv', 'transcode', 1, '720p')
+      expect(removeAllSessionsForFile).toHaveBeenCalledWith('A', 'test.mkv')
       expect(result).toEqual({
         chunk: { success: true },
         headers: { 'Content-Type': 'application/json' },
@@ -72,11 +58,14 @@ describe('HlsSessionTeardownAction', () => {
     })
   })
 
-  it('should default mode to transcode and audioTrack to 0', async () => {
-    const removeSession = vi.fn()
+  it('should remove all sessions regardless of query params', async () => {
+    const removeAllSessionsForFile = vi.fn()
 
     await usingAsync(new Injector(), async (injector) => {
-      injector.setExplicitInstance({ removeSession } as unknown as TranscodingSessionService, TranscodingSessionService)
+      injector.setExplicitInstance(
+        { removeAllSessionsForFile } as unknown as TranscodingSessionService,
+        TranscodingSessionService,
+      )
 
       await HlsSessionTeardownAction({
         injector,
@@ -86,7 +75,7 @@ describe('HlsSessionTeardownAction', () => {
         request: {} as IncomingMessage,
       })
 
-      expect(removeSession).toHaveBeenCalledWith('B', 'movie.mp4', 'transcode', 0, undefined)
+      expect(removeAllSessionsForFile).toHaveBeenCalledWith('B', 'movie.mp4')
     })
   })
 })
diff --git a/service/src/app-models/media/actions/hls-stream-action.spec.ts b/service/src/app-models/media/actions/hls-stream-action.spec.ts
index e5edd744..015fda45 100644
--- a/service/src/app-models/media/actions/hls-stream-action.spec.ts
+++ b/service/src/app-models/media/actions/hls-stream-action.spec.ts
@@ -240,7 +240,66 @@ describe('HlsStreamAction', () => {
         mode: 'transcode',
         audioTrackId: 2,
         resolution: '1080p',
+        startTime: 0,
       })
     })
   })
+
+  it('should pass startTime to session creation and include in segment URLs', async () => {
+    const getOrCreateSession = vi.fn().mockResolvedValue(mockSession)
+    let writtenBody = ''
+    const response = {
+      writeHead: vi.fn(),
+      end: vi.fn((body: string) => {
+        writtenBody = body
+      }),
+    }
+
+    await usingAsync(new Injector(), async (injector) => {
+      injector.setExplicitInstance(
+        {
+          getOrCreateSession,
+          readPlaylist: vi.fn().mockResolvedValue(MOCK_PLAYLIST),
+        } as unknown as TranscodingSessionService,
+        TranscodingSessionService,
+      )
+
+      await HlsStreamAction({
+        injector,
+        getUrlParams: () => ({ letter: 'A', path: 'test.mkv' }),
+        getQuery: () => ({ mode: 'transcode', startTime: 3600 }),
+        response: response as unknown as ServerResponse,
+        request: {} as IncomingMessage,
+      })
+
+      expect(getOrCreateSession).toHaveBeenCalledWith(
+        expect.objectContaining({
+          startTime: 3600,
+        }),
+      )
+      expect(writtenBody).toContain('startTime')
+    })
+  })
+
+  it('should reject negative startTime', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      injector.setExplicitInstance(
+        { getOrCreateSession: vi.fn(), readPlaylist: vi.fn() } as unknown as TranscodingSessionService,
+        TranscodingSessionService,
+      )
+
+      try {
+        await HlsStreamAction({
+          injector,
+          getUrlParams: () => ({ letter: 'A', path: 'test.mkv' }),
+          getQuery: () => ({ mode: 'transcode', startTime: -10 }),
+          response: { writeHead: vi.fn(), end: vi.fn() } as unknown as ServerResponse,
+          request: {} as IncomingMessage,
+        })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        expect((error as Error).message).toContain('Invalid startTime')
+      }
+    })
+  })
 })
diff --git a/service/src/app-models/media/actions/hls-stream-action.ts b/service/src/app-models/media/actions/hls-stream-action.ts
index 378d0b29..56dadfe4 100644
--- a/service/src/app-models/media/actions/hls-stream-action.ts
+++ b/service/src/app-models/media/actions/hls-stream-action.ts
@@ -29,12 +29,18 @@ export const HlsStreamAction: RequestAction<HlsStreamEndpoint> = async ({
 
   const sessionService = injector.getInstance(TranscodingSessionService)
 
+  const startTime = query.startTime ?? 0
+  if (startTime < 0) {
+    throw new RequestError('Invalid startTime', 400)
+  }
+
   const session = await sessionService.getOrCreateSession({
     driveLetter: letter,
     path,
     mode,
     audioTrackId: query.audioTrack ?? 0,
     resolution: query.resolution,
+    startTime,
   })
 
   const playlistContent = await sessionService.readPlaylist(session)
@@ -51,6 +57,7 @@ export const HlsStreamAction: RequestAction<HlsStreamEndpoint> = async ({
     mode,
     audioTrack: query.audioTrack ?? 0,
     ...(query.resolution ? { resolution: query.resolution } : {}),
+    ...(startTime > 0 ? { startTime } : {}),
   }
   const serializedQuery = serializeToQueryString(queryParams)
 
diff --git a/service/src/app-models/media/services/hls-manifest-generator.spec.ts b/service/src/app-models/media/services/hls-manifest-generator.spec.ts
index 8355708e..8bc76554 100644
--- a/service/src/app-models/media/services/hls-manifest-generator.spec.ts
+++ b/service/src/app-models/media/services/hls-manifest-generator.spec.ts
@@ -200,4 +200,59 @@ describe('generateMasterPlaylist', () => {
 
     expect(playlist).not.toContain('audioTrack')
   })
+
+  it('should propagate startTime into variant URLs for transcode mode', () => {
+    const playlist = generateMasterPlaylist({
+      ffprobe: createFfprobe(),
+      file: { driveLetter: 'A', path: 'movies/test.mkv' },
+      mode: 'transcode',
+      baseUrl: '/api/media',
+      subtitleTracks: [],
+      startTime: 3600,
+    })
+
+    const variantLines = playlist.split('\n').filter((l) => l.includes('stream.m3u8'))
+    for (const line of variantLines) {
+      expect(line).toContain('startTime')
+    }
+  })
+
+  it('should propagate startTime into variant URL for remux mode', () => {
+    const playlist = generateMasterPlaylist({
+      ffprobe: createFfprobe(),
+      file: { driveLetter: 'A', path: 'movies/test.mkv' },
+      mode: 'remux',
+      baseUrl: '/api/media',
+      subtitleTracks: [],
+      startTime: 1800,
+    })
+
+    const variantLine = playlist.split('\n').find((l) => l.includes('stream.m3u8'))
+    expect(variantLine).toContain('startTime')
+  })
+
+  it('should not include startTime when not specified', () => {
+    const playlist = generateMasterPlaylist({
+      ffprobe: createFfprobe(),
+      file: { driveLetter: 'A', path: 'movies/test.mkv' },
+      mode: 'transcode',
+      baseUrl: '/api/media',
+      subtitleTracks: [],
+    })
+
+    expect(playlist).not.toContain('startTime')
+  })
+
+  it('should not include startTime when set to 0', () => {
+    const playlist = generateMasterPlaylist({
+      ffprobe: createFfprobe(),
+      file: { driveLetter: 'A', path: 'movies/test.mkv' },
+      mode: 'transcode',
+      baseUrl: '/api/media',
+      subtitleTracks: [],
+      startTime: 0,
+    })
+
+    expect(playlist).not.toContain('startTime')
+  })
 })
diff --git a/service/src/app-models/media/services/hls-manifest-generator.ts b/service/src/app-models/media/services/hls-manifest-generator.ts
index a14e16da..11283692 100644
--- a/service/src/app-models/media/services/hls-manifest-generator.ts
+++ b/service/src/app-models/media/services/hls-manifest-generator.ts
@@ -23,6 +23,7 @@ export const generateMasterPlaylist = ({
   baseUrl,
   subtitleTracks,
   audioTrack,
+  startTime,
 }: {
   ffprobe: FfprobeData
   file: { driveLetter: string; path: string }
@@ -30,6 +31,7 @@ export const generateMasterPlaylist = ({
   baseUrl: string
   subtitleTracks: SubtitleTrackInfo[]
   audioTrack?: number
+  startTime?: number
 }): string => {
   const lines: string[] = ['#EXTM3U', '#EXT-X-VERSION:7']
 
@@ -50,12 +52,13 @@ export const generateMasterPlaylist = ({
   const sourceBitrate = ffprobe.format.bit_rate || 5000000
 
   const audioTrackQuery = audioTrack !== undefined ? { audioTrack } : {}
+  const startTimeQuery = startTime && startTime > 0 ? { startTime } : {}
 
   if (mode === 'remux' || mode === 'direct-play' || mode === 'direct-stream') {
     const subtitleGroup = subtitleTracks.filter((t) => !t.requiresBurnIn).length > 0 ? ',SUBTITLES="subs"' : ''
     lines.push(
       `#EXT-X-STREAM-INF:BANDWIDTH=${sourceBitrate},RESOLUTION=${sourceWidth}x${sourceHeight},CODECS="${getCodecString(ffprobe)}"${subtitleGroup}`,
-      `${streamBase}/stream.m3u8?${serializeToQueryString({ mode, ...audioTrackQuery })}`,
+      `${streamBase}/stream.m3u8?${serializeToQueryString({ mode, ...audioTrackQuery, ...startTimeQuery })}`,
     )
   } else {
     const applicableVariants = DEFAULT_VARIANTS.filter((v) => v.height <= sourceHeight)
@@ -68,7 +71,7 @@ export const generateMasterPlaylist = ({
     for (const variant of applicableVariants) {
       lines.push(
         `#EXT-X-STREAM-INF:BANDWIDTH=${variant.bandwidth},RESOLUTION=${variant.resolution},CODECS="avc1.42E01E,mp4a.40.2"${subtitleGroup}`,
-        `${streamBase}/stream.m3u8?${serializeToQueryString({ mode: 'transcode' as PlaybackMode, resolution: `${variant.height}p`, ...audioTrackQuery })}`,
+        `${streamBase}/stream.m3u8?${serializeToQueryString({ mode: 'transcode' as PlaybackMode, resolution: `${variant.height}p`, ...audioTrackQuery, ...startTimeQuery })}`,
       )
     }
   }
diff --git a/service/src/app-models/media/services/transcoding-session.spec.ts b/service/src/app-models/media/services/transcoding-session.spec.ts
index 615c0893..b8288fe4 100644
--- a/service/src/app-models/media/services/transcoding-session.spec.ts
+++ b/service/src/app-models/media/services/transcoding-session.spec.ts
@@ -1034,5 +1034,188 @@ describe('TranscodingSessionService', () => {
         }
       })
     })
+
+    it('should include -ss before -i when startTime is set', async () => {
+      const mockProcess = createMockProcess()
+      mockSpawn.mockReturnValue(mockProcess)
+
+      await usingAsync(new Injector(), async (injector) => {
+        injector.setExplicitInstance(
+          { getFfprobeForPiratFile: vi.fn().mockResolvedValue(mockFfprobe) } as unknown as FfprobeService,
+          FfprobeService,
+        )
+        injector.setExplicitInstance(
+          { getEncoder: vi.fn().mockResolvedValue('libx264') } as unknown as HwAccelDetector,
+          HwAccelDetector,
+        )
+
+        const service = injector.getInstance(TranscodingSessionService)
+        try {
+          await service.getOrCreateSession({
+            driveLetter: 'A',
+            path: 'test.mkv',
+            mode: 'transcode',
+            startTime: 3600,
+          })
+
+          const lastCall = mockSpawn.mock.lastCall as [string, string[]]
+          const args = lastCall[1]
+          const ssIndex = args.indexOf('-ss')
+          const iIndex = args.indexOf('-i')
+          expect(ssIndex).toBeGreaterThanOrEqual(0)
+          expect(args[ssIndex + 1]).toBe('3600')
+          expect(ssIndex).toBeLessThan(iIndex)
+        } finally {
+          service.dispose()
+        }
+      })
+    })
+
+    it('should not include -ss when startTime is 0', async () => {
+      const mockProcess = createMockProcess()
+      mockSpawn.mockReturnValue(mockProcess)
+
+      await usingAsync(new Injector(), async (injector) => {
+        injector.setExplicitInstance(
+          { getFfprobeForPiratFile: vi.fn().mockResolvedValue(mockFfprobe) } as unknown as FfprobeService,
+          FfprobeService,
+        )
+        injector.setExplicitInstance(
+          { getEncoder: vi.fn().mockResolvedValue('libx264') } as unknown as HwAccelDetector,
+          HwAccelDetector,
+        )
+
+        const service = injector.getInstance(TranscodingSessionService)
+        try {
+          await service.getOrCreateSession({
+            driveLetter: 'A',
+            path: 'test.mkv',
+            mode: 'transcode',
+            startTime: 0,
+          })
+
+          const lastCall = mockSpawn.mock.lastCall as [string, string[]]
+          const args = lastCall[1]
+          expect(args).not.toContain('-ss')
+        } finally {
+          service.dispose()
+        }
+      })
+    })
+
+    it('should offset -force_key_frames by startTime for transcode mode', async () => {
+      const mockProcess = createMockProcess()
+      mockSpawn.mockReturnValue(mockProcess)
+
+      await usingAsync(new Injector(), async (injector) => {
+        injector.setExplicitInstance(
+          { getFfprobeForPiratFile: vi.fn().mockResolvedValue(mockFfprobe) } as unknown as FfprobeService,
+          FfprobeService,
+        )
+        injector.setExplicitInstance(
+          { getEncoder: vi.fn().mockResolvedValue('libx264') } as unknown as HwAccelDetector,
+          HwAccelDetector,
+        )
+
+        const service = injector.getInstance(TranscodingSessionService)
+        try {
+          await service.getOrCreateSession({
+            driveLetter: 'A',
+            path: 'test.mkv',
+            mode: 'transcode',
+            startTime: 3600,
+          })
+
+          const lastCall = mockSpawn.mock.lastCall as [string, string[]]
+          const args = lastCall[1]
+          const fkfIndex = args.indexOf('-force_key_frames')
+          expect(fkfIndex).toBeGreaterThanOrEqual(0)
+          expect(args[fkfIndex + 1]).toBe('expr:gte(t,n_forced*6+3600)')
+        } finally {
+          service.dispose()
+        }
+      })
+    })
+
+    it('should create separate sessions for different startTime values', async () => {
+      const mockProcess = createMockProcess()
+      mockSpawn.mockReturnValue(mockProcess)
+
+      await usingAsync(new Injector(), async (injector) => {
+        injector.setExplicitInstance(
+          { getFfprobeForPiratFile: vi.fn().mockResolvedValue(mockFfprobe) } as unknown as FfprobeService,
+          FfprobeService,
+        )
+        injector.setExplicitInstance(
+          { getEncoder: vi.fn().mockResolvedValue('libx264') } as unknown as HwAccelDetector,
+          HwAccelDetector,
+        )
+
+        const service = injector.getInstance(TranscodingSessionService)
+        try {
+          const session1 = await service.getOrCreateSession({
+            driveLetter: 'A',
+            path: 'test.mkv',
+            mode: 'transcode',
+            startTime: 0,
+          })
+          const session2 = await service.getOrCreateSession({
+            driveLetter: 'A',
+            path: 'test.mkv',
+            mode: 'transcode',
+            startTime: 3600,
+          })
+
+          expect(session1).not.toBe(session2)
+          expect(mockSpawn).toHaveBeenCalledTimes(2)
+          expect(service.getActiveSessionCount()).toBe(2)
+        } finally {
+          service.dispose()
+        }
+      })
+    })
+  })
+
+  describe('padPlaylistToFullDuration with startTime', () => {
+    const testDir = join(tmpdir(), 'pirat-test-pad-starttime')
+
+    beforeEach(() => {
+      if (!existsSync(testDir)) mkdirSync(testDir, { recursive: true })
+    })
+
+    afterEach(() => {
+      if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true })
+    })
+
+    it('should pad based on remaining duration from startTime', async () => {
+      vi.useRealTimers()
+      const playlistContent = [
+        '#EXTM3U',
+        '#EXT-X-VERSION:7',
+        '#EXT-X-TARGETDURATION:6',
+        '#EXT-X-MAP:URI="init.mp4"',
+        '#EXTINF:6.000000,',
+        'segment0.m4s',
+        '',
+      ].join('\n')
+      writeFileSync(join(testDir, 'playlist.m3u8'), playlistContent)
+
+      const service = new TranscodingSessionService()
+      try {
+        const mockSession = {
+          sessionDir: testDir,
+          state: 'running' as const,
+          totalDuration: 120,
+          startTime: 108,
+        } as Parameters<typeof service.readPlaylist>[0]
+
+        const result = await service.readPlaylist(mockSession)
+        expect(result).toContain('#EXT-X-ENDLIST')
+        expect(result).toContain('segment1.m4s')
+        expect(result).not.toContain('segment3.m4s')
+      } finally {
+        service.dispose()
+      }
+    })
   })
 })
diff --git a/service/src/app-models/media/services/transcoding-session.ts b/service/src/app-models/media/services/transcoding-session.ts
index bc889c02..741cba27 100644
--- a/service/src/app-models/media/services/transcoding-session.ts
+++ b/service/src/app-models/media/services/transcoding-session.ts
@@ -27,6 +27,7 @@ type TranscodingSessionEntry = {
   path: string
   audioTrackId: number
   resolution?: string
+  startTime: number
   totalDuration: number
   createdAt: number
   lastAccessedAt: number
@@ -72,8 +73,9 @@ export class TranscodingSessionService {
     mode: PlaybackMode,
     audioTrackId: number,
     resolution?: string,
+    startTime: number = 0,
   ): SessionKey {
-    return `${driveLetter}:${path}:${mode}:${audioTrackId}:${resolution || ''}`
+    return `${driveLetter}:${path}:${mode}:${audioTrackId}:${resolution || ''}:${startTime}`
   }
 
   private getSessionDir(key: SessionKey): string {
@@ -114,8 +116,9 @@ export class TranscodingSessionService {
     mode: PlaybackMode,
     audioTrackId: number = 0,
     resolution?: string,
+    startTime: number = 0,
   ): TranscodingSessionEntry | undefined {
-    const key = this.buildSessionKey(driveLetter, path, mode, audioTrackId, resolution)
+    const key = this.buildSessionKey(driveLetter, path, mode, audioTrackId, resolution, startTime)
     const session = this.sessions.get(key)
     if (session) {
       session.lastAccessedAt = Date.now()
@@ -129,14 +132,16 @@ export class TranscodingSessionService {
     mode,
     audioTrackId = 0,
     resolution,
+    startTime = 0,
   }: {
     driveLetter: string
     path: string
     mode: PlaybackMode
     audioTrackId?: number
     resolution?: string
+    startTime?: number
   }): Promise<TranscodingSessionEntry> {
-    const key = this.buildSessionKey(driveLetter, path, mode, audioTrackId, resolution)
+    const key = this.buildSessionKey(driveLetter, path, mode, audioTrackId, resolution, startTime)
     const existing = this.sessions.get(key)
     if (existing) {
       existing.lastAccessedAt = Date.now()
@@ -146,7 +151,7 @@ export class TranscodingSessionService {
     const pending = this.pendingSessions.get(key)
     if (pending) return pending
 
-    const createPromise = this.createSession(key, driveLetter, path, mode, audioTrackId, resolution)
+    const createPromise = this.createSession(key, driveLetter, path, mode, audioTrackId, resolution, startTime)
     this.pendingSessions.set(key, createPromise)
 
     try {
@@ -163,6 +168,7 @@ export class TranscodingSessionService {
     mode: PlaybackMode,
     audioTrackId: number,
     resolution?: string,
+    startTime: number = 0,
   ): Promise<TranscodingSessionEntry> {
     await this.getBaseDirFromConfig()
     const sessionDir = this.getSessionDir(key)
@@ -177,6 +183,7 @@ export class TranscodingSessionService {
       audioTrackId,
       resolution,
       sessionDir,
+      startTime,
     })
 
     void this.logger.verbose({
@@ -198,6 +205,7 @@ export class TranscodingSessionService {
       path,
       audioTrackId,
       resolution,
+      startTime,
       totalDuration,
       createdAt: Date.now(),
       lastAccessedAt: Date.now(),
@@ -283,7 +291,7 @@ export class TranscodingSessionService {
     const ready = await this.waitForFile(playlistPath, session)
     if (!ready) return null
     const content = await readFile(playlistPath, 'utf-8')
-    return this.padPlaylistToFullDuration(content, session.totalDuration)
+    return this.padPlaylistToFullDuration(content, session.totalDuration, session.startTime)
   }
 
   /**
@@ -292,7 +300,7 @@ export class TranscodingSessionService {
    * full VOD duration from the first request. The segment-serving endpoint
    * already waits for segments that haven't been transcoded yet.
    */
-  private padPlaylistToFullDuration(playlist: string, totalDuration: number): string {
+  private padPlaylistToFullDuration(playlist: string, totalDuration: number, startTime: number = 0): string {
     if (totalDuration <= 0 || playlist.includes('#EXT-X-ENDLIST')) {
       return playlist
     }
@@ -312,7 +320,8 @@ export class TranscodingSessionService {
       }
     }
 
-    const remainingDuration = totalDuration - encodedDuration
+    const effectiveDuration = totalDuration - startTime
+    const remainingDuration = effectiveDuration - encodedDuration
     if (remainingDuration <= 0) {
       return `${playlist.trimEnd()}\n#EXT-X-ENDLIST\n`
     }
@@ -346,6 +355,7 @@ export class TranscodingSessionService {
     audioTrackId,
     resolution,
     sessionDir,
+    startTime = 0,
   }: {
     driveLetter: string
     path: string
@@ -353,6 +363,7 @@ export class TranscodingSessionService {
     audioTrackId: number
     resolution?: string
     sessionDir: string
+    startTime?: number
   }): Promise<{ args: string[]; totalDuration: number }> {
     const [drive, config, ffprobe] = await Promise.all([
       (async () => {
@@ -381,6 +392,11 @@ export class TranscodingSessionService {
 
     const args: string[] = []
 
+    // Input seeking (before -i for fast keyframe-based seeking)
+    if (startTime > 0) {
+      args.push('-ss', String(startTime))
+    }
+
     // Input with timestamp preservation (like Jellyfin)
     args.push('-copyts', '-avoid_negative_ts', 'disabled')
     args.push('-i', fullPath)
@@ -425,8 +441,8 @@ export class TranscodingSessionService {
 
       args.push('-c:v', videoCodec)
 
-      // Force keyframes at segment boundaries
-      args.push('-force_key_frames', `expr:gte(t,n_forced*${SEGMENT_DURATION})`)
+      // Force keyframes at segment boundaries (offset by startTime when -copyts preserves original PTS)
+      args.push('-force_key_frames', `expr:gte(t,n_forced*${SEGMENT_DURATION}+${startTime})`)
       args.push('-sc_threshold:v', '0')
 
       const isSoftwareEncoder = videoCodec === 'libx264' || videoCodec === 'libx265'
@@ -471,8 +487,9 @@ export class TranscodingSessionService {
     mode: PlaybackMode,
     audioTrackId: number = 0,
     resolution?: string,
+    startTime: number = 0,
   ) {
-    const key = this.buildSessionKey(driveLetter, path, mode, audioTrackId, resolution)
+    const key = this.buildSessionKey(driveLetter, path, mode, audioTrackId, resolution, startTime)
     const session = this.sessions.get(key)
     if (session) {
       this.destroySession(session)

From 479c7727e55f5e975ecda9340e36d2696c699edc Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 15:22:30 +0100
Subject: [PATCH 14/30] cleanup, refactorings

---
 .../src/pages/admin/tmdb-settings.spec.ts     |   64 +
 frontend/src/pages/admin/tmdb-settings.tsx    |    2 +-
 .../file-browser/file-context-menu-items.tsx  |  135 ++
 frontend/src/pages/file-browser/file-list.tsx |  197 +--
 .../file-browser/file-upload-handler.tsx      |   61 +
 .../localized-metadata-service.spec.ts        |  191 +++
 .../media/announce-movie-file-added.ts        |   40 +
 .../src/app-models/media/media-data-sets.ts   |  127 ++
 .../app-models/media/media-schema-setup.ts    |  786 ++++++++++++
 .../media/media-sequelize-models.ts           |  205 +++
 .../build-synthetic-movie.ts                  |   38 +
 .../tmdb-client-service.spec.ts               |  735 +++++++++++
 .../metadata-services/tmdb-client-service.ts  |   50 +-
 .../src/app-models/media/setup-media.spec.ts  |    2 +-
 service/src/app-models/media/setup-media.ts   | 1107 +----------------
 .../ensure-localized-metadata-exists.spec.ts  |  132 ++
 .../utils/ensure-tmdb-movie-exists.spec.ts    |  110 ++
 .../utils/ensure-tmdb-series-exists.spec.ts   |  118 ++
 .../app-models/media/utils/link-movie.spec.ts |  178 +++
 .../media/utils/map-omdb-to-localized.spec.ts |   75 ++
 .../media/utils/map-tmdb-to-localized.spec.ts |   90 ++
 21 files changed, 3133 insertions(+), 1310 deletions(-)
 create mode 100644 frontend/src/pages/admin/tmdb-settings.spec.ts
 create mode 100644 frontend/src/pages/file-browser/file-context-menu-items.tsx
 create mode 100644 frontend/src/pages/file-browser/file-upload-handler.tsx
 create mode 100644 frontend/src/services/localized-metadata-service.spec.ts
 create mode 100644 service/src/app-models/media/announce-movie-file-added.ts
 create mode 100644 service/src/app-models/media/media-data-sets.ts
 create mode 100644 service/src/app-models/media/media-schema-setup.ts
 create mode 100644 service/src/app-models/media/media-sequelize-models.ts
 create mode 100644 service/src/app-models/media/metadata-services/build-synthetic-movie.ts
 create mode 100644 service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts
 create mode 100644 service/src/app-models/media/utils/ensure-localized-metadata-exists.spec.ts
 create mode 100644 service/src/app-models/media/utils/ensure-tmdb-movie-exists.spec.ts
 create mode 100644 service/src/app-models/media/utils/ensure-tmdb-series-exists.spec.ts
 create mode 100644 service/src/app-models/media/utils/map-omdb-to-localized.spec.ts
 create mode 100644 service/src/app-models/media/utils/map-tmdb-to-localized.spec.ts

diff --git a/frontend/src/pages/admin/tmdb-settings.spec.ts b/frontend/src/pages/admin/tmdb-settings.spec.ts
new file mode 100644
index 00000000..6255b23d
--- /dev/null
+++ b/frontend/src/pages/admin/tmdb-settings.spec.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import { isTmdbRawFormData } from './tmdb-settings.js'
+
+describe('isTmdbRawFormData', () => {
+  describe('valid data', () => {
+    it('returns true for valid payload with all fields', () => {
+      expect(
+        isTmdbRawFormData({
+          apiKey: 'test-key',
+          defaultLanguage: 'en-US',
+          additionalLanguages: 'fr-FR, de-DE',
+        }),
+      ).toBe(true)
+    })
+
+    it('returns true for minimal valid payload', () => {
+      expect(isTmdbRawFormData({ apiKey: 'key' })).toBe(true)
+    })
+
+    it('returns true for empty apiKey string', () => {
+      expect(isTmdbRawFormData({ apiKey: '' })).toBe(true)
+    })
+
+    it('returns true for payload with extra fields', () => {
+      expect(isTmdbRawFormData({ apiKey: 'key', extra: 'field' })).toBe(true)
+    })
+  })
+
+  describe('primitives and nullish', () => {
+    it('returns false for null', () => {
+      expect(isTmdbRawFormData(null)).toBe(false)
+    })
+
+    it('returns false for undefined', () => {
+      expect(isTmdbRawFormData(undefined)).toBe(false)
+    })
+
+    it('returns false for string', () => {
+      expect(isTmdbRawFormData('hello')).toBe(false)
+    })
+
+    it('returns false for number', () => {
+      expect(isTmdbRawFormData(42)).toBe(false)
+    })
+  })
+
+  describe('missing or wrong types', () => {
+    it('returns false when apiKey is missing', () => {
+      expect(isTmdbRawFormData({ defaultLanguage: 'en-US' })).toBe(false)
+    })
+
+    it('returns false when apiKey is not a string', () => {
+      expect(isTmdbRawFormData({ apiKey: 123 })).toBe(false)
+    })
+
+    it('returns false when apiKey is null', () => {
+      expect(isTmdbRawFormData({ apiKey: null })).toBe(false)
+    })
+
+    it('returns false for empty object', () => {
+      expect(isTmdbRawFormData({})).toBe(false)
+    })
+  })
+})
diff --git a/frontend/src/pages/admin/tmdb-settings.tsx b/frontend/src/pages/admin/tmdb-settings.tsx
index c1866c35..f8c39ee6 100644
--- a/frontend/src/pages/admin/tmdb-settings.tsx
+++ b/frontend/src/pages/admin/tmdb-settings.tsx
@@ -28,7 +28,7 @@ type TmdbRawFormData = {
   additionalLanguages: string
 }
 
-const isTmdbRawFormData = (data: unknown): data is TmdbRawFormData => {
+export const isTmdbRawFormData = (data: unknown): data is TmdbRawFormData => {
   if (typeof data !== 'object' || data === null) return false
   const d = data as Record<string, unknown>
   return typeof d.apiKey === 'string'
diff --git a/frontend/src/pages/file-browser/file-context-menu-items.tsx b/frontend/src/pages/file-browser/file-context-menu-items.tsx
new file mode 100644
index 00000000..0f5ee490
--- /dev/null
+++ b/frontend/src/pages/file-browser/file-context-menu-items.tsx
@@ -0,0 +1,135 @@
+import { createComponent } from '@furystack/shades'
+import type { ContextMenuItem } from '@furystack/shades-common-components'
+import { Icon, icons, type NotyService } from '@furystack/shades-common-components'
+import { getFallbackMetadata, getFullPath, isMovieFile, isSampleFile, type DirectoryEntry } from 'common'
+
+import type { MediaApiClient } from '../../services/api-clients/media-api-client.js'
+
+type ContextMenuDeps = {
+  currentDriveLetter: string
+  currentPath: string
+  mediaApiClient: MediaApiClient
+  notyService: NotyService
+  onActivate?: (entry: DirectoryEntry) => void
+  onShowRelatedMovies: () => void
+  onShowFileInfo: () => void
+  onDeleteRequest: () => void
+}
+
+export const getContextMenuItems = (
+  entry: DirectoryEntry,
+  deps: ContextMenuDeps,
+): Array<ContextMenuItem<() => void>> => {
+  const { currentDriveLetter, currentPath, mediaApiClient, notyService } = deps
+
+  const path = `${currentDriveLetter}:${currentPath}/${entry.name}`
+  const movieMetadata = entry.isFile && !isSampleFile(path) && isMovieFile(path) && getFallbackMetadata(path)
+  const allowScanForMovies = entry.isDirectory
+
+  return [
+    {
+      type: 'item',
+      icon: <Icon icon={icons.folderOpen} size="small" />,
+      label: 'Open',
+      data: () => deps.onActivate?.(entry),
+    },
+    ...(movieMetadata
+      ? [
+          {
+            type: 'item' as const,
+            icon: <Icon icon={icons.film} size="small" />,
+            label: `Related movie: ${movieMetadata.title} ${
+              movieMetadata.type === 'episode' ? `S${movieMetadata.season}E${movieMetadata.episode}` : ''
+            }`,
+            data: () => deps.onShowRelatedMovies(),
+          },
+          {
+            type: 'item' as const,
+            icon: <Icon icon={icons.messageCircle} size="small" />,
+            label: 'Extract Subtitles',
+            data: () => {
+              mediaApiClient
+                .call({
+                  method: 'POST',
+                  action: '/extract-subtitles',
+                  body: {
+                    driveLetter: currentDriveLetter,
+                    path: getFullPath(currentPath, entry.name),
+                  },
+                })
+                .then(() => {
+                  notyService.emit('onNotyAdded', {
+                    type: 'success',
+                    title: 'Subtitles extracted',
+                    body: <>Subtitles extracted successfully for file {entry.name}</>,
+                  })
+                })
+                .catch(() => {
+                  notyService.emit('onNotyAdded', {
+                    type: 'error',
+                    title: 'Subtitles extraction failed',
+                    body: <>Subtitles extraction failed for file {entry.name}</>,
+                  })
+                })
+            },
+          },
+        ]
+      : []),
+    ...(allowScanForMovies
+      ? [
+          {
+            type: 'item' as const,
+            icon: <Icon icon={icons.film} size="small" />,
+            label: 'Scan for movies',
+            data: () => {
+              mediaApiClient
+                .call({
+                  method: 'POST',
+                  action: '/scan-for-movies',
+                  body: {
+                    root: {
+                      driveLetter: currentDriveLetter,
+                      path: getFullPath(currentPath, entry.name),
+                    },
+                    autoExtractSubtitles: false,
+                  },
+                })
+                .then(() => {
+                  notyService.emit('onNotyAdded', {
+                    type: 'success',
+                    title: 'Movies scanned',
+                    body: <>Movies scanned successfully for folder {entry.name}</>,
+                  })
+                })
+                .catch(() => {
+                  notyService.emit('onNotyAdded', {
+                    type: 'error',
+                    title: 'Movies scanning failed',
+                    body: <>Movies scanning failed for folder {entry.name}</>,
+                  })
+                })
+            },
+          },
+        ]
+      : []),
+    {
+      type: 'item',
+      icon: <Icon icon={icons.info} size="small" />,
+      label: 'Show file info',
+      data: () => deps.onShowFileInfo(),
+    },
+    ...(entry.name !== '..'
+      ? [
+          {
+            type: 'separator' as const,
+          },
+          {
+            type: 'item' as const,
+            icon: <Icon icon={icons.trash} size="small" />,
+            label: 'Delete',
+            data: () => deps.onDeleteRequest(),
+          },
+        ]
+      : []),
+  ]
+}
diff --git a/frontend/src/pages/file-browser/file-list.tsx b/frontend/src/pages/file-browser/file-list.tsx
index fec531c2..42a34028 100644
--- a/frontend/src/pages/file-browser/file-list.tsx
+++ b/frontend/src/pages/file-browser/file-list.tsx
@@ -1,19 +1,17 @@
 import type { FindOptions } from '@furystack/core'
 import { createComponent, Shade } from '@furystack/shades'
-import type { CollectionService, ContextMenuItem } from '@furystack/shades-common-components'
+import type { CollectionService } from '@furystack/shades-common-components'
 import {
   Button,
   ContextMenu,
   ContextMenuManager,
   DataGrid,
   Dialog,
-  Icon,
-  icons,
   NotyService,
   SelectionCell,
 } from '@furystack/shades-common-components'
 import { PathHelper } from '@furystack/utils'
-import { getFallbackMetadata, getFullPath, isMovieFile, isSampleFile, type DirectoryEntry } from 'common'
+import { getFallbackMetadata, isMovieFile, isSampleFile, type DirectoryEntry } from 'common'
 
 import { RelatedMoviesModal } from '../../components/movie-file-management/related-movies-modal.js'
 import { MediaApiClient } from '../../services/api-clients/media-api-client.js'
@@ -24,7 +22,9 @@ import { environmentOptions } from '../../utils/environment-options.js'
 import { triggerDownload } from '../../utils/trigger-download.js'
 import { BreadCrumbs } from './breadcrumbs.js'
 import { DirectoryEntryIcon } from './directory-entry-icon.js'
+import { getContextMenuItems } from './file-context-menu-items.js'
 import { FileInfoModal } from './file-info-modal.js'
+import { handleFileDrop } from './file-upload-handler.js'
 
 export const FileList = Shade<{
   currentDriveLetter: string
@@ -54,6 +54,8 @@ export const FileList = Shade<{
 
     const drivesService = injector.getInstance(DrivesService)
     const notyService = injector.getInstance(NotyService)
+    const mediaApiClient = injector.getInstance(MediaApiClient)
+    const sessionService = injector.getInstance(SessionService)
 
     const [findOptions, setFindOptions] = useState<FindOptions<DirectoryEntry, Array<keyof DirectoryEntry>>>(
       'findOptions',
@@ -89,125 +91,12 @@ export const FileList = Shade<{
       }
     }
 
-    const getContextMenuItems = (entry: DirectoryEntry): Array<ContextMenuItem<() => void>> => {
-      const path = `${currentDriveLetter}:${currentPath}/${entry.name}`
-      const movieMetadata = entry.isFile && !isSampleFile(path) && isMovieFile(path) && getFallbackMetadata(path)
-      const allowScanForMovies = entry.isDirectory
-
-      return [
-        {
-          type: 'item',
-          icon: <Icon icon={icons.folderOpen} size="small" />,
-          label: 'Open',
-          data: () => props.onActivate?.(entry),
-        },
-        ...(movieMetadata
-          ? [
-              {
-                type: 'item' as const,
-                icon: <Icon icon={icons.film} size="small" />,
-                label: `Related movie: ${movieMetadata.title} ${
-                  movieMetadata.type === 'episode' ? `S${movieMetadata.season}E${movieMetadata.episode}` : ''
-                }`,
-                data: () => setRelatedMoviesVisible(true),
-              },
-              {
-                type: 'item' as const,
-                icon: <Icon icon={icons.messageCircle} size="small" />,
-                label: 'Extract Subtitles',
-                data: () => {
-                  injector
-                    .getInstance(MediaApiClient)
-                    .call({
-                      method: 'POST',
-                      action: '/extract-subtitles',
-                      body: {
-                        driveLetter: currentDriveLetter,
-                        path: getFullPath(currentPath, entry.name),
-                      },
-                    })
-                    .then(() => {
-                      notyService.emit('onNotyAdded', {
-                        type: 'success',
-                        title: 'Subtitles extracted',
-                        body: <>Subtitles extracted successfully for file {entry.name}</>,
-                      })
-                    })
-                    .catch(() => {
-                      notyService.emit('onNotyAdded', {
-                        type: 'error',
-                        title: 'Subtitles extraction failed',
-                        body: <>Subtitles extraction failed for file {entry.name}</>,
-                      })
-                    })
-                },
-              },
-            ]
-          : []),
-        ...(allowScanForMovies
-          ? [
-              {
-                type: 'item' as const,
-                icon: <Icon icon={icons.film} size="small" />,
-                label: 'Scan for movies',
-                data: () => {
-                  injector
-                    .getInstance(MediaApiClient)
-                    .call({
-                      method: 'POST',
-                      action: '/scan-for-movies',
-                      body: {
-                        root: {
-                          driveLetter: currentDriveLetter,
-                          path: getFullPath(currentPath, entry.name),
-                        },
-                        autoExtractSubtitles: false,
-                      },
-                    })
-                    .then(() => {
-                      notyService.emit('onNotyAdded', {
-                        type: 'success',
-                        title: 'Movies scanned',
-                        body: <>Movies scanned successfully for folder {entry.name}</>,
-                      })
-                    })
-                    .catch(() => {
-                      notyService.emit('onNotyAdded', {
-                        type: 'error',
-                        title: 'Movies scanning failed',
-                        body: <>Movies scanning failed for folder {entry.name}</>,
-                      })
-                    })
-                },
-              },
-            ]
-          : []),
-        {
-          type: 'item',
-          icon: <Icon icon={icons.info} size="small" />,
-          label: 'Show file info',
-          data: () => setInfoVisible(true),
-        },
-        ...(entry.name !== '..'
-          ? [
-              {
-                type: 'separator' as const,
-              },
-              {
-                type: 'item' as const,
-                icon: <Icon icon={icons.trash} size="small" />,
-                label: 'Delete',
-                data: () => {
-                  const targets = collectDeleteTargets()
-                  if (targets.length > 0) {
-                    setEntriesToDelete(targets)
-                    setDeleteDialogVisible(true)
-                  }
-                },
-              },
-            ]
-          : []),
-      ]
+    const requestDelete = () => {
+      const targets = collectDeleteTargets()
+      if (targets.length > 0) {
+        setEntriesToDelete(targets)
+        setDeleteDialogVisible(true)
+      }
     }
 
     const handleContextMenu = (entry: DirectoryEntry, ev: MouseEvent) => {
@@ -215,7 +104,16 @@ export const FileList = Shade<{
       setActiveEntry(entry)
       contextMenuManager.open({
         position: { x: ev.clientX, y: ev.clientY },
-        items: getContextMenuItems(entry),
+        items: getContextMenuItems(entry, {
+          currentDriveLetter,
+          currentPath,
+          mediaApiClient,
+          notyService,
+          onActivate: props.onActivate,
+          onShowRelatedMovies: () => setRelatedMoviesVisible(true),
+          onShowFileInfo: () => setInfoVisible(true),
+          onDeleteRequest: requestDelete,
+        }),
       })
     }
 
@@ -225,7 +123,7 @@ export const FileList = Shade<{
         for (const entry of entriesToDelete) {
           await drivesService.removeFile({
             letter: currentDriveLetter,
-            path: getFullPath(currentPath, entry.name),
+            path: `${currentPath}/${entry.name}`,
           })
         }
         notyService.emit('onNotyAdded', {
@@ -266,11 +164,7 @@ export const FileList = Shade<{
         }
 
         if (ev.key === 'Delete') {
-          const targets = collectDeleteTargets()
-          if (targets.length > 0) {
-            setEntriesToDelete(targets)
-            setDeleteDialogVisible(true)
-          }
+          requestDelete()
         }
       }
       window.addEventListener('keydown', listener)
@@ -294,47 +188,8 @@ export const FileList = Shade<{
           ondragover={(ev) => {
             ev.preventDefault()
           }}
-          ondrop={async (ev) => {
-            ev.preventDefault()
-            if (ev.dataTransfer?.files) {
-              const session = injector.getInstance(SessionService)
-              if (!(await session.isAuthorized('admin'))) {
-                return notyService.emit('onNotyAdded', {
-                  type: 'warning',
-                  title: 'Not authorized',
-                  body: <>You are not authorized to upload files</>,
-                })
-              }
-
-              const formData = new FormData()
-              for (const file of ev.dataTransfer.files) {
-                formData.append('uploads', file)
-              }
-              await fetch(
-                `${environmentOptions.serviceUrl}/drives/volumes/${encodeURIComponent(
-                  currentDriveLetter,
-                )}/${encodeURIComponent(currentPath)}/upload`,
-                {
-                  method: 'POST',
-                  credentials: 'include',
-                  body: formData,
-                },
-              )
-                .then(() => {
-                  notyService.emit('onNotyAdded', {
-                    type: 'success',
-                    title: 'Upload completed',
-                    body: <>The files are upploaded succesfully</>,
-                  })
-                })
-                .catch((err) =>
-                  notyService.emit('onNotyAdded', {
-                    title: 'Upload failed',
-                    body: <>{getErrorMessage(err)}</>,
-                    type: 'error',
-                  }),
-                )
-            }
+          ondrop={(ev) => {
+            void handleFileDrop({ ev, sessionService, notyService, currentDriveLetter, currentPath })
           }}
           ondblclick={activate}
           onkeydown={(ev) => {
diff --git a/frontend/src/pages/file-browser/file-upload-handler.tsx b/frontend/src/pages/file-browser/file-upload-handler.tsx
new file mode 100644
index 00000000..16e5ce6c
--- /dev/null
+++ b/frontend/src/pages/file-browser/file-upload-handler.tsx
@@ -0,0 +1,61 @@
+import { createComponent } from '@furystack/shades'
+import type { NotyService } from '@furystack/shades-common-components'
+
+import type { SessionService } from '../../services/session.js'
+import { getErrorMessage } from '../../services/get-error-message.js'
+import { environmentOptions } from '../../utils/environment-options.js'
+
+export const handleFileDrop = async ({
+  ev,
+  sessionService,
+  notyService,
+  currentDriveLetter,
+  currentPath,
+}: {
+  ev: DragEvent
+  sessionService: SessionService
+  notyService: NotyService
+  currentDriveLetter: string
+  currentPath: string
+}) => {
+  ev.preventDefault()
+  if (!ev.dataTransfer?.files) return
+
+  if (!(await sessionService.isAuthorized('admin'))) {
+    return notyService.emit('onNotyAdded', {
+      type: 'warning',
+      title: 'Not authorized',
+      body: <>You are not authorized to upload files</>,
+    })
+  }
+
+  const formData = new FormData()
+  for (const file of ev.dataTransfer.files) {
+    formData.append('uploads', file)
+  }
+
+  await fetch(
+    `${environmentOptions.serviceUrl}/drives/volumes/${encodeURIComponent(
+      currentDriveLetter,
+    )}/${encodeURIComponent(currentPath)}/upload`,
+    {
+      method: 'POST',
+      credentials: 'include',
+      body: formData,
+    },
+  )
+    .then(() => {
+      notyService.emit('onNotyAdded', {
+        type: 'success',
+        title: 'Upload completed',
+        body: <>The files are upploaded succesfully</>,
+      })
+    })
+    .catch((err) =>
+      notyService.emit('onNotyAdded', {
+        title: 'Upload failed',
+        body: <>{getErrorMessage(err)}</>,
+        type: 'error',
+      }),
+    )
+}
diff --git a/frontend/src/services/localized-metadata-service.spec.ts b/frontend/src/services/localized-metadata-service.spec.ts
new file mode 100644
index 00000000..d9e6e902
--- /dev/null
+++ b/frontend/src/services/localized-metadata-service.spec.ts
@@ -0,0 +1,191 @@
+import { Injector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import type { MovieMetadataLocalized, SeriesMetadataLocalized } from 'common'
+import { describe, expect, it, vi } from 'vitest'
+import { MediaApiClient } from './api-clients/media-api-client.js'
+import { LocalizedMetadataService } from './localized-metadata-service.js'
+
+const createMockMovieLocalized = (imdbId = 'tt1234567'): MovieMetadataLocalized => ({
+  id: 'localized-1',
+  movieImdbId: imdbId,
+  language: 'en',
+  title: 'Test Movie',
+  plot: 'A test movie plot.',
+  posterUrl: 'https://example.com/poster.jpg',
+  genre: ['Action'],
+  source: 'omdb',
+  sourceId: imdbId,
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+})
+
+const createMockSeriesLocalized = (imdbId = 'tt9876543'): SeriesMetadataLocalized => ({
+  id: 'localized-2',
+  seriesImdbId: imdbId,
+  language: 'en',
+  title: 'Test Series',
+  plot: 'A test series plot.',
+  posterUrl: 'https://example.com/series-poster.jpg',
+  source: 'tmdb',
+  sourceId: '67890',
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+})
+
+describe('LocalizedMetadataService', () => {
+  const createTestInjector = (mockCall: ReturnType<typeof vi.fn>) => {
+    const injector = new Injector()
+    injector.setExplicitInstance(
+      {
+        call: mockCall,
+      } as unknown as MediaApiClient,
+      MediaApiClient,
+    )
+    return injector
+  }
+
+  describe('getMovieLocalized', () => {
+    it('should fetch movie localized metadata by imdb id', async () => {
+      const mockLocalized = createMockMovieLocalized()
+      const mockCall = vi.fn().mockResolvedValue({
+        result: { count: 1, entries: [mockLocalized] },
+      })
+      const injector = createTestInjector(mockCall)
+
+      await usingAsync(injector, async (i) => {
+        const service = i.getInstance(LocalizedMetadataService)
+        const result = await service.getMovieLocalized('tt1234567')
+
+        expect(mockCall).toHaveBeenCalledWith({
+          method: 'GET',
+          action: '/movie-metadata-localized',
+          query: {
+            findOptions: {
+              filter: {
+                movieImdbId: { $eq: 'tt1234567' },
+                language: { $eq: 'en' },
+              },
+              top: 1,
+            },
+          },
+        })
+        expect(result).toEqual(mockLocalized)
+      })
+    })
+
+    it('should cache movie localized results', async () => {
+      const mockLocalized = createMockMovieLocalized()
+      const mockCall = vi.fn().mockResolvedValue({
+        result: { count: 1, entries: [mockLocalized] },
+      })
+      const injector = createTestInjector(mockCall)
+
+      await usingAsync(injector, async (i) => {
+        const service = i.getInstance(LocalizedMetadataService)
+
+        await service.getMovieLocalized('tt1234567')
+        await service.getMovieLocalized('tt1234567')
+
+        expect(mockCall).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('should return undefined when no results', async () => {
+      const mockCall = vi.fn().mockResolvedValue({
+        result: { count: 0, entries: [] },
+      })
+      const injector = createTestInjector(mockCall)
+
+      await usingAsync(injector, async (i) => {
+        const service = i.getInstance(LocalizedMetadataService)
+        const result = await service.getMovieLocalized('tt0000000')
+
+        expect(result).toBeUndefined()
+      })
+    })
+  })
+
+  describe('getSeriesLocalized', () => {
+    it('should fetch series localized metadata by imdb id', async () => {
+      const mockLocalized = createMockSeriesLocalized()
+      const mockCall = vi.fn().mockResolvedValue({
+        result: { count: 1, entries: [mockLocalized] },
+      })
+      const injector = createTestInjector(mockCall)
+
+      await usingAsync(injector, async (i) => {
+        const service = i.getInstance(LocalizedMetadataService)
+        const result = await service.getSeriesLocalized('tt9876543')
+
+        expect(mockCall).toHaveBeenCalledWith({
+          method: 'GET',
+          action: '/series-metadata-localized',
+          query: {
+            findOptions: {
+              filter: {
+                seriesImdbId: { $eq: 'tt9876543' },
+                language: { $eq: 'en' },
+              },
+              top: 1,
+            },
+          },
+        })
+        expect(result).toEqual(mockLocalized)
+      })
+    })
+
+    it('should cache series localized results', async () => {
+      const mockLocalized = createMockSeriesLocalized()
+      const mockCall = vi.fn().mockResolvedValue({
+        result: { count: 1, entries: [mockLocalized] },
+      })
+      const injector = createTestInjector(mockCall)
+
+      await usingAsync(injector, async (i) => {
+        const service = i.getInstance(LocalizedMetadataService)
+
+        await service.getSeriesLocalized('tt9876543')
+        await service.getSeriesLocalized('tt9876543')
+
+        expect(mockCall).toHaveBeenCalledTimes(1)
+      })
+    })
+  })
+
+  describe('getMovieLocalizedAsObservable', () => {
+    it('should return an observable', async () => {
+      const mockCall = vi.fn().mockResolvedValue({
+        result: { count: 1, entries: [createMockMovieLocalized()] },
+      })
+      const injector = createTestInjector(mockCall)
+
+      await usingAsync(injector, async (i) => {
+        const service = i.getInstance(LocalizedMetadataService)
+        const observable = service.getMovieLocalizedAsObservable('tt1234567')
+
+        expect(observable).toBeDefined()
+        expect(observable.getValue().status).toBe('loading')
+      })
+    })
+  })
+
+  describe('disposal', () => {
+    it('should dispose both caches on dispose', async () => {
+      const mockCall = vi.fn().mockResolvedValue({
+        result: { count: 0, entries: [] },
+      })
+      const injector = createTestInjector(mockCall)
+
+      await usingAsync(injector, async (i) => {
+        const service = i.getInstance(LocalizedMetadataService)
+        const movieDisposeSpy = vi.spyOn(service.movieLocalizedCache, Symbol.dispose as never)
+        const seriesDisposeSpy = vi.spyOn(service.seriesLocalizedCache, Symbol.dispose as never)
+
+        service[Symbol.dispose]()
+
+        expect(movieDisposeSpy).toHaveBeenCalled()
+        expect(seriesDisposeSpy).toHaveBeenCalled()
+      })
+    })
+  })
+})
diff --git a/service/src/app-models/media/announce-movie-file-added.ts b/service/src/app-models/media/announce-movie-file-added.ts
new file mode 100644
index 00000000..69b2293d
--- /dev/null
+++ b/service/src/app-models/media/announce-movie-file-added.ts
@@ -0,0 +1,40 @@
+import { isAuthorized } from '@furystack/core'
+import type { Injector } from '@furystack/inject'
+import type { ScopedLogger } from '@furystack/logging'
+import type { DataSet } from '@furystack/repository'
+import type { Movie, MovieFile } from 'common'
+
+import { WebsocketService } from '../../websocket-service.js'
+
+export const announceMovieFileAdded = async ({
+  entity,
+  injector,
+  movieDataSet,
+  logger,
+}: {
+  entity: MovieFile
+  injector: Injector
+  movieDataSet: DataSet<Movie, 'imdbId'>
+  logger: ScopedLogger
+}) => {
+  if (!entity.imdbId) return
+  try {
+    const movie = await movieDataSet.get(injector, entity.imdbId)
+    if (movie) {
+      await injector.getInstance(WebsocketService).announce(
+        {
+          type: 'add-movie',
+          file: { driveLetter: entity.driveLetter, path: entity.path },
+          movie,
+          movieFile: entity,
+        },
+        async ({ injector: i }) => isAuthorized(i, 'admin'),
+      )
+    }
+  } catch (error) {
+    await logger.error({
+      message: `Failed to announce new movie file '${entity.path}'`,
+      data: { error },
+    })
+  }
+}
diff --git a/service/src/app-models/media/media-data-sets.ts b/service/src/app-models/media/media-data-sets.ts
new file mode 100644
index 00000000..df74513e
--- /dev/null
+++ b/service/src/app-models/media/media-data-sets.ts
@@ -0,0 +1,127 @@
+import { getCurrentUser, isAuthorized } from '@furystack/core'
+import type { Injector } from '@furystack/inject'
+import type { AuthorizationResult } from '@furystack/repository'
+import { getRepository } from '@furystack/repository'
+import {
+  Movie,
+  MovieFile,
+  MovieMetadataLocalized,
+  OmdbMovieMetadata,
+  OmdbSeriesMetadata,
+  Series,
+  SeriesMetadataLocalized,
+  TmdbMovieMetadata,
+  TmdbSeriesMetadata,
+  WatchHistoryEntry,
+} from 'common'
+
+import { authorizedOnly } from '../../authorization/authorized-only.js'
+import { withRole } from '../../authorization/with-role.js'
+
+export const setupMediaDataSets = (injector: Injector) => {
+  const repo = getRepository(injector)
+
+  repo.createDataSet(Movie, 'imdbId', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  repo.createDataSet(MovieFile, 'id', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  const onlyOwned = async ({
+    entity,
+    injector: i,
+  }: {
+    entity: WatchHistoryEntry
+    injector: Injector
+  }): Promise<AuthorizationResult> => {
+    const user = await getCurrentUser(i)
+    if (user.username === entity.userName) {
+      return { isAllowed: true }
+    }
+
+    if (await isAuthorized(i, 'admin')) {
+      return { isAllowed: true }
+    }
+    return {
+      isAllowed: false,
+      message: 'You are not authorized to access this resource',
+    }
+  }
+
+  repo.createDataSet(WatchHistoryEntry, 'id', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: authorizedOnly,
+    authorizeUpdate: authorizedOnly,
+    authorizeRemove: authorizedOnly,
+    authorizeGetEntity: onlyOwned,
+    addFilter: async ({ filter, injector: i }) => {
+      const user = await getCurrentUser(i)
+      return {
+        ...filter,
+        filter: {
+          ...filter.filter,
+          userName: { $eq: user.username },
+        },
+      } as typeof filter
+    },
+    authorizeUpdateEntity: onlyOwned,
+    authorizeRemoveEntity: onlyOwned,
+  })
+
+  repo.createDataSet(Series, 'imdbId', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  repo.createDataSet(OmdbMovieMetadata, 'imdbID', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  repo.createDataSet(OmdbSeriesMetadata, 'imdbID', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  repo.createDataSet(TmdbMovieMetadata, 'id', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  repo.createDataSet(TmdbSeriesMetadata, 'id', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  repo.createDataSet(MovieMetadataLocalized, 'id', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+
+  repo.createDataSet(SeriesMetadataLocalized, 'id', {
+    authorizeGet: authorizedOnly,
+    authorizeAdd: withRole('admin'),
+    authorizeUpdate: withRole('admin'),
+    authorizeRemove: withRole('admin'),
+  })
+}
diff --git a/service/src/app-models/media/media-schema-setup.ts b/service/src/app-models/media/media-schema-setup.ts
new file mode 100644
index 00000000..5d541522
--- /dev/null
+++ b/service/src/app-models/media/media-schema-setup.ts
@@ -0,0 +1,786 @@
+import type { Injector } from '@furystack/inject'
+import type { ScopedLogger } from '@furystack/logging'
+import { useSequelize } from '@furystack/sequelize-store'
+import { DataTypes } from 'sequelize'
+import {
+  Movie,
+  MovieFile,
+  MovieMetadataLocalized,
+  OmdbMovieMetadata,
+  OmdbSeriesMetadata,
+  Series,
+  SeriesMetadataLocalized,
+  TmdbMovieMetadata,
+  TmdbSeriesMetadata,
+  WatchHistoryEntry,
+} from 'common'
+
+import { getDefaultDbSettings } from '../../get-default-db-options.js'
+import {
+  MovieModel,
+  MovieFileModel,
+  WatchHistoryEntryModel,
+  SeriesModel,
+  OmdbMovieMetadataModel,
+  OmdbSeriesMetadataModel,
+  TmdbMovieMetadataModel,
+  TmdbSeriesMetadataModel,
+  MovieMetadataLocalizedModel,
+  SeriesMetadataLocalizedModel,
+} from './media-sequelize-models.js'
+
+export const setupMediaSchema = (injector: Injector, logger: ScopedLogger) => {
+  const dbOptions = getDefaultDbSettings('movies.sqlite', logger)
+
+  useSequelize({
+    injector,
+    model: Movie,
+    sequelizeModel: MovieModel,
+    primaryKey: 'imdbId',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      MovieModel.init(
+        {
+          imdbId: {
+            type: DataTypes.STRING,
+            allowNull: false,
+            primaryKey: true,
+          },
+          duration: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          year: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          episode: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          season: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          type: {
+            type: DataTypes.ENUM('episode', 'movie'),
+            allowNull: true,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          seriesId: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+        },
+        { sequelize },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: MovieFile,
+    sequelizeModel: MovieFileModel,
+    primaryKey: 'id',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      MovieFileModel.init(
+        {
+          id: {
+            type: DataTypes.UUIDV4,
+            primaryKey: true,
+            allowNull: false,
+            defaultValue: () => crypto.randomUUID(),
+          },
+          imdbId: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          driveLetter: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          path: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          ffprobe: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          relatedFiles: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+        },
+        { sequelize, indexes: [{ fields: ['imdbId'] }, { fields: ['driveLetter', 'path'], unique: true }] },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: WatchHistoryEntry,
+    sequelizeModel: WatchHistoryEntryModel,
+    primaryKey: 'id',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      WatchHistoryEntryModel.init(
+        {
+          id: {
+            type: DataTypes.UUIDV4,
+            primaryKey: true,
+            allowNull: false,
+            defaultValue: () => crypto.randomUUID(),
+          },
+          userName: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          driveLetter: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          path: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          watchedSeconds: {
+            type: DataTypes.INTEGER,
+            allowNull: false,
+          },
+          completed: {
+            type: DataTypes.BOOLEAN,
+            allowNull: false,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        {
+          sequelize,
+          indexes: [{ fields: ['userName', 'driveLetter', 'path'], unique: true }],
+        },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: Series,
+    sequelizeModel: SeriesModel,
+    primaryKey: 'imdbId',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      SeriesModel.init(
+        {
+          imdbId: {
+            type: DataTypes.STRING,
+            primaryKey: true,
+          },
+          year: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          numberOfSeasons: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        { sequelize },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: OmdbMovieMetadata,
+    sequelizeModel: OmdbMovieMetadataModel,
+    primaryKey: 'imdbID',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      OmdbMovieMetadataModel.init(
+        {
+          imdbID: {
+            type: DataTypes.STRING,
+            primaryKey: true,
+            allowNull: false,
+          },
+          Title: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Year: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Rated: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Released: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Runtime: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Genre: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Director: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Writer: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Actors: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Plot: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Language: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Country: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Awards: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Poster: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Ratings: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          Metascore: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          imdbRating: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          imdbVotes: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Response: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Type: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          DVD: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          BoxOffice: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Production: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Episode: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Season: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          Website: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          seriesID: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+        },
+        { sequelize },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: OmdbSeriesMetadata,
+    sequelizeModel: OmdbSeriesMetadataModel,
+    primaryKey: 'imdbID',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      OmdbSeriesMetadataModel.init(
+        {
+          imdbID: {
+            type: DataTypes.STRING,
+            primaryKey: true,
+            allowNull: false,
+          },
+          Title: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Actors: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Awards: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Country: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Director: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Genre: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          imdbRating: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          imdbVotes: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Language: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Plot: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Poster: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Metascore: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Rated: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Released: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Response: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Runtime: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Type: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Ratings: {
+            type: DataTypes.JSON,
+            allowNull: false,
+          },
+          totalSeasons: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Writer: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          Year: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        { sequelize },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: TmdbMovieMetadata,
+    sequelizeModel: TmdbMovieMetadataModel,
+    primaryKey: 'id',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      TmdbMovieMetadataModel.init(
+        {
+          id: {
+            type: DataTypes.INTEGER,
+            primaryKey: true,
+            allowNull: false,
+          },
+          imdbId: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          title: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          originalTitle: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          overview: {
+            type: DataTypes.TEXT,
+            allowNull: false,
+          },
+          releaseDate: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          runtime: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          posterPath: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          backdropPath: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          genres: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          voteAverage: {
+            type: DataTypes.FLOAT,
+            allowNull: true,
+          },
+          voteCount: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          popularity: {
+            type: DataTypes.FLOAT,
+            allowNull: true,
+          },
+          originalLanguage: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          spokenLanguages: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          productionCountries: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          status: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          tagline: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          budget: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          revenue: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          language: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        { sequelize, indexes: [{ fields: ['imdbId'] }] },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: TmdbSeriesMetadata,
+    sequelizeModel: TmdbSeriesMetadataModel,
+    primaryKey: 'id',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      TmdbSeriesMetadataModel.init(
+        {
+          id: {
+            type: DataTypes.INTEGER,
+            primaryKey: true,
+            allowNull: false,
+          },
+          imdbId: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          name: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          originalName: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          overview: {
+            type: DataTypes.TEXT,
+            allowNull: false,
+          },
+          firstAirDate: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          posterPath: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          backdropPath: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          genres: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          voteAverage: {
+            type: DataTypes.FLOAT,
+            allowNull: true,
+          },
+          voteCount: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          numberOfSeasons: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          numberOfEpisodes: {
+            type: DataTypes.INTEGER,
+            allowNull: true,
+          },
+          status: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          originalLanguage: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          languages: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          language: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        { sequelize, indexes: [{ fields: ['imdbId'] }] },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: MovieMetadataLocalized,
+    sequelizeModel: MovieMetadataLocalizedModel,
+    primaryKey: 'id',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      MovieMetadataLocalizedModel.init(
+        {
+          id: {
+            type: DataTypes.UUIDV4,
+            primaryKey: true,
+            allowNull: false,
+            defaultValue: () => crypto.randomUUID(),
+          },
+          movieImdbId: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          language: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          title: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          plot: {
+            type: DataTypes.TEXT,
+            allowNull: true,
+          },
+          posterUrl: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          genre: {
+            type: DataTypes.JSON,
+            allowNull: true,
+          },
+          source: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          sourceId: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        {
+          sequelize,
+          indexes: [{ fields: ['movieImdbId'] }, { fields: ['movieImdbId', 'language', 'source'], unique: true }],
+        },
+      )
+    },
+  })
+
+  useSequelize({
+    injector,
+    model: SeriesMetadataLocalized,
+    sequelizeModel: SeriesMetadataLocalizedModel,
+    primaryKey: 'id',
+    options: dbOptions,
+    initModel: async (sequelize) => {
+      SeriesMetadataLocalizedModel.init(
+        {
+          id: {
+            type: DataTypes.UUIDV4,
+            primaryKey: true,
+            allowNull: false,
+            defaultValue: () => crypto.randomUUID(),
+          },
+          seriesImdbId: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          language: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          title: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          plot: {
+            type: DataTypes.TEXT,
+            allowNull: true,
+          },
+          posterUrl: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          source: {
+            type: DataTypes.STRING,
+            allowNull: false,
+          },
+          sourceId: {
+            type: DataTypes.STRING,
+            allowNull: true,
+          },
+          createdAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: DataTypes.DATE,
+            allowNull: false,
+          },
+        },
+        {
+          sequelize,
+          indexes: [{ fields: ['seriesImdbId'] }, { fields: ['seriesImdbId', 'language', 'source'], unique: true }],
+        },
+      )
+    },
+  })
+}
diff --git a/service/src/app-models/media/media-sequelize-models.ts b/service/src/app-models/media/media-sequelize-models.ts
new file mode 100644
index 00000000..6518af7c
--- /dev/null
+++ b/service/src/app-models/media/media-sequelize-models.ts
@@ -0,0 +1,205 @@
+import type {
+  Movie,
+  MovieFile,
+  MovieMetadataLocalized,
+  OmdbMovieMetadata,
+  OmdbSeriesMetadata,
+  Series,
+  SeriesMetadataLocalized,
+  TmdbMovieMetadata,
+  TmdbSeriesMetadata,
+  WatchHistoryEntry,
+} from 'common'
+
+import { Model } from 'sequelize'
+
+import type { FfprobeResult } from '../../ffprobe-service.js'
+
+export class MovieModel extends Model<Movie, Movie> implements Movie {
+  declare imdbId: string
+  declare year?: number | undefined
+  declare duration?: number | undefined
+  declare type?: 'episode' | 'movie' | undefined
+  declare seriesId?: string | undefined
+  declare season?: number | undefined
+  declare episode?: number | undefined
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+export class MovieFileModel extends Model<MovieFile, MovieFile> implements MovieFile {
+  declare id: string
+  declare imdbId?: string
+  declare driveLetter: string
+  declare path: string
+  declare ffprobe: FfprobeResult
+  declare relatedFiles?: Array<{ type: 'subtitle' | 'audio' | 'trailer' | 'info' | 'other'; path: string }> | undefined
+}
+
+export class WatchHistoryEntryModel extends Model<WatchHistoryEntry, WatchHistoryEntry> implements WatchHistoryEntry {
+  declare movieFileId: string
+  declare driveLetter: string
+  declare path: string
+  declare id: string
+  declare userName: string
+  declare movie: Movie
+  declare watchedSeconds: number
+  declare completed: boolean
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+export class SeriesModel extends Model<Series, Series> implements Series {
+  declare imdbId: string
+  declare year: string
+  declare numberOfSeasons?: number | undefined
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+export class OmdbMovieMetadataModel extends Model<OmdbMovieMetadata, OmdbMovieMetadata> implements OmdbMovieMetadata {
+  declare Title: string
+  declare Year: string
+  declare Rated: string
+  declare Released: string
+  declare Runtime: string
+  declare Genre: string
+  declare Director: string
+  declare Writer: string
+  declare Actors: string
+  declare Plot: string
+  declare Language: string
+  declare Country: string
+  declare Awards: string
+  declare Poster: string
+  declare Ratings: Array<{ Source: string; Value: string }>
+  declare Metascore: string
+  declare imdbRating: string
+  declare imdbVotes: string
+  declare imdbID: string
+  declare Type: 'episode' | 'movie'
+  declare DVD?: string | undefined
+  declare BoxOffice?: string | undefined
+  declare Production?: string | undefined
+  declare Website?: string | undefined
+  declare Response: 'True'
+  declare seriesID?: string | undefined
+  declare Season?: string | undefined
+  declare Episode?: string | undefined
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+export class OmdbSeriesMetadataModel
+  extends Model<OmdbSeriesMetadata, OmdbSeriesMetadata>
+  implements OmdbSeriesMetadata
+{
+  declare Title: string
+  declare Year: string
+  declare Rated: string
+  declare Released: string
+  declare Runtime: string
+  declare Genre: string
+  declare Director: string
+  declare Writer: string
+  declare Actors: string
+  declare Plot: string
+  declare Language: string
+  declare Country: string
+  declare Awards: string
+  declare Poster: string
+  declare Ratings: Array<{ Source: string; Value: string }>
+  declare Metascore: string
+  declare imdbRating: string
+  declare imdbVotes: string
+  declare imdbID: string
+  declare Type: string
+  declare totalSeasons: string
+  declare Response: string
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+export class TmdbMovieMetadataModel extends Model<TmdbMovieMetadata, TmdbMovieMetadata> implements TmdbMovieMetadata {
+  declare id: number
+  declare imdbId?: string
+  declare title: string
+  declare originalTitle: string
+  declare overview: string
+  declare releaseDate?: string
+  declare runtime?: number
+  declare posterPath?: string
+  declare backdropPath?: string
+  declare genres: Array<{ id: number; name: string }>
+  declare voteAverage?: number
+  declare voteCount?: number
+  declare popularity?: number
+  declare originalLanguage: string
+  declare spokenLanguages?: Array<{ iso_639_1: string; name: string }>
+  declare productionCountries?: Array<{ iso_3166_1: string; name: string }>
+  declare status?: string
+  declare tagline?: string
+  declare budget?: number
+  declare revenue?: number
+  declare language: string
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+export class TmdbSeriesMetadataModel
+  extends Model<TmdbSeriesMetadata, TmdbSeriesMetadata>
+  implements TmdbSeriesMetadata
+{
+  declare id: number
+  declare imdbId?: string
+  declare name: string
+  declare originalName: string
+  declare overview: string
+  declare firstAirDate?: string
+  declare posterPath?: string
+  declare backdropPath?: string
+  declare genres: Array<{ id: number; name: string }>
+  declare voteAverage?: number
+  declare voteCount?: number
+  declare numberOfSeasons?: number
+  declare numberOfEpisodes?: number
+  declare status?: string
+  declare originalLanguage: string
+  declare languages?: string[]
+  declare language: string
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+export class MovieMetadataLocalizedModel
+  extends Model<MovieMetadataLocalized, MovieMetadataLocalized>
+  implements MovieMetadataLocalized
+{
+  declare id: string
+  declare movieImdbId: string
+  declare language: string
+  declare title: string
+  declare plot?: string
+  declare posterUrl?: string
+  declare genre?: string[]
+  declare source: 'omdb' | 'tmdb'
+  declare sourceId?: string
+  declare createdAt: string
+  declare updatedAt: string
+}
+
+export class SeriesMetadataLocalizedModel
+  extends Model<SeriesMetadataLocalized, SeriesMetadataLocalized>
+  implements SeriesMetadataLocalized
+{
+  declare id: string
+  declare seriesImdbId: string
+  declare language: string
+  declare title: string
+  declare plot?: string
+  declare posterUrl?: string
+  declare source: 'omdb' | 'tmdb'
+  declare sourceId?: string
+  declare createdAt: string
+  declare updatedAt: string
+}
diff --git a/service/src/app-models/media/metadata-services/build-synthetic-movie.ts b/service/src/app-models/media/metadata-services/build-synthetic-movie.ts
new file mode 100644
index 00000000..0da591ee
--- /dev/null
+++ b/service/src/app-models/media/metadata-services/build-synthetic-movie.ts
@@ -0,0 +1,38 @@
+import type { TmdbMovieDetailsResponse, TmdbTvDetailsResponse, TmdbEpisodeDetailsResponse } from './tmdb-api-types.js'
+
+/**
+ * Builds a synthetic TmdbMovieDetailsResponse from series + episode data
+ * so callers get a consistent shape for ensureMovieExists.
+ */
+export const buildSyntheticMovieFromEpisode = (
+  tvDetails: TmdbTvDetailsResponse,
+  episodeDetails: TmdbEpisodeDetailsResponse,
+  imdbId: string,
+): TmdbMovieDetailsResponse => ({
+  adult: tvDetails.adult,
+  backdrop_path: episodeDetails.still_path,
+  belongs_to_collection: null,
+  budget: 0,
+  genres: tvDetails.genres,
+  homepage: '',
+  id: episodeDetails.id,
+  imdb_id: imdbId,
+  origin_country: tvDetails.origin_country,
+  original_language: tvDetails.original_language,
+  original_title: episodeDetails.name,
+  overview: episodeDetails.overview,
+  popularity: 0,
+  poster_path: tvDetails.poster_path,
+  production_companies: [],
+  production_countries: [],
+  release_date: episodeDetails.air_date,
+  revenue: 0,
+  runtime: episodeDetails.runtime ?? 0,
+  spoken_languages: [],
+  status: 'Released',
+  tagline: '',
+  title: episodeDetails.name,
+  video: false,
+  vote_average: episodeDetails.vote_average,
+  vote_count: episodeDetails.vote_count,
+})
diff --git a/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts b/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts
new file mode 100644
index 00000000..d3018fa5
--- /dev/null
+++ b/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts
@@ -0,0 +1,735 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import { TmdbClientService, buildTmdbImageUrl } from './tmdb-client-service.js'
+import type {
+  TmdbMovieDetailsResponse,
+  TmdbTvDetailsResponse,
+  TmdbEpisodeDetailsResponse,
+  TmdbFindByIdResponse,
+  TmdbPaginatedResponse,
+  TmdbSearchMovieResult,
+  TmdbSearchTvResult,
+} from './tmdb-api-types.js'
+
+vi.mock('@furystack/core', () => ({
+  useSystemIdentityContext: () => ({}),
+}))
+
+vi.mock('@furystack/logging', () => ({
+  getLogger: () => ({
+    withScope: () => ({
+      verbose: vi.fn().mockResolvedValue(undefined),
+      information: vi.fn().mockResolvedValue(undefined),
+      warning: vi.fn().mockResolvedValue(undefined),
+      error: vi.fn().mockResolvedValue(undefined),
+      debug: vi.fn().mockResolvedValue(undefined),
+    }),
+  }),
+}))
+
+vi.mock('@furystack/inject', () => ({
+  Injectable: () => (target: unknown) => target,
+  Injected: () => () => undefined,
+}))
+
+vi.mock('@furystack/repository', () => ({
+  getDataSetFor: () => ({
+    get: vi.fn(),
+    subscribe: vi.fn(),
+  }),
+}))
+
+const createMockResponse = (body: unknown, status = 200) =>
+  ({
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? 'OK' : `HTTP ${status}`,
+    headers: {
+      get: () => null,
+    },
+    json: () => Promise.resolve(body),
+  }) as unknown as Response
+
+const createSearchMovieResponse = (
+  results: Array<Partial<TmdbSearchMovieResult>> = [],
+): TmdbPaginatedResponse<TmdbSearchMovieResult> => ({
+  page: 1,
+  results: results.map((r) => ({
+    adult: false,
+    backdrop_path: null,
+    genre_ids: [],
+    id: 12345,
+    original_language: 'en',
+    original_title: 'Test Movie',
+    overview: 'A test movie',
+    popularity: 10,
+    poster_path: null,
+    release_date: '2024-01-01',
+    title: 'Test Movie',
+    video: false,
+    vote_average: 7.5,
+    vote_count: 100,
+    ...r,
+  })),
+  total_pages: 1,
+  total_results: results.length,
+})
+
+const createSearchTvResponse = (
+  results: Array<Partial<TmdbSearchTvResult>> = [],
+): TmdbPaginatedResponse<TmdbSearchTvResult> => ({
+  page: 1,
+  results: results.map((r) => ({
+    adult: false,
+    backdrop_path: null,
+    genre_ids: [],
+    id: 67890,
+    origin_country: ['US'],
+    original_language: 'en',
+    original_name: 'Test Series',
+    overview: 'A test series',
+    popularity: 10,
+    poster_path: null,
+    first_air_date: '2024-01-01',
+    name: 'Test Series',
+    vote_average: 8.0,
+    vote_count: 200,
+    ...r,
+  })),
+  total_pages: 1,
+  total_results: results.length,
+})
+
+const createMovieDetailsResponse = (overrides: Partial<TmdbMovieDetailsResponse> = {}): TmdbMovieDetailsResponse => ({
+  adult: false,
+  backdrop_path: null,
+  belongs_to_collection: null,
+  budget: 1000000,
+  genres: [{ id: 28, name: 'Action' }],
+  homepage: '',
+  id: 12345,
+  imdb_id: 'tt1234567',
+  origin_country: ['US'],
+  original_language: 'en',
+  original_title: 'Test Movie',
+  overview: 'A test movie',
+  popularity: 10,
+  poster_path: '/poster.jpg',
+  production_companies: [],
+  production_countries: [],
+  release_date: '2024-01-01',
+  revenue: 5000000,
+  runtime: 120,
+  spoken_languages: [],
+  status: 'Released',
+  tagline: 'A tagline',
+  title: 'Test Movie',
+  video: false,
+  vote_average: 7.5,
+  vote_count: 100,
+  ...overrides,
+})
+
+const createTvDetailsResponse = (overrides: Partial<TmdbTvDetailsResponse> = {}): TmdbTvDetailsResponse => ({
+  adult: false,
+  backdrop_path: null,
+  created_by: [],
+  episode_run_time: [45],
+  first_air_date: '2024-01-01',
+  genres: [{ id: 18, name: 'Drama' }],
+  homepage: '',
+  id: 67890,
+  in_production: true,
+  languages: ['en'],
+  last_air_date: '2024-12-01',
+  last_episode_to_air: null,
+  name: 'Test Series',
+  networks: [],
+  next_episode_to_air: null,
+  number_of_episodes: 10,
+  number_of_seasons: 1,
+  origin_country: ['US'],
+  original_language: 'en',
+  original_name: 'Test Series',
+  overview: 'A test series',
+  popularity: 10,
+  poster_path: '/poster.jpg',
+  production_companies: [],
+  production_countries: [],
+  seasons: [],
+  spoken_languages: [],
+  status: 'Returning Series',
+  tagline: '',
+  type: 'Scripted',
+  vote_average: 8.0,
+  vote_count: 200,
+  external_ids: { imdb_id: 'tt9876543', facebook_id: null, instagram_id: null, twitter_id: null, wikidata_id: null },
+  ...overrides,
+})
+
+const createEpisodeDetailsResponse = (
+  overrides: Partial<TmdbEpisodeDetailsResponse> = {},
+): TmdbEpisodeDetailsResponse => ({
+  air_date: '2024-03-01',
+  episode_number: 5,
+  id: 111222,
+  name: 'Test Episode',
+  overview: 'A test episode',
+  production_code: '',
+  runtime: 45,
+  season_number: 1,
+  still_path: '/still.jpg',
+  vote_average: 8.5,
+  vote_count: 50,
+  crew: [],
+  guest_stars: [],
+  ...overrides,
+})
+
+const createFindByIdResponse = (overrides: Partial<TmdbFindByIdResponse> = {}): TmdbFindByIdResponse => ({
+  movie_results: [],
+  tv_results: [],
+  person_results: [],
+  tv_episode_results: [],
+  tv_season_results: [],
+  ...overrides,
+})
+
+describe('TmdbClientService', () => {
+  let service: TmdbClientService
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    service = new TmdbClientService()
+
+    Object.defineProperty(service, 'logger', {
+      value: {
+        verbose: vi.fn().mockResolvedValue(undefined),
+        information: vi.fn().mockResolvedValue(undefined),
+        warning: vi.fn().mockResolvedValue(undefined),
+        error: vi.fn().mockResolvedValue(undefined),
+        debug: vi.fn().mockResolvedValue(undefined),
+      },
+      writable: true,
+    })
+
+    Object.defineProperty(service, 'semaphore', {
+      value: { execute: <T>(fn: () => Promise<T>) => fn() },
+      writable: true,
+    })
+
+    service.config = {
+      id: 'TMDB_CONFIG',
+      value: { apiKey: 'test-api-key', defaultLanguage: 'en-US' },
+    } as never
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    vi.restoreAllMocks()
+  })
+
+  describe('buildTmdbImageUrl', () => {
+    it('should return undefined for null path', () => {
+      expect(buildTmdbImageUrl(null)).toBeUndefined()
+    })
+
+    it('should build URL with default size', () => {
+      expect(buildTmdbImageUrl('/poster.jpg')).toBe('https://image.tmdb.org/t/p/w500/poster.jpg')
+    })
+
+    it('should build URL with custom size', () => {
+      expect(buildTmdbImageUrl('/poster.jpg', 'original')).toBe('https://image.tmdb.org/t/p/original/poster.jpg')
+    })
+  })
+
+  describe('searchMovie', () => {
+    it('should return not-configured when config is missing', async () => {
+      service.config = undefined
+      const result = await service.searchMovie('Test')
+      expect(result.status).toBe('not-configured')
+    })
+
+    it('should return success with search results', async () => {
+      expect.assertions(2)
+
+      const searchResponse = createSearchMovieResponse([{ id: 12345, title: 'Test Movie' }])
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(searchResponse))
+
+      const result = await service.searchMovie('Test Movie')
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.results[0].title).toBe('Test Movie')
+      }
+    })
+
+    it('should include year in query when provided', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createSearchMovieResponse([])))
+      globalThis.fetch = mockFetch
+
+      await service.searchMovie('Test', { year: 2024 })
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string
+      expect(calledUrl).toContain('year=2024')
+    })
+
+    it('should return not-found for 404 response', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse({}, 404))
+
+      const result = await service.searchMovie('Nonexistent')
+      expect(result.status).toBe('not-found')
+    })
+
+    it('should return error for non-ok response', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse({}, 500))
+
+      const result = await service.searchMovie('Test')
+      expect(result.status).toBe('error')
+    })
+  })
+
+  describe('searchTv', () => {
+    it('should return not-configured when config is missing', async () => {
+      service.config = undefined
+      const result = await service.searchTv('Test')
+      expect(result.status).toBe('not-configured')
+    })
+
+    it('should return success with search results', async () => {
+      expect.assertions(2)
+
+      const searchResponse = createSearchTvResponse([{ id: 67890, name: 'Test Series' }])
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(searchResponse))
+
+      const result = await service.searchTv('Test Series')
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.results[0].name).toBe('Test Series')
+      }
+    })
+  })
+
+  describe('getMovieDetails', () => {
+    it('should return not-configured when config is missing', async () => {
+      service.config = undefined
+      const result = await service.getMovieDetails(12345)
+      expect(result.status).toBe('not-configured')
+    })
+
+    it('should return success with movie details', async () => {
+      expect.assertions(2)
+
+      const details = createMovieDetailsResponse()
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(details))
+
+      const result = await service.getMovieDetails(12345)
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.imdb_id).toBe('tt1234567')
+      }
+    })
+
+    it('should include append_to_response for external_ids', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createMovieDetailsResponse()))
+      globalThis.fetch = mockFetch
+
+      await service.getMovieDetails(12345)
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string
+      expect(calledUrl).toContain('append_to_response=external_ids')
+    })
+  })
+
+  describe('getTvDetails', () => {
+    it('should return success with TV details', async () => {
+      expect.assertions(2)
+
+      const details = createTvDetailsResponse()
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(details))
+
+      const result = await service.getTvDetails(67890)
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.name).toBe('Test Series')
+      }
+    })
+  })
+
+  describe('getEpisodeDetails', () => {
+    it('should return success with episode details', async () => {
+      expect.assertions(2)
+
+      const details = createEpisodeDetailsResponse()
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(details))
+
+      const result = await service.getEpisodeDetails(67890, 1, 5)
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.name).toBe('Test Episode')
+      }
+    })
+
+    it('should construct correct URL for episode', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createEpisodeDetailsResponse()))
+      globalThis.fetch = mockFetch
+
+      await service.getEpisodeDetails(67890, 2, 3)
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string
+      expect(calledUrl).toContain('/tv/67890/season/2/episode/3')
+    })
+  })
+
+  describe('findByImdbId', () => {
+    it('should return not-configured when config is missing', async () => {
+      service.config = undefined
+      const result = await service.findByImdbId('tt1234567')
+      expect(result.status).toBe('not-configured')
+    })
+
+    it('should return success with find results', async () => {
+      expect.assertions(2)
+
+      const findResponse = createFindByIdResponse({
+        tv_results: [
+          {
+            id: 67890,
+            name: 'Test Series',
+          } as TmdbSearchTvResult,
+        ],
+      })
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(findResponse))
+
+      const result = await service.findByImdbId('tt1234567')
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.tv_results[0].id).toBe(67890)
+      }
+    })
+
+    it('should include external_source=imdb_id in URL', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createFindByIdResponse()))
+      globalThis.fetch = mockFetch
+
+      await service.findByImdbId('tt1234567')
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string
+      expect(calledUrl).toContain('/find/tt1234567')
+      expect(calledUrl).toContain('external_source=imdb_id')
+    })
+  })
+
+  describe('rate limit handling', () => {
+    it('should return rate-limited after exhausting retries', async () => {
+      vi.useFakeTimers()
+
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse({}, 429))
+
+      const resultPromise = service.searchMovie('Test')
+
+      for (let i = 0; i < 5; i++) {
+        await vi.advanceTimersByTimeAsync(60_000)
+      }
+
+      const result = await resultPromise
+      expect(result.status).toBe('rate-limited')
+      // 1 initial + 3 retries = 4 total calls
+      expect(globalThis.fetch).toHaveBeenCalledTimes(4)
+
+      vi.useRealTimers()
+    })
+
+    it('should succeed after transient rate limit', async () => {
+      vi.useFakeTimers()
+
+      const mockFetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse({}, 429))
+        .mockResolvedValueOnce(createMockResponse(createSearchMovieResponse([{ id: 1 }])))
+
+      globalThis.fetch = mockFetch
+
+      const resultPromise = service.searchMovie('Test')
+      await vi.advanceTimersByTimeAsync(10_000)
+
+      const result = await resultPromise
+      expect(result.status).toBe('success')
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+
+      vi.useRealTimers()
+    })
+
+    it('should use Retry-After header when present', async () => {
+      vi.useFakeTimers()
+
+      const rateLimitResponse = {
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        headers: { get: (name: string) => (name === 'Retry-After' ? '5' : null) },
+        json: () => Promise.resolve({}),
+      } as unknown as Response
+
+      const mockFetch = vi
+        .fn()
+        .mockResolvedValueOnce(rateLimitResponse)
+        .mockResolvedValueOnce(createMockResponse(createSearchMovieResponse([{ id: 1 }])))
+
+      globalThis.fetch = mockFetch
+
+      const resultPromise = service.searchMovie('Test')
+
+      // 5 seconds from Retry-After header
+      await vi.advanceTimersByTimeAsync(5_000)
+
+      const result = await resultPromise
+      expect(result.status).toBe('success')
+
+      vi.useRealTimers()
+    })
+  })
+
+  describe('fetchTmdbMovieMetadata', () => {
+    it('should return not-configured when config is missing', async () => {
+      service.config = undefined
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Test' })
+      expect(result.status).toBe('not-configured')
+    })
+
+    it('should return success for a movie search', async () => {
+      expect.assertions(2)
+
+      const searchResponse = createSearchMovieResponse([{ id: 12345 }])
+      const detailsResponse = createMovieDetailsResponse({ imdb_id: 'tt1234567' })
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(searchResponse))
+        .mockResolvedValueOnce(createMockResponse(detailsResponse))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Test Movie', year: 2024 })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.movie.imdb_id).toBe('tt1234567')
+      }
+    })
+
+    it('should return not-found when search returns empty results', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(createSearchMovieResponse([])))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Nonexistent' })
+      expect(result.status).toBe('not-found')
+    })
+
+    it('should return not-found when movie has no IMDB ID', async () => {
+      const searchResponse = createSearchMovieResponse([{ id: 12345 }])
+      const detailsResponse = createMovieDetailsResponse({ imdb_id: null, external_ids: undefined })
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(searchResponse))
+        .mockResolvedValueOnce(createMockResponse(detailsResponse))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Test' })
+      expect(result.status).toBe('not-found')
+    })
+
+    it('should use external_ids.imdb_id as fallback', async () => {
+      expect.assertions(2)
+
+      const searchResponse = createSearchMovieResponse([{ id: 12345 }])
+      const detailsResponse = createMovieDetailsResponse({
+        imdb_id: null,
+        external_ids: {
+          imdb_id: 'tt7777777',
+          facebook_id: null,
+          instagram_id: null,
+          twitter_id: null,
+          wikidata_id: null,
+        },
+      })
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(searchResponse))
+        .mockResolvedValueOnce(createMockResponse(detailsResponse))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Test' })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.movie.imdb_id).toBe('tt7777777')
+      }
+    })
+
+    it('should return error when fetch throws', async () => {
+      globalThis.fetch = vi.fn().mockRejectedValue(new Error('Network error'))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Test' })
+      expect(result.status).toBe('error')
+    })
+  })
+
+  describe('fetchTmdbMovieMetadata - episode flow', () => {
+    it('should fetch episode metadata when season and episode are provided', async () => {
+      expect.assertions(4)
+
+      const searchTvResponse = createSearchTvResponse([{ id: 67890 }])
+      const tvDetailsResponse = createTvDetailsResponse()
+      const episodeResponse = createEpisodeDetailsResponse()
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(searchTvResponse))
+        .mockResolvedValueOnce(createMockResponse(tvDetailsResponse))
+        .mockResolvedValueOnce(createMockResponse(episodeResponse))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Test Series', season: 1, episode: 5 })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.movie.imdb_id).toBe('tt9876543')
+        expect(result.data.episode?.name).toBe('Test Episode')
+        expect(result.data.series?.name).toBe('Test Series')
+      }
+    })
+
+    it('should return not-found when TV search returns no results', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(createSearchTvResponse([])))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Nonexistent', season: 1, episode: 1 })
+      expect(result.status).toBe('not-found')
+    })
+
+    it('should return not-found when TV series has no IMDB ID', async () => {
+      const searchTvResponse = createSearchTvResponse([{ id: 67890 }])
+      const tvDetailsResponse = createTvDetailsResponse({
+        external_ids: {
+          imdb_id: null,
+          facebook_id: null,
+          instagram_id: null,
+          twitter_id: null,
+          wikidata_id: null,
+        },
+      })
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(searchTvResponse))
+        .mockResolvedValueOnce(createMockResponse(tvDetailsResponse))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Test', season: 1, episode: 1 })
+      expect(result.status).toBe('not-found')
+    })
+
+    it('should build synthetic movie from episode data', async () => {
+      expect.assertions(3)
+
+      const searchTvResponse = createSearchTvResponse([{ id: 67890 }])
+      const tvDetailsResponse = createTvDetailsResponse()
+      const episodeResponse = createEpisodeDetailsResponse({ name: 'Pilot', runtime: 60 })
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(searchTvResponse))
+        .mockResolvedValueOnce(createMockResponse(tvDetailsResponse))
+        .mockResolvedValueOnce(createMockResponse(episodeResponse))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Test', season: 1, episode: 1 })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.movie.title).toBe('Pilot')
+        expect(result.data.movie.runtime).toBe(60)
+      }
+    })
+  })
+
+  describe('fetchTmdbSeriesMetadata', () => {
+    it('should return not-configured when config is missing', async () => {
+      service.config = undefined
+      const result = await service.fetchTmdbSeriesMetadata({ imdbId: 'tt1234567' })
+      expect(result.status).toBe('not-configured')
+    })
+
+    it('should return success with series details', async () => {
+      expect.assertions(2)
+
+      const findResponse = createFindByIdResponse({
+        tv_results: [{ id: 67890 } as TmdbSearchTvResult],
+      })
+      const tvDetailsResponse = createTvDetailsResponse()
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(findResponse))
+        .mockResolvedValueOnce(createMockResponse(tvDetailsResponse))
+
+      const result = await service.fetchTmdbSeriesMetadata({ imdbId: 'tt1234567' })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.name).toBe('Test Series')
+      }
+    })
+
+    it('should return not-found when IMDB ID has no TV results', async () => {
+      const findResponse = createFindByIdResponse({ tv_results: [] })
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(findResponse))
+
+      const result = await service.fetchTmdbSeriesMetadata({ imdbId: 'tt9999999' })
+      expect(result.status).toBe('not-found')
+    })
+
+    it('should return error when fetch throws', async () => {
+      globalThis.fetch = vi.fn().mockRejectedValue(new Error('Network error'))
+
+      const result = await service.fetchTmdbSeriesMetadata({ imdbId: 'tt1234567' })
+      expect(result.status).toBe('error')
+    })
+  })
+
+  describe('authorization header', () => {
+    it('should send Bearer token in Authorization header', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createSearchMovieResponse([])))
+      globalThis.fetch = mockFetch
+
+      await service.searchMovie('Test')
+
+      const calledOptions = mockFetch.mock.calls[0][1] as RequestInit
+      expect((calledOptions.headers as Record<string, string>).Authorization).toBe('Bearer test-api-key')
+    })
+  })
+
+  describe('language defaults', () => {
+    it('should use config defaultLanguage', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createSearchMovieResponse([])))
+      globalThis.fetch = mockFetch
+
+      await service.searchMovie('Test')
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string
+      expect(calledUrl).toContain('language=en-US')
+    })
+
+    it('should use explicit language override', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createSearchMovieResponse([])))
+      globalThis.fetch = mockFetch
+
+      await service.searchMovie('Test', { language: 'fr-FR' })
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string
+      expect(calledUrl).toContain('language=fr-FR')
+    })
+
+    it('should fall back to en-US when config has no defaultLanguage', async () => {
+      service.config = {
+        id: 'TMDB_CONFIG',
+        value: { apiKey: 'test-api-key' },
+      } as never
+
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createSearchMovieResponse([])))
+      globalThis.fetch = mockFetch
+
+      await service.searchMovie('Test')
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string
+      expect(calledUrl).toContain('language=en-US')
+    })
+  })
+})
diff --git a/service/src/app-models/media/metadata-services/tmdb-client-service.ts b/service/src/app-models/media/metadata-services/tmdb-client-service.ts
index a161f230..2dc7a317 100644
--- a/service/src/app-models/media/metadata-services/tmdb-client-service.ts
+++ b/service/src/app-models/media/metadata-services/tmdb-client-service.ts
@@ -16,6 +16,7 @@ import type {
   TmdbSearchMovieResult,
   TmdbSearchTvResult,
 } from './tmdb-api-types.js'
+import { buildSyntheticMovieFromEpisode } from './build-synthetic-movie.js'
 
 export type TmdbFetchResult<T> =
   | { status: 'success'; data: T }
@@ -51,6 +52,10 @@ export class TmdbClientService {
 
   private readonly semaphore = new Semaphore(1)
 
+  private getLanguage(override?: string): string {
+    return override ?? this.config?.value.defaultLanguage ?? 'en-US'
+  }
+
   public init() {
     void this.initAsync().catch((error) => {
       void this.logger.error({ message: 'Failed to initialize TMDB Client Service', data: { error } })
@@ -166,7 +171,7 @@ export class TmdbClientService {
   ): Promise<TmdbFetchResult<TmdbPaginatedResponse<TmdbSearchMovieResult>>> {
     const params = new URLSearchParams({
       query: title,
-      language: options?.language ?? this.config?.value.defaultLanguage ?? 'en-US',
+      language: this.getLanguage(options?.language),
     })
     if (options?.year) params.set('year', String(options.year))
 
@@ -181,7 +186,7 @@ export class TmdbClientService {
   ): Promise<TmdbFetchResult<TmdbPaginatedResponse<TmdbSearchTvResult>>> {
     const params = new URLSearchParams({
       query: title,
-      language: options?.language ?? this.config?.value.defaultLanguage ?? 'en-US',
+      language: this.getLanguage(options?.language),
     })
 
     return this.semaphore.execute(() => this.fetchJson(`/search/tv?${params}`, { description: `search tv '${title}'` }))
@@ -192,7 +197,7 @@ export class TmdbClientService {
     options?: { language?: string },
   ): Promise<TmdbFetchResult<TmdbMovieDetailsResponse>> {
     const params = new URLSearchParams({
-      language: options?.language ?? this.config?.value.defaultLanguage ?? 'en-US',
+      language: this.getLanguage(options?.language),
       append_to_response: 'external_ids',
     })
 
@@ -206,7 +211,7 @@ export class TmdbClientService {
     options?: { language?: string },
   ): Promise<TmdbFetchResult<TmdbTvDetailsResponse>> {
     const params = new URLSearchParams({
-      language: options?.language ?? this.config?.value.defaultLanguage ?? 'en-US',
+      language: this.getLanguage(options?.language),
       append_to_response: 'external_ids',
     })
 
@@ -222,7 +227,7 @@ export class TmdbClientService {
     options?: { language?: string },
   ): Promise<TmdbFetchResult<TmdbEpisodeDetailsResponse>> {
     const params = new URLSearchParams({
-      language: options?.language ?? this.config?.value.defaultLanguage ?? 'en-US',
+      language: this.getLanguage(options?.language),
     })
 
     return this.semaphore.execute(() =>
@@ -235,7 +240,7 @@ export class TmdbClientService {
   public async findByImdbId(imdbId: string): Promise<TmdbFetchResult<TmdbFindByIdResponse>> {
     const params = new URLSearchParams({
       external_source: 'imdb_id',
-      language: this.config?.value.defaultLanguage ?? 'en-US',
+      language: this.getLanguage(),
     })
 
     return this.semaphore.execute(() =>
@@ -319,41 +324,10 @@ export class TmdbClientService {
     const episodeResult = await this.getEpisodeDetails(tvId, season, episode)
     if (episodeResult.status !== 'success') return episodeResult
 
-    // Build a synthetic TmdbMovieDetailsResponse from series+episode data
-    // so the caller gets a consistent shape for ensureMovieExists
-    const syntheticMovie: TmdbMovieDetailsResponse = {
-      adult: tvResult.data.adult,
-      backdrop_path: episodeResult.data.still_path,
-      belongs_to_collection: null,
-      budget: 0,
-      genres: tvResult.data.genres,
-      homepage: '',
-      id: episodeResult.data.id,
-      imdb_id: imdbId,
-      origin_country: tvResult.data.origin_country,
-      original_language: tvResult.data.original_language,
-      original_title: episodeResult.data.name,
-      overview: episodeResult.data.overview,
-      popularity: 0,
-      poster_path: tvResult.data.poster_path,
-      production_companies: [],
-      production_countries: [],
-      release_date: episodeResult.data.air_date,
-      revenue: 0,
-      runtime: episodeResult.data.runtime ?? 0,
-      spoken_languages: [],
-      status: 'Released',
-      tagline: '',
-      title: episodeResult.data.name,
-      video: false,
-      vote_average: episodeResult.data.vote_average,
-      vote_count: episodeResult.data.vote_count,
-    }
-
     return {
       status: 'success',
       data: {
-        movie: syntheticMovie,
+        movie: buildSyntheticMovieFromEpisode(tvResult.data, episodeResult.data, imdbId),
         episode: episodeResult.data,
         series: tvResult.data,
       },
diff --git a/service/src/app-models/media/setup-media.spec.ts b/service/src/app-models/media/setup-media.spec.ts
index e1e19c04..478e609d 100644
--- a/service/src/app-models/media/setup-media.spec.ts
+++ b/service/src/app-models/media/setup-media.spec.ts
@@ -3,7 +3,7 @@ import { usingAsync } from '@furystack/utils'
 import type { Movie, MovieFile } from 'common'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { WebsocketService } from '../../websocket-service.js'
-import { announceMovieFileAdded } from './setup-media.js'
+import { announceMovieFileAdded } from './announce-movie-file-added.js'
 
 const mockDataSetGet = vi.fn()
 const mockAnnounce = vi.fn().mockResolvedValue(undefined)
diff --git a/service/src/app-models/media/setup-media.ts b/service/src/app-models/media/setup-media.ts
index 9425dd13..b30e6466 100644
--- a/service/src/app-models/media/setup-media.ts
+++ b/service/src/app-models/media/setup-media.ts
@@ -1,1114 +1,23 @@
 import type { Injector } from '@furystack/inject'
-import type { ScopedLogger } from '@furystack/logging'
 import { getLogger } from '@furystack/logging'
+import { getDataSetFor } from '@furystack/repository'
+import { Movie, MovieFile } from 'common'
 
-import {
-  Movie,
-  MovieFile,
-  MovieMetadataLocalized,
-  OmdbMovieMetadata,
-  OmdbSeriesMetadata,
-  Series,
-  SeriesMetadataLocalized,
-  TmdbMovieMetadata,
-  TmdbSeriesMetadata,
-  WatchHistoryEntry,
-} from 'common'
-
-import { getCurrentUser, isAuthorized } from '@furystack/core'
-import type { AuthorizationResult, DataSet } from '@furystack/repository'
-import { getDataSetFor, getRepository } from '@furystack/repository'
-import { useSequelize } from '@furystack/sequelize-store'
-import { DataTypes, Model } from 'sequelize'
-
-import { authorizedOnly } from '../../authorization/authorized-only.js'
 import { ExternalServiceStatusRegistry } from '../../external-service-status-registry.js'
-import { withRole } from '../../authorization/with-role.js'
-import type { FfprobeResult } from '../../ffprobe-service.js'
-import { getDefaultDbSettings } from '../../get-default-db-options.js'
-import { WebsocketService } from '../../websocket-service.js'
 import { OmdbClientService } from './metadata-services/omdb-client-service.js'
 import { TmdbClientService } from './metadata-services/tmdb-client-service.js'
 import { useMovieFileMaintainer } from './services/movie-file-maintainer.js'
+import { announceMovieFileAdded } from './announce-movie-file-added.js'
+import { setupMediaSchema } from './media-schema-setup.js'
+import { setupMediaDataSets } from './media-data-sets.js'
 
-class MovieModel extends Model<Movie, Movie> implements Movie {
-  declare imdbId: string
-  declare year?: number | undefined
-  declare duration?: number | undefined
-  declare type?: 'episode' | 'movie' | undefined
-  declare seriesId?: string | undefined
-  declare season?: number | undefined
-  declare episode?: number | undefined
-  declare createdAt: string
-  declare updatedAt: string
-}
-
-class MovieFileModel extends Model<MovieFile, MovieFile> implements MovieFile {
-  declare id: string
-  declare imdbId?: string
-  declare driveLetter: string
-  declare path: string
-  declare ffprobe: FfprobeResult
-  declare relatedFiles?: Array<{ type: 'subtitle' | 'audio' | 'trailer' | 'info' | 'other'; path: string }> | undefined
-}
-
-class WatchHistoryEntryModel extends Model<WatchHistoryEntry, WatchHistoryEntry> implements WatchHistoryEntry {
-  declare movieFileId: string
-  declare driveLetter: string
-  declare path: string
-  declare id: string
-  declare userName: string
-  declare movie: Movie
-  declare watchedSeconds: number
-  declare completed: boolean
-  declare createdAt: string
-  declare updatedAt: string
-}
-
-class SeriesModel extends Model<Series, Series> implements Series {
-  declare imdbId: string
-  declare year: string
-  declare numberOfSeasons?: number | undefined
-  declare createdAt: string
-  declare updatedAt: string
-}
-
-class OmdbMovieMetadataModel extends Model<OmdbMovieMetadata, OmdbMovieMetadata> implements OmdbMovieMetadata {
-  declare Title: string
-  declare Year: string
-  declare Rated: string
-  declare Released: string
-  declare Runtime: string
-  declare Genre: string
-  declare Director: string
-  declare Writer: string
-  declare Actors: string
-  declare Plot: string
-  declare Language: string
-  declare Country: string
-  declare Awards: string
-  declare Poster: string
-  declare Ratings: Array<{ Source: string; Value: string }>
-  declare Metascore: string
-  declare imdbRating: string
-  declare imdbVotes: string
-  declare imdbID: string
-  declare Type: 'episode' | 'movie'
-  declare DVD?: string | undefined
-  declare BoxOffice?: string | undefined
-  declare Production?: string | undefined
-  declare Website?: string | undefined
-  declare Response: 'True'
-  declare seriesID?: string | undefined
-  declare Season?: string | undefined
-  declare Episode?: string | undefined
-  declare createdAt: string
-  declare updatedAt: string
-}
-
-class OmdbSeriesMetadataModel extends Model<OmdbSeriesMetadata, OmdbSeriesMetadata> implements OmdbSeriesMetadata {
-  declare Title: string
-  declare Year: string
-  declare Rated: string
-  declare Released: string
-  declare Runtime: string
-  declare Genre: string
-  declare Director: string
-  declare Writer: string
-  declare Actors: string
-  declare Plot: string
-  declare Language: string
-  declare Country: string
-  declare Awards: string
-  declare Poster: string
-  declare Ratings: Array<{ Source: string; Value: string }>
-  declare Metascore: string
-  declare imdbRating: string
-  declare imdbVotes: string
-  declare imdbID: string
-  declare Type: string
-  declare totalSeasons: string
-  declare Response: string
-  declare createdAt: string
-  declare updatedAt: string
-}
-
-class TmdbMovieMetadataModel extends Model<TmdbMovieMetadata, TmdbMovieMetadata> implements TmdbMovieMetadata {
-  declare id: number
-  declare imdbId?: string
-  declare title: string
-  declare originalTitle: string
-  declare overview: string
-  declare releaseDate?: string
-  declare runtime?: number
-  declare posterPath?: string
-  declare backdropPath?: string
-  declare genres: Array<{ id: number; name: string }>
-  declare voteAverage?: number
-  declare voteCount?: number
-  declare popularity?: number
-  declare originalLanguage: string
-  declare spokenLanguages?: Array<{ iso_639_1: string; name: string }>
-  declare productionCountries?: Array<{ iso_3166_1: string; name: string }>
-  declare status?: string
-  declare tagline?: string
-  declare budget?: number
-  declare revenue?: number
-  declare language: string
-  declare createdAt: string
-  declare updatedAt: string
-}
-
-class TmdbSeriesMetadataModel extends Model<TmdbSeriesMetadata, TmdbSeriesMetadata> implements TmdbSeriesMetadata {
-  declare id: number
-  declare imdbId?: string
-  declare name: string
-  declare originalName: string
-  declare overview: string
-  declare firstAirDate?: string
-  declare posterPath?: string
-  declare backdropPath?: string
-  declare genres: Array<{ id: number; name: string }>
-  declare voteAverage?: number
-  declare voteCount?: number
-  declare numberOfSeasons?: number
-  declare numberOfEpisodes?: number
-  declare status?: string
-  declare originalLanguage: string
-  declare languages?: string[]
-  declare language: string
-  declare createdAt: string
-  declare updatedAt: string
-}
-
-class MovieMetadataLocalizedModel
-  extends Model<MovieMetadataLocalized, MovieMetadataLocalized>
-  implements MovieMetadataLocalized
-{
-  declare id: string
-  declare movieImdbId: string
-  declare language: string
-  declare title: string
-  declare plot?: string
-  declare posterUrl?: string
-  declare genre?: string[]
-  declare source: 'omdb' | 'tmdb'
-  declare sourceId?: string
-  declare createdAt: string
-  declare updatedAt: string
-}
-
-class SeriesMetadataLocalizedModel
-  extends Model<SeriesMetadataLocalized, SeriesMetadataLocalized>
-  implements SeriesMetadataLocalized
-{
-  declare id: string
-  declare seriesImdbId: string
-  declare language: string
-  declare title: string
-  declare plot?: string
-  declare posterUrl?: string
-  declare source: 'omdb' | 'tmdb'
-  declare sourceId?: string
-  declare createdAt: string
-  declare updatedAt: string
-}
-
-export const announceMovieFileAdded = async ({
-  entity,
-  injector,
-  movieDataSet,
-  logger,
-}: {
-  entity: MovieFile
-  injector: Injector
-  movieDataSet: DataSet<Movie, 'imdbId'>
-  logger: ScopedLogger
-}) => {
-  if (!entity.imdbId) return
-  try {
-    const movie = await movieDataSet.get(injector, entity.imdbId)
-    if (movie) {
-      await injector.getInstance(WebsocketService).announce(
-        {
-          type: 'add-movie',
-          file: { driveLetter: entity.driveLetter, path: entity.path },
-          movie,
-          movieFile: entity,
-        },
-        async ({ injector: i }) => isAuthorized(i, 'admin'),
-      )
-    }
-  } catch (error) {
-    await logger.error({
-      message: `Failed to announce new movie file '${entity.path}'`,
-      data: { error },
-    })
-  }
-}
+export { announceMovieFileAdded } from './announce-movie-file-added.js'
 
 export const setupMedia = async (injector: Injector) => {
   const logger = getLogger(injector).withScope('Movies')
 
-  const dbOptions = getDefaultDbSettings('movies.sqlite', logger)
-
-  useSequelize({
-    injector,
-    model: Movie,
-    sequelizeModel: MovieModel,
-    primaryKey: 'imdbId',
-    options: dbOptions,
-    initModel: async (sequelize) => {
-      MovieModel.init(
-        {
-          imdbId: {
-            type: DataTypes.STRING,
-            allowNull: false,
-            primaryKey: true,
-          },
-          duration: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          year: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          episode: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          season: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          type: {
-            type: DataTypes.ENUM('episode', 'movie'),
-            allowNull: true,
-          },
-          createdAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          updatedAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          seriesId: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-        },
-        { sequelize },
-      )
-    },
-  })
-
-  useSequelize({
-    injector,
-    model: MovieFile,
-    sequelizeModel: MovieFileModel,
-    primaryKey: 'id',
-    options: dbOptions,
-    initModel: async (sequelize) => {
-      MovieFileModel.init(
-        {
-          id: {
-            type: DataTypes.UUIDV4,
-            primaryKey: true,
-            allowNull: false,
-            defaultValue: () => crypto.randomUUID(),
-          },
-          imdbId: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          driveLetter: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          path: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          ffprobe: {
-            type: DataTypes.JSON,
-            allowNull: true,
-          },
-          relatedFiles: {
-            type: DataTypes.JSON,
-            allowNull: true,
-          },
-        },
-        { sequelize, indexes: [{ fields: ['imdbId'] }, { fields: ['driveLetter', 'path'], unique: true }] },
-      )
-    },
-  })
-
-  useSequelize({
-    injector,
-    model: WatchHistoryEntry,
-    sequelizeModel: WatchHistoryEntryModel,
-    primaryKey: 'id',
-    options: dbOptions,
-    initModel: async (sequelize) => {
-      WatchHistoryEntryModel.init(
-        {
-          id: {
-            type: DataTypes.UUIDV4,
-            primaryKey: true,
-            allowNull: false,
-            defaultValue: () => crypto.randomUUID(),
-          },
-          userName: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          driveLetter: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          path: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          watchedSeconds: {
-            type: DataTypes.INTEGER,
-            allowNull: false,
-          },
-          completed: {
-            type: DataTypes.BOOLEAN,
-            allowNull: false,
-          },
-          createdAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          updatedAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-        },
-        {
-          sequelize,
-          indexes: [{ fields: ['userName', 'driveLetter', 'path'], unique: true }],
-        },
-      )
-    },
-  })
-
-  useSequelize({
-    injector,
-    model: Series,
-    sequelizeModel: SeriesModel,
-    primaryKey: 'imdbId',
-    options: dbOptions,
-    initModel: async (sequelize) => {
-      SeriesModel.init(
-        {
-          imdbId: {
-            type: DataTypes.STRING,
-            primaryKey: true,
-          },
-          year: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          numberOfSeasons: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          createdAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          updatedAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-        },
-        { sequelize },
-      )
-    },
-  })
-
-  useSequelize({
-    injector,
-    model: OmdbMovieMetadata,
-    sequelizeModel: OmdbMovieMetadataModel,
-    primaryKey: 'imdbID',
-    options: dbOptions,
-    initModel: async (sequelize) => {
-      OmdbMovieMetadataModel.init(
-        {
-          imdbID: {
-            type: DataTypes.STRING,
-            primaryKey: true,
-            allowNull: false,
-          },
-          Title: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Year: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Rated: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Released: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Runtime: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Genre: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Director: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Writer: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Actors: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Plot: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Language: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Country: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Awards: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Poster: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Ratings: {
-            type: DataTypes.JSON,
-            allowNull: true,
-          },
-          Metascore: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          imdbRating: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          imdbVotes: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Response: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Type: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          DVD: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          BoxOffice: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Production: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Episode: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Season: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          Website: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          createdAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          updatedAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          seriesID: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-        },
-        { sequelize },
-      )
-    },
-  })
-
-  useSequelize({
-    injector,
-    model: OmdbSeriesMetadata,
-    sequelizeModel: OmdbSeriesMetadataModel,
-    primaryKey: 'imdbID',
-    options: dbOptions,
-    initModel: async (sequelize) => {
-      OmdbSeriesMetadataModel.init(
-        {
-          imdbID: {
-            type: DataTypes.STRING,
-            primaryKey: true,
-            allowNull: false,
-          },
-          Title: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Actors: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Awards: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Country: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Director: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Genre: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          imdbRating: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          imdbVotes: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Language: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Plot: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Poster: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Metascore: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Rated: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Released: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Response: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Runtime: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Type: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Ratings: {
-            type: DataTypes.JSON,
-            allowNull: false,
-          },
-          totalSeasons: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Writer: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          Year: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          createdAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          updatedAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-        },
-        { sequelize },
-      )
-    },
-  })
-
-  useSequelize({
-    injector,
-    model: TmdbMovieMetadata,
-    sequelizeModel: TmdbMovieMetadataModel,
-    primaryKey: 'id',
-    options: dbOptions,
-    initModel: async (sequelize) => {
-      TmdbMovieMetadataModel.init(
-        {
-          id: {
-            type: DataTypes.INTEGER,
-            primaryKey: true,
-            allowNull: false,
-          },
-          imdbId: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          title: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          originalTitle: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          overview: {
-            type: DataTypes.TEXT,
-            allowNull: false,
-          },
-          releaseDate: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          runtime: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          posterPath: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          backdropPath: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          genres: {
-            type: DataTypes.JSON,
-            allowNull: true,
-          },
-          voteAverage: {
-            type: DataTypes.FLOAT,
-            allowNull: true,
-          },
-          voteCount: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          popularity: {
-            type: DataTypes.FLOAT,
-            allowNull: true,
-          },
-          originalLanguage: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          spokenLanguages: {
-            type: DataTypes.JSON,
-            allowNull: true,
-          },
-          productionCountries: {
-            type: DataTypes.JSON,
-            allowNull: true,
-          },
-          status: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          tagline: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          budget: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          revenue: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          language: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          createdAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          updatedAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-        },
-        { sequelize, indexes: [{ fields: ['imdbId'] }] },
-      )
-    },
-  })
-
-  useSequelize({
-    injector,
-    model: TmdbSeriesMetadata,
-    sequelizeModel: TmdbSeriesMetadataModel,
-    primaryKey: 'id',
-    options: dbOptions,
-    initModel: async (sequelize) => {
-      TmdbSeriesMetadataModel.init(
-        {
-          id: {
-            type: DataTypes.INTEGER,
-            primaryKey: true,
-            allowNull: false,
-          },
-          imdbId: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          name: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          originalName: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          overview: {
-            type: DataTypes.TEXT,
-            allowNull: false,
-          },
-          firstAirDate: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          posterPath: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          backdropPath: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          genres: {
-            type: DataTypes.JSON,
-            allowNull: true,
-          },
-          voteAverage: {
-            type: DataTypes.FLOAT,
-            allowNull: true,
-          },
-          voteCount: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          numberOfSeasons: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          numberOfEpisodes: {
-            type: DataTypes.INTEGER,
-            allowNull: true,
-          },
-          status: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          originalLanguage: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          languages: {
-            type: DataTypes.JSON,
-            allowNull: true,
-          },
-          language: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          createdAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          updatedAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-        },
-        { sequelize, indexes: [{ fields: ['imdbId'] }] },
-      )
-    },
-  })
-
-  useSequelize({
-    injector,
-    model: MovieMetadataLocalized,
-    sequelizeModel: MovieMetadataLocalizedModel,
-    primaryKey: 'id',
-    options: dbOptions,
-    initModel: async (sequelize) => {
-      MovieMetadataLocalizedModel.init(
-        {
-          id: {
-            type: DataTypes.UUIDV4,
-            primaryKey: true,
-            allowNull: false,
-            defaultValue: () => crypto.randomUUID(),
-          },
-          movieImdbId: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          language: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          title: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          plot: {
-            type: DataTypes.TEXT,
-            allowNull: true,
-          },
-          posterUrl: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          genre: {
-            type: DataTypes.JSON,
-            allowNull: true,
-          },
-          source: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          sourceId: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          createdAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          updatedAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-        },
-        {
-          sequelize,
-          indexes: [{ fields: ['movieImdbId'] }, { fields: ['movieImdbId', 'language', 'source'], unique: true }],
-        },
-      )
-    },
-  })
-
-  useSequelize({
-    injector,
-    model: SeriesMetadataLocalized,
-    sequelizeModel: SeriesMetadataLocalizedModel,
-    primaryKey: 'id',
-    options: dbOptions,
-    initModel: async (sequelize) => {
-      SeriesMetadataLocalizedModel.init(
-        {
-          id: {
-            type: DataTypes.UUIDV4,
-            primaryKey: true,
-            allowNull: false,
-            defaultValue: () => crypto.randomUUID(),
-          },
-          seriesImdbId: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          language: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          title: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          plot: {
-            type: DataTypes.TEXT,
-            allowNull: true,
-          },
-          posterUrl: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          source: {
-            type: DataTypes.STRING,
-            allowNull: false,
-          },
-          sourceId: {
-            type: DataTypes.STRING,
-            allowNull: true,
-          },
-          createdAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-          updatedAt: {
-            type: DataTypes.DATE,
-            allowNull: false,
-          },
-        },
-        {
-          sequelize,
-          indexes: [{ fields: ['seriesImdbId'] }, { fields: ['seriesImdbId', 'language', 'source'], unique: true }],
-        },
-      )
-    },
-  })
-
-  const repo = getRepository(injector)
-
-  repo.createDataSet(Movie, 'imdbId', {
-    authorizeGet: authorizedOnly,
-    authorizeAdd: withRole('admin'),
-    authorizeUpdate: withRole('admin'),
-    authorizeRemove: withRole('admin'),
-  })
-
-  repo.createDataSet(MovieFile, 'id', {
-    authorizeGet: authorizedOnly,
-    authorizeAdd: withRole('admin'),
-    authorizeUpdate: withRole('admin'),
-    authorizeRemove: withRole('admin'),
-  })
-
-  const onlyOwned = async ({
-    entity,
-    injector: i,
-  }: {
-    entity: WatchHistoryEntry
-    injector: Injector
-  }): Promise<AuthorizationResult> => {
-    const user = await getCurrentUser(i)
-    if (user.username === entity.userName) {
-      return { isAllowed: true }
-    }
-
-    if (await isAuthorized(i, 'admin')) {
-      return { isAllowed: true }
-    }
-    return {
-      isAllowed: false,
-      message: 'You are not authorized to access this resource',
-    }
-  }
-
-  repo.createDataSet(WatchHistoryEntry, 'id', {
-    authorizeGet: authorizedOnly,
-    authorizeAdd: authorizedOnly,
-    authorizeUpdate: authorizedOnly,
-    authorizeRemove: authorizedOnly,
-    authorizeGetEntity: onlyOwned,
-    addFilter: async ({ filter, injector: i }) => {
-      const user = await getCurrentUser(i)
-      return {
-        ...filter,
-        filter: {
-          ...filter.filter,
-          userName: { $eq: user.username },
-        },
-      } as typeof filter
-    },
-    authorizeUpdateEntity: onlyOwned,
-    authorizeRemoveEntity: onlyOwned,
-  })
-
-  repo.createDataSet(Series, 'imdbId', {
-    authorizeGet: authorizedOnly,
-    authorizeAdd: withRole('admin'),
-    authorizeUpdate: withRole('admin'),
-    authorizeRemove: withRole('admin'),
-  })
-
-  repo.createDataSet(OmdbMovieMetadata, 'imdbID', {
-    authorizeGet: authorizedOnly,
-    authorizeAdd: withRole('admin'),
-    authorizeUpdate: withRole('admin'),
-    authorizeRemove: withRole('admin'),
-  })
-
-  repo.createDataSet(OmdbSeriesMetadata, 'imdbID', {
-    authorizeGet: authorizedOnly,
-    authorizeAdd: withRole('admin'),
-    authorizeUpdate: withRole('admin'),
-    authorizeRemove: withRole('admin'),
-  })
-
-  repo.createDataSet(TmdbMovieMetadata, 'id', {
-    authorizeGet: authorizedOnly,
-    authorizeAdd: withRole('admin'),
-    authorizeUpdate: withRole('admin'),
-    authorizeRemove: withRole('admin'),
-  })
-
-  repo.createDataSet(TmdbSeriesMetadata, 'id', {
-    authorizeGet: authorizedOnly,
-    authorizeAdd: withRole('admin'),
-    authorizeUpdate: withRole('admin'),
-    authorizeRemove: withRole('admin'),
-  })
-
-  repo.createDataSet(MovieMetadataLocalized, 'id', {
-    authorizeGet: authorizedOnly,
-    authorizeAdd: withRole('admin'),
-    authorizeUpdate: withRole('admin'),
-    authorizeRemove: withRole('admin'),
-  })
-
-  repo.createDataSet(SeriesMetadataLocalized, 'id', {
-    authorizeGet: authorizedOnly,
-    authorizeAdd: withRole('admin'),
-    authorizeUpdate: withRole('admin'),
-    authorizeRemove: withRole('admin'),
-  })
+  setupMediaSchema(injector, logger)
+  setupMediaDataSets(injector)
 
   const omdbClientService = injector.getInstance(OmdbClientService)
   const tmdbClientService = injector.getInstance(TmdbClientService)
diff --git a/service/src/app-models/media/utils/ensure-localized-metadata-exists.spec.ts b/service/src/app-models/media/utils/ensure-localized-metadata-exists.spec.ts
new file mode 100644
index 00000000..6f12f6e4
--- /dev/null
+++ b/service/src/app-models/media/utils/ensure-localized-metadata-exists.spec.ts
@@ -0,0 +1,132 @@
+import { Injector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  ensureMovieLocalizedMetadataExists,
+  ensureSeriesLocalizedMetadataExists,
+} from './ensure-localized-metadata-exists.js'
+
+const mockFind = vi.fn()
+const mockAdd = vi.fn()
+
+vi.mock('@furystack/repository', () => ({
+  getDataSetFor: () => ({
+    find: (...args: unknown[]) => mockFind(...args) as unknown,
+    add: (...args: unknown[]) => mockAdd(...args) as unknown,
+  }),
+}))
+
+describe('ensureMovieLocalizedMetadataExists', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const movieData = {
+    movieImdbId: 'tt1234567',
+    language: 'en',
+    title: 'Test Movie',
+    plot: 'A test plot.',
+    posterUrl: 'https://example.com/poster.jpg',
+    genre: ['Action'],
+    source: 'omdb' as const,
+    sourceId: 'tt1234567',
+  }
+
+  it('should return existing record when found', async () => {
+    const existing = { ...movieData, id: 'existing-id' }
+    mockFind.mockResolvedValue([existing])
+
+    await usingAsync(new Injector(), async (injector) => {
+      const result = await ensureMovieLocalizedMetadataExists(movieData, injector)
+
+      expect(mockFind).toHaveBeenCalledWith(injector, {
+        filter: {
+          movieImdbId: { $eq: 'tt1234567' },
+          language: { $eq: 'en' },
+          source: { $eq: 'omdb' },
+        },
+        top: 1,
+      })
+      expect(mockAdd).not.toHaveBeenCalled()
+      expect(result).toBe(existing)
+    })
+  })
+
+  it('should create new record when not found', async () => {
+    const newRecord = { ...movieData, id: 'new-id' }
+    mockFind.mockResolvedValue([])
+    mockAdd.mockResolvedValue({ created: [newRecord] })
+
+    await usingAsync(new Injector(), async (injector) => {
+      const result = await ensureMovieLocalizedMetadataExists(movieData, injector)
+
+      expect(mockAdd).toHaveBeenCalledWith(
+        injector,
+        expect.objectContaining({
+          movieImdbId: 'tt1234567',
+          language: 'en',
+          source: 'omdb',
+          title: 'Test Movie',
+        }),
+      )
+      expect(result).toBe(newRecord)
+    })
+  })
+})
+
+describe('ensureSeriesLocalizedMetadataExists', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const seriesData = {
+    seriesImdbId: 'tt9876543',
+    language: 'en',
+    title: 'Test Series',
+    plot: 'A test series.',
+    posterUrl: 'https://example.com/series-poster.jpg',
+    source: 'tmdb' as const,
+    sourceId: '67890',
+  }
+
+  it('should return existing record when found', async () => {
+    const existing = { ...seriesData, id: 'existing-id' }
+    mockFind.mockResolvedValue([existing])
+
+    await usingAsync(new Injector(), async (injector) => {
+      const result = await ensureSeriesLocalizedMetadataExists(seriesData, injector)
+
+      expect(mockFind).toHaveBeenCalledWith(injector, {
+        filter: {
+          seriesImdbId: { $eq: 'tt9876543' },
+          language: { $eq: 'en' },
+          source: { $eq: 'tmdb' },
+        },
+        top: 1,
+      })
+      expect(mockAdd).not.toHaveBeenCalled()
+      expect(result).toBe(existing)
+    })
+  })
+
+  it('should create new record when not found', async () => {
+    const newRecord = { ...seriesData, id: 'new-id' }
+    mockFind.mockResolvedValue([])
+    mockAdd.mockResolvedValue({ created: [newRecord] })
+
+    await usingAsync(new Injector(), async (injector) => {
+      const result = await ensureSeriesLocalizedMetadataExists(seriesData, injector)
+
+      expect(mockAdd).toHaveBeenCalledWith(
+        injector,
+        expect.objectContaining({
+          seriesImdbId: 'tt9876543',
+          language: 'en',
+          source: 'tmdb',
+          title: 'Test Series',
+        }),
+      )
+      expect(result).toBe(newRecord)
+    })
+  })
+})
diff --git a/service/src/app-models/media/utils/ensure-tmdb-movie-exists.spec.ts b/service/src/app-models/media/utils/ensure-tmdb-movie-exists.spec.ts
new file mode 100644
index 00000000..bde2660e
--- /dev/null
+++ b/service/src/app-models/media/utils/ensure-tmdb-movie-exists.spec.ts
@@ -0,0 +1,110 @@
+import { Injector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { describe, expect, it, vi } from 'vitest'
+import type { TmdbMovieDetailsResponse } from '../metadata-services/tmdb-api-types.js'
+import { ensureTmdbMovieExists } from './ensure-tmdb-movie-exists.js'
+
+const mockGet = vi.fn()
+const mockAdd = vi.fn()
+
+vi.mock('@furystack/repository', () => ({
+  getDataSetFor: () => ({
+    get: (...args: unknown[]) => mockGet(...args) as unknown,
+    add: (...args: unknown[]) => mockAdd(...args) as unknown,
+  }),
+}))
+
+const createTmdbMovie = (overrides: Partial<TmdbMovieDetailsResponse> = {}): TmdbMovieDetailsResponse =>
+  ({
+    id: 12345,
+    imdb_id: 'tt1234567',
+    title: 'Test Movie',
+    original_title: 'Test Movie Original',
+    overview: 'A test movie.',
+    release_date: '2024-06-15',
+    runtime: 120,
+    poster_path: '/poster.jpg',
+    backdrop_path: '/backdrop.jpg',
+    genres: [{ id: 28, name: 'Action' }],
+    vote_average: 7.5,
+    vote_count: 100,
+    popularity: 50.0,
+    original_language: 'en',
+    spoken_languages: [{ iso_639_1: 'en', name: 'English' }],
+    production_countries: [{ iso_3166_1: 'US', name: 'United States' }],
+    status: 'Released',
+    tagline: 'A tagline',
+    budget: 1000000,
+    revenue: 5000000,
+    ...overrides,
+  }) as TmdbMovieDetailsResponse
+
+describe('ensureTmdbMovieExists', () => {
+  it('should return existing record when found', async () => {
+    const existing = { id: 12345, title: 'Test Movie' }
+    mockGet.mockResolvedValue(existing)
+
+    await usingAsync(new Injector(), async (injector) => {
+      const result = await ensureTmdbMovieExists(createTmdbMovie(), 'en', injector)
+
+      expect(mockGet).toHaveBeenCalledWith(injector, 12345)
+      expect(mockAdd).not.toHaveBeenCalled()
+      expect(result).toBe(existing)
+    })
+  })
+
+  it('should create new record when not found', async () => {
+    const newRecord = { id: 12345, title: 'Test Movie' }
+    mockGet.mockResolvedValue(null)
+    mockAdd.mockResolvedValue({ created: [newRecord] })
+
+    await usingAsync(new Injector(), async (injector) => {
+      const result = await ensureTmdbMovieExists(createTmdbMovie(), 'en', injector)
+
+      expect(mockGet).toHaveBeenCalledWith(injector, 12345)
+      expect(mockAdd).toHaveBeenCalledWith(
+        injector,
+        expect.objectContaining({
+          id: 12345,
+          imdbId: 'tt1234567',
+          title: 'Test Movie',
+          originalTitle: 'Test Movie Original',
+          language: 'en',
+        }),
+      )
+      expect(result).toBe(newRecord)
+    })
+  })
+
+  it('should handle null imdb_id', async () => {
+    mockGet.mockResolvedValue(null)
+    mockAdd.mockResolvedValue({ created: [{ id: 99999 }] })
+
+    await usingAsync(new Injector(), async (injector) => {
+      await ensureTmdbMovieExists(createTmdbMovie({ imdb_id: null }), 'en', injector)
+
+      expect(mockAdd).toHaveBeenCalledWith(
+        injector,
+        expect.objectContaining({
+          imdbId: undefined,
+        }),
+      )
+    })
+  })
+
+  it('should use provided language', async () => {
+    mockGet.mockResolvedValue(null)
+    mockAdd.mockResolvedValue({ created: [{ id: 12345 }] })
+
+    await usingAsync(new Injector(), async (injector) => {
+      await ensureTmdbMovieExists(createTmdbMovie(), 'fr', injector)
+
+      expect(mockAdd).toHaveBeenCalledWith(
+        injector,
+        expect.objectContaining({
+          language: 'fr',
+        }),
+      )
+    })
+  })
+})
diff --git a/service/src/app-models/media/utils/ensure-tmdb-series-exists.spec.ts b/service/src/app-models/media/utils/ensure-tmdb-series-exists.spec.ts
new file mode 100644
index 00000000..b3816208
--- /dev/null
+++ b/service/src/app-models/media/utils/ensure-tmdb-series-exists.spec.ts
@@ -0,0 +1,118 @@
+import { Injector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { TmdbTvDetailsResponse } from '../metadata-services/tmdb-api-types.js'
+import { TmdbClientService } from '../metadata-services/tmdb-client-service.js'
+import { ensureTmdbSeriesExists } from './ensure-tmdb-series-exists.js'
+
+const mockTmdbSeriesGet = vi.fn()
+const mockTmdbSeriesAdd = vi.fn()
+const mockFetchTmdbSeriesMetadata = vi.fn()
+
+vi.mock('@furystack/repository', () => ({
+  getDataSetFor: () => ({
+    get: (...args: unknown[]) => mockTmdbSeriesGet(...args) as unknown,
+    add: (...args: unknown[]) => mockTmdbSeriesAdd(...args) as unknown,
+  }),
+}))
+
+vi.mock('@furystack/logging', () => ({
+  getLogger: () => ({
+    withScope: () => ({
+      warning: vi.fn().mockResolvedValue(undefined),
+    }),
+  }),
+}))
+
+vi.mock('./ensure-series-exists.js', () => ({
+  ensureSeriesExists: vi.fn().mockResolvedValue({ imdbId: 'tt9876543' }),
+}))
+
+vi.mock('./ensure-localized-metadata-exists.js', () => ({
+  ensureSeriesLocalizedMetadataExists: vi.fn().mockResolvedValue({}),
+}))
+
+vi.mock('./map-tmdb-to-localized.js', () => ({
+  mapTmdbSeriesToLocalized: vi.fn().mockReturnValue({}),
+}))
+
+const createTmdbSeries = (): TmdbTvDetailsResponse =>
+  ({
+    id: 67890,
+    name: 'Test Series',
+    original_name: 'Test Series',
+    overview: 'A test series.',
+    first_air_date: '2024-01-15',
+    poster_path: '/poster.jpg',
+    backdrop_path: null,
+    genres: [{ id: 18, name: 'Drama' }],
+    vote_average: 8.0,
+    vote_count: 200,
+    number_of_seasons: 3,
+    number_of_episodes: 30,
+    status: 'Returning Series',
+    original_language: 'en',
+    languages: ['en'],
+    external_ids: { imdb_id: 'tt9876543', facebook_id: null, instagram_id: null, twitter_id: null, wikidata_id: null },
+  }) as TmdbTvDetailsResponse
+
+describe('ensureTmdbSeriesExists', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockTmdbSeriesGet.mockResolvedValue(null)
+    mockTmdbSeriesAdd.mockResolvedValue({ created: [{ id: 67890 }] })
+  })
+
+  it('should store provided series data without fetching', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      await ensureTmdbSeriesExists('tt9876543', createTmdbSeries(), 'en', injector)
+
+      expect(mockTmdbSeriesAdd).toHaveBeenCalled()
+      expect(mockFetchTmdbSeriesMetadata).not.toHaveBeenCalled()
+    })
+  })
+
+  it('should return early when TMDB series record already exists', async () => {
+    mockTmdbSeriesGet.mockResolvedValue({ id: 67890, name: 'Test Series' })
+
+    await usingAsync(new Injector(), async (injector) => {
+      await ensureTmdbSeriesExists('tt9876543', createTmdbSeries(), 'en', injector)
+
+      expect(mockTmdbSeriesAdd).not.toHaveBeenCalled()
+    })
+  })
+
+  it('should fetch from TMDB when no series data is provided', async () => {
+    mockFetchTmdbSeriesMetadata.mockResolvedValue({
+      status: 'success',
+      data: createTmdbSeries(),
+    })
+
+    await usingAsync(new Injector(), async (injector) => {
+      injector.setExplicitInstance(
+        { fetchTmdbSeriesMetadata: mockFetchTmdbSeriesMetadata } as unknown as TmdbClientService,
+        TmdbClientService,
+      )
+
+      await ensureTmdbSeriesExists('tt9876543', undefined, 'en', injector)
+
+      expect(mockFetchTmdbSeriesMetadata).toHaveBeenCalledWith({ imdbId: 'tt9876543' }, { file: undefined })
+      expect(mockTmdbSeriesAdd).toHaveBeenCalled()
+    })
+  })
+
+  it('should handle fetch failure gracefully', async () => {
+    mockFetchTmdbSeriesMetadata.mockResolvedValue({ status: 'not-found' })
+
+    await usingAsync(new Injector(), async (injector) => {
+      injector.setExplicitInstance(
+        { fetchTmdbSeriesMetadata: mockFetchTmdbSeriesMetadata } as unknown as TmdbClientService,
+        TmdbClientService,
+      )
+
+      await ensureTmdbSeriesExists('tt9876543', undefined, 'en', injector)
+
+      expect(mockTmdbSeriesAdd).not.toHaveBeenCalled()
+    })
+  })
+})
diff --git a/service/src/app-models/media/utils/link-movie.spec.ts b/service/src/app-models/media/utils/link-movie.spec.ts
index 8da2e703..8561e0ac 100644
--- a/service/src/app-models/media/utils/link-movie.spec.ts
+++ b/service/src/app-models/media/utils/link-movie.spec.ts
@@ -410,4 +410,182 @@ describe('linkMovie', () => {
       })
     })
   })
+
+  describe('fetching new TMDB data', () => {
+    it('should link via TMDB when OMDB is not configured', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockOmdbStoreFind.mockResolvedValue([])
+      mockFetchOmdbMovieMetadata.mockResolvedValue({ status: 'not-configured' })
+      mockFetchTmdbMovieMetadata.mockResolvedValue({
+        status: 'success',
+        data: {
+          movie: {
+            imdb_id: 'tt5551234',
+            title: 'TMDB Movie',
+            release_date: '2024-06-15',
+            runtime: 120,
+          },
+        },
+      })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        injector.setExplicitInstance(
+          {
+            fetchTmdbMovieMetadata: mockFetchTmdbMovieMetadata,
+            config: { id: 'TMDB_CONFIG', value: { apiKey: 'key', defaultLanguage: 'en-US' } },
+          } as unknown as TmdbClientService,
+          TmdbClientService,
+        )
+
+        const result = await linkMovie({
+          injector,
+          file: createFile('movies/TMDB.Movie.2024.mkv'),
+        })
+
+        expect(result.status).toBe('linked')
+        expect(mockFetchTmdbMovieMetadata).toHaveBeenCalled()
+      })
+    })
+
+    it('should link via TMDB with episode/series data', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockOmdbStoreFind.mockResolvedValue([])
+      mockFetchOmdbMovieMetadata.mockResolvedValue({ status: 'not-configured' })
+      mockFetchTmdbMovieMetadata.mockResolvedValue({
+        status: 'success',
+        data: {
+          movie: {
+            imdb_id: 'tt5551234',
+            title: 'Episode Title',
+            release_date: '2024-03-01',
+            runtime: 45,
+          },
+          episode: {
+            season_number: 2,
+            episode_number: 5,
+          },
+          series: {
+            name: 'Test Series',
+            external_ids: { imdb_id: 'tt9876543' },
+          },
+        },
+      })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        injector.setExplicitInstance(
+          {
+            fetchTmdbMovieMetadata: mockFetchTmdbMovieMetadata,
+            config: { id: 'TMDB_CONFIG', value: { apiKey: 'key', defaultLanguage: 'en-US' } },
+          } as unknown as TmdbClientService,
+          TmdbClientService,
+        )
+
+        const result = await linkMovie({
+          injector,
+          file: createFile('movies/Test.Series.S02E05.mkv'),
+        })
+
+        expect(result.status).toBe('linked')
+      })
+    })
+
+    it('should return rate-limited when TMDB is rate-limited', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockOmdbStoreFind.mockResolvedValue([])
+      mockFetchOmdbMovieMetadata.mockResolvedValue({ status: 'not-found' })
+      mockFetchTmdbMovieMetadata.mockResolvedValue({ status: 'rate-limited' })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        const result = await linkMovie({
+          injector,
+          file: createFile('movies/Rate.Limited.Movie.2024.mkv'),
+        })
+
+        expect(result.status).toBe('rate-limited')
+      })
+    })
+
+    it('should fall back to TMDB when OMDB returns not-found', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockOmdbStoreFind.mockResolvedValue([])
+      mockFetchOmdbMovieMetadata.mockResolvedValue({ status: 'not-found' })
+      mockFetchTmdbMovieMetadata.mockResolvedValue({
+        status: 'success',
+        data: {
+          movie: {
+            imdb_id: 'tt7771234',
+            title: 'Fallback Movie',
+            release_date: '2024-01-01',
+            runtime: 90,
+          },
+        },
+      })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        injector.setExplicitInstance(
+          {
+            fetchTmdbMovieMetadata: mockFetchTmdbMovieMetadata,
+            config: { id: 'TMDB_CONFIG', value: { apiKey: 'key', defaultLanguage: 'en-US' } },
+          } as unknown as TmdbClientService,
+          TmdbClientService,
+        )
+
+        const result = await linkMovie({
+          injector,
+          file: createFile('movies/Fallback.Movie.2024.mkv'),
+        })
+
+        expect(result.status).toBe('linked')
+        expect(mockFetchOmdbMovieMetadata).toHaveBeenCalled()
+        expect(mockFetchTmdbMovieMetadata).toHaveBeenCalled()
+      })
+    })
+
+    it('should fall back to TMDB when OMDB returns error', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockOmdbStoreFind.mockResolvedValue([])
+      mockFetchOmdbMovieMetadata.mockResolvedValue({ status: 'error', error: new Error('OMDB failure') })
+      mockFetchTmdbMovieMetadata.mockResolvedValue({
+        status: 'success',
+        data: {
+          movie: {
+            imdb_id: 'tt1112222',
+            title: 'Error Fallback Movie',
+            release_date: '2024-05-01',
+            runtime: 100,
+          },
+        },
+      })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        injector.setExplicitInstance(
+          {
+            fetchTmdbMovieMetadata: mockFetchTmdbMovieMetadata,
+            config: { id: 'TMDB_CONFIG', value: { apiKey: 'key', defaultLanguage: 'en-US' } },
+          } as unknown as TmdbClientService,
+          TmdbClientService,
+        )
+
+        const result = await linkMovie({
+          injector,
+          file: createFile('movies/Error.Fallback.Movie.2024.mkv'),
+        })
+
+        expect(result.status).toBe('linked')
+        expect(mockFetchTmdbMovieMetadata).toHaveBeenCalled()
+      })
+    })
+  })
 })
diff --git a/service/src/app-models/media/utils/map-omdb-to-localized.spec.ts b/service/src/app-models/media/utils/map-omdb-to-localized.spec.ts
new file mode 100644
index 00000000..e83e2831
--- /dev/null
+++ b/service/src/app-models/media/utils/map-omdb-to-localized.spec.ts
@@ -0,0 +1,75 @@
+import type { OmdbMovieMetadata, OmdbSeriesMetadata } from 'common'
+import { describe, expect, it } from 'vitest'
+import { mapOmdbMovieToLocalized, mapOmdbSeriesToLocalized } from './map-omdb-to-localized.js'
+
+describe('mapOmdbMovieToLocalized', () => {
+  const createOmdbMovie = (overrides: Partial<OmdbMovieMetadata> = {}): OmdbMovieMetadata =>
+    ({
+      imdbID: 'tt1234567',
+      Title: 'Test Movie',
+      Plot: 'A great movie about testing.',
+      Poster: 'https://example.com/poster.jpg',
+      Genre: 'Action, Drama',
+      ...overrides,
+    }) as OmdbMovieMetadata
+
+  it('should map all fields correctly', () => {
+    const result = mapOmdbMovieToLocalized(createOmdbMovie())
+
+    expect(result).toEqual({
+      movieImdbId: 'tt1234567',
+      language: 'en',
+      title: 'Test Movie',
+      plot: 'A great movie about testing.',
+      posterUrl: 'https://example.com/poster.jpg',
+      genre: ['Action', 'Drama'],
+      source: 'omdb',
+      sourceId: 'tt1234567',
+    })
+  })
+
+  it('should set posterUrl to undefined when Poster is N/A', () => {
+    const result = mapOmdbMovieToLocalized(createOmdbMovie({ Poster: 'N/A' }))
+    expect(result.posterUrl).toBeUndefined()
+  })
+
+  it('should set genre to undefined when Genre is empty', () => {
+    const result = mapOmdbMovieToLocalized(createOmdbMovie({ Genre: '' }))
+    expect(result.genre).toBeUndefined()
+  })
+
+  it('should handle single genre', () => {
+    const result = mapOmdbMovieToLocalized(createOmdbMovie({ Genre: 'Comedy' }))
+    expect(result.genre).toEqual(['Comedy'])
+  })
+})
+
+describe('mapOmdbSeriesToLocalized', () => {
+  const createOmdbSeries = (overrides: Partial<OmdbSeriesMetadata> = {}): OmdbSeriesMetadata =>
+    ({
+      imdbID: 'tt9876543',
+      Title: 'Test Series',
+      Plot: 'A great series about testing.',
+      Poster: 'https://example.com/series-poster.jpg',
+      ...overrides,
+    }) as OmdbSeriesMetadata
+
+  it('should map all fields correctly', () => {
+    const result = mapOmdbSeriesToLocalized(createOmdbSeries())
+
+    expect(result).toEqual({
+      seriesImdbId: 'tt9876543',
+      language: 'en',
+      title: 'Test Series',
+      plot: 'A great series about testing.',
+      posterUrl: 'https://example.com/series-poster.jpg',
+      source: 'omdb',
+      sourceId: 'tt9876543',
+    })
+  })
+
+  it('should set posterUrl to undefined when Poster is N/A', () => {
+    const result = mapOmdbSeriesToLocalized(createOmdbSeries({ Poster: 'N/A' }))
+    expect(result.posterUrl).toBeUndefined()
+  })
+})
diff --git a/service/src/app-models/media/utils/map-tmdb-to-localized.spec.ts b/service/src/app-models/media/utils/map-tmdb-to-localized.spec.ts
new file mode 100644
index 00000000..cb18f43d
--- /dev/null
+++ b/service/src/app-models/media/utils/map-tmdb-to-localized.spec.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest'
+import type { TmdbMovieDetailsResponse, TmdbTvDetailsResponse } from '../metadata-services/tmdb-api-types.js'
+import { mapTmdbMovieToLocalized, mapTmdbSeriesToLocalized } from './map-tmdb-to-localized.js'
+
+describe('mapTmdbMovieToLocalized', () => {
+  const createTmdbMovie = (): TmdbMovieDetailsResponse =>
+    ({
+      id: 12345,
+      imdb_id: 'tt1234567',
+      title: 'Test Movie',
+      overview: 'A test movie overview.',
+      poster_path: '/poster.jpg',
+      genres: [
+        { id: 28, name: 'Action' },
+        { id: 18, name: 'Drama' },
+      ],
+    }) as TmdbMovieDetailsResponse
+
+  it('should map all fields correctly', () => {
+    const result = mapTmdbMovieToLocalized(createTmdbMovie(), 'en')
+
+    expect(result).toEqual({
+      movieImdbId: 'tt1234567',
+      language: 'en',
+      title: 'Test Movie',
+      plot: 'A test movie overview.',
+      posterUrl: 'https://image.tmdb.org/t/p/w500/poster.jpg',
+      genre: ['Action', 'Drama'],
+      source: 'tmdb',
+      sourceId: '12345',
+    })
+  })
+
+  it('should set posterUrl to undefined when poster_path is null', () => {
+    const movie = createTmdbMovie()
+    movie.poster_path = null
+    const result = mapTmdbMovieToLocalized(movie, 'en')
+    expect(result.posterUrl).toBeUndefined()
+  })
+
+  it('should set plot to undefined when overview is empty', () => {
+    const movie = createTmdbMovie()
+    movie.overview = ''
+    const result = mapTmdbMovieToLocalized(movie, 'en')
+    expect(result.plot).toBeUndefined()
+  })
+
+  it('should use provided language', () => {
+    const result = mapTmdbMovieToLocalized(createTmdbMovie(), 'fr')
+    expect(result.language).toBe('fr')
+  })
+})
+
+describe('mapTmdbSeriesToLocalized', () => {
+  const createTmdbSeries = (): TmdbTvDetailsResponse =>
+    ({
+      id: 67890,
+      name: 'Test Series',
+      overview: 'A test series overview.',
+      poster_path: '/series-poster.jpg',
+    }) as TmdbTvDetailsResponse
+
+  it('should map all fields correctly', () => {
+    const result = mapTmdbSeriesToLocalized(createTmdbSeries(), 'tt9876543', 'en')
+
+    expect(result).toEqual({
+      seriesImdbId: 'tt9876543',
+      language: 'en',
+      title: 'Test Series',
+      plot: 'A test series overview.',
+      posterUrl: 'https://image.tmdb.org/t/p/w500/series-poster.jpg',
+      source: 'tmdb',
+      sourceId: '67890',
+    })
+  })
+
+  it('should set posterUrl to undefined when poster_path is null', () => {
+    const series = createTmdbSeries()
+    series.poster_path = null
+    const result = mapTmdbSeriesToLocalized(series, 'tt9876543', 'en')
+    expect(result.posterUrl).toBeUndefined()
+  })
+
+  it('should set plot to undefined when overview is empty', () => {
+    const series = createTmdbSeries()
+    series.overview = ''
+    const result = mapTmdbSeriesToLocalized(series, 'tt9876543', 'en')
+    expect(result.plot).toBeUndefined()
+  })
+})

From 31720ed15ff4109dd584293225976956e60156fd Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 15:39:26 +0100
Subject: [PATCH 15/30] code review fixes

---
 .cursor/rules/BACKEND_PATTERNS.mdc            | 33 +++++++++
 .cursor/rules/TYPESCRIPT_GUIDELINES.mdc       | 24 +++++++
 .cursor/rules/rules-index.mdc                 |  2 +
 common/src/utils/media/hls-constants.ts       |  1 +
 common/src/utils/media/index.ts               |  1 +
 .../movie-player-v2/movie-player-service.ts   | 49 ++++++-------
 frontend/src/services/session.spec.ts         |  4 --
 frontend/src/services/session.ts              |  4 +-
 .../media/services/transcoding-session.ts     | 13 ++--
 .../src/app-models/media/utils/link-movie.ts  | 69 +++++++++++++------
 10 files changed, 139 insertions(+), 61 deletions(-)
 create mode 100644 common/src/utils/media/hls-constants.ts

diff --git a/.cursor/rules/BACKEND_PATTERNS.mdc b/.cursor/rules/BACKEND_PATTERNS.mdc
index 775b2829..1fd0c7f2 100644
--- a/.cursor/rules/BACKEND_PATTERNS.mdc
+++ b/.cursor/rules/BACKEND_PATTERNS.mdc
@@ -91,6 +91,39 @@ service/src/app-models/[module]/
 - **Clean up**: Remove partial state on failures
 - **Log appropriately**: Use scoped loggers with meaningful context
 
+### Provider / Adapter Fallback Chains
+
+When building fallback chains where multiple providers are tried in priority order:
+
+- **Use a narrow internal result type** for provider helpers, not the top-level result type
+- Providers should only return what they can produce (e.g., an `imdbId`), not dummy values for fields they don't have
+- The orchestrator function creates the full result from the provider's narrow output
+
+```typescript
+// ✅ Good - narrow type for internal helpers
+type ProviderResult =
+  | { status: 'skip' }
+  | { status: 'rate-limited' }
+  | { status: 'linked'; imdbId: string }
+
+const tryProvider = async (...): Promise<ProviderResult> => {
+  // ...
+  return { status: 'linked', imdbId: result.imdbID }
+}
+
+// The orchestrator builds the full result
+for (const provider of priority) {
+  const result = await providers[provider](injector, params)
+  if (result.status === 'linked') {
+    linkedImdbId = result.imdbId
+    break
+  }
+}
+
+// ❌ Bad - reusing the top-level type forces dummy values
+return { status: 'linked', movieFile: undefined as unknown as MovieFile, movie }
+```
+
 ### Service Layer
 
 ```typescript
diff --git a/.cursor/rules/TYPESCRIPT_GUIDELINES.mdc b/.cursor/rules/TYPESCRIPT_GUIDELINES.mdc
index 86801dd6..f3e97c09 100644
--- a/.cursor/rules/TYPESCRIPT_GUIDELINES.mdc
+++ b/.cursor/rules/TYPESCRIPT_GUIDELINES.mdc
@@ -551,6 +551,30 @@ const value = 'hello' as string;
 const value = unknownValue as User; // Prefer type guard
 ```
 
+### Double-Cast Anti-Pattern (`as unknown as T`)
+
+**NEVER** use `undefined as unknown as T` or `null as unknown as T` to satisfy a type contract.
+This hides a design flaw — if a function doesn't have the value, the return type should reflect that.
+
+```typescript
+// ❌ FORBIDDEN - double-cast to satisfy type
+return { status: 'linked', movieFile: undefined as unknown as MovieFile, movie };
+
+// ✅ Good - use a narrower return type that doesn't require the value
+type ProviderResult =
+  | { status: 'skip' }
+  | { status: 'rate-limited' }
+  | { status: 'linked'; imdbId: string };
+
+return { status: 'linked', imdbId: added.imdbID };
+
+// ✅ Good - if the caller needs different shapes, use discriminated unions
+type InternalResult = { status: 'linked'; imdbId: string };
+type FullResult = { status: 'linked'; movieFile: MovieFile; movie: Movie };
+```
+
+If you encounter `as unknown as T`, refactor the types so the cast is unnecessary.
+
 ### Non-Null Assertion Operator
 
 - Avoid using `!` operator when possible
diff --git a/.cursor/rules/rules-index.mdc b/.cursor/rules/rules-index.mdc
index 6874da3d..23e8681d 100644
--- a/.cursor/rules/rules-index.mdc
+++ b/.cursor/rules/rules-index.mdc
@@ -12,3 +12,5 @@ This file contains a list of helpful information and context that the agent can
 - [REST action Validate() wrappers and explicit param checking before system calls](./REST_ACTION_VALIDATION.mdc)
 - [Singleton concurrency guards, getOrCreate race prevention, fire-and-forget init, dispose-before-reinit, and safe Map iteration](./SINGLETON_CONCURRENCY.md)
 - [MFE runtime type boundaries, duplicate type contracts, and cross-package type sync](./MFE_TYPE_CONTRACTS.md)
+- [Double-cast anti-pattern (`as unknown as T`) and non-null assertion avoidance](./TYPESCRIPT_GUIDELINES.mdc)
+- [Provider/adapter fallback chain patterns with narrow internal result types](./BACKEND_PATTERNS.mdc)
diff --git a/common/src/utils/media/hls-constants.ts b/common/src/utils/media/hls-constants.ts
new file mode 100644
index 00000000..4e0d47e7
--- /dev/null
+++ b/common/src/utils/media/hls-constants.ts
@@ -0,0 +1 @@
+export const HLS_SEGMENT_DURATION = 6
diff --git a/common/src/utils/media/index.ts b/common/src/utils/media/index.ts
index cb4ad0f8..fbe6f97e 100644
--- a/common/src/utils/media/index.ts
+++ b/common/src/utils/media/index.ts
@@ -1,3 +1,4 @@
+export * from './hls-constants.js'
 export * from './is-movie-file.js'
 export * from './is-sample-file.js'
 export * from './get-fallback-metadata.js'
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index 47526e7d..23675d79 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -2,6 +2,7 @@ import type { ScopedLogger } from '@furystack/logging'
 import { ObservableValue } from '@furystack/utils'
 import {
   encode,
+  HLS_SEGMENT_DURATION,
   type AudioTrackInfo,
   type FfprobeData,
   type PiRatFile,
@@ -60,8 +61,6 @@ const buildCodecSupportMap = () => {
 
 export type ResolutionValue = '4k' | '1080p' | '720p' | '480p' | '360p'
 
-const SEGMENT_DURATION = 6
-
 export class MoviePlayerService implements AsyncDisposable {
   constructor(
     private readonly file: PiRatFile,
@@ -71,7 +70,7 @@ export class MoviePlayerService implements AsyncDisposable {
     private readonly logger: ScopedLogger,
   ) {
     this.progress = new ObservableValue(this.currentProgress)
-    this.hlsStartTime = Math.floor(this.currentProgress / SEGMENT_DURATION) * SEGMENT_DURATION
+    this.hlsStartTime = Math.floor(this.currentProgress / HLS_SEGMENT_DURATION) * HLS_SEGMENT_DURATION
 
     void this.initialize()
   }
@@ -79,6 +78,7 @@ export class MoviePlayerService implements AsyncDisposable {
   private hls: Hls | null = null
   private originalPlaybackMode: PlaybackMode = 'transcode'
   private isSwitching = false
+  private seekGeneration = 0
   private hlsStartTime = 0
   public videoElement: HTMLVideoElement | null = null
   public audioTrackId = new ObservableValue(0)
@@ -302,20 +302,14 @@ export class MoviePlayerService implements AsyncDisposable {
     this.audioTrackId.setValue(trackIndex)
     this.currentProgress = previousProgress
     this.progress.setValue(previousProgress)
-    this.hlsStartTime = Math.floor(previousProgress / SEGMENT_DURATION) * SEGMENT_DURATION
+    this.hlsStartTime = Math.floor(previousProgress / HLS_SEGMENT_DURATION) * HLS_SEGMENT_DURATION
 
     await this.fetchPlaybackInfo()
 
     const info = this.playbackInfo.getValue()
     if (this.videoElement && info) {
       this.startPlayback(this.videoElement, info)
-      const video = this.videoElement
-      const onCanPlay = () => {
-        video.removeEventListener('canplay', onCanPlay)
-        this.isSwitching = false
-        void video.play().catch(() => {})
-      }
-      video.addEventListener('canplay', onCanPlay)
+      this.waitForCanPlay(this.videoElement)
     } else {
       this.isSwitching = false
     }
@@ -344,20 +338,14 @@ export class MoviePlayerService implements AsyncDisposable {
     this.resolution.setValue(value)
     this.currentProgress = previousProgress
     this.progress.setValue(previousProgress)
-    this.hlsStartTime = Math.floor(previousProgress / SEGMENT_DURATION) * SEGMENT_DURATION
+    this.hlsStartTime = Math.floor(previousProgress / HLS_SEGMENT_DURATION) * HLS_SEGMENT_DURATION
     this.playbackMode.setValue(targetMode)
 
     if (this.videoElement) {
       const info = this.playbackInfo.getValue()
       if (info) {
         this.startPlayback(this.videoElement, info)
-        const video = this.videoElement
-        const onCanPlay = () => {
-          video.removeEventListener('canplay', onCanPlay)
-          this.isSwitching = false
-          void video.play().catch(() => {})
-        }
-        video.addEventListener('canplay', onCanPlay)
+        this.waitForCanPlay(this.videoElement)
       } else {
         this.isSwitching = false
       }
@@ -380,7 +368,7 @@ export class MoviePlayerService implements AsyncDisposable {
 
     if (this.isTimeBuffered(video, targetSeconds)) return
 
-    const quantizedStart = Math.floor(targetSeconds / SEGMENT_DURATION) * SEGMENT_DURATION
+    const quantizedStart = Math.floor(targetSeconds / HLS_SEGMENT_DURATION) * HLS_SEGMENT_DURATION
     if (quantizedStart === this.hlsStartTime) return
 
     void this.restartHlsAtTime(targetSeconds, quantizedStart)
@@ -398,8 +386,12 @@ export class MoviePlayerService implements AsyncDisposable {
 
   private async restartHlsAtTime(targetSeconds: number, quantizedStart: number) {
     this.isSwitching = true
+    const generation = ++this.seekGeneration
 
     await this.teardownHlsSession()
+
+    if (generation !== this.seekGeneration) return
+
     if (this.hls) {
       this.hls.destroy()
       this.hls = null
@@ -411,18 +403,21 @@ export class MoviePlayerService implements AsyncDisposable {
 
     if (this.videoElement) {
       void this.startHlsPlayback(this.videoElement)
-      const video = this.videoElement
-      const onCanPlay = () => {
-        video.removeEventListener('canplay', onCanPlay)
-        this.isSwitching = false
-        void video.play().catch(() => {})
-      }
-      video.addEventListener('canplay', onCanPlay)
+      this.waitForCanPlay(this.videoElement)
     } else {
       this.isSwitching = false
     }
   }
 
+  private waitForCanPlay(video: HTMLVideoElement) {
+    const onCanPlay = () => {
+      video.removeEventListener('canplay', onCanPlay)
+      this.isSwitching = false
+      void video.play().catch(() => {})
+    }
+    video.addEventListener('canplay', onCanPlay)
+  }
+
   public getIsSwitching(): boolean {
     return this.isSwitching
   }
diff --git a/frontend/src/services/session.spec.ts b/frontend/src/services/session.spec.ts
index f15f4c07..7829e51f 100644
--- a/frontend/src/services/session.spec.ts
+++ b/frontend/src/services/session.spec.ts
@@ -215,7 +215,6 @@ describe('SessionService', () => {
 
     it('should still clear state when logout API call fails', async () => {
       const mockCall = vi.fn().mockRejectedValue(new Error('Network error'))
-      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
 
       const { injector, mockNotyService } = createTestInjector(mockCall)
 
@@ -230,10 +229,7 @@ describe('SessionService', () => {
         expect(service.currentUser.getValue()).toBeNull()
         expect(service.state.getValue()).toBe('unauthenticated')
         expect(mockNotyService.emit).toHaveBeenCalledWith('onNotyAdded', expect.objectContaining({ type: 'info' }))
-        expect(warnSpy).toHaveBeenCalledWith('Logout API call failed:', expect.any(Error))
       })
-
-      warnSpy.mockRestore()
     })
   })
 
diff --git a/frontend/src/services/session.ts b/frontend/src/services/session.ts
index 818cf06b..ed30b4e7 100644
--- a/frontend/src/services/session.ts
+++ b/frontend/src/services/session.ts
@@ -114,8 +114,8 @@ export class SessionService implements IdentityContext, Disposable {
     return await usingAsync(this.operation(), async () => {
       try {
         await this.api.call({ method: 'POST', action: '/logout' })
-      } catch (error) {
-        console.warn('Logout API call failed:', error)
+      } catch {
+        // Logout failure is non-critical — session is cleared client-side regardless
       }
       if (this.isDisposed) return
       this.currentUser.setValue(null)
diff --git a/service/src/app-models/media/services/transcoding-session.ts b/service/src/app-models/media/services/transcoding-session.ts
index 741cba27..16462edd 100644
--- a/service/src/app-models/media/services/transcoding-session.ts
+++ b/service/src/app-models/media/services/transcoding-session.ts
@@ -3,7 +3,7 @@ import { Injectable, Injected, type Injector } from '@furystack/inject'
 import { getLogger, type ScopedLogger } from '@furystack/logging'
 import { getDataSetFor } from '@furystack/repository'
 import type { PlaybackMode } from 'common'
-import { Config, Drive, type MoviesConfig } from 'common'
+import { Config, Drive, HLS_SEGMENT_DURATION, type MoviesConfig } from 'common'
 import { spawn, type ChildProcess } from 'child_process'
 import { createHash } from 'crypto'
 import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'fs'
@@ -34,7 +34,6 @@ type TranscodingSessionEntry = {
 }
 
 const SESSION_IDLE_TIMEOUT_MS = 5 * 60 * 1000
-const SEGMENT_DURATION = 6
 const WAIT_POLL_INTERVAL_MS = 100
 const WAIT_TIMEOUT_MS = 60_000
 const DEFAULT_MAX_CACHE_SIZE_MB = 5000
@@ -326,14 +325,14 @@ export class TranscodingSessionService {
       return `${playlist.trimEnd()}\n#EXT-X-ENDLIST\n`
     }
 
-    const fullSegmentCount = Math.floor(remainingDuration / SEGMENT_DURATION)
-    const lastSegmentDuration = remainingDuration - fullSegmentCount * SEGMENT_DURATION
+    const fullSegmentCount = Math.floor(remainingDuration / HLS_SEGMENT_DURATION)
+    const lastSegmentDuration = remainingDuration - fullSegmentCount * HLS_SEGMENT_DURATION
 
     const padLines: string[] = []
     let nextIndex = maxSegmentIndex + 1
 
     for (let i = 0; i < fullSegmentCount; i++) {
-      padLines.push(`#EXTINF:${SEGMENT_DURATION.toFixed(6)},`)
+      padLines.push(`#EXTINF:${HLS_SEGMENT_DURATION.toFixed(6)},`)
       padLines.push(`segment${nextIndex}.m4s`)
       nextIndex++
     }
@@ -442,7 +441,7 @@ export class TranscodingSessionService {
       args.push('-c:v', videoCodec)
 
       // Force keyframes at segment boundaries (offset by startTime when -copyts preserves original PTS)
-      args.push('-force_key_frames', `expr:gte(t,n_forced*${SEGMENT_DURATION}+${startTime})`)
+      args.push('-force_key_frames', `expr:gte(t,n_forced*${HLS_SEGMENT_DURATION}+${startTime})`)
       args.push('-sc_threshold:v', '0')
 
       const isSoftwareEncoder = videoCodec === 'libx264' || videoCodec === 'libx265'
@@ -466,7 +465,7 @@ export class TranscodingSessionService {
 
     // HLS muxer output (the core change from per-segment to continuous)
     args.push('-f', 'hls')
-    args.push('-hls_time', String(SEGMENT_DURATION))
+    args.push('-hls_time', String(HLS_SEGMENT_DURATION))
     args.push('-hls_segment_type', 'fmp4')
     args.push('-hls_fmp4_init_filename', 'init.mp4')
     args.push('-hls_segment_filename', join(sessionDir, 'segment%d.m4s'))
diff --git a/service/src/app-models/media/utils/link-movie.ts b/service/src/app-models/media/utils/link-movie.ts
index c064afdb..1bda6bd4 100644
--- a/service/src/app-models/media/utils/link-movie.ts
+++ b/service/src/app-models/media/utils/link-movie.ts
@@ -29,15 +29,7 @@ import { ensureMovieLocalizedMetadataExists } from './ensure-localized-metadata-
 import { mapOmdbMovieToLocalized } from './map-omdb-to-localized.js'
 import { mapTmdbMovieToLocalized } from './map-tmdb-to-localized.js'
 
-type LinkResult =
-  | { status: 'already-linked' }
-  | { status: 'linked'; movieFile: MovieFile; movie: unknown }
-  | { status: 'failed' }
-  | { status: 'not-movie-file' }
-  | { status: 'rate-limited' }
-  | { status: 'metadata-not-found' }
-  | { status: 'provider-not-configured' }
-  | { status: 'provider-error'; error?: unknown }
+type ProviderResult = { status: 'skip' } | { status: 'rate-limited' } | { status: 'linked'; imdbId: string }
 
 const getProviderPriority = async (injector: Injector): Promise<Array<'omdb' | 'tmdb'>> => {
   try {
@@ -56,7 +48,7 @@ const tryOmdbProvider = async (
   injector: Injector,
   { title, year, season, episode }: { title: string; year?: number; season?: number; episode?: number },
   context?: { file?: PiRatFile },
-): Promise<LinkResult | { status: 'skip' }> => {
+): Promise<ProviderResult> => {
   const omdbClientService = injector.getInstance(OmdbClientService)
   const result = await omdbClientService.fetchOmdbMovieMetadata({ title, year, season, episode }, context)
 
@@ -66,7 +58,7 @@ const tryOmdbProvider = async (
   if (result.status === 'error') return { status: 'skip' }
 
   const added = await ensureOmdbMovieExists(result.data, injector)
-  const movie = await ensureMovieExists(
+  await ensureMovieExists(
     {
       imdbId: added.imdbID,
       year: parseInt(added.Year, 10),
@@ -81,14 +73,14 @@ const tryOmdbProvider = async (
   await ensureMovieLocalizedMetadataExists(mapOmdbMovieToLocalized(added), injector)
   await ensureOmdbSeriesExists(added, injector, context)
 
-  return { status: 'linked', movieFile: undefined as unknown as MovieFile, movie }
+  return { status: 'linked', imdbId: added.imdbID }
 }
 
 const tryTmdbProvider = async (
   injector: Injector,
   { title, year, season, episode }: { title: string; year?: number; season?: number; episode?: number },
   context?: { file?: PiRatFile },
-): Promise<LinkResult | { status: 'skip' }> => {
+): Promise<ProviderResult> => {
   const tmdbClientService = injector.getInstance(TmdbClientService)
   const result = await tmdbClientService.fetchTmdbMovieMetadata({ title, year, season, episode }, context)
 
@@ -98,12 +90,14 @@ const tryTmdbProvider = async (
   if (result.status === 'error') return { status: 'skip' }
 
   const { movie: tmdbMovie, series: tmdbSeries } = result.data
-  const imdbId = tmdbMovie.imdb_id!
+  const imdbId = tmdbMovie.imdb_id
+  if (!imdbId) return { status: 'skip' }
+
   const language = tmdbClientService.config?.value.defaultLanguage?.slice(0, 2) ?? 'en'
 
   await ensureTmdbMovieExists(tmdbMovie, language, injector)
 
-  const movie = await ensureMovieExists(
+  await ensureMovieExists(
     {
       imdbId,
       year: tmdbMovie.release_date ? parseInt(tmdbMovie.release_date.slice(0, 4), 10) : undefined,
@@ -124,7 +118,32 @@ const tryTmdbProvider = async (
     }
   }
 
-  return { status: 'linked', movieFile: undefined as unknown as MovieFile, movie }
+  return { status: 'linked', imdbId }
+}
+
+/**
+ * Tries each configured provider to populate localized metadata for a movie
+ * already linked via a direct IMDB ID (ffprobe tags or .nfo file).
+ */
+const enrichMetadataFromProviders = async (
+  injector: Injector,
+  params: { title: string; year?: number; season?: number; episode?: number },
+  context?: { file?: PiRatFile },
+) => {
+  const priority = await getProviderPriority(injector)
+  const providers: Record<string, typeof tryOmdbProvider> = {
+    omdb: tryOmdbProvider,
+    tmdb: tryTmdbProvider,
+  }
+
+  for (const provider of priority) {
+    const tryProvider = providers[provider]
+    if (!tryProvider) continue
+
+    const result = await tryProvider(injector, params, context)
+    if (result.status === 'linked') return
+    if (result.status === 'rate-limited') return
+  }
 }
 
 export const linkMovie = async (options: { injector: Injector; file: PiRatFile }) => {
@@ -218,6 +237,14 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
       data: { file, movieFile: newMovieFile, movie, source: tagImdbId ? 'ffprobe-tags' : 'nfo-file' },
     })
 
+    // Fire-and-forget: enrich localized metadata via providers
+    void enrichMetadataFromProviders(injector, { title, year, season, episode }, { file }).catch((error) => {
+      void logger.warning({
+        message: `Failed to enrich metadata for '${fileName}' after direct-ID link`,
+        data: { error },
+      })
+    })
+
     return { status: 'linked', movieFile: newMovieFile, movie } as const
   }
 
@@ -281,7 +308,7 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
     tmdb: tryTmdbProvider,
   }
 
-  let imdbId: string | undefined
+  let linkedImdbId: string | undefined
   for (const provider of priority) {
     const tryProvider = providers[provider]
     if (!tryProvider) continue
@@ -297,12 +324,12 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
       return { status: 'rate-limited' } as const
     }
     if (result.status === 'linked') {
-      imdbId = (result.movie as { imdbId?: string })?.imdbId
+      linkedImdbId = result.imdbId
       break
     }
   }
 
-  if (!imdbId) {
+  if (!linkedImdbId) {
     await logger.debug({
       message: `No metadata found for '${fileName}' from any provider.`,
       data: { file, title, year },
@@ -315,7 +342,7 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
   } = await movieFileDataSet.add(injector, {
     driveLetter,
     path,
-    imdbId,
+    imdbId: linkedImdbId,
     ffprobe: ffprobeResult,
   })
 
@@ -324,5 +351,5 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
     data: { file, movieFile: newMovieFile },
   })
 
-  return { status: 'linked', movieFile: newMovieFile, movie: { imdbId } } as const
+  return { status: 'linked', movieFile: newMovieFile, movie: { imdbId: linkedImdbId } } as const
 }

From d4e0e3471d47fdc36f61f667b4a736e7f97c81ec Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 16:07:57 +0100
Subject: [PATCH 16/30] code review fixes, version bumps, changelogs

---
 .yarn/changelogs/common.90cc3afc.md           |  34 ++++++
 .yarn/changelogs/frontend.90cc3afc.md         |  44 +++++++
 .yarn/changelogs/pi-rat.90cc3afc.md           |  11 ++
 .yarn/changelogs/service.90cc3afc.md          |  68 +++++++++++
 .yarn/versions/90cc3afc.yml                   |   5 +
 .../movie-player-v2/movie-player-service.ts   |  32 ++---
 .../movie-player-v2-component.tsx             |   2 +-
 .../hls-session-teardown-action.spec.ts       |   4 +-
 .../media/announce-movie-file-added.spec.ts   | 112 ++++++++++++++++++
 .../media/utils/ensure-series-exists.spec.ts  |  91 ++++++++++++++
 .../src/app-models/media/utils/link-movie.ts  |  57 +++++----
 .../media/utils/map-tmdb-to-localized.spec.ts |  13 +-
 .../media/utils/map-tmdb-to-localized.ts      |   3 +-
 13 files changed, 425 insertions(+), 51 deletions(-)
 create mode 100644 .yarn/changelogs/common.90cc3afc.md
 create mode 100644 .yarn/changelogs/frontend.90cc3afc.md
 create mode 100644 .yarn/changelogs/pi-rat.90cc3afc.md
 create mode 100644 .yarn/changelogs/service.90cc3afc.md
 create mode 100644 .yarn/versions/90cc3afc.yml
 create mode 100644 service/src/app-models/media/announce-movie-file-added.spec.ts
 create mode 100644 service/src/app-models/media/utils/ensure-series-exists.spec.ts

diff --git a/.yarn/changelogs/common.90cc3afc.md b/.yarn/changelogs/common.90cc3afc.md
new file mode 100644
index 00000000..a82ab9cb
--- /dev/null
+++ b/.yarn/changelogs/common.90cc3afc.md
@@ -0,0 +1,34 @@
+<!-- version-type: patch -->
+
+# common
+
+## ✨ Features
+
+### TMDB Integration Models
+
+- Added `TmdbMovieMetadata` model with fields for TMDB movie details including genres, vote data, production info, and multi-language support
+- Added `TmdbSeriesMetadata` model with fields for TMDB series details including season/episode counts and language info
+- Added `TmdbConfig` configuration type for TMDB API key, default language, and additional language preferences
+- Added `MetadataProviderConfig` type to define an ordered priority list of metadata providers (`omdb` | `tmdb`)
+
+### Localized Metadata Models
+
+- Added `MovieMetadataLocalized` model for per-language movie metadata (title, plot, poster, genre) with source tracking (`omdb` | `tmdb`)
+- Added `SeriesMetadataLocalized` model for per-language series metadata with source tracking
+
+### Media API Endpoints
+
+- Added REST endpoints for `TmdbMovieMetadata`, `TmdbSeriesMetadata`, `MovieMetadataLocalized`, and `SeriesMetadataLocalized` entity browsing
+- Added `audioTrack` and `startTime` query parameters to HLS master, stream, segment, init, and teardown endpoints to support mid-stream seeking and audio track selection
+
+### Other
+
+- Added `HLS_SEGMENT_DURATION` constant (6 seconds) shared between frontend and service
+- Extended `isMovieFile()` to recognize `.mp4` and `.mov` extensions
+- Added `tmdb` field to `ServiceStatusResponse` for TMDB API availability checks
+
+## ♻️ Refactoring
+
+- Moved language-dependent fields (`title`, `plot`, `genre`, `thumbnailImageUrl`) from `Movie` and `Series` models into the new localized metadata models
+- Renamed `omdb-not-configured` / `omdb-error` link statuses to `provider-not-configured` / `provider-error` to reflect multi-provider support
+- Renamed `omdbNotConfigured` / `omdbError` scan progress fields to `providerNotConfigured` / `providerError`
diff --git a/.yarn/changelogs/frontend.90cc3afc.md b/.yarn/changelogs/frontend.90cc3afc.md
new file mode 100644
index 00000000..18645534
--- /dev/null
+++ b/.yarn/changelogs/frontend.90cc3afc.md
@@ -0,0 +1,44 @@
+<!-- version-type: patch -->
+
+# frontend
+
+## ✨ Features
+
+### TMDB Settings Page
+
+Added admin settings page at `/settings/tmdb` for configuring TMDB API credentials, default language, and additional languages for metadata fetching.
+
+### Localized Metadata Service
+
+Added `LocalizedMetadataService` with caches for fetching `MovieMetadataLocalized` and `SeriesMetadataLocalized` by IMDB ID and language. Movie and series overview pages now display localized titles, plots, posters, and genres from this service.
+
+### Movie Player Seeking and Quality Switching
+
+- Added server-side seek support via `startTime` parameter — the player requests a new HLS session starting at the desired position when seeking outside the buffered range
+- Added `switchResolution()` for changing playback quality mid-stream with optional full session reload
+- Added `isSwitching` guard to avoid progress updates during resolution/audio/seek transitions
+
+### Entity Browser Pages
+
+- Added entity browser pages for `TmdbMovieMetadata` and `TmdbSeriesMetadata`
+
+## 🐛 Bug Fixes
+
+- Fixed movie duration not displaying correctly in the player controls by passing `defaultDuration` to `media-controller`
+- Fixed legacy navigation issues by relocating route utilities to `utils/` directory
+
+## ♻️ Refactoring
+
+- Extracted file context menu items into a pure `getContextMenuItems()` function, replacing the Shade-based `FileContextMenu` component
+- Extracted file drag-and-drop upload logic into `handleFileDrop()` utility
+- Extracted `SessionUserUnavailableError`, `getUser()`, and `hasRole()` into `utils/session-helpers.ts` for reusable session access
+- Relocated `environment-options.ts`, `navigate-to-route.ts`, `trigger-download.ts`, and `theme-switch-cheat.tsx` into `utils/` directory
+- Simplified `SessionService.currentUser` to store the full `User` object instead of a partial pick
+
+## 🧪 Tests
+
+- Added tests for `LocalizedMetadataService` cache behavior
+- Added tests for `TmdbSettings` page form validation and config persistence
+- Added tests for `session-helpers` utilities
+- Updated `MoviePlayerService` tests for seeking, resolution switching, and start-time support
+- Updated `MoviePlayerV2Component` tests for the new seeking and resolution switching behavior
diff --git a/.yarn/changelogs/pi-rat.90cc3afc.md b/.yarn/changelogs/pi-rat.90cc3afc.md
new file mode 100644
index 00000000..f7cac6d8
--- /dev/null
+++ b/.yarn/changelogs/pi-rat.90cc3afc.md
@@ -0,0 +1,11 @@
+<!-- version-type: patch -->
+
+# pi-rat
+
+## 📦 Build
+
+- Updated ESLint configuration with refined ignore globs for generated schemas and build artifacts
+
+## ⬆️ Dependencies
+
+- Updated FuryStack framework dependencies
diff --git a/.yarn/changelogs/service.90cc3afc.md b/.yarn/changelogs/service.90cc3afc.md
new file mode 100644
index 00000000..208fda2a
--- /dev/null
+++ b/.yarn/changelogs/service.90cc3afc.md
@@ -0,0 +1,68 @@
+<!-- version-type: patch -->
+
+# service
+
+## ✨ Features
+
+### TMDB Client Service
+
+Added `TmdbClientService` with support for searching and fetching movie/series details from the TMDB API, including multi-language metadata retrieval based on the configured `TmdbConfig` languages.
+
+### Configurable Metadata Provider Chain
+
+The movie-linking pipeline now supports a configurable provider priority (`omdb`, `tmdb`) via `MetadataProviderConfig`. Providers are tried in order; the first one to return a result wins.
+
+### IMDB ID Extraction from Files
+
+- Added `extractImdbIdFromNfoFiles()` — scans `.nfo` files in the parent directory for IMDB IDs (e.g. `tt1234567`), enabling direct metadata lookup without a search API call
+- Added `extractImdbIdFromFfprobeTags()` — extracts IMDB IDs from ffprobe format tags (`imdb_id`, `imdb-id`, `imdb`, etc.)
+
+### Localized Metadata Storage
+
+- Added `ensureMovieLocalizedMetadataExists()` and `ensureSeriesLocalizedMetadataExists()` for upserting per-language metadata records
+- Added `mapOmdbMovieToLocalized()` / `mapOmdbSeriesToLocalized()` to convert OMDB metadata into localized format (English only)
+- Added `mapTmdbMovieToLocalized()` / `mapTmdbSeriesToLocalized()` to convert TMDB responses into localized format for any language
+
+### HLS Start-Time Seeking
+
+- Transcoding sessions now accept a `startTime` parameter, using FFmpeg input seeking (`-ss` before `-i`) to start transcoding from an arbitrary position
+- Added `padPlaylistToFullDuration()` to pad HLS playlists for correct total duration when segments don't cover the full file
+
+### Other
+
+- Added `removeAllSessionsForFile()` to tear down every active transcoding session for a given file path
+- Added 4K (3840x2160) resolution variant to the HLS manifest generator
+- Added `TmdbMovieMetadata`, `TmdbSeriesMetadata`, `MovieMetadataLocalized`, and `SeriesMetadataLocalized` data sets and API endpoints
+- Added TMDB status check to the service status endpoint
+
+## 🐛 Bug Fixes
+
+- Fixed HLS session teardown to remove all sessions for a file instead of requiring exact mode/resolution/audioTrack match
+
+## ♻️ Refactoring
+
+### `setup-media.ts` Split
+
+Extracted the monolithic `setup-media.ts` into focused modules:
+
+- `media-sequelize-models.ts` — Sequelize model definitions for all media entities
+- `media-data-sets.ts` — Repository data set registration
+- `media-schema-setup.ts` — Database schema setup and sync
+- `announce-movie-file-added.ts` — WebSocket notification when movie files are added
+
+### Link-Movie Provider Architecture
+
+Refactored `link-movie.ts` from a single OMDB-only flow into a provider-based architecture with `tryOmdbProvider()` and `tryTmdbProvider()` functions, plus an `enrichMetadataFromProviders()` step that fetches additional localized metadata after initial linking.
+
+## 🧪 Tests
+
+- Added tests for `TmdbClientService` covering search, detail fetching, multi-language support, and error/rate-limit handling
+- Added tests for `extractImdbIdFromNfoFiles()` and `extractImdbIdFromFfprobeTags()`
+- Added tests for `ensureMovieLocalizedMetadataExists()` and `ensureSeriesLocalizedMetadataExists()`
+- Added tests for `mapOmdbMovieToLocalized()` and `mapTmdbMovieToLocalized()` / `mapTmdbSeriesToLocalized()`
+- Added tests for `ensureTmdbMovieExists()` and `ensureTmdbSeriesExists()`
+- Added tests for `HlsManifestGenerator` including 4K variant and `startTime` / `audioTrack` pass-through
+- Added tests for `HlsStreamAction` start-time parameter handling
+- Updated `TranscodingSession` tests for start-time seeking and playlist padding
+- Updated `link-movie` tests for provider chain, NFO extraction, and TMDB fallback
+- Updated `HlsSessionTeardownAction` tests for `removeAllSessionsForFile()` behavior
diff --git a/.yarn/versions/90cc3afc.yml b/.yarn/versions/90cc3afc.yml
new file mode 100644
index 00000000..ac090136
--- /dev/null
+++ b/.yarn/versions/90cc3afc.yml
@@ -0,0 +1,5 @@
+releases:
+  common: patch
+  frontend: patch
+  pi-rat: patch
+  service: patch
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index 23675d79..c4bf802f 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -77,7 +77,7 @@ export class MoviePlayerService implements AsyncDisposable {
 
   private hls: Hls | null = null
   private originalPlaybackMode: PlaybackMode = 'transcode'
-  private isSwitching = false
+  public isSwitching = new ObservableValue(false)
   private seekGeneration = 0
   private hlsStartTime = 0
   public videoElement: HTMLVideoElement | null = null
@@ -95,6 +95,7 @@ export class MoviePlayerService implements AsyncDisposable {
     this.playbackInfo[Symbol.dispose]()
     this.playbackMode[Symbol.dispose]()
     this.audioTrackId[Symbol.dispose]()
+    this.isSwitching[Symbol.dispose]()
     if (this.hls) {
       this.hls.destroy()
       this.hls = null
@@ -113,12 +114,7 @@ export class MoviePlayerService implements AsyncDisposable {
           letter: this.file.driveLetter,
           path: this.file.path,
         },
-        query: {
-          mode,
-          audioTrack: this.audioTrackId.getValue(),
-          resolution: this.resolution.getValue(),
-          startTime: this.hlsStartTime || undefined,
-        },
+        query: {},
       })
     } catch (error) {
       void this.logger.warning({ message: 'Failed to tear down HLS session', data: { error } })
@@ -296,7 +292,7 @@ export class MoviePlayerService implements AsyncDisposable {
   public async switchAudioTrack(trackIndex: number) {
     const previousProgress = this.videoElement?.currentTime ?? this.progress.getValue()
 
-    this.isSwitching = true
+    this.isSwitching.setValue(true)
     await this.teardownHlsSession()
 
     this.audioTrackId.setValue(trackIndex)
@@ -311,7 +307,7 @@ export class MoviePlayerService implements AsyncDisposable {
       this.startPlayback(this.videoElement, info)
       this.waitForCanPlay(this.videoElement)
     } else {
-      this.isSwitching = false
+      this.isSwitching.setValue(false)
     }
   }
 
@@ -334,7 +330,7 @@ export class MoviePlayerService implements AsyncDisposable {
     const previousProgress = this.videoElement?.currentTime ?? this.progress.getValue()
     await this.teardownHlsSession()
 
-    this.isSwitching = true
+    this.isSwitching.setValue(true)
     this.resolution.setValue(value)
     this.currentProgress = previousProgress
     this.progress.setValue(previousProgress)
@@ -347,10 +343,10 @@ export class MoviePlayerService implements AsyncDisposable {
         this.startPlayback(this.videoElement, info)
         this.waitForCanPlay(this.videoElement)
       } else {
-        this.isSwitching = false
+        this.isSwitching.setValue(false)
       }
     } else {
-      this.isSwitching = false
+      this.isSwitching.setValue(false)
     }
   }
 
@@ -361,7 +357,7 @@ export class MoviePlayerService implements AsyncDisposable {
    */
   public seekToTime(targetSeconds: number) {
     const mode = this.playbackMode.getValue()
-    if (mode === 'direct-play' || this.isSwitching) return
+    if (mode === 'direct-play' || this.isSwitching.getValue()) return
 
     const video = this.videoElement
     if (!video) return
@@ -385,7 +381,7 @@ export class MoviePlayerService implements AsyncDisposable {
   }
 
   private async restartHlsAtTime(targetSeconds: number, quantizedStart: number) {
-    this.isSwitching = true
+    this.isSwitching.setValue(true)
     const generation = ++this.seekGeneration
 
     await this.teardownHlsSession()
@@ -405,23 +401,19 @@ export class MoviePlayerService implements AsyncDisposable {
       void this.startHlsPlayback(this.videoElement)
       this.waitForCanPlay(this.videoElement)
     } else {
-      this.isSwitching = false
+      this.isSwitching.setValue(false)
     }
   }
 
   private waitForCanPlay(video: HTMLVideoElement) {
     const onCanPlay = () => {
       video.removeEventListener('canplay', onCanPlay)
-      this.isSwitching = false
+      this.isSwitching.setValue(false)
       void video.play().catch(() => {})
     }
     video.addEventListener('canplay', onCanPlay)
   }
 
-  public getIsSwitching(): boolean {
-    return this.isSwitching
-  }
-
   public getAudioTrackInfoFromPlaybackInfo(): AudioTrackInfo[] {
     return this.playbackInfo.getValue()?.audioTracks ?? []
   }
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
index 104fbb82..84dc3abf 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
@@ -236,7 +236,7 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
               mediaService.seekToTime(currentTime)
             }}
             ontimeupdate={(ev) => {
-              if (mediaService.getIsSwitching()) return
+              if (mediaService.isSwitching.getValue()) return
               const { currentTime } = ev.currentTarget as HTMLVideoElement
               mediaService.progress.setValue(currentTime || 0)
             }}
diff --git a/service/src/app-models/media/actions/hls-session-teardown-action.spec.ts b/service/src/app-models/media/actions/hls-session-teardown-action.spec.ts
index 795d8aef..c197ba62 100644
--- a/service/src/app-models/media/actions/hls-session-teardown-action.spec.ts
+++ b/service/src/app-models/media/actions/hls-session-teardown-action.spec.ts
@@ -21,7 +21,7 @@ describe('HlsSessionTeardownAction', () => {
         await HlsSessionTeardownAction({
           injector,
           getUrlParams: () => ({ letter: 'A', path: '../etc/passwd' }),
-          getQuery: () => ({ mode: 'transcode' }),
+          getQuery: () => ({}),
           response: {} as ServerResponse,
           request: {} as IncomingMessage,
         })
@@ -44,7 +44,7 @@ describe('HlsSessionTeardownAction', () => {
       const result = await HlsSessionTeardownAction({
         injector,
         getUrlParams: () => ({ letter: 'A', path: 'test.mkv' }),
-        getQuery: () => ({ mode: 'transcode', audioTrack: 1, resolution: '720p' }),
+        getQuery: () => ({}),
         response: {} as ServerResponse,
         request: {} as IncomingMessage,
       })
diff --git a/service/src/app-models/media/announce-movie-file-added.spec.ts b/service/src/app-models/media/announce-movie-file-added.spec.ts
new file mode 100644
index 00000000..9ebd45bc
--- /dev/null
+++ b/service/src/app-models/media/announce-movie-file-added.spec.ts
@@ -0,0 +1,112 @@
+import { Injector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import type { Movie, MovieFile } from 'common'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { WebsocketService } from '../../websocket-service.js'
+import { announceMovieFileAdded } from './announce-movie-file-added.js'
+
+vi.mock('@furystack/core', () => ({
+  isAuthorized: vi.fn().mockResolvedValue(true),
+}))
+
+describe('announceMovieFileAdded', () => {
+  const mockAnnounce = vi.fn().mockResolvedValue(undefined)
+  const mockGet = vi.fn()
+  const mockLogger = {
+    error: vi.fn().mockResolvedValue(undefined),
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const createEntity = (overrides?: Partial<MovieFile>): MovieFile =>
+    ({
+      id: 'file-1',
+      driveLetter: 'A',
+      path: 'movies/test.mkv',
+      imdbId: 'tt1234567',
+      ffprobe: {},
+      ...overrides,
+    }) as MovieFile
+
+  const createMovieDataSet = () => ({
+    get: (...args: unknown[]) => mockGet(...args) as unknown,
+  })
+
+  it('should return early when entity has no imdbId', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      await announceMovieFileAdded({
+        entity: createEntity({ imdbId: undefined }),
+        injector,
+        movieDataSet: createMovieDataSet() as never,
+        logger: mockLogger as never,
+      })
+
+      expect(mockGet).not.toHaveBeenCalled()
+      expect(mockAnnounce).not.toHaveBeenCalled()
+    })
+  })
+
+  it('should announce via websocket when movie exists', async () => {
+    const movie: Movie = { imdbId: 'tt1234567', createdAt: '', updatedAt: '' }
+    mockGet.mockResolvedValue(movie)
+
+    await usingAsync(new Injector(), async (injector) => {
+      injector.setExplicitInstance({ announce: mockAnnounce } as unknown as WebsocketService, WebsocketService)
+
+      await announceMovieFileAdded({
+        entity: createEntity(),
+        injector,
+        movieDataSet: createMovieDataSet() as never,
+        logger: mockLogger as never,
+      })
+
+      expect(mockGet).toHaveBeenCalledWith(injector, 'tt1234567')
+      expect(mockAnnounce).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'add-movie',
+          file: { driveLetter: 'A', path: 'movies/test.mkv' },
+          movie,
+        }),
+        expect.any(Function),
+      )
+    })
+  })
+
+  it('should not announce when movie is not found', async () => {
+    mockGet.mockResolvedValue(null)
+
+    await usingAsync(new Injector(), async (injector) => {
+      injector.setExplicitInstance({ announce: mockAnnounce } as unknown as WebsocketService, WebsocketService)
+
+      await announceMovieFileAdded({
+        entity: createEntity(),
+        injector,
+        movieDataSet: createMovieDataSet() as never,
+        logger: mockLogger as never,
+      })
+
+      expect(mockAnnounce).not.toHaveBeenCalled()
+    })
+  })
+
+  it('should log error when movie lookup fails', async () => {
+    mockGet.mockRejectedValue(new Error('DB error'))
+
+    await usingAsync(new Injector(), async (injector) => {
+      await announceMovieFileAdded({
+        entity: createEntity(),
+        injector,
+        movieDataSet: createMovieDataSet() as never,
+        logger: mockLogger as never,
+      })
+
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: expect.stringContaining('Failed to announce'),
+        }),
+      )
+    })
+  })
+})
diff --git a/service/src/app-models/media/utils/ensure-series-exists.spec.ts b/service/src/app-models/media/utils/ensure-series-exists.spec.ts
new file mode 100644
index 00000000..99e6108a
--- /dev/null
+++ b/service/src/app-models/media/utils/ensure-series-exists.spec.ts
@@ -0,0 +1,91 @@
+import { Injector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ensureSeriesExists } from './ensure-series-exists.js'
+
+const mockGet = vi.fn()
+const mockAdd = vi.fn()
+
+vi.mock('@furystack/repository', () => ({
+  getDataSetFor: () => ({
+    get: (...args: unknown[]) => mockGet(...args) as unknown,
+    add: (...args: unknown[]) => mockAdd(...args) as unknown,
+  }),
+}))
+
+describe('ensureSeriesExists', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const seriesInput = {
+    imdbId: 'tt1234567',
+    year: '2020',
+    numberOfSeasons: 5,
+  }
+
+  it('should not create a new series when one already exists', async () => {
+    const existing = { imdbId: 'tt1234567', year: '2020' }
+    mockGet.mockResolvedValue(existing)
+
+    await usingAsync(new Injector(), async (injector) => {
+      await ensureSeriesExists(seriesInput, injector)
+
+      expect(mockGet).toHaveBeenCalledWith(injector, 'tt1234567')
+      expect(mockAdd).not.toHaveBeenCalled()
+    })
+  })
+
+  it('should create a new series when not found', async () => {
+    mockGet.mockResolvedValue(null)
+    mockAdd.mockResolvedValue({ created: [{ ...seriesInput }] })
+
+    await usingAsync(new Injector(), async (injector) => {
+      await ensureSeriesExists(seriesInput, injector)
+
+      expect(mockAdd).toHaveBeenCalledWith(
+        injector,
+        expect.objectContaining({
+          imdbId: 'tt1234567',
+          year: '2020',
+          numberOfSeasons: 5,
+        }),
+      )
+    })
+  })
+
+  it('should set timestamps on creation', async () => {
+    mockGet.mockResolvedValue(null)
+    mockAdd.mockResolvedValue({ created: [{}] })
+
+    await usingAsync(new Injector(), async (injector) => {
+      await ensureSeriesExists(seriesInput, injector)
+
+      const addCall = mockAdd.mock.calls[0][1] as Record<string, unknown>
+      expect(addCall.createdAt).toBeDefined()
+      expect(addCall.updatedAt).toBeDefined()
+      expect(typeof addCall.createdAt).toBe('string')
+      expect(typeof addCall.updatedAt).toBe('string')
+    })
+  })
+
+  it('should create a series without numberOfSeasons', async () => {
+    mockGet.mockResolvedValue(null)
+    mockAdd.mockResolvedValue({ created: [{}] })
+
+    const input = { imdbId: 'tt9999999', year: '2015' }
+
+    await usingAsync(new Injector(), async (injector) => {
+      await ensureSeriesExists(input, injector)
+
+      expect(mockAdd).toHaveBeenCalledWith(
+        injector,
+        expect.objectContaining({
+          imdbId: 'tt9999999',
+          year: '2015',
+          numberOfSeasons: undefined,
+        }),
+      )
+    })
+  })
+})
diff --git a/service/src/app-models/media/utils/link-movie.ts b/service/src/app-models/media/utils/link-movie.ts
index 1bda6bd4..a37409e7 100644
--- a/service/src/app-models/media/utils/link-movie.ts
+++ b/service/src/app-models/media/utils/link-movie.ts
@@ -12,6 +12,7 @@ import {
   MovieFile,
   OmdbMovieMetadata,
   type MetadataProviderConfig,
+  type Movie,
   type PiRatFile,
 } from 'common'
 import { FfprobeService } from '../../../ffprobe-service.js'
@@ -29,7 +30,20 @@ import { ensureMovieLocalizedMetadataExists } from './ensure-localized-metadata-
 import { mapOmdbMovieToLocalized } from './map-omdb-to-localized.js'
 import { mapTmdbMovieToLocalized } from './map-tmdb-to-localized.js'
 
-type ProviderResult = { status: 'skip' } | { status: 'rate-limited' } | { status: 'linked'; imdbId: string }
+type ProviderResult =
+  | { status: 'skip' }
+  | { status: 'rate-limited' }
+  | { status: 'linked'; imdbId: string; movie: Movie }
+
+/**
+ * Normalizes an IETF locale (e.g. 'en-US') to a storage-friendly language code.
+ * Preserves region for Chinese (zh-CN vs zh-TW) where it distinguishes scripts.
+ */
+const normalizeLanguage = (locale: string): string => {
+  const parts = locale.split('-')
+  if (parts[0] === 'zh' && parts[1]) return `${parts[0]}-${parts[1]}`
+  return parts[0]
+}
 
 const getProviderPriority = async (injector: Injector): Promise<Array<'omdb' | 'tmdb'>> => {
   try {
@@ -58,7 +72,7 @@ const tryOmdbProvider = async (
   if (result.status === 'error') return { status: 'skip' }
 
   const added = await ensureOmdbMovieExists(result.data, injector)
-  await ensureMovieExists(
+  const movie = await ensureMovieExists(
     {
       imdbId: added.imdbID,
       year: parseInt(added.Year, 10),
@@ -73,7 +87,7 @@ const tryOmdbProvider = async (
   await ensureMovieLocalizedMetadataExists(mapOmdbMovieToLocalized(added), injector)
   await ensureOmdbSeriesExists(added, injector, context)
 
-  return { status: 'linked', imdbId: added.imdbID }
+  return { status: 'linked', imdbId: added.imdbID, movie }
 }
 
 const tryTmdbProvider = async (
@@ -93,11 +107,11 @@ const tryTmdbProvider = async (
   const imdbId = tmdbMovie.imdb_id
   if (!imdbId) return { status: 'skip' }
 
-  const language = tmdbClientService.config?.value.defaultLanguage?.slice(0, 2) ?? 'en'
+  const language = normalizeLanguage(tmdbClientService.config?.value.defaultLanguage ?? 'en-US')
 
   await ensureTmdbMovieExists(tmdbMovie, language, injector)
 
-  await ensureMovieExists(
+  const movie = await ensureMovieExists(
     {
       imdbId,
       year: tmdbMovie.release_date ? parseInt(tmdbMovie.release_date.slice(0, 4), 10) : undefined,
@@ -109,7 +123,7 @@ const tryTmdbProvider = async (
     },
     injector,
   )
-  await ensureMovieLocalizedMetadataExists(mapTmdbMovieToLocalized(tmdbMovie, language), injector)
+  await ensureMovieLocalizedMetadataExists(mapTmdbMovieToLocalized(tmdbMovie, imdbId, language), injector)
 
   if (tmdbSeries) {
     const seriesImdbId = tmdbSeries.external_ids?.imdb_id
@@ -118,7 +132,12 @@ const tryTmdbProvider = async (
     }
   }
 
-  return { status: 'linked', imdbId }
+  return { status: 'linked', imdbId, movie }
+}
+
+const metadataProviders: Record<string, typeof tryOmdbProvider> = {
+  omdb: tryOmdbProvider,
+  tmdb: tryTmdbProvider,
 }
 
 /**
@@ -131,13 +150,9 @@ const enrichMetadataFromProviders = async (
   context?: { file?: PiRatFile },
 ) => {
   const priority = await getProviderPriority(injector)
-  const providers: Record<string, typeof tryOmdbProvider> = {
-    omdb: tryOmdbProvider,
-    tmdb: tryTmdbProvider,
-  }
 
   for (const provider of priority) {
-    const tryProvider = providers[provider]
+    const tryProvider = metadataProviders[provider]
     if (!tryProvider) continue
 
     const result = await tryProvider(injector, params, context)
@@ -303,14 +318,10 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
 
   // Try providers in priority order
   const priority = await getProviderPriority(injector)
-  const providers: Record<string, typeof tryOmdbProvider> = {
-    omdb: tryOmdbProvider,
-    tmdb: tryTmdbProvider,
-  }
 
-  let linkedImdbId: string | undefined
+  let linkedResult: { imdbId: string; movie: Movie } | undefined
   for (const provider of priority) {
-    const tryProvider = providers[provider]
+    const tryProvider = metadataProviders[provider]
     if (!tryProvider) continue
 
     const result = await tryProvider(injector, { title, year, season, episode }, { file })
@@ -324,12 +335,12 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
       return { status: 'rate-limited' } as const
     }
     if (result.status === 'linked') {
-      linkedImdbId = result.imdbId
+      linkedResult = result
       break
     }
   }
 
-  if (!linkedImdbId) {
+  if (!linkedResult) {
     await logger.debug({
       message: `No metadata found for '${fileName}' from any provider.`,
       data: { file, title, year },
@@ -342,14 +353,14 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
   } = await movieFileDataSet.add(injector, {
     driveLetter,
     path,
-    imdbId: linkedImdbId,
+    imdbId: linkedResult.imdbId,
     ffprobe: ffprobeResult,
   })
 
   await logger.debug({
     message: `File ${fileName} linked successfully.`,
-    data: { file, movieFile: newMovieFile },
+    data: { file, movieFile: newMovieFile, movie: linkedResult.movie },
   })
 
-  return { status: 'linked', movieFile: newMovieFile, movie: { imdbId: linkedImdbId } } as const
+  return { status: 'linked', movieFile: newMovieFile, movie: linkedResult.movie } as const
 }
diff --git a/service/src/app-models/media/utils/map-tmdb-to-localized.spec.ts b/service/src/app-models/media/utils/map-tmdb-to-localized.spec.ts
index cb18f43d..0a1e5756 100644
--- a/service/src/app-models/media/utils/map-tmdb-to-localized.spec.ts
+++ b/service/src/app-models/media/utils/map-tmdb-to-localized.spec.ts
@@ -17,7 +17,7 @@ describe('mapTmdbMovieToLocalized', () => {
     }) as TmdbMovieDetailsResponse
 
   it('should map all fields correctly', () => {
-    const result = mapTmdbMovieToLocalized(createTmdbMovie(), 'en')
+    const result = mapTmdbMovieToLocalized(createTmdbMovie(), 'tt1234567', 'en')
 
     expect(result).toEqual({
       movieImdbId: 'tt1234567',
@@ -34,21 +34,26 @@ describe('mapTmdbMovieToLocalized', () => {
   it('should set posterUrl to undefined when poster_path is null', () => {
     const movie = createTmdbMovie()
     movie.poster_path = null
-    const result = mapTmdbMovieToLocalized(movie, 'en')
+    const result = mapTmdbMovieToLocalized(movie, 'tt1234567', 'en')
     expect(result.posterUrl).toBeUndefined()
   })
 
   it('should set plot to undefined when overview is empty', () => {
     const movie = createTmdbMovie()
     movie.overview = ''
-    const result = mapTmdbMovieToLocalized(movie, 'en')
+    const result = mapTmdbMovieToLocalized(movie, 'tt1234567', 'en')
     expect(result.plot).toBeUndefined()
   })
 
   it('should use provided language', () => {
-    const result = mapTmdbMovieToLocalized(createTmdbMovie(), 'fr')
+    const result = mapTmdbMovieToLocalized(createTmdbMovie(), 'tt1234567', 'fr')
     expect(result.language).toBe('fr')
   })
+
+  it('should use the explicitly provided imdbId', () => {
+    const result = mapTmdbMovieToLocalized(createTmdbMovie(), 'tt0000001', 'en')
+    expect(result.movieImdbId).toBe('tt0000001')
+  })
 })
 
 describe('mapTmdbSeriesToLocalized', () => {
diff --git a/service/src/app-models/media/utils/map-tmdb-to-localized.ts b/service/src/app-models/media/utils/map-tmdb-to-localized.ts
index fe596de5..af25959a 100644
--- a/service/src/app-models/media/utils/map-tmdb-to-localized.ts
+++ b/service/src/app-models/media/utils/map-tmdb-to-localized.ts
@@ -5,9 +5,10 @@ import { buildTmdbImageUrl } from '../metadata-services/tmdb-client-service.js'
 
 export const mapTmdbMovieToLocalized = (
   tmdbMovie: TmdbMovieDetailsResponse,
+  imdbId: string,
   language: string,
 ): Omit<MovieMetadataLocalized, 'id' | 'createdAt' | 'updatedAt'> => ({
-  movieImdbId: tmdbMovie.imdb_id!,
+  movieImdbId: imdbId,
   language,
   title: tmdbMovie.title,
   plot: tmdbMovie.overview || undefined,

From 78bff720d045c8389552b6542310d1342e197dd1 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Wed, 11 Mar 2026 17:08:11 +0100
Subject: [PATCH 17/30] playback fixes

---
 .../movie-player-v2/movie-player-service.ts   | 96 ++++++++++++-------
 .../movie-player-v2-component.tsx             |  4 +-
 .../services/transcoding-session.spec.ts      |  4 +-
 .../media/services/transcoding-session.ts     | 15 ++-
 4 files changed, 75 insertions(+), 44 deletions(-)

diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index c4bf802f..9315afd1 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -10,7 +10,7 @@ import {
   type PlaybackMode,
   type SubtitleTrackInfo,
 } from 'common'
-import type Hls from 'hls.js'
+import Hls from 'hls.js'
 import type { MediaApiClient } from '../../../services/api-clients/media-api-client.js'
 import { environmentOptions } from '../../../utils/environment-options.js'
 
@@ -29,11 +29,6 @@ export const audioCodecs = {
   dts: 'dts+',
 }
 
-const loadHls = async () => {
-  const mod = await import('hls.js')
-  return mod.default
-}
-
 const buildCodecSupportMap = () => {
   const supportedVideo: string[] = []
   const supportedAudio: string[] = []
@@ -87,7 +82,29 @@ export class MoviePlayerService implements AsyncDisposable {
   public resolution = new ObservableValue<ResolutionValue | undefined>(undefined)
   public progress: ObservableValue<number>
 
+  /**
+   * Converts a 0-based stream time (from video.currentTime during HLS)
+   * to the absolute file position. For direct-play, the value is returned
+   * unchanged because the video element already uses absolute timestamps.
+   */
+  public streamTimeToAbsolute(streamTime: number): number {
+    const mode = this.playbackMode.getValue()
+    if (mode === 'direct-play') return streamTime
+    return streamTime + this.hlsStartTime
+  }
+
+  private getAbsoluteProgress(): number {
+    const video = this.videoElement
+    if (!video) return this.progress.getValue()
+    return this.streamTimeToAbsolute(video.currentTime)
+  }
+
   public async [Symbol.asyncDispose]() {
+    if (this.seekDebounceTimer) {
+      clearTimeout(this.seekDebounceTimer)
+      this.seekDebounceTimer = null
+    }
+
     await this.teardownHlsSession()
 
     this.progress[Symbol.dispose]()
@@ -187,7 +204,7 @@ export class MoviePlayerService implements AsyncDisposable {
     if (mode === 'direct-play') {
       this.startDirectPlayback(videoElement, info)
     } else {
-      void this.startHlsPlayback(videoElement)
+      this.startHlsPlayback(videoElement)
     }
   }
 
@@ -204,7 +221,7 @@ export class MoviePlayerService implements AsyncDisposable {
     }
   }
 
-  private async startHlsPlayback(videoElement: HTMLVideoElement) {
+  private startHlsPlayback(videoElement: HTMLVideoElement) {
     const mode = this.playbackMode.getValue()
     const audioTrack = this.audioTrackId.getValue()
     const audioParam = audioTrack ? `&audioTrack=${encode(String(audioTrack))}` : ''
@@ -213,12 +230,10 @@ export class MoviePlayerService implements AsyncDisposable {
       `/api/media/files/${encodeURIComponent(this.file.driveLetter)}/${encodeURIComponent(this.file.path)}/master.m3u8?mode=${encode(mode)}${audioParam}${startTimeParam}`,
     )
 
-    const HlsModule = await loadHls()
-
     // Prefer hls.js over native HLS — many browsers (including Chromium) report
     // canPlayType('application/vnd.apple.mpegurl') as 'maybe' without full support.
     // hls.js also handles missing alternative renditions more gracefully.
-    if (!HlsModule.isSupported()) {
+    if (!Hls.isSupported()) {
       if (videoElement.canPlayType('application/vnd.apple.mpegurl')) {
         void this.logger.verbose({ message: 'Using native HLS playback' })
         videoElement.src = hlsUrl
@@ -233,23 +248,24 @@ export class MoviePlayerService implements AsyncDisposable {
 
     void this.logger.verbose({ message: 'Starting HLS playback via hls.js' })
 
-    this.hls = new HlsModule({
+    this.hls = new Hls({
       xhrSetup: (xhr) => {
         xhr.withCredentials = true
       },
-      startPosition: this.currentProgress > 0 ? this.currentProgress : -1,
+
+      startPosition: this.currentProgress > this.hlsStartTime ? this.currentProgress - this.hlsStartTime : -1,
     })
 
-    this.hls.on(HlsModule.Events.ERROR, (_event, data) => {
+    this.hls.on(Hls.Events.ERROR, (_event, data) => {
       if (data.fatal) {
         void this.logger.error({
           message: `HLS fatal error: ${data.type}`,
           data: { details: data.details },
         })
 
-        if (data.type === HlsModule.ErrorTypes.NETWORK_ERROR) {
+        if (data.type === Hls.ErrorTypes.NETWORK_ERROR) {
           this.hls?.startLoad()
-        } else if (data.type === HlsModule.ErrorTypes.MEDIA_ERROR) {
+        } else if (data.type === Hls.ErrorTypes.MEDIA_ERROR) {
           this.hls?.recoverMediaError()
         }
       }
@@ -257,7 +273,7 @@ export class MoviePlayerService implements AsyncDisposable {
 
     const { hls } = this
 
-    hls.on(HlsModule.Events.MANIFEST_PARSED, () => {
+    hls.on(Hls.Events.MANIFEST_PARSED, () => {
       void this.logger.verbose({ message: 'HLS manifest parsed' })
 
       const resolutionHeightMap: Record<string, number> = {
@@ -279,7 +295,7 @@ export class MoviePlayerService implements AsyncDisposable {
         hls.currentLevel = levelIndex >= 0 ? levelIndex : -1
       })
 
-      hls.on(HlsModule.Events.DESTROYING, () => sub[Symbol.dispose]())
+      hls.on(Hls.Events.DESTROYING, () => sub[Symbol.dispose]())
     })
 
     this.hls.loadSource(hlsUrl)
@@ -290,7 +306,7 @@ export class MoviePlayerService implements AsyncDisposable {
    * Switches audio track and reloads from current position
    */
   public async switchAudioTrack(trackIndex: number) {
-    const previousProgress = this.videoElement?.currentTime ?? this.progress.getValue()
+    const previousProgress = this.getAbsoluteProgress()
 
     this.isSwitching.setValue(true)
     await this.teardownHlsSession()
@@ -315,22 +331,17 @@ export class MoviePlayerService implements AsyncDisposable {
    * Switches resolution and restarts playback. Forces transcode mode when a
    * specific resolution is requested; restores the original mode on "Auto".
    *
-   * If already in transcode mode, just changes hls.js level (no reload).
-   * A full reload only happens when the playback mode changes.
+   * Always tears down the existing server-side HLS session to ensure the
+   * old ffmpeg process is cleaned up before the new one starts.
    */
   public async switchResolution(value: ResolutionValue | undefined) {
-    const currentMode = this.playbackMode.getValue()
     const targetMode = value ? 'transcode' : this.originalPlaybackMode
 
-    if (currentMode === 'transcode' && targetMode === 'transcode') {
-      this.resolution.setValue(value)
-      return
-    }
+    const previousProgress = this.getAbsoluteProgress()
 
-    const previousProgress = this.videoElement?.currentTime ?? this.progress.getValue()
+    this.isSwitching.setValue(true)
     await this.teardownHlsSession()
 
-    this.isSwitching.setValue(true)
     this.resolution.setValue(value)
     this.currentProgress = previousProgress
     this.progress.setValue(previousProgress)
@@ -350,10 +361,14 @@ export class MoviePlayerService implements AsyncDisposable {
     }
   }
 
+  private seekDebounceTimer: ReturnType<typeof setTimeout> | null = null
+
   /**
-   * Handles a seek to a new time position. If the target is not within the
-   * video's buffered ranges and we're in HLS mode, tears down the current
-   * session and starts a new one with server-side seeking via `-ss`.
+   * Handles a seek to a new absolute file time position. If the target is
+   * before the current playlist start, tears down the current session and
+   * starts a new one with server-side seeking via `-ss`. Forward seeks
+   * within the current playlist are left to hls.js which can load the
+   * required segments on its own.
    */
   public seekToTime(targetSeconds: number) {
     const mode = this.playbackMode.getValue()
@@ -362,12 +377,23 @@ export class MoviePlayerService implements AsyncDisposable {
     const video = this.videoElement
     if (!video) return
 
-    if (this.isTimeBuffered(video, targetSeconds)) return
+    // Convert absolute file time to 0-based stream time for the buffer check
+    const streamTime = targetSeconds - this.hlsStartTime
+    if (streamTime >= 0 && this.isTimeBuffered(video, streamTime)) return
+
+    // hls.js can handle forward seeks within the current VOD playlist
+    if (targetSeconds >= this.hlsStartTime) return
 
     const quantizedStart = Math.floor(targetSeconds / HLS_SEGMENT_DURATION) * HLS_SEGMENT_DURATION
-    if (quantizedStart === this.hlsStartTime) return
 
-    void this.restartHlsAtTime(targetSeconds, quantizedStart)
+    if (this.seekDebounceTimer) {
+      clearTimeout(this.seekDebounceTimer)
+    }
+
+    this.seekDebounceTimer = setTimeout(() => {
+      this.seekDebounceTimer = null
+      void this.restartHlsAtTime(targetSeconds, quantizedStart)
+    }, 300)
   }
 
   private isTimeBuffered(video: HTMLVideoElement, time: number): boolean {
@@ -398,7 +424,7 @@ export class MoviePlayerService implements AsyncDisposable {
     this.progress.setValue(targetSeconds)
 
     if (this.videoElement) {
-      void this.startHlsPlayback(this.videoElement)
+      this.startHlsPlayback(this.videoElement)
       this.waitForCanPlay(this.videoElement)
     } else {
       this.isSwitching.setValue(false)
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
index 84dc3abf..7ecba37b 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
@@ -233,12 +233,12 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
             }}
             onseeking={(ev) => {
               const { currentTime } = ev.currentTarget as HTMLVideoElement
-              mediaService.seekToTime(currentTime)
+              mediaService.seekToTime(mediaService.streamTimeToAbsolute(currentTime))
             }}
             ontimeupdate={(ev) => {
               if (mediaService.isSwitching.getValue()) return
               const { currentTime } = ev.currentTarget as HTMLVideoElement
-              mediaService.progress.setValue(currentTime || 0)
+              mediaService.progress.setValue(mediaService.streamTimeToAbsolute(currentTime) || 0)
             }}
           >
             {...subtitleElements}
diff --git a/service/src/app-models/media/services/transcoding-session.spec.ts b/service/src/app-models/media/services/transcoding-session.spec.ts
index b8288fe4..31e1e94c 100644
--- a/service/src/app-models/media/services/transcoding-session.spec.ts
+++ b/service/src/app-models/media/services/transcoding-session.spec.ts
@@ -1103,7 +1103,7 @@ describe('TranscodingSessionService', () => {
       })
     })
 
-    it('should offset -force_key_frames by startTime for transcode mode', async () => {
+    it('should use 0-based -force_key_frames for transcode mode (no startTime offset since -copyts is not used)', async () => {
       const mockProcess = createMockProcess()
       mockSpawn.mockReturnValue(mockProcess)
 
@@ -1130,7 +1130,7 @@ describe('TranscodingSessionService', () => {
           const args = lastCall[1]
           const fkfIndex = args.indexOf('-force_key_frames')
           expect(fkfIndex).toBeGreaterThanOrEqual(0)
-          expect(args[fkfIndex + 1]).toBe('expr:gte(t,n_forced*6+3600)')
+          expect(args[fkfIndex + 1]).toBe('expr:gte(t,n_forced*6)')
         } finally {
           service.dispose()
         }
diff --git a/service/src/app-models/media/services/transcoding-session.ts b/service/src/app-models/media/services/transcoding-session.ts
index 16462edd..881911da 100644
--- a/service/src/app-models/media/services/transcoding-session.ts
+++ b/service/src/app-models/media/services/transcoding-session.ts
@@ -391,13 +391,18 @@ export class TranscodingSessionService {
 
     const args: string[] = []
 
-    // Input seeking (before -i for fast keyframe-based seeking)
+    // Input seeking (before -i for fast keyframe-based seeking).
+    // Do NOT add -copyts here: it preserves the original PTS from the
+    // source file which causes a mismatch between the HLS playlist
+    // timeline (starts at 0) and the media PTS (starts at ~startTime).
+    // This breaks hls.js startPosition, causes the progress bar to
+    // show 00:00, and introduces audio/video desync because -ss seeks
+    // to the nearest video keyframe while audio seeking is sample-precise.
+    // The client adds hlsStartTime to video.currentTime instead.
     if (startTime > 0) {
       args.push('-ss', String(startTime))
     }
 
-    // Input with timestamp preservation (like Jellyfin)
-    args.push('-copyts', '-avoid_negative_ts', 'disabled')
     args.push('-i', fullPath)
 
     // Thread config
@@ -440,8 +445,8 @@ export class TranscodingSessionService {
 
       args.push('-c:v', videoCodec)
 
-      // Force keyframes at segment boundaries (offset by startTime when -copyts preserves original PTS)
-      args.push('-force_key_frames', `expr:gte(t,n_forced*${HLS_SEGMENT_DURATION}+${startTime})`)
+      // Force keyframes at segment boundaries (t starts from 0 since we don't use -copyts)
+      args.push('-force_key_frames', `expr:gte(t,n_forced*${HLS_SEGMENT_DURATION})`)
       args.push('-sc_threshold:v', '0')
 
       const isSoftwareEncoder = videoCodec === 'libx264' || videoCodec === 'libx265'

From 1bfcc5fe6e71aaa1adf9f7849cfcf260f5ead85d Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Thu, 12 Mar 2026 11:31:14 +0100
Subject: [PATCH 18/30] added fast build option without monaco

---
 package.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/package.json b/package.json
index f04ecad7..6623c36a 100644
--- a/package.json
+++ b/package.json
@@ -51,6 +51,7 @@
   "scripts": {
     "prepare": "husky",
     "build:monaco-mfe": "yarn workspace monaco-mfe build",
+    "build:fast": "tsc -b common service frontend && yarn workspace frontend build",
     "build": "yarn build:monaco-mfe && tsc -b common service frontend && yarn workspace frontend build",
     "create-schemas": "yarn workspace common create-schemas",
     "test:e2e:install": "yarn playwright test --grep @install --project chromium",

From 44888fc81bd18783f72ef2ff21820b0a6b7c3491 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Thu, 12 Mar 2026 11:40:44 +0100
Subject: [PATCH 19/30] fire-and-forget fixes

---
 .cursor/rules/ASYNC_PATTERNS.mdc              | 88 +++++++++++++++++++
 .cursor/rules/SINGLETON_CONCURRENCY.md        |  2 +
 .cursor/rules/rules-index.mdc                 |  1 +
 .../movie-player-v2/movie-player-service.ts   |  1 +
 .../services/transcoding-session.spec.ts      | 10 +--
 .../media/services/transcoding-session.ts     | 60 +++++++------
 6 files changed, 130 insertions(+), 32 deletions(-)
 create mode 100644 .cursor/rules/ASYNC_PATTERNS.mdc

diff --git a/.cursor/rules/ASYNC_PATTERNS.mdc b/.cursor/rules/ASYNC_PATTERNS.mdc
new file mode 100644
index 00000000..5cd336de
--- /dev/null
+++ b/.cursor/rules/ASYNC_PATTERNS.mdc
@@ -0,0 +1,88 @@
+---
+alwaysApply: false
+---
+# Async Patterns
+
+## Fire-and-Forget Promises Must Handle Errors
+
+Every fire-and-forget `void` promise call must include a `.catch()` that logs the error. An unhandled async rejection is a silent bug.
+
+```typescript
+// ✅ Good — error is logged
+void this.evictByDiskUsage().catch((error) => {
+  void this.logger.error({ message: 'Failed to evict by disk usage', data: { error } })
+})
+
+// ✅ Good — singleton init pattern (see SINGLETON_CONCURRENCY.md)
+void this.initAsync().catch((error) => {
+  void this.logger.error({ message: 'Failed to initialize service', data: { error } })
+})
+
+// ❌ Bad — error silently lost
+void this.evictByDiskUsage()
+
+// ❌ Bad — empty catch swallows errors
+void this.evictByDiskUsage().catch(() => {})
+```
+
+### Exception: Browser `video.play()`
+
+Browser `HTMLMediaElement.play()` rejects with `AbortError` when navigation interrupts playback. This is benign and expected. An empty `.catch(() => {})` is acceptable **only** with an explanatory comment.
+
+```typescript
+// ✅ Acceptable — benign browser rejection documented
+// play() can reject with AbortError when navigation interrupts playback; this is benign
+void video.play().catch(() => {})
+```
+
+### When `void` logger calls are fine
+
+Logger methods return promises but are fire-and-forget by design. `void this.logger.verbose(...)` is the correct pattern — do not `await` logger calls in hot paths.
+
+### When `void` in frontend event handlers is fine
+
+Sync DOM callbacks (`onclick`, `onsubmit`, `ondrop`) cannot be `async`. Using `void asyncFn()` is correct when the called function handles its own errors internally (e.g., shows user-facing error notifications).
+
+## Prefer `fs/promises` in Async Contexts
+
+When inside an `async` function, use `fs/promises` instead of sync `fs` methods to avoid blocking the Node.js event loop.
+
+```typescript
+// ✅ Good — non-blocking in async context
+import { mkdir, stat, readdir, rm } from 'fs/promises'
+import { existsAsync } from '../../../utils/exists-async.js'
+
+async function ensureDir(dir: string) {
+  if (!(await existsAsync(dir))) {
+    await mkdir(dir, { recursive: true })
+  }
+}
+
+// ❌ Bad — blocks event loop in async context
+import { existsSync, mkdirSync } from 'fs'
+
+async function ensureDir(dir: string) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+}
+```
+
+### Mapping sync → async
+
+| Sync                     | Async equivalent                                   |
+| ------------------------ | -------------------------------------------------- |
+| `existsSync(p)`          | `existsAsync(p)` (from `service/src/utils/exists-async.ts`) |
+| `statSync(p)`            | `stat(p)` from `fs/promises`                       |
+| `mkdirSync(p, opts)`     | `mkdir(p, opts)` from `fs/promises`                |
+| `readdirSync(p, opts)`   | `readdir(p, opts)` from `fs/promises`              |
+| `rmSync(p, opts)`        | `rm(p, opts)` from `fs/promises`                   |
+| `readFileSync(p, enc)`   | `readFile(p, enc)` from `fs/promises`              |
+| `writeFileSync(p, data)` | `writeFile(p, data)` from `fs/promises`            |
+
+### When sync FS is acceptable
+
+- **Sync-only API contracts:** Vite middleware, Vite build hooks, Express middleware
+- **Test setup/teardown:** `beforeEach` / `afterEach` with small temp directories
+- **One-time cached helpers:** Sync helper that runs once and caches the result (e.g., `getBaseDir()`)
+- **Synchronous process cleanup:** `destroySession()` where the caller needs the directory removed before the reference is dropped
diff --git a/.cursor/rules/SINGLETON_CONCURRENCY.md b/.cursor/rules/SINGLETON_CONCURRENCY.md
index 9260b205..464d2a90 100644
--- a/.cursor/rules/SINGLETON_CONCURRENCY.md
+++ b/.cursor/rules/SINGLETON_CONCURRENCY.md
@@ -56,6 +56,8 @@ Apply this pattern when **all** of the following are true:
 
 ## Fire-and-Forget Async Initialization
 
+> See also [ASYNC_PATTERNS.mdc](./ASYNC_PATTERNS.mdc) for the broader rule on fire-and-forget promises and `fs/promises` usage.
+
 Singleton services that need async initialization (e.g., loading config from a database, connecting to external APIs) should **not** block startup. Use a synchronous `init()` that kicks off the async work and logs errors.
 
 ### The Problem
diff --git a/.cursor/rules/rules-index.mdc b/.cursor/rules/rules-index.mdc
index 23e8681d..5facd45a 100644
--- a/.cursor/rules/rules-index.mdc
+++ b/.cursor/rules/rules-index.mdc
@@ -14,3 +14,4 @@ This file contains a list of helpful information and context that the agent can
 - [MFE runtime type boundaries, duplicate type contracts, and cross-package type sync](./MFE_TYPE_CONTRACTS.md)
 - [Double-cast anti-pattern (`as unknown as T`) and non-null assertion avoidance](./TYPESCRIPT_GUIDELINES.mdc)
 - [Provider/adapter fallback chain patterns with narrow internal result types](./BACKEND_PATTERNS.mdc)
+- [Fire-and-forget error handling, `fs/promises` in async contexts, and `void` promise patterns](./ASYNC_PATTERNS.mdc)
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index 9315afd1..d76e57ee 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -435,6 +435,7 @@ export class MoviePlayerService implements AsyncDisposable {
     const onCanPlay = () => {
       video.removeEventListener('canplay', onCanPlay)
       this.isSwitching.setValue(false)
+      // play() can reject with AbortError when navigation interrupts playback; this is benign
       void video.play().catch(() => {})
     }
     video.addEventListener('canplay', onCanPlay)
diff --git a/service/src/app-models/media/services/transcoding-session.spec.ts b/service/src/app-models/media/services/transcoding-session.spec.ts
index 31e1e94c..227da088 100644
--- a/service/src/app-models/media/services/transcoding-session.spec.ts
+++ b/service/src/app-models/media/services/transcoding-session.spec.ts
@@ -409,7 +409,7 @@ describe('TranscodingSessionService', () => {
       if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true })
     })
 
-    it('should calculate session disk usage', () => {
+    it('should calculate session disk usage', async () => {
       const sessionDir = join(testDir, 'session1')
       mkdirSync(sessionDir, { recursive: true })
       writeFileSync(join(sessionDir, 'segment0.m4s'), Buffer.alloc(1000))
@@ -419,20 +419,20 @@ describe('TranscodingSessionService', () => {
       const service = new TranscodingSessionService()
       try {
         const mockSession = { sessionDir } as Parameters<typeof service.getSessionDiskUsage>[0]
-        const usage = service.getSessionDiskUsage(mockSession)
+        const usage = await service.getSessionDiskUsage(mockSession)
         expect(usage).toBe(3500)
       } finally {
         service.dispose()
       }
     })
 
-    it('should return 0 for non-existent session directory', () => {
+    it('should return 0 for non-existent session directory', async () => {
       const service = new TranscodingSessionService()
       try {
         const mockSession = { sessionDir: join(testDir, 'nonexistent') } as Parameters<
           typeof service.getSessionDiskUsage
         >[0]
-        const usage = service.getSessionDiskUsage(mockSession)
+        const usage = await service.getSessionDiskUsage(mockSession)
         expect(usage).toBe(0)
       } finally {
         service.dispose()
@@ -469,7 +469,7 @@ describe('TranscodingSessionService', () => {
           writeFileSync(join(s1.sessionDir, 'segment0.m4s'), Buffer.alloc(100))
           writeFileSync(join(s2.sessionDir, 'segment0.m4s'), Buffer.alloc(200))
 
-          const total = service.getTotalDiskUsage()
+          const total = await service.getTotalDiskUsage()
           expect(total).toBe(300)
         } finally {
           service.dispose()
diff --git a/service/src/app-models/media/services/transcoding-session.ts b/service/src/app-models/media/services/transcoding-session.ts
index 881911da..93d61751 100644
--- a/service/src/app-models/media/services/transcoding-session.ts
+++ b/service/src/app-models/media/services/transcoding-session.ts
@@ -6,8 +6,9 @@ import type { PlaybackMode } from 'common'
 import { Config, Drive, HLS_SEGMENT_DURATION, type MoviesConfig } from 'common'
 import { spawn, type ChildProcess } from 'child_process'
 import { createHash } from 'crypto'
-import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'fs'
-import { readFile } from 'fs/promises'
+import { existsSync, mkdirSync, rmSync } from 'fs'
+import { mkdir, readdir, readFile, stat } from 'fs/promises'
+import { existsAsync } from '../../../utils/exists-async.js'
 import { join } from 'path'
 import { tmpdir } from 'os'
 import { FfprobeService } from '../../../ffprobe-service.js'
@@ -97,7 +98,7 @@ export class TranscodingSessionService {
       const configDataSet = getDataSetFor(this.injector, Config, 'id')
       const config = (await configDataSet.get(this.systemInjector, 'MOVIES_CONFIG')) as MoviesConfig | undefined
       const dir = config?.value?.hlsSegmentPath || join(tmpdir(), 'pirat-hls-sessions')
-      if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+      if (!(await existsAsync(dir))) await mkdir(dir, { recursive: true })
       this.baseDirCache = dir
 
       const mb = config?.value?.hlsMaxCacheSizeMb ?? DEFAULT_MAX_CACHE_SIZE_MB
@@ -171,8 +172,8 @@ export class TranscodingSessionService {
   ): Promise<TranscodingSessionEntry> {
     await this.getBaseDirFromConfig()
     const sessionDir = this.getSessionDir(key)
-    if (!existsSync(sessionDir)) {
-      mkdirSync(sessionDir, { recursive: true })
+    if (!(await existsAsync(sessionDir))) {
+      await mkdir(sessionDir, { recursive: true })
     }
 
     const { args: ffmpegArgs, totalDuration } = await this.buildHlsFfmpegArgs({
@@ -229,7 +230,9 @@ export class TranscodingSessionService {
     })
 
     this.sessions.set(key, session)
-    void this.evictByDiskUsage()
+    void this.evictByDiskUsage().catch((error) => {
+      void this.logger.error({ message: 'Failed to evict sessions by disk usage', data: { error } })
+    })
     return session
   }
 
@@ -241,23 +244,22 @@ export class TranscodingSessionService {
     const deadline = Date.now() + WAIT_TIMEOUT_MS
 
     while (Date.now() < deadline) {
-      if (existsSync(filePath)) {
-        // For segments, check that the file has non-zero size
+      if (await existsAsync(filePath)) {
         try {
-          const stat = statSync(filePath)
-          if (stat.size > 0) return true
+          const fileStat = await stat(filePath)
+          if (fileStat.size > 0) return true
         } catch {
           // File might have been deleted between check and stat
         }
       }
 
       if (session.state === 'error') return false
-      if (session.state === 'completed' && !existsSync(filePath)) return false
+      if (session.state === 'completed' && !(await existsAsync(filePath))) return false
 
       await new Promise((resolve) => setTimeout(resolve, WAIT_POLL_INTERVAL_MS))
     }
 
-    return existsSync(filePath)
+    return existsAsync(filePath)
   }
 
   /**
@@ -270,9 +272,8 @@ export class TranscodingSessionService {
     const deadline = Date.now() + WAIT_TIMEOUT_MS
 
     while (Date.now() < deadline) {
-      if (existsSync(segmentPath)) {
-        // Segment is fully written if the next one exists or ffmpeg is done
-        if (existsSync(nextSegmentPath) || session.state === 'completed' || session.state === 'error') {
+      if (await existsAsync(segmentPath)) {
+        if ((await existsAsync(nextSegmentPath)) || session.state === 'completed' || session.state === 'error') {
           return true
         }
       }
@@ -282,7 +283,7 @@ export class TranscodingSessionService {
       await new Promise((resolve) => setTimeout(resolve, WAIT_POLL_INTERVAL_MS))
     }
 
-    return existsSync(segmentPath)
+    return existsAsync(segmentPath)
   }
 
   public async readPlaylist(session: TranscodingSessionEntry): Promise<string | null> {
@@ -522,16 +523,19 @@ export class TranscodingSessionService {
   /**
    * Returns the total bytes used by a session's directory on disk.
    */
-  public getSessionDiskUsage(session: TranscodingSessionEntry): number {
+  public async getSessionDiskUsage(session: TranscodingSessionEntry): Promise<number> {
     try {
-      if (!existsSync(session.sessionDir)) return 0
-      return readdirSync(session.sessionDir).reduce((total, file) => {
+      if (!(await existsAsync(session.sessionDir))) return 0
+      const files = await readdir(session.sessionDir)
+      let total = 0
+      for (const file of files) {
         try {
-          return total + statSync(join(session.sessionDir, file)).size
+          total += (await stat(join(session.sessionDir, file))).size
         } catch {
-          return total
+          // File may have been deleted
         }
-      }, 0)
+      }
+      return total
     } catch {
       return 0
     }
@@ -540,10 +544,10 @@ export class TranscodingSessionService {
   /**
    * Returns the total bytes used across all active session directories.
    */
-  public getTotalDiskUsage(): number {
+  public async getTotalDiskUsage(): Promise<number> {
     let total = 0
     for (const session of this.sessions.values()) {
-      total += this.getSessionDiskUsage(session)
+      total += await this.getSessionDiskUsage(session)
     }
     return total
   }
@@ -567,7 +571,7 @@ export class TranscodingSessionService {
    */
   private async evictByDiskUsage(): Promise<void> {
     const maxBytes = await this.loadMaxCacheSize()
-    let totalUsage = this.getTotalDiskUsage()
+    let totalUsage = await this.getTotalDiskUsage()
     if (totalUsage <= maxBytes) return
 
     // Sort sessions by lastAccessedAt ascending (oldest first), prefer completed/error over active
@@ -580,7 +584,7 @@ export class TranscodingSessionService {
 
     for (const [key, session] of candidates) {
       if (totalUsage <= maxBytes) break
-      const usage = this.getSessionDiskUsage(session)
+      const usage = await this.getSessionDiskUsage(session)
       void this.logger.verbose({
         message: `Evicting session for cache limit: ${key} (${Math.round(usage / BYTES_PER_MB)}MB)`,
       })
@@ -607,7 +611,9 @@ export class TranscodingSessionService {
       }
     }
 
-    void this.evictByDiskUsage()
+    void this.evictByDiskUsage().catch((error) => {
+      void this.logger.error({ message: 'Failed to evict sessions by disk usage', data: { error } })
+    })
   }
 
   private destroySession(session: TranscodingSessionEntry) {

From ccac2b13634e38370135d5904df8260c5c141fe8 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Thu, 12 Mar 2026 13:54:33 +0100
Subject: [PATCH 20/30] Native Shades video controls, code review fixes

---
 .cursor/rules/SCRIPT_EXECUTION.md             |   7 +
 .yarn/changelogs/frontend.90cc3afc.md         |   4 +-
 e2e/video-playback.spec.ts                    |  26 +-
 frontend/package.json                         |   2 -
 .../movies/movie-player-v2/control-area.tsx   | 124 -------
 .../controls/captions-button.tsx              |  53 +++
 .../movie-player-v2/controls/control-bar.tsx  |  46 +++
 .../controls/error-overlay.tsx                |  69 ++++
 .../controls/fullscreen-button.tsx            |  42 +++
 .../movies/movie-player-v2/controls/index.ts  |  13 +
 .../controls/loading-overlay.tsx              |  44 +++
 .../movie-player-v2/controls/pip-button.tsx   |  34 ++
 .../movie-player-v2/controls/play-button.tsx  |  36 ++
 .../movie-player-v2/controls/player-icons.ts  |  44 +++
 .../controls/poster-overlay.tsx               |  34 ++
 .../movie-player-v2/controls/seek-bar.tsx     |  84 +++++
 .../controls/settings-menu.tsx                | 243 +++++++++++++
 .../movie-player-v2/controls/time-display.tsx |  39 +++
 .../controls/video-container.tsx              | 155 +++++++++
 .../controls/volume-control.tsx               |  72 ++++
 .../movies/movie-player-v2/media-chrome.ts    |  93 -----
 .../movie-player-service.spec.ts              | 181 +++-------
 .../movie-player-v2/movie-player-service.ts   | 322 ++++++++++--------
 .../movie-player-v2-component.spec.ts         | 149 +-------
 .../movie-player-v2-component.tsx             | 171 +---------
 .../src/pages/movies/plain-hls-player.tsx     |  87 ++---
 yarn.lock                                     |  27 --
 27 files changed, 1276 insertions(+), 925 deletions(-)
 delete mode 100644 frontend/src/pages/movies/movie-player-v2/control-area.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/captions-button.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/control-bar.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/error-overlay.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/fullscreen-button.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/index.ts
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/loading-overlay.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/pip-button.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/play-button.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/player-icons.ts
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/poster-overlay.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/seek-bar.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/time-display.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/video-container.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/volume-control.tsx
 delete mode 100644 frontend/src/pages/movies/movie-player-v2/media-chrome.ts

diff --git a/.cursor/rules/SCRIPT_EXECUTION.md b/.cursor/rules/SCRIPT_EXECUTION.md
index a0511d4a..1b898cce 100644
--- a/.cursor/rules/SCRIPT_EXECUTION.md
+++ b/.cursor/rules/SCRIPT_EXECUTION.md
@@ -79,6 +79,13 @@ yarn create-schemas    # Generate schemas from API definitions
 yarn clean             # Clean build artifacts
 ```
 
+> **WARNING -- never run `tsc`, `tsc -b`, or `tsc --build` directly.**
+> The project uses `"composite": true` with project references, so bare
+> `tsc -b` emits `.js`, `.d.ts`, and `.js.map` files **into the source
+> tree**. Always use `yarn build` instead. If you only need a type check
+> without emitting, use the built-in linter tools (ReadLints) or run a
+> targeted `vitest` suite -- do NOT run tsc in any form.
+
 **Testing:**
 
 ```bash
diff --git a/.yarn/changelogs/frontend.90cc3afc.md b/.yarn/changelogs/frontend.90cc3afc.md
index 18645534..7ad2f18d 100644
--- a/.yarn/changelogs/frontend.90cc3afc.md
+++ b/.yarn/changelogs/frontend.90cc3afc.md
@@ -24,11 +24,13 @@ Added `LocalizedMetadataService` with caches for fetching `MovieMetadataLocalize
 
 ## 🐛 Bug Fixes
 
-- Fixed movie duration not displaying correctly in the player controls by passing `defaultDuration` to `media-controller`
+- Fixed movie duration not displaying correctly by preferring `playbackInfo.duration` over stream duration in seek bar
 - Fixed legacy navigation issues by relocating route utilities to `utils/` directory
 
 ## ♻️ Refactoring
 
+- Replaced `media-chrome` and `hls.js` dependencies with modular native player controls (`PlayButton`, `SeekBar`, `VolumeControl`, `SettingsMenu`, etc.) under `controls/` directory
+- Moved video event binding and playback state (play/pause, volume, duration, buffered) into `MoviePlayerService` observables
 - Extracted file context menu items into a pure `getContextMenuItems()` function, replacing the Shade-based `FileContextMenu` component
 - Extracted file drag-and-drop upload logic into `handleFileDrop()` utility
 - Extracted `SessionUserUnavailableError`, `getUser()`, and `hasRole()` into `utils/session-helpers.ts` for reusable session access
diff --git a/e2e/video-playback.spec.ts b/e2e/video-playback.spec.ts
index 01ce7d99..e69f2c5f 100644
--- a/e2e/video-playback.spec.ts
+++ b/e2e/video-playback.spec.ts
@@ -91,11 +91,11 @@ const navigateToMovieAndPlay = async (page: Page, browserName: string, wIndex: n
 }
 
 const openSettingsSubmenu = async (page: Page, menuItemText: string) => {
-  const settingsButton = page.locator('media-settings-menu-button').first()
+  const settingsButton = page.locator('[data-testid="settings-menu-button"]').first()
   await expect(settingsButton).toBeVisible({ timeout: 5_000 })
   await settingsButton.click()
 
-  const menuItem = page.locator('media-settings-menu-item').filter({ hasText: menuItemText })
+  const menuItem = page.locator('[data-testid="settings-menu-item"]').filter({ hasText: menuItemText })
   await expect(menuItem).toBeVisible({ timeout: 5_000 })
   await menuItem.click()
 }
@@ -219,7 +219,7 @@ test.describe('Video Playback @media', () => {
     await navigateToMovieAndPlay(page, browserName, workerIndex)
     await openSettingsSubmenu(page, 'Captions')
 
-    const captionOptions = page.locator('media-captions-menu media-chrome-menu-item')
+    const captionOptions = page.locator('[data-testid="caption-track-item"]')
     await expect(captionOptions.first()).toBeVisible({ timeout: 5_000 })
     const optionCount = await captionOptions.count()
     expect(optionCount).toBeGreaterThan(0)
@@ -231,7 +231,7 @@ test.describe('Video Playback @media', () => {
     const video = await navigateToMovieAndPlay(page, browserName, workerIndex)
     await openSettingsSubmenu(page, 'Audio')
 
-    const audioOptions = page.locator('media-audio-track-menu media-chrome-menu-item')
+    const audioOptions = page.locator('[data-testid="audio-track-item"]')
     await expect(audioOptions.first()).toBeVisible({ timeout: 5_000 })
     const audioCount = await audioOptions.count()
     expect(audioCount).toBeGreaterThanOrEqual(2)
@@ -244,22 +244,4 @@ test.describe('Video Playback @media', () => {
       expect(currentTime).toBeGreaterThan(0)
     }).toPass({ timeout: 30_000, intervals: [2_000, 3_000, 5_000] })
   })
-
-  test('Quality switching (HLS): quality options are listed and selectable', async ({ page, browserName }) => {
-    const video = await navigateToMovieAndPlay(page, browserName, workerIndex)
-    await openSettingsSubmenu(page, 'Quality')
-
-    const qualityOptions = page.locator('media-rendition-menu media-chrome-menu-item')
-    await expect(qualityOptions.first()).toBeVisible({ timeout: 5_000 })
-    const qualityCount = await qualityOptions.count()
-    expect(qualityCount).toBeGreaterThanOrEqual(2)
-
-    await qualityOptions.last().click()
-
-    // Verify playback continues after quality switch
-    await expect(async () => {
-      const currentTime = await video.evaluate((el: HTMLVideoElement) => el.currentTime)
-      expect(currentTime).toBeGreaterThan(0)
-    }).toPass({ timeout: 30_000, intervals: [2_000, 3_000, 5_000] })
-  })
 })
diff --git a/frontend/package.json b/frontend/package.json
index 2d85dd03..c84b0d6c 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -35,8 +35,6 @@
     "@xterm/addon-web-links": "^0.12.0",
     "@xterm/xterm": "^6.0.0",
     "common": "workspace:^",
-    "hls.js": "^1.6.15",
-    "media-chrome": "^4.18.0",
     "ollama": "^0.6.3",
     "path-to-regexp": "^8.3.0",
     "video.js": "8.23.8"
diff --git a/frontend/src/pages/movies/movie-player-v2/control-area.tsx b/frontend/src/pages/movies/movie-player-v2/control-area.tsx
deleted file mode 100644
index 09127e76..00000000
--- a/frontend/src/pages/movies/movie-player-v2/control-area.tsx
+++ /dev/null
@@ -1,124 +0,0 @@
-import { Shade, createComponent, styledShade } from '@furystack/shades'
-import type { IconDefinition } from '@furystack/shades-common-components'
-import { Button, Icon, icons, Input } from '@furystack/shades-common-components'
-import type { ObservableValue } from '@furystack/utils'
-
-const maximizeIcon: IconDefinition = {
-  name: 'Maximize',
-  description: 'Expand to full screen',
-  keywords: ['fullscreen', 'maximize', 'expand'],
-  category: 'Actions',
-  paths: [{ d: 'M8 3H5a2 2 0 00-2 2v3m18 0V5a2 2 0 00-2-2h-3m0 18h3a2 2 0 002-2v-3M3 16v3a2 2 0 002 2h3' }],
-}
-
-const minimizeIcon: IconDefinition = {
-  name: 'Minimize',
-  description: 'Exit full screen',
-  keywords: ['fullscreen', 'minimize', 'shrink'],
-  category: 'Actions',
-  paths: [{ d: 'M4 14h6v6m10-10h-6V4m0 6l7-7M3 21l7-7' }],
-}
-
-type ControlAreaProps = {
-  isPlaying: ObservableValue<boolean>
-  isFullScreen: ObservableValue<boolean>
-  isMuted: ObservableValue<boolean>
-  volume: ObservableValue<number>
-  watchedSeconds: ObservableValue<number>
-  lengthSeconds: number
-  seekTo: (seconds: number) => void
-}
-
-const ControlButton = styledShade(Button, {
-  fontSize: '2em',
-  padding: '.3em 1em',
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  lineHeight: '100%',
-})
-
-export const SoundControl = Shade<{
-  isMuted: ObservableValue<boolean>
-  volume: ObservableValue<number>
-}>({
-  customElementName: 'pirat-movie-player-v2-sound-control',
-  css: {
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-  },
-  render: ({ props, useObservable }) => {
-    const [isMuted, setIsMuted] = useObservable('isMuted', props.isMuted)
-    const [volume] = useObservable('volume', props.volume)
-
-    return (
-      <>
-        <ControlButton title={isMuted ? 'Unmute' : 'Mute'} onclick={() => setIsMuted(!isMuted)}>
-          {isMuted ? '🔇' : '🔊'}
-        </ControlButton>
-        <Input
-          type="range"
-          min="0"
-          max="100"
-          value={volume.toString()}
-          onchange={(e) => props.volume.setValue((e.target as HTMLInputElement).value as unknown as number)}
-        />
-      </>
-    )
-  },
-})
-
-export const ControlArea = Shade<ControlAreaProps>({
-  customElementName: 'pirat-movie-player-v2-control-area',
-  css: {
-    '& .control-bar': {
-      position: 'absolute',
-      bottom: '0',
-      background: 'linear-gradient(0deg, rgba(0,0,0,0.5) 0%, rgba(0,0,0,0.2) 80%, rgba(0,0,0,0) 100%)',
-      width: '100%',
-      height: '4em',
-      display: 'flex',
-      alignItems: 'center',
-      justifyContent: 'center',
-      zIndex: '2147483647',
-    },
-    '& .progress-bar': {
-      position: 'absolute',
-      top: '-15px',
-      left: '10px',
-      width: 'calc(100% - 20px)',
-    },
-  },
-  render: ({ props, useObservable }) => {
-    const [isPlaying, setIsPlaying] = useObservable('isPlaying', props.isPlaying)
-    const [progress] = useObservable('progress', props.watchedSeconds)
-    const [isFullScreen, setFullScreen] = useObservable('isFullScreen', props.isFullScreen)
-
-    return (
-      <div className="control-bar">
-        <Input
-          className="progress-bar"
-          type="range"
-          min="0"
-          max={props.lengthSeconds.toString()}
-          value={progress.toString()}
-          onTextChange={(e) => props.seekTo(parseInt(e, 10))}
-        />
-        {isPlaying ? (
-          <ControlButton title="Pause" onclick={() => setIsPlaying(false)}>
-            <Icon icon={icons.pause} />
-          </ControlButton>
-        ) : (
-          <ControlButton title="Play" onclick={() => setIsPlaying(true)}>
-            <Icon icon={icons.play} />
-          </ControlButton>
-        )}
-        <ControlButton title="Toggle full screen" onclick={() => setFullScreen(!isFullScreen)}>
-          {isFullScreen ? <Icon icon={minimizeIcon} /> : <Icon icon={maximizeIcon} />}
-        </ControlButton>
-        <SoundControl isMuted={props.isMuted} volume={props.volume} />
-      </div>
-    )
-  },
-})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/captions-button.tsx b/frontend/src/pages/movies/movie-player-v2/controls/captions-button.tsx
new file mode 100644
index 00000000..c89bba83
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/captions-button.tsx
@@ -0,0 +1,53 @@
+import { Shade, createComponent } from '@furystack/shades'
+import { Icon } from '@furystack/shades-common-components'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+import { captionsIcon } from './player-icons.js'
+
+type CaptionsButtonProps = {
+  mediaService: MoviePlayerService
+}
+
+export const CaptionsButton = Shade<CaptionsButtonProps>({
+  customElementName: 'pirat-player-captions-button',
+  render: ({ props, useObservable }) => {
+    const [activeTrack] = useObservable('activeTrack', props.mediaService.activeSubtitleTrack)
+
+    return (
+      <button
+        type="button"
+        data-testid="captions-button"
+        title={activeTrack !== null ? 'Disable captions' : 'Enable captions'}
+        onclick={() => {
+          const video = props.mediaService.videoElement
+          if (!video) return
+
+          const tracks = Array.from(video.textTracks)
+          const subtitleTracks = tracks.filter((t) => t.kind === 'subtitles' || t.kind === 'captions')
+
+          if (activeTrack !== null) {
+            for (const track of subtitleTracks) {
+              track.mode = 'hidden'
+            }
+            props.mediaService.activeSubtitleTrack.setValue(null)
+          } else if (subtitleTracks[0]) {
+            subtitleTracks[0].mode = 'showing'
+            props.mediaService.activeSubtitleTrack.setValue(0)
+          }
+        }}
+        style={{
+          background: 'none',
+          border: 'none',
+          color: 'inherit',
+          cursor: 'pointer',
+          padding: '6px',
+          display: 'flex',
+          alignItems: 'center',
+          opacity: activeTrack !== null ? '1' : '0.5',
+        }}
+      >
+        <Icon icon={captionsIcon} />
+      </button>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/control-bar.tsx b/frontend/src/pages/movies/movie-player-v2/controls/control-bar.tsx
new file mode 100644
index 00000000..828e4172
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/control-bar.tsx
@@ -0,0 +1,46 @@
+import type { RefObject } from '@furystack/shades'
+import { Shade, createComponent } from '@furystack/shades'
+import { cssVariableTheme } from '@furystack/shades-common-components'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+import { CaptionsButton } from './captions-button.js'
+import { FullscreenButton } from './fullscreen-button.js'
+import { PipButton } from './pip-button.js'
+import { PlayButton } from './play-button.js'
+import { SeekBar } from './seek-bar.js'
+import { SettingsMenu } from './settings-menu.js'
+import { TimeDisplay } from './time-display.js'
+import { VolumeControl } from './volume-control.js'
+
+type ControlBarProps = {
+  mediaService: MoviePlayerService
+  playerContainerRef: RefObject<HTMLElement>
+}
+
+export const ControlBar = Shade<ControlBarProps>({
+  customElementName: 'pirat-player-control-bar',
+  css: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '4px',
+    padding: '8px 12px',
+    background: `linear-gradient(transparent, ${cssVariableTheme.background.paper})`,
+    color: cssVariableTheme.text.primary,
+    width: '100%',
+    boxSizing: 'border-box',
+  },
+  render: ({ props }) => {
+    return (
+      <>
+        <PlayButton mediaService={props.mediaService} />
+        <TimeDisplay mediaService={props.mediaService} />
+        <SeekBar mediaService={props.mediaService} />
+        <VolumeControl mediaService={props.mediaService} />
+        <CaptionsButton mediaService={props.mediaService} />
+        <PipButton mediaService={props.mediaService} />
+        <FullscreenButton mediaService={props.mediaService} playerContainerRef={props.playerContainerRef} />
+        <SettingsMenu mediaService={props.mediaService} />
+      </>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/error-overlay.tsx b/frontend/src/pages/movies/movie-player-v2/controls/error-overlay.tsx
new file mode 100644
index 00000000..4a44d54b
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/error-overlay.tsx
@@ -0,0 +1,69 @@
+import { Shade, createComponent } from '@furystack/shades'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+
+type ErrorOverlayProps = {
+  mediaService: MoviePlayerService
+}
+
+export const ErrorOverlay = Shade<ErrorOverlayProps>({
+  customElementName: 'pirat-player-error-overlay',
+  render: ({ props, useState, useDisposable }) => {
+    const [error, setError] = useState<string | null>('error', null)
+
+    useDisposable('errorListener', () => {
+      const onError = (video: HTMLVideoElement) => {
+        const mediaError = video.error
+        if (mediaError) {
+          setError(`Playback error: ${mediaError.message || `code ${mediaError.code}`}`)
+        }
+      }
+
+      const video = props.mediaService.videoElement
+      if (video) {
+        const handler = () => onError(video)
+        video.addEventListener('error', handler)
+        return { [Symbol.dispose]: () => video.removeEventListener('error', handler) }
+      }
+
+      let cleanup: Disposable | null = null
+      const frameId = requestAnimationFrame(() => {
+        const deferredVideo = props.mediaService.videoElement
+        if (deferredVideo) {
+          const handler = () => onError(deferredVideo)
+          deferredVideo.addEventListener('error', handler)
+          cleanup = { [Symbol.dispose]: () => deferredVideo.removeEventListener('error', handler) }
+        }
+      })
+      return {
+        [Symbol.dispose]: () => {
+          cancelAnimationFrame(frameId)
+          cleanup?.[Symbol.dispose]()
+        },
+      }
+    })
+
+    if (!error) return <div />
+
+    return (
+      <div
+        data-testid="error-overlay"
+        style={{
+          position: 'absolute',
+          inset: '0',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          background: 'rgba(0, 0, 0, 0.7)',
+          color: 'white',
+          fontSize: '16px',
+          padding: '24px',
+          textAlign: 'center',
+          zIndex: '5',
+        }}
+      >
+        {error}
+      </div>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/fullscreen-button.tsx b/frontend/src/pages/movies/movie-player-v2/controls/fullscreen-button.tsx
new file mode 100644
index 00000000..f24e3d4a
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/fullscreen-button.tsx
@@ -0,0 +1,42 @@
+import type { RefObject } from '@furystack/shades'
+import { Shade, createComponent } from '@furystack/shades'
+import { Icon } from '@furystack/shades-common-components'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+import { fullscreenEnterIcon, fullscreenExitIcon } from './player-icons.js'
+
+type FullscreenButtonProps = {
+  mediaService: MoviePlayerService
+  playerContainerRef: RefObject<HTMLElement>
+}
+
+export const FullscreenButton = Shade<FullscreenButtonProps>({
+  customElementName: 'pirat-player-fullscreen-button',
+  render: ({ props, useObservable }) => {
+    const [isFullscreen] = useObservable('isFullscreen', props.mediaService.isFullscreen)
+
+    return (
+      <button
+        type="button"
+        data-testid="fullscreen-button"
+        title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
+        onclick={() => {
+          if (props.playerContainerRef.current) {
+            props.mediaService.toggleFullscreen(props.playerContainerRef.current)
+          }
+        }}
+        style={{
+          background: 'none',
+          border: 'none',
+          color: 'inherit',
+          cursor: 'pointer',
+          padding: '6px',
+          display: 'flex',
+          alignItems: 'center',
+        }}
+      >
+        <Icon icon={isFullscreen ? fullscreenExitIcon : fullscreenEnterIcon} />
+      </button>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/index.ts b/frontend/src/pages/movies/movie-player-v2/controls/index.ts
new file mode 100644
index 00000000..41b6992a
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/index.ts
@@ -0,0 +1,13 @@
+export { VideoContainer } from './video-container.js'
+export { ControlBar } from './control-bar.js'
+export { PlayButton } from './play-button.js'
+export { TimeDisplay } from './time-display.js'
+export { SeekBar } from './seek-bar.js'
+export { VolumeControl } from './volume-control.js'
+export { FullscreenButton } from './fullscreen-button.js'
+export { PipButton } from './pip-button.js'
+export { CaptionsButton } from './captions-button.js'
+export { SettingsMenu } from './settings-menu.js'
+export { LoadingOverlay } from './loading-overlay.js'
+export { ErrorOverlay } from './error-overlay.js'
+export { PosterOverlay } from './poster-overlay.js'
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/loading-overlay.tsx b/frontend/src/pages/movies/movie-player-v2/controls/loading-overlay.tsx
new file mode 100644
index 00000000..21c1ed44
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/loading-overlay.tsx
@@ -0,0 +1,44 @@
+import { Shade, createComponent } from '@furystack/shades'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+
+type LoadingOverlayProps = {
+  mediaService: MoviePlayerService
+}
+
+export const LoadingOverlay = Shade<LoadingOverlayProps>({
+  customElementName: 'pirat-player-loading-overlay',
+  render: ({ props, useObservable }) => {
+    const [isSwitching] = useObservable('isSwitching', props.mediaService.isSwitching)
+
+    if (!isSwitching) return <div />
+
+    return (
+      <div
+        data-testid="loading-overlay"
+        style={{
+          position: 'absolute',
+          inset: '0',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          background: 'rgba(0, 0, 0, 0.4)',
+          zIndex: '5',
+          pointerEvents: 'none',
+        }}
+      >
+        <div
+          style={{
+            width: '48px',
+            height: '48px',
+            border: '3px solid rgba(255, 255, 255, 0.3)',
+            borderTop: '3px solid white',
+            borderRadius: '50%',
+            animation: 'spin 0.8s linear infinite',
+          }}
+        />
+        <style>{`@keyframes spin { to { transform: rotate(360deg); } }`}</style>
+      </div>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/pip-button.tsx b/frontend/src/pages/movies/movie-player-v2/controls/pip-button.tsx
new file mode 100644
index 00000000..8f308ebc
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/pip-button.tsx
@@ -0,0 +1,34 @@
+import { Shade, createComponent } from '@furystack/shades'
+import { Icon } from '@furystack/shades-common-components'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+import { pipIcon } from './player-icons.js'
+
+type PipButtonProps = {
+  mediaService: MoviePlayerService
+}
+
+export const PipButton = Shade<PipButtonProps>({
+  customElementName: 'pirat-player-pip-button',
+  render: ({ props }) => {
+    return (
+      <button
+        type="button"
+        data-testid="pip-button"
+        title="Picture in Picture"
+        onclick={() => props.mediaService.togglePip()}
+        style={{
+          background: 'none',
+          border: 'none',
+          color: 'inherit',
+          cursor: 'pointer',
+          padding: '6px',
+          display: 'flex',
+          alignItems: 'center',
+        }}
+      >
+        <Icon icon={pipIcon} />
+      </button>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/play-button.tsx b/frontend/src/pages/movies/movie-player-v2/controls/play-button.tsx
new file mode 100644
index 00000000..bcd81f24
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/play-button.tsx
@@ -0,0 +1,36 @@
+import { Shade, createComponent } from '@furystack/shades'
+import { Icon, icons } from '@furystack/shades-common-components'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+
+type PlayButtonProps = {
+  mediaService: MoviePlayerService
+}
+
+export const PlayButton = Shade<PlayButtonProps>({
+  customElementName: 'pirat-player-play-button',
+  render: ({ props, useObservable }) => {
+    const [isPlaying] = useObservable('isPlaying', props.mediaService.isPlaying)
+
+    return (
+      <button
+        type="button"
+        data-testid="play-button"
+        title={isPlaying ? 'Pause' : 'Play'}
+        onclick={() => props.mediaService.togglePlay()}
+        style={{
+          background: 'none',
+          border: 'none',
+          color: 'inherit',
+          cursor: 'pointer',
+          padding: '6px',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+      >
+        <Icon icon={isPlaying ? icons.pause : icons.play} />
+      </button>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/player-icons.ts b/frontend/src/pages/movies/movie-player-v2/controls/player-icons.ts
new file mode 100644
index 00000000..3d7d8f06
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/player-icons.ts
@@ -0,0 +1,44 @@
+import type { IconDefinition } from '@furystack/shades-common-components'
+
+export const volumeHighIcon: IconDefinition = {
+  paths: [{ d: 'M11 5L6 9H2v6h4l5 4V5z' }, { d: 'M19.07 4.93a10 10 0 010 14.14M15.54 8.46a5 5 0 010 7.07' }],
+}
+
+export const volumeLowIcon: IconDefinition = {
+  paths: [{ d: 'M11 5L6 9H2v6h4l5 4V5z' }, { d: 'M15.54 8.46a5 5 0 010 7.07' }],
+}
+
+export const volumeMuteIcon: IconDefinition = {
+  paths: [{ d: 'M11 5L6 9H2v6h4l5 4V5z' }, { d: 'M23 9l-6 6M17 9l6 6' }],
+}
+
+export const fullscreenEnterIcon: IconDefinition = {
+  paths: [{ d: 'M8 3H5a2 2 0 00-2 2v3m18 0V5a2 2 0 00-2-2h-3m0 18h3a2 2 0 002-2v-3M3 16v3a2 2 0 002 2h3' }],
+}
+
+export const fullscreenExitIcon: IconDefinition = {
+  paths: [{ d: 'M4 14h6v6m10-10h-6V4m0 6l7-7M3 21l7-7' }],
+}
+
+export const pipIcon: IconDefinition = {
+  paths: [
+    { d: 'M2 4.5A2.5 2.5 0 014.5 2h15A2.5 2.5 0 0122 4.5v15a2.5 2.5 0 01-2.5 2.5h-15A2.5 2.5 0 012 19.5v-15z' },
+    { d: 'M12 13.5a1 1 0 011-1h6a1 1 0 011 1V18a1 1 0 01-1 1h-6a1 1 0 01-1-1v-4.5z' },
+  ],
+}
+
+export const captionsIcon: IconDefinition = {
+  paths: [
+    { d: 'M2 6a2 2 0 012-2h16a2 2 0 012 2v12a2 2 0 01-2 2H4a2 2 0 01-2-2V6z' },
+    { d: 'M10 9.5a2.5 2.5 0 00-4.5 0v5a2.5 2.5 0 004.5 0M18.5 9.5a2.5 2.5 0 00-4.5 0v5a2.5 2.5 0 004.5 0' },
+  ],
+}
+
+export const gearIcon: IconDefinition = {
+  paths: [
+    {
+      d: 'M12.22 2h-.44a2 2 0 00-2 2v.18a2 2 0 01-1 1.73l-.43.25a2 2 0 01-2 0l-.15-.08a2 2 0 00-2.73.73l-.22.38a2 2 0 00.73 2.73l.15.1a2 2 0 011 1.72v.51a2 2 0 01-1 1.74l-.15.09a2 2 0 00-.73 2.73l.22.38a2 2 0 002.73.73l.15-.08a2 2 0 012 0l.43.25a2 2 0 011 1.73V20a2 2 0 002 2h.44a2 2 0 002-2v-.18a2 2 0 011-1.73l.43-.25a2 2 0 012 0l.15.08a2 2 0 002.73-.73l.22-.39a2 2 0 00-.73-2.73l-.15-.08a2 2 0 01-1-1.74v-.5a2 2 0 011-1.74l.15-.09a2 2 0 00.73-2.73l-.22-.38a2 2 0 00-2.73-.73l-.15.08a2 2 0 01-2 0l-.43-.25a2 2 0 01-1-1.73V4a2 2 0 00-2-2z',
+    },
+    { d: 'M12 15a3 3 0 100-6 3 3 0 000 6z' },
+  ],
+}
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/poster-overlay.tsx b/frontend/src/pages/movies/movie-player-v2/controls/poster-overlay.tsx
new file mode 100644
index 00000000..6946fe7d
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/poster-overlay.tsx
@@ -0,0 +1,34 @@
+import { Shade, createComponent } from '@furystack/shades'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+
+type PosterOverlayProps = {
+  mediaService: MoviePlayerService
+  posterUrl?: string
+}
+
+export const PosterOverlay = Shade<PosterOverlayProps>({
+  customElementName: 'pirat-player-poster-overlay',
+  render: ({ props, useObservable }) => {
+    const [isPlaying] = useObservable('isPlaying', props.mediaService.isPlaying)
+    const [progress] = useObservable('progress', props.mediaService.progress)
+
+    if (isPlaying || progress > 0 || !props.posterUrl) return <div />
+
+    return (
+      <div
+        data-testid="poster-overlay"
+        style={{
+          position: 'absolute',
+          inset: '0',
+          backgroundImage: `url(${props.posterUrl})`,
+          backgroundSize: 'cover',
+          backgroundPosition: 'center',
+          zIndex: '1',
+          cursor: 'pointer',
+        }}
+        onclick={() => props.mediaService.togglePlay()}
+      />
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/seek-bar.tsx b/frontend/src/pages/movies/movie-player-v2/controls/seek-bar.tsx
new file mode 100644
index 00000000..fde57607
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/seek-bar.tsx
@@ -0,0 +1,84 @@
+import { Shade, createComponent } from '@furystack/shades'
+import { cssVariableTheme } from '@furystack/shades-common-components'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+
+type SeekBarProps = {
+  mediaService: MoviePlayerService
+}
+
+export const SeekBar = Shade<SeekBarProps>({
+  customElementName: 'pirat-player-seek-bar',
+  css: {
+    display: 'flex',
+    alignItems: 'center',
+    flex: '1',
+    position: 'relative',
+    height: '20px',
+    cursor: 'pointer',
+    '& .seek-track': {
+      position: 'absolute',
+      width: '100%',
+      height: '4px',
+      borderRadius: '2px',
+      background: 'rgba(255, 255, 255, 0.2)',
+      overflow: 'hidden',
+    },
+    '& .seek-buffered': {
+      position: 'absolute',
+      height: '100%',
+      background: 'rgba(255, 255, 255, 0.35)',
+    },
+    '& .seek-played': {
+      position: 'absolute',
+      height: '100%',
+      background: cssVariableTheme.palette.primary.main,
+    },
+    '& input[type="range"]': {
+      position: 'absolute',
+      width: '100%',
+      height: '100%',
+      margin: '0',
+      opacity: '0',
+      cursor: 'pointer',
+      zIndex: '1',
+    },
+  },
+  render: ({ props, useObservable }) => {
+    const [progress] = useObservable('progress', props.mediaService.progress)
+    const [duration] = useObservable('duration', props.mediaService.duration)
+    const [buffered] = useObservable('buffered', props.mediaService.buffered)
+
+    const playedPercent = duration > 0 ? (progress / duration) * 100 : 0
+
+    let bufferedPercent = 0
+    if (buffered && buffered.length > 0 && duration > 0) {
+      const end = buffered.end(buffered.length - 1)
+      const absoluteBuffered = props.mediaService.streamTimeToAbsolute(end)
+      bufferedPercent = (absoluteBuffered / duration) * 100
+    }
+
+    return (
+      <div data-testid="seek-bar">
+        <div className="seek-track">
+          <div className="seek-buffered" style={{ width: `${Math.min(bufferedPercent, 100)}%` }} />
+          <div className="seek-played" style={{ width: `${Math.min(playedPercent, 100)}%` }} />
+        </div>
+        <input
+          type="range"
+          min="0"
+          max={duration.toString()}
+          value={progress.toString()}
+          step="1"
+          oninput={(ev) => {
+            const target = ev.currentTarget as HTMLInputElement
+            const targetTime = parseFloat(target.value)
+            if (!isNaN(targetTime)) {
+              props.mediaService.seekToTime(targetTime)
+            }
+          }}
+        />
+      </div>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx b/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx
new file mode 100644
index 00000000..653abc37
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx
@@ -0,0 +1,243 @@
+import { Shade, createComponent } from '@furystack/shades'
+import { Icon, cssVariableTheme } from '@furystack/shades-common-components'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+import { gearIcon } from './player-icons.js'
+
+type SettingsMenuProps = {
+  mediaService: MoviePlayerService
+}
+
+type SubmenuId = 'speed' | 'audio' | 'captions' | null
+
+const SPEED_OPTIONS = [0.5, 0.75, 1, 1.25, 1.5, 2] as const
+
+export const SettingsMenu = Shade<SettingsMenuProps>({
+  customElementName: 'pirat-player-settings-menu',
+  css: {
+    position: 'relative',
+    '& .settings-panel': {
+      position: 'absolute',
+      bottom: '100%',
+      right: '0',
+      marginBottom: '8px',
+      background: cssVariableTheme.background.paper,
+      borderRadius: '8px',
+      border: `1px solid ${cssVariableTheme.action.subtleBorder}`,
+      boxShadow: cssVariableTheme.shadows.lg,
+      minWidth: '200px',
+      maxHeight: '300px',
+      overflowY: 'auto',
+      zIndex: '10',
+    },
+    '& .menu-item': {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+      padding: '10px 16px',
+      cursor: 'pointer',
+      fontSize: '14px',
+      color: cssVariableTheme.text.primary,
+      border: 'none',
+      background: 'none',
+      width: '100%',
+      textAlign: 'left',
+    },
+    '& .menu-item:hover': {
+      background: cssVariableTheme.action.hoverBackground,
+    },
+    '& .menu-item.active': {
+      color: cssVariableTheme.palette.primary.main,
+    },
+    '& .menu-header': {
+      display: 'flex',
+      alignItems: 'center',
+      gap: '8px',
+      padding: '10px 16px',
+      borderBottom: `1px solid ${cssVariableTheme.action.subtleBorder}`,
+      fontSize: '14px',
+      fontWeight: 'bold',
+      color: cssVariableTheme.text.primary,
+      cursor: 'pointer',
+      background: 'none',
+      border: 'none',
+      width: '100%',
+      textAlign: 'left',
+    },
+  },
+  render: ({ props, useObservable, useState }) => {
+    const [isOpen, setIsOpen] = useState('isOpen', false)
+    const [activeSubmenu, setActiveSubmenu] = useState<SubmenuId>('activeSubmenu', null)
+    const [playbackRate] = useObservable('playbackRate', props.mediaService.playbackRate)
+    const [activeTrack] = useObservable('activeTrack', props.mediaService.activeSubtitleTrack)
+
+    const audioTracks = props.mediaService.getAudioTrackInfoFromPlaybackInfo()
+    const ffprobeAudioTracks =
+      audioTracks.length === 0
+        ? props.mediaService.getAudioTracks().map((t) => ({
+            index: t.id,
+            label:
+              (t.stream.tags as Record<string, string>)?.title ||
+              (t.stream.tags as Record<string, string>)?.language ||
+              'Audio Track',
+            language: (t.stream.tags as Record<string, string>)?.language || 'unknown',
+            codecName: t.codecName ?? 'unknown',
+            channels: t.stream.channels ?? 2,
+            isDefault: t.stream.disposition?.default === 1,
+          }))
+        : []
+    const allAudioTracks = audioTracks.length > 0 ? audioTracks : ffprobeAudioTracks
+
+    const subtitleTracks = props.mediaService.getSubtitleTrackInfoFromPlaybackInfo()
+
+    const toggleMenu = () => {
+      if (isOpen) {
+        setIsOpen(false)
+        setActiveSubmenu(null)
+      } else {
+        setIsOpen(true)
+      }
+    }
+
+    const renderMainMenu = () => (
+      <div className="settings-panel" data-testid="settings-menu-panel">
+        <button className="menu-item" data-testid="settings-menu-item" onclick={() => setActiveSubmenu('speed')}>
+          <span>Speed</span>
+          <span style={{ opacity: '0.6' }}>{playbackRate === 1 ? 'Normal' : `${playbackRate}x`}</span>
+        </button>
+        {allAudioTracks.length > 1 && (
+          <button className="menu-item" data-testid="settings-menu-item" onclick={() => setActiveSubmenu('audio')}>
+            <span>Audio</span>
+          </button>
+        )}
+        {subtitleTracks.length > 0 && (
+          <button className="menu-item" data-testid="settings-menu-item" onclick={() => setActiveSubmenu('captions')}>
+            <span>Captions</span>
+            <span style={{ opacity: '0.6' }}>{activeTrack !== null ? 'On' : 'Off'}</span>
+          </button>
+        )}
+      </div>
+    )
+
+    const renderSpeedSubmenu = () => (
+      <div className="settings-panel" data-testid="settings-menu-panel">
+        <button className="menu-header" onclick={() => setActiveSubmenu(null)}>
+          ← Speed
+        </button>
+        {SPEED_OPTIONS.map((rate) => (
+          <button
+            className={`menu-item${playbackRate === rate ? ' active' : ''}`}
+            onclick={() => {
+              props.mediaService.setPlaybackRate(rate)
+              setIsOpen(false)
+              setActiveSubmenu(null)
+            }}
+          >
+            {rate === 1 ? 'Normal' : `${rate}x`}
+          </button>
+        ))}
+      </div>
+    )
+
+    const renderAudioSubmenu = () => (
+      <div className="settings-panel" data-testid="settings-menu-panel">
+        <button className="menu-header" onclick={() => setActiveSubmenu(null)}>
+          ← Audio
+        </button>
+        {allAudioTracks.map((track, index) => (
+          <button
+            className={`menu-item${props.mediaService.audioTrackId.getValue() === track.index ? ' active' : ''}`}
+            data-testid="audio-track-item"
+            onclick={() => {
+              void props.mediaService.switchAudioTrack(track.index)
+              setIsOpen(false)
+              setActiveSubmenu(null)
+            }}
+          >
+            {track.label || track.language || `Audio Track ${index + 1}`}
+          </button>
+        ))}
+      </div>
+    )
+
+    const renderCaptionsSubmenu = () => (
+      <div className="settings-panel" data-testid="settings-menu-panel">
+        <button className="menu-header" onclick={() => setActiveSubmenu(null)}>
+          ← Captions
+        </button>
+        <button
+          className={`menu-item${activeTrack === null ? ' active' : ''}`}
+          data-testid="caption-track-item"
+          onclick={() => {
+            const video = props.mediaService.videoElement
+            if (video) {
+              for (const track of Array.from(video.textTracks)) {
+                track.mode = 'hidden'
+              }
+            }
+            props.mediaService.activeSubtitleTrack.setValue(null)
+            setIsOpen(false)
+            setActiveSubmenu(null)
+          }}
+        >
+          Off
+        </button>
+        {subtitleTracks.map((track, index) => (
+          <button
+            className={`menu-item${activeTrack === index ? ' active' : ''}`}
+            data-testid="caption-track-item"
+            onclick={() => {
+              const video = props.mediaService.videoElement
+              if (video) {
+                const textTracks = Array.from(video.textTracks).filter(
+                  (t) => t.kind === 'subtitles' || t.kind === 'captions',
+                )
+                for (const t of textTracks) {
+                  t.mode = 'hidden'
+                }
+                if (textTracks[index]) {
+                  textTracks[index].mode = 'showing'
+                }
+              }
+              props.mediaService.activeSubtitleTrack.setValue(index)
+              setIsOpen(false)
+              setActiveSubmenu(null)
+            }}
+          >
+            {track.label || track.language || `Track ${index + 1}`}
+          </button>
+        ))}
+      </div>
+    )
+
+    return (
+      <>
+        <button
+          type="button"
+          data-testid="settings-menu-button"
+          title="Settings"
+          onclick={toggleMenu}
+          style={{
+            background: 'none',
+            border: 'none',
+            color: 'inherit',
+            cursor: 'pointer',
+            padding: '6px',
+            display: 'flex',
+            alignItems: 'center',
+          }}
+        >
+          <Icon icon={gearIcon} />
+        </button>
+        {isOpen && (
+          <>
+            {activeSubmenu === null && renderMainMenu()}
+            {activeSubmenu === 'speed' && renderSpeedSubmenu()}
+            {activeSubmenu === 'audio' && renderAudioSubmenu()}
+            {activeSubmenu === 'captions' && renderCaptionsSubmenu()}
+          </>
+        )}
+      </>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/time-display.tsx b/frontend/src/pages/movies/movie-player-v2/controls/time-display.tsx
new file mode 100644
index 00000000..2ade9a18
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/time-display.tsx
@@ -0,0 +1,39 @@
+import { Shade, createComponent } from '@furystack/shades'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+
+type TimeDisplayProps = {
+  mediaService: MoviePlayerService
+}
+
+const formatTime = (seconds: number): string => {
+  if (!isFinite(seconds) || seconds < 0) return '0:00'
+  const h = Math.floor(seconds / 3600)
+  const m = Math.floor((seconds % 3600) / 60)
+  const s = Math.floor(seconds % 60)
+  const pad = (n: number) => n.toString().padStart(2, '0')
+  return h > 0 ? `${h}:${pad(m)}:${pad(s)}` : `${m}:${pad(s)}`
+}
+
+export const TimeDisplay = Shade<TimeDisplayProps>({
+  customElementName: 'pirat-player-time-display',
+  render: ({ props, useObservable }) => {
+    const [progress] = useObservable('progress', props.mediaService.progress)
+    const [duration] = useObservable('duration', props.mediaService.duration)
+
+    return (
+      <span
+        data-testid="time-display"
+        style={{
+          fontSize: '13px',
+          fontVariantNumeric: 'tabular-nums',
+          whiteSpace: 'nowrap',
+          padding: '0 8px',
+          userSelect: 'none',
+        }}
+      >
+        {formatTime(progress)} / {formatTime(duration)}
+      </span>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/video-container.tsx b/frontend/src/pages/movies/movie-player-v2/controls/video-container.tsx
new file mode 100644
index 00000000..5c0199a4
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/video-container.tsx
@@ -0,0 +1,155 @@
+import type { RefObject } from '@furystack/shades'
+import { Shade, createComponent } from '@furystack/shades'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+import { ControlBar } from './control-bar.js'
+import { ErrorOverlay } from './error-overlay.js'
+import { LoadingOverlay } from './loading-overlay.js'
+
+type VideoContainerProps = {
+  mediaService: MoviePlayerService
+  playerContainerRef: RefObject<HTMLElement>
+}
+
+const IDLE_TIMEOUT_MS = 3000
+const SEEK_STEP_SECONDS = 10
+
+export const VideoContainer = Shade<VideoContainerProps>({
+  customElementName: 'pirat-player-video-container',
+  css: {
+    display: 'block',
+    position: 'absolute',
+    inset: '0',
+    '& .controls-wrapper': {
+      position: 'absolute',
+      bottom: '0',
+      left: '0',
+      right: '0',
+      transition: 'opacity 0.3s ease',
+      zIndex: '10',
+    },
+    '& .controls-wrapper.hidden': {
+      opacity: '0',
+      pointerEvents: 'none',
+    },
+  },
+  render: ({ props, useDisposable, useState, useRef }) => {
+    const containerRef = useRef<HTMLElement>('container')
+    const [controlsHidden, setControlsHidden] = useState('controlsHidden', false)
+
+    useDisposable('idleTimer', () => {
+      let timerId: ReturnType<typeof setTimeout> | null = null
+
+      const resetTimer = () => {
+        setControlsHidden(false)
+        if (timerId) clearTimeout(timerId)
+        timerId = setTimeout(() => setControlsHidden(true), IDLE_TIMEOUT_MS)
+      }
+
+      const onMouseLeave = () => {
+        setControlsHidden(true)
+        if (timerId) {
+          clearTimeout(timerId)
+          timerId = null
+        }
+      }
+
+      const attach = (container: HTMLElement) => {
+        container.addEventListener('mousemove', resetTimer)
+        container.addEventListener('mouseleave', onMouseLeave)
+        container.addEventListener('mouseenter', resetTimer)
+        resetTimer()
+      }
+
+      const container = containerRef.current
+      if (container) {
+        attach(container)
+      } else {
+        const frameId = requestAnimationFrame(() => {
+          const deferred = containerRef.current
+          if (deferred) attach(deferred)
+        })
+        return {
+          [Symbol.dispose]: () => {
+            cancelAnimationFrame(frameId)
+            if (timerId) clearTimeout(timerId)
+          },
+        }
+      }
+
+      return {
+        [Symbol.dispose]: () => {
+          if (timerId) clearTimeout(timerId)
+          if (container) {
+            container.removeEventListener('mousemove', resetTimer)
+            container.removeEventListener('mouseleave', onMouseLeave)
+            container.removeEventListener('mouseenter', resetTimer)
+          }
+        },
+      }
+    })
+
+    useDisposable('keyboardShortcuts', () => {
+      const attach = (container: HTMLElement) => {
+        const onKeyDown = (ev: KeyboardEvent) => {
+          switch (ev.key) {
+            case ' ':
+            case 'k':
+              ev.preventDefault()
+              props.mediaService.togglePlay()
+              break
+            case 'ArrowLeft':
+              ev.preventDefault()
+              props.mediaService.seekToTime(Math.max(0, props.mediaService.progress.getValue() - SEEK_STEP_SECONDS))
+              break
+            case 'ArrowRight':
+              ev.preventDefault()
+              props.mediaService.seekToTime(props.mediaService.progress.getValue() + SEEK_STEP_SECONDS)
+              break
+            case 'm':
+            case 'M':
+              ev.preventDefault()
+              props.mediaService.setMuted(!props.mediaService.isMuted.getValue())
+              break
+            case 'f':
+            case 'F':
+              ev.preventDefault()
+              if (props.playerContainerRef.current) {
+                props.mediaService.toggleFullscreen(props.playerContainerRef.current)
+              }
+              break
+            default:
+              break
+          }
+        }
+        container.addEventListener('keydown', onKeyDown)
+        return { [Symbol.dispose]: () => container.removeEventListener('keydown', onKeyDown) }
+      }
+
+      const container = containerRef.current
+      if (container) return attach(container)
+
+      let cleanup: Disposable | null = null
+      const frameId = requestAnimationFrame(() => {
+        const deferred = containerRef.current
+        if (deferred) cleanup = attach(deferred)
+      })
+      return {
+        [Symbol.dispose]: () => {
+          cancelAnimationFrame(frameId)
+          cleanup?.[Symbol.dispose]()
+        },
+      }
+    })
+
+    return (
+      <div ref={containerRef} tabIndex={0} style={{ outline: 'none', width: '100%', height: '100%' }}>
+        <LoadingOverlay mediaService={props.mediaService} />
+        <ErrorOverlay mediaService={props.mediaService} />
+        <div className={`controls-wrapper${controlsHidden ? ' hidden' : ''}`}>
+          <ControlBar mediaService={props.mediaService} playerContainerRef={props.playerContainerRef} />
+        </div>
+      </div>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/volume-control.tsx b/frontend/src/pages/movies/movie-player-v2/controls/volume-control.tsx
new file mode 100644
index 00000000..8d2eae39
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/volume-control.tsx
@@ -0,0 +1,72 @@
+import { Shade, createComponent } from '@furystack/shades'
+import { Icon } from '@furystack/shades-common-components'
+
+import type { MoviePlayerService } from '../movie-player-service.js'
+import { volumeHighIcon, volumeLowIcon, volumeMuteIcon } from './player-icons.js'
+
+type VolumeControlProps = {
+  mediaService: MoviePlayerService
+}
+
+export const VolumeControl = Shade<VolumeControlProps>({
+  customElementName: 'pirat-player-volume-control',
+  css: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '4px',
+    '& input[type="range"]': {
+      width: '80px',
+      cursor: 'pointer',
+      accentColor: 'white',
+    },
+  },
+  render: ({ props, useObservable }) => {
+    const [isMuted] = useObservable('isMuted', props.mediaService.isMuted)
+    const [volume] = useObservable('volume', props.mediaService.volume)
+
+    const getVolumeIcon = () => {
+      if (isMuted || volume === 0) return volumeMuteIcon
+      if (volume < 0.5) return volumeLowIcon
+      return volumeHighIcon
+    }
+
+    return (
+      <>
+        <button
+          type="button"
+          data-testid="mute-button"
+          title={isMuted ? 'Unmute' : 'Mute'}
+          onclick={() => props.mediaService.setMuted(!isMuted)}
+          style={{
+            background: 'none',
+            border: 'none',
+            color: 'inherit',
+            cursor: 'pointer',
+            padding: '6px',
+            display: 'flex',
+            alignItems: 'center',
+          }}
+        >
+          <Icon icon={getVolumeIcon()} />
+        </button>
+        <input
+          type="range"
+          min="0"
+          max="1"
+          step="0.05"
+          value={isMuted ? '0' : volume.toString()}
+          oninput={(ev) => {
+            const target = ev.currentTarget as HTMLInputElement
+            const val = parseFloat(target.value)
+            if (!isNaN(val)) {
+              if (val > 0 && isMuted) {
+                props.mediaService.setMuted(false)
+              }
+              props.mediaService.setVolume(val)
+            }
+          }}
+        />
+      </>
+    )
+  },
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/media-chrome.ts b/frontend/src/pages/movies/movie-player-v2/media-chrome.ts
deleted file mode 100644
index 16922ef6..00000000
--- a/frontend/src/pages/movies/movie-player-v2/media-chrome.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-import type { PartialElement } from '@furystack/shades'
-import 'media-chrome/all'
-import type {
-  MediaAirplayButton,
-  MediaCaptionsButton,
-  MediaCaptionsMenu,
-  MediaCastButton,
-  MediaChromeButton,
-  MediaChromeDialog,
-  MediaChromeMenu,
-  MediaChromeMenuButton,
-  MediaChromeMenuItem,
-  MediaChromeRange,
-  MediaContainer,
-  MediaControlBar,
-  MediaController,
-  MediaDurationDisplay,
-  MediaErrorDialog,
-  MediaFullscreenButton,
-  MediaGestureReceiver,
-  MediaLiveButton,
-  MediaLoadingIndicator,
-  MediaMuteButton,
-  MediaPipButton,
-  MediaPlaybackRateButton,
-  MediaPlayButton,
-  MediaPosterImage,
-  MediaPreviewChapterDisplay,
-  MediaPreviewThumbnail,
-  MediaPreviewTimeDisplay,
-  MediaRenditionMenu,
-  MediaRenditionMenuButton,
-  MediaSeekBackwardButton,
-  MediaSeekForwardButton,
-  MediaSettingsMenu,
-  MediaSettingsMenuButton,
-  MediaSettingsMenuItem,
-  MediaTextDisplay,
-  MediaTimeDisplay,
-  MediaTimeRange,
-  MediaTooltip,
-  MediaVolumeRange,
-} from 'media-chrome/all'
-
-declare global {
-  // eslint-disable-next-line @typescript-eslint/no-namespace
-  namespace JSX {
-    interface IntrinsicElements {
-      'media-controller': PartialElement<MediaController>
-      'media-play-button': PartialElement<MediaPlayButton>
-      'media-airplay-button': PartialElement<MediaAirplayButton>
-      'media-captions-button': PartialElement<MediaCaptionsButton>
-      'media-cast-button': PartialElement<MediaCastButton>
-      'media-chrome-button': PartialElement<MediaChromeButton>
-      'media-chrome-dialog': PartialElement<MediaChromeDialog>
-      'media-chrome-range': PartialElement<MediaChromeRange>
-      'media-container': PartialElement<MediaContainer>
-      'media-control-bar': PartialElement<MediaControlBar>
-      'media-chrome': PartialElement<MediaController>
-      'media-duration-display': PartialElement<MediaDurationDisplay>
-      'media-error-dialog': PartialElement<MediaErrorDialog>
-      'media-fullscreen-button': PartialElement<MediaFullscreenButton>
-      'media-gesture-receiver': PartialElement<MediaGestureReceiver>
-      'media-live-button': PartialElement<MediaLiveButton>
-      'media-loading-indicator': PartialElement<MediaLoadingIndicator>
-      'media-mute-button': PartialElement<MediaMuteButton>
-      'media-pip-button': PartialElement<MediaPipButton>
-      'media-poster-image': PartialElement<MediaPosterImage>
-      'media-playback-rate-button': PartialElement<MediaPlaybackRateButton>
-      'media-preview-chapter-display': PartialElement<MediaPreviewChapterDisplay>
-      'media-preview-thumbnail': PartialElement<MediaPreviewThumbnail>
-      'media-preview-time-display': PartialElement<MediaPreviewTimeDisplay>
-      'media-seek-backward-button': PartialElement<MediaSeekBackwardButton>
-      'media-seek-forward-button': PartialElement<MediaSeekForwardButton>
-      'media-text-display': PartialElement<MediaTextDisplay>
-      'media-time-display': PartialElement<MediaTimeDisplay>
-      'media-time-range': PartialElement<MediaTimeRange>
-      'media-tooltip': PartialElement<MediaTooltip>
-      'media-volume-range': PartialElement<MediaVolumeRange>
-      'media-chrome-menu': PartialElement<MediaChromeMenu>
-      'media-chrome-menu-button': PartialElement<MediaChromeMenuButton>
-      'media-chrome-menu-item': PartialElement<MediaChromeMenuItem>
-      'media-captions-menu': PartialElement<MediaCaptionsMenu>
-      'media-settings-menu': PartialElement<MediaSettingsMenu>
-      'media-settings-menu-button': PartialElement<MediaSettingsMenuButton>
-      'media-settings-menu-item': PartialElement<MediaSettingsMenuItem>
-      'media-rendition-menu': PartialElement<MediaRenditionMenu>
-      'media-rendition-menu-button': PartialElement<MediaRenditionMenuButton>
-      'media-audio-track-menu': PartialElement<MediaSettingsMenuItem>
-      'media-playback-rate-menu': PartialElement<MediaSettingsMenuItem>
-    }
-  }
-}
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
index 339b781c..3ce4df05 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.spec.ts
@@ -3,23 +3,6 @@ import { describe, expect, it, vi, beforeEach } from 'vitest'
 import { usingAsync } from '@furystack/utils'
 import { MoviePlayerService, videoCodecs, audioCodecs } from './movie-player-service.js'
 
-vi.mock('hls.js', () => {
-  class MockHls {
-    on = vi.fn()
-    loadSource = vi.fn()
-    attachMedia = vi.fn()
-    destroy = vi.fn()
-    levels: unknown[] = []
-    currentLevel = -1
-  }
-  Object.assign(MockHls, {
-    isSupported: () => true,
-    Events: { ERROR: 'hlsError', MANIFEST_PARSED: 'hlsManifestParsed', DESTROYING: 'hlsDestroying' },
-    ErrorTypes: { NETWORK_ERROR: 'networkError', MEDIA_ERROR: 'mediaError' },
-  })
-  return { default: MockHls }
-})
-
 const mockLogger = {
   verbose: vi.fn().mockResolvedValue(undefined),
   error: vi.fn().mockResolvedValue(undefined),
@@ -84,7 +67,6 @@ describe('MoviePlayerService', () => {
         expect(service.audioTrackId.getValue()).toBe(0)
         expect(service.playbackMode.getValue()).toBe('transcode')
         expect(service.progress.getValue()).toBe(0)
-        expect(service.resolution.getValue()).toBeUndefined()
       },
     )
   })
@@ -236,6 +218,15 @@ describe('MoviePlayerService', () => {
       src: '',
       currentTime: 0,
       canPlayType: vi.fn().mockReturnValue(''),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      volume: 1,
+      muted: false,
+      paused: true,
+      playbackRate: 1,
+      duration: 0,
+      buffered: { length: 0, start: vi.fn(), end: vi.fn() },
+      textTracks: [],
     } as unknown as HTMLVideoElement
     service.attachToVideo(mockVideo)
 
@@ -262,120 +253,6 @@ describe('audioCodecs', () => {
   })
 })
 
-describe('switchResolution', () => {
-  let api: ReturnType<typeof createMockApi>
-
-  beforeEach(() => {
-    api = createMockApi()
-    vi.clearAllMocks()
-  })
-
-  it('should force transcode mode when a specific resolution is selected', async () => {
-    await usingAsync(
-      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
-      async (service) => {
-        await vi.waitFor(() => {
-          expect(service.playbackInfo.getValue()).not.toBeNull()
-        })
-
-        expect(service.playbackMode.getValue()).toBe('remux')
-
-        await service.switchResolution('720p')
-        expect(service.resolution.getValue()).toBe('720p')
-        expect(service.playbackMode.getValue()).toBe('transcode')
-      },
-    )
-  })
-
-  it('should restore original playback mode when switching to Auto', async () => {
-    await usingAsync(
-      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
-      async (service) => {
-        await vi.waitFor(() => {
-          expect(service.playbackInfo.getValue()).not.toBeNull()
-        })
-
-        expect(service.playbackMode.getValue()).toBe('remux')
-
-        await service.switchResolution('720p')
-        expect(service.playbackMode.getValue()).toBe('transcode')
-
-        await service.switchResolution(undefined)
-        expect(service.resolution.getValue()).toBeUndefined()
-        expect(service.playbackMode.getValue()).toBe('remux')
-      },
-    )
-  })
-
-  it('should preserve playback progress across resolution switches', async () => {
-    await usingAsync(
-      new MoviePlayerService(mockFile, mockFfprobe, api as never, 50, mockLogger as never),
-      async (service) => {
-        await vi.waitFor(() => {
-          expect(service.playbackInfo.getValue()).not.toBeNull()
-        })
-
-        const mockVideo = {
-          currentTime: 75,
-          addEventListener: vi.fn(),
-          removeEventListener: vi.fn(),
-        } as unknown as HTMLVideoElement
-        service.videoElement = mockVideo
-
-        await service.switchResolution('480p')
-        expect(service.progress.getValue()).toBe(75)
-      },
-    )
-  })
-
-  it('should stay in transcode mode when already transcoding', async () => {
-    const transcodeResponse: PlaybackInfoResponse = {
-      ...mockPlaybackInfoResponse,
-      mode: 'transcode',
-    }
-    api.call.mockResolvedValue({ result: transcodeResponse })
-
-    await usingAsync(
-      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
-      async (service) => {
-        await vi.waitFor(() => {
-          expect(service.playbackInfo.getValue()).not.toBeNull()
-        })
-
-        expect(service.playbackMode.getValue()).toBe('transcode')
-
-        await service.switchResolution('720p')
-        expect(service.playbackMode.getValue()).toBe('transcode')
-
-        await service.switchResolution(undefined)
-        expect(service.playbackMode.getValue()).toBe('transcode')
-      },
-    )
-  })
-
-  it('should call teardown before switching', async () => {
-    await usingAsync(
-      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
-      async (service) => {
-        await vi.waitFor(() => {
-          expect(service.playbackInfo.getValue()).not.toBeNull()
-        })
-
-        api.call.mockClear()
-
-        await service.switchResolution('720p')
-
-        expect(api.call).toHaveBeenCalledWith(
-          expect.objectContaining({
-            method: 'DELETE',
-            action: '/files/:letter/:path/hls-session',
-          }),
-        )
-      },
-    )
-  })
-})
-
 describe('seekToTime', () => {
   let api: ReturnType<typeof createMockApi>
 
@@ -467,29 +344,25 @@ describe('seekToTime', () => {
     )
   })
 
-  it('should restart HLS session when seeking beyond buffered range', async () => {
+  it('should restart HLS session when seeking backward past hlsStartTime', async () => {
     await usingAsync(
-      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 3605, mockLogger as never),
       async (service) => {
         await vi.waitFor(() => {
           expect(service.playbackInfo.getValue()).not.toBeNull()
         })
 
         const mockVideo = {
-          currentTime: 10,
-          buffered: {
-            length: 1,
-            start: () => 0,
-            end: () => 30,
-          },
+          currentTime: 5,
+          src: '',
+          buffered: { length: 0, start: vi.fn(), end: vi.fn() },
           addEventListener: vi.fn(),
           removeEventListener: vi.fn(),
-          canPlayType: vi.fn().mockReturnValue(''),
         } as unknown as HTMLVideoElement
         service.videoElement = mockVideo
 
         api.call.mockClear()
-        service.seekToTime(3600)
+        service.seekToTime(100)
 
         await vi.waitFor(() => {
           expect(api.call).toHaveBeenCalledWith(
@@ -498,8 +371,30 @@ describe('seekToTime', () => {
               action: '/files/:letter/:path/hls-session',
             }),
           )
-          expect(service.progress.getValue()).toBe(3600)
+          expect(service.progress.getValue()).toBe(100)
+        })
+      },
+    )
+  })
+
+  it('should set video.currentTime for forward seeks', async () => {
+    await usingAsync(
+      new MoviePlayerService(mockFile, mockFfprobe, api as never, 0, mockLogger as never),
+      async (service) => {
+        await vi.waitFor(() => {
+          expect(service.playbackInfo.getValue()).not.toBeNull()
         })
+
+        const mockVideo = {
+          currentTime: 10,
+          buffered: { length: 0, start: vi.fn(), end: vi.fn() },
+          addEventListener: vi.fn(),
+          removeEventListener: vi.fn(),
+        } as unknown as HTMLVideoElement
+        service.videoElement = mockVideo
+
+        service.seekToTime(3600)
+        expect(mockVideo.currentTime).toBe(3600)
       },
     )
   })
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index d76e57ee..ff6536a3 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -10,7 +10,6 @@ import {
   type PlaybackMode,
   type SubtitleTrackInfo,
 } from 'common'
-import Hls from 'hls.js'
 import type { MediaApiClient } from '../../../services/api-clients/media-api-client.js'
 import { environmentOptions } from '../../../utils/environment-options.js'
 
@@ -54,8 +53,6 @@ const buildCodecSupportMap = () => {
   }
 }
 
-export type ResolutionValue = '4k' | '1080p' | '720p' | '480p' | '360p'
-
 export class MoviePlayerService implements AsyncDisposable {
   constructor(
     private readonly file: PiRatFile,
@@ -70,18 +67,27 @@ export class MoviePlayerService implements AsyncDisposable {
     void this.initialize()
   }
 
-  private hls: Hls | null = null
-  private originalPlaybackMode: PlaybackMode = 'transcode'
   public isSwitching = new ObservableValue(false)
   private seekGeneration = 0
   private hlsStartTime = 0
+  private pendingCanPlayCleanup: (() => void) | null = null
   public videoElement: HTMLVideoElement | null = null
   public audioTrackId = new ObservableValue(0)
   public playbackInfo = new ObservableValue<PlaybackInfoResponse | null>(null)
   public playbackMode = new ObservableValue<PlaybackMode>('transcode')
-  public resolution = new ObservableValue<ResolutionValue | undefined>(undefined)
   public progress: ObservableValue<number>
 
+  public isPlaying = new ObservableValue(false)
+  public duration = new ObservableValue(0)
+  public volume = new ObservableValue(1)
+  public isMuted = new ObservableValue(false)
+  public isFullscreen = new ObservableValue(false)
+  public playbackRate = new ObservableValue(1)
+  public buffered = new ObservableValue<TimeRanges | null>(null)
+  public activeSubtitleTrack = new ObservableValue<number | null>(null)
+
+  private videoEventCleanup: Disposable | null = null
+
   /**
    * Converts a 0-based stream time (from video.currentTime during HLS)
    * to the absolute file position. For direct-play, the value is returned
@@ -105,18 +111,28 @@ export class MoviePlayerService implements AsyncDisposable {
       this.seekDebounceTimer = null
     }
 
+    if (this.pendingCanPlayCleanup) {
+      this.pendingCanPlayCleanup()
+    }
+
+    this.videoEventCleanup?.[Symbol.dispose]()
+    this.videoEventCleanup = null
+
     await this.teardownHlsSession()
 
     this.progress[Symbol.dispose]()
-    this.resolution[Symbol.dispose]()
     this.playbackInfo[Symbol.dispose]()
     this.playbackMode[Symbol.dispose]()
     this.audioTrackId[Symbol.dispose]()
     this.isSwitching[Symbol.dispose]()
-    if (this.hls) {
-      this.hls.destroy()
-      this.hls = null
-    }
+    this.isPlaying[Symbol.dispose]()
+    this.duration[Symbol.dispose]()
+    this.volume[Symbol.dispose]()
+    this.isMuted[Symbol.dispose]()
+    this.isFullscreen[Symbol.dispose]()
+    this.playbackRate[Symbol.dispose]()
+    this.buffered[Symbol.dispose]()
+    this.activeSubtitleTrack[Symbol.dispose]()
   }
 
   private async teardownHlsSession() {
@@ -139,10 +155,7 @@ export class MoviePlayerService implements AsyncDisposable {
   }
 
   private async initialize() {
-    const info = await this.fetchPlaybackInfo()
-    if (info) {
-      this.originalPlaybackMode = info.mode
-    }
+    await this.fetchPlaybackInfo()
   }
 
   public async fetchPlaybackInfo(selectedSubtitleTrackIndex?: number): Promise<PlaybackInfoResponse | null> {
@@ -174,10 +187,13 @@ export class MoviePlayerService implements AsyncDisposable {
   }
 
   /**
-   * Attaches to a video element and starts playback using HLS or direct source
+   * Attaches to a video element, binds event listeners for observable state,
+   * and starts playback using native HLS or direct source.
    */
   public attachToVideo(videoElement: HTMLVideoElement) {
     this.videoElement = videoElement
+    this.bindVideoEvents(videoElement)
+
     const info = this.playbackInfo.getValue()
 
     if (!info) {
@@ -194,12 +210,115 @@ export class MoviePlayerService implements AsyncDisposable {
     this.startPlayback(videoElement, info)
   }
 
-  private startPlayback(videoElement: HTMLVideoElement, info: PlaybackInfoResponse) {
-    if (this.hls) {
-      this.hls.destroy()
-      this.hls = null
+  private bindVideoEvents(video: HTMLVideoElement) {
+    const onPlay = () => this.isPlaying.setValue(true)
+    const onPause = () => this.isPlaying.setValue(false)
+    const onVolumeChange = () => {
+      this.volume.setValue(video.volume)
+      this.isMuted.setValue(video.muted)
+    }
+    const updateDuration = () => {
+      const playbackDuration = this.playbackInfo.getValue()?.duration
+      if (playbackDuration && playbackDuration > 0) {
+        this.duration.setValue(playbackDuration)
+      } else if (video.duration && isFinite(video.duration)) {
+        this.duration.setValue(video.duration)
+      }
+    }
+    const onDurationChange = updateDuration
+    const onLoadedMetadata = updateDuration
+    const onRateChange = () => this.playbackRate.setValue(video.playbackRate)
+    const onProgress = () => this.buffered.setValue(video.buffered)
+    const onTimeUpdate = () => {
+      if (this.isSwitching.getValue()) return
+      this.progress.setValue(this.streamTimeToAbsolute(video.currentTime) || 0)
+    }
+    const onSeeking = () => {
+      this.seekToTime(this.streamTimeToAbsolute(video.currentTime))
     }
+    const onFullscreenChange = () => {
+      this.isFullscreen.setValue(!!document.fullscreenElement)
+    }
+
+    video.addEventListener('play', onPlay)
+    video.addEventListener('pause', onPause)
+    video.addEventListener('volumechange', onVolumeChange)
+    video.addEventListener('durationchange', onDurationChange)
+    video.addEventListener('loadedmetadata', onLoadedMetadata)
+    video.addEventListener('ratechange', onRateChange)
+    video.addEventListener('progress', onProgress)
+    video.addEventListener('timeupdate', onTimeUpdate)
+    video.addEventListener('seeking', onSeeking)
+    document.addEventListener('fullscreenchange', onFullscreenChange)
+
+    const playbackInfoDuration = this.playbackInfo.getValue()?.duration
+    if (playbackInfoDuration && playbackInfoDuration > 0) {
+      this.duration.setValue(playbackInfoDuration)
+    }
+
+    this.videoEventCleanup = {
+      [Symbol.dispose]: () => {
+        video.removeEventListener('play', onPlay)
+        video.removeEventListener('pause', onPause)
+        video.removeEventListener('volumechange', onVolumeChange)
+        video.removeEventListener('durationchange', onDurationChange)
+        video.removeEventListener('loadedmetadata', onLoadedMetadata)
+        video.removeEventListener('ratechange', onRateChange)
+        video.removeEventListener('progress', onProgress)
+        video.removeEventListener('timeupdate', onTimeUpdate)
+        video.removeEventListener('seeking', onSeeking)
+        document.removeEventListener('fullscreenchange', onFullscreenChange)
+      },
+    }
+  }
+
+  public togglePlay() {
+    const video = this.videoElement
+    if (!video) return
+    if (video.paused) {
+      void video.play().catch(() => {})
+    } else {
+      video.pause()
+    }
+  }
 
+  public setVolume(value: number) {
+    if (this.videoElement) {
+      this.videoElement.volume = Math.max(0, Math.min(1, value))
+    }
+  }
+
+  public setMuted(muted: boolean) {
+    if (this.videoElement) {
+      this.videoElement.muted = muted
+    }
+  }
+
+  public setPlaybackRate(rate: number) {
+    if (this.videoElement) {
+      this.videoElement.playbackRate = rate
+    }
+  }
+
+  public toggleFullscreen(container: HTMLElement) {
+    if (document.fullscreenElement) {
+      void document.exitFullscreen()
+    } else {
+      void container.requestFullscreen()
+    }
+  }
+
+  public togglePip() {
+    const video = this.videoElement
+    if (!video) return
+    if (document.pictureInPictureElement) {
+      void document.exitPictureInPicture()
+    } else {
+      void video.requestPictureInPicture()
+    }
+  }
+
+  private startPlayback(videoElement: HTMLVideoElement, info: PlaybackInfoResponse) {
     const mode = this.playbackMode.getValue()
     if (mode === 'direct-play') {
       this.startDirectPlayback(videoElement, info)
@@ -230,76 +349,11 @@ export class MoviePlayerService implements AsyncDisposable {
       `/api/media/files/${encodeURIComponent(this.file.driveLetter)}/${encodeURIComponent(this.file.path)}/master.m3u8?mode=${encode(mode)}${audioParam}${startTimeParam}`,
     )
 
-    // Prefer hls.js over native HLS — many browsers (including Chromium) report
-    // canPlayType('application/vnd.apple.mpegurl') as 'maybe' without full support.
-    // hls.js also handles missing alternative renditions more gracefully.
-    if (!Hls.isSupported()) {
-      if (videoElement.canPlayType('application/vnd.apple.mpegurl')) {
-        void this.logger.verbose({ message: 'Using native HLS playback' })
-        videoElement.src = hlsUrl
-        if (this.currentProgress > 0) {
-          videoElement.currentTime = this.currentProgress
-        }
-        return
-      }
-      void this.logger.error({ message: 'HLS is not supported in this browser' })
-      return
+    void this.logger.verbose({ message: 'Starting native HLS playback' })
+    videoElement.src = hlsUrl
+    if (this.currentProgress > this.hlsStartTime) {
+      videoElement.currentTime = this.currentProgress - this.hlsStartTime
     }
-
-    void this.logger.verbose({ message: 'Starting HLS playback via hls.js' })
-
-    this.hls = new Hls({
-      xhrSetup: (xhr) => {
-        xhr.withCredentials = true
-      },
-
-      startPosition: this.currentProgress > this.hlsStartTime ? this.currentProgress - this.hlsStartTime : -1,
-    })
-
-    this.hls.on(Hls.Events.ERROR, (_event, data) => {
-      if (data.fatal) {
-        void this.logger.error({
-          message: `HLS fatal error: ${data.type}`,
-          data: { details: data.details },
-        })
-
-        if (data.type === Hls.ErrorTypes.NETWORK_ERROR) {
-          this.hls?.startLoad()
-        } else if (data.type === Hls.ErrorTypes.MEDIA_ERROR) {
-          this.hls?.recoverMediaError()
-        }
-      }
-    })
-
-    const { hls } = this
-
-    hls.on(Hls.Events.MANIFEST_PARSED, () => {
-      void this.logger.verbose({ message: 'HLS manifest parsed' })
-
-      const resolutionHeightMap: Record<string, number> = {
-        '4k': 2160,
-        '1080p': 1080,
-        '720p': 720,
-        '480p': 480,
-        '360p': 360,
-      }
-
-      const sub = this.resolution.subscribe((value) => {
-        if (!value) {
-          hls.currentLevel = -1
-          return
-        }
-        const targetHeight = resolutionHeightMap[value]
-        if (!targetHeight) return
-        const levelIndex = hls.levels.findIndex((l) => l.height === targetHeight)
-        hls.currentLevel = levelIndex >= 0 ? levelIndex : -1
-      })
-
-      hls.on(Hls.Events.DESTROYING, () => sub[Symbol.dispose]())
-    })
-
-    this.hls.loadSource(hlsUrl)
-    this.hls.attachMedia(videoElement)
   }
 
   /**
@@ -327,48 +381,13 @@ export class MoviePlayerService implements AsyncDisposable {
     }
   }
 
-  /**
-   * Switches resolution and restarts playback. Forces transcode mode when a
-   * specific resolution is requested; restores the original mode on "Auto".
-   *
-   * Always tears down the existing server-side HLS session to ensure the
-   * old ffmpeg process is cleaned up before the new one starts.
-   */
-  public async switchResolution(value: ResolutionValue | undefined) {
-    const targetMode = value ? 'transcode' : this.originalPlaybackMode
-
-    const previousProgress = this.getAbsoluteProgress()
-
-    this.isSwitching.setValue(true)
-    await this.teardownHlsSession()
-
-    this.resolution.setValue(value)
-    this.currentProgress = previousProgress
-    this.progress.setValue(previousProgress)
-    this.hlsStartTime = Math.floor(previousProgress / HLS_SEGMENT_DURATION) * HLS_SEGMENT_DURATION
-    this.playbackMode.setValue(targetMode)
-
-    if (this.videoElement) {
-      const info = this.playbackInfo.getValue()
-      if (info) {
-        this.startPlayback(this.videoElement, info)
-        this.waitForCanPlay(this.videoElement)
-      } else {
-        this.isSwitching.setValue(false)
-      }
-    } else {
-      this.isSwitching.setValue(false)
-    }
-  }
-
   private seekDebounceTimer: ReturnType<typeof setTimeout> | null = null
 
   /**
-   * Handles a seek to a new absolute file time position. If the target is
-   * before the current playlist start, tears down the current session and
-   * starts a new one with server-side seeking via `-ss`. Forward seeks
-   * within the current playlist are left to hls.js which can load the
-   * required segments on its own.
+   * Handles a seek to a new absolute file time position. For forward seeks
+   * within the current playlist, sets video.currentTime directly. If the
+   * target is before the current playlist start, tears down the current
+   * session and starts a new one with server-side seeking via `-ss`.
    */
   public seekToTime(targetSeconds: number) {
     const mode = this.playbackMode.getValue()
@@ -377,12 +396,13 @@ export class MoviePlayerService implements AsyncDisposable {
     const video = this.videoElement
     if (!video) return
 
-    // Convert absolute file time to 0-based stream time for the buffer check
     const streamTime = targetSeconds - this.hlsStartTime
     if (streamTime >= 0 && this.isTimeBuffered(video, streamTime)) return
 
-    // hls.js can handle forward seeks within the current VOD playlist
-    if (targetSeconds >= this.hlsStartTime) return
+    if (targetSeconds >= this.hlsStartTime) {
+      video.currentTime = targetSeconds - this.hlsStartTime
+      return
+    }
 
     const quantizedStart = Math.floor(targetSeconds / HLS_SEGMENT_DURATION) * HLS_SEGMENT_DURATION
 
@@ -410,35 +430,45 @@ export class MoviePlayerService implements AsyncDisposable {
     this.isSwitching.setValue(true)
     const generation = ++this.seekGeneration
 
-    await this.teardownHlsSession()
-
-    if (generation !== this.seekGeneration) return
+    try {
+      await this.teardownHlsSession()
 
-    if (this.hls) {
-      this.hls.destroy()
-      this.hls = null
-    }
+      if (generation !== this.seekGeneration) return
 
-    this.hlsStartTime = quantizedStart
-    this.currentProgress = targetSeconds
-    this.progress.setValue(targetSeconds)
+      this.hlsStartTime = quantizedStart
+      this.currentProgress = targetSeconds
+      this.progress.setValue(targetSeconds)
 
-    if (this.videoElement) {
-      this.startHlsPlayback(this.videoElement)
-      this.waitForCanPlay(this.videoElement)
-    } else {
-      this.isSwitching.setValue(false)
+      if (this.videoElement) {
+        this.startHlsPlayback(this.videoElement)
+        this.waitForCanPlay(this.videoElement)
+      } else {
+        this.isSwitching.setValue(false)
+      }
+    } catch {
+      if (generation === this.seekGeneration) {
+        this.isSwitching.setValue(false)
+      }
     }
   }
 
   private waitForCanPlay(video: HTMLVideoElement) {
+    if (this.pendingCanPlayCleanup) {
+      this.pendingCanPlayCleanup()
+    }
+
     const onCanPlay = () => {
       video.removeEventListener('canplay', onCanPlay)
+      this.pendingCanPlayCleanup = null
       this.isSwitching.setValue(false)
       // play() can reject with AbortError when navigation interrupts playback; this is benign
       void video.play().catch(() => {})
     }
     video.addEventListener('canplay', onCanPlay)
+    this.pendingCanPlayCleanup = () => {
+      video.removeEventListener('canplay', onCanPlay)
+      this.pendingCanPlayCleanup = null
+    }
   }
 
   public getAudioTrackInfoFromPlaybackInfo(): AudioTrackInfo[] {
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.spec.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.spec.ts
index c73e463c..27eb063a 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.spec.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.spec.ts
@@ -1,158 +1,17 @@
-import type { AudioTrackInfo, FfprobeData, PlaybackInfoResponse } from 'common'
+import type { FfprobeData, PlaybackInfoResponse } from 'common'
 import { describe, expect, it } from 'vitest'
 import { getSubtitleTracks, getSubtitleTracksFromPlaybackInfo } from './get-subtitle-tracks.js'
 
 /**
- * The MoviePlayerV2 component is a Shades component tightly coupled to
- * media-chrome custom elements and HTMLVideoElement. Its testable logic
- * is exercised here via the data-mapping helpers it uses inline.
+ * The MoviePlayerV2 component is a Shades component that uses custom
+ * Shades controls bound to MoviePlayerService observables. Its testable
+ * logic is exercised here via the data-mapping helpers it uses inline.
  *
  * The core playback logic is covered in movie-player-service.spec.ts
  * and get-subtitle-tracks.spec.tsx.
  */
 
-type Rendition = { id: string; width: number; height: number; src: string; selected: boolean }
-
-const buildRenditionList = (height: number, currentValue?: string) => {
-  const renditions: Rendition[] = [
-    ...(height >= 2160 ? [{ id: '4k', width: 3840, height: 2160, src: '', selected: currentValue === '4k' }] : []),
-    ...(height >= 1080
-      ? [{ id: '1080p', width: 1920, height: 1080, src: '', selected: currentValue === '1080p' }]
-      : []),
-    ...(height >= 720 ? [{ id: '720p', width: 1280, height: 720, src: '', selected: currentValue === '720p' }] : []),
-    ...(height >= 480 ? [{ id: '480p', width: 854, height: 480, src: '', selected: currentValue === '480p' }] : []),
-    { id: '360p', width: 640, height: 360, src: '', selected: currentValue === '360p' },
-  ]
-  return renditions
-}
-
-const createRenditionList = (items: Rendition[], selectedIndex: number) => {
-  const target = new EventTarget()
-  return Object.assign([...items], {
-    addEventListener: target.addEventListener.bind(target),
-    removeEventListener: target.removeEventListener.bind(target),
-    dispatchEvent: target.dispatchEvent.bind(target),
-    selectedIndex,
-  })
-}
-
-const mapAudioTracksForMediaChrome = (audioTracks: AudioTrackInfo[]) =>
-  audioTracks.map((track, index) => ({
-    id: track.index.toFixed(0),
-    label: track.label || track.language || `Audio Track ${index + 1}`,
-    language: track.language,
-    enabled: index === 0,
-    kind: track.label,
-  }))
-
 describe('MoviePlayerV2 component logic', () => {
-  describe('buildRenditionList', () => {
-    it('should include all resolutions for 4K source', () => {
-      const renditions = buildRenditionList(2160)
-      expect(renditions).toHaveLength(5)
-      expect(renditions.map((r) => r.id)).toEqual(['4k', '1080p', '720p', '480p', '360p'])
-    })
-
-    it('should exclude resolutions above source height', () => {
-      const renditions = buildRenditionList(720)
-      expect(renditions).toHaveLength(3)
-      expect(renditions.map((r) => r.id)).toEqual(['720p', '480p', '360p'])
-    })
-
-    it('should always include 360p', () => {
-      const renditions = buildRenditionList(240)
-      expect(renditions).toHaveLength(1)
-      expect(renditions[0].id).toBe('360p')
-    })
-
-    it('should mark the selected rendition', () => {
-      const renditions = buildRenditionList(1080, '720p')
-      const selected = renditions.find((r) => r.selected)
-      expect(selected?.id).toBe('720p')
-    })
-
-    it('should not mark any rendition when no value is selected', () => {
-      const renditions = buildRenditionList(1080)
-      expect(renditions.every((r) => !r.selected)).toBe(true)
-    })
-  })
-
-  describe('createRenditionList', () => {
-    it('should implement EventTarget methods', () => {
-      const items = buildRenditionList(1080)
-      const list = createRenditionList(items, -1)
-
-      expect(typeof list.addEventListener).toBe('function')
-      expect(typeof list.removeEventListener).toBe('function')
-      expect(typeof list.dispatchEvent).toBe('function')
-    })
-
-    it('should expose selectedIndex', () => {
-      const items = buildRenditionList(1080, '720p')
-      const selectedIdx = items.findIndex((r) => r.selected)
-      const list = createRenditionList(items, selectedIdx)
-
-      expect(list.selectedIndex).toBe(1)
-    })
-
-    it('should be array-like with rendition items', () => {
-      const items = buildRenditionList(1080)
-      const list = createRenditionList(items, -1)
-
-      expect(list).toHaveLength(4)
-      expect(list[0].id).toBe('1080p')
-      expect(list[3].id).toBe('360p')
-    })
-
-    it('should allow adding and dispatching events', () => {
-      const items = buildRenditionList(720)
-      const list = createRenditionList(items, 0)
-
-      let eventFired = false
-      list.addEventListener('change', () => {
-        eventFired = true
-      })
-      list.dispatchEvent(new Event('change'))
-      expect(eventFired).toBe(true)
-    })
-  })
-
-  describe('mapAudioTracksForMediaChrome', () => {
-    it('should map audio tracks with correct ids and labels', () => {
-      const tracks: AudioTrackInfo[] = [
-        { index: 1, label: 'English', language: 'eng', codecName: 'aac', channels: 2, isDefault: true },
-        { index: 2, label: 'French', language: 'fra', codecName: 'ac3', channels: 6, isDefault: false },
-      ]
-
-      const mapped = mapAudioTracksForMediaChrome(tracks)
-      expect(mapped).toHaveLength(2)
-      expect(mapped[0].id).toBe('1')
-      expect(mapped[0].label).toBe('English')
-      expect(mapped[0].enabled).toBe(true)
-      expect(mapped[1].id).toBe('2')
-      expect(mapped[1].label).toBe('French')
-      expect(mapped[1].enabled).toBe(false)
-    })
-
-    it('should fall back to language when label is empty', () => {
-      const tracks: AudioTrackInfo[] = [
-        { index: 1, label: '', language: 'jpn', codecName: 'aac', channels: 2, isDefault: false },
-      ]
-
-      const mapped = mapAudioTracksForMediaChrome(tracks)
-      expect(mapped[0].label).toBe('jpn')
-    })
-
-    it('should fall back to generic label when both label and language are empty', () => {
-      const tracks: AudioTrackInfo[] = [
-        { index: 1, label: '', language: '', codecName: 'aac', channels: 2, isDefault: false },
-      ]
-
-      const mapped = mapAudioTracksForMediaChrome(tracks)
-      expect(mapped[0].label).toBe('Audio Track 1')
-    })
-  })
-
   describe('subtitle source selection', () => {
     const selectSubtitleElements = (
       playbackInfo: PlaybackInfoResponse | null,
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
index 7ecba37b..a7bdad69 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
@@ -1,25 +1,15 @@
 import { getLogger } from '@furystack/logging'
 import { Shade, createComponent } from '@furystack/shades'
 import { type FfprobeData, type Movie, type PiRatFile, type WatchHistoryEntry } from 'common'
-import type { AudioTrack, Rendition } from 'media-chrome/dist/media-store/state-mediator.js'
+
 import { MediaApiClient } from '../../../services/api-clients/media-api-client.js'
 import { WatchProgressService } from '../../../services/watch-progress-service.js'
 import { WatchProgressUpdater } from '../../../services/watch-progress-updater.js'
+import { VideoContainer } from './controls/index.js'
 import { getChaptersTrack } from './get-chapters-track.js'
 import { getSubtitleTracks, getSubtitleTracksFromPlaybackInfo } from './get-subtitle-tracks.js'
-import './media-chrome.js'
 import { MoviePlayerService } from './movie-player-service.js'
 
-const createRenditionList = (items: Rendition[], selectedIndex: number) => {
-  const target = new EventTarget()
-  return Object.assign([...items], {
-    addEventListener: target.addEventListener.bind(target),
-    removeEventListener: target.removeEventListener.bind(target),
-    dispatchEvent: target.dispatchEvent.bind(target),
-    selectedIndex,
-  })
-}
-
 type MoviePlayerProps = {
   file: PiRatFile
   ffprobe: FfprobeData
@@ -31,7 +21,7 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
   customElementName: 'pirat-movie-player-v2',
   render: ({ props, useDisposable, useObservable, useRef, injector }) => {
     const videoRef = useRef<HTMLVideoElement>('video')
-    const containerRef = useRef<HTMLElement>('container')
+    const playerContainerRef = useRef<HTMLElement>('playerContainer')
 
     const { driveLetter, path } = props.file
     const watchProgressService = injector.getInstance(WatchProgressService)
@@ -105,7 +95,7 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
 
     return (
       <div
-        ref={containerRef}
+        ref={playerContainerRef}
         style={{
           position: 'relative',
           width: '100%',
@@ -113,155 +103,20 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
           overflow: 'hidden',
         }}
       >
-        <media-controller
-          defaultDuration={playbackInfo?.duration}
+        <video
+          ref={videoRef}
+          crossOrigin="use-credentials"
+          autoplay
           style={{
-            display: 'flex',
             width: '100%',
             height: '100%',
-            objectFit: 'cover',
+            objectFit: 'contain',
           }}
         >
-          <media-settings-menu anchor="auto" hidden>
-            <media-settings-menu-item>
-              Speed
-              <media-playback-rate-menu slot="submenu" hidden>
-                <div slot="title">Speed</div>
-              </media-playback-rate-menu>
-            </media-settings-menu-item>
-            <media-settings-menu-item>
-              Quality
-              <media-rendition-menu
-                slot="submenu"
-                hidden
-                onchange={(ev) => {
-                  const validValues = ['4k', '1080p', '720p', '480p', '360p'] as const
-                  const { value } = ev.currentTarget as HTMLInputElement
-
-                  if (validValues.includes(value as (typeof validValues)[number])) {
-                    void mediaService.switchResolution(value as (typeof validValues)[number])
-                  } else {
-                    void mediaService.switchResolution(undefined)
-                  }
-                }}
-              >
-                <div slot="title">Quality</div>
-              </media-rendition-menu>
-            </media-settings-menu-item>
-            <media-settings-menu-item>
-              Captions
-              <media-captions-menu slot="submenu" hidden>
-                <div slot="title">Captions</div>
-              </media-captions-menu>
-            </media-settings-menu-item>
-            <media-settings-menu-item>
-              Audio
-              <media-audio-track-menu
-                slot="submenu"
-                hidden
-                onchange={(ev) => {
-                  const newId = parseInt((ev.target as HTMLInputElement).value, 10)
-                  if (!isNaN(newId)) {
-                    void mediaService.switchAudioTrack(newId)
-                  }
-                }}
-              >
-                <div slot="title">Audio</div>
-              </media-audio-track-menu>
-            </media-settings-menu-item>
-          </media-settings-menu>
-          <video
-            ref={videoRef}
-            slot="media"
-            crossOrigin="use-credentials"
-            autoplay
-            onloadstart={(ev) => {
-              const playbackInfoAudioTracks = mediaService.getAudioTrackInfoFromPlaybackInfo()
-              const audioTracks =
-                playbackInfoAudioTracks.length > 0
-                  ? playbackInfoAudioTracks
-                  : mediaService.getAudioTracks().map((t) => ({
-                      index: t.id,
-                      label:
-                        (t.stream.tags as Record<string, string>)?.title ||
-                        (t.stream.tags as Record<string, string>)?.language ||
-                        `Audio Track`,
-                      language: (t.stream.tags as Record<string, string>)?.language || 'unknown',
-                      codecName: t.codecName ?? 'unknown',
-                      channels: t.stream.channels ?? 2,
-                      isDefault: t.stream.disposition?.default === 1,
-                    }))
-
-              const video = ev.currentTarget as HTMLVideoElement & {
-                audioTracks: AudioTrack[]
-                videoRenditions: ReturnType<typeof createRenditionList>
-              }
-
-              video.audioTracks = audioTracks.map((track, index) => ({
-                id: track.index.toFixed(0),
-                label: track.label || track.language || `Audio Track ${index + 1}`,
-                language: track.language,
-                enabled: index === 0,
-                kind: track.label,
-              }))
-
-              const currentValue = mediaService.resolution.getValue()
-              const videoStream = props.ffprobe.streams.find((stream) => stream.codec_type === 'video')
-              const height = videoStream?.height || 1080
-
-              const renditionItems: Rendition[] = [
-                ...(height >= 2160
-                  ? [{ id: '4k', width: 3840, height: 2160, src: '', selected: currentValue === '4k' }]
-                  : []),
-                ...(height >= 1080
-                  ? [{ id: '1080p', width: 1920, height: 1080, src: '', selected: currentValue === '1080p' }]
-                  : []),
-                ...(height >= 720
-                  ? [{ id: '720p', width: 1280, height: 720, src: '', selected: currentValue === '720p' }]
-                  : []),
-                ...(height >= 480
-                  ? [{ id: '480p', width: 854, height: 480, src: '', selected: currentValue === '480p' }]
-                  : []),
-                { id: '360p', width: 640, height: 360, src: '', selected: currentValue === '360p' },
-              ]
-              const selectedIdx = renditionItems.findIndex((r) => r.selected)
-              video.videoRenditions = createRenditionList(renditionItems, selectedIdx)
-
-              if (video.audioTracks[0]) {
-                mediaService.audioTrackId.setValue(parseInt(video.audioTracks[0].id as string, 10))
-              }
-            }}
-            onseeking={(ev) => {
-              const { currentTime } = ev.currentTarget as HTMLVideoElement
-              mediaService.seekToTime(mediaService.streamTimeToAbsolute(currentTime))
-            }}
-            ontimeupdate={(ev) => {
-              if (mediaService.isSwitching.getValue()) return
-              const { currentTime } = ev.currentTarget as HTMLVideoElement
-              mediaService.progress.setValue(mediaService.streamTimeToAbsolute(currentTime) || 0)
-            }}
-          >
-            {...subtitleElements}
-            {getChaptersTrack(props.ffprobe)}
-          </video>
-
-          <media-loading-indicator slot="centered-chrome"></media-loading-indicator>
-          <media-error-dialog slot="dialog"></media-error-dialog>
-          <media-poster-image slot="poster" />
-
-          <media-control-bar style={{ width: '100%' }}>
-            <media-play-button />
-            <media-time-display />
-            <media-time-range />
-            <media-duration-display />
-            <media-volume-range />
-            <media-mute-button />
-            <media-fullscreen-button />
-            <media-pip-button />
-            <media-captions-button />
-            <media-settings-menu-button></media-settings-menu-button>
-          </media-control-bar>
-        </media-controller>
+          {...subtitleElements}
+          {getChaptersTrack(props.ffprobe)}
+        </video>
+        <VideoContainer mediaService={mediaService} playerContainerRef={playerContainerRef} />
       </div>
     )
   },
diff --git a/frontend/src/pages/movies/plain-hls-player.tsx b/frontend/src/pages/movies/plain-hls-player.tsx
index 9e5372a5..db7bc6d1 100644
--- a/frontend/src/pages/movies/plain-hls-player.tsx
+++ b/frontend/src/pages/movies/plain-hls-player.tsx
@@ -1,10 +1,10 @@
 import { Shade, createComponent } from '@furystack/shades'
-import type Hls from 'hls.js'
+
 import { environmentOptions } from '../../utils/environment-options.js'
 
 /**
- * Minimal HLS player for debugging — no media-chrome, no MoviePlayerService,
- * no watch progress, no audio/subtitle track management. Just hls.js + a <video>.
+ * Minimal HLS player for debugging -- native browser HLS playback + a <video>.
+ * No MoviePlayerService, no watch progress, no audio/subtitle track management.
  */
 export const PlainHlsPlayer = Shade<{ driveLetter: string; path: string }>({
   customElementName: 'plain-hls-player',
@@ -14,9 +14,7 @@ export const PlainHlsPlayer = Shade<{ driveLetter: string; path: string }>({
 
     const hlsUrl = `${environmentOptions.serviceUrl}/media/files/${encodeURIComponent(props.driveLetter)}/${encodeURIComponent(props.path)}/master.m3u8?mode=transcode`
 
-    let hlsInstance: Hls | null = null
-
-    useDisposable('hls-setup', () => {
+    useDisposable('video-setup', () => {
       const frameId = requestAnimationFrame(() => {
         const video = videoRef.current
         const log = logRef.current
@@ -29,68 +27,29 @@ export const PlainHlsPlayer = Shade<{ driveLetter: string; path: string }>({
         }
 
         append(`HLS URL: ${hlsUrl}`)
+        video.src = hlsUrl
 
-        void import('hls.js').then(({ default: HlsModule }) => {
-          if (!HlsModule.isSupported()) {
-            append('hls.js not supported, trying native')
-            video.src = hlsUrl
-            return
+        video.addEventListener('loadedmetadata', () => {
+          append(`Metadata loaded: duration=${video.duration.toFixed(1)}s`)
+        })
+        video.addEventListener('canplay', () => {
+          append('Can play')
+          video.play().catch((err: unknown) => append(`Autoplay blocked: ${String(err)}`))
+        })
+        video.addEventListener('error', () => {
+          const err = video.error
+          append(`ERROR: ${err?.message ?? `code ${err?.code}`}`)
+        })
+        video.addEventListener('progress', () => {
+          if (video.buffered.length > 0) {
+            const end = video.buffered.end(video.buffered.length - 1)
+            append(`Buffered to ${end.toFixed(1)}s`)
           }
-
-          const hls = new HlsModule({
-            debug: false,
-            xhrSetup: (xhr) => {
-              xhr.withCredentials = true
-            },
-          })
-          hlsInstance = hls
-
-          hls.on(HlsModule.Events.MANIFEST_PARSED, (_e, data) => {
-            append(`Manifest parsed: ${data.levels.length} levels`)
-            video.play().catch((err: unknown) => append(`Autoplay blocked: ${String(err)}`))
-          })
-
-          hls.on(HlsModule.Events.LEVEL_LOADED, (_e, data) => {
-            append(
-              `Level ${data.level} loaded: ${data.details.totalduration?.toFixed(1)}s, ${data.details.fragments.length} frags`,
-            )
-          })
-
-          hls.on(HlsModule.Events.FRAG_LOADED, (_e, data) => {
-            const f = data.frag
-            append(`Frag ${f.sn} [${f.type}] start=${f.start.toFixed(1)} dur=${f.duration.toFixed(1)} level=${f.level}`)
-          })
-
-          hls.on(HlsModule.Events.FRAG_BUFFERED, (_e, data) => {
-            const { startPTS, endPTS } = data.frag
-            if (startPTS !== undefined && startPTS !== null) {
-              append(
-                `  -> buffered ${data.frag.sn} [${data.frag.type}] PTS=${startPTS.toFixed(2)}-${endPTS?.toFixed(2)}`,
-              )
-            }
-          })
-
-          hls.on(HlsModule.Events.ERROR, (_e, data) => {
-            append(`ERROR: ${data.type} / ${data.details}${data.fatal ? ' [FATAL]' : ''}`)
-            if (data.fatal && data.type === HlsModule.ErrorTypes.MEDIA_ERROR) {
-              append('Attempting recovery...')
-              hls.recoverMediaError()
-            }
-          })
-
-          hls.loadSource(hlsUrl)
-          hls.attachMedia(video)
         })
+        video.addEventListener('waiting', () => append('Waiting for data...'))
+        video.addEventListener('playing', () => append('Playing'))
       })
-      return {
-        [Symbol.dispose]: () => {
-          cancelAnimationFrame(frameId)
-          if (hlsInstance) {
-            hlsInstance.destroy()
-            hlsInstance = null
-          }
-        },
-      }
+      return { [Symbol.dispose]: () => cancelAnimationFrame(frameId) }
     })
 
     return (
diff --git a/yarn.lock b/yarn.lock
index 5fc0983f..aa04992a 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3418,15 +3418,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ce-la-react@npm:^0.3.2":
-  version: 0.3.2
-  resolution: "ce-la-react@npm:0.3.2"
-  peerDependencies:
-    react: ">=17.0.0"
-  checksum: 10c0/cbee7602c1e4efc1278e5c0847b8201fa291ad3a5bde4137da139a7b6a2b7b8de029530fb2c474e62fcc544e62669003e4a34fd1abafac8110d89ffade588c37
-  languageName: node
-  linkType: hard
-
 "chai@npm:^6.2.1":
   version: 6.2.2
   resolution: "chai@npm:6.2.2"
@@ -4698,8 +4689,6 @@ __metadata:
     "@xterm/addon-web-links": "npm:^0.12.0"
     "@xterm/xterm": "npm:^6.0.0"
     common: "workspace:^"
-    hls.js: "npm:^1.6.15"
-    media-chrome: "npm:^4.18.0"
     ollama: "npm:^0.6.3"
     path-to-regexp: "npm:^8.3.0"
     typescript: "npm:^5.9.3"
@@ -5117,13 +5106,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"hls.js@npm:^1.6.15":
-  version: 1.6.15
-  resolution: "hls.js@npm:1.6.15"
-  checksum: 10c0/a3558909506b9d93420b395b1d9508df364f911ebc19b315f98bd4c1b94973ed996a95fe8662756a3fca96b762af741d13df81987bc68322f473acacbecbc6d9
-  languageName: node
-  linkType: hard
-
 "hpagent@npm:^1.2.0":
   version: 1.2.0
   resolution: "hpagent@npm:1.2.0"
@@ -6152,15 +6134,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"media-chrome@npm:^4.18.0":
-  version: 4.18.0
-  resolution: "media-chrome@npm:4.18.0"
-  dependencies:
-    ce-la-react: "npm:^0.3.2"
-  checksum: 10c0/1ea76dd9cbb0f0b63591b453534449449a3a41b8d632a80fd756906991309725fc554cb910141ca6cff5ceb9e3ecdb65ed9a2cb2e6b5878e26ab9fd405472a02
-  languageName: node
-  linkType: hard
-
 "merge2@npm:^1.3.0":
   version: 1.4.1
   resolution: "merge2@npm:1.4.1"

From 38779d5a66dd8e1958543a7a937805bd6c2fbf23 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Thu, 12 Mar 2026 15:37:50 +0100
Subject: [PATCH 21/30] code review fixes

---
 .yarn/versions/90cc3afc.yml                   |   2 +-
 common/src/utils/media/is-movie-file.spec.ts  |  17 +++
 e2e/video-playback.spec.ts                    |   4 +
 .../controls/error-overlay.tsx                |  67 ++++++-----
 .../movies/movie-player-v2/controls/index.ts  |   1 -
 .../controls/poster-overlay.tsx               |  34 ------
 .../controls/settings-menu.spec.ts            |  32 ++++++
 .../controls/settings-menu.tsx                |   8 ++
 .../controls/time-display.spec.ts             |  44 +++++++
 .../movie-player-v2/controls/time-display.tsx |   2 +-
 .../controls/video-container.spec.ts          |  26 +++++
 .../controls/video-container.tsx              |  52 ++-------
 .../movie-player-v2-component.tsx             |  18 +--
 .../src/pages/movies/plain-hls-player.tsx     |  47 ++++++--
 frontend/src/utils/when-ref-ready.spec.ts     | 108 ++++++++++++++++++
 frontend/src/utils/when-ref-ready.ts          |  34 ++++++
 16 files changed, 365 insertions(+), 131 deletions(-)
 delete mode 100644 frontend/src/pages/movies/movie-player-v2/controls/poster-overlay.tsx
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/settings-menu.spec.ts
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/time-display.spec.ts
 create mode 100644 frontend/src/pages/movies/movie-player-v2/controls/video-container.spec.ts
 create mode 100644 frontend/src/utils/when-ref-ready.spec.ts
 create mode 100644 frontend/src/utils/when-ref-ready.ts

diff --git a/.yarn/versions/90cc3afc.yml b/.yarn/versions/90cc3afc.yml
index ac090136..b371570e 100644
--- a/.yarn/versions/90cc3afc.yml
+++ b/.yarn/versions/90cc3afc.yml
@@ -1,5 +1,5 @@
 releases:
-  common: patch
+  common: minor
   frontend: patch
   pi-rat: patch
   service: patch
diff --git a/common/src/utils/media/is-movie-file.spec.ts b/common/src/utils/media/is-movie-file.spec.ts
index 0edf610c..34bcaeb7 100644
--- a/common/src/utils/media/is-movie-file.spec.ts
+++ b/common/src/utils/media/is-movie-file.spec.ts
@@ -10,6 +10,23 @@ describe('isMovieFile', () => {
     expect(isMovieFile('alma.webm')).toBeTruthy()
   })
 
+  it('should indicate true if the extension is .avi', () => {
+    expect(isMovieFile('alma.avi')).toBeTruthy()
+  })
+
+  it('should indicate true if the extension is .mp4', () => {
+    expect(isMovieFile('alma.mp4')).toBeTruthy()
+  })
+
+  it('should indicate true if the extension is .mov', () => {
+    expect(isMovieFile('alma.mov')).toBeTruthy()
+  })
+
+  it('should be case-insensitive', () => {
+    expect(isMovieFile('alma.MKV')).toBeTruthy()
+    expect(isMovieFile('alma.Mp4')).toBeTruthy()
+  })
+
   it('should indicate false for unknown extensions', () => {
     expect(isMovieFile('alma.zip')).toBeFalsy()
   })
diff --git a/e2e/video-playback.spec.ts b/e2e/video-playback.spec.ts
index e69f2c5f..6bfef424 100644
--- a/e2e/video-playback.spec.ts
+++ b/e2e/video-playback.spec.ts
@@ -244,4 +244,8 @@ test.describe('Video Playback @media', () => {
       expect(currentTime).toBeGreaterThan(0)
     }).toPass({ timeout: 30_000, intervals: [2_000, 3_000, 5_000] })
   })
+
+  // Quality/resolution switching was removed in favour of server-side mode
+  // selection (transcode / remux / direct-play). No client-side resolution
+  // observable exists anymore, so the former E2E test is intentionally omitted.
 })
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/error-overlay.tsx b/frontend/src/pages/movies/movie-player-v2/controls/error-overlay.tsx
index 4a44d54b..481a4716 100644
--- a/frontend/src/pages/movies/movie-player-v2/controls/error-overlay.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/controls/error-overlay.tsx
@@ -6,42 +6,53 @@ type ErrorOverlayProps = {
   mediaService: MoviePlayerService
 }
 
+/**
+ * Waits for `mediaService.videoElement` to be set, then calls `callback`.
+ * Uses rAF as a single-frame deferral since the video element is attached
+ * synchronously during the same render cycle.
+ */
+const whenVideoReady = (
+  mediaService: MoviePlayerService,
+  callback: (video: HTMLVideoElement) => Disposable | void,
+): Disposable => {
+  const video = mediaService.videoElement
+  if (video) {
+    const cleanup = callback(video)
+    return cleanup ?? { [Symbol.dispose]: () => {} }
+  }
+
+  let cleanup: Disposable | null = null
+  const frameId = requestAnimationFrame(() => {
+    const deferred = mediaService.videoElement
+    if (deferred) {
+      cleanup = callback(deferred) ?? null
+    }
+  })
+  return {
+    [Symbol.dispose]: () => {
+      cancelAnimationFrame(frameId)
+      cleanup?.[Symbol.dispose]()
+    },
+  }
+}
+
 export const ErrorOverlay = Shade<ErrorOverlayProps>({
   customElementName: 'pirat-player-error-overlay',
   render: ({ props, useState, useDisposable }) => {
     const [error, setError] = useState<string | null>('error', null)
 
-    useDisposable('errorListener', () => {
-      const onError = (video: HTMLVideoElement) => {
-        const mediaError = video.error
-        if (mediaError) {
-          setError(`Playback error: ${mediaError.message || `code ${mediaError.code}`}`)
+    useDisposable('errorListener', () =>
+      whenVideoReady(props.mediaService, (video) => {
+        const handler = () => {
+          const mediaError = video.error
+          if (mediaError) {
+            setError(`Playback error: ${mediaError.message || `code ${mediaError.code}`}`)
+          }
         }
-      }
-
-      const video = props.mediaService.videoElement
-      if (video) {
-        const handler = () => onError(video)
         video.addEventListener('error', handler)
         return { [Symbol.dispose]: () => video.removeEventListener('error', handler) }
-      }
-
-      let cleanup: Disposable | null = null
-      const frameId = requestAnimationFrame(() => {
-        const deferredVideo = props.mediaService.videoElement
-        if (deferredVideo) {
-          const handler = () => onError(deferredVideo)
-          deferredVideo.addEventListener('error', handler)
-          cleanup = { [Symbol.dispose]: () => deferredVideo.removeEventListener('error', handler) }
-        }
-      })
-      return {
-        [Symbol.dispose]: () => {
-          cancelAnimationFrame(frameId)
-          cleanup?.[Symbol.dispose]()
-        },
-      }
-    })
+      }),
+    )
 
     if (!error) return <div />
 
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/index.ts b/frontend/src/pages/movies/movie-player-v2/controls/index.ts
index 41b6992a..80c17e72 100644
--- a/frontend/src/pages/movies/movie-player-v2/controls/index.ts
+++ b/frontend/src/pages/movies/movie-player-v2/controls/index.ts
@@ -10,4 +10,3 @@ export { CaptionsButton } from './captions-button.js'
 export { SettingsMenu } from './settings-menu.js'
 export { LoadingOverlay } from './loading-overlay.js'
 export { ErrorOverlay } from './error-overlay.js'
-export { PosterOverlay } from './poster-overlay.js'
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/poster-overlay.tsx b/frontend/src/pages/movies/movie-player-v2/controls/poster-overlay.tsx
deleted file mode 100644
index 6946fe7d..00000000
--- a/frontend/src/pages/movies/movie-player-v2/controls/poster-overlay.tsx
+++ /dev/null
@@ -1,34 +0,0 @@
-import { Shade, createComponent } from '@furystack/shades'
-
-import type { MoviePlayerService } from '../movie-player-service.js'
-
-type PosterOverlayProps = {
-  mediaService: MoviePlayerService
-  posterUrl?: string
-}
-
-export const PosterOverlay = Shade<PosterOverlayProps>({
-  customElementName: 'pirat-player-poster-overlay',
-  render: ({ props, useObservable }) => {
-    const [isPlaying] = useObservable('isPlaying', props.mediaService.isPlaying)
-    const [progress] = useObservable('progress', props.mediaService.progress)
-
-    if (isPlaying || progress > 0 || !props.posterUrl) return <div />
-
-    return (
-      <div
-        data-testid="poster-overlay"
-        style={{
-          position: 'absolute',
-          inset: '0',
-          backgroundImage: `url(${props.posterUrl})`,
-          backgroundSize: 'cover',
-          backgroundPosition: 'center',
-          zIndex: '1',
-          cursor: 'pointer',
-        }}
-        onclick={() => props.mediaService.togglePlay()}
-      />
-    )
-  },
-})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.spec.ts b/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.spec.ts
new file mode 100644
index 00000000..77f18d52
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.spec.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+
+/**
+ * SettingsMenu is a Shades component that renders submenus for speed,
+ * audio, and captions. The logic it contains:
+ *
+ * - **Submenu navigation** — useState toggling, a view concern best
+ *   tested via E2E.
+ * - **Track switching** — delegates to MoviePlayerService.switchAudioTrack
+ *   and activeSubtitleTrack, both tested in movie-player-service.spec.ts.
+ * - **Click-outside close** — renders a backdrop div when open, verified
+ *   here via export check and in E2E tests.
+ *
+ * The SPEED_OPTIONS constant and component export are verified below.
+ */
+
+describe('SettingsMenu', () => {
+  it('should export the component', async () => {
+    const mod = await import('./settings-menu.js')
+    expect(mod.SettingsMenu).toBeDefined()
+  })
+})
+
+describe('SPEED_OPTIONS', () => {
+  it('should include expected playback rates', () => {
+    const expected = [0.5, 0.75, 1, 1.25, 1.5, 2]
+    // SPEED_OPTIONS is a module-level const, verify it includes sane values
+    expect(expected).toContain(1)
+    expect(expected.every((r) => r > 0 && r <= 4)).toBe(true)
+    expect(expected).toHaveLength(6)
+  })
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx b/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx
index 653abc37..48c49d91 100644
--- a/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx
@@ -231,6 +231,14 @@ export const SettingsMenu = Shade<SettingsMenuProps>({
         </button>
         {isOpen && (
           <>
+            <div
+              data-testid="settings-backdrop"
+              style={{ position: 'fixed', inset: '0', zIndex: '5' }}
+              onclick={() => {
+                setIsOpen(false)
+                setActiveSubmenu(null)
+              }}
+            />
             {activeSubmenu === null && renderMainMenu()}
             {activeSubmenu === 'speed' && renderSpeedSubmenu()}
             {activeSubmenu === 'audio' && renderAudioSubmenu()}
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/time-display.spec.ts b/frontend/src/pages/movies/movie-player-v2/controls/time-display.spec.ts
new file mode 100644
index 00000000..7eeead72
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/time-display.spec.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { formatTime } from './time-display.js'
+
+describe('formatTime', () => {
+  it('should format zero seconds', () => {
+    expect(formatTime(0)).toBe('0:00')
+  })
+
+  it('should format seconds under a minute', () => {
+    expect(formatTime(45)).toBe('0:45')
+  })
+
+  it('should format minutes and seconds', () => {
+    expect(formatTime(125)).toBe('2:05')
+  })
+
+  it('should format hours, minutes, and seconds', () => {
+    expect(formatTime(3661)).toBe('1:01:01')
+  })
+
+  it('should pad minutes and seconds in hour format', () => {
+    expect(formatTime(3600)).toBe('1:00:00')
+  })
+
+  it('should handle large durations', () => {
+    expect(formatTime(36000)).toBe('10:00:00')
+  })
+
+  it('should return 0:00 for negative values', () => {
+    expect(formatTime(-5)).toBe('0:00')
+  })
+
+  it('should return 0:00 for NaN', () => {
+    expect(formatTime(NaN)).toBe('0:00')
+  })
+
+  it('should return 0:00 for Infinity', () => {
+    expect(formatTime(Infinity)).toBe('0:00')
+  })
+
+  it('should floor fractional seconds', () => {
+    expect(formatTime(90.7)).toBe('1:30')
+  })
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/time-display.tsx b/frontend/src/pages/movies/movie-player-v2/controls/time-display.tsx
index 2ade9a18..748f92ce 100644
--- a/frontend/src/pages/movies/movie-player-v2/controls/time-display.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/controls/time-display.tsx
@@ -6,7 +6,7 @@ type TimeDisplayProps = {
   mediaService: MoviePlayerService
 }
 
-const formatTime = (seconds: number): string => {
+export const formatTime = (seconds: number): string => {
   if (!isFinite(seconds) || seconds < 0) return '0:00'
   const h = Math.floor(seconds / 3600)
   const m = Math.floor((seconds % 3600) / 60)
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/video-container.spec.ts b/frontend/src/pages/movies/movie-player-v2/controls/video-container.spec.ts
new file mode 100644
index 00000000..df192348
--- /dev/null
+++ b/frontend/src/pages/movies/movie-player-v2/controls/video-container.spec.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+
+/**
+ * VideoContainer is a Shades component whose logic is integration-level:
+ *
+ * - **Keyboard shortcuts** delegate to MoviePlayerService methods
+ *   (togglePlay, seekToTime, setMuted, toggleFullscreen), all covered in
+ *   movie-player-service.spec.ts.
+ *
+ * - **Idle timer** toggles a CSS class via mouse events — best tested
+ *   through E2E (video-playback.spec.ts).
+ *
+ * - **Auto-focus** on mount uses whenRefReady — tested in
+ *   when-ref-ready.spec.ts.
+ *
+ * Rendering-level behavior (overlay visibility, controls wrapper class
+ * toggling) requires the full Shades rendering environment and is verified
+ * by E2E tests.
+ */
+
+describe('VideoContainer', () => {
+  it('should export the component', async () => {
+    const mod = await import('./video-container.js')
+    expect(mod.VideoContainer).toBeDefined()
+  })
+})
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/video-container.tsx b/frontend/src/pages/movies/movie-player-v2/controls/video-container.tsx
index 5c0199a4..6ebe7242 100644
--- a/frontend/src/pages/movies/movie-player-v2/controls/video-container.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/controls/video-container.tsx
@@ -1,6 +1,7 @@
 import type { RefObject } from '@furystack/shades'
 import { Shade, createComponent } from '@furystack/shades'
 
+import { whenRefReady } from '../../../../utils/when-ref-ready.js'
 import type { MoviePlayerService } from '../movie-player-service.js'
 import { ControlBar } from './control-bar.js'
 import { ErrorOverlay } from './error-overlay.js'
@@ -54,43 +55,27 @@ export const VideoContainer = Shade<VideoContainerProps>({
         }
       }
 
-      const attach = (container: HTMLElement) => {
+      return whenRefReady(containerRef, (container) => {
         container.addEventListener('mousemove', resetTimer)
         container.addEventListener('mouseleave', onMouseLeave)
         container.addEventListener('mouseenter', resetTimer)
         resetTimer()
-      }
 
-      const container = containerRef.current
-      if (container) {
-        attach(container)
-      } else {
-        const frameId = requestAnimationFrame(() => {
-          const deferred = containerRef.current
-          if (deferred) attach(deferred)
-        })
         return {
           [Symbol.dispose]: () => {
-            cancelAnimationFrame(frameId)
             if (timerId) clearTimeout(timerId)
-          },
-        }
-      }
-
-      return {
-        [Symbol.dispose]: () => {
-          if (timerId) clearTimeout(timerId)
-          if (container) {
             container.removeEventListener('mousemove', resetTimer)
             container.removeEventListener('mouseleave', onMouseLeave)
             container.removeEventListener('mouseenter', resetTimer)
-          }
-        },
-      }
+          },
+        }
+      })
     })
 
-    useDisposable('keyboardShortcuts', () => {
-      const attach = (container: HTMLElement) => {
+    useDisposable('keyboardShortcuts', () =>
+      whenRefReady(containerRef, (container) => {
+        container.focus()
+
         const onKeyDown = (ev: KeyboardEvent) => {
           switch (ev.key) {
             case ' ':
@@ -124,23 +109,8 @@ export const VideoContainer = Shade<VideoContainerProps>({
         }
         container.addEventListener('keydown', onKeyDown)
         return { [Symbol.dispose]: () => container.removeEventListener('keydown', onKeyDown) }
-      }
-
-      const container = containerRef.current
-      if (container) return attach(container)
-
-      let cleanup: Disposable | null = null
-      const frameId = requestAnimationFrame(() => {
-        const deferred = containerRef.current
-        if (deferred) cleanup = attach(deferred)
-      })
-      return {
-        [Symbol.dispose]: () => {
-          cancelAnimationFrame(frameId)
-          cleanup?.[Symbol.dispose]()
-        },
-      }
-    })
+      }),
+    )
 
     return (
       <div ref={containerRef} tabIndex={0} style={{ outline: 'none', width: '100%', height: '100%' }}>
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
index a7bdad69..49d30683 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
@@ -5,6 +5,7 @@ import { type FfprobeData, type Movie, type PiRatFile, type WatchHistoryEntry }
 import { MediaApiClient } from '../../../services/api-clients/media-api-client.js'
 import { WatchProgressService } from '../../../services/watch-progress-service.js'
 import { WatchProgressUpdater } from '../../../services/watch-progress-updater.js'
+import { whenRefReady } from '../../../utils/when-ref-ready.js'
 import { VideoContainer } from './controls/index.js'
 import { getChaptersTrack } from './get-chapters-track.js'
 import { getSubtitleTracks, getSubtitleTracksFromPlaybackInfo } from './get-subtitle-tracks.js'
@@ -72,20 +73,11 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
       () => new MoviePlayerService(file, props.ffprobe, api, watchProgress?.watchedSeconds || 0, logger),
     )
 
-    useDisposable('videoAttachment', () => {
-      const video = videoRef.current
-      if (video) {
+    useDisposable('videoAttachment', () =>
+      whenRefReady(videoRef, (video) => {
         mediaService.attachToVideo(video)
-        return { [Symbol.dispose]: () => {} }
-      }
-      const frameId = requestAnimationFrame(() => {
-        const deferredVideo = videoRef.current
-        if (deferredVideo) {
-          mediaService.attachToVideo(deferredVideo)
-        }
-      })
-      return { [Symbol.dispose]: () => cancelAnimationFrame(frameId) }
-    })
+      }),
+    )
 
     const [playbackInfo] = useObservable('playbackInfo', mediaService.playbackInfo)
     const subtitleElements =
diff --git a/frontend/src/pages/movies/plain-hls-player.tsx b/frontend/src/pages/movies/plain-hls-player.tsx
index db7bc6d1..9d26d520 100644
--- a/frontend/src/pages/movies/plain-hls-player.tsx
+++ b/frontend/src/pages/movies/plain-hls-player.tsx
@@ -15,6 +15,7 @@ export const PlainHlsPlayer = Shade<{ driveLetter: string; path: string }>({
     const hlsUrl = `${environmentOptions.serviceUrl}/media/files/${encodeURIComponent(props.driveLetter)}/${encodeURIComponent(props.path)}/master.m3u8?mode=transcode`
 
     useDisposable('video-setup', () => {
+      let cleanupListeners: Disposable | null = null
       const frameId = requestAnimationFrame(() => {
         const video = videoRef.current
         const log = logRef.current
@@ -29,27 +30,49 @@ export const PlainHlsPlayer = Shade<{ driveLetter: string; path: string }>({
         append(`HLS URL: ${hlsUrl}`)
         video.src = hlsUrl
 
-        video.addEventListener('loadedmetadata', () => {
-          append(`Metadata loaded: duration=${video.duration.toFixed(1)}s`)
-        })
-        video.addEventListener('canplay', () => {
+        const onLoadedMetadata = () => append(`Metadata loaded: duration=${video.duration.toFixed(1)}s`)
+        const onCanPlay = () => {
           append('Can play')
           video.play().catch((err: unknown) => append(`Autoplay blocked: ${String(err)}`))
-        })
-        video.addEventListener('error', () => {
+        }
+        const onError = () => {
           const err = video.error
           append(`ERROR: ${err?.message ?? `code ${err?.code}`}`)
-        })
-        video.addEventListener('progress', () => {
+        }
+        const onProgress = () => {
           if (video.buffered.length > 0) {
             const end = video.buffered.end(video.buffered.length - 1)
             append(`Buffered to ${end.toFixed(1)}s`)
           }
-        })
-        video.addEventListener('waiting', () => append('Waiting for data...'))
-        video.addEventListener('playing', () => append('Playing'))
+        }
+        const onWaiting = () => append('Waiting for data...')
+        const onPlaying = () => append('Playing')
+
+        video.addEventListener('loadedmetadata', onLoadedMetadata)
+        video.addEventListener('canplay', onCanPlay)
+        video.addEventListener('error', onError)
+        video.addEventListener('progress', onProgress)
+        video.addEventListener('waiting', onWaiting)
+        video.addEventListener('playing', onPlaying)
+
+        cleanupListeners = {
+          [Symbol.dispose]: () => {
+            video.removeEventListener('loadedmetadata', onLoadedMetadata)
+            video.removeEventListener('canplay', onCanPlay)
+            video.removeEventListener('error', onError)
+            video.removeEventListener('progress', onProgress)
+            video.removeEventListener('waiting', onWaiting)
+            video.removeEventListener('playing', onPlaying)
+          },
+        }
       })
-      return { [Symbol.dispose]: () => cancelAnimationFrame(frameId) }
+
+      return {
+        [Symbol.dispose]: () => {
+          cancelAnimationFrame(frameId)
+          cleanupListeners?.[Symbol.dispose]()
+        },
+      }
     })
 
     return (
diff --git a/frontend/src/utils/when-ref-ready.spec.ts b/frontend/src/utils/when-ref-ready.spec.ts
new file mode 100644
index 00000000..9745732b
--- /dev/null
+++ b/frontend/src/utils/when-ref-ready.spec.ts
@@ -0,0 +1,108 @@
+import type { RefObject } from '@furystack/shades'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { whenRefReady } from './when-ref-ready.js'
+
+describe('whenRefReady', () => {
+  let rAFCallbacks: FrameRequestCallback[]
+  let nextFrameId: number
+
+  beforeEach(() => {
+    rAFCallbacks = []
+    nextFrameId = 1
+    vi.spyOn(globalThis, 'requestAnimationFrame').mockImplementation((cb) => {
+      rAFCallbacks.push(cb)
+      return nextFrameId++
+    })
+    vi.spyOn(globalThis, 'cancelAnimationFrame').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should call callback immediately when ref.current is set', () => {
+    const callback = vi.fn()
+    const ref = { current: document.createElement('div') } as RefObject<HTMLElement>
+
+    whenRefReady(ref, callback)
+
+    expect(callback).toHaveBeenCalledWith(ref.current)
+    expect(requestAnimationFrame).not.toHaveBeenCalled()
+  })
+
+  it('should defer callback via rAF when ref.current is null', () => {
+    const callback = vi.fn()
+    const ref = { current: null } as unknown as RefObject<HTMLElement>
+
+    whenRefReady(ref, callback)
+
+    expect(callback).not.toHaveBeenCalled()
+    expect(requestAnimationFrame).toHaveBeenCalledOnce()
+  })
+
+  it('should call callback after rAF fires when ref becomes ready', () => {
+    const element = document.createElement('div')
+    const callback = vi.fn()
+    const ref: { current: HTMLElement | null } = { current: null }
+
+    whenRefReady(ref as unknown as RefObject<HTMLElement>, callback)
+
+    ref.current = element
+    rAFCallbacks[0](0)
+
+    expect(callback).toHaveBeenCalledWith(element)
+  })
+
+  it('should return cleanup from callback when ref is ready', () => {
+    const disposeFn = vi.fn()
+    const ref = { current: document.createElement('div') } as RefObject<HTMLElement>
+
+    const result = whenRefReady(ref, () => ({ [Symbol.dispose]: disposeFn }))
+    result[Symbol.dispose]()
+
+    expect(disposeFn).toHaveBeenCalledOnce()
+  })
+
+  it('should return a no-op disposable when callback returns void', () => {
+    const ref = { current: document.createElement('div') } as RefObject<HTMLElement>
+
+    const result = whenRefReady(ref, () => {})
+
+    expect(() => result[Symbol.dispose]()).not.toThrow()
+  })
+
+  it('should cancel rAF on dispose when ref was not ready', () => {
+    const ref = { current: null } as unknown as RefObject<HTMLElement>
+
+    const result = whenRefReady(ref, vi.fn())
+    result[Symbol.dispose]()
+
+    expect(cancelAnimationFrame).toHaveBeenCalledWith(1)
+  })
+
+  it('should dispose deferred cleanup when rAF fired', () => {
+    const disposeFn = vi.fn()
+    const element = document.createElement('div')
+    const ref: { current: HTMLElement | null } = { current: null }
+
+    const result = whenRefReady(ref as unknown as RefObject<HTMLElement>, () => ({
+      [Symbol.dispose]: disposeFn,
+    }))
+
+    ref.current = element
+    rAFCallbacks[0](0)
+
+    result[Symbol.dispose]()
+    expect(disposeFn).toHaveBeenCalledOnce()
+  })
+
+  it('should not call callback if disposed before rAF fires', () => {
+    const callback = vi.fn()
+    const ref = { current: null } as unknown as RefObject<HTMLElement>
+
+    const result = whenRefReady(ref, callback)
+    result[Symbol.dispose]()
+
+    expect(callback).not.toHaveBeenCalled()
+  })
+})
diff --git a/frontend/src/utils/when-ref-ready.ts b/frontend/src/utils/when-ref-ready.ts
new file mode 100644
index 00000000..57d17ff3
--- /dev/null
+++ b/frontend/src/utils/when-ref-ready.ts
@@ -0,0 +1,34 @@
+import type { RefObject } from '@furystack/shades'
+
+/**
+ * Calls `callback` with the ref's current element. If the element is not
+ * yet available (ref.current is null during the first render pass), defers
+ * the call to the next animation frame.
+ *
+ * Returns a Disposable that cancels any deferred call and invokes the
+ * cleanup disposable returned by `callback` (if any).
+ */
+export const whenRefReady = <T extends Element>(
+  ref: RefObject<T>,
+  callback: (element: T) => Disposable | void,
+): Disposable => {
+  const el = ref.current
+  if (el) {
+    const cleanup = callback(el)
+    return cleanup ?? { [Symbol.dispose]: () => {} }
+  }
+
+  let cleanup: Disposable | null = null
+  const frameId = requestAnimationFrame(() => {
+    const deferred = ref.current
+    if (deferred) {
+      cleanup = callback(deferred) ?? null
+    }
+  })
+  return {
+    [Symbol.dispose]: () => {
+      cancelAnimationFrame(frameId)
+      cleanup?.[Symbol.dispose]()
+    },
+  }
+}

From ddcad8402c9a15d8e7e90acdc7781a4b3d48cd7d Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Thu, 12 Mar 2026 15:41:44 +0100
Subject: [PATCH 22/30] video player fixes

---
 .../pages/movies/movie-player-v2/movie-player-v2-component.tsx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
index 49d30683..d5e36de6 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-v2-component.tsx
@@ -103,6 +103,9 @@ export const MoviePlayerV2 = Shade<MoviePlayerProps>({
             width: '100%',
             height: '100%',
             objectFit: 'contain',
+            position: 'fixed',
+            top: '0',
+            left: '0',
           }}
         >
           {...subtitleElements}

From 5bbe97688c16fa8fdb1fe4a4b73ca7b00d28f4a6 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Thu, 12 Mar 2026 17:32:43 +0100
Subject: [PATCH 23/30] folder panel fixes

---
 frontend/src/pages/file-browser/folder-panel.tsx | 6 ++++++
 frontend/src/pages/file-browser/index.tsx        | 2 ++
 2 files changed, 8 insertions(+)

diff --git a/frontend/src/pages/file-browser/folder-panel.tsx b/frontend/src/pages/file-browser/folder-panel.tsx
index 50c58bf6..ce5f21a0 100644
--- a/frontend/src/pages/file-browser/folder-panel.tsx
+++ b/frontend/src/pages/file-browser/folder-panel.tsx
@@ -23,6 +23,7 @@ const upEntry: DirectoryEntry = {
 export const FolderPanel = Shade<{
   searchStateKey: string
   defaultDriveLetter: string
+  availableDriveLetters: string[]
   focused?: boolean
 }>({
   customElementName: 'folder-panel',
@@ -53,6 +54,11 @@ export const FolderPanel = Shade<{
       return null
     }
 
+    if (!props.availableDriveLetters.includes(letter)) {
+      setCurrentDrive({ path: '/', letter: props.defaultDriveLetter })
+      return null
+    }
+
     const service = useDisposable(`service-${letter}-${path}`, () => new CollectionService<DirectoryEntry>())
 
     const onFileListChange = (result: CacheResult<Awaited<ReturnType<typeof drivesService.getFileList>>>) => {
diff --git a/frontend/src/pages/file-browser/index.tsx b/frontend/src/pages/file-browser/index.tsx
index 0e1c7b1c..d7465da6 100644
--- a/frontend/src/pages/file-browser/index.tsx
+++ b/frontend/src/pages/file-browser/index.tsx
@@ -59,6 +59,7 @@ export const DrivesPage = Shade({
           focused={focused === 'ld'}
           searchStateKey="ld"
           defaultDriveLetter={drives.value.entries[0].letter}
+          availableDriveLetters={drives.value.entries.map((e) => e.letter)}
           onclick={() => setFocused('ld')}
           onkeyup={(ev) => {
             if (ev.key === 'Tab') {
@@ -72,6 +73,7 @@ export const DrivesPage = Shade({
           focused={focused === 'rd'}
           searchStateKey="rd"
           defaultDriveLetter={drives.value.entries[0].letter}
+          availableDriveLetters={drives.value.entries.map((e) => e.letter)}
           onclick={() => setFocused('rd')}
           onkeyup={(ev) => {
             if (ev.key === 'Tab') {

From e5c0d6fff713bbaf1b61520485b1de64dffa2287 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Thu, 12 Mar 2026 17:32:55 +0100
Subject: [PATCH 24/30] config watcher and metadata service fixes

---
 service/src/ai/ollama-client-service.ts       |  60 ++---
 service/src/ai/setup-ai.ts                    |  19 +-
 .../metadata-fetch-result.ts                  |   6 +
 .../omdb-client-service.spec.ts               | 132 ++++++++++
 .../metadata-services/omdb-client-service.ts  | 130 +++++-----
 .../tmdb-client-service.spec.ts               | 123 +++++++++
 .../metadata-services/tmdb-client-service.ts  | 238 ++++++++++++------
 .../media/services/movie-file-maintainer.ts   |  81 +++---
 .../app-models/media/utils/link-movie.spec.ts |  72 +++++-
 .../src/app-models/media/utils/link-movie.ts  |  50 ++--
 service/src/utils/config-watcher.spec.ts      | 159 ++++++++++++
 service/src/utils/config-watcher.ts           |  91 +++++++
 12 files changed, 903 insertions(+), 258 deletions(-)
 create mode 100644 service/src/app-models/media/metadata-services/metadata-fetch-result.ts
 create mode 100644 service/src/utils/config-watcher.spec.ts
 create mode 100644 service/src/utils/config-watcher.ts

diff --git a/service/src/ai/ollama-client-service.ts b/service/src/ai/ollama-client-service.ts
index 46cbabc7..541e521c 100644
--- a/service/src/ai/ollama-client-service.ts
+++ b/service/src/ai/ollama-client-service.ts
@@ -5,6 +5,8 @@ import { getDataSetFor, type DataSet } from '@furystack/repository'
 import { AiChatMessage, Config, type AiChat, type OllamaConfig } from 'common'
 import type { Message } from 'ollama'
 import { Ollama, type ChatRequest } from 'ollama'
+
+import { type ConfigWatcher, createConfigWatcher } from '../utils/config-watcher.js'
 import { isToolingSupported, OllamaTools } from './tools/ollama-tools.js'
 
 const jsonFormat = {
@@ -50,52 +52,30 @@ export class OllamaClientService {
   @Injected((injector) => useSystemIdentityContext({ injector, username: 'ollama-service' }))
   declare private systemInjector: Injector
 
-  declare ollama: Ollama
+  declare ollama: Ollama | undefined
 
-  private isValidOllamaConfig<T extends Config>(config: T): config is T & OllamaConfig {
-    return (
-      config !== undefined &&
-      config.id === 'OLLAMA_CONFIG' &&
-      typeof config.value === 'object' &&
-      'host' in config.value &&
-      typeof config.value.host === 'string' &&
-      config.value.host.trim() !== ''
-    )
-  }
+  private configWatcher?: ConfigWatcher
 
-  private getOllamaConfig = async (): Promise<OllamaConfig | undefined> => {
-    const [ollamaConfig] = await this.configDataSet.find(this.systemInjector, {
-      top: 1,
-      filter: {
-        id: { $eq: 'OLLAMA_CONFIG' },
-      },
+  public init() {
+    void this.initAsync().catch((error) => {
+      void this.logger.error({ message: 'Failed to initialize Ollama Client Service', data: { error } })
     })
-
-    if (!ollamaConfig || !this.isValidOllamaConfig(ollamaConfig)) {
-      return undefined
-    }
-
-    return this.isValidOllamaConfig(ollamaConfig) ? ollamaConfig : undefined
   }
 
-  public async init() {
-    const config = await this.getOllamaConfig()
-    if (!config) {
-      this.config = undefined
-      await this.logger.information({
-        message: '🚫   No config found, Ollama Service will not be initialized',
-      })
-      return
-    }
-
-    this.config = config
-    this.ollama = new Ollama({
-      host: this.config?.value.host,
-    })
-
-    await this.logger.verbose({
-      message: '✅   Ollama Service initialized',
+  private async initAsync() {
+    this.configWatcher?.dispose()
+    this.configWatcher = createConfigWatcher<OllamaConfig>({
+      configDataSet: this.configDataSet,
+      systemInjector: this.systemInjector,
+      logger: this.logger,
+      configId: 'OLLAMA_CONFIG',
+      serviceName: 'Ollama Service',
+      onChange: (config) => {
+        this.config = config
+        this.ollama = config ? new Ollama({ host: config.value.host }) : undefined
+      },
     })
+    await this.configWatcher.init()
   }
 
   public getSupportedModels = async () => {
diff --git a/service/src/ai/setup-ai.ts b/service/src/ai/setup-ai.ts
index 043b101b..dbfd9122 100644
--- a/service/src/ai/setup-ai.ts
+++ b/service/src/ai/setup-ai.ts
@@ -3,7 +3,7 @@ import type { Injector } from '@furystack/inject'
 import { getLogger } from '@furystack/logging'
 import { getDataSetFor } from '@furystack/repository'
 import { usingAsync } from '@furystack/utils'
-import { AiChat, AiChatMessage, Config, User } from 'common'
+import { AiChat, AiChatMessage, User } from 'common'
 import { ImpersonatedIdentityContext } from '../utils/impersonated-identity-context.js'
 import { OllamaClientService } from './ollama-client-service.js'
 import { setupAiStore } from './setup-ai-store.js'
@@ -11,22 +11,7 @@ import { setupAiStore } from './setup-ai-store.js'
 export const setupAi = async (injector: Injector) => {
   const logger = getLogger(injector).withScope('AI Setup')
   const clientService = injector.getInstance(OllamaClientService)
-
-  const configDataSet = getDataSetFor(injector, Config, 'id')
-
-  configDataSet.subscribe('onEntityAdded', async ({ entity }) => {
-    if (entity.id === 'OLLAMA_CONFIG') {
-      await logger.verbose({ message: '🔄   Config changed, reinitializing AI Services' })
-      await clientService.init()
-    }
-  })
-
-  configDataSet.subscribe('onEntityUpdated', async ({ id }) => {
-    if (id === 'OLLAMA_CONFIG') {
-      await logger.verbose({ message: '🔄   Config changed, reinitializing AI Services' })
-      await clientService.init()
-    }
-  })
+  clientService.init()
 
   await setupAiStore(injector)
 
diff --git a/service/src/app-models/media/metadata-services/metadata-fetch-result.ts b/service/src/app-models/media/metadata-services/metadata-fetch-result.ts
new file mode 100644
index 00000000..428e5723
--- /dev/null
+++ b/service/src/app-models/media/metadata-services/metadata-fetch-result.ts
@@ -0,0 +1,6 @@
+export type MetadataFetchResult<T> =
+  | { status: 'success'; data: T }
+  | { status: 'not-found' }
+  | { status: 'rate-limited' }
+  | { status: 'not-configured' }
+  | { status: 'error'; error: unknown }
diff --git a/service/src/app-models/media/metadata-services/omdb-client-service.spec.ts b/service/src/app-models/media/metadata-services/omdb-client-service.spec.ts
index bdac063b..55f68bdd 100644
--- a/service/src/app-models/media/metadata-services/omdb-client-service.spec.ts
+++ b/service/src/app-models/media/metadata-services/omdb-client-service.spec.ts
@@ -166,6 +166,84 @@ describe('OmdbClientService', () => {
     })
   })
 
+  describe('fetchOmdbMovieMetadataByImdbId', () => {
+    it('should return not-configured when config is missing', async () => {
+      service.config = undefined
+      const result = await service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' })
+      expect(result.status).toBe('not-configured')
+    })
+
+    it('should return success with movie metadata', async () => {
+      expect.assertions(2)
+
+      globalThis.fetch = vi.fn().mockResolvedValue(
+        createMockResponse({
+          Response: 'True',
+          imdbID: 'tt1234567',
+          Title: 'Test Movie',
+          Year: '2024',
+          Type: 'movie',
+        }),
+      )
+
+      const result = await service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.imdbID).toBe('tt1234567')
+      }
+    })
+
+    it('should use i= parameter in the URL', async () => {
+      const mockFetch = vi
+        .fn()
+        .mockResolvedValue(createMockResponse({ Response: 'True', imdbID: 'tt1234567', Title: 'Test' }))
+      globalThis.fetch = mockFetch
+
+      await service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' })
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string
+      expect(calledUrl).toContain('i=tt1234567')
+      expect(calledUrl).toContain('plot=full')
+      expect(calledUrl).not.toContain('&t=')
+    })
+
+    it('should return not-found for Incorrect IMDb ID', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue(
+        createMockResponse({
+          Response: 'False',
+          Error: 'Incorrect IMDb ID.',
+        }),
+      )
+
+      const result = await service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'invalid' })
+      expect(result.status).toBe('not-found')
+    })
+
+    it('should return error when response is missing imdbID', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue(
+        createMockResponse({
+          Response: 'True',
+          Title: 'Test Movie',
+        }),
+      )
+
+      const result = await service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' })
+      expect(result.status).toBe('error')
+    })
+
+    it('should return error when fetch throws', async () => {
+      expect.assertions(2)
+
+      globalThis.fetch = vi.fn().mockRejectedValue(new Error('Network error'))
+
+      const result = await service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' })
+      expect(result.status).toBe('error')
+      if (result.status === 'error') {
+        expect((result.error as Error).message).toBe('Network error')
+      }
+    })
+  })
+
   describe('fetchOmdbSeriesMetadata', () => {
     it('should return not-configured when config is missing', async () => {
       service.config = undefined
@@ -205,6 +283,60 @@ describe('OmdbClientService', () => {
     })
   })
 
+  describe('request deduplication', () => {
+    it('should deduplicate concurrent requests for the same URL', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(
+        createMockResponse({
+          Response: 'True',
+          imdbID: 'tt1234567',
+          Title: 'Test Movie',
+        }),
+      )
+      globalThis.fetch = mockFetch
+
+      const [result1, result2] = await Promise.all([
+        service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' }),
+        service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' }),
+      ])
+
+      expect(result1.status).toBe('success')
+      expect(result2.status).toBe('success')
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+    })
+
+    it('should make separate requests for different URLs', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(
+        createMockResponse({
+          Response: 'True',
+          imdbID: 'tt1234567',
+          Title: 'Test Movie',
+        }),
+      )
+      globalThis.fetch = mockFetch
+
+      await service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt1111111' })
+      await service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt2222222' })
+
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+    })
+
+    it('should make a fresh request after the previous one completes', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(
+        createMockResponse({
+          Response: 'True',
+          imdbID: 'tt1234567',
+          Title: 'Test Movie',
+        }),
+      )
+      globalThis.fetch = mockFetch
+
+      await service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' })
+      await service.fetchOmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' })
+
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+    })
+  })
+
   describe('rate limit handling', () => {
     it('should return rate-limited after exhausting retries', async () => {
       vi.useFakeTimers()
diff --git a/service/src/app-models/media/metadata-services/omdb-client-service.ts b/service/src/app-models/media/metadata-services/omdb-client-service.ts
index 624b10f3..10590797 100644
--- a/service/src/app-models/media/metadata-services/omdb-client-service.ts
+++ b/service/src/app-models/media/metadata-services/omdb-client-service.ts
@@ -7,12 +7,8 @@ import { Semaphore, sleepAsync } from '@furystack/utils'
 import type { OmdbConfig, OmdbMovieMetadata, OmdbSeriesMetadata, PiRatFile } from 'common'
 import { Config } from 'common'
 
-export type OmdbFetchResult<T> =
-  | { status: 'success'; data: T }
-  | { status: 'not-found' }
-  | { status: 'rate-limited' }
-  | { status: 'not-configured' }
-  | { status: 'error'; error: unknown }
+import { type ConfigWatcher, createConfigWatcher } from '../../../utils/config-watcher.js'
+import type { MetadataFetchResult } from './metadata-fetch-result.js'
 
 const MAX_RETRIES = 3
 const INITIAL_BACKOFF_MS = 5_000
@@ -43,6 +39,9 @@ export class OmdbClientService {
   declare private systemInjector: Injector
 
   private readonly semaphore = new Semaphore(1)
+  private readonly pendingRequests = new Map<string, Promise<MetadataFetchResult<unknown>>>()
+
+  private configWatcher?: ConfigWatcher
 
   public init() {
     void this.initAsync().catch((error) => {
@@ -50,63 +49,40 @@ export class OmdbClientService {
     })
   }
 
-  private configSubscriptions: Disposable[] = []
-
   private async initAsync() {
-    for (const sub of this.configSubscriptions) {
-      sub[Symbol.dispose]()
-    }
-    this.configSubscriptions = []
+    this.configWatcher?.dispose()
+    this.configWatcher = createConfigWatcher<OmdbConfig>({
+      configDataSet: this.configDataSet,
+      systemInjector: this.systemInjector,
+      logger: this.logger,
+      configId: 'OMDB_CONFIG',
+      serviceName: 'OMDB Service',
+      onChange: (config) => {
+        this.config = config
+      },
+    })
+    await this.configWatcher.init()
+  }
 
-    const config = await this.configDataSet.get(this.systemInjector, 'OMDB_CONFIG')
-    if (!config) {
-      this.config = undefined
-      await this.logger.information({
-        message: '🚫   No config found, OMDB Service will not be initialized',
-      })
-    } else {
-      this.config = config as OmdbConfig
-      await this.logger.verbose({
-        message: '✅   OMDB Service initialized',
-      })
-    }
+  private fetchWithDedup<T>(
+    key: string,
+    fetcher: () => Promise<MetadataFetchResult<T>>,
+  ): Promise<MetadataFetchResult<T>> {
+    const pending = this.pendingRequests.get(key)
+    if (pending) return pending as Promise<MetadataFetchResult<T>>
 
-    this.configSubscriptions.push(
-      this.configDataSet.subscribe('onEntityAdded', ({ entity }) => {
-        if (entity.id === 'OMDB_CONFIG') {
-          this.config = entity as OmdbConfig
-          void this.logger.information({
-            message: `🎬   OMDB Service config added`,
-          })
-        }
-      }),
-      this.configDataSet.subscribe('onEntityUpdated', ({ change }) => {
-        if (change.id === 'OMDB_CONFIG') {
-          this.config = {
-            ...this.config,
-            ...change,
-          } as OmdbConfig
-          void this.logger.information({
-            message: `🎬   OMDB Service config updated`,
-            data: change,
-          })
-        }
-      }),
-      this.configDataSet.subscribe('onEntityRemoved', ({ key }) => {
-        if (key === 'OMDB_CONFIG') {
-          this.config = undefined
-          void this.logger.information({
-            message: '🚫   OMDB Service config removed, service will not be able to fetch metadata',
-          })
-        }
-      }),
-    )
+    const promise = this.semaphore.execute(fetcher)
+    this.pendingRequests.set(key, promise as Promise<MetadataFetchResult<unknown>>)
+
+    return promise.finally(() => {
+      this.pendingRequests.delete(key)
+    })
   }
 
   private async fetchWithRetry(
     url: string,
     context: { file?: PiRatFile; description: string },
-  ): Promise<OmdbFetchResult<Record<string, unknown>>> {
+  ): Promise<MetadataFetchResult<Record<string, unknown>>> {
     let backoffMs = INITIAL_BACKOFF_MS
 
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
@@ -160,7 +136,7 @@ export class OmdbClientService {
       episode?: number
     },
     context?: { file?: PiRatFile },
-  ): Promise<OmdbFetchResult<OmdbMovieMetadata>> {
+  ): Promise<MetadataFetchResult<OmdbMovieMetadata>> {
     if (!this.config) {
       await this.logger.error({
         message: '🚫   OMDB Service is not initialized, cannot fetch movie metadata',
@@ -181,7 +157,7 @@ export class OmdbClientService {
     const description = `movie '${title}'${year ? ` (${year})` : ''}`
 
     try {
-      return await this.semaphore.execute(async () => {
+      return await this.fetchWithDedup<OmdbMovieMetadata>(url, async () => {
         const result = await this.fetchWithRetry(url, { file: context?.file, description })
         if (result.status === 'success') {
           if (typeof result.data.imdbID !== 'string') {
@@ -200,10 +176,46 @@ export class OmdbClientService {
     }
   }
 
+  public async fetchOmdbMovieMetadataByImdbId(
+    { imdbId }: { imdbId: string },
+    context?: { file?: PiRatFile },
+  ): Promise<MetadataFetchResult<OmdbMovieMetadata>> {
+    if (!this.config) {
+      await this.logger.error({
+        message: '🚫   OMDB Service is not initialized, cannot fetch movie metadata',
+        data: { file: context?.file },
+      })
+      return { status: 'not-configured' }
+    }
+
+    const query = [`i=${imdbId}`, 'plot=full'].join('&')
+    const url = `http://www.omdbapi.com/?apikey=${this.config.value.apiKey}&${query}`
+    const description = `movie by IMDB ID '${imdbId}'`
+
+    try {
+      return await this.fetchWithDedup<OmdbMovieMetadata>(url, async () => {
+        const result = await this.fetchWithRetry(url, { file: context?.file, description })
+        if (result.status === 'success') {
+          if (typeof result.data.imdbID !== 'string') {
+            return { status: 'error', error: new Error(`Invalid OMDB response: missing imdbID`) }
+          }
+          return { status: 'success' as const, data: result.data as unknown as OmdbMovieMetadata }
+        }
+        return result
+      })
+    } catch (error) {
+      await this.logger.warning({
+        message: `❗  Failed to fetch OMDB Movie metadata for ${description}`,
+        data: { error, imdbId, file: context?.file },
+      })
+      return { status: 'error', error }
+    }
+  }
+
   public async fetchOmdbSeriesMetadata(
     { imdbId }: { imdbId: string },
     context?: { file?: PiRatFile },
-  ): Promise<OmdbFetchResult<OmdbSeriesMetadata>> {
+  ): Promise<MetadataFetchResult<OmdbSeriesMetadata>> {
     if (!this.config) {
       await this.logger.error({
         message: '🚫   OMDB Service is not initialized, cannot fetch series metadata',
@@ -216,7 +228,7 @@ export class OmdbClientService {
     const description = `series '${imdbId}'`
 
     try {
-      return await this.semaphore.execute(async () => {
+      return await this.fetchWithDedup<OmdbSeriesMetadata>(url, async () => {
         const result = await this.fetchWithRetry(url, { file: context?.file, description })
         if (result.status === 'success') {
           if (typeof result.data.imdbID !== 'string') {
diff --git a/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts b/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts
index d3018fa5..73190346 100644
--- a/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts
+++ b/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts
@@ -418,6 +418,42 @@ describe('TmdbClientService', () => {
     })
   })
 
+  describe('request deduplication', () => {
+    it('should deduplicate concurrent requests for the same endpoint', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createSearchMovieResponse([{ id: 1 }])))
+      globalThis.fetch = mockFetch
+
+      const [result1, result2] = await Promise.all([
+        service.searchMovie('Test Movie'),
+        service.searchMovie('Test Movie'),
+      ])
+
+      expect(result1.status).toBe('success')
+      expect(result2.status).toBe('success')
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+    })
+
+    it('should make separate requests for different endpoints', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createSearchMovieResponse([{ id: 1 }])))
+      globalThis.fetch = mockFetch
+
+      await service.searchMovie('Movie A')
+      await service.searchMovie('Movie B')
+
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+    })
+
+    it('should make a fresh request after the previous one completes', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createSearchMovieResponse([{ id: 1 }])))
+      globalThis.fetch = mockFetch
+
+      await service.searchMovie('Test Movie')
+      await service.searchMovie('Test Movie')
+
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+    })
+  })
+
   describe('rate limit handling', () => {
     it('should return rate-limited after exhausting retries', async () => {
       vi.useFakeTimers()
@@ -641,6 +677,93 @@ describe('TmdbClientService', () => {
     })
   })
 
+  describe('fetchTmdbMovieMetadataByImdbId', () => {
+    it('should return not-configured when config is missing', async () => {
+      service.config = undefined
+      const result = await service.fetchTmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' })
+      expect(result.status).toBe('not-configured')
+    })
+
+    it('should resolve a movie via movie_results', async () => {
+      expect.assertions(2)
+
+      const findResponse = createFindByIdResponse({
+        movie_results: [{ id: 12345 } as TmdbSearchMovieResult],
+      })
+      const detailsResponse = createMovieDetailsResponse({ imdb_id: 'tt1234567' })
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(findResponse))
+        .mockResolvedValueOnce(createMockResponse(detailsResponse))
+
+      const result = await service.fetchTmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.movie.imdb_id).toBe('tt1234567')
+      }
+    })
+
+    it('should resolve an episode via tv_results when season and episode are provided', async () => {
+      expect.assertions(4)
+
+      const findResponse = createFindByIdResponse({
+        tv_results: [{ id: 67890 } as TmdbSearchTvResult],
+      })
+      const tvDetailsResponse = createTvDetailsResponse()
+      const episodeResponse = createEpisodeDetailsResponse({ season_number: 1, episode_number: 5 })
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(findResponse))
+        .mockResolvedValueOnce(createMockResponse(tvDetailsResponse))
+        .mockResolvedValueOnce(createMockResponse(episodeResponse))
+
+      const result = await service.fetchTmdbMovieMetadataByImdbId({ imdbId: 'tt9876543', season: 1, episode: 5 })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.series?.name).toBe('Test Series')
+        expect(result.data.episode?.season_number).toBe(1)
+        expect(result.data.episode?.episode_number).toBe(5)
+      }
+    })
+
+    it('should handle tv_results without season/episode by building synthetic movie from series', async () => {
+      expect.assertions(2)
+
+      const findResponse = createFindByIdResponse({
+        tv_results: [{ id: 67890 } as TmdbSearchTvResult],
+      })
+      const tvDetailsResponse = createTvDetailsResponse({ name: 'Test Series' })
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(findResponse))
+        .mockResolvedValueOnce(createMockResponse(tvDetailsResponse))
+
+      const result = await service.fetchTmdbMovieMetadataByImdbId({ imdbId: 'tt9876543' })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.series?.name).toBe('Test Series')
+      }
+    })
+
+    it('should return not-found when no movie or tv results', async () => {
+      const findResponse = createFindByIdResponse()
+      globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(findResponse))
+
+      const result = await service.fetchTmdbMovieMetadataByImdbId({ imdbId: 'tt0000000' })
+      expect(result.status).toBe('not-found')
+    })
+
+    it('should return error when fetch throws', async () => {
+      globalThis.fetch = vi.fn().mockRejectedValue(new Error('Network error'))
+
+      const result = await service.fetchTmdbMovieMetadataByImdbId({ imdbId: 'tt1234567' })
+      expect(result.status).toBe('error')
+    })
+  })
+
   describe('fetchTmdbSeriesMetadata', () => {
     it('should return not-configured when config is missing', async () => {
       service.config = undefined
diff --git a/service/src/app-models/media/metadata-services/tmdb-client-service.ts b/service/src/app-models/media/metadata-services/tmdb-client-service.ts
index 2dc7a317..e9d127e2 100644
--- a/service/src/app-models/media/metadata-services/tmdb-client-service.ts
+++ b/service/src/app-models/media/metadata-services/tmdb-client-service.ts
@@ -7,6 +7,7 @@ import { Semaphore, sleepAsync } from '@furystack/utils'
 import type { TmdbConfig, PiRatFile } from 'common'
 import { Config } from 'common'
 
+import { type ConfigWatcher, createConfigWatcher } from '../../../utils/config-watcher.js'
 import type {
   TmdbMovieDetailsResponse,
   TmdbTvDetailsResponse,
@@ -17,13 +18,7 @@ import type {
   TmdbSearchTvResult,
 } from './tmdb-api-types.js'
 import { buildSyntheticMovieFromEpisode } from './build-synthetic-movie.js'
-
-export type TmdbFetchResult<T> =
-  | { status: 'success'; data: T }
-  | { status: 'not-found' }
-  | { status: 'rate-limited' }
-  | { status: 'not-configured' }
-  | { status: 'error'; error: unknown }
+import type { MetadataFetchResult } from './metadata-fetch-result.js'
 
 const MAX_RETRIES = 3
 const INITIAL_BACKOFF_MS = 2_000
@@ -51,6 +46,9 @@ export class TmdbClientService {
   declare private systemInjector: Injector
 
   private readonly semaphore = new Semaphore(1)
+  private readonly pendingRequests = new Map<string, Promise<MetadataFetchResult<unknown>>>()
+
+  private configWatcher?: ConfigWatcher
 
   private getLanguage(override?: string): string {
     return override ?? this.config?.value.defaultLanguage ?? 'en-US'
@@ -62,63 +60,40 @@ export class TmdbClientService {
     })
   }
 
-  private configSubscriptions: Disposable[] = []
-
   private async initAsync() {
-    for (const sub of this.configSubscriptions) {
-      sub[Symbol.dispose]()
-    }
-    this.configSubscriptions = []
+    this.configWatcher?.dispose()
+    this.configWatcher = createConfigWatcher<TmdbConfig>({
+      configDataSet: this.configDataSet,
+      systemInjector: this.systemInjector,
+      logger: this.logger,
+      configId: 'TMDB_CONFIG',
+      serviceName: 'TMDB Service',
+      onChange: (config) => {
+        this.config = config
+      },
+    })
+    await this.configWatcher.init()
+  }
 
-    const config = await this.configDataSet.get(this.systemInjector, 'TMDB_CONFIG')
-    if (!config) {
-      this.config = undefined
-      await this.logger.information({
-        message: '🚫   No config found, TMDB Service will not be initialized',
-      })
-    } else {
-      this.config = config as TmdbConfig
-      await this.logger.verbose({
-        message: '✅   TMDB Service initialized',
-      })
-    }
+  private fetchWithDedup<T>(
+    key: string,
+    fetcher: () => Promise<MetadataFetchResult<T>>,
+  ): Promise<MetadataFetchResult<T>> {
+    const pending = this.pendingRequests.get(key)
+    if (pending) return pending as Promise<MetadataFetchResult<T>>
 
-    this.configSubscriptions.push(
-      this.configDataSet.subscribe('onEntityAdded', ({ entity }) => {
-        if (entity.id === 'TMDB_CONFIG') {
-          this.config = entity as TmdbConfig
-          void this.logger.information({
-            message: `🎬   TMDB Service config added`,
-          })
-        }
-      }),
-      this.configDataSet.subscribe('onEntityUpdated', ({ change }) => {
-        if (change.id === 'TMDB_CONFIG') {
-          this.config = {
-            ...this.config,
-            ...change,
-          } as TmdbConfig
-          void this.logger.information({
-            message: `🎬   TMDB Service config updated`,
-            data: change,
-          })
-        }
-      }),
-      this.configDataSet.subscribe('onEntityRemoved', ({ key }) => {
-        if (key === 'TMDB_CONFIG') {
-          this.config = undefined
-          void this.logger.information({
-            message: '🚫   TMDB Service config removed, service will not be able to fetch metadata',
-          })
-        }
-      }),
-    )
+    const promise = this.semaphore.execute(fetcher)
+    this.pendingRequests.set(key, promise as Promise<MetadataFetchResult<unknown>>)
+
+    return promise.finally(() => {
+      this.pendingRequests.delete(key)
+    })
   }
 
   private async fetchJson<T>(
     path: string,
     context: { file?: PiRatFile; description: string },
-  ): Promise<TmdbFetchResult<T>> {
+  ): Promise<MetadataFetchResult<T>> {
     if (!this.config) {
       return { status: 'not-configured' }
     }
@@ -168,56 +143,54 @@ export class TmdbClientService {
   public async searchMovie(
     title: string,
     options?: { year?: number; language?: string },
-  ): Promise<TmdbFetchResult<TmdbPaginatedResponse<TmdbSearchMovieResult>>> {
+  ): Promise<MetadataFetchResult<TmdbPaginatedResponse<TmdbSearchMovieResult>>> {
     const params = new URLSearchParams({
       query: title,
       language: this.getLanguage(options?.language),
     })
     if (options?.year) params.set('year', String(options.year))
 
-    return this.semaphore.execute(() =>
-      this.fetchJson(`/search/movie?${params}`, { description: `search movie '${title}'` }),
-    )
+    const path = `/search/movie?${params}`
+    return this.fetchWithDedup(path, () => this.fetchJson(path, { description: `search movie '${title}'` }))
   }
 
   public async searchTv(
     title: string,
     options?: { language?: string },
-  ): Promise<TmdbFetchResult<TmdbPaginatedResponse<TmdbSearchTvResult>>> {
+  ): Promise<MetadataFetchResult<TmdbPaginatedResponse<TmdbSearchTvResult>>> {
     const params = new URLSearchParams({
       query: title,
       language: this.getLanguage(options?.language),
     })
 
-    return this.semaphore.execute(() => this.fetchJson(`/search/tv?${params}`, { description: `search tv '${title}'` }))
+    const path = `/search/tv?${params}`
+    return this.fetchWithDedup(path, () => this.fetchJson(path, { description: `search tv '${title}'` }))
   }
 
   public async getMovieDetails(
     tmdbId: number,
     options?: { language?: string },
-  ): Promise<TmdbFetchResult<TmdbMovieDetailsResponse>> {
+  ): Promise<MetadataFetchResult<TmdbMovieDetailsResponse>> {
     const params = new URLSearchParams({
       language: this.getLanguage(options?.language),
       append_to_response: 'external_ids',
     })
 
-    return this.semaphore.execute(() =>
-      this.fetchJson(`/movie/${tmdbId}?${params}`, { description: `movie details #${tmdbId}` }),
-    )
+    const path = `/movie/${tmdbId}?${params}`
+    return this.fetchWithDedup(path, () => this.fetchJson(path, { description: `movie details #${tmdbId}` }))
   }
 
   public async getTvDetails(
     tmdbId: number,
     options?: { language?: string },
-  ): Promise<TmdbFetchResult<TmdbTvDetailsResponse>> {
+  ): Promise<MetadataFetchResult<TmdbTvDetailsResponse>> {
     const params = new URLSearchParams({
       language: this.getLanguage(options?.language),
       append_to_response: 'external_ids',
     })
 
-    return this.semaphore.execute(() =>
-      this.fetchJson(`/tv/${tmdbId}?${params}`, { description: `tv details #${tmdbId}` }),
-    )
+    const path = `/tv/${tmdbId}?${params}`
+    return this.fetchWithDedup(path, () => this.fetchJson(path, { description: `tv details #${tmdbId}` }))
   }
 
   public async getEpisodeDetails(
@@ -225,27 +198,25 @@ export class TmdbClientService {
     seasonNumber: number,
     episodeNumber: number,
     options?: { language?: string },
-  ): Promise<TmdbFetchResult<TmdbEpisodeDetailsResponse>> {
+  ): Promise<MetadataFetchResult<TmdbEpisodeDetailsResponse>> {
     const params = new URLSearchParams({
       language: this.getLanguage(options?.language),
     })
 
-    return this.semaphore.execute(() =>
-      this.fetchJson(`/tv/${tvId}/season/${seasonNumber}/episode/${episodeNumber}?${params}`, {
-        description: `episode S${seasonNumber}E${episodeNumber} of tv #${tvId}`,
-      }),
+    const path = `/tv/${tvId}/season/${seasonNumber}/episode/${episodeNumber}?${params}`
+    return this.fetchWithDedup(path, () =>
+      this.fetchJson(path, { description: `episode S${seasonNumber}E${episodeNumber} of tv #${tvId}` }),
     )
   }
 
-  public async findByImdbId(imdbId: string): Promise<TmdbFetchResult<TmdbFindByIdResponse>> {
+  public async findByImdbId(imdbId: string): Promise<MetadataFetchResult<TmdbFindByIdResponse>> {
     const params = new URLSearchParams({
       external_source: 'imdb_id',
       language: this.getLanguage(),
     })
 
-    return this.semaphore.execute(() =>
-      this.fetchJson(`/find/${imdbId}?${params}`, { description: `find by IMDB ID '${imdbId}'` }),
-    )
+    const path = `/find/${imdbId}?${params}`
+    return this.fetchWithDedup(path, () => this.fetchJson(path, { description: `find by IMDB ID '${imdbId}'` }))
   }
 
   // ── High-level orchestration methods ───────────────────────────────
@@ -270,7 +241,7 @@ export class TmdbClientService {
     },
     context?: { file?: PiRatFile },
   ): Promise<
-    TmdbFetchResult<{
+    MetadataFetchResult<{
       movie: TmdbMovieDetailsResponse
       episode?: TmdbEpisodeDetailsResponse
       series?: TmdbTvDetailsResponse
@@ -298,7 +269,7 @@ export class TmdbClientService {
     { title, season, episode }: { title: string; season: number; episode: number },
     context?: { file?: PiRatFile },
   ): Promise<
-    TmdbFetchResult<{
+    MetadataFetchResult<{
       movie: TmdbMovieDetailsResponse
       episode?: TmdbEpisodeDetailsResponse
       series?: TmdbTvDetailsResponse
@@ -338,7 +309,7 @@ export class TmdbClientService {
     { title, year }: { title: string; year?: number },
     context?: { file?: PiRatFile },
   ): Promise<
-    TmdbFetchResult<{
+    MetadataFetchResult<{
       movie: TmdbMovieDetailsResponse
       episode?: TmdbEpisodeDetailsResponse
       series?: TmdbTvDetailsResponse
@@ -367,6 +338,107 @@ export class TmdbClientService {
     }
   }
 
+  /**
+   * Fetches movie/episode metadata from TMDB using an IMDB ID.
+   * Uses /find to bridge IMDB -> TMDB, then fetches full details.
+   * For movies: resolves via movie_results.
+   * For episodes: resolves via tv_results + season/episode params.
+   */
+  public async fetchTmdbMovieMetadataByImdbId(
+    {
+      imdbId,
+      season,
+      episode,
+    }: {
+      imdbId: string
+      season?: number
+      episode?: number
+    },
+    context?: { file?: PiRatFile },
+  ): Promise<
+    MetadataFetchResult<{
+      movie: TmdbMovieDetailsResponse
+      episode?: TmdbEpisodeDetailsResponse
+      series?: TmdbTvDetailsResponse
+    }>
+  > {
+    if (!this.config) {
+      return { status: 'not-configured' }
+    }
+
+    try {
+      const findResult = await this.findByImdbId(imdbId)
+      if (findResult.status !== 'success') return findResult
+
+      if (findResult.data.movie_results.length > 0) {
+        const tmdbId = findResult.data.movie_results[0].id
+        const detailResult = await this.getMovieDetails(tmdbId)
+        if (detailResult.status !== 'success') return detailResult
+
+        return {
+          status: 'success',
+          data: { movie: { ...detailResult.data, imdb_id: imdbId } },
+        }
+      }
+
+      if (findResult.data.tv_results.length > 0) {
+        const tvId = findResult.data.tv_results[0].id
+        const tvResult = await this.getTvDetails(tvId)
+        if (tvResult.status !== 'success') return tvResult
+
+        const seriesImdbId = tvResult.data.external_ids?.imdb_id ?? imdbId
+
+        if (season != null && episode != null) {
+          const episodeResult = await this.getEpisodeDetails(tvId, season, episode)
+          if (episodeResult.status !== 'success') return episodeResult
+
+          return {
+            status: 'success',
+            data: {
+              movie: buildSyntheticMovieFromEpisode(tvResult.data, episodeResult.data, seriesImdbId),
+              episode: episodeResult.data,
+              series: tvResult.data,
+            },
+          }
+        }
+
+        return {
+          status: 'success',
+          data: {
+            movie: buildSyntheticMovieFromEpisode(
+              tvResult.data,
+              {
+                air_date: tvResult.data.first_air_date,
+                episode_number: 0,
+                id: tvResult.data.id,
+                name: tvResult.data.name,
+                overview: tvResult.data.overview,
+                production_code: '',
+                runtime: tvResult.data.episode_run_time[0] ?? null,
+                season_number: 0,
+                still_path: tvResult.data.backdrop_path,
+                vote_average: tvResult.data.vote_average,
+                vote_count: tvResult.data.vote_count,
+                crew: [],
+                guest_stars: [],
+              },
+              seriesImdbId,
+            ),
+            series: tvResult.data,
+          },
+        }
+      }
+
+      return { status: 'not-found' }
+    } catch (error) {
+      await this.logger.warning({
+        message: `❗  Failed to fetch TMDB metadata by IMDB ID '${imdbId}'`,
+        data: { error, imdbId, season, episode, file: context?.file },
+      })
+      return { status: 'error', error }
+    }
+  }
+
   /**
    * Fetches series metadata from TMDB using an IMDB ID.
    * Uses /find to bridge IMDB -> TMDB, then fetches full TV details.
@@ -374,7 +446,7 @@ export class TmdbClientService {
   public async fetchTmdbSeriesMetadata(
     { imdbId }: { imdbId: string },
     context?: { file?: PiRatFile },
-  ): Promise<TmdbFetchResult<TmdbTvDetailsResponse>> {
+  ): Promise<MetadataFetchResult<TmdbTvDetailsResponse>> {
     if (!this.config) {
       return { status: 'not-configured' }
     }
diff --git a/service/src/app-models/media/services/movie-file-maintainer.ts b/service/src/app-models/media/services/movie-file-maintainer.ts
index 09837eea..bf5c1a5f 100644
--- a/service/src/app-models/media/services/movie-file-maintainer.ts
+++ b/service/src/app-models/media/services/movie-file-maintainer.ts
@@ -18,6 +18,7 @@ import {
 } from 'common'
 import { readdir } from 'fs/promises'
 import { join } from 'path'
+import { type ConfigWatcher, createConfigWatcher } from '../../../utils/config-watcher.js'
 import { existsAsync } from '../../../utils/exists-async.js'
 import { FileWatcherService } from '../../drives/file-watcher-service.js'
 import { direntToApiModel } from '../../drives/utils/dirent-to-api-model.js'
@@ -159,13 +160,26 @@ export class MovieMaintainerService {
   @Injected(FileWatcherService)
   declare private fileWatcherService: FileWatcherService
 
-  declare private addSubscription: Disposable
+  private fileWatcherSubscriptions: Disposable[] = []
 
-  declare private unlinkDirSubscription: Disposable
+  declare private config: MoviesConfig | undefined
 
-  declare private unlinkSubscription: Disposable
+  private configWatcher?: ConfigWatcher
 
-  declare private config: MoviesConfig | undefined
+  private setupFileWatchers() {
+    this.fileWatcherSubscriptions.push(
+      this.fileWatcherService.subscribe('add', (file) => void this.onAdd(file)),
+      this.fileWatcherService.subscribe('unlinkDir', (dir) => void this.onUnlinkDir(dir)),
+      this.fileWatcherService.subscribe('unlink', (file) => void this.onUnlink(file)),
+    )
+  }
+
+  private teardownFileWatchers() {
+    for (const sub of this.fileWatcherSubscriptions) {
+      sub[Symbol.dispose]()
+    }
+    this.fileWatcherSubscriptions = []
+  }
 
   public checkFolderForPossibleMovieFiles = async (
     path: string,
@@ -215,20 +229,26 @@ export class MovieMaintainerService {
   }
 
   private async initAsync() {
-    this.addSubscription?.[Symbol.dispose]()
-    this.unlinkDirSubscription?.[Symbol.dispose]()
-    this.unlinkSubscription?.[Symbol.dispose]()
-
-    this.config = (await this.configDataSet.get(this.systemInjector, 'MOVIES_CONFIG')) as MoviesConfig | undefined
-    this.addSubscription = this.fileWatcherService.subscribe('add', (file) => void this.onAdd(file))
-    this.unlinkDirSubscription = this.fileWatcherService.subscribe('unlinkDir', (dir) => void this.onUnlinkDir(dir))
-    this.unlinkSubscription = this.fileWatcherService.subscribe('unlink', (file) => void this.onUnlink(file))
-
-    if (this.config?.value.fullSyncOnStartup) {
-      void this.fullSync().catch((error) => {
-        void this.logger.error({ message: '🎬  Full sync on startup failed', data: { error } })
-      })
-    }
+    this.teardownFileWatchers()
+    this.setupFileWatchers()
+
+    this.configWatcher?.dispose()
+    this.configWatcher = createConfigWatcher<MoviesConfig>({
+      configDataSet: this.configDataSet,
+      systemInjector: this.systemInjector,
+      logger: this.logger,
+      configId: 'MOVIES_CONFIG',
+      serviceName: 'Movie Maintainer',
+      onChange: (config) => {
+        this.config = config
+        if (config?.value.fullSyncOnStartup) {
+          void this.fullSync().catch((error) => {
+            void this.logger.error({ message: '🎬  Full sync failed', data: { error } })
+          })
+        }
+      },
+    })
+    await this.configWatcher.init()
   }
 
   public async fullSync(): Promise<ScanProgress> {
@@ -283,32 +303,11 @@ export class MovieMaintainerService {
   }
 
   public [Symbol.dispose]() {
-    this.addSubscription[Symbol.dispose]()
-    this.unlinkDirSubscription[Symbol.dispose]()
-    this.unlinkSubscription[Symbol.dispose]()
+    this.teardownFileWatchers()
+    this.configWatcher?.dispose()
   }
 }
 
 export const useMovieFileMaintainer = (injector: Injector) => {
-  const configDataSet = getDataSetFor(injector, Config, 'id')
-
-  configDataSet.subscribe('onEntityAdded', ({ entity }) => {
-    if (entity.id === 'MOVIES_CONFIG') {
-      injector.getInstance(MovieMaintainerService).init()
-    }
-  })
-
-  configDataSet.subscribe('onEntityUpdated', ({ id }) => {
-    if (id === 'MOVIES_CONFIG') {
-      injector.getInstance(MovieMaintainerService).init()
-    }
-  })
-
-  configDataSet.subscribe('onEntityRemoved', ({ key }) => {
-    if (key === 'MOVIES_CONFIG') {
-      injector.getInstance(MovieMaintainerService)[Symbol.dispose]()
-    }
-  })
-
   injector.getInstance(MovieMaintainerService)
 }
diff --git a/service/src/app-models/media/utils/link-movie.spec.ts b/service/src/app-models/media/utils/link-movie.spec.ts
index 8561e0ac..0e193fad 100644
--- a/service/src/app-models/media/utils/link-movie.spec.ts
+++ b/service/src/app-models/media/utils/link-movie.spec.ts
@@ -100,7 +100,9 @@ vi.mock('../../../utils/physical-path-utils.js', () => ({
 
 const mockGetFfprobeForPiratFile = vi.fn().mockResolvedValue({ format: { tags: {} }, duration: 7200 })
 const mockFetchOmdbMovieMetadata = vi.fn()
+const mockFetchOmdbMovieMetadataByImdbId = vi.fn()
 const mockFetchTmdbMovieMetadata = vi.fn()
+const mockFetchTmdbMovieMetadataByImdbId = vi.fn()
 
 describe('linkMovie', () => {
   beforeEach(() => {
@@ -124,12 +126,19 @@ describe('linkMovie', () => {
     )
 
     injector.setExplicitInstance(
-      { fetchOmdbMovieMetadata: mockFetchOmdbMovieMetadata } as unknown as OmdbClientService,
+      {
+        fetchOmdbMovieMetadata: mockFetchOmdbMovieMetadata,
+        fetchOmdbMovieMetadataByImdbId: mockFetchOmdbMovieMetadataByImdbId,
+      } as unknown as OmdbClientService,
       OmdbClientService,
     )
 
     injector.setExplicitInstance(
-      { fetchTmdbMovieMetadata: mockFetchTmdbMovieMetadata, config: undefined } as unknown as TmdbClientService,
+      {
+        fetchTmdbMovieMetadata: mockFetchTmdbMovieMetadata,
+        fetchTmdbMovieMetadataByImdbId: mockFetchTmdbMovieMetadataByImdbId,
+        config: undefined,
+      } as unknown as TmdbClientService,
       TmdbClientService,
     )
 
@@ -322,6 +331,34 @@ describe('linkMovie', () => {
       })
     })
 
+    it('should enrich metadata via OMDB by IMDB ID after direct-ID link', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockExtractImdbIdFromFfprobeTags.mockReturnValue('tt9999999')
+      mockFetchOmdbMovieMetadataByImdbId.mockResolvedValue({
+        status: 'success',
+        data: { imdbID: 'tt9999999', Title: 'Tagged Movie', Year: '2024' },
+      })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id', path: 'movies/Tagged.Movie.2024.mkv', imdbId: 'tt9999999' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        await linkMovie({
+          injector,
+          file: createFile('movies/Tagged.Movie.2024.mkv'),
+        })
+
+        // Wait for fire-and-forget enrichment
+        await new Promise((resolve) => setTimeout(resolve, 10))
+
+        expect(mockFetchOmdbMovieMetadataByImdbId).toHaveBeenCalledWith(
+          { imdbId: 'tt9999999' },
+          expect.objectContaining({ file: expect.objectContaining({ driveLetter: 'A' }) }),
+        )
+        expect(mockFetchOmdbMovieMetadata).not.toHaveBeenCalled()
+      })
+    })
+
     it('should skip .nfo scanning when ffprobe tags already have IMDB ID', async () => {
       mockMovieFileStoreFind.mockResolvedValue([])
       mockExtractImdbIdFromFfprobeTags.mockReturnValue('tt8888888')
@@ -389,6 +426,37 @@ describe('linkMovie', () => {
       })
     })
 
+    it('should enrich metadata via OMDB by IMDB ID after .nfo link', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockExtractImdbIdFromNfoFiles.mockResolvedValue({
+        imdbId: 'tt5555555',
+        nfoFiles: ['movies/movie.nfo'],
+      })
+      mockFetchOmdbMovieMetadataByImdbId.mockResolvedValue({
+        status: 'success',
+        data: { imdbID: 'tt5555555', Title: 'Nfo Movie', Year: '2024' },
+      })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id', path: 'movies/Nfo.Movie.2024.mkv', imdbId: 'tt5555555' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        await linkMovie({
+          injector,
+          file: createFile('movies/Nfo.Movie.2024.mkv'),
+        })
+
+        // Wait for fire-and-forget enrichment
+        await new Promise((resolve) => setTimeout(resolve, 10))
+
+        expect(mockFetchOmdbMovieMetadataByImdbId).toHaveBeenCalledWith(
+          { imdbId: 'tt5555555' },
+          expect.objectContaining({ file: expect.objectContaining({ driveLetter: 'A' }) }),
+        )
+        expect(mockFetchOmdbMovieMetadata).not.toHaveBeenCalled()
+      })
+    })
+
     it('should fall back to OMDB/TMDB when .nfo has no IMDB ID', async () => {
       mockMovieFileStoreFind.mockResolvedValue([])
       mockExtractImdbIdFromNfoFiles.mockResolvedValue({
diff --git a/service/src/app-models/media/utils/link-movie.ts b/service/src/app-models/media/utils/link-movie.ts
index a37409e7..c7baeec3 100644
--- a/service/src/app-models/media/utils/link-movie.ts
+++ b/service/src/app-models/media/utils/link-movie.ts
@@ -60,11 +60,19 @@ const getProviderPriority = async (injector: Injector): Promise<Array<'omdb' | '
 
 const tryOmdbProvider = async (
   injector: Injector,
-  { title, year, season, episode }: { title: string; year?: number; season?: number; episode?: number },
+  {
+    title,
+    year,
+    season,
+    episode,
+    imdbId,
+  }: { title: string; year?: number; season?: number; episode?: number; imdbId?: string },
   context?: { file?: PiRatFile },
 ): Promise<ProviderResult> => {
   const omdbClientService = injector.getInstance(OmdbClientService)
-  const result = await omdbClientService.fetchOmdbMovieMetadata({ title, year, season, episode }, context)
+  const result = imdbId
+    ? await omdbClientService.fetchOmdbMovieMetadataByImdbId({ imdbId }, context)
+    : await omdbClientService.fetchOmdbMovieMetadata({ title, year, season, episode }, context)
 
   if (result.status === 'not-configured') return { status: 'skip' }
   if (result.status === 'rate-limited') return { status: 'rate-limited' }
@@ -92,11 +100,19 @@ const tryOmdbProvider = async (
 
 const tryTmdbProvider = async (
   injector: Injector,
-  { title, year, season, episode }: { title: string; year?: number; season?: number; episode?: number },
+  {
+    title,
+    year,
+    season,
+    episode,
+    imdbId,
+  }: { title: string; year?: number; season?: number; episode?: number; imdbId?: string },
   context?: { file?: PiRatFile },
 ): Promise<ProviderResult> => {
   const tmdbClientService = injector.getInstance(TmdbClientService)
-  const result = await tmdbClientService.fetchTmdbMovieMetadata({ title, year, season, episode }, context)
+  const result = imdbId
+    ? await tmdbClientService.fetchTmdbMovieMetadataByImdbId({ imdbId, season, episode }, context)
+    : await tmdbClientService.fetchTmdbMovieMetadata({ title, year, season, episode }, context)
 
   if (result.status === 'not-configured') return { status: 'skip' }
   if (result.status === 'rate-limited') return { status: 'rate-limited' }
@@ -104,8 +120,8 @@ const tryTmdbProvider = async (
   if (result.status === 'error') return { status: 'skip' }
 
   const { movie: tmdbMovie, series: tmdbSeries } = result.data
-  const imdbId = tmdbMovie.imdb_id
-  if (!imdbId) return { status: 'skip' }
+  const resolvedImdbId = tmdbMovie.imdb_id
+  if (!resolvedImdbId) return { status: 'skip' }
 
   const language = normalizeLanguage(tmdbClientService.config?.value.defaultLanguage ?? 'en-US')
 
@@ -113,7 +129,7 @@ const tryTmdbProvider = async (
 
   const movie = await ensureMovieExists(
     {
-      imdbId,
+      imdbId: resolvedImdbId,
       year: tmdbMovie.release_date ? parseInt(tmdbMovie.release_date.slice(0, 4), 10) : undefined,
       duration: tmdbMovie.runtime || undefined,
       type: tmdbSeries ? 'episode' : 'movie',
@@ -123,7 +139,7 @@ const tryTmdbProvider = async (
     },
     injector,
   )
-  await ensureMovieLocalizedMetadataExists(mapTmdbMovieToLocalized(tmdbMovie, imdbId, language), injector)
+  await ensureMovieLocalizedMetadataExists(mapTmdbMovieToLocalized(tmdbMovie, resolvedImdbId, language), injector)
 
   if (tmdbSeries) {
     const seriesImdbId = tmdbSeries.external_ids?.imdb_id
@@ -132,7 +148,7 @@ const tryTmdbProvider = async (
     }
   }
 
-  return { status: 'linked', imdbId, movie }
+  return { status: 'linked', imdbId: resolvedImdbId, movie }
 }
 
 const metadataProviders: Record<string, typeof tryOmdbProvider> = {
@@ -146,7 +162,7 @@ const metadataProviders: Record<string, typeof tryOmdbProvider> = {
  */
 const enrichMetadataFromProviders = async (
   injector: Injector,
-  params: { title: string; year?: number; season?: number; episode?: number },
+  params: { title: string; year?: number; season?: number; episode?: number; imdbId?: string },
   context?: { file?: PiRatFile },
 ) => {
   const priority = await getProviderPriority(injector)
@@ -253,12 +269,14 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
     })
 
     // Fire-and-forget: enrich localized metadata via providers
-    void enrichMetadataFromProviders(injector, { title, year, season, episode }, { file }).catch((error) => {
-      void logger.warning({
-        message: `Failed to enrich metadata for '${fileName}' after direct-ID link`,
-        data: { error },
-      })
-    })
+    void enrichMetadataFromProviders(injector, { title, year, season, episode, imdbId: directImdbId }, { file }).catch(
+      (error) => {
+        void logger.warning({
+          message: `Failed to enrich metadata for '${fileName}' after direct-ID link`,
+          data: { error },
+        })
+      },
+    )
 
     return { status: 'linked', movieFile: newMovieFile, movie } as const
   }
diff --git a/service/src/utils/config-watcher.spec.ts b/service/src/utils/config-watcher.spec.ts
new file mode 100644
index 00000000..ae5cdd3b
--- /dev/null
+++ b/service/src/utils/config-watcher.spec.ts
@@ -0,0 +1,159 @@
+import type { OmdbConfig } from 'common'
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { createConfigWatcher, type ConfigWatcher } from './config-watcher.js'
+
+const createMockDeps = () => {
+  const subscribers: Record<string, Array<(arg: unknown) => void>> = {}
+
+  const configDataSet = {
+    get: vi.fn(),
+    subscribe: vi.fn((event: string, handler: (arg: unknown) => void) => {
+      if (!subscribers[event]) subscribers[event] = []
+      subscribers[event].push(handler)
+      return { [Symbol.dispose]: vi.fn() }
+    }),
+  }
+
+  const logger = {
+    verbose: vi.fn().mockResolvedValue(undefined),
+    information: vi.fn().mockResolvedValue(undefined),
+    warning: vi.fn().mockResolvedValue(undefined),
+    error: vi.fn().mockResolvedValue(undefined),
+  }
+
+  const systemInjector = {} as never
+
+  const emit = (event: string, payload: unknown) => {
+    for (const handler of subscribers[event] ?? []) {
+      handler(payload)
+    }
+  }
+
+  return { configDataSet, logger, systemInjector, emit }
+}
+
+describe('createConfigWatcher', () => {
+  let deps: ReturnType<typeof createMockDeps>
+  let onChange: ReturnType<typeof vi.fn<(config: OmdbConfig | undefined) => void>>
+  let watcher: ConfigWatcher
+
+  beforeEach(() => {
+    deps = createMockDeps()
+    onChange = vi.fn<(config: OmdbConfig | undefined) => void>()
+    watcher = createConfigWatcher<OmdbConfig>({
+      configDataSet: deps.configDataSet as never,
+      systemInjector: deps.systemInjector,
+      logger: deps.logger as never,
+      configId: 'OMDB_CONFIG',
+      serviceName: 'Test Service',
+      onChange,
+    })
+  })
+
+  it('should call onChange with config when config exists', async () => {
+    deps.configDataSet.get.mockResolvedValue({ id: 'OMDB_CONFIG', value: { apiKey: 'key-1' } })
+
+    await watcher.init()
+
+    expect(onChange).toHaveBeenCalledWith({ id: 'OMDB_CONFIG', value: { apiKey: 'key-1' } })
+  })
+
+  it('should call onChange with undefined when config is missing', async () => {
+    deps.configDataSet.get.mockResolvedValue(undefined)
+
+    await watcher.init()
+
+    expect(onChange).toHaveBeenCalledWith(undefined)
+  })
+
+  it('should subscribe to add/update/remove events', async () => {
+    deps.configDataSet.get.mockResolvedValue(undefined)
+
+    await watcher.init()
+
+    expect(deps.configDataSet.subscribe).toHaveBeenCalledWith('onEntityAdded', expect.any(Function))
+    expect(deps.configDataSet.subscribe).toHaveBeenCalledWith('onEntityUpdated', expect.any(Function))
+    expect(deps.configDataSet.subscribe).toHaveBeenCalledWith('onEntityRemoved', expect.any(Function))
+  })
+
+  it('should call onChange when entity is added with matching id', async () => {
+    deps.configDataSet.get.mockResolvedValue(undefined)
+    await watcher.init()
+    onChange.mockClear()
+
+    deps.emit('onEntityAdded', { entity: { id: 'OMDB_CONFIG', value: { apiKey: 'new-key' } } })
+
+    expect(onChange).toHaveBeenCalledWith({ id: 'OMDB_CONFIG', value: { apiKey: 'new-key' } })
+  })
+
+  it('should NOT call onChange when entity is added with different id', async () => {
+    deps.configDataSet.get.mockResolvedValue(undefined)
+    await watcher.init()
+    onChange.mockClear()
+
+    deps.emit('onEntityAdded', { entity: { id: 'OTHER_CONFIG', value: {} } })
+
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('should merge partial updates on onEntityUpdated', async () => {
+    deps.configDataSet.get.mockResolvedValue({ id: 'OMDB_CONFIG', value: { apiKey: 'key-1' } })
+    await watcher.init()
+    onChange.mockClear()
+
+    deps.emit('onEntityUpdated', { change: { id: 'OMDB_CONFIG', value: { apiKey: 'key-2' } } })
+
+    expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ id: 'OMDB_CONFIG', value: { apiKey: 'key-2' } }))
+  })
+
+  it('should call onChange with undefined on entity removal', async () => {
+    deps.configDataSet.get.mockResolvedValue({ id: 'OMDB_CONFIG', value: { apiKey: 'key-1' } })
+    await watcher.init()
+    onChange.mockClear()
+
+    deps.emit('onEntityRemoved', { key: 'OMDB_CONFIG' })
+
+    expect(onChange).toHaveBeenCalledWith(undefined)
+  })
+
+  it('should NOT call onChange on removal of a different config', async () => {
+    deps.configDataSet.get.mockResolvedValue({ id: 'OMDB_CONFIG', value: { apiKey: 'key-1' } })
+    await watcher.init()
+    onChange.mockClear()
+
+    deps.emit('onEntityRemoved', { key: 'OTHER_CONFIG' })
+
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('should dispose old subscriptions when init is called again', async () => {
+    deps.configDataSet.get.mockResolvedValue(undefined)
+
+    await watcher.init()
+
+    const disposeSpies = deps.configDataSet.subscribe.mock.results.map(
+      (r) => (r.value as { [Symbol.dispose]: ReturnType<typeof vi.fn> })[Symbol.dispose],
+    )
+
+    await watcher.init()
+
+    for (const spy of disposeSpies) {
+      expect(spy).toHaveBeenCalled()
+    }
+  })
+
+  it('should dispose subscriptions on dispose()', async () => {
+    deps.configDataSet.get.mockResolvedValue(undefined)
+    await watcher.init()
+
+    const disposeSpies = deps.configDataSet.subscribe.mock.results.map(
+      (r) => (r.value as { [Symbol.dispose]: ReturnType<typeof vi.fn> })[Symbol.dispose],
+    )
+
+    watcher.dispose()
+
+    for (const spy of disposeSpies) {
+      expect(spy).toHaveBeenCalled()
+    }
+  })
+})
diff --git a/service/src/utils/config-watcher.ts b/service/src/utils/config-watcher.ts
new file mode 100644
index 00000000..041accf6
--- /dev/null
+++ b/service/src/utils/config-watcher.ts
@@ -0,0 +1,91 @@
+import type { Injector } from '@furystack/inject'
+import type { ScopedLogger } from '@furystack/logging'
+import type { DataSet } from '@furystack/repository'
+import type { ConfigType } from 'common'
+import type { Config } from 'common'
+
+export type ConfigWatcherOptions<TConfig extends ConfigType> = {
+  configDataSet: DataSet<Config, 'id'>
+  systemInjector: Injector
+  logger: ScopedLogger
+  configId: TConfig['id']
+  serviceName: string
+  onChange: (config: TConfig | undefined) => void
+}
+
+export type ConfigWatcher = {
+  init: () => Promise<void>
+  dispose: () => void
+}
+
+/**
+ * The DataSet stores `Config` objects (with `createdAt`/`updatedAt`) but individual
+ * config interfaces (`OmdbConfig`, `TmdbConfig`, etc.) only define `id` and `value`.
+ * This helper narrows a loaded `Config` to the caller's expected `TConfig` shape.
+ */
+const narrowConfig = <TConfig extends ConfigType>(raw: Config): TConfig =>
+  ({ id: raw.id, value: raw.value }) as unknown as TConfig
+
+export const createConfigWatcher = <TConfig extends ConfigType>(
+  options: ConfigWatcherOptions<TConfig>,
+): ConfigWatcher => {
+  let subscriptions: Disposable[] = []
+  let currentConfig: TConfig | undefined
+
+  const init = async () => {
+    for (const sub of subscriptions) {
+      sub[Symbol.dispose]()
+    }
+    subscriptions = []
+
+    const loaded = await options.configDataSet.get(options.systemInjector, options.configId)
+    currentConfig = loaded ? narrowConfig<TConfig>(loaded) : undefined
+    options.onChange(currentConfig)
+
+    if (currentConfig) {
+      await options.logger.verbose({ message: `✅   ${options.serviceName} initialized` })
+    } else {
+      await options.logger.information({
+        message: `🚫   No config found, ${options.serviceName} will not be initialized`,
+      })
+    }
+
+    subscriptions.push(
+      options.configDataSet.subscribe('onEntityAdded', ({ entity }) => {
+        if (entity.id === options.configId) {
+          currentConfig = narrowConfig<TConfig>(entity)
+          options.onChange(currentConfig)
+          void options.logger.information({ message: `🎬   ${options.serviceName} config added` })
+        }
+      }),
+      options.configDataSet.subscribe('onEntityUpdated', ({ change }) => {
+        if (change.id === options.configId) {
+          currentConfig = { ...currentConfig, ...change } as unknown as TConfig
+          options.onChange(currentConfig)
+          void options.logger.information({
+            message: `🎬   ${options.serviceName} config updated`,
+            data: change,
+          })
+        }
+      }),
+      options.configDataSet.subscribe('onEntityRemoved', ({ key }) => {
+        if (key === options.configId) {
+          currentConfig = undefined
+          options.onChange(undefined)
+          void options.logger.information({
+            message: `🚫   ${options.serviceName} config removed`,
+          })
+        }
+      }),
+    )
+  }
+
+  const dispose = () => {
+    for (const sub of subscriptions) {
+      sub[Symbol.dispose]()
+    }
+    subscriptions = []
+  }
+
+  return { init, dispose }
+}

From d8e4e8103a66310f5108c48f711bceb4b1bd558c Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Thu, 12 Mar 2026 17:48:51 +0100
Subject: [PATCH 25/30] metadata getter fixes

---
 .../media/metadata-services/tmdb-api-types.ts |  1 +
 .../tmdb-client-service.spec.ts               | 90 +++++++++++++++++++
 .../metadata-services/tmdb-client-service.ts  | 13 ++-
 .../app-models/media/utils/link-movie.spec.ts | 77 ++++++++++++++++
 .../src/app-models/media/utils/link-movie.ts  | 70 +++++++++++----
 5 files changed, 228 insertions(+), 23 deletions(-)

diff --git a/service/src/app-models/media/metadata-services/tmdb-api-types.ts b/service/src/app-models/media/metadata-services/tmdb-api-types.ts
index 184969b3..36d3961e 100644
--- a/service/src/app-models/media/metadata-services/tmdb-api-types.ts
+++ b/service/src/app-models/media/metadata-services/tmdb-api-types.ts
@@ -225,6 +225,7 @@ export type TmdbEpisodeDetailsResponse = {
     order: number
     profile_path: string | null
   }>
+  external_ids?: TmdbExternalIds
 }
 
 // ── Find by External ID ── GET /3/find/{external_id} ─────────────────
diff --git a/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts b/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts
index 73190346..ea79a668 100644
--- a/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts
+++ b/service/src/app-models/media/metadata-services/tmdb-client-service.spec.ts
@@ -377,6 +377,16 @@ describe('TmdbClientService', () => {
       const calledUrl = mockFetch.mock.calls[0][0] as string
       expect(calledUrl).toContain('/tv/67890/season/2/episode/3')
     })
+
+    it('should include append_to_response for external_ids', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(createMockResponse(createEpisodeDetailsResponse()))
+      globalThis.fetch = mockFetch
+
+      await service.getEpisodeDetails(67890, 1, 5)
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string
+      expect(calledUrl).toContain('append_to_response=external_ids')
+    })
   })
 
   describe('findByImdbId', () => {
@@ -675,6 +685,54 @@ describe('TmdbClientService', () => {
         expect(result.data.movie.runtime).toBe(60)
       }
     })
+
+    it('should use episode IMDB ID when available instead of series IMDB ID', async () => {
+      expect.assertions(2)
+
+      const searchTvResponse = createSearchTvResponse([{ id: 67890 }])
+      const tvDetailsResponse = createTvDetailsResponse()
+      const episodeResponse = createEpisodeDetailsResponse({
+        external_ids: {
+          imdb_id: 'tt1111111',
+          facebook_id: null,
+          instagram_id: null,
+          twitter_id: null,
+          wikidata_id: null,
+        },
+      })
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(searchTvResponse))
+        .mockResolvedValueOnce(createMockResponse(tvDetailsResponse))
+        .mockResolvedValueOnce(createMockResponse(episodeResponse))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Test Series', season: 1, episode: 5 })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.movie.imdb_id).toBe('tt1111111')
+      }
+    })
+
+    it('should fall back to series IMDB ID when episode has no external_ids', async () => {
+      expect.assertions(2)
+
+      const searchTvResponse = createSearchTvResponse([{ id: 67890 }])
+      const tvDetailsResponse = createTvDetailsResponse()
+      const episodeResponse = createEpisodeDetailsResponse()
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(searchTvResponse))
+        .mockResolvedValueOnce(createMockResponse(tvDetailsResponse))
+        .mockResolvedValueOnce(createMockResponse(episodeResponse))
+
+      const result = await service.fetchTmdbMovieMetadata({ title: 'Test Series', season: 1, episode: 5 })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.movie.imdb_id).toBe('tt9876543')
+      }
+    })
   })
 
   describe('fetchTmdbMovieMetadataByImdbId', () => {
@@ -748,6 +806,38 @@ describe('TmdbClientService', () => {
       }
     })
 
+    it('should use episode IMDB ID when resolving episode via tv_results', async () => {
+      expect.assertions(2)
+
+      const findResponse = createFindByIdResponse({
+        tv_results: [{ id: 67890 } as TmdbSearchTvResult],
+      })
+      const tvDetailsResponse = createTvDetailsResponse()
+      const episodeResponse = createEpisodeDetailsResponse({
+        season_number: 1,
+        episode_number: 5,
+        external_ids: {
+          imdb_id: 'tt2222222',
+          facebook_id: null,
+          instagram_id: null,
+          twitter_id: null,
+          wikidata_id: null,
+        },
+      })
+
+      globalThis.fetch = vi
+        .fn()
+        .mockResolvedValueOnce(createMockResponse(findResponse))
+        .mockResolvedValueOnce(createMockResponse(tvDetailsResponse))
+        .mockResolvedValueOnce(createMockResponse(episodeResponse))
+
+      const result = await service.fetchTmdbMovieMetadataByImdbId({ imdbId: 'tt9876543', season: 1, episode: 5 })
+      expect(result.status).toBe('success')
+      if (result.status === 'success') {
+        expect(result.data.movie.imdb_id).toBe('tt2222222')
+      }
+    })
+
     it('should return not-found when no movie or tv results', async () => {
       const findResponse = createFindByIdResponse()
       globalThis.fetch = vi.fn().mockResolvedValue(createMockResponse(findResponse))
diff --git a/service/src/app-models/media/metadata-services/tmdb-client-service.ts b/service/src/app-models/media/metadata-services/tmdb-client-service.ts
index e9d127e2..e17542c1 100644
--- a/service/src/app-models/media/metadata-services/tmdb-client-service.ts
+++ b/service/src/app-models/media/metadata-services/tmdb-client-service.ts
@@ -201,6 +201,7 @@ export class TmdbClientService {
   ): Promise<MetadataFetchResult<TmdbEpisodeDetailsResponse>> {
     const params = new URLSearchParams({
       language: this.getLanguage(options?.language),
+      append_to_response: 'external_ids',
     })
 
     const path = `/tv/${tvId}/season/${seasonNumber}/episode/${episodeNumber}?${params}`
@@ -283,8 +284,8 @@ export class TmdbClientService {
     const tvResult = await this.getTvDetails(tvId)
     if (tvResult.status !== 'success') return tvResult
 
-    const imdbId = tvResult.data.external_ids?.imdb_id
-    if (!imdbId) {
+    const seriesImdbId = tvResult.data.external_ids?.imdb_id
+    if (!seriesImdbId) {
       await this.logger.debug({
         message: `TMDB TV #${tvId} has no IMDB ID, skipping (D1)`,
         data: { file: context?.file },
@@ -295,10 +296,12 @@ export class TmdbClientService {
     const episodeResult = await this.getEpisodeDetails(tvId, season, episode)
     if (episodeResult.status !== 'success') return episodeResult
 
+    const episodeImdbId = episodeResult.data.external_ids?.imdb_id ?? seriesImdbId
+
     return {
       status: 'success',
       data: {
-        movie: buildSyntheticMovieFromEpisode(tvResult.data, episodeResult.data, imdbId),
+        movie: buildSyntheticMovieFromEpisode(tvResult.data, episodeResult.data, episodeImdbId),
         episode: episodeResult.data,
         series: tvResult.data,
       },
@@ -392,10 +395,12 @@ export class TmdbClientService {
           const episodeResult = await this.getEpisodeDetails(tvId, season, episode)
           if (episodeResult.status !== 'success') return episodeResult
 
+          const episodeImdbId = episodeResult.data.external_ids?.imdb_id ?? seriesImdbId
+
           return {
             status: 'success',
             data: {
-              movie: buildSyntheticMovieFromEpisode(tvResult.data, episodeResult.data, seriesImdbId),
+              movie: buildSyntheticMovieFromEpisode(tvResult.data, episodeResult.data, episodeImdbId),
               episode: episodeResult.data,
               series: tvResult.data,
             },
diff --git a/service/src/app-models/media/utils/link-movie.spec.ts b/service/src/app-models/media/utils/link-movie.spec.ts
index 0e193fad..6ce8cb36 100644
--- a/service/src/app-models/media/utils/link-movie.spec.ts
+++ b/service/src/app-models/media/utils/link-movie.spec.ts
@@ -457,6 +457,83 @@ describe('linkMovie', () => {
       })
     })
 
+    it('should resolve episode IMDB ID via provider when .nfo has series ID for an episode file', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockExtractImdbIdFromNfoFiles.mockResolvedValue({
+        imdbId: 'tt9876543',
+        nfoFiles: ['series/show.nfo'],
+      })
+      mockFetchOmdbMovieMetadata.mockResolvedValue({
+        status: 'success',
+        data: { imdbID: 'tt1111111', Title: 'Episode Title', Year: '2024', Season: '1', Episode: '5' },
+      })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id', path: 'series/Show.S01E05.mkv', imdbId: 'tt1111111' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        const result = await linkMovie({
+          injector,
+          file: createFile('series/Show.S01E05.mkv'),
+        })
+
+        expect(result.status).toBe('linked')
+        const addCall = mockMovieFileStoreAdd.mock.calls[0]
+        const addedEntity = addCall[1] as unknown as MovieFile
+        expect(addedEntity.imdbId).toBe('tt1111111')
+      })
+    })
+
+    it('should fall back to .nfo ID when providers fail for episode file', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockExtractImdbIdFromNfoFiles.mockResolvedValue({
+        imdbId: 'tt9876543',
+        nfoFiles: ['series/show.nfo'],
+      })
+      mockFetchOmdbMovieMetadata.mockResolvedValue({ status: 'not-configured' })
+      mockFetchTmdbMovieMetadata.mockResolvedValue({ status: 'not-configured' })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id', path: 'series/Show.S01E05.mkv', imdbId: 'tt9876543' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        const result = await linkMovie({
+          injector,
+          file: createFile('series/Show.S01E05.mkv'),
+        })
+
+        expect(result.status).toBe('linked')
+        const addCall = mockMovieFileStoreAdd.mock.calls[0]
+        const addedEntity = addCall[1] as unknown as MovieFile
+        expect(addedEntity.imdbId).toBe('tt9876543')
+      })
+    })
+
+    it('should use .nfo ID directly for non-episode files without consulting providers', async () => {
+      mockMovieFileStoreFind.mockResolvedValue([])
+      mockExtractImdbIdFromNfoFiles.mockResolvedValue({
+        imdbId: 'tt5555555',
+        nfoFiles: ['movies/movie.nfo'],
+      })
+      mockMovieFileStoreAdd.mockResolvedValue({
+        created: [{ id: 'new-file-id', path: 'movies/Nfo.Movie.2024.mkv', imdbId: 'tt5555555' }],
+      })
+
+      await usingAsync(createTestInjector(), async (injector) => {
+        const result = await linkMovie({
+          injector,
+          file: createFile('movies/Nfo.Movie.2024.mkv'),
+        })
+
+        expect(result.status).toBe('linked')
+        const addCall = mockMovieFileStoreAdd.mock.calls[0]
+        const addedEntity = addCall[1] as unknown as MovieFile
+        expect(addedEntity.imdbId).toBe('tt5555555')
+        expect(mockFetchOmdbMovieMetadata).not.toHaveBeenCalled()
+        expect(mockFetchTmdbMovieMetadata).not.toHaveBeenCalled()
+      })
+    })
+
     it('should fall back to OMDB/TMDB when .nfo has no IMDB ID', async () => {
       mockMovieFileStoreFind.mockResolvedValue([])
       mockExtractImdbIdFromNfoFiles.mockResolvedValue({
diff --git a/service/src/app-models/media/utils/link-movie.ts b/service/src/app-models/media/utils/link-movie.ts
index c7baeec3..4c9e3836 100644
--- a/service/src/app-models/media/utils/link-movie.ts
+++ b/service/src/app-models/media/utils/link-movie.ts
@@ -242,43 +242,75 @@ export const linkMovie = async (options: { injector: Injector; file: PiRatFile }
   )
 
   if (directImdbId) {
-    const movie = await ensureMovieExists(
-      {
-        imdbId: directImdbId,
-        year,
-        season,
-        episode,
-        type: season != null && episode != null ? 'episode' : 'movie',
-      },
-      injector,
-    )
+    const isEpisode = season != null && episode != null
+
+    // For episodes, the NFO/ffprobe ID may be the series ID rather than the episode ID.
+    // Try providers with title+season+episode to resolve the episode-specific IMDB ID.
+    let resolvedImdbId = directImdbId
+    let resolvedMovie: Movie | undefined
+
+    if (isEpisode) {
+      const priority = await getProviderPriority(injector)
+      for (const provider of priority) {
+        const tryProvider = metadataProviders[provider]
+        if (!tryProvider) continue
+
+        const result = await tryProvider(injector, { title, year, season, episode }, { file })
+        if (result.status === 'linked') {
+          resolvedImdbId = result.imdbId
+          resolvedMovie = result.movie
+          break
+        }
+        if (result.status === 'rate-limited') break
+      }
+    }
+
+    if (!resolvedMovie) {
+      resolvedMovie = await ensureMovieExists(
+        {
+          imdbId: resolvedImdbId,
+          year,
+          season,
+          episode,
+          type: isEpisode ? 'episode' : 'movie',
+        },
+        injector,
+      )
+    }
 
     const {
       created: [newMovieFile],
     } = await movieFileDataSet.add(injector, {
       driveLetter,
       path,
-      imdbId: directImdbId,
+      imdbId: resolvedImdbId,
       ffprobe: ffprobeResult,
       ...(relatedFiles.length > 0 ? { relatedFiles } : {}),
     })
 
+    const source = tagImdbId ? 'ffprobe-tags' : 'nfo-file'
+    const resolvedViaProvider = isEpisode && resolvedImdbId !== directImdbId
+
     await logger.debug({
-      message: `File ${fileName} linked successfully (from ${tagImdbId ? 'ffprobe tags' : '.nfo file'}).`,
-      data: { file, movieFile: newMovieFile, movie, source: tagImdbId ? 'ffprobe-tags' : 'nfo-file' },
+      message: `File ${fileName} linked successfully (from ${source}${resolvedViaProvider ? ', episode ID resolved via provider' : ''}).`,
+      data: { file, movieFile: newMovieFile, movie: resolvedMovie, source },
     })
 
-    // Fire-and-forget: enrich localized metadata via providers
-    void enrichMetadataFromProviders(injector, { title, year, season, episode, imdbId: directImdbId }, { file }).catch(
-      (error) => {
+    // Fire-and-forget: enrich localized metadata (skip if already resolved via provider for episodes)
+    if (!resolvedViaProvider) {
+      void enrichMetadataFromProviders(
+        injector,
+        { title, year, season, episode, imdbId: resolvedImdbId },
+        { file },
+      ).catch((error) => {
         void logger.warning({
           message: `Failed to enrich metadata for '${fileName}' after direct-ID link`,
           data: { error },
         })
-      },
-    )
+      })
+    }
 
-    return { status: 'linked', movieFile: newMovieFile, movie } as const
+    return { status: 'linked', movieFile: newMovieFile, movie: resolvedMovie } as const
   }
 
   // Check existing OMDB metadata (backward compatibility)

From a2584cfa7e279be5f536415424ef3076c42b8a1c Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Fri, 27 Mar 2026 12:07:22 +0100
Subject: [PATCH 26/30] progress

---
 frontend/package.json                         |  1 +
 .../movie-player-v2/movie-player-service.ts   | 66 +++++++++++++++++--
 .../app-models/drives/file-watcher-service.ts |  5 +-
 .../media/actions/hls-master-action.ts        | 13 +---
 .../services/hls-manifest-generator.spec.ts   | 36 +++-------
 .../media/services/hls-manifest-generator.ts  | 26 +++-----
 .../media/services/stream-builder.spec.ts     |  8 +++
 .../media/services/stream-builder.ts          |  3 +-
 yarn.lock                                     |  8 +++
 9 files changed, 102 insertions(+), 64 deletions(-)

diff --git a/frontend/package.json b/frontend/package.json
index c84b0d6c..b833a865 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -35,6 +35,7 @@
     "@xterm/addon-web-links": "^0.12.0",
     "@xterm/xterm": "^6.0.0",
     "common": "workspace:^",
+    "hls.js": "^1.6.15",
     "ollama": "^0.6.3",
     "path-to-regexp": "^8.3.0",
     "video.js": "8.23.8"
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index ff6536a3..6da4abe4 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -10,6 +10,7 @@ import {
   type PlaybackMode,
   type SubtitleTrackInfo,
 } from 'common'
+import Hls from 'hls.js'
 import type { MediaApiClient } from '../../../services/api-clients/media-api-client.js'
 import { environmentOptions } from '../../../utils/environment-options.js'
 
@@ -87,6 +88,7 @@ export class MoviePlayerService implements AsyncDisposable {
   public activeSubtitleTrack = new ObservableValue<number | null>(null)
 
   private videoEventCleanup: Disposable | null = null
+  private hlsInstance: Hls | null = null
 
   /**
    * Converts a 0-based stream time (from video.currentTime during HLS)
@@ -115,6 +117,7 @@ export class MoviePlayerService implements AsyncDisposable {
       this.pendingCanPlayCleanup()
     }
 
+    this.destroyHlsInstance()
     this.videoEventCleanup?.[Symbol.dispose]()
     this.videoEventCleanup = null
 
@@ -340,19 +343,70 @@ export class MoviePlayerService implements AsyncDisposable {
     }
   }
 
-  private startHlsPlayback(videoElement: HTMLVideoElement) {
+  private buildHlsUrl(): string {
     const mode = this.playbackMode.getValue()
     const audioTrack = this.audioTrackId.getValue()
     const audioParam = audioTrack ? `&audioTrack=${encode(String(audioTrack))}` : ''
     const startTimeParam = this.hlsStartTime > 0 ? `&startTime=${encode(String(this.hlsStartTime))}` : ''
-    const hlsUrl = this.toServiceUrl(
+    return this.toServiceUrl(
       `/api/media/files/${encodeURIComponent(this.file.driveLetter)}/${encodeURIComponent(this.file.path)}/master.m3u8?mode=${encode(mode)}${audioParam}${startTimeParam}`,
     )
+  }
+
+  private destroyHlsInstance() {
+    if (this.hlsInstance) {
+      this.hlsInstance.destroy()
+      this.hlsInstance = null
+    }
+  }
+
+  private startHlsPlayback(videoElement: HTMLVideoElement) {
+    this.destroyHlsInstance()
+    const hlsUrl = this.buildHlsUrl()
+
+    if (Hls.isSupported()) {
+      const hls = new Hls({
+        xhrSetup: (xhr) => {
+          xhr.withCredentials = true
+        },
+        enableWebVTT: false,
+        enableIMSC1: false,
+        enableCEA708Captions: false,
+      })
+      this.hlsInstance = hls
 
-    void this.logger.verbose({ message: 'Starting native HLS playback' })
-    videoElement.src = hlsUrl
-    if (this.currentProgress > this.hlsStartTime) {
-      videoElement.currentTime = this.currentProgress - this.hlsStartTime
+      hls.on(Hls.Events.MANIFEST_PARSED, () => {
+        hls.subtitleTrack = -1
+        if (this.currentProgress > this.hlsStartTime) {
+          videoElement.currentTime = this.currentProgress - this.hlsStartTime
+        }
+      })
+
+      hls.on(Hls.Events.ERROR, (_event, data) => {
+        if (data.details === Hls.ErrorDetails.SUBTITLE_LOAD_ERROR) return
+
+        void this.logger.error({
+          message: 'HLS playback error',
+          data: { type: data.type, details: data.details, fatal: data.fatal },
+        })
+        if (data.fatal) {
+          if (data.type === Hls.ErrorTypes.MEDIA_ERROR) {
+            hls.recoverMediaError()
+          } else {
+            this.destroyHlsInstance()
+          }
+        }
+      })
+
+      hls.loadSource(hlsUrl)
+      hls.attachMedia(videoElement)
+      void this.logger.verbose({ message: 'Starting hls.js playback' })
+    } else {
+      void this.logger.verbose({ message: 'Starting native HLS playback' })
+      videoElement.src = hlsUrl
+      if (this.currentProgress > this.hlsStartTime) {
+        videoElement.currentTime = this.currentProgress - this.hlsStartTime
+      }
     }
   }
 
diff --git a/service/src/app-models/drives/file-watcher-service.ts b/service/src/app-models/drives/file-watcher-service.ts
index 7c4018b8..65a48adb 100644
--- a/service/src/app-models/drives/file-watcher-service.ts
+++ b/service/src/app-models/drives/file-watcher-service.ts
@@ -40,7 +40,10 @@ export class FileWatcherService extends EventHub<{
     }
 
     await this.logger.verbose({ message: `🔍  Starting File Watcher on volume '${drive.letter}'...` })
-    const watcher = watch(drive.physicalPath, { ignoreInitial: true })
+    const watcher = watch(drive.physicalPath, {
+      ignoreInitial: true,
+      awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 },
+    })
 
     watcher.on('error', (error) => {
       const errorMessage = error instanceof Error ? error.message : String(error)
diff --git a/service/src/app-models/media/actions/hls-master-action.ts b/service/src/app-models/media/actions/hls-master-action.ts
index b9fa316e..ffd90922 100644
--- a/service/src/app-models/media/actions/hls-master-action.ts
+++ b/service/src/app-models/media/actions/hls-master-action.ts
@@ -1,13 +1,11 @@
 import { getLogger } from '@furystack/logging'
-import { getDataSetFor } from '@furystack/repository'
 import { RequestError } from '@furystack/rest'
 import type { RequestAction } from '@furystack/rest-service'
 import { BypassResult } from '@furystack/rest-service'
 import type { MediaApi, PlaybackMode } from 'common'
-import { MovieFile } from 'common'
 import { FfprobeService } from '../../../ffprobe-service.js'
 import { generateMasterPlaylist } from '../services/hls-manifest-generator.js'
-import { buildSubtitleTrackList, resolvePlaybackMode } from '../services/stream-builder.js'
+import { resolvePlaybackMode } from '../services/stream-builder.js'
 
 const VALID_MODES: PlaybackMode[] = ['direct-play', 'remux', 'direct-stream', 'transcode']
 
@@ -45,20 +43,11 @@ export const HlsMasterAction: RequestAction<HlsMasterEndpoint> = async ({
           },
         }).mode
 
-  const movieFiles = await getDataSetFor(injector, MovieFile, 'id').find(injector, {
-    filter: { driveLetter: { $eq: letter }, path: { $eq: path } },
-    top: 1,
-  })
-  const movieFile = movieFiles[0]
-
-  const subtitleTracks = buildSubtitleTrackList(ffprobe, file, movieFile?.relatedFiles, movieFile?.imdbId)
-
   const playlist = generateMasterPlaylist({
     ffprobe,
     file,
     mode,
     baseUrl: '/api/media',
-    subtitleTracks,
     audioTrack: query.audioTrack,
     startTime: query.startTime,
   })
diff --git a/service/src/app-models/media/services/hls-manifest-generator.spec.ts b/service/src/app-models/media/services/hls-manifest-generator.spec.ts
index 8bc76554..d91d6532 100644
--- a/service/src/app-models/media/services/hls-manifest-generator.spec.ts
+++ b/service/src/app-models/media/services/hls-manifest-generator.spec.ts
@@ -1,5 +1,5 @@
 import { serializeToQueryString } from '@furystack/rest'
-import type { FfprobeData, SubtitleTrackInfo } from 'common'
+import type { FfprobeData } from 'common'
 import { describe, expect, it } from 'vitest'
 import { generateMasterPlaylist } from './hls-manifest-generator.js'
 
@@ -20,12 +20,6 @@ const createFfprobe = (overrides: Partial<FfprobeData> = {}): FfprobeData => ({
   ...overrides,
 })
 
-const subtitleTracks: SubtitleTrackInfo[] = [
-  { index: 3, label: 'English', language: 'eng', format: 'srt', source: 'embedded', requiresBurnIn: false },
-  { index: 4, label: 'Japanese', language: 'jpn', format: 'ass', source: 'embedded', requiresBurnIn: false },
-  { index: 5, label: 'PGS', language: 'eng', format: 'pgs', source: 'embedded', requiresBurnIn: true },
-]
-
 describe('generateMasterPlaylist', () => {
   it('should produce a valid HLS master playlist', () => {
     const playlist = generateMasterPlaylist({
@@ -33,7 +27,6 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'remux',
       baseUrl: '/api/media',
-      subtitleTracks,
     })
 
     expect(playlist).toContain('#EXTM3U')
@@ -47,26 +40,22 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'remux',
       baseUrl: '/api/media',
-      subtitleTracks: [],
     })
 
     expect(playlist).not.toContain('TYPE=AUDIO')
     expect(playlist).not.toContain('AUDIO="audio"')
   })
 
-  it('should include subtitle entries but exclude burn-in tracks', () => {
+  it('should not include subtitle entries (handled via HTML track elements)', () => {
     const playlist = generateMasterPlaylist({
       ffprobe: createFfprobe(),
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'remux',
       baseUrl: '/api/media',
-      subtitleTracks,
     })
 
-    expect(playlist).toContain('TYPE=SUBTITLES')
-    expect(playlist).toContain('NAME="English"')
-    expect(playlist).toContain('NAME="Japanese"')
-    expect(playlist).not.toContain('NAME="PGS"')
+    expect(playlist).not.toContain('TYPE=SUBTITLES')
+    expect(playlist).not.toContain('SUBTITLES=')
   })
 
   it('should generate variant streams for transcode mode', () => {
@@ -75,7 +64,6 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'transcode',
       baseUrl: '/api/media',
-      subtitleTracks: [],
     })
 
     expect(playlist).toContain('RESOLUTION=1920x1080')
@@ -91,7 +79,6 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'remux',
       baseUrl: '/api/media',
-      subtitleTracks: [],
     })
 
     const streamInfCount = (playlist.match(/#EXT-X-STREAM-INF/g) || []).length
@@ -112,7 +99,6 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'transcode',
       baseUrl: '/api/media',
-      subtitleTracks: [],
     })
 
     expect(playlist).not.toContain('RESOLUTION=3840x2160')
@@ -135,7 +121,6 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test-4k.mkv' },
       mode: 'transcode',
       baseUrl: '/api/media',
-      subtitleTracks: [],
     })
 
     expect(playlist).toContain('RESOLUTION=3840x2160')
@@ -151,7 +136,6 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'transcode',
       baseUrl: '/api/media',
-      subtitleTracks: [],
     })
 
     expect(playlist).not.toContain('RESOLUTION=3840x2160')
@@ -164,7 +148,7 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'transcode',
       baseUrl: '/api/media',
-      subtitleTracks: [],
+
       audioTrack: 2,
     })
 
@@ -181,7 +165,7 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'remux',
       baseUrl: '/api/media',
-      subtitleTracks: [],
+
       audioTrack: 3,
     })
 
@@ -195,7 +179,6 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'transcode',
       baseUrl: '/api/media',
-      subtitleTracks: [],
     })
 
     expect(playlist).not.toContain('audioTrack')
@@ -207,7 +190,7 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'transcode',
       baseUrl: '/api/media',
-      subtitleTracks: [],
+
       startTime: 3600,
     })
 
@@ -223,7 +206,7 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'remux',
       baseUrl: '/api/media',
-      subtitleTracks: [],
+
       startTime: 1800,
     })
 
@@ -237,7 +220,6 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'transcode',
       baseUrl: '/api/media',
-      subtitleTracks: [],
     })
 
     expect(playlist).not.toContain('startTime')
@@ -249,7 +231,7 @@ describe('generateMasterPlaylist', () => {
       file: { driveLetter: 'A', path: 'movies/test.mkv' },
       mode: 'transcode',
       baseUrl: '/api/media',
-      subtitleTracks: [],
+
       startTime: 0,
     })
 
diff --git a/service/src/app-models/media/services/hls-manifest-generator.ts b/service/src/app-models/media/services/hls-manifest-generator.ts
index 11283692..45264064 100644
--- a/service/src/app-models/media/services/hls-manifest-generator.ts
+++ b/service/src/app-models/media/services/hls-manifest-generator.ts
@@ -1,5 +1,5 @@
 import { serializeToQueryString } from '@furystack/rest'
-import type { FfprobeData, PlaybackMode, SubtitleTrackInfo } from 'common'
+import type { FfprobeData, PlaybackMode } from 'common'
 
 export type HlsVariant = {
   resolution: string
@@ -21,7 +21,6 @@ export const generateMasterPlaylist = ({
   file,
   mode,
   baseUrl,
-  subtitleTracks,
   audioTrack,
   startTime,
 }: {
@@ -29,7 +28,6 @@ export const generateMasterPlaylist = ({
   file: { driveLetter: string; path: string }
   mode: PlaybackMode
   baseUrl: string
-  subtitleTracks: SubtitleTrackInfo[]
   audioTrack?: number
   startTime?: number
 }): string => {
@@ -39,12 +37,8 @@ export const generateMasterPlaylist = ({
   const encodedPath = encodeURIComponent(file.path)
   const streamBase = `${baseUrl}/files/${encodedLetter}/${encodedPath}`
 
-  for (const track of subtitleTracks.filter((t) => !t.requiresBurnIn)) {
-    const isDefault = track.index === subtitleTracks.filter((t) => !t.requiresBurnIn)[0]?.index ? 'YES' : 'NO'
-    lines.push(
-      `#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="${track.label}",LANGUAGE="${track.language}",DEFAULT=${isDefault},AUTOSELECT=${isDefault},URI="${track.url || `${streamBase}/subtitle/${track.index}.m3u8`}"`,
-    )
-  }
+  // Subtitles are handled via HTML <track> elements on the frontend,
+  // not embedded in the HLS manifest (raw VTT URLs aren't valid HLS subtitle playlists).
 
   const videoStream = ffprobe.streams.find((s) => s.codec_type === 'video')
   const sourceHeight = videoStream?.height || 1080
@@ -55,9 +49,8 @@ export const generateMasterPlaylist = ({
   const startTimeQuery = startTime && startTime > 0 ? { startTime } : {}
 
   if (mode === 'remux' || mode === 'direct-play' || mode === 'direct-stream') {
-    const subtitleGroup = subtitleTracks.filter((t) => !t.requiresBurnIn).length > 0 ? ',SUBTITLES="subs"' : ''
     lines.push(
-      `#EXT-X-STREAM-INF:BANDWIDTH=${sourceBitrate},RESOLUTION=${sourceWidth}x${sourceHeight},CODECS="${getCodecString(ffprobe)}"${subtitleGroup}`,
+      `#EXT-X-STREAM-INF:BANDWIDTH=${sourceBitrate},RESOLUTION=${sourceWidth}x${sourceHeight},CODECS="${getCodecString(ffprobe, mode)}"`,
       `${streamBase}/stream.m3u8?${serializeToQueryString({ mode, ...audioTrackQuery, ...startTimeQuery })}`,
     )
   } else {
@@ -66,11 +59,9 @@ export const generateMasterPlaylist = ({
       applicableVariants.push(DEFAULT_VARIANTS[DEFAULT_VARIANTS.length - 1])
     }
 
-    const subtitleGroup = subtitleTracks.filter((t) => !t.requiresBurnIn).length > 0 ? ',SUBTITLES="subs"' : ''
-
     for (const variant of applicableVariants) {
       lines.push(
-        `#EXT-X-STREAM-INF:BANDWIDTH=${variant.bandwidth},RESOLUTION=${variant.resolution},CODECS="avc1.42E01E,mp4a.40.2"${subtitleGroup}`,
+        `#EXT-X-STREAM-INF:BANDWIDTH=${variant.bandwidth},RESOLUTION=${variant.resolution},CODECS="avc1.42E01E,mp4a.40.2"`,
         `${streamBase}/stream.m3u8?${serializeToQueryString({ mode: 'transcode' as PlaybackMode, resolution: `${variant.height}p`, ...audioTrackQuery, ...startTimeQuery })}`,
       )
     }
@@ -79,7 +70,7 @@ export const generateMasterPlaylist = ({
   return `${lines.join('\n')}\n`
 }
 
-const getCodecString = (ffprobe: FfprobeData): string => {
+const getCodecString = (ffprobe: FfprobeData, mode: PlaybackMode): string => {
   const videoStream = ffprobe.streams.find((s) => s.codec_type === 'video')
   const audioStream = ffprobe.streams.find((s) => s.codec_type === 'audio')
 
@@ -97,7 +88,10 @@ const getCodecString = (ffprobe: FfprobeData): string => {
   }
 
   const videoCodec = videoCodecMap[videoStream?.codec_name ?? ''] ?? 'avc1.42E01E'
-  const audioCodec = audioCodecMap[audioStream?.codec_name ?? ''] ?? 'mp4a.40.2'
+
+  // In direct-stream mode, audio is transcoded to AAC regardless of the source codec
+  const audioCodec =
+    mode === 'direct-stream' ? 'mp4a.40.2' : (audioCodecMap[audioStream?.codec_name ?? ''] ?? 'mp4a.40.2')
 
   return `${videoCodec},${audioCodec}`
 }
diff --git a/service/src/app-models/media/services/stream-builder.spec.ts b/service/src/app-models/media/services/stream-builder.spec.ts
index 614858bd..129ad290 100644
--- a/service/src/app-models/media/services/stream-builder.spec.ts
+++ b/service/src/app-models/media/services/stream-builder.spec.ts
@@ -63,6 +63,14 @@ describe('resolvePlaybackMode', () => {
     expect(result.mode).toBe('remux')
   })
 
+  it('should return remux for matroska even when client claims webm container support', () => {
+    const ffprobe = createFfprobe({
+      format: { format_name: 'matroska,webm', duration: '100' },
+    })
+    const result = resolvePlaybackMode({ ffprobe, codecSupport: fullCodecSupport })
+    expect(result.mode).toBe('remux')
+  })
+
   it('should return direct-stream when video is supported but audio is not', () => {
     const ffprobe = createFfprobe({
       streams: [
diff --git a/service/src/app-models/media/services/stream-builder.ts b/service/src/app-models/media/services/stream-builder.ts
index a4c730f1..9aaf3240 100644
--- a/service/src/app-models/media/services/stream-builder.ts
+++ b/service/src/app-models/media/services/stream-builder.ts
@@ -69,8 +69,7 @@ export const resolvePlaybackMode = ({
   const formatAliases = ffprobe.format.format_name?.split(',').map((s) => s.trim()) ?? []
   const primaryFormat = formatAliases[0] ?? ''
   const containerSupported =
-    formatAliases.some((alias) => codecSupport.containers.includes(alias)) ||
-    BROWSER_NATIVE_PRIMARY_FORMATS.has(primaryFormat)
+    codecSupport.containers.includes(primaryFormat) || BROWSER_NATIVE_PRIMARY_FORMATS.has(primaryFormat)
 
   if (videoSupported && audioSupported && containerSupported) {
     return { mode: 'direct-play', warnings }
diff --git a/yarn.lock b/yarn.lock
index aa04992a..55382f04 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -4689,6 +4689,7 @@ __metadata:
     "@xterm/addon-web-links": "npm:^0.12.0"
     "@xterm/xterm": "npm:^6.0.0"
     common: "workspace:^"
+    hls.js: "npm:^1.6.15"
     ollama: "npm:^0.6.3"
     path-to-regexp: "npm:^8.3.0"
     typescript: "npm:^5.9.3"
@@ -5106,6 +5107,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"hls.js@npm:^1.6.15":
+  version: 1.6.15
+  resolution: "hls.js@npm:1.6.15"
+  checksum: 10c0/a3558909506b9d93420b395b1d9508df364f911ebc19b315f98bd4c1b94973ed996a95fe8662756a3fca96b762af741d13df81987bc68322f473acacbecbc6d9
+  languageName: node
+  linkType: hard
+
 "hpagent@npm:^1.2.0":
   version: 1.2.0
   resolution: "hpagent@npm:1.2.0"

From 8e384caaa4c1676c6b79c3d1298d4738c8b9e644 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Fri, 27 Mar 2026 12:13:29 +0100
Subject: [PATCH 27/30] code review fixes

---
 .yarn/changelogs/common.90cc3afc.md           |  7 +++++-
 .yarn/changelogs/frontend.90cc3afc.md         |  5 ++++
 .../controls/video-container.spec.ts          |  6 ++++-
 .../movie-player-v2/movie-player-service.ts   |  4 ++++
 .../media/actions/hls-master-action.spec.ts   | 24 +++----------------
 service/src/utils/config-watcher.ts           | 13 +++++++---
 6 files changed, 33 insertions(+), 26 deletions(-)

diff --git a/.yarn/changelogs/common.90cc3afc.md b/.yarn/changelogs/common.90cc3afc.md
index a82ab9cb..b2ddf71b 100644
--- a/.yarn/changelogs/common.90cc3afc.md
+++ b/.yarn/changelogs/common.90cc3afc.md
@@ -1,4 +1,4 @@
-<!-- version-type: patch -->
+<!-- version-type: minor -->
 
 # common
 
@@ -32,3 +32,8 @@
 - Moved language-dependent fields (`title`, `plot`, `genre`, `thumbnailImageUrl`) from `Movie` and `Series` models into the new localized metadata models
 - Renamed `omdb-not-configured` / `omdb-error` link statuses to `provider-not-configured` / `provider-error` to reflect multi-provider support
 - Renamed `omdbNotConfigured` / `omdbError` scan progress fields to `providerNotConfigured` / `providerError`
+
+## ⚠️ Breaking Changes
+
+- `LinkMovie` response status strings `omdb-not-configured` and `omdb-error` have been renamed to `provider-not-configured` and `provider-error`
+- `ScanProgress` fields `omdbNotConfigured` and `omdbError` have been renamed to `providerNotConfigured` and `providerError`
diff --git a/.yarn/changelogs/frontend.90cc3afc.md b/.yarn/changelogs/frontend.90cc3afc.md
index 7ad2f18d..0959b332 100644
--- a/.yarn/changelogs/frontend.90cc3afc.md
+++ b/.yarn/changelogs/frontend.90cc3afc.md
@@ -44,3 +44,8 @@ Added `LocalizedMetadataService` with caches for fetching `MovieMetadataLocalize
 - Added tests for `session-helpers` utilities
 - Updated `MoviePlayerService` tests for seeking, resolution switching, and start-time support
 - Updated `MoviePlayerV2Component` tests for the new seeking and resolution switching behavior
+
+## ⬆️ Dependencies
+
+- Removed `media-chrome`
+- Re-added `hls.js` (^1.6.15) for cross-browser HLS playback support
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/video-container.spec.ts b/frontend/src/pages/movies/movie-player-v2/controls/video-container.spec.ts
index df192348..d314ac4f 100644
--- a/frontend/src/pages/movies/movie-player-v2/controls/video-container.spec.ts
+++ b/frontend/src/pages/movies/movie-player-v2/controls/video-container.spec.ts
@@ -1,4 +1,8 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('./control-bar.js', () => ({ ControlBar: {} }))
+vi.mock('./error-overlay.js', () => ({ ErrorOverlay: {} }))
+vi.mock('./loading-overlay.js', () => ({ LoadingOverlay: {} }))
 
 /**
  * VideoContainer is a Shades component whose logic is integration-level:
diff --git a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
index 6da4abe4..de8dbf5d 100644
--- a/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
+++ b/frontend/src/pages/movies/movie-player-v2/movie-player-service.ts
@@ -89,6 +89,7 @@ export class MoviePlayerService implements AsyncDisposable {
 
   private videoEventCleanup: Disposable | null = null
   private hlsInstance: Hls | null = null
+  private isProgrammaticSeek = false
 
   /**
    * Converts a 0-based stream time (from video.currentTime during HLS)
@@ -237,6 +238,7 @@ export class MoviePlayerService implements AsyncDisposable {
       this.progress.setValue(this.streamTimeToAbsolute(video.currentTime) || 0)
     }
     const onSeeking = () => {
+      if (this.isProgrammaticSeek) return
       this.seekToTime(this.streamTimeToAbsolute(video.currentTime))
     }
     const onFullscreenChange = () => {
@@ -454,7 +456,9 @@ export class MoviePlayerService implements AsyncDisposable {
     if (streamTime >= 0 && this.isTimeBuffered(video, streamTime)) return
 
     if (targetSeconds >= this.hlsStartTime) {
+      this.isProgrammaticSeek = true
       video.currentTime = targetSeconds - this.hlsStartTime
+      this.isProgrammaticSeek = false
       return
     }
 
diff --git a/service/src/app-models/media/actions/hls-master-action.spec.ts b/service/src/app-models/media/actions/hls-master-action.spec.ts
index 5e571b27..4ca26dd1 100644
--- a/service/src/app-models/media/actions/hls-master-action.spec.ts
+++ b/service/src/app-models/media/actions/hls-master-action.spec.ts
@@ -17,14 +17,6 @@ vi.mock('@furystack/logging', () => ({
   }),
 }))
 
-const mockFind = vi.fn()
-
-vi.mock('@furystack/repository', () => ({
-  getDataSetFor: () => ({
-    find: (...args: unknown[]) => mockFind(...args) as unknown,
-  }),
-}))
-
 const mockFfprobe: FfprobeData = {
   streams: [
     { index: 0, codec_type: 'video', codec_name: 'h264', width: 1920, height: 1080, tags: {} },
@@ -43,8 +35,6 @@ const mockFfprobe: FfprobeData = {
 
 describe('HlsMasterAction', () => {
   it('should return a valid M3U8 master playlist', async () => {
-    mockFind.mockResolvedValue([])
-
     let writtenBody = ''
     const response = {
       writeHead: vi.fn(),
@@ -77,8 +67,6 @@ describe('HlsMasterAction', () => {
   })
 
   it('should use codec support from query params', async () => {
-    mockFind.mockResolvedValue([])
-
     let writtenBody = ''
     const response = {
       writeHead: vi.fn(),
@@ -105,14 +93,7 @@ describe('HlsMasterAction', () => {
     })
   })
 
-  it('should include subtitle tracks from related files', async () => {
-    mockFind.mockResolvedValue([
-      {
-        imdbId: 'tt1234',
-        relatedFiles: [{ type: 'subtitle', path: 'movies/test.eng.srt' }],
-      },
-    ])
-
+  it('should not include subtitle entries in master playlist (handled via HTML track elements)', async () => {
     let writtenBody = ''
     const response = {
       writeHead: vi.fn(),
@@ -135,7 +116,8 @@ describe('HlsMasterAction', () => {
         request: {} as IncomingMessage,
       })
 
-      expect(writtenBody).toContain('TYPE=SUBTITLES')
+      expect(writtenBody).not.toContain('TYPE=SUBTITLES')
+      expect(writtenBody).not.toContain('SUBTITLES=')
     })
   })
 })
diff --git a/service/src/utils/config-watcher.ts b/service/src/utils/config-watcher.ts
index 041accf6..a2dcedb7 100644
--- a/service/src/utils/config-watcher.ts
+++ b/service/src/utils/config-watcher.ts
@@ -22,9 +22,13 @@ export type ConfigWatcher = {
  * The DataSet stores `Config` objects (with `createdAt`/`updatedAt`) but individual
  * config interfaces (`OmdbConfig`, `TmdbConfig`, etc.) only define `id` and `value`.
  * This helper narrows a loaded `Config` to the caller's expected `TConfig` shape.
+ *
+ * The caller guarantees the correct `TConfig` by filtering on `configId`, so the
+ * assertion is safe at runtime even though TypeScript cannot statically verify the
+ * id-value pairing within the `ConfigType` union.
  */
-const narrowConfig = <TConfig extends ConfigType>(raw: Config): TConfig =>
-  ({ id: raw.id, value: raw.value }) as unknown as TConfig
+const narrowConfig = <TConfig extends ConfigType>(raw: Pick<Config, 'id' | 'value'>): TConfig =>
+  ({ id: raw.id, value: raw.value }) as TConfig
 
 export const createConfigWatcher = <TConfig extends ConfigType>(
   options: ConfigWatcherOptions<TConfig>,
@@ -60,7 +64,10 @@ export const createConfigWatcher = <TConfig extends ConfigType>(
       }),
       options.configDataSet.subscribe('onEntityUpdated', ({ change }) => {
         if (change.id === options.configId) {
-          currentConfig = { ...currentConfig, ...change } as unknown as TConfig
+          currentConfig = narrowConfig<TConfig>({
+            id: change.id,
+            value: change.value ?? currentConfig?.value,
+          } as Config)
           options.onChange(currentConfig)
           void options.logger.information({
             message: `🎬   ${options.serviceName} config updated`,

From afcce071e5fef0837a2ce4505d8e63757257c379 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Fri, 27 Mar 2026 12:21:48 +0100
Subject: [PATCH 28/30] cr fixes #2

---
 .../models/config/metadata-provider-config.ts |   2 +-
 common/src/models/config/tmdb-config.ts       |   2 +-
 .../controls/settings-menu.spec.ts            |  15 +-
 .../controls/settings-menu.tsx                |  17 ++-
 .../build-synthetic-movie.spec.ts             | 128 ++++++++++++++++++
 .../external-service-status-registry.spec.ts  |  40 ++++++
 service/src/utils/config-watcher.ts           |  13 +-
 7 files changed, 196 insertions(+), 21 deletions(-)
 create mode 100644 service/src/app-models/media/metadata-services/build-synthetic-movie.spec.ts
 create mode 100644 service/src/external-service-status-registry.spec.ts

diff --git a/common/src/models/config/metadata-provider-config.ts b/common/src/models/config/metadata-provider-config.ts
index 24950679..e11471b9 100644
--- a/common/src/models/config/metadata-provider-config.ts
+++ b/common/src/models/config/metadata-provider-config.ts
@@ -1,4 +1,4 @@
-export interface MetadataProviderConfig {
+export type MetadataProviderConfig = {
   id: 'METADATA_PROVIDER_CONFIG'
   value: {
     /**
diff --git a/common/src/models/config/tmdb-config.ts b/common/src/models/config/tmdb-config.ts
index 635c01ce..7552dbba 100644
--- a/common/src/models/config/tmdb-config.ts
+++ b/common/src/models/config/tmdb-config.ts
@@ -1,4 +1,4 @@
-export interface TmdbConfig {
+export type TmdbConfig = {
   id: 'TMDB_CONFIG'
   value: {
     /**
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.spec.ts b/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.spec.ts
index 77f18d52..16fe37d3 100644
--- a/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.spec.ts
+++ b/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.spec.ts
@@ -18,15 +18,14 @@ describe('SettingsMenu', () => {
   it('should export the component', async () => {
     const mod = await import('./settings-menu.js')
     expect(mod.SettingsMenu).toBeDefined()
-  })
+  }, 15_000)
 })
 
 describe('SPEED_OPTIONS', () => {
-  it('should include expected playback rates', () => {
-    const expected = [0.5, 0.75, 1, 1.25, 1.5, 2]
-    // SPEED_OPTIONS is a module-level const, verify it includes sane values
-    expect(expected).toContain(1)
-    expect(expected.every((r) => r > 0 && r <= 4)).toBe(true)
-    expect(expected).toHaveLength(6)
-  })
+  it('should include expected playback rates', async () => {
+    const { SPEED_OPTIONS } = await import('./settings-menu.js')
+    expect(SPEED_OPTIONS).toContain(1)
+    expect(Array.from(SPEED_OPTIONS).every((r) => r > 0 && r <= 4)).toBe(true)
+    expect(SPEED_OPTIONS).toHaveLength(6)
+  }, 15_000)
 })
diff --git a/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx b/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx
index 48c49d91..ad4b0d98 100644
--- a/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx
+++ b/frontend/src/pages/movies/movie-player-v2/controls/settings-menu.tsx
@@ -10,7 +10,15 @@ type SettingsMenuProps = {
 
 type SubmenuId = 'speed' | 'audio' | 'captions' | null
 
-const SPEED_OPTIONS = [0.5, 0.75, 1, 1.25, 1.5, 2] as const
+const getTagString = (tags: unknown, key: string): string | undefined => {
+  if (tags && typeof tags === 'object') {
+    const value = (tags as Record<string, unknown>)[key]
+    return typeof value === 'string' ? value : undefined
+  }
+  return undefined
+}
+
+export const SPEED_OPTIONS = [0.5, 0.75, 1, 1.25, 1.5, 2] as const
 
 export const SettingsMenu = Shade<SettingsMenuProps>({
   customElementName: 'pirat-player-settings-menu',
@@ -76,11 +84,8 @@ export const SettingsMenu = Shade<SettingsMenuProps>({
       audioTracks.length === 0
         ? props.mediaService.getAudioTracks().map((t) => ({
             index: t.id,
-            label:
-              (t.stream.tags as Record<string, string>)?.title ||
-              (t.stream.tags as Record<string, string>)?.language ||
-              'Audio Track',
-            language: (t.stream.tags as Record<string, string>)?.language || 'unknown',
+            label: getTagString(t.stream.tags, 'title') || getTagString(t.stream.tags, 'language') || 'Audio Track',
+            language: getTagString(t.stream.tags, 'language') || 'unknown',
             codecName: t.codecName ?? 'unknown',
             channels: t.stream.channels ?? 2,
             isDefault: t.stream.disposition?.default === 1,
diff --git a/service/src/app-models/media/metadata-services/build-synthetic-movie.spec.ts b/service/src/app-models/media/metadata-services/build-synthetic-movie.spec.ts
new file mode 100644
index 00000000..41c9d11f
--- /dev/null
+++ b/service/src/app-models/media/metadata-services/build-synthetic-movie.spec.ts
@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest'
+
+import type { TmdbTvDetailsResponse, TmdbEpisodeDetailsResponse } from './tmdb-api-types.js'
+import { buildSyntheticMovieFromEpisode } from './build-synthetic-movie.js'
+
+const makeTvDetails = (overrides?: Partial<TmdbTvDetailsResponse>): TmdbTvDetailsResponse => ({
+  adult: false,
+  backdrop_path: '/tv-backdrop.jpg',
+  created_by: [],
+  episode_run_time: [45],
+  first_air_date: '2020-01-01',
+  genres: [{ id: 18, name: 'Drama' }],
+  homepage: '',
+  id: 100,
+  in_production: false,
+  languages: ['en'],
+  last_air_date: '2020-12-31',
+  last_episode_to_air: null,
+  name: 'Test Series',
+  networks: [],
+  next_episode_to_air: null,
+  number_of_episodes: 10,
+  number_of_seasons: 1,
+  origin_country: ['US'],
+  original_language: 'en',
+  original_name: 'Test Series',
+  overview: 'A test series',
+  popularity: 50,
+  poster_path: '/tv-poster.jpg',
+  production_companies: [],
+  production_countries: [],
+  seasons: [],
+  spoken_languages: [],
+  status: 'Ended',
+  tagline: '',
+  type: 'Scripted',
+  vote_average: 8.0,
+  vote_count: 1000,
+  ...overrides,
+})
+
+const makeEpisodeDetails = (overrides?: Partial<TmdbEpisodeDetailsResponse>): TmdbEpisodeDetailsResponse => ({
+  air_date: '2020-03-15',
+  episode_number: 5,
+  id: 500,
+  name: 'Test Episode',
+  overview: 'Episode overview',
+  production_code: 'S01E05',
+  runtime: 42,
+  season_number: 1,
+  still_path: '/episode-still.jpg',
+  vote_average: 7.5,
+  vote_count: 200,
+  crew: [],
+  guest_stars: [],
+  ...overrides,
+})
+
+describe('buildSyntheticMovieFromEpisode', () => {
+  it('should map all fields correctly', () => {
+    const tv = makeTvDetails()
+    const ep = makeEpisodeDetails()
+    const result = buildSyntheticMovieFromEpisode(tv, ep, 'tt1234567')
+
+    expect(result.imdb_id).toBe('tt1234567')
+    expect(result.id).toBe(ep.id)
+    expect(result.title).toBe(ep.name)
+    expect(result.original_title).toBe(ep.name)
+    expect(result.overview).toBe(ep.overview)
+    expect(result.release_date).toBe(ep.air_date)
+    expect(result.runtime).toBe(42)
+    expect(result.vote_average).toBe(ep.vote_average)
+    expect(result.vote_count).toBe(ep.vote_count)
+  })
+
+  it('should use episode still_path for backdrop', () => {
+    const result = buildSyntheticMovieFromEpisode(makeTvDetails(), makeEpisodeDetails(), 'tt0000001')
+    expect(result.backdrop_path).toBe('/episode-still.jpg')
+  })
+
+  it('should use series poster_path for poster', () => {
+    const result = buildSyntheticMovieFromEpisode(makeTvDetails(), makeEpisodeDetails(), 'tt0000001')
+    expect(result.poster_path).toBe('/tv-poster.jpg')
+  })
+
+  it('should inherit genres from series', () => {
+    const tv = makeTvDetails({
+      genres: [
+        { id: 1, name: 'Action' },
+        { id: 2, name: 'Sci-Fi' },
+      ],
+    })
+    const result = buildSyntheticMovieFromEpisode(tv, makeEpisodeDetails(), 'tt0000001')
+    expect(result.genres).toEqual([
+      { id: 1, name: 'Action' },
+      { id: 2, name: 'Sci-Fi' },
+    ])
+  })
+
+  it('should inherit origin_country and original_language from series', () => {
+    const tv = makeTvDetails({ origin_country: ['GB'], original_language: 'fr' })
+    const result = buildSyntheticMovieFromEpisode(tv, makeEpisodeDetails(), 'tt0000001')
+    expect(result.origin_country).toEqual(['GB'])
+    expect(result.original_language).toBe('fr')
+  })
+
+  it('should default runtime to 0 when episode runtime is null', () => {
+    const ep = makeEpisodeDetails({ runtime: null })
+    const result = buildSyntheticMovieFromEpisode(makeTvDetails(), ep, 'tt0000001')
+    expect(result.runtime).toBe(0)
+  })
+
+  it('should set static fields to expected defaults', () => {
+    const result = buildSyntheticMovieFromEpisode(makeTvDetails(), makeEpisodeDetails(), 'tt0000001')
+    expect(result.adult).toBe(false)
+    expect(result.budget).toBe(0)
+    expect(result.revenue).toBe(0)
+    expect(result.popularity).toBe(0)
+    expect(result.status).toBe('Released')
+    expect(result.video).toBe(false)
+    expect(result.tagline).toBe('')
+    expect(result.homepage).toBe('')
+    expect(result.belongs_to_collection).toBeNull()
+    expect(result.production_companies).toEqual([])
+    expect(result.production_countries).toEqual([])
+    expect(result.spoken_languages).toEqual([])
+  })
+})
diff --git a/service/src/external-service-status-registry.spec.ts b/service/src/external-service-status-registry.spec.ts
new file mode 100644
index 00000000..1fd290c6
--- /dev/null
+++ b/service/src/external-service-status-registry.spec.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest'
+
+import { ExternalServiceStatusRegistry } from './external-service-status-registry.js'
+
+describe('ExternalServiceStatusRegistry', () => {
+  it('should return empty statuses when no providers are registered', () => {
+    const registry = new ExternalServiceStatusRegistry()
+    expect(registry.getStatuses()).toEqual({})
+  })
+
+  it('should register a provider and return its status', () => {
+    const registry = new ExternalServiceStatusRegistry()
+    registry.register('omdb', () => true)
+    expect(registry.getStatuses()).toEqual({ omdb: true })
+  })
+
+  it('should return statuses for multiple providers', () => {
+    const registry = new ExternalServiceStatusRegistry()
+    registry.register('omdb', () => true)
+    registry.register('tmdb', () => false)
+    expect(registry.getStatuses()).toEqual({ omdb: true, tmdb: false })
+  })
+
+  it('should overwrite a provider when registered with the same name', () => {
+    const registry = new ExternalServiceStatusRegistry()
+    registry.register('omdb', () => true)
+    registry.register('omdb', () => false)
+    expect(registry.getStatuses()).toEqual({ omdb: false })
+  })
+
+  it('should call status getters on each getStatuses invocation', () => {
+    const registry = new ExternalServiceStatusRegistry()
+    let isUp = false
+    registry.register('service', () => isUp)
+
+    expect(registry.getStatuses()).toEqual({ service: false })
+    isUp = true
+    expect(registry.getStatuses()).toEqual({ service: true })
+  })
+})
diff --git a/service/src/utils/config-watcher.ts b/service/src/utils/config-watcher.ts
index a2dcedb7..b1fb79b8 100644
--- a/service/src/utils/config-watcher.ts
+++ b/service/src/utils/config-watcher.ts
@@ -64,11 +64,14 @@ export const createConfigWatcher = <TConfig extends ConfigType>(
       }),
       options.configDataSet.subscribe('onEntityUpdated', ({ change }) => {
         if (change.id === options.configId) {
-          currentConfig = narrowConfig<TConfig>({
-            id: change.id,
-            value: change.value ?? currentConfig?.value,
-          } as Config)
-          options.onChange(currentConfig)
+          const mergedValue = change.value ?? currentConfig?.value
+          if (mergedValue == null) {
+            currentConfig = undefined
+            options.onChange(undefined)
+          } else {
+            currentConfig = narrowConfig<TConfig>({ id: change.id, value: mergedValue } as Config)
+            options.onChange(currentConfig)
+          }
           void options.logger.information({
             message: `🎬   ${options.serviceName} config updated`,
             data: change,

From 9eabc27254c01176f5e8613968893de68a9312a3 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Fri, 27 Mar 2026 12:33:47 +0100
Subject: [PATCH 29/30] e2e fix

---
 e2e/file-browser.spec.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/e2e/file-browser.spec.ts b/e2e/file-browser.spec.ts
index 407a3ee3..00352c59 100644
--- a/e2e/file-browser.spec.ts
+++ b/e2e/file-browser.spec.ts
@@ -58,7 +58,12 @@ const deleteFile = async (page: Page, fileName: string) => {
   await expect(file).toBeVisible()
   await file.click()
   await page.keyboard.press('Delete')
-  await assertAndDismissNoty(page, 'The file is deleted succesfully')
+
+  const confirmButton = page.locator('shades-dialog button', { hasText: 'Delete' })
+  await expect(confirmButton).toBeVisible()
+  await confirmButton.click()
+
+  await assertAndDismissNoty(page, 'item(s) deleted successfully')
 }
 
 test.describe('File Browser', () => {

From 03706a0a56f95696dd199ec50e3d81e794df39d4 Mon Sep 17 00:00:00 2001
From: Gallay Lajos <gallay.lajos@gmail.com>
Date: Fri, 27 Mar 2026 12:51:31 +0100
Subject: [PATCH 30/30] typo fix

---
 e2e/file-browser.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/e2e/file-browser.spec.ts b/e2e/file-browser.spec.ts
index 00352c59..dcb9f3cf 100644
--- a/e2e/file-browser.spec.ts
+++ b/e2e/file-browser.spec.ts
@@ -59,7 +59,7 @@ const deleteFile = async (page: Page, fileName: string) => {
   await file.click()
   await page.keyboard.press('Delete')
 
-  const confirmButton = page.locator('shades-dialog button', { hasText: 'Delete' })
+  const confirmButton = page.locator('shade-dialog button', { hasText: /Delete/i })
   await expect(confirmButton).toBeVisible()
   await confirmButton.click()