lab-mic 0.2.0

Record audio directly within Jupyter/IPython/Colab using the browser microphone and ffmpeg.

Lab Mic

Record audio directly within Jupyter Notebooks, JupyterLab, Google Colab, or other IPython environments using your browser's microphone. This package provides an ipywidgets-based interface, captures audio using standard browser APIs, and leverages ffmpeg for reliable conversion to WAV format (16-bit PCM mono).

Features

• Simple ipywidgets interface for recording start/stop within notebooks.
• Captures audio directly in the browser using getUserMedia and MediaRecorder.
• Uses ffmpeg for robust conversion from web formats (like webm/opus) to WAV (16-bit PCM, mono).
• Works across different Jupyter environments including Colab.
• Allows specifying the target sampling rate for the output.
• Returns the final audio data conveniently as a NumPy array.
• Includes basic UI feedback for status and errors.

Installation

1. Install ffmpeg:

This package requires the ffmpeg command-line tool to be installed on the system where the Python kernel is running (this includes the Colab runtime if using Colab). ffmpeg must be accessible in the system's PATH.

• Ubuntu/Debian: sudo apt update && sudo apt install ffmpeg
• macOS (using Homebrew): brew install ffmpeg
• Windows: Download from the official ffmpeg website, extract, and add the bin directory to your system's PATH.
• Google Colab: ffmpeg is usually pre-installed on Colab runtimes.

2. Install the Python package:

Install lab_mic using pip. This will also install required Python dependencies (numpy, scipy, ffmpeg-python, ipython, ipywidgets).

pip install lab_mic

Usage

from lab_mic import LabMic

# Create an instance of LabMic
mic = LabMic()

# Start recording
mic.start_recording()

# Stop recording after a specified duration (e.g., 5 seconds)
mic.stop_recording(duration=5)

# Get the recorded audio data as a NumPy array
audio_data = mic.get_audio_data()

# Save the recorded audio to a file (optional)
mic.save_to_file("output.wav")

Example in Jupyter Notebook

from lab_mic import LabMic

# Initialize the microphone recorder
mic = LabMic(sampling_rate=16000)

print("Displaying recording interface...")
# --- Display the Interface ---
# This will show the button and status/preview area in the cell output
mic.display()

# --- Get the Processed Audio ---
audio_data = mic.get_result()

How it Works

The NotebookMic (or similarly named class) uses ipywidgets to create interactive elements (Button, Output area, hidden Text widget) in the notebook frontend. When initiated, it injects HTML and JavaScript code into the ipywidgets.Output area.
The JavaScript utilizes the browser's navigator.mediaDevices.getUserMedia to request microphone access and MediaRecorder to capture audio (typically in formats like webm/opus). Upon stopping, the recorded audio data is encoded into a Base64 Data URL by the JavaScript.
This Data URL is sent back to the Python kernel by setting the .value of the hidden ipywidgets.Text widget.
A Python observer callback (_handle_received_data within the class) detects the change in the Text widget's value.
The Python code decodes the Base64 data.
It uses the ffmpeg-python library to execute the external ffmpeg command, piping the received audio binary data in and piping the converted WAV audio data out. The resulting WAV data (as bytes) is parsed, potentially resampled or type-converted, and loaded into a NumPy array using scipy.io.wavfile and numpy.
The final NumPy array (int16 PCM) is stored and made accessible via the .get_result() method.

License

This project is licensed under the MIT License.

Author

voidful [e-mail]