树莓派 Python 音频播放开发实战指南

树莓派上用 Python 玩转音频播放：从入门到实战的完整指南

在嵌入式项目中，声音是最直接的人机交互方式之一。无论是智能门铃的'叮咚'声、语音助手的回应，还是环境监测系统的报警提示，都离不开稳定可靠的音频播放能力。而树莓派 + Python 的组合，恰好提供了既强大又灵活的实现路径。

面对 PyAudio、pygame.mixer、sounddevice 等多个选择，到底该用哪个？它们各自适合什么场景？怎么避免常见的'无声坑'？本文将带你一步步打通树莓派音频开发的关键环节，不讲空话，只给能落地的方案。

为什么树莓派上的音频这么'难搞'？

先泼一盆冷水：树莓派本身没有内置功放，3.5mm 耳机口输出功率有限，接普通小喇叭可能音量微弱甚至无声。更别说系统默认音频输出可能指向 HDMI，而不是你插着的扬声器。

再加上 Linux 的音频架构（ALSA/PulseAudio）本就复杂，Python 又是高层语言，中间还隔着 PortAudio 这样的桥梁库……稍有不慎，就会出现：

播放失败
音频卡顿
格式不支持
多进程抢占设备

所以，搞清楚'谁控制谁'特别重要。

简单来说，在树莓派上，你的 Python 程序 → 调用音频库 → 通过 ALSA 访问声卡 → 输出到物理设备。整个链条任何一个环节出问题，都会导致'静音'。

✅ 小贴士：运行 sudo raspi-config，进入 System Options > Audio，手动选择'Force 3.5mm ('headphone') jack'可以强制音频走模拟口。

方案一：精细控制之选 —— PyAudio

如果你需要对采样率、缓冲区、声道等参数精确掌控，比如做实时音频处理或者低延迟应用，PyAudio 是首选。

它底层基于 C 编写的 PortAudio，可以直接与 ALSA 打交道，绕过 PulseAudio 的调度开销，延迟更低。

安装有点坑，得提前铺路

# 先装依赖
sudo apt-get install portaudio19-dev python3-pyaudio
# 或者用 pip（推荐使用虚拟环境）
pip install pyaudio

注意：直接 pip install pyaudio 经常报错，因为缺少 PortAudio 开发库。上面那条 apt 命令就是补这个'地基'的。

实战代码：播放一个 WAV 文件

import pyaudio
import wave

def play_wav(file_path):
    wf = wave.open(file_path, 'rb')
    p = pyaudio.PyAudio()
    stream = p.open(
        format=p.get_format_from_width(wf.getsampwidth()),
        channels=wf.getnchannels(),
        rate=wf.getframerate(),
        output=True
    )
    chunk = 1024
    data = wf.readframes(chunk)
    while data:
        stream.write(data)
        data = wf.readframes(chunk)
    stream.stop_stream()
    stream.close()
    p.terminate()
    wf.close()

# 使用 play_wav("alert.wav")

关键点解析

参数	说明
`format`	必须匹配 WAV 文件的位深（如 16bit 对应 `paInt16`）
`channels`	单声道/立体声自动识别
`rate`	采样率必须一致，否则变调或崩溃
`output=True`	表示这是播放流

💡 经验谈：如果遇到播放速度异常快或慢，八成是采样率没对上。用 file alert.wav 命令查看真实参数。

什么时候该用 PyAudio？

需要自定义音频流（如网络流播放）
实现全双工录音 + 播放
对延迟敏感的应用（<50ms）
自行解码后送原始 PCM 数据

但它也有缺点：不支持 MP3 解码。想播 MP3？得先转成 WAV，或者搭配 pydub 使用。

方案二：快速上手利器 —— pygame.mixer

你是不是只想让程序'响一下'就完事？比如按钮按下播放提示音？那完全没必要折腾 PyAudio。

试试 pygame.mixer —— 虽然它是游戏库的一部分，但在树莓派社区里早已成为'最香'的音频播放方案之一。

安装简洁

pip install pygame

没错，就这一句。而且它自带音频解码器，MP3、OGG、WAV 全都支持！

极简代码示例

import pygame
import time

def play_sound(file_path):
    pygame.mixer.init(frequency=44100, size=-16, channels=2, buffer=512)
    pygame.mixer.music.load(file_path)
    pygame.mixer.music.set_volume(0.7)
    pygame.mixer.music.play()
    # 等待播放完成
    while pygame.mixer.music.get_busy():
        time.sleep(0.1)

play_sound("welcome.mp3")

就这么几行，MP3 就响了。而且音量可调、支持循环播放，连缓冲区都可以设。

为什么开发者都喜欢它？

API 极其简单，三步搞定：init → load → play
内置解码，无需额外安装 ffmpeg
资源占用低，适合长时间运行的服务
支持并发播放多个音效（通过 Channel 分配）

注意事项

第一次 init() 会有轻微延迟（初始化音频引擎）
不要频繁创建/销毁 mixer，建议全局初始化一次
多线程中使用时注意同步，避免冲突

📌 最佳实践：在主程序启动时初始化一次 mixer，后续复用即可。

# 应用启动时
pygame.mixer.init(frequency=44100, size=-16, channels=2, buffer=1024)
# 按需播放
pygame.mixer.music.load("beep.mp3")
pygame.mixer.music.play()

方案三：科学计算搭档 —— sounddevice

如果你正在做一个信号生成、音频分析或机器学习相关的项目，那你一定会爱上 sounddevice。

它的设计哲学很明确：一切皆为 NumPy 数组。正弦波、白噪声、滤波后的信号，只要是个数组，就能直接播放。

安装方便

pip install sounddevice numpy

播放一个标准音 A4（440Hz）

import numpy as np
import sounddevice as sd

def play_tone(freq=440, duration=2.0, sr=44100):
    t = np.linspace(0, duration, int(sr * duration), False)
    tone = 0.5 * np.sin(2 * np.pi * freq * t)
    sd.play(tone, samplerate=sr)
    sd.wait()  # 阻塞直到播放结束

play_tone()

是不是很像 MATLAB？这种写法非常适合教学演示、算法验证、合成音效等场景。

高级玩法：回调模式连续播放

不想阻塞主线程？可以用异步回调：

import numpy as np
import sounddevice as sd

def callback(outdata, frames, time, status):
    if status:
        print(status)
    frequency = 440.0
    phase = getattr(callback, 'phase', 0.0)
    t = (phase + np.arange(frames)) / 44100.0
    outdata[:, 0] = 0.5 * np.sin(2 * np.pi * frequency * t)  # 左声道
    outdata[:, 1] = outdata[:, 0]  # 右声道同步
    callback.phase = phase + frames

stream = sd.OutputStream(samplerate=44100, channels=2, callback=callback)
with stream:
    input("按回车停止...\n")

这种方式可用于生成无限持续音、实时信号注入等高级用途。

三种方案怎么选？一张表说清楚

特性	PyAudio	pygame.mixer	sounddevice
易用性	⭐⭐☆	⭐⭐⭐⭐⭐	⭐⭐⭐☆
支持格式	WAV（PCM）	MP3/WAV/OGG	数组输入
是否需解码	否（需配合 wave/pydub）	是（内置）	否
延迟表现	低	中	低
适合场景	实时音频处理	提示音/事件音效	科学计算/信号生成
依赖复杂度	高（需编译）	低	中
NumPy 集成	差	无	强

✅ 总结一句话：

想快速响一声？用 pygame.mixer
做专业音频处理？选 PyAudio
玩信号合成或算法？上 sounddevice

实际项目中的常见'坑'与应对策略

❌ 问题 1：明明代码跑了，为啥没声音？

最常见的原因有三个：

音频输出设备选错了（HDMI vs 耳机口）
音量被系统静音
文件路径错误或格式不受支持

🔧 排查步骤：

# 查看当前音频设备
arecord -l  # 录音设备
aplay -l    # 播放设备
# 测试是否能播放（绕过 Python）
aplay example.wav
# 查看音量设置
amixer controls | grep Master
amixer cset numid=1 -- 80%  # 设置主音量

❌ 问题 2：MP3 播放失败？

PyGame 有时会因缺少 GStreamer 插件无法播放 MP3。解决方案是安装 pydub + ffmpeg 做预处理：

sudo apt install ffmpeg
pip install pydub

然后转换格式：

from pydub import AudioSegment
# 转成 WAV 供 PyAudio 使用
audio = AudioSegment.from_mp3("input.mp3")
audio.export("output.wav", format="wav")

❌ 问题 3：多进程抢设备冲突？

Linux 一次只允许一个进程访问音频设备。多个脚本同时运行会导致'Device busy'。

🔧 解决办法：

使用文件锁协调访问
统一由一个服务负责播放
改用 PulseAudio（支持混音），但增加延迟

例如加个简单的锁机制：

import fcntl

with open("/tmp/audio.lock", "w") as f:
    fcntl.flock(f.fileno(), fcntl.LOCK_EX)  # 排他锁
    play_sound("alert.mp3")  # 安全播放
    fcntl.flock(f.fileno(), fcntl.LOCK_UN)  # 释放

实战案例：做个智能门铃

设想这样一个场景：有人按门铃，树莓派检测到 GPIO 上升沿，立刻播放一段 MP3 提示音。

import RPi.GPIO as GPIO
import pygame
import time

BUTTON_PIN = 18
GPIO.setmode(GPIO.BCM)
GPIO.setup(BUTTON_PIN, GPIO.IN, pull_up_down=GPIO.PUD_UP)
pygame.mixer.init(frequency=44100, size=-16, channels=2, buffer=512)

def on_button_pressed(channel):
    print("门铃被按下！")
    pygame.mixer.music.load("/home/pi/sounds/welcome.mp3")
    pygame.mixer.music.play()
    while pygame.mixer.music.get_busy():
        time.sleep(0.1)

# 添加边沿检测
GPIO.add_event_detect(BUTTON_PIN, GPIO.FALLING, callback=on_button_pressed, bouncetime=500)

try:
    print("等待按钮触发...")
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    GPIO.cleanup()

这就是一个典型的物联网音频应用场景。结合网络还能实现远程播报、微信通知联动等功能。

树莓派上用 Python 玩转音频播放：从入门到实战的完整指南

为什么树莓派上的音频这么'难搞'？

再加上 Linux 的音频架构（ALSA/PulseAudio）本就复杂，Python 又是高层语言，中间还隔着 PortAudio 这样的桥梁库……稍有不慎，就会出现：

播放失败
音频卡顿
格式不支持
多进程抢占设备

所以，搞清楚'谁控制谁'特别重要。

简单来说，在树莓派上，你的 Python 程序 → 调用音频库 → 通过 ALSA 访问声卡 → 输出到物理设备。整个链条任何一个环节出问题，都会导致'静音'。

✅ 小贴士：运行 sudo raspi-config，进入 System Options > Audio，手动选择'Force 3.5mm ('headphone') jack'可以强制音频走模拟口。

方案一：精细控制之选 —— PyAudio

如果你需要对采样率、缓冲区、声道等参数精确掌控，比如做实时音频处理或者低延迟应用，PyAudio 是首选。

它底层基于 C 编写的 PortAudio，可以直接与 ALSA 打交道，绕过 PulseAudio 的调度开销，延迟更低。

安装有点坑，得提前铺路

# 先装依赖
sudo apt-get install portaudio19-dev python3-pyaudio
# 或者用 pip（推荐使用虚拟环境）
pip install pyaudio

注意：直接 pip install pyaudio 经常报错，因为缺少 PortAudio 开发库。上面那条 apt 命令就是补这个'地基'的。

实战代码：播放一个 WAV 文件

import pyaudio
import wave

def play_wav(file_path):
    wf = wave.open(file_path, 'rb')
    p = pyaudio.PyAudio()
    stream = p.open(
        format=p.get_format_from_width(wf.getsampwidth()),
        channels=wf.getnchannels(),
        rate=wf.getframerate(),
        output=True
    )
    chunk = 1024
    data = wf.readframes(chunk)
    while data:
        stream.write(data)
        data = wf.readframes(chunk)
    stream.stop_stream()
    stream.close()
    p.terminate()
    wf.close()

# 使用 play_wav("alert.wav")

关键点解析

参数	说明
`format`	必须匹配 WAV 文件的位深（如 16bit 对应 `paInt16`）
`channels`	单声道/立体声自动识别
`rate`	采样率必须一致，否则变调或崩溃
`output=True`	表示这是播放流

💡 经验谈：如果遇到播放速度异常快或慢，八成是采样率没对上。用 file alert.wav 命令查看真实参数。

什么时候该用 PyAudio？

需要自定义音频流（如网络流播放）
实现全双工录音 + 播放
对延迟敏感的应用（<50ms）
自行解码后送原始 PCM 数据

但它也有缺点：不支持 MP3 解码。想播 MP3？得先转成 WAV，或者搭配 pydub 使用。

方案二：快速上手利器 —— pygame.mixer

你是不是只想让程序'响一下'就完事？比如按钮按下播放提示音？那完全没必要折腾 PyAudio。

试试 pygame.mixer —— 虽然它是游戏库的一部分，但在树莓派社区里早已成为'最香'的音频播放方案之一。

安装简洁

pip install pygame

没错，就这一句。而且它自带音频解码器，MP3、OGG、WAV 全都支持！

极简代码示例

import pygame
import time

def play_sound(file_path):
    pygame.mixer.init(frequency=44100, size=-16, channels=2, buffer=512)
    pygame.mixer.music.load(file_path)
    pygame.mixer.music.set_volume(0.7)
    pygame.mixer.music.play()
    # 等待播放完成
    while pygame.mixer.music.get_busy():
        time.sleep(0.1)

play_sound("welcome.mp3")

就这么几行，MP3 就响了。而且音量可调、支持循环播放，连缓冲区都可以设。

为什么开发者都喜欢它？

API 极其简单，三步搞定：init → load → play
内置解码，无需额外安装 ffmpeg
资源占用低，适合长时间运行的服务
支持并发播放多个音效（通过 Channel 分配）

注意事项

第一次 init() 会有轻微延迟（初始化音频引擎）
不要频繁创建/销毁 mixer，建议全局初始化一次
多线程中使用时注意同步，避免冲突

📌 最佳实践：在主程序启动时初始化一次 mixer，后续复用即可。

# 应用启动时
pygame.mixer.init(frequency=44100, size=-16, channels=2, buffer=1024)
# 按需播放
pygame.mixer.music.load("beep.mp3")
pygame.mixer.music.play()

方案三：科学计算搭档 —— sounddevice

如果你正在做一个信号生成、音频分析或机器学习相关的项目，那你一定会爱上 sounddevice。

它的设计哲学很明确：一切皆为 NumPy 数组。正弦波、白噪声、滤波后的信号，只要是个数组，就能直接播放。

安装方便

pip install sounddevice numpy

播放一个标准音 A4（440Hz）

import numpy as np
import sounddevice as sd

def play_tone(freq=440, duration=2.0, sr=44100):
    t = np.linspace(0, duration, int(sr * duration), False)
    tone = 0.5 * np.sin(2 * np.pi * freq * t)
    sd.play(tone, samplerate=sr)
    sd.wait()  # 阻塞直到播放结束

play_tone()

是不是很像 MATLAB？这种写法非常适合教学演示、算法验证、合成音效等场景。

高级玩法：回调模式连续播放

不想阻塞主线程？可以用异步回调：

import numpy as np
import sounddevice as sd

def callback(outdata, frames, time, status):
    if status:
        print(status)
    frequency = 440.0
    phase = getattr(callback, 'phase', 0.0)
    t = (phase + np.arange(frames)) / 44100.0
    outdata[:, 0] = 0.5 * np.sin(2 * np.pi * frequency * t)  # 左声道
    outdata[:, 1] = outdata[:, 0]  # 右声道同步
    callback.phase = phase + frames

stream = sd.OutputStream(samplerate=44100, channels=2, callback=callback)
with stream:
    input("按回车停止...\n")

这种方式可用于生成无限持续音、实时信号注入等高级用途。

三种方案怎么选？一张表说清楚

特性	PyAudio	pygame.mixer	sounddevice
易用性	⭐⭐☆	⭐⭐⭐⭐⭐	⭐⭐⭐☆
支持格式	WAV（PCM）	MP3/WAV/OGG	数组输入
是否需解码	否（需配合 wave/pydub）	是（内置）	否
延迟表现	低	中	低
适合场景	实时音频处理	提示音/事件音效	科学计算/信号生成
依赖复杂度	高（需编译）	低	中
NumPy 集成	差	无	强

✅ 总结一句话：

想快速响一声？用 pygame.mixer
做专业音频处理？选 PyAudio
玩信号合成或算法？上 sounddevice

实际项目中的常见'坑'与应对策略

❌ 问题 1：明明代码跑了，为啥没声音？

最常见的原因有三个：

音频输出设备选错了（HDMI vs 耳机口）
音量被系统静音
文件路径错误或格式不受支持

🔧 排查步骤：

# 查看当前音频设备
arecord -l  # 录音设备
aplay -l    # 播放设备
# 测试是否能播放（绕过 Python）
aplay example.wav
# 查看音量设置
amixer controls | grep Master
amixer cset numid=1 -- 80%  # 设置主音量

❌ 问题 2：MP3 播放失败？

PyGame 有时会因缺少 GStreamer 插件无法播放 MP3。解决方案是安装 pydub + ffmpeg 做预处理：

sudo apt install ffmpeg
pip install pydub

然后转换格式：

from pydub import AudioSegment
# 转成 WAV 供 PyAudio 使用
audio = AudioSegment.from_mp3("input.mp3")
audio.export("output.wav", format="wav")

❌ 问题 3：多进程抢设备冲突？

Linux 一次只允许一个进程访问音频设备。多个脚本同时运行会导致'Device busy'。

🔧 解决办法：

使用文件锁协调访问
统一由一个服务负责播放
改用 PulseAudio（支持混音），但增加延迟

例如加个简单的锁机制：

import fcntl

with open("/tmp/audio.lock", "w") as f:
    fcntl.flock(f.fileno(), fcntl.LOCK_EX)  # 排他锁
    play_sound("alert.mp3")  # 安全播放
    fcntl.flock(f.fileno(), fcntl.LOCK_UN)  # 释放

实战案例：做个智能门铃

设想这样一个场景：有人按门铃，树莓派检测到 GPIO 上升沿，立刻播放一段 MP3 提示音。

import RPi.GPIO as GPIO
import pygame
import time

BUTTON_PIN = 18
GPIO.setmode(GPIO.BCM)
GPIO.setup(BUTTON_PIN, GPIO.IN, pull_up_down=GPIO.PUD_UP)
pygame.mixer.init(frequency=44100, size=-16, channels=2, buffer=512)

def on_button_pressed(channel):
    print("门铃被按下！")
    pygame.mixer.music.load("/home/pi/sounds/welcome.mp3")
    pygame.mixer.music.play()
    while pygame.mixer.music.get_busy():
        time.sleep(0.1)

# 添加边沿检测
GPIO.add_event_detect(BUTTON_PIN, GPIO.FALLING, callback=on_button_pressed, bouncetime=500)

try:
    print("等待按钮触发...")
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    GPIO.cleanup()

这就是一个典型的物联网音频应用场景。结合网络还能实现远程播报、微信通知联动等功能。

树莓派 Python 音频播放开发实战指南

树莓派上用 Python 玩转音频播放：从入门到实战的完整指南

为什么树莓派上的音频这么'难搞'？

方案一：精细控制之选 —— PyAudio

安装有点坑，得提前铺路

实战代码：播放一个 WAV 文件

关键点解析

什么时候该用 PyAudio？

方案二：快速上手利器 —— pygame.mixer

安装简洁

极简代码示例

为什么开发者都喜欢它？

注意事项

方案三：科学计算搭档 —— sounddevice

安装方便

播放一个标准音 A4（440Hz）

高级玩法：回调模式连续播放

三种方案怎么选？一张表说清楚

实际项目中的常见'坑'与应对策略

❌ 问题 1：明明代码跑了，为啥没声音？

❌ 问题 2：MP3 播放失败？

❌ 问题 3：多进程抢设备冲突？

实战案例：做个智能门铃

树莓派 Python 音频播放开发实战指南

树莓派上用 Python 玩转音频播放：从入门到实战的完整指南

为什么树莓派上的音频这么'难搞'？

方案一：精细控制之选 —— PyAudio

安装有点坑，得提前铺路

实战代码：播放一个 WAV 文件

关键点解析

什么时候该用 PyAudio？

方案二：快速上手利器 —— pygame.mixer

安装简洁

极简代码示例

为什么开发者都喜欢它？

注意事项

方案三：科学计算搭档 —— sounddevice

安装方便

播放一个标准音 A4（440Hz）

高级玩法：回调模式连续播放

三种方案怎么选？一张表说清楚

实际项目中的常见'坑'与应对策略

❌ 问题 1：明明代码跑了，为啥没声音？

❌ 问题 2：MP3 播放失败？

❌ 问题 3：多进程抢设备冲突？

实战案例：做个智能门铃

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具