• Download
  
  • coreCore scripts, including JSDoc documentation.
  • docsAdditional documentation on the internals.
  • prePrecomposed scripts to be included in HTML documents, minified with JSMin; available in three versions, each in English and German:
    • ekmplayer*Player only
    • ekmscore*Score only
    • ekmcomb*Both combined
• ZIP Archive
  … with all scripts and documentation.

See also the Tables with alterations and note names.

The player contains the following elements:

• Transport buttons for Playback, Stop, Pause / Resume, Hold / Resume, Previous mark, Next mark, and Repeat (loop).
• to open / close the Control Window for the audio settings.
• to open / close the Edit Window for the tone sequence.
• to show the score; see Player with Score. This is present only together with the script for the score.
• Display of the elapse time and of the total duration. The bar also shows the duration of the currently played tone.
• - / + to the right to minimize / open the player.

The HTML ekmaudio Element

To embed audio content, i.e. a player in a document, a HTML ekmaudio element must be inserted. This can be any appropriate HTML element with the class ekmaudio, e.g.:

<div class="ekmaudio" [ATTRIBUTE ...] > FALLBACK_CONTENT </div>

The content (FALLBACK_CONTENT) of each ekmaudio element in the document will be replaced with the actual player which is then initialized with the specified attributes.

Attributes

The first six attributes – seq, relative, pitch, tempo, time, supplement – form together the actual tone sequence, i.e. the value of the seq attribute is completed with preceding commands corresponding to the other five attributes.

The next four attributes – var, volume, detune, type – are respected only at the first occurrence in a document (in a player or a score).

seq="TONE_SEQUENCE"
seq="?"

The tone sequence. The default is empty.

? retrieves the tone sequence from the query part, i.e. from ?… in the URI of the document. If it consists only of a single variable this will be loaded automatically; e.g. http://my.domain/page.htm?%5cmelody (with the URI escape %5c for \) loads the variable melody.

relative="NOTE"

The octave mode. The default is the Absolute octave mode. See the relative command.

pitch="FREQUENCY"

The concert / root pitch. The default is 440 Hz. See the pitch command.

tempo="NOTEVALUE=RATE"
tempo="DURATION"

The tempo of note values. The default is "4=60". See the tempo command.

time="NUM/DENOM"

The time (meter). The default is no meter (no barlines). See the time command.

supplement="NAME …"

Supplemental data for the tones. This is a space-separated list of names.2 Each designates a set of data that will be added to each tone as properties. See the caption attribute for properties and methods of tones. NAME is one of:

• degreeData related to the respective degree:
  • partialPartial tone number.
  • propNum, propDenomNumerator and denominator of the (approximate) proportion.

  This applies to tones specified as note, proportion, or frequency in the tone sequence. For a proportion or frequency, the note data (see below) are added as well.

• noteData of the note which is nearest to the respective tone:
  • nameNote name.
  • scaleScale index 0 - 6 (usually).
  • accAccidental index 0 - 4 (12-EDO), 0 - 14 (24-EDO), 0 - 34 (72-EDO).
  • octaveOctave index 0 - 15.

  This applies to tones specified as proportion or frequency in the tone sequence. These data are added automatically if the score script is included in the document.

var="PATH"

The path component of the URI to online available variables, i.e. to a directory containing files of variables as well as the special file list.txt. This file must hold the names of the online variables (not the filenames and without a leading \) as a space-separated list.2 It is loaded automatically to fill the select list in the Edit Window.

Note that the origin of the URI (i.e. protocol, host, and port) cannot be specified, because it must be the same as that of the document; e.g. if the current URI is http://my.domain/and/page.htm the file melody.txt has the URI http://my.domain/PATH/melody.txt.

If this attribute is not present or if PATH is empty, only local files can be loaded.

volume="LEVEL"

The volume level (master gain value). The range of LEVEL determines the unit:

• 0.0 ≤ LEVEL ≤ 1.0 is the actual level (silent thru loudest).
• LEVEL > 1.0 is a percent value, i.e. 100 is equivalent to 1.0.
• LEVEL < 0.0 is a decibel (dB) value.

The default is 0.5 = 50 % = − 6.0 dB.

detune="CENTS"

The cent value of the detuning. The default is 0.

type="OSCILLATOR"

The oscillator type (waveform). OSCILLATOR is one of:

• sineSine wave (default)
• sawtoothSaw-tooth wave
• squareSquare wave
• triangleTriangle wave

loop

A boolean attribute. If present, the player will, upon reaching the end of the tone sequence, automatically seek back to the start.

autoplay

A boolean attribute. If present, the player automatically starts playing. Only the first occurrence of this attribute in a document is respected.

mini

A boolean attribute. If present, the player is minimized.

score="SCORE_ID"
score="+"

The ID of an ekmscore element that will be associated with the player. See Player with Score.

The value + creates a new score immediately after the ekmaudio element.

Example 1

This example creates a player for 72-EDO and German note names.3

It requires the following files to be included in the document:

• pre/css/ekmplayer.css
• pre/js/ekmplayer-72-en-de.js

<div class="ekmaudio"
     seq="\gain=0.8 t4 t t t c4 r r8 er4. gir,2 fisir
          r4 heser2. r8 cel dir4.~ dir4 cel2 fih4 asil,2
          \\
          \gain=0.33 \=c'
          <fisil c' asel'>1~ q <gir cel esir>
          <heser dir fih>1*19/8 <heser dir fih>2.
          \\
          \gain=0.33 \=c,
          <er hesel''>1~ q <er desir''>
          <aser eir'>1*19/8 q2."
     relative="c''"
     tempo="4=80"
     volume="30"
     type="sawtooth"
     var="var"
>
Here is an ekmelib player
</div>

Result in the browser:

The score contains the following elements:

• to open / close the Style Window for the style settings.
• to open / close the Control Window for the audio settings. They are used when playing a clicked note / chord.
• to open / close the Edit Window for the tone sequence. This is not present if the score is associated with a player.
• to show the score, i.e. to apply the current tone sequence. This is not present if the score is associated with a player.
• One staff for each voice in the tone sequence. The staves can be scrolled horizontally if they do not fit inside the ekmscore element, while the clefs (the staff prefixes) remain fixed. Automatic scrolling is performed during the playback of the associated player.
• A bar number above every fourth barline, ignoring barlines set with the bar command.
• Special diamond note heads for tones specified as proportion or frequency in the tone sequence. They are placed at the nearest degree.
• Clickable notes / chords to play them individually. A further click while playing stops it (useful in particular if the duration is set to a continuous tone in the Style Window).
• An optional caption (e.g. note name) placed below each note / chord and a corresponding label placed below the clef.

The HTML ekmscore Element

To embed score content in a document, a HTML ekmscore element must be inserted. This can be any appropriate HTML element with the class ekmscore, e.g.:

<div class="ekmscore" [ATTRIBUTE ...] > FALLBACK_CONTENT </div>

The content (FALLBACK_CONTENT) of each ekmscore element in the document will be replaced with the actual score which is then initialized with the specified attributes.

Attributes

seq="TONE_SEQUENCE"
seq="?"
relative="NOTE"
pitch="FREQUENCY"
tempo="NOTEVALUE=RATE"
tempo="DURATION"
time="NUM/DENOM"
supplement="NAME …"
var="PATH"
volume="LEVEL"
detune="CENTS"
type="OSCILLATOR"

See these attributes in the ekmaudio element. They are usually not required in a score if this is associated with a player.

ledger="LEDGER_LINES"

The maximum number of ledger lines both above and below. This enlarges the space for each staff. An ottava bracket is displayed for higher / lower note positions. The default is 1.

spacing="SPACING"

The minimum spacing between consecutive notes / chords in staff units (half the staff line distance). The actual spacing can be larger. The default is 0, i.e. a proportional spacing (a.k.a. spring).

clef="CLEF …"

The clef types. This is a space-separated list of names2 – one for each staff and the last name applies to all further staves. CLEF is one of:

• trebleTreble clef (G)
• bassBass clef (F)
• altoAlto clef (C)

The default is "treble treble alto bass".

notation="NOTATIONSTYLE"

The notation style designating the set of used accidentals. NOTATIONSTYLE is one of:

for 12-EDO:

• stdStandard notation (default)
• sagSagittal notation

for 24-EDO:

• arrowArrow notation (default)
• sagSagittal notation
• goGould notation
• stzStein / Zimmermann notation
• stcStein / Couper notation
• stvtStein / Van Blankenburg / Tartini notation
• habaHába notation
• fourDigit 4 notation
• fernFerneyhough notation

for 72-EDO:

• arrowArrow notation (default)
• rhmRichter Herf / Maedel notation
• simsSims notation
• hesseHesse notation
• sagSagittal notation
• msagMixed Sagittal notation
• wysWyschnegradsky notation
• bosBosanquet commatic notation
• habaHába notation

accidental="ACCIDENTALSTYLE"

The accidental style designating the rules of the notation of accidentals.4 ACCIDENTALSTYLE is one of:

• forgetAlways (default).
• traditional18th century style (is "default" in LilyPond!).
• modern20th century style with extra accidentals.
• modern-cautionaryDitto with extra accidentals parenthesized.
• neo-modernContemporary style with repeated extra accidentals.
• neo-modern-cautionaryDitto with extra accidentals parenthesized.
• dodecaphonicAccidental or natural sign on every note.

duration="DURATION"

The playback duration of a clicked note / chord in seconds. 0 sets a continuous tone. The default is 1.

caption="LABEL|CAPTION|…"

A caption placed below each note / chord and a corresponding label placed below the clef. This is a list with any number of label-caption items separated by a | character. Each item is displayed as preformatted text in a separate line and enlarges the space below each staff accordingly. Both LABEL and CAPTION can be empty.

CAPTION is any JavaScript code (expression or statements), that will be evaluated for each tone (or for the highest tone of a chord) and the result will be displayed. Inside of the code, the name (variable) t can be used to access the respective tone (an instance of EkmTone). If the entire code consists of letters only (a-z, A-Z, no spaces) it is treated as a tone property (e.g. name is equivalent to t.name).

Some tone properties and methods:

• nameNote name.
• fFrequency in Hz, or a flag < 0 for rest, tick, or command.
• scaleScale index 0 - 6 (usually).
• accAccidental index 0 - 4 (12-EDO), 0 - 14 (24-EDO), 0 - 34 (72-EDO).
• octaveOctave index 0 - 15.
• partialPartial tone number.
• propNum, propDenomNumerator and denominator of the (approximate) proportion.
• centExplicitely specified cent value.
• valueNote value index 0 - 6.
• dotsNumber of augmentation dots.
• voiceVoice index 0 - 15.
• durDuration in seconds.
• lagTime lag.
• tieTrue if the tone is tied to the next tone.
• degree()Degree 0 - 71 (72-EDO).
• proportion()Proportion relative to the small C.
• fullScale()Full scale index.

See docs/terms.md and the documentation of EkmTone in core/js/ekmdata.js for more details.

Example 2

This example creates a score for 72-EDO and German note names.3

It requires the following files to be included in the document:

• pre/css/ekmscore-72.css
• pre/js/ekmscore-72-en-de.js
• and the Ekmelos font, either "Ekmelos 72-EDO" or "Ekmelos", as WOFF2, WOFF, or OTF, online in a directory fonts, e.g. http://my.domain/fonts/Ekmelos72edo.woff2, or installed locally.

<div class="ekmscore"
     seq="t4 t t t c4 r r8 er4. gir,2 fisir
          \time=19/8 r4 heser2. r8 cel dir4.~ dir4 cel2
          \time=3/4 fih4 asil,2
          \\
          \=c' <fisil c' asel'>1~ q <gir cel esir>
          <heser dir fih>1*19/8 <heser dir fih>2.
          \\
          \=c, <er hesel''>1~ q <er desir''>
          <aser eir'>1*19/8 q2."
     relative="c''"
     time="4/4"
     clef="treble treble bass"
     notation="rhm"
     accidental="modern"
>
Here is an ekmelib score
</div>

Result in the browser:

A player can be associated with a score for typesetting its current tone sequence.

This is accomplished

1. either with the attribute score="SCORE_ID" in the ekmaudio element, where SCORE_ID must be the ID of an existing ekmscore element anywhere in the document;
2. or with the attribute score="+" in the ekmaudio element;
3. or with a click on in the player if this is not yet associated with a score.

B and C create a new score, i.e. a new ekmscore element immediately after the ekmaudio element and pass the following attributes from the ekmaudio element to the score:

• ledger
• spacing
• clef
• notation
• accidental
• duration
• caption

A player can have only one associated score. But a score can be associated with any number of players in the same document. It always shows the tone sequence of that associated player for which or last has been clicked.

Example 3

This example creates a player and a score which are associated through the ID "show". Here, the ekmscore element is placed after the ekmaudio element with a text in between, but it can be anywhere in the document.3

It requires the following files to be included in the document:

• pre/css/ekmcomb-72.css
• pre/js/ekmcomb-72-en-de.js
• and the Ekmelos font, either "Ekmelos 72-EDO" or "Ekmelos", as WOFF2, WOFF, or OTF, online in a directory fonts, e.g. http://my.domain/fonts/Ekmelos72edo.woff2, or installed locally.

<div class="ekmaudio"
     seq="\gain=0.8 t4 t t t c4 r r8 er4. gir,2 fisir
          \time=19/8 r4 heser2. r8 cel dir4.~ dir4 cel2
          \time=3/4 fih4 asil,2
          \\
          \gain=0.33 \=c'
          <fisil c' asel'>1~ q <gir cel esir>
          <heser dir fih>1*19/8 <heser dir fih>2.
          \\
          \gain=0.33 \=c,
          <er hesel''>1~ q <er desir''>
          <aser eir'>1*19/8 q2."
     relative="c''"
     tempo="4=80"
     time="4/4"
     volume="30"
     type="sawtooth"
     var="var"
     score="show"
>
Here is an ekmelib player
</div>
Click on a note or chord to play it:
<div class="ekmscore"
     id="show"
     clef="treble treble bass"
     notation="rhm"
     accidental="modern"
>
Here is an ekmelib score
</div>

Result in the browser:

Example 4

This example creates a player and automatically an associated score by means of the special attribute value score="+". The tone sequence is a longer version of the above examples.3

It requires the same files as in Example 3 to be included in the document:

• pre/css/ekmcomb-72.css
• pre/js/ekmcomb-72-en-de.js
• and the Ekmelos font, either "Ekmelos 72-EDO" or "Ekmelos", as WOFF2, WOFF, or OTF, online in a directory fonts, e.g. http://my.domain/fonts/Ekmelos72edo.woff2, or installed locally.

<div class="ekmaudio"
     seq="\gain=0.8 t4 t t t  c4 r r8 er4.  gir,2 fisir
          \time=19/8 r4 heser2. r8 cel dir4.~ dir4 cel2
          \time=3/4  fih4 asil,2
          \time=29/8 r4 deseh2 r4 eser2 eir8 deseh4. aser8 r
                     r4 aser8 heser4 cel2 her4
          \time=6/4  r4 eser,2 r4 desil2
                     gir4 r r2 fisir4 r8 cel'8
          \time=4/4  d4 asel'2.
          \time=6/4  r2 heser,4. cel dir8 cel
          \time=3/4  fih4 asil, heser8 cel
                     r4 eir,8 fih eir ger
          \time=6/4  r4 deseh'2 r8 eser2 eir8
                     deseh4 aser r heser r r8 cel
                     her4 eser,2 r4 desil4 r8. desil16
          \time=4/4  ces1
          \\
          \gain=0.33 \=c'
          <fisil c' asel'>1~ q <gir cel esir>
          <heser dir fih>1*19/8
          <heser dir fih>4 asil'8 fih asil fih
          <aser, deseh eir>1*29/8
          R1.
          <gir cel esir>1.
          <fisil c' asel'>1
          <heser dir fih>1*6/4
          <eir, heser' dir fih>8 <ger cil>
            <eir heser' asil'> <ger cil fih>
            <eir heser' fih'> <ger cil>
          <eir heser' asil'>4 <eir heser' fih'>2
          <aser deseh eir>1*6/4~ q~ q
          <ces, fil heser>4 fil heser2
          \\
          \gain=0.33 \=c,
          <er hesel''>1~ q <er desir''>
          <aser eir'>1*19/8
          q2.
          <eser desil''>1*29/8
          eser1.
          <er desir''>1.
          <er hesel''>1
          <aser eir'>1*6/4
          <aser dir'>2.~ q
          <eser desil''>1*6/4~ q~ q
          R1"
     relative="c''"
     tempo="4=80"
     time="4/4"
     volume="30"
     type="sawtooth"
     var="var"
     clef="treble treble bass"
     notation="rhm"
     accidental="modern"
     score="+"
>
Here is an ekmelib player with score
</div>

Result in the browser:

These windows are used to enter / select parameters for Player and/or Score. A window of a particular type is shared by all devices in the document, i.e. it can be open only for one device at the same time.

Edit Window

Window to enter tone sequences and to maintain variables. It contains the following elements:

• to load a variable from a local file. This can also be accomplished by drag and drop into the text input field. The variable will be inserted with \ into the tone sequence.
• to save the tone sequence from the text input field in a local file (for use as a variable).
• to expand all loaded variables in the tone sequence.
• A select list with all loaded and optionally all online available variables. A selected variable will be inserted with \ into the tone sequence. This list is shared by all devices in the same document.
• A select list with the error messages for the tone sequence or “-- OK --”. When selecting a message, the cursor in the text input field jumps to the position where the error occurred.
• to open the page Syntax of Tone Sequences in a separate browser window (or tab).
• to close the window.
• A text input field for the tone sequence. Changes in the text have no immediate effect. The tone sequence will be applied not until or is clicked. If it has errors the edit window is opened for the concerning device, with the error messages in the select list.

Control Window

Window for the audio settings. These are shared by all devices in the document.

• Volume (master gain value): The display of the volume level is likewise a button to toggle between percent (%) and decibel (dB).
• Detuning: The display of the cent value is likewise a button to reset the detuning to zero.
• Oscillator type (waveform): sine sawtooth square triangle

Style Window

Window for the style settings of a score. These apply to all staves, except for the clef type.

• Clef type: See the clef attribute in the ekmscore element. For two or more staves, i.e. for a tone sequence with two or more voices, a button is shown next to the select list to toggle the staff for which to select the clef.
• Notation style: See the notation attribute in the ekmscore element.
• Accidental style:4 See the accidental attribute in the ekmscore element.
• Playback duration of a clicked note / chord: 1 thru 4 seconds or continuous tone. See the duration attribute in the ekmscore element.

Copyright © 2016-2023 Thomas Richter

Ekmelib is licensed under the GNU General Public License, version 3 or later.
See the file LICENSE.txt. This license is also available at www.gnu.org/licenses.