stepfun-ai/stepfunApi-audio-sdk

stepfun-ai/stepfunApi-audio-sdk

Description: 基于阶跃星辰开放平台语音api的android 语音sdk，支持tts 流式与非流式，asr，流式，非流式音频播放器，语音录制能力

Language: Kotlin

License: Apache-2.0

Stars: 5

Forks: 1

Open issues: 0

Created: 2025-11-20T06:21:54Z

Pushed: 2025-12-15T08:27:36Z

Default branch: main

Fork: no

Archived: no

README:

StepFun Audio SDK 使用文档

---

目录

1. [快速开始](#快速开始) 2. [SDK 初始化](#sdk-初始化) 3. [TTS 文字转语音](#tts-文字转语音)

• [一次性生成](#一次性生成)
• [生成并播放](#生成并播放)
• [流式 TTS](#流式-tts)

4. [ASR 语音识别](#asr-语音识别)

• [识别音频文件](#识别音频文件)
• [录音并识别](#录音并识别)

5. [配置参数说明](#配置参数说明) 6. [错误处理](#错误处理) 7. [资源释放](#资源释放)

---

快速开始

添加依赖

implementation("com.stepfun:stepfun-audio-sdk:x.x.x")

最简示例

// 1. 初始化 SDK
SpeechSdk.init(context, SpeechConfig.Builder()
.httpBaseUrl("https://your-api-server.com")
.webSocketUrl("wss://your-ws-server.com")
.customHeaders(mapOf("Authorization" to "Bearer YOUR_API_KEY"))
.enableLogging(true)
.build()
)

// 2. 一键播放语音
SpeechSdk.TTS.quickPlay(context, "你好，世界！")

---

SDK 初始化

SpeechConfig 配置

val config = SpeechConfig.Builder()
// 服务器地址（必填）
.httpBaseUrl("https://api.stepfun.com")
.webSocketUrl("wss://ws.stepfun.com")

// 认证信息（通过 headers 传递）
.customHeaders(mapOf(
"Authorization" to "Bearer sk-xxxxxx"
))

// 环境配置
.environment(Environment.PRODUCTION)

// 日志开关
.enableLogging(true)

// TTS 默认配置
.ttsConfig(TtsConfig(
defaultModel = TtsModel.STEP_TTS_MINI.modelId,
defaultVoice = TtsVoice.STEP_TTS_MINI_DEFAULT,
defaultResponseFormat = TtsAudioFormat.PCM,
defaultSpeed = 1.0f,
defaultVolume = 1.0f,
defaultSampleRate = 24000
))

.build()

SpeechSdk.init(context, config)

检查初始化状态

if (SpeechSdk.isInitialized()) {
// SDK 已初始化
}

更新配置

SpeechSdk.updateConfig(newConfig)

---

TTS 文字转语音

一次性生成

使用默认配置

SpeechSdk.TTS.generateSpeech(
text = "你好，我是阶跃星辰语音助手",
voice = TtsVoice.STEP_TTS_MINI_DEFAULT,
callback = object : TtsCallback {
override fun onSuccess(audioData: ByteArray) {
// 获取到音频数据（可保存或自行播放）
}

override fun onError(error: TtsError) {
Log.e("TTS", "生成失败: ${error.message}")
}
}
)

使用自定义参数

val params = TtsSpeechParams.Builder()
.model(TtsModel.STEP_TTS_MINI.modelId)
.input("需要合成的文本内容")
.voice(TtsVoice.STEP_TTS_MINI_CIXINGNANSHENG)
.responseFormat(TtsAudioFormat.MP3)
.speed(1.2f) // 语速 0.5-2.0
.volume(1.0f) // 音量 0.1-2.0
.sampleRate(24000) // 采样率
.build()

SpeechSdk.TTS.generateSpeech(params, callback)

协程方式

lifecycleScope.launch {
try {
val audioData = SpeechSdk.TTS.generateSpeechAsync(params)
// 使用音频数据
} catch (e: Exception) {
Log.e("TTS", "生成失败", e)
}
}

保存到文件

val outputFile = File(cacheDir, "speech.mp3")
SpeechSdk.TTS.generateSpeechToFile(params, outputFile, callback)

---

生成并播放

快速播放（推荐）

// 最简单的方式，一行代码搞定
SpeechSdk.TTS.quickPlay(
context = this,
text = "你好，世界！",
voice = TtsVoice.STEP_TTS_MINI_DEFAULT
)

带回调的播放

SpeechSdk.TTS.generateAndPlay(
context = this,
params = TtsSpeechParams.Builder()
.model(TtsModel.STEP_TTS_MINI.modelId)
.input("需要播放的文本")
.voice(TtsVoice.STEP_TTS_MINI_DEFAULT)
.build(),
callback = object : TtsCallback {
override fun onSuccess(audioData: ByteArray) {
Log.d("TTS", "生成成功，正在播放")
}

override fun onError(error: TtsError) {
Log.e("TTS", "生成失败: ${error.message}")
}
},
playbackCallback = object : AudioPlayer.PlaybackCallback {
override fun onStart() {
Log.d("TTS", "开始播放")
}

override fun onComplete() {
Log.d("TTS", "播放完成")
}

override fun onError(error: String) {
Log.e("TTS", "播放错误: $error")
}
}
)

控制播放

// 停止播放
SpeechSdk.TTS.stopPlayback()

// 取消所有任务
SpeechSdk.TTS.cancelAll()

---

流式 TTS

流式 TTS 适用于需要边生成边播放的场景，可以显著降低首字延迟。

创建流式会话

val params = TtsStreamParams.Builder()
.model(TtsModel.STEP_TTS_MINI.modelId)
.voice(TtsVoice.STEP_TTS_MINI_CIXINGNANSHENG.voiceId)
.responseFormat(TtsAudioFormat.MP3) // 支持 PCM/MP3/FLAC/WAV/OPUS
.sampleRate(24000) // 8000/16000/24000
.speedRatio(1.0f) // 语速 0.5-2.0
.volumeRatio(1.0f) // 音量 0.1-2.0
.build()

SpeechSdk.TTS.createStreamSession(
context = this,
params = params,
callback = object : TtsStreamCallback {
override fun onConnectionEstablished(sessionId: String) {
Log.d("TTS", "WebSocket 连接建立")
}

override fun onSessionCreated(sessionId: String) {
Log.d("TTS", "会话创建成功: $sessionId")
// 可以开始发送文本
SpeechSdk.TTS.sendStreamText("你好，我是阶跃星辰语音助手")
}

override fun onSentenceStart(text: String) {
Log.d("TTS", "开始生成句子: $text")
}

override fun onAudioData(audioData: ByteArray, isFinished: Boolean) {
// 音频数据会自动播放，也可以在这里处理
Log.d("TTS", "收到音频: ${audioData.size} bytes, finished: $isFinished")
}

override fun onSentenceEnd(text: String) {
Log.d("TTS", "句子生成完成: $text")
}

override fun onFlushed() {
Log.d("TTS", "缓冲区已清空")
}

override fun onComplete() {
Log.d("TTS", "全部生成完成")
}

override fun onError(error: TtsStreamError) {
Log.e("TTS", "错误: ${error.code} - ${error.message}")
}
}
)

使用默认配置创建会话

SpeechSdk.TTS.createStreamSession(
context = this,
voice = TtsVoice.STEP_TTS_MINI_DEFAULT.voiceId,
callback = streamCallback
)

流式控制方法

// 发送文本（可多次调用）
SpeechSdk.TTS.sendStreamText("第一段文本")
SpeechSdk.TTS.sendStreamText("第二段文本")

// 清空缓冲区（快速获取当前未返回的音频）
SpeechSdk.TTS.flushStream()

// 完成生成（通知服务端不再发送文本）
SpeechSdk.TTS.finishStream()

// 暂停播放
SpeechSdk.TTS.pauseStream()

// 恢复播放
SpeechSdk.TTS.resumeStream()

// 停止播放（不关闭连接）
SpeechSdk.TTS.stopStream()

---

ASR 语音识别

识别音频文件

基础用法

val audioFile = File("/path/to/audio.mp3")

SpeechSdk.ASR.transcribe(audioFile, object : AsrCallback {
override fun onSuccess(result: AsrResult) {
Log.d("ASR", "识别结果: ${result.text}")
}

override fun onError(error: AsrError) {
Log.e("ASR", "识别失败: ${error.message}")
}
})

使用自定义参数

val params = AsrParams.Builder()
.file(audioFile)
.responseFormat(AsrResponseFormat.JSON)
.hotwords(listOf("阶跃星辰", "人工智能")) // 热词提升识别准确度
.build()

SpeechSdk.ASR.transcribe(params, callback)

快速识别

SpeechSdk.ASR.quickTranscribe(
file = audioFile,
hotwords = listOf("专业术语"),
callback = asrCallback
)

协程方式

lifecycleScope.launch {
try {
val result = SpeechSdk.ASR.transcribeAsync(params)
Log.d("ASR", "识别结果: ${result.text}")
} catch (e: Exception) {
Log.e("ASR", "识别失败", e)
}
}

---

录音并识别

分步录音

// 1. 开始录音
val recorder = SpeechSdk.ASR.startRecording(
context = this,
format = AudioRecordFormat.M4A,
sampleRate = 16000,
recordingCallback =…