diff --git a/packages/embed/README.md b/packages/embed/README.md index e09ca811..0ab8f475 100644 --- a/packages/embed/README.md +++ b/packages/embed/README.md @@ -2,32 +2,63 @@ 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 +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..5128a003 100644 --- a/packages/repl/README.md +++ b/packages/repl/README.md @@ -2,4 +2,93 @@ 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]() that runs the REPL. diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 033c6a7e..7db5a480 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -452,9 +452,6 @@ importers: packages/web: dependencies: - '@rollup/plugin-replace': - specifier: ^5.0.5 - version: 5.0.5 '@strudel/core': specifier: workspace:* version: link:../core @@ -471,6 +468,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 @@ -563,6 +563,9 @@ importers: '@strudel/draw': specifier: workspace:* version: link:../packages/draw + '@strudel/embed': + specifier: workspace:* + version: link:../packages/embed '@strudel/hydra': specifier: workspace:* version: link:../packages/hydra @@ -3742,6 +3745,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==} @@ -3767,6 +3771,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==} @@ -7168,6 +7173,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 7af9e61e..cadcb6a1 100644 --- a/website/package.json +++ b/website/package.json @@ -34,6 +34,7 @@ "@strudel/mini": "workspace:*", "@strudel/osc": "workspace:*", "@strudel/repl": "workspace:*", + "@strudel/embed": "workspace:*", "@strudel/serial": "workspace:*", "@strudel/soundfonts": "workspace:*", "@strudel/tonal": "workspace:*", diff --git a/website/src/config.ts b/website/src/config.ts index adbcc7f0..d6ecb559 100644 --- a/website/src/config.ts +++ b/website/src/config.ts @@ -102,6 +102,7 @@ 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: 'REPL', link: 'technical-manual/repl' }, { text: 'Sounds', link: 'technical-manual/sounds' }, { text: 'Packages', link: 'technical-manual/packages' }, diff --git a/website/src/layouts/MainLayout.astro b/website/src/layouts/MainLayout.astro index 49952a7e..190e0dd5 100644 --- a/website/src/layouts/MainLayout.astro +++ b/website/src/layouts/MainLayout.astro @@ -28,6 +28,10 @@ const githubEditUrl = `${CONFIG.GITHUB_EDIT_URL}/${currentFile}`; {frontmatter.title ? `${frontmatter.title} 🌀 ${CONFIG.SITE.title}` : CONFIG.SITE.title} + 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..638065ea --- /dev/null +++ b/website/src/pages/technical-manual/project-start.mdx @@ -0,0 +1,122 @@ +--- +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. + +### Inside an iframe via `@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. + +This is the result: + +*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))`}> + + +For alternative ways to load this package, see [@strudel/embed README](https://github.com/tidalcycles/strudel/tree/main/packages/embed#strudelembed). + +### Without an iframe via `@strudel/repl` + +Loading strudel directly in your site 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.. + +*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))`}> + + +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.