# Audio

How sound gets into and out of a Kode Dot through one codec, two buses, a microphone and a speaker, and why the speaker needs the second chip.

## What it is

Sound on the Kode Dot goes through one chip in both directions. A **codec**,
an ES8311, turns the microphone's analogue signal into numbers on the way in
and numbers back into a signal for the speaker on the way out. It is mono:
one microphone, one speaker, one channel each way.

The P4 talks to that codec over two buses, and keeping them apart is the
first thing to learn:

- **I2C** carries configuration: volume, gain, sample rate, on and off. It
  is the same shared bus as the rest of the board.
- **I2S** carries the audio itself: a stream of samples, in both directions
  at once, on its own five wires. I2S is built for exactly this, a clock
  and a word-select line that keep every sample in step, so sound crosses
  it without loss or jitter.

On the way out there is one more part. The codec's output is a line-level
signal, too weak for a speaker, so a small class-D **amplifier** sits
between them. Its enable pin is on the Kode Dot's other chip, the ESP32-C5,
which is the one fact on this page that explains most silent boards.

## How it is connected

```mermaid
flowchart LR
  p4["ESP32-P4"] -- "I2C, 0x18" --> codec["ES8311 codec"]
  p4 <-- "I2S" --> codec
  mic["ZTS6211E microphone"] --> codec
  codec --> amp["NS4150B amplifier"] --> spk["Speaker"]
  c5["ESP32-C5"] -. "PA_CTRL, IO4" .-> amp
```

*Configuration over I2C, audio over I2S, and the amplifier's enable on the C5*

The codec answers at `0x18` on the shared I2C bus that `kode_bsp_init`
brings up. Audio runs over I2S on `GPIO33` (master clock), `GPIO34` (bit
clock), `GPIO37` (word select), `GPIO38` (P4 to codec) and `GPIO36` (codec
to P4). The microphone is wired straight into the codec's analogue input,
so it is not a device on any bus. The amplifier's enable, `PA_CTRL`, is
`IO4` on the C5: the P4 cannot raise it, and Kode's C5 firmware raises it at
boot.

## Apps that use it

On the marketplace, apps that put this part to work. Install one from
`start/first-app` and see it before you write a line.

- https://apps.kode.diy/app/3dc95a93-1b79-4bd2-bded-67b4d616bd9a
- https://apps.kode.diy/app/b3c74f9b-6250-459b-835c-5e352546f535
- https://apps.kode.diy/app/328951aa-5eb7-426c-8b29-1e3b0ac57c49
- https://apps.kode.diy/app/6e2bfa27-4f6a-45ba-beb2-444fa6044044
- https://apps.kode.diy/app/102d6357-d51f-4911-b75a-243c2c1a3093
- https://apps.kode.diy/app/b33fa9d4-e0b9-4522-b5cd-65c565e06d43
- https://apps.kode.diy/app/f11ba199-e040-4403-ada1-135c21f189c7
- https://apps.kode.diy/app/7b60e571-9826-405f-8af5-3185899dfc74

## The parts

| Part | What it gives you | Page |
| --- | --- | --- |
| Speaker, through the codec's DAC and the NS4150B | Sound out: tones, notifications, playback | `device/audio/speaker` |
| Microphone, through the codec's ADC | Sound in: a level, a waveform, a recording | `device/audio/microphone` |

## Gotchas

> **NOTE**
>
> **The codec is mono.** The I2S channel is set up as stereo because that is
> what the peripheral expects, but only one channel of audio ever crosses it.
> Hand it a stereo file without mixing down first and you lose half of it.

## In the SDK

- [`kdrv_audio`](https://github.com/kodediy/kode-sdk/tree/main/components/kdrv/kdrv_audio): the ES8311 driver, a tone generator and a WAV reader in `kode-sdk`.