kugelaudio 0.7.0 → 0.9.0

package/dist/index.d.mts

@@ -34,6 +34,7 @@ interface Voice {
     category?: VoiceCategory;
     sex?: VoiceSex;
     age?: VoiceAge;
+    quality?: string;
     supportedLanguages: string[];
     sampleText?: string;
     avatarUrl?: string;
@@ -221,7 +222,7 @@ interface GenerateOptions {
     modelId?: string;
     /** Voice ID to use */
     voiceId?: number;
-    /** CFG scale for generation (default: 2.0) */
+    /** Classifier-free guidance scale. Clamped to [1.2, 2.5] (default: 2.0). */
     cfgScale?: number;
     /**
      * Sampling variance. Range [0.0, 1.0]. 0 = most stable (near-greedy),
@@ -235,6 +236,12 @@ interface GenerateOptions {
     maxNewTokens?: number;
     /** Output sample rate (default: 24000) */
     sampleRate?: number;
+    /**
+     * Combined codec+rate token, e.g. 'ulaw_8000' / 'alaw_8000' / 'pcm_8000'.
+     * Opt-in; when set it is authoritative and must not contradict sampleRate.
+     * Absent ⇒ legacy PCM16 at sampleRate.
+     */
+    outputFormat?: string;
     /**
      * Enable text normalization (converts numbers, dates, etc. to spoken words).
      * When true, text will be normalized before TTS generation.
@@ -263,8 +270,9 @@ interface GenerateOptions {
     /**
      * Playback speed multiplier (0.8 = slower, 1.0 = normal, 1.2 = faster).
      *
-     * Uses pitch-preserving time-stretching (WSOLA). Inline `<prosody rate="...">` tags
-     * can also be used for per-segment speed control.
+     * Uses pitch-preserving time-stretching (WSOLA); applies to the whole
+     * request. Wrap text in `<prosody rate="slow|medium|fast|0.8-1.2">` to
+     * override the rate for a span (the span rate wins inside the span).
      * Range: [0.8, 1.2]. Default: 1.0.
      */
     speed?: number;
@@ -275,6 +283,14 @@ interface GenerateOptions {
      * server treats the value as trusted once received.
      */
     projectId?: number;
+    /**
+     * Per-request dictionary selection. Omit for the default behavior (all
+     * active dictionaries of the project apply, filtered by language). An
+     * empty array disables dictionaries for this request. A list of
+     * dictionary IDs applies exactly those dictionaries — including
+     * inactive ones — bypassing the language filter.
+     */
+    dictionaryIds?: number[];
 }
 /**
  * Streaming session configuration for `/ws/tts/stream`.
@@ -298,7 +314,7 @@ interface StreamConfig {
     voiceId?: number;
     /** Model ID. Default: 'kugel-3'. Legacy ids still accepted; they alias to kugel-3 server-side. */
     modelId?: string;
-    /** CFG scale for generation */
+    /** Classifier-free guidance scale. Clamped to [1.2, 2.5] (default: 2.0). */
     cfgScale?: number;
     /**
      * Sampling variance. Range [0.0, 1.0]. 0 = most stable, 1 = most variance.
@@ -309,6 +325,8 @@ interface StreamConfig {
     maxNewTokens?: number;
     /** Output sample rate */
     sampleRate?: number;
+    /** Combined codec+rate token (e.g. 'ulaw_8000'); opt-in, set-once per session. */
+    outputFormat?: string;
     /** Auto-flush timeout in milliseconds */
     flushTimeoutMs?: number;
     /** Maximum buffer length */
@@ -353,11 +371,55 @@ interface StreamConfig {
     /**
      * Playback speed multiplier (0.8 = slower, 1.0 = normal, 1.2 = faster).
      *
-     * Uses pitch-preserving time-stretching (WSOLA). Inline `<prosody rate="...">` tags
-     * can also be used for per-segment speed control.
+     * Uses pitch-preserving time-stretching (WSOLA); applies to the whole
+     * request. Wrap text in `<prosody rate="slow|medium|fast|0.8-1.2">` to
+     * override the rate for a span (the span rate wins inside the span).
      * Range: [0.8, 1.2]. Default: 1.0.
      */
     speed?: number;
+    /**
+     * Per-request dictionary selection. Omit for the default behavior (all
+     * active dictionaries of the project apply, filtered by language). An
+     * empty array disables dictionaries for this request. A list of
+     * dictionary IDs applies exactly those dictionaries — including
+     * inactive ones — bypassing the language filter.
+     */
+    dictionaryIds?: number[];
+}
+/**
+ * Generation parameters changeable mid-connection via
+ * {@link StreamingSession.updateSettings} / {@link MultiContextSession.updateSettings}
+ * (KUG-1166). Every field is optional; an update changes only the fields it
+ * carries. Identity / audio-format fields (`voiceId`, `modelId`, `sampleRate`,
+ * `outputFormat`, `dictionaryIds`) are NOT here — they are fixed for the
+ * connection's lifetime and the server rejects them in an update.
+ */
+interface SettingsUpdate {
+    /** Classifier-free guidance scale (0.0–10.0). */
+    cfgScale?: number;
+    /** Sampling variance (0.0–1.0). */
+    temperature?: number;
+    /** Playback speed multiplier (0.8–1.2). */
+    speed?: number;
+    /** Maximum tokens per generation (1–8192). */
+    maxNewTokens?: number;
+    /** Language code for normalization (e.g. `'de'`). */
+    language?: string;
+    /** Enable text normalization. */
+    normalize?: boolean;
+}
+/**
+ * The generation parameters in effect after an
+ * {@link StreamingSession.updateSettings} call — the server's echo. Fields the
+ * session never set come back `null` (e.g. `temperature`, `language`).
+ */
+interface EffectiveSettings {
+    cfgScale?: number;
+    temperature?: number | null;
+    speed?: number;
+    maxNewTokens?: number;
+    language?: string | null;
+    normalize?: boolean;
 }
 /**
  * Event callbacks for a streaming session (`/ws/tts/stream`).
@@ -374,9 +436,18 @@ interface StreamingSessionCallbacks {
      * Carries the segment index, total audio duration, and generation time.
      */
     onChunkComplete?: (chunkId: number, audioSeconds: number, genMs: number) => void;
+    /**
+     * Called when the server marks the end of a turn's audio
+     * (`{"final": true, ...}` — sent after the last audio frame of every
+     * gracefully completed turn, right before `session_closed`). The
+     * ElevenLabs `isFinal` equivalent: once this fires, no further audio
+     * for the turn will arrive. Not fired on a barge-in cancel — that
+     * path fires {@link onInterrupted} instead.
+     */
+    onFinal?: (totalAudioSeconds: number, totalTextChunks: number, totalAudioChunks: number) => void;
     /**
      * Called when the session is fully closed (after `session.close()`).
-     * Equivalent to `onFinal` on the one-shot endpoint.
+     * Fires right after {@link onFinal} and additionally carries usage.
      */
     onSessionClosed?: (totalAudioSeconds: number, totalTextChunks: number, totalAudioChunks: number) => void;
     /** Called when the server begins generating audio for a text segment. */
@@ -393,14 +464,45 @@ interface StreamingSessionCallbacks {
     /** Called on any error. */
     onError?: (error: Error) => void;
 }
+/**
+ * Per-session usage reported in the `session_closed` frame (KUG-1192).
+ *
+ * Lets you bill your own customers per conversation. `costCents` is the
+ * actual amount charged in **EUR cents**. When the charge could not be
+ * determined at session end (e.g. a transient billing error) `costCents` is
+ * `null` and `costAvailable` is `false` — never a misleading `0`.
+ * `audioSeconds` is always reported. On `/ws/tts/multi` usage is reported per
+ * context (per conversation) on each `context_closed` frame, not aggregated
+ * across contexts.
+ */
+interface SessionUsage {
+    /** Total audio generated this session, in seconds (the unit we bill on). */
+    audioSeconds: number;
+    /** Actual amount charged in EUR cents, or `null` if undetermined. */
+    costCents: number | null;
+    /** Currency of `costCents` (`"eur"`); present only when `costCents` is set. */
+    currency?: string;
+    /** Total input characters submitted this session, if reported. */
+    characters?: number;
+    /** Model that produced the audio, if reported. */
+    modelId?: string;
+    /** `true` when an authoritative charge was returned for this session. */
+    costAvailable: boolean;
+}
+/**
+ * Parse the raw `usage` object (or a legacy `session_closed` payload without
+ * one) into a typed {@link SessionUsage}. Returns `null` when no usage info
+ * is present.
+ */
+declare function parseSessionUsage(data: Record<string, unknown>): SessionUsage | null;
 /**
  * Audio chunk from streaming TTS.
  */
 interface AudioChunk {
     /** Raw PCM16 audio as base64 */
     audio: string;
-    /** Encoding format */
-    encoding: 'pcm_s16le';
+    /** Encoding format. 'mulaw' / 'alaw' only when output_format requested G.711. */
+    encoding: 'pcm_s16le' | 'mulaw' | 'alaw';
     /** Chunk index */
     index: number;
     /** Sample rate */
@@ -426,6 +528,12 @@ interface GenerationStats {
     rtf: number;
     /** Error message if any */
     error?: string;
+    /**
+     * Per-request usage (audio time + amount charged), for billing your own
+     * customers. Undefined when the server reports no usage. See
+     * {@link SessionUsage}.
+     */
+    usage?: SessionUsage;
 }
 /**
  * Complete audio response from TTS generation.
@@ -505,7 +613,9 @@ interface MultiContextConfig {
     defaultVoiceId?: number;
     /** Output sample rate (default: 24000) */
     sampleRate?: number;
-    /** CFG scale for generation (default: 2.0) */
+    /** Combined codec+rate token (e.g. 'ulaw_8000'); opt-in, set-once per context. */
+    outputFormat?: string;
+    /** Classifier-free guidance scale. Clamped to [1.2, 2.5] (default: 2.0). */
     cfgScale?: number;
     /**
      * Sampling variance. Range [0.0, 1.0]. 0 = most stable, 1 = most variance.
@@ -522,6 +632,14 @@ interface MultiContextConfig {
      * the language, which adds ~60-150ms to time-to-first-audio.
      */
     language?: string;
+    /**
+     * Per-request dictionary selection. Omit for the default behavior (all
+     * active dictionaries of the project apply, filtered by language). An
+     * empty array disables dictionaries for this request. A list of
+     * dictionary IDs applies exactly those dictionaries — including
+     * inactive ones — bypassing the language filter.
+     */
+    dictionaryIds?: number[];
     /** Seconds before context auto-closes (default: 20.0) */
     inactivityTimeout?: number;
 }
@@ -557,8 +675,20 @@ interface MultiContextCallbacks {
     onContextCreated?: (contextId: string) => void;
     /** Called when an audio chunk is received */
     onChunk?: (chunk: MultiContextAudioChunk) => void;
-    /** Called when a context is closed */
-    onContextClosed?: (contextId: string) => void;
+    /**
+     * Called when all audio admitted before a `{flush: true}` has been
+     * delivered for a context (`{"final": true, "context_id": ...}`), and
+     * once more before {@link onContextClosed} on a graceful close. The
+     * ElevenLabs multi-context `is_final` equivalent. Not fired on an
+     * immediate (barge-in) close.
+     */
+    onFinal?: (contextId: string) => void;
+    /**
+     * Called when a context is closed (terminal). `usage` carries this
+     * conversation's audio time + amount charged (undefined if not reported).
+     * See {@link SessionUsage}.
+     */
+    onContextClosed?: (contextId: string, usage?: SessionUsage) => void;
     /** Called when a context times out */
     onContextTimeout?: (contextId: string) => void;
     /** Called when session is closed */
@@ -912,13 +1042,25 @@ declare class MultiContextSession {
     private config;
     private callbacks;
     private contexts;
+    /** Contexts a create message has been sent for (not yet necessarily
+     *  confirmed by the server via context_created). */
+    private requestedContexts;
     private _sessionId;
+    private _contextUsage;
     private isStarted;
     constructor(client: KugelAudio, config?: MultiContextConfig);
     /**
      * Get the current session ID, or null if not connected.
      */
     get sessionId(): string | null;
+    /**
+     * Per-context usage (audio time + amount charged) for a closed context, or
+     * null if that context hasn't closed yet. Each context is its own
+     * conversation — use this to bill per conversation. See {@link SessionUsage}.
+     */
+    usageFor(contextId: string): SessionUsage | null;
+    /** Map of context_id → per-context usage for all closed contexts. */
+    get contextUsage(): Map<string, SessionUsage>;
     /**
      * Connect to the multi-context WebSocket endpoint.
      *
@@ -957,6 +1099,22 @@ declare class MultiContextSession {
      * Send keep-alive to reset a context's inactivity timeout.
      */
     keepAlive(contextId: string): void;
+    /**
+     * Change the session's generation parameters mid-connection (KUG-1166).
+     *
+     * Session-scoped (there is no `contextId`): the update applies to contexts
+     * started **after** it — a context already streaming keeps the settings it
+     * began with, since generation parameters are bound when a context's engine
+     * session opens. With the common one-context-per-turn pattern that means it
+     * takes effect on the next turn. Per-context `cfgScale` / `maxNewTokens`
+     * passed to {@link createContext} still win for that context.
+     *
+     * Resolves with the generation parameters now in effect (the server's echo).
+     *
+     * @throws {KugelAudioError} if no field is provided, the socket is not open,
+     *   or the server rejects the update.
+     */
+    updateSettings(settings: SettingsUpdate): Promise<EffectiveSettings>;
     /**
      * Close the session and all contexts.
      */
@@ -1005,7 +1163,14 @@ declare class StreamingSession {
     private callbacks;
     private client;
     private configSent;
+    private _lastUsage;
     constructor(client: KugelAudio, config: StreamConfig, callbacks: StreamingSessionCallbacks);
+    /**
+     * Per-session usage from the most recently closed session, or null before
+     * the first session closes. Use this to bill your own customers per
+     * conversation. See {@link SessionUsage}.
+     */
+    get lastUsage(): SessionUsage | null;
     /**
      * Open the WebSocket connection and authenticate.
      *
@@ -1079,6 +1244,28 @@ declare class StreamingSession {
      * to change voice, model, language, or other settings.
      */
     updateConfig(config: Partial<StreamConfig>): void;
+    /**
+     * Change generation parameters mid-connection without reconnecting (KUG-1166).
+     *
+     * Sends an `update_settings` message and resolves with the generation
+     * parameters now in effect (the server's echo). Only the six fields of
+     * {@link SettingsUpdate} are updatable; identity / audio-format fields
+     * (`voiceId`, `modelId`, `sampleRate`, `outputFormat`, `dictionaryIds`) are
+     * fixed for the connection — change those with {@link updateConfig} after
+     * {@link endSession} instead.
+     *
+     * The change applies to the **next turn**: a turn already streaming keeps the
+     * settings it started with, so call this between turns.
+     *
+     * @example
+     * ```typescript
+     * const effective = await session.updateSettings({ cfgScale: 1.5, speed: 1.1 });
+     * ```
+     *
+     * @throws {KugelAudioError} if no field is provided, the socket is not open,
+     *   or the server rejects the update (e.g. a value out of range).
+     */
+    updateSettings(settings: SettingsUpdate): Promise<EffectiveSettings>;
     /**
      * Close the session and the WebSocket connection.
      *
@@ -1334,9 +1521,6 @@ declare function classifyWsClose(code: number | undefined, reason?: string): Kug
  */
 declare function classifyWsHandshakeError(err: unknown): KugelAudioError | null;
 
-/**
- * Utility functions for KugelAudio SDK.
- */
 /**
  * Decode base64 string to ArrayBuffer.
  */
@@ -1354,4 +1538,4 @@ declare function createWavFile(audio: ArrayBuffer, sampleRate: number): ArrayBuf
  */
 declare function createWavBlob(audio: ArrayBuffer, sampleRate: number): Blob;
 
-export { type AudioChunk, type AudioResponse, AuthenticationError, type BulkReplaceResult, ConnectionError, type ContextVoiceSettings, type CreateDictionaryOptions, type CreateVoiceOptions, DictionariesResource, type Dictionary, DictionaryEntriesResource, type DictionaryEntry, type DictionaryEntryInput, type DictionaryEntryListResponse, type ErrorCode, ErrorCodes, type GenerateOptions, type GenerationStats, InsufficientCreditsError, KugelAudio, KugelAudioError, type KugelAudioErrorOptions, type KugelAudioOptions, type Model, type MultiContextAudioChunk, type MultiContextCallbacks, type MultiContextConfig, NotFoundError, RateLimitError, type Region, type StreamCallbacks, type StreamConfig, type StreamingSessionCallbacks, type UpdateDictionaryEntryOptions, type UpdateDictionaryOptions, type UpdateVoiceOptions, ValidationError, type Voice, type VoiceAge, type VoiceCategory, type VoiceDetail, type VoiceListResponse, type VoiceQuality, type VoiceReference, type VoiceSex, type WordTimestamp, WsCloseCodes, base64ToArrayBuffer, classifyHttpError, classifyWsClose, classifyWsFrame, classifyWsHandshakeError, createWavBlob, createWavFile, decodePCM16 };
+export { type AudioChunk, type AudioResponse, AuthenticationError, type BulkReplaceResult, ConnectionError, type ContextVoiceSettings, type CreateDictionaryOptions, type CreateVoiceOptions, DictionariesResource, type Dictionary, DictionaryEntriesResource, type DictionaryEntry, type DictionaryEntryInput, type DictionaryEntryListResponse, type EffectiveSettings, type ErrorCode, ErrorCodes, type GenerateOptions, type GenerationStats, InsufficientCreditsError, KugelAudio, KugelAudioError, type KugelAudioErrorOptions, type KugelAudioOptions, type Model, type MultiContextAudioChunk, type MultiContextCallbacks, type MultiContextConfig, NotFoundError, RateLimitError, type Region, type SessionUsage, type SettingsUpdate, type StreamCallbacks, type StreamConfig, type StreamingSessionCallbacks, type UpdateDictionaryEntryOptions, type UpdateDictionaryOptions, type UpdateVoiceOptions, ValidationError, type Voice, type VoiceAge, type VoiceCategory, type VoiceDetail, type VoiceListResponse, type VoiceQuality, type VoiceReference, type VoiceSex, type WordTimestamp, WsCloseCodes, base64ToArrayBuffer, classifyHttpError, classifyWsClose, classifyWsFrame, classifyWsHandshakeError, createWavBlob, createWavFile, decodePCM16, parseSessionUsage };