createSpeechRecognizer / isSpeechRecognitionSupported

پوششی گرد SpeechRecognition در Web Speech API؛ همتای AudioRecorder که بایت‌های صدا را می‌گیرد، حال آنکه این یکی از سکو می‌خواهد گفتار را به متن بدل کند.

می‌ارزد که API خام را یک بار بپیچیم تا اینکه مستقیم به آن دست بزنیم: در WebKit هنوز پیشوند دارد (webkitSpeechRecognition)، در lib.dom.d.ts نیست، و رویدادهای پیش‌پاافتاده‌ای را که اصلاً رویداد نیستند (مکثی خاموش، stop()ی که خودتان صدا زده‌اید) از همان مجرای خطایی گزارش می‌کند که میکروفونِ رد شده.

کاربرد

import { createSpeechRecognizer } from 'ranuts/utils';

const mic = createSpeechRecognizer({
  lang: () => currentLocale(), // در هر ضبط از نو خوانده می‌شود، نه فقط یک بار
  onResult: (text, isFinal) => {
    input.value = text;
  },
  onError: (e) => {
    if (e.kind === 'denied') toast('دسترسی به میکروفون رد شد');
  },
  onStart: () => button.classList.add('recording'),
  onEnd: () => button.classList.remove('recording'),
});

if (!mic.supported) button.style.display = 'none'; // دکمهٔ میکروفون را از همان آغاز پنهان کنید
button.addEventListener('click', () => mic.toggle());

API

isSpeechRecognitionSupported()

boolean برمی‌گرداند. وارسی هنگام فراخوانی انجام می‌شود و در بار شدن پیمانه انباره نمی‌گردد، پس می‌توان این پیمانه را در رندر سمت سرور وارد کرد و پس از آب‌رسانی صفحه وارسی را صدا زد.

createSpeechRecognizer(options?)

یک SpeechRecognizer بازاستفاده‌پذیر می‌سازد. start() هر بار نمونهٔ خامِ تازه‌ای از شناسا می‌سازد، پس هر گزینه‌ای که به شکل تابع بدهید (به‌ویژه lang) در آغاز هر ضبط از نو خوانده می‌شود، نه اینکه هنگام ساختن منجمد بماند.

پارامترها (SpeechRecognizerOptions)

گزینه	توضیح	نوع	پیش‌فرض
lang	برچسب BCP 47 ('en-US'، 'zh-CN')، یا تابعی که در آغاز هر ضبط خوانده می‌شود	string | (() => string)	''
continuous	به‌جای ایستادن در نخستین مکث، از میان مکث‌ها هم گوش می‌دهد	boolean	true
interimResults	نتیجه‌های ناتمام را همچنان که گوینده سخن می‌گوید بیرون می‌دهد	boolean	true
onResult	با رونوشت تمام ضبطِ تا این لحظه و اینکه نهایی است یا نه فراخوانده می‌شود	(transcript: string, isFinal: boolean) => void	-
onError	با خطایی که پیشاپیش دسته‌بندی شده فراخوانده می‌شود	(error: SpeechError) => void	-
onStart	هنگام آغاز یک ضبط شلیک می‌کند	() => void	-
onEnd	در هر ضبط یک بار شلیک می‌کند، هرگونه که پایان یافته باشد (ایستادن، پایان مهلت، خطا)	() => void	-

SpeechRecognizer

عضو	توضیح	نوع
supported	اگر سکو بازشناسی گفتار نداشته باشد false؛ آنگاه هیچ متدی کاری نمی‌کند	boolean (گیرنده)
active	اینکه هم‌اکنون ضبطی در جریان است یا نه	boolean (گیرنده)
start()	ضبطی را آغاز می‌کند. اگر یکی در جریان باشد نادیده گرفته می‌شود	() => void
stop()	ضبط کنونی را پایان می‌دهد؛ آنچه پیش‌تر شناسایی شده می‌ماند و سپس onEnd می‌آید	() => void
abort()	ضبط کنونی را پایان می‌دهد و نتیجه‌های معلق را دور می‌ریزد	() => void
toggle()	اگر بیکار است آغاز می‌کند و اگر در جریان است می‌ایستد: درست همان چیزی که یک دکمهٔ میکروفون می‌خواهد	() => void

SpeechError

میدان	توضیح	نوع
kind	'denied' (میکروفون رد شد، ارزش نشان دادن دارد)، 'noSpeech' / 'aborted' (پیش‌پاافتاده و معمولاً نشان‌دادنی نیست)، 'failed' (هر چیز دیگر)	SpeechErrorKind
detail	رشتهٔ خامِ error از رویداد سکو	string

یادداشت‌ها

1. همه‌جا پشتیبانی نمی‌شود. فایرفاکس اصلاً پیاده‌سازی SpeechRecognition ندارد؛ به‌جای آنکه فرض کنید سازنده هست، پیش از نشان دادن دکمهٔ میکروفون همیشه recognizer.supported (یا isSpeechRecognitionSupported()) را وارسی کنید.
2. supported و active گیرنده‌اند و در هر دسترسی از نو سنجیده می‌شوند، نه اینکه هنگام ساختن یک بار گرفته شوند. این وقتی اهمیت دارد که createSpeechRecognizer() پیش از در دسترس بودن window یا سازندهٔ پیشونددار اجرا شود (SSR، یا فراخوانی زودهنگام در بدنهٔ پیمانه پیش از آب‌رسانی): شناسا به‌محض پدیدار شدن API واقعی آن را برمی‌دارد و برای همیشه در گفتن supported === false گیر نمی‌کند.
3. رونوشتِ onResult انباشته است، نه افزایشی: متن کاملِ ضبطِ تا آن لحظه است که با محکم‌تر شدن نتیجه‌های میانی بازنویسی می‌شود. خودتان آن‌ها را به هم نچسبانید.
4. ساختن شناسای خام یا صدا زدن start() آن می‌تواند همگام خطا پرتاب کند (مثلاً محدودیت Permissions-Policy، یا InvalidStateError کروم وقتی ضبطی در جریان است)؛ createSpeechRecognizer این را می‌گیرد و به‌جای آنکه بگذارد بگریزد، از راه onError و onEnd گزارش می‌کند.