腾讯特效 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);}

鉴权 errorCode 说明：

二、日志管理

腾讯礼物动画特效 SDK 默认支持保存运行日志，如果测试过程中出现问题，可以提取日志反馈给腾讯云客服，你可以根据业务需要把此目录的日志上传到业务后台，用于定位线上用户问题。

腾讯礼物动画特效 SDK Android 端的日志保存在目录：/sdcard/Android/data/${your_packagename}/files/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)

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 类型来播放，无视文件后缀名）

4. enableAudioFrameCallback(boolean enableAudioFrameCallback)：开启播放中音频回调开关，适用于某些情况下需要监听处理礼物动画音轨的场景。

5. enableProgressCallback(boolean enable)：开启播放中动画进度回调开关。

6. progressCallbackIntervalMs(int intervalInMS)：播放中动画进度回调间隔，单位毫秒，默认值200毫秒。

7. enableFrameRenderCallback(boolean enable)：开启播放中动画帧进度回调开关。

八、融合动画配置

实现 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); } }});

九、动画属性获取

如果需要在动画播放前获取到动画的宽高、时长，以及融合动画属性信息，你可以通过如下办法来实现：

TCEffectAnimInfo animInfo = TCEffectAnimView.preloadTCAnimInfo(playPath, config);

·playPath：即要获取信息的动画路径地址，类似于调用 TCEffectAnimView#startPlay() 方法时传入的参数。

·config：TCEffectConfig 实例，用于指定该动画的额外配置

十、动画截图

如果需要在动画播放中进行截图，可以通过如下办法来实现：

Bitmap snapshot = mPlayerView.snapshot();

使用该接口时有如下注意事项：

1. 如果在动画播放结束后截图，会返回 null。但是如果播放前设置了 FREEZE_FRAME_LAST ，即保留最后一帧，则此时当动画播放完成之后画面不会消失，而是会停留在最后一帧，此时截图可以拿到最后一帧内容。

2. 对于 MP4 来说：设置 setScaleType = FIT_CENTER 或 CENTER_CROP 时，截图宽高比例跟原动画一致；setScaleType = FIT_XY 时，截图宽高比例跟当时 TCEffectAnimView 宽高比例一致。

对于 TCMP4 来说：截图宽高比例始终跟原动画一致。

3. 该方法返回 Bitmap 实例归属于业务来管理，业务可根据自己的使用生命周期来决定何时回收，SDK 不会主动回收它。

十二、开始播放

TCEffectPlayer 支持播放 .mp4、.tcmp4 文件格式资源。

String localPath = /sdcard/Android/${packageName}/files/tep_cool_ss.mp4mPlayerView.startPlay(localPath)

十三、暂停播放

mPlayerView.pause()

十四、继续播放

mPlayerView.resume()

十五、循环播放

mPlayerView.setLoop(true)

十六、静音播放

mPlayerView.setMute(true)

十七、停止播放

当不需要继续使用播放器时，需要停止播放，释放占用的资源。

mPlayerView.stopPlay(true)

十九、在播放过程中出现下面的日志信息，如何处理？

License checked failed! tceffect player license required!

请检查是否申请特效播放器 License，并进行了初始化注册。

20、日志文件如何提取？

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

·方法二：如果有开发环境，可以通过 adb 运行下面的命令抓取全量日志：

adb logcat -v time > log.txt

21、常见错误码

更多常见问题请参见 常见问题列表。