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

Plays a song's loops together, each in its own process, against one shared beat.

The band keeps the tempo timeline, as `Mx.Tempo` describes it.
Every loop works out the real time of its notes from that timeline, so loops of any length keep their place against the same beat.
A saved version with a new tempo starts it on the first whole beat after the notes already sent, so every loop changes on that beat.
The tempo changes a song's music writes go on the timeline when the first loop cues the pass they are in, before any loop sends a note of that pass.

When the song changes, a changed loop takes over at the end of its own pass, a new loop starts on the next beat, and a removed loop stops at the end of its pass, unless it is added back before then, when it takes over at that end as a changed loop does.
The band starts a loop again when its process fails.
Given `subscribe`, it subscribes to the inputs, and passes each one to the loops whose `on:` waits for it.
Each version's live audio goes to `live`, which starts, changes and stops it.
Each version of the song goes through `prepare` first, which loads its samples, so playing starts only once they are ready.
When every loop has played its last pass, the band calls `on_end`.
Given `from`, a beat of the song, each loop starts in the pass that holds that beat and plays it from there, so that beat sounds first; a loop whose passes end before it does not start.
A part a new version of a song written as music adds joins at the next section, with the pass number the other parts play there.
Every loop with a start beat is handed to `worked_out` with that beat before any loop works out a pass, so no loop's pass reads the shared values before the other loops' set steps are in.

# `beat_at`

The beat at a real time, in microseconds, on a timeline, as `Mx.Tempo.beat_at/2` works it out.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `cue`

Tells the band that the loop `name` starts a pass at `beat`, so the parts waiting to join start with it and the pass's tempo changes go on the timeline; returns the timeline.

# `loops`

The processes of the loops playing, stopping or waiting to join.

# `start_link`

Starts the band with the `:song` in `opts`, the `:play` function its notes go to the engine through, as `c:Mx.Engine.play/2` takes them, an optional `:new_id` as `c:Mx.Engine.new_id/0`, optional functions for samples, effects, inputs and live audio, and an optional `:name`.

# `switch`

Hands the band a new version of the song, which takes over loop by loop at the end of each one's pass.

# `tempo_at`

The tempo in beats per minute at a beat on a timeline, as `Mx.Tempo.tempo_at/2` works it out.

# `time_at`

The real time, in microseconds, of a beat on a timeline, as `Mx.Tempo.time_at/2` works it out.

# `timeline`

The tempo timeline, the latest entry first.

---

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