audiocore
=========

作者：朱天华 陈旭东 时间：2020年08月03日

::

   脚本lib中audio库对audiocore进行了二次封装
   建议直接使用脚本lib中的audio库来设计程序
   不建议直接使用core中的audiocore库来设计程序
   本章节audiocore 接口可帮助理解脚本lib中的audio库代码

audiocore.play(audioFilePath)
-----------------------------

-  功能：播放音频文件

   ​ 音频文件格式支持：mp3、wav、amr、pcm

-  参数：

+--------+---+------------+-------------------------------------------+
| 参数   | 类 | 释义      | 取值                                      |
|        | 型 |           |                                           |
+========+===+============+===========================================+
| a      | s | 音频文件   | 如果是Luatools烧录的音频文件xxx.mp3，则文 |
| udioFi | t | 的完整路径 | 件完整路径为“lua/xxx.mp3”如果是sd卡中根目 |
| lePath | r |            | 录下的音频文件yyy.mp3，则文件完整路径为“s |
|        | i |            | dcard0/yyy.mp3”其余路径根据实际值传入即可 |
|        | n |            |                                           |
|        | g |            |                                           |
+--------+---+------------+-------------------------------------------+

-  返回值：

+----+---+------------+-------------------------------------------------+
| 返 | 类 | 释义      | 取值                                            |
| 回 | 型 |           |                                                 |
| 值 |   |            |                                                 |
+====+===+============+=================================================+
| re | b | 返回同     | false表示不允许播放true表示允许播放，并         |
| su | o | 步播放结果 | 且已经去执行播放动作；异步播放结果通过消息rtos. |
| lt | o |            | MSG_AUDIO通知到Lua脚本，消息携带参数msg.play_en |
|    | l |            | d_ind，true表示播放成功结束，其余值表示播放失败 |
+----+---+------------+-------------------------------------------------+

-  示例：

.. code:: c

   local function audioMsg(msg)
       log.info("audio.MSG_AUDIO",msg.play_end_ind)
       sys.publish("LIB_AUDIO_PLAY_IND","RESULT",msg.play_end_ind)
   end
       
   --注册core上报的rtos.MSG_AUDIO消息的处理函数
   rtos.on(rtos.MSG_AUDIO,audioMsg)
   audiocore.play("/lua/call.mp3")

audiocore.playdata(audioData,audioFormat[,audioLoop])
-----------------------------------------------------

-  功能：播放音频数据

   ​ 音频数据格式支持：mp3、wav、amr、pcm、spx

-  参数：

+------+---+---------------------+-------------------------------------+
| 参数 | 类 | 释义               | 取值                                |
|      | 型 |                    |                                     |
+======+===+=====================+=====================================+
| a    | s | 音频数据内容        |                                     |
| udio | t |                     |                                     |
| Data | r |                     |                                     |
|      | i |                     |                                     |
|      | n |                     |                                     |
|      | g |                     |                                     |
+------+---+---------------------+-------------------------------------+
| aud  | n | 音频数据格式        | audiocore.MP3audiocore.WAVaudi      |
| ioFo | u |                     | ocore.AMRaudiocore.PCMaudiocore.SPX |
| rmat | m |                     |                                     |
|      | b |                     |                                     |
|      | e |                     |                                     |
|      | r |                     |                                     |
+------+---+---------------------+-------------------------------------+
| a    | b | 是否循环播放可      | true表示循环播放fal                 |
| udio | o | 选参数，默认不循环  | se或者nil表示仅播放一次，不循环播放 |
| Loop | o |                     |                                     |
|      | l |                     |                                     |
+------+---+---------------------+-------------------------------------+

-  返回值：

+----+---+------------+-------------------------------------------------+
| 返 | 类 | 释义      | 取值                                            |
| 回 | 型 |           |                                                 |
| 值 |   |            |                                                 |
+====+===+============+=================================================+
| re | b | 返回同     | false表示不允许播放true表示允许播放，并         |
| su | o | 步播放结果 | 且已经去执行播放动作；异步播放结果通过消息rtos. |
| lt | o |            | MSG_AUDIO通知到Lua脚本，消息携带参数msg.play_en |
|    | l |            | d_ind，true表示播放成功结束，其余值表示播放失败 |
+----+---+------------+-------------------------------------------------+

-  示例：

.. code:: c

   local function audioMsg(msg)
       log.info("audio.MSG_AUDIO",msg.play_end_ind)
       sys.publish("LIB_AUDIO_PLAY_IND","RESULT",msg.play_end_ind)
   end
       
   --注册core上报的rtos.MSG_AUDIO消息的处理函数
   rtos.on(rtos.MSG_AUDIO,audioMsg)
   audiocore.play(io.readFile("/lua/call.mp3"),audiocore.MP3)    

audiocore.streamplay(audioFormat,audioData)
-------------------------------------------

-  功能：流式播放音频数据

   ​ 音频数据格式支持：mp3、wav、amr、pcm、spx

-  参数：

+-------+---+--------+-----------------------------------------------+
| 参数  | 类 | 释义  | 取值                                          |
|       | 型 |       |                                               |
+=======+===+========+===============================================+
| a     | n | 音频数 | audiocore.MP3audioco                          |
| udioF | u | 据格式 | re.WAVaudiocore.AMRaudiocore.PCMaudiocore.SPX |
| ormat | m |        |                                               |
|       | b |        |                                               |
|       | e |        |                                               |
|       | r |        |                                               |
+-------+---+--------+-----------------------------------------------+
| audi  | s | 音频数 |                                               |
| oData | t | 据内容 |                                               |
|       | r |        |                                               |
|       | i |        |                                               |
|       | n |        |                                               |
|       | g |        |                                               |
+-------+---+--------+-----------------------------------------------+

-  返回值：

==================== ====== ================== ====
返回值               类型   释义               取值
==================== ====== ================== ====
acceptedAudioDataLen number 接受的音频数据长度 
==================== ====== ================== ====

-  注意事项：

   流式播放音频数据时，在core中有一个4K字节的缓冲区，用来存放音频数据，调用audiocore.streamplay接口时，音频数据被填充到这个缓冲区内，被填充的最大长度为缓冲区的剩余字节数；例如缓冲区还剩1000字节可以填充，如果此时调用audiocore.streamplay填充3000字节数据，则实际只能将这3000字节数据的前1000字节填充到缓冲区，返回值acceptedAudioDataLen的值为1000，表示填充的字节数，剩余的2000字节被丢弃

-  示例：

.. code:: c

   local tBuffer = {}
   local tStreamType
       
   local function consumer()
       sys.taskInit(function()
           audio.setVolume(7)
           while true do
               while #tBuffer==0 do
                   sys.waitUntil("DATA_STREAM_IND")
               end
               local data = table.remove(tBuffer,1)
               --log.info("testAudioStream.consumer remove",data:len())
               local procLen = audiocore.streamplay(tStreamType,data)
               if procLen<data:len() then
                   --log.warn("produce fast")
                   table.insert(tBuffer,1,data:sub(procLen+1,-1))
                   sys.wait(5)
               end
           end
       end)
   end
       
   local function producer(streamType)
       sys.taskInit(function()
           while true do
               tStreamType = streamType
               local tAudioFile =
               {
                   [audiocore.AMR] = "tip.amr",
                   [audiocore.SPX] = "record.spx",
                   [audiocore.PCM] = "alarm_door.pcm",
               }
               local fileHandle = io.open("/lua/"..tAudioFile[streamType],"rb")
               if not fileHandle then
                   log.error("testAudioStream.producer open file error")
                   return
               end
               while true do
                   local data = fileHandle:read(streamType==audiocore.SPX and 1200 or 1024)
                   if not data then fileHandle:close() return end
                   table.insert(tBuffer,data)
                   if #tBuffer==1 then sys.publish("DATA_STREAM_IND") end
                   --log.info("testAudioStream.producer",data:len())
                   sys.wait(10)
               end 
           end
       end)
   end
       
       
   sys.timerStart(function()
       --producer(audiocore.AMR)
       --producer(audiocore.SPX)
       producer(audiocore.PCM)
       consumer()
   end,3000)

audiocore.streamremain()
------------------------

-  功能：获取core中流式播放缓冲区剩余未播放的音频流字节数

-  参数：无

-  返回值：

========= ====== ============================== ====
返回值    类型   释义                           取值
========= ====== ============================== ====
remainLen number 缓冲区剩余未播放的音频流字节数 
========= ====== ============================== ====

-  注意事项：

   流式播放音频数据时，在core中有一个4K字节的缓冲区，用来存放音频数据，调用audiocore.streamplay接口时，音频数据被填充到这个缓冲区内，audiocore.streamreamin接口的返回值是缓冲区内未播放的音频流数据字节数

-  示例：

.. code:: c

   sys.taskInit(function()
       sys.wait(5000)
       local audioData = io.readFile("/lua/tip.amr")
       --此处audiocore.streamremain()返回0
       log.info("begin streamremain",audiocore.streamremain())
       audiocore.streamplay(audiocore.AMR,audioData:sub(1,2000))
       --此处audiocore.streamremain()返回值不定，和core中rtos系统调度有关
       log.info("after streamplay 2000, streamremain",audiocore.streamremain())
       sys.wait(2000)
       --此处audiocore.streamremain()返回0
       log.info("play done, streamremain",audiocore.streamremain())
   end)

audiocore.setpa(audioClass)
---------------------------

-  功能：设置音频功放类型
-  参数：

========== ====== ============ ===================================
参数       类型   释义         取值
========== ====== ============ ===================================
audioClass number 音频功放类型 audiocore.CLASS_ABaudiocore.CLASS_D
========== ====== ============ ===================================

-  返回值：无

audiocore.getpa()
-----------------

-  功能：获取音频功放类型

-  参数：无

-  返回值：

========== ====== ============ ===================================
返回值     类型   释义         取值
========== ====== ============ ===================================
audioClass number 音频功放类型 audiocore.CLASS_ABaudiocore.CLASS_D
========== ====== ============ ===================================

audiocore.pa(gpio,devout,[plus_count],[plus_period])
----------------------------------------------------

-  功能：设置外部pa控制参数
-  参数：

+-------------+--------+---------------------+---------------------+
| 参数        | 类型   | 释义                | 取值                |
+=============+========+=====================+=====================+
| gpio        | number | gpio id             | 0到31               |
+-------------+--------+---------------------+---------------------+
| devout      | number | 音频输出通道        | 0：RECEIVER1：      |
|             |        |                     | HEADPHONE2：SPEAKER |
+-------------+--------+---------------------+---------------------+
| plus_count  | number | 输出波形个数        |                     |
|             |        | ，默认为3个可选参数 |                     |
+-------------+--------+---------------------+---------------------+
| plus_period | number | 输                  |                     |
|             |        | 出波形的时间单位us  |                     |
|             |        | ，默认为2us可选参数 |                     |
+-------------+--------+---------------------+---------------------+

-  返回值：无

audiocore.headsetinit(auto)
---------------------------

-  功能：开启耳机监测功能
-  参数：

+------+--------+----------+----------------------------------------+
| 参数 | 类型   | 释义     | 取值                                   |
+======+========+==========+========================================+
| auto | number | 控制模式 | 0：耳机插拔会有消息上报给脚本应        |
|      |        |          | 用，脚本根据消息自行处理1：耳机插拔没  |
|      |        |          | 有消息上报给脚本应用，音频通道自动切换 |
+------+--------+----------+----------------------------------------+

-  返回值：无

-  注意事项：

   当auto设置为0时，耳机插拔会有消息上报给脚本应用，上报的消息为table类型，具体参数如下：

   +-----+---+------------------+-----------------------------------------+
   | 参  | 类 | 释义            | 取值                                    |
   | 数  | 型 |                 |                                         |
   +=====+===+==================+=========================================+
   | ms  | n | 耳机消息         | 1：                                     |
   | g.t | u |                  | HEADSET_PLUGIN，耳机插入2：HEADSET_PLU  |
   | ype | m |                  | GOUT，耳机拔出3：HEADSET_BTN_DOWN，耳机 |
   |     | b |                  | 按键按下4：HEADSET_BTN_UP，耳机按键弹起 |
   |     | e |                  |                                         |
   |     | r |                  |                                         |
   +-----+---+------------------+-----------------------------------------+
   | msg | n | 当msg.type为     | UNKNOWN_MIC_TYPE =                      |
   | .pa | u | 1时，携带的参数  | 0,HEADSET_TYPE_NO_MIC =                 |
   | ram | m |                  | 1,HEADSET_TYPE_4POLE_NORMAL =           |
   |     | b |                  | 2,HEADSET_TYPE_4POLE_NOT_NORMAL =       |
   |     | e |                  | 3,HEADSET_TYPE_APPLE =                  |
   |     | r |                  | 4,HEADSET_TYPE_ERR = 5                  |
   |     |   |                  | ，目前按键功能尚不支持                  |
   +-----+---+------------------+-----------------------------------------+

-  示例：

.. code:: c

   local function headsetCB(msg)
       --log.info("audio.MSG_AUDIO",msg.type,msg.param)
   end
   --注册core上报的rtos.MSG_AUDIO消息的处理函数
   rtos.on(rtos.MSG_HEADSET,headsetCB)
       
   audiocore.headsetinit(0)

audiocore.head_plug(type)
-------------------------

-  功能：耳机配置
-  参数：

==== ====== ======== =======================================
参数 类型   释义     取值
==== ====== ======== =======================================
type number 耳机动作 0：耳机拔出1：4段耳机插入2：3段耳机插入
==== ====== ======== =======================================

-  返回值：无

audiocore.rtmpopen(url)
-----------------------

-  功能：打开rtmp拉流
-  参数：

==== ====== =============== ====
参数 类型   释义            取值
==== ====== =============== ====
url  string rtmp流的url地址 
==== ====== =============== ====

-  返回值：无

audiocore.rtmpclose()
---------------------

-  功能：关闭rtmp拉流

-  参数：无

-  返回值：无

-  注意事项：在音频播放状态下，调用audiocore.rtmpclose()后，会有一个异步消息rtos.MSG_RTMP通知到Lua脚本

audiocore.stop()
----------------

-  功能：停止音频播放

-  参数：无

-  返回值：无

-  注意事项：

   在音频播放状态下，调用audiocore.stop()后，会有一个异步消息rtos.MSG_AUDIO通知到Lua脚本，消息携带参数msg.play_end_ind的值为false，表示播放失败；

   无音频播放状态下，调用audiocore.stop()后，没有任何消息通知到Lua脚本