updata audio doc

docs/doc/en/audio/play.md

@@ -24,7 +24,49 @@ Note: If the `MaixCAM` has copper posts attached to these pins, they can be sold
 
 ### Code
 
-Method of playing a PCM file
+#### Playing a `WAV` file
+
+```python
+from maix import audio, time, app
+
+p = audio.Player("/root/output.wav")
+
+p.play()
+
+while not app.need_exit():
+    time.sleep_ms(10)
+print("play finish!")
+```
+
+Steps：
+
+
+1. Import the audio, time and app modules:
+
+   ```python
+   from maix import audio, time, app
+   ```
+
+2. Initialize the player:
+
+   ```python
+   p = audio.Player("/root/output.wav")
+   ```
+  - Note that the default sample rate is 48k, the sample format is little-endian format - signed 16-bit, and the sample channel is 1. You can also customise the parameters like this `p = audio.Player(sample_rate=48000, format=audio.Format.FMT_S16_LE, channel = 1)`. So far only tested with sample rate 48000, format `FMT_S16_LE`, and number of sampling channels 1.
+  - If it is a `.wav` file, the sample rate, sample format and sample channel are automatically obtained.
+
+3. Playing audio
+
+   ```python
+   p.play()
+   ```
+
+  - This will block until all audio data is written, but not until all audio data is actually played. If you exit the programme after calling `play()`, some of the audio data to be played may be lost.
+
+4. Done
+
+
+#### Playback with `PCM` data
 
 ```python
 from maix import audio, time, app
@@ -60,18 +102,32 @@ Steps：
 
 3. Open and playback a PCM file
 
-  ```python
-  with open('/root/output.pcm', 'rb') as f:
-      ctx = f.read()
-
-  p.play(bytes(ctx))
+   ```python
+     with open('/root/output.pcm', 'rb') as f:
+         ctx = f.read()
+
+     p.play(bytes(ctx))
+
+     while not app.need_exit():
+       time.sleep_ms(10)
+   ```
 
-  while not app.need_exit():
-    time.sleep_ms(10)
-  ```
   - `with open(‘xxx’,‘rb’) as f:` open file `xxx` and get file object `f`
   - `ctx = f.read()` reads the contents of the file into `ctx`
   - `p.play(bytes(ctx))` plays the audio, `p` is the opened player object, `ctx` is the `PCM` data converted to type bytes
   - `time.sleep_ms(10)` Here there is a loop to wait for the playback to complete, as the playback operation is performed asynchronously, and if the program exits early, then it may result in the audio not being played completely.
 
-4. Done
+4. Done
+
+### Other
+
+The `Player` and `Recorder` modules have some `bugs` to be worked out, make sure they are created before other modules (`Camera` module, `Display` module, etc.). For example:
+
+```python
+# Create Player and Recorder first.
+p = audio.Player()
+r = audio.Recorder()
+
+# Then create the Camera
+c = camera.Camera()
+```

docs/doc/en/audio/record.md

@@ -9,11 +9,15 @@ update:
 
 ## Introduction
 
-This document provides methods for recording
+This document provides the usage of audio recording and supports recording audio in `PCM` and `WAV` formats.
+
+The `MaixCAM` has a microphone on board, so you can use the recording function directly.
 
 ### How to use
 
-An example of a recording
+#### Getting `PCM` data
+
+If you don't pass `path` when constructing a `Recorder` object, it will only record audio and not save it to a file, but you can save it to a file manually.
 
 ```python
 from maix import audio, time, app
@@ -56,6 +60,59 @@ Steps：
    data = r.record()
    ```
 
-   - `data` is `bytes` type data in `PCM` format that holds the currently recorded audio. The `PCM` format is set when initialising the `Recorder` object, see step 2.
+   - `data` is `bytes` type data in `PCM` format that holds the currently recorded audio. The `PCM` format is set when initialising the `Recorder` object, see step 2. Note that if the recording is too fast and there is no data in the audio buffer, it is possible to return an empty `bytes` of data.
 
 4. Done, you can do voice processing on the `PCM` data returned by `r.record()` when doing your own applications.
+
+#### Records audio and saves it in `WAV` format.
+
+If you pass `path` when constructing a `Recorder` object, the recorded audio will be saved to a `path` file, and you can also get the currently recorded `PCM` data via the `record` method. `path` only supports paths with `.pcm` and `.wav` suffixes, and the `record` method does not return `WAV` headers when recording `.wav`, it only returns `PCM` data.
+
+```python
+from maix import audio, time, app
+
+r = audio.Recorder("/root/output.wav")
+r.volume(12)
+print("sample_rate:{} format:{} channel:{}".format(r.sample_rate(), r.format(), r.channel()))
+
+while not app.need_exit():
+    data = r.record()
+    print("data size", len(data))
+
+    time.sleep_ms(10)
+
+print("record finish!")
+```
+
+The code means basically the same as above.
+
+#### Record audio and save to `WAV` format (blocking)
+
+If the `record_ms` parameter is set during recording, recording audio will block until the time set by `record_ms` is reached, unit: ms.
+
+```python
+from maix import audio, time, app
+
+r = audio.Recorder("/root/output.wav")
+r.volume(12)
+print("sample_rate:{} format:{} channel:{}".format(r.sample_rate(), r.format(), r.channel()))
+
+r.record(5000)
+
+print("record finish!")
+```
+
+The above example will keep recording `5000`ms and save it to `WAV` format, during the recording period it will block in `record` method, note that `PCM` data will not be returned when `record` is set to `record_ms`.
+
+### Other
+
+The `Player` and `Recorder` modules have some `bugs` to be worked out, make sure they are created before other modules (`Camera` module, `Display` module, etc.). For example:
+
+```python
+# Create Player and Recorder first.
+p = audio.Player()
+r = audio.Recorder()
+
+# Then create the Camera
+c = camera.Camera()
+```

docs/doc/zh/audio/play.md

@@ -12,8 +12,6 @@ update:
 本文档提供播放音频的使用方法
 
 
-
-
 ## 使用方法
 
 ### 硬件操作
@@ -26,7 +24,51 @@ update:
 
 ### 编写代码
 
-播放一个PCM文件的方法
+#### 播放一个`WAV`文件
+
+```python
+from maix import audio, time, app
+
+p = audio.Player("/root/output.wav")
+
+p.play()
+
+while not app.need_exit():
+    time.sleep_ms(10)
+print("play finish!")
+```
+
+步骤：
+
+
+1. 导入audio、time和app模块
+
+   ```python
+   from maix import audio, time, app
+   ```
+
+2. 初始化播放器
+
+   ```python
+   p = audio.Player("/root/output.wav")
+   ```
+
+  - 默认的采样率是48k，采样格式为小端格式-有符号16位，采样通道为1。你也可以像这样自定义参数`p = audio.Player(sample_rate=48000, format=audio.Format.FMT_S16_LE, channel = 1)`。目前只测试过采样率48000，`FMT_S16_LE`格式，和采样通道数为1。
+  - 如果是`.wav`文件，则会自动获取采样率、采样格式和采样通道。
+
+3. 播放音频
+
+   ```python
+   p.play()
+   ```
+
+  - 该将会阻塞直到写入所有音频数据，但不会阻塞到实际播放完所有音频数据。如果调用`play()`后退出了程序，则部分待播放的音频数据可能会丢失。
+
+4. 完成
+
+
+
+#### 用`PCM`数据播放
 
 ```python
 from maix import audio, time, app
@@ -62,18 +104,34 @@ print("play finish!")
 
 3. 打开并播放一个PCM文件
 
-  ```python
-  with open('/root/output.pcm', 'rb') as f:
-      ctx = f.read()
-
-  p.play(bytes(ctx))
+   ```python
+     with open('/root/output.pcm', 'rb') as f:
+         ctx = f.read()
+
+     p.play(bytes(ctx))
+
+     while not app.need_exit():
+       time.sleep_ms(10)
+   ```
 
-  while not app.need_exit():
-    time.sleep_ms(10)
-  ```
   - `with open('xxx','rb') as f:`打开文件`xxx`， 并获取文件对象`f`
   - `ctx = f.read()`将读取文件的内容到`ctx`中
   - `p.play(bytes(ctx))`播放音频，`p`是已打开的播放器对象， `ctx`是转换为bytes类型的`PCM`数据
   - `time.sleep_ms(10)`这里有一个循环来等待播放完成，因为播放操作是异步执行的，如果提前退出了程序，那么可能导致音频不会完全播放。
 
-4. 完成
+4. 完成
+
+
+
+### 其他
+
+`Player`和`Recorder`模块有些`bug`待解决，请保证它们在其他模块（`Camera`模块，`Display`模块等）之前创建。例如：
+
+```python
+# 先创建Player和Recorder
+p = audio.Player()
+r = audio.Recorder()
+
+# 再创建Camera
+c = camera.Camera()						
+```

docs/doc/zh/audio/record.md

@@ -9,13 +9,15 @@ update:
 
 ## 简介
 
-本文档提供录音的使用方法
-
+本文档提供录音的使用方法，支持录入`PCM`和`WAV`格式的音频。
 
+`MaixCAM`板载了麦克风，所以你可以直接使用录音功能。
 
 ### 使用方法
 
-一个录音的示例
+####  获取`PCM`数据
+
+当构造`Recorder`对象时不传入`path`， 则只会录入音频后不会保存到文件中，当然你可以手动保存到文件。
 
 ```python
 from maix import audio, time, app
@@ -47,9 +49,9 @@ print("record finish!")
    r = audio.Recorder()
    r.volume(12)
    ```
-   
+
      - 注意默认的采样率是48k，采样格式为小端格式-有符号16位，采样通道为1。你也可以像这样自定义参数`p = audio.Recorder(sample_rate=48000, format=audio.Format.FMT_S16_LE, channel = 1)`。目前只测试过采样率48000，`FMT_S16_LE`格式，和采样通道数为1
-   
+
      - `r.volume(12)`用来设置音量，音量范围为[0,24]
 
 3. 开始录制
@@ -58,6 +60,62 @@ print("record finish!")
    data = r.record()
    ```
 
-   - `data`是`PCM`格式的`bytes`类型数据，保存了当前录入的音频。`PCM`格式在初始化`Recorder`对象时设置，见步骤2.
+   - `data`是`PCM`格式的`bytes`类型数据，保存了当前录入的音频。`PCM`格式在初始化`Recorder`对象时设置，见步骤2。注意如果录制太快，音频缓冲区没有数据， 则有可能返回一个空的`bytes`数据。
 
 4. 完成，做自己的应用时可以对`r.record()`返回的`PCM`数据做语音处理。
+
+
+
+#### 录制音频并保存为`WAV`格式
+
+当构造`Recorder`对象时传入了`path`， 则录入的音频将会保存到`path`文件中，并且你也可以通过`record`方法获取当前录入的`PCM`数据。`path`只支持`.pcm`和`.wav`后缀的路径，并且当录入`.wav`时，`record`方法不会返回`WAV`头部信息，只会返回`PCM`数据。
+
+```python
+from maix import audio, time, app
+
+r = audio.Recorder("/root/output.wav")
+r.volume(12)
+print("sample_rate:{} format:{} channel:{}".format(r.sample_rate(), r.format(), r.channel()))
+
+while not app.need_exit():
+    data = r.record()
+    print("data size", len(data))
+
+    time.sleep_ms(10)
+
+print("record finish!")
+```
+
+代码含义基本同上。
+
+
+
+#### 录制音频并保存为`WAV`格式（阻塞）
+
+录入时如果设置了`record_ms`参数，录入音频会阻塞直到到达`record_ms`设置的时间，单位ms。
+
+```python
+from maix import audio, time, app
+
+r = audio.Recorder("/root/output.wav")
+r.volume(12)
+print("sample_rate:{} format:{} channel:{}".format(r.sample_rate(), r.format(), r.channel()))
+
+r.record(5000)
+print("record finish!")
+```
+
+上面示例将会持续录入`5000`ms，并保存为`WAV`格式，录入期间将会阻塞在`record`方法中，注意当`record`设置了`record_ms`后不会返回`PCM`数据。
+
+### 其他
+
+`Player`和`Recorder`模块有些`bug`待解决，请保证它们在其他模块（`Camera`模块，`Display`模块等）之前创建。例如：
+
+```python
+# 先创建Player和Recorder
+p = audio.Player()
+r = audio.Recorder()
+
+# 再创建Camera
+c = camera.Camera()
+```