音頻系統核心庫的穩定運行，是實現低延遲、高保真音頻體驗的前提。其內部通過精密的線程調度、緩沖區管理與設備驅動交互，保障音頻數據的連續性與同步性。本文將聚焦其運行機制，逐層拆解關鍵技術要點，幫助開發者洞察音頻系統背后的工程智慧。

一、概述

audio 核心庫 是指 LuatOS 通過對 es8311 或者 TM8211 編解碼器進行配置以及傳輸，從而實現錄音，播放音頻，播放 TTS（文字轉語音）功能，由于此核心庫開發較早，歷史包袱導致參數過多，使用非常不方便，建議使用exaudio擴展庫。

重要概念解釋：

1.1 硬件 DAC&ADC

也常稱為 codec(編碼器) ，decoder(解碼器) 音頻的編解碼芯片，目前僅支持"es8311"，"TM8211"，其中 es8311 支持 模擬音頻轉數據音頻的輸入，即為錄音，也支持數據音頻轉為模擬音頻的輸出，即為播放。

1.2采樣率：

決定 “聲音會不會漏了高頻細節”（比如沒抓住小鳥叫），采樣率越高，細節越豐富，但是占用的空間也越大

1.3 位深：

決定 “聲音的音量變化會不會生硬”（比如能不能分清小聲說話和輕聲咳嗽），使用 bit 表示，表示單次采樣，模擬量使用數據量保存的位數，位數越高質量越高，占用空間越大

1.4 流式播放

一邊傳輸音頻數據，一邊進行播放，適合一些對實時性要求較高的場景，或者需要對音頻進行編碼的場景

1.5 流式錄音

一邊錄音，一邊上傳數據，適合對錄音實時性要求較高或者需要對音頻進行編碼的場景。

1.6 es8311 和 TM8211 的區別

es8311 支持音頻的編碼和解碼，即支持錄音和播放，如果需要打電話，則需要使用 es8311

TM8211 僅支持音頻的解碼，即支持播放

es8311 相對于 TM8211 需要一路 I2C 作為信令的收發，因此電路上 TM8211 要更為簡單.

780EHV 模塊內部集成了 es8311，方便大家使用音頻相關功能，并使用 GPIO20 控制 es8311 的使能；Air8000 以及 Air780 系列其他型號內部不含 es8311，需要外掛，

1.7 audio、exaudio、codec 三個庫文件的區別和聯系

audio、codec 是核心庫，可以調用的最底層的代碼，exaudio 是擴展庫

audio 庫和 exaudio 庫都是實現了錄音和播放，但是 exaudio 使用更加簡單，去掉了歷史原因造成的 audio 的冗余參數

codec 庫 是實現了音頻數據的編碼和解碼，不會對音頻直接播放，audio 和 exaudio 可以對編解碼后的音頻進行播放

1.8 audio 核心庫使用相關組合關系圖

如圖所示，audio 核心庫大致可以分為如下幾種組合關系，用戶可根據所需功能自行搭配

二、核心示例

1、核心示例是指：使用本庫文件提供的核心 API，開發的基礎業務邏輯的演示代碼；

2、核心示例的作用是：幫助開發者快速理解如何使用本庫，所以核心示例的邏輯都比較簡單；

3、由于 audio 核心庫使用起來比較復雜，所以目前已經不推薦使用 audio 核心庫，而是推薦使用 exaudio 擴展庫來開發音頻應用

4、此處僅僅簡單地列舉 audio 核心庫中少數 api 的使用方法，供大家學習理解使用

三、常量詳解

這些常量用于 audio 庫的各種配置和操作，在腳本代碼中不需要聲明，可直接調用。

3.1 音頻格式常量

這些常量用于指定音頻數據的格式：

audio.PCM

3.2 音頻事件常量

這些常量用于 audio.on() 回調函數中的事件類型

audio.MORE_DATA

audio.DONE

audio.RECORD_DATA

audio.RECORD_DONE

3.3 休眠模式常量

這些常量用于 audio.pm() 函數的休眠模式

audio.RESUME

audio.STANDBY

audio.SHUTDOWN

audio.POWEROFF

四、函數詳解

4.1 配置相關

配置相關函數用于音頻硬件配置、參數設置和事件注冊。

audio.config(id, paPin, onLevel, dacDelay, paDelay, dacPin, dacLevel, dacTimeDelay)

功能

配置音頻硬件參數。

參數

id

paPin

onLevel

dacDelay

paDelay

dacPin

dacLevel

dacTimeDelay

返回值

無

示例

audio.setBus(id, bus_type, config_table)

功能

配置音頻 DAC（編解碼器）

參數

id

bus_type

config_table

返回值

local result = audio.setBus(id, bus_type, config_table)

result

例子

audio.vol(id, value)

功能

設置播放音量

參數

id

value

返回值

local result = audio.vol(id, value)

result

例子

audio.micVol(id, value)

功能

設置 mic 音量

參數

id

value

返回值

local result = audio.micVol(id, value)

result

例子

audio.on(id, callback)

功能

注冊音頻事件回調函數

參數

id

callback

返回值

無

例子

audio.pm(id,pm_mode)

功能

休眠控制（一般會自動調用 RESUME 模式）

參數

id

pm_mode

返回值

local result = audio.pm(id,pm_mode)

result

例子

4.2 檢查相關

檢查相關函數用于獲取音頻狀態、錯誤信息和調試信息。

audio.getError(id)

功能

獲取最近一次播放結果

參數

id

返回值

local result = audio.getError(id)

result

user_stop

file_no

例子

audio.isEnd(id)

功能

檢查音頻通道是否播放結束

參數

id

返回值

local result = audio.isEnd(id)

result

例子

audio.debug(on_off)

功能

配置調試信息輸出

參數

on_off

返回值

無

例子

4.3 播放相關

播放相關函數，用于音頻播放控制。

audio.play(id, path, errStop)

功能

播放音頻文件或者停止播放（可以是文件或 TTS）

注意事項：

1、播放完成后，會回調一個 audio.DONE 消息

2、可以用 pause 來暫停或者恢復

3、audio.play(0) 即為停止播放，可以停止文件或 TTS

參數

id

path

errStop

返回值

local result = audio.play(id, path, errStop)

result

例子

audio.pause(id, pause)

功能

暫停或恢復播放

參數

id

pause

返回值

local result = audio.pause(id, pause)

result

例子

audio.playStop(id)

功能

停止播放音頻文件，等同于 audio.play(id)

參數

id

返回值

local result = audio.playStop(id)

result

例子

audio.tts(id, text)

功能

播放或暫停播放 TTS 文本轉語音

參數

id

text

返回值

local result = audio.tts(id, text)

result

例子

audio.start(id,audio_format, num_channels, sample_rate, bits_per_sample, is_signed)

功能

啟動一個音頻通道，僅用于流式播放。

參數

id

audio_format

num_channels

sample_rate

bits_per_sample

is_signed

返回值

local result = audio.start(id, audio_format, num_channels, sample_rate, bits_per_sample, is_signed)

result

示例

audio.write(id, data)

功能

向音頻通道中寫入音頻數據，用于播放

參數

id

data

返回值

local result = audio.write(id, data)

result

示例

audio.finish(id)

功能

寫入最后一塊數據后，通知多媒體通道已經沒有更多數據需要播放了

參數

id

返回值

local result = audio.finish(id)

result

示例

audio.stop(id)

功能

停止指定的多媒體通道

參數

id

返回值

local result = audio.stop(id)

result

示例

audio.record(id, record_type, record_time, amr_quailty, path, nil, buff0, buff1,channelCount)

功能

錄音

參數

id

record_type

record_time

amr_quailty

path

reserved

buff0

buff1

返回值

local result = audio.record(id, record_type, record_time, amr_quailty, path, nil, buff0, buff1,channelCount)

result

示例 1: 錄制到文件

示例 2: 流式錄音

audio.recordStop(id)

功能

停止錄音

注意：audio 的回調函數返回 audio.RECORD_DONE 的 event 才是真正的結束

參數

id

返回值

local result = audio.recordStop(id)

result

示例

五、模組支持說明

780EHM，780EHV，780EGH，780EGG，以及 8000 全系列均支持；

780EPM，780EGP，700ECP 不支持。

724，722，720，820，795 也不支持。

今天的內容就分享到這里了~

審核編輯 黃宇