Add docs for media_player and i2s_audio (#2107)

Makefile

@@ -48,7 +48,7 @@ netlify-dependencies:
 copy-svg2png:
 	cp svg2png/*.png _build/html/_images/
 
-netlify: netlify-dependencies netlify-api html copy-svg2png
+netlify: netlify-dependencies netlify-api html svg2png copy-svg2png
 
 lint: html-strict
 	python3 lint.py

components/index.rst

@@ -20,4 +20,5 @@ Components
     stepper/index
     touchscreen/index
     lock/index
+    media_player/index
     *

components/media_player/i2s_audio.rst

@@ -0,0 +1,54 @@
+I2S Audio Media Player
+======================
+
+.. seo::
+    :description: Instructions for setting up I2S based media players in ESPHome.
+    :image: i2s_audio.svg
+
+The ``i2s_audio`` media player platform allows you to play media from webservers and web streams
+via the I2S bus. This platform only works on ESP32 based chips.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    media_player:
+      - platform: i2s_audio
+        name: ESPHome I2S Media Player
+        dac_type: external
+        i2s_lrclk_pin: GPIO33
+        i2s_dout_pin: GPIO22
+        i2s_bclk_pin: GPIO19
+        mode: mono
+
+Configuration variables:
+------------------------
+
+- **dac_type** (**Required**, enum)
+
+  - ``external``: Use an external DAC, for example the NS4168.
+  - ``internal``: Use the internal DAC
+
+- All other options from :ref:`Media Player <config-media_player>`
+
+External DAC
+************
+
+- **i2s_lrclk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I2S LRCLK signal.
+- **i2s_dout_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I2S DOUT signal.
+- **i2s_bclk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I2S BCLK signal.
+- **mode** (*Optional*, string): The mode of the I2S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``.
+
+Internal DAC
+************
+
+- **mode** (**Required**, enum): The channel mode of the internal DAC.
+
+  - ``left``
+  - ``right``
+  - ``stereo``
+
+See also
+--------
+
+- :doc:`index`
+- :ghedit:`Edit`

components/media_player/index.rst

@@ -0,0 +1,50 @@
+Media Player Components
+=======================
+
+.. seo::
+    :description: Instructions for setting up generic media players in ESPHome.
+    :image: folder-open.svg
+
+The ``media_player`` domain includes all platforms that implement media player
+functionality.
+
+.. note::
+
+    ESPHome media players require Home Assistant 2022.6 or newer.
+
+.. _config-media_player:
+
+Base Media Player Configuration
+-------------------------------
+
+.. code-block:: yaml
+
+    media_player:
+      - platform: ...
+        name: "Media Player Name"
+
+Configuration variables:
+
+- **name** (**Required**, string): The name of the media player.
+- **icon** (*Optional*, icon): Manually set the icon to use for the
+  media player in the frontend.
+- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
+  not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
+  a ``name`` will implicitly set this to true.
+- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
+  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
+  Defaults to ``false``.
+- **entity_category** (*Optional*, string): The category of the entity.
+  See https://developers.home-assistant.io/docs/core/entity/#generic-properties
+  for a list of available options. Set to ``""`` to remove the default entity category.
+
+See Also
+--------
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *
+
+- :ghedit:`Edit`

images/i2s_audio.svg

@@ -0,0 +1 @@
+<svg width="527.266" height="25mm" viewBox="0 0 139.506 25" xmlns="http://www.w3.org/2000/svg"><path style="fill:#000;fill-opacity:1;stroke-width:.133497;stroke-miterlimit:4;stroke-dasharray:none" d="M5 0h129.506c2.77 0 5 2.23 5 5v15c0 2.77-2.23 5-5 5H5c-2.77 0-5-2.23-5-5V5c0-2.77 2.23-5 5-5Z"/><g aria-label="I2S AUDIO" style="font-size:10.5833px;line-height:1.25;letter-spacing:1.08479px;fill:#fffffc;stroke-width:.264583"><path d="M10.138 20.666H6.48V4.86h3.658ZM18.99 17.685h6.796v2.98H13.842v-2.37l6.096-5.757q.97-.926 1.31-1.58.338-.678.338-1.333 0-.948-.655-1.445-.632-.52-1.874-.52-1.038 0-1.874.407-.835.384-1.4 1.174L13.12 7.525q.926-1.377 2.552-2.144 1.625-.79 3.725-.79 1.761 0 3.07.586 1.333.565 2.055 1.626.745 1.039.745 2.46 0 1.288-.542 2.417-.542 1.129-2.1 2.574zM34.57 20.937q-1.875 0-3.636-.497-1.738-.52-2.8-1.332l1.242-2.755q1.016.745 2.416 1.197 1.4.452 2.8.452 1.558 0 2.303-.452.745-.474.745-1.242 0-.564-.452-.926-.429-.383-1.129-.61-.677-.225-1.85-.496-1.807-.429-2.959-.858-1.151-.429-1.986-1.377-.813-.948-.813-2.529 0-1.377.745-2.483.745-1.13 2.235-1.784 1.513-.655 3.68-.655 1.513 0 2.958.362 1.445.36 2.529 1.038l-1.13 2.777q-2.19-1.242-4.38-1.242-1.535 0-2.28.497-.722.497-.722 1.31 0 .812.835 1.219.858.384 2.597.767 1.806.43 2.957.858 1.152.43 1.965 1.355.835.926.835 2.506 0 1.355-.768 2.484-.745 1.106-2.257 1.76-1.513.656-3.68.656zM67.987 20.666h-3.839l-1.4-3.387h-7.337l-1.4 3.387h-3.748L57.307 4.86h3.613zM59.09 8.45l-2.506 6.051h5.012zM77.403 20.937q-3.387 0-5.284-1.874-1.874-1.874-1.874-5.351v-8.85h3.658v8.714q0 4.245 3.522 4.245 1.716 0 2.62-1.016.902-1.039.902-3.229V4.861h3.613v8.85q0 3.478-1.897 5.352-1.874 1.874-5.26 1.874zM89.257 20.666V4.86h7.18q2.574 0 4.538.994 1.987.97 3.07 2.754 1.107 1.784 1.107 4.154 0 2.371-1.107 4.155-1.083 1.783-3.07 2.777-1.964.97-4.538.97zm7-3.003q2.37 0 3.77-1.31 1.422-1.332 1.422-3.59 0-2.257-1.422-3.567-1.4-1.332-3.77-1.332h-3.342v9.799zM112.649 20.666h-3.658V4.86h3.658zM125.135 20.937q-2.46 0-4.448-1.062-1.964-1.06-3.093-2.912-1.106-1.874-1.106-4.2 0-2.325 1.106-4.176 1.13-1.874 3.093-2.936 1.987-1.06 4.448-1.06 2.461 0 4.426 1.06 1.964 1.062 3.093 2.936 1.129 1.851 1.129 4.176 0 2.326-1.13 4.2-1.128 1.851-3.092 2.912-1.965 1.062-4.426 1.062zm0-3.116q1.4 0 2.529-.632 1.129-.655 1.761-1.807.655-1.151.655-2.619 0-1.467-.655-2.619-.632-1.151-1.761-1.783-1.129-.655-2.529-.655t-2.528.655q-1.13.632-1.784 1.783-.632 1.152-.632 2.62 0 1.467.632 2.618.655 1.152 1.784 1.807 1.128.632 2.528.632z" style="font-weight:700;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat, Bold'"/></g></svg>

index.rst

@@ -631,6 +631,14 @@ Lock Components
     Generic Output Lock, components/lock/output, upload.svg
     Template Lock, components/lock/template, description.svg
 
+Media Player Components
+-----------------------
+
+.. imgtable::
+
+    Media Player Core, components/media_player/index, folder-open.svg
+    I2S Audio, components/media_player/i2s_audio, i2s_audio.svg
+
 Misc Components
 ---------------