feat(player): start Plex transcodes at the resume position (#1817)

A Plex transcode session always starts producing at zero: the decision
request never sent offset=, so any non-zero open - resuming a
transcoded title, or switching from Direct Play to a transcoded
quality mid-playback - opened a session whose produced window begins
at the start of the file and seeked it. mpv immediately requests a
segment the transcoder has not produced, PMS answers 404 for it and
every subsequent segment, and playback buffers forever.

Send offset=<seconds> (6dp) with the decision and start request - the
view offset on initial open, the resolved resume position on every
in-place reload - so the session begins producing at the position the
player consumes first. The playlist timeline is unchanged: an offset
session's media playlist still covers the full title from segment
zero, so the player keeps opening with start: at the resume position
and in-stream seeks work as before.

Before a native player opens an offset playlist, waitForTranscodeReady
walks the master playlist, the media playlist, and the segment
containing the offset, because PMS can publish a manifest before that
segment is fetchable and mpv treats the 404 as an HLS error. The probe
is best-effort: it never fails an open, hands off immediately on HTTP
500 (on the response and exception paths alike) so the server-limit
dialog stays prompt, stops on cancellation, skips itself when the
playlist durations never reach the offset, and stays out of the
endpoint-failover cascade. In-place reloads resolve the replacement
source only after the old stop report has gone out, so Plex cannot use
that stop to terminate the replacement transcode.

close #1840

lib/screens/video_player/parts/episode_navigation.dart

@@ -632,11 +632,22 @@ extension _VideoPlayerEpisodeNavigationMethods on VideoPlayerScreenState {
         }
         if (!isCurrentReload()) return _MediaReloadOutcome.superseded;
 
-        // Overlap the old item's stop report with the resolve round-trip; it
-        // is awaited again right before the open below.
+        // Local resume lookup can overlap the old stop, but source resolution
+        // below must not: Plex can use that stop to terminate any new
+        // transcode sharing this playback session identifier.
         final stoppedProgressFuture = _sendStoppedProgressOnce();
 
+        var openResumePosition = await _resolveOpenResumePosition(
+          metadata: metadata,
+          isOffline: _offlineLibraryMode,
+          offlineWatchService: offlineWatchService,
+          requested: resumePosition,
+        );
+        if (!isCurrentReload()) return _MediaReloadOutcome.superseded;
+
         final playbackResolver = PlaybackSourceResolver(serverManager: serverManager, database: database);
+        await stoppedProgressFuture;
+        if (!isCurrentReload()) return _MediaReloadOutcome.superseded;
         final playbackContext = await playbackResolver.resolve(
           PlaybackInitializationOptions(
             metadata: metadata,
@@ -649,6 +660,7 @@ extension _VideoPlayerEpisodeNavigationMethods on VideoPlayerScreenState {
             preferredSubtitleTrack: initializationSubtitleTrack,
             sessionIdentifier: _playbackSessionIdentifier,
             transcodeSessionId: _playbackTranscodeSessionId,
+            transcodeOffset: openResumePosition,
           ),
           offlineLibraryMode: _offlineLibraryMode,
         );
@@ -661,7 +673,17 @@ extension _VideoPlayerEpisodeNavigationMethods on VideoPlayerScreenState {
         if (result.videoUrl == null) {
           throw PlaybackException('No video URL available');
         }
-
+        if (result.isOffline && !_offlineLibraryMode) {
+          // The pre-resolve lookup assumed an online source; a download won
+          // instead, so consult locally tracked progress after all.
+          openResumePosition = await _resolveOpenResumePosition(
+            metadata: metadata,
+            isOffline: true,
+            offlineWatchService: offlineWatchService,
+            requested: resumePosition,
+          );
+          if (!isCurrentReload()) return _MediaReloadOutcome.superseded;
+        }
         var subtitleSelection = await _resolveSubtitleSelectionForOpen(
           metadata: metadata,
           result: result,
@@ -688,14 +710,6 @@ extension _VideoPlayerEpisodeNavigationMethods on VideoPlayerScreenState {
           showErrorSnackBar(context, t.videoControls.transcodeUnavailableFallback);
         }
 
-        final openResumePosition = await _resolveOpenResumePosition(
-          metadata: metadata,
-          isOffline: _offlineLibraryMode || result.isOffline,
-          offlineWatchService: offlineWatchService,
-          requested: resumePosition,
-        );
-        if (!isCurrentReload()) return _MediaReloadOutcome.superseded;
-
         final displayCriteria = result.mediaInfo?.displayCriteria;
         final settingsService = await SettingsService.getInstance();
         if (!isCurrentReload()) return _MediaReloadOutcome.superseded;
@@ -731,7 +745,6 @@ extension _VideoPlayerEpisodeNavigationMethods on VideoPlayerScreenState {
           resumePosition: openResumePosition,
           durationMs: metadata.durationMs,
         );
-        await stoppedProgressFuture;
         _progressTracker?.stopTracking();
         _progressTracker?.dispose();
         _progressTracker = null;
@@ -753,6 +766,12 @@ extension _VideoPlayerEpisodeNavigationMethods on VideoPlayerScreenState {
           externalSubtitles: subtitleSelection.sidecarsAtOpen,
         );
         var effectiveExternalSubtitlePlan = externalSubtitlePlan;
+        await _awaitTranscodeReadiness(
+          client: mediaClient,
+          isTranscoding: result.isTranscoding,
+          videoUrl: result.videoUrl!,
+        );
+        if (!isCurrentReload()) return _MediaReloadOutcome.superseded;
         final openResult = await _openMediaOnPlayer(
           player: currentPlayer,
           settingsService: settingsService,

lib/screens/video_player/parts/playback_open.dart

@@ -602,6 +602,24 @@ extension _VideoPlayerOpenMethods on VideoPlayerScreenState {
     await player.setProperty('stream-buffer-size', '${ringBytes ?? mpvDefaultStreamBufferBytes}');
   }
 
+  /// Best-effort wait for an offset transcode session's segment at the
+  /// resume point, run immediately before the player opens the URL so the
+  /// wait hides behind the other pre-open work and the guarantee is fresh
+  /// when the player attaches. A not-ready session still opens — mpv
+  /// classifies whatever the server actually returns — and no-offset URLs
+  /// return immediately. Starting a new probe aborts the previous one so a
+  /// superseded open never leaves it polling out its window.
+  Future<void> _awaitTranscodeReadiness({
+    required MediaServerClient? client,
+    required bool isTranscoding,
+    required String videoUrl,
+  }) async {
+    if (!isTranscoding || client is! PlexClient) return;
+    _transcodeReadinessAbort?.abort();
+    final abort = _transcodeReadinessAbort = AbortController();
+    await client.waitForTranscodeReady(videoUrl, abort: abort);
+  }
+
   /// Open [videoUrl] on [player]: stream tuning → open → native subtitle style.
   ///
   /// [shouldContinue] is re-checked between the awaits so stale generations

lib/screens/video_player/parts/playback_start.dart

@@ -259,6 +259,12 @@ extension _VideoPlayerPlaybackStartMethods on VideoPlayerScreenState {
           resumePosition: resumePosition,
           durationMs: _currentMetadata.durationMs,
         );
+        await _awaitTranscodeReadiness(
+          client: playbackContext.reportingClient,
+          isTranscoding: result.isTranscoding,
+          videoUrl: result.videoUrl!,
+        );
+        if (!attempt.isCurrent) return;
         final openResult = await _openMediaOnPlayer(
           player: currentPlayer,
           settingsService: settingsService,

lib/screens/video_player_screen.dart

@@ -75,6 +75,7 @@ import '../providers/shader_provider.dart';
 import '../providers/user_profile_provider.dart';
 import '../utils/app_logger.dart';
 import '../utils/dialogs.dart';
+import '../utils/media_server_http_client.dart' show AbortController;
 import '../utils/log_redaction_manager.dart';
 import '../utils/live_tv_player_navigation.dart';
 import '../utils/player_utils.dart';
@@ -431,6 +432,10 @@ class VideoPlayerScreenState extends State<VideoPlayerScreen> with WidgetsBindin
   _PlaybackTransitionLease? _playbackTransitionLease;
   Completer<void>? _playbackTransitionIdleCompleter;
   bool _playbackIntentShouldPlay = true;
+
+  /// In-flight transcode readiness probe, aborted by the next probe or by
+  /// dispose so a superseded open never leaves it polling out its window.
+  AbortController? _transcodeReadinessAbort;
   int _pendingSubtitleCycleCount = 0;
   bool _subtitleCycleDrainActive = false;
 
@@ -1268,6 +1273,13 @@ class VideoPlayerScreenState extends State<VideoPlayerScreen> with WidgetsBindin
             preferredSubtitleTrack: _preferredSubtitleTrack,
             sessionIdentifier: _playbackSessionIdentifier,
             transcodeSessionId: _playbackTranscodeSessionId,
+            // The initial resume position is the server view offset (the
+            // online open resolves the same value later), so a resumed
+            // transcode starts producing at the resume point instead of
+            // seeking a stream that begins at zero.
+            transcodeOffset: _currentMetadata.viewOffsetMs != null
+                ? Duration(milliseconds: _currentMetadata.viewOffsetMs!)
+                : null,
           ),
           offlineLibraryMode: false,
         );
@@ -1688,6 +1700,7 @@ class VideoPlayerScreenState extends State<VideoPlayerScreen> with WidgetsBindin
   @override
   void dispose() {
     unawaited(AndroidExitDiagnostics.markUiState(AndroidUiState.mainScreen));
+    _transcodeReadinessAbort?.abort();
     _playerInitializationGeneration++;
     _frameRate.dispose();
     WidgetsBinding.instance.removeObserver(this);

lib/services/playback_initialization_types.dart

@@ -61,6 +61,13 @@ class PlaybackInitializationOptions {
   /// for Plex transcode.
   final String? transcodeSessionId;
 
+  /// Absolute VOD position at which a new Plex transcode must begin. Sent
+  /// with both Plex's decision and HLS start request so the server and the
+  /// player agree on the first available segment. Only the Plex client
+  /// consumes this today; Jellyfin's StartTimeTicks equivalent is
+  /// intentionally unwired.
+  final Duration? transcodeOffset;
+
   const PlaybackInitializationOptions({
     required this.metadata,
     required this.selectedMediaIndex,
@@ -73,6 +80,7 @@ class PlaybackInitializationOptions {
     this.preferredSubtitleTrack,
     this.sessionIdentifier,
     this.transcodeSessionId,
+    this.transcodeOffset,
   });
 }
 

lib/services/plex_client.dart

@@ -1,6 +1,7 @@
 import 'dart:async';
 import '../utils/isolate_helper.dart';
 import '../utils/json_utils.dart';
+import 'package:clock/clock.dart';
 import 'package:flutter/foundation.dart';
 import 'package:http/http.dart' as http;
 import 'package:uuid/uuid.dart';
@@ -2617,6 +2618,7 @@ class PlexClient
     required String sessionIdentifier,
     required String transcodeSessionId,
     int? audioStreamId,
+    Duration? offset,
   }) async {
     try {
       final allParams = _buildTranscodeParams(
@@ -2627,6 +2629,7 @@ class PlexClient
         sessionIdentifier: sessionIdentifier,
         transcodeSessionId: transcodeSessionId,
         audioStreamId: audioStreamId,
+        offset: offset,
       );
       return await _runTranscodeDecision(
         startEndpoint: _plexVideoHlsStartEndpoint,
@@ -2639,6 +2642,205 @@ class PlexClient
     }
   }
 
+  /// Absolute media position a transcode start URL was requested at, or null
+  /// when the URL is not an offset HLS start request. Matched on decoded
+  /// path segments so a percent-encoded spelling of the same URL cannot
+  /// silently switch the readiness probe off.
+  static Duration? transcodeStreamOffsetFromUrl(String videoUrl) {
+    final uri = Uri.tryParse(videoUrl);
+    if (uri == null || !'/${uri.pathSegments.join('/')}'.endsWith('/video/:/transcode/universal/start.m3u8')) {
+      return null;
+    }
+    final offsetSeconds = double.tryParse(uri.queryParameters['offset'] ?? '');
+    if (offsetSeconds == null || offsetSeconds <= 0) return null;
+    return Duration(microseconds: (offsetSeconds * Duration.microsecondsPerSecond).round());
+  }
+
+  /// Picks the playlist entry the readiness probe should touch: the segment
+  /// whose duration window contains [offset].
+  ///
+  /// Plex media playlists always cover the full title from segment zero, so
+  /// probing the first entry would steer the transcoder back to the start —
+  /// requesting a segment is how a client seeks a Plex HLS session. A master
+  /// playlist (no `#EXTINF` durations) descends into its first variant. A
+  /// media playlist whose durations never cross [offset] returns null: it
+  /// cannot say where the offset lives, and a probe aimed at the wrong
+  /// segment would seek the session, so the caller skips probing instead.
+  @visibleForTesting
+  static String? selectReadinessProbeTarget(String body, Duration offset) {
+    String? firstEntry;
+    var sawSegmentDurations = false;
+    var cumulative = Duration.zero;
+    var pending = Duration.zero;
+    for (final raw in body.split(RegExp(r'\r?\n'))) {
+      final line = raw.trim();
+      if (line.isEmpty) continue;
+      if (line.startsWith('#')) {
+        if (line.startsWith('#EXTINF:')) {
+          sawSegmentDurations = true;
+          final seconds = double.tryParse(line.substring('#EXTINF:'.length).split(',').first);
+          if (seconds != null) pending = Duration(microseconds: (seconds * Duration.microsecondsPerSecond).round());
+        }
+        continue;
+      }
+      firstEntry ??= line;
+      cumulative += pending;
+      pending = Duration.zero;
+      if (sawSegmentDurations && cumulative > offset) return line;
+    }
+    return sawSegmentDurations ? null : (firstEntry ?? '');
+  }
+
+  /// Waits for a just-started Plex offset HLS session to serve the segment at
+  /// the requested offset before a native player opens its playlist. Plex can
+  /// return a manifest before the segment is ready; mpv treats that 404 as an
+  /// HLS error and races through the rest of the manifest.
+  ///
+  /// Best-effort by design: the probe never fails an open, it only stops
+  /// waiting, and callers ignore the returned bool — it exists for tests. The
+  /// player then sees whatever the server is actually doing and the existing
+  /// log-stream classification applies unchanged. To that end a 500 stops the
+  /// wait immediately — a persistent 500 must keep failing fast so the
+  /// server-limit dialog appears promptly — whether it arrives as a response
+  /// or inside a decode exception, and a cancellation ([abort] fired or the
+  /// owning client closing) stops it too rather than sleeping out the window.
+  /// URLs without an offset return immediately: probing a no-offset playlist
+  /// would touch segment zero, and requesting a segment is how a client seeks
+  /// a Plex HLS session.
+  ///
+  /// Other non-2xx responses are the expected not-ready signal. `_http.get`
+  /// does not throw on the status, though its body decode can throw carrying
+  /// one — both paths share [handOffStatus] so they cannot drift. Every
+  /// not-ready round waits [pollInterval], doubling up to 4x after three
+  /// consecutive failed round-trips so a stalled transcode is not hammered;
+  /// the accepted trade is that a session whose segments 404 for real
+  /// reaches the player, and its media-unreadable dialog, one probe window
+  /// later than an unprobed open would. The probe carries this retry budget
+  /// itself, so its requests bypass endpoint failover, and each request has a
+  /// hard timeout (5s, shrinking as the overall deadline approaches) so a
+  /// single hung request cannot consume the entire window.
+  Future<bool> waitForTranscodeReady(
+    String videoUrl, {
+    Duration timeout = const Duration(seconds: 15),
+    Duration pollInterval = const Duration(milliseconds: 500),
+    AbortController? abort,
+  }) async {
+    final startUri = Uri.tryParse(videoUrl);
+    final probeOffset = transcodeStreamOffsetFromUrl(videoUrl);
+    if (startUri == null || probeOffset == null) return true;
+
+    // One rule for terminal statuses, applied to responses and to
+    // status-bearing exceptions alike.
+    bool handOffStatus(int? statusCode) {
+      if (statusCode != 500) return false;
+      // Hand off without classifying: mpv opens the URL, hits the same 500,
+      // and the log-stream path raises the server-limit dialog.
+      appLogger.i('Plex transcode readiness probe handing off on HTTP 500');
+      return true;
+    }
+
+    final deadline = clock.now().add(timeout);
+    var candidate = startUri;
+    var playlistDepth = 0;
+    var consecutiveFailures = 0;
+    int? lastStatus;
+    while (true) {
+      final remaining = deadline.difference(clock.now());
+      if (remaining <= Duration.zero) break;
+      if (abort?.isAborted ?? false) return false;
+      try {
+        final requestTimeout = remaining < const Duration(seconds: 5) ? remaining : const Duration(seconds: 5);
+        final isPlaylist = candidate.path.toLowerCase().endsWith('.m3u8');
+        // The default Accept is application/json (PlexConfig.headers); the
+        // probe mirrors the player's request shape instead. Segments go
+        // through getStatus so a server that ignores Range never routes a
+        // full media segment through text decoding.
+        final int statusCode;
+        var body = '';
+        Uri? effectiveUri;
+        if (isPlaylist) {
+          final response = await _http.get(
+            candidate.toString(),
+            headers: const {'Accept': '*/*'},
+            timeout: requestTimeout,
+            abort: abort,
+            allowEndpointFailover: false,
+          );
+          statusCode = response.statusCode;
+          body = response.data?.toString() ?? '';
+          effectiveUri = response.effectiveUri;
+        } else {
+          final response = await _http.getStatus(
+            candidate.toString(),
+            headers: const {'Range': 'bytes=0-0', 'Accept': '*/*'},
+            timeout: requestTimeout,
+            abort: abort,
+          );
+          statusCode = response.statusCode;
+        }
+        lastStatus = statusCode;
+        if (statusCode >= 200 && statusCode < 300) {
+          consecutiveFailures = 0;
+          if (body.trimLeft().startsWith('#EXTM3U')) {
+            final child = selectReadinessProbeTarget(body, probeOffset);
+            if (child == null) {
+              // The playlist has segments but its durations never reach the
+              // offset — a playlist shape this client has never observed
+              // against a real PMS. It cannot say where the offset lives,
+              // and a probe aimed at the wrong segment would seek the
+              // session, so skip probing and let the player negotiate.
+              return true;
+            }
+            if (child.isNotEmpty) {
+              candidate = (effectiveUri ?? candidate).resolve(child);
+              playlistDepth++;
+              if (playlistDepth > 4) {
+                appLogger.w('Plex transcode readiness exceeded the HLS playlist depth limit');
+                return false;
+              }
+              // Descending into a child playlist is progress, not a poll.
+              continue;
+            }
+            // A manifest with no media entries yet: not ready, poll again.
+          } else if (!isPlaylist) {
+            // The segment at the offset answered: the session is ready.
+            return true;
+          }
+        } else if (handOffStatus(statusCode)) {
+          return false;
+        } else {
+          consecutiveFailures++;
+        }
+      } on MediaServerHttpException catch (e) {
+        if (e.isCancellation) {
+          // Cancellation is not a not-ready signal, so stop instead of
+          // sleeping out the window.
+          return false;
+        }
+        lastStatus = e.statusCode ?? lastStatus;
+        if (handOffStatus(e.statusCode)) return false;
+        // Transport failure — same treatment as a not-ready response.
+        consecutiveFailures++;
+        appLogger.d('Plex transcode readiness probe transport failure', error: e);
+      } catch (e) {
+        consecutiveFailures++;
+        appLogger.d('Plex transcode readiness probe transport failure', error: e);
+      }
+      var delay = pollInterval;
+      if (consecutiveFailures > 3) {
+        delay = pollInterval * (1 << (consecutiveFailures - 3).clamp(0, 2));
+      }
+      final timeLeft = deadline.difference(clock.now());
+      if (timeLeft <= Duration.zero) break;
+      await Future<void>.delayed(delay < timeLeft ? delay : timeLeft);
+    }
+    appLogger.w(
+      'Plex transcode did not become ready within ${timeout.inMilliseconds}ms '
+      '(playlistDepth=$playlistDepth, lastStatus=${lastStatus ?? 'none'}, consecutiveFailures=$consecutiveFailures)',
+    );
+    return false;
+  }
+
   /// Build a music transcode stream URL (decision + start path).
   ///
   /// Mirrors [buildTranscodeStartPath] for audio tracks: the same
@@ -2736,6 +2938,7 @@ class PlexClient
     required String sessionIdentifier,
     required String transcodeSessionId,
     int? audioStreamId,
+    Duration? offset,
   }) {
     final isOriginal = preset.isOriginal;
     final clientProfileExtra = _buildPlexHlsClientProfileExtra(
@@ -2760,6 +2963,7 @@ class PlexClient
       'directStreamAudio': '0',
       'mediaBufferSize': '102400',
       'session': transcodeSessionId,
+      if (offset != null && offset > Duration.zero) 'offset': (offset.inMilliseconds / 1000).toStringAsFixed(6),
       'subtitles': 'none',
       if (audioStreamId != null) 'audioStreamID': audioStreamId.toString(),
       'Accept-Language': 'en',
@@ -2789,6 +2993,7 @@ class PlexClient
     required String sessionIdentifier,
     required String transcodeSessionId,
     int? audioStreamId,
+    Duration? offset,
   }) {
     return _buildTranscodeParams(
       ratingKey: ratingKey,
@@ -2798,6 +3003,7 @@ class PlexClient
       sessionIdentifier: sessionIdentifier,
       transcodeSessionId: transcodeSessionId,
       audioStreamId: audioStreamId,
+      offset: offset,
     );
   }
 
@@ -3330,6 +3536,7 @@ class PlexClient
           sessionIdentifier: options.sessionIdentifier!,
           transcodeSessionId: options.transcodeSessionId!,
           audioStreamId: resolvedAudioId,
+          offset: options.transcodeOffset,
         );
 
         if (result.outcome == TranscodeDecisionOutcome.transcodeOk && result.startPath != null) {

lib/utils/media_server_http_client.dart

@@ -177,6 +177,45 @@ class MediaServerHttpClient {
     );
   }
 
+  /// Issue a GET and return only status and headers, draining the body
+  /// unread — the shape for probes that ask "does this answer?" rather than
+  /// "what does it say?".
+  ///
+  /// Unlike [getBytes] the status code is surfaced instead of only logged.
+  /// Unlike [get] nothing is ever decoded, so a body that fails decoding
+  /// cannot convert a status into an exception, and — because
+  /// [FailoverHttpClient] overrides [get] alone — this method structurally
+  /// never enters the endpoint-failover cascade. Non-2xx is returned, not
+  /// thrown, matching [get].
+  Future<MediaServerResponse> getStatus(
+    String url, {
+    Map<String, String>? headers,
+    Duration? timeout,
+    AbortController? abort,
+  }) {
+    return _perform<MediaServerResponse>(
+      'GET',
+      url,
+      headers: headers,
+      timeout: timeout,
+      abort: abort,
+      consume: (streamed, scope) async {
+        final effectiveUri = switch (streamed) {
+          http.BaseResponseWithUrl(:final url) => url,
+          _ => scope.uri,
+        };
+        await scope.receive(streamed.stream.drain<void>());
+        scope.logResponse(streamed.statusCode);
+        return MediaServerResponse(
+          statusCode: streamed.statusCode,
+          headers: streamed.headers,
+          requestUri: scope.uri,
+          effectiveUri: effectiveUri,
+        );
+      },
+    );
+  }
+
   /// Stream-download a URL directly into a file.
   Future<void> downloadFile(
     String url,