From 93139737ffe6193735d10175fecb733d0ea42c4d Mon Sep 17 00:00:00 2001
From: Michael Hansen <hansen.mike@gmail.com>
Date: Mon, 20 Mar 2023 22:59:32 -0500
Subject: [PATCH] Add documentation for pipeline WebSocket API (#1722)

* Add docs for pipelines

* Minor changes

* Fix parameter

* Fix other parameter
---
 docs/voice/pipelines/index.md | 43 +++++++++++++++++++++++++++++++++++
 sidebars.js                   |  1 +
 2 files changed, 44 insertions(+)
 create mode 100644 docs/voice/pipelines/index.md

diff --git a/docs/voice/pipelines/index.md b/docs/voice/pipelines/index.md
new file mode 100644
index 00000000..38651bd0
--- /dev/null
+++ b/docs/voice/pipelines/index.md
@@ -0,0 +1,43 @@
+---
+title: "Pipelines"
+---
+
+A pipeline runs the common steps of a [voice assistant](https://next.home-assistant.io/integrations/voice_assistant):
+
+1. Speech to text
+2. Intent recognition
+3. Text to speech
+
+Pipelines are run via a WebSocket API:
+
+```json
+{
+  "type": "voice_assistant/run",
+  "language": "en-US"
+}
+```
+
+The following input fields are available:
+
+| Name              | Type   | Description                                                                                 |
+|-------------------|--------|---------------------------------------------------------------------------------------------|
+| `intent_input`    | string | Required. Input text to process.                                                            |
+| `language`        | string | Optional. Language of pipeline to run (default: configured language in HA).                 |
+| `pipeline`        | string | Optional. Id of a pipeline to run (default: use first one that matches specified language). |
+| `conversation_id` | string | Optional. [Unique id for conversation](/docs/intent_conversation_api#conversation-id).      |
+| `timeout`         | number | Optional. Number of seconds before pipeline times out (default: 30).                        |
+
+## Events
+
+As the pipeline runs, it emits events back over the WebSocket connection.
+The following events can be emitted:
+
+| Name            | Description                 | Emitted    | Attributes                                                                                              |
+|-----------------|-----------------------------|------------|---------------------------------------------------------------------------------------------------------|
+| `run-start`     | Start of pipeline run       | always     | `pipeline` - Id of pipeline<br />`language` - Language used for pipeline<br />                        |
+| `run-finish`    | End of pipeline run         | always     |                                                                                                         |
+| `intent-start`  | Start of intent recognition | always     | `engine` - [Agent](/docs/intent_conversation_api) engine used<br />`intent_input` - Input text to agent |
+| `intent-finish` | End of intent recognition   | always     | `intent_output` - [conversation response](/docs/intent_conversation_api#conversation-response)          |
+| `tts-start`     | Start of text to speech     | audio only | `tts_input` - text to speak                                                                             |
+| `tts-finish`    | End of text to speech       | audio only | `tts_otuput` - URL of spoken audio                                                                      |
+
diff --git a/sidebars.js b/sidebars.js
index 4c76e8f1..3223a49f 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -248,6 +248,7 @@ module.exports = {
       ],
     },
 
+    "voice/pipelines/index",
     "voice/language-leaders",
     "voice/contributing-your-voice",
   ],