client

package module
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 1, 2026 License: MIT Imports: 2 Imported by: 0

README

Tengen Speech SDK for Go

Go 语言语音服务客户端 SDK，连接 Speech Arena Gateway，提供流式 TTS（文本转语音）和流式 STT（语音转文本）功能。

安装

go get github.com/jinbozhan/tengen-speech-sdk-go@v0.2.2

TTS - 流式文本转语音

单次合成
import (
    "io"
    "time"
    "github.com/jinbozhan/tengen-speech-sdk-go/tts"
)

config := &tts.Config{
    GatewayURL:     "ws://localhost:8080",
    Provider:       "tengen",
    APIKey:         "sk_xxx",
    VoiceID:        "loongstella",
    Speed:          1.0,
    SampleRate:     8000,
    AudioFormat:    "pcm",
    ConnectTimeout: 30 * time.Second,
    ReadTimeout:    120 * time.Second,
}

client, _ := tts.NewClient(config)
defer client.Close()

// 流式合成，stream 实现 io.Reader
stream, _ := client.SynthesizeStream(ctx, "你好，世界")
defer stream.Close()
io.Copy(outputFile, stream)
多轮合成（Session 复用）

创建一个 Session 后可多次合成，避免重复建连：

session, _ := client.CreateSession(ctx, nil)
defer session.Close()

for _, text := range []string{"第一句", "第二句", "第三句"} {
    stream, _ := session.SynthesizeStream(ctx, text)
    buf := make([]byte, 4096)
    for {
        n, err := stream.Read(buf)
        if n > 0 {
            // 处理音频 buf[:n]
        }
        if err == io.EOF {
            break
        }
    }
}

STT - 流式语音转文本

import (
    "time"
    "github.com/jinbozhan/tengen-speech-sdk-go/stt"
)

config := &stt.Config{
    GatewayURL:     "ws://localhost:8080",
    Provider:       "tengen",
    APIKey:         "sk_xxx",
    Language:       "zh-CN",
    // Languages:   []string{"ms-MY", "en-SG"}, // 多语言候选（LID），非空时优先于 Language
    SampleRate:     16000,
    AudioFormat:    "pcm",
    ConnectTimeout: 30 * time.Second,
    ReadTimeout:    120 * time.Second,
}

client, _ := stt.NewClient(config)
defer client.Close()

// 创建流式会话
session, _ := client.CreateSession(ctx, &stt.StreamOptions{
    Language:    "zh-CN",
    SampleRate:  16000,
    AudioFormat: "pcm",
})
defer session.Close()

// goroutine 发送音频
go func() {
    chunkSize := 16000 * 2 * 100 / 1000 // 100ms 音频块
    buf := make([]byte, chunkSize)
    for {
        n, err := audioReader.Read(buf)
        if err == io.EOF {
            break
        }
        session.Send(buf[:n])
    }
    session.EndInput() // 标记发送完毕
}()

// 接收识别事件
for event := range session.Events() {
    switch event.Type {
    case stt.EventTranscriptPartial:
        fmt.Printf("\r[Partial] %s", event.Text)
    case stt.EventTranscriptFinal:
        // event.Language：LID 检测到的语言（provider 支持且启用多语言候选时填充）
        fmt.Printf("\r[Final] [%.3fs-%.3fs] [%s] %s\n",
            event.StartTime.Seconds(), event.EndTime.Seconds(), event.Language, event.Text)
    case stt.EventSpeechStarted:
        fmt.Println("[SpeechStarted]")
    case stt.EventError:
        fmt.Printf("[Error] %v\n", event.Error)
    case stt.EventSessionEnded:
        break
    }
}

fmt.Printf("TTFB: %dms\n", session.TTFB().Milliseconds())
多语言候选（LID）

传入候选语言列表后，支持 LID 的 provider（如 azure）会在候选集内自动检测实际语言：

config.WithLanguages("ms-MY", "en-SG") // 非空时优先于 Language

// 或在创建会话时通过 StreamOptions 指定
session, _ := client.CreateSession(ctx, &stt.StreamOptions{
    Languages:   []string{"ms-MY", "en-SG"},
    SampleRate:  16000,
    AudioFormat: "pcm",
})

检测到的语言通过最终结果事件的 event.Language 回传（仅 EventTranscriptFinal，provider 支持时填充）。

命令行示例

./build.sh
TTS
./bin/tts_stream "你好，世界"
./bin/tts_stream "第一句" "第二句" "第三句"
./bin/tts_stream -provider qwen -voice loongstella -apikey "sk_xxx" "测试"
./bin/tts_stream -speed 1.5 -sample-rate 16000 -output result.wav "快速播放"
参数 默认值 说明
-gateway ws://localhost:8080 Gateway 地址
-provider qwen TTS 提供商
-apikey - API Key
-session-id - 会话 ID（每通电话唯一；与该通话的 STT 使用同值以便 Gateway 侧日志/录音关联；留空由 Gateway 生成）
-voice loongstella Voice ID
-language - 语言代码（文本归一化用，如 en-NG, sw-TZ）
-speed 1.0 语速 (0.5-2.0)
-pitch 1.0 音调 (-10 to 10)
-volume 1.0 音量 (0.0-1.0)
-output output.wav 输出文件路径
-sample-rate 8000 采样率
-channels 1 声道数
-bits 16 采样位深
STT
./bin/stt_stream audio.wav
./bin/stt_stream -provider qwen -language en-US recording.wav
./bin/stt_stream -provider azure -languages ms-MY,en-SG recording.wav
./bin/stt_stream -apikey "sk_xxx" audio.wav
参数 默认值 说明
-gateway ws://localhost:8080 Gateway 地址
-provider azure STT 提供商
-apikey - API Key
-session-id - 会话 ID（每通电话唯一；与该通话的 TTS 使用同值以便 Gateway 侧日志/录音关联；留空由 Gateway 生成）
-language zh-CN 识别语言
-languages - 多语言候选列表（LID），逗号分隔，如 ms-MY,en-SG；非空时优先于 -language
-sample-rate 8000 采样率
-interval 100 音频发送间隔 (ms)

支持的 Provider

Provider STT TTS 说明
tengen Y Y 默认提供商
azure Y Y Microsoft Azure Speech Services
qwen Y Y 阿里通义千问实时语音
voxnexus Y Y VoxNexus 语音服务

前置条件

  1. 运行 Speech Arena Gateway
  2. 获取有效的 API Key（如需认证）

版本历史

v0.2.2
  • 修复服务端优雅关闭（WS Close Frame 1000/1001）时 STT/TTS messageLoop 永久阻塞：该路径只关 conn.closeCh、不写 errorCh，此前 select 无对应分支，导致 STT Events() 的 channel 永不关闭、调用方 for range 卡死，goroutine 与连接滞留到 Session.Close()。典型触发是 Gateway 滚动发布（1001）；Gateway 崩溃 / 断网（1006）走 errorCh，此前即正常
  • 调用方无需改动：STT Events() 会正常关闭，for range 自然结束；断连不补发事件，事件类型与话单口径不变。TTS 侧不改变 AudioStream 语义（仍由调用方自身超时兜底），避免断连被误判为"合成正常结束"
v0.2.1
  • STT/TTS 支持逐通话会话 ID：新增 StreamOptions.SessionID / SynthesisOptions.SessionID，经 WS URL session_id 参数透传给 Gateway；同一通话的 STT/TTS 传同值即可在 Gateway 侧关联日志/录音，留空由 Gateway 生成。仅 CreateSession / SynthesizeStreamWithOptions 支持；简化 API（RecognizeFile / RecognizeBytes / SynthesizeToFile / SynthesizeToBytes）不透传。Gateway 未回传同值时 SDK 打印 Warn 日志
  • CreateSession / SynthesizeStreamWithOptions 支持部分填充的 options：零值字段自动回填 client Config 对应值（此前传非 nil opts 时未填字段会按零值发送）
  • TTS WS URL 的 voice_id 预热参数改为 per-call opts 优先、Config 兜底
  • stt_stream / tts_stream 示例新增 -session-id 参数
v0.2.0
  • STT 支持多语言候选（LID）：新增 Config.Languages / StreamOptions.Languages 候选语言列表，非空时优先于 Language；最终识别结果通过 RecognitionEvent.Language 回传检测到的语言
  • stt_stream 示例新增 -languages 参数（逗号分隔候选语言）
v0.1.2
  • 移除 speech.stopped 协议消息、SpeechStopped 结构体及 EventSpeechStopped 事件，清理未使用的代码路径
  • 重命名 examples-sdk 为 examples，统一目录结构
  • 新增 EventSpeechStarted 事件类型
  • TTS CLI 默认 provider 切换为 qwen
  • 新增 TTS Benchmark、TTS Detailed Timing、VAD-Clip ASR 工具
v0.1.1
  • 流式 STT/TTS 稳定版，统一 SDK 接口，日志迁移至 slog

Documentation

Overview

Package client 客户端错误定义

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrSessionNotReady 会话未就绪
	ErrSessionNotReady = errors.New("session not ready")

	// ErrSessionClosed 会话已关闭
	ErrSessionClosed = errors.New("session closed")

	// ErrProviderNotSupported 不支持的提供商
	ErrProviderNotSupported = errors.New("provider not supported")

	// ErrInvalidConfig 无效配置
	ErrInvalidConfig = errors.New("invalid configuration")

	// ErrAudioFormatNotSupported 不支持的音频格式
	ErrAudioFormatNotSupported = errors.New("audio format not supported")

	// ErrFileNotFound 文件未找到
	ErrFileNotFound = errors.New("file not found")

	// ErrTimeout 操作超时
	ErrTimeout = errors.New("operation timeout")
)

预定义错误

Functions

func IsConnectionError 

func IsConnectionError(err error) bool

IsConnectionError 判断是否为连接错误

func IsRetryable 

func IsRetryable(err error) bool

IsRetryable 判断错误是否可重试

func IsTimeoutError 

func IsTimeoutError(err error) bool

IsTimeoutError 判断是否为超时错误

func WrapError 

func WrapError(op string, err error) error

WrapError 包装错误

Types

type ClientError 

type ClientError struct {
	Op       string // 操作名称
	Provider string // 提供商
	Code     string // 错误代码
	Message  string // 错误信息
	Err      error  // 底层错误
}

ClientError 客户端错误

func NewClientError 

func NewClientError(op, provider, code, message string, err error) *ClientError

NewClientError 创建客户端错误

func NewConfigError 

func NewConfigError(op, message string) *ClientError

NewConfigError 创建配置错误

func NewConnectionError 

func NewConnectionError(op, message string, err error) *ClientError

NewConnectionError 创建连接错误

func NewProtocolError 

func NewProtocolError(op, message string, err error) *ClientError

NewProtocolError 创建协议错误

func NewProviderError 

func NewProviderError(op, provider, code, message string) *ClientError

NewProviderError 创建提供商错误

func NewTimeoutError 

func NewTimeoutError(op, message string) *ClientError

NewTimeoutError 创建超时错误

func (*ClientError) Error 

func (e *ClientError) Error() string

func (*ClientError) Unwrap 

func (e *ClientError) Unwrap() error

Source Files

View all Source files

Directories

Path Synopsis
Package audio 音频格式转换
 Package audio 音频格式转换
cmd
test_vad_clip_asr command
Package main - VAD-Clip ASR 端到端正确性测试
 Package main - VAD-Clip ASR 端到端正确性测试
tts_benchmark command
Package main 提供TTS并发测试工具
 Package main 提供TTS并发测试工具
tts_detailed_timing command
Package main 提供TTS详细时延分析工具
 Package main 提供TTS详细时延分析工具
examples
stt_stream command
Package main STT 客户端演示程序
 Package main STT 客户端演示程序
tts_pipeline command
Package main TTS 管道化合成示例
 Package main TTS 管道化合成示例
tts_stream command
Package main TTS 多轮合成示例
 Package main TTS 多轮合成示例
Package logging 提供人类友好的 slog 日志格式化
 Package logging 提供人类友好的 slog 日志格式化
Package protocol 定义统一 WebSocket 消息协议
 Package protocol 定义统一 WebSocket 消息协议
Package stt 提供STT客户端SDK
 Package stt 提供STT客户端SDK
Package transport 提供WebSocket连接管理
 Package transport 提供WebSocket连接管理
Package tts 提供TTS客户端SDK
 Package tts 提供TTS客户端SDK

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.