Merge pull request #244 from tidalcycles/readme-tlc

Readme + TLC

.github/workflows/test.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [16, 17]
+        node-version: [18]
 
     steps:
     - uses: actions/checkout@v2

package-lock.json

@@ -3314,9 +3314,9 @@
       }
     },
     "node_modules/caniuse-lite": {
-      "version": "1.0.30001341",
+      "version": "1.0.30001430",
-      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001341.tgz",
+      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001430.tgz",
-      "integrity": "sha512-2SodVrFFtvGENGCv0ChVJIDQ0KPaS1cg7/qtfMaICgeMolDdo/Z2OD32F0Aq9yl6F4YFwGPBS5AaPqNYiW4PoA==",
+      "integrity": "sha512-IB1BXTZKPDVPM7cnV4iaKaHxckvdr/3xtctB3f7Hmenx3qYBhGtTZ//7EllK66aKXW98Lx0+7Yr0kxBtIt3tzg==",
       "funding": [
         {
           "type": "opencollective",
@@ -15537,9 +15537,9 @@
       }
     },
     "caniuse-lite": {
-      "version": "1.0.30001341",
+      "version": "1.0.30001430",
-      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001341.tgz",
+      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001430.tgz",
-      "integrity": "sha512-2SodVrFFtvGENGCv0ChVJIDQ0KPaS1cg7/qtfMaICgeMolDdo/Z2OD32F0Aq9yl6F4YFwGPBS5AaPqNYiW4PoA=="
+      "integrity": "sha512-IB1BXTZKPDVPM7cnV4iaKaHxckvdr/3xtctB3f7Hmenx3qYBhGtTZ//7EllK66aKXW98Lx0+7Yr0kxBtIt3tzg=="
     },
     "caseless": {
       "version": "0.12.0",

packages/core/controls.mjs

@@ -97,7 +97,7 @@ const generic_params = [
   ],
 
   /**
-   * Select the sound bank to use. To be used together with `s`. The bank name (+ "_") will be prepended to the value of `s`. 
+   * Select the sound bank to use. To be used together with `s`. The bank name (+ "_") will be prepended to the value of `s`.
    *
    * @name bank
    * @param {string | Pattern} bank the name of the bank
@@ -105,11 +105,7 @@ const generic_params = [
    * s("bd sd").bank('RolandTR909') // = s("RolandTR909_bd RolandTR909_sd")
    *
    */
-  [
+  ['f', 'bank', 'selects sound bank to use'],
-    'f',
-    'bank',
-    'selects sound bank to use',
-  ],
 
   // TODO: find out how this works?
   /*

packages/core/index.mjs

@@ -4,10 +4,10 @@ Copyright (C) 2022 Strudel contributors - see <https://github.com/tidalcycles/st
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-export * from './controls.mjs';
+import controls from './controls.mjs';
 export * from './euclid.mjs';
 import Fraction from './fraction.mjs';
-export { Fraction };
+export { Fraction, controls };
 export * from './hap.mjs';
 export * from './pattern.mjs';
 export * from './signal.mjs';

packages/embed/README.md

@@ -10,15 +10,22 @@ Either install with `npm i @strudel.cycles/embed` or just use a cdn to import th
 <script src="https://unpkg.com/@strudel.cycles/embed@latest"></script>
 <strudel-repl>
   <!--
-      "a4 [a3 c3] a3 c3".color('#F9D649')
+note(`[[e5 [b4 c5] d5 [c5 b4]]
-    .sub("<7 12 5 12>".slow(2))
+[a4 [a4 c5] e5 [d5 c5]]
-    .off(1/4,x=>x.add(7).color("#FFFFFF #0C3AA1 #C63928"))
+[b4 [~ c5] d5 e5]
-    .off(1/8,x=>x.add(12).color('#215CB6'))
+[c5 a4 a4 ~]
-    .slow(2)
+[[~ d5] [~ f5] a5 [g5 f5]]
-    .legato(sine.range(0.3, 2).slow(28))
+[e5 [~ c5] e5 [d5 c5]]
-    .wave("sawtooth square".fast(2))
+[b4 [b4 c5] d5 e5]
-    .filter('lowpass', cosine.range(500,4000).slow(16))
+[c5 a4 a4 ~]],
-    .pianoroll({minMidi:20,maxMidi:120,background:'#202124'})
+[[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>
 ```

packages/embed/example.html

@@ -2,14 +2,21 @@
 <!-- <script src="./embed.js"></script> -->
 <strudel-repl>
   <!--
-      "a4 [a3 c3] a3 c3".color('#F9D649')
+note(`[[e5 [b4 c5] d5 [c5 b4]]
-    .sub("<7 12 5 12>".slow(2))
+[a4 [a4 c5] e5 [d5 c5]]
-    .off(1/4,x=>x.add(7).color("#FFFFFF #0C3AA1 #C63928"))
+[b4 [~ c5] d5 e5]
-    .off(1/8,x=>x.add(12).color('#215CB6'))
+[c5 a4 a4 ~]
-    .slow(2)
+[[~ d5] [~ f5] a5 [g5 f5]]
-    .legato(sine.range(0.3, 2).slow(28))
+[e5 [~ c5] e5 [d5 c5]]
-    .wave("sawtooth square".fast(2))
+[b4 [b4 c5] d5 e5]
-    .filter('lowpass', cosine.range(500,4000).slow(16))
+[c5 a4 a4 ~]],
-    .pianoroll({minMidi:20,maxMidi:120,background:'#202124'})
+[[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>

packages/mini/README.md

@@ -33,3 +33,12 @@ yields:
 ## Mini Notation API
 
 See "Mini Notation" in the [Strudel Tutorial](https://strudel.tidalcycles.org/tutorial/)
+
+## Building the Parser
+
+The parser [krill-parser.js] is generated from [krill.pegjs](./krill.pegjs) using [peggy](https://peggyjs.org/).
+To generate the parser, run
+
+```js
+npm run build:parser
+```

packages/mini/mini.mjs

@@ -6,7 +6,7 @@ This program is free software: you can redistribute it and/or modify it under th
 
 import * as krill from './krill-parser.js';
 import * as strudel from '@strudel.cycles/core';
-import { addMiniLocations } from '@strudel.cycles/eval/shapeshifter.mjs';
+// import { addMiniLocations } from '@strudel.cycles/eval/shapeshifter.mjs';
 
 const { pure, Pattern, Fraction, stack, slowcat, sequence, timeCat, silence, reify } = strudel;
 
@@ -29,7 +29,10 @@ const applyOptions = (parent) => (pat, i) => {
       case 'bjorklund':
         return pat.euclid(operator.arguments_.pulse, operator.arguments_.step, operator.arguments_.rotation);
       case 'degradeBy':
-        return reify(pat)._degradeByWith(strudel.rand.early(randOffset * _nextSeed()).segment(1), operator.arguments_.amount);
+        return reify(pat)._degradeByWith(
+          strudel.rand.early(randOffset * _nextSeed()).segment(1),
+          operator.arguments_.amount,
+        );
       // TODO: case 'fixed-step': "%"
     }
     console.warn(`operator "${operator.type_}" not implemented`);
@@ -112,9 +115,9 @@ export function patternifyAST(ast) {
         return silence;
       }
       if (typeof ast.source_ !== 'object') {
-        if (!addMiniLocations) {
+        /* if (!addMiniLocations) {
           return ast.source_;
-        }
+        } */
         if (!ast.location_) {
           console.warn('no location for', ast);
           return ast.source_;

packages/osc/README.md

@@ -35,3 +35,5 @@ s("<bd sd> hh").osc()
 ```
 
 or just [click here](http://localhost:3000/#cygiPGJkIHNkPiBoaCIpLm9zYygp)...
+
+You can read more about [how to use Superdirt with Strudel the Tutorial](https://strudel.tidalcycles.org/tutorial/#superdirt-api)

packages/react/README.md

@@ -1,4 +1,44 @@
 # @strudel.cycles/react
 
-This package contains react hooks and components for strudel.
+This package contains react hooks and components for strudel. It is used internally by the Strudel REPL.
-Example coming soon
+
+## Install
+
+```js
+npm i @strudel.cycles/react
+```
+
+## Usage
+
+Here is a minimal example of how to set up a MiniRepl:
+
+```jsx
+import { evalScope } from '@strudel.cycles/eval';
+import { MiniRepl } from '@strudel.cycles/react';
+import controls from '@strudel.cycles/core/controls.mjs';
+import { prebake } from '../repl/src/prebake.mjs';
+
+evalScope(
+  controls,
+  import('@strudel.cycles/core'),
+  import('@strudel.cycles/tonal'),
+  import('@strudel.cycles/mini'),
+  import('@strudel.cycles/webaudio'),
+  /* probably import other strudel packages */
+);
+
+prebake();
+
+export function Repl({ tune }) {
+  return <MiniRepl tune={tune} hideOutsideView={true} />;
+}
+```
+
+## Development
+
+If you change something in here and want to see the changes in the repl, make sure to run `npm run build` inside this folder!
+
+```js
+npm run dev # dev server
+npm run build # build package
+```

packages/react/src/App.jsx

@@ -16,7 +16,7 @@ evalScope(
 function App() {
   return (
     <div>
-      <MiniRepl tune={`"c3"`} />
+      <MiniRepl tune={`note("c3")`} />
     </div>
   );
 }

repl/src/App.jsx

@@ -4,7 +4,6 @@ Copyright (C) 2022 Strudel contributors - see <https://github.com/tidalcycles/st
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import controls from '@strudel.cycles/core/controls.mjs';
 import { evalScope, evaluate } from '@strudel.cycles/eval';
 import { CodeMirror, cx, flash, useHighlighting, useRepl, useWebMidi } from '@strudel.cycles/react';
 import { cleanupDraw, cleanupUi, Tone } from '@strudel.cycles/tone';
@@ -15,6 +14,7 @@ import * as tunes from './tunes.mjs';
 import { prebake } from './prebake.mjs';
 import * as WebDirt from 'WebDirt';
 import { resetLoadedSamples, getAudioContext } from '@strudel.cycles/webaudio';
+import { controls } from '@strudel.cycles/core';
 import { createClient } from '@supabase/supabase-js';
 import { nanoid } from 'nanoid';
 
@@ -26,7 +26,7 @@ const supabase = createClient(
 
 evalScope(
   Tone,
-  controls,
+  controls, // sadly, this cannot be exported from core direclty
   { WebDirt },
   import('@strudel.cycles/core'),
   import('@strudel.cycles/tone'),