// audio.h
#pragma once
#ifndef AUDIO_H
#define AUDIO_H

#ifdef __cplusplus
#include <cstdint>
extern "C" {
#else
#include <stdint.h>
#include <stdbool.h>
#endif

typedef struct audio_t audio_t;
typedef uint32_t audio_stream_id_t;

// If the return type is bool, false means failure.

// Initialize audio system
// nullptr means failure
audio_t* audio_init(void);

// Destroy audio system and free resources
void audio_destroy(audio_t* audio);

// Load MADPCM data from a WAV file.
// Returns a pointer to the allocated audio data, or nullptr on failure.
// The returned buffer must be freed with audio_free_data().
uint8_t* audio_load_madpcm(const char* filename, int* out_size, int* out_channels, int* out_rate, int* out_total_samples);

// Free data allocated by audio_load_madpcm
void audio_free_data(uint8_t* data);

// Play a MADPCM stream, returns unique ID
// data must remain valid until the stream ends or is stopped
// loop: if true, the stream restarts on EOF
// 0 means failure, valid IDs start from 1
audio_stream_id_t audio_play(audio_t* audio,
    const uint8_t* data,
    int size,
    int channels,
    int rate,
    bool loop);

// Stop and remove stream by ID
bool audio_stop(audio_t* audio, audio_stream_id_t id);

bool audio_pause(audio_t* audio, audio_stream_id_t id);
bool audio_resume(audio_t* audio, audio_stream_id_t id);

// Returns true if the stream is active (playing or paused)
bool audio_is_active(audio_t* audio, audio_stream_id_t id);

// Returns true if the stream is currently playing (not paused, not stopped)
bool audio_is_playing(audio_t* audio, audio_stream_id_t id);

// Per-stream volume, immediate effect, range [0.0, 1.0]
bool audio_set_volume(audio_t* audio, audio_stream_id_t id, float volume);

// Animate per-stream volume linearly over time, driven by audio_tick()
bool audio_animate_volume(audio_t* audio, audio_stream_id_t id,
    float to_volume, float duration_sec);

// Global volume, immediate effect, range [0.0, 1.0]
// Applied on top of per-stream volume at mix time
void audio_set_global_volume(audio_t* audio, float volume);

// Animate global volume linearly over time, driven by audio_tick()
void audio_animate_global_volume(audio_t* audio,
    float to_volume, float duration_sec);

// Advances stream decoding and volume animations
// Call once per main loop iteration with the same delta as compositor_tick()
void audio_tick(audio_t* audio, float delta_time_sec);

#ifdef __cplusplus
}
#endif

#endif // AUDIO_H