# `Mx.Music`
[🔗](https://github.com/mx-music/mx/blob/main/lib/mx/music.ex#L1)

Music as values: notes and rests joined one after another or at once, repeated, moved and placed, and played by parts.

Every function returns a value and records nothing on the side, and raises `ArgumentError` as soon as what it is given cannot play: `note` refuses an unknown name, `part` a note its synth cannot play, `together` two parts of one name, and `song` a note outside any part.
The song file's loader finds the line in the stacktrace of that error.

A song's music is split into sections, the items of its outermost seq, looking through repeat.
Each part becomes a loop whose pass `n` plays that part's notes in section `n`, so every part's pass ends where a section ends, and a saved version takes over there.

# `at`

Music lasting some beats whose items start at their beats from its start, given as `{beat, music}`.

# `beats`

The length of the music in beats, or `:infinity` for music that plays until mx stops.

# `change`

A change to every sound of a part still playing, or with `{part, effect}` to one of its effects, taking no time.

# `check_range`

Raises `ArgumentError` naming the value unless it is an integer from `low` to `high`.

# `delay`

The music after some beats of silence.

# `hit`

A hit of a drum at its own pitch, taking no time, with options for the part's synth.

# `load`

Records a song into the song being loaded: its settings, and a loop for each of its parts.

# `loop`

Music that runs the function with the pass number and the inputs every `beats` beats, and plays the music it returns; `times:` plays a number of passes, and `on:`, given instead of beats, plays a pass on each input it waits for.

# `midi`

A MIDI note on, and its note off after some beats, taking `velocity:` and `channel:`.

# `midi_cc`

A MIDI controller change, taking `channel:` and no time.

# `note`

A note of a pitch, given as a name, a number or a list of them, lasting some beats, with options for the part's synth.

# `osc`

An OSC message to the song's `osc_to`, taking no time.

# `part`

Music played by one player, refusing a synth mx does not have and a note the synth cannot play.

# `pitch`

The number of a note name, or the number itself.

# `repeat`

Music played again and again until mx stops.

# `repeat`

Music played a number of times in a row.

# `replay`

Records pass `n` of a part's music: its notes in section `n`, and the passes its loops play there, going round again after the last section of music that repeats until mx stops.

# `rest`

Silence lasting some beats.

# `sample`

A sample of the pack by name, a WAV, AIFF or FLAC file by path, or a file of a GitHub repository as `{:github, repo, ref, path}`, lasting some beats, refusing a sample mx cannot find and an option samples do not take.

# `seq`

Music played one item after another; an item given as `{name, beats}` is a note, and as `{:r, beats}` a rest.

# `set`

A value shared with every loop from its next pass, taking no time.

# `song`

The song, refusing a note outside any part, a part of one name played with other options, and repeat with no count anywhere but around the whole music.

# `steps`

The sounds of a pattern, each character of a string or each word of `~MX` lasting a step of beats; a list of strings is one bar after another.

# `swing`

The music with each note started at the beat the function returns for the beat it was written on, its length unchanged.

# `tempo`

A change of every part's tempo to some beats per minute, at once, or with `over:` evenly over that many beats, taking no time.

# `together`

Music whose items all start at once, as long as the longest, refusing two parts of one name among them.

# `transpose`

The music moved by a number of semitones, every note moved and nothing else changed.

---

*Consult [api-reference.md](api-reference.md) for complete listing*