dictation

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

type Options struct {
	Router                 Transcriber
	MaxUploadMB            int    // request body ceiling; 0 disables the limit (discouraged)
	MaxDecodedAudioSeconds int    // decoded PCM duration ceiling; 0 disables the decode-duration cap
	DefaultPrompt          string // applied when the request does not provide a prompt
	Store                  store.Store
	ActiveTemplateIDs      []string
	// DefaultProviderProfileID is the server's configured Dictation primary
	// (ModelSelection.Dictate.PrimaryProfileID). It is the lowest-precedence
	// provider preference: explicit request override → edge-injected user
	// preference → this default → the router's configured fallback order.
	DefaultProviderProfileID string
}

type StreamAdapter struct {
	Session *wssession.ManagedSession
	Conn    *websocket.Conn
	Router  StreamRouter
	// IdleTimeout terminates a session without any client- or provider-side
	// activity. Zero disables the watchdog.
	IdleTimeout time.Duration
	// MaxDuration terminates a session after this wall-clock duration. Zero
	// disables the hard cap.
	MaxDuration time.Duration
	// MaxStreamAudio caps cumulative uploaded audio (decoded duration)
	// across all segments of this session. Zero disables the budget.
	MaxStreamAudio time.Duration
	// OnClose runs after the read pump has returned. Typically removes the
	// session from the manager.
	OnClose func()
	// contains filtered or unexported fields
}

type StreamAudioFormat struct {
	Encoding     string `json:"encoding,omitempty"`       // "linear16" (default) | "pcm16"
	SampleRateHz int    `json:"sample_rate_hz,omitempty"` // default 16000
	Channels     int    `json:"channels,omitempty"`       // default 1
}

type StreamErrorFrame struct {
	Type    string `json:"type"` // "error"
	Code    string `json:"code"`
	Message string `json:"message"`
}

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

type StreamHandlerOptions struct {
	Manager *wssession.SessionManager
	Router  StreamRouter
	// PublicURL overrides request-derived scheme/host in returned ws_url
	// values (Docker/proxy deployments).
	PublicURL         string
	AllowedOrigins    []string
	TrustedProxyCIDRs []string
	// IdleTimeout terminates a session without any client- or provider-side
	// activity. Zero defaults to 5 minutes; negative disables.
	IdleTimeout time.Duration
	// MaxSessionDuration hard-caps a session's wall-clock lifetime. Zero
	// disables the cap.
	MaxSessionDuration time.Duration
	// MaxStreamAudio caps the cumulative PCM a session may upload, expressed
	// as decoded audio duration. Zero disables the budget.
	MaxStreamAudio time.Duration
	// ReadLimit caps per-frame bytes; zero or negative falls back to 64 KiB.
	ReadLimit int64
}

type StreamPongFrame struct {
	Type string `json:"type"` // "pong"
}

type StreamReadyFrame struct {
	Type      string `json:"type"` // "ready"
	SegmentID uint64 `json:"segment_id"`
}

type StreamRouter interface {
	StartDictationStream(ctx context.Context, opts speechkit.DictationStreamOptions, format speaker.AudioFormat) (speechkit.DictationStream, error)
	HasDictationStreaming() bool
}

type StreamSegmentDoneFrame struct {
	Type      string `json:"type"` // "segment_done"
	SegmentID uint64 `json:"segment_id"`
}

type StreamSessionEndFrame struct {
	Type   string `json:"type"` // "session_end"
	Reason string `json:"reason"`
}

type StreamStartFrame struct {
	Type              string `json:"type"` // must be "start"
	Language          string `json:"language,omitempty"`
	Model             string `json:"model,omitempty"`
	ProviderProfileID string `json:"provider_profile_id,omitempty"`
	// InterimResults defaults to true when omitted — live partials are the
	// point of this endpoint. Send false explicitly for finals-only.
	InterimResults *bool              `json:"interim_results,omitempty"`
	EndpointingMs  int                `json:"endpointing_ms,omitempty"`
	TurnDetection  bool               `json:"turn_detection,omitempty"`
	Keyterms       []string           `json:"keyterms,omitempty"`
	PromptHint     string             `json:"prompt_hint,omitempty"`
	Diarization    bool               `json:"diarization,omitempty"`
	Format         *StreamAudioFormat `json:"format,omitempty"`
}

type StreamTranscriptFrame struct {
	Type       string                     `json:"type"` // "transcript"
	SegmentID  uint64                     `json:"segment_id"`
	Sequence   int64                      `json:"sequence,omitempty"`
	Text       string                     `json:"text"`
	Done       bool                       `json:"done"`
	Language   string                     `json:"language,omitempty"`
	Confidence float64                    `json:"confidence,omitempty"`
	Provider   string                     `json:"provider,omitempty"`
	Model      string                     `json:"model,omitempty"`
	Words      []StreamWord               `json:"words,omitempty"`
	Speakers   *speaker.DiarizationResult `json:"speakers,omitempty"`
}

type StreamWord struct {
	Text       string  `json:"text"`
	Confidence float64 `json:"confidence,omitempty"`
	StartMs    int64   `json:"start_ms,omitempty"`
	EndMs      int64   `json:"end_ms,omitempty"`
}

type Transcriber interface {
	Route(ctx context.Context, audio []byte, audioDurationSecs float64, opts stt.TranscribeOpts) (*stt.Result, error)
}