Skip to content
Get started

Audio HTTP Media Source

The audio_http media source platform plays audio streamed from HTTP and HTTPS URLs. Audio is fetched over the network and decoded on the device.

Files are played using the http:// or https:// URI scheme.

This component only works on ESP32 based chips.

Decoding is provided by the microDecoder library, which supports MP3, FLAC, Opus (Ogg-encapsulated), and WAV. To keep firmware size small, MP3, FLAC, and Opus decoders are compiled in only when another component in the configuration requests them; WAV is always available. A codec is enabled when any of the following is true:

# Example configuration entry


media_source:
  - platform: audio_http
    id: http_source

To play a file, send a media URL like https://example.com/audio/alert.mp3 to a media player that uses this media source.

HTTPS and TLS certificates

Section titled “HTTPS and TLS certificates”

HTTPS URLs are validated against ESP-IDF’s bundled X.509 certificate store (the same Mozilla root CA list used by other ESPHome components). By default, ESPHome includes only the common-CA subset, which covers the vast majority of public servers; set use_full_certificate_bundle: true under the esp32 component’s advanced options for the full bundle. Servers using self-signed certificates or private CAs fail to connect with the built-in bundle. To trust a private CA, point ca_certificate_path at the CA certificate file:

# Example configuration entry
media_source:
  - platform: audio_http
    ca_certificate_path: ca_cert.pem

A media source without its own ca_certificate_path uses the one set on http_request, so a single declaration covers both components. See ca_certificate_path under Configuration variables for when this applies.

http_request:
  ca_certificate_path: ca_cert.pem


media_source:
  - platform: audio_http   # uses the CA above

verify_ssl: false under http_request does not turn off certificate verification for media playback; use ca_certificate_path instead.

Configuration variables

Section titled “Configuration variables”
  • id (Optional, ID): Manually specify the ID for this media source.
  • buffer_size (Optional, int): The size of the ring buffer in bytes used to transfer data between the HTTP reader and the audio decoder. Minimum is 5000, maximum is 1000000. Defaults to 50000.
  • persistent_ring_buffer (Optional, boolean): If true, pre-allocate the decoder ring buffer when the media source is set up, normally during device startup, and retain it between URL playback sessions. This avoids repeated allocation and release of a contiguous buffer, which can help devices that run several memory-intensive components concurrently. The buffer consumes buffer_size bytes while playback is stopped. If pre-allocation fails, allocation is retried when playback starts. Defaults to false.
  • ca_certificate_path (Optional, path): Path to a PEM file containing the CA certificate(s) used to verify the server for https:// playback URLs. The file is read at build time and embedded in the firmware, so re-flash after rotating the CA certificate. It replaces, rather than extends, ESP-IDF’s bundled certificate store for this media source. Relative paths are resolved against the configuration directory. If omitted, the http_request component’s ca_certificate_path is used, unless http_request sets verify_ssl: false. A path set here is used whatever verify_ssl is set to.
  • task_stack_in_psram (Optional, boolean): If true, the FreeRTOS decode task stack is allocated in PSRAM instead of internal RAM. Requires the psram component. Defaults to false.
  • All other options from Media Source.

See Also

Section titled “See Also”