syncfusion-react-speech-to-text

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syncfusion React SpeechToText Component

Syncfusion React SpeechToText组件

Component Overview

组件概述

The SpeechToText component enables users to convert spoken words into text using the Web Speech API. This skill helps you implement, customize, and troubleshoot speech recognition in React applications. The main component that captures audio from the user's microphone and converts speech to text in real-time using browser APIs.
SpeechToText组件允许用户通过Web Speech API将语音转换为文本。本技能可帮助你在React应用中实现、自定义语音识别功能并排查相关问题。该核心组件通过浏览器API捕获用户麦克风的音频,并实时将语音转换为文本。

Key Capabilities

核心功能

  • Real-time speech recognition
  • Multiple language support
  • Customizable button and tooltip
  • Event-driven architecture
  • Programmatic control via methods
  • Accessibility support (ARIA labels, keyboard navigation)
  • Localization support
  • Error handling and recovery
  • 实时语音识别
  • 多语言支持
  • 可自定义按钮与提示框
  • 事件驱动架构
  • 通过方法实现程序化控制
  • 无障碍支持(ARIA标签、键盘导航)
  • 本地化支持
  • 错误处理与恢复

Documentation

文档资料

Getting Started

快速开始

📄 Read: references/getting-started.md
  • Installation via npm
  • Package installation and setup
  • Basic component implementation
  • CSS imports and theme selection
  • First working example
  • TypeScript configuration
  • Disabling the component (
    disabled
    property)
📄 阅读: references/getting-started.md
  • 通过npm安装
  • 包安装与配置
  • 基础组件实现
  • CSS导入与主题选择
  • 首个可用示例
  • TypeScript配置
  • 禁用组件(
    disabled
    属性)

Speech Recognition Features

语音识别功能

📄 Read: references/speech-recognition-features.md
  • Retrieving transcripts in real-time
  • Setting language for recognition
  • Managing interim results
  • Listening state management with
    SpeechToTextState
    enum (Inactive, Listening, Stopped)
  • Reading
    listeningState
    from event args and component ref
  • Handling speech-to-text conversion
  • Real-time vs final results
📄 阅读: references/speech-recognition-features.md
  • 实时获取转录文本
  • 设置识别语言
  • 管理临时结果
  • 通过
    SpeechToTextState
    枚举管理监听状态(Inactive、Listening、Stopped)
  • 从事件参数与组件ref中读取
    listeningState
  • 处理语音转文本转换
  • 实时结果与最终结果对比

Button and Tooltip Customization

按钮与提示框自定义

📄 Read: references/button-and-tooltip-customization.md
  • Customizing button content and icons
  • Icon positioning and styling
  • Controlling tooltip visibility (
    showTooltip
    property)
  • Tooltip configuration and placement (all 12
    TooltipPosition
    values)
  • CSS class styling (e-primary, e-success, etc.)
  • Button appearance modes
  • Responsive button design
📄 阅读: references/button-and-tooltip-customization.md
  • 自定义按钮内容与图标
  • 图标定位与样式设置
  • 控制提示框可见性(
    showTooltip
    属性)
  • 提示框配置与位置(支持全部12种
    TooltipPosition
    取值)
  • CSS类样式设置(e-primary、e-success等)
  • 按钮外观模式
  • 响应式按钮设计

Events and Methods

事件与方法

📄 Read: references/events-and-methods.md
  • Event handling (created, onStart, onStop, onError, transcriptChanged)
  • Correct event argument interfaces (StartListeningEventArgs, StopListeningEventArgs, ErrorEventArgs, TranscriptChangedEventArgs)
  • cancel
    property to prevent listening start
  • isInteracted
    to distinguish user vs programmatic triggers
  • errorMessage
    for human-readable error details
  • isInterimResult
    for interim vs final transcript results
  • startListening(), stopListening(), and destroy() methods
  • Ref-based component control
  • Programmatic listening management
📄 阅读: references/events-and-methods.md
  • 事件处理(created、onStart、onStop、onError、transcriptChanged)
  • 正确的事件参数接口(StartListeningEventArgs、StopListeningEventArgs、ErrorEventArgs、TranscriptChangedEventArgs)
  • cancel
    属性:阻止监听启动
  • isInteracted
    :区分用户触发与程序化触发
  • errorMessage
    :人类可读的错误详情
  • isInterimResult
    :区分临时转录结果与最终转录结果
  • startListening()、stopListening()、destroy()方法
  • 基于ref的组件控制
  • 程序化监听管理

Globalization and Localization

全球化与本地化

📄 Read: references/globalization-and-localization.md
  • Localization with L10n.load()
  • Available locale strings and translations
  • Language-specific error messages
  • RTL support for right-to-left languages
  • Accessibility labels and ARIA attributes
  • htmlAttributes
    for custom HTML/ARIA attributes on the button element
  • Multi-language interface support
📄 阅读: references/globalization-and-localization.md
  • 通过L10n.load()实现本地化
  • 可用的区域字符串与翻译
  • 语言特定的错误提示
  • 支持从右到左(RTL)布局
  • 无障碍标签与ARIA属性
  • htmlAttributes
    :为按钮元素添加自定义HTML/ARIA属性
  • 多语言界面支持

Troubleshooting and Security

故障排查与安全

📄 Read: references/troubleshooting-and-security.md
  • Common issues and solutions
  • Browser compatibility matrix
  • Microphone permission handling
  • Security considerations and best practices
  • Privacy and data transmission
  • Performance optimization
  • Offline fallback strategies
📄 阅读: references/troubleshooting-and-security.md
  • 常见问题与解决方案
  • 浏览器兼容性矩阵
  • 麦克风权限处理
  • 安全注意事项与最佳实践
  • 隐私与数据传输
  • 性能优化
  • 离线回退策略

Quick Start Example

快速开始示例

tsx
import { SpeechToTextComponent, TextAreaComponent, TranscriptChangedEventArgs } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';
import '@syncfusion/ej2-react-inputs/styles/material.css';

function VoiceNoteApp() {
  const [transcript, setTranscript] = useState('');

  const handleTranscriptChanged = (args: TranscriptChangedEventArgs) => {
    setTranscript(args.transcript);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h2>Voice Note Recorder</h2>
      
      {/* SpeechToText component with microphone button */}
      <SpeechToTextComponent 
        id="speechToText"
        transcriptChanged={handleTranscriptChanged}
      />
      
      {/* Display transcribed text */}
      <TextAreaComponent
        id="noteArea"
        value={transcript}
        resizeMode="None"
        rows={5}
        cols={50}
        placeholder="Your voice will appear here..."
      />
    </div>
  );
}

export default VoiceNoteApp;
tsx
import { SpeechToTextComponent, TextAreaComponent, TranscriptChangedEventArgs } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';
import '@syncfusion/ej2-react-inputs/styles/material.css';

function VoiceNoteApp() {
  const [transcript, setTranscript] = useState('');

  const handleTranscriptChanged = (args: TranscriptChangedEventArgs) => {
    setTranscript(args.transcript);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h2>Voice Note Recorder</h2>
      
      {/* SpeechToText component with microphone button */}
      <SpeechToTextComponent 
        id="speechToText"
        transcriptChanged={handleTranscriptChanged}
      />
      
      {/* Display transcribed text */}
      <TextAreaComponent
        id="noteArea"
        value={transcript}
        resizeMode="None"
        rows={5}
        cols={50}
        placeholder="Your voice will appear here..."
      />
    </div>
  );
}

export default VoiceNoteApp;

Common Patterns

常见模式

Pattern 1: Voice Form Input

模式1:语音表单输入

tsx
import { SpeechToTextComponent, TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';

function VoiceForm() {
  const [formData, setFormData] = useState({
    name: '',
    message: ''
  });

  const handleNameTranscript = (args: any) => {
    setFormData(prev => ({ ...prev, name: args.transcript }));
  };

  const handleMessageTranscript = (args: any) => {
    setFormData(prev => ({ ...prev, message: args.transcript }));
  };

  return (
    <div>
      <label>Name (speak):</label>
      <SpeechToTextComponent transcriptChanged={handleNameTranscript} />
      <TextBoxComponent value={formData.name} />
      
      <label>Message (speak):</label>
      <SpeechToTextComponent transcriptChanged={handleMessageTranscript} />
      <TextBoxComponent value={formData.message} />
    </div>
  );
}
tsx
import { SpeechToTextComponent, TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';

function VoiceForm() {
  const [formData, setFormData] = useState({
    name: '',
    message: ''
  });

  const handleNameTranscript = (args: any) => {
    setFormData(prev => ({ ...prev, name: args.transcript }));
  };

  const handleMessageTranscript = (args: any) => {
    setFormData(prev => ({ ...prev, message: args.transcript }));
  };

  return (
    <div>
      <label>Name (speak):</label>
      <SpeechToTextComponent transcriptChanged={handleNameTranscript} />
      <TextBoxComponent value={formData.name} />
      
      <label>Message (speak):</label>
      <SpeechToTextComponent transcriptChanged={handleMessageTranscript} />
      <TextBoxComponent value={formData.message} />
    </div>
  );
}

Pattern 2: Programmatic Control

模式2:程序化控制

tsx
import { SpeechToTextComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

function VoiceControlApp() {
  const speechRef = useRef<SpeechToTextComponent>(null);

  const startVoiceInput = () => {
    speechRef.current?.startListening();
  };

  const stopVoiceInput = () => {
    speechRef.current?.stopListening();
  };

  return (
    <div>
      <SpeechToTextComponent ref={speechRef} />
      <button onClick={startVoiceInput}>Start Recording</button>
      <button onClick={stopVoiceInput}>Stop Recording</button>
    </div>
  );
}
tsx
import { SpeechToTextComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

function VoiceControlApp() {
  const speechRef = useRef<SpeechToTextComponent>(null);

  const startVoiceInput = () => {
    speechRef.current?.startListening();
  };

  const stopVoiceInput = () => {
    speechRef.current?.stopListening();
  };

  return (
    <div>
      <SpeechToTextComponent ref={speechRef} />
      <button onClick={startVoiceInput}>Start Recording</button>
      <button onClick={stopVoiceInput}>Stop Recording</button>
    </div>
  );
}

Pattern 3: Error Handling

模式3:错误处理

tsx
import { SpeechToTextComponent, ErrorEventArgs } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';

function VoiceWithErrorHandling() {
  const [error, setError] = useState('');
  const [isListening, setIsListening] = useState(false);

  const handleError = (args: ErrorEventArgs) => {
    // args.errorMessage is the human-readable description; args.error is the error code
    setError(args.errorMessage || `Error: ${args.error}`);
  };

  const handleStart = () => {
    setIsListening(true);
    setError('');
  };

  const handleStop = () => {
    setIsListening(false);
  };

  return (
    <div>
      <SpeechToTextComponent 
        onError={handleError}
        onStart={handleStart}
        onStop={handleStop}
      />
      {isListening && <p>🎤 Listening...</p>}
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </div>
  );
}
tsx
import { SpeechToTextComponent, ErrorEventArgs } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';

function VoiceWithErrorHandling() {
  const [error, setError] = useState('');
  const [isListening, setIsListening] = useState(false);

  const handleError = (args: ErrorEventArgs) => {
    // args.errorMessage is the human-readable description; args.error is the error code
    setError(args.errorMessage || `Error: ${args.error}`);
  };

  const handleStart = () => {
    setIsListening(true);
    setError('');
  };

  const handleStop = () => {
    setIsListening(false);
  };

  return (
    <div>
      <SpeechToTextComponent 
        onError={handleError}
        onStart={handleStart}
        onStop={handleStop}
      />
      {isListening && <p>🎤 Listening...</p>}
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </div>
  );
}

Key Props

核心属性

PropTypeDescription
lang
stringLanguage for speech recognition (e.g., 'en-US', 'fr-FR')
transcript
stringCurrent transcribed text
allowInterimResults
booleanShow real-time results (default: true)
listeningState
SpeechToTextStateCurrent listening state (Inactive, Listening, Stopped)
buttonSettings
ButtonSettingsModelCustomize button appearance and content
tooltipSettings
TooltipSettingsModelConfigure tooltip display
showTooltip
booleanWhether to display the tooltip on hover (default: true)
cssClass
stringApply CSS classes for styling
disabled
booleanDisable all component interaction (default: false)
htmlAttributes
{ [key: string]: string }Additional HTML attributes (ARIA, data-*, etc.) for the root button element
locale
stringLocalization language code
enableRtl
booleanEnable right-to-left layout
enablePersistence
booleanPersist component state between page reloads via localStorage
属性类型描述
lang
string语音识别语言(例如:'en-US'、'fr-FR')
transcript
string当前转录文本
allowInterimResults
boolean是否显示实时结果(默认:true)
listeningState
SpeechToTextState当前监听状态(Inactive、Listening、Stopped)
buttonSettings
ButtonSettingsModel自定义按钮外观与内容
tooltipSettings
TooltipSettingsModel配置提示框显示
showTooltip
boolean鼠标悬停时是否显示提示框(默认:true)
cssClass
string应用自定义CSS类进行样式设置
disabled
boolean禁用组件所有交互(默认:false)
htmlAttributes
{ [key: string]: string }为根按钮元素添加额外HTML属性(ARIA、data-*等)
locale
string本地化语言代码
enableRtl
boolean启用从右到左布局
enablePersistence
boolean通过localStorage在页面刷新时保留组件状态

Event Handlers

事件处理器

EventArgsDescription
created
-Fired when component is initialized
onStart
StartListeningEventArgsFired when speech recognition begins. Args:
cancel
,
event
,
isInteracted
,
listeningState
,
name
onStop
StopListeningEventArgsFired when speech recognition ends. Args:
event
,
isInteracted
,
listeningState
,
name
onError
ErrorEventArgsFired when an error occurs. Args:
error
,
errorMessage
,
event
,
name
transcriptChanged
TranscriptChangedEventArgsFired when transcription updates. Args:
transcript
,
isInterimResult
,
event
,
name
事件参数描述
created
-组件初始化完成时触发
onStart
StartListeningEventArgs语音识别开始时触发。参数:
cancel
event
isInteracted
listeningState
name
onStop
StopListeningEventArgs语音识别结束时触发。参数:
event
isInteracted
listeningState
name
onError
ErrorEventArgs发生错误时触发。参数:
error
errorMessage
event
name
transcriptChanged
TranscriptChangedEventArgs转录内容更新时触发。参数:
transcript
isInterimResult
event
name

Methods

方法

MethodDescription
startListening()
Begin speech recognition programmatically
stopListening()
Stop speech recognition programmatically
destroy()
Destroy the component instance and release all resources
方法描述
startListening()
程序化启动语音识别
stopListening()
程序化停止语音识别
destroy()
销毁组件实例并释放所有资源

Troubleshooting

故障排查

Microphone permission denied

麦克风权限被拒绝

Solution: Check browser permissions settings and allow microphone access in security settings
解决方案: 检查浏览器权限设置,在安全设置中允许麦克风访问

Speech not recognized

语音无法被识别

Solution: Check microphone volume, speak clearly, verify correct language setting
解决方案: 检查麦克风音量、清晰发音、验证语言设置是否正确

Component not rendering

组件无法渲染

Solution: Ensure CSS imports are included and license key is registered
解决方案: 确保已导入CSS文件并注册许可证密钥

Browser not supported

浏览器不支持

Solution: Check if browser supports Web Speech API (Chrome, Edge, Safari support it)
解决方案: 检查浏览器是否支持Web Speech API(Chrome、Edge、Safari均支持)

Related Components

相关组件

  • TextArea: For displaying transcribed text
  • TextBox: For input fields with voice capabilities
  • Button: For custom voice control buttons
  • Tooltip: For contextual help on voice features
  • TextArea: 用于显示转录文本
  • TextBox: 具备语音输入功能的输入框
  • Button: 自定义语音控制按钮
  • Tooltip: 为语音功能提供上下文帮助