写 Python 音频处理的人，多半都绕不开“声道”这个坎。不管是做语音工具、音乐播放器还是实时采样程序，左声道右声道怎么分配、怎么分离、怎么合成立体声，都是最基础也最容易踩坑的环节。而这个领域里，我用得最顺手的就是sounddevice——它不像pyaudio那样需要手工管理缓冲区，也不像librosa那样偏重分析而不适合实时播放，sounddevice的定位非常清晰：底层封装 PortAudio，上层直接给你 NumPy 数组格式的数据流，播放和录音本质上就是“往数组里填数据”和“从数组里取数据”。这篇内容我会完整拆解用sounddevice处理左声道、右声道、立体声的播放与录音流程，从设备查询、数据形状理解到双声道分离、实时混音，一路写到排查技巧，适合所有刚接触 Python 音频又想把声道控制搞明白的人。
1. 为什么选择 sounddevice：一个被低估的音频利器
1.1 它是什么，能解决哪些问题
sounddevice是 Python 生态里一个基于 PortAudio 库的音频输入输出模块。简单说，它把底层声卡的播放和采集能力封装成了一组非常干净的 Python 函数，核心操作只有三个：play负责播放，rec负责录音，Stream负责输入输出同时进行。它和前几年流行的pyaudio相比，最大的优势是数据格式直接基于 NumPy 数组，这意味着你不需要手动去解析二进制 PCM 数据，也不需要去处理readframes返回的字节流，所有音频数据在你眼里就是一个形状清晰的矩阵：(采样点数量, 声道数)。
举个例子，如果你要录制一段 1 秒的立体声，采样率 44100 Hz，那么你拿到的录音数据就是一个(44100, 2)的数组。这个数组的第一列是左声道，第二列是右声道，索引是行号，对应时间轴上的每一个采样点。理解了这一点，你对声道控制的困惑基本就解决了大半。而sounddevice让你以这种“矩阵思维”去操作音频，天然就适合做各种左右声道的灵活处理，这也是它在技术社区里口碑一直不错的原因。
我当初从pyaudio切换过来的一个重要契机，就是做双声道实时监听时，pyaudio的回调函数要处理的数据格式特别别扭，需要在二进制缓冲区和数值数组之间反复转换，调试起来非常痛苦。换成sounddevice之后，回调函数里直接操作 NumPy 数组，左声道右声道各自处理，代码量直接少了一半，逻辑也清楚得多。如果你也受够了底层缓冲区的折磨，这个库很值得一试。
1.2 与同类库的对比
经常有人问我，做 Python 音频到底该用哪个库？其实没有绝对答案，但我们可以按场景拆开看：
wave和scipy.io.wavfile：只能做文件的读写，不涉及实时播放和采集，适合离线处理。pyaudio：跨平台和 sounddevice 一样底层都依赖 PortAudio，但它的 API 设计更老派，回调函数里拿到的是二进制数据，需要自己用struct或numpy.frombuffer手动解析，编码量较大。librosa：偏重音频特征分析和音乐信息检索，虽然有play相关接口，但播放功能只是附属品，不适合做实时低延迟采集。sounddevice：兼顾易用性和实时性，数据格式直接用 NumPy，cFFI 封装性能不错，回调模式下延迟可以做到很低。
如果你只是要“把音频文件读进来、做一些声道处理、播放出去，同时还要录音”，那sounddevice几乎是最平衡、最省心的选择。它涉及的依赖只有CFFI和NumPy，安装简单，遇到问题的排查成本也低。后面我会从头到尾带你把播放、录音、声道分离这些环节全部跑通。
2. 环境准备：5分钟跑通第一个音频程序
2.1 安装与基础依赖
先用 pip 把依赖装上：
pip install sounddevice numpy如果你打算用soundfile来读取 WAV 文件，可以一并安装：
pip install soundfile安装完成后，在 Python 里跑一句验证：
import sounddevice as sd print(sd.query_devices())query_devices()会列出当前机器上所有可用的音频设备，包括输入设备（麦克风）和输出设备（扬声器、耳机等）。输出的每一行包含设备编号、设备名称、最大输入输出声道数、默认采样率等信息。这一步是必须的，因为后续代码里如果你不做特殊指定，sounddevice会使用机器上的“默认输入设备”和“默认输出设备”，而这个默认设备不一定是你想要的。
2.2 音频核心概念再认识：采样率、声道数与数据形状
在进入代码之前，先把三个最基础的概念对齐，后面不会走偏。
第一是采样率（Sample Rate），单位是 Hz，表示每秒采集多少个采样点。CD 音质的标准是 44100 Hz，意味着每一秒的音频数据包含 44100 个采样点。采样率越高，频率响应范围越宽，但数据量也越大。
第二是声道数（Channels）。单声道（Mono）只有 1 个声道，数据形状是(N,)或者(N, 1)；立体声（Stereo）有 2 个声道，数据形状是(N, 2)，第一列是左声道，第二列是右声道。如果你的声道数更多，比如 5.1 声道的 6 个通道，也是同理，数组按列依次对应各声道。
第三是位深度（Bit Depth）。sounddevice内部统一用浮点数表示音频数据，常用的是float32或float64，值的范围在 -1.0 到 1.0 之间。在最终写入 WAV 文件时，通常我们会转成 16 位整数 PCM，范围是 -32768 到 32767，转换公式是int_value = float_value * 32767。
理解了这三个概念，下面所有的代码你就可以顺着“数据形状”这条主线去理解了。
2.3 必须先做的两件事：查询设备与默认设备确认
在跑任何播放或录音代码之前，我强烈建议你先查询设备并打印出来，确认你的输入输出设备是哪个。特别是笔记本用户，很容易出现：明明代码跑通了，但声音从 HDMI 显示器外放出来，或者录音拿到的数据全为零，因为默认输入设备指向了一个根本没有信号源的麦克风。
你可以用下面的代码来查看默认设备：
import sounddevice as sd devices = sd.query_devices() print("默认输入设备:", sd.default.device[0]) print("默认输出设备:", sd.default.device[1]) print("默认采样率:", sd.default.samplerate)如果你需要指定某个设备，可以这样设置：
sd.default.device = (3, 5) # 第一个数字是输入设备编号，第二个是输出设备编号 sd.default.samplerate = 44100注意括号里的顺序：(input_device_index, output_device_index)。很多新手在这里会卡壳，因为直觉上会觉得第一个是输出、第二个是输入，其实是反的。我建议你把sd.default.device的赋值理解成“先声明从哪个设备采集，再声明往哪个设备播放”，这样就顺了。
3. 播放：向左走还是向右走（声道控制全解析）
3.1 播放立体声：你的第一个双声道程序
播放立体声最简单的方式，就是准备一个(N, 2)形状的 NumPy 数组，然后丢给sd.play并指定采样率。下面我生成一段 2 秒的测试音：左声道 440 Hz，右声道 880 Hz。这样听到的会是两个不同音高的声音，分别从左右两边出来，方便直观验证声道方向是否正确。
import sounddevice as sd import numpy as np sample_rate = 44100 duration = 2.0 t = np.linspace(0, duration, int(sample_rate * duration), endpoint=False) # 左声道 440Hz，右声道 880Hz left = 0.5 * np.sin(2 * np.pi * 440 * t) right = 0.5 * np.sin(2 * np.pi * 880 * t) # 用 column_stack 合并成两列，shape 为 (N, 2) stereo = np.column_stack((left, right)) sd.play(stereo, sample_rate) sd.wait() # 等待播放结束sd.wait()的作用是阻塞当前进程，直到声音播放完毕。如果你不写这一步，程序会在声音还没开始播放时就结束退出，表现上就是“什么也没听到”。在交互式环境里（比如 Jupyter Notebook）可能没那么明显，但写成脚本运行时就一定会遇到这个问题，先把这个坑记住。
关于np.linspace生成的t，时间轴精度完全由采样率决定。这里int(sample_rate * duration)保证了数组长度恰好等于 88200 个采样点。你也可以用np.arange(0, duration, 1/sample_rate)，效果一致，但我更习惯linspace的写法，端点处理更干净。
3.2 只让左声道响：打造单边播放入门
场景很常见：你有一段单声道音频，想让它只从左边音箱或者只从右边耳机出声。实现方法很简单，构建一个(N, 2)的数组，把不想出声音的那一列置为零即可。
# 假设 mono 是一个一维的单声道音频 mono = 0.5 * np.sin(2 * np.pi * 440 * t) # 只播放左声道 left_only = np.zeros((len(mono), 2)) left_only[:, 0] = mono # 左声道填数据，右声道保持 0 sd.play(left_only, sample_rate) sd.wait()同理，只播放右声道就把数据放到第二列：
right_only = np.zeros((len(mono), 2)) right_only[:, 1] = mono sd.play(right_only, sample_rate) sd.wait()这种方法本质上是“用静音填充不需要的声道”，简单直观，适合大多数场景。但如果你对信噪比或者性能有极致要求，更专业的做法是不要生成多余的样本数据，而是直接用sd.Stream配合设备声道映射来实现，这个我在后面的实时处理部分会展开。
3.3 实时调节左右声道音量与平衡
另一个高频需求是调节左右声道音量，比如左声道音量降低到原来的 30%，右声道维持不变，实现“声像偏右”的效果。这个操作本质上就是对 NumPy 数组做矩阵运算。
stereo = np.column_stack((left, right)) # 左声道降到 30%，右声道保持 80% balanced = stereo.copy() balanced[:, 0] *= 0.3 balanced[:, 1] *= 0.8 sd.play(balanced, sample_rate) sd.wait()如果你想实现一个更平滑的平衡控制（Pan），可以用一个系数pan在 -1 到 1 之间变化，-1 表示全左，1 表示全右，0 表示居中。计算公式如下：
def apply_pan(stereo_data, pan): # pan: -1.0 全左, 0.0 居中, 1.0 全右 pan_left = np.clip(1 - max(pan, 0), 0, 1) pan_right = np.clip(1 + min(pan, 0), 0, 1) left = stereo_data[:, 0] * pan_left right = stereo_data[:, 1] * pan_right return np.column_stack((left, right))比如pan=-1时，pan_left=1，pan_right=0，输出就完全是左声道的声音。pan=1时则相反。这种方式在音乐播放器或者游戏声效处理里很常用。需要注意，严格意义上的等功率 Pan 还会涉及三角函数增益计算来保证听觉响度一致，但日常简单应用用线性系数完全够用了。
4. 录音：把左右声道分开拿下
4.1 用 sounddevice 录立体声
录音的核心函数是sd.rec。下面这段代码会录制 5 秒的立体声，采样率 44100，数据格式为float32：
import sounddevice as sd import numpy as np duration = 5.0 sample_rate = 44100 recording = sd.rec( int(duration * sample_rate), samplerate=sample_rate, channels=2, dtype='float32' ) sd.wait() # 等待录音完成 print(recording.shape) # 输出 (220500, 2)这里recording的形状是(220500, 2)，第一列是左声道，第二列是右声道。如果你只想录单声道，把channels=1即可，得到的数组形状是(220500,)。另外，dtype可以是'float32'、'float64'或者'int16'，建议优先用float32，精度足够，又与sounddevice内部处理格式一致，避免不必要的转换。
这里有个细节：sd.rec和sd.wait之间是有异步时序关系的。rec调用后录音会在后台开始，wait会阻塞直到录音完成。如果在一些小内存设备上同时启动多个录制任务，可能会报PortAudio error: Device unavailable，这通常是声卡驱动不支持同时多路采集导致的，建议一个一个来。
4.2 从录音数据中分离左声道与右声道
录音拿到(N, 2)的数据后，分离左右声道就是最基础的切片操作：
left_channel = recording[:, 0] # 左声道 right_channel = recording[:, 1] # 右声道分离出来之后，你可以对每个声道做独立处理。比如左声道降噪、右声道加回声，处理完以后再合并回去：
# 对左声道做一个简单的高通滤波示例（一阶差分） left_filtered = np.diff(left_channel, prepend=0) # 合并回立体声 processed_stereo = np.column_stack((left_filtered, right_channel)) sd.play(processed_stereo, sample_rate) sd.wait()prepend=0是为了让np.diff输出长度与原始数据一致，否则替换回去会维度不匹配。类似的细节在处理音频时特别多，一旦数组维度对不上，sounddevice会直接报 ValueError，内容大概是list of arrays has different lengths，排查时先检查数据形状就对了。
4.3 保存成标准 WAV：不依赖第三方库的写法
录音不保存等于白录。如果把音频数据直接np.save存成 npy 文件，那只有你自己能读，别人拿到的就不是通用音频文件。为了通用性，我通常直接用 Python 标准库wave模块来写 WAV 文件，这样可以少依赖一个第三方库。
import wave import numpy as np def save_stereo_wav(filename, stereo_data, sample_rate): """ 将 (N, 2) 的 float32 立体声数据保存为 16 位 WAV 文件 """ # 裁剪到 [-1.0, 1.0]，防止溢出导致爆音 stereo_data = np.clip(stereo_data, -1.0, 1.0) # 转成 16 位整数 PCM pcm_data = (stereo_data * 32767).astype(np.int16) with wave.open(filename, 'wb') as wf: wf.setnchannels(2) # 双声道 wf.setsampwidth(2) # 16 位 = 2 字节 wf.setframerate(sample_rate) wf.writeframes(pcm_data.tobytes())写完后可以验证一下：
with wave.open('test.wav', 'rb') as wf: print('声道数:', wf.getnchannels()) print('采样率:', wf.getframerate()) print('帧数:', wf.getnframes()) print('采样宽度:', wf.getsampwidth())有些情况下你可能需要保存 32 位浮点 WAV，只需要把setsampwidth(4)并将数据按float32原样写入即可：
with wave.open('test_float.wav', 'wb') as wf: wf.setnchannels(2) wf.setsampwidth(4) wf.setframerate(sample_rate) wf.writeframes(stereo_data.astype(np.float32).tobytes())不过 16 位 PCM 的兼容性最好，大多数播放器和音频编辑软件都能打开，日常够用了。
如果想省事，用soundfile库也很简单：
import soundfile as sf sf.write('test.wav', stereo_data, sample_rate)但我依然建议你自己实现一遍wave版本，这样能彻底理解音频数据的底层存储方式，排查问题时也会更有底气。
5. 更进一步：播放与录音同时进行
5.1 回声监听
实时处理是sounddevice最强大的场景。通过sd.Stream可以同时启动输入和输出流，在回调函数里拿到输入数据（麦克风采集），处理后写入输出数据（扬声器播放）。最简单的演示是“回声监听”：把麦克风录到的声音直接播放出来。
import sounddevice as sd def callback(indata, outdata, frames, time_info, status): if status: print(f"状态提示: {status}") # indata 形状为 (frames, channels)，直接拷贝到输出 outdata[:] = indata sample_rate = 44100 blocksize = 1024 stream = sd.Stream( samplerate=sample_rate, blocksize=blocksize, channels=2, callback=callback ) stream.start() input("按回车停止...") stream.stop() stream.close()这段代码会把你对着麦克风说的话从扬声器里实时放出来，延迟通常能控制在几十毫秒以内（取决于设备和驱动）。第一次跑通的时候你会发现两个问题：一是音量可能会很大，容易产生啸叫，建议先把系统音量调低再试；二是延迟感如果比较明显，大概率是blocksize设置过大，官方推荐的默认值通常是 0，表示由 PortAudio 自动选择，你可以在 256、512、1024 几个档位之间测试。
outdata[:] = indata这行代码是必须的。outdata是预先分配好的缓冲区，如果你不去填充它，输出会保持静音，程序也不会报错，这会让很多初学者困惑。如果回调执行时间过长，缓冲区来不及填满，PortAudio 会进入欠载状态，具体表现就是声音断续、咔哒响。
5.2 实时混音
回声监听只是最基础的用法，真正体现声道控制价值的是实时混音。下面这段代码演示：麦克风采集到的立体声信号，左声道音量提升 50%，右声道保持不变，同时叠加一个预设的立体声背景音乐。
import sounddevice as sd import numpy as np sample_rate = 44100 background_duration = 10.0 t = np.linspace(0, background_duration, int(sample_rate * background_duration), endpoint=False) # 生成立体声背景音乐（左 330Hz，右 550Hz 的柔和测试音） bg_left = 0.2 * np.sin(2 * np.pi * 330 * t) bg_right = 0.2 * np.sin(2 * np.pi * 550 * t) background = np.column_stack((bg_left, bg_right)) position = 0 def mix_callback(indata, outdata, frames, time_info, status): global position if status: print(f"状态提示: {status}") # 混入麦克风信号，左声道放大 1.5 倍，右声道原样 mic_left = indata[:, 0] * 1.5 mic_right = indata[:, 1] mic = np.column_stack((mic_left, mic_right)) # 叠加背景音乐片段（循环） end = position + frames bg_segment = background[position % len(background):end % len(background)] if len(bg_segment) < frames: bg_segment = np.concatenate([bg_segment, background[:frames - len(bg_segment)]]) outdata[:] = mic + bg_segment position += frames stream = sd.Stream( samplerate=sample_rate, blocksize=1024, channels=2, callback=mix_callback ) stream.start() input("按回车停止...") stream.stop() stream.close()这段代码融合了两个要点：一是微调了输入信号中左右声道的音量比例；二是在输出端叠加了另一路立体声音频，数据形状始终保持在(frames, 2)。这种“麦克风声音 + 背景音乐同时从立体声扬声器出来”的模式，已经足以应对很多直播场景、伴奏跟唱工具和语音交互原型的需求。
6. 常见问题与排查技巧实录
6.1 没有声音？先查默认设备
脚本跑起来没声音，80% 的原因是输出设备指向错了。最常见的情况是机器上有多个输出设备，除了内置扬声器之外还有 HDMI 音频、蓝牙耳机、USB 声卡，系统默认的输出设备不是你正在用的那个。排查方法完全可以用脚本做：
import sounddevice as sd devices = sd.query_devices() print(devices) # 查看默认输出设备明细 default_out = sd.default.device[1] print(sd.query_devices(default_out))如果你的默认设备编号指向了-1，说明系统还没有设置默认设备，这时你需要手动指定：
sd.default.device = (None, 5) # 输入保持默认，输出用编号 5query_devices()输出了设备的输入输出声道数，比如max output channels: 2，如果你的输出设备最大只支持 1 声道，而你的数据是 2 声道的，sounddevice在用默认设置播放时会自动做转换，但有些旧驱动会报错，需要你显式降为单声道播放。
6.2 采样率不匹配
sounddevice在初始化时有一个原则：输入、输出和回调里处理的采样率必须一致。你从 WAV 文件读入一段 16000 Hz 的语音，却用 44100 Hz 的采样率去播放，声音会明显变调（音调变高或变低），这是最典型的“采样率不匹配”后果。
import soundfile as sf data, sr = sf.read('speech_16k.wav') print(f"文件采样率: {sr}") # 用文件自带采样率播放 sd.play(data, sr) sd.wait() # 如果你想统一成 44100，需要做重采样，不能直接改播放参数 import scipy.signal data_resampled = scipy.signal.resample(data, int(len(data) * 44100 / sr)) sd.play(data_resampled, 44100) sd.wait()没有scipy的话，你也可以用librosa.resample或者soundfile在读取时直接指定目标采样率：
data, sr = sf.read('speech_16k.wav', dtype='float32') # 重新采样到 44100 data_44100 = sf.resample(data, 44100)注意：重采样不是简单“改个播放参数”就能完成的，它涉及到插值和抗混叠滤波，直接用resample是安全的做法。
6.3 录音波形消失/全为零
录音完成后数据全是 0 或者波形完全不可见，这类问题一般集中在两块：
第一是输入设备选错了。笔记本内置麦克风和 USB 麦克风可能对应不同的设备编号，如果你的程序默认用的是“立体声混音”或者一个没有信号的虚拟设备，采集到的就是静音。解决办法是遍历所有输入设备，逐个打印设备名，找到实际型号后再手动指定。
第二是通道数量不匹配。比如你的麦克风是单声道的，但你在sd.rec里设置channels=2，某些声卡驱动力会强行补零，导致右声道永远静音。这种情况可以先录一个单声道的：
test_rec = sd.rec(44100, samplerate=44100, channels=1, dtype='float32') sd.wait() print("单声道录音最大值:", np.max(np.abs(test_rec)))如果单声道录音有波形但立体声没有，那就大概率是设备通道配置的问题。
6.4 缓冲区溢出
运行过程中出现Buffer underflow或者Buffer overflow的提示，通常是因为回调函数内部处理时间过长，超过了声卡缓冲区能够容忍的时间。这个问题常见于你在回调里做了重型的音频处理，比如深度学习模型推理、复杂滤波等。
解决思路有两个方向：一是加大blocksize，从 1024 调整到 2048 或更高；二是把耗时操作移到独立的线程里去，回调函数只在队列里塞任务和取结果，尽量做到“快进快出”。前者牺牲延迟换稳定性，后者更优雅但复杂度高。
# 简单版本：加大 blocksize 提升稳定性 stream = sd.Stream( samplerate=44100, blocksize=2048, channels=2, callback=callback )注意，blocksize并不是越大越好。过大的 blocksize 会导致播放延迟显著增加，在需要实时交互（比如乐器演奏）的场景里会很难受。常规做法是先试 1024，不够再升，找到一个延迟和稳定性都可以接受的平衡点。
6.5 声道方向反了
左右声道反过来也是个很容易被忽略的问题。不一定是代码写错了，很多时候是声卡驱动或者硬件接线决定的。比如有些外置声卡的立体声输出，左右信号在物理接口上就是反的。遇到这种情况，最直接的做法是在程序里做一个声道交换：
left = stereo[:, 0] right = stereo[:, 1] swapped = np.column_stack((right, left)) sd.play(swapped, sample_rate) sd.wait()如果你确定你的声道逻辑是对的有参考基准，那就以你的耳朵为准做一次校准，别盲目相信“左声道就是左音箱”。
7. 实操笔记总结
我用sounddevice做音频处理的这几个月下来，最大的体会就是：音频处理并不难，难的是把数据形状、设备配置、采样率这些基础概念彻底消化掉。不管代码逻辑写得多花哨，最后都要落回到一个(采样点数, 声道数)的数组上。左声道就是第 0 列，右声道就是第 1 列，想要哪个声道响就往哪个列填数据，想让哪个声道静音就把哪一列置零，这个思维一旦建立起来，你在音频开发这条路上就再也不会迷路。
如果你想在这个项目基础上继续扩展，可以考虑加一个图形界面，把你的左右声道音量调节做成可视化推子；也可以把录音部分接到whisper之类的语音识别模型上，做一个实时转录工具；或者把声道分离逻辑推到极致，录制多通道音频并分别导出各个声道的独立 WAV 文件。这些操作的核心仍然离不开sounddevice这套简洁的数据流。走稳了第一步，后面的路就好走多了。