ekmelib

Download ekmelib

Ekmelib is a collection of scripts (JavaScript and CSS) which support the embedding of simple audio and score content in Web pages (HTML documents) – intended primarily for microtonal samples, scales, intonation exercises etc., in particular, for the 72-tone equal-temperament (72-ET, ekmelic) system.
It works in modern browsers without the need of special plugins (such as QuickTime), audio files, streaming audio, or graphic files. (The playback is based on the Web Audio API.)

Ekmelib provides precomposed scripts for the most important use cases – player only, score only, or both combined – as described below, each in English and German. They can be found in the pack directory of the ekmelib package. Note that they are minified with JSMin for faster download.
See the pages Audio samples of Tone sequences, Tunings of some Works, Introduction, and Ekmelic Series, as well as the Ekmelic Player which make use of ekmelib.

Beyond the precomposed scripts, other playback and typesetting engines can be built by combining ekmelib scripts from the js directory, possibly with additional scripts, e.g. to implement another tone system outside of 72-ET or other note names.

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

Tone Sequences

A tone sequence is given in textual form, e.g. in a text editing control or with the seq attribute in an HTML "ekmaudio" or "ekmusic" element.

See the Syntax of Tone Sequences. It is the same, both for the player and the score.

A tone sequence may have any length, either monophonic or polyphonic with up to 16 voices. Note that the player always renders the tone sequence in one channel (mono) and the score displays only the first voice.

Player

The ekmelib audio player provides the following elements in the user interface:

  • A button bar (transport bar) with buttons for "Play-back" ►, "Stop" █▌, "Pause" ▌▌, "Hold" ▌Ɔ, "Resume" ▌►, and "Repeated play-back" Ɔ.
  • A progress bar that indicates the elapsed time in steps of the tones played so far.
  • Four text input fields to enter the text parameters: tone sequence, octave mode ("Relative to"), pitch, and tempo.
    Note that changes of the text parameters have no effect while playing. They will be respected not until the next play-back.
  • Three controls for the audio parameters: oscillator type (waveform), volume level (master gain value), and detuning.
  • A display of the volume level that can be toggled between percent (%) and decibel (dB) by clicking on the value.
  • A list of error messages. It is displayed only if necessary for the current tone sequence.
  • An optional link to open a help page in a separate browser window.
  • An optional link to open the variables window used to load files with variable definitions into the player.
  • A "Show score" ♪ button, if a score is associated with the player. The first click opens the score.
  • A Minimize button − or an Opening button +.
    In the minimized player, only the Opening button +, the "Play-back" ► or "Stop" █▌ button, depending on the current mode, and the "Show score" ♪ button if applicable, are visible.

The "ekmaudio" Element

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): Hides the entire user interface.
  • 1 = min: Displays a minimized player.
  • 2 = open: Displays the entire user interface.
If not present (or any other 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 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="syntax.htm"
     variables="var"
>
Here is an audio player
</div>

Result in the browser:

Here is an audio player

Score

The ekmelib music score provides the following elements in the user interface:

  • A single staff of variable length.
  • Clickable music notes / chords to play them individually.
  • An optional caption for each note / chord placed below the staff and an overall caption leftmost below the clef.
  • Buttons for horizontal scrolling of the notes and their captions, while the clef and the overall caption are fixed.
  • A dialog box placed below the captions. It is initially hidden and can be opened / hidden by clicking on the clef. It contains controls to select the clef, the notation style, the accidental style, and the playback duration of a clicked note.
  • A Minimize button − or an Opening button +.
    In the minimized score, only the Opening button + and a small note ♪ as a placeholder for the score are visible.

The "ekmusic" Element

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 overall caption positioned below the clef. 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 overall 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): Hides the entire user interface.
  • 1 = min: Displays a minimized score.
  • 2 = open: Displays the entire user interface.
If not present (or any other 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

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="syntax.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="syntax.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 ekmelib score supports only one voice). The scores with all exercises are available for download.