Updated dependencies.

managed_components/chmorgan__esp-audio-player/include/audio_stream.h

@@ -0,0 +1,188 @@
+/**
+ * @file audio_stream.h
+ * @brief Stream API — create/delete logical playback streams and control them.
+ * These streams own their decode task and submit PCM to the mixer.
+ */
+#pragma once
+
+#include "audio_player.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct audio_stream;
+/**
+ * @brief Audio stream handle
+ */
+typedef struct audio_stream* audio_stream_handle_t;
+
+/**
+ * @brief Macro to check if a stream handle is valid
+ */
+#define CHECK_STREAM(s) \
+    ESP_RETURN_ON_FALSE(s != NULL, ESP_ERR_INVALID_ARG, "audio_stream", "stream is NULL")
+
+/**
+ * @brief Audio stream types
+ */
+typedef enum {
+    AUDIO_STREAM_TYPE_UNKNOWN = 0, /**< Unknown stream type */
+    AUDIO_STREAM_TYPE_DECODER,     /**< Stream that decodes audio (e.g., MP3, WAV) */
+    AUDIO_STREAM_TYPE_RAW          /**< Stream that accepts raw PCM data */
+} audio_stream_type_t;
+
+/**
+ * @brief Configuration structure for an audio stream
+ */
+typedef struct {
+    audio_stream_type_t type;    /**< Type of stream */
+    char name[16];               /**< Optional: Name of the stream (e.g. "sfx", "bgm"). Auto-generated if empty. */
+    UBaseType_t priority;        /**< FreeRTOS task priority for the stream's decoder task (if applicable) */
+    BaseType_t coreID;           /**< ESP32 core ID for the stream's decoder task (if applicable) */
+} audio_stream_config_t;
+
+/**
+ * @brief Default configuration for an audio decoder stream
+ *
+ * @param _name Name of the stream
+ */
+#define DEFAULT_AUDIO_STREAM_CONFIG(_name) {    \
+        .type = AUDIO_STREAM_TYPE_DECODER,      \
+        .name = _name,                          \
+        .priority = tskIDLE_PRIORITY + 1,       \
+        .coreID = tskNO_AFFINITY                \
+    }
+
+/**
+ * @brief Get the current state of a stream
+ *
+ * @param h Handle of the stream
+ * @return Current audio_player_state_t of the stream
+ */
+audio_player_state_t audio_stream_get_state(audio_stream_handle_t h);
+
+/**
+ * @brief Get the type of a stream
+ *
+ * @param h Handle of the stream
+ * @return audio_stream_type_t of the stream
+ */
+audio_stream_type_t audio_stream_get_type(audio_stream_handle_t h);
+
+/**
+ * @brief Play an audio file on a stream
+ *
+ * Only supported for DECODER type streams.
+ *
+ * @param h Handle of the stream
+ * @param fp File pointer to the audio file
+ * @return
+ *    - ESP_OK: Success
+ *    - ESP_ERR_NOT_SUPPORTED: Stream is not a decoder stream
+ *    - Others: Fail
+ */
+esp_err_t audio_stream_play(audio_stream_handle_t h, FILE *fp);
+
+/**
+ * @brief Queue an audio file to be played on a stream
+ *
+ * Only supported for DECODER type streams.
+ *
+ * @param h Handle of the stream
+ * @param fp File pointer to the audio file
+ * @param play_now If true, start playing immediately (interrupting current playback)
+ * @return
+ *    - ESP_OK: Success
+ *    - ESP_ERR_NOT_SUPPORTED: Stream is not a decoder stream
+ *    - Others: Fail
+ */
+esp_err_t audio_stream_queue(audio_stream_handle_t h, FILE *fp, bool play_now);
+
+/**
+ * @brief Stop playback on a stream
+ *
+ * @param h Handle of the stream
+ * @return
+ *    - ESP_OK: Success
+ *    - Others: Fail
+ */
+esp_err_t audio_stream_stop(audio_stream_handle_t h);
+
+/**
+ * @brief Pause playback on a stream
+ *
+ * Only supported for DECODER type streams.
+ *
+ * @param h Handle of the stream
+ * @return
+ *    - ESP_OK: Success
+ *    - ESP_ERR_NOT_SUPPORTED: Stream is not a decoder stream
+ *    - Others: Fail
+ */
+esp_err_t audio_stream_pause(audio_stream_handle_t h);
+
+/**
+ * @brief Resume playback on a stream
+ *
+ * Only supported for DECODER type streams.
+ *
+ * @param h Handle of the stream
+ * @return
+ *    - ESP_OK: Success
+ *    - ESP_ERR_NOT_SUPPORTED: Stream is not a decoder stream
+ *    - Others: Fail
+ */
+esp_err_t audio_stream_resume(audio_stream_handle_t h);
+
+/**
+ * @brief Direct write raw PCM data to a stream
+ *
+ * Only supported for RAW type streams.
+ * Data format must match the mixer configuration (e.g. 44.1kHz, 16-bit, mono/stereo).
+ *
+ * @param h Handle of the stream
+ * @param data Pointer to the PCM data
+ * @param size Size of the data in bytes
+ * @param timeout_ms Timeout in milliseconds to wait for space in the stream's buffer
+ * @return
+ *    - ESP_OK: Success
+ *    - ESP_ERR_NOT_SUPPORTED: Stream is not a raw stream
+ *    - Others: Fail
+ */
+esp_err_t audio_stream_write_pcm(audio_stream_handle_t h, void *data, size_t size, uint32_t timeout_ms);
+
+/**
+ * @brief Send an event to a raw stream's callback
+ *
+ * Allows manual state management for raw streams.
+ *
+ * @param h Handle of the stream
+ * @param event Event to send
+ * @return
+ *    - ESP_OK: Success
+ *    - ESP_ERR_NOT_SUPPORTED: Stream is not a raw stream
+ */
+esp_err_t audio_stream_raw_send_event(audio_stream_handle_t h, audio_player_callback_event_t event);
+
+/**
+ * @brief Create a new audio stream
+ *
+ * @param cfg Pointer to the stream configuration structure
+ * @return Handle to the new stream, or NULL if failed
+ */
+audio_stream_handle_t audio_stream_new(audio_stream_config_t *cfg);
+
+/**
+ * @brief Delete an audio stream and free its resources
+ *
+ * @param h Handle of the stream to delete
+ * @return
+ *    - ESP_OK: Success
+ *    - Others: Fail
+ */
+esp_err_t audio_stream_delete(audio_stream_handle_t h);
+
+#ifdef __cplusplus
+}
+#endif