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

文档中心

立即注册

导航

快速开始

最近更新时间：2024.09.05 18:32:13首次发布时间：2022.05.13 17:10:55

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

适用版本

本文适用于点播 SDK 1.27.1.3 及之后的版本。更早版本请见 Android 快速开始（历史版本）。

前提条件

已完成集成 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.init(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())
        .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 方法。

步骤 6：设置播放源

TTVideoEngine 支持播放本地视频，也支持网络流媒体视频。针对不同的使用场景，我们提供了相应的播放源设置接口。

Vid 播放源

DirectUrl 播放源

本地播放源

如果您购买并接入了火山引擎视频点播服务，可使用 Vid 方式播放视频。您需要将播放器的 vid 参数设为视频点播服务生成的 Vid，将 playAuthToken 参数设为临时播放 Token。Vid 和临时播放 Token 是由应用服务端下发的，应用客户端无需关心，调用应用服务端的接口获取即可，具体请见通过临时播放 Token 播放。

// 开启缓存 video model
ttVideoEngine.setIntOption(PLAYER_OPTION_USE_VIDEOMODEL_CACHE, 1);

final String vid = "your video id"; // appServer 下发
final String playAuthToken = "your video id's play auth token"; // appServer 下发

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

// 1.组装 vid 播放源
StrategySource vidSource = new VidPlayAuthTokenSource.Builder()
        .setVid(vid)
        .setPlayAuthToken(playAuthToken)
        // 设置 Codec 类型（h264，h265、h266），不传则使用默认值 h264
        .setEncodeType(encodeType)
        // 启播清晰度设置，这里演示设置为 480P。不传使用默认值 360P
        .setResolution(Resolution.High)
        .build();
// 2.设置播放源
ttVideoEngine.setStrategySource(vidSource);
// 3.播放
ttVideoEngine.play()

如果您使用 DirectUrl 方式播放视频，需将 url 参数设为视频播放地址。播放地址可以是第三方点播地址或视频点播服务生成的播放地址。此外，对于 DirectUrl 播放源， vid 和 cacheKey 也为必填参数，说明如下：

vid：视频的唯一标识，必须与视频源一一对应。vid 可以是您自己的视频管理系统中的唯一标识，也可以在 App 层自行生成一个 ID。此 ID 会用于点播 SDK 的日志上报、预加载、预渲染等功能中。
cacheKey：推荐使用 URL 的 MD5 作为缓存 key。缓存 key 也需能和视频资源文件一一对应，不带特殊字符，能作为文件名。

示例代码如下：

final String vid = "video id"; // 视频源与 vid 必须一一对应
final String url = "http://www.example.com/h264.mp4";
final String cacheKey = TTVideoEngine.computeMD5(url);

// 1.组装资源
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()

如果您想播放本地视频，仅需将 videoFile 参数设为本地的视频地址。示例代码如下：

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

步骤 7：释放播放器

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

ttVideoEngine.releaseAsync();

步骤 8：集成 Debug 工具

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

后续操作

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

注意

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