diff --git a/README.md b/README.md index dd857537..7743bcab 100644 --- a/README.md +++ b/README.md @@ -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: ```bash -pnpm run setup -pnpm run repl +pnpm i +pnpm dev ``` ## 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 -- [`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. +Read more about how to use these in your own project [here](https://strudel.cc/technical-manual/project-start). ## Contributing diff --git a/examples/buildless/headless-simple.html b/examples/buildless/headless-simple.html index 013cc87b..15a56161 100644 --- a/examples/buildless/headless-simple.html +++ b/examples/buildless/headless-simple.html @@ -1,10 +1,9 @@ + - diff --git a/examples/buildless/headless-with-samples.html b/examples/buildless/headless-with-samples.html index 2ac7aa71..18b5e379 100644 --- a/examples/buildless/headless-with-samples.html +++ b/examples/buildless/headless-with-samples.html @@ -1,10 +1,10 @@ + - +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)) +--> ``` -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 + +
+ +``` + +When you're using JSX, you could also use the `code` attribute in your markup: + +```html + +*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)) +`}> +``` diff --git a/packages/embed/embed.js b/packages/embed/embed.js index ce2e3b2a..6cf8a3b8 100644 --- a/packages/embed/embed.js +++ b/packages/embed/embed.js @@ -4,7 +4,7 @@ class Strudel extends HTMLElement { } connectedCallback() { setTimeout(() => { - const code = (this.innerHTML + '').replace('', '').trim(); + const code = this.getAttribute('code') || (this.innerHTML + '').replace('', '').trim(); const iframe = document.createElement('iframe'); const src = `https://strudel.cc/#${encodeURIComponent(btoa(code))}`; // const src = `http://localhost:3000/#${encodeURIComponent(btoa(code))}`; diff --git a/packages/repl/README.md b/packages/repl/README.md index b4cbf37c..b82f3434 100644 --- a/packages/repl/README.md +++ b/packages/repl/README.md @@ -2,4 +2,95 @@ 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 + +``` + +You can also pin the version like this: + +```html + +``` + +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 + + + +``` + +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 + +
+ +``` + +## Interacting with the REPL + +If you get a hold of the `strudel-editor` element, you can interact with the strudel REPL from Javascript: + +```html + + + + + +``` + +or + +```html + +
+ +``` + +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. diff --git a/packages/web/README.md b/packages/web/README.md index b3d2f6fe..8b567729 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -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: ```html - + + - ``` -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. 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. @@ -79,4 +76,4 @@ There will probably be an escapte hatch for that in the future. ## More Examples -Check out the examples folder for more examples, both using plain html and vite! \ No newline at end of file +Check out the examples folder for more examples, both using plain html and vite! diff --git a/packages/web/package.json b/packages/web/package.json index 45946398..d70e84c8 100644 --- a/packages/web/package.json +++ b/packages/web/package.json @@ -37,10 +37,10 @@ "@strudel/mini": "workspace:*", "@strudel/tonal": "workspace:*", "@strudel/transpiler": "workspace:*", - "@strudel/webaudio": "workspace:*", - "@rollup/plugin-replace": "^5.0.5" + "@strudel/webaudio": "workspace:*" }, "devDependencies": { - "vite": "^5.0.10" + "vite": "^5.0.10", + "@rollup/plugin-replace": "^5.0.5" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 44e26d08..96bd1dc9 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -449,9 +449,6 @@ importers: packages/web: dependencies: - '@rollup/plugin-replace': - specifier: ^5.0.5 - version: 5.0.5 '@strudel/core': specifier: workspace:* version: link:../core @@ -468,6 +465,9 @@ importers: specifier: workspace:* version: link:../webaudio devDependencies: + '@rollup/plugin-replace': + specifier: ^5.0.5 + version: 5.0.5 vite: specifier: ^5.0.10 version: 5.0.10 @@ -572,9 +572,6 @@ importers: '@strudel/osc': specifier: workspace:* version: link:../packages/osc - '@strudel/repl': - specifier: workspace:* - version: link:../packages/repl '@strudel/serial': specifier: workspace:* version: link:../packages/serial @@ -3744,6 +3741,7 @@ packages: dependencies: '@rollup/pluginutils': 5.1.0 magic-string: 0.30.5 + dev: true /@rollup/pluginutils@3.1.0(rollup@2.79.1): resolution: {integrity: sha512-GksZ6pr6TpIjHm8h9lSQ8pi8BE9VeubNT0OMJ3B5uZJ8pz73NPiqOtCog/x2/QzM1ENChPKxMDhiQuRHsqc+lg==} @@ -3769,6 +3767,7 @@ packages: '@types/estree': 1.0.0 estree-walker: 2.0.2 picomatch: 2.3.1 + dev: true /@rollup/rollup-android-arm-eabi@4.9.2: resolution: {integrity: sha512-RKzxFxBHq9ysZ83fn8Iduv3A283K7zPPYuhL/z9CQuyFrjwpErJx0h4aeb/bnJ+q29GRLgJpY66ceQ/Wcsn3wA==} @@ -7155,6 +7154,7 @@ packages: /estree-walker@2.0.2: resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==} + dev: true /estree-walker@3.0.3: resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==} diff --git a/website/package.json b/website/package.json index ad0cfbcd..b7abacf0 100644 --- a/website/package.json +++ b/website/package.json @@ -33,7 +33,6 @@ "@strudel/midi": "workspace:*", "@strudel/mini": "workspace:*", "@strudel/osc": "workspace:*", - "@strudel/repl": "workspace:*", "@strudel/serial": "workspace:*", "@strudel/soundfonts": "workspace:*", "@strudel/tonal": "workspace:*", diff --git a/website/src/config.ts b/website/src/config.ts index adbcc7f0..012a6542 100644 --- a/website/src/config.ts +++ b/website/src/config.ts @@ -102,9 +102,10 @@ export const SIDEBAR: Sidebar = { { text: 'Strudel vs Tidal', link: 'learn/strudel-vs-tidal' }, ], Development: [ + { text: 'Strudel in your Project', link: 'technical-manual/project-start' }, + { text: 'Packages', link: 'technical-manual/packages' }, { text: 'REPL', link: 'technical-manual/repl' }, { text: 'Sounds', link: 'technical-manual/sounds' }, - { text: 'Packages', link: 'technical-manual/packages' }, { text: 'Docs', link: 'technical-manual/docs' }, { text: 'Testing', link: 'technical-manual/testing' }, // { text: 'Internals', link: 'technical-manual/internals' }, diff --git a/website/src/docs/MiniRepl.jsx b/website/src/docs/MiniRepl.jsx index cb0f26f7..fe618965 100644 --- a/website/src/docs/MiniRepl.jsx +++ b/website/src/docs/MiniRepl.jsx @@ -5,7 +5,6 @@ import { getPunchcardPainter } from '@strudel/draw'; import { transpiler } from '@strudel/transpiler'; import { getAudioContext, webaudioOutput, initAudioOnFirstClick } from '@strudel/webaudio'; import { StrudelMirror } from '@strudel/codemirror'; -// import { prebake } from '@strudel/repl'; import { prebake } from '../repl/prebake.mjs'; import { loadModules } from '../repl/util.mjs'; import Claviature from '@components/Claviature'; diff --git a/website/src/pages/technical-manual/packages.mdx b/website/src/pages/technical-manual/packages.mdx index d378f781..9a067317 100644 --- a/website/src/pages/technical-manual/packages.mdx +++ b/website/src/pages/technical-manual/packages.mdx @@ -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). 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 These package are the most essential. You might want to use all of those if you're using strudel in your project: diff --git a/website/src/pages/technical-manual/project-start.mdx b/website/src/pages/technical-manual/project-start.mdx new file mode 100644 index 00000000..64081625 --- /dev/null +++ b/website/src/pages/technical-manual/project-start.mdx @@ -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 + +``` + +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 + +``` + +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 + + + + +``` + +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 + + + + +``` + +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 + + + + +``` + +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 + + + + + +``` + +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)