Metadata-Version: 2.4
Name: micring
Version: 0.1.0
Summary: A unified cross-platform CLI toolkit for the ReSpeaker USB Mic Array (v2.0 / USB 4-Mic): record, DOA, VAD, DSP tuning, LED ring and spectrogram analysis.
Author: RL
License: MIT
Project-URL: Homepage, https://github.com/recklight/micring
Project-URL: Issues, https://github.com/recklight/micring/issues
Keywords: respeaker,microphone-array,doa,beamforming,vad,audio,recording
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pyusb
Requires-Dist: pyaudio
Provides-Extra: analysis
Requires-Dist: librosa; extra == "analysis"
Requires-Dist: matplotlib; extra == "analysis"
Requires-Dist: scipy; extra == "analysis"
Provides-Extra: led
Requires-Dist: pixel-ring; extra == "led"
Provides-Extra: all
Requires-Dist: librosa; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: scipy; extra == "all"
Requires-Dist: pixel-ring; extra == "all"
Dynamic: license-file

# micring

A unified, cross-platform (Windows + Linux/Raspberry Pi) command-line toolkit
for the **ReSpeaker Mic Array v2.0 / USB 4-Mic Array**. It consolidates the
recording, direction-of-arrival, VAD, DSP-tuning, LED-ring and spectrogram
scripts that used to live as separate files into a single `micring` command.

> Hardware: [ReSpeaker Mic Array v2.0](https://wiki.seeedstudio.com/ReSpeaker_Mic_Array_v2.0/)
> (XVF3000, 4 microphones, 12 RGB LEDs, on-board AEC / VAD / DOA / beamforming / NS).

## Install

```bash
pip install -e .            # core: record, devices, doa, vad, tuning
pip install -e ".[analysis]"  # + spectrogram plotting (librosa, matplotlib, scipy)
pip install -e ".[led]"       # + LED ring control (pixel-ring)
pip install -e ".[all]"       # everything
```

After install you get a `micring` command (equivalently `python -m micring`).

### Platform notes
- **Audio capture** works out of the box on Windows, macOS and Linux via PyAudio/PortAudio.
- **DOA / VAD / tuning / LED** use USB control transfers. On Linux/macOS they
  just work; on **Windows** install the `libusb-win32` driver for the
  *SEEED Control* interface using [Zadig](https://zadig.akeo.ie/)
  (select **libusb-win32**, not WinUSB/libusbK).

## Commands

```bash
micring devices                     # list input devices; marks the auto-detected ReSpeaker
micring record -d 5 -o out.wav      # record 5 s (auto-detects the device)
micring record -d 5 --split         # one mono WAV per channel: out_ch0.wav ...
micring record -d 5 --keep 0        # keep only the processed ASR channel
micring record -d 5 --meter         # live level meter while recording
micring doa --csv angles.csv        # stream DOA angle, log to CSV
micring vad                         # stream the on-chip voice-activity flag
micring tuning --list               # list all DSP parameters (no hardware needed)
micring tuning AGCONOFF 0           # turn Automatic Gain Control off
micring tuning DOAANGLE             # read one parameter
micring led trace                   # LED patterns: trace/listen/think/spin/speak/wakeup/off
micring led --color 0xFF0000        # solid colour
micring led --track                 # DOA -> LED linkage: ring colour follows the sound source
micring plot out.wav --save fig.png # waveform + STFT + mel + MFCC
```

Run `micring <command> --help` for the full options of each subcommand.

### Channels & firmware
The 6-channel firmware exposes: **ch0** = processed audio (for ASR),
**ch1-4** = the four raw microphones, **ch5** = playback. Use `--channels 1`
with the 1-channel firmware. Firmware images and the DFU tool are in
[`UpdateFirmware/`](UpdateFirmware/).

## What's included beyond the original scripts
- **Auto device detection** — no more hand-editing `RESPEAKER_INDEX`; the device
  is matched by name (override with `--index`).
- **Live level meter** (`--meter`) and **DOA CSV logging** (`doa --csv`).
- **Software DOA → LED linkage** (`led --track`) in addition to the firmware's
  native `trace` mode.
- **Fixed deprecated APIs** — `np.frombuffer`/`tobytes` (replacing removed
  `np.fromstring`/`tostring`) and `librosa.display.waveshow`.

## Package layout
```
micring/
  cli.py        # argparse entry point (micring …)
  device.py     # PortAudio + USB discovery, auto-detection
  recorder.py   # unified capture, split / combined WAV writing
  tuning.py     # on-chip DSP parameter table + read/write
  doa.py        # DOA streaming + CSV logging
  meter.py      # RMS / dBFS level metering
  led.py        # pixel-ring control + DOA linkage
  plot.py       # waveform / spectrogram / MFCC
```

The original standalone scripts (`record_*.py`, `DOA.py`, `get_index.py`,
`wave_record/`, `LightControl/`) are superseded by this package and can be
removed once you've confirmed the CLI works on your device.

## PyCharm sudo on Linux
On Raspberry Pi, USB access may need root. See the wrapper-script tip for
running the interpreter under `sudo` in
[`docs/linux-sudo.md`](docs/linux-sudo.md).
