### Play Specific WAV File from SD Card

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Stops current playback, sets a specific WAV file as the active track, and starts playback. The filename must be an absolute path (e.g., `/music/song.wav`) in ASCII with no spaces.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;
String musicList[100];

void setup() {
  Serial.begin(115200);
  amplifier.initI2S(GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);
  amplifier.initSDCard(GPIO_NUM_5);
  amplifier.scanSDMusic(musicList);

  // Play the second track from the scanned list
  if (musicList[1].length()) {
    amplifier.playSDMusic(musicList[1].c_str());
    // or use a hard-coded path:
    // amplifier.playSDMusic("/music/track02.wav");
  }
}
```

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

### Initialize I2S Driver Only

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Call this function to configure and install the I2S driver for audio output without initializing Bluetooth. This is suitable for scenarios where audio is driven solely from an SD card. Ensure the correct I2S GPIO pins are provided.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);

  // _bclk  – bit clock pin
  // _lrclk – left/right clock (word-select) pin
  // _din   – serial data pin
  while (!amplifier.initI2S(/*_bclk=*/GPIO_NUM_25,
                             /*_lrclk=*/GPIO_NUM_26,
                             /*_din=*/GPIO_NUM_27)) {
    Serial.println("I2S init failed!");
    delay(3000);
  }
  Serial.println("I2S ready.");
}
```

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

### Mount SPI SD Card and Initialize WAV Playback

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

This function mounts an SPI SD card and starts a FreeRTOS task for WAV file decoding and playback. Ensure the SD card is correctly wired to the ESP32, and specify the chip-select pin if it differs from the default GPIO 5.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);

  amplifier.initI2S(GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  // csPin – SPI chip-select pin for the SD card module (default GPIO 5)
  while (!amplifier.initSDCard(/*csPin=*/GPIO_NUM_5)) {
    Serial.println("SD card init failed – check wiring!");
    delay(3000);
  }
  Serial.println("SD card mounted.");
}
```

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

### Initialize Classic Bluetooth A2DP/AVRCP Only

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Use this function to start the Bluedroid stack and register Bluetooth callbacks independently of I2S initialization. This is useful when combining Bluetooth with a separately configured I2S bus. The device name for discovery must be specified.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);

  // Initialize I2S first, then Bluetooth separately
  amplifier.initI2S(GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  // _btName – name that appears in the phone's Bluetooth scan list
  if (!amplifier.initBluetooth("LivingRoomSpeaker")) {
    Serial.println("Bluetooth init failed!");
  } else {
    Serial.println("Discoverable as 'LivingRoomSpeaker'.");
  }
}
```

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

### Get Metadata via AVRCP

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Retrieves metadata (Title, Artist, Album) from a connected Bluetooth device using AVRCP commands. Returns the metadata as a String.

```C++
String getMetadata(uint8_t type);
```

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

### Control SD Card Playback

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Sends playback control commands (play, pause, stop) to the background WAV player task. `SD_AMPLIFIER_PLAY` resumes from pause or starts the default track. `SD_AMPLIFIER_PAUSE` freezes playback. `SD_AMPLIFIER_STOP` halts playback completely.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;
String musicList[100];

void setup() {
  Serial.begin(115200);
  amplifier.initI2S(GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);
  amplifier.initSDCard(GPIO_NUM_5);
  amplifier.scanSDMusic(musicList);

  amplifier.SDPlayerControl(SD_AMPLIFIER_PLAY);   // start first track
  delay(5000);
  amplifier.SDPlayerControl(SD_AMPLIFIER_PAUSE);  // pause after 5 s
  delay(2000);
  amplifier.SDPlayerControl(SD_AMPLIFIER_PLAY);   // resume
  delay(3000);
  amplifier.SDPlayerControl(SD_AMPLIFIER_STOP);   // stop completely
}
```

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

### Get Remote Bluetooth Device MAC Address with getRemoteAddress

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Returns a pointer to a 6-byte array containing the Bluetooth MAC address of the remote device once AVRCP has successfully connected. Returns NULL if no AVRCP connection is established yet.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("AddressSpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  uint8_t *addr = nullptr;

  // Wait until a Bluetooth device connects via AVRCP
  while (addr == nullptr) {
    Serial.println("Waiting for Bluetooth connection...");
    delay(3000);
    addr = amplifier.getRemoteAddress();
  }

  Serial.print("Connected device MAC: ");
  for (uint8_t i = 0; i < 6; i++) {
    if (i) Serial.print("-");
    if (addr[i] < 0x10) Serial.print("0");
    Serial.print(addr[i], HEX);
  }
  Serial.println();
  // Example output:
  // Connected device MAC: A4-C3-F0-12-AB-7E
}
```

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

### Get Remote Bluetooth Device Address

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Retrieves the MAC address of the paired remote Bluetooth device after successful communication via AVRCP. Returns a pointer to the address array or NULL if connection/communication fails.

```C++
uint8_t * getRemoteAddress(void);
```

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

### begin

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Initializes the I2S driver and the Classic Bluetooth stack for a fully functional Bluetooth speaker. Returns true on success.

```APIDOC
## begin — One-call initialization for Bluetooth speaker mode

### Description
Initializes the I2S driver with the specified GPIO pins, then brings up the Classic Bluetooth stack (Bluedroid), registers A2DP sink and AVRCP controller callbacks, and sets the device discoverable. This is the only call needed to create a fully functional Bluetooth speaker. Returns `true` on success.

### Parameters
#### Path Parameters
- **btName** (string) - Required - Advertised Bluetooth device name
- **bclk** (GPIO_NUM) - Required - I2S bit clock pin (default GPIO 25)
- **lrclk** (GPIO_NUM) - Required - I2S word-select pin (default GPIO 26)
- **din** (GPIO_NUM) - Required - I2S data pin (default GPIO 27)

### Request Example
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);

  while (!amplifier.begin(/*btName=*/"MyBTSpeaker",
                          /*bclk=*/  GPIO_NUM_25,
                          /*lrclk=*/ GPIO_NUM_26,
                          /*din=*/   GPIO_NUM_27)) {
    Serial.println("Init failed, retrying...");
    delay(3000);
  }
  Serial.println("Bluetooth speaker ready – connect your device!");
}

void loop() {
  // Audio streams automatically once a phone pairs and plays music.
}
```
```

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

### initSDCard

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Mounts an SPI SD card and spawns a FreeRTOS task for WAV file playback. The default CS pin is GPIO 5. Returns true on success.

```APIDOC
## initSDCard — Mount an SPI SD card

### Description
Mounts the SD card using the Arduino SD library over SPI and spawns the background `playWAV` FreeRTOS task that handles WAV file decoding. The default CS pin is GPIO 5. SD card connections: VCC→5V, GND→GND, SS→csPin (IO5), SCK→IO18, MISO→IO19, MOSI→IO23. Returns `true` on success.

### Parameters
#### Path Parameters
- **csPin** (GPIO_NUM) - Required - SPI chip-select pin for the SD card module (default GPIO 5)

### Request Example
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);

  amplifier.initI2S(GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  while (!amplifier.initSDCard(/*csPin=*/GPIO_NUM_5)) {
    Serial.println("SD card init failed – check wiring!");
    delay(3000);
  }
  Serial.println("SD card mounted.");
}
```
```

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

### Initialize Bluetooth Module

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Initializes the Bluetooth module with a specified device name. Returns true on success, false on error.

```C++
bool initBluetooth(const char * _btName);
```

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

### Initialization Functions

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Functions to initialize the MAX98357A module, including I2S communication, Bluetooth, and SD card.

```APIDOC
## begin

### Description
Initializes the MAX98357A module with optional Bluetooth name and I2S pins.

### Method
bool begin(const char *btName="bluetoothAmplifier", int bclk=GPIO_NUM_25, int lrclk=GPIO_NUM_26, int din=GPIO_NUM_27)

### Parameters
- **btName** (const char *) - Optional: Name for the Bluetooth device. Defaults to "bluetoothAmplifier".
- **bclk** (int) - Optional: GPIO pin for I2S bit clock (BCK). Defaults to GPIO_NUM_25.
- **lrclk** (int) - Optional: GPIO pin for I2S word select (WS). Defaults to GPIO_NUM_26.
- **din** (int) - Optional: GPIO pin for I2S data in (SD). Defaults to GPIO_NUM_27.

### Return
- true on success, false on error.
```

```APIDOC
## initI2S

### Description
Initializes the I2S communication interface with specified pins.

### Method
bool initI2S(int _bclk, int _lrclk, int _din)

### Parameters
- **_bclk** (int) - GPIO pin number for I2S bit clock (BCK).
- **_lrclk** (int) - GPIO pin number for I2S word select (WS).
- **_din** (int) - GPIO pin number for I2S data in (SD).

### Return
- true on success, false on error.
```

```APIDOC
## initBluetooth

### Description
Initializes the Bluetooth functionality with a specified device name.

### Method
bool initBluetooth(const char * _btName)

### Parameters
- **_btName** (const char *) - The desired name for the Bluetooth device.

### Return
- true on success, false on error.
```

```APIDOC
## initSDCard

### Description
Initializes the SD card interface using the specified chip select pin.

### Method
bool initSDCard(uint8_t csPin=GPIO_NUM_5)

### Parameters
- **csPin** (uint8_t) - Optional: The GPIO pin number for the SD card's chip select (CS). Defaults to GPIO_NUM_5.

### Return
- true on success, false on error.
```

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

### Scan SD Card for WAV Files

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Recursively scans the SD card for WAV files and populates a string array with their absolute paths. The first found file is set as the default track for playback. File paths and names must be ASCII-only with no spaces.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;
String musicList[100];

void setup() {
  Serial.begin(115200);
  amplifier.initI2S(GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);
  amplifier.initSDCard(GPIO_NUM_5);

  // Populate musicList[] with absolute paths of every .wav on the card
  amplifier.scanSDMusic(musicList);

  // Print discovered tracks
  for (uint8_t i = 0; musicList[i].length(); i++) {
    Serial.print(i); Serial.print(" – "); Serial.println(musicList[i]);
  }
  // Example output:
  // 0 – /music/track01.wav
  // 1 – /music/track02.wav
}
```

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

### Initialize SD Card Module

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Initializes the SD card module using SPI communication. Requires the chip select (CS) pin. Defaults to GPIO_NUM_5 if not specified.

```C++
bool initSDCard(uint8_t csPin=GPIO_NUM_5);
```

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

### initI2S

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Initializes the I2S driver only, configuring it for master/TX mode at 44100 Hz, 16-bit stereo. Useful for SD card playback without Bluetooth. Returns true on success.

```APIDOC
## initI2S — Initialize the I2S driver only

### Description
Configures and installs the ESP-IDF I2S driver in master/TX mode at 44 100 Hz, 16-bit stereo. Call this instead of `begin()` when you want to drive audio from the SD card without Bluetooth. Returns `true` on success.

### Parameters
#### Path Parameters
- **_bclk** (GPIO_NUM) - Required - Bit clock pin
- **_lrclk** (GPIO_NUM) - Required - Left/right clock (word-select) pin
- **_din** (GPIO_NUM) - Required - Serial data pin

### Request Example
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);

  while (!amplifier.initI2S(/*_bclk=*/GPIO_NUM_25,
                             /*_lrclk=*/GPIO_NUM_26,
                             /*_din=*/GPIO_NUM_27)) {
    Serial.println("I2S init failed!");
    delay(3000);
  }
  Serial.println("I2S ready.");
}
```
```

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

### initBluetooth

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Initializes the Classic Bluetooth A2DP sink and AVRCP controller, making the device discoverable. Useful when combining Bluetooth with a separately initialized I2S bus. Returns true on success.

```APIDOC
## initBluetooth — Initialize Classic Bluetooth A2DP/AVRCP only

### Description
Starts the Bluedroid stack, registers A2DP sink and AVRCP controller callbacks, and makes the device discoverable under the given name. Useful when combining Bluetooth with a separately initialized I2S bus. Returns `true` on success.

### Parameters
#### Path Parameters
- **_btName** (string) - Required - Name that appears in the phone's Bluetooth scan list

### Request Example
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);

  amplifier.initI2S(GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  if (!amplifier.initBluetooth("LivingRoomSpeaker")) {
    Serial.println("Bluetooth init failed!");
  } else {
    Serial.println("Discoverable as 'LivingRoomSpeaker'.");
  }
}
```
```

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

### Initialize Bluetooth Speaker Mode

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Use this function for a one-call initialization to set up the I2S driver and Classic Bluetooth stack for wireless audio streaming. Ensure the Bluetooth device name, and I2S GPIO pins are correctly specified.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);

  // btName   – advertised Bluetooth device name
  // bclk     – I2S bit clock pin  (default GPIO 25)
  // lrclk    – I2S word-select pin (default GPIO 26)
  // din      – I2S data pin       (default GPIO 27)
  while (!amplifier.begin(/*btName=*/"MyBTSpeaker",
                          /*bclk=*/  GPIO_NUM_25,
                          /*lrclk=*/ GPIO_NUM_26,
                          /*din=*/   GPIO_NUM_27)) {
    Serial.println("Init failed, retrying...");
    delay(3000);
  }
  Serial.println("Bluetooth speaker ready – connect your device!");
}

void loop() {
  // Audio streams automatically once a phone pairs and plays music.
}
```

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

### scanSDMusic

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Recursively scans the SD card for WAV files, populating a provided string array with their paths and setting the first found file as the default track for playback.

```APIDOC
## scanSDMusic — Scan all WAV files on the SD card

### Description
Recursively traverses the SD card filesystem from the root and collects every file whose name ends in `.wav` into the caller-supplied `String` array (max 100 entries). Also sets the first found file as the default track for subsequent `SDPlayerControl(SD_AMPLIFIER_PLAY)` calls. File paths and names must be ASCII-only with no spaces.

### Method
`amplifier.scanSDMusic(musicList)`

### Parameters
#### Path Parameters
- **musicList** (String array) - Required - An array to store the paths of discovered WAV files. Maximum 100 entries.

### Request Example
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;
String musicList[100];

void setup() {
  Serial.begin(115200);
  amplifier.initI2S(GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);
  amplifier.initSDCard(GPIO_NUM_5);

  // Populate musicList[] with absolute paths of every .wav on the card
  amplifier.scanSDMusic(musicList);

  // Print discovered tracks
  for (uint8_t i = 0; musicList[i].length(); i++) {
    Serial.print(i); Serial.print(" – "); Serial.println(musicList[i]);
  }
}
```

### Response
This function does not return a value directly but populates the `musicList` array.
```

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

### Play WAV Music File from SD Card

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Plays a specified music file from the SD card. The filename must be an absolute path and in WAV format. Only supports English filenames.

```C++
void playSDMusic(const char *Filename);
```

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

### Initialize I2S Communication

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Initializes the I2S communication interface with specified clock, word select, and data pins. Returns true on success, false on error.

```C++
bool initI2S(int _bclk, int _lrclk, int _din);
```

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

### Scan SD Card for WAV Music Files

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Scans the SD card for music files in WAV format and stores their names in the provided String array. Only supports English filenames and WAV format.

```C++
void scanSDMusic(String * musicList);
```

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

### playSDMusic

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Stops current playback, sets a specified WAV file as the active track, and immediately begins playback.

```APIDOC
## playSDMusic — Play a specific WAV file from the SD card

### Description
Stops any current playback, sets the given absolute file path as the active track, and immediately starts playback. The filename must be an absolute path (e.g. `/music/song.wav`) in ASCII with no spaces, and the file must be in WAV format.

### Method
`amplifier.playSDMusic(filePath)`

### Parameters
#### Path Parameters
- **filePath** (const char*) - Required - The absolute path to the WAV file to play.

### Request Example
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;
String musicList[100];

void setup() {
  Serial.begin(115200);
  amplifier.initI2S(GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);
  amplifier.initSDCard(GPIO_NUM_5);
  amplifier.scanSDMusic(musicList);

  // Play the second track from the scanned list
  if (musicList[1].length()) {
    amplifier.playSDMusic(musicList[1].c_str());
    // or use a hard-coded path:
    // amplifier.playSDMusic("/music/track02.wav");
  }
}
```

### Response
This function does not return a value.
```

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

### Initialize MAX98357A with Bluetooth

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Initializes the MAX98357A amplifier with optional Bluetooth device name and I2S communication pins. Defaults are provided for pins if not specified.

```C++
bool begin(const char *btName="bluetoothAmplifier", 
             int bclk=GPIO_NUM_25, 
             int lrclk=GPIO_NUM_26, 
             int din=GPIO_NUM_27);
```

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

### Bluetooth and Metadata

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Functions for retrieving Bluetooth device information and metadata.

```APIDOC
## getMetadata

### Description
Retrieves metadata (like title, artist, album) from the connected Bluetooth device using AVRC commands.

### Method
String getMetadata(uint8_t type)

### Parameters
- **type** (uint8_t) - The type of metadata to retrieve. Supported values:
  - `ESP_AVRC_MD_ATTR_TITLE`
  - `ESP_AVRC_MD_ATTR_ARTIST`
  - `ESP_AVRC_MD_ATTR_ALBUM`

### Return
- A String containing the requested metadata.
```

```APIDOC
## getRemoteAddress

### Description
Retrieves the MAC address of the remotely connected Bluetooth device after successful pairing and AVRCP communication.

### Method
uint8_t * getRemoteAddress(void)

### Return
- A pointer to a uint8_t array containing the remote Bluetooth device's address.
- Returns None if the module is not connected or communication failed via AVRCP.
```

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

### setVolume

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Adjusts the software volume multiplier for audio playback.

```APIDOC
## setVolume — Set playback volume

### Description
Adjusts the software volume multiplier applied to every PCM sample before it is written to I2S. The range is **0–9**: 0 is silence, 5 is unity gain (original audio level), and 9 is approximately double the original amplitude. Applies to both Bluetooth and SD card audio sources.

### Method
`amplifier.setVolume(level)`

### Parameters
#### Path Parameters
- **level** (int) - Required - The volume level, ranging from 0 (silence) to 9 (maximum amplification).

### Request Example
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("MySpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  amplifier.setVolume(5);   // unity gain – no amplification or attenuation
  // amplifier.setVolume(8);   // louder
  // amplifier.setVolume(2);   // quieter
}
```

### Response
This function does not return a value.
```

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

### Retrieve Track Metadata with getMetadata

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Sends an AVRC metadata request to the connected A2DP source, waiting up to 2 seconds for a response. Returns an empty string if the device is not connected via AVRCP or the request times out.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("MetadataSpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);
}

void loop() {
  String title  = amplifier.getMetadata(ESP_AVRC_MD_ATTR_TITLE);
  String artist = amplifier.getMetadata(ESP_AVRC_MD_ATTR_ARTIST);
  String album  = amplifier.getMetadata(ESP_AVRC_MD_ATTR_ALBUM);

  if (title.length())  { Serial.print("Title:  "); Serial.println(title); }
  if (artist.length()) { Serial.print("Artist: "); Serial.println(artist); }
  if (album.length())  { Serial.print("Album:  "); Serial.println(album); }

  // Example output:
  // Title:  Bohemian Rhapsody
  // Artist: Queen
  // Album:  A Night at the Opera

  delay(5000);
}
```

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

### Swap Left and Right Audio Channels with reverseLeftRightChannels

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Toggles the channel mapping used when writing samples to the I2S bus. Call this if the physical speaker wiring causes the left and right channels to be swapped.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("MySpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  // Uncomment if left/right audio channels appear reversed:
  // amplifier.reverseLeftRightChannels();
}
```

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

### SDPlayerControl

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Controls the SD card music playback state, allowing for play, pause, or stop commands.

```APIDOC
## SDPlayerControl — Pause, resume, or stop SD card playback

### Description
Sends a playback control command to the background WAV player task. Use the constants `SD_AMPLIFIER_PLAY` (1), `SD_AMPLIFIER_PAUSE` (2), or `SD_AMPLIFIER_STOP` (3). PLAY resumes from the paused position; if no track was selected with `playSDMusic()`, the first scanned track plays. PAUSE freezes playback at the current sample position.

### Method
`amplifier.SDPlayerControl(command)`

### Parameters
#### Path Parameters
- **command** (int) - Required - The playback control command. Use `SD_AMPLIFIER_PLAY`, `SD_AMPLIFIER_PAUSE`, or `SD_AMPLIFIER_STOP`.

### Request Example
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;
String musicList[100];

void setup() {
  Serial.begin(115200);
  amplifier.initI2S(GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);
  amplifier.initSDCard(GPIO_NUM_5);
  amplifier.scanSDMusic(musicList);

  amplifier.SDPlayerControl(SD_AMPLIFIER_PLAY);   // start first track
  delay(5000);
  amplifier.SDPlayerControl(SD_AMPLIFIER_PAUSE);  // pause after 5 s
  delay(2000);
  amplifier.SDPlayerControl(SD_AMPLIFIER_PLAY);   // resume
  delay(3000);
  amplifier.SDPlayerControl(SD_AMPLIFIER_STOP);   // stop completely
}
```

### Response
This function does not return a value.
```

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

### Enable Audio Filters

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Activates a 3-stage cascaded biquad filter on both audio channels. Specify filter type (`bq_type_highpass` or `bq_type_lowpass`) and cutoff frequency (2–20000 Hz). Both filter types can be active simultaneously.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("FilteredSpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);
  amplifier.setVolume(5);

  // Remove low-frequency rumble below 200 Hz
  amplifier.openFilter(bq_type_highpass, 200.0);

  // Also cut any ultrasonic content above 15 kHz
  amplifier.openFilter(bq_type_lowpass, 15000.0);

  // Both filters are now active simultaneously
}
```

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

### Audio Control

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Functions for adjusting audio volume and applying filters.

```APIDOC
## setVolume

### Description
Sets the playback volume for the MAX98357A amplifier.

### Method
void setVolume(float vol)

### Parameters
- **vol** (float) - The desired volume level, ranging from 0 to 9. A value of 5 represents the original volume without amplification or reduction.

### Return
- None
```

```APIDOC
## openFilter

### Description
Enables and configures an audio filter (high-pass or low-pass).

### Method
void openFilter(int type, float fc)

### Parameters
- **type** (int) - The type of filter to enable. Use `bq_type_highpass` for high-pass or `bq_type_lowpass` for low-pass filtering.
- **fc** (float) - The cutoff frequency for the filter, ranging from 2 to 20000 Hz.

### Return
- None

### Notes
- High-pass and low-pass filters can work simultaneously.
- Example: Enabling a high-pass filter with a threshold of 500 Hz will filter out audio signals below 500 Hz.
```

```APIDOC
## closeFilter

### Description
Disables the audio filter.

### Method
void closeFilter()

### Return
- None
```

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

### Control SD Card Music Playback

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Provides an interface to control SD card music playback. Commands include PLAY, PAUSE, and STOP. Playback may error if files are not scanned correctly.

```C++
void SDPlayerControl(uint8_t CMD);
```

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

### Enable Audio Filter

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Enables either a high-pass or low-pass audio filter with a specified cutoff frequency. Both filters can be active simultaneously. The cutoff frequency ranges from 2 to 20000 Hz.

```C++
void openFilter(int type, float fc);
```

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

### Set Audio Volume

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Sets the playback volume for the MAX98357A amplifier. The volume can be set on a scale of 0 to 9, where 5 represents the original audio data volume.

```C++
void setVolume(float vol);
```

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

### SD Card Music Playback

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Functions for scanning, playing, and controlling music files stored on an SD card.

```APIDOC
## scanSDMusic

### Description
Scans the SD card for music files in WAV format and populates a provided string array with their names.

### Method
void scanSDMusic(String * musicList)

### Parameters
- **musicList** (String *) - A pointer to a String array where the names of found WAV files will be stored.

### Return
- None

### Notes
- Currently only supports English path names and WAV format for music files.
```

```APIDOC
## playSDMusic

### Description
Plays a specified music file from the SD card.

### Method
void playSDMusic(const char *Filename)

### Parameters
- **Filename** (const char *) - The name of the music file to play. Must be an absolute path (e.g., "/musicDir/music.wav").

### Return
- None

### Notes
- Currently only supports English path names and WAV format for music files.
```

```APIDOC
## SDPlayerControl

### Description
Controls the playback of music files from the SD card.

### Method
void SDPlayerControl(uint8_t CMD)

### Parameters
- **CMD** (uint8_t) - The playback control command. Accepted values:
  - `SD_AMPLIFIER_PLAY`: Starts or resumes playback. If no file is selected, plays the first in the playlist. Playback may fail if files are not scanned correctly.
  - `SD_AMPLIFIER_PAUSE`: Pauses playback, retaining the current position.
  - `SD_AMPLIFIER_STOP`: Stops playback.

### Return
- None

### Notes
- Music files must be scanned from the SD card in the correct format (English path names, WAV format).
```

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

### getMetadata

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Retrieves track metadata (title, artist, album) from the connected Bluetooth device using an AVRCP request. Waits up to 2 seconds for a response.

```APIDOC
## getMetadata — Retrieve track metadata from the connected Bluetooth device

### Description
Sends an AVRC metadata request to the connected A2DP source and waits up to 2 seconds for the response. Supported attribute types: `ESP_AVRC_MD_ATTR_TITLE`, `ESP_AVRC_MD_ATTR_ARTIST`, `ESP_AVRC_MD_ATTR_ALBUM`. Returns an empty string if the device is not connected via AVRCP or the request times out.

### Method
```cpp
amplifier.getMetadata(attribute_type);
```

### Parameters
#### Path Parameters
- **attribute_type** (enum) - Required - The type of metadata to retrieve (e.g., `ESP_AVRC_MD_ATTR_TITLE`).

### Example Usage
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("MetadataSpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);
}

void loop() {
  String title  = amplifier.getMetadata(ESP_AVRC_MD_ATTR_TITLE);
  String artist = amplifier.getMetadata(ESP_AVRC_MD_ATTR_ARTIST);
  String album  = amplifier.getMetadata(ESP_AVRC_MD_ATTR_ALBUM);

  if (title.length())  { Serial.print("Title:  "); Serial.println(title); }
  if (artist.length()) { Serial.print("Artist: "); Serial.println(artist); }
  if (album.length())  { Serial.print("Album:  "); Serial.println(album); }

  // Example output:
  // Title:  Bohemian Rhapsody
  // Artist: Queen
  // Album:  A Night at the Opera

  delay(5000);
}
```
```

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

### reverseLeftRightChannels

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Swaps the left and right audio channels. This is useful if the physical speaker wiring causes audio channels to be reversed.

```APIDOC
## reverseLeftRightChannels — Swap left and right audio channels

### Description
Toggles the channel mapping used when writing samples to the I2S bus. Call this if the physical speaker wiring causes the left and right channels to be swapped. It applies to both Bluetooth and SD card playback by inverting the internal `_voiceSource` flag.

### Method
```cpp
amplifier.reverseLeftRightChannels();
```

### Example Usage
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("MySpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  // Uncomment if left/right audio channels appear reversed:
  // amplifier.reverseLeftRightChannels();
}
```
```

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

### openFilter

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Enables a biquad filter (high-pass or low-pass) with a specified cutoff frequency.

```APIDOC
## openFilter — Enable a high-pass or low-pass biquad filter

### Description
Activates a 3-stage cascaded biquad filter on both the left and right audio channels. Specify the filter type (`bq_type_highpass` or `bq_type_lowpass`) and a cutoff frequency in Hz (range 2–20000). Both filter types can be active simultaneously. Filtering is applied inside `audioDataProcessCallback` on every received audio packet.

### Method
`amplifier.openFilter(type, frequency)`

### Parameters
#### Path Parameters
- **type** (enum) - Required - The type of filter. Use `bq_type_highpass` or `bq_type_lowpass`.
- **frequency** (float) - Required - The cutoff frequency in Hz. Range: 2–20000.

### Request Example
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("FilteredSpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);
  amplifier.setVolume(5);

  // Remove low-frequency rumble below 200 Hz
  amplifier.openFilter(bq_type_highpass, 200.0);

  // Also cut any ultrasonic content above 15 kHz
  amplifier.openFilter(bq_type_lowpass, 15000.0);

  // Both filters are now active simultaneously
}
```

### Response
This function does not return a value.
```

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

### Disable Audio Filters with closeFilter

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Disables biquad filter processing, passing raw PCM samples directly to I2S. Filter coefficients are preserved for later re-enabling.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("MySpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  amplifier.openFilter(bq_type_highpass, 500.0);
  delay(10000);                 // run with filter for 10 seconds

  amplifier.closeFilter();      // return to unfiltered audio
}
```

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

### reverseLeftRightChannels

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Reverses the left and right audio channels. This is useful when the stereo channels are found to be playing in opposite directions. This function does not take any parameters and returns nothing.

```APIDOC
## reverseLeftRightChannels

### Description
Reverses left and right channels. When you find that the left and right channels play opposite, you can call this interface to adjust.

### Method
void

### Parameters
None

### Return Value
None
```

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

### Set Playback Volume

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Adjusts the software volume multiplier for audio playback. The range is 0 (silence) to 9 (approximately double amplitude). This setting affects both SD card and Bluetooth audio sources.

```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("MySpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  amplifier.setVolume(5);   // unity gain – no amplification or attenuation
  // amplifier.setVolume(8);   // louder
  // amplifier.setVolume(2);   // quieter
}
```

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

### closeFilter

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Disables the audio filter. This function does not take any parameters and returns nothing.

```APIDOC
## closeFilter

### Description
Disables the audio filter.

### Method
void

### Parameters
None

### Return Value
None
```

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

### getRemoteAddress

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Retrieves the MAC address of the connected Bluetooth device once an AVRCP connection is established.

```APIDOC
## getRemoteAddress — Get the MAC address of the connected Bluetooth device

### Description
Returns a pointer to a 6-byte array containing the Bluetooth MAC address of the remote device once AVRCP has successfully connected. Returns `NULL` if no AVRCP connection is established yet. The address is stored in the static member `DFRobot_MAX98357A::remoteAddress`.

### Method
```cpp
amplifier.getRemoteAddress();
```

### Return Value
- `uint8_t*`: A pointer to a 6-byte array containing the MAC address, or `NULL` if not connected.

### Example Usage
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("AddressSpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  uint8_t *addr = nullptr;

  // Wait until a Bluetooth device connects via AVRCP
  while (addr == nullptr) {
    Serial.println("Waiting for Bluetooth connection...");
    delay(3000);
    addr = amplifier.getRemoteAddress();
  }

  Serial.print("Connected device MAC: ");
  for (uint8_t i = 0; i < 6; i++) {
    if (i) Serial.print("-");
    if (addr[i] < 0x10) Serial.print("0");
    Serial.print(addr[i], HEX);
  }
  Serial.println();
  // Example output:
  // Connected device MAC: A4-C3-F0-12-AB-7E
}
```
```

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

### closeFilter

Source: https://context7.com/dfrobot/dfrobot_max98357a/llms.txt

Disables the biquad filter processing, allowing raw PCM samples to be passed directly to I2S. The filter coefficients are preserved for later re-enabling.

```APIDOC
## closeFilter — Disable all audio filters

### Description
Disables the biquad filter processing so raw (volume-adjusted) PCM samples are passed directly to I2S without any frequency filtering. The filter coefficients are preserved; calling `openFilter()` again re-enables filtering without reconfiguring unless new parameters are supplied.

### Method
```cpp
amplifier.closeFilter();
```

### Example Usage
```cpp
#include <DFRobot_MAX98357A.h>

DFRobot_MAX98357A amplifier;

void setup() {
  Serial.begin(115200);
  amplifier.begin("MySpeaker", GPIO_NUM_25, GPIO_NUM_26, GPIO_NUM_27);

  amplifier.openFilter(bq_type_highpass, 500.0);
  delay(10000);                 // run with filter for 10 seconds

  amplifier.closeFilter();      // return to unfiltered audio
}
```
```

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

### Disable Audio Filter

Source: https://github.com/dfrobot/dfrobot_max98357a/blob/main/README.md

Disables the audio filter. No parameters are required.

```C++
void closeFilter();
```

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