音频模块 API 手册#

概述#

本手册旨在详细介绍 CanMV 音频模块,指导开发人员如何通过调用 Python API 接口实现音频的采集与播放功能。

API 介绍#

wave#

wave 模块提供了一种简便的方法来读取和处理 WAV 文件。

  • wave.open 函数可以打开 WAV 文件并返回相应的类对象。

  • wave.Wave_read 类提供获取 WAV 文件的元数据(如采样率、采样点、声道数和采样精度)以及从文件读取 WAV 音频数据的方法。

  • wave.Wave_write 类提供设置 WAV 文件的元数据(如采样率、采样点、声道数和采样精度)以及保存 PCM 音频数据到 WAV 文件的方法。

该模块与 pyaudio 模块结合使用,可以轻松实现 WAV 文件音频的播放与采集及保存 WAV 音频文件。

open#

描述

打开 WAVE 文件,以读取或写入音频数据。

语法

open(f, mode=None)

参数

参数名称

描述

输入 / 输出

f

文件名称

输入

mode

打开模式 (‘r’, ‘rb’, ‘w’, ‘wb’)

输入

返回值

返回值

描述

Wave_read 或 Wave_write 类对象

成功

其他

失败,抛出异常

wave.Wave_read#

Wave_read 类提供获取 WAV 文件的元数据(如采样率、采样点、声道数和采样精度)以及从文件读取 WAV 音频数据的方法。

get_channels#

描述

获取声道数。

语法

get_channels()

参数

返回值

返回值

描述

>0

成功

0

失败

get_sampwidth#

描述

获取采样字节长度。

语法

get_sampwidth()

参数

返回值

返回值

描述

>0 (有效范围 [1, 2, 3, 4] 分别对应采样精度 [8, 16, 24, 32])

成功

0

失败

get_framerate#

描述

获取采样频率。

语法

get_framerate()

参数

返回值

返回值

描述

>0 (有效范围 (8000~192000))

成功

0

失败

read_frames#

描述

读取帧数据。

语法

read_frames(nframes)

参数

参数名称

描述

输入 / 输出

nframes

读取的帧长度(声道数 × 每个采样点的采样精度 / 8 )

输入

返回值

返回值

描述

bytes 字节序列

wave.Wave_write#

Wave_write 类提供设置 WAV 文件的元数据(如采样率、采样点、声道数和采样精度)以及保存 PCM 音频数据到 WAV 文件的方法。

set_channels#

描述

设置声道数。

语法

set_channels(nchannels)

参数

参数名称

描述

输入 / 输出

nchannels

声道数

输入

返回值

set_sampwidth#

描述

设置采样字节长度。

语法

set_sampwidth(sampwidth)

参数

参数名称

描述

输入 / 输出

sampwidth

采样字节长度,有效范围 [1, 2, 3, 4] 分别对应采样精度 [8, 16, 24, 32]

输入

返回值

set_framerate#

描述

设置采样频率。

语法

set_framerate(framerate)

参数

参数名称

描述

输入 / 输出

framerate

采样频率 [8000~192000]

输入

返回值

write_frames#

描述

写入音频数据。

语法

write_frames(data)

参数

参数名称

描述

输入 / 输出

data

音频数据( bytes 字节序列)

输入

返回值

pyaudio#

pyaudio 模块用于音频处理,负责采集和播放二进制 PCM 音频数据。如需播放 WAV 格式文件或将采集到的数据保存为 WAV 文件,需与 wave 库结合使用,详见 示例程序 部分。

pyaudio.PyAudio#

负责管理多路音频输入和输出通路,每路通路均以流( Stream)类对象体现。

open#

描述

打开一路流( Stream)。

语法

open(*args, **kwargs)

参数

可变参数,参考 [Stream.__init__]。

返回值

返回值

描述

py:class:Stream

成功

其他

失败,抛出异常

close#

描述

关闭一路流( Stream)。

语法

close(stream)

参数

返回值

注意

该函数会调用 Stream 对象中的 close 方法,并将 Stream 对象从 PyAudio 对象中删除。因此,该函数可以不调用,直接调用 Stream.close 方法即可。

terminate#

描述

释放音频资源。在 PyAudio 不再使用时,一定要调用该函数以释放音频资源。如在默认构造函数中申请了 vb block,则应在该函数中释放 vb block。

语法

terminate()

参数

返回值

注意

该函数会调用 Stream 对象中的 close 方法,并将 Stream 对象从 PyAudio 对象中删除。因此,该函数可以不调用,直接调用 Stream.close 方法即可。

pyaudio.Stream#

Stream 类对象用于管理一路音频输入或输出通路。

__init__#

描述

构造函数。

语法

__init__(
            PA_manager,
            rate,
            channels,
            format,
            input=False,
            output=False,
            input_device_index=None,
            output_device_index=None,
            enable_codec=True,
            frames_per_buffer=1024,
            start=True,
            stream_callback=None)

参数

参数名称

描述

输入 / 输出

PA_manager

PyAudio 类对象

输入

rate

采样率

输入

channels

声道数

输入

format

采样点字节数

输入

input

是否为音频输入,默认值为 False

输入

output

是否为音频输出,默认值为 False

输入

input_device_index

输入通路索引 [0,1],默认值为 None(使用默认通路 0 )

输入

output_device_index

输出通路索引 [0,1],默认值为 None(使用默认通路 0 )

输入

enable_codec

是否启用编码,默认值为 True

输入

frames_per_buffer

每个缓冲区的帧数

输入

start

是否立即启动,默认值为 True

输入

stream_callback

输入 / 输出回调函数

输入

返回值

start_stream#

描述

启动流。

语法

start_stream()

参数

返回值

stop_stream#

描述

停止流。

语法

stop_stream()

参数

返回值

read#

描述

读取音频数据。

语法

read(frames)

参数

参数名称

描述

输入 / 输出

frames

帧数

输入

返回值

返回值

描述

bytes

读取的音频数据

write#

描述

写入音频数据。

语法

write(data)

参数

参数名称

描述

输入 / 输出

data

音频数据( bytes 字节序列)

输入

返回值

volume#

描述

获取或设置音量。

语法

volume(vol = None, channel = LEFT_RIGHT)

参数

参数名称

描述

输入 / 输出

vol

设置音量值

输入

channel

声道选择:LEFT(左声道),RIGHT(右声道),LEFT_RIGHT(左右声道)

输入

返回值

设置音量时,返回值:无 获取音量时,返回值:‌tuple

enable_audio3a#

描述

使能音频3a。

语法

enable_audio3a(audio3a_value)

参数

参数名称

描述

输入 / 输出

audio3a_value

音频3a使能项:AUDIO_3A_ENABLE_ANS(音频降噪),UDIO_3A_ENABLE_AGC(自动增益),AUDIO_3A_ENABLE_AEC(回声抑制)

输入

返回值

audio3a_send_far_echo_frame#

描述

发送远端参考语音(即近端扬声器播放的语音),仅在音频3a中回声抑制(AEC)场景使用。

语法

audio3a_send_far_echo_frame(frame_data,data_len)

参数

参数名称

描述

输入 / 输出

frame_data

远端参考语音数据( bytes 字节序列)

输入

data_len

数据长度

输入

返回值

示例程序#

采集音频并保存为 WAV 文件示例#

import os
from media.media import *   #导入media模块,用于初始化vb buffer
from media.pyaudio import * #导入pyaudio模块,用于采集和播放音频
import media.wave as wave   #导入wav模块,用于保存和加载wav音频文件

def exit_check():
    try:
        os.exitpoint()
    except KeyboardInterrupt as e:
        print("user stop: ", e)
        return True
    return False

def record_audio(filename, duration):
    CHUNK = 44100//25  #设置音频chunk值
    FORMAT = paInt16       #设置采样精度,支持16bit(paInt16)/24bit(paInt24)/32bit(paInt32)
    CHANNELS = 2           #设置声道数,支持单声道(1)/立体声(2)
    RATE = 44100           #设置采样率

    try:
        p = PyAudio()
        p.initialize(CHUNK)    #初始化PyAudio对象
        MediaManager.init()    #vb buffer初始化

        #创建音频输入流
        stream = p.open(format=FORMAT,
                        channels=CHANNELS,
                        rate=RATE,
                        input=True,
                        frames_per_buffer=CHUNK)

        stream.volume(vol=70, channel=LEFT)
        stream.volume(vol=85, channel=RIGHT)
        print("volume :",stream.volume())

        #启用音频3A功能:自动噪声抑制(ANS)
        stream.enable_audio3a(AUDIO_3A_ENABLE_ANS)

        frames = []
        #采集音频数据并存入列表
        for i in range(0, int(RATE / CHUNK * duration)):
            data = stream.read()
            frames.append(data)
            if exit_check():
                break
        #将列表中的数据保存到wav文件中
        wf = wave.open(filename, 'wb') #创建wav 文件
        wf.set_channels(CHANNELS) #设置wav 声道数
        wf.set_sampwidth(p.get_sample_size(FORMAT))  #设置wav 采样精度
        wf.set_framerate(RATE)  #设置wav 采样率
        wf.write_frames(b''.join(frames)) #存储wav音频数据
        wf.close() #关闭wav文件
    except BaseException as e:
            print(f"Exception {e}")
    finally:
        stream.stop_stream() #停止采集音频数据
        stream.close()#关闭音频输入流
        p.terminate()#释放音频对象
        MediaManager.deinit() #释放vb buffer

if __name__ == "__main__":
    os.exitpoint(os.EXITPOINT_ENABLE)
    print("音频示例开始")
    record_audio('/sdcard/examples/test.wav', 5)  # 录制WAV文件

播放 WAV 文件示例#

import os
from media.media import *   #导入media模块,用于初始化vb buffer
from media.pyaudio import * #导入pyaudio模块,用于采集和播放音频
import media.wave as wave   #导入wav模块,用于保存和加载wav音频文件

def exit_check():
    try:
        os.exitpoint()
    except KeyboardInterrupt as e:
        print("user stop: ", e)
        return True
    return False

def play_audio(filename):
    try:
        wf = wave.open(filename, 'rb')#打开wav文件
        CHUNK = int(wf.get_framerate()/25)#设置音频chunk值

        p = PyAudio()
        p.initialize(CHUNK) #初始化PyAudio对象
        MediaManager.init()    #vb buffer初始化

        #创建音频输出流,设置的音频参数均为wave中获取到的参数
        stream = p.open(format=p.get_format_from_width(wf.get_sampwidth()),
                    channels=wf.get_channels(),
                    rate=wf.get_framerate(),
                    output=True,frames_per_buffer=CHUNK)

        #设置音频输出流的音量
        stream.volume(vol=85)

        data = wf.read_frames(CHUNK)#从wav文件中读取数一帧数据

        while data:
            stream.write(data)  #将帧数据写入到音频输出流中
            data = wf.read_frames(CHUNK) #从wav文件中读取数一帧数据
            if exit_check():
                break
    except BaseException as e:
            print(f"Exception {e}")
    finally:
        stream.stop_stream() #停止音频输出流
        stream.close()#关闭音频输出流
        p.terminate()#释放音频对象
        wf.close()#关闭wav文件

        MediaManager.deinit() #释放vb buffer

if __name__ == "__main__":
    os.exitpoint(os.EXITPOINT_ENABLE)
    print("音频示例开始")
    play_audio('/sdcard/examples/test.wav')  # 播放WAV文件

总结#

通过本手册,开发者可以轻松地利用 CanMV 音频模块实现音频的播放与采集功能。该模块结合了 wavepyaudio 库的优势,提供了便捷的接口和清晰的 API 文档,便于快速开发和应用音频相关项目。

评论列表
条评论
登录