Skip to main content

nbplay

let's play!

Build Status codecov License PyPI Binder

Overview

Music composition widgets in a jupyter notebook

Try it in your browser: the live demo runs the example notebooks on JupyterLite with nbplay compiled to WebAssembly. Nothing to install; open a notebook and run it top to bottom. The web app runs a demo session the same way, as a page of panels with no notebook.

nbplay is a set of Jupyter widgets that together form a small DAW in the browser: synths, samplers, step sequencers, a QWERTY and a MIDI keyboard, trigger pads, a transport, a multitrack timeline that records audio and MIDI, a clip launcher, and a mixer. Every widget in a session follows one clock that lives in the browser, so play, seek, and tempo changes never wait on the kernel. The widgets are spaday widgets on transports models, with no extension to install; they work in JupyterLab, Notebook, VS Code, Voila, and JupyterLite. A session can be saved to a .nbplay archive and loaded back:

session.timeline.export_all_clips()   # pull recorded takes from the browser
# ... once session.timeline.pending_exports == 0
session.save("song.nbplay")
session = nb.Session.load("song.nbplay")

Mixer channels and the master bus have Web Audio insert chains with built-in gain, filter, compressor, limiter, delay, and reverb effects; you can register your own browser plugin factories as well. Effect descriptors must be JSON-safe, and the built-in effect names are reserved. When Web Audio or Web MIDI is unavailable the widgets still render and their controls keep working; they are silent until the browser provides those APIs.

import nbplay as nb

session = nb.Session(bpm=120, theme="studio")   # or "flat", "cube", "one", "grim", "pro", "fruit"; "" follows Jupyter
drums = session.add_track("Drums", nb.SequencerWidget(num_voices=2), nb.SamplerWidget())
vocals = session.add_track("Vocals", armed=True)      # microphone lane
keys = session.add_track("Keys", input="midi", armed=True)  # records note events

session.mixer.add_channel_effect(
    drums.mixer_channel,
    nb.EffectPlugin("compressor", threshold=-18, ratio=4),
)
session.mixer.add_master_effect(nb.EffectPlugin("limiter", threshold=-1))

session.timeline.length = 64
session.timeline.count_in_bars = 1
session.launcher.add_scene("Intro")
session.launcher.set_slot(drums.mixer_channel, 0, drums.sequencer, name="Beat")

session.play()   # or press play on any widget; they share the clock

Song structure comes from named patterns: session.add_pattern("verse", drums.sequencer), then session.chain(drums, ["verse", "verse", "chorus"]) lays them out as clips on the track's timeline lane, and the sequencer stops looping on its own so the arrangement drives it.

Each widget hosts a validated config model in the kernel (synth.config.frequency = 220.0, seq.config.length) and, where the browser owns state, a status model it only reads (session.transport.status.is_playing). Edits made in the browser are validated by the same model before they land, and widget.on_change(listener, names=...) reports changes from either side. session.play(), launcher.launch(0, 0) or midi_out.note_on(60) is a transports command delivered to the browser widget that owns the state.

Samplers hold one main sample plus zones, each mapping a key and velocity range to its own audio: sampler.add_zone_file("kick.wav", 36, 36), or press Rec in the sampler to record the microphone straight onto a pad, or sampler.capture_clip(session.timeline, clip_id, pad=0) to move a recorded take onto one.

MidiOutputWidget sends what the session plays to a hardware synth or another app over Web MIDI, and MidiLearn maps hardware knobs to widget config fields (MidiLearn(midi_keyboard).learn(synth, "frequency", low=100, high=2000), then turn a knob). The session can lead external gear with MIDI clock (send_clock on the output widget) or follow a device's clock (sync_clock on the MIDI keyboard). Patterns and MIDI clips move in and out of .mid files (pip install "nbplay[midi]"): sequencer.to_midi("lead.mid"), sequencer.load_midi(path), session.export_midi("song.mid"), and session.import_midi(path).

Sequencers, launcher slots, and MIDI clips play through the track's own instrument, a sampler or a synth, with the built-in oscillator only as a fallback. Every change to a session widget is undoable: session.undo() and session.redo(), or Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z with the transport focused. Adding and removing tracks is the exception.

The example notebooks in examples/ walk through each widget and end with a full DAW playground and the beats view.

The same session runs outside Jupyter as a web app with the instruments in resizable panels: python -m nbplay.app, then open http://127.0.0.1:8020. nbplay.app.build(session) serves your own session with one WebSocket per instrument.

Metadata

Release files for nbplay 0.4.0

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

Source distribution (sdist)

Source distribution for nbplay 0.4.0
File Size Uploaded Provenance Actions
nbplay-0.4.0.tar.gz 1.1 MB Without provenance Details for nbplay-0.4.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for nbplay 0.4.0
File Actions
nbplay-0.4.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl CPython 3.14 CPython 3.14 PyEmscripten 2026.0+ WebAssembly Details for nbplay-0.4.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl
nbplay-0.4.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for nbplay-0.4.0-cp311-abi3-win_amd64.whl
nbplay-0.4.0-cp311-abi3-manylinux_2_28_x86_64.whl CPython 3.11 abi3 Linux glibc 2.28+ x86-64 Details for nbplay-0.4.0-cp311-abi3-manylinux_2_28_x86_64.whl
nbplay-0.4.0-cp311-abi3-manylinux_2_28_aarch64.whl CPython 3.11 abi3 Linux glibc 2.28+ ARM64 Details for nbplay-0.4.0-cp311-abi3-manylinux_2_28_aarch64.whl
nbplay-0.4.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for nbplay-0.4.0-cp311-abi3-macosx_11_0_arm64.whl

Total release size: 8.1 MB

Release files / nbplay-0.4.0.tar.gz

Download URL nbplay-0.4.0.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
82a17010423bfc52021d4048b66342aff9eef2db020c139bbdc311ebb19add7b
BLAKE2b-256 checksum
How to use checksums
4bdb4676f9ee017477e704a634b5258d4aacabdc7c69de9684f8f90156f309e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / nbplay-0.4.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl

Download URL nbplay-0.4.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl
Size 934.8 kB
Tags CPython 3.14 PyEmscripten 2026.0+ WebAssembly
SHA-256 checksum
How to use checksums
fc783287d7c1a660404af93c9470961db3f0765be2c1665132262160f6a1370f
BLAKE2b-256 checksum
How to use checksums
50f866978dbb769ee105995e2d733725783c66f055f55c0d85be04ba858a3e1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / nbplay-0.4.0-cp311-abi3-win_amd64.whl

Download URL nbplay-0.4.0-cp311-abi3-win_amd64.whl
Size 1.7 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
72ebd7a0d61fc5befa1447049221a09d223a94c6bc290cf4904b1ed555e47de2
BLAKE2b-256 checksum
How to use checksums
cd142d16eee39bc1aefd7e5c588822b49149c44a979db13dc34a631082fc2218
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / nbplay-0.4.0-cp311-abi3-manylinux_2_28_x86_64.whl

Download URL nbplay-0.4.0-cp311-abi3-manylinux_2_28_x86_64.whl
Size 1.6 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
f0387ac7ba3f813db2419fb9e375031af17ba746319efeb4418fc8a46ab4c031
BLAKE2b-256 checksum
How to use checksums
90959b36ece8fc591da1bbe5c261f31ce990408b86d3ef5f284f56a65cd25b03
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / nbplay-0.4.0-cp311-abi3-manylinux_2_28_aarch64.whl

Download URL nbplay-0.4.0-cp311-abi3-manylinux_2_28_aarch64.whl
Size 1.6 MB
Tags CPython 3.11 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
bb710474ca6cfede8dd673e8d2e6b08679238cd940b6cba537ac2630ffa5c83c
BLAKE2b-256 checksum
How to use checksums
a2e721ccac5e1de97e53fd7d3731b1d7e807728eefd249c61088622aabc9f112
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / nbplay-0.4.0-cp311-abi3-macosx_11_0_arm64.whl

Download URL nbplay-0.4.0-cp311-abi3-macosx_11_0_arm64.whl
Size 1.1 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
cd7821330c22c015c634566cf1b1e7b04e756b0b5ecc92928c7e48ecd5eb7bee
BLAKE2b-256 checksum
How to use checksums
1a907c945eef82c57d4ad46b1020740cd571323b1042c70433f6b5e9fc696926
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Security for nbplay 0.4.0

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