@providerkit/core 0.27.2 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +15 -0
  2. package/dist/index.d.ts +1 -1
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +3 -1
  5. package/dist/index.js.map +1 -1
  6. package/dist/presets.d.ts +50 -0
  7. package/dist/presets.d.ts.map +1 -1
  8. package/dist/presets.js +82 -0
  9. package/dist/presets.js.map +1 -1
  10. package/dist/providers/gemini-speech.d.ts +25 -0
  11. package/dist/providers/gemini-speech.d.ts.map +1 -0
  12. package/dist/providers/gemini-speech.js +172 -0
  13. package/dist/providers/gemini-speech.js.map +1 -0
  14. package/dist/providers/openai-speech.d.ts +23 -0
  15. package/dist/providers/openai-speech.d.ts.map +1 -0
  16. package/dist/providers/openai-speech.js +86 -0
  17. package/dist/providers/openai-speech.js.map +1 -0
  18. package/dist/providers/speech-factory.d.ts +35 -0
  19. package/dist/providers/speech-factory.d.ts.map +1 -0
  20. package/dist/providers/speech-factory.js +47 -0
  21. package/dist/providers/speech-factory.js.map +1 -0
  22. package/dist/speech-core.d.ts +184 -0
  23. package/dist/speech-core.d.ts.map +1 -0
  24. package/dist/speech-core.js +349 -0
  25. package/dist/speech-core.js.map +1 -0
  26. package/dist/speech.d.ts +6 -0
  27. package/dist/speech.d.ts.map +1 -0
  28. package/dist/speech.js +12 -0
  29. package/dist/speech.js.map +1 -0
  30. package/dist/transport.d.ts +42 -0
  31. package/dist/transport.d.ts.map +1 -1
  32. package/dist/transport.js +154 -11
  33. package/dist/transport.js.map +1 -1
  34. package/package.json +6 -1
  35. package/src/index.ts +14 -1
  36. package/src/presets.ts +113 -0
  37. package/src/providers/gemini-speech.ts +232 -0
  38. package/src/providers/openai-speech.ts +125 -0
  39. package/src/providers/speech-factory.ts +85 -0
  40. package/src/speech-core.ts +507 -0
  41. package/src/speech.ts +24 -0
  42. package/src/transport.ts +185 -11
@@ -0,0 +1,86 @@
1
+ // The OpenAI speech wire: POST {base}/audio/speech, JSON in, audio bytes out.
2
+ // Serves OpenAI, OpenRouter and any server that copies the route (a local Kokoro,
3
+ // a proxy). One request per call; speech-core.ts says why.
4
+ import { attributionHeaders } from "../attribution.js";
5
+ import { asRecord, describeAudio, inBandFailure, prepareSpeech, resolveLimits, sniffFormat, SPEECH_FORMATS, synthesizeOnce, unusable, } from "../speech-core.js";
6
+ import { apiUrl, postBytes, versionedPath } from "../transport.js";
7
+ // A JSON or text body is an error that arrived with a 200, not audio.
8
+ const TEXT_TYPE = /^(application\/(?:[\w.+-]*\+)?json|text\/)/;
9
+ /** First byte that is not blank or a control character is "{". */
10
+ const startsLikeJson = (bytes) => bytes.subarray(0, 16).find((b) => b > 0x20) === 0x7b;
11
+ /**
12
+ * A 200 reply that is not audio: a JSON error, or JSON or text where audio belongs.
13
+ * Audio is named by its bytes first, so a server that sends audio under a wrong
14
+ * content type still gets through. `undefined` means the bytes may be audio.
15
+ */
16
+ function notAudio(provider, bytes, contentType) {
17
+ if (bytes.byteLength === 0 || sniffFormat(bytes))
18
+ return undefined;
19
+ const textual = TEXT_TYPE.test(contentType);
20
+ const body = textual || startsLikeJson(bytes) ? parseObject(bytes) : undefined;
21
+ if (body) {
22
+ return body.error !== undefined || body.errors !== undefined
23
+ ? inBandFailure(provider, body)
24
+ : unusable(provider, "unknown", "bad_audio", "the reply is JSON and holds no audio");
25
+ }
26
+ return textual
27
+ ? unusable(provider, "unknown", "bad_audio", "the reply is text, not audio")
28
+ : undefined;
29
+ }
30
+ /** Only the head is read: an error object sits at the start of a body. */
31
+ function parseObject(bytes) {
32
+ try {
33
+ return asRecord(JSON.parse(new TextDecoder().decode(bytes.subarray(0, 64 * 1024))));
34
+ }
35
+ catch {
36
+ return undefined;
37
+ }
38
+ }
39
+ export function createOpenAISpeechProvider(config) {
40
+ const id = config.id ?? "openai";
41
+ const provider = `speech:${id}`;
42
+ const baseUrl = config.baseUrl ?? "https://api.openai.com";
43
+ const limits = resolveLimits(config);
44
+ return {
45
+ id,
46
+ model: config.model,
47
+ async synthesize(request) {
48
+ const { text, voice, format } = prepareSpeech(provider, request, {
49
+ apiKey: config.apiKey,
50
+ voice: config.voice,
51
+ format: config.format,
52
+ maxInputChars: limits.maxInputChars,
53
+ formats: SPEECH_FORMATS,
54
+ });
55
+ return synthesizeOnce(provider, limits.timeoutMs, request, async (signal) => {
56
+ const { bytes, contentType } = await postBytes({
57
+ url: apiUrl(baseUrl, config.path ?? versionedPath(baseUrl, "/audio/speech")),
58
+ headers: {
59
+ ...(config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}),
60
+ ...attributionHeaders(config, config.headers),
61
+ ...config.headers,
62
+ },
63
+ body: { model: config.model, input: text, voice, response_format: format },
64
+ provider,
65
+ signal,
66
+ redirect: "error",
67
+ maxBytes: limits.maxAudioBytes,
68
+ redactErrors: true,
69
+ ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
70
+ });
71
+ // A failure inside a 200 is still a failure (invariant 11).
72
+ const problem = notAudio(provider, bytes, contentType);
73
+ if (problem)
74
+ throw problem;
75
+ const result = describeAudio(provider, bytes, format, {
76
+ model: config.model,
77
+ voice,
78
+ characters: text.length,
79
+ });
80
+ signal.throwIfAborted();
81
+ return result;
82
+ });
83
+ },
84
+ };
85
+ }
86
+ //# sourceMappingURL=openai-speech.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"openai-speech.js","sourceRoot":"","sources":["../../src/providers/openai-speech.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,35 @@
1
+ import { type ProviderPresetId } from "../presets.ts";
2
+ import type { Attribution } from "../attribution.ts";
3
+ import type { SpeechFormat, SpeechLimits, SpeechProvider } from "../speech-core.ts";
4
+ export interface SpeechProviderConfig extends SpeechLimits, Attribution {
5
+ apiKey: string;
6
+ /** Absent: the preset's `speech.defaultModel`. A preset without one needs this. */
7
+ model?: string;
8
+ /** Used when a call names no voice. Absent: the preset's `speech.defaultVoice`. */
9
+ voice?: string;
10
+ /** Used when a call names no format. Absent: the preset's `speech.defaultFormat`, else "wav". */
11
+ format?: SpeechFormat;
12
+ /**
13
+ * Replaces the preset's host, for a server that copies its route (a local speech
14
+ * server behind the `openai` preset, a proxy). The preset's default model, voice,
15
+ * format and text limit are facts about its own host, so they do not follow you
16
+ * here: pass the `model`, and a `voice` unless every call names one.
17
+ */
18
+ baseUrl?: string;
19
+ headers?: Record<string, string>;
20
+ /** The `google` preset only: caps the audio tokens generated. Refused on a wire that has no such field. */
21
+ maxOutputTokens?: number;
22
+ /** Swapped in tests, or to route through a proxy. Defaults to global fetch. */
23
+ fetchImpl?: typeof fetch;
24
+ }
25
+ /**
26
+ * Build a speech provider for a preset that can speak. A preset without a
27
+ * `speech` row throws, naming the ones that do (`SPEECH_PRESET_IDS`).
28
+ *
29
+ * ```ts
30
+ * const speech = createSpeechProvider("google", { apiKey });
31
+ * const { bytes, mimeType } = await speech.synthesize({ text: "Click Settings." });
32
+ * ```
33
+ */
34
+ export declare function createSpeechProvider(id: ProviderPresetId, config: SpeechProviderConfig): SpeechProvider;
35
+ //# sourceMappingURL=speech-factory.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"speech-factory.d.ts","sourceRoot":"","sources":["../../src/providers/speech-factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIpF,MAAM,WAAW,oBAAqB,SAAQ,YAAY,EAAE,WAAW;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,2GAA2G;IAC3G,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,gBAAgB,EACpB,MAAM,EAAE,oBAAoB,GAC3B,cAAc,CAqChB"}
@@ -0,0 +1,47 @@
1
+ // The speech twin of `createPresetProvider`: name a preset, hand over a key, get a
2
+ // speech provider. The preset row (`ProviderPreset.speech`) picks the wire.
3
+ import { PROVIDER_PRESETS, SPEECH_PRESET_IDS, } from "../presets.js";
4
+ import { createGeminiSpeechProvider } from "./gemini-speech.js";
5
+ import { createOpenAISpeechProvider } from "./openai-speech.js";
6
+ /**
7
+ * Build a speech provider for a preset that can speak. A preset without a
8
+ * `speech` row throws, naming the ones that do (`SPEECH_PRESET_IDS`).
9
+ *
10
+ * ```ts
11
+ * const speech = createSpeechProvider("google", { apiKey });
12
+ * const { bytes, mimeType } = await speech.synthesize({ text: "Click Settings." });
13
+ * ```
14
+ */
15
+ export function createSpeechProvider(id, config) {
16
+ const preset = PROVIDER_PRESETS[id];
17
+ const spec = preset.speech;
18
+ if (!spec) {
19
+ throw new Error(`[providerkit] Preset "${id}" has no speech endpoint. Presets that do: ${SPEECH_PRESET_IDS.join(", ")}.`);
20
+ }
21
+ // A default is a fact about the host that documented it.
22
+ const own = config.baseUrl === undefined;
23
+ const model = config.model ?? (own ? spec.defaultModel : undefined);
24
+ if (!model) {
25
+ throw new Error(`[providerkit] Speech on "${id}" has no default model${own ? "" : " for another host"}. Pass a model.`);
26
+ }
27
+ const shared = {
28
+ ...config,
29
+ id,
30
+ model,
31
+ baseUrl: config.baseUrl ?? spec.baseUrl ?? preset.baseUrl,
32
+ voice: config.voice ?? (own ? spec.defaultVoice : undefined),
33
+ format: config.format ?? (own ? spec.defaultFormat : undefined),
34
+ maxInputChars: config.maxInputChars ?? (own ? spec.maxInputChars : undefined),
35
+ };
36
+ switch (spec.shape) {
37
+ case "openai": {
38
+ if (config.maxOutputTokens !== undefined) {
39
+ throw new Error(`[providerkit] Speech on "${id}" uses the openai shape, which has no maxOutputTokens. Remove it.`);
40
+ }
41
+ return createOpenAISpeechProvider(shared);
42
+ }
43
+ case "gemini":
44
+ return createGeminiSpeechProvider(shared);
45
+ }
46
+ }
47
+ //# sourceMappingURL=speech-factory.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"speech-factory.js","sourceRoot":"","sources":["../../src/providers/speech-factory.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,4EAA4E;AAC5E,OAAO,EACL,gBAAgB,EAChB,iBAAiB,GAGlB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAwBhE;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,EAAoB,EACpB,MAA4B;IAE5B,MAAM,MAAM,GAAmB,gBAAgB,CAAC,EAAE,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACb,yBAAyB,EAAE,8CAA8C,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACzG,CAAC;IACJ,CAAC;IACD,yDAAyD;IACzD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC;IACzC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,4BAA4B,EAAE,yBAAyB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,iBAAiB,CACvG,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG;QACb,GAAG,MAAM;QACT,EAAE;QACF,KAAK;QACL,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO;QACzD,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5D,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/D,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;KAC9E,CAAC;IACF,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;gBACzC,MAAM,IAAI,KAAK,CACb,4BAA4B,EAAE,mEAAmE,CAClG,CAAC;YACJ,CAAC;YACD,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;QACD,KAAK,QAAQ;YACX,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}
@@ -0,0 +1,184 @@
1
+ import { ProviderError, type ErrorKind } from "./errors.ts";
2
+ import type { TokenUsage } from "./types.ts";
3
+ export declare const SPEECH_FORMATS: readonly ["wav", "pcm", "mp3", "opus", "aac", "flac"];
4
+ export type SpeechFormat = (typeof SPEECH_FORMATS)[number];
5
+ /** Which wire speaks. A third shape is one new file and one preset row. */
6
+ export type SpeechShape = "openai" | "gemini";
7
+ export interface SpeechRequest {
8
+ /** What to say. Trimmed first. Empty is refused before any request. */
9
+ text: string;
10
+ /** The voice as the endpoint spells it ("Kore", "alloy"). Absent: the provider's default. */
11
+ voice?: string;
12
+ /** Absent: the provider's default format, else "wav". */
13
+ format?: SpeechFormat;
14
+ /** The caller's Stop. Never retried and never turned into a timeout. */
15
+ signal?: AbortSignal;
16
+ }
17
+ /** Token counts the provider stated. `totalTokens` can exceed input plus output:
18
+ * the gap is what the provider counts and does not break out. */
19
+ export interface SpeechUsage extends TokenUsage {
20
+ totalTokens?: number;
21
+ }
22
+ export interface SpeechResult {
23
+ bytes: Uint8Array;
24
+ /** Read from the bytes, so it can differ from the format asked for. */
25
+ format: SpeechFormat;
26
+ /** The media type of `format`. */
27
+ mimeType: string;
28
+ /** Hz. Only when the bytes (a WAV header) or the request state it. */
29
+ sampleRate?: number;
30
+ /** Only when the bytes or the provider state it. */
31
+ channels?: number;
32
+ /** Exact, from a WAV header that checks out. Absent for every other format:
33
+ * measuring those takes a decoder, and a guess here would be wrong in the ledger. */
34
+ durationMs?: number;
35
+ /** Characters sent after trimming, for endpoints billed per character. */
36
+ characters: number;
37
+ /** Only when the provider reported it. Never estimated. */
38
+ usage?: SpeechUsage;
39
+ /** The model and voice that were asked for. */
40
+ model: string;
41
+ voice: string;
42
+ }
43
+ export interface SpeechProvider {
44
+ readonly id: string;
45
+ readonly model: string;
46
+ /**
47
+ * Exactly one HTTP request. No retry, no fallback, no second key. Throws a
48
+ * `ProviderError`; a reply that arrived but holds no usable audio throws a
49
+ * `SpeechError`, which keeps the usage the provider billed for it.
50
+ */
51
+ synthesize(request: SpeechRequest): Promise<SpeechResult>;
52
+ }
53
+ export interface SpeechLimits {
54
+ /** Longest `text`, in UTF-16 units (JavaScript's `.length`). Default 4,096.
55
+ * Over it is refused before any request. Never silently cut. */
56
+ maxInputChars?: number;
57
+ /** Largest audio accepted, in bytes. Default 32 MiB. */
58
+ maxAudioBytes?: number;
59
+ /** One deadline for the whole call, headers and body. Default 120,000. */
60
+ timeoutMs?: number;
61
+ }
62
+ export declare const DEFAULT_SPEECH_LIMITS: {
63
+ readonly maxInputChars: 4096;
64
+ readonly maxAudioBytes: number;
65
+ readonly timeoutMs: 120000;
66
+ };
67
+ type ProviderErrorOptions = NonNullable<ConstructorParameters<typeof ProviderError>[3]>;
68
+ /**
69
+ * A reply that arrived but holds no usable audio, or a failure the provider
70
+ * reported inside a 200. Carries the usage the provider stated for it, because it
71
+ * billed that: a caller that drops this loses the only record of the charge.
72
+ * Plain `ProviderError`s carry no usage.
73
+ */
74
+ export declare class SpeechError extends ProviderError {
75
+ readonly usage?: SpeechUsage;
76
+ constructor(provider: string, kind: ErrorKind, message: string, opts?: ProviderErrorOptions & {
77
+ usage?: SpeechUsage;
78
+ });
79
+ }
80
+ /** @internal Positive integers or a RangeError, at build time, never mid-call. */
81
+ export declare function resolveLimits(config: SpeechLimits): Required<SpeechLimits>;
82
+ /**
83
+ * @internal Trim, bound and fill in defaults. Throws BEFORE any request, and never
84
+ * puts the text or the key in the message: they are the caller's, and may be private.
85
+ */
86
+ export declare function prepareSpeech(provider: string, request: SpeechRequest, defaults: {
87
+ /** Checked, never echoed. A key with a line break, a non-Latin-1 character or a zero-width
88
+ * one pasted in makes the runtime reject the header and quote the value in its error. */
89
+ apiKey: string;
90
+ voice?: string;
91
+ format?: SpeechFormat;
92
+ maxInputChars: number;
93
+ /** What this wire can make. */
94
+ formats: readonly SpeechFormat[];
95
+ }): {
96
+ text: string;
97
+ voice: string;
98
+ format: SpeechFormat;
99
+ };
100
+ /**
101
+ * @internal The "could the vendor already have billed this?" rule, applied in one
102
+ * place so a new failure path cannot forget it.
103
+ *
104
+ * - The caller's Stop comes back untouched.
105
+ * - A timeout, a dead socket, a 5xx or anything unclassified may have landed after
106
+ * the vendor started work, so it is marked `shouldRetry: false`, and a vendor's
107
+ * `x-should-retry: true` does not undo that: the header says the vendor thinks a
108
+ * resend is fine, not that the first call was not billed.
109
+ * - Every other kind keeps what it came with. A 429 means the vendor refused before
110
+ * doing any work, so sending it again is safe, and `Retry-After` is honoured by
111
+ * the caller's own retry. `x-should-retry` is believed there, in either direction.
112
+ */
113
+ export declare function noReplay(provider: string, error: unknown, signal?: AbortSignal): unknown;
114
+ /**
115
+ * @internal The one place a call runs: under one deadline, once, and with the
116
+ * no-replay rule applied to whatever it throws. Both wires go through here.
117
+ */
118
+ export declare function synthesizeOnce<T>(provider: string, timeoutMs: number, request: SpeechRequest, call: (signal: AbortSignal) => Promise<T>): Promise<T>;
119
+ /** @internal A reply that arrived but cannot be used. Never retried: it was billed. */
120
+ export declare function unusable(provider: string, kind: ErrorKind, code: string, message: string, usage?: SpeechUsage): SpeechError;
121
+ /**
122
+ * @internal A failure the provider reported inside a 200 body (a gateway that
123
+ * answers 200 with a JSON error, an Interactions reply that says it failed). It is
124
+ * classified like any other failure, with the same words-over-status rules, and
125
+ * then the provider's words are dropped: they can echo the text that was sent.
126
+ */
127
+ export declare function inBandFailure(provider: string, envelope: unknown, usage?: SpeechUsage): SpeechError;
128
+ /** @internal */
129
+ export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
130
+ /**
131
+ * @internal Strict base64 to bytes: the length is a multiple of 4, the alphabet is
132
+ * the standard one, padding sits only at the end. `atob` alone is too forgiving:
133
+ * it drops whitespace and accepts missing padding. `undefined` on anything else.
134
+ */
135
+ export declare function decodeBase64(data: string): Uint8Array | undefined;
136
+ /** A format with a signature in its first bytes. Raw PCM has none. */
137
+ type ContainerFormat = Exclude<SpeechFormat, "pcm">;
138
+ /**
139
+ * @internal Which container the first bytes say this is, or `undefined`. Raw PCM
140
+ * has no signature, so it is never returned here. ADTS AAC and mp3 share a sync
141
+ * pattern and are told apart by their layer field.
142
+ */
143
+ export declare function sniffFormat(bytes: Uint8Array): ContainerFormat | undefined;
144
+ export interface WavInfo {
145
+ sampleRate: number;
146
+ channels: number;
147
+ bitsPerSample: number;
148
+ /** Samples per channel. */
149
+ frames: number;
150
+ durationMs: number;
151
+ }
152
+ /**
153
+ * Read a WAV file's own numbers, strictly. PCM only (format tag 1). The RIFF size
154
+ * is exact, every chunk sits inside the file, there is one `fmt ` before one
155
+ * non-empty `data` that holds whole frames, and nothing trails. Extra chunks such
156
+ * as `LIST` are skipped, and odd-sized chunks carry their pad byte. `undefined`
157
+ * on anything else. It reports what the bytes say; whether 24 kHz mono is
158
+ * acceptable is the caller's policy.
159
+ */
160
+ export declare function readWav(bytes: Uint8Array): WavInfo | undefined;
161
+ /** @internal Everything a result needs besides the audio itself. */
162
+ export interface AudioExtras {
163
+ model: string;
164
+ voice: string;
165
+ characters: number;
166
+ usage?: SpeechUsage;
167
+ /** What the request or the provider stated, for raw PCM only. */
168
+ sampleRate?: number;
169
+ channels?: number;
170
+ }
171
+ /**
172
+ * @internal Bytes in, `SpeechResult` out. An empty body is `empty_audio`. A
173
+ * recognised container is accepted whatever was asked for, and `format` says what
174
+ * it really is. Raw PCM is the one case with no signature to read, so it is
175
+ * accepted only when PCM was asked for and the length is whole samples. Anything
176
+ * else is `bad_audio`.
177
+ *
178
+ * A WAV is labelled by its signature. Its numbers (rate, channels, duration) are
179
+ * filled in only when the header checks out, so a server whose header lies still
180
+ * gets its audio through, without a duration anyone could take as measured.
181
+ */
182
+ export declare function describeAudio(provider: string, bytes: Uint8Array, wanted: SpeechFormat, extras: AudioExtras): SpeechResult;
183
+ export {};
184
+ //# sourceMappingURL=speech-core.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"speech-core.d.ts","sourceRoot":"","sources":["../src/speech-core.ts"],"names":[],"mappings":"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"}