gr.Microphone — a record-only audio component in one line

$ import gradio as gr
import numpy as np


def clip_report(audio):              # one component -> one argument
    if audio is None:                # user cleared the take
        return {"status": "no clip"}
    sr, data = audio                 # type='numpy' default: (int rate, int16 array)
    mono = data.mean(axis=1) if data.ndim > 1 else data
    return {
        "sample_rate": int(sr),
        "frames": int(data.shape[0]),
        "seconds": round(data.shape[0] / sr, 3),
        "channels": int(data.shape[1]) if data.ndim > 1 else 1,
        "peak": int(np.abs(mono).max()),
        "clipped": bool(np.abs(mono).max() >= 32767),
    }


with gr.Blocks(title="Voicemail QA") as demo:
    gr.Markdown("## Voicemail QA")
    mic = gr.Microphone(label="hold to record")
    out = gr.JSON(label="what your handler gets")
    mic.stop_recording(clip_report, mic, out, api_name="report")
    mic.clear(lambda: None, None, out, api_name="reset")

demo.launch(prevent_thread_lock=True, server_port=7921)

* Running on local URL:  http://127.0.0.1:7921
* To create a public link, set `share=True` in `launch()`.

Renders: a 'Voicemail QA' heading, an audio widget labeled 'hold to record' that has ONLY the microphone tab (no upload dropzone — the served /config shows sources=['microphone'], format='wav', streaming=False), and a JSON panel labeled 'what your handler gets'. The served /config lists two dependencies: [2,'stop_recording'] api_name='report' and [2,'clear'] api_name='reset'. Driving /report with gradio_client and a real 1.5 s 220 Hz WAV (24000 frames @ 16 kHz) returned exactly {'sample_rate': 16000, 'frames': 24000, 'seconds': 1.5, 'channels': 1, 'peak': 19660, 'clipped': False}.

Verified on gradio 6.27.0 — that dict is the real event payload from the live app. The clip was generated with stdlib wave at 60% amplitude, so peak 19660 is the actual sample maximum, not a rounded guess.

$ import gradio as gr


def echo_path(p):
    import os
    if p is None:
        return "-"
    return "%s | %d bytes" % (os.path.basename(str(p)), os.path.getsize(str(p)))


with gr.Blocks(title="wav-or-not") as demo:
    gr.Markdown("## default format: Microphone vs Audio")
    with gr.Row():
        mic = gr.Microphone(type="filepath", label="gr.Microphone (format default 'wav')")
        aud = gr.Audio(type="filepath", label="gr.Audio (format default None)")
    a = gr.Textbox(label="mic got")
    b = gr.Textbox(label="audio got")
    mic.change(echo_path, mic, a, api_name="mic_path")
    aud.change(echo_path, aud, b, api_name="audio_path")

demo.launch(prevent_thread_lock=True, server_port=7925)

* Running on local URL:  http://127.0.0.1:7925
* To create a public link, set `share=True` in `launch()`.

Renders: a Row with two filepath-mode audio components side by side (the Microphone one still exposes only the mic tab) and two Textboxes below them. Calling the live endpoints with the SAME 4977-byte mp3: /mic_path returned 'audio.wav | 48044 bytes' and /audio_path returned 'audio.mp3 | 4977 bytes'. Both handlers received a file, but only one received the file they uploaded.

This is the practical cost of the wav default: format='wav' on the Microphone made preprocess transcode the mp3 to a 48 kB wav before the handler saw it, while gr.Audio passed the original bytes through untouched. Set format=None on a Microphone to opt out — verified, the attribute then reads None.

$ import gradio as gr
import numpy as np


def level(audio):                    # ONE argument — the (sample_rate, chunk) tuple
    if audio is None:
        return "idle"
    sr, chunk = audio
    if chunk is None or len(chunk) == 0:
        return "silence"
    rms = float(np.sqrt((np.asarray(chunk, dtype=np.float64) ** 2).mean()))
    return "%.1f dBFS" % (20 * np.log10(max(rms, 1) / 32768))


with gr.Blocks(title="Live dictation meter") as demo:
    gr.Markdown("## Live dictation meter")
    mic = gr.Microphone(streaming=True, label="live mic")
    lvl = gr.Textbox(label="level")
    log = gr.Textbox(label="recorder log", lines=4)
    mic.stream(level, mic, lvl, api_name="level")
    mic.start_recording(lambda: "recording started", None, log, api_name="armed")
    mic.stop_recording(lambda: "recording stopped", None, log, api_name="stopped")

demo.launch(prevent_thread_lock=True, server_port=7922)

* Running on local URL:  http://127.0.0.1:7922
* To create a public link, set `share=True` in `launch()`.

Renders: a mic-only audio widget labeled 'live mic' with streaming enabled (served /config: sources=['microphone'], streaming=True, format='wav') and two Textboxes. The /config dependencies show the difference in wiring: the stream dependency is ([[2,'stream']], 'level', connection='stream', stream_every=0.5) while the two recorder events are plain sse dependencies named 'armed' and 'stopped'. Calling level() directly with a real 0.5 s 220 Hz chunk (60% amplitude) returned '-7.4 dBFS'; level(None) returned 'idle'; level((16000, np.array([], dtype=np.int16))) returned 'silence'.

The wrong signature is the classic trap: wiring `def bad(s, c)` to a single Microphone logs 'UserWarning: Expected 2 arguments for function <function bad>, received 1' plus 'Expected at least 2 arguments … received 1' — and the app still launches, quietly filling the missing argument with None on every tick (reproduced in this run). One component, one argument.

$ import gradio as gr
import numpy as np
import time


def on_start():
    return "started at " + time.strftime("%H:%M:%S")


def keep(audio):                     # runs once, on the button click
    if audio is None:
        return None, "nothing recorded"
    sr, data = audio
    return (sr, data), "%d frames @ %d Hz = %.2f s" % (data.shape[0], sr, data.shape[0] / sr)


with gr.Blocks(title="Voice memo") as demo:
    gr.Markdown("## Voice memo — record, inspect, play back")
    with gr.Row():
        mic = gr.Microphone(label="memo")
        play = gr.Audio(label="playback", type="numpy", editable=False)
    info = gr.Textbox(label="clip info")
    stamps = gr.Textbox(label="recorder events")
    mic.start_recording(on_start, None, stamps, api_name="started")
    mic.stop_recording(lambda: "stopped at " + time.strftime("%H:%M:%S"), None, stamps, api_name="stopped")
    btn = gr.Button("Keep this memo", variant="primary")
    btn.click(keep, mic, [play, info], api_name="keep")

demo.launch(prevent_thread_lock=True, server_port=7923)

* Running on local URL:  http://127.0.0.1:7923
* To create a public link, set `share=True` in `launch()`.

Renders: a 'Voice memo' heading, a Row with the recorder labeled 'memo' next to a non-editable player labeled 'playback', then two Textboxes ('clip info', 'recorder events') and a primary Button 'Keep this memo'. Startup emits two UserWarnings naming the handler: 'Expected 1 arguments for function <function on_stop>, received 0' and 'Expected at least 1 arguments … received 0' — a recorder event wired with no input components still launches, it just cannot receive the clip.

The tuple returned by keep() lands in the player as a cache file, and because gr.Audio there has format=None the wav is passed straight through. Bonus, verified in the same run: a Microphone can also be an output — .click(push, None, mic) served the synthesized clip as '…/gradio/43a95c34…/audio.wav'. It is the format='wav' default doing that re-encode, not a rule about inputs.