使用文档

本文将详细介绍如何在项目中快速地使用腾讯礼物动画特效 SDK。只需遵循以下步骤,即可完成 SDK 的配置和使用。

初始化注册 License

在正式使用腾讯礼物动画特效 SDK 时,需要先设置 License,设置 License 成功之后,才可以进行后续的 SDK 使用。
设置 License 方式如下:
private static final String sLicenseUrl = "${licenseUrl}";
private static final String sLicenseKey = "${licenseKey}";
private final ILicenseCallback mLicenseCallback = new ILicenseCallback() {
@Override
public void onResult(int errCode, String msg) {
// 注意:此回调不一定在调用线程
Log.d(TAG, "TCMediaX license result: errCode: " + errCode + ", msg: " + msg);
if (errorCode == TXLicenceErrorCode.LicenseCheckOk) {
//鉴权成功
} else {
//鉴权失败
}
}
};

// 调用当前方法进行license设置
public void init() {
TCMediaXBase.getInstance().setLicense(DemoApplication.getAppContext(), sLicenseUrl, sLicenseKey, mLicenseCallback);
}
注意:
License 是强线上检验逻辑,应用首次启动后调用 TCMediaXBase#setLicense 时,需确保网络可用。 在 App 首次启动时,可能还没有授权联网权限,则需要等授予联网权限后,再次调用 TCMediaXBase#setLicense。
监听 TCMediaXBase#setLicence 加载结果:ILicenseCallback#onResult 接口,如果失败要根据实际情况做对应重试及引导,如果多次失败后,可以限频,并业务辅以产品弹窗等引导,让用户检查网络情况。
对于多进程的 App, 确保每个使用特效播放器的进程启动时,都调用了 TCMediaXBase#setLicense。例如: Android 端使用独立进程播放特效的 App,后台播放时进程被系统 kill 掉重启时,也要调用 TCMediaXBase#setLicense。
鉴权 errorCode 说明:
错误码
描述
0
成功。Success。
-1
输入参数无效,例如 URL 或 KEY 为空。
-3
下载环节失败,请检查网络设置。
-4
从本地读取的 TE 授权信息为空,可能是 IO 失败引起。
-5
读取 VCUBE TEMP License文件内容为空,可能是 IO 失败引起。
-6
v_cube.license 文件 JSON 字段不对。请联系腾讯云团队处理。
-7
签名校验失败。请联系腾讯云团队处理。
-8
解密失败。请联系腾讯云团队处理。
-9
TELicense 字段里的 JSON 字段不对。请联系腾讯云团队处理。
-10
从网络解析的 TE 授权信息为空。请联系腾讯云团队处理。
-11
把 TE 授权信息写到本地文件时失败,可能是 IO 失败引起。
-12
下载失败,解析本地 asset 也失败。
-13
鉴权失败,请检查so是否在包里,或者已正确设置 so 路径。
3004/3005
无效授权。请联系腾讯云团队处理。
3015
Bundle Id / Package Name 不匹配。检查您的 App 使用的 Bundle Id / Package Name 和申请的是否一致,检查是否使用了正确的授权文件。
3018
授权文件已过期,需要向腾讯云申请续期。
其他
请联系腾讯云团队处理。

日志管理

腾讯礼物动画特效 SDK 默认支持保存运行日志,如果测试过程中出现问题,可以提取日志反馈给腾讯云客服,您可以根据业务需要把此目录的日志上传到业务后台,用于定位线上用户问题。
腾讯礼物动画特效 SDK Android 端的日志保存在目录:/sdcard/Android/data/${your_packagename}/files/TCMediaLog,日志文件按照日期命名,把 TCMediaLog 文件夹导出即可:

注意:
没有日志文件?
请检查是否通过 TCMediaXBase#setLogEnable 传入 false 关闭了日志,默认文件日志是开启的。

播放器使用

把 TCEffectAnimView 加入布局里

<FrameLayout
android:layout_width="match_parent"
android:layout_height="match_parent"
android:layout_marginTop="0dp">
<com.tencent.tcmediax.tceffectplayer.api.TCEffectAnimView
android:id="@+id/video_view"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:layout_centerInParent="true"
android:visibility="visible" />
</FrameLayout>

初始化 TCEffectAnimView

private TCEffectAnimView mPlayerView;
mPlayerView = (TCEffectAnimView) findViewById(R.id.video_view);

// 可选: 设置动画对齐方式(默认FIT_CENTER,支持自定义)
mPlayerView.setScaleType(TCEffectPlayerConstant.ScaleType.FIT_CENTER);

播放监听

可以在开始播放之前通过调用setPlayListener方法来设置动画播放状态监听:
// 设置播放状态回调
playerView.setPlayListener(new TCEffectAnimView.IAnimPlayListener() {
@Override
public void onPlayStart() {
// 动画开始播放
}

@Override
public void onPlayEnd() {
// 动画结束播放
}

@Override
public void onPlayError(int errorCode) {
// 动画播放失败
}
@Override
public void onPlayEvent(int event, Bundle param) {
// 动画播放事件
}
});
1. 如果您需要获取当前正在播放的动画信息,可以在onPlayStart()方法中(或者该方法执行之后)调用getTCAnimInfo()方法来获取到TCEffectAnimInfo对象实例,进而获取到当前播放动画的类型、时长、宽高、融合动画等信息。
2. onPlayEvent()方法会回调动画播放中的事件,回调线程不保证都在主线程中。

播放配置

// 设置播放配置,非必需的步骤
TCEffectConfig config = new TCEffectConfig.Builder().setCodecType(TCEffectConfig.CodecType.TC_MPLAYER).build();
mPlayerView.setConfig(config);
TCEffectConfig 中目前支持:
1. setCodecType(CodecType type) :它有三个取值,分别是:
TCEffectConfig.CodecType.TC_MPLAYER (MPLAYER 播放引擎)
TCEffectConfig.CodecType.TC_MCODEC(MCODEC 播放引擎)
TCEffectConfig.CodecType.TX_LITEAV_SDK (腾讯云播放器 SDK)
注意:
1. 目前仅支持在播放器开始前调用 setConfig() 方法来设置播放配置,开始播放后不支持修改配置。
2. 目前支持的三种 CodecType 仅对 TEP 动画生效。
3. 如果设置 CodecType 为 TCEffectConfig.CodecType.TX_LITEAV_SDK ,则还需要单独引入腾讯云播放器 SDK,以及申请、注册好其对应的 License。
4. 如果不设置 config,则会默认使用 CodecType = TCEffectConfig.CodecType.TC_MPLAYER。
2. setFreezeFrame(int frame):用于设置播放动画冻结帧,详细解释见 API 文档
3. setAnimType(AnimType type):用于指定后续要播放的动画格式,适用于某些情况下,要播放的动画文件后缀被修改的场景。可取值如下:
TCEffectConfig.AnimType.AUTO(SDK 默认策略,即以动画文件的后缀来判断动画格式,例如 tcmp4/mp4/tep/tepg 等格式)。
TCEffectConfig.AnimType.MP4(MP4 动画格式,后续都将动画文件当做 MP4 类型来播放,无视文件后缀名)。
TCEffectConfig.AnimType.TCMP4(TCMP4 动画格式,后续都将动画文件当做 TCMP4 类型来播放,无视文件后缀名)。

融合动画配置

实现 mp4 或者 tcmp4 融合动画的播放,需要实现 IFetchResource 接口。
1. 如果是图片类型的融合动画,需要返回对应的 Bitmap 来替换对应的元素;
2. 如果是文字类型的融合动画,需要返回对应的 TCEffectText 对象实例,来指定文字的显示配置信息。
mPlayerView.setFetchResource(new IFetchResource() {
@Override
public void fetchImage(Resource resource, IFetchResourceImgResult result) {
// 如果替换的是 tepg 文件资源的话,isTEPG() = true
boolean isTEPG = resource.isTEPG();
// 如果原始文件是pag的话,这里的 id 是原始pag文件中图片图层对应的index,如 0、1、2......
String index = resource.id;
// 后续可以根据图层 index 的值,来选择您要替换返回的图片 Bitmap 资源
// 如果想跳过指定图层不替换的话,可以返回 null
BitmapFactory.Options options = new BitmapFactory.Options();
options.inScaled = false;
Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.test, options);
// 回调结果出去
result.fetch(bitmap);
}
@Override
public void fetchText(Resource resource, IFetchResourceTxtResult result) {
// 如果替换的是 tepg 文件资源的话,isTEPG() = true
boolean isTEPG = resource.isTEPG();
// 如果原始文件是pag的话,这里的 id 是原始pag文件中文字图层对应的index,如 0、1、2......
String index = resource.id;
// 根据图层 index 的值,来选择您要替换返回的文字 String 即可
TCEffectText tcEffectText = new TCEffectText();
tcEffectText.text = "test";
// tcEffectText.color = Color.YELLOW;
// tcEffectText.alignment = TCEffectText.TEXT_ALIGNMENT_RIGHT;
tcEffectText.fontStyle = "bold";
result.loadTextForPlayer(tcEffectText);
}
@Override
public void releaseResource(List<Resource> resources) {
// 资源释放通知
for (Resource resource : resources) {
if (resource.bitmap != null) resource.bitmap.recycle();
}
}
});
如果需要监听融合动画自定义资源的点击事件,需要注册 OnResourceClickListener :
mPlayerView.setOnResourceClickListener(new OnResourceClickListener() {
@Override
public void onClick(Resource resource) {
// 根据点击的资源类型来做展示处理
if (resource.srcType.equals(Resource.SrcType.TXT)) {
// 如果是 TXT 类型,则 id 字段是其图层id,text是其当时被替换的文本
tvTest.setText(resource.text);
} else {
// 如果是 IMG 类型,则 id 字段是其图层id,bitmap是其当时被替换的图片
ivTest.setImageBitmap(resource.bitmap);
}
}
});

播放控制

开始播放

TCEffectPlayer 支持播放 .mp4、.tcmp4 文件格式资源。
注意:
1. 只支持播放 sdcard 本地视频资源, 如果您使用的网络视频资源, 先下载到本地再播放。
2. 动画资源可以通过 特效转换工具 来生成,除此之外也支持 VAP 格式动画资源播放。
String localPath = /sdcard/Android/${packageName}/files/tep_cool_ss.tep
mPlayerView.startPlay(localPath)

暂停播放

mPlayerView.pause()

继续播放

mPlayerView.resume()

循环播放

mPlayerView.setLoop(true)

静音播放

mPlayerView.setMute(true)

停止播放

当不需要继续使用播放器时,需要停止播放,释放占用的资源。
mPlayerView.stopPlay(true)

常见问题

在播放过程中出现下面的日志信息,如何处理?

License checked failed! tceffect player license required!
请检查是否申请特效播放器 License,并进行了初始化注册。

日志文件如何提取?

方法一:特效播放器的日志保存在目录: /sdcard/Android/data/${your_packagename}/files/TCMediaLog , 日志文件按照日期命名,把 TCMediaLog 文件夹导出,压缩成 zip。

方法二:如果有开发环境,可以通过 adb 运行下面的命令抓取全量日志:
adb logcat -v time > log.txt

常见错误码

错误码
描述
-10003
创建线程失败。
-10004
render 创建失败。
-10005
配置解析失败。
-10006
文件无法读取。
-10007
动画视频编码格式是 H.265,在当前设备上不支持。
-10008
参数非法。
-10009
license 不合法。
-10010
MediaPlayer 播放失败。
-10012
缺少必备的依赖,比如播放类型为 TX_LITEAV_SDK 时没有引入 liteavSDK。