使用文档
本文将详细介绍如何在项目中快速地使用腾讯礼物动画特效 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() {@Overridepublic 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 加入布局里
<FrameLayoutandroid:layout_width="match_parent"android:layout_height="match_parent"android:layout_marginTop="0dp"><com.tencent.tcmediax.tceffectplayer.api.TCEffectAnimViewandroid: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() {@Overridepublic void onPlayStart() {// 动画开始播放}@Overridepublic void onPlayEnd() {// 动画结束播放}@Overridepublic void onPlayError(int errorCode) {// 动画播放失败}@Overridepublic 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() {@Overridepublic void fetchImage(Resource resource, IFetchResourceImgResult result) {// 如果替换的是 tepg 文件资源的话,isTEPG() = trueboolean isTEPG = resource.isTEPG();// 如果原始文件是pag的话,这里的 id 是原始pag文件中图片图层对应的index,如 0、1、2......String index = resource.id;// 后续可以根据图层 index 的值,来选择您要替换返回的图片 Bitmap 资源// 如果想跳过指定图层不替换的话,可以返回 nullBitmapFactory.Options options = new BitmapFactory.Options();options.inScaled = false;Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.test, options);// 回调结果出去result.fetch(bitmap);}@Overridepublic void fetchText(Resource resource, IFetchResourceTxtResult result) {// 如果替换的是 tepg 文件资源的话,isTEPG() = trueboolean 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);}@Overridepublic void releaseResource(List<Resource> resources) {// 资源释放通知for (Resource resource : resources) {if (resource.bitmap != null) resource.bitmap.recycle();}}});
如果需要监听融合动画自定义资源的点击事件,需要注册 OnResourceClickListener :
mPlayerView.setOnResourceClickListener(new OnResourceClickListener() {@Overridepublic 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 文件格式资源。
String localPath = /sdcard/Android/${packageName}/files/tep_cool_ss.tepmPlayerView.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。 |