# `Ascii.Pieces.Equalizer`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/pieces/equalizer.ex#L1)

Spectrum bars bouncing to a beat, peak caps falling slowly.

A spectrum analyser over a short drum and bass loop. Bars jump to each
band's level and sink back, and peak caps hold, then drop slowly. As
upstream draws it, it plays its own loop; give it `levels` and it shows
yours, from real audio.

## Options

Give them to `Ascii.new/2` as `options:`, and new ones while it plays
with `Ascii.put_options/2` (or a Phoenix player's `options`): the bars
carry on from where they were, jumping to the new levels and sinking
back, the caps holding and dropping, as they do to the loop.

  * `levels` - each band's level from 0 to 1, low to high, spread over
    the nineteen bars whatever their number. Default `[]`: upstream's
    loop.
  * `bpm` - the loop's tempo, 60 to 180. Default 120.

The frame is always 62 by 16.

## Colours

In one ink, or a gradient, with `:ink` and `:gradient` (see
`Ascii.Ink`); part by part with `:parts` (see `Ascii.Parts`),
`parts: true` taking the colours suggested here:

  * `bar` - the bars, by height as on a meter: `bar.low`, the bottom
    seven rows, green; `bar.mid`, the three above them, yellow; and
    `bar.high`, the top two, red.
  * `peak` - the caps.
  * `axis` - the axis, grey.
  * `scale` - the frequencies, grey.

## Keys and clicks

It takes none: it shows levels, and `Ascii.handle_event/2` ignores
every event. A Phoenix player given `interactive` and `notify` still tells
your LiveView where it was clicked, and on which part
(`Ascii.part_at/4`): a bar, or the `scale` under it.

## Screen readers

`Ascii.describe/1` reads the levels given, low to high, the first
eight then how many more: "equalizer: 3 levels, low to high: 100%, 50%,
25%". Playing its loop, it gives the piece's name and note.

## Example

```elixir
eq = Ascii.new!("equalizer", options: %{levels: [1.0, 0.5, 0.25]}, parts: true)

Ascii.describe(eq)
#=> "equalizer: 3 levels, low to high: 100%, 50%, 25%"

eq = Ascii.put_options!(eq, levels: [0.2, 0.9, 0.6])
Ascii.describe(eq)
#=> "equalizer: 3 levels, low to high: 20%, 90%, 60%"
```

```heex
<Ascii.Phoenix.live_player id="audio" piece="equalizer" options={%{levels: @levels}} parts />
```

Ported from `src/pieces/equalizer.ts` in bas3line/ascii (MIT).

---

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