Initial public release of the 2024A software.

managed_components/chmorgan__esp-audio-player/README.md

@@ -0,0 +1,80 @@
+# Audio player component for esp32
+
+
+[![cppcheck-action](https://github.com/chmorgan/esp-audio-player/actions/workflows/cppcheck.yml/badge.svg)](https://github.com/chmorgan/esp-audio-player/actions/workflows/cppcheck.yml)
+
+## Capabilities
+
+* MP3 decoding (via libhelix-mp3)
+* Wav/wave file decoding
+
+## Who is this for?
+
+Decode only audio playback on esp32 series of chips, where the features and footprint of esp-adf are not 
+necessary.
+
+## What about esp-adf?
+
+This component is not intended to compete with esp-adf, a much more fully developed
+audio framework.
+
+It does however have a number of advantages at the moment including:
+
+* Fully open source (esp-adf has a number of binary modules at the moment)
+* Minimal size (it's less capable, but also simpler, than esp-adf)
+
+## Getting started
+
+### Examples
+
+* [esp-box mp3_demo](https://github.com/espressif/esp-box/tree/master/examples/mp3_demo) uses esp-audio-player.
+* The [test example](https://github.com/chmorgan/esp-audio-player/tree/main/test) is a simpler example than mp3_demo that also uses the esp-box hardware.
+
+### How to use this?
+[esp-audio-player is a component](https://components.espressif.com/components/chmorgan/esp-audio-player) on the [Espressif component registry](https://components.espressif.com).
+
+In your project run:
+```
+idf.py add-dependency chmorgan/esp-audio-player
+```
+
+to add the component dependency to the project's manifest file.
+
+
+## Dependencies
+
+For MP3 support you'll need the [esp-libhelix-mp3](https://github.com/chmorgan/esp-libhelix-mp3) component.
+
+## Tests
+
+Unity tests are implemented in the [test/](../test) folder.
+
+## States
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle : new(), cb(IDLE)
+    Idle --> Playing : play(), cb(PLAYING)
+    Playing --> Paused : pause(), cb(PAUSE)
+    Paused --> Playing : resume(), cb(PLAYING)
+    Playing --> Playing : play(), cb(COMPLETED_PLAYING_NEXT)
+    Paused --> Idle : stop(), cb(IDLE)
+    Playing --> Idle : song complete, cb(IDLE)
+    [*] --> Shutdown : delete(), cb(SHUTDOWN)
+    Shutdown --> Idle : new(), cb(IDLE)
+```
+
+Note: Diagram shortens callbacks from AUDIO_PLAYER_EVENT_xxx to xxx, and functions from audio_player_xxx() to xxx(), for clarity.
+
+
+## Release process - Pushing component to the IDF Component Registry
+
+The github workflow, .github/workflows/esp_upload_component.yml, pushes data to the espressif
+[IDF component registry](https://components.espressif.com).
+
+To push a new version:
+
+* Apply a git tag via 'git tag vA.B.C'
+* Push tags via 'git push --tags'
+
+The github workflow *should* run and automatically push to the IDF component registry.