composer-nb 0.1.0__tar.gz

composer_nb-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+# Built by `npm run build -w dsl`; shipped in the wheel, not committed.
+python/composer_nb/static/
+/dist/
+__pycache__/
+.pytest_cache/
+*.egg-info/

composer_nb-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: composer-nb
+Version: 0.1.0
+Summary: A small language for sketching chord progressions, played inside Jupyter notebooks.
+Project-URL: Homepage, https://github.com/pkhambat1/composer-nb
+Project-URL: Issues, https://github.com/pkhambat1/composer-nb/issues
+Author: Pezanne Khambatta
+Keywords: chords,dsl,jupyter,music,notebook
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Artistic Software
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.9
+Requires-Dist: anywidget>=0.9
+Requires-Dist: ipython>=7.23
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# composer-nb
+
+A small language for chords and drums, played right inside Jupyter notebooks.
+
+```
+%%music
+time: 7/8
+crash: 1|.|.
+ride.bell: x..
+kick: x..x...
+snare: ....x..
+```
+
+Each `%%music` cell renders to audio in the notebook, with a play button, a waveform, a drum grid, the chords it heard and any mistakes it found.
+
+## Install
+
+```bash
+pip install composer-nb
+```
+
+Then, in a notebook:
+
+```python
+%load_ext composer_nb
+```
+
+It works in JupyterLab, Jupyter Notebook 7, VS Code and Google Colab. Sounds are rendered in your browser, and the piano, guitar and drum samples load from the web, so you need an internet connection.
+
+## Cells that continue from each other
+
+Give a cell a name, and later cells can start from the settings and words it ended with:
+
+```
+%%music intro
+tempo: 75
+capo: 2
+sound: guitar
+Am E7|G D
+```
+
+```
+%%music verse after intro
+F C|Dm E7
+```
+
+`verse` plays on guitar with a capo at fret 2, at 75 bpm, wherever it sits in the notebook and whenever you run it. If `intro` hasn't been run yet, you get an error saying so. A cell can still change anything it inherits: `tempo: 90` in `verse` speeds up just `verse`.
+
+A cell with no name plays on its own and isn't saved.
+
+## From Python
+
+`%%music` is a shortcut for `Song`, which you can use directly:
+
+```python
+from composer_nb import Song
+
+intro = Song("tempo: 75\nsound: guitar\nAm E7|G D", name="intro")
+verse = Song("F C|Dm E7", after=intro, name="verse")
+verse  # shows the player
+```
+
+Songs are ordinary Python values, so you can generate them with loops and functions:
+
+```python
+blues = "|".join(["A7", "D7", "A7", "A7", "D7", "D7", "A7", "A7", "E7", "D7", "A7", "E7"])
+Song("tempo: 120\n" + blues)
+```
+
+## The language
+
+Every line is a setting, an instrument and what it plays, a line of chords, a word you can reuse, or a `--` comment. Lines next to each other play together; a blank line starts the next block, which plays after it.
+
+### Settings
+
+| Setting  | Default   | Meaning                                                                       |
+| -------- | --------- | ----------------------------------------------------------------------------- |
+| `time`   | `4/4`     | `4/4`, `7/8`, or added-up like `(3+4)/4`                                      |
+| `tempo`  | `120`     | Quarter notes per minute                                                      |
+| `sound`  | `piano`   | What chord lines play on: `piano`, `epiano`, `organ`, `pad`, `bass`, `guitar` |
+| `capo`   | `0`       | Capo fret, 0 to 12. Only for guitar                                           |
+| `key`    | `C`       | Key for Roman numeral chords                                                  |
+| `step`   | `1/16`    | Length of each step in a drum loop                                            |
+| `bars`   | automatic | How many bars this block plays                                                |
+| `octave` | `3`       | Octave chords are voiced in                                                   |
+| `kit`    | `rock`    | Drum sound: `rock` or `synth`                                                 |
+
+Settings carry on into the blocks and cells below.
+
+### Chords
+
+```
+sound: guitar
+Am F|C G
+C . . G|Am . F G|%|F . _ .
+```
+
+`|` is a bar line and the chords in a bar split it evenly. `.` holds the chord before for another slot, `_` is silence and `%` repeats the bar before. Chord lines next to each other carry on from one another. Chords can be names (`Cmaj7`, `F#m`, `Bb7`, `C/E`) or Roman numerals that follow `key` (`I vi IV V7`). To layer a second instrument, start its line with its name: `bass: C A|F G`.
+
+### Drums
+
+`kick`, `snare`, `hat`, `ride`, `crash`, `tom` and `floor` each get their own line, played either on beats or as a loop. Some have a second sound with a line of its own: `ride.bell`, `hat.open` and `hat.pedal`.
+
+```
+kick: 1 3
+snare: 2 4 accent
+crash: 1|.|.
+hat: X.x.X.x.
+ride.bell: x..
+```
+
+Beats are counted `1 e & a 2 e & a`, and `|` separates bars (`.` is an empty bar). A loop is a row of steps that repeats on its own: `x` hit, `X` accent, `g` ghost, `d` double, `.` rest. Every line in a block repeats until they all line up again.
+
+### Repeats
+
+```
+repeat 2:
+  repeat 3:
+    kick: x..x...
+  crash: 1
+  snare: 2 4
+```
+
+`repeat 2:` plays the lines indented under it twice. It ends at the first line that isn't indented under it, and repeats nest.
+
+### Words
+
+```
+pair = X.x.
+verse = Am E7|G D
+hat: pair pair
+verse verse
+```
+
+## Playground
+
+The same language runs in the composer-nb playground, a notebook-style web app. Its source is in the [`playground/`](https://github.com/pkhambat1/composer-nb/tree/main/playground) folder of the repository.
+
+## Developing
+
+This package lives in the `dsl/` folder of [the repository](https://github.com/pkhambat1/composer-nb). The parser and audio engine are JavaScript (`dsl/js/`), and the Python side (`dsl/python/composer_nb/`) passes cell sources to them through an [anywidget](https://anywidget.dev). Build the widget before installing:
+
+```bash
+npm install
+npm run build -w dsl
+pip install -e "dsl[test]"
+pytest dsl/tests/python
+```

composer_nb-0.1.0/README.md

@@ -0,0 +1,148 @@
+# composer-nb
+
+A small language for chords and drums, played right inside Jupyter notebooks.
+
+```
+%%music
+time: 7/8
+crash: 1|.|.
+ride.bell: x..
+kick: x..x...
+snare: ....x..
+```
+
+Each `%%music` cell renders to audio in the notebook, with a play button, a waveform, a drum grid, the chords it heard and any mistakes it found.
+
+## Install
+
+```bash
+pip install composer-nb
+```
+
+Then, in a notebook:
+
+```python
+%load_ext composer_nb
+```
+
+It works in JupyterLab, Jupyter Notebook 7, VS Code and Google Colab. Sounds are rendered in your browser, and the piano, guitar and drum samples load from the web, so you need an internet connection.
+
+## Cells that continue from each other
+
+Give a cell a name, and later cells can start from the settings and words it ended with:
+
+```
+%%music intro
+tempo: 75
+capo: 2
+sound: guitar
+Am E7|G D
+```
+
+```
+%%music verse after intro
+F C|Dm E7
+```
+
+`verse` plays on guitar with a capo at fret 2, at 75 bpm, wherever it sits in the notebook and whenever you run it. If `intro` hasn't been run yet, you get an error saying so. A cell can still change anything it inherits: `tempo: 90` in `verse` speeds up just `verse`.
+
+A cell with no name plays on its own and isn't saved.
+
+## From Python
+
+`%%music` is a shortcut for `Song`, which you can use directly:
+
+```python
+from composer_nb import Song
+
+intro = Song("tempo: 75\nsound: guitar\nAm E7|G D", name="intro")
+verse = Song("F C|Dm E7", after=intro, name="verse")
+verse  # shows the player
+```
+
+Songs are ordinary Python values, so you can generate them with loops and functions:
+
+```python
+blues = "|".join(["A7", "D7", "A7", "A7", "D7", "D7", "A7", "A7", "E7", "D7", "A7", "E7"])
+Song("tempo: 120\n" + blues)
+```
+
+## The language
+
+Every line is a setting, an instrument and what it plays, a line of chords, a word you can reuse, or a `--` comment. Lines next to each other play together; a blank line starts the next block, which plays after it.
+
+### Settings
+
+| Setting  | Default   | Meaning                                                                       |
+| -------- | --------- | ----------------------------------------------------------------------------- |
+| `time`   | `4/4`     | `4/4`, `7/8`, or added-up like `(3+4)/4`                                      |
+| `tempo`  | `120`     | Quarter notes per minute                                                      |
+| `sound`  | `piano`   | What chord lines play on: `piano`, `epiano`, `organ`, `pad`, `bass`, `guitar` |
+| `capo`   | `0`       | Capo fret, 0 to 12. Only for guitar                                           |
+| `key`    | `C`       | Key for Roman numeral chords                                                  |
+| `step`   | `1/16`    | Length of each step in a drum loop                                            |
+| `bars`   | automatic | How many bars this block plays                                                |
+| `octave` | `3`       | Octave chords are voiced in                                                   |
+| `kit`    | `rock`    | Drum sound: `rock` or `synth`                                                 |
+
+Settings carry on into the blocks and cells below.
+
+### Chords
+
+```
+sound: guitar
+Am F|C G
+C . . G|Am . F G|%|F . _ .
+```
+
+`|` is a bar line and the chords in a bar split it evenly. `.` holds the chord before for another slot, `_` is silence and `%` repeats the bar before. Chord lines next to each other carry on from one another. Chords can be names (`Cmaj7`, `F#m`, `Bb7`, `C/E`) or Roman numerals that follow `key` (`I vi IV V7`). To layer a second instrument, start its line with its name: `bass: C A|F G`.
+
+### Drums
+
+`kick`, `snare`, `hat`, `ride`, `crash`, `tom` and `floor` each get their own line, played either on beats or as a loop. Some have a second sound with a line of its own: `ride.bell`, `hat.open` and `hat.pedal`.
+
+```
+kick: 1 3
+snare: 2 4 accent
+crash: 1|.|.
+hat: X.x.X.x.
+ride.bell: x..
+```
+
+Beats are counted `1 e & a 2 e & a`, and `|` separates bars (`.` is an empty bar). A loop is a row of steps that repeats on its own: `x` hit, `X` accent, `g` ghost, `d` double, `.` rest. Every line in a block repeats until they all line up again.
+
+### Repeats
+
+```
+repeat 2:
+  repeat 3:
+    kick: x..x...
+  crash: 1
+  snare: 2 4
+```
+
+`repeat 2:` plays the lines indented under it twice. It ends at the first line that isn't indented under it, and repeats nest.
+
+### Words
+
+```
+pair = X.x.
+verse = Am E7|G D
+hat: pair pair
+verse verse
+```
+
+## Playground
+
+The same language runs in the composer-nb playground, a notebook-style web app. Its source is in the [`playground/`](https://github.com/pkhambat1/composer-nb/tree/main/playground) folder of the repository.
+
+## Developing
+
+This package lives in the `dsl/` folder of [the repository](https://github.com/pkhambat1/composer-nb). The parser and audio engine are JavaScript (`dsl/js/`), and the Python side (`dsl/python/composer_nb/`) passes cell sources to them through an [anywidget](https://anywidget.dev). Build the widget before installing:
+
+```bash
+npm install
+npm run build -w dsl
+pip install -e "dsl[test]"
+pytest dsl/tests/python
+```

composer_nb-0.1.0/hatch_build.py

@@ -0,0 +1,21 @@
+"""Stop a build that would ship without the widget's JavaScript.
+
+The widget is compiled by `npm run build -w dsl` into python/composer_nb/static/,
+which git ignores. Without this check, forgetting that step produces a wheel
+that installs fine but shows nothing in the notebook.
+"""
+
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        static = Path(self.root) / "python" / "composer_nb" / "static"
+        missing = [name for name in ("widget.js", "widget.css") if not (static / name).is_file()]
+        if missing:
+            raise RuntimeError(
+                f"{', '.join(missing)} missing from {static}. "
+                "Build the widget first: npm run build -w dsl"
+            )

composer_nb-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "composer-nb"
+version = "0.1.0"
+description = "A small language for sketching chord progressions, played inside Jupyter notebooks."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Pezanne Khambatta" }]
+keywords = ["music", "chords", "jupyter", "notebook", "dsl"]
+classifiers = [
+  "Framework :: Jupyter",
+  "Intended Audience :: Education",
+  "Programming Language :: Python :: 3",
+  "Topic :: Artistic Software",
+  "Topic :: Multimedia :: Sound/Audio",
+]
+dependencies = [
+  "anywidget>=0.9",
+  "ipython>=7.23",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/pkhambat1/composer-nb"
+Issues = "https://github.com/pkhambat1/composer-nb/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["python/composer_nb"]
+artifacts = ["python/composer_nb/static/*"]
+
+[tool.hatch.build.targets.sdist]
+include = ["python", "README.md", "hatch_build.py"]
+artifacts = ["python/composer_nb/static/*"]
+
+# Refuses to build without the compiled widget; see hatch_build.py.
+[tool.hatch.build.hooks.custom]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/python"]

composer_nb-0.1.0/python/composer_nb/__init__.py

@@ -0,0 +1,38 @@
+"""composer-nb: a small language for chords and drums, played inside notebooks.
+
+In Jupyter, load the cell magic and write music in `%%music` cells:
+
+    %load_ext composer_nb
+
+    %%music intro
+    tempo 75
+    sound guitar
+    play {
+      chords: Am E7|G D
+      kick: loop x-------
+      snare: loop ----x---
+    }
+
+Or build songs from Python with `Song`.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .song import Song
+from .widget import MusicWidget
+
+try:
+    __version__ = version("composer-nb")
+except PackageNotFoundError:  # running from a source checkout that isn't installed
+    __version__ = "0.0.0"
+
+__all__ = ["MusicWidget", "Song", "__version__"]
+
+
+def load_ipython_extension(ipython):
+    """Called by `%load_ext composer_nb`; registers the `%%music` cell magic and its Tab completion."""
+    from .completer import register
+    from .magic import MusicMagics
+
+    ipython.register_magics(MusicMagics)
+    register(ipython)

composer_nb-0.1.0/python/composer_nb/completer.py

@@ -0,0 +1,148 @@
+"""Tab completion inside `%%music` cells.
+
+Jupyter asks the kernel what could come next, and IPython only knows Python, so the
+extension adds a matcher of its own. The word lists mirror dsl/js/language.js;
+tests/python/test_completer.py fails if the two drift apart.
+"""
+
+import re
+from typing import Dict, List, Optional, Tuple
+
+from .song import Song
+
+DRUMS = ["crash", "ride", "hat", "tom", "floor", "snare", "kick"]
+VARIATIONS = {"ride": ["bell"], "hat": ["open", "pedal"]}
+INSTRUMENTS = ["piano", "epiano", "organ", "pad", "bass", "guitar"]
+SETTINGS = ["time", "tempo", "step", "sound", "key", "capo", "octave", "kit"]
+MODIFIERS = ["accent", "ghost", "double"]
+KITS = ["rock", "synth"]
+
+LANES = [lane for d in DRUMS for lane in [d, *(f"{d}.{v}" for v in VARIATIONS.get(d, []))]]
+PARTS = ["chords", *LANES]
+SETTING_VALUES = {"sound": INSTRUMENTS, "kit": KITS}
+
+MAGIC = "%%music"
+WORD_RE = re.compile(r"^\s*([A-Za-z_]\w*)\s*=", re.M)
+PATTERN_RE = re.compile(r"\bpattern\s+([A-Za-z_]\w*)")
+# The instrument line the cursor is on: its name, then what's been written after the colon.
+PART_RE = re.compile(r"(?:^|[\s{])([a-z]+(?:\.[a-z]+)?):([^:{}]*)$")
+NUMBER_RE = re.compile(r"^\d+$|\)$")
+
+Option = Tuple[str, str]  # the text to insert and its kind, which picks the icon
+
+
+def _options(texts, kind) -> List[Option]:
+    return [(t, kind) for t in texts]
+
+
+def _magic_line(line: str, songs: Dict[str, Song]) -> Optional[Tuple[str, List[Option]]]:
+    """Completions for the `%%music [name] [after <name>]` line itself."""
+    if not line.startswith(MAGIC + " "):
+        return None  # still typing the magic's name, which IPython completes
+    fragment = re.search(r"\w*$", line).group()
+    words = line[len(MAGIC) : len(line) - len(fragment)].split()
+    if words and words[-1] == "after":
+        return fragment, _options(sorted(songs), "variable")
+    if len(words) == 1:
+        return fragment, [("after ", "keyword")]
+    return fragment, []
+
+
+def _statement(head: str, body: str, patterns: List[str]) -> List[Option]:
+    """What can come next on a line that isn't an instrument's."""
+    inside = (body + head).count("{") > (body + head).count("}")
+    words = re.split(r"[{}]", head)[-1].split()
+    names = _options(patterns, "variable")
+    parts = _options([p + ": " for p in PARTS], "property")
+    if not words:
+        settings = _options([s + " " for s in SETTINGS], "keyword")
+        if inside:
+            return parts + names + settings
+        return settings + [("pattern ", "keyword"), ("play ", "keyword")]
+    first, last = words[0], words[-1]
+    if first in ("play", "pattern") and len(words) > 1 and NUMBER_RE.search(last):
+        return _options(["bars ", "bar "], "keyword")
+    if first == "play":
+        return names + (parts if len(words) == 1 else [])
+    if first == "time" and len(words) > 1 and "over" not in words:
+        return [("over ", "keyword")]
+    if first in SETTING_VALUES and len(words) == 1:
+        return _options(SETTING_VALUES[first], "value")
+    if inside and first not in SETTINGS and first != "pattern":
+        return names  # a line that plays patterns in order: intro verse * 2
+    return []
+
+
+def complete(text: str, cursor: int, songs: Optional[Dict[str, Song]] = None):
+    """Completions at `cursor` in a `%%music` cell (`text` includes the magic line).
+
+    Returns (fragment, options): the part of a word already typed, and what could
+    replace it. None means the cursor isn't somewhere this language applies.
+    """
+    songs = songs or {}
+    before = text[:cursor]
+    start = before.rfind("\n") + 1
+    line = before[start:]
+    if start == 0:
+        return _magic_line(line, songs)
+    if "//" in line:
+        return "", []
+    fragment = re.search(r"[A-Za-z_]\w*$|$", line).group()
+    head = line[: len(line) - len(fragment)]
+    magic_line, _, body = before[:start].partition("\n")
+
+    # Names defined above the cursor, in this cell or the cells it continues from.
+    after = re.search(r"\bafter\s+(\w+)", magic_line)
+    inherited = songs[after.group(1)].chain if after and after.group(1) in songs else []
+    defined = "\n".join([*inherited, body])
+    words = sorted(set(WORD_RE.findall(defined)))
+    patterns = sorted(set(PATTERN_RE.findall(defined)))
+
+    variation = re.search(r"([a-z]+)\.$", head)
+    part = PART_RE.search(head)
+    if variation:  # ride. -> ride.bell
+        options = _options([v + ": " for v in VARIATIONS.get(variation.group(1), [])], "property")
+    elif part and part.group(1) in PARTS:
+        written = part.group(2).split()
+        options = _options(words, "variable")
+        if not written:
+            options = [("loop ", "keyword")] + options
+        elif part.group(1) != "chords" and any(w[0].isdigit() for w in written):
+            options = _options(MODIFIERS, "keyword")  # beats take accent, ghost, double
+    else:
+        options = _statement(head, body, patterns)
+    return fragment, [o for o in options if o[0].startswith(fragment) and o[0] != fragment]
+
+
+def register(shell) -> None:
+    """Add the `%%music` matcher to `shell`'s completer, once."""
+    try:
+        from IPython.core.completer import SimpleCompletion, context_matcher
+    except ImportError:  # IPython before 8.6 has no matcher API
+        return
+    identifier = "composer_nb.music_matcher"
+    matchers = shell.Completer.custom_matchers
+    if any(getattr(m, "matcher_identifier", None) == identifier for m in matchers):
+        return
+
+    @context_matcher(identifier=identifier)
+    def music_matcher(context):
+        text = context.full_text
+        result = None
+        if text.startswith(MAGIC):
+            lines = text.split("\n")
+            cursor = sum(len(l) + 1 for l in lines[: context.cursor_line]) + context.cursor_position
+            songs = {k: v for k, v in shell.user_ns.items() if isinstance(v, Song)}
+            result = complete(text, cursor, songs)
+        if result is None:
+            return {"completions": [], "suppress": False}
+        fragment, options = result
+        return {
+            "completions": [SimpleCompletion(text=t, type=kind) for t, kind in options],
+            "matched_fragment": fragment,
+            # Python names mean nothing in a music cell, so IPython's own matchers stay out.
+            # (IPython only honours this when there's something to offer.)
+            "suppress": True,
+        }
+
+    matchers.append(music_matcher)

composer_nb-0.1.0/python/composer_nb/magic.py

@@ -0,0 +1,53 @@
+import keyword
+from typing import Optional, Tuple
+
+from IPython.core.error import UsageError
+from IPython.core.magic import Magics, cell_magic, magics_class
+
+from .song import Song
+
+USAGE = "Usage: %%music [name] [after <name>]"
+
+
+def parse_magic_line(line: str) -> Tuple[Optional[str], Optional[str]]:
+    """Split the `%%music` line into (name, after)."""
+    words = line.split()
+    name = after = None
+    if words and words[0] != "after":
+        name = words.pop(0)
+    if words:
+        if words[0] != "after" or len(words) != 2:
+            raise UsageError(USAGE)
+        after = words[1]
+    for word in (name, after):
+        if word is not None and (not word.isidentifier() or keyword.iskeyword(word)):
+            raise UsageError(
+                f"{word!r} can't be a cell name. Use letters, digits and underscores, like intro or verse_2."
+            )
+    if name is not None and name == after:
+        raise UsageError(f"{name} can't continue from itself.")
+    return name, after
+
+
+@magics_class
+class MusicMagics(Magics):
+    @cell_magic
+    def music(self, line, cell):
+        """Play a cell of composer-nb source.
+
+        %%music                    play this cell on its own
+        %%music intro              ...and save it as `intro`
+        %%music verse after intro  start from the settings and definitions `intro` ended with
+        """
+        name, after_name = parse_magic_line(line)
+        after = None
+        if after_name is not None:
+            if after_name not in self.shell.user_ns:
+                raise UsageError(f"{after_name} hasn't been run yet. Run its cell first.")
+            after = self.shell.user_ns[after_name]
+            if not isinstance(after, Song):
+                raise UsageError(f"{after_name} is a {type(after).__name__}, not a %%music cell.")
+        song = Song(cell, after=after, name=name)
+        if name is not None:
+            self.shell.user_ns[name] = song
+        return song