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.

25.3 KB
Raw Blame
"""Bounded, text-free UI progress receipts. No ComfyUI, Torch or device imports.

The allowlists are deliberately checked in, rather than learned from messages.
Sources: engine phase/stage/timing_phase literals; comfy_bridge encoder/event
label tables and send_progress; comfy_nodes; sampling_progress; decode/media
phase labels; web/generation_progress.js encodingLabel/stageLabel translation
keys. Retry kinds originate in adaptive.py and warnings in engine event codes.
"""
from copy import deepcopy
import json
import math
import re
import time


PHASES = frozenset((
    'Decoding video tiles',
    'Encoding image/video references',
    'Encoding input media',
    'Encoding reference audio',
    'Load cached blocks and upload resident weights',
    'Loading and decoding audio',
    'Loading native MPS model',
    'Loading video VAE',
    'Preparing offloaded weight storage',
    'Saving MP4 and audio',
    'backend',
    'cancelled',
    'cancelling',
    'complete',
    'configuration',
    'connect',
    'decode',
    'dependencies',
    'download',
    'downloading',
    'encoder_import',
    'encoder_oom',
    'encoding',
    'engine',
    'failed',
    'finishing',
    'idle-encoder-load',
    'keyframe_vae',
    'load',
    'loading',
    'lora',
    'other',
    'paused',
    'plan',
    'preflight',
    'read_source_weights',
    'ready',
    'reconstruct',
    'recovery',
    'sample',
    'sample_finalize',
    'sampling',
    'starting',
    'switch',
    'transfer_complete',
    'unknown',
    'verify',
    'verify_cache',
    'verifying',
    'video',
    'waiting',
    'warmup',
))

STAGES = frozenset((
    'after-encoding',
    'before-encoding',
    'between_steps',
    'comfy',
    'complete',
    'encode',
    'encoder_compute',
    'encoder_load',
    'encoder_save',
    'encoder_tokenize',
    'encoding',
    'first_pass_reused',
    'gpu',
    'imports',
    'inputs',
    'kernel_prepare',
    'installation',
    'latent_save',
    'latent_upscale',
    'latent_validation',
    'layers',
    'media_vae',
    'offload_release',
    'other',
    'other_or_unmeasured',
    'preset_download',
    'preview_mismatch',
    'reference_download',
    'sources_download',
    'starting',
    'transformer_release',
    'verify',
    'video',
))

TIMING_PHASES = frozenset((
    'decode',
    'encoding',
    'load',
    'other',
    'sampling',
))

LABEL_KEYS = frozenset((
    '#',
    'Adjusting memory placement and retrying',
    'Check local models',
    'Checking completed sampling',
    'Checking saved video',
    'Checking text encoder cache',
    'ComfyUI',
    'Compatibility level # · smaller work groups',
    'Continuing from the preview',
    'Copy local model',
    'Decoding video and audio',
    'Decoding audio',
    'Decoding video tiles',
    'Downloading extra model weights (one-time download)',
    'Extracting depth from the reference video',
    'Encoding image/video references',
    'Encoding input media',
    'Encoding long references in smaller blocks',
    'Encoding prompt',
    'Encoding reference audio',
    'Encoding reference media',
    'Encoding text and images',
    'Existing models checked',
    'Find existing models',
    'First-pass preview · # × # · # steps',
    'GPU peak (GiB)',
    'Generating video',
    'Generation cancelled',
    'Generation stopped',
    'History forecast',
    'HF Mirror',
    'Hugging Face',
    'Importing offline packages',
    'Install FreeVideo workflow',
    'Connecting workflow nodes',
    'Installing sampling cache',
    'Leaving more GPU memory for text encoding',
    'Load cached blocks and upload resident weights',
    'Loading LoRAs',
    'Loading LoRAs · # / #',
    'Loading and decoding audio',
    'Loading cached video model',
    'Loading cached video model · # / # blocks',
    'Loading native MPS model',
    'Loading native MPS model · # / # blocks',
    'Loading text encoder',
    'Loading text encoder onto GPU',
    'Loading video VAE',
    'Loading video model',
    'Loading video model · # / # blocks',
    'Low-memory mode for this GPU',
    'ModelScope',
    'Open ComfyUI',
    'Paused; existing data kept',
    'Peak disk space',
    'Prepare ComfyUI',
    'Prepare ComfyUI environment',
    'Prepare FreeVideo',
    'Prepare download tools',
    'Preparing installation',
    'Preparing # s video + audio · # × #',
    'Preparing offloaded weight storage',
    'Preparing offloaded weight storage · # / # blocks',
    'Preparing prompt data',
    'Preparing reference media',
    'Preparing reference media resources',
    'Preparing sampling preset',
    'Preparing text and image tokens',
    'Preparing text encoder GPU',
    'Preparing text encoder model',
    'Preparing text encoding',
    'Preparing two-pass upscaler',
    'Preparing video',
    'Preparing video decoding',
    'Preparing GPU programs for the first step',
    'Processing video colors',
    'Preview saved',
    'Prompt ready',
    'RAM measurement',
    'RAM peak (GiB)',
    'Reading text encoder weights',
    'Ready',
    'Releasing encoder weights after insufficient GPU memory',
    'Releasing idle models and checking available memory again',
    'Releasing sampling buffers',
    'Restart ComfyUI',
    'Restart explicitly allowed',
    'Resource forecast ready',
    'Resume unavailable; checking another source',
    'Retaining and checking input media',
    'Retrying same source',
    'Retrying same source with configured proxy',
    'Retrying same source with direct connection',
    'Retrying text encoding with more GPU workspace',
    'Reused previous result',
    'Reuse local model',
    'Reusing completed sampling · retrying video and audio decoding',
    'Reusing prompt cache',
    'Reusing text encoder',
    'Reusing the completed first pass',
    'Sampling',
    'Sampling # / #',
    'Sampling # / # · #%',
    'Sampling # / # · ~#%',
    'Saving MP# and audio',
    'Saving completed sampling',
    'Saving prompt cache',
    'Saving decoded video',
    'Saving decoded audio',
    'Single-pass · # steps',
    'Start ComfyUI',
    'Starting ComfyUI',
    'Starting text encoder',
    'System available minimum (GiB)',
    'Test GPU acceleration',
    'The preview no longer matches; sampling its first pass again',
    'Two-pass · # × # → # × # · # + # steps',
    'Update ComfyUI packages',
    'Upscaling before the second pass',
    'Using text encoder already on GPU',
    'Verify / reuse local models',
    'Verify bundled files',
    'Verify local model',
    'Video + audio saved',
    'Video model ready',
    'Video saved',
    'compute_device',
    'other',
    'root',
    'your Hub endpoint',
    'Checking configuration',
    'Checking packages',
    'Downloading models',
    '下载模型',
    '导入离线包',
    '检查配套包',
    '正在检查配置',
    'Decoding the video',
    'Encoding long references',
    'Loading the video model',
    'Preparing the prompt and images',
    'Starting generation process',
))

UNITS = frozenset((
    'bytes',
    'frames',
    'items',
    'other',
    'seconds',
    'steps',
))

RETRY_KINDS = frozenset((
    'cancelled',
    'code_error',
    'cuda_error',
    'gpu_oom',
    'memory_monitor_unavailable',
    'memory_pressure',
    'other',
    'ram_pressure',
    'shared_memory_spill',
    'timeout',
    'unknown_worker_exit',
    'worker_stop_unconfirmed',
))

STATUSES = frozenset((
    'cancelled',
    'complete',
    'failed',
    'other',
    'running',
))

WARNINGS = frozenset((
    'other',
    'ram_budget_warning',
    'unified_memory_tight',
))

SEGMENT_KEYS = ('phase', 'stage', 'timing_phase', 'label_key')
ENUMS = dict(phase=PHASES, stage=STAGES, timing_phase=TIMING_PHASES,
             label_key=LABEL_KEYS, unit=UNITS, warning=WARNINGS)
OVERALL_ENUMS = dict(status=STATUSES, remaining_source=frozenset(('local', 'similar', 'measured', 'other')))
RETRY_ENUMS = dict(kind=RETRY_KINDS, failed_phase=PHASES)
COUNTERS = frozenset(('done', 'total', 'block', 'blocks', 'reference_trimmed'))
FLAGS = frozenset(('low_memory', 'kernel_cache_note', 'estimated', 'new_request', 'reset', 'result'))
ONE_SHOT = frozenset(('new_request', 'reset', 'result', 'warning'))
SECONDS = frozenset(('step_elapsed_seconds', 'estimated_step_seconds', 'measured_age_seconds'))
FRACTIONS = frozenset(('display_fraction',))
OVERALL_SECONDS = frozenset(('remaining_seconds', 'phase_seconds', 'remaining_floor_seconds',
                             'elapsed_seconds', 'phase_elapsed_seconds'))
OVERALL_FRACTIONS = frozenset(('fraction', 'phase_start_fraction', 'phase_weight'))
SCOPE = ('Events are sanitized actual UI rows after publish applies retry carry-over and warning overlays; '
         'low_memory and reference_trimmed use the UI row when present, otherwise the current input; '
         'delta fields and overall subkeys inherit, null clears a field, retry is replaced as a whole, '
         'and new_request/reset/result/warning belong only to their event; '
         'the first event and every segment start contain full states; '
         't is seconds since the first recorded event, and measured_age_seconds is how old a warning overlay\'s inherited row was; heartbeats are counted but omitted without changing sampling; '
         'truncated means mandatory events exhausted the capacity, later events were dropped except terminal events, which may replace retained events; '
         'the report is written before the node final event, '
         'so use bridge.bridge_seconds for the end time.')
MAX_EVENTS = 5000
MAX_BYTES = 160_000
# Everything but the events, as monitoring.save writes it (indent=2, nested in
# the report), with the widest counters, plus the summary and analysis counts.
METADATA_BYTES = len(json.dumps(dict(progress_timeline=dict(
    version=1, encoding='delta', events=[], dropped=10**12, heartbeats=10**12, errors=10**12,
    truncated=False, scope=SCOPE)), indent=2)) + 512
_NUMBERS = re.compile(r'\d{1,3}(?:,\d{3})+(?:\.\d+)?|\d+(?:\.\d+)?')


def label_key(value):
    """Never retain unmatched text, including device names in known prefixes."""
    if not isinstance(value, str):
        return 'other'
    if value.startswith('Compute device ·') or value == 'Compute device':
        return 'compute_device'
    key = _NUMBERS.sub('#', value)
    return key if key in LABEL_KEYS else 'other'


def _number(value, digits=1, significant=False):
    if type(value) not in (int, float) or not math.isfinite(value) or value < 0:
        raise ValueError('Invalid progress number')
    result = float(format(value, '.3g')) if significant else round(value, digits)
    if not math.isfinite(result):
        raise ValueError('Invalid rounded progress number')
    return result


def _fields(value, *, strict=False, nested=None):
    """One schema for ingestion and the final report boundary; no arbitrary keys."""
    if not isinstance(value, dict):
        return {}, 1
    result, errors = {}, 0
    enums = ENUMS if nested is None else OVERALL_ENUMS if nested == 'overall' else RETRY_ENUMS
    for key, raw in value.items():
        known = (key in enums or
                 (nested is None and (key in COUNTERS or key in FLAGS or key in SECONDS or key in FRACTIONS
                                      or key in ('t', 'bytes_per_second', 'overall', 'retry'))) or
                 (nested == 'overall' and (key in OVERALL_SECONDS or key in OVERALL_FRACTIONS
                                          or key in ('estimated', 'sampling_time_weighted', 'at_ceiling'))) or
                 (nested == 'retry' and key in ('attempt', 'max_attempts', 'reuse_sampling')))
        if not known:
            # Heartbeat and the bridge's extra overall fields are intentionally omitted.
            if strict:
                errors += 1
            continue
        try:
            if raw is None:
                result[key] = None
            elif key in enums:
                if not isinstance(raw, str):
                    raise ValueError('Invalid progress code')
                if strict and raw not in enums[key]:
                    raise ValueError('Unknown progress code')
                result[key] = raw if raw in enums[key] else 'other'
            elif key in ('overall', 'retry') and nested is None:
                if not isinstance(raw, dict):
                    raise ValueError('Invalid progress mapping')
                result[key], count = _fields(raw, strict=strict, nested=key)
                errors += count
            elif (nested is None and key in FLAGS) or key in ('estimated', 'reuse_sampling', 'sampling_time_weighted',
                                                              'at_ceiling'):
                if (strict or key in ('sampling_time_weighted', 'at_ceiling')) and type(raw) is not bool:
                    raise ValueError('Invalid progress flag')
                result[key] = bool(raw)
            elif (nested is None and key in COUNTERS) or key in ('attempt', 'max_attempts'):
                if type(raw) is not int or raw < 0:
                    raise ValueError('Invalid progress counter')
                result[key] = raw
            else:
                result[key] = _number(raw, 4 if key in OVERALL_FRACTIONS or key in FRACTIONS else 1,
                                      significant=key == 'bytes_per_second')
        except (ValueError, TypeError, OverflowError):
            errors += 1
    return result, errors


def sanitize(message):
    """Clean supplied presentation fields without inheriting any prior state."""
    supplied = {key: message[key] for key in (*ENUMS, *COUNTERS, *FLAGS, *SECONDS, *FRACTIONS,
                                             'overall', 'retry', 'bytes_per_second')
                if key in message}
    if 'label' in message:
        supplied['label_key'] = label_key(message['label'])
    for key in FLAGS & supplied.keys():
        if supplied[key] is not None:
            supplied[key] = bool(supplied[key])
    # A single bridge reference_trimmed mapping describes one reference, not four fields.
    if 'reference_trimmed' in supplied:
        raw = supplied['reference_trimmed']
        supplied['reference_trimmed'] = (raw if type(raw) is int and raw >= 0 else
                                        len(raw) if isinstance(raw, (list, tuple)) else
                                        1 if raw is not None else 0)
    clean, errors = _fields(supplied)
    # Null is the wire's removal operation, not a retained state value.
    clean = {key: ({subkey: item for subkey, item in value.items() if item is not None}
                   if isinstance(value, dict) else value)
             for key, value in clean.items() if value is not None}
    return clean, errors


def _segment(event):
    return tuple(event.get(key) for key in SEGMENT_KEYS)


def _delta(event, previous):
    if previous is None:
        return dict(event)
    full = _segment(event) != _segment(previous)
    delta = {key: None for key in previous if key not in event and key not in ONE_SHOT}
    for key, value in event.items():
        if full or key == 't' or key in ONE_SHOT or key not in previous:
            delta[key] = value
        elif key == 'overall' and isinstance(previous[key], dict):
            changed = {subkey: None for subkey in previous[key] if subkey not in value}
            changed.update((subkey, item) for subkey, item in value.items()
                           if subkey not in previous[key] or item != previous[key][subkey])
            if changed:
                delta[key] = changed
        elif value != previous[key]:
            delta[key] = value
    return delta


def decode(events):
    """Restore complete states; a segment's first event can be read independently."""
    result, state = [], {}
    for event in events:
        # Segment keys are omitted within a segment. A changed (including
        # cleared) key identifies a full row, whose overall is also complete.
        if any(key in event and event[key] != state.get(key) for key in SEGMENT_KEYS):
            state = {}
        for key in ONE_SHOT:
            state.pop(key, None)
        for key, value in event.items():
            if value is None:
                state.pop(key, None)
            elif key == 'overall':
                overall = state.setdefault(key, {})
                for subkey, item in value.items():
                    if item is None:
                        overall.pop(subkey, None)
                    else:
                        overall[subkey] = deepcopy(item)
            else:
                state[key] = deepcopy(value)
        result.append(deepcopy(state))
    return result


def _event_bytes(event, previous):
    # monitoring.save uses indent=2; payload.progress_timeline.events adds six
    # spaces to every event line. Default ASCII escaping is conservative for
    # the fixed Unicode labels saved as UTF-8. Include a comma and newline.
    encoded = json.dumps(_delta(event, previous), indent=2)
    return len(encoded) + 6 * (encoded.count('\n') + 1) + 2


def validate(payload):
    """Revalidate the receipt before report redaction, discarding invalid values."""
    if not isinstance(payload, dict):
        return None
    errors = 0
    counters = {}
    for key in ('dropped', 'heartbeats', 'errors'):
        value = payload.get(key, 0)
        if type(value) is int and value >= 0:
            counters[key] = value
        else:
            counters[key] = 0
            errors += 1
    events = []
    raw = payload.get('events', [])
    if not isinstance(raw, list):
        raw = []
        errors += 1
    for event in raw:
        clean, count = _fields(event, strict=True)
        errors += count
        if type(clean.get('t')) not in (int, float):
            counters['dropped'] += 1
            errors += 1
            continue
        events.append(clean)
    truncated = payload.get('truncated', False)
    if type(truncated) is not bool:
        truncated = False
        errors += 1
    counters['errors'] += errors
    return dict(version=1, encoding='delta', events=events, **counters, truncated=truncated, scope=SCOPE)


def _terminal(event):
    overall = event.get('overall')
    return 'result' in event or (isinstance(overall, dict)
        and overall.get('status') in ('failed', 'cancelled', 'complete'))


class Timeline:
    """Full states internally, online sampling, delta only at the output boundary.

    Rows carry a preservation flag and the unrounded sampling clock. Compaction
    costs O(retained rows), paid for by the rows it discards; normal records touch
    a bounded schema and the last row only. The caller supplies synchronization.
    """
    def __init__(self, clock=time.monotonic):
        self.clock = clock
        self.started = None
        self.state = {}
        self.rows = []
        self.pending = None
        self.interval = .5
        self.dropped = self.heartbeats = self.errors = 0
        self.report_id = None
        self._bytes = 0
        self._counted = False
        self._last_count = None
        self.truncated = False
        self._saturated = False

    def record(self, value, now=None, *, message=None, measured=None):
        """Record the actual publish row, falling back to input-only metadata.

        Direct callers supply an already resolved UI row as value. The original
        message controls heartbeat detection and one-shot marker presence: a
        warning can inherit a heartbeat's UI row without itself being one.
        measured is when the row's values were measured: a warning overlay keeps
        the earlier row's time, and the page ages its remaining time from it.
        """
        message = value if message is None else message
        overall = message.get('overall')
        if message.get('heartbeat') is True or isinstance(overall, dict) and overall.get('heartbeat') is True:
            self.heartbeats += 1
            return
        if self._saturated and not _terminal(value):
            self.dropped += 1
            return
        now = self.clock() if now is None else now
        if self.started is None:
            self.started = now
        supplied = dict(value)
        for key in ONE_SHOT:
            if key not in message:
                supplied.pop(key, None)
        for key in ('low_memory', 'reference_trimmed'):
            if key not in supplied and key in message:
                supplied[key] = message[key]
        clean, errors = sanitize(supplied)
        self.errors += errors
        event = dict(clean, t=_number(max(0., now - self.started)))
        age = round(now - measured, 1) if type(measured) in (int, float) and math.isfinite(measured) else 0.
        if age > 0:
            event['measured_age_seconds'] = _number(age)
        changed = not self.rows or _segment(event) != _segment(self.state)
        if changed:
            if self._last_count is not None:
                self._last_count[1] = True
            self._last_count = None
            self._counted = False
        counted = any(type(event.get(key)) is int for key in ('done', 'total', 'block', 'blocks'))
        first_count = counted and not self._counted
        self._counted |= counted
        mandatory = changed or first_count or any(key in message for key in ('retry', 'new_request', 'reset', 'result', 'warning'))
        mandatory |= event.get('phase') in ('failed', 'cancelled', 'complete') or (isinstance(event.get('overall'), dict)
                        and event['overall'].get('status') in ('failed', 'cancelled', 'complete'))
        self.state = event
        row = [event, mandatory, now]
        if counted:
            self._last_count = row
        elif self.pending is not None and self.pending is self._last_count:
            # An uncounted update must not supersede the segment's last count.
            self._flush()
        if mandatory:
            self._flush(last=changed)
            if changed and self.rows:
                self.rows[-1][1] = True
            self._append(row)
        elif now - self.rows[-1][2] >= self.interval:
            # The pending update is superseded by this sample at the interval boundary.
            if self.pending is not None:
                self.dropped += 1
                self.pending = None
            self._append(row)
        else:
            if self.pending is not None:
                self.dropped += 1
            self.pending = row

    def _flush(self, last=False):
        if self.pending is not None:
            row = self.pending
            self.pending = None
            if last:
                promoted = [row[0], True, row[2]]
                if self._last_count is row:
                    self._last_count = promoted
                row = promoted
            self._append(row)

    def _append(self, row):
        if self._saturated and not _terminal(row[0]):
            self.dropped += 1
            return
        previous = self.rows[-1][0] if self.rows else None
        self._bytes += _event_bytes(row[0], previous)
        self.rows.append(row)
        if self._over_capacity():
            self._compact()
            # Mandatory-only receipts cannot be thinned. Stop accepting ordinary
            # events, but always make room for the newest terminal event.
            terminal = _terminal(row[0])
            while self._over_capacity():
                index = len(self.rows) - 1
                if terminal:
                    index = next((i for i in range(len(self.rows) - 2, -1, -1)
                                  if not _terminal(self.rows[i][0])), len(self.rows) - 2)
                self._remove(index)

    def _over_capacity(self):
        return len(self.rows) > MAX_EVENTS or self._bytes > MAX_BYTES - METADATA_BYTES

    def _remove(self, index):
        previous = self.rows[index - 1][0] if index else None
        event = self.rows[index][0]
        self._bytes -= _event_bytes(event, previous)
        if index + 1 < len(self.rows):
            following = self.rows[index + 1][0]
            self._bytes += _event_bytes(following, previous) - _event_bytes(following, event)
        self.rows.pop(index)
        self.dropped += 1

    def _compact(self):
        if self._saturated:
            return
        while self._over_capacity():
            optional = [index for index, row in enumerate(self.rows[:-1])
                        if not row[1] and row is not self._last_count]
            if not optional:
                self.truncated = self._saturated = True
                break
            remove = set(optional[::2])
            self.rows = [row for index, row in enumerate(self.rows) if index not in remove]
            self.dropped += len(remove)
            self.interval *= 2
            self._bytes = 0
            previous = None
            for event, _, _ in self.rows:
                self._bytes += _event_bytes(event, previous)
                previous = event

    def snapshot(self):
        # Flush on a copy: a live download must not influence future sampling.
        view = Timeline(self.clock)
        view.rows = list(self.rows)
        view.pending = self.pending
        view.interval = self.interval
        view.dropped, view.heartbeats, view.errors = self.dropped, self.heartbeats, self.errors
        view._bytes = self._bytes
        view._last_count = self._last_count
        view.truncated, view._saturated = self.truncated, self._saturated
        view._flush(last=True)
        view._compact()
        events, previous = [], None
        for event, _, _ in view.rows:
            events.append(deepcopy(_delta(event, previous)))
            previous = event
        return dict(version=1, encoding='delta', events=events, dropped=view.dropped,
                    heartbeats=view.heartbeats, errors=view.errors, truncated=view.truncated, scope=SCOPE)