### Configure and Get Sample Rate

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Use `WM8904_SetFrequency` to change the sample rate at runtime. `WM8904_GetFrequency` retrieves the current rate, returning the lower value of a paired rate. Ensure MCLK is externally configured for the desired rate.

```c
/* Switch sample rate at runtime */
if (WM8904_SetFrequency(&AudioObj, WM8904_FREQUENCY_44K) != WM8904_OK)
{
    Error_Handler();
}

uint32_t freq = 0;
WM8904_GetFrequency(&AudioObj, &freq);
/* freq == WM8904_FREQUENCY_44K (44100) */

/* Supported frequency constants:
   WM8904_FREQUENCY_8K   =   8000
   WM8904_FREQUENCY_11K  =  11025
   WM8904_FREQUENCY_16K  =  16000
   WM8904_FREQUENCY_22K  =  22050
   WM8904_FREQUENCY_24K  =  24000
   WM8904_FREQUENCY_32K  =  32000
   WM8904_FREQUENCY_44K  =  44100
   WM8904_FREQUENCY_48K  =  48000   */
```

--------------------------------

### WM8904_Play

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Unmutes the audio outputs and starts the audio stream on the WM8904 codec. This function should be called after the SAI/I2S peripheral and DMA have been started.

```APIDOC
## WM8904_Play

### Description
Unmutes outputs and starts the audio stream. Clears the DAC soft mute bit for headphone output and removes the analog input mute for the active input device (MIC1, LINE2, or DMIC). For digital microphone input, the ADC digital volume is restored to +17.6 dB. This is typically called after the SAI/I2S peripheral has been started and DMA is running.

### Function Signature
`int32_t WM8904_Play(WM8904_Type *AudioObj)`

### Parameters
- **AudioObj** (*WM8904_Type*)
  - Pointer to the WM8904 codec instance structure.

### Return Value
- `WM8904_OK` on success.
- `WM8904_ERROR` on failure.

### Example
```c
/* Start the SAI/I2S DMA transfer first */
HAL_SAI_Transmit_DMA(&hsai_BlockA1, (uint8_t *)AudioBuffer, AUDIO_BUFFER_SIZE);

/* Then unmute the codec */
if (WM8904_Play(&AudioObj) != WM8904_OK)
{
    Error_Handler();
}
```
```

--------------------------------

### Start WM8904 audio playback

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Unmutes the headphone output and active input paths, and restores digital microphone volume. Call this after the SAI/I2S peripheral and DMA have been started.

```c
/* Start the SAI/I2S DMA transfer first */
HAL_SAI_Transmit_DMA(&hsai_BlockA1, (uint8_t *)AudioBuffer, AUDIO_BUFFER_SIZE);

/* Then unmute the codec */
if (WM8904_Play(&AudioObj) != WM8904_OK)
{
    Error_Handler();
}
```

--------------------------------

### WM8904_ReadID

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Verifies the identity of the WM8904 codec by reading its device ID. This is crucial for confirming bus connectivity after initialization and before starting audio operations.

```APIDOC
## WM8904_ReadID

### Description
Verifies codec identity by reading the SW_RESET register (address 0x0000), which returns the device ID `0x8904` on a correctly functioning WM8904. Call this after `WM8904_RegisterBusIO` but before `WM8904_Init` to confirm bus connectivity.

### Function Signature
`int32_t WM8904_ReadID(WM8904_Type *AudioObj, uint32_t *chipID)`

### Parameters
- **AudioObj** (*WM8904_Type*)
  - Pointer to the WM8904 codec instance structure.
- **chipID** (*uint32_t*)
  - Pointer to a variable where the read chip ID will be stored.

### Return Value
- `WM8904_OK` on success.
- `WM8904_ERROR` if the I2C transaction fails.

### Example
```c
uint32_t chipID = 0;
if (WM8904_ReadID(&AudioObj, &chipID) != WM8904_OK)
{
    /* I2C transaction failed */
    Error_Handler();
}
if ((chipID & WM8904_ID_MASK) != WM8904_ID)   /* WM8904_ID = 0x8904 */
{
    /* Unexpected device on the bus */
    Error_Handler();
}
/* chipID == 0x8904 — WM8904 confirmed */
```
```

--------------------------------

### Set and get WM8904 headphone volume

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Controls the headphone output volume on a 0-100 linear scale, converting it to the codec's register values. Supports only output volume; input volume is not supported.

```c
/* Set output volume to 75% */
if (WM8904_SetVolume(&AudioObj, VOLUME_OUTPUT, 75U) != WM8904_OK)
{
    Error_Handler();
}

/* Read back the current volume */
uint8_t currentVolume = 0;
if (WM8904_GetVolume(&AudioObj, VOLUME_OUTPUT, &currentVolume) == WM8904_OK)
{
    /* currentVolume is in range 0–100 */
    printf("Volume: %d%%\n", currentVolume);
}

/* Ramp volume from 0 to 80 over 800 ms */
for (uint8_t vol = 0; vol <= 80U; vol++)
{
    WM8904_SetVolume(&AudioObj, VOLUME_OUTPUT, vol);
    HAL_Delay(10U);
}
```

--------------------------------

### WM8904_Init

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Initializes the WM8904 audio codec with specified input, output, frequency, resolution, and volume settings. It performs a hardware reset and a power-up sequence, configuring the codec for audio operation.

```APIDOC
## WM8904_Init — Initialize the codec with input, output, frequency, resolution, and volume

### Description
Performs a full hardware reset followed by a precise power-up sequence: bias/VMID ramp, microphone bias, DAC/ADC enable, charge pump, headphone output path, and DC servo startup. The codec is configured for the requested input device, output device, sample rate, and initial volume. If the object was already initialized, it is cleanly de-initialized first.

### Function Signature
```c
int32_t WM8904_Init(WM8904_Object_t *CodecObj, WM8904_Init_t *Init);
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters (for `WM8904_Init_t` struct)
- **InputDevice** (WM8904_Input_t) - Specifies the audio input source (e.g., `WM8904_IN_MIC1`, `WM8904_IN_LINE2`, `WM8904_IN_DIGITAL_MIC2`).
- **OutputDevice** (WM8904_Output_t) - Specifies the audio output path (e.g., `WM8904_OUT_HEADPHONE`, `WM8904_OUT_NONE`).
- **Frequency** (WM8904_Frequency_t) - Sets the audio sample rate (e.g., `WM8904_FREQUENCY_48K`, `WM8904_FREQUENCY_44K`, `WM8904_FREQUENCY_16K`).
- **Resolution** (WM8904_Resolution_t) - Configures the audio data resolution (e.g., `WM8904_RESOLUTION_16B`).
- **Volume** (uint8_t) - Sets the initial output volume on a scale of 0 to 100.

### Request Example
```c
WM8904_Init_t AudioInit = {
    .InputDevice  = WM8904_IN_MIC1,           /* Analog microphone on IN1L */
    .OutputDevice = WM8904_OUT_HEADPHONE,     /* Headphone output */
    .Frequency    = WM8904_FREQUENCY_48K,     /* 48 kHz sample rate */
    .Resolution   = WM8904_RESOLUTION_16B,    /* 16-bit word length */
    .Volume       = 70U,                      /* 0–100 scale */
};

int32_t ret = WM8904_Init(&AudioObj, &AudioInit);
if (ret != WM8904_OK)
{
    /* Initialization failed — check I2C bus, power supply, MCLK */
    Error_Handler();
}
/* Codec is now powered and ready; audio data can be fed via SAI/I2S */

/* --- Alternative: LINE2 stereo input at 44.1 kHz ----------------------- */
WM8904_Init_t LineInit = {
    .InputDevice  = WM8904_IN_LINE2,
    .OutputDevice = WM8904_OUT_HEADPHONE,
    .Frequency    = WM8904_FREQUENCY_44K,
    .Resolution   = WM8904_RESOLUTION_16B,
    .Volume       = 80U,
};
WM8904_Init(&AudioObj, &LineInit);

/* --- Alternative: Digital microphone (DMIC) at 16 kHz ----------------- */
WM8904_Init_t DmicInit = {
    .InputDevice  = WM8904_IN_DIGITAL_MIC2,   /* DMICDAT2 / IN1R pin */
    .OutputDevice = WM8904_OUT_NONE,
    .Frequency    = WM8904_FREQUENCY_16K,
    .Resolution   = WM8904_RESOLUTION_16B,
    .Volume       = 0U,
};
WM8904_Init(&AudioObj, &DmicInit);
/* DRC is automatically enabled for DMIC path; GPIO1 drives the DMIC clock */
```

### Response
#### Success Response (0)
Indicates successful initialization of the WM8904 codec.

#### Error Response (-1)
Indicates an error during codec initialization. This could be due to issues with the I2C bus, power supply, or MCLK signal.

### Return Value
- `WM8904_OK` (0): Success.
- `WM8904_ERROR` (-1): Failure.
```

--------------------------------

### Query Audio Interface Resolution and Protocol

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Retrieve audio interface settings using `WM8904_GetResolution` and `WM8904_GetProtocol`. `GetResolution` returns a 4-bit constant for bit depth, while `GetProtocol` returns a 2-bit constant for the data format. The corresponding setters are currently unimplemented.

```c
uint32_t resolution = 0;
if (WM8904_GetResolution(&AudioObj, &resolution) == WM8904_OK)
{
    switch (resolution)
    {
        case WM8904_RESOLUTION_16B: printf("16-bit\n");  break;
        case WM8904_RESOLUTION_20B: printf("20-bit\n");  break;
        case WM8904_RESOLUTION_24B: printf("24-bit\n");  break;
        case WM8904_RESOLUTION_32B: printf("32-bit\n");  break;
    }
}

uint32_t protocol = 0;
if (WM8904_GetProtocol(&AudioObj, &protocol) == WM8904_OK)
{
    /* WM8904_PROTOCOL_I2S         = 0x0002 (default after Init)
       WM8904_PROTOCOL_L_JUSTIFIED = 0x0001
       WM8904_PROTOCOL_R_JUSTIFIED = 0x0000
       WM8904_PROTOCOL_DSP         = 0x0003 */
    printf("Protocol register value: 0x%04lX\n", protocol);
}
```

--------------------------------

### Initialize WM8904 Codec for Audio Playback/Recording

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Initializes the WM8904 codec with specified input, output, frequency, resolution, and volume. Handles hardware reset and power-up sequencing. If the object is already initialized, it will be de-initialized first. Ensure the bus is registered before calling this function.

```c
WM8904_Init_t AudioInit = {
    .InputDevice  = WM8904_IN_MIC1,           /* Analog microphone on IN1L */
    .OutputDevice = WM8904_OUT_HEADPHONE,     /* Headphone output */
    .Frequency    = WM8904_FREQUENCY_48K,     /* 48 kHz sample rate */
    .Resolution   = WM8904_RESOLUTION_16B,    /* 16-bit word length */
    .Volume       = 70U,                      /* 0–100 scale */
};

int32_t ret = WM8904_Init(&AudioObj, &AudioInit);
if (ret != WM8904_OK)
{
    /* Initialization failed — check I2C bus, power supply, MCLK */
    Error_Handler();
}
/* Codec is now powered and ready; audio data can be fed via SAI/I2S */
```

```c
/* --- Alternative: LINE2 stereo input at 44.1 kHz ----------------------- */
WM8904_Init_t LineInit = {
    .InputDevice  = WM8904_IN_LINE2,
    .OutputDevice = WM8904_OUT_HEADPHONE,
    .Frequency    = WM8904_FREQUENCY_44K,
    .Resolution   = WM8904_RESOLUTION_16B,
    .Volume       = 80U,
};
WM8904_Init(&AudioObj, &LineInit);
```

```c
/* --- Alternative: Digital microphone (DMIC) at 16 kHz ----------------- */
WM8904_Init_t DmicInit = {
    .InputDevice  = WM8904_IN_DIGITAL_MIC2,   /* DMICDAT2 / IN1R pin */
    .OutputDevice = WM8904_OUT_NONE,
    .Frequency    = WM8904_FREQUENCY_16K,
    .Resolution   = WM8904_RESOLUTION_16B,
    .Volume       = 0U,
};
WM8904_Init(&AudioObj, &DmicInit);
/* DRC is automatically enabled for DMIC path; GPIO1 drives the DMIC clock */
```

--------------------------------

### Polymorphic Driver Interface (vtable)

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

The `WM8904_Driver` vtable provides a codec-agnostic interface through function pointers, adhering to the STM32 BSP component driver convention. Board BSPs can assign this vtable to an `AUDIO_Drv_t *` pointer for unified codec control.

```c
/* Board BSP layer — codec-agnostic usage via vtable */
AUDIO_Drv_t    *pAudioDrv  = (AUDIO_Drv_t *)&WM8904_Driver;
WM8904_Object_t AudioObj   = {0};

/* Register I/O */
WM8904_RegisterBusIO(&AudioObj, &AudioIO);

/* Use the vtable for all operations */
pAudioDrv->Init(&AudioObj, &AudioInit);
pAudioDrv->SetVolume(&AudioObj, VOLUME_OUTPUT, 80U);
pAudioDrv->Play(&AudioObj);
pAudioDrv->Pause(&AudioObj);
pAudioDrv->Resume(&AudioObj);
pAudioDrv->Stop(&AudioObj, WM8904_PDWN_SW);
pAudioDrv->DeInit(&AudioObj);
```

--------------------------------

### WM8904_SetFrequency / WM8904_GetFrequency

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Configure and query the audio sample rate. `SetFrequency` writes to the CLOCK_RATES1 register, and `GetFrequency` retrieves the current rate, returning the lower value for paired rates.

```APIDOC
## WM8904_SetFrequency / WM8904_GetFrequency — Configure sample rate

### Description
Writes the CLOCK_RATES1 register to select one of twelve supported sample rates. Paired rates (e.g., 44.1 kHz and 48 kHz) share the same register value; `GetFrequency` returns the lower of the pair in such cases. The MCLK source must be configured externally to derive the correct system clock for the chosen rate.

### Usage
```c
/* Switch sample rate at runtime */
if (WM8904_SetFrequency(&AudioObj, WM8904_FREQUENCY_44K) != WM8904_OK)
{
    Error_Handler();
}

uint32_t freq = 0;
WM8904_GetFrequency(&AudioObj, &freq);
/* freq == WM8904_FREQUENCY_44K (44100) */
```

### Supported Frequencies
- WM8904_FREQUENCY_8K   =   8000
- WM8904_FREQUENCY_11K  =  11025
- WM8904_FREQUENCY_16K  =  16000
- WM8904_FREQUENCY_22K  =  22050
- WM8904_FREQUENCY_24K  =  24000
- WM8904_FREQUENCY_32K  =  32000
- WM8904_FREQUENCY_44K  =  44100
- WM8904_FREQUENCY_48K  =  48000
```

--------------------------------

### Power down WM8904 codec gracefully

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Reverses the power-up sequence to safely shut down the codec. Leaves IsInitialized set to 0. Ensure communication is successful during power-down.

```c
int32_t ret = WM8904_DeInit(&AudioObj);
if (ret != WM8904_OK)
{
    /* Communication error during power-down */
    Error_Handler();
}
/* AudioObj.IsInitialized == 0; bus callbacks still registered */
```

--------------------------------

### WM8904_GetResolution / WM8904_GetProtocol

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Query the audio interface configuration, specifically the bit resolution and data transfer protocol. These functions read from the AUDIO_INTERFACE1 register.

```APIDOC
## WM8904_GetResolution / WM8904_GetProtocol — Query audio interface configuration

### Description
Both getters read the AUDIO_INTERFACE1 register. `GetResolution` decodes bits [3:2] and returns one of the four `WM8904_RESOLUTION_*` constants. `GetProtocol` returns bits [1:0] as one of the four `WM8904_PROTOCOL_*` constants. The matching setters (`SetResolution`, `SetProtocol`) are stubbed and return `WM8904_ERROR` in the current release.

### Usage
```c
uint32_t resolution = 0;
if (WM8904_GetResolution(&AudioObj, &resolution) == WM8904_OK)
{
    switch (resolution)
    {
        case WM8904_RESOLUTION_16B: printf("16-bit\n");  break;
        case WM8904_RESOLUTION_20B: printf("20-bit\n");  break;
        case WM8904_RESOLUTION_24B: printf("24-bit\n");  break;
        case WM8904_RESOLUTION_32B: printf("32-bit\n");  break;
    }
}

uint32_t protocol = 0;
if (WM8904_GetProtocol(&AudioObj, &protocol) == WM8904_OK)
{
    /* WM8904_PROTOCOL_I2S         = 0x0002 (default after Init)
       WM8904_PROTOCOL_L_JUSTIFIED = 0x0001
       WM8904_PROTOCOL_R_JUSTIFIED = 0x0000
       WM8904_PROTOCOL_DSP         = 0x0003 */
    printf("Protocol register value: 0x%04lX\n", protocol);
}
```
```

--------------------------------

### Register Bus I/O Callbacks for WM8904

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Binds platform-specific I2C/SPI callbacks and device address to a WM8904 codec object. This must be called before any other WM8904 functions. Ensure the I2C bus is initialized and the correct device address is provided.

```c
#include "wm8904.h"

/* Platform-specific I2C callbacks (provided by the BSP board layer) */
static int32_t I2C_Init(void)       { return BSP_I2C_Init();  }
static int32_t I2C_DeInit(void)     { return BSP_I2C_DeInit(); }
static int32_t I2C_GetTick(void)    { return (int32_t)HAL_GetTick(); }

static int32_t I2C_WriteReg(uint16_t addr, uint16_t reg,
                             uint8_t *pData, uint16_t len)
{
    return BSP_I2C_WriteReg16(addr, reg, pData, len);
}
static int32_t I2C_ReadReg(uint16_t addr, uint16_t reg,
                            uint8_t *pData, uint16_t len)
{
    return BSP_I2C_ReadReg16(addr, reg, pData, len);
}

WM8904_Object_t  AudioObj  = {0};
WM8904_IO_t      AudioIO   = {
    .Init     = I2C_Init,
    .DeInit   = I2C_DeInit,
    .Address  = 0x34U,   /* WM8904 I2C address (ADDR pin = GND) */
    .WriteReg = I2C_WriteReg,
    .ReadReg  = I2C_ReadReg,
    .GetTick  = I2C_GetTick,
};

if (WM8904_RegisterBusIO(&AudioObj, &AudioIO) != WM8904_OK)
{
    /* Handle bus registration error */
    Error_Handler();
}
```

--------------------------------

### WM8904_RegisterBusIO

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Binds platform-specific I2C/SPI callbacks and the device address to a codec object. This function must be called before any other WM8904 driver functions to initialize the communication bus.

```APIDOC
## WM8904_RegisterBusIO — Bind platform I/O callbacks to a codec object

### Description
Before any other function is called, the application must supply platform-specific I2C/SPI callbacks and the device address via `WM8904_IO_t`. This function populates the internal context and calls the user-supplied `Init` callback to bring up the bus.

### Function Signature
```c
int32_t WM8904_RegisterBusIO(WM8904_Object_t *CodecObj, WM8904_IO_t *IO);
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters (for `WM8904_IO_t` struct)
- **Init** (function pointer) - Callback function to initialize the I2C/SPI bus.
- **DeInit** (function pointer) - Callback function to de-initialize the I2C/SPI bus.
- **Address** (uint16_t) - The I2C address of the WM8904 codec.
- **WriteReg** (function pointer) - Callback function to write data to a codec register.
- **ReadReg** (function pointer) - Callback function to read data from a codec register.
- **GetTick** (function pointer) - Callback function to get the current tick value.

### Request Example
```c
#include "wm8904.h"

/* Platform-specific I2C callbacks (provided by the BSP board layer) */
static int32_t I2C_Init(void)       { return BSP_I2C_Init();  }
static int32_t I2C_DeInit(void)     { return BSP_I2C_DeInit(); }
static int32_t I2C_GetTick(void)    { return (int32_t)HAL_GetTick(); }

static int32_t I2C_WriteReg(uint16_t addr, uint16_t reg,
                             uint8_t *pData, uint16_t len)
{
    return BSP_I2C_WriteReg16(addr, reg, pData, len);
}
static int32_t I2C_ReadReg(uint16_t addr, uint16_t reg,
                            uint8_t *pData, uint16_t len)
{
    return BSP_I2C_ReadReg16(addr, reg, pData, len);
}

WM8904_Object_t  AudioObj  = {0};
WM8904_IO_t      AudioIO   = {
    .Init     = I2C_Init,
    .DeInit   = I2C_DeInit,
    .Address  = 0x34U,   /* WM8904 I2C address (ADDR pin = GND) */
    .WriteReg = I2C_WriteReg,
    .ReadReg  = I2C_ReadReg,
    .GetTick  = I2C_GetTick,
};

if (WM8904_RegisterBusIO(&AudioObj, &AudioIO) != WM8904_OK)
{
    /* Handle bus registration error */
    Error_Handler();
}
```

### Response
#### Success Response (0)
Indicates successful registration of the bus I/O callbacks.

#### Error Response (-1)
Indicates an error during bus registration.

### Return Value
- `WM8904_OK` (0): Success.
- `WM8904_ERROR` (-1): Failure.
```

--------------------------------

### WM8904_Driver vtable

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

The polymorphic driver interface exposed through the `WM8904_Driver` vtable, allowing for codec-agnostic application code by using function pointers.

```APIDOC
## WM8904_Driver vtable — Polymorphic driver interface

### Description
The global `WM8904_Drv_t WM8904_Driver` structure exposes all public functions as function pointers, following the STM32 BSP component driver convention. Board-level BSP drivers assign this vtable to an `AUDIO_Drv_t *` pointer, enabling codec-agnostic application code.

### Usage
```c
/* Board BSP layer — codec-agnostic usage via vtable */
AUDIO_Drv_t    *pAudioDrv  = (AUDIO_Drv_t *)&WM8904_Driver;
WM8904_Object_t AudioObj   = {0};

/* Register I/O */
WM8904_RegisterBusIO(&AudioObj, &AudioIO);

/* Use the vtable for all operations */
pAudioDrv->Init(&AudioObj, &AudioInit);
pAudioDrv->SetVolume(&AudioObj, VOLUME_OUTPUT, 80U);
pAudioDrv->Play(&AudioObj);
pAudioDrv->Pause(&AudioObj);
pAudioDrv->Resume(&AudioObj);
pAudioDrv->Stop(&AudioObj, WM8904_PDWN_SW);
pAudioDrv->DeInit(&AudioObj);
```
```

--------------------------------

### WM8904_Reset

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Perform a software reset of all codec registers, restoring them to their default values. This function is also called automatically during `WM8904_Init`.

```APIDOC
## WM8904_Reset — Software reset of all codec registers

### Description
Writes 0x0000 to the SW_RESET register (address 0x0000), restoring all internal registers to their default values. This is also performed automatically at the start of `WM8904_Init`. After a manual reset, the full `WM8904_Init` sequence must be run again.

### Usage
```c
if (WM8904_Reset(&AudioObj) != WM8904_OK)
{
    Error_Handler();
}
/* All codec registers are now at power-on defaults */
WM8904_Init(&AudioObj, &AudioInit);
```
```

--------------------------------

### WM8904_Pause / WM8904_Resume

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Allows suspending and resuming audio playback without reinitializing the codec. `WM8904_Pause` mutes the audio paths, while `WM8904_Resume` restores them, preserving the codec's register state.

```APIDOC
## WM8904_Pause / WM8904_Resume

### Description
Suspend and resume audio without reinitializing. `WM8904_Pause` asserts the soft mute on the active DAC and analog input paths. `WM8904_Resume` clears the mute, restoring the previously configured volume. Codec register state is preserved; no re-initialization is needed.

### Function Signatures
`int32_t WM8904_Pause(WM8904_Type *AudioObj)`
`int32_t WM8904_Resume(WM8904_Type *AudioObj)`

### Parameters
- **AudioObj** (*WM8904_Type*)
  - Pointer to the WM8904 codec instance structure.

### Return Value
- `WM8904_OK` on success.
- `WM8904_ERROR` on failure.

### Example
```c
/* User presses pause button */
if (WM8904_Pause(&AudioObj) != WM8904_OK) { Error_Handler(); }

/* ... later, user presses play ... */
if (WM8904_Resume(&AudioObj) != WM8904_OK) { Error_Handler(); }
```
```

--------------------------------

### Verify WM8904 codec identity

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Reads the SW_RESET register to confirm the device ID is 0x8904. Call after bus registration and before initialization to check connectivity. Handles I2C transaction failures and unexpected device IDs.

```c
uint32_t chipID = 0;
if (WM8904_ReadID(&AudioObj, &chipID) != WM8904_OK)
{
    /* I2C transaction failed */
    Error_Handler();
}
if ((chipID & WM8904_ID_MASK) != WM8904_ID)   /* WM8904_ID = 0x8904 */
{
    /* Unexpected device on the bus */
    Error_Handler();
}
/* chipID == 0x8904 — WM8904 confirmed */
```

--------------------------------

### WM8904_SetMute / WM8904_SetOutputMode

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Manages mute states and output routing for the WM8904 codec. `WM8904_SetMute` controls muting on all active paths, while `WM8904_SetOutputMode` is documented but currently unsupported.

```APIDOC
## WM8904_SetMute / WM8904_SetOutputMode

### Description
Mute control and output routing. `WM8904_SetMute` enables or disables the mute on all active paths simultaneously (DAC for headphone, analog mute for MIC1/LINE2, digital volume mute for DMIC). `WM8904_SetOutputMode` is defined in the driver interface but is currently unsupported and returns `WM8904_ERROR`.

### Function Signatures
`int32_t WM8904_SetMute(WM8904_Type *AudioObj, uint32_t muteState)`
`int32_t WM8904_SetOutputMode(WM8904_Type *AudioObj, uint32_t outputMode)`

### Parameters
- **AudioObj** (*WM8904_Type*)
  - Pointer to the WM8904 codec instance structure.
- **muteState** (*uint32_t*)
  - For `SetMute`: State to set. Accepts `WM8904_MUTE_ON` or `WM8904_MUTE_OFF`.
- **outputMode** (*uint32_t*)
  - For `SetOutputMode`: Desired output mode (e.g., `WM8904_OUT_LINE`). This parameter is currently unused as the function is unsupported.

### Return Value
- `WM8904_OK` for `SetMute` on success.
- `WM8904_ERROR` for `SetMute` on failure, or always for `SetOutputMode`.

### Example
```c
/* Mute all active paths */
WM8904_SetMute(&AudioObj, WM8904_MUTE_ON);

/* Unmute */
WM8904_SetMute(&AudioObj, WM8904_MUTE_OFF);

/* Output mode switching is not supported in this driver version */
int32_t ret = WM8904_SetOutputMode(&AudioObj, WM8904_OUT_LINE);
if (ret == WM8904_ERROR)
{
    /* Expected: feature not supported */
}
```
```

--------------------------------

### Low-Level Register Access

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Utilize `wm8904_write_reg` and `wm8904_read_reg` for direct access to codec registers. These functions handle byte-order conversion and are available for advanced control or debugging. They are called internally by high-level driver functions.

```c
/* Direct register write — example: force DAC left digital volume to +0 dB */
wm8904_ctx_t *ctx = &AudioObj.Ctx;
uint16_t val = 0x00C0U;  /* DAC_VU=1, DAC_VOL=0xC0 (+0 dB) */
int32_t  ret = wm8904_write_reg(ctx, WM8904_DAC_DIGITAL_VOL_LEFT, &val, 2U);

/* Direct register read — example: inspect interrupt status */
uint16_t irqStatus = 0;
ret = wm8904_read_reg(ctx, WM8904_INTERRUPT_STATUS, &irqStatus, 2U);
if (ret == WM8904_OK)
{
    printf("IRQ status: 0x%04X\n", irqStatus);
}
```

--------------------------------

### WM8904_DeInit

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Powers down the WM8904 codec gracefully by reversing the power-up sequence. This function disables various components and ramps down biases, leaving the device in an uninitialized state.

```APIDOC
## WM8904_DeInit

### Description
Powers down the codec gracefully by reversing the power-up sequence: removes headphone shorts, disables the DC servo, turns off the charge pump, powers down DAC/ADC, disables the PGA, disables microphone bias, and ramps down VMID and master bias. Leaves `IsInitialized = 0`.

### Function Signature
`int32_t WM8904_DeInit(WM8904_Type *AudioObj)`

### Parameters
- **AudioObj** (*WM8904_Type*)
  - Pointer to the WM8904 codec instance structure.

### Return Value
- `WM8904_OK` on success.
- `WM8904_ERROR` on communication error during power-down.

### Example
```c
int32_t ret = WM8904_DeInit(&AudioObj);
if (ret != WM8904_OK)
{
    /* Communication error during power-down */
    Error_Handler();
}
/* AudioObj.IsInitialized == 0; bus callbacks still registered */
```
```

--------------------------------

### WM8904_Stop

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Stops audio playback with two selectable power-down modes. `WM8904_PDWN_SW` performs a soft stop, preserving register state for quick resumption. `WM8904_PDWN_HW` performs a hard stop, fully powering down the codec and requiring re-initialization.

```APIDOC
## WM8904_Stop

### Description
Stops playback with selectable power-down mode. `WM8904_PDWN_SW` mutes the codec (soft stop) while keeping all registers intact, allowing resumption without re-initialization. `WM8904_PDWN_HW` additionally calls `WM8904_DeInit`, fully powering down the codec; `WM8904_Init` must be called again before next use.

### Function Signature
`int32_t WM8904_Stop(WM8904_Type *AudioObj, uint32_t pdwnMode)`

### Parameters
- **AudioObj** (*WM8904_Type*)
  - Pointer to the WM8904 codec instance structure.
- **pdwnMode** (*uint32_t*)
  - Power-down mode. Accepts `WM8904_PDWN_SW` (soft stop) or `WM8904_PDWN_HW` (hard stop).

### Return Value
- `WM8904_OK` on success.
- `WM8904_ERROR` on failure.

### Example
```c
/* Soft stop — registers intact, fast resume */
WM8904_Stop(&AudioObj, WM8904_PDWN_SW);

/* Hard stop — full power-down, must re-init before next play */
WM8904_Stop(&AudioObj, WM8904_PDWN_HW);
/* Re-initialize when needed: */
WM8904_Init(&AudioObj, &AudioInit);
WM8904_Play(&AudioObj);
```
```

--------------------------------

### wm8904_write_reg / wm8904_read_reg

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Low-level functions for direct read and write access to WM8904 registers. These functions handle byte-order conversion and are available for advanced use cases.

```APIDOC
## wm8904_write_reg / wm8904_read_reg — Low-level register access (register layer)

### Description
These functions in `wm8904_reg.c` form the transport layer. They perform big-endian ↔ host byte-order conversion on the 16-bit register values before dispatching through the `wm8904_ctx_t` function pointers. They are called internally by all high-level functions and are also available for direct register access when needed.

### Usage
```c
/* Direct register write — example: force DAC left digital volume to +0 dB */
wm8904_ctx_t *ctx = &AudioObj.Ctx;
uint16_t val = 0x00C0U;  /* DAC_VU=1, DAC_VOL=0xC0 (+0 dB) */
int32_t  ret = wm8904_write_reg(ctx, WM8904_DAC_DIGITAL_VOL_LEFT, &val, 2U);

/* Direct register read — example: inspect interrupt status */
uint16_t irqStatus = 0;
ret = wm8904_read_reg(ctx, WM8904_INTERRUPT_STATUS, &irqStatus, 2U);
if (ret == WM8904_OK)
{
    printf("IRQ status: 0x%04X\n", irqStatus);
}
```
```

--------------------------------

### WM8904_SetVolume / WM8904_GetVolume

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Controls the headphone output volume on a linear scale from 0 to 100. `WM8904_SetVolume` adjusts the volume, while `WM8904_GetVolume` retrieves the current setting.

```APIDOC
## WM8904_SetVolume / WM8904_GetVolume

### Description
Control headphone output volume on a 0–100 linear scale. The driver converts this to the codec's 6-bit register field (range 13–63, i.e., approximately −54 dB to 0 dB) using the macro `VOLUME_OUT_CONVERT`. Only `VOLUME_OUTPUT` is supported; passing `VOLUME_INPUT` returns `WM8904_ERROR`.

### Function Signatures
`int32_t WM8904_SetVolume(WM8904_Type *AudioObj, uint32_t volumeType, uint8_t volume)`
`int32_t WM8904_GetVolume(WM8904_Type *AudioObj, uint32_t volumeType, uint8_t *volume)`

### Parameters
- **AudioObj** (*WM8904_Type*)
  - Pointer to the WM8904 codec instance structure.
- **volumeType** (*uint32_t*)
  - Type of volume to set/get. Accepts `VOLUME_OUTPUT`.
- **volume** (*uint8_t*)
  - For `SetVolume`: The desired volume level (0-100).
  - For `GetVolume`: Pointer to a variable to store the retrieved volume level (0-100).

### Return Value
- `WM8904_OK` on success.
- `WM8904_ERROR` if `volumeType` is not `VOLUME_OUTPUT` or on communication error.

### Example
```c
/* Set output volume to 75% */
if (WM8904_SetVolume(&AudioObj, VOLUME_OUTPUT, 75U) != WM8904_OK)
{
    Error_Handler();
}

/* Read back the current volume */
uint8_t currentVolume = 0;
if (WM8904_GetVolume(&AudioObj, VOLUME_OUTPUT, &currentVolume) == WM8904_OK)
{
    /* currentVolume is in range 0–100 */
    printf("Volume: %d%%\n", currentVolume);
}

/* Ramp volume from 0 to 80 over 800 ms */
for (uint8_t vol = 0; vol <= 80U; vol++)
{
    WM8904_SetVolume(&AudioObj, VOLUME_OUTPUT, vol);
    HAL_Delay(10U);
}
```
```

--------------------------------

### Perform Software Reset

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

The `WM8904_Reset` function resets all codec registers to their default values by writing to the SW_RESET register. This function is also called automatically during `WM8904_Init`. A manual reset requires re-running the `WM8904_Init` sequence.

```c
if (WM8904_Reset(&AudioObj) != WM8904_OK)
{
    Error_Handler();
}
/* All codec registers are now power-on defaults */
WM8904_Init(&AudioObj, &AudioInit);
```

--------------------------------

### Stop WM8904 playback with power-down options

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Stops audio playback. WM8904_PDWN_SW mutes the codec for a fast resume, while WM8904_PDWN_HW fully powers down the codec, requiring re-initialization.

```c
/* Soft stop — registers intact, fast resume */
WM8904_Stop(&AudioObj, WM8904_PDWN_SW);

/* Hard stop — full power-down, must re-init before next play */
WM8904_Stop(&AudioObj, WM8904_PDWN_HW);
/* Re-initialize when needed: */
WM8904_Init(&AudioObj, &AudioInit);
WM8904_Play(&AudioObj);
```

--------------------------------

### Mute WM8904 paths and control output mode

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Enables or disables muting on all active audio paths. The SetOutputMode function is defined but not supported in this driver version.

```c
/* Mute all active paths */
WM8904_SetMute(&AudioObj, WM8904_MUTE_ON);

/* Unmute */
WM8904_SetMute(&AudioObj, WM8904_MUTE_OFF);

/* Output mode switching is not supported in this driver version */
int32_t ret = WM8904_SetOutputMode(&AudioObj, WM8904_OUT_LINE);
if (ret == WM8904_ERROR)
{
    /* Expected: feature not supported */
}
```

--------------------------------

### Pause and resume WM8904 audio stream

Source: https://context7.com/stmicroelectronics/stm32-wm8904/llms.txt

Temporarily mutes and unmutes audio paths without reinitializing the codec. Register state and volume settings are preserved.

```c
/* User presses pause button */
if (WM8904_Pause(&AudioObj) != WM8904_OK) { Error_Handler(); }

/* ... later, user presses play ... */
if (WM8904_Resume(&AudioObj) != WM8904_OK) { Error_Handler(); }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.