@qvac/sdk 0.21.1 → 0.22.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 (167) hide show
  1. package/NOTICE +84 -55
  2. package/README.md +167 -24
  3. package/dist/examples/abot-world.js +1 -1
  4. package/dist/examples/advisory-model-fit.d.ts +0 -58
  5. package/dist/examples/advisory-model-fit.js +23 -150
  6. package/dist/examples/asr/moss-transcribe-filesystem.d.ts +2 -0
  7. package/dist/examples/asr/moss-transcribe-filesystem.js +84 -0
  8. package/dist/examples/asr/moss-transcribe-fit.d.ts +2 -0
  9. package/dist/examples/asr/moss-transcribe-fit.js +40 -0
  10. package/dist/examples/asr/nemotron-diarization-filesystem.d.ts +2 -0
  11. package/dist/examples/asr/nemotron-diarization-filesystem.js +64 -0
  12. package/dist/examples/asr/parakeet-ctc-filesystem.js +2 -2
  13. package/dist/examples/asr/parakeet-indic-conformer-filesystem.js +2 -2
  14. package/dist/examples/asr/parakeet-microphone-record.js +1 -1
  15. package/dist/examples/asr/parakeet-microphone-stream.js +1 -1
  16. package/dist/examples/asr/parakeet-nemotron-filesystem.js +3 -3
  17. package/dist/examples/asr/parakeet-sortformer-streaming.js +2 -2
  18. package/dist/examples/asr/parakeet-sortformer.js +1 -1
  19. package/dist/examples/asr/parakeet-tdt-filesystem-chunked.js +2 -2
  20. package/dist/examples/asr/parakeet-tdt-filesystem.js +2 -2
  21. package/dist/examples/asr/parakeet-unified-coreml.js +2 -2
  22. package/dist/examples/asr/parakeet-unified-filesystem.js +2 -2
  23. package/dist/examples/asr/whispercpp-filesystem-streaming.js +1 -1
  24. package/dist/examples/asr/whispercpp-filesystem.js +1 -1
  25. package/dist/examples/asr/whispercpp-microphone-record.js +1 -1
  26. package/dist/examples/asr/whispercpp-prompt.js +1 -1
  27. package/dist/examples/assess-model-fit.js +3 -6
  28. package/dist/examples/audiogen/edit-music.js +2 -2
  29. package/dist/examples/audiogen/generate-cover.js +2 -2
  30. package/dist/examples/audiogen/generate-music-minimax.js +1 -1
  31. package/dist/examples/audiogen/generate-music.js +1 -1
  32. package/dist/examples/audiogen/understand-music.js +2 -2
  33. package/dist/examples/batch-completion.d.ts +1 -1
  34. package/dist/examples/batch-completion.js +1 -1
  35. package/dist/examples/bci/bci-filesystem-streaming.js +2 -2
  36. package/dist/examples/bci/bci-filesystem.js +2 -2
  37. package/dist/examples/concurrent-completion-collision.js +1 -1
  38. package/dist/examples/config-reload.js +1 -1
  39. package/dist/examples/decisions.d.ts +2 -0
  40. package/dist/examples/decisions.js +38 -0
  41. package/dist/examples/diffusion-esrgan-upscale.js +1 -1
  42. package/dist/examples/diffusion-flux2-klein-img2img.js +1 -1
  43. package/dist/examples/diffusion-img2img.js +1 -1
  44. package/dist/examples/diffusion-img2vid-ltx.js +1 -1
  45. package/dist/examples/diffusion-img2vid-minimax-h3.d.ts +2 -0
  46. package/dist/examples/diffusion-img2vid-minimax-h3.js +72 -0
  47. package/dist/examples/diffusion-img2vid.js +1 -1
  48. package/dist/examples/llamacpp-filesystem.js +1 -1
  49. package/dist/examples/llamacpp-multi-gpu.js +2 -2
  50. package/dist/examples/llamacpp-structured-output.js +1 -1
  51. package/dist/examples/mcp-websearch.d.ts +2 -2
  52. package/dist/examples/mcp-websearch.js +3 -3
  53. package/dist/examples/model-fit-ui/server.d.ts +1 -1
  54. package/dist/examples/model-fit-ui/server.js +1 -1
  55. package/dist/examples/multi-job-completion.d.ts +1 -1
  56. package/dist/examples/multi-job-completion.js +1 -1
  57. package/dist/examples/ocr-fasttext.js +1 -1
  58. package/dist/examples/tools/llamacpp-tools-auto-dialect.js +1 -1
  59. package/dist/examples/tools/llamacpp-tools-gemma4.js +1 -1
  60. package/dist/examples/tools/llamacpp-tools-qwen35.js +1 -1
  61. package/dist/examples/tts/llm-to-tts-streaming.d.ts +2 -2
  62. package/dist/examples/tts/llm-to-tts-streaming.js +2 -2
  63. package/dist/examples/tts/moss-sound-effect-controls.d.ts +2 -0
  64. package/dist/examples/tts/moss-sound-effect-controls.js +88 -0
  65. package/dist/examples/tts/moss-sound-effect.d.ts +2 -0
  66. package/dist/examples/tts/moss-sound-effect.js +86 -0
  67. package/dist/examples/tts/moss-speech-audio.d.ts +2 -0
  68. package/dist/examples/tts/moss-speech-audio.js +159 -0
  69. package/dist/examples/tts/moss-speech.d.ts +2 -0
  70. package/dist/examples/tts/moss-speech.js +70 -0
  71. package/dist/examples/vla-groot.js +2 -2
  72. package/dist/examples/vla-pi05.js +2 -2
  73. package/dist/examples/vla-smolvla.js +2 -2
  74. package/dist/examples/voice-assistant/voice-assistant.js +1 -1
  75. package/dist/scripts/contract/build-contract.d.ts +3 -1
  76. package/dist/scripts/contract/build-contract.js +40 -2
  77. package/dist/scripts/contract/build-model-type-maps.d.ts +6 -1
  78. package/dist/scripts/contract/build-model-type-maps.js +3 -2
  79. package/dist/scripts/contract/constants-registry.d.ts +4 -0
  80. package/dist/scripts/contract/constants-registry.js +3 -1
  81. package/dist/scripts/contract/method-shapes.d.ts +1 -0
  82. package/dist/scripts/contract/method-shapes.js +1 -0
  83. package/dist/scripts/export-contract.js +20 -7
  84. package/dist/scripts/run-unit-tests.js +10 -5
  85. package/dist/src/client/api/assess-model-fit.d.ts +5 -5
  86. package/dist/src/client/api/assess-model-fit.js +5 -6
  87. package/dist/src/client/api/audio-edit.d.ts +14 -2
  88. package/dist/src/client/api/audio-edit.js +14 -2
  89. package/dist/src/client/api/audio-gen.d.ts +10 -2
  90. package/dist/src/client/api/audio-gen.js +10 -2
  91. package/dist/src/client/api/audio-understand.d.ts +1 -1
  92. package/dist/src/client/api/audio-understand.js +1 -1
  93. package/dist/src/client/api/batch-completion.js +1 -1
  94. package/dist/src/client/api/completion-stream.js +1 -1
  95. package/dist/src/client/api/decide.d.ts +31 -0
  96. package/dist/src/client/api/decide.js +29 -0
  97. package/dist/src/client/api/index.d.ts +1 -0
  98. package/dist/src/client/api/index.js +1 -0
  99. package/dist/src/client/api/load-model.d.ts +1 -0
  100. package/dist/src/client/api/text-to-speech.d.ts +1 -0
  101. package/dist/src/client/api/text-to-speech.js +15 -22
  102. package/dist/src/client/api/transcribe.js +5 -2
  103. package/dist/src/client/api/video-request.d.ts +5 -5
  104. package/dist/src/client/api/video.d.ts +23 -3
  105. package/dist/src/client/api/video.js +23 -3
  106. package/dist/src/commands/bundle/bare-pack.d.ts +8 -0
  107. package/dist/src/commands/bundle/bare-pack.js +28 -5
  108. package/dist/src/commands/bundle/constants.js +2 -0
  109. package/dist/src/commands/bundle/index.d.ts +7 -6
  110. package/dist/src/commands/bundle/index.js +126 -43
  111. package/dist/src/commands/bundle/manifest.d.ts +2 -0
  112. package/dist/src/commands/bundle/manifest.js +3 -2
  113. package/dist/src/commands/host-prebuilds/index.d.ts +15 -7
  114. package/dist/src/commands/host-prebuilds/index.js +35 -16
  115. package/dist/src/commands/index.d.ts +1 -1
  116. package/dist/src/commands/index.js +1 -1
  117. package/dist/src/commands/verify/addon-source.d.ts +12 -0
  118. package/dist/src/commands/verify/addon-source.js +36 -3
  119. package/dist/src/commands/verify/bare-kit-runtimes.js +2 -1
  120. package/dist/src/commands/verify/node-modules-source.js +10 -1
  121. package/dist/src/{expo/plugins/patches/qvac-platform-addons.d.ts → commands/verify/platform-addons.d.ts} +6 -10
  122. package/dist/src/{expo/plugins/patches/qvac-platform-addons.js → commands/verify/platform-addons.js} +2 -45
  123. package/dist/src/commands/verify/prebuilds.d.ts +7 -10
  124. package/dist/src/commands/verify/prebuilds.js +43 -34
  125. package/dist/src/expo/plugins/get-project-root.d.ts +1 -1
  126. package/dist/src/expo/plugins/link-addons.d.ts +18 -0
  127. package/dist/src/expo/plugins/link-addons.js +65 -0
  128. package/dist/src/expo/plugins/withAndroidArchitecture.d.ts +1 -1
  129. package/dist/src/expo/plugins/withAndroidNdkVersion.d.ts +1 -1
  130. package/dist/src/expo/plugins/withDeviceInfo.d.ts +1 -1
  131. package/dist/src/expo/plugins/withMobileBundle.d.ts +11 -21
  132. package/dist/src/expo/plugins/withMobileBundle.js +22 -112
  133. package/dist/src/expo/plugins/withOpenCL.d.ts +1 -1
  134. package/dist/src/expo/plugins/withQvacSDK.d.ts +1 -1
  135. package/dist/src/index.d.ts +3 -3
  136. package/dist/src/index.js +2 -2
  137. package/dist/src/logging/base-logger.js +1 -1
  138. package/dist/src/logging/utils.js +1 -1
  139. package/dist/src/pear/pre.js +2 -0
  140. package/dist/src/plugin-ids.d.ts +3 -1
  141. package/dist/src/plugin-ids.js +4 -0
  142. package/dist/src/schemas/public.d.ts +2 -1
  143. package/dist/src/schemas/public.js +2 -1
  144. package/dist/src/schemas/sdk-errors-client.d.ts +3 -0
  145. package/dist/src/schemas/sdk-errors-client.js +16 -0
  146. package/dist/src/schemas/sdk-errors-server.d.ts +1 -0
  147. package/dist/src/schemas/sdk-errors-server.js +5 -0
  148. package/dist/src/utils/errors-client.d.ts +10 -0
  149. package/dist/src/utils/errors-client.js +18 -0
  150. package/dist/src/utils/mcp-adapter.js +12 -8
  151. package/dist/src/utils/tool-helpers.d.ts +1 -1
  152. package/dist/src/utils/tool-helpers.js +20 -52
  153. package/dist/src/worker/create-server.d.ts +1 -0
  154. package/dist/src/worker/create-server.js +5 -0
  155. package/dist/src/worker/index.js +4 -0
  156. package/dist/src/worker/lifecycle.js +9 -1
  157. package/dist/src/worker/plugins/llamacpp-decision.d.ts +2 -0
  158. package/dist/src/worker/plugins/llamacpp-decision.js +1 -0
  159. package/dist/src/worker/plugins/moss-transcribe.d.ts +2 -0
  160. package/dist/src/worker/plugins/moss-transcribe.js +1 -0
  161. package/package.json +39 -35
  162. package/src/electron-forge/index.cjs +12 -71
  163. package/dist/scripts/link-workspace-inference.d.ts +0 -2
  164. package/dist/scripts/link-workspace-inference.js +0 -31
  165. package/src/expo/plugins/patches/android-link.mjs +0 -67
  166. package/src/expo/plugins/patches/ios-link.mjs +0 -67
  167. package/src/expo/plugins/patches/qvac-platform-addons.ts +0 -124
@@ -4,9 +4,8 @@ import { spawnSync } from 'child_process';
4
4
  import { fileURLToPath } from 'url';
5
5
  const __dirname = dirname(fileURLToPath(import.meta.url));
6
6
  const testDir = join(__dirname, '..', 'test');
7
- // The Bare suite (test/bare) and its build output (test/dist) run via
8
- // `test:bare`, so the Bun/Node unit runner skips them.
9
- const SKIP_DIRS = new Set(['bare', 'dist']);
7
+ // test/dist is a build output, not a test source tree.
8
+ const SKIP_DIRS = new Set(['dist']);
10
9
  function collectTestFiles(dir) {
11
10
  const files = [];
12
11
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -28,9 +27,15 @@ function usesNodeTestRunner(filePath) {
28
27
  const source = readFileSync(filePath, 'utf8');
29
28
  return source.includes("from 'node:test'") || source.includes('from "node:test"');
30
29
  }
30
+ // Each file runs in its own Node process with tsx loaded, so TypeScript sources
31
+ // and the tsconfig path aliases resolve without a build step. brittle files run
32
+ // as plain scripts; node:test files go through Node's test runner, with
33
+ // `mock.module` enabled for tests that replace a module before importing it.
31
34
  for (const file of testFiles) {
32
- const args = usesNodeTestRunner(file) ? ['test', file] : ['run', file];
33
- const result = spawnSync('bun', args, {
35
+ const args = usesNodeTestRunner(file)
36
+ ? ['--experimental-test-module-mocks', '--import', 'tsx', '--test', file]
37
+ : ['--import', 'tsx', file];
38
+ const result = spawnSync(process.execPath, args, {
34
39
  stdio: 'inherit'
35
40
  });
36
41
  if (result.status !== 0) {
@@ -8,11 +8,11 @@ import { type AssessModelFitInput, type AssessModelFitResult } from '@qvac/infer
8
8
  * the available evidence does not support a verdict either way, and callers
9
9
  * should treat it as "cannot say", not "no".
10
10
  *
11
- * For a single candidate it fetches the registry's weightless description of
12
- * every source that load names — tens of KB each, never the weights — and runs
13
- * the engine's own fitter against them, reported as `native-fit` evidence.
14
- * Where that is unavailable, and for a set of candidates, the calibrated
15
- * estimate stands.
11
+ * For each candidate it fetches the registry's weightless description of every
12
+ * source that load names — tens of KB each, never the weights — and runs the
13
+ * engine's own fitter against them, reported as `native-fit` evidence. Where
14
+ * that is unavailable the computed floor stands, which can refuse a model but
15
+ * never confirm one.
16
16
  *
17
17
  * @param input - Loads to assess in `loadModel`'s own parameters, the declared
18
18
  * execution mode, and the headroom policy.
@@ -23,11 +23,11 @@ function withModelType(candidate) {
23
23
  * the available evidence does not support a verdict either way, and callers
24
24
  * should treat it as "cannot say", not "no".
25
25
  *
26
- * For a single candidate it fetches the registry's weightless description of
27
- * every source that load names — tens of KB each, never the weights — and runs
28
- * the engine's own fitter against them, reported as `native-fit` evidence.
29
- * Where that is unavailable, and for a set of candidates, the calibrated
30
- * estimate stands.
26
+ * For each candidate it fetches the registry's weightless description of every
27
+ * source that load names — tens of KB each, never the weights — and runs the
28
+ * engine's own fitter against them, reported as `native-fit` evidence. Where
29
+ * that is unavailable the computed floor stands, which can refuse a model but
30
+ * never confirm one.
31
31
  *
32
32
  * @param input - Loads to assess in `loadModel`'s own parameters, the declared
33
33
  * execution mode, and the headroom policy.
@@ -53,7 +53,6 @@ export async function assessModelFit(input) {
53
53
  execution: response.execution,
54
54
  ...(response.evidence && { evidence: response.evidence }),
55
55
  ...(response.budget && { budget: response.budget }),
56
- ...(response.estimate && { estimate: response.estimate }),
57
56
  ...(response.floorBytes !== undefined && { floorBytes: response.floorBytes }),
58
57
  models: response.models,
59
58
  reasons: response.reasons,
@@ -3,15 +3,24 @@ import type { AudioEditClientParams, AudioGenResult } from '@qvac/inference/surf
3
3
  * Edits a source recording with a loaded ACE-Step AudioGen model: an ordered
4
4
  * pipeline of `flow-edit` and `repaint` operations, executed in array order.
5
5
  *
6
- * @param params - Loaded model ID, the source audio, the ordered `operations`, and an optional `seed`.
6
+ * @param params - Loaded model ID, the source audio, the ordered `operations`, and optional
7
+ * run controls that apply to every operation.
7
8
  * @param params.sourceAudio - The recording to edit: a file path (decoded server-side) or raw
8
9
  * interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
10
+ * @param params.referenceAudio - Optional timbre reference for every operation, in the same forms
11
+ * as `sourceAudio` (samples need only be finite).
12
+ * @param params.vocalLanguage - Prompt metadata for every operation, as on a generation; so are
13
+ * `bpm`, `keyscale`, `timesignature` and `augmentCaptionWithMetadata`.
14
+ * @param params.dcwEnabled - Repaint only: the Haar DCW sampler correction, tuned by `dcwScaler` and
15
+ * `dcwHighScaler`.
16
+ * @param params.inferenceSteps - DiT steps for every operation (0..1000); omit to keep the load-time
17
+ * value. `shift` overrides the load-time timestep shift the same way.
9
18
  * @param params.operations - `flow-edit` re-conditions the whole clip from a `from` prompt to a
10
19
  * `to` prompt over an optional `nMin`/`nMax` diffusion window (turbo DiT variants only);
11
20
  * `repaint` regenerates the `start`..`end` range (seconds) against a new `caption`, keeping the
12
21
  * rest of the clip. Operations may repeat or mix.
13
22
  * @param params.seed - Seeds the first operation; each following operation uses `seed + index`.
14
- * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise.
23
+ * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise. `stats.metadata.seed` reports the base seed the edit used.
15
24
  *
16
25
  * @example
17
26
  * ```typescript
@@ -27,6 +36,9 @@ import type { AudioEditClientParams, AudioGenResult } from '@qvac/inference/surf
27
36
  * { type: "repaint", caption: "analog synth solo", start: 10, end: 20, mode: "balanced" },
28
37
  * ],
29
38
  * seed: 22883,
39
+ * referenceAudio: "/path/to/reference.wav",
40
+ * bpm: 120,
41
+ * keyscale: "C minor",
30
42
  * });
31
43
  * stopButton.onclick = () => cancel({ requestId: run.requestId });
32
44
  * const { pcm, sampleRate, channels, bitsPerSample } = await run.audio;
@@ -4,15 +4,24 @@ import { createAudioEditResult } from './audio-gen-result.js';
4
4
  * Edits a source recording with a loaded ACE-Step AudioGen model: an ordered
5
5
  * pipeline of `flow-edit` and `repaint` operations, executed in array order.
6
6
  *
7
- * @param params - Loaded model ID, the source audio, the ordered `operations`, and an optional `seed`.
7
+ * @param params - Loaded model ID, the source audio, the ordered `operations`, and optional
8
+ * run controls that apply to every operation.
8
9
  * @param params.sourceAudio - The recording to edit: a file path (decoded server-side) or raw
9
10
  * interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
11
+ * @param params.referenceAudio - Optional timbre reference for every operation, in the same forms
12
+ * as `sourceAudio` (samples need only be finite).
13
+ * @param params.vocalLanguage - Prompt metadata for every operation, as on a generation; so are
14
+ * `bpm`, `keyscale`, `timesignature` and `augmentCaptionWithMetadata`.
15
+ * @param params.dcwEnabled - Repaint only: the Haar DCW sampler correction, tuned by `dcwScaler` and
16
+ * `dcwHighScaler`.
17
+ * @param params.inferenceSteps - DiT steps for every operation (0..1000); omit to keep the load-time
18
+ * value. `shift` overrides the load-time timestep shift the same way.
10
19
  * @param params.operations - `flow-edit` re-conditions the whole clip from a `from` prompt to a
11
20
  * `to` prompt over an optional `nMin`/`nMax` diffusion window (turbo DiT variants only);
12
21
  * `repaint` regenerates the `start`..`end` range (seconds) against a new `caption`, keeping the
13
22
  * rest of the clip. Operations may repeat or mix.
14
23
  * @param params.seed - Seeds the first operation; each following operation uses `seed + index`.
15
- * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise.
24
+ * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise. `stats.metadata.seed` reports the base seed the edit used.
16
25
  *
17
26
  * @example
18
27
  * ```typescript
@@ -28,6 +37,9 @@ import { createAudioEditResult } from './audio-gen-result.js';
28
37
  * { type: "repaint", caption: "analog synth solo", start: 10, end: 20, mode: "balanced" },
29
38
  * ],
30
39
  * seed: 22883,
40
+ * referenceAudio: "/path/to/reference.wav",
41
+ * bpm: 120,
42
+ * keyscale: "C minor",
31
43
  * });
32
44
  * stopButton.onclick = () => cancel({ requestId: run.requestId });
33
45
  * const { pcm, sampleRate, channels, bitsPerSample } = await run.audio;
@@ -22,7 +22,10 @@ import type { AudioGenClientParams, AudioGenResult } from '@qvac/inference/surfa
22
22
  * @param params.track - ACE-Step only: the instrument layer the `"lego"` task regenerates.
23
23
  * Required when `taskType` is `"lego"` and rejected otherwise.
24
24
  * @param params.maxFrames - MiniMax semantic-frame cap; mutually exclusive with `duration`.
25
- * @param params.inferenceSteps - MiniMax flow steps for this run.
25
+ * @param params.inferenceSteps - Diffusion steps for this run (0..1000), on either engine; omit to
26
+ * keep the load-time value.
27
+ * @param params.shift - ACE-Step only: DiT timestep shift for this run; omit to keep the load-time
28
+ * value.
26
29
  * @param params.cfgScale - MiniMax flow classifier-free guidance scale for this run.
27
30
  * @param params.referenceAudio - Optional timbre reference: a file path (decoded server-side)
28
31
  * or raw interleaved stereo 48 kHz Float32 LE PCM bytes.
@@ -31,7 +34,7 @@ import type { AudioGenClientParams, AudioGenResult } from '@qvac/inference/surfa
31
34
  * @param params.taskType - `"text2music"` (default), `"cover-nofsq"`, or `"lego"`.
32
35
  * @param params.audioCoverStrength - Source-context strength for cover tasks (0..1).
33
36
  * @param params.coverNoiseStrength - Initial source/noise blend for cover tasks (0..1).
34
- * @returns A run with a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise describing the backend the run resolved to.
37
+ * @returns A run with a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise describing the backend the run resolved to. An ACE-Step run's stats carry `metadata`: the caption, lyrics and musical metadata it rendered and the seed it used. A MiniMax run's stats carry its stage timings and `emittedFrames`.
35
38
  *
36
39
  * @example
37
40
  * ```typescript
@@ -59,6 +62,7 @@ import type { AudioGenClientParams, AudioGenResult } from '@qvac/inference/surfa
59
62
  * engine: "minimax",
60
63
  * lmModelSrc: "/models/mm3-lm-q8.gguf",
61
64
  * synthModelSrc: "/models/mm3-synth-q8.gguf",
65
+ * device: "gpu", // fail the load instead of falling back to the CPU
62
66
  * },
63
67
  * });
64
68
  * const minimaxRun = audioGen({
@@ -89,6 +93,10 @@ import type { AudioGenClientParams, AudioGenResult } from '@qvac/inference/surfa
89
93
  * });
90
94
  * const { lrc, lyricsScore, qualityScore } = (await assisted.stats) ?? {};
91
95
  *
96
+ * // What the LM composed, and the seed that replays the take:
97
+ * const rendered = (await assisted.stats)?.metadata;
98
+ * console.log(rendered?.caption, rendered?.lyrics, rendered?.bpm, rendered?.seed);
99
+ *
92
100
  * // Rebuild one layer of an existing song:
93
101
  * const newDrums = audioGen({
94
102
  * modelId,
@@ -23,7 +23,10 @@ import { createAudioGenResult } from './audio-gen-result.js';
23
23
  * @param params.track - ACE-Step only: the instrument layer the `"lego"` task regenerates.
24
24
  * Required when `taskType` is `"lego"` and rejected otherwise.
25
25
  * @param params.maxFrames - MiniMax semantic-frame cap; mutually exclusive with `duration`.
26
- * @param params.inferenceSteps - MiniMax flow steps for this run.
26
+ * @param params.inferenceSteps - Diffusion steps for this run (0..1000), on either engine; omit to
27
+ * keep the load-time value.
28
+ * @param params.shift - ACE-Step only: DiT timestep shift for this run; omit to keep the load-time
29
+ * value.
27
30
  * @param params.cfgScale - MiniMax flow classifier-free guidance scale for this run.
28
31
  * @param params.referenceAudio - Optional timbre reference: a file path (decoded server-side)
29
32
  * or raw interleaved stereo 48 kHz Float32 LE PCM bytes.
@@ -32,7 +35,7 @@ import { createAudioGenResult } from './audio-gen-result.js';
32
35
  * @param params.taskType - `"text2music"` (default), `"cover-nofsq"`, or `"lego"`.
33
36
  * @param params.audioCoverStrength - Source-context strength for cover tasks (0..1).
34
37
  * @param params.coverNoiseStrength - Initial source/noise blend for cover tasks (0..1).
35
- * @returns A run with a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise describing the backend the run resolved to.
38
+ * @returns A run with a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise describing the backend the run resolved to. An ACE-Step run's stats carry `metadata`: the caption, lyrics and musical metadata it rendered and the seed it used. A MiniMax run's stats carry its stage timings and `emittedFrames`.
36
39
  *
37
40
  * @example
38
41
  * ```typescript
@@ -60,6 +63,7 @@ import { createAudioGenResult } from './audio-gen-result.js';
60
63
  * engine: "minimax",
61
64
  * lmModelSrc: "/models/mm3-lm-q8.gguf",
62
65
  * synthModelSrc: "/models/mm3-synth-q8.gguf",
66
+ * device: "gpu", // fail the load instead of falling back to the CPU
63
67
  * },
64
68
  * });
65
69
  * const minimaxRun = audioGen({
@@ -90,6 +94,10 @@ import { createAudioGenResult } from './audio-gen-result.js';
90
94
  * });
91
95
  * const { lrc, lyricsScore, qualityScore } = (await assisted.stats) ?? {};
92
96
  *
97
+ * // What the LM composed, and the seed that replays the take:
98
+ * const rendered = (await assisted.stats)?.metadata;
99
+ * console.log(rendered?.caption, rendered?.lyrics, rendered?.bpm, rendered?.seed);
100
+ *
93
101
  * // Rebuild one layer of an existing song:
94
102
  * const newDrums = audioGen({
95
103
  * modelId,
@@ -9,7 +9,7 @@ import type { AudioUnderstandClientParams, AudioUnderstandResult } from '@qvac/i
9
9
  * interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
10
10
  * @param params.vocalLanguage - Language hint forced into the result instead of the LM's guess.
11
11
  * @param params.seed - Seeds the LM decode; omit for a random seed.
12
- * @returns A synchronous request ID, a progress stream, the `description` promise, and the stats and diagnostics promises.
12
+ * @returns A synchronous request ID, a progress stream, the `description` promise, and the stats and diagnostics promises. `description.seed` is the seed the decode used, so an unseeded description can be reproduced.
13
13
  *
14
14
  * @example
15
15
  * ```typescript
@@ -10,7 +10,7 @@ import { createAudioUnderstandResult } from './audio-gen-result.js';
10
10
  * interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
11
11
  * @param params.vocalLanguage - Language hint forced into the result instead of the LM's guess.
12
12
  * @param params.seed - Seeds the LM decode; omit for a random seed.
13
- * @returns A synchronous request ID, a progress stream, the `description` promise, and the stats and diagnostics promises.
13
+ * @returns A synchronous request ID, a progress stream, the `description` promise, and the stats and diagnostics promises. `description.seed` is the seed the decode used, so an unseeded description can be reproduced.
14
14
  *
15
15
  * @example
16
16
  * ```typescript
@@ -51,7 +51,7 @@ async function resolveBatchPrompts(prompts) {
51
51
  resolvedHandlers.push(handlers);
52
52
  resolvedPrompts.push({
53
53
  ...(prompt.id !== undefined && { id: prompt.id }),
54
- history: prompt.history,
54
+ history: prompt.history.map((message) => ({ ...message, content: message.content ?? '' })),
55
55
  ...(prompt.generationParams && {
56
56
  generationParams: prompt.generationParams
57
57
  }),
@@ -181,7 +181,7 @@ export function completion(params) {
181
181
  const request = {
182
182
  type: 'completionStream',
183
183
  modelId: params.modelId,
184
- history: params.history,
184
+ history: params.history.map((message) => ({ ...message, content: message.content ?? '' })),
185
185
  kvCache: params.kvCache,
186
186
  tools: allTools.length > 0 ? allTools : undefined,
187
187
  stream: params.stream ?? true,
@@ -0,0 +1,31 @@
1
+ import { send } from '../rpc/rpc-client.js';
2
+ import { type DecideParams, type DecisionResult, type DecisionResponse, type RPCOptions } from '@qvac/inference/surface';
3
+ /**
4
+ * Answers typed decision questions about one state or a batch of states.
5
+ *
6
+ * @param params - Model ID, states, questions, and optional token budgets.
7
+ * @param options - RPC transport options.
8
+ * @returns A promise with a synchronous requestId for cancel(). One state
9
+ * resolves to one result; a batch resolves to results in input order.
10
+ * @throws {RequestValidationFailedError} If the request is invalid.
11
+ * @throws {InferenceCancelledError} If the request is cancelled.
12
+ * @throws {RequestRejectedByPolicyError} If this model's decision queue is full.
13
+ * @throws {InvalidResponseError} If the worker returns a malformed result.
14
+ */
15
+ export declare function decide(params: Extract<DecideParams, {
16
+ state: unknown;
17
+ }>, options?: RPCOptions): Promise<DecisionResult> & {
18
+ requestId: string;
19
+ };
20
+ export declare function decide(params: Extract<DecideParams, {
21
+ states: unknown;
22
+ }>, options?: RPCOptions): Promise<DecisionResult[]> & {
23
+ requestId: string;
24
+ };
25
+ export declare function decide(params: DecideParams, options?: RPCOptions): Promise<DecisionResponse> & {
26
+ requestId: string;
27
+ };
28
+ export declare function createDecisionCall(params: DecideParams, options?: RPCOptions, sendRequest?: typeof send): Promise<DecisionResponse> & {
29
+ requestId: string;
30
+ };
31
+ //# sourceMappingURL=decide.d.ts.map
@@ -0,0 +1,29 @@
1
+ import { parseClientInput } from '../parse-input.js';
2
+ import { send } from '../rpc/rpc-client.js';
3
+ import { decideParamsSchema, decideResponseSchema } from '@qvac/inference/surface';
4
+ import { InvalidResponseError } from '../../utils/errors-client.js';
5
+ import { decoratePromise } from '../../utils/decorate-promise.js';
6
+ import { generateClientRequestId } from './client-request-id.js';
7
+ export function decide(params, options) {
8
+ return createDecisionCall(params, options);
9
+ }
10
+ export function createDecisionCall(params, options, sendRequest = send) {
11
+ const requestId = generateClientRequestId();
12
+ return decoratePromise(runDecide(params, requestId, options, sendRequest), { requestId });
13
+ }
14
+ async function runDecide(params, requestId, options, sendRequest) {
15
+ const input = parseClientInput(decideParamsSchema, params);
16
+ const response = await sendRequest({ ...input, type: 'decide', requestId }, options);
17
+ if (response.type !== 'decide')
18
+ throw new InvalidResponseError('decide');
19
+ const parsed = decideResponseSchema.safeParse(response);
20
+ if (!parsed.success)
21
+ throw new InvalidResponseError('decide', parsed.error);
22
+ const { result } = parsed.data;
23
+ if ('states' in input
24
+ ? !Array.isArray(result) || result.length !== input.states.length
25
+ : Array.isArray(result)) {
26
+ throw new InvalidResponseError('decide');
27
+ }
28
+ return result;
29
+ }
@@ -38,4 +38,5 @@ export { audioGen } from './audio-gen.js';
38
38
  export { audioEdit } from './audio-edit.js';
39
39
  export { audioUnderstand } from './audio-understand.js';
40
40
  export { startRpcServer, stopRpcServer, discoverRpcServers } from './rpc-server.js';
41
+ export { decide } from './decide.js';
41
42
  //# sourceMappingURL=index.d.ts.map
@@ -38,3 +38,4 @@ export { audioGen } from './audio-gen.js';
38
38
  export { audioEdit } from './audio-edit.js';
39
39
  export { audioUnderstand } from './audio-understand.js';
40
40
  export { startRpcServer, stopRpcServer, discoverRpcServers } from './rpc-server.js';
41
+ export { decide } from './decide.js';
@@ -44,6 +44,7 @@ export declare function loadModel<S extends ModelDescriptor>(options: LoadModelD
44
44
  * - fallbackSrc: For a built-in catalog model, an HTTP URL or local file path to load from when the registry is unreachable (validated against the model checksum)
45
45
  * - requireHttpChecksum: Per-call override — reject a Hugging Face HTTP download that exposes no usable SHA-256 instead of downloading it unverified. Defaults to the engine config (false).
46
46
  * - requireSecureTransport: Per-call override — reject plaintext http:// and HTTPS→HTTP downgrades for every HTTP source (loopback exempt); when unset, only Hugging Face transport is hardened. Defaults to the engine config (false).
47
+ * - modelFitPolicy: Per-call override — "log" reports the engine fitter's verdict and loads anyway, "refuse" rejects a load it projects will not fit, "off" skips the check. Defaults to the engine config ("log").
47
48
  * - onProgress: Callback for download progress updates
48
49
  * - logger: Logger instance for model operation logs
49
50
  * @param rpcOptions - Optional RPC options including per-call profiling configuration
@@ -83,6 +83,7 @@ export declare function textToSpeech(params: TtsClientParamsInput, options?: RPC
83
83
  * so `await result.sampleRate` can never hang or reject on its own.
84
84
  */
85
85
  export type TtsSideChannel = {
86
+ text: Promise<string | undefined>;
86
87
  sampleRate: Promise<number | undefined>;
87
88
  stats: Promise<TtsStats | undefined>;
88
89
  stopReason: Promise<'completed' | 'cancelled' | undefined>;
@@ -132,29 +132,9 @@ export class TtsMulticast {
132
132
  }
133
133
  function buildTtsRequest(params, requestId) {
134
134
  return {
135
+ ...params,
135
136
  type: 'textToSpeech',
136
- modelId: params.modelId,
137
- requestId,
138
- inputType: params.inputType,
139
- text: params.text,
140
- stream: params.stream,
141
- sentenceStream: params.sentenceStream,
142
- ...(params.sentenceStreamLocale !== undefined && {
143
- sentenceStreamLocale: params.sentenceStreamLocale
144
- }),
145
- ...(params.sentenceStreamMaxChunkScalars !== undefined && {
146
- sentenceStreamMaxChunkScalars: params.sentenceStreamMaxChunkScalars
147
- }),
148
- ...(params.description !== undefined && { description: params.description }),
149
- ...(params.voiceDescription !== undefined && { voiceDescription: params.voiceDescription }),
150
- ...(params.voice !== undefined && { voice: params.voice }),
151
- ...(params.emotion !== undefined && { emotion: params.emotion }),
152
- ...(params.pitch !== undefined && { pitch: params.pitch }),
153
- ...(params.pace !== undefined && { pace: params.pace }),
154
- ...(params.expressivity !== undefined && { expressivity: params.expressivity }),
155
- ...(params.noise !== undefined && { noise: params.noise }),
156
- ...(params.reverb !== undefined && { reverb: params.reverb }),
157
- ...(params.quality !== undefined && { quality: params.quality })
137
+ requestId
158
138
  };
159
139
  }
160
140
  function buildTextToSpeechStreamRequest(params, requestId) {
@@ -271,6 +251,11 @@ async function* ttsResponseSource(request, options, side) {
271
251
  }
272
252
  /** Exported for test use; not part of the public SDK surface. */
273
253
  export function createTtsSideChannel() {
254
+ let resolveText;
255
+ const text = new Promise((resolve) => {
256
+ resolveText = resolve;
257
+ });
258
+ let seenText;
274
259
  let resolveSampleRate;
275
260
  let resolveStats;
276
261
  let resolveStopReason;
@@ -288,10 +273,13 @@ export function createTtsSideChannel() {
288
273
  let seenStopReason;
289
274
  let settled = false;
290
275
  return {
276
+ text,
291
277
  sampleRate,
292
278
  stats,
293
279
  stopReason,
294
280
  observe(response) {
281
+ if (response.text !== undefined)
282
+ seenText = response.text;
295
283
  // Resolve on the FIRST frame that carries a rate, not at end of stream:
296
284
  // a caller opening an audio device wants it before draining the audio.
297
285
  // Promise resolution is idempotent, so settle() can still resolve the
@@ -309,6 +297,7 @@ export function createTtsSideChannel() {
309
297
  if (settled)
310
298
  return;
311
299
  settled = true;
300
+ resolveText(seenText);
312
301
  resolveSampleRate(seenSampleRate);
313
302
  resolveStats(latestStats);
314
303
  resolveStopReason(seenStopReason);
@@ -331,6 +320,7 @@ function sentenceStreamTts(request, options) {
331
320
  buffer: Promise.resolve([]),
332
321
  done: multicast.done,
333
322
  requestId: request.requestId,
323
+ text: side.text,
334
324
  sampleRate: side.sampleRate,
335
325
  stats: side.stats,
336
326
  stopReason: side.stopReason
@@ -379,6 +369,7 @@ function plainStreamTts(request, options) {
379
369
  buffer: Promise.resolve([]),
380
370
  done,
381
371
  requestId: request.requestId,
372
+ text: side.text,
382
373
  sampleRate: side.sampleRate,
383
374
  stats: side.stats,
384
375
  stopReason: side.stopReason
@@ -431,6 +422,7 @@ function collectTts(request, options) {
431
422
  buffer: collectTtsBuffer(request, options, resolveDone, rejectDone, side),
432
423
  done,
433
424
  requestId: request.requestId,
425
+ text: side.text,
434
426
  sampleRate: side.sampleRate,
435
427
  stats: side.stats,
436
428
  stopReason: side.stopReason
@@ -449,6 +441,7 @@ async function collectTtsBuffer(request, options, resolveDone, rejectDone, side)
449
441
  buffer = buffer.concat(response.buffer);
450
442
  if (response.done) {
451
443
  resolveDone(true);
444
+ break;
452
445
  }
453
446
  }
454
447
  return buffer;
@@ -12,7 +12,9 @@ function buildTranscribeRequest(params, requestId) {
12
12
  audioChunk: typeof params.audioChunk === 'string'
13
13
  ? { type: 'filePath', value: params.audioChunk }
14
14
  : { type: 'base64', value: params.audioChunk.toString('base64') },
15
- ...(params.prompt && { prompt: params.prompt }),
15
+ ...(params.prompt !== undefined && params.prompt !== null && { prompt: params.prompt }),
16
+ ...(params.hotwords !== undefined && { hotwords: params.hotwords }),
17
+ ...(params.maxNewTokens !== undefined && { maxNewTokens: params.maxNewTokens }),
16
18
  ...(params.metadata === true && { metadata: true }),
17
19
  requestId
18
20
  };
@@ -310,7 +312,8 @@ export function processLineConversation(line, wantsMetadata, onTerminal) {
310
312
  type: 'vad',
311
313
  speaking: response.vad.speaking,
312
314
  probability: response.vad.probability,
313
- ...(response.vad.source && { source: response.vad.source })
315
+ ...(response.vad.source && { source: response.vad.source }),
316
+ ...(response.vad.speakerId !== undefined && { speakerId: response.vad.speakerId })
314
317
  };
315
318
  }
316
319
  if (response.endOfTurn) {
@@ -9,10 +9,10 @@ export declare function createVideoStreamRequest(params: VideoClientParams, requ
9
9
  modelId: string;
10
10
  seed?: number | undefined;
11
11
  vae_tiling?: boolean | undefined;
12
+ steps?: number | undefined;
12
13
  negative_prompt?: string | undefined;
13
14
  width?: number | undefined;
14
15
  height?: number | undefined;
15
- steps?: number | undefined;
16
16
  cfg_scale?: number | undefined;
17
17
  sampling_method?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
18
18
  scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | "ltx2" | undefined;
@@ -50,10 +50,10 @@ export declare function createVideoStreamRequest(params: VideoClientParams, requ
50
50
  modelId: string;
51
51
  seed?: number | undefined;
52
52
  vae_tiling?: boolean | undefined;
53
+ steps?: number | undefined;
53
54
  negative_prompt?: string | undefined;
54
55
  width?: number | undefined;
55
56
  height?: number | undefined;
56
- steps?: number | undefined;
57
57
  cfg_scale?: number | undefined;
58
58
  sampling_method?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
59
59
  scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | "ltx2" | undefined;
@@ -91,10 +91,10 @@ export declare function createVideoStreamRequest(params: VideoClientParams, requ
91
91
  modelId: string;
92
92
  seed?: number | undefined;
93
93
  vae_tiling?: boolean | undefined;
94
+ steps?: number | undefined;
94
95
  negative_prompt?: string | undefined;
95
96
  width?: number | undefined;
96
97
  height?: number | undefined;
97
- steps?: number | undefined;
98
98
  cfg_scale?: number | undefined;
99
99
  sampling_method?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
100
100
  scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | "ltx2" | undefined;
@@ -132,10 +132,10 @@ export declare function createVideoStreamRequest(params: VideoClientParams, requ
132
132
  modelId: string;
133
133
  seed?: number | undefined;
134
134
  vae_tiling?: boolean | undefined;
135
+ steps?: number | undefined;
135
136
  negative_prompt?: string | undefined;
136
137
  width?: number | undefined;
137
138
  height?: number | undefined;
138
- steps?: number | undefined;
139
139
  cfg_scale?: number | undefined;
140
140
  sampling_method?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
141
141
  scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | "ltx2" | undefined;
@@ -173,10 +173,10 @@ export declare function createVideoStreamRequest(params: VideoClientParams, requ
173
173
  modelId: string;
174
174
  seed?: number | undefined;
175
175
  vae_tiling?: boolean | undefined;
176
+ steps?: number | undefined;
176
177
  negative_prompt?: string | undefined;
177
178
  width?: number | undefined;
178
179
  height?: number | undefined;
179
- steps?: number | undefined;
180
180
  cfg_scale?: number | undefined;
181
181
  sampling_method?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
182
182
  scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | "ltx2" | undefined;
@@ -16,12 +16,15 @@ export interface VideoResult {
16
16
  * @param params - Video request parameters (model, prompt, dimensions, frame count, fps, sampler, seed, etc.).
17
17
  * @returns A result object exposing `requestId` (stable identifier for this in-flight generation), `progressStream` (async iterator of `{ step, totalSteps, elapsedMs }`), `outputs` (promise of the generated video buffers, typically a single AVI file), and `stats` (promise of generation statistics).
18
18
  *
19
- * Supports `txt2vid` (text-to-video) and `img2vid` (image-to-video) for both the
20
- * Wan and LTX-2 layouts. For Wan `img2vid`, load the pipeline with
19
+ * Supports `txt2vid` (text-to-video) and `img2vid` (image-to-video) for Wan,
20
+ * LTX-2, and MiniMax H3. For Wan `img2vid`, load the pipeline with
21
21
  * `modelConfig.clipVisionModelSrc` set to `clip_vision_h.safetensors`; LTX-2
22
22
  * `img2vid` conditions on the first frame through its video VAE and needs no
23
23
  * CLIP vision weights (the same LTX-2 model loaded for txt2vid also does
24
- * img2vid). On React Native, the bundled video diffusion models are too large
24
+ * img2vid). MiniMax H3 also conditions through its video VAE; load its text
25
+ * encoder companion and optionally its audio VAE for synchronized audio. H3
26
+ * frames must satisfy `17*k + 5`, and its native frame rate is 24 FPS. On
27
+ * React Native, the bundled video diffusion models are too large
25
28
  * for typical mobile devices.
26
29
  *
27
30
  * @example Basic txt2vid generation
@@ -64,6 +67,23 @@ export interface VideoResult {
64
67
  * });
65
68
  * ```
66
69
  *
70
+ * @example MiniMax H3 image-to-video
71
+ * ```typescript
72
+ * const firstFrame = fs.readFileSync("first-frame.png");
73
+ * const { outputs } = video({
74
+ * modelId,
75
+ * mode: "img2vid",
76
+ * prompt: "A sailboat glides across a calm bay as the camera follows it.",
77
+ * init_image: firstFrame,
78
+ * width: 864,
79
+ * height: 480,
80
+ * video_frames: 22,
81
+ * fps: 24,
82
+ * cfg_scale: 1,
83
+ * });
84
+ * fs.writeFileSync("h3-output.avi", (await outputs)[0]);
85
+ * ```
86
+ *
67
87
  * @example With control frames (e.g. for guided generation)
68
88
  * ```typescript
69
89
  * const frameA = fs.readFileSync("frame-a.png");
@@ -9,12 +9,15 @@ import { decodeBase64 } from '../../utils/encoding.js';
9
9
  * @param params - Video request parameters (model, prompt, dimensions, frame count, fps, sampler, seed, etc.).
10
10
  * @returns A result object exposing `requestId` (stable identifier for this in-flight generation), `progressStream` (async iterator of `{ step, totalSteps, elapsedMs }`), `outputs` (promise of the generated video buffers, typically a single AVI file), and `stats` (promise of generation statistics).
11
11
  *
12
- * Supports `txt2vid` (text-to-video) and `img2vid` (image-to-video) for both the
13
- * Wan and LTX-2 layouts. For Wan `img2vid`, load the pipeline with
12
+ * Supports `txt2vid` (text-to-video) and `img2vid` (image-to-video) for Wan,
13
+ * LTX-2, and MiniMax H3. For Wan `img2vid`, load the pipeline with
14
14
  * `modelConfig.clipVisionModelSrc` set to `clip_vision_h.safetensors`; LTX-2
15
15
  * `img2vid` conditions on the first frame through its video VAE and needs no
16
16
  * CLIP vision weights (the same LTX-2 model loaded for txt2vid also does
17
- * img2vid). On React Native, the bundled video diffusion models are too large
17
+ * img2vid). MiniMax H3 also conditions through its video VAE; load its text
18
+ * encoder companion and optionally its audio VAE for synchronized audio. H3
19
+ * frames must satisfy `17*k + 5`, and its native frame rate is 24 FPS. On
20
+ * React Native, the bundled video diffusion models are too large
18
21
  * for typical mobile devices.
19
22
  *
20
23
  * @example Basic txt2vid generation
@@ -57,6 +60,23 @@ import { decodeBase64 } from '../../utils/encoding.js';
57
60
  * });
58
61
  * ```
59
62
  *
63
+ * @example MiniMax H3 image-to-video
64
+ * ```typescript
65
+ * const firstFrame = fs.readFileSync("first-frame.png");
66
+ * const { outputs } = video({
67
+ * modelId,
68
+ * mode: "img2vid",
69
+ * prompt: "A sailboat glides across a calm bay as the camera follows it.",
70
+ * init_image: firstFrame,
71
+ * width: 864,
72
+ * height: 480,
73
+ * video_frames: 22,
74
+ * fps: 24,
75
+ * cfg_scale: 1,
76
+ * });
77
+ * fs.writeFileSync("h3-output.avi", (await outputs)[0]);
78
+ * ```
79
+ *
60
80
  * @example With control frames (e.g. for guided generation)
61
81
  * ```typescript
62
82
  * const frameA = fs.readFileSync("frame-a.png");