ekmelib

Download ekmelib

Ekmelib is a collection of scripts (JavaScript and CSS files) that support the embedding of simple audio and score content in HTML documents (Web pages) – intended primarily for microtonal audio samples, scales, intonation exercises etc., in particular, for the 72-tone equal-temperament (72-ET, ekmelic) system.
The scripts can be combined in any desired configuration and extended with other scripts to build a JavaScript playback or typesetting engine that works in modern browsers without the need of special plugins, audio files, streaming audio, or graphic files.
It is in development.

It also provides precomposed scripts for an easy use in documents, as described further below. These scripts can be found in the pack directory of the ekmelib package. Note that they are minified with JSMin for faster download.

The Ekmelic Player is now part of the ekmelib project.
See also the pages Audio samples of Tone sequences, Tunings of some Works, Introduction, and Ekmelic Series which make use of these ekmelib scripts for playback and typesetting.

Please, enable JavaScript in your browser to use the ekmelib scripts in the examples.

Introduction

A tone sequence is given in plain text form, e.g. it is entered in a text editing control or specified with the seq attribute of an HTML "ekmaudio" element or "ekmusic" element (see below). It consists of single tones and chords, each assigned to a particular voice. Two or more simultaneous tones must be either part of the same chord (i.e. they have the same duration / note value) or assigned to different voices. The sequence may have any length. The number of voices is limited to 16.

The syntax is the same, both for the player and the score. It is adopted from LilyPonde.g. note names, relative octave mode, reciprocal note values, scaling, ties – and extended with elements to specify proportions, cent values, absolute frequencies and durations etc. However, the score has many limitations, i.e. only the first voice is displayed and extended elements (proportions etc.) are ignored.

See the Ekmelic Player Help for a detailed description of the syntax.

Player

To embed an audio player in a document, a HTML "ekmaudio" element, i.e. an element with the class name ekmaudio must be inserted; e.g.:

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

The content (fallback content) of each "ekmaudio" element will be replaced with the player user interface using the following attributes in the element to initialize the controls and the layout of the player:

seq="TONE_SEQUENCE"
The textual tone sequence in the "Tone sequence" field. The sequence can also be provided by the query part of the window location (i.e. ?... in the URL of the document). Default is an empty field.
relative="NOTENAME[ACCENTS]"
The octave mode in the "Relative to" field. A note name with optional octave accents (' or ,) sets the Relative Octave Mode and specifies the reference point for the octave of the first note. An empty string sets the Absolute Octave Mode. Default is c' (one-line C).
pitch="FREQUENCY"
The frequency in Hz of the concert pitch a' for notes, or of the root pitch for proportions and proportional chords. Default is 440.
tempo="NOTEVALUE=RATE|DURATION"
The number (rate) of reciprocal note values per minute. A single number is the duration of a whole note in seconds. Default is "4=60".
volume="LEVEL"
The volume level (master gain value) in the range 0.0 (silent) thru 1.0 (loudest, 100%, 0 dB). Default is 0.5 (50%, -6.0 dB).
detune="CENTS"
The cent value for detuning each tone of the sequence. Default is 0.
type="OSCILLATOR_TYPE"
The index or name of the oscillator type (waveform); one of:
  • 0 = sine (default)
  • 1 = sawtooth
  • 2 = square
  • 3 = triangle
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. In case of several players in a document, only the first player with this attribues respects it.
display="DISPLAY_STATE"
The index or name of the display state; one of:
  • 0 = hidden (or empty): All elements incl. Minimize/Opening and "Show score" buttons are hidden.
  • 1 = min: Displays only the Play-back or the Stop button, depending on the current mode, the "Show score" button if applicable, and an Opening button +.
  • 2 = open: Displays all elements of the user interface and a Minimize button .
If not present (or another value) and the "Tone sequence" field contains a text (from the seq attribute or from the query part of the window location), the player is minimized, else it is open.
score="SCORE_ID"
The ID of an HTML "ekmusic" element whose embedded score will be associated with the player for typesetting the current tone sequence; see Associated Player and Score.
The special value + automatically creates a score (incl. an HTML "ekmusic" element) immediately after the player, associates it with the player, and passes to it the following score specific attribues if specified in the HTML "ekmaudio" element:
  • ledger
  • spacing
  • caption
  • notecaption
  • clef
  • notation
  • accidental
  • duration
help="URL"
The URL for the help link in the player that will open a separate window. If not present. the latest URL specified in a previous player of the same document is set. An empty value does not show a help link. This is the default.
variables="PATH"
The path component of the URL of online variable definition files. If not present or if PATH is empty, no online files can be loaded (only local files). The origin (protocol, host, port) cannot be specified, because it must be the same as that of the document; e.g. if the current URL is http://my.domain/dir/page.htm a file myvars.json has the URL http://my.domain/PATH/myvars.json .
This attribute is respected only in the first player of a document and effects all subsequent players.

Example 1

This example requires the following files to be included in the document:

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

<div class="ekmaudio"
     seq="c4 [hesel, fisil' c' asel']2 er'4
          gir,8 [desir er gir cel esir]4. fisir2
          [aser, eir' heser' dir  fih]2.. cel'8
          dir4 cel2 fih4 asil,1" 1
     relative="c''"
     tempo="4=80"
     volume="0.3"
     help="playerhelp.htm"
     variables="var"
>
Here is an audio player
</div>

Result in the browser:

Here is an audio player

Score

To embed a music score in a document, a HTML "ekmusic" element, i.e. an element with the class name ekmusic must be inserted; e.g.:

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

The content (fallback content) of each "ekmusic" element will be replaced with the score user interface using the following attributes in the element to initialize the layout and the content of the score:

seq="TONE_SEQUENCE"
The textual tone sequence of the music notes to be displayed Default is an empty score.
relative="NOTENAME[ACCENTS]"
The octave mode for the TONE_SEQUENCE. A note name with optional octave accents (' or ,) sets the Relative Octave Mode and specifies the reference point for the octave of the first note. An empty string sets the Absolute Octave Mode. This is the default.
ledger="LEDGER_LINES"
The maximum number of ledger lines both above and below the staff lines. This reserves extra vertical space. An octave marking (ottava line) is displayed for higher/lower note positions. Default is 0.
spacing="SPACING"
The minimum spacing in em (1 em is the height of the staff) between consecutive notes/chords. The actual spacing can be higher depending e.g. on the used accidentals. Default is 0 (i.e. a proportional spacing a.k.a. spring).
caption="CAPTION"
The content for the score caption positioned below the prefix staff. It may include HTML code, though it is displayed as preformatted text, i.e. newline can be used to separate caption items. Vertical lines | are replaced by newlines (\n) as an alternative to &#x0A; entities or <br> tags.
The height of the entire score and the left position of the first note are adapted according to the dimensions of the score caption. Its width should not exceed 4 em (1 em is the height of the staff).
notecaption="NAME[;...]"
A list of property names of tones, separated by vertical lines |. This generates a caption below each note with the respective property values, separated by newlines (\n). For a chord, only the lowest tone is respected.
Possible property names are among others:
  • pos: A consecutive number ≥ 1 of the tone (or chord) within voice 0 of the sequence.
  • name: The note name.
  • scale: The scale note (natural note) index 0 - 6, i.e. the index of the C major scale.
  • accidental: The accidental type index 0 - 34: 0 = natural, 1 = 1/12 tone up, 2 = 1/12 tone down, 3 = 1/6 tone up, etc..
  • degree: The degree (tone step) 0 - 71: 0 = C, 1 = C 1/12 tone up (cir), 2 = C 1/6 tone up (cil), etc..
  • proportion: The proportion relative to C.
  • cent: The explicitely specified cent value.
clef="CLEF"
The index or name of the clef type; one of:
  • 0 = treble: G clef (default)
  • 1 = bass: F clef
  • 2 = alto: C clef
notation="NOTATION"
The index or name of the notation style specifying the set of used accidentals.
For 72-ET, this is one of:
  • 0 = arrow: Arrow notation (default)
  • 1 = rhm: Richter Herf / Maedel notation
  • 2 = sims: Sims notation
  • 3 = sag: Sagittal notation
  • 4 = msag: Mixed Sagittal notation
  • 5 = wys: Wyschnegradsky notation
  • 6 = bos: Bosanquet commatic notation
For 24-ET, this is one of:
  • 0 = arrow: Arrow notation (default)
  • 1 = rhm: Richter Herf / Maedel notation
  • 2 = sims: Sims notation
  • 3 = sag: Sagittal notation
  • 4 = wys: Wyschnegradsky notation
  • 5 = go: Gould notation
  • 6 = stz: Stein / Zimmermann notation
  • 7 = stc: Stein / Couper notation
  • 8 = stvt: Stein / Van Blankenburg / Tartini notation
  • 9 = bos: Bosanquet commatic notation
  • 10 = four: Digit 4 notation
  • 11 = fern: Ferneyhough notation
accidental="ACCIDENTAL"
The index or name of the accidental style specifying the rules of typesetting the accidentals; one of:
  • 0 = forget: Always (default)
  • 1 = traditional: 18th century style (default in LilyPond!)
  • 2 = modern: 20th century style with extra accidentals
  • 3 = modern-cautionary: Dito with extra accidentals parenthesized
  • 4 = neo-modern: Contemporary style with repeated extra accidentals
  • 5 = neo-modern-cautionary: Dito with extra accidentals parenthesized
  • 6 = dodecaphonic: Accidental or natural sign on every note
Note: The notion of accidental style and its names are adopted from LilyPond, except for default because forget is a more suitable style for the typical usage of ekmelib with microtonal scales and intonation exercises. Other styles are omitted since the score doesn't support several voices, staff groups, or measures. Instead, the entire staff is treated as one measure.
duration="DURATION"
The playback duration of clicked notes in seconds. 0 or any non-numeric value sets a continuous tone. Default is 2.
display="DISPLAY_STATE"
The index or name of the display state; one of:
  • 0 = hidden (or empty): All elements incl. Minimize/Opening button are hidden.
  • 1 = min: Displays a small note ♪ as a placeholder for the score and an Opening button +.
  • 2 = open: Displays all elements of the score and a Minimize button .
If not present (or another value) and a valid tone sequence is specified with the seq attribute, the score is open, else it is hidden.
pitch="FREQUENCY"
The frequency in Hz of the concert pitch a' used for playing a clicked note. Default is 440.

Example 2

This example requires the following files to be included in the document:

  • pack/en-de/ekmscore-72.js
  • pack/css/ekmscore.css
  • and the Ekmelos Font, either locally installed or online available as WOFF, OTF, or SVG file, in a fonts directory, like http://my.domain/fonts/ekmelos.woff .

<div class="ekmusic"
     seq="c4 [hesel, fisil' c' asel']2 er'4
          gir,8 [desir er gir cel esir]4. fisir2
          [aser, eir' heser' dir  fih]2.. cel'8
          dir4 cel2 fih4 asil,1" 1
     relative="c''"
     ledger="3"
     spacing="1.5"
     caption="Position|Note name"
     notecaption="pos|name"
     notation="rhm"
>
Here is a music score
</div>

Result in the browser:

Here is a music score

Associated Player and Score

A player can be associated with a score for typesetting its current tone sequence; see the score attribute of the HTML "ekmaudio" element. This provides an additional "Show score" ♪ button to the right of the player window, so it is visible even for a minimized player. The first click on this button opens the score.

A player can have only one associated score. But the same score can be associated with any number of players in the same document, and it can be placed anywhere independently of the players. It always shows the tone sequence of the latest player for which the Play-back ► or the "Show score" ♪ button has been clicked. It also uses the audio parameters (Oscillator, Volume, Detuning) of this player for clicked notes.

Example 3

This example requires the following files to be included in the document:

  • pack/en-de/ekmcomb-72.js
  • pack/css/ekmcomb.css
  • and the Ekmelos Font, either locally installed or online available as WOFF, OTF, or SVG file, in a fonts directory, like http://my.domain/fonts/ekmelos.woff .

<div class="ekmaudio"
     seq="c4 [hesel, fisil' c' asel']2 er'4
          gir,8 [desir er gir cel esir]4. fisir2
          [aser, eir' heser' dir  fih]2.. cel'8
          dir4 cel2 fih4 asil,1" 1
     relative="c''"
     tempo="4=80"
     volume="0.3"
     help="playerhelp.htm"
     variables="var"
     score="samp"
>
Here is an audio player
</div>
<div class="ekmusic"
     id="samp"
     ledger="3"
     spacing="1.5"
     caption="Position|Note name"
     notecaption="pos|name"
     notation="rhm"
>
Here is a music score
</div>

Result in the browser:

Here is an audio player
Here is a music score

Example 4

This is similar to Example 3, but it makes use of the special attribute score="+".
It requires the same files to be included in the document.

<div class="ekmaudio"
     seq="c4 [hesel, fisil' c' asel']2 er'4
          gir,8 [desir er gir cel esir]4. fisir2
          [aser, eir' heser' dir  fih]2.. cel'8
          dir4 cel2 fih4 asil,1" 1
     relative="c''"
     tempo="4=80"
     volume="0.3"
     help="playerhelp.htm"
     variables="var"
     score="+"
     ledger="3"
     spacing="1.5"
     caption="Position|Note name"
     notecaption="pos|name"
     notation="rhm"
>
Here is an audio player
</div>

Result in the browser:

Here is an audio player
  1. abcdThe tone sequence is taken from the Intonation Exercises for “Welle der Nacht”, op. 2 by Franz Richter Herf (a variation in a single voice for demonstration purpose since the score supports only one voice). The scores with all exercises are available for download.