Metadata-Version: 2.1
Name: SoundGraph
Version: 0.3.0
Summary: Real-time audio waveform visualizer with voice-command stop
Home-page: https://github.com/bappy-3/sound-graph
Author: Al Mustafiz Bappy
Author-email: almustafizbappy@gmail.com
License: MIT
Keywords: audio,visualization,waveform,speech-recognition,microphone,real-time
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: matplotlib>=3.4
Requires-Dist: SpeechRecognition>=3.8
Requires-Dist: pyaudio>=0.2.11

# SoundGraph

[![PyPI version](https://badge.fury.io/py/SoundGraph.svg)](https://pypi.org/project/SoundGraph/)
[![Python](https://img.shields.io/pypi/pyversions/SoundGraph)](https://pypi.org/project/SoundGraph/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**SoundGraph** is a Python package that visualizes your microphone audio as a **live waveform** in real-time.

Make noise → see the wave. Say **"stop"** (or close the window) → exits cleanly.

---

## Installation

```bash
pip install SoundGraph
```

> **macOS** — install PortAudio first: `brew install portaudio`  
> **Linux** — `sudo apt-get install portaudio19-dev python3-pyaudio`

---

## Quick Start

```python
import soundgraph

soundgraph.start()
```

That's it.

---

## Features

| Feature | Description |
|---|---|
| **Visualization modes** | Waveform, frequency spectrum, or both side-by-side |
| **Color themes** | `dark`, `light`, `neon` |
| **Live dB meter** | Real-time decibel level bar at the bottom |
| **Record to WAV** | Save your session to a file while visualizing |
| **Device selection** | Pick any connected microphone by index |
| **Voice stop** | Say "stop" to exit hands-free |

---

## Usage

### Python API

```python
import soundgraph

# Waveform + spectrum side-by-side, neon theme
soundgraph.start(mode='both', theme='neon')

# Record while visualizing
soundgraph.start(record=True, output='session.wav')

# List available input devices, then use one
soundgraph.list_devices()
soundgraph.start(device=2)

# All options
soundgraph.start(
    mode='both',           # 'waveform' | 'spectrum' | 'both'
    theme='dark',          # 'dark' | 'light' | 'neon'
    record=True,           # save to WAV
    output='out.wav',      # custom output path
    device=0,              # input device index
    sample_rate=44100,     # Hz
    chunk=2048,            # frames per update
    phrase_seconds=1.5,    # seconds per recognition attempt
)
```

### Command Line

```bash
soundgraph                              # default waveform, dark theme
soundgraph --mode both --theme neon     # spectrum + waveform, neon
soundgraph --record --output out.wav    # record while visualizing
soundgraph --list-devices               # print available mics
soundgraph --device 2                   # use mic at index 2
```

All flags:

```
--mode, -m       waveform | spectrum | both   (default: waveform)
--theme, -t      dark | light | neon          (default: dark)
--record, -r     Record session to WAV
--output, -o     Output WAV path              (default: auto-named)
--device, -d     Input device index
--list-devices   List available input devices and exit
--rate           Sample rate in Hz            (default: 44100)
--chunk          Frames per update            (default: 2048)
--phrase-seconds Seconds per recognition      (default: 1.5)
--verbose, -v    Debug logging
--version        Show version
```

---

## How It Works

```
Microphone
    │
    ▼
PyAudio stream (single handle)
    │
    ├──► viz_queue    → Matplotlib animation   (main thread)
    ├──► speech_queue → VoiceCommandListener   (background thread)
    └──► record_queue → AudioRecorder          (background thread, if --record)
```

The waveform colour shifts from **blue → red** as your volume increases.  
The dB meter at the bottom turns green → yellow → red as level rises.

---

## Requirements

| Package | Purpose |
|---|---|
| `pyaudio` | Live microphone capture |
| `numpy` | PCM byte → number conversion |
| `matplotlib` | Animated waveform / spectrum plot |
| `SpeechRecognition` | Voice "stop" command detection |

---

## Contributing

1. Fork → `git checkout -b feature/my-feature`
2. Make changes, add tests in `tests/`
3. `pytest tests/ -v` — all tests must pass
4. Pull request → [github.com/bappy-3/sound-graph](https://github.com/bappy-3/sound-graph)

---

## License

MIT © [Al Mustafiz Bappy](https://github.com/bappy-3)
