gstaudiocap 0.1.2

GStreamer-based audio capture and ring buffer for real-time audio processing

gstaudiocap

GStreamer-based audio capture and ring buffer for real-time audio processing.

Features

• Cross-platform audio capture: Works on macOS, Linux, and Windows using GStreamer
• Multi-consumer ring buffer: Single-producer multi-consumer architecture
• Automatic lifecycle management: GStreamer pipeline starts/stops based on consumer registration
• Flexible configuration: Support for custom audio sources, sample rates, channels, and gain

Installation

pip install gstaudiocap

Dependencies

• Python 3.10+
• GStreamer 1.0 with appropriate plugins
• PyGObject
• PyYAML

Usage

Basic Usage

from gstaudiocap import AudioRingBuffer

# Create ring buffer
audio_buffer = AudioRingBuffer(
    device="default",       # macOS default, Linux: "hw:0"
    sample_rate=16000,      # Hz
    channels=1,             # Mono
    gain=1.0,              # No gain
)

# Register consumer
audio_buffer.register_consumer("my_consumer")

# Read audio (16-bit PCM, little-endian)
audio_chunk = audio_buffer.read("my_consumer")

# Unregister consumer (stops pipeline if last consumer)
audio_buffer.unregister_consumer("my_consumer")

Audio Capture Only

from gstaudiocap import AudioCapture

# Create audio capture
capture = AudioCapture(
    device="default",
    sample_rate=16000,
    channels=1,
    gain=1.0,
    audio_source="osxaudiosrc",  # Custom GStreamer source
)

# Start capture
capture.start()

# Read audio
audio_chunk = capture.read()

# Stop capture
capture.stop()

API

AudioRingBuffer

class AudioRingBuffer:
    def __init__(
        self,
        capacity: int = 50,
        device: str = "default",
        sample_rate: int = 16000,
        channels: int = 1,
        gain: float = 1.0,
        audio_source: Optional[str] = None,
    ) -> None

    def register_consumer(self, consumer_id: str) -> None
    def unregister_consumer(self, consumer_id: str) -> None
    def read(self, consumer_id: str) -> Optional[bytes]
    def read_exact(
        self,
        consumer_id: str,
        frame_bytes: int,
        timeout_ms: int = 40,
    ) -> Optional[bytes]

AudioCapture

class AudioCapture:
    def __init__(
        self,
        device: str = "default",
        sample_rate: int = 16000,
        channels: int = 1,
        gain: float = 1.0,
        audio_source: Optional[str] = None,
    ) -> None

    def start(self) -> None
    def stop(self) -> None
    def read(self) -> Optional[bytes]

Platform Support

macOS

• Default device: "default"
• Default source: "osxaudiosrc"

Linux

• Default device: "hw:0"
• Default source: "alsasrc"

Windows

• Default device: "default"
• Default source: "autoaudiosrc" or "directsoundsrc"

Audio Format

All audio is returned as:

• Format: 16-bit PCM, little-endian
• Channels: Mono (1) or Stereo (2)
• Sample Rate: Configurable (default: 16000 Hz)

Development

Build and Upload to PyPI

# 1. Update version in pyproject.toml and src/gstaudiocap/__init__.py
#    (both must match, e.g. "0.2.0")

# 2. Build package
make package

# 3. Check package integrity
make check

# 4. Upload to test PyPI (recommended first)
make upload-test

# 5. Upload to PyPI
make upload

Update Version Number

The version is defined in two places that must be kept in sync:

• pyproject.toml — version = "0.1.0"
• src/gstaudiocap/__init__.py — __version__ = "0.1.0"

After updating both, commit with a message like chore: bump version to 0.2.0, tag the release, then run make upload.

License

MIT License