Merge pull request #261 from cuthbertLab/articulations-loader-docs

Improve loader docs and articulations
cuthbertLab · Aug 21, 2024 · 2fe35ff · 2fe35ff
2 parents e616efb + 3d54c4a
commit 2fe35ff
Show file tree

Hide file tree

Showing 7 changed files with 155 additions and 136 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,4 @@
-Music21j
-=========
+# Music21j
 
 **Music21j: An Interactive Framework for Musical Analysis**
 
@@ -26,8 +25,7 @@ targets browsers no more than 30 months old.
 Safari is the only major desktop browser for which there is no out of the box 
 support for MIDI devices.
 
-Documentation
--------------
+## Documentation
 This README appears in both the GitHub home page and the documentation
 home page; to make the following links work, go to the documentation
 page at http://web.mit.edu/music21/music21j/doc/ .
@@ -39,15 +37,13 @@ or a Class such as {@link music21.note.Note} or {@link music21.stream.Stream}.
 
 (Ignore "Modules" they're not useful and duplicate the namespace pages).
 
-Example
---------
+## Example
 Install by downloading a copy of the music21 code to your own webserver.
 
 ```sh
 % npm install music21j
 ```
 
-
 If this line (`npm install`) doesn't work, download the
 latest version of `node.js` from https://nodejs.org/en/download/
 
@@ -98,19 +94,49 @@ const n = new music21.note.Note('F#');
 // etc.
 ```
 
-Version
---------
+### Embedding, etc.
+Music21j was originally intended for self-hosting, so embedding is not
+yet as simple as it should be.
+
+To load soundfonts from other locations (like in a CDN), 
+(1) set a global `m21conf` variable to disable loading soundfonts,
+(2) load the music21j script, and (3) set the new soundfont location,
+and (4) load the soundfont.
+
+This fragment shows how to do it.  A working implementation is in the
+testHTML directory as `sfElsewhereCDN.html`.
+
+```html
+<body>
+<script>
+    window.m21conf = { loadSoundfont: false };
+</script>
+<script 
+    src="https://cdn.jsdelivr.net/npm/music21j/releases/music21.debug.min.js"
+></script>
+<script>
+    music21.common.urls.soundfontUrl = 'https://raw.githubusercontent.com/gleitz/midi-js-soundfonts/gh-pages/FluidR3_GM/';
+    music21.miditools.loadSoundfont('clarinet', i => {
+       const tn = music21.tinyNotation.TinyNotation('4/4 c4 d e f g1');
+       tn.instrument = i;
+       tn.playStream();
+    });
+</script>
+</body>
+```
+
+
+
+## Version
 0.16 beta
 
 
-License
---------
+## License
 Music21j is released under the BSD 3-Clause License. Essentially you
 can do with it what you want so long as you leave in my copyright statements
 and do not represent that I endorse your product.
 
-Thanks
------------
+## Thanks
 
 Thanks to the following packages (among others) for making music21j possible:
 
@@ -135,8 +161,7 @@ and supported by the Music and Theater Arts section of [MIT].
 [jsdoc]:http://usejsdoc.org
 
 
-Dev Notes
-----------------
+## Dev Notes
 Build and watch with
 
 ```sh
@@ -166,8 +191,7 @@ for running tests one time without watch, you can use:
 $ grunt test_no_watch
 ```
 
-Publishing a new version
--------------------------
+### Publishing a new version
 You'll need to be part of the npm dev team.
 
 Two steps.  First make sure you have run:
@@ -214,6 +238,4 @@ $ npm install
 ```
 
 
-These docs will be changing in preparation for v. 1.0 release.
-
-
+These docs may change someday in preparation for v.1.0 release.
diff --git a/src/articulations.ts b/src/articulations.ts
@@ -77,14 +77,18 @@ export class Articulation extends prebase.ProtoM21Object {
 
     name: string;
     placement: ArticulationPlacement = ArticulationPlacement.NOTE_SIDE;
-    vexflowModifier: string;
+    vexflowModifier: string = '';
     dynamicScale: number = 1.0;
     lengthScale: number = 1.0;
 
     /**
-     * Generates a Vex.Flow.Articulation for this articulation.
+     * Generates a Vex.Flow.Articulation for this articulation if it is something
+     * vexflow can display.
      */
-    vexflow({stemDirection}: VexflowArticulationParams = {}): VFArticulation {
+    vexflow({stemDirection}: VexflowArticulationParams = {}): VFArticulation|null {
+        if (!this.vexflowModifier) {
+            return null;
+        }
         const vfa = new VFArticulation(this.vexflowModifier);
         setPlacementOnVexFlowArticulation(vfa, this.placement, stemDirection);
         return vfa;
@@ -97,10 +101,7 @@ export class Articulation extends prebase.ProtoM21Object {
 export class LengthArticulation extends Articulation {
     static get className() { return 'music21.articulation.LengthArticulation'; }
 
-    constructor() {
-        super();
-        this.name = 'length-articulation';
-    }
+    override name = 'length-articulation';
 }
 
 /**
@@ -109,10 +110,7 @@ export class LengthArticulation extends Articulation {
 export class DynamicArticulation extends Articulation {
     static get className() { return 'music21.articulation.DynamicArticulation'; }
 
-    constructor() {
-        super();
-        this.name = 'dynamic-articulation';
-    }
+    override name ='dynamic-articulation';
 }
 
 /**
@@ -121,10 +119,7 @@ export class DynamicArticulation extends Articulation {
 export class PitchArticulation extends Articulation {
     static get className() { return 'music21.articulation.PitchArticulation'; }
 
-    constructor() {
-        super();
-        this.name = 'pitch-articulation';
-    }
+    override name = 'pitch-articulation';
 }
 
 /**
@@ -133,10 +128,7 @@ export class PitchArticulation extends Articulation {
 export class TimbreArticulation extends Articulation {
     static get className() { return 'music21.articulation.TimbreArticulation'; }
 
-    constructor() {
-        super();
-        this.name = 'timbre-articulation';
-    }
+    override name = 'timbre-articulation';
 }
 
 /**
@@ -145,12 +137,9 @@ export class TimbreArticulation extends Articulation {
 export class Accent extends DynamicArticulation {
     static get className() { return 'music21.articulation.Accent'; }
 
-    constructor() {
-        super();
-        this.name = 'accent';
-        this.vexflowModifier = 'a>';
-        this.dynamicScale = 1.5;
-    }
+    override name = 'accent';
+    override vexflowModifier = 'a>';
+    override dynamicScale = 1.5;
 }
 
 /**
@@ -159,51 +148,35 @@ export class Accent extends DynamicArticulation {
 export class StrongAccent extends Accent {
     static get className() { return 'music21.articulation.StrongAccent'; }
 
-    constructor() {
-        super();
-        this.name = 'strong accent';
-        this.vexflowModifier = 'a^';
-        this.dynamicScale = 2.0;
-    }
+    override name = 'strong accent';
+    override vexflowModifier = 'a^';
+    override dynamicScale = 2.0;
 }
 
-/**
- * no playback for now.
- */
 export class Staccato extends LengthArticulation {
     static get className() { return 'music21.articulation.Staccato'; }
 
-    constructor() {
-        super();
-        this.name = 'staccato';
-        this.vexflowModifier = 'a.';
-    }
+    override name = 'staccato';
+    override vexflowModifier = 'a.';
+    override lengthScale = 0.6;
 }
 
-/**
- * no playback for now.
- */
 export class Staccatissimo extends Staccato {
     static get className() { return 'music21.articulation.Staccatissimo'; }
 
-    constructor() {
-        super();
-        this.name = 'staccatissimo';
-        this.vexflowModifier = 'av';
-    }
+    override name = 'staccatissimo';
+    override vexflowModifier = 'av';
+    override lengthScale = 0.3;
 }
 
 /**
- * no playback or display for now.
+ * no difference in playback from staccato.  no display.
  */
 export class Spiccato extends Staccato {
     static get className() { return 'music21.articulation.Spiccato'; }
 
-    constructor() {
-        super();
-        this.name = 'spiccato';
-        this.vexflowModifier = undefined;
-    }
+    override name = 'spiccato';
+    override vexflowModifier = '';
 }
 
 /**
@@ -225,9 +198,6 @@ export class Marcato extends DynamicArticulation {
 export class Tenuto extends LengthArticulation {
     static get className() { return 'music21.articulation.Tenuto'; }
 
-    constructor() {
-        super();
-        this.name = 'tenuto';
-        this.vexflowModifier = 'a-';
-    }
+    override name = 'tenuto';
+    override vexflowModifier = 'a-';
 }
diff --git a/src/expressions.ts b/src/expressions.ts
@@ -30,7 +30,10 @@ export class Expression extends base.Music21Object {
      *
      * (this is not right for all cases)
      */
-    vexflow({stemDirection}: VexflowArticulationParams = {}): VFArticulation | VFOrnament {
+    vexflow({stemDirection}: VexflowArticulationParams = {}): VFArticulation | VFOrnament | null {
+        if (!this.vexflowModifier) {
+            return null;
+        }
         const vfe = new VFArticulation(this.vexflowModifier);
         setPlacementOnVexFlowArticulation(vfe, this.placement, stemDirection);
         return vfe;
@@ -56,7 +59,10 @@ export class Ornament extends Expression {
     static get className() { return 'music21.expressions.Ornament'; }
 
     name: string = 'ornament';
-    vexflow({stemDirection}: VexflowArticulationParams = {}): VFOrnament {
+    vexflow({stemDirection}: VexflowArticulationParams = {}): VFOrnament | null {
+        if (!this.vexflowModifier) {
+            return null;
+        }
         const vfe = new VFOrnament(this.vexflowModifier);
         setPlacementOnVexFlowArticulation(vfe, this.placement, stemDirection);
         return vfe;