diff --git a/README.md b/README.md index 6d0a7e1..4fd30dc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Gift AR Flutter -Gift AR Flutter plugin project. +English | [简体中文](./README_CN.md) ## OverView @@ -13,9 +13,23 @@ Gift AR provides clients with efficient and smooth animation effects playback so | High device compatibility | Deeply optimized playback performance, compatible with mid-to-low end devices, ensuring smooth user experience across various hardware configurations. | | High security | Encrypt special effect resources to prevent piracy and tampering, ensuring customer content and asset security. | +## Directory Structure + +This directory contains the demo source code of the Gift AR SDK for Android, which shows you how to call the APIs to implement basic features. + +``` +├── android // The android source code for plugin. +├── ios // The iOS source code for plugin. +├── lib // The dart source code for plugin. +└── example // The demo source code + ├── android // The android demo source code + ├── ios // The ios demo source code + └── lib // The dart demo source code +``` + ## Related Documents -- [Quick Run Demo](./doc/Quick%20Run%20Demo-EN.md) -- [Integration Guide](./doc/Integration%20Guide_EN.md) -- [User Documentation](./doc/User%20Documentation-EN.md) -- [API Documentation](./doc/API%20Documentation-EN.md) +- [Quick Run Demo](https://www.tencentcloud.com/document/product/1143/73974) +- [Integration Guide](https://www.tencentcloud.com/document/product/1143/73975) +- [User Documentation](https://www.tencentcloud.com/document/product/1143/73976) +- [API Documentation](https://www.tencentcloud.com/document/product/1143/73977) diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 0000000..3c2cab6 --- /dev/null +++ b/README_CN.md @@ -0,0 +1,36 @@ +# 腾讯礼物动画特效SDK Flutter插件 + +简体中文| [English](./README.md) + +## 概述 + +腾讯礼物动画特效SDK致力于为客户提供高效、流畅的动画特效播放解决方案。针对动画播放卡顿、崩溃、高耗电、性能占用过高、低端机表现不佳等行业难题，我们通过技术优化和创新，打造了一款高性能、高兼容性、高安全性的动画特效播放工具。 + +| 特性 | 描述 | +|---------|----------------------------------------------------------------| +| 多格式特效支持 | 支持 MP4、VAP、SVGA、PAG、WebP、Lottie、PNG 序列图等多种格式的特效动画转换后播放，满足多样化需求 | +| 高性能播放 | 在播放复杂特效时，性能占用更低，确保多动画同时播放流畅，尤其在低端设备上表现优异。 | +| 设备兼容性强 | 深度优化播放性能，兼容中低端设备，确保用户在各种硬件配置下都能流畅体验。 | +| 高安全性 | 特效资源采用加密处理，防止盗版和篡改，保障客户内容资产安全。 | + + +## 工程目录结构说明 + +本目录包含腾讯礼物动画特效SDK Flutter 插件 和 Demo 源代码，主要演示接口如何调用以及最基本的功能。 + +``` +├── android // 插件android源代码 +├── ios // 插件iOS源代码 +├── lib // 插件dart源代码 +└── example // 相关demo代码 + ├── android // android的demo源代码 + ├── ios // iOS的demo源代码 + └── lib // dart的demo源代码 +``` + +## 相关文档 + +- [快速跑通Demo](https://cloud.tencent.com/document/product/616/123948) +- [集成文档](https://cloud.tencent.com/document/product/616/123945) +- [使用文档](https://cloud.tencent.com/document/product/616/123946) +- [API文档](https://cloud.tencent.com/document/product/616/123947) diff --git a/android/src/main/java/com/tcmedia/tcmediax/tceffectplayer/tceffectplayer_flutter/messages/TCEffectMessages.java b/android/src/main/java/com/tcmedia/tcmediax/tceffectplayer/tceffectplayer_flutter/messages/TCEffectMessages.java index c8cc04b..a86d3bc 100644 --- a/android/src/main/java/com/tcmedia/tcmediax/tceffectplayer/tceffectplayer_flutter/messages/TCEffectMessages.java +++ b/android/src/main/java/com/tcmedia/tcmediax/tceffectplayer/tceffectplayer_flutter/messages/TCEffectMessages.java @@ -1051,6 +1051,9 @@ public interface FTCEffectAnimViewApi { @NonNull String getSdkVersion(); + @NonNull + FTCEffectAnimInfoMsg preloadTCAnimInfo(@NonNull String playUrl, @NonNull FTCEffectConfigMsg config); + /** The codec used by FTCEffectAnimViewApi. */ static @NonNull MessageCodec getCodec() { return PigeonCodec.INSTANCE; @@ -1498,6 +1501,30 @@ static void setUp(@NonNull BinaryMessenger binaryMessenger, @NonNull String mess String output = api.getSdkVersion(); wrapped.add(0, output); } + catch (Throwable exception) { + wrapped = wrapError(exception); + } + reply.reply(wrapped); + }); + } else { + channel.setMessageHandler(null); + } + } + { + BasicMessageChannel channel = + new BasicMessageChannel<>( + binaryMessenger, "dev.flutter.pigeon.flutter_effect_player.FTCEffectAnimViewApi.preloadTCAnimInfo" + messageChannelSuffix, getCodec()); + if (api != null) { + channel.setMessageHandler( + (message, reply) -> { + ArrayList wrapped = new ArrayList<>(); + ArrayList args = (ArrayList) message; + String playUrlArg = (String) args.get(0); + FTCEffectConfigMsg configArg = (FTCEffectConfigMsg) args.get(1); + try { + FTCEffectAnimInfoMsg output = api.preloadTCAnimInfo(playUrlArg, configArg); + wrapped.add(0, output); + } catch (Throwable exception) { wrapped = wrapError(exception); } diff --git a/android/src/main/java/com/tcmedia/tcmediax/tceffectplayer/tceffectplayer_flutter/ui/view/FTCEffectAnimController.java b/android/src/main/java/com/tcmedia/tcmediax/tceffectplayer/tceffectplayer_flutter/ui/view/FTCEffectAnimController.java index 498b14a..0a6463c 100644 --- a/android/src/main/java/com/tcmedia/tcmediax/tceffectplayer/tceffectplayer_flutter/ui/view/FTCEffectAnimController.java +++ b/android/src/main/java/com/tcmedia/tcmediax/tceffectplayer/tceffectplayer_flutter/ui/view/FTCEffectAnimController.java @@ -164,6 +164,13 @@ public void setRate(@NonNull Double rate) { mEffectView.getTCEffectPlayer().setRate(rate.floatValue()); } + @NonNull + @Override + public TCEffectMessages.FTCEffectAnimInfoMsg preloadTCAnimInfo(@NonNull String playUrl, @NonNull TCEffectMessages.FTCEffectConfigMsg config) { + TCEffectConfig effectConfig = FEffectViewHelper.transConfigFromMsg(config); + return FEffectViewHelper.transAnimInfoToMsg(TCEffectAnimView.preloadTCAnimInfo(playUrl, effectConfig)); + } + @NonNull @Override public String getSdkVersion() { diff --git a/doc/API Documentation-EN.md b/doc/API Documentation-EN.md deleted file mode 100644 index 6f35e6b..0000000 --- a/doc/API Documentation-EN.md +++ /dev/null @@ -1,599 +0,0 @@ -This article mainly introduces the Flutter API interface document of Tencent Gift AR SDK for easy reference and use. - -## FTCMediaXBase - -### instance - -**Description** - -Get a single instance of FTCMediaXBase. - -**Interface** - -``` dart -static FTCMediaXBase get instance -``` - -**Parameter Description** - -None - -### setLicense - -**Description** - -Set License. - -**Interface** - -``` dart -Future setLicense(String url, String key, FTCMediaLicenseListener listener) async -``` - -**Parameter Description** - -| Parameter name | Type | Description | -| -------- | ---------------- | ---------------- | -| url | String | The url of the license. | -| key | String | The key of the license. | -| callback | ILicenseCallback | Callback | - -Callback declaration: - -``` dart -typedef FTCMediaLicenseListener = void Function(int errCode, String msg); -``` - -Common error codes for license verification: - -| Error code | Description | -| ---------- | ------------------------------------------------------------ | -| 0 | Success. Success. | -| -1 | Invalid input parameters, for example, URL or KEY is empty. | -| -3 | Download failed, please check network settings. | -| -4 | The TE authorization information read from the local is empty, which may be caused by IO failure. | -| -5 | The content of the VCUBE TEMP License file is empty, which may be caused by IO failure. | -| -6 | The JSON field of the v_cube.license file is incorrect. Please contact the Tencent Cloud team for processing. | -| -7 | Signature verification failed. Please contact the Tencent Cloud team for processing. | -| -8 | Decryption failed. Please contact the Tencent Cloud team for processing. | -| -9 | The JSON field in the TELicense field is incorrect. Please contact the Tencent Cloud team for processing. | -| -10 | The TE authorization information parsed from the network is empty. Please contact the Tencent Cloud team for processing. | -| -11 | Failed to write the TE authorization information to the local file, which may be caused by IO failure. | -| -12 | Download failed, and parsing of local assets also failed. | -| -13 | Authentication failed, please check whether so is in the package, or the so path has been set correctly. | -| 3004/3005 | Invalid authorization. Please contact the Tencent Cloud team for processing. | -| 3015 | Bundle Id / Package Name does not match. Check whether the Bundle Id / Package Name used by your App is consistent with the one applied for, and check whether the correct authorization file is used. | -| 3018 | The authorization file has expired and needs to be renewed from Tencent Cloud. | -| Others | Please contact the Tencent Cloud team for processing. | - -### setLogEnable - -**Description** - -Whether to enable log output, default is on. - -**Note:** Android side saves in /sdcard/Android/data/packagename/files/TCMediaX directory, iOS side saves in Documents/TCMediaX directory of sandbox, you can upload the logs in this directory to the business backend according to business needs, to locate online user problems. - -**Interface** - -``` dart -Future setLogEnable(bool enable) async -``` - -## FTCEffectAnimView - -### FTCEffectAnimView - -**Description** - -Create `FTCEffectAnimView` gift animation playback instance. - -**Interface** - -``` dart -FTCEffectAnimView({this.controllerCallback, Key? viewKey}) -``` - -**Parameter Description** - -**Parameter Description** - -| Parameter Name | Type | Description | -| ------------------ | ----------------------------- | ------------------------------------------------------------ | -| controllerCallback | FEffectViewControllerCallback | The playback controller of the current gift animation is successfully created. | - -## FTCEffectViewController - -### startPlay - -**Description** - -Start the player. - -**Interface** - -``` dart -Future startPlay(String playUrl) async -``` - -**Parameter Description** - -playUrl is the video resource address. - -**Note:** Only local video resources on the phone are supported. If you use online video resources, download them locally before playing. - -### setVideoMode - -**Description** - -Set the alignment of the alpha and rgb areas of the tep animation. - -**Interface** - -``` dart -Future setVideoMode(FVideoMode videoMode) async -``` - -**Parameter Description** - -videoMode supports the following formats: - -| Enumeration value | Meaning | -| ---------------------------------------------- | ------------------------------------------- | -| FVideoMode.VIDEO_MODE_NONE | Ordinary mp4 file | -| FVideoMode.EVIDEO_MODE_SPLIT_HORIZONTAL | Align left and right (alpha left\rgb right) | -| FVideoMode.VIDEO_MODE_SPLIT_VERTICAL | Align top and bottom (alpha top\rgb bottom) | -| FVideoMode.VIDEO_MODE_SPLIT_HORIZONTAL_REVERSE | Align left and right (rgb left\alpha right) | -| FVideoMode.VIDEO_MODE_SPLIT_VERTICAL_REVERSE | Align up and down (RGB up\alpha down) | - -### setConfig - -**Description** - -Set the special Gift AR playr parameters, which needs to be called before starting playback. - -**Interface** - -``` dart -Future setConfig(FTCEffectConfig config) async -``` - -**Parameter Description** - -Refer to the FTCEffectConfig class below. - -### setScaleType - -**Description** - -Set the alignment. - -**Interface** - -``` dart -Future setScaleType(FScaleType type) async -``` - -**Parameter Description** - -type supports the following formats: - -| Enumeration value | Meaning | -| ---------------------- | ------------------------------------------------------------ | -| FScaleType.FIT_XY | Completely fill the entire layout, default value. | -| FScaleType.FIT_CENTER | Display completely in the middle of the layout according to the video ratio. | -| FScaleType.CENTER_CROP | Fill the layout completely according to the video ratio (the excess part is not displayed). | - -### setFetchResource - -**Description** - -Set the resources of the fusion animation. - -**Interface** - -``` dart -void setFetchResource(FResourceFetcher resFetcher) -``` - -**Parameter Description** - -FResourceFetcher interface: - -``` dart -class FResourceFetcher { -// Get image -FResImgResultFetcher? imgFetcher; - -// Get text -FResTextResultFetcher? textFetcher; - -// Resource release notification -FResReleaseListener? releaseListener; - -FResourceFetcher({this.imgFetcher, this.textFetcher, this.releaseListener}); -} -``` - -FEffectResource#tag is the tag (subscript) of the fusion animation, which can be used to judge the tag and pass in different text or image resources. - -### requestUpdateResource - -**Description** - -Update the fusion animation information during playback. - -After calling the current method, the IFetchResource interface callback will be triggered to update the fusion animation information. - -**Interface** - -``` dart -Future requestUpdateResource() async -``` - -### setRenderRotation - -**Description** - -Set the rotation angle of the fusion animation selection, supporting 0, 90, 180, 270, 360 degrees. - -**Interface** - -``` dart -Future setRenderRotation(int rotation) async -``` - -### isPlaying - -**Description** - -Return whether the special Gift AR player is playing. - -**Interface** - -``` dart -Future isPlaying() async -``` - -### resume - -**Description** - -Resume the special effect animation playback. - -**Interface** - -``` dart -Future resume() async -``` - -### pause - -**Description** - -Pause the special effect animation playback. - -**Interface** - -``` dart -Future pause() async -``` - -### seekTo - -**Description** - -Jump to the specified position to start playback. - -**Note:** - -- This method can be called only after startPlay(), otherwise it will not take effect. - -- This interface is effective for tcmp4 animations, or mp4 animations played when FCodecType.TX_LITEAV_SDK is set. - -- milliSec: To jump to the specified duration to start playback, in milliseconds. - -**Interface** - -``` dart -Future seekTo(int millSec) async -``` - -### seekProgress - -**Description** - -Go to the specified position to start playing. - -progress: Jump to the specified percentage of the animation duration to start playing, in percentage, value range: [0.0-1.0]. - -**Note:** - -1. This method can be called only after startPlay(), otherwise it will not take effect. - -2. This interface is effective for tcmp4 animation, or mp4 animation played when FCodecType.TX_LITEAV_SDK is set. - -3. The value range of the input parameter progress is [0.0-1.0]. If it exceeds the range, it will not take effect. - -**Interface** - -``` dart -Future seekProgress(double progress) async -``` - -### setLoop - -**Description** - -Set loop playback. - -- true: Indicates loop playback. - -- false: Indicates closing loop playback. - -**Interface** - -``` dart -Future setLoop(bool isLoop) async -``` - -### setLoopCount - -**Description** - -Set the number of loop playback. - -loopCount: Indicates the number of loop playback. When loopCount <= 0, it means infinite loop playback; when loopCount=n(n>=1), it means that the playback is played n times from the beginning to the end. - -**Note:** - -1. The default value of loopCount is 1, that is, when the external method is not actively called, the animation is played only once and then ends. - -2. The setLoop(boolean isLoop) method will call the current method internally, that is, when isLoop = true, it is equivalent to calling setLoopCount(-1); that is, when isLoop = false, it is equivalent to calling setLoopCount(1); therefore, these two methods affect each other, and the later call will overwrite the previous call. - -**Interface** - -``` dart -Future setLoopCount(int loopCount) async -``` - -### setDuration - -**Description** - -Set how long the animation takes to play. After setting, the animation playback speed is automatically adjusted during subsequent animation playback to ensure that the animation ends at the specified duration. - -That is: if the set duration exceeds the original animation duration, the animation will be slowed down; if it is less than the original animation duration, it will be fast-forwarded. - -durationInMilliSec: The duration to be set, in milliseconds. - -**Note:** - -1. Currently only applies to animations in tcmp4 format. - -2. The current method and the setRate method for setting the speed are mutually exclusive, and the later call will overwrite the earlier call. - -**Interface** - -``` dart -Future setDuration(int durationInMilliSec) async -``` - -### stopPlay - -**Description** - -Stop playback. - -**interface** - -``` dart -Future stopPlay({bool? clearLastFrame}) async -``` - -### setMute - -**Description** - -Set whether to play in mute mode. - -- true: Play in mute mode. - -- false: Play in non-mute mode. - -**Interface** - -``` dart -Future setMute(bool mute) -``` - -### setPlayListener - -**Description** - -Set the playback callback of the special Gift AR player. - -**Interface** - -``` dart -void setPlayListener(FAnimPlayListener? listener) -``` - -**Parameter Description** - -IAnimPlayListener interface: - -``` dart -class FAnimPlayListener { -FEmptyFunction? onPlayStart; - -FEmptyFunction? onPlayEnd; - -FIntParamsFunction? onPlayError; - -FOnPlayEventFunction? onPlayEvent; - -FAnimPlayListener({this.onPlayStart, this.onPlayEnd, this.onPlayError, this.onPlayEvent}); -} -``` - -For the event value in the onPlayEvent method, see the constant value in the FTCEffectPlayerConstant class: - -``` dart -static static int REPORT_INFO_ON_PLAY_EVT_PLAY_END = 2006; -static static int REPORT_INFO_ON_PLAY_EVT_RCV_FIRST_I_FRAME = 2003; -static static int REPORT_INFO_ON_PLAY_EVT_CHANGE_RESOLUTION = 2009; -static static int REPORT_INFO_ON_PLAY_EVT_LOOP_ONCE_COMPLETE = 6001; -static static int REPORT_INFO_ON_VIDEO_CONFIG_READY = 200001; -static static int REPORT_INFO_ON_NEED_SURFACE = 200002; -static static int REPORT_INFO_ON_VIDEO_SIZE_CHANGE = 200003; -static static int REPORT_ANIM_INFO = 200004; -``` - -For details on the errorCode value in the onPlayError method, see FTCEffectPlayerConstant Constant values in the class: - -``` dart -static const REPORT_ERROR_TYPE_HEVC_NOT_SUPPORT = -10007; // h265 is not supported -static const REPORT_ERROR_TYPE_INVALID_PARAM = -10008; // Illegal parameters -static const REPORT_ERROR_TYPE_INVALID_LICENSE = -10009; // Illegal License -static const REPORT_ERROR_TYPE_ADVANCE_MEDIA_PLAYER = -10010; // MediaPlayer playback failed -static const REPORT_ERROR_TYPE_MC_DECODER = -10011; // Decoder failed in MediaCodec -static const REPORT_ERROR_TYPE_UNKNOWN_ERROR = -20000; // Unknown error -``` - -### getTCAnimInfo - -**Description** - -Get the information corresponding to the currently playing animation and return the FTCEffectAnimInfo instance. For details, see FTCEffectAnimInfo. - -**Note:** - -This method must be called in the FAnimPlayListener#onPlayStart() method or after this method is executed to get the information of the current animation, otherwise it returns null. - -**Interface** - -``` dart -Future getTCAnimInfo() async -``` - -### FTCEffectConfig - -**Description** - -Construct special effects player configuration. - -**codecType property** - -``` dart -// Set CodecType -FCodecType? codecType; -``` - -**Parameter Description** - -It has three values, namely: - -- FCodecType.TC_MPLAYER (MPLAYER playback engine, only valid on Android platform) - -- FCodecType.TC_MCODEC (MCODEC playback engine, only valid on Android platform) - -- FCodecType.TX_LITEAV_SDK (Tencent Cloud Player SDK, valid on Andriod and iOS platforms) - -**Note:** - -1. Currently, only calling the setConfig() method before the player starts to set the playback configuration is supported. Configuration modification is not supported after the playback starts. -1. The three currently supported CodecTypes are only valid for TEP animations. -1. If CodecType is set to FCodecType.TX_LITEAV_SDK , you also need to separately introduce Tencent Cloud Player SDK, and apply for and register its corresponding license. - -**freezeFrame property** - -``` dart -// Set the freeze frame index -FFreezeFrame? freezeFrame; -``` - -**Parameter description** - -The input parameter frame indicates which frame the animation needs to stay at during playback. Currently available values: - -- FFreezeFrame.FREEZE_FRAME_NONE: Turn off the freezeFrame capability, and the player will pause and disappear when playing normally. - -- FFreezeFrame.FREEZE_FRAME_LAST: After the first playback is completed, the picture stays at the last frame. - -**animType attribute** - -``` dart -// Set the animation format to be played later -FAnimType? animType; -``` - -**Parameter description** - -Used to specify the animation format to be played later, applicable to the scene where the suffix of the animation file to be played is modified in some cases. The input parameter type indicates the animation format to be specified. Currently available values: - -- FAnimType.AUTO (SDK default strategy, that is, the animation format is determined by the suffix of the animation file, such as tcmp4/mp4/tep/tepg and other formats.) - -- FAnimType.MP4 (MP4 animation format, animation files will be played as MP4 type in the future, regardless of the file suffix.) - -- FAnimType.TCMP4 (TCMP4 animation format, animation files will be played as TCMP4 type in the future, regardless of the file suffix.) - -## FTCEffectAnimInfo - -**Description** - -Stores the animation information currently being played. - -**Property Description** - -| Property Name | Type | Description | -| ------------- | -------- | ------------------------------------------------------------ | -| type | int | Current animation type, value: FAnimType.MP4 MP4 type resource and FAnimType.TCMP4 TCMP4 type resource. | -| duration | long | Animation duration, in milliseconds. | -| width | int | Animation width. | -| height | int | Animation height. | -| encryptLevel | int | Advanced encryption type of the current animation, if the value is 0, it means there is no advanced encryption, otherwise it means it is already advanced encryption. | -| mixInfo | FMixInfo | Fusion animation information, if it is null, it means that the animation has no fusion information. | - -## FMixInfo - -**Description** - -Stores the fusion information of the currently playing animation. - -**Property Description** - -| Property Name | Type | Description | -| ---------------- | -------------- | ------------------------------------------------------------ | -| textMixItemList | List | Text fusion information. When null, it means there is no text fusion information. | -| imageMixItemList | List | Image fusion information. When null, it means there is no image fusion information. | - -## FMixItem - -**Description** - -Stores the fusion information of the currently playing animation. - -**Property Description** - -| Property Name | Type | Description | -| ------------- | ------ | ------------------------------------------------------------ | -| id | String | Current fusion animation id. | -| tag | String | Current fusion animation tag. | -| text | String | Current text fusion animation text content (the value is empty for image fusion animation). If it is tcmp4, it is the original text content inside; if it is mp4, it is the tag value filled in the tool. | - -## FTCEffectText - -**Description** - -Fusion animation replacement text style data class. - -**Property Description** - -| Property Name | Type | Description | -| ------------- | ------ | ------------------------------------------------------------ | -| text | String | The text content to be replaced in the end. | -| color | int | Text color, format requirements: ARGB, such as 0xFFFFFFFF. | -| fontStyle | String | Text display style, possible values: "bold" means bold, default size if not passed. | -| alignment | int | Text alignment, possible values: TEXT_ALIGNMENT_NONE (default value, i.e. keep the SDK default alignment), TEXT_ALIGNMENT_LEFT (left), TEXT_ALIGNMENT_CENTER (center), TEXT_ALIGNMENT_RIGHT (right). | -| fontSize | double | Text size, in px; if the text size is set (value greater than 0), the internal automatic scaling strategy will fail, and the set text size will be used as the standard, which may cause the text to be too large and not fully displayed. | diff --git a/doc/API Documentation-zh_CN.md b/doc/API Documentation-zh_CN.md deleted file mode 100644 index 47f4567..0000000 --- a/doc/API Documentation-zh_CN.md +++ /dev/null @@ -1,583 +0,0 @@ -本文主要介绍腾讯礼物动画特效 SDK 的 Flutter 端 API 接口文档，以便于查阅和使用。 - -## FTCMediaXBase - -### instance - -**说明** - -获取 FTCMediaXBase 的单例。 - -**接口** -``` dart -static FTCMediaXBase get instance -``` - -**参数说明** - -无 - -### setLicense - -**说明** - -设置 License。 - -**接口** -``` dart -Future setLicense(String url, String key, FTCMediaLicenseListener listener) async -``` - -**参数说明** - -**参数说明** - -| 参数名 | 类型 | 描述 | -| -------- | ---------------- | ---------------- | -| url | String | licence 的 url。 | -| key | String | licence 的 key。 | -| callback | ILicenseCallback | 回调 | - - -回调声明： -``` dart -typedef FTCMediaLicenseListener = void Function(int errCode, String msg); -``` - -License 校验常见错误码： - -| 错误码 | 描述 | -| --------- | ------------------------------------------------------------ | -| 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 | 授权文件已过期，需要向腾讯云申请续期。 | -| 其他 | 请联系腾讯云团队处理。 | - - -### setLogEnable - -**说明** - -是否开启 Log 输出，默认开始。 - -**注意：**Android 端保存在 /sdcard/Android/data/packagename/files/TCMediaX 目录，iOS 端保存在 sandbox 的 Documents/TCMediaX 目录，您可以根据业务需要把此目录的日志上传到业务后台，用于定位线上用户问题。 - -**接口** - -``` dart -Future setLogEnable(bool enable) async -``` - -## FTCEffectAnimView - -### FTCEffectAnimView - -**说明** - -创建 `FTCEffectAnimView` 礼物动画播放实例。 - -**接口** - -``` dart -FTCEffectAnimView({this.controllerCallback, Key? viewKey}) -``` - -**参数说明** - -**参数说明** - -| 参数名 | 类型 | 描述 | -| ------------------ | ----------------------------- | -------------------------------------- | -| controllerCallback | FEffectViewControllerCallback | 当前礼物动画的播放控制器创建成功回调。 | - -## FTCEffectViewController - -### startPlay - -**说明** - -启动播放器。 - -**接口** -``` dart -Future startPlay(String playUrl) async -``` - -**参数说明** - -playUrl 为视频资源地址。 - -**注意：**只支持播放手机本地视频资源， 如果您使用的网络视频资源， 先下载到本地再播放。 - - -### setVideoMode - -**说明** - -设置 tep 动画的 alpha 和 rgb 区域的对齐方式。 - -**接口** -``` dart -Future setVideoMode(FVideoMode videoMode) async -``` - -**参数说明** - -videoMode 支持以下格式： - -| 枚举值 | 含义 | -| ---------------------------------------------- | ------------------------- | -| FVideoMode.VIDEO_MODE_NONE | 普通mp4文件 | -| FVideoMode.EVIDEO_MODE_SPLIT_HORIZONTAL | 左右对齐（alpha左\rgb右） | -| FVideoMode.VIDEO_MODE_SPLIT_VERTICAL | 上下对齐（alpha上\rgb下） | -| FVideoMode.VIDEO_MODE_SPLIT_HORIZONTAL_REVERSE | 左右对齐（rgb左\alpha右） | -| FVideoMode.VIDEO_MODE_SPLIT_VERTICAL_REVERSE | 上下对齐（rgb上\alpha下） | - - -### setConfig - -**说明** - -设置特效播放器参数，需要在启动播放前调用。 - -**接口** -``` dart -Future setConfig(FTCEffectConfig config) async -``` - -**参数说明** - -参考下面 FTCEffectConfig 类。 - -### setScaleType - -**说明** - -设置对齐方式。 - -**接口** -``` dart -Future setScaleType(FScaleType type) async -``` - -**参数说明** - -type 支持以下格式： - -| 枚举值 | 含义 | -| ---------------------- | ------------------------------------------ | -| FScaleType.FIT_XY | 完整填充整个布局，默认值。 | -| FScaleType.FIT_CENTER | 按视频比例在布局中间完整显示。 | -| FScaleType.CENTER_CROP | 按视频比例完整填充布局（多余部分不显示）。 | - - -### setFetchResource - -**说明** - -设置融合动画的资源。 - -**接口** -``` dart -void setFetchResource(FResourceFetcher resFetcher) -``` - -**参数说明** - -FResourceFetcher 接口： -``` dart -class FResourceFetcher { - // 获取图片 - FResImgResultFetcher? imgFetcher; - - // 获取文字 - FResTextResultFetcher? textFetcher; - - // 资源释放通知 - FResReleaseListener? releaseListener; - - FResourceFetcher({this.imgFetcher, this.textFetcher, this.releaseListener}); -} -``` - -FEffectResource#tag 为融合动画的 tag（下标），可以判断 tag 传入不同的文字或图片资源。 - -### requestUpdateResource - -**说明** - -播放过程中更新融合动画信息。 - -调用当前方法之后，会触发 IFetchResource 接口回调更新融合动画信息。 - -**接口** -``` dart -Future requestUpdateResource() async -``` - -### setRenderRotation - -**说明** - -设置融合动画选择旋转角度，支持 0， 90，180, 270， 360 度。 - -**接口** -``` dart -Future setRenderRotation(int rotation) async -``` - -### isPlaying - -**说明** - -返回特效播放器是否在播放中。 - -**接口** -``` dart -Future isPlaying() async -``` - -### resume - -**说明** - -恢复特效动画播放。 - -**接口** -``` dart -Future resume() async -``` - -### pause - -**说明** - -暂停特效动画播放。 - -**接口** -``` dart -Future pause() async -``` - -### seekTo - -**说明** - -跳转到指定位置开始播放。 - -**注意：** - -- startPlay() 之后才可以调用该方法，否则不生效。 -- 该接口对于 tcmp4 动画、或者设置了 FCodecType.TX_LITEAV_SDK 时播放的mp4动画生效。 -- milliSec：要跳转到指定时长处开始播放，单位毫秒。 - - -**接口** -``` dart -Future seekTo(int millSec) async -``` - -### seekProgress - -**说明** - -跳转到指定位置开始播放。 - -progress：跳转到动画时长的指定百分比处开始播放，单位百分比，取值范围为：[0.0-1.0]。 - -**注意：** - -1. startPlay() 之后才可以调用该方法，否则不生效。 -2. 该接口对于 tcmp4 动画、或者设置了 FCodecType.TX_LITEAV_SDK 时播放的mp4动画生效。 -3. 入参 progress 取值范围为 [0.0-1.0]，超出范围的不生效。 - - -**接口** -``` dart -Future seekProgress(double progress) async -``` - -### setLoop - -**说明** - -设置循环播放。 -- true： 表示循环播放。 - -- false： 表示关闭循环播放。 - - - **接口** - - ``` dart - Future setLoop(bool isLoop) async - ``` - -### setLoopCount - -**说明** - -设置循环播放次数。 - -loopCount：表示循环播放次数。当 loopCount <= 0 时，表示无限循环播放；当 loopCount=n(n>=1)时表示从开始播放到播放结束，共播放 n 次。 - -**注意：** - -1. loopCount 默认值是1，即当外部不主动调用该方法时，动画只播放一次就结束。 -2. setLoop(boolean isLoop) 方法内部会调用当前方法，即当 isLoop = true 时，等价于调用 setLoopCount(-1)；即当 isLoop = false 时，等价于调用 setLoopCount(1)；因此这两个方法是互相影响的，后调用的会覆盖之前的调用。 - - -**接口** -``` dart -Future setLoopCount(int loopCount) async -``` - -### setDuration - -**说明** - -设置动画需要多长时间播放完成。设置之后，后续动画播放时自动调整动画播放速度，以保证动画在设置的规定时长时播放结束。 - -即：设置的时长超过动画原时长，则动画慢放；小于动画原时长，则快进播放。 - -durationInMilliSec： 要设置的时长，单位毫秒。 - -**注意：** - -1. 目前仅对 tcmp4 格式的动画生效。 -2. 当前方法和 setRate 设置倍速的方法是互斥的，后调用的会覆盖掉先调用的。 - - -**接口** -``` dart -Future setDuration(int durationInMilliSec) async -``` - -### stopPlay - -**说明** - -停止播放。 - -**接口** -``` dart -Future stopPlay({bool? clearLastFrame}) async -``` - -### setMute - -**说明** - -设置是否静音播放。 -- true： 静音播放。 - -- false： 非静音播放。 - - - **接口** - - ``` dart - Future setMute(bool mute) - ``` - -### setPlayListener - -**说明** - -设置特效播放器播放回调。 - -**接口** -``` dart -void setPlayListener(FAnimPlayListener? listener) -``` - -**参数说明** - -IAnimPlayListener 接口： -``` dart -class FAnimPlayListener { - FEmptyFunction? onPlayStart; - - FEmptyFunction? onPlayEnd; - - FIntParamsFunction? onPlayError; - - FOnPlayEventFunction? onPlayEvent; - - FAnimPlayListener({this.onPlayStart, this.onPlayEnd, this.onPlayError, this.onPlayEvent}); -} -``` - -对于 onPlayEvent 方法中的 event 值详见 FTCEffectPlayerConstant 类中的常量值: -``` dart -static static int REPORT_INFO_ON_PLAY_EVT_PLAY_END = 2006; -static static int REPORT_INFO_ON_PLAY_EVT_RCV_FIRST_I_FRAME = 2003; -static static int REPORT_INFO_ON_PLAY_EVT_CHANGE_RESOLUTION = 2009; -static static int REPORT_INFO_ON_PLAY_EVT_LOOP_ONCE_COMPLETE = 6001; -static static int REPORT_INFO_ON_VIDEO_CONFIG_READY = 200001; -static static int REPORT_INFO_ON_NEED_SURFACE = 200002; -static static int REPORT_INFO_ON_VIDEO_SIZE_CHANGE = 200003; -static static int REPORT_ANIM_INFO = 200004; -``` - -对于 onPlayError 方法中的 errorCode 值详见 FTCEffectPlayerConstant 类中的常量值： -``` dart -static const REPORT_ERROR_TYPE_HEVC_NOT_SUPPORT = -10007; // 不支持h265 -static const REPORT_ERROR_TYPE_INVALID_PARAM = -10008; // 参数非法 -static const REPORT_ERROR_TYPE_INVALID_LICENSE = -10009; // License 不合法 -static const REPORT_ERROR_TYPE_ADVANCE_MEDIA_PLAYER = -10010; // MediaPlayer播放失败 -static const REPORT_ERROR_TYPE_MC_DECODER = -10011; // MediaCodec 中 Decoder 失败 -static const REPORT_ERROR_TYPE_UNKNOWN_ERROR = -20000; // 未知错误 -``` - -### getTCAnimInfo - -**说明** - -获取当前播放动画对应的信息，返回 FTCEffectAnimInfo 实例，详见 FTCEffectAnimInfo。 - -**注意：** - -该方法必须在 FAnimPlayListener#onPlayStart() 方法中，或者该方法执行之后调用才可以获取到当前动画的信息，否则返回 null。 - -**接口** - -``` dart -Future getTCAnimInfo() async -``` - -## FTCEffectConfig - -**说明** - -构造特效播放器配置。 - -**codecType 属性** - -``` dart -// 设置 CodecType -FCodecType? codecType; -``` - -**参数说明** - -它有三个取值，分别是： -- FCodecType.TC_MPLAYER (MPLAYER 播放引擎， 仅在 Android 平台生效) -- FCodecType.TC_MCODEC(MCODEC 播放引擎，仅在 Android 平台生效) -- FCodecType.TX_LITEAV_SDK (腾讯云播放器 SDK，在 Andriod 和 iOS 平台生效) - - -**注意：** - -1. 目前仅支持在播放器开始前调用 setConfig() 方法来设置播放配置，开始播放后不支持修改配置。 -1. 目前支持的三种 CodecType 仅对 TEP 动画生效。 -1. 如果设置 CodecType 为 FCodecType.TX_LITEAV_SDK ，则还需要单独引入腾讯云播放器 SDK，以及申请、注册好其对应的license。 - -**freezeFrame 属性** - - ``` dart - // 设置冻结停留帧索引 - FFreezeFrame? freezeFrame; - ``` - - **参数说明** - - - 入参 frame 表示当动画播放中需要停留在哪一帧。目前可选值： - -- FFreezeFrame.FREEZE_FRAME_NONE：关闭 freezeFrame 能力，播放器正常播放暂停消失。 -- FFreezeFrame.FREEZE_FRAME_LAST：当第一次播放完毕之后，画面停留在最后一帧。 - -**animType 属性** - -``` dart -// 设置后续要播放的动画格式 -FAnimType? animType; -``` - -**参数说明** - - - 用于指定后续要播放的动画格式，适用于某些情况下，要播放的动画文件后缀被修改的场景。入参 type 表示要指定的动画格式。目前可选值： - -- FAnimType.AUTO (SDK 默认策略，即以动画文件的后缀来判断动画格式，比如 tcmp4/mp4/tep/tepg 等格式。) - -- FAnimType.MP4 (MP4动画格式，后续都将动画文件当做MP4类型来播放，无视文件后缀名。) - -- FAnimType.TCMP4 (TCMP4动画格式，后续都将动画文件当做TCMP4类型来播放，无视文件后缀名。) - - -## FTCEffectAnimInfo - -**说明** - -存储当前播放的动画信息。 - -**属性说明** - -| 属性名 | 类型 | 描述 | -| ------------ | -------- | ------------------------------------------------------------ | -| type | int | 当前动画类型，取值：FAnimType.MP4 MP4类型的资源和 FAnimType.TCMP4 TCMP4类型的资源。 | -| duration | long | 动画时长，单位毫秒。 | -| width | int | 动画宽度。 | -| height | int | 动画高度。 | -| encryptLevel | int | 当前动画的高级加密类型，取值如果是 0，表示没有高级加密，否则表示已是高级加密。 | -| mixInfo | FMixInfo | 融合动画信息，为 null 时则表示该动画无融合信息。 | - - -## FMixInfo - -**说明** - -存储当前播放动画中的融合信息。 - -**属性说明** -| 属性名 | 类型 | 描述 | -| ---------------- | -------------- | ---------------------------------------------- | -| textMixItemList | List | 文字融合信息，为 null 时则表示无文字融合信息。 | -| imageMixItemList | List | 图片融合信息，为 null 时则表示无图片融合信息。 | - - -## FMixItem - -**说明** - -存储当前播放动画中的融合信息。 - -**属性说明** - -| 属性名 | 类型 | 描述 | -| ------ | ------ | ------------------------------------------------------------ | -| id | String | 当前融合动画 id。 | -| tag | String | 当前融合动画 tag。 | -| text | String | 当前文字融合动画文字内容(图片融合动画时该值为空)。如果是 tcmp4 时，则是其内部原始的文字内容；如果是 mp4 时，则是在工具中填写的 tag 值。 | - - -## FTCEffectText - -**说明** - -融合动画替换文本样式数据类。 - -**属性说明** - -| 属性名 | 类型 | 描述 | -| --------- | ------ | ------------------------------------------------------------ | -| text | String | 最终要替换显示的文本内容。 | -| color | int | 文字颜色，格式要求：ARGB，如 0xFFFFFFFF。 | -| fontStyle | String | 文字显示样式，可取值："bold"表示粗体，不传则默认大小。 | -| alignment | int | 文字对齐方式，可取值：TEXT_ALIGNMENT_NONE（默认值，即保持 SDK 默认对齐方式）、TEXT_ALIGNMENT_LEFT（居左） 、TEXT_ALIGNMENT_CENTER（居中）、 TEXT_ALIGNMENT_RIGHT（居右）。 | -| fontSize | double | 文字大小，单位是px；如果设置了文字大小(值大于0)，则内部自动缩放策略失效，强制以设置的文字大小为准，则可能出现文字过大显示不全的问题。 | diff --git a/doc/Integration Guide-zh_CN.md b/doc/Integration Guide-zh_CN.md deleted file mode 100644 index f08bc09..0000000 --- a/doc/Integration Guide-zh_CN.md +++ /dev/null @@ -1,41 +0,0 @@ -# 集成指引 - -## 环境准备 - -- 支持 Flutter 3.16.0 及以上版本。 - -- Android 端开发： - - - Android Studio 3.5及以上版本。 - - - App 要求 Android 4.1及以上版本设备。 - -- iOS 端开发： - - - Xcode 11.0及以上版本。 - - - OSX 系统版本要求 10.11 及以上版本。 - - - 请确保您的项目已设置有效的开发者签名。 - -## 快速集成 - -### 在项目的 pubspec.yaml 中添加依赖 - -目前仅支持通过 github 集成，暂不支持通过 pub 集成，在`pubspec.yaml`中增加配置： - -``` -flutter_effect_player: - git: - url: https://github.com/Tencent-RTC/EffectPlayer_Flutter -``` - -如果需要特定版本，可以指定通过 ref 依赖的 tag 来指定到对应版本，如下所示： - -``` -flutter_effect_player: - git: - url: https://github.com/Tencent-RTC/EffectPlayer_Flutter - ref: release_example_tag -``` - diff --git a/doc/Integration Guide_EN.md b/doc/Integration Guide_EN.md deleted file mode 100644 index 485598c..0000000 --- a/doc/Integration Guide_EN.md +++ /dev/null @@ -1,39 +0,0 @@ -# Integration Guide - -## Environment Preparation - -- Supports Flutter 3.16.0 and above. - -- Android development: - - Android Studio 3.5 and above. - - - App requires Android 4.1 and above devices. - -- iOS development: - - Xcode 11.0 and above. - - - OSX system version requires 10.11 and above. - - - Please make sure your project has set a valid developer signature. - - -## Quick integration - -### Add dependencies in the project's pubspec.yaml - -Currently, only integration through github is supported, and integration through pub is not supported yet. Add configuration in `pubspec.yaml`: - -``` -flutter_effect_player: - git: - url: https://github.com/Tencent-RTC/EffectPlayer_Flutter -``` - -If a specific version is required, you can specify the corresponding version through the tag of the ref dependency, as shown below: - -``` -flutter_effect_player: - git: - url: https://github.com/Tencent-RTC/EffectPlayer_Flutter - ref: release_example_tag -``` diff --git a/doc/Quick Run Demo-EN.md b/doc/Quick Run Demo-EN.md deleted file mode 100644 index 0afd24c..0000000 --- a/doc/Quick Run Demo-EN.md +++ /dev/null @@ -1,38 +0,0 @@ -# Run Demo Quickly - -## Environment Preparation - -- Supports Flutter 3.16.0 and above. - -- Android development: - - Android Studio 2.0 or above. - - - Android SDK API Level 19 and above. - - - Android 4.4 and above, support mobile devices with armeabi-v7a and arm-v8a architectures. - -- iOS development: - - Xcode 11.0 and above. - - - OSX system version requires 10.11 and above. - - - Please make sure that your project has set a valid developer signature. - - -## Quick Integration - -### Import Project - -Import the EffectPlayer_Flutter project into Android Studio and pull dependencies. - -### Apply for a License - -International customers [click here](https://trtc.io/document/60219?product=beautyar&menulabel=core%20sdk&platform=android) Apply for a Gift Animation Special Effects Test License. - -After successfully applying for the LicenseUrl and LicenseKey, assign them to the LICENSE_URL and LICENSE_KEY fields in `example/lib/main.dart`. - -### Run the project - -Android: Replace `applicationId = "com.tencent.tcmediax.demo"` in the `example/android/app/build.gradle.kts` file with the Package Name filled in when applying for the License. - -iOS: Replace the Bundle Identifer of the example run with the Bundle ID filled in when applying for the License. diff --git a/doc/Quick Run Demo-zh_CN.md b/doc/Quick Run Demo-zh_CN.md deleted file mode 100644 index 423046f..0000000 --- a/doc/Quick Run Demo-zh_CN.md +++ /dev/null @@ -1,39 +0,0 @@ -# 快速跑通 Demo - -## 环境准备 - -- 支持 Flutter 3.16.0 及以上版本。 - -- Android 端开发： - - - Android Studio 2.0 或以上版本。 - - - Android SDK API Level 19 及以上。 - - - Android 4.4 及以上，支持 armeabi-v7a、arm-v8a 架构的移动设备。 - -- iOS 端开发： - - - Xcode 11.0及以上版本。 - - - OSX 系统版本要求 10.11 及以上版本。 - - - 请确保您的项目已设置有效的开发者签名。 - -## 快速集成 - -### 导入项目 - -把 EffectPlayer_Flutter 项目导入到 Android Studio 后拉取依赖。 - -### 申请 License - -中国站客户 [点击这里](https://cloud.tencent.com/document/product/616/116465) 申请 礼物动画特效测试 License。 - -成功申请到 LicenseUrl 和 LicenseKey 后，把它们赋值给 example/lib/main.dart 里面的 LICENSE_URL 和 LICENSE_KEY 字段。 - -### 运行项目 - -Android 端：把 example/android/app/build.gradle.kts 文件里 applicationId = "com.tencent.tcmediax.demo" 替换为申请 License 是填写的Package Name。 - -iOS 端： 把 example 运行的 Bundle Identifer 替换为 申请 License 时填写的 Bundle ID。 diff --git a/doc/User Documentation-EN.md b/doc/User Documentation-EN.md deleted file mode 100644 index df11db5..0000000 --- a/doc/User Documentation-EN.md +++ /dev/null @@ -1,225 +0,0 @@ -This document mainly introduces how to quickly integrate the Tencent Gift AR Flutter SDK into your project. Configure according to the following steps, and you can complete the integration work of the SDK. - -## Initialize License Registration - -Before officially using the Tencent Gift AR Flutter SDK, you need to set up the License. Only after successfully setting the License can you proceed to use the SDK. - -The method to set the License is as follows: - -```java -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}"); -}); -``` - -> **Note:** -> -> * The License involves strict online verification. After the app is launched for the first time, when calling `FTCMediaXBase.instance.setLicense`, ensure that the network is available. On the app’s first launch, network permission might not have been granted yet. You need to wait for network permissions to be granted and then call the method again. -> * Listen for the callback result of `FTCMediaXBase.instance.setLicense`. If it fails, retry and guide accordingly based on the actual situation. If multiple failures occur, you can limit the frequency and provide product popups or other guidance to help the user check their network situation. - -**License errorCode explanation:** - -| Error Code | Description | -| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 0 | Success. | -| -1 | Invalid input parameters, such as empty URL or KEY. | -| -3 | Download failed, check network settings. | -| -4 | Local TE authorization info is empty, possibly due to IO failure. | -| -5 | Failed to read the VCUBE TEMP License file content, possibly due to IO failure. | -| -6 | The `v_cube.license` file JSON fields are incorrect. Please contact the Tencent Cloud team. | -| -7 | Signature verification failed. Please contact the Tencent Cloud team. | -| -8 | Decryption failed. Please contact the Tencent Cloud team. | -| -9 | Incorrect JSON fields in the TELicense field. Please contact the Tencent Cloud team. | -| -10 | TE authorization info parsed from the network is empty. Please contact the Tencent Cloud team. | -| -11 | Failed to write TE authorization info to a local file, possibly due to IO failure. | -| -12 | Download failed and parsing local asset also failed. | -| -13 | Authorization failed, check if the SO file is in the package, or if the SO path is correctly set. | -| 3004/3005 | Invalid authorization. Please contact the Tencent Cloud team. | -| 3015 | Bundle Id / Package Name mismatch. Check if the Bundle Id / Package Name used by your app matches the application one, and check if the correct authorization file is used. | -| 3018 | License file has expired, renewal from Tencent Cloud is required. | -| Other | Please contact the Tencent Cloud team. | - -## Log Management - -The Tencent Gift Animation Effects SDK supports saving runtime logs by default. If any issues arise during testing, you can extract the logs and provide them to Tencent Cloud support. You can also upload these logs to your backend to help diagnose user issues online. - -1. On Android, logs are saved in the directory: `/sdcard/Android/data/${your_packagename}/files/TCMediaLog`. The log files are named by date, and you can export the `TCMediaLog` folder: - -![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100034408908/1a1e4d0e095511f0990f52540099c741.png) - -2. On iOS, logs are saved in the sandbox `Documents/TCMedialog` folder, with log files named by date. For detailed log export instructions, [refer here](https://trtc.io/document/70544?platform=ios&product=beautyar&menulabel=core%20sdk#59b6468e-c7a0-48da-9b96-94c85e49e48c). - -> **Note:** -> -> **No log files?** -> -> Check if you have disabled logs by setting `FTCMediaXBase.instance.setLogEnable` to false. By default, file logs are enabled. - -## Player Usage - -### Introduce FTCEffectAnimView - -```dart -Widget _getFTCEffectAnimView() { - return FTCEffectAnimView( - controllerCallback: (controller){ - // controller.setLoop(true); - // controller.startPlay("xxxxxxx"); - } - ); -} -``` - -### Playback Listener - -You can set an animation playback status listener before starting playback by calling the `setPlayListener` method: - -```dart -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 -})); -``` - -1. If you need to get the current animation information, you can call `getTCAnimInfo()` in the `onPlayStart()` method (or after it is executed) to get the `FTCEffectAnimInfo` object instance, which provides the current animation type, duration, width, height, and merged animation information. - -### Playback Configuration - -```dart -// Set playback configuration, optional step -final FTCEffectConfig _curConfig = FTCEffectConfig()..codecType = FCodecType.TC_MPLAYER; -controller?.setConfig(_curConfig); -``` - -The `FTCEffectConfig` currently supports: - -1. `FCodecType codecType`: It has three possible values: - -* `FCodecType.TC_MPLAYER` (MPLAYER playback engine) -* `FCodecType.TC_MCODEC` (MCODEC playback engine) -* `FCodecType.TX_LITEAV_SDK` (Tencent Cloud Player SDK) - -> **Note:** -> -> 1. Currently, `setConfig()` must be called before starting playback, and configurations cannot be modified after playback has started. -> 2. The above settings currently only apply to MP4 animations. -> 3. If set to `FCodecType.TX_LITEAV_SDK`, you also need to introduce the Tencent Cloud Player SDK and apply for and register its corresponding License. -> 4. If no config is set, the default codec type is `FCodecType.TC_MPLAYER`. - -2. `FFreezeFrame freezeFrame`: Used to set the animation freeze frame. For a detailed explanation, see the API documentation. - -3. `FAnimType animType`: Used to specify the animation format to be played. This is suitable for cases where the animation file extension is changed. The possible values are: - -> * `FAnimType.AUTO` (SDK default strategy, determines the animation format based on the file extension, such as tcmp4/mp4/tep/tepg formats). -> * `FAnimType.MP4` (MP4 animation format, the file will always be treated as MP4 format regardless of the file extension). -> * `FAnimType.TCMP4` (TCMP4 animation format, the file will always be treated as TCMP4 format regardless of the file extension). - -### Fusion Animation Configuration - -Implement the playback of mp4 or tcmp4 fusion animations, you need to implement `FResourceFetcher`. - -1. If it's an image-based fusion animation, you need to implement `FResImgResultFetcher`, which returns the corresponding image’s `Uint8List` to replace the corresponding element. - -2. If it's a text-based fusion animation, you need to implement `FResTextResultFetcher`, which returns the corresponding `FTCEffectText` object instance to specify the display configuration of the text. - - ```dart - controller?.setFetchResource(FResourceFetcher(textFetcher: (res) { - // Return an FTCEffectText instance, where you can specify the text content, color, etc. - return FTCEffectText() - ..text = "FTCEffect${res.id}" - ..color = 0xff0000ff; - }, imgFetcher: (res) { - // Prepare the image data to be replaced in advance and return it here. - // final data = await rootBundle.load('asset/image/head1.png'); - // _samplePng = data.buffer.asUint8List(); - return _samplePng; - })); - ``` - -### Playback Control - -#### Start Playback - -Supports playing `.mp4`, `.tcmp4` file format resources. - -> **Note:** -> -> 1. Only local video resources are supported. If you're using network video resources, download them to local storage before playback. -> 2. Animation resources can be generated using the [Effect Conversion Tool](https://trtc.io/document/70541?platform=android&product=beautyar&menulabel=core%20sdk), and VAP format animation resources are also supported for playback. - -```dart -controller?.startPlay("xxxx") -``` - -#### Pause Playback - -```dart -controller?.pause() -``` - -#### Resume Playback - -```dart -controller?.resume() -``` - -#### Loop Playback - -```dart -controller?.setLoop(true) -``` - -#### Mute Playback - -```dart -controller?.setMute(true) -``` - -#### Stop Playback - -When the player is no longer needed, stop playback and release the resources it occupies. - -```dart -controller?.stopPlay() -``` - -## Common Problems - -### What to do when the following log appears during playback? - -```plaintext -License checked failed! tceffect player -``` - - -license required! - -``` - -Please check if you have applied for the effect player License and initialized it. - -## Common Error Codes - -| Error Code | Description | -|------------|-------------| -| -10003 | Failed to create thread. | -| -10004 | Failed to create render. | -| -10005 | Failed to parse configuration. | -| -10006 | File cannot be read. | -| -10007 | The animation video encoding format is H.265, which is not supported on the current device. | -| -10008 | Invalid parameter. | -| -10009 | Invalid license. | -| -10010 | MediaPlayer playback failed. | -| -10012 | Missing essential dependencies, such as missing `liteavSDK` when `TX_LITEAV_SDK` is used. | ---- -``` diff --git a/doc/User Documentation-zh_CN.md b/doc/User Documentation-zh_CN.md deleted file mode 100644 index b9b4ef6..0000000 --- a/doc/User Documentation-zh_CN.md +++ /dev/null @@ -1,353 +0,0 @@ -本文将详细介绍如何在项目中快速地使用腾讯礼物动画特效 Flutter SDK。只需遵循以下步骤，即可完成 SDK 的配置和使用。 - -## 初始化注册 License - -在正式使用腾讯礼物动画特效 SDK 时，需要先设置 License，设置 License 成功之后，才可以进行后续的 SDK 使用。 - -设置 License 方式如下： -``` java -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 失败引起。
-6v_cube.license 文件 JSON 字段不对。请联系腾讯云团队处理。
-7签名校验失败。请联系腾讯云团队处理。
-8解密失败。请联系腾讯云团队处理。
-9TELicense 字段里的 JSON 字段不对。请联系腾讯云团队处理。
-10从网络解析的 TE 授权信息为空。请联系腾讯云团队处理。
-11把 TE 授权信息写到本地文件时失败，可能是 IO 失败引起。
-12下载失败，解析本地 asset 也失败。
-13鉴权失败，请检查so是否在包里，或者已正确设置 so 路径。
3004/3005无效授权。请联系腾讯云团队处理。
3015Bundle Id / Package Name 不匹配。检查您的 App 使用的 Bundle Id / Package Name 和申请的是否一致，检查是否使用了正确的授权文件。
3018授权文件已过期，需要向腾讯云申请续期。
其他请联系腾讯云团队处理。
- - -## 日志管理 - -腾讯礼物动画特效 SDK 默认支持保存运行日志，如果测试过程中出现问题，可以提取日志反馈给腾讯云客服，您可以根据业务需要把此目录的日志上传到业务后台，用于定位线上用户问题。 - -1. Android 端的日志保存在目录：`/sdcard/Android/data/${your_packagename}/files/TCMediaLog`，日志文件按照日期命名，把 TCMediaLog 文件夹导出即可： - -![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100034408908/1a1e4d0e095511f0990f52540099c741.png) - -2. iOS 端保存在沙箱 Documents/TCMedialog 文件夹，日志文件按照日期命名。详细日志导出教程 [参考这里](https://cloud.tencent.com/document/product/616/116481#59b6468e-c7a0-48da-9b96-94c85e49e48c) - -> **注意：** -> - -> **没有日志文件？** -> - -> 请检查是否通过 FTCMediaXBase.instance.setLogEnable 传入 false 关闭了日志，默认文件日志是开启的。 -> - - -## 播放器使用 - -### 引入 FTCEffectAnimView -``` dart -Widget _getFTCEffectAnimView() { - return FTCEffectAnimView( - controllerCallback: (controller){ - // controller.setLoop(true); - // controller.startPlay("xxxxxxx"); - } - ); -} -``` - -### 播放监听 - -可以在开始播放之前通过调用`setPlayListener`方法来设置动画播放状态监听： -``` dart -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 -})); -``` -1. 如果您需要获取当前正在播放的动画信息，可以在`onPlayStart()`方法中(或者该方法执行之后)调用`getTCAnimInfo()`方法来获取到`FTCEffectAnimInfo`对象实例，进而获取到当前播放动画的类型、时长、宽高、融合动画等信息。 - - - -### 播放配置 -``` dart -// 设置播放配置，非必需的步骤 -final FTCEffectConfig _curConfig = FTCEffectConfig()..codecType = FCodecType.TC_MPLAYER; -controller?.setConfig(_curConfig); -``` - -FTCEffectConfig 中目前支持： -1. FCodecType codecType ：它有三个取值，分别是： -- FCodecType.TC_MPLAYER (MPLAYER 播放引擎) -- FCodecType.TC_MCODEC(MCODEC 播放引擎) -- FCodecType.TX_LITEAV_SDK (腾讯云播放器 SDK) - -> 注意： -> 1. 目前仅支持在播放器开始前调用 setConfig() 方法来设置播放配置，开始播放后不支持修改配置。 -> 2. 目前如上设置仅对 MP4 动画生效。 -> 3. 如果设置为 FCodecType.TX_LITEAV_SDK ，则还需要单独引入腾讯云播放器 SDK，以及申请、注册好其对应的 License。 -> 4. 如果不设置 config，则会默认使用 CodecType = FCodecType.TC_MPLAYER。 - -2. FFreezeFrame freezeFrame：用于设置播放动画冻结帧，详细解释见 API 文档。 - -3. FAnimType animType：用于指定后续要播放的动画格式，适用于某些情况下，要播放的动画文件后缀被修改的场景。可取值如下： - -> - FAnimType.AUTO（SDK 默认策略，即以动画文件的后缀来判断动画格式，例如 tcmp4/mp4/tep/tepg 等格式）。 -> - FAnimType.MP4（MP4 动画格式，后续都将动画文件当做 MP4 类型来播放，无视文件后缀名） -> - FAnimType.TCMP4（TCMP4 动画格式，后续都将动画文件当做 TCMP4 类型来播放，无视文件后缀名）。 - - -### 融合动画配置 - -实现 mp4 或者 tcmp4 融合动画的播放，需要实现 FResourceFetcher。 -1. 如果是图片类型的融合动画，需要实现 FResImgResultFetcher ，来返回对应图片的 Uint8List 来替换对应的元素； - -2. 如果是文字类型的融合动画，需要实现 FResTextResultFetcher ，来返回对应的 FTCEffectText 对象实例，来指定文字的显示配置信息。 - - ``` dart - 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 文件格式资源。 - -> **注意：** -> -> 1. 只支持播放本地视频资源，如果您使用的网络视频资源， 先下载到本地再播放。 -> 2. 动画资源可以通过 [特效转换工具](https://write.woa.com/document/172562058121748480) 来生成，除此之外也支持 VAP 格式动画资源播放。 - -``` dart -controller?.startPlay("xxxx") -``` - -#### 暂停播放 -``` dart -controller?.pause() -``` - -#### 继续播放 -``` dart -controller?.resume() -``` - -#### 循环播放 -``` dart -controller?.setLoop(true) -``` - -#### 静音播放 -``` dart -controller?.setMute(true) -``` - -#### 停止播放 - -当不需要继续使用播放器时，需要停止播放，释放占用的资源。 -``` dart -controller?.stopPlay() -``` - -## 常见问题 - -### 在播放过程中出现下面的日志信息，如何处理？ -``` plaintext -License checked failed! tceffect player license required! -``` - -请检查是否申请特效播放器 License，并进行了初始化注册。 - - -## 常见错误码 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
错误码描述
-10003创建线程失败。
-10004render 创建失败。
-10005配置解析失败。
-10006文件无法读取。
-10007动画视频编码格式是 H.265，在当前设备上不支持。
-10008参数非法。
-10009license 不合法。
-10010MediaPlayer 播放失败。
-10012缺少必备的依赖，比如播放类型为 TX_LITEAV_SDK 时没有引入 liteavSDK。
- - diff --git a/ios/Classes/messages/TCEffectMessages.h b/ios/Classes/messages/TCEffectMessages.h index 6565484..26ae004 100644 --- a/ios/Classes/messages/TCEffectMessages.h +++ b/ios/Classes/messages/TCEffectMessages.h @@ -129,6 +129,8 @@ extern void SetUpFTCMediaXBaseApiWithSuffix(id binaryMes - (void)setRateRate:(double)rate error:(FlutterError *_Nullable *_Nonnull)error; /// @return `nil` only when `error != nil`. - (nullable NSString *)getSdkVersionWithError:(FlutterError *_Nullable *_Nonnull)error; +/// @return `nil` only when `error != nil`. +- (nullable FTCEffectAnimInfoMsg *)preloadTCAnimInfoPlayUrl:(NSString *)playUrl config:(FTCEffectConfigMsg *)config error:(FlutterError *_Nullable *_Nonnull)error; @end extern void SetUpFTCEffectAnimViewApi(id binaryMessenger, NSObject *_Nullable api); diff --git a/ios/Classes/messages/TCEffectMessages.m b/ios/Classes/messages/TCEffectMessages.m index a62d5b8..e16375c 100644 --- a/ios/Classes/messages/TCEffectMessages.m +++ b/ios/Classes/messages/TCEffectMessages.m @@ -763,6 +763,26 @@ void SetUpFTCEffectAnimViewApiWithSuffix(id binaryMessen [channel setMessageHandler:nil]; } } + { + FlutterBasicMessageChannel *channel = + [[FlutterBasicMessageChannel alloc] + initWithName:[NSString stringWithFormat:@"%@%@", @"dev.flutter.pigeon.flutter_effect_player.FTCEffectAnimViewApi.preloadTCAnimInfo", messageChannelSuffix] + binaryMessenger:binaryMessenger + codec:nullGetTCEffectMessagesCodec()]; + if (api) { + NSCAssert([api respondsToSelector:@selector(preloadTCAnimInfoPlayUrl:config:error:)], @"FTCEffectAnimViewApi api (%@) doesn't respond to @selector(preloadTCAnimInfoPlayUrl:config:error:)", api); + [channel setMessageHandler:^(id _Nullable message, FlutterReply callback) { + NSArray *args = message; + NSString *arg_playUrl = GetNullableObjectAtIndex(args, 0); + FTCEffectConfigMsg *arg_config = GetNullableObjectAtIndex(args, 1); + FlutterError *error; + FTCEffectAnimInfoMsg *output = [api preloadTCAnimInfoPlayUrl:arg_playUrl config:arg_config error:&error]; + callback(wrapResult(output, error)); + }]; + } else { + [channel setMessageHandler:nil]; + } + } } @interface FTCMediaXBaseFlutterEvent () @property(nonatomic, strong) NSObject *binaryMessenger; diff --git a/ios/Classes/ui/view/FTCEffectAnimController.m b/ios/Classes/ui/view/FTCEffectAnimController.m index 7add6ef..3e75993 100644 --- a/ios/Classes/ui/view/FTCEffectAnimController.m +++ b/ios/Classes/ui/view/FTCEffectAnimController.m @@ -114,6 +114,10 @@ - (nullable NSString *)getSdkVersionWithError:(FlutterError * _Nullable __autore return [TCEffectAnimView getSdkVersion]; } +- (FTCEffectAnimInfoMsg *)preloadTCAnimInfoPlayUrl:(NSString *)playUrl config:(FTCEffectConfigMsg *)config error:(FlutterError * _Nullable __autoreleasing *)error{ + return [FEffectViewHelper transAnimInfoToMsg:[TCEffectAnimView preloadTCAnimInfo:playUrl config:[FEffectViewHelper transConfigFromMsg:config]]];; +} + #pragma mark - TCEPAnimViewDelegate - (void)onPlayEvent:(ITCEffectPlayer *)player diff --git a/lib/message/tceffect_messages.dart b/lib/message/tceffect_messages.dart index 1bcf92e..f7384f6 100644 --- a/lib/message/tceffect_messages.dart +++ b/lib/message/tceffect_messages.dart @@ -833,6 +833,33 @@ class FTCEffectAnimViewApi { return (pigeonVar_replyList[0] as String?)!; } } + + Future preloadTCAnimInfo(String playUrl, FTCEffectConfigMsg config) async { + final String pigeonVar_channelName = 'dev.flutter.pigeon.flutter_effect_player.FTCEffectAnimViewApi.preloadTCAnimInfo$pigeonVar_messageChannelSuffix'; + final BasicMessageChannel pigeonVar_channel = BasicMessageChannel( + pigeonVar_channelName, + pigeonChannelCodec, + binaryMessenger: pigeonVar_binaryMessenger, + ); + final List? pigeonVar_replyList = + await pigeonVar_channel.send([playUrl, config]) as List?; + if (pigeonVar_replyList == null) { + throw _createConnectionError(pigeonVar_channelName); + } else if (pigeonVar_replyList.length > 1) { + throw PlatformException( + code: pigeonVar_replyList[0]! as String, + message: pigeonVar_replyList[1] as String?, + details: pigeonVar_replyList[2], + ); + } else if (pigeonVar_replyList[0] == null) { + throw PlatformException( + code: 'null-error', + message: 'Host platform returned null value for non-null return value.', + ); + } else { + return (pigeonVar_replyList[0] as FTCEffectAnimInfoMsg?)!; + } + } } abstract class FTCMediaXBaseFlutterEvent { diff --git a/lib/player/ftceffect_view_controller.dart b/lib/player/ftceffect_view_controller.dart index 145c74f..ce3a311 100644 --- a/lib/player/ftceffect_view_controller.dart +++ b/lib/player/ftceffect_view_controller.dart @@ -105,6 +105,12 @@ class FTCEffectViewController implements FTCEffectAnimViewFlutterEvent { return await _effectViewApi.getSdkVersion(); } + Future preloadTCAnimInfo(String playUrl, FTCEffectConfig config) async { + FTCEffectAnimInfoMsg msg = await _effectViewApi.preloadTCAnimInfo(playUrl, config.toMsg()); + return FTCEffectAnimInfo.copyFromMsg(msg); + } + + // Future onDestroy() async { // await _effectViewApi.onDestroy(); // } diff --git a/pigeons/tceffect_messages.dart b/pigeons/tceffect_messages.dart index 0a1be63..10ab001 100644 --- a/pigeons/tceffect_messages.dart +++ b/pigeons/tceffect_messages.dart @@ -128,6 +128,8 @@ abstract class FTCEffectAnimViewApi { void setRate(double rate); String getSdkVersion(); + + FTCEffectAnimInfoMsg preloadTCAnimInfo(String playUrl, FTCEffectConfigMsg config); } @FlutterApi()