majordomo/audio/diarize.go

package audio

import "context"

// DiarizationRequest is a speaker-labelled transcription request ("who said
// what"). Audio is carried as bytes (never a URL), mirroring
// TranscriptionRequest. Zero values mean "backend default" (ADR-0020).
type DiarizationRequest struct {
	// Audio is the encoded audio (or video container) to transcribe.
	Audio []byte

	// MIME is the audio MIME type (e.g. "audio/mpeg"); "" = let the backend
	// sniff it.
	MIME string

	// Filename is the multipart filename hint some backends key their format
	// detection on; "" derives one from MIME or falls back to "audio".
	Filename string

	// Language is a BCP-47/ISO-639 hint (e.g. "en"); "" = auto-detect.
	Language string

	// MinSpeakers / MaxSpeakers bound the speaker count when the caller knows
	// it; 0 = let the backend estimate.
	MinSpeakers int
	MaxSpeakers int
}

// DiarizationSegment is one speaker turn.
type DiarizationSegment struct {
	// Start and End are offsets into the audio, in seconds.
	Start float64
	End   float64

	// Speaker is the backend's per-file speaker label (e.g. "SPEAKER_00").
	// Labels are relative to this one file — they are NOT stable identities
	// across files.
	Speaker string

	// Text is the transcript of this turn.
	Text string
}

// DiarizationResult is the canonical diarization result.
type DiarizationResult struct {
	// Text is the full transcript, unlabelled.
	Text string

	// Language is the detected (or requested) language code; may be "".
	Language string

	// Segments are the speaker turns in time order.
	Segments []DiarizationSegment

	// Raw is the provider-native response object. May be nil.
	Raw any
}

// DiarizationOption mutates a DiarizationRequest before it is sent.
type DiarizationOption func(*DiarizationRequest)

// WithDiarizationLanguage sets the language hint (e.g. "en").
func WithDiarizationLanguage(l string) DiarizationOption {
	return func(r *DiarizationRequest) { r.Language = l }
}

// WithSpeakerBounds bounds the expected speaker count (0 leaves a bound
// unset).
func WithSpeakerBounds(minSpeakers, maxSpeakers int) DiarizationOption {
	return func(r *DiarizationRequest) {
		r.MinSpeakers, r.MaxSpeakers = minSpeakers, maxSpeakers
	}
}

// Apply returns a copy of the request with all options applied.
func (r DiarizationRequest) Apply(opts ...DiarizationOption) DiarizationRequest {
	for _, opt := range opts {
		opt(&r)
	}
	return r
}

// DiarizationModel transcribes audio with speaker labels.
type DiarizationModel interface {
	// Diarize converts the request's audio into speaker-labelled segments.
	Diarize(ctx context.Context, req DiarizationRequest, opts ...DiarizationOption) (*DiarizationResult, error)
}

// DiarizationModelOption configures a DiarizationModel at construction time.
// Reserved for future per-model settings.
type DiarizationModelOption func(*DiarizationModelConfig)

// DiarizationModelConfig carries per-model construction settings.
type DiarizationModelConfig struct{}

// ApplyDiarizationModelOptions folds options into a config.
func ApplyDiarizationModelOptions(opts []DiarizationModelOption) DiarizationModelConfig {
	var cfg DiarizationModelConfig
	for _, opt := range opts {
		opt(&cfg)
	}
	return cfg
}

// DiarizationProvider mints diarization models bound to one backend.
type DiarizationProvider interface {
	// Name is the registry identifier for the provider.
	Name() string

	// DiarizationModel returns a DiarizationModel bound to the given id
	// (passed through to the backend verbatim; no catalog validation).
	DiarizationModel(id string, opts ...DiarizationModelOption) (DiarizationModel, error)
}