@qvac/sdk 0.19.1 → 0.20.1

package/dist/examples/tts/cosyvoice3.js

@@ -4,6 +4,8 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // synthesis (emotion, pace, or instruct). The LLM GGUF's registry companion
 // set downloads the flow/HiFT models, baked voice and tokenizer alongside it.
 // Native output is 24 kHz.
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const COSYVOICE3_SAMPLE_RATE = 24000;
 try {
     const modelId = await loadModel({
@@ -30,16 +32,14 @@ try {
         emotion: 'happy'
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? COSYVOICE3_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, COSYVOICE3_SAMPLE_RATE, 'cosyvoice3-output.wav');
+    createWav(audioBuffer, sampleRate, 'cosyvoice3-output.wav');
     console.log('▸ Audio saved to cosyvoice3-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, COSYVOICE3_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

package/dist/examples/tts/llm-to-tts-streaming.js

@@ -14,6 +14,9 @@
  */
 import { completion, loadModel, textToSpeechStream, unloadModel, LLAMA_3_2_1B_INST_Q4_0, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0 } from '@qvac/sdk';
 import { createWav, playPcmInt16Chunk } from './utils.js';
+// Only a fallback, for the case where no frame ever reports a rate: each
+// audio frame carries the rate the engine actually produced, and
+// `outputSampleRate` can move it off this default.
 const SUPERTONIC_SAMPLE_RATE = 44100;
 /**
  * Drop angle-bracket spans (e.g. `<think>…</think>`, `<|foo|>`) even when split across tokens,
@@ -107,16 +110,23 @@ try {
     });
     let phraseIndex = 0;
     const filterChunk = createAngleBracketAndStarFilter();
+    // Playback and the WAV header both follow what the engine reports rather
+    // than the engine's documented default, so a configured `outputSampleRate`
+    // cannot leave the audio playing back at the wrong speed.
+    let sampleRate = SUPERTONIC_SAMPLE_RATE;
     const drainPcm = (async () => {
         for await (const m of ttsSession) {
             if (m.buffer.length > 0) {
+                if (m.sampleRate !== undefined) {
+                    sampleRate = m.sampleRate;
+                }
                 appendPcmSamples(combinedPcm, m.buffer);
                 phraseIndex += 1;
                 const preview = typeof m.sentenceChunk === 'string'
                     ? m.sentenceChunk.replace(/\s+/g, ' ').trim().slice(0, 72)
                     : '';
                 console.log(`\n▸ [TTS phrase ${phraseIndex}] ${m.buffer.length} samples${preview ? ` — "${preview}${preview.length >= 72 ? '...' : ''}"` : ''}`);
-                await playPcmInt16Chunk(m.buffer, SUPERTONIC_SAMPLE_RATE);
+                await playPcmInt16Chunk(m.buffer, sampleRate);
             }
         }
     })();
@@ -135,7 +145,7 @@ try {
     }
     const outWav = 'llm-to-tts-streaming-output.wav';
     console.log(`\n▸ Writing ${combinedPcm.length} samples to ${outWav} (full utterance; phrases were already played above).`);
-    createWav(combinedPcm, SUPERTONIC_SAMPLE_RATE, outWav);
+    createWav(combinedPcm, sampleRate, outWav);
     await unloadModel({ modelId: llmModelId, clearStorage: false });
     await unloadModel({ modelId: ttsModelId, clearStorage: false });
     console.log('▸ Models unloaded.');

package/dist/examples/tts/parler.js

@@ -2,6 +2,8 @@ import { loadModel, textToSpeech, unloadModel, TTS_MINI_V1_EN_PARLER_TTS_Q8_0 }
 import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
 // Parler-TTS (GGML): description-conditioned speech with per-call voice controls.
 // Uses the registry-hosted Mini v1 Q8_0 model and its native 44.1 kHz output.
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const PARLER_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
@@ -29,16 +31,14 @@ try {
         emotion: 'happy'
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? PARLER_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, PARLER_SAMPLE_RATE, 'parler-output.wav');
+    createWav(audioBuffer, sampleRate, 'parler-output.wav');
     console.log('▸ Audio saved to parler-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, PARLER_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

package/dist/examples/tts/supertonic-enhanced.js

@@ -5,6 +5,7 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // Supplying the enhancer GGUF is what enables enhancement — there is no on/off
 // flag — and it forces the output to 48 kHz regardless of the engine's native
 // rate.
+// Only a fallback; the engine reports the rate it actually produced.
 const ENHANCED_SAMPLE_RATE = 48000;
 try {
     const modelId = await loadModel({
@@ -35,16 +36,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? ENHANCED_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, ENHANCED_SAMPLE_RATE, 'supertonic-enhanced-output.wav');
+    createWav(audioBuffer, sampleRate, 'supertonic-enhanced-output.wav');
     console.log('▸ Audio saved to supertonic-enhanced-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, ENHANCED_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

package/dist/examples/tts/supertonic-multilingual.js

@@ -1,6 +1,8 @@
 import { loadModel, textToSpeech, unloadModel, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0 } from '@qvac/sdk';
 import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
 // Supertonic 3 TTS (GGML): multilingual synthesis across 31 languages.
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const SUPERTONIC_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
@@ -29,16 +31,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? SUPERTONIC_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, SUPERTONIC_SAMPLE_RATE, 'supertonic-multilingual-output.wav');
+    createWav(audioBuffer, sampleRate, 'supertonic-multilingual-output.wav');
     console.log('▸ Audio saved to supertonic-multilingual-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, SUPERTONIC_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

package/dist/examples/tts/supertonic.js

@@ -2,6 +2,8 @@ import { loadModel, textToSpeech, unloadModel, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0
 import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
 // Supertonic 3 TTS (GGML): fast multilingual synthesis with baked-in voices.
 // Uses registry model constants — downloads automatically from QVAC Registry.
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const SUPERTONIC_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
@@ -30,16 +32,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? SUPERTONIC_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, SUPERTONIC_SAMPLE_RATE, 'supertonic-output.wav');
+    createWav(audioBuffer, sampleRate, 'supertonic-output.wav');
     console.log('▸ Audio saved to supertonic-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, SUPERTONIC_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

package/dist/scripts/contract/build-contract.d.ts

@@ -20,7 +20,7 @@ export declare function buildContract(): {
                 condition: string;
                 responseSchema: string;
             };
-            name: "audioGenStream" | "heartbeat" | "loadModel" | "downloadAsset" | "completionStream" | "completionOrchestrate" | "batchCompletionStream" | "unloadModel" | "transcribe" | "transcribeStream" | "bciTranscribe" | "bciTranscribeStream" | "loggingStream" | "embed" | "translate" | "textToSpeech" | "textToSpeechStream" | "cancel" | "finetune" | "rag" | "deleteCache" | "getModelInfo" | "getLoadedModelInfo" | "getSystemResources" | "assessModelFit" | "ocrStream" | "diffusionStream" | "videoStream" | "upscaleStream" | "worldSceneStream" | "worldStepStream" | "resume" | "pluginInvoke" | "pluginInvokeStream" | "modelRegistryList" | "modelRegistrySearch" | "modelRegistryGetModel" | "suspend" | "state" | "classify";
+            name: "audioGenStream" | "audioEditStream" | "audioUnderstand" | "heartbeat" | "loadModel" | "downloadAsset" | "completionStream" | "completionOrchestrate" | "batchCompletionStream" | "unloadModel" | "transcribe" | "transcribeStream" | "bciTranscribe" | "bciTranscribeStream" | "loggingStream" | "embed" | "translate" | "textToSpeech" | "textToSpeechStream" | "cancel" | "finetune" | "rag" | "vectorIndex" | "deleteCache" | "getModelInfo" | "getLoadedModelInfo" | "getSystemResources" | "assessModelFit" | "ocrStream" | "diffusionStream" | "videoStream" | "upscaleStream" | "worldSceneStream" | "worldStepStream" | "resume" | "pluginInvoke" | "pluginInvokeStream" | "modelRegistryList" | "modelRegistrySearch" | "modelRegistryGetModel" | "suspend" | "state" | "classify";
             callShape: "duplex" | "request-reply" | "server-stream";
             requestSchema: string;
             responseSchema: string;

package/dist/scripts/contract/constants-registry.d.ts

@@ -61,9 +61,24 @@ export declare const constantsRegistry: {
     readonly SupportedAudioFormat: z.ZodEnum<{
         [k: string]: string;
     }>;
+    readonly TtsEngine: z.ZodEnum<{
+        [k: string]: string;
+    }>;
     readonly TtsPace: z.ZodEnum<{
         [k: string]: string;
     }>;
+    readonly TtsParlerEmotion: z.ZodEnum<{
+        [k: string]: "command" | "anger" | "narration" | "conversation" | "disgust" | "fear" | "happy" | "neutral" | "proper noun" | "news" | "sad" | "surprise";
+    }>;
+    readonly TtsSentenceDelimiterPreset: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsChatterboxLanguage: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsSupertonicLanguage: z.ZodEnum<{
+        [k: string]: string;
+    }>;
     readonly TtsCosyvoice3Emotion: z.ZodEnum<{
         [k: string]: string;
     }>;
@@ -82,5 +97,21 @@ export declare const constantsRegistry: {
     readonly AudioGenTaskType: z.ZodEnum<{
         [k: string]: string;
     }>;
+    readonly AudioGenEditOperation: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly AudioGenRepaintMode: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly AudioGenTrack: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly VectorIndexStorage: z.ZodEnum<{
+        readonly F32: "f32";
+        readonly Q8: "q8";
+        readonly Q4: "q4";
+        readonly TURBOVEC_Q4: "turbovec-q4";
+        readonly TURBOVEC_Q2: "turbovec-q2";
+    }>;
 };
 //# sourceMappingURL=constants-registry.d.ts.map

package/dist/scripts/contract/constants-registry.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ModelType, VERBOSITY, SUPPORTED_AUDIO_FORMATS, AUDIOGEN_ENGINES, AUDIOGEN_TASK_TYPES, TTS_PACES, TTS_COSYVOICE3_EMOTIONS, TTS_COSYVOICE3_INSTRUCT_DIALECTS, TTS_COSYVOICE3_INSTRUCT_VOLUMES, TTS_COSYVOICE3_INSTRUCT_STYLES } from '@qvac/inference/surface';
+import { ModelType, VERBOSITY, SUPPORTED_AUDIO_FORMATS, AUDIOGEN_ENGINES, AUDIOGEN_TASK_TYPES, AUDIOGEN_EDIT_OPERATIONS, AUDIOGEN_REPAINT_MODES, AUDIOGEN_TRACKS, TTS_ENGINES, TTS_PACES, TTS_PARLER_EMOTIONS, TTS_SENTENCE_DELIMITER_PRESETS, TTS_CHATTERBOX_LANGUAGES, TTS_SUPERTONIC_LANGUAGES, TTS_COSYVOICE3_EMOTIONS, TTS_COSYVOICE3_INSTRUCT_DIALECTS, TTS_COSYVOICE3_INSTRUCT_VOLUMES, TTS_COSYVOICE3_INSTRUCT_STYLES, VectorIndexStorage } from '@qvac/inference/surface';
 import { PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_BCI, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, PLUGIN_AUDIOGEN, PLUGIN_VLA, PLUGIN_CLASSIFICATION } from '../../src/plugin-ids.js';
 // Uppercases each vocabulary value into an identifier-safe varname (e.g.
 // 'slow' -> 'SLOW', 'cover-nofsq' -> 'COVER_NOFSQ'), mirroring the
@@ -52,11 +52,22 @@ export const constantsRegistry = {
     // than a hand-written record, so the varnames can't drift from the one
     // source of truth every other consumer of SUPPORTED_AUDIO_FORMATS shares.
     SupportedAudioFormat: z.enum(Object.fromEntries(SUPPORTED_AUDIO_FORMATS.map((ext) => [ext.slice(1).toUpperCase(), ext]))),
+    TtsEngine: enumFromVocabulary(TTS_ENGINES),
     TtsPace: enumFromVocabulary(TTS_PACES),
+    // 'proper noun' carries a space; enumFromVocabulary only rewrites '-', so
+    // map it explicitly to keep the varname identifier-safe.
+    TtsParlerEmotion: z.enum(Object.fromEntries(TTS_PARLER_EMOTIONS.map((value) => [value.toUpperCase().replace(/[\s-]/g, '_'), value]))),
+    TtsSentenceDelimiterPreset: enumFromVocabulary(TTS_SENTENCE_DELIMITER_PRESETS),
+    TtsChatterboxLanguage: enumFromVocabulary(TTS_CHATTERBOX_LANGUAGES),
+    TtsSupertonicLanguage: enumFromVocabulary(TTS_SUPERTONIC_LANGUAGES),
     TtsCosyvoice3Emotion: enumFromVocabulary(TTS_COSYVOICE3_EMOTIONS),
     TtsCosyvoice3InstructDialect: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_DIALECTS),
     TtsCosyvoice3InstructVolume: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_VOLUMES),
     TtsCosyvoice3InstructStyle: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_STYLES),
     AudioGenEngine: enumFromVocabulary(AUDIOGEN_ENGINES),
-    AudioGenTaskType: enumFromVocabulary(AUDIOGEN_TASK_TYPES)
+    AudioGenTaskType: enumFromVocabulary(AUDIOGEN_TASK_TYPES),
+    AudioGenEditOperation: enumFromVocabulary(AUDIOGEN_EDIT_OPERATIONS),
+    AudioGenRepaintMode: enumFromVocabulary(AUDIOGEN_REPAINT_MODES),
+    AudioGenTrack: enumFromVocabulary(AUDIOGEN_TRACKS),
+    VectorIndexStorage: z.enum(VectorIndexStorage)
 };

package/dist/scripts/contract/method-shapes.d.ts

@@ -8,7 +8,9 @@
  */
 export declare const methodShapes: {
     readonly assessModelFit: "reply";
+    readonly audioEditStream: "stream";
     readonly audioGenStream: "stream";
+    readonly audioUnderstand: "stream";
     readonly batchCompletionStream: "stream";
     readonly bciTranscribe: "stream";
     readonly bciTranscribeStream: "duplex";
@@ -44,6 +46,7 @@ export declare const methodShapes: {
     readonly translate: "stream";
     readonly unloadModel: "reply";
     readonly upscaleStream: "stream";
+    readonly vectorIndex: "reply";
     readonly videoStream: "stream";
     readonly worldSceneStream: "stream";
     readonly worldStepStream: "stream";

package/dist/scripts/contract/method-shapes.js

@@ -8,7 +8,9 @@
  */
 export const methodShapes = {
     assessModelFit: 'reply',
+    audioEditStream: 'stream',
     audioGenStream: 'stream',
+    audioUnderstand: 'stream',
     batchCompletionStream: 'stream',
     bciTranscribe: 'stream',
     bciTranscribeStream: 'duplex',
@@ -44,6 +46,7 @@ export const methodShapes = {
     translate: 'stream',
     unloadModel: 'reply',
     upscaleStream: 'stream',
+    vectorIndex: 'reply',
     videoStream: 'stream',
     worldSceneStream: 'stream',
     worldStepStream: 'stream'

package/dist/src/client/api/assess-model-fit.d.ts

@@ -3,10 +3,15 @@ import { type AssessModelFitInput, type AssessModelFitResult } from '@qvac/infer
  * Assesses, before anything is downloaded, whether the given models are likely
  * to fit in this device's memory.
  *
- * Advisory only: it does not download weights, run a native fit probe, block
- * `loadModel`, reserve memory, or make a performance claim. `unknown` is a real
- * answer — it means the available evidence does not support a verdict either
- * way, and callers should treat it as "cannot say", not "no".
+ * Advisory only: it does not download weights, block `loadModel`, reserve
+ * memory, or make a performance claim. `unknown` is a real answer — it means
+ * the available evidence does not support a verdict either way, and callers
+ * should treat it as "cannot say", not "no".
+ *
+ * For a single candidate it fetches the registry's weightless description of
+ * the artifact — tens of KB, never the weights — and runs the engine's own
+ * fitter against it, reported as `native-fit` evidence. Where that is
+ * unavailable, and for a set of candidates, the calibrated estimate stands.
  *
  * @param input - Candidates with their intended workloads, the declared
  *   execution mode, and the headroom policy.

package/dist/src/client/api/assess-model-fit.js

@@ -5,10 +5,15 @@ import { InvalidResponseError } from '../../utils/errors-client.js';
  * Assesses, before anything is downloaded, whether the given models are likely
  * to fit in this device's memory.
  *
- * Advisory only: it does not download weights, run a native fit probe, block
- * `loadModel`, reserve memory, or make a performance claim. `unknown` is a real
- * answer — it means the available evidence does not support a verdict either
- * way, and callers should treat it as "cannot say", not "no".
+ * Advisory only: it does not download weights, block `loadModel`, reserve
+ * memory, or make a performance claim. `unknown` is a real answer — it means
+ * the available evidence does not support a verdict either way, and callers
+ * should treat it as "cannot say", not "no".
+ *
+ * For a single candidate it fetches the registry's weightless description of
+ * the artifact — tens of KB, never the weights — and runs the engine's own
+ * fitter against it, reported as `native-fit` evidence. Where that is
+ * unavailable, and for a set of candidates, the calibrated estimate stands.
  *
  * @param input - Candidates with their intended workloads, the declared
  *   execution mode, and the headroom policy.

package/dist/src/client/api/audio-edit.d.ts

@@ -0,0 +1,36 @@
+import type { AudioEditClientParams, AudioGenResult } from '@qvac/inference/surface';
+/**
+ * Edits a source recording with a loaded ACE-Step AudioGen model: an ordered
+ * pipeline of `flow-edit` and `repaint` operations, executed in array order.
+ *
+ * @param params - Loaded model ID, the source audio, the ordered `operations`, and an optional `seed`.
+ * @param params.sourceAudio - The recording to edit: a file path (decoded server-side) or raw
+ *   interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
+ * @param params.operations - `flow-edit` re-conditions the whole clip from a `from` prompt to a
+ *   `to` prompt over an optional `nMin`/`nMax` diffusion window (turbo DiT variants only);
+ *   `repaint` regenerates the `start`..`end` range (seconds) against a new `caption`, keeping the
+ *   rest of the clip. Operations may repeat or mix.
+ * @param params.seed - Seeds the first operation; each following operation uses `seed + index`.
+ * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise.
+ *
+ * @example
+ * ```typescript
+ * const run = audioEdit({
+ *   modelId,
+ *   sourceAudio: "/path/to/song.wav",
+ *   operations: [
+ *     {
+ *       type: "flow-edit",
+ *       from: { caption: "original pop song", lyrics: originalLyrics },
+ *       to: { caption: "guitar pop-rock", lyrics: newLyrics },
+ *     },
+ *     { type: "repaint", caption: "analog synth solo", start: 10, end: 20, mode: "balanced" },
+ *   ],
+ *   seed: 22883,
+ * });
+ * stopButton.onclick = () => cancel({ requestId: run.requestId });
+ * const { pcm, sampleRate, channels, bitsPerSample } = await run.audio;
+ * ```
+ */
+export declare function audioEdit(params: AudioEditClientParams): AudioGenResult;
+//# sourceMappingURL=audio-edit.d.ts.map

package/dist/src/client/api/audio-edit.js

@@ -0,0 +1,38 @@
+import { stream as streamRpc } from '../rpc/rpc-client.js';
+import { createAudioEditResult } from './audio-gen-result.js';
+/**
+ * Edits a source recording with a loaded ACE-Step AudioGen model: an ordered
+ * pipeline of `flow-edit` and `repaint` operations, executed in array order.
+ *
+ * @param params - Loaded model ID, the source audio, the ordered `operations`, and an optional `seed`.
+ * @param params.sourceAudio - The recording to edit: a file path (decoded server-side) or raw
+ *   interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
+ * @param params.operations - `flow-edit` re-conditions the whole clip from a `from` prompt to a
+ *   `to` prompt over an optional `nMin`/`nMax` diffusion window (turbo DiT variants only);
+ *   `repaint` regenerates the `start`..`end` range (seconds) against a new `caption`, keeping the
+ *   rest of the clip. Operations may repeat or mix.
+ * @param params.seed - Seeds the first operation; each following operation uses `seed + index`.
+ * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise.
+ *
+ * @example
+ * ```typescript
+ * const run = audioEdit({
+ *   modelId,
+ *   sourceAudio: "/path/to/song.wav",
+ *   operations: [
+ *     {
+ *       type: "flow-edit",
+ *       from: { caption: "original pop song", lyrics: originalLyrics },
+ *       to: { caption: "guitar pop-rock", lyrics: newLyrics },
+ *     },
+ *     { type: "repaint", caption: "analog synth solo", start: 10, end: 20, mode: "balanced" },
+ *   ],
+ *   seed: 22883,
+ * });
+ * stopButton.onclick = () => cancel({ requestId: run.requestId });
+ * const { pcm, sampleRate, channels, bitsPerSample } = await run.audio;
+ * ```
+ */
+export function audioEdit(params) {
+    return createAudioEditResult(params, streamRpc);
+}

package/dist/src/client/api/audio-gen-result.d.ts

@@ -1,4 +1,8 @@
-import { type AudioGenClientParams, type AudioGenResult, type AudioGenStreamRequest } from '@qvac/inference/surface';
+import { type AudioEditClientParams, type AudioEditStreamRequest, type AudioGenClientParams, type AudioGenResult, type AudioGenStreamRequest, type AudioUnderstandClientParams, type AudioUnderstandRequest, type AudioUnderstandResult } from '@qvac/inference/surface';
 export type AudioGenStreamFactory = (request: AudioGenStreamRequest) => AsyncGenerator<unknown>;
+export type AudioEditStreamFactory = (request: AudioEditStreamRequest) => AsyncGenerator<unknown>;
+export type AudioUnderstandStreamFactory = (request: AudioUnderstandRequest) => AsyncGenerator<unknown>;
 export declare function createAudioGenResult(params: AudioGenClientParams, streamFactory: AudioGenStreamFactory): AudioGenResult;
+export declare function createAudioEditResult(params: AudioEditClientParams, streamFactory: AudioEditStreamFactory): AudioGenResult;
+export declare function createAudioUnderstandResult(params: AudioUnderstandClientParams, streamFactory: AudioUnderstandStreamFactory): AudioUnderstandResult;
 //# sourceMappingURL=audio-gen-result.d.ts.map