1---
2title: Using Strudel in your Project
3layout: ../../layouts/MainLayout.astro
4---
5
6# Using Strudel in your Project
7
8This Guide shows you the different ways to get started with using Strudel in your own project.
9
10## Respect the license
11
12First, please take a moment to understand Strudel's free/open source license,
13[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.en.html).
14
15Here is a lay summary, but check the license for legal definitions and responsibilities.
16
17- You can distribute modified versions if you keep track of the changes and the date you made them.
18- You must license derivative work under the same license.
19- Source code must be distributed along with web publication.
20
21Among other things, it means that when you share your work, the whole application must be shared under the same free/open source license, or one compatible with it. This is because we want Strudel to stay free/open source. In other words, you are not permitted to distribute integrations of Strudel with libraries or other code that does not have a compatible free/open source license.
22
23This also applies to clones informed by reading Strudel's source code, as legally speaking, that counts as a 'derivative work'. Again, please [read the licence](https://www.gnu.org/licenses/agpl-3.0.en.html) for details.
24
25## Embedding the Strudel REPL
26
27There are 3 quick ways to embed strudel in your website:
28
291. Embed the strudel website as an iframe directly
302. Embed the strudel website as an iframe using `@strudel/embed`
313. Embed the REPL directly using `@strudel/repl`
32
33### Inside an iframe
34
35Using an iframe is the most easy way to embed a strudel tune.
36You can embed any pattern of your choice via an iframe and the URL of the pattern of your choice:
37
38```html
39<iframe src="https://strudel.cc/?xwWRfuCE8TAR" width="600" height="300"></iframe>
40```
41
42The URL can be obtained by pressing `share` in the REPL.
43Note that these share links depend on a database, which is not guaranteed to live forever.
44To make sure your code is not lost, you can also use the long url:
45
46```html
47<iframe
48  src="https://strudel.cc/#c2V0Y3BzKDEpCm4oIjwwIDEgMiAzIDQ%2BKjgiKS5zY2FsZSgnRzQgbWlub3InKQoucygiZ21fbGVhZF82X3ZvaWNlIikKLmNsaXAoc2luZS5yYW5nZSguMiwuOCkuc2xvdyg4KSkKLmp1eChyZXYpCi5yb29tKDIpCi5zb21ldGltZXMoYWRkKG5vdGUoIjEyIikpKQoubHBmKHBlcmxpbi5yYW5nZSgyMDAsMjAwMDApLnNsb3coNCkp"
49  width="600"
50  height="300"
51></iframe>
52```
53
54That 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.
55
56### @strudel/embed
57
58To simplify the process of emebdding via an iframe, you can use the package `@strudel/embed`:
59
60```html
61<script src="https://unpkg.com/@strudel/embed@latest"></script>
62<strudel-repl>
63  <!--
64setcps(1)
65n("<0 1 2 3 4>*8").scale('G4 minor')
66.s("gm_lead_6_voice")
67.clip(sine.range(.2,.8).slow(8))
68.jux(rev)
69.room(2)
70.sometimes(add(note("12")))
71.lpf(perlin.range(200,20000).slow(4))
72-->
73</strudel-repl>
74```
75
76This will load the strudel website in an iframe, using the code provided within the HTML comments `<!-- -->`.
77The HTML comments are needed to make sure the browser won't interpret it as HTML.
78
79For alternative ways to load this package, see the [@strudel/embed README](https://codeberg.org/uzu/strudel/src/branch/main/packages/embed#strudel-embed).
80
81### @strudel/repl
82
83Loading strudel directly in your site, without an iframe, looks similar to the iframe variant:
84
85```html
86<script src="https://unpkg.com/@strudel/repl@latest"></script>
87<strudel-editor>
88  <!--
89setcps(1)
90n("<0 1 2 3 4>*8").scale('G4 minor')
91.s("gm_lead_6_voice")
92.clip(sine.range(.2,.8).slow(8))
93.jux(rev)
94.room(2)
95.sometimes(add(note("12")))
96.lpf(perlin.range(200,20000).slow(4))
97-->
98</strudel-editor>
99```
100
101Here, we're loading `@strudel/repl` instead of `@strudel/embed`, and the component is called `strudel-editor` instead of `strudel-repl`.
102Yes the naming is a bit confusing..
103
104The upside of using the repl without an iframe is that you can pin the strudel version you're using:
105
106```html
107<script src="https://unpkg.com/@strudel/repl@1.0.2"></script>
108<strudel-editor>
109  <!--
110...  
111-->
112</strudel-editor>
113```
114
115This will guarantee your pattern wont break due to changes to the strudel project in the future.
116
117For more info on this package, see the [@strudel/repl README](https://codeberg.org/uzu/strudel/src/branch/main/packages/repl#strudel-repl).
118
119## With your own UI
120
121The above approach assumes you want to use the builtin [codemirror](https://codemirror.net/) editor.
122If you'd rather use your own UI, you can use the `@strudel/web` package:
123
124```html
125<!doctype html>
126<script src="https://unpkg.com/@strudel/web@1.0.3"></script>
127<button id="play">play</button>
128<button id="stop">stop</button>
129<script>
130  initStrudel();
131  document.getElementById('play').addEventListener('click', () => note('<c a f e>(3,8)').jux(rev).play());
132  document.getElementById('stop').addEventListener('click', () => hush());
133</script>
134```
135
136For more info on this package, see the [@strudel/web README](https://codeberg.org/uzu/strudel/src/branch/main/packages/web#strudel-web).
137
138## Via npm
139
140[All the packages and many more are available on npm under the @strudel namespace](https://www.npmjs.com/search?q=%40strudel).
141There are actually many more packages you can use to have fine grained control over what you use and what not.
142To use these packages, you have to use a bundler that supports es modules, like [vite](https://vitejs.dev/).
143
144To find out more about the purpose of each package, see [Packages](/technical-manual/packages)