能力概述 #

播放源自动刷新用于解决签名播放地址有时效的问题。火山引擎 VOD 的播放 URL 通常带有签名鉴权参数（如 auth_key、过期时间戳），长视频播放、后台挂起后恢复、HLS 长拉流等场景下，URL 可能在播放过程中过期，导致拉流失败、卡住或报错。

开启本能力后，SDK 在检测到地址过期或分片错误时，会主动回调到业务层索取新的播放地址并热替换，播放过程无感知、不中断。

快速接入 #

三步即可接入：实现回调 → 注册回调 → 起播前开启策略。

import 'package:ve_vod/ve_vod.dart';

// 1. 实现业务刷新回调
class MyUrlRefreshCallback implements TTVideoEngineUrlRefreshCallback {
  @override
  Future<dynamic> refreshUrl(TTVideoEngineUrlRequest request) async {
    // request.url / request.cacheKey / request.vid
    // 向业务服务端换取新的播放信息（可返回 GetPlayInfo 的 PlayInfoList）
    final playInfoList = await fetchNewPlayInfoList(request.vid);
    return playInfoList;
    // 也可直接返回 TTVideoEngineUrlResult(url: newUrl, expireTimeInMS: ts);
  }

  @override
  void cancel() {
    // 取消正在进行的网络请求
  }
}

// 2. 注册回调（建议在 App 启动或进入播放页时）
TTVideoEngineSourceRefreshStrategy.setUrlRefreshCallback(
  MyUrlRefreshCallback(),
);

// 3. 起播前开启策略，然后再设置播放源
await player.enableSourceRefreshStrategy(enableHlsSegError: true);
await player.setMediaSource(mediaSource);

接口说明 #

业务需实现的回调接口 #

abstract class TTVideoEngineUrlRefreshCallback {
  /// 刷新过期的 URL。可返回 TTVideoEngineUrlResult，
  /// 或返回包含全部播放地址的 MediaSource / Map / List，由 SDK 自动匹配。
  Future<dynamic> refreshUrl(TTVideoEngineUrlRequest request);

  /// 取消正在进行的刷新操作
  void cancel();
}

请求与结果模型 #

策略管理类 TTVideoEngineSourceRefreshStrategy（静态） #

播放器实例开关 VodPlayerFlutter #

/// 启用源过期自动刷新
/// [enableHlsSegError] 是否启用 HLS 分片错误处理，默认 true
/// 建议在 setMediaSource() 之前调用
Future<void> enableSourceRefreshStrategy({bool enableHlsSegError = true});

/// 禁用源过期自动刷新
Future<void> disableSourceRefreshStrategy();

• enableHlsSegError：开启后，HLS（m3u8）分片因签名过期返回错误时也会触发刷新；纯 MP4 等非 HLS 源可关闭。

刷新结果（refreshUrl 返回值） #

refreshUrl() 的返回值非常灵活，SDK 会自动归一化为一条 {url, expireTimeInMS}。支持以下几种返回形式：

自动匹配逻辑 #

• 以旧 URL 的 path（去掉签名 query）为基准，在新播放信息中查找 path 相同的地址；
• 兼容多种字段命名：urls / MainPlayUrl / BackupPlayUrl、expires / urlExpiredTimes / MainUrlExpire / BackupUrlExpire、playInfoList / PlayInfoList，以及 Result 包裹层；
• 主备地址优先级：依据旧 URL 的 a=0 查询参数判断优先匹配主地址（MainPlayUrl）还是备地址（BackupPlayUrl）。

expireTimeInMS 时间单位 #

过期时间同时兼容秒级与毫秒级时间戳：小于 100000000000 的值会被视为秒并自动 ×1000 转为毫秒。因此服务端无论返回秒级（如 1875780093）还是毫秒级时间戳都能正确解析。

HLS CacheKey 生成（可选） #

HLS 场景下，TS 分片的缓存 key 默认由完整 URL 推导。当签名参数变化时，同一分片可能因 URL 不同而被认为是不同文件，影响缓存命中。可选地注册 generateFileKey 回调，剥离签名参数后生成稳定 cacheKey，保证签名变化时缓存仍唯一且可复用。

typedef GenerateFileKeyCallback = String Function(
    String url, String fileKey, Map<String, String> extraInfo);

String myGenerateFileKey(
    String url, String fileKey, Map<String, String> extraInfo) {
  final uri = Uri.parse(url);
  final params = Map<String, String>.from(uri.queryParameters)
    ..removeWhere((k, v) =>
        k.toLowerCase().contains('token') ||
        k.toLowerCase().contains('sign') ||
        k.toLowerCase().contains('auth'));
  final cleanUrl = uri.replace(queryParameters: params).toString();
  return cleanUrl.hashCode.toString(); // 实际应使用 MD5 等稳定哈希
}

// 注册（可选）
TTVideoEngineSourceRefreshStrategy.setGenerateFileKeyCallback(myGenerateFileKey);

注意事项与 FAQ #