recognizer

package module
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Aug 20, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package recognizer defines the core types and interfaces for speech recognition (ASR).

This is the vendor-agnostic core package. Vendor-specific implementations live in submodules (e.g. recognizer/volcengine, recognizer/qcloud).

Index

Constants

View Source 
const (
	ProtocolVersionV1 = ProtocolVersion(0b0001)

	// Message Type
	MessageTypeClientFullRequest      = MessageType(0b0001)
	MessageTypeClientAudioOnlyRequest = MessageType(0b0010)
	MessageTypeServerFullResponse     = MessageType(0b1001)
	MessageTypeServerAck              = MessageType(0b1011)
	MessageTypeServerErrorResponse    = MessageType(0b1111)

	// Message Type Specific Flags
	FlagNoSequence        = MessageTypeSpecificFlags(0b0000)
	FlagPosSequence       = MessageTypeSpecificFlags(0b0001)
	FlagNegWithSequence   = MessageTypeSpecificFlags(0b0011)
	FlagEventWithSequence = MessageTypeSpecificFlags(0b0100)

	// Serialization Type
	SerializationJSON = SerializationType(0b0001)
	SerializationRaw  = SerializationType(0b0010)
	SerializationNone = SerializationType(0b0000)

	// Compression Type
	CompressionNone = CompressionType(0b0000)
	CompressionGZIP = CompressionType(0b0001)
)
View Source 
const DefaultSampleRate = 16000

Variables

View Source 
var ErrClientClosed = errClientClosed("asr client closed")

ErrClientClosed is returned when the ASR client is closed.

Functions

func BuildAuthHeader 

func BuildAuthHeader(auth AuthConfig) http.Header

BuildAuthHeader creates HTTP headers for authentication.

func ComputeSampleByteCount 

func ComputeSampleByteCount(sampleRate, bitDepth, channels int) int

ComputeSampleByteCount computes the number of bytes for audio samples based on sample rate, bit depth, and number of channels. Formula: (sampleRate * bitDepth * channels) / 8

func DefaultVolcEndWindowMs 

func DefaultVolcEndWindowMs() int

DefaultVolcEndWindowMs returns the default VAD end window size in milliseconds.

func GzipCompress 

func GzipCompress(input []byte) []byte

GzipCompress compresses data using gzip.

func GzipDecompress 

func GzipDecompress(input []byte) []byte

GzipDecompress decompresses gzip data.

func NewAudioOnlyRequest 

func NewAudioOnlyRequest(seq int, segment []byte) []byte

NewAudioOnlyRequest creates an audio-only request payload.

func NewFullClientRequest 

func NewFullClientRequest(config *Config) []byte

NewFullClientRequest creates a full client request payload.

func RegisterAllVendors 

func RegisterAllVendors(f *DefaultFactory, registrations map[Vendor]Creator)

RegisterAllVendors registers all known vendor creators into the given factory. Vendor submodules call RegisterCreator individually; this helper provides a single entry point for consumers that want to register all vendors at once. Each registration is guarded by a nil-creator check so partial registrations are safe.

func SetGlobalFactory 

func SetGlobalFactory(factory *DefaultFactory)

SetGlobalFactory sets the global factory instance.

func VendorString 

func VendorString(v Vendor) string

VendorString returns the string representation of a Vendor.

Types

type AudioConfig 

type AudioConfig struct {
	Format  string `json:"format" yaml:"format" default:"pcm"`
	Codec   string `json:"codec" yaml:"codec" default:"raw"`
	Rate    int    `json:"rate" yaml:"rate" default:"16000"`
	Bits    int    `json:"bits" yaml:"bits" default:"16"`
	Channel int    `json:"channel" yaml:"channel" default:"1"`
}

AudioConfig represents audio format configuration.

type AudioFrame 

type AudioFrame struct {
	IsEnd bool
	Data  []byte
}

AudioFrame represents a single audio frame to be sent to the ASR server.

type AudioMeta 

type AudioMeta struct {
	Format  string `json:"format,omitempty"`
	Codec   string `json:"codec,omitempty"`
	Rate    int    `json:"rate,omitempty"`
	Bits    int    `json:"bits,omitempty"`
	Channel int    `json:"channel,omitempty"`
}

AudioMeta represents audio format metadata in the ASR request payload.

type AuthConfig 

type AuthConfig struct {
	ResourceId string `json:"resource_id" yaml:"resource_id"`
	AccessKey  string `json:"access_key" yaml:"access_key"`
	AppKey     string `json:"app_key" yaml:"app_key"`
}

AuthConfig represents authentication configuration.

type BaseEngine 

type BaseEngine struct {
	// contains filtered or unexported fields
}

BaseEngine provides common functionality that ASR vendor implementations can embed to reduce boilerplate. It handles callback storage, dialog ID management, timing, sentence accumulation, and thread-safe state access.

Vendor implementations should embed *BaseEngine and override only the vendor-specific methods (ConnAndReceive, SendAudioBytes, etc.).

func NewBaseEngine 

func NewBaseEngine(vendorName string) *BaseEngine

NewBaseEngine creates a BaseEngine with the given vendor name.

func (*BaseEngine) Callbacks 

func (b *BaseEngine) Callbacks() (ResultFunc, ErrorFunc)

Callbacks returns the stored result and error callbacks. This is useful for vendor implementations that need to call them directly.

func (*BaseEngine) DialogID 

func (b *BaseEngine) DialogID() string

DialogID returns the current dialog identifier.

func (*BaseEngine) EmitError 

func (b *BaseEngine) EmitError(err error, isFatal bool)

EmitError emits an error via the error callback.

func (*BaseEngine) EmitFinal 

func (b *BaseEngine) EmitFinal(text string)

EmitFinal emits a final recognition result via the callback. If text is empty, the last partial sentence is used.

func (*BaseEngine) EmitPartial 

func (b *BaseEngine) EmitPartial(text string)

EmitPartial emits a partial recognition result via the callback.

func (*BaseEngine) HasSentence 

func (b *BaseEngine) HasSentence() bool

HasSentence returns true if there is a non-empty accumulated sentence.

func (*BaseEngine) Init 

func (b *BaseEngine) Init(tr ResultFunc, er ErrorFunc)

Init stores the result and error callbacks.

func (*BaseEngine) MarkEnd 

func (b *BaseEngine) MarkEnd()

MarkEnd records the end-of-request timestamp.

func (*BaseEngine) ResetState 

func (b *BaseEngine) ResetState()

ResetState resets the engine state for a new recognition session. This includes clearing the accumulated sentence, resetting timing, and setting the send request time to now.

func (*BaseEngine) Sentence 

func (b *BaseEngine) Sentence() string

Sentence returns the current accumulated sentence text.

func (*BaseEngine) SetDialogID 

func (b *BaseEngine) SetDialogID(id string)

SetDialogID sets the current dialog identifier.

func (*BaseEngine) SinceSend 

func (b *BaseEngine) SinceSend() time.Duration

SinceSend returns the duration since the request was started. Returns 0 if ResetState has not been called.

func (*BaseEngine) Vendor 

func (b *BaseEngine) Vendor() string

Vendor returns the vendor name.

type BufferConfig 

type BufferConfig struct {
	SegmentDurationMs int `json:"segment_duration_ms" yaml:"segment_duration_ms" default:"200"`
	MaxBufferSize     int `json:"max_buffer_size" yaml:"max_buffer_size"`
}

BufferConfig represents buffer configuration.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the low-level WebSocket ASR client that handles the binary protocol.

func NewClient 

func NewClient(config *Config) *Client

NewClient creates a new ASR client.

func (*Client) Close 

func (c *Client) Close()

Close gracefully closes the connection.

func (*Client) Connect 

func (c *Client) Connect(ctx context.Context) error

Connect establishes WebSocket connection and authenticates.

func (*Client) GetTraceID 

func (c *Client) GetTraceID() string

GetTraceID returns the trace ID from the connection.

func (*Client) IsClosed 

func (c *Client) IsClosed() bool

IsClosed returns true if the client is closed.

func (*Client) ReceiveResult 

func (c *Client) ReceiveResult() (*Response, error)

ReceiveResult returns the next result from the queue.

func (*Client) SendAudioFrame 

func (c *Client) SendAudioFrame(frame *AudioFrame) error

SendAudioFrame sends an audio frame to the server.

func (*Client) SetErrorCallback 

func (c *Client) SetErrorCallback(handler func(error))

SetErrorCallback sets the error handler function.

func (*Client) SetTimeouts 

func (c *Client) SetTimeouts(sendTimeout, recvTimeout time.Duration)

SetTimeouts sets the timeouts for send and receive operations.

type CompressionType 

type CompressionType byte

type Config 

type Config struct {
	URL     string        `json:"url" yaml:"url"`
	Auth    AuthConfig    `json:"auth" yaml:"auth"`
	User    UserConfig    `json:"user" yaml:"user"`
	Audio   AudioConfig   `json:"audio" yaml:"audio"`
	Request RequestConfig `json:"request" yaml:"request"`
	Buffer  BufferConfig  `json:"buffer" yaml:"buffer"`
}

Config represents the configuration for ASR client.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a default configuration.

func (*Config) CalculateBufferSize 

func (c *Config) CalculateBufferSize() int

CalculateBufferSize calculates the buffer size based on audio format and segment duration.

func (*Config) WithAudio 

func (c *Config) WithAudio(audio AudioConfig) *Config

WithAudio sets the audio configuration.

func (*Config) WithAuth 

func (c *Config) WithAuth(auth AuthConfig) *Config

WithAuth sets the auth configuration.

func (*Config) WithBuffer 

func (c *Config) WithBuffer(buffer BufferConfig) *Config

WithBuffer sets the buffer configuration.

func (*Config) WithRequest 

func (c *Config) WithRequest(request RequestConfig) *Config

WithRequest sets the request configuration.

func (*Config) WithURL 

func (c *Config) WithURL(url string) *Config

WithURL sets the URL for the ASR service.

func (*Config) WithUser 

func (c *Config) WithUser(user UserConfig) *Config

WithUser sets the user configuration.

type CorpusConfig 

type CorpusConfig struct {
	BoostingTableName string `json:"boosting_table_name" yaml:"boosting_table_name"`
	CorrectTableName  string `json:"correct_table_name" yaml:"correct_table_name"`
	Context           string `json:"context" yaml:"context"`
}

CorpusConfig represents corpus configuration.

type CorpusMeta 

type CorpusMeta struct {
	BoostingTableName string `json:"boosting_table_name,omitempty"`
	CorrectTableName  string `json:"correct_table_name,omitempty"`
	Context           string `json:"context,omitempty"`
}

CorpusMeta represents corpus metadata in the ASR request payload.

type Creator 

type Creator func(TranscriberConfig) (Engine, error)

Creator is a function that creates an Engine from a TranscriberConfig.

type DefaultFactory 

type DefaultFactory struct {
	// contains filtered or unexported fields
}

DefaultFactory is the thread-safe default implementation of Factory.

func GetGlobalFactory 

func GetGlobalFactory() *DefaultFactory

GetGlobalFactory returns the global factory instance.

func NewFactory 

func NewFactory() *DefaultFactory

NewFactory creates a new empty factory.

func (*DefaultFactory) CreateTranscriber 

func (f *DefaultFactory) CreateTranscriber(config TranscriberConfig) (Engine, error)

CreateTranscriber looks up the creator for the config's vendor and invokes it.

func (*DefaultFactory) GetSupportedVendors 

func (f *DefaultFactory) GetSupportedVendors() []Vendor

GetSupportedVendors returns all registered vendors.

func (*DefaultFactory) IsVendorSupported 

func (f *DefaultFactory) IsVendorSupported(vendor Vendor) bool

IsVendorSupported checks if a vendor is registered.

func (*DefaultFactory) RegisterCreator 

func (f *DefaultFactory) RegisterCreator(vendor Vendor, creator Creator)

RegisterCreator registers a creator function for a vendor.

type Engine 

type Engine interface {
	// Init registers the result and error callbacks.
	Init(resultCallback ResultFunc, errorCallback ErrorFunc)
	// Vendor returns the vendor identifier string.
	Vendor() string
	// ConnAndReceive establishes connection and starts receiving results.
	// dialogID is a unique identifier for the current dialog.
	ConnAndReceive(dialogID string) error
	// Activity returns true if the engine is actively connected.
	Activity() bool
	// RestartClient restarts the underlying client connection.
	RestartClient()
	// SendAudioBytes sends audio data for recognition.
	SendAudioBytes(data []byte) error
	// SendEnd signals end of audio stream.
	SendEnd() error
	// StopConn stops the connection and cleans up resources.
	StopConn() error
}

Engine is the core ASR engine interface that all vendors implement. This matches the SpeechRecognitionEngine interface from LingEchoX.

func Create 

func Create(config TranscriberConfig) (Engine, error)

Create is a convenience function using the global factory.

func MustCreate 

func MustCreate(config TranscriberConfig) Engine

MustCreate is like Create but panics on error.

type ErrorFunc 

type ErrorFunc func(err error, isFatal bool)

ErrorFunc is the callback for recognition errors. isFatal indicates whether the error is fatal (requires restart) or transient.

type Factory 

type Factory interface {
	CreateTranscriber(config TranscriberConfig) (Engine, error)
	GetSupportedVendors() []Vendor
	IsVendorSupported(vendor Vendor) bool
	RegisterCreator(vendor Vendor, creator Creator)
}

Factory creates ASR engines by vendor.

type HotWord 

type HotWord struct {
	Word   string `json:"word"`
	Weight int    `json:"weight"`
}

HotWord represents a hot word for boosting recognition accuracy.

type MessageType 

type MessageType byte

type MessageTypeSpecificFlags 

type MessageTypeSpecificFlags byte

type ProtocolHeader 

type ProtocolHeader struct {
	// contains filtered or unexported fields
}

ProtocolHeader represents the binary protocol header for ASR requests.

func NewDefaultHeader 

func NewDefaultHeader() *ProtocolHeader

NewDefaultHeader creates a default protocol header.

func (*ProtocolHeader) Serialize 

func (h *ProtocolHeader) Serialize() []byte

Serialize converts the header to binary format.

func (*ProtocolHeader) SetCompressionType 

func (h *ProtocolHeader) SetCompressionType(compType CompressionType) *ProtocolHeader

SetCompressionType sets the compression type.

func (*ProtocolHeader) SetMessageType 

func (h *ProtocolHeader) SetMessageType(msgType MessageType) *ProtocolHeader

SetMessageType sets the message type.

func (*ProtocolHeader) SetMessageTypeFlags 

func (h *ProtocolHeader) SetMessageTypeFlags(flags MessageTypeSpecificFlags) *ProtocolHeader

SetMessageTypeFlags sets the message type specific flags.

func (*ProtocolHeader) SetReservedData 

func (h *ProtocolHeader) SetReservedData(data []byte) *ProtocolHeader

SetReservedData sets the reserved data bytes.

func (*ProtocolHeader) SetSerializationType 

func (h *ProtocolHeader) SetSerializationType(serType SerializationType) *ProtocolHeader

SetSerializationType sets the serialization type.

type ProtocolVersion 

type ProtocolVersion byte

type Recognizer 

type Recognizer struct {
	// contains filtered or unexported fields
}

Recognizer is a high-level ASR recognizer that wraps the Client with audio buffering, callbacks, and result conversion.

func NewRecognizer 

func NewRecognizer(config *Config) *Recognizer

NewRecognizer creates a new Recognizer from a Config.

func (*Recognizer) GetTraceID 

func (r *Recognizer) GetTraceID() string

GetTraceID returns the trace ID from the underlying client.

func (*Recognizer) OnError 

func (r *Recognizer) OnError(callback onErrorFunc)

OnError registers the callback for error handling.

func (*Recognizer) OnResult 

func (r *Recognizer) OnResult(callback onResultFunc)

OnResult registers the callback for recognition results.

func (*Recognizer) SendAudioFrame 

func (r *Recognizer) SendAudioFrame(frame *AudioFrame) error

SendAudioFrame sends an audio frame to the recognizer. If end is true, all buffered data is flushed and an end marker is sent.

func (*Recognizer) Start 

func (r *Recognizer) Start() error

Start connects to the ASR server and begins receiving results.

func (*Recognizer) Stop 

func (r *Recognizer) Stop()

Stop closes the recognizer and releases resources.

type RequestConfig 

type RequestConfig struct {
	ModelName       string       `json:"model_name" yaml:"model_name" default:"bigmodel"`
	EnableITN       bool         `json:"enable_itn" yaml:"enable_itn" default:"true"`
	EnablePUNC      bool         `json:"enable_punc" yaml:"enable_punc" default:"true"`
	EnableDDC       bool         `json:"enable_ddc" yaml:"enable_ddc" default:"true"`
	ShowUtterances  bool         `json:"show_utterances" yaml:"show_utterances" default:"true"`
	EnableNonstream bool         `json:"enable_nonstream" yaml:"enable_nonstream" default:"false"`
	EndWindowSize   int          `json:"end_window_size" yaml:"end_window_size"`
	Corpus          CorpusConfig `json:"corpus" yaml:"corpus"`
}

RequestConfig represents request configuration.

type RequestMeta 

type RequestMeta struct {
	ModelName       string     `json:"model_name,omitempty"`
	EnableITN       bool       `json:"enable_itn,omitempty"`
	EnablePUNC      bool       `json:"enable_punc,omitempty"`
	EnableDDC       bool       `json:"enable_ddc,omitempty"`
	ShowUtterances  bool       `json:"show_utterances"`
	EnableNonstream bool       `json:"enable_nonstream"`
	EndWindowSize   int        `json:"end_window_size,omitempty"`
	Corpus          CorpusMeta `json:"corpus,omitempty"`
}

RequestMeta represents request metadata in the ASR request payload.

type RequestPayload 

type RequestPayload struct {
	User    UserMeta    `json:"user"`
	Audio   AudioMeta   `json:"audio"`
	Request RequestMeta `json:"request"`
}

RequestPayload represents the full ASR request payload.

type Response 

type Response struct {
	Code            int              `json:"code"`
	Event           int              `json:"event"`
	IsLastPackage   bool             `json:"is_last_package"`
	PayloadSequence int32            `json:"payload_sequence"`
	PayloadSize     int              `json:"payload_size"`
	PayloadMsg      *ResponsePayload `json:"payload_msg"`
	Err             error
}

Response represents a parsed ASR response.

func ParseResponse 

func ParseResponse(msg []byte) *Response

ParseResponse parses the binary response message.

type ResponsePayload 

type ResponsePayload struct {
	AudioInfo struct {
		Duration int `json:"duration"`
	} `json:"audio_info"`
	Result struct {
		Text       string `json:"text"`
		Utterances []struct {
			Definite  bool   `json:"definite"`
			EndTime   int    `json:"end_time"`
			StartTime int    `json:"start_time"`
			Text      string `json:"text"`
			Words     []struct {
				EndTime   int    `json:"end_time"`
				StartTime int    `json:"start_time"`
				Text      string `json:"text"`
			} `json:"words"`
		} `json:"utterances,omitempty"`
	} `json:"result"`
	Error string `json:"error,omitempty"`
}

ResponsePayload represents the ASR response payload.

type Result 

type Result struct {
	Text      string    `json:"text"`
	IsFinal   bool      `json:"is_final"`
	Timestamp time.Time `json:"timestamp"`
	Error     error     `json:"error,omitempty"`
}

Result represents a single recognition result.

type ResultCallback 

type ResultCallback func(*Result)

ResultCallback defines the callback for handling recognition results.

type ResultFunc 

type ResultFunc func(text string, isLast bool, duration time.Duration, dialogID string)

ResultFunc is the callback for successful speech recognition results. text: recognized text isLast: true if this is the final result for the current utterance duration: time since the recognition request started dialogID: unique identifier for the current dialog/utterance

type SerializationType 

type SerializationType byte

type TimeoutConfig 

type TimeoutConfig struct {
	Send time.Duration
	Read time.Duration
}

TimeoutConfig holds timeout settings for ASR clients.

func DefaultTimeoutConfig 

func DefaultTimeoutConfig() TimeoutConfig

DefaultTimeoutConfig returns default timeout settings.

type TranscriberConfig 

type TranscriberConfig interface {
	GetVendor() Vendor
}

TranscriberConfig is the unified config interface for ASR engines.

type UserConfig 

type UserConfig struct {
	UID        string `json:"uid" yaml:"uid" default:"demo_uid"`
	DID        string `json:"did" yaml:"did"`
	Platform   string `json:"platform" yaml:"platform"`
	SDKVersion string `json:"sdk_version" yaml:"sdk_version"`
	APPVersion string `json:"app_version" yaml:"app_version"`
}

UserConfig represents user metadata configuration.

type UserMeta 

type UserMeta struct {
	UID        string `json:"uid,omitempty"`
	DID        string `json:"did,omitempty"`
	Platform   string `json:"platform,omitempty"`
	SDKVersion string `json:"sdk_version,omitempty"`
	APPVersion string `json:"app_version,omitempty"`
}

UserMeta represents user metadata in the ASR request payload.

type Vendor 

type Vendor string

Vendor identifies an ASR service provider. 

const (
	VendorQCloud         Vendor = "qcloud"
	VendorGoogle         Vendor = "google"
	VendorAliyun         Vendor = "aliyun"
	VendorFunASR         Vendor = "funasr"
	VendorVolcengine     Vendor = "volcengine"
	VendorVolcengineLLM  Vendor = "volcllmasr"
	VendorXfyunMul       Vendor = "xfyun_mul"
	VendorGladia         Vendor = "gladia"
	VendorFunASRRealtime Vendor = "funasr_realtime"
	VendorWhisper        Vendor = "whisper"
	VendorDeepgram       Vendor = "deepgram"
	VendorAWS            Vendor = "aws"
	VendorBaidu          Vendor = "baidu"
	VendorVoiceAPI       Vendor = "voiceapi"
	VendorLocal          Vendor = "local"
)

func AllVendors 

func AllVendors() []Vendor

AllVendors returns all known vendor constants in a deterministic order.

func GetVendor 

func GetVendor(provider string) Vendor

GetVendor returns the Vendor enum for a provider string.

Source Files

View all Source files

Directories

Path Synopsis
aws module
baidu module

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.