# Module `Mu.M`

Music definition module.

This module provides short forms and derived combinators to define music concisely. It is meant to be used with `M.`, `M.()`, `M.[]` notations and, possibly, local `open`s.

## Basic music

`val note : Music.dur -> 'a -> 'a Music.t`

`note d p` is ``Prim (`Note (d, p))`, interprets note `p` for duration `d`. See also pitched notes constructors.

`val rest : Music.dur -> 'a Music.t`

`rest d` is ``Prim (`Rest d)`, rests for duration `d`.

`val seq : 'a Music.t -> 'a Music.t -> 'a Music.t`

`seq m0 m1` is ``Seq (m0, m1)`, interprets `m0` followed by `m1`.

`val par : 'a Music.t -> 'a Music.t -> 'a Music.t`

`par m0 m1` is ``Par (m0, m1)`, interprets `m0` in parallel with `m1`.

`val ctrl : Music.Ctrl.t -> 'a Music.t -> 'a Music.t`

`ctrl c m` is ``Ctrl (c, m)`.

`val nil : 'a Music.t`

`nil` is `rest Q.zero`, empty music.

`val line : 'a Music.t list -> 'a Music.t`

`line ms` interprets musics `ms` sequentially, in order.

`val chord : 'a Music.t list -> 'a Music.t`

`chord ms` iterprets musics `ms` in parallel.

`val times : int -> 'a Music.t -> 'a Music.t`

`times n m` repeats music `m` `n` times. Raises `Invalid_argument` if `n` is negative.

`val retro : 'a Music.t -> 'a Music.t`

`retro m` is the retrograde of `m`.

`val drop_zeros : 'a Music.t -> 'a Music.t`

`drop_zeros m` removes zero duration rests and notes from `m`.

## Breaking

`val take : Music.dur -> 'a Music.t -> 'a Music.t`

`take d m` is music `m` for duration `d`.

`val drop : Music.dur -> 'a Music.t -> 'a Music.t`

`drop d m` is the music of `m` after `d`.

## Ornaments

`val grace : Q.t -> Pitch.rel -> Pitch.t Music.t -> Pitch.t Music.t`

`grace rd rp m` is the note `m` with a grace note added. Given `d = Music.dur m`, this becomes two notes: the note `m` transposed by `rp` with duration `rd * d` followed by the note `m` with duration `(1 - r) * d`.

Raises `Invalid_argument` if `m` is not a note.

XXX. We could make it polymorphic by using `transp`.

## Percussion and instruments

`val perc : Percussion.t -> Music.dur -> Pitch.t Music.t`

`perc p d` is percusion sound `p` during `d`.

`val instrument : Instrument.t -> 'a Music.t -> 'a Music.t`

`instrument i m` is ``Ctrl (`Instrument i) m`, interprets `m` with instrument `i`.

Note. `instrument i' (instrument i m)` interprets `m` with `i`. Use `change_instrument` if you want to change the instrument in `m`.

`val drop_instruments : 'a Music.t -> 'a Music.t`

`drop_instruments m` removes all instruments from `m`.

`val change_instrument : Instrument.t -> 'a Music.t -> 'a Music.t`

`change_instrument i m` is `instrument i (drop_instrument m)`.

## Other controls

`val transp : Pitch.rel -> 'a Music.t -> 'a Music.t`

`transp r m` is `ctrl (`Transpose n) m`, transposes `m` by `r` relative semitones. Note that this does not alterate actual pitch values in `m` (the function does not know the note representation).

`val phrase : Music.Phrase.t -> 'a Music.t -> 'a Music.t`

`phrase atts m` is ``Ctrl (`Phrase atts) m`.

`val key_sig : Pitch.Class.t -> Music.Mode.t -> 'a Music.t -> 'a Music.t`

`key_sig c mode m` is ``Ctrl (`Key_sig (c, mode)) m`.

## Timing

`val offset : Music.dur -> 'a Music.t -> 'a Music.t`

`offset d m` is `rest d ^ m`.

`val tempo : Q.t -> 'a Music.t -> 'a Music.t`

`tempo r m` is `ctrl (`Tempo r) m`, multiplies the tempo of `m` by `r`. If `r` is `Q.(2/1)` `m` is played twice as fast (duration are divided by `m`). Note that in contrast to `mul_durs`, this does not change actual durations in `m`.

`val mul_durs : Q.t -> 'a Music.t -> 'a Music.t`

`mul_durs r m` multiplies durations in `m` by `r`. In contrast to `tempo` this acts on the actual duration values in `m`.

### Durations

Using initials of the American English standard, except for double whole note where breve note is used (`bn`) due to a name clash with dotted whole note (`dwn`).

`val bn : Music.dur`

`bn` is `2/1`, breve note (double whole note).

`val wn : Music.dur`

`wn` is `1/1`, whole note.

`val hn : Music.dur`

`hn` is `1/2`, half note.

`val qn : Music.dur`

`qn` is `1/4`, quarter note.

`val en : Music.dur`

`en` is `1/8`, eighth note.

`val sn : Music.dur`

`sn` is `1/16`, sixteenth note.

`val tsn : Music.dur`

`tsn` is `1/32`, thirty-second note.

`val sfn : Music.dur`

`sfn` is `1/64`, sixty-fourth note.

`val dwn : Music.dur`

`dwn` is `3/2`, dotted whole note.

`val dhn : Music.dur`

`dhn` is `3/4`, dotted half note.

`val dqn : Music.dur`

`dqn` is `3/8`, dotted quarted note.

`val den : Music.dur`

`den` is `3/16`, dotted height note.

`val dsn : Music.dur`

`dsn` is `3/32`, dotted sixteenth note.

`val dtsn : Music.dur`

`dtsn` is `3/64`, dotted thirty-second note.

`val ddhn : Music.dur`

`ddhn` is `7/8`, double dotted half note.

`val ddqn : Music.dur`

`ddqn` is `7/16`, double dotted quarter note.

`val dden : Music.dur`

`dden` is `7/32`, double dotted eight note.

### Rests

The names are those of durations suffixed by `r`.

`val bnr : 'a Music.t`
`val wnr : 'a Music.t`
`val hnr : 'a Music.t`
`val qnr : 'a Music.t`
`val enr : 'a Music.t`
`val snr : 'a Music.t`
`val tsnr : 'a Music.t`
`val sfnr : 'a Music.t`
`val dwnr : 'a Music.t`
`val dhnr : 'a Music.t`
`val dqnr : 'a Music.t`
`val denr : 'a Music.t`
`val dsnr : 'a Music.t`
`val dtsnr : 'a Music.t`
`val ddhnr : 'a Music.t`
`val ddqnr : 'a Music.t`
`val ddenr : 'a Music.t`

## Pitched notes

The names are those of `Pitch.Class.t` constructors lowercased. `as'` is primed since `as` is an OCaml keyword.

`val cff : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`cff o d` is `note d (`Cff, o)`

`val cf : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`cf o d` is `note d (`Cf, o)`

`val c : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`c o d` is `note d (`C, o)`

`val dff : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`dff o d` is `note d (`Dff, o)`

`val cs : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`cs o d` is `note d (`Cs, o)`

`val df : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`df o d` is `note d (`Df, o)`

`val css : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`css o d` is `note d (`Css, o)`

`val d : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`d o d` is `note d (`D, o)`

`val eff : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`eff o d` is `note d (`Eff, o)`

`val ds : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`ds o d` is `note d (`Ds, o)`

`val ef : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`ef o d` is `note d (`Ef, o)`

`val fff : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`fff o d` is `note d (`Fff, o)`

`val dss : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`dss o d` is `note d (`Dss, o)`

`val e : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`e o d` is `note d (`E, o)`

`val ff : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`ff o d` is `note d (`Ff, o)`

`val es : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`es o d` is `note d (`Es, o)`

`val f : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`f o d` is `note d (`F, o)`

`val gff : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`gff o d` is `note d (`Gff, o)`

`val ess : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`ess o d` is `note d (`Ess, o)`

`val fs : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`fs o d` is `note d (`Fs, o)`

`val gf : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`gf o d` is `note d (`Gf, o)`

`val fss : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`fss o d` is `note d (`Fss, o)`

`val g : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`g o d` is `note d (`G, o)`

`val aff : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`aff o d` is `note d (`Aff, o)`

`val gs : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`gs o d` is `note d (`Gs, o)`

`val af : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`af o d` is `note d (`Af, o)`

`val gss : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`gss o d` is `note d (`Gss, o)`

`val a : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`a o d` is `note d (`A, o)`

`val bff : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`bff o d` is `note d (`Bff, o)`

`val as' : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`as' o d` is `note d (`As, o)`

`val bf : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`bf o d` is `note d (`Bf, o)`

`val ass : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`ass o d` is `note d (`Ass, o)`

`val b : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`b o d` is `note d (`B, o)`

`val bs : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`bs o d` is `note d (`Bs, o)`

`val bss : Pitch.octave -> Music.dur -> Pitch.t Music.t`

`bss o d` is `note d (`Bss, o)`

## Operators

Both operators are right associative, `^` is tighter than `@|@`. Open `Mu.Syntax` if you want them in your scope.

`val (^) : 'a Music.t -> 'a Music.t -> 'a Music.t`

`m0 ^ m1` is `Music.seq`` m0 m1`.

`val (@|@) : 'a Music.t -> 'a Music.t -> 'a Music.t`

`m0 @|@ m1` is `Music.par`` m0 m1`.