/*
 * MTG RFID Companion - Piezo buzzer driver (LEDC PWM)
 *
 * Phase 7 Step 7.4: Subtle audio cues on GPIO 14.
 */

#pragma once

#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Musical note frequencies (Hz) */
#define NOTE_REST 0
#define NOTE_G3   196
#define NOTE_GS3  208
#define NOTE_A3   220
#define NOTE_AS3  233
#define NOTE_B3   247
#define NOTE_C4   262
#define NOTE_CS4  277
#define NOTE_D4   294
#define NOTE_DS4  311
#define NOTE_E4   330
#define NOTE_F4   349
#define NOTE_FS4  370
#define NOTE_G4   392
#define NOTE_GS4  415
#define NOTE_A4   440
#define NOTE_AS4  466
#define NOTE_B4   494
#define NOTE_C5   523
#define NOTE_CS5  554
#define NOTE_D5   587
#define NOTE_DS5  622
#define NOTE_E5   659
#define NOTE_F5   698
#define NOTE_FS5  740
#define NOTE_G5   784
#define NOTE_GS5  831
#define NOTE_A5   880
#define NOTE_AS5  932
#define NOTE_B5   988
#define NOTE_C6   1047
#define NOTE_D6   1175
#define NOTE_E6   1319
#define NOTE_G6   1568

typedef struct {
    uint16_t freq_hz;
    uint16_t duration_ms;
} buzzer_note_t;

typedef enum {
    BUZZER_SOUND_NONE = 0,
    BUZZER_SOUND_VICTORY,
    BUZZER_SOUND_LEGENDARY,
    BUZZER_SOUND_LOSS,
} buzzer_sound_t;

/**
 * @brief Initialize LEDC PWM channel for the buzzer and starts worker task.
 */
esp_err_t buzzer_init(void);

/**
 * @brief Start a tone at the given frequency.
 */
esp_err_t buzzer_start(uint32_t freq_hz, uint32_t duty_percent);

/**
 * @brief Silence the buzzer.
 */
esp_err_t buzzer_stop(void);

/**
 * @brief Play a short chirp (blocking).
 * @param freq_hz Tone frequency
 * @param duration_ms Tone length in ms
 */
esp_err_t buzzer_chirp(uint32_t freq_hz, uint32_t duration_ms);

/**
 * @brief Play an 8-bit melody asynchronously (non-blocking).
 */
esp_err_t buzzer_play_sound(buzzer_sound_t sound);

/**
 * @brief Play a custom sequence of notes synchronously.
 */
esp_err_t buzzer_play_notes(const buzzer_note_t *notes, size_t count);

#ifdef __cplusplus
}
#endif