feat(web): hls player (#28312)

* update e2e

* hls player

* fix transcoding restart on explicit quality selection

* move level filtering to manager

* move init to manager declaration

* refactor commit on release

* these lints...

* fix seek sometimes being ignored

* fix panic downswitch

.github/workflows/cli.yml

@@ -49,7 +49,9 @@ jobs:
 
       - name: Publish
         if: ${{ github.event_name == 'release' }}
-        run: mise run ci-publish
+        env:
+          NPM_TAG: ${{ github.event.release.prerelease && 'rc' || 'latest' }}
+        run: mise run ci-publish -- --tag "$NPM_TAG"
 
   docker:
     name: Docker
@@ -102,7 +104,7 @@ jobs:
             name=ghcr.io/${{ github.repository_owner }}/immich-cli
           tags: |
             type=raw,value=${{ steps.package-version.outputs.version }},enable=${{ github.event_name == 'release' }}
-            type=raw,value=latest,enable=${{ github.event_name == 'release' }}
+            type=raw,value=latest,enable=${{ github.event_name == 'release' && !github.event.release.prerelease }}
 
       - name: Build and push image
         uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0

.github/workflows/docker.yml

@@ -132,7 +132,7 @@ jobs:
             suffixes: '-rocm'
             platforms: linux/amd64
             runner-mapping: '{"linux/amd64": "pokedex-large"}'
-    uses: immich-app/devtools/.github/workflows/multi-runner-build.yml@5813c7c4f7016c748ae7ac5d5f684846649d4d20 # multi-runner-build-workflow-v2.4.0
+    uses: immich-app/devtools/.github/workflows/multi-runner-build.yml@db54dcf16fbb12c43479a23749ceea0ad1b4a704 # multi-runner-build-workflow-v3.0.0
     permissions:
       contents: read
       actions: read
@@ -147,7 +147,7 @@ jobs:
       platforms: ${{ matrix.platforms }}
       runner-mapping: ${{ matrix.runner-mapping }}
       suffixes: ${{ matrix.suffixes }}
-      dockerhub-push: ${{ github.event_name == 'release' }}
+      dockerhub-push: ${{ github.event_name == 'release' && !github.event.release.prerelease }}
       build-args: |
         DEVICE=${{ matrix.device }}
 
@@ -155,7 +155,7 @@ jobs:
     name: Build and Push Server
     needs: pre-job
     if: ${{ fromJSON(needs.pre-job.outputs.should_run).server == true }}
-    uses: immich-app/devtools/.github/workflows/multi-runner-build.yml@5813c7c4f7016c748ae7ac5d5f684846649d4d20 # multi-runner-build-workflow-v2.4.0
+    uses: immich-app/devtools/.github/workflows/multi-runner-build.yml@db54dcf16fbb12c43479a23749ceea0ad1b4a704 # multi-runner-build-workflow-v3.0.0
     permissions:
       contents: read
       actions: read
@@ -167,7 +167,7 @@ jobs:
       image: immich-server
       context: .
       dockerfile: server/Dockerfile
-      dockerhub-push: ${{ github.event_name == 'release' }}
+      dockerhub-push: ${{ github.event_name == 'release' && !github.event.release.prerelease }}
       build-args: |
         DEVICE=cpu
 

.github/workflows/docs-deploy.yml

@@ -98,9 +98,16 @@ jobs:
                 shouldDeploy: true
               };
             } else if (eventType == "release") {
+              const tag = context.payload.workflow_run.head_branch;
+              const { data: release } = await github.rest.repos.getReleaseByTag({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                tag,
+              });
               parameters = {
                 event: "release",
-                name: context.payload.workflow_run.head_branch,
+                name: tag,
+                prerelease: release.prerelease,
                 shouldDeploy: !isFork
               };
             }
@@ -146,6 +153,7 @@ jobs:
             const parameters = JSON.parse(process.env.PARAM_JSON);
             core.setOutput("event", parameters.event);
             core.setOutput("name", parameters.name);
+            core.setOutput("prerelease", parameters.prerelease);
             core.setOutput("shouldDeploy", parameters.shouldDeploy);
 
       - name: Download artifact
@@ -203,7 +211,7 @@ jobs:
         run: mise run //docs:deploy
 
       - name: Deploy Docs Release Domain
-        if: ${{ steps.parameters.outputs.event == 'release' }}
+        if: ${{ steps.parameters.outputs.event == 'release' && steps.parameters.outputs.prerelease != 'true' }}
         env:
           TF_VAR_prefix_name: ${{ steps.parameters.outputs.name}}
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

.github/workflows/prepare-release.yml

@@ -137,7 +137,7 @@ jobs:
           github-token: ${{ steps.generate-token.outputs.token }}
 
       - name: Create draft release
-        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2.6.2
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
         with:
           draft: true
           tag_name: ${{ needs.bump_version.outputs.version }}

.github/workflows/sdk.yml

@@ -39,4 +39,6 @@ jobs:
         run: pnpm --filter @immich/sdk build
 
       - name: Publish
-        run: pnpm --filter @immich/sdk publish --provenance --no-git-checks
+        env:
+          NPM_TAG: ${{ github.event.release.prerelease && 'rc' || 'latest' }}
+        run: pnpm --filter @immich/sdk publish --provenance --no-git-checks --tag "$NPM_TAG"

.github/workflows/test.yml

@@ -374,7 +374,7 @@ jobs:
           token: ${{ steps.token.outputs.token }}
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
 
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -451,7 +451,7 @@ jobs:
           token: ${{ steps.token.outputs.token }}
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
 
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0

e2e/src/specs/server/api/server.e2e-spec.ts

@@ -95,6 +95,7 @@ describe('/server', () => {
         major: expect.any(Number),
         minor: expect.any(Number),
         patch: expect.any(Number),
+        prerelease: null,
       });
     });
   });
@@ -115,6 +116,7 @@ describe('/server', () => {
         oauthAutoLaunch: false,
         ocr: false,
         passwordLogin: true,
+        realtimeTranscoding: false,
         search: true,
         sidecar: true,
         trash: true,

e2e/src/specs/server/api/system-config.e2e-spec.ts

@@ -21,18 +21,18 @@ describe('/system-config', () => {
       const response1 = await request(app)
         .put('/system-config')
         .set('Authorization', `Bearer ${admin.accessToken}`)
-        .send({ ...config, newVersionCheck: { enabled: false } });
+        .send({ ...config, newVersionCheck: { enabled: false, channel: 'stable' } });
 
       expect(response1.status).toBe(200);
-      expect(response1.body).toEqual({ ...config, newVersionCheck: { enabled: false } });
+      expect(response1.body).toEqual({ ...config, newVersionCheck: { enabled: false, channel: 'stable' } });
 
       const response2 = await request(app)
         .put('/system-config')
         .set('Authorization', `Bearer ${admin.accessToken}`)
-        .send({ ...config, newVersionCheck: { enabled: true } });
+        .send({ ...config, newVersionCheck: { enabled: true, channel: 'stable' } });
 
       expect(response2.status).toBe(200);
-      expect(response2.body).toEqual({ ...config, newVersionCheck: { enabled: true } });
+      expect(response2.body).toEqual({ ...config, newVersionCheck: { enabled: true, channel: 'stable' } });
     });
 
     it('should reject an invalid config entry', async () => {

i18n/en.json

@@ -305,6 +305,8 @@
     "refreshing_all_libraries": "Refreshing all libraries",
     "registration": "Admin Registration",
     "registration_description": "Since you are the first user on the system, you will be assigned as the Admin and are responsible for administrative tasks, and additional users will be created by you.",
+    "release_channel_release_candidate": "Release candidate",
+    "release_channel_stable": "Stable",
     "remove_failed_jobs": "Remove failed jobs",
     "require_password_change_on_login": "Require user to change password on first login",
     "reset_settings_to_default": "Reset settings to default",
@@ -399,6 +401,10 @@
     "transcoding_preferred_hardware_device_description": "Applies only to VAAPI and QSV. Sets the dri node used for hardware transcoding.",
     "transcoding_preset_preset": "Preset (-preset)",
     "transcoding_preset_preset_description": "Compression speed. Slower presets produce smaller files, and increase quality when targeting a certain bitrate. VP9 ignores speeds above 'faster'.",
+    "transcoding_realtime": "Real-time Transcoding [EXPERIMENTAL]",
+    "transcoding_realtime_description": "Allows transcoding to be performed in real-time as the video is being streamed. Enables quality switching, but may cause higher playback latency and stuttering depending on server capabilities.",
+    "transcoding_realtime_enabled": "Enable real-time transcoding",
+    "transcoding_realtime_enabled_description": "If disabled, the server will refuse to start new real-time transcoding sessions.",
     "transcoding_reference_frames": "Reference frames",
     "transcoding_reference_frames_description": "The number of frames to reference when compressing a given frame. Higher values improve compression efficiency, but slow down encoding. 0 sets this value automatically.",
     "transcoding_required_description": "Only videos not in an accepted format",
@@ -442,6 +448,8 @@
     "user_settings_description": "Manage user settings",
     "user_successfully_removed": "User {email} has been successfully removed.",
     "users_page_description": "Admin users page",
+    "version_check_channel": "Release channel",
+    "version_check_channel_description": "Pick the release channel you want to get version announcements for",
     "version_check_enabled_description": "Enable version check",
     "version_check_implications": "The version check feature relies on periodic communication with {server}",
     "version_check_settings": "Version Check",
@@ -2452,6 +2460,7 @@
   "video": "Video",
   "video_hover_setting": "Play video thumbnail on hover",
   "video_hover_setting_description": "Play video thumbnail when mouse is hovering over item. Even when disabled, playback can be started by hovering over the play icon.",
+  "video_quality": "Video quality",
   "videos": "Videos",
   "videos_count": "{count, plural, one {# Video} other {# Videos}}",
   "videos_only": "Videos only",

mobile/ios/fastlane/Fastfile

@@ -49,7 +49,7 @@ def get_version_from_pubspec
   pubspec = YAML.load_file(pubspec_path)
   
   version_string = pubspec['version']
-  version_string ? version_string.split('+').first : nil
+  version_string ? version_string.split('+').first.split('-').first : nil
 end
   
   # Helper method to configure code signing for all targets

mobile/lib/models/server_info/server_version.model.dart

@@ -2,16 +2,12 @@ import 'package:immich_mobile/utils/semver.dart';
 import 'package:openapi/api.dart';
 
 class ServerVersion extends SemVer {
-  const ServerVersion({required super.major, required super.minor, required super.patch});
+  const ServerVersion({required super.major, required super.minor, required super.patch, super.prerelease});
 
-  @override
-  String toString() {
-    return 'ServerVersion(major: $major, minor: $minor, patch: $patch)';
-  }
+  ServerVersion.fromDto(ServerVersionResponseDto dto)
+    : super(major: dto.major, minor: dto.minor, patch: dto.patch_, prerelease: dto.prerelease);
 
-  ServerVersion.fromDto(ServerVersionResponseDto dto) : super(major: dto.major, minor: dto.minor, patch: dto.patch_);
-
-  bool isAtLeast({int major = 0, int minor = 0, int patch = 0}) {
-    return this >= SemVer(major: major, minor: minor, patch: patch);
+  bool isAtLeast({int major = 0, int minor = 0, int patch = 0, int? prerelease}) {
+    return this >= SemVer(major: major, minor: minor, patch: patch, prerelease: prerelease);
   }
 }

mobile/lib/utils/semver.dart

@@ -1,36 +1,42 @@
-enum SemVerType { major, minor, patch }
+enum SemVerType { major, minor, patch, prerelease }
 
 class SemVer {
   final int major;
   final int minor;
   final int patch;
+  final int? prerelease;
 
-  const SemVer({required this.major, required this.minor, required this.patch});
+  const SemVer({required this.major, required this.minor, required this.patch, this.prerelease});
 
   @override
   String toString() {
-    return '$major.$minor.$patch';
+    return '$major.$minor.$patch${prerelease == null ? '' : '-rc.$prerelease'}';
   }
 
-  SemVer copyWith({int? major, int? minor, int? patch}) {
-    return SemVer(major: major ?? this.major, minor: minor ?? this.minor, patch: patch ?? this.patch);
+  SemVer copyWith({int? major, int? minor, int? patch, int? prerelease}) {
+    return SemVer(
+      major: major ?? this.major,
+      minor: minor ?? this.minor,
+      patch: patch ?? this.patch,
+      prerelease: prerelease ?? this.prerelease,
+    );
   }
 
+  static final _pattern = RegExp(r'^v?(\d+)\.(\d+)\.(\d+)(?:-rc\.(\d+))?(?:[-+].*)?$', caseSensitive: false);
+
   factory SemVer.fromString(String version) {
-    if (version.toLowerCase().startsWith("v")) {
-      version = version.substring(1);
-    }
-
-    final parts = version.split("-")[0].split('.');
-    if (parts.length != 3) {
+    final match = _pattern.firstMatch(version);
+    if (match == null) {
       throw FormatException('Invalid semantic version string: $version');
     }
 
-    try {
-      return SemVer(major: int.parse(parts[0]), minor: int.parse(parts[1]), patch: int.parse(parts[2]));
-    } catch (e) {
-      throw FormatException('Invalid semantic version string: $version');
-    }
+    final prerelease = match.group(4);
+    return SemVer(
+      major: int.parse(match.group(1)!),
+      minor: int.parse(match.group(2)!),
+      patch: int.parse(match.group(3)!),
+      prerelease: prerelease == null ? null : int.parse(prerelease),
+    );
   }
 
   bool operator >(SemVer other) {
@@ -40,7 +46,10 @@ class SemVer {
     if (minor != other.minor) {
       return minor > other.minor;
     }
-    return patch > other.patch;
+    if (patch != other.patch) {
+      return patch > other.patch;
+    }
+    return _comparePrerelease(other) > 0;
   }
 
   bool operator <(SemVer other) {
@@ -50,7 +59,23 @@ class SemVer {
     if (minor != other.minor) {
       return minor < other.minor;
     }
-    return patch < other.patch;
+    if (patch != other.patch) {
+      return patch < other.patch;
+    }
+    return _comparePrerelease(other) < 0;
+  }
+
+  int _comparePrerelease(SemVer other) {
+    if (prerelease == other.prerelease) {
+      return 0;
+    }
+    if (prerelease == null) {
+      return 1;
+    }
+    if (other.prerelease == null) {
+      return -1;
+    }
+    return prerelease!.compareTo(other.prerelease!);
   }
 
   bool operator >=(SemVer other) {
@@ -67,7 +92,11 @@ class SemVer {
       return true;
     }
 
-    return other is SemVer && other.major == major && other.minor == minor && other.patch == patch;
+    return other is SemVer &&
+        other.major == major &&
+        other.minor == minor &&
+        other.patch == patch &&
+        other.prerelease == prerelease;
   }
 
   SemVerType? differenceType(SemVer other) {
@@ -80,10 +109,13 @@ class SemVer {
     if (patch != other.patch) {
       return SemVerType.patch;
     }
+    if (prerelease != other.prerelease) {
+      return SemVerType.prerelease;
+    }
 
     return null;
   }
 
   @override
-  int get hashCode => major.hashCode ^ minor.hashCode ^ patch.hashCode;
+  int get hashCode => major.hashCode ^ minor.hashCode ^ patch.hashCode ^ prerelease.hashCode;
 }

mobile/lib/widgets/common/app_bar_dialog/app_bar_server_info.dart

@@ -50,9 +50,7 @@ class AppBarServerInfo extends HookConsumerWidget {
           divider,
           _ServerInfoItem(
             label: "server_version".tr(),
-            text: serverInfoState.serverVersion.major > 0
-                ? "${serverInfoState.serverVersion.major}.${serverInfoState.serverVersion.minor}.${serverInfoState.serverVersion.patch}"
-                : "--",
+            text: serverInfoState.serverVersion.major > 0 ? "${serverInfoState.serverVersion}" : "--",
           ),
           divider,
           _ServerInfoItem(label: "server_info_box_server_url".tr(), text: getServerUrl() ?? '--', tooltip: true),
@@ -60,9 +58,7 @@ class AppBarServerInfo extends HookConsumerWidget {
             divider,
             _ServerInfoItem(
               label: "latest_version".tr(),
-              text: serverInfoState.latestVersion!.major > 0
-                  ? "${serverInfoState.latestVersion!.major}.${serverInfoState.latestVersion!.minor}.${serverInfoState.latestVersion!.patch}"
-                  : "--",
+              text: serverInfoState.latestVersion!.major > 0 ? "${serverInfoState.latestVersion!}" : "--",
               tooltip: true,
               icon: serverInfoState.versionStatus == VersionStatus.serverOutOfDate
                   ? const Icon(Icons.info, color: Color.fromARGB(255, 243, 188, 106), size: 12)

mobile/openapi/README.md

@@ -103,12 +103,16 @@ Class | Method | HTTP request | Description
 *AssetsApi* | [**deleteBulkAssetMetadata**](doc//AssetsApi.md#deletebulkassetmetadata) | **DELETE** /assets/metadata | Delete asset metadata
 *AssetsApi* | [**downloadAsset**](doc//AssetsApi.md#downloadasset) | **GET** /assets/{id}/original | Download original asset
 *AssetsApi* | [**editAsset**](doc//AssetsApi.md#editasset) | **PUT** /assets/{id}/edits | Apply edits to an existing asset
+*AssetsApi* | [**endSession**](doc//AssetsApi.md#endsession) | **DELETE** /assets/{id}/video/stream/{sessionId} | End HLS streaming session
 *AssetsApi* | [**getAssetEdits**](doc//AssetsApi.md#getassetedits) | **GET** /assets/{id}/edits | Retrieve edits for an existing asset
 *AssetsApi* | [**getAssetInfo**](doc//AssetsApi.md#getassetinfo) | **GET** /assets/{id} | Retrieve an asset
 *AssetsApi* | [**getAssetMetadata**](doc//AssetsApi.md#getassetmetadata) | **GET** /assets/{id}/metadata | Get asset metadata
 *AssetsApi* | [**getAssetMetadataByKey**](doc//AssetsApi.md#getassetmetadatabykey) | **GET** /assets/{id}/metadata/{key} | Retrieve asset metadata by key
 *AssetsApi* | [**getAssetOcr**](doc//AssetsApi.md#getassetocr) | **GET** /assets/{id}/ocr | Retrieve asset OCR data
 *AssetsApi* | [**getAssetStatistics**](doc//AssetsApi.md#getassetstatistics) | **GET** /assets/statistics | Get asset statistics
+*AssetsApi* | [**getMainPlaylist**](doc//AssetsApi.md#getmainplaylist) | **GET** /assets/{id}/video/stream/main.m3u8 | Get HLS main playlist
+*AssetsApi* | [**getMediaPlaylist**](doc//AssetsApi.md#getmediaplaylist) | **GET** /assets/{id}/video/stream/{sessionId}/{variantIndex}/playlist.m3u8 | Get HLS media playlist
+*AssetsApi* | [**getSegment**](doc//AssetsApi.md#getsegment) | **GET** /assets/{id}/video/stream/{sessionId}/{variantIndex}/{filename} | Get HLS segment or init file
 *AssetsApi* | [**playAssetVideo**](doc//AssetsApi.md#playassetvideo) | **GET** /assets/{id}/video/playback | Play asset video
 *AssetsApi* | [**removeAssetEdits**](doc//AssetsApi.md#removeassetedits) | **DELETE** /assets/{id}/edits | Remove edits from an existing asset
 *AssetsApi* | [**runAssetJobs**](doc//AssetsApi.md#runassetjobs) | **POST** /assets/jobs | Run an asset job
@@ -513,6 +517,9 @@ Class | Method | HTTP request | Description
  - [RatingsUpdate](doc//RatingsUpdate.md)
  - [ReactionLevel](doc//ReactionLevel.md)
  - [ReactionType](doc//ReactionType.md)
+ - [ReleaseChannel](doc//ReleaseChannel.md)
+ - [ReleaseEventV1](doc//ReleaseEventV1.md)
+ - [ReleaseType](doc//ReleaseType.md)
  - [ReverseGeocodingStateResponseDto](doc//ReverseGeocodingStateResponseDto.md)
  - [RotateParameters](doc//RotateParameters.md)
  - [SearchAlbumResponseDto](doc//SearchAlbumResponseDto.md)
@@ -597,6 +604,7 @@ Class | Method | HTTP request | Description
  - [SystemConfigBackupsDto](doc//SystemConfigBackupsDto.md)
  - [SystemConfigDto](doc//SystemConfigDto.md)
  - [SystemConfigFFmpegDto](doc//SystemConfigFFmpegDto.md)
+ - [SystemConfigFFmpegRealtimeDto](doc//SystemConfigFFmpegRealtimeDto.md)
  - [SystemConfigFacesDto](doc//SystemConfigFacesDto.md)
  - [SystemConfigGeneratedFullsizeImageDto](doc//SystemConfigGeneratedFullsizeImageDto.md)
  - [SystemConfigGeneratedImageDto](doc//SystemConfigGeneratedImageDto.md)

mobile/openapi/lib/api.dart

@@ -258,6 +258,9 @@ part 'model/ratings_response.dart';
 part 'model/ratings_update.dart';
 part 'model/reaction_level.dart';
 part 'model/reaction_type.dart';
+part 'model/release_channel.dart';
+part 'model/release_event_v1.dart';
+part 'model/release_type.dart';
 part 'model/reverse_geocoding_state_response_dto.dart';
 part 'model/rotate_parameters.dart';
 part 'model/search_album_response_dto.dart';
@@ -342,6 +345,7 @@ part 'model/sync_user_v1.dart';
 part 'model/system_config_backups_dto.dart';
 part 'model/system_config_dto.dart';
 part 'model/system_config_f_fmpeg_dto.dart';
+part 'model/system_config_f_fmpeg_realtime_dto.dart';
 part 'model/system_config_faces_dto.dart';
 part 'model/system_config_generated_fullsize_image_dto.dart';
 part 'model/system_config_generated_image_dto.dart';

mobile/openapi/lib/api/assets_api.dart

@@ -423,6 +423,76 @@ class AssetsApi {
     return null;
   }
 
+  /// End HLS streaming session
+  ///
+  /// Releases server resources for the streaming session.
+  ///
+  /// Note: This method returns the HTTP [Response].
+  ///
+  /// Parameters:
+  ///
+  /// * [String] id (required):
+  ///
+  /// * [String] sessionId (required):
+  ///
+  /// * [String] key:
+  ///
+  /// * [String] slug:
+  Future<Response> endSessionWithHttpInfo(String id, String sessionId, { String? key, String? slug, Future<void>? abortTrigger, }) async {
+    // ignore: prefer_const_declarations
+    final apiPath = r'/assets/{id}/video/stream/{sessionId}'
+      .replaceAll('{id}', id)
+      .replaceAll('{sessionId}', sessionId);
+
+    // ignore: prefer_final_locals
+    Object? postBody;
+
+    final queryParams = <QueryParam>[];
+    final headerParams = <String, String>{};
+    final formParams = <String, String>{};
+
+    if (key != null) {
+      queryParams.addAll(_queryParams('', 'key', key));
+    }
+    if (slug != null) {
+      queryParams.addAll(_queryParams('', 'slug', slug));
+    }
+
+    const contentTypes = <String>[];
+
+
+    return apiClient.invokeAPI(
+      apiPath,
+      'DELETE',
+      queryParams,
+      postBody,
+      headerParams,
+      formParams,
+      contentTypes.isEmpty ? null : contentTypes.first,
+      abortTrigger: abortTrigger,
+    );
+  }
+
+  /// End HLS streaming session
+  ///
+  /// Releases server resources for the streaming session.
+  ///
+  /// Parameters:
+  ///
+  /// * [String] id (required):
+  ///
+  /// * [String] sessionId (required):
+  ///
+  /// * [String] key:
+  ///
+  /// * [String] slug:
+  Future<void> endSession(String id, String sessionId, { String? key, String? slug, Future<void>? abortTrigger, }) async {
+    final response = await endSessionWithHttpInfo(id, sessionId, key: key, slug: slug, abortTrigger: abortTrigger,);
+    if (response.statusCode >= HttpStatus.badRequest) {
+      throw ApiException(response.statusCode, await _decodeBodyBytes(response));
+    }
+  }
+
   /// Retrieve edits for an existing asset
   ///
   /// Retrieve a series of edit actions (crop, rotate, mirror) associated with the specified asset.
@@ -822,6 +892,250 @@ class AssetsApi {
     return null;
   }
 
+  /// Get HLS main playlist
+  ///
+  /// Returns an HLS main playlist with all available variants for the asset.
+  ///
+  /// Note: This method returns the HTTP [Response].
+  ///
+  /// Parameters:
+  ///
+  /// * [String] id (required):
+  ///
+  /// * [String] key:
+  ///
+  /// * [String] slug:
+  Future<Response> getMainPlaylistWithHttpInfo(String id, { String? key, String? slug, Future<void>? abortTrigger, }) async {
+    // ignore: prefer_const_declarations
+    final apiPath = r'/assets/{id}/video/stream/main.m3u8'
+      .replaceAll('{id}', id);
+
+    // ignore: prefer_final_locals
+    Object? postBody;
+
+    final queryParams = <QueryParam>[];
+    final headerParams = <String, String>{};
+    final formParams = <String, String>{};
+
+    if (key != null) {
+      queryParams.addAll(_queryParams('', 'key', key));
+    }
+    if (slug != null) {
+      queryParams.addAll(_queryParams('', 'slug', slug));
+    }
+
+    const contentTypes = <String>[];
+
+
+    return apiClient.invokeAPI(
+      apiPath,
+      'GET',
+      queryParams,
+      postBody,
+      headerParams,
+      formParams,
+      contentTypes.isEmpty ? null : contentTypes.first,
+      abortTrigger: abortTrigger,
+    );
+  }
+
+  /// Get HLS main playlist
+  ///
+  /// Returns an HLS main playlist with all available variants for the asset.
+  ///
+  /// Parameters:
+  ///
+  /// * [String] id (required):
+  ///
+  /// * [String] key:
+  ///
+  /// * [String] slug:
+  Future<String?> getMainPlaylist(String id, { String? key, String? slug, Future<void>? abortTrigger, }) async {
+    final response = await getMainPlaylistWithHttpInfo(id, key: key, slug: slug, abortTrigger: abortTrigger,);
+    if (response.statusCode >= HttpStatus.badRequest) {
+      throw ApiException(response.statusCode, await _decodeBodyBytes(response));
+    }
+    // When a remote server returns no body with a status of 204, we shall not decode it.
+    // At the time of writing this, `dart:convert` will throw an "Unexpected end of input"
+    // FormatException when trying to decode an empty string.
+    if (response.body.isNotEmpty && response.statusCode != HttpStatus.noContent) {
+      return await apiClient.deserializeAsync(await _decodeBodyBytes(response), 'String',) as String;
+    
+    }
+    return null;
+  }
+
+  /// Get HLS media playlist
+  ///
+  /// Returns an HLS media playlist for one variant of the streaming session.
+  ///
+  /// Note: This method returns the HTTP [Response].
+  ///
+  /// Parameters:
+  ///
+  /// * [String] id (required):
+  ///
+  /// * [String] sessionId (required):
+  ///
+  /// * [int] variantIndex (required):
+  ///
+  /// * [String] key:
+  ///
+  /// * [String] slug:
+  Future<Response> getMediaPlaylistWithHttpInfo(String id, String sessionId, int variantIndex, { String? key, String? slug, Future<void>? abortTrigger, }) async {
+    // ignore: prefer_const_declarations
+    final apiPath = r'/assets/{id}/video/stream/{sessionId}/{variantIndex}/playlist.m3u8'
+      .replaceAll('{id}', id)
+      .replaceAll('{sessionId}', sessionId)
+      .replaceAll('{variantIndex}', variantIndex.toString());
+
+    // ignore: prefer_final_locals
+    Object? postBody;
+
+    final queryParams = <QueryParam>[];
+    final headerParams = <String, String>{};
+    final formParams = <String, String>{};
+
+    if (key != null) {
+      queryParams.addAll(_queryParams('', 'key', key));
+    }
+    if (slug != null) {
+      queryParams.addAll(_queryParams('', 'slug', slug));
+    }
+
+    const contentTypes = <String>[];
+
+
+    return apiClient.invokeAPI(
+      apiPath,
+      'GET',
+      queryParams,
+      postBody,
+      headerParams,
+      formParams,
+      contentTypes.isEmpty ? null : contentTypes.first,
+      abortTrigger: abortTrigger,
+    );
+  }
+
+  /// Get HLS media playlist
+  ///
+  /// Returns an HLS media playlist for one variant of the streaming session.
+  ///
+  /// Parameters:
+  ///
+  /// * [String] id (required):
+  ///
+  /// * [String] sessionId (required):
+  ///
+  /// * [int] variantIndex (required):
+  ///
+  /// * [String] key:
+  ///
+  /// * [String] slug:
+  Future<String?> getMediaPlaylist(String id, String sessionId, int variantIndex, { String? key, String? slug, Future<void>? abortTrigger, }) async {
+    final response = await getMediaPlaylistWithHttpInfo(id, sessionId, variantIndex, key: key, slug: slug, abortTrigger: abortTrigger,);
+    if (response.statusCode >= HttpStatus.badRequest) {
+      throw ApiException(response.statusCode, await _decodeBodyBytes(response));
+    }
+    // When a remote server returns no body with a status of 204, we shall not decode it.
+    // At the time of writing this, `dart:convert` will throw an "Unexpected end of input"
+    // FormatException when trying to decode an empty string.
+    if (response.body.isNotEmpty && response.statusCode != HttpStatus.noContent) {
+      return await apiClient.deserializeAsync(await _decodeBodyBytes(response), 'String',) as String;
+    
+    }
+    return null;
+  }
+
+  /// Get HLS segment or init file
+  ///
+  /// Streams an HLS init segment (init.mp4) or media segment (seg_N.m4s).
+  ///
+  /// Note: This method returns the HTTP [Response].
+  ///
+  /// Parameters:
+  ///
+  /// * [String] filename (required):
+  ///
+  /// * [String] id (required):
+  ///
+  /// * [String] sessionId (required):
+  ///
+  /// * [int] variantIndex (required):
+  ///
+  /// * [String] key:
+  ///
+  /// * [String] slug:
+  Future<Response> getSegmentWithHttpInfo(String filename, String id, String sessionId, int variantIndex, { String? key, String? slug, Future<void>? abortTrigger, }) async {
+    // ignore: prefer_const_declarations
+    final apiPath = r'/assets/{id}/video/stream/{sessionId}/{variantIndex}/{filename}'
+      .replaceAll('{filename}', filename)
+      .replaceAll('{id}', id)
+      .replaceAll('{sessionId}', sessionId)
+      .replaceAll('{variantIndex}', variantIndex.toString());
+
+    // ignore: prefer_final_locals
+    Object? postBody;
+
+    final queryParams = <QueryParam>[];
+    final headerParams = <String, String>{};
+    final formParams = <String, String>{};
+
+    if (key != null) {
+      queryParams.addAll(_queryParams('', 'key', key));
+    }
+    if (slug != null) {
+      queryParams.addAll(_queryParams('', 'slug', slug));
+    }
+
+    const contentTypes = <String>[];
+
+
+    return apiClient.invokeAPI(
+      apiPath,
+      'GET',
+      queryParams,
+      postBody,
+      headerParams,
+      formParams,
+      contentTypes.isEmpty ? null : contentTypes.first,
+      abortTrigger: abortTrigger,
+    );
+  }
+
+  /// Get HLS segment or init file
+  ///
+  /// Streams an HLS init segment (init.mp4) or media segment (seg_N.m4s).
+  ///
+  /// Parameters:
+  ///
+  /// * [String] filename (required):
+  ///
+  /// * [String] id (required):
+  ///
+  /// * [String] sessionId (required):
+  ///
+  /// * [int] variantIndex (required):
+  ///
+  /// * [String] key:
+  ///
+  /// * [String] slug:
+  Future<MultipartFile?> getSegment(String filename, String id, String sessionId, int variantIndex, { String? key, String? slug, Future<void>? abortTrigger, }) async {
+    final response = await getSegmentWithHttpInfo(filename, id, sessionId, variantIndex, key: key, slug: slug, abortTrigger: abortTrigger,);
+    if (response.statusCode >= HttpStatus.badRequest) {
+      throw ApiException(response.statusCode, await _decodeBodyBytes(response));
+    }
+    // When a remote server returns no body with a status of 204, we shall not decode it.
+    // At the time of writing this, `dart:convert` will throw an "Unexpected end of input"
+    // FormatException when trying to decode an empty string.
+    if (response.body.isNotEmpty && response.statusCode != HttpStatus.noContent) {
+      return await apiClient.deserializeAsync(await _decodeBodyBytes(response), 'MultipartFile',) as MultipartFile;
+    
+    }
+    return null;
+  }
+
   /// Play asset video
   ///
   /// Streams the video file for the specified asset. This endpoint also supports byte range requests.

mobile/openapi/lib/api_client.dart

@@ -563,6 +563,12 @@ class ApiClient {
           return ReactionLevelTypeTransformer().decode(value);
         case 'ReactionType':
           return ReactionTypeTypeTransformer().decode(value);
+        case 'ReleaseChannel':
+          return ReleaseChannelTypeTransformer().decode(value);
+        case 'ReleaseEventV1':
+          return ReleaseEventV1.fromJson(value);
+        case 'ReleaseType':
+          return ReleaseTypeTypeTransformer().decode(value);
         case 'ReverseGeocodingStateResponseDto':
           return ReverseGeocodingStateResponseDto.fromJson(value);
         case 'RotateParameters':
@@ -731,6 +737,8 @@ class ApiClient {
           return SystemConfigDto.fromJson(value);
         case 'SystemConfigFFmpegDto':
           return SystemConfigFFmpegDto.fromJson(value);
+        case 'SystemConfigFFmpegRealtimeDto':
+          return SystemConfigFFmpegRealtimeDto.fromJson(value);
         case 'SystemConfigFacesDto':
           return SystemConfigFacesDto.fromJson(value);
         case 'SystemConfigGeneratedFullsizeImageDto':

mobile/openapi/lib/api_helper.dart

@@ -157,6 +157,12 @@ String parameterToString(dynamic value) {
   if (value is ReactionType) {
     return ReactionTypeTypeTransformer().encode(value).toString();
   }
+  if (value is ReleaseChannel) {
+    return ReleaseChannelTypeTransformer().encode(value).toString();
+  }
+  if (value is ReleaseType) {
+    return ReleaseTypeTypeTransformer().encode(value).toString();
+  }
   if (value is SearchSuggestionType) {
     return SearchSuggestionTypeTypeTransformer().encode(value).toString();
   }

mobile/openapi/lib/model/job_name.dart

@@ -52,6 +52,7 @@ class JobName {
   static const librarySyncFilesQueueAll = JobName._(r'LibrarySyncFilesQueueAll');
   static const librarySyncFiles = JobName._(r'LibrarySyncFiles');
   static const libraryScanQueueAll = JobName._(r'LibraryScanQueueAll');
+  static const hlsSessionCleanup = JobName._(r'HlsSessionCleanup');
   static const memoryCleanup = JobName._(r'MemoryCleanup');
   static const memoryGenerate = JobName._(r'MemoryGenerate');
   static const notificationsCleanup = JobName._(r'NotificationsCleanup');
@@ -110,6 +111,7 @@ class JobName {
     librarySyncFilesQueueAll,
     librarySyncFiles,
     libraryScanQueueAll,
+    hlsSessionCleanup,
     memoryCleanup,
     memoryGenerate,
     notificationsCleanup,
@@ -203,6 +205,7 @@ class JobNameTypeTransformer {
         case r'LibrarySyncFilesQueueAll': return JobName.librarySyncFilesQueueAll;
         case r'LibrarySyncFiles': return JobName.librarySyncFiles;
         case r'LibraryScanQueueAll': return JobName.libraryScanQueueAll;
+        case r'HlsSessionCleanup': return JobName.hlsSessionCleanup;
         case r'MemoryCleanup': return JobName.memoryCleanup;
         case r'MemoryGenerate': return JobName.memoryGenerate;
         case r'NotificationsCleanup': return JobName.notificationsCleanup;

mobile/openapi/lib/model/release_channel.dart

@@ -0,0 +1,85 @@
+//
+// AUTO-GENERATED FILE, DO NOT MODIFY!
+//
+// @dart=2.18
+
+// ignore_for_file: unused_element, unused_import
+// ignore_for_file: always_put_required_named_parameters_first
+// ignore_for_file: constant_identifier_names
+// ignore_for_file: lines_longer_than_80_chars
+
+part of openapi.api;
+
+/// Release channel
+class ReleaseChannel {
+  /// Instantiate a new enum with the provided [value].
+  const ReleaseChannel._(this.value);
+
+  /// The underlying value of this enum member.
+  final String value;
+
+  @override
+  String toString() => value;
+
+  String toJson() => value;
+
+  static const stable = ReleaseChannel._(r'stable');
+  static const releaseCandidate = ReleaseChannel._(r'releaseCandidate');
+
+  /// List of all possible values in this [enum][ReleaseChannel].
+  static const values = <ReleaseChannel>[
+    stable,
+    releaseCandidate,
+  ];
+
+  static ReleaseChannel? fromJson(dynamic value) => ReleaseChannelTypeTransformer().decode(value);
+
+  static List<ReleaseChannel> listFromJson(dynamic json, {bool growable = false,}) {
+    final result = <ReleaseChannel>[];
+    if (json is List && json.isNotEmpty) {
+      for (final row in json) {
+        final value = ReleaseChannel.fromJson(row);
+        if (value != null) {
+          result.add(value);
+        }
+      }
+    }
+    return result.toList(growable: growable);
+  }
+}
+
+/// Transformation class that can [encode] an instance of [ReleaseChannel] to String,
+/// and [decode] dynamic data back to [ReleaseChannel].
+class ReleaseChannelTypeTransformer {
+  factory ReleaseChannelTypeTransformer() => _instance ??= const ReleaseChannelTypeTransformer._();
+
+  const ReleaseChannelTypeTransformer._();
+
+  String encode(ReleaseChannel data) => data.value;
+
+  /// Decodes a [dynamic value][data] to a ReleaseChannel.
+  ///
+  /// If [allowNull] is true and the [dynamic value][data] cannot be decoded successfully,
+  /// then null is returned. However, if [allowNull] is false and the [dynamic value][data]
+  /// cannot be decoded successfully, then an [UnimplementedError] is thrown.
+  ///
+  /// The [allowNull] is very handy when an API changes and a new enum value is added or removed,
+  /// and users are still using an old app with the old code.
+  ReleaseChannel? decode(dynamic data, {bool allowNull = true}) {
+    if (data != null) {
+      switch (data) {
+        case r'stable': return ReleaseChannel.stable;
+        case r'releaseCandidate': return ReleaseChannel.releaseCandidate;
+        default:
+          if (!allowNull) {
+            throw ArgumentError('Unknown enum value to decode: $data');
+          }
+      }
+    }
+    return null;
+  }
+
+  /// Singleton [ReleaseChannelTypeTransformer] instance.
+  static ReleaseChannelTypeTransformer? _instance;
+}
+

mobile/openapi/lib/model/release_event_v1.dart

@@ -0,0 +1,133 @@
+//
+// AUTO-GENERATED FILE, DO NOT MODIFY!
+//
+// @dart=2.18
+
+// ignore_for_file: unused_element, unused_import
+// ignore_for_file: always_put_required_named_parameters_first
+// ignore_for_file: constant_identifier_names
+// ignore_for_file: lines_longer_than_80_chars
+
+part of openapi.api;
+
+class ReleaseEventV1 {
+  /// Returns a new [ReleaseEventV1] instance.
+  ReleaseEventV1({
+    required this.checkedAt,
+    required this.isAvailable,
+    required this.releaseVersion,
+    required this.serverVersion,
+    required this.type,
+  });
+
+  /// When the server last checked for a latest version. As an ISO timestamp
+  String checkedAt;
+
+  /// Whether a new version is available
+  bool isAvailable;
+
+  ServerVersionResponseDto releaseVersion;
+
+  ServerVersionResponseDto serverVersion;
+
+  ReleaseType type;
+
+  @override
+  bool operator ==(Object other) => identical(this, other) || other is ReleaseEventV1 &&
+    other.checkedAt == checkedAt &&
+    other.isAvailable == isAvailable &&
+    other.releaseVersion == releaseVersion &&
+    other.serverVersion == serverVersion &&
+    other.type == type;
+
+  @override
+  int get hashCode =>
+    // ignore: unnecessary_parenthesis
+    (checkedAt.hashCode) +
+    (isAvailable.hashCode) +
+    (releaseVersion.hashCode) +
+    (serverVersion.hashCode) +
+    (type.hashCode);
+
+  @override
+  String toString() => 'ReleaseEventV1[checkedAt=$checkedAt, isAvailable=$isAvailable, releaseVersion=$releaseVersion, serverVersion=$serverVersion, type=$type]';
+
+  Map<String, dynamic> toJson() {
+    final json = <String, dynamic>{};
+      json[r'checkedAt'] = this.checkedAt;
+      json[r'isAvailable'] = this.isAvailable;
+      json[r'releaseVersion'] = this.releaseVersion;
+      json[r'serverVersion'] = this.serverVersion;
+      json[r'type'] = this.type;
+    return json;
+  }
+
+  /// Returns a new [ReleaseEventV1] instance and imports its values from
+  /// [value] if it's a [Map], null otherwise.
+  // ignore: prefer_constructors_over_static_methods
+  static ReleaseEventV1? fromJson(dynamic value) {
+    upgradeDto(value, "ReleaseEventV1");
+    if (value is Map) {
+      final json = value.cast<String, dynamic>();
+
+      return ReleaseEventV1(
+        checkedAt: mapValueOfType<String>(json, r'checkedAt')!,
+        isAvailable: mapValueOfType<bool>(json, r'isAvailable')!,
+        releaseVersion: ServerVersionResponseDto.fromJson(json[r'releaseVersion'])!,
+        serverVersion: ServerVersionResponseDto.fromJson(json[r'serverVersion'])!,
+        type: ReleaseType.fromJson(json[r'type'])!,
+      );
+    }
+    return null;
+  }
+
+  static List<ReleaseEventV1> listFromJson(dynamic json, {bool growable = false,}) {
+    final result = <ReleaseEventV1>[];
+    if (json is List && json.isNotEmpty) {
+      for (final row in json) {
+        final value = ReleaseEventV1.fromJson(row);
+        if (value != null) {
+          result.add(value);
+        }
+      }
+    }
+    return result.toList(growable: growable);
+  }
+
+  static Map<String, ReleaseEventV1> mapFromJson(dynamic json) {
+    final map = <String, ReleaseEventV1>{};
+    if (json is Map && json.isNotEmpty) {
+      json = json.cast<String, dynamic>(); // ignore: parameter_assignments
+      for (final entry in json.entries) {
+        final value = ReleaseEventV1.fromJson(entry.value);
+        if (value != null) {
+          map[entry.key] = value;
+        }
+      }
+    }
+    return map;
+  }
+
+  // maps a json object with a list of ReleaseEventV1-objects as value to a dart map
+  static Map<String, List<ReleaseEventV1>> mapListFromJson(dynamic json, {bool growable = false,}) {
+    final map = <String, List<ReleaseEventV1>>{};
+    if (json is Map && json.isNotEmpty) {
+      // ignore: parameter_assignments
+      json = json.cast<String, dynamic>();
+      for (final entry in json.entries) {
+        map[entry.key] = ReleaseEventV1.listFromJson(entry.value, growable: growable,);
+      }
+    }
+    return map;
+  }
+
+  /// The list of required keys that must be present in a JSON.
+  static const requiredKeys = <String>{
+    'checkedAt',
+    'isAvailable',
+    'releaseVersion',
+    'serverVersion',
+    'type',
+  };
+}
+

mobile/openapi/lib/model/release_type.dart

@@ -0,0 +1,100 @@
+//
+// AUTO-GENERATED FILE, DO NOT MODIFY!
+//
+// @dart=2.18
+
+// ignore_for_file: unused_element, unused_import
+// ignore_for_file: always_put_required_named_parameters_first
+// ignore_for_file: constant_identifier_names
+// ignore_for_file: lines_longer_than_80_chars
+
+part of openapi.api;
+
+
+class ReleaseType {
+  /// Instantiate a new enum with the provided [value].
+  const ReleaseType._(this.value);
+
+  /// The underlying value of this enum member.
+  final String value;
+
+  @override
+  String toString() => value;
+
+  String toJson() => value;
+
+  static const major = ReleaseType._(r'major');
+  static const premajor = ReleaseType._(r'premajor');
+  static const minor = ReleaseType._(r'minor');
+  static const preminor = ReleaseType._(r'preminor');
+  static const patch_ = ReleaseType._(r'patch');
+  static const prepatch = ReleaseType._(r'prepatch');
+  static const prerelease = ReleaseType._(r'prerelease');
+
+  /// List of all possible values in this [enum][ReleaseType].
+  static const values = <ReleaseType>[
+    major,
+    premajor,
+    minor,
+    preminor,
+    patch_,
+    prepatch,
+    prerelease,
+  ];
+
+  static ReleaseType? fromJson(dynamic value) => ReleaseTypeTypeTransformer().decode(value);
+
+  static List<ReleaseType> listFromJson(dynamic json, {bool growable = false,}) {
+    final result = <ReleaseType>[];
+    if (json is List && json.isNotEmpty) {
+      for (final row in json) {
+        final value = ReleaseType.fromJson(row);
+        if (value != null) {
+          result.add(value);
+        }
+      }
+    }
+    return result.toList(growable: growable);
+  }
+}
+
+/// Transformation class that can [encode] an instance of [ReleaseType] to String,
+/// and [decode] dynamic data back to [ReleaseType].
+class ReleaseTypeTypeTransformer {
+  factory ReleaseTypeTypeTransformer() => _instance ??= const ReleaseTypeTypeTransformer._();
+
+  const ReleaseTypeTypeTransformer._();
+
+  String encode(ReleaseType data) => data.value;
+
+  /// Decodes a [dynamic value][data] to a ReleaseType.
+  ///
+  /// If [allowNull] is true and the [dynamic value][data] cannot be decoded successfully,
+  /// then null is returned. However, if [allowNull] is false and the [dynamic value][data]
+  /// cannot be decoded successfully, then an [UnimplementedError] is thrown.
+  ///
+  /// The [allowNull] is very handy when an API changes and a new enum value is added or removed,
+  /// and users are still using an old app with the old code.
+  ReleaseType? decode(dynamic data, {bool allowNull = true}) {
+    if (data != null) {
+      switch (data) {
+        case r'major': return ReleaseType.major;
+        case r'premajor': return ReleaseType.premajor;
+        case r'minor': return ReleaseType.minor;
+        case r'preminor': return ReleaseType.preminor;
+        case r'patch': return ReleaseType.patch_;
+        case r'prepatch': return ReleaseType.prepatch;
+        case r'prerelease': return ReleaseType.prerelease;
+        default:
+          if (!allowNull) {
+            throw ArgumentError('Unknown enum value to decode: $data');
+          }
+      }
+    }
+    return null;
+  }
+
+  /// Singleton [ReleaseTypeTypeTransformer] instance.
+  static ReleaseTypeTypeTransformer? _instance;
+}
+

mobile/openapi/lib/model/server_features_dto.dart

@@ -23,6 +23,7 @@ class ServerFeaturesDto {
     required this.oauthAutoLaunch,
     required this.ocr,
     required this.passwordLogin,
+    required this.realtimeTranscoding,
     required this.reverseGeocoding,
     required this.search,
     required this.sidecar,
@@ -60,6 +61,9 @@ class ServerFeaturesDto {
   /// Whether password login is enabled
   bool passwordLogin;
 
+  /// Whether real-time transcoding is enabled
+  bool realtimeTranscoding;
+
   /// Whether reverse geocoding is enabled
   bool reverseGeocoding;
 
@@ -87,6 +91,7 @@ class ServerFeaturesDto {
     other.oauthAutoLaunch == oauthAutoLaunch &&
     other.ocr == ocr &&
     other.passwordLogin == passwordLogin &&
+    other.realtimeTranscoding == realtimeTranscoding &&
     other.reverseGeocoding == reverseGeocoding &&
     other.search == search &&
     other.sidecar == sidecar &&
@@ -106,6 +111,7 @@ class ServerFeaturesDto {
     (oauthAutoLaunch.hashCode) +
     (ocr.hashCode) +
     (passwordLogin.hashCode) +
+    (realtimeTranscoding.hashCode) +
     (reverseGeocoding.hashCode) +
     (search.hashCode) +
     (sidecar.hashCode) +
@@ -113,7 +119,7 @@ class ServerFeaturesDto {
     (trash.hashCode);
 
   @override
-  String toString() => 'ServerFeaturesDto[configFile=$configFile, duplicateDetection=$duplicateDetection, email=$email, facialRecognition=$facialRecognition, importFaces=$importFaces, map=$map, oauth=$oauth, oauthAutoLaunch=$oauthAutoLaunch, ocr=$ocr, passwordLogin=$passwordLogin, reverseGeocoding=$reverseGeocoding, search=$search, sidecar=$sidecar, smartSearch=$smartSearch, trash=$trash]';
+  String toString() => 'ServerFeaturesDto[configFile=$configFile, duplicateDetection=$duplicateDetection, email=$email, facialRecognition=$facialRecognition, importFaces=$importFaces, map=$map, oauth=$oauth, oauthAutoLaunch=$oauthAutoLaunch, ocr=$ocr, passwordLogin=$passwordLogin, realtimeTranscoding=$realtimeTranscoding, reverseGeocoding=$reverseGeocoding, search=$search, sidecar=$sidecar, smartSearch=$smartSearch, trash=$trash]';
 
   Map<String, dynamic> toJson() {
     final json = <String, dynamic>{};
@@ -127,6 +133,7 @@ class ServerFeaturesDto {
       json[r'oauthAutoLaunch'] = this.oauthAutoLaunch;
       json[r'ocr'] = this.ocr;
       json[r'passwordLogin'] = this.passwordLogin;
+      json[r'realtimeTranscoding'] = this.realtimeTranscoding;
       json[r'reverseGeocoding'] = this.reverseGeocoding;
       json[r'search'] = this.search;
       json[r'sidecar'] = this.sidecar;
@@ -154,6 +161,7 @@ class ServerFeaturesDto {
         oauthAutoLaunch: mapValueOfType<bool>(json, r'oauthAutoLaunch')!,
         ocr: mapValueOfType<bool>(json, r'ocr')!,
         passwordLogin: mapValueOfType<bool>(json, r'passwordLogin')!,
+        realtimeTranscoding: mapValueOfType<bool>(json, r'realtimeTranscoding')!,
         reverseGeocoding: mapValueOfType<bool>(json, r'reverseGeocoding')!,
         search: mapValueOfType<bool>(json, r'search')!,
         sidecar: mapValueOfType<bool>(json, r'sidecar')!,
@@ -216,6 +224,7 @@ class ServerFeaturesDto {
     'oauthAutoLaunch',
     'ocr',
     'passwordLogin',
+    'realtimeTranscoding',
     'reverseGeocoding',
     'search',
     'sidecar',

mobile/openapi/lib/model/server_version_response_dto.dart

@@ -16,47 +16,61 @@ class ServerVersionResponseDto {
     required this.major,
     required this.minor,
     required this.patch_,
+    required this.prerelease,
   });
 
   /// Major version number
   ///
-  /// Minimum value: -9007199254740991
+  /// Minimum value: 0
   /// Maximum value: 9007199254740991
   int major;
 
   /// Minor version number
   ///
-  /// Minimum value: -9007199254740991
+  /// Minimum value: 0
   /// Maximum value: 9007199254740991
   int minor;
 
   /// Patch version number
   ///
-  /// Minimum value: -9007199254740991
+  /// Minimum value: 0
   /// Maximum value: 9007199254740991
   int patch_;
 
+  /// Pre-release version number
+  ///
+  /// Minimum value: 0
+  /// Maximum value: 9007199254740991
+  int? prerelease;
+
   @override
   bool operator ==(Object other) => identical(this, other) || other is ServerVersionResponseDto &&
     other.major == major &&
     other.minor == minor &&
-    other.patch_ == patch_;
+    other.patch_ == patch_ &&
+    other.prerelease == prerelease;
 
   @override
   int get hashCode =>
     // ignore: unnecessary_parenthesis
     (major.hashCode) +
     (minor.hashCode) +
-    (patch_.hashCode);
+    (patch_.hashCode) +
+    (prerelease == null ? 0 : prerelease!.hashCode);
 
   @override
-  String toString() => 'ServerVersionResponseDto[major=$major, minor=$minor, patch_=$patch_]';
+  String toString() => 'ServerVersionResponseDto[major=$major, minor=$minor, patch_=$patch_, prerelease=$prerelease]';
 
   Map<String, dynamic> toJson() {
     final json = <String, dynamic>{};
       json[r'major'] = this.major;
       json[r'minor'] = this.minor;
       json[r'patch'] = this.patch_;
+    if (this.prerelease != null) {
+      json[r'prerelease'] = this.prerelease;
+    } else {
+    //  json[r'prerelease'] = null;
+    }
     return json;
   }
 
@@ -72,6 +86,7 @@ class ServerVersionResponseDto {
         major: mapValueOfType<int>(json, r'major')!,
         minor: mapValueOfType<int>(json, r'minor')!,
         patch_: mapValueOfType<int>(json, r'patch')!,
+        prerelease: mapValueOfType<int>(json, r'prerelease'),
       );
     }
     return null;
@@ -122,6 +137,7 @@ class ServerVersionResponseDto {
     'major',
     'minor',
     'patch',
+    'prerelease',
   };
 }
 

mobile/openapi/lib/model/system_config_f_fmpeg_dto.dart

@@ -25,6 +25,7 @@ class SystemConfigFFmpegDto {
     required this.maxBitrate,
     required this.preferredHwDevice,
     required this.preset,
+    required this.realtime,
     required this.refs,
     required this.targetAudioCodec,
     required this.targetResolution,
@@ -79,6 +80,8 @@ class SystemConfigFFmpegDto {
   /// Preset
   String preset;
 
+  SystemConfigFFmpegRealtimeDto realtime;
+
   /// References
   ///
   /// Minimum value: 0
@@ -122,6 +125,7 @@ class SystemConfigFFmpegDto {
     other.maxBitrate == maxBitrate &&
     other.preferredHwDevice == preferredHwDevice &&
     other.preset == preset &&
+    other.realtime == realtime &&
     other.refs == refs &&
     other.targetAudioCodec == targetAudioCodec &&
     other.targetResolution == targetResolution &&
@@ -147,6 +151,7 @@ class SystemConfigFFmpegDto {
     (maxBitrate.hashCode) +
     (preferredHwDevice.hashCode) +
     (preset.hashCode) +
+    (realtime.hashCode) +
     (refs.hashCode) +
     (targetAudioCodec.hashCode) +
     (targetResolution.hashCode) +
@@ -158,7 +163,7 @@ class SystemConfigFFmpegDto {
     (twoPass.hashCode);
 
   @override
-  String toString() => 'SystemConfigFFmpegDto[accel=$accel, accelDecode=$accelDecode, acceptedAudioCodecs=$acceptedAudioCodecs, acceptedContainers=$acceptedContainers, acceptedVideoCodecs=$acceptedVideoCodecs, bframes=$bframes, cqMode=$cqMode, crf=$crf, gopSize=$gopSize, maxBitrate=$maxBitrate, preferredHwDevice=$preferredHwDevice, preset=$preset, refs=$refs, targetAudioCodec=$targetAudioCodec, targetResolution=$targetResolution, targetVideoCodec=$targetVideoCodec, temporalAQ=$temporalAQ, threads=$threads, tonemap=$tonemap, transcode=$transcode, twoPass=$twoPass]';
+  String toString() => 'SystemConfigFFmpegDto[accel=$accel, accelDecode=$accelDecode, acceptedAudioCodecs=$acceptedAudioCodecs, acceptedContainers=$acceptedContainers, acceptedVideoCodecs=$acceptedVideoCodecs, bframes=$bframes, cqMode=$cqMode, crf=$crf, gopSize=$gopSize, maxBitrate=$maxBitrate, preferredHwDevice=$preferredHwDevice, preset=$preset, realtime=$realtime, refs=$refs, targetAudioCodec=$targetAudioCodec, targetResolution=$targetResolution, targetVideoCodec=$targetVideoCodec, temporalAQ=$temporalAQ, threads=$threads, tonemap=$tonemap, transcode=$transcode, twoPass=$twoPass]';
 
   Map<String, dynamic> toJson() {
     final json = <String, dynamic>{};
@@ -174,6 +179,7 @@ class SystemConfigFFmpegDto {
       json[r'maxBitrate'] = this.maxBitrate;
       json[r'preferredHwDevice'] = this.preferredHwDevice;
       json[r'preset'] = this.preset;
+      json[r'realtime'] = this.realtime;
       json[r'refs'] = this.refs;
       json[r'targetAudioCodec'] = this.targetAudioCodec;
       json[r'targetResolution'] = this.targetResolution;
@@ -207,6 +213,7 @@ class SystemConfigFFmpegDto {
         maxBitrate: mapValueOfType<String>(json, r'maxBitrate')!,
         preferredHwDevice: mapValueOfType<String>(json, r'preferredHwDevice')!,
         preset: mapValueOfType<String>(json, r'preset')!,
+        realtime: SystemConfigFFmpegRealtimeDto.fromJson(json[r'realtime'])!,
         refs: mapValueOfType<int>(json, r'refs')!,
         targetAudioCodec: AudioCodec.fromJson(json[r'targetAudioCodec'])!,
         targetResolution: mapValueOfType<String>(json, r'targetResolution')!,
@@ -275,6 +282,7 @@ class SystemConfigFFmpegDto {
     'maxBitrate',
     'preferredHwDevice',
     'preset',
+    'realtime',
     'refs',
     'targetAudioCodec',
     'targetResolution',

mobile/openapi/lib/model/system_config_f_fmpeg_realtime_dto.dart

@@ -0,0 +1,100 @@
+//
+// AUTO-GENERATED FILE, DO NOT MODIFY!
+//
+// @dart=2.18
+
+// ignore_for_file: unused_element, unused_import
+// ignore_for_file: always_put_required_named_parameters_first
+// ignore_for_file: constant_identifier_names
+// ignore_for_file: lines_longer_than_80_chars
+
+part of openapi.api;
+
+class SystemConfigFFmpegRealtimeDto {
+  /// Returns a new [SystemConfigFFmpegRealtimeDto] instance.
+  SystemConfigFFmpegRealtimeDto({
+    required this.enabled,
+  });
+
+  /// Enable real-time HLS transcoding (alpha)
+  bool enabled;
+
+  @override
+  bool operator ==(Object other) => identical(this, other) || other is SystemConfigFFmpegRealtimeDto &&
+    other.enabled == enabled;
+
+  @override
+  int get hashCode =>
+    // ignore: unnecessary_parenthesis
+    (enabled.hashCode);
+
+  @override
+  String toString() => 'SystemConfigFFmpegRealtimeDto[enabled=$enabled]';
+
+  Map<String, dynamic> toJson() {
+    final json = <String, dynamic>{};
+      json[r'enabled'] = this.enabled;
+    return json;
+  }
+
+  /// Returns a new [SystemConfigFFmpegRealtimeDto] instance and imports its values from
+  /// [value] if it's a [Map], null otherwise.
+  // ignore: prefer_constructors_over_static_methods
+  static SystemConfigFFmpegRealtimeDto? fromJson(dynamic value) {
+    upgradeDto(value, "SystemConfigFFmpegRealtimeDto");
+    if (value is Map) {
+      final json = value.cast<String, dynamic>();
+
+      return SystemConfigFFmpegRealtimeDto(
+        enabled: mapValueOfType<bool>(json, r'enabled')!,
+      );
+    }
+    return null;
+  }
+
+  static List<SystemConfigFFmpegRealtimeDto> listFromJson(dynamic json, {bool growable = false,}) {
+    final result = <SystemConfigFFmpegRealtimeDto>[];
+    if (json is List && json.isNotEmpty) {
+      for (final row in json) {
+        final value = SystemConfigFFmpegRealtimeDto.fromJson(row);
+        if (value != null) {
+          result.add(value);
+        }
+      }
+    }
+    return result.toList(growable: growable);
+  }
+
+  static Map<String, SystemConfigFFmpegRealtimeDto> mapFromJson(dynamic json) {
+    final map = <String, SystemConfigFFmpegRealtimeDto>{};
+    if (json is Map && json.isNotEmpty) {
+      json = json.cast<String, dynamic>(); // ignore: parameter_assignments
+      for (final entry in json.entries) {
+        final value = SystemConfigFFmpegRealtimeDto.fromJson(entry.value);
+        if (value != null) {
+          map[entry.key] = value;
+        }
+      }
+    }
+    return map;
+  }
+
+  // maps a json object with a list of SystemConfigFFmpegRealtimeDto-objects as value to a dart map
+  static Map<String, List<SystemConfigFFmpegRealtimeDto>> mapListFromJson(dynamic json, {bool growable = false,}) {
+    final map = <String, List<SystemConfigFFmpegRealtimeDto>>{};
+    if (json is Map && json.isNotEmpty) {
+      // ignore: parameter_assignments
+      json = json.cast<String, dynamic>();
+      for (final entry in json.entries) {
+        map[entry.key] = SystemConfigFFmpegRealtimeDto.listFromJson(entry.value, growable: growable,);
+      }
+    }
+    return map;
+  }
+
+  /// The list of required keys that must be present in a JSON.
+  static const requiredKeys = <String>{
+    'enabled',
+  };
+}
+

mobile/openapi/lib/model/system_config_new_version_check_dto.dart

@@ -13,26 +13,32 @@ part of openapi.api;
 class SystemConfigNewVersionCheckDto {
   /// Returns a new [SystemConfigNewVersionCheckDto] instance.
   SystemConfigNewVersionCheckDto({
+    required this.channel,
     required this.enabled,
   });
 
+  ReleaseChannel channel;
+
   /// Enabled
   bool enabled;
 
   @override
   bool operator ==(Object other) => identical(this, other) || other is SystemConfigNewVersionCheckDto &&
+    other.channel == channel &&
     other.enabled == enabled;
 
   @override
   int get hashCode =>
     // ignore: unnecessary_parenthesis
+    (channel.hashCode) +
     (enabled.hashCode);
 
   @override
-  String toString() => 'SystemConfigNewVersionCheckDto[enabled=$enabled]';
+  String toString() => 'SystemConfigNewVersionCheckDto[channel=$channel, enabled=$enabled]';
 
   Map<String, dynamic> toJson() {
     final json = <String, dynamic>{};
+      json[r'channel'] = this.channel;
       json[r'enabled'] = this.enabled;
     return json;
   }
@@ -46,6 +52,7 @@ class SystemConfigNewVersionCheckDto {
       final json = value.cast<String, dynamic>();
 
       return SystemConfigNewVersionCheckDto(
+        channel: ReleaseChannel.fromJson(json[r'channel'])!,
         enabled: mapValueOfType<bool>(json, r'enabled')!,
       );
     }
@@ -94,6 +101,7 @@ class SystemConfigNewVersionCheckDto {
 
   /// The list of required keys that must be present in a JSON.
   static const requiredKeys = <String>{
+    'channel',
     'enabled',
   };
 }

mobile/test/domain/services/sync_stream_service_test.dart

@@ -116,7 +116,7 @@ void main() {
     when(() => mockApi.serverInfoApi).thenReturn(mockServerApi);
     when(
       () => mockServerApi.getServerVersion(),
-    ).thenAnswer((_) async => ServerVersionResponseDto(major: 1, minor: 132, patch_: 0));
+    ).thenAnswer((_) async => ServerVersionResponseDto(major: 1, minor: 132, patch_: 0, prerelease: null));
 
     when(() => mockSyncStreamRepo.updateUsersV1(any())).thenAnswer(successHandler);
     when(() => mockSyncStreamRepo.deleteUsersV1(any())).thenAnswer(successHandler);
@@ -559,7 +559,7 @@ void main() {
       await Store.put(StoreKey.syncMigrationStatus, "[]");
       when(
         () => mockServerApi.getServerVersion(),
-      ).thenAnswer((_) async => ServerVersionResponseDto(major: 2, minor: 4, patch_: 1));
+      ).thenAnswer((_) async => ServerVersionResponseDto(major: 2, minor: 4, patch_: 1, prerelease: null));
 
       await sut.sync();
 
@@ -587,7 +587,7 @@ void main() {
       await Store.put(StoreKey.syncMigrationStatus, "[]");
       when(
         () => mockServerApi.getServerVersion(),
-      ).thenAnswer((_) async => ServerVersionResponseDto(major: 2, minor: 5, patch_: 0));
+      ).thenAnswer((_) async => ServerVersionResponseDto(major: 2, minor: 5, patch_: 0, prerelease: null));
       await sut.sync();
 
       verifyInOrder([
@@ -617,7 +617,7 @@ void main() {
 
       when(
         () => mockServerApi.getServerVersion(),
-      ).thenAnswer((_) async => ServerVersionResponseDto(major: 2, minor: 4, patch_: 1));
+      ).thenAnswer((_) async => ServerVersionResponseDto(major: 2, minor: 4, patch_: 1, prerelease: null));
 
       await sut.sync();
 

mobile/test/unit/utils/semver_test.dart

@@ -88,5 +88,71 @@ void main() {
       expect(version2.minor, 2);
       expect(version2.patch, 3);
     });
+
+    test('Orders later prerelease above earlier prerelease', () {
+      const rc1 = SemVer(major: 1, minor: 151, patch: 0, prerelease: 1);
+      const rc2 = SemVer(major: 1, minor: 151, patch: 0, prerelease: 2);
+      expect(rc2 > rc1, isTrue);
+      expect(rc1 < rc2, isTrue);
+      expect(rc1 == rc2, isFalse);
+    });
+
+    test('Final release outranks its prerelease of the same version', () {
+      const rc = SemVer(major: 1, minor: 151, patch: 0, prerelease: 1);
+      const release = SemVer(major: 1, minor: 151, patch: 0);
+      expect(release > rc, isTrue);
+      expect(rc < release, isTrue);
+    });
+
+    test('Higher major outranks a prerelease regardless of ordinal', () {
+      const rc = SemVer(major: 1, minor: 151, patch: 0, prerelease: 9);
+      const next = SemVer(major: 2, minor: 0, patch: 0);
+      expect(next > rc, isTrue);
+    });
+
+    test('Equal prerelease versions compare as equal', () {
+      const a = SemVer(major: 1, minor: 151, patch: 0, prerelease: 3);
+      const b = SemVer(major: 1, minor: 151, patch: 0, prerelease: 3);
+      expect(a == b, isTrue);
+      expect(a > b, isFalse);
+      expect(a < b, isFalse);
+    });
+
+    test('Reports prerelease difference type', () {
+      const rc1 = SemVer(major: 1, minor: 151, patch: 0, prerelease: 1);
+      const rc2 = SemVer(major: 1, minor: 151, patch: 0, prerelease: 2);
+      expect(rc1.differenceType(rc2), SemVerType.prerelease);
+    });
+
+    test('toString includes prerelease suffix when present', () {
+      const rc = SemVer(major: 1, minor: 151, patch: 0, prerelease: 2);
+      expect(rc.toString(), '1.151.0-rc.2');
+    });
+
+    test('Parses prerelease ordinal from -rc strings', () {
+      final dotted = SemVer.fromString('1.151.0-rc.2');
+      expect(dotted.major, 1);
+      expect(dotted.minor, 151);
+      expect(dotted.patch, 0);
+      expect(dotted.prerelease, 2);
+
+      expect(SemVer.fromString('v1.151.0-rc.3').prerelease, 3);
+      expect(SemVer.fromString('1.2.3-rc.2+build.5').prerelease, 2);
+    });
+
+    test('Plain version string has null prerelease', () {
+      expect(SemVer.fromString('3.0.0').prerelease, isNull);
+    });
+
+    test('Invalid rc suffixes parse without error and have null prerelease', () {
+      final debug = SemVer.fromString('1.2.3-debug');
+      expect(debug.major, 1);
+      expect(debug.minor, 2);
+      expect(debug.patch, 3);
+      expect(debug.prerelease, isNull);
+
+      expect(SemVer.fromString('1.2.3+build.5').prerelease, isNull);
+      expect(SemVer.fromString('1.151.0-rc4').prerelease, isNull);
+    });
   });
 }

open-api/immich-openapi-specs.json

@@ -4308,6 +4308,351 @@
         "x-immich-state": "Stable"
       }
     },
+    "/assets/{id}/video/stream/main.m3u8": {
+      "get": {
+        "description": "Returns an HLS main playlist with all available variants for the asset.",
+        "operationId": "getMainPlaylist",
+        "parameters": [
+          {
+            "name": "id",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
+              "type": "string"
+            }
+          },
+          {
+            "name": "key",
+            "required": false,
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "slug",
+            "required": false,
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/vnd.apple.mpegurl": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "description": ""
+          }
+        },
+        "security": [
+          {
+            "bearer": []
+          },
+          {
+            "cookie": []
+          },
+          {
+            "api_key": []
+          }
+        ],
+        "summary": "Get HLS main playlist",
+        "tags": [
+          "Assets"
+        ],
+        "x-immich-history": [
+          {
+            "version": "v3",
+            "state": "Added"
+          },
+          {
+            "version": "v3",
+            "state": "Alpha"
+          }
+        ],
+        "x-immich-permission": "asset.view",
+        "x-immich-state": "Alpha"
+      }
+    },
+    "/assets/{id}/video/stream/{sessionId}": {
+      "delete": {
+        "description": "Releases server resources for the streaming session.",
+        "operationId": "endSession",
+        "parameters": [
+          {
+            "name": "id",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
+              "type": "string"
+            }
+          },
+          {
+            "name": "key",
+            "required": false,
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "sessionId",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
+              "type": "string"
+            }
+          },
+          {
+            "name": "slug",
+            "required": false,
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": ""
+          }
+        },
+        "security": [
+          {
+            "bearer": []
+          },
+          {
+            "cookie": []
+          },
+          {
+            "api_key": []
+          }
+        ],
+        "summary": "End HLS streaming session",
+        "tags": [
+          "Assets"
+        ],
+        "x-immich-history": [
+          {
+            "version": "v3",
+            "state": "Added"
+          },
+          {
+            "version": "v3",
+            "state": "Alpha"
+          }
+        ],
+        "x-immich-permission": "asset.view",
+        "x-immich-state": "Alpha"
+      }
+    },
+    "/assets/{id}/video/stream/{sessionId}/{variantIndex}/playlist.m3u8": {
+      "get": {
+        "description": "Returns an HLS media playlist for one variant of the streaming session.",
+        "operationId": "getMediaPlaylist",
+        "parameters": [
+          {
+            "name": "id",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
+              "type": "string"
+            }
+          },
+          {
+            "name": "key",
+            "required": false,
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "sessionId",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
+              "type": "string"
+            }
+          },
+          {
+            "name": "slug",
+            "required": false,
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "variantIndex",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "minimum": 0,
+              "maximum": 9007199254740991,
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/vnd.apple.mpegurl": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "description": ""
+          }
+        },
+        "security": [
+          {
+            "bearer": []
+          },
+          {
+            "cookie": []
+          },
+          {
+            "api_key": []
+          }
+        ],
+        "summary": "Get HLS media playlist",
+        "tags": [
+          "Assets"
+        ],
+        "x-immich-history": [
+          {
+            "version": "v3",
+            "state": "Added"
+          },
+          {
+            "version": "v3",
+            "state": "Alpha"
+          }
+        ],
+        "x-immich-permission": "asset.view",
+        "x-immich-state": "Alpha"
+      }
+    },
+    "/assets/{id}/video/stream/{sessionId}/{variantIndex}/{filename}": {
+      "get": {
+        "description": "Streams an HLS init segment (init.mp4) or media segment (seg_N.m4s).",
+        "operationId": "getSegment",
+        "parameters": [
+          {
+            "name": "filename",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "pattern": "^(init\\.mp4|seg_\\d+\\.m4s)$",
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
+              "type": "string"
+            }
+          },
+          {
+            "name": "key",
+            "required": false,
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "sessionId",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
+              "type": "string"
+            }
+          },
+          {
+            "name": "slug",
+            "required": false,
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "variantIndex",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "minimum": 0,
+              "maximum": 9007199254740991,
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/octet-stream": {
+                "schema": {
+                  "format": "binary",
+                  "type": "string"
+                }
+              }
+            },
+            "description": ""
+          }
+        },
+        "security": [
+          {
+            "bearer": []
+          },
+          {
+            "cookie": []
+          },
+          {
+            "api_key": []
+          }
+        ],
+        "summary": "Get HLS segment or init file",
+        "tags": [
+          "Assets"
+        ],
+        "x-immich-history": [
+          {
+            "version": "v3",
+            "state": "Added"
+          },
+          {
+            "version": "v3",
+            "state": "Alpha"
+          }
+        ],
+        "x-immich-permission": "asset.view",
+        "x-immich-state": "Alpha"
+      }
+    },
     "/auth/admin-sign-up": {
       "post": {
         "description": "Create the first admin user in the system.",
@@ -18146,6 +18491,7 @@
           "LibrarySyncFilesQueueAll",
           "LibrarySyncFiles",
           "LibraryScanQueueAll",
+          "HlsSessionCleanup",
           "MemoryCleanup",
           "MemoryGenerate",
           "NotificationsCleanup",
@@ -20828,6 +21174,57 @@
         ],
         "type": "string"
       },
+      "ReleaseChannel": {
+        "description": "Release channel",
+        "enum": [
+          "stable",
+          "releaseCandidate"
+        ],
+        "type": "string"
+      },
+      "ReleaseEventV1": {
+        "properties": {
+          "checkedAt": {
+            "description": "When the server last checked for a latest version. As an ISO timestamp",
+            "type": "string"
+          },
+          "isAvailable": {
+            "description": "Whether a new version is available",
+            "type": "boolean"
+          },
+          "releaseVersion": {
+            "$ref": "#/components/schemas/ServerVersionResponseDto"
+          },
+          "serverVersion": {
+            "$ref": "#/components/schemas/ServerVersionResponseDto"
+          },
+          "type": {
+            "$ref": "#/components/schemas/ReleaseType",
+            "description": "Release type",
+            "nullable": true
+          }
+        },
+        "required": [
+          "checkedAt",
+          "isAvailable",
+          "releaseVersion",
+          "serverVersion",
+          "type"
+        ],
+        "type": "object"
+      },
+      "ReleaseType": {
+        "enum": [
+          "major",
+          "premajor",
+          "minor",
+          "preminor",
+          "patch",
+          "prepatch",
+          "prerelease"
+        ],
+        "type": "string"
+      },
       "ReverseGeocodingStateResponseDto": {
         "properties": {
           "lastImportFileName": {
@@ -21285,6 +21682,10 @@
             "description": "Whether password login is enabled",
             "type": "boolean"
           },
+          "realtimeTranscoding": {
+            "description": "Whether real-time transcoding is enabled",
+            "type": "boolean"
+          },
           "reverseGeocoding": {
             "description": "Whether reverse geocoding is enabled",
             "type": "boolean"
@@ -21317,6 +21718,7 @@
           "oauthAutoLaunch",
           "ocr",
           "passwordLogin",
+          "realtimeTranscoding",
           "reverseGeocoding",
           "search",
           "sidecar",
@@ -21497,26 +21899,40 @@
           "major": {
             "description": "Major version number",
             "maximum": 9007199254740991,
-            "minimum": -9007199254740991,
+            "minimum": 0,
             "type": "integer"
           },
           "minor": {
             "description": "Minor version number",
             "maximum": 9007199254740991,
-            "minimum": -9007199254740991,
+            "minimum": 0,
             "type": "integer"
           },
           "patch": {
             "description": "Patch version number",
             "maximum": 9007199254740991,
-            "minimum": -9007199254740991,
+            "minimum": 0,
             "type": "integer"
+          },
+          "prerelease": {
+            "description": "Pre-release version number",
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "nullable": true,
+            "type": "integer",
+            "x-immich-history": [
+              {
+                "version": "v3.0.0",
+                "state": "Added"
+              }
+            ]
           }
         },
         "required": [
           "major",
           "minor",
-          "patch"
+          "patch",
+          "prerelease"
         ],
         "type": "object"
       },
@@ -24177,6 +24593,9 @@
             "description": "Preset",
             "type": "string"
           },
+          "realtime": {
+            "$ref": "#/components/schemas/SystemConfigFFmpegRealtimeDto"
+          },
           "refs": {
             "description": "References",
             "maximum": 6,
@@ -24227,6 +24646,7 @@
           "maxBitrate",
           "preferredHwDevice",
           "preset",
+          "realtime",
           "refs",
           "targetAudioCodec",
           "targetResolution",
@@ -24239,6 +24659,18 @@
         ],
         "type": "object"
       },
+      "SystemConfigFFmpegRealtimeDto": {
+        "properties": {
+          "enabled": {
+            "description": "Enable real-time HLS transcoding (alpha)",
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "enabled"
+        ],
+        "type": "object"
+      },
       "SystemConfigFacesDto": {
         "properties": {
           "import": {
@@ -24537,12 +24969,16 @@
       },
       "SystemConfigNewVersionCheckDto": {
         "properties": {
+          "channel": {
+            "$ref": "#/components/schemas/ReleaseChannel"
+          },
           "enabled": {
             "description": "Enabled",
             "type": "boolean"
           }
         },
         "required": [
+          "channel",
           "enabled"
         ],
         "type": "object"

packages/plugin-core/manifest.json

@@ -232,7 +232,6 @@
           "albumName": {
             "type": "string",
             "title": "Album name",
-            "array": true,
             "description": "Use an album with this name if one exists, otherwise create a new one"
           }
         },

packages/sdk/src/fetch-client.ts

@@ -1993,6 +1993,8 @@ export type ServerFeaturesDto = {
     ocr: boolean;
     /** Whether password login is enabled */
     passwordLogin: boolean;
+    /** Whether real-time transcoding is enabled */
+    realtimeTranscoding: boolean;
     /** Whether reverse geocoding is enabled */
     reverseGeocoding: boolean;
     /** Whether search is enabled */
@@ -2076,6 +2078,8 @@ export type ServerVersionResponseDto = {
     minor: number;
     /** Patch version number */
     patch: number;
+    /** Pre-release version number */
+    prerelease: number | null;
 };
 export type VersionCheckStateResponseDto = {
     /** Last check timestamp */
@@ -2251,6 +2255,10 @@ export type DatabaseBackupConfig = {
 export type SystemConfigBackupsDto = {
     database: DatabaseBackupConfig;
 };
+export type SystemConfigFFmpegRealtimeDto = {
+    /** Enable real-time HLS transcoding (alpha) */
+    enabled: boolean;
+};
 export type SystemConfigFFmpegDto = {
     accel: TranscodeHWAccel;
     /** Accelerated decode */
@@ -2274,6 +2282,7 @@ export type SystemConfigFFmpegDto = {
     preferredHwDevice: string;
     /** Preset */
     preset: string;
+    realtime: SystemConfigFFmpegRealtimeDto;
     /** References */
     refs: number;
     targetAudioCodec: AudioCodec;
@@ -2423,6 +2432,7 @@ export type SystemConfigMetadataDto = {
     faces: SystemConfigFacesDto;
 };
 export type SystemConfigNewVersionCheckDto = {
+    channel: ReleaseChannel;
     /** Enabled */
     enabled: boolean;
 };
@@ -2768,6 +2778,16 @@ export type WorkflowShareResponseDto = {
     trigger: WorkflowTrigger;
 };
 export type LicenseResponseDto = UserLicense;
+export type ReleaseEventV1 = {
+    /** When the server last checked for a latest version. As an ISO timestamp */
+    checkedAt: string;
+    /** Whether a new version is available */
+    isAvailable: boolean;
+    releaseVersion: ServerVersionResponseDto;
+    serverVersion: ServerVersionResponseDto;
+    /** Release type */
+    "type": ReleaseType;
+};
 export type SyncAckV1 = {};
 export type SyncAlbumDeleteV1 = {
     /** Album ID */
@@ -4212,6 +4232,82 @@ export function playAssetVideo({ id, key, slug }: {
         ...opts
     }));
 }
+/**
+ * Get HLS main playlist
+ */
+export function getMainPlaylist({ id, key, slug }: {
+    id: string;
+    key?: string;
+    slug?: string;
+}, opts?: Oazapfts.RequestOpts) {
+    return oazapfts.ok(oazapfts.fetchBlob<{
+        status: 200;
+        data: string;
+    }>(`/assets/${encodeURIComponent(id)}/video/stream/main.m3u8${QS.query(QS.explode({
+        key,
+        slug
+    }))}`, {
+        ...opts
+    }));
+}
+/**
+ * End HLS streaming session
+ */
+export function endSession({ id, key, sessionId, slug }: {
+    id: string;
+    key?: string;
+    sessionId: string;
+    slug?: string;
+}, opts?: Oazapfts.RequestOpts) {
+    return oazapfts.ok(oazapfts.fetchText(`/assets/${encodeURIComponent(id)}/video/stream/${encodeURIComponent(sessionId)}${QS.query(QS.explode({
+        key,
+        slug
+    }))}`, {
+        ...opts,
+        method: "DELETE"
+    }));
+}
+/**
+ * Get HLS media playlist
+ */
+export function getMediaPlaylist({ id, key, sessionId, slug, variantIndex }: {
+    id: string;
+    key?: string;
+    sessionId: string;
+    slug?: string;
+    variantIndex: number;
+}, opts?: Oazapfts.RequestOpts) {
+    return oazapfts.ok(oazapfts.fetchBlob<{
+        status: 200;
+        data: string;
+    }>(`/assets/${encodeURIComponent(id)}/video/stream/${encodeURIComponent(sessionId)}/${encodeURIComponent(variantIndex)}/playlist.m3u8${QS.query(QS.explode({
+        key,
+        slug
+    }))}`, {
+        ...opts
+    }));
+}
+/**
+ * Get HLS segment or init file
+ */
+export function getSegment({ filename, id, key, sessionId, slug, variantIndex }: {
+    filename: string;
+    id: string;
+    key?: string;
+    sessionId: string;
+    slug?: string;
+    variantIndex: number;
+}, opts?: Oazapfts.RequestOpts) {
+    return oazapfts.ok(oazapfts.fetchBlob<{
+        status: 200;
+        data: Blob;
+    }>(`/assets/${encodeURIComponent(id)}/video/stream/${encodeURIComponent(sessionId)}/${encodeURIComponent(variantIndex)}/${encodeURIComponent(filename)}${QS.query(QS.explode({
+        key,
+        slug
+    }))}`, {
+        ...opts
+    }));
+}
 /**
  * Register admin
  */
@@ -7122,6 +7218,7 @@ export enum JobName {
     LibrarySyncFilesQueueAll = "LibrarySyncFilesQueueAll",
     LibrarySyncFiles = "LibrarySyncFiles",
     LibraryScanQueueAll = "LibraryScanQueueAll",
+    HlsSessionCleanup = "HlsSessionCleanup",
     MemoryCleanup = "MemoryCleanup",
     MemoryGenerate = "MemoryGenerate",
     NotificationsCleanup = "NotificationsCleanup",
@@ -7312,6 +7409,10 @@ export enum LogLevel {
     Error = "error",
     Fatal = "fatal"
 }
+export enum ReleaseChannel {
+    Stable = "stable",
+    ReleaseCandidate = "releaseCandidate"
+}
 export enum OAuthTokenEndpointAuthMethod {
     ClientSecretPost = "client_secret_post",
     ClientSecretBasic = "client_secret_basic"
@@ -7320,6 +7421,15 @@ export enum AssetOrderBy {
     TakenAt = "takenAt",
     CreatedAt = "createdAt"
 }
+export enum ReleaseType {
+    Major = "major",
+    Premajor = "premajor",
+    Minor = "minor",
+    Preminor = "preminor",
+    Patch = "patch",
+    Prepatch = "prepatch",
+    Prerelease = "prerelease"
+}
 export enum UserMetadataKey {
     Preferences = "preferences",
     License = "license",

pnpm-lock.yaml

@@ -577,8 +577,8 @@ importers:
         specifier: ^1.6.3
         version: 1.6.4
       semver:
-        specifier: ^7.6.2
-        version: 7.8.0
+        specifier: ^7.8.1
+        version: 7.8.1
       sharp:
         specifier: ^0.34.5
         version: 0.34.5
@@ -820,6 +820,12 @@ importers:
       happy-dom:
         specifier: ^20.0.0
         version: 20.9.0
+      hls-video-element:
+        specifier: ^1.5.11
+        version: 1.5.11
+      hls.js:
+        specifier: ^1.6.16
+        version: 1.6.16
       intl-messageformat:
         specifier: ^11.0.0
         version: 11.2.6
@@ -6947,6 +6953,9 @@ packages:
   csstype@3.2.3:
     resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
 
+  custom-media-element@1.4.6:
+    resolution: {integrity: sha512-/HRYqJOa1ob5ik4q7FIJVYxTJCFs/FL3+cQPAJjUf2uiqrDEzbTgB315gQ2rG8oK3w094W9m5tcB8S5Qah+caA==}
+
   cytoscape-cose-bilkent@4.1.0:
     resolution: {integrity: sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==}
     peerDependencies:
@@ -8271,6 +8280,12 @@ packages:
   history@4.10.1:
     resolution: {integrity: sha512-36nwAD620w12kuzPAsyINPWJqlNbij+hpK1k9XRloDtym8mxzGYl2c17LnV6IAGB2Dmg4tEa7G7DlawS0+qjew==}
 
+  hls-video-element@1.5.11:
+    resolution: {integrity: sha512-tJJ65/52CDxj8XFyIve6zT9nVVdUIc6mqvKR25X0ycPKHk07rpjp4xxVteeCefDUBSf/tFLhlICFmn3KWj37xA==}
+
+  hls.js@1.6.16:
+    resolution: {integrity: sha512-VSIRpLfRwlAAdGL4wiTucx2ScRipo0ed1FBatWkyt832jC4CReKstga6yIhYVwGu9LOBjuX9wzmRMeQdBJtzEA==}
+
   hogan.js@3.0.2:
     resolution: {integrity: sha512-RqGs4wavGYJWE07t35JQccByczmNUXQT0E12ZYV1VKYu5UiAU9lsos/yBAcf840+zrUQQxgVduCR5/B8nNtibg==}
     hasBin: true
@@ -9275,6 +9290,9 @@ packages:
   media-chrome@4.19.0:
     resolution: {integrity: sha512-HWhDTwts+BSbdPkkB1VsJXp5kvL0IxY7xFT5tBwliM2+89kTPVTnHnev+9it2f9PweANjT/C8/C/S0PW9oyZbA==}
 
+  media-tracks@0.3.5:
+    resolution: {integrity: sha512-l54rkKXlLBt3ob3zOLWHcnjvwUmX5bNEZ70igyapOZZC9imzqBmq1oz8p2roiV04KhjblFIi2hetLPF1oYVLRA==}
+
   media-typer@0.3.0:
     resolution: {integrity: sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==}
     engines: {node: '>= 0.6'}
@@ -11250,6 +11268,11 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
+  semver@7.8.1:
+    resolution: {integrity: sha512-rkVq3IXh+4FDGch+KwzX3aV9W3kO54GyEgpvBzSyctDA6Xtd7RJQV1xmXbeQp5v7+VzLOfVqiutSE6GICgPFvg==}
+    engines: {node: '>=10'}
+    hasBin: true
+
   send@0.19.2:
     resolution: {integrity: sha512-VMbMxbDeehAxpOtWJXlcUS5E8iXh6QmN+BkRX1GARS3wRaXEEgzCcB10gTQazO42tpNIya8xIyNx8fll1OFPrg==}
     engines: {node: '>= 0.8.0'}
@@ -16307,7 +16330,7 @@ snapshots:
       nopt: 5.0.0
       npmlog: 5.0.1
       rimraf: 3.0.2
-      semver: 7.8.0
+      semver: 7.8.1
       tar: 6.2.1
     transitivePeerDependencies:
       - encoding
@@ -17765,7 +17788,7 @@ snapshots:
   '@testing-library/dom@10.4.1':
     dependencies:
       '@babel/code-frame': 7.29.0
-      '@babel/runtime': 7.29.2
+      '@babel/runtime': 7.29.7
       '@types/aria-query': 5.0.4
       aria-query: 5.3.0
       dom-accessibility-api: 0.5.16
@@ -18469,7 +18492,7 @@ snapshots:
       '@typescript-eslint/visitor-keys': 8.59.4
       debug: 4.4.3
       minimatch: 10.2.5
-      semver: 7.8.0
+      semver: 7.8.1
       tinyglobby: 0.2.16
       ts-api-utils: 2.5.0(typescript@6.0.3)
       typescript: 6.0.3
@@ -19569,7 +19592,7 @@ snapshots:
       dot-prop: 10.1.0
       env-paths: 3.0.0
       json-schema-typed: 8.0.2
-      semver: 7.8.0
+      semver: 7.8.1
       uint8array-extras: 1.5.0
 
   config-chain@1.1.13:
@@ -19741,7 +19764,7 @@ snapshots:
       postcss-modules-scope: 3.2.1(postcss@8.5.15)
       postcss-modules-values: 4.0.0(postcss@8.5.15)
       postcss-value-parser: 4.2.0
-      semver: 7.8.0
+      semver: 7.8.1
     optionalDependencies:
       webpack: 5.107.0(postcss@8.5.15)
 
@@ -19864,6 +19887,8 @@ snapshots:
 
   csstype@3.2.3: {}
 
+  custom-media-element@1.4.6: {}
+
   cytoscape-cose-bilkent@4.1.0(cytoscape@3.33.4):
     dependencies:
       cose-base: 1.0.3
@@ -20609,7 +20634,7 @@ snapshots:
       find-up: 5.0.0
       globals: 15.15.0
       lodash.memoize: 4.1.2
-      semver: 7.8.0
+      semver: 7.8.1
 
   eslint-plugin-prettier@5.5.5(@types/eslint@9.6.1)(eslint-config-prettier@10.1.8(eslint@10.4.0(jiti@2.7.0)))(eslint@10.4.0(jiti@2.7.0))(prettier@3.8.3):
     dependencies:
@@ -20632,7 +20657,7 @@ snapshots:
       postcss: 8.5.15
       postcss-load-config: 3.1.4(postcss@8.5.15)
       postcss-safe-parser: 7.0.1(postcss@8.5.15)
-      semver: 7.8.0
+      semver: 7.8.1
       svelte-eslint-parser: 1.6.1(svelte@5.55.8(@typescript-eslint/types@8.59.4))
     optionalDependencies:
       svelte: 5.55.8(@typescript-eslint/types@8.59.4)
@@ -21110,7 +21135,7 @@ snapshots:
       minimatch: 3.1.5
       node-abort-controller: 3.1.1
       schema-utils: 3.3.0
-      semver: 7.8.0
+      semver: 7.8.1
       tapable: 2.3.3
       typescript: 5.9.3
       webpack: 5.106.0(@swc/core@1.15.33(@swc/helpers@0.5.22))(esbuild@0.28.0)(lightningcss@1.32.0)
@@ -21546,13 +21571,21 @@ snapshots:
 
   history@4.10.1:
     dependencies:
-      '@babel/runtime': 7.29.2
+      '@babel/runtime': 7.29.7
       loose-envify: 1.4.0
       resolve-pathname: 3.0.0
       tiny-invariant: 1.3.3
       tiny-warning: 1.0.3
       value-equal: 1.0.1
 
+  hls-video-element@1.5.11:
+    dependencies:
+      custom-media-element: 1.4.6
+      hls.js: 1.6.16
+      media-tracks: 0.3.5
+
+  hls.js@1.6.16: {}
+
   hogan.js@3.0.2:
     dependencies:
       mkdirp: 0.3.0
@@ -22134,7 +22167,7 @@ snapshots:
       lodash.isstring: 4.0.1
       lodash.once: 4.1.1
       ms: 2.1.3
-      semver: 7.8.0
+      semver: 7.8.1
 
   just-compare@2.3.0: {}
 
@@ -22420,7 +22453,7 @@ snapshots:
 
   make-dir@4.0.0:
     dependencies:
-      semver: 7.8.0
+      semver: 7.8.1
 
   maplibre-gl@5.24.0:
     dependencies:
@@ -22656,6 +22689,8 @@ snapshots:
     transitivePeerDependencies:
       - react
 
+  media-tracks@0.3.5: {}
+
   media-typer@0.3.0: {}
 
   media-typer@1.1.0: {}
@@ -23255,7 +23290,7 @@ snapshots:
 
   node-abi@3.92.0:
     dependencies:
-      semver: 7.8.0
+      semver: 7.8.1
     optional: true
 
   node-abort-controller@3.1.1: {}
@@ -23296,7 +23331,7 @@ snapshots:
       graceful-fs: 4.2.11
       nopt: 9.0.0
       proc-log: 6.1.0
-      semver: 7.8.0
+      semver: 7.8.1
       tar: 7.5.15
       tinyglobby: 0.2.16
       undici: 6.25.0
@@ -23534,7 +23569,7 @@ snapshots:
       got: 12.6.1
       registry-auth-token: 5.1.1
       registry-url: 6.0.1
-      semver: 7.8.0
+      semver: 7.8.1
 
   package-manager-detector@1.6.0: {}
 
@@ -23922,7 +23957,7 @@ snapshots:
       cosmiconfig: 8.3.6(typescript@6.0.3)
       jiti: 1.21.7
       postcss: 8.5.15
-      semver: 7.8.0
+      semver: 7.8.1
       webpack: 5.107.0(postcss@8.5.15)
     transitivePeerDependencies:
       - typescript
@@ -24977,12 +25012,14 @@ snapshots:
 
   semver-diff@4.0.0:
     dependencies:
-      semver: 7.8.0
+      semver: 7.8.1
 
   semver@6.3.1: {}
 
   semver@7.8.0: {}
 
+  semver@7.8.1: {}
+
   send@0.19.2:
     dependencies:
       debug: 2.6.9
@@ -25517,7 +25554,7 @@ snapshots:
       postcss: 8.5.15
       postcss-scss: 4.0.9(postcss@8.5.15)
       postcss-selector-parser: 7.1.1
-      semver: 7.8.0
+      semver: 7.8.1
     optionalDependencies:
       svelte: 5.55.8(@typescript-eslint/types@8.59.4)
 
@@ -26225,7 +26262,7 @@ snapshots:
       is-yarn-global: 0.4.1
       latest-version: 7.0.0
       pupa: 3.3.0
-      semver: 7.8.0
+      semver: 7.8.1
       semver-diff: 4.0.0
       xdg-basedir: 5.1.0
 

server/Dockerfile

@@ -56,7 +56,7 @@ FROM builder AS plugins
 
 ARG TARGETPLATFORM
 
-COPY --from=ghcr.io/jdx/mise:2026.5.11@sha256:2ba959e4827f845fe0c4cfb4814089e790dc513040ef74f9e14925f446412a51 /usr/local/bin/mise /usr/local/bin/mise
+COPY --from=ghcr.io/jdx/mise:2026.5.18@sha256:5bb3311994fa78cef307ca3077cdb18f9551da0886371fc26ea91ab56220ffc5 /usr/local/bin/mise /usr/local/bin/mise
 
 WORKDIR /app
 COPY ./mise.toml ./mise.toml

server/Dockerfile.dev

@@ -2,7 +2,7 @@
 FROM ghcr.io/immich-app/base-server-dev:202605051129@sha256:d07d8fcdb7e9f3ac22a811e87761ebf341ed0bb91956b89097540c2ed3fb9ca3 AS dev
 
 
-COPY --from=ghcr.io/jdx/mise:2026.5.11@sha256:2ba959e4827f845fe0c4cfb4814089e790dc513040ef74f9e14925f446412a51 /usr/local/bin/mise /usr/local/bin/mise
+COPY --from=ghcr.io/jdx/mise:2026.5.18@sha256:5bb3311994fa78cef307ca3077cdb18f9551da0886371fc26ea91ab56220ffc5 /usr/local/bin/mise /usr/local/bin/mise
 
 RUN echo "devdir=/buildcache/node-gyp" >> /usr/local/etc/npmrc && \
   echo "store-dir=/buildcache/pnpm-store" >> /usr/local/etc/npmrc && \

server/package.json

@@ -106,7 +106,7 @@
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.1",
     "sanitize-filename": "^1.6.3",
-    "semver": "^7.6.2",
+    "semver": "^7.8.1",
     "sharp": "^0.34.5",
     "sirv": "^3.0.0",
     "socket.io": "^4.8.1",

server/src/config.ts

@@ -1,4 +1,5 @@
 import { CronExpression } from '@nestjs/schedule';
+import { ReleaseChannel } from 'src/dtos/system-config.dto';
 import {
   AudioCodec,
   Colorspace,
@@ -45,6 +46,9 @@ export type SystemConfig = {
     accel: TranscodeHardwareAcceleration;
     accelDecode: boolean;
     tonemap: ToneMapping;
+    realtime: {
+      enabled: boolean;
+    };
   };
   job: Record<ConcurrentQueueName, { concurrency: number }>;
   logging: {
@@ -135,6 +139,7 @@ export type SystemConfig = {
   };
   newVersionCheck: {
     enabled: boolean;
+    channel: ReleaseChannel;
   };
   nightlyTasks: {
     startTime: string;
@@ -224,6 +229,9 @@ export const defaults = Object.freeze<SystemConfig>({
     tonemap: ToneMapping.Hable,
     accel: TranscodeHardwareAcceleration.Disabled,
     accelDecode: true,
+    realtime: {
+      enabled: false,
+    },
   },
   job: {
     [QueueName.BackgroundTask]: { concurrency: 5 },
@@ -344,6 +352,7 @@ export const defaults = Object.freeze<SystemConfig>({
   },
   newVersionCheck: {
     enabled: true,
+    channel: ReleaseChannel.Stable,
   },
   nightlyTasks: {
     startTime: '00:00',

server/src/constants.ts

@@ -1,7 +1,15 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { SemVer } from 'semver';
-import { ApiTag, AudioCodec, DatabaseExtension, ExifOrientation, VectorIndex } from 'src/enum';
+import {
+  ApiTag,
+  AudioCodec,
+  DatabaseExtension,
+  ExifOrientation,
+  TranscodeHardwareAcceleration,
+  VectorIndex,
+  VideoCodec,
+} from 'src/enum';
 
 export const IMMICH_SERVER_START = 'Immich Server is listening';
 
@@ -202,3 +210,32 @@ export const AUDIO_ENCODER: Record<AudioCodec, string> = {
   [AudioCodec.Opus]: 'libopus',
   [AudioCodec.PcmS16le]: 'pcm_s16le',
 };
+
+export const SUPPORTED_HWA_CODECS: Record<TranscodeHardwareAcceleration, VideoCodec[]> = {
+  [TranscodeHardwareAcceleration.Nvenc]: [VideoCodec.H264, VideoCodec.Hevc, VideoCodec.Av1],
+  [TranscodeHardwareAcceleration.Qsv]: [VideoCodec.H264, VideoCodec.Hevc, VideoCodec.Vp9, VideoCodec.Av1],
+  [TranscodeHardwareAcceleration.Vaapi]: [VideoCodec.H264, VideoCodec.Hevc, VideoCodec.Vp9, VideoCodec.Av1],
+  [TranscodeHardwareAcceleration.Rkmpp]: [VideoCodec.H264, VideoCodec.Hevc],
+  [TranscodeHardwareAcceleration.Disabled]: [VideoCodec.H264, VideoCodec.Hevc, VideoCodec.Vp9, VideoCodec.Av1],
+};
+
+export const HLS_BACKPRESSURE_PAUSE_SEGMENTS = 30;
+export const HLS_BACKPRESSURE_RESUME_SEGMENTS = 15;
+export const HLS_CLEANUP_INTERVAL_MS = 60 * 1000;
+export const HLS_INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000;
+export const HLS_LEASE_DURATION_MS = 30 * 60 * 1000;
+export const HLS_PLAYLIST_CONTENT_TYPE = 'application/vnd.apple.mpegurl';
+export const HLS_SEGMENT_DURATION = 2;
+export const HLS_SEGMENT_FILENAME_REGEX = /^seg_(\d+)\.m4s$/;
+export const HLS_VARIANTS = [
+  { resolution: 480, codec: VideoCodec.Av1, bitrate: 1_000_000, codecString: 'av01.0.04M.08' },
+  { resolution: 480, codec: VideoCodec.Hevc, bitrate: 1_200_000, codecString: 'hvc1.1.6.L90.B0' },
+  { resolution: 480, codec: VideoCodec.H264, bitrate: 2_500_000, codecString: 'avc1.64001e' },
+  { resolution: 720, codec: VideoCodec.Av1, bitrate: 2_000_000, codecString: 'av01.0.08M.08' },
+  { resolution: 720, codec: VideoCodec.Hevc, bitrate: 2_500_000, codecString: 'hvc1.1.6.L93.B0' },
+  { resolution: 720, codec: VideoCodec.H264, bitrate: 5_000_000, codecString: 'avc1.64001f' },
+  { resolution: 1080, codec: VideoCodec.Av1, bitrate: 4_000_000, codecString: 'av01.0.09M.08' },
+  { resolution: 1080, codec: VideoCodec.Hevc, bitrate: 4_500_000, codecString: 'hvc1.1.6.L120.B0' },
+  { resolution: 1080, codec: VideoCodec.H264, bitrate: 8_000_000, codecString: 'avc1.640028' },
+];
+export const HLS_VERSION = 7;

server/src/controllers/index.ts

@@ -35,6 +35,7 @@ import { TimelineController } from 'src/controllers/timeline.controller';
 import { TrashController } from 'src/controllers/trash.controller';
 import { UserAdminController } from 'src/controllers/user-admin.controller';
 import { UserController } from 'src/controllers/user.controller';
+import { VideoStreamController } from 'src/controllers/video-stream.controller';
 import { ViewController } from 'src/controllers/view.controller';
 import { WorkflowController } from 'src/controllers/workflow.controller';
 
@@ -76,6 +77,7 @@ export const controllers = [
   TrashController,
   UserAdminController,
   UserController,
+  VideoStreamController,
   ViewController,
   WorkflowController,
 ];

server/src/controllers/video-stream.controller.ts

@@ -0,0 +1,79 @@
+import { Controller, Delete, Get, Header, HttpCode, HttpStatus, Next, Param, Res } from '@nestjs/common';
+import { ApiProduces, ApiTags } from '@nestjs/swagger';
+import { NextFunction, Response } from 'express';
+import { HLS_PLAYLIST_CONTENT_TYPE } from 'src/constants';
+import { Endpoint, HistoryBuilder } from 'src/decorators';
+import { AuthDto } from 'src/dtos/auth.dto';
+import { HlsSegmentParamDto, HlsSessionParamDto, HlsVariantParamDto } from 'src/dtos/streaming.dto';
+import { ApiTag, Permission, RouteKey } from 'src/enum';
+import { Auth, Authenticated, FileResponse } from 'src/middleware/auth.guard';
+import { LoggingRepository } from 'src/repositories/logging.repository';
+import { HlsService } from 'src/services/hls.service';
+import { sendFile } from 'src/utils/file';
+import { UUIDParamDto } from 'src/validation';
+
+@ApiTags(ApiTag.Assets)
+@Controller(RouteKey.Asset)
+export class VideoStreamController {
+  constructor(
+    private logger: LoggingRepository,
+    private service: HlsService,
+  ) {}
+
+  @Get(':id/video/stream/main.m3u8')
+  @Authenticated({ permission: Permission.AssetView, sharedLink: true })
+  @Header('Cache-Control', 'no-cache')
+  @Header('Content-Type', HLS_PLAYLIST_CONTENT_TYPE)
+  @ApiProduces(HLS_PLAYLIST_CONTENT_TYPE)
+  @Endpoint({
+    summary: 'Get HLS main playlist',
+    description: 'Returns an HLS main playlist with all available variants for the asset.',
+    history: new HistoryBuilder().added('v3').alpha('v3'),
+  })
+  getMainPlaylist(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto) {
+    return this.service.getMainPlaylist(auth, id);
+  }
+
+  @Get(':id/video/stream/:sessionId/:variantIndex/playlist.m3u8')
+  @Authenticated({ permission: Permission.AssetView, sharedLink: true })
+  @Header('Cache-Control', 'no-cache')
+  @Header('Content-Type', HLS_PLAYLIST_CONTENT_TYPE)
+  @ApiProduces(HLS_PLAYLIST_CONTENT_TYPE)
+  @Endpoint({
+    summary: 'Get HLS media playlist',
+    description: 'Returns an HLS media playlist for one variant of the streaming session.',
+    history: new HistoryBuilder().added('v3').alpha('v3'),
+  })
+  getMediaPlaylist(@Auth() auth: AuthDto, @Param() { id, sessionId }: HlsVariantParamDto) {
+    return this.service.getMediaPlaylist(auth, id, sessionId);
+  }
+
+  @Get(':id/video/stream/:sessionId/:variantIndex/:filename')
+  @FileResponse()
+  @Authenticated({ permission: Permission.AssetView, sharedLink: true })
+  @Endpoint({
+    summary: 'Get HLS segment or init file',
+    description: 'Streams an HLS init segment (init.mp4) or media segment (seg_N.m4s).',
+    history: new HistoryBuilder().added('v3').alpha('v3'),
+  })
+  async getSegment(
+    @Auth() auth: AuthDto,
+    @Param() { id, sessionId, variantIndex, filename }: HlsSegmentParamDto,
+    @Res() res: Response,
+    @Next() next: NextFunction,
+  ) {
+    await sendFile(res, next, () => this.service.getSegment(auth, id, sessionId, variantIndex, filename), this.logger);
+  }
+
+  @Delete(':id/video/stream/:sessionId')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @Authenticated({ permission: Permission.AssetView, sharedLink: true })
+  @Endpoint({
+    summary: 'End HLS streaming session',
+    description: 'Releases server resources for the streaming session.',
+    history: new HistoryBuilder().added('v3').alpha('v3'),
+  })
+  async endSession(@Auth() auth: AuthDto, @Param() { id, sessionId }: HlsSessionParamDto) {
+    await this.service.endSession(auth, id, sessionId);
+  }
+}

server/src/cores/storage.core.ts

@@ -35,6 +35,10 @@ export interface MoveRequest {
 
 export type ThumbnailPathEntity = { id: string; ownerId: string };
 
+export type HlsSessionFolder = { ownerId: string; sessionId: string };
+
+export type HlsVariantFolder = { ownerId: string; sessionId: string; variantIndex: number };
+
 export type ImagePathOptions = { fileType: AssetFileType; format: ImageFormat | RawExtractedFormat; isEdited: boolean };
 
 let instance: StorageCore | null;
@@ -125,6 +129,14 @@ export class StorageCore {
     return StorageCore.getNestedPath(StorageFolder.EncodedVideo, asset.ownerId, `${asset.id}.mp4`);
   }
 
+  static getHlsSessionFolder({ ownerId, sessionId }: HlsSessionFolder) {
+    return StorageCore.getNestedPath(StorageFolder.EncodedVideo, ownerId, sessionId);
+  }
+
+  static getHlsVariantFolder({ ownerId, sessionId, variantIndex }: HlsVariantFolder) {
+    return join(StorageCore.getHlsSessionFolder({ ownerId, sessionId }), variantIndex.toString());
+  }
+
   static getAndroidMotionPath(asset: ThumbnailPathEntity, uuid: string) {
     return StorageCore.getNestedPath(StorageFolder.EncodedVideo, asset.ownerId, `${uuid}-MP.mp4`);
   }

server/src/decorators.ts

@@ -265,3 +265,13 @@ export class HistoryBuilder {
     return this;
   }
 }
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export const extraModels: Function[] = [];
+
+export const ExtraModel = (): ClassDecorator => {
+  // eslint-disable-next-line unicorn/consistent-function-scoping, @typescript-eslint/no-unsafe-function-type
+  return (object: Function) => {
+    extraModels.push(object);
+  };
+};

server/src/dtos/server.dto.ts

@@ -1,5 +1,6 @@
 import { createZodDto } from 'nestjs-zod';
 import type { SemVer } from 'semver';
+import { ExtraModel, HistoryBuilder } from 'src/decorators';
 import { isoDatetimeToDate } from 'src/validation';
 import z from 'zod';
 
@@ -58,9 +59,15 @@ const ServerStorageResponseSchema = z
 
 const ServerVersionResponseSchema = z
   .object({
-    major: z.int().describe('Major version number'),
-    minor: z.int().describe('Minor version number'),
-    patch: z.int().describe('Patch version number'),
+    major: z.int().min(0).describe('Major version number'),
+    minor: z.int().min(0).describe('Minor version number'),
+    patch: z.int().min(0).describe('Patch version number'),
+    prerelease: z
+      .int()
+      .min(0)
+      .nullable()
+      .meta(HistoryBuilder.v3().getExtensions())
+      .describe('Pre-release version number'),
   })
   .meta({ id: 'ServerVersionResponseDto' });
 
@@ -137,9 +144,30 @@ const ServerFeaturesSchema = z
     search: z.boolean().describe('Whether search is enabled'),
     email: z.boolean().describe('Whether email notifications are enabled'),
     ocr: z.boolean().describe('Whether OCR is enabled'),
+    realtimeTranscoding: z.boolean().describe('Whether real-time transcoding is enabled'),
   })
   .meta({ id: 'ServerFeaturesDto' });
 
+export enum ReleaseType {
+  Major = 'major',
+  Premajor = 'premajor',
+  Minor = 'minor',
+  Preminor = 'preminor',
+  Patch = 'patch',
+  Prepatch = 'prepatch',
+  Prerelease = 'prerelease',
+}
+
+const ReleaseTypeSchema = z.enum(ReleaseType).meta({ id: 'ReleaseType' }).describe('Release type');
+
+const ReleaseEventV1Schema = z.object({
+  isAvailable: z.boolean().describe('Whether a new version is available'),
+  checkedAt: z.string().describe('When the server last checked for a latest version. As an ISO timestamp'),
+  serverVersion: ServerVersionResponseSchema,
+  releaseVersion: ServerVersionResponseSchema,
+  type: ReleaseTypeSchema.nullable(),
+});
+
 export class ServerPingResponse extends createZodDto(ServerPingResponseSchema) {}
 export class ServerAboutResponseDto extends createZodDto(ServerAboutResponseSchema) {}
 export class ServerApkLinksDto extends createZodDto(ServerApkLinksSchema) {}
@@ -147,7 +175,12 @@ export class ServerStorageResponseDto extends createZodDto(ServerStorageResponse
 
 export class ServerVersionResponseDto extends createZodDto(ServerVersionResponseSchema) {
   static fromSemVer(value: SemVer): z.infer<typeof ServerVersionResponseSchema> {
-    return { major: value.major, minor: value.minor, patch: value.patch };
+    return {
+      major: value.major,
+      minor: value.minor,
+      patch: value.patch,
+      prerelease: (value.prerelease[1] as number) ?? null,
+    };
   }
 }
 
@@ -158,10 +191,5 @@ export class ServerMediaTypesResponseDto extends createZodDto(ServerMediaTypesRe
 export class ServerConfigDto extends createZodDto(ServerConfigSchema) {}
 export class ServerFeaturesDto extends createZodDto(ServerFeaturesSchema) {}
 
-export interface ReleaseNotification {
-  isAvailable: boolean;
-  /** ISO8601 */
-  checkedAt: string;
-  serverVersion: ServerVersionResponseDto;
-  releaseVersion: ServerVersionResponseDto;
-}
+@ExtraModel()
+export class ReleaseEventV1 extends createZodDto(ReleaseEventV1Schema) {}

server/src/dtos/streaming.dto.ts

@@ -0,0 +1,26 @@
+import { createZodDto } from 'nestjs-zod';
+import z from 'zod';
+
+const HlsSessionParamSchema = z.object({
+  id: z.uuidv4(),
+  sessionId: z.uuidv4(),
+});
+
+export class HlsSessionParamDto extends createZodDto(HlsSessionParamSchema) {}
+
+const HlsVariantParamSchema = z.object({
+  id: z.uuidv4(),
+  sessionId: z.uuidv4(),
+  variantIndex: z.coerce.number().int().min(0),
+});
+
+export class HlsVariantParamDto extends createZodDto(HlsVariantParamSchema) {}
+
+const HlsSegmentParamSchema = z.object({
+  id: z.uuidv4(),
+  sessionId: z.uuidv4(),
+  variantIndex: z.coerce.number().int().min(0),
+  filename: z.string().regex(/^(init\.mp4|seg_\d+\.m4s)$/, { error: 'Invalid HLS segment filename' }),
+});
+
+export class HlsSegmentParamDto extends createZodDto(HlsSegmentParamSchema) {}

server/src/dtos/sync.dto.ts

@@ -1,5 +1,5 @@
-/* eslint-disable @typescript-eslint/no-unsafe-function-type */
 import { createZodDto } from 'nestjs-zod';
+import { ExtraModel } from 'src/decorators';
 import { AssetEditActionSchema } from 'src/dtos/editing.dto';
 import {
   AlbumUserRole,
@@ -17,15 +17,6 @@ import {
 import { isoDatetimeToDate } from 'src/validation';
 import z from 'zod';
 
-export const extraSyncModels: Function[] = [];
-
-const ExtraModel = (): ClassDecorator => {
-  // eslint-disable-next-line unicorn/consistent-function-scoping
-  return (object: Function) => {
-    extraSyncModels.push(object);
-  };
-};
-
 const SyncUserV1Schema = z
   .object({
     id: z.string().describe('User ID'),

server/src/dtos/system-config.dto.ts

@@ -79,6 +79,11 @@ const SystemConfigFFmpegSchema = z
     accel: TranscodeHardwareAccelerationSchema,
     accelDecode: configBool.describe('Accelerated decode'),
     tonemap: ToneMappingSchema,
+    realtime: z
+      .object({
+        enabled: configBool.describe('Enable real-time HLS transcoding (alpha)'),
+      })
+      .meta({ id: 'SystemConfigFFmpegRealtimeDto' }),
   })
   .meta({ id: 'SystemConfigFFmpegDto' });
 
@@ -151,8 +156,15 @@ const SystemConfigMapSchema = z
   })
   .meta({ id: 'SystemConfigMapDto' });
 
+export enum ReleaseChannel {
+  Stable = 'stable',
+  ReleaseCandidate = 'releaseCandidate',
+}
+
+const ReleaseChannelSchema = z.enum(ReleaseChannel).describe('Release channel').meta({ id: 'ReleaseChannel' });
+
 const SystemConfigNewVersionCheckSchema = z
-  .object({ enabled: configBool.describe('Enabled') })
+  .object({ enabled: configBool.describe('Enabled'), channel: ReleaseChannelSchema })
   .meta({ id: 'SystemConfigNewVersionCheckDto' });
 
 const SystemConfigNightlyTasksSchema = z

server/src/enum.ts

@@ -453,11 +453,7 @@ export enum VideoCodec {
 
 export const VideoCodecSchema = z.enum(VideoCodec).describe('Target video codec').meta({ id: 'VideoCodec' });
 
-export enum VideoSegmentCodec {
-  Av1 = 'av1',
-  Hevc = 'hevc',
-  H264 = 'h264',
-}
+export type VideoSegmentCodec = VideoCodec.Av1 | VideoCodec.Hevc | VideoCodec.H264;
 
 export enum AudioCodec {
   Mp3 = 'mp3',
@@ -827,6 +823,8 @@ export enum JobName {
   LibrarySyncFiles = 'LibrarySyncFiles',
   LibraryScanQueueAll = 'LibraryScanQueueAll',
 
+  HlsSessionCleanup = 'HlsSessionCleanup',
+
   MemoryCleanup = 'MemoryCleanup',
   MemoryGenerate = 'MemoryGenerate',
 
@@ -920,6 +918,7 @@ export enum DatabaseLock {
   MaintenanceOperation = 621,
   MemoryCreation = 777,
   VersionCheck = 800,
+  HlsSessionCleanup = 850,
 }
 
 export enum MaintenanceAction {

server/src/queries/video.stream.repository.sql

@@ -7,6 +7,7 @@ from
   "video_stream_session"
 where
   "id" = $1
+  and "expiresAt" > $2
 
 -- VideoStreamRepository.getVariant
 select
@@ -27,11 +28,13 @@ where
 
 -- VideoStreamRepository.getExpiredSessions
 select
-  "id"
+  "video_stream_session"."id",
+  "asset"."ownerId"
 from
   "video_stream_session"
+  inner join "asset" on "asset"."id" = "video_stream_session"."assetId"
 where
-  "expiresAt" <= $1
+  "video_stream_session"."expiresAt" <= $1
 
 -- VideoStreamRepository.extendSession
 update "video_stream_session"
@@ -44,3 +47,253 @@ where
 delete from "video_stream_session"
 where
   "id" = $1
+
+-- VideoStreamRepository.getForMainPlaylist
+select
+  (
+    select
+      to_json(obj)
+    from
+      (
+        select
+          "asset_video"."index",
+          "asset_video"."codecName",
+          "asset_video"."profile",
+          "asset_video"."level",
+          "asset_video"."bitrate",
+          "asset_exif"."exifImageWidth" as "width",
+          "asset_exif"."exifImageHeight" as "height",
+          "asset_video"."pixelFormat",
+          "asset_video"."frameCount",
+          "asset_exif"."fps" as "frameRate",
+          "asset_video"."timeBase",
+          case
+            when "asset_exif"."orientation" = '6' then -90
+            when "asset_exif"."orientation" = '8' then 90
+            when "asset_exif"."orientation" = '3' then 180
+            else 0
+          end as "rotation",
+          "asset_video"."colorPrimaries",
+          "asset_video"."colorMatrix",
+          "asset_video"."colorTransfer",
+          "asset_video"."dvProfile",
+          "asset_video"."dvLevel",
+          "asset_video"."dvBlSignalCompatibilityId"
+        from
+          (
+            select
+              1
+          ) as "dummy"
+        where
+          "asset_video"."assetId" is not null
+      ) as obj
+  ) as "videoStream",
+  (
+    select
+      to_json(obj)
+    from
+      (
+        select
+          "asset_keyframe"."pts" as "keyframePts",
+          "asset_keyframe"."accDuration" as "keyframeAccDuration",
+          "asset_keyframe"."ownDuration" as "keyframeOwnDuration",
+          "asset_keyframe"."totalDuration",
+          "asset_keyframe"."packetCount",
+          "asset_keyframe"."outputFrames"
+        from
+          (
+            select
+              1
+          ) as "dummy"
+        where
+          "asset_keyframe"."assetId" is not null
+      ) as obj
+  ) as "packets"
+from
+  "asset"
+  inner join "asset_exif" on "asset"."id" = "asset_exif"."assetId"
+  inner join "asset_video" on "asset"."id" = "asset_video"."assetId"
+  inner join "asset_keyframe" on "asset"."id" = "asset_keyframe"."assetId"
+where
+  "asset"."id" = $1
+
+-- VideoStreamRepository.getForMediaPlaylist
+select
+  (
+    select
+      to_json(obj)
+    from
+      (
+        select
+          "asset_video"."index",
+          "asset_video"."codecName",
+          "asset_video"."profile",
+          "asset_video"."level",
+          "asset_video"."bitrate",
+          "asset_exif"."exifImageWidth" as "width",
+          "asset_exif"."exifImageHeight" as "height",
+          "asset_video"."pixelFormat",
+          "asset_video"."frameCount",
+          "asset_exif"."fps" as "frameRate",
+          "asset_video"."timeBase",
+          case
+            when "asset_exif"."orientation" = '6' then -90
+            when "asset_exif"."orientation" = '8' then 90
+            when "asset_exif"."orientation" = '3' then 180
+            else 0
+          end as "rotation",
+          "asset_video"."colorPrimaries",
+          "asset_video"."colorMatrix",
+          "asset_video"."colorTransfer",
+          "asset_video"."dvProfile",
+          "asset_video"."dvLevel",
+          "asset_video"."dvBlSignalCompatibilityId"
+        from
+          (
+            select
+              1
+          ) as "dummy"
+        where
+          "asset_video"."assetId" is not null
+      ) as obj
+  ) as "videoStream",
+  (
+    select
+      to_json(obj)
+    from
+      (
+        select
+          "asset_keyframe"."pts" as "keyframePts",
+          "asset_keyframe"."accDuration" as "keyframeAccDuration",
+          "asset_keyframe"."ownDuration" as "keyframeOwnDuration",
+          "asset_keyframe"."totalDuration",
+          "asset_keyframe"."packetCount",
+          "asset_keyframe"."outputFrames"
+        from
+          (
+            select
+              1
+          ) as "dummy"
+        where
+          "asset_keyframe"."assetId" is not null
+      ) as obj
+  ) as "packets"
+from
+  "asset"
+  inner join "asset_exif" on "asset"."id" = "asset_exif"."assetId"
+  inner join "video_stream_session" on "asset"."id" = "video_stream_session"."assetId"
+  inner join "asset_video" on "asset"."id" = "asset_video"."assetId"
+  inner join "asset_keyframe" on "asset"."id" = "asset_keyframe"."assetId"
+where
+  "asset"."id" = $1
+  and "video_stream_session"."id" = $2
+  and "video_stream_session"."expiresAt" > $3
+
+-- VideoStreamRepository.getForTranscoding
+select
+  "asset"."originalPath",
+  (
+    select
+      to_json(obj)
+    from
+      (
+        select
+          "asset_audio"."index",
+          "asset_audio"."codecName",
+          "asset_audio"."profile",
+          "asset_audio"."bitrate"
+        from
+          (
+            select
+              1
+          ) as "dummy"
+        where
+          "asset_audio"."assetId" is not null
+      ) as obj
+  ) as "audioStream",
+  (
+    select
+      to_json(obj)
+    from
+      (
+        select
+          "asset_video"."index",
+          "asset_video"."codecName",
+          "asset_video"."profile",
+          "asset_video"."level",
+          "asset_video"."bitrate",
+          "asset_exif"."exifImageWidth" as "width",
+          "asset_exif"."exifImageHeight" as "height",
+          "asset_video"."pixelFormat",
+          "asset_video"."frameCount",
+          "asset_exif"."fps" as "frameRate",
+          "asset_video"."timeBase",
+          case
+            when "asset_exif"."orientation" = '6' then -90
+            when "asset_exif"."orientation" = '8' then 90
+            when "asset_exif"."orientation" = '3' then 180
+            else 0
+          end as "rotation",
+          "asset_video"."colorPrimaries",
+          "asset_video"."colorMatrix",
+          "asset_video"."colorTransfer",
+          "asset_video"."dvProfile",
+          "asset_video"."dvLevel",
+          "asset_video"."dvBlSignalCompatibilityId"
+        from
+          (
+            select
+              1
+          ) as "dummy"
+        where
+          "asset_video"."assetId" is not null
+      ) as obj
+  ) as "videoStream",
+  (
+    select
+      to_json(obj)
+    from
+      (
+        select
+          "asset_video"."formatName",
+          "asset_video"."formatLongName",
+          "asset"."duration",
+          "asset_video"."bitrate"
+        from
+          (
+            select
+              1
+          ) as "dummy"
+        where
+          "asset_video"."assetId" is not null
+      ) as obj
+  ) as "format",
+  (
+    select
+      to_json(obj)
+    from
+      (
+        select
+          "asset_keyframe"."pts" as "keyframePts",
+          "asset_keyframe"."accDuration" as "keyframeAccDuration",
+          "asset_keyframe"."ownDuration" as "keyframeOwnDuration",
+          "asset_keyframe"."totalDuration",
+          "asset_keyframe"."packetCount",
+          "asset_keyframe"."outputFrames"
+        from
+          (
+            select
+              1
+          ) as "dummy"
+        where
+          "asset_keyframe"."assetId" is not null
+      ) as obj
+  ) as "packets"
+from
+  "asset"
+  inner join "asset_exif" on "asset"."id" = "asset_exif"."assetId"
+  left join "asset_audio" on "asset"."id" = "asset_audio"."assetId"
+  inner join "asset_video" on "asset"."id" = "asset_video"."assetId"
+  inner join "asset_keyframe" on "asset"."id" = "asset_keyframe"."assetId"
+where
+  "asset"."id" = $1

server/src/repositories/event.repository.ts

@@ -92,6 +92,14 @@ type EventMap = {
 
   AuthChangePassword: [{ userId: string; currentSessionId?: string; invalidateSessions?: boolean }];
 
+  // hls streaming events
+  HlsSegmentRequest: [{ sessionId: string; assetId: string; variantIndex: number; segmentIndex: number }];
+  HlsSegmentResult: [{ sessionId: string; variantIndex: number; segmentIndex: number; error?: string }];
+  HlsHeartbeat: [{ sessionId: string; variantIndex?: number; segmentIndex?: number }];
+  HlsSessionRequest: [{ sessionId: string; assetId: string; ownerId: string }];
+  HlsSessionResult: [{ sessionId: string; error?: string }];
+  HlsSessionEnd: [{ sessionId: string }];
+
   // websocket events
   WebsocketConnect: [{ userId: string }];
 };

server/src/repositories/media.repository.ts

@@ -490,18 +490,43 @@ export class MediaRepository {
     return this.parseInt(b.bit_rate) - this.parseInt(a.bit_rate);
   }
 
+  /* Ported from https://code.ffmpeg.org/FFmpeg/FFmpeg/src/commit/5c44245878e235ae64fe87fb9877644856d33d1d/fftools/ffmpeg_filter.c
+   * SPDX-License-Identifier: LGPL-2.1-or-later
+   * Copyright (c) FFmpeg authors and contributors — https://ffmpeg.org/
+   * Modifications: TS port operating on probe-derived packet metadata rather than decoded AVFrames. */
   private cfrOutputFrames(packets: { pts: number; duration: number }[], slotsPerTick: number) {
-    // Packets may be out of PTS order due to B-frames
     packets.sort((a, b) => a.pts - b.pts);
     const firstPts = packets[0].pts;
     let outputFrames = 0;
     let nextPts = 0;
+    const history = [0, 0, 0];
     for (const pkt of packets) {
-      const delta = (pkt.pts - firstPts) * slotsPerTick - nextPts + pkt.duration * slotsPerTick;
-      const nb = delta < -1.1 ? 0 : delta > 1.1 ? Math.round(delta) : 1;
+      const syncIpts = (pkt.pts - firstPts) * slotsPerTick;
+      const duration = pkt.duration * slotsPerTick;
+      let delta0 = syncIpts - nextPts;
+      const delta = delta0 + duration;
+
+      if (delta0 < 0 && delta > 0) {
+        delta0 = 0;
+      }
+
+      let nb = 1;
+      let nbPrev = 0;
+      if (delta < -1.1) {
+        nb = 0;
+      } else if (delta > 1.1) {
+        nb = Math.round(delta);
+        if (delta0 > 1.1) {
+          nbPrev = Math.round(delta0 - 0.6);
+        }
+      }
       outputFrames += nb;
       nextPts += nb;
+      history[2] = history[1];
+      history[1] = history[0];
+      history[0] = nbPrev;
     }
-    return outputFrames;
+    const median = history.sort((a, b) => a - b)[1];
+    return outputFrames + median;
   }
 }

server/src/repositories/process.repository.ts

@@ -1,12 +1,10 @@
 import { Injectable } from '@nestjs/common';
-import { ChildProcessWithoutNullStreams, fork, spawn, SpawnOptionsWithoutStdio } from 'node:child_process';
+import { fork, spawn, SpawnOptionsWithoutStdio } from 'node:child_process';
 import { Duplex } from 'node:stream';
 
 @Injectable()
 export class ProcessRepository {
-  spawn(command: string, args?: readonly string[], options?: SpawnOptionsWithoutStdio): ChildProcessWithoutNullStreams {
-    return spawn(command, args, options);
-  }
+  spawn = spawn;
 
   spawnDuplexStream(command: string, args?: readonly string[], options?: SpawnOptionsWithoutStdio): Duplex {
     let stdinClosed = false;

server/src/repositories/server-info.repository.ts

@@ -4,6 +4,7 @@ import { exec as execCallback } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { promisify } from 'node:util';
 import sharp from 'sharp';
+import { ReleaseChannel } from 'src/dtos/system-config.dto';
 import { ConfigRepository } from 'src/repositories/config.repository';
 import { LoggingRepository } from 'src/repositories/logging.repository';
 
@@ -64,10 +65,12 @@ export class ServerInfoRepository {
     this.logger.setContext(ServerInfoRepository.name);
   }
 
-  async getLatestRelease(): Promise<VersionResponse> {
+  async getLatestRelease(channel: ReleaseChannel): Promise<VersionResponse> {
     try {
       const { versionCheck } = this.configRepository.getEnv();
-      const response = await fetch(versionCheck.url);
+      const url = new URL(versionCheck.url);
+      url.searchParams.append('channel', channel);
+      const response = await fetch(url);
 
       if (!response.ok) {
         throw new Error(`Version check request failed with status ${response.status}: ${await response.text()}`);

server/src/repositories/storage.repository.ts

@@ -10,6 +10,7 @@ import {
   existsSync,
   mkdirSync,
   ReadOptionsWithBuffer,
+  watch,
 } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -277,6 +278,8 @@ export class StorageRepository {
     return () => watcher.close();
   }
 
+  watchDir = watch; // Native fs.watch without chokidar overhead
+
   private asGlob(pathToCrawl: string): string {
     const escapedPath = escapePath(pathToCrawl).replaceAll('"', '["]').replaceAll("'", "[']").replaceAll('`', '[`]');
     const extensions = `*{${mimeTypes.getSupportedFileExtensions().join(',')}}`;

server/src/repositories/video-stream.repository.ts

@@ -8,6 +8,7 @@ import {
   VideoStreamSessionTable,
   VideoStreamVariantTable,
 } from 'src/schema/tables/video-stream.table';
+import { withAudioStream, withVideoFormat, withVideoPackets, withVideoStream } from 'src/utils/database';
 
 @Injectable()
 export class VideoStreamRepository {
@@ -27,7 +28,12 @@ export class VideoStreamRepository {
 
   @GenerateSql({ params: [DummyValue.UUID] })
   getSession(id: string) {
-    return this.db.selectFrom('video_stream_session').selectAll().where('id', '=', id).executeTakeFirst();
+    return this.db
+      .selectFrom('video_stream_session')
+      .selectAll()
+      .where('id', '=', id)
+      .where('expiresAt', '>', new Date())
+      .executeTakeFirst();
   }
 
   @GenerateSql({ params: [DummyValue.UUID] })
@@ -47,7 +53,12 @@ export class VideoStreamRepository {
 
   @GenerateSql()
   getExpiredSessions() {
-    return this.db.selectFrom('video_stream_session').select(['id']).where('expiresAt', '<=', new Date()).execute();
+    return this.db
+      .selectFrom('video_stream_session')
+      .innerJoin('asset', 'asset.id', 'video_stream_session.assetId')
+      .select(['video_stream_session.id', 'asset.ownerId'])
+      .where('video_stream_session.expiresAt', '<=', new Date())
+      .execute();
   }
 
   @GenerateSql({ params: [DummyValue.UUID, DummyValue.DATE] })
@@ -59,4 +70,50 @@ export class VideoStreamRepository {
   async deleteSession(id: string) {
     await this.db.deleteFrom('video_stream_session').where('id', '=', id).execute();
   }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  async getForMainPlaylist(id: string) {
+    return this.db
+      .selectFrom('asset')
+      .innerJoin('asset_exif', 'asset.id', 'asset_exif.assetId')
+      .where('asset.id', '=', id)
+      .innerJoin('asset_video', 'asset.id', 'asset_video.assetId')
+      .innerJoin('asset_keyframe', 'asset.id', 'asset_keyframe.assetId')
+      .select((eb) => withVideoStream(eb).$notNull().as('videoStream'))
+      .select((eb) => withVideoPackets(eb).$notNull().as('packets'))
+      .executeTakeFirst();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID, DummyValue.UUID] })
+  async getForMediaPlaylist(id: string, sessionId: string) {
+    return this.db
+      .selectFrom('asset')
+      .innerJoin('asset_exif', 'asset.id', 'asset_exif.assetId')
+      .innerJoin('video_stream_session', 'asset.id', 'video_stream_session.assetId')
+      .where('asset.id', '=', id)
+      .where('video_stream_session.id', '=', sessionId)
+      .where('video_stream_session.expiresAt', '>', new Date())
+      .innerJoin('asset_video', 'asset.id', 'asset_video.assetId')
+      .innerJoin('asset_keyframe', 'asset.id', 'asset_keyframe.assetId')
+      .select((eb) => withVideoStream(eb).$notNull().as('videoStream'))
+      .select((eb) => withVideoPackets(eb).$notNull().as('packets'))
+      .executeTakeFirst();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  async getForTranscoding(id: string) {
+    return this.db
+      .selectFrom('asset')
+      .innerJoin('asset_exif', 'asset.id', 'asset_exif.assetId')
+      .where('asset.id', '=', id)
+      .leftJoin('asset_audio', 'asset.id', 'asset_audio.assetId')
+      .innerJoin('asset_video', 'asset.id', 'asset_video.assetId')
+      .innerJoin('asset_keyframe', 'asset.id', 'asset_keyframe.assetId')
+      .select('asset.originalPath')
+      .select((eb) => withAudioStream(eb).as('audioStream'))
+      .select((eb) => withVideoStream(eb).$notNull().as('videoStream'))
+      .select((eb) => withVideoFormat(eb).$notNull().as('format'))
+      .select((eb) => withVideoPackets(eb).$notNull().as('packets'))
+      .executeTakeFirst();
+  }
 }

server/src/repositories/websocket.repository.ts

@@ -10,13 +10,22 @@ import { Server, Socket } from 'socket.io';
 import { AssetResponseDto } from 'src/dtos/asset-response.dto';
 import { AuthDto } from 'src/dtos/auth.dto';
 import { NotificationDto } from 'src/dtos/notification.dto';
-import { ReleaseNotification, ServerVersionResponseDto } from 'src/dtos/server.dto';
+import { ReleaseEventV1, ServerVersionResponseDto } from 'src/dtos/server.dto';
 import { SyncAssetEditV1, SyncAssetExifV1, SyncAssetV2 } from 'src/dtos/sync.dto';
 import { AppRestartEvent, ArgsOf, EventRepository } from 'src/repositories/event.repository';
 import { LoggingRepository } from 'src/repositories/logging.repository';
 import { handlePromiseError } from 'src/utils/misc';
 
-export const serverEvents = ['ConfigUpdate', 'AppRestart'] as const;
+export const serverEvents = [
+  'ConfigUpdate',
+  'AppRestart',
+  'HlsSegmentRequest',
+  'HlsSegmentResult',
+  'HlsHeartbeat',
+  'HlsSessionRequest',
+  'HlsSessionResult',
+  'HlsSessionEnd',
+] as const;
 export type ServerEvents = (typeof serverEvents)[number];
 
 export interface ClientEventMap {
@@ -31,7 +40,7 @@ export interface ClientEventMap {
   on_person_thumbnail: [string];
   on_server_version: [ServerVersionResponseDto];
   on_config_update: [];
-  on_new_release: [ReleaseNotification];
+  on_new_release: [ReleaseEventV1];
   on_notification: [NotificationDto];
   on_session_delete: [string];
 

server/src/schema/enums.ts

@@ -1,12 +1,5 @@
 import { registerEnum } from '@immich/sql-tools';
-import {
-  AlbumUserRole,
-  AssetStatus,
-  AssetVisibility,
-  ChecksumAlgorithm,
-  SourceType,
-  VideoSegmentCodec,
-} from 'src/enum';
+import { AlbumUserRole, AssetStatus, AssetVisibility, ChecksumAlgorithm, SourceType, VideoCodec } from 'src/enum';
 
 export const album_user_role_enum = registerEnum({
   name: 'album_user_role_enum',
@@ -35,5 +28,5 @@ export const asset_checksum_algorithm_enum = registerEnum({
 
 export const video_stream_variant_codec_enum = registerEnum({
   name: 'video_stream_variant_codec_enum',
-  values: Object.values(VideoSegmentCodec),
+  values: [VideoCodec.Av1, VideoCodec.Hevc, VideoCodec.H264],
 });

server/src/services/hls.service.spec.ts

@@ -0,0 +1,327 @@
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+import { TranscodeHardwareAcceleration } from 'src/enum';
+import { HlsService } from 'src/services/hls.service';
+import { eiffelTower, train, waterfall } from 'test/fixtures/media.stub';
+import { factory } from 'test/small.factory';
+import { newTestService, ServiceMocks } from 'test/utils';
+
+// EXTINF values come from FFmpeg's playlist to enforce an exact match
+const eiffelExpectedMediaPlaylist = `#EXTM3U
+#EXT-X-VERSION:7
+#EXT-X-TARGETDURATION:2
+#EXT-X-MEDIA-SEQUENCE:0
+#EXT-X-PLAYLIST-TYPE:VOD
+#EXT-X-MAP:URI="init.mp4"
+#EXTINF:2.007222,
+seg_0.m4s
+#EXTINF:2.007222,
+seg_1.m4s
+#EXTINF:2.007222,
+seg_2.m4s
+#EXTINF:2.007222,
+seg_3.m4s
+#EXTINF:2.007222,
+seg_4.m4s
+#EXTINF:2.007222,
+seg_5.m4s
+#EXTINF:2.007222,
+seg_6.m4s
+#EXTINF:2.007222,
+seg_7.m4s
+#EXTINF:2.007222,
+seg_8.m4s
+#EXTINF:2.007222,
+seg_9.m4s
+#EXTINF:2.007222,
+seg_10.m4s
+#EXTINF:0.281011,
+seg_11.m4s
+#EXT-X-ENDLIST
+`;
+
+const waterfallExpectedMediaPlaylist = `#EXTM3U
+#EXT-X-VERSION:7
+#EXT-X-TARGETDURATION:2
+#EXT-X-MEDIA-SEQUENCE:0
+#EXT-X-PLAYLIST-TYPE:VOD
+#EXT-X-MAP:URI="init.mp4"
+#EXTINF:2.011405,
+seg_0.m4s
+#EXTINF:2.011405,
+seg_1.m4s
+#EXTINF:2.011405,
+seg_2.m4s
+#EXTINF:2.011405,
+seg_3.m4s
+#EXTINF:2.011405,
+seg_4.m4s
+#EXTINF:0.301711,
+seg_5.m4s
+#EXT-X-ENDLIST
+`;
+
+const trainExpectedMediaPlaylist = `#EXTM3U
+#EXT-X-VERSION:7
+#EXT-X-TARGETDURATION:2
+#EXT-X-MEDIA-SEQUENCE:0
+#EXT-X-PLAYLIST-TYPE:VOD
+#EXT-X-MAP:URI="init.mp4"
+#EXTINF:2.000000,
+seg_0.m4s
+#EXTINF:2.000000,
+seg_1.m4s
+#EXTINF:2.000000,
+seg_2.m4s
+#EXTINF:2.000000,
+seg_3.m4s
+#EXTINF:2.000000,
+seg_4.m4s
+#EXTINF:2.000000,
+seg_5.m4s
+#EXTINF:2.000000,
+seg_6.m4s
+#EXTINF:2.000000,
+seg_7.m4s
+#EXTINF:2.000000,
+seg_8.m4s
+#EXTINF:2.000000,
+seg_9.m4s
+#EXTINF:1.733333,
+seg_10.m4s
+#EXT-X-ENDLIST
+`;
+
+const sessionId = '00000000-0000-0000-0000-000000000000';
+
+const eiffelExpectedMasterDisabled = `#EXTM3U
+#EXT-X-VERSION:7
+#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=480x852,CODECS="av01.0.04M.08,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/0/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=1200000,RESOLUTION=480x852,CODECS="hvc1.1.6.L90.B0,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/1/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=480x852,CODECS="avc1.64001e,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/2/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=2000000,RESOLUTION=720x1280,CODECS="av01.0.08M.08,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/3/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=720x1280,CODECS="hvc1.1.6.L93.B0,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/4/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=720x1280,CODECS="avc1.64001f,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/5/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=4000000,RESOLUTION=1080x1920,CODECS="av01.0.09M.08,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/6/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=4500000,RESOLUTION=1080x1920,CODECS="hvc1.1.6.L120.B0,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/7/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=8000000,RESOLUTION=1080x1920,CODECS="avc1.640028,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/8/playlist.m3u8
+`;
+
+const eiffelExpectedMasterRkmpp = `#EXTM3U
+#EXT-X-VERSION:7
+#EXT-X-STREAM-INF:BANDWIDTH=1200000,RESOLUTION=480x852,CODECS="hvc1.1.6.L90.B0,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/1/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=480x852,CODECS="avc1.64001e,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/2/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=720x1280,CODECS="hvc1.1.6.L93.B0,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/4/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=720x1280,CODECS="avc1.64001f,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/5/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=4500000,RESOLUTION=1080x1920,CODECS="hvc1.1.6.L120.B0,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/7/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=8000000,RESOLUTION=1080x1920,CODECS="avc1.640028,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=24.910
+${sessionId}/8/playlist.m3u8
+`;
+
+const waterfallExpectedMasterDisabled = `#EXTM3U
+#EXT-X-VERSION:7
+#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=480x852,CODECS="av01.0.04M.08,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=29.830
+${sessionId}/0/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=1200000,RESOLUTION=480x852,CODECS="hvc1.1.6.L90.B0,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=29.830
+${sessionId}/1/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=480x852,CODECS="avc1.64001e,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=29.830
+${sessionId}/2/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=2000000,RESOLUTION=720x1280,CODECS="av01.0.08M.08,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=29.830
+${sessionId}/3/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=720x1280,CODECS="hvc1.1.6.L93.B0,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=29.830
+${sessionId}/4/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=720x1280,CODECS="avc1.64001f,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=29.830
+${sessionId}/5/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=4000000,RESOLUTION=1080x1920,CODECS="av01.0.09M.08,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=29.830
+${sessionId}/6/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=4500000,RESOLUTION=1080x1920,CODECS="hvc1.1.6.L120.B0,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=29.830
+${sessionId}/7/playlist.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=8000000,RESOLUTION=1080x1920,CODECS="avc1.640028,mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=29.830
+${sessionId}/8/playlist.m3u8
+`;
+
+describe(HlsService.name, () => {
+  let sut: HlsService;
+  let mocks: ServiceMocks;
+
+  beforeEach(() => {
+    ({ sut, mocks } = newTestService(HlsService));
+  });
+
+  describe('getMainPlaylist', () => {
+    const auth = factory.auth();
+    const assetId = 'asset-1';
+
+    const setup = (asset: typeof eiffelTower | typeof waterfall, accel: TranscodeHardwareAcceleration) => {
+      mocks.access.asset.checkOwnerAccess.mockResolvedValue(new Set([assetId]));
+      mocks.systemMetadata.get.mockResolvedValue({ ffmpeg: { realtime: { enabled: true }, accel } });
+      mocks.videoStream.getForMainPlaylist.mockResolvedValue(asset);
+      mocks.crypto.randomUUID.mockReturnValue(sessionId);
+      mocks.websocket.serverSend.mockImplementation((event, ...rest) => {
+        if (event === 'HlsSessionRequest') {
+          const { sessionId: id } = rest[0] as { sessionId: string };
+          queueMicrotask(() => sut.onSessionResult({ sessionId: id }));
+        }
+      });
+    };
+
+    it('returns main playlist for eiffel-tower (1080p portrait, no acceleration)', async () => {
+      setup(eiffelTower, TranscodeHardwareAcceleration.Disabled);
+      await expect(sut.getMainPlaylist(auth, assetId)).resolves.toBe(eiffelExpectedMasterDisabled);
+    });
+
+    it('returns main playlist for eiffel-tower with RKMPP (no AV1 variants)', async () => {
+      setup(eiffelTower, TranscodeHardwareAcceleration.Rkmpp);
+      await expect(sut.getMainPlaylist(auth, assetId)).resolves.toBe(eiffelExpectedMasterRkmpp);
+    });
+
+    it('returns main playlist for waterfall (4K landscape) with no acceleration', async () => {
+      setup(waterfall, TranscodeHardwareAcceleration.Disabled);
+      await expect(sut.getMainPlaylist(auth, assetId)).resolves.toBe(waterfallExpectedMasterDisabled);
+    });
+
+    it('throws BadRequestException when realtime transcoding is disabled', async () => {
+      mocks.access.asset.checkOwnerAccess.mockResolvedValue(new Set([assetId]));
+      mocks.systemMetadata.get.mockResolvedValue({ ffmpeg: { realtime: { enabled: false } } });
+      await expect(sut.getMainPlaylist(auth, assetId)).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('throws NotFoundException when asset is not yet ready for streaming', async () => {
+      mocks.access.asset.checkOwnerAccess.mockResolvedValue(new Set([assetId]));
+      mocks.systemMetadata.get.mockResolvedValue({ ffmpeg: { realtime: { enabled: true } } });
+      await expect(sut.getMainPlaylist(auth, assetId)).rejects.toBeInstanceOf(NotFoundException);
+    });
+  });
+
+  describe('getMediaPlaylist', () => {
+    const auth = factory.auth();
+    const assetId = 'asset-1';
+    const fixtures = [
+      { data: eiffelTower, playlist: eiffelExpectedMediaPlaylist },
+      { data: waterfall, playlist: waterfallExpectedMediaPlaylist },
+      { data: train, playlist: trainExpectedMediaPlaylist },
+    ];
+
+    it.each(fixtures)('matches FFmpeg for $data.originalPath', async ({ data, playlist }) => {
+      mocks.access.asset.checkOwnerAccess.mockResolvedValue(new Set([assetId]));
+      mocks.videoStream.getForMediaPlaylist.mockResolvedValue(data);
+      await expect(sut.getMediaPlaylist(auth, assetId, sessionId)).resolves.toBe(playlist);
+    });
+
+    it('throws NotFoundException when the session/asset cannot be loaded', async () => {
+      mocks.access.asset.checkOwnerAccess.mockResolvedValue(new Set([assetId]));
+      await expect(sut.getMediaPlaylist(auth, assetId, sessionId)).rejects.toBeInstanceOf(NotFoundException);
+    });
+  });
+
+  describe('getSegment', () => {
+    const auth = factory.auth();
+    const assetId = 'asset-1';
+    const variantIndex = 0;
+
+    beforeEach(() => {
+      mocks.access.asset.checkOwnerAccess.mockResolvedValue(new Set([assetId]));
+      mocks.videoStream.getSession.mockResolvedValue({ id: sessionId, assetId } as never);
+      mocks.storage.checkFileExists.mockResolvedValue(true);
+    });
+
+    it('emits HlsHeartbeat with segmentIndex 0 for the first init.mp4 request', async () => {
+      await sut.getSegment(auth, assetId, sessionId, variantIndex, 'init.mp4');
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsHeartbeat', {
+        sessionId,
+        variantIndex,
+        segmentIndex: 0,
+      });
+    });
+
+    it('emits HlsHeartbeat with the parsed segment number for seg_K.m4s', async () => {
+      await sut.getSegment(auth, assetId, sessionId, variantIndex, 'seg_5.m4s');
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsHeartbeat', {
+        sessionId,
+        variantIndex,
+        segmentIndex: 5,
+      });
+    });
+
+    it('returns lastRequested + 1 for init.mp4 after a segment has been served', async () => {
+      await sut.getSegment(auth, assetId, sessionId, variantIndex, 'seg_5.m4s');
+      mocks.websocket.serverSend.mockClear();
+      await sut.getSegment(auth, assetId, sessionId, variantIndex, 'init.mp4');
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsHeartbeat', {
+        sessionId,
+        variantIndex,
+        segmentIndex: 6,
+      });
+    });
+
+    it('updates lastRequested on a backward-seek segment request', async () => {
+      await sut.getSegment(auth, assetId, sessionId, variantIndex, 'seg_5.m4s');
+      await sut.getSegment(auth, assetId, sessionId, variantIndex, 'seg_3.m4s');
+      mocks.websocket.serverSend.mockClear();
+      await sut.getSegment(auth, assetId, sessionId, variantIndex, 'init.mp4');
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsHeartbeat', {
+        sessionId,
+        variantIndex,
+        segmentIndex: 4,
+      });
+    });
+
+    it('tracks segment state per session independently', async () => {
+      await sut.getSegment(auth, assetId, 'session-a', variantIndex, 'seg_5.m4s');
+      await sut.getSegment(auth, assetId, 'session-b', variantIndex, 'seg_2.m4s');
+      mocks.websocket.serverSend.mockClear();
+      await sut.getSegment(auth, assetId, 'session-a', variantIndex, 'init.mp4');
+      await sut.getSegment(auth, assetId, 'session-b', variantIndex, 'init.mp4');
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsHeartbeat', {
+        sessionId: 'session-a',
+        variantIndex,
+        segmentIndex: 6,
+      });
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsHeartbeat', {
+        sessionId: 'session-b',
+        variantIndex,
+        segmentIndex: 3,
+      });
+    });
+
+    it('rejects pending waiters for the previous variant on variant change', async () => {
+      mocks.storage.checkFileExists.mockResolvedValueOnce(false);
+
+      const pending = sut.getSegment(auth, assetId, sessionId, 0, 'seg_1.m4s');
+      await new Promise((resolve) => setImmediate(resolve));
+      await sut.getSegment(auth, assetId, sessionId, 1, 'seg_1.m4s');
+
+      await expect(pending).rejects.toThrow('Variant changed');
+    });
+
+    it('throws NotFoundException when the session does not exist', async () => {
+      mocks.videoStream.getSession.mockReset();
+      await expect(sut.getSegment(auth, assetId, sessionId, variantIndex, 'init.mp4')).rejects.toBeInstanceOf(
+        NotFoundException,
+      );
+    });
+  });
+
+  describe('endSession', () => {
+    it('emits HlsSessionEnd', async () => {
+      const auth = factory.auth();
+      const assetId = 'asset-1';
+      mocks.access.asset.checkOwnerAccess.mockResolvedValue(new Set([assetId]));
+      await sut.endSession(auth, assetId, sessionId);
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsSessionEnd', { sessionId });
+    });
+  });
+});

server/src/services/hls.service.ts

@@ -0,0 +1,198 @@
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+import {
+  HLS_SEGMENT_DURATION,
+  HLS_SEGMENT_FILENAME_REGEX,
+  HLS_VARIANTS,
+  HLS_VERSION,
+  SUPPORTED_HWA_CODECS,
+} from 'src/constants';
+import { StorageCore } from 'src/cores/storage.core';
+import { OnEvent } from 'src/decorators';
+import { AuthDto } from 'src/dtos/auth.dto';
+import { SystemConfigFFmpegDto } from 'src/dtos/system-config.dto';
+import { CacheControl, ImmichWorker, Permission } from 'src/enum';
+import { ArgOf } from 'src/repositories/event.repository';
+import { BaseService } from 'src/services/base.service';
+import { VideoPacketInfo, VideoStreamInfo } from 'src/types';
+import { PendingEvents } from 'src/utils/event';
+import { ImmichFileResponse } from 'src/utils/file';
+import { getOutputSize } from 'src/utils/media';
+
+type AssetWithStreamInfo = { videoStream: VideoStreamInfo & { timeBase: number }; packets: VideoPacketInfo };
+type ApiSession = { lastRequestedSegment: number | null; lastVariantIndex: number | null };
+
+@Injectable()
+export class HlsService extends BaseService {
+  private pendingSegments = new PendingEvents<'HlsSegmentResult'>({ timeoutMs: 15_000 });
+  private pendingSessions = new PendingEvents<'HlsSessionResult'>({ timeoutMs: 5000 });
+  private sessions = new Map<string, ApiSession>();
+
+  @OnEvent({ name: 'HlsSessionResult', server: true, workers: [ImmichWorker.Api] })
+  onSessionResult(event: ArgOf<'HlsSessionResult'>) {
+    this.pendingSessions.complete(event.sessionId, event);
+    if (event.error) {
+      this.sessions.delete(event.sessionId);
+      this.pendingSegments.rejectByPrefix(`${event.sessionId}:`, event.error);
+    }
+  }
+
+  @OnEvent({ name: 'HlsSessionEnd', server: true, workers: [ImmichWorker.Api] })
+  onSessionEnd({ sessionId }: ArgOf<'HlsSessionEnd'>) {
+    this.sessions.delete(sessionId);
+    this.pendingSegments.rejectByPrefix(`${sessionId}:`, 'Session ended');
+  }
+
+  @OnEvent({ name: 'HlsSegmentResult', server: true, workers: [ImmichWorker.Api] })
+  onSegmentResult(event: ArgOf<'HlsSegmentResult'>) {
+    this.pendingSegments.complete(this.getSegmentKey(event), event);
+  }
+
+  async getMainPlaylist(auth: AuthDto, assetId: string) {
+    await this.requireAccess({ auth, permission: Permission.AssetView, ids: [assetId] });
+    const { ffmpeg } = await this.getConfig({ withCache: true });
+    if (!ffmpeg.realtime.enabled) {
+      throw new BadRequestException('Real-time transcoding is not enabled');
+    }
+
+    const asset = await this.videoStreamRepository.getForMainPlaylist(assetId);
+    if (!asset) {
+      throw new NotFoundException('Asset is not yet ready for streaming');
+    }
+
+    // Sharing the sessionId allows only one microservices worker to successfully insert to the session table.
+    // The microservices worker that creates a session owns the transcoding lifecycle for it.
+    const sessionId = this.cryptoRepository.randomUUID();
+    this.websocketRepository.serverSend('HlsSessionRequest', { sessionId, assetId, ownerId: auth.user.id });
+    await this.pendingSessions.wait(sessionId);
+    this.trackSession(sessionId);
+
+    return this.generateMainPlaylist(sessionId, ffmpeg, asset);
+  }
+
+  async getMediaPlaylist(auth: AuthDto, assetId: string, sessionId: string) {
+    await this.requireAccess({ auth, permission: Permission.AssetView, ids: [assetId] });
+
+    const asset = await this.videoStreamRepository.getForMediaPlaylist(assetId, sessionId);
+    if (!asset) {
+      throw new NotFoundException('Asset not found or not yet ready for streaming');
+    }
+
+    return this.generateMediaPlaylist(asset);
+  }
+
+  async getSegment(auth: AuthDto, assetId: string, sessionId: string, variantIndex: number, filename: string) {
+    await this.requireAccess({ auth, permission: Permission.AssetView, ids: [assetId] });
+
+    const session = await this.videoStreamRepository.getSession(sessionId);
+    if (!session) {
+      throw new NotFoundException('Session not found');
+    }
+
+    const variantDir = StorageCore.getHlsVariantFolder({ ownerId: auth.user.id, sessionId, variantIndex });
+    const path = join(variantDir, filename);
+    const response = new ImmichFileResponse({
+      path,
+      contentType: 'video/mp4',
+      cacheControl: CacheControl.PrivateWithCache,
+    });
+
+    const apiSession = this.trackSession(sessionId, variantIndex);
+    const segmentIndex = this.getSegmentIndex(apiSession, filename);
+    this.websocketRepository.serverSend('HlsHeartbeat', { sessionId, variantIndex, segmentIndex });
+
+    if (await this.storageRepository.checkFileExists(path, constants.R_OK)) {
+      return response;
+    }
+
+    this.websocketRepository.serverSend('HlsSegmentRequest', { sessionId, assetId, variantIndex, segmentIndex });
+    await this.pendingSegments.wait(this.getSegmentKey({ sessionId, variantIndex, segmentIndex }));
+
+    return response;
+  }
+
+  async endSession(auth: AuthDto, assetId: string, sessionId: string): Promise<void> {
+    await this.requireAccess({ auth, permission: Permission.AssetView, ids: [assetId] });
+
+    this.websocketRepository.serverSend('HlsSessionEnd', { sessionId });
+  }
+
+  private generateMainPlaylist(sessionId: string, ffmpeg: SystemConfigFFmpegDto, asset: AssetWithStreamInfo) {
+    const fps = ((asset.packets.packetCount * asset.videoStream.timeBase) / asset.packets.totalDuration).toFixed(3);
+    const sourceResolution = Math.min(asset.videoStream.height, asset.videoStream.width);
+    const targetResolution = Math.max(sourceResolution, HLS_VARIANTS[0].resolution);
+    const lines = ['#EXTM3U', `#EXT-X-VERSION:${HLS_VERSION}`];
+    for (let i = 0; i < HLS_VARIANTS.length; i++) {
+      const { resolution, bitrate, codec, codecString } = HLS_VARIANTS[i];
+      if (resolution > targetResolution || !SUPPORTED_HWA_CODECS[ffmpeg.accel].includes(codec)) {
+        continue;
+      }
+      const { width, height } = getOutputSize(asset.videoStream, resolution);
+      lines.push(
+        `#EXT-X-STREAM-INF:BANDWIDTH=${bitrate},RESOLUTION=${width}x${height},CODECS="${codecString},mp4a.40.2",VIDEO-RANGE=SDR,FRAME-RATE=${fps}`,
+        `${sessionId}/${i}/playlist.m3u8`,
+      );
+    }
+    lines.push('');
+
+    if (lines.length === 3) {
+      throw new NotFoundException('No supported variants for this video');
+    }
+
+    return lines.join('\n');
+  }
+
+  private generateMediaPlaylist({ videoStream, packets }: AssetWithStreamInfo) {
+    const fps = (packets.packetCount * videoStream.timeBase) / packets.totalDuration;
+    const framesPerSegment = Math.ceil(HLS_SEGMENT_DURATION * fps);
+    const fullSegmentDuration = framesPerSegment / fps;
+    const segmentCount = Math.ceil(packets.outputFrames / framesPerSegment);
+    const lastSegmentFrames = packets.outputFrames - framesPerSegment * (segmentCount - 1);
+    const lastSegmentDuration = lastSegmentFrames / fps;
+
+    const lines = [
+      '#EXTM3U',
+      `#EXT-X-VERSION:${HLS_VERSION}`,
+      `#EXT-X-TARGETDURATION:${HLS_SEGMENT_DURATION}`,
+      '#EXT-X-MEDIA-SEQUENCE:0',
+      '#EXT-X-PLAYLIST-TYPE:VOD',
+      '#EXT-X-MAP:URI="init.mp4"',
+    ];
+
+    for (let i = 0; i < segmentCount - 1; i++) {
+      lines.push(`#EXTINF:${fullSegmentDuration.toFixed(6)},`, `seg_${i}.m4s`);
+    }
+    lines.push(`#EXTINF:${lastSegmentDuration.toFixed(6)},`, `seg_${segmentCount - 1}.m4s`, '#EXT-X-ENDLIST', '');
+
+    return lines.join('\n');
+  }
+
+  private getSegmentKey({ sessionId, variantIndex, segmentIndex }: ArgOf<'HlsSegmentResult'>) {
+    return `${sessionId}:${variantIndex}:${segmentIndex}`;
+  }
+
+  private getSegmentIndex(session: ApiSession, filename: string) {
+    if (filename.endsWith('.mp4')) {
+      return (session.lastRequestedSegment ?? -1) + 1;
+    }
+    const segmentIndex = Number.parseInt(HLS_SEGMENT_FILENAME_REGEX.exec(filename)![1]);
+    session.lastRequestedSegment = segmentIndex;
+    return segmentIndex;
+  }
+
+  private trackSession(id: string, variantIndex: number | null = null) {
+    const session = this.sessions.get(id);
+    if (!session) {
+      const newSession = { lastRequestedSegment: null, lastVariantIndex: variantIndex };
+      this.sessions.set(id, newSession);
+      return newSession;
+    }
+
+    if (session.lastVariantIndex !== null && session.lastVariantIndex !== variantIndex) {
+      this.pendingSegments.rejectByPrefix(`${id}:${session.lastVariantIndex}:`, 'Variant changed');
+    }
+    session.lastVariantIndex = variantIndex;
+    return session;
+  }
+}

server/src/services/index.ts

@@ -11,6 +11,7 @@ import { DatabaseBackupService } from 'src/services/database-backup.service';
 import { DatabaseService } from 'src/services/database.service';
 import { DownloadService } from 'src/services/download.service';
 import { DuplicateService } from 'src/services/duplicate.service';
+import { HlsService } from 'src/services/hls.service';
 import { JobService } from 'src/services/job.service';
 import { LibraryService } from 'src/services/library.service';
 import { MaintenanceService } from 'src/services/maintenance.service';
@@ -39,6 +40,7 @@ import { SystemMetadataService } from 'src/services/system-metadata.service';
 import { TagService } from 'src/services/tag.service';
 import { TelemetryService } from 'src/services/telemetry.service';
 import { TimelineService } from 'src/services/timeline.service';
+import { TranscodingService } from 'src/services/transcoding.service';
 import { TrashService } from 'src/services/trash.service';
 import { UserAdminService } from 'src/services/user-admin.service';
 import { UserService } from 'src/services/user.service';
@@ -61,6 +63,7 @@ export const services = [
   DatabaseService,
   DownloadService,
   DuplicateService,
+  HlsService,
   JobService,
   LibraryService,
   MaintenanceService,
@@ -89,6 +92,7 @@ export const services = [
   TagService,
   TelemetryService,
   TimelineService,
+  TranscodingService,
   TrashService,
   UserAdminService,
   UserService,

server/src/services/queue.service.spec.ts

@@ -41,6 +41,7 @@ describe(QueueService.name, () => {
         { name: JobName.PersonCleanup },
         { name: JobName.MemoryCleanup },
         { name: JobName.SessionCleanup },
+        { name: JobName.HlsSessionCleanup },
         { name: JobName.AuditTableCleanup },
         { name: JobName.MemoryGenerate },
         { name: JobName.UserSyncUsage },

server/src/services/queue.service.ts

@@ -269,6 +269,7 @@ export class QueueService extends BaseService {
         { name: JobName.PersonCleanup },
         { name: JobName.MemoryCleanup },
         { name: JobName.SessionCleanup },
+        { name: JobName.HlsSessionCleanup },
         { name: JobName.AuditTableCleanup },
       );
     }

server/src/services/server.service.spec.ts

@@ -148,6 +148,7 @@ describe(ServerService.name, () => {
         configFile: false,
         trash: true,
         email: false,
+        realtimeTranscoding: false,
       });
       expect(mocks.systemMetadata.get).toHaveBeenCalled();
     });

server/src/services/server.service.ts

@@ -86,7 +86,7 @@ export class ServerService extends BaseService {
   }
 
   async getFeatures(): Promise<ServerFeaturesDto> {
-    const { reverseGeocoding, metadata, map, machineLearning, trash, oauth, passwordLogin, notifications } =
+    const { reverseGeocoding, metadata, map, machineLearning, trash, oauth, passwordLogin, notifications, ffmpeg } =
       await this.getConfig({ withCache: false });
     const { configFile } = this.configRepository.getEnv();
 
@@ -106,6 +106,7 @@ export class ServerService extends BaseService {
       passwordLogin: passwordLogin.enabled,
       configFile: !!configFile,
       email: notifications.smtp.enabled,
+      realtimeTranscoding: ffmpeg.realtime.enabled,
     };
   }
 

server/src/services/system-config.service.spec.ts

@@ -1,5 +1,6 @@
 import { BadRequestException } from '@nestjs/common';
 import { defaults, SystemConfig } from 'src/config';
+import { ReleaseChannel } from 'src/dtos/system-config.dto';
 import {
   AudioCodec,
   Colorspace,
@@ -72,6 +73,9 @@ const updatedConfig = Object.freeze<SystemConfig>({
     accel: TranscodeHardwareAcceleration.Disabled,
     accelDecode: true,
     tonemap: ToneMapping.Hable,
+    realtime: {
+      enabled: false,
+    },
   },
   logging: {
     enabled: true,
@@ -184,6 +188,7 @@ const updatedConfig = Object.freeze<SystemConfig>({
   },
   newVersionCheck: {
     enabled: true,
+    channel: ReleaseChannel.Stable,
   },
   trash: {
     enabled: true,

server/src/services/transcoding.service.spec.ts

@@ -0,0 +1,539 @@
+import {
+  HLS_BACKPRESSURE_PAUSE_SEGMENTS,
+  HLS_BACKPRESSURE_RESUME_SEGMENTS,
+  HLS_CLEANUP_INTERVAL_MS,
+  HLS_INACTIVITY_TIMEOUT_MS,
+  HLS_LEASE_DURATION_MS,
+} from 'src/constants';
+import { TranscodingService } from 'src/services/transcoding.service';
+import { VIDEO_STREAM_SESSION_PK_CONSTRAINT } from 'src/utils/database';
+import { eiffelTower, train, waterfall } from 'test/fixtures/media.stub';
+import { mockSpawn, newTestService, ServiceMocks } from 'test/utils';
+import { vi } from 'vitest';
+
+describe(TranscodingService.name, () => {
+  let sut: TranscodingService;
+  let mocks: ServiceMocks;
+
+  const sessionId = 'session-1';
+  const assetId = 'asset-1';
+  const ownerId = 'user-1';
+
+  const completeSegment = (index: number) => {
+    const listener = vi.mocked(mocks.storage.watchDir).mock.lastCall?.[1];
+    expect(listener).toBeDefined();
+    listener!('rename', `seg_${index}.m4s`);
+  };
+
+  const completeSegmentsThrough = (start: number, end: number) => {
+    for (let i = start; i <= end; i++) {
+      completeSegment(i);
+    }
+  };
+
+  beforeEach(() => {
+    ({ sut, mocks } = newTestService(TranscodingService));
+    mocks.systemMetadata.get.mockResolvedValue({ ffmpeg: { realtime: { enabled: true } } });
+    mocks.videoStream.getForTranscoding.mockResolvedValue(eiffelTower);
+  });
+
+  describe('onSessionRequest', () => {
+    it('creates the session row and emits HlsSessionResult on success', async () => {
+      await sut.onSessionRequest({ sessionId, assetId, ownerId });
+
+      expect(mocks.videoStream.createSession).toHaveBeenCalledWith({
+        id: sessionId,
+        assetId,
+        expiresAt: expect.any(Date),
+      });
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsSessionResult', { sessionId });
+    });
+
+    it('treats a primary-key conflict as a no-op for replay tolerance', async () => {
+      mocks.videoStream.createSession.mockRejectedValue({ constraint_name: VIDEO_STREAM_SESSION_PK_CONSTRAINT });
+
+      await sut.onSessionRequest({ sessionId, assetId, ownerId });
+
+      expect(mocks.websocket.serverSend).not.toHaveBeenCalled();
+    });
+
+    it('emits HlsSessionResult with an error on other DB failures', async () => {
+      mocks.videoStream.createSession.mockRejectedValue(new Error('database is down'));
+
+      await sut.onSessionRequest({ sessionId, assetId, ownerId });
+
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsSessionResult', {
+        sessionId,
+        error: 'Failed to create HLS session',
+      });
+    });
+  });
+
+  describe('onSessionEnd', () => {
+    it('removes the session, kills the transcode, and deletes the dir + DB row', async () => {
+      await sut.onSessionRequest({ sessionId, assetId, ownerId });
+      const process = mockSpawn(0, '', '');
+      mocks.process.spawn.mockReturnValue(process);
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 0 });
+
+      await sut.onSessionEnd({ sessionId });
+
+      expect(process.kill).toHaveBeenCalled();
+      expect(mocks.storage.unlinkDir).toHaveBeenCalled();
+      expect(mocks.videoStream.deleteSession).toHaveBeenCalledWith(sessionId);
+    });
+
+    it('is a no-op when the session is unknown', async () => {
+      await sut.onSessionEnd({ sessionId: 'never-created' });
+
+      expect(mocks.videoStream.deleteSession).not.toHaveBeenCalled();
+      expect(mocks.storage.unlinkDir).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('onHeartbeat', () => {
+    it('extends the DB lease when remaining time falls below half', async () => {
+      vi.useFakeTimers();
+      try {
+        await sut.onSessionRequest({ sessionId, assetId, ownerId });
+        vi.setSystemTime(Date.now() + HLS_LEASE_DURATION_MS / 2 + 1);
+
+        await sut.onHeartbeat({ sessionId });
+
+        expect(mocks.videoStream.extendSession).toHaveBeenCalledWith(sessionId, expect.any(Date));
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('does not extend the lease while it is still fresh', async () => {
+      await sut.onSessionRequest({ sessionId, assetId, ownerId });
+
+      await sut.onHeartbeat({ sessionId });
+
+      expect(mocks.videoStream.extendSession).not.toHaveBeenCalled();
+    });
+
+    it('is a no-op when the session is unknown', async () => {
+      await sut.onHeartbeat({ sessionId: 'never-created' });
+
+      expect(mocks.videoStream.extendSession).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('onSegmentRequest', () => {
+    beforeEach(async () => {
+      await sut.onSessionRequest({ sessionId, assetId, ownerId });
+      mocks.websocket.serverSend.mockClear();
+    });
+
+    it('spawns FFmpeg on the first request', async () => {
+      mocks.process.spawn.mockReturnValue(mockSpawn(0, '', ''));
+
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 0 });
+
+      expect(mocks.process.spawn).toHaveBeenCalledTimes(1);
+      expect(mocks.process.spawn).toHaveBeenCalledWith('ffmpeg', expect.any(Array), expect.any(Object));
+    });
+
+    it('kills and respawns when the variant changes', async () => {
+      const first = mockSpawn(0, '', '');
+      const second = mockSpawn(0, '', '');
+      mocks.process.spawn.mockReturnValueOnce(first).mockReturnValueOnce(second);
+
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 0 });
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 1, segmentIndex: 0 });
+
+      expect(first.kill).toHaveBeenCalled();
+      expect(mocks.process.spawn).toHaveBeenCalledTimes(2);
+    });
+
+    it('kills and respawns when seeking before the start segment', async () => {
+      const first = mockSpawn(0, '', '');
+      const second = mockSpawn(0, '', '');
+      mocks.process.spawn.mockReturnValueOnce(first).mockReturnValueOnce(second);
+
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 5 });
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 2 });
+
+      expect(first.kill).toHaveBeenCalled();
+      expect(mocks.process.spawn).toHaveBeenCalledTimes(2);
+    });
+
+    it('kills and respawns when the requested segment is too far ahead', async () => {
+      const first = mockSpawn(0, '', '');
+      const second = mockSpawn(0, '', '');
+      mocks.process.spawn.mockReturnValueOnce(first).mockReturnValueOnce(second);
+
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 0 });
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 5 });
+
+      expect(first.kill).toHaveBeenCalled();
+      expect(mocks.process.spawn).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not spawn when the session is unknown', async () => {
+      await sut.onSegmentRequest({ sessionId: 'never-created', assetId, variantIndex: 0, segmentIndex: 0 });
+
+      expect(mocks.process.spawn).not.toHaveBeenCalled();
+    });
+
+    it('accepts segments from a restart after the previous ffmpeg exited on its own', async () => {
+      const first = mockSpawn(0, '', '');
+      const second = mockSpawn(0, '', '');
+      mocks.process.spawn.mockReturnValueOnce(first).mockReturnValueOnce(second);
+
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 10 });
+      completeSegment(10);
+
+      const onCalls = vi.mocked(first.on).mock.calls as unknown as [string, (code: number) => void][];
+      const exitHandler = onCalls.find(([event]) => event === 'exit')?.[1];
+      exitHandler?.(0);
+
+      mocks.websocket.serverSend.mockClear();
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 2 });
+      completeSegment(2);
+
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsSegmentResult', {
+        sessionId,
+        variantIndex: 0,
+        segmentIndex: 2,
+      });
+    });
+  });
+
+  describe('backpressure', () => {
+    let proc: ReturnType<typeof mockSpawn>;
+
+    beforeEach(async () => {
+      proc = mockSpawn(0, '', '');
+      mocks.process.spawn.mockReturnValue(proc);
+
+      await sut.onSessionRequest({ sessionId, assetId, ownerId });
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 0 });
+    });
+
+    it('pauses the transcode once the lead exceeds HLS_BACKPRESSURE_PAUSE_SEGMENTS', async () => {
+      completeSegmentsThrough(0, HLS_BACKPRESSURE_PAUSE_SEGMENTS + 1);
+
+      await sut.onHeartbeat({ sessionId, segmentIndex: 0 });
+
+      expect(proc.kill).toHaveBeenCalledWith('SIGSTOP');
+    });
+
+    it('does not pause when the lead equals the pause threshold', async () => {
+      completeSegmentsThrough(0, HLS_BACKPRESSURE_PAUSE_SEGMENTS);
+
+      await sut.onHeartbeat({ sessionId, segmentIndex: 0 });
+
+      expect(proc.kill).not.toHaveBeenCalled();
+    });
+
+    it('resumes once the lead drops below HLS_BACKPRESSURE_RESUME_SEGMENTS', async () => {
+      completeSegmentsThrough(0, HLS_BACKPRESSURE_PAUSE_SEGMENTS + 1);
+      await sut.onHeartbeat({ sessionId, segmentIndex: 0 });
+      expect(proc.kill).toHaveBeenCalledWith('SIGSTOP');
+      vi.mocked(proc.kill).mockClear();
+
+      const requested = HLS_BACKPRESSURE_PAUSE_SEGMENTS + 1 - (HLS_BACKPRESSURE_RESUME_SEGMENTS - 1);
+      await sut.onHeartbeat({ sessionId, segmentIndex: requested });
+
+      expect(proc.kill).toHaveBeenCalledWith('SIGCONT');
+    });
+
+    it('stays paused while the lead is in the dead-band', async () => {
+      completeSegmentsThrough(0, HLS_BACKPRESSURE_PAUSE_SEGMENTS + 1);
+      await sut.onHeartbeat({ sessionId, segmentIndex: 0 });
+      vi.mocked(proc.kill).mockClear();
+
+      const requested = HLS_BACKPRESSURE_PAUSE_SEGMENTS + 1 - HLS_BACKPRESSURE_RESUME_SEGMENTS;
+      await sut.onHeartbeat({ sessionId, segmentIndex: requested });
+
+      expect(proc.kill).not.toHaveBeenCalled();
+    });
+
+    it('is a no-op when no segment has completed yet', async () => {
+      await sut.onHeartbeat({ sessionId, segmentIndex: 0 });
+
+      expect(proc.kill).not.toHaveBeenCalled();
+    });
+
+    it('is a no-op when the heartbeat omits segmentIndex', async () => {
+      completeSegmentsThrough(0, HLS_BACKPRESSURE_PAUSE_SEGMENTS + 1);
+
+      await sut.onHeartbeat({ sessionId });
+
+      expect(proc.kill).not.toHaveBeenCalled();
+    });
+
+    it('resumes the paused transcode when the client requests the next in-range segment', async () => {
+      completeSegmentsThrough(0, HLS_BACKPRESSURE_PAUSE_SEGMENTS + 1);
+      await sut.onHeartbeat({ sessionId, segmentIndex: 0 });
+      expect(proc.kill).toHaveBeenCalledWith('SIGSTOP');
+      vi.mocked(proc.kill).mockClear();
+
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex: 1 });
+
+      expect(proc.kill).toHaveBeenCalledWith('SIGCONT');
+      expect(mocks.process.spawn).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not re-pause a freshly spawned transcode after a seek-driven restart', async () => {
+      const newProc = mockSpawn(0, '', '');
+      mocks.process.spawn.mockReturnValueOnce(newProc);
+
+      completeSegmentsThrough(0, HLS_BACKPRESSURE_PAUSE_SEGMENTS + 1);
+      await sut.onHeartbeat({ sessionId, segmentIndex: 0 });
+      expect(proc.kill).toHaveBeenCalledWith('SIGSTOP');
+
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 1, segmentIndex: 0 });
+      vi.mocked(newProc.kill).mockClear();
+
+      await sut.onHeartbeat({ sessionId, segmentIndex: 0 });
+
+      expect(newProc.kill).not.toHaveBeenCalled();
+    });
+
+    it('ignores stale segment events from the prior transcode after a backward seek', async () => {
+      const newProc = mockSpawn(0, '', '');
+      mocks.process.spawn.mockReturnValueOnce(newProc);
+
+      const completedAhead = HLS_BACKPRESSURE_PAUSE_SEGMENTS + 5;
+      completeSegmentsThrough(1, completedAhead); // seg_0 was emitted in beforeEach
+
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 1, segmentIndex: 0 });
+
+      vi.mocked(newProc.kill).mockClear();
+      mocks.websocket.serverSend.mockClear();
+      completeSegment(completedAhead + 1);
+
+      expect(mocks.websocket.serverSend).not.toHaveBeenCalledWith(
+        'HlsSegmentResult',
+        expect.objectContaining({ segmentIndex: completedAhead + 1 }),
+      );
+      expect(newProc.kill).not.toHaveBeenCalled();
+
+      completeSegment(0);
+      expect(mocks.websocket.serverSend).toHaveBeenCalledWith(
+        'HlsSegmentResult',
+        expect.objectContaining({ segmentIndex: 0 }),
+      );
+    });
+  });
+
+  describe('inactivity sweeper', () => {
+    it('reaps a session whose last activity exceeds the inactivity timeout', async () => {
+      vi.useFakeTimers();
+      try {
+        await sut.onSessionRequest({ sessionId, assetId, ownerId });
+        mocks.websocket.serverSend.mockClear();
+        await vi.advanceTimersByTimeAsync(HLS_INACTIVITY_TIMEOUT_MS + HLS_CLEANUP_INTERVAL_MS);
+
+        expect(mocks.websocket.serverSend).toHaveBeenCalledWith('HlsSessionEnd', { sessionId });
+        expect(mocks.videoStream.deleteSession).toHaveBeenCalledWith(sessionId);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+  });
+
+  describe('onShutdown', () => {
+    it('ends every active session', async () => {
+      await sut.onSessionRequest({ sessionId: 'session-a', assetId, ownerId });
+      await sut.onSessionRequest({ sessionId: 'session-b', assetId, ownerId });
+
+      await sut.onShutdown();
+
+      expect(mocks.videoStream.deleteSession).toHaveBeenCalledWith('session-a');
+      expect(mocks.videoStream.deleteSession).toHaveBeenCalledWith('session-b');
+    });
+  });
+
+  describe('onHlsSessionCleanup', () => {
+    it('reaps DB-expired sessions under a database lock', async () => {
+      mocks.database.withLock.mockImplementation(async (_, fn) => fn());
+      mocks.videoStream.getExpiredSessions.mockResolvedValue([
+        { id: 'expired-1', ownerId: 'user-a' },
+        { id: 'expired-2', ownerId: 'user-b' },
+      ]);
+
+      await sut.onHlsSessionCleanup();
+
+      expect(mocks.videoStream.deleteSession).toHaveBeenCalledWith('expired-1');
+      expect(mocks.videoStream.deleteSession).toHaveBeenCalledWith('expired-2');
+      expect(mocks.storage.unlinkDir).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('FFmpeg full command', () => {
+    const baseCommand = [
+      '-nostdin',
+      '-nostats',
+      '-i',
+      'eiffel-tower.mp4',
+      '-map',
+      '0:0',
+      '-map_metadata',
+      '-1',
+      '-map',
+      '0:1',
+      '-g',
+      '50',
+      '-keyint_min',
+      '50',
+      '-crf',
+      '23',
+      '-copyts',
+      '-r',
+      '50130000/2012441',
+      '-avoid_negative_ts',
+      'disabled',
+      '-f',
+      'hls',
+      '-hls_time',
+      '2',
+      '-hls_list_size',
+      '0',
+      '-hls_segment_type',
+      'fmp4',
+      '-hls_fmp4_init_filename',
+      'init.mp4',
+      '-hls_segment_options',
+      'movflags=+frag_discont',
+      '-hls_flags',
+      'temp_file',
+      '-start_number',
+      '0',
+    ];
+
+    it.each([
+      {
+        variantIndex: 6,
+        expected: [
+          ...baseCommand,
+          '-c:v',
+          'libsvtav1',
+          '-c:a',
+          'aac',
+          '-preset',
+          '12',
+          '-svtav1-params',
+          'hierarchical-levels=3:lookahead=0:enable-tf=0:mbr=4000k',
+          '-hls_segment_filename',
+          '/data/encoded-video/user-1/se/ss/session-1/6/seg_%d.m4s',
+          '/data/encoded-video/user-1/se/ss/session-1/6/playlist.m3u8',
+        ].sort(),
+      },
+      {
+        variantIndex: 4,
+        expected: [
+          ...baseCommand,
+          '-c:v',
+          'hevc',
+          '-c:a',
+          'aac',
+          '-tag:v',
+          'hvc1',
+          '-preset',
+          'ultrafast',
+          '-maxrate',
+          '2500k',
+          '-bufsize',
+          '5000k',
+          '-x265-params',
+          'no-scenecut=1:no-open-gop=1',
+          '-vf',
+          'scale=720:-2',
+          '-hls_segment_filename',
+          '/data/encoded-video/user-1/se/ss/session-1/4/seg_%d.m4s',
+          '/data/encoded-video/user-1/se/ss/session-1/4/playlist.m3u8',
+        ].sort(),
+      },
+      {
+        variantIndex: 2,
+        expected: [
+          ...baseCommand,
+          '-c:v',
+          'h264',
+          '-c:a',
+          'aac',
+          '-preset',
+          'ultrafast',
+          '-maxrate',
+          '2500k',
+          '-bufsize',
+          '5000k',
+          '-sc_threshold:v',
+          '0',
+          '-vf',
+          'scale=480:-2',
+          '-hls_segment_filename',
+          '/data/encoded-video/user-1/se/ss/session-1/2/seg_%d.m4s',
+          '/data/encoded-video/user-1/se/ss/session-1/2/playlist.m3u8',
+        ].sort(),
+      },
+    ])('builds the expected FFmpeg command for $codec (variant $variantIndex)', async ({ variantIndex, expected }) => {
+      mocks.process.spawn.mockReturnValue(mockSpawn(0, '', ''));
+
+      await sut.onSessionRequest({ sessionId, assetId, ownerId });
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex, segmentIndex: 0 });
+
+      expect(mocks.process.spawn.mock.calls[0][1].toSorted()).toEqual(expected);
+    });
+  });
+
+  describe('FFmpeg seek per segment', () => {
+    const eiffelSeeks = [
+      0, 1.987_15, 3.994_372_222_222_222, 6.001_594_444_444_444, 8.008_816_666_666_666, 10.016_038_888_888_888,
+      12.023_261_111_111_111, 14.030_483_333_333_333, 16.037_705_555_555_554, 18.044_927_777_777_776,
+      20.052_149_999_999_997, 22.059_372_222_222_223,
+    ];
+    const waterfallSeeks = [
+      0, 1.994_642_826_321_467, 4.006_047_357_065_803, 6.017_451_887_810_139_5, 8.028_856_418_554_476,
+      10.040_260_949_298_812,
+    ];
+    const trainSeeks = [
+      0, 1.991_666_666_666_666_7, 3.991_666_666_666_666_7, 5.991_666_666_666_666, 7.991_666_666_666_666,
+      9.991_666_666_666_667, 11.991_666_666_666_667, 13.991_666_666_666_667, 15.991_666_666_666_667,
+      17.991_666_666_666_667, 19.991_666_666_666_667,
+    ];
+    const cases = [
+      ...eiffelSeeks.map((expected, segmentIndex) => ({
+        name: `${eiffelTower.originalPath} K=${segmentIndex}`,
+        fixture: eiffelTower,
+        segmentIndex,
+        expected,
+      })),
+      ...waterfallSeeks.map((expected, segmentIndex) => ({
+        name: `${waterfall.originalPath} K=${segmentIndex}`,
+        fixture: waterfall,
+        segmentIndex,
+        expected,
+      })),
+      ...trainSeeks.map((expected, segmentIndex) => ({
+        name: `${train.originalPath} K=${segmentIndex}`,
+        fixture: train,
+        segmentIndex,
+        expected,
+      })),
+    ];
+
+    it.each(cases)('$name', async ({ fixture, segmentIndex, expected }) => {
+      mocks.videoStream.getForTranscoding.mockResolvedValue(fixture);
+      mocks.process.spawn.mockReturnValue(mockSpawn(0, '', ''));
+
+      await sut.onSessionRequest({ sessionId, assetId, ownerId });
+      await sut.onSegmentRequest({ sessionId, assetId, variantIndex: 0, segmentIndex });
+
+      const args = mocks.process.spawn.mock.calls[0][1] as string[];
+      if (expected === 0) {
+        expect(args).toEqual(expect.arrayContaining(['-copyts', '-avoid_negative_ts', 'disabled']));
+        expect(args).not.toContain('-ss');
+      } else {
+        expect(args).toEqual(
+          expect.arrayContaining(['-ss', String(expected), '-copyts', '-avoid_negative_ts', 'disabled']),
+        );
+      }
+    });
+  });
+});

server/src/services/transcoding.service.ts

@@ -0,0 +1,387 @@
+import { Injectable } from '@nestjs/common';
+import { ChildProcess } from 'node:child_process';
+import { join } from 'node:path';
+import {
+  HLS_BACKPRESSURE_PAUSE_SEGMENTS,
+  HLS_BACKPRESSURE_RESUME_SEGMENTS,
+  HLS_CLEANUP_INTERVAL_MS,
+  HLS_INACTIVITY_TIMEOUT_MS,
+  HLS_LEASE_DURATION_MS,
+  HLS_SEGMENT_DURATION,
+  HLS_SEGMENT_FILENAME_REGEX,
+  HLS_VARIANTS,
+} from 'src/constants';
+import { StorageCore } from 'src/cores/storage.core';
+import { OnEvent, OnJob } from 'src/decorators';
+import { DatabaseLock, ImmichWorker, JobName, QueueName, TranscodeTarget } from 'src/enum';
+import { ArgOf } from 'src/repositories/event.repository';
+import { BaseService } from 'src/services/base.service';
+import { VideoInterfaces } from 'src/types';
+import { isVideoStreamSessionPkConstraint } from 'src/utils/database';
+import { BaseConfig } from 'src/utils/media';
+
+type Session = {
+  assetId: string;
+  expiresAt: Date;
+  id: string;
+  lastActivityTime: Date;
+  lastClientRequestedSegment: number | null;
+  lastCompletedSegment: number | null;
+  ownerId: string;
+  paused: boolean;
+  process: ChildProcess | null;
+  startSegment: number | null;
+  variantIndex: number | null;
+};
+
+@Injectable()
+export class TranscodingService extends BaseService {
+  private sessions = new Map<string, Session>();
+  private videoInterfaces: VideoInterfaces = { dri: [], mali: false };
+  private cleanupInterval: NodeJS.Timeout | null = null;
+
+  @OnEvent({ name: 'AppBootstrap', workers: [ImmichWorker.Microservices] })
+  async onBootstrap() {
+    const [videoInterfaces] = await Promise.all([this.storageCore.getVideoInterfaces(), this.removeExpiredSessions()]);
+    this.videoInterfaces = videoInterfaces;
+  }
+
+  @OnEvent({ name: 'AppShutdown', workers: [ImmichWorker.Microservices] })
+  onShutdown() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    return Promise.all([...this.sessions.values()].map(({ id }) => this.onSessionEnd({ sessionId: id })));
+  }
+
+  @OnJob({ name: JobName.HlsSessionCleanup, queue: QueueName.BackgroundTask })
+  onHlsSessionCleanup() {
+    return this.removeExpiredSessions();
+  }
+
+  @OnEvent({ name: 'HlsSessionRequest', server: true, workers: [ImmichWorker.Microservices] })
+  async onSessionRequest({ assetId, sessionId, ownerId }: ArgOf<'HlsSessionRequest'>) {
+    try {
+      const expiresAt = new Date(Date.now() + HLS_LEASE_DURATION_MS);
+      await this.videoStreamRepository.createSession({ id: sessionId, assetId, expiresAt });
+      this.sessions.set(sessionId, {
+        assetId,
+        expiresAt,
+        id: sessionId,
+        lastActivityTime: new Date(),
+        lastClientRequestedSegment: null,
+        lastCompletedSegment: null,
+        ownerId,
+        paused: false,
+        process: null,
+        startSegment: null,
+        variantIndex: null,
+      });
+      this.cleanupInterval ??= setInterval(() => void this.removeInactiveSessions(), HLS_CLEANUP_INTERVAL_MS);
+      this.websocketRepository.serverSend('HlsSessionResult', { sessionId });
+    } catch (error) {
+      // If insertion failed due to a PK constraint, another worker has already created a session for this ID.
+      if (!isVideoStreamSessionPkConstraint(error)) {
+        this.logger.error(`Failed to create HLS session ${sessionId}: ${error}`);
+        this.websocketRepository.serverSend('HlsSessionResult', { sessionId, error: 'Failed to create HLS session' });
+      }
+    }
+  }
+
+  @OnEvent({ name: 'HlsSessionEnd', server: true, workers: [ImmichWorker.Microservices] })
+  async onSessionEnd({ sessionId }: ArgOf<'HlsSessionEnd'>) {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return;
+    }
+    this.sessions.delete(sessionId);
+    if (this.cleanupInterval && this.sessions.size === 0) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.stopTranscode(session);
+    await this.removeSessionDir(session);
+    await this.videoStreamRepository.deleteSession(sessionId);
+  }
+
+  @OnEvent({ name: 'HlsHeartbeat', server: true, workers: [ImmichWorker.Microservices] })
+  async onHeartbeat({ sessionId, segmentIndex }: ArgOf<'HlsHeartbeat'>) {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return;
+    }
+
+    session.lastActivityTime = new Date();
+
+    if (segmentIndex !== undefined) {
+      session.lastClientRequestedSegment = segmentIndex;
+      this.applyBackpressure(session);
+    }
+
+    const remaining = session.expiresAt.getTime() - Date.now();
+    if (remaining < HLS_LEASE_DURATION_MS / 2) {
+      session.expiresAt = new Date(Date.now() + HLS_LEASE_DURATION_MS);
+      await this.videoStreamRepository.extendSession(sessionId, session.expiresAt);
+    }
+  }
+
+  @OnEvent({ name: 'HlsSegmentRequest', server: true, workers: [ImmichWorker.Microservices] })
+  async onSegmentRequest({ sessionId, variantIndex, segmentIndex }: ArgOf<'HlsSegmentRequest'>) {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return;
+    }
+
+    session.variantIndex ??= variantIndex;
+    session.startSegment ??= segmentIndex;
+    const curSegment = session.lastCompletedSegment === null ? session.startSegment : session.lastCompletedSegment + 1;
+    const needsRestart =
+      session.variantIndex !== variantIndex || segmentIndex < session.startSegment || segmentIndex > curSegment + 1;
+    if (needsRestart) {
+      this.stopTranscode(session);
+      session.variantIndex = variantIndex;
+      session.startSegment = segmentIndex;
+    } else if (session.process) {
+      this.resumeTranscode(session);
+      return;
+    }
+
+    const process = await this.startTranscode(session, variantIndex, segmentIndex);
+    if (process) {
+      session.process = process;
+    }
+  }
+
+  private applyBackpressure(session: Session) {
+    if (session.lastCompletedSegment === null || session.lastClientRequestedSegment === null) {
+      return;
+    }
+    const lead = session.lastCompletedSegment - session.lastClientRequestedSegment;
+    this.logger.debug(`Session ${session.id} lead is ${lead} segments`);
+    if (!session.paused && lead > HLS_BACKPRESSURE_PAUSE_SEGMENTS) {
+      this.pauseTranscode(session);
+    } else if (session.paused && lead < HLS_BACKPRESSURE_RESUME_SEGMENTS) {
+      this.resumeTranscode(session);
+    }
+  }
+
+  private async startTranscode(session: Session, variantIndex: number, startSegment: number) {
+    const { ffmpeg } = await this.getConfig({ withCache: true });
+
+    const asset = await this.videoStreamRepository.getForTranscoding(session.assetId);
+    if (!asset) {
+      this.logger.error(`Asset ${session.assetId} not found for HLS transcoding`);
+      return;
+    }
+
+    if (session.variantIndex !== variantIndex || session.startSegment !== startSegment) {
+      return;
+    }
+
+    const variant = HLS_VARIANTS[variantIndex];
+    if (!variant) {
+      this.logger.error(`Variant ${variantIndex} out of range for asset ${session.assetId}`);
+      await this.failSession(session, `Invalid variant index ${variantIndex}`);
+      return;
+    }
+
+    const variantDir = StorageCore.getHlsVariantFolder({
+      ownerId: session.ownerId,
+      sessionId: session.id,
+      variantIndex,
+    });
+    this.storageRepository.mkdirSync(variantDir);
+
+    // Encoder runs at fps = packetCount × timeBase / totalDuration with
+    // gop = ceil(SEGMENT_DURATION × fps). To start segment K's content at
+    // exactly cfr slot K × gop, seek to the midpoint between slots K×gop−1 and
+    // K×gop. accurate_seek's "discard < target" then keeps the source frame
+    // that quantizes to slot K×gop and discards the one quantizing to K×gop−1.
+    const fps = (asset.packets.packetCount * asset.videoStream.timeBase) / asset.packets.totalDuration;
+    const gop = Math.ceil(HLS_SEGMENT_DURATION * fps);
+    const seekSeconds = startSegment > 0 ? (startSegment * gop - 0.5) / fps : 0;
+
+    let config;
+    try {
+      config = BaseConfig.create(
+        {
+          ...ffmpeg,
+          targetVideoCodec: variant.codec,
+          targetResolution: String(variant.resolution),
+          maxBitrate: `${Math.round(variant.bitrate / 1000)}k`,
+          gopSize: gop,
+        },
+        this.videoInterfaces,
+        { strictGop: true, lowLatency: true },
+      );
+    } catch (error: any) {
+      this.logger.error(
+        `Failed to create transcode config for variant ${variantIndex} asset ${session.assetId}: ${error?.message ?? error}`,
+      );
+      await this.failSession(session, `Failed to start transcode: ${error?.message ?? 'unknown error'}`);
+      return;
+    }
+    const args = config.getHlsCommand(
+      {
+        initFilename: 'init.mp4',
+        inputPath: asset.originalPath,
+        packetCount: asset.packets.packetCount,
+        playlistFilename: join(variantDir, 'playlist.m3u8'),
+        seekSeconds,
+        segmentDuration: HLS_SEGMENT_DURATION,
+        segmentFilename: join(variantDir, 'seg_%d.m4s'),
+        startSegment,
+        target: TranscodeTarget.All,
+        timeBase: asset.videoStream.timeBase,
+        totalDuration: asset.packets.totalDuration,
+      },
+      asset.videoStream,
+      asset.audioStream ?? undefined,
+    );
+    this.logger.log(
+      `Starting HLS transcode for asset ${session.assetId} variant ${variantIndex} with command: ffmpeg ${args.join(' ')}`,
+    );
+    const process = this.processRepository.spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    this.attachProcessHandlers(process, session, variantIndex);
+    return process;
+  }
+
+  private failSession(session: Session, error: string) {
+    this.websocketRepository.serverSend('HlsSessionResult', { sessionId: session.id, error });
+    return this.onSessionEnd({ sessionId: session.id });
+  }
+
+  private attachProcessHandlers(process: ChildProcess, session: Session, variantIndex: number) {
+    let stderr = '';
+    const variantDir = StorageCore.getHlsVariantFolder({
+      ownerId: session.ownerId,
+      sessionId: session.id,
+      variantIndex,
+    });
+
+    // hlsenc writes each segment as `seg_K.m4s.tmp` then renames to
+    // `seg_K.m4s`. The rename event fires the moment the renamed file is
+    // observable — the only signal we need to tell the API worker the
+    // segment is ready to serve.
+    const watcher = this.storageRepository.watchDir(variantDir, (eventType, filename) => {
+      if (eventType !== 'rename' || !filename || session.process !== process) {
+        return;
+      }
+      const match = HLS_SEGMENT_FILENAME_REGEX.exec(filename);
+      if (!match) {
+        return;
+      }
+      const segmentIndex = Number.parseInt(match[1]);
+      const expected = session.lastCompletedSegment === null ? session.startSegment : session.lastCompletedSegment + 1;
+      // Ignore stale events from old process after seek
+      if (expected === null || segmentIndex !== expected) {
+        return;
+      }
+      session.lastCompletedSegment = segmentIndex;
+      this.websocketRepository.serverSend('HlsSegmentResult', {
+        sessionId: session.id,
+        variantIndex,
+        segmentIndex,
+      });
+      this.applyBackpressure(session);
+    });
+    watcher.on('error', (error) => {
+      this.logger.error(`watcher error for ${variantDir}: ${error}`);
+    });
+
+    process.stderr!.on('data', (chunk: Buffer) => {
+      if (session.process !== process) {
+        return;
+      }
+      stderr += chunk.toString();
+    });
+
+    process.on('exit', (code) => {
+      watcher.close();
+      if (session.process !== process || session.variantIndex !== variantIndex) {
+        return;
+      }
+      session.paused = false;
+      session.process = null;
+      session.lastCompletedSegment = null;
+      if (code) {
+        this.logger.error(
+          `FFmpeg exited with code ${code} for variant ${variantIndex} asset ${session.assetId}\n${stderr}`,
+        );
+        void this.failSession(session, `Transcoding process exited unexpectedly with code ${code}`).catch((error) =>
+          this.logger.error(`Failed to end session ${session.id} after ffmpeg exit: ${error}`),
+        );
+      }
+    });
+  }
+
+  private stopTranscode(session: Session) {
+    if (!session.process) {
+      return;
+    }
+    // SIGTERM makes it rename .tmp segments to .m4s even if they're still incomplete
+    session.process.kill('SIGKILL');
+    session.process = null;
+    session.lastCompletedSegment = null;
+    session.paused = false;
+    this.logger.debug(`Stopped transcoding for session ${session.id}`);
+  }
+
+  private pauseTranscode(session: Session) {
+    if (session.paused || !session.process) {
+      return;
+    }
+    session.process.kill('SIGSTOP');
+    session.paused = true;
+    this.logger.debug(`Paused transcoding for session ${session.id}`);
+  }
+
+  private resumeTranscode(session: Session) {
+    if (!session.paused || !session.process) {
+      return;
+    }
+    session.process.kill('SIGCONT');
+    session.paused = false;
+    this.logger.debug(`Resumed transcoding for session ${session.id}`);
+  }
+
+  private async removeSessionDir(session: { ownerId: string; id: string }) {
+    const dir = StorageCore.getHlsSessionFolder({ ownerId: session.ownerId, sessionId: session.id });
+    try {
+      await this.storageRepository.unlinkDir(dir, { recursive: true, force: true });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
+        throw error;
+      }
+      this.logger.warn(`Session dir ${dir} does not exist.`);
+    }
+  }
+
+  private removeInactiveSessions() {
+    const cutoff = Date.now() - HLS_INACTIVITY_TIMEOUT_MS;
+    const inactiveSessions = [...this.sessions.values()].filter((s) => s.lastActivityTime.getTime() < cutoff);
+    return Promise.all(
+      inactiveSessions.map(async (session) => {
+        try {
+          this.websocketRepository.serverSend('HlsSessionEnd', { sessionId: session.id });
+          await this.onSessionEnd({ sessionId: session.id });
+        } catch (error) {
+          this.logger.error(`Failed to sweep inactive HLS session ${session.id}: ${error}`);
+        }
+      }),
+    );
+  }
+
+  private removeExpiredSessions() {
+    return this.databaseRepository.withLock(DatabaseLock.HlsSessionCleanup, async () => {
+      const expiredSessions = await this.videoStreamRepository.getExpiredSessions();
+      await Promise.all(
+        expiredSessions.map(async (session) => {
+          await this.removeSessionDir(session);
+          await this.videoStreamRepository.deleteSession(session.id);
+        }),
+      );
+    });
+  }
+}

server/src/services/version.service.spec.ts

@@ -2,6 +2,7 @@ import { DateTime } from 'luxon';
 import { SemVer } from 'semver';
 import { defaults } from 'src/config';
 import { serverVersion } from 'src/constants';
+import { ReleaseChannel } from 'src/dtos/system-config.dto';
 import { CronJob, JobName, JobStatus, SystemMetadataKey } from 'src/enum';
 import { VersionService } from 'src/services/version.service';
 import { factory } from 'test/small.factory';
@@ -22,6 +23,17 @@ describe(VersionService.name, () => {
     mocks.cron.update.mockResolvedValue();
   });
 
+  beforeAll(() => {
+    vitest.mock(import('src/constants.js'), async () => ({
+      ...(await vitest.importActual<typeof import('src/constants.js')>('src/constants.js')),
+      serverVersion: new SemVer('v3.0.0'),
+    }));
+  });
+
+  afterAll(() => {
+    vitest.unmock(import('src/constants.js'));
+  });
+
   it('should work', () => {
     expect(sut).toBeDefined();
   });
@@ -66,9 +78,10 @@ describe(VersionService.name, () => {
   describe('getVersion', () => {
     it('should respond the server version', () => {
       expect(sut.getVersion()).toEqual({
-        major: serverVersion.major,
-        minor: serverVersion.minor,
-        patch: serverVersion.patch,
+        major: 3,
+        minor: 0,
+        patch: 0,
+        prerelease: null,
       });
     });
   });
@@ -143,24 +156,24 @@ describe(VersionService.name, () => {
   describe('onConfigUpdate', () => {
     it('should queue a version check job when newVersionCheck is enabled', async () => {
       await sut.onConfigUpdate({
-        oldConfig: { ...defaults, newVersionCheck: { enabled: false } },
-        newConfig: { ...defaults, newVersionCheck: { enabled: true } },
+        oldConfig: { ...defaults, newVersionCheck: { enabled: false, channel: ReleaseChannel.Stable } },
+        newConfig: { ...defaults, newVersionCheck: { enabled: true, channel: ReleaseChannel.Stable } },
       });
       expect(mocks.job.queue).toHaveBeenCalledWith({ name: JobName.VersionCheck, data: {} });
     });
 
     it('should not queue a version check job when newVersionCheck is disabled', async () => {
       await sut.onConfigUpdate({
-        oldConfig: { ...defaults, newVersionCheck: { enabled: true } },
-        newConfig: { ...defaults, newVersionCheck: { enabled: false } },
+        oldConfig: { ...defaults, newVersionCheck: { enabled: true, channel: ReleaseChannel.Stable } },
+        newConfig: { ...defaults, newVersionCheck: { enabled: false, channel: ReleaseChannel.Stable } },
       });
       expect(mocks.job.queue).not.toHaveBeenCalled();
     });
 
     it('should not queue a version check job when newVersionCheck was already enabled', async () => {
       await sut.onConfigUpdate({
-        oldConfig: { ...defaults, newVersionCheck: { enabled: true } },
-        newConfig: { ...defaults, newVersionCheck: { enabled: true } },
+        oldConfig: { ...defaults, newVersionCheck: { enabled: true, channel: ReleaseChannel.Stable } },
+        newConfig: { ...defaults, newVersionCheck: { enabled: true, channel: ReleaseChannel.Stable } },
       });
       expect(mocks.job.queue).not.toHaveBeenCalled();
     });
@@ -169,21 +182,36 @@ describe(VersionService.name, () => {
   describe('onWebsocketConnection', () => {
     it('should send on_server_version client event', async () => {
       await sut.onWebsocketConnection({ userId: '42' });
-      expect(mocks.websocket.clientSend).toHaveBeenCalledWith('on_server_version', '42', expect.any(SemVer));
+      expect(mocks.websocket.clientSend).toHaveBeenCalledWith('on_server_version', '42', {
+        major: 3,
+        minor: 0,
+        patch: 0,
+        prerelease: null,
+      });
       expect(mocks.websocket.clientSend).toHaveBeenCalledTimes(1);
     });
 
     it('should also send a new release notification', async () => {
       mocks.systemMetadata.get.mockResolvedValue({ checkedAt: '2024-01-01', releaseVersion: 'v1.42.0' });
       await sut.onWebsocketConnection({ userId: '42' });
-      expect(mocks.websocket.clientSend).toHaveBeenCalledWith('on_server_version', '42', expect.any(SemVer));
+      expect(mocks.websocket.clientSend).toHaveBeenCalledWith('on_server_version', '42', {
+        major: 3,
+        minor: 0,
+        patch: 0,
+        prerelease: null,
+      });
       expect(mocks.websocket.clientSend).toHaveBeenCalledWith('on_new_release', '42', expect.any(Object));
     });
 
     it('should not send a release notification when the version check is disabled', async () => {
       mocks.systemMetadata.get.mockResolvedValueOnce({ newVersionCheck: { enabled: false } });
       await sut.onWebsocketConnection({ userId: '42' });
-      expect(mocks.websocket.clientSend).toHaveBeenCalledWith('on_server_version', '42', expect.any(SemVer));
+      expect(mocks.websocket.clientSend).toHaveBeenCalledWith('on_server_version', '42', {
+        major: 3,
+        minor: 0,
+        patch: 0,
+        prerelease: null,
+      });
       expect(mocks.websocket.clientSend).not.toHaveBeenCalledWith('on_new_release', '42', expect.any(Object));
     });
   });

server/src/services/version.service.ts

@@ -3,19 +3,27 @@ import { DateTime } from 'luxon';
 import semver, { SemVer } from 'semver';
 import { serverVersion } from 'src/constants';
 import { OnEvent, OnJob } from 'src/decorators';
-import { ReleaseNotification, ServerVersionResponseDto } from 'src/dtos/server.dto';
+import { ReleaseEventV1, ReleaseType, ServerVersionResponseDto } from 'src/dtos/server.dto';
+import { ReleaseChannel } from 'src/dtos/system-config.dto';
 import { CronJob, DatabaseLock, ImmichWorker, JobName, JobStatus, QueueName, SystemMetadataKey } from 'src/enum';
 import { ArgOf } from 'src/repositories/event.repository';
 import { BaseService } from 'src/services/base.service';
 import { VersionCheckMetadata } from 'src/types';
 import { handlePromiseError } from 'src/utils/misc';
 
-const asNotification = ({ checkedAt, releaseVersion }: VersionCheckMetadata): ReleaseNotification => {
+const asNotification = (
+  channel: ReleaseChannel,
+  { checkedAt, releaseVersion }: VersionCheckMetadata,
+): ReleaseEventV1 => {
   return {
-    isAvailable: semver.gt(releaseVersion, serverVersion),
+    // can't use gt because it's broken for release candidates F https://github.com/npm/node-semver/issues/483
+    isAvailable: semver.intersects(`>${serverVersion}`, releaseVersion.toString(), {
+      includePrerelease: channel === ReleaseChannel.ReleaseCandidate,
+    }),
     checkedAt,
     serverVersion: ServerVersionResponseDto.fromSemVer(serverVersion),
     releaseVersion: ServerVersionResponseDto.fromSemVer(new SemVer(releaseVersion)),
+    type: semver.diff(serverVersion, releaseVersion) as ReleaseType,
   };
 };
 
@@ -98,14 +106,21 @@ export class VersionService extends BaseService {
         }
       }
 
-      const { version: releaseVersion, published_at: publishedAt } = await this.serverInfoRepository.getLatestRelease();
+      const { version: releaseVersion, published_at: publishedAt } = await this.serverInfoRepository.getLatestRelease(
+        newVersionCheck.channel,
+      );
       const metadata: VersionCheckMetadata = { checkedAt: DateTime.utc().toISO(), releaseVersion };
 
       await this.systemMetadataRepository.set(SystemMetadataKey.VersionCheckState, metadata);
 
-      if (semver.gt(releaseVersion, serverVersion)) {
+      // can't use gt because it's broken for release candidates F https://github.com/npm/node-semver/issues/483
+      if (
+        semver.intersects(`>${serverVersion}`, releaseVersion.toString(), {
+          includePrerelease: newVersionCheck.channel === ReleaseChannel.ReleaseCandidate,
+        })
+      ) {
         this.logger.log(`Found ${releaseVersion}, released at ${new Date(publishedAt).toLocaleString()}`);
-        this.websocketRepository.clientBroadcast('on_new_release', asNotification(metadata));
+        this.websocketRepository.clientBroadcast('on_new_release', asNotification(newVersionCheck.channel, metadata));
       }
     } catch (error: Error | any) {
       this.logger.warn(`Unable to run version check: ${error}\n${error?.stack}`);
@@ -117,7 +132,11 @@ export class VersionService extends BaseService {
 
   @OnEvent({ name: 'WebsocketConnect' })
   async onWebsocketConnection({ userId }: ArgOf<'WebsocketConnect'>) {
-    this.websocketRepository.clientSend('on_server_version', userId, serverVersion);
+    this.websocketRepository.clientSend(
+      'on_server_version',
+      userId,
+      ServerVersionResponseDto.fromSemVer(serverVersion),
+    );
 
     const { newVersionCheck } = await this.getConfig({ withCache: true });
     if (!newVersionCheck.enabled) {
@@ -126,7 +145,7 @@ export class VersionService extends BaseService {
 
     const metadata = await this.systemMetadataRepository.get(SystemMetadataKey.VersionCheckState);
     if (metadata) {
-      this.websocketRepository.clientSend('on_new_release', userId, asNotification(metadata));
+      this.websocketRepository.clientSend('on_new_release', userId, asNotification(newVersionCheck.channel, metadata));
     }
   }
 }

server/src/types.ts

@@ -29,7 +29,6 @@ import {
   SystemMetadataKey,
   TranscodeTarget,
   UserMetadataKey,
-  VideoCodec,
   WorkflowType,
 } from 'src/enum';
 
@@ -162,6 +161,25 @@ export interface TranscodeCommand {
   };
 }
 
+export interface VideoTuning {
+  strictGop: boolean;
+  lowLatency: boolean;
+}
+
+export interface HlsCommandOptions {
+  initFilename: string;
+  inputPath: string;
+  packetCount: number;
+  playlistFilename: string;
+  seekSeconds?: number;
+  segmentDuration: number;
+  segmentFilename: string;
+  startSegment: number;
+  target: TranscodeTarget;
+  timeBase: number;
+  totalDuration: number;
+}
+
 export interface BitrateDistribution {
   max: number;
   target: number;
@@ -177,14 +195,11 @@ export interface ImageBuffer {
 export interface VideoCodecSWConfig {
   getCommand(
     target: TranscodeTarget,
-    videoStream: VideoStreamInfo,
-    audioStream?: AudioStreamInfo,
+    video: VideoStreamInfo,
+    audio?: AudioStreamInfo,
     format?: VideoFormat,
   ): TranscodeCommand;
-}
-
-export interface VideoCodecHWConfig extends VideoCodecSWConfig {
-  getSupportedCodecs(): Array<VideoCodec>;
+  getHlsCommand(options: HlsCommandOptions, video: VideoStreamInfo, audio?: AudioStreamInfo): string[];
 }
 
 export interface ProbeOptions {
@@ -371,6 +386,7 @@ export type JobItem =
 
   // Cleanup
   | { name: JobName.SessionCleanup; data?: IBaseJob }
+  | { name: JobName.HlsSessionCleanup; data?: IBaseJob }
 
   // Tags
   | { name: JobName.TagCleanup; data?: IBaseJob }

server/src/utils/database.ts

@@ -71,10 +71,13 @@ export const removeUndefinedKeys = <T extends object>(update: T, template: unkno
 };
 
 export const ASSET_CHECKSUM_CONSTRAINT = 'UQ_assets_owner_checksum';
+export const VIDEO_STREAM_SESSION_PK_CONSTRAINT = 'video_stream_session_pkey';
 
-export const isAssetChecksumConstraint = (error: unknown) => {
-  return (error as PostgresError)?.constraint_name === 'UQ_assets_owner_checksum';
-};
+export const isAssetChecksumConstraint = (error: unknown) =>
+  (error as PostgresError)?.constraint_name === ASSET_CHECKSUM_CONSTRAINT;
+
+export const isVideoStreamSessionPkConstraint = (error: unknown) =>
+  (error as PostgresError)?.constraint_name === VIDEO_STREAM_SESSION_PK_CONSTRAINT;
 
 export function withDefaultVisibility<O>(qb: SelectQueryBuilder<DB, 'asset', O>) {
   return qb.where('asset.visibility', 'in', [sql.lit(AssetVisibility.Archive), sql.lit(AssetVisibility.Timeline)]);

server/src/utils/event.ts

@@ -0,0 +1,50 @@
+import { ArgOf, EmitEvent } from 'src/repositories/event.repository';
+
+export class PendingEvents<T extends { [T in EmitEvent]: ArgOf<T> extends { error?: string } ? T : never }[EmitEvent]> {
+  private pending = new Map<string, { completers: PromiseWithResolvers<ArgOf<T>>[]; timeout: NodeJS.Timeout }>();
+  private timeoutMs: number;
+
+  constructor({ timeoutMs }: { timeoutMs: number }) {
+    this.timeoutMs = timeoutMs;
+  }
+
+  wait(key: string): Promise<ArgOf<T>> {
+    const completer = Promise.withResolvers<ArgOf<T>>();
+    const existing = this.pending.get(key);
+    if (existing) {
+      existing.completers.push(completer);
+      return completer.promise;
+    }
+
+    const timeout = setTimeout(() => this.complete(key, { error: 'Request timed out' }), this.timeoutMs);
+    this.pending.set(key, { completers: [completer], timeout });
+    return completer.promise;
+  }
+
+  complete(key: string, value: ArgOf<T> | { error: string }) {
+    const pending = this.pending.get(key);
+    if (!pending) {
+      return;
+    }
+    clearTimeout(pending.timeout);
+    this.pending.delete(key);
+    if ('error' in value) {
+      const error = new Error(value.error);
+      for (const completer of pending.completers) {
+        completer.reject(error);
+      }
+    } else {
+      for (const completer of pending.completers) {
+        completer.resolve(value);
+      }
+    }
+  }
+
+  rejectByPrefix(prefix: string, error: string) {
+    for (const key of this.pending.keys()) {
+      if (key.startsWith(prefix)) {
+        this.complete(key, { error });
+      }
+    }
+  }
+}

server/src/utils/media.ts

@@ -1,4 +1,4 @@
-import { AUDIO_ENCODER } from 'src/constants';
+import { AUDIO_ENCODER, SUPPORTED_HWA_CODECS } from 'src/constants';
 import { SystemConfigFFmpegDto } from 'src/dtos/system-config.dto';
 import {
   ColorMatrix,
@@ -13,38 +13,56 @@ import {
 import {
   AudioStreamInfo,
   BitrateDistribution,
+  HlsCommandOptions,
   TranscodeCommand,
-  VideoCodecHWConfig,
   VideoCodecSWConfig,
   VideoFormat,
   VideoInterfaces,
   VideoStreamInfo,
+  VideoTuning,
 } from 'src/types';
 
+export const isVideoRotated = (videoStream: VideoStreamInfo): boolean => Math.abs(videoStream.rotation) === 90;
+
+export const isVideoVertical = (videoStream: VideoStreamInfo): boolean =>
+  videoStream.height > videoStream.width || isVideoRotated(videoStream);
+
+export const getOutputSize = (videoStream: VideoStreamInfo, targetRes: number) => {
+  const factor = Math.max(videoStream.height, videoStream.width) / Math.min(videoStream.height, videoStream.width);
+  let larger = Math.round(targetRes * factor);
+  if (larger % 2 !== 0) {
+    larger -= 1;
+  }
+  return isVideoVertical(videoStream) ? { width: targetRes, height: larger } : { width: larger, height: targetRes };
+};
+
 export class BaseConfig implements VideoCodecSWConfig {
   readonly presets = ['veryslow', 'slower', 'slow', 'medium', 'fast', 'faster', 'veryfast', 'superfast', 'ultrafast'];
-  protected constructor(protected config: SystemConfigFFmpegDto) {}
+  protected constructor(
+    protected config: SystemConfigFFmpegDto,
+    protected tune: VideoTuning = { strictGop: false, lowLatency: false },
+  ) {}
 
-  static create(config: SystemConfigFFmpegDto, interfaces: VideoInterfaces): VideoCodecSWConfig {
+  static create(config: SystemConfigFFmpegDto, interfaces: VideoInterfaces, tune?: VideoTuning) {
     if (config.accel === TranscodeHardwareAcceleration.Disabled) {
-      return this.getSWCodecConfig(config);
+      return this.getSWCodecConfig(config, tune);
     }
-    return this.getHWCodecConfig(config, interfaces);
+    return this.getHWCodecConfig(config, interfaces, tune);
   }
 
-  private static getSWCodecConfig(config: SystemConfigFFmpegDto) {
+  private static getSWCodecConfig(config: SystemConfigFFmpegDto, tune?: VideoTuning): VideoCodecSWConfig {
     switch (config.targetVideoCodec) {
       case VideoCodec.H264: {
-        return new H264Config(config);
+        return new H264Config(config, tune);
       }
       case VideoCodec.Hevc: {
-        return new HEVCConfig(config);
+        return new HEVCConfig(config, tune);
       }
       case VideoCodec.Vp9: {
-        return new VP9Config(config);
+        return new VP9Config(config, tune);
       }
       case VideoCodec.Av1: {
-        return new AV1Config(config);
+        return new AV1Config(config, tune);
       }
       default: {
         throw new Error(`Codec '${config.targetVideoCodec}' is unsupported`);
@@ -52,72 +70,122 @@ export class BaseConfig implements VideoCodecSWConfig {
     }
   }
 
-  private static getHWCodecConfig(config: SystemConfigFFmpegDto, interfaces: VideoInterfaces) {
-    let handler: VideoCodecHWConfig;
+  private static getHWCodecConfig(config: SystemConfigFFmpegDto, interfaces: VideoInterfaces, tune?: VideoTuning) {
+    if (!SUPPORTED_HWA_CODECS[config.accel].includes(config.targetVideoCodec)) {
+      throw new Error(
+        `${config.accel.toUpperCase()} acceleration does not support codec '${config.targetVideoCodec.toUpperCase()}'. Supported codecs: ${SUPPORTED_HWA_CODECS[config.accel]}`,
+      );
+    }
+
+    let handler: VideoCodecSWConfig;
     switch (config.accel) {
       case TranscodeHardwareAcceleration.Nvenc: {
         handler = config.accelDecode
-          ? new NvencHwDecodeConfig(config, interfaces)
-          : new NvencSwDecodeConfig(config, interfaces);
+          ? new NvencHwDecodeConfig(config, interfaces, tune)
+          : new NvencSwDecodeConfig(config, interfaces, tune);
         break;
       }
       case TranscodeHardwareAcceleration.Qsv: {
         handler = config.accelDecode
-          ? new QsvHwDecodeConfig(config, interfaces)
-          : new QsvSwDecodeConfig(config, interfaces);
+          ? new QsvHwDecodeConfig(config, interfaces, tune)
+          : new QsvSwDecodeConfig(config, interfaces, tune);
         break;
       }
       case TranscodeHardwareAcceleration.Vaapi: {
         handler = config.accelDecode
-          ? new VaapiHwDecodeConfig(config, interfaces)
-          : new VaapiSwDecodeConfig(config, interfaces);
+          ? new VaapiHwDecodeConfig(config, interfaces, tune)
+          : new VaapiSwDecodeConfig(config, interfaces, tune);
         break;
       }
       case TranscodeHardwareAcceleration.Rkmpp: {
         handler = config.accelDecode
-          ? new RkmppHwDecodeConfig(config, interfaces)
-          : new RkmppSwDecodeConfig(config, interfaces);
+          ? new RkmppHwDecodeConfig(config, interfaces, tune)
+          : new RkmppSwDecodeConfig(config, interfaces, tune);
         break;
       }
       default: {
         throw new Error(`${config.accel.toUpperCase()} acceleration is unsupported`);
       }
     }
-    if (!handler.getSupportedCodecs().includes(config.targetVideoCodec)) {
-      throw new Error(
-        `${config.accel.toUpperCase()} acceleration does not support codec '${config.targetVideoCodec.toUpperCase()}'. Supported codecs: ${handler.getSupportedCodecs()}`,
-      );
-    }
 
     return handler;
   }
 
-  getCommand(
-    target: TranscodeTarget,
-    videoStream: VideoStreamInfo,
-    audioStream?: AudioStreamInfo,
-    format?: VideoFormat,
-  ) {
+  getCommand(target: TranscodeTarget, video: VideoStreamInfo, audio?: AudioStreamInfo, format?: VideoFormat) {
     const options = {
-      inputOptions: this.getBaseInputOptions(videoStream, format),
-      outputOptions: [...this.getBaseOutputOptions(target, videoStream, audioStream), '-v', 'verbose'],
+      inputOptions: this.getBaseInputOptions(video, format),
+      outputOptions: [
+        ...this.getBaseOutputOptions(target, video, audio),
+        ...this.getPresetOptions(),
+        ...this.getBitrateOptions(),
+        ...this.getEncoderOptions(),
+        '-movflags',
+        'faststart',
+        '-fps_mode',
+        'passthrough',
+        '-v',
+        'verbose',
+      ],
       twoPass: this.eligibleForTwoPass(),
-      progress: { frameCount: videoStream.frameCount, percentInterval: 5 },
+      progress: { frameCount: video.frameCount, percentInterval: 5 },
     } as TranscodeCommand;
     if ([TranscodeTarget.All, TranscodeTarget.Video].includes(target)) {
-      const filters = this.getFilterOptions(videoStream);
+      const filters = this.getFilterOptions(video);
       if (filters.length > 0) {
         options.outputOptions.push('-vf', filters.join(','));
       }
     }
 
-    options.outputOptions.push(
+    return options;
+  }
+
+  getHlsCommand(options: HlsCommandOptions, video: VideoStreamInfo, audio?: AudioStreamInfo) {
+    const args: string[] = this.getBaseInputOptions(video);
+    if (options.seekSeconds) {
+      args.push('-ss', String(options.seekSeconds));
+    }
+    args.push(
+      '-nostdin',
+      '-nostats',
+      '-i',
+      options.inputPath,
+      ...this.getBaseOutputOptions(options.target, video, audio),
       ...this.getPresetOptions(),
-      ...this.getOutputThreadOptions(),
       ...this.getBitrateOptions(),
+      ...this.getEncoderOptions(),
+      '-copyts',
+      '-r',
+      `${options.packetCount * options.timeBase}/${options.totalDuration}`,
+      '-avoid_negative_ts',
+      'disabled',
+      '-f',
+      'hls',
+      '-hls_time',
+      String(options.segmentDuration),
+      '-hls_list_size',
+      '0',
+      '-hls_segment_type',
+      'fmp4',
+      '-hls_fmp4_init_filename',
+      options.initFilename,
+      '-hls_segment_options',
+      'movflags=+frag_discont',
+      '-hls_flags',
+      'temp_file',
+      '-hls_segment_filename',
+      options.segmentFilename,
+      '-start_number',
+      String(options.startSegment),
     );
 
-    return options;
+    if ([TranscodeTarget.All, TranscodeTarget.Video].includes(options.target)) {
+      const filters = this.getFilterOptions(video);
+      if (filters.length > 0) {
+        args.push('-vf', filters.join(','));
+      }
+    }
+    args.push(options.playlistFilename);
+    return args;
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -129,23 +197,7 @@ export class BaseConfig implements VideoCodecSWConfig {
     const videoCodec = [TranscodeTarget.All, TranscodeTarget.Video].includes(target) ? this.getVideoCodec() : 'copy';
     const audioCodec = [TranscodeTarget.All, TranscodeTarget.Audio].includes(target) ? this.getAudioEncoder() : 'copy';
 
-    const options = [
-      '-c:v',
-      videoCodec,
-      '-c:a',
-      audioCodec,
-      // Makes a second pass moving the moov atom to the
-      // beginning of the file for improved playback speed.
-      '-movflags',
-      'faststart',
-      '-fps_mode',
-      'passthrough',
-      '-map',
-      `0:${videoStream.index}`,
-      '-map_metadata',
-      '-1',
-    ];
-
+    const options = ['-c:v', videoCodec, '-c:a', audioCodec, '-map', `0:${videoStream.index}`, '-map_metadata', '-1'];
     if (audioStream) {
       options.push('-map', `0:${audioStream.index}`);
     }
@@ -157,18 +209,22 @@ export class BaseConfig implements VideoCodecSWConfig {
     }
     if (this.getGopSize() > 0) {
       options.push('-g', `${this.getGopSize()}`);
+      if (this.tune.strictGop) {
+        options.push('-keyint_min', `${this.getGopSize()}`);
+      }
     }
-
-    if (
-      this.config.targetVideoCodec === VideoCodec.Hevc &&
-      (videoCodec !== 'copy' || videoStream.codecName === 'hevc')
-    ) {
+    const isHvc = (videoCodec === 'copy' ? videoStream.codecName : videoCodec) === VideoCodec.Hevc;
+    if (isHvc) {
       options.push('-tag:v', 'hvc1');
     }
 
     return options;
   }
 
+  getEncoderOptions(): string[] {
+    return [];
+  }
+
   getFilterOptions(videoStream: VideoStreamInfo) {
     const options = [];
     if (this.shouldScale(videoStream)) {
@@ -272,25 +328,7 @@ export class BaseConfig implements VideoCodecSWConfig {
 
   getScaling(videoStream: VideoStreamInfo, mult = 2) {
     const targetResolution = this.getTargetResolution(videoStream);
-    return this.isVideoVertical(videoStream) ? `${targetResolution}:-${mult}` : `-${mult}:${targetResolution}`;
-  }
-
-  getSize(videoStream: VideoStreamInfo) {
-    const smaller = this.getTargetResolution(videoStream);
-    const factor = Math.max(videoStream.height, videoStream.width) / Math.min(videoStream.height, videoStream.width);
-    let larger = Math.round(smaller * factor);
-    if (larger % 2 !== 0) {
-      larger -= 1;
-    }
-    return this.isVideoVertical(videoStream) ? { width: smaller, height: larger } : { width: larger, height: smaller };
-  }
-
-  isVideoRotated(videoStream: VideoStreamInfo) {
-    return Math.abs(videoStream.rotation) === 90;
-  }
-
-  isVideoVertical(videoStream: VideoStreamInfo) {
-    return videoStream.height > videoStream.width || this.isVideoRotated(videoStream);
+    return isVideoVertical(videoStream) ? `${targetResolution}:-${mult}` : `-${mult}:${targetResolution}`;
   }
 
   isBitrateConstrained() {
@@ -353,23 +391,18 @@ export class BaseConfig implements VideoCodecSWConfig {
   }
 }
 
-export class BaseHWConfig extends BaseConfig implements VideoCodecHWConfig {
+export class BaseHWConfig extends BaseConfig {
   protected device: string;
-  protected interfaces: VideoInterfaces;
 
   constructor(
     protected config: SystemConfigFFmpegDto,
-    interfaces: VideoInterfaces,
+    protected interfaces: VideoInterfaces,
+    tune?: VideoTuning,
   ) {
-    super(config);
-    this.interfaces = interfaces;
+    super(config, tune);
     this.device = this.getDevice(interfaces);
   }
 
-  getSupportedCodecs() {
-    return [VideoCodec.H264, VideoCodec.Hevc];
-  }
-
   validateDevices(devices: string[]) {
     if (devices.length === 0) {
       throw new Error('No /dev/dri devices found. If using Docker, make sure at least one /dev/dri device is mounted');
@@ -474,24 +507,32 @@ export class ThumbnailConfig extends BaseConfig {
 }
 
 export class H264Config extends BaseConfig {
-  getOutputThreadOptions() {
-    const options = super.getOutputThreadOptions();
-    if (this.config.threads === 1) {
-      options.push('-x264-params', 'frame-threads=1:pools=none');
+  getEncoderOptions(): string[] {
+    const out = this.getOutputThreadOptions();
+    if (this.tune.strictGop) {
+      out.push('-sc_threshold:v', '0');
     }
-
-    return options;
+    if (this.config.threads === 1) {
+      out.push('-x264-params', 'frame-threads=1:pools=none');
+    }
+    return out;
   }
 }
 
 export class HEVCConfig extends BaseConfig {
-  getOutputThreadOptions() {
-    const options = super.getOutputThreadOptions();
-    if (this.config.threads === 1) {
-      options.push('-x265-params', 'frame-threads=1:pools=none');
+  getEncoderOptions(): string[] {
+    const out: string[] = this.getOutputThreadOptions();
+    const params: string[] = [];
+    if (this.tune.strictGop) {
+      params.push('no-scenecut=1', 'no-open-gop=1');
     }
-
-    return options;
+    if (this.config.threads === 1) {
+      params.push('frame-threads=1', 'pools=none');
+    }
+    if (params.length > 0) {
+      out.push('-x265-params', params.join(':'));
+    }
+    return out;
   }
 }
 
@@ -520,8 +561,8 @@ export class VP9Config extends BaseConfig {
     return [`-${this.useCQP() ? 'q:v' : 'crf'}`, `${this.config.crf}`, '-b:v', `${bitrates.max}${bitrates.unit}`];
   }
 
-  getOutputThreadOptions() {
-    return ['-row-mt', '1', ...super.getOutputThreadOptions()];
+  getEncoderOptions(): string[] {
+    return ['-row-mt', '1', ...this.getOutputThreadOptions()];
   }
 
   eligibleForTwoPass() {
@@ -543,23 +584,22 @@ export class AV1Config extends BaseConfig {
   }
 
   getBitrateOptions() {
-    const options = ['-crf', `${this.config.crf}`];
-    const bitrates = this.getBitrateDistribution();
-    const svtparams = [];
-    if (this.config.threads > 0) {
-      svtparams.push(`lp=${this.config.threads}`);
-    }
-    if (bitrates.max > 0) {
-      svtparams.push(`mbr=${bitrates.max}${bitrates.unit}`);
-    }
-    if (svtparams.length > 0) {
-      options.push('-svtav1-params', svtparams.join(':'));
-    }
-    return options;
+    return ['-crf', `${this.config.crf}`];
   }
 
-  getOutputThreadOptions() {
-    return []; // Already set above with svtav1-params
+  getEncoderOptions(): string[] {
+    const params: string[] = [];
+    if (this.tune.lowLatency) {
+      params.push('hierarchical-levels=3', 'lookahead=0', 'enable-tf=0');
+    }
+    if (this.config.threads > 0) {
+      params.push(`lp=${this.config.threads}`);
+    }
+    const bitrates = this.getBitrateDistribution();
+    if (bitrates.max > 0) {
+      params.push(`mbr=${bitrates.max}${bitrates.unit}`);
+    }
+    return params.length > 0 ? ['-svtav1-params', params.join(':')] : [];
   }
 
   eligibleForTwoPass() {
@@ -572,10 +612,6 @@ export class NvencSwDecodeConfig extends BaseHWConfig {
     return '0';
   }
 
-  getSupportedCodecs() {
-    return [VideoCodec.H264, VideoCodec.Hevc, VideoCodec.Av1];
-  }
-
   getBaseInputOptions() {
     return ['-init_hw_device', `cuda=cuda:${this.device}`, '-filter_hw_device', 'cuda'];
   }
@@ -652,6 +688,14 @@ export class NvencSwDecodeConfig extends BaseHWConfig {
     return [];
   }
 
+  getEncoderOptions(): string[] {
+    const out = this.getOutputThreadOptions();
+    if (this.tune.strictGop) {
+      out.push('-forced-idr', '1');
+    }
+    return out;
+  }
+
   getRefs() {
     const bframes = this.getBFrames();
     if (bframes > 0 && bframes < 3 && this.config.refs < 3) {
@@ -703,8 +747,8 @@ export class NvencHwDecodeConfig extends NvencSwDecodeConfig {
     return ['-threads', '1'];
   }
 
-  getOutputThreadOptions() {
-    return [];
+  getEncoderOptions(): string[] {
+    return this.tune.strictGop ? ['-forced-idr', '1'] : [];
   }
 }
 
@@ -749,10 +793,6 @@ export class QsvSwDecodeConfig extends BaseHWConfig {
     return options;
   }
 
-  getSupportedCodecs() {
-    return [VideoCodec.H264, VideoCodec.Hevc, VideoCodec.Vp9, VideoCodec.Av1];
-  }
-
   // recommended from https://github.com/intel/media-delivery/blob/master/doc/benchmarks/intel-iris-xe-max-graphics/intel-iris-xe-max-graphics.md
   getBFrames() {
     if (this.config.bframes < 0) {
@@ -775,6 +815,14 @@ export class QsvSwDecodeConfig extends BaseHWConfig {
   getScaling(videoStream: VideoStreamInfo): string {
     return super.getScaling(videoStream, 1);
   }
+
+  getEncoderOptions(): string[] {
+    const out = this.getOutputThreadOptions();
+    if (this.tune.strictGop) {
+      out.push('-idr_interval', '0');
+    }
+    return out;
+  }
 }
 
 export class QsvHwDecodeConfig extends QsvSwDecodeConfig {
@@ -888,13 +936,17 @@ export class VaapiSwDecodeConfig extends BaseHWConfig {
     return options;
   }
 
-  getSupportedCodecs() {
-    return [VideoCodec.H264, VideoCodec.Hevc, VideoCodec.Vp9, VideoCodec.Av1];
-  }
-
   useCQP() {
     return this.config.cqMode !== CQMode.Icq || this.config.targetVideoCodec === VideoCodec.Vp9;
   }
+
+  getEncoderOptions(): string[] {
+    const out = this.getOutputThreadOptions();
+    if (this.tune.strictGop) {
+      out.push('-idr_interval', '0');
+    }
+    return out;
+  }
 }
 
 export class VaapiHwDecodeConfig extends VaapiSwDecodeConfig {
@@ -988,10 +1040,6 @@ export class RkmppSwDecodeConfig extends BaseHWConfig {
     return ['-rc_mode', 'CQP', '-qp_init', `${this.config.crf}`];
   }
 
-  getSupportedCodecs() {
-    return [VideoCodec.H264, VideoCodec.Hevc];
-  }
-
   getVideoCodec(): string {
     return `${this.config.targetVideoCodec}_rkmpp`;
   }

server/src/utils/misc.ts

@@ -15,7 +15,7 @@ import picomatch from 'picomatch';
 import parse from 'picomatch/lib/parse';
 import { SystemConfig } from 'src/config';
 import { CLIP_MODEL_INFO, endpointTags, serverVersion } from 'src/constants';
-import { extraSyncModels } from 'src/dtos/sync.dto';
+import { extraModels } from 'src/decorators';
 import { ApiCustomExtension, ImmichCookie, ImmichHeader, MetadataKey } from 'src/enum';
 import { LoggingRepository } from 'src/repositories/logging.repository';
 
@@ -289,7 +289,7 @@ export const useSwagger = (app: INestApplication, { write }: { write: boolean })
 
   const options: SwaggerDocumentOptions = {
     operationIdFactory: (controllerKey: string, methodKey: string) => methodKey,
-    extraModels: extraSyncModels,
+    extraModels,
     ignoreGlobalPrefix: true,
   };
 

server/test/fixtures/media.stub.ts

@@ -597,7 +597,7 @@ export const train = {
   packets: {
     totalDuration: 12_290,
     packetCount: 1229,
-    outputFrames: 1303,
+    outputFrames: 1304,
     keyframePts: [
       0, 601, 1201, 1802, 2402, 3003, 3604, 4204, 4805, 5405, 6006, 6607, 7207, 7808, 8408, 9009, 9609, 10_210, 10_811,
       11_411, 12_062, 12_703,

server/test/repositories/storage.repository.mock.ts

@@ -75,5 +75,6 @@ export const newStorageRepositoryMock = (): Mocked<RepositoryInterface<StorageRe
     copyFile: vitest.fn(),
     utimes: vitest.fn(),
     watch: vitest.fn().mockImplementation(makeMockWatcher({})),
+    watchDir: vitest.fn().mockImplementation(() => ({ close: vitest.fn(), on: vitest.fn() })),
   };
 };

server/test/utils.ts

@@ -181,7 +181,11 @@ export const automock = <T>(
   const mocks: Mock[] = [];
 
   const instance = new Dependency(...args);
-  for (const property of Object.getOwnPropertyNames(Dependency.prototype)) {
+  const propertyNames = new Set([
+    ...Object.getOwnPropertyNames(Dependency.prototype),
+    ...Object.getOwnPropertyNames(instance),
+  ]);
+  for (const property of propertyNames) {
     if (property === 'constructor') {
       continue;
     }
@@ -346,7 +350,7 @@ export const getMocks = () => {
     trash: automock(TrashRepository),
     user: automock(UserRepository, { strict: false }),
     versionHistory: automock(VersionHistoryRepository),
-    videoStream: automock(VideoStreamRepository),
+    videoStream: automock(VideoStreamRepository, { strict: false }),
     view: automock(ViewRepository),
     // eslint-disable-next-line no-sparse-arrays
     websocket: automock(WebsocketRepository, { args: [, loggerMock], strict: false }),
@@ -500,6 +504,7 @@ export const mockSpawn = vitest.fn((exitCode: number, stdout: string, stderr: st
         callback(exitCode);
       }
     }),
+    kill: vitest.fn(),
   } as unknown as ChildProcessWithoutNullStreams;
 });
 

server/tsconfig.json

@@ -8,9 +8,9 @@
     "experimentalDecorators": true,
     "allowSyntheticDefaultImports": true,
     "resolveJsonModule": true,
-    "target": "es2022",
+    "target": "es2024",
     "moduleResolution": "node16",
-    "lib": ["dom", "es2023"],
+    "lib": ["dom", "es2024"],
     "sourceMap": true,
     "outDir": "./dist",
     "incremental": true,

web/package.json

@@ -46,6 +46,8 @@
     "geojson": "^0.5.0",
     "handlebars": "^4.7.8",
     "happy-dom": "^20.0.0",
+    "hls-video-element": "^1.5.11",
+    "hls.js": "^1.6.16",
     "intl-messageformat": "^11.0.0",
     "justified-layout": "^4.1.0",
     "lodash-es": "^4.17.21",

web/src/lib/components/asset-viewer/VideoNativeViewer.svelte

@@ -5,7 +5,7 @@
   import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
   import { castManager } from '$lib/managers/cast-manager.svelte';
   import { autoPlayVideo, lang, loopVideo as loopVideoPreference } from '$lib/stores/preferences.store';
-  import { getAssetMediaUrl, getAssetPlaybackUrl } from '$lib/utils';
+  import { getAssetHlsSessionUrl, getAssetHlsUrl, getAssetMediaUrl, getAssetPlaybackUrl } from '$lib/utils';
   import { AssetMediaSize, type AssetResponseDto } from '@immich/sdk';
   import { Icon, LoadingSpinner } from '@immich/ui';
   import {
@@ -21,6 +21,9 @@
     mdiVolumeMedium,
     mdiVolumeMute,
   } from '@mdi/js';
+  import Hls, { AbrController, Events, type FragLoadedData, type FragLoadingData, type HlsConfig } from 'hls.js';
+  import 'hls-video-element';
+  import type HlsVideoElement from 'hls-video-element';
   import 'media-chrome/media-control-bar';
   import 'media-chrome/media-controller';
   import 'media-chrome/media-fullscreen-button';
@@ -28,9 +31,10 @@
   import 'media-chrome/media-play-button';
   import 'media-chrome/media-playback-rate-button';
   import 'media-chrome/media-time-display';
-  import 'media-chrome/media-time-range';
+  import './immich-time-range';
   import 'media-chrome/media-volume-range';
   import 'media-chrome/menu/media-playback-rate-menu';
+  import 'media-chrome/menu/media-rendition-menu';
   import 'media-chrome/menu/media-settings-menu';
   import 'media-chrome/menu/media-settings-menu-button';
   import 'media-chrome/menu/media-settings-menu-item';
@@ -38,6 +42,8 @@
   import { useSwipe, type SwipeCustomEvent } from 'svelte-gestures';
   import { t } from 'svelte-i18n';
   import { fade } from 'svelte/transition';
+  import { featureFlagsManager } from '$lib/managers/feature-flags-manager.svelte';
+  import { mediaCapabilitiesManager } from '$lib/managers/media-capabilities-manager.svelte';
 
   interface Props {
     asset: AssetResponseDto;
@@ -69,14 +75,155 @@
 
   let videoPlayer: HTMLVideoElement | undefined = $state();
   let isLoading = $state(true);
-  let assetFileUrl = $derived(
-    playOriginalVideo
-      ? getAssetMediaUrl({ id: assetId, size: AssetMediaSize.Original, cacheKey })
-      : getAssetPlaybackUrl({ id: assetId, cacheKey }),
-  );
+  let assetFileUrl = $derived.by(() => {
+    if (featureFlagsManager.value.realtimeTranscoding) {
+      return getAssetHlsUrl(assetId);
+    }
+
+    if (playOriginalVideo) {
+      return getAssetMediaUrl({ id: assetId, size: AssetMediaSize.Original, cacheKey });
+    }
+
+    return getAssetPlaybackUrl({ id: assetId, cacheKey });
+  });
   const aspectRatio = $derived(asset.width && asset.height ? `${asset.width} / ${asset.height}` : undefined);
   let showVideo = $state(false);
   let hasFocused = $state(false);
+  let activeSession: { assetId: string; id: string } | undefined;
+  let rebuildCount = 0;
+
+  const MAX_REBUILDS = 1;
+  const SESSION_ID_REGEX = /\/video\/stream\/([0-9a-f-]{36})\//;
+
+  // hls.js can abandon fetching an in-flight fragment if it thinks it'll take too long, in which case
+  // it emergency switches to a different variant. This extends the delay even further due to
+  // cold starting another transcode, so let the fragment finish and have steady ABR decide the next level.
+  //
+  // It can also emergency switch between fragments: while a switch's first segment is still loading,
+  // it can run out of buffer and drop to a lower level for just one segment before continuing at the switched quality.
+  // This can cause multiple redundant transcoding restarts when it occurs.
+  // Hold the committed level until its first fragment lands, then resume normal ABR.
+  class NoAbandonAbrController extends AbrController {
+    private switchTarget = -1;
+
+    protected override onFragLoading(_event: Events.FRAG_LOADING, data: FragLoadingData) {
+      if (data.frag.sn === 'initSegment') {
+        this.switchTarget = data.frag.level;
+      }
+    }
+
+    protected override onFragLoaded(event: Events.FRAG_LOADED, data: FragLoadedData) {
+      if (data.frag.sn !== 'initSegment') {
+        this.switchTarget = -1;
+      }
+      super.onFragLoaded(event, data);
+    }
+
+    override get nextAutoLevel(): number {
+      const level = super.nextAutoLevel;
+      const target = this.hls.levels[this.switchTarget];
+      // Hold the committed level, but only while hls.js still considers it healthy.
+      if (target && level < this.switchTarget && target.loadError === 0 && target.fragmentError === 0) {
+        return this.switchTarget;
+      }
+      return level;
+    }
+
+    override set nextAutoLevel(level: number) {
+      super.nextAutoLevel = level;
+    }
+  }
+
+  const hlsConfig: Partial<HlsConfig> = {
+    abrController: NoAbandonAbrController,
+    highBufferWatchdogPeriod: 10,
+    detectStallWithCurrentTimeMs: 10_000,
+    maxBufferHole: 0.5,
+    maxBufferLength: 30,
+    maxMaxBufferLength: 60,
+    fragLoadPolicy: {
+      default: {
+        maxTimeToFirstByteMs: 30_000,
+        maxLoadTimeMs: 60_000,
+        timeoutRetry: { maxNumRetry: 5, retryDelayMs: 100, maxRetryDelayMs: 0 },
+        errorRetry: { maxNumRetry: 3, retryDelayMs: 1000, maxRetryDelayMs: 8000 },
+      },
+    },
+    useMediaCapabilities: false,
+  };
+
+  const releaseSession = () => {
+    const session = activeSession;
+    if (!session) {
+      return;
+    }
+    activeSession = undefined;
+    const url = getAssetHlsSessionUrl(session.assetId, session.id);
+    void fetch(url, { method: 'DELETE' }).catch(() => console.warn('Failed to release HLS session', session));
+  };
+
+  const isHlsElement = (el: HTMLVideoElement | undefined): el is HlsVideoElement => {
+    return el?.tagName === 'HLS-VIDEO';
+  };
+
+  const wireHlsListeners = (el: HlsVideoElement, assetId: string, resumeTime?: number) => {
+    const api = el.api;
+    if (!api) {
+      return;
+    }
+
+    // This is a hack to make the rendition menu use `api.currentLevel` instead of `api.nextLevel`.
+    // `api.nextLevel` makes the player request the next segment followed by the current segment.
+    // That backward request causes the server to restart transcoding for no reason.
+    Object.defineProperty(api, 'nextLevel', {
+      configurable: true,
+      get: () => api.currentLevel,
+      set: (level: number) => {
+        api.currentLevel = level;
+      },
+    });
+
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+    api.on(Hls.Events.MANIFEST_PARSED, async () => {
+      // Defer hls.js's first fragment load until we filter out suboptimal variants
+      api.stopLoad();
+      const id = api.levels[0]?.url[0]?.match(SESSION_ID_REGEX)?.[1];
+      if (id) {
+        activeSession = { assetId, id };
+      }
+
+      const keep = await mediaCapabilitiesManager.efficientLevels(api.levels);
+      for (let i = api.levels.length - 1; i >= 0; i--) {
+        if (!keep.has(i)) {
+          api.removeLevel(i);
+        }
+      }
+
+      api.startLoad(resumeTime);
+    });
+
+    api.on(Hls.Events.FRAG_LOADED, () => (rebuildCount = 0));
+
+    api.on(Hls.Events.ERROR, (_, data) => {
+      // 404 on a fragment can mean the server-side session has expired. Refetch
+      // master for a new session, but give up if it still 404s.
+      if (
+        !data.fatal ||
+        data.details !== Hls.ErrorDetails.FRAG_LOAD_ERROR ||
+        data.response?.code !== 404 ||
+        rebuildCount++ >= MAX_REBUILDS
+      ) {
+        console.error('HLS error', JSON.stringify(data));
+        return;
+      }
+      console.warn('Error loading segment, starting new session');
+      activeSession = undefined;
+      resumeTime = el.currentTime;
+      el.load();
+      // wireHlsListeners must run after el.api is repopulated.
+      queueMicrotask(() => wireHlsListeners(el, assetId, resumeTime));
+    });
+  };
 
   onMount(() => {
     showVideo = true;
@@ -84,10 +231,31 @@
 
   $effect(() => {
     // reactive on `assetFileUrl` changes
-    if (assetFileUrl) {
+    if (videoPlayer && assetFileUrl) {
       hasFocused = false;
-      videoPlayer?.load();
+      rebuildCount = 0;
+      releaseSession();
+      if (isHlsElement(videoPlayer)) {
+        videoPlayer.config = hlsConfig;
+        videoPlayer.src = assetFileUrl;
+        const el = videoPlayer;
+        queueMicrotask(() => wireHlsListeners(el, assetId));
+      } else {
+        videoPlayer.load();
+      }
     }
+    return releaseSession;
+  });
+
+  const onPagehide = (event: PageTransitionEvent) => {
+    if (!event.persisted) {
+      releaseSession();
+    }
+  };
+
+  $effect(() => {
+    window.addEventListener('pagehide', onPagehide);
+    return () => window.removeEventListener('pagehide', onPagehide);
   });
 
   onDestroy(() => {
@@ -144,6 +312,10 @@
       videoPlayer?.pause();
     }
   });
+
+  // The time is only refreshed on HLS fragment decode by default,
+  // so manually emit events on seek to update it immediately.
+  const onSeeking = (event: Event) => event.currentTarget?.dispatchEvent(new Event('timeupdate'));
 </script>
 
 {#if showVideo}
@@ -172,27 +344,51 @@
         style:aspect-ratio={aspectRatio}
         defaultduration={asset.duration! / 1000}
       >
-        <video
-          bind:this={videoPlayer}
-          slot="media"
-          loop={$loopVideoPreference && loopVideo}
-          autoplay={$autoPlayVideo}
-          disablePictureInPicture
-          playsinline
-          {...useSwipe(onSwipe)}
-          class="h-full object-contain"
-          oncanplay={(e) => handleCanPlay(e.currentTarget)}
-          onended={onVideoEnded}
-          onplaying={(e) => {
-            if (!hasFocused) {
-              e.currentTarget.focus();
-              hasFocused = true;
-            }
-          }}
-          onclose={onClose}
-          poster={getAssetMediaUrl({ id: asset.id, size: AssetMediaSize.Preview, cacheKey })}
-          src={assetFileUrl}
-        ></video>
+        {#if featureFlagsManager.value.realtimeTranscoding}
+          <hls-video
+            bind:this={videoPlayer}
+            slot="media"
+            loop={$loopVideoPreference && loopVideo}
+            autoplay={$autoPlayVideo}
+            disablePictureInPicture
+            playsinline
+            {...useSwipe(onSwipe)}
+            class="h-full object-contain"
+            oncanplay={(e: Event) => handleCanPlay(e.currentTarget as HTMLVideoElement)}
+            onended={onVideoEnded}
+            onseeking={onSeeking}
+            onplaying={(e: Event) => {
+              if (!hasFocused) {
+                (e.currentTarget as HTMLElement).focus();
+                hasFocused = true;
+              }
+            }}
+            onclose={onClose}
+            poster={getAssetMediaUrl({ id: asset.id, size: AssetMediaSize.Preview, cacheKey })}
+          ></hls-video>
+        {:else}
+          <video
+            bind:this={videoPlayer}
+            slot="media"
+            loop={$loopVideoPreference && loopVideo}
+            autoplay={$autoPlayVideo}
+            disablePictureInPicture
+            playsinline
+            {...useSwipe(onSwipe)}
+            class="h-full object-contain"
+            oncanplay={(e) => handleCanPlay(e.currentTarget)}
+            onended={onVideoEnded}
+            onseeking={onSeeking}
+            onplaying={(e) => {
+              if (!hasFocused) {
+                e.currentTarget.focus();
+                hasFocused = true;
+              }
+            }}
+            onclose={onClose}
+            poster={getAssetMediaUrl({ id: asset.id, size: AssetMediaSize.Preview, cacheKey })}
+          ></video>
+        {/if}
 
         {#if extendedControls}
           <media-settings-menu hidden anchor="auto" class="min-w-3xs rounded-xl border border-light-300 shadow-sm">
@@ -205,6 +401,16 @@
                 <span slot="title">{$t('media_chrome.playback_rate')}</span>
               </media-playback-rate-menu>
             </media-settings-menu-item>
+            {#if featureFlagsManager.value.realtimeTranscoding}
+              <media-settings-menu-item class="mx-1 rounded-lg p-1 ps-2">
+                {$t('video_quality')}
+                <Icon slot="suffix" icon={mdiChevronRight} class="m-2" />
+                <media-rendition-menu slot="submenu" hidden>
+                  <Icon slot="back-icon" icon={mdiChevronLeft} class="m-2" />
+                  <span slot="title">{$t('video_quality')}</span>
+                </media-rendition-menu>
+              </media-settings-menu-item>
+            {/if}
           </media-settings-menu>
         {/if}
 
@@ -238,7 +444,7 @@
               <media-settings-menu-button class="shrink-0 rounded-full p-2 outline-none"></media-settings-menu-button>
             {/if}
           </media-control-bar>
-          <media-time-range class="h-8 w-full rounded-lg px-2 pb-3 outline-none"></media-time-range>
+          <immich-time-range class="h-8 w-full rounded-lg px-2 pb-3 outline-none"></immich-time-range>
         </div>
       </media-controller>
 
@@ -248,7 +454,7 @@
         </div>
       {/if}
 
-      {#if assetViewerManager.isFaceEditMode}
+      {#if assetViewerManager.isFaceEditMode && videoPlayer}
         <FaceEditor htmlElement={videoPlayer} {containerWidth} {containerHeight} {assetId} />
       {/if}
     {/if}
@@ -291,12 +497,12 @@
     font-variant-numeric: tabular-nums;
   }
 
-  media-time-range,
+  immich-time-range,
   media-volume-range {
     --media-control-hover-background: none;
   }
 
-  media-time-range:hover,
+  immich-time-range:hover,
   media-volume-range:hover {
     --media-range-thumb-opacity: 1;
   }

web/src/lib/components/asset-viewer/immich-time-range.ts

@@ -0,0 +1,54 @@
+import { MediaUIEvents } from 'media-chrome/constants';
+import MediaTimeRange from 'media-chrome/media-time-range';
+
+const COMMIT_DELAY_MS = 750;
+
+/** Custom MediaTimeRange that only seeks after pointer release to avoid hammering the server.
+ * Keyboard input uses timed debouncing instead since there's no release event. */
+class ImmichTimeRange extends MediaTimeRange {
+  private seeking = false;
+  private pending: number | undefined;
+  private idleTimer: ReturnType<typeof setTimeout> | undefined;
+
+  override connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('pointerdown', this.hold);
+    this.addEventListener('keydown', this.hold);
+    this.addEventListener('pointerup', this.release);
+    this.addEventListener('pointercancel', this.release);
+    this.addEventListener(MediaUIEvents.MEDIA_SEEK_REQUEST, this.intercept, { capture: true });
+  }
+
+  private hold(event: Event) {
+    if (event instanceof KeyboardEvent) {
+      if (!this.keysUsed.includes(event.key)) {
+        return;
+      }
+      clearTimeout(this.idleTimer);
+      this.idleTimer = setTimeout(this.release, COMMIT_DELAY_MS);
+    }
+    this.seeking = true;
+  }
+
+  private intercept(event: Event) {
+    if (!this.seeking) {
+      return; // not mid-scrub, or this is the request we replay in release()
+    }
+    this.pending = (event as CustomEvent<number>).detail;
+    event.stopImmediatePropagation();
+  }
+
+  private release() {
+    clearTimeout(this.idleTimer);
+    this.seeking = false;
+    if (this.pending !== undefined) {
+      const detail = this.pending;
+      this.pending = undefined;
+      this.dispatchEvent(new CustomEvent(MediaUIEvents.MEDIA_SEEK_REQUEST, { bubbles: true, composed: true, detail }));
+    }
+  }
+}
+
+if (!globalThis.customElements.get('immich-time-range')) {
+  globalThis.customElements.define('immich-time-range', ImmichTimeRange);
+}

web/src/lib/components/shared-components/gallery-viewer/GalleryViewer.svelte

@@ -22,16 +22,11 @@
   import { getJustifiedLayoutFromAssets } from '$lib/utils/layout-utils';
   import { navigate } from '$lib/utils/navigation';
   import { isTimelineAsset, toTimelineAsset } from '$lib/utils/timeline-util';
-  import { TUNABLES } from '$lib/utils/tunables';
   import { AssetVisibility, type AssetResponseDto } from '@immich/sdk';
   import { modalManager } from '@immich/ui';
   import { debounce } from 'lodash-es';
   import { t } from 'svelte-i18n';
 
-  const {
-    TIMELINE: { INTERSECTION_EXPAND_TOP, INTERSECTION_EXPAND_BOTTOM },
-  } = TUNABLES;
-
   type Props = {
     assets: AssetResponseDto[];
     viewerAssets?: AssetResponseDto[];
@@ -39,7 +34,7 @@
     disableAssetSelect?: boolean;
     showArchiveIcon?: boolean;
     viewport: Viewport;
-    onEndReached?: (() => void) | undefined;
+    onIntersected?: (() => void) | undefined;
     showAssetName?: boolean;
     onReload?: (() => void) | undefined;
     pageHeaderOffset?: number;
@@ -55,7 +50,7 @@
     disableAssetSelect = false,
     showArchiveIcon = false,
     viewport,
-    onEndReached = undefined,
+    onIntersected = undefined,
     showAssetName = false,
     onReload = undefined,
     slidingWindowOffset = 0,
@@ -75,23 +70,24 @@
     }),
   );
 
-  const getStyle = (index: number) => {
-    return `top: ${geometry.getTop(index)}px; left: ${geometry.getLeft(index)}px; width: ${geometry.getWidth(index)}px; height: ${geometry.getHeight(index)}px;`;
+  const getStyle = (i: number) => {
+    const geo = geometry;
+    return `top: ${geo.getTop(i)}px; left: ${geo.getLeft(i)}px; width: ${geo.getWidth(i)}px; height: ${geo.getHeight(i)}px;`;
   };
 
-  const isInOrNearViewport = (index: number) => {
+  const isIntersecting = (i: number) => {
+    const geo = geometry;
     const window = slidingWindow;
-    const top = geometry.getTop(index);
-    return top + pageHeaderOffset < window.bottom && top + geometry.getHeight(index) > window.top;
+    const top = geo.getTop(i);
+    return top + pageHeaderOffset < window.bottom && top + geo.getHeight(i) > window.top;
   };
 
   let shiftKeyIsDown = $state(false);
   let lastAssetMouseEvent: TimelineAsset | null = $state(null);
   let scrollTop = $state(0);
-
   let slidingWindow = $derived.by(() => {
-    const top = (scrollTop || 0) - slidingWindowOffset - INTERSECTION_EXPAND_TOP;
-    const bottom = top + viewport.height + slidingWindowOffset + INTERSECTION_EXPAND_BOTTOM;
+    const top = (scrollTop || 0) - slidingWindowOffset;
+    const bottom = top + viewport.height + slidingWindowOffset;
     return {
       top,
       bottom,
@@ -105,15 +101,17 @@
 
   const updateSlidingWindow = () => (scrollTop = document.scrollingElement?.scrollTop ?? 0);
 
-  const debouncedOnEndReached = debounce(() => onEndReached?.(), 750, { maxWait: 100, leading: true });
+  const debouncedOnIntersected = debounce(() => onIntersected?.(), 750, { maxWait: 100, leading: true });
 
-  let lastEndReachedHeight = 0;
+  let lastIntersectedHeight = 0;
   $effect(() => {
+    // Intersect if there's only one viewport worth of assets left to scroll.
     if (geometry.containerHeight - slidingWindow.bottom <= viewport.height) {
-      const contentHeight = geometry.containerHeight;
-      if (lastEndReachedHeight !== contentHeight) {
-        debouncedOnEndReached();
-        lastEndReachedHeight = contentHeight;
+      // Notify we got to (near) the end of scroll.
+      const intersectedHeight = geometry.containerHeight;
+      if (lastIntersectedHeight !== intersectedHeight) {
+        debouncedOnIntersected();
+        lastIntersectedHeight = intersectedHeight;
       }
     }
   });
@@ -364,10 +362,10 @@
     style:height={geometry.containerHeight + 'px'}
     style:width={geometry.containerWidth + 'px'}
   >
-    {#each assets as asset, index (asset.id + '-' + index)}
-      {#if isInOrNearViewport(index)}
+    {#each assets as asset, i (asset.id + '-' + i)}
+      {#if isIntersecting(i)}
         {@const currentAsset = toTimelineAsset(asset)}
-        <div class="absolute" style:overflow="clip" style={getStyle(index)}>
+        <div class="absolute" style:overflow="clip" style={getStyle(i)}>
           <Thumbnail
             readonly={disableAssetSelect}
             onClick={() => {
@@ -384,8 +382,8 @@
             asset={currentAsset}
             selected={assetInteraction.hasSelectedAsset(currentAsset.id)}
             selectionCandidate={assetInteraction.hasSelectionCandidate(currentAsset.id)}
-            thumbnailWidth={geometry.getWidth(index)}
-            thumbnailHeight={geometry.getHeight(index)}
+            thumbnailWidth={geometry.getWidth(i)}
+            thumbnailHeight={geometry.getHeight(i)}
           />
           {#if showAssetName && !isTimelineAsset(asset)}
             <div

web/src/lib/components/shared-components/side-bar/ServerStatus.svelte

@@ -4,12 +4,12 @@
   import ServerAboutModal from '$lib/modals/ServerAboutModal.svelte';
   import { userInteraction } from '$lib/stores/user.svelte';
   import { websocketStore } from '$lib/stores/websocket';
-  import type { ReleaseEvent } from '$lib/types';
   import { semverToName } from '$lib/utils';
   import { requestServerInfo } from '$lib/utils/auth';
   import {
     getAboutInfo,
     getVersionHistory,
+    type ReleaseEventV1,
     type ServerAboutResponseDto,
     type ServerVersionHistoryResponseDto,
   } from '@immich/sdk';
@@ -35,11 +35,9 @@
     userInteraction.versions = versions;
   });
   let isMain = $derived(info?.sourceRef === 'main' && info.repository === 'immich-app/immich');
-  let version = $derived(
-    $serverVersion ? `v${$serverVersion.major}.${$serverVersion.minor}.${$serverVersion.patch}` : null,
-  );
+  let version = $derived($serverVersion ? semverToName($serverVersion) : null);
 
-  const getReleaseInfo = (release?: ReleaseEvent) => {
+  const getReleaseInfo = (release?: ReleaseEventV1) => {
     if (!release || !release?.isAvailable || !authManager.user.isAdmin) {
       return;
     }

web/src/lib/managers/event-manager.svelte.ts

@@ -7,13 +7,13 @@ import type {
   LoginResponseDto,
   PersonResponseDto,
   QueueResponseDto,
+  ReleaseEventV1,
   SharedLinkResponseDto,
   SystemConfigDto,
   TagResponseDto,
   UserAdminResponseDto,
   WorkflowResponseDto,
 } from '@immich/sdk';
-import type { ReleaseEvent } from '$lib/types';
 import { BaseEventManager } from '$lib/utils/base-event-manager.svelte';
 import type { TreeNode } from '$lib/utils/tree-utils';
 
@@ -86,7 +86,7 @@ export type Events = {
   WorkflowUpdate: [WorkflowResponseDto];
   WorkflowDelete: [WorkflowResponseDto];
 
-  ReleaseEvent: [ReleaseEvent];
+  ReleaseEvent: [ReleaseEventV1];
 
   WebsocketConnect: [];
 };

web/src/lib/managers/media-capabilities-manager.svelte.ts

@@ -0,0 +1,92 @@
+export type Level = { videoCodec?: string; width: number; height: number; bitrate: number; frameRate: number };
+
+export const DEFAULT_DECODING_INFO: MediaCapabilitiesDecodingInfo = {
+  powerEfficient: true,
+  smooth: true,
+  supported: true,
+  keySystemAccess: null,
+};
+
+class MediaCapabilitiesManager {
+  private cache = new Map<string, Promise<MediaCapabilitiesDecodingInfo>>();
+
+  init() {
+    for (const level of [
+      { videoCodec: 'av01.0.04M.08', width: 854, height: 480, bitrate: 1_000_000, frameRate: 60 },
+      { videoCodec: 'hvc1.1.6.L90.B0', width: 854, height: 480, bitrate: 1_200_000, frameRate: 60 },
+      { videoCodec: 'av01.0.08M.08', width: 1280, height: 720, bitrate: 2_000_000, frameRate: 60 },
+      { videoCodec: 'hvc1.1.6.L93.B0', width: 1280, height: 720, bitrate: 2_500_000, frameRate: 60 },
+      { videoCodec: 'av01.0.09M.08', width: 1920, height: 1080, bitrate: 4_000_000, frameRate: 60 },
+      { videoCodec: 'hvc1.1.6.L120.B0', width: 1920, height: 1080, bitrate: 4_500_000, frameRate: 60 },
+      { videoCodec: 'av01.0.12M.08', width: 2560, height: 1440, bitrate: 7_000_000, frameRate: 60 },
+      { videoCodec: 'hvc1.2.4.L150.B0', width: 2560, height: 1440, bitrate: 8_000_000, frameRate: 60 },
+    ]) {
+      this.cache.set(this.cacheKey(level), this.queryDecodingInfo(level));
+    }
+
+    for (const level of [
+      { videoCodec: 'avc1.64001e', width: 854, height: 480, bitrate: 2_500_000, frameRate: 60 },
+      { videoCodec: 'avc1.64001f', width: 1280, height: 720, bitrate: 5_000_000, frameRate: 60 },
+      { videoCodec: 'avc1.640028', width: 1920, height: 1080, bitrate: 8_000_000, frameRate: 60 },
+      { videoCodec: 'avc1.640032', width: 2560, height: 1440, bitrate: 16_000_000, frameRate: 60 },
+    ]) {
+      this.cache.set(this.cacheKey(level), Promise.resolve(DEFAULT_DECODING_INFO));
+    }
+  }
+
+  async efficientLevels(levels: Level[]) {
+    const decodingInfo = await Promise.all(levels.map((level) => this.decodingInfo(level)));
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    const lowestBitrateByHeight = new Map<number, number>();
+    for (let i = 0; i < levels.length; i++) {
+      if (!decodingInfo[i].powerEfficient) {
+        continue;
+      }
+
+      const { bitrate, height } = levels[i];
+      const cur = lowestBitrateByHeight.get(height);
+      if (cur === undefined || bitrate < levels[cur].bitrate) {
+        lowestBitrateByHeight.set(height, i);
+      }
+    }
+
+    return new Set(lowestBitrateByHeight.values());
+  }
+
+  decodingInfo(level: Level) {
+    const key = this.cacheKey(level);
+    const existing = this.cache.get(key);
+    if (existing) {
+      return existing;
+    }
+    const promise = this.queryDecodingInfo(level);
+    this.cache.set(key, promise);
+    return promise;
+  }
+
+  private async queryDecodingInfo(level: Level) {
+    try {
+      return await navigator.mediaCapabilities.decodingInfo({
+        type: 'media-source',
+        video: {
+          contentType: `video/mp4; codecs="${level.videoCodec}"`,
+          width: level.width,
+          height: level.height,
+          bitrate: level.bitrate,
+          framerate: level.frameRate,
+        },
+      });
+    } catch {
+      return DEFAULT_DECODING_INFO;
+    }
+  }
+
+  private cacheKey({ videoCodec, width, height, frameRate }: Level) {
+    const resolution = Math.min(width, height);
+    const fpsBucket = Math.trunc(frameRate / 61) * 60;
+    return `${videoCodec}|${resolution}|${fpsBucket}`;
+  }
+}
+
+export const mediaCapabilitiesManager = new MediaCapabilitiesManager();
+mediaCapabilitiesManager.init();

web/src/lib/managers/release-manager.svelte.ts

@@ -1,8 +1,8 @@
+import type { ReleaseEventV1 } from '@immich/sdk';
 import { eventManager } from '$lib/managers/event-manager.svelte';
-import { type ReleaseEvent } from '$lib/types';
 
 class ReleaseManager {
-  value = $state<ReleaseEvent | undefined>();
+  value = $state<ReleaseEventV1 | undefined>();
 
   constructor() {
     eventManager.on({

web/src/lib/route.ts

@@ -152,4 +152,13 @@ export const Route = {
   // queues
   queues: () => '/admin/queues',
   viewQueue: ({ name }: { name: QueueName }) => `/admin/queues/${asQueueSlug(name)}`,
+
+  // continue helper for ensuring same-origin URLs
+  continue: (url: string | null, fallback: string) => {
+    if (!url || !url.startsWith('/') || url.startsWith('//')) {
+      return fallback;
+    }
+
+    return url;
+  },
 };

web/src/lib/stores/websocket.ts

@@ -3,6 +3,7 @@ import {
   type AssetResponseDto,
   type MaintenanceStatusResponseDto,
   type NotificationDto,
+  type ReleaseEventV1,
   type ServerVersionResponseDto,
   type SyncAssetEditV1,
   type SyncAssetV2,
@@ -15,7 +16,6 @@ import { eventManager } from '$lib/managers/event-manager.svelte';
 import { Route } from '$lib/route';
 import { maintenanceStore } from '$lib/stores/maintenance.store';
 import { notificationManager } from '$lib/stores/notification-manager.svelte';
-import type { ReleaseEvent } from '$lib/types';
 import { createEventEmitter } from '$lib/utils/eventemitter';
 
 interface AppRestartEvent {
@@ -34,7 +34,7 @@ export interface Events {
   on_person_thumbnail: (personId: string) => void;
   on_server_version: (serverVersion: ServerVersionResponseDto) => void;
   on_config_update: () => void;
-  on_new_release: (event: ReleaseEvent) => void;
+  on_new_release: (event: ReleaseEventV1) => void;
   on_session_delete: (sessionId: string) => void;
   on_notification: (notification: NotificationDto) => void;
 

web/src/lib/types.ts

@@ -1,4 +1,4 @@
-import type { QueueResponseDto, ServerVersionResponseDto } from '@immich/sdk';
+import type { QueueResponseDto } from '@immich/sdk';
 import type { ActionItem } from '@immich/ui';
 import type { DateTime } from 'luxon';
 import type { SvelteSet } from 'svelte/reactivity';
@@ -7,14 +7,6 @@ import type { TimelineAsset } from '$lib/managers/timeline-manager/types';
 
 export type LatLng = { lng: number; lat: number };
 
-export interface ReleaseEvent {
-  isAvailable: boolean;
-  /** ISO8601 */
-  checkedAt: string;
-  serverVersion: ServerVersionResponseDto;
-  releaseVersion: ServerVersionResponseDto;
-}
-
 export type QueueSnapshot = { timestamp: number; snapshot?: QueueResponseDto[] };
 
 export type HeaderButtonActionItem = ActionItem & { data?: { title?: string } };

web/src/lib/utils.spec.ts

@@ -1,5 +1,5 @@
 import { AssetTypeEnum } from '@immich/sdk';
-import { getAssetUrl, getReleaseType } from '$lib/utils';
+import { getAssetUrl, semverToName } from '$lib/utils';
 import { assetFactory } from '@test-data/factories/asset-factory';
 import { sharedLinkFactory } from '@test-data/factories/shared-link-factory';
 
@@ -161,26 +161,13 @@ describe('utils', () => {
       expect(url).toContain(asset.id);
     });
   });
-
-  describe(getReleaseType.name, () => {
-    it('should return "major" for major version changes', () => {
-      expect(getReleaseType({ major: 1, minor: 0, patch: 0 }, { major: 2, minor: 0, patch: 0 })).toBe('major');
-      expect(getReleaseType({ major: 1, minor: 0, patch: 0 }, { major: 3, minor: 2, patch: 1 })).toBe('major');
+  describe('semverToName', () => {
+    it('should not append release candidate tag if prelease is not set', () => {
+      expect(semverToName({ major: 3, minor: 0, patch: 0, prerelease: null })).toEqual('v3.0.0');
     });
 
-    it('should return "minor" for minor version changes', () => {
-      expect(getReleaseType({ major: 1, minor: 0, patch: 0 }, { major: 1, minor: 1, patch: 0 })).toBe('minor');
-      expect(getReleaseType({ major: 1, minor: 0, patch: 0 }, { major: 1, minor: 2, patch: 1 })).toBe('minor');
-    });
-
-    it('should return "patch" for patch version changes', () => {
-      expect(getReleaseType({ major: 1, minor: 0, patch: 0 }, { major: 1, minor: 0, patch: 1 })).toBe('patch');
-      expect(getReleaseType({ major: 1, minor: 0, patch: 0 }, { major: 1, minor: 0, patch: 5 })).toBe('patch');
-    });
-
-    it('should return "none" for matching versions', () => {
-      expect(getReleaseType({ major: 1, minor: 0, patch: 0 }, { major: 1, minor: 0, patch: 0 })).toBe('none');
-      expect(getReleaseType({ major: 1, minor: 2, patch: 3 }, { major: 1, minor: 2, patch: 3 })).toBe('none');
+    it('should append release candidate if set', () => {
+      expect(semverToName({ major: 3, minor: 0, patch: 0, prerelease: 0 })).toEqual('v3.0.0-rc.0');
     });
   });
 });

web/src/lib/utils.ts

@@ -244,6 +244,14 @@ export const getAssetPlaybackUrl = (options: AssetUrlOptions) => {
   return createUrl(getAssetPlaybackPath(id), { ...authManager.params, c });
 };
 
+export const getAssetHlsUrl = (id: string) => {
+  return createUrl(`/assets/${id}/video/stream/main.m3u8`, authManager.params);
+};
+
+export const getAssetHlsSessionUrl = (id: string, sessionId: string) => {
+  return createUrl(`/assets/${id}/video/stream/${sessionId}`, authManager.params);
+};
+
 export const getProfileImageUrl = (user: UserResponseDto) =>
   createUrl(getUserProfileImagePath(user.id), { updatedAt: user.profileChangedAt });
 
@@ -411,26 +419,8 @@ export function createDateFormatter(localeCode: string | undefined): DateFormatt
   };
 }
 
-export const getReleaseType = (
-  current: ServerVersionResponseDto,
-  newVersion: ServerVersionResponseDto,
-): 'major' | 'minor' | 'patch' | 'none' => {
-  if (current.major !== newVersion.major) {
-    return 'major';
-  }
-
-  if (current.minor !== newVersion.minor) {
-    return 'minor';
-  }
-
-  if (current.patch !== newVersion.patch) {
-    return 'patch';
-  }
-
-  return 'none';
-};
-
-export const semverToName = ({ major, minor, patch }: ServerVersionResponseDto) => `v${major}.${minor}.${patch}`;
+export const semverToName = ({ major, minor, patch, prerelease }: ServerVersionResponseDto) =>
+  `v${major}.${minor}.${patch}${prerelease === null ? '' : `-rc.${prerelease}`}`;
 
 export const withoutIcons = (actions: ActionItem[]): ActionItem[] =>
   actions.map((action) => ({ ...action, icon: undefined }));

web/src/routes/(user)/search/[[photos=photos]]/[[assetId=id]]/+page.svelte

@@ -309,7 +309,7 @@
       <GalleryViewer
         assets={searchResultAssets}
         assetInteraction={assetMultiSelectManager}
-        onEndReached={loadNextPage}
+        onIntersected={loadNextPage}
         showArchiveIcon={true}
         {viewport}
         onReload={onSearchQueryUpdate}

web/src/routes/VersionAnnouncement.svelte

@@ -2,8 +2,8 @@
   import OnEvents from '$lib/components/OnEvents.svelte';
   import { authManager } from '$lib/managers/auth-manager.svelte';
   import VersionAnnouncementModal from '$lib/modals/VersionAnnouncementModal.svelte';
-  import type { ReleaseEvent } from '$lib/types';
-  import { getReleaseType, semverToName } from '$lib/utils';
+  import { semverToName } from '$lib/utils';
+  import { ReleaseType, type ReleaseEventV1 } from '@immich/sdk';
   import { modalManager } from '@immich/ui';
 
   let modal = $state<{
@@ -11,16 +11,20 @@
     close: () => Promise<void>;
   }>();
 
-  const onReleaseEvent = async (release: ReleaseEvent) => {
+  const onReleaseEvent = async (release: ReleaseEventV1) => {
     if (!release.isAvailable || !authManager.user.isAdmin) {
       return;
     }
 
     const releaseVersion = semverToName(release.releaseVersion);
     const serverVersion = semverToName(release.serverVersion);
-    const type = getReleaseType(release.serverVersion, release.releaseVersion);
 
-    if (type === 'none' || type === 'patch' || localStorage.getItem('appVersion') === releaseVersion) {
+    if (
+      !release.type ||
+      release.type === ReleaseType.Patch ||
+      release.type === ReleaseType.Prepatch ||
+      localStorage.getItem('appVersion') === releaseVersion
+    ) {
       return;
     }
 

web/src/routes/admin/system-settings/FFmpegSettings.svelte

@@ -388,6 +388,22 @@
             />
           </div>
         </SettingAccordion>
+
+        <SettingAccordion
+          key="realtime-transcoding"
+          title={$t('admin.transcoding_realtime')}
+          subtitle={$t('admin.transcoding_realtime_description')}
+        >
+          <div class="ms-4 mt-4 flex flex-col gap-4">
+            <SettingSwitch
+              title={$t('admin.transcoding_realtime_enabled')}
+              subtitle={$t('admin.transcoding_realtime_enabled_description')}
+              bind:checked={configToEdit.ffmpeg.realtime.enabled}
+              isEdited={configToEdit.ffmpeg.realtime.enabled !== configToEdit.ffmpeg.realtime.enabled}
+              {disabled}
+            />
+          </div>
+        </SettingAccordion>
       </div>
 
       <div class="ms-4">

web/src/routes/admin/system-settings/NewVersionCheckSettings.svelte

@@ -5,21 +5,38 @@
   import { systemConfigManager } from '$lib/managers/system-config-manager.svelte';
   import { t } from 'svelte-i18n';
   import { fade } from 'svelte/transition';
+  import SettingSelect from './SettingSelect.svelte';
+  import { ReleaseChannel } from '@immich/sdk';
 
   const disabled = $derived(featureFlagsManager.value.configFile);
+  const config = $derived(systemConfigManager.value);
   let configToEdit = $state(systemConfigManager.cloneValue());
 </script>
 
 <div>
   <div in:fade={{ duration: 500 }}>
     <form autocomplete="off" onsubmit={(event) => event.preventDefault()}>
-      <div class="ms-4 mt-4">
+      <div class="ms-4 mt-4 flex flex-col gap-4">
         <SettingSwitch
           title={$t('admin.version_check_enabled_description')}
           subtitle={$t('admin.version_check_implications', { values: { server: 'version.immich.cloud' } })}
           bind:checked={configToEdit.newVersionCheck.enabled}
           {disabled}
         />
+        <SettingSelect
+          label={$t('admin.version_check_channel')}
+          desc={$t('admin.version_check_channel_description')}
+          bind:value={configToEdit.newVersionCheck.channel}
+          options={[
+            {
+              value: ReleaseChannel.Stable,
+              text: $t('admin.release_channel_stable'),
+            },
+            { value: ReleaseChannel.ReleaseCandidate, text: $t('admin.release_channel_release_candidate') },
+          ]}
+          isEdited={configToEdit.newVersionCheck.channel !== config.newVersionCheck.channel}
+          {disabled}
+        />
         <SettingButtonsRow bind:configToEdit keys={['newVersionCheck']} {disabled} />
       </div>
     </form>

web/src/routes/auth/login/+page.ts

@@ -8,7 +8,8 @@ import type { PageLoad } from './$types';
 export const load = (async ({ parent, url }) => {
   await parent();
 
-  const continueUrl = url.searchParams.get('continue') || Route.photos();
+  const continueUrl = Route.continue(url.searchParams.get('continue'), Route.photos());
+
   if (authManager.authenticated) {
     redirect(307, continueUrl);
   }

web/src/routes/auth/pin-prompt/+page.svelte

@@ -30,7 +30,7 @@
 
       await new Promise((resolve) => setTimeout(resolve, 1000));
 
-      await goto(data.continueUrl);
+      await goto(Route.continue(data.continueUrl, Route.photos()));
     } catch (error) {
       handleError(error, $t('wrong_pin_code'));
       isBadPinCode = true;