SoundGraph 0.2__tar.gz → 0.3.0__tar.gz

soundgraph-0.3.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to SoundGraph are documented here.
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.2.0] — 2024-03-04
+
+### Added
+- Proper Python package structure under `soundgraph/`
+- `soundgraph.visualizer` — core real-time waveform plotting via Matplotlib animation
+- `soundgraph.recognizer` — `VoiceCommandListener` background thread using a shared audio queue
+- CLI entry point: `soundgraph` (and `python -m soundgraph`) with `--rate`, `--chunk`, `--phrase-seconds`, `--verbose`, `--version` flags
+- Reactive waveform colour: shifts from blue → red as volume increases
+- Clean shutdown on window close or "stop" voice command
+- `pyproject.toml` + `setup.cfg` modern packaging
+- Full test suite with hardware mocking
+
+### Fixed
+- **Dual microphone conflict** — original code opened two separate mic streams (PyAudio + SpeechRecognition) simultaneously, causing device errors on many systems. Fixed by sharing a single PyAudio callback stream via a thread-safe queue.
+
+---
+
+## [0.1.0] — 2024-01-01 *(initial sketch)*
+
+### Added
+- Basic real-time audio visualizer using PyAudio + Matplotlib
+- Simple voice "stop" command via SpeechRecognition

{SoundGraph-0.2 → soundgraph-0.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Al Mustafiz Bappy
+Copyright (c) 2024 Al Mustafiz Bappy
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

soundgraph-0.3.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include requirements.txt
+recursive-include soundgraph *.py py.typed

soundgraph-0.3.0/PKG-INFO

@@ -0,0 +1,178 @@
+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)

soundgraph-0.3.0/README.md

@@ -0,0 +1,147 @@
+# 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)

soundgraph-0.3.0/SoundGraph.egg-info/PKG-INFO

@@ -0,0 +1,178 @@
+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)

soundgraph-0.3.0/SoundGraph.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+requirements.txt
+setup.cfg
+setup.py
+SoundGraph.egg-info/PKG-INFO
+SoundGraph.egg-info/SOURCES.txt
+SoundGraph.egg-info/dependency_links.txt
+SoundGraph.egg-info/entry_points.txt
+SoundGraph.egg-info/requires.txt
+SoundGraph.egg-info/top_level.txt
+soundgraph/__init__.py
+soundgraph/__main__.py
+soundgraph/py.typed
+soundgraph/recognizer.py
+soundgraph/recorder.py
+soundgraph/spectrum.py
+soundgraph/themes.py
+soundgraph/visualizer.py
+tests/test_soundgraph.py

soundgraph-0.3.0/SoundGraph.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+soundgraph = soundgraph.__main__:main

soundgraph-0.3.0/SoundGraph.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy>=1.21
+matplotlib>=3.4
+SpeechRecognition>=3.8
+pyaudio>=0.2.11

soundgraph-0.3.0/SoundGraph.egg-info/top_level.txt

@@ -0,0 +1 @@
+soundgraph

soundgraph-0.3.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"

soundgraph-0.3.0/requirements.txt

@@ -0,0 +1,9 @@
+# Runtime dependencies
+numpy>=1.21
+matplotlib>=3.4
+SpeechRecognition>=3.8
+pyaudio>=0.2.11
+
+# Development / testing
+pytest>=7.0
+pytest-mock>=3.10

soundgraph-0.3.0/setup.cfg

@@ -0,0 +1,47 @@
+[metadata]
+name = SoundGraph
+version = 0.3.0
+author = Al Mustafiz Bappy
+author_email = almustafizbappy@gmail.com
+description = Real-time audio waveform visualizer with voice-command stop
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/bappy-3/sound-graph
+license = MIT
+keywords = audio, visualization, waveform, speech-recognition, microphone, real-time
+classifiers = 
+	Development Status :: 4 - Beta
+	Environment :: Console
+	Intended Audience :: Developers
+	Intended Audience :: Science/Research
+	License :: OSI Approved :: MIT License
+	Operating System :: OS Independent
+	Programming Language :: Python :: 3
+	Programming Language :: Python :: 3.8
+	Programming Language :: Python :: 3.9
+	Programming Language :: Python :: 3.10
+	Programming Language :: Python :: 3.11
+	Programming Language :: Python :: 3.12
+	Topic :: Multimedia :: Sound/Audio :: Analysis
+	Topic :: Scientific/Engineering :: Visualization
+
+[options]
+packages = soundgraph
+python_requires = >=3.8
+install_requires = 
+	numpy>=1.21
+	matplotlib>=3.4
+	SpeechRecognition>=3.8
+	pyaudio>=0.2.11
+
+[options.entry_points]
+console_scripts = 
+	soundgraph = soundgraph.__main__:main
+
+[options.package_data]
+soundgraph = py.typed
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

soundgraph-0.3.0/setup.py

@@ -0,0 +1,5 @@
+# Minimal setup.py shim for legacy pip / tooling compatibility.
+# All real metadata lives in setup.cfg and pyproject.toml.
+from setuptools import setup
+
+setup()

soundgraph-0.3.0/soundgraph/__init__.py

@@ -0,0 +1,35 @@
+"""
+SoundGraph
+==========
+Real-time audio waveform visualizer with voice-command stop.
+
+Quick start::
+
+    import soundgraph
+    soundgraph.start()
+
+Full options::
+
+    soundgraph.start(
+        mode='both',       # 'waveform' | 'spectrum' | 'both'
+        theme='neon',      # 'dark' | 'light' | 'neon'
+        record=True,       # save session to WAV
+        output='out.wav',  # custom WAV path
+        device=2,          # input device index
+    )
+
+    soundgraph.list_devices()  # print available mic/input devices
+"""
+
+from soundgraph.visualizer import start_visualization, list_devices
+
+# Short-form alias — the recommended way to use SoundGraph
+start = start_visualization
+
+__version__ = "0.3.0"
+__author__ = "Al Mustafiz Bappy"
+__email__ = "almustafizbappy@gmail.com"
+__license__ = "MIT"
+__url__ = "https://github.com/bappy-3/sound-graph"
+
+__all__ = ["start", "start_visualization", "list_devices", "__version__"]