# `TuningFork.Kit`
[🔗](https://github.com/jaman/tuning_fork/blob/v0.1.0/tuning_fork/lib/tuning_fork/kit.ex#L1)

Names to voices: `voice/2` turns a drum name, a note name, a MIDI number, hertz or a map of
controls into a `TuningFork.Voice`.

    iex> %TuningFork.Voice{} = TuningFork.Kit.voice("bd", 0.25)
    iex> TuningFork.Kit.voice("nothing here", 0.25)
    nil

# `banks`

```elixir
@spec banks() :: [String.t()]
```

The sound banks `voice/2` knows, sorted.

    iex> "RolandTR909" in TuningFork.Kit.banks()
    true

A bank is not a set of recordings — nothing here is recorded — but a set of adjustments to
the drums this kit synthesises, so `bank("RolandTR808")` gives the long booming kick that
name is known for. A name it does not know changes nothing, so a pattern written for a bank
that is not here still plays.

# `drums`

```elixir
@spec drums() :: [String.t()]
```

The drum names `voice/2` knows, sorted.

# `families`

```elixir
@spec families() :: keyword([[String.t()]])
```

The drum names grouped by what they are, short name first.

    iex> TuningFork.Kit.families() |> Keyword.keys()
    [:kick, :snare, :hat, :tom, :cymbal, :percussion]

Names in the same group make the same sound; `"bd"` and `"kick"` are one entry.

# `from_map`

```elixir
@spec from_map(map(), number(), keyword()) :: TuningFork.Voice.t() | nil
```

A voice from a map of controls.

`:sound` or `:note` says what to play and is passed to `voice/2`; every other key changes the
voice that comes back. A map with neither is `nil`.

# `midi`

```elixir
@spec midi(term()) :: integer() | nil
```

The MIDI note a value stands for, or `nil` when it is not a pitch.

    iex> TuningFork.Kit.midi(%{degree: 4, scale: "g:minor"})
    62
    iex> TuningFork.Kit.midi(%{sound: "bd"})
    nil

A drum name has no pitch, so it is `nil`. `:octave` moves the root — 3 is where a scale sits
without one — and `:transpose` adds semitones after everything else.

# `notes`

```elixir
@spec notes() :: [String.t()]
```

Every note name `voice/2` takes, low to high.

A name is a letter, `s` for sharp or `b` for flat, and an octave: `c3`, `fs4`, `eb2`.

# `prefetch`

```elixir
@spec prefetch([term()]) :: :ok
```

Start fetching, in the background, every recording and soundfont the `values` would play.
Values are what `voice/3` takes; anything else is skipped. Returns at once.

# `voice`

```elixir
@spec voice(term(), number(), keyword()) :: TuningFork.Voice.t() | nil
```

The voice for `value`, lasting `seconds`.

Returns `nil` for a value naming nothing, so a pattern carrying words this kit does not have
plays the ones it does rather than failing.

## Options

  * `:wait` — whether to wait for a recording still being fetched from the web, default
    `true`; with `false` such a value is `nil` this time and the fetch carries on behind

---

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