You need to enable JavaScript to run this app.
导航
集成 HEIF 编码库
最近更新时间:2024.06.21 18:12:33首次发布时间:2024.05.07 15:24:06

本文为您介绍 veImageX 自研 Android 端 HEIF 编码库的接入流程。

适用版本

本文档适用于 Android 4.0 及以上开发版本。

前提条件

您已完成独立 HEIF 编解码库的集成准备

添加 Maven 仓库

确保 project 根目录下的build.gradle下配置服务,代码示例如下所示:

maven {
    url 'https://artifact.bytedance.com/repository/Volcengine/'
    // 最新版本号获取地址:https://artifact.bytedance.com/repository/Volcengine/
}

获取 SDK 最新版本号

请参考发布历史,获取 SDK 最新版本号。

添加 SDK 依赖

在 module 目录下的build.gradle文件中的dependencies中添加 SDK 依赖,并填入获取的最新版本号。代码示例如下所示:

implementation 'com.bytedance.fresco:authorization:xxx'//添加授权认证+云控配置
implementation 'com.bytedance.fresco:nativeheifencoder:xxx' //heif 编码

混淆规则

proguard-rules.pro 文件中配置 SDK 混淆规则。

-keep class com.bytedance.fresco.cloudcontrol.CloudControl {*;}
-keep class com.bytedance.fresco.native_heif_encoder.HeifEncoder {*;}
-keep class com.bytedance.imagex.bdauthorization.AuthManagerNative {
    native <methods>;
}

日志打印

测试开发的过程中,建议打开 logcat 日志,便于排查和调试问题。

注意

对于 Release 线上版本建议您关闭日志打印能力,以减少实际业务使用时的性能开销。

ImageXLog.setDebug(true);
AuthManagerNative.nativeOpenLog(true);

配置授权

在自定义的ApplicationonCreate方法中执行下面代码:

List<String> encodedAuthCode = new ArrayList<>();
encodedAuthCode.add("xxxxxxxxxxxxxxxxxxxxxxxxx");

InitConfig initConfig = new InitConfig(
        this,             // Application Context
        "000000",         // App id, 如实填写
        "sample",         // App Name,暂未用到,传入app名称
        "debug",          // channel,暂未用到,传入例如OPPO 
        "0.0.1",          // App的versionName, 如实填写
        "1",              // App的versionCode, 如实填写
        "48144589260",    // device id,暂未用到
        InitConfig.CHINA, // App上线的区域,如实填写
        "M2ZmYzkzZjUtN2", // Token,如实填写,您可在 接入准备-购买授权 获取Token
        encodedAuthCode   // 授权码List<String>,如实填写,您可在 接入准备-购买授权 获取授权码
);
CloudControl.init(initConfig);

编码准备

为避免因加载库失败导致后续调用编码库接口时出现异常,请确保在调用编码接口之前先调用 HeifEncoder.init() 加载 so。如果返回值为 true 则表示 so 加载成功,此时您可正常调用编码接口进行图片编码。如果返回值为 false,您可重新调用 init() 进行重试。代码示例如下所示:

public class HeifEncoder {
    /**
     * 调用该接口会进行 so 加载。
     * sdk 会在类加载时会自动调用该接口,但特殊机型可能会偶现 so 加载失败的情况,这时可调用此接口重试 so 加载。
     * 建议在调用编码接口之前调用,并判断返回值,返回 true 表示 so 加载成功,可能正常使用编码接口。
     * 
     * @return true, so 加载成功,可使用以下编码接口。
     *         false,so 加载失败,可调整时机再次调用 init 重试 so 加载。
     */
    public synchronized static boolean init();
}

编码示例

  • 使用 bitmap 编码成 heic,代码示例如下所示:
FileOutputStream fileOutputStream = new FileOutputStream(new File(getFilesDir(), "bitmap_encode.heic"));
HeifEncoder.compressBitmap(bitmap, quality, fileOutputStream);
  • 使用 yuv 数据编码成 heic,代码示例如下所示:
FileOutputStream fileOutputStream = new FileOutputStream(new File(getFilesDir(), "yuv_encode.heic"));
HeifEncoder.compressYuv(yuv, width, height, quality, fileOutputStream);
  • 使用 yuva 数据编码成 heic,代码示例如下所示:
FileOutputStream fileOutputStream = new FileOutputStream(new File(getFilesDir(),  "yuva_encode.heic"));

HeifEncoder.compressYuva(yuva, width, height, quality, fileOutputStream, exifData, HeifEncoder.ENCODE_SPEED_FAST);
  • 使用 rgba 数据编码成 heic,代码示例如下所示:
FileOutputStream fileOutputStream = new FileOutputStream(new File(getFilesDir(), "rgba_encode.heic"));
HeifEncoder.compressRgba(rgba, width, height, quality, fileOutputStream);
  • 使用 rgb 数据编码成 heic,代码示例如下所示:
FileOutputStream fileOutputStream = new FileOutputStream(new File(getFilesDir(),  "rgb_encode.heic"));

HeifEncoder.compressRgb(rgb, width, height, quality, fileOutputStream, exifData, HeifEncoder.ENCODE_SPEED_FAST);
  • 使用本地其他格式(jpg、png)文件编码成 heic,代码示例如下所示:
FileOutputStream fileOutputStream = new FileOutputStream(new File(getFilesDir(), "jpg_encode.heic"));
HeifEncoder.compressLocalPic(filePath, quality, fileOutputStream);

编码接口介绍

com.bytedance.fresco.native_heif_encoder.HeifEncoder 类

com.bytedance.fresco.native_heif_encoder.HeifEncoder为编码 heic 静图的接口类,支持 bitmap/yuv/yuva/rgba/rgb/jpg 进行 heic 编码。代码示例如下所示:

/**
 *
 * @param filePath 需要编码的本地图片,必须是系统可以解码的图片格式,例如:jpg png
 * @param quality 编码质量,取值范围为[1,100]。1 表示为最小编码质量,100 表示为最大编码质量。值越大,编码后的图片体积越大,画质越好
 * @param hasAlpha 是否有 alpha 通道
 * @param stream 写入编码heic数据的流
 * @param exifData exifData 数据
 * @return 0 成功
 *         12001 云控配置不支持编码,请提交工单联系技术支持协助您修改云控配置
 *         12002 授权错误,请检查是否正确配置授权
 *         13101 底层创建数组失败,请检查是否内存不足(2.9.5-tob 及以上版本支持)
 *         其他 未定义错误,您可提交工单联系技术支持协助排查和处理
 */
public static int compressLocalPic(String filePath, int quality, boolean hasAlpha, OutputStream stream, byte[] exifData)
        
/**
 * @param bitmap 需要编码的 bitmap 数据
 * @param quality 编码质量,取值范围为[1,100]。1 表示为最小编码质量,100 表示为最大编码质量。值越大,编码后的图片体积越大,画质越好
 * @param hasAlpha 是否有alpha通道
 * @param stream 写入编码heic数据的流
 * @param exifData exifData 数据
 * @param speed   编码档位,“slow”表示编码压缩率高速度慢,“fast”表示编码压缩率低速度快
 * @return 0 成功
 *         12001 云控配置不支持编码,请提交工单联系技术支持协助您修改云控配置
 *         12002 授权错误,请检查是否正确配置授权
 *         13101 底层创建数组失败,请检查是否内存不足(2.9.5-tob 及以上版本支持)
 *         其他 未定义错误,您可提交工单联系技术支持协助排查和处理
 */        
public static int compressBitmap(Bitmap bitmap, int quality, boolean hasAlpha, OutputStream stream, byte[] exifData, String speed)
        
/**
 * @param yuvData 需要编码的yuv数据
 * @param width 宽
 * @param height 高
 * @param quality 编码质量,取值范围为[1,100]。1 表示为最小编码质量,100 表示为最大编码质量。值越大,编码后的图片体积越大,画质越好
 * @param stream 写入编码heic数据的流
 * @param exifData exifData 数据
 * @param speed   编码档位,“slow”表示编码压缩率高速度慢,“fast”表示编码压缩率低速度快
 * @return true 成功, false 失败
 */
public static boolean compressYuv(byte[] yuvData, int width,int height,int quality,OutputStream stream, 
byte[] exifData, String speed) throws IllegalArgumentException, IOException 

/**
 * @param yuvaData 需要编码的yuva数据
 * @param width    宽
 * @param height   高
 * @param quality  编码质量,取值范围为[1,100]。1 表示为最小编码质量,100 表示为最大编码质量。值越大,编码后的图片体积越大,画质越好
 * @param stream   写入编码heic数据的流
 * @param exifData exifData 数据
 * @param speed   编码档位,“slow”表示编码压缩率高速度慢,“fast”表示编码压缩率低速度快
 * @return 0 成功,其他表示失败
 */
public static int compressYuva(byte[] yuvaData, int width, int height, int quality, OutputStream stream,
                               byte[] exifData, String speed) throws IllegalArgumentException, IOException       
        
/**
 * @param rgbaData 需要编码的rgba数据
 * @param width 宽
 * @param height 高
 * @param quality 编码质量,取值范围为[1,100]。1 表示为最小编码质量,100 表示为最大编码质量。值越大,编码后的图片体积越大,画质越好
 * @param hasAlpha 是否有alpha通道
 * @param stream 写入编码heic数据的流
 * @param exifData exifData 数据
 * @param speed   编码档位,“slow”表示编码压缩率高速度慢,“fast”表示编码压缩率低速度快
 * @return true 成功, false 失败.
 */
public static boolean compressRgba(byte[] rgbaData,int width,int height,int quality,boolean hasAlpha,OutputStream stream, 
byte[] exifData, String speed) throws IllegalArgumentException, IOException     

/**
 * @param rgbData  需要编码的rgb数据
 * @param width    宽
 * @param height   高
 * @param quality  编码质量,取值范围为[1,100]。1 表示为最小编码质量,100 表示为最大编码质量。值越大,编码后的图片体积越大,画质越好
 * @param stream   写入编码heic数据的流
 * @param exifData exifData 数据
 * @param speed   编码档位,“slow”表示编码压缩率高速度慢,“fast”表示编码压缩率低速度快
 * @return 0 成功,其他表示失败
 */
public static int compressRgb(byte[] rgbData, int width, int height, int quality,
                              OutputStream stream, byte[] exifData, String speed
) throws IllegalArgumentException, IOException