本文列举了接入美颜特效SDK常见的集成、调用等技术问题。
目录
一般类问题 | 技术类问题 |
什么是美颜特效SDK？
美颜特效SDK是由阿里云自研的，用于各种视频拍摄场景下提供的包括美颜美型、滤镜、贴纸、美妆及手势识别智能抠图等多种实时特效功能，覆盖多种拍摄场景，满足用户多类拍摄需求。
美颜特效SDK是否支持第三方接入使用？
美颜特效SDK作为完全独立的SDK，可与市面上阿里直播SDK、腾讯云SDK、七牛直播SDK、声网SDK、Librestreaming等常见SDK进行组合使用。
组合使用诉求简单，只要任何第三方SDK支持返回纹理或画面数据Buffer给到应用侧自行处理，则均可接入到美颜特效SDK中。同时，为方便各种业务更快速便捷接入，美颜特效SDK已与阿里云的短视频SDK、直播推流SDK、互动直播SDK、RTC等常用SDK进行深度合作绑定可快速直接接入。操作指引，请参见快速接入。
如何选择美颜特效SDK版本？
为便于客户贴近业务更小合集地来接入，美颜特效SDK按照常见业务使用场景，细分为5个版本。
基础lite版本
专业pro版本
旗舰ultimate版本
智能抠图版本
手势识别版本
5个版本既可独立使用，也可按需进行功能组合叠加。前三个版本功能范围，请参见SDK下载。
智能抠图主要解决绿/蓝幕抠图和实时场景下的抠图，绿/蓝幕抠图更准确说是纯色幕布抠图，支持包括绿幕/蓝幕/青幕/紫幕在内的各种常见纯色背景幕布。
手势识别主要对各种常用手势进行识别，同时该版本也支持识别人体姿态。
智能抠图和手势识别由于包体大小与常用性的关系，没有在Demo包中体现。有需要的客户可以发送需求到创建应用并绑定License，或加入钉钉群：34197869，联系我们试用体验。
如何申请不同版本的SDK？
根据自身业务需求，选定匹配的版本，申请可按照指定要求，发送信息到指定地址即可，我们会在工作日的48小时内进行开通授权及后续对接服务。操作指引，请参见获取美颜特效SDK License。
想要手势识别或智能抠图SDK如何获取？
手势识别与智能抠图SDK，作为特殊应用场景中的特殊应用，一般会需要一定的定制服务，不直接对外开放SDK下载，您可从我们的Demo中直接试用体验，看是否符合预期，请参见体验美颜特效SDK。如果想进一步了解对应接入和使用规则，欢迎发送需求到创建应用并绑定License或加入我们官方钉钉群（34197869）来咨询更详细信息。
资源加载
使用MediaBox音视频SDK时，如果您没有使用我们的低代码（含UI）集成方案，则需要手动处理算法模型等资源文件的下载，否则部分依赖算法模型的美颜特效功能无法生效。
请参照以下文档，在完成资源下载后再使用美颜特效SDK的功能。
Android：Android端集成美颜特效SDK/使用示例/资源下载能力
iOS：iOS端集成美颜特效SDK/动态下载接口调用示例
美颜SDK的API使用要求？
美颜SDK所有API，包括创建、配置、使用、销毁，在整个使用过程中，必须确保满足如下两个条件：
始终在同一个线程中调用。
该线程必须要有GL上下文。若没有，可通过接口，改由Queen内部去创建。
问题排查调试方法？
Android端：
engine创建完成后，打开debug开关。
engine.enableDebugLog();可以通过过滤“Queen”关键字来查看当前美颜SDK运行状态的日志输出，如下：
其中，过滤d级日志，信息较多，过滤i级日志，信息集中。
输入输出参数怎么填?
SDK内置了智能自动检测当前画面最佳输入参数的算法，通过如下两个步骤，可以开启查看当前所预期需要的输入参数。
创建engine时，指定算法输入模式为自动模式。config.algInputMode = AlgInputMode.kModeAutomatic;
开启debugLog模式，即engine创建完成后，打开debug开关。
engine.enableDebugLog();通过过滤日志，可以看到如下的Logcat输出。
其中，input_angle，out_angle，out_flip即为算法计算得出的，当前画面预期的输入参数值。
智能算法检测画面会有额外性能开销，测试验证完毕后，请及时还原该两步的操作。
SDK性能表现如何？
美颜特效SDK历经多年迭代，在性能优化、效果优化、效率优化方面力求做到业内领先。尤其，性能优化一直是美颜特效SDK在技术侧最为看重的方面，经过多轮优化，已达到性能水平领先，尤其在低端机和东南亚地区较老系统版本中，进行专项优化与迭代。对同一功能提供多种版本，例如美颜模块，提供高级模式、省电模式、智能调节模式等更好去适配客户实际场景。同时，日常迭代中，每个版本均有专门的多维度性能测试报告，并在多个内外部客户中得到大规模验证与应用。
如何解决屏幕黑屏问题？
出现原因：常见是由于纹理ID错误或生成纹理错误所致，偶尔会出现个别客户对返回后的纹理ID使用不当或使用无效纹理ID进行自身业务层的绘制而产生黑屏的问题。
解决方法：美颜特效SDK的渲染层基于OpenGL实现，只要确保传入美颜特效SDK接口的纹理ID是正常显示，则美颜特效SDK可以保障传出的画面纹理是正常可显示的。即便没有应用任何效果甚至是参数错误或者是没有授权情况下，美颜特效SDK也会保证将原始纹理进行返回。
接入美颜特效SDK后，画面纯色闪烁，移动手机后，画面颜色变化，但仍然没有画面？
出现条件：engine的构造参数toScreen为true，input纹理为oes纹理，render采用无参render()。
解决方法：render()改为renderTexture(matrix) ，如果输入纹理是oes的，则需要使用renderTexture，其中参数matrix是需要从surfaceTexture中获取的。
启动后闪退问题？
检查engine.setInputTexture中的textureId是否正确，确保正确后，重新启动。
贴纸/美妆功能，人脸像呈90度横屏后，人脸不可识别问题？
出现条件：engine的构造参数toScreen为true，input纹理为oes纹理，render采用无参render()，且算法运算采用取帧方案，而非bytebuffer方案。
解决方法：用bytebuffer方案，人脸能识别，但因为宽高的原因，会出现被错误拉大或拉窄情况。
基础美颜有效，高级美颜/美妆/贴纸无效问题？
基础美颜有效，说明Queen-engine的初始化/设参/渲染流程是通的，高级美颜无效，通常是由于设置参数错误，导致识别不了人脸，从而导致一切需要人脸关键点的效果均失效。常见的可能设置错误的参数，主要有三种情况：
设置纹理输入时宽高参数错误，如接口：
setInputTexture(int texture, int width, int height, boolean isOES)，其中width/height必须是当前texture的显示宽高大小，需与texture参数匹配。第四个参数isOES直接决定了texture是否是一个oes纹理（Android特有），是否是oes纹理决定了Queen-engine内部是否需要做纹理显示转换（对应需要render传入当前相机采集时正确的matrix）。此处的宽/高直接决定了显示画面渲染的宽高比，从而可能影响到高级功能的效果在具体渲染时的画面缩放比。常见的影响效果是，高级功能效果可用，但尺寸被拉大且变形。设置输入数据时的宽高参数错误，如接口：
updateInputDataAndRunAlg(byte[] imageData, int format, int width, int height, int stride, int inputAngle, int outAngle, int flipAxis, boolean reuseData)，其中的width/height指示的是当前输入数据ImageData的实际宽/高，它和上面第1种情况中的宽/高，可能是相同参数，也可能是相反参数（如Android端直接从相机里获取到的buffer都是旋转90度的，宽/高刚好相反）。此处的宽/高直接决定了人脸头像是否能正常识别，进而直接影响功能是否可用。设置输入数据时的输入角度/输出角度/xy轴旋转等参数错误，如接口：
updateInputDataAndRunAlg(byte[] imageData, int format, int width, int height, int stride, int inputAngle, int outAngle, int flipAxis, boolean reuseData)或者帧同步接口updateInputTextureBufferAndRunAlg(int inputAngle, int outAngle, int flipAxis, boolean usePreviousFrame)，其中的inputAngle/outAngle/flipAxis都是高级功能中人脸识别所必需的参数。 参数inputAngle决定了算法如何使用传入的数据或纹理，是否需要旋转，旋转多少角度；参数outAngle决定了算法如何将识别结果进行渲染显示，是否需要旋转，旋转多少角度；参数flipAxis是个枚举值，Queen-engine内有定义，决定了最终渲染画面是否需要对称翻转，沿x轴还是y轴翻转；上述几个参数，对算法识别特别关键，且又和当前相机角度/前后摄像头密切相关，为方便处理，特地封装与整理到了相关处理工具类QueenCameraHelper.java中，各应用可在此基础上直接或适当调整使用。