VideoModel 是火山引擎播放器 SDK 针对多清晰度场景推出的面向极致体验的自研协议。通过 VideoModel，您可以将包含多清晰度、多格式视频流的复杂信息整合为单个对象，并直接将这些信息传递给播放器 SDK 进行播放。使用 VideoModel 具有以下优势：

• 降低首帧耗时：与 Vid 模式（播放器 SDK 通过 Vid 请求视频点播服务端获取播放信息）相比，通过 VideoModel 播放，可以减少一次客户端到视频点播服务端的网络请求。您的业务服务端可以直接生成或者客户端组装生成VideoModel播放源，将其传给播放器 SDK 即可开始加载，从而有效缩短视频首帧的加载时间。
• 功能完整性：VideoModel 完整地承载了视频点播的所有能力，包括 ABR、平滑切换、私有加密等。
• 灵活性高：您可以完全掌控 VideoModel 的生成和下发时机，更好地与您的业务逻辑集成。

本文将指导您如何根据不同的视频数据来源，构造 VideoModel 播放源。

数据流转路径 #

VideoModel 的构造方式取决于您的视频数据来源。主要分为以下两种路径：

• 视频数据来自第三方服务或自定义数据：
  1. 业务服务端从第三方服务获取视频数据，并将其组装成自定义的数据结构下发给客户端。
  2. 业务客户端收到数据后，需要逐个调用 Builder 的 set 方法（如 setUrl、setBitrate 等），将各路视频流的信息填充到 IVideoModel 对象中。
• 视频数据来自火山引擎视频点播服务：
  1. 业务服务端调用视频点播的 GetPlayInfo 接口，获取包含视频元数据的 JSON 字符串。
  2. 业务服务端将此 JSON 字符串通过业务 API 下发给客户端。
  3. 业务客户端收到 JSON 字符串后，直接使用 SDK 提供的方法，一步到位地将其转换为 IVideoModel 对象，无需手动解析和设置字段。

构造 VideoModel 播放源 #

步骤 1：构造 IVideoModel #

方式 1：手动设置字段构造（适用于视频数据来自第三方服务或自定义数据）

假设您的业务数据模型 VideoItem 如下：

// 业务视频 Model
public class VideoItem {
    public String videoId;
    public long durationInS;
    public List<StreamItem> streamItems;

    // 每一个 StreamItem 代表一路特定清晰度的视频流
    public static class StreamItem {
        public String url;
        public String cacheKey;
        public String codecType; // "h264", "h265"
        public String format;    // "dash", "hls", "mp4"
        public int width;
        public int height;
        public int bitrate;
        public Resolution resolution;
        public String playAuth;  // 私有 DRM 密钥
    }
}

您可以参考以下示例代码，将 VideoItem 对象转换为 IVideoModel：

public static IVideoModel createVideoModel(VideoItem videoItem) {
    List<VideoInfo> videoInfos = new ArrayList<>();
    // 遍历所有清晰度流，为每一路流创建一个 VideoInfo 对象
    for (VideoItem.StreamItem streamItem : videoItem.streamItems) {
        videoInfos.add(new BareVideoInfo
                .Builder()
                // --- 基础信息 ---
                .urls(Arrays.asList(streamItem.url)) // 视频流的 URL 列表。**必须设置**。
                .fileHash(streamItem.cacheKey)       // 视频流的唯一缓存 Key。**必须设置**。
                .resolution(streamItem.resolution) // 清晰度档位枚举。**必须设置**。
                .codecType(streamItem.codecType)     // 编码类型 (如 "h264", "h265")。**必须设置**。
                
                // --- ABR 与平滑切换所需信息 ---
                .bitrate(streamItem.bitrate) // 码率 (单位: bps)。是 ABR 和平滑切换的必要字段。
                .vWidth(streamItem.width)    // 视频宽度。是 ABR 的必要字段。
                .vHeight(streamItem.height)  // 视频高度。是 ABR 的必要字段。
                .format(streamItem.format)   // 格式类型 (如 "dash", "hls")。是 ABR 和平滑切换的必要字段。
                .mediaType(VideoRef.TYPE_VIDEO) // 流类型。对于 DASH 播放，必须明确设置为 video 或 audio。
                
                // --- DRM 加密所需信息 ---
                .spadea(streamItem.playAuth) // 私有 DRM 密钥 (playAuth)，用于解密视频流。
                .build());
    }
    
    // 将所有 VideoInfo 聚合到一个 BareVideoModel 中
    return new BareVideoModel.Builder()
            .vid(videoItem.videoId)              // 视频的唯一 ID。**必须设置**。
            .duration(videoItem.durationInS)     // 视频总时长（单位：秒）。
            .setVideoInfos(videoInfos)           // 包含所有清晰度流的列表。**必须设置**。
            .adaptive(true)                      // 如需支持平滑切换或 ABR，必须设置为 true。
            .dynamicType(TTVideoEngine.DYNAMIC_TYPE_SEGMENT_BASE) // 当 format 为 dash 或 fmp4 时需要设置。
            .build();
}

方式 2：通过 JSON 直接构造（适用于视频数据来自火山引擎视频点播服务）

您的业务服务端获取到视频点播 GetPlayInfo 接口返回的 JSON 字符串时，可以使用以下方法将其转换为 IVideoModel 对象。

/**
 * 从 JSON 字符串创建 IVideoModel 实例的辅助方法。
 * @param jsonModel 来自火山引擎视频点播 GetPlayInfo 接口的 JSON 字符串。
 * @return 一个 IVideoModel 实例；如果解析失败则返回 null。
 */
@Nullable
static IVideoModel create(String jsonModel) {
    if (TextUtils.isEmpty(jsonModel)) return null;

    VideoRef ref = new VideoRef();
    try {
        ref.extractFields(new JSONObject(jsonModel));
        VideoModel model = new VideoModel();
        model.setVideoRef(ref);
        return model;
    } catch (Throwable throwable) {
        return null;
    }
}

传入的 JSON 字符串应该是 GetPlayInfo 接口响应体中 Result 字段对应的 JSON 对象，而非整个响应的字符串。Result 对象结构示例如下：

{
    "Vid": "v029c1g10003civ2i5mqib*******",
    "Status": 1,
    "PosterUrl": "https://img.***.com/1234/8511abe****.jpeg",
    "Duration": 0.1,
    "FileType": "video",
    "EnableAdaptive": true,
    "TotalCount": 1
    // ... 更多字段
}

步骤 2：封装为 VideoModelSource #

无论 IVideoModel 是通过哪些方式构造的，您都需要将其封装为播放器 SDK 可识别的 VideoModelSource 对象。

public static VideoModelSource createVideoModelSource(IVideoModel videoModel) {
    // 构造 VideoModelSource 
    final VideoModelSource videoModelSource = new VideoModelSource.Builder()
            // 视频 ID，必须与 IVideoModel 中设置的 vid 保持一致。
            .setVid(videoModel.getVideoRefStr(VideoRef.VALUE_VIDEO_REF_VIDEO_ID))
            // 传入上一步创建的 IVideoModel 对象。**必须设置**。
            .setVideoModel(videoModel)
            // （可选）指定起播清晰度。若要实现智能起播选档或 ABR，则无需设置此项。
            .setResolution(Resolution.Standard)
            .build();
    return videoModelSource;
}

进阶使用 #

（可选）开启 VideoModel 播放失败重试策略 #

在构造并设置 VideoModelSource 后，您还可以通过开启特定的播放器选项来优化播放体验。当您遇到因网络波动（如 socket 接收数据超时，错误码：-499793；私有加密视频播放失败，错误码：-499897）或数据源异常导致的播放失败时，可开启 PLAYER_OPTION_OPTIMIZE_VIDEO_MODEL_RETRY_STRATEGY 选项。

• 默认行为（关闭）：播放失败后，播放器会尝试使用备用 URL（如果存在）。
• 开启后行为：播放失败后，播放器会优先对当前失败的 URL 进行重试，而不是直接切换到备用 URL。这有助于在临时网络抖动的情况下快速恢复播放。

开启方法：在设置播放源之前，通过 setIntOption 方法开启 PLAYER_OPTION_OPTIMIZE_VIDEO_MODEL_RETRY_STRATEGY 选项。

// 1. 初始化播放器引擎
TTVideoEngine mTTVideoEngine = new TTVideoEngine(context, 0);

// 2. 开启 VideoModel 播放失败重试策略
// 该选项默认关闭（值为 0），设置为 1 可开启。
mTTVideoEngine.setIntOption(PLAYER_OPTION_OPTIMIZE_VIDEO_MODEL_RETRY_STRATEGY, 1);

// 3. 设置 VideoModelSource 播放源
// videoModelSource 是您在步骤 2 中创建的对象。
mTTVideoEngine.setVideoModelSource(videoModelSource);

// 4. 开始播放
mTTVideoEngine.play();