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

适用版本 #

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

前提条件 #

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

初始化点播 SDK #

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

初始化点播 SDK，仅需初始化一次

OpenGL 渲染开关 #

因为渲染操作不支持在后台操作，需要在 appDelegate 对应的方法对 opengl 环境进行控制。必须在 appDelegate 这里的代理方法处理。

#import <TTSDK/TTVideoEngineHeader.h>

/** 同时需要在 appDelegate 对应的方法加上(这两个方法不耗时) **/
- (void)applicationWillResignActive:(UIApplication *)application {
 [TTVideoEngine stopOpenGLESActivity];
//...
}
  

- (void)applicationDidBecomeActive:(UIApplication *)application {
 [TTVideoEngine startOpenGLESActivity];
//...
}

日志调试

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

/// 需要 debug 日志信息，更多取值参考 TTVideoEngineLogFlag
[TTVideoEngine setLogFlag:TTVideoEngineLogFlagDefault];

/// 提交应用商店时，需要设置为 None
[TTVideoEngine setLogFlag:TTVideoEngineLogFlagNone];

配置通用参数 #

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

需要的参数列举如下：

TTSDK初始化

集成 TTSDK 后，在 App 启动时需要对 TTSDK 进行初始化操作，参考代码如下：

#import <TTSDK/TTSDKManager.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Override point for customization after application launch.

    [self initTTSDK];
    
    // Your code...

    return YES;
}

- (void)initTTSDK {
    TTSDKConfiguration *configuration = [TTSDKConfiguration defaultConfigurationWithAppID:@"163053"];/// 您的APPID
    configuration.appName = @"TTSDKDemo";
    configuration.channel = @"test_channel";
    configuration.bundleID = @"BundleID";
    configuration.licenseFilePath = [NSBundle.mainBundle pathForResource:@"path/to/license" ofType:nil];
    [TTSDKManager startWithConfiguration:configuration];
}

TTSDK 1.14.0 之后使用 License 2.0 机制，详细使用规则可查看 License 2.0 升级说明。

初始化 TTVideoEngine

#import <TTSDK/TTVideoEngineHeader.h>

NSDictionary *appInfo = @{
        TTVideoEngineAID : @(163053), /// 您的APPID
        TTVideoEngineAppName : @"TTSDKDemo",/// appName
        TTVideoEngineChannel : @"test_channel",
        TTVideoEngineServiceVendor : @(TTVideoEngineServiceVendorCN),
        TTVideoEngineAppVersion : @"1.0.0"
        };
[TTVideoEngine configureAppInfo:appInfo];

[TTVideoEngine startOpenGLESActivity]; // 激活OpenGLES环境,必需

初始化 AppLog

AppLog 是实现日志上报模块，目前是单独对外提供。播放器依赖该库的功能，需要同时配置和启动 SDK。

如果您的 APP 之前已经接入了 RangersAppLog SDK，请忽略改步骤。

TTSDK 版本 1.18 以下，使用以下方法集成：

#import <RangersAppLog/RangersAppLog.h>

- (void)startAppLog {
        BDAutoTrackConfig *config = [BDAutoTrackConfig new];
        config.appID = @"163053"; 您的APPID
        config.channel = @"test_channel";
        config.appName = @"TTSDKDemo";
        config.serviceVendor = BDAutoTrackServiceVendorCN;
#if DEBUG
        config.showDebugLog = YES;      // YES则会在控制台输出日志，仅仅调试使用，release版本请勿设置为YES
        config.logNeedEncrypt = NO;     // 日志上报是否加密，默认加密，release版本请勿设置为NO
#else
        config.showDebugLog = NO;       // YES则会在控制台输出日志，仅仅调试使用，release版本请勿设置为YES
        config.logNeedEncrypt = YES;    // 日志上报是否加密，默认加密，release版本请勿设置为NO
#endif
        BDAutoTrack *track = [BDAutoTrack trackWithConfig:config];
        [track startTrack];
}

TTSDK 版本 1.18 以上（包括 1.18），通过 TTSDK 初始化参数控制使用。

TTSDKConfiguration \*configuration = \[TTSDKConfiguration defaultConfigurationWithAppID:@"163053"\];/// 您的APPID
configuration.appName = @"TTSDKDemo";
configuration.channel = @"test\_channel";
configuration.bundleID = @"BundleID";
configuration.shouldInitAppLog = YES;    // 默认开启AppLog，关闭AppLog设置为NO 
configuration.licenseFilePath = [NSBundle.mainBundle pathForResource:@"path/to/license" ofType:nil];
[TTSDKManager startWithConfiguration:configuration];

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

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

配置 MDL

开启 MDL 前，必须要设置：

• 视频缓存文件夹路径

• 视频缓存文件夹大小

实例代码：

// 1. 配置
TTVideoEngine.ls_localServerConfigure.maxCacheSize = 300 * 1024 * 1024;// 300M
    NSString *cacheDir = [[NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES) lastObject] stringByAppendingPathComponent:@"com.video.cache"];
TTVideoEngine.ls_localServerConfigure.cachDirectory = cacheDir;

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

开启 MDL

//2. 启动
[TTVideoEngine ls_start];

使用 MDL

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

[engine setOptionForKey:VEKKeyProxyServerEnable_BOOL value:@(YES)];

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

开始单个视频播放 #

接下来演示初始化一个 TTVideoEngine 对象，播放一个视频。

创建 TTVideoEngine 实例 #

### 初始实例  需要传参 YES
TTVideoEngine *engine = [[TTVideoEngine alloc] initWithOwnPlayer:YES];
### 必要的配置
engine.hardwareDecode = YES;/// 硬解开关
[engine setOptionForKey: VEKKeyProxyServerEnable_BOOL value:@(YES)]; /// 必要操作
[engine setOptionForKey:VEKKeyViewRenderEngine_ENUM value:@(TTVideoEngineRenderEngineMetal)];/// metal 渲染，可以设置 opengl 模式

• 软硬解配置

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

engine.hardwareDecode = YES; /// YES 开启硬解， NO 关闭硬解

设置显示的视图 #

TTVideoEngine 提供了显示画面的视图 view ，需要被添加的父视图和设置 frame .
[self.view addSubview:engine.playerView];/// 添加到合适的视图层级

TTVideoEngine 设置播放数据源 #

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

本地视频源

NSString *localMediaPath = @"";
[engine setLocalURL:localMediaPath];

Http URL 视频源

### 设置播放源信息
NSString *videoUrlString = @"";
NSString *cacheFileKey = @""; /// key 信息需要和资源一一对应，并且不能直接使用 url . 建议使用 url md5 .
[engine ls_setDirectURL:videoUrlString key:cacheFileKey];

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

缓存 key 的生成规则：

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

VideoID 视频源

TTVideoEngine 支持设置 VideoId + PlayAuthToken 播放。集成点播 SDK 的 App，VideoID 和 PlayAuthToken 是由 AppServer 下发的，App 无需关心，调用 AppServer 的接口获取即可。

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

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

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

### videoId 方式播放，需要同时设置 playAuthToken 
NSString *videoId = @"";
NSString *playAuthToken = @"";
[engine setVideoID:videoId];
[engine setPlayAuthToken:playAuthToken];

开始播放 #

[engine play];/// 开始播放

释放 TTVideoEngine 实例 #

[engine closeAysnc];/// 停止播放，销毁 engine 实例， engine 实例不能再次被使用。
[engine.playerView removeFromSuperview];/// 记得移除视图

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