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 (XVF3000, 4 microphones, 12 RGB LEDs, on-board AEC / VAD / DOA / beamforming / NS).

Install

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 (select libusb-win32, not WinUSB/libusbK).

Commands

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/.

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.