feat(player): 进度条拖动预览改用雪碧图

lib/core/data/models/drama.dart

@@ -17,6 +17,7 @@ class Episode {
     this.locked = false,
     this.likeCount,
     this.commentCount,
+    this.thumbnailsUrl,
   });
 
   final String id;
@@ -32,19 +33,25 @@ class Episode {
   final bool locked;
   final int? likeCount;
   final int? commentCount;
+  final String? thumbnailsUrl;
 
-  Episode withVideoUrl(String url, {int? likeCount, int? commentCount}) =>
-      Episode(
-        id: id,
-        number: number,
-        title: title,
-        isFree: isFree,
-        videoUrl: url,
-        durationSec: durationSec,
-        locked: locked,
-        likeCount: likeCount ?? this.likeCount,
-        commentCount: commentCount ?? this.commentCount,
-      );
+  Episode withVideoUrl(
+    String url, {
+    int? likeCount,
+    int? commentCount,
+    String? thumbnailsUrl,
+  }) => Episode(
+    id: id,
+    number: number,
+    title: title,
+    isFree: isFree,
+    videoUrl: url,
+    durationSec: durationSec,
+    locked: locked,
+    likeCount: likeCount ?? this.likeCount,
+    commentCount: commentCount ?? this.commentCount,
+    thumbnailsUrl: thumbnailsUrl ?? this.thumbnailsUrl,
+  );
 
   factory Episode.fromJson(Map<String, dynamic> json) {
     return Episode(
@@ -57,6 +64,7 @@ class Episode {
       videoUrl: json['playUrl'] as String? ?? '',
       likeCount: _optionalInt(json['likeCount']),
       commentCount: _optionalInt(json['commentCount']),
+      thumbnailsUrl: _optionalString(json['thumbnailsUrl']),
     );
   }
 }
@@ -159,3 +167,8 @@ class Drama {
 }
 
 int? _optionalInt(dynamic value) => value == null ? null : jsonToInt(value);
+
+String? _optionalString(dynamic value) {
+  final text = value is String ? value.trim() : '';
+  return text.isEmpty ? null : text;
+}

lib/core/data/models/play_ticket.dart

@@ -14,6 +14,7 @@ class PlayTicket {
     this.unlockCoin = 0,
     this.previewSeconds = 0,
     this.qualities = const [],
+    this.thumbnailsUrl,
     this.likeCount,
     this.commentCount,
   });
@@ -40,6 +41,7 @@ class PlayTicket {
 
   /// 后端下发的清晰度档位（如 AUTO / 720P / 1080P），HLS 由播放器自动切换。
   final List<String> qualities;
+  final String? thumbnailsUrl;
   final int? likeCount;
   final int? commentCount;
 
@@ -62,6 +64,7 @@ class PlayTicket {
           .whereType<String>()
           .where((quality) => quality.isNotEmpty)
           .toList(),
+      thumbnailsUrl: _optionalString(json['thumbnailsUrl']),
       likeCount: json['likeCount'] == null
           ? null
           : jsonToInt(json['likeCount']),
@@ -71,3 +74,8 @@ class PlayTicket {
     );
   }
 }
+
+String? _optionalString(dynamic value) {
+  final text = value is String ? value.trim() : '';
+  return text.isEmpty ? null : text;
+}

lib/core/data/services/sprite_thumbnail_asset_loader.dart

@@ -0,0 +1,128 @@
+// Author: fruit.com.cn
+
+import 'dart:convert';
+import 'dart:typed_data';
+import 'dart:ui' as ui;
+
+import 'package:dio/dio.dart';
+
+import '../../config/app_config.dart';
+
+const int spriteThumbnailDecodeMaxDimension = 2048;
+
+/// VTT 资源拒绝访问，服务层据此清缓存并重试一次。
+class SpriteThumbnailForbiddenException implements Exception {
+  const SpriteThumbnailForbiddenException();
+}
+
+/// 已解码 sprite 与原图尺寸；cue 坐标会按解码缩放比例映射。
+class SpriteThumbnailDecodedImage {
+  const SpriteThumbnailDecodedImage({
+    required this.image,
+    required this.originalWidth,
+    required this.originalHeight,
+  });
+
+  final ui.Image image;
+  final int originalWidth;
+  final int originalHeight;
+}
+
+/// 可注入的资源加载接口，测试无需真实网络或图片。
+abstract interface class SpriteThumbnailAssetLoader {
+  Future<String?> loadVtt(Uri uri);
+
+  Future<SpriteThumbnailDecodedImage?> loadSprite(Uri uri);
+}
+
+/// 默认通过项目现有 Dio 拉取 VTT 和 sprite 图片。
+class DioSpriteThumbnailAssetLoader implements SpriteThumbnailAssetLoader {
+  DioSpriteThumbnailAssetLoader({Dio? dio})
+    : _dio =
+          dio ??
+          Dio(
+            BaseOptions(
+              connectTimeout: AppConfig.requestTimeout,
+              receiveTimeout: AppConfig.requestTimeout,
+              validateStatus: (_) => true,
+            ),
+          );
+
+  final Dio _dio;
+
+  @override
+  Future<String?> loadVtt(Uri uri) async {
+    final response = await _request(uri);
+    if (response?.statusCode == 403) {
+      throw const SpriteThumbnailForbiddenException();
+    }
+    if (response == null || !_isSuccess(response.statusCode)) return null;
+    final data = response.data;
+    if (data is! List<int>) return null;
+    return utf8.decode(data, allowMalformed: true);
+  }
+
+  @override
+  Future<SpriteThumbnailDecodedImage?> loadSprite(Uri uri) async {
+    final response = await _request(uri);
+    if (response == null || !_isSuccess(response.statusCode)) return null;
+    final data = response.data;
+    if (data is! List<int>) return null;
+    return _decode(Uint8List.fromList(data));
+  }
+
+  Future<Response<List<int>>?> _request(Uri uri) async {
+    try {
+      return await _dio.get<List<int>>(
+        uri.toString(),
+        options: Options(responseType: ResponseType.bytes),
+      );
+    } catch (_) {
+      return null;
+    }
+  }
+
+  bool _isSuccess(int? status) =>
+      status != null && status >= 200 && status < 300;
+
+  Future<SpriteThumbnailDecodedImage?> _decode(Uint8List bytes) async {
+    ui.ImmutableBuffer? buffer;
+    ui.ImageDescriptor? descriptor;
+    ui.Codec? codec;
+    try {
+      buffer = await ui.ImmutableBuffer.fromUint8List(bytes);
+      descriptor = await ui.ImageDescriptor.encoded(buffer);
+      final originalWidth = descriptor.width;
+      final originalHeight = descriptor.height;
+      final target = _targetSize(originalWidth, originalHeight);
+      codec = await descriptor.instantiateCodec(
+        targetWidth: target.$1,
+        targetHeight: target.$2,
+      );
+      final frame = await codec.getNextFrame();
+      return SpriteThumbnailDecodedImage(
+        image: frame.image,
+        originalWidth: originalWidth,
+        originalHeight: originalHeight,
+      );
+    } catch (_) {
+      return null;
+    } finally {
+      codec?.dispose();
+      descriptor?.dispose();
+      buffer?.dispose();
+    }
+  }
+
+  (int?, int?) _targetSize(int width, int height) {
+    final longest = width > height ? width : height;
+    if (longest <= spriteThumbnailDecodeMaxDimension) {
+      return (null, null);
+    }
+    final scale = spriteThumbnailDecodeMaxDimension / longest;
+    return (
+      (width * scale).round().clamp(1, spriteThumbnailDecodeMaxDimension),
+      (height * scale).round().clamp(1, spriteThumbnailDecodeMaxDimension),
+    );
+  }
+}

lib/core/data/services/sprite_thumbnail_axis.dart

@@ -0,0 +1,461 @@
+// Author: fruit.com.cn
+
+import 'dart:collection';
+import 'dart:ui' as ui;
+
+import 'package:flutter/foundation.dart';
+
+import '../../config/app_config.dart';
+import 'sprite_thumbnail_asset_loader.dart';
+
+const Duration spriteVttCacheTtl = Duration(minutes: 10);
+const int spriteImageCacheCapacity = 2;
+
+/// 单个 VTT cue 对应的 sprite 裁剪区域。
+class SpriteThumbnailCue {
+  const SpriteThumbnailCue({
+    required this.start,
+    required this.end,
+    required this.spriteFile,
+    required this.sourceRect,
+  });
+
+  final Duration start;
+  final Duration end;
+  final String spriteFile;
+  final ui.Rect sourceRect;
+}
+
+/// 已解析的 VTT 时间轴。
+class SpriteThumbnailAxis {
+  const SpriteThumbnailAxis({required this.vttUrl, required this.cues});
+
+  final String vttUrl;
+  final List<SpriteThumbnailCue> cues;
+
+  factory SpriteThumbnailAxis.empty(String vttUrl) =>
+      SpriteThumbnailAxis(vttUrl: vttUrl, cues: const []);
+
+  Uri resolveSpriteUri(String spriteFile) =>
+      Uri.parse(vttUrl).resolve(spriteFile);
+}
+
+/// 可直接交给 RawImage.sourceRect 的裁剪帧。
+class SpriteThumbnailFrame {
+  const SpriteThumbnailFrame({
+    required this.image,
+    required this.sourceRect,
+    required this.spriteUrl,
+    required this.cue,
+  });
+
+  final ui.Image image;
+  final ui.Rect sourceRect;
+  final String spriteUrl;
+  final SpriteThumbnailCue cue;
+}
+
+/// 预览卡片当前应展示的回退阶段。
+enum ScrubPreviewStage { sprite, waitingForAxis, localFrame, cover }
+
+/// 预览回退链的纯判定函数。
+ScrubPreviewStage decideScrubPreviewStage({
+  required bool hasThumbnailsUrl,
+  required bool hasSpriteFrame,
+  required bool hasAxis,
+  required bool hasLocalFrame,
+}) {
+  if (hasSpriteFrame) return ScrubPreviewStage.sprite;
+  if (hasThumbnailsUrl && !hasAxis) {
+    return ScrubPreviewStage.waitingForAxis;
+  }
+  if (hasLocalFrame) return ScrubPreviewStage.localFrame;
+  return ScrubPreviewStage.cover;
+}
+
+/// 解析 WebVTT；任意异常都收敛为空轴。
+SpriteThumbnailAxis parseSpriteThumbnailVtt(
+  String source, {
+  required String vttUrl,
+}) {
+  final cues = <SpriteThumbnailCue>[];
+  try {
+    for (final block
+        in source.replaceAll('\r\n', '\n').split(RegExp(r'\n\s*\n'))) {
+      final cue = _parseCueBlock(block);
+      if (cue != null) cues.add(cue);
+    }
+  } catch (_) {
+    return SpriteThumbnailAxis.empty(vttUrl);
+  }
+  cues.sort((left, right) => left.start.compareTo(right.start));
+  return SpriteThumbnailAxis(vttUrl: vttUrl, cues: cues);
+}
+
+/// 按 position 二分选择 cue；边界外选择最近 cue。
+SpriteThumbnailCue? selectSpriteThumbnailCue(
+  List<SpriteThumbnailCue> cues,
+  Duration position,
+) {
+  if (cues.isEmpty) return null;
+  var low = 0;
+  var high = cues.length;
+  while (low < high) {
+    final middle = (low + high) >> 1;
+    if (cues[middle].start <= position) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  if (low == 0) return cues.first;
+  final previous = cues[low - 1];
+  if (low == cues.length || position <= previous.end) return previous;
+  final next = cues[low];
+  final previousDistance = position - previous.end;
+  final nextDistance = next.start - position;
+  return previousDistance <= nextDistance ? previous : next;
+}
+
+/// 只读缓存接口，便于 widget 测试注入。
+abstract interface class SpriteThumbnailAxisSource implements Listenable {
+  SpriteThumbnailFrame? cachedFrameAt(String? thumbnailsUrl, Duration position);
+
+  bool hasAxis(String? thumbnailsUrl);
+}
+
+/// VTT 时间轴、cue 二分与 sprite ui.Image LRU 缓存。
+class SpriteThumbnailAxisService extends ChangeNotifier
+    implements SpriteThumbnailAxisSource {
+  SpriteThumbnailAxisService({
+    SpriteThumbnailAssetLoader? loader,
+    this.cacheTtl = spriteVttCacheTtl,
+    DateTime Function()? now,
+  }) : _loader = loader ?? DioSpriteThumbnailAssetLoader(),
+       _now = now ?? DateTime.now;
+
+  final SpriteThumbnailAssetLoader _loader;
+  final Duration cacheTtl;
+  final DateTime Function() _now;
+  final Map<String, _CachedAxis> _axisCache = {};
+  final Map<String, Future<SpriteThumbnailAxis>> _axisRequests = {};
+  final LinkedHashMap<String, _CachedSprite> _spriteCache = LinkedHashMap();
+  final Map<String, Future<_CachedSprite?>> _spriteRequests = {};
+  final Set<String> _failedSprites = {};
+  String? _activeAxisUrl;
+  int _axisGeneration = 0;
+  bool _disposed = false;
+
+  @visibleForTesting
+  int get spriteCacheSize => _spriteCache.length;
+
+  @visibleForTesting
+  List<String> get spriteCacheKeys => _spriteCache.keys.toList();
+
+  /// 播放器就绪时预取当前 cue 与相邻 sprite，拖动帧不触发网络或解码。
+  Future<void> prepareAt(String? thumbnailsUrl, Duration position) async {
+    final url = _normalizeUrl(thumbnailsUrl);
+    if (_disposed || url == null) return;
+    _activateAxis(url);
+    final axis = await _loadAxis(url);
+    if (_disposed || _activeAxisUrl != url) return;
+    for (final cue in _prefetchCues(axis, position)) {
+      await _ensureSprite(axis, cue);
+    }
+  }
+
+  @override
+  bool hasAxis(String? thumbnailsUrl) {
+    final url = _normalizeUrl(thumbnailsUrl);
+    if (url == null || url != _activeAxisUrl) return false;
+    return _readAxis(url) != null;
+  }
+
+  @override
+  SpriteThumbnailFrame? cachedFrameAt(
+    String? thumbnailsUrl,
+    Duration position,
+  ) {
+    final url = _normalizeUrl(thumbnailsUrl);
+    if (url == null || url != _activeAxisUrl) return null;
+    final axis = _readAxis(url);
+    if (axis == null) return null;
+    final cue = selectSpriteThumbnailCue(axis.cues, position);
+    if (cue == null) return null;
+    final cached = _readSprite(cue.spriteFile);
+    if (cached == null) return null;
+    final sourceRect = _scaledSourceRect(cached, cue.sourceRect);
+    if (sourceRect == null) return null;
+    return SpriteThumbnailFrame(
+      image: cached.decoded.image,
+      sourceRect: sourceRect,
+      spriteUrl: axis.resolveSpriteUri(cue.spriteFile).toString(),
+      cue: cue,
+    );
+  }
+
+  /// 页面销毁时释放全部 VTT 与 ui.Image 内存。
+  @override
+  void dispose() {
+    if (_disposed) return;
+    _disposed = true;
+    _clearAll();
+    super.dispose();
+  }
+
+  void _activateAxis(String url) {
+    if (_activeAxisUrl == url) return;
+    _activeAxisUrl = url;
+    _axisGeneration++;
+    _clearSprites();
+  }
+
+  Future<SpriteThumbnailAxis> _loadAxis(String url) {
+    final cached = _readAxis(url);
+    if (cached != null) return Future.value(cached);
+    final existing = _axisRequests[url];
+    if (existing != null) return existing;
+    final request = _fetchAxis(url);
+    _axisRequests[url] = request;
+    return request.whenComplete(() {
+      _axisRequests.remove(url);
+    });
+  }
+
+  Future<SpriteThumbnailAxis> _fetchAxis(String url) async {
+    for (var attempt = 0; attempt < 2; attempt++) {
+      try {
+        final text = await _loader.loadVtt(Uri.parse(url));
+        final axis = text == null
+            ? SpriteThumbnailAxis.empty(url)
+            : parseSpriteThumbnailVtt(text, vttUrl: url);
+        if (_disposed) return SpriteThumbnailAxis.empty(url);
+        _cacheAxis(axis);
+        notifyListeners();
+        return axis;
+      } on SpriteThumbnailForbiddenException {
+        if (_disposed) return SpriteThumbnailAxis.empty(url);
+        _axisCache.remove(url);
+        if (_activeAxisUrl == url) _clearSprites();
+      } catch (_) {
+        break;
+      }
+    }
+    final empty = SpriteThumbnailAxis.empty(url);
+    if (_disposed) return empty;
+    _cacheAxis(empty);
+    notifyListeners();
+    return empty;
+  }
+
+  void _cacheAxis(SpriteThumbnailAxis axis) {
+    _axisCache[axis.vttUrl] = _CachedAxis(
+      axis: axis,
+      expiresAt: _now().add(cacheTtl),
+    );
+  }
+
+  SpriteThumbnailAxis? _readAxis(String url) {
+    final cached = _axisCache[url];
+    if (cached == null) return null;
+    if (cached.expiresAt.isAfter(_now())) return cached.axis;
+    _axisCache.remove(url);
+    return null;
+  }
+
+  List<SpriteThumbnailCue> _prefetchCues(
+    SpriteThumbnailAxis axis,
+    Duration position,
+  ) {
+    final current = selectSpriteThumbnailCue(axis.cues, position);
+    if (current == null) return const [];
+    final index = axis.cues.indexOf(current);
+    final candidates = <SpriteThumbnailCue>[current];
+    for (final direction in const [1, -1]) {
+      for (var step = 1; step < axis.cues.length; step++) {
+        final neighborIndex = index + direction * step;
+        if (neighborIndex < 0 || neighborIndex >= axis.cues.length) break;
+        final neighbor = axis.cues[neighborIndex];
+        if (neighbor.spriteFile != current.spriteFile) {
+          candidates.add(neighbor);
+          break;
+        }
+      }
+      if (candidates.length > 1) break;
+    }
+    return candidates;
+  }
+
+  Future<_CachedSprite?> _ensureSprite(
+    SpriteThumbnailAxis axis,
+    SpriteThumbnailCue cue,
+  ) {
+    final cached = _readSprite(cue.spriteFile);
+    if (cached != null) return Future.value(cached);
+    if (_failedSprites.contains(cue.spriteFile)) return Future.value();
+    final existing = _spriteRequests[cue.spriteFile];
+    if (existing != null) return existing;
+    final generation = _axisGeneration;
+    final request = _loadSprite(axis, cue, generation);
+    _spriteRequests[cue.spriteFile] = request;
+    return request.whenComplete(() {
+      _spriteRequests.remove(cue.spriteFile);
+    });
+  }
+
+  Future<_CachedSprite?> _loadSprite(
+    SpriteThumbnailAxis axis,
+    SpriteThumbnailCue cue,
+    int generation,
+  ) async {
+    SpriteThumbnailDecodedImage? decoded;
+    try {
+      decoded = await _loader.loadSprite(axis.resolveSpriteUri(cue.spriteFile));
+    } catch (_) {
+      decoded = null;
+    }
+    if (decoded == null) {
+      _failedSprites.add(cue.spriteFile);
+      if (!_disposed) notifyListeners();
+      return null;
+    }
+    if (_disposed || generation != _axisGeneration) {
+      decoded.image.dispose();
+      return null;
+    }
+    final cached = _CachedSprite(decoded);
+    _putSprite(cue.spriteFile, cached);
+    notifyListeners();
+    return cached;
+  }
+
+  _CachedSprite? _readSprite(String key) {
+    final value = _spriteCache.remove(key);
+    if (value == null) return null;
+    _spriteCache[key] = value;
+    return value;
+  }
+
+  void _putSprite(String key, _CachedSprite value) {
+    _spriteCache.remove(key)?.decoded.image.dispose();
+    _spriteCache[key] = value;
+    while (_spriteCache.length > spriteImageCacheCapacity) {
+      final oldest = _spriteCache.remove(_spriteCache.keys.first);
+      oldest?.decoded.image.dispose();
+    }
+  }
+
+  ui.Rect? _scaledSourceRect(_CachedSprite cached, ui.Rect source) {
+    final scaleX = cached.decoded.image.width / cached.decoded.originalWidth;
+    final scaleY = cached.decoded.image.height / cached.decoded.originalHeight;
+    final scaled =
+        ui.Rect.fromLTWH(
+          source.left * scaleX,
+          source.top * scaleY,
+          source.width * scaleX,
+          source.height * scaleY,
+        ).intersect(
+          ui.Rect.fromLTWH(
+            0,
+            0,
+            cached.decoded.image.width.toDouble(),
+            cached.decoded.image.height.toDouble(),
+          ),
+        );
+    return scaled.isEmpty ? null : scaled;
+  }
+
+  void _clearSprites() {
+    for (final cached in _spriteCache.values) {
+      cached.decoded.image.dispose();
+    }
+    _spriteCache.clear();
+    _spriteRequests.clear();
+    _failedSprites.clear();
+  }
+
+  void _clearAll() {
+    _axisGeneration++;
+    _activeAxisUrl = null;
+    _axisCache.clear();
+    _axisRequests.clear();
+    _clearSprites();
+  }
+
+  String? _normalizeUrl(String? url) {
+    final trimmed = url?.trim() ?? '';
+    if (trimmed.isEmpty) return null;
+    return AppConfig.mediaUrl(trimmed);
+  }
+}
+
+final RegExp _timingPattern = RegExp(
+  r'^(\d{2,}:\d{2}:\d{2}\.\d{3})\s*-->\s*(\d{2,}:\d{2}:\d{2}\.\d{3})',
+);
+final RegExp _cueLinkPattern = RegExp(r'^(\S+?)#xywh=(.+)$');
+final RegExp _xywhPattern = RegExp(r'^(\d+),(\d+),(\d+),(\d+)$');
+
+SpriteThumbnailCue? _parseCueBlock(String block) {
+  final lines = block
+      .split('\n')
+      .map((line) => line.trim())
+      .where((line) => line.isNotEmpty)
+      .toList();
+  final timingIndex = lines.indexWhere(_timingPattern.hasMatch);
+  if (timingIndex < 0 || timingIndex + 1 >= lines.length) return null;
+  final timing = _timingPattern.firstMatch(lines[timingIndex]);
+  if (timing == null) return null;
+  final link = _cueLinkPattern.firstMatch(lines[timingIndex + 1]);
+  if (link == null) return null;
+  final start = _parseTimestamp(timing.group(1)!);
+  final end = _parseTimestamp(timing.group(2)!);
+  if (start == null || end == null || end <= start) return null;
+  final segments = Uri.tryParse(link.group(1)!)?.pathSegments;
+  final file = segments == null || segments.isEmpty ? null : segments.last;
+  final xywh = _xywhPattern.firstMatch(link.group(2)!);
+  if (file == null || file.isEmpty || xywh == null) return null;
+  final rect = ui.Rect.fromLTWH(
+    double.parse(xywh.group(1)!),
+    double.parse(xywh.group(2)!),
+    double.parse(xywh.group(3)!),
+    double.parse(xywh.group(4)!),
+  );
+  if (rect.isEmpty) return null;
+  return SpriteThumbnailCue(
+    start: start,
+    end: end,
+    spriteFile: file,
+    sourceRect: rect,
+  );
+}
+
+Duration? _parseTimestamp(String value) {
+  final parts = value.split(':');
+  if (parts.length != 3) return null;
+  final secondsParts = parts[2].split('.');
+  if (secondsParts.length != 2) return null;
+  final hours = int.tryParse(parts[0]);
+  final minutes = int.tryParse(parts[1]);
+  final seconds = int.tryParse(secondsParts[0]);
+  final milliseconds = int.tryParse(secondsParts[1]);
+  if ([hours, minutes, seconds, milliseconds].contains(null)) return null;
+  return Duration(
+    hours: hours!,
+    minutes: minutes!,
+    seconds: seconds!,
+    milliseconds: milliseconds!,
+  );
+}
+
+class _CachedAxis {
+  const _CachedAxis({required this.axis, required this.expiresAt});
+
+  final SpriteThumbnailAxis axis;
+  final DateTime expiresAt;
+}
+
+class _CachedSprite {
+  const _CachedSprite(this.decoded);
+
+  final SpriteThumbnailDecodedImage decoded;
+}