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

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}`.

The pack is too large for the repository, so `download/1` fetches it from a fixed Sonic Pi release into a folder outside the repository, the user's cache by default.
Each file is written under a temporary name and renamed once complete, so an interrupted download never leaves a sample that looks downloaded.

# `check_cut`

Refuses options that cannot cut the sample `ref` at `path`, as `:ok` or `{:error, message}`.

# `check_github`

Refuses a GitHub sample's reference that is not `{:github, "owner/repo", ref, path}`, as `:ok` or `{:error, message}`.

# `cut`

Sample options with from, to, slices, slice and beats worked out into start, finish and rate, for a file of `seconds` played at `tempo`; options that cut nothing need no length.

# `cut_option?`

Whether an option cuts a sample or fits it to beats, which mx works out into the sample players' own options.

# `default_dir`

The folder in the user's cache the sample pack downloads to.

# `dir`

The folder the sample pack is in: the `:samples_dir` setting, or `default_dir/0`.

# `download`

Downloads the files of the pack that are missing, with its licence, and returns `{:ok, count}` or `{:error, file, reason, count}`.

# `download_source`

Downloads a collection ahead of time, for `mx samples download SOURCE` and `mix mx.samples.download SOURCE`, and returns `{:ok, message}` or `{:error, message}`.

SOURCE is `sonic_pi` for Sonic Pi's pack, or a GitHub repository as `owner/repo@ref`, optionally followed by `:folder` for only that folder.
Files already on disk are skipped, so running it again finishes an interrupted download.

# `level_warning`

The line mx prints when the song loads for a sample file played at `peak`, silent or too quiet to hear without normalize, or nil.

# `name`

How messages name a sample: by its name in the pack, its path, or its repository and path.

# `names`

The names of the files in Sonic Pi's sample pack, without their extension.

# `path`

The full path of a sample named as an atom from the pack, given as a file path, or of a GitHub repository, downloaded into the cache when it is not there yet, or `{:error, message}` saying why it cannot play.

# `peak`

The loudest moment of a sample file mx can play, as a level from 0, read from the whole file.

# `seconds`

The length in seconds of a sample file mx can play.

---

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