Stickers

  • As many as 300 different kinds of stickers to choose from
  • Optimized real-time tracking on mobiles. A smooth performance even on low-end Android phones

Beautifications, Filters

  • Beautifications include whole frame effect and local facial area effect. Features of beautifications include skin whitening, blemish removal, skin tone saturation, chin slimming, and eye magnifying.
  • Users can set their preferred parameters for each of the features. 3 default beautification settings are also available for easy usage.
  • As many as 50 different filters of various styles are provided.

Anime

  • Real-time facial expressions mapped to anime characters, include head rotating, eye opening/closing, mouth movement etc.
  • Customized designs for anime characters are also available

Background substitution

  • Cut out human figure from the background and change background in real time
  • Support multiple persons under the same camera

AR Stickers Studio

  • Through an easy-to-use UI, designers can create their own live stickers
  • Automatically integrates with face tracking once the design is complete
  • Stickers Studio >

Magic Mirrors, Face Swap

  • Magic Mirrors: more than a dozen magic mirrors are available
  • Face Swap: real time face swap between two persons

KiwiFace SDK

iOS Demo

Register and Download

KiwiFace SDK

Android Demo

Register and Download

KiwiFace SDK

iOS Demo

Register and Download

KiwiFace SDK

Android Demo

Register and Download
ios-instruction.md

Kiwi人脸跟踪SDK快速集成指南(iOS)

kiwi人脸跟踪SDK,主要功能包括:

  • 静态图片的人脸以及关键点位置检测
  • 68个人脸关键点的实时检测与跟踪(单人脸/多人脸)
  • 美颜、哈哈镜等实时滤镜功能
  • 趣味2D贴纸

我们的SDK针对移动端,在算法效率、硬件占用、性能精度等方面进行了相关优化,使其适用于移动端直播,美颜相机,滤镜相机,趣味贴纸,虚拟美妆等应用场景。

流程图

这个文档将演示如何利用我们的demo快速入门,并详细描述具体集成步骤。

Demo快速入门

该demo基于GPUImage的短视频录制,实现了在短视频录制的场景下实现人脸跟踪以及趣味贴纸。

准备环境

开发环境要求

软件

* XCode 6.0 或以上版本
* iOS 7.0 或以上版本

硬件

* 支持语音/视频的真机设备

编译代码示例

  1. 用XCode打开demo工程文件(KiwifaceRecordingDemo)。代码包含以下目录结构

  2. 添加license文件

    • 将从官网下载下来的授权文件(试用此SDK需要在Kiwi官方网站中注册,以获取绑定应用BundleID的License文件)放入KiwiFaceSDK/Resource/KWResource.bundle/models目录下

    • 请确认demo工程文件(KiwifaceRecordingDemo)的bundleID是否正确(网站注册时填写的bundleID)
  3. 选中项目,点击 "Build and Run" 按钮进行编译

    示例截图

| |

p.s. 该示例只支持在真机上实现功能,不支持模拟器。编译完成后,即可运行。

具体集成步骤

第一步:准备环境

软件

  • XCode 6.0 或以上版本
  • iOS 7.0 或以上版本

硬件

  • 支持语音/视频的真机设备

第二步:项目所需库

  • kiwi提供(请从sdk文件夹中获取)

    • libfaceTrackerSDK.a(人脸捕捉SDK)
    • libKwSDK.a(UI+视频帧渲染SDK)
  • 系统库 (xcode自带)

    • UIKit.framework
    • Foundation.framework
    • libz.tbd

第三步:导入工程

  1. 直接将KiwiFaceSDK文件夹拖入项目中即可,选择Create groups.(SDK中自带GPUimage.a,使用GPUImage短视频录制必须使用Demo中的GPUImage.a,其他则不需要)

  2. 导入opencv3.framework

    注意,从官网下载的包有可能被错误的命名为opencv2.framework。

第四步:贴纸配置

如果有需要,请配置贴纸。贴纸相关资源文件存放在stickers目录下,一套贴纸对应一个目录,每套贴纸包含一个config.json文件,其中配置了音效文件名及每个item参数等信息。其结构如下:

  |--[sticker_1] (贴纸1)
  |   |--config.json (贴纸配置文件)
  |   |--[audio](音频文件)
  |   |--[item_1](贴纸序列图文件夹1)
  |   |   |--[frame_1](贴纸序列图1)
  |   |   |--[frame_2](贴纸序列图2)
  |   |   |--...
  |   |   |--[frame_n](贴纸序列图n)
  |   |--[item_2](贴纸序列图文件夹2)
  |   |--...
  |   |--[item_n](贴纸序列图文件夹n)
  |--[sticker_2](贴纸2)
  |--...
  |--[sticker_n](贴纸n)
  |—stickers.json(总配置文件)

程序靠读取在StickerManager文件夹下的stickers.json显示相应的贴纸和图标。

注意,使用贴纸云,需要在Info.plist中加入App Transport Security Settings字段,并将Allow Arbitrary Loads设置为YES。 具体的json文件格式如下:

stickers.json

参数名称意义
name贴纸的名称(UI显示和贴纸的识别)
dir贴纸存放路径文件夹名称
category类别(贴纸类型的区分或分组)
thumb贴纸图标的文件名(与声音在同一文件夹下)
voicedtrue(有声音)false(没有声音播放)
downloaded是否已经下载。如果没有下载,程序则可以去下载到指定目录后更改该状态

config.json

参数名称意义
type贴纸显示的位置类型(脸部、全屏)
facePos贴纸在脸部的位置
scaleWidthOffset贴纸宽度缩放系数
scaleHeightOffset贴纸高度缩放系数
scaleXOffset贴纸在脸部水平方向偏移系数
scaleYOffset贴纸在脸部垂直方向偏移系数
alignPos边缘item参数
alignX边缘水平方向偏移系数
alignY边缘垂直方向系数
frameFolder贴纸资源目录(包括一组图片序列帧)
frameNum帧数(一组序列帧组成一个动画效果)
frameDuration每帧的间隔(秒)
frameWidth图片的宽
frameHeight图片的高
trigerType触发条件,默认0,始终显示

编写config.json文件可使用我司提供的贴纸配置网站进行调试生成。

第五步:滤镜配置

如果有需要,请配置滤镜。滤镜相关资源文件存放在filter目录下,一套滤镜对应一个目录,每套滤镜包含filter.png(滤镜lookUpTable)和thumb.png(滤镜icon)文件。其结构如下:

  |--[filter_1] (滤镜1)
  |   |--filter.png (滤镜lookUpTable)
  |   |--thumb.png(滤镜icon)
  |--[filter_2](滤镜2)
  |   |--thumb.png(滤镜icon)
  |--...
  |--[filter_n](滤镜n)
  |—filters.json(滤镜配置文件)

注意:资源文件里有filter.png(lookUpTable)图片的是单层滤镜。

程序靠读取在filter文件夹下的filters.json显示相应的贴纸和图标。

具体的filters.json文件格式如下:

参数名称意义
name滤镜的名称(UI显示和滤镜的识别)
dir滤镜存放路径文件夹名称

| category | 类别(滤镜类型的区分)

第六步:调用API

使用SDK内置UI

如果直接使用我们SDK内置的UI, 可以在页面的viewDidload里面初始化SDK。

 
使用sdk自带功能
  • 人脸关键点和贴纸:

    • 初始化人脸关键点和贴纸集合

       
      • 调用人脸关键点和贴纸集合
       

    //调用贴纸 [self.renderer addFilter: self.stickerRender];

  • 哈哈镜:

    • 初始化哈哈镜集合

       
    • 调用哈哈镜集合

     
    • 去除哈哈镜

       
  • 美颜:

    • 初始化美颜

       
    • 调用美颜

       
    • 去除美颜

       
  • 全局滤镜:

    • 调用滤镜
     
  • 去除具体功能:

     
自定义功能扩展
  • 增加特定滤镜,进行渲染:

    在 sdk入口类中,有一个类型为KWRenderer的渲染类,由他来控制滤镜的增加。

    [KWRenderManager.KWRenderer addFilter: GPUImageOutput<GPUImageInput, KWRenderProtocol> *];

    滤镜对象必须遵守GPUImageInput和KWRenderProtocol两个协议才能正常被人脸捕捉和渲染。

  • 删除特定滤镜,停止渲染:

    [KWRenderManager.KWRenderer removeFilter: GPUImageOutput<GPUImageInput, KWRenderProtocol> *];
  • 人脸捕捉之后,在渲染视频帧之前可以对每一帧图像做自定义处理的回调block:

    typedef void (^RenderAndGetFacePointsBlock)(unsigned char *pixels, int format, int width, int height,result_68_t *p_result, int rstNum, int orientation,int faceNum);
    //block属性
    @property (nonatomic, copy)RenderAndGetFacePointsBlock kwRenderBlock;

    block 回调用于在人脸捕捉之后,渲染之前,可以对视频帧进行自定已处理的接口。Block的3个参数可供处理和使用:

    • result :人脸坐标集合 (可能是多张人脸 是二维数组)
    • faceNum :捕捉到的人脸数量
    • pixelBuffer:单帧的像素流
释放内存

我们建议在离开页面的时候释放内存

 
android-dev-instruction.md

KiwiFace人脸跟踪SDK快速集成指南(Android)

kiwi人脸跟踪SDK,主要功能包括:

  • 静态图片的人脸以及关键点位置检测
  • 68个人脸关键点的实时检测与跟踪(单人脸/多人脸)
  • 美颜、哈哈镜等实时滤镜功能
  • 人脸Pose参数估计
  • 趣味2D贴纸

我们的SDK针对移动端,在算法效率、硬件占用、性能精度等方面进行了相关优化,使其适用于移动端直播,美颜相机,滤镜相机,趣味贴纸,虚拟美妆等应用场景。

流程图

directories

这个文档将演示如何利用我们的demo快速入门,并详细描述具体集成步骤。

Demo快速入门

准备环境

开发软件

* Android SDK API Level> = 15
* Android Studio 2.0 或以上版本

硬件

* 支持语音和视频功能的真机
* Android 4.1或以上设备

编译代码示例

  1. 在Android Studio里选择 Import project (Eclipse ADT, Gradle, etc.)

  2. 利用Android studio的导入功能导入以下项目

    agora_kiwi_sdk\android\sample\trackerAndroidDemo-master
  3. 代码包含以下目录结构

    directories

  4. 点击run,编译代码示例

    示例截图

| |

具体集成步骤

第一步:aar包获取

从给的sdk文件夹下获取kw-filter.aar与 kw-tracker.aar 两个aar包

第二步:准备环境

  • Android SDK API Level> = 15

  • Android studio 2.0或以上版本

    • 真机设备调试

第三步:引入sdk中的相关包

具体如下:

  1. 首先在项目中新建一个libs包,然后再将步骤一获取的aar包放入其中

  2. 在自己项目的build.gradle中引入aar包

     ```
     repositories {
       flatDir {
           dirs '../libs'
       }
     }
    
     dependencies {
       compile(name: 'kw-filter', ext: 'aar')
       compile(name: 'kw-tracker', ext: 'aar')
     }
      ```
  3. 将sdk文件夹中的assets文件复制到自己项目的相应文件夹下

  4. 将sdk文件夹中的jniLibs文件复制到自己项目的相应文件夹下

  5. 为保证sdk正常运行,程序部署时需在AndroidManisfest.xml文件中加入以下许可:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAG"/>
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS" />
  6. 将申请到的KiwiFace.lic文件放在ui模块中的assets目录下

第四步:贴纸配置

如果有需要,请配置贴纸。贴纸相关文件存放在stickers目录下,一套贴纸对应一个目录,每套贴纸包含一个config.json文件,其中配置了音效文件名及每个item参数等信息。其结构如下:

  |--[sticker_1] (贴纸1)
  |   |--config.json (贴纸配置文件)
  |   |--[audio](音频文件)
  |   |--[preview](贴纸预览图)
  |   |--[item_1](贴纸序列图文件夹1)
  |   |   |--[frame_1](贴纸序列图1)
  |   |   |--[frame_2](贴纸序列图2)
  |   |   |--...
  |   |   |--[frame_n](贴纸序列图n)
  |   |--[item_2](贴纸序列图文件夹2)
  |   |--...
  |   |--[item_n](贴纸序列图文件夹n)
  |--[sticker_2](贴纸2)
  |--...
  |--[sticker_n](贴纸n)
  |—StickerConfig.json(总配置文件)

程序靠读取在stickers文件夹下的StickerConfig.json显示相应的贴纸和图标。

具体的json文件格式如下:

StickerConfig.json

参数名称意义
name贴纸的名称(UI显示和贴纸的识别)
dir贴纸存放路径文件夹名称
category类别(贴纸类型的区分或分组)
thumb贴纸图标的文件名(与声音在同一文件夹下)
voicedtrue(有声音)false(没有声音播放)
downloaded是否已经下载。如果没有下载,程序则可以去下载到指定目录后更改该状态

config.json

参数名称意义
type贴纸显示的位置类型(脸部、全屏)
facePos贴纸在脸部的位置
scaleWidthOffset贴纸宽度缩放系数
scaleHeightOffset贴纸高度缩放系数
scaleXOffset贴纸在脸部水平方向偏移系数
scaleYOffset贴纸在脸部垂直方向偏移系数
alignPos边缘item参数
alignX边缘水平方向偏移系数
alignY边缘垂直方向系数
frameFolder贴纸资源目录(包括一组图片序列帧)
frameNum帧数(一组序列帧组成一个动画效果)
frameDuration每帧的间隔(秒)
frameWidth图片的宽
frameHeight图片的高
trigerType触发条件,默认0,始终显示

编写config.json文件可使用我司提供的工具 https://apps.kiwiapp.mobi/sticker.html 进行调试生成。

第五步:调用API

根据API文档(具体功能请参照android-api文档),实现所需功能。 可以参照demo中KwTrackerWrapper类为例,来对贴纸,美颜,滤镜操作。

  1. 在Activity中进行初始化
 
xxxxxxxxxx
  // 在Activity中初始化kwTrackerWrapper
  // 传入Android context和Camera type(表示是前置摄像头还是后置摄像头), e.g Camera.CameraInfo.CAMERA_FACING_FRONT
  kwTrackerWrapper = new KwTrackerWrapper(this, mCamera.mCurrentCameraId);
  kwTrackerWrapper.onCreate(this);
  1. 在Activity布局中引入自定义控件

    <com.kiwi.ui.KwControlView
      android:id="@+id/camera_control_view"
      android:layout_height="match_parent"
      android:layout_width="match_parent"/>
    1. 调用KwTrackerManager的方法
 
x
  public OnViewEventListener initUIEventListener(final UIClickListener uiClickListener) {
    OnViewEventListener eventListener = new OnViewEventListener() {
        @Override
        public void onTakeShutter() {
            uiClickListener.onTakeShutter();
        }
        //切换摄像头
        @Override
        public void onSwitchCamera() {
            uiClickListener.onSwitchCamera();
        }
        //滤镜切换
        @Override
        public void onFilterChanged(KwFilterType filterType) {
            getKwTrackerManager().switchFilter(filterType);
        }
        //贴纸切换
        @Override
        public void onStickerChanged(StickerConfig item) {
            getKwTrackerManager().switchSticker(item);
        }
        //大眼瘦脸开关
        @Override
        public void onSwitchBeauty(boolean enable) {
            getKwTrackerManager().setBeautyEnabled(enable);
        }
        //全局美颜开关
        @Override
        public void onSwitchBeautyFace(boolean enable) {
            getKwTrackerManager().setBeautyFaceEnabled(enable);
        }
        //描点
        @Override
        public void onSwitchDrawPoints() {
            getKwTrackerManager().switchDrawPoints();
        }
        //哈哈镜切换
        @Override
        public void onDistortionChanged(KwFilterType filterType) {
            getKwTrackerManager().switchDistortion(filterType);
        }
      //赠送礼物
      //giftSticker  礼物贴纸
      //播放次数
       @Override
       public void onGiveGift(StickerConfig giftSticker) {
           getKwTrackerManager().switchGift(giftSticker, 1);
        }
        @Override
        public void onAdjustFaceBeauty(int type, float param) {
            switch (type) {
                //大眼调整
                case KwControlView.BEAUTY_BIG_EYE_TYPE:
                    getKwTrackerManager().adjustFaceBigEyeScale(param);
                    break;
                //瘦脸幅度调整
                case KwControlView.BEAUTY_THIN_FACE_TYPE:
                    getKwTrackerManager().adjustFaceThinFaceScale(param);
                    break;
                case SKIN_SHINNING_TENDERNESS:
                        //粉嫩
                      getKwTrackerManager().adjustSkinShinningTenderness(param);
                      break;
                 case SKIN_TONE_SATURATION:
                        //饱和
                      getKwTrackerManager().adjustSkinToneSaturation(param);
                      break;
                 case REMOVE_BLEMISHES:
                        //磨皮
                      getKwTrackerManager().adjustRemoveBlemishes(param);
                      break;
                case SKIN_TONE_PERFECTION:
                        //美白
                      getKwTrackerManager().adjustSkinTonePerfection(param);
                      break;
            }
        }
        //全局美颜幅度调整
        @Override
        public void onFaceBeautyLevel(float level) {
            getKwTrackerManager().adjustBeauty(level);
        }    

其他注意事项

  • 请开发者在build.gradle定义支持的CPU架构 在Module的buid.gradle文件中添加依赖和属性配置:

      android {
                defaultConfig {
                  ndk {
                    //设置支持的SO库架构
                    abiFilters 'armeabi' //, 'x86', 'armeabi-v7a', 'x86_64', 'arm64-v8a'
                  }
                }
            }
  • 请避免混淆Kiwi,在Proguard混淆文件中增加以下配置:

     
    xxxxxxxxxx
    -dontwarn com.kiwi.**
    -keep public class com.kiwi.**{*;}
KiwiFace常见问题.md

KiwiFace集成常见问题(iOS)

1. KW_Track.bin文件过大?

如果觉得KW_Track.bin文件占用大,可以采用下载的方式。

  • 将KWSDK .m的sharedManager方法里初始化renderer删掉。

image1

  • 在需要初始化的controller里声明一个NSString属性。并用下图所示方法初始化renderer

    image3

image5

在进入需要使用tracker的页面之前下载KW_Track.bin文件(使用场景可按自身需求改变)。

2. 贴纸图片报错

stickers文件夹引入方式不正确。按照下图方式引入stickers文件夹

image7

3. 模拟器不能使用

Tracker暂时不支持模拟器,只能在真机上使用。

4. GPUImage必须使用我们demo中提供的吗

  • 录制视频必须使用我们demo中提供的GPUImage
  • 推流直播可以不使用我们demo中提供的GPUImage

5. 美颜可变参数是多少?

美颜指定可变最小值:0;

美颜指定可变最大值:100;

美颜指定初始值:可根据kiwiSDK美颜参数参考设置;

6. 贴纸没有效果

检查一下tracker的返回值,通过返回值判断原因。下列是tracker返回值的含义:

 
#define KW_OK 0                            //正常状态
#define KW_E_OUT_OF_DATE -1                //日期过期
#define KW_E_INVALID_BUNDLEID -2           //bundle id匹配错误
#define KW_E_DETECTOR_LOADFAILED -3        //xml载入失败
#define KW_E_ALIGNMENT_LOADFAILED -4       //bin载入失败
#define KW_E_INVALID_FACE_NUM -5           //错误的人脸个数
#define KW_E_WRONG_IMAGE_FORMAT -6         //错误的图像格式
#define KW_E_NO_DETECT_FACE -8             //没有检测到人脸
#define KW_E_TRACK_FAILED -9               //跟踪失败
#define KW_E_NETCERTIFICATION_FAILED -10   //网络验证失败
#define KW_E_NULL_KEY_STRING -11           //空的密钥

7. stickers目录层级

image9

8. 可以从自己的服务器下载贴纸吗?

  • 既可以从我们的服务器上下载贴纸,也可以从自己的服务器上下载贴纸。从自己的服务器下载贴纸需要在stickers.json文件中添加”sourceType”: “1"的字段。

    image11

  • 在下图红色方框中填入贴纸压缩包链接。

    image13

9. 引入SSZipArchive,出现错误

image15

10. 没有渲染效果,打印Failed to create IOSurface image (texture)

需要将GPUImage里面YUV的视频帧输出格式改为RGBA的视频帧格式。

image17

11. 使用shader滤镜需要在Build Settings中的Other Linker Flags加上-all_load

kiwiface-android-faq.md

KiwiFace集成常见问题(Android)

1. 界面卡顿怎么办?

​ 可以打开性能优先模式,目前配置的是oppo和vivo,还可以自己配置指定的系统版本以及其他手机

 
String manufacturer = Build.MANUFACTURER.toLowerCase();
boolean isOppoVivo = manufacturer.contains("oppo") || manufacturer.contains("vivo");
  if(isOppoVivo || Build.VERSION.SDK_INT < Build.VERSION_CODES.LOLLIPOP){
            Config.TRACK_MODE = Config.TRACK_PRIORITY_PERFORMANCE;
   }
  • so包问题
 
只使用armeabi下的so包会导致界面卡顿,建议加上armeabi-v7a 和x86下面的so包


2. track 返回-1

 
如果日志中返回track  -1字样,那么需要确认发放的证书日期是否已过期,或者手机的日期不在证书的日期之内

3. 接入ndk,apk不能安装或者启动失败,提示不支持某架构

可以在build.gradle配置ndk架构,如:

 
android {
            defaultConfig {
              ndk {
                //设置支持的SO库架构
                abiFilters 'armeabi' //, 'x86', 'armeabi-v7a', 'x86_64', 'arm64-v8a'
              }
            }
        }

4. 如何关闭sdk中的日志:

 
Config.isDebug = false;

5. sdk中用了哪些包

 
com.github.bumptech.glide:glide:3.7.0
com.android.support:appcompat-v7:25.1.0

6. 安装的时候有个Leaks是什么?

 
Leaks是用于检查内存泄漏的,而且只在debug包下才会生成,release包不会生成

7. 七牛直播本地预览有效果,观众端没效果

​ 添加以下代码:

 
  mCameraStreamingSetting.setCameraId(Camera.CameraInfo.CAMERA_FACING_BACK)
                         .setCameraSourceImproved(true)

8. KW_Track过大

 
/**
 * model路径,支持用户网络下载KW_Track.bin,放在此目录下
 *
 * @param context
 * @return model路径
 */
public static String getModelPath(Context context) {
    String path = null;
    File dataDir = context.getApplicationContext().getExternalFilesDir("");
    if (dataDir != null) {
        path = dataDir.getAbsolutePath() + File.separator + models;
    }
    return path;
}

9. 大眼瘦脸参数多少

 
大眼指定可变最小值:0.05;大眼指定可变最大值:0.3;大眼指定初始值:0.10
瘦脸指定可变最小值:0.90;瘦脸指定可变最大值:1.00;瘦脸指定初始值:1.90 - 0.97;