HarmonyOS Speech Recognition Tutorial: Real-time Voice-to-Text with Core Speech Kit
This tutorial demonstrates how to implement real-time speech recognition in HarmonyOS using Core Speech Kit, covering engine creation, permission handling, result callbacks, and a complete voice note app example with code snippets.
Speech Recognition Principle
Speech recognition receives audio data, processes it through a recognition engine, and returns recognized text via callbacks. When using an offline model, recognition runs entirely on-device, allowing transcription without network connectivity and without sending audio to external servers.
Engine Creation and Configuration
Create the recognition engine via speechRecognizer.createEngine with parameters specifying language, online mode, and recognizer mode. The example uses short-mode for brief utterances:
const params: speechRecognizer.CreateEngineParams = {
language: 'zh-CN',
online: 1,
extraParams: { 'locate': 'CN', 'recognizerMode': 'short' }
};
const engine = await speechRecognizer.createEngine(params);Result Handling
After engine preparation, set a listener and start recognition. The onResult callback returns both intermediate and final results. Intermediate results change during recognition; they should not be simply concatenated to avoid duplicate text. The example updates the displayed text only when the page is active and the session ID matches:
onResult: (id: string, result: speechRecognizer.SpeechRecognitionResult) => {
if (this.pageActive && id === this.sessionId) {
this.text = result.result;
}
}Short-mode recognition ends either manually, after brief silence, or when a duration limit is reached. For longer or multi-sentence recordings, handling differs between intermediate results and final clause results.
Code Practice: Voice Note App
Permission Declaration
Declare microphone permission in entry/src/main/module.json5:
"requestPermissions": [
{
"name": "ohos.permission.MICROPHONE",
"reason": "$string:microphone_reason",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
}
]Add the permission description in entry/src/main/resources/base/element/string.json:
{ "name": "microphone_reason", "value": "用于将语音转换为文字" }Runtime Permission Request
Request permission at runtime using abilityAccessCtrl.createAtManager() and requestPermissionsFromUser.
Complete Component Implementation
The Index component manages engine lifecycle, recognition state, and UI. Key points:
Engine created once in start() with parameters: language zh-CN, online 1, extraParams { locate: 'CN', recognizerMode: 'short' }.
Listener includes onStart, onResult, onComplete, onError callbacks, each guarded by pageActive and session ID.
Start parameters: audioInfo with PCM, 16000 Hz sample rate, 1 channel, 16-bit; extraParams with recognitionMode: 0 and maxAudioDuration: 20000 (20 seconds).
Stop calls engine.finish(sessionId) and updates status to await final result.
Cleanup in aboutToDisappear cancels recognition and shuts down engine.
@Entry
@Component
struct Index {
@State private text: string = '';
@State private status: string = '点击开始,说一句话';
@State private busy: boolean = false;
@State private listening: boolean = false;
private engine: speechRecognizer.SpeechRecognitionEngine | undefined = undefined;
private sessionId: string = '';
private pageActive: boolean = false;
aboutToAppear(): void {
this.pageActive = true;
}
aboutToDisappear(): void {
this.pageActive = false;
if (this.engine) {
try {
if (this.sessionId) {
this.engine.cancel(this.sessionId);
}
} catch (error) {
console.error('取消识别失败');
}
try {
this.engine.shutdown();
} catch (error) {
console.error('关闭引擎失败');
}
this.engine = undefined;
}
this.sessionId = '';
}
private async start(): Promise<void> {
if (this.busy) { return; }
this.busy = true;
this.status = '正在准备语音识别';
try {
const context = this.getUIContext().getHostContext() as common.UIAbilityContext | undefined;
if (!context) {
this.status = '无法获取页面上下文';
this.busy = false;
return;
}
const permissions: Array<Permissions> = ['ohos.permission.MICROPHONE'];
const manager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
const grant = await manager.requestPermissionsFromUser(context, permissions);
if (!this.pageActive) { return; }
if (grant.authResults[0] !== 0) {
this.status = '未获得麦克风权限,请在系统设置中开启';
this.busy = false;
return;
}
if (!this.engine) {
const params: speechRecognizer.CreateEngineParams = {
language: 'zh-CN',
online: 1,
extraParams: { 'locate': 'CN', 'recognizerMode': 'short' }
};
const created: speechRecognizer.SpeechRecognitionEngine = await speechRecognizer.createEngine(params);
if (!this.pageActive) {
created.shutdown();
return;
}
this.engine = created;
}
const listener: speechRecognizer.RecognitionListener = {
onStart: (id: string, message: string) => {
if (this.pageActive && id === this.sessionId) {
this.listening = true;
this.status = '正在识别,请说话';
}
},
onEvent: (id: string, code: number, message: string) => {},
onResult: (id: string, result: speechRecognizer.SpeechRecognitionResult) => {
if (this.pageActive && id === this.sessionId) {
this.text = result.result;
}
},
onComplete: (id: string, message: string) => {
if (this.pageActive && id === this.sessionId) {
this.listening = false;
this.busy = false;
this.sessionId = '';
this.status = '识别结束,可以复制文字或重新开始';
}
},
onError: (id: string, code: number, message: string) => {
if (this.pageActive && id === this.sessionId) {
this.listening = false;
this.busy = false;
this.sessionId = '';
this.status = '识别失败:' + code + ',' + message;
}
}
};
this.engine.setListener(listener);
this.sessionId = 'speech_' + Date.now();
this.text = '';
const startParams: speechRecognizer.StartParams = {
sessionId: this.sessionId,
audioInfo: { audioType: 'pcm', sampleRate: 16000, soundChannel: 1, sampleBit: 16 },
extraParams: { 'recognitionMode': 0, 'maxAudioDuration': 20000 }
};
this.engine.startListening(startParams);
this.status = '正在启动识别';
} catch (error) {
if (this.pageActive) {
const err = error as BusinessError;
this.status = '启动失败:' + err.code + ',' + err.message;
this.listening = false;
this.busy = false;
this.sessionId = '';
}
}
}
private stop(): void {
if (!this.engine || !this.sessionId || !this.listening) { return; }
try {
this.engine.finish(this.sessionId);
this.listening = false;
this.status = '正在等待最终结果';
} catch (error) {
const err = error as BusinessError;
this.status = '结束识别失败:' + err.code + ',' + err.message;
this.listening = true;
}
}
build() {
Column({ space: 16 }) {
Text('语音便签')
.fontSize(24)
.fontWeight(FontWeight.Bold)
.width('100%')
Text(this.status)
.fontSize(14)
.fontColor('#666666')
.width('100%')
Scroll() {
Text(this.text.length > 0 ? this.text : '识别的文字会显示在这里')
.fontSize(18)
.fontColor(this.text.length > 0 ? '#222222' : '#999999')
.lineHeight(28)
.copyOption(CopyOptions.LocalDevice)
.width('100%')
}
.width('100%')
.layoutWeight(1)
.padding(16)
.backgroundColor('#F3F3F3')
.borderRadius(10)
Button('开始识别')
.width('100%')
.enabled(!this.busy)
.onClick(() => { void this.start(); })
Button('结束识别')
.width('100%')
.enabled(this.listening)
.onClick(() => { this.stop(); })
Text('长按识别结果可以复制文字')
.fontSize(13)
.fontColor('#888888')
.width('100%')
}
.padding(20)
.width('100%')
.height('100%')
.alignItems(HorizontalAlign.Start)
.backgroundColor('#FFFFFF')
}
}Running Effect
The article includes a GIF demonstrating the voice note app in action.
Summary
Core Speech Kit converts speech to text, suitable for voice input, search, and note-taking. On-device recognition can run offline when the device supports it and has the required model. Actual accuracy is affected by ambient noise, pronunciation, and device conditions.
Developers must handle microphone permission, recognition completion, and error callbacks, and shut down the engine when no longer needed. Short and long speech modes differ in termination behavior and result processing; choose based on business requirements.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
