文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>腾讯特效 SDK>集成指引>礼物动画特效>Flutter>使用文档

使用文档

最近更新时间：2025-10-13 11:07:22

我的收藏

本页目录：

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

初始化注册 License

在正式使用腾讯礼物动画特效 SDK 时，需要先设置 License，设置 License 成功之后，才可以进行后续的 SDK 使用。
设置 License 方式如下：
import 'package:flutter_effect_player/ftceffect_player.dart';

const LICENSE_URL = "${licenseUrl}";
const LICENSE_KEY = "${licenseKey}";

FTCMediaXBase.instance.setLicense(LICENSE_URL, LICENSE_KEY, (code, msg) {
  print("TCMediaX license result: errCode:${code}, msg:${msg}");
});
注意：
License 是强线上检验逻辑，应用首次启动后调用 FTCMediaXBase.instance.setLicense 时，需确保网络可用。 在 App 首次启动时，可能还没有授权联网权限，则需要等授予联网权限后，再次调用该方法。
监听 FTCMediaXBase.instance.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 默认支持保存运行日志，如果测试过程中出现问题，可以提取日志反馈给腾讯云客服，您可以根据业务需要把此目录的日志上传到业务后台，用于定位线上用户问题。
Android 端的日志保存在目录：/sdcard/Android/data/${your_packagename}/files/TCMediaLog，日志文件按照日期命名，把 TCMediaLog 文件夹导出即可。

iOS 端保存在沙箱 Documents/TCMedialog 文件夹，日志文件按照日期命名。详细日志导出教程 参考这里。
注意：
没有日志文件？
请检查是否通过 FTCMediaXBase.instance.setLogEnable 传入 false 关闭了日志，默认文件日志是开启的。

播放器使用

引入 FTCEffectAnimView

FTCEffectViewController? controller;

Widget _getFTCEffectAnimView() {
  return FTCEffectAnimView(
      controllerCallback: (controller){
        // controller.setLoop(true);
        // controller.startPlay("xxxxxxx");
      }
  );
}

播放监听

可以在开始播放之前通过调用setPlayListener方法来设置动画播放状态监听。
controller?.setPlayListener(FAnimPlayListener(onPlayStart: () {
  // on anim play start
}, onPlayEnd: () {
  // on anim play end
}, onPlayEvent: (int event, Map params) {
  // on anim play events
}, onPlayError: (code) {
  // on anim play error
}));
如果您需要获取当前正在播放的动画信息，可以在onPlayStart()方法中(或者该方法执行之后)调用getTCAnimInfo()方法来获取到FTCEffectAnimInfo对象实例，进而获取到当前播放动画的类型、时长、宽高、融合动画等信息。

播放配置

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

融合动画配置

实现 mp4 或者 tcmp4 融合动画的播放，需要实现 FResourceFetcher。
如果是图片类型的融合动画，需要实现 FResImgResultFetcher ，来返回对应图片的 Uint8List 来替换对应的元素；
如果是文字类型的融合动画，需要实现 FResTextResultFetcher ，来返回对应的 FTCEffectText 对象实例，来指定文字的显示配置信息。
controller?.setFetchResource(FResourceFetcher(textFetcher: (res) {
   // 返回 FTCEffectText 实例，内部可以指定文字内容、颜色等
   return FTCEffectText()
     ..text = "FTCEffect${res.id}"
     ..color = 0xff0000ff;
 }, imgFetcher: (res) {
   // 需要提前准备好要替换的图片数据，这里直接返回即可。
   // final data = await rootBundle.load('asset/image/head1.png');
   // _samplePng = data.buffer.asUint8List();
   return _samplePng;
 }));

播放控制

开始播放

支持播放 .mp4、.tcmp4 文件格式资源。
注意：
只支持播放 sdcard 本地视频资源， 如果您使用的网络视频资源， 先下载到本地再播放。下载后保持资源文件后缀和原始文件一样，如： .mp4 或 .tcmp4， 去掉或修改后缀将会导致播放失败。
动画资源可以通过 特效转换工具 来生成，除此之外也支持 VAP 格式动画资源播放。
String localPath = /path/files/tep_cool_ss.mp4
controller?.startPlay("xxxx")

暂停播放

controller?.pause()

继续播放

controller?.resume()

循环播放

controller?.setLoop(true)

静音播放

controller?.setMute(true)

停止播放

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

常见问题

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

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

常见错误码

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