@qvac/audiogen-ggml 0.4.0 → 0.5.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.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.5.0] - 2026-09-25
11
+
12
+ ### Changed
13
+
14
+ - Raise the `ggml-speech` floor to `2026-09-23` and the `speech-cpp` floor to
15
+ `2026-09-23#1`. The speech ggml now tracks upstream ggml 0.20.2 (was 0.10.2),
16
+ and its Vulkan backend no longer crashes on NVIDIA GPUs that report
17
+ cooperative-matrix2 support when a matmul is asked for f32 precision. The
18
+ ACE-Step memory-fit preflight now returns a verdict instead of aborting the
19
+ process: it priced the VAE decode/encode windows through a graph scheduler
20
+ that cannot place a metadata-only model's weights, so every ACE-Step model
21
+ hit a ggml assertion on CPU and GPU alike. Generation itself is unchanged.
22
+ - Raise the `speech-cpp` floor to `2026-09-18`. MiniMax-Music3 generates faster
23
+ with the model files you already have: the RVQ depth decoder keeps a K/V cache
24
+ instead of recomputing its prefix on every codebook step, and the flow default
25
+ is 20 steps instead of 30 (`inferenceSteps` still overrides it). On an AMD
26
+ Strix Halo a 10 s track goes from 57.0 s to 39.1 s on Vulkan. Synth files
27
+ re-converted with the new engine also quantize the depth decoder with the
28
+ chosen tier, worth a further 2.6 s there.
29
+ - Raise the `speech-cpp` floor to `2026-09-16`, keeping the speech packages on
30
+ one engine stack. Nothing in the window touches the audiogen engine, so
31
+ published behavior is unchanged.
32
+
33
+ ## [0.4.1] - 2026-09-16
34
+
35
+ ### Changed
36
+
37
+ - Raise the `speech-cpp` floor to `2026-09-11`. The pinned engine adds an
38
+ optional Apple-only Core ML sidecar for the ACE-Step VAE decoder
39
+ (`AUDIOGEN_COREML`); the prebuilds keep it disabled, so published behavior
40
+ is unchanged until a build opts in.
41
+
42
+ - The binding loader now verifies that `require.addon()` returned an AudioGen
43
+ native binding before using it. If the result is the JavaScript package entry,
44
+ loading falls through to `#host-addon`; the resolved platform package is
45
+ validated as well, and the original lookup failure is retained as the error
46
+ cause for clearer diagnostics. Without this the wrong module was returned
47
+ verbatim and the first symptom was `createInstance is not a function` deep in
48
+ a model load. Local source-build behaviour is unchanged.
49
+
50
+ ### Fixed
51
+
52
+ - Mobile platform packages (`@qvac/audiogen-ggml-android-arm64`,
53
+ `@qvac/audiogen-ggml-ios`) are no longer `os`-filtered `optionalDependencies`
54
+ of the meta package. No build host ever reports a mobile `os`, so installers
55
+ could never select them during a cross-build and mobile bundles failed
56
+ verification with missing prebuilds. They now publish without install filters;
57
+ mobile applications declare the target's platform package as a direct
58
+ dependency pinned to the exact meta package version.
59
+
60
+
10
61
  ## [0.4.0] - 2026-09-11
11
62
 
12
63
  ### Added
package/README.md CHANGED
@@ -43,8 +43,8 @@ MiniMax-Music3 is available only in the Linux, macOS, and Windows prebuilds.
43
43
  ### Platform packages
44
44
 
45
45
  `@qvac/audiogen-ggml` is a meta package that ships the JavaScript wrapper
46
- only. The native prebuild for each host lives in a version-locked platform
47
- package selected at install time through `os`/`cpu` filtered
46
+ only. The native prebuild for each desktop host lives in a version-locked
47
+ platform package selected at install time through `os`/`cpu` filtered
48
48
  `optionalDependencies`:
49
49
 
50
50
  | Host | Package |
@@ -54,17 +54,34 @@ package selected at install time through `os`/`cpu` filtered
54
54
  | darwin-arm64 | `@qvac/audiogen-ggml-darwin-arm64` |
55
55
  | darwin-x64 | `@qvac/audiogen-ggml-darwin-x64` |
56
56
  | win32-x64 | `@qvac/audiogen-ggml-win32-x64` |
57
- | android-arm64 | `@qvac/audiogen-ggml-android-arm64` |
58
- | ios (device + simulators) | `@qvac/audiogen-ggml-ios` |
59
57
 
60
- Do not depend on platform packages directly. Supported installers are npm 7+,
61
- pnpm, bun, and Yarn Berry. Yarn v1 and `--omit=optional` installs skip the
62
- platform package and fail at require time with an error naming the missing
58
+ Do not depend on desktop platform packages directly. Supported installers are
59
+ npm 7+, pnpm, bun, and Yarn Berry. Yarn v1 and `--omit=optional` installs skip
60
+ the platform package and fail at require time with an error naming the missing
63
61
  package; a locally built `prebuilds/` directory in the package root always
64
62
  takes precedence. Use `require('@qvac/audiogen-ggml').resolveBackendsDir()`
65
63
  to locate the directory holding the host's prebuilt binaries and dynamically
66
64
  loaded ggml backends.
67
65
 
66
+ Mobile targets are cross-built, so no install host ever matches their `os`,
67
+ and `optionalDependencies` filtering can never select them. Mobile
68
+ applications must declare the target's platform package as a direct
69
+ dependency, pinned to the exact `@qvac/audiogen-ggml` version:
70
+
71
+ | Target | Package |
72
+ | --- | --- |
73
+ | android-arm64 | `@qvac/audiogen-ggml-android-arm64` |
74
+ | ios (device + simulators) | `@qvac/audiogen-ggml-ios` |
75
+
76
+ ```json
77
+ {
78
+ "dependencies": {
79
+ "@qvac/audiogen-ggml": "x.y.z",
80
+ "@qvac/audiogen-ggml-android-arm64": "x.y.z"
81
+ }
82
+ }
83
+ ```
84
+
68
85
  The published linux-x64 prebuild bundles the CUDA backend next to Vulkan; the
69
86
  linux-arm64 and Windows prebuilds ship Vulkan, and there CUDA is opt-in at
70
87
  build time via `npm run build:cuda` (or `bare-make generate -D ENABLE_CUDA=ON`;
@@ -641,6 +658,58 @@ npx qvac-audiogen-download-models --output ./models/audiogen --variant turbo-q4
641
658
  `sft`, or `all`; it defaults to `turbo-q4`. Use `--help` to print the flags.
642
659
  The command does not write into the installed package.
643
660
 
661
+ ## Assessing fit
662
+
663
+ `assessFit` projects a load against the memory free right now. It reads GGUF
664
+ metadata and never weight data, so the registry's weightless copy of each stage
665
+ answers the same as the file itself and the projection can run before anything
666
+ is downloaded. It is a module export, not an instance method — nothing is
667
+ loaded to call it.
668
+
669
+ ```js
670
+ const { assessFit } = require('@qvac/audiogen-ggml')
671
+
672
+ const fit = assessFit({
673
+ modelsDir: '/models/ace-step',
674
+ durationSeconds: 30,
675
+ textTokens: 256,
676
+ lyricTokens: 256
677
+ })
678
+
679
+ fit.status // 'fits' | 'does-not-fit' | 'error'
680
+ fit.reason // the engine's own wording, e.g. 'model-unreadable', 'workload-too-large'
681
+ fit.modelName
682
+ fit.isTurbo
683
+ fit.deviceName
684
+ fit.deviceBytes // peak across the pipeline phases under the projected residency mode
685
+ fit.hostBytes
686
+ fit.hostFreeBytes // host capacity, a budget of its own where the device has its own memory
687
+ fit.stagesResident
688
+ fit.report
689
+ ```
690
+
691
+ `modelsDir` holds the four stage GGUFs; `textEncoderPath`, `lmPath`, `ditPath`
692
+ and `vaePath` name them individually and win over it.
693
+
694
+ | Option | Description |
695
+ | --- | --- |
696
+ | `durationSeconds` | Longest single generation the projection must accommodate. |
697
+ | `textTokens`, `lyricTokens` | The prompt the projection is sized for. |
698
+ | `lmPromptTokens` | 0 derives it from the text and lyric budgets. |
699
+ | `lmMaxNewTokens` | 0 derives it from the duration, as the pipeline does. |
700
+ | `lmCfgScale`, `guidanceScale` | 0 picks CFG or no CFG from the checkpoint. |
701
+ | `withSourceAudio` | Projects the extra VAE-encoder phase a cover or reference request loads. |
702
+ | `keepStages` | `-1` mirrors the engine, `0` forces the staged projection, `1` all-resident. |
703
+ | `gpuLayers` | Greater than 0 requests the GPU stack, with the fallbacks a real load applies. |
704
+ | `threads`, `backendsDir` | As the load takes them. |
705
+ | `marginBytes` | Free memory that must remain for the projection to count as fitting. Defaults to 256 MiB. |
706
+
707
+ `deviceSharesHostMemory` reports that the device pool is system RAM, so host
708
+ bytes compete with device bytes.
709
+
710
+ A model the engine cannot read is `status: "error"`; a broken request, or a
711
+ host with no native binding, throws.
712
+
644
713
  ## Lifecycle
645
714
 
646
715
  Call `load()` before `run()`. Overlapping `run()` calls are admitted in order;
package/binding.js CHANGED
@@ -1,18 +1,49 @@
1
1
  module.exports = loadAddon()
2
2
 
3
+ // The split meta package has no local prebuild. Some runtimes return this
4
+ // package's Javascript entry from require.addon() instead of throwing, so
5
+ // validate the result before accepting it as the native binding.
6
+
3
7
  function loadAddon() {
8
+ let cause = null
9
+
4
10
  try {
5
- return require.addon()
11
+ const addon = require.addon()
12
+ if (isNativeBinding(addon)) return addon
13
+ cause = new Error(
14
+ '@qvac/audiogen-ggml: require.addon() answered with a module that is not the native binding ' +
15
+ '(no createInstance function), so the prebuild in this package was treated as absent.'
16
+ )
6
17
  } catch (err) {
7
- return loadPlatformPackageAddon(err)
18
+ cause = err
8
19
  }
20
+
21
+ return loadPlatformPackageAddon(cause)
9
22
  }
10
23
 
11
24
  function loadPlatformPackageAddon(cause) {
25
+ let addon
26
+
12
27
  try {
13
- return require('#host-addon')
28
+ addon = require('#host-addon')
14
29
  } catch (err) {
15
30
  if (err.cause === undefined) err.cause = cause
16
31
  throw err
17
32
  }
33
+
34
+ if (!isNativeBinding(addon)) {
35
+ const err = new Error(
36
+ '@qvac/audiogen-ggml resolved #host-addon to a module that is not the native binding: ' +
37
+ 'it has no createInstance function. Check that the platform package for this host ' +
38
+ 'is installed and is not shadowed by another module of the same name.'
39
+ )
40
+ err.cause = cause
41
+ throw err
42
+ }
43
+
44
+ return addon
45
+ }
46
+
47
+ function isNativeBinding(addon) {
48
+ return addon !== null && typeof addon === 'object' && typeof addon.createInstance === 'function'
18
49
  }
package/index.d.ts CHANGED
@@ -79,7 +79,7 @@ export interface GenerateOptions {
79
79
  duration?: number;
80
80
  /** MiniMax semantic-frame cap. Cannot be combined with `duration`. */
81
81
  maxFrames?: number;
82
- /** MiniMax flow steps for this generation; 0 uses the model default. */
82
+ /** MiniMax flow steps for this generation; 0 uses the engine default (20). */
83
83
  inferenceSteps?: number;
84
84
  /** MiniMax flow classifier-free guidance scale for this generation. */
85
85
  cfgScale?: number;
@@ -459,6 +459,8 @@ export type { DitVariant, ModelManifest, ModelSources, ResolveDitModelPathOption
459
459
  export { encodePcm, pcmToWav, SUPPORTED_FORMATS as OUTPUT_FORMATS } from './lib/audio-format';
460
460
  export type { OutputFormat, EncodeOptions, EncodedAudio } from './lib/audio-format';
461
461
  export { resolveBackendsDir } from './lib/backends';
462
+ export { assessFit } from './lib/fit';
463
+ export type { AudiogenFitRequest, AudiogenFitResult, AudiogenFitStatus } from './lib/fit';
462
464
  export { ERR_CODE_RANGE, ERR_CODES, QvacErrorAudioGen } from './error';
463
465
  export { AudioEditOperationType, RepaintMode } from './audiogen';
464
466
  export type { AudioGenConfigurationParams, AudioGenJobData, AudioGenBinding, AudioGenOutputCallback } from './audiogen';
package/index.js CHANGED
@@ -11,7 +11,7 @@
11
11
  // streams the engine's output (progress ticks + one interleaved-Int16 PCM
12
12
  // chunk) and resolves with the run stats.
13
13
  Object.defineProperty(exports, "__esModule", { value: true });
14
- exports.RepaintMode = exports.AudioEditOperationType = exports.QvacErrorAudioGen = exports.ERR_CODES = exports.ERR_CODE_RANGE = exports.resolveBackendsDir = exports.OUTPUT_FORMATS = exports.pcmToWav = exports.encodePcm = exports.allRegistryPaths = exports.resolveDitModelPath = exports.modelSources = exports.modelManifest = exports.modelFilenames = exports.registryPath = exports.ditFilename = exports.ditVariants = exports.DEFAULT_DIT_VARIANT = exports.DIT_VARIANTS = exports.FIXED_MODELS = exports.REGISTRY_PREFIX = exports.REGISTRY_SOURCE = exports.AudioGen = exports.AudioEditSession = exports.AUDIOGEN_GPU_FALLBACK_REASONS = exports.AUDIOGEN_BACKEND_NAMES = exports.MINIMAX_DEFAULT_MAX_FRAMES = exports.MINIMAX_FRAMES_PER_SECOND = exports.ENGINE_MINIMAX = exports.ENGINE_ACESTEP = void 0;
14
+ exports.RepaintMode = exports.AudioEditOperationType = exports.QvacErrorAudioGen = exports.ERR_CODES = exports.ERR_CODE_RANGE = exports.assessFit = exports.resolveBackendsDir = exports.OUTPUT_FORMATS = exports.pcmToWav = exports.encodePcm = exports.allRegistryPaths = exports.resolveDitModelPath = exports.modelSources = exports.modelManifest = exports.modelFilenames = exports.registryPath = exports.ditFilename = exports.ditVariants = exports.DEFAULT_DIT_VARIANT = exports.DIT_VARIANTS = exports.FIXED_MODELS = exports.REGISTRY_PREFIX = exports.REGISTRY_SOURCE = exports.AudioGen = exports.AudioEditSession = exports.AUDIOGEN_GPU_FALLBACK_REASONS = exports.AUDIOGEN_BACKEND_NAMES = exports.MINIMAX_DEFAULT_MAX_FRAMES = exports.MINIMAX_FRAMES_PER_SECOND = exports.ENGINE_MINIMAX = exports.ENGINE_ACESTEP = void 0;
15
15
  exports.audiogenBackendName = audiogenBackendName;
16
16
  exports.audiogenGpuFallbackReason = audiogenGpuFallbackReason;
17
17
  exports.detectEngineType = detectEngineType;
@@ -1079,6 +1079,8 @@ Object.defineProperty(exports, "pcmToWav", { enumerable: true, get: function ()
1079
1079
  Object.defineProperty(exports, "OUTPUT_FORMATS", { enumerable: true, get: function () { return audio_format_2.SUPPORTED_FORMATS; } });
1080
1080
  var backends_2 = require("./lib/backends");
1081
1081
  Object.defineProperty(exports, "resolveBackendsDir", { enumerable: true, get: function () { return backends_2.resolveBackendsDir; } });
1082
+ var fit_1 = require("./lib/fit");
1083
+ Object.defineProperty(exports, "assessFit", { enumerable: true, get: function () { return fit_1.assessFit; } });
1082
1084
  var error_2 = require("./error");
1083
1085
  Object.defineProperty(exports, "ERR_CODE_RANGE", { enumerable: true, get: function () { return error_2.ERR_CODE_RANGE; } });
1084
1086
  Object.defineProperty(exports, "ERR_CODES", { enumerable: true, get: function () { return error_2.ERR_CODES; } });
package/lib/fit.d.ts ADDED
@@ -0,0 +1,88 @@
1
+ export type AudiogenFitEngine = 'acestep' | 'minimax'
2
+
3
+ export interface AudiogenFitRequest {
4
+ /** Engine that would run the load. Defaults to `acestep`. */
5
+ engine?: AudiogenFitEngine
6
+ /** Directory holding the four stage GGUFs; explicit paths win over it. */
7
+ modelsDir?: string
8
+ textEncoderPath?: string
9
+ lmPath?: string
10
+ ditPath?: string
11
+ vaePath?: string
12
+
13
+ /** > 0 requests the GPU stack, with the fallbacks a real load applies. */
14
+ gpuLayers?: number
15
+ threads?: number
16
+ backendsDir?: string
17
+
18
+ /** Longest single generation the projection must accommodate. */
19
+ durationSeconds?: number
20
+ textTokens?: number
21
+ lyricTokens?: number
22
+ /** 0 derives it from the text and lyric budgets. */
23
+ lmPromptTokens?: number
24
+ /** 0 derives it from the duration, as the pipeline does. */
25
+ lmMaxNewTokens?: number
26
+ lmCfgScale?: number
27
+ /** 0 picks CFG or no CFG from the checkpoint. */
28
+ guidanceScale?: number
29
+ /** Projects the extra VAE-encoder phase a cover or reference request loads. */
30
+ withSourceAudio?: boolean
31
+ /** -1 mirrors the engine, 0 forces the staged projection, 1 all-resident. */
32
+ keepStages?: number
33
+ /** Free memory that must remain for the projection to count as fitting. Defaults to 256 MiB. */
34
+ marginBytes?: number
35
+ }
36
+
37
+ export type AudiogenFitStatus = 'fits' | 'does-not-fit' | 'error'
38
+
39
+ /** One pipeline stage, as the fitter placed it. */
40
+ export interface AudiogenFitStage {
41
+ /** `textenc` | `lm` | `cond` | `detok` | `dit` | `vae`. */
42
+ name: string
43
+ /** Backend the stage loads on, after placement. */
44
+ deviceName: string
45
+ onGpu: boolean
46
+ weightsBytes: number
47
+ /** The portion mapped in place from the file, on the host. */
48
+ weightsMmapBytes: number
49
+ /** The LM KV cache. */
50
+ stateBytes: number
51
+ /** Largest compute arena the stage holds at once. */
52
+ computeBytes: number
53
+ /** Stage-phase host buffers: masks, latents, PCM. */
54
+ hostBytes: number
55
+ }
56
+
57
+ export interface AudiogenFitResult {
58
+ status: AudiogenFitStatus
59
+ /**
60
+ * The engine's own wording, e.g. `model-unreadable`, `workload-too-large`.
61
+ * `unsupported-engine` names an engine the addon loads and the fitter does
62
+ * not cover.
63
+ */
64
+ reason: string
65
+ modelName: string
66
+ isTurbo: boolean
67
+ deviceName: string
68
+ deviceIsCpu: boolean
69
+ /** The device pool is system RAM, so host bytes compete with device bytes. */
70
+ deviceSharesHostMemory: boolean
71
+ deviceFreeBytes: number
72
+ deviceTotalBytes: number
73
+ /** Peak across the pipeline phases under the projected residency mode. */
74
+ deviceBytes: number
75
+ hostBytes: number
76
+ /** Host capacity, which is a budget of its own where the device has its own memory. */
77
+ hostFreeBytes: number
78
+ hostTotalBytes: number
79
+ stagesResident: boolean
80
+ /**
81
+ * One row per pipeline stage. `deviceBytes` is a peak across phases, so the
82
+ * rows are where the weights, state and compute split apart.
83
+ */
84
+ stages: AudiogenFitStage[]
85
+ report: string
86
+ }
87
+
88
+ export function assessFit(request: AudiogenFitRequest): AudiogenFitResult
package/lib/fit.js ADDED
@@ -0,0 +1,30 @@
1
+ 'use strict'
2
+
3
+ const { resolveBackendsDir } = require('./backends')
4
+
5
+ /**
6
+ * Projects one model set against the memory free right now, reading GGUF
7
+ * metadata and never weight data. The registry's weightless copy of each stage
8
+ * answers the same as the stage itself, so this can run before anything is
9
+ * downloaded.
10
+ *
11
+ * `engine` defaults to `acestep`, the one engine audiogen-cpp ships a fitter
12
+ * for. Any other engine comes back as `status: "error"` with
13
+ * `reason: "unsupported-engine"`.
14
+ *
15
+ * A model set the engine cannot read comes back as `status: "error"` with its
16
+ * own reason; a broken request, or a host with no native binding, throws.
17
+ */
18
+ function assessFit(request) {
19
+ const binding = require('../binding.js')
20
+
21
+ return binding.assessFit({
22
+ ...request,
23
+ backendsDir:
24
+ typeof request.backendsDir === 'string' && request.backendsDir.length > 0
25
+ ? request.backendsDir
26
+ : resolveBackendsDir()
27
+ })
28
+ }
29
+
30
+ module.exports = { assessFit }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qvac/audiogen-ggml",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Audio generation (music) addon for qvac",
5
5
  "addon": true,
6
6
  "engines": {
@@ -173,12 +173,10 @@
173
173
  },
174
174
  "types": "index.d.ts",
175
175
  "optionalDependencies": {
176
- "@qvac/audiogen-ggml-linux-x64": "0.4.0",
177
- "@qvac/audiogen-ggml-linux-arm64": "0.4.0",
178
- "@qvac/audiogen-ggml-darwin-arm64": "0.4.0",
179
- "@qvac/audiogen-ggml-darwin-x64": "0.4.0",
180
- "@qvac/audiogen-ggml-win32-x64": "0.4.0",
181
- "@qvac/audiogen-ggml-android-arm64": "0.4.0",
182
- "@qvac/audiogen-ggml-ios": "0.4.0"
176
+ "@qvac/audiogen-ggml-linux-x64": "0.5.0",
177
+ "@qvac/audiogen-ggml-linux-arm64": "0.5.0",
178
+ "@qvac/audiogen-ggml-darwin-arm64": "0.5.0",
179
+ "@qvac/audiogen-ggml-darwin-x64": "0.5.0",
180
+ "@qvac/audiogen-ggml-win32-x64": "0.5.0"
183
181
  }
184
182
  }