tencent cloud

文档反馈

最后更新时间:2024-08-30 17:36:51
    腾讯特效 SDK Flutter版本核心接口类 TencentEffectApi,更新美颜数值、调用动效等功能。

    Public 成员函数

    API
    描述
    设置美颜资源的本地存储路径(V0.3.5.0版本新增)
    初始化美颜数据,使用美颜前必须先调用此方法(在V0.3.1.1版本及之前)
    进行美颜授权
    设置 SDK 的 log 等级,建议开发调试时设为 Log.DEBUG,正式发布时设置为 Log.WARN,如果正式发布设置为 Log.DEBUG,大量的日志会影响性能
    onResume
    恢复渲染,页面可见时调用
    onPause
    暂停渲染,页面不可见时调用
    开启美颜增强模式,具体请参考增强模式使用指南
    调用此方法开启高性能模式。高性能模式开启后,美颜占用的系统 CPU/GPU 资源更少,可减少手机的发热和卡顿现象,更适合低端机长时间使用。注意:需要在调用其他方法之前调用
    设置静音(因为有些贴纸中有声音)
    开启或关闭某个特性
    @Deprecated
    更新美颜属性, 可在任意线程调用(此接口已废弃)
    setEffect
    更新美颜属性(V0.3.5.0版本新增)
    设置创建美颜对象时的回调接口(如果出错会回调此接口)
    设置动效提示语回调函数,用于将提示语展示到前端页面上
    设置人脸点位信息等数据回调,需要获得人脸点位的 Licence 授权(例如原子能力X102)才会有回调。
    设置人脸、手势、身体检测状态回调
    @Deprecated
    判断当前的 lic 授权支持哪些美颜。 仅支持 BEAUTY 和 BODY_BEAUTY 类型的美颜项检测。检测后的结果会赋值到各个美颜对象 XmagicProperty.isAuth 字段中(此接口已废弃)
    判断当前机型是否支持美颜(OpenGL3.0)
    返回当前设备支持的原子能力表
    @Deprecated
    将动效资源列表传入 SDK 中做检测,执行后 XmagicProperty.isSupport 字段标识该原子能力是否可用。 根据 XmagicProperty.isSupport 可 UI 层控制单击限制,或者直接从资源列表删除(此接口已废弃)
    检测当前设备是否支持此素材
    @Deprecated
    传入一个动效资源列表,返回每一个资源所使用到的 SDK 原子能力列表(此接口已废弃)

    成员函数说明

    setResourcePath (V0.3.5.0版本新增)

    设置美颜资源存放的本地路径
    ///设置美颜资源存放的本地路径,使用美颜前必须先调用此方法。 ///v0.3.5.0新增 void setResourcePath(String xmagicResDir);

    参数

    参数
    含义
    String xmagicResDir
    资源文件放置的目录

    initXmagic

    初始化美颜数据。在V0.3.1.1版本及之前,使用美颜前必须先调用此方法。在V0.3.5.0版本,此方法每个版本只需要调用一次,并且在调用了此方法之前必须先调用setResourcePath方法设置了资源路径,在V0.3.5.0版本中删除了之前的 xmagicResDir 参数,可参考最新 demo。
    V0.3.5.0版本
    void initXmagic(InitXmagicCallBack callBack);
    
    typedef InitXmagicCallBack = void Function(bool reslut);
    V0.3.1.1版本及之前
    void initXmagic(String xmagicResDir,InitXmagicCallBack callBack);
    
    typedef InitXmagicCallBack = void Function(bool reslut);

    参数

    参数
    含义
    String xmagicResDir
    资源文件放置的目录
    InitXmagicCallBack callBack
    初始化回调接口

    setLicense

    设置鉴权数据,进行美颜授权。
    ///美颜进行鉴权处理
    void setLicense(String licenseKey, String licenseUrl, LicenseCheckListener checkListener);
    ///授权校验的结果回调方法
    typedef LicenseCheckListener = void Function(int errorCode, String msg);

    参数

    参数
    含义
    String licenseKey
    鉴权的 LicenseKey
    String licenseUrl
    鉴权的 LicenseUrl
    LicenseCheckListener checkListener
    授权结果回调接口

    setXmagicLogLevel

    设置 SDK 的 log 等级
    void setXmagicLogLevel(int logLevel);

    参数

    参数
    含义
    int logLevel
    可使用 LogLevel 定义好的类型进行设置

    onResume

    恢复美颜处理
    void onResume();

    onPause

    暂停美颜处理
    void onPause();

    enableEnhancedMode

    开启增强模式,具体请参考增强模式使用指南
    void enableEnhancedMode();

    setDowngradePerformance(V0.3.1.1新增)

    开启性能模式
    void setDowngradePerformance();

    setAudioMute(V0.3.1.1新增)

    设置是否静音。参数:true 表示静音,false 表示非静音。
    ///背景音乐是否静音 void setAudioMute(bool isMute);

    setFeatureEnableDisable(V0.3.1.1新增)

    开启或关闭某个能力
    /// 开启或关闭某个特性 void setFeatureEnableDisable(String featureName, bool enable);

    参数

    参数
    含义
    String featureName
    原子能力名称
    取值如下:
    "ai.3dmmV2.enable" 人脸表情能力
    "ai.body3dpoint.enable" 身体点位能力
    "ai.hand.enable" 手势检测能力
    "beauty.onlyWhitenSkin" 美白仅对皮肤生效
    "ai.segmentation.skin.enable" 皮肤分割能力
    "auto_beauty_switch" 智能美颜(为男性、宝宝减淡美颜美妆效果)
    boolean enable
    true 表示开启此能力,false 表示关闭此能力
    注:如果是降级模式,则不允许开启皮肤分割

    updateProperty(此接口已废弃)

    设置某一项美颜数值或者动效、滤镜,可在任意线程调用。
    void updateProperty(XmagicProperty xmagicProperty);

    参数

    参数
    含义
    XmagicProperty xmagicProperty
    美颜属性封装对象

    setEffect(V0.3.5.0新增)

    设置美颜、美型、滤镜、美妆、贴纸、分割等效果,可在任意线程调用。具体参数请参考 美颜参数说明
    ///更新美颜属性。 void setEffect(String effectName,int effectValue,String? resourcePath,Map<String,String>? extraInfo);

    setOnCreateXmagicApiErrorListener

    设置美颜对象创建时的错误回调接口
    void setOnCreateXmagicApiErrorListener(OnCreateXmagicApiErrorListener? errorListener);
    ///创建美颜实例时的错误回调方法
    typedef OnCreateXmagicApiErrorListener = void Function(String errorMsg, int code);

    参数

    参数
    含义
    OnCreateXmagicApiErrorListener? errorListener
    创建美颜对象时错误信息回调接口
    返回错误码含义对照表:
    错误码
    含义
    -1
    未知错误
    -100
    3D 引擎资源初始化失败
    -200
    不支持 GAN 素材
    -300
    设备不支持此素材组件
    -400
    模板 JSON 内容为空
    -500
    SDK 版本过低
    -600
    不支持分割
    -700
    不支持 OpenGL
    -800
    不支持脚本
    5000
    分割背景图片分辨率超过 2160×3840
    5001
    分割背景图片所需内存不足
    5002
    分割背景视频解析失败。
    5003
    分割背景视频超过200秒
    5004
    分割背景视频格式不支持

    setTipsListener

    设置动效提示语回调函数,用于将提示语展示到前端页面上。比如某些素材会提示用户点点头、伸出手掌、比心等。
    void setTipsListener(XmagicTipsListener? xmagicTipsListener);
    
    abstract class XmagicTipsListener {
    /// 显示tips。Show the tip.
    /// @param tips tips字符串。Tip's content
    /// @param tipsIcon tips的icon。Tip's icon
    /// @param type tips类别,0表示字符串和icon都展示,1表示是pag素材只展示icon。tips category, 0 means that both strings and icons are displayed, 1 means that only the icon is displayed for the pag material
    /// @param duration tips显示时长, 毫秒。Tips display duration, milliseconds
    void tipsNeedShow(String tips, String tipsIcon, int type, int duration);
    
    /// *
    /// 隐藏tips。Hide the tip.
    /// @param tips tips字符串。Tip's content
    /// @param tipsIcon tips的icon。Tip's icon
    /// @param type tips类别,0表示字符串和icon都展示,1表示是pag素材只展示icon。tips category, 0 means that both strings and icons are displayed, 1 means that only the icon is displayed for the pag material
    void tipsNeedHide(String tips, String tipsIcon, int type);
    }

    参数

    参数
    含义
    XmagicTipsListener xmagicTipsListener
    回调函数实现类

    setYTDataListener

    设置人脸点位信息等数据回调。
    ///设置人脸点位信息等数据回调(S1-05 和 S1-06 套餐才会有回调)
    void setYTDataListener(XmagicYTDataListener? xmagicYTDataListener);
    设置人脸信息等数据回调
    
    abstract class XmagicYTDataListener {
    //优图AI数据回调。
    void onYTDataUpdate(String data);
    }
    onYTDataUpdate 返回 JSON string 结构,最多返回5个人脸信息:
    {
    "face_info":[{
    "trace_id":5,
    "face_256_point":[
    180.0,
    112.2,
    ...
    ],
    "face_256_visible":[
    0.85,
    ...
    ],
    "out_of_screen":true,
    "left_eye_high_vis_ratio:1.0,
    "right_eye_high_vis_ratio":1.0,
    "left_eyebrow_high_vis_ratio":1.0,
    "right_eyebrow_high_vis_ratio":1.0,
    "mouth_high_vis_ratio":1.0
    },
    ...
    ]
    }

    字段含义

    字段
    类型
    值域
    说明
    trace_id
    int
    [1,INF)
    人脸 ID,连续取流过程中,ID 相同的可以认为是同一张人脸
    face_256_point
    float
    [0,screenWidth] 或 [0,screenHeight]
    共512个数,人脸256个关键点,屏幕左上角为(0,0)
    face_256_visible
    float
    [0,1]
    人脸256关键点可见度
    out_of_screen
    bool
    true/false
    人脸是否出框
    left_eye_high_vis_ratio
    float
    [0,1]
    左眼高可见度点位占比
    right_eye_high_vis_ratio
    float
    [0,1]
    右眼高可见度点位占比
    left_eyebrow_high_vis_ratio
    float
    [0,1]
    左眉高可见度点位占比
    right_eyebrow_high_vis_ratio
    float
    [0,1]
    右眉高可见度点位占比
    mouth_high_vis_ratio
    float
    [0,1]
    嘴高可见度点位占比

    参数

    参数
    含义
    XmagicYTDataListener xmagicYTDataListener
    回调函数实现类

    setAIDataListener

    检测到人脸、身体、手势时,会回调这些部位的点位信息。
    void setAIDataListener(XmagicAIDataListener? aiDataListener);
    
    abstract class XmagicAIDataListener {
    void onFaceDataUpdated(String faceDataList);
    
    void onHandDataUpdated(String handDataList);
    
    void onBodyDataUpdated(String bodyDataList);
    }

    isBeautyAuthorized(此接口已废弃)

    判断当前的 License 授权支持哪些美颜或美体项。 仅支持 BEAUTY 和 BODY_BEAUTY 类型的美颜项检测。检测后的结果会赋值到各个美颜对象 XmagicProperty.isAuth 字段中。如果 isAuth 字段为 false,可以在 UI 上屏蔽这些项的入口。
    Future<List<XmagicProperty>> isBeautyAuthorized(
    List<XmagicProperty> properties);

    参数

    参数
    含义
    List<XmagicProperty> properties
    需要检测的美颜项

    isSupportBeauty

    判断当前机型是否支持美颜(OpenGL3.0)。
    Future&lt;bool> isSupportBeauty();

    返回

    返回值 bool:是否支持支持美颜。

    getDeviceAbilities

    返回当前设备支持的原子能力表。与 getPropertyRequiredAbilities 方法搭配使用.
    Future<Map<String, bool>> getDeviceAbilities();

    返回

    返回值 Map&lt;String,bool>
    key:原子能力名(与素材能力名字对应)。
    value:当前设备是否支持。

    isDeviceSupport

    将动效资源列表传入 SDK 中做检测,执行后 XmagicProperty.isSupport 字段标识该素材是否可用。根据XmagicProperty.isSupport 可 UI 层控制单击限制,或者直接从资源列表删除。
    Future&lt;List<XmagicProperty>> isDeviceSupport(List<XmagicProperty> assetsList);

    参数

    参数
    含义
    List<XmagicProperty> assetsList
    需要检测的动效素材列表

    isDeviceSupportMotion (V0.3.5.0版本新增)

    检测当前设备是否支持此素材
    Future<bool> isDeviceSupportMotion(String motionResPath);

    参数

    参数
    含义
    motionResPath
    需要检测的动效素材的本地文件地址

    getPropertyRequiredAbilities

    传入一个动效资源列表,返回每一个资源所使用到的 SDK 原子能力列表。 方法的使用场景为: 您购买或制作了若干款动效素材,调用这个方法,会返回每一个素材需要使用的原子能力列表。例如素材1需要使用能力 A、B、C,素材2需要使用能力 B、C、D,然后您把这样的能力列表保持在服务器上。之后,当用户要从服务器下载动效素材时,用户先通过 getDeviceAbilities 方法获取他手机具备的原子能力列表(比如这台手机具备能力 A、B、C,但不具备能力 D),把他的能力列表传给服务器,服务器判断该设备不具备能力 D,因此不给该用户下发素材2。
    Future<Map<XmagicProperty, List<String>?>> getPropertyRequiredAbilities(
    List<XmagicProperty> assetsList);

    参数

    参数
    含义
    List<XmagicProperty> assetsList
    需要检测原子能力的动效资源列表

    返回

    返回值 Map<XmagicProperty, List<String>?> :
    key:动效资源素材实体类。
    value:所使用到的原子能力列表。
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持