Skip to main content

jupyterlab_voice_capture_extension

GitHub Actions npm version PyPI version Total PyPI downloads JupyterLab 4 Brought To You By KOLOMOLO Donate PayPal

Capture microphone audio in the JupyterLab browser tab and stream it to a server-side FIFO, so terminal applications running inside the container - notably Claude Code voice mode - can record from a microphone the container itself has no access to.

The container has no capture device; the browser does. This extension bridges that gap: the browser captures the mic, ships the audio over an authenticated websocket to a Jupyter server handler, and the handler writes raw PCM to a named pipe. A separate, out-of-scope plumbing layer (PulseAudio module-pipe-source + SoX) turns that pipe into the system default audio source.

How it works

  • Capture - a microphone toggle in the status bar calls getUserMedia; the AudioContext resamples to 16 kHz; an AudioWorklet downmixes to mono and encodes signed 16-bit little-endian PCM off the UI thread
  • Transport - 20 ms PCM frames (640 bytes) are sent as binary websocket messages to …/jupyterlab-voice-capture-extension/stream, which lives under the Jupyter base URL and inherits Jupyter token auth - no new port is opened
  • Sink - the server handler writes each frame, in order, to a FIFO (default /run/voice/pulseaudio.fifo); the PulseAudio reader creates the pipe (module-pipe-source refuses a pre-existing one), so the handler attaches as writer, waits for the pipe to appear, and tolerates a not-yet-attached reader without blocking the server
  • Speaker - a program in the container that plays to the default PulseAudio sink (voiceout, a module-pipe-sink) writes s16le, 48 kHz, stereo PCM to speaker.fifo in the directory of the sink FIFO (default /run/voice/speaker.fifo); a server thread reads it and sends it as binary websocket messages to …/jupyterlab-voice-capture-extension/speaker, under the same token auth; an AudioWorklet in each open JupyterLab tab plays it. While no tab listens, the server discards what it reads, so a tab hears live audio only

Chain: browser mic → AudioWorklet (16 kHz mono s16le) → websocket → server handler → FIFO → (PulseAudio + SoX, out of scope) → terminal app.

Speaker chain: program in the container → (PulseAudio voiceout, out of scope) → speaker.fifo (48 kHz stereo s16le) → server reader → websocket → AudioWorklet → tab audio output.

Requirements

  • JupyterLab >= 4.6.0
  • A secure context (https or localhost) - browsers only expose the microphone over a secure origin

Install

pip install jupyterlab-voice-capture-extension

Dependencies

  • Python: jupyter_server and traitlets, installed automatically with the package
  • System (only for the full voice chain into a terminal app and for the speaker): PulseAudio + SoX for the voice chain; the speaker needs only PulseAudio (paplay comes from pulseaudio-utils). Provision and verify them with the bundled CLI:
jupyterlab_voice_capture install    # apt packages + /run/voice dir + client.conf + Jupyter config line (does NOT start the daemon)
jupyterlab_voice_capture start -d   # start the PulseAudio daemon + pipe-source + voicedrain loopback that keeps it reading + voiceout pipe-sink as the default sink (run after install and each restart)
jupyterlab_voice_capture validate   # check every component, print what to fix (--json for machine output)
jupyterlab_voice_capture stop       # kill the PulseAudio daemon

See docs/jupyterlab-enable-claude-voice.md for the full setup and troubleshooting.

Usage

  • Click the microphone icon in the status bar (or run Toggle Voice Capture from the command palette) to start capture
  • On the first start the browser asks for microphone permission; the state shows through the icon and its tooltip (Disconnected → Connecting → Connected), the icon glows green while streaming, and the browser shows its active-microphone indicator
  • Click again to stop - capture tracks are released and the browser indicator clears
  • In the Error state (blinking icon) a click disconnects and returns the control to Disconnected, shown in the tooltip; click once more to start capture again
  • Only one tab streams at a time: starting capture in a second tab takes over and stops the first
  • Playback is always on, with no on/off control and no setting: every tab starts it when JupyterLab loads, and sound that a program in the container plays to the default PulseAudio sink (for example paplay <file>) is heard in the tab
  • Sound plays as soon as it arrives in a browser that allows sound without a gesture (Chrome with the autoplay policy no-user-gesture-required), and in any browser after any click or key press anywhere in the tab, panels and frames included. In a browser that blocks autoplay, a tab nobody has clicked or typed in since it loaded may stay silent; sound sent more than 0.5 s before the first click or key press is dropped
  • Every open JupyterLab browser tab plays the sound; opening another tab stops none of them
  • The status bar pill holds the microphone toggle, a play/stop control and a pause control: while a file plays both controls are enabled and the first shows stop; while paused the first shows play and resumes; with nothing playing both are disabled and greyed
  • When the speaker FIFO is missing, so the audio sink was never loaded, the play control in the pill blinks in the warning colour for 30 seconds and its tooltip names the missing FIFO and jupyterlab_voice_capture start -d, then it reads disabled with the reason left in the tooltip
  • The command voice-capture:player drives the container player and returns its state: play with a path relative to the Jupyter root queues an mp3 or wav file and starts it when nothing plays, mode: "now" starts it at once, mixed with every file already playing, pause and resume stop and continue every playing file at its position, stop ends every playing file and keeps the queue, clear removes the queue, and status reports paused, stopped, playing with ids and positions, and queue. A missing or undecodable file, a path outside the root or an unknown action is refused with the reason and changes nothing. The palette entry Stop All Audio in category Voice Capture runs the command with {"action": "stop"}. From a terminal: jupyterlab-commands execute voice-capture:player --args '{"action": "play", "path": "<file>"}', which runs only after voice-capture:player is added to the allowedCommands setting of @stellarshenson/jupyterlab-commands-extension:plugin
  • The commands voice-capture:enable (label Enable Voice Capture) and voice-capture:disable (label Disable Voice Capture) start capture in the tab that runs voice-capture:enable and stop capture in every open tab, for terminal programs such as Claude Code /voice. voice-capture:enable returns once capture streams, fails with the error message (for example Microphone permission denied.) when capture turns to Error, and does nothing when capture already streams; voice-capture:disable does nothing when capture is already off. From a terminal: jupyterlab-commands execute voice-capture:enable, which, like voice-capture:player, runs only after the command is added to the allowedCommands setting

Agent skill

The skill in .agents/skills/jupyterlab-voice-capture-extension tells an AI agent how to play a sound in the JupyterLab browser tab and where the help of jupyterlab_voice_capture is. pip install puts a copy in <sys.prefix>/share/jupyter/agents/skills/jupyterlab-voice-capture-extension.

Configuration

The sink FIFO path defaults to /run/voice/pulseaudio.fifo and is overridable via Jupyter server config:

c.VoiceCapture.sink_path = "/run/voice/pulseaudio.fifo"

Settings → Voice Capture has one option, Auto-connect on startup (autoConnect, default off): when enabled, capture starts automatically as JupyterLab loads instead of waiting for a click.

Uninstall

pip uninstall jupyterlab-voice-capture-extension

Troubleshoot

If you see the frontend extension but it is not working, check that the server extension is enabled:

jupyter server extension list

If the server extension is installed and enabled but you do not see the frontend extension, check the frontend extension is installed:

jupyter labextension list

Contributing

If you would like to contribute to this extension, please refer to the Contributing Guide.

Metadata

Release files for jupyterlab-voice-capture-extension 1.1.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jupyterlab-voice-capture-extension 1.1.5
File Size Uploaded Provenance Actions
jupyterlab_voice_capture_extension-1.1.5.tar.gz 452.8 kB Without provenance Details for jupyterlab_voice_capture_extension-1.1.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jupyterlab-voice-capture-extension 1.1.5
File Interpreter ABI Platform Actions
jupyterlab_voice_capture_extension-1.1.5-py3-none-any.whl Python 3 none any Details for jupyterlab_voice_capture_extension-1.1.5-py3-none-any.whl

Total release size: 546.2 kB

Release files / jupyterlab_voice_capture_extension-1.1.5.tar.gz

Download URL jupyterlab_voice_capture_extension-1.1.5.tar.gz
Size 452.8 kB
Tags Source
SHA-256 checksum
How to use checksums
e99b77f2e04bf20af0ace0273c3a9ac304feb4198b52a3f7814a6d794c0395e4
BLAKE2b-256 checksum
How to use checksums
c4ed96024f1989502e8ffd8808a805730358d7f7821f10edd52eeec4f7b8592f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / jupyterlab_voice_capture_extension-1.1.5-py3-none-any.whl

Download URL jupyterlab_voice_capture_extension-1.1.5-py3-none-any.whl
Size 93.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3c2b0926ec47a3b25599ed6b968cd8f53560418b082a0047675bd488d09aeb4a
BLAKE2b-256 checksum
How to use checksums
0f495b889915eef102bee4368d2a249b23bc6808f4e4b6265b53fbff676ca2b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for jupyterlab-voice-capture-extension 1.1.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page