Skip to content

Make videos on the computer you already own. FreeVideo runs MiniMax H3 in as little as 8 GB of VRAM and 16 GB of RAM, and adapts its acceleration path to your hardware.

Quality levels: Max uses 20 steps with a guarded step cache, High 16 steps with the step cache

Bowen Xue1a814ba3600a
diff --git a/freevideo_engine/agent/guide.py b/freevideo_engine/agent/guide.py
index 56a6ccf..778d367 100644
--- a/freevideo_engine/agent/guide.py
+++ b/freevideo_engine/agent/guide.py
@@ -74,8 +74,8 @@ GUIDE = {
],
'quality': [
'Steps per quality: "light" = 8 first-pass steps + 3 refine steps, two-pass, the first pass at half size '
- '(default); "medium" = the same 8 + 3 two-pass with a larger first pass, for more detail; "high" = 20 steps '
- 'with a step cache and "max" = 20 plain steps, each in one pass. The same on a Mac. sampling.two_pass=false '
+ '(default); "medium" = the same 8 + 3 two-pass with a larger first pass, for more detail; "high" = 16 steps '
+ 'with a step cache and "max" = 20 steps with a step cache, each in one pass. The same on a Mac. sampling.two_pass=false '
'without base_steps runs 20 steps.',
'Two-pass generation runs only with 8 first-pass steps. Any other base_steps (for example 20 with '
'two_pass=true) runs in one pass of that many steps; the job notice says so. A preview is always two-pass '
diff --git a/freevideo_engine/agent/schema.py b/freevideo_engine/agent/schema.py
index dfca3b7..f0ac1cd 100644
--- a/freevideo_engine/agent/schema.py
+++ b/freevideo_engine/agent/schema.py
@@ -14,7 +14,7 @@ from .. import tiers
S = 'https://json-schema.org/draft/2020-12/schema'
PREFIX = '/freevideo/agent/v1'
# (two_pass, base_steps, refine_steps) of each level on this platform; the step
-# cache a level adds is tiers.step_cache(name, mac) (only high has one, easycache-av),
+# cache a level adds is tiers.step_cache(name, mac) (high and max use easycache-av),
# its two-pass upscale factor tiers.upscale_factor(name, mac) (medium samples a larger first pass).
QUALITY = {name: tiers.plan(name, mac=tiers.on_mac()) for name in tiers.TIERS}
ASPECTS = {'16:9': (16, 9), '9:16': (9, 16), '1:1': (1, 1), '4:3': (4, 3), '3:4': (3, 4),
diff --git a/freevideo_engine/agent/spec.py b/freevideo_engine/agent/spec.py
index c3fdeb4..f2e508a 100644
--- a/freevideo_engine/agent/spec.py
+++ b/freevideo_engine/agent/spec.py
@@ -147,9 +147,7 @@ def sampling(value):
cache = tiers.step_cache(quality, mac) if own else None
factor = tiers.upscale_factor(quality, mac) if own and two else 2
if custom:
- quality = next((k for k, v in QUALITY.items() if v == (two, base, refine)
- and tiers.step_cache(k, mac) == cache
- and (not two or tiers.upscale_factor(k, mac) == factor)), 'custom')
+ quality = tiers.name_for(base, two, refine, cache, mac, factor) or 'custom'
return dict(quality=quality, two_pass=two, base_steps=base, refine_steps=refine,
**({'step_cache': cache} if cache else {}), **({'upscale_factor': factor} if factor != 2 else {}),
**({'sampling_note': note} if note else {}))
diff --git a/freevideo_engine/comfy_bridge.py b/freevideo_engine/comfy_bridge.py
index d112fb3..9601098 100644
--- a/freevideo_engine/comfy_bridge.py
+++ b/freevideo_engine/comfy_bridge.py
@@ -1486,7 +1486,7 @@ def generate(prompt, width, height, seconds, seed, output_directory, *,
# Reference audio selects its own tables; match the encoder's choice.
asset_task = ((ANCHOR_ADALN_TASK if anchored or pictured else ADALN_TASK) if continue_from is not None
else engine_task(extra.get('media', {}), media_base))
- # The cache only names the level of a missing table (high or max at 20 steps).
+ # Tables follow the step count; the cache is carried for exact level recognition.
preparation = prepare_sampling_assets(root, machine, dict(planned, step_cache=step_cache) if step_cache else planned,
asset_task,
progress=asset_progress, interrupted=interrupted, environ=environment)
diff --git a/freevideo_engine/failure_details.py b/freevideo_engine/failure_details.py
index adf51af..3b770a7 100644
--- a/freevideo_engine/failure_details.py
+++ b/freevideo_engine/failure_details.py
@@ -88,7 +88,7 @@ def sampling_table_failure(value, *, zh=False):
return None
from .launcher_copy import size_text
language = 1 if zh else 0
- # Tables follow the step count; the cache tells high from max at 20 steps.
+ # Tables follow the step count: 16 steps is high, 20 steps is max.
level = table_level(details['base_steps'], details['two_pass'], details['refine_steps'],
details.get('step_cache'), on_mac(), details.get('scale', 2))
index = list(TIERS).index(level) if level else None
diff --git a/freevideo_engine/step_cache.py b/freevideo_engine/step_cache.py
index e081419..c54f734 100644
--- a/freevideo_engine/step_cache.py
+++ b/freevideo_engine/step_cache.py
@@ -111,6 +111,7 @@ class StepCache:
def stats(self):
full = self.steps - len(self.hits)
return dict(kind=self.kind, threshold=self.threshold, steps=self.steps, cached_steps=list(self.hits),
+ cached_share=round(len(self.hits) / self.steps, 3) if self.steps else 0.,
full_forwards=full, decisions=self.decisions, source=self.source,
disabled_reason=self.disabled_reason, guard=GUARD)
diff --git a/freevideo_engine/tiers.py b/freevideo_engine/tiers.py
index 8e58e08..a5c08fd 100644
--- a/freevideo_engine/tiers.py
+++ b/freevideo_engine/tiers.py
@@ -6,12 +6,11 @@ that cannot import it (web JS, prose docs) against this table.
- light: two-pass, 8 + 3 steps, first pass at half size (2x learned upscale).
- medium: two-pass, 8 + 3 steps, a larger first pass (`upscale`, below 2).
-- high: one pass of 20 steps with the audio-video EasyCache.
-- max: one pass of 20 steps, every step sampled.
+- high: one pass of 16 steps with the guarded audio-video EasyCache.
+- max: one pass of 20 steps with the same guarded cache.
-A level in one pass always samples 20 steps; fewer steps come only from a
-user's own setting. Only a two-pass level samples a second time. Single-pass
-levels carry REFINE_STEPS only as the neutral value the `refine_steps` field
+Each level uses the step count in the table below. Only a two-pass level
+samples a second time. Single-pass levels carry REFINE_STEPS only as the neutral value the `refine_steps` field
needs; it is never run for them, and their `upscale` is 2 (no factor).
`step_cache` is the engine's cache key: None, 'easycache-av' (audio-video
EasyCache) or 'fbcache' (first-block cache, no level uses it; a request may
@@ -20,7 +19,8 @@ still ask for it). `upscale` is the two-pass learned upscale factor
Mac (MPS) runs the same levels (TIERS_MAC). Results made before the
audio-video EasyCache was ported there, one pass of 16 steps without a cache,
-still count as high (LEGACY_MAC_HIGH).
+still count as high (LEGACY_MAC_HIGH). Earlier one-pass 20-step results
+without a cache still count as max on every platform (LEGACY_MAX).
"""
import sys
@@ -30,10 +30,11 @@ STEP_CACHES = (None, 'easycache-av', 'fbcache')
TIERS = {
'light': dict(steps=8, two_pass=True, step_cache=None, upscale=2),
'medium': dict(steps=8, two_pass=True, step_cache=None, upscale=1.5),
- 'high': dict(steps=20, two_pass=False, step_cache='easycache-av', upscale=2),
- 'max': dict(steps=20, two_pass=False, step_cache=None, upscale=2),
+ 'high': dict(steps=16, two_pass=False, step_cache='easycache-av', upscale=2),
+ 'max': dict(steps=20, two_pass=False, step_cache='easycache-av', upscale=2),
}
TIERS_MAC = TIERS
+LEGACY_MAX = dict(steps=20, two_pass=False, step_cache=None, upscale=2)
LEGACY_MAC_HIGH = dict(steps=16, two_pass=False, step_cache=None, upscale=2)
# Sampling time of a cached pass as a share of the same pass without a cache,
@@ -50,6 +51,8 @@ LEGACY_MAC_HIGH = dict(steps=16, two_pass=False, step_cache=None, upscale=2)
# is plain 20 steps.
# EasyCache-AV, guarded (at most 40% of steps reused, never twice in a row): measured on the RTX PRO 6000,
# 864x1184, 5 s, 20 steps, 2 reused steps: 212 s against 238 s for the plain 20 steps (about .88 of the sampling).
+# At 16 steps the guarded cache reused 1–4 steps (about 14% on average),
+# so the same conservative .88 share also applies at 16 steps.
SAMPLING_SHARE = {None: 1., 'easycache-av': .88, 'fbcache': .9}
# Sampling time (both passes) of a two-pass request with this upscale factor,
@@ -94,6 +97,8 @@ def name_for(steps, two_pass, refine_steps=REFINE_STEPS, step_cache=None, mac=Fa
if tier['steps'] == steps and tier['two_pass'] == two_pass
and (not two_pass or refine_steps == REFINE_STEPS) and tier['step_cache'] == step_cache
and tier['upscale'] == upscale), None)
+ if found is None and (steps, two_pass, step_cache, upscale) == tuple(LEGACY_MAX.values()):
+ return 'max'
if found is None and mac and (steps, two_pass, step_cache, upscale) == tuple(LEGACY_MAC_HIGH.values()):
return 'high'
return found
@@ -102,10 +107,10 @@ def name_for(steps, two_pass, refine_steps=REFINE_STEPS, step_cache=None, mac=Fa
def table_level(steps, two_pass, refine_steps=REFINE_STEPS, step_cache=None, mac=False, upscale=2):
"""The level whose sampling table a plan needs, for naming a missing download.
- Tables follow the step count only. Prefer the exact level (the cache tells
- high from max at 20 steps), then the other platform's table (16 steps is
- the earlier Mac "high"), then the first level with that step count (light
- for 8 + 3, whatever the upscale factor).
+ Tables follow the step count only: 16 steps names high, 20 names max.
+ Prefer the exact level or a legacy alias, then the other platform's table,
+ then the first level with that step count (light for 8 + 3, whatever the
+ upscale factor).
"""
found = name_for(steps, two_pass, refine_steps, step_cache, mac, upscale) or name_for(
steps, two_pass, refine_steps, step_cache, not mac, upscale)
diff --git a/web/capability_view.js b/web/capability_view.js
index 524ce7e..78139bb 100644
--- a/web/capability_view.js
+++ b/web/capability_view.js
@@ -1,5 +1,5 @@
import { referenceItems } from './prompt_references.js';
-import { stepCacheOf, upscaleOf } from './sampling_effort.js';
+import { effortFor, effortsFrom, stepCacheOf, upscaleOf } from './sampling_effort.js';
const PRESETS = [.5, .75, .98, 1.5, 2];
const COLUMN_SPACING = 'equal'; // 'equal' or 'width'
@@ -77,11 +77,11 @@ export function capabilityContext(node, state) {
return query.toString();
}
-// The grid's level with exactly this plan; a step cache tells High from Max at 20 steps, the
-// upscale factor Light from Medium (a row without one is 2x).
-const gridTier = (grid, steps, twoPass, refine, stepCache, upscale = 2) => Object.values(grid.tiers || {}).find(v => v.steps === steps
- && v.two_pass === twoPass && (!v.two_pass || refine === 3) && stepCacheOf(v.step_cache) === stepCacheOf(stepCache)
- && (!v.two_pass || upscaleOf(v.upscale) === upscaleOf(upscale)));
+// Shared recognition includes legacy Max and the Mac-only legacy High.
+const gridTier = (grid, steps, twoPass, refine, stepCache, upscale = 2) => {
+ const level = effortFor(steps, twoPass, refine, stepCache, effortsFrom(grid), upscale);
+ return grid.tiers?.[level?.name.toLowerCase()];
+};
export function capabilitySurface(grid, state) {
if (grid?.version !== 1 || grid.status !== 'ready' || typeof grid.revision !== 'string' || !grid.machine?.system
diff --git a/web/chain_support.js b/web/chain_support.js
index 218e024..8101415 100644
--- a/web/chain_support.js
+++ b/web/chain_support.js
@@ -1,6 +1,6 @@
// Pure helpers the creative panel's long-video planning shares with the editor store; kept out of
// editor_store.js so the panel does not load the editing implementation.
-import { stepCacheOf, upscaleOf } from './sampling_effort.js';
+import { effortFor, effortsFrom } from './sampling_effort.js';
const clockDefault = {now: () => Date.now(), setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: id => clearTimeout(id)};
export const chainRoute = (id, action) => '/freevideo/chain' + (id ? '/' + encodeURIComponent(id) : '') + (action ? '/' + action : '');
@@ -38,11 +38,9 @@ function capabilityTier(reply, settings) {
const tiers = reply.tiers;
if (!tiers || typeof tiers !== 'object') return reply;
if (tiers[settings?.tier]) return tiers[settings.tier];
- const steps = Number(settings?.base_steps), twoPass = !!settings?.two_pass, cache = stepCacheOf(settings?.step_cache);
- const factor = twoPass ? upscaleOf(settings?.upscale_factor) : 2;
- return Object.values(tiers).find(tier => tier.steps === steps && tier.two_pass === twoPass
- && (!twoPass || Number(settings?.refine_steps) === 3) && stepCacheOf(tier.step_cache) === cache
- && (tier.two_pass ? upscaleOf(tier.upscale) : 2) === factor) || {};
+ const level = effortFor(Number(settings?.base_steps), !!settings?.two_pass, Number(settings?.refine_steps),
+ settings?.step_cache, effortsFrom(reply), settings?.upscale_factor);
+ return tiers[level?.name.toLowerCase()] || {};
}
export function capabilityPoints(reply, {width, height, settings = {}}) {
const tier = capabilityTier(reply, settings);
diff --git a/web/sampling_effort.js b/web/sampling_effort.js
index 14af234..4cb0fab 100644
--- a/web/sampling_effort.js
+++ b/web/sampling_effort.js
@@ -1,19 +1,24 @@
// One editor control. The queued request remains an immutable graph snapshot.
// Each level is a complete plan (freevideo_engine/tiers.py): Light and Medium are two-pass 8 + 3,
// told apart by the learned upscale factor (Medium starts from a larger first pass); High and Max
-// sample 20 steps once, High with a step cache. `upscale` is 2 for every single-pass level.
+// sample 16 and 20 steps once, both with the guarded step cache. `upscale` is 2 for every single-pass level.
const frozen = rows => Object.freeze(rows.map(row => Object.freeze({...row})));
export const SAMPLING_EFFORTS = frozen([
{name: 'Light', zh: '轻量', steps: 8, twoPass: true, stepCache: null, upscale: 2, color: '#3dd6b5'},
{name: 'Medium', zh: '标准', steps: 8, twoPass: true, stepCache: null, upscale: 1.5, color: '#4ea8ff'},
- {name: 'High', zh: '精细', steps: 20, twoPass: false, stepCache: 'easycache-av', upscale: 2, color: '#9d7bff'},
- {name: 'Max', zh: '极致', steps: 20, twoPass: false, stepCache: null, upscale: 2, color: '#ffa94d'},
+ {name: 'High', zh: '精细', steps: 16, twoPass: false, stepCache: 'easycache-av', upscale: 2, color: '#9d7bff'},
+ {name: 'Max', zh: '极致', steps: 20, twoPass: false, stepCache: 'easycache-av', upscale: 2, color: '#ffa94d'},
]);
-// Mac runs the same levels.
-export const SAMPLING_EFFORTS_MAC = SAMPLING_EFFORTS;
+// Mac runs the same plans; retain platform identity for its legacy High alias.
+const macLevels = new WeakSet();
+export const SAMPLING_EFFORTS_MAC = frozen(SAMPLING_EFFORTS);
+macLevels.add(SAMPLING_EFFORTS_MAC);
+// Earlier Max sampled 20 plain steps, on every platform.
+export const legacyMaxEffort = (steps, twoPass, stepCache = null, levels = SAMPLING_EFFORTS) =>
+ steps === 20 && !twoPass && stepCacheOf(stepCache) === null ? levels.find(tier => tier.name === 'Max') : undefined;
// Mac results made before the cache came: High was 16 steps without one.
-export const legacyMacEffort = (steps, twoPass, stepCache = null) =>
- steps === 16 && !twoPass && stepCacheOf(stepCache) === null ? SAMPLING_EFFORTS_MAC.find(tier => tier.name === 'High') : undefined;
+export const legacyMacEffort = (steps, twoPass, stepCache = null, levels = SAMPLING_EFFORTS_MAC) =>
+ steps === 16 && !twoPass && stepCacheOf(stepCache) === null ? levels.find(tier => tier.name === 'High') : undefined;
export const effortName = (t, tier) => t(tier.name, tier.zh);
export const STEP_CACHES = Object.freeze([null, 'easycache-av', 'fbcache']);
@@ -34,13 +39,15 @@ export function effortsFrom(grid) {
const base = grid?.machine?.system === 'Darwin' ? SAMPLING_EFFORTS_MAC : SAMPLING_EFFORTS;
const tiers = grid?.tiers;
if (!tiers || typeof tiers !== 'object') return base;
- return frozen(base.map(tier => {
+ const levels = frozen(base.map(tier => {
const row = tiers[tier.name.toLowerCase()];
if (!row || !Number.isInteger(row.steps) || typeof row.two_pass !== 'boolean') return tier;
return {...tier, steps: row.steps, twoPass: row.two_pass,
stepCache: 'step_cache' in row ? stepCacheOf(row.step_cache) : tier.stepCache,
upscale: !row.two_pass ? 2 : 'upscale' in row ? upscaleOf(row.upscale) : tier.upscale};
}));
+ if (base === SAMPLING_EFFORTS_MAC) macLevels.add(levels);
+ return levels;
}
// The level a plan matches, or undefined for custom steps; the upscale factor tells the
@@ -48,7 +55,9 @@ export function effortsFrom(grid) {
export function effortFor(steps, twoPass, refine, stepCache = null, levels = SAMPLING_EFFORTS, upscale = 2) {
const cache = stepCacheOf(stepCache), factor = twoPass ? upscaleOf(upscale) : 2;
return levels.find(tier => tier.steps === steps && tier.twoPass === twoPass && (!twoPass || refine === 3)
- && tier.stepCache === cache && tier.upscale === factor);
+ && tier.stepCache === cache && tier.upscale === factor)
+ || legacyMaxEffort(steps, twoPass, cache, levels)
+ || (macLevels.has(levels) ? legacyMacEffort(steps, twoPass, cache, levels) : undefined);
}
// The level a result's sampling_plan names. Results made with the earlier 8 + 2 default count as
@@ -60,11 +69,15 @@ export function resultEffort(plan) {
}
// The steps and factor switching two-pass leaves. Off from an 8-step first pass samples the
-// single-pass levels' 20 steps; on from a single-pass level gives Light. Typed steps stay.
+// Max plan including its cache; on from a single-pass level gives Light without a cache. Typed steps stay.
export function passSwitch(on, steps, refine, stepCache = null, levels = SAMPLING_EFFORTS) {
- if (!on) return {steps: steps === 8 ? levels.find(tier => !tier.twoPass)?.steps ?? 20 : steps, refine, upscale: 2};
+ const max = levels.find(tier => tier.name === 'Max');
+ if (!on) return {steps: steps === 8 ? max?.steps ?? 20 : steps, refine, upscale: 2,
+ stepCache: steps === 8 ? max?.stepCache ?? null : null};
const light = levels.find(tier => tier.twoPass && tier.upscale === 2);
- return effortFor(steps, false, refine, stepCache, levels) && light ? {steps: light.steps, refine: 3, upscale: 2} : {steps, refine, upscale: 2};
+ return effortFor(steps, false, refine, stepCache, levels) && light
+ ? {steps: light.steps, refine: 3, upscale: 2, stepCache: null}
+ : {steps, refine, upscale: 2, stepCache: null};
}
// A continuation samples 8 + 3 in two passes: it keeps the factor of a two-pass level, else 2 (widget text).
@@ -72,8 +85,8 @@ export const continuationUpscale = (steps, twoPass, refine, stepCache, upscale,
String(effortFor(Number(steps), twoPass !== false, Number(refine), stepCache, levels, upscale)?.twoPass ? upscaleOf(upscale) : 2);
// The level whose sampling table a plan needs, for naming a missing download (tiers.table_level):
-// the exact level (the cache tells High from Max at 20 steps, the factor Light from Medium; 16 steps
-// is the earlier Mac High), else the first level with those steps (Light for 8 + 3, whatever the factor).
+// the exact level or legacy alias, else the first with those steps (16 is High, 20 is Max,
+// Light for 8 + 3 whatever the factor).
export function tableLevel(steps, twoPass, refine, stepCache = null, upscale = 2) {
return effortFor(steps, twoPass, refine, stepCache, SAMPLING_EFFORTS, upscale)
|| legacyMacEffort(steps, twoPass, stepCache) || SAMPLING_EFFORTS.find(tier => tier.steps === steps && tier.twoPass === twoPass && (!twoPass || refine === 3));
@@ -182,7 +195,8 @@ export function createSamplingEffort(t, {onChange, onPreview = () => {}, levels
// The machine's own table (effortsFrom); the names stay, the plans follow the machine.
function setLevels(next) {
const same = (a, b) => a.steps === b.steps && a.twoPass === b.twoPass && a.stepCache === b.stepCache && a.upscale === b.upscale;
- if (!next || next.length !== efforts.length || next.every((tier, i) => same(tier, efforts[i]))) return;
+ if (!next || next.length !== efforts.length || (macLevels.has(next) === macLevels.has(efforts)
+ && next.every((tier, i) => same(tier, efforts[i])))) return;
efforts = next;
update({baseSteps: currentSteps, refineSteps: currentRefine, twoPass, stepCache, upscale, disabled, reason});
}
diff --git a/web/studio.js b/web/studio.js
index f419e9d..b80d036 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -818,9 +818,9 @@ export function openStudio(node, {extendFrom = null} = {}) {
if (extension.source) return;
const wantsTwoPass = mode !== 'off', wantsPreview = mode === 'preview';
if (twoPass.checked !== wantsTwoPass) {
- // A level in one pass samples 20 steps; two-pass from one is Light. Typed steps stay.
+ // Switching off uses Max including its cache; switching on uses uncached Light. Typed steps stay.
const next = passSwitch(wantsTwoPass, Number(baseSteps.value), Number(refineSteps.value), stepCacheNow(), effort.levels());
- twoPass.checked = wantsTwoPass; autoSinglePass = false; set(node, 'two_pass', wantsTwoPass); clearStepCache(); setUpscale(next.upscale);
+ twoPass.checked = wantsTwoPass; autoSinglePass = false; set(node, 'two_pass', wantsTwoPass); set(node, 'step_cache', next.stepCache || 'none'); setUpscale(next.upscale);
if (next.steps !== Number(baseSteps.value) && !linked(node, 'base_steps') && widget(node, 'base_steps')) {
baseSteps.value = String(next.steps); set(node, 'base_steps', next.steps);
if (next.refine !== Number(refineSteps.value) && set(node, 'refine_steps', next.refine)) refineSteps.value = String(next.refine);