Merge pull request 'improve xen documentation' (#1946) from tyow/localstrudel:xen-docs into main

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

packages/xen/tune.mjs

@@ -7,12 +7,42 @@ This program is free software: you can redistribute it and/or modify it under th
 import Tune from './tunejs.js';
 import { register } from '@strudel/core';
 
+/**
+ * Assumes a numerical pattern of EDO steps. Accepts a scale name or list of frequencies (see all available names at the link on the reference). Returns a new pattern with all values mapped to a frequency ratio. Similar to `xen`.
+ * @name tune
+ * @returns Pattern
+ * @memberof Pattern
+ * @param {(string | number[] )} scale
+ * @example
+ * "0 1 2 3 4 5".tune("hexany15").mul("220").freq()
+ * @example
+ * // You can set your root to be a
+ * // particular note with getFreq:
+ * "4 8 9 10 - - 5 7 9 11 - -".tune("tranh3")
+ *   .mul(getFreq('c3'))
+ *   .freq().clip(.5).room(1)
+ * @example
+ * // You can also give tune a list of
+ * // frequencies to use as the scale:
+ * "0 1 2 3 4".tune([
+ *   261.6255653006,
+ *   302.72962012827,
+ *   350.29154279212,
+ *   405.32593044476,
+ *   469.00678383895,
+ *   523.2511306012
+ * ]).mul(220).freq();
+ * @tags tonal
+ */
+
+// Tune.scale seems to be in ratio format
 export const tune = register('tune', (scale, pat) => {
   const tune = new Tune();
   if (!tune.isValidScale(scale)) {
     throw new Error('not a valid tune.js scale name: "' + scale + '". See http://abbernie.github.io/tune/scales.html');
   }
   tune.loadScale(scale);
+  // if the tonic is a frequency, why are we putting in "1"
   tune.tonicize(1);
   return pat.withHap((hap) => {
     return hap.withValue(() => tune.note(hap.value));

packages/xen/tunejs.js

@@ -78,14 +78,21 @@ Tune.prototype.frequency = function(stepIn, octaveIn) {
 	}
 	
 	// which scale degree (0 - scale length) is our input
+	// 60 % 12 = 0
 	var scaleDegree = stepIn % this.scale.length
 
+	// what's this doing
+	// 0 scaleDegree = 12
+	// seems to simply be for a negative result from above, maybe another way to do it, but ok for now
 	while (scaleDegree < 0) {
 		scaleDegree += this.scale.length
 	}
 	
+	// tonic is currently always 1
+	// so this is 1*scale[scaledegree]
 	var freq = this.tonic*this.scale[scaleDegree]
 	
+	// map it to octave
 	freq = freq*(Math.pow(2,octave))
 	
 	// truncate irrational numbers
@@ -137,10 +144,13 @@ Tune.prototype.MIDI = function(stepIn,octaveIn) {
 }
 
 /* Load a new scale */
+// sets .scale to ratios
 
 Tune.prototype.loadScale = function(scale){
 
 	/* load the scale */
+	let name
+	if (typeof scale === 'string') name = scale;
 	var freqs = isArrayOfNumbers(scale) ? scale : TuningList[scale].frequencies
 	this.scale = []
 	for (var i=0;i<freqs.length-1;i++) {
@@ -148,10 +158,10 @@ Tune.prototype.loadScale = function(scale){
 	}
 
 	/* visualize in console */
-/* 	console.log(" ");
-	console.log("LOADED "+name);
-	console.log(TuningList[name].description);
-	console.log(this.scale); */
+	// console.log(" ");
+	// console.log("LOADED "+name);
+	// console.log(TuningList[name].description);
+	// console.log(this.scale);
 	var vis = [];
 	for (var i=0;i<100;i++) {
 		vis[i] = " ";

packages/xen/xen.mjs

@@ -5,7 +5,9 @@ This program is free software: you can redistribute it and/or modify it under th
 */
 
 import { register, _mod, parseNumeral } from '@strudel/core';
+import Tune from './tunejs.js';
 
+// returns a list of frequency ratios for given edo scale
 export function edo(name) {
   if (!/^[1-9]+[0-9]*edo$/.test(name)) {
     throw new Error('not an edo scale: "' + name + '"');
@@ -18,18 +20,26 @@ const presets = {
   '12ji': [1 / 1, 16 / 15, 9 / 8, 6 / 5, 5 / 4, 4 / 3, 45 / 32, 3 / 2, 8 / 5, 5 / 3, 16 / 9, 15 / 8],
 };
 
+// Given a base frequency such as 220 and an edo scale, returns
+// an array of frequencies representing the given edo scale in that base
 function withBase(freq, scale) {
   return scale.map((r) => r * freq);
 }
 
 const defaultBase = 220;
 
+// Assumes a base of 220. Returns a filtered scale based on 'indices'
+// NOTE: indices functionality is unused
 function getXenScale(scale, indices) {
+  let tune = new Tune();
   if (typeof scale === 'string') {
     if (/^[1-9]+[0-9]*edo$/.test(scale)) {
       scale = edo(scale);
     } else if (presets[scale]) {
       scale = presets[scale];
+    } else if (tune.isValidScale(scale)) {
+      tune.loadScale(scale);
+      scale = tune.scale;
     } else {
       throw new Error('unknown scale name: "' + scale + '"');
     }
@@ -47,15 +57,53 @@ function xenOffset(xenScale, offset, index = 0) {
   return xenScale[i] * Math.pow(2, oct);
 }
 
+// accepts a scale name such as 31edo, and a pattern
+// pattern expected to follow format such that a value can be mapped
+// to an edostep within the scale. Returns the pattern with
+// values mapped to the frequencies associated with the given edosteps
 // scaleNameOrRatios: string || number[], steps?: number
+
+/**
+ * Assumes a numerical pattern of scale steps, and a scale. Scales accepted are all preset scale names of `tune`, arbitrary edos such as 31edo, or an array of frequency ratios. Assumes scales repeat at octave (2/1). Returns a new pattern with all values mapped to their associated frequency, assuming a base frequency of 220hz.
+ *
+ * @name xen
+ * @returns Pattern
+ * @memberof Pattern
+ * @param {(string | number[] )} scaleNameOrRatios
+ * @tags tonal
+ * @example
+ * // A major triad in 31edo:
+ * "0 8 18".xen("31edo").freq().piano()
+ * @example
+ * // You can also use xen with frequency ratios.
+ * // This is equivalent to the above:
+ * "0 1 2".xen([
+ *   Math.pow(2, 0/31),
+ *   Math.pow(2, 8/31),
+ *   Math.pow(2, 18/31),
+ * ]).freq().piano()
+ * @example
+ * // xen also supports all scale names that
+ * // tune does:
+ * "0 1 2 3 4 5".xen("hexany15").freq()
+ * // equiv to:
+ * // "0 1 2 3 4 5".tune("hexany15").mul("220").freq()
+ */
+
+// TODO feat: change root frequency
+// TODO add explanation for what "31edo" etc. are
+// TODO (maybe): should this return freq ratios like tune does, for parity's sake?
 export const xen = register('xen', function (scaleNameOrRatios, pat) {
   return pat.withHap((hap) => {
     const scale = getXenScale(scaleNameOrRatios);
-    const frequency = xenOffset(scale, parseNumeral(hap.value));
+    let frequency = xenOffset(scale, parseNumeral(hap.value));
+    // 10 is somewhat arbitrary
+    frequency = parseFloat(frequency.toPrecision(10));
     return hap.withValue(() => frequency);
   });
 });
 
+// not sure there's a point to having this and the above, seems like a proto version of the above.
 export const tuning = register('tuning', function (ratios, pat) {
   return pat.withHap((hap) => {
     const frequency = xenOffset(ratios, parseNumeral(hap.value));