Documentation
¶
Overview ¶
Package speaker defines SpeechKit's public speaker diarization and attribution contracts. It is intentionally provider-neutral so Dictation, Assist, Voice Agent fallbacks, and HTTP clients can share the same result shape without importing desktop internals.
Index ¶
- Constants
- func NormalizeSpeakerLabel(raw any) string
- type AudioEncoding
- type AudioFormat
- type Capability
- type DiarizationResult
- type IdentificationLevel
- type KnownSpeaker
- type Options
- type Provider
- type ProviderProfile
- type Speaker
- type SpeakerFrame
- type SpeakerSegment
- type SpeakerStream
- type SpeakerWord
- type StreamingProvider
Constants ¶
const ( SpeakerTypeName = "name" SpeakerTypeRole = "role" )
Variables ¶
This section is empty.
Functions ¶
func NormalizeSpeakerLabel ¶
Types ¶
type AudioEncoding ¶
type AudioEncoding string
AudioEncoding names the on-wire audio encoding a streaming speaker provider receives.
const ( AudioEncodingLinear16 AudioEncoding = "linear16" AudioEncodingPCM16 AudioEncoding = "pcm16" )
type AudioFormat ¶
type AudioFormat struct {
Encoding AudioEncoding `json:"encoding,omitempty"`
SampleRateHz int `json:"sampleRateHz,omitempty"`
Channels int `json:"channels,omitempty"`
Container string `json:"container,omitempty"`
}
AudioFormat describes the raw microphone stream passed to a speaker streaming provider. Empty fields normalize to SpeechKit's Voice Agent default: 16 kHz S16 mono PCM.
func (AudioFormat) Normalized ¶
func (f AudioFormat) Normalized() AudioFormat
type Capability ¶
type Capability string
Capability names speaker-specific add-on capabilities. These are not modes: hosts opt into them per request or per provider profile.
const ( CapabilityDiarization Capability = "speaker_diarization" CapabilityIdentification Capability = "speaker_identification" CapabilityAttribution Capability = "speaker_attribution" CapabilityEnrollment Capability = "speaker_enrollment" )
type DiarizationResult ¶
type DiarizationResult struct {
Provider string `json:"provider,omitempty"`
Model string `json:"model,omitempty"`
Level IdentificationLevel `json:"level,omitempty"`
Text string `json:"text,omitempty"`
Language string `json:"language,omitempty"`
Speakers []Speaker `json:"speakers,omitempty"`
Segments []SpeakerSegment `json:"segments,omitempty"`
Words []SpeakerWord `json:"words,omitempty"`
}
DiarizationResult is the canonical output contract for speaker add-ons.
type IdentificationLevel ¶
type IdentificationLevel string
IdentificationLevel describes how far a provider went beyond plain transcription.
const ( IdentificationNone IdentificationLevel = "none" IdentificationDiarization IdentificationLevel = "diarization" IdentificationAttribution IdentificationLevel = "attribution" IdentificationProviderID IdentificationLevel = "provider_identification" IdentificationBiometric IdentificationLevel = "biometric" )
type KnownSpeaker ¶
type KnownSpeaker struct {
ID string `json:"id,omitempty"`
DisplayName string `json:"displayName,omitempty"`
Role string `json:"role,omitempty"`
Description string `json:"description,omitempty"`
}
KnownSpeaker is app-provided context for attribution or provider-supported speaker identification. It is not a biometric enrollment record.
type Options ¶
type Options struct {
Enabled bool `json:"enabled,omitempty"`
Diarization bool `json:"diarization,omitempty"`
Identification bool `json:"identification,omitempty"`
Attribution bool `json:"attribution,omitempty"`
ProviderProfileID string `json:"providerProfileId,omitempty"`
Model string `json:"model,omitempty"`
DiarizationModel string `json:"diarizationModel,omitempty"`
Language string `json:"language,omitempty"`
SpeakersExpected int `json:"speakersExpected,omitempty"`
MinSpeakersExpected int `json:"minSpeakersExpected,omitempty"`
MaxSpeakersExpected int `json:"maxSpeakersExpected,omitempty"`
SpeakerType string `json:"speakerType,omitempty"`
KnownValues []string `json:"knownValues,omitempty"`
KnownSpeakers []KnownSpeaker `json:"knownSpeakers,omitempty"`
PreferStreaming bool `json:"preferStreaming,omitempty"`
AllowProviderMapping bool `json:"allowProviderMapping,omitempty"`
}
Options configures a single diarization request. Empty options mean "transcribe only"; providers must not enable speaker work unless WantsDiarization returns true.
func (Options) Normalized ¶
func (Options) WantsDiarization ¶
func (Options) WantsIdentification ¶
type Provider ¶
type Provider interface {
Diarize(ctx context.Context, audio []byte, opts Options) (*DiarizationResult, error)
Name() string
Health(ctx context.Context) error
}
Provider is the public add-on provider contract for applications that want diarization independent from the STT router.
type ProviderProfile ¶
type ProviderProfile struct {
ID string `json:"id"`
Name string `json:"name"`
Provider string `json:"provider"`
Framework string `json:"framework"`
Mode string `json:"mode"`
ProviderKind string `json:"providerKind"`
ExecutionMode string `json:"executionMode"`
Streaming bool `json:"streaming"`
Batch bool `json:"batch"`
IdentificationLevel string `json:"identificationLevel"`
Capabilities []Capability `json:"capabilities,omitempty"`
RequiredEnvVars []string `json:"requiredEnvVars,omitempty"`
Status string `json:"status,omitempty"`
}
ProviderProfile is a provider-neutral capability matrix row for Notion or setup UIs. Values are strings by design to avoid coupling this subpackage to the parent speechkit catalog package.
func DefaultProviderProfiles ¶
func DefaultProviderProfiles() []ProviderProfile
type Speaker ¶
type Speaker struct {
Label string `json:"label"`
PersonID string `json:"personId,omitempty"`
DisplayName string `json:"displayName,omitempty"`
Role string `json:"role,omitempty"`
Confidence float64 `json:"confidence,omitempty"`
AttributionConfidence float64 `json:"attributionConfidence,omitempty"`
}
Speaker is the canonical person/speaker entry for a diarized transcript.
func SpeakersFromSegments ¶
func SpeakersFromSegments(segments []SpeakerSegment) []Speaker
type SpeakerFrame ¶
type SpeakerFrame struct {
Provider string `json:"provider,omitempty"`
Model string `json:"model,omitempty"`
Sequence int64 `json:"sequence,omitempty"`
Text string `json:"text,omitempty"`
IsFinal bool `json:"isFinal,omitempty"`
Segment *SpeakerSegment `json:"segment,omitempty"`
Words []SpeakerWord `json:"words,omitempty"`
Speakers []Speaker `json:"speakers,omitempty"`
LatencyMs int64 `json:"latencyMs,omitempty"`
}
SpeakerFrame is the canonical realtime speaker attribution frame. It is intentionally shaped like DiarizationResult fragments so Voice Agent, realtime clients, and SDKs can consume one public contract.
func FrameFromWords ¶
func FrameFromWords(provider, model string, sequence int64, text string, final bool, words []SpeakerWord, latencyMs int64) SpeakerFrame
FrameFromWords builds the common frame fields from provider word output.
type SpeakerSegment ¶
type SpeakerSegment struct {
Text string `json:"text"`
StartMs int64 `json:"startMs,omitempty"`
EndMs int64 `json:"endMs,omitempty"`
SpeakerLabel string `json:"speakerLabel,omitempty"`
SpeakerConfidence float64 `json:"speakerConfidence,omitempty"`
PersonID string `json:"personId,omitempty"`
DisplayName string `json:"displayName,omitempty"`
Role string `json:"role,omitempty"`
AttributionConfidence float64 `json:"attributionConfidence,omitempty"`
Words []SpeakerWord `json:"words,omitempty"`
}
SpeakerSegment groups contiguous speech attributed to one speaker.
func BuildSegmentsFromWords ¶
func BuildSegmentsFromWords(words []SpeakerWord) []SpeakerSegment
type SpeakerStream ¶
type SpeakerStream interface {
SendAudio(ctx context.Context, chunk []byte) error
EndAudio(ctx context.Context) error
Receive(ctx context.Context) (*SpeakerFrame, error)
Close() error
}
SpeakerStream is a bidirectional streaming speaker session.
type SpeakerWord ¶
type SpeakerWord struct {
Text string `json:"text"`
StartMs int64 `json:"startMs,omitempty"`
EndMs int64 `json:"endMs,omitempty"`
Confidence float64 `json:"confidence,omitempty"`
SpeakerLabel string `json:"speakerLabel,omitempty"`
SpeakerConfidence float64 `json:"speakerConfidence,omitempty"`
PersonID string `json:"personId,omitempty"`
DisplayName string `json:"displayName,omitempty"`
Role string `json:"role,omitempty"`
AttributionConfidence float64 `json:"attributionConfidence,omitempty"`
}
SpeakerWord is the word-level speaker attribution surface shared by Deepgram, AssemblyAI, and Google. Times are milliseconds from audio start.
type StreamingProvider ¶
type StreamingProvider interface {
StartSpeakerStream(ctx context.Context, opts Options, format AudioFormat) (SpeakerStream, error)
}
StreamingProvider is implemented by speaker providers that support live attribution against a stream of raw audio chunks.
Source Files