# `Cauldron2D.Net.Audio`
[🔗](https://github.com/jaman/cauldron/blob/v0.1.3/cauldron_2d_net/lib/cauldron_2d/net/audio.ex#L1)

The server's sound policy: what every session's sound costs it.

    Cauldron2D.Net.Audio.set(music: :arena, sfx: :personal)
    Cauldron2D.Net.Audio.set(music: :dynamic)
    Cauldron2D.Net.Audio.policy()

## Music

  * `:personal` — every session synthesises its own music, cued by its own view.
    Default
  * `:arena` — one stage a world (`Cauldron2D.Net.Audio.Shared`), cued by the world's
    state, its music mixed under each session's own effects
  * `:static` — every session plays the first section it is cued and no other,
    rendered once a node and looped (`Cauldron2D.Audio` with `static_music: true`):
    the music is a resource, not a performance, and costs a copy a chunk
  * `:dynamic` — personal, at a rate the node's load sets: 44 100 Hz while the
    schedulers are under 30% busy, 22 050 Hz once they pass 60%, each held for
    thirty seconds at least. A session whose rate changes restarts its audio and
    tells its browser
  * `:off` — no music

## Effects

  * `:personal` — each session's own, placed against its listener. Default
  * `:off` — none

A session that asks for no sound (join param `audio: false`) gets none whatever the
policy. `:rate` (default 44 100) caps the rate any session gets; a session asking
for less gets what it asked. `format/1` answers what a session gets for what it
asked; `subscribe/0` has the calling process told `{:cauldron_audio_rate, rate}`
when the rate changes.

# `format`

```elixir
@type format() :: %{rate: pos_integer(), channels: 1 | 2} | :off
```

# `music`

```elixir
@type music() :: :personal | :arena | :dynamic | :static | :off
```

# `policy`

```elixir
@type policy() :: %{music: music(), sfx: sfx(), rate: pos_integer()}
```

# `sfx`

```elixir
@type sfx() :: :personal | :off
```

# `format`

```elixir
@spec format(%{rate: pos_integer(), channels: 1 | 2} | :off | nil) :: format()
```

What a session gets for the format it asked, `:off` for no sound asked.

# `policy`

```elixir
@spec policy() :: policy()
```

The policy in force.

# `rate`

```elixir
@spec rate() :: pos_integer()
```

The rate sessions get now: the policy's, lowered by the governor under `:dynamic` music.

# `set`

```elixir
@spec set(keyword()) :: :ok
```

Set the policy: `:music`, `:sfx` and `:rate`; what is not given goes back to its default.

# `subscribe`

```elixir
@spec subscribe() :: :ok
```

Have the calling process told `{:cauldron_audio_rate, rate}` whenever the rate changes.

---

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