# mx v0.1.0 - Table of Contents

> Write music in Elixir, played by mxs, its own sound engine in Rust

## Pages

- [mx](readme.md)

- Guides
  - [The notation](notation.md)
  - [Instruments](instruments.md)
  - [Scores and hums](scores.md)
  - [Examples](examples.md)

- Setup
  - [Setting up Audiveris](audiveris.md)

- Internals
  - [Architecture](architecture.md)

## Modules

- [Mx.Page](Mx.Page.md): Writes a song as one HTML page that plays it and shows each part's notes on a timeline, for `mix mx.page`.
- [Mx.Pattern](Mx.Pattern.md): Music written as words, which `~MX` reads when the song compiles and `Mx.steps/3` gives its sounds.

- Music
  - [Mx](Mx.md): Music written as Elixir code.
  - [Mx.Music](Mx.Music.md): Music as values: notes and rests joined one after another or at once, repeated, moved and placed, and played by parts.
  - [Mx.Notes](Mx.Notes.md): Note names, chords and scales, worked out as plain MIDI note numbers.
  - [Mx.Pass](Mx.Pass.md): Runs one pass of a loop and returns what it played, with each note's beat
within the pass.
  - [Mx.Song](Mx.Song.md): A song loaded from a file: its tempo and its parts, each played as a loop, in the order of the song.
`tempos` holds the tempo changes its music writes, each section's as `Mx.Tempo` takes them, or nil when it writes none.
  - [Mx.Tempo](Mx.Tempo.md): The tempo over a song's beats: the timeline the band plays against, and the tempo changes a song's music writes in its sections.
  - [Mx.Music.At](Mx.Music.At.md): Music of a length whose items start at their beats from its start.
  - [Mx.Music.Change](Mx.Music.Change.md): A change to every sound of a part still playing, or to one of its effects, with `target` being the part's name or `{name, effect}`.
  - [Mx.Music.Loop](Mx.Music.Loop.md): Music that runs a function for each pass of some beats and plays the music it returns, a number of times or as long as the music beside it; or, with `on:`, a pass for each input it waits for.
  - [Mx.Music.LoopError](Mx.Music.LoopError.md): A pass of a loop refused after its function returned, with the line of the song that wrote the loop.
  - [Mx.Music.MIDI](Mx.Music.MIDI.md): A MIDI note sent for some beats, with its velocity and channel.
  - [Mx.Music.Message](Mx.Music.Message.md): A step that takes no time: a MIDI controller change, an OSC message, or a value shared with the other loops.
  - [Mx.Music.Note](Mx.Music.Note.md): A note: its pitch, a number, a list of numbers or `:own_note` for a drum, its length in beats and its options.
  - [Mx.Music.Part](Mx.Music.Part.md): Music played by one player, with its synth and the loop options it takes.
  - [Mx.Music.Repeat](Mx.Music.Repeat.md): Music played a number of times in a row, or until mx stops with `times: :forever`.
  - [Mx.Music.Rest](Mx.Music.Rest.md): Silence lasting some beats.
  - [Mx.Music.Sample](Mx.Music.Sample.md): A sample by name or path, lasting some beats, with the options samples take.
  - [Mx.Music.Seq](Mx.Music.Seq.md): Music played one item after another.
  - [Mx.Music.Song](Mx.Music.Song.md): The value a song file ends with: its settings, and its music split into sections, each part's notes in each.
  - [Mx.Music.Swing](Mx.Music.Swing.md): Music whose notes start at the beat a function returns for the beat they were written on.
  - [Mx.Music.TempoChange](Mx.Music.TempoChange.md): A change of the whole song's tempo to `bpm`, at once or evenly over `over` beats.
  - [Mx.Music.Together](Mx.Music.Together.md): Music whose items all start at once.
  - [Mx.Pass.Handle](Mx.Pass.Handle.md): What record_play, record_sample and effect return: the events or effect a later control step changes, and the synth whose options they are.
  - [Mx.Song.Live](Mx.Song.Live.md): A live audio input the song declares: the sound card input it plays, in mono or stereo, with its options and effects.
  - [Mx.Song.Loop](Mx.Song.Loop.md): A part of the song played as a loop, with the music it replays and the samples it uses.

- Samples
  - [Mx.GitHub](Mx.GitHub.md): Files of public GitHub repositories, downloaded into the user's cache, for samples a song names as `{:github, repo, ref, path}` and collections downloaded ahead of time.
  - [Mx.Sampled](Mx.Sampled.md): A sampled instrument: recordings of an instrument one key at a time, often at several strengths and in several takes, played as a part plays a synth.
  - [Mx.Samples](Mx.Samples.md): Sonic Pi's sample pack, which is under Creative Commons 0, and the files a song plays as samples: the pack's by name, a file by path, or a file of a public GitHub repository as `{:github, repo, ref, path}`.

- Playing
  - [Mx.Application](Mx.Application.md): Starts mx with an empty supervisor; each session starts its own processes.

  - [Mx.Band](Mx.Band.md): Plays a song's loops together, each in its own process, against one shared beat.
  - [Mx.Clock](Mx.Clock.md): The Unix time in microseconds mx plays against: the system's, or while a song renders offline, the time its render has reached.
  - [Mx.Inputs](Mx.Inputs.md): Keeps the latest value of every input from outside mx, and the values loops share.
  - [Mx.Loop](Mx.Loop.md): Plays one loop of a song, pass after pass.
  - [Mx.Out](Mx.Out.md): Sends MIDI and OSC to other devices and programs at their time.
  - [Mx.Player](Mx.Player.md): Plays a song file until Enter is pressed or its music ends, and plays each saved version of it, for `mix mx.play` and the `mx` command.

  - [Mx.Session](Mx.Session.md): Plays one song file: the engine, the band, and the
watcher that hands each saved version to the band.
  - [Mx.Watcher](Mx.Watcher.md): Loads a song file again whenever its content changes, and hands each
version that loads to `on_song`. A version that does not load prints its
error, and the playing version stays.

- Engine
  - [Mx.Engine](Mx.Engine.md): The boundary between mx and the engine that makes its sound.
  - [Mx.OSC](Mx.OSC.md): Encodes and decodes the OSC messages and bundles mx exchanges with other programs.
  - [Mx.Render](Mx.Render.md): Renders a song file offline to a stereo WAV file, as fast as the machine renders it and with no sound card, for `--render`.
  - [Mx.Synths](Mx.Synths.md): The synths mx ships, with the options each one takes and their defaults, as mxs lists them.
  - [Mx.Engine.Mxs](Mx.Engine.Mxs.md): mx's engine on mxs, mx's sound engine in Rust, through a NIF.
  - [Mx.Engine.Mxs.Native](Mx.Engine.Mxs.Native.md): The functions mxs, the Rust engine, provides as NIFs.

- Instruments
  - [Mx.Instrument](Mx.Instrument.md): Synths written in Elixir, as `defsynth`, which mxs builds when a note starts; the guide "Instruments" introduces them.
  - [Mx.Instrument.Expr](Mx.Instrument.Expr.md): A value a `defsynth` works out from the note's options: one option, or a call of the vocabulary on its arguments and named arguments.
  - [Mx.Instrument.Ops](Mx.Instrument.Ops.md): The arithmetic a `defsynth`'s operators become: on numbers it is Elixir's own, and on anything worked out from the note it records the operation.
  - [Mx.Instrument.Vocabulary](Mx.Instrument.Vocabulary.md): The nodes and functions a `defsynth` builds its sound from, named by what they do, with each argument named by its unit.

- Measuring
  - [Mx.Audio](Mx.Audio.md): Reads WAV and AIFF recordings, in mono or stereo, at any sample rate, as one channel of samples from -1 to 1.
  - [Mx.FFT](Mx.FFT.md): The spectrum of a stretch of samples, through a Hann window, as the magnitude of each frequency bin up to half the sample rate.
  - [Mx.Fit](Mx.Fit.md): Searches for the values of a synth's controls that bring its held notes closest to recordings of them, as `mix mx.fit` does.
  - [Mx.Measure](Mx.Measure.md): Measures recordings of single notes, plucked or struck, so a synth's design can be compared with a real instrument's.
  - [Mx.Recording](Mx.Recording.md): Checks where a session can be recorded, and reads the length, peak and clips of a recording.
  - [Mx.Signal](Mx.Signal.md): The pieces the measuring of plucked notes, held notes and hits share: filtering, spectra, finding where sounds start, and fitting a fade.
  - [Mx.Spectrogram](Mx.Spectrogram.md): Draws a spectrogram of a recording into a PNG image: seconds across, at 100 pixels a second unless `per_second:` gives another count, and frequency up the side on a scale of octaves.
  - [Mx.Measure.Held](Mx.Measure.Held.md): Measures recordings of held notes, bowed, blown or played on an organ, so a synth's design can be compared with a real instrument's.
  - [Mx.Measure.Hits](Mx.Measure.Hits.md): Measures recordings of hits, struck bars, bells, drums and scrapers, with or without a pitch, so a synth's design can be compared with a real instrument's.
  - [Mx.Measure.Strokes](Mx.Measure.Strokes.md): Measures recordings of an instrument played in strokes that run into one another, such as the rubs of a cuíca's stick, so a synth can play a stroke back as it was measured.

- Scores
  - [Mx.ABC](Mx.ABC.md): Reads ABC notation written one system of music at a time, and writes the systems out as one MusicXML score.
  - [Mx.Audiveris](Mx.Audiveris.md): Runs Audiveris, the optical music recognition program, on page images, and gathers the MusicXML it writes for each page into one score.
  - [Mx.Hum](Mx.Hum.md): Turns a recording of one voice humming, singing or whistling a melody into notes on beats, and writes them as a song.
  - [Mx.Notation](Mx.Notation.md): Small helpers a song's functions use to choose and tune notes: stepping through a list, drawing seeded random numbers, and intervals in cents or ratios.

  - [Mx.Scan](Mx.Scan.md): Prepares scanned score pages for optical music recognition by Audiveris.
  - [Mx.Score](Mx.Score.md): A MusicXML score read into parts of bars, each bar a list of voices and each voice a list of notes and rests in order.
  - [Mx.Transcriber](Mx.Transcriber.md): Transcribes images of single systems of printed music to ABC notation with a vision-language model, which `Mx.ABC` turns into a score.
  - [Mx.Hum.Recorder](Mx.Hum.Recorder.md): Records a hum against a click and turns it into a song, for `mix mx.hum --record`.

## Mix Tasks

- [mix mx.fit](Mix.Tasks.Mx.Fit.md): Searches for the values of a synth's controls that bring its held notes closest to recordings of them, as `Mx.Fit` describes.
- [mix mx.hum](Mix.Tasks.Mx.Hum.md): Reads a recording of one voice humming, singing or whistling a melody, and writes it as a song beside the recording.
- [mix mx.import](Mix.Tasks.Mx.Import.md): Reads a MusicXML score and writes it as a song beside it, one part per part of the score, that plays the whole score once.
- [mix mx.measure](Mix.Tasks.Mx.Measure.md): Measures recordings of single notes, plucked or struck, and prints the median fade time and level of their harmonics in each frequency band.
- [mix mx.page](Mix.Tasks.Mx.Page.md): Writes a song file as one HTML page, which plays the song's render and shows each part's notes on a timeline.
- [mix mx.play](Mix.Tasks.Mx.Play.md): Plays the loops a song file describes until Enter is pressed, or until the song's music ends.
- [mix mx.print](Mix.Tasks.Mx.Print.md): Prints each part's notes with their beats from the start of the song, through the whole of its music once, and makes no sound.
Given `--pass`, it prints that pass of each part, a pass being a section, or the length of the longest loop in music that plays until mx stops.
- [mix mx.samples.download](Mix.Tasks.Mx.Samples.Download.md): Downloads a collection of samples into the user's cache, so songs play them with no network access.
- [mix mx.scan](Mix.Tasks.Mx.Scan.md): Prepares the pages of a scanned score, reads the music on them with Audiveris or with a transcription model, and writes it as MusicXML beside the scan, ready for `mix mx.import`.
- [mix mx.spectrogram](Mix.Tasks.Mx.Spectrogram.md): Draws a spectrogram of a WAV or AIFF recording into a PNG image, with seconds across and octaves up the side.