syncfusion-blazor-speech-to-text

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syncfusion Blazor Speech To Text

Syncfusion Blazor 语音转文本

A comprehensive guide for implementing voice input and speech recognition using the Syncfusion Blazor SpeechToText component. This component captures audio from the user's microphone and converts it to text in real time.
本文是一份关于使用Syncfusion Blazor SpeechToText组件实现语音输入和语音识别的综合指南。该组件可捕获用户麦克风的音频并实时转换为文本。

Component Overview

组件概述

The SpeechToText component provides voice input capabilities by leveraging the browser's Speech Recognition API. It automatically handles microphone access, captures audio, transcribes speech, and manages the listening lifecycle.
Key Features:
  • Real-time speech-to-text conversion
  • Multi-language support (en-US, fr-FR, de-DE, and 100+ languages)
  • Listening state management (Inactive, Listening, Stopped)
  • Interim results for real-time feedback
  • Error handling for various microphone/network issues
  • Browser compatibility detection
  • Customizable tooltips and disabled states
  • Event callbacks for lifecycle hooks
SpeechToText组件通过浏览器的语音识别API提供语音输入功能。它会自动处理麦克风权限获取、音频捕获、语音转录以及监听生命周期管理。
核心特性:
  • 实时语音转文本转换
  • 多语言支持(包含en-US、fr-FR、de-DE等100+种语言)
  • 监听状态管理(未激活、正在监听、已停止)
  • 提供实时反馈的临时转录结果
  • 针对各类麦克风/网络问题的错误处理
  • 浏览器兼容性检测
  • 可自定义的提示框和禁用状态
  • 生命周期钩子的事件回调

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Installation via NuGet package
  • Basic component setup and configuration
  • Property binding and two-way data binding
  • CSS styling and theming
  • Integration with TextArea for display
  • Minimal working example
📄 阅读: references/getting-started.md
  • 通过NuGet包安装组件
  • 基础组件配置与设置
  • 属性绑定和双向数据绑定
  • CSS样式与主题定制
  • 与TextArea集成以显示转录内容
  • 最简可运行示例

Transcript and Language

转录文本与语言设置

📄 Read: references/transcript-and-language.md
  • Retrieving transcribed text with Transcript property
  • Binding transcript to input fields
  • Setting language preferences (en-US, fr-FR, etc.)
  • Supported language codes and locales
  • Real-world multi-language examples
  • Language switching patterns
📄 阅读: references/transcript-and-language.md
  • 通过Transcript属性获取转录文本
  • 将转录文本绑定到输入字段
  • 设置语言偏好(如en-US、fr-FR等)
  • 支持的语言代码与区域设置
  • 多语言实际应用示例
  • 语言切换实现模式

Button Customization

按钮自定义

📄 Read: references/button-customization.md
  • SpeechToTextButtonSettings configuration
  • Button text customization (start and stop states)
  • Icon CSS classes and icon positioning
  • Icon position values (Left, Right, Top, Bottom)
  • Primary button styling (IsPrimary property)
  • Dynamic button customization patterns
  • Icon library integration (Syncfusion, Font Awesome, Bootstrap)
  • Multi-language button text examples
📄 阅读: references/button-customization.md
  • SpeechToTextButtonSettings配置
  • 按钮文本自定义(开始和停止状态)
  • 图标CSS类与图标位置设置
  • 图标位置选项(左、右、上、下)
  • 主按钮样式(IsPrimary属性)
  • 动态按钮自定义模式
  • 图标库集成(Syncfusion、Font Awesome、Bootstrap)
  • 多语言按钮文本示例

Tooltip Configuration

提示框配置

📄 Read: references/tooltip-configuration.md
  • SpeechToTextTooltipSettings configuration
  • Tooltip text customization for different states
  • Tooltip positioning (12 position options available)
  • Position reference guide and best practices
  • ShowTooltip property control
  • Dynamic tooltip enabling/disabling
  • Multi-language tooltip support
  • Accessibility considerations for tooltips
📄 阅读: references/tooltip-configuration.md
  • SpeechToTextTooltipSettings配置
  • 不同状态下的提示框文本自定义
  • 提示框位置设置(支持12种位置选项)
  • 位置参考指南与最佳实践
  • ShowTooltip属性控制
  • 动态启用/禁用提示框
  • 多语言提示框支持
  • 提示框的无障碍访问考量

Listening States

监听状态

📄 Read: references/listening-states.md
  • Understanding ListeningState property
  • State values: Inactive, Listening, Stopped
  • Event handling: SpeechRecognitionStarted, SpeechRecognitionStopped
  • State-based UI updates and visual feedback
  • Waveform animations during listening
  • Status indicators and user guidance
📄 阅读: references/listening-states.md
  • 理解ListeningState属性
  • 状态值:未激活、正在监听、已停止
  • 事件处理:SpeechRecognitionStarted、SpeechRecognitionStopped
  • 基于状态的UI更新与视觉反馈
  • 监听时的波形动画
  • 状态指示器与用户引导

Interim Results and Configuration

临时结果与配置

📄 Read: references/interim-results-and-options.md
  • AllowInterimResults property for real-time updates
  • Difference between interim and final results
  • ShowTooltip property and tooltip customization
  • Disabled state configuration
  • HTML attributes for custom styling
  • Control panel options and UI customization
📄 阅读: references/interim-results-and-options.md
  • AllowInterimResults属性实现实时更新
  • 临时结果与最终结果的区别
  • ShowTooltip属性与提示框自定义
  • 禁用状态配置
  • 用于自定义样式的HTML属性
  • 控制面板选项与UI定制

Public Methods

公共方法

📄 Read: references/methods.md
  • StartListeningAsync() - Start speech recognition
  • StopListeningAsync() - Stop speech recognition
  • Method signatures and return types
  • Exception handling patterns
  • Complete control examples with start/stop buttons
  • State management and button disabling
📄 阅读: references/methods.md
  • StartListeningAsync() - 启动语音识别
  • StopListeningAsync() - 停止语音识别
  • 方法签名与返回类型
  • 异常处理模式
  • 包含启动/停止按钮的完整控制示例
  • 状态管理与按钮禁用

Error Handling and Troubleshooting

错误处理与故障排除

📄 Read: references/error-handling.md
  • Error types: no-speech, aborted, audio-capture, not-allowed, network, etc.
  • Error handling patterns and recovery
  • User feedback mechanisms for errors
  • Network and service availability issues
  • Microphone permission troubleshooting
  • Browser compatibility checking
📄 阅读: references/error-handling.md
  • 错误类型:无语音输入、已中止、音频捕获失败、权限被拒绝、网络错误等
  • 错误处理模式与恢复策略
  • 错误场景下的用户反馈机制
  • 网络与服务可用性问题
  • 麦克风权限故障排除
  • 浏览器兼容性检查

Browser Support and API Limitations

浏览器支持与API限制

📄 Read: references/browser-support.md
  • Browser compatibility matrix
  • Version requirements for Chrome, Edge, Safari, Opera
  • Unsupported browsers (Firefox)
  • Feature detection and polyfills
  • Graceful degradation for unsupported browsers
📄 阅读: references/browser-support.md
  • 浏览器兼容性矩阵
  • Chrome、Edge、Safari、Opera的版本要求
  • 不支持的浏览器(Firefox)
  • 特性检测与polyfill方案
  • 对不支持浏览器的优雅降级处理

Quick Start Example

快速入门示例

Here's a minimal example to get started with SpeechToText:
razor
@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 = "";
}
What this does:
  1. Renders a microphone button from SpeechToText
  2. Binds the transcribed text to the
    transcript
    variable
  3. Displays the transcript in a TextArea for editing
  4. Uses two-way binding to keep both in sync
以下是一个使用SpeechToText的最简示例:
razor
@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. 使用双向绑定保持两者同步

Common Patterns

常见实现模式

Pattern 1: Real-Time Transcription Display

模式1:实时转录内容显示

Display interim results as the user speaks (not just final results):
razor
<SfSpeechToText 
    AllowInterimResults="true"
    @bind-Transcript="@transcript">
</SfSpeechToText>
<p>@transcript</p>
在用户说话时显示临时转录结果(而非仅显示最终结果):
razor
<SfSpeechToText 
    AllowInterimResults="true"
    @bind-Transcript="@transcript">
</SfSpeechToText>
<p>@transcript</p>

Pattern 2: Multi-Language Support

模式2:多语言支持

Allow users to switch between languages:
razor
<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 = "";
}
允许用户切换语言:
razor
<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 = "";
}

Pattern 3: Listen for State Changes

模式3:监听状态变化

Provide visual feedback based on listening state:
razor
<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;
    }
}
根据监听状态提供视觉反馈:
razor
<SfSpeechToText 
    ListeningState="@listeningState"
    SpeechRecognitionStarted="@OnListeningStarted"
    SpeechRecognitionStopped="@OnListeningStopped">
</SfSpeechToText>

<div style="margin-top: 15px;">
    @if (listeningState == SpeechToTextState.Listening)
    {
        <span style="color: green;">🎤 正在监听...</span>
    }
    else if (listeningState == SpeechToTextState.Stopped)
    {
        <span style="color: orange;">⏸ 已停止</span>
    }
    else
    {
        <span style="color: gray;">○ 准备就绪</span>
    }
</div>

@code {
    private SpeechToTextState listeningState = SpeechToTextState.Inactive;

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

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

Pattern 4: Error Handling

模式4:错误处理

Gracefully handle errors and inform users:
razor
<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}"
        };
    }
}
优雅处理错误并通知用户:
razor
<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" => "未检测到语音,请重试。",
            "audio-capture" => "未找到麦克风,请检查设备。",
            "not-allowed" => "麦克风权限被拒绝,请检查浏览器设置。",
            "network" => "网络错误,请检查连接。",
            _ => $"错误:{args.Error}"
        };
    }
}

Key Properties

核心属性

PropertyTypeDefaultPurpose
Transcript
string""Two-way binding for transcribed text
Language
string"en-US"Language code for speech recognition
ListeningState
SpeechToTextStateInactiveCurrent state (Inactive, Listening, Stopped)
AllowInterimResults
booltrueShow interim results while speaking
ShowTooltip
booltrueDisplay tooltip on hover
Disabled
boolfalseDisable the component
HtmlAttributes
Dictionary-Custom HTML attributes for button
属性类型默认值用途
Transcript
string""转录文本的双向绑定属性
Language
string"en-US"语音识别的语言代码
ListeningState
SpeechToTextStateInactive当前监听状态(未激活、正在监听、已停止)
AllowInterimResults
booltrue是否在说话时显示临时结果
ShowTooltip
booltrue鼠标悬停时是否显示提示框
Disabled
boolfalse是否禁用组件
HtmlAttributes
Dictionary-按钮的自定义HTML属性

Common Use Cases

常见应用场景

  1. Voice Search: Add voice input to a search box for hands-free searching
  2. Form Filling: Populate form fields using voice input instead of typing
  3. Notes Application: Capture voice notes and convert to text
  4. Accessibility: Enable voice input for users with typing limitations
  5. Multilingual Chat: Support speech input in multiple languages for chat applications
  6. Dictation Feature: Create a dictation tool for long-form text entry
  7. Customer Support: Record and transcribe customer feedback or support calls
  8. Accessibility Compliance: Meet WCAG requirements for voice-enabled interfaces

  1. 语音搜索: 为搜索框添加语音输入,实现免提搜索
  2. 表单填写: 使用语音输入填充表单字段,替代手动输入
  3. 笔记应用: 捕获语音笔记并转换为文本
  4. 无障碍访问: 为有输入障碍的用户提供语音输入功能
  5. 多语言聊天: 为聊天应用支持多语言语音输入
  6. 听写功能: 构建用于长文本输入的听写工具
  7. 客户支持: 记录并转录客户反馈或支持通话内容
  8. 无障碍合规: 实现符合WCAG标准的语音启用界面

Next Steps

下一步操作

  • Start with Getting Started reference for installation
  • Explore Transcript and Language for basic usage
  • Check Browser Support to ensure compatibility
  • Review Error Handling for production-ready implementation
  • 快速入门文档开始学习组件安装
  • 探索转录文本与语言设置了解基础用法
  • 查看浏览器支持确保兼容性
  • 参考错误处理文档实现生产级别的稳定功能