update articles

Author: didiyordanova

controls/speechtotextbutton/custom-recognizer.md

@@ -29,7 +29,7 @@ xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui"
 
 <snippet id='speechtotext-mycustomrecognizer' />
 
-**4.** Set the `SpeechRecognizer` property of the `RadSpeechToTextButton` to an instance of your custom recognizer:
+**4.** Set the `SpeechRecognizerCreator` property of the `RadSpeechToTextButton` to an instance of your custom recognizer:
 
 <snippet id='speechtotext-speech-recognizer-creator' />
 

controls/speechtotextbutton/events.md

@@ -26,6 +26,10 @@ The .NET MAUI SpeechToTextButton exposes the following events:
 		* `Exception` (`System.Exception`) property that contains the exception associated with the speech recognizer error, if any.
 		* `Handled` (`bool`) property that determines whether the error has been handled. Set this to `true` to prevent the default error handling behavior.
 
+* `StateChanged`—Raaised when the state of the speech recognizer changes. The `StateChanged` event handler receives two parameters:
+	* The `sender` argument which is of type `object` but can be cast to `RadSpeechToTextButton`.
+	* An `System.EventArgs`.
+
 ## Example
 
 Here is an example using the `SpeechRecognized` and `ErrorOccurred` events:

controls/speechtotextbutton/getting-started.md

@@ -24,6 +24,35 @@ Before adding the SpeechToTextButton, you need to:
 
 1. [Install Telerik UI for .NET MAUI]({%slug maui-getting-started %}#step-3-install-telerik-ui-for-net-maui).
 
+## Required Permissions
+
+Before adding the contol, ensure that you have the required permissions set up in your project:
+
+### Android
+
+Add the following permissions to your `AndroidManifest.xml` file:
+
+```xml
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+```
+
+### iOS and MacCatalyst
+
+Add the `NSMicrophoneUsageDescription` and `NSSpeechRecognitionUsageDescription` permissions to your `Info.plist` file:
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>The SpeechToTextButton requires access to microphone.</string>
+<key>NSSpeechRecognitionUsageDescription</key>
+<string>The SpeechToTextButton requires access to the Speech Recognition service.</string>
+```
+
+### WinUI
+
+There are limitations when using the SpeechToTextButton on WinUI. When clicking on the control, the InvalidOperationException occurs.
+
+To turn speech recognition on WinUI, review the [WinUI Support]({%slug speechtotextbutton-winui-support%}) article.
+
 ## Define the Control
 
 **1.** When your .NET MAUI application is set up, you are ready to add a SpeechToTextButton control to your page:

controls/speechtotextbutton/images/speechtotext-architecture.png

@@ -17,11 +17,11 @@ When the user taps the button, the control uses a speech recognition service, li
 
 ## Key Features of the Telerik .NET MAUI SpeechToTextButton
 
-* [Visual States]({%slug speechtotextbutton-visual-states%})—The SpeechToTextButton supports different visual states such as Normal, Listening, Error, and more, providing visual feedback to users during speech recognition.
 * [Language Configuration]({%slug speechtotextbutton-configuration%}#language)—The SpeechToTextButton allows you to set the language for speech recognition, ensuring accurate transcription of spoken words into text.
 * [Events]({%slug speechtotextbutton-events%})—The SpeechToTextButton emits a set of events that allow you to configure the component's behavior in response to speech recognition, including `SpeechRecognized` and `ErrorOccurred` events.
 * [Commands]({%slug speechtotextbutton-commands%})—The SpeechToTextButton supports command execution, allowing you to bind commands to the button's actions in an MVVM-friendly way.
 * [Custom Speech Recognizer]({%slug speechtotextbutton-custom-recognizer%})—Implement your own speech recognition logic by creating a custom recognizer that implements the `IRadSpeechRecognizer` interface.
+* [Visual States]({%slug speechtotextbutton-visual-states%})—The SpeechToTextButton supports different visual states such as Normal, Listening, Error, and more, providing visual feedback to users during speech recognition.
 * [Styling API]({%slug speechtotextbutton-styling%})—You can customize the appearance of the SpeechToTextButton using the styling API, which allows you to set properties like background color, border color, corner radius, and more.
 
 ## Next Steps

controls/speechtotextbutton/overview.md

@@ -7,9 +7,15 @@ tags: .net maui, telerik speech to text button for .net maui, ui for .net maui
 slug: speechtotextbutton-states
 ---
 
-# .NET MAUI SpeechToTextButton States
+# .NET MAUI SpeechToTextButton Architecture and States
 
+The SpeechTextButton control provides visual feedback and handle user interactions. The button uses a speech recognition service. The service provides per platform implementation or an AI agent conenction. Almost all operations are asynconous.
 
+The SpeechToTextButton control in .NET MAUI has several states that reflect its current operation and user interaction. 
+
+The image below explains how the control works and how the states are managed: 
+
+![.NET MAUI SpeechToTextButton States](images/speechtotext-architecture.png)
 
 ## See Also
 

controls/speechtotextbutton/states.md

@@ -10,5 +10,37 @@ slug: speechtotextbutton-winui-support
 
 The Telerik UI for .NET MAUI SpeechToTextButton control is designed to work seamlessly across all supported platforms, including WinUI.
 
-However, there are some platform-specific considerations and limitations to be aware of when using the control on WinUI.
+The Speech Recognizer uses platform-specific speech recognition services. On WinUI, it relies on the [`Windows.Media.SpeechRecognition`](https://learn.microsoft.com/en-us/uwp/api/windows.media.speechrecognition?view=winrt-26100). However, there are specific considerations when using the control on WinUI due to platform limitations.
 
+## Limitations in Windows.Media.SpeechRecognition
+
+* The app crashes when trying to close the application via the "X" button and the app is **Packaged**. There is an open bug report: [Application crashes after using SpeechRecognizer in a Packaged App](https://github.com/microsoft/microsoft-ui-xaml/issues/10697)
+
+* Based on this issue, the SpeechToTextButton control is not fully supported on WinUI. When you click the control, an `InvalidOperationException` is thrown.
+
+## Solutions
+
+To use the SpeechToTextButton on WinUI, you can use one of the following approaches:
+
+* Set the `SpeechRecognizerCreator` property of the `RadSpeechToTextButton` to `RadSpeechRecognizer` for **Unpackaged** apps:
+
+```csharp
+this.speechToTextButton.SpeechRecognizerCreator = () => new RadSpeechRecognizer();
+```
+
+* Create a [custom recognizer]({%slug speechtotextbutton-custom-recognizer%}) for **Packaged** and **Unpackaged** apps.
+
+* Use an **Unpackaged** app deployment model.
+
+## Language Support
+
+When setting the `LanguageTag` to a specific value, ensure that the language is supported by the `Windows.Media.SpeechRecognition.SpeechRecognizer` on WinUI. 
+
+For more details, review the [Microsoft documentation](https://learn.microsoft.com/en-us/windows/apps/design/input/speech-recognition#predefined-grammars).
+
+## See Also
+
+- [Visual States in the SpeechToTextButton]({%slug speechtotextbutton-visual-states%})
+- [Configure the SpeechToTextButton]({%slug speechtotextbutton-configuration%})
+- [Events]({%slug speechtotextbutton-events%})
+- [Execute Commands]({%slug speechtotextbutton-commands%})