Metadata-Version: 2.4
Name: gstaudiocap
Version: 0.1.1
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)

## Development

### Build and Upload to PyPI

```bash
# 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
