Metadata-Version: 2.5
Name: nbplay
Version: 0.4.0
Summary: let's play!
Project-URL: Repository, https://github.com/1kbgz/nbplay
Project-URL: Homepage, https://github.com/1kbgz/nbplay
Author-email: the nbplay authors <dev@1kbgz.com>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Rust
Requires-Python: >=3.11
Requires-Dist: anywidget
Requires-Dist: ipywidgets>=8
Requires-Dist: spaday-regular-layout
Requires-Dist: spaday[widget]>=0.14.1
Requires-Dist: starlette
Requires-Dist: transports>=0.12.2
Requires-Dist: uvicorn
Requires-Dist: websockets
Provides-Extra: develop
Requires-Dist: build; extra == 'develop'
Requires-Dist: bump-my-version; extra == 'develop'
Requires-Dist: check-dist; extra == 'develop'
Requires-Dist: cibuildwheel; extra == 'develop'
Requires-Dist: codespell; extra == 'develop'
Requires-Dist: hatch-js; extra == 'develop'
Requires-Dist: hatch-rs; extra == 'develop'
Requires-Dist: hatchling; extra == 'develop'
Requires-Dist: httpx; extra == 'develop'
Requires-Dist: jupyterlab; extra == 'develop'
Requires-Dist: jupyterlite-core[contents]; extra == 'develop'
Requires-Dist: jupyterlite-pyodide-kernel; extra == 'develop'
Requires-Dist: mdformat; extra == 'develop'
Requires-Dist: mdformat-myst; extra == 'develop'
Requires-Dist: mdformat-tables>=1; extra == 'develop'
Requires-Dist: mido; extra == 'develop'
Requires-Dist: pytest; extra == 'develop'
Requires-Dist: pytest-cov; extra == 'develop'
Requires-Dist: ruff; extra == 'develop'
Requires-Dist: twine; extra == 'develop'
Requires-Dist: ty; extra == 'develop'
Requires-Dist: uv; extra == 'develop'
Requires-Dist: voila; extra == 'develop'
Requires-Dist: wheel; extra == 'develop'
Provides-Extra: midi
Requires-Dist: mido; extra == 'midi'
Description-Content-Type: text/markdown

# nbplay

let's play!

[![Build Status](https://github.com/1kbgz/nbplay/actions/workflows/build.yaml/badge.svg?branch=main&event=push)](https://github.com/1kbgz/nbplay/actions/workflows/build.yaml)
[![codecov](https://codecov.io/gh/1kbgz/nbplay/branch/main/graph/badge.svg)](https://codecov.io/gh/1kbgz/nbplay)
[![License](https://img.shields.io/github/license/1kbgz/nbplay)](https://github.com/1kbgz/nbplay)
[![PyPI](https://img.shields.io/pypi/v/nbplay.svg)](https://pypi.python.org/pypi/nbplay)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/1kbgz/nbplay/main?urlpath=lab)

## Overview

> [!WARNING]
> This library is in early development and the API is subject to change without deprecation. Feedback and contributions are very welcome!

[![Music composition widgets in a jupyter notebook](https://raw.githubusercontent.com/1kbgz/nbplay/refs/heads/main/docs/img/sample.gif)](https://raw.githubusercontent.com/1kbgz/nbplay/refs/heads/main/docs/img/sample.gif)

**Try it in your browser:** the [live demo](https://1kbgz.github.io/nbplay/lite/lab/index.html?path=13_daw_playground.ipynb)
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](https://1kbgz.github.io/nbplay/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](https://github.com/1kbgz/spaday) widgets on
[transports](https://github.com/1kbgz/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:

```python
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.

```python
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.

> [!NOTE]
> This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).
