/*
 * 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.
 */
typedef enum {
    AUDIO_PROFILE_CHIPTUNE = 0, /* Full 8-bit melodies & arcade fanfares */
    AUDIO_PROFILE_TACTILE  = 1, /* Soft micro-clicks & subtle clean chimes */
    AUDIO_PROFILE_SILENT   = 2, /* Mute all sound */
} audio_profile_t;

/**
 * @brief Set the active audio profile and persist to NVS.
 */
void buzzer_set_profile(audio_profile_t profile);

/**
 * @brief Get the active audio profile.
 */
audio_profile_t buzzer_get_profile(void);

/**
 * @brief Get human-readable string for audio profile.
 */
const char *buzzer_get_profile_name(audio_profile_t profile);

/**
 * @brief Pitch-up feedback when gaining life.
 */
void buzzer_sound_life_gain(void);

/**
 * @brief Pitch-down feedback when losing life.
 */
void buzzer_sound_life_loss(void);

/**
 * @brief Clean notification chime when RFID card is tapped.
 */
void buzzer_sound_rfid_tap(void);

/**
 * @brief Subtle encoder rotary detent click.
 */
void buzzer_sound_tick(void);

#ifdef __cplusplus
}
#endif