/** Where a voice memo came from. */
interface VoiceSource {
    /** Channel that delivered the audio: 'telegram-voice', 'browser-upload', 'call-recording', ... */
    channel: string;
    /** Channel-specific identifier (e.g. Telegram file_id, browser blob id). */
    externalId: string;
    /** Fetch the raw audio bytes. Implementation channel-specific. */
    fetchBytes: () => Promise<Buffer>;
    /** Optional MIME type hint ('audio/ogg' for Telegram voice, 'audio/mp3', 'audio/wav', ...). */
    mimeType?: string;
    /** Optional duration hint in seconds. */
    durationSec?: number;
    /** Optional accompanying text (e.g. a caption on a Telegram voice memo). */
    caption?: string;
}
/** Pluggable durable storage for audio. Same shape as PhotoStorage by design. */
interface VoiceStorage {
    /**
     * Persist the audio, return a stable URL and storage key. The orchestrator
     * calls `source.fetchBytes()` exactly once and hands the buffer in via a
     * memoised source, so adapters can call `source.fetchBytes()` freely
     * without triggering a second network fetch.
     */
    persist: (source: VoiceSource, opts: {
        agentId: string;
        userId?: string;
    }) => Promise<{
        url: string;
        key: string;
    }>;
}
/** A single transcribed segment within a Transcript. */
interface TranscriptSegment {
    /** Seconds from the beginning of the audio. */
    start: number;
    /** Seconds from the beginning of the audio. */
    end: number;
    /** Transcribed text for this segment. */
    text: string;
    /** 0-1 model confidence for this segment. */
    confidence: number;
    /** Speaker label when diarization is enabled (e.g. 'speaker_0'). */
    speaker?: string;
}
/** Result of STT — what the orchestrator returns. */
interface Transcript {
    /** Full concatenated transcript. */
    text: string;
    /** Per-segment breakdown. May be a single segment for providers that don't return them. */
    segments: TranscriptSegment[];
    /** Total duration in seconds. */
    duration: number;
    /** ISO language code, e.g. 'en-AU'. */
    language: string;
    /** Overall 0-1 confidence. */
    confidence: number;
    /** Persisted audio URL (so the caller can link the recording to a record later). */
    audioUrl: string;
    /** Storage key (for backend cleanup / migration). */
    audioKey: string;
}
/** Default ISO language code when the caller doesn't specify one. */
declare const DEFAULT_LANGUAGE = "en-AU";
/** Default MIME type when a VoiceSource doesn't supply one. Telegram voice is OGG/Opus. */
declare const DEFAULT_MIME = "audio/ogg";

interface STTTranscribeArgs {
    /** Raw audio bytes to transcribe. */
    audioBytes: Buffer;
    /** MIME type of the audio (e.g. 'audio/ogg', 'audio/mp3', 'audio/wav'). */
    mimeType: string;
    /** ISO language code. Defaults to 'en-AU' at the orchestrator boundary. */
    language?: string;
    /** Ask the provider to label speaker turns when supported. */
    enableSpeakerDiarization?: boolean;
    /** Expected speaker count when diarization is on (hint, not a hard cap). */
    expectedSpeakers?: number;
}
/**
 * Provider-agnostic STT result. The orchestrator fills `audioUrl` and
 * `audioKey` in after persistence — providers don't need to know about
 * storage at all.
 */
type STTResult = Omit<Transcript, "audioUrl" | "audioKey">;
interface STTProvider {
    /** Human-readable provider name for logs / telemetry (e.g. 'google-cloud-stt'). */
    name: string;
    transcribe(args: STTTranscribeArgs): Promise<STTResult>;
}

interface ProcessVoiceArgs {
    source: VoiceSource;
    storage: VoiceStorage;
    stt: STTProvider;
    /** ISO language code passed through to STT. Defaults to 'en-AU'. */
    language?: string;
    /** Request speaker turn labels when the provider supports diarization. */
    enableSpeakerDiarization?: boolean;
    /** Expected speaker count hint when diarization is on. */
    expectedSpeakers?: number;
    ctx: {
        agentId: string;
        userId?: string;
    };
}
declare function processVoice(args: ProcessVoiceArgs): Promise<Transcript>;

declare class MemoryVoiceStorage implements VoiceStorage {
    private readonly store;
    persist(source: VoiceSource, opts: {
        agentId: string;
        userId?: string;
    }): Promise<{
        url: string;
        key: string;
    }>;
    get(key: string): Buffer | undefined;
    has(key: string): boolean;
    size(): number;
    clear(): void;
}

interface MockSTTOptions {
    /** Provider name reported in telemetry / logs. Defaults to 'mock-stt'. */
    name?: string;
    /** Fixed result returned for every call. Ignored when `queue` is supplied. */
    result?: STTResult;
    /** Queue of results — shifted on each call. */
    queue?: STTResult[];
}
declare class MockSTTProvider implements STTProvider {
    readonly name: string;
    private readonly fixed?;
    private readonly queue;
    /** All transcribe() calls recorded in order. Useful for assertions in tests. */
    readonly calls: STTTranscribeArgs[];
    constructor(opts?: MockSTTOptions);
    transcribe(args: STTTranscribeArgs): Promise<STTResult>;
}

declare const index_DEFAULT_LANGUAGE: typeof DEFAULT_LANGUAGE;
declare const index_DEFAULT_MIME: typeof DEFAULT_MIME;
type index_MemoryVoiceStorage = MemoryVoiceStorage;
declare const index_MemoryVoiceStorage: typeof MemoryVoiceStorage;
type index_MockSTTOptions = MockSTTOptions;
type index_MockSTTProvider = MockSTTProvider;
declare const index_MockSTTProvider: typeof MockSTTProvider;
type index_ProcessVoiceArgs = ProcessVoiceArgs;
type index_STTProvider = STTProvider;
type index_STTResult = STTResult;
type index_STTTranscribeArgs = STTTranscribeArgs;
type index_Transcript = Transcript;
type index_TranscriptSegment = TranscriptSegment;
type index_VoiceSource = VoiceSource;
type index_VoiceStorage = VoiceStorage;
declare const index_processVoice: typeof processVoice;
declare namespace index {
  export { index_DEFAULT_LANGUAGE as DEFAULT_LANGUAGE, index_DEFAULT_MIME as DEFAULT_MIME, index_MemoryVoiceStorage as MemoryVoiceStorage, type index_MockSTTOptions as MockSTTOptions, index_MockSTTProvider as MockSTTProvider, type index_ProcessVoiceArgs as ProcessVoiceArgs, type index_STTProvider as STTProvider, type index_STTResult as STTResult, type index_STTTranscribeArgs as STTTranscribeArgs, type index_Transcript as Transcript, type index_TranscriptSegment as TranscriptSegment, type index_VoiceSource as VoiceSource, type index_VoiceStorage as VoiceStorage, index_processVoice as processVoice };
}

export { DEFAULT_LANGUAGE as D, MemoryVoiceStorage as M, type ProcessVoiceArgs as P, type STTProvider as S, type Transcript as T, type VoiceSource as V, DEFAULT_MIME as a, type MockSTTOptions as b, MockSTTProvider as c, type STTResult as d, type STTTranscribeArgs as e, type TranscriptSegment as f, type VoiceStorage as g, index as i, processVoice as p };
