跳转至

codec 核心库

作者：梁健

一、概述

Codec 核心库 是合宙的软件编解码库，可以实现不同的音频格式相互转换，以适应平台格式要求，流量控制，或者播放器的要求

1.1 audio,exaudio,codec 三个库文件的区别和联系

  1. audio,codec,是核心库，可以调用的最底层的代码，exaudio 是扩展库
  2. audio 库和 exaudio 库都是实现了录音和播放，但是 exaudio 使用更加简单，去掉了历史原因造成的 audio 的荣冗余参数
  3. codec 库 是实现了音频数据的编码和解码，不会对音频直接播放，audio 和 exaudio 可以对编解码后的音频进行播放

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的相关示例:demo/codec：

-- 解码
local decoder = codec.create(codec.MP3, true)  -- 初始化解码器
codec.info(decoder ,"/luadb/1.mp3")   --需要解码的文件解析
local decode_buffer = zbuff.create(54594)   --创建一个可以存放音频的缓存
local decode_result = codec.data(decoder , decode_buffer,4096)  -- 使用默认编码等级0
codec.release(decoder ) --  关闭解码器并释放资源

-- 编码
local encoder= codec.create(codec.AMR,false)  -- 初始化编码器
local encode_result = codec.encode(encoder, in_buffer, out_buffer, 0)  -- 开始编码
codec.release(encoder) --  关闭编码器并释放资源

三、常量详解

核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用； | 常量 | 类型 | 解释 | 参数示例 | | ------------ | ------ | ------------------------------------------ | ------------------------------------------------------------ | | codec.MP3 | number | MP3格式，仅支持解码 | local decoder = codec.create(codec.MP3, true) -- 初始化解码器 | | codec.AMR | number | AMR_NB格式，支持编解码 | local encoder = codec.create(codec.AMR, false, 7) | | codec.AMR_WB | number | AMR_WB格式，仅在支持volte 的固件支持编解码 | local encoder = codec.create(codec.AMR_WB, false, 8)--创建一个amr-wb的encoder，编码等级默认8 | | codec.ULAW | number | G711 μ-law格式 | local encoder = codec.create(codec.ALAW, false) --开启G711 μ-law 编码器 | | codec.ALAW | number | G711 A-law格式 | local encoder = codec.create(codec.ALAW, false) --开启G711 A-law 编码器 |

四、函数详解

4.1 codec.create(type, isDecoder, quality)

功能

创建编解码器

参数

type

参数含义：需要编解码的目标格式；
数据类型：number；
取值范围：codec.MP3,codec.AMR,codec.AMR_WB,codec.ULAW,codec.ALAW；
是否必选：必须传入此参数；
注意事项：
        1. 编码支持codec.AMR,codec.AMR_WB,codec.ULAW,codec.ALAW；
        2. 解码支持codec.MP3,codec.AMR,codec.AMR_WB,codec.ULAW,codec.ALAW；
参数示例：codec.AMR,编码或者解码为codec.AMR 格式的音频 ；

isDecoder

参数含义：是否为解码器；
数据类型：boolean；
取值范围：true,false；
是否必选：必须传入此参数；
注意事项：true为解码器，false为编码器；
参数示例：true 表示解码器；

quality

参数含义：编码等级；
数据类型：number；
取值范围：0-7或0-8；
是否必选：非必须传入此参数；
注意事项：
        1. 当codec.create 的 type 为codec.AMR，取值范围是 0~7 值越大消耗的空间越多(0，2.11MB/小时，7，5.49MB/小时),音质越高,默认0 
        2. 当codec.create 的 type 为codec.AMR_WB，取值范围是 0~8,值越大消耗的空间越多(0，2.97MB/小时，7，10.73MB/小时),音质越高,默认0
        3. 默认为0，如果填入此值，则必须和codec.encode的**quality**保持一致
参数示例：0，音频质量为最差；

返回值

参数含义：codec.creat 的返回值；
数据类型：userdata 或 nil；
取值范围：对象；
是否必选：必须传入此参数；
注意事项：如果创建失败，则返回nil；

示例

-- 创建解码器
local decoder = codec.create(codec.MP3)--创建一个mp3的decoder
-- 创建编码器
local encoder = codec.create(codec.AMR, false)--创建一个amr的encoder
-- 创建编码器
local encoder = codec.create(codec.AMR_WB, false, 8)--创建一个amr-wb的encoder，音频等级为8

4.2 codec.info(decoder, file_path)

功能

从文件中解析出音频信息，仅仅在解码模式下可用

参数

decoder

参数含义：解码器的对象（codec.create 返回值）；
数据类型：userdata；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：codec.create 必须使用解码模式
参数示例：无 ；

file_path

参数含义：音频文件路径；
数据类型：string；
取值范围：无特别限制，
是否必选：必须传入此参数；
注意事项：该文件必须存在，并且没被其他task 占用
参数示例："/luadb/xxx.mp3",xxx.mp3 音频信息 ；

返回值

local result, audio_format, num_channels, sample_rate, bits_per_sample, is_signed= codec.info(coder, "xxx")

**result **

参数含义：是否解析成功；
数据类型：boolean；
取值范围：true,false；
是否必选：必须接收此参数；
注意事项：true 表示解析成功，false 表示解析失败

audio_format

参数含义：音频格式；
数据类型：number；
取值范围：1.pcm, 2.mp3, 4.amr_nb, 5.amr_wb, 6.G711 ULAW, 7.G711 ALAW；
是否必选：必须接收此参数；

num_channels

参数含义：声音通道数；
数据类型：number；
取值范围：>0；
是否必选：必须接收此参数；

sample_rate

参数含义：采样频率；
数据类型：number；
取值范围：8000,16000,24000,32000,48000,20050,44100；
是否必选：必须接收此参数；

is_signed

参数含义：是否有符号；
数据类型：boolean；
取值范围：true:有符号,false:无符号；
是否必选：必须接收此参数；

示例

local result, audio_format, num_channels, sample_rate, bits_per_sample, is_signed= codec.info(coder, "xxx")

4.3 codec.data(decoder, out_buff,size)

功能

从文件中解析出原始音频数据，比如从 MP3 文件里解析出 PCM 数据，这里的文件路径已经在 codec.info 传入，不需要再次传入

参数

decoder

参数含义：需要解码的对象（codec.create 返回值）；
数据类型：userdata；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：codec.create 必须使用解码模式
参数示例：无 ；

out_buff

参数含义：存放输出数据的zbuff；
数据类型：zbuff；
取值范围：zbuff 的 空间需要大于等于16K(过小的数据可能导致解码后播放不流畅)，；
是否必选：必须传入此参数；
注意事项：无特别要求

size

参数含义：最少解码出多少字节的音频数据；
数据类型：number；
取值范围：> 0 ；
是否必选：非必须传入此参数；
注意事项：默认值为16384

返回值

成功 true， 失败 false

示例

local buff = zbuff.create(16*1024)
local result = codec.data(coder, buff，4096)

4.4 codec.encode(encode, in_buffer, out_buffer, quality)

功能

编码音频数据

参数

encode

参数含义：使用编码器的对象（codec.create 返回值）；
数据类型：userdata；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：codec.create 必须使用编码模式
参数示例：无 ；

in_buffer

参数含义：需要编码的源数据；
数据类型：zbuff；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：无
参数示例：无 ；

out_buffer

参数含义：编码后输出数据的位置；
数据类型：zbuff；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：自动添加到buff的尾部,如果空间大小不足,会自动扩展,但是会额外消耗时间,甚至会失败,所以尽量一开始就给足空间
参数示例：无 ；

quality

参数含义：音频质量等级；
数据类型：int；
取值范围：0~7 或者0~8；
是否必选：非必须传入此参数；
注意事项：
        1. 当codec.create 的 type 为codec.AMR，取值范围是 0~7 值越大消耗的空间越多(0，2.11MB/小时，7，5.49MB/小时),音质越高,默认0 
        2. 当codec.create 的 type 为codec.AMR_WB，取值范围是 0~8,值越大消耗的空间越多(0，2.97MB/小时，7，10.73MB/小时),音质越高,默认0
        3. 默认为0，如果填入此值，则必须和codec.create 的quality 保持一致
参数示例：0，音频质量为最差；

返回值

成功 true， 失败 false

示例

codec.encode(amr_coder, inbuf, outbuf)

4.5 codec.release(coder)

功能

释放创建的编解码器

参数

decoder

参数含义：编解码器的对象（codec.create 返回值）；
数据类型：userdata；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：需要先用codec.create创建对象
参数示例：无 ；

返回值

成功 true， 失败 false

示例

codec.release(coder)

五、产品支持说明

支持 LuatOS 开发的 Air780xx,Air8000xx 产品都支持 codec 库。