快速开始

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

适用版本

本文档适用于点播 SDK 1.27.1.3 及之后的版本，旧版本文档请参考快速开始（旧版）。

前提条件

您已完成点播 SDK 的集成准备。

开源示例项目

Github 地址：Demo-Android。

使用流程

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

1. 初始化点播 SDK
2. 设置自定义 ID
3. 创建播放器
4. 设置显示视图
5. 设置播放源
6. 释放播放器
7. 接入 Debug 工具

日志调试

开发的过程中，建议开启日志，便于调试和排查问题。

// （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);

1. 初始化点播 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());

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

2. 设置自定义 ID

初始化点播 SDK 后，您可以设置自定义 ID，用于实现单点追查功能，即进行用户级和播放会话级的全链路问题定位和追踪。详细的代码示例如下所示。

// 初始化自定义 ID
private void initVodSDK(Context context, String userUniqueId) {
    // 1. 根据步骤一初始化点播 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);
    }
}

自定义 ID 配置完成后，您可登录视频点播控制台，选择左侧导航栏质量平台 > 单点追查，进入单点追查页面，查询单点追查数据。详细操作说明请见单点追查。

3. 创建播放器

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

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

4. 设置显示视图

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

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

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) {
    }
});
    

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

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

5. 设置播放源

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

// enable 缓存 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()
    

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()
    

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

6. 释放播放器

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

ttVideoEngine.releaseAsync();

7. 接入 Debug 工具

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

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