ekmelib

Download ekmelib 2.5

Ekmelib is a collection of scripts (JavaScript and CSS) which support the embedding of simple audio and score content in Web pages (HTML documents). The focus is on:

  • Microtonality:
    Ekmelib is intended primarily for microtonal samples (scales, intonation exercises etc.), in particular, in the Ekmelic, i.e. in the 72-tone equal-temperament system (72-ET).
  • Textual form:
    Music samples are given as tone sequences in textual form. These can be specified inline in HTML documents (in ekmaudio and ekmscore elements) or in URLs, without the need of separate audio files or streaming audio. User-specific tone sequences can be entered simply with a text editing field in a Web page.
  • Simplicity:
    The scripts implement a simple playback (in one channel) and typesetting that work in modern browsers without the need of special plugins. The playback is based on the Web Audio API. The typesetting uses the Ekmelos Font.

Ekmelib provides precomposed scripts for the most important use cases – player only, score only, or both combined – each in English and German. They can be found in the directory pre of the ekmelib package and are minified with JSMin (for fast download). In addition, other playback and typesetting engines can be built, e.g. to implement another tone system or other note names, using the scripts in the directory dev.

See also the pages Audio samples of Tone sequences, Tunings of some Works, Introduction, and Ekmelic Series, which make use of ekmelib, as well as the separate Ekmelic Player (is now part of ekmelib).

Pleae, enable JavaScript in your browser for the player and the score.
Sorry, but your browser doesn't support Web Audio rendering.

Player

The player contains the following elements:

  • A button to minimize/open the player. In the minimized player, only the "Play-back" or "Stop" button is visible.
  • Transport buttons for "Play-back", "Stop", "Pause/Resume", "Hold/Resume", "Previous mark", "Next mark", and "Repeat (loop)".
  • A button to show/hide the audio parameters:
    • Volume level (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.
    The audio parameters are shared by all players and scores (to play individual notes) in the same document.
  • A button to expand all variables in the tone sequence.
  • A button to show/hide the list of variables. It contains all variables loaded so far and optionally all online available variables. A selected variable will be inserted with \ into the tone sequence.
    The list of variables is shared by all players in the same document.
  • A button to show/hide the error messages. When selecting an error (e.g. "Unknown note name"), the player jumps in the text input field to the position (note) where the error occurred.
  • A button to draw the score if applicable (i.e. if the corresponding script is included in the Web page). See Player with Score.
  • A link to the Syntax of Tone Sequences, that will be opened in a separate browser window.
  • A display of the elapse time in steps of the tones played so far, numerical and as a bar, and a display of the total duration.
  • A text input field to enter the tone sequence.
    Note that changes of the text have no effect while playing. They will be respected not until the next play-back.

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 HTML element with the class ekmaudio, 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. The following attributes in the ekmaudio element will then be used to initialize the player.

The first six attributes – seq, relative, pitch, tempo, time, and add – are the same, both for the player and the score. They will be combined to form the actual tone sequence (in the text input field), i.e. the value of the seq attribute is completed with preceding commands corresponding to the other five attributes.

seq="TONE_SEQUENCE"
The tone sequence for the text input field. A non-empty tone sequence minimizes the player initially. Default is empty.
For the first player in a document (not for a score), the tone sequence can also be provided by the query part of the window location, i.e. by ?... in the URL of the document.
relative="NOTE"
The octave mode.
NOTE is a note name with optional octave accents (' or ,). It 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.
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"
tempo="DURATION"
The tempo of note values.
NOTEVALUE=RATE sets the number of reciprocal note values per minute. The default is "4=60".
DURATION sets the absolute duration of a whole note in seconds. It may have a fractional portion.
time="NUM/DENOM"
The time (meter). NUM and DENOM must be integer numbers.
An empty string disables the meter, i.e. the score omits barlines. This is the default.
add="DATA …"
Additional data for the tones. This is a list of names separated by spaces.1 Each designates a set of related data that will be added to the tones as properties and which can be used e.g. in the caption attribute of an associated ekmscore element (see there for details on these properties).
DATA must be one of the following names:
  • degree: Data related to the respective degree: partial, approxNum, approxDenom.
    This applies to tones specified as note, frequency, or proportion in the tone sequence. It also implies note for a frequency or proportion.
  • note: Data of the note which is nearest to the respective tone: name, scale, acc, octave.
    This applies to tones specified as frequency or proportion in the tone sequence and enables the score to display real instead of "generic" note heads.
volume="LEVEL"
The volume level (master gain value). The range of LEVEL constitutes its unit:
  • 0.0 ≤ LEVEL ≤ 1.0 is the actual level (silent thru loudest).
  • LEVEL > 1 is a percent value, i.e. 100 is equivalent to 1.
  • LEVEL < 0 is a decibel (dB) value.
Default is 0.5 = 50 % = − 6.0 dB.
detune="CENTS"
The cent value of the detuning. Default is 0.
type="OSCILLATOR"
The oscillator type (waveform); one of:
  • sine (default)
  • sawtooth
  • square
  • 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. Only the first player in a document with this attribute respects it.
mini
A boolean attribute. If present or if a non-empty tone sequence is given (from the seq attribute or from the query part) the player is minimized, else it is open.
var="PATH"
The path component of the URL of a directory containing variable definition files as well as the special file list.txt. This must be a plain text file containing space-separated variable names 1 (not the filenames and without a leading \ ) which are intended to be online available. It will be loaded automatically to fill the list of variables.
Note that the origin of the URL (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 myvar.txt has the URL http://my.domain/PATH/myvar.txt
If this attribute is not present or if PATH is empty, only local files can be loaded. Only the first player in a document respects this attribute.
score="SCORE_ID"
score="+"
The ID of an HTML ekmscore element that will be associated with the player. See Player with Score.
+ creates a new score.

Example 1

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

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

Result in the browser:

Here is an ekmelib player

Score

The score contains the following elements:

  • 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 (i.e. the staff prefixes) remain fixed. Scrolling takes place either via the flashed scroll buttons or automatically during play-back of the associated player.
  • Clickable staff prefixes (containing the clef) to show/hide the style parameters:
    • Clef type: Treble, Bass, Alto clef.
    • Notation style: Depends on the tone system; e.g. for 72-ET: Arrow, Richter Herf / Maedel, Sims, Sagittal, Wyschnegradsky notation et al.
    • Accidental style: Specifies the rules of typesetting the accidentals: always (forget), traditional, modern, neo-modern, dodecaphonic et al. 3
    • Playback duration of a clicked note: 1 thru 4 seconds or continuous tone.
    The style parameters apply to all staves, except for the clef type.
  • Clickable music notes / chords to play them individually. A further click while playing stops the play-back (useful in particular when a continuous tone is selected).
  • Tones specified as frequency or proportion in the tone sequence are represented by "generic" note heads [] and <> above the bottom staff line.
  • An optional caption (e.g. note name) placed below each note / chord, and a label placed below each clef.

The HTML ekmscore Element

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

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

The content (fallback content) of each ekmscore element will be replaced with the actual score. The following attributes in the ekmscore element will then be used to initialize the score.

The first six attributes – seq, relative, pitch, tempo, time, and add – are described in details at the ekmaudio element. They are the same, both for the score and the player. They are usually not required in a score if this is associated with a player.

seq="TONE_SEQUENCE"
The tone sequence to be displayed.
relative="NOTE"
The octave mode.
pitch="FREQUENCY"
The concert or root pitch.
tempo="NOTEVALUE=RATE"
tempo="DURATION"
The tempo of note values.
time="NUM/DENOM"
The time (meter).
add="DATA …"
Additional data.
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 1.
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 e.g. depending on the printed accidentals. Default is 0, i.e. a proportional spacing (a.k.a. spring).
clef="CLEF …"
The clef types. This is a list of names separated by spaces;1 one for each staff and the last name applies to all further staves. CLEF must be one of:
  • treble: G clef (default)
  • bass: F clef
  • alto: C clef
Default is "treble treble alto bass".
notation="NOTATION"
The notation style specifying the set of used accidentals.
For 72-ET, this is one of:
  • arrow: Arrow notation (default)
  • rhm: Richter Herf / Maedel notation
  • sims: Sims notation
  • sag: Sagittal notation
  • msag: Mixed Sagittal notation
  • wys: Wyschnegradsky notation
  • bos: Bosanquet commatic notation
For 24-ET, this is one of:
  • arrow: Arrow notation (default)
  • rhm: Richter Herf / Maedel notation
  • sims: Sims notation
  • sag: Sagittal notation
  • wys: Wyschnegradsky notation
  • go: Gould notation
  • stz: Stein / Zimmermann notation
  • stc: Stein / Couper notation
  • stvt: Stein / Van Blankenburg / Tartini notation
  • bos: Bosanquet commatic notation
  • four: Digit 4 notation
  • fern: Ferneyhough notation
For 12-ET, this is one of:
  • std: Standard notation (default)
  • sag: Sagittal notation
accidental="ACCIDENTAL"
The accidental style specifying the rules of typesetting the accidentals; one of: 3
  • forget: Always (default).
  • traditional: 18th century style (This is "default" in LilyPond!).
  • modern: 20th century style with extra accidentals.
  • modern-cautionary: Dito with extra accidentals parenthesized.
  • neo-modern: Contemporary style with repeated extra accidentals.
  • neo-modern-cautionary: Dito with extra accidentals parenthesized.
  • dodecaphonic: Accidental or natural sign on every note.
duration="DURATION"
The playback duration of clicked notes in seconds. 0 sets a continuous tone. Default is 1.
caption="LABEL|CAPTION|…"
The label placed below each clef, and the caption placed below each note or chord. This is a list of items separated by |, each of which will be displayed in a separate line. The height of the entire score is adapted according to the number of label/caption items. Both LABEL and CAPTION can be empty.
LABEL may contain HTML code, though it is treated as preformatted text.
CAPTION contains JavaScript code (expression or statements) that will be evaluated for each tone (or for the highest tone of a chord), as follows:
A # is used to indicate a tone property or method. It must be followed by a valid property/method name that will be evaluated (invoked) for the respective tone. An item that consists only of letters (a-z,A-Z; no space) is considered being a single property name. A literal # must be specified as ##.
Available properties and methods are among others:
  • name: The note name.
  • f: The frequency in Hz, or a flag < 0 for a tick, rest, skip, or command.
  • scale: The scale index: 0 = C, 1 = D, … 6 = B.
  • acc: The accidental index; e.g. for 72-ET: 0 = natural, 1 = 1/12 up, 2 = 1/12 down, 3 = 1/6 up, 4 = 1/6 down, … 34 = 5/4 down.
  • octave: The octave index: 0, … 7 = great octave, 8 = small octave, 9 = one-line octave, … 15.
  • partial: The partial tone number.
  • approxNum, approxDenom: The numerator and denominator of the approximate proportion relative to C.
  • cent: The explicitely specified cent value.
  • value: The note value index: 0 = whole note, 1 = half note, 2 = quarter note, … 7 = 128th note.
  • dots: The number of augmentation dots.
  • voice: The index of the voice: 0 - 15.
  • dur: The duration in seconds.
  • lag: The time-lag, i.e. the distance to the subsequent moment in seconds.
  • tie: True if the tone is tied to the next tone.
  • degree(): The degree; e.g. for 72-ET: 0 = C, 1 = C 1/12 up, 2 = C 1/6 up, 3 = C 1/4 up, … 71 = B 5/12 up.
  • proportion(): The proportion relative to the small C.
  • fullScale(): The scale and octave index combined: … 56 = small C, … 62 = small B, 63 = one-line C, …
See the description of EkmTone in dev/js/ekmdata.js for more details on tone properties and methods.

Example 2

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

  • pre/en-de/ekmscore-72.js
  • pre/css/ekmscore.css
  • and the Ekmelos Font as WOFF, OTF, or SVG, online in a directory fonts (e.g. http://my.domain/fonts/ekmelos.woff) or locally installed.
<div class="ekmscore"
     seq="t4 t t t c4 r r8 er4. gir,2 fisir
          \time r4 heser2. r8 cel dir4.~
          \time=3/4 dir4 cel2 fih4 asil,2
          \\
          \gain=0.15 \=c'
          <fisil c' asel'>1~ q <gir cel esir>
          <heser dir fih>1*19/8 <heser dir fih>2.
          \\
          \gain=0.2 \=c,
          <er hesel''>1~ q <er desir''>
          <aser eir'>1*19/8 q2." 2
     relative="c''"
     time="4/4"
     clef="treble treble bass"
     notation="rhm"
     accidental="modern"
>
Here is an ekmelib score
</div>

Result in the browser:

Here is an ekmelib score

Player with Score

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

  1. either initially, 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 later by clicking the "Draw score" button 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 containing the score) immediately after the ekmaudio element and pass to it the following attributes if specified in the ekmaudio element:

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

A player can have only one associated score. But the same score can be associated with any number of players in the same document. It always shows the tone sequence of the latest associated player for which "Play-back" or "Draw score" has been clicked.

Example 3

This example associates a player with a score that has the ID "show". Here, the ekmscore element is placed after the ekmaudio element with a text in between, but it can be placed anywhere in the document.
The example requires the following files to be included in the document:

  • pre/en-de/ekmcomb-72.js
  • pre/css/ekmcomb.css
  • and the Ekmelos Font as WOFF, OTF, or SVG, online in a directory fonts (e.g. http://my.domain/fonts/ekmelos.woff) or locally installed.
<div class="ekmaudio"
     seq="t4 t t t c4 r r8 er4. gir,2 fisir
          \time r4 heser2. r8 cel dir4.~
          \time=3/4 dir4 cel2 fih4 asil,2
          \\
          \gain=0.15 \=c'
          <fisil c' asel'>1~ q <gir cel esir>
          <heser dir fih>1*19/8 <heser dir fih>2.
          \\
          \gain=0.2 \=c,
          <er hesel''>1~ q <er desir''>
          <aser eir'>1*19/8 q2." 2
     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:

Here is an ekmelib player
Click on a note or chord to play it:
Here is an ekmelib score

Example 4

This is similar to Example 3, but it makes use of the special attribute value score="+", and nothing can be inserted between the ekmaudio element and the auto-created ekmscore element.
The example requires the same files to be included in the document.

<div class="ekmaudio"
     seq="t4 t t t c4 r r8 er4. gir,2 fisir
          \time r4 heser2. r8 cel dir4.~
          \time=3/4 dir4 cel2 fih4 asil,2
          \\
          \gain=0.15 \=c'
          <fisil c' asel'>1~ q <gir cel esir>
          <heser dir fih>1*19/8 <heser dir fih>2.
          \\
          \gain=0.2 \=c,
          <er hesel''>1~ q <er desir''>
          <aser eir'>1*19/8 q2." 2
     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:

Here is an ekmelib player with score
  1. abcThis is a “set of space-separated tokens”, according to HTML 5, where a space character is a space, tab, line feed (LF), carriage return (CR), or form feed (FF). However here, it can be any Unicode white space according to the JavaScript character class \s (equivalent to [ \f\n\r\t\v​\u00a0\u1680​\u180e\u2000​-\u200a​\u2028\u2029\u202f\u205f​\u3000\ufeff]).
  2. abcdThe tone sequence is taken from the Intonation Exercises for “Welle der Nacht”, op. 2 by Franz Richter Herf. The scores with all exercises are available for download.
  3. abThe notion of the Accidental style and the names are adopted from LilyPond, except for "default" because "always (forget)" is a more suitable style for the typical usage of ekmelib with microtonal scales and intonation exercises.