Nervously Proposing Marriage


    0.1.6 • Public • Published


    Build Status

    pattern composition mini-language for javascript

    var assert = require('assert')
    var motif = require('motif')
      motif('[a  b], [[[c d] [e], f]*3, g], h'),
      [['a', 'c', 'f', 'g', 'h'],
       ['c', 'f'],
       ['b', 'e'],
       ['c', 'f'],

    motif is heavily inspired by Tidal. The parser is generated via PEG.js.




    $ npm install motif


    $ bower install motif-js
    <script src="/bower_components/motif-js/motif.js"></script>


    motif(pattern[, lookup])

    motif('a b')
    // => [['a'], ['b']]

    Compiles the given pattern string into a javascript object.

    If a lookup object is given, the value of each symbol given in the lookup object will replace the symbol's occurences in the pattern.

    motif('a b', {
      a: 23,
      b: 42,
    // => [[23], [42]]


    compilation result (buckets)

    All motif patterns produce an array of 'bucket' arrays, where a bucket represents things that occur simultaneously. In the context of music, this would mean a series of notes played at the same time. In the example below, 'a' and 'c' are in the same bucket, so they would be played at the same time.

    motif('a b, c')
    // => [['a', 'c'], ['b']]



    Numbers are a primitive type in the language. Like javascript, numbers can have an optional sign, an integer part, an optional fraction part and an optional exponent.

    // => [[23]]


    Strings are another primitive type in the language. Strings can be any series of alphanumeric characters apart from cases containing only numbers.

    // => [['l3mon']]

    If a corresponding symbol exists for the string in a lookup object given to motif, the string representation is replaced by the symbol.

    motif('a b c', {
      a: 23,
      b: 42,
    // => [[23], [42], ['c']]


    A rest produces an empty bucket. ~ is the symbol used for a rest. In the context of music, this would mean a time interval where no notes are played.

    motif('a ~ b')
    // => [['a'], [], ['b']]



    A repitition is an operation used to duplicate a pattern a number of times. Repititions can be any primitive, rest or group literal followed by a *, then an integer.

    motif('[a b]*3')
    // => [['a'], ['b'], ['a'], ['b'], ['a'], ['b']]


    Groups define pattern segments of the same 'length'. In the context of music, this would mean groups of things which should be played one after the other, each at an equivalent amount of time.

    A group can be any combination of whitespace separated primitives, rests, operations, or group literals, where a group literal is a nested motif pattern enclosed inside square brackets ([ and ]).

    Group literals and whitespace allow one to form multiple groups. In the example below, the following patterns are equivalent, where [a b], [c d] and [e f g] are the groups in each pattern.

    motif('[a b] [c d] [e f g]')
    motif('a b [c d] [e f g]')
    motif('a b [c d] e f g')

    In the example below, [a] has a rest added to it (it essentially becomes [a ~]) so that has the same length as [b c].

    motif('[a] [b c]'),
    // this simplifies to: '[a ~] [b c]'
    // then simplifies to: '[a] [] [b] [c]'
    // then compiles to: [['a'], [], ['b'], ['c']])


    Layers define pattern segments which should overlap. In the context of music, this would mean two different rhythms, possibly of different lengths, that are played simultaneously.

    A layer is recognised as one or more groups. Multiple layers are recognised as layers separated by , characters (with any number of whitespace characters before and after).

    In the example below, a and b would occur simulataneously.

    motif('a, b'),
    // => [['a', 'b']])

    As is the case with groups, layers are simplified to be of the same 'length'. In the example below, a has a rest added to it to give it the same length as [b c]. From there, buckets are formed from the two layers, so a and b get played together, and c gets played alone ([a] is concatenated with [b] and [] is concatenated with [c]).

    motif('[a], [b c]'),
    // this simplifies to: '[a ~], [b c]'
    // then simplifies to: '[a] [], [b] [c]'
    // then compiles to: [['a', 'b'], ['c']]


    You can use this library as the npm package motif:

    npm i motif
    # or
    yarn add motif

    It can be used in both es-module-aware and commonjs bundlers/environments.

    // es module
    import motif from 'motif'
    // commonjs
    const motif = require('motif')

    It can also be used a <script>:

    motif('[a], [b c]')


    npm i motif

    DownloadsWeekly Downloads






    Unpacked Size

    68.5 kB

    Total Files


    Last publish


    • justinvdm