@qvac/sdk 0.17.0 → 0.18.0

package/dist/schemas/audio-gen.d.ts

@@ -1,4 +1,26 @@
 import { z } from 'zod';
+/** Sample rate the ACE-Step engine expects for reference and source audio. */
+export declare const AUDIOGEN_INPUT_SAMPLE_RATE = 48000;
+/** Channel count (interleaved stereo) the ACE-Step engine expects for input audio. */
+export declare const AUDIOGEN_INPUT_CHANNELS = 2;
+/**
+ * Longest reference/source clip the SDK accepts (10 minutes). Bounds the PCM
+ * the server materializes per input — a 48 kHz stereo Float32 clip weighs
+ * 384 KB per second — so a request cannot exhaust the inference process.
+ */
+export declare const AUDIOGEN_INPUT_MAX_SECONDS = 600;
+/**
+ * ACE-Step task discriminators reachable through the SDK. `text2music` is the
+ * default caption-driven generation; `cover-nofsq` re-renders `sourceAudio`
+ * with a new caption while keeping its structure. The engine also reserves an
+ * FSQ-roundtrip `cover` task that is not implemented yet, so it is not offered
+ * here.
+ */
+export declare const AUDIOGEN_TASK_TYPES: readonly ["text2music", "cover-nofsq"];
+export declare const audioGenTaskTypeSchema: z.ZodEnum<{
+    text2music: "text2music";
+    "cover-nofsq": "cover-nofsq";
+}>;
 export declare const audioGenRuntimeConfigSchema: z.ZodObject<{
     useGPU: z.ZodOptional<z.ZodBoolean>;
     inferenceSteps: z.ZodOptional<z.ZodNumber>;
@@ -171,7 +193,44 @@ export declare const audioGenConfigSchema: z.ZodObject<{
         }>, z.ZodLiteral<"vad">]>>;
     }, z.core.$strip>]>;
 }, z.core.$strict>;
+/**
+ * Wire form of a reference/source audio input. `filePath` inputs are decoded
+ * server-side (any format the SDK's audio decoder supports, plus raw PCM);
+ * `base64` inputs must already be interleaved stereo 48 kHz Float32 LE PCM.
+ */
+export declare const audioGenAudioInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"base64">;
+    value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"filePath">;
+    value: z.ZodString;
+}, z.core.$strip>], "type">;
+/**
+ * Client form of a reference/source audio input: a file path, or raw
+ * interleaved stereo 48 kHz Float32 LE PCM bytes. Normalized to the wire form.
+ */
+export declare const audioGenClientAudioInputSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>, z.ZodTransform<{
+    type: "base64";
+    value: string;
+} | {
+    type: "filePath";
+    value: string;
+}, string | Uint8Array<ArrayBuffer>>>;
 export declare const audioGenClientParamsSchema: z.ZodObject<{
+    referenceAudio: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>, z.ZodTransform<{
+        type: "base64";
+        value: string;
+    } | {
+        type: "filePath";
+        value: string;
+    }, string | Uint8Array<ArrayBuffer>>>>;
+    sourceAudio: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>, z.ZodTransform<{
+        type: "base64";
+        value: string;
+    } | {
+        type: "filePath";
+        value: string;
+    }, string | Uint8Array<ArrayBuffer>>>>;
     modelId: z.ZodString;
     caption: z.ZodString;
     lyrics: z.ZodOptional<z.ZodString>;
@@ -181,10 +240,38 @@ export declare const audioGenClientParamsSchema: z.ZodObject<{
     keyscale: z.ZodOptional<z.ZodString>;
     timesignature: z.ZodOptional<z.ZodString>;
     duration: z.ZodOptional<z.ZodNumber>;
+    lmTemperature: z.ZodOptional<z.ZodNumber>;
+    lmTopP: z.ZodOptional<z.ZodNumber>;
+    lmTopK: z.ZodOptional<z.ZodNumber>;
+    lmCfgScale: z.ZodOptional<z.ZodNumber>;
+    lmPhase1: z.ZodOptional<z.ZodBoolean>;
+    dcwEnabled: z.ZodOptional<z.ZodBoolean>;
+    dcwScaler: z.ZodOptional<z.ZodNumber>;
+    dcwHighScaler: z.ZodOptional<z.ZodNumber>;
+    taskType: z.ZodOptional<z.ZodEnum<{
+        text2music: "text2music";
+        "cover-nofsq": "cover-nofsq";
+    }>>;
+    audioCoverStrength: z.ZodOptional<z.ZodNumber>;
+    coverNoiseStrength: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export declare const audioGenStreamRequestSchema: z.ZodObject<{
     type: z.ZodLiteral<"audioGenStream">;
     requestId: z.ZodOptional<z.ZodString>;
+    referenceAudio: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"base64">;
+        value: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"filePath">;
+        value: z.ZodString;
+    }, z.core.$strip>], "type">>;
+    sourceAudio: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"base64">;
+        value: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"filePath">;
+        value: z.ZodString;
+    }, z.core.$strip>], "type">>;
     modelId: z.ZodString;
     caption: z.ZodString;
     lyrics: z.ZodOptional<z.ZodString>;
@@ -194,6 +281,20 @@ export declare const audioGenStreamRequestSchema: z.ZodObject<{
     keyscale: z.ZodOptional<z.ZodString>;
     timesignature: z.ZodOptional<z.ZodString>;
     duration: z.ZodOptional<z.ZodNumber>;
+    lmTemperature: z.ZodOptional<z.ZodNumber>;
+    lmTopP: z.ZodOptional<z.ZodNumber>;
+    lmTopK: z.ZodOptional<z.ZodNumber>;
+    lmCfgScale: z.ZodOptional<z.ZodNumber>;
+    lmPhase1: z.ZodOptional<z.ZodBoolean>;
+    dcwEnabled: z.ZodOptional<z.ZodBoolean>;
+    dcwScaler: z.ZodOptional<z.ZodNumber>;
+    dcwHighScaler: z.ZodOptional<z.ZodNumber>;
+    taskType: z.ZodOptional<z.ZodEnum<{
+        text2music: "text2music";
+        "cover-nofsq": "cover-nofsq";
+    }>>;
+    audioCoverStrength: z.ZodOptional<z.ZodNumber>;
+    coverNoiseStrength: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export declare const audioGenProgressSchema: z.ZodObject<{
     stage: z.ZodString;
@@ -231,6 +332,8 @@ export declare const audioGenStreamResponseSchema: z.ZodObject<{
         backendId: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strict>;
+export type AudioGenTaskType = z.infer<typeof audioGenTaskTypeSchema>;
+export type AudioGenAudioInput = z.infer<typeof audioGenAudioInputSchema>;
 export type AudioGenRuntimeConfig = z.infer<typeof audioGenRuntimeConfigSchema>;
 export type AudioGenConfig = z.infer<typeof audioGenConfigSchema>;
 export type AudioGenClientParams = z.input<typeof audioGenClientParamsSchema>;

package/dist/schemas/audio-gen.js

@@ -1,6 +1,27 @@
 import { z } from 'zod';
 import { modelSrcInputSchema } from '../schemas/model-src-utils.js';
+import { audioInputSchema } from '../schemas/transcription.js';
+import { encodeBase64 } from '../utils/encoding.js';
 const base64Schema = z.string().min(1);
+/** Sample rate the ACE-Step engine expects for reference and source audio. */
+export const AUDIOGEN_INPUT_SAMPLE_RATE = 48000;
+/** Channel count (interleaved stereo) the ACE-Step engine expects for input audio. */
+export const AUDIOGEN_INPUT_CHANNELS = 2;
+/**
+ * Longest reference/source clip the SDK accepts (10 minutes). Bounds the PCM
+ * the server materializes per input — a 48 kHz stereo Float32 clip weighs
+ * 384 KB per second — so a request cannot exhaust the inference process.
+ */
+export const AUDIOGEN_INPUT_MAX_SECONDS = 600;
+/**
+ * ACE-Step task discriminators reachable through the SDK. `text2music` is the
+ * default caption-driven generation; `cover-nofsq` re-renders `sourceAudio`
+ * with a new caption while keeping its structure. The engine also reserves an
+ * FSQ-roundtrip `cover` task that is not implemented yet, so it is not offered
+ * here.
+ */
+export const AUDIOGEN_TASK_TYPES = ['text2music', 'cover-nofsq'];
+export const audioGenTaskTypeSchema = z.enum(AUDIOGEN_TASK_TYPES);
 export const audioGenRuntimeConfigSchema = z
     .object({
     useGPU: z.boolean().optional(),
@@ -19,7 +40,31 @@ export const audioGenConfigSchema = audioGenRuntimeConfigSchema
     vaeModelSrc: modelSrcInputSchema
 })
     .strict();
-const audioGenParamsShape = {
+const unitIntervalSchema = z.number().min(0).max(1);
+/**
+ * Wire form of a reference/source audio input. `filePath` inputs are decoded
+ * server-side (any format the SDK's audio decoder supports, plus raw PCM);
+ * `base64` inputs must already be interleaved stereo 48 kHz Float32 LE PCM.
+ */
+export const audioGenAudioInputSchema = audioInputSchema;
+/**
+ * Client form of a reference/source audio input: a file path, or raw
+ * interleaved stereo 48 kHz Float32 LE PCM bytes. Normalized to the wire form.
+ */
+export const audioGenClientAudioInputSchema = z
+    .union([z.string().min(1), z.instanceof(Uint8Array)])
+    .transform((value) => {
+    if (typeof value === 'string')
+        return { type: 'filePath', value };
+    return { type: 'base64', value: bytesToBase64(value) };
+});
+function bytesToBase64(bytes) {
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(bytes)) {
+        return bytes.toString('base64');
+    }
+    return encodeBase64(bytes);
+}
+const audioGenGenerationShape = {
     modelId: z.string().min(1),
     caption: z.string().trim().min(1, 'caption must not be empty or whitespace-only'),
     lyrics: z.string().optional(),
@@ -32,16 +77,102 @@ const audioGenParamsShape = {
         .number()
         .positive()
         .optional()
-        .describe('Approximate requested duration in seconds. ACE-Step rounds to its latent frame grid; use output frames or stats.audioDurationMs as authoritative.')
+        .describe('Approximate requested duration in seconds. ACE-Step rounds to its latent frame grid; use output frames or stats.audioDurationMs as authoritative.'),
+    lmTemperature: z
+        .number()
+        .nonnegative()
+        .optional()
+        .describe('LM sampling temperature (ACE-Step default: 0.85).'),
+    lmTopP: unitIntervalSchema
+        .optional()
+        .describe('LM nucleus-sampling probability (ACE-Step default: 0.9).'),
+    lmTopK: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('LM top-k cutoff; 0 disables top-k filtering.'),
+    lmCfgScale: z
+        .number()
+        .nonnegative()
+        .optional()
+        .describe('Classifier-free guidance scale used by the LM.'),
+    lmPhase1: z
+        .boolean()
+        .optional()
+        .describe('Allow the LM to infer missing metadata before semantic-code generation.'),
+    dcwEnabled: z
+        .boolean()
+        .optional()
+        .describe('Apply the official ACE-Step Haar DCW correction during DiT sampling (default: true).'),
+    dcwScaler: z
+        .number()
+        .nonnegative()
+        .optional()
+        .describe('DCW low-frequency correction strength (official default: 0.05).'),
+    dcwHighScaler: z
+        .number()
+        .nonnegative()
+        .optional()
+        .describe('DCW high-frequency correction strength (official default: 0.02).'),
+    taskType: audioGenTaskTypeSchema
+        .optional()
+        .describe('Generation task: text2music (default) or cover-nofsq (requires sourceAudio).'),
+    audioCoverStrength: unitIntervalSchema
+        .optional()
+        .describe('Fraction of DiT steps that keep the source context (0..1, default 1). cover-nofsq currently requires 1.'),
+    coverNoiseStrength: unitIntervalSchema
+        .optional()
+        .describe('Blend of the initial DiT noise toward the clean source latent (0..1). 0 = pure noise, 1 ≈ source latent. Default 0.')
+};
+const audioGenParamsShape = {
+    ...audioGenGenerationShape,
+    referenceAudio: audioGenAudioInputSchema
+        .optional()
+        .describe('Optional timbre reference audio; omit to keep the engine default.'),
+    sourceAudio: audioGenAudioInputSchema
+        .optional()
+        .describe('Source audio to re-render; required for cover tasks.')
 };
-export const audioGenClientParamsSchema = z.object(audioGenParamsShape).strict();
+/**
+ * Cross-field rules for cover tasks: `sourceAudio` is mandatory, and the engine
+ * currently only implements full source context, so an explicit
+ * `audioCoverStrength` must be `1` until context switching lands upstream.
+ */
+function validateCoverTask(value, ctx) {
+    if (value.taskType !== 'cover-nofsq')
+        return;
+    if (value.sourceAudio === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['sourceAudio'],
+            message: "taskType 'cover-nofsq' requires sourceAudio"
+        });
+    }
+    if (value.audioCoverStrength !== undefined && value.audioCoverStrength !== 1) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['audioCoverStrength'],
+            message: "taskType 'cover-nofsq' currently requires audioCoverStrength 1"
+        });
+    }
+}
+export const audioGenClientParamsSchema = z
+    .object({
+    ...audioGenGenerationShape,
+    referenceAudio: audioGenClientAudioInputSchema.optional(),
+    sourceAudio: audioGenClientAudioInputSchema.optional()
+})
+    .strict()
+    .superRefine(validateCoverTask);
 export const audioGenStreamRequestSchema = z
     .object({
     ...audioGenParamsShape,
     type: z.literal('audioGenStream'),
     requestId: z.string().min(1).optional()
 })
-    .strict();
+    .strict()
+    .superRefine(validateCoverTask);
 export const audioGenProgressSchema = z.object({
     stage: z.string(),
     step: z.number().int().nonnegative(),