logologo
售前咨询
人像美化
产品简介
开发指南
相关协议
常见问题
文档中心开发指南Android-Java接入文档

Android-Java接入文档


快手人像美化SDK Java API

1. SDK依赖

1.1 依赖库

  • MagicEngine-reuh0s1-x.x.x.x.aar 为特效引擎(人像美化)aar包。
  • licensing.0.0.10.aar 为鉴权aar
  • tflite-2.4.1-0.0.7-jni.aar 依赖库

1.2依赖资源

  • MagicEngine.bundle 人像美化SDK内置素材,细条特效需要用到,实例化sdk时设到EngineConfig assetDir

2. 工程配置

将以上*.aar放到工程libs目录下或者自行决定目录并确保aar会被引进即可。

3. 数据结构与枚举


/**
 * 业务类型
 */
public enum BusinessType {
    Camera,                ///< 相机业务
    Video,                 ///< 视频业务
    Image                  ///< 图片业务
}

/**
 * 引擎配置
 */
public static class EngineConfig {
    public int width;                   ///< 渲染尺寸
    public int height;                  ///< 渲染尺寸
    public String assetDir;             ///< 内置资源跟目录
    public BusinessType businessType;   ///< 业务类型
}

/**
 * 色域类型
 */
public enum ColorSpace {
    BT601VideoRange,
    BT601FullRange,
    BT709VideoRange,
    BT709FullRange,
    BT2020VideoRange,
    BT2020FullRange
}

/**
 * 数据类型
 */
public enum YUVDataFormat {
    NV21,
    NV12,
    I420
}

/**
 * 相机位置
 */
public enum CameraPosition {
    Unknown,        ///< 未定义的相机位置
    Front,          ///< 前置
    Back            ///< 后置
}

/**
 * 原始YUV帧数据
 */
public static class FrameData {
    public ByteBuffer data;                 ///< YUV像素数据
    public int stride;                      ///< data的Y平面一行字节数
    public YUVDataFormat format;            ///< 像素数据格式
    public CameraPosition position;         ///< 相机位置(前置,后置)
    public ColorSpace colorSpace;           ///< 色域
    public int width;                       ///< 宽度
    public int height;                      ///< 高度
    public int rotation;                    ///< 顺时针旋转这个角度后为正图,取值:0, 90, 180, 270
    public float fov;                       ///< 相机视野角度
    public boolean mirror;                  ///< 镜像
}

/**
 * 特效类型
 */
public enum EffectType {
    Beautify,               ///< 美颜
    Makeup,                 ///< 美妆
    Deform,                 ///< 美型
    Lookup,                 ///< 滤镜
    BodySlimming            ///< 美体
}

/**
 * 滤镜Lut类型
 */
public enum LookupTableType {
    NxN,        ///< 方形NxN的Lut
    Nx1         ///< 横向Nx1的Lut
}

/**
 * 滤镜配置
 */
public static class LookupInfo {
    public String path;                ///< Lut图路径
    public int dimension;              ///< 维数
    public float intensity;            ///< 强度
    public LookupTableType lutType;    ///< Lut类型
}

/**
 * 美妆配置
 */
public static class MakeupInfo {
    public String key;         ///< 资源key, 用于替换
    public String resourceDir; ///< 资源路径
    public float intensity;    ///< 强度
}

/**
 * 美颜调节类型
 */
public enum BeautyType {
    Bright,         ///< 美白
    Soften,         ///< 磨皮
    WrinkleRemove,  ///< 去法令纹
    EyeBagRemove,   ///< 去黑眼圈
    Teeth,          ///< 白牙
    EyeBrighten,    ///< 亮眼
    FaceShadow,     ///< 立体
    Clarity,        ///< 清晰
    EvenSkin,       ///< 匀肤
}

/**
 * 美体调节
 */
public enum BodySlimmingType {
    Head,       ///< 头部
    Neck,       ///< 脖子
    Waist,      ///< 腰部
    Hip,        ///< 臀部
    Leg,        ///< 腿部
    Shoulder,   ///< 肩膀
    Breast      ///< 胸部
}

/**
 * 传感器配置类型
 */
public enum SensorConfigType {
    Reset,
    Remove
}

/**
 * 传感器配置
 */
public static class SensorConfig {
    public float updateInterval;
    public SensorConfigType configType;
}

/**
 * 传感器数据
 */
public static class SensorData {
    public long timestamp = 0;
    public float rotation = 0;
}
    

4. API说明

4.1 鉴权API说明:

人像美化SDK的使用依赖StreamlakeLicensing,请务必先初始化Licensing SDK,否则人像美化会调用失败,不生效

  • Step1. 初始化StreamlakeOpenAPI
    Hint: ⚠️ 请确保OpenAPI的初始化在LicensingSDK之前!!!
private void initSloManager() {
    SloManager.get().init(new InitParams() {
      @Override
      public String getHost() {
        return "https://vod.streamlakeapi.com";
      }

      @Override
      public String getAccessKey() { 
        return "xxx"; // 对应申请好的AK
      }

      @Override
      public String getSecretKey() {
        return "secretKey"; //此字段为缺省字段, 目前可传任意字段
      }

      @Override
      public String getVersion() {
        return "2022-02-10"; //一般为Build日期
      }
    });
  }

  • Step2 初始化StreamlakeLicensing
    Hint: ⚠️publicKey为streamlake颁发的公钥,用于licensing校验,ProdCode传入"y-tech"
private void initSll() {
    mSLLicensingManager = new SLLicensingManager(this, publicKey, prodCode,
        new LicensingInitListener() {
          @Override
          public void onSuccess() {
            Log.i(TAG, "init success");
          }

          @Override
          public void onFailure(Throwable throwable) {
            Log.i(TAG, "init failed" + throwable.getMessage());
          }
        });
  }

4.2 渲染API说明:

人像美化SDK需要引以下的包:

import com.kwai.magicengine.MagicEngine;
import com.kwai.magicengine.MagicEngineCommon;
import com.kwai.magicengine.MagicEngineDefines;
import com.kwai.magicengine.MagicEngineSync;

人像美化 API中的参数和返回值类型以及每个属性的含义请看上面的**3.数据结构与枚举**
人像美化SDK主要包含滤镜,美妆,美颜,美型,美体。需要单独开启和关闭并设定参数

4.2.1 引擎实例化

import com.kwai.magicengine.MagicEngine;

/**
 * 实例化人像美化SDK
 * @param context Context实例
 * @param config 引擎配置
 * @return 引擎实例
 */
@Nullable
public static MagicEngineSync createSyncMagicEngine(@NonNull Context context, @NonNull MagicEngineDefines.EngineConfig config);

4.2.2 数据处理接口

import com.kwai.magicengine.MagicEngineSync;

/**
 * 同步渲染接口,结果写入返回值FrameData中,不要求在GL上下文中调用
 * @param frameData 属于处理的裸数据
 * @return 处理后的裸数据
 */
MagicEngineDefines.FrameData processWithFrameData(MagicEngineDefines.FrameData frameData);

4.2.4 通用调节接口

下面这些接口主要是用来设定及调节美颜,美型,美妆,美体,滤镜等。

/**
* @brief 设置引擎回调接口
* @param listener:回调接口
*/
void setEngineListener(MagicEngine.MagicEngineListener listener);

/**
* @brief 设定模型路径
* @param pathMap: 模型key和path的map
* */
void setModelPathMap(HashMap<String, String> pathMap);

/**
* @brief 开启/关闭 单个特效
* @param effectType 需要开启的特效类型
* @param enable 开启或者关闭状态
*/
void setEffectEnabled(MagicEngineDefines.EffectType effectType, boolean enabled);

/**
* @brief 设定滤镜资源
* @param info 需要设定的拍前滤镜信息
*/
void setLookupInfo(MagicEngineDefines.LookupInfo info);

/**
* @brief 设定滤镜强度
* @param intensity 滤镜强度
*/
void setLookupIntensity(float intensity);

/**
* @brief 设定美妆资源
* @param makeupInfo  需要设定的美妆信息,每个部分都是一个MakeupInfo结构
*/
void setMakeupInfo(ArrayList<MagicEngineDefines.MakeupInfo> makeupInfo);

/**
* @brief 设定美妆强度
* @param key 需要调整的美妆key(设定美妆时用户自定义)
* @param intensity 强度
*/
void setMakeupIntensity(String key, float intensity);

/**
* @brief 设定美颜强度
* @param type 需要调节的美颜类型
* @param intensity 强度
*/
void setBeautyIntensity(MagicEngineDefines.BeautyType beautyType, float intensity);

/**
* @brief 设定美型强度
* @param mode 美型类型
* @param intensity  强度
*/
void setDeformIntensity(int mode, float intensity);

/**
* @brief 设定美体强度
* @param type  需要调整的美体类型
* @param intensity  强度
*/
void setBodySlimmingIntensity(MagicEngineDefines.BodySlimmingType type, float intensity);

/**
* 更新传感器数据
* @param sensorData 传感器数据
*/
void setSensorData(MagicEngineDefines.SensorData sensorData);

/**
* 清理内部正在处理的数据帧队列
*/
void clearFrameQueue();

/**
* @brief 销毁引擎. 调用之后此实例不可再使用. 此方法主要用于保障 MagicEngine 在合适的时机合适的线程释放资源.
*/
void destroy();

4.3模型配置

美颜美型等都需要一些AI模型的支持。模型的路径通过上面所说的setModelPathDic 方法设定。模型资源都放在了resource目录中的model.7z中,解压之后就能看到。其中模型的key为文件夹名字,path设此文件夹的路径。例如:key为magic_ycnn_model_landmark的路径设为/path/to/magic_ycnn_model_landmark

当前所有的模型为:

magic_mmu_model_animoji1 	
magic_mmu_model_basewhite
magic_ycnn_model_cloth_seg
magic_ycnn_model_face_attributes
magic_ycnn_model_face_seg
magic_ycnn_model_finger
magic_ycnn_model_general_handpose
magic_ycnn_model_gesture
magic_ycnn_model_hair
magic_ycnn_model_head_seg
magic_ycnn_model_humanpose
magic_ycnn_model_landmark
magic_ycnn_model_matting
magic_ycnn_model_skin_seg
  • 美颜模块所需模型:
magic_ycnn_model_landmark
  • 美妆模块所需模型:
magic_ycnn_model_landmark
magic_ycnn_model_face_attributes
magic_ycnn_model_face_seg
  • 美型模块所需模型:
magic_ycnn_model_landmark
  • 美体模块所需模型:
magic_ycnn_model_landmark
magic_ycnn_model_humanpose
  • 滤镜模块所需模型:
不需要AI模型

通过setModelPathDic可以多次设定或刚开始把模型key和对应的路径先设定,应用对应功能之前确保再该路径中下载好或者放好对应模型。原则上需要模型的功能在被调用之前把对应的key和path通过这个dictionary设进去即可。

例如:刚开始只调用美颜和美型可以设定magic_ycnn_model_landmark ,magic_ycnn_model_face_attributes ,后面调节美体可以在之前的基础上添加magic_ycnn_model_humanpose三个一起设进去。可以一直累加,外部维护一个dictionary,或者全部一起设定,之后在确保模型存于早先设定的路径。

5. 调用流程

请注意,标注 [GL]的步骤必须在有效GLContext下执行,否则会出错。标注[CPT]的API需要在采集线程执行

1.调用鉴权API进行授权
2.调用 createSyncMagicEngine 创建人像美化
3.调用 processWithFrameData 进行数据处理
5.调用 destroy 方法销毁引擎

上一篇:应用场景下一篇:iOS-ObjC接入文档
该篇文档内容是否对您有帮助?
有帮助没帮助