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

适用版本 #

此文档适用于 1.27.1.3 之前的版本。

前提条件 #

您已完成播放器 SDK 的 集成准备。

操作流程 #

按照以下流程，对于简单使用场景，使用播放器 SDK 在 App 中让一个视频播放。

初始化播放器 SDK #

播放器 SDK 对外提供的播放器接口为 TTVideoEngine 在使用前，我们需要初始化 TTVideoEngine 依赖的一些参数和模块。初始化操作很轻量，建议放到 Application#onCreate 中执行保障初始化顺序。

日志调试 #

开发的过程中，可以打开 logcat 日志，获取更多信息，帮助定位问题。SDK 默认是不输出日志的，排查问题可以打开，在 Release 版本一定要关闭，以免引发安全隐患。

TTVideoEngineLog.turnOn(TTVideoEngineLog.LOG_DEBUG, 1); // 1 打开 0 关闭

配置通用参数 #

SDK 内部需访问网络 API 来获取视频数据、传日志等。字节的服务端 API 需要一些通用的参数来做身份校验。

初始化 TTSDK 环境

需要的参数列举如下：

• 参数获取：请参考 管理应用 文档，在控制台“创建应用”后获取。
• 参数集成：

Env.setupSDKEnv(new Env.SdkContextEnv() {
    @Override
    public Context getApplicationContext() {
        return context.getApplicationContext();
    }
    @Override
    public Thread.UncaughtExceptionHandler getUncaughtExceptionHandler() {
        return new Thread.UncaughtExceptionHandler() {
            @Override
            public void uncaughtException(Thread t, Throwable e) {
            }
        };
    }
    @Override
    public String getAppID() {
        return "your app id";
    }
    @Override
    public String getAppName() {
        return "your app name";
    }
    @Override
    public String getAppRegion() {
        return "china";
    }
});

初始化 License 模块

使用 1.13.0.x 及更早版本的客户，请参考： License 2.0 升级说明。

// 开启 License 模块 logcat 输出，排查问题可以开启，release 包不建议开启
// LicenseManager.turnOnLogcat(true);
// 初始化 license 2.0 的 LicenseManager
LicenseManager.init(context);
// license 2.0 的授权文件支持从 app 的 assets 文件夹中直接读取。下面 assets Licenseuri 对应工程中 assets 路径为：assets/license2/license2_test.lic 
String assetsLicenseUri = "assets:///license2/license2_test.lic";
// 将 license uri 添加到 LicenseManager 中即可完成授权文件添加
LicenseManager.getInstance().addLicense(assetsLicenseUri, null);

说明：

• License 获取请参考 请参考 管理应用 文档，在控制台 “创建应用” 后，点击 “购买 License” 获取。
• SDK License 模块对外暴露的接口类为 LicenseManager
• 从火山引擎点播控制台获取到 License 文件后，可拷贝到 app 的 assets 文件夹中，LicenseManager 支持从 assets 文件夹直接加载 License
• 调用 LicenseManager.getInstance().addLicense(String licesnseUri, Callback callback) 方法添加 License。licenseUri 支持 scheme 有：

• 从易用性角度出发，我们强烈推荐使用 assets:// scheme 的 License
• 无论使用哪种 scheme，License 都有自动更新机制。

初始化 TTVideoEngine & AppLog

需要的参数列举如下：

• 参数获取：创建 App 获取 license
• 参数集成：

// 下面填写的参数仅供释义，请填写您自己的参数
Map<String, Object> appinfoMap = new HashMap<>();
appinfoMap.put("appname", "your app name");
appinfoMap.put("appid", 123); // your app id
appinfoMap.put("appchannel", "xiaomi_appstore"); // 设为test_channel不会展示日志
appinfoMap.put("region", "china");
appinfoMap.put("appversion", BuildConfig.VERSION_NAME);
// 初始化点播
TTVideoEngine.setAppInfo(getApplicationContext(), appinfoMap);
// 初始化点播依赖的 AppLog SDK
TTVideoEngine.initAppLog();

初始化数据加载模块 (Media Data Loader) #

Media Data Loader 简称 MDL。TTVideoEngine 播放流媒体视频时，依赖 MDL 下载视频数据，管理视频缓存。在创建 TTVideoEngine 实例前，需配置并开启 MDL 模块。MDL 会代理了播放器的 I/O 模块。在没有缓存的时候，能边缓存边播放，减少播放卡顿。有缓存的时候，使用缓存启播，提升启播速度。

配置 MDL

开启 MDL 前，必须要设置：

• 视频缓存文件夹路径
• 视频缓存文件夹大小

File videoCacheDir = new File(context.getCacheDir(), "video_cache");
if (!videoCacheDir.exists()) videoCacheDir.mkdirs();
// 设置视频缓存文件夹路径, 需保障路径是存在的
TTVideoEngine.setStringValue(DataLoaderHelper.DATALOADER_KEY_STRING_CACHEDIR, videoCacheDir.getAbsolutePath());
// 设置视频缓存文件夹大小
TTVideoEngine.setIntValue(DataLoaderHelper.DATALOADER_KEY_INT_MAXCACHESIZE, 300 * 1024 * 1024); // 300MB
// 开启 hls 支持
TTVideoEngine.setIntValue(DataLoaderHelper.DATALOADER_KEY_INT_ENABLE_HLS, 1);

对于大多数 APP 的使用场景，配置了上面列举的必须参数，就可以了。

开启 MDL

MDL 实例是单例，只需 start 一次即可。

try {
    TTVideoEngine.startDataLoader(context);
} catch (Exception e) {
    // 缓存模块开启失败
    e.printStackTrace();
}

使用 MDL

MDL start 后，TTVideoEngine 实例需设置 MDL 的 Options 才能使用 MDL 进行视频数据加载。

ttVideoEngine.setIntOption(PLAYER_OPTION_ENABLE_DATALOADER, 1);

这点非常重要，经常被忽略。

至此，TTVideoEngine SDK 就初始化完成了。下面演示如何让一段视频播起来。

创建 TTVideoEngine 实例 #

TTVideoEngine 在创建时，支持指定播放内核。对于大多数 APP 而言，推荐使用我们的自研播放器内核，即：TTVideoEngine.PLAYER_TYPE_OWN。

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

TTVideoEngine 实例可以设置 option 来适配不同的使用场景和需求。我们提供了丰富的 option 选项，比如上面介绍的 使用 MDL。一般使用默认设置即可。在后续介绍的 TTVideoEngine 设置播放数据源 部分也会涉及到 option 的配置。

软硬解配置 #

受益于成熟的软硬解适配经验，播放器 SDK 会根据当前机型能力自动选择软/硬解码器，接入方无需关心。若需自定义软硬解码可以通过 option 配置，自定义配置会覆盖默认规则。请在 TTVideoEngine 对象第一次调用 play 方法之前配置。

ttVideoEngine.setIntOption(TTVideoEngine.PLAYER_OPTION_ENABLE_HARDWARE_DECODE, 1); // 1:打开硬解码 0:关闭硬解码

创建 TextureView/SurfaceView 关联 TTVideoEngine #

TextureView 关联 TTVideoEngine #

在布局文件中声明 TextureView ：

<TextureView
    android:id="@+id/textureView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@null" />

NOTE: 这里需要注意 TextureView 的一个 bug。如果 targetSDKVersion >= API 24，在 layout xml 中声明的 TextureView 必须将背景设置为 null，否则会 crash。 抛出: java.lang.UnsupportedOperationException: TextureView doesn't support displaying a background drawable

在 Java 代码中：

TextureView textureView = findViewById(R.id.textureView);
// 设置 SurfaceTexture 监听
textureView.setSurfaceTextureListener(new TextureView.SurfaceTextureListener() {
    @Override
    public void onSurfaceTextureAvailable(SurfaceTexture surfaceTexture, int width, int height) {
        // TextureView 的 SurfaceTexture 创建完成回调
        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) {
    }
});

将 TextureView 中的 SurfaceTexture 对象，包装成 Surface 对象设置给 TTVideoEngine 即可完成关联。TTVideoEngine 播放的视频数据，就可以通过 TextureView 显示给用户了。

SurfaceView 关联 TTVideoEngine #

在布局中声明 SurfaceView :

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

在 Java 代码中：

SurfaceView surfaceView = findViewById(R.id.surfaceView);
ttVideoEngine.setSurfaceHolder(surfaceView.getHolder());

SurfaceView 的 SurfaceHolder 内部持有了一个 Surface 对象，将 SurfaceHolder 设置给 TTVideoEngine, SurfaceView 就可以展示视频数据了。

TTVideoEngine 设置播放数据源 #

TTVideoEngine 支持播放本地视频，也支持网络流媒体视频。针对不同的使用场景，我们提供了相应的播放源设置接口。 基础版不支持 H.265 编码、Dash 视频格式等高级版和增值服务功能，详细的功能支持情况请参考点播SDK介绍中的功能列表。

本地视频源 #

File videoFile = new File("/sdcard/Download/video.MP4");
ttVideoEngine.setLocalURL(videoFile.getAbsolutePath());
ttVideoEngine.play()

Http URL 视频源 #

// enable MDL (数据加载模块)
ttVideoEngine.setIntOption(PLAYER_OPTION_ENABLE_DATALOADER,1);

String videoUrl = "https://yourdomain.com/video.mp4";
// 缓存key 推荐使用 url md5
String key = TTVideoEngine.computeMD5(videoUrl);
ttVideoEngine.setDirectUrlUseDataLoader(videoUrl, key);
ttVideoEngine.play()

为提升用户体验，使用 Http URL 视频源时需要借助 MDL(数据加载模块) 实现缓存功能。使用 MDL 要设置一个缓存 key。

缓存 key 的生成规则：

• 生成的 key 不带特殊字符，能作为文件名；
• 生成的 key 能和视频资源文件一一对应。
  推荐使用 url 的 md5 作为缓存 key。

VideoID 视频源 #

针对购买并接入了 ByteVod 服务的用户，支持给 TTVideoEngine 设置 VideoId + PlayAuthToken 播放。VideoID 和 PlayAuthToken 是由 AppServer 下发的，App 无需关心，调用 AppServer 的接口获取即可。

1. 什么是 VideoID?
用户上传一个 1080P 视频，服务端会在数据库中创建一个视频对象。转码服务会用原视频转码出多个清晰度的视频 ( eg: 360P、480P、540P、720P、1080P) 写入到该视频对象里。VideoID 就是这个视频对象的 id。
2. 什么是 PlayAuthToken?
PlayAuthToken 即播放临时凭证, 概念比较抽象。具体来说：

• PlayAuthToken 承担了两个职责：
  1.安全性。保证该视频的播放源只能被有资源权限的接入方获取。
  2.描述播放源的获取策略。比如：h264/h265、清晰度、是否加密。
• PlayAuthToken 特点是：
  1.加密性。由 AppServer 签出并下发，不支持 App 修改。
  2.临时性。签出时有过期时间，会过期。过期后需 App 调用 AppServer 接口重新获取。
  3.对应性。在使用时一个 VideoID 对应一个临时的 PlayAuthToken，不可混用。

TTVideoEngine 内部通过 VideoID + PlayAuthToken 调用 GetPlayInfo 查询接口，就可以获取到该视频对象本次播放所需的视频信息和各个清晰度的播放地址。

// enable MDL (缓存模块)
ttVideoEngine.setIntOption(PLAYER_OPTION_ENABLE_DATALOADER, 1); 
// enable 缓存 video model
ttVideoEngine.setIntOption(PLAYER_OPTION_USE_VIDEOMODEL_CACHE, 1);

String videoId = "your video id"; // AppServer 下发
String playAuthToken = "your video id's play auth token"; // AppServer 下发
ttVideoEngine.setVideoID(videoId);
ttVideoEngine.setPlayAuthToken(playAuthToken);

ttVideoEngine.play();

释放 TTVideoEngine 实例 #

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

ttVideoEngine.releaseAsync();

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