shipwright-audio 0.1.0__tar.gz

shipwright_audio-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python-version: "3.10"
+          - os: ubuntu-latest
+            python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: macos-latest
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.12"
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv run --python ${{ matrix.python-version }} --extra dev pytest
+
+  package:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv build
+      - run: uvx twine check dist/*

shipwright_audio-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/shipwright-audio
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv build
+      - run: uvx twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1

shipwright_audio-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Project output
+output/
+soundfonts/*.sf2
+
+# Python bytecode / caches
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Packaging / build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+uv.lock
+
+# Editors / IDEs
+.vscode/
+.idea/
+*.swp
+
+# macOS
+.DS_Store

shipwright_audio-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-06-28
+
+- Initial public package for code-first audio rendering.
+- Added the `shipwright` console command.
+- Added Buffer-based SFX rendering and RenderSpec-based DawDreamer music rendering.

shipwright_audio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Braun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shipwright_audio-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: shipwright-audio
+Version: 0.1.0
+Summary: A code-first audio studio: write -> render -> listen -> adjust.
+Project-URL: Homepage, https://github.com/dinger086/shipwright-audio
+Project-URL: Repository, https://github.com/dinger086/shipwright-audio
+Project-URL: Issues, https://github.com/dinger086/shipwright-audio/issues
+Project-URL: Changelog, https://github.com/dinger086/shipwright-audio/blob/main/CHANGELOG.md
+Author: Robert Braun
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,dawdreamer,faust,music,sfx,synthesis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: <3.13,>=3.10
+Requires-Dist: dawdreamer
+Requires-Dist: numpy
+Requires-Dist: scipy<1.15,>=1.11
+Requires-Dist: soundfile
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: midi
+Requires-Dist: pretty-midi; extra == 'midi'
+Provides-Extra: soundfont
+Requires-Dist: pyfluidsynth; extra == 'soundfont'
+Provides-Extra: theory
+Requires-Dist: music21; extra == 'theory'
+Description-Content-Type: text/markdown
+
+# shipwright-audio
+
+A code-first audio studio: describe a sound or a few bars of music in a
+small Python function, run one command, get a `.wav`.
+
+Requires Python 3.10 through 3.12.
+
+## The shape
+
+Four layers, cleanly separated:
+
+| Layer | File | Job |
+| --- | --- | --- |
+| **Composition** (above) | `shipwright/compose.py` | chord symbols / pitch lists → `Note`s |
+| **Sound sources** (below) | `shipwright/instruments.py` | Faust synths the engine plays |
+| **SFX synthesis** | `shipwright/dsp.py` | numpy oscillators / noise / envelopes / filters |
+| **The spine** | `shipwright/engine.py` | DawDreamer: graph → mix → bus FX → offline render |
+
+You author in a `sounds/` directory in your project (create it yourself —
+the tool reads `./sounds` from wherever you run it). Each file is one sound.
+A build-function returns either a **`Buffer`** (raw numpy samples → SFX) or a
+**`RenderSpec`** (tracks of MIDI played by instruments → music). The harness
+routes by type. Copy-paste starting points live in [`examples/`](examples/).
+
+## Install
+
+As a tool (gets you the `shipwright` command anywhere):
+
+```bash
+uv tool install shipwright-audio      # or: pipx install shipwright-audio
+```
+
+Or from a checkout for development:
+
+```bash
+uv sync                               # create .venv + install deps
+```
+
+## Use
+
+`shipwright` loads sounds from `./sounds` and writes to `./output` relative
+to the directory you run it in (override with `SHIPWRIGHT_SOUNDS` /
+`SHIPWRIGHT_OUTPUT`).
+
+```bash
+shipwright                       # list sounds
+shipwright sea_bed               # render one  -> output/sea_bed.wav
+shipwright all --ogg             # render all, also write .ogg
+shipwright --watch sea_bed       # re-render on every save (tight loop)
+```
+
+From a checkout without installing, `uv run shipwright ...` or
+`python render.py ...` both work.
+
+## Develop
+
+```bash
+uv run --extra dev pytest
+env SHIPWRIGHT_SOUNDS=examples uv run shipwright ui_blip
+env SHIPWRIGHT_SOUNDS=examples uv run shipwright sea_bed
+```
+
+## Add a sound
+
+Create `sounds/my_thing.py`:
+
+```python
+from shipwright import sound, Buffer, dsp
+
+@sound("zap")
+def zap():
+    s = dsp.ad_env(dsp.saw(220, 0.25), attack=0.001, release=0.2)
+    s = dsp.lowpass(s, 1200)
+    return Buffer(dsp.to_stereo(dsp.normalize(s, 0.9)))
+```
+
+…then `shipwright zap`. Music works the same way but returns a
+`RenderSpec` of `Track`s — see [`examples/music_sea_bed.py`](examples/music_sea_bed.py).
+
+## Why DawDreamer is the spine but not the whole thing
+
+DawDreamer mixes, automates (sample-accurate, via numpy arrays), hosts
+plugins, and renders deterministically offline. It does **not** compose and
+ships **no instruments** — so composition lives above it (`compose.py`) and
+sound sources below it (`instruments.py`, here as Faust). That's the whole
+architecture.
+
+## Nicer instruments (upgrade path)
+
+The built-in Faust synths need zero files. When you want more "produced"
+sound, swap a `Track`'s instrument for either:
+
+- **SoundFont**: drop an `.sf2` in `soundfonts/`, render its MIDI with
+  `pyfluidsynth`, feed the audio into the DawDreamer graph as a track.
+- **VST/AU**: `engine.make_plugin_processor("name", "/path/to/plugin.vst3")`,
+  then `add_midi_note(...)` exactly like the Faust instruments.
+
+## License
+
+`shipwright-audio` is MIT licensed. Its DawDreamer dependency is GPLv3; review
+that license before redistributing bundled applications or generated tooling.

shipwright_audio-0.1.0/README.md

@@ -0,0 +1,101 @@
+# shipwright-audio
+
+A code-first audio studio: describe a sound or a few bars of music in a
+small Python function, run one command, get a `.wav`.
+
+Requires Python 3.10 through 3.12.
+
+## The shape
+
+Four layers, cleanly separated:
+
+| Layer | File | Job |
+| --- | --- | --- |
+| **Composition** (above) | `shipwright/compose.py` | chord symbols / pitch lists → `Note`s |
+| **Sound sources** (below) | `shipwright/instruments.py` | Faust synths the engine plays |
+| **SFX synthesis** | `shipwright/dsp.py` | numpy oscillators / noise / envelopes / filters |
+| **The spine** | `shipwright/engine.py` | DawDreamer: graph → mix → bus FX → offline render |
+
+You author in a `sounds/` directory in your project (create it yourself —
+the tool reads `./sounds` from wherever you run it). Each file is one sound.
+A build-function returns either a **`Buffer`** (raw numpy samples → SFX) or a
+**`RenderSpec`** (tracks of MIDI played by instruments → music). The harness
+routes by type. Copy-paste starting points live in [`examples/`](examples/).
+
+## Install
+
+As a tool (gets you the `shipwright` command anywhere):
+
+```bash
+uv tool install shipwright-audio      # or: pipx install shipwright-audio
+```
+
+Or from a checkout for development:
+
+```bash
+uv sync                               # create .venv + install deps
+```
+
+## Use
+
+`shipwright` loads sounds from `./sounds` and writes to `./output` relative
+to the directory you run it in (override with `SHIPWRIGHT_SOUNDS` /
+`SHIPWRIGHT_OUTPUT`).
+
+```bash
+shipwright                       # list sounds
+shipwright sea_bed               # render one  -> output/sea_bed.wav
+shipwright all --ogg             # render all, also write .ogg
+shipwright --watch sea_bed       # re-render on every save (tight loop)
+```
+
+From a checkout without installing, `uv run shipwright ...` or
+`python render.py ...` both work.
+
+## Develop
+
+```bash
+uv run --extra dev pytest
+env SHIPWRIGHT_SOUNDS=examples uv run shipwright ui_blip
+env SHIPWRIGHT_SOUNDS=examples uv run shipwright sea_bed
+```
+
+## Add a sound
+
+Create `sounds/my_thing.py`:
+
+```python
+from shipwright import sound, Buffer, dsp
+
+@sound("zap")
+def zap():
+    s = dsp.ad_env(dsp.saw(220, 0.25), attack=0.001, release=0.2)
+    s = dsp.lowpass(s, 1200)
+    return Buffer(dsp.to_stereo(dsp.normalize(s, 0.9)))
+```
+
+…then `shipwright zap`. Music works the same way but returns a
+`RenderSpec` of `Track`s — see [`examples/music_sea_bed.py`](examples/music_sea_bed.py).
+
+## Why DawDreamer is the spine but not the whole thing
+
+DawDreamer mixes, automates (sample-accurate, via numpy arrays), hosts
+plugins, and renders deterministically offline. It does **not** compose and
+ships **no instruments** — so composition lives above it (`compose.py`) and
+sound sources below it (`instruments.py`, here as Faust). That's the whole
+architecture.
+
+## Nicer instruments (upgrade path)
+
+The built-in Faust synths need zero files. When you want more "produced"
+sound, swap a `Track`'s instrument for either:
+
+- **SoundFont**: drop an `.sf2` in `soundfonts/`, render its MIDI with
+  `pyfluidsynth`, feed the audio into the DawDreamer graph as a track.
+- **VST/AU**: `engine.make_plugin_processor("name", "/path/to/plugin.vst3")`,
+  then `add_midi_note(...)` exactly like the Faust instruments.
+
+## License
+
+`shipwright-audio` is MIT licensed. Its DawDreamer dependency is GPLv3; review
+that license before redistributing bundled applications or generated tooling.

shipwright_audio-0.1.0/examples/music_sea_bed.py

@@ -0,0 +1,25 @@
+"""An 8-bar ambient sea bed: pad + soft lead + sub bass, through reverb.
+Music path: returns a RenderSpec that the DawDreamer engine renders."""
+from shipwright import sound, Track, RenderSpec, instruments, compose
+
+@sound("sea_bed")
+def sea_bed():
+    bpm = 70
+    pad = Track(
+        instruments.soft_pad(cutoff=1100),
+        compose.progression(["Dm", "Bb", "F", "C"], bpm, beats_per_chord=4, repeats=2),
+        gain_db=-6,
+    )
+    lead = Track(
+        instruments.saw_lead(cutoff=1400),
+        compose.melody([74, 77, 76, 74, 72, 74, None, 69, 72, 74],
+                       bpm, note_beats=[2,1,1,2,1,1,2,2,2,4], start_beat=4),
+        gain_db=-11,
+    )
+    bass = Track(
+        instruments.sub_bass(),
+        compose.bassline(["D", "Bb", "F", "C"], bpm, octave=2, beats_per_note=4, repeats=2),
+        gain_db=-7,
+    )
+    return RenderSpec(tracks=[pad, lead, bass], tempo=bpm,
+                      master_fx=[instruments.reverb(wet=0.35)])

shipwright_audio-0.1.0/examples/sfx_ui_blip.py

@@ -0,0 +1,12 @@
+"""A short UI confirm blip. SFX path: synthesise samples -> Buffer."""
+import numpy as np
+from shipwright import sound, Buffer, dsp
+
+@sound("ui_blip")
+def ui_blip():
+    ping1 = dsp.ad_env(dsp.sine(880, 0.09), attack=0.002, release=0.07)
+    ping2 = dsp.ad_env(dsp.sine(1320, 0.11), attack=0.002, release=0.09)
+    gap = np.zeros(int(0.045 * dsp.SR))
+    sig = dsp.layer(ping1, np.concatenate([gap, ping2]))
+    sig = dsp.normalize(sig, 0.85)
+    return Buffer(dsp.to_stereo(sig, pan=0.0))

shipwright_audio-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shipwright-audio"
+version = "0.1.0"
+description = "A code-first audio studio: write -> render -> listen -> adjust."
+readme = "README.md"
+requires-python = ">=3.10,<3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Robert Braun" }]
+keywords = ["audio", "synthesis", "dawdreamer", "faust", "sfx", "music"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio",
+]
+dependencies = [
+    "dawdreamer",
+    "numpy",
+    "scipy>=1.11,<1.15",
+    "soundfile",
+]
+
+[project.optional-dependencies]
+dev       = ["pytest"]
+soundfont = ["pyfluidsynth"]
+midi      = ["pretty_midi"]
+theory    = ["music21"]
+
+[project.urls]
+Homepage = "https://github.com/dinger086/shipwright-audio"
+Repository = "https://github.com/dinger086/shipwright-audio"
+Issues = "https://github.com/dinger086/shipwright-audio/issues"
+Changelog = "https://github.com/dinger086/shipwright-audio/blob/main/CHANGELOG.md"
+
+[project.scripts]
+shipwright = "shipwright.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["shipwright"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.DS_Store",
+    "/.venv",
+    "/dist",
+    "/output",
+    "/uv.lock",
+    "**/__pycache__",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shipwright_audio-0.1.0/render.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+"""In-repo dev shim. The real entry point is `shipwright` (shipwright.cli:main),
+installed via pyproject. This lets you run the CLI from a checkout without
+installing: `python render.py sea_bed`."""
+from shipwright.cli import main
+
+if __name__ == "__main__":
+    main()

shipwright_audio-0.1.0/shipwright/__init__.py

@@ -0,0 +1,4 @@
+__version__ = "0.1.0"
+
+from .registry import sound, Buffer, Note, Instrument, Track, RenderSpec, names, get
+from . import dsp, instruments, compose

shipwright_audio-0.1.0/shipwright/cli.py

@@ -0,0 +1,132 @@
+"""The harness, as a console command. The whole point: edit a file in
+sounds/, run this, listen.
+
+    shipwright                 list all sounds
+    shipwright sea_bed         render one -> output/sea_bed.wav
+    shipwright all             render everything
+    shipwright sea_bed --ogg   also write a Vorbis .ogg
+    shipwright --watch sea_bed re-render on every save (tight loop)
+
+Sounds are loaded from ./sounds and written to ./output relative to the
+current directory (override with SHIPWRIGHT_ROOT / SHIPWRIGHT_SOUNDS /
+SHIPWRIGHT_OUTPUT).
+"""
+import argparse
+import importlib.util
+from pathlib import Path
+import time
+
+from . import __version__, config
+from .registry import Buffer, RenderSpec, clear, get, names
+
+
+def load_sounds():
+    if not config.SOUNDS_DIR.is_dir():
+        raise SystemExit(
+            f"no sounds directory at {config.SOUNDS_DIR}\n"
+            "cd into a project with a sounds/ folder, or set SHIPWRIGHT_SOUNDS."
+        )
+    clear()
+    for f in sorted(config.SOUNDS_DIR.glob("*.py")):
+        spec = importlib.util.spec_from_file_location(f.stem, f)
+        if spec is None or spec.loader is None:
+            raise SystemExit(f"could not load sound file: {f}")
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+
+
+def _available():
+    sound_names = names()
+    return ", ".join(sound_names) if sound_names else "(none)"
+
+
+def _output_path(name):
+    config.OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    return config.OUTPUT_DIR / f"{name}.wav"
+
+
+def _display_path(path):
+    try:
+        return path.relative_to(Path.cwd())
+    except ValueError:
+        return path
+
+
+def render_one(name, ogg=False):
+    if name not in names():
+        raise SystemExit(f"unknown sound '{name}'. Available sounds: {_available()}")
+
+    obj = get(name)()
+    if isinstance(obj, Buffer):
+        from .engine import render_buffer
+        audio = render_buffer(obj)
+        sample_rate = obj.sr
+    elif isinstance(obj, RenderSpec):
+        from .engine import render_spec
+        audio = render_spec(obj)
+        sample_rate = config.SR
+    else:
+        raise SystemExit(
+            f"sound '{name}' returned {type(obj).__name__}; expected Buffer or RenderSpec."
+        )
+
+    import soundfile as sf
+
+    out = _output_path(name)
+    sf.write(out, audio, sample_rate)
+    if ogg:
+        sf.write(out.with_suffix(".ogg"), audio, sample_rate, format="OGG", subtype="VORBIS")
+    dur = len(audio) / sample_rate
+    print(f"  {name:14s} -> {_display_path(out)}   {dur:4.1f}s  peak {abs(audio).max():.2f}")
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="shipwright",
+        description="Render sounds defined in ./sounds to ./output.",
+    )
+    p.add_argument("target", nargs="?",
+                   help="sound name to render, or 'all'. Omit to list sounds.")
+    p.add_argument("--ogg", action="store_true",
+                   help="also write a Vorbis .ogg next to the .wav")
+    p.add_argument("--watch", action="store_true",
+                   help="re-render TARGET on every save (Ctrl-C to stop)")
+    p.add_argument("--version", action="version",
+                   version=f"%(prog)s {__version__}")
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+
+    if args.watch:
+        if not args.target:
+            raise SystemExit("--watch needs a sound name, e.g. shipwright --watch sea_bed")
+        load_sounds()
+        print(f"watching {config.SOUNDS_DIR} — rendering '{args.target}' on save (Ctrl-C to stop)")
+        last = 0
+        while True:
+            m = max((f.stat().st_mtime for f in config.SOUNDS_DIR.glob("*.py")), default=0)
+            if m != last:
+                last = m
+                try:
+                    load_sounds()
+                    render_one(args.target, args.ogg)
+                except Exception as e:
+                    print("  error:", e)
+            time.sleep(0.4)
+
+    load_sounds()
+    if not args.target:
+        print("sounds:", _available())
+        return
+    targets = names() if args.target == "all" else [args.target]
+    if args.target != "all" and args.target not in names():
+        raise SystemExit(f"unknown sound '{args.target}'. Available sounds: {_available()}")
+    print(f"rendering {len(targets)} sound(s) @ {config.SR} Hz")
+    for t0 in targets:
+        render_one(t0, args.ogg)
+
+
+if __name__ == "__main__":
+    main()

shipwright_audio-0.1.0/shipwright/compose.py

@@ -0,0 +1,48 @@
+"""The composition layer (above the engine). Tiny helpers to turn chord
+symbols / pitch lists into Note objects. Swap this for music21 if you want
+richer theory; the engine only cares about the Note list."""
+from .registry import Note
+
+_NOTE = {'C':0,'C#':1,'Db':1,'D':2,'D#':3,'Eb':3,'E':4,'F':5,'F#':6,'Gb':6,
+         'G':7,'G#':8,'Ab':8,'A':9,'A#':10,'Bb':10,'B':11}
+_QUAL = {'':[0,4,7],'m':[0,3,7],'7':[0,4,7,10],'m7':[0,3,7,10],
+         'maj7':[0,4,7,11],'sus2':[0,2,7],'sus4':[0,5,7]}
+
+def note_to_midi(name, octave=4):
+    return 12 * (octave + 1) + _NOTE[name]
+
+def _split(sym):
+    if len(sym) > 1 and sym[1] in '#b':
+        return sym[:2], sym[2:]
+    return sym[:1], sym[1:]
+
+def parse_chord(sym, octave=3):
+    root, qual = _split(sym)
+    base = note_to_midi(root, octave)
+    return [base + iv for iv in _QUAL.get(qual, [0, 4, 7])]
+
+def progression(chords, bpm=70, beats_per_chord=4, repeats=1, octave=3, vel=70):
+    spb = 60.0 / bpm; notes = []; cur = 0.0
+    for _ in range(repeats):
+        for c in chords:
+            for p in parse_chord(c, octave):
+                notes.append(Note(p, cur, beats_per_chord * spb, vel))
+            cur += beats_per_chord * spb
+    return notes
+
+def melody(pitches, bpm=70, note_beats=None, start_beat=0.0, vel=90):
+    spb = 60.0 / bpm; cur = start_beat * spb; notes = []
+    nb = note_beats or [1] * len(pitches)
+    for p, b in zip(pitches, nb):
+        if p is not None:
+            notes.append(Note(p, cur, b * spb * 0.95, vel))
+        cur += b * spb
+    return notes
+
+def bassline(roots, bpm=70, octave=2, beats_per_note=4, repeats=1, vel=80):
+    spb = 60.0 / bpm; notes = []; cur = 0.0
+    for _ in range(repeats):
+        for r in roots:
+            notes.append(Note(note_to_midi(r, octave), cur, beats_per_note * spb * 0.9, vel))
+            cur += beats_per_note * spb
+    return notes

shipwright_audio-0.1.0/shipwright/config.py

@@ -0,0 +1,22 @@
+"""Global settings + paths. One place to change sample rate / output dir.
+
+Data dirs are anchored to the current working directory so the installed
+command works in whatever project you run it from. Override any of them
+with environment variables (SHIPWRIGHT_ROOT / _SOUNDS / _OUTPUT / _SOUNDFONTS).
+"""
+import os
+from pathlib import Path
+
+SR = 44100          # sample rate for everything
+BLOCK = 512         # DawDreamer render block size
+MASTER_CEILING = 0.97  # peak limit so renders never clip the file
+
+
+def _dir(env, default):
+    return Path(os.environ[env]).expanduser() if env in os.environ else default
+
+
+ROOT = _dir("SHIPWRIGHT_ROOT", Path.cwd())
+SOUNDS_DIR = _dir("SHIPWRIGHT_SOUNDS", ROOT / "sounds")
+SOUNDFONT_DIR = _dir("SHIPWRIGHT_SOUNDFONTS", ROOT / "soundfonts")
+OUTPUT_DIR = _dir("SHIPWRIGHT_OUTPUT", ROOT / "output")

shipwright_audio-0.1.0/shipwright/dsp.py

@@ -0,0 +1,70 @@
+"""numpy synthesis primitives for SFX. Pure code -> samples. Deterministic,
+tiny, no black box. Build blips, creaks, whooshes from oscillators + noise
++ envelopes + filters."""
+import numpy as np
+from scipy.signal import butter, sosfilt
+from .config import SR
+
+def t(dur):
+    return np.linspace(0, dur, int(SR * dur), endpoint=False)
+
+# --- oscillators -----------------------------------------------------------
+def sine(freq, dur, amp=1.0, phase=0.0):
+    return amp * np.sin(2 * np.pi * freq * t(dur) + phase)
+
+def saw(freq, dur, amp=1.0):
+    x = t(dur)
+    return amp * (2 * ((freq * x) % 1.0) - 1.0)
+
+def square(freq, dur, amp=1.0, duty=0.5):
+    return amp * np.where((freq * t(dur)) % 1.0 < duty, 1.0, -1.0)
+
+def noise(dur, amp=1.0, seed=None):
+    rng = np.random.default_rng(seed)
+    return amp * rng.uniform(-1, 1, int(SR * dur))
+
+# --- envelopes -------------------------------------------------------------
+def ad_env(sig, attack=0.005, release=0.1):
+    """Apply a linear attack/release to an existing signal."""
+    n = len(sig); env = np.ones(n)
+    a, r = int(attack * SR), int(release * SR)
+    if a: env[:a] = np.linspace(0, 1, a)
+    if r: env[-r:] *= np.linspace(1, 0, r)
+    return sig * env
+
+def perc_env(dur, decay=0.99):
+    """Exponential percussive decay over `dur` seconds."""
+    n = int(SR * dur)
+    return decay ** np.arange(n) if 0 < decay < 1 else np.exp(-np.linspace(0, 6, n))
+
+# --- filters (scipy biquads) ----------------------------------------------
+def _sos(kind, cutoff, order=2):
+    nyq = SR / 2
+    if kind == 'band':
+        wn = [float(np.clip(c / nyq, 1e-4, 0.999)) for c in cutoff]
+    else:
+        wn = float(np.clip(cutoff / nyq, 1e-4, 0.999))
+    return butter(order, wn, btype=kind, output='sos')
+
+def lowpass(sig, cutoff, order=2):  return sosfilt(_sos('low', cutoff, order=order), sig)
+def highpass(sig, cutoff, order=2): return sosfilt(_sos('high', cutoff, order=order), sig)
+def bandpass(sig, low, high, order=2):
+    return sosfilt(_sos('band', [low, high], order=order), sig)
+
+# --- utilities -------------------------------------------------------------
+def layer(*sigs):
+    """Sum signals of any length (zero-padded to the longest)."""
+    n = max(len(s) for s in sigs)
+    out = np.zeros(n)
+    for s in sigs:
+        out[:len(s)] += s
+    return out
+
+def to_stereo(sig, pan=0.0):
+    """Mono -> stereo with equal-power pan (-1 left .. +1 right)."""
+    a = (pan + 1) * np.pi / 4
+    return np.stack([sig * np.cos(a), sig * np.sin(a)], axis=1)
+
+def normalize(sig, peak=0.9):
+    m = np.abs(sig).max()
+    return sig if m == 0 else sig * (peak / m)

shipwright_audio-0.1.0/shipwright/engine.py

@@ -0,0 +1,55 @@
+"""The DawDreamer spine: build a processor graph from a RenderSpec
+(instruments -> per-track gain -> master sum -> bus FX), render offline,
+return stereo samples. Also handles writing Buffers (SFX) straight out."""
+import numpy as np
+import dawdreamer as daw
+from .config import SR, BLOCK, MASTER_CEILING
+from .registry import Buffer, RenderSpec
+
+def _limit(audio):
+    m = float(np.abs(audio).max())
+    if m > MASTER_CEILING:
+        audio = audio * (MASTER_CEILING / m)
+    return audio.astype(np.float32)
+
+def render_buffer(buf: Buffer):
+    s = np.asarray(buf.samples, dtype=np.float32)
+    return _limit(s)
+
+def render_spec(spec: RenderSpec):
+    engine = daw.RenderEngine(SR, BLOCK)
+    nodes, track_outs = [], []
+
+    if spec.duration is not None:
+        dur = spec.duration
+    else:
+        end = max((n.start + n.dur for tr in spec.tracks for n in tr.notes), default=1.0)
+        dur = end + 2.0   # tail for releases/reverb
+
+    for i, tr in enumerate(spec.tracks):
+        inst = engine.make_faust_processor(f"inst{i}")
+        inst.set_dsp_string(tr.instrument.dsp)
+        inst.num_voices = tr.instrument.num_voices
+        for n in tr.notes:
+            inst.add_midi_note(n.pitch, n.vel, n.start, n.dur)
+        nodes.append((inst, [])); last = f"inst{i}"
+
+        for j, fx in enumerate(tr.fx):
+            p = engine.make_faust_processor(f"fx{i}_{j}"); p.set_dsp_string(fx)
+            nodes.append((p, [last])); last = f"fx{i}_{j}"
+
+        lin = 10 ** (tr.gain_db / 20.0)
+        g = engine.make_faust_processor(f"g{i}")
+        g.set_dsp_string(f"process = _,_ : *({lin}),*({lin});")
+        nodes.append((g, [last])); track_outs.append(f"g{i}")
+
+    master = engine.make_add_processor("master", [1.0] * len(track_outs))
+    nodes.append((master, track_outs)); last = "master"
+
+    for k, mfx in enumerate(spec.master_fx):
+        p = engine.make_faust_processor(f"m{k}"); p.set_dsp_string(mfx)
+        nodes.append((p, [last])); last = f"m{k}"
+
+    engine.load_graph(nodes)
+    engine.render(dur)
+    return _limit(engine.get_audio().T)   # (n, 2)

shipwright_audio-0.1.0/shipwright/instruments.py

@@ -0,0 +1,63 @@
+"""The sound-source layer. DawDreamer has no instruments of its own, so we
+supply them. These are Faust programs compiled inside the engine -> zero
+external files, fully reproducible. Swap any of these for a SoundFont or a
+VST later (see README) when you want more 'produced' instruments."""
+from .registry import Instrument
+
+# Faust convention for a polyphonic instrument: expose freq/gain/gate; the
+# engine drives them from MIDI. `effect = _,_;` silences the poly warning.
+_HEAD = 'import("stdfaust.lib");\n'
+
+def saw_lead(cutoff=1500, voices=8):
+    dsp = _HEAD + f"""
+    freq=hslider("freq",440,20,8000,0.01);
+    gain=hslider("gain",0.4,0,1,0.01);
+    gate=button("gate");
+    env=en.adsr(0.01,0.15,0.6,0.25,gate);
+    process=os.sawtooth(freq)*env*gain : fi.resonlp({cutoff},2,1) <: _,_;
+    effect=_,_;
+    """
+    return Instrument("saw_lead", dsp, voices)
+
+def soft_pad(cutoff=1200, voices=8):
+    dsp = _HEAD + f"""
+    freq=hslider("freq",220,20,8000,0.01);
+    gain=hslider("gain",0.3,0,1,0.01);
+    gate=button("gate");
+    env=en.adsr(0.6,0.4,0.8,1.2,gate);
+    osc=(os.sawtooth(freq)+os.sawtooth(freq*1.006)+os.sawtooth(freq*0.994))/3;
+    process=osc*env*gain : fi.lowpass(2,{cutoff}) <: _,_;
+    effect=_,_;
+    """
+    return Instrument("soft_pad", dsp, voices)
+
+def sub_bass(voices=4):
+    dsp = _HEAD + """
+    freq=hslider("freq",110,20,4000,0.01);
+    gain=hslider("gain",0.5,0,1,0.01);
+    gate=button("gate");
+    env=en.adsr(0.01,0.1,0.9,0.2,gate);
+    process=(os.triangle(freq)*0.7+os.osc(freq)*0.3)*env*gain <: _,_;
+    effect=_,_;
+    """
+    return Instrument("sub_bass", dsp, voices)
+
+def pluck(voices=8):
+    dsp = _HEAD + """
+    freq=hslider("freq",440,20,8000,0.01);
+    gain=hslider("gain",0.5,0,1,0.01);
+    gate=button("gate");
+    process=pm.ks(freq, gate)*gain <: _,_;
+    effect=_,_;
+    """
+    return Instrument("pluck", dsp, voices)
+
+# ---- bus / master effects (2 in -> 2 out) --------------------------------
+def reverb(wet=0.3):
+    return _HEAD + f"""
+    wet={wet};
+    process = _,_ <:
+      (_*(1.0-wet), _*(1.0-wet)),
+      (re.stereo_freeverb(0.72,0.5,0.5,23) : _*wet, _*wet)
+      :> _,_;
+    """

shipwright_audio-0.1.0/shipwright/registry.py

@@ -0,0 +1,57 @@
+"""The vocabulary you author in: a @sound registry plus the data types
+that describe a sound. A sound build-function returns EITHER:
+  - a Buffer       (raw samples you synthesised in numpy -> SFX)
+  - a RenderSpec   (tracks of MIDI played by instruments -> music)
+The harness looks at the type and routes it to the right renderer.
+"""
+from dataclasses import dataclass, field
+from typing import List, Optional
+import numpy as np
+from .config import SR
+
+_REGISTRY = {}
+
+def sound(name):
+    """Decorator: register a build-function under a name."""
+    def deco(fn):
+        _REGISTRY[name] = fn
+        return fn
+    return deco
+
+def get(name):   return _REGISTRY[name]
+def names():     return sorted(_REGISTRY)
+def clear():     _REGISTRY.clear()
+
+# ---- SFX path -------------------------------------------------------------
+@dataclass
+class Buffer:
+    samples: np.ndarray      # (n,) mono or (n, 2) stereo, float -1..1
+    sr: int = SR
+
+# ---- Music path -----------------------------------------------------------
+@dataclass
+class Note:
+    pitch: int               # MIDI note number (60 = middle C)
+    start: float             # seconds
+    dur: float               # seconds
+    vel: int = 100           # 1..127
+
+@dataclass
+class Instrument:
+    name: str
+    dsp: str                 # a Faust program (the sound source)
+    num_voices: int = 8      # >0 makes it a polyphonic MIDI instrument
+
+@dataclass
+class Track:
+    instrument: Instrument
+    notes: List[Note]
+    gain_db: float = 0.0
+    fx: List[str] = field(default_factory=list)   # per-track Faust effects
+
+@dataclass
+class RenderSpec:
+    tracks: List[Track]
+    tempo: float = 120.0
+    duration: Optional[float] = None              # auto from notes if None
+    master_fx: List[str] = field(default_factory=list)  # bus effects (reverb...)

shipwright_audio-0.1.0/soundfonts/README.md

@@ -0,0 +1,3 @@
+Drop General-MIDI SoundFonts (`.sf2`) here when you want real sampled
+instruments instead of the built-in Faust synths. A good free starter is
+`FluidR3_GM.sf2`. Then play them with pyfluidsynth (see project README).

shipwright_audio-0.1.0/tests/test_cli.py

@@ -0,0 +1,141 @@
+import os
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from shipwright import cli
+from shipwright import config
+from shipwright.registry import clear
+
+
+def write_sound(path: Path, body: str) -> None:
+    path.write_text(body, encoding="utf-8")
+
+
+@pytest.fixture(autouse=True)
+def reset_registry():
+    clear()
+    yield
+    clear()
+
+
+def test_import_does_not_create_output_dir(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+
+    assert not Path("output").exists()
+
+
+def test_cli_lists_sounds(tmp_path, monkeypatch, capsys):
+    sounds = tmp_path / "sounds"
+    sounds.mkdir()
+    write_sound(
+        sounds / "blip.py",
+        """
+from shipwright import sound, Buffer
+import numpy as np
+
+@sound("blip")
+def blip():
+    return Buffer(np.zeros((8, 2), dtype=np.float32))
+""".lstrip(),
+    )
+    monkeypatch.setattr(config, "SOUNDS_DIR", sounds)
+    monkeypatch.setattr(config, "OUTPUT_DIR", tmp_path / "output")
+
+    cli.main([])
+
+    assert capsys.readouterr().out.strip() == "sounds: blip"
+    assert not (tmp_path / "output").exists()
+
+
+def test_cli_unknown_sound_has_friendly_error(tmp_path, monkeypatch):
+    sounds = tmp_path / "sounds"
+    sounds.mkdir()
+    write_sound(
+        sounds / "blip.py",
+        """
+from shipwright import sound, Buffer
+import numpy as np
+
+@sound("blip")
+def blip():
+    return Buffer(np.zeros((8, 2), dtype=np.float32))
+""".lstrip(),
+    )
+    monkeypatch.setattr(config, "SOUNDS_DIR", sounds)
+
+    with pytest.raises(SystemExit, match="unknown sound 'missing'. Available sounds: blip"):
+        cli.main(["missing"])
+
+
+def test_cli_renders_buffer_sound(tmp_path, monkeypatch, capsys):
+    sounds = tmp_path / "sounds"
+    output = tmp_path / "rendered"
+    sounds.mkdir()
+    write_sound(
+        sounds / "blip.py",
+        """
+from shipwright import sound, Buffer
+import numpy as np
+
+@sound("blip")
+def blip():
+    return Buffer(np.zeros((16, 2), dtype=np.float32))
+""".lstrip(),
+    )
+    monkeypatch.setattr(config, "SOUNDS_DIR", sounds)
+    monkeypatch.setattr(config, "OUTPUT_DIR", output)
+
+    cli.main(["blip"])
+
+    assert (output / "blip.wav").is_file()
+    assert "blip" in capsys.readouterr().out
+
+
+def test_cli_rejects_invalid_sound_return(tmp_path, monkeypatch):
+    sounds = tmp_path / "sounds"
+    sounds.mkdir()
+    write_sound(
+        sounds / "bad.py",
+        """
+from shipwright import sound
+
+@sound("bad")
+def bad():
+    return object()
+""".lstrip(),
+    )
+    monkeypatch.setattr(config, "SOUNDS_DIR", sounds)
+
+    with pytest.raises(SystemExit, match="expected Buffer or RenderSpec"):
+        cli.main(["bad"])
+
+
+def test_cli_routes_render_spec_without_real_dawdreamer(tmp_path, monkeypatch):
+    sounds = tmp_path / "sounds"
+    output = tmp_path / "output"
+    sounds.mkdir()
+    write_sound(
+        sounds / "song.py",
+        """
+from shipwright import sound, RenderSpec
+
+@sound("song")
+def song():
+    return RenderSpec(tracks=[])
+""".lstrip(),
+    )
+    monkeypatch.setattr(config, "SOUNDS_DIR", sounds)
+    monkeypatch.setattr(config, "OUTPUT_DIR", output)
+
+    def fake_render_spec(spec):
+        return np.zeros((16, 2), dtype=np.float32)
+
+    import shipwright.engine
+
+    monkeypatch.setattr(shipwright.engine, "render_spec", fake_render_spec)
+
+    cli.main(["song"])
+
+    assert (output / "song.wav").is_file()

shipwright_audio-0.1.0/tests/test_compose.py

@@ -0,0 +1,20 @@
+from shipwright import compose
+
+
+def test_note_to_midi_and_chord_parsing():
+    assert compose.note_to_midi("C", 4) == 60
+    assert compose.note_to_midi("Bb", 3) == 58
+    assert compose.parse_chord("Dm", octave=3) == [50, 53, 57]
+    assert compose.parse_chord("Cmaj7", octave=4) == [60, 64, 67, 71]
+
+
+def test_progression_and_melody_timing():
+    notes = compose.progression(["C"], bpm=120, beats_per_chord=2)
+    assert [note.pitch for note in notes] == [48, 52, 55]
+    assert {note.start for note in notes} == {0.0}
+    assert {note.dur for note in notes} == {1.0}
+
+    melody = compose.melody([60, None, 62], bpm=60, note_beats=[1, 1, 2])
+    assert [note.pitch for note in melody] == [60, 62]
+    assert [note.start for note in melody] == [0.0, 2.0]
+    assert [note.dur for note in melody] == [0.95, 1.9]

shipwright_audio-0.1.0/tests/test_dsp.py

@@ -0,0 +1,24 @@
+import numpy as np
+
+from shipwright import config, dsp
+
+
+def test_oscillators_have_expected_length_and_range():
+    sig = dsp.sine(440, 0.1)
+
+    assert len(sig) == int(config.SR * 0.1)
+    assert np.max(np.abs(sig)) <= 1.0
+
+
+def test_layer_pads_to_longest_signal():
+    out = dsp.layer(np.ones(3), np.ones(5))
+
+    np.testing.assert_array_equal(out, np.array([2.0, 2.0, 2.0, 1.0, 1.0]))
+
+
+def test_normalize_and_stereo_shape():
+    sig = dsp.normalize(np.array([0.0, 2.0, -1.0]), peak=0.5)
+    stereo = dsp.to_stereo(sig)
+
+    assert np.max(np.abs(sig)) == 0.5
+    assert stereo.shape == (3, 2)

shipwright_audio-0.1.0/tests/test_engine.py

@@ -0,0 +1,14 @@
+import numpy as np
+
+from shipwright.engine import render_buffer
+from shipwright.registry import Buffer
+
+
+def test_render_buffer_limits_peak_and_preserves_shape():
+    audio = np.array([[2.0, -2.0], [0.5, -0.5]], dtype=np.float32)
+
+    rendered = render_buffer(Buffer(audio))
+
+    assert rendered.shape == audio.shape
+    assert rendered.dtype == np.float32
+    assert np.max(np.abs(rendered)) <= 0.97

shipwright_audio-0.1.0/tests/test_metadata.py

@@ -0,0 +1,12 @@
+import re
+from pathlib import Path
+
+import shipwright
+
+
+def test_package_version_matches_project_metadata():
+    pyproject = Path("pyproject.toml").read_text(encoding="utf-8")
+    match = re.search(r'^version = "([^"]+)"$', pyproject, re.MULTILINE)
+
+    assert match is not None
+    assert shipwright.__version__ == match.group(1)