Merge pull request 'Docs: add xen package examples' (#1446) from dudymas/strudel:docs/xen/added-tune into main

Reviewed-on: https://codeberg.org/uzu/strudel/pulls/1446

Dockerfile

@@ -0,0 +1,21 @@
+FROM node:24
+
+WORKDIR /app
+
+RUN npm install pnpm --global
+
+COPY pnpm-workspace.yaml ./
+COPY package.json pnpm-lock.yaml ./
+COPY packages/ ./packages/
+COPY examples/ ./examples/
+RUN mkdir -p website/public
+COPY website/package.json ./website/
+
+RUN pnpm install
+
+
+COPY . .
+
+EXPOSE 4321
+
+CMD ["pnpm", "dev"]

packages/xen/tunejs.js

@@ -139,10 +139,10 @@ Tune.prototype.MIDI = function(stepIn,octaveIn) {
 
 /* Load a new scale */
 
-Tune.prototype.loadScale = function(name){
+Tune.prototype.loadScale = function(scale){
 
 	/* load the scale */
-	var freqs = TuningList[name].frequencies
+	var freqs = isArrayOfNumbers(scale) ? scale : TuningList[scale].frequencies
 	this.scale = []
 	for (var i=0;i<freqs.length-1;i++) {
 		this.scale.push(freqs[i]/freqs[0])
@@ -207,8 +207,13 @@ Tune.prototype.search = function(letters) {
 	return possible
 }
 
-Tune.prototype.isValidScale = function(name) {
+function isArrayOfNumbers(arg) {
-  return !!TuningList[name];
+    return Array.isArray(arg) && arg.length > 0 && arg.every(item => typeof item === 'number' && !isNaN(item));
+}
+
+/* allow an array of values too */
+Tune.prototype.isValidScale = function(scale) {
+  return !!TuningList[scale] || isArrayOfNumbers(scale) ;
 }
 
 /* Return a collection of notes as an array */

website/src/config.ts

@@ -103,6 +103,7 @@ export const SIDEBAR: Sidebar = {
     Understand: [
       { text: 'Coding syntax', link: 'learn/code' },
       { text: 'Pitch', link: 'understand/pitch' },
+      { text: 'Xen Harmonic Functions', link: 'learn/xen' },
       { text: 'Cycles', link: 'understand/cycles' },
       { text: 'Voicings', link: 'understand/voicings' },
       { text: 'Pattern Alignment', link: 'technical-manual/alignment' },

website/src/pages/learn/xen.mdx

@@ -0,0 +1,100 @@
+---
+title: Xen Harmonic Functions
+layout: ../../layouts/MainLayout.astro
+---
+
+import { MiniRepl } from '../../docs/MiniRepl';
+import { JsDoc } from '../../docs/JsDoc';
+
+# Xen Harmonic Functions
+
+These functions allow the use of scales other than your typical chromatic 12 based ones.
+
+### tune(scale)
+
+<JsDoc client:idle name="tune" h={0} />
+
+Here's an example of how to configure a basic hexany scale:
+
+<MiniRepl
+  client:idle
+  tune={`"0 1 2 3 4 5".tune("hexany15").mul("220").freq()`}
+/>
+
+Try other scales like `hexany1`, `iraq`, `gumbeng`, `gunkali`, or `tranh3`
+
+For a full list of available scales from tunejs, see http://abbernie.github.io/tune/scales.html
+
+You can set your root to be a particular note with `getFreq`
+
+<MiniRepl
+  client:idle
+  tune={`"4 8 9 10 - - 5 7 9 11 - -".tune("tranh3")
+    .mul(getFreq('c3'))
+    .freq().clip(.5).room(1)`}
+/>
+
+Some tunings become more pronounced with a longer reverb decay:
+
+<MiniRepl
+  client:idle
+  tune={`"<[5 6 8 10] - [5 7 9 12] -> -".tune("gumbeng")
+  .mul(getFreq('c3'))
+  .freq().clip(.8).room("3:10").rdim(10000).rfade(5)`}
+/>
+
+Additionally, you can combo this with `fmap` so that the base note changes:
+
+<MiniRepl
+  client:idle
+  tune={`"9 11 12 10 - - -".tune("gunkali")
+  .mul("<c3 c3 a3 d#3>".fmap(getFreq))
+  .freq().legato("2 .7").room("1:15").rdim(8500).rlp(14000).rfade(8)`}
+/>
+
+Combining this with various polyrhythm tricks can become very evocative:
+
+<MiniRepl
+  client:idle
+  tune={`"<[0 3 1 -] [-1 4 2 8]> ~ ~,<-4 -5>"
+  .transpose(4)
+  .tune("iraq")
+  .mul("<c3 d3 c#3>".fmap(getFreq))
+  .freq().clip(.5).room(1).rfade(9)`}
+/>
+
+Another helpful trick when exploring new tunings is to strum them.
+Many have a much more enchanting sound that was chosen over many generations of musicians for being strummed.
+
+Take the `sanza` tuning:
+<MiniRepl
+  client:idle
+  tune={`"4 5 6 7 8 9".tune("sanza")
+  .mul(getFreq('c3'))
+  .freq()`}
+/>
+
+Notes 7 and 9 will clash quite a bit if you arp them normally. Many tunings will have this sort of sound, and it can feel distracting on its own.
+See how close they are on the pitch wheel?
+
+<MiniRepl
+  client:idle
+  tune={`"[7 9]!3".tune("sanza").mul(getFreq('c3')).freq()._pitchwheel()`}
+/>
+
+This quality is often due to how the tunings were formed with instruments that were played differently than a piano.
+As such, some tunings are much better strummed, with the subtle clash of the detuned notes actually making the sound much more magical:
+
+<MiniRepl
+  client:idle
+  tune={`"[0 1 2 3 4 5 6]@0.3 -"
+  .transpose("<2 5 8 1>")
+  .tune("sanza")
+  .mul(getFreq('c3')).freq()
+  .legato("3").room(1).rfade(5)`}
+/>
+
+Note the legato and reverb effects make sure the sound of the strumming gets to wash together. Alternating the direction of the strum can make the
+tones sound even more alive, too.
+
+The `tranh3` tuning has a similar set of notes, with two clashing. You might trying plugging that in above and see if you find a favorite strumming pattern.