gstaudiocap 0.1.0__tar.gz

gstaudiocap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zcl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gstaudiocap-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include src *.py
+recursive-include defaults *.yaml 

gstaudiocap-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: gstaudiocap
+Version: 0.1.0
+Summary: GStreamer-based audio capture and ring buffer for real-time audio processing
+Author-email: alonsolee <lizhenchang@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/alonsolee/gstaudiocap
+Project-URL: Documentation, https://github.com/alonsolee/gstaudiocap#readme
+Project-URL: Repository, https://github.com/alonsolee/gstaudiocap.git
+Project-URL: Issues, https://github.com/alonsolee/gstaudiocap/issues
+Keywords: audio,gstreamer,ring-buffer,real-time,capture
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyGObject>=3.42.0
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# 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
+
+```bash
+pip install gstaudiocap
+```
+
+## Dependencies
+
+- Python 3.10+
+- GStreamer 1.0 with appropriate plugins
+- PyGObject
+- PyYAML
+
+## Usage
+
+### Basic Usage
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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)
+
+## License
+
+MIT License

gstaudiocap-0.1.0/README.md

@@ -0,0 +1,142 @@
+# 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
+
+```bash
+pip install gstaudiocap
+```
+
+## Dependencies
+
+- Python 3.10+
+- GStreamer 1.0 with appropriate plugins
+- PyGObject
+- PyYAML
+
+## Usage
+
+### Basic Usage
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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)
+
+## License
+
+MIT License

gstaudiocap-0.1.0/defaults/gstaudiocap.yaml

@@ -0,0 +1,22 @@
+audio:
+  # Enable audio capture
+  enabled: true
+
+  # Audio device (default for macOS, hw:0 for Linux)
+  device: "hw:0,0"
+
+  # Sample rate in Hz
+  sample_rate: 16000
+
+  # Number of audio channels (1=mono, 2=stereo)
+  channels: 1
+
+  # Audio gain multiplier (1.0 = original volume)
+  gain: 1.0
+
+  # Custom GStreamer audio source (null = auto-detect)
+  # Examples: "osxaudiosrc" (macOS), "alsasrc" (Linux), "autoaudiosrc"
+  audio_source: null
+
+  # Ring buffer capacity (number of chunks)
+  capacity: 50

gstaudiocap-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gstaudiocap"
+version = "0.1.0"
+description = "GStreamer-based audio capture and ring buffer for real-time audio processing"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "alonsolee", email = "lizhenchang@gmail.com"}
+]
+keywords = ["audio", "gstreamer", "ring-buffer", "real-time", "capture"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Multimedia :: Sound/Audio",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+
+dependencies = [
+    "PyGObject>=3.42.0",
+    "PyYAML>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/alonsolee/gstaudiocap"
+Documentation = "https://github.com/alonsolee/gstaudiocap#readme"
+Repository = "https://github.com/alonsolee/gstaudiocap.git"
+Issues = "https://github.com/alonsolee/gstaudiocap/issues"
+
+[tool.setuptools]
+zip-safe = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"gstaudiocap" = ["*.yaml", "*.json"]
+
+[tool.black]
+line-length = 100
+target-version = ['py310', 'py311', 'py312', 'py313']
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false

gstaudiocap-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gstaudiocap-0.1.0/src/gstaudiocap/__init__.py

@@ -0,0 +1,34 @@
+"""GStreamer-based audio capture and ring buffer for real-time audio processing.
+
+This package provides:
+- AudioConfig: Configuration for audio capture
+- AudioCapture: Cross-platform audio capture using GStreamer
+- AudioRingBuffer: Single-producer multi-consumer ring buffer for shared audio
+
+Usage:
+    from gstaudiocap import AudioConfig, AudioCapture, AudioRingBuffer
+
+    # Load config from YAML
+    config = AudioConfig.from_yaml("config.yaml")
+
+    # Create ring buffer from config
+    audio_buffer = AudioRingBuffer(
+        device=config.device,
+        sample_rate=config.sample_rate,
+        channels=config.channels,
+        gain=config.gain,
+    )
+"""
+
+from gstaudiocap.audio_capture import AudioCapture, gstreamer_available
+from gstaudiocap.audio_buffer import AudioRingBuffer
+from gstaudiocap.config import AudioConfig
+
+__all__ = [
+    "AudioConfig",
+    "AudioCapture",
+    "AudioRingBuffer",
+    "gstreamer_available",
+]
+
+__version__ = "0.1.0"

gstaudiocap-0.1.0/src/gstaudiocap/audio_buffer.py

@@ -0,0 +1,177 @@
+"""SPMC ring buffer for shared audio consumption."""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Optional
+
+import yaml
+
+from gstaudiocap.audio_capture import AudioCapture
+
+
+
+class AudioRingBuffer:
+    """Fixed-capacity ring buffer for audio with multi-consumer support."""
+
+    def __init__(
+        self,
+        capacity: int = 50,
+        device: str = "hw:0",
+        sample_rate: int = 16000,
+        channels: int = 1,
+        gain: float = 1.0,
+        audio_source: Optional[str] = None,
+    ) -> None:
+        """Initialize audio ring buffer."""
+        self._capacity = capacity
+        self._slots: list[bytes | None] = [None] * capacity
+        self._write_pos = 0
+        self._cursors: dict[str, int] = {}
+        self._pending_bytes: dict[str, bytearray] = {}
+        self._lock = threading.Lock()
+        self._consumers: set[str] = set()
+        self._reference_count = 0
+        self._audio_capture = AudioCapture(
+            device=device,
+            sample_rate=sample_rate,
+            channels=channels,
+            gain=gain,
+            audio_source=audio_source,
+        )
+        self._running = False
+        self._thread: Optional[threading.Thread] = None
+
+    @classmethod
+    def from_yaml(cls, yaml_path: str, section: str = "audio") -> "AudioRingBuffer":
+        """Load ring buffer config from YAML."""
+        with open(yaml_path, "r", encoding="utf-8") as file:
+            raw = yaml.safe_load(file) or {}
+        payload = raw.get(section, raw)
+        return cls(
+            capacity=int(payload.get("capacity", 50)),
+            device=str(payload.get("device", "hw:0")),
+            sample_rate=int(payload.get("sample_rate", 16000)),
+            channels=int(payload.get("channels", 1)),
+            gain=float(payload.get("gain", 1.0)),
+            audio_source=payload.get("audio_source"),
+        )
+
+    def register_consumer(self, consumer_id: str) -> None:
+        """Register a consumer."""
+        with self._lock:
+            if consumer_id in self._consumers:
+                return
+            self._consumers.add(consumer_id)
+            self._cursors[consumer_id] = self._write_pos
+            self._pending_bytes[consumer_id] = bytearray()
+            self._reference_count += 1
+            if self._reference_count == 1:
+                self._start_pipeline()
+
+    def unregister_consumer(self, consumer_id: str) -> None:
+        """Unregister a consumer."""
+        with self._lock:
+            if consumer_id not in self._consumers:
+                return
+            self._consumers.remove(consumer_id)
+            self._cursors.pop(consumer_id, None)
+            self._pending_bytes.pop(consumer_id, None)
+            self._reference_count -= 1
+            if self._reference_count == 0:
+                self._stop_pipeline()
+
+    def _start_pipeline(self) -> None:
+        """Start audio capture pipeline and read loop."""
+        if self._running:
+            return
+        self._audio_capture.start()
+        self._running = True
+        self._thread = threading.Thread(target=self._read_loop, name="AudioRingBuffer", daemon=True)
+        self._thread.start()
+
+    def _stop_pipeline(self) -> None:
+        """Stop audio capture pipeline and read loop."""
+        if not self._running:
+            return
+        self._running = False
+        self._audio_capture.stop()
+        if self._thread is not None:
+            self._thread.join(timeout=1.0)
+            self._thread = None
+
+    def _read_loop(self) -> None:
+        """Read from capture and write into ring slots."""
+        while self._running:
+            audio_data = self._audio_capture.read()
+            if audio_data:
+                self._write(audio_data)
+            else:
+                time.sleep(0.001)
+
+    def _write(self, audio_data: bytes) -> None:
+        """Write chunk into ring."""
+        with self._lock:
+            self._slots[self._write_pos % self._capacity] = audio_data
+            self._write_pos += 1
+
+    def read(self, consumer_id: str) -> Optional[bytes]:
+        """Read next chunk for one consumer."""
+        with self._lock:
+            cursor = self._cursors.get(consumer_id)
+            if cursor is None:
+                return None
+            if cursor >= self._write_pos:
+                return None
+            behind = self._write_pos - cursor
+            if behind > self._capacity:
+                cursor = self._write_pos - self._capacity
+            audio_data = self._slots[cursor % self._capacity]
+            self._cursors[consumer_id] = cursor + 1
+            return audio_data
+
+    def read_exact(
+        self,
+        consumer_id: str,
+        frame_bytes: int,
+        timeout_ms: int = 40,
+    ) -> Optional[bytes]:
+        """Read fixed-size bytes for one consumer with bounded wait."""
+        if frame_bytes <= 0:
+            return None
+        deadline = time.monotonic() + (timeout_ms / 1000.0)
+        while True:
+            with self._lock:
+                pending = self._pending_bytes.get(consumer_id)
+                if pending is None:
+                    return None
+                if len(pending) >= frame_bytes:
+                    frame = bytes(pending[:frame_bytes])
+                    del pending[:frame_bytes]
+                    return frame
+                cursor = self._cursors.get(consumer_id)
+                if cursor is not None and cursor < self._write_pos:
+                    behind = self._write_pos - cursor
+                    if behind > self._capacity:
+                        cursor = self._write_pos - self._capacity
+                    audio_data = self._slots[cursor % self._capacity]
+                    self._cursors[consumer_id] = cursor + 1
+                    if audio_data:
+                        pending.extend(audio_data)
+                    continue
+            if time.monotonic() >= deadline:
+                with self._lock:
+                    pending = self._pending_bytes.get(consumer_id)
+                    if pending is None:
+                        return None
+                    available = bytes(pending)
+                    pending.clear()
+                if available:
+                    return available + (b"\x00" * (frame_bytes - len(available)))
+                return b"\x00" * frame_bytes
+            time.sleep(0.001)
+
+    def __del__(self):
+        """Cleanup on destruction."""
+        self._stop_pipeline()

gstaudiocap-0.1.0/src/gstaudiocap/audio_capture.py

@@ -0,0 +1,220 @@
+"""GStreamer audio capture module."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+try:
+    import gi
+
+    gi.require_version("Gst", "1.0")
+    gi.require_version("GstApp", "1.0")
+    from gi.repository import Gst, GstApp
+
+    Gst.init(None)
+    _GST_AVAILABLE = True
+except (ImportError, ValueError):
+    _GST_AVAILABLE = False
+
+
+def gstreamer_available() -> bool:
+    """Return whether GStreamer bindings are available."""
+    return _GST_AVAILABLE
+
+
+class AudioCapture:
+    """Audio capture using GStreamer."""
+
+    def __init__(
+        self,
+        device: str = "hw:0",
+        sample_rate: int = 16000,
+        channels: int = 1,
+        gain: float = 1.0,
+        max_buffers: int = 64,
+        audio_source: Optional[str] = None,
+        file_sources: Optional[list[str]] = None,
+        loop_file_sources: bool = False,
+    ) -> None:
+        """Initialize audio capture."""
+        if not _GST_AVAILABLE:
+            raise RuntimeError("GStreamer is not available")
+        self._device = device
+        self._sample_rate = sample_rate
+        self._channels = channels
+        self._gain = gain
+        self._max_buffers = max_buffers
+        self._audio_source = audio_source
+        self._file_sources = [str(Path(p).expanduser()) for p in (file_sources or [])]
+        self._loop_file_sources = loop_file_sources
+        self._pipeline: Optional[Gst.Pipeline] = None
+        self._appsink: Optional[GstApp.AppSink] = None
+        self._running = False
+        self._empty_read_count = 0
+
+    @classmethod
+    def from_yaml(cls, yaml_path: str, section: str = "audio") -> "AudioCapture":
+        """Load audio capture config from YAML."""
+        with open(yaml_path, "r", encoding="utf-8") as file:
+            raw = yaml.safe_load(file) or {}
+        payload = raw.get(section, raw)
+        return cls(
+            device=str(payload.get("device", "hw:0")),
+            sample_rate=int(payload.get("sample_rate", 16000)),
+            channels=int(payload.get("channels", 1)),
+            gain=float(payload.get("gain", 1.0)),
+            max_buffers=int(payload.get("max_buffers", 5)),
+            audio_source=payload.get("audio_source"),
+            file_sources=payload.get("file_sources"),
+            loop_file_sources=bool(payload.get("loop_file_sources", False)),
+        )
+
+    def start(self) -> None:
+        """Start audio capture pipeline."""
+        if self._running:
+            return
+        pipeline_desc = self._build_pipeline_desc()
+        pipeline = Gst.parse_launch(pipeline_desc)
+        if pipeline is None:
+            raise RuntimeError("Failed to create GStreamer pipeline")
+        self._pipeline = pipeline
+        self._appsink = pipeline.get_by_name("audio_sink")
+        pipeline.set_state(Gst.State.PLAYING)
+        self._running = True
+
+    def stop(self) -> None:
+        """Stop audio capture pipeline."""
+        if not self._running:
+            return
+        self._running = False
+        self._cleanup()
+
+    def read(self) -> Optional[bytes]:
+        """Read audio data from the pipeline."""
+        if not self._running or self._appsink is None:
+            return None
+        sample = self._appsink.try_pull_sample(100 * Gst.MSECOND)
+        if not sample:
+            self._empty_read_count += 1
+            if self._file_sources and self._loop_file_sources and self._empty_read_count >= 3:
+                self._restart_file_pipeline()
+            return None
+        self._empty_read_count = 0
+        buffer = sample.get_buffer()
+        success, map_info = buffer.map(Gst.MapFlags.READ)
+        if not success:
+            return None
+        audio_data = bytes(map_info.data)
+        buffer.unmap(map_info)
+        return audio_data
+
+    def _build_pipeline_desc(self) -> str:
+        """Build GStreamer pipeline description."""
+        if self._file_sources:
+            return self._build_file_pipeline_desc()
+        import platform
+
+        if self._audio_source:
+            audio_src = self._audio_source
+        else:
+            system = platform.system()
+            if system == "Darwin":
+                audio_src = "osxaudiosrc"
+            elif system == "Linux":
+                audio_src = "alsasrc"
+            else:
+                audio_src = "autoaudiosrc"
+        device_param = f"device={self._device}" if audio_src == "alsasrc" else ""
+        return (
+            f"{audio_src} {device_param} "
+            f"! audioconvert "
+            f"! audioresample "
+            f"! audio/x-raw,format=S16LE,rate={self._sample_rate},channels={self._channels} "
+            f"! volume name=volume volume={self._gain} "
+            f"! audioconvert "
+            f"! appsink name=audio_sink emit-signals=false max-buffers={self._max_buffers} drop=false sync=false"
+        )
+
+    def _build_file_pipeline_desc(self) -> str:
+        """Build pipeline that reads multiple local audio files."""
+        allowed_suffixes = {
+            ".wav",
+            ".mp3",
+            ".m4a",
+            ".aac",
+            ".flac",
+            ".ogg",
+            ".opus",
+            ".webm",
+        }
+        normalized_files: list[Path] = []
+        for file_source in self._file_sources:
+            candidate = Path(file_source).expanduser().resolve()
+            if not candidate.exists():
+                raise FileNotFoundError(f"Audio file not found: {candidate}")
+            if candidate.suffix.lower() not in allowed_suffixes:
+                raise ValueError(
+                    f"Unsupported audio file type: {candidate}. "
+                    f"Supported: {sorted(allowed_suffixes)}"
+                )
+            normalized_files.append(candidate)
+        if not normalized_files:
+            raise ValueError("file_sources is empty")
+
+        branches: list[str] = []
+        for file_path in normalized_files:
+            file_uri = file_path.as_uri()
+            branches.append(
+                f'uridecodebin uri="{file_uri}" ! audioconvert ! audioresample '
+                f'! audio/x-raw,format=S16LE,rate={self._sample_rate},channels={self._channels} '
+                f'! queue ! audio_concat.'
+            )
+        branches_str = " ".join(branches)
+
+        return (
+            f"{branches_str} "
+            f"concat name=audio_concat "
+            f"! audioconvert "
+            f"! audioresample "
+            f"! audio/x-raw,format=S16LE,rate={self._sample_rate},channels={self._channels} "
+            f"! volume name=volume volume={self._gain} "
+            f"! audioconvert "
+            f"! appsink name=audio_sink emit-signals=false max-buffers={self._max_buffers} drop=false sync=true"
+        )
+
+    def _restart_file_pipeline(self) -> None:
+        """Restart file-based pipeline to loop file sources."""
+        pipeline_desc = self._build_file_pipeline_desc()
+        self._cleanup()
+        pipeline = Gst.parse_launch(pipeline_desc)
+        if pipeline is None:
+            return
+        self._pipeline = pipeline
+        self._appsink = pipeline.get_by_name("audio_sink")
+        pipeline.set_state(Gst.State.PLAYING)
+        self._empty_read_count = 0
+
+    def _cleanup(self) -> None:
+        """Clean up GStreamer resources."""
+        if self._pipeline is None:
+            return
+        try:
+            self._pipeline.send_event(Gst.Event.new_eos())
+            bus = self._pipeline.get_bus()
+            if bus is not None:
+                bus.timed_pop_filtered(
+                    Gst.SECOND, Gst.MessageType.EOS | Gst.MessageType.ERROR
+                )
+        except Exception:
+            pass
+        finally:
+            self._pipeline.set_state(Gst.State.NULL)
+        self._pipeline = None
+        self._appsink = None
+
+    def __del__(self):
+        """Cleanup on destruction."""
+        self.stop()

gstaudiocap-0.1.0/src/gstaudiocap/config.py

@@ -0,0 +1,52 @@
+"""Audio configuration for GStreamer capture."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+@dataclass(slots=True)
+class AudioConfig:
+    """Audio configuration for capture."""
+
+    enabled: bool = True
+    device: str = "hw:0,0"
+    sample_rate: int = 16000
+    channels: int = 1
+    gain: float = 1.0
+    audio_source: Optional[str] = None
+    capacity: int = 50
+
+    @classmethod
+    def from_yaml(cls, yaml_path: Optional[str] = None) -> AudioConfig:
+        """Load configuration from YAML file.
+
+        Args:
+            yaml_path: Path to YAML file. If None, returns default config.
+
+        Returns:
+            AudioConfig instance
+        """
+        if yaml_path is None:
+            return cls()
+
+        if not Path(yaml_path).exists():
+            return cls()
+
+        with open(yaml_path, "r", encoding="utf-8") as f:
+            raw = yaml.safe_load(f) or {}
+
+        audio_data = raw.get("audio", raw)
+        return cls(
+            enabled=bool(audio_data.get("enabled", True)),
+            device=str(audio_data.get("device", "default")),
+            sample_rate=int(audio_data.get("sample_rate", 16000)),
+            channels=int(audio_data.get("channels", 1)),
+            gain=float(audio_data.get("gain", 1.0)),
+            audio_source=audio_data.get("audio_source"),
+            capacity=int(audio_data.get("capacity", 50)),
+        )

gstaudiocap-0.1.0/src/gstaudiocap.egg-info/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: gstaudiocap
+Version: 0.1.0
+Summary: GStreamer-based audio capture and ring buffer for real-time audio processing
+Author-email: alonsolee <lizhenchang@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/alonsolee/gstaudiocap
+Project-URL: Documentation, https://github.com/alonsolee/gstaudiocap#readme
+Project-URL: Repository, https://github.com/alonsolee/gstaudiocap.git
+Project-URL: Issues, https://github.com/alonsolee/gstaudiocap/issues
+Keywords: audio,gstreamer,ring-buffer,real-time,capture
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyGObject>=3.42.0
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# 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
+
+```bash
+pip install gstaudiocap
+```
+
+## Dependencies
+
+- Python 3.10+
+- GStreamer 1.0 with appropriate plugins
+- PyGObject
+- PyYAML
+
+## Usage
+
+### Basic Usage
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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)
+
+## License
+
+MIT License

gstaudiocap-0.1.0/src/gstaudiocap.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+defaults/gstaudiocap.yaml
+src/gstaudiocap/__init__.py
+src/gstaudiocap/audio_buffer.py
+src/gstaudiocap/audio_capture.py
+src/gstaudiocap/config.py
+src/gstaudiocap.egg-info/PKG-INFO
+src/gstaudiocap.egg-info/SOURCES.txt
+src/gstaudiocap.egg-info/dependency_links.txt
+src/gstaudiocap.egg-info/not-zip-safe
+src/gstaudiocap.egg-info/requires.txt
+src/gstaudiocap.egg-info/top_level.txt

gstaudiocap-0.1.0/src/gstaudiocap.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gstaudiocap-0.1.0/src/gstaudiocap.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

gstaudiocap-0.1.0/src/gstaudiocap.egg-info/requires.txt

@@ -0,0 +1,2 @@
+PyGObject>=3.42.0
+PyYAML>=6.0

gstaudiocap-0.1.0/src/gstaudiocap.egg-info/top_level.txt

@@ -0,0 +1 @@
+gstaudiocap