dough

good for baking. wip synth engine that runs natively and in the browser.

see the superdough puzzle for details.

Demo

dough is deployed at dough.strudel.cc.

Minimal Example (WASM)

here's a minimal example on how to run dough in an html file:

<button id="runButton">run</button>
<button id="stopButton">stop</button>
<script type="module">
  // load dough from cdn
  import { Dough } from "https://unpkg.com/[email protected]/dough.js";
  // init dough with base url
  const dough = new Dough({
    base: "https://unpkg.com/[email protected]/",
  });
  // start a sine sound, read https://dough.strudel.cc/reference.html for all options
  runButton.onclick = () => dough.evaluate({ sound: "sine" });
  // stop all sound
  stopButton.onclick = () => dough.hush();
</script>

that's all you need! save this as index.html and in the same folder, run:

npx dough-synth # open server with coop/coep headers

..then open http://localhost:8888/ and you should hear a sine wave when clicking run.

because dough uses shared memory, when serving an application that uses it, you need to have a cross-origin isolated document. that's what npx dough-synth does for you for quick local testing.

dough-synth on npm

you can install dough-synth from npm:

npm i dough-synth

it's recommended you pin the version, as breaking changes can still happen.

Vite Example (WASM)

when using dough with vite, there's a slightly different setup:

import { Dough, doughsamples } from "dough-synth";
import wasm from "dough-synth/dough.wasm?url";
import workletCode from "dough-synth/dough.js?raw";

const dough = new Dough({
  wasm, // wasm file url or ArrayBuffer
  workletCode, // worklet code string
  audioContext, // audio context (optional)
});

// start a sine sound, read https://dough.strudel.cc/reference.html for all options
runButton.onclick = () => dough.evaluate({ sound: "sine", freq: 330 });
// stop all sound
stopButton.onclick = () => dough.hush();

the wasm and workletCode options fit directly with vite's ?url and ?raw directives of the needed files.

contributing

in this repository, we practise jam oriented programming. this means:

• anybody is welcome to make changes
• to become a collaborator, create an issue and ask to get added
• we aim to be hierarchy free, assuming good faith in everyone
• either create a PR, or push directly to main, both is fine
• we try to follow the design goals, which are open to change

design goals

these are the initial design goals for dough:

• runs natively and in the browser
• a single .c file
• keep it simple stupid
• runs fast
• similar to superdough

Development Setup

To be able to build and test the native version, we're going to install:

1. portaudio for cross platform audio
2. liblo for osc messaging
3. pkg-config to simplify building
4. node.js to run the osc bridge

To build and test the browser version, you need:

1. clang to compile c to wasm
2. node.js to run the dev server

MacOS Setup

1. make sure you have https://brew.sh/ installed
2. install libraries:

brew install pkg-config liblo portaudio libsndfile libsamplerate

Linux Setup

sudo apt install liblo-dev portaudio19-dev libsndfile1-dev libsamplerate0-dev lld
# .. should work similarly with other package managers

Get the Source Code

git clone https://codeberg.org/uzu/dough.git && cd dough

Native Version

here's how you compile and run the native version:

./scripts/build-native.sh

testing with strudel

so far, i'm doing my testing with strudel. to make sure strudel can talk to dough, you need to run the osc bridge in a separate terminal:

# run strudel osc bridge:
npx --yes @strudel/osc --port 7771

now you can run a pattern with .osc()!

WASM version

the demo is not deployed yet, so you need to run it locally:

1. run the dev server* via node server.mjs
2. open localhost:8888
3. press play

compiling the wasm version

here's how to compile to WebAssembly using clang:

./scripts/build-wasm.sh
# or
npm run w # if you use npm

after compiling, refresh the page to get the new version of dough.wasm.

MacOS: the system clang might not work, so you'd need to brew install llvm then echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.zshrc.

dough-synth on npm

you can install dough on npm: npm i dough-synth

publishing to npm

here's how to publish a new version to npm:

# make sure you have a clean git
npm run w
npm run test
npm pack --dry-run
npm version patch
npm login
npm publish
git push && git push --tags

git lfs

this repo uses git lfs. you may have to install the git-lfs plugin and initialize it in the repo by running git lfs install. if the files you see in snapshots/* are smaller than 1kB then git-lfs is not working.

snapshot testing

the reference contained in dough.js is tested with snapshots. if you're in a "correct" state, meaning dough does what you expect it to do, run:

./scripts/write-snapshots.sh

at any later time, you can test the current behavior of dough against the previously "correct" state via:

./scripts/test-snapshots.sh

this is also part of test.yml to make sure things don't break.

note that .pcm files are stored with git lfs, which is why write-snapshots will track them automatically.

inspiration

dough is inspired by

• dirt
• superdough
• kabelsalat
• noisecraft