hacklab/strudel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #1006 from tidalcycles/update-examples

Browse source 
using strudel in your project guide + cleanup examples
This commit is contained in:
Felix Roos 2024-03-22 23:53:51 +01:00 • committed by GitHub
commit 5537652497
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
14 changed files with 307 additions and 62 deletions
Download patch file Download diff file Expand all files Collapse all files

18
README.md
View file

@ -15,25 +15,15 @@ An experiment in making a [Tidal](https://github.com/tidalcycles/tidal/) using w
After cloning the project, you can run the REPL locally: After cloning the project, you can run the REPL locally:
```bash ```bash
pnpm run setup pnpm i
pnpm run repl pnpm dev
``` ```
## Using Strudel In Your Project ## Using Strudel In Your Project
There are multiple npm packages you can use to use strudel, or only parts of it, in your project: This project is organized into many [packages](./packages), which are also available on [npm](https://www.npmjs.com/search?q=%40strudel).
- [`core`](./packages/core/): tidal pattern engine Read more about how to use these in your own project [here](https://strudel.cc/technical-manual/project-start).
- [`mini`](./packages/mini): mini notation parser + core binding
- [`transpiler`](./packages/transpiler): user code transpiler
- [`webaudio`](./packages/webaudio): webaudio output
- [`osc`](./packages/osc): bindings to communicate via OSC
- [`midi`](./packages/midi): webmidi bindings
- [`serial`](./packages/serial): webserial bindings
- [`tonal`](./packages/tonal): tonal functions
- ... [and there are more](./packages/)
Click on the package names to find out more about each one.
## Contributing ## Contributing

7
examples/buildless/headless-simple.html
View file

@ -1,10 +1,9 @@
<!doctype html> <!doctype html>
<script src="https://unpkg.com/@strudel/web@1.0.3"></script>
<button id="play">play</button> <button id="play">play</button>
<button id="stop">stop</button> <button id="stop">stop</button>
<script type="module"> <script>
import { initStrudel } from 'https://cdn.skypack.dev/@strudel/web@0.8.2'; strudel.initStrudel();
initStrudel();
document.getElementById('play').addEventListener('click', () => evaluate('note("c a f e").jux(rev)')); document.getElementById('play').addEventListener('click', () => evaluate('note("c a f e").jux(rev)'));
document.getElementById('play').addEventListener('stop', () => hush()); document.getElementById('play').addEventListener('stop', () => hush());
</script> </script>

4
examples/buildless/headless-with-samples.html
View file

@ -1,10 +1,10 @@
<!doctype html> <!doctype html>
<script src="https://unpkg.com/@strudel/web@1.0.3"></script>
<button id="a">A</button> <button id="a">A</button>
<button id="b">B</button> <button id="b">B</button>
<button id="c">C</button> <button id="c">C</button>
<button id="stop">stop</button> <button id="stop">stop</button>
<script type="module"> <script>
import { initStrudel } from 'https://cdn.skypack.dev/@strudel/web@0.8.2';
initStrudel({ initStrudel({
prebake: () => samples('github:tidalcycles/dirt-samples'), prebake: () => samples('github:tidalcycles/dirt-samples'),
}); });

71
packages/embed/README.md
View file

@ -2,32 +2,63 @@
This package contains a embeddable web component for the Strudel REPL. This package contains a embeddable web component for the Strudel REPL.
## Usage ## Usage via Script Tag
Either install with `npm i @strudel/embed` or just use a cdn to import the script: Use this code in any HTML file:
```html ```html
<script src="https://unpkg.com/@strudel/embed@latest"></script> <script src="https://unpkg.com/@strudel/embed@latest"></script>
<strudel-repl> <strudel-repl>
<!-- <!--
note(`[[e5 [b4 c5] d5 [c5 b4]] setcps(1)
[a4 [a4 c5] e5 [d5 c5]] n("<0 1 2 3 4>*8").scale('G4 minor')
[b4 [~ c5] d5 e5] .s("gm_lead_6_voice")
[c5 a4 a4 ~] .clip(sine.range(.2,.8).slow(8))
[[~ d5] [~ f5] a5 [g5 f5]] .jux(rev)
[e5 [~ c5] e5 [d5 c5]] .room(2)
[b4 [b4 c5] d5 e5] .sometimes(add(note("12")))
[c5 a4 a4 ~]], .lpf(perlin.range(200,20000).slow(4))
[[e2 e3]*4] -->
[[a2 a3]*4]
[[g#2 g#3]*2 [e2 e3]*2]
[a2 a3 a2 a3 a2 a3 b1 c2]
[[d2 d3]*4]
[[c2 c3]*4]
[[b1 b2]*2 [e2 e3]*2]
[[a1 a2]*4]`).slow(16)
-->
</strudel-repl> </strudel-repl>
``` ```
Note that the Code is placed inside HTML comments to prevent the browser from treating it as HTML. This will load the strudel website in an iframe, using the code provided within the HTML comments `<!-- -->`.
The HTML comments are needed to make sure the browser won't interpret it as HTML.
Alternatively you can create a REPL from JavaScript like this:
```html
<script src="https://unpkg.com/@strudel/embed@1.0.2"></script>
<div id="strudel"></div>
<script>
let editor = document.createElement('strudel-repl');
editor.setAttribute(
'code',
`setcps(1)
n("<0 1 2 3 4>*8").scale('G4 minor')
.s("gm_lead_6_voice")
.clip(sine.range(.2,.8).slow(8))
.jux(rev)
.room(2)
.sometimes(add(note("12")))
.lpf(perlin.range(200,20000).slow(4))`,
);
document.getElementById('strudel').append(editor);
</script>
```
When you're using JSX, you could also use the `code` attribute in your markup:
```html
<script src="https://unpkg.com/@strudel/embed@1.0.2"></script>
<strudel-repl code={`
setcps(1)
n("<0 1 2 3 4>*8").scale('G4 minor')
.s("gm_lead_6_voice")
.clip(sine.range(.2,.8).slow(8))
.jux(rev)
.room(2)
.sometimes(add(note("12")))
.lpf(perlin.range(200,20000).slow(4))
`}></strudel-repl>
```

2
packages/embed/embed.js
View file

@ -4,7 +4,7 @@ class Strudel extends HTMLElement {
} }
connectedCallback() { connectedCallback() {
setTimeout(() => { setTimeout(() => {
const code = (this.innerHTML + '').replace('<!--', '').replace('-->', '').trim(); const code = this.getAttribute('code') || (this.innerHTML + '').replace('<!--', '').replace('-->', '').trim();
const iframe = document.createElement('iframe'); const iframe = document.createElement('iframe');
const src = `https://strudel.cc/#${encodeURIComponent(btoa(code))}`; const src = `https://strudel.cc/#${encodeURIComponent(btoa(code))}`;
// const src = `http://localhost:3000/#${encodeURIComponent(btoa(code))}`; // const src = `http://localhost:3000/#${encodeURIComponent(btoa(code))}`;

93
packages/repl/README.md
View file

@ -2,4 +2,95 @@
The Strudel REPL as a web component. The Strudel REPL as a web component.
[Usage example](https://github.com/tidalcycles/strudel/blob/main/examples/buildless/web-component-no-iframe.html) ## Add Script Tag
First place this script tag once in your HTML:
```html
<script src="https://unpkg.com/@strudel/repl@latest"></script>
```
You can also pin the version like this:
```html
<script src="https://unpkg.com/@strudel/repl@1.0.2"></script>
```
This has the advantage that your code will always work, regardless of potential breaking changes in the strudel codebase.
See [releases](https://github.com/tidalcycles/strudel/releases) for the latest versions.
## Use Web Component
When you've added the script tag, you can use the `strudel-editor` web component:
```html
<strudel-editor>
<!--
setcps(1)
n("<0 1 2 3 4>*8").scale('G4 minor')
.s("gm_lead_6_voice")
.clip(sine.range(.2,.8).slow(8))
.jux(rev)
.room(2)
.sometimes(add(note("12")))
.lpf(perlin.range(200,20000).slow(4))
-->
</strudel-editor>
```
This will load the Strudel REPL using the code provided within the HTML comments `<!-- -->`.
The HTML comments are needed to make sure the browser won't interpret it as HTML.
Alternatively you can create a REPL from JavaScript like this:
```html
<script src="https://unpkg.com/@strudel/repl@latest"></script>
<div id="strudel"></div>
<script>
const repl = document.createElement('strudel-editor');
repl.setAttribute(
'code',
`setcps(1)
n("<0 1 2 3 4>*8").scale('G4 minor')
.s("gm_lead_6_voice")
.clip(sine.range(.2,.8).slow(8))
.jux(rev)
.room(2)
.sometimes(add(note("12")))
.lpf(perlin.range(200,20000).slow(4))`,
);
document.getElementById('strudel').append(repl);
</script>
```
## Interacting with the REPL
If you get a hold of the `strudel-editor` element, you can interact with the strudel REPL from Javascript:
```html
<script src="https://unpkg.com/@strudel/repl@latest"></script>
<strudel-editor id="repl">
<!-- ... -->
</strudel-editor>
<script>
const repl = document.getElementById('repl');
console.log(repl.editor);
</script>
```
or
```html
<script src="https://unpkg.com/@strudel/repl@latest"></script>
<div id="strudel"></div>
<script>
const repl = document.createElement('strudel-editor');
repl.setAttribute('code', `...`);
document.getElementById('strudel').append(repl);
console.log(repl.editor);
</script>
```
The `.editor` property on the `strudel-editor` web component gives you the instance of [StrudelMirror](https://github.com/tidalcycles/strudel/blob/a46bd9b36ea7d31c9f1d3fca484297c7da86893f/packages/codemirror/codemirror.mjs#L124) that runs the REPL.
For example, you could use `setCode` to change the code from the outside, `start` / `stop` to toggle playback or `evaluate` to evaluate the code.

13
packages/web/README.md
View file

@ -7,20 +7,17 @@ This package provides an easy to use bundle of multiple strudel packages for the
Save this code as a `.html` file and double click it: Save this code as a `.html` file and double click it:
```html ```html
<!DOCTYPE html> <!doctype html>
<script src="https://unpkg.com/@strudel/web@1.0.3"></script>
<button id="play">play</button> <button id="play">play</button>
<button id="stop">stop</button> <button id="stop">stop</button>
<script type="module"> <script>
import { initStrudel } from 'https://cdn.skypack.dev/@strudel/web@0.8.2';
initStrudel(); initStrudel();
document.getElementById('play').addEventListener('click', () => note('<c a f e>(3,8)').play()); document.getElementById('play').addEventListener('click', () => note('<c a f e>(3,8)').jux(rev).play());
document.getElementById('stop').addEventListener('click', () => hush()); document.getElementById('stop').addEventListener('click', () => hush());
</script> </script>
``` ```
With the help of [skypack](https://www.skypack.dev/), you don't need a bundler nor a server.
As soon as you call `initStrudel()`, all strudel functions are made available. As soon as you call `initStrudel()`, all strudel functions are made available.
In this case, we are using the `note` function to create a pattern. In this case, we are using the `note` function to create a pattern.
To actually play the pattern, you have to append `.play()` to the end. To actually play the pattern, you have to append `.play()` to the end.
@ -79,4 +76,4 @@ There will probably be an escapte hatch for that in the future.
## More Examples ## More Examples
Check out the examples folder for more examples, both using plain html and vite! Check out the examples folder for more examples, both using plain html and vite!

6
packages/web/package.json
View file

@ -37,10 +37,10 @@
"@strudel/mini": "workspace:*", "@strudel/mini": "workspace:*",
"@strudel/tonal": "workspace:*", "@strudel/tonal": "workspace:*",
"@strudel/transpiler": "workspace:*", "@strudel/transpiler": "workspace:*",
"@strudel/webaudio": "workspace:*", "@strudel/webaudio": "workspace:*"
"@rollup/plugin-replace": "^5.0.5"
}, },
"devDependencies": { "devDependencies": {
"vite": "^5.0.10" "vite": "^5.0.10",
"@rollup/plugin-replace": "^5.0.5"
} }
} }

12
pnpm-lock.yaml generated
View file

@ -449,9 +449,6 @@ importers:
packages/web: packages/web:
dependencies: dependencies:
'@rollup/plugin-replace':
specifier: ^5.0.5
version: 5.0.5
'@strudel/core': '@strudel/core':
specifier: workspace:* specifier: workspace:*
version: link:../core version: link:../core
@ -468,6 +465,9 @@ importers:
specifier: workspace:* specifier: workspace:*
version: link:../webaudio version: link:../webaudio
devDependencies: devDependencies:
'@rollup/plugin-replace':
specifier: ^5.0.5
version: 5.0.5
vite: vite:
specifier: ^5.0.10 specifier: ^5.0.10
version: 5.0.10 version: 5.0.10
@ -572,9 +572,6 @@ importers:
'@strudel/osc': '@strudel/osc':
specifier: workspace:* specifier: workspace:*
version: link:../packages/osc version: link:../packages/osc
'@strudel/repl':
specifier: workspace:*
version: link:../packages/repl
'@strudel/serial': '@strudel/serial':
specifier: workspace:* specifier: workspace:*
version: link:../packages/serial version: link:../packages/serial
@ -3744,6 +3741,7 @@ packages:
dependencies: dependencies:
'@rollup/pluginutils': 5.1.0 '@rollup/pluginutils': 5.1.0
magic-string: 0.30.5 magic-string: 0.30.5
dev: true
/@rollup/pluginutils@3.1.0(rollup@2.79.1): /@rollup/pluginutils@3.1.0(rollup@2.79.1):
resolution: {integrity: sha512-GksZ6pr6TpIjHm8h9lSQ8pi8BE9VeubNT0OMJ3B5uZJ8pz73NPiqOtCog/x2/QzM1ENChPKxMDhiQuRHsqc+lg==} resolution: {integrity: sha512-GksZ6pr6TpIjHm8h9lSQ8pi8BE9VeubNT0OMJ3B5uZJ8pz73NPiqOtCog/x2/QzM1ENChPKxMDhiQuRHsqc+lg==}
@ -3769,6 +3767,7 @@ packages:
'@types/estree': 1.0.0 '@types/estree': 1.0.0
estree-walker: 2.0.2 estree-walker: 2.0.2
picomatch: 2.3.1 picomatch: 2.3.1
dev: true
/@rollup/rollup-android-arm-eabi@4.9.2: /@rollup/rollup-android-arm-eabi@4.9.2:
resolution: {integrity: sha512-RKzxFxBHq9ysZ83fn8Iduv3A283K7zPPYuhL/z9CQuyFrjwpErJx0h4aeb/bnJ+q29GRLgJpY66ceQ/Wcsn3wA==} resolution: {integrity: sha512-RKzxFxBHq9ysZ83fn8Iduv3A283K7zPPYuhL/z9CQuyFrjwpErJx0h4aeb/bnJ+q29GRLgJpY66ceQ/Wcsn3wA==}
@ -7155,6 +7154,7 @@ packages:
/estree-walker@2.0.2: /estree-walker@2.0.2:
resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==} resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
dev: true
/estree-walker@3.0.3: /estree-walker@3.0.3:
resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==} resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}

1
website/package.json
View file

@ -33,7 +33,6 @@
"@strudel/midi": "workspace:*", "@strudel/midi": "workspace:*",
"@strudel/mini": "workspace:*", "@strudel/mini": "workspace:*",
"@strudel/osc": "workspace:*", "@strudel/osc": "workspace:*",
"@strudel/repl": "workspace:*",
"@strudel/serial": "workspace:*", "@strudel/serial": "workspace:*",
"@strudel/soundfonts": "workspace:*", "@strudel/soundfonts": "workspace:*",
"@strudel/tonal": "workspace:*", "@strudel/tonal": "workspace:*",

3
website/src/config.ts
View file

@ -102,9 +102,10 @@ export const SIDEBAR: Sidebar = {
{ text: 'Strudel vs Tidal', link: 'learn/strudel-vs-tidal' }, { text: 'Strudel vs Tidal', link: 'learn/strudel-vs-tidal' },
], ],
Development: [ Development: [
{ text: 'Strudel in your Project', link: 'technical-manual/project-start' },
{ text: 'Packages', link: 'technical-manual/packages' },
{ text: 'REPL', link: 'technical-manual/repl' }, { text: 'REPL', link: 'technical-manual/repl' },
{ text: 'Sounds', link: 'technical-manual/sounds' }, { text: 'Sounds', link: 'technical-manual/sounds' },
{ text: 'Packages', link: 'technical-manual/packages' },
{ text: 'Docs', link: 'technical-manual/docs' }, { text: 'Docs', link: 'technical-manual/docs' },
{ text: 'Testing', link: 'technical-manual/testing' }, { text: 'Testing', link: 'technical-manual/testing' },
// { text: 'Internals', link: 'technical-manual/internals' }, // { text: 'Internals', link: 'technical-manual/internals' },

1
website/src/docs/MiniRepl.jsx
View file

@ -5,7 +5,6 @@ import { getPunchcardPainter } from '@strudel/draw';
import { transpiler } from '@strudel/transpiler'; import { transpiler } from '@strudel/transpiler';
import { getAudioContext, webaudioOutput, initAudioOnFirstClick } from '@strudel/webaudio'; import { getAudioContext, webaudioOutput, initAudioOnFirstClick } from '@strudel/webaudio';
import { StrudelMirror } from '@strudel/codemirror'; import { StrudelMirror } from '@strudel/codemirror';
// import { prebake } from '@strudel/repl';
import { prebake } from '../repl/prebake.mjs'; import { prebake } from '../repl/prebake.mjs';
import { loadModules } from '../repl/util.mjs'; import { loadModules } from '../repl/util.mjs';
import Claviature from '@components/Claviature'; import Claviature from '@components/Claviature';

9
website/src/pages/technical-manual/packages.mdx
View file

@ -19,6 +19,15 @@ The purpose of the multiple packages is to
[See the latest published packages on npm](https://www.npmjs.com/search?q=%40strudel). [See the latest published packages on npm](https://www.npmjs.com/search?q=%40strudel).
Here is an overview of all the packages: Here is an overview of all the packages:
### Umbrella Packages
These packages give you a batteries-included point of getting started, and most likely the thing you'd want to use in your project:
- [repl](https://github.com/tidalcycles/strudel/tree/main/packages/repl): The Strudel REPL as a web component.
- [web](https://github.com/tidalcycles/strudel/tree/main/packages/web): Strudel library for the browser, without UI.
To find out more about these two, read [Using Strudel in Your Project](/technical-manual/project-start)
### Essential Packages ### Essential Packages
These package are the most essential. You might want to use all of those if you're using strudel in your project: These package are the most essential. You might want to use all of those if you're using strudel in your project:

129
website/src/pages/technical-manual/project-start.mdx Normal file
View file

@ -0,0 +1,129 @@
---
title: Using Strudel in your Project
layout: ../../layouts/MainLayout.astro
---
# Using Strudel in your Project
This Guide shows you the different ways to get started with using Strudel in your own project.
## Embedding the Strudel REPL
There are 3 quick ways to embed strudel in your website:
1. Embed the strudel website as an iframe directly
2. Embed the strudel website as an iframe using `@strudel/embed`
3. Embed the REPL directly using `@strudel/repl`
### Inside an iframe
Using an iframe is the most easy way to embed a studel tune.
You can embed any pattern of your choice via an iframe and the URL of the pattern of your choice:
```html
<iframe src="https://strudel.cc/?xwWRfuCE8TAR" width="600" height="300"></iframe>
```
The URL can be obtained by pressing `share` in the REPL.
Note that these share links depend on a database, which is not guaranteed to live forever.
To make sure your code is not lost, you can also use the long url:
```html
<iframe
src="https://strudel.cc/#c2V0Y3BzKDEpCm4oIjwwIDEgMiAzIDQ%2BKjgiKS5zY2FsZSgnRzQgbWlub3InKQoucygiZ21fbGVhZF82X3ZvaWNlIikKLmNsaXAoc2luZS5yYW5nZSguMiwuOCkuc2xvdyg4KSkKLmp1eChyZXYpCi5yb29tKDIpCi5zb21ldGltZXMoYWRkKG5vdGUoIjEyIikpKQoubHBmKHBlcmxpbi5yYW5nZSgyMDAsMjAwMDApLnNsb3coNCkp"
width="600"
height="300"
></iframe>
```
That long URL can just be copy pasted from the URL bar when you're on the strudel website. It always reflects the latest evaluation of your code.
### @strudel/embed
To simplify the process of emebdding via an iframe, you can use the package `@strudel/embed`:
```html
<script src="https://unpkg.com/@strudel/embed@latest"></script>
<strudel-repl>
<!--
setcps(1)
n("<0 1 2 3 4>*8").scale('G4 minor')
.s("gm_lead_6_voice")
.clip(sine.range(.2,.8).slow(8))
.jux(rev)
.room(2)
.sometimes(add(note("12")))
.lpf(perlin.range(200,20000).slow(4))
-->
</strudel-repl>
```
This will load the strudel website in an iframe, using the code provided within the HTML comments `<!-- -->`.
The HTML comments are needed to make sure the browser won't interpret it as HTML.
For alternative ways to load this package, see the [@strudel/embed README](https://github.com/tidalcycles/strudel/tree/main/packages/embed#strudelembed).
### @strudel/repl
Loading strudel directly in your site, without an iframe, looks similar to the iframe variant:
```html
<script src="https://unpkg.com/@strudel/repl@latest"></script>
<strudel-editor>
<!--
setcps(1)
n("<0 1 2 3 4>*8").scale('G4 minor')
.s("gm_lead_6_voice")
.clip(sine.range(.2,.8).slow(8))
.jux(rev)
.room(2)
.sometimes(add(note("12")))
.lpf(perlin.range(200,20000).slow(4))
-->
</strudel-editor>
```
Here, we're loading `@strudel/repl` instead of `@strudel/embed`, and the component is called `strudel-editor` instead of `strudel-repl`.
Yes the naming is a bit confusing..
The upside of using the repl without an iframe is that you can pin the strudel version you're using:
```html
<script src="https://unpkg.com/@strudel/repl@1.0.2"></script>
<strudel-editor>
<!--
...
-->
</strudel-editor>
```
This will guarantee your pattern wont break due to changes to the strudel project in the future.
For more info on this package, see the [@strudel/repl README](https://github.com/tidalcycles/strudel/tree/main/packages/repl#strudelrepl).
## With your own UI
The above approach assumes you want to use the builtin [codemirror](https://codemirror.net/) editor.
If you'd rather use your own UI, you can use the `@strudel/web` package:
```html
<!doctype html>
<script src="https://unpkg.com/@strudel/web@1.0.3"></script>
<button id="play">play</button>
<button id="stop">stop</button>
<script>
initStrudel();
document.getElementById('play').addEventListener('click', () => note('<c a f e>(3,8)').jux(rev).play());
document.getElementById('stop').addEventListener('click', () => hush());
</script>
```
For more info on this package, see the [@strudel/web README](https://github.com/tidalcycles/strudel/tree/main/packages/web#strudelweb).
## Via npm
[All the packages and many more are available on npm under the @strudel namespace](https://www.npmjs.com/search?q=%40strudel).
There are actually many more packages you can use to have fine grained control over what you use and what not.
To use these packages, you have to use a bundler that supports es modules, like [vite](https://vitejs.dev/).
To find out more about the purpose of each package, see [Packages](/technical-manual/packages)