SoundGraph

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

pip install SoundGraph

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

Quick Start

import soundgraph

soundgraph.start()

That's it.

Features

Usage

Python API

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

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

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

License

MIT © Al Mustafiz Bappy