From 9179f09aa14f1cbc59cb7b26c844935f80c627e6 Mon Sep 17 00:00:00 2001
From: Erik Montnemery <erik@montnemery.com>
Date: Fri, 25 Oct 2024 07:52:10 +0200
Subject: [PATCH] Document WebRTC configuration (#35351)

* Document WebRTC configuration

* Apply suggestions from code review

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update homeassistant.markdown

* Update homeassistant.markdown

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---
 source/_integrations/homeassistant.markdown | 52 +++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/source/_integrations/homeassistant.markdown b/source/_integrations/homeassistant.markdown
index 96260028206..da9b70919ff 100644
--- a/source/_integrations/homeassistant.markdown
+++ b/source/_integrations/homeassistant.markdown
@@ -141,6 +141,10 @@ debug:
   required: false
   type: boolean
   default: false
+webrtc:
+  description: A [custom list of STUN and TURN servers for WebRTC video streaming](#custom-stun-and-turn-servers).
+  required: false
+  type: map
 {% endconfiguration %}
 
 ## Editing entity settings in YAML
@@ -251,6 +255,54 @@ homeassistant:
       icon: mdi:other
 ```
 
+## Custom STUN and TURN servers
+
+It's possible to override the default list of STUN and TURN servers which are used to initiate WebRTC streaming.
+Each STUN or TURN server can be configured as described in the table below.
+
+{% configuration webrtc %}
+ice_servers:
+  description: List of STUN and TURN server configurations
+  required: true
+  type: list
+  keys:
+    url:
+      description: STUN or TURN server URLs. This can either be a single URL or a list of URLs.
+      required: true
+      type: string
+    username:
+      description: Username for TURN server authentication
+      required: false
+      type: string
+    credential:
+      description: Credential for TURN server authentication
+      required: false
+      type: string
+{% endconfiguration %}
+
+### WebRTC configuration example
+
+{% important %}
+If you implement `webrtc` in your {% term "`configuration.yaml`" %} file, you must make sure it is done inside of `homeassistant:` or it will fail.
+{% endimportant %}
+
+```yaml
+homeassistant:
+  name: Home
+  unit_system: metric
+  # etc
+
+  webrtc:
+    ice_servers:
+    # Add an entry for each STUN or TURN server
+    - url:
+      - "stun:stun.l.google.com:19302"
+      - "stun:stun1.l.google.com:3478"
+    - url: "turn:turn.domain.com"
+      username: "username"
+      credential: "abc123"
+```
+
 ## Actions
 
 The `homeassistant` integration provides actions for controlling Home Assistant itself, as well as generic controls for any entity.