本文为您介绍Android端阿里云Queen SDK的接口文档、集成操作及简单使用示例,用于实现美颜特效功能。

前提条件

开发前的环境要求如下表所示。
类别 说明
系统版本 支持Android 4.3及以上版本。
Java版本 支持Java 1.7及以上版本。
API LEVEL 支持ANDROID SDK API LEVEL 18及以上版本。
Android Studio版本 支持Android Studio 2.3以上版本,下载Android Studio

接口文档

中文版接口文档,更多信息,请参见接口文档

Sample示例工程

可参考的样例工程,请参见Sample示例工程。示例工程文件中,assets目录下包含Demo所有图片资源。

Maven方式集成SDK

  1. 在项目级build.gradle项目文件中添加阿里云Maven仓库。
    allprojects {
        repositories {
            google()
            jcenter()
            maven { url "https://maven.aliyun.com/repository/releases" }
        }
    }
  2. 在应用级build.gradle项目文件下加入Queen依赖项。
    implementation "com.aliyun.maliang.android:queen:1.1.0-official-pro"

手动导入aar集成SDK

  1. 下载并解压SDK。下载地址请参见SDK下载
  2. 将解压SDK获得的.aar文件复制到工程的libs目录中。

使用示例

  • 创建QueenEngine实例,设置初始化纹理与视窗参数
    QueenEngine engine;
    try {
        // 传入Android.content.Context触发引擎的初始化
        // 第二个参数为true表示直接输出到当前OpenGL的显示区域
        engine = new QueenEngine(mContext,true);
    } catch (InitializationException e) {
        e.printStackTrace();
    }
    
    // 设置输入纹理,用于美颜流程的渲染
    // 第四个参数表示输入纹理是否为OES类型的纹理
    engine.setInputTexture(textureId, textureWidth, textureHeight, true);
    
    // 非必要步骤:获得美颜输出纹理,可以在用于其他扩展业务
    Texture2D outTexture = engine.autoGenOutTexture();
    engine.updateOutTexture(outTexture.getTextureId(), textureWidth, textureHeight);
    
    // 设置视窗大小
    engine.setScreenViewport(0, 0, viewWidth, viewHeight);
    // 开启log日志打印调试模式
    engine.enableDebugLog();
  • 设置美白和基础美化功能参数
    • 美白
      //美白开关
      engine.enableBeautyType(BeautyFilterType.kSkinWhiting, true);
      //美白参数 [0,1]
      engine.setBeautyParam(
          BeautyParams.kBPSkinWhitening, 
          0.3f
      );
    • 基础美颜
      //磨皮/锐化 开关
      engine.enableBeautyType(BeautyFilterType.kSkinBuffing, true);
      //磨皮 [0,1]
      engine.setBeautyParam(BeautyParams.kBPSkinBuffing, 0.6f);
      //锐化 [0,1]
      engine.setBeautyParam(BeautyParams.kBPSkinSharpen, 0.2f);
  • 设置高级功能参数
    使用高级功能,如高级美颜、美型、美妆、滤镜、贴纸,需要调用执行算法。
    // 输入帧图片流,
    engine.updateInputDataAndRunAlg(
        imageData, // 帧图片流
        ImageFormat.NV21, // 帧图片流格式
        imageWidth, // 帧图片宽度 
        imageHeight, // 帧图片高度
        0, // 用于检测的图像的跨度(以像素为单位),即每行的字节数, 默认情况下设为 0
        mCamera.inputAngle, // 当前输入帧图片需旋转的角度,计算方式参考Sample工程
        mCamera.outAngle, // 算法输出结果所需旋转的角度,计算方式参考Sample工程
        mCamera.flipAxis // 输出数据的xy轴翻转处理,0为不旋转,1为x轴翻转,2为y轴翻转
        );
    • 高级美颜
      //高级美颜开关
      engine.enableBeautyType(BeautyFilterType.kFaceBuffing, true);
      //去法令纹[0,1]
      engine.setBeautyParam(BeautyParams.kBPNasolabialFolds, 0.3f); 
      //去眼袋[0,1]
      engine.setBeautyParam(BeautyParams.kBPPouch, 0.3f); 
      //白牙[0,1]
      engine.setBeautyParam(BeautyParams.kBPWhiteTeeth, 0.2f); 
      //滤镜美妆:口红[0,1]
      engine.setBeautyParam(BeautyParams.kBPLipstick, 0.2f); 
      //滤镜美妆:腮红[0,1]
      engine.setBeautyParam(BeautyParams.kBPBlush, 0.2f);
      //滤镜美妆:亮眼[0,1]
      engine.setBeautyParam(BeautyParams.kBPBrightenEye, 1.0f); 
      // 滤镜美妆:红润[0,1]
      engine.setBeautyParam(BeautyParams.kBPBlush, 1.0f);
      // 滤镜美妆:口红色相[-0.5,0.5],需配合饱和度、明度使用,参考颜色如下:土红(-0.125)、粉红(-0.1)、复古红(0.0)、紫红(-0.2)、正红(-0.08)、橘红(0.0)、紫色(-0.42)、橘色(0.125)、黄色(0.25)
      engine.setBeautyParam(BeautyParams.kBPLipstickColorParam, 0.0f);
      // 滤镜美妆:口红饱和度[0,1],需配合色相、明度使用,参考颜色如下:土红(0.25)、粉红(0.125)、复古红(1.0)、紫红(0.35)、正红(1.0)、橘红(0.35)、紫色(0.35)、橘色(0.25)、黄色(0.45)
      engine.setBeautyParam(BeautyParams.kBPLipstickGlossParam, 0.0f);
      // 滤镜美妆:口红明度[0,1],需配合色相、饱和度使用,参考颜色如下:土红(0.4)、粉红(0.0)、复古红(0.2)、紫红(0.0)、正红(0.0)、橘红(0.0)、紫色(0.0)、橘色(0.0)、黄色(0.0)
      engine.setBeautyParam(BeautyParams.kBPLipstickBrightnessParam, 1.0f);
    • 美型
      // 美型开关,其中第二个参数是功能开关,第三个参数为调试开关
      engine.enableBeautyType(BeautyFilterType.kFaceShape, true, false);
      /**
       * 美型参数:颧骨<br />
       * 参数范围:[0,1]
       */
      engine.updateFaceShape(FaceShapeType.typeCutCheek, 0.0f);
      /**
       * 美型参数:削脸<br />
       * 参数范围:[0,1]
       */
      engine.updateFaceShape(FaceShapeType.typeCutFace, 0.0f);
      /**
       * 美型参数:瘦脸<br />
       * 参数范围:[0,1]
       */
      engine.updateFaceShape(FaceShapeType.typeThinFace, 0.0f);
      /**
       * 美型参数:脸长<br />
       * 参数范围:[0,1]
       */
      engine.updateFaceShape(FaceShapeType.typeLongFace, 0.0f);
      /**
       * 美型参数:下巴缩短<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeLowerJaw, 0.0f);
      /**
       * 美型参数:下巴拉长<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeHigherJaw, 0.0f);
      /**
       * 美型参数:瘦下巴<br />
       * 参数范围:[0,1]
       */
      engine.updateFaceShape(FaceShapeType.typeThinJaw, 0.0f);
      /**
       * 美型参数:瘦下颌<br />
       * 参数范围:[0,1]
       */
      engine.updateFaceShape(FaceShapeType.typeThinMandible, 0.0f);
      /**
       * 美型参数:大眼<br />
       * 参数范围:[0,1]
       */
      engine.updateFaceShape(FaceShapeType.typeBigEye, 0.0f);
      /**
       * 美型参数:眼角1<br />
       * 参数范围:[0,1]
       */
      engine.updateFaceShape(FaceShapeType.typeEyeAngle1, 0.0f);
      /**
       * 美型参数:眼距<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeCanthus, 0.0f);
      /**
       * 美型参数:拉宽眼距<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeCanthus1, 0.0f);
      /**
       * 美型参数:眼角2<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeEyeAngle2, 0.0f);
      /**
       * 美型参数:眼睛高度<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeEyeTDAngle, 0.0f);
      /**
       * 美型参数:瘦鼻<br />
       * 参数范围:[0,1]
       */
      engine.updateFaceShape(FaceShapeType.typeThinNose, 0.0f);
      /**
       * 美型参数:鼻翼<br />
       * 参数范围:[0,1]
       */
      engine.updateFaceShape(FaceShapeType.typeNosewing, 0.0f);
      /**
       * 美型参数:鼻长<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeNasalHeight, 0.0f);
      /**
       * 美型参数:鼻头长<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeNoseTipHeight, 0.0f);
      /**
       * 美型参数:唇宽<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeMouthWidth, 0.0f);
      /**
       * 美型参数:嘴唇大小<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeMouthSize, 0.0f);
      /**
       * 美型参数:唇高<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeMouthHigh, 0.0f);
      /**
       * 美型参数:人中<br />
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typePhiltrum, 0.0f);
      /**
       * 美型参数:发际线
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeHairLine, 0.0f);
      /**
       * 美型参数:嘴角上扬(微笑)
       * 参数范围:[-1,1]
       */
      engine.updateFaceShape(FaceShapeType.typeSmile, 0.0f);
    • 美妆
      // 第二个参数是开关,第三个参数是调试开关
      engine.enableBeautyType(BeautyFilterType.kMakeup, true, false);
      
      // 设置美妆素材
      // 第一个参数是美妆类型
      // 第二个参数是素材文件路径,基于assets的相对路径,如"/makeup/蜜桃妆.png"
      // 第三个参数是素材与人脸的融合类型,第四个参数是保留参数
      engine.setMakeupImage(MakeupType.kMakeupWhole,
                            makeupResPath,
                            BlendType.kBlendNormal,
                            15);
      // 设置美妆素材透明度
      // 第二个参数是透明度,第三个参数是保留参数
      engine.setMakeupAlpha(MakeupType.kMakeupWhole,
                            0.6f,
                            0.3f);
    • 滤镜
      // 功能开关
      engine.enableBeautyType(BeautyFilterType.kLUT, true);
      //设置滤镜资源路径,基于assets的相对路径,如“/lookups/lookup_1.png”
      engine.setFilter(lutResPath); 
      //滤镜强度
      engine.setBeautyParam(BeautyParams.kBPLUT, 1.0f); 
    • 贴纸
      // 删除贴纸素材路径
      engine.removeMaterial(oldStickerResPath);
      // 添加贴纸素材路径,相同贴纸不能重复添加
      // 基于assets的相对路径,如"/sticker/baiyang"
      engine.addMaterial(stickerResPath);
    • 抠像
      /**
       * 设置绿幕抠像参数
       * @param backgroundPath : 要替换的背景资源图文件地址,路径地址为"",则为关闭该项功能
       * @param blueScreenEnabled : 是否使用蓝幕,true为替换蓝幕背景,false则为替换绿幕背景
       * @param threshold 范围:【20,60】,默认建议取值30.    
       */
      engine.setGreenScreen(String backgroundPath, boolean blueScreenEnabled, float threshold);
  • 渲染
    // OES纹理的变换矩阵,通过SurfaceTexture获取
    float[] transformMatrix = new float[16];
    // 通过SurfaceTexture更新矩阵
    mSurfaceTexture.updateTexImage();
    mSurfaceTexture.getTransformMatrix(transformMatrix);
    
    // 渲染到当前窗口,如证书校验失败或者全部特效功能关闭,则SDK不会执行渲染操作
    int retCode = engine.renderTexture(transformMatrix);
    
    // 参考API文档
    // QUEEN_INVALID_LICENSE(-9),表示证书校验失败
    // QUEEN_NO_EFFECT(-10),表示全部特效功能关闭
    // 则需要业务方执行渲染,可参考Sample工程
    if (retCode == -9 || retCode == -10) {
        mFrameGlDrawer.draw(transformMatrix, mOESTextureId, true);
    }
  • 释放引擎
    // 释放引擎资源
    engine.release();

视频直播接入范例

以当前阿里云视频直播官网v4.0.2为例,接入步骤如下所示。

  1. 确保已开启直播配置项,允许预处理模式。
    mAliLiveConfig.customPreProcessMode = CUSTOM_MODE_VIDEO_PREPROCESS;
  2. 初始化QueenEngine。
    engine = new QueenEngine(this, false);
  3. 注册视频处理回调代理,获取纹理更新。
    mAliLiveEngine.setVidePreProcessDelegate(new AliLiveCallback.AliLiveVideoPreProcessCallback() {
        @Override
        public int onTexture(int textureId, int width, int height, int rotate, int i4) {
            // 绑定更新当前gl环境
            int[] oldFboId = new int[1];
            GLES20.glGetIntegerv(GLES20.GL_FRAMEBUFFER_BINDING, IntBuffer.wrap(oldFboId));
    
            // 更新输入纹理id
            engine.setInputTexture(textureId, width, height, false);
    
            // 更新设置美颜美型相关参数
            engine.enableBeautyType(BeautyFilterType.kSkinBuffing, true);//磨皮开关
            engine.setBeautyParam(BeautyParams.kBPSkinBuffing, 0.9f);  //磨皮 [0,1]
            engine.setBeautyParam(BeautyParams.kBPSkinSharpen, 0.6f);  //锐化 [0,1]
    
            // 指定处理后的画面更新到新的纹理id上
            if (mOutTexture == null) {
                mOutTexture = engine.autoGenOutTexture();
            }
            engine.updateOutTexture(mOutTexture.getTextureId(), width, height);
    
            // 开始渲染画面
            int result = engine.render();
            // 绑定更新到当前gl环境
            GLES20.glBindFramebuffer(GL_FRAMEBUFFER, oldFboId[0]);
            // 返回更新后的纹理id
            return mOutTexture.getTextureId();
        }
    
        @Override
        public void onTextureDestroy() {
            Log.e("AnchorActivity", "onTexture: ");
        }
    
        @Override
        public void onVideoData(long l, long l1, long l2, AliLiveConstants.AliLiveImageFormat aliLiveImageFormat, int i, int i1, int i2, int i3, int i4, int i5) {
                 // 更新视频帧数据
                engine.updateInputDataAndRunAlg();
        }
    });