Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Media model registry — single source of truth for image/video model
* definitions and the text encoder used by the LTX video pipeline.
*
* On first load, seeds `data/media-models.json` with the project's default
* catalog. Edit that JSON to add models, tune steps/guidance, switch the
* text encoder, etc. Server restart picks up changes (the registry is
* cached at boot — there's no hot-reload).
*
* Schema (see seed defaults below for the full picture):
* - video.mlx[], video.cuda[]: { id, name, repo?, steps, guidance, broken?, disclosure?, hardwareRequirements? }
* The two buckets split on RUNTIME FAMILY, not operating system: `mlx`
* holds the Apple-MLX runtimes, `cuda` the plain torch+CUDA ones (which
* run on Windows AND Linux). They were keyed `macos` / `windows` before
* issue #4142; both spellings still load — see lib/mediaModelBuckets.js.
* Models may also declare `defaultWidth` / `defaultHeight`,
* `resolutionStep`, and `resolutionOptions[]` when their native canvas
* differs from the shared Video Gen presets.
* `repoFiles[]` (optional) narrows the model's OWN `repo` to an explicit
* list of repo-relative POSIX filenames, the way `requiredWeights[].files`
* already does for a secondary repo. Absent means "snapshot the whole
* repo", which is right for a repo that holds exactly one model. Declare
* it when the repo is an AGGREGATE holding more than the runner loads —
* `MiniMaxAI/MiniMax-H3` ships three layouts totalling ~498 GB where the
* CUDA runner needs ~144 GB of them — since the download, cache-status,
* integrity-verify and repair paths all fan out from the same
* `modelDownloadTargets()` in services/videoGen/modelCache.js and would
* otherwise pull and checksum the lot.
* `offloadProfile` (optional, `minimax_h3_cuda` only) pins the weight
* offload recipe to one of `auto` / `bf16` / `int8-stream` / `int8-lean`
* instead of letting the runner size one from the card's own VRAM. Left
* absent on the shipped entry deliberately: the registry syncs between
* peers and cannot know what GPU is on the other end. Validated in
* services/videoGen/local.js against MINIMAX_H3_CUDA_OFFLOAD_PROFILES.
* `memoryProfiles` (issue #5420) is the declared, capability-checked
* weight-placement table for the two MiniMax H3 entries — each profile's
* honest host-RAM and device-VRAM floor, best-first. Declared in
* lib/minimaxH3Memory.js and backfilled at load like `disclosure` and
* `speedProfiles`; the render path fails closed when no profile fits the
* measured machine, and the runners re-select on the same table.
* `disclosure` is optional provenance/licensing metadata (issue #3674):
* { modelCardUrl?, weightsLicense?: { name, url }, runtimeLicense?: { name, url },
* estimatedDownloadGb?, reviewedAt? }. Every key is optional and an
* absent key means "not established" — the UI renders it as Unknown
* rather than guessing. Canonical fields (repo/revision/runtime/memoryGb/
* supportedModes/requiredWeights/repoFiles) are NOT duplicated inside it. Shipped
* values live in lib/videoDisclosure.js and are backfilled at load.
* `finishModelId` (optional, issue #3696) names the delivery model a
* fast draft entry finishes into — declared in lib/videoFinishProfiles.js,
* backfilled at load, and validated (invalid edges are dropped, loudly).
* `supportedModes` (issue #3737) is resolved for EVERY entry by
* getVideoModels() from lib/videoModeProfiles.js's per-runtime table when
* the entry doesn't declare its own, so no consumer has to treat "absent"
* as "supports everything". A declared list always wins.
* - video.defaultMlx / video.defaultCuda: id of the default model
* (legacy `defaultMacos` / `defaultWindows` still read)
* - image[]: { id, name, steps, guidance, broken?, hardwareRequirements? }
* - textEncoders[]: { id, label, repo, localPath? }
* - selectedTextEncoder: id of the active text encoder
*/
import { MOSS_IMAGE_MODEL_ID } from './imageRuntimeRemedies.js';
import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, openSync, closeSync, rmSync } from 'fs';
import { join, dirname } from 'path';
import { randomUUID } from 'node:crypto';
import { PATHS, expandHome } from './fileUtils.js';
import { isPlainObject } from './objects.js';
import {
LEGACY_VIDEO_KEYS,
VIDEO_BUCKET_CUDA,
VIDEO_BUCKETS,
VIDEO_DEFAULT_KEYS,
activeVideoBucket,
matchesVideoBucket,
readVideoBucket,
readVideoDefault,
resolveVideoBucketKey,
} from './mediaModelBuckets.js';
import { RUNNER_FAMILIES } from './runners.js';
import { ServerError } from './errorHandler.js';
import { applyVideoDisclosures } from './videoDisclosure.js';
import { applyVideoFinishProfiles, sanitizeFinishProfiles } from './videoFinishProfiles.js';
import { applyVideoSpeedProfiles, sanitizeSpeedProfiles } from './videoSpeedProfiles.js';
import { applyVideoDraftDecoders, sanitizeDraftDecoders } from './videoDraftDecoders.js';
import { applyMiniMaxH3MemoryProfiles, sanitizeMiniMaxH3MemoryProfiles } from './minimaxH3Memory.js';
import { applyVideoSupportedModes } from './videoModeProfiles.js';
import { LTX25_AUDIO_PROFILE } from './videoDurationProfiles.js';
import {
captureSystemCapabilities,
hardwareRequirementsForMediaModel,
isHardwareCompatible,
withHardwareCompatibility,
} from './systemCapabilities.js';
import { isNonBlankStr } from './textUtils.js';
// fileUtils.ensureDir is async/Promise-returning; this module needs a
// synchronous version because `loadMediaModels()` is called at import-time
// from videoGen/imageGen modules, which can't await before exporting.
// Allow tests + non-standard deployments to point at a different file
// without monkey-patching PATHS. Defaults to data/media-models.json.
const REGISTRY_FILE = process.env.PORTOS_MEDIA_MODELS_FILE || join(PATHS.data, 'media-models.json');
// Migration 267 and the load-time normalizer share this exact shipped-profile
// contract. The load-time half is essential because route imports can cache the
// registry before bootstrap migrations run; a later registry edit would
// otherwise persist that stale object over the migrated file in the same boot.
// MiniMax H3's canvas contract — a property of the CHECKPOINT, so it is
// identical on the MLX port and the diffusers CUDA path. H3-Base was trained on
// a native 768px short edge; its canvas resolver caps area at 768x1344 and
// rounds each edge to 32px, and these are the exact outputs for the aspect
// ratios MiniMax documents. Both model entries spread this rather than restating
// it — `mediaModels.test.js` asserts they stay identical.
export const MINIMAX_H3_CANVAS = Object.freeze({
defaultWidth: 1344,
defaultHeight: 768,
resolutionStep: 32,
resolutionOptions: Object.freeze([
Object.freeze({ label: '1536x672 (21:9 H3 native)', w: 1536, h: 672 }),
Object.freeze({ label: '1344x768 (16:9 H3 default)', w: 1344, h: 768 }),
Object.freeze({ label: '1024x768 (4:3 H3 native)', w: 1024, h: 768 }),
Object.freeze({ label: '768x768 (1:1 H3 native)', w: 768, h: 768 }),
Object.freeze({ label: '768x1024 (3:4 H3 native)', w: 768, h: 1024 }),
Object.freeze({ label: '768x1344 (9:16 H3 native)', w: 768, h: 1344 }),
]),
});
// H3's video VAE decodes only frame counts on the 17n+5 grid, so every frame
// list PortOS ships is an arithmetic sequence stepping by 17 — the runners
// enforce the same modulus. Generated rather than typed out for the reason
// `shardFiles` below is: a single wrong digit among the ~45 literals these three
// lists would otherwise need is invisible in review and surfaces only as a
// rejected render, and the three lists could silently disagree about the grid.
const h3FrameGrid = (min, max) => {
const out = [];
for (let frames = min; frames <= max; frames += 17) out.push(frames);
return Object.freeze(out);
};
// FastH3 Preview v1's output contract (#5860). It is a distilled MiniMax H3, so
// it inherits H3's 17n+5 VAE frame grid and 32px edge rounding — but NOT H3's
// full frame range: the MLX pipeline hard-refuses anything outside 5-15 s at its
// fixed 24 fps ("H3 generates 5-15 s at 24 fps", resolve_geometry in
// fastvideo/mlx_runtime/minimax_h3_pipeline.py), so the grid is clamped to
// 120..360 frames. The unclamped 107..362 this shipped with put a too-short AND
// a too-long value at the two ends of the picker, each of which reached the
// runtime and raised instead of rendering.
// canvas: the MLX FastH3 entry point is validated at 832x480 (its own default,
// and the resolution upstream's conversion manifest records a passing 124-frame
// generation at), and its docstring documents 1280x720 as the other supported
// request. `resolutionOptions` are presets rather than a whitelist, so a custom
// size still resolves through `resolutionStep`.
export const FASTH3_OUTPUT_PROFILE = Object.freeze({
frameOptions: h3FrameGrid(124, 345),
fpsOptions: Object.freeze([24]),
resolutionStep: 32,
resolutionOptions: Object.freeze([
Object.freeze({ label: '832x480 (16:9 FastH3 default)', w: 832, h: 480 }),
Object.freeze({ label: '1280x720 (16:9 HD)', w: 1280, h: 720 }),
]),
});
// The upstream FastH3 source snapshot (#5860 follow-up). FastVideo's own MLX
// repos publish a model card and a conversion manifest but still no weights, so
// the checkpoint PortOS points at is the bf16 diffusers snapshot the converter
// documents as its input: one repo, whose `transformer/` becomes an MLX DiT on
// this machine. That is a per-format local step, not a per-format download —
// the three rows below share ONE snapshot and differ only in the format the
// helper converts it to, which is the knob that maps to the user's RAM.
export const FASTH3_SOURCE_REPO = 'FastVideo/FastVideo-FastH3-4-step-Preview-v1-Dense-DataFree';
export const FASTH3_SOURCE_REVISION = 'f624f08c6c279ab43534c003e556fc5b295b6558';
const FASTH3_SOURCE_FORMATS = Object.freeze([
Object.freeze({ format: 'int8', memoryGb: 48, label: 'INT8 (highest fidelity)' }),
Object.freeze({ format: 'int6', memoryGb: 42, label: 'INT6 (upstream default)' }),
Object.freeze({ format: 'int4', memoryGb: 36, label: 'INT4 (smallest)' }),
]);
const FASTH3_SOURCE_ENTRIES = FASTH3_SOURCE_FORMATS.map(({ format, memoryGb, label }) => ({
id: `fasth3_dense_datafree_${format}`,
name: `FastH3 Preview v1 Dense Data-Free — MLX ${label} (video + audio, ~144 GB download, ${memoryGb}+ GB RAM, 4-step)`,
repo: FASTH3_SOURCE_REPO,
revision: FASTH3_SOURCE_REVISION,
runtime: 'fastvideo',
fastvideoFamily: 'fasth3',
fastvideoMlxFormat: format,
supportedModes: ['text'],
defaultWidth: 832,
defaultHeight: 480,
defaultFrames: 124,
frameOptions: [...FASTH3_OUTPUT_PROFILE.frameOptions],
fpsOptions: [...FASTH3_OUTPUT_PROFILE.fpsOptions],
resolutionStep: FASTH3_OUTPUT_PROFILE.resolutionStep,
resolutionOptions: FASTH3_OUTPUT_PROFILE.resolutionOptions.map((preset) => ({ ...preset })),
memoryGb,
steps: 4,
guidance: 1.0,
samplerLocked: true,
samplerNote: `FastH3 Preview v1 is a 4-step DMD2 model. This is FastVideo's own dense-attention checkpoint — it does not support VSA, whose routing weights the MLX runtime drops. The first render converts its transformer to an MLX ${format.toUpperCase()} DiT (a few minutes, once), after which the 66 GB bf16 transformer can be deleted. Renders video with audio at a fixed 24 fps.`,
// Same argv boundary as the repack row below: mlx_fasth3.py has no
// --negative-prompt, no way to mute the joint audio track, and PortOS never
// hands it a tiling flag.
supportsNegativePrompt: false,
supportsTiling: false,
supportsDisableAudio: false,
}));
// The MLX entry's output profile: the shared canvas above PLUS the upgrade
// machinery migration 267 and `upgradeMiniMaxH3OutputControls` key off (the id,
// the repo it was checked against, and the frame list it supersedes). That
// upgrade half is specific to this one registry row, which is why the canvas is
// factored out rather than left tangled with it.
export const MINIMAX_H3_OUTPUT_PROFILE = Object.freeze({
id: 'minimax_h3_8bit',
shippedRepo: 'pipenetwork/MiniMax-H3-MLX-8bit',
oldFrameOptions: h3FrameGrid(124, 362),
frameOptions: h3FrameGrid(107, 362),
oldMlxSteps: 8,
mlxSteps: 9,
oldMlxSamplerNote: 'MiniMax H3 is CFG-distilled; this profile locks the validated 8-point sigma schedule and does not use CFG.',
mlxSamplerNote: 'MiniMax H3 is CFG-distilled; this profile locks the MLX reference 9-point sigma schedule (8 DiT forwards) and does not use CFG.',
...MINIMAX_H3_CANVAS,
});
// Expand one diffusers sharded-component file set. Written out rather than
// listed literally because these are 14- and 3-way shards whose names differ
// only by index — a hand-typed list is 30+ near-identical lines in which a
// single wrong digit is invisible in review and surfaces only as a failed
// cache resolve mid-render.
const shardFiles = (dir, stem, count) => Array.from(
{ length: count },
(_, i) => `${dir}/${stem}-${String(i + 1).padStart(5, '0')}-of-${String(count).padStart(5, '0')}.safetensors`,
);
// MiniMax H3 on CUDA loads through diffusers' `MiniMaxH3ModularPipeline`, whose
// `fl2va` workflow reads the `transformer/` partition plus the shared
// conditioner, VAEs, tokenizers and schedulers.
//
// This MUST stay an explicit file list rather than a repo snapshot.
// `MiniMaxAI/MiniMax-H3` is ~498 GB: it ships the diffusers layout enumerated
// here (~144 GB), the `transformer_ref/` partition for the `ref2va` workflow
// PortOS does not expose (~66 GB), and the ORIGINAL non-diffusers `FL2VA/` +
// `Ref2VA/` layouts (~144 GB each) that the MLX port consumes. A snapshot would
// pull 3.5x what the render path can use.
const MINIMAX_H3_CUDA_REPO_FILES = Object.freeze([
'LICENSE',
'modular_model_index.json',
'transformer/config.json',
'transformer/diffusion_pytorch_model.safetensors.index.json',
...shardFiles('transformer', 'diffusion_pytorch_model', 14),
'text_encoder/config.json',
'text_encoder/model.safetensors.index.json',
...shardFiles('text_encoder', 'model', 14),
'text_encoder/chat_template.json',
'text_encoder/merges.txt',
'text_encoder/preprocessor_config.json',
'text_encoder/tokenizer.json',
'text_encoder/tokenizer_config.json',
'text_encoder/video_preprocessor_config.json',
'text_encoder/vocab.json',
'vae/config.json',
'vae/diffusion_pytorch_model.safetensors.index.json',
...shardFiles('vae', 'diffusion_pytorch_model', 3),
'audio_vae/config.json',
'audio_vae/diffusion_pytorch_model.safetensors',
// The Qwen3-VL processor/tokenizer pair the keyframe (image / FFLF) path
// runs conditioning images through. ~20 MB, so it rides along rather than
// becoming a second opt-in pull the way a multi-GB component would.
'processor/chat_template.json',
'processor/merges.txt',
'processor/preprocessor_config.json',
'processor/tokenizer.json',
'processor/tokenizer_config.json',
'processor/video_preprocessor_config.json',
'processor/vocab.json',
'tokenizer/merges.txt',
'tokenizer/tokenizer.json',
'tokenizer/tokenizer_config.json',
'tokenizer/vocab.json',
'scheduler/scheduler_config.json',
'audio_scheduler/scheduler_config.json',
]);
const LTX25_CUDA_REPO_FILES = Object.freeze([
'diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors',
'text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors',
'vae/ltx-2.5-video-vae-bf16.safetensors',
'vae/ltx-2.5-audio-vae-bf16.safetensors',
'model_patches/ltx-2.5-duration-head-bf16.safetensors',
'latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors',
]);
// The diffusers integration's duration window, which is NARROWER than the MLX
// port's at both ends: frames are snapped up to the next 17n+5 and the RESULTING
// duration must land in 5-15 s, so 107 (4.46 s) is under the floor and 362
// (15.08 s) is over the ceiling. Mirrored by MIN_FRAMES / MAX_FRAMES in
// scripts/generate_minimax_h3_cuda.py, which rejects the same values.
const MINIMAX_H3_CUDA_FRAME_OPTIONS = h3FrameGrid(124, 345);
const sameValues = (left, right) => (
Array.isArray(left)
&& left.length === right.length
&& left.every((value, index) => value === right[index])
);
const upgradeMiniMaxH3DenoisingCountEntry = (entry, profile) => {
if (!isPlainObject(entry) || entry.id !== profile.id || entry.repo !== profile.shippedRepo) return entry;
// The MLX port treats `steps` as sigma-grid points, with the terminal zero
// excluded from transformer evaluation. The old shipped value therefore
// ran seven forwards, while the reference quality example uses nine grid
// points for eight forwards. Preserve a hand-tuned sampler contract.
const samplerIsLegacyShipped = entry.steps === profile.oldMlxSteps
&& (!Object.hasOwn(entry, 'guidance') || entry.guidance === 0)
&& (!Object.hasOwn(entry, 'samplerLocked') || entry.samplerLocked === true)
&& (!Object.hasOwn(entry, 'samplerNote') || entry.samplerNote === profile.oldMlxSamplerNote);
return samplerIsLegacyShipped
? { ...entry, steps: profile.mlxSteps, samplerNote: profile.mlxSamplerNote }
: entry;
};
export const upgradeMiniMaxH3DenoisingCount = (list) => {
if (!Array.isArray(list)) return list;
const profile = MINIMAX_H3_OUTPUT_PROFILE;
return list.map((entry) => upgradeMiniMaxH3DenoisingCountEntry(entry, profile));
};
export const upgradeMiniMaxH3OutputControls = (list) => {
if (!Array.isArray(list)) return list;
const profile = MINIMAX_H3_OUTPUT_PROFILE;
const withGeometry = list.map((entry) => {
if (!isPlainObject(entry) || entry.id !== profile.id || entry.repo !== profile.shippedRepo) return entry;
let next = entry;
if (sameValues(next.frameOptions, profile.oldFrameOptions)) {
next = { ...next, frameOptions: [...profile.frameOptions] };
}
if (!Object.hasOwn(next, 'defaultWidth') && !Object.hasOwn(next, 'defaultHeight')) {
next = { ...next, defaultWidth: profile.defaultWidth, defaultHeight: profile.defaultHeight };
}
// The step and presets describe one geometry contract. If either side was
// customized, preserve the pair rather than installing presets that may be
// off-grid for the user's declared step (or vice versa).
if (!Object.hasOwn(next, 'resolutionStep') && !Object.hasOwn(next, 'resolutionOptions')) {
next = {
...next,
resolutionStep: profile.resolutionStep,
resolutionOptions: profile.resolutionOptions.map((preset) => ({ ...preset })),
};
}
return next;
});
return upgradeMiniMaxH3DenoisingCount(withGeometry);
};
// FastMetal 14B ships its MLX DiT TWICE — `mlx_dit.safetensors` at the repo
// root and an `ema/` copy of the same 14.14 GB tensor. The render path reads
// only the root one: scripts/generate_fastvideo.py defaults `mlx_checkpoint`
// to the model root for the fastmetal family and ALWAYS forwards it, so
// mlx_wan_prompt_to_video.py takes `resolve_mlx_checkpoint`'s explicit branch
// and loads `mlx_dit.json` + `mlx_dit.safetensors` from that one directory.
// Nothing on that path names `ema/` — the `ema/*` entries in the entry
// script's own `allow_patterns` belong to its download helper, which PortOS
// bypasses by passing an explicit `--model-root`.
//
// Enumerating the loaded set therefore drops 14.14 GB from the pull without
// changing a single byte the render path reads.
//
// Listed rather than expressed as an "everything but ema/" exclusion because
// `repoFiles` is the only narrowing the download path has (see
// `modelDownloadTargets`), and an explicit list is also what the cache
// completeness check verifies. `.gitattributes` and `README.md` are omitted:
// nothing loads them, and a file in this list that upstream later drops would
// read as an incomplete download.
const FASTMETAL_14B_REPO_FILES = Object.freeze([
'model_index.json',
'mlx_dit.json',
'mlx_dit.safetensors',
'scheduler/scheduler_config.json',
'text_encoder/config.json',
'text_encoder/model.safetensors.index.json',
...shardFiles('text_encoder', 'model', 5),
'tokenizer/special_tokens_map.json',
'tokenizer/spiece.model',
'tokenizer/tokenizer.json',
'tokenizer/tokenizer_config.json',
'vae/config.json',
'vae/diffusion_pytorch_model.safetensors',
]);
// The three shipped FastMetal rows quote a download size in their DISPLAY NAME
// that is only the MLX DiT, while the entries pull a whole-repo snapshot that
// also carries a bundled T5 text encoder and VAE — so a user reading "~3.5 GB"
// was handed a 13.4 GB pull (#5871). #5860 corrected `estimatedDownloadGb` in
// the disclosure panel; the name is the number the user reads BEFORE opening
// that panel, so it is what these profiles correct.
//
// `oldName` / `oldEstimatedDownloadGb` are the exact superseded SHIPPED values:
// each rewrite fires only when the persisted value still matches one of them, so
// a user's own rename or hand-tuned estimate survives untouched. Same shape as
// MINIMAX_H3_OUTPUT_PROFILE's upgrade half — keyed on (id, shipped repo, prior
// shipped value).
//
// `oldEstimatedDownloadGb` carries TWO generations because #5860 shipped no
// migration: an install that persisted its disclosure before it still reads the
// DiT-only figure, and one that seeded after reads the whole-snapshot figure the
// 14B row no longer pulls.
export const FASTMETAL_DOWNLOAD_SIZE_PROFILES = Object.freeze([
Object.freeze({
id: 'fastmetal_1_3b_qad',
shippedRepo: 'FastVideo/FastMetal-1.3B-QAD',
oldName: 'FastMetal 1.3B QAD (~3.5 GB download, 8+ GB RAM, 3-step)',
name: 'FastMetal 1.3B QAD (~13.4 GB download, 8+ GB RAM, 3-step)',
oldEstimatedDownloadGb: Object.freeze([3.5]),
estimatedDownloadGb: 13.4,
}),
Object.freeze({
id: 'fastmetal_5b_qad',
shippedRepo: 'FastVideo/FastMetal-5B-QAD',
oldName: 'FastMetal 5B QAD (~10 GB download, 16+ GB RAM, 3-step)',
name: 'FastMetal 5B QAD (~19.5 GB download, 16+ GB RAM, 3-step)',
oldEstimatedDownloadGb: Object.freeze([10.2]),
estimatedDownloadGb: 19.5,
}),
// The 14B repo ships the DiT twice — `mlx_dit.safetensors` and an `ema/` copy
// of it, 14.14 GB each — and the entry script loads only the root one, so
// `repoFiles` drops the `ema/` half. That makes this row's honest number the
// narrowed 27.1 GB pull rather than the 42.3 GB whole snapshot. Every name
// here quotes its `estimatedDownloadGb` verbatim — the whole bug was the two
// disagreeing, so they are not allowed to round apart.
Object.freeze({
id: 'fastmetal_14b_qad',
shippedRepo: 'FastVideo/FastMetal-14B-QAD',
oldName: 'FastMetal 14B QAD (~25 GB download, 36+ GB RAM, 3-step)',
name: 'FastMetal 14B QAD (~27.1 GB download, 36+ GB RAM, 3-step)',
oldEstimatedDownloadGb: Object.freeze([25.4, 42.3]),
estimatedDownloadGb: 27.1,
repoFiles: FASTMETAL_14B_REPO_FILES,
}),
]);
const upgradeFastMetalEntry = (entry, profile) => {
if (!isPlainObject(entry) || entry.id !== profile.id || entry.repo !== profile.shippedRepo) return entry;
let next = entry;
// Only the untouched shipped string is rewritten — a user rename is theirs.
if (next.name === profile.oldName) next = { ...next, name: profile.name };
// The file list is additive and only lands on a row that declares none: an
// entry already carrying `repoFiles` has a narrowing its owner chose.
if (profile.repoFiles && !Object.hasOwn(next, 'repoFiles')) {
next = { ...next, repoFiles: [...profile.repoFiles] };
}
// A row that persisted its disclosure before this correction keeps a stale
// size that would now contradict the name beside it. applyVideoDisclosures
// only fills an ABSENT block, so the stale one is corrected here — and only
// when it still equals a value PortOS itself shipped.
if (isPlainObject(next.disclosure)
&& profile.oldEstimatedDownloadGb.includes(next.disclosure.estimatedDownloadGb)) {
next = {
...next,
disclosure: { ...next.disclosure, estimatedDownloadGb: profile.estimatedDownloadGb },
};
}
return next;
};
/**
* Bring the shipped FastMetal rows onto the size their download actually pulls
* — in the display name and in any stale persisted disclosure — and narrow the
* 14B row off its duplicated `ema/` DiT.
*
* Load-time twin of migration 336: the registry cache is populated before
* migrations execute, so the boot that runs the migration still needs this.
*/
export const upgradeFastMetalDownloadSizes = (list) => {
if (!Array.isArray(list)) return list;
return list.map((entry) => FASTMETAL_DOWNLOAD_SIZE_PROFILES.reduce(upgradeFastMetalEntry, entry));
};
const FASTH3_V2_MODE_REPO = 'FastVideo/FastVideo-FastH3-8-Step-V2';
const FASTH3_V2_MODE_REVISION = '3da2ddfe1954d9cda4c05b643dc0f26007a655c5';
const FASTH3_V2_MODE_IDS = new Set(['fasth3_v2_int8', 'fasth3_v2_int6']);
// The pinned MLX entry and pipeline have no image-conditioning API. Correct
// the exact erroneous shipped declaration while preserving repointed forks,
// custom IDs, and other explicit mode lists.
export const upgradeFastH3V2RuntimeModes = (list) => {
if (!Array.isArray(list)) return list;
return list.map((entry) => {
if (!isPlainObject(entry)
|| !FASTH3_V2_MODE_IDS.has(entry.id)
|| entry.repo !== FASTH3_V2_MODE_REPO
|| entry.revision !== FASTH3_V2_MODE_REVISION
|| JSON.stringify(entry.supportedModes) !== JSON.stringify(['text', 'image'])) return entry;
return { ...entry, supportedModes: ['text'] };
});
};
// Existing installs already persisted the shipped LTX-2.5 row before its A2V
// duration contract was declared. Backfill only the untouched pinned model and
// only absent keys: a user-repointed fork or an explicit local override remains
// authoritative. Migration 318 persists the same fields, while this load-time
// twin matters on the boot that runs the migration because the registry cache is
// populated before migrations execute.
export const upgradeLtx25AudioControls = (list) => {
if (!Array.isArray(list)) return list;
return list.map((entry) => {
if (!isPlainObject(entry)
|| entry.id !== LTX25_AUDIO_PROFILE.id
|| entry.repo !== LTX25_AUDIO_PROFILE.repo
|| entry.revision !== LTX25_AUDIO_PROFILE.revision) return entry;
const missing = ['audioDurationDriven', 'frameStride', 'maxNumFrames']
.filter((key) => !Object.hasOwn(entry, key));
return missing.length === 0
? entry
: { ...entry, ...Object.fromEntries(missing.map((key) => [key, LTX25_AUDIO_PROFILE[key]])) };
});
};
const DEFAULT_REGISTRY = {
_doc: 'PortOS media model registry. Edit to add models, tune defaults, or switch the text encoder. Restart the server to apply changes.',
video: {
// `applyVideoDisclosures` attaches the shipped provenance/licensing block
// (lib/videoDisclosure.js) to each entry, so the seed written on a fresh
// install and the in-memory defaults carry the same disclosure without repeating it inline here.
// `applyVideoFinishProfiles` attaches the shipped draft → delivery
// `finishModelId` edges (lib/videoFinishProfiles.js) the same way, so the
// Finish relationship is declared in one place instead of inline here.
// `applyVideoSpeedProfiles` (lib/videoSpeedProfiles.js) is the third such
// decorator: it attaches the shipped `speedProfiles` a model offers, pin-
// guarded on repo AND revision so a re-pointed entry keeps no schedule
// claim we can't back. `applyVideoDraftDecoders`
// (lib/videoDraftDecoders.js) is the fourth, attaching the separately
// downloaded preview-fidelity decoder a model can render drafts on.
mlx: applyMiniMaxH3MemoryProfiles(applyVideoDraftDecoders(applyVideoSpeedProfiles(applyVideoFinishProfiles(applyVideoDisclosures([
// notapalindrome's mlx-video-with-audio runtime — single PyPI package,
// T2V/I2V only, FFLF degrades to last-frame conditioning (one --image arg).
// LTX-2 Unified (the older 42 GB model) was retired in favour of 2.3 —
// see RETIRED_VIDEO_MODELS. 2.3 Unified bf16 is the quality ceiling for
// the mlx_video runtime and is practical on 128 GB unified-memory
// hardware, while Distilled Q4 is both smaller and better than LTX-2 was,
// and stays the shipped default because it works on smaller boxes.
{ id: 'ltx23_unified', name: 'LTX-2.3 Unified Beta (~48 GB, bf16 quality ceiling)', repo: 'notapalindrome/ltx23-mlx-av', runtime: 'mlx_video', steps: 25, guidance: 3.0 },
{ id: 'ltx23_distilled_q4', name: 'LTX-2.3 Distilled Q4 (~22 GB)', repo: 'notapalindrome/ltx23-mlx-av-q4', runtime: 'mlx_video', steps: 25, guidance: 3.0 },
// dgrauet's ltx-2-mlx runtime — true KeyframeInterpolationPipeline,
// native video Extend, audio→video. Requires a separate venv synced
// via `INSTALL_LTX2=1 bash scripts/setup-image-video.sh`.
{ id: 'ltx23_dgrauet_q4', name: 'LTX-2.3 dgrauet Q4 (~16 GB, true keyframes)', repo: 'dgrauet/ltx-2.3-mlx-q4', runtime: 'ltx2', steps: 8, guidance: 3.0 },
{ id: 'ltx23_dgrauet_q8', name: 'LTX-2.3 dgrauet Q8 (~25 GB, true keyframes)', repo: 'dgrauet/ltx-2.3-mlx-q8', runtime: 'ltx2', steps: 8, guidance: 3.0 },
// LTX-2.5 Q8 on MrMofer's ltx25 fork of dgrauet/ltx-2-mlx. The 2.3 pin
// cannot load these weights; INSTALL_LTX25 provisions a sibling venv.
{
id: 'ltx25_mlx_q8',
name: 'LTX-2.5 MLX Q8 (~68 GB, Apple Silicon)',
repo: 'MrMofer/ltx-2.5-mlx-q8',
revision: 'f1b56e7dc89f71a9af2cddac787b89ed22a8b7fc',
runtime: 'ltx25',
// A2V accepts an optional frame-one image. PortOS probes a direct audio
// upload and rounds its full duration up to the LTX 8n+1 grid. 1017 is
// the highest legal count under the route's 1024-frame single-pass cap.
audioDurationDriven: true,
frameStride: 8,
maxNumFrames: 1017,
steps: 8,
guidance: 3.0,
},
// MiniMax H3 joint video+audio through PipeNetwork's pinned MLX port.
// The quantized DiT is one HF snapshot; the released conditioner + VAEs
// are an exact selective file set from MiniMax's upstream snapshot. Both
// downloads are explicit in Video Gen, and render-time resolution is
// cache-only. The server-owned disclosure attaches the mandatory,
// versioned territory/license acceptance gate.
...[
{ bits: 8, revision: '3ac52081470b0488921c3ec3ba84a39097bf2361' },
{ bits: 6, revision: '58ea790a856734132293164b8305c8bb80bee6fe' },
{ bits: 4, revision: '95a0e7d97f23f8b0029afea9411f13535262d935' },
].map(({ bits, revision }) => ({
runtime: 'minimax_h3',
// H3 is an fl2va model: it conditions on up to two keyframes anchored
// at the first / last latent frame. 'image' anchors one at 'first',
// 'fflf' anchors both.
supportedModes: ['text', 'image', 'fflf'],
// The upstream model supports 4-15 seconds. H3's VAE snaps duration
// UP to a 17n+5 frame grid, so 4s becomes 107 frames and the port's
// recommended 5s default becomes 124. Keep the shortest recommended
// run as the default: dense attention already makes it a multi-hour
// render on current Apple Silicon.
defaultFrames: 124,
frameOptions: [...MINIMAX_H3_OUTPUT_PROFILE.frameOptions],
fpsOptions: [24],
// The checkpoint's canvas contract, shared verbatim with the CUDA entry.
...MINIMAX_H3_CANVAS,
resolutionOptions: MINIMAX_H3_CANVAS.resolutionOptions.map((preset) => ({ ...preset })),
memoryGb: 128,
steps: MINIMAX_H3_OUTPUT_PROFILE.mlxSteps,
guidance: 0,
samplerLocked: true,
samplerNote: MINIMAX_H3_OUTPUT_PROFILE.mlxSamplerNote,
supportsNegativePrompt: false,
supportsTiling: false,
supportsDisableAudio: false,
requiredWeights: [{
repo: 'MiniMaxAI/MiniMax-H3',
revision: '6818f6c32d12b210915e44ad56a4228c2608f160',
files: [
'LICENSE',
'FL2VA/model_index.json',
'FL2VA/audio_vae/config.json',
'FL2VA/audio_vae/metadata.json',
'FL2VA/audio_vae/model.safetensors',
'FL2VA/text_encoder/config.json',
'FL2VA/text_encoder/model-00001-of-00014.safetensors',
'FL2VA/text_encoder/model-00002-of-00014.safetensors',
'FL2VA/text_encoder/model-00003-of-00014.safetensors',
'FL2VA/text_encoder/model-00004-of-00014.safetensors',
'FL2VA/text_encoder/model-00005-of-00014.safetensors',
'FL2VA/text_encoder/model-00006-of-00014.safetensors',
'FL2VA/text_encoder/model-00007-of-00014.safetensors',
'FL2VA/text_encoder/model-00008-of-00014.safetensors',
'FL2VA/text_encoder/model-00009-of-00014.safetensors',
'FL2VA/text_encoder/model-00010-of-00014.safetensors',
'FL2VA/text_encoder/model-00011-of-00014.safetensors',
// The pinned port truncates Qwen3-VL at layer 50. Index shards
// 12/13 contain only layers 53-63 and are intentionally omitted;
// shard 14 remains necessary for the final norm tensor.
'FL2VA/text_encoder/model-00014-of-00014.safetensors',
'FL2VA/text_encoder/model.safetensors.index.json',
// Keyframe conditioning runs each image through the Qwen3-VL
// processor (AutoProcessor reads the `processor/` directory, not
// `tokenizer/`) before the vision tower, whose weights already ride
// along in shard 14. ~11 MB total, so it stays in the base download
// rather than becoming a second opt-in pull.
'FL2VA/processor/chat_template.json',
'FL2VA/processor/merges.txt',
'FL2VA/processor/preprocessor_config.json',
'FL2VA/processor/tokenizer.json',
'FL2VA/processor/tokenizer_config.json',
'FL2VA/processor/video_preprocessor_config.json',
'FL2VA/processor/vocab.json',
'FL2VA/tokenizer/merges.txt',
'FL2VA/tokenizer/tokenizer.json',
'FL2VA/tokenizer/tokenizer_config.json',
'FL2VA/tokenizer/vocab.json',
'FL2VA/video_vae/config.json',
'FL2VA/video_vae/source/config.json',
'FL2VA/video_vae/source/model.safetensors',
],
}],
id: `minimax_h3_${bits}bit`,
name: `MiniMax H3 MLX ${bits}-bit (reference quality, very slow, 128 GB RAM)`,
repo: `pipenetwork/MiniMax-H3-MLX-${bits}bit`,
revision,
})),
// MiniMax H3 Ref2VA through the signed mere.run native runtime. The
// checkpoint accepts at most 15 seconds of reference audio per call;
// PortOS chains those windows and remuxes the exact source audio so the
// user-facing mode has no arbitrary duration cap.
{
id: 'minimax_h3_ref2va_8bit',
name: 'MiniMax H3 Ref2VA MLX 8-bit (image + arbitrary-length audio, ~71 GB, 128 GB RAM)',
repo: 'Sawfwair/MiniMax-H3-Ref2VA-MLX-8bit',
revision: '61dc387ef1a7166425cdacd63c2340598dcc364f',
runtime: 'minimax_h3_ref2va',
supportedModes: ['a2v'],
requiresSourceImageForA2v: true,
audioDurationDriven: true,
arbitraryLengthAudio: true,
maxReferenceAudioSeconds: 15,
defaultFrames: 124,
frameOptions: [...MINIMAX_H3_OUTPUT_PROFILE.frameOptions],
fpsOptions: [24],
defaultWidth: 512,
defaultHeight: 320,
resolutionStep: 32,
resolutionOptions: [
{ label: '512x320 (draft)', w: 512, h: 320 },
{ label: '768x480', w: 768, h: 480 },
{ label: '1024x640', w: 1024, h: 640 },
{ label: '768x768 (1:1)', w: 768, h: 768 },
],
memoryGb: 128,
steps: 9,
guidance: 0,
samplerLocked: true,
samplerNote: 'MiniMax H3 Ref2VA is CFG-distilled. PortOS renders audio in up-to-15-second continuity-linked windows, then restores the exact source audio over the final video.',
supportsNegativePrompt: false,
supportsTiling: false,
supportsDisableAudio: false,
},
// Wan 2.2 through pinned MLX-Gen. Generation is cache-only: PortOS owns
// the explicit base/adaptor downloads and uses the saved HF token.
{
id: 'wan22_ti2v_5b',
name: 'Wan 2.2 TI2V 5B Q8 (~17 GiB download, text + image)',
repo: 'AbstractFramework/wan2.2-ti2v-5b-diffusers-8bit',
revision: '6875952a110b6bdbcfc00d72b1d89a8e02ab0fc3',
runtime: 'wan22',
supportedModes: ['text', 'image'],
frameStride: 4,
fpsOptions: [16, 20, 24],
memoryGb: 24,
steps: 25,
guidance: 5.0,
flowShift: 3.0,
solver: 'unipc',
},
{
id: 'wan22_t2v_a14b',
name: 'Wan 2.2 T2V A14B Q8 (~40 GiB download, 64+ GB RAM)',
repo: 'AbstractFramework/wan2.2-t2v-a14b-diffusers-8bit',
revision: '39ee5f1f630789956f29f40b5c2c6d48c6e9a798',
runtime: 'wan22',
supportedModes: ['text'],
frameStride: 4,
fpsOptions: [16, 20, 24],
memoryGb: 48,
steps: 20,
guidance: 4.0,
guidance2: 3.0,
flowShift: 3.0,
solver: 'unipc',
},
{
id: 'wan22_i2v_a14b',
name: 'Wan 2.2 I2V A14B Q8 (~40 GiB download, 64+ GB RAM)',
repo: 'AbstractFramework/wan2.2-i2v-a14b-diffusers-8bit',
revision: '1a17fbea2649c576de844e08e79fe56296751efa',
runtime: 'wan22',
supportedModes: ['image'],
frameStride: 4,
fpsOptions: [16, 20, 24],
memoryGb: 48,
steps: 20,
guidance: 3.5,
guidance2: 3.5,
flowShift: 3.0,
solver: 'unipc',
},
{
id: 'wan22_t2v_a14b_lightning',
name: 'Wan 2.2 T2V A14B Lightning Q8 (~40 GiB download, 64+ GB RAM, 4-step)',
repo: 'AbstractFramework/wan2.2-t2v-a14b-diffusers-8bit',
revision: '39ee5f1f630789956f29f40b5c2c6d48c6e9a798',
runtime: 'wan22',
supportedModes: ['text'],
frameStride: 4,
fpsOptions: [16, 20, 24],
memoryGb: 48,
steps: 4,
guidance: 1.0,
guidance2: 1.0,
flowShift: 5.0,
solver: 'euler',
samplerLocked: true,
requiredWeights: [{
repo: 'lightx2v/Wan2.2-Lightning',
revision: '18bccf8884ec0a078eed79785eb4ef13ea16ce1e',
files: [
'Wan2.2-T2V-A14B-4steps-lora-rank64-Seko-V1.1/high_noise_model.safetensors',
'Wan2.2-T2V-A14B-4steps-lora-rank64-Seko-V1.1/low_noise_model.safetensors',
],
targetRoles: ['high_noise_transformer', 'low_noise_transformer'],
}],
},
{
id: 'wan22_i2v_a14b_lightning',
name: 'Wan 2.2 I2V A14B Lightning Q8 (~40 GiB download, 64+ GB RAM, 4-step)',
repo: 'AbstractFramework/wan2.2-i2v-a14b-diffusers-8bit',
revision: '1a17fbea2649c576de844e08e79fe56296751efa',
runtime: 'wan22',
supportedModes: ['image'],
frameStride: 4,
fpsOptions: [16, 20, 24],
memoryGb: 48,
steps: 4,
guidance: 1.0,
guidance2: 1.0,
flowShift: 5.0,
solver: 'euler',
samplerLocked: true,
requiredWeights: [{
repo: 'lightx2v/Wan2.2-Lightning',
revision: '18bccf8884ec0a078eed79785eb4ef13ea16ce1e',
files: [
'Wan2.2-I2V-A14B-4steps-lora-rank64-Seko-V1/high_noise_model.safetensors',
'Wan2.2-I2V-A14B-4steps-lora-rank64-Seko-V1/low_noise_model.safetensors',
],
targetRoles: ['high_noise_transformer', 'low_noise_transformer'],
}],
},
// FastVideo FastMetal models — Hao AI Lab's distilled DMD2 Wan models
// with affine INT8 quantization on Apple Silicon MLX. The download size
// in each name is the WHOLE snapshot (bundled T5 text encoder and VAE
// included), not the MLX DiT alone — see FASTMETAL_DOWNLOAD_SIZE_PROFILES.
{
id: 'fastmetal_1_3b_qad',
name: 'FastMetal 1.3B QAD (~13.4 GB download, 8+ GB RAM, 3-step)',
repo: 'FastVideo/FastMetal-1.3B-QAD',
runtime: 'fastvideo',
supportedModes: ['text'],
defaultWidth: 832,
defaultHeight: 480,
defaultFrames: 81,
memoryGb: 8,
steps: 3,
guidance: 1.0,
samplerLocked: true,
samplerNote: 'FastMetal models are DMD2-distilled 3-step models with affine INT8 quantization.',
},
{
id: 'fastmetal_5b_qad',
name: 'FastMetal 5B QAD (~19.5 GB download, 16+ GB RAM, 3-step)',
repo: 'FastVideo/FastMetal-5B-QAD',
runtime: 'fastvideo',
supportedModes: ['text'],
defaultWidth: 1280,
defaultHeight: 720,
defaultFrames: 81,
memoryGb: 16,
steps: 3,
guidance: 1.0,
samplerLocked: true,
samplerNote: 'FastMetal models are DMD2-distilled 3-step models with affine INT8 quantization.',
},
{
id: 'fastmetal_14b_qad',
name: 'FastMetal 14B QAD (~27.1 GB download, 36+ GB RAM, 3-step)',
repo: 'FastVideo/FastMetal-14B-QAD',
// Drops the duplicated `ema/` DiT the entry script never loads (#5871).
repoFiles: [...FASTMETAL_14B_REPO_FILES],
runtime: 'fastvideo',
supportedModes: ['text'],
defaultWidth: 1280,
defaultHeight: 720,
defaultFrames: 81,
memoryGb: 36,
steps: 3,
guidance: 1.0,
samplerLocked: true,
samplerNote: 'FastMetal models are DMD2-distilled 3-step models with affine INT8 quantization.',
},
// FastVideo's own FastH3 Dense / Data-Free snapshot, converted to MLX on
// this machine. Listed before the third-party repack below because it is
// the upstream checkpoint the repack is derived from.
...FASTH3_SOURCE_ENTRIES,
// Convert the official V2 snapshot locally, retaining its VSA routing weights.
...FASTH3_SOURCE_ENTRIES.filter((entry) => entry.fastvideoMlxFormat !== 'int4').map((entry) => ({
...entry,
id: `fasth3_v2_${entry.fastvideoMlxFormat}`,
name: `FastH3 8-Step V2 — MLX ${entry.fastvideoMlxFormat.toUpperCase()} + VSA (quality, local conversion)`,
repo: 'FastVideo/FastVideo-FastH3-8-Step-V2',
revision: '3da2ddfe1954d9cda4c05b643dc0f26007a655c5',
fastvideoVsa: true,
supportedModes: ['text'],
steps: 8,
samplerNote: 'Quality option: 8 steps with 80% sparse attention, reference implementation. Requires an updated FastVideo runtime with VSA support. INT6 and INT8 share one ~147.9 GB source download; first use converts the DiT locally with routing weights retained. Not a real-time model.',
})),
// FastH3 Preview v1 Dense / Data-Free, packed for MLX (#5860). Same
// `fastvideo` venv and checkout as FastMetal above, but a different entry
// script and argv shape — `fastvideoFamily` is what routes it, see
// buildFastVideoArgs. Text-to-video-WITH-AUDIO: the runner muxes H.264 at
// a fixed 24 fps with 32 kHz stereo AAC, which is why `fpsOptions` offers
// that one value rather than letting the form ask for a rate the entry
// script has no flag to accept.
// The DiT arrives pre-quantized, so nothing is converted on first render.
{
id: 'fasth3_dense_datafree_mlx_int4',
name: 'FastH3 Preview v1 Dense Data-Free MLX INT4 (video + audio, ~89 GB download, 36+ GB RAM, 4-step)',
repo: 'MrMofer/FastVideo-FastH3-4-step-Preview-v1-Dense-DataFree-MLX-INT4',
revision: '4c8c3e54da8cd667b5db10f6074b4cb9b7559f15',
runtime: 'fastvideo',
fastvideoFamily: 'fasth3',
supportedModes: ['text'],
defaultWidth: 832,
defaultHeight: 480,
defaultFrames: 124,
frameOptions: [...FASTH3_OUTPUT_PROFILE.frameOptions],
fpsOptions: [...FASTH3_OUTPUT_PROFILE.fpsOptions],
resolutionStep: FASTH3_OUTPUT_PROFILE.resolutionStep,
resolutionOptions: FASTH3_OUTPUT_PROFILE.resolutionOptions.map((preset) => ({ ...preset })),
memoryGb: 36,
steps: 4,
guidance: 1.0,
samplerLocked: true,
samplerNote: 'FastH3 Preview v1 is a 4-step DMD2 model. This export is dense-attention only — it does not support VSA. Renders video with audio at a fixed 24 fps.',
// mlx_fasth3.py takes no --negative-prompt, exposes no way to mute the
// joint audio track, and PortOS never passes it a tiling flag. Declaring
// each `false` is what removes the control from the form rather than
// offering a knob whose value is silently dropped at the argv boundary.
supportsNegativePrompt: false,
supportsTiling: false,
supportsDisableAudio: false,
},
]))))),
cuda: applyMiniMaxH3MemoryProfiles(applyVideoDraftDecoders(applyVideoSpeedProfiles(applyVideoFinishProfiles(applyVideoDisclosures([
{ id: 'ltx_video', name: 'LTX-Video 0.9.5 — T2V + I2V (~9.5 GB, auto-downloads)', runtime: 'cuda_video', steps: 25, guidance: 3.0 },
{
id: 'ltx25_cuda_distilled',
name: 'LTX-2.5 CUDA Distilled (joint video + audio, ~72 GB download, streamed)',
repo: 'Lightricks/LTX-2.5',
revision: 'bf86adedf518142442575d1ce2e767b7d01c8c76',
repoFiles: [...LTX25_CUDA_REPO_FILES],
runtime: 'ltx25_cuda',
supportedModes: ['text', 'image'],
defaultFrames: 121,
resolutionStep: 64,
fpsOptions: [24],
steps: 8,
guidance: 1.0,
samplerLocked: true,
samplerNote: 'LTX-2.5 Distilled uses the official fixed 8-step, CFG-free schedule.',
supportsNegativePrompt: false,
supportsTiling: false,
supportsDisableAudio: true,
requiresHfToken: true,
hardwareRequirements: { minMemoryGb: 64, minVramGb: 16, minCudaComputeCapability: 8 },
},
{
id: 'wan22_cuda_ti2v_5b',
name: 'Wan 2.2 TI2V 5B CUDA (high quality, ~34 GB download, text-to-video)',
repo: 'Wan-AI/Wan2.2-TI2V-5B-Diffusers',
revision: 'b8fff7315c768468a5333511427288870b2e9635',
runtime: 'wan22_cuda',
supportedModes: ['text'],
defaultWidth: 1280,
defaultHeight: 704,
resolutionStep: 16,
defaultFrames: 121,
frameStride: 4,
fpsOptions: [24],
steps: 50,
guidance: 5,
supportsNegativePrompt: true,
supportsTiling: false,
hardwareRequirements: { minMemoryGb: 32, minVramGb: 24, minCudaComputeCapability: 8 },
},
// MiniMax H3 on NVIDIA, through diffusers' MiniMaxH3ModularPipeline —
// the same joint video+audio model the MLX list runs on Apple Silicon, so it
// shares H3's canvas grid, its fixed 24 fps, its locked CFG-distilled
// sampler and the same license gate. Generation is cache-only: PortOS
// owns the explicit file-list download (see MINIMAX_H3_CUDA_REPO_FILES —
// never a snapshot of this repo) and the runtime is provisioned only
// after the user selects Install in Video Gen.
{
id: 'minimax_h3_cuda',
name: 'MiniMax H3 CUDA int8 (joint video + audio, ~144 GB download, 24 GB VRAM + 96 GB RAM)',
repo: 'MiniMaxAI/MiniMax-H3',
revision: '42ed227ee7df40d41602854ae760620d6eb651fe',
repoFiles: [...MINIMAX_H3_CUDA_REPO_FILES],
runtime: 'minimax_h3_cuda',
supportedModes: ['text', 'image', 'fflf'],
defaultFrames: 124,
frameOptions: [...MINIMAX_H3_CUDA_FRAME_OPTIONS],
fpsOptions: [24],
...MINIMAX_H3_CANVAS,
resolutionOptions: MINIMAX_H3_CANVAS.resolutionOptions.map((preset) => ({ ...preset })),
// HOST RAM, not VRAM: at int8 the transformer's blocks and the
// conditioner's leaves are streamed from CPU memory, so ~75 GB of the
// weights are resident off-GPU for the whole render. The card itself
// needs ~24 GB, and the runner steps down to a leaner offload profile
// on a smaller one (see scripts/generate_minimax_h3_cuda.py).
memoryGb: 96,
steps: 8,
guidance: 0,
samplerLocked: true,
samplerNote: 'MiniMax H3 is CFG-distilled; this profile locks the validated 8-point sigma schedule and does not use CFG.',
supportsNegativePrompt: false,
supportsTiling: false,
supportsDisableAudio: false,
},
]))))),
defaultMlx: 'fastmetal_5b_qad',
defaultCuda: 'ltx_video',
},
image: [
{
id: MOSS_IMAGE_MODEL_ID, name: 'MOSS Image SFT Preview (Swift/MLX bf16, 27.2 GB download, 48+ GB RAM)',
runner: 'moss-swift', repo: 'OpenMOSS-Team/MOSS-Image-SFT',
revision: 'fc5de0d56fc910cbca6f6625a70f5f582b26deb1',
steps: 50, guidance: 3, quantization: 'bf16', supportsImg2Img: false, supportsLoras: false,
hardwareRequirements: { platforms: ['darwin'], architectures: ['arm64'], requiresAppleSilicon: true, minMemoryGb: 48 },
license: 'apache-2.0', licenseUrl: 'https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT/blob/fc5de0d56fc910cbca6f6625a70f5f582b26deb1/LICENSE',
},
// mflux runner — MLX-only, Flux 1 (dev/schnell). `runner` defaults to 'mflux'.
{ id: 'dev', name: 'Flux 1 Dev', steps: 20, guidance: 3.5, requiresHfToken: true, licenseUrl: 'https://huggingface.co/black-forest-labs/FLUX.1-dev' },
{ id: 'schnell', name: 'Flux 1 Schnell', steps: 4, guidance: 0, cfgDisabled: true },
// flux2 runner — PyTorch + diffusers + MPS (Apple Silicon) or CUDA (Win/Linux).
// Models are quantized to fit on consumer hardware; tokenizer comes from the
// gated base repo, so users must accept the license at huggingface.co and
// set HF_TOKEN before first use.
{
id: 'flux2-klein-4b',
name: 'Flux 2 Klein 4B (SDNQ 4-bit, ~8 GB @ 512px)',
runner: 'flux2',
quantization: 'sdnq',
repo: 'Disty0/FLUX.2-klein-4B-SDNQ-4bit-dynamic',
tokenizerRepo: 'black-forest-labs/FLUX.2-klein-4B',
steps: 8,
guidance: 3.5,
cfgDisabled: true,
},
{
id: 'flux2-klein-9b',
name: 'Flux 2 Klein 9B (SDNQ 4-bit, ~12 GB — needs 32+ GB RAM)',
runner: 'flux2',
quantization: 'sdnq',
repo: 'Disty0/FLUX.2-klein-9B-SDNQ-4bit-dynamic-svd-r32',
// KV repo's tokenizer is the same Qwen3 tokenizer as the base 9B repo,
// but the multi-reference editing path in scripts/flux2_macos.py probes
// HF auth against this value — pinning to the KV repo means accepting
// its license once enables both single-ref + multi-ref renders.
tokenizerRepo: 'black-forest-labs/FLUX.2-klein-9B-kv',
steps: 8,
guidance: 3.5,
cfgDisabled: true,
},
{
id: 'flux2-klein-4b-int8',
name: 'Flux 2 Klein 4B (Int8, ~16 GB)',
runner: 'flux2',
quantization: 'int8',
repo: 'aydin99/FLUX.2-klein-4B-int8',
basePipelineRepo: 'black-forest-labs/FLUX.2-klein-4B',
steps: 8,
guidance: 3.5,
cfgDisabled: true,
},
// FLUX.2 9B at native bf16 — no quantization, full quality. Needs ~36 GB
// resident for the transformer alone, plus ~8 GB for the text encoder.
// Practical on 128GB unified-memory hardware; will OOM on smaller boxes.
// Uses the gated black-forest-labs/FLUX.2-klein-9B repo directly (same
// license as flux2-klein-9b SDNQ variant — accept once at huggingface.co).
{
id: 'flux2-klein-9b-bf16',
name: 'Flux 2 Klein 9B (bf16, ~36 GB — 64+ GB RAM)',
runner: 'flux2',
quantization: 'none',
repo: 'black-forest-labs/FLUX.2-klein-9B',
// Multi-reference editing loads this `-kv` sibling repo instead of the
// base 9B (its transformer is tuned for the K/V reference-editing task).
// The plain text/i2i bf16 path stays on `repo`. Same FLUX.2-klein
// license — accept once at huggingface.co. Threaded to the runner as
// `--kv-repo`; see scripts/flux2_macos.py.
kvRepo: 'black-forest-labs/FLUX.2-klein-9B-kv',
steps: 20,
guidance: 3.5,
cfgDisabled: true,
requiresHfToken: true,
licenseUrl: 'https://huggingface.co/black-forest-labs/FLUX.2-klein-9B',
},
// hidream runner — HiDream-I1 17B MoE DiT, Apache 2.0 weights but needs
// meta-llama/Meta-Llama-3.1-8B-Instruct (gated) as text-encoder-4.
// Pipeline class isn't auto-detected so passed explicitly. Reuses the
// FLUX.2 venv (diffusers >= 0.32 has HiDreamImagePipeline).
{
id: 'hidream-i1-full',
name: 'HiDream-I1 Full (17B, ~34 GB @ bf16, 50 steps)',
runner: 'hidream',
repo: 'HiDream-ai/HiDream-I1-Full',
pipelineClass: 'HiDreamImagePipeline',
textEncoderRepo: 'meta-llama/Meta-Llama-3.1-8B-Instruct',
textEncoderClass: 'LlamaForCausalLM',
tokenizerClass: 'PreTrainedTokenizerFast',
steps: 50,
guidance: 5.0,
requiresHfToken: true,
licenseUrl: 'https://huggingface.co/meta-llama/Meta-Llama-3.1-8B-Instruct',
},
{
id: 'hidream-i1-fast',
name: 'HiDream-I1 Fast (17B distilled, ~34 GB, 16 steps)',
runner: 'hidream',
repo: 'HiDream-ai/HiDream-I1-Fast',
pipelineClass: 'HiDreamImagePipeline',
textEncoderRepo: 'meta-llama/Meta-Llama-3.1-8B-Instruct',
textEncoderClass: 'LlamaForCausalLM',
tokenizerClass: 'PreTrainedTokenizerFast',
steps: 16,
guidance: 0,
cfgDisabled: true,
requiresHfToken: true,
licenseUrl: 'https://huggingface.co/meta-llama/Meta-Llama-3.1-8B-Instruct',
},
// qwen runner — Qwen-Image 20B MMDiT, Apache 2.0, ungated. Uses
// Qwen/Qwen2.5-VL-7B-Instruct as the bundled text encoder (also Apache).
// Diffusers >= 0.31 ships QwenImagePipeline (autodetectable via
// AutoPipelineForText2Image, but pinned explicitly so registry edits
// don't fight pipeline-class auto-resolution).
{
id: 'qwen-image',
name: 'Qwen-Image (20B MMDiT, ~40 GB @ bf16, best text rendering)',
runner: 'qwen',
repo: 'Qwen/Qwen-Image',
pipelineClass: 'QwenImagePipeline',
steps: 30,
guidance: 4.0,
},
{
id: 'qwen-image-edit',
name: 'Qwen-Image-Edit (20B, image-to-image + text-rewrite)',
runner: 'qwen',
repo: 'Qwen/Qwen-Image-Edit',
pipelineClass: 'QwenImageEditPipeline',
steps: 30,
guidance: 4.0,
// QwenImageEditPipeline requires a source `image` arg — a text-only
// submission crashes deep inside diffusers. `editOnly` lets the route
// reject (and the UI gate) a render with no init image up-front.
editOnly: true,
},
// Qwen 2.1 unifies generation/editing in a new RGBA pipeline. Its
// research license differs from the original Apache-licensed Qwen models.
{
id: 'qwen-image-2.1',
name: 'Qwen-Image 2.1 (7B DiT, generation + editing, research license)',
runner: 'qwen',
repo: 'Qwen/Qwen-Image-2.1',
pipelineClass: 'QwenImage21Pipeline',
steps: 40,
guidance: 1.0,
cfgDisabled: true,
licenseUrl: 'https://huggingface.co/Qwen/Qwen-Image-2.1/blob/main/LICENSE',
},
// z-image runner — Apache 2.0, ungated, reuses the FLUX.2 venv. Turbo
// distillation runs ~8 steps with CFG disabled (guidance 1.0).
{
id: 'z-image-turbo-bf16',
name: 'Z-Image-Turbo (bf16, ~13 GB)',
runner: 'z-image',
repo: 'Tongyi-MAI/Z-Image-Turbo',
steps: 8,
guidance: 1.0,
cfgDisabled: true,
},
// ernie runner — Baidu's ERNIE-Image (8B DiT). Apache 2.0, ungated,
// reuses the FLUX.2 venv. Pipeline class isn't in AutoPipelineForText2Image's
// registry yet so we pass `pipelineClass: 'ErnieImagePipeline'` for
// explicit dispatch. `usePromptEnhancer` activates the built-in PE module.
{
id: 'ernie-image',
name: 'ERNIE-Image (~16 GB @ bf16, 50 steps)',
runner: 'ernie',
repo: 'baidu/ERNIE-Image',
pipelineClass: 'ErnieImagePipeline',
usePromptEnhancer: true,
steps: 50,
guidance: 4.0,
},
{
id: 'ernie-image-turbo',
name: 'ERNIE-Image-Turbo (~16 GB @ bf16, 8 steps)',
runner: 'ernie',
repo: 'baidu/ERNIE-Image-Turbo',
pipelineClass: 'ErnieImagePipeline',
usePromptEnhancer: true,
steps: 8,
guidance: 1.0,
cfgDisabled: true,
},
{
id: 'z-image-turbo-quant',
name: 'Z-Image-Turbo (community quantized)',
runner: 'z-image',
repo: '',
steps: 8,
guidance: 1.0,
cfgDisabled: true,
// Hidden from the UI until the user picks a community quant repo and
// clears this flag. Keeping the entry here gives them a copy-paste
// template instead of having to remember the schema.
broken: true,
},
],
textEncoders: [
{ id: 'gemma-4bit', label: 'Gemma 3 12B 4-bit (smallest, ~7 GB)', repo: 'mlx-community/gemma-3-12b-it-4bit' },
{ id: 'gemma-qat-4bit', label: 'Gemma 3 12B QAT 4-bit (better, ~8 GB, LM Studio)', repo: 'mlx-community/gemma-3-12b-it-qat-4bit', localPath: '~/.lmstudio/models/mlx-community/gemma-3-12b-it-qat-4bit' },
{ id: 'gemma-bf16', label: 'Gemma 3 12B bf16 (default, best quality, ~24 GB)', repo: 'mlx-community/gemma-3-12b-it-bf16' },
],
selectedTextEncoder: 'gemma-bf16',
};
let cached = null;
// Whether the most recent fresh load parsed the file (false = fell back to the
// in-memory defaults). Read only by withLiveMediaModelsRestore's reconciliation.
let lastLoadReadOk = true;
// Live-restore ownership: `restoreFences` counts restores that have been
// requested and not yet reconciled; `restoreTail` serializes them;
// `reconcileFailure` pins the registry read-only after a reload that could not
// establish what the restored bytes say.
let restoreFences = 0;
let restoreTail = Promise.resolve();
let reconcileFailure = null;
const ensureDir = (file) => {
const dir = dirname(file);
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
};
// The shipped default registry, cloned so a caller (a migration adding a new
// shipped row to an existing install) can never mutate the in-memory defaults.
export const getShippedMediaRegistry = () => structuredClone(DEFAULT_REGISTRY);
// Write-then-rename so a crash mid-write can't truncate the registry — it holds
// every user-added model and the shipped-defaults ledger the upgrade merge reads.
const writeRegistryAtomic = (reg) => {
const temporary = `${REGISTRY_FILE}.${randomUUID()}.tmp`;
// Exclusive creation establishes ownership before cleanup is allowed.
const fd = openSync(temporary, 'wx');
try {
try {
writeFileSync(fd, JSON.stringify(reg, null, 2) + '\n');
} finally {
closeSync(fd);
}
renameSync(temporary, REGISTRY_FILE);
} finally {
rmSync(temporary, { force: true });
}
};
const seedIfMissing = () => {
if (existsSync(REGISTRY_FILE)) return;
ensureDir(REGISTRY_FILE);
writeRegistryAtomic(DEFAULT_REGISTRY);
console.log(`📝 Seeded media model registry: ${REGISTRY_FILE}`);
};
// Merge user-edited registry over DEFAULT_REGISTRY so missing top-level keys
// (e.g. someone deletes `video` or saves `{}`) don't blow up consumers that
// assume `reg.video.mlx`. We also coerce array-shaped fields back to the
// defaults when the user's JSON is parseable but wrong-shape (e.g.
// `image: {}` or `video.mlx: "ltx"`) — otherwise getImageModels /
// getVideoModels / buildAppModels would throw at module import-time and
// take down server startup. If a user supplies a real array, that's their
// list, full stop — we don't deep-merge entries.
const arrayOrDefault = (v, fallback) => (Array.isArray(v) ? v : fallback);
// Pre-flux2 stored entries had `broken: 'macos'` and no `runner` field. Merge
// missing flux2 fields from DEFAULT_REGISTRY when an entry id matches a known
// flux2 model but is missing the runner discriminator. User overrides for
// other fields (custom name, steps, repo) are preserved.
const FLUX2_DEFAULTS_BY_ID = Object.fromEntries(
DEFAULT_REGISTRY.image.filter((m) => m.runner === RUNNER_FAMILIES.FLUX2).map((m) => [m.id, m])
);
const upgradeImageEntries = (list) => {
if (!Array.isArray(list)) return list;
return list.map((entry) => {
if (!isPlainObject(entry) || typeof entry.id !== 'string') return entry;
const seed = FLUX2_DEFAULTS_BY_ID[entry.id];
// Only upgrade entries that DIDN'T set `runner` at all — a user who
// explicitly chose a different runner for a known flux2 id (e.g. to
// wire it up to a custom runner) keeps that override.
if (!seed || entry.runner !== undefined) return entry;
// Only strip `broken: 'macos'` (the legacy flag the upgrade is meant
// to clear). Any other broken value the user added is intentional and
// preserved.
const { broken, ...rest } = entry;
const merged = { ...seed, ...rest, runner: RUNNER_FAMILIES.FLUX2 };
if (broken !== undefined && broken !== 'macos') merged.broken = broken;
return merged;
});
};
// IDs whose underlying pipeline is step-wise distilled (Flux Schnell, FLUX.2
// Klein, Z-Image-Turbo). For these models, classifier-free guidance is fixed
// internally and any user-supplied guidance scale is silently ignored — the
// diffusers runner literally prints "Guidance scale X is ignored for step-
// wise distilled models." into the log on every render. Surface this as an
// explicit flag on each registry entry so the UI can hide the Guidance input
// and the runners can skip passing the flag.
const CFG_DISABLED_IDS = new Set([
'schnell',
'flux2-klein-4b',
'flux2-klein-9b',
'flux2-klein-9b-bf16',
'flux2-klein-4b-int8',
'z-image-turbo-bf16',
'z-image-turbo-quant',
'ernie-image-turbo',
'hidream-i1-fast',
]);
const backfillCfgDisabled = (list) => {
if (!Array.isArray(list)) return list;
return list.map((entry) => {
if (!isPlainObject(entry) || typeof entry.id !== 'string') return entry;
if ('cfgDisabled' in entry) return entry; // user override (true OR false) wins
if (!CFG_DISABLED_IDS.has(entry.id)) return entry;
return { ...entry, cfgDisabled: true };
});
};
// IDs whose underlying pipeline REQUIRES a source `image` arg (Qwen-Image-Edit
// loads QwenImageEditPipeline). A text-only render against one of these crashes
// deep inside diffusers, so the route rejects (and the UI gates) it up-front.
// Backfilled at load time — same pattern as cfgDisabled — so installs that
// stored their `qwen-image-edit` entry before this flag existed pick it up
// without a migration.
const EDIT_ONLY_IDS = new Set([
'qwen-image-edit',
]);
const backfillEditOnly = (list) => {
if (!Array.isArray(list)) return list;
return list.map((entry) => {
if (!isPlainObject(entry) || typeof entry.id !== 'string') return entry;
if ('editOnly' in entry) return entry; // user override (true OR false) wins
if (!EDIT_ONLY_IDS.has(entry.id)) return entry;
return { ...entry, editOnly: true };
});
};
// Multi-reference editing on the bf16 path loads the `-kv` sibling repo. Map
// each id to the base repo it shipped with and the kv repo it should pair
// with. Existing installs stored their `flux2-klein-9b-bf16` entry before
// `kvRepo` existed, so backfill it at load (same pattern as
// cfgDisabled/editOnly) AND ship migration 064 for installs that have already
// persisted the registry.
//
// Fork-preservation: only backfill when the entry's `repo` still matches the
// shipped base repo. A user who pointed `repo` at a fork must NOT get the
// upstream kv sibling silently injected (reference renders would mix a custom
// base with the upstream KV repo) — this mirrors migration 064's guard. A
// user-set `kvRepo` (any value, including '') always wins: `'kvRepo' in entry`
// is the override signal.
const KV_REPO_BY_ID = {
'flux2-klein-9b-bf16': {
shippedRepo: 'black-forest-labs/FLUX.2-klein-9B',
kvRepo: 'black-forest-labs/FLUX.2-klein-9B-kv',
},
};
const backfillKvRepo = (list) => {
if (!Array.isArray(list)) return list;
return list.map((entry) => {
if (!isPlainObject(entry) || typeof entry.id !== 'string') return entry;
if ('kvRepo' in entry) return entry; // user override wins
const spec = KV_REPO_BY_ID[entry.id];
if (!spec || entry.repo !== spec.shippedRepo) return entry; // unknown id or forked repo
return { ...entry, kvRepo: spec.kvRepo };
});
};
export const isFlux2 = (model) => model?.runner === RUNNER_FAMILIES.FLUX2;
export const isZImage = (model) => model?.runner === RUNNER_FAMILIES.Z_IMAGE;
export const isErnie = (model) => model?.runner === RUNNER_FAMILIES.ERNIE;
export const isHiDream = (model) => model?.runner === RUNNER_FAMILIES.HIDREAM;
export const isQwen = (model) => model?.runner === RUNNER_FAMILIES.QWEN;
export const isEditOnly = (model) => model?.editOnly === true;
// Append models that are genuinely new in this release (not in
// _shippedDefaults) to the user's list, while respecting deletions the user
// already made. Returns both the merged entry list and the newly-added ids so
// the caller can record them in _shippedDefaults. Used for both video and
// image lists — the deletion-survives-upgrade contract is identical.
//
// Semantics:
// - id already in userList → keep as-is (user customisations intact)
// - id in shippedIds but not userList → user explicitly deleted it; skip
// - id NOT in shippedIds → genuinely new built-in; add + record
const appendNewlyShippedEntries = (userList, defaultList, shippedIds) => {
const safeList = Array.isArray(userList) ? userList : [];
const safeDefaults = Array.isArray(defaultList) ? defaultList : [];
const userIds = new Set(safeList.map((e) => e?.id).filter((id) => typeof id === 'string'));
const result = [...safeList];
const newlyShipped = [];
for (const def of safeDefaults) {
if (typeof def?.id !== 'string') continue;
if (userIds.has(def.id)) continue; // already present — keep user copy
if (shippedIds.has(def.id)) continue; // user deleted it; don't re-add
result.push(def);
newlyShipped.push(def.id);
}
return { entries: result, newlyShipped };
};
// Existing installs predate the `runtime` field on video entries — fill it
// with 'mlx_video' (the legacy default) for known-legacy ids so the
// dispatch in videoGen/local.js routes them through `python -m
// mlx_video.generate_av` rather than treating undefined as ltx2.
// 'ltx2_unified' is retired (see RETIRED_VIDEO_MODELS) but stays here: an
// install that re-pointed its entry at a fork keeps that entry, and it still
// needs the runtime backfill.
const LEGACY_MLX_VIDEO_IDS = new Set(['ltx2_unified', 'ltx23_unified', 'ltx23_distilled_q4']);
const backfillRuntime = (list) => {
if (!Array.isArray(list)) return list;
return list.map((entry) => {
if (!isPlainObject(entry) || typeof entry.id !== 'string') return entry;
if (typeof entry.runtime === 'string' && entry.runtime.length > 0) return entry;
if (LEGACY_MLX_VIDEO_IDS.has(entry.id)) return { ...entry, runtime: 'mlx_video' };
return entry;
});
};
// `ltx_video` is the legacy diffusers CUDA helper, not an MLX runtime. It
// shipped in the CUDA bucket before the bucket names made that mismatch
// obvious, so correct an untouched persisted entry during the same early load
// that still precedes migrations. A custom repo is deliberately left alone.
const upgradeLegacyCudaLtxRuntime = (list) => {
if (!Array.isArray(list)) return list;
return list.map((entry) => (
isPlainObject(entry)
&& entry.id === 'ltx_video'
&& (entry.runtime === undefined || entry.runtime === 'mlx_video')
&& entry.repo === undefined
? { ...entry, runtime: 'cuda_video' }
: entry
));
};
export const upgradeLtx25CudaMemoryFloor = (list) => {
if (!Array.isArray(list)) return list;
return list.map((entry) => (
isPlainObject(entry)
&& entry.id === 'ltx25_cuda_distilled'
&& entry.repo === 'Lightricks/LTX-2.5'
&& entry.hardwareRequirements?.minMemoryGb === 32
? { ...entry, hardwareRequirements: { ...entry.hardwareRequirements, minMemoryGb: 64 } }
: entry
));
};
// Built-in video models that were delivered to installs and have since been
// withdrawn. Dropping an id from DEFAULT_REGISTRY is NOT enough on its own: the
// user's persisted list is what the pickers read, and appendNewlyShippedEntries
// only ever adds. This is the load-time twin of the retirement migrations (247
// for ltx2_unified, 315 for hunyuan_video) — and it is the load-bearing half,
// because the registry is cached at import time, BEFORE bootstrapServices()
// runs migrations, and
// persistRegistry writes the whole cached object back on the next registry
// edit. Without this the migration's deletion is undone by the same boot that
// applied it.
//
// `replacement` repoints a `defaultMlx`/`defaultCuda` that named the
// retired model. getDefaultVideoModelId() would otherwise fall back to the
// first available entry, which is not necessarily the intended successor.
//
// Preservation guard mirrors backfillKvRepo: an entry whose `repo` no longer
// matches the shipped one is a fork the user pointed at deliberately, so it
// stays — that is also the escape hatch for anyone who wants a retired model
// back.
//
// Exported so the matching retirement migration can assert it froze the same
// id/repo/replacement — a typo in either copy would otherwise turn one half of
// the retirement into a silent no-op with every test still green.
export const RETIRED_VIDEO_MODELS = Object.freeze({
ltx2_unified: Object.freeze({
shippedRepo: 'notapalindrome/ltx2-mlx-av',
replacement: 'ltx23_distilled_q4',
}),
hunyuan_video: Object.freeze({
shippedRepo: 'tencent/HunyuanVideo',
replacement: 'fastmetal_1_3b_qad',
}),
});
const isRetired = (entry) => {
if (!isPlainObject(entry) || typeof entry.id !== 'string') return false;
const spec = RETIRED_VIDEO_MODELS[entry.id];
// `spec &&` is load-bearing, not defensive: several entries (the Windows
// `ltx_video`) carry no `repo` at all, and without the guard an absent spec
// would compare `undefined === undefined` and retire every one of them.
return Boolean(spec) && entry.repo === spec.shippedRepo;
};
const dropRetiredEntries = (list) => (
Array.isArray(list) ? list.filter((entry) => !isRetired(entry)) : list
);
// The ordered load-time upgrade chain a video bucket's persisted entries run
// through before the apply*/sanitize* decorators in `videoEntries` touch them.
//
// This list IS the order. Every row is the same shape — a whole-list rewrite
// that only touches an entry still matching what PortOS itself shipped — so
// adding the next upgrader is appending a row rather than adding a paren level
// to one nested expression, and the ordering constraints below are stated where
// a reader — and the ordering guard in `mediaModels.test.js` — can see them,
// instead of being implied by nesting depth.
//
// `buckets` limits a row to the video buckets it applies to; a row without one
// runs for every bucket.
const VIDEO_REGISTRY_UPGRADES = Object.freeze([
// FIRST, unconditionally: a withdrawn model has to leave before any later row
// spends work on it, and before the apply* decorators would hand it a
// disclosure, a Finish edge, a speed profile or a draft decoder on its way out.
Object.freeze({ name: 'dropRetiredEntries', apply: dropRetiredEntries }),
Object.freeze({ name: 'upgradeMiniMaxH3OutputControls', apply: upgradeMiniMaxH3OutputControls }),
Object.freeze({ name: 'upgradeLtx25AudioControls', apply: upgradeLtx25AudioControls }),
// MUST stay ahead of `applyVideoDisclosures`, which only fills an ABSENT
// disclosure block: this row corrects the stale `estimatedDownloadGb` inside
// an already-persisted one, and the decorator would never revisit it.
Object.freeze({ name: 'upgradeFastMetalDownloadSizes', apply: upgradeFastMetalDownloadSizes }),
Object.freeze({ name: 'upgradeFastH3V2RuntimeModes', apply: upgradeFastH3V2RuntimeModes }),
Object.freeze({ name: 'backfillRuntime', apply: backfillRuntime }),
// CUDA-only, and in this order: the legacy `ltx_video` row is repointed at the
// `cuda_video` runtime first, then the LTX-2.5 memory floor is raised.
Object.freeze({
name: 'upgradeLegacyCudaLtxRuntime',
apply: upgradeLegacyCudaLtxRuntime,
buckets: [VIDEO_BUCKET_CUDA],
}),
Object.freeze({
name: 'upgradeLtx25CudaMemoryFloor',
apply: upgradeLtx25CudaMemoryFloor,
buckets: [VIDEO_BUCKET_CUDA],
}),
]);
// Exported for the ordering guard in mediaModels.test.js: the chain's
// order is load-bearing (see the constraints above), so a reorder has to be a
// deliberate edit to a named list rather than an invisible re-nesting.
export const VIDEO_REGISTRY_UPGRADE_NAMES = Object.freeze(
VIDEO_REGISTRY_UPGRADES.map((upgrade) => upgrade.name),
);
// Run one bucket's persisted entries through the chain above.
const applyVideoRegistryUpgrades = (entries, bucket) => VIDEO_REGISTRY_UPGRADES.reduce(
(list, { apply, buckets }) => (buckets && !buckets.includes(bucket) ? list : apply(list)),
entries,
);
// Repoint a platform default that named a model this load just retired. Falls
// through to the original id when the successor isn't installed either — then
// getDefaultVideoModelId()'s "unknown default → first available" warning is the
// honest outcome, rather than naming a model this install doesn't have.
const resolveRetiredDefault = (configuredId, entries) => {
const replacement = RETIRED_VIDEO_MODELS[configuredId]?.replacement;
if (!replacement) return configuredId;
if (entries.some((entry) => entry?.id === configuredId)) return configuredId; // fork kept it
return entries.some((entry) => entry?.id === replacement) ? replacement : configuredId;
};
// Build the initial shippedIds set for one bucket on first encounter
// (no _shippedDefaults field yet).
//
// Pre-snapshot bootstrap: existing installs without _shippedDefaults can't
// distinguish "user explicitly removed this built-in" from "this built-in
// is new in this release". We choose to UNION the user's current ids with
// the current default ids, treating both as "already shipped". That preserves
// any deletions the user made before this feature existed, at the cost of new
// built-in models in this release also being marked as shipped — so they won't
// appear on this install until the user edits data/media-models.json directly.
//
// Trade-off favors data preservation over feature visibility: a user who curated
// their model list won't have it silently re-populated. Users who want the new
// built-ins can delete media-models.json and restart to re-seed from scratch,
// or add the entries manually.
//
// When the bucket key is absent from their registry (e.g. the whole `video`
// section is missing), we return an empty set so the defaults are treated as
// genuinely new and get added as on a fresh install.
const bootstrapShippedIds = (userList, defaultList) => {
if (!Array.isArray(userList)) return new Set(); // missing key → treat as fresh
const safeDefaults = Array.isArray(defaultList) ? defaultList : [];
const ids = new Set();
for (const e of userList) if (typeof e?.id === 'string') ids.add(e.id);
for (const e of safeDefaults) if (typeof e?.id === 'string') ids.add(e.id);
return ids;
};
const normalizeRegistry = (parsed) => {
const safe = isPlainObject(parsed) ? parsed : {};
const safeVideo = isPlainObject(safe.video) ? safe.video : {};
// _shippedDefaults tracks which built-in ids have ever been delivered
// to this install, so we can distinguish "user deleted it" from "genuinely
// new in this release". Tracked separately for video (per-bucket) and
// image (single list — image entries cover both buckets).
const shippedVideo = isPlainObject(safe._shippedDefaults?.video) ? safe._shippedDefaults.video : null;
const isVideoBootstrap = shippedVideo === null;
// Every read goes through readVideoBucket / readVideoDefault so a registry
// still keyed `macos` / `windows` (any install written before #4142) resolves
// exactly as it did before. The OUTPUT below is canonical-only.
const shippedIdsFor = (bucket) => (isVideoBootstrap
? bootstrapShippedIds(readVideoBucket(safeVideo, bucket), DEFAULT_REGISTRY.video[bucket])
: new Set(arrayOrDefault(readVideoBucket(shippedVideo, bucket), [])));
const shippedIds = Object.fromEntries(VIDEO_BUCKETS.map((b) => [b, shippedIdsFor(b)]));
const bucketResults = Object.fromEntries(VIDEO_BUCKETS.map((bucket) => [bucket, appendNewlyShippedEntries(
readVideoBucket(safeVideo, bucket),
DEFAULT_REGISTRY.video[bucket],
shippedIds[bucket],
)]));
const updatedShippedVideo = Object.fromEntries(VIDEO_BUCKETS.map((bucket) => [
bucket, [...shippedIds[bucket], ...bucketResults[bucket].newlyShipped],
]));
// Image upgrade path. Same shape as video, single list. The flux2 upgrade
// (upgradeImageEntries) runs first so legacy `broken: 'macos'` entries get
// promoted to runner-aware ones before the new-entry append step looks at
// their ids. Skips bootstrap union when the image key was missing entirely
// (treat as fresh install — let the new entries land).
const shippedImage = isPlainObject(safe._shippedDefaults?.image) ? safe._shippedDefaults.image : null;
const isImageBootstrap = shippedImage === null;
const upgradedImage = backfillKvRepo(backfillEditOnly(backfillCfgDisabled(
upgradeImageEntries(arrayOrDefault(safe.image, DEFAULT_REGISTRY.image)),
)));
// Image bootstrap deliberately uses userIds ONLY (not union with defaults).
// Image is getting `_shippedDefaults` for the first time in this release, so
// there's no prior history of deletions to preserve via the union trick the
// video side uses. Pre-existing installs will pick up the new built-ins
// (z-image-turbo-*, etc.) on next boot. Subsequent loads use the persisted
// list so user deletions stick.
const upgradedImageIds = (Array.isArray(upgradedImage) ? upgradedImage : [])
.map((e) => e?.id)
.filter((id) => typeof id === 'string');
const shippedImageIds = isImageBootstrap
? new Set(upgradedImageIds)
: new Set(arrayOrDefault(shippedImage.list, []));
const imageResult = appendNewlyShippedEntries(
upgradedImage,
DEFAULT_REGISTRY.image,
shippedImageIds,
);
const updatedShippedImage = {
list: [...shippedImageIds, ...imageResult.newlyShipped],
};
// VIDEO_REGISTRY_UPGRADES runs first: it is the ordered chain of load-time
// twins of the registry migrations, and its own ordering constraints are
// stated row by row up there.
//
// applyVideoDisclosures is the load-time twin of migration 237: installs
// that persisted their registry before `disclosure` existed pick it up
// here without waiting for the migration, and both paths share the same
// preservation guards (user value wins, forked repo keeps Unknown). It only
// fills an ABSENT block, which is why the upgrade chain — not a decorator —
// is where a stale persisted disclosure gets corrected.
// sanitizeFinishProfiles runs LAST (after the backfill and
// after the user's own entries are merged in) so an edge that points at a
// model this install deleted — or a hand-edited typo — is dropped with a
// warning instead of surfacing a Finish button targeting nothing.
const videoEntries = (entries, bucket) => {
const upgraded = applyVideoRegistryUpgrades(entries, bucket);
const decorated = sanitizeFinishProfiles(applyVideoFinishProfiles(applyVideoDisclosures(upgraded)));
// applyVideoSpeedProfiles is the load-time twin of migration 295, and
// sanitizeSpeedProfiles is its sibling of sanitizeFinishProfiles: a
// hand-edited profile with a NaN step count would otherwise reach the
// picker and spawn a broken render, so it is warned about and stripped.
const withSpeed = sanitizeSpeedProfiles(applyVideoSpeedProfiles(decorated));
// applyVideoDraftDecoders + sanitizeDraftDecoders (lib/videoDraftDecoders.js)
// are the same arrangement for the preview-fidelity decode (#5423). The
// sanitizer matters more here than elsewhere: a hand-edited decoder pointed
// at a runtime whose builder emits no draft flags would render on the FULL
// decoder while the history record claimed a draft one, so it is warned
// about and stripped rather than allowed to make a false claim.
const withDraftDecode = sanitizeDraftDecoders(applyVideoDraftDecoders(withSpeed));
// applyMiniMaxH3MemoryProfiles is the load-time twin of migration 317, and
// its sanitizer the sibling of the two above: a hand-edited profile with a
// NaN memory floor would otherwise make every capacity comparison false and
// refuse H3 renders on a machine that can run them, so it is warned about
// and stripped.
return sanitizeMiniMaxH3MemoryProfiles(applyMiniMaxH3MemoryProfiles(withDraftDecode));
};
const normalizedBuckets = Object.fromEntries(
VIDEO_BUCKETS.map((bucket) => [bucket, videoEntries(bucketResults[bucket].entries, bucket)]),
);
// Spread the user's own `video` keys but NOT the legacy bucket spellings: the
// canonical keys below already carry those lists, and leaving both on the
// object would persist two spellings of the same bucket into a file users
// hand-edit — a later edit to the stale copy would silently do nothing.
const carriedVideo = Object.fromEntries(
Object.entries(safeVideo).filter(([key]) => !LEGACY_VIDEO_KEYS.includes(key)),
);
return {
...DEFAULT_REGISTRY,
...safe,
image: imageResult.entries,
textEncoders: arrayOrDefault(safe.textEncoders, DEFAULT_REGISTRY.textEncoders),
video: {
...DEFAULT_REGISTRY.video,
...carriedVideo,
...normalizedBuckets,
...Object.fromEntries(VIDEO_BUCKETS.map((bucket) => [
VIDEO_DEFAULT_KEYS[bucket],
resolveRetiredDefault(
readVideoDefault(safeVideo, bucket) ?? DEFAULT_REGISTRY.video[VIDEO_DEFAULT_KEYS[bucket]],
normalizedBuckets[bucket],
),
])),
},
_shippedDefaults: {
...(safe._shippedDefaults || {}),
video: updatedShippedVideo,
image: updatedShippedImage,
},
};
};
// Detect drift between `_shippedDefaults` and the user's live list. We
// previously hit a real install (2026-05-09) where `_shippedDefaults.image.list`
// claimed all default ids had been shipped but the user's `image[]` array was
// missing several of them — most likely from a partial editor save or a
// concurrent-write race. The deletion-survives-upgrade contract then
// permanently skipped re-adding those built-ins on every restart. We DON'T
// auto-recover (that would defeat real deletions), but we make the drift
// loud at boot so a user / sysadmin can act on it.
//
// IMPORTANT: this state is structurally indistinguishable from an INTENTIONAL
// deletion — `appendNewlyShippedEntries` skips re-adding ids that are in
// shippedIds but not userList for exactly that reason. There is no "silence
// without re-adding" path today: removing an id from `_shippedDefaults`
// flips it back to "genuinely new built-in" and normalizeRegistry will
// re-append it on next boot. So if the absence is intentional, this log
// fires every restart — users can either live with it, or accept the
// re-add and delete the entry again from the UI. We surface it anyway
// because the silent-skipping behaviour was the original bug.
//
// `where` and `shippedKey` are the two on-disk paths the warning quotes, and
// both are resolved by the CALLER rather than assembled here: image keeps its
// ids at `_shippedDefaults.image.list` while video keeps them at
// `_shippedDefaults.video.{mlx,cuda}`, and either half of a pre-#4142 registry
// may still be spelled `macos` / `windows` (migration 242 can write a canonical
// snapshot onto a legacy-keyed `video`). A copy-paste out of this warning has to
// land on a key that actually exists in the user's file.
const warnDrift = ({ where, shippedKey }, shippedIds, defaultIds, presentIds) => {
const shippedSet = new Set(shippedIds || []);
const defaultSet = new Set(defaultIds || []);
const presentSet = new Set(presentIds || []);
for (const id of shippedSet) {
if (!defaultSet.has(id)) continue; // not a current built-in; ignore
if (presentSet.has(id)) continue; // present — no drift
console.log(`⚠️ media-models drift: built-in "${id}" was shipped but is missing from ${where}[] — if the deletion is intentional this warning will repeat each boot (no silence-without-restore path exists); to restore, either re-add the entry manually or delete ${shippedKey} entirely to re-bootstrap`);
}
};
export const loadMediaModels = () => {
if (cached) return cached;
seedIfMissing();
// Catch read AND parse failures — both can happen at module import-time
// (videoGen/imageGen import this synchronously), so an unhandled throw
// here aborts server startup. Permissions, broken symlink, transient I/O
// all surface from readFileSync; malformed JSON from JSON.parse.
let parsed = DEFAULT_REGISTRY;
let readOk = false;
try {
const raw = readFileSync(REGISTRY_FILE, 'utf-8');
parsed = JSON.parse(raw);
readOk = true;
} catch (err) {
console.log(`⚠️ Failed to load ${REGISTRY_FILE} (${err.message}) — using built-in defaults`);
}
// Drift check runs on the RAW parsed file (pre-normalize), because
// normalizeRegistry uses _shippedDefaults to decide which built-ins to
// re-add and which to skip. We want to surface the mismatch as it exists
// on disk, not the post-merge view. Skip when no parsed file at all (the
// catch above already logged) or when _shippedDefaults isn't populated yet
// (bootstrap path — no drift is possible).
if (readOk && isPlainObject(parsed?._shippedDefaults)) {
const sd = parsed._shippedDefaults;
if (isPlainObject(sd.image) && Array.isArray(parsed.image)) {
warnDrift(
{ where: 'image', shippedKey: '_shippedDefaults.image.list' },
Array.isArray(sd.image.list) ? sd.image.list : [],
DEFAULT_REGISTRY.image.map((m) => m.id),
parsed.image.map((m) => m?.id).filter((id) => typeof id === 'string'),
);
}
// Only the CURRENT machine's video bucket is worth warning about. The
// pickers, downloads, and every edit path read one bucket's array
// (`getVideoModels`), so drift in the other one is invisible and
// unactionable here — and because the warning has no silence-without-
// restore path, a CUDA box would print the MLX rows on every single
// boot forever with nothing the user can usefully do about them. The
// machine that actually runs that bucket still gets the warning.
const driftBucket = activeVideoBucket();
const shippedDrift = readVideoBucket(sd.video, driftBucket);
const presentDrift = readVideoBucket(parsed.video, driftBucket);
if (
isPlainObject(sd.video) &&
isPlainObject(parsed.video) &&
Array.isArray(shippedDrift) &&
Array.isArray(presentDrift)
) {
warnDrift(
{
where: `video.${resolveVideoBucketKey(parsed.video, driftBucket)}`,
shippedKey: `_shippedDefaults.video.${resolveVideoBucketKey(sd.video, driftBucket)}`,
},
shippedDrift,
DEFAULT_REGISTRY.video[driftBucket].map((m) => m.id),
presentDrift.map((m) => m?.id).filter((id) => typeof id === 'string'),
);
}
}
lastLoadReadOk = readOk;
cached = normalizeRegistry(parsed);
// Persist _shippedDefaults back to disk whenever it was absent or gained new
// ids (bootstrap run or a new built-in model shipped in this release). This
// ensures user deletions survive the next server restart.
if (readOk) {
const parsedShippedVideo = isPlainObject(parsed._shippedDefaults?.video)
? parsed._shippedDefaults.video
: null;
const parsedShippedImage = isPlainObject(parsed._shippedDefaults?.image)
? parsed._shippedDefaults.image
: null;
const normalizedVideo = cached._shippedDefaults.video;
const normalizedImage = cached._shippedDefaults.image;
// A pre-#4142 bucket spelling still on disk counts as a change: the
// normalized object is canonical-only, so the file has to be rewritten once
// or the two spellings diverge the next time anything edits the registry.
// (Migration 270 performs the same rename; this is its load-time twin, for
// the same reason applyVideoDisclosures mirrors migration 237.)
const carriesLegacyKeys = (obj) => isPlainObject(obj)
&& LEGACY_VIDEO_KEYS.some((key) => Object.hasOwn(obj, key));
const videoChanged =
parsedShippedVideo === null ||
carriesLegacyKeys(parsed.video) ||
carriesLegacyKeys(parsedShippedVideo) ||
VIDEO_BUCKETS.some((bucket) => (
normalizedVideo[bucket].length !== (readVideoBucket(parsedShippedVideo, bucket)?.length ?? 0)
));
const imageChanged =
parsedShippedImage === null ||
normalizedImage.list.length !== (parsedShippedImage.list?.length ?? 0);
if (videoChanged || imageChanged) {
writeRegistryAtomic(cached);
console.log(`📝 Updated media model registry _shippedDefaults: ${REGISTRY_FILE}`);
}
}
return cached;
};
// Bust the boot-only cache so the next loadMediaModels() re-reads the file.
// The registry is cached at module scope (videoGen/imageGen import it
// synchronously at boot), so a runtime add/edit/remove must invalidate the
// cache or the change 400s ("Unknown model") until a server restart — the
// exact gotcha called out in issue #2124. Returns the freshly-loaded registry.
export const reloadMediaModels = () => {
cached = null;
return loadMediaModels();
};
// Registry mutators are synchronous, so checking this at their top refuses a
// write before any disk or cache change while a live restore owns the file (or
// after a restore whose reload failed — persisting the stale/default cache then
// would overwrite the restored bytes).
const assertRegistryWritable = () => {
if (restoreFences > 0) {
throw new ServerError('The media model registry is being restored from a snapshot — retry once the restore finishes.', { status: 409, code: 'MEDIA_MODELS_RESTORE_BUSY' });
}
if (reconcileFailure) {
throw new ServerError(`The media model registry could not be reloaded after a snapshot restore (${reconcileFailure.message}). Restart PortOS before editing it.`, { status: 503, code: 'MEDIA_MODELS_UNAVAILABLE' });
}
};
/**
* Own data/media-models.json across an out-of-band live restore. Registry
* mutations are refused from the moment the restore is requested until the
* cache has been reloaded from the resulting file — including after a partial
* transfer, which may already have overwritten it. Competing restores are
* serialized. A reload that cannot parse the file leaves the registry
* read-only until a later restore reconciles it (or the process restarts).
* The callback must not call a registry mutator.
*/
export const withLiveMediaModelsRestore = (transfer) => {
restoreFences += 1;
const run = restoreTail.then(async () => {
try {
const [result] = await Promise.allSettled([Promise.resolve().then(transfer)]);
let reloadError = null;
try {
reloadMediaModels();
if (!lastLoadReadOk) throw new Error('media-models.json is unreadable or not valid JSON');
reconcileFailure = null;
} catch (err) {
reloadError = err;
reconcileFailure = err;
}
if (result.status === 'rejected') {
if (!reloadError) throw result.reason;
const error = new Error(`${result.reason.message}. Media model registry reload failed: ${reloadError.message}. Restart PortOS before editing media models.`, { cause: result.reason });
if (result.reason?.code) error.code = result.reason.code;
throw error;
}
if (reloadError) {
throw new Error(`Media model registry reload failed: ${reloadError.message}. Restart PortOS before editing media models.`, { cause: reloadError });
}
return result.value;
} finally {
restoreFences -= 1;
}
});
restoreTail = run.catch(() => {});
return run;
};
// Persist a registry object to disk and swap it in as the cache. The cache is
// only replaced AFTER a successful write, so a persist failure leaves the live
// cache untouched (the mutators build an immutable `next` rather than editing
// the shared cache in place). Single-user trust model → no file lock needed.
const persistRegistry = (reg) => {
ensureDir(REGISTRY_FILE);
writeRegistryAtomic(reg);
cached = reg;
return reg;
};
// A user-added entry (from the "add from HuggingFace" flow) carries
// `source: 'user'`. Shipped built-ins have no `source` (or a non-'user' one
// like 'trained' won't appear here). Only user entries are editable/removable
// through the API — built-ins are read-only (the registry is their source of
// truth + they round-trip through the shipped-defaults upgrade machinery).
export const isUserModelEntry = (entry) => entry?.source === 'user';
// Locate a model entry by id, returning `{ entry, list, listKey, idx }` or null.
// Scans the CURRENT machine's video bucket + the image list — NOT the other
// bucket's video list. The other bucket's rows aren't visible to
// getVideoModels()/the render path on this install, and scanning both would
// make patch/remove ambiguous when a shared media-models.json (an MLX box and a
// CUDA box syncing as peers) legitimately holds the same custom id in both
// buckets — a remove(id) meant for the CUDA row would hit the MLX row first.
// `listKey` ('mlx' | 'cuda' | 'image') lets the mutators rebuild just that list.
// The registry passed in is always post-normalizeRegistry, so its bucket keys
// are canonical.
const findModelLocation = (reg, id) => {
const videoKey = activeVideoBucket();
const lists = [
[videoKey, reg.video?.[videoKey]],
['image', reg.image],
];
for (const [listKey, list] of lists) {
if (!Array.isArray(list)) continue;
const idx = list.findIndex((m) => m?.id === id);
if (idx >= 0) return { entry: list[idx], list, listKey, idx };
}
return null;
};
// Rebuild the registry with one list replaced — shallow everywhere except the
// swapped array, so we neither deep-clone the whole registry nor mutate the
// live cache before the write succeeds.
const withList = (reg, listKey, nextList) =>
listKey === 'image'
? { ...reg, image: nextList }
: { ...reg, video: { ...reg.video, [listKey]: nextList } };
// Add a user model entry to the registry. `kind` selects the target list:
// 'video' → the current machine's video bucket; 'image' → the image list.
// Throws on a duplicate id (a repo already added). Persists + hot-reloads.
export const addUserModelEntry = (entry, { kind }) => {
if (!entry || typeof entry.id !== 'string') {
throw new ServerError('Model entry must carry a string id', { status: 400, code: 'BAD_MODEL_ENTRY' });
}
if (kind !== 'video' && kind !== 'image') {
throw new ServerError(`Unknown model kind "${kind}" — expected "image" or "video".`, { status: 400, code: 'BAD_MODEL_KIND' });
}
assertRegistryWritable();
const reg = loadMediaModels();
const listKey = kind === 'video' ? activeVideoBucket() : 'image';
// Conflict-check against the ACTIVE-on-this-install lists — the current
// machine's video bucket + the image list — via findModelLocation (which
// scopes to exactly those). This rejects a collision between the current
// video list and the image list (both mutable through the same :id-only
// PATCH/DELETE, so a dup would make one row unaddressable), while still
// allowing the same custom video id to be added on the OTHER bucket's list
// of a shared media-models.json (that list isn't scanned, so no false 409).
if (findModelLocation(reg, entry.id)) {
throw new ServerError(
`A model with id "${entry.id}" is already in this install's registry (repo already added?). Remove it first to re-add.`,
{ status: 409, code: 'MODEL_ALREADY_EXISTS' },
);
}
const current = (listKey === 'image' ? reg.image : reg.video?.[listKey]) || [];
// Also reject a duplicate REPO in the target list — the same weights under a
// different id (e.g. the UI placeholder `notapalindrome/ltx23-mlx-av-q4`,
// already shipped as the built-in `ltx23_distilled_q4`) would otherwise add a
// second pickable row for identical weights. Only meaningful when the entry
// carries a repo.
if (typeof entry.repo === 'string' && entry.repo.trim()
&& current.some((m) => typeof m?.repo === 'string' && m.repo === entry.repo)) {
throw new ServerError(
`The HuggingFace repo "${entry.repo}" is already in this install's ${kind} registry (possibly as a built-in). It's already available in the model picker.`,
{ status: 409, code: 'MODEL_REPO_ALREADY_EXISTS' },
);
}
persistRegistry(withList(reg, listKey, [...current, entry]));
console.log(`📝 Added user media model: ${entry.id} (${kind}) → ${entry.repo || '?'}`);
return entry;
};
// Guard shared by patch/remove: locate a USER entry by id or throw (404 for
// unknown, 403 for a built-in). Returns the `findModelLocation` result.
const requireUserEntry = (reg, id, verb) => {
const loc = findModelLocation(reg, id);
if (!loc) throw new ServerError(`Unknown model id: ${id}`, { status: 404, code: 'NOT_FOUND' });
if (!isUserModelEntry(loc.entry)) {
throw new ServerError(
`Model "${id}" is a built-in — built-in models can't be ${verb} through this surface.`,
{ status: 403, code: 'MODEL_READONLY' },
);
}
return loc;
};
// Patch a USER model entry's editable fields (name, steps, guidance). Refuses
// built-ins and unknown ids. Persists + hot-reloads. Returns the updated entry.
const USER_EDITABLE_FIELDS = new Set(['name', 'steps', 'guidance']);
export const patchUserModelEntry = (id, patch) => {
assertRegistryWritable();
const reg = loadMediaModels();
const loc = requireUserEntry(reg, id, 'edited');
const cleanPatch = {};
for (const [k, v] of Object.entries(patch || {})) {
if (USER_EDITABLE_FIELDS.has(k) && v !== undefined) cleanPatch[k] = v;
}
const updated = { ...loc.entry, ...cleanPatch, id, source: 'user' };
const nextList = loc.list.map((m, i) => (i === loc.idx ? updated : m));
persistRegistry(withList(reg, loc.listKey, nextList));
console.log(`📝 Patched user media model: ${id}`);
return updated;
};
// Availability is install configuration, including for shipped entries. Keep
// disabled rows in the registry so they can be re-enabled without reinstalling.
export const setMediaModelEnabled = (id, enabled) => {
assertRegistryWritable();
const reg = loadMediaModels();
const loc = findModelLocation(reg, id);
if (!loc) throw new ServerError(`Unknown model id: ${id}`, { status: 404, code: 'NOT_FOUND' });
if (typeof enabled !== 'boolean') throw new ServerError('enabled must be a boolean', { status: 400, code: 'VALIDATION_ERROR' });
const updated = { ...loc.entry, enabled };
persistRegistry(withList(reg, loc.listKey, loc.list.map((m, i) => i === loc.idx ? updated : m)));
return updated;
};
// Remove a USER model entry. Refuses built-ins and unknown ids. Persists +
// hot-reloads. Returns `{ ok, id }`.
export const removeUserModelEntry = (id) => {
assertRegistryWritable();
const reg = loadMediaModels();
const loc = requireUserEntry(reg, id, 'removed');
const nextList = loc.list.filter((_, i) => i !== loc.idx);
persistRegistry(withList(reg, loc.listKey, nextList));
console.log(`🗑️ Removed user media model: ${id}`);
return { ok: true, id };
};
// `broken` is either `true` (broken everywhere) or the name of the ONE bucket
// it's broken on. Pre-#4142 entries spell that name `macos` / `windows`, so
// matchesVideoBucket accepts both spellings for the active bucket.
const platformBroken = (broken) =>
broken === true || matchesVideoBucket(broken, activeVideoBucket());
// `supportedModes` is resolved HERE rather than in normalizeRegistry (#3737):
// deriving on read covers the load path, the user-model mutators (which bypass
// normalizeRegistry) and peer-synced entries in one place, and keeps the derived
// list out of data/media-models.json — a persisted copy would read back as a
// *declared* list that no later correction to VIDEO_RUNTIME_MODES could reach.
/**
* Every pinned file group a model needs resolvable in the HF cache.
*
* Two shapes, and a caller that checks only one gets the other wrong: a
* selective row pins its subset with `repoFiles` against its OWN repo (the H3
* CUDA entry, whose base repo is ~498 GB and whose diffusers layout is ~144 GB
* of it), while a row that composes weights from a SECOND repo pins them in
* `requiredWeights` (the H3 MLX entry's upstream FL2VA checkpoint). Checking
* `requiredWeights` alone reports a half-downloaded CUDA model as complete.
*
* An empty result means "the base snapshot is the whole answer".
*/
export const requiredModelCacheGroups = (model) => {
const groups = [];
if (Array.isArray(model?.repoFiles)) {
groups.push({ repo: model.repo, revision: model.revision, files: model.repoFiles });
}
if (Array.isArray(model?.requiredWeights)) groups.push(...model.requiredWeights);
return groups;
};
export const getVideoModels = ({ includeDisabled = false } = {}) => {
const reg = loadMediaModels();
const bucket = activeVideoBucket();
const capabilities = captureSystemCapabilities();
const list = readVideoBucket(reg.video, bucket) || [];
return applyVideoSupportedModes(list.filter((m) => !platformBroken(m.broken) && (includeDisabled || m.enabled !== false))).map((model) => (
withHardwareCompatibility(
model,
capabilities,
hardwareRequirementsForMediaModel(model, { kind: 'video', bucket }),
)
));
};
export const getDefaultVideoModelId = (capabilities = captureSystemCapabilities(), preferredId = null) => {
const reg = loadMediaModels();
// Note: defaultMlx / defaultCuda may legitimately point at a model
// flagged `deprecated: true` — the dgrauet (non-deprecated) runtime
// requires an opt-in venv (`INSTALL_LTX2=1 bash scripts/setup-image-video.sh`),
// so the shipped default must stay on a model that works out of the box.
// The UI dropdowns surface dgrauet at the top via the `Legacy` optgroup
// pattern; user-driven migration > auto-rolling forward.
const bucket = activeVideoBucket();
const configuredId = readVideoDefault(reg.video, bucket);
const preferred = typeof preferredId === 'string' && preferredId.trim() ? preferredId.trim() : null;
// Validate against the bucket's available (non-broken) list — a typo or
// a model marked broken on this bucket would otherwise surface as
// "Unknown video model" the first time the UI tries to use the default.
const available = getVideoModels().map((model) => withHardwareCompatibility(
model,
capabilities,
model.hardwareRequirements,
));
const compatible = available.filter((model) => isHardwareCompatible(model.hardwareCompatibility));
const candidates = [preferred, configuredId];
// FastMetal 5B is the shipped Apple Silicon default. On a machine below its
// 16 GB floor, use the smaller FastMetal profile when it is compatible
// before considering older catalog entries.
if (candidates.includes('fastmetal_5b_qad')) candidates.push('fastmetal_1_3b_qad');
const selected = candidates.find((id) => compatible.some((model) => model.id === id));
if (selected) return selected;
const fallback = compatible[0]?.id;
if (fallback) {
console.log(`⚠️ Default video model "${preferred || configuredId}" is unavailable or unknown for ${bucket}; falling back to "${fallback}"`);
return fallback;
}
console.log(`⚠️ Default video model "${preferred || configuredId}" is unavailable or unknown for ${bucket}; no available models to fall back to`);
return preferred || configuredId;
};
export const getImageModels = ({ includeDisabled = false } = {}) => {
const reg = loadMediaModels();
const capabilities = captureSystemCapabilities();
return (reg.image || [])
.filter((m) => !platformBroken(m.broken) && (includeDisabled || m.enabled !== false))
.map((model) => withHardwareCompatibility(
model,
capabilities,
hardwareRequirementsForMediaModel(model, { kind: 'image' }),
));
};
// Map a registry entry to the HuggingFace repo id whose weights need to be
// resident on disk before generation can run. Used by the download-status
// badge on the image/video gen forms.
//
// Most entries already carry `repo` directly. mflux's legacy `dev` / `schnell`
// ids predate the field and resolve to the canonical Black Forest Labs repos
// at runtime via the `mflux-generate` CLI — hardcode those two so the badge
// can probe their HF cache the same way as every other model.
const MFLUX_LEGACY_REPOS = {
dev: 'black-forest-labs/FLUX.1-dev',
schnell: 'black-forest-labs/FLUX.1-schnell',
};
export const repoForModel = (model) => {
if (!model || typeof model !== 'object') return null;
if (isNonBlankStr(model.repo)) return model.repo;
if (MFLUX_LEGACY_REPOS[model.id]) return MFLUX_LEGACY_REPOS[model.id];
return null;
};
// Full list of HF repos a model needs cached on disk before the runner can
// inference. For HiDream entries this includes the separate Llama-3.1 text
// encoder (`textEncoderRepo`) the Diffusers pipeline loads as `text_encoder_4`
// — otherwise the cache-status badge says "Available" while the renderer
// silently kicks off a second multi-GB gated download at start-up. Result is
// `null` when the main repo itself isn't known (model is misconfigured / a
// custom mflux third-party entry).
export const requiredReposForModel = (model) => {
const main = repoForModel(model);
if (!main) return null;
const aux = [];
if (isNonBlankStr(model?.textEncoderRepo)) aux.push(model.textEncoderRepo);
return [main, ...aux];
};
// `getTextEncoderRepo()` can return either an HF repo id (`org/name`) or a
// resolved local filesystem path when the registry entry has a `localPath`
// override. Only `org/name` is a valid input to HF-cache inspection /
// download endpoints.
//
// Reject local-path shapes across platforms:
// - POSIX absolute / home-relative: `/foo/bar`, `~/foo`
// - Windows drive paths (both backslash and forward-slash style): `C:\…`,
// `C:/Users/…` — without this check, a Windows install with a
// forward-slash-style localPath text encoder would be misclassified as
// an HF repo, triggering bogus cache inspection / download requests.
// - Windows UNC paths: `\\server\share\…`
// - Any path containing a backslash (Windows separator)
// Then require exactly one `/` separator — standard HF repo ids are the
// `org/name` shape; zero (`legacy-bare-name`) and multiple (a path) are not.
export const isHfRepoId = (value) => {
if (typeof value !== 'string' || value.length === 0) return false;
if (value.startsWith('/') || value.startsWith('~')) return false;
if (value.includes('\\')) return false;
if (/^[A-Za-z]:/.test(value)) return false;
return (value.match(/\//g) || []).length === 1;
};
// Resolve the active text encoder to a path mlx_video can pass via
// --text-encoder-repo. Prefers `localPath` (e.g. an existing LM Studio
// install) when it exists; otherwise returns the HF repo id which mlx_video
// will resolve via the HF cache (downloading on first run).
const FALLBACK_TEXT_ENCODER_REPO = 'mlx-community/gemma-3-12b-it-4bit';
export const getTextEncoderRepo = () => {
const reg = loadMediaModels();
const id = reg.selectedTextEncoder;
const entry = (reg.textEncoders || []).find((t) => t.id === id);
if (!entry) {
console.log(`⚠️ Unknown selectedTextEncoder "${id}"; falling back to first entry`);
const firstRepo = reg.textEncoders?.[0]?.repo;
return isNonBlankStr(firstRepo) ? firstRepo : FALLBACK_TEXT_ENCODER_REPO;
}
if (entry.localPath) {
const expanded = expandHome(entry.localPath);
if (existsSync(expanded)) return expanded;
}
// Spawn args must be non-empty strings — a malformed registry entry
// (missing/empty `repo`) would otherwise reach mlx_video as undefined and
// surface as a confusing TypeError or downstream CLI error.
if (!isNonBlankStr(entry.repo)) {
console.log(`⚠️ Text encoder "${id}" has no repo; falling back to "${FALLBACK_TEXT_ENCODER_REPO}"`);
return FALLBACK_TEXT_ENCODER_REPO;
}
return entry.repo;
};
export const getTextEncoderEntries = () => {
const reg = loadMediaModels();
return (reg.textEncoders || []).map((t) => ({
id: t.id,
label: t.label,
repo: t.repo,
localPath: t.localPath ? expandHome(t.localPath) : null,
localAvailable: t.localPath ? existsSync(expandHome(t.localPath)) : false,
selected: t.id === reg.selectedTextEncoder,
}));
};