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

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