快速开始--视频点播-火山引擎

文档中心

立即注册

视频点播

不含 UI 集成方案

快速开始

本文介绍如何用播放器 SDK 以最简单快捷的方式让视频播放起来。

适用版本

本文适用于播放器 SDK 1.27.1.3 及之后的版本。更早版本请见 Android 播放器 SDK 使用文档（历史版本）。

前提条件

已完成集成 SDK。

开源示例项目

Github 地址：Demo-Android

操作步骤

步骤 1：开启日志调试

初始化播放器 SDK 之前，建议您先开启日志，便于调试和排查问题。

注意

线上版本请务必关闭日志，减少性能开销。

示例代码如下：

// （1.41.2.10 及之后版本）开启 SDK 全部模块日志
VodSDK.openAllVodLog();

// （1.41.2.10 之前版本）开启 SDK 各个模块的日志
// 开启 ttsdk 模块日志
// TTVideoLog.turnOn(TTVideoLog.LOG_DEBUG, 1);
// 开启 CacheModule 模块日志
// CmLog.turnLogLevel(CmLog.LogLevel.D, true);
// 开启 Engine 模块日志
// TTVideoEngineLog.turnOn(TTVideoEngineLog.LOG_DEBUG, 1);
// 开启数据加载模块日志
// AVMDLLog.turnOn(AVMDLLog.LOG_DEBUG, 1);
// 开启 License 模块日志
// LicenseManager.turnOnLogcat(true);

步骤 2：初始化 SDK

初始化操作是轻量的，建议在 Application#onCreate 中执行初始化，保障初始化顺序。

File videoCacheDir = new File(context.getCacheDir(), "video_cache");
if (!videoCacheDir.exists()) videoCacheDir.mkdirs();
VodConfig.Builder vodBuilder = new VodConfig.Builder(context)
        .setCacheDirPath(videoCacheDir.getAbsolutePath())
        .setMaxCacheSize(300 * 1024 * 1024);
        
Env.start(new Config.Builder()
        .setApplicationContext(context)
        .setAppID("your app id")
        .setAppName("your app English name")
        // 合法版本号应大于、等于 2 个分隔符，如："1.3.2"
        .setAppVersion(BuildConfig.VERSION_NAME)
        .setAppChannel("channel name")
        // 将 license 文件拷贝到 app 的 assets 文件夹中，并设置 LicenseUri  
        // 下面 LicenseUri 对应工程中 assets 路径为：assets/license/vod.lic
        .setLicenseUri("assets:///license/vod.lic")
        // 可不设置，默认值见下表
        .setVodConfig(vodBuilder.build())
        .setBizType(BIZ_TYPE_VOD)
        .build());

详细的参数说明如下表所示。

参数	类型	是否必填	说明
AppId	String	必填	应用 ID。可在视频点播控制台应用管理页面获取。详情请见应用管理。
AppName	String	必填	应用的英文名称。可在视频点播控制台应用管理页面获取。详情请见应用管理。
AppVersion	String	必填	App 版本号。可设为 `BuildConfig.VERSION_NAME`。合法版本号应包含大于或等于 2 个分隔符，如 `1.3.2`。
AppChannel	String	必填	渠道号。由您自定义，如小米应用商店 (`xiaomi`)、华为应用市场 (`huawei`) 等。
LicenseUri	String	必填	License 文件路径。详情请见 License 使用说明。
CacheDirPath	String	选填	视频缓存路径，默认值为 `/data/user/0/包名/cache/video_cache`。
MaxCacheSize	Integer	选填	视频缓存文件夹大小，默认值为 300 * 1024 * 1024 (300 MB)。

步骤 3：自定义设备 ID

初始化播放器 SDK 后，您可自定义设备 ID，用于实现单点追查功能，以便在视频点播控制台质量平台的单点追查页面查看单设备的播放数据。详细信息请见单点追查。示例代码如下：

// 初始化自定义 ID
private void initVodSDK(Context context, String userUniqueId) {
    // 1. 根据步骤 2 初始化播放器 SDK
    Env.init(new Config.Builder()
        // ... 省略
        .build());
    // 2. 获取 AppLog 实例设置 userUniqueId
    IAppLogInstance applog = AppLogWrapper.getAppLogInstance();
    if (applog != null && !TextUtils.isEmpty(userUniqueId)) {
        applog.setUserUniqueID(userUniqueId); 
    }
}

// 您的用户注销登录时调用
private void onUserLogout() {
    IAppLogInstance applog = AppLogWrapper.getAppLogInstance();
    if (applog != null) {
        applog.setUserUniqueID(null);
    }
}

// 登录成功/切换后调用
private void onUserLogin(String userUniqueId) {
    IAppLogInstance applog = AppLogWrapper.getAppLogInstance();
    if (applog != null) {
        applog.setUserUniqueID(userUniqueId);
    }
}

步骤 4：创建播放器

参考以下示例代码创建 TTVideoEngine 播放器实例。

注意

为确保播放效果，建议每次播放时创建新的 Engine 实例，而非复用 Engine 实例。

// context 建议传入 application context
TTVideoEngine ttVideoEngine = new TTVideoEngine(context, TTVideoEngine.PLAYER_TYPE_OWN);

步骤 5：设置显示视图

播放器支持设置显示画面的视图。播放器支持关联以下两种视图：

TextureView

SurfaceView

在布局文件中声明 TextureView：
```
<TextureView
    android:id="@+id/textureView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@null" />
```
注意
如果 targetSDKVersion ≥ API 24，在布局文件中声明 TextureView 时，必须将 background 设置为 null 或不设置 background，否则会 crash。

调用 TTVideoEngine 的 setSurface 方法，将 TextureView 中的 SurfaceTexture 对象包装成 Surface 对象设置给 TTVideoEngine ，即可完成播放器和 TextureView 的关联。播放器播放的视频数据就可以通过 TextureView 显示。示例代码如下：

TextureView textureView = findViewById(R.id.textureView);
// 设置 SurfaceTexture 监听
textureView.setSurfaceTextureListener(new TextureView.SurfaceTextureListener() {
    // TextureView 的 SurfaceTexture 创建完成回调
    @Override
    public void onSurfaceTextureAvailable(SurfaceTexture surfaceTexture, int width, int height) {
        // 将 SurfaceTexture 设置给 TTVideoEngine
        ttVideoEngine.setSurface(new Surface(surfaceTexture));
    }
    @Override
    public void onSurfaceTextureSizeChanged(SurfaceTexture surfaceTexture, int width, int height) { 
    }
    @Override
    public boolean onSurfaceTextureDestroyed(SurfaceTexture surfaceTexture) {
        return true;
    }
    @Override
    public void onSurfaceTextureUpdated(SurfaceTexture surfaceTexture) {
    }
});

在布局文件中声明 SurfaceView：

<SurfaceView
    android:id="@+id/surfaceView"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

调用 TTVideoEngine 的 setSurfaceHolder 方法，将 SurfaceView 的 SurfaceHolder 设置给 TTVideoEngine，即可完成播放器和 SurfaceView 的关联。播放器播放的视频数据就可以通过 TextureView 显示。示例代码如下：
```
SurfaceView surfaceView = findViewById(R.id.surfaceView);
ttVideoEngine.setSurfaceHolder(surfaceView.getHolder());
```
注意
从 API 24 开始，SurfaceView 支持与 View tree 中其他 View 同步 Window 的位置渲染。但在低于 API 24 的版本中，由于不支持同步渲染，可能会出现视图层级错乱和动画不同步的问题。更多信息，请见 SurfaceView。

注意

您必须先调用 TTVideoEngine 的 setSurface 或 setSurfaceHolder 方法，再调用 play 方法。
TextureView 或 SurfaceView 的父布局需要使用 FrameLayout。

步骤 6：设置播放源

播放器 SDK 支持多种播放源，您可以根据视频的来源和业务场景选择最合适的方式。

Vid 播放源

DirectUrl 播放源

本地播放源

VideoModel 播放源

适用于播放已上传至火山引擎视频点播服务的视频。通过视频的 Vid 和其对应的临时播放凭证 PlayAuthToken 来指定播放内容。这两个参数通常由您的业务服务端下发，客户端直接使用即可。详情请见通过临时播放 Token 播放。

// 开启 VideoModel 缓存，提升后续播放体验
ttVideoEngine.setIntOption(PLAYER_OPTION_USE_VIDEOMODEL_CACHE, 1);

final String vid = "your_video_id"; // 由您的业务服务端提供
final String playAuthToken = "your_play_auth_token"; // 由您的业务服务端提供

final String encodeType = TTVideoEngine.CODEC_TYPE_H264;
// final String encodeType = TTVideoEngine.CODEC_TYPE_h265;
// final String encodeType = TTVideoEngine.CODEC_TYPE_h266;

// 1. 构造 VidSource
StrategySource vidSource = new VidPlayAuthTokenSource.Builder()
        .setVid(vid)
        .setPlayAuthToken(playAuthToken)
        // （可选）设置视频编码类型（h264，h265、h266），默认为 h264
        .setEncodeType(encodeType)
        // （可选）指定起播清晰度，此处演示设为 480P。不传使用默认值 360P
        .setResolution(Resolution.High)
        .build();
// 2. 设置播放源
ttVideoEngine.setStrategySource(vidSource);
// 3. 开始播放
ttVideoEngine.play()

适用于播放来自火山引擎或第三方 CDN 的视频 URL 地址。通过传入视频的直接播放地址进行播放。除了 url，您还必须提供以下两个关键参数：

vid：视频的唯一标识。可以是您自己的视频管理系统中的唯一标识，也可以在 App 层自行生成一个 ID。此 ID 会用于播放器 SDK 的日志上报、预加载、预渲染等功能中。
cacheKey：视频的缓存索引 Key。为确保唯一性，推荐使用 URL 的 MD5 值。建议 cacheKey 仅包含字母和数字，避免使用特殊符号，以免影响下载功能。

final String vid = "your_unique_video_id"; // 必须与视频一一对应
final String url = "http://www.example.com/video.mp4";
final String cacheKey = TTVideoEngine.computeMD5(url); // 推荐使用 URL 的 MD5

// 1. 构造 DirectUrlSource
StrategySource directUrlSource = new DirectUrlSource.Builder()
        .setVid(vid)
        .addItem(new DirectUrlSource.UrlItem.Builder()
                .setUrl(url)
                .setCacheKey(cacheKey)
                .build())
        .build();
       
// 2. 设置播放源
ttVideoEngine.setStrategySource(directUrlSource);
// 3. 开始播放
ttVideoEngine.play()

适用于播放存储在设备本地的视频文件。通过提供视频文件的本地绝对路径进行播放。

// 1. 指定本地视频文件的路径
File videoFile = new File("/sdcard/Download/video.MP4");
// 2. 设置本地播放地址并播放
ttVideoEngine.setLocalURL(videoFile.getAbsolutePath());
ttVideoEngine.play()

适用于对首帧性能有极致要求，且需要精细化控制多清晰度信息的业务场景。VideoModel 是火山引擎播放器 SDK 针对多清晰度场景推出的面向极致体验的自研协议。与 Vid 模式相比，通过 VideoModel 播放可以减少一次客户端到视频点播服务端的网络请求，有效降低视频首帧耗时。以下为设置 VideoModel 播放源的示例：

说明

VideoModel 构造方式较为复杂，详细说明请参见构造 VideoModel 播放源。

// 假设 videoModelSource 是您通过业务数据构造好的对象
VideoModelSource videoModelSource = createVideoModelSource();

// 1. 设置播放源
ttVideoEngine.setStrategySource(videoModelSource);
// 2. 开始播放
ttVideoEngine.play();

步骤 7：释放播放器

如果视频播放结束，或者用户离开了视频播放页面，就要及时停止播放，并释放 TTVideoEngine 实例。调用 releaseAsync 方法，可以释放 TTVideoEngine 的硬件解码器占用、内存占用、网络占用，能有效帮助用户节省电量。

ttVideoEngine.releaseAsync();

步骤 8：集成 Debug 工具

为了提升接入和调试效率，建议您集成可视化的 Debug 工具，直观方便地观察 SDK 相关信息。支持查看播放日志、视频信息和初始化信息，在接入过程中，展示当前播放视频的详细信息，以及在异常或错误状态下的相应提示。详细操作请参见 Debug 工具说明。

后续操作

至此，我们已经可以让视频播放起来了。虽然只有简单的开始播放与结束播放，还不能满足产品需求，但我们已经基本掌握了播放器 SDK 的核心使用方式。下面我们演示如何实现更多的播放功能，详见基础功能。

注意

强烈推荐您使用最佳策略，能够快速实现零首帧体验的短视频播放效果。详情请见 Android 短视频场景。

最近更新时间：2025.10.11 18:00:20

这个页面对您有帮助吗？

有用

无用