document support for ogg opus decoding and changes to the codec_support_enabled option

Author: kahrendt

src/content/docs/components/media_player/speaker.mdx

@@ -7,7 +7,7 @@ The `speaker` media player platform allows you to play on-device and online audi
 
 This platform greatly benefits from having external PSRAM. See the [performance section](#media_player-speaker-performance) for details.
 
-It natively supports decoding `FLAC`, `MP3`, and `WAV` audio files. Home Assistant (since version 2024.10) can proxy any media it sends and transcode it to a specified format and sample rate to minimize the device's computational load.
+It natively supports decoding `FLAC`, `MP3`, `OPUS`, and `WAV` audio files. Home Assistant (since version 2024.10) can proxy any media it sends and transcode it to a specified format and sample rate to minimize the device's computational load.
 
 It supports two different audio pipelines: announcement and media. Each audio pipeline must output to a unique speaker. Use a [mixer speaker](/components/speaker/mixer/) component to create two different speakers that output to a single audio speaker.
 
@@ -35,13 +35,13 @@ media_player:
 - **announcement_pipeline** (**Required**, Pipeline Schema): Configuration settings for the announcement pipeline.
 
   - **speaker** (**Required**, [ID](/guides/configuration-types#id)): The [speaker](/components/speaker/) to output the audio.
-  - **format** (*Optional*, enum): The audio format Home Assistant will transcode audio to before sending it to the device. One of `FLAC`, `MP3`, `WAV`, or `NONE`. `NONE` disables transcoding in Home Assistant. Defaults to `FLAC`.
-  - **sample_rate** (*Optional*, positive integer): Sample rate for the transcoded audio. Should be supported by the configured `speaker` component. Defaults to the speaker's sample rate.
+  - **format** (*Optional*, enum): The audio format Home Assistant will transcode audio to before sending it to the device. One of `FLAC`, `MP3`, `OPUS`, `WAV`, or `NONE`. `NONE` disables transcoding in Home Assistant. Defaults to `FLAC`.
+  - **sample_rate** (*Optional*, positive integer): Sample rate for the transcoded audio. Should be supported by the configured `speaker` component. Defaults to the speaker's sample rate. The `OPUS` codec only supports a `48000` sample rate.
   - **num_channels** (*Optional*, positive integer): Number of channels for the transcoded audio. Must be either `1` or `2`. Defaults to the speaker's number of channels.
 
 - **media_pipeline** (*Optional*, Pipeline Schema): Configuration settings for the media pipeline. Same options as the `announcement_pipeline`.
 - **buffer_size** (*Optional*, positive integer): The buffer size in bytes for each pipeline. Must be between `4000` and `4000000`. Defaults to `1000000`.
-- **codec_support_enabled** (*Optional*, boolean): Enables the MP3 and FLAC decoders. Defaults to `true`.
+- **codec_support_enabled** (*Optional*, enum): Controls which audio codecs (MP3, FLAC, Opus) are compiled. One of `ALL` (all available codecs are supported), `NEEDED` (only codecs needed to play the pipelines' preferred formats and included files), or `NONE` (only supports WAV files). Defaults to `NEEDED`.
 - **task_stack_in_psram** (*Optional*, boolean): Run the audio tasks in external memory. Defaults to `false`.
 - **volume_increment** (*Optional*, percentage): Increment amount that the `media_player.volume_up` and `media_player.volume_down` actions will increase or decrease volume by. Defaults to `5%`.
 - **volume_initial** (*Optional*, percentage): The default volume that mediaplayer uses for first boot where a volume has not been previously saved. Defaults to `50%`.
@@ -165,7 +165,7 @@ Configuration variables:
 
 ## Performance
 
-Decoding audio files is CPU and memory intensive. PSRAM external memory is strongly recommended. To use the component on a memory constrained device, define only the announcement pipeline, decrease the buffer size, set `codec_support_enabled` to false, and set the pipeline transcode setting format to `WAV` with a low sample rate and only 1 channel.
+Decoding audio files is CPU and memory intensive. PSRAM external memory is strongly recommended. To use the component on a memory constrained device, define only the announcement pipeline, decrease the buffer size, and set the pipeline transcode setting format to `WAV` with a low sample rate and only 1 channel.
 
 ### Network Optimizations
 
@@ -180,6 +180,8 @@ If you experience out-of-memory issues, you can disable these optimizations by s
 
 In general, decoding FLAC has the lowest CPU usage, but requires a strong WiFi connection. Decoding MP3 requires less data to be sent over WiFi but is more CPU intensive to decode. Decoding WAV is only recommended at low sample rates if streamed over a network connection.
 
+Decoding OPUS is extremely CPU and memory intensive and may not even decode in real-time on an ESP32. It is only suitable for ESP32-S3 devices with PSRAM.
+
 Increasing the buffer size may reduce stuttering, but do not set it to the entire size of the external memory. Each pipeline allocates the configured amount, and this setting also does not take into account other smaller buffers allocated throughout the audio stack.
 
 Only set `task_stack_in_psram` to true if you have many components configured and your logs show that memory allocation failed. It is slower, especially if your PSRAM doesn't support `octal` mode.