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.
"""One local FP8 request, reusing the native ComfyUI encoder in a separate child.
Use a saved profile or select placement from current available resources.
The parent imports no tensor runtime. Standalone requests use fresh workers;
ComfyUI can reuse an isolated worker and reclaim its idle models. Both paths
share the exclusive GPU-work lock and monitor the actual compute process.
"""
import argparse
import json
import os
import re
from pathlib import Path
import signal
import subprocess
import sys
import shutil
import time
from contextlib import nullcontext
from .locking import runtime_lock, LOCK_ENV
from .paths import vdn_root, comfy_root
from .monitoring import save
from .encoder_checkpoint import preflight_encoder
from .music_request import without_music
from . import tuning
from . import processes
from .system import (inference_headroom, inference_memory_sample, inference_environment, memory_sample,
windows, inference_pressure, inference_emergency_floor, ram_budget_is_estimate)
from .adaptive import (WorkerExit, classify_failure, local_identity, history_path,
attempt_geometry, execute_attempts, complete_observation, benchmark_allocator_limit)
from .resource_history import ResourceHistory
# A worker that exits after a CUDA error normally does so at once. One whose
# driver teardown never returns would otherwise hold the request forever, so
# the controller ends a worker that recorded this failure and is still running.
FAILED_WORKER_GRACE_SECONDS = 20.
class FailureReceipt:
"""Whether the worker's metrics file records a request ended by a CUDA error."""
def __init__(self, command):
self.path = self.stamp = None
self.found = False
self.since = time.time_ns() # A receipt left by an earlier request is not this worker's.
try:
request = json.loads(Path(command[command.index('--request') + 1]).read_text(encoding='utf-8'))
self.path = Path(request['metrics']) if request.get('metrics') else None
except (ValueError, IndexError, KeyError, OSError, TypeError):
pass
def recorded(self):
if self.path is None or self.found:
return self.found
try:
status = self.path.stat()
stamp = (status.st_mtime_ns, status.st_size)
if stamp == self.stamp or status.st_mtime_ns < self.since:
return False
metrics = json.loads(self.path.read_text(encoding='utf-8'))
except (OSError, ValueError):
return False # Unreadable or half written: read again at the next poll.
self.stamp = stamp
failure = metrics.get('failure') if isinstance(metrics, dict) else None
self.found = (isinstance(failure, dict) and metrics.get('success') is False
and failure.get('kind') == 'cuda_error')
return self.found
def child(command, env, descriptor, log, *, ram_budget_bytes=None, gpu=None, on_start=None,
minimum_available_bytes=None, ram_budget_is_estimate=False):
from .ram import ProcessMemory
memory = ProcessMemory() if ram_budget_bytes is not None else None
telemetry = {}
monitor = None
from .exit_diagnostics import exit_reading, memory_sample
# A worker that the system ends cannot report its own memory: this process reads it.
telemetry['memory_at_start'] = memory_sample()
with log.open('w', encoding='utf-8') as stream:
from .resident_process import ENV, RemoteProcess, SessionRestarted
module = command[command.index('-m')+1] if '-m' in command else None
process = None
if env.get(ENV) and module in ('freevideo_engine.worker', 'freevideo_engine.encode_worker'):
try:
process = RemoteProcess(env[ENV], command, env, descriptor, log)
except SessionRestarted as error:
env = dict(env)
env.pop(ENV, None)
os.environ.pop(ENV, None)
print(json.dumps({'event': 'resident_session_restart', 'reason': str(error)}), flush=True)
if process is None:
process = processes.popen(command, env=env, stdout=stream, stderr=subprocess.STDOUT,
pass_fds=(descriptor,), start_new_session=True)
pending_error = None
receipt = FailureReceipt(command)
failed_since = None
try:
if on_start:
on_start(process.pid)
if gpu:
from .monitoring import Monitor
monitor = Monitor(log.with_suffix('.gpu.csv'), device=gpu, pid=process.pid).start()
while process.poll() is None:
if memory:
sample = memory.sample(process.pid)
telemetry.setdefault('ram_start', sample)
telemetry['ram_last'] = sample
pressure = inference_pressure(sample, ram_budget_bytes, minimum_available_bytes,
budget_is_estimate=ram_budget_is_estimate)
telemetry['ram_guard'] = pressure
if pressure['reasons'] and not pressure['enforced_reasons']:
# Keep the first crossing even when later samples return
# below the estimate. Let the OS reclaim/page memory; do
# not trim another application's working set or alter its
# pagefile settings. One event per worker, not per sample.
if 'ram_budget_warning' not in telemetry:
telemetry['ram_budget_warning'] = dict(pressure)
print(json.dumps(dict(event='ram_budget_warning', **pressure)), flush=True)
if pressure['enforced_reasons']:
detail = ''
if pressure.get('commit_available_bytes') is not None:
if pressure.get('physical_available_bytes') is not None:
detail = ' Physical RAM available %.2f GiB;' % (pressure['physical_available_bytes']/2**30)
detail += ' Windows commit headroom %.3f GiB.' % (pressure['commit_available_bytes']/2**30)
if pressure['commit_available_bytes'] <= pressure['emergency_floor_bytes']:
detail += ' Windows commit headroom exhausted; this is separate from physical RAM usage.'
raise MemoryError(('RAM guard: %s. Working RAM %.2f GiB / budget %.2f GiB; '
'available physical/commit headroom %.2f GiB / emergency floor %.3f GiB.' %
(', '.join(pressure['enforced_reasons']), pressure['working_bytes']/2**30,
ram_budget_bytes/2**30, pressure['available_bytes']/2**30,
pressure['emergency_floor_bytes']/2**30)) + detail)
if receipt.recorded():
failed_since = time.monotonic() if failed_since is None else failed_since
if time.monotonic() - failed_since >= FAILED_WORKER_GRACE_SECONDS:
telemetry['worker_unresponsive_after_failure_seconds'] = time.monotonic() - failed_since
telemetry['worker_exit'] = dict(exit_reading(None), memory=memory_sample())
print(json.dumps({'event': 'worker_ended_after_failure',
'seconds': telemetry['worker_unresponsive_after_failure_seconds']}), flush=True)
raise WorkerExit(None, log)
try:
process.wait(timeout=.5)
except subprocess.TimeoutExpired:
pass
code = process.returncode
if code:
telemetry['worker_exit'] = dict(exit_reading(code), memory=memory_sample())
raise WorkerExit(code, log)
except BaseException as error:
pending_error = error
try:
processes.stop(process)
except BaseException as stop_error:
# A stop timeout is not a controlled timeout. The worker may
# still own CUDA; never convert this into an ordinary retry.
# A worker observed gone afterwards owns nothing, whatever the
# signal call reported while it was exiting.
if not processes.gone(process):
error.worker_stop_confirmed = False
error.worker_stop_error = repr(stop_error)
error.telemetry = telemetry
raise
finally:
cleanup_errors = []
for name, observed, suffix in (('ram', memory, '.memory.json'), ('gpu', monitor, '.gpu.json')):
if observed is not None:
try:
telemetry[name] = observed.result() if name == 'ram' else observed.stop()
save(log.with_suffix(suffix), telemetry[name])
except BaseException as error:
cleanup_errors.append(error)
if cleanup_errors:
if pending_error is None:
raise cleanup_errors[0]
pending_error.cleanup_errors = [repr(error) for error in cleanup_errors]
return telemetry
def main():
from .cli import main as cli
sys.argv.insert(1, 'generate')
cli()
def suggest_alternatives(error, hardware, options):
"""Name smaller requests this GPU can run now, when only VRAM refused this one.
A request with a new prompt is first planned for its text encoder, which
already applies the video stage's VRAM floor, so that is where most
refusals happen. Suggestions are planned for the video stage either way.
"""
if error.details.get('insufficient') != ['gpu'] or not options.get('canvas'):
return
from .policy import describe_alternatives, feasible_alternatives
try:
rows = feasible_alternatives(hardware, options['canvas'],
**{key: value for key, value in options.items() if key not in ('canvas', 'stage')})
except Exception: # A suggestion is advisory; the refusal stands as planned.
return
if rows:
error.details['alternatives'] = rows
error.args = (str(error) + '\n' + describe_alternatives(rows),)
def low_memory_mode(engine):
"""The placements that trade speed for a smaller GPU working set, if this plan uses them."""
if engine.get('residual_offload') or engine.get('attention_cpu_outputs'):
return dict(staging=bool(engine.get('residual_offload')), host_outputs=bool(engine.get('attention_cpu_outputs')))
return None
def automatic_profile(args, canvas, *, stage, evidence, descriptor=None, environment=None):
"""Plan with idle-cache accounting; reclaim once if it prevents admission."""
from .hardware import detect
from .policy import choose, ResourceBudgetError
from .kernel_capabilities import available_backends
from .resident_process import credit, release_idle_cache, ENV, SessionRestarted
environment = os.environ if environment is None else environment
for attempt in range(2):
raw = detect()
encoding_stage = stage == 'before-encoding' and bool(getattr(args, 'prompt_file', None))
hardware, state = credit(raw, environment, reuse_encoder=encoding_stage)
row = dict(stage=stage, raw=raw.to_dict(), adjusted=hardware.to_dict(), idle_cache=state)
from .system import system_memory
try:
row['system_memory'] = system_memory()
except (OSError, RuntimeError):
pass
evidence.append(row)
try:
# What this machine has demonstrably held, for the weight cache
# only. None on a first run, which leaves the plan unchanged.
from .adaptive import demonstrated_local_ram
options = {key: getattr(args, key) for key in
('vram_gib', 'ram_gib', 'attention', 'gpu_reserve_gib', 'ram_reserve_gib')}
planning_canvas = dict(canvas)
if getattr(args, 'task', None):
planning_canvas['task'] = args.task
if getattr(args, 'step_cache', None):
# The planner keeps the first-block cache only where it fits.
planning_canvas['step_cache'] = args.step_cache
kernels = {}
offered = available_backends(hardware, probe_missing=False, evidence=kernels)
row['attention_backends'] = dict(kernels, offered=sorted(offered))
options.update(available_backends=offered, canvas=planning_canvas,
demonstrated_ram_bytes=demonstrated_local_ram(hardware, args, canvas))
cache = getattr(args, 'cache', None)
if cache is not None and (Path(cache) / 'manifest.json').is_file():
manifest = json.loads((Path(cache) / 'manifest.json').read_text(encoding='utf-8'))
options['precision'] = 'int8' if manifest.get('precision') == 'int8' else 'fp8'
if getattr(args, '_lora_max_block_bytes', 0):
options['lora_max_block_bytes'] = args._lora_max_block_bytes
if getattr(args, '_lora_root_bytes', 0):
options['lora_root_bytes'] = args._lora_root_bytes
if encoding_stage:
options['stage'] = 'encoding'
try:
selected = choose(hardware, **options)
except ResourceBudgetError as estimate:
details = estimate.details
cache_cannot_resolve = (attempt or not state or not environment.get(ENV) or
details['gpu_capacity_bytes'] - details['gpu_reserve_bytes'] < details['gpu_minimum_bytes'])
if (details['insufficient'] != ['gpu'] or details.get('gpu_requirement') != 'estimated_working_set'
or not cache_cannot_resolve):
raise
selected = choose(hardware, **options, allow_capacity_trial=True)
row.update(capacity_trial=True, resource_error=details)
row['status'] = 'admitted'
profile = selected.legacy_profile()
if 'steps' in canvas:
profile['engine']['steps'] = canvas['steps']
profile['policy']['engine']['steps'] = canvas['steps']
row['budget_bytes'] = dict(gpu=profile['gpu_budget_gb']*1e9, ram=profile['inference_ram_budget_gb']*1e9)
row['reserve_bytes'] = dict(gpu=profile.get('policy', {}).get('gpu_system_reserve_bytes'),
ram=profile.get('policy', {}).get('ram_system_reserve_bytes'))
# Encoding is finished. Do not keep its process if its retained
# working set already leaves less than the model loader's existing
# 2 GiB increment inside the new whole-process RAM budget. Release
# under the lease, then actually measure recovered commit/physical
# capacity; never invent commit credit for GPU or mapped weights.
memory = (state.get('memory') or {}) if state else {}
used = memory.get('guard_bytes')
mapped = memory.get('reclaimable_mapped_bytes')
commit = memory.get('system_commit_available_bytes')
# A read-only text-encoder checkpoint is cheap in the working-set
# guard, but Windows still charges its section view to Commit until
# the resident worker exits. The old test only looked at
# ``guard_bytes`` and therefore retained a 14--16 GiB mapping on a
# 30 GiB machine: the next stage then had a 5.5 GiB budget and
# reopened roughly 20 GiB of transformer weights on every step.
# Releasing the idle worker is safe after conditioning is saved and
# is preferable to letting Commit fall through the emergency floor.
# Require both measurements so a missing/incomplete Windows sample
# never causes a speculative restart. On machines with genuine
# commit headroom the resident encoder remains reusable.
# Only Windows section views consume Commit while looking small in
# the working-set guard. Linux mappings are already represented by
# MemAvailable/cgroup accounting and must not trigger a Windows
# style encoder restart.
mapped_commit_pressure = (
hardware.system == 'Windows' and
type(mapped) is int and mapped >= 4 * 2**30 and
type(commit) is int and commit >= 0 and
commit < mapped + 2 * 2**30)
encoder_idle = state and any(m.get('role') == 'encoder' for m in state.get('models', []))
# The plan counted the idle encoder's memory as reclaimable. If it
# still streams every transformer block from disk with nothing
# retained, actually reclaim it: a 16 GiB RTX 3060 Laptop kept the
# encoder's 4.5 GiB while each step reread 21.6 GB of weights with
# no room left for host read-ahead. Machines that retain weights
# keep the encoder for the next prompt.
from .policy import BLOCK_BYTES
engine = profile['engine']
before, after = getattr(raw, 'ram_available', None), getattr(hardware, 'ram_available', None)
credited = after - before if type(before) is int and type(after) is int else 0
retention_starved = (engine.get('stream_weights') is True and credited >= 2 * 2**30
and engine.get('pin_host_gb', 0.) * 1e9 < BLOCK_BYTES)
# The plan also counted the idle worker's GPU memory as free, but
# only a process exit is sure to return memory the model bank does
# not own. On a 6 GiB RTX 3060 Laptop the lowvram encoder's
# streaming buffers held 0.80 GiB allocated (1.68 GiB reserved),
# evicting the encoder released nothing, and the transformer,
# planned with zero resident blocks, ran out of memory in its second
# pass. The worker now frees those buffers after encoding; this
# covers anything else it still holds.
idle_gpu = state.get('reclaimable_gpu_bytes') if state else None
gpu_starved = (type(idle_gpu) is int and idle_gpu >= 256 * 2**20
and engine.get('resident_blocks', 0) == 0)
working_set_short = type(used) is int and used >= 0 and used + 2*2**30 > row['budget_bytes']['ram']
reclaim = (stage == 'after-encoding' and not attempt and encoder_idle and environment.get(ENV)
and (working_set_short or mapped_commit_pressure or retention_starved or gpu_starved))
if not reclaim:
return hardware, state, profile
reason = ('Idle encoder working set leaves insufficient model-loading room' if working_set_short
else 'Idle encoder mapping leaves insufficient Windows Commit headroom' if mapped_commit_pressure
else 'Idle encoder GPU memory leaves the transformer no spare VRAM' if gpu_starved
else 'Idle encoder memory leaves the transformer rereading every weight from disk')
row.update(status='reclaim-before-load', reason=reason,
mapped_bytes=mapped if type(mapped) is int else None,
commit_available_bytes=commit if type(commit) is int else None)
except ResourceBudgetError as error:
from .exit_diagnostics import own_memory
own = dict(own_memory())
resident = ((state or {}).get('memory') or {})
if (resident.get('guard_metric') == 'tree private working set'
and type(resident.get('guard_bytes')) is int and resident['guard_bytes'] >= 0):
own['resident_private_working_set_bytes'] = resident['guard_bytes']
if own:
error.add_own_memory(own)
row['own_memory'] = own
row.update(status='rejected', resource_error=error.details)
error.resource_planning = evidence
impossible_capacity = any(error.details[name+'_capacity_bytes'] - error.details[name+'_reserve_bytes']
< error.details[name+'_minimum_bytes'] for name in error.details['insufficient'])
if attempt or impossible_capacity or not state or not environment.get(ENV):
suggest_alternatives(error, hardware, options)
raise
print(json.dumps(dict(event='release_idle_cache', stage=stage,
reason='Cached models prevent next-stage loading; releasing them and measuring again',
resources=row.get('resource_error', row.get('budget_bytes')))), flush=True)
lease_scope = runtime_lock() if descriptor is None else nullcontext(descriptor)
with lease_scope as lease:
try:
row['recovery'] = release_idle_cache(environment, lease)
except SessionRestarted:
row['recovery'] = dict(released=True, reason='Old worker already confirmed stopped')
environment.pop(ENV, None)
os.environ.pop(ENV, None)
def _runtime_libraries(error, record):
"""Check the cuDNN files when this process saw them refused, or when the
hardware probe, which imports torch, failed. Workers check their own failures."""
try:
from .runtime_libraries import mismatch, diagnose
if mismatch(error) or getattr(error, 'torch_probe_failed', False):
record['runtime_libraries'] = diagnose()
except Exception:
pass
def encoder_size_mismatch(encoding):
# Cache hits retain the checkpoint with the original request's metrics.
checkpoint = encoding.get('checkpoint') or (encoding.get('cache_source_metrics') or {}).get('checkpoint') or {}
return checkpoint.get('tested_size') is False
def run(args):
"""Also retain admission/import failures before the main request starts."""
output = Path(args.out).expanduser().resolve()
preexisting = any(path.exists() for path in (output, output.with_suffix('.request.json'),
output.with_suffix('.debug.json'), output.with_suffix('.artifacts')))
started = time.perf_counter()
try:
return _run(args)
except BaseException as error:
if not preexisting and not getattr(error, 'diagnostic_recorded', False):
from .diagnostic_resources import exception_details
from .support_report import write as write_debug, code_identity
planning = getattr(error, 'resource_planning', [])
record = dict(success=False, request_seconds=time.perf_counter()-started,
phase=planning[-1]['stage'] if planning else 'preflight', resource_planning=planning,
error_type=type(error).__name__, exception=exception_details(error),
error_message=str(error), resource_error=getattr(error, 'details', None), runtime_code=code_identity())
if getattr(error, 'code', None):
record['error_code'] = error.code
_runtime_libraries(error, record)
try:
save(output.with_suffix('.request.json'), record)
write_debug(output, record)
except (OSError, ValueError):
pass
raise
def upscale_factor(args):
"""The two-pass upscale factor a command asked for: 2 (the original half-size first pass) unless given."""
factor = getattr(args, 'upscale_factor', None)
return 2 if factor in (None, 2) else factor
def dialogue_reason(prompt):
"""Shared eligibility for opening-voice references and hidden dialogue tails."""
from .prompt_vlm.rules import split_source
if not prompt or not split_source(prompt)[2]:
return 'no_lines'
if re.search(r'(?i)\b(?:sing|sings|singing|sang|sung|lyrics)\b|唱', prompt):
return 'singing'
return None
def hide_tail_geometry(canvas, prompt, requested=False, *, preview=False, max_frames=None):
"""Plan the generated canvas while keeping the ordinary output duration."""
if not requested:
return canvas, None
from .continuation import HIDE_TAIL_FRAMES
from .geometry import geometry
# The product's longest selectable request is 60 seconds on the H3 grid.
limit = geometry(seconds=60)['frames'] if max_frames is None else max_frames
reason = 'preview' if preview else dialogue_reason(prompt)
if reason is None and canvas['frames'] + HIDE_TAIL_FRAMES > limit:
reason = 'too_long'
if reason is not None:
return canvas, dict(requested=True, used=False, reason=reason)
generated = dict(canvas, **geometry(canvas['width'], canvas['height'], frames=canvas['frames'] + HIDE_TAIL_FRAMES))
return generated, dict(requested=True, used=True, frames=HIDE_TAIL_FRAMES)
def _run(args):
from .hardware import detect
from .geometry import geometry
from .continuation import (validate_frames, validate_route, prepare as prepare_continuation,
summary as continuation_summary, validate_snapshot, persist_snapshot, restore_snapshot,
audio_context, MISSING as CONTINUATION_MISSING)
from .continuation_tail import pending as encoded_continuation, freeze as freeze_tail
continuation_directory = continuation_first = None
def freeze_continuation(value):
from .paths import base_path
return freeze_tail(value, canvas, continuation_first, continuation_directory,
profile['engine'].get('base') or base_path())
def usable_continuation(value, *check):
"""The stored context when it fits this run, otherwise the previous video's own ending."""
if 'tail' in value:
return value
try:
return validate_snapshot(value, *check)
except ValueError as error:
if str(error) != CONTINUATION_MISSING:
raise
# A record of another version, other weights or another first-pass size.
value = dict(encoded_continuation(continue_from, canvas),
**{key: value[key] for key in ('audio_context', 'source_video', 'anchor', 'pictures', 'sound', 'video_only')
if key in value})
return freeze_continuation(value) if continuation_directory is not None else value
frames = getattr(args, 'frames', None)
continue_from = getattr(args, 'continue_from', None)
continue_anchor = getattr(args, 'continue_anchor', None)
if continue_anchor is not None and continue_from is None:
raise ValueError('--continue-anchor requires --continue-from')
# Every part of a long video is asked alike; only a part that continues another can use it.
first_frame = None
voice_reference = (dict(requested=True, used=False, reason=None)
if getattr(args, 'voice_reference', False) and continue_from is not None else None)
if getattr(args, 'first_frame_reference', False) and continue_from is not None:
if continue_anchor is not None:
raise ValueError('Choose --first-frame-reference or --continue-anchor, not both')
first_frame = dict(requested=True, used=False)
from .media_request import read as read_media, task_for, cache_key
from .original_audio import cli_media, prepare_request
media = cli_media(args, read_media(getattr(args, 'media', None)))
original_audio, original_canvas = prepare_request(media, getattr(args, 'width', 1344),
getattr(args, 'height', 768), continuation=continue_from is not None)
if continue_from is not None and frames is not None:
validate_frames(frames)
canvas = original_canvas or geometry(getattr(args, 'width', 1344), getattr(args, 'height', 768),
frames=frames, seconds=getattr(args, 'seconds', None))
visible_canvas = canvas
canvas, hide_tail = hide_tail_geometry(canvas,
args.prompt_file.read_text(encoding='utf-8') if getattr(args, 'hide_tail', False) and args.prompt_file else None,
getattr(args, 'hide_tail', False) and original_audio is None,
preview=bool(getattr(args, 'preview', False) or getattr(args, 'refine_from', None)))
if original_audio is not None and getattr(args, 'hide_tail', False):
# The clip's samples set where the part ends; nothing is generated past them to hide.
hide_tail = dict(requested=True, used=False, reason='original_audio')
hide_tail_frames = hide_tail['frames'] if hide_tail and hide_tail['used'] else 0
continuation = None
from .two_pass import validate_steps
requested_steps = getattr(args, 'base_steps', None)
refine_steps = getattr(args, 'refine_steps', 3)
two_pass = getattr(args, 'two_pass', True)
preview = getattr(args, 'preview', False) is True
from .preview import validate_flags, source as preview_source
validate_flags(preview, getattr(args, 'refine_from', None), two_pass, requested_steps)
refine_source = preview_source(args.refine_from) if getattr(args, 'refine_from', None) else None
if requested_steps is not None:
validate_steps(requested_steps, refine_steps, two_pass)
if requested_steps != 8:
canvas['steps'] = requested_steps
if continue_anchor is not None:
from .continuation import anchor_media
media = anchor_media(media, continue_anchor)
# The cast's pictures, sent with a continued part like with a part that starts fresh.
# A clip used as is is the part's sound, not one of its pictures.
pictures = []
if continue_from is not None and continue_anchor is None and media.get('references'):
from .continuation import continuation_pictures
pictures = continuation_pictures(dict(media, references=[
row for row in media['references'] if row.get('use') != 'original']))
anchored = continue_anchor is not None or bool(pictures)
# Too small to sample cleanly: render larger, scale the picture down. Decided before anything
# compares or stores the canvas, so every later check sees the size that is sampled.
from .two_pass import sampling_canvas
canvas, output_size = sampling_canvas(canvas, staged=bool(preview or refine_source), media=media,
conditioned=bool(args.conditioning))
if continue_from is not None:
validate_route(task=getattr(args, 'task', None) or ('ref2va' if anchored else 't2va'),
anchor=anchored, two_pass=two_pass,
preview=preview, refine_from=getattr(args, 'refine_from', None), media=media,
original_audio=original_audio is not None and 'segment' in original_audio)
# Reject absent/mismatched context before text encoding or model loading.
preview_encoded = False
if refine_source:
from .preview import continuation_snapshot
snapshot, digest, preview_encoded = continuation_snapshot(refine_source, continue_from)
continuation = restore_snapshot(snapshot, digest, canvas)
elif getattr(args, 'continuation_snapshot', None):
continuation = restore_snapshot(args.continuation_snapshot,
getattr(args, 'continuation_snapshot_sha256', None), canvas)
else:
try:
continuation = prepare_continuation(continue_from, canvas)
except ValueError as error:
if str(error) != CONTINUATION_MISSING:
raise
# Nothing was stored for this file: its own ending is encoded when the run starts.
continuation = encoded_continuation(continue_from, canvas)
continuation = dict(continuation, audio_context=audio_context(), source_video=str(continue_from))
if original_audio is not None:
from .original_audio_chain import validate_continuation
validate_continuation(original_audio, continuation)
continuation.update(video_only=True, audio_context='clean')
if first_frame is not None and original_audio is not None:
# The clip used as is is the part's only audio row; no first-frame picture is added beside it.
first_frame['reason'] = 'original_audio'
elif first_frame is not None and pictures:
# The cast's pictures already hold the people; the film's first frame is not added to them.
first_frame['reason'] = 'pictures'
elif first_frame is not None:
from .continuation import anchor_media, chain_first_frame_picture
try:
# A context encoded from the file carries no first frame; whoever planned this run saw none either.
kept = (None if 'tail' in continuation or preview_encoded
else chain_first_frame_picture(continuation, continue_from))
except ValueError:
kept = None
first_frame['reason'] = 'unreadable'
if kept is None:
# Optional help: the part is made as an ordinary continuation and the report says why.
first_frame.setdefault('reason', 'source_predates')
else:
if args.out.resolve().exists():
raise FileExistsError(args.out.resolve())
args.out.resolve().parent.mkdir(parents=True, exist_ok=True)
picture, picture_width, picture_height = kept
# A second pass names the same picture its preview was made with.
continue_anchor = None
if refine_source:
from .preview import continuation_anchor
continue_anchor = continuation_anchor(refine_source)
if continue_anchor is None:
continue_anchor = args.out.resolve().with_suffix('.first-frame.png')
continue_anchor.write_bytes(picture)
media = anchor_media(media, continue_anchor)
validate_route(task=getattr(args, 'task', None) or 'ref2va', anchor=True, two_pass=two_pass,
preview=preview, refine_from=getattr(args, 'refine_from', None), media=media)
first_frame.update(used=True, width=picture_width, height=picture_height)
anchored = True
if anchored:
continuation['anchor'] = media['references'][0]
if pictures:
continuation['pictures'] = len(pictures)
if voice_reference is not None:
if original_audio is not None:
voice_reference['reason'] = 'original_audio'
elif first_frame is not None and not pictures:
voice_reference['reason'] = 'first_frame'
elif continue_anchor is not None:
voice_reference['reason'] = 'anchor'
elif args.conditioning:
# Preencoded conditioning cannot take another reference.
voice_reference['reason'] = 'conditioning'
else:
voice_reference['reason'] = dialogue_reason(
args.prompt_file.read_text(encoding='utf-8') if args.prompt_file else None)
active_loras = [row for row in media.get('loras', []) if row['strength'] != 0]
if media:
inferred_task = task_for(media)
structural = any(media.get(k) for k in ('first', 'last', 'references', 'conditioning_info'))
if structural and getattr(args, 'task', None) and args.task != inferred_task:
raise ValueError('Explicit task disagrees with the media input')
args.task = inferred_task if structural or not getattr(args, 'task', None) else args.task
if args.conditioning and any(media.get(k) for k in ('first', 'last', 'references')):
raise ValueError('Preencoded conditioning already includes media; use conditioning_info, not another set of files')
base_cache = args.cache
from .resident_process import credit
planning = []
if args.profile:
hardware, resident_credit = credit(detect())
profile = json.loads(args.profile.read_text(encoding='utf-8'))
else:
from .policy import ResourceBudgetError
try:
hardware, resident_credit, profile = automatic_profile(args, canvas, stage='before-encoding', evidence=planning)
except ResourceBudgetError:
if not hide_tail_frames:
raise
# The optional tail must fit this size/step tier too. Re-admit the
# original duration before encoding anything; never shorten it.
canvas, output_size = sampling_canvas(dict(canvas, **visible_canvas),
staged=bool(preview or refine_source), media=media, conditioned=bool(args.conditioning))
hardware, resident_credit, profile = automatic_profile(args, canvas, stage='before-encoding', evidence=planning)
hide_tail, hide_tail_frames = dict(requested=True, used=False, reason='too_long'), 0
if continuation is not None:
from .continuation import OVERLAP_FRAMES
continuation = dict(continuation, new_frames=canvas['frames'] - OVERLAP_FRAMES)
print(json.dumps(dict(event='compute_device', backend='CUDA', name=getattr(hardware, 'gpu_name', None),
uuid=getattr(hardware, 'gpu_uuid', None), vram_total_bytes=getattr(hardware, 'vram_total', None),
vram_free_bytes=getattr(hardware, 'vram_free', None))), flush=True)
allocator_limit_bytes = benchmark_allocator_limit(profile, getattr(args, 'allocator_limit_gib', None), hardware)
if 'gpu_budget_bytes' in profile:
profile = dict(gpu_budget_gb=profile['gpu_budget_bytes'] / 1e9,
inference_ram_budget_gb=profile['ram_budget_bytes'] / 1e9,
engine=profile['engine'], decoder=profile['decoder'],
allocator_config=profile['allocator_config'], policy=profile)
base_steps = requested_steps if requested_steps is not None else profile['engine'].get('steps', 8)
validate_steps(base_steps, refine_steps, two_pass)
profile['engine']['steps'] = base_steps
if args.profile and getattr(args, 'step_cache', None):
profile['engine']['step_cache'] = args.step_cache
if 'engine' in profile.get('policy', {}):
profile['policy']['engine']['steps'] = base_steps
if base_steps != 8:
canvas['steps'] = base_steps
if args.base:
profile['engine']['base'] = str(args.base.resolve())
if args.checkpoint:
profile['engine']['checkpoint'] = str(args.checkpoint.resolve())
if getattr(args, 'task', None):
profile['engine']['task'] = args.task
if allocator_limit_bytes is not None:
profile['benchmark_allocator_limit_bytes'] = allocator_limit_bytes
if args.out.suffix.lower() != '.mp4':
raise ValueError('--out must name an MP4 file')
manifest = json.loads((args.cache / 'manifest.json').read_text(encoding='utf-8'))
if continuation is not None:
from .two_pass import plan as continuation_plan
validate_route(task=profile['engine'].get('task', 't2va'), anchor=anchored,
original_audio=original_audio is not None)
planned = continuation_plan(canvas, two_pass, base_steps=base_steps, refine_steps=refine_steps,
staged=bool(preview or refine_source), scale=upscale_factor(args))
if two_pass and not planned['enabled'] and base_steps != 8:
raise ValueError(planned['reason'] + ' A continuation needs two-pass generation.')
continuation_first = planned['first']
continuation = usable_continuation(continuation, canvas, None if active_loras else manifest, planned)
if manifest.get('precision') not in ('fp8', 'int8', 'bf16'): # BF16: the unquantized reference
raise ValueError('Select the prepared official FP8 or int8 cache')
destination = args.out.resolve()
if destination.exists():
raise FileExistsError(destination)
destination.parent.mkdir(parents=True, exist_ok=True)
artifacts = destination.with_suffix('.artifacts')
artifacts.mkdir(exist_ok=False)
continuation_directory = artifacts
if continuation is not None and 'tail' in continuation:
continuation = freeze_continuation(continuation)
elif continuation is not None and 'snapshot' not in continuation:
continuation = persist_snapshot(continuation, artifacts / 'continuation-source.safetensors')
if args.prompt_file:
shutil.copyfile(args.prompt_file, artifacts / 'prompt.txt')
repo = Path(__file__).resolve().parents[1]
report = {'profile': profile, 'seed': args.seed, 'success': False, 'geometry': canvas,
**({'output_size': output_size} if output_size else {}),
'resource_planning': planning,
'artifacts': str(artifacts),
'idle_resources': dict(automatic=not bool(args.profile), system=hardware.system,
vram_gib=getattr(args, 'vram_gib', None),
gpu_reserve_gib=getattr(args, 'gpu_reserve_gib', None),
allocator_limit_bytes=allocator_limit_bytes),
'reclaimable_resident_models': resident_credit,
'encoder_mode': 'native H3 encoder library child' if args.prompt_file else 'preencoded shared conditioning'}
if continuation is not None:
report['continuation'] = continuation_summary(continuation, hide_tail_frames=hide_tail_frames)
if 'tail' in continuation:
report['continuation']['context'] = 'encoded'
report['audio_context'] = continuation['audio_context']
if continue_anchor is not None:
report['continue_anchor'] = continuation['anchor']
if pictures:
report['continue_pictures'] = len(pictures)
if first_frame is not None:
report['first_frame_reference'] = first_frame
if voice_reference is not None:
report['voice_reference'] = voice_reference
if hide_tail is not None:
report['hide_tail'] = hide_tail
if hide_tail_frames:
report['output_frames'] = (report['continuation']['new_frames'] if continuation is not None
else canvas['frames'] - hide_tail_frames)
from .support_report import code_identity, write as write_debug
report['runtime_hardware'] = hardware.to_dict()
from .device_index import card_report
report['gpu_card'] = card_report(hardware)
report['runtime_code'] = code_identity()
started = time.perf_counter()
applied = None
def interrupted(signum, frame):
raise KeyboardInterrupt(f'Request interrupted by signal {signum}')
previous = processes.termination_handler(interrupted)
try:
with runtime_lock() as descriptor:
if active_loras:
lora_request = artifacts / 'lora-request.json'
lora_result = artifacts / 'lora-result.json'
save(lora_request, {'cache': str(args.cache.resolve()), 'adapters': active_loras, 'result': str(lora_result),
'mode': 'online' if profile['engine'].get('head_chunk') and profile['engine'].get('inference_kernels') else 'fused'})
lora_env = dict(os.environ, PYTHONPATH=str(repo), CUDA_VISIBLE_DEVICES='', PYTHONUNBUFFERED='1')
lora_env[LOCK_ENV] = str(descriptor)
print(json.dumps({'event': 'lora_prepare_start'}), flush=True)
report['lora_resources'] = child([sys.executable, '-m', 'freevideo_engine.lora_cache', '--request', str(lora_request)],
lora_env, descriptor, destination.with_suffix('.lora.log'),
ram_budget_bytes=profile['inference_ram_budget_gb'] * 1e9)
prepared = json.loads(lora_result.read_text(encoding='utf-8'))
args.cache = Path(prepared['cache'])
report['lora'] = prepared['report']
args._lora_max_block_bytes = prepared['report'].get('max_block_bytes', 0)
args._lora_root_bytes = prepared['report'].get('root_bytes', 0)
if continuation is not None:
continuation = usable_continuation(continuation, canvas,
json.loads((args.cache / 'manifest.json').read_text(encoding='utf-8')))
if 'tail' in continuation:
report['continuation']['context'] = 'encoded'
if args._lora_max_block_bytes or args._lora_root_bytes:
profile.setdefault('policy', {})['lora_max_block_bytes'] = args._lora_max_block_bytes
profile['policy']['lora_root_bytes'] = args._lora_root_bytes
if voice_reference is not None and voice_reference['reason'] is None:
# Model identity, first-pass size and LoRA admission may have switched this
# request to tail encoding. Decide only after those checks, before encoding media.
if 'tail' in continuation:
voice_reference['reason'] = 'source_predates'
else:
from .continuation import chain_first_sound, unpack_first_sound
try:
kept = chain_first_sound(continuation, continue_from)
sound = unpack_first_sound(kept) if kept is not None else None
except ValueError:
sound = None
if sound is None:
voice_reference['reason'] = 'unreadable'
else:
path = destination.with_suffix('.first-sound.wav')
path.write_bytes(sound)
from .media_request import digest
# After the cast's pictures: the sound is the last reference.
media = dict(media, version=1, references=[*media.get('references', []), dict(kind='audio',
path=str(path), sha256=digest(path), bytes=path.stat().st_size)])
validate_route(task=getattr(args, 'task', None) or ('ref2va' if anchored else 't2va'), sound=True,
anchor=anchored, two_pass=two_pass,
preview=preview, refine_from=getattr(args, 'refine_from', None), media=media)
continuation['sound'] = media['references'][-1]
args.task = profile['engine']['task'] = task_for(media)
voice_reference['used'] = True
resource_identity = local_identity(hardware, args.cache)
history = ResourceHistory(history_path())
history.recover_pending()
report['resource_history'] = str(history.path)
state = None
input_cache = None
report['tuning'] = {'profile_id': None, 'conditioning_cache_hit': False}
report['input_cache'] = {'enabled': False, 'conditioning_hit': False}
if not args.profile and not getattr(args, 'no_tuning', False):
machine_path = tuning.state_path().parents[1] / 'machine.json'
if machine_path.is_file():
try:
machine = json.loads(machine_path.read_text(encoding='utf-8'))
same_inputs = (base_cache.resolve() == Path(machine['cache']).resolve()
and args.encoder == machine['encoder']
and Path(args.comfy_python).absolute() == Path(machine['comfy_python']).absolute()
and (args.comfy_root or comfy_root()).resolve() == Path(machine['comfy_root']).resolve()
and args.model_paths and args.model_paths.resolve() == Path(machine['model_paths']).resolve())
if same_inputs:
# The text cache needs only the encoder and its code: no git, no video models.
from .input_cache import InputCache
input_cache = InputCache(tuning.text_identity(machine, hardware))
report['input_cache'].update(enabled=True, directory=str(input_cache.root))
identity = tuning.identity(machine, hardware)
state, reason = tuning.load_state(identity)
if active_loras:
state, reason = None, 'LoRA uses its own model history; encoder cache remains reusable'
report['tuning']['note'] = reason
else:
report['tuning']['note'] = 'Explicit model/encoder paths differ from the optimized installation'
except (OSError, ValueError, KeyError, subprocess.SubprocessError) as error:
report['tuning']['note'] = 'Could not validate saved tuning: ' + str(error)
else:
report['tuning']['note'] = 'Saved optimization bypassed by --no-tuning or --profile'
if state:
report['tuning']['baseline_report'] = state.get('baseline_report')
report['tuning']['optimization_report'] = state.get('optimization_report')
save(destination.with_suffix('.request.json'), report)
temporary = artifacts
allocator = profile.get('allocator_config', os.environ.get('PYTORCH_ALLOC_CONF',
os.environ.get('PYTORCH_CUDA_ALLOC_CONF', 'backend:native,pinned_max_round_threshold_mb:128')))
profile['allocator_config'] = allocator
env = dict(os.environ, HF_HUB_OFFLINE='1', TRANSFORMERS_OFFLINE='1', PYTHONUNBUFFERED='1',
PYTORCH_ALLOC_CONF=allocator, PYTORCH_CUDA_ALLOC_CONF=allocator)
env[LOCK_ENV] = str(descriptor)
condition = temporary / 'conditioning.pt'
if refine_source:
# The preview's own conditioning: the exact file its first pass used.
condition = Path(refine_source['conditioning'])
if refine_source['report'].get('encoding'):
report['encoding'] = dict(refine_source['report']['encoding'], reused_from_preview=True)
print(json.dumps({'event': 'conditioning_reused', 'source': 'preview'}), flush=True)
elif args.conditioning:
shutil.copyfile(args.conditioning, condition)
if args.prompt_file and not refine_source:
prompt_text = args.prompt_file.read_text(encoding='utf-8')
# Checked before any cache lookup: a cached conditioning never stands in for the explicit permission.
if not prompt_text.strip() and getattr(args, 'allow_empty_prompt', False) is not True:
raise ValueError('A nonempty prompt is required')
if first_frame is not None and first_frame['used']:
# The saved prompt stays the user's own; the model is also told what the picture is.
from .continuation import first_frame_prompt
prompt_text = first_frame_prompt(prompt_text)
prompt_text = without_music(prompt_text)
encoding = {'prompt': prompt_text, 'encoder': args.encoder,
'comfy_root': str(args.comfy_root or comfy_root()),
'model_paths': str(args.model_paths.resolve()) if args.model_paths else None,
'output': str(condition), 'gpu_budget_gb': profile['gpu_budget_gb'],
'ram_budget_bytes': round(profile['inference_ram_budget_gb'] * 1e9),
'metrics': str(destination.with_suffix('.encoding.json')),
'diagnostic_output': str(destination)}
if getattr(args, 'allow_empty_prompt', False):
encoding['allow_empty_prompt'] = True
if media:
from .paths import base_path
encoding.update(media=media, geometry=canvas, base=profile['engine'].get('base') or str(base_path()),
reference_latent_cache=str(input_cache.root.parent.parent) if input_cache else None)
# Lets the encoder child read the video model while it computes, on a slow drive.
from .model_read_ahead import request_fields
if getattr(args, 'cache', None):
encoding.update(request_fields(args.cache, profile['engine'],
budget_is_estimate=ram_budget_is_estimate(args)))
conditioning_key = cache_key(encoding['prompt'], media, canvas)
encode_request = temporary / 'encode.json'
encode_request.write_text(json.dumps(encoding) + '\n', encoding='utf-8')
cached = input_cache.get(conditioning_key, condition) if input_cache else None
if cached and encoder_size_mismatch(cached):
cached = None
elif cached and (cached.get('success') is not True or cached.get('conditioning_shape', [])[1:] != [5120]):
condition.rename(condition.with_name('conditioning.cache-rejected-' + str(time.time_ns()) + '.pt'))
cached = None
if not cached and state and task_for(media) == 't2va':
cached = tuning.cached_conditioning(state, encoding['prompt'], condition)
if cached and encoder_size_mismatch(cached):
cached = None
if cached:
save(destination.with_suffix('.encoding.json'), cached)
destination.with_suffix('.encoding.log').write_text('Reused validated local text conditioning; encoder model was not loaded.\n', encoding='utf-8')
report['tuning']['conditioning_cache_hit'] = True
report['input_cache']['conditioning_hit'] = True
print(json.dumps({'event': 'conditioning_cache_hit'}), flush=True)
for trimmed in cached.get('reference_trims') or []:
print(json.dumps(dict(event='reference_trimmed', **trimmed)), flush=True)
else:
try:
preflight_encoder(args.comfy_root or comfy_root(), args.encoder, encoding['model_paths'])
except Exception as error:
# Only a missing encoder stops the run; the worker stays the judge of anything else.
if str(error).startswith('ENCODER_MODEL_MISSING:'):
raise
print(json.dumps(dict(event='encoder_preflight_skipped', error=repr(error)[:300])), flush=True)
encoder_env = dict(env, PYTHONPATH=str(repo))
print(json.dumps({'event': 'encoding_start'}), flush=True)
encoder_attempt = history.begin(resource_identity, {'encoder': args.encoder},
attempt_geometry(canvas, profile['engine']), purpose='encoding',
evidence={'reason': 'Text conditioning cache miss',
'request_artifacts': str(artifacts)})
report['encoding_attempt'] = encoder_attempt
save(destination.with_suffix('.request.json'), report)
try:
report['encoding_resources'] = child(
[args.comfy_python, '-m', 'freevideo_engine.encode_worker', '--request', str(encode_request)],
encoder_env, descriptor, destination.with_suffix('.encoding.log'),
ram_budget_bytes=profile['inference_ram_budget_gb'] * 1e9,
ram_budget_is_estimate=ram_budget_is_estimate(args),
minimum_available_bytes=inference_emergency_floor(profile['inference_ram_budget_gb'] * 1e9,
getattr(args, 'ram_reserve_gib', None)),
on_start=lambda pid: history.attach_worker(encoder_attempt, pid, phase='encoding'))
encoded = json.loads(destination.with_suffix('.encoding.json').read_text(encoding='utf-8'))
if encoded.get('success') is not True or not condition.is_file():
raise ValueError('Encoder exited without verified conditioning')
except BaseException as error:
try:
failed_encoding = json.loads(destination.with_suffix('.encoding.json').read_text(encoding='utf-8'))
except (OSError, ValueError):
failed_encoding = {}
failure = classify_failure(error, failed_encoding)
report['encoding_resources'] = getattr(error, 'telemetry', {})
report['encoding_failure'] = dict(phase=failed_encoding.get('phase', 'encoding'), failure=failure)
history.finish(encoder_attempt, failure['outcome'], details=failure)
raise
history.finish(encoder_attempt, 'success', details={'reason': 'Encoder exited with conditioning',
'encoding': encoded, 'resources': report.get('encoding_resources'),
'prompt_characters': len(encoding['prompt'])})
report['encoding'] = json.loads(destination.with_suffix('.encoding.json').read_text(encoding='utf-8'))
report['encoder_process_exited_before_video'] = not bool(os.environ.get('FREEVIDEO_RESIDENT_SESSION'))
cacheable = not cached and not encoder_size_mismatch(report['encoding'])
if input_cache and cacheable:
try:
report['input_cache']['conditioning_saved'] = input_cache.put(conditioning_key, condition, report['encoding'])
if input_cache.note:
report['input_cache']['note'] = input_cache.note
except (OSError, ValueError) as error:
report['input_cache']['note'] = str(error)
if state and cacheable and task_for(media) == 't2va':
try:
tuning.remember_conditioning(state, encoding['prompt'], condition, report['encoding'])
tuning.save_state(state)
except (OSError, ValueError) as error:
report['tuning']['cache_note'] = str(error)
# The encoder is done with the reference frames it normalized (over 1 GB per reference video).
for frames in (temporary / 'media').glob('*.npy'):
try:
frames.unlink(missing_ok=True)
except OSError:
pass # Windows keeps a file open; the next start's release frees it
info = report.get('encoding', {}).get('conditioning_info') or media.get('conditioning_info')
if info:
if any(info.get(k) != canvas[k] for k in ('width', 'height', 'frames')):
raise ValueError('Encoded media does not match the requested geometry')
for name in ('reference_video_tokens', 'reference_audio_tokens'):
count = info.get(name, 0)
if type(count) is not int or count < 0:
raise ValueError('Invalid reference token count')
canvas[name] = count
if 'early_reference' in info:
canvas['early_reference'] = info['early_reference']
profile['engine']['task'] = info['task']
if original_audio is not None:
# Include all clean clock constants in live re-planning;
# the original track adds no reference audio rows.
args.task = info['task']
if not condition.is_file():
raise FileNotFoundError(condition)
from .two_pass import plan as plan_sampling, ensure_checkpoint
sampling_plan = plan_sampling(canvas, two_pass, profile['engine'].get('task', 't2va'),
base_steps=base_steps, refine_steps=refine_steps,
staged=bool(preview or refine_source), scale=upscale_factor(args))
report['sampling_plan'] = sampling_plan
if continuation is not None:
validate_route(task=profile['engine'].get('task', 't2va'), anchor=anchored,
original_audio=original_audio is not None,
**(dict(sound=True, media=media) if voice_reference and voice_reference['used'] else {}))
continuation = usable_continuation(continuation, canvas,
json.loads((args.cache / 'manifest.json').read_text(encoding='utf-8')), sampling_plan)
if 'tail' in continuation:
report['continuation']['context'] = 'encoded'
if preview:
report['preview'] = dict(geometry=dict(sampling_plan['first'], fps=canvas['fps']))
if refine_source:
report['upscaled_preview'] = dict(output=refine_source['output'])
if sampling_plan['enabled'] or sampling_plan['version'] == 2:
canvas['sampling_plan'] = sampling_plan
print(json.dumps(dict(event='sampling_plan', **sampling_plan, **({'preview': True} if preview else {}))), flush=True)
save(destination.with_suffix('.request.json'), report)
upscaler_checkpoint = None
if sampling_plan.get('upscaler_sha256'):
print(json.dumps(dict(event='latent_upscaler_prepare')), flush=True)
upscaler_checkpoint = str(ensure_checkpoint())
if not args.profile:
# Encoding can take minutes; always recheck current free memory,
# even before any optimization has been saved.
hardware, resident_credit, live = automatic_profile(args, canvas, stage='after-encoding',
evidence=planning, descriptor=descriptor, environment=env)
report['reclaimable_resident_models'] = resident_credit
live['engine'].update({k: profile['engine'][k] for k in ('base', 'checkpoint', 'task', 'steps') if k in profile['engine']})
profile = live
report['profile'] = profile
report['low_memory_mode'] = low_memory_mode(profile['engine'])
if report['low_memory_mode']:
# Slower than usual but bounded; the panel says so while it runs.
print(json.dumps(dict(event='low_memory_mode', **report['low_memory_mode'])), flush=True)
from .prediction import predict
from .prediction_ui import show as show_prediction, errors as prediction_errors
condition_hash = tuning.digest(condition)
observations = history.observations(identity=resource_identity, limit=512, include_details=False)
tokens = info.get('text_tokens') if info else report.get('encoding', {}).get('conditioning_shape', [None])[0]
if tokens is None:
tokens = next((row['observation'].get('text_tokens', row.get('geometry', {}).get('text_tokens'))
for row in reversed(observations)
if row['observation'].get('conditioning_sha256') == condition_hash), None)
if state and args.attention == 'auto' and tokens is not None and sampling_plan['version'] in (1, 3):
profile, applied = tuning.apply_profile(state, profile, canvas, tokens)
report['profile'] = profile
report['tuning']['profile_id'] = applied
if allocator_limit_bytes is not None:
profile['benchmark_allocator_limit_bytes'] = allocator_limit_bytes
if not args.profile and not getattr(args, 'no_history_placement', False):
from .prediction_policy import select
profile, decision = select(profile, canvas, hardware, observations, resource_identity,
text_tokens=tokens)
report['history_placement'] = decision
report['profile'] = profile
from .adaptive import recovered_compute
profile, report['recovered_compute'] = recovered_compute(profile, history, resource_identity, canvas)
report['profile'] = profile
if report['recovered_compute']['applied'] or report['recovered_compute'].get('reprobe'):
print(json.dumps(dict(event='recovered_compute', **report['recovered_compute'])), flush=True)
from .compatibility import Store as CompatibilityStore, apply as apply_compatibility
compatibility_state = CompatibilityStore(history.path.parent).status(resource_identity, persist=True)
profile, report['compatibility'] = apply_compatibility(profile, compatibility_state)
report['profile'] = profile
if compatibility_state['level']:
print(json.dumps(dict(event='compatibility', **report['compatibility'])), flush=True)
def forecast(selected):
if not args.profile and report.get('resource_attempts'):
# A failed resident worker may have exited and returned tens
# of GiB. Refresh limits in both directions; keep the chosen
# recovery options so a replan cannot undo offload/recompute.
_, _, live = automatic_profile(args, canvas,
stage='retry-%d' % (len(report['resource_attempts']) + 1), evidence=planning,
descriptor=descriptor, environment=engine_env)
for key in ('gpu_budget_gb', 'inference_ram_budget_gb'):
selected[key] = live[key]
if 'policy' in selected:
selected['policy'].update({k: v for k, v in live.get('policy', {}).items()
if k not in ('engine', 'decoder')})
report['resource_prediction'] = predict(observations, resource_identity, selected, canvas, text_tokens=tokens)
show_prediction(report['resource_prediction'])
def validate(metrics, telemetry, selected):
observation = complete_observation(metrics, canvas, destination, artifacts, telemetry)
if observation is not None:
observation['conditioning_sha256'] = condition_hash
report['resource_prediction_error'] = prediction_errors(report['resource_prediction'], observation)
return observation
# A live policy may have replaced the initial profile after text
# encoding. Record and execute that exact allocator consistently.
allocator = profile.get('allocator_config', allocator)
profile['allocator_config'] = allocator
env.update(PYTORCH_ALLOC_CONF=allocator, PYTORCH_CUDA_ALLOC_CONF=allocator)
save(destination.with_suffix('.request.json'), report)
request = {'conditioning': str(condition), 'seed': args.seed, 'cache': str(args.cache.resolve()),
'input_cache_dir': str(input_cache.root.parent.parent) if input_cache else None,
'gpu_budget_bytes': round(profile['gpu_budget_gb'] * 1e9), 'engine_options': profile['engine'],
'decoder_options': profile['decoder'], 'output': str(destination),
'geometry': canvas, 'artifacts': str(artifacts),
**({'output_size': output_size} if output_size else {}),
'sampling_plan': sampling_plan, 'upscaler_checkpoint': upscaler_checkpoint,
'automatic_pass_cache': not bool(args.profile),
'metrics': str(destination.with_suffix('.engine.json'))}
if continuation is not None:
request['continuation'] = continuation
if hide_tail_frames:
request['hide_tail_frames'] = hide_tail_frames
if original_audio is not None:
request['original_audio'] = original_audio
report['original_audio'] = original_audio
if preview:
request['preview'] = True
if allocator_limit_bytes is not None:
request['allocator_limit_bytes'] = allocator_limit_bytes
report['benchmark_limit'] = {'pytorch_allocator_bytes': request['allocator_limit_bytes'],
'scope': 'PyTorch CUDA allocator only; other CUDA allocations and whole-device usage are measured separately.'}
request_path = temporary / 'video.json'
resume_decode = resume_refine = None
# An upscale reuses its preview's first pass unless a later attempt
# retains a newer checkpoint, or the current inputs no longer match.
preview_pass = ({key: refine_source[key] for key in ('input', 'metrics', 'request')}
if refine_source else None)
# Keep explicit dependency overlays while keeping the snapshotted engine first.
engine_env = dict(env, PYTHONPATH=os.pathsep.join((str(repo), str(vdn_root()),
env.get('PYTHONPATH', ''))))
def persist():
save(destination.with_suffix('.request.json'), report)
def launch(selected, attempt):
nonlocal preview_pass
selected_env = inference_environment(engine_env, selected['inference_ram_budget_gb'] * 1e9)
if continuation is not None:
from .continuation import ADALN_TASK, ANCHOR_ADALN_TASK
selected['engine'] = dict(selected['engine'],
adaln_task=(selected['engine']['task'] if original_audio is not None
else ANCHOR_ADALN_TASK if anchored else ADALN_TASK))
request.update(engine_options=selected['engine'], decoder_options=selected['decoder'],
ram_budget_bytes=round(selected['inference_ram_budget_gb'] * 1e9),
ram_budget_is_estimate=ram_budget_is_estimate(args),
gpu_budget_bytes=round(selected['gpu_budget_gb'] * 1e9),
gpu_reserve_bytes=selected.get('policy', {}).get('gpu_system_reserve_bytes', 0),
capacity_trial=bool(selected.get('policy', {}).get('capacity_trial')),
resource_attempt=attempt)
request.pop('first_pass_policy', None)
request['automatic_pass_cache'] = not bool(args.profile) and len(report.get('resource_attempts', [])) <= 1
# Explicit profiles and recovery placements retain their cap.
# Automatic Windows requests can use a later driver-budget rise
# without exceeding a user/benchmark capacity constraint.
request['dynamic_gpu_budget'] = (hardware.system == 'Windows' and
request['automatic_pass_cache'] and getattr(args, 'gpu_reserve_gib', None) is None)
request['gpu_capacity_bytes'] = min(hardware.vram_total,
int(args.vram_gib * 2**30) if args.vram_gib else hardware.vram_total)
from .two_pass import clamp_first_pass_for_retry, first_pass_policy, keeps_first_pass_on_retry
retry_keeps = (not args.profile and not request['automatic_pass_cache'] and keeps_first_pass_on_retry(
report.get('resource_attempts'), getattr(args, 'resource_retries', 2)))
if request['automatic_pass_cache'] or retry_keeps:
first_policy = first_pass_policy(selected, canvas, sampling_plan)
if first_policy is not None:
first_policy['profile'], _ = apply_compatibility(first_policy['profile'], compatibility_state)
if retry_keeps:
# A recovery attempt narrows placement, not the first pass's arithmetic
# partitions: keep those and never exceed what the retry frees.
# With the pass cache off only the compute options (chunks, residual
# offload, prefetch, recompute) take effect; the rest is diagnostic.
first_policy, clamped = clamp_first_pass_for_retry(first_policy, selected)
first_policy['retry_clamped'] = clamped
request['first_pass_policy'] = first_policy
report['first_pass_policy'] = first_policy
if resume_decode is not None:
request['resume_decode'] = dict(resume_decode)
else:
request.pop('resume_decode', None)
if resume_decode is None and resume_refine is not None:
request['resume_refine'] = dict(resume_refine)
else:
request.pop('resume_refine', None)
request.pop('resume_first_pass', None)
if resume_decode is None and resume_refine is None and preview_pass is not None:
from .decode_resume import refine_provenance, same_identity
receipt = json.loads(Path(preview_pass['metrics']).read_text(encoding='utf-8'))
if same_identity(refine_provenance(request), receipt.get('refine_provenance')):
request['resume_first_pass'] = dict(preview_pass)
report['upscaled_preview']['first_pass_reused'] = True
else:
# Other models, settings or math: the preview's first pass
# is not this request's. Sample it again instead.
preview_pass = None
report['upscaled_preview'].update(first_pass_reused=False,
reason='The preview no longer matches the current models or settings; '
'its first pass was sampled again.')
print(json.dumps(dict(event='preview_mismatch')), flush=True)
save(request_path, request)
# The epoch pairs with the worker's own events to time its start.
print(json.dumps({'event': 'decode_resume' if resume_decode else 'video_start', 'resource_attempt': attempt,
'engine': selected['engine'], 'decoder': selected['decoder'],
'epoch': time.time()}), flush=True)
try:
telemetry = child([sys.executable, '-m', 'freevideo_engine.worker', '--request', str(request_path)],
selected_env, descriptor, destination.with_suffix('.engine.log'),
ram_budget_bytes=selected['inference_ram_budget_gb'] * 1e9,
ram_budget_is_estimate=ram_budget_is_estimate(args),
minimum_available_bytes=inference_emergency_floor(selected['inference_ram_budget_gb'] * 1e9,
getattr(args, 'ram_reserve_gib', None)),
gpu=resource_identity['gpu']['uuid'],
on_start=lambda pid: history.attach_worker(attempt, pid, phase='video'))
except BaseException as error:
try:
error.metrics = json.loads(destination.with_suffix('.engine.json').read_text(encoding='utf-8'))
except (OSError, ValueError):
pass
if isinstance(getattr(error, 'metrics', None), dict) and not error.metrics.get('sampling_memory'):
try:
from .diagnostics import read_bounded
raw, truncated = read_bounded(destination.with_suffix('.sampling-memory.json'), 2 * 2**20)
observed = json.loads(raw) if not truncated else None
if isinstance(observed, dict):
error.metrics['sampling_memory'] = observed
except (OSError, ValueError):
pass
raise
return json.loads(destination.with_suffix('.engine.json').read_text(encoding='utf-8')), telemetry
def archive(index, row):
nonlocal resume_decode, resume_refine
retained = artifacts / 'attempts' / ('%02d-%s' % (index + 1, row['id']))
retained.mkdir(parents=True, exist_ok=False)
paths = [destination] + [destination.with_suffix('.engine.' + ext)
for ext in ('json','log','memory.json','gpu.json','gpu.csv')]
paths.append(destination.with_suffix('.sampling-memory.json'))
paths += [artifacts/name for name in ('latents.pt','refine-input.pt','rgb.npy','audio.npy','audio.wav','video.json')]
for path in paths:
if path.exists():
path.rename(retained / path.name)
save(retained / 'attempt.json', row)
# Reuse only completed sampling from this request, never a
# partial sample. The worker validates provenance and tensor
# metadata again before loading the saved video/audio latents.
# The controller's durable row can still say ``sample`` when
# the worker has already written a complete sampling receipt
# and is failing while releasing streamed weights. The
# worker receipt is authoritative: inspect it regardless of
# the parent monitor phase, then require completed_sampling()
# to validate all planned finite steps, provenance, and the
# retained latent checkpoint before switching to decode-only.
if resume_decode is None:
try:
sample_metrics = retained / destination.with_suffix('.engine.json').name
sampled = json.loads(sample_metrics.read_text(encoding='utf-8'))
from .decode_resume import completed_sampling
if (completed_sampling(sampled)
and (retained / 'latents.pt').is_file() and (retained / 'latents.pt').stat().st_size > 0):
resume_decode = dict(latents=str(retained / 'latents.pt'),
metrics=str(sample_metrics), request=str(retained / 'video.json'))
except (OSError, ValueError, TypeError):
pass # Older/incomplete artifacts retain full-request recovery.
# A second-pass failure keeps its completed first pass. Later
# retries reuse the first retained one; the worker validates
# its provenance and tensors again before loading it.
if resume_decode is None and resume_refine is None:
try:
sample_metrics = retained / destination.with_suffix('.engine.json').name
sampled = json.loads(sample_metrics.read_text(encoding='utf-8'))
from .decode_resume import refine_checkpoint_complete
source = retained / 'refine-input.pt'
if (refine_checkpoint_complete(sampled) and source.is_file() and source.stat().st_size > 0
and (retained / 'video.json').is_file()):
resume_refine = dict(input=str(source), metrics=str(sample_metrics),
request=str(retained / 'video.json'))
except (OSError, ValueError, TypeError):
pass
return str(retained)
def retry(index, row, selected, decision):
retry_state = dict(attempt=index + 2, max_attempts=getattr(args, 'resource_retries', 2) + 1,
failed_phase=row.get('phase'), kind=row['failure']['kind'],
reuse_sampling=resume_decode is not None,
reuse_first_pass=resume_decode is None and (resume_refine is not None
or preview_pass is not None))
row['recovery'] = dict(decision, next_profile=selected, **retry_state)
persist()
print(json.dumps(dict(event='resource_retry', retained=row['retained'], retry=retry_state)), flush=True)
from .support_report import write_retry
write_retry(destination, report, index=index + 1, retained=row['retained'],
next_profile=selected, decision=row['recovery'])
report['video'], report['resources'], profile = execute_attempts(
history, resource_identity, profile, canvas, launch,
validate=validate, prepare=forecast,
archive=archive, report=report, persist=persist, on_retry=retry,
automatic=not args.profile or getattr(args, 'recover_placement', False),
max_retries=getattr(args, 'resource_retries', 2))
report['gpu_card'] = {**report['gpu_card'], **(report['video'].get('gpu_card') or {})}
if continuation is not None:
report['continuation']['audio_lead_in_samples'] = report['video'].get('continuation', {}).get(
'audio_lead_in_samples', 0)
if preview:
# An upscale validates this receipt beside the retained first pass.
shutil.copyfile(destination.with_suffix('.engine.json'), artifacts / 'first-pass.engine.json')
from .preview import upscale_reads
report['preview']['upscale_reads'] = upscale_reads(request['cache'], report['video'], upscaler_checkpoint)
from .guide_audio import apply_to_report as keep_source_audio, requested as keeps_source_audio
if keeps_source_audio(media):
# A preview gets the guide clip's sound too; its upscale reads the retained first pass, not this MP4.
keep_source_audio(destination, media, report)
report['success'] = True
except BaseException as error:
from .diagnostic_resources import exception_details
report['exception'] = exception_details(error)
error.diagnostic_recorded = True
report['error'] = repr(error)
report['error_message'] = str(error)
report['error_type'] = type(error).__name__
if hasattr(error, 'details'):
report['resource_error'] = error.details
_runtime_libraries(error, report)
if applied:
report['tuning']['disabled_after_failure'] = tuning.disable_profile(applied, error)
raise
finally:
processes.restore_handlers(previous)
report['request_seconds'] = time.perf_counter() - started
diagnostic = write_debug(destination, report)
if diagnostic:
report['diagnostic_file'] = diagnostic.name
save(destination.with_suffix('.request.json'), report)
if __name__ == '__main__':
main()