syncfusion-blazor-speech-to-text

Syncfusion Blazor Speech To Text

使用 Syncfusion Blazor SpeechToText 组件实现语音输入和语音识别的完整指南。此组件可捕获用户麦克风的音频，并实时将其转换为文本。

组件概述

SpeechToText 组件借助浏览器的语音识别 API 提供语音输入功能。它会自动处理麦克风访问、捕获音频、转录语音并管理聆听生命周期。

主要功能：

• 实时语音转文本
• 支持多种语言（en-US、fr-FR、de-DE 及 100 多种语言）
• 聆听状态管理（Inactive、Listening、Stopped）
• 提供实时反馈的中间结果
• 处理各种麦克风／网络问题
• 检测浏览器兼容性
• 可自定义工具提示和禁用状态
• 提供生命周期钩子的事件回调

文档和导航指南

快速入门

📄 阅读： references/getting-started.md

• 通过 NuGet 包安装
• 基本组件设置和配置
• 属性绑定和双向数据绑定
• CSS 样式和主题
• 与 TextArea 集成以显示内容
• 最简可运行示例

转录文本和语言

📄 阅读： references/transcript-and-language.md

• 使用 Transcript 属性获取转录文本
• 将转录文本绑定到输入字段
• 设置语言首选项（en-US、fr-FR 等）
• 支持的语言代码和区域设置
• 真实场景中的多语言示例
• 语言切换模式

按钮自定义

📄 阅读： references/button-customization.md

• SpeechToTextButtonSettings 配置
• 自定义按钮文本（开始和停止状态）
• 图标 CSS 类和图标位置
• 图标位置值（Left、Right、Top、Bottom）
• 主要按钮样式（IsPrimary 属性）
• 动态自定义按钮模式
• 集成图标库（Syncfusion、Font Awesome、Bootstrap）
• 多语言按钮文本示例

工具提示配置

📄 阅读： references/tooltip-configuration.md

• SpeechToTextTooltipSettings 配置
• 自定义不同状态的工具提示文本
• 工具提示位置（提供 12 种位置选项）
• 位置参考指南和最佳实践
• 控制 ShowTooltip 属性
• 动态启用／禁用工具提示
• 多语言工具提示支持
• 工具提示的无障碍注意事项

聆听状态

📄 阅读： references/listening-states.md

• 了解 ListeningState 属性
• 状态值：Inactive、Listening、Stopped
• 事件处理：SpeechRecognitionStarted、SpeechRecognitionStopped
• 基于状态的 UI 更新和视觉反馈
• 聆听期间的波形动画
• 状态指示器和用户指引

中间结果和配置

📄 阅读： references/interim-results-and-options.md

• 使用 AllowInterimResults 属性实时更新
• 中间结果与最终结果的区别
• ShowTooltip 属性和工具提示自定义
• 禁用状态配置
• 用于自定义样式的 HTML 属性
• 控制面板选项和 UI 自定义

公共方法

📄 阅读： references/methods.md

• StartListeningAsync() - 开始语音识别
• StopListeningAsync() - 停止语音识别
• 方法签名和返回类型
• 异常处理模式
• 使用开始／停止按钮进行完整控制的示例
• 状态管理和禁用按钮

错误处理和故障排除

📄 阅读： references/error-handling.md

• 错误类型：no-speech、aborted、audio-capture、not-allowed、network 等
• 错误处理模式和恢复方法
• 错误的用户反馈机制
• 网络和服务可用性问题
• 麦克风权限故障排除
• 浏览器兼容性检查

浏览器支持和 API 限制

📄 阅读： references/browser-support.md

• 浏览器兼容性矩阵
• Chrome、Edge、Safari、Opera 的版本要求
• 不支持的浏览器（Firefox）
• 特性检测和 polyfill
• 对不支持的浏览器进行平稳降级

快速入门示例

以下是使用 SpeechToText 快速入门的最简示例：

@using Syncfusion.Blazor.Inputs

<div style="display: flex; flex-direction: column; gap: 20px; align-items: center; padding: 20px;">
    <h3>Voice to Text Converter</h3>
    
    <SfSpeechToText @bind-Transcript="@transcript"></SfSpeechToText>
    
    <SfTextArea 
        RowCount="5" 
        ColumnCount="50" 
        @bind-Value="@transcript" 
        ResizeMode="Resize.None" 
        Placeholder="Transcribed text will appear here...">
    </SfTextArea>
</div>

@code {
    private string transcript = "";
}

此示例的功能：

1. 渲染 SpeechToText 的麦克风按钮
2. 将转录文本绑定到 transcript 变量
3. 在 TextArea 中显示转录文本以供编辑
4. 使用双向绑定使两者保持同步

常见模式

模式 1：实时转录显示

在用户说话时显示临时结果（而不仅是最终结果）：

<SfSpeechToText 
    AllowInterimResults="true"
    @bind-Transcript="@transcript">
</SfSpeechToText>
<p>@transcript</p>

模式 2：多语言支持

允许用户切换语言：

<select @onchange="@((ChangeEventArgs e) => selectedLanguage = e.Value.ToString())">
    <option value="en-US">English</option>
    <option value="fr-FR">French</option>
    <option value="de-DE">German</option>
</select>

<SfSpeechToText 
    Language="@selectedLanguage"
    @bind-Transcript="@transcript">
</SfSpeechToText>

@code {
    private string selectedLanguage = "en-US";
    private string transcript = "";
}

模式 3：监听状态变化

根据监听状态提供视觉反馈：

<SfSpeechToText 
    ListeningState="@listeningState"
    SpeechRecognitionStarted="@OnListeningStarted"
    SpeechRecognitionStopped="@OnListeningStopped">
</SfSpeechToText>

<div style="margin-top: 15px;">
    @if (listeningState == SpeechToTextState.Listening)
    {
        <span style="color: green;">🎤 Listening...</span>
    }
    else if (listeningState == SpeechToTextState.Stopped)
    {
        <span style="color: orange;">⏸ Stopped</span>
    }
    else
    {
        <span style="color: gray;">○ Ready to listen</span>
    }
</div>

@code {
    private SpeechToTextState listeningState = SpeechToTextState.Inactive;

    private void OnListeningStarted(SpeechRecognitionStartedEventArgs args)
    {
        listeningState = args.State;
    }

    private void OnListeningStopped(SpeechRecognitionStoppedEventArgs args)
    {
        listeningState = args.State;
    }
}

模式 4：错误处理

妥善处理错误并通知用户：

<SfSpeechToText 
    SpeechRecognitionError="@OnSpeechError"
    @bind-Transcript="@transcript">
</SfSpeechToText>

@if (!string.IsNullOrEmpty(errorMessage))
{
    <div style="color: red; margin-top: 10px;">
        ⚠️ @errorMessage
    </div>
}

@code {
    private string transcript = "";
    private string errorMessage = "";

    private void OnSpeechError(SpeechRecognitionErrorEventArgs args)
    {
        errorMessage = args.Error switch
        {
            "no-speech" => "No speech detected. Please try again.",
            "audio-capture" => "No microphone found. Check your device.",
            "not-allowed" => "Microphone access denied. Check browser permissions.",
            "network" => "Network error. Check your connection.",
            _ => $"Error: {args.Error}"
        };
    }
}

关键属性

属性	类型	默认值	用途
Transcript	string	""	转录文本的双向绑定
Language	string	"en-US"	语音识别的语言代码
ListeningState	SpeechToTextState	Inactive	当前状态（Inactive、Listening、Stopped）
AllowInterimResults	bool	true	说话时显示临时结果
ShowTooltip	bool	true	悬停时显示工具提示
Disabled	bool	false	禁用此组件
HtmlAttributes	Dictionary	-	按钮的自定义 HTML 属性

常见用例

1. 语音搜索： 在搜索框中添加语音输入，实现免手动搜索
2. 填写表单： 使用语音输入而非打字来填写表单字段
3. 笔记应用： 录制语音笔记并将其转换为文本
4. 无障碍访问： 为打字受限的用户启用语音输入
5. 多语言聊天： 在聊天应用中支持多语言语音输入
6. 听写功能： 创建用于长文本输入的听写工具
7. 客户支持： 录制并转录客户反馈或支持通话
8. 无障碍合规： 满足语音启用界面的 WCAG 要求

---

后续步骤

• 从 入门指南 参考文档开始安装
• 查看 转录文本和语言，了解基本用法
• 查看 浏览器支持，确保兼容性
• 查看 错误处理，了解适用于生产环境的实现方式