SoundCard Python Library

SoundCard uses a two-tier abstraction model to manage audio hardware:

1. Sound Card Handles (_Speaker and _Microphone): These are lightweight objects that act as references to your audio hardware. They do not perform audio processing themselves. Because hardware configuration can change (e.g., plugging in a USB headset), you should always retrieve fresh instances from the library instead of storing long-lived references.

2. Sound Streams (_Player and _Recorder): These are context managers that perform the actual heavy lifting of interfacing with backend drivers to play or record audio. You obtain these by calling methods on your handles.

Workflow Summary:

• Use soundcard functions to get a handle (_Speaker or _Microphone).
• Use the handle to create a stream (_Player or _Recorder).
• Use the stream (typically via a with statement) to process audio.

Since Raspberry Pi OS Lite does not include PulseAudio by default, you must install it and adjust the configuration to avoid mono-only output:

1. Install dependencies:

   sudo apt install -y python3-pip python3-numpy pulseaudio

2. Edit the PulseAudio profile configuration:

   sudo nano /usr/share/pulseaudio/alsa-mixer/profile-sets/default.conf

   Comment out the block [Mapping analog-mono] by adding a ; at the start of the lines.
3. Start PulseAudio:

   pulseaudio -D

4. Install SoundCard via pip:

   python3 -m pip install soundcard

sudo apt install -y python3-pip python3-numpy pulseaudio
# Edit /usr/share/pulseaudio/alsa-mixer/profile-sets/default.conf to comment out [Mapping analog-mono]
pulseaudio -D
python3 -m pip install soundcard

Windows/WASAPI

• Single Channel Recording: Currently records garbage if only a single channel is requested. Use multi-channel or channel maps instead.
• Blocksize Ignored: blocksize might be ignored unless exclusive_mode=True is used.
• Buffer Underruns: If underruns occur, use a larger blocksize than numframes.

macOS

• Silence during Recording: If you record silence, ensure your terminal or the application running the script has been granted Microphone permissions in System Settings.

General

• Error Messages: Errors may report internal CFFI or backend-specific issues.

The Speaker and Microphone objects provide direct methods for one-off recording and playback.

Important Data Format: All input and output data are handled as Numpy arrays with the shape (frames × channels). To avoid clipping, ensure all data values are restricted between -1 and 1 (0dBFS).

import soundcard as sc
import numpy

default_mic = sc.default_microphone()
default_speaker = sc.default_speaker()

# Record one second of audio at 48kHz
data = default_mic.record(samplerate=48000, numframes=48000)

# Play back with normalized volume to prevent clipping
# (dividing by the max absolute value scales data to [-1, 1])
default_speaker.play(data/numpy.max(numpy.abs(data)), samplerate=48000)

For continuous audio streams, use the recorder() and player() context managers provided by Microphone and Speaker objects. This approach is more efficient for real-time processing loops.

import soundcard as sc

default_mic = sc.default_microphone()
default_speaker = sc.default_speaker()

# Use context managers for continuous streaming
with default_mic.recorder(samplerate=48000) as mic, \
      default_speaker.player(samplerate=48000) as sp:
    for _ in range(100):
        data = mic.record(numframes=1024)
        sp.play(data)

To actually play or record audio, you must create stream objects from your device handles. These objects are context managers.

For Playback:

• Call _Speaker.play(...) for a quick playback operation.
• Call _Speaker.player() to get a _Player object for more granular control.

For Recording:

• Call _Microphone.record(...) for a quick recording operation.
• Call _Microphone.recorder() to get a _Recorder object for more granular control.

You can discover and select audio devices using the following entry point functions. These return lightweight _Speaker or _Microphone objects.

Speakers (Output):

• default_speaker(): Returns the current system default speaker.
• get_speaker(name): Returns a specific speaker by name.
• all_speakers(): Returns a list of all available speakers.

Microphones (Input):

• default_microphone(): Returns the current system default microphone.
• get_microphone(name): Returns a specific microphone by name.
• all_microphones(): Returns a list of all available microphones.