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.8 KB
Raw Blame
"""Reuse Comfy's registered libraries and provision a separate engine environment.

Import/GET discovery is read-only. Only explicit inspect/install actions start
children. The existing installer owns content checks, consent, download recovery,
resource locks and readiness; this module does not run pip in ComfyUI.
"""
from collections import deque
import json
import os
from pathlib import Path
import secrets
import sys
import threading
import uuid

from .long_paths import io_path, resolved, plain, plain_text, plain_errors
from .comfy_bridge import installation, installation_root, source_root
from .environments import ENVIRONMENTS
from .desktop_runtime import Runner, preflight_json
from .comfy_environment import isolated_environment
from .local_models import library_roots
from .monitoring import save
from .setup_progress import ProgressState


def discover_libraries(folder_paths, environ=None):
    env = os.environ if environ is None else environ
    from .launcher_settings import saved_model_libraries
    candidates = saved_model_libraries() + [str(folder_paths.models_dir)]
    # folder_paths already incorporates extra_model_paths.yaml, including paths
    # registered by other nodes. No second, subtly different YAML parser.
    for name in ('diffusion_models', 'unet', 'checkpoints', 'text_encoders', 'clip', 'vae'):
        try:
            candidates.extend(folder_paths.get_folder_paths(name))
        except KeyError:
            pass
    cache = env.get('HF_HUB_CACHE') or env.get('HUGGINGFACE_HUB_CACHE')
    if not cache and env.get('HF_HOME'):
        cache = str(Path(env['HF_HOME']) / 'hub')
    modelscope = env.get('MODELSCOPE_CACHE')
    if not cache or not modelscope:
        # Optional cache discovery must also work in portable/service Windows
        # environments without USERPROFILE. Evaluate defaults only if needed.
        try:
            home_cache = Path.home() / '.cache'
        except (OSError, RuntimeError):
            pass
        else:
            cache = cache or str(home_cache / 'huggingface/hub')
            modelscope = modelscope or str(home_cache / 'modelscope/hub')
    candidates.extend(value for value in (cache, modelscope) if value)
    existing = []
    for value in candidates:
        try:
            path = io_path(Path(value).expanduser())
            if path.is_dir():
                existing.append(plain(path))
        except (OSError, RuntimeError):
            pass
    # A folder registered under several model types is listed once; finding
    # more than 64 folders keeps the first 64 rather than failing setup.
    return library_roots(list(dict.fromkeys(existing)), keep_first=True)


# The calibration encodes this once and every variant reads it, so the
# comparison excludes text encoding and both halves see one input.
CALIBRATION_PROMPT = ('A neon-lit alley after heavy rain. The camera drifts forward past '
                      'reflected signage while distant thunder rolls and footsteps echo '
                      'on wet stone.')


def inspection_failed(value):
    """The first line of a failed inspection: what ran, how it ended and how much the child printed.

    Only integers, fixed words and an exception class name, so a report keeps it whole however the rest is cut."""
    code, failed = value.get('returncode'), value.get('failed_with')
    parts = [value.get('action') if value.get('action') in ('plan', 'setup') else 'other']
    if isinstance(code, int):
        # Windows reports a crash as a large unsigned code; its hex form is the one people search for
        parts.append('exit %d' % code + (' (0x%08X)' % code if 0xFFFF < code <= 0xFFFFFFFF else ''))
    else:
        parts.append('no exit code')
    parts.append('%d output lines' % int(value.get('lines') or 0))
    # A cancelled run never gets here: only a complete or failed plan is read, so cancelling is not a failure to report.
    if failed in ('TimeoutExpired', 'TimeoutError'):
        parts.append('timed out')
    if isinstance(failed, str) and failed.isidentifier() and len(failed) <= 60:
        parts.append(failed)
    return 'Setup inspection failed (%s)' % ', '.join(parts)


class SetupRunner(Runner):
    token = ''

    def prepare(self, action, root, env, progress):
        if os.name == 'nt' and action in ('plan', 'setup'):
            from .curl_windows import ensure
            executable = ensure(root, env, progress=progress, cancelled=self.cancelled.is_set)
            env = dict(env, FREEVIDEO_CURL=executable)
            # The PowerShell bootstrap also needs curl before Python exists.
            env['PATH'] = str(Path(executable).parent) + os.pathsep + env.get('PATH', os.defpath)
        return env

    def command(self, root, arguments):
        if os.name == 'nt':
            return super().command(root, arguments)
        if sys.platform == 'darwin':
            if getattr(sys, 'frozen', False):
                return [sys.executable, '--managed', str(self.source), '--root', str(root), *arguments]
            return [sys.executable, '-B', '-X', 'utf8', '-m', 'freevideo_engine.managed',
                    '--root', str(root), *arguments]
        return ['/bin/bash', str(self.source / 'freevideo'), '--root', str(root), *arguments]

    def environment(self, root):
        from .hf_auth import environment
        return environment(self.token, isolated_environment(root, self.source))


class Events:
    """A closed browser must not block a worker or grow a queue indefinitely."""
    def __init__(self):
        self.lock = threading.Lock()
        self.rows = deque(maxlen=128)
        self.progress = ProgressState()

    def put(self, row):
        with self.lock:
            if row[0] == 'progress':
                self.progress.update(row[1])
            self.rows.append(row)

    def reset(self):
        with self.lock:
            self.rows.clear()
            self.progress = ProgressState()

    def snapshot(self):
        with self.lock:
            return self.progress.snapshot()

    def drain(self):
        with self.lock:
            rows = list(self.rows)
            self.rows.clear()
        return rows


def owned_comfy(root, host):
    """./setup.sh puts the ComfyUI it installs in <engine>/ComfyUI; that one is the engine's own."""
    from .comfy_source import RECEIPT, specification
    root, host = io_path(root), io_path(host)
    try:
        return host == root / 'ComfyUI' and json.loads((host / RECEIPT).read_text(encoding='utf-8')) == specification()
    except (OSError, ValueError):
        return False


class Setup:
    @plain_errors
    def __init__(self, source, folder_paths, runner_factory=SetupRunner):
        self.source = Path(plain(resolved(source)))
        self.folder_paths = folder_paths
        self.events = Events()
        self.logs = self.source / '.freevideo' / 'comfy-setup'
        self.runner = runner_factory(self.source, self.events, self.logs)
        self.state = {'status': 'idle'}
        self.plan = self.selection = None
        self.token = secrets.token_urlsafe(32)
        from .download_settings import Probe
        self.download_probe = Probe()

    def discovery(self, download_root=None):
        root = Path(self.selection['root']) if self.runner.busy and self.selection else installation_root(self.source)
        ready, detail = False, ''
        try:
            installation(self.source)
            ready = True
        except (OSError, ValueError) as error:
            detail = str(error)
        from .sampling_assets import total_bytes
        from .launcher_settings import extra_model_directories
        return dict(root=str(root), ready=ready, detail=detail,
                    libraries=discover_libraries(self.folder_paths), extra_libraries=extra_model_directories(), token=self.token,
                    environment='Managed FreeVideo environment; ComfyUI packages are kept',
                    restart_required=False, downloads=self.downloads(download_root or root),
                    resources=self.resource_settings(),
                    sampling_cache_bytes=total_bytes())


    @plain_errors
    def model_directories(self, value):
        if self.runner.busy:
            raise ValueError('Wait for setup to finish before saving model folders')
        from .launcher_settings import model_directory_store
        choices = model_directory_store().save_model_directories(value.get('extra_libraries'))
        missing = []
        for path in choices:
            try:
                exists = io_path(Path(path).expanduser()).is_dir()
            except (OSError, RuntimeError):
                exists = False
            if not exists:
                missing.append(path)
        self.plan = None
        self.state.pop('plan_id', None)
        self.state.pop('plan', None)
        return dict(saved=True, extra_libraries=choices, missing_libraries=missing)

    def resource_settings(self, value=None):
        from .resource_settings import read, write, setting
        root = installation_root(self.source)
        backend = 'mps' if sys.platform == 'darwin' else 'cuda'
        field, _, label = setting(backend)
        if value is None:
            return read(root, backend=backend)
        if field not in value:
            raise ValueError('Specify automatic (null) or ' + label + ' in GiB')
        return write(root, value[field], backend=backend)

    def downloads(self, root=None):
        from .download_settings import read
        return dict(preferences=read(Path(root or installation_root(self.source))/'download-settings.json'),
                    probe=self.download_probe.snapshot(), hf_token_set=bool(getattr(self.runner, 'token', '')))

    def download_token(self, value):
        from .hf_auth import validate
        if self.runner.busy:
            raise ValueError('Stop setup before changing the token, then resume with retained downloads.')
        self.runner.token = validate(value.get('hf_token', ''))
        self.plan = None
        self.state.pop('plan_id', None)
        self.state.pop('plan', None)
        return dict(hf_token_set=bool(self.runner.token))

    def network_settings(self, value, *, probe=False):
        root=self.validate_root(value.get('root'))
        if self.runner.busy and self.selection and root!=Path(self.selection['root']):
            raise ValueError('Choose the active installation folder to switch its download')
        if probe:
            self.download_probe.start(root, getattr(self.runner, 'token', ''))
        else:
            self.download_probe.select(root,value.get('source'),proxy_mode=value.get('proxy_mode'))
        return self.downloads(root)

    def compatibility_settings(self, value, action):
        from .compatibility import Store, installed_identity, check_installation
        root = self.validate_root(value.get('root') or str(installation_root(self.source)))
        identity = installed_identity(root)
        store = Store(root)
        if action == 'compatibility-check':
            result = check_installation(root)
        elif action == 'compatibility-save':
            result = store.set(identity, value.get('level'), value.get('automatic'))
        elif action == 'compatibility-ack':
            result = store.acknowledge(identity, value.get('notice_id'))
        else:
            raise ValueError('Unknown compatibility action')
        return result

    @plain_errors
    def validate_root(self, value):
        if not isinstance(value, str) or not value.strip() or len(value) > 4096:
            raise ValueError('Choose an engine installation folder')
        root = resolved(Path(value).expanduser())
        host = resolved(self.folder_paths.base_path)
        if root == Path(root.anchor) or root == host or (root in host.parents and not owned_comfy(root, host)):
            raise ValueError('Use a dedicated FreeVideo folder, not the ComfyUI root or its parent')
        prefix = resolved(sys.prefix)
        # Refuse to pip into the interpreter that is running, and nothing more.
        # The earlier test asked whether the live interpreter lived anywhere
        # under `root/envs`, which is true of every working installation the
        # product builds: comfy_host puts ComfyUI in `root/envs/comfyui-<key>`
        # beside the engine's own env. So updating an installed FreeVideo from
        # inside its own ComfyUI was refused as "the active environment", with
        # nothing wrong and nothing to change. Only the engine's own
        # environment names are its install target; a ComfyUI sibling is not.
        engine_envs = {(root / 'envs' / name).resolve() for name in ENVIRONMENTS}
        if root == prefix or prefix in root.parents or prefix in engine_envs:
            raise ValueError('FreeVideo cannot install packages into the environment it is '
                             'running in. Launch ComfyUI from its own environment, or run '
                             'setup from the FreeVideo launcher instead of this panel.')
        selected = os.environ.get('FREEVIDEO_HOME')
        if selected and resolved(installation_root(self.source)) != root:
            raise ValueError('FREEVIDEO_HOME selects another installation. Change it before starting ComfyUI.')
        return Path(plain(root))

    @plain_errors
    def inspect(self, value):
        self.status()
        if self.runner.busy:
            raise ValueError('FreeVideo setup is already running')
        root = self.validate_root(value.get('root'))
        extra = value.get('extra_libraries', [])
        if not isinstance(extra, list) or not isinstance(value.get('copy', False), bool):
            raise ValueError('Invalid setup choices')
        # Folders the user chose are validated and kept first; folders found
        # automatically fill the remaining places.
        chosen = library_roots(extra, skip_missing=True)
        libraries = library_roots(chosen + discover_libraries(self.folder_paths), keep_first=True)
        io_path(self.logs).mkdir(parents=True, exist_ok=True)
        manifest = self.logs / ('libraries-' + uuid.uuid4().hex + '.json')
        save(manifest, dict(version=1, roots=libraries))
        # A download that cannot resume (for example a Xet partial) starts again
        # instead of pausing every retry; the old partial is set aside.
        arguments = ['setup', '--reuse-models-manifest', str(manifest), '--allow-model-restart']
        frontend = value.get('frontend')
        if frontend:
            arguments += ['--frontend-root', plain(resolved(Path(frontend['root']).expanduser()))]
            if frontend.get('separate'):
                arguments.append('--frontend-separate')
            if frontend.get('download'):
                arguments.append('--frontend-download')
            if frontend.get('repair_python'):
                arguments += ['--frontend-repair-python', frontend['repair_python']]
        if isinstance(value.get('sampling_caches'), bool):
            arguments.append('--sampling-caches' if value['sampling_caches'] else '--no-sampling-caches')
        if value.get('prepared_format') in ('int8', 'fp8'):
            arguments += ['--prepared-format', value['prepared_format']]
        if value.get('copy'):
            arguments.append('--copy-existing-models')
        if value.get('download_list'):
            arguments.append('--download-list')
        self.selection = dict(root=str(root), arguments=arguments)
        self.plan = None
        self.state = dict(status='running', action='plan', libraries=libraries)
        self.events.reset()
        self.runner.start('plan', root, [*arguments, '--plan', '--json'])
        return self.status()

    @plain_errors
    def bind(self, root):
        root = self.validate_root(root)
        installation(self.source, dict(os.environ, FREEVIDEO_HOME=str(root)))
        config = io_path(self.source) / 'comfyui.json'
        value = json.loads(config.read_text(encoding='utf-8')) if config.is_file() else {}
        value['installation'] = str(root)
        save(config, value)

    def install(self, value):
        self.status()
        if self.runner.busy or not self.plan or value.get('plan_id') != self.state.get('plan_id'):
            raise ValueError('Inspect this installation again before installing')
        if value.get('accept_licenses') is not True or self.plan.get('errors'):
            raise ValueError('Review the plan and accept its model/toolkit licenses first')
        # Inputs are held server-side; the browser cannot swap paths after consent.
        receipt = self.logs / ('approved-' + uuid.uuid4().hex + '.json')
        save(receipt, self.plan)
        selection = self.selection
        self.state = dict(status='running', action='setup')
        self.events.reset()
        self.plan = None  # Consent cannot be replayed, even if a worker fails.
        self.runner.start('setup', selection['root'], [*selection['arguments'], '--plain',
            '--yes', '--accept-model-license', '--approved-plan', str(receipt)])
        return self.status()

    def calibrate(self, value):
        """Start the placement sweep on the same worker the installer uses.

        It is a measurement, not a change: nothing it produces alters this
        installation's placement. It can run for hours, so it goes to the
        background runner and reports through the same status the panel already
        polls, and it refuses to start beside queued generation work rather
        than competing with it for the card.
        """
        state = self.status()
        # Order matters: a machine with no installation cannot calibrate no
        # matter how idle the worker is, and being told to wait for a task it
        # never started sends it looking for the wrong thing.
        root = installation_root(self.source)
        if not root or not Path(root).is_dir():
            raise ValueError('Install FreeVideo first. The placement test measures an '
                             'installed engine; it cannot run before setup finishes.')
        if self.runner.busy:
            # Name what is running. The panel shows its progress, and a user
            # who reads only this message otherwise has nothing to wait for.
            running = {'plan': 'the installation check', 'setup': 'the installation',
                       'calibrate': 'a placement test'}.get(
                           state.get('action'), state.get('action') or 'a setup task')
            raise ValueError('Wait for %s to finish; its progress is in this panel.' % running)
        repeats = value.get('repeats', 1)
        if type(repeats) is not int or not 1 <= repeats <= 4:
            raise ValueError('Repeats must be a whole number from 1 to 4')
        prompt = str(value.get('prompt') or CALIBRATION_PROMPT).strip()
        if not prompt:
            raise ValueError('Enter a prompt for the calibration to encode')
        run = self.logs / ('calibration-' + uuid.uuid4().hex)
        run.mkdir(parents=True, exist_ok=True)
        (run / 'prompt.txt').write_text(prompt, encoding='utf-8')
        arguments = ['calibrate', '--prompt-file', str(run / 'prompt.txt'),
                     '--out', str(run / 'report'), '--repeats', str(repeats)]
        # Hand the child a free card and a free lease, exactly as generation
        # does. The resident worker holds the lease while it works and the idle
        # prewarmer takes it between requests, and ComfyUI keeps its own models
        # resident: releasing only the first two left a 16 GiB RTX 5060 Ti with
        # ComfyUI's weights still on the card, and the text encoder died in
        # dequantize_int8_embedding with CUDA out of memory before any
        # measurement ran. The same prompt encodes in two and a half minutes on
        # a card that size when it is actually free. Best effort and in this
        # order: the workers exit first, so emptying the cache afterwards
        # returns what they held.
        released = []
        for name, release in (('idle_prewarm', self._stop_idle_prewarm),
                              ('resident_worker', self._close_resident_worker),
                              ('comfy_models', self._release_comfy_models)):
            try:
                release()
                released.append(name)
            except Exception as error:
                released.append('%s failed: %s' % (name, type(error).__name__))
        self.state = dict(status='running', action='calibrate', run=str(run),
                          released=released)
        self.events.reset()
        self.runner.start('calibrate', str(root), arguments)
        return self.status()

    def _stop_idle_prewarm(self):
        from .background_compile import COMPILE
        from .encoder_prewarm import IDLE
        COMPILE.stop()
        IDLE.stop()

    def _close_resident_worker(self):
        from .resident_process import OWNER
        OWNER.close()

    def _release_comfy_models(self):
        # Not keep_engine_cache(): that exists so a generation handoff keeps
        # the resident worker alive, and this one has already closed it.
        from comfy import model_management as memory
        memory.unload_all_models()
        memory.soft_empty_cache()

    @plain_errors
    def status(self):
        for kind, value in self.events.drain():
            if kind == 'started':
                self.state['log'] = value
            elif kind == 'progress':
                self.state['progress'] = value
            elif kind == 'log':
                self.state['tail'] = (self.state.get('tail', '') + value)[-8192:]
            elif kind == 'done':
                self.state.update({key: value[key] for key in ('status', 'action', 'error', 'wall_seconds', 'log')})
                if value['status'] == 'failed' and not value.get('error'):
                    # Older/bootstrap failures may not emit a structured error.
                    # Recover the complete retained output once, after exit.
                    try:
                        self.state['error'] = plain_text((io_path(value['log']) / 'launcher.log').read_text(encoding='utf-8', errors='replace'))
                    except OSError:
                        self.state['error'] = value.get('output') or self.state.get('tail', '')
                if value['action'] == 'plan' and value['status'] in ('complete', 'failed'):
                    try:
                        self.plan = preflight_json(value['output'])
                        self.state.update(plan=self.plan, plan_id=uuid.uuid4().hex)
                    except ValueError:
                        self.state.update(status='failed', error=inspection_failed(value) + '\n' +
                                          (self.state.get('error') or value.get('output', '')))
                elif value['action'] == 'setup' and value['status'] == 'complete':
                    try:
                        self.bind(value['root'])
                        self.state['ready'] = True
                    except (OSError, ValueError) as error:
                        self.state.update(status='failed', error=plain_text(error))
        return dict(self.state, **self.events.snapshot(), busy=self.runner.busy)


def register():
    from aiohttp import web
    import folder_paths
    from server import PromptServer
    server = PromptServer.instance
    if server is None or getattr(server, '_freevideo_setup', None) is not None:
        return
    setup = Setup(source_root(), folder_paths)
    server._freevideo_setup = setup

    @server.routes.get('/freevideo/setup')
    async def info(request):
        try:
            root=setup.validate_root(request.query['root']) if request.query.get('root') else None
            return web.json_response(dict(discovery=setup.discovery(root), task=setup.status()))
        except (OSError, ValueError) as error:
            return web.json_response({'error': str(error)}, status=400)

    @server.routes.post('/freevideo/setup/{action}')
    async def action(request):
        # Same-origin clients must first read the per-process token. Blind
        # cross-site forms cannot trigger filesystem changes or installations.
        if not secrets.compare_digest(request.headers.get('X-FreeVideo-Setup', ''), setup.token):
            return web.json_response({'error': 'Reload the setup panel'}, status=403)
        try:
            value = await request.json()
            if not isinstance(value, dict):
                raise ValueError('Invalid setup request')
            name = request.match_info['action']
            if name == 'inspect':
                result = setup.inspect(value)
            elif name == 'model-directories':
                result = setup.model_directories(value)
            elif name in ('network-probe','network-source'):
                result = setup.network_settings(value,probe=name=='network-probe')
            elif name == 'network-token':
                result = setup.download_token(value)
            elif name == 'resources':
                result = setup.resource_settings(value)
            elif name == 'calibrate':
                running, pending = server.prompt_queue.get_current_queue()
                if running or pending:
                    raise ValueError('Finish or cancel queued ComfyUI requests before calibrating')
                result = setup.calibrate(value)
            elif name in ('compatibility-check', 'compatibility-save', 'compatibility-ack'):
                result = setup.compatibility_settings(value, name)
            elif name == 'install':
                running, pending = server.prompt_queue.get_current_queue()
                if running or pending:
                    raise ValueError('Finish or cancel queued ComfyUI requests before installing')
                result = setup.install(value)
            elif name == 'use':
                if setup.runner.busy:
                    raise ValueError('Wait for setup to finish')
                setup.bind(value.get('root', ''))
                result = setup.discovery()
            elif name == 'cancel':
                setup.runner.cancel()
                result = setup.status()
            else:
                raise ValueError('Unknown setup action')
            return web.json_response(result)
        except (OSError, ValueError, RuntimeError) as error:
            return web.json_response({'error': str(error)}, status=400)