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.
"""Public CLI. Planning and help do not import the model runtime."""
import argparse
import json
import os
from pathlib import Path
import sys
from .hardware import Hardware, detect
from .kernel_capabilities import available_backends
from .policy import choose
def write_json(value, path=None):
text = json.dumps(value, ensure_ascii=False, indent=2) + '\n'
if path:
Path(path).parent.mkdir(parents=True, exist_ok=True)
Path(path).write_text(text, encoding='utf-8')
print(text, end='')
def resource_arguments(parser):
parser.add_argument('--vram-gib', type=float, help='Nominal capacity, bounded by detected VRAM')
parser.add_argument('--ram-gib', type=float, help='Nominal system RAM, bounded by detected RAM')
parser.add_argument('--gpu-reserve-gib', type=float,
help='Explicit foreground VRAM growth reserve (minimum 0.2 GiB); automatic planning may shrink its default reserve for a tight request')
parser.add_argument('--ram-reserve-gib', type=float, help='Override headroom kept beyond current system RAM usage')
parser.add_argument('--attention', default='auto', help='auto, sage2, cudnn, torch-flash, fa2, fa4, or global/window')
def main():
if os.environ.get('FREEVIDEO_HOME'):
# Without a system compiler, run-time builds (Triton) in this process use the one FreeVideo installed.
from .comfy_environment import with_private_compiler
with_private_compiler(os.environ['FREEVIDEO_HOME'], os.environ)
if len(sys.argv) > 1 and sys.argv[1] in ('projects', 'sessions'):
from .agent.cli import main as agent
return agent(sys.argv[1:])
if not getattr(sys, 'frozen', False) and not {'-h', '--help'} & set(sys.argv[1:]):
from .launch_view import restart_arguments
restart = restart_arguments(sys.argv[1:])
if restart is not None:
# Deep installation folder: Windows cannot load the libraries by their full path.
from . import processes
raise SystemExit(processes.run(restart[0], env=restart[1], start_new_session=False).returncode)
if len(sys.argv) > 1 and sys.argv[1] == 'predict':
from .prediction_cli import main as predict
raise SystemExit(predict(sys.argv[2:]))
if len(sys.argv) > 1 and sys.argv[1] == 'resource-history':
from .resource_cli import main as resource_history
raise SystemExit(resource_history(sys.argv[2:]))
if len(sys.argv) > 1 and sys.argv[1] == 'optimize':
from .optimize import main as optimize
raise SystemExit(optimize(sys.argv[2:]))
if len(sys.argv) > 1 and sys.argv[1] == 'diagnose':
from .diagnostics import main as diagnose
raise SystemExit(diagnose(sys.argv[2:]))
if len(sys.argv) > 1 and sys.argv[1] == 'bench':
from .benchmark import main as benchmark
return benchmark(sys.argv[2:])
if len(sys.argv) > 1 and sys.argv[1] == 'calibrate':
from .calibration import main as calibrate
return calibrate(sys.argv[2:])
parser = argparse.ArgumentParser(prog='freevideo', description='VDN Engine: video and audio with bounded memory')
sub = parser.add_subparsers(dest='command', required=True)
plan = sub.add_parser('plan', help='Show a resource policy without loading models')
resource_arguments(plan)
plan.add_argument('--hardware-json', type=Path, help='Inspect a fixture, not a hardware benchmark')
plan.add_argument('--out', type=Path)
plan.add_argument('--width', type=int, default=1344)
plan.add_argument('--height', type=int, default=768)
plan_length = plan.add_mutually_exclusive_group()
plan_length.add_argument('--frames', type=int)
plan_length.add_argument('--seconds', type=float)
doctor = sub.add_parser('doctor', help='Check paths, versions and installed attention kernels')
doctor.add_argument('--probe', action='store_true', help='Execute small kernels in isolated processes')
doctor.add_argument('--require-paths', action='store_true', help='Fail if model or source directories are missing')
doctor.add_argument('--out', type=Path, help='Save the complete kernel report, including optional failures')
sub.add_parser('diagnose', help='Collect bounded local diagnostics, even after a failed setup')
sub.add_parser('optimize', help='Reuse a test report and validate bounded local tuning')
sub.add_parser('resource-history', help='Inspect local performance and resource measurements (CPU only)')
sub.add_parser('predict', help='Preview phase time and memory from local complete request history')
setup = sub.add_parser('setup', help='Install the pinned upstream model-code dependency')
setup.add_argument('--vdn-root', type=Path)
setup.add_argument('--install-packages', action='store_true')
setup.add_argument('--fa4-guard', action='store_true', help='Prepare the validated isolated FA4 b26 SM120 fix')
prepare = sub.add_parser('prepare', help='Prepare official merged weights and an FP8 cache')
prepare.add_argument('--base', type=Path, required=True)
prepare.add_argument('--checkpoint', type=Path, required=True)
prepare.add_argument('--cache-root', type=Path, required=True)
prepare.add_argument('--bf16-source', type=Path)
encode = sub.add_parser('encode', help='Save reusable text conditioning for generation and matched benchmarks')
resource_arguments(encode)
encode.add_argument('--prompt-file', type=Path, required=True)
encode.add_argument('--out', type=Path, required=True)
generate = sub.add_parser('generate', help='Generate an MP4 from text or cached conditioning')
resource_arguments(generate)
source = generate.add_mutually_exclusive_group(required=True)
source.add_argument('--prompt-file', type=Path)
source.add_argument('--conditioning', type=Path)
generate.add_argument('--allow-empty-prompt', action='store_true', help='Generate from an empty prompt file')
generate.add_argument('--cache', type=Path, required=True)
generate.add_argument('--base', type=Path)
generate.add_argument('--checkpoint', type=Path)
generate.add_argument('--profile', type=Path, help='Explicit policy/profile override')
from .media_request import TASKS
generate.add_argument('--task', choices=TASKS, help='Input task; inferred when --media is provided')
generate.add_argument('--media', type=Path, help='Versioned keyframe/reference/LoRA request JSON; local files only')
generate.add_argument('--audio', type=Path, help='Audio file; may be combined with image/video references in --media')
generate.add_argument('--audio-use', choices=('reference', 'original'),
help='Audio use (default: reference); with --media alone, applies to its single audio file')
generate.add_argument('--continue-from', type=Path, help='Continue an existing MP4 using its absolute path')
generate.add_argument('--first-frame-reference', action='store_true',
help='With --continue-from: also give the model the first frame of the whole film as a '
'reference picture. Reduces drift over many parts; holds framing and motion close to '
'the opening, so leave it off when later parts should move away from it')
generate.add_argument('--hide-tail', action='store_true',
help='Generate and discard 17 extra frames for dialogue segments.')
generate.add_argument('--voice-reference', action='store_true',
help='With --continue-from: use the opening six seconds as a voice reference when the prompt has dialogue')
generate.add_argument('--continue-anchor', type=Path, metavar='IMAGE',
help='Experimental: a reference picture of your own for a continuation, with no prompt note')
generate.add_argument('--allocator-limit-gib', type=float,
help='Explicit benchmark cap on PyTorch CUDA allocations; not a whole-device memory limit')
generate.add_argument('--no-history-placement', action='store_true', help='Keep the starting placement for a matched baseline; still record measurements')
generate.add_argument('--recover-placement', action='store_true', help='Allow numerical-neutral resource recovery with an explicit profile; automatic profiles already recover')
generate.add_argument('--resource-retries', type=int, choices=(0, 1, 2), default=2,
help='Fresh-worker placement retries after confirmed resource exhaustion (default: 2)')
generate.add_argument('--no-tuning', action='store_true', help='Bypass saved tuning and conditioning reuse for this request')
generate.add_argument('--seed', type=int, default=2026090901)
generate.add_argument('--two-pass', action=argparse.BooleanOptionalAction, default=True,
help='Sample a smaller canvas, upscale latents and refine (default: on; 8 + 3 steps)')
generate.add_argument('--step-cache', choices=('easycache-av', 'fbcache'),
help='Approximate reuse between sampling steps (disabled by default)')
generate.add_argument('--base-steps', type=int, choices=range(1, 33), metavar='1..32',
help='First-pass steps (default: 8, or explicit profile). Changes may reduce quality.')
generate.add_argument('--refine-steps', type=int, choices=range(1, 32), default=3, metavar='1..31',
help='Second-pass steps (default: 3, independent schedule). Other counts use the original tail.')
generate.add_argument('--upscale-factor', type=float, choices=(2., 1.5, 1.2), default=2., metavar='{2,1.5,1.2}',
help='Two-pass learned upscale factor (default 2: half-size first pass). 1.5 and 1.2 sample '
'a larger first pass (44%% / 69%% of the pixels) for the same output size.')
upscale = generate.add_mutually_exclusive_group()
upscale.add_argument('--preview', action='store_true',
help='Two-pass only: stop after the half-resolution first pass, save it as a quick preview, '
'and keep that pass so the preview can be upscaled later')
upscale.add_argument('--refine-from', type=Path, metavar='PREVIEW.mp4',
help="Upscale a finished preview: reuse its first pass, then the latent upscale, the refinement "
"steps and a full-resolution decode. Use the preview's own prompt, seed, size and inputs")
generate.add_argument('--out', type=Path, required=True)
generate.add_argument('--width', type=int, default=1344)
generate.add_argument('--height', type=int, default=768)
duration = generate.add_mutually_exclusive_group()
duration.add_argument('--frames', type=int, help='Frame count (rounded up); continuation requires 39, 56, 73, ... total frames')
duration.add_argument('--seconds', type=float)
generate.add_argument('--continuation-snapshot', type=Path, help=argparse.SUPPRESS)
generate.add_argument('--continuation-snapshot-sha256', help=argparse.SUPPRESS)
for command in (generate, encode):
command.add_argument('--encoder-python', '--comfy-python', dest='comfy_python',
default=os.environ.get('FREEVIDEO_COMFY_PYTHON', sys.executable))
command.add_argument('--encoder-root', '--comfy-root', dest='comfy_root', type=Path)
command.add_argument('--model-paths', type=Path, help='Optional ComfyUI extra_model_paths.yaml')
command.add_argument('--encoder', default='qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors')
bench = sub.add_parser('bench', help='Compare attention backends under one explicit policy')
bench.add_argument('arguments', nargs=argparse.REMAINDER)
calibrate = sub.add_parser('calibrate',
help='Measure the placement questions this machine can settle')
calibrate.add_argument('arguments', nargs=argparse.REMAINDER)
args = parser.parse_args()
if args.command == 'generate':
from .continuation import validate_frames, validate_route
if args.continue_anchor is not None and args.continue_from is None:
raise ValueError('--continue-anchor requires --continue-from')
if args.continue_from is not None:
if args.frames is not None:
validate_frames(args.frames)
validate_route(task=args.task or ('ref2va' if args.continue_anchor else 't2va'),
anchor=args.continue_anchor is not None, two_pass=args.two_pass, preview=args.preview,
refine_from=args.refine_from)
if sys.platform == 'darwin' and args.command in ('plan', 'generate', 'encode', 'doctor'):
if args.command == 'generate':
from .media_request import read
from .original_audio import original, AudioUseError
if args.audio is not None or args.audio_use == 'original' or original(read(args.media)) is not None:
raise AudioUseError('audio_original_backend')
from .macos_generate import dispatch
return dispatch(args)
if args.command == 'plan':
from .geometry import geometry
canvas = geometry(args.width, args.height, frames=args.frames, seconds=args.seconds)
from .two_pass import render_canvas
canvas = render_canvas(canvas)[0]
hardware = Hardware.from_dict(json.loads(args.hardware_json.read_text(encoding='utf-8'))) if args.hardware_json else detect()
available = {'sage2', 'cudnn', 'torch-flash', 'fa2', 'fa4'} if args.hardware_json else available_backends(hardware, probe_missing=False)
policy = choose(hardware, **{key: getattr(args, key) for key in
['vram_gib', 'ram_gib', 'attention', 'gpu_reserve_gib', 'ram_reserve_gib']},
available_backends=available, canvas=canvas)
write_json(policy.to_dict(), args.out)
elif args.command == 'doctor':
from .doctor import doctor
result = doctor(probe=args.probe)
if args.out:
from .monitoring import save
save(args.out, result)
write_json(result)
if args.probe and not result['ready']:
raise SystemExit(1)
if args.require_paths and not all(row['exists'] for row in result['paths'].values()):
raise SystemExit(1)
elif args.command == 'setup':
from .install import install
install(args.vdn_root, packages=args.install_packages)
if args.fa4_guard:
from .fa4_guard import prepare
write_json({'fa4_overlay': str(prepare())})
elif args.command == 'prepare':
from .paths import add_vdn
add_vdn()
from .weights import prepare as prepare_bf16
from .fp8 import prepare as prepare_fp8
source = args.bf16_source or prepare_bf16(args.base, args.checkpoint, args.cache_root)
write_json({'cache': str(prepare_fp8(source, args.cache_root, base=args.base, checkpoint=args.checkpoint))})
elif args.command == 'generate':
from .generate import run
run(args)
elif args.command == 'encode':
from .encode import run
run(args)
else:
from .benchmark import main as benchmark
benchmark(args.arguments)