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.

Add the experimental Mac app (#49)

Bowen Xuec8aa5a9bedcb
diff --git a/.github/workflows/install.yml b/.github/workflows/install.yml
index b09ea3e..ea4b66e 100644
--- a/.github/workflows/install.yml
+++ b/.github/workflows/install.yml
@@ -76,9 +76,9 @@ jobs:
GH_TOKEN: ${{ github.token }}
shell: pwsh
run: |
- gh release download windows-preview --repo FlashML-org/FreeVideo --pattern FreeVideo.exe --pattern FreeVideo-Windows-folder.zip --dir build/previous-release
+ gh release download windows-preview --repo FlashML-org/FreeVideo --pattern FreeVideo.exe --dir build/previous-release
if ($LASTEXITCODE -ne 0) { throw 'Could not retrieve the previous release for comparison' }
- python scripts/scan_windows_release.py --file build/previous-release/FreeVideo.exe --file build/previous-release/FreeVideo-Windows-folder.zip --verify-launches build/previous-release/FreeVideo.exe build/previous-release/FreeVideo-Windows-folder.zip --report antivirus/previous-release.json
+ python scripts/scan_windows_release.py --file build/previous-release/FreeVideo.exe --report antivirus/previous-release.json
$baselineExit = $LASTEXITCODE
if (Test-Path antivirus/previous-release.json) { Get-Content antivirus/previous-release.json -Raw }
Write-Output "Previous-release diagnosis exit code: $baselineExit"
@@ -141,20 +141,19 @@ jobs:
$scripts = @(Get-ChildItem build/windows-folder/dist -Recurse -Filter *.ps1 | ForEach-Object FullName)
"bundled scripts: $($scripts.Count)"
./scripts/verify_windows_release.ps1 -FolderDist build/windows-folder/dist -Signed ($scripts + 'build/windows-exe/dist/FreeVideo.exe' + 'build/windows-folder/dist/FreeVideo/FreeVideo.exe')
- - name: Collect the folder launcher
- run: Copy-Item build/windows-folder/dist/FreeVideo-Windows-folder.zip build/windows-exe/dist/
- name: Hash final Windows launchers
shell: pwsh
run: |
- python -c "from pathlib import Path; import hashlib; p=Path('build/windows-exe/dist'); (p/'SHA256SUMS.txt').write_text(''.join(hashlib.sha256(f.read_bytes()).hexdigest()+' '+f.name+'\n' for f in (p/'FreeVideo.exe', p/'FreeVideo-Windows-folder.zip')))"
+ python -c "from pathlib import Path; import hashlib; p=Path('build/windows-exe/dist'); (p/'SHA256SUMS.txt').write_text(''.join(hashlib.sha256(f.read_bytes()).hexdigest()+' '+f.name+'\n' for f in (p/'FreeVideo.exe',)))"
# Keep the full report in the job log; a blocked or inconclusive scan
# must stop publication instead of making a suspicious build public.
+ # The folder layout is only checked here, not published.
- name: Open both packaged launchers and scan with real-time Defender
timeout-minutes: 20
shell: pwsh
run: |
$scripts = @(Get-ChildItem build/windows-folder/dist -Recurse -Filter *.ps1 | ForEach-Object { '--script', $_.FullName })
- python scripts/scan_windows_release.py --file build/windows-exe/dist/FreeVideo.exe --file build/windows-folder/dist/FreeVideo/FreeVideo.exe --file build/windows-exe/dist/FreeVideo-Windows-folder.zip @scripts --verify-launches build/windows-exe/dist/FreeVideo.exe build/windows-exe/dist/FreeVideo-Windows-folder.zip --report antivirus/report.json
+ python scripts/scan_windows_release.py --file build/windows-exe/dist/FreeVideo.exe --file build/windows-folder/dist/FreeVideo/FreeVideo.exe --file build/windows-folder/dist/FreeVideo-Windows-folder.zip @scripts --verify-launches build/windows-exe/dist/FreeVideo.exe build/windows-folder/dist/FreeVideo-Windows-folder.zip --report antivirus/report.json
$scanExit = $LASTEXITCODE
if (Test-Path antivirus/report.json) { Get-Content antivirus/report.json -Raw }
exit $scanExit
@@ -268,6 +267,8 @@ jobs:
[Discord](https://discord.gg/MsA277cJzZ) · [QQ Group / QQ 群](https://freevideo-community.pages.dev/qq) · [WeChat Group / 微信群](https://freevideo-community.pages.dev/wechat)
NOTES
+ python "$GITHUB_WORKSPACE/freevideo_engine/release_notes.py" --build launcher-build.json --out release-notes.md --prepend
+ release_title=$(python -c 'import json; print("FreeVideo v" + json.load(open("launcher-build.json"))["product_version"] + " for Windows")' | tr -d '\r')
# A failed read is not evidence that a tag or release is missing.
gh_json 'Read preview tags' api "repos/$GH_REPO/git/matching-refs/tags/$preview_tag" > tags.json
tag_exists=$(python -c 'import json; print(int(any(r["ref"] == "refs/tags/windows-preview" for r in json.load(open("tags.json")))))' | tr -d '\r')
@@ -279,9 +280,9 @@ jobs:
gh_retry 'Create preview tag' gh api -X POST "repos/$GH_REPO/git/refs" -f ref="refs/tags/$preview_tag" -f sha="$GITHUB_SHA" > /dev/null
fi
if [ "$release_exists" = 0 ]; then
- gh_retry 'Create draft release' gh release create "$preview_tag" --verify-tag --draft --prerelease --latest=false --title 'FreeVideo for Windows' --notes-file release-notes.md
+ gh_retry 'Create draft release' gh release create "$preview_tag" --verify-tag --draft --prerelease --latest=false --title "$release_title" --notes-file release-notes.md
fi
- gh_retry 'Upload launcher' gh release upload "$preview_tag" FreeVideo.exe FreeVideo-Windows-folder.zip SHA256SUMS.txt --clobber
+ gh_retry 'Upload launcher' gh release upload "$preview_tag" FreeVideo.exe SHA256SUMS.txt --clobber
# Publish metadata last, bound to the immutable executable asset ID.
# Readers reject a mismatched pair while a moving preview is updating.
gh_json 'Locate release including drafts' release view "$preview_tag" --json databaseId > release-id.json
@@ -299,8 +300,14 @@ jobs:
sha256=hashlib.sha256(binary.read_bytes()).hexdigest())
Path('update.json').write_text(json.dumps(build, indent=2))
PY
+ # The folder ZIP is no longer published; remove the copy an earlier
+ # release left so the page lists only current files.
+ retired=$(python -c 'import json; print(int(any(a["name"] == "FreeVideo-Windows-folder.zip" for a in json.load(open("release.json"))["assets"])))' | tr -d '\r')
+ if [ "$retired" = 1 ]; then
+ gh_retry 'Remove retired folder ZIP' gh release delete-asset "$preview_tag" FreeVideo-Windows-folder.zip --yes
+ fi
gh_retry 'Upload update manifest' gh release upload "$preview_tag" update.json --clobber
- gh_retry 'Publish release' gh release edit "$preview_tag" --draft=false --prerelease --latest=false --title 'FreeVideo for Windows' --notes-file release-notes.md
+ gh_retry 'Publish release' gh release edit "$preview_tag" --draft=false --prerelease --latest=false --title "$release_title" --notes-file release-notes.md
# Previous development snapshots have been archived privately.
# Remove their release/source-archive references only after replacement.
python - <<'PY_CLEANUP'
diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml
new file mode 100644
index 0000000..363da9d
--- /dev/null
+++ b/.github/workflows/macos.yml
@@ -0,0 +1,55 @@
+name: Build Mac launcher
+on:
+ workflow_dispatch:
+permissions:
+ contents: read
+concurrency:
+ group: freevideo-macos-build-${{ github.ref }}
+ cancel-in-progress: false
+jobs:
+ macos:
+ runs-on: macos-15
+ timeout-minutes: 30
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.12'
+ architecture: arm64
+ cache: pip
+ cache-dependency-path: constraints/macos-launcher.txt
+ - name: Check installation and build the Apple Silicon launcher
+ run: |
+ python -c "import platform; assert platform.machine() == 'arm64'"
+ python scripts/check_installation.py
+ python -m pip install -r constraints/macos-launcher.txt
+ python scripts/build_macos.py --out build/macos
+ - name: Verify both archives and native startup
+ env:
+ FREEVIDEO_LAUNCHER_HOME: ${{ runner.temp }}/freevideo-launcher-state
+ run: |
+ python scripts/verify_macos_build.py --build build/macos --out build/macos-verification
+ build/macos/applications.noindex/FreeVideo.app/Contents/MacOS/FreeVideo --smoke-test "$RUNNER_TEMP/freevideo-smoke"
+ python -c "import json, os; from pathlib import Path; value=json.loads((Path(os.environ['RUNNER_TEMP'])/'freevideo-smoke/smoke.json').read_text()); assert value['success'] and not value['model_modules_imported']"
+ - name: Keep checked preview artifacts
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: FreeVideo-Mac-arm64-${{ github.sha }}
+ path: |
+ build/macos/dist/*
+ build/macos/launcher-build.json
+ build/macos-verification/result.json
+ ${{ runner.temp }}/freevideo-smoke/smoke.json
+ if-no-files-found: error
+ retention-days: 7
+ - name: Keep failure diagnostics
+ if: failure()
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: FreeVideo-Mac-build-failure-${{ github.sha }}
+ path: |
+ build/macos/build-result.json
+ build/macos-verification/result.json
+ ${{ runner.temp }}/freevideo-smoke/smoke.json
+ if-no-files-found: ignore
+ retention-days: 7
diff --git a/MANIFEST.in b/MANIFEST.in
index d1aa63f..23467ce 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -11,6 +11,7 @@ recursive-include freevideo_engine/launcher/licenses *.txt
recursive-include freevideo_engine/licenses *.txt
recursive-include constraints *.txt
include scripts/bootstrap_linux.sh scripts/build_windows.py scripts/windows_app.py scripts/check_installation.py
+include scripts/build_macos.py scripts/macos_app.py scripts/verify_macos_build.py
include scripts/scan_windows_release.py
include scripts/build_launcher_notices.py
prune docs
diff --git a/README.md b/README.md
index 7cefca4..f23e923 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ It coordinates VRAM, system memory and disk, adapting weight placement, compute
- **Multimodal inputs**: Text prompts, first and last frames, and image, video and audio references.
- **Community LoRAs**: Use MiniMax H3 LoRAs in your workflow. See [examples](docs/LoRA.md).
- **ComfyUI integration**: A dedicated creative workspace inside ComfyUI that supports two-pass sampling and batch generation and keeps a history of past creations. For finer control, switch to the node view to add LoRAs or customize the workflow.
-- **One-click deployment**: The Windows launcher sets up ComfyUI, the runtime environment and the models, reuses existing models, and supports offline installation.
+- **One-click deployment**: The Windows and Mac launchers set up ComfyUI, the runtime environment and the models, reuse existing models, and support offline installation.
## Getting Started
@@ -42,6 +42,16 @@ It coordinates VRAM, system memory and disk, adapting weight placement, compute
**Offline installation:** Download the packages from [Quark](https://pan.quark.cn/s/c51235b84618) and drag the ZIP files into the launcher without extracting them. The common models and the model pack for your GPU (30/40 series or 50 series) are required; a new ComfyUI installation also requires the environment package.
+### macOS (Apple silicon preview)
+
+1. [Download FreeVideo-Mac-arm64.dmg](https://github.com/FlashML-org/FreeVideo/releases/download/macos-preview/FreeVideo-Mac-arm64.dmg), open it and drag **FreeVideo.app** into **Applications**.
+2. Open FreeVideo, then select an existing ComfyUI folder or install a new one. Existing model folders can be added for reuse; the runtime environment and missing models are downloaded automatically.
+3. Click **Install & launch**. ComfyUI opens in the browser with the FreeVideo workspace.
+
+This preview has been tested on an M5 Mac with 24 GB of unified memory. See the [Mac&nbsp;guide](docs/Mac.md) for generation times and memory.
+
+The Mac preview isn't notarized by Apple yet, so macOS blocks it the first time you open it. Download it only from the Releases page, then check the file and approve it as described in the [Mac guide](docs/Mac.md#first-open). This approves FreeVideo only; your other security settings stay as they are.
+
### Existing ComfyUI
Install FreeVideo as a custom node:
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 83e74da..ee06be2 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -26,7 +26,7 @@ FreeVideo 是面向消费级显卡的 MiniMax H3 本地推理引擎,基于 [Op
- **多模态输入**:支持文本、首帧、尾帧,以及图像、视频、音频参考输入。
- **社区 LoRA**:支持在工作流中使用 MiniMax H3 社区 LoRA。[查看效果对比](docs/LoRA.zh-CN.md)。
- **ComfyUI 集成**:在 ComfyUI 中提供专门的创作面板,支持二次采样和批量生成,并可浏览历史作品;需要更精细的控制时,可切换到节点视图,接入 LoRA 或自定义工作流。
-- **一键部署**:Windows 启动器自动完成 ComfyUI、运行环境与模型的部署,可复用已有模型,并支持离线安装。
+- **一键部署**:Windows 和 Mac 启动器自动完成 ComfyUI、运行环境与模型的部署,可复用已有模型,并支持离线安装。
## 开始使用
@@ -42,6 +42,16 @@ FreeVideo 是面向消费级显卡的 MiniMax H3 本地推理引擎,基于 [Op
**离线安装:** 从[夸克网盘](https://pan.quark.cn/s/c51235b84618)下载离线包,将 ZIP 文件直接拖入启动器,无需解压。需要「公用模型」包和对应显卡的模型包(30/40 系或 50 系);全新安装 ComfyUI 时还需要「运行环境」包。
+### macOS(Apple 芯片预览版)
+
+1. [下载 FreeVideo-Mac-arm64.dmg](https://github.com/FlashML-org/FreeVideo/releases/download/macos-preview/FreeVideo-Mac-arm64.dmg),打开后将 **FreeVideo.app** 拖入 **应用程序**。
+2. 打开 FreeVideo,选择已有的 ComfyUI 目录或安装新的 ComfyUI。可添加已有的模型目录以复用文件,缺失的运行环境和模型会自动下载。
+3. 点击 **安装并启动**,浏览器中会打开带有 FreeVideo 创作面板的 ComfyUI。
+
+预览版已在 24GB 统一内存的 M5 Mac 上测试,生成耗时与内存说明见 [Mac 说明](docs/Mac.zh-CN.md)。
+
+Mac 预览版暂未进行 Apple 公证,首次打开时 macOS 会拦截。请只从 Release 页面下载,按 [Mac 说明](docs/Mac.zh-CN.md#首次打开)核对文件后再放行。这只对 FreeVideo 生效,不影响其他安全设置。
+
### 已有 ComfyUI
以自定义节点方式安装:
diff --git a/constraints/macos-launcher.txt b/constraints/macos-launcher.txt
new file mode 100644
index 0000000..39e1ff3
--- /dev/null
+++ b/constraints/macos-launcher.txt
@@ -0,0 +1,4 @@
+# Native arm64 launcher only; inference is installed separately.
+pyinstaller==6.22.3
+psutil==7.2.2
+PySide6-Essentials==6.11.2
diff --git a/constraints/macos-runtime-requirements.txt b/constraints/macos-runtime-requirements.txt
new file mode 100644
index 0000000..3a2708d
--- /dev/null
+++ b/constraints/macos-runtime-requirements.txt
@@ -0,0 +1,20 @@
+# Native Torch and the shared H3 encoder libraries. No CUDA index or packages.
+torch
+torchvision
+torchaudio
+# Fused Metal attention for the sampling window leg (streams keys; PyTorch MPS SDPA materializes scores).
+mlx
+-r encoder-runtime.txt
+accelerate
+peft
+omegaconf
+modelscope-hub
+huggingface-hub
+hf-xet
+httpx[socks]
+requests[socks]
+importlib-metadata
+packaging
+wheel
+setuptools
+pip
diff --git a/constraints/macos-runtime.txt b/constraints/macos-runtime.txt
new file mode 100644
index 0000000..4db0198
--- /dev/null
+++ b/constraints/macos-runtime.txt
@@ -0,0 +1,68 @@
+# Native Apple Silicon runtime pins, resolved separately from CUDA environments.
+# Source/model compatibility and full generation require separate validation.
+accelerate==1.14.0
+annotated-doc==0.0.5
+antlr4-python3-runtime==4.9.3
+anyio==4.15.1
+av==18.1.0
+certifi==2026.7.22
+cffi==2.1.1
+charset-normalizer==3.5.1
+click==8.5.0
+comfy-aimdo==0.5.3
+comfy-kitchen==0.2.33
+cryptography==50.0.1
+einops==0.8.2
+filelock==3.32.3
+fsspec==2026.7.0
+h11==0.16.0
+hf-xet==1.6.1a0
+httpcore==1.0.9
+httpx==0.28.1
+huggingface-hub==1.30.0
+idna==3.19
+importlib-metadata==9.0.1
+jinja2==3.1.6
+markdown-it-py==4.2.0
+markupsafe==3.0.3
+mdurl==0.1.2
+mlx==0.32.3
+mlx-metal==0.32.3
+mpmath==1.3.0
+modelscope-hub==0.4.2
+networkx==3.6.1
+ninja==1.13.2
+numpy==2.5.2
+omegaconf==2.3.1
+packaging==26.3
+peft==0.20.0
+pillow==12.3.0
+pip==26.2.1
+psutil==7.2.2
+pygments==2.21.0
+pycparser==3.0
+pysocks==1.7.1
+pyyaml==6.0.3
+regex==2026.9.3
+requests==2.34.2
+rich==15.0.0
+safetensors==0.8.0
+scipy==1.18.1
+sentencepiece==0.2.2
+setuptools==78.1.0
+shellingham==1.5.4
+sympy==1.14.0
+socksio==1.0.0
+tokenizers==0.23.0rc0
+torch==2.13.0
+torchaudio==2.11.0
+torchsde==0.2.6
+torchvision==0.28.0
+tqdm==4.70.0
+trampoline==0.1.2
+transformers==5.15.0
+typer==0.27.2
+typing-extensions==4.16.0
+urllib3==2.7.0
+wheel==0.48.0
+zipp==4.1.0
diff --git a/docs/Mac.md b/docs/Mac.md
new file mode 100644
index 0000000..f32b57b
--- /dev/null
+++ b/docs/Mac.md
@@ -0,0 +1,41 @@
+# Mac (experimental)
+
+English · [中文](Mac.zh-CN.md)
+
+FreeVideo runs MiniMax H3 locally on Apple silicon Macs with macOS 14 or later and the Xcode Command Line Tools. Mac support is experimental and still being optimized.
+
+## Installation
+
+1. [Download FreeVideo-Mac-arm64.dmg](https://github.com/FlashML-org/FreeVideo/releases/download/macos-preview/FreeVideo-Mac-arm64.dmg) and drag FreeVideo into Applications.
+2. Open FreeVideo. The preview needs your approval the first time; see [First open](#first-open).
+3. Choose an install location, optionally add existing model folders, and click **Install & launch**. The Mac environment and missing models are downloaded automatically.
+
+## First open
+
+The Mac preview isn't notarized by Apple yet, so macOS blocks it the first time and says it can't verify the developer. Before approving it, make sure the file is the official one:
+
+1. Download it only from the [FreeVideo releases page](https://github.com/FlashML-org/FreeVideo/releases/tag/macos-preview).
+2. In Terminal, run `shasum -a 256 ~/Downloads/FreeVideo-Mac-arm64.dmg`. The result should match the value in SHA256SUMS.txt on the release.
+3. Open FreeVideo and dismiss the alert. Then, in **System Settings → Privacy & Security**, find FreeVideo, click **Open Anyway** and confirm.
+
+This approves FreeVideo only. It doesn't turn off Gatekeeper or change your other security settings. If macOS says the file is damaged or contains malware, don't open it, and let us know. Once FreeVideo is notarized, this step goes away.
+
+## Features
+
+- Computation runs on the GPU through Metal; attention in sampling and video decoding uses MLX's fused kernels.
+- Before each stage, attention head groups, chunk sizes and the number of resident transformer layers are set from the unified memory available at that moment.
+- Macs download ConvRot int8 weights. On Apple M5 and newer, the large projections run as int8 on the GPU's Metal 4 tensor units; earlier Macs decode them to BF16 on the GPU as each layer loads.
+- Layers that are not kept in memory stream from disk with read-ahead.
+- Text prompts, first-frame input and two-pass sampling are supported.
+
+## Generation time
+
+On an M5 with 24 GB of unified memory and about 14 GB available:
+
+| Resolution | Length | Time |
+| --- | --- | --- |
+| 1344 × 768 | 10 s | about 42 min |
+| 960 × 544 | 10 s | about 22 min |
+| 512 × 512 | 1.6 s | about 3 min |
+
+These times use the M5's int8 tensor units. Macs before the M5 run the same weights in BF16 and take longer. Mac support is still being optimized; more unified memory and newer chips shorten generation further.
diff --git a/docs/Mac.zh-CN.md b/docs/Mac.zh-CN.md
new file mode 100644
index 0000000..8032960
--- /dev/null
+++ b/docs/Mac.zh-CN.md
@@ -0,0 +1,41 @@
+# Mac(实验性)
+
+[English](Mac.md) · 中文
+
+FreeVideo 可在 Apple 芯片 Mac 上本地运行 MiniMax H3,需要 macOS 14 及以上和 Xcode 命令行工具。Mac 版本目前为实验性质,仍在持续优化。
+
+## 安装
+
+1. [下载 FreeVideo-Mac-arm64.dmg](https://github.com/FlashML-org/FreeVideo/releases/download/macos-preview/FreeVideo-Mac-arm64.dmg),将 FreeVideo 拖入「应用程序」。
+2. 打开 FreeVideo。预览版首次打开需要你确认一次,见下方[首次打开](#首次打开)。
+3. 选择安装位置,可添加已有的模型目录,然后点击 **安装并启动**。Mac 运行环境和缺失的模型会自动下载。
+
+## 首次打开
+
+Mac 预览版暂未进行 Apple 公证,因此首次打开时 macOS 会拦截,并提示无法验证开发者。放行前请先确认文件来自官方:
+
+1. 只从 [FreeVideo 的 Release 页面](https://github.com/FlashML-org/FreeVideo/releases/tag/macos-preview)下载。
+2. 在「终端」中运行 `shasum -a 256 ~/Downloads/FreeVideo-Mac-arm64.dmg`,输出应与 Release 中 SHA256SUMS.txt 里的值一致。
+3. 打开 FreeVideo,关闭系统提示后,在 **系统设置 → 隐私与安全** 中找到 FreeVideo,点击 **仍要打开** 并按提示确认。
+
+这只放行 FreeVideo,不会关闭 Gatekeeper,也不会改动其他安全设置。如果系统提示文件已损坏或包含恶意软件,请不要打开,并向我们反馈。完成公证后将不再需要这一步。
+
+## 特性
+
+- 通过 Metal 在 GPU 上计算,采样和视频解码中的注意力使用 MLX 融合内核。
+- 每个阶段开始前,根据当前可用的统一内存确定注意力头分组、分块大小和常驻的 Transformer 层数。
+- Mac 下载 ConvRot int8 权重。M5 及更新的芯片在 GPU 的 Metal 4 张量单元上以 int8 计算大矩阵;更早的芯片在每层加载时于 GPU 上解码为 BF16 计算。
+- 未常驻内存的层从磁盘流式加载并提前预取。
+- 支持文本、首帧输入和二次采样。
+
+## 生成时间
+
+在 M5、24GB 统一内存、可用内存约 14GB 的情况下:
+
+| 分辨率 | 时长 | 生成时间 |
+| --- | --- | --- |
+| 1344 × 768 | 10 秒 | 约 42 分钟 |
+| 960 × 544 | 10 秒 | 约 22 分钟 |
+| 512 × 512 | 1.6 秒 | 约 3 分钟 |
+
+以上时间使用了 M5 的 int8 张量单元。M5 之前的 Mac 以 BF16 运行同一套权重,耗时更长。Mac 版本仍在持续优化,更大的统一内存和更新的芯片都会进一步缩短生成时间。
diff --git a/freevideo_engine/adaln.py b/freevideo_engine/adaln.py
index 9e9d524..013a0a5 100644
--- a/freevideo_engine/adaln.py
+++ b/freevideo_engine/adaln.py
@@ -130,7 +130,7 @@ class TableCache:
raise ValueError('Nonfinite AdaLN model asset')
return [state[f'step_{i}'].chunk(6, dim=-1) for i in range(steps)]
- def save(self, index, module):
+ def save(self, index, module, *, producer_device=None):
from . import adaln_assets as assets
from .monitoring import save
if self.asset is not None:
@@ -148,13 +148,18 @@ class TableCache:
provenance = self.root / 'producer.json'
if not provenance.exists():
from diffusers.models.transformers import transformer_minimax_h3
- save(provenance, {'torch': str(torch.__version__), 'cuda': torch.version.cuda,
+ producer = {'torch': str(torch.__version__), 'cuda': torch.version.cuda,
'gpu': torch.cuda.get_device_name() if str(self.device).startswith('cuda') else 'cpu',
'implementation': assets.file_hash(__file__),
'original_implementation': assets.file_hash(transformer_minimax_h3.__file__),
'matmul_precision': torch.get_float32_matmul_precision(),
'tf32': torch.backends.cuda.matmul.allow_tf32,
- 'bf16_reduced_reduction': torch.backends.cuda.matmul.allow_bf16_reduced_precision_reduction})
+ 'bf16_reduced_reduction': torch.backends.cuda.matmul.allow_bf16_reduced_precision_reduction}
+ if producer_device is not None:
+ # Storage/loading can be CPU even when constants were computed
+ # on Metal. Existing CUDA callers keep their original receipt.
+ producer.update(device_backend=producer_device, gpu=producer_device)
+ save(provenance, producer)
@torch.no_grad()
diff --git a/freevideo_engine/adaln_assets.py b/freevideo_engine/adaln_assets.py
index 918c2c6..74b653c 100644
--- a/freevideo_engine/adaln_assets.py
+++ b/freevideo_engine/adaln_assets.py
@@ -15,6 +15,8 @@ import struct
CONTRACT = 'minimax-h3-adaln-silu-linear-3x6-v1'
FORMAT = 'freevideo-adaln-v2'
SLIM_FORMAT = 'freevideo-fp8-slim-v1'
+# The int8 export keeps the slim layout and its AdaLN tables; only matrices differ.
+SLIM_FORMATS = (SLIM_FORMAT, 'freevideo-int8-slim-v1')
def digest(value):
@@ -122,7 +124,7 @@ def check_table(path, row, expected, *, verify_hash=True):
def validate_catalog(manifest, count):
"""Return every required asset row; no file I/O, Torch or device probing."""
tables = manifest.get('adaln_tables', [])
- slim = manifest.get('format') == SLIM_FORMAT
+ slim = manifest.get('format') in SLIM_FORMATS
sources = projection_groups(manifest)
for row in sources:
if (row['file'] != row['group'] + '.safetensors' or
diff --git a/freevideo_engine/attention.py b/freevideo_engine/attention.py
index 20fd7e9..1c1c4fa 100644
--- a/freevideo_engine/attention.py
+++ b/freevideo_engine/attention.py
@@ -1,15 +1,13 @@
"""Official decomposed attention or portable cuDNN/Sage window calls."""
import types
-import importlib.metadata
from collections import defaultdict
import torch
-import torch.nn.functional as F
-from torch.nn.attention import SDPBackend, sdpa_kernel
+from .backends import get_backend
from .paths import add_vdn
add_vdn()
-from src.models.softmax_attention.decomposed import _plan, window_softmax_decomposed
+from src.models.softmax_attention.decomposed import _plan
ALIASES = {'original': 'cudnn/fa4', 'dense': 'cudnn/cudnn',
@@ -18,22 +16,23 @@ ALIASES = {'original': 'cudnn/fa4', 'dense': 'cudnn/cudnn',
BACKENDS = ('cudnn', 'torch-flash', 'sage2', 'fa2', 'fa4')
-def split_backend(backend):
+def split_backend(backend, allowed=BACKENDS):
parts = ALIASES.get(backend, backend).split('/')
if len(parts) == 1:
parts *= 2
- if len(parts) != 2 or any(p not in BACKENDS for p in parts):
- raise ValueError('Attention must be a backend or global/window pair: ' + ', '.join(BACKENDS))
+ if len(parts) != 2 or any(p not in allowed for p in parts):
+ raise ValueError('Attention must be a backend or global/window pair: ' + ', '.join(allowed))
return tuple(parts)
class WindowAttention:
def __init__(self, backend, query_chunk=0, window_batch=1, window_varlen=False,
- varlen_smooth_k=True):
+ varlen_smooth_k=True, *, device_backend=None):
if window_batch < 1:
raise ValueError('Window batch must be positive')
if window_varlen and query_chunk:
raise ValueError('Packed varlen windows do not support a query-chunk override')
+ self.device_backend = device_backend if device_backend is not None else get_backend()
self.backend = backend
self.query_chunk = query_chunk
self.window_batch = window_batch
@@ -47,55 +46,28 @@ class WindowAttention:
self.batches = None
self.calls = 0
self.window_calls = 0
- self.backend_calls = {part + '_' + name: 0 for part in ('global', 'window')
- for name in (*BACKENDS, 'fa2_varlen', 'fa4_varlen', 'sage2_varlen')}
+ names = ((*BACKENDS, 'fa2_varlen', 'fa4_varlen', 'sage2_varlen')
+ if self.device_backend.capabilities.name == 'cuda'
+ else self.device_backend.capabilities.attention_candidates)
+ self.backend_calls = {part + '_' + name: 0 for part in ('global', 'window') for name in names}
self.select_backend(backend)
def batched(self, q, k, v, scale, *, window=False):
leg = self.window_backend if window else self.global_backend
self.calls += 1
self.backend_calls[('window_' if window else 'global_') + leg] += 1
- if leg == 'sage2':
- return self.attention(q, k, v, tensor_layout='NHD', is_causal=False, sm_scale=scale)
- if leg == 'fa2':
- from flash_attn.flash_attn_interface import flash_attn_func
- return flash_attn_func(q, k, v, softmax_scale=scale, causal=False)
- if leg == 'fa4':
- from flash_attn.cute import flash_attn_func
- result = flash_attn_func(q, k, v, softmax_scale=scale, causal=False)
- return result[0] if isinstance(result, tuple) else result
- backend = SDPBackend.CUDNN_ATTENTION if leg == 'cudnn' else SDPBackend.FLASH_ATTENTION
- with sdpa_kernel(backend):
- result = F.scaled_dot_product_attention(q.transpose(1, 2), k.transpose(1, 2),
- v.transpose(1, 2), scale=scale)
- return result.transpose(1, 2)
+ return self.kernels.batched(leg, q, k, v, scale)
def dense(self, q, k, v, scale, *, window=False):
return self.batched(q.unsqueeze(0), k.unsqueeze(0), v.unsqueeze(0), scale, window=window)[0]
def select_backend(self, backend):
- self.global_backend, self.window_backend = split_backend(backend)
- if 'fa4' in (self.global_backend, self.window_backend):
- from .fa4_guard import check_selected
- check_selected()
- if self.window_backend in ('fa2', 'fa4') and self.query_chunk:
- raise ValueError('Packed varlen windows do not support a query-chunk override')
- if self.window_varlen and self.window_backend not in ('sage2', 'fa2', 'fa4'):
- raise ValueError('Packed varlen windows require a sage2, fa2 or fa4 window backend')
- if 'sage2' in (self.global_backend, self.window_backend):
- if not importlib.metadata.version('sageattention').startswith('2.'):
- raise ImportError('The sage2 route requires SageAttention 2.x; the tested version is 2.2.0.')
- from .triton_compat import activate
- activate()
- from sageattention import sageattn
- self.attention = sageattn
- if self.window_varlen and self.window_backend == 'sage2':
- from sageattention import sageattn_varlen
- self.attention_varlen = sageattn_varlen
- if 'fa2' in (self.global_backend, self.window_backend):
- if not importlib.metadata.version('flash-attn').startswith('2.'):
- raise ImportError('The fa2 route requires flash-attn 2.x.')
- from flash_attn.flash_attn_interface import flash_attn_varlen_func
+ global_backend, window_backend = split_backend(backend,
+ allowed=self.device_backend.capabilities.attention_candidates)
+ kernels = self.device_backend.attention_kernels(global_backend, window_backend,
+ query_chunk=self.query_chunk, window_varlen=self.window_varlen)
+ self.global_backend, self.window_backend = global_backend, window_backend
+ self.kernels = kernels
self.backend = backend
def _window_batches(self, plan):
@@ -136,7 +108,7 @@ class WindowAttention:
self.backend_calls['global_cudnn'] += bool(len(plan.dense_q))
self.backend_calls['window_fa4_varlen'] += bool(plan.has_windows)
self.window_calls += 1
- return window_softmax_decomposed(q, k, v, layout, bounds, scale, anchor_frames)
+ return self.kernels.decomposed(q, k, v, layout, bounds, scale, anchor_frames)
plan = self.prepare(layout, bounds, q.device, anchor_frames)
out = torch.empty_like(q)
if len(plan.dense_q):
@@ -145,25 +117,11 @@ class WindowAttention:
rows = plan.dense_q[start:start + chunk]
out[rows] = self.dense(q[rows], k, v, scale)
if plan.has_windows:
- if self.window_varlen and self.window_backend == 'sage2':
- # Every window in one kernel: no Python loop, no per-window
- # gather temporaries. Keys are smoothed across the packed batch.
- out[plan.win_q] = self.attention_varlen(
- q[plan.win_q], k[plan.kv_gather], v[plan.kv_gather],
- cu_seqlens_q=plan.cu_q, cu_seqlens_k=plan.cu_k,
- max_seqlen_q=plan.max_q, max_seqlen_k=plan.max_k,
- sm_scale=scale, is_causal=False, smooth_k=self.varlen_smooth_k)
- self.backend_calls['window_sage2_varlen'] += 1
- elif self.window_backend in ('fa2', 'fa4'):
- if self.window_backend == 'fa2':
- from flash_attn.flash_attn_interface import flash_attn_varlen_func
- else:
- from flash_attn.cute import flash_attn_varlen_func
- result = flash_attn_varlen_func(q[plan.win_q], k[plan.kv_gather], v[plan.kv_gather],
- cu_seqlens_q=plan.cu_q, cu_seqlens_k=plan.cu_k,
- max_seqlen_q=plan.max_q, max_seqlen_k=plan.max_k,
- softmax_scale=scale, causal=False)
- out[plan.win_q] = result[0] if isinstance(result, tuple) else result
+ if ((self.window_varlen and self.window_backend == 'sage2')
+ or self.window_backend in ('fa2', 'fa4')):
+ out[plan.win_q] = self.kernels.varlen(
+ self.window_backend, q[plan.win_q], k[plan.kv_gather], v[plan.kv_gather],
+ plan, scale, smooth_k=self.varlen_smooth_k)
self.backend_calls['window_' + self.window_backend + '_varlen'] += 1
elif self.window_batch > 1:
if self.batches is None:
diff --git a/freevideo_engine/backends/__init__.py b/freevideo_engine/backends/__init__.py
new file mode 100644
index 0000000..47eae8c
--- /dev/null
+++ b/freevideo_engine/backends/__init__.py
@@ -0,0 +1,12 @@
+"""Explicit device selection; importing this package does not load Torch kernels."""
+from .base import BackendCapabilities, DeviceBackend
+
+
+def get_backend(name='cuda', *, torch_module=None):
+ if name == 'cuda':
+ from .cuda import CUDABackend
+ return CUDABackend(torch_module=torch_module)
+ if name == 'mps':
+ from .mps import MPSBackend
+ return MPSBackend(torch_module=torch_module)
+ raise ValueError('Unknown device backend: ' + str(name))
diff --git a/freevideo_engine/backends/base.py b/freevideo_engine/backends/base.py
new file mode 100644
index 0000000..e21f731
--- /dev/null
+++ b/freevideo_engine/backends/base.py
@@ -0,0 +1,89 @@
+"""Device services used by the runtime, independent of an OS or Torch import.
+
+Backends must preserve the requested arithmetic policy or reject it. Selection
+never means that every candidate kernel is installed or supported by the device.
+Memory observations and enforcement are backend-specific: unified memory must
+not be added to host RAM as if it were a separate physical pool.
+"""
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BackendCapabilities:
+ name: str
+ memory_model: str
+ linear_policies: tuple[str, ...]
+ attention_candidates: tuple[str, ...]
+ pinned_host_weights: bool
+ streamed_weights: bool
+
+
+class DeviceBackend(ABC):
+ """Current-device contract. A backend owns placement and its memory policy.
+
+ Streams, events and PCIe scheduling belong to the CUDA offloader, not this
+ interface. A unified-memory implementation must supply its own transport.
+ Creating a backend must not initialize an accelerator or allocate tensors.
+ """
+ capabilities: BackendCapabilities
+ device: str
+
+ @abstractmethod
+ def is_available(self): ...
+
+ @abstractmethod
+ def synchronize(self): ...
+
+ @abstractmethod
+ def empty_cache(self): ...
+
+ @abstractmethod
+ def memory_info(self):
+ """Return available/total bytes in the device budget domain.
+
+ A unified-memory backend must define its admitted working-set domain;
+ it must not report host RAM plus a second copy of GPU capacity.
+ """
+
+ @abstractmethod
+ def max_memory_allocated(self): ...
+
+ @abstractmethod
+ def max_memory_reserved(self): ...
+
+ @abstractmethod
+ def reset_peak_memory_stats(self): ...
+
+ @abstractmethod
+ def configure_budget(self, budget_bytes, allocator_limit_bytes=None, *,
+ reserve_bytes=0, capacity_trial=False): ...
+
+ @abstractmethod
+ def arithmetic_identity(self):
+ """Device and arithmetic flags for cache invalidation, not a parity claim."""
+
+ @abstractmethod
+ def attention_kernels(self, global_backend, window_backend, *,
+ query_chunk=0, window_varlen=False): ...
+
+ @abstractmethod
+ def prepare_linears(self, model, manifest, linear_compute, fp8_gemm): ...
+
+ @abstractmethod
+ def install_chunked_ff(self, module, chunk, *, recompute=False): ...
+
+ @abstractmethod
+ def make_offloader(self, layers, **options): ...
+
+ @abstractmethod
+ def pin_layer_weights(self, layers, **options): ...
+
+ @abstractmethod
+ def host_memory_stats(self): ...
+
+ @abstractmethod
+ def prepare_streamed_layer(self, layer, source, index, **options): ...
+
+ @abstractmethod
+ def unload_streamed_layer(self, layer, source, index): ...
diff --git a/freevideo_engine/backends/cuda.py b/freevideo_engine/backends/cuda.py
new file mode 100644
index 0000000..a3ff72d
--- /dev/null
+++ b/freevideo_engine/backends/cuda.py
@@ -0,0 +1,110 @@
+"""CUDA services. Existing kernels and transfer scheduling remain authoritative."""
+from .base import BackendCapabilities, DeviceBackend
+
+
+class CUDABackend(DeviceBackend):
+ device = 'cuda'
+ capabilities = BackendCapabilities(
+ name='cuda', memory_model='dedicated',
+ linear_policies=('native-fp8', 'bf16-weight-only'),
+ attention_candidates=('cudnn', 'torch-flash', 'sage2', 'fa2', 'fa4'),
+ pinned_host_weights=True, streamed_weights=True)
+
+ def __init__(self, *, torch_module=None):
+ self._torch = torch_module
+
+ @property
+ def torch(self):
+ if self._torch is None:
+ import torch
+ self._torch = torch
+ return self._torch
+
+ def is_available(self):
+ return self.torch.cuda.is_available()
+
+ def synchronize(self):
+ return self.torch.cuda.synchronize()
+
+ def empty_cache(self):
+ return self.torch.cuda.empty_cache()
+
+ def memory_info(self):
+ return self.torch.cuda.mem_get_info()
+
+ def max_memory_allocated(self):
+ return self.torch.cuda.max_memory_allocated()
+
+ def max_memory_reserved(self):
+ return self.torch.cuda.max_memory_reserved()
+
+ def reset_peak_memory_stats(self):
+ return self.torch.cuda.reset_peak_memory_stats()
+
+ def host_memory_stats(self):
+ return self.torch.cuda.memory.host_memory_stats()
+
+ def configure_budget(self, budget_bytes, allocator_limit_bytes=None, *,
+ reserve_bytes=0, capacity_trial=False):
+ from ..gpu_budget import configure
+ return configure(self.torch, budget_bytes, allocator_limit_bytes,
+ reserve_bytes=reserve_bytes, capacity_trial=capacity_trial)
+
+ def arithmetic_identity(self):
+ import hashlib
+ from pathlib import Path
+ torch = self.torch
+ return dict(cuda=torch.version.cuda, gpu=torch.cuda.get_device_name(),
+ device_backend='cuda',
+ backend_source_sha256={name: hashlib.sha256(Path(__file__).with_name(name).read_bytes()).hexdigest()
+ for name in ('__init__.py', 'base.py', 'cuda.py', 'cuda_attention.py')},
+ tf32=torch.backends.cuda.matmul.allow_tf32,
+ bf16_reduced_reduction=torch.backends.cuda.matmul.allow_bf16_reduced_precision_reduction,
+ deterministic=torch.are_deterministic_algorithms_enabled())
+
+ def attention_kernels(self, global_backend, window_backend, *,
+ query_chunk=0, window_varlen=False):
+ from .cuda_attention import CUDAAttentionKernels
+ return CUDAAttentionKernels(global_backend, window_backend,
+ query_chunk=query_chunk, window_varlen=window_varlen)
+
+ def prepare_linears(self, model, manifest, linear_compute, fp8_gemm):
+ if linear_compute not in self.capabilities.linear_policies:
+ raise ValueError('Unknown linear compute policy')
+ precision = manifest.get('precision', 'bf16')
+ actual_fp8_gemm = None
+ if precision == 'fp8':
+ from src.models.ops.fp8_linear import per_tensor_gemm
+ from ..fp8 import install_cached_linears
+ expected = 'per_tensor' if per_tensor_gemm() else 'rowwise'
+ if linear_compute == 'native-fp8' and self.torch.cuda.get_device_capability() < (8, 9):
+ raise ValueError('Native FP8 GEMM requires Ada or newer; choose bf16-weight-only on Ampere')
+ if linear_compute == 'native-fp8' and manifest['scale_granularity'] != expected:
+ raise ValueError('FP8 cache scale granularity does not match this GPU; prepare a separate cache')
+ install_cached_linears(model, manifest['linears'], weight_only=linear_compute == 'bf16-weight-only')
+ if linear_compute == 'native-fp8':
+ from ..fp8_gemm import install
+ actual_fp8_gemm = install(model, manifest['scale_granularity'], requested=fp8_gemm)
+ elif precision != 'bf16':
+ raise ValueError('Unknown prepared weight precision')
+ return actual_fp8_gemm
+
+ def install_chunked_ff(self, module, chunk, *, recompute=False):
+ from ..fp8_ops import install_chunked_ff
+ return install_chunked_ff(module, chunk, recompute=recompute)
+
+ def make_offloader(self, layers, **options):
+ from ..offload import LayerOffloader
+ return LayerOffloader(layers, device=self.device, **options)
+
+ def pin_layer_weights(self, layers, **options):
+ from ..offload import pin_layer_weights
+ return pin_layer_weights(layers, **options)
+
+ def prepare_streamed_layer(self, layer, source, index, **options):
+ from ..offload import prepare_streamed_layer
+ return prepare_streamed_layer(layer, source, index, **options)
+
+ def unload_streamed_layer(self, layer, source, index):
+ from ..offload import unload_streamed_layer
+ return unload_streamed_layer(layer, source, index)
diff --git a/freevideo_engine/backends/cuda_attention.py b/freevideo_engine/backends/cuda_attention.py
new file mode 100644
index 0000000..5978359
--- /dev/null
+++ b/freevideo_engine/backends/cuda_attention.py
@@ -0,0 +1,72 @@
+"""Selected CUDA attention operators; failures propagate without substitution."""
+import importlib.metadata
+
+
+class CUDAAttentionKernels:
+ def __init__(self, global_backend, window_backend, *, query_chunk=0, window_varlen=False):
+ choices = ('cudnn', 'torch-flash', 'sage2', 'fa2', 'fa4')
+ if global_backend not in choices or window_backend not in choices:
+ raise ValueError('Unknown CUDA attention backend')
+ if 'fa4' in (global_backend, window_backend):
+ from ..fa4_guard import check_selected
+ check_selected()
+ if window_backend in ('fa2', 'fa4') and query_chunk:
+ raise ValueError('Packed varlen windows do not support a query-chunk override')
+ if window_varlen and window_backend not in ('sage2', 'fa2', 'fa4'):
+ raise ValueError('Packed varlen windows require a sage2, fa2 or fa4 window backend')
+ if 'sage2' in (global_backend, window_backend):
+ if not importlib.metadata.version('sageattention').startswith('2.'):
+ raise ImportError('The sage2 route requires SageAttention 2.x; the tested version is 2.2.0.')
+ from ..triton_compat import activate
+ activate()
+ from sageattention import sageattn
+ self.attention = sageattn
+ if window_varlen and window_backend == 'sage2':
+ from sageattention import sageattn_varlen
+ self.attention_varlen = sageattn_varlen
+ if 'fa2' in (global_backend, window_backend):
+ if not importlib.metadata.version('flash-attn').startswith('2.'):
+ raise ImportError('The fa2 route requires flash-attn 2.x.')
+ from flash_attn.flash_attn_interface import flash_attn_varlen_func
+
+ def batched(self, leg, q, k, v, scale):
+ if leg == 'sage2':
+ return self.attention(q, k, v, tensor_layout='NHD', is_causal=False, sm_scale=scale)
+ if leg == 'fa2':
+ from flash_attn.flash_attn_interface import flash_attn_func
+ return flash_attn_func(q, k, v, softmax_scale=scale, causal=False)
+ if leg == 'fa4':
+ from flash_attn.cute import flash_attn_func
+ result = flash_attn_func(q, k, v, softmax_scale=scale, causal=False)
+ return result[0] if isinstance(result, tuple) else result
+ if leg not in ('cudnn', 'torch-flash'):
+ raise ValueError('Unknown CUDA attention backend: ' + str(leg))
+ import torch.nn.functional as F
+ from torch.nn.attention import SDPBackend, sdpa_kernel
+ backend = SDPBackend.CUDNN_ATTENTION if leg == 'cudnn' else SDPBackend.FLASH_ATTENTION
+ with sdpa_kernel(backend):
+ result = F.scaled_dot_product_attention(q.transpose(1, 2), k.transpose(1, 2),
+ v.transpose(1, 2), scale=scale)
+ return result.transpose(1, 2)
+
+ def varlen(self, leg, q, k, v, plan, scale, *, smooth_k=True):
+ if leg == 'sage2':
+ return self.attention_varlen(q, k, v,
+ cu_seqlens_q=plan.cu_q, cu_seqlens_k=plan.cu_k,
+ max_seqlen_q=plan.max_q, max_seqlen_k=plan.max_k,
+ sm_scale=scale, is_causal=False, smooth_k=smooth_k)
+ if leg == 'fa2':
+ from flash_attn.flash_attn_interface import flash_attn_varlen_func
+ elif leg == 'fa4':
+ from flash_attn.cute import flash_attn_varlen_func
+ else:
+ raise ValueError('Packed varlen requires sage2, fa2 or fa4')
+ result = flash_attn_varlen_func(q, k, v,
+ cu_seqlens_q=plan.cu_q, cu_seqlens_k=plan.cu_k,
+ max_seqlen_q=plan.max_q, max_seqlen_k=plan.max_k,
+ softmax_scale=scale, causal=False)
+ return result[0] if isinstance(result, tuple) else result
+
+ def decomposed(self, q, k, v, layout, bounds, scale, anchor_frames):
+ from src.models.softmax_attention.decomposed import window_softmax_decomposed
+ return window_softmax_decomposed(q, k, v, layout, bounds, scale, anchor_frames)
diff --git a/freevideo_engine/backends/mps.py b/freevideo_engine/backends/mps.py
new file mode 100644
index 0000000..d315f26
--- /dev/null
+++ b/freevideo_engine/backends/mps.py
@@ -0,0 +1,185 @@
+"""Apple MPS services with one shared physical-memory budget.
+
+Model loading/streaming are integrated separately. Unsupported services fail
+explicitly; model operations never route to CUDA or implicit CPU fallback.
+"""
+import math
+import os
+
+from .base import BackendCapabilities, DeviceBackend
+
+
+def allocator_ceiling(budget, recommended, total, available, owned, reserve, explicit=None):
+ values = (budget, recommended, total, available, owned, reserve)
+ if any(type(x) not in (int, float) or not math.isfinite(x) or x < 0 for x in values):
+ raise ValueError('MPS admission requires finite nonnegative byte counts')
+ if not budget or not recommended or not total:
+ raise ValueError('MPS admission requires positive budget and capacity')
+ if explicit is not None and (type(explicit) is not int or not 0 < explicit <= total):
+ raise ValueError('MPS allocator limit must be positive and within unified physical RAM')
+ bounds = dict(planning_budget_bytes=int(budget), recommended_working_set_bytes=int(recommended),
+ physical_capacity_after_reserve_bytes=max(0, int(total - reserve)),
+ live_pool_capacity_bytes=max(0, int(min(total, available) + owned - reserve)))
+ if explicit is not None:
+ bounds['explicit_allocator_limit_bytes'] = explicit
+ return dict(allocator_limit_bytes=min(bounds.values()), bounds=bounds,
+ owned_driver_bytes=int(owned), growth_reserve_bytes=int(reserve))
+
+
+class MPSBackend(DeviceBackend):
+ device = 'mps'
+ capabilities = BackendCapabilities(name='mps', memory_model='unified',
+ linear_policies=('bf16', 'bf16-weight-only'), attention_candidates=('mps',),
+ pinned_host_weights=False, streamed_weights=True)
+
+ def __init__(self, *, torch_module=None):
+ if os.environ.get('PYTORCH_ENABLE_MPS_FALLBACK', '0') not in ('', '0'):
+ raise ValueError('MPS CPU fallback must be disabled; unsupported operators must fail explicitly')
+ self._torch = torch_module
+ self._limit = None
+ self._reserve = 0
+
+ @property
+ def torch(self):
+ if self._torch is None:
+ import torch
+ self._torch = torch
+ return self._torch
+
+ def is_available(self):
+ return self.torch.backends.mps.is_available()
+
+ def synchronize(self):
+ return self.torch.mps.synchronize()
+
+ def empty_cache(self):
+ return self.torch.mps.empty_cache()
+
+ def memory_stats(self):
+ from ..macos_memory import memory_status
+ return dict(memory_model='unified', host=memory_status(),
+ current_allocated_bytes=self.torch.mps.current_allocated_memory(),
+ driver_allocated_bytes=self.torch.mps.driver_allocated_memory(),
+ recommended_working_set_bytes=self.torch.mps.recommended_max_memory(),
+ allocator_limit_bytes=self._limit, peak_allocated_bytes=None,
+ peak_driver_bytes=None, peak_measurement='not exposed by the MPS API')
+
+ def memory_info(self):
+ row = self.memory_stats()
+ domain = min(row['host']['total_bytes'], row['recommended_working_set_bytes'])
+ if self._limit is not None:
+ domain = min(domain, self._limit)
+ free = max(0, min(domain - row['driver_allocated_bytes'],
+ row['host']['available_bytes'] - self._reserve))
+ return free, domain
+
+ def max_memory_allocated(self):
+ return None # Current usage is not a peak.
+
+ def max_memory_reserved(self):
+ return None
+
+ def reset_peak_memory_stats(self):
+ return None
+
+ def host_memory_stats(self):
+ return {'supported': False, 'memory_model': 'unified', 'allocated_bytes.current': None}
+
+ def configure_budget(self, budget_bytes, allocator_limit_bytes=None, *,
+ reserve_bytes=0, capacity_trial=False):
+ row = self.memory_stats()
+ decision = allocator_ceiling(budget_bytes, row['recommended_working_set_bytes'],
+ row['host']['total_bytes'], row['host']['available_bytes'], row['driver_allocated_bytes'],
+ reserve_bytes, allocator_limit_bytes)
+ limit = decision['allocator_limit_bytes']
+ if limit <= 0:
+ raise MemoryError('No unified-memory allowance remains for MPS after the system reserve')
+ # Never pass zero: MPS interprets fraction=0 as UNLIMITED allocation.
+ self.torch.mps.set_per_process_memory_fraction(float(limit / row['recommended_working_set_bytes']))
+ self._limit, self._reserve = limit, reserve_bytes
+ return dict(enforced=True, memory_model='unified', admission=decision,
+ effective_allocator_limit_bytes=limit, capacity_trial_limit_enforced=bool(capacity_trial),
+ scope='MPS allocator only; CPU allocations and other applications share physical RAM and need a host guard.')
+
+ def arithmetic_identity(self):
+ import hashlib
+ from importlib.metadata import PackageNotFoundError, version
+ import os
+ from pathlib import Path
+ import platform
+ from ..macos_memory import chip_name
+ packages = {}
+ for name in ('mlx', 'mlx-metal'):
+ try:
+ packages[name] = version(name)
+ except PackageNotFoundError:
+ packages[name] = None
+ return dict(device_backend='mps', gpu=chip_name(), macos=platform.mac_ver()[0],
+ torch=str(self.torch.__version__),
+ packages=packages,
+ mps_fast_math=os.environ.get('PYTORCH_MPS_FAST_MATH', '0'),
+ mps_prefer_metal=os.environ.get('PYTORCH_MPS_PREFER_METAL', '0'),
+ mps_cpu_fallback=os.environ.get('PYTORCH_ENABLE_MPS_FALLBACK', '0'),
+ deterministic=self.torch.are_deterministic_algorithms_enabled(),
+ backend_source_sha256={name: hashlib.sha256(Path(__file__).with_name(name).read_bytes()).hexdigest()
+ for name in ('__init__.py', 'base.py', 'mps.py', 'mps_attention.py', 'mps_weights.py',
+ 'mps_fp8.py', 'mps_nvfp4.py', 'mps_linear.py', 'mps_delta.py',
+ 'mps_features.py', 'mps_qk.py', 'mps_mlx_attention.py', 'mps_vae.py',
+ 'mps_blocks.py', 'mps_grouped_qkv.py', 'mps_vae_encode.py', 'mps_modulation.py',
+ 'mps_int8.py')},
+ runtime_source_sha256={name: hashlib.sha256((Path(__file__).parent.parent / name).read_bytes()).hexdigest()
+ for name in ('macos_runtime.py', 'macos_vdn.py', 'macos_decode.py', 'macos_encoder.py',
+ 'macos_compute.py', 'macos_stages.py', 'macos_decode_tiles.py',
+ 'latent_upscale.py')})
+
+ def attention_kernels(self, global_backend, window_backend, *, query_chunk=0, window_varlen=False):
+ from .mps_attention import MPSAttentionKernels
+ return MPSAttentionKernels(global_backend, window_backend,
+ query_chunk=query_chunk, window_varlen=window_varlen)
+
+ def prepare_linears(self, model, manifest, linear_compute, fp8_gemm):
+ if fp8_gemm != 'auto':
+ raise ValueError('MPS BF16 execution does not select a CUDA FP8 GEMM')
+ precision = manifest.get('precision')
+ if precision == 'fp8' and linear_compute == 'bf16-weight-only':
+ if manifest.get('scale_granularity') not in ('rowwise', 'per_tensor'):
+ raise ValueError('Unknown FP8 storage scale granularity')
+ return None # The MPS weight reader decodes each matrix before binding.
+ if precision == 'int8' and linear_compute in ('int8', 'bf16-weight-only'):
+ if manifest.get('scale_granularity') != 'rowwise':
+ raise ValueError('Int8 storage requires per-row scales')
+ # Int8 products keep eligible weights int8; every other matrix, and
+ # every matrix on GPUs without int8 TensorOps, is dequantized when read.
+ return None
+ if linear_compute != 'bf16' or precision != 'bf16':
+ raise ValueError('MPS requires BF16 execution or explicit BF16 weight-only decoding')
+ return None
+
+ def install_chunked_ff(self, module, chunk, *, recompute=False):
+ if type(chunk) is not int or chunk < 1 or recompute:
+ raise ValueError('MPS reference feed-forward requires a positive chunk without FP8 recompute')
+ import types
+ torch = self.torch
+ original = module.forward
+ def forward(owner, hidden, *args, **kwargs):
+ if torch.is_grad_enabled():
+ raise RuntimeError('Chunked MPS feed-forward requires inference')
+ output = torch.empty_like(hidden)
+ for start in range(0, hidden.shape[-2], chunk):
+ output[..., start:start + chunk, :] = original(hidden[..., start:start + chunk, :], *args, **kwargs)
+ return output
+ module.forward = types.MethodType(forward, module)
+ module._freevideo_mps_ff_chunk = chunk
+
+ def make_offloader(self, layers, **options):
+ from .mps_weights import LayerResidency
+ return LayerResidency(layers, backend=self, **options)
+
+ def pin_layer_weights(self, *args, **kwargs):
+ raise NotImplementedError('CUDA pinned host weights do not apply to MPS unified memory')
+
+ def prepare_streamed_layer(self, *args, **kwargs):
+ raise NotImplementedError('MPS model streaming is not integrated yet')
+
+ def unload_streamed_layer(self, *args, **kwargs):
+ raise NotImplementedError('MPS model streaming is not integrated yet')
diff --git a/freevideo_engine/backends/mps_attention.py b/freevideo_engine/backends/mps_attention.py
new file mode 100644
index 0000000..e7020a2
--- /dev/null
+++ b/freevideo_engine/backends/mps_attention.py
@@ -0,0 +1,143 @@
+"""Native MPS attention with the same NHD contract as the CUDA adapter."""
+
+
+class MPSAttentionKernels:
+ def __init__(self, global_backend, window_backend, *, query_chunk=0, window_varlen=False):
+ if (global_backend, window_backend) != ('mps', 'mps'):
+ raise ValueError('The MPS device requires explicit mps attention for both legs')
+ if window_varlen:
+ raise ValueError('MPS packed varlen attention is not implemented; use bounded window batches')
+ if type(query_chunk) is not int or query_chunk < 0:
+ raise ValueError('Query chunk must be nonnegative')
+
+ def batched(self, leg, q, k, v, scale):
+ if leg != 'mps':
+ raise ValueError('Unknown MPS attention operator: ' + str(leg))
+ if any(t.device.type != 'mps' for t in (q, k, v)):
+ raise ValueError('MPS attention requires native MPS Q/K/V tensors')
+ import torch.nn.functional as F
+ result = F.scaled_dot_product_attention(q.transpose(1, 2), k.transpose(1, 2),
+ v.transpose(1, 2), dropout_p=0., is_causal=False, scale=scale)
+ return result.transpose(1, 2)
+
+ def varlen(self, *args, **kwargs):
+ raise NotImplementedError('MPS packed varlen attention is not implemented')
+
+ def decomposed(self, *args, **kwargs):
+ raise NotImplementedError('CUDA FA4 decomposition is not an MPS kernel')
+
+
+def prepare_qk(value, norm, rotary_emb, chunk):
+ """Preserve the full per-head reduction and each token's rotary position."""
+ import torch
+ from diffusers.models.transformers.transformer_minimax_h3 import _apply_rotary_emb
+ output = torch.empty_like(value)
+ for start in range(0, value.shape[0], chunk):
+ end = min(start + chunk, value.shape[0])
+ part = norm(value[start:end])
+ if rotary_emb is not None:
+ part = _apply_rotary_emb(part.unsqueeze(0),
+ *(position[start:end] for position in rotary_emb)).squeeze(0)
+ output[start:end] = part
+ return output
+
+
+def project_rows(value, projection, *, chunk, dtype, reuse=False):
+ """Project independent token rows, optionally consuming an owned buffer.
+
+ Reuse is only valid for a dead, unaliased intermediate with sufficient row
+ width and matching dtype. The complete channel reduction remains in each GEMM.
+ """
+ import torch
+ if torch.is_grad_enabled():
+ raise RuntimeError('MPS row projection requires inference without autograd')
+ if type(chunk) is not int or chunk < 1:
+ raise ValueError('Projection chunk must be a positive integer')
+ if reuse and value.shape[-1] >= projection.out_features and value.dtype == dtype:
+ output = value[:, :projection.out_features]
+ else:
+ output = torch.empty((value.shape[0], projection.out_features), dtype=dtype, device=value.device)
+ for start in range(0, value.shape[0], chunk):
+ end = min(start + chunk, value.shape[0])
+ output[start:end] = projection(value[start:end].to(dtype))
+ return output
+
+
+def install_hybrid(model, attention, *, head_chunk=4, row_chunk=256, qk_prepare=None):
+ """Native eager hybrid attention with bounded independent-head preparation.
+
+ Keep full QKV projections and upstream linear attention. QK normalization,
+ RoPE and softmax run on independent head groups; all sequence/mask reductions
+ remain intact. This adapter is installed only by the native engine.
+ """
+ import types
+ import torch
+ from src.models.hybrid_attention import HybridAttention
+ qk_prepare = prepare_qk if qk_prepare is None else qk_prepare
+ for name, value in (('head_chunk', head_chunk), ('row_chunk', row_chunk)):
+ if type(value) is not int or value < 1:
+ raise ValueError(name + ' must be a positive integer')
+
+ def forward(owner, x, rotary_emb):
+ if torch.is_grad_enabled() or owner.inference_mode or owner.hybrid_inference_mode:
+ raise RuntimeError('MPS hybrid attention requires the eager, no-grad branch')
+ orig, layout = owner.orig, owner.layout
+ bounds = owner._bounds(layout) if layout is not None else None
+ full = layout is None or all(lo <= 0 and hi >= layout.num_frames - 1 for lo, hi in bounds)
+ raw = tuple(p(x).unflatten(-1, (orig.heads, -1))
+ for p in (orig.to_q, orig.to_k, orig.to_v))
+ softmax = torch.empty_like(raw[0])
+ for start in range(0, orig.heads, head_chunk):
+ group = slice(start, min(start + head_chunk, orig.heads))
+ query = qk_prepare(raw[0][:, group], orig.norm_q, rotary_emb, row_chunk)
+ key = qk_prepare(raw[1][:, group], orig.norm_k, rotary_emb, row_chunk)
+ if full:
+ # Match the original processor's full-cover dispatcher. Only
+ # independent heads are grouped; no alternative kernel fallback.
+ from diffusers.models.attention_dispatch import dispatch_attention_fn
+ part = dispatch_attention_fn(query.unsqueeze(0), key.unsqueeze(0),
+ raw[2][:, group].unsqueeze(0), attn_mask=None, dropout_p=0., is_causal=False,
+ backend=getattr(type(orig.processor), '_attention_backend', None)).squeeze(0)
+ else:
+ part = attention(query, key, raw[2][:, group], layout, bounds,
+ owner.head_dim ** -.5, owner.anchor_frames)
+ softmax[:, group] = part
+ del query, key, part
+ if owner.enable_softmax_gate:
+ gate = owner.softmax_gate(x).to(softmax.dtype)
+ softmax.mul_(gate)
+ del gate
+ # This softmax buffer has no remaining readers. A narrowing projection can
+ # consume it one row chunk at a time instead of allocating another full
+ # packed-sequence activation while QKV are still needed by the linear leg.
+ out = orig.to_out[1](project_rows(softmax.reshape(x.shape[0], -1), orig.to_out[0],
+ chunk=row_chunk, dtype=x.dtype, reuse=True))
+ del softmax
+ if not full and owner.linear_attention_enabled:
+ start, end = layout.video_start, layout.video_end
+ video_qkv = tuple(t[start:end] for t in raw)
+ text_x = text_qkv = None
+ if owner.enable_text_state:
+ a, b = layout.text_range
+ text_x, text_qkv = x[a:b], tuple(t[a:b] for t in raw)
+ from .mps_linear import consume_qkv
+ readout = consume_qkv(owner.linear_attention, x[start:end], layout.num_frames, layout.tokens_per_frame,
+ bounds, qkv_raw=video_qkv,
+ frame_size=layout.frame_size if owner.linear_attention.short_conv is not None else None,
+ skip_ends=owner.anchor_frames == 'both', text_x=text_x, text_qkv_raw=text_qkv,
+ head_chunk=head_chunk, gate_chunk=row_chunk)
+ # The readout now owns Q storage. Drop the remaining views so K/V
+ # can be released before the output projection.
+ del raw, video_qkv, text_qkv
+ for begin in range(0, end - start, row_chunk):
+ stop = min(begin + row_chunk, end - start)
+ out[start + begin:start + stop] += owner.to_out_linear(readout[begin:stop].type_as(x))
+ return out
+
+ count = 0
+ for module in model.modules():
+ if isinstance(module, HybridAttention):
+ module._hybrid_forward = types.MethodType(forward, module)
+ count += 1
+ return dict(implementation='mps-eager-hybrid-heads-v3', branches=count,
+ head_chunk=head_chunk, row_chunk=row_chunk)
diff --git a/freevideo_engine/backends/mps_blocks.py b/freevideo_engine/backends/mps_blocks.py
new file mode 100644
index 0000000..3b51580
--- /dev/null
+++ b/freevideo_engine/backends/mps_blocks.py
@@ -0,0 +1,160 @@
+"""Bounded MPS inference buffers, preserving full normalization reductions.
+
+The consumed FF input is overwritten only after each original row partition has
+completed. Normalization is evaluated over the original full input. Only independent row
+selection, multiplication and addition are chunked into owned output buffers.
+"""
+import types
+
+
+def post_into_branch(residual, gate, indices, branch, chunk, *, stats=None):
+ import torch
+ if torch.is_grad_enabled():
+ raise RuntimeError('Owned branch reuse requires inference without autograd')
+ if type(chunk) is not int or chunk < 1:
+ raise ValueError('Positive integer row chunk required')
+ if residual.shape != branch.shape or residual.ndim != 3:
+ raise ValueError('Expected matching batch, row, channel residual and branch')
+ if gate.ndim != 2 or indices.ndim != 1 or indices.numel() != branch.shape[-2]:
+ raise ValueError('Invalid packed modulation rows')
+ if gate.shape[-1] != branch.shape[-1]:
+ raise ValueError('Gate width differs')
+ if not residual.dtype == branch.dtype == gate.dtype:
+ raise ValueError('Buffer reuse requires the original common output dtype')
+ if any(value.device != branch.device for value in (residual, gate, indices)):
+ raise ValueError('Branch and modulation must share a device')
+ if any(value.untyped_storage().data_ptr() == branch.untyped_storage().data_ptr()
+ for value in (residual, gate, indices)):
+ raise ValueError('The consumed branch must not alias live residual or modulation')
+ for begin in range(0, branch.shape[-2], chunk):
+ end = min(begin + chunk, branch.shape[-2])
+ rows = slice(begin, end)
+ # Preserve eager multiply and add as separate operations/dtype roundings.
+ selected = gate.index_select(0, indices[rows])
+ branch[..., rows, :].copy_(residual[..., rows, :] + selected * branch[..., rows, :])
+ if stats is not None:
+ stats['post_chunks'] = stats.get('post_chunks', 0) + 1
+ stats['largest_selected_gate_elements'] = max(
+ stats.get('largest_selected_gate_elements', 0), selected.numel())
+ return branch
+
+
+def modulate_owned(normalized, scale, shift, indices, chunk, *, live=(), stats=None):
+ import torch
+ if torch.is_grad_enabled():
+ raise RuntimeError('Owned modulation requires inference without autograd')
+ if type(chunk) is not int or chunk < 1:
+ raise ValueError('Positive integer row chunk required')
+ if normalized.ndim != 3 or not normalized.is_contiguous():
+ raise ValueError('Require an owned contiguous batch/row/channel normalization output')
+ if scale.ndim != 2 or scale.shape != shift.shape or scale.shape[-1] != normalized.shape[-1]:
+ raise ValueError('Invalid scale/shift geometry')
+ if indices.ndim != 1 or indices.numel() != normalized.shape[-2]:
+ raise ValueError('Invalid packed modulation rows')
+ if not normalized.dtype == scale.dtype == shift.dtype:
+ raise ValueError('Owned modulation requires the original common output dtype')
+ if any(value.device != normalized.device for value in (scale, shift, indices)):
+ raise ValueError('Modulation inputs must share a device')
+ if any(value.untyped_storage().data_ptr() == normalized.untyped_storage().data_ptr()
+ for value in (scale, shift, indices, *live)):
+ raise ValueError('Owned normalized output must not alias live inputs')
+ for begin in range(0, normalized.shape[-2], chunk):
+ end = min(begin + chunk, normalized.shape[-2])
+ rows = slice(begin, end)
+ selected_scale = scale.index_select(0, indices[rows])
+ selected_shift = shift.index_select(0, indices[rows])
+ # Do not fuse multiply/add or change their separate dtype rounding.
+ normalized[..., rows, :].copy_(
+ normalized[..., rows, :] * (1.0 + selected_scale) + selected_shift)
+ if stats is not None:
+ stats['modulation_chunks'] = stats.get('modulation_chunks', 0) + 1
+ stats['largest_selected_modulation_elements'] = max(
+ stats.get('largest_selected_modulation_elements', 0), selected_scale.numel())
+ return normalized
+
+
+def feed_forward_owned(value, forward, chunk, *, live=(), stats=None):
+ import torch
+ if torch.is_grad_enabled():
+ raise RuntimeError('Owned feed-forward requires inference without autograd')
+ if type(chunk) is not int or chunk < 1:
+ raise ValueError('Positive integer row chunk required')
+ if value.ndim != 3 or not value.is_contiguous():
+ raise ValueError('Require owned contiguous batch/row/channel input')
+ if any(other.untyped_storage().data_ptr() == value.untyped_storage().data_ptr() for other in live):
+ raise ValueError('Consumed feed-forward input must not alias live inputs')
+ for begin in range(0, value.shape[-2], chunk):
+ rows = slice(begin, min(begin + chunk, value.shape[-2]))
+ part = value[..., rows, :]
+ output = forward(part)
+ if output.shape != part.shape or output.dtype != part.dtype or output.device != part.device:
+ raise ValueError('Feed-forward changed the buffer geometry, dtype or device')
+ part.copy_(output)
+ if stats is not None:
+ stats['ff_chunks'] = stats.get('ff_chunks', 0) + 1
+ stats['largest_ff_input_elements'] = max(stats.get('largest_ff_input_elements', 0), part.numel())
+ del part, output
+ return value
+
+
+def validate(model, *, row_chunk=256, ff_chunk=256):
+ """Validate the complete block/partition contract without changing methods."""
+ from diffusers.models.transformers.transformer_minimax_h3 import MiniMaxH3TransformerBlock
+ if type(row_chunk) is not int or row_chunk < 1:
+ raise ValueError('Positive integer row chunk required')
+ if type(ff_chunk) is not int or ff_chunk < 1:
+ raise ValueError('Positive integer feed-forward chunk required')
+ blocks = tuple(model.transformer_blocks)
+ if not blocks:
+ raise ValueError('Expected at least one MiniMax H3 transformer block')
+ for block in blocks:
+ if not isinstance(block, MiniMaxH3TransformerBlock):
+ raise TypeError('Expected the pinned MiniMax H3 transformer block')
+ if getattr(block.ff, '_freevideo_mps_ff_chunk', None) != ff_chunk:
+ raise ValueError('Owned feed-forward must preserve the installed row chunk')
+ if block.training:
+ raise ValueError('Owned block buffers require evaluation mode')
+ return blocks
+
+
+def install(model, *, row_chunk=256, ff_chunk=256):
+ """Bind owned intermediates only after validating every block.
+
+ The engine must install the ordinary MPS feed-forward partition first. Its
+ chunk size is the arithmetic contract: changing a GEMM batch can change
+ rounding. Reuse that partition, including its final partial chunk.
+
+ This adapter is not enabled by the engine's default policy yet.
+ """
+ import torch
+ blocks = validate(model, row_chunk=row_chunk, ff_chunk=ff_chunk)
+ stats = dict(implementation='mps-owned-block-buffers-v1', blocks=0,
+ row_chunk=row_chunk, block_calls=0, post_chunks=0,
+ largest_selected_gate_elements=0, modulation_chunks=0,
+ largest_selected_modulation_elements=0, ff_chunk=ff_chunk, ff_chunks=0, largest_ff_input_elements=0)
+
+ def forward(owner, hidden_states, temb, adaln_indices, rotary_emb, attention_mask=None):
+ if torch.is_grad_enabled() or owner.training:
+ raise RuntimeError('Owned branch reuse requires evaluation without autograd')
+ shift_a, scale_a, gate_a, shift_f, scale_f, gate_f = owner.adaln_proj(temb)
+ # Keep normalization reductions unchanged; chunk only independent modulation rows.
+ normalized = owner.norm1(hidden_states)
+ modulate_owned(normalized, scale_a, shift_a, adaln_indices, row_chunk,
+ live=(hidden_states,), stats=stats)
+ branch = owner.attn(normalized, rotary_emb, attention_mask)
+ del normalized
+ hidden = post_into_branch(hidden_states, gate_a, adaln_indices, branch, row_chunk, stats=stats)
+ del branch
+ normalized = owner.norm2(hidden)
+ modulate_owned(normalized, scale_f, shift_f, adaln_indices, row_chunk,
+ live=(hidden,), stats=stats)
+ branch = feed_forward_owned(normalized, owner.ff, ff_chunk, live=(hidden,), stats=stats)
+ del normalized
+ output = post_into_branch(hidden, gate_f, adaln_indices, branch, row_chunk, stats=stats)
+ stats['block_calls'] += 1
+ return output
+
+ for block in blocks:
+ block.forward = types.MethodType(forward, block)
+ stats['blocks'] += 1
+ return stats
diff --git a/freevideo_engine/backends/mps_delta.py b/freevideo_engine/backends/mps_delta.py
new file mode 100644
index 0000000..4794faa
--- /dev/null
+++ b/freevideo_engine/backends/mps_delta.py
@@ -0,0 +1,153 @@
+"""VDN delta-rule factors with GPU matrix products instead of batched Cholesky.
+
+The released checkpoints use (I + A)^-1 for every frame and head. MPS runs the
+batched Cholesky and triangular solve far below its matrix-product rate: on an
+M5 those two calls cost 0.39 s of a 1.1 s linear branch. I + A is symmetric
+positive definite with eigenvalues in [1, 1 + trace(A)], so a Newton-Schulz
+iteration started at 2 / (2 + trace(A)) * I converges to the same inverse using
+only batched FP32 products. The iteration count covers the worst condition
+number the trace allows, and the residual is checked rather than assumed.
+"""
+import math
+
+
+def iterations_for(trace_bound):
+ """Quadratic steps that shrink the initial error below FP32 resolution."""
+ condition = 1. + max(0., float(trace_bound))
+ error = (condition - 1.) / (condition + 1.)
+ if error <= 0.:
+ return 1
+ # error ** (2 ** k) <= 2 ** -26 -> 2 ** k >= 26 ln 2 / -ln(error)
+ return max(1, math.ceil(math.log2(26. * math.log(2.) / -math.log(error))) + 1)
+
+
+def iterations_to(trace_bound, error):
+ """Quadratic steps that shrink the initial error below `error`."""
+ condition = 1. + max(0., float(trace_bound))
+ start = (condition - 1.) / (condition + 1.)
+ if start <= error:
+ return 0
+ return max(1, math.ceil(math.log2(math.log(error) / math.log(start))))
+
+
+BATCH_CHUNK = 1024
+
+
+def inverse_spd(A32, *, max_residual=1e-3, low_precision=True, chunk=BATCH_CHUNK):
+ """Chunked over the batch: the FP32/FP16 iterates of all F x H matrices at
+ once cost about 1.5 GiB on a full first pass and ran an M5 out of memory.
+
+ The host reads two scalars per call, the spectral bound and the residual, not
+ two per chunk: each read waits for every queued kernel."""
+ import torch
+ flat = A32.reshape(-1, *A32.shape[-2:])
+ trace = torch.diagonal(flat, dim1=-2, dim2=-1).sum(-1).clamp_min(0.)
+ # min(trace, Frobenius norm) bounds the largest eigenvalue of a PSD A; the
+ # tighter bound saved one of nine first-pass iterations.
+ scale = torch.minimum(trace, flat.square().sum((-2, -1)).sqrt()) if low_precision else trace
+ bound = float(scale.max())
+ out, residuals = torch.empty_like(flat), []
+ for begin in range(0, flat.shape[0], chunk):
+ end = begin + chunk
+ out[begin:end], part = _inverse_spd(flat[begin:end], bound, scale=scale[begin:end],
+ low_precision=low_precision)
+ residuals.append(part)
+ residual = float(residuals[0] if len(residuals) == 1 else torch.stack(residuals).amax())
+ if not math.isfinite(residual) or residual > max_residual:
+ raise FloatingPointError(f'VDN inverse did not converge (residual {residual:.3g})')
+ return out.reshape(A32.shape)
+
+
+def _inverse_spd(A32, bound, *, scale=None, low_precision=True):
+ """(I + A)^-1 for a batch of symmetric positive semidefinite FP32 A, and the
+ largest residual entry as a device scalar. `bound` bounds every `scale`,
+ which bounds each matrix's largest eigenvalue (its trace by default).
+
+ MPS runs FP32 batched products at about 1.4 TFLOPS on an M5 and FP16 ones
+ several times faster, so the long contraction phase runs in FP16 until the
+ error is about 1e-3; each FP32 step then squares the error, and two reach
+ FP32 resolution. Entries stay within FP16 range: ||X|| <= 1, ||M|| <= 1 + trace.
+ """
+ import torch
+ size = A32.shape[-1]
+ eye = torch.eye(size, device=A32.device, dtype=torch.float32)
+ M = A32 + eye
+ if scale is None:
+ scale = torch.diagonal(A32, dim1=-2, dim2=-1).sum(-1).clamp_min(0.)
+ two = 2. * eye
+ if low_precision and A32.device.type == 'mps':
+ X = (2. / (2. + scale))[..., None, None] * eye
+ M16, X16, two16 = M.half(), X.half(), two.half()
+ for _ in range(iterations_to(bound, 2e-3)):
+ X16 = X16 @ (two16 - M16 @ X16)
+ X = X16.float()
+ del M16, X16
+ refinements = 3
+ else:
+ X = (2. / (2. + scale))[..., None, None] * eye
+ # One step beyond the bound absorbs FP32 rounding in the products.
+ refinements = iterations_for(bound) + 1
+ for _ in range(refinements):
+ X = X @ (two - M @ X)
+ X = 0.5 * (X + X.transpose(-1, -2))
+ # A NaN anywhere must fail the check: amax propagates it.
+ return X, (M @ X - eye).abs().amax()
+
+
+SMALL_BATCH = 512
+
+
+def factor_apply(backend, alpha, A_raw, B_raw, *, stats=None):
+ """Drop-in for VdnDelta.factor_apply: (transition, injection) in the input dtypes."""
+ from src.models.linear_attention.delta_rule import VdnDelta
+ exact = getattr(backend, '_freevideo_cholesky', None)
+ if exact is None:
+ from functools import partial
+ exact = partial(VdnDelta.factor_apply, backend)
+ if A_raw.shape[:-2].numel() < SMALL_BATCH:
+ # The prompt's single chunk is one matrix per head: a dozen launch-bound
+ # products cost more than the exact factor there.
+ if stats is not None:
+ stats['cholesky_small_batch_calls'] = stats.get('cholesky_small_batch_calls', 0) + 1
+ return exact(alpha, A_raw, B_raw)
+ try:
+ inverse = inverse_spd(A_raw.float())
+ except FloatingPointError:
+ # Keep the request on the exact Cholesky path rather than failing it.
+ if stats is not None:
+ stats['cholesky_residual_calls'] = stats.get('cholesky_residual_calls', 0) + 1
+ return exact(alpha, A_raw, B_raw)
+ if stats is not None:
+ stats['newton_calls'] = stats.get('newton_calls', 0) + 1
+ transition = alpha.unsqueeze(-1) * inverse
+ injection = B_raw.float() @ inverse
+ return transition.to(A_raw.dtype), injection.to(B_raw.dtype)
+
+
+def install(model, *, stats=None):
+ """Wrap only this model's lazy unscaled delta backends, including text state."""
+ import types
+ import torch
+ from src.models.linear_attention.branch import BidirectionalLinearBranch
+ from src.models.linear_attention.delta_rule import VdnDelta
+
+ def apply(backend, alpha, A_raw, B_raw):
+ if A_raw.device.type != 'mps' or torch.is_grad_enabled():
+ if stats is not None:
+ stats['reference_calls'] = stats.get('reference_calls', 0) + 1
+ return backend._freevideo_cholesky(alpha, A_raw, B_raw)
+ return factor_apply(backend, alpha, A_raw, B_raw, stats=stats)
+
+ def delta_backend(branch, attr, length):
+ backend = branch._freevideo_eager_delta_backend(attr, length)
+ # Subclasses may implement a different scaling rule: leave them intact.
+ if type(backend) is VdnDelta and not hasattr(backend, '_freevideo_cholesky'):
+ backend._freevideo_cholesky = backend.factor_apply
+ backend.factor_apply = types.MethodType(apply, backend)
+ return backend
+
+ for branch in model.modules():
+ if isinstance(branch, BidirectionalLinearBranch) and not hasattr(branch, '_freevideo_eager_delta_backend'):
+ branch._freevideo_eager_delta_backend = branch._delta_backend
+ branch._delta_backend = types.MethodType(delta_backend, branch)
+ return 'mps-newton-schulz-v1'
diff --git a/freevideo_engine/backends/mps_features.py b/freevideo_engine/backends/mps_features.py
new file mode 100644
index 0000000..9b22dc8
--- /dev/null
+++ b/freevideo_engine/backends/mps_features.py
@@ -0,0 +1,133 @@
+"""Linear-branch features in one Metal pass: temporal 5-tap conv, SiLU, L2 norm.
+
+Eager MPS walks each projection's [frames, tokens, channels] tensor about ten
+times (pad, five shifted products and sums, SiLU, norm, division); on an M5
+the features cost 0.31 s of a 1.1 s first-pass linear branch. This kernel reads
+each element's temporal taps once and writes the normalized feature once,
+accumulating in FP32 with one rounding at the store, like the upstream
+inference kernel. The spatial 5x5 depthwise conv stays on PyTorch.
+"""
+from functools import lru_cache
+
+SOURCE = r'''
+#include <metal_stdlib>
+using namespace metal;
+
+kernel void conv_silu_norm(device bfloat* out [[buffer(0)]],
+ device const bfloat* x [[buffer(1)]],
+ device const bfloat* weight [[buffer(2)]],
+ constant int* dims [[buffer(3)]],
+ uint group [[threadgroup_position_in_grid]],
+ uint lane [[thread_index_in_threadgroup]],
+ uint simd_lane [[thread_index_in_simdgroup]],
+ uint simd_id [[simdgroup_index_in_threadgroup]]) {
+ threadgroup float partial[32];
+ // dims: frames, tokens, channels, taps (0 = no conv), l2norm, head_dim
+ const int frames = dims[0], tokens = dims[1], channels = dims[2];
+ const int taps = dims[3], l2norm = dims[4], head_dim = dims[5];
+ const int heads = channels / head_dim;
+ const int head = int(group) % heads;
+ const int token = (int(group) / heads) % tokens;
+ const int frame = int(group) / (heads * tokens);
+ const int channel = head * head_dim + int(lane);
+ float value;
+ if (taps > 0) {
+ const int pad = taps / 2;
+ value = 0.f;
+ for (int tap = 0; tap < taps; ++tap) {
+ const int source = frame + tap - pad;
+ if (source >= 0 && source < frames) {
+ value += float(x[(ulong(source) * tokens + token) * channels + channel])
+ * float(weight[channel * taps + tap]);
+ }
+ }
+ } else {
+ value = float(x[(ulong(frame) * tokens + token) * channels + channel]);
+ }
+ float y = value / (1.f + exp(-value));
+ if (l2norm) {
+ float square = simd_sum(y * y);
+ if (simd_lane == 0) partial[simd_id] = square;
+ threadgroup_barrier(mem_flags::mem_threadgroup);
+ float total = 0.f;
+ const int groups = (head_dim + 31) / 32;
+ for (int index = 0; index < groups; ++index) total += partial[index];
+ y = y / max(sqrt(total), 1e-6f);
+ }
+ out[(ulong(frame) * tokens + token) * channels + channel] = bfloat(y);
+}
+'''
+
+
+@lru_cache(maxsize=1)
+def _library():
+ import torch
+ try:
+ return torch.mps.compile_shader(SOURCE)
+ except Exception: # Older Metal compilers lack bfloat; keep eager.
+ return None
+
+
+def available():
+ return _library() is not None
+
+
+def conv_silu_norm(x, weight, *, head_dim, l2norm):
+ """x [frames, tokens, channels] BF16 MPS, weight [channels, taps] or None -> same shape."""
+ import torch
+ if x.device.type != 'mps' or x.dtype != torch.bfloat16 or x.ndim != 3:
+ raise ValueError('Fused features need a [frames, tokens, channels] BF16 MPS tensor')
+ frames, tokens, channels = x.shape
+ if channels % head_dim or head_dim > 1024:
+ raise ValueError('Channels must be whole heads of at most 1024 features')
+ x = x.contiguous()
+ if weight is None:
+ taps, weight = 0, x # No weight access when the convolution is disabled.
+ else:
+ taps = weight.shape[1]
+ weight = weight.to(device=x.device, dtype=torch.bfloat16).contiguous()
+ if weight.shape[0] != channels:
+ raise ValueError('Temporal weight channels differ from the features')
+ out = torch.empty_like(x)
+ dims = [frames, tokens, channels, taps, int(l2norm), head_dim]
+ _library().conv_silu_norm(out, x, weight, dims, threads=frames * tokens * channels,
+ group_size=head_dim, arg_casts={3: 'int32'})
+ return out
+
+
+def feature_one(branch, tokens, proj, num_frames, frame_size, use_conv=True, inference=False,
+ fhsd=None, heads=None, *, stats=None):
+ """BidirectionalLinearBranch._feature_one for MPS BF16 inference."""
+ import torch
+ from src.models.linear_attention.branch import _HeadSliceSepConv
+ conv = branch.short_conv if use_conv else None
+ if conv is not None and heads is not None:
+ conv = _HeadSliceSepConv(conv, heads, branch.head_dim)
+ l2norm = proj != 'v'
+ if (tokens.device.type != 'mps' or tokens.dtype != torch.bfloat16 or fhsd is not None
+ or torch.is_grad_enabled() or not available()):
+ if stats is not None:
+ stats['reference_calls'] = stats.get('reference_calls', 0) + 1
+ return branch._freevideo_eager_feature_one(tokens, proj, num_frames, frame_size,
+ use_conv=use_conv, inference=inference, fhsd=fhsd, heads=heads)
+ if stats is not None:
+ stats['metal_calls'] = stats.get('metal_calls', 0) + 1
+ count, dim = tokens.shape[-2], tokens.shape[-1]
+ if conv is not None and proj in conv.projs:
+ x, weight = conv.spatial(proj, tokens, num_frames, frame_size)
+ out = conv_silu_norm(x, weight, head_dim=dim, l2norm=l2norm)
+ else:
+ out = conv_silu_norm(tokens.reshape(1, -1, count * dim), None, head_dim=dim, l2norm=l2norm)
+ return out.reshape(-1, count, dim)
+
+
+def install(model, *, stats=None):
+ """Bind the fused features to this model only; leave VDN classes unchanged."""
+ from functools import partial
+ import types
+ from src.models.linear_attention.branch import BidirectionalLinearBranch
+ for branch in model.modules():
+ if isinstance(branch, BidirectionalLinearBranch) and not hasattr(branch, '_freevideo_eager_feature_one'):
+ branch._freevideo_eager_feature_one = branch._feature_one
+ branch._feature_one = types.MethodType(partial(feature_one, stats=stats), branch)
+ return 'mps-fused-conv-silu-norm-v1'
diff --git a/freevideo_engine/backends/mps_fp8.py b/freevideo_engine/backends/mps_fp8.py
new file mode 100644
index 0000000..3b8b955
--- /dev/null
+++ b/freevideo_engine/backends/mps_fp8.py
@@ -0,0 +1,45 @@
+"""Decode E4M3 storage directly into BF16 MPS buffers with explicit rounding.
+
+Only weight storage is FP8. Model projections still execute in BF16. The CPU
+decoder remains the numerical reference and neither path enters CUDA imports.
+"""
+from functools import lru_cache
+
+
+@lru_cache(maxsize=1)
+def _kernel():
+ import torch
+ library = torch.mps.compile_shader('''
+ #include <metal_stdlib>
+ using namespace metal;
+ kernel void decode_e4m3(device ushort* output,
+ device const uchar* packed,
+ device const float* scales,
+ device const float* values,
+ device const int* config,
+ uint index [[thread_position_in_grid]]) {
+ uint row = config[1] ? index / config[0] : 0;
+ float decoded = values[packed[index]] * scales[row];
+ uint bits = as_type<uint>(decoded);
+ output[index] = (bits & 0x7fffffffu) > 0x7f800000u
+ ? ushort((bits >> 16) | 0x0040u)
+ : ushort((bits + 0x7fffu + ((bits >> 16) & 1u)) >> 16);
+ }
+ ''')
+ values = torch.arange(256, dtype=torch.uint8).view(torch.float8_e4m3fn).float().to('mps')
+ return library, values
+
+
+def decode_weight(weight, scale):
+ import torch
+ if (weight.device.type != 'cpu' or scale.device.type != 'cpu' or weight.ndim != 2
+ or weight.dtype != torch.float8_e4m3fn or not weight.is_contiguous()
+ or scale.dtype != torch.float32 or scale.numel() not in (1, weight.shape[0])):
+ raise ValueError('Expected contiguous CPU E4M3 matrix and FP32 scalar/row scales')
+ library, values = _kernel()
+ result = torch.empty(weight.shape, dtype=torch.bfloat16, device='mps')
+ packed = weight.view(torch.uint8).to('mps')
+ scales = scale.reshape(-1).to('mps')
+ config = torch.tensor([weight.shape[1], int(scale.numel() > 1)], dtype=torch.int32, device='mps')
+ library.decode_e4m3(result, packed, scales, values, config)
+ return result
diff --git a/freevideo_engine/backends/mps_grouped_qkv.py b/freevideo_engine/backends/mps_grouped_qkv.py
new file mode 100644
index 0000000..befd36b
--- /dev/null
+++ b/freevideo_engine/backends/mps_grouped_qkv.py
@@ -0,0 +1,140 @@
+"""MPS projection groups with bounded Q/K/V lifetimes.
+
+Project independent output channels per head group. Reuse original norms,
+RoPE, window attention, delta scans and full-width output projections. Grouped
+GEMM/text-state shapes can change rounding; native/full-output checks are required.
+This adapter is not enabled by the engine default policy yet.
+"""
+import types
+
+
+def install(model, attention, *, head_chunk=4, row_chunk=1024, qk_prepare=None):
+ import torch
+ import torch.nn.functional as F
+ from src.models.hybrid_attention import HybridAttention
+ from src.models.linear_attention.scan import _run_scans, gather_linear_state
+ from .mps_attention import prepare_qk, project_rows
+ from .mps_linear import frame_mean, frame_statistics
+ from ..lora_online import apply as apply_lora
+ qk_prepare = prepare_qk if qk_prepare is None else qk_prepare
+ for value in (head_chunk, row_chunk):
+ if type(value) is not int or value < 1:
+ raise ValueError('Positive integer group sizes required')
+ modules = tuple(module for module in model.modules() if isinstance(module, HybridAttention))
+ if not modules:
+ raise ValueError('Expected at least one pinned HybridAttention module')
+ for module in modules:
+ projections = (module.orig.to_q, module.orig.to_k, module.orig.to_v)
+ if any(not isinstance(projection, torch.nn.Linear) for projection in projections):
+ raise TypeError('Grouped MPS attention requires eager Linear projections')
+ if any(projection.out_features != module.orig.heads * module.head_dim for projection in projections):
+ raise ValueError('Projection width must match the original attention heads')
+ policy = dict(implementation='mps-grouped-qkv-v1', branches=0,
+ head_chunk=head_chunk, row_chunk=row_chunk,
+ largest_projected_elements=0, full_projection_elements=0)
+
+ def project(module, value, channels, count, dim):
+ if not isinstance(module, torch.nn.Linear):
+ raise TypeError('Grouped MPS attention requires eager Linear projections')
+ weight = module.weight[channels]
+ bias = None if module.bias is None else module.bias[channels]
+ output = F.linear(value, weight, bias)
+ output = apply_lora(module, value, output, channels=channels)
+ policy['largest_projected_elements'] = max(policy['largest_projected_elements'], output.numel())
+ return output.unflatten(-1, (count, dim))
+
+ def forward(owner, x, rotary_emb):
+ if torch.is_grad_enabled() or owner.training or owner.inference_mode or owner.hybrid_inference_mode:
+ raise RuntimeError('Grouped MPS QKV requires eager no-grad inference')
+ orig, layout = owner.orig, owner.layout
+ bounds = owner._bounds(layout) if layout is not None else None
+ full = layout is None or all(lo <= 0 and hi >= layout.num_frames - 1 for lo, hi in bounds)
+ dim, heads = owner.head_dim, orig.heads
+ policy['full_projection_elements'] = max(policy['full_projection_elements'], x.shape[0] * heads * dim)
+ softmax = None
+ linear_active = not full and owner.linear_attention_enabled
+ linear = beta = alpha = text_beta = xv = None
+ if linear_active:
+ branch = owner.linear_attention
+ start, end = layout.video_start, layout.video_end
+ skip = owner.anchor_frames == 'both'
+ tokens = layout.tokens_per_frame
+ frames = layout.num_frames - 2 if skip else layout.num_frames
+ inner = slice(tokens, (layout.num_frames - 1) * tokens) if skip else slice(None)
+ linear = x.new_zeros(layout.num_frames * tokens, heads, dim)
+ xv = x[start:end][inner]
+ inner_bounds = [(lo - 1, hi - 1) for lo, hi in bounds[1:-1]] if skip else bounds
+ if frames > 0:
+ beta = torch.sigmoid(branch.beta_proj(xv)).view(frames, tokens, heads).permute(0, 2, 1)
+ alpha = branch.alpha(frame_mean(xv, frames, tokens))
+ backend = branch._delta_backend('backend', tokens)
+ if owner.enable_text_state:
+ ta, tb = layout.text_range
+ text_beta = torch.sigmoid(branch.beta_proj(x[ta:tb]))
+ for begin in range(0, heads, head_chunk):
+ group = slice(begin, min(begin + head_chunk, heads))
+ count = group.stop - group.start
+ channels = slice(group.start * dim, group.stop * dim)
+ raw = tuple(project(module, x, channels, count, dim)
+ for module in (orig.to_q, orig.to_k, orig.to_v))
+ if softmax is None:
+ # Preserve the reference projection dtype under autocast, too.
+ softmax = raw[0].new_empty(x.shape[0], heads, dim)
+ policy['softmax_buffer_dtype'] = str(softmax.dtype)
+ policy['softmax_buffer_bytes'] = softmax.numel() * softmax.element_size()
+ if linear_active and raw[0].dtype != x.dtype:
+ raise ValueError('MPS linear readout output dtype differs')
+ query = qk_prepare(raw[0], orig.norm_q, rotary_emb, row_chunk)
+ key = qk_prepare(raw[1], orig.norm_k, rotary_emb, row_chunk)
+ if full:
+ from diffusers.models.attention_dispatch import dispatch_attention_fn
+ part = dispatch_attention_fn(query.unsqueeze(0), key.unsqueeze(0), raw[2].unsqueeze(0),
+ attn_mask=None, dropout_p=0., is_causal=False,
+ backend=getattr(type(orig.processor), '_attention_backend', None)).squeeze(0)
+ else:
+ part = attention(query, key, raw[2], layout, bounds, dim ** -.5, owner.anchor_frames)
+ softmax[:, group] = part
+ del query, key, part
+ if linear_active and frames > 0:
+ initial = None
+ if text_beta is not None:
+ initial = branch._text_state(None, tuple(value[ta:tb] for value in raw),
+ heads=group, text_beta=text_beta[:, group])
+ shape = (frames, tokens, count, dim)
+ query, key, value = (branch._feature_one(value[start:end][inner].contiguous(), name,
+ frames, layout.frame_size if branch.short_conv is not None else None, heads=group)
+ for name, value in zip(('q', 'k', 'v'), raw))
+ A, B = frame_statistics(key.view(shape).permute(0, 2, 1, 3),
+ value.view(shape).permute(0, 2, 1, 3), beta[:, group], a_fp32=branch.a_fp32)
+ del key, value
+ prefix, suffix = _run_scans(backend, alpha[:, group], A, B, text_state=initial)
+ del A, B
+ state = gather_linear_state(prefix, suffix, alpha[:, group], inner_bounds,
+ bridge=branch.bridge, text_state=initial).to(x.dtype)
+ del prefix, suffix
+ part = torch.einsum('fhvk,fshk->fshv', state, query.view(shape))
+ linear[inner, group] = branch.norm(part.reshape(frames * tokens, count, dim))
+ del state, query, part, initial
+ del raw
+ if owner.enable_softmax_gate:
+ gate = owner.softmax_gate(x).to(softmax.dtype)
+ softmax.mul_(gate)
+ del gate
+ out = orig.to_out[1](project_rows(softmax.reshape(x.shape[0], -1), orig.to_out[0],
+ chunk=row_chunk, dtype=x.dtype, reuse=True))
+ del softmax
+ if linear_active:
+ if frames > 0:
+ for begin in range(0, len(xv), row_chunk):
+ stop = min(begin + row_chunk, len(xv))
+ linear[inner][begin:stop].mul_(branch.output_gate(xv[begin:stop]))
+ readout = linear.reshape(end - start, -1)
+ for begin in range(0, end - start, row_chunk):
+ stop = min(begin + row_chunk, end - start)
+ out[start + begin:start + stop] += owner.to_out_linear(readout[begin:stop].type_as(x))
+ return out
+
+ for module in modules:
+ module._hybrid_forward = types.MethodType(forward, module)
+ policy['branches'] += 1
+ return policy
diff --git a/freevideo_engine/backends/mps_int8.py b/freevideo_engine/backends/mps_int8.py
new file mode 100644
index 0000000..39cd22f
--- /dev/null
+++ b/freevideo_engine/backends/mps_int8.py
@@ -0,0 +1,465 @@
+"""Int8 projections on Apple M5 TensorOps for the large H3 linear layers.
+
+Activations take one scale per row (absmax / 127) and weights one per output
+channel; exact int32 products are scaled back to BF16. On an M5 with a 10-core
+GPU the products ran at 20.7-21.2 TOPS, against 13.7-14.6 TFLOPS for torch MPS
+BF16 matmuls, at the 4,096- and 18,144-row block shapes; the 14,336-wide FC2
+input reached 16.9-19.1 TOPS. The tiled TensorOps matmul is adapted from
+antirez/h3.c (MIT). Other Apple GPUs keep the BF16 path.
+
+ConvRot weights (rows rotated by a group-256 regular Hadamard transform before
+quantization, the convention of ComfyUI's int8 H3 checkpoints) get the same
+rotation on each activation row inside the quantizer. On real block-10 inputs
+it cut the output error of FC2 from 5.9% to 1.2% and of every large projection
+to 0.75-1.3%, against 1.8-2.6% for the FP8 weights of the BF16 path.
+"""
+from functools import lru_cache
+
+TILE = 128
+
+ROTATE = r'''
+constant constexpr uint MAXG2 = 7;
+
+inline void rotate_group2(thread float (&v)[8], uint lane) {
+ // Digit 0: registers 0-3 and 4-7. Row d of H4 has its -1 at column 3 - d.
+ for (uint b = 0; b < 8; b += 4) {
+ float a0 = v[b], a1 = v[b + 1], a2 = v[b + 2], a3 = v[b + 3];
+ float s = a0 + a1 + a2 + a3;
+ v[b] = s - 2.0f * a3; v[b + 1] = s - 2.0f * a2; v[b + 2] = s - 2.0f * a1; v[b + 3] = s - 2.0f * a0;
+ }
+ // Digit 1 = register bit 2 + 2 * lane bit 0.
+ uint low = lane & 1u;
+ for (uint j = 0; j < 4; j++) {
+ float own0 = v[j], own1 = v[j + 4];
+ float other0 = simd_shuffle_xor(own0, 1), other1 = simd_shuffle_xor(own1, 1);
+ float a0 = low ? other0 : own0, a1 = low ? other1 : own1;
+ float a2 = low ? own0 : other0, a3 = low ? own1 : other1;
+ float s = a0 + a1 + a2 + a3;
+ // This lane keeps digit values 2*low (register j) and 1 + 2*low (register j + 4).
+ v[j] = s - 2.0f * (low ? a1 : a3);
+ v[j + 4] = s - 2.0f * (low ? a0 : a2);
+ }
+ // Digits 2 and 3: the partner with digit 3 - d is lane ^ (3 << shift).
+ for (uint j = 0; j < 8; j++) {
+ float a = v[j];
+ float s = a + simd_shuffle_xor(a, 2);
+ s += simd_shuffle_xor(s, 4);
+ a = s - 2.0f * simd_shuffle_xor(a, 6);
+ s = a + simd_shuffle_xor(a, 8);
+ s += simd_shuffle_xor(s, 16);
+ v[j] = (s - 2.0f * simd_shuffle_xor(a, 24)) * 0.0625f;
+ }
+}
+'''
+
+SOURCE = r'''
+#include <metal_stdlib>
+#include <metal_tensor>
+#include <MetalPerformancePrimitives/MetalPerformancePrimitives.h>
+using namespace metal;
+using namespace mpp::tensor_ops;
+''' + ROTATE + r'''
+
+// One threadgroup per row: the absmax reduction, then rounding to nearest
+// even. Rows past the last real row are written as zeros for the matmul tile.
+template <typename T>
+[[kernel]] void quantize_rows_impl(device const T *input [[buffer(0)]],
+ device int8_t *output [[buffer(1)]],
+ device float *scales [[buffer(2)]],
+ constant uint &rows [[buffer(3)]],
+ constant uint &depth [[buffer(4)]],
+ constant uint &stride [[buffer(5)]],
+ uint row [[threadgroup_position_in_grid]],
+ uint tid [[thread_index_in_threadgroup]],
+ uint threads [[threads_per_threadgroup]],
+ uint lane [[thread_index_in_simdgroup]],
+ uint simd [[simdgroup_index_in_threadgroup]]) {
+ threadgroup float partial[32];
+ device int8_t *destination = output + (ulong)row * depth;
+ if (row >= rows) {
+ for (uint k = tid; k < depth; k += threads) destination[k] = 0;
+ if (tid == 0) scales[row] = 0.0f;
+ return;
+ }
+ device const T *source = input + (ulong)row * stride;
+ float largest = 0.0f;
+ for (uint k = tid; k < depth; k += threads) largest = max(largest, fabs((float)source[k]));
+ largest = simd_max(largest);
+ if (lane == 0) partial[simd] = largest;
+ threadgroup_barrier(mem_flags::mem_threadgroup);
+ if (simd == 0) {
+ uint groups = (threads + 31) / 32;
+ largest = lane < groups ? partial[lane] : 0.0f;
+ largest = simd_max(largest);
+ if (lane == 0) partial[0] = largest;
+ }
+ threadgroup_barrier(mem_flags::mem_threadgroup);
+ float scale = max(partial[0], 1e-12f) / 127.0f;
+ for (uint k = tid; k < depth; k += threads)
+ destination[k] = (int8_t)clamp(rint(precise::divide((float)source[k], scale)), -127.0f, 127.0f);
+ if (tid == 0) scales[row] = scale;
+}
+
+template <typename T>
+[[kernel]] void int8_matmul_impl(device int8_t *input [[buffer(0)]],
+ device int8_t *weight [[buffer(1)]],
+ device const float *input_scales [[buffer(2)]],
+ device const float *weight_scales [[buffer(3)]],
+ device T *output [[buffer(4)]],
+ constant uint &rows [[buffer(5)]],
+ constant uint &depth [[buffer(6)]],
+ constant uint &columns [[buffer(7)]],
+ uint2 group [[threadgroup_position_in_grid]]) {
+ constexpr uint TILE = 128;
+ uint padded_rows = (rows + TILE - 1) & ~(TILE - 1);
+ uint row_start = group.y * TILE;
+ uint column_start = group.x * TILE;
+ auto x = tensor<device int8_t, dextents<int32_t, 2>, tensor_inline>(
+ input, dextents<int32_t, 2>((int)depth, (int)padded_rows));
+ auto w = tensor<device int8_t, dextents<int32_t, 2>, tensor_inline>(
+ weight, dextents<int32_t, 2>((int)depth, (int)columns));
+ constexpr auto descriptor = matmul2d_descriptor(
+ TILE, TILE, TILE, false, true, true, matmul2d_descriptor::mode::multiply_accumulate);
+ matmul2d<descriptor, execution_simdgroups<8>> mm;
+ auto first_a = x.slice<TILE, TILE>(0, (int)row_start);
+ auto first_b = w.slice<TILE, TILE>(0, (int)column_start);
+ auto accum = mm.template get_destination_cooperative_tensor<decltype(first_a), decltype(first_b), int32_t>();
+ #pragma clang loop unroll(full)
+ for (ushort e = 0; e < accum.get_capacity(); e++)
+ if (accum.is_valid_element(e)) accum[e] = 0;
+ for (uint k = 0; k < depth; k += TILE) {
+ auto a = x.slice<TILE, TILE>((int)k, (int)row_start);
+ auto b = w.slice<TILE, TILE>((int)k, (int)column_start);
+ mm.run(a, b, accum);
+ }
+ #pragma clang loop unroll(full)
+ for (ushort e = 0; e < accum.get_capacity(); e++) {
+ if (!accum.is_valid_element(e)) continue;
+ auto index = accum.get_multidimensional_index(e);
+ uint row = row_start + (uint)index[1];
+ uint column = column_start + (uint)index[0];
+ if (row < rows)
+ output[(ulong)row * columns + column] =
+ (T)((float)accum[e] * input_scales[row] * weight_scales[column]);
+ }
+}
+
+// ConvRot: a group-256 regular Hadamard rotation of each row, then per-row int8.
+// H256 = H4 (x) H4 (x) H4 (x) H4 / 16 with H4 = [[1,1,1,-1],[1,1,-1,1],[1,-1,1,1],[-1,1,1,1]],
+// symmetric and orthogonal, so x W^T = (x H)(W H)^T. Each simdgroup rotates whole groups:
+// lane l holds channels 8l..8l+7, so digit 0 lives in registers, digit 1 mixes register
+// bit 2 with lane bit 0, and digits 2 and 3 are lane bits 1-2 and 3-4 (xor shuffles).
+// The rotated row stays in registers (at most MAXG2 groups per simdgroup) until the row's
+// absmax is known; rounding is to nearest even like quantize_rows. At 18,144 rows this
+// took 2.5-6.5 ms, against 3.0-8.1 ms for the unrotated quantizer.
+template <typename T, typename T4>
+[[kernel]] void quantize_rows_convrot2_impl(device const T *input [[buffer(0)]],
+ device int8_t *output [[buffer(1)]],
+ device float *scales [[buffer(2)]],
+ constant uint &rows [[buffer(3)]],
+ constant uint &depth [[buffer(4)]],
+ constant uint &stride [[buffer(5)]],
+ uint row [[threadgroup_position_in_grid]],
+ uint tid [[thread_index_in_threadgroup]],
+ uint lane [[thread_index_in_simdgroup]],
+ uint simd [[simdgroup_index_in_threadgroup]]) {
+ threadgroup float partial[8];
+ device int8_t *destination = output + (ulong)row * depth;
+ if (row >= rows) {
+ for (uint k = tid; k < depth; k += 256) destination[k] = 0;
+ if (tid == 0) scales[row] = 0.0f;
+ return;
+ }
+ device const T *source = input + (ulong)row * stride;
+ uint groups = depth / 256;
+ float values[MAXG2][8];
+ float largest = 0.0f;
+ for (uint slot = 0; slot < MAXG2; slot++) {
+ uint g = simd + slot * 8;
+ if (g >= groups) break;
+ thread float (&v)[8] = values[slot];
+ device const T4 *pair = (device const T4 *)(source + g * 256 + lane * 8);
+ float4 first = float4(pair[0]), second = float4(pair[1]);
+ v[0] = first.x; v[1] = first.y; v[2] = first.z; v[3] = first.w;
+ v[4] = second.x; v[5] = second.y; v[6] = second.z; v[7] = second.w;
+ rotate_group2(v, lane);
+ for (uint j = 0; j < 8; j++) largest = max(largest, fabs(v[j]));
+ }
+ largest = simd_max(largest);
+ if (lane == 0) partial[simd] = largest;
+ threadgroup_barrier(mem_flags::mem_threadgroup);
+ largest = max(max(max(partial[0], partial[1]), max(partial[2], partial[3])),
+ max(max(partial[4], partial[5]), max(partial[6], partial[7])));
+ float scale = max(largest, 1e-12f) / 127.0f;
+ for (uint slot = 0; slot < MAXG2; slot++) {
+ uint g = simd + slot * 8;
+ if (g >= groups) break;
+ char4 q0, q1;
+ for (uint j = 0; j < 4; j++) {
+ q0[j] = (char)clamp(rint(precise::divide(values[slot][j], scale)), -127.0f, 127.0f);
+ q1[j] = (char)clamp(rint(precise::divide(values[slot][j + 4], scale)), -127.0f, 127.0f);
+ }
+ device char4 *out = (device char4 *)(destination + g * 256 + lane * 8);
+ out[0] = q0; out[1] = q1;
+ }
+ if (tid == 0) scales[row] = scale;
+}
+
+#define INSTANTIATE(NAME, FUNCTION, T) \
+ template [[host_name(NAME)]] [[kernel]] decltype(FUNCTION<T>) FUNCTION<T>;
+template [[host_name("quantize_rows_convrot")]] [[kernel]]
+decltype(quantize_rows_convrot2_impl<bfloat, bfloat4>) quantize_rows_convrot2_impl<bfloat, bfloat4>;
+template [[host_name("quantize_rows_convrot_half")]] [[kernel]]
+decltype(quantize_rows_convrot2_impl<half, half4>) quantize_rows_convrot2_impl<half, half4>;
+INSTANTIATE("quantize_rows", quantize_rows_impl, bfloat)
+INSTANTIATE("quantize_rows_half", quantize_rows_impl, half)
+INSTANTIATE("int8_matmul", int8_matmul_impl, bfloat)
+INSTANTIATE("int8_matmul_half", int8_matmul_impl, half)
+'''
+
+
+PORTABLE = r'''
+#include <metal_stdlib>
+using namespace metal;
+''' + ROTATE + r'''
+// One threadgroup (8 simdgroups) per row: int8 x row scale, then the ConvRot
+// rotation, which is its own inverse, back to the original BF16 basis.
+kernel void dequantize_convrot(device const char *weight [[buffer(0)]],
+ device const float *scales [[buffer(1)]],
+ device bfloat *output [[buffer(2)]],
+ constant uint &depth [[buffer(3)]],
+ uint row [[threadgroup_position_in_grid]],
+ uint lane [[thread_index_in_simdgroup]],
+ uint simd [[simdgroup_index_in_threadgroup]]) {
+ float scale = scales[row];
+ for (uint g = simd; g < depth / 256; g += 8) {
+ float v[8];
+ device const char *source = weight + (ulong)row * depth + g * 256 + lane * 8;
+ for (uint j = 0; j < 8; j++) v[j] = (float)source[j] * scale;
+ rotate_group2(v, lane);
+ device bfloat *target = output + (ulong)row * depth + g * 256 + lane * 8;
+ for (uint j = 0; j < 8; j++) target[j] = (bfloat)v[j];
+ }
+}
+'''
+
+
+@lru_cache(maxsize=1)
+def _portable_library():
+ import torch
+ return torch.mps.compile_shader(PORTABLE)
+
+
+def dequantize_convrot(weight, scales):
+ """ConvRot int8 rows [N, K] and FP32 row scales -> BF16 [N, K] in the original basis (MPS)."""
+ import torch
+ if (weight.dtype != torch.int8 or weight.ndim != 2 or weight.device.type != 'mps'
+ or weight.shape[1] % CONVROT_GROUP or not weight.is_contiguous()):
+ raise ValueError('ConvRot dequantization expects contiguous int8 MPS rows of 256-channel groups')
+ scales = scales.reshape(-1).float().contiguous()
+ if scales.numel() != weight.shape[0] or scales.device != weight.device:
+ raise ValueError('ConvRot dequantization needs one MPS scale per row')
+ output = torch.empty(weight.shape, dtype=torch.bfloat16, device=weight.device)
+ _portable_library().dequantize_convrot(weight, scales, output, weight.shape[1],
+ threads=[weight.shape[0] * 256, 1, 1], group_size=[256, 1, 1])
+ return output
+
+@lru_cache(maxsize=1)
+def _library():
+ import torch
+ return torch.mps.compile_shader(SOURCE)
+
+
+@lru_cache(maxsize=1)
+def available():
+ """True on an Apple M5 or newer whose Metal compiler accepts the TensorOps kernels."""
+ import platform
+ import subprocess
+ if platform.system() != 'Darwin':
+ return False
+ try:
+ import os
+ import re
+ if os.environ.get('FREEVIDEO_MPS_INT8_COMPUTE') == '0':
+ return False
+ chip = subprocess.run(['sysctl', '-n', 'machdep.cpu.brand_string'], capture_output=True,
+ text=True, timeout=10).stdout
+ generation = re.search(r'Apple M(\d+)', chip)
+ if generation is None or int(generation.group(1)) < 5:
+ return False
+ _library()
+ return True
+ except Exception:
+ return False
+
+
+CONVROT_GROUP = 256
+CONVROT_DEPTH = 14336 # MAXG2 groups per simdgroup in the rotation kernel
+
+
+def convrot_rotate(matrix, group=CONVROT_GROUP):
+ """Rows of a float matrix times the block-diagonal ConvRot Hadamard transform.
+
+ The transform is symmetric and orthogonal, so this both rotates rows into
+ the ConvRot basis and rotates dequantized ConvRot rows back.
+ """
+ import torch
+ if group != CONVROT_GROUP or matrix.ndim != 2 or matrix.shape[1] % group:
+ raise ValueError('ConvRot rows need 256-channel groups')
+ h4 = torch.tensor([[1, 1, 1, -1], [1, 1, -1, 1], [1, -1, 1, 1], [-1, 1, 1, 1]], dtype=torch.float64)
+ h = torch.kron(torch.kron(h4, h4), torch.kron(h4, h4)) / 16
+ rows = matrix.double().reshape(matrix.shape[0], -1, group) @ h.to(matrix.device)
+ return rows.reshape(matrix.shape).to(matrix.dtype)
+
+
+def quantize_rows(value, convrot=False):
+ """BF16 [rows, K] -> int8 [rows padded to 128, K] and FP32 row scales.
+
+ With convrot, each 256-channel group of a row is first rotated by the
+ regular Hadamard transform the ConvRot weights were rotated with.
+ """
+ import torch
+ if (value.ndim != 2 or value.dtype not in (torch.bfloat16, torch.float16)
+ or value.device.type != 'mps' or value.stride(1) != 1):
+ raise ValueError('Row quantization expects a BF16 or FP16 MPS matrix with unit column stride')
+ rows, depth = value.shape
+ if depth % TILE:
+ raise ValueError('Int8 projection depth must be a multiple of 128')
+ if convrot and (depth % CONVROT_GROUP or depth > CONVROT_DEPTH):
+ raise ValueError('ConvRot rows need a multiple of 256 channels, at most 14,336')
+ if convrot and (value.stride(0) % 4 or value.data_ptr() % 8):
+ value = value.contiguous() # The rotation kernel reads four channels per load.
+ padded = (rows + TILE - 1) // TILE * TILE
+ quantized = torch.empty((padded, depth), dtype=torch.int8, device=value.device)
+ scales = torch.empty(padded, dtype=torch.float32, device=value.device)
+ library = _library()
+ if convrot:
+ kernel = library.quantize_rows_convrot if value.dtype == torch.bfloat16 else library.quantize_rows_convrot_half
+ else:
+ kernel = library.quantize_rows if value.dtype == torch.bfloat16 else library.quantize_rows_half
+ kernel(value, quantized, scales, rows, depth, value.stride(0),
+ threads=[padded * 256, 1, 1], group_size=[256, 1, 1])
+ return quantized, scales, rows
+
+
+def matmul(quantized, weight, weight_scales, dtype=None):
+ """(int8 rows, scales, row count) x int8 [N, K] weight -> BF16 (or FP16) [rows, N]."""
+ import torch
+ dtype = torch.bfloat16 if dtype is None else dtype
+ values, scales, rows = quantized
+ columns, depth = weight.shape
+ if (weight.dtype != torch.int8 or not weight.is_contiguous() or values.shape[1] != depth
+ or columns % TILE or weight_scales.shape != (columns,) or weight_scales.dtype != torch.float32):
+ raise ValueError('Int8 projection expects a contiguous int8 [N, K] weight and FP32 [N] scales')
+ if dtype not in (torch.bfloat16, torch.float16):
+ raise ValueError('Int8 products return BF16 or FP16')
+ output = torch.empty((rows, columns), dtype=dtype, device=values.device)
+ kernel = _library().int8_matmul if dtype == torch.bfloat16 else _library().int8_matmul_half
+ kernel(values, weight, scales, weight_scales, output, rows, depth, columns,
+ threads=[columns // TILE * 256, values.shape[0] // TILE, 1], group_size=[256, 1, 1])
+ return output
+
+
+def quantize_weight(weight):
+ """Per-output-channel int8 weights and FP32 scales from a floating [N, K] matrix."""
+ import torch
+ values = weight.float()
+ scales = values.abs().amax(dim=1).clamp_min(1e-12) / 127
+ quantized = torch.round(values / scales[:, None]).clamp_(-127, 127).to(torch.int8)
+ return quantized.contiguous(), scales.contiguous()
+
+
+def eligible(module):
+ """The large projections: Q/K/V, both attention outputs, FF up and down."""
+ import torch
+ return (isinstance(module, torch.nn.Linear) and module.in_features >= 5376
+ and module.out_features >= 1024 and module.in_features % TILE == 0
+ and module.out_features % TILE == 0)
+
+
+def install(model, *, stats=None, storage=None, int8_linears=None):
+ """Route eligible Linear forwards through int8 products.
+
+ With storage='int8' the prepared model already holds per-row int8 weights:
+ each eligible weight placeholder becomes int8 and gains a `weight_scale`
+ buffer, so layer loading binds both and residency accounting sees one byte
+ per weight. `int8_linears` maps those Linear names to their manifest
+ entries; an entry with convrot_group 256 holds ConvRot-rotated rows, and its
+ inputs are rotated the same way while they are quantized. Otherwise BF16
+ weights are quantized on first use after each load, and the int8 copy lives
+ as long as the bound BF16 weight. The most recent quantized input is reused,
+ so Q/K/V share one quantization.
+ """
+ import types
+ import weakref
+ import torch
+ if storage not in (None, 'int8'):
+ raise ValueError('Unknown int8 weight storage')
+ if storage == 'int8' and not isinstance(int8_linears, dict):
+ raise ValueError('Int8 storage needs the manifest entries of the Linears stored as int8')
+ for entry in (int8_linears or {}).values():
+ if entry.get('convrot_group') not in (None, CONVROT_GROUP):
+ raise ValueError('Unknown ConvRot group in the int8 manifest')
+ # Engine kernel reports subtract counters between phases: numbers only.
+ stats = {} if stats is None else stats
+ stats.update(modules=0, convrot_modules=0, weight_quantizations=0, input_quantizations=0, int8_forwards=0)
+ weights = {}
+ last = {}
+
+ def quantized_weight(weight):
+ key = (weight.data_ptr(), weight._version, tuple(weight.shape))
+ found = weights.get(key)
+ if found is None:
+ found = weights[key] = quantize_weight(weight)
+ weakref.finalize(weight, weights.pop, key, None)
+ stats['weight_quantizations'] += 1
+ return found
+
+ def quantized_input(rows, convrot):
+ # The entry keeps its source alive: a freed input's address could
+ # otherwise be reused by the next block with the same shape.
+ key = (rows.data_ptr(), rows._version, tuple(rows.shape), tuple(rows.stride()), convrot)
+ if last.get('key') != key or last.get('source') is None:
+ last.clear()
+ last.update(key=key, source=rows, value=quantize_rows(rows, convrot=convrot))
+ stats['input_quantizations'] += 1
+ return last['value']
+
+ def forward(module, value):
+ weight = module.weight
+ if weight.dtype == torch.int8:
+ if value.dtype != torch.bfloat16 or value.device.type != 'mps' or weight.is_meta:
+ raise RuntimeError('Int8 weights need a loaded layer and BF16 MPS inputs')
+ pair = (weight, module.weight_scale)
+ elif value.dtype != torch.bfloat16 or value.device.type != 'mps' or weight.is_meta:
+ return torch.nn.functional.linear(value, weight, module.bias)
+ else:
+ pair = quantized_weight(weight)
+ rows = value.reshape(-1, value.shape[-1])
+ if rows.stride(1) != 1:
+ rows = rows.contiguous()
+ output = matmul(quantized_input(rows, getattr(module, '_freevideo_convrot', False)), *pair)
+ if module.bias is not None:
+ output += module.bias
+ stats['int8_forwards'] += 1
+ return output.reshape(*value.shape[:-1], module.out_features)
+
+ for name, module in model.named_modules():
+ # Only matrices the prepared model stores as int8 get int8 placeholders;
+ # every other Linear keeps its BF16 storage and ordinary forward.
+ if eligible(module) and (storage != 'int8' or name in int8_linears):
+ if storage == 'int8':
+ module.weight = torch.nn.Parameter(torch.empty(module.weight.shape, dtype=torch.int8,
+ device='meta'), requires_grad=False)
+ module.register_buffer('weight_scale', torch.empty(module.out_features, dtype=torch.float32,
+ device='meta'))
+ if int8_linears[name].get('convrot_group') == CONVROT_GROUP:
+ if module.in_features % CONVROT_GROUP or module.in_features > CONVROT_DEPTH:
+ raise ValueError('ConvRot Linear width is outside the rotation kernel: ' + name)
+ module._freevideo_convrot = True
+ stats['convrot_modules'] += 1
+ module.forward = types.MethodType(forward, module)
+ stats['modules'] += 1
+ return dict(implementation='mps-int8-tensorops-v1', storage=storage or 'quantize-on-load',
+ modules=stats['modules'])
+
diff --git a/freevideo_engine/backends/mps_linear.py b/freevideo_engine/backends/mps_linear.py
new file mode 100644
index 0000000..03d8614
--- /dev/null
+++ b/freevideo_engine/backends/mps_linear.py
@@ -0,0 +1,136 @@
+"""Bound the native reference linear branch by independent attention heads.
+
+Keep the upstream eager operations, dtypes and temporal/spatial neighborhoods.
+Only independent heads are grouped; no token reduction is split. Smaller batched
+GEMM/convolution shapes can change rounding and need native numerical comparison.
+The CUDA inference body and its fused kernels are never selected here.
+"""
+from functools import partial
+import types
+
+
+def frame_mean(xv, num_frames, tokens_per_frame):
+ """Keep each full spatial reduction; bound independent frames' FP32 casts."""
+ import torch
+ frames = xv.view(num_frames, tokens_per_frame, -1)
+ # MPS mean(dtype=FP32) can materialize an FP32 copy of its input. A whole
+ # 10-second sequence needs hundreds of MiB before any reduction happens.
+ # Batch only independent frames, never split the spatial reduction axis.
+ batch = max(1, (32 * 2**20) // (tokens_per_frame * frames.shape[-1] * 4))
+ result = torch.empty((num_frames, frames.shape[-1]), dtype=torch.float32, device=xv.device)
+ for start in range(0, num_frames, batch):
+ result[start:start + batch] = torch.mean(frames[start:start + batch], dim=1, dtype=torch.float32)
+ return result
+
+
+def frame_statistics(key, value, beta, *, a_fp32):
+ """Call the original statistics on bounded batches of independent frames."""
+ import torch
+ from src.models.linear_attention.scan import frame_statistics as reference
+ frames, heads, tokens, dim = key.shape
+ # Preserve the complete token/channel contractions and original FP32 A /
+ # BF16 B policy. Limit simultaneous cast/scaling planes, not their precision.
+ per_frame = heads * tokens * dim * (8 + 2 * key.element_size())
+ batch = max(1, (16 * 2**20) // per_frame)
+ if frames <= batch:
+ return reference(key, value, beta, a_fp32=a_fp32)
+ A = torch.empty((frames, heads, dim, dim), device=key.device, dtype=torch.float32)
+ B = torch.empty((frames, heads, value.shape[-1], dim), device=key.device, dtype=torch.float32)
+ for start in range(0, frames, batch):
+ end = min(start + batch, frames)
+ a, b = reference(key[start:end], value[start:end], beta[start:end], a_fp32=a_fp32)
+ A[start:end], B[start:end] = a, b
+ del a, b
+ return A, B
+
+
+def readout(branch, xv, num_frames, tokens_per_frame, bounds, qkv_raw,
+ frame_size=None, text_x=None, text_qkv_raw=None, *, head_chunk=4, gate_chunk=256,
+ output=None):
+ import torch
+ from src.models.linear_attention.scan import _run_scans, gather_linear_state
+ if torch.is_grad_enabled():
+ raise RuntimeError('Bounded MPS linear attention requires inference without autograd')
+ heads, dim = branch.num_heads, branch.head_dim
+ rows = num_frames * tokens_per_frame
+ backend = branch._delta_backend('backend', tokens_per_frame)
+ # Evaluate the original small projections with their full shapes, preserving
+ # the FP32 frame mean and alpha island, and the shared text initial state.
+ beta = torch.sigmoid(branch.beta_proj(xv)).view(num_frames, tokens_per_frame, heads)
+ beta = beta.permute(0, 2, 1)
+ alpha = branch.alpha(frame_mean(xv, num_frames, tokens_per_frame))
+ text_state = branch._text_state(text_x, text_qkv_raw)
+ out = xv.new_empty(rows, heads, dim) if output is None else output
+ if out.shape != (rows, heads, dim) or out.dtype != xv.dtype or out.device != xv.device:
+ raise ValueError('MPS linear readout output shape, dtype or device differs')
+ for start in range(0, heads, head_chunk):
+ group = slice(start, min(start + head_chunk, heads))
+ count = group.stop - group.start
+ shape = (num_frames, tokens_per_frame, count, dim)
+ query, key, value = (
+ branch._feature_one(tokens[:, group].contiguous(), proj, num_frames,
+ frame_size, heads=group)
+ for proj, tokens in zip(('q', 'k', 'v'), qkv_raw))
+ A, B = frame_statistics(key.view(shape).permute(0, 2, 1, 3),
+ value.view(shape).permute(0, 2, 1, 3),
+ beta[:, group], a_fp32=branch.a_fp32)
+ del key, value
+ initial = None if text_state is None else text_state[group]
+ prefix, suffix = _run_scans(backend, alpha[:, group], A, B, text_state=initial)
+ del A, B
+ state = gather_linear_state(prefix, suffix, alpha[:, group], bounds,
+ bridge=branch.bridge, text_state=initial).to(xv.dtype)
+ del prefix, suffix
+ part = torch.einsum('fhvk,fshk->fshv', state, query.view(shape))
+ del state, query
+ out[:, group] = branch.norm(part.reshape(rows, count, dim))
+ del part
+ # The original gate retains all channels and reduction axes. Bound only its
+ # independent token rows, avoiding another full video-sized activation.
+ for start in range(0, rows, gate_chunk):
+ end = min(start + gate_chunk, rows)
+ out[start:end].mul_(branch.output_gate(xv[start:end]))
+ return out.reshape(rows, heads * dim)
+
+
+def consume_qkv(branch, xv, num_frames, tokens_per_frame, bounds, qkv_raw, *,
+ frame_size=None, skip_ends=False, text_x=None, text_qkv_raw=None,
+ head_chunk=4, gate_chunk=256):
+ """Consume dead query storage after softmax, preserving upstream anchors.
+
+ Only the native hybrid adapter owns these QKV buffers and may use this path.
+ Each head's query is read before its output overwrites that head's storage;
+ K/V and text state remain unchanged. No whole-sequence readout/scatter copy.
+ """
+ import torch
+ if torch.is_grad_enabled():
+ raise RuntimeError('MPS QKV consumption requires inference without autograd')
+ target = qkv_raw[0]
+ if target.shape != (num_frames * tokens_per_frame, branch.num_heads, branch.head_dim):
+ raise ValueError('MPS QKV output geometry differs')
+ inner = slice(tokens_per_frame, (num_frames - 1) * tokens_per_frame) if skip_ends else slice(None)
+ if not skip_ends or num_frames > 2:
+ readout(branch, xv[inner], num_frames - 2 if skip_ends else num_frames,
+ tokens_per_frame, [(lo - 1, hi - 1) for lo, hi in bounds[1:-1]] if skip_ends else bounds,
+ tuple(t[inner] for t in qkv_raw), frame_size, text_x, text_qkv_raw,
+ head_chunk=head_chunk, gate_chunk=gate_chunk, output=target[inner])
+ if skip_ends:
+ target[:tokens_per_frame].zero_()
+ target[(num_frames - 1) * tokens_per_frame:].zero_()
+ return target.reshape(num_frames * tokens_per_frame, -1)
+
+
+def install(model, *, head_chunk=4, gate_chunk=256):
+ """Bind only this native model's eager readout; upstream anchor handling stays."""
+ from src.models.linear_attention.branch import BidirectionalLinearBranch
+ for name, value in (('head_chunk', head_chunk), ('gate_chunk', gate_chunk)):
+ if type(value) is not int or value < 1:
+ raise ValueError(name + ' must be a positive integer')
+ count = 0
+ for module in model.modules():
+ if isinstance(module, BidirectionalLinearBranch):
+ module._readout = types.MethodType(partial(readout, head_chunk=head_chunk,
+ gate_chunk=gate_chunk), module)
+ count += 1
+ return dict(implementation='mps-eager-head-groups-v3', branches=count,
+ head_chunk=head_chunk, gate_chunk=gate_chunk)
diff --git a/freevideo_engine/backends/mps_mlx_attention.py b/freevideo_engine/backends/mps_mlx_attention.py
new file mode 100644
index 0000000..3368264
--- /dev/null
+++ b/freevideo_engine/backends/mps_mlx_attention.py
@@ -0,0 +1,196 @@
+"""Window softmax attention through MLX's fused Metal SDPA.
+
+On the profiled M5 window shapes the Torch path ran at about 3.4 TFLOPS and
+MLX's fused kernel at 10.5-12 TFLOPS. Those measurements do not establish which
+Torch kernel ran. Q/K/V share their prepared Metal buffers through DLPack.
+The planner retains its conservative import allowance until complete workload
+capacity measurements justify changing compute partitions.
+
+The row sets are exactly the decomposed plan's: global and anchor-row queries
+see every key; each run of frames with identical bounds sees the globals, its
+window frames and any anchor columns. Only the reduction order changes.
+"""
+import time
+
+import numpy as np
+
+
+def _merge(ranges):
+ merged = []
+ for start, end in sorted(ranges):
+ if merged and merged[-1][1] >= start:
+ merged[-1] = (merged[-1][0], max(merged[-1][1], end))
+ else:
+ merged.append((start, end))
+ return merged
+
+
+def plan_ranges(layout, bounds, anchor_frames):
+ """Dense query ranges and (query range, key ranges) windows, covering every row once."""
+ rows, frames, per_frame = layout.seq_len, layout.num_frames, layout.tokens_per_frame
+ video_start, video_end = layout.video_start, layout.video_end
+ anchors = {0, frames - 1} if anchor_frames in ('columns', 'rows', 'both') else set()
+ dense_frames = anchors if anchor_frames in ('rows', 'both') else set()
+ column_frames = anchors if anchor_frames in ('columns', 'both') else set()
+
+ def frame_rows(frame):
+ return (video_start + frame * per_frame, video_start + (frame + 1) * per_frame)
+
+ globals_ = [r for r in ((0, video_start), (video_end, rows)) if r[0] < r[1]]
+ dense = _merge(globals_ + [frame_rows(f) for f in sorted(dense_frames)])
+ groups = []
+ for frame in range(frames):
+ if frame in dense_frames:
+ continue
+ if groups and bounds[groups[-1][-1]] == bounds[frame] and groups[-1][-1] == frame - 1:
+ groups[-1].append(frame)
+ else:
+ groups.append([frame])
+ windows = []
+ for group in groups:
+ low, high = bounds[group[0]]
+ keys = sorted(set(range(max(low, 0), min(high + 1, frames))) | column_frames)
+ query = _merge([frame_rows(f) for f in group])
+ if len(query) != 1:
+ raise ValueError('A window group must be one contiguous run of frames')
+ windows.append((query[0], tuple(_merge(globals_ + [frame_rows(f) for f in keys]))))
+ covered = sum(b - a for a, b in dense) + sum(q[1] - q[0] for q, _ in windows)
+ if covered != rows:
+ raise ValueError(f'Window plan covers {covered} of {rows} rows')
+ return dense, windows
+
+
+def to_mlx(tensor):
+ """Share prepared MPS storage; retain the host conversion for CPU inputs."""
+ return to_mlx_many((tensor,))[0]
+
+
+def to_mlx_many(tensors):
+ """Prepare all producer buffers before one Torch-to-MLX stream boundary.
+
+ A fence before preparing the last strided input would allow MLX to read an
+ unfinished copy. Validate the entire batch, prepare every copy, then fence.
+ DLPack retains each producer until lazy MLX consumers release it.
+ """
+ import mlx.core as mx
+ import torch
+ tensors = tuple(tensors)
+ for tensor in tensors:
+ if tensor.device.type == 'mps' and (torch.is_grad_enabled() or tensor.requires_grad):
+ raise ValueError('Shared MPS imports require no-grad inference')
+ prepared = tuple(t.contiguous() if t.device.type == 'mps' and not t.is_contiguous()
+ else t for t in tensors)
+ if any(t.device.type == 'mps' for t in tensors):
+ torch.mps.synchronize()
+ result = []
+ for original, tensor in zip(tensors, prepared):
+ if original.device.type == 'mps':
+ # Sharing failures stay explicit; do not silently duplicate Q/K/V.
+ result.append(mx.from_dlpack(tensor, copy=False))
+ else:
+ host = tensor.detach().to('cpu')
+ if host.dtype == torch.bfloat16:
+ result.append(mx.array(host.view(torch.int16).numpy()).view(mx.bfloat16))
+ else:
+ result.append(mx.array(host.numpy()))
+ return tuple(result)
+
+
+def to_torch(array, device):
+ """MLX array -> torch tensor; on MPS the DLPack capsule shares the buffer."""
+ import mlx.core as mx
+ import torch
+ mx.eval(array)
+ if str(device).startswith('mps'):
+ try:
+ # The capsule keeps the MLX array alive for the tensor's lifetime.
+ return torch.utils.dlpack.from_dlpack(array)
+ except (RuntimeError, TypeError, BufferError):
+ pass
+ if array.dtype == mx.bfloat16:
+ host = np.array(array.view(mx.int16), copy=False)
+ return torch.from_numpy(host).view(torch.bfloat16).to(device)
+ return torch.from_numpy(np.array(array, copy=False)).to(device)
+
+
+def window_attention(query, key, value, layout, bounds, scale, anchor_frames, *,
+ batch_bytes=1 << 29, stats=None):
+ """[S, H, d] torch tensors -> [S, H, d] on the query's device.
+
+ batch_bytes bounds the gathered keys plus values of one batched call; the
+ MLX kernel itself never materializes scores.
+ """
+ import mlx.core as mx
+ tick = time.perf_counter()
+ dense, windows = plan_ranges(layout, bounds, anchor_frames)
+ q, k, v = to_mlx_many((query, key, value)) # [S, H, d], imported
+ heads, dim = q.shape[1], q.shape[2]
+ qh, kh, vh = (mx.swapaxes(t, 0, 1) for t in (q, k, v)) # [H, S, d] views
+ imported = time.perf_counter()
+ pieces = []
+ for start, end in dense:
+ out = mx.fast.scaled_dot_product_attention(qh[None, :, start:end], kh[None], vh[None], scale=scale)
+ pieces.append((start, mx.swapaxes(out[0], 0, 1)))
+ shapes = {}
+ for (qa, qb), keys in windows:
+ shapes.setdefault((qb - qa, tuple(b - a for a, b in keys)), []).append(((qa, qb), keys))
+ for (length, key_lengths), members in shapes.items():
+ per_window = 2 * heads * sum(key_lengths) * dim * 2
+ count = max(1, min(len(members), batch_bytes // max(1, per_window)))
+ for begin in range(0, len(members), count):
+ chosen = members[begin:begin + count]
+ kb = mx.stack([mx.concatenate([kh[:, a:b] for a, b in keys], axis=1) for _, keys in chosen])
+ vb = mx.stack([mx.concatenate([vh[:, a:b] for a, b in keys], axis=1) for _, keys in chosen])
+ qb = mx.stack([qh[:, qa:qe] for (qa, qe), _ in chosen])
+ out = mx.fast.scaled_dot_product_attention(qb, kb, vb, scale=scale) # [B, H, L, d]
+ for index, ((qa, _), _) in enumerate(chosen):
+ pieces.append((qa, mx.swapaxes(out[index], 0, 1)))
+ # Bound live gathers: evaluate this batch before building the next.
+ mx.eval([p for _, p in pieces])
+ del kb, vb, qb, out
+ computed = time.perf_counter()
+ pieces.sort(key=lambda item: item[0])
+ result = mx.concatenate([p for _, p in pieces], axis=0) # [S, H, d]
+ output = to_torch(result, query.device)
+ if output.device != query.device or output.shape != query.shape or output.dtype != query.dtype:
+ raise ValueError('MLX attention output differs from its query geometry')
+ del q, k, v, qh, kh, vh, pieces, result
+ # Torch and MLX draw on one unified pool; do not let MLX keep freed buffers.
+ mx.clear_cache()
+ if stats is not None:
+ done = time.perf_counter()
+ stats['import_seconds'] = stats.get('import_seconds', 0.) + imported - tick
+ stats['attention_seconds'] = stats.get('attention_seconds', 0.) + computed - imported
+ stats['export_seconds'] = stats.get('export_seconds', 0.) + done - computed
+ return output
+
+
+class MLXWindowAttention:
+ """Drop-in for WindowAttention's call contract inside the native hybrid adapter."""
+
+ def __init__(self, *, batch_bytes=1 << 29):
+ self.batch_bytes = batch_bytes
+ self.calls = self.window_calls = 0
+ self.backend_calls = {'global_mlx': 0, 'window_mlx': 0}
+ self.stats = {}
+
+ def install(self, transformer):
+ from src.models.hybrid_transform import iter_hybrids
+ import types
+ policy = self
+
+ def window(attn, q, k, v, layout, bounds, scale, inference):
+ return policy(q, k, v, layout, bounds, scale, attn.anchor_frames)
+
+ count = 0
+ for attn in iter_hybrids(transformer):
+ attn._window_softmax = types.MethodType(window, attn)
+ count += 1
+ return count
+
+ def __call__(self, query, key, value, layout, bounds, scale, anchor_frames='none'):
+ self.calls += 1
+ self.window_calls += 1
+ self.backend_calls['window_mlx'] += 1
+ return window_attention(query, key, value, layout, bounds, scale, anchor_frames,
+ batch_bytes=self.batch_bytes, stats=self.stats)
diff --git a/freevideo_engine/backends/mps_modulation.py b/freevideo_engine/backends/mps_modulation.py
new file mode 100644
index 0000000..3ff611e
--- /dev/null
+++ b/freevideo_engine/backends/mps_modulation.py
@@ -0,0 +1,151 @@
+# Copyright 2026 The MiniMax and HuggingFace Teams. All rights reserved.
+# Copyright 2026 FreeVideo contributors.
+# Licensed under the Apache License, Version 2.0.
+# Block ordering follows the pinned Diffusers MiniMaxH3TransformerBlock.
+"""Metal indexed AdaLN arithmetic with the eager rounding boundaries.
+
+Keep RMSNorm and checked row indices in PyTorch. Select the small modulation
+table inside the fused kernel, avoiding full activation-sized gathered tables
+and arithmetic temporaries. The checked index selection has one scalar column.
+This module is used only by the explicit MPS block adapter.
+"""
+from functools import lru_cache
+import types
+
+IMPLEMENTATION = 'mps-indexed-rounded-modulation-v2'
+
+SOURCE = r'''
+#include <metal_stdlib>
+using namespace metal;
+#pragma clang fp contract(off)
+
+template <typename T>
+void modulate(device T* out, device const T* x, device const T* scale,
+ device const T* shift, device const long* indices,
+ constant uint* dims, uint i) {
+ uint width = dims[0], rows = dims[1], channel = i % width;
+ ulong row = ulong(indices[(i / width) % rows]);
+ ulong sj = row * dims[2] + channel * dims[3];
+ ulong bj = row * dims[4] + channel * dims[5];
+ T factor = T(1.f + float(scale[sj]));
+ T product = T(float(x[i]) * float(factor));
+ out[i] = T(float(product) + float(shift[bj]));
+}
+template <typename R, typename G, typename B, typename P, typename O>
+void post(device O* out, device const R* residual, device const G* gate,
+ device const B* branch, device const long* indices,
+ constant uint* dims, uint i) {
+ ulong row = ulong(indices[(i / dims[0]) % dims[1]]);
+ ulong j = row * dims[2] + (i % dims[0]) * dims[3];
+ P product = P(float(gate[j]) * float(branch[i]));
+ out[i] = O(float(residual[i]) + float(product));
+}
+#define MOD(NAME, T) \
+kernel void NAME(device T* o [[buffer(0)]], device const T* x [[buffer(1)]], \
+ device const T* s [[buffer(2)]], device const T* b [[buffer(3)]], \
+ device const long* ix [[buffer(4)]], constant uint* d [[buffer(5)]], \
+ uint i [[thread_position_in_grid]]) { modulate(o,x,s,b,ix,d,i); }
+#define POST(NAME, R, G, B, P, O) \
+kernel void NAME(device O* o [[buffer(0)]], device const R* x [[buffer(1)]], \
+ device const G* g [[buffer(2)]], device const B* b [[buffer(3)]], \
+ device const long* ix [[buffer(4)]], constant uint* d [[buffer(5)]], \
+ uint i [[thread_position_in_grid]]) { post<R,G,B,P,O>(o,x,g,b,ix,d,i); }
+MOD(modulate_bf16, bfloat)
+MOD(modulate_f32, float)
+POST(post_bbb, bfloat, bfloat, bfloat, bfloat, bfloat)
+POST(post_bbf, bfloat, bfloat, float, float, float)
+POST(post_bfb, bfloat, float, bfloat, float, float)
+POST(post_bff, bfloat, float, float, float, float)
+POST(post_fbb, float, bfloat, bfloat, bfloat, float)
+POST(post_fbf, float, bfloat, float, float, float)
+POST(post_ffb, float, float, bfloat, float, float)
+POST(post_fff, float, float, float, float, float)
+'''
+
+
+@lru_cache(maxsize=1)
+def _library():
+ import torch
+ try:
+ return torch.mps.compile_shader(SOURCE)
+ except RuntimeError:
+ return None
+
+
+def _eligible(value, *others, mixed=False):
+ import torch
+ return (value.device.type == 'mps' and value.dtype in (torch.bfloat16, torch.float32)
+ and value.ndim == 3 and value.numel() > 0 and value.numel() < 2**32
+ and value.is_contiguous() and not torch.is_grad_enabled()
+ and all(t.device == value.device and (t.dtype in (torch.bfloat16, torch.float32)
+ if mixed else t.dtype == value.dtype)
+ for t in others) and _library() is not None)
+
+
+def _checked_indices(table, indices):
+ """Preserve index_select bounds/dtype checks without gathering wide rows."""
+ import torch
+ return torch.arange(table.shape[0], device=table.device, dtype=torch.int64).index_select(0, indices)
+
+
+def _table_matches(value, table, indices):
+ return (table.ndim == 2 and table.shape[0] > 0 and table.shape[1] == value.shape[-1]
+ and indices.ndim == 1 and indices.numel() == value.shape[-2]
+ and indices.device == value.device and all(0 <= s < 2**31 for s in table.stride()))
+
+
+def modulate(value, scale, shift, indices, *, stats=None):
+ if (not _eligible(value, scale, shift) or scale.shape != shift.shape
+ or not _table_matches(value, scale, indices) or not _table_matches(value, shift, indices)):
+ return value * (1.0 + scale.index_select(0, indices)) + shift.index_select(0, indices)
+ import torch
+ checked = _checked_indices(scale, indices)
+ # Encode small constants directly; making an MPS tensor here introduces
+ # a host-to-device copy in every block's hot path.
+ dims = [value.shape[-1], value.shape[-2], *scale.stride(), *shift.stride()]
+ output = torch.empty_like(value)
+ kernel = _library().modulate_bf16 if value.dtype == torch.bfloat16 else _library().modulate_f32
+ kernel(output, value, scale, shift, checked, dims, threads=value.numel(), arg_casts={5: 'int32'})
+ if stats is not None:
+ stats['modulation_calls'] = stats.get('modulation_calls', 0) + 1
+ return output
+
+
+def residual_add(residual, gate, indices, branch, *, stats=None):
+ if (not _eligible(branch, residual, gate, mixed=True) or branch.shape != residual.shape
+ or not residual.is_contiguous() or not _table_matches(branch, gate, indices)):
+ return residual + gate.index_select(0, indices) * branch
+ import torch
+ checked = _checked_indices(gate, indices)
+ dims = [branch.shape[-1], branch.shape[-2], *gate.stride()]
+ dtype = torch.promote_types(residual.dtype, torch.promote_types(gate.dtype, branch.dtype))
+ output = torch.empty_like(branch, dtype=dtype)
+ suffix = ''.join('b' if t.dtype == torch.bfloat16 else 'f' for t in (residual, gate, branch))
+ kernel = getattr(_library(), 'post_' + suffix)
+ kernel(output, residual, gate, branch, checked, dims, threads=branch.numel(), arg_casts={5: 'int32'})
+ if stats is not None:
+ stats['residual_calls'] = stats.get('residual_calls', 0) + 1
+ return output
+
+
+def install(model):
+ """Install on this model's blocks only; preserve normalization, FF and attention."""
+ from diffusers.models.transformers.transformer_minimax_h3 import MiniMaxH3TransformerBlock
+ blocks = tuple(model.transformer_blocks)
+ if not blocks or any(not isinstance(block, MiniMaxH3TransformerBlock) for block in blocks):
+ raise TypeError('Expected pinned MiniMax H3 transformer blocks')
+ stats = dict(modulation_calls=0, residual_calls=0)
+
+ def forward(owner, hidden_states, temb, adaln_indices, rotary_emb, attention_mask=None):
+ shift_a, scale_a, gate_a, shift_f, scale_f, gate_f = owner.adaln_proj(temb)
+ value = modulate(owner.norm1(hidden_states), scale_a, shift_a, adaln_indices, stats=stats)
+ branch = owner.attn(value, rotary_emb, attention_mask)
+ del value
+ hidden = residual_add(hidden_states, gate_a, adaln_indices, branch, stats=stats)
+ del branch
+ value = modulate(owner.norm2(hidden), scale_f, shift_f, adaln_indices, stats=stats)
+ return residual_add(hidden, gate_f, adaln_indices, owner.ff(value), stats=stats)
+
+ for block in blocks:
+ block.forward = types.MethodType(forward, block)
+ return stats
diff --git a/freevideo_engine/backends/mps_nvfp4.py b/freevideo_engine/backends/mps_nvfp4.py
new file mode 100644
index 0000000..3f4b272
--- /dev/null
+++ b/freevideo_engine/backends/mps_nvfp4.py
@@ -0,0 +1,63 @@
+"""Decode native H3 NVFP4 weight storage into an MPS FP32 matrix.
+
+The encoder still runs its original FP32 projections and AWQ input smoothing.
+Only packed weight decoding moves to Metal; the CPU reader is the reference.
+"""
+from functools import lru_cache
+import os
+
+
+@lru_cache(maxsize=1)
+def _kernel():
+ import torch
+ return torch.mps.compile_shader('''
+ #include <metal_stdlib>
+ using namespace metal;
+ constant float e2m1[16] = {
+ 0.0f, 0.5f, 1.0f, 1.5f, 2.0f, 3.0f, 4.0f, 6.0f,
+ -0.0f, -0.5f, -1.0f, -1.5f, -2.0f, -3.0f, -4.0f, -6.0f
+ };
+ kernel void decode_nvfp4(device float* output,
+ device const uchar* packed,
+ device const float* block_scales,
+ device const float* tensor_scale,
+ uint index [[thread_position_in_grid]]) {
+ uchar byte = packed[index / 2];
+ uint code = (index & 1) ? (byte & 15) : (byte >> 4);
+ float block = e2m1[code] * block_scales[index / 16];
+ output[index] = block * tensor_scale[0];
+ }
+ ''')
+
+
+def decode_weight(weight, dtype, device):
+ """Match nvfp4_weight's nibble order, scale order and padded output view."""
+ import torch
+ from comfy_kitchen.float_utils import from_blocked
+ if torch.device(device).type != 'mps' or dtype != torch.float32:
+ raise ValueError('Metal NVFP4 decoding requires FP32 output on MPS')
+ # Torch 2.13 compiles shaders with safe math when this is unset or "0".
+ # Empty or other values enable fast math in its native implementation.
+ if os.environ.get('PYTORCH_MPS_FAST_MATH', '0') != '0':
+ raise ValueError('Metal NVFP4 decoding requires PYTORCH_MPS_FAST_MATH=0')
+ packed, params = weight._qdata, weight._params
+ if (packed.device.type != 'cpu' or packed.dtype != torch.uint8
+ or packed.ndim != 2 or not packed.is_contiguous()
+ or getattr(params, 'transposed', False)):
+ raise ValueError('Expected contiguous untransposed CPU NVFP4 storage')
+ rows, columns = packed.shape[0], packed.shape[1] * 2
+ original = tuple(params.orig_shape)
+ if (not rows or not columns or columns % 16 or params.scale.numel() != 1
+ or params.scale.device.type != 'cpu' or params.block_scale.device.type != 'cpu'
+ or len(original) != 2 or any(type(n) is not int or n < 1 for n in original)
+ or original[0] > rows or original[1] > columns):
+ raise ValueError('Invalid NVFP4 scale or original shape geometry')
+ # Unblocking the small scale plane is CPU work; the expanded weight never
+ # occupies a full CPU FP32 matrix. Preserve the reference's two multiplies.
+ scales = from_blocked(params.block_scale, num_rows=rows, num_cols=columns // 16).float()
+ result = torch.empty((rows, columns), dtype=dtype, device=device)
+ packed_device = packed.to(device)
+ scales_device = scales.contiguous().to(device)
+ tensor_scale = params.scale.float().reshape(-1).to(device)
+ _kernel().decode_nvfp4(result, packed_device, scales_device, tensor_scale)
+ return result[:original[0], :original[1]]
diff --git a/freevideo_engine/backends/mps_qk.py b/freevideo_engine/backends/mps_qk.py
new file mode 100644
index 0000000..d18d71a
--- /dev/null
+++ b/freevideo_engine/backends/mps_qk.py
@@ -0,0 +1,108 @@
+"""Q/K RMSNorm and H3 rotary embedding in one Metal pass per head row.
+
+The eager adapter normalizes and rotates in row chunks: about a dozen kernels
+and full reads/writes per chunk, 0.15 s of a first-pass block and 0.7 s of a
+full-resolution block on an M5. Here each threadgroup owns one token's head:
+FP32 sum of squares, the RMSNorm weight, rounding to BF16 where the reference
+stores the normalized row, then rotate-half over the leading rotary channels
+with BF16 cos/sin, as `_apply_rotary_emb` casts them.
+"""
+from functools import lru_cache
+
+SOURCE = r'''
+#include <metal_stdlib>
+using namespace metal;
+
+kernel void norm_rope(device bfloat* out [[buffer(0)]],
+ device const bfloat* x [[buffer(1)]],
+ device const bfloat* weight [[buffer(2)]],
+ device const bfloat* cos_table [[buffer(3)]],
+ device const bfloat* sin_table [[buffer(4)]],
+ constant int* dims [[buffer(5)]],
+ constant float* eps [[buffer(6)]],
+ uint group [[threadgroup_position_in_grid]],
+ uint lane [[thread_index_in_threadgroup]],
+ uint simd_lane [[thread_index_in_simdgroup]],
+ uint simd_id [[simdgroup_index_in_threadgroup]]) {
+ threadgroup float partial[32];
+ threadgroup float row[1024];
+ // dims: tokens, heads, head_dim, rotary_dim, row stride (elements) of x, head stride of x
+ const int heads = dims[1], head_dim = dims[2], rotary = dims[3];
+ const long token_stride = dims[4], head_stride = dims[5];
+ const int head = int(group) % heads;
+ const int token = int(group) / heads;
+ const int channel = int(lane);
+ const float value = float(x[long(token) * token_stride + long(head) * head_stride + channel]);
+ float square = simd_sum(value * value);
+ if (simd_lane == 0) partial[simd_id] = square;
+ threadgroup_barrier(mem_flags::mem_threadgroup);
+ float total = 0.f;
+ const int groups = (head_dim + 31) / 32;
+ for (int index = 0; index < groups; ++index) total += partial[index];
+ const float scale = rsqrt(total / float(head_dim) + eps[0]);
+ const float normed = float(bfloat(value * scale * float(weight[channel])));
+ row[channel] = normed;
+ threadgroup_barrier(mem_flags::mem_threadgroup);
+ float result = normed;
+ if (channel < rotary) {
+ const int half_width = rotary / 2;
+ const float rotated = channel < half_width ? -row[channel + half_width] : row[channel - half_width];
+ const float c = float(cos_table[long(token) * rotary + channel]);
+ const float s = float(sin_table[long(token) * rotary + channel]);
+ result = normed * c + rotated * s;
+ }
+ out[(long(token) * heads + head) * head_dim + channel] = bfloat(result);
+}
+'''
+
+
+@lru_cache(maxsize=1)
+def _library():
+ import torch
+ try:
+ return torch.mps.compile_shader(SOURCE)
+ except Exception: # Older Metal compilers lack bfloat; keep eager.
+ return None
+
+
+def available():
+ return _library() is not None
+
+
+def norm_rope(value, norm, rotary_emb):
+ """value [tokens, heads, head_dim] BF16 MPS (any token/head stride) -> contiguous result."""
+ import torch
+ tokens, heads, head_dim = value.shape
+ if value.stride(-1) != 1:
+ value = value.contiguous()
+ if rotary_emb is None:
+ cos = sin = value # The kernel does not read rotary tables when rotary=0.
+ rotary = 0
+ else:
+ cos, sin = (t.to(device=value.device, dtype=torch.bfloat16).contiguous() for t in rotary_emb)
+ rotary = cos.shape[-1]
+ if cos.shape != (tokens, rotary) or rotary > head_dim or rotary % 2:
+ raise ValueError('Rotary tables differ from the query/key rows')
+ weight = norm.weight.to(device=value.device, dtype=torch.bfloat16).contiguous()
+ out = torch.empty((tokens, heads, head_dim), dtype=torch.bfloat16, device=value.device)
+ dims = [tokens, heads, head_dim, rotary, value.stride(0), value.stride(1)]
+ eps = float(norm.eps if norm.eps is not None else torch.finfo(torch.float32).eps)
+ _library().norm_rope(out, value, weight, cos, sin, dims, eps,
+ threads=tokens * heads * head_dim, group_size=head_dim, arg_casts={5: 'int32'})
+ return out
+
+
+def prepare_qk(value, norm, rotary_emb, chunk, *, stats=None):
+ """Drop-in for mps_attention.prepare_qk on BF16 MPS rows; other inputs stay eager."""
+ import torch
+ from . import mps_attention
+ usable = (value.device.type == 'mps' and value.dtype == torch.bfloat16 and value.shape[-1] <= 1024
+ and isinstance(norm, torch.nn.RMSNorm) and norm.weight is not None
+ and not torch.is_grad_enabled() and available())
+ if not usable:
+ if stats is not None:
+ stats['reference_calls'] = stats.get('reference_calls', 0) + 1
+ return mps_attention.prepare_qk(value, norm, rotary_emb, chunk)
+ if stats is not None:
+ stats['metal_calls'] = stats.get('metal_calls', 0) + 1
+ return norm_rope(value, norm, rotary_emb)
diff --git a/freevideo_engine/backends/mps_vae.py b/freevideo_engine/backends/mps_vae.py
new file mode 100644
index 0000000..9ecfbf4
--- /dev/null
+++ b/freevideo_engine/backends/mps_vae.py
@@ -0,0 +1,72 @@
+"""H3 video decoder attention through MLX's fused Metal kernel on MPS.
+
+A decoder tile is 448 latent voxels plus five appended tokens, attended over
+with full self-attention by 32 heads of 64 channels. PyTorch's MPS kernel
+materializes each [32, 453, 453] score matrix; in a fixed default clip, MLX's
+fused kernel decoded 28 tiles in 32 s instead of 37 s. Projections, norms,
+RoPE and the residual path are the upstream processor's.
+"""
+
+
+def mlx_attention(query, key, value):
+ """[B, S, H, D] Torch FP16/BF16 MPS -> [B, S, H, D] on the same device."""
+ import mlx.core as mx
+ from .mps_mlx_attention import to_mlx_many, to_torch
+ # Reuse the strict shared-buffer import used by DiT attention. Prepare all
+ # strided inputs before one producer fence; DLPack retains their storage.
+ # Attention shapes, strides after swapaxes, scale and arithmetic stay fixed.
+ q, k, v = (mx.swapaxes(t, 1, 2) for t in to_mlx_many((query, key, value)))
+ out = mx.fast.scaled_dot_product_attention(q, k, v, scale=query.shape[-1] ** -.5)
+ return to_torch(mx.swapaxes(out, 1, 2), query.device)
+
+
+class MLXAttentionProcessor:
+ """MiniMaxH3VideoAttnProcessor at OpenVDN 30b6b380 with MLX's fused attention."""
+
+ def __call__(self, attn, hidden_states, rotary_emb=None):
+ import torch
+ query = attn.to_q(hidden_states).unflatten(2, (attn.heads, -1))
+ key = attn.to_k(hidden_states).unflatten(2, (attn.heads, -1))
+ value = attn.to_v(hidden_states).unflatten(2, (attn.heads, -1))
+
+ # The reference normalizes Q/K in float32 regardless of the compute dtype.
+ query = attn.norm_q(query.float()).to(query.dtype)
+ key = attn.norm_k(key.float()).to(key.dtype)
+
+ if rotary_emb is not None:
+ cos, sin = rotary_emb
+ cos = cos.to(query.dtype)
+ sin = sin.to(query.dtype)
+ rotary_dim = cos.shape[-1]
+ query_rotary, query_pass = query[..., :rotary_dim], query[..., rotary_dim:]
+ key_rotary, key_pass = key[..., :rotary_dim], key[..., rotary_dim:]
+ query_first, query_second = query_rotary.chunk(2, dim=-1)
+ key_first, key_second = key_rotary.chunk(2, dim=-1)
+ query_rotated = torch.cat([-query_second, query_first], dim=-1)
+ key_rotated = torch.cat([-key_second, key_first], dim=-1)
+ query = torch.cat([query_rotary * cos + query_rotated * sin, query_pass], dim=-1)
+ key = torch.cat([key_rotary * cos + key_rotated * sin, key_pass], dim=-1)
+
+ hidden_states = mlx_attention(query, key, value.to(query.dtype)).flatten(2, 3)
+ return attn.to_out[0](hidden_states)
+
+
+def install_mlx_attention(vae):
+ """Select optional MLX before execution; installed-backend failures stay visible."""
+ try:
+ import mlx.core as mx
+ except ModuleNotFoundError as error:
+ if error.name not in ('mlx', 'mlx.core'):
+ raise
+ return 0
+ # A broken native library, Metal initialization error or allocation failure
+ # must retain its cause rather than silently selecting different arithmetic.
+ mx.array([1.0])
+ from diffusers.models.autoencoders.autoencoder_kl_minimax_h3 import (
+ MiniMaxH3VideoAttention, MiniMaxH3VideoAttnProcessor)
+ modules = [module for module in vae.decoder.modules() if isinstance(module, MiniMaxH3VideoAttention)]
+ if any(type(module.processor) is not MiniMaxH3VideoAttnProcessor for module in modules):
+ raise ValueError('Unexpected H3 decoder attention processor')
+ for module in modules:
+ module.processor = MLXAttentionProcessor()
+ return len(modules)
diff --git a/freevideo_engine/backends/mps_vae_encode.py b/freevideo_engine/backends/mps_vae_encode.py
new file mode 100644
index 0000000..b4e5512
--- /dev/null
+++ b/freevideo_engine/backends/mps_vae_encode.py
@@ -0,0 +1,33 @@
+"""Bound the pending Metal work of the original FP32 input-video encoder."""
+from contextlib import contextmanager
+
+
+@contextmanager
+def bounded_encoder(model):
+ """Finish each convolution before submitting the next encoder operation.
+
+ MPS can retain large temporary allocations for pending 3D convolutions even
+ after their Python tensors are gone. Fencing the original operators bounds
+ that lifetime without changing weights, precision, tiles or posterior noise.
+ Hooks belong to this VAE instance and are always removed.
+ """
+ import torch
+ if torch.is_grad_enabled():
+ raise RuntimeError('Bounded MPS input encoding requires inference')
+ modules = [module for module in model.modules() if isinstance(module, torch.nn.Conv3d)]
+ if not modules:
+ raise ValueError('Expected the H3 input encoder convolution modules')
+ handles = []
+ stats = dict(policy='Complete original FP32 convolutions and release unused MPS allocations',
+ convolution_completions=0, convolution_modules=len(modules))
+ def complete(module, inputs, output):
+ torch.mps.synchronize()
+ torch.mps.empty_cache()
+ stats['convolution_completions'] += 1
+ try:
+ for module in modules:
+ handles.append(module.register_forward_hook(complete))
+ yield stats
+ finally:
+ for handle in handles:
+ handle.remove()
diff --git a/freevideo_engine/backends/mps_weights.py b/freevideo_engine/backends/mps_weights.py
new file mode 100644
index 0000000..5072595
--- /dev/null
+++ b/freevideo_engine/backends/mps_weights.py
@@ -0,0 +1,657 @@
+"""Bounded storage decoding and MPS layer residency.
+
+Hydrate one matrix from original storage with an explicit CPU or Metal decoder.
+Metal never receives float8 Torch tensors. No whole-model BF16 disk copy, locked
+host planes, CUDA streams or implicit CPU operator fallback are involved.
+"""
+import json
+import math
+import os
+import struct
+import time
+from concurrent.futures import ThreadPoolExecutor, wait
+from contextlib import ExitStack
+from pathlib import Path
+
+import torch
+
+from ..tensor_io import open_tensors
+
+_DTYPES = {'F8_E4M3': torch.float8_e4m3fn, 'BF16': torch.bfloat16, 'F16': torch.float16,
+ 'F32': torch.float32, 'F64': torch.float64, 'I64': torch.int64, 'I32': torch.int32,
+ 'I16': torch.int16, 'I8': torch.int8, 'U8': torch.uint8, 'BOOL': torch.bool}
+
+
+class HostTensors:
+ """One safetensors file read whole into host memory; tensors are views of it.
+
+The data section is read in parallel chunks: one synchronous read per tensor
+left the SSD at a fraction of its bandwidth. File reads release the GIL, so a
+background read overlaps the sampling thread's work. load_group binds device
+copies (or CPU clones), never these views.
+"""
+ def __init__(self, path, *, pool=None, chunk=8 << 20, max_bytes=512 << 20):
+ if (type(chunk) is not int or chunk <= 0 or
+ type(max_bytes) is not int or max_bytes <= 0):
+ raise ValueError('Prefetch needs positive chunk and buffer limits')
+ # Keep safetensors' shape, offset, overlap and payload validation. Reading
+ # ahead changes I/O scheduling, not which model files are accepted.
+ with open_tensors(path) as checked:
+ validated = {key: (checked.get_slice(key).get_shape(), checked.get_slice(key).get_dtype())
+ for key in checked.keys()}
+ with open(path, 'rb', buffering=0) as handle:
+ prefix = handle.read(8)
+ if len(prefix) != 8:
+ raise ValueError('Truncated prefetched tensor header')
+ length = struct.unpack('<Q', prefix)[0]
+ if not 2 <= length <= 16 << 20:
+ raise ValueError('Prefetched tensor header exceeds its bounded read')
+ header = json.loads(handle.read(length))
+ size = os.fstat(handle.fileno()).st_size
+ header.pop('__metadata__', None)
+ if set(header) != set(validated):
+ raise ValueError('Prepared tensor header changed during prefetch')
+ for key, info in header.items():
+ if info['dtype'] not in _DTYPES:
+ raise ValueError('Unsupported prepared tensor dtype: ' + key)
+ if (info['shape'], info['dtype']) != validated[key]:
+ raise ValueError('Prepared tensor metadata changed during prefetch: ' + key)
+ self.header, self.start = header, 8 + length
+ if not 0 <= size - self.start <= max_bytes:
+ raise ValueError('Prepared tensor file exceeds the prefetch buffer limit')
+ self.buffer = torch.empty(size - self.start, dtype=torch.uint8)
+ view = memoryview(self.buffer.numpy())
+ ranges = [(begin, min(begin + chunk, len(view))) for begin in range(0, len(view), chunk)]
+
+ def read(bounds):
+ begin, end = bounds
+ with open(path, 'rb', buffering=0) as source:
+ source.seek(self.start + begin)
+ while begin < end:
+ count = source.readinto(view[begin:end])
+ if not count:
+ raise OSError('Prepared tensor file ended early: ' + str(path))
+ begin += count
+ if pool is None or len(ranges) < 2:
+ for bounds in ranges:
+ read(bounds)
+ else:
+ futures = [pool.submit(read, bounds) for bounds in ranges]
+ try:
+ for future in futures:
+ future.result()
+ finally:
+ # A failed chunk must finish/cancel its siblings before a retry
+ # allocates another host buffer on the same reader pool.
+ for future in futures:
+ future.cancel()
+ wait(futures)
+
+ def keys(self):
+ return list(self.header)
+
+ def get_tensor(self, key):
+ info = self.header[key]
+ begin, end = info['data_offsets']
+ dtype = _DTYPES[info['dtype']]
+ raw = self.buffer[begin:end]
+ if begin % dtype.itemsize: # Element views need aligned storage offsets.
+ raw = raw.clone()
+ return raw.view(dtype).reshape(info['shape'])
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *args):
+ return False
+
+
+def attach_lora(module, index, cache, manifest):
+ """Bind shared eager LoRA forwards with unloaded, metadata-only factors.
+
+ The returned sidecar joins the layer's existing residency files. Factors
+ follow the same load/release hooks as the base weights on every sampling
+ step; attaching adapters does not retain a second model in unified memory.
+ """
+ from ..adaln_assets import asset_path, tensor_header
+ from ..lora_online import attach_block
+ online = manifest.get('online_lora', {})
+ if not online:
+ return None
+ if online.get('version') != 1:
+ raise ValueError('Unsupported native LoRA manifest version')
+ spec = online.get('blocks', {}).get(str(index))
+ if spec is None:
+ return None
+ path = asset_path(cache, spec['file'])
+ records = [row for row in manifest['groups'] if row['file'] == spec['file']]
+ if len(records) != 1 or path.stat().st_size != records[0]['bytes']:
+ raise ValueError('Incomplete native LoRA factor group')
+ header = tensor_header(path)
+ prefix = '' if index == 'root' else f'transformer_blocks.{index}.'
+ allowed = 'token_refiner.refiner_blocks.' if index == 'root' else prefix
+ dtypes = {'BF16': torch.bfloat16, 'F32': torch.float32}
+ values = {}
+ for name, row in header.items():
+ if row['dtype'] not in dtypes:
+ raise ValueError('Native LoRA factors require BF16 or FP32 storage')
+ values[name] = torch.empty(row['shape'], dtype=dtypes[row['dtype']], device='meta')
+ expected = set()
+ for name, patches in spec['modules'].items():
+ if not name.startswith(allowed) or not patches:
+ raise ValueError('Native LoRA target is outside its streamed layer')
+ layer = module.get_submodule(name.removeprefix(prefix))
+ if not isinstance(layer, torch.nn.Linear) or hasattr(layer, '_freevideo_lora'):
+ raise ValueError('Native LoRA requires an unpatched linear projection')
+ for number, patch in enumerate(patches):
+ scale, rank = patch['scale'], patch['rank']
+ if (type(scale) not in (int, float) or not math.isfinite(scale)
+ or type(rank) is not int or rank <= 0):
+ raise ValueError('Invalid native LoRA scale or rank')
+ key = name + '._freevideo_lora.' + str(number)
+ expected.update((key + '.a', key + '.b'))
+ if key + '.a' not in values or key + '.b' not in values:
+ raise ValueError('Native LoRA factor pair is incomplete')
+ a, b = values[key + '.a'], values[key + '.b']
+ dtype = manifest['linears'][name]['input_dtype']
+ if (a.shape != (rank, layer.in_features) or b.shape != (layer.out_features, rank)
+ or a.dtype != b.dtype or str(a.dtype).removeprefix('torch.') != dtype):
+ raise ValueError('Native LoRA factor shape or dtype differs from its projection')
+ if set(values) != expected:
+ raise ValueError('Native LoRA factor group includes unbound tensors')
+ # attach_block installs the same two eager matmuls used by the shared
+ # implementation. Its CUDA-only fused branch is never selected on MPS.
+ attach_block(module, index, Path(cache), manifest, lambda _: values, device='meta')
+ return path
+
+
+def decode_weight(weight, scale, dtype=torch.bfloat16):
+ if weight.device.type != 'cpu' or scale.device.type != 'cpu':
+ raise ValueError('MPS storage decoding requires CPU source tensors')
+ if weight.dtype != torch.float8_e4m3fn or weight.ndim != 2:
+ raise ValueError('Expected a two-dimensional E4M3 weight')
+ if scale.dtype != torch.float32 or scale.numel() not in (1, weight.shape[0]):
+ raise ValueError('Expected FP32 scalar or per-output-channel scales')
+ if dtype != torch.bfloat16:
+ raise ValueError('MPS weight-only execution requires explicit BF16 weights')
+ # This matches W8A16's E4M3 -> FP32, scale, then BF16 rounding order.
+ # A full FF matrix would otherwise create hundreds of MiB of FP32 scratch.
+ result = torch.empty(weight.shape, dtype=dtype, device='cpu')
+ rows = max(1, (16 * 2**20) // max(1, weight.shape[1] * 4))
+ scales = scale.reshape(-1, 1)
+ for begin in range(0, weight.shape[0], rows):
+ end = begin + rows
+ block = weight[begin:end].float()
+ block.mul_(scales if scales.numel() == 1 else scales[begin:end])
+ result[begin:end].copy_(block)
+ del block
+ return result
+
+
+def _bind(module, name, value):
+ parent, _, leaf = name.rpartition('.')
+ owner = module.get_submodule(parent) if parent else module
+ parameter = leaf in owner._parameters
+ if not parameter and leaf not in owner._buffers:
+ raise ValueError('Unexpected prepared weight: ' + name)
+ expected = getattr(owner, leaf)
+ # Hybrid modules are constructed in FP32 on meta; checkpoint assignment
+ # supplies their actual BF16/FP32 dtype, just as the shared CUDA loader does.
+ # The explicit VAE compute cache additionally binds FP16 Linear parameters.
+ # Int8 weights bind only where int8 storage was installed (an int8 placeholder).
+ floating = value.dtype in (torch.float16, torch.bfloat16, torch.float32)
+ if (expected is None or expected.shape != value.shape
+ or not (floating or value.dtype == expected.dtype == torch.int8)):
+ raise ValueError('Prepared weight shape/dtype changed: ' + name)
+ setattr(owner, leaf, torch.nn.Parameter(value, requires_grad=False) if parameter else value)
+
+
+def load_group(module, path, linears, *, prefix='', exclude=(), device='mps', decoder=None,
+ linear_dtype=None, handles=None):
+ """Bind only this module's tensors, one CPU matrix at a time.
+
+ handles optionally supplies already-read files (HostTensors), one per path."""
+ expected = {name for name, _ in list(module.named_parameters()) + list(module.named_buffers())
+ if not any(name.startswith(skip) for skip in exclude)}
+ loaded, total = set(), 0
+ paths = [path] if isinstance(path, (str, Path)) else list(path)
+ if handles is not None and len(handles) != len(paths):
+ raise ValueError('Prefetched tensors need one handle per shard')
+ # Views of a prefetched file must not outlive it as bound CPU parameters.
+ own_copy = handles is not None and torch.device(device).type == 'cpu'
+ with ExitStack() as stack:
+ sources = {}
+ for position, item in enumerate(paths):
+ handle = (handles[position] if handles is not None
+ else stack.enter_context(open_tensors(item)))
+ for key in handle.keys():
+ if key.startswith(prefix):
+ if key in sources:
+ raise ValueError('Duplicate prepared tensor across shards: ' + key)
+ sources[key] = handle
+ keys = set(sources)
+ for key in sorted(keys):
+ if not key.startswith(prefix):
+ continue
+ name = key[len(prefix):]
+ source = sources[key]
+ if any(name.startswith(skip) for skip in exclude):
+ continue
+ if key.endswith('.weight_scale'):
+ # Int8 storage keeps its row scales beside an int8 weight when
+ # the Linear runs int8 products; FP8 scales are consumed below.
+ if name not in expected or key.removesuffix('.weight_scale') + '.weight_int8' not in keys:
+ continue
+ value = source.get_tensor(key).reshape(-1).float()
+ elif key.endswith('.weight_int8'):
+ base = key.removesuffix('.weight_int8')
+ entry = linears.get(base)
+ if entry is None or entry.get('storage') != 'int8' or base + '.weight_scale' not in keys:
+ raise ValueError('Missing int8 weight metadata: ' + key)
+ value = source.get_tensor(key)
+ if list(value.shape) != entry['weight_shape'] or value.dtype != torch.int8:
+ raise ValueError('Int8 storage shape differs from its manifest: ' + key)
+ name = name.removesuffix('weight_int8') + 'weight'
+ if name.removesuffix('weight') + 'weight_scale' not in expected:
+ # Linears without int8 products get the dequantized BF16 matrix,
+ # rotated back when its rows were stored in the ConvRot basis.
+ # Macs without int8 TensorOps take every matrix this way, on the GPU.
+ scale = sources[base + '.weight_scale'].get_tensor(base + '.weight_scale').reshape(-1).float()
+ if entry.get('convrot_group') is not None and torch.device(device).type == 'mps':
+ from .mps_int8 import dequantize_convrot
+ value = dequantize_convrot(value.to(device), scale.to(device))
+ else:
+ value = value.float() * scale[:, None]
+ if entry.get('convrot_group') is not None:
+ from .mps_int8 import convrot_rotate
+ value = convrot_rotate(value, entry['convrot_group'])
+ value = value.to(torch.bfloat16)
+ del scale
+ elif key.endswith('.weight_fp8'):
+ base = key.removesuffix('.weight_fp8')
+ entry = linears.get(base)
+ if entry is None or entry['input_dtype'] != 'bfloat16' or base + '.weight_scale' not in keys:
+ raise ValueError('Missing FP8 weight metadata: ' + key)
+ weight = source.get_tensor(key)
+ scale = sources[base + '.weight_scale'].get_tensor(base + '.weight_scale')
+ if list(weight.shape) != entry['weight_shape'] or list(scale.shape) != entry['scale_shape']:
+ raise ValueError('FP8 storage shape differs from its manifest: ' + key)
+ value = (decoder or decode_weight)(weight, scale)
+ del weight, scale
+ name = name.removesuffix('weight_fp8') + 'weight'
+ else:
+ if name == 'original.bias':
+ name = 'bias'
+ elif '.original.bias' in name:
+ name = name.replace('.original.bias', '.bias')
+ value = source.get_tensor(key)
+ if name not in expected or name in loaded:
+ raise ValueError('Unexpected or duplicate prepared weight: ' + key)
+ if linear_dtype is not None:
+ parent, _, leaf = name.rpartition('.')
+ owner = module.get_submodule(parent) if parent else module
+ if isinstance(owner, torch.nn.Linear) and leaf in owner._parameters:
+ # The VAE reference loads FP32 then autocasts each Linear
+ # to FP16. Cache that cast; keep norms/scales in FP32.
+ value = value.float().to(linear_dtype)
+ total += value.numel() * value.element_size()
+ if own_copy and value.device.type == 'cpu':
+ value = value.clone()
+ _bind(module, name, value.to(device))
+ loaded.add(name)
+ del value
+ if loaded != expected:
+ raise ValueError('Incomplete prepared group: ' + ', '.join(sorted(expected - loaded)))
+ return total
+
+
+def release_group(module, *, exclude=()):
+ for name, value in list(module.named_parameters()) + list(module.named_buffers()):
+ if not any(name.startswith(skip) for skip in exclude):
+ _bind(module, name, torch.empty(value.shape, dtype=value.dtype, device='meta'))
+
+
+class LayerResidency:
+ """One streamed layer, optionally retaining a bounded fixed subset.
+
+Specs are (module, file, prefix, excluded names). All nonexcluded parameters
+must start as meta tensors. Progress observes actual completed layer forwards.
+Retention defaults to zero and requires an explicit working-memory reserve.
+Every retained layer is released when the owning context exits.
+"""
+ def __init__(self, specs, linears, backend, progress=None, decoder=None, *,
+ resident_bytes=0, working_reserve_bytes=0, linear_dtype=None, preload=False,
+ synchronize_layers=True, release_cache_every_layer=True, cache_floor_bytes=2 * 2**30,
+ prefetch=False, prefetch_threads=8, prefetch_bytes=512 << 20):
+ if (type(resident_bytes) is not int or resident_bytes < 0
+ or type(working_reserve_bytes) is not int or working_reserve_bytes < 0
+ or resident_bytes and not working_reserve_bytes):
+ raise ValueError('MPS retained weights need a nonnegative cap and positive working reserve')
+ if linear_dtype is not None and (linear_dtype != torch.float16 or linears):
+ raise ValueError('MPS Linear compute caching requires FP16 and original VAE storage')
+ if type(preload) is not bool or preload and linears:
+ raise ValueError('MPS preloading requires original VAE storage')
+ if (type(synchronize_layers) is not bool or type(release_cache_every_layer) is not bool
+ or type(cache_floor_bytes) is not int or cache_floor_bytes < 0):
+ raise ValueError('MPS streaming needs boolean fence/cache options and a nonnegative cache floor')
+ if type(prefetch) is not bool or prefetch and (preload or linear_dtype is not None
+ or type(prefetch_threads) is not int
+ or prefetch_threads < 1
+ or type(prefetch_bytes) is not int
+ or prefetch_bytes <= 0):
+ raise ValueError('MPS layer prefetching applies to sequential transformer streaming')
+ self.specs, self.linears, self.backend = list(specs), linears, backend
+ self.progress = progress
+ self.decoder = decoder
+ self.linear_dtype = linear_dtype
+ self.preload = preload
+ self.preloaded_layers = 0
+ self.handles = []
+ self.active = None
+ self.loads = self.bytes = self.peak_layer_bytes = 0
+ self.load_seconds = 0.
+ self.resident_limit, self.working_reserve = resident_bytes, working_reserve_bytes
+ self.synchronize_layers, self.release_cache_every_layer = synchronize_layers, release_cache_every_layer
+ self.cache_floor = cache_floor_bytes
+ self.retained = {}
+ self.retained_bytes = self.peak_retained_bytes = self.cache_hits = self.evictions = 0
+ self.deferred_cached_forwards = 0
+ self.active_bytes = 0
+ self.pending_work = False
+ # Sampling visits layers in a fixed cycle. While one layer computes, a
+ # reader thread fetches the next streamed layer's file into host memory
+ # (one file, about 0.43 GB for H3); the sampling thread then only
+ # copies and decodes. On an M5 the synchronous read was 0.15 s per
+ # layer, longer than a small request's whole layer forward.
+ self.prefetch, self.prefetch_threads = prefetch, prefetch_threads
+ self.prefetch_bytes = prefetch_bytes
+ self._prefetcher = self._readers = self._pending = None
+ self.prefetch_hits = self.prefetch_misses = 0
+ self.prefetch_wait_seconds = self.read_seconds = 0.
+
+ def _read(self, index):
+ _, path, _, _ = self.specs[index]
+ tick = time.monotonic()
+ paths = [path] if isinstance(path, (str, Path)) else list(path)
+ # Include every shard and LoRA sidecar in the one-layer host allowance.
+ # Oversized layers retain the original bounded per-tensor reader.
+ sizes = [Path(item).stat().st_size for item in paths]
+ if sum(sizes) > self.prefetch_bytes:
+ raise ValueError('Prepared layer exceeds the prefetch buffer limit')
+ handles = [HostTensors(item, pool=self._readers, max_bytes=size)
+ for item, size in zip(paths, sizes)]
+ self.read_seconds += time.monotonic() - tick
+ return handles
+
+ def _take(self, index):
+ pending, self._pending = self._pending, None
+ if pending is not None:
+ pending_index, future = pending
+ tick = time.monotonic()
+ try:
+ handles = future.result()
+ except Exception:
+ handles = None # Retried by the direct read below.
+ self.prefetch_wait_seconds += time.monotonic() - tick
+ if pending_index == index and handles is not None:
+ self.prefetch_hits += 1
+ return handles
+ del handles
+ self.prefetch_misses += 1
+ if self.backend.memory_info()[0] < self.prefetch_bytes + self.working_reserve:
+ return None
+ try:
+ return self._read(index)
+ except ValueError:
+ return None # Bounded reader handles larger layers or other dtypes.
+
+ def _schedule_after(self, index):
+ count = len(self.specs)
+ following = next(((index + step) % count for step in range(1, count)
+ if (index + step) % count not in self.retained), None)
+ if following is not None and self._prefetcher is not None:
+ if self.backend.memory_info()[0] >= self.prefetch_bytes + self.working_reserve:
+ self._pending = (following, self._prefetcher.submit(self._read, following))
+
+ def _load(self, index):
+ module, path, prefix, exclude = self.specs[index]
+ tick = time.monotonic()
+ self.pending_work = True
+ handles = self._take(index) if self._prefetcher is not None else None
+ size = load_group(module, path, self.linears, prefix=prefix, exclude=exclude,
+ device=self.backend.device, decoder=self.decoder, linear_dtype=self.linear_dtype,
+ handles=handles)
+ del handles
+ if self._prefetcher is not None:
+ # Queue the next read only after this layer's host copy is released:
+ # at most one prefetched layer is resident in host memory.
+ self._schedule_after(index)
+ self.load_seconds += time.monotonic() - tick
+ self.loads += 1
+ self.bytes += size
+ self.peak_layer_bytes = max(self.peak_layer_bytes, size)
+ return size
+
+ def _synchronize(self):
+ self.backend.synchronize()
+ self.pending_work = False
+
+ def _preload(self):
+ # Allocate retained weights together before temporary decoder workspaces
+ # exist. Keep that fixed set, reclaiming under pressure without refilling
+ # it during this decode. The next request makes a fresh live decision.
+ for index, (module, _, _, exclude) in enumerate(self.specs):
+ size = 0
+ for name, value in list(module.named_parameters()) + list(module.named_buffers()):
+ if any(name.startswith(skip) for skip in exclude):
+ continue
+ parent, _, leaf = name.rpartition('.')
+ owner = module.get_submodule(parent) if parent else module
+ cached = self.linear_dtype is not None and isinstance(owner, torch.nn.Linear) and leaf in owner._parameters
+ size += value.numel() * (2 if cached else value.element_size())
+ margin = max(self.working_reserve // 4, 2 * size)
+ if (self.retained_bytes + size > self.resident_limit or
+ self.backend.memory_info()[0] < self.working_reserve + margin + size):
+ break
+ self.active = index # close() also releases a partially loaded layer.
+ loaded = self._load(index)
+ self._synchronize()
+ if loaded != size:
+ raise ValueError('Preloaded MPS weight size differs from its original VAE metadata')
+ self.retained[index] = loaded
+ self.retained_bytes += loaded
+ self.peak_retained_bytes = max(self.peak_retained_bytes, self.retained_bytes)
+ self.preloaded_layers += 1
+ self.active = None
+ self.backend.empty_cache()
+
+ def _release(self, index):
+ module, _, _, exclude = self.specs[index]
+ release_group(module, exclude=exclude)
+ self.retained_bytes -= self.retained.pop(index, 0)
+
+ def _reclaim(self):
+ # Keep a fixed subset across the sequential layer cycle. An LRU cache
+ # smaller than that cycle would evict every layer before its next use.
+ # memory_info already subtracts the system reserve and allocator use.
+ if self.retained and self.backend.memory_info()[0] < self.working_reserve:
+ # Completed temporary allocations can still occupy driver heaps.
+ # Return those before deciding that useful weights must be evicted.
+ self._synchronize()
+ self.backend.empty_cache()
+ while self.retained and self.backend.memory_info()[0] < self.working_reserve:
+ self._release(next(reversed(self.retained)))
+ self.evictions += 1
+ self.backend.empty_cache()
+
+ def reconfigure(self, *, resident_bytes, working_reserve_bytes):
+ """Resize retained weights at a completed sampling-phase boundary.
+
+ Hooks and eligible tensors remain bound. Reduced capacity fences queued
+ work before dropping any weights; subsequent forwards can stream them
+ through the ordinary reader. This never changes precision or operators.
+ """
+ if (type(resident_bytes) is not int or resident_bytes < 0
+ or type(working_reserve_bytes) is not int or working_reserve_bytes < 0
+ or resident_bytes and not working_reserve_bytes):
+ raise ValueError('Retained weights require a nonnegative limit and positive working reserve')
+ if self.active is not None:
+ raise RuntimeError('Cannot reconfigure weights during a layer forward')
+ self.resident_limit, self.working_reserve = resident_bytes, working_reserve_bytes
+ if self.retained_bytes > resident_bytes:
+ self._synchronize()
+ while self.retained_bytes > resident_bytes:
+ self._release(next(reversed(self.retained)))
+ self.evictions += 1
+ self.backend.empty_cache()
+ self._reclaim()
+
+ def __enter__(self):
+ try:
+ for index, (module, path, prefix, exclude) in enumerate(self.specs):
+ if any(not value.is_meta for name, value in module.named_parameters()
+ if not any(name.startswith(skip) for skip in exclude)):
+ raise ValueError('MPS streamed parameters must start unloaded')
+ def before(layer, args, index=index):
+ if self.active is not None:
+ raise RuntimeError('MPS streamed layers cannot overlap')
+ if self.resident_limit:
+ self._reclaim()
+ self.active = index
+ self.pending_work = True
+ if index in self.retained:
+ self.active_bytes = self.retained[index]
+ self.cache_hits += 1
+ return
+ self.active_bytes = self._load(index)
+ def after(layer, args, output, index=index):
+ if self.active != index:
+ return
+ # Preloaded weights remain alive on the same MPS stream.
+ # With spare working space and no completion callback,
+ # queue their next use without a per-layer host barrier.
+ # Reclamation, failed forwards and close() still fence
+ # before releasing weights; ordinary streaming is unchanged.
+ if (output is not None and self.preload and index in self.retained
+ and self.progress is None
+ and self.backend.memory_info()[0] >= self.working_reserve):
+ self.deferred_cached_forwards += 1
+ self.active = None
+ self.active_bytes = 0
+ return
+ keep = False
+ try:
+ # One MPS queue orders a release before any reuse, so
+ # streaming needs no host barrier here; syncing kept the
+ # next layer's read from overlapping this layer's compute.
+ # The default keeps the measured fence for retention
+ # decisions; fast sampling decides from the unfenced live
+ # reading, which the admission margin below absorbs.
+ if self.synchronize_layers or output is None or self.progress is not None:
+ self._synchronize()
+ cached = index in self.retained
+ additional = 0 if cached else self.active_bytes
+ if self.resident_limit and self.synchronize_layers:
+ self.backend.empty_cache()
+ # Admit new weights with extra space between the fill
+ # and eviction thresholds. Without that gap, ordinary
+ # layer workspace fluctuations refill and evict the
+ # same subset throughout every decoder tile.
+ margin = 0 if cached else max(self.working_reserve // 4, 2 * self.active_bytes)
+ if (output is not None and self.resident_limit
+ and (cached or not self.preload)
+ and self.retained_bytes + additional <= self.resident_limit
+ and self.backend.memory_info()[0] >= self.working_reserve + margin):
+ self.retained[index] = self.active_bytes
+ self.retained_bytes += additional
+ self.peak_retained_bytes = max(self.peak_retained_bytes, self.retained_bytes)
+ keep = True
+ finally:
+ if not keep:
+ if index in self.retained and output is not None:
+ self.evictions += 1
+ self._release(index)
+ self.active = None
+ self.active_bytes = 0
+ # Returning cached buffers costs a reallocation per layer;
+ # streaming does it only when the live allowance is short.
+ if not keep and (self.release_cache_every_layer
+ or self.backend.memory_info()[0] < self.cache_floor):
+ self.backend.empty_cache()
+ if output is not None and self.progress is not None:
+ self.progress(index)
+ self.handles.extend((module.register_forward_pre_hook(before),
+ module.register_forward_hook(after, always_call=True)))
+ if self.preload and self.resident_limit:
+ self._preload()
+ if self.prefetch:
+ self._readers = ThreadPoolExecutor(self.prefetch_threads, thread_name_prefix='freevideo-read')
+ self._prefetcher = ThreadPoolExecutor(1, thread_name_prefix='freevideo-prefetch')
+ self._schedule_after(-1)
+ return self
+ except BaseException:
+ self.close()
+ raise
+
+ def close(self):
+ for handle in self.handles:
+ handle.remove()
+ self.handles.clear()
+ # The read after the last layer is never used; wait for it, then drop it.
+ self._pending = None
+ for pool in (self._prefetcher, self._readers):
+ if pool is not None:
+ pool.shutdown(wait=True, cancel_futures=True)
+ self._prefetcher = self._readers = None
+ remaining = set(self.retained)
+ if self.active is not None:
+ remaining.add(self.active)
+ if remaining or self.pending_work:
+ try:
+ self._synchronize()
+ finally:
+ for index in sorted(remaining):
+ self._release(index)
+ self.active = None
+ self.active_bytes = 0
+ self.backend.empty_cache()
+
+ def __exit__(self, *args):
+ self.close()
+
+ def stats(self):
+ value = dict(layer_loads=self.loads, hydrated_weight_bytes=self.bytes,
+ largest_layer_bytes=self.peak_layer_bytes, load_seconds=self.load_seconds,
+ load_seconds_scope='Host read/submit time; device completion is included in each sampling step',
+ policy='one synchronous MPS layer; original storage decoded per tensor',
+ fp8_storage=bool(self.linears),
+ fp8_decode_device='mps' if self.decoder is not None else 'cpu',
+ retains_bf16_disk_copy=False,
+ layer_synchronization=('per-layer' if self.synchronize_layers else
+ 'completion callbacks, errors, reclamation and context exit'),
+ cache_release_policy=('per streamed layer' if self.release_cache_every_layer else
+ 'low headroom and context exit'))
+ if not self.synchronize_layers:
+ value['policy'] = 'one queued MPS layer; original storage decoded per tensor'
+ if self.resident_limit or self.peak_retained_bytes or self.cache_hits or self.evictions:
+ value.update(policy=('bounded retained MPS layers with ' +
+ ('synchronous' if self.synchronize_layers else 'queued') +
+ ' streaming and live headroom reclamation'),
+ resident_limit_bytes=self.resident_limit, working_reserve_bytes=self.working_reserve,
+ retained_weight_bytes=self.retained_bytes, peak_retained_weight_bytes=self.peak_retained_bytes,
+ retained_layer_hits=self.cache_hits, retained_layer_evictions=self.evictions)
+ if self.linear_dtype is not None:
+ value['linear_compute_cache'] = 'FP16 Linear weights; original norm/scale storage'
+ if self.prefetch:
+ value.update(prefetch=dict(hits=self.prefetch_hits, misses=self.prefetch_misses,
+ wait_seconds=self.prefetch_wait_seconds, read_seconds=self.read_seconds,
+ threads=self.prefetch_threads,
+ buffer_limit_bytes=self.prefetch_bytes,
+ scope='Next streamed layer read on a host thread; one layer in flight'))
+ if self.preload:
+ value.update(preloaded_layers=self.preloaded_layers,
+ deferred_cached_forwards=self.deferred_cached_forwards,
+ retention_admission='fixed before first forward; pressure may only shrink it')
+ return value
diff --git a/freevideo_engine/bootstrap.py b/freevideo_engine/bootstrap.py
index f3da034..0dccfc8 100644
--- a/freevideo_engine/bootstrap.py
+++ b/freevideo_engine/bootstrap.py
@@ -123,6 +123,9 @@ def dependency_status(root, layout='unified', system=None):
"""Inspect distribution metadata only: no tensor imports or downloads."""
result = {}
system = system or platform.system()
+ if system == 'Darwin':
+ from .macos_bootstrap import dependency_status as native_status
+ return native_status(root)
packages = {
'engine': ['torch', 'torchvision', 'triton', 'transformers', 'accelerate', 'peft', 'safetensors',
'huggingface-hub', 'omegaconf', 'pyyaml', 'einops', 'numpy', 'pillow', 'av',
@@ -201,6 +204,11 @@ def existing_parent(path):
return path
+def prepared_precision(prepared):
+ """Display name of a prepared model's weight format (Macs use the ConvRot int8 export)."""
+ return 'ConvRot int8' if (prepared or {}).get('scale_granularity') == 'int8_convrot' else 'FP8'
+
+
def model_target(row, model_dir, encoder_dir, prepared_dir=None):
if row.get('role') == 'latent_upscaler':
return model_dir / 'latent_upscaler' / Path(row['file']).name
@@ -225,34 +233,44 @@ def plan(args, *, local_progress=None):
keep_limits = getattr(args, 'keep_resource_limits', False)
vram_gib = args.vram_gib if args.vram_gib is not None else saved.get('vram_gib') if keep_limits else None
ram_gib = args.ram_gib if args.ram_gib is not None else saved.get('ram_gib') if keep_limits else None
- if not args.hardware_json and (platform.system() not in ('Linux', 'Windows') or platform.machine().lower() not in ('x86_64', 'amd64')):
- raise RuntimeError('One-click setup supports Linux x86_64 and native Windows x64.')
- snapshot = json.loads(args.hardware_json.read_text(encoding='utf-8')) if args.hardware_json else inventory(args.gpu)
- hardware = Hardware.from_dict(snapshot['hardware'])
- errors = []
- if snapshot.get('machine', '').lower() not in ('x86_64', 'amd64') or hardware.system not in ('Linux', 'Windows'):
- errors.append('This installer supports Linux x86_64 and native Windows x64.')
- windows_target = hardware.system == 'Windows'
- if windows_target and layout != 'unified':
- errors.append('Native Windows uses the unified environment. Rerun with --environment unified.')
- layout = 'unified'
- if windows_target and getattr(args, 'rebuild_sage', False):
- errors.append('Windows uses the pinned, verified Sage2 wheel; --rebuild-sage is a Linux source-build option.')
- if int(snapshot['selected_gpu']['driver_version'].split('.')[0]) < 580:
- errors.append('NVIDIA driver 580 or newer is required by the pinned CUDA 13 encoder; update the driver first.')
- if hardware.capability not in ((8, 0), (8, 6), (8, 9), (9, 0), (12, 0)):
- errors.append('The one-click profiles currently target SM80/86, SM89, SM90 and SM120.')
- for name in () if windows_target else ('git', 'compiler'):
- if not snapshot.get(name):
- errors.append('Missing %s. Run ./setup.sh interactively to install basic tools, then review the engine plan.' % name)
- if not args.hardware_json and not shutil.which('curl'):
- errors.append('Missing curl for bounded downloads and HTTP/SOCKS proxy support. Run ./setup.sh to install it.')
- resources = None
- try:
- resources = resource_budget(hardware, vram_gib=vram_gib, ram_gib=ram_gib)
- resources['ram_budget_bytes'] = max(0, resources['ram_budget_bytes'])
- except ValueError as error:
- errors.append(str(error))
+ fixture = json.loads(args.hardware_json.read_text(encoding='utf-8')) if args.hardware_json else None
+ mac_target = (fixture or {}).get('hardware', {}).get('system', platform.system()) == 'Darwin'
+ if mac_target:
+ from .macos_bootstrap import preflight
+ snapshot, resources, errors = preflight(args, fixture, ram_gib=ram_gib, vram_gib=vram_gib)
+ system, windows_target, layout = 'Darwin', False, 'unified'
+ cache_format = dict(capability=None, scale_granularity='int8_convrot')
+ else:
+ if not args.hardware_json and (platform.system() not in ('Linux', 'Windows') or platform.machine().lower() not in ('x86_64', 'amd64')):
+ raise RuntimeError('One-click setup supports Linux x86_64 and native Windows x64.')
+ snapshot = json.loads(args.hardware_json.read_text(encoding='utf-8')) if args.hardware_json else inventory(args.gpu)
+ hardware = Hardware.from_dict(snapshot['hardware'])
+ errors = []
+ if snapshot.get('machine', '').lower() not in ('x86_64', 'amd64') or hardware.system not in ('Linux', 'Windows'):
+ errors.append('This installer supports Linux x86_64 and native Windows x64.')
+ windows_target = hardware.system == 'Windows'
+ if windows_target and layout != 'unified':
+ errors.append('Native Windows uses the unified environment. Rerun with --environment unified.')
+ layout = 'unified'
+ if windows_target and getattr(args, 'rebuild_sage', False):
+ errors.append('Windows uses the pinned, verified Sage2 wheel; --rebuild-sage is a Linux source-build option.')
+ if int(snapshot['selected_gpu']['driver_version'].split('.')[0]) < 580:
+ errors.append('NVIDIA driver 580 or newer is required by the pinned CUDA 13 encoder; update the driver first.')
+ if hardware.capability not in ((8, 0), (8, 6), (8, 9), (9, 0), (12, 0)):
+ errors.append('The one-click profiles currently target SM80/86, SM89, SM90 and SM120.')
+ for name in () if windows_target else ('git', 'compiler'):
+ if not snapshot.get(name):
+ errors.append('Missing %s. Run ./setup.sh interactively to install basic tools, then review the engine plan.' % name)
+ if not args.hardware_json and not shutil.which('curl'):
+ errors.append('Missing curl for bounded downloads and HTTP/SOCKS proxy support. Run ./setup.sh to install it.')
+ resources = None
+ try:
+ resources = resource_budget(hardware, vram_gib=vram_gib, ram_gib=ram_gib)
+ resources['ram_budget_bytes'] = max(0, resources['ram_budget_bytes'])
+ except ValueError as error:
+ errors.append(str(error))
+ system = hardware.system
+ cache_format = dict(capability=hardware.capability)
model_dir = Path(args.models or saved.get('model_root') or root / 'models' / 'vdn').expanduser().resolve()
encoder_dir = Path(args.encoder_models or saved.get('encoder_model_root') or prior.get('encoder_dir') or root / 'models' / 'encoder').expanduser().resolve()
reuse_cache = args.cache.expanduser().resolve() if args.cache else None
@@ -263,18 +281,20 @@ def plan(args, *, local_progress=None):
if cache_record.is_file():
record = json.loads(cache_record.read_text(encoding='utf-8'))
candidate = record.get('cache')
- if record.get('model_revision') == revision and candidate and cache_compatible(candidate, hardware.capability):
+ if record.get('model_revision') == revision and candidate and cache_compatible(candidate, **cache_format):
reuse_cache = Path(candidate)
break
if reuse_cache is None and not getattr(args, 'rebuild_cache', False):
from .install_tuning import discover_prepared
- reuse_cache = discover_prepared(getattr(args, 'reuse_models', None), hardware.capability)
+ reuse_cache = discover_prepared(getattr(args, 'reuse_models', None), **cache_format)
from . import prepared_model
prepared = None
model_source = getattr(args, 'model_source', 'prepared')
if reuse_cache is None and not getattr(args, 'rebuild_cache', False) and model_source == 'prepared':
- prepared = prepared_model.select(hardware.capability, root)
+ prepared = prepared_model.select(root=root, **cache_format)
prepared_dir = prepared['directory'] if prepared else None
+ if mac_target and reuse_cache is None and prepared is None:
+ errors.append('No verified native-compatible prepared model is available. Source conversion is not supported on Mac.')
files = required_models(json.loads((PACKAGE / 'model_files.json').read_text(encoding='utf-8')), reuse_cache or prepared)
files += prepared_model.files(prepared)
local_reuse = None
@@ -326,7 +346,7 @@ def plan(args, *, local_progress=None):
# Stream directly into final FP8 groups. The pinned model occupies ~45.3
# GiB; allow 52 GiB including the largest group in progress. Never credit
# future source deletion toward the space needed to complete conversion.
- dependencies = dependency_status(root, layout, hardware.system)
+ dependencies = dependency_status(root, layout, system)
environments_ready = all(r['exists'] and not r['missing'] and not r['mismatched'] for r in dependencies.values())
extra = (0 if reuse_cache or prepared else 52) + (5 if environments_ready else 30 if layout == 'unified' else 45) + 10
frontend = None
@@ -343,11 +363,11 @@ def plan(args, *, local_progress=None):
keep_extreme=reviewed.get('disk_mode') == 'extreme')
extra = disk_plan['environment_cache_safety_gib']
errors.extend(disk_plan['errors'])
- if reuse_cache and not cache_compatible(reuse_cache, hardware.capability):
+ if reuse_cache and not cache_compatible(reuse_cache, **cache_format):
errors.append('--cache must contain a prepared FP8 cache compatible with this GPU scale format.')
from .download_settings import read as download_preferences
networking = network.plan(json.loads((PACKAGE / 'dependencies.json').read_text(encoding='utf-8')),
- bootstrap_versions(json.loads((PACKAGE / 'bootstrap_versions.json').read_text(encoding='utf-8')), hardware.system), layout,
+ bootstrap_versions(json.loads((PACKAGE / 'bootstrap_versions.json').read_text(encoding='utf-8')), system), layout,
mode=getattr(args, 'network', 'auto'), timeout=getattr(args, 'network_timeout', 5),
offline=bool(args.hardware_json or errors),
proxy_mode=download_preferences(root / 'download-settings.json')['proxy_mode'])
@@ -361,16 +381,17 @@ def plan(args, *, local_progress=None):
if error:
errors.append(error)
from .model_transfer import policy as transfer_policy
- build = build_parallelism(resources['ram_budget_bytes'], snapshot.get('cpu_threads') or 1) if resources and not windows_target else None
+ build = build_parallelism(resources['ram_budget_bytes'], snapshot.get('cpu_threads') or 1) if resources and not windows_target and not mac_target else None
transfers = transfer_policy(resources['ram_budget_bytes'], build['estimated_peak_bytes'] if build else 0) if resources else None
if disk_plan['mode'] == 'extreme':
transfers = dict(transfers or {}, file_workers=1, overlap_build=False, mode='streaming-space-saver')
from .model_status import inventory as model_inventory
- return {'schema_version': 1, 'engine_version': __version__, 'root': str(root), 'inventory': snapshot, 'policy_estimate': None,
+ value = {'schema_version': 1, 'engine_version': __version__, 'root': str(root), 'inventory': snapshot, 'policy_estimate': None,
'installation_resources': resources,
'storage': storage,
'disk_mode': disk_plan['mode'], 'disk_policy': disk_plan, 'frontend': frontend,
- 'storage_preparation': ('Download verified slim FP8 weights and fixed AdaLN tables; no original transformer or local conversion'
+ 'storage_preparation': ('Download verified slim %s weights and fixed AdaLN tables; no original transformer or local conversion'
+ % prepared_precision(prepared)
if prepared else 'Stream CPU merge directly to FP8 groups; no complete BF16 intermediate cache'),
'storage_cleanup': ('After cache verification and GPU probes, remove only unchanged conversion-only weights downloaded/copied into this installation; borrowed originals and outputs are retained'
if storage == 'compact' else 'Retain original conversion weights for future re-quantization'),
@@ -416,6 +437,11 @@ def plan(args, *, local_progress=None):
'licenses': ['https://huggingface.co/OpenVDN/vdn-minimax-h3/blob/751739ee5b9e3ac802dca5d5111075fdaeb47885/LICENSE',
'https://huggingface.co/t8star/Vdn-Minimax-H3-Comfy',
'https://docs.nvidia.com/cuda/eula/index.html']}
+ if mac_target:
+ from .macos_bootstrap import describe_plan
+ describe_plan(value)
+ return value
+
def display(value, ui=None, *, verbose=False):
@@ -424,10 +450,13 @@ def display(value, ui=None, *, verbose=False):
return display_details(value, ui)
h = value['inventory']['hardware']
usable_ram = min(h['ram_total'], h.get('cgroup_ram_limit') or h['ram_total'])
- rows = [('GPU', '%s · %.1f GiB / %.1f GiB free' % (h['gpu_name'], h['vram_total']/GiB, h['vram_free']/GiB)),
- ('RAM', '%.1f GiB / %.1f GiB available%s' % (usable_ram/GiB, min(usable_ram, h['ram_available'])/GiB,
- ' · container limit' if usable_ram < h['ram_total'] else '')),
- ('Install in', value['root']),
+ rows = ([('GPU', h['gpu_name'] + ' · MPS'),
+ ('Unified memory', '%.1f GiB / %.1f GiB available' % (h['ram_total']/GiB, h['ram_available']/GiB))]
+ if value.get('device_backend') == 'mps' else
+ [('GPU', '%s · %.1f GiB / %.1f GiB free' % (h['gpu_name'], h['vram_total']/GiB, h['vram_free']/GiB)),
+ ('RAM', '%.1f GiB / %.1f GiB available%s' % (usable_ram/GiB, min(usable_ram, h['ram_available'])/GiB,
+ ' · container limit' if usable_ram < h['ram_total'] else ''))])
+ rows += [('Install in', value['root']),
('Environment', 'One shared Python environment · missing dependencies installed automatically'
if value['environment_layout'] == 'unified' else 'Two separate Python environments · keeping your selected layout')]
for key, default, label in (('model_dir', 'vdn', 'Model directory'), ('encoder_dir', 'encoder', 'Encoder directory')):
@@ -447,7 +476,7 @@ def display(value, ui=None, *, verbose=False):
label = 'Peak disk space' if len(value['disks']) == 1 else 'Disk ' + disk['paths'][0]
rows.append((label, '~%.1f GiB additional needed · %.1f GiB free' % (disk['needed_bytes']/GiB, disk['free_bytes']/GiB)))
prepared = value.get('prepared_model')
- rows.append(('Storage', 'Download slim FP8 model · no local conversion' if prepared else
+ rows.append(('Storage', 'Download slim %s model · no local conversion' % prepared_precision(prepared) if prepared else
'Reuse prepared FP8 cache' if value['reuse_cache'] else 'Prepare compact FP8 model'))
if prepared:
rows.append(('Prepared model', prepared['repo'] + ' · ' + prepared['scale_granularity'] +
@@ -457,7 +486,7 @@ def display(value, ui=None, *, verbose=False):
rows.append(('Original weights', 'Not downloaded; fixed AdaLN tables included' if prepared else
'Remove verified conversion inputs downloaded/copied here; keep borrowed originals'
if value.get('storage', 'compact') == 'compact' else 'Keep original weights for future conversion'))
- setup_ram = 'Bounded model verification; no FP8 conversion' if prepared else 'About 4–8 GiB for model preparation'
+ setup_ram = 'Bounded model verification; no local conversion' if prepared else 'About 4–8 GiB for model preparation'
if value.get('build'):
setup_ram += ' · up to ~%.1f GiB for compilation' % (value['build']['estimated_peak_bytes']/GiB)
rows.append(('Setup RAM', setup_ram))
@@ -485,7 +514,8 @@ def display(value, ui=None, *, verbose=False):
+ (' · compare proxy / direct' if networking.get('proxy_configured') or networking.get('git_proxy_configured') else '')))
ui.panel('FreeVideo / ' + h['system'] + ' setup', rows)
ui.write('Space and memory are estimates. Setup checks your GPU before marking it ready.\n')
- ui.write('Model / toolkit licenses: MiniMax H3, H3 text encoder, NVIDIA CUDA.\n')
+ ui.write('Model licenses: MiniMax H3, H3 text encoder.\n' if value.get('device_backend') == 'mps' else
+ 'Model / toolkit licenses: MiniMax H3, H3 text encoder, NVIDIA CUDA.\n')
ui.write('Use --verbose for full details and license links, or enter d at confirmation.\n')
for error in value['errors']:
ui.write('BLOCKED: ' + str(error) + '\n')
@@ -494,9 +524,12 @@ def display(value, ui=None, *, verbose=False):
def display_details(value, ui=None):
ui = ui or TerminalUI('Setup')
h = value['inventory']['hardware']
- rows = [('GPU', '%s · SM %s' % (h['gpu_name'], '.'.join(map(str, h['capability'])))),
- ('VRAM', '%.2f GiB total / %.2f GiB free' % (h['vram_total']/GiB, h['vram_free']/GiB)),
- ('RAM', '%.2f GiB total / %.2f GiB available' % (h['ram_total']/GiB, h['ram_available']/GiB))]
+ rows = ([('GPU', h['gpu_name'] + ' · MPS'),
+ ('Unified memory', '%.2f GiB total / %.2f GiB available' % (h['ram_total']/GiB, h['ram_available']/GiB))]
+ if value.get('device_backend') == 'mps' else
+ [('GPU', '%s · SM %s' % (h['gpu_name'], '.'.join(map(str, h['capability'])))),
+ ('VRAM', '%.2f GiB total / %.2f GiB free' % (h['vram_total']/GiB, h['vram_free']/GiB)),
+ ('RAM', '%.2f GiB total / %.2f GiB available' % (h['ram_total']/GiB, h['ram_available']/GiB))])
limits = [value.get(key) for key in ('vram_gib', 'ram_gib')]
rows.append(('Resources', 'Automatic · current available VRAM/RAM' if all(v is None for v in limits)
else 'Capacity limits · VRAM %s / RAM %s' % tuple('auto' if v is None else '%g GiB' % v for v in limits)))
@@ -558,7 +591,11 @@ def confirmed(args, value, ask=input, ui=None):
reviewed = json.loads(Path(reviewed_path).read_text(encoding='utf-8'))
keys = ('root', 'engine_version', 'environment_layout', 'model_dir', 'encoder_dir', 'vram_gib', 'ram_gib', 'reuse_cache', 'storage', 'storage_cleanup', 'model_downloader', 'prepared_model', 'model_source', 'disk_mode', 'frontend')
changed = any(reviewed.get(key) != value.get(key) for key in keys)
- changed |= reviewed.get('inventory', {}).get('selected_gpu', {}).get('uuid') != value['inventory']['selected_gpu']['uuid']
+ changed |= reviewed.get('device_backend') != value.get('device_backend')
+ if value.get('device_backend') == 'mps':
+ changed |= reviewed.get('inventory', {}).get('selected_device') != value['inventory']['selected_device']
+ else:
+ changed |= reviewed.get('inventory', {}).get('selected_gpu', {}).get('uuid') != value['inventory']['selected_gpu']['uuid']
changed |= value['model_download_bytes'] > reviewed.get('model_download_bytes', -1)
changed |= bool(reviewed.get('allow_model_restart')) != bool(value.get('allow_model_restart'))
for key in ('root', 'roots', 'copy_mode', 'copy_bytes'):
@@ -730,18 +767,13 @@ class Installer:
FREEVIDEO_COMFY_PYTHON=str(self.pythons['encoder']),
FREEVIDEO_LOCK_PATH=lock_path,
PATH=str(self.pythons['engine'].parent) + os.pathsep + os.environ.get('PATH', ''),
- CUDA_VISIBLE_DEVICES=value['inventory']['selected_gpu']['uuid'],
UV_CACHE_DIR=str(self.root / 'downloads' / 'uv-cache'),
UV_PYTHON_INSTALL_DIR=str(self.root / 'python'), UV_LINK_MODE='hardlink',
HF_HOME=str(self.root / 'downloads' / 'huggingface'), HF_HUB_DISABLE_TELEMETRY='1',
- TRITON_CACHE_DIR=str(self.root / 'kernel-cache' / 'triton'),
- CUDA_CACHE_PATH=str(self.root / 'kernel-cache' / 'cuda'),
- TORCHINDUCTOR_CACHE_DIR=str(self.root / 'kernel-cache' / 'inductor'),
HF_HUB_OFFLINE='0', TRANSFORMERS_OFFLINE='0',
PIP_DISABLE_PIP_VERSION_CHECK='1',
PYTHONUNBUFFERED='1', PYTHONUTF8='1', PYTHONIOENCODING='utf-8', PYTHONPATH=str(SOURCE), OMP_NUM_THREADS='4', MKL_NUM_THREADS='4')
- from .triton_compat import environment as compiler_environment
- self.env = compiler_environment(self.root, self.env)
+ self.env = self.device_environment(self.env)
self.env[LOCK_ENV] = str(self.runtime_fd)
self.env.update(FREEVIDEO_NETWORK_PLAN=str(self.run_dir / 'plan.json'),
FREEVIDEO_NETWORK_EVENTS=str(self.run_dir / 'network.jsonl'))
@@ -760,6 +792,14 @@ class Installer:
self.monitor_thread = None
self.started = time.monotonic()
+ def device_environment(self, env):
+ from .triton_compat import environment
+ return environment(self.root, dict(env,
+ CUDA_VISIBLE_DEVICES=self.plan['inventory']['selected_gpu']['uuid'],
+ TRITON_CACHE_DIR=str(self.root / 'kernel-cache' / 'triton'),
+ CUDA_CACHE_PATH=str(self.root / 'kernel-cache' / 'cuda'),
+ TORCHINDUCTOR_CACHE_DIR=str(self.root / 'kernel-cache' / 'inductor')))
+
def start_monitor(self):
from .ram import ProcessMemory
memory = ProcessMemory()
@@ -1238,8 +1278,35 @@ class Installer:
save(receipt, spec)
return toolkit
- def execute(self):
- self.ui.phase('Prepare download tools', 0, 8)
+ def device_configuration(self):
+ return {'gpu_uuid': self.plan['inventory']['selected_gpu']['uuid']}
+
+ def check_kernels(self, python, kernel_report):
+ # Kernel probes execute real CUDA work and take roughly a minute on a
+ # consumer GPU. A completed receipt is reusable only when every
+ # input that can change the result still matches: GPU identity,
+ # driver, Torch/CUDA, installed attention packages, and the engine
+ # source hashes. Keep the run-local copy so diagnostics retain the
+ # exact receipt used by this installation.
+ cached_kernel = self.root / 'kernel-capabilities.json'
+ hardware_data = self.plan.get('inventory', {}).get('hardware')
+ receipt = (reusable_kernel_receipt(cached_kernel, hardware_data)
+ if isinstance(hardware_data, dict) else None)
+ if receipt is None:
+ self.command('kernels', [python, '-m', 'freevideo_engine', 'doctor', '--probe', '--require-paths', '--out', kernel_report])
+ else:
+ save(kernel_report, receipt)
+ self.ui.event('setup_cache', key='kernels', detail='Reused matching GPU kernel checks')
+
+ def record_kernel_validation(self, results, kernel_report):
+ sage_manifest = results['sage']
+ sage_record = json.loads(sage_manifest.read_text(encoding='utf-8'))
+ kernels = json.loads(kernel_report.read_text(encoding='utf-8'))
+ sage_record['kernel_validation'] = ('Small Sage2 kernels passed on ' + self.plan['inventory']['selected_gpu']['uuid']
+ if 'sage2' in kernels['usable_attention_backends'] else 'Sage2 probe failed; see ' + str(kernel_report))
+ save(sage_manifest, sage_record)
+
+ def prepare_tools(self):
uv_spec = self.versions['uv']
if self.system == 'Windows':
from .uv_bootstrap import prepare_windows
@@ -1257,6 +1324,11 @@ class Installer:
self.fetch(uv_spec['url'], archive, uv_spec['sha256'])
unpack(archive, self.root / 'tools')
uv = self.root / 'tools' / 'uv-x86_64-unknown-linux-gnu' / 'uv'
+ return uv
+
+ def execute(self):
+ self.ui.phase('Prepare download tools', 0, 8)
+ uv = self.prepare_tools()
self.env['FREEVIDEO_UV'] = str(uv)
from .install_schedule import run
tasks, pythons, comfy = self.component_tasks(uv)
@@ -1271,7 +1343,6 @@ class Installer:
self.ui.phase(phase, 1, total)
results = run(tasks, self.cancel, progress=scheduling,
workers=1 if self.plan.get('disk_mode') == 'extreme' else 3)
- sage_manifest = results['sage']
python, encoder_python = self.pythons['engine'], self.pythons['encoder']
prepared = self.run_dir / 'prepared.json'
self.ui.phase('Optimize model storage', total - 3, total)
@@ -1282,28 +1353,10 @@ class Installer:
self.command(name + '-dependency-check', [uv, 'pip', 'check', '--python', executable])
self.command(name + '-freeze', [uv, 'pip', 'freeze', '--python', executable])
kernel_report = self.run_dir / 'kernel-capabilities.json'
- # Kernel probes execute real CUDA work and take roughly a minute on a
- # consumer GPU. A completed receipt is reusable only when every
- # input that can change the result still matches: GPU identity,
- # driver, Torch/CUDA, installed attention packages, and the engine
- # source hashes. Keep the run-local copy so diagnostics retain the
- # exact receipt used by this installation.
- cached_kernel = self.root / 'kernel-capabilities.json'
- hardware_data = self.plan.get('inventory', {}).get('hardware')
- receipt = (reusable_kernel_receipt(cached_kernel, hardware_data)
- if isinstance(hardware_data, dict) else None)
- if receipt is None:
- self.command('kernels', [python, '-m', 'freevideo_engine', 'doctor', '--probe', '--require-paths', '--out', kernel_report])
- else:
- save(kernel_report, receipt)
- self.ui.event('setup_cache', key='kernels', detail='Reused matching GPU kernel checks')
+ self.check_kernels(python, kernel_report)
self.command('storage', [python, '-m', 'freevideo_engine.provision', '--plan', self.run_dir / 'plan.json',
'--cleanup', '--out', self.run_dir / 'storage.json'])
- sage_record = json.loads(sage_manifest.read_text(encoding='utf-8'))
- kernels = json.loads(kernel_report.read_text(encoding='utf-8'))
- sage_record['kernel_validation'] = ('Small Sage2 kernels passed on ' + self.plan['inventory']['selected_gpu']['uuid']
- if 'sage2' in kernels['usable_attention_backends'] else 'Sage2 probe failed; see ' + str(kernel_report))
- save(sage_manifest, sage_record)
+ self.record_kernel_validation(results, kernel_report)
self.ui.phase('Finish setup', total - 1, total)
configuration = {'schema_version': 1, 'root': str(self.root), 'source': str(SOURCE),
'storage': self.plan.get('storage', 'compact'),
@@ -1321,7 +1374,7 @@ class Installer:
'cache': json.loads(prepared.read_text(encoding='utf-8'))['cache'],
'encoder': self.spec['models']['encoder_file'].split('/')[-1],
'model_paths': str(self.root / 'encoder-paths.yaml'),
- 'gpu_uuid': self.plan['inventory']['selected_gpu']['uuid'],
+ **self.device_configuration(),
'vram_gib': self.plan.get('vram_gib'), 'ram_gib': self.plan.get('ram_gib'),
'model_revision': self.spec['models']['vdn_revision'],
'setup_run': str(self.run_dir), 'ready': True}
@@ -1414,7 +1467,10 @@ def main(argv=None):
print('Cancelled. No engine or model installation was started.')
return 0
try:
- installer = Installer(value, ui)
+ installer_class = Installer
+ if value.get('device_backend') == 'mps':
+ from .macos_setup import Installer as installer_class
+ installer = installer_class(value, ui)
except BlockingIOError:
print('Setup, testing or generation is using this installation/GPU lock. Retry after it finishes.', file=sys.stderr)
from .locking import lock_holders
diff --git a/freevideo_engine/cli.py b/freevideo_engine/cli.py
index 0890178..b9462ef 100644
--- a/freevideo_engine/cli.py
+++ b/freevideo_engine/cli.py
@@ -121,6 +121,9 @@ def main():
help='Measure the placement questions this machine can settle')
calibrate.add_argument('arguments', nargs=argparse.REMAINDER)
args = parser.parse_args()
+ if sys.platform == 'darwin' and args.command in ('plan', 'generate', 'encode', 'doctor'):
+ from .macos_generate import dispatch
+ return dispatch(args)
if args.command == 'plan':
from .geometry import geometry
canvas = geometry(args.width, args.height, frames=args.frames, seconds=args.seconds)
diff --git a/freevideo_engine/comfy_assets.py b/freevideo_engine/comfy_assets.py
index 1a3ba82..0017d90 100644
--- a/freevideo_engine/comfy_assets.py
+++ b/freevideo_engine/comfy_assets.py
@@ -144,7 +144,7 @@ def output_summary(report, relative_video):
values = [v for v in values if isinstance(v, (int, float)) and v >= 0]
gpu_values = [phase.get('torch_peak_reserved_bytes') for phase in (video, encoding)]
gpu_values = [v for v in gpu_values if isinstance(v, (int, float)) and v >= 0]
- return dict(sample_seconds=video.get('sample_seconds'), request_seconds=report.get('request_seconds'),
+ result = dict(sample_seconds=video.get('sample_seconds'), request_seconds=report.get('request_seconds'),
vram_peak_bytes=max(gpu_values) if gpu_values else None,
ram_peak_bytes=max(values) if values else None, ram_metric=metric,
conditioning_cache_hit=report.get('encoding', {}).get('cache_hit', False),
@@ -155,3 +155,13 @@ def output_summary(report, relative_video):
video=relative_video.as_posix(), report=relative_video.with_suffix(
'.debug.json' if report.get('diagnostic_file') == relative_video.with_suffix('.debug.json').name
else '.request.json').as_posix())
+ if report.get('device_backend') == 'mps':
+ policy = report.get('profile', {}).get('policy', {})
+ hardware = report.get('runtime_hardware', {})
+ # RSS is a process observation, not total unified or Metal memory. MPS
+ # exposes current allocations but no allocator peak; never relabel it.
+ result.update(device_backend='mps', memory_model='unified',
+ unified_total_bytes=hardware.get('ram_total'),
+ unified_reserve_bytes=policy.get('reserve_bytes'),
+ vram_peak_bytes=None, gpu_budget_bytes=None, gpu_total_bytes=None)
+ return result
diff --git a/freevideo_engine/comfy_bridge.py b/freevideo_engine/comfy_bridge.py
index 0d37f74..d352ed3 100644
--- a/freevideo_engine/comfy_bridge.py
+++ b/freevideo_engine/comfy_bridge.py
@@ -8,6 +8,7 @@ import math
import os
from pathlib import Path
import subprocess
+import sys
import time
import uuid
@@ -261,9 +262,12 @@ def installation(source=None, environ=None):
'in the FreeVideo folder, or set FREEVIDEO_HOME to your existing installation. '
'A prepared engine installation is required.') from error
required = ('root', 'python', 'cache', 'base', 'checkpoint', 'comfy_python',
- 'comfy_root', 'vdn_root', 'model_paths', 'model_root', 'gpu_uuid', 'encoder')
+ 'comfy_root', 'vdn_root', 'model_paths', 'model_root', 'encoder')
if not isinstance(machine, dict) or not machine.get('ready') or any(not machine.get(k) for k in required):
raise ValueError('FreeVideo setup is incomplete. Open FreeVideo Settings and click "Install / repair" to repair %s; existing files are reused.' % root)
+ identity = 'device_identity' if machine.get('device_backend') == 'mps' else 'gpu_uuid'
+ if not machine.get(identity):
+ raise ValueError('FreeVideo device configuration is missing. Open Settings and click "Install / repair".')
if Path(machine['root']).expanduser().resolve() != root:
raise ValueError('The FreeVideo installation was moved. Rerun setup in the selected folder.')
if not Path(machine['python']).is_file():
@@ -441,7 +445,10 @@ def progress_message(event):
def engine_environment(root, source, environ=None):
- from .triton_compat import environment
+ if sys.platform == 'darwin':
+ from .macos_bootstrap import environment
+ else:
+ from .triton_compat import environment
return environment(root, isolated_environment(root, source, environ))
@@ -466,7 +473,7 @@ def generate(prompt, width, height, seconds, seed, output_directory, *,
# No attention, placement or capacity override: managed CLI uses the
# installation's explicit caps, otherwise its live automatic policy.
from .resource_settings import read as read_resources
- resources = read_resources(root)
+ resources = read_resources(root, backend=machine.get('device_backend', 'cuda'))
run = Path(output_directory).resolve() / 'FreeVideo' / time.strftime('%Y-%m-%d', time.gmtime()) / uuid.uuid4().hex
run.mkdir(parents=True, exist_ok=False)
output = run / 'video.mp4'
@@ -478,8 +485,9 @@ def generate(prompt, width, height, seconds, seed, output_directory, *,
'--width', str(width), '--height', str(height), '--seconds', str(seconds), '--seed', str(seed),
'--two-pass' if two_pass else '--no-two-pass',
'--base-steps', str(base_steps), '--refine-steps', str(refine_steps)]
- if resources['gpu_reserve_gib'] is not None:
- command += ['--gpu-reserve-gib', str(resources['gpu_reserve_gib'])]
+ for field, reserve in resources.items():
+ if reserve is not None:
+ command += ['--' + field.replace('_', '-'), str(reserve)]
state = {'status': 'starting', 'geometry': canvas, 'seed': seed, 'installation': str(root),
'command': command, 'output': str(output), 'source': str(source), 'resources': resources}
from .diagnostic_resources import encoder_prewarm as prewarm_summary
@@ -556,7 +564,7 @@ def generate(prompt, width, height, seconds, seed, output_directory, *,
if release_models:
release_models()
state['encoder_prewarm'] = prewarm_summary(encoder_prewarm)
- if (source/'freevideo_engine'/'resident_worker.py').is_file():
+ if machine.get('device_backend') != 'mps' and (source/'freevideo_engine'/'resident_worker.py').is_file():
from .resident_process import OWNER, ENV
if environment.get('FREEVIDEO_KEEP_MODELS', 'auto').lower() in ('0', 'off', 'false'):
OWNER.close()
diff --git a/freevideo_engine/comfy_host.py b/freevideo_engine/comfy_host.py
index 3de5632..3a7f8f5 100644
--- a/freevideo_engine/comfy_host.py
+++ b/freevideo_engine/comfy_host.py
@@ -139,14 +139,14 @@ def _prepare(root, comfy, machine, run, download):
python = env_root / ('Scripts/python.exe' if os.name == 'nt' else 'bin/python')
receipt = env_root / 'freevideo-host.json'
if not (python.is_file() and receipt.is_file() and json.loads(receipt.read_text(encoding='utf-8')) == identity):
- uv = root / 'tools' / ('uv.exe' if os.name == 'nt' else 'uv-x86_64-unknown-linux-gnu/uv')
+ uv = root / 'tools' / ('uv.exe' if os.name == 'nt' else 'uv' if sys.platform == 'darwin' else 'uv-x86_64-unknown-linux-gnu/uv')
if not uv.is_file():
raise ValueError('The engine download tool is missing. Run engine repair first.')
if not python.is_file():
execute([uv, 'venv', '--python', machine['python'], env_root], env, 'Create ComfyUI Python environment')
# Match the already validated CUDA packages. Hardlinked uv cache
# entries share their disk bytes without sharing a writable env.
- pins = directory / 'cuda-constraints.txt'
+ pins = directory / ('native-constraints.txt' if sys.platform == 'darwin' else 'cuda-constraints.txt')
rows = [name + '==' + importlib.metadata.version(name) for name in ('torch', 'torchvision', 'torchaudio')]
pins.write_text('\n'.join(rows) + '\n', encoding='utf-8')
torch_version = importlib.metadata.version('torch')
@@ -170,7 +170,7 @@ def _prepare(root, comfy, machine, run, download):
prepared = install(uv, python, rows, cuda, root=root, networking=plan, env=env, ui=ui,
run=lambda args, environment: execute(args, environment, 'Prepare ComfyUI GPU packages'), check=check)
if not prepared:
- package_install('torch-' + cuda,
+ package_install('pypi' if sys.platform == 'darwin' else 'torch-' + cuda,
lambda environment, _: execute([uv, 'pip', 'install', '--python', python, *rows], environment, 'Prepare ComfyUI GPU packages'),
'Prepare ComfyUI GPU packages')
ui.phase('Install ComfyUI packages', stage_offset + 2, stage_total)
diff --git a/freevideo_engine/comfy_launcher_runtime.py b/freevideo_engine/comfy_launcher_runtime.py
index d644d4e..b0b5fde 100644
--- a/freevideo_engine/comfy_launcher_runtime.py
+++ b/freevideo_engine/comfy_launcher_runtime.py
@@ -596,6 +596,9 @@ class Controller:
deadline = time.monotonic() + 10
while True:
with socket.socket(socket.AF_INET6 if parsed.hostname == '::1' else socket.AF_INET, socket.SOCK_STREAM) as check:
+ if sys.platform == 'darwin':
+ # Reopening our own server must tolerate TIME_WAIT on macOS.
+ check.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
try:
check.bind((parsed.hostname, parsed.port or 80))
break
diff --git a/freevideo_engine/comfy_setup.py b/freevideo_engine/comfy_setup.py
index 5b73354..9beabcf 100644
--- a/freevideo_engine/comfy_setup.py
+++ b/freevideo_engine/comfy_setup.py
@@ -71,6 +71,11 @@ class SetupRunner(Runner):
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):
@@ -136,13 +141,15 @@ class Setup:
def resource_settings(self, value=None):
- from .resource_settings import read, write
+ 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)
- if 'gpu_reserve_gib' not in value:
- raise ValueError('Specify automatic (null) or reserved VRAM in GiB')
- return write(root, value['gpu_reserve_gib'])
+ 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
diff --git a/freevideo_engine/comfy_updates.py b/freevideo_engine/comfy_updates.py
index 19682bc..aad629b 100644
--- a/freevideo_engine/comfy_updates.py
+++ b/freevideo_engine/comfy_updates.py
@@ -9,6 +9,7 @@ import threading
import time
from . import launcher_update
+from .release_notes import installed_details, public_details
def installed_build(package):
@@ -36,7 +37,7 @@ def launcher_view(status):
"""The parts of a launcher status a page may show; None without a launcher."""
if not isinstance(status, dict):
return None
- view = {k: status.get(k) for k in ('version', 'phase', 'status', 'progress', 'candidate', 'engine', 'error', 'manual')}
+ view = {k: status.get(k) for k in ('version', 'phase', 'status', 'progress', 'candidate', 'engine', 'error', 'manual', 'channel')}
view['phase'] = str(view['phase'] or '')
return view
@@ -52,6 +53,8 @@ class UpdateStatus:
self.bridge = bridge
self.state = dict(status='idle' if current else 'source',
current_version=current['version'] if current else None,
+ current_release=public_details(current) if current else installed_details(Path(__file__).parent),
+ channel=(current or {}).get('channel', launcher_update.CHANNEL),
available=None)
self.next_check = 0
self.client_seen = -1e9
@@ -80,10 +83,12 @@ class UpdateStatus:
# Pages that reload themselves after an update polled recently.
state['clients'] = int(now - self.client_seen < 20)
if launcher is not None:
+ if launcher.get('channel') in (launcher_update.CHANNEL, launcher_update.MAC_CHANNEL):
+ state['channel'] = launcher['channel']
engine = launcher.get('engine') or {}
candidate = launcher.get('candidate') if isinstance(launcher.get('candidate'), dict) else None
- available = (dict(version=str(candidate.get('version'))) if candidate and candidate.get('version') else
- dict(version=str(engine.get('version'))) if engine.get('pending') and engine.get('version') else None)
+ available = (public_details(candidate) if candidate and candidate.get('version') else
+ public_details(engine) if engine.get('pending') and engine.get('version') else None)
if self.current or available:
state.update(status='available' if available else 'current', available=available)
state['launcher'] = launcher
@@ -91,10 +96,15 @@ class UpdateStatus:
def _check(self):
try:
- candidate = launcher_update.latest_release()
+ channel = self.current.get('channel', launcher_update.CHANNEL)
+ candidate = (launcher_update.latest_release() if channel == launcher_update.CHANNEL
+ else launcher_update.latest_release(channel=channel))
+ if (candidate.get('channel', launcher_update.CHANNEL) != channel
+ or launcher_update.build_target(candidate) != launcher_update.build_target(self.current)):
+ raise ValueError('Update belongs to a different platform')
newer = (candidate['built_at'] > self.current['built_at']
and candidate['revision'] != self.current['revision'])
- available = {key: candidate[key] for key in ('version', 'revision', 'built_at')} if newer else None
+ available = public_details(candidate) if newer else None
with self.lock:
self.state.update(status='available' if available else 'current', available=available)
self.next_check = time.monotonic() + 15 * 60
diff --git a/freevideo_engine/dependencies.json b/freevideo_engine/dependencies.json
index 0dec872..fc5fdcf 100644
--- a/freevideo_engine/dependencies.json
+++ b/freevideo_engine/dependencies.json
@@ -49,6 +49,12 @@
"revision": "5be1ff90c02c9b1c1ce7300d6a803931732e6ab0",
"hf_revision": "ae041e5aec51f8516a3416bd86d579cb29c4c796",
"probe_file": "rowwise/cache/blocks/00.safetensors"
+ },
+ "int8_convrot": {
+ "repo": "OpenVDN/vdn-minimax-h3-edge",
+ "revision": "17738b37839b490c5ae95246d8cb41893e76d887",
+ "hf_revision": "da37681f5a1f7015fdb63482142b865111b687d3",
+ "probe_file": "int8-convrot/cache/blocks/00.safetensors"
}
},
"latent_upscaler": {
diff --git a/freevideo_engine/desktop_runtime.py b/freevideo_engine/desktop_runtime.py
index 3b50c52..5d8ea85 100644
--- a/freevideo_engine/desktop_runtime.py
+++ b/freevideo_engine/desktop_runtime.py
@@ -22,6 +22,8 @@ from .system import install_root, windows
def launcher_root():
if os.environ.get('FREEVIDEO_LAUNCHER_HOME'):
return Path(os.environ['FREEVIDEO_LAUNCHER_HOME'])
+ if sys.platform == 'darwin':
+ return Path.home() / 'Library/Application Support/FreeVideo/launcher'
home = os.environ.get('LOCALAPPDATA') or str(Path.home())
return Path(home) / 'FreeVideo-launcher'
@@ -32,6 +34,9 @@ def source_files(root):
'freevideo.ps1', 'setup.ps1', 'test.ps1', 'freevideo.cmd', 'setup.cmd', 'test.cmd',
'scripts/bootstrap_linux.sh', 'scripts/windows_app.py', 'scripts/build_windows.py',
'scripts/check_installation.py', 'scripts/build_launcher_notices.py']
+ # Older deployed Windows payloads may predate the optional Mac entry points.
+ files_optional = ('scripts/build_macos.py', 'scripts/macos_app.py')
+ names += [name for name in files_optional if (root / name).is_file()]
files = [root / name for name in names]
files += [p for folder in ('freevideo_engine', 'constraints', 'web', 'example_workflows')
for p in (root / folder).rglob('*')
diff --git a/freevideo_engine/desktop_shortcut.py b/freevideo_engine/desktop_shortcut.py
index 2819eaa..70cbfd2 100644
--- a/freevideo_engine/desktop_shortcut.py
+++ b/freevideo_engine/desktop_shortcut.py
@@ -111,6 +111,9 @@ def launcher_target(engine, source, portable_root=None):
def create(engine, source, portable_root=None):
if not windows():
+ if sys.platform == 'darwin':
+ from .macos_shortcut import create as create_mac
+ return create_mac(engine)
return dict(status='not-applicable')
engine = Path(engine)
receipt = engine / 'launcher/desktop-shortcut.json'
diff --git a/freevideo_engine/diagnostic_summary.py b/freevideo_engine/diagnostic_summary.py
index 95ca955..64e9d85 100644
--- a/freevideo_engine/diagnostic_summary.py
+++ b/freevideo_engine/diagnostic_summary.py
@@ -30,7 +30,7 @@ def summary_report(report):
hardware = summary.get('hardware') or {}
config = summary.get('effective_engine_config') or {}
result = dict(kind='generation', status=summary.get('status') if summary.get('status') in
- ('complete', 'retrying', 'running') else 'incomplete',
+ ('complete', 'reused', 'retrying', 'running') else 'incomplete',
version=__version__, hardware={}, config={}, geometry={}, memory={}, stages=[], steps=[], errors=[])
for k in ('gpu_name', 'system', 'architecture', 'driver_version', 'torch_version', 'cuda_version'):
if _label(hardware.get(k)):
@@ -206,7 +206,7 @@ def summary_report(report):
current = phase or diagnostic.mapping(report.get('encoding')).get('phase')
if diagnostic.name(current):
result['current_stage'] = current
- elif result['status'] != 'complete' and diagnostic.name(phase):
+ elif result['status'] not in ('complete', 'reused') and diagnostic.name(phase):
result['failure_stage'] = phase
if result['attempts']:
result['errors'] = [dict(attempt=row['index'], phase=row.get('phase', 'unknown'),
diff --git a/freevideo_engine/environments.py b/freevideo_engine/environments.py
index fc7b313..35f9560 100644
--- a/freevideo_engine/environments.py
+++ b/freevideo_engine/environments.py
@@ -10,12 +10,20 @@ ENVIRONMENTS = {
def constraints_file(name, system=None):
+ if (system or platform.system()) == 'Darwin':
+ if name != 'unified':
+ raise ValueError('Mac requires the native unified environment')
+ from .macos_bootstrap import constraints
+ return constraints()
prefix = 'windows-' if (system or platform.system()) == 'Windows' else ''
return Path(__file__).resolve().parent.parent / 'constraints' / (prefix + name + '.txt')
def bootstrap_versions(value, system=None):
result = dict(value, target_system=system or platform.system())
+ if result['target_system'] == 'Darwin':
+ from .macos_bootstrap import versions
+ return versions(value)
if result['target_system'] == 'Windows':
result['uv'] = result['windows']['uv']
return result
diff --git a/freevideo_engine/install_tuning.py b/freevideo_engine/install_tuning.py
index 7518b99..902ff9b 100644
--- a/freevideo_engine/install_tuning.py
+++ b/freevideo_engine/install_tuning.py
@@ -25,12 +25,19 @@ def required_models(rows, reuse_cache):
return [r for r in rows if not conversion_source(r)]
-def cache_compatible(path, capability):
+def cache_compatible(path, capability=None, *, scale_granularity=None):
try:
value = json.loads((Path(path) / 'manifest.json').read_text(encoding='utf-8'))
- if value.get('format') == 'freevideo-fp8-slim-v1':
+ if value.get('format') in ('freevideo-fp8-slim-v1', 'freevideo-int8-slim-v1'):
from .adaln_assets import validate_catalog
validate_catalog(value, sum(r['group'].startswith('blocks/') for r in value['groups']))
+ if scale_granularity == 'int8_convrot':
+ rotation = value.get('rotation') or {}
+ return (value.get('precision') == 'int8' and value.get('scale_granularity') == 'rowwise'
+ and rotation.get('kind') == 'convrot' and rotation.get('group') == 256 and bool(value.get('groups')))
+ if scale_granularity is not None:
+ return (scale_granularity in ('rowwise', 'per_tensor') and value.get('precision') == 'fp8'
+ and bool(value.get('groups')) and value.get('scale_granularity') == scale_granularity)
native_format = 'per_tensor' if capability[0] >= 10 else 'rowwise'
return (value.get('precision') == 'fp8' and bool(value.get('groups')) and
(tuple(capability) < (8, 9) or value.get('scale_granularity') == native_format))
@@ -38,14 +45,14 @@ def cache_compatible(path, capability):
return False
-def discover_prepared(folder, capability):
+def discover_prepared(folder, capability=None, *, scale_granularity=None):
"""Recognize a downloaded engine bundle in the user's selected model folder."""
if not folder:
return None
root = Path(folder).expanduser().resolve()
candidates = [root, root / 'cache', root / 'vdn-h3-edge/cache', root / 'vdn-minimax-h3-edge/cache']
for candidate in candidates:
- if cache_compatible(candidate, capability):
+ if cache_compatible(candidate, capability, scale_granularity=scale_granularity):
return candidate
return None
diff --git a/freevideo_engine/kernel_capabilities.py b/freevideo_engine/kernel_capabilities.py
index 0f1f35a..c99d5e5 100644
--- a/freevideo_engine/kernel_capabilities.py
+++ b/freevideo_engine/kernel_capabilities.py
@@ -9,7 +9,8 @@ from .hardware import installed_backends
from .paths import data_root
PACKAGES = ('torch', 'triton', 'triton-windows', 'diffusers', 'sageattention', 'flash-attn', 'flash-attn-4')
-COMPUTE_FILES = ('attention.py', 'probe.py', 'fp8_gemm.py', 'fp8_ops.py', 'weight_only.py',
+COMPUTE_FILES = ('attention.py', 'backends/__init__.py', 'backends/base.py', 'backends/cuda.py',
+ 'backends/cuda_attention.py', 'probe.py', 'fp8_gemm.py', 'fp8_ops.py', 'weight_only.py',
'kernel_capabilities.py', 'doctor.py', 'fa4_guard.py', 'triton_compat.py', 'runtime.py',
'head_chunk.py', 'blocks.py', 'packing.py', 'dependencies.json')
diff --git a/freevideo_engine/latent_upscale.py b/freevideo_engine/latent_upscale.py
index 94b8611..1e2d2fa 100644
--- a/freevideo_engine/latent_upscale.py
+++ b/freevideo_engine/latent_upscale.py
@@ -65,7 +65,9 @@ def upscale(video, checkpoint, width, height, *, memory_saving=False):
strict=True,assign=True)
del state
model = model.eval().requires_grad_(False).to(device=video.device,dtype=torch.float16)
+ folded = install_folded_convolutions(model) if video.device.type == 'mps' else 0
if video.is_cuda:torch.cuda.synchronize(video.device)
+ elif video.device.type == 'mps':torch.mps.synchronize()
loaded = time.perf_counter()-tick
tick = time.perf_counter()
mean = video.new_tensor(LATENTS_MEAN, dtype=torch.float16).view(1,-1,1,1,1)
@@ -75,16 +77,66 @@ def upscale(video, checkpoint, width, height, *, memory_saving=False):
target_size=(video.shape[2],target_h,target_w),enable_chunking=False)
result = (result * std + mean).float()
if video.is_cuda:torch.cuda.synchronize(video.device)
+ elif video.device.type == 'mps':torch.mps.synchronize()
computed = time.perf_counter()-tick
if not bool(torch.isfinite(result).all()):
raise RuntimeError('Latent upscaler produced nonfinite values')
return result, dict(load_seconds=loaded,compute_seconds=computed,scale=scale,
checkpoint_sha256=digest,temporal_chunking=False,normalized_input=True,
- buffer_reuse=memory_saving,checkpoint_transform='extra_per_channel_v1')
+ buffer_reuse=memory_saving,checkpoint_transform='extra_per_channel_v1',
+ folded_convolutions=folded)
finally:
del model
gc.collect()
if video.is_cuda:torch.cuda.empty_cache()
+ elif video.device.type == 'mps':torch.mps.empty_cache()
+
+FOLD_BYTES = 512 * 2**20
+
+
+def _folded_conv3d(module, x):
+ """A 3x3x3, padding-1 Conv3d as one conv2d over the temporal taps in channels.
+
+ Each output frame is the same single reduction over 3 x C x 3 x 3 inputs:
+ its previous, current and next frame (zeros past either end) side by side.
+ MPS ran the 3D form at about 0.9 TFLOPS on an M5; the 2D form uses its
+ matrix units. Frames are folded a bounded group at a time.
+ """
+ batch, channels, frames, height, width = x.shape
+ weight = module.weight.permute(0, 2, 1, 3, 4).reshape(module.out_channels, 3 * channels, 3, 3)
+ planes = x.transpose(1, 2) # [B, T, C, H, W]
+ out = x.new_empty((batch, module.out_channels, frames, height, width))
+ group = max(1, FOLD_BYTES // max(1, 3 * channels * height * width * x.element_size()))
+ for start in range(0, frames, group):
+ end = min(frames, start + group)
+ parts = []
+ for shift in (-1, 0, 1):
+ lo, hi = start + shift, end + shift
+ part = planes[:, max(lo, 0):min(hi, frames)]
+ pad_before, pad_after = max(0, -lo), max(0, hi - frames)
+ if pad_before or pad_after:
+ zero = x.new_zeros((batch, 1, channels, height, width))
+ part = torch.cat([zero] * pad_before + [part] + [zero] * pad_after, dim=1)
+ parts.append(part)
+ stacked = torch.cat(parts, dim=2).reshape(batch * (end - start), 3 * channels, height, width)
+ result = F.conv2d(stacked, weight, module.bias, padding=1)
+ out[:, :, start:end] = result.view(batch, end - start, module.out_channels, height, width).transpose(1, 2)
+ del parts, stacked, result
+ return out
+
+
+def install_folded_convolutions(model):
+ """Route this model's 3x3x3 zero-padded convolutions through `_folded_conv3d`."""
+ import types
+ count = 0
+ for module in model.modules():
+ if (isinstance(module, nn.Conv3d) and module.kernel_size == (3, 3, 3) and module.stride == (1, 1, 1)
+ and module.padding == (1, 1, 1) and module.dilation == (1, 1, 1) and module.groups == 1
+ and module.padding_mode == 'zeros'):
+ module.forward = types.MethodType(_folded_conv3d, module)
+ count += 1
+ return count
+
def normalization(channels):
return nn.GroupNorm(32, channels)
diff --git a/freevideo_engine/launcher/FPopup.qml b/freevideo_engine/launcher/FPopup.qml
index 6aec07d..a21f8de 100644
--- a/freevideo_engine/launcher/FPopup.qml
+++ b/freevideo_engine/launcher/FPopup.qml
@@ -4,7 +4,7 @@ import QtQuick.Controls.Basic
// Modal sheet shared by every launcher dialog.
Popup {
anchors.centerIn: Overlay.overlay
- modal: true; padding: 28
+ modal: true; focus: true; padding: 28
background: Rectangle { radius: theme.radiusLg; color: theme.canvas; border.color: theme.sheen }
Overlay.modal: Rectangle { color: theme.scrim }
enter: Transition { ParallelAnimation {
diff --git a/freevideo_engine/launcher/FReleaseNotes.qml b/freevideo_engine/launcher/FReleaseNotes.qml
new file mode 100644
index 0000000..e46914c
--- /dev/null
+++ b/freevideo_engine/launcher/FReleaseNotes.qml
@@ -0,0 +1,20 @@
+import QtQuick
+import QtQuick.Layouts
+
+ColumnLayout {
+ property var release: ({})
+ property bool zh: false
+ property string heading: ""
+ readonly property var notes: release && release.release_notes ? release.release_notes[zh ? "zh" : "en"] : null
+ spacing: 8
+ FText { text: heading; font.weight: Font.DemiBold; font.pixelSize: theme.section; Layout.fillWidth: true }
+ FText {
+ text: release && release.development ? (zh ? "开发版本" : "Development version") : (zh ? "构建号:" : "Build: ") + (release && release.version || "—")
+ color: theme.muted; font.pixelSize: theme.micro; Layout.fillWidth: true
+ }
+ FText { text: notes ? notes.summary : (zh ? "此版本未附带更新说明。" : "No release notes were included with this version."); Layout.fillWidth: true }
+ Repeater {
+ model: notes ? notes.changes : []
+ delegate: FText { required property string modelData; text: "• " + modelData; color: theme.muted; Layout.fillWidth: true }
+ }
+}
diff --git a/freevideo_engine/launcher/Main.qml b/freevideo_engine/launcher/Main.qml
index bdb78b9..48a2c5d 100644
--- a/freevideo_engine/launcher/Main.qml
+++ b/freevideo_engine/launcher/Main.qml
@@ -4,8 +4,9 @@ import QtQuick.Layouts
ApplicationWindow {
id: win
- title: "FreeVideo"
- color: theme.bg
+ title: unifiedChrome ? "" : "FreeVideo"
+ readonly property bool unifiedChrome: Qt.platform.os === "osx"
+ color: unifiedChrome ? theme.canvas : theme.bg
width: 1280; height: 860
property var s: initialState
Connections { target: backend; function onChanged() { win.s = backend.state } }
@@ -17,12 +18,13 @@ ApplicationWindow {
property bool closePending: false
property bool accepted: false
property bool manualUpdate: false
+ property bool releaseNotesOpen: false
property string previousStatus: ""
property string previousReview: ""
property bool compact: width < 1000
property bool shortWindow: height < 700
property bool otherModelLinksOpen: false
- readonly property bool manualEnvironment: s.form.new_comfy && s.form.environment_method === "manual"
+ readonly property bool manualEnvironment: s.offline.runtime_supported !== false && s.form.new_comfy && s.form.environment_method === "manual"
readonly property bool usingRuntime: manualEnvironment && s.offline.runtime
readonly property bool needsRuntime: s.page === "comfy" && manualEnvironment && !s.offline.runtime
readonly property bool offlineSelected: usingRuntime || s.form.model_method === "manual"
@@ -32,6 +34,10 @@ ApplicationWindow {
property bool errorDetailsOpen: false
property string previousError: ""
function t(en, zh) { return s.zh ? zh : en }
+ function releaseVersion(value) { return value && value.product_version ? "v" + value.product_version : value && value.version || "—" }
+ function releaseSummary(value) { return value && value.release_notes ? value.release_notes[s.zh ? "zh" : "en"].summary : "" }
+ readonly property var currentRelease: s.update.current_release || {version: s.update.current}
+ readonly property var availableRelease: s.update.candidate || (s.update.engine ? currentRelease : null)
function sourceName(value) { return ({"auto": t("Automatic", "自动选择"), "official": "Hugging Face", "hf-mirror": t("HF Mirror", "HF 镜像"), "modelscope": t("ModelScope", "魔搭")})[value] || value }
function number(n) { return typeof n === "number" && isFinite(n) }
function fraction(row) { return row && number(row.total) && row.total > 0 && number(row.done) && row.done <= row.total ? row.done / row.total : -1 }
@@ -47,8 +53,8 @@ ApplicationWindow {
if (phase === "restarting") return t("Restarting FreeVideo…", "正在重启 FreeVideo…")
if (phase === "engine") return t("Updating the engine…", "正在更新引擎…")
if (phase === "checking") return t("Checking for updates…", "正在检查更新…")
- if (s.update.candidate) return t("FreeVideo ", "FreeVideo ") + s.update.candidate.version + t(" is available", " 可以更新")
- return t("New engine ", "新版引擎 ") + s.update.current + t(" is ready", " 已就绪")
+ if (s.update.candidate) return t("FreeVideo ", "FreeVideo ") + releaseVersion(s.update.candidate) + t(" is available", " 可以更新")
+ return t("New engine ", "新版引擎 ") + releaseVersion(currentRelease) + t(" is ready", " 已就绪")
}
function updateExplanation() {
var phase = s.update.phase
@@ -57,7 +63,7 @@ ApplicationWindow {
if (phase === "restarting" || phase === "engine") return t("ComfyUI restarts once; open FreeVideo pages refresh automatically.", "ComfyUI 会重启一次,已打开的 FreeVideo 页面会自动刷新。")
if (phase === "checking") return ""
if (s.update.status === "error" && s.update.error) return s.update.error
- if (s.update.candidate) return t("Current version ", "当前版本 ") + s.update.current + t(". Updating keeps your models and settings and takes about a minute.", "。更新会保留模型和设置,约需 1 分钟。")
+ if (s.update.candidate) return t("Current version ", "当前版本 ") + releaseVersion(currentRelease) + t(". Updating keeps your models and settings and takes about a minute.", "。更新会保留模型和设置,约需 1 分钟。")
return t("Installed engine ", "已安装引擎 ") + (s.update.installed || "—") + t(". Updating takes about a minute and keeps your models and settings.", "。更新约需 1 分钟,模型和设置都会保留。")
}
function primaryText() {
@@ -97,16 +103,21 @@ ApplicationWindow {
Rectangle {
id: sidebar
+ objectName: "sidebar"
width: win.compact ? 200 : 232
anchors.top: parent.top; anchors.bottom: parent.bottom; anchors.left: parent.left
- color: theme.bg
+ color: win.color
Rectangle { width: 1; color: theme.border; anchors.right: parent.right; height: parent.height }
ColumnLayout {
anchors.fill: parent; anchors.margins: 16; spacing: 4
- RowLayout {
- Layout.topMargin: 10; Layout.leftMargin: 6; Layout.bottomMargin: 28; spacing: 10
- Image { source: "../assets/icon.png"; sourceSize.width: 64; sourceSize.height: 64; Layout.preferredWidth: 32; Layout.preferredHeight: 32; smooth: true }
- FText { text: "FreeVideo"; font.pixelSize: theme.section; font.weight: Font.DemiBold; font.letterSpacing: -0.4 }
+ // The app icon alone is the brand mark.
+ Image {
+ objectName: "brandIcon"
+ source: "../assets/icon.png"; sourceSize.width: 96; sourceSize.height: 96
+ Layout.preferredWidth: 40; Layout.preferredHeight: 40
+ Layout.topMargin: 6; Layout.leftMargin: 6; Layout.bottomMargin: 24
+ smooth: true; mipmap: true
+ Accessible.role: Accessible.Graphic; Accessible.name: "FreeVideo"
}
FNav { objectName: "navLauncher"; glyph: "play"; text: t("Launch", "启动"); Layout.fillWidth: true; selected: s.page === "launcher"; enabled: s.selected && !s.busy; onClicked: backend.action("launcher", false) }
FNav { objectName: "navSetup"; glyph: "download"; text: t("Installation", "安装"); Layout.fillWidth: true; selected: s.page !== "launcher"; enabled: !s.busy && !s.portable; onClicked: backend.action("setup", false) }
@@ -129,7 +140,7 @@ ApplicationWindow {
}
FNav { glyph: "terminal"; text: t("Terminal", "终端"); Layout.fillWidth: true; selected: terminalOpen; onClicked: terminalOpen = !terminalOpen }
FNav { objectName: "settingsButton"; glyph: "settings"; text: t("Settings", "设置"); Layout.fillWidth: true; onClicked: settingsOpen = true }
- FText { text: s.version; color: theme.disabled; font.pixelSize: 11; Layout.leftMargin: 12; Layout.topMargin: 12 }
+ FButton { objectName: "versionInfoButton"; text: releaseVersion(currentRelease); flat: true; font.pixelSize: 11; Layout.topMargin: 12; Accessible.name: t("Version & release notes", "版本与更新说明"); onClicked: releaseNotesOpen = true }
}
}
@@ -287,7 +298,7 @@ ApplicationWindow {
FCard {
Layout.fillWidth: true; padding: shortWindow ? 16 : 22; spacing: 10
RowLayout {
- objectName: "environmentMethods"; visible: s.form.new_comfy; Layout.fillWidth: true; spacing: 12
+ objectName: "environmentMethods"; visible: s.form.new_comfy && s.offline.runtime_supported !== false; Layout.fillWidth: true; spacing: 12
FText { text: t("Install method", "安装方式"); font.weight: Font.DemiBold; Layout.fillWidth: true }
FSegmented {
objectName: "environmentMethod"; Layout.preferredWidth: Math.min(340, parent.width * .72)
@@ -297,7 +308,7 @@ ApplicationWindow {
Accessible.name: t("Install method", "安装方式")
}
}
- FDivider { visible: s.form.new_comfy; Layout.fillWidth: true; Layout.topMargin: 4; Layout.bottomMargin: 4 }
+ FDivider { visible: s.form.new_comfy && s.offline.runtime_supported !== false; Layout.fillWidth: true; Layout.topMargin: 4; Layout.bottomMargin: 4 }
FText { text: s.form.new_comfy ? t("Install location", "安装位置") : t("ComfyUI folder", "ComfyUI 目录"); font.weight: Font.DemiBold }
RowLayout {
Layout.fillWidth: true; spacing: 8
@@ -414,7 +425,7 @@ ApplicationWindow {
model: cloudLinks
delegate: FButton { required property var modelData; required property int index; objectName: "offlineShare-" + index; text: t("Download from Quark ↗", "打开夸克网盘 ↗"); onClicked: backend.link(modelData.url) }
}
- FText { text: t("Get Common models and the pack for your GPU (RTX 30/40 or RTX 50).", "下载「公用模型」和对应显卡包(30/40 系或 50 系)。"); color: theme.muted; font.pixelSize: theme.micro; Layout.fillWidth: true }
+ FText { objectName: "offlinePackageGuide"; text: s.offline.guide; color: theme.muted; font.pixelSize: theme.micro; Layout.fillWidth: true }
FButton { objectName: "otherModelLinks"; text: t("Alternative download sources", "其他下载渠道") + (otherModelLinksOpen ? " −" : " +"); flat: true; implicitHeight: theme.heightSm - 2; leftPadding: 0; font.pixelSize: theme.micro + 1; onClicked: otherModelLinksOpen = !otherModelLinksOpen }
FText { visible: otherModelLinksOpen; text: t("The same models are also available from Hugging Face or ModelScope.", "同一套模型,也可从 Hugging Face 或魔搭下载。"); color: theme.muted; font.pixelSize: theme.micro; Layout.fillWidth: true }
Flow {
@@ -552,6 +563,8 @@ ApplicationWindow {
}
}
FMeter { visible: s.update.phase === "downloading"; Layout.fillWidth: true; fraction: s.update.progress && s.update.progress.total ? s.update.progress.done / s.update.progress.total : -1; active: visible }
+ FText { visible: !s.update.phase && !!text; text: releaseSummary(availableRelease); Layout.fillWidth: true; color: theme.muted; font.pixelSize: theme.micro }
+ FButton { text: t("What's new", "更新内容"); flat: true; visible: !s.update.phase; implicitHeight: theme.heightSm; onClicked: releaseNotesOpen = true }
}
FCard {
Layout.fillWidth: true; padding: 26; spacing: 18
@@ -760,6 +773,7 @@ ApplicationWindow {
}
FButton { objectName: "checkUpdatesButton"; text: t("Check now", "检查更新"); implicitHeight: theme.heightSm; font.pixelSize: theme.micro + 1; onClicked: { manualUpdate = true; backend.checkUpdates("") } }
}
+ FButton { text: t("Version & release notes", "版本与更新说明") + " · " + releaseVersion(currentRelease); flat: true; Layout.fillWidth: true; onClicked: releaseNotesOpen = true }
}
FGroup {
Layout.fillWidth: true; title: t("Compatibility", "兼容性")
@@ -828,7 +842,7 @@ ApplicationWindow {
id: modelContents; width: modelScroll.availableWidth
spacing: 12
FText { text: t("Download models", "下载模型"); font.pixelSize: theme.section + 2; font.weight: Font.DemiBold }
- FText { text: modelInfo === "video" ? t("Choose your GPU variant on the model page and keep its folder structure.", "按模型页说明选择显卡版本,保留下载的目录结构。") : modelInfo === "decoder" ? t("Download the vae and audio_vae folders.", "下载 vae 和 audio_vae 文件夹。") : t("Download the text encoder to your model folder.", "下载文本编码器,放入模型目录。"); color: theme.muted; Layout.fillWidth: true; Layout.bottomMargin: 4 }
+ FText { objectName: "videoModelGuide"; text: modelInfo === "video" ? s.video_model_guide : modelInfo === "decoder" ? t("Download the vae and audio_vae folders.", "下载 vae 和 audio_vae 文件夹。") : t("Download the text encoder to your model folder.", "下载文本编码器,放入模型目录。"); color: theme.muted; Layout.fillWidth: true; Layout.bottomMargin: 4 }
Repeater { model: modelLinks[modelInfo]; delegate: FButton { required property var modelData; required property int index; objectName: "modelLink-" + index; text: t(modelData.label, modelData.label_zh) + " ↗"; Layout.fillWidth: true; onClicked: backend.link(modelData.url) } }
Repeater { model: cloudLinks; delegate: FButton { required property var modelData; text: t("Quark · ", "夸克 · ") + modelData.label + " ↗"; Layout.fillWidth: true; onClicked: backend.link(modelData.url) } }
FText { text: t("When your download finishes, import a FreeVideo ZIP or choose the folder containing your models.", "下载完成后,导入 FreeVideo ZIP 或选择存放模型的文件夹。"); color: theme.muted; font.pixelSize: theme.micro; Layout.fillWidth: true; Layout.topMargin: 6 }
@@ -857,8 +871,10 @@ ApplicationWindow {
id: updateContents; width: updateScroll.availableWidth
spacing: 14
FText { text: s.update.candidate ? t("Update available", "有可用更新") : s.update.engine ? t("Engine update", "引擎更新") : t("Updates", "更新"); font.pixelSize: theme.section + 2; font.weight: Font.DemiBold }
- FText { objectName: "updateDialogText"; text: s.update.phase === "waiting" ? t("A video is still generating. FreeVideo restarts and updates as soon as it finishes.", "还有视频正在生成,完成后会自动重启并更新。") : s.update.status === "ready" && s.update.candidate ? t("Downloaded. Restart to finish; models and settings are kept.", "下载完成,重启即可完成更新,模型和设置都会保留。") : s.update.candidate ? t("FreeVideo ", "FreeVideo ") + s.update.candidate.version + t(" is available (current ", " 已发布(当前 ") + s.update.current + t("). Updating keeps your models and settings. FreeVideo restarts after the download; running videos finish first.", ")。更新会保留模型和设置,下载完成后自动重启;正在生成的视频会先完成。") : s.update.engine ? t("This launcher already includes engine ", "启动器已带有新版引擎 ") + s.update.current + t(" (installed ", "(已安装 ") + (s.update.installed || "—") + (s.status === "open" ? t("). Updating takes about a minute, restarts ComfyUI once and keeps your models and settings.", ")。更新约需 1 分钟,会重启一次 ComfyUI,模型和设置都会保留。") : t("). Updating takes about a minute, then FreeVideo starts; models and settings are kept.", ")。更新约需 1 分钟,完成后自动启动,模型和设置都会保留。")) : s.update.status === "current" ? t("You're up to date.", "已是最新版本。") : s.update.status === "development" ? t("Running from source. Update with Git.", "当前从源码运行,请通过 Git 更新。") : s.update.status === "error" ? t("Couldn't check for updates. Try again below.", "暂时无法检查更新,请重试。") : t("Checking the latest release…", "正在检查最新版本…"); color: theme.muted; Layout.fillWidth: true }
+ FText { objectName: "updateDialogText"; text: s.update.phase === "waiting" ? t("A video is still generating. FreeVideo restarts and updates as soon as it finishes.", "还有视频正在生成,完成后会自动重启并更新。") : s.update.status === "ready" && s.update.candidate ? t("Downloaded. Restart to finish; models and settings are kept.", "下载完成,重启即可完成更新,模型和设置都会保留。") : s.update.candidate ? t("FreeVideo ", "FreeVideo ") + releaseVersion(s.update.candidate) + t(" is available (current ", " 已发布(当前 ") + releaseVersion(currentRelease) + t("). Updating keeps your models and settings. FreeVideo restarts after the download; running videos finish first.", ")。更新会保留模型和设置,下载完成后自动重启;正在生成的视频会先完成。") : s.update.engine ? t("This launcher already includes engine ", "启动器已带有新版引擎 ") + releaseVersion(currentRelease) + t(" (installed ", "(已安装 ") + (s.update.installed || "—") + (s.status === "open" ? t("). Updating takes about a minute, restarts ComfyUI once and keeps your models and settings.", ")。更新约需 1 分钟,会重启一次 ComfyUI,模型和设置都会保留。") : t("). Updating takes about a minute, then FreeVideo starts; models and settings are kept.", ")。更新约需 1 分钟,完成后自动启动,模型和设置都会保留。")) : s.update.status === "current" ? t("You're up to date.", "已是最新版本。") : s.update.status === "development" ? t("Running from source. Update with Git.", "当前从源码运行,请通过 Git 更新。") : s.update.status === "error" ? t("Couldn't check for updates. Try again below.", "暂时无法检查更新,请重试。") : t("Checking the latest release…", "正在检查最新版本…"); color: theme.muted; Layout.fillWidth: true }
FMeter { Layout.fillWidth: true; visible: s.update.status === "downloading"; active: true; fraction: s.update.progress && s.update.progress.total ? s.update.progress.done/s.update.progress.total : -1 }
+ FReleaseNotes { objectName: "updateReleaseNotes"; visible: !!availableRelease; Layout.fillWidth: true; release: availableRelease; zh: s.zh; heading: t("What's new", "更新内容") + " · " + releaseVersion(availableRelease) }
+ FButton { text: t("Version & release notes", "版本与更新说明"); flat: true; onClicked: releaseNotesOpen = true }
FText { visible: !!s.update.error; text: s.update.error || ""; color: theme.danger; Layout.fillWidth: true; font.pixelSize: theme.micro }
FField { id: githubToken; visible: !!s.update.error; Layout.fillWidth: true; echoMode: TextInput.Password; placeholderText: t("GitHub token · optional", "GitHub Token · 可选") }
RowLayout {
@@ -871,6 +887,28 @@ ApplicationWindow {
}
}
+ FPopup {
+ objectName: "releaseNotesDialog"; visible: releaseNotesOpen; onClosed: releaseNotesOpen = false
+ width: Math.min(560, win.width - 40)
+ height: Math.min(releaseContents.implicitHeight + padding * 2 + 60, win.height - 48)
+ contentItem: ColumnLayout {
+ spacing: 14
+ ScrollView {
+ Layout.fillWidth: true; Layout.fillHeight: true
+ id: releaseScroll; clip: true; contentWidth: availableWidth
+ ColumnLayout {
+ id: releaseContents; width: releaseScroll.availableWidth; spacing: 18
+ FText { text: t("Version & release notes", "版本与更新说明"); font.pixelSize: theme.section + 2; font.weight: Font.DemiBold; Layout.fillWidth: true }
+ FReleaseNotes { visible: !!s.update.candidate; Layout.fillWidth: true; release: s.update.candidate; zh: s.zh; heading: t("Available update", "可用更新") + " · " + releaseVersion(s.update.candidate) }
+ FDivider { visible: !!s.update.candidate }
+ FReleaseNotes { objectName: "currentReleaseNotes"; Layout.fillWidth: true; release: currentRelease; zh: s.zh; heading: t("Current version", "当前版本") + " · " + releaseVersion(currentRelease) }
+ FText { visible: !!s.update.installed; text: t("Installed engine build: ", "已安装引擎构建号:") + (s.update.installed || ""); color: theme.muted; font.pixelSize: theme.micro; Layout.fillWidth: true }
+ }
+ }
+ FButton { objectName: "closeReleaseNotesButton"; text: t("Close", "关闭"); onClicked: releaseNotesOpen = false }
+ }
+ }
+
FDialog {
visible: closePending
title: t("Pause and close?", "暂停并退出?")
diff --git a/freevideo_engine/launcher_session.py b/freevideo_engine/launcher_session.py
index 3d59b4c..1554f79 100644
--- a/freevideo_engine/launcher_session.py
+++ b/freevideo_engine/launcher_session.py
@@ -1,6 +1,5 @@
"""Widget-independent state for the Qt launcher; uses the existing installer."""
import json
-import locale
import os
from pathlib import Path
import threading
@@ -11,9 +10,10 @@ from . import __version__
from .comfy_launcher_runtime import Controller, layout, local_url, new_layout
from .desktop_runtime import launcher_root, materialize_source
from .download_settings import Probe, read as download_preferences, speed_text
-from .launcher_settings import Store
+from .launcher_settings import Store, default_language
from .launcher_terminal import Tail
from .model_status import FAMILIES, NAMES
+from .model_guidance import package_instructions, video_instructions, runtime_packages_supported
from .setup_progress import progress_text
from .terminal_ui import clean, duration
@@ -38,6 +38,7 @@ class Session:
update_checked = 0.
page = 'comfy'
selected = installed_versions = None
+ release_details = None
def __init__(self, source=None, *, controller=None, store=None, updater=None, smoke=False):
from .offline_packages import Importer
@@ -56,10 +57,12 @@ class Session:
self.form['environment_method'] = 'manual'
if self.form['model_method'] == 'reuse':
self.form['model_method'] = 'manual' if self.form['offline_runtime'] else 'auto'
+ if not runtime_packages_supported():
+ self.form.update(environment_method='auto', offline_runtime='')
self.form['engine'] = os.environ.get('FREEVIDEO_HOME') or self.form['engine']
if saved.get('comfy') and 'new_comfy' not in saved:
self.form['new_comfy'] = False
- self.language = saved.get('language', (locale.getlocale()[0] or '').lower())
+ self.language = saved['language'] if 'language' in saved else default_language()
self.selected = saved.get('installation')
self.saved_setup = saved.get('setup', {})
self.page = 'comfy'
@@ -152,6 +155,9 @@ class Session:
value = bool(value)
if key == 'environment_method' and value not in ('auto', 'manual'):
raise ValueError('Unknown environment installation method')
+ if key == 'environment_method' and value == 'manual' and not runtime_packages_supported():
+ raise ValueError(self.t('The Mac environment is prepared automatically. Import model packages in the next step.',
+ 'Mac 运行环境由安装器自动准备,请在下一步导入模型包。'))
if key == 'model_method' and value not in ('auto', 'manual', 'reuse'):
raise ValueError('Unknown model download method')
if self.form[key] == value:
@@ -192,6 +198,8 @@ class Session:
self.error = ''
def activate_offline(self, root):
+ from .offline_packages import check_runtime_platform
+ check_runtime_platform()
from .portable_launcher import PortableController
controller = PortableController(root)
controller.restore({'url': self.form['url']})
@@ -422,11 +430,11 @@ class Session:
self.queue_state = None
row = self.updater.state if self.updater else {}
if self.updater and row.get('candidate') and row.get('status') != 'checking':
- if self.updater.current.get('packaging') == 'onedir':
- from .launcher_update import RELEASE_PAGE
+ if self.updater.current.get('packaging') in ('onedir', 'app'):
+ from .launcher_update import release_page
from .windows_ux import open_browser
self.update_intent = None
- open_browser(RELEASE_PAGE)
+ open_browser(release_page(self.updater.current))
return
self._unsnooze()
self.update_intent = 'launcher'
@@ -604,13 +612,18 @@ class Session:
return self.source_stamp((self.selected or {}).get('source'))[0]
def update_view(self):
+ from .release_notes import installed_details, public_details
+ if self.release_details is None:
+ self.release_details = installed_details(Path(__file__).parent, __version__)
row = dict(self.updater.state) if self.updater else dict(status='development')
# Only display fields from the update manifest, never access tokens.
view = {k: row[k] for k in ('status', 'error', 'progress', 'candidate') if k in row}
key = self.update_key()
view.update(engine=self.engine_update_pending(), current=__version__,
+ current_release=public_details(self.updater.current) if self.updater else self.release_details,
installed=self.installed_version(), phase=self.update_phase(), key=key,
- manual=bool(self.updater and self.updater.current.get('packaging') == 'onedir'))
+ channel=self.updater.current.get('channel') if self.updater else None,
+ manual=bool(self.updater and self.updater.current.get('packaging') in ('onedir', 'app')))
due = ((view.get('candidate') and row['status'] in ('available', 'ready', 'error'))
or (view['engine'] and self.page == 'launcher'))
view['remind'] = bool(key and due and self.update_snoozed.get(key, 0) <= time.monotonic()
@@ -621,11 +634,12 @@ class Session:
if not self.bridge:
return
view = self.update_view()
+ from .release_notes import public_details
candidate = view.get('candidate') or {}
value = dict(version=__version__, phase=view['phase'], status=view.get('status'),
- progress=view.get('progress'), manual=view['manual'],
- candidate=dict(version=candidate['version']) if candidate.get('version') else None,
- engine=dict(pending=view['engine'], version=__version__, installed=view['installed']),
+ progress=view.get('progress'), manual=view['manual'], channel=view['channel'],
+ candidate=public_details(candidate) if candidate.get('version') else None,
+ engine=dict(view['current_release'], pending=view['engine'], installed=view['installed']),
error=str(view.get('error') or '')[:500])
now = time.monotonic()
last, previous = self.bridge_written
@@ -792,7 +806,10 @@ class Session:
ok=entry.get('ok', False), rate=speed_text(entry, self.language.startswith('zh'))))
return dict(version=__version__, zh=self.language.startswith('zh'), form=dict(self.form),
page=self.page, status=row.get('status', 'idle'), busy=self.controller.busy or self.importer.busy,
- offline=dict(progress_view(self.importer.state, zh), runtime=bool(self.form['offline_runtime']), models=len(self.form['offline_models'])),
+ offline=dict(progress_view(self.importer.state, zh), runtime=bool(self.form['offline_runtime']),
+ runtime_supported=runtime_packages_supported(),
+ models=len(self.form['offline_models']), guide=package_instructions(self.form['new_comfy'], zh)),
+ video_model_guide=video_instructions(zh),
selected=bool(self.selected), error=error, notice=self.notice, compatibility=self.compatibility,
report=dict(self.report),
models=models, overall=overall, progress=progress, detail=clean(progress.get('detail', '')),
diff --git a/freevideo_engine/launcher_settings.py b/freevideo_engine/launcher_settings.py
index 191afaf..a06e50f 100644
--- a/freevideo_engine/launcher_settings.py
+++ b/freevideo_engine/launcher_settings.py
@@ -2,6 +2,7 @@
import json
import os
from pathlib import Path
+import sys
import time
from .monitoring import save
@@ -10,6 +11,19 @@ TEXT = ('comfy', 'destination', 'engine', 'models', 'python', 'url', 'language',
SELECTION = ('root', 'engine', 'source', 'python', 'url')
+def default_language():
+ if sys.platform == 'darwin':
+ from .macos_preferences import preferred_language
+ try:
+ language = preferred_language()
+ if language:
+ return language
+ except (OSError, AttributeError, ValueError):
+ pass
+ import locale
+ return (locale.getlocale()[0] or '').lower()
+
+
def sanitize(value):
value = value if isinstance(value, dict) else {}
result = {k: value[k] for k in TEXT if isinstance(value.get(k), str)}
diff --git a/freevideo_engine/launcher_update.py b/freevideo_engine/launcher_update.py
index c8c3251..935324d 100644
--- a/freevideo_engine/launcher_update.py
+++ b/freevideo_engine/launcher_update.py
@@ -24,18 +24,37 @@ CHANNEL = 'windows-preview'
API = 'https://api.github.com/repos/' + REPOSITORY
RELEASE_PAGE = 'https://github.com/' + REPOSITORY + '/releases/tag/' + CHANNEL
MAX_EXE_BYTES = 512 * 2**20
+MAC_CHANNEL = 'macos-preview'
+
+
+def build_target(value):
+ """Legacy identities are Windows x64; never mix host update artifacts."""
+ return value.get('target', 'windows-x86_64')
+
+
+def release_page(current):
+ return 'https://github.com/' + REPOSITORY + '/releases/tag/' + build_identity(current)['channel']
def build_identity(value):
if (not isinstance(value, dict) or value.get('repository') != REPOSITORY
- or value.get('channel') != CHANNEL or value.get('schema') != 1
+ or value.get('channel') not in (CHANNEL, MAC_CHANNEL) or value.get('schema') != 1
or not re.fullmatch(r'[0-9a-f]{40,64}', str(value.get('revision', '')))
or type(value.get('built_at')) is not int or value['built_at'] <= 0
or not isinstance(value.get('version'), str) or len(value['version']) > 64):
raise ValueError('Invalid launcher build identity')
+ if value['channel'] == MAC_CHANNEL:
+ if value.get('target') != 'macos-arm64' or value.get('packaging') != 'app':
+ raise ValueError('Invalid Mac launcher build identity')
+ elif build_target(value) != 'windows-x86_64':
+ raise ValueError('Launcher update channel does not match its target')
result = {k: value[k] for k in ('schema', 'repository', 'channel', 'revision', 'built_at', 'version')}
if value.get('packaging') == 'onedir':
result['packaging'] = 'onedir'
+ if value['channel'] == MAC_CHANNEL:
+ result.update(target='macos-arm64', packaging='app')
+ from .release_notes import optional_fields
+ result.update(optional_fields(value))
return result
@@ -60,7 +79,9 @@ def manifest(value):
def newer(candidate, current):
- return candidate['revision'] != current['revision'] and candidate['built_at'] > current['built_at']
+ return (build_target(candidate) == build_target(current)
+ and candidate['channel'] == current['channel']
+ and candidate['revision'] != current['revision'] and candidate['built_at'] > current['built_at'])
def _trusted_url(url):
@@ -120,16 +141,21 @@ def _json(url, token, *, binary=False, limit=2**20):
return json.loads(b''.join(_bytes(response, limit)))
-def latest_release(token=''):
+def latest_release(token='', *, channel=CHANNEL):
"""Read and validate the published build without downloading an executable."""
- release = _json(API + '/releases/tags/' + CHANNEL, token)
- if not isinstance(release, dict) or release.get('draft') or release.get('tag_name') != CHANNEL:
- raise ValueError('No published Windows update is available')
+ if channel not in (CHANNEL, MAC_CHANNEL):
+ raise ValueError('Unknown launcher update channel')
+ release = _json(API + '/releases/tags/' + channel, token)
+ if not isinstance(release, dict) or release.get('draft') or release.get('tag_name') != channel:
+ raise ValueError('No published update is available for this platform')
assets = {a.get('name'): a for a in release.get('assets', []) if isinstance(a, dict)}
- metadata, executable = assets.get('update.json', {}), assets.get('FreeVideo.exe', {})
+ metadata, executable = assets.get('update.json', {}), assets.get(
+ 'FreeVideo-Mac-arm64.dmg' if channel == MAC_CHANNEL else 'FreeVideo.exe', {})
if type(metadata.get('id')) is not int:
raise ValueError('Update metadata is not published yet; check the release page')
candidate = manifest(_json(API + '/releases/assets/' + str(metadata['id']), token, binary=True, limit=65536))
+ if candidate['channel'] != channel:
+ raise ValueError('Update metadata belongs to a different platform')
if candidate['asset']['id'] != executable.get('id') or candidate['asset']['bytes'] != executable.get('size'):
raise ValueError('A new release is being published; check again shortly')
return candidate
@@ -137,7 +163,7 @@ def latest_release(token=''):
def check(current, token=''):
build_identity(current)
- candidate = latest_release(token)
+ candidate = latest_release(token) if current['channel'] == CHANNEL else latest_release(token, channel=current['channel'])
return candidate if newer(candidate, current) else None
@@ -158,7 +184,8 @@ def verified(path, asset):
def executable_path(root, candidate):
- return Path(root).absolute().resolve() / 'updates' / candidate['asset']['sha256'] / 'FreeVideo.exe'
+ filename = 'FreeVideo-Mac-arm64.dmg' if build_target(candidate) == 'macos-arm64' else 'FreeVideo.exe'
+ return Path(root).absolute().resolve() / 'updates' / candidate['asset']['sha256'] / filename
def download(candidate, root, token='', *, progress=None, cancel=None):
@@ -201,6 +228,8 @@ class DownloadedLauncherUnavailable(ValueError):
def launch_download(candidate, root, *, token='', popen=None):
candidate = manifest(candidate)
+ if build_target(candidate) == 'macos-arm64':
+ raise ValueError('Mac update activation is not available in this development build')
path = executable_path(root, candidate)
if not verified(path, candidate['asset']):
raise DownloadedLauncherUnavailable('Downloaded launcher is missing or changed; download again')
@@ -220,7 +249,7 @@ def launch_download(candidate, root, *, token='', popen=None):
def forward_approved(current, root):
"""Opening the original shortcut starts the last approved newer EXE."""
- if current.get('packaging') == 'onedir':
+ if current.get('packaging') in ('onedir', 'app'):
return False # Keep the user's folder distribution; do not switch to onefile.
try:
receipt = json.loads((Path(root)/'updates/active.json').read_text(encoding='utf-8'))
@@ -308,8 +337,9 @@ class UpdateClient:
return
if operation not in ('check', 'download'):
raise ValueError('Unknown update operation')
- if operation == 'download' and self.current.get('packaging') == 'onedir':
- raise ValueError('Download and extract the updated folder ZIP from the release page')
+ if operation == 'download' and self.current.get('packaging') in ('onedir', 'app'):
+ kind = 'application' if self.current.get('packaging') == 'app' else 'folder'
+ raise ValueError('Download and extract the updated %s ZIP from the release page' % kind)
self.cancelled.clear()
quiet = background and operation == 'check'
if not quiet:
diff --git a/freevideo_engine/lora_cache.py b/freevideo_engine/lora_cache.py
index 0485339..7f9523a 100644
--- a/freevideo_engine/lora_cache.py
+++ b/freevideo_engine/lora_cache.py
@@ -178,7 +178,7 @@ def prepare(cache, adapters, output_root=None):
manifest = json.loads(manifest_path.read_text(encoding='utf-8'))
if manifest.get('precision') != 'fp8':
raise ValueError('LoRA variants require the prepared FP8 model')
- from .adaln_assets import SLIM_FORMAT, restore_projections
+ from .adaln_assets import SLIM_FORMATS, restore_projections
from .export_slim import embedding_hash, share
changes_modulation = False
changes_embedding = False
@@ -206,7 +206,7 @@ def prepare(cache, adapters, output_root=None):
if (stamp != current or not reliable) and digest(path) != group['sha256']:
raise ValueError('Adapter cache changed: ' + str(path))
return output, {'enabled': True, 'cache_hit': True, 'cache': str(output), 'identity': identity}
- if manifest.get('format') == SLIM_FORMAT and (changes_modulation or changes_embedding):
+ if manifest.get('format') in SLIM_FORMATS and (changes_modulation or changes_embedding):
# Ordinary attention/FF LoRAs keep the fixed tables. Only adapters that
# actually change modulation need the optional original projection data.
originals = restore_projections(cache, manifest)
diff --git a/freevideo_engine/macos_bootstrap.py b/freevideo_engine/macos_bootstrap.py
new file mode 100644
index 0000000..f9987bb
--- /dev/null
+++ b/freevideo_engine/macos_bootstrap.py
@@ -0,0 +1,192 @@
+"""Apple Silicon bootstrap data and tool acquisition, separate from CUDA pins.
+
+The caller supplies the shared installer's fetch/progress/cancellation service.
+This prepares one tool; it does not declare a model installation ready.
+"""
+from pathlib import Path
+import json
+import math
+import os
+import platform
+import shutil
+import subprocess
+import sys
+
+from . import network
+from .uv_bootstrap import extract, verified, wheel_url
+
+PYTHON_VERSION = '3.12.3'
+UV = dict(version='0.9.0', filename='uv-0.9.0-py3-none-macosx_11_0_arm64.whl',
+ sha256='b900e84d992a657e16371426dbb030ab031c0322a604b632dada34401ebe7145',
+ bytes=18207114, executable='uv-0.9.0.data/scripts/uv', executable_bytes=41368656,
+ sources=dict(official='https://files.pythonhosted.org/packages/8e/06/f5e38314e318bfaa20ccce966f6d0a69b093854648d31085b2d8b2097aab/uv-0.9.0-py3-none-macosx_11_0_arm64.whl'))
+
+
+def require_native():
+ if sys.platform != 'darwin' or platform.machine() != 'arm64':
+ raise RuntimeError('The Mac runtime requires native Apple Silicon; use the platform installer')
+
+
+def constraints():
+ return Path(__file__).resolve().parents[1] / 'constraints' / 'macos-runtime.txt'
+
+
+def versions(value):
+ # Keep the pinned GitHub route probe independent of native uv delivery.
+ # The native executable is always obtained from the verified PyPI wheel.
+ return dict(value, target_system='Darwin', python=PYTHON_VERSION,
+ uv=dict(UV, url=UV['sources']['official']), github_probe_url=value['uv']['url'])
+
+
+def available_git():
+ executable = shutil.which('git')
+ if not executable:
+ return None
+ try:
+ # /usr/bin/git can be Apple's tool launcher before the developer tools
+ # are installed. Check selection first so inventory cannot open its
+ # installation dialog. Independently installed Git needs no Apple tools.
+ if Path(executable).resolve() == Path('/usr/bin/git'):
+ selected = subprocess.run(['/usr/bin/xcode-select', '--print-path'],
+ stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=5)
+ if selected.returncode or not selected.stdout.strip():
+ return None
+ version = subprocess.run([executable, '--version'], stdout=subprocess.PIPE,
+ stderr=subprocess.DEVNULL, text=True, timeout=5)
+ if version.returncode == 0 and version.stdout.startswith('git version '):
+ return executable
+ except (OSError, subprocess.TimeoutExpired):
+ pass
+ return None
+
+
+def inventory():
+ require_native()
+ from .macos_memory import chip_name, memory_status
+ memory = memory_status()
+ hardware = dict(gpu_name=chip_name(), system='Darwin', device_backend='mps',
+ memory_model='unified', ram_total=memory['total_bytes'], ram_available=memory['available_bytes'])
+ return dict(hardware=hardware, selected_device=dict(backend='mps', name=hardware['gpu_name'],
+ unified_ram_bytes=hardware['ram_total']), machine=platform.machine(),
+ platform=platform.platform(), kernel=platform.release(), cpu_threads=os.cpu_count(),
+ system_memory=memory, git=available_git())
+
+
+def preflight(args, snapshot=None, *, ram_gib=None, vram_gib=None):
+ snapshot = inventory() if snapshot is None else snapshot
+ hardware = snapshot['hardware']
+ errors = []
+ if hardware.get('system') != 'Darwin' or snapshot.get('machine') != 'arm64':
+ errors.append('Mac setup requires native Apple Silicon (arm64).')
+ if getattr(args, 'environment', None) not in (None, 'unified'):
+ errors.append('Mac uses one native environment; select unified.')
+ if getattr(args, 'model_source', 'prepared') != 'prepared' or getattr(args, 'rebuild_cache', False):
+ errors.append('Mac setup uses the verified prepared model. Local source conversion is not supported.')
+ if getattr(args, 'rebuild_sage', False) or getattr(args, 'gpu', None) is not None:
+ errors.append('CUDA device and SageAttention build options do not apply to Mac.')
+ if vram_gib is not None:
+ errors.append('Mac has one unified memory pool; use --ram-gib instead of a separate VRAM limit.')
+ if not snapshot.get('git'):
+ errors.append('Git is unavailable. Install or repair Git (Apple Command Line Tools), then retry.')
+ total, available = hardware['ram_total'], hardware['ram_available']
+ if any(type(n) is not int or n < 0 for n in (total, available)) or not 0 < total or available > total:
+ raise ValueError('Invalid unified-memory observation')
+ if ram_gib is not None and (not math.isfinite(ram_gib) or ram_gib <= 0):
+ raise ValueError('RAM limit must be positive and finite')
+ reserve = 2 * 2**30
+ capacity = min(total, int(ram_gib * 2**30)) if ram_gib is not None else total
+ resources = dict(memory_model='unified', ram_system_reserve_bytes=reserve,
+ ram_budget_bytes=max(0, min(capacity, available) - reserve))
+ # This is installation supervision, not a video-capacity admission decision.
+ if resources['ram_budget_bytes'] < 2**30:
+ errors.append('Setup needs at least 3 GiB available unified memory, including its 2 GiB system reserve. Close memory-heavy applications and retry.')
+ return snapshot, resources, errors
+
+
+def dependency_status(root):
+ from . import __version__
+ required = set()
+ def requirements(path):
+ for text in path.read_text(encoding='utf-8').splitlines():
+ text = text.strip()
+ if text.startswith('-r '):
+ requirements(path.parent / text[3:])
+ elif text and not text.startswith('#'):
+ required.add(text.split('[', 1)[0].lower().replace('_', '-'))
+ requirements(constraints().with_name('macos-runtime-requirements.txt'))
+ required.update(('diffusers', 'freevideo-engine'))
+ expected = dict(line.strip().split('==', 1) for line in constraints().read_text().splitlines() if '==' in line)
+ expected['freevideo-engine'] = __version__
+ python = Path(root) / 'envs/unified/bin/python'
+ row = dict(python=str(python), exists=python.is_file(), installed={}, missing=sorted(required), mismatched={})
+ if python.is_file():
+ result = subprocess.run([str(python), '-I', '-B', '-c',
+ 'import importlib.metadata as m,json; print(json.dumps({d.metadata["Name"].lower().replace("_","-"):d.version for d in m.distributions()}))'],
+ capture_output=True, text=True, timeout=30)
+ if result.returncode:
+ row['error'] = result.stderr[-1000:]
+ else:
+ installed = json.loads(result.stdout)
+ row.update(installed={p: installed.get(p) for p in sorted(required)},
+ missing=sorted(required - installed.keys()),
+ mismatched={p: dict(installed=installed[p], required=expected[p]) for p in required
+ if p in installed and p in expected and installed[p] != expected[p]})
+ return {'unified': row}
+
+
+def environment(root, env):
+ result = dict(env)
+ for name in ('CUDA_VISIBLE_DEVICES', 'CUDA_CACHE_PATH', 'TRITON_CACHE_DIR',
+ 'TORCHINDUCTOR_CACHE_DIR', 'FREEVIDEO_FA4_OVERLAY'):
+ result.pop(name, None)
+ result.update(FREEVIDEO_DEVICE_BACKEND='mps', PYTORCH_ENABLE_MPS_FALLBACK='0',
+ PYTORCH_MPS_FAST_MATH='0', UV_NO_CONFIG='1')
+ return result
+
+
+def describe_plan(value):
+ value.update(device_backend='mps', model_scale_granularity='int8_convrot',
+ kernel_install='Native Apple MPS kernels; actual execution checked before readiness',
+ model_source_reason='Verified compact ConvRot int8 storage: int8 products on Apple M5 and newer, BF16 execution on earlier Macs',
+ first_generation_note='Unified memory is shared by macOS and the GPU. Generation uses current available memory and preserves the requested geometry and steps.',
+ steps=['Prepare isolated native Python and one shared environment',
+ 'Install pinned model code and native H3 encoder library',
+ 'Download and verify models, reusing matching local files',
+ 'Verify prepared model storage',
+ 'Execute native GPU checks and save installation configuration'])
+ value['licenses'] = value['licenses'][:2]
+
+
+def prepare_uv(root, networking, env, fetch):
+ require_native()
+ root = Path(root)
+ archive = root / 'downloads' / UV['filename']
+ destination = root / 'tools' / 'uv'
+ for cached in (archive, archive.with_name(archive.name + '.partial')):
+ if verified(cached, UV['sha256'], UV['bytes']):
+ archive = cached
+ break
+ else:
+ sources = []
+ for name in network.ordered(networking, 'pypi'):
+ for route in network.route_order(networking, 'pypi', name, env):
+ try:
+ address = wheel_url(UV, name, networking.get('timeout_seconds', 5),
+ network.route_environment(networking, 'pypi', name, env, route))
+ sources.append((name, address))
+ break
+ except (OSError, ValueError, RuntimeError):
+ network.event(networking, category='pypi', source=name, route=route,
+ file=UV['filename'], action='fallback', reason='wheel-index-unavailable')
+ if not sources:
+ raise network.DownloadError('No Mac uv source is available; cached files retained')
+ if archive.exists():
+ network.retain_partial(archive, 'hash-rejected')
+ fetch(sources[0][1], archive, UV['sha256'], size=UV['bytes'],
+ candidates=sources, category='pypi', low_speed_limit=32 * 1024, max_seconds=180, cycles=1)
+ # Always revalidate before extraction, including the fetch callback's output.
+ if not verified(archive, UV['sha256'], UV['bytes']):
+ raise ValueError('Mac uv archive failed integrity verification')
+ extract(archive, destination, UV['executable'], UV['executable_bytes'])
+ destination.chmod(0o755)
+ return destination
diff --git a/freevideo_engine/macos_compute.py b/freevideo_engine/macos_compute.py
new file mode 100644
index 0000000..ace1430
--- /dev/null
+++ b/freevideo_engine/macos_compute.py
@@ -0,0 +1,161 @@
+"""Per-stage compute partitions for the native Mac engine, sized by unified memory.
+
+Every partition below changes only how independent heads, rows and windows are
+grouped; reductions, precision, geometry, steps and seeds are unchanged.
+Larger groups mean fewer Metal dispatches: on an M5 / 24 GiB the first-pass block
+went from 4.84 s with four heads per group to 3.90 s with fourteen.
+
+Activation bytes per token come from H3's widths: a 5376-channel residual, 7168
+attention channels for Q/K/V and the softmax output, and the linear branch's
+features for each head group. Memory left after the working set retains
+streamed layers between steps, which matters once a larger GPU makes the
+compute per step short.
+"""
+GiB = 2**30
+HIDDEN, HEADS, HEAD_DIM, FF = 5376, 56, 128, 17920
+LAYER_BYTES = 856_311_776 # one decoded BF16 transformer block
+PREFETCH_BYTES = 512 << 20 # total bound for one layer, including LoRA sidecars
+RESIDENT_LIMIT = 50
+RETENTION_HEADROOM = 4 * GiB
+GROUPS = (56, 28, 14, 8, 4)
+
+
+def working_bytes(tokens, group, *, ff_chunk=4096, window_bytes=1 << 29, frames=72):
+ """Estimated peak activations of one block at `tokens` rows and `group` heads.
+
+ The linear branch also keeps FP32 [frames, heads, 128, 128] banks: A, B,
+ transitions, injections, both scan directions, the gathered state and the
+ inverse's iterates. A full 10 s first pass measured about 5.4 GiB of live
+ working memory with all 56 heads; this estimate is 5.5 GiB there."""
+ attention = HEADS * HEAD_DIM
+ shared = tokens * (HIDDEN * 2 * 3 # residual, normed input and block output
+ + attention * 2 * 3 # raw Q/K/V
+ + attention * 2) # softmax output before projection
+ per_group = tokens * group * HEAD_DIM * (2 * 2 # normalized Q/K
+ + 2 * 3 # MLX copies of Q/K/V (same pool)
+ + 2 * 3 # linear features
+ + 4 * 2) # FP32 statistics operands
+ banks = frames * group * HEAD_DIM * HEAD_DIM * 4 * 6
+ ff = ff_chunk * FF * 2 * 2
+ return shared + per_group + banks + ff + window_bytes
+
+
+# Fastest first. The tail keeps the reference engine's small row chunks for the
+# tightest allowances, where a 4096-row FF chunk alone needs 0.27 GiB.
+CANDIDATES = tuple((group, 4096, 1 << 29) for group in GROUPS) + ((4, 1024, 1 << 28), (4, 256, 1 << 27))
+
+
+def bounded_working_bytes(tokens, *, frames=72):
+ """Conservative working estimate for the four-head/256-row owned profile.
+
+ Unlike the original adapter, grouped projections retain two full attention
+ outputs (softmax and linear), but only one group's raw Q/K/V. Full RMSNorm
+ reductions remain: their full-size inputs/outputs must still be counted.
+ This estimate includes MLX and host prefetch allowances through the planner;
+ fitting a PyTorch allocator cap alone does not validate this unified budget.
+ """
+ if any(type(value) is not int or value <= 0 for value in (tokens, frames)):
+ raise ValueError('Bounded planning needs positive integer row and frame counts')
+ group, chunk, window = CANDIDATES[-1]
+ hidden = tokens * HIDDEN * 2
+ attention = tokens * HEADS * HEAD_DIM * 2
+ # Residual and normalized input coexist with both full attention outputs.
+ # Allow eight BF16 group planes for raw projections, features, contiguity
+ # preparation and readout; softmax and linear-leg temporaries do not overlap.
+ grouped = tokens * group * HEAD_DIM * 2 * 8
+ banks = frames * group * HEAD_DIM * HEAD_DIM * 4 * 6
+ # Frame-statistic casts and means are explicitly bounded in mps_linear.
+ scratch = (16 + 32) << 20
+ row_temporaries = chunk * (HIDDEN * 2 * 5 + FF * 2 * 2)
+ return 2 * hidden + 2 * attention + grouped + banks + window + scratch + row_temporaries
+
+
+def sequence_tokens(canvas, prompt_rows):
+ """Count all packed rows with the pinned audio clock and validated references."""
+ from diffusers.modular_pipelines.minimax_h3.modular_pipeline import (
+ MINIMAX_H3_AUDIO_CHANNELS, audio_latent_num_frames)
+ if type(prompt_rows) is not int or prompt_rows <= 0:
+ raise ValueError('Compute planning needs the actual positive prompt row count')
+ rows = dict(text=prompt_rows, video=canvas['video_tokens'],
+ audio=MINIMAX_H3_AUDIO_CHANNELS * audio_latent_num_frames(canvas['frames']),
+ reference_video=canvas.get('reference_video_tokens', 0),
+ reference_audio=canvas.get('reference_audio_tokens', 0))
+ if any(type(value) is not int or value < 0 for value in rows.values()):
+ raise ValueError('Packed row counts must be nonnegative integers')
+ return dict(rows, total=sum(rows.values()))
+
+
+def plan(budget_bytes, tokens, *, frames=72, reserve_bytes=GiB, layers=50,
+ allow_retention=True, allow_bounded=False):
+ """Head group, row chunks and retained-layer bytes for one sampling stage."""
+ if type(budget_bytes) is not int or budget_bytes <= 0 or type(tokens) is not int or tokens <= 0:
+ raise ValueError('Compute planning needs a positive byte budget and token count')
+ if type(allow_bounded) is not bool:
+ raise ValueError('Bounded planning must be explicitly enabled or disabled')
+ available = budget_bytes - reserve_bytes - LAYER_BYTES - PREFETCH_BYTES
+ # Keep a tenth of the allowance unplanned for allocator fragmentation.
+ group, chunk, window = next(((g, c, w) for g, c, w in CANDIDATES
+ if working_bytes(tokens, g, ff_chunk=c, window_bytes=w, frames=frames)
+ <= .9 * available),
+ CANDIDATES[-1])
+ working = working_bytes(tokens, group, ff_chunk=chunk, window_bytes=window, frames=frames)
+ # The candidate is opt-in until native complete-product acceptance. Cover
+ # only the smallest existing partition; do not increase head/FF groups or
+ # spend the released buffers on additional retained weights.
+ bounded = allow_bounded and (group, chunk, window) == CANDIDATES[-1]
+ if bounded:
+ working = bounded_working_bytes(tokens, frames=frames)
+ # A retained layer saves one 0.12 s load per step on an M5, against 2.7 s
+ # of compute: only spend memory the system will not miss. The first 4 GiB
+ # beyond the working set stay free for other applications and the OS file
+ # cache; on a 24 GiB Mac, retaining 14 layers pushed it into swap.
+ spare = max(0, available - working - RETENTION_HEADROOM)
+ retained = min(layers, RESIDENT_LIMIT, spare // LAYER_BYTES) if allow_retention and not bounded else 0
+ result = dict(head_chunk=group, attention_chunk=chunk, ff_chunk=chunk, window_batch=64,
+ attention_batch_bytes=window,
+ resident_bytes=int(retained * LAYER_BYTES), retained_layers=int(retained),
+ estimated_working_bytes=int(working), budget_bytes=int(budget_bytes),
+ fits=working <= available,
+ scope='Grouping of independent heads, rows and windows; reductions unchanged.')
+ if bounded:
+ result.update(bounded_buffers=True,
+ scope='Grouped projections and owned intermediate buffers; unified working estimate is not a physical capacity result.')
+ return result
+
+
+def shared_sampling_plan(budget_bytes, sampling, prompt_rows, *, phase_reference_tokens=None):
+ """Candidate cross-pass lifetime from an already enforced allocator cap.
+
+ The caller validates conditioning and supplies its per-pass reference rows.
+ Actual per-pass admission and
+ pressure checks still run before sampling; this predicts whether retaining
+ weights across the boundary can help, not physical workload capacity.
+ """
+ from .geometry import geometry
+ if type(budget_bytes) is not int or budget_bytes <= 0:
+ raise ValueError('Shared sampling needs an enforced positive byte budget')
+ if type(prompt_rows) is not int or prompt_rows <= 0:
+ raise ValueError('Shared sampling needs the actual positive prompt row count')
+ if phase_reference_tokens is not None:
+ if (not isinstance(phase_reference_tokens, dict)
+ or set(phase_reference_tokens) != {'first-pass', 'refinement'}
+ or any(not isinstance(row, dict)
+ or set(row) - {'reference_video_tokens', 'reference_audio_tokens'}
+ or any(type(n) is not int or n < 0 for n in row.values())
+ for row in phase_reference_tokens.values())):
+ raise ValueError('Shared sampling needs both validated per-pass reference token counts')
+ if not sampling['enabled']:
+ return dict(eligible=False, reason='single-pass', budget_bytes=budget_bytes)
+ phases = {}
+ for phase, key in (('first-pass', 'first'), ('refinement', 'second')):
+ canvas = geometry(**sampling[key])
+ if phase_reference_tokens is not None:
+ canvas.update(phase_reference_tokens[phase])
+ rows = sequence_tokens(canvas, prompt_rows)
+ phases[phase] = plan(budget_bytes, rows['total'], frames=canvas['latent_frames'])
+ phases[phase]['packed_rows'] = rows
+ eligible = all(p['fits'] and p['retained_layers'] > 0 for p in phases.values())
+ return dict(eligible=eligible, reason='retained-weights-in-both-passes' if eligible else
+ 'no-cross-pass-retention-allowance', budget_bytes=budget_bytes, phases=phases,
+ refinement_resident_bytes=phases['refinement']['resident_bytes'],
+ scope='Enforced live cap and actual text rows; per-pass planning and pressure reclamation remain active.')
diff --git a/freevideo_engine/macos_decode.py b/freevideo_engine/macos_decode.py
new file mode 100644
index 0000000..e6ed00b
--- /dev/null
+++ b/freevideo_engine/macos_decode.py
@@ -0,0 +1,144 @@
+"""MPS H3 decoding through the shared bounded readers and RGB writer."""
+import gc
+import json
+from pathlib import Path
+import time
+
+
+def weight_cache_limits(allocator_bytes):
+ """Bound optional retained weights by the actual admitted Metal capacity."""
+ if type(allocator_bytes) is not int or allocator_bytes <= 0:
+ raise ValueError('Decoder cache requires a positive admitted byte limit')
+ # At 6 GiB the native decoder evicted 17 of 23 preloaded layers and loaded
+ # 562 layers, versus 216 with the active-layer schedule. The 8 GiB retained
+ # path loaded only 63 and was faster. Keep the 5 GiB cache plus 3 GiB of
+ # workspace together; partial preloading below that point causes churn.
+ retained = 0 if allocator_bytes < 8 * 2**30 else min(5 * 2**30, allocator_bytes - 3 * 2**30)
+ return dict(resident_bytes=retained,
+ working_reserve_bytes=2 * 2**30)
+
+
+def tile_group_size(allocator_bytes, *, cache_weights=True):
+ """Reuse streamed layers when the admitted allowance cannot retain a set."""
+ limits = weight_cache_limits(allocator_bytes)
+ if type(cache_weights) is not bool:
+ raise ValueError('Decoder weight caching must be explicitly enabled or disabled')
+ # Four simultaneous tile states were measured at 4 GiB. Smaller admitted
+ # allowances keep one tile's activations instead of assuming those fit.
+ return 4 if cache_weights and allocator_bytes >= 4 * 2**30 and not limits['resident_bytes'] else 0
+
+
+def decode_to_file(latents, audio_latents, output, *, base, artifacts_dir,
+ budget_bytes=4 * 2**30, reserve_bytes=2 * 2**30, cache_weights=True):
+ if type(cache_weights) is not bool:
+ raise ValueError('Decoder weight caching must be explicitly enabled or disabled')
+ from .macos_vdn import activate
+ activate()
+ import torch
+ import numpy as np
+ from diffusers import AutoencoderKLMiniMaxH3
+ from diffusers.utils.export_utils import encode_video
+ from src.inference.render import PIXEL_MEAN, PIXEL_STD, FPS
+ from .backends import get_backend
+ from .vae_weights import skeleton, load_parameters, load_audio_vae
+ from .decode_stream import render_rgb
+ from .system import system_memory
+ backend = get_backend('mps')
+ policy = backend.configure_budget(budget_bytes, reserve_bytes=reserve_bytes)
+ cache_options = (dict(weight_cache_limits(policy['effective_allocator_limit_bytes']),
+ linear_dtype=torch.float16, preload=True) if cache_weights else {})
+ tile_group = tile_group_size(policy['effective_allocator_limit_bytes'], cache_weights=cache_weights)
+ output, artifacts_dir, base = Path(output), Path(artifacts_dir), Path(base)
+ artifacts_dir.mkdir(parents=True, exist_ok=True)
+ started = time.monotonic()
+ vae = video_decoder = audio_vae = frames = mapping = None
+ handles, specs = [], []
+ def phase(text):
+ print(json.dumps(dict(event='decode_phase', phase=text)), flush=True)
+ def guard(module, inputs):
+ if system_memory()['available_bytes'] < 2**30:
+ raise MemoryError('MPS decoding reached the 1 GiB physical RAM emergency floor')
+ def finite_video(module, inputs, output):
+ if not bool(output.isfinite().all()):
+ raise ValueError('MPS video decoder produced nonfinite pixels')
+ try:
+ with torch.no_grad():
+ phase('Loading video VAE')
+ vae = skeleton(AutoencoderKLMiniMaxH3, base / 'vae')
+ vae.encoder = vae.quant_conv = None
+ paths = tuple(sorted((base / 'vae').glob('*.safetensors')))
+ load_parameters(vae, paths, device_for_name=lambda name:
+ 'meta' if name.startswith('decoder.transformer_blocks.') else 'mps',
+ linear_fp16=False, mapped=False)
+ # Constructor-computed RoPE buffers are not checkpoint parameters.
+ for name, value in list(vae.named_buffers()):
+ parent, _, leaf = name.rpartition('.')
+ setattr(vae.get_submodule(parent) if parent else vae, leaf, value.to('mps'))
+ vae.eval().requires_grad_(False)
+ from .backends.mps_vae import install_mlx_attention
+ mlx_attention = install_mlx_attention(vae)
+ handles.append(vae.decoder.register_forward_hook(finite_video))
+ for index, layer in enumerate(vae.decoder.transformer_blocks):
+ specs.append((layer, paths, f'decoder.transformer_blocks.{index}.', ()))
+ handles.append(layer.register_forward_pre_hook(guard))
+ mean = torch.tensor(vae.config.latents_mean, device='mps').view(1, -1, 1, 1, 1)
+ std = torch.tensor(vae.config.latents_std, device='mps').view(1, -1, 1, 1, 1)
+ phase('Decoding video tiles')
+ def progress(done, total, elapsed):
+ print(json.dumps(dict(event='decode_progress', done=done, total=total,
+ elapsed_seconds=elapsed)), flush=True)
+ if tile_group:
+ from .macos_decode_tiles import TileDecoder
+ residency = video_decoder = TileDecoder(vae, backend, specs, group_tiles=tile_group)
+ else:
+ residency = backend.make_offloader(specs, linears={}, **cache_options)
+ video_decoder = vae
+ with residency, \
+ torch.autocast(device_type='mps', dtype=torch.float16, cache_enabled=False):
+ frames, mapping, timings = render_rgb(video_decoder, latents.to('mps') * std + mean,
+ PIXEL_MEAN, PIXEL_STD, artifacts_dir / 'rgb.npy', progress=progress)
+ video_residency = residency.stats()
+ for handle in handles:
+ handle.remove()
+ handles.clear()
+ specs.clear()
+ residency.specs.clear()
+ del mean, std
+ layer = value = None
+ vae = video_decoder = None
+ gc.collect()
+ backend.empty_cache()
+ phase('Loading and decoding audio')
+ audio_vae, audio_loading = load_audio_vae(base, device='mps')
+ mean = torch.tensor(audio_vae.config.latents_mean, device='mps').view(1, -1, 1)
+ std = torch.tensor(audio_vae.config.latents_std, device='mps').view(1, -1, 1)
+ audio = audio_vae.decode(audio_latents.to('mps') * std + mean, return_dict=False)[0]
+ audio = audio.float().permute(1, 0, 2)[0].cpu()
+ backend.synchronize()
+ if not bool(audio.isfinite().all()):
+ raise ValueError('MPS audio decoder produced nonfinite samples')
+ rate = audio_vae.config.sampling_rate
+ np.save(artifacts_dir / 'audio.npy', audio.numpy(), allow_pickle=False)
+ audio_vae = None
+ del mean, std
+ gc.collect()
+ backend.empty_cache()
+ phase('Saving MP4 and audio')
+ output.parent.mkdir(parents=True, exist_ok=True)
+ temporary = output.with_name(output.stem + '.partial' + output.suffix)
+ encode_video(frames, fps=FPS, output_path=str(temporary), audio=audio, audio_sample_rate=rate)
+ temporary.replace(output)
+ return dict(device_backend='mps', output=str(output), frames=len(frames),
+ audio_sample_rate=rate, audio_shape=list(audio.shape), elapsed_seconds=time.monotonic()-started,
+ policy=policy, video_residency=video_residency, audio_loading=audio_loading, timings=timings,
+ precision='FP32 checkpoint; FP16 video autocast; FP32 audio decoder',
+ mlx_attention_modules=mlx_attention)
+ finally:
+ for handle in handles:
+ handle.remove()
+ specs.clear()
+ vae = video_decoder = audio_vae = frames = None
+ if mapping is not None:
+ mapping._mmap.close()
+ gc.collect()
+ backend.empty_cache()
diff --git a/freevideo_engine/macos_decode_tiles.py b/freevideo_engine/macos_decode_tiles.py
new file mode 100644
index 0000000..fce82d7
--- /dev/null
+++ b/freevideo_engine/macos_decode_tiles.py
@@ -0,0 +1,159 @@
+# Copyright 2026 The MiniMax and HuggingFace Teams. All rights reserved.
+# Copyright 2026 FreeVideo contributors.
+# Licensed under the Apache License, Version 2.0.
+"""Mac decoder scheduling: reuse one layer across original, unbatched tiles.
+
+The decoder preparation/output equations are adapted from the pinned Diffusers
+AutoencoderKLMiniMaxH3 at OpenVDN 30b6b380c2482f3519469350810c2955d8847fd9.
+Tile geometry, per-tile operator shapes and the original stitching are retained.
+Temporal chunks and spatial stitching continue to use the shared decoder plan.
+"""
+import torch
+import time
+
+from .backends.mps_weights import load_group, release_group
+
+
+def prepare_tile(decoder, hidden):
+ batch, channels, frames, height, width = hidden.shape
+ hidden = hidden.permute(0, 2, 3, 4, 1).reshape(batch, frames * height * width, channels)
+ hidden = decoder.proj_in(hidden)
+ patches = hidden.shape[1]
+ registers = decoder.register_tokens.expand(batch, -1, -1)
+ cls = torch.zeros_like(hidden[:, :1, :])
+ hidden = torch.cat([hidden, registers, cls], dim=1)
+ grids = [2.0 * (torch.arange(0.5, size, dtype=torch.float32, device=hidden.device) / size) - 1.0
+ for size in (frames, height, width)]
+ positions = torch.stack(torch.meshgrid(*grids, indexing='ij'), dim=-1).flatten(0, 2)
+ positions = positions.unsqueeze(0).expand(batch, -1, -1)
+ suffix = positions.new_zeros((batch, decoder.num_register_tokens + 1, 3))
+ positions = torch.cat([positions, suffix], dim=1)
+ return dict(hidden=hidden, rotary=decoder.rope(positions), patches=patches,
+ shape=(batch, frames, height, width))
+
+
+def finish_tile(decoder, state):
+ hidden = decoder.norm_out(state['hidden'])
+ hidden = decoder.proj_out(hidden)
+ hidden = hidden[:, :state['patches'], :]
+ batch, frames, height, width = state['shape']
+ patch, temporal = decoder.patch_size, decoder.patch_size_t
+ hidden = hidden.view(batch, frames, height, width, decoder.out_channels, temporal, patch, patch)
+ hidden = hidden.permute(0, 4, 1, 5, 2, 6, 3, 7).contiguous()
+ output = hidden.reshape(batch, decoder.out_channels, frames * temporal, height * patch, width * patch)
+ if not bool(output.isfinite().all()):
+ raise ValueError('Tile-layer decoder produced nonfinite pixels')
+ return output
+
+
+def decode_clip(vae, z, apply_layer, *, group_tiles):
+ if torch.is_grad_enabled() or vae.decoder.gradient_checkpointing:
+ raise ValueError('Tile-layer scheduling requires inference without gradient checkpointing')
+ if type(group_tiles) is not int or group_tiles < 1:
+ raise ValueError('Tile group must be a positive integer')
+ if not vae.use_tiling:
+ return vae.decoder(vae.post_quant_conv(z))
+ ratio = vae.spatial_compression_ratio
+ ys, heights, overlaps_y = vae._split_tiles(z.shape[-2] * ratio,
+ vae.tile_sample_min_height, vae.tile_sample_min_overlap_height)
+ xs, widths, overlaps_x = vae._split_tiles(z.shape[-1] * ratio,
+ vae.tile_sample_min_width, vae.tile_sample_min_overlap_width)
+ positions = [(row, col, y, h, x, w) for row, (y, h) in enumerate(zip(ys, heights))
+ for col, (x, w) in enumerate(zip(xs, widths))]
+ outputs = [[None] * len(xs) for _ in ys]
+ for begin in range(0, len(positions), group_tiles):
+ locations = positions[begin:begin + group_tiles]
+ states = [prepare_tile(vae.decoder, vae.post_quant_conv(
+ z[..., y // ratio:(y + h) // ratio, x // ratio:(x + w) // ratio]))
+ for _, _, y, h, x, w in locations]
+ for index, block in enumerate(vae.decoder.transformer_blocks):
+ # Each invocation has the exact original per-tile shape. Only the
+ # order of independent tiles changes; no concatenated matmul batch.
+ hidden = apply_layer(index, block, states)
+ if len(hidden) != len(states):
+ raise ValueError('Layer scheduler lost a tile')
+ for state, value in zip(states, hidden):
+ state['hidden'] = value
+ del hidden, value
+ for (row, col, *_), state in zip(locations, states):
+ outputs[row][col] = finish_tile(vae.decoder, state)
+ del states, state
+ return vae._stitch_tiles(outputs, overlaps_y, overlaps_x)
+
+
+class TileDecoder:
+ """A request-local VAE view; never replace model or module-level methods.
+
+ One active layer belongs to a whole group, then leaves before the next
+ layer is read. Each original forward still executes its pressure guard.
+ This is active work, not an optional cache between future layer visits.
+ """
+ def __init__(self, vae, backend, specs, *, group_tiles=4):
+ if type(group_tiles) is not int or not 1 <= group_tiles <= 4:
+ raise ValueError('Native decode groups require one to four original tiles')
+ if not vae.use_tiling:
+ raise ValueError('Tile scheduling requires the original tiled decoder')
+ self.vae, self.backend, self.specs = vae, backend, list(specs)
+ self.group_tiles = group_tiles
+ self.records = []
+ self.entered = False
+
+ def __getattr__(self, name):
+ return getattr(self.vae, name)
+
+ def __enter__(self):
+ if self.entered or self.vae is None:
+ raise RuntimeError('A tile decoder belongs to one request')
+ self.entered = True
+ return self
+
+ def __exit__(self, *args):
+ self.entered = False
+ self.vae = None
+ self.specs.clear()
+ return False
+
+ def _decode_clip(self, z):
+ if not self.entered:
+ raise RuntimeError('Tile decoder requires an active request scope')
+ return decode_clip(self.vae, z, self.apply, group_tiles=self.group_tiles)
+
+ def apply(self, index, block, states):
+ if not self.entered or self.specs[index][0] is not block:
+ raise ValueError('Decoder layer order or request scope changed')
+ _, paths, prefix, exclude = self.specs[index]
+ if any(not p.is_meta for name, p in block.named_parameters()
+ if not any(name.startswith(skip) for skip in exclude)):
+ raise ValueError('Decoder layer must start unloaded')
+ tick = time.monotonic()
+ record = dict(layer_loads=0, hydrated_weight_bytes=0, largest_layer_bytes=0,
+ load_seconds=0., tile_forwards=0)
+ try:
+ size = load_group(block, paths, {}, prefix=prefix, exclude=exclude,
+ device=self.backend.device, linear_dtype=torch.float16)
+ record.update(layer_loads=1, hydrated_weight_bytes=size, largest_layer_bytes=size,
+ load_seconds=time.monotonic() - tick)
+ result = []
+ for state in states:
+ result.append(block(state['hidden'], state['rotary']))
+ record['tile_forwards'] += 1
+ return result
+ finally:
+ try:
+ self.backend.synchronize()
+ finally:
+ release_group(block, exclude=exclude)
+ self.backend.empty_cache()
+ self.records.append(record)
+
+ def stats(self):
+ summed = ('layer_loads', 'hydrated_weight_bytes', 'load_seconds', 'tile_forwards')
+ value = {key: sum(row.get(key, 0) for row in self.records) for key in summed}
+ value.update(policy='One layer across original unbatched spatial tiles',
+ spatial_tile_group=self.group_tiles, layer_groups=len(self.records),
+ largest_layer_bytes=max((r['largest_layer_bytes'] for r in self.records), default=0),
+ retains_between_layer_groups=False,
+ load_seconds_scope='Host read and submission; completion is inside the group timer',
+ layer_synchronization='Group completion and failure before weight release',
+ precision='Original FP32 checkpoint; FP16 Linear compute cache')
+ return value
diff --git a/freevideo_engine/macos_doctor.py b/freevideo_engine/macos_doctor.py
new file mode 100644
index 0000000..480d2f5
--- /dev/null
+++ b/freevideo_engine/macos_doctor.py
@@ -0,0 +1,109 @@
+"""Native Mac readiness checks, independent of CUDA packages and receipts."""
+import argparse
+import importlib.metadata
+import json
+import os
+from pathlib import Path
+import sys
+import traceback
+
+
+def doctor(*, probe=False):
+ from .macos_bootstrap import require_native, inventory
+ from .paths import data_root, model_root, vdn_root
+ require_native()
+ root = data_root()
+ cached = root / 'prepared-cache.json'
+ cache = json.loads(cached.read_text()).get('cache') if cached.is_file() else None
+ locations = dict(vdn=vdn_root(), base=model_root() / 'h3-base',
+ checkpoint=model_root() / 'stage-dmd-step-250', comfy=root / 'vendor/h3-text-encoder', cache=cache)
+ result = dict(schema_version=1, device_backend='mps', hardware=inventory()['hardware'],
+ paths={k: dict(path=str(p) if p else None, exists=bool(p and Path(p).is_dir()))
+ for k, p in locations.items()}, ready=False, kernel_probes=[],
+ usable_attention_backends=[], failed_optional_backends=[],
+ validation='Small native operations only; not full-video capacity, performance or quality validation')
+ result['versions'] = {name: importlib.metadata.version(name) for name in
+ ('torch', 'torchvision', 'torchaudio', 'safetensors', 'diffusers')}
+ if not probe:
+ return result
+ try:
+ if os.environ.get('PYTORCH_MPS_FAST_MATH', '0') != '0':
+ raise ValueError('Native readiness checks require default precision (MPS fast math disabled)')
+ from .macos_vdn import activate
+ activate()
+ sys.path.insert(0, str(locations['comfy']))
+ from comfy.text_encoders import minimax # Same native encoder contract used by generation.
+ import torch
+ from .backends import get_backend
+ backend = get_backend('mps')
+ if not backend.is_available() or torch.version.cuda is not None:
+ raise RuntimeError('The installed runtime is not a native Apple MPS build')
+ result['budget'] = backend.configure_budget(2 * 2**30, reserve_bytes=2**30)
+ generator = torch.Generator().manual_seed(20261004)
+ kernels = backend.attention_kernels('mps', 'mps')
+ with torch.inference_mode():
+ for dtype in (torch.float32, torch.bfloat16):
+ q, k, v = [torch.randn(1, 31, 4, 128, generator=generator).to(dtype) for _ in range(3)]
+ actual = kernels.batched('mps', q.to('mps'), k.to('mps'), v.to('mps'), 128**-.5)
+ reference = torch.nn.functional.scaled_dot_product_attention(
+ *[t.double().transpose(1, 2) for t in (q, k, v)], scale=128**-.5).transpose(1, 2)
+ backend.synchronize()
+ relative = ((actual.cpu().double() - reference).square().mean().sqrt() /
+ reference.square().mean().sqrt().clamp_min(1e-12)).item()
+ limit = .01 if dtype == torch.bfloat16 else .0001
+ if not bool(actual.isfinite().all()) or relative > limit:
+ raise ValueError('Native attention comparison failed: ' + str(relative))
+ result['kernel_probes'].append(dict(backend='mps', dtype=str(dtype), status='complete',
+ relative_rmse=relative, relative_rmse_limit=limit))
+ from .backends.mps_fp8 import decode_weight
+ from .backends.mps_weights import decode_weight as reference_decode
+ weight = torch.randn(64, 128, generator=generator).to(torch.float8_e4m3fn)
+ scale = torch.full((1, 64), .125)
+ decoded = decode_weight(weight, scale)
+ if not torch.equal(decoded.cpu(), reference_decode(weight, scale)):
+ raise ValueError('Native weight storage decoding differs from its BF16 reference')
+ x = torch.randn(7, 128, generator=generator).bfloat16().to('mps')
+ projected = torch.nn.functional.linear(x, decoded)
+ if not bool(projected.isfinite().all()):
+ raise ValueError('Native BF16 projection produced nonfinite output')
+ result['kernel_probes'].append(dict(backend='linear', status='complete', storage_decode_exact=True))
+ from types import SimpleNamespace
+ from comfy_kitchen.float_utils import to_blocked
+ from .macos_encoder import nvfp4_weight
+ from .backends.mps_nvfp4 import decode_weight as decode_nvfp4
+ packed = torch.arange(128 * 32).remainder(256).to(torch.uint8).reshape(128, 32)
+ scales = torch.arange(128 * 4).remainder(127).to(torch.uint8).view(
+ torch.float8_e4m3fn).reshape(128, 4)
+ weight = SimpleNamespace(_qdata=packed, _params=SimpleNamespace(
+ block_scale=to_blocked(scales), scale=torch.tensor(.0379), orig_shape=(127, 61),
+ transposed=False))
+ decoded = decode_nvfp4(weight, torch.float32, 'mps').cpu().contiguous()
+ reference = nvfp4_weight(weight, torch.float32, 'cpu').contiguous()
+ if not torch.equal(decoded.view(torch.uint8), reference.view(torch.uint8)):
+ raise ValueError('Native NVFP4 decoding differs from its FP32 reference')
+ result['kernel_probes'].append(dict(backend='encoder-nvfp4', status='complete',
+ storage_decode_exact=True))
+ result.update(ready=all(row['exists'] for row in result['paths'].values()),
+ usable_attention_backends=['mps'], identity=backend.arithmetic_identity())
+ except Exception:
+ result['kernel_probes'].append(dict(backend='mps', status='error', error=traceback.format_exc()))
+ return result
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--probe', action='store_true')
+ parser.add_argument('--require-paths', action='store_true')
+ parser.add_argument('--out', type=Path)
+ args = parser.parse_args()
+ result = doctor(probe=args.probe)
+ if args.out:
+ from .monitoring import save
+ save(args.out, result)
+ print(json.dumps(result, indent=2))
+ return int((args.probe and not result['ready']) or
+ (args.require_paths and not all(row['exists'] for row in result['paths'].values())))
+
+
+if __name__ == '__main__':
+ raise SystemExit(main())
diff --git a/freevideo_engine/macos_encoder.py b/freevideo_engine/macos_encoder.py
new file mode 100644
index 0000000..ec2208b
--- /dev/null
+++ b/freevideo_engine/macos_encoder.py
@@ -0,0 +1,240 @@
+"""Native Comfy H3 conditioning with bounded weight decoding for MPS.
+
+The native tokenizer, layer-50 model, AWQ input smoothing and output contract
+remain authoritative. Quantized checkpoint storage stays on the host; MPS
+executes FP32 model operations, as the native H3 text forward requests. This
+entry point is isolated from the existing CUDA encoder worker.
+"""
+import gc
+import json
+import os
+from pathlib import Path
+import sys
+import time
+import types
+
+
+def nvfp4_weight(weight, dtype, device, *, rows=128):
+ """Decode original E2M1 storage in bounded rows using FP32 scale arithmetic."""
+ import torch
+ from comfy_kitchen.float_utils import from_blocked
+ if rows < 1 or weight._qdata.device.type != 'cpu':
+ raise ValueError('MPS NVFP4 reader requires host storage and a positive row chunk')
+ params, packed = weight._params, weight._qdata
+ if getattr(params, 'transposed', False) or packed.dtype != torch.uint8 or packed.ndim != 2:
+ raise ValueError('Unsupported NVFP4 storage layout')
+ count, columns = packed.shape[0], packed.shape[1] * 2
+ if columns % 16 or params.scale.numel() != 1:
+ raise ValueError('Invalid NVFP4 scale geometry')
+ scales = from_blocked(params.block_scale, num_rows=count, num_cols=columns // 16).float()
+ lut = torch.tensor([0., .5, 1., 1.5, 2., 3., 4., 6., -0., -.5, -1., -1.5, -2., -3., -4., -6.])
+ result = torch.empty((count, columns), dtype=dtype, device=device)
+ for start in range(0, count, rows):
+ part = packed[start:start + rows]
+ indices = torch.stack((part >> 4, part & 15), dim=-1).long()
+ decoded = lut[indices].reshape(len(part), -1, 16)
+ # CUDA's native dequantizer multiplies block scale before tensor scale.
+ decoded.mul_(scales[start:start + rows, :, None]).mul_(params.scale.float())
+ result[start:start + rows].copy_(decoded.reshape(len(part), columns).to(dtype))
+ del part, indices, decoded
+ return result[:params.orig_shape[0], :params.orig_shape[1]]
+
+
+def install_weight_reader(clip, backend, checkpoint, *, decoder=nvfp4_weight):
+ """Adapt only this encoder instance; never patch the shared Comfy library."""
+ import torch
+ from comfy.quant_ops import QuantizedTensor, get_layout_class
+ from .encoder_checkpoint import release_mapped_pages
+ from .system import system_memory
+ handles, restores = [], []
+ stats = dict(linear_calls=0, embedding_calls=0, largest_weight_bytes=0,
+ weight_decode_seconds=0., host_storage='original read-only checkpoint',
+ weight_decode_seconds_scope='Host read/decode/submit time; Metal completion is included in encoding elapsed time')
+ def guard():
+ if system_memory()['available_bytes'] < 2**30:
+ raise MemoryError('MPS encoding reached the 1 GiB physical RAM emergency floor')
+ def linear(module, input, *args, **kwargs):
+ if input.device.type != 'mps' or input.dtype != torch.float32:
+ raise ValueError('Native H3 encoder must execute FP32 operations on MPS')
+ guard()
+ tick = time.monotonic()
+ source = module.weight
+ if isinstance(source, QuantizedTensor):
+ if module.quant_format != 'nvfp4':
+ raise NotImplementedError('Unsupported MPS encoder projection storage: ' + module.quant_format)
+ weight = decoder(source, input.dtype, input.device)
+ else:
+ weight = source.to(device=input.device, dtype=input.dtype)
+ bias = module.bias.to(device=input.device, dtype=input.dtype) if module.bias is not None else None
+ stats['weight_decode_seconds'] += time.monotonic() - tick
+ stats['largest_weight_bytes'] = max(stats['largest_weight_bytes'], weight.numel() * weight.element_size())
+ try:
+ output = torch.nn.functional.linear(input, weight, bias)
+ backend.synchronize()
+ stats['linear_calls'] += 1
+ return output
+ finally:
+ del weight, bias
+ backend.empty_cache()
+ release_mapped_pages([checkpoint])
+ def embedding(module, input, out_dtype=None):
+ guard()
+ weight = module.weight
+ indices = input.cpu()
+ if isinstance(weight, QuantizedTensor):
+ if module.quant_format != 'int8_tensorwise':
+ raise NotImplementedError('Unsupported MPS encoder embedding storage')
+ value = get_layout_class(module.layout_type).dequantize_embedding(weight._qdata, weight._params, indices)
+ else:
+ value = torch.nn.functional.embedding(indices, weight)
+ stats['embedding_calls'] += 1
+ return value.to(device=input.device, dtype=out_dtype or value.dtype)
+ model = clip.cond_stage_model.qwen3vl_32b.transformer.model
+ if len(model.layers) != 50:
+ raise ValueError('Expected the native H3 encoder truncated to layer 50')
+ selected = []
+ for module in clip.cond_stage_model.modules():
+ if isinstance(module, torch.nn.Embedding):
+ function = embedding
+ elif hasattr(module, 'forward_comfy_cast_weights') and hasattr(module, 'in_features'):
+ function = linear
+ else:
+ continue
+ if getattr(module, 'weight_function', ()) or getattr(module, 'bias_function', ()):
+ raise ValueError('MPS encoder reader does not support patched weights')
+ selected.append((module, function))
+ for module, function in selected:
+ restores.append((module, module.__dict__.get('forward_comfy_cast_weights')))
+ module.forward_comfy_cast_weights = types.MethodType(function, module)
+ for index, layer in enumerate(model.layers):
+ def progress(module, inputs, output, index=index):
+ print(json.dumps(dict(event='encoder_layer', completed=index + 1, total=50)), flush=True)
+ handles.append(layer.register_forward_hook(progress))
+ return stats, restores, handles
+
+
+def encode(prompt, output, *, root, budget_bytes=3 * 2**30, reserve_bytes=2 * 2**30,
+ library=None, checkpoint=None, weight_decoder='cpu', media=None, canvas=None, base=None,
+ media_budget_bytes=None):
+ if sys.platform != 'darwin' or os.environ.get('PYTORCH_ENABLE_MPS_FALLBACK', '0') not in ('', '0'):
+ raise RuntimeError('This encoder requires native Mac with CPU fallback disabled')
+ if not isinstance(prompt, str) or not prompt.strip():
+ raise ValueError('A nonempty prompt is required')
+ if media_budget_bytes is not None and (type(media_budget_bytes) is not int or media_budget_bytes <= 0):
+ raise ValueError('Native media encoding requires a positive byte allowance')
+ from .media_request import task_for, TASKS
+ if (media or {}).get('conditioning_info'):
+ raise ValueError('Native encoding expects raw media, not preencoded conditioning information')
+ task = task_for(media or {})
+ if task not in TASKS:
+ raise ValueError('Unsupported native conditioning task')
+ if task != 't2va' and (canvas is None or base is None):
+ raise ValueError('Native media encoding requires the target canvas and H3 base')
+ if weight_decoder == 'metal':
+ from .backends.mps_nvfp4 import decode_weight as decoder
+ elif weight_decoder == 'cpu':
+ decoder = nvfp4_weight
+ else:
+ raise ValueError('Unknown native encoder weight decoder')
+ root, output = Path(root), Path(output)
+ library = Path(library) if library else root / 'vendor/h3-text-encoder'
+ sys.path.insert(0, str(library))
+ import torch
+ torch.set_num_threads(2)
+ from .backends import get_backend
+ backend = get_backend('mps')
+ policy = backend.configure_budget(budget_bytes, reserve_bytes=reserve_bytes)
+ import comfy.options
+ comfy.options.enable_args_parsing()
+ old_args = sys.argv
+ sys.argv = [str(library / 'main.py'), '--disable-all-custom-nodes', '--cache-none',
+ '--disable-dynamic-vram', '--disable-comfy-compiler', '--disable-cuda-graphs']
+ started = time.monotonic()
+ clip = None
+ handles, restores = [], []
+ def release_encoder():
+ nonlocal clip
+ for handle in handles:
+ handle.remove()
+ for module, original in restores:
+ if original is None:
+ module.__dict__.pop('forward_comfy_cast_weights', None)
+ else:
+ module.forward_comfy_cast_weights = original
+ handles.clear()
+ restores.clear()
+ clip = None
+ gc.collect()
+ backend.empty_cache()
+ try:
+ import comfy.sd
+ from .encoder_checkpoint import load_clip, release_mapped_pages
+ from .conditioning import to_cache
+ if checkpoint is not None and not Path(checkpoint).is_file():
+ raise FileNotFoundError('Selected encoder checkpoint is missing: ' + str(checkpoint))
+ checkpoint = Path(checkpoint) if checkpoint else root / 'models/encoder/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors'
+ if not checkpoint.is_file():
+ candidates = list((root / 'models/encoder').rglob(checkpoint.name))
+ if len(candidates) != 1:
+ raise ValueError('Expected one installed native H3 encoder checkpoint')
+ checkpoint = candidates[0]
+ with torch.no_grad():
+ normalized, vision_kwargs = None, {}
+ if task != 't2va':
+ from .media_encoding import prepare
+ normalized, vision_kwargs = prepare(media, canvas, output.parent / 'media')
+ print(json.dumps(dict(event='encoder_phase', stage='encoder_load')), flush=True)
+ clip = load_clip([checkpoint], clip_type=comfy.sd.CLIPType.MINIMAX,
+ model_options=dict(initial_device=torch.device('cpu'), load_device=torch.device('mps'),
+ offload_device=torch.device('cpu'), dtype=torch.bfloat16), disable_dynamic=True)
+ stats, restores, handles = install_weight_reader(clip, backend, checkpoint, decoder=decoder)
+ # Placement is handled by the instance reader; native tokenization,
+ # forward and output packing still execute through the CLIP API.
+ clip.load_model = lambda tokens: clip.patcher
+ print(json.dumps(dict(event='encoder_phase', stage='encoder_tokenize')), flush=True)
+ tokens = clip.tokenize(prompt, **vision_kwargs)
+ release_mapped_pages([checkpoint])
+ print(json.dumps(dict(event='encoder_phase', stage='encoder_compute')), flush=True)
+ encoded = clip.encode_from_tokens_scheduled(tokens, show_pbar=False)
+ backend.synchronize()
+ value = to_cache(encoded, prompt, task=task)
+ media_metrics = {}
+ if normalized is not None:
+ # Keep the same native vision/text contract, then release every
+ # encoder reference before the independent input VAE is loaded.
+ del encoded, tokens, vision_kwargs
+ release_encoder()
+ # Text streaming deliberately uses a small allocation ceiling.
+ # Input VAEs have separate workspaces: re-admit after releasing
+ # text weights, against the request's original capacity bound.
+ # configure_budget also enforces live availability, the reserve
+ # and Metal's recommendation; this never selects unlimited MPS.
+ media_policy = backend.configure_budget(
+ budget_bytes if media_budget_bytes is None else media_budget_bytes,
+ reserve_bytes=reserve_bytes)
+ from .macos_vdn import activate
+ activate()
+ from .media_encoding import encode_latents
+ tick = time.monotonic()
+ value.update(task=task, width=canvas['width'], height=canvas['height'])
+ print(json.dumps(dict(event='encoder_phase', stage='media_vae', budget=media_policy)), flush=True)
+ info = encode_latents(normalized, value, base, canvas, device='mps')
+ backend.synchronize()
+ media_metrics.update(conditioning_info=info, media_vae_seconds=time.monotonic() - tick,
+ media_budget=media_policy)
+ output.parent.mkdir(parents=True, exist_ok=True)
+ temporary = output.with_suffix('.partial')
+ print(json.dumps(dict(event='encoder_phase', stage='encoder_save')), flush=True)
+ torch.save(value, temporary)
+ temporary.replace(output)
+ return dict(success=True, shape=list(value['prompt_embeds'].shape), output=str(output),
+ elapsed_seconds=time.monotonic() - started, budget=policy, reader=stats,
+ device_backend='mps', precision='NVFP4/AWQ storage; FP32 decoder and native FP32 H3 forward',
+ weight_decoder=weight_decoder, **media_metrics,
+ cpu_work=(('tokenization, selected embedding rows and scale layout' if weight_decoder == 'metal'
+ else 'tokenization, selected embedding rows, and explicit weight decoding')
+ + ('; media normalization and native vision position preparation' if normalized is not None else '')),
+ cpu_operator_fallback=False)
+ finally:
+ sys.argv = old_args
+ release_encoder()
diff --git a/freevideo_engine/macos_generate.py b/freevideo_engine/macos_generate.py
new file mode 100644
index 0000000..d0781f1
--- /dev/null
+++ b/freevideo_engine/macos_generate.py
@@ -0,0 +1,298 @@
+"""Native request entry point, using shared leases, supervision and reports.
+
+Encoding and generation use separate children so their weights never overlap.
+No tensor runtime is imported by this supervisor. CUDA orchestration is unchanged.
+"""
+import argparse
+import importlib.metadata
+import json
+import math
+import os
+from pathlib import Path
+import platform
+import sys
+import time
+import traceback
+
+from . import processes
+from .geometry import geometry
+from .locking import LOCK_ENV, runtime_lock
+from .monitoring import save
+from .paths import data_root
+
+GiB = 2**30
+
+
+def policy(args, memory=None):
+ from .system import system_memory
+ memory = memory or system_memory()
+ if (any(type(memory.get(k)) is not int or memory[k] < 0 for k in ('total_bytes', 'available_bytes'))
+ or not 0 < memory['total_bytes'] or memory['available_bytes'] > memory['total_bytes']):
+ raise ValueError('Invalid unified-memory observation')
+ for name in ('vram_gib', 'gpu_reserve_gib', 'profile'):
+ if getattr(args, name, None) is not None:
+ raise ValueError('Mac uses a unified memory budget; --' + name.replace('_', '-') + ' is not supported')
+ if getattr(args, 'attention', 'auto') not in ('auto', 'mps'):
+ raise ValueError('Native Mac attention must be auto or mps')
+ def amount(name, default):
+ value = getattr(args, name, None)
+ if value is None:
+ return default
+ if type(value) not in (int, float) or not math.isfinite(value) or value <= 0:
+ raise ValueError(name + ' must be positive and finite')
+ return int(value * GiB)
+ reserve = max(GiB, amount('ram_reserve_gib', 2 * GiB))
+ capacity = min(memory['total_bytes'], amount('ram_gib', memory['total_bytes']))
+ working = min(capacity, memory['available_bytes']) - reserve
+ if working < 2 * GiB:
+ raise MemoryError('Native generation needs at least 2 GiB working unified memory after the system reserve')
+ # The original 4 GiB cap was a small-workload trial, not a device capacity.
+ # Use the live unified allowance. The native backend additionally clamps it
+ # to Metal's recommendation and rechecks availability when the worker starts.
+ allocator = min(working, amount('allocator_limit_gib', working))
+ allocator_capacity = min(capacity - reserve, amount('allocator_limit_gib', capacity - reserve))
+ return dict(device_backend='mps', memory_model='unified', observed=memory,
+ reserve_bytes=reserve, allocator_bytes=allocator, allocator_capacity_bytes=allocator_capacity,
+ encoder_bytes=min(3 * GiB, allocator),
+ ram_budget_bytes=capacity if getattr(args, 'ram_gib', None) is not None else working,
+ ram_budget_is_estimate=getattr(args, 'ram_gib', None) is None,
+ emergency_floor_bytes=GiB, query_chunk=128, ff_chunk=256, projection_chunk=256,
+ weight_decoder='metal', encoder_weight_decoder='metal', cpu_operator_fallback=False,
+ sampling_lifetime='auto',
+ scope='Live unified-memory bounds and eligible cross-pass weight retention; not proof of workload capacity.')
+
+
+def encoder_checkpoint(args):
+ filename = getattr(args, 'encoder', 'qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors')
+ if Path(filename).name != filename:
+ raise ValueError('Encoder must be an installed checkpoint filename')
+ folders = [data_root() / 'models/encoder', data_root() / 'models/encoder/text_encoders']
+ paths = getattr(args, 'model_paths', None)
+ if paths:
+ import yaml
+ config = yaml.safe_load(Path(paths).read_text(encoding='utf-8'))
+ for row in config.values():
+ if not isinstance(row, dict):
+ continue
+ base = Path(row.get('base_path', Path(paths).parent)).expanduser()
+ if not base.is_absolute():
+ base = Path(paths).parent / base
+ for folder in str(row.get('text_encoders', '')).splitlines():
+ if folder.strip():
+ folders.append(base / folder.strip())
+ matches = {(folder / filename).resolve() for folder in folders if (folder / filename).is_file()}
+ if len(matches) != 1:
+ raise ValueError('Expected one installed native H3 encoder checkpoint; run Install / repair')
+ return matches.pop()
+
+
+def conditioning_cache(checkpoint, library):
+ from .input_cache import InputCache, digest
+ from .storage import fingerprint
+ # Include the actual encoder implementation, not only a nominal version.
+ sources = {}
+ for label, root in (('engine', Path(__file__).parent), ('comfy', Path(library) / 'comfy')):
+ for path in sorted(root.rglob('*.py')):
+ sources[label + '/' + path.relative_to(root).as_posix()] = digest(path)
+ identity = dict(backend='mps', macos=platform.mac_ver()[0], checkpoint=fingerprint(checkpoint),
+ torch=importlib.metadata.version('torch'), sources=sources, precision='native-h3-fp32-v1')
+ return InputCache(identity)
+
+
+def run(args):
+ from .macos_bootstrap import require_native, environment, inventory
+ from .macos_power import awake
+ from .generate import child
+ from .support_report import write as write_debug, code_identity
+ from .two_pass import plan
+ require_native()
+ output = Path(args.out).expanduser().resolve()
+ artifacts = output.with_suffix('.artifacts')
+ if any(p.exists() for p in (output, artifacts, output.with_suffix('.request.json'))):
+ raise FileExistsError('Choose a new output path; previous artifacts are retained')
+ artifacts.mkdir(parents=True)
+ started = time.monotonic()
+ report = dict(success=False, device_backend='mps', phase='preflight', seed=args.seed)
+ def interrupted(signum, frame):
+ raise KeyboardInterrupt('Request interrupted by signal ' + str(signum))
+ previous = processes.termination_handler(interrupted)
+ try:
+ resource = policy(args)
+ hardware = inventory()['hardware']
+ resource['hardware'] = hardware
+ report.update(runtime_hardware=hardware, runtime_code=code_identity())
+ print(json.dumps(dict(event='compute_device', backend='MPS', name=hardware['gpu_name'],
+ memory_model='unified', ram_total_bytes=hardware['ram_total'])), flush=True)
+ canvas = geometry(args.width, args.height, frames=args.frames, seconds=args.seconds)
+ from .media_request import read as read_media, task_for, cache_key, TASKS
+ media = read_media(args.media)
+ structural = any(media.get(k) for k in ('first', 'last', 'references', 'conditioning_info'))
+ task = args.task or task_for(media)
+ if (args.task and structural and args.task != task_for(media)
+ and not (media.get('references') and args.task in ('ref2va_audio', 'ref2va_av'))):
+ raise ValueError('Native request task differs from its media inputs')
+ if task not in TASKS:
+ raise ValueError('Unsupported native conditioning task')
+ raw_media = any(media.get(k) for k in ('first', 'last', 'references'))
+ if media.get('conditioning_info') and (not args.conditioning or raw_media):
+ raise ValueError('Use preencoded conditioning information with its file and no additional media')
+ if args.conditioning and raw_media:
+ raise ValueError('Preencoded conditioning already includes media; use its conditioning_info')
+ if args.prompt_file and task != 't2va' and not raw_media:
+ raise ValueError('Native media encoding requires its input files')
+ sampling = plan(canvas, args.two_pass, task, base_steps=args.base_steps or 8, refine_steps=args.refine_steps)
+ from .paths import base_path, checkpoint_path
+ base = str(Path(args.base or base_path()).resolve())
+ adapters = [row for row in media.get('loras', []) if row['strength'] != 0]
+ prepared_cache = Path(args.cache).resolve()
+ report.update(geometry=canvas, sampling_plan=sampling, profile=dict(policy=resource,
+ engine=dict(device_backend='mps', task=task, attention='mps', steps=sampling['base_steps'])),
+ encoder_mode='native H3 encoder library child' if args.prompt_file else 'preencoded shared conditioning')
+ env = environment(data_root(), dict(os.environ, PYTHONUNBUFFERED='1', OMP_NUM_THREADS='2', MKL_NUM_THREADS='2'))
+ with runtime_lock() as descriptor, awake() as idle_sleep_prevented:
+ report['idle_sleep_prevented'] = idle_sleep_prevented
+ env[LOCK_ENV] = str(descriptor)
+ def execute(value, name, module='freevideo_engine.macos_generate'):
+ request = artifacts / (name + '-request.json')
+ save(request, value)
+ return child([sys.executable, '-m', module, '--request', str(request)],
+ env, descriptor, output.with_suffix('.' + name + '.log'),
+ ram_budget_bytes=resource['ram_budget_bytes'],
+ minimum_available_bytes=resource['emergency_floor_bytes'],
+ ram_budget_is_estimate=resource['ram_budget_is_estimate'])
+ if adapters:
+ report['phase'] = 'lora'
+ save(output.with_suffix('.request.json'), report)
+ result_path = artifacts / 'lora-result.json'
+ print(json.dumps(dict(event='lora_prepare_start')), flush=True)
+ report['lora_resources'] = execute(dict(cache=str(prepared_cache), adapters=adapters,
+ result=str(result_path), mode='online'), 'lora', module='freevideo_engine.lora_cache')
+ prepared = json.loads(result_path.read_text(encoding='utf-8'))
+ prepared_cache = Path(prepared['cache']).resolve()
+ report['lora'] = prepared['report']
+ conditioning = Path(args.conditioning).resolve() if args.conditioning else artifacts / 'conditioning.pt'
+ if args.prompt_file:
+ report['phase'] = 'encoding'
+ save(output.with_suffix('.request.json'), report)
+ prompt = Path(args.prompt_file).read_text(encoding='utf-8')
+ if not prompt.strip():
+ raise ValueError('A nonempty prompt is required')
+ checkpoint = encoder_checkpoint(args)
+ library = Path(args.comfy_root or data_root() / 'vendor/h3-text-encoder').resolve()
+ cache = None if args.no_tuning else conditioning_cache(checkpoint, library)
+ key = cache_key(prompt, media, canvas)
+ metrics = cache.get(key, conditioning) if cache else None
+ if metrics is None:
+ report['encoding_resources'] = execute(dict(phase='encoding', root=str(data_root()),
+ prompt_file=str(Path(args.prompt_file).resolve()), output=str(conditioning),
+ report=str(output.with_suffix('.encoding.json')), checkpoint=str(checkpoint),
+ library=str(library), resources=resource, media=media, canvas=canvas, base=base), 'encoding')
+ metrics = json.loads(output.with_suffix('.encoding.json').read_text())
+ if cache:
+ try:
+ cache.put(key, conditioning, metrics)
+ except (OSError, ValueError) as error:
+ report['input_cache_note'] = type(error).__name__ + ': input cache unavailable'
+ else:
+ save(output.with_suffix('.encoding.json'), metrics)
+ print(json.dumps(dict(event='conditioning_cache_hit')), flush=True)
+ report['input_cache'] = dict(conditioning_hit=bool(metrics.get('cache_hit')))
+ report['encoding'] = metrics
+ encoded_task = metrics.get('conditioning_info', {}).get('task')
+ if task.startswith('ref2va'):
+ if (encoded_task not in ('ref2va', 'ref2va_audio', 'ref2va_av') or
+ args.task in ('ref2va_audio', 'ref2va_av') and args.task != encoded_task):
+ raise ValueError('Native encoder did not return the requested reference task')
+ task = encoded_task
+ report['profile']['engine']['task'] = task
+ elif task != 't2va' and encoded_task != task:
+ raise ValueError('Native encoder did not return the requested keyframe task')
+ if not conditioning.is_file():
+ raise FileNotFoundError('Conditioning is missing: ' + str(conditioning))
+ report['phase'] = 'engine'
+ save(output.with_suffix('.request.json'), report)
+ print(json.dumps(dict(event='sampling_plan', **sampling)), flush=True)
+ report['resources'] = execute(dict(phase='engine', output=str(output), artifacts=str(artifacts),
+ conditioning=str(conditioning), cache=str(prepared_cache),
+ base=base, task=task,
+ checkpoint=str(Path(args.checkpoint or checkpoint_path()).resolve()),
+ seed=args.seed, canvas=canvas, sampling=sampling, resources=resource), 'engine')
+ metrics = json.loads(output.with_suffix('.engine.json').read_text())
+ if (metrics.get('success') is not True or metrics.get('sampling_plan') != sampling
+ or len(metrics.get('step_seconds', [])) != sampling['total_steps']
+ or not output.is_file() or output.stat().st_size == 0):
+ raise RuntimeError('Native worker did not complete the requested video')
+ report.update(success=True, phase='complete', video=metrics)
+ return output
+ except BaseException as error:
+ report.update(error_type=type(error).__name__, error_message=str(error), exception=traceback.format_exc(),
+ cancelled=isinstance(error, KeyboardInterrupt))
+ raise
+ finally:
+ processes.restore_handlers(previous)
+ report['request_seconds'] = time.monotonic() - started
+ save(output.with_suffix('.request.json'), report)
+ write_debug(output)
+
+
+def worker(value):
+ from .macos_bootstrap import require_native
+ require_native()
+ if value['phase'] == 'engine':
+ from .macos_stages import run
+ return run(value)
+ if value['phase'] != 'encoding':
+ raise ValueError('Unknown native request worker phase')
+ import torch
+ torch.set_num_threads(2)
+ resource, output = value['resources'], Path(value['output'])
+ path = Path(value['report'])
+ result = dict(success=False, device_backend='mps', phase=value['phase'])
+ started = time.monotonic()
+ try:
+ from .macos_encoder import encode
+ result.update(encode(Path(value['prompt_file']).read_text(encoding='utf-8'), output,
+ root=value['root'], library=value['library'], checkpoint=value['checkpoint'],
+ budget_bytes=resource['encoder_bytes'], reserve_bytes=resource['reserve_bytes'],
+ media_budget_bytes=resource.get('allocator_capacity_bytes', resource['encoder_bytes']),
+ weight_decoder=resource.get('encoder_weight_decoder', 'cpu'),
+ media=value.get('media'), canvas=value.get('canvas'), base=value.get('base')))
+ result['work_seconds'] = time.monotonic() - started
+ except BaseException as error:
+ result.update(error_type=type(error).__name__, error_message=str(error), exception=traceback.format_exc())
+ raise
+ finally:
+ result['worker_seconds'] = time.monotonic() - started
+ save(path, result)
+
+
+def dispatch(args):
+ from .cli import write_json
+ from .macos_bootstrap import require_native
+ require_native()
+ if args.command == 'generate':
+ return run(args)
+ if args.command == 'doctor':
+ from .macos_doctor import doctor
+ result = doctor(probe=args.probe)
+ write_json(result, args.out)
+ if (args.probe and not result['ready']) or (args.require_paths and
+ not all(row['exists'] for row in result['paths'].values())):
+ raise SystemExit(1)
+ elif args.command == 'plan':
+ write_json(policy(args), args.out)
+ elif args.command == 'encode':
+ from .macos_encoder import encode
+ resource = policy(args)
+ with runtime_lock():
+ result = encode(args.prompt_file.read_text(encoding='utf-8'), args.out,
+ root=data_root(), library=args.comfy_root, checkpoint=encoder_checkpoint(args),
+ budget_bytes=resource['encoder_bytes'], reserve_bytes=resource['reserve_bytes'],
+ weight_decoder=resource['encoder_weight_decoder'])
+ write_json(result, args.out.with_suffix('.encoding.json'))
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--request', type=Path, required=True)
+ worker(json.loads(parser.parse_args().request.read_text(encoding='utf-8')))
diff --git a/freevideo_engine/macos_memory.py b/freevideo_engine/macos_memory.py
new file mode 100644
index 0000000..abd7202
--- /dev/null
+++ b/freevideo_engine/macos_memory.py
@@ -0,0 +1,142 @@
+"""Native Mach/sysctl memory observations, usable before installing packages.
+
+Apple's vm_statistics64.free_count already includes speculative pages. Available
+memory is free + inactive (the same convention as psutil on macOS). Compressor
+contents and swap are reported separately and never treated as extra RAM.
+"""
+import ctypes
+from functools import lru_cache
+import os
+import sys
+
+
+class VMStatistics(ctypes.Structure):
+ # Stable prefix through HOST_VM_INFO64 revision 1. Query into a larger buffer
+ # so later kernel revisions can append fields without overrunning our struct.
+ _fields_ = [(name, ctypes.c_uint32) for name in
+ ('free_count', 'active_count', 'inactive_count', 'wire_count')]
+ _fields_ += [(name, ctypes.c_uint64) for name in
+ ('zero_fill_count', 'reactivations', 'pageins', 'pageouts', 'faults',
+ 'cow_faults', 'lookups', 'hits', 'purges')]
+ _fields_ += [(name, ctypes.c_uint32) for name in ('purgeable_count', 'speculative_count')]
+ _fields_ += [(name, ctypes.c_uint64) for name in
+ ('decompressions', 'compressions', 'swapins', 'swapouts')]
+ _fields_ += [(name, ctypes.c_uint32) for name in
+ ('compressor_page_count', 'throttled_count', 'external_page_count', 'internal_page_count')]
+ _fields_ += [('total_uncompressed_pages_in_compressor', ctypes.c_uint64)]
+
+
+class SwapUsage(ctypes.Structure):
+ _fields_ = [('total', ctypes.c_uint64), ('available', ctypes.c_uint64),
+ ('used', ctypes.c_uint64), ('page_size', ctypes.c_uint32),
+ ('encrypted', ctypes.c_int)]
+
+
+class ResourceUsage(ctypes.Structure):
+ """Public rusage_info_v0 ABI from Darwin sys/resource.h (96 bytes)."""
+ _fields_ = [('uuid', ctypes.c_ubyte * 16)] + [(name, ctypes.c_uint64) for name in
+ ('user_time', 'system_time', 'pkg_idle_wkups', 'interrupt_wkups', 'pageins',
+ 'wired_size', 'resident_size', 'phys_footprint', 'proc_start_abstime', 'proc_exit_abstime')]
+
+
+@lru_cache(maxsize=1)
+def _process_library():
+ if sys.platform != 'darwin':
+ raise RuntimeError('Native process footprint observations require macOS')
+ lib = ctypes.CDLL('/usr/lib/libproc.dylib', use_errno=True)
+ lib.proc_pid_rusage.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_void_p]
+ lib.proc_pid_rusage.restype = ctypes.c_int
+ return lib
+
+
+def process_footprint(pid):
+ """Kernel memory charge, including compressed and accounted IOKit memory.
+
+ This is not RSS or extra GPU memory. Never sum it with Metal driver bytes.
+ Read the stable v0 ABI rather than guessing the latest struct size.
+ """
+ if type(pid) is not int or pid <= 0:
+ raise ValueError('A positive process ID is required')
+ usage = ResourceUsage()
+ if _process_library().proc_pid_rusage(pid, 0, ctypes.byref(usage)):
+ code = ctypes.get_errno()
+ raise OSError(code, os.strerror(code), 'proc_pid_rusage: ' + str(pid))
+ return usage.phys_footprint
+
+
+@lru_cache(maxsize=1)
+def _library():
+ if sys.platform != 'darwin':
+ raise RuntimeError('Mach memory observations require macOS')
+ lib = ctypes.CDLL('/usr/lib/libSystem.B.dylib', use_errno=True)
+ lib.sysctlbyname.argtypes = [ctypes.c_char_p, ctypes.c_void_p,
+ ctypes.POINTER(ctypes.c_size_t), ctypes.c_void_p, ctypes.c_size_t]
+ lib.sysctlbyname.restype = ctypes.c_int
+ lib.mach_host_self.argtypes = []
+ lib.mach_host_self.restype = ctypes.c_uint32
+ lib.host_statistics64.argtypes = [ctypes.c_uint32, ctypes.c_int, ctypes.c_void_p,
+ ctypes.POINTER(ctypes.c_uint32)]
+ lib.host_statistics64.restype = ctypes.c_int
+ lib.mach_port_deallocate.argtypes = [ctypes.c_uint32, ctypes.c_uint32]
+ lib.mach_port_deallocate.restype = ctypes.c_int
+ return lib
+
+
+def _sysctl(name, value):
+ size = ctypes.c_size_t(ctypes.sizeof(value))
+ if _library().sysctlbyname(name.encode('ascii'), ctypes.byref(value), ctypes.byref(size), None, 0):
+ code = ctypes.get_errno()
+ raise OSError(code, os.strerror(code), name)
+ if size.value != ctypes.sizeof(value):
+ raise RuntimeError('Unexpected sysctl field size: ' + name)
+ return value
+
+
+def chip_name():
+ lib = _library()
+ size = ctypes.c_size_t(256)
+ buffer = ctypes.create_string_buffer(size.value)
+ if lib.sysctlbyname(b'machdep.cpu.brand_string', buffer, ctypes.byref(size), None, 0):
+ code = ctypes.get_errno()
+ raise OSError(code, os.strerror(code), 'machdep.cpu.brand_string')
+ return buffer.value.decode('utf-8')
+
+
+def summarize(total, page_size, stats, swap=None):
+ if type(total) is not int or total <= 0 or type(page_size) is not int or page_size <= 0:
+ raise ValueError('Mac memory requires positive physical capacity and page size')
+ available = min(total, (stats.free_count + stats.inactive_count) * page_size)
+ return dict(total_bytes=total, available_bytes=available, physical_available_bytes=available,
+ commit_available_bytes=None, memory_model='unified', source='Mach host_statistics64',
+ free_bytes=max(0, stats.free_count - stats.speculative_count) * page_size,
+ inactive_bytes=stats.inactive_count * page_size, active_bytes=stats.active_count * page_size,
+ wired_bytes=stats.wire_count * page_size,
+ compressor_physical_bytes=stats.compressor_page_count * page_size,
+ compressor_logical_bytes=stats.total_uncompressed_pages_in_compressor * page_size,
+ swap_total_bytes=None if swap is None else swap.total,
+ swap_free_bytes=None if swap is None else swap.available)
+
+
+def memory_status():
+ lib = _library()
+ total = _sysctl('hw.memsize', ctypes.c_uint64()).value
+ storage = (ctypes.c_uint32 * 1024)()
+ count = ctypes.c_uint32(len(storage))
+ host = lib.mach_host_self()
+ if not host:
+ raise RuntimeError('mach_host_self returned no host port')
+ try:
+ code = lib.host_statistics64(host, 4, storage, ctypes.byref(count)) # HOST_VM_INFO64
+ if code:
+ raise OSError('host_statistics64 failed: ' + str(code))
+ if count.value * ctypes.sizeof(ctypes.c_uint32) < ctypes.sizeof(VMStatistics):
+ raise RuntimeError('Incomplete Mach memory counters')
+ stats = VMStatistics.from_buffer_copy(storage)
+ finally:
+ task = ctypes.c_uint32.in_dll(lib, 'mach_task_self_').value
+ lib.mach_port_deallocate(task, host)
+ try:
+ swap = _sysctl('vm.swapusage', SwapUsage())
+ except OSError:
+ swap = None
+ return summarize(total, os.sysconf('SC_PAGE_SIZE'), stats, swap)
diff --git a/freevideo_engine/macos_power.py b/freevideo_engine/macos_power.py
new file mode 100644
index 0000000..3aee1e7
--- /dev/null
+++ b/freevideo_engine/macos_power.py
@@ -0,0 +1,51 @@
+"""Request-scoped idle sleep prevention through macOS power assertions."""
+from contextlib import contextmanager
+import ctypes
+import sys
+
+
+def _create():
+ cf = ctypes.CDLL('/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation')
+ io = ctypes.CDLL('/System/Library/Frameworks/IOKit.framework/IOKit')
+ cf.CFStringCreateWithCString.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_uint32]
+ cf.CFStringCreateWithCString.restype = ctypes.c_void_p
+ cf.CFRelease.argtypes, cf.CFRelease.restype = [ctypes.c_void_p], None
+ io.IOPMAssertionCreateWithName.argtypes = [ctypes.c_void_p, ctypes.c_uint32,
+ ctypes.c_void_p, ctypes.POINTER(ctypes.c_uint32)]
+ io.IOPMAssertionCreateWithName.restype = ctypes.c_int32
+ io.IOPMAssertionRelease.argtypes, io.IOPMAssertionRelease.restype = [ctypes.c_uint32], ctypes.c_int32
+ strings = []
+ try:
+ for value in (b'PreventUserIdleSystemSleep', b'FreeVideo generation'):
+ string = cf.CFStringCreateWithCString(None, value, 0x08000100)
+ if not string:
+ return None
+ strings.append(string)
+ assertion = ctypes.c_uint32()
+ if io.IOPMAssertionCreateWithName(strings[0], 255, strings[1], ctypes.byref(assertion)) != 0:
+ return None
+ return io.IOPMAssertionRelease, assertion.value
+ finally:
+ for string in reversed(strings):
+ cf.CFRelease(string)
+
+
+@contextmanager
+def awake():
+ """Hold one assertion during work, without changing persistent preferences.
+
+ Display sleep and explicit user sleep/lid actions retain their normal meaning.
+ Failure to create the optional assertion does not prevent generation.
+ """
+ token = None
+ if sys.platform == 'darwin':
+ try:
+ token = _create()
+ except (OSError, AttributeError):
+ pass
+ try:
+ yield token is not None
+ finally:
+ if token is not None:
+ release, assertion = token
+ release(assertion)
diff --git a/freevideo_engine/macos_preferences.py b/freevideo_engine/macos_preferences.py
new file mode 100644
index 0000000..b96ef71
--- /dev/null
+++ b/freevideo_engine/macos_preferences.py
@@ -0,0 +1,37 @@
+"""Read native UI language preferences without depending on a shell locale or Qt."""
+import ctypes
+import sys
+
+
+def preferred_language():
+ if sys.platform != 'darwin':
+ raise RuntimeError('Native language preferences require macOS')
+ cf = ctypes.CDLL('/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation')
+ signatures = {
+ 'CFLocaleCopyPreferredLanguages': ([], ctypes.c_void_p),
+ 'CFArrayGetCount': ([ctypes.c_void_p], ctypes.c_long),
+ 'CFArrayGetValueAtIndex': ([ctypes.c_void_p, ctypes.c_long], ctypes.c_void_p),
+ 'CFStringGetCString': ([ctypes.c_void_p, ctypes.c_void_p, ctypes.c_long, ctypes.c_uint32], ctypes.c_bool),
+ 'CFRelease': ([ctypes.c_void_p], None),
+ }
+ for name, (args, result) in signatures.items():
+ function = getattr(cf, name)
+ function.argtypes, function.restype = args, result
+ languages = cf.CFLocaleCopyPreferredLanguages()
+ if not languages:
+ return None
+ try:
+ count = cf.CFArrayGetCount(languages)
+ if not count:
+ return None
+ for index in range(min(count, 32)):
+ value = cf.CFArrayGetValueAtIndex(languages, index)
+ buffer = ctypes.create_string_buffer(128)
+ if value and cf.CFStringGetCString(value, buffer, len(buffer), 0x08000100):
+ language = buffer.value.decode('utf-8').lower().replace('_', '-').split('-')[0]
+ if language in ('en', 'zh'):
+ return language
+ return 'en'
+ finally:
+ # Copy follows Core Foundation's Create Rule; array elements are borrowed.
+ cf.CFRelease(languages)
diff --git a/freevideo_engine/macos_process_host.py b/freevideo_engine/macos_process_host.py
new file mode 100644
index 0000000..6a0d26a
--- /dev/null
+++ b/freevideo_engine/macos_process_host.py
@@ -0,0 +1,115 @@
+"""Mac child ownership, including FreeVideo workers in separate sessions.
+
+Each FreeVideo spawn has a lightweight parent watcher. Descendants are tracked
+with psutil process identities so cleanup never signals a reused PID. This is
+not a kernel subreaper: unrelated daemonization is outside this contract.
+"""
+import os
+import signal
+import subprocess
+import sys
+import time
+
+import psutil
+
+
+class Tree:
+ def __init__(self, pid):
+ self.processes = {}
+ try:
+ process = psutil.Process(pid)
+ self.processes[process.pid] = process
+ except psutil.NoSuchProcess:
+ pass
+
+ def alive(self):
+ found = {}
+ for process in list(self.processes.values()):
+ if process.pid in found:
+ continue # An earlier live ancestor already enumerated this subtree.
+ try:
+ if process.is_running() and process.status() != psutil.STATUS_ZOMBIE:
+ found[process.pid] = process
+ for child in process.children(recursive=True):
+ found[child.pid] = child
+ except psutil.NoSuchProcess:
+ pass
+ self.processes.update(found)
+ result = []
+ for process in self.processes.values():
+ try:
+ if process.is_running() and process.status() != psutil.STATUS_ZOMBIE:
+ result.append(process)
+ except psutil.NoSuchProcess:
+ pass
+ self.processes = {process.pid: process for process in result}
+ return result
+
+ def cleanup(self, grace):
+ deadline = time.monotonic() + grace
+ terminated = set()
+ while pending := self.alive():
+ force = time.monotonic() >= deadline
+ for process in pending:
+ try:
+ identity = (process.pid, process.create_time())
+ if force:
+ process.kill()
+ elif identity not in terminated:
+ process.terminate()
+ terminated.add(identity)
+ except psutil.NoSuchProcess:
+ pass
+ if time.monotonic() > deadline + 3:
+ raise RuntimeError('Mac worker cleanup could not confirm exit; retain the runtime lease')
+ time.sleep(.05)
+
+
+def stop(process, grace=10):
+ # Capture descendants before signalling. The root can exit first and leave
+ # separate-session workers reparented to launchd while they clean up.
+ tree = Tree(process.pid) if process.poll() is None else None
+ if tree is not None:
+ try:
+ tree.cleanup(grace)
+ finally:
+ process.poll()
+ process.wait(timeout=3)
+
+
+def command(command, inherited):
+ from .processes import module_command
+ arguments = [str(os.getpid()), ','.join(map(str, inherited)), *command]
+ if getattr(sys, 'frozen', False):
+ return [sys.executable, '--macos-process-host', *arguments]
+ return module_command('freevideo_engine.macos_process_host', *arguments)
+
+
+def main(argv=None):
+ parent, inherited, *arguments = sys.argv[1:] if argv is None else argv
+ stopping = []
+ for name in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP):
+ signal.signal(name, lambda *_: stopping.append(True))
+ if os.getppid() != int(parent) or stopping:
+ return 130
+ child = subprocess.Popen(arguments, start_new_session=True,
+ pass_fds=tuple(int(fd) for fd in inherited.split(',') if fd))
+ tree = Tree(child.pid)
+ try:
+ while child.poll() is None and not stopping:
+ tree.alive()
+ if os.getppid() != int(parent):
+ stopping.append(True)
+ break
+ try:
+ child.wait(timeout=.1)
+ except subprocess.TimeoutExpired:
+ pass
+ return 130 if stopping else child.returncode if child.returncode >= 0 else 128 - child.returncode
+ finally:
+ tree.cleanup(2)
+ child.wait(timeout=3)
+
+
+if __name__ == '__main__':
+ raise SystemExit(main())
diff --git a/freevideo_engine/macos_process_memory.py b/freevideo_engine/macos_process_memory.py
new file mode 100644
index 0000000..228988c
--- /dev/null
+++ b/freevideo_engine/macos_process_memory.py
@@ -0,0 +1,93 @@
+"""Native process memory accounting; no CUDA or MPS imports.
+
+RSS can miss kernel-accounted Metal allocations. Use phys_footprint for the
+request guard, retain RSS separately, and never add the two or GPU driver bytes.
+"""
+from .macos_memory import memory_status, process_footprint
+
+
+class ProcessMemory:
+ def __init__(self):
+ import psutil
+ self.psutil = psutil
+ self.peak_rss = self.peak_footprint = self.samples = 0
+ self.complete = True
+ self.minimum_available = None
+
+ def sample(self, root_pid):
+ psutil = self.psutil
+ errors, processes = [], []
+
+ def unreadable(pid, error):
+ errors.append(dict(pid=pid, error=type(error).__name__))
+
+ try:
+ root = psutil.Process(root_pid)
+ processes = [root]
+ try:
+ processes.extend(root.children(recursive=True))
+ except (psutil.NoSuchProcess, psutil.AccessDenied) as error:
+ # The tree may be incomplete even if its root exits mid-query.
+ unreadable(root_pid, error)
+ except psutil.NoSuchProcess:
+ pass
+ except psutil.AccessDenied as error:
+ unreadable(root_pid, error)
+ rss = footprint = count = 0
+ seen = set()
+ for process in processes:
+ if process.pid in seen:
+ continue
+ seen.add(process.pid)
+ try:
+ if not process.is_running() or process.status() == psutil.STATUS_ZOMBIE:
+ continue
+ resident = process.memory_info().rss
+ try:
+ charged = process_footprint(process.pid)
+ except ProcessLookupError:
+ continue
+ except OSError as error:
+ unreadable(process.pid, error)
+ charged = 0
+ rss += resident
+ footprint += charged
+ count += 1
+ except psutil.NoSuchProcess:
+ continue
+ except psutil.AccessDenied as error:
+ unreadable(process.pid, error)
+ system = memory_status()
+ available = system['available_bytes']
+ self.samples += 1
+ self.peak_rss = max(self.peak_rss, rss)
+ self.peak_footprint = max(self.peak_footprint, footprint)
+ self.complete &= not errors
+ self.minimum_available = (available if self.minimum_available is None
+ else min(self.minimum_available, available))
+ guard = None if errors else footprint
+ return dict(rss_bytes=rss, pss_bytes=None, nonfile_pss_bytes=None,
+ phys_footprint_bytes=footprint,
+ private_commit_bytes=None, guard_bytes=guard, inference_guard_bytes=guard,
+ guard_metric='phys_footprint', processes=count, memory_model='unified',
+ unreadable_memory_pids=sorted({row['pid'] for row in errors}),
+ memory_read_errors=errors, system_available_bytes=available,
+ system_physical_available_bytes=available, system_commit_available_bytes=None,
+ effective_available_bytes=available, inference_available_bytes=available,
+ macos_memory=system)
+
+ def result(self):
+ return dict(process_tree_peak_rss_bytes=self.peak_rss,
+ process_tree_peak_phys_footprint_bytes=self.peak_footprint,
+ process_tree_peak_guard_bytes=self.peak_footprint, process_tree_guard_complete=self.complete,
+ process_tree_peak_pss_bytes=None, process_tree_pss_complete=False,
+ inference_peak_working_pss_bytes=None, ram_guard_metric='phys_footprint',
+ system_min_available_bytes=self.minimum_available,
+ effective_min_available_bytes=self.minimum_available,
+ inference_min_available_bytes=self.minimum_available,
+ cgroup_memory_final=None, ram_observation_samples=self.samples,
+ process_tree_disk_read_bytes=None, process_tree_disk_write_bytes=None,
+ ram_observation_scope='Sampled live worker/descendant kernel phys_footprint charge, '
+ 'including compressed and kernel-accounted IOKit memory; not resident physical RAM. '
+ 'RSS is retained separately. No PSS, private-commit, disk-I/O or kernel-limit claim. '
+ 'Metal driver memory is not added again. Peaks can miss events between samples.')
diff --git a/freevideo_engine/macos_reference.py b/freevideo_engine/macos_reference.py
new file mode 100644
index 0000000..fbeae8a
--- /dev/null
+++ b/freevideo_engine/macos_reference.py
@@ -0,0 +1,166 @@
+"""Deliver supplemental Mac modulation tables without importing a GPU runtime.
+
+The caller supplies a bundled catalog pinned to a published model revision.
+Weights and exact timestep rows select the asset; a backend or task name alone
+never does. Existing computed tables retain their original bytes and receipts.
+"""
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+
+from . import adaln_assets as assets
+from . import network
+from .monitoring import save
+
+
+CATALOG_FILE = Path(__file__).with_name('macos_reference_catalog.json')
+
+
+def prepare_missing(cache, identity, count, *, networking=None, env=None):
+ """Deliver a missing schedule only when the app includes its pinned index.
+
+ A build without that optional index keeps the original projection path.
+ An invalid index or failed supported transfer is an error, so a failed
+ small download cannot silently trigger a much larger projection download.
+ """
+ try:
+ catalog = _read(CATALOG_FILE)
+ except FileNotFoundError:
+ return False
+ return ensure(cache, identity, count, catalog=catalog, networking=networking, env=env)
+
+
+def select(catalog, identity, count):
+ """Validate the complete pinned index before selecting an exact schedule."""
+ if (not isinstance(catalog, dict) or catalog.get('schema_version') != 1
+ or not isinstance(catalog.get('repo'), str)
+ or not re.fullmatch(r'[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+', catalog['repo'])
+ or not isinstance(catalog.get('revision'), str)
+ or not re.fullmatch('[0-9a-f]{40}', catalog['revision'])
+ or type(count) is not int or not 1 <= count <= 100
+ or not isinstance(catalog.get('tables'), list)):
+ raise ValueError('Invalid pinned Mac reference catalog')
+ selected, seen = None, set()
+ for table in catalog['tables']:
+ try:
+ value = table['identity']
+ expected = assets.identity(value['weights'], value['timesteps'], value['channels'], value['dtype'])
+ directory = assets.directory(expected)
+ if (value != expected or not isinstance(value['weights'], str)
+ or not re.fullmatch('[0-9a-f]{64}', value['weights'])
+ or table['directory'] != directory or directory in seen
+ or not isinstance(table['files'], list) or len(table['files']) != count):
+ raise ValueError('Invalid Mac reference identity or layer count')
+ indices = set()
+ for row in table['files']:
+ index = row['index']
+ if (type(index) is not int or not 0 <= index < count or index in indices
+ or row['file'] != f'reference-tables-v1/{directory}/{index:02d}.safetensors'
+ or type(row['bytes']) is not int or row['bytes'] <= 0
+ or not isinstance(row['sha256'], str)
+ or not re.fullmatch('[0-9a-f]{64}', row['sha256'])):
+ raise ValueError('Invalid Mac reference file record')
+ indices.add(index)
+ seen.add(directory)
+ except (KeyError, TypeError, AttributeError, OverflowError) as error:
+ raise ValueError('Invalid Mac reference catalog structure') from error
+ if value == identity:
+ selected = table
+ return selected
+
+
+def _read(path):
+ with Path(path).open(encoding='utf-8') as stream:
+ return json.load(stream)
+
+
+def _receipt(row):
+ return {key: row[key] for key in ('bytes', 'sha256')}
+
+
+def _network_plan(env):
+ from .paths import data_root
+ value = network.installed_plan(env)
+ value.setdefault('download_settings_path', str(data_root() / 'download-settings.json'))
+ # An installation made without a saved probe still has the two supported
+ # HF sources. ModelScope requires a separately verified revision mapping.
+ value.setdefault('sources', {}).setdefault('models', [dict(id=name)
+ for name in ('official', 'hf-mirror')])
+ return value
+
+
+def ensure(cache, identity, count, *, catalog, networking=None, env=None):
+ """Reuse or download one schedule; unsupported identities return False.
+
+ A supported transfer failure propagates. The caller must not turn it into
+ a request for the much larger original projection weights. Publication of
+ the catalog's immutable revision is a prerequisite, never inferred here.
+ """
+ table = select(catalog, identity, count)
+ if table is None:
+ return False
+ root = assets.asset_path(cache, table['directory'])
+ root.mkdir(parents=True, exist_ok=True)
+ marker = assets.asset_path(root, 'identity.json')
+ if marker.exists():
+ if _read(marker) != identity:
+ raise ValueError('Mac reference cache identity changed; files retained')
+ else:
+ save(marker, identity)
+ missing, recovered, reused = [], [], 0
+ for row in sorted(table['files'], key=lambda row: row['index']):
+ path = assets.asset_path(root, f"{row['index']:02d}.safetensors")
+ sidecar = assets.asset_path(root, f"{row['index']:02d}.json")
+ partial = assets.asset_path(root, path.name + '.partial')
+ assets.asset_path(root, partial.name + '.source.json')
+ if sidecar.exists():
+ # Local per-step GEMMs may have a different producer. Validate by
+ # their original receipt instead of replacing valid cached output.
+ if path.exists():
+ assets.check_table(path, _read(sidecar), identity)
+ reused += 1
+ continue
+ if _receipt(_read(sidecar)) != _receipt(row):
+ raise ValueError('Missing locally computed reference table; receipt retained')
+ if path.exists():
+ # Recover an interrupted publication only after checking against
+ # the bundled checksum, not a new self-generated checksum.
+ assets.check_table(path, row, identity)
+ recovered.append((sidecar, row))
+ else:
+ missing.append((path, sidecar, row))
+ # Rejected partial bytes are retained by the shared downloader. Reserve a
+ # full replacement even when an existing prefix looks complete.
+ needed = sum(row['bytes'] for _, _, row in missing)
+ if missing and shutil.disk_usage(root).free < needed + 256 * 2**20:
+ raise ValueError('Insufficient disk space for Mac reference constants; existing files retained')
+ for sidecar, row in recovered:
+ if not sidecar.exists():
+ save(sidecar, _receipt(row))
+ if not missing:
+ return True
+ env = os.environ if env is None else env
+ networking = _network_plan(env) if networking is None else networking
+ from .prepared_model import token
+ secret = token(env)
+ headers = ['Authorization: Bearer ' + secret] if secret else []
+ network.event(networking, category='models', action='reference-tables-required',
+ files=len(missing), bytes=needed, reused_files=reused,
+ recovered_files=len(recovered), revision=catalog['revision'])
+ for path, sidecar, row in missing:
+ remote = dict(row, repo=catalog['repo'], revision=catalog['revision'])
+ def progress(done, total, speed):
+ network.event(networking, category='models', action='reference-table-progress',
+ file=path.name, done=done, total=total, bytes_per_second=speed)
+ network.download(network.model_urls(networking, remote, env), path, row['sha256'],
+ size=row['bytes'], network=networking, env=env,
+ progress=progress,
+ headers_for=lambda source: headers if source == 'official' else [],
+ category=network.model_family(remote), stall_seconds=30,
+ slow_seconds=15, low_speed_limit=64 * 1024)
+ assets.check_table(path, row, identity)
+ if not sidecar.exists():
+ save(sidecar, _receipt(row))
+ return True
diff --git a/freevideo_engine/macos_reference_catalog.json b/freevideo_engine/macos_reference_catalog.json
new file mode 100644
index 0000000..29b1d2a
--- /dev/null
+++ b/freevideo_engine/macos_reference_catalog.json
@@ -0,0 +1,745 @@
+{
+ "schema_version": 1,
+ "repo": "OpenVDN/vdn-minimax-h3-edge",
+ "revision": "9a48a497c567ddcdad3dba9076f90dd58b7f2802",
+ "tables": [
+ {
+ "task": "ref2va_audio",
+ "directory": "adaln-tables-v2-16be2201bf77b8878581c987",
+ "identity": {
+ "format": "freevideo-adaln-v2",
+ "contract": "minimax-h3-adaln-silu-linear-3x6-v1",
+ "weights": "e774c1a077535cc8f79bc6ad0d99450afbbfc197d241f14c0040c7338e324649",
+ "timesteps": [
+ [
+ 0.0
+ ],
+ [
+ 0.0,
+ 0.011764705181121826,
+ 0.045454561710357666
+ ],
+ [
+ 0.0,
+ 0.027027010917663574,
+ 0.10000002384185791
+ ],
+ [
+ 0.0,
+ 0.0476190447807312,
+ 0.1666666865348816
+ ],
+ [
+ 0.0,
+ 0.07692307233810425,
+ 0.25
+ ],
+ [
+ 0.0,
+ 0.12195122241973877,
+ 0.3571428656578064
+ ],
+ [
+ 0.0,
+ 0.19999998807907104,
+ 0.5
+ ],
+ [
+ 0.0,
+ 0.3684210777282715,
+ 0.699999988079071
+ ]
+ ],
+ "channels": 5376,
+ "dtype": "BF16",
+ "modality_rows": 3,
+ "components": 6
+ },
+ "producer": {
+ "torch": "2.13.0+cu130",
+ "cuda": "13.0",
+ "gpu": "NVIDIA RTX PRO 6000 Blackwell Server Edition",
+ "implementation": "4edeeb1866b581a67ff573fa8ce9d278886e856c2a40d5113917f54f76afcab7",
+ "original_implementation": "0f94a5583d5f3f16f9e2d10f0955eb2f55a92a0b6501f339d2b6445f38614841",
+ "matmul_precision": "highest",
+ "tf32": false,
+ "bf16_reduced_reduction": true
+ },
+ "files": [
+ {
+ "index": 0,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/00.safetensors",
+ "bytes": 4258408,
+ "sha256": "cccc180d424055776a76cc10d02e8848fda8d9064dfb80c28c06c7b08d299392"
+ },
+ {
+ "index": 1,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/01.safetensors",
+ "bytes": 4258408,
+ "sha256": "dd558a9fe95c20b7880435d5d6ccc398df45db0c081276ed8de348af4af30469"
+ },
+ {
+ "index": 2,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/02.safetensors",
+ "bytes": 4258408,
+ "sha256": "439ad6e470b545bba4d40ffcf04c261001d513f7e584da5de29146bf12c01035"
+ },
+ {
+ "index": 3,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/03.safetensors",
+ "bytes": 4258408,
+ "sha256": "86b64f972310f6fff1ab2f5a327d1ebf81b4456d4ddab2c50c37a5ca2641af79"
+ },
+ {
+ "index": 4,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/04.safetensors",
+ "bytes": 4258408,
+ "sha256": "22bcc533fcd5fe01d56c10f121b8d1dd9fb6628c1047b31872691e36ed085335"
+ },
+ {
+ "index": 5,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/05.safetensors",
+ "bytes": 4258408,
+ "sha256": "88616aeac3e313e04281d2bd5eda658778d5eadaf74f4ffbc5510f2f8433e1e6"
+ },
+ {
+ "index": 6,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/06.safetensors",
+ "bytes": 4258408,
+ "sha256": "ff35f28766dfa4f7c40f5e47e20cc0c5b8c4d95191ee1115f679b9d6d00431d1"
+ },
+ {
+ "index": 7,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/07.safetensors",
+ "bytes": 4258408,
+ "sha256": "214d1834441a301f2377fa28a127487853b7a471075cc3be7b11f7c2455b5ff4"
+ },
+ {
+ "index": 8,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/08.safetensors",
+ "bytes": 4258408,
+ "sha256": "f2e9132e66cb0202240be586640a2bcf058eb3a18638434f3d70920274e82920"
+ },
+ {
+ "index": 9,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/09.safetensors",
+ "bytes": 4258408,
+ "sha256": "76750e77bc3e05307e94a099910e9d41b7b925b7c02e8a7e132035a6f1dcc081"
+ },
+ {
+ "index": 10,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/10.safetensors",
+ "bytes": 4258408,
+ "sha256": "71b942a6da4b84f2d2b494447fb605440cb239b42a292ea5543d1e461225d69e"
+ },
+ {
+ "index": 11,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/11.safetensors",
+ "bytes": 4258408,
+ "sha256": "f98b633ac8d867998e6dee898cf25c8e8088b6749bf9b02db85fb02ffda00050"
+ },
+ {
+ "index": 12,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/12.safetensors",
+ "bytes": 4258408,
+ "sha256": "61ca9419891b63f03d21b0c81e59a4d0005fae3f44fbe7ddb89daa1c4986a4e4"
+ },
+ {
+ "index": 13,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/13.safetensors",
+ "bytes": 4258408,
+ "sha256": "83075f0e886237f1e42ab962c53d7c8e8b426890b0d700bdfa80b9edad97be9f"
+ },
+ {
+ "index": 14,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/14.safetensors",
+ "bytes": 4258408,
+ "sha256": "05ac80c4ab39f8d85893d7bd14d32c40937e210f438d64f1c2057d2f47d5bf68"
+ },
+ {
+ "index": 15,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/15.safetensors",
+ "bytes": 4258408,
+ "sha256": "609a12db85e0daca1b85e027d1f046e1aee9b843e33add985bb40c9b70aa4d2b"
+ },
+ {
+ "index": 16,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/16.safetensors",
+ "bytes": 4258408,
+ "sha256": "9d27a5b48db27dcb27159b4c343ff6f7ae21957356b1ff2c426bff2b5a8a8eba"
+ },
+ {
+ "index": 17,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/17.safetensors",
+ "bytes": 4258408,
+ "sha256": "927d228a38d88e2f0f66836c73282cb0e6a7e8d68b6b9a232152ccdd46cc97da"
+ },
+ {
+ "index": 18,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/18.safetensors",
+ "bytes": 4258408,
+ "sha256": "598496e0253ab9155465391dae7fb88ec8aa779e3acfa9ab6055069a2b794240"
+ },
+ {
+ "index": 19,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/19.safetensors",
+ "bytes": 4258408,
+ "sha256": "bf777a15c52a0b0a6ea1c6491ca2af5a56cdff882f88fe95b210b18a6c3959fa"
+ },
+ {
+ "index": 20,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/20.safetensors",
+ "bytes": 4258408,
+ "sha256": "74f6203aac9520554ffce220636ff1e1e4f71e2fa9e6c65e0a33b994f709bed6"
+ },
+ {
+ "index": 21,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/21.safetensors",
+ "bytes": 4258408,
+ "sha256": "cda5ddb097911efdcd860ea1c3c39c19f0e9fa19238f0b812a5e384a987cb582"
+ },
+ {
+ "index": 22,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/22.safetensors",
+ "bytes": 4258408,
+ "sha256": "32db6c9ce9a423aaf01ee056d6de9a9006fda658b8d92b10543d6cec2412fcee"
+ },
+ {
+ "index": 23,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/23.safetensors",
+ "bytes": 4258408,
+ "sha256": "69775104c2bc6c9648f4caf45d82efa6195ae20f4918713b0cc78c7a67a9ec71"
+ },
+ {
+ "index": 24,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/24.safetensors",
+ "bytes": 4258408,
+ "sha256": "a1e7796a3f49b80db372285078671d815105c799b1044f85a284963479beee5b"
+ },
+ {
+ "index": 25,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/25.safetensors",
+ "bytes": 4258408,
+ "sha256": "a29846533760c17cdcb1bba332ddc997c674188c5ce6bd50ff5a9fceba20664b"
+ },
+ {
+ "index": 26,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/26.safetensors",
+ "bytes": 4258408,
+ "sha256": "18d8bbe5eff51f9743aaf6ac6b9d82e08e9398d3497809f3419f1daff6a65da1"
+ },
+ {
+ "index": 27,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/27.safetensors",
+ "bytes": 4258408,
+ "sha256": "6eca99a48a01d07bbe50be72152df044381b2f12b78e94d89caf8d642d048c68"
+ },
+ {
+ "index": 28,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/28.safetensors",
+ "bytes": 4258408,
+ "sha256": "133e26555c0730a18b4b2be622b8dbd1bf5048c7cc33e1e5589f04f3d1fdd840"
+ },
+ {
+ "index": 29,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/29.safetensors",
+ "bytes": 4258408,
+ "sha256": "d0844e3bd46654e1cb834b3bbddddca22fb0cea202d17d0c0c9e5cad5fa683a4"
+ },
+ {
+ "index": 30,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/30.safetensors",
+ "bytes": 4258408,
+ "sha256": "d95546607f1c7a9e7d827b74503936ef3f0fc00a65906088d0e7d399fe797bc4"
+ },
+ {
+ "index": 31,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/31.safetensors",
+ "bytes": 4258408,
+ "sha256": "ad3aa1a67810fb9086ea964f39b2b80a223ae94abffffac4e3ccf4bc344eb6b4"
+ },
+ {
+ "index": 32,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/32.safetensors",
+ "bytes": 4258408,
+ "sha256": "e23de9a6ae2e6a879b861a5d17cbb245009f838bf7e5c9ecd02e5f44bd42571e"
+ },
+ {
+ "index": 33,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/33.safetensors",
+ "bytes": 4258408,
+ "sha256": "4775ff73c3e6dcf1e6d91a2f38ad35f64578a114bb24fc7284493067098c3e70"
+ },
+ {
+ "index": 34,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/34.safetensors",
+ "bytes": 4258408,
+ "sha256": "2c9eb5c9d8be12dec907566f643c5df420ec8d31d13033b88b9d1cf0c3321cf7"
+ },
+ {
+ "index": 35,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/35.safetensors",
+ "bytes": 4258408,
+ "sha256": "65f8b4ff6808443c8d1ae225cb71ecfbe12181fa226bb591370ef4f34ec851e2"
+ },
+ {
+ "index": 36,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/36.safetensors",
+ "bytes": 4258408,
+ "sha256": "bade6315d533de39090da389c7d9172bdc9d9f41be66c23c307c98324247785e"
+ },
+ {
+ "index": 37,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/37.safetensors",
+ "bytes": 4258408,
+ "sha256": "c9af4bd53fef28e3bafa1d4feddfec2c0a4c47ba425f1d6c65b5d78c8ee86542"
+ },
+ {
+ "index": 38,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/38.safetensors",
+ "bytes": 4258408,
+ "sha256": "3cd45a1270b7bb7405d00db362354d79a5ed16200dcc2bd966182fe0fe929ec5"
+ },
+ {
+ "index": 39,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/39.safetensors",
+ "bytes": 4258408,
+ "sha256": "47a17d86e07c74fbfe760964d535b5d872e9099aa574e2b87ee17d93c76de8c2"
+ },
+ {
+ "index": 40,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/40.safetensors",
+ "bytes": 4258408,
+ "sha256": "75c8e3559499ab593b65354176970598a2247170ec2a1d95a4b6adc212517e58"
+ },
+ {
+ "index": 41,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/41.safetensors",
+ "bytes": 4258408,
+ "sha256": "595780583737400d99733d7491a183ce5ddaf88b75308d4c097651dee85eebe7"
+ },
+ {
+ "index": 42,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/42.safetensors",
+ "bytes": 4258408,
+ "sha256": "a74f72d96feebdcf5f9bf9e41c2f3a8295d22a5302cd644912df4e1546a00f75"
+ },
+ {
+ "index": 43,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/43.safetensors",
+ "bytes": 4258408,
+ "sha256": "64d5dab35b981a6dbbf26dd1704b82b294d0edee53a77118f351e6685690b360"
+ },
+ {
+ "index": 44,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/44.safetensors",
+ "bytes": 4258408,
+ "sha256": "f2b4aa1d6e78127c3cfaa4881261fbd83150ac747d6b7b337b3e3d70df7efa0d"
+ },
+ {
+ "index": 45,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/45.safetensors",
+ "bytes": 4258408,
+ "sha256": "31b7a9c96673d1b12f2afd396d559b61710d26cee969c8aa4bc1fb1a3d301c73"
+ },
+ {
+ "index": 46,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/46.safetensors",
+ "bytes": 4258408,
+ "sha256": "64985a0e5bee8295acffcb68e8e3520be96eede0bdb363268f2e398108b4807a"
+ },
+ {
+ "index": 47,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/47.safetensors",
+ "bytes": 4258408,
+ "sha256": "cd1dd7dc5999c4bc2d5a2efd726fd0f4f1eedfba54e68477db2006c743fac557"
+ },
+ {
+ "index": 48,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/48.safetensors",
+ "bytes": 4258408,
+ "sha256": "358127706e9b48591cb611c53489fe89142f7dcc6f57ecc6bc81ca0a8a346d16"
+ },
+ {
+ "index": 49,
+ "file": "reference-tables-v1/adaln-tables-v2-16be2201bf77b8878581c987/49.safetensors",
+ "bytes": 4258408,
+ "sha256": "d77241c59809be587ee20f6b3911c315fe7f557174f7ea3d8118c2c514eb6d99"
+ }
+ ]
+ },
+ {
+ "task": "ref2va_av",
+ "directory": "adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3",
+ "identity": {
+ "format": "freevideo-adaln-v2",
+ "contract": "minimax-h3-adaln-silu-linear-3x6-v1",
+ "weights": "e774c1a077535cc8f79bc6ad0d99450afbbfc197d241f14c0040c7338e324649",
+ "timesteps": [
+ [
+ 0.0,
+ 0.9990000128746033
+ ],
+ [
+ 0.0,
+ 0.011764705181121826,
+ 0.045454561710357666,
+ 0.9990000128746033
+ ],
+ [
+ 0.0,
+ 0.027027010917663574,
+ 0.10000002384185791,
+ 0.9990000128746033
+ ],
+ [
+ 0.0,
+ 0.0476190447807312,
+ 0.1666666865348816,
+ 0.9990000128746033
+ ],
+ [
+ 0.0,
+ 0.07692307233810425,
+ 0.25,
+ 0.9990000128746033
+ ],
+ [
+ 0.0,
+ 0.12195122241973877,
+ 0.3571428656578064,
+ 0.9990000128746033
+ ],
+ [
+ 0.0,
+ 0.19999998807907104,
+ 0.5,
+ 0.9990000128746033
+ ],
+ [
+ 0.0,
+ 0.3684210777282715,
+ 0.699999988079071,
+ 0.9990000128746033
+ ]
+ ],
+ "channels": 5376,
+ "dtype": "BF16",
+ "modality_rows": 3,
+ "components": 6
+ },
+ "producer": {
+ "torch": "2.13.0+cu130",
+ "cuda": "13.0",
+ "gpu": "NVIDIA RTX PRO 6000 Blackwell Server Edition",
+ "implementation": "4edeeb1866b581a67ff573fa8ce9d278886e856c2a40d5113917f54f76afcab7",
+ "original_implementation": "0f94a5583d5f3f16f9e2d10f0955eb2f55a92a0b6501f339d2b6445f38614841",
+ "matmul_precision": "highest",
+ "tf32": false,
+ "bf16_reduced_reduction": true
+ },
+ "files": [
+ {
+ "index": 0,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/00.safetensors",
+ "bytes": 5806704,
+ "sha256": "345d512cf0d8033bef2e27e2c81b27a7f9eb178209516d7b7208485599629aba"
+ },
+ {
+ "index": 1,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/01.safetensors",
+ "bytes": 5806704,
+ "sha256": "a28e0704e1218b3a854e670c3a7e5d044fa58245923bfe460bc3748b178ba618"
+ },
+ {
+ "index": 2,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/02.safetensors",
+ "bytes": 5806704,
+ "sha256": "f97bff9427d75d8da3b7a40c4bcc05304f55ac071a959f264e5d629ac16ea23f"
+ },
+ {
+ "index": 3,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/03.safetensors",
+ "bytes": 5806704,
+ "sha256": "0b07431ac3144fff2d3d1e7b189b6f926ce59bd003ed86213e8133f17b85e47d"
+ },
+ {
+ "index": 4,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/04.safetensors",
+ "bytes": 5806704,
+ "sha256": "7603f4eeec2d719307ddd87851255154b55578384cdf55aa4a3a557e2d62c812"
+ },
+ {
+ "index": 5,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/05.safetensors",
+ "bytes": 5806704,
+ "sha256": "f36e21d90d958b9a1a61a5c6a6c8b95e0f150914cf31142252ca26cd7b35cd89"
+ },
+ {
+ "index": 6,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/06.safetensors",
+ "bytes": 5806704,
+ "sha256": "349a2204d79ae69b9ed5e5a481538ccd74e74790c52158eebf7582d96f6ac121"
+ },
+ {
+ "index": 7,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/07.safetensors",
+ "bytes": 5806704,
+ "sha256": "32948b0da293c8dc3d4d41562312f575197a4d7f6274184e792c0da0dbee206e"
+ },
+ {
+ "index": 8,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/08.safetensors",
+ "bytes": 5806704,
+ "sha256": "b2adeac517dc5f4a13d1820ec33ab352a39552194b01085c6df3c70f6bf415fd"
+ },
+ {
+ "index": 9,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/09.safetensors",
+ "bytes": 5806704,
+ "sha256": "d8bc35cdd8b51702fce6fee73efafce2a3c46adc74b5c8fdbf42a3c03d0bab5e"
+ },
+ {
+ "index": 10,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/10.safetensors",
+ "bytes": 5806704,
+ "sha256": "8c448bf65255f6b1c5ff2b1622fab706b3d31872c8058912d432cba83b932d1a"
+ },
+ {
+ "index": 11,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/11.safetensors",
+ "bytes": 5806704,
+ "sha256": "ad1b36e5489467333758e50b920b96f31e9e9e4d1ca0b99020793ba08e7cc59d"
+ },
+ {
+ "index": 12,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/12.safetensors",
+ "bytes": 5806704,
+ "sha256": "c9caef11b096c8c46621dd26e29a8c71b38257d1404e22aa0f6cd000a4705a4a"
+ },
+ {
+ "index": 13,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/13.safetensors",
+ "bytes": 5806704,
+ "sha256": "3cedc27c23027dae018d2ca5c61fa2585b7e0a0145caff879527c00cdb1397fd"
+ },
+ {
+ "index": 14,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/14.safetensors",
+ "bytes": 5806704,
+ "sha256": "335030daa768dbae467dc2ad7f78e060582ea01b37e6adc4fbfa7536d3ef77ef"
+ },
+ {
+ "index": 15,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/15.safetensors",
+ "bytes": 5806704,
+ "sha256": "8a43a69af39af4bb3c99dad4dcaab1e1df93adee58662798af2509991731facd"
+ },
+ {
+ "index": 16,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/16.safetensors",
+ "bytes": 5806704,
+ "sha256": "d478a6074f513fdc2164571cd11d40f3b11d5b353db47cf8338bfa0cca40b70f"
+ },
+ {
+ "index": 17,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/17.safetensors",
+ "bytes": 5806704,
+ "sha256": "69dbe5ef7797540290a894933ff08fc0e0e8888e8be51dde96cf7a7212818383"
+ },
+ {
+ "index": 18,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/18.safetensors",
+ "bytes": 5806704,
+ "sha256": "0a21e6df79eac6bd97e54a655e42faf787e74af82cefbae36e01a1f3517f71db"
+ },
+ {
+ "index": 19,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/19.safetensors",
+ "bytes": 5806704,
+ "sha256": "346c61205eb391ca7ed02126ed3425495190f59754890b54f2b4f5a4ab22141d"
+ },
+ {
+ "index": 20,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/20.safetensors",
+ "bytes": 5806704,
+ "sha256": "a9eb9d512919aa8560ee8008a172456d6f0f8d3c22905ca0e5181902dffed66c"
+ },
+ {
+ "index": 21,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/21.safetensors",
+ "bytes": 5806704,
+ "sha256": "d9eddf54ace82cdd4dc3df1637d39efadfda57f853eee1bca141529ec5150bf3"
+ },
+ {
+ "index": 22,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/22.safetensors",
+ "bytes": 5806704,
+ "sha256": "b9c186566e3a6f37a84dd1f0dfee1de2e4cb205bab29609147586afbddd2215e"
+ },
+ {
+ "index": 23,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/23.safetensors",
+ "bytes": 5806704,
+ "sha256": "b3c0ea28bdddfff1dbade84bcecd0b5f388264e1973a616f57f274722e4070e8"
+ },
+ {
+ "index": 24,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/24.safetensors",
+ "bytes": 5806704,
+ "sha256": "c9c855f333e8fb21cfd5fef4e079f8a56bf83f747e2d05128d56cd9b340fb428"
+ },
+ {
+ "index": 25,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/25.safetensors",
+ "bytes": 5806704,
+ "sha256": "228c2d22918adad04aafd7efc5c4912a8a3558ecc1df5c4e740eb12fc949f47e"
+ },
+ {
+ "index": 26,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/26.safetensors",
+ "bytes": 5806704,
+ "sha256": "1f1959f52f3ce8ed1339f48943d05946732c716e345a441bc89fde7e0fd00da3"
+ },
+ {
+ "index": 27,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/27.safetensors",
+ "bytes": 5806704,
+ "sha256": "d559a6b582b2928b902adf8157422e2d6d8b55deb960a9b503f3a82384cf3608"
+ },
+ {
+ "index": 28,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/28.safetensors",
+ "bytes": 5806704,
+ "sha256": "ccb1453432875d63788b49a35b30ff67fde5a30f75d4a8ad887a31854f07547b"
+ },
+ {
+ "index": 29,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/29.safetensors",
+ "bytes": 5806704,
+ "sha256": "0d61de964762b9b2f2b09e230e242f6b078865cd67534c6ad1e6218d30568d81"
+ },
+ {
+ "index": 30,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/30.safetensors",
+ "bytes": 5806704,
+ "sha256": "0adacb67cb8ec9bd3db5591f8db40614d93bf80a958a74075315ee1c1e11f4d3"
+ },
+ {
+ "index": 31,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/31.safetensors",
+ "bytes": 5806704,
+ "sha256": "f1b7dc2382f6ab71745fd4216c45d790114bd24f0ccf24d1c31ce2e9305e968e"
+ },
+ {
+ "index": 32,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/32.safetensors",
+ "bytes": 5806704,
+ "sha256": "bf8f88186763200df0c079bbc62a81c3bbadac410f2dff781870ce91a9330145"
+ },
+ {
+ "index": 33,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/33.safetensors",
+ "bytes": 5806704,
+ "sha256": "d2f975ab2411b3fe08b7fee1a0f328d5c1c2fd75809b1e1085b2d622bbe3f0aa"
+ },
+ {
+ "index": 34,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/34.safetensors",
+ "bytes": 5806704,
+ "sha256": "f5ed40f8096993815a87c7f514ba996a8a8b3cdca8913b4b8e9df076428e85b6"
+ },
+ {
+ "index": 35,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/35.safetensors",
+ "bytes": 5806704,
+ "sha256": "1a82102f6f55d8fa4b63f140bda6d11d1cd2688ee95e9e67cf95f61d795d144b"
+ },
+ {
+ "index": 36,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/36.safetensors",
+ "bytes": 5806704,
+ "sha256": "219fa46ccb943d3d1cf5bc671a0eccf2dc59c642f8745f3fbaae5f205b52ad61"
+ },
+ {
+ "index": 37,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/37.safetensors",
+ "bytes": 5806704,
+ "sha256": "c7e3025d7dc10e4ab23929469fdbae9e111029a3b1f9161588e52ea2f4c18ac9"
+ },
+ {
+ "index": 38,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/38.safetensors",
+ "bytes": 5806704,
+ "sha256": "9d4d01c3395db6f8828033943e3f81b27680c1b5539981aefd15b07729b88d5b"
+ },
+ {
+ "index": 39,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/39.safetensors",
+ "bytes": 5806704,
+ "sha256": "8afab294cefb48cb6beb288cb28f0d50f965f3258b0efda2951f9b66a6ce1a8f"
+ },
+ {
+ "index": 40,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/40.safetensors",
+ "bytes": 5806704,
+ "sha256": "4ef8b3068d49a4b7260f5d4d847dc9662c11c52a4a7895984bafc5ef3da2a8ef"
+ },
+ {
+ "index": 41,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/41.safetensors",
+ "bytes": 5806704,
+ "sha256": "5314cc74aa87ec83a6bf2cb63589a6ca1af8e25a70aeb8460403207f3cb01687"
+ },
+ {
+ "index": 42,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/42.safetensors",
+ "bytes": 5806704,
+ "sha256": "aeb9a18693115a6ead1172628483c5dc77c00ebffe8d3be90cc494966e660b28"
+ },
+ {
+ "index": 43,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/43.safetensors",
+ "bytes": 5806704,
+ "sha256": "bc07fbc5bb77866fb291710f40dfb03a81ec16288c4b54d1ccb94687d95b453e"
+ },
+ {
+ "index": 44,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/44.safetensors",
+ "bytes": 5806704,
+ "sha256": "2b964defdfd01ff5e479cad829f7c27fb2650e1060c3d8110cc0b9c9b6c71217"
+ },
+ {
+ "index": 45,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/45.safetensors",
+ "bytes": 5806704,
+ "sha256": "72525028f2fe0f86680d22d54ed069c7d8c9f7fa29f9514d46d9caaf76d0f47c"
+ },
+ {
+ "index": 46,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/46.safetensors",
+ "bytes": 5806704,
+ "sha256": "0197107d52a4c43ae61c8218f3bb9dff0e7c34acb42bb5c3b01d34b0042e4760"
+ },
+ {
+ "index": 47,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/47.safetensors",
+ "bytes": 5806704,
+ "sha256": "0ed2d43d1ad8e0cdf12672217d4810dbd1783523aa14fa092284241cb160483e"
+ },
+ {
+ "index": 48,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/48.safetensors",
+ "bytes": 5806704,
+ "sha256": "630ee3bde713069d6632077ae8a3142f11d66f09180a198d54ea06b6d6906b43"
+ },
+ {
+ "index": 49,
+ "file": "reference-tables-v1/adaln-tables-v2-3ae9ea71d2372fe1f6f4dcc3/49.safetensors",
+ "bytes": 5806704,
+ "sha256": "8268992788efdb3a0bb7be63def31059e94313a2f4ba958739c2add537b63ace"
+ }
+ ]
+ }
+ ]
+}
diff --git a/freevideo_engine/macos_runtime.py b/freevideo_engine/macos_runtime.py
new file mode 100644
index 0000000..e84dc1b
--- /dev/null
+++ b/freevideo_engine/macos_runtime.py
@@ -0,0 +1,656 @@
+"""Native MPS model lifecycle around the shared VDN model, sampler and assets.
+
+The CUDA engine remains its own entry point. This explicit reference path uses
+BF16 projections, native SDPA and one streamed layer; it does not use CUDA kernel
+profiles or declare the installed application ready.
+"""
+import gc
+from contextlib import contextmanager
+import json
+import math
+from pathlib import Path
+import os
+import time
+
+
+def upscale_latents(video, sampling, base, backend, checkpoint=None):
+ """The same learned upscale/crop for resident and process-separated stages."""
+ import torch
+ from .latent_upscale import upscale
+ from .two_pass import UPSCALER, crop_latents
+ print(json.dumps(dict(event='latent_upscale', completed_steps=sampling['base_steps'],
+ total=sampling['total_steps'])), flush=True)
+ checkpoint = checkpoint or Path(base).parent / 'latent_upscaler' / Path(UPSCALER['file']).name
+ tick = time.monotonic()
+ with torch.no_grad():
+ backend.empty_cache()
+ lifted, stats = upscale(video.to('mps'), checkpoint,
+ sampling['upscale_target']['width'], sampling['upscale_target']['height'], memory_saving=True)
+ lifted = crop_latents(lifted, sampling).cpu()
+ backend.synchronize()
+ backend.empty_cache()
+ return lifted, dict(stats, stage_seconds=time.monotonic() - tick, crop=dict(sampling['crop']))
+
+
+def load_conditioning(path, device, *, task, canvas, target=None):
+ """Validate H3 inputs; resize keyframes and retain complete reference rows."""
+ import torch
+ from .conditioning import to_cache
+ from .keyframes import first_pass_conditions, validate_conditioning
+ from .media_conditioning import describe
+ value = torch.load(path, map_location='cpu', weights_only=True)
+ anchors = tuple(value.get('keyframe_anchors', ()))
+ inferred = {(): 't2va', ('first',): 'i2va', ('last',): 'l2va', ('first', 'last'): 'fl2va'}.get(anchors)
+ actual_task = value.get('task', inferred)
+ reference = str(actual_task).startswith('ref2va')
+ if (not reference and (actual_task != task or inferred != task)
+ or not anchors and value.get('condition_latents')):
+ raise ValueError('Saved conditioning does not match the native request task')
+ prompt = value['prompt_embeds']
+ if not isinstance(prompt, torch.Tensor) or prompt.ndim != 2:
+ raise ValueError('Expected saved H3 layer-50 prompt embeddings [L,5120]')
+ checked = to_cache([[prompt.unsqueeze(0), {'minimax_token_tags': value['text_token_tags']}]], task=actual_task)
+ value.update(checked, task=actual_task)
+ source = target or canvas
+ info = describe(value, source['width'], source['height'], source['frames'])
+ if info['task'] != task:
+ raise ValueError('Saved conditioning does not match the native request task')
+ if reference:
+ references = [{name: (item.to(device=device, dtype=torch.float32)
+ if isinstance(item, torch.Tensor) else item) for name, item in row.items()}
+ for row in value['references']]
+ return checked['prompt_embeds'].to(device), checked['text_token_tags'], references
+ conditions = (anchors, value['condition_latents']) if anchors else None
+ if conditions:
+ if (source['width'], source['height']) != (canvas['width'], canvas['height']):
+ # Latents are still on the host. Use the shared deterministic input
+ # resize before uploading; the original full-size anchors stay saved.
+ conditions = first_pass_conditions(conditions, source, canvas)
+ validate_conditioning(checked['prompt_embeds'], checked['text_token_tags'], conditions,
+ task, canvas['width'], canvas['height'])
+ conditions = (conditions[0], [latent.to(device, torch.float32) for latent in conditions[1]])
+ return checked['prompt_embeds'].to(device), checked['text_token_tags'], conditions
+
+
+def conditioning_tokens(task, canvas, conditions):
+ """Packed reference rows from already validated conditioning, on CPU or MPS.
+
+ Arbitrary references keep their original latent geometry in both passes;
+ keyframes follow the current pass's resized canvas. Use the same accounting
+ for lifetime admission and the actual per-pass compute plan.
+ """
+ if not conditions:
+ return {}
+ if task.startswith('ref2va'):
+ return dict(reference_video_tokens=sum(math.prod(row['latent'].shape[2:]) // 4
+ for row in conditions if row['kind'] in ('image', 'video')),
+ reference_audio_tokens=sum(row['audio_latent'].shape[0]
+ for row in conditions if row.get('audio_latent') is not None))
+ return dict(reference_video_tokens=len(conditions[0]) * (canvas['width'] // 32)
+ * (canvas['height'] // 32))
+
+
+class Engine:
+ def __init__(self, cache, *, base, checkpoint, steps=8, budget_bytes=4 * 2**30,
+ reserve_bytes=2 * 2**30, query_chunk=128, ff_chunk=256, projection_chunk=256,
+ weight_decoder='cpu', budget_ceiling_bytes=None, attention_chunk=None, task='t2va', canvas=None,
+ head_chunk=4, window_batch=1, attention_impl='torch', fast_kernels=False,
+ resident_bytes=0, attention_batch_bytes=1 << 29, plan_compute=False):
+ attention_chunk = projection_chunk if attention_chunk is None else attention_chunk
+ if type(attention_chunk) is not int or attention_chunk < 1:
+ raise ValueError('MPS attention row chunk must be a positive integer')
+ for name, value in (('head_chunk', head_chunk), ('window_batch', window_batch)):
+ if type(value) is not int or value < 1:
+ raise ValueError('MPS ' + name + ' must be a positive integer')
+ if attention_impl not in ('torch', 'mlx'):
+ raise ValueError('Native window attention must use torch or mlx')
+ if type(resident_bytes) is not int or resident_bytes < 0:
+ raise ValueError('MPS retained layer bytes must be a nonnegative integer')
+ if type(plan_compute) is not bool:
+ raise ValueError('MPS compute planning must be explicitly enabled or disabled')
+ self.plan_compute, self.compute = plan_compute, None
+ self._ff_originals = []
+ self._block_originals = []
+ self.block_policy = None
+ self.fused_modulation = bool(fast_kernels)
+ self.modulation_policy = None
+ self.resident_bytes = resident_bytes
+ self._reuse_sampling_weights = False
+ self._shared_residency = None
+ self._shared_residency_final = None
+ self.kernels = {}
+ self.kernel_stats = {}
+ from .media_request import TASKS
+ if task not in TASKS:
+ raise ValueError('Unsupported native conditioning task')
+ if task != 't2va' and canvas is None:
+ raise ValueError('Native media generation requires its full target canvas')
+ self.task, self.canvas = task, dict(canvas) if canvas is not None else None
+ from .macos_vdn import activate
+ self.overlay = activate()
+ import torch
+ from .backends import get_backend
+ from .backends.mps_weights import load_group, attach_lora
+ from .backends.mps_linear import install as install_linear
+ from .weights import skeleton
+ from .adaln import CachedModulation, ScheduleCursor, TableCache, schedule_embeddings, schedule_timesteps
+ from .adaln_assets import SLIM_FORMATS, asset_path, validate_catalog, restore_projections
+ from .attention import WindowAttention
+ from .packing import install_streamed_forward
+ self.backend = get_backend('mps')
+ if not self.backend.is_available():
+ raise RuntimeError('Native MPS is unavailable')
+ if type(steps) is not int or steps < 1:
+ raise ValueError('Sampling steps must be positive')
+ if budget_ceiling_bytes is not None and (type(budget_ceiling_bytes) is not int or budget_ceiling_bytes < 1):
+ raise ValueError('MPS budget ceiling must be a positive integer')
+ self.policy = self.backend.configure_budget(budget_bytes, reserve_bytes=reserve_bytes)
+ self.budget_ceiling_bytes = budget_ceiling_bytes
+ self.reserve_bytes = reserve_bytes
+ self.allocator_limits = [self.policy['effective_allocator_limit_bytes']]
+ self.steps, self.cache = steps, Path(cache).resolve()
+ self.base = Path(base).resolve()
+ self.model = None
+ self.closed = False
+ self.residency = None
+ self.specs = []
+ self.manifest = json.loads((self.cache / 'manifest.json').read_text())
+ manifest = self.manifest
+ precision = manifest.get('precision')
+ int8_compute = False
+ if precision == 'int8':
+ from .backends import mps_int8
+ # Apple M5 and newer run int8 products; earlier Macs read the same
+ # ConvRot weights as BF16 (better than the FP8 export, no int8 speedup).
+ int8_compute = mps_int8.available()
+ self.linear_compute = 'int8' if int8_compute else {'fp8': 'bf16-weight-only', 'int8': 'bf16-weight-only'}.get(
+ precision, 'bf16')
+ self.backend.prepare_linears(None, manifest, self.linear_compute, 'auto')
+ groups = {row['group']: row for row in manifest['groups']}
+ if len(groups) != len(manifest['groups']):
+ raise ValueError('Duplicate prepared model group')
+ def path(name):
+ row = groups[name]
+ value = asset_path(self.cache, row['file'])
+ if value.stat().st_size != row['bytes']:
+ raise ValueError('Incomplete prepared model group: ' + name)
+ return value
+ self.linears = manifest.get('linears', {})
+ self.weight_decoder_name = weight_decoder
+ if weight_decoder == 'metal':
+ from .backends.mps_fp8 import decode_weight
+ self.weight_decoder = decode_weight
+ elif weight_decoder == 'cpu':
+ self.weight_decoder = None
+ else:
+ raise ValueError('Unknown MPS weight decoder')
+ started = time.monotonic()
+ try:
+ with torch.no_grad():
+ model = self.model = skeleton(self.base, Path(checkpoint))
+ count = len(model.transformer_blocks)
+ validate_catalog(manifest, count)
+ if precision == 'int8':
+ rotation = manifest.get('rotation')
+ if rotation is not None and rotation != dict(rotation, kind='convrot', group=256):
+ raise ValueError('Unknown int8 weight rotation')
+ int8_linears = {name: entry for name, entry in manifest['linears'].items()
+ if entry.get('storage') == 'int8'}
+ if any(entry.get('convrot_group') != (256 if rotation is not None else None)
+ for entry in int8_linears.values()):
+ raise ValueError('Int8 manifest rotation differs between its Linears')
+ int8_stats = {}
+ int8_info = (mps_int8.install(model, stats=int8_stats, storage='int8', int8_linears=int8_linears)
+ if int8_compute else dict(implementation='mps-int8-dequantized-bf16'))
+ root = path('root')
+ root_lora = attach_lora(model, 'root', self.cache, manifest)
+ load_group(model, root, self.linears,
+ exclude=('transformer_blocks.', 'token_refiner.refiner_blocks.', 'rope.'),
+ decoder=self.weight_decoder)
+ model.rope.to('mps')
+ times = schedule_timesteps(steps, device='mps', task=task)
+ self.cursor = ScheduleCursor(times)
+ tables = TableCache(self.cache, manifest['source_id'], steps, manifest=manifest,
+ timesteps=times, channels=model.config.hidden_size, device='cpu', task=task)
+ embeddings = None
+ delivery_checked = False
+ for index, layer in enumerate(model.token_refiner.refiner_blocks):
+ files = [root, root_lora] if root_lora is not None else root
+ self.specs.append((layer, files, f'token_refiner.refiner_blocks.{index}.', ()))
+ for index, layer in enumerate(model.transformer_blocks):
+ self._block_originals.append((layer, layer.forward))
+ table = tables.load(index, steps)
+ if (table is None and not delivery_checked and manifest.get('format') in SLIM_FORMATS
+ and f'adaln/{index:02d}' not in groups):
+ from .macos_reference import prepare_missing
+ delivery_checked = True
+ if prepare_missing(self.cache, tables.identity, count):
+ table = tables.load(index, steps)
+ if table is None:
+ raise RuntimeError('Downloaded reference constants are incomplete; files retained')
+ if table is None:
+ if manifest.get('format') in SLIM_FORMATS and f'adaln/{index:02d}' not in groups:
+ # Audio references add time zero; arbitrary step
+ # counts can also need constants absent from a slim
+ # package. Restore the original, pinned projections
+ # through the existing shared path only on a miss.
+ # The package manifest and published tables stay
+ # immutable; verified computed tables are reusable.
+ groups.update({row['group']: row for row in restore_projections(self.cache, manifest)})
+ load_group(layer.adaln_proj, path(f'adaln/{index:02d}'), self.linears,
+ prefix=f'transformer_blocks.{index}.adaln_proj.', decoder=self.weight_decoder)
+ if embeddings is None:
+ _, embeddings = schedule_embeddings(model, steps, device='mps', task=task)
+ table = [layer.adaln_proj(value) for value in embeddings]
+ layer.adaln_proj = CachedModulation(table, self.cursor)
+ tables.save(index, layer.adaln_proj, producer_device='mps')
+ else:
+ layer.adaln_proj = CachedModulation(table, self.cursor).to('mps')
+ factors = attach_lora(layer, index, self.cache, manifest)
+ files = [path(f'blocks/{index:02d}'), factors] if factors is not None else path(f'blocks/{index:02d}')
+ self.specs.append((layer, files,
+ f'transformer_blocks.{index}.', ('adaln_proj.',)))
+ self._ff_originals.append((layer.ff, layer.ff.forward))
+ self.backend.install_chunked_ff(layer.ff, ff_chunk)
+ self.schedule_hook = model.register_forward_pre_hook(self.cursor.before, with_kwargs=True)
+ if attention_impl == 'mlx':
+ from .backends.mps_mlx_attention import MLXWindowAttention
+ self.attention = MLXWindowAttention(batch_bytes=attention_batch_bytes)
+ else:
+ self.attention = WindowAttention('mps', query_chunk=query_chunk, window_batch=window_batch,
+ device_backend=self.backend)
+ self.attention.install(model)
+ # Keep FP32 input/output packing independent from BF16 attention
+ # workspace tuning. Changing the output-head GEMM batch changed
+ # rounding and amplified differences across sampling steps.
+ install_streamed_forward(model, projection_chunk)
+ self.linear_policy = install_linear(model, head_chunk=head_chunk, gate_chunk=attention_chunk)
+ qk_prepare = None
+ if fast_kernels:
+ from functools import partial
+ from .backends import mps_delta, mps_features, mps_qk
+ self.kernel_stats = dict(delta_rule={}, features={}, qk={})
+ self.kernels = dict(
+ delta_rule=mps_delta.install(model, stats=self.kernel_stats['delta_rule']),
+ features=mps_features.install(model, stats=self.kernel_stats['features']),
+ qk='mps-fused-qk-norm-rope-v1')
+ qk_prepare = partial(mps_qk.prepare_qk, stats=self.kernel_stats['qk'])
+ self.qk_prepare = qk_prepare
+ if precision == 'int8':
+ # Fast kernels above rebuild these reports; keep the int8 receipt.
+ self.kernel_stats['int8'] = int8_stats
+ self.kernels['int8_linears'] = int8_info['implementation']
+ self._bind_attention(head_chunk=head_chunk, row_chunk=attention_chunk, ff_chunk=ff_chunk)
+ self.kernels['attention'] = attention_impl
+ model.eval().requires_grad_(False)
+ self.backend.synchronize()
+ self.load_seconds = time.monotonic() - started
+ except BaseException:
+ self.close()
+ raise
+
+ def _bind_attention(self, *, head_chunk, row_chunk, ff_chunk, bounded=False):
+ """Bind one phase's attention and owned-buffer policy as a unit.
+
+ Automatic planning currently never enables the bounded candidate. Its
+ explicit binding is available for complete native acceptance. Validate
+ the block contract before changing attention, and restore the captured
+ upstream block methods when returning to the reference path.
+ """
+ if type(bounded) is not bool:
+ raise ValueError('MPS bounded buffers must be explicitly enabled or disabled')
+ if bounded:
+ from .backends import mps_blocks, mps_grouped_qkv
+ mps_blocks.validate(self.model, row_chunk=row_chunk, ff_chunk=ff_chunk)
+ hybrid = mps_grouped_qkv.install(self.model, self.attention,
+ head_chunk=head_chunk, row_chunk=row_chunk, qk_prepare=self.qk_prepare)
+ blocks = mps_blocks.install(self.model, row_chunk=row_chunk, ff_chunk=ff_chunk)
+ else:
+ from .backends.mps_attention import install_hybrid
+ hybrid = install_hybrid(self.model, self.attention,
+ head_chunk=head_chunk, row_chunk=row_chunk, qk_prepare=self.qk_prepare)
+ if (getattr(self, 'block_policy', None) is not None
+ or getattr(self, 'modulation_policy', None) is not None):
+ for module, original in self._block_originals:
+ module.forward = original
+ blocks = None
+ self.modulation_policy = None
+ if getattr(self, 'fused_modulation', False) and not bounded:
+ from .backends import mps_modulation
+ self.modulation_policy = mps_modulation.install(self.model)
+ self.kernel_stats['modulation'] = self.modulation_policy
+ self.kernels['modulation'] = mps_modulation.IMPLEMENTATION
+ elif hasattr(self, 'kernel_stats'):
+ self.kernel_stats.pop('modulation', None)
+ self.kernels.pop('modulation', None)
+ self.hybrid_policy, self.block_policy = hybrid, blocks
+
+ def _block_metrics(self, previous=None):
+ policy = getattr(self, 'block_policy', None)
+ if policy is None:
+ return None
+ result = dict(policy)
+ for name in ('block_calls', 'post_chunks', 'modulation_chunks', 'ff_chunks'):
+ result[name] -= (previous or {}).get(name, 0)
+ return result
+
+ @contextmanager
+ def _sampling_weights(self, specs, options):
+ """Own the offloader for one sample, or for this generate() invocation."""
+ if not getattr(self, '_reuse_sampling_weights', False):
+ with self.backend.make_offloader(specs, linears=self.linears,
+ decoder=self.weight_decoder, **options) as residency:
+ yield residency
+ return
+ residency = self._shared_residency
+ if residency is None:
+ residency = self.backend.make_offloader(specs, linears=self.linears,
+ decoder=self.weight_decoder, **options)
+ # __enter__ cleans a partial load itself. Publish only a successful
+ # entry so close() never sees a half-constructed shared context.
+ residency.__enter__()
+ self._shared_residency = residency
+ else:
+ if list(specs) != residency.specs:
+ raise RuntimeError('Shared sampling weights must keep the same model and checkpoints')
+ residency.reconfigure(resident_bytes=getattr(self, 'resident_bytes', 0),
+ working_reserve_bytes=self.reserve_bytes)
+ try:
+ yield residency
+ except BaseException:
+ self._release_shared_weights()
+ raise
+
+ def _release_shared_weights(self):
+ residency = getattr(self, '_shared_residency', None)
+ if residency is not None:
+ self._shared_residency_final = residency.stats()
+ # Clear only after cleanup succeeds. A failed fence/release must be
+ # visible to Engine.close() rather than silently losing ownership.
+ residency.close()
+ self._shared_residency = None
+
+ @staticmethod
+ def _residency_metrics(residency, previous=None):
+ result = residency.stats()
+ if previous is None:
+ return result
+ counters = ('layer_loads', 'hydrated_weight_bytes', 'load_seconds',
+ 'retained_layer_hits', 'retained_layer_evictions', 'deferred_cached_forwards')
+ result = dict(result)
+ for key in counters:
+ if key in result:
+ result[key] -= previous.get(key, 0)
+ if 'prefetch' in result:
+ result['prefetch'] = dict(result['prefetch'])
+ for key in ('hits', 'misses', 'wait_seconds', 'read_seconds'):
+ result['prefetch'][key] -= previous.get('prefetch', {}).get(key, 0)
+ result.update(counter_scope='Current sampling phase', peak_scope='Shared sampling lifetime')
+ return result
+
+ def _plan_compute(self, canvas, prompt_rows):
+ """Rebind this pass's partitions against the enforced cap and actual rows.
+
+ This runs before the offloader is entered or any sampling forward. Keep
+ the original FF methods so repeated passes never nest chunk wrappers.
+ Explicit diagnostic/reference partitions opt out of planning.
+ """
+ if not getattr(self, 'plan_compute', False):
+ return
+ from .macos_compute import plan, sequence_tokens
+ from .backends.mps_linear import install as install_linear
+ rows = sequence_tokens(canvas, prompt_rows)
+ computed = plan(self.policy['effective_allocator_limit_bytes'], rows['total'],
+ frames=canvas['latent_frames'], layers=len(self.model.transformer_blocks))
+ computed.update(tokens=rows['total'], packed_rows=rows, frames=canvas['latent_frames'],
+ admission='enforced allocator cap, after conditioning; before sampling')
+ for module, original in self._ff_originals:
+ module.forward = original
+ self.backend.install_chunked_ff(module, computed['ff_chunk'])
+ self.linear_policy = install_linear(self.model, head_chunk=computed['head_chunk'],
+ gate_chunk=computed['attention_chunk'])
+ self._bind_attention(head_chunk=computed['head_chunk'], row_chunk=computed['attention_chunk'],
+ ff_chunk=computed['ff_chunk'], bounded=computed.get('bounded_buffers', False))
+ self.attention.window_batch = computed['window_batch']
+ if hasattr(self.attention, 'batch_bytes'):
+ self.attention.batch_bytes = computed['attention_batch_bytes']
+ self.resident_bytes = computed['resident_bytes']
+ self.compute = computed
+ if getattr(self, '_shared_residency', None) is not None:
+ self._shared_residency.reconfigure(resident_bytes=self.resident_bytes,
+ working_reserve_bytes=self.reserve_bytes)
+
+ def _refine_prompt(self, prompt):
+ """Release one-use prompt weights before the repeating sampling cycle.
+
+ The refined tensor lives for this sample call. Keeping its refiner
+ weights consumes the layer cache without another forward, and including
+ them in the prefetch cycle reads them again after the last video block.
+ """
+ specs = [row for row in self.specs if row[2].startswith('token_refiner.refiner_blocks.')]
+ try:
+ with self.backend.make_offloader(specs, linears=self.linears,
+ decoder=self.weight_decoder) as residency:
+ self.residency = residency
+ text = self.model.context_embedder(prompt.unsqueeze(0))
+ self.model._freevideo_refined_text = self.model.token_refiner(text)
+ return residency.stats()
+ finally:
+ self.residency = None
+
+ def sample(self, conditioning, seed, *, width, height, frames, progress_offset=0, progress_total=None,
+ initial_latents=None, refine_steps=None):
+ import torch
+ from .geometry import geometry, sampler_for_canvas
+ from .sampling_progress import SamplingProgress
+ from .system import system_memory
+ from src.inference.render import generate_latents
+ if self.closed:
+ raise RuntimeError('MPS engine is closed')
+ shared = getattr(self, '_shared_residency', None)
+ previous_residency = shared.stats() if shared is not None else None
+ if self.budget_ceiling_bytes is not None:
+ # Recheck at a phase boundary, before loading the next set of layers.
+ # Per-layer allocator changes react to transient release accounting
+ # and can shrink the limit below the next layer's working set.
+ self.policy = self.backend.configure_budget(self.budget_ceiling_bytes,
+ reserve_bytes=self.reserve_bytes)
+ self.allocator_limits.append(self.policy['effective_allocator_limit_bytes'])
+ if shared is not None:
+ # Return retained weights under newly observed pressure before even
+ # uploading conditioning or loading the one-use prompt refiner.
+ shared.reconfigure(resident_bytes=self.resident_bytes,
+ working_reserve_bytes=self.reserve_bytes)
+ refining = initial_latents is not None
+ if refining != (refine_steps is not None):
+ raise ValueError('Refinement requires both initial latents and tail steps')
+ if refining:
+ from .refine import generate_latents, validate_tail
+ validate_tail(self.steps, refine_steps)
+ elif self.task.startswith('ref2va'):
+ from .reference_sampler import generate_latents
+ active_steps = refine_steps if refining else self.steps
+ canvas = geometry(width, height, frames=frames)
+ sampler = sampler_for_canvas(generate_latents, width, height)
+ progress = SamplingProgress(active_steps, len(self.model.transformer_blocks),
+ offset=progress_offset, total=progress_total)
+ class StepTimes(list):
+ def append(owner, duration):
+ super().append(duration)
+ progress.complete(duration)
+ durations = StepTimes()
+ previous_calls = dict(self.attention.backend_calls)
+ previous_kernel_calls = {name: dict(counts) for name, counts in
+ getattr(self, 'kernel_stats', {}).items()}
+ def host_guard(module, inputs):
+ if system_memory()['available_bytes'] < 2**30:
+ raise MemoryError('MPS generation reached the 1 GiB physical RAM emergency floor')
+ guards = [module.register_forward_pre_hook(host_guard, prepend=True) for module, _, _, _ in self.specs]
+ try:
+ with torch.no_grad():
+ prompt, tags, conditions = load_conditioning(conditioning, 'mps', task=self.task,
+ canvas=canvas, target=self.canvas)
+ canvas.update(conditioning_tokens(self.task, canvas, conditions))
+ self._plan_compute(canvas, prompt.shape[0])
+ previous_block_calls = self._block_metrics()
+ self.cursor.reset(self.steps - refine_steps if refining else 0)
+ progress.start()
+ resident = getattr(self, 'resident_bytes', 0)
+ retention = (dict(resident_bytes=resident, working_reserve_bytes=self.reserve_bytes)
+ if resident else {})
+ if getattr(self, 'kernels', {}).get('delta_rule'):
+ from .macos_compute import PREFETCH_BYTES
+ # Fast kernels also stream without a per-layer sync or cache
+ # release, reading the next streamed layer during this one.
+ retention.update(synchronize_layers=False, release_cache_every_layer=False,
+ prefetch=True, prefetch_bytes=PREFETCH_BYTES)
+ text_residency = self._refine_prompt(prompt)
+ sampling_specs = [row for row in self.specs
+ if not row[2].startswith('token_refiner.refiner_blocks.')]
+ with self._sampling_weights(sampling_specs, retention) as residency, \
+ progress.layers(self.model.transformer_blocks):
+ self.residency = residency
+ video, audio = sampler(self.model, prompt, tags, canvas['frames'], self.steps,
+ seed, 'mps', step_seconds=durations,
+ **(dict(conditions=conditions) if conditions else {}),
+ **(dict(initial_latents=initial_latents, refine_steps=refine_steps)
+ if refining else {}))
+ self.backend.synchronize()
+ if not bool(video.isfinite().all()) or not bool(audio.isfinite().all()):
+ raise ValueError('MPS sampling produced nonfinite video or audio latents')
+ return video.cpu(), audio.cpu(), dict(device_backend='mps', canvas=canvas,
+ steps=active_steps, seed=seed, task=self.task, linear_compute=self.linear_compute,
+ refinement=(dict(base_steps=self.steps, steps=refine_steps,
+ start_index=self.steps - refine_steps, restart_seed=seed) if refining else None),
+ weight_decoder=self.weight_decoder_name,
+ linear_attention=self.linear_policy,
+ hybrid_attention=self.hybrid_policy,
+ block_buffers=self._block_metrics(previous_block_calls),
+ kernels=dict(getattr(self, 'kernels', {})),
+ compute=getattr(self, 'compute', None),
+ kernel_calls={name: {key: count - previous_kernel_calls.get(name, {}).get(key, 0)
+ for key, count in counts.items()}
+ for name, counts in getattr(self, 'kernel_stats', {}).items()},
+ attention_stats=dict(getattr(self.attention, 'stats', {})),
+ allocator_limits=dict(min_bytes=min(self.allocator_limits),
+ max_bytes=max(self.allocator_limits)),
+ attention_calls={name: value - previous_calls[name]
+ for name, value in self.attention.backend_calls.items()},
+ step_seconds=list(durations),
+ load_seconds=self.load_seconds, residency=self._residency_metrics(residency, previous_residency),
+ text_refiner_residency=text_residency,
+ residency_scope='Repeated video blocks; one-use prompt weights reported separately',
+ memory=self.backend.memory_stats())
+ finally:
+ for handle in guards:
+ handle.remove()
+ if self.model is not None:
+ self.model.__dict__.pop('_freevideo_refined_text', None)
+ self.residency = None
+ self.backend.empty_cache()
+
+ def generate(self, conditioning, seed, *, width, height, frames, two_pass=True, refine_steps=2,
+ upscaler_checkpoint=None, first_pass_saved=None, reuse_weights=False,
+ refinement_resident_bytes=None, phase_changed=None):
+ """Optional cross-pass weight lifetime, isolated to this one request.
+
+ Product admission remains separate. Retention obeys each sample's live
+ allocator decision and the existing per-layer pressure checks. The model
+ is released on completion, failure or cancellation, including upscaling.
+ """
+ if type(reuse_weights) is not bool:
+ raise ValueError('Cross-pass weight reuse must be explicitly enabled or disabled')
+ if refinement_resident_bytes is not None and (not reuse_weights or
+ type(refinement_resident_bytes) is not int or refinement_resident_bytes < 0):
+ raise ValueError('Refinement weight allowance requires shared sampling and nonnegative bytes')
+ if phase_changed is not None and not callable(phase_changed):
+ raise ValueError('Sampling phase callback must be callable')
+ options = dict(width=width, height=height, frames=frames, two_pass=two_pass,
+ refine_steps=refine_steps, upscaler_checkpoint=upscaler_checkpoint,
+ first_pass_saved=first_pass_saved, phase_changed=phase_changed,
+ refinement_resident_bytes=refinement_resident_bytes)
+ if getattr(self, '_reuse_sampling_weights', False) or getattr(self, '_shared_residency', None) is not None:
+ raise RuntimeError('Native sampling weight lifetimes cannot overlap')
+ if not reuse_weights:
+ return self._generate(conditioning, seed, **options)
+ self._reuse_sampling_weights = True
+ self._shared_residency = None
+ self._shared_residency_final = None
+ try:
+ video, audio, metrics = self._generate(conditioning, seed, **options)
+ finally:
+ self._reuse_sampling_weights = False
+ self._release_shared_weights()
+ metrics['shared_sampling_residency'] = self._shared_residency_final
+ return video, audio, metrics
+
+ def _generate(self, conditioning, seed, *, width, height, frames, two_pass=True, refine_steps=2,
+ upscaler_checkpoint=None, first_pass_saved=None,
+ refinement_resident_bytes=None, phase_changed=None):
+ """Use the shared canvas/schedule, including the original audio clock.
+
+ Single-pass behavior remains explicit; memory pressure never disables
+ refinement or reduces geometry. First-pass latents can be retained by
+ the worker before the upscaler runs, including on a later failure.
+ """
+ import torch
+ from .geometry import geometry
+ from .two_pass import plan
+ canvas = geometry(width, height, frames=frames)
+ if self.canvas is not None and any(canvas[k] != self.canvas[k] for k in ('width', 'height', 'frames')):
+ raise ValueError('Native generation differs from its loaded target canvas')
+ sampling = plan(canvas, enabled=two_pass, task=self.task,
+ base_steps=self.steps, refine_steps=refine_steps)
+ if phase_changed is not None:
+ phase_changed('first-pass')
+ video, audio, first = self.sample(conditioning, seed, **sampling['first'],
+ progress_total=sampling['total_steps'])
+ metrics = dict(sampling_plan=sampling, sampling_passes=[first])
+ if not sampling['enabled']:
+ return video, audio, metrics
+ if first_pass_saved is not None:
+ first_pass_saved(video, audio, metrics)
+ if phase_changed is not None:
+ phase_changed('upscale')
+ shared = getattr(self, '_shared_residency', None)
+ if shared is not None and refinement_resident_bytes is not None:
+ # The larger second-pass workspace may retain fewer layers. Return
+ # those weights before loading the upscaler, keeping eligible ones.
+ shared.reconfigure(resident_bytes=min(shared.resident_limit, refinement_resident_bytes),
+ working_reserve_bytes=self.reserve_bytes)
+ lifted, metrics['latent_upscale'] = upscale_latents(video, sampling, self.base,
+ self.backend, upscaler_checkpoint)
+ if phase_changed is not None:
+ phase_changed('refinement')
+ result, sound, second = self.sample(conditioning, seed + sampling['restart_seed_offset'],
+ **sampling['second'], initial_latents=(lifted, audio), refine_steps=refine_steps,
+ progress_offset=self.steps, progress_total=sampling['total_steps'])
+ if not torch.equal(sound, audio):
+ raise ValueError('MPS refinement changed first-pass audio')
+ metrics['sampling_passes'].append(second)
+ return result, sound, metrics
+
+ def close(self):
+ shared = getattr(self, '_shared_residency', None)
+ self._release_shared_weights()
+ if self.residency is not None and self.residency is not shared:
+ self.residency.close()
+ self.residency = None
+ if getattr(self, 'schedule_hook', None) is not None:
+ self.schedule_hook.remove()
+ self.schedule_hook = None
+ self.specs.clear()
+ self._ff_originals.clear()
+ self._block_originals.clear()
+ self.block_policy = None
+ self.model = None
+ self.attention = None
+ self.closed = True
+ gc.collect()
+ self.backend.empty_cache()
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *args):
+ self.close()
diff --git a/freevideo_engine/macos_setup.py b/freevideo_engine/macos_setup.py
new file mode 100644
index 0000000..9f6b4c5
--- /dev/null
+++ b/freevideo_engine/macos_setup.py
@@ -0,0 +1,60 @@
+"""Native package/source steps inside the shared installer lifecycle."""
+import json
+
+from .bootstrap import Installer as SharedInstaller, SOURCE
+from . import macos_bootstrap as native
+from .monitoring import save
+
+
+class Installer(SharedInstaller):
+ def __init__(self, value, ui=None):
+ native.require_native()
+ super().__init__(value, ui)
+
+ def device_environment(self, env):
+ return native.environment(self.root, env)
+
+ def device_configuration(self):
+ return dict(device_backend='mps', device_identity=self.plan['inventory']['selected_device'])
+
+ def prepare_tools(self):
+ return native.prepare_uv(self.root, self.network, self.env, self.fetch)
+
+ def component_tasks(self, uv):
+ tasks = {}
+ def task(name, run, after=(), writes=()):
+ tasks[name] = dict(run=run, after=tuple(after), writes=tuple(writes))
+ python = self.pythons['engine']
+ writer = ('environment:unified',)
+ task('python', lambda: self.python_install(uv))
+ task('unified-venv', lambda: None if python.is_file() else
+ self.command('unified-venv', [uv, 'venv', '--python', native.PYTHON_VERSION, self.root / 'envs/unified']),
+ ('python',), writer)
+ task('runtime', lambda: self.packages('unified-packages', [uv, 'pip', 'install', '--python', python,
+ '-r', SOURCE / 'constraints/macos-runtime-requirements.txt', '-c', native.constraints()]),
+ ('unified-venv',), writer)
+ task('engine', lambda: self.packages('unified-engine', [uv, 'pip', 'install', '--python', python,
+ '--no-deps', '-e', SOURCE]), ('runtime',), writer)
+ task('vdn-source', lambda: self.command('vdn-source', [python, '-c',
+ 'from freevideo_engine.install import install; install()']), ('unified-venv',))
+ task('vdn-install', lambda: self.packages('vdn', [uv, 'pip', 'install', '--python', python,
+ '--no-deps', '-e', self.root / 'vendor/vdn' / self.spec['vdn']['diffusers_subdirectory']]),
+ ('engine', 'vdn-source'), writer)
+ task('encoder-source', lambda: self.clone('h3-text-encoder',
+ self.spec['encoder']['comfy_url'], self.spec['encoder']['comfy_commit']))
+ task('models', lambda: self.command('models', [python, '-m', 'freevideo_engine.provision',
+ '--plan', self.run_dir / 'plan.json']), ('engine',))
+ return tasks, {'unified': python}, self.root / 'vendor/h3-text-encoder'
+
+ def check_kernels(self, python, kernel_report):
+ # A cheap native execution check is repeated on repair. Do not reuse
+ # a CUDA receipt or claim a full model benchmark from this probe.
+ self.command('kernels', [python, '-m', 'freevideo_engine.macos_doctor',
+ '--probe', '--require-paths', '--out', kernel_report])
+ result = json.loads(kernel_report.read_text(encoding='utf-8'))
+ if not result.get('ready') or result.get('device_backend') != 'mps':
+ raise RuntimeError('Native GPU checks did not complete; see the retained report')
+ save(self.root / 'kernel-capabilities.json', result)
+
+ def record_kernel_validation(self, results, kernel_report):
+ pass # Native checks have no optional CUDA package build receipt.
diff --git a/freevideo_engine/macos_shortcut.py b/freevideo_engine/macos_shortcut.py
new file mode 100644
index 0000000..dc256c6
--- /dev/null
+++ b/freevideo_engine/macos_shortcut.py
@@ -0,0 +1,116 @@
+"""A Finder shortcut to a retained native app; no scripts or global installation."""
+import json
+import os
+from pathlib import Path
+import plistlib
+import shutil
+import subprocess
+import sys
+import tempfile
+import uuid
+
+from .desktop_shortcut import digest
+from .monitoring import save
+
+
+def desktop_directory():
+ from PySide6.QtCore import QStandardPaths
+ value = QStandardPaths.writableLocation(QStandardPaths.DesktopLocation)
+ if not value:
+ raise OSError('macOS could not locate your desktop folder')
+ return Path(value)
+
+
+def application():
+ executable = Path(sys.executable).resolve()
+ if not getattr(sys, 'frozen', False) or len(executable.parents) < 3:
+ raise OSError('Open FreeVideo.app to create its desktop shortcut')
+ app = executable.parents[2]
+ try:
+ info = plistlib.loads((app / 'Contents/Info.plist').read_bytes())
+ except (OSError, ValueError) as error:
+ raise OSError('The FreeVideo application bundle is incomplete') from error
+ if (app.suffix != '.app' or info.get('CFBundleIdentifier') != 'org.flashml.FreeVideo'
+ or (app / 'Contents/MacOS' / info.get('CFBundleExecutable', '')).resolve() != executable):
+ raise OSError('The running executable does not belong to FreeVideo.app')
+ return app, executable
+
+
+def retained_application(engine):
+ app, executable = application()
+ parent = Path(engine).resolve() / 'launcher/application.noindex'
+ # Already running from a retained app; do not copy it again.
+ if app.is_relative_to(parent):
+ return app
+ # The executable contains the frozen Python code. Include the bundle metadata
+ # to distinguish packaging changes with the same executable.
+ import hashlib
+ identity = hashlib.sha256((digest(executable) + digest(app / 'Contents/Info.plist')).encode()).hexdigest()
+ target = parent / identity / 'FreeVideo.app'
+ def valid(path):
+ if not path.is_dir() or path.is_symlink():
+ return False
+ try:
+ result = subprocess.run(['/usr/bin/codesign', '--verify', '--deep', '--strict', str(path)],
+ capture_output=True, timeout=30)
+ return result.returncode == 0 and digest(path / 'Contents/MacOS' / executable.name) == digest(executable)
+ except (OSError, subprocess.SubprocessError):
+ return False
+ if valid(target):
+ return target
+ parent.mkdir(parents=True, exist_ok=True)
+ stage = Path(tempfile.mkdtemp(prefix='launcher-', dir=parent))
+ try:
+ prepared = stage / 'FreeVideo.app'
+ # Preserve framework links, permissions and signing resources.
+ subprocess.run(['/usr/bin/ditto', str(app), str(prepared)], check=True, capture_output=True, timeout=120)
+ if not valid(prepared):
+ raise OSError('The copied FreeVideo application failed verification')
+ if target.parent.exists():
+ target = parent / (identity + '-' + uuid.uuid4().hex[:8]) / 'FreeVideo.app'
+ stage.rename(target.parent)
+ return target
+ except subprocess.SubprocessError as error:
+ raise OSError('Could not prepare the FreeVideo desktop shortcut') from error
+ finally:
+ if stage.exists():
+ shutil.rmtree(stage)
+
+
+def create(engine):
+ receipt = Path(engine) / 'launcher/desktop-shortcut.json'
+ target = retained_application(engine)
+ desktop = desktop_directory().resolve()
+ path = desktop / 'FreeVideo.app'
+ try:
+ previous = json.loads(receipt.read_text(encoding='utf-8'))
+ except (OSError, ValueError):
+ previous = {}
+ old = Path(previous.get('path', str(path)))
+ owned = (old.parent == desktop and old.is_symlink()
+ and os.readlink(old) == previous.get('target'))
+ if owned:
+ path = old
+ if previous['target'] == str(target):
+ return dict(previous, status='present')
+ else:
+ index = 2
+ while os.path.lexists(path):
+ path = desktop / ('FreeVideo (%d).app' % index)
+ index += 1
+ if owned:
+ stage = desktop / ('FreeVideo-' + uuid.uuid4().hex + '.app')
+ try:
+ stage.symlink_to(target, target_is_directory=True)
+ if not path.is_symlink() or os.readlink(path) != previous.get('target'):
+ raise OSError('The desktop shortcut changed while updating; retry to keep the new item')
+ os.replace(stage, path)
+ finally:
+ if stage.is_symlink():
+ stage.unlink()
+ else:
+ # An unrelated file appearing during creation must never be overwritten.
+ path.symlink_to(target, target_is_directory=True)
+ result = dict(status='created', kind='macos-app-symlink', path=str(path), target=str(target))
+ save(receipt, result)
+ return result
diff --git a/freevideo_engine/macos_stages.py b/freevideo_engine/macos_stages.py
new file mode 100644
index 0000000..baac1ac
--- /dev/null
+++ b/freevideo_engine/macos_stages.py
@@ -0,0 +1,318 @@
+"""Run native generation stages with explicit sampling process lifetimes.
+
+The controller imports no tensor runtime. Its existing parent supervises the
+whole process tree and records one continuous engine log and memory observation.
+"""
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+import time
+import traceback
+
+from . import processes
+from .locking import LOCK_ENV, runtime_lock
+from .monitoring import save
+
+
+def sampling_lifetime(resource):
+ # New requests choose auto in macos_generate.policy. Preserve the historical
+ # lifetime when replaying saved requests which predate this field.
+ mode = resource.get('sampling_lifetime', 'phase')
+ if mode not in ('phase', 'auto', 'request'):
+ raise ValueError('Unknown native sampling lifetime: ' + str(mode))
+ return mode
+
+
+def joined_admission(engine, value):
+ """Decide in the GPU worker, using its enforced cap and validated packed rows."""
+ mode = sampling_lifetime(value['resources'])
+ if mode == 'phase' or not value['sampling']['enabled']:
+ return dict(selected=False, mode=mode, reason='separate-or-single-pass')
+ task = value.get('task', 't2va')
+ from .macos_runtime import conditioning_tokens, load_conditioning
+ from .macos_compute import shared_sampling_plan
+ if engine.policy.get('enforced') is not True:
+ raise ValueError('Shared sampling requires an enforced MPS allocator policy')
+ phase_tokens = None
+ if task == 't2va':
+ prompt, _, conditions = load_conditioning(value['conditioning'], 'cpu',
+ task=task, canvas=value['canvas'])
+ if conditions is not None:
+ raise ValueError('Shared text sampling received unexpected media conditioning')
+ prompt_rows = prompt.shape[0]
+ else:
+ from .geometry import geometry
+ phase_tokens, prompt_rows = {}, None
+ for phase, key in (('first-pass', 'first'), ('refinement', 'second')):
+ canvas = geometry(**value['sampling'][key])
+ prompt, _, conditions = load_conditioning(value['conditioning'], 'cpu',
+ task=task, canvas=canvas, target=value['canvas'])
+ if prompt_rows is not None and prompt.shape[0] != prompt_rows:
+ raise ValueError('Prompt row count changed between sampling admissions')
+ prompt_rows = prompt.shape[0]
+ phase_tokens[phase] = conditioning_tokens(task, canvas, conditions)
+ del prompt, conditions
+ result = shared_sampling_plan(engine.policy['effective_allocator_limit_bytes'],
+ value['sampling'], prompt_rows,
+ phase_reference_tokens=phase_tokens)
+ return dict(result, selected=mode == 'request' or result['eligible'], mode=mode)
+
+
+def retain_joined_progress(result, observed):
+ """Recover completed sampling when a joined child fails later in the request."""
+ rows = observed.get('sampling_passes', [])
+ expected = (result['sampling_plan']['base_steps'], result['sampling_plan']['refine_steps'])
+ if (not isinstance(rows, list) or len(rows) > 2 or any(
+ not isinstance(row, dict) or not isinstance(row.get('step_seconds'), list)
+ or len(row['step_seconds']) != expected[index] for index, row in enumerate(rows))):
+ raise ValueError('Invalid completed joined sampling report')
+ result['sampling_passes'] = rows
+ result['step_seconds'] = [t for row in rows for t in row['step_seconds']]
+ result['load_seconds'] = observed.get('load_seconds', 0.)
+ result['sample_seconds'] = observed.get('completed_work_seconds', 0.)
+ result['latent_save_seconds'] = observed.get('latent_save_seconds', 0.)
+ result['phase'] = observed.get('sampling_phase', result['phase'])
+
+
+def run(value):
+ output, artifacts = Path(value['output']), Path(value['artifacts'])
+ sampling = value['sampling']
+ path = output.with_suffix('.engine.json')
+ result = dict(success=False, device_backend='mps', phase='load', geometry=value['canvas'],
+ sampling_plan=sampling, stages={}, sampling_passes=[])
+ started = time.monotonic()
+ def interrupted(signum, frame):
+ raise KeyboardInterrupt('Native stage interrupted by signal ' + str(signum))
+ previous = processes.termination_handler(interrupted)
+ try:
+ lifetime = sampling_lifetime(value['resources'])
+ with runtime_lock() as descriptor:
+ stages = ['first-pass', 'upscale', 'refinement', 'decode'] if sampling['enabled'] else ['first-pass', 'decode']
+ joined = False
+ for stage in stages:
+ if joined and stage in ('upscale', 'refinement'):
+ continue
+ result['phase'] = stage
+ save(path, result)
+ request = artifacts / (stage + '-request.json')
+ receipt = artifacts / (stage + '-result.json')
+ save(request, dict(value, phase=stage, report=str(receipt)))
+ tick = time.monotonic()
+ try:
+ # Inherit stdout/stderr: progress and errors stay in the same
+ # engine log consumed by the existing UI and report exporter.
+ processes.run([sys.executable, '-m', __name__, '--request', str(request)],
+ env=dict(os.environ, **{LOCK_ENV: str(descriptor)}),
+ pass_fds=(descriptor,), check=True)
+ finally:
+ if receipt.is_file():
+ try:
+ observed = json.loads(receipt.read_text(encoding='utf-8'))
+ if not isinstance(observed, dict):
+ raise ValueError('Native stage receipt is not an object')
+ except (OSError, ValueError) as error:
+ # A child killed while writing its receipt must not
+ # replace the original failure/cancellation with a
+ # secondary JSON error in this controller.
+ observed = dict(success=False, receipt_error=str(error))
+ result['stages'][stage] = dict(observed, process_seconds=time.monotonic() - tick)
+ observed = result['stages'].get(stage, {})
+ if observed.get('success') is not True:
+ raise RuntimeError('Native stage did not complete: ' + stage)
+ if stage == 'first-pass' and observed.get('joined_sampling') is True:
+ if lifetime == 'phase':
+ raise ValueError('Separate sampling request reported a joined child')
+ if not sampling['enabled']:
+ raise ValueError('Single-pass request reported joined refinement')
+ retain_joined_progress(result, observed)
+ if len(result['sampling_passes']) != 2:
+ raise ValueError('Joined sampling omitted a requested pass')
+ result['latent_upscale'] = observed['latent_upscale']
+ result['shared_sampling_residency'] = observed['shared_sampling_residency']
+ result['sampling_admission'] = observed['sampling_admission']
+ joined = True
+ elif stage in ('first-pass', 'refinement'):
+ result['sampling_passes'].append(observed['sampling'])
+ if stage == 'first-pass' and sampling['enabled']:
+ save(artifacts / 'first-pass.json', dict(sampling_plan=sampling,
+ sampling_passes=result['sampling_passes']))
+ elif stage == 'upscale':
+ result['latent_upscale'] = observed['upscale']
+ else:
+ result['decode'] = observed['decode']
+ result['decode_save_seconds'] = observed['work_seconds']
+ # Keep completed work visible if a later stage fails or the
+ # controller is interrupted. Failed/incomplete work is retained
+ # separately in the stage receipt and process elapsed time.
+ completed = {k: s for k, s in result['stages'].items() if s.get('success') is True}
+ result.update(load_seconds=sum(s.get('load_seconds', 0.) for s in completed.values()),
+ sample_seconds=sum(s['work_seconds'] for k, s in completed.items() if k != 'decode'),
+ latent_save_seconds=sum(s.get('latent_save_seconds', 0.) for s in completed.values()),
+ step_seconds=[t for row in result['sampling_passes'] for t in row['step_seconds']])
+ if (len(result['step_seconds']) != sampling['total_steps'] or
+ not output.is_file() or output.stat().st_size == 0):
+ raise RuntimeError('Native stages did not produce the complete requested video')
+ result.update(success=True, phase='complete')
+ except BaseException as error:
+ observed = result['stages'].get('first-pass', {})
+ if observed.get('joined_sampling') is True and observed.get('success') is not True:
+ try:
+ retain_joined_progress(result, observed)
+ except (ValueError, TypeError, KeyError) as receipt_error:
+ observed['progress_receipt_error'] = str(receipt_error)
+ result.update(error_type=type(error).__name__, error_message=str(error), exception=traceback.format_exc(),
+ cancelled=isinstance(error, KeyboardInterrupt))
+ raise
+ finally:
+ processes.restore_handlers(previous)
+ result['worker_seconds'] = time.monotonic() - started
+ save(path, result)
+
+
+def stage_compute(resource, canvas):
+ """Partitions for this sampling stage from its live unified-memory allowance.
+
+ The supervisor's policy fixes the reserve and allocator ceiling; the stage
+ process sees its own live availability, which is larger after the encoder
+ or a previous stage exited. Explicit `compute_plan: False` keeps the
+ reference partitions."""
+ if resource.get('compute_plan') is False:
+ return {}
+ from .geometry import geometry
+ from .macos_compute import plan
+ from .system import system_memory
+ available = system_memory()['available_bytes'] - resource['reserve_bytes']
+ budget = int(max(0, min(resource['allocator_capacity_bytes'], available)))
+ shape = geometry(canvas['width'], canvas['height'], frames=canvas['frames'])
+ tokens, frames = shape['video_tokens'] + 1024, shape['latent_frames']
+ result = plan(budget, tokens, frames=frames)
+ try:
+ import mlx.core as mx
+ mx.array([1.0]) # Fails early where Metal is unusable for MLX.
+ result['attention_impl'] = 'mlx'
+ except Exception:
+ result['attention_impl'] = 'torch'
+ result.update(fast_kernels=resource.get('fast_kernels', True), tokens=tokens, frames=frames)
+ return result
+
+
+def worker(value):
+ from .macos_bootstrap import require_native
+ require_native()
+ import torch
+ torch.set_num_threads(2)
+ resource, sampling = value['resources'], value['sampling']
+ artifacts, phase = Path(value['artifacts']), value['phase']
+ result = dict(success=False, device_backend='mps', phase=phase)
+ started = time.monotonic()
+ try:
+ sampling_lifetime(resource)
+ if phase in ('first-pass', 'refinement'):
+ from .macos_runtime import Engine
+ refining = phase == 'refinement'
+ if refining and not sampling['enabled']:
+ raise ValueError('Refinement is absent from this sampling plan')
+ initial = torch.load(artifacts / 'upscaled.pt', map_location='cpu', weights_only=True) if refining else None
+ print(json.dumps(dict(event='model_load_phase', phase='Loading native MPS model')), flush=True)
+ compute = stage_compute(resource, sampling['second' if refining else 'first'])
+ result['compute'] = compute
+ with Engine(value['cache'], base=value['base'], checkpoint=value['checkpoint'],
+ steps=sampling['base_steps'], budget_bytes=resource['allocator_capacity_bytes'],
+ budget_ceiling_bytes=resource['allocator_capacity_bytes'],
+ reserve_bytes=resource['reserve_bytes'], query_chunk=resource['query_chunk'],
+ ff_chunk=compute.get('ff_chunk', resource['ff_chunk']),
+ projection_chunk=resource['projection_chunk'],
+ attention_chunk=compute.get('attention_chunk', resource.get('attention_chunk')),
+ weight_decoder=resource['weight_decoder'],
+ head_chunk=compute.get('head_chunk', 4), window_batch=compute.get('window_batch', 1),
+ attention_impl=compute.get('attention_impl', 'torch'),
+ fast_kernels=compute.get('fast_kernels', False),
+ resident_bytes=compute.get('resident_bytes', 0),
+ attention_batch_bytes=compute.get('attention_batch_bytes', 1 << 29),
+ plan_compute=bool(compute),
+ task=value.get('task', 't2va'), canvas=value['canvas']) as engine:
+ result['load_seconds'] = engine.load_seconds
+ tick = time.monotonic()
+ admission = joined_admission(engine, value) if not refining else dict(selected=False)
+ result['sampling_admission'] = admission
+ if admission['selected']:
+ result.update(joined_sampling=True, sampling_passes=[], latent_save_seconds=0.)
+ def changed(stage):
+ result['sampling_phase'] = stage
+ save(Path(value['report']), result)
+ def first_saved(video, audio, metrics):
+ save_started = time.monotonic()
+ torch.save(dict(video=video, audio=audio), artifacts / 'first-pass.pt')
+ save(artifacts / 'first-pass.json', metrics)
+ result['latent_save_seconds'] += time.monotonic() - save_started
+ result['sampling_passes'] = list(metrics['sampling_passes'])
+ result['completed_work_seconds'] = time.monotonic() - tick - result['latent_save_seconds']
+ save(Path(value['report']), result)
+ video, audio, measured = engine.generate(value['conditioning'], value['seed'],
+ width=value['canvas']['width'], height=value['canvas']['height'],
+ frames=value['canvas']['frames'], two_pass=True, refine_steps=sampling['refine_steps'],
+ reuse_weights=True, refinement_resident_bytes=admission['refinement_resident_bytes'],
+ first_pass_saved=first_saved, phase_changed=changed)
+ result.update(sampling_passes=measured['sampling_passes'],
+ shared_sampling_residency=measured['shared_sampling_residency'],
+ latent_upscale=measured['latent_upscale'], sampling_phase='latent-save')
+ result['work_seconds'] = time.monotonic() - tick - result['latent_save_seconds']
+ result['completed_work_seconds'] = result['work_seconds']
+ else:
+ video, audio, measured = engine.sample(value['conditioning'],
+ value['seed'] + (sampling['restart_seed_offset'] if refining else 0),
+ **sampling['second' if refining else 'first'], progress_total=sampling['total_steps'],
+ progress_offset=sampling['base_steps'] if refining else 0,
+ **(dict(initial_latents=(initial['video'], initial['audio']), refine_steps=sampling['refine_steps'])
+ if refining else {}))
+ if refining and not torch.equal(audio, initial['audio']):
+ raise ValueError('MPS refinement changed first-pass audio')
+ if measured.get('compute') is not None:
+ result.update(initial_compute=compute, compute=measured['compute'])
+ result.update(sampling=measured, work_seconds=time.monotonic() - tick)
+ name = ('first-pass.pt' if not refining and sampling['enabled']
+ and not result.get('joined_sampling') else 'latents.pt')
+ elif phase == 'upscale':
+ from .macos_vdn import activate
+ activate()
+ from .backends import get_backend
+ from .macos_runtime import upscale_latents
+ backend = get_backend('mps')
+ result['policy'] = backend.configure_budget(resource['allocator_capacity_bytes'],
+ reserve_bytes=resource['reserve_bytes'])
+ initial = torch.load(artifacts / 'first-pass.pt', map_location='cpu', weights_only=True)
+ video, stats = upscale_latents(initial['video'], sampling, value['base'], backend)
+ audio = initial['audio']
+ result.update(upscale=stats, work_seconds=stats['stage_seconds'])
+ name = 'upscaled.pt'
+ elif phase == 'decode':
+ from .macos_decode import decode_to_file
+ initial = torch.load(artifacts / 'latents.pt', map_location='cpu', weights_only=True)
+ tick = time.monotonic()
+ result['decode'] = decode_to_file(initial['video'], initial['audio'], value['output'],
+ base=value['base'], artifacts_dir=artifacts,
+ budget_bytes=resource['allocator_capacity_bytes'], reserve_bytes=resource['reserve_bytes'])
+ result.update(work_seconds=time.monotonic() - tick, success=True)
+ return
+ else:
+ raise ValueError('Unknown native generation stage: ' + str(phase))
+ if not bool(video.isfinite().all()) or not bool(audio.isfinite().all()):
+ raise ValueError('Native stage produced nonfinite latents')
+ tick = time.monotonic()
+ torch.save(dict(video=video, audio=audio), artifacts / name)
+ result.update(latent_save_seconds=result.get('latent_save_seconds', 0.) + time.monotonic() - tick,
+ success=True)
+ except BaseException as error:
+ result.update(error_type=type(error).__name__, error_message=str(error), exception=traceback.format_exc())
+ raise
+ finally:
+ result['worker_seconds'] = time.monotonic() - started
+ save(Path(value['report']), result)
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--request', type=Path, required=True)
+ worker(json.loads(parser.parse_args().request.read_text(encoding='utf-8')))
diff --git a/freevideo_engine/macos_vdn.py b/freevideo_engine/macos_vdn.py
new file mode 100644
index 0000000..dd3c5a5
--- /dev/null
+++ b/freevideo_engine/macos_vdn.py
@@ -0,0 +1,119 @@
+"""Verified Mac import overlay for the pinned VDN source; originals stay clean.
+
+CUDA-only imports, sampler synchronization and dead tensor lifetimes are adapted.
+The reference hybrid equations, model topology, schedule and checkpoint names are unchanged.
+Optimized CUDA inference kernels remain unavailable on this reference MPS path.
+"""
+import hashlib
+import importlib
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+
+
+EDITS = {
+ 'src/models/hybrid_attention.py': (
+ ('from src.models.ops.fp8_linear import Fp8Linear, quantize_activation\n', ''),
+ (' if all(isinstance(p, Fp8Linear) for p in projections):\n',
+ ' fp8 = False\n'
+ ' if x.is_cuda:\n'
+ ' from src.models.ops.fp8_linear import Fp8Linear, quantize_activation\n'
+ ' fp8 = all(isinstance(p, Fp8Linear) for p in projections)\n'
+ ' if fp8:\n'),
+ (' del softmax_out\n', ' del softmax_out, flat\n'),
+ ),
+ 'src/models/linear_attention/features.py': (
+ ('from src.models.ops.temporal_conv import temporal_conv_activate\n', ''),
+ (' out = temporal_conv_activate(x, w_tm, conv.KERNEL, conv.KERNEL // 2,\n',
+ ' from src.models.ops.temporal_conv import temporal_conv_activate\n'
+ ' out = temporal_conv_activate(x, w_tm, conv.KERNEL, conv.KERNEL // 2,\n'),
+ ),
+ 'src/models/hybrid_transform.py': (
+ ('from src.models.ops.fused_block import fast_block_forward, fast_ff_forward\n', ''),
+ (' block.forward = types.MethodType(fast_block_forward, block)\n',
+ ' from src.models.ops.fused_block import fast_block_forward, fast_ff_forward\n'
+ ' block.forward = types.MethodType(fast_block_forward, block)\n'),
+ ),
+ 'src/inference/render.py': (
+ ('torch.cuda.synchronize(device)', 'torch.mps.synchronize()'),
+ # RoPE immediately casts coordinates to FP32. Move that exact cast
+ # before device transfer because MPS cannot store float64 tensors.
+ ('position_ids.to(device), token_tags.to(device)',
+ 'position_ids.to(dtype=torch.float32).to(device), token_tags.to(device)'),
+ ),
+}
+
+
+def adapt(name, content):
+ for before, after in EDITS.get(name, ()):
+ count = 3 if before == 'torch.cuda.synchronize(device)' else 1
+ if content.count(before) != count:
+ raise ValueError('Pinned VDN Mac patch no longer matches: ' + name)
+ content = content.replace(before, after)
+ compile(content, name, 'exec')
+ return content
+
+
+def prepare(source, directory):
+ source, directory = Path(source).resolve(), Path(directory).resolve()
+ spec = json.loads(Path(__file__).with_name('dependencies.json').read_text())['vdn']
+ def git(*args):
+ return subprocess.check_output(['git', *args], cwd=source).decode('utf-8')
+ if git('rev-parse', 'HEAD').strip() != spec['commit'] or git('status', '--porcelain', '--untracked-files=no').strip():
+ raise ValueError('Mac overlay requires the clean pinned VDN checkout')
+ files = [name for name in git('ls-files', '-z', 'src').split('\0') if name]
+ if not files or not set(EDITS).issubset(files):
+ raise ValueError('Pinned VDN source is incomplete')
+ content = {}
+ for name in files:
+ path = source / name
+ if path.is_symlink():
+ raise ValueError('Unexpected source symlink in the pinned VDN tree')
+ data = path.read_bytes()
+ content[name] = adapt(name, data.decode('utf-8')).encode('utf-8') if name in EDITS else data
+ hashes = {name: hashlib.sha256(data).hexdigest() for name, data in content.items()}
+ identity = dict(schema_version=1, upstream_commit=spec['commit'], files=hashes)
+ key = hashlib.sha256(json.dumps(identity, sort_keys=True).encode()).hexdigest()[:24]
+ target = directory / ('vdn-mps-' + key)
+ def validate():
+ for name, expected in hashes.items():
+ path = target / name
+ if path.is_symlink() or hashlib.sha256(path.read_bytes()).hexdigest() != expected:
+ raise ValueError('VDN Mac overlay failed verification: ' + name)
+ if target.exists():
+ validate()
+ return target
+ directory.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory(prefix='vdn-mps-', dir=directory) as temp:
+ stage = Path(temp) / 'overlay'
+ for name, data in content.items():
+ path = stage / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_bytes(data)
+ (stage / 'identity.json').write_text(json.dumps(identity, indent=2) + '\n')
+ shutil.copyfile(source / 'LICENSE', stage / 'LICENSE')
+ try:
+ stage.rename(target)
+ except OSError:
+ if not target.is_dir():
+ raise
+ validate()
+ return target
+
+
+def activate():
+ if sys.platform != 'darwin':
+ raise RuntimeError('The VDN MPS overlay is for the native Mac runtime')
+ from .paths import add_vdn, data_root
+ source = add_vdn()
+ target = prepare(source, data_root() / 'vendor')
+ loaded = sys.modules.get('src')
+ if loaded is not None and not Path(loaded.__file__).resolve().is_relative_to(target):
+ raise RuntimeError('VDN was already imported without its Mac overlay; start a fresh worker')
+ if str(target) not in sys.path:
+ sys.path.insert(0, str(target))
+ importlib.import_module('src')
+ return target
diff --git a/freevideo_engine/media_encoding.py b/freevideo_engine/media_encoding.py
index a113db9..eaaa095 100644
--- a/freevideo_engine/media_encoding.py
+++ b/freevideo_engine/media_encoding.py
@@ -6,6 +6,7 @@ in the generation process. Reference clips must be explicitly trimmed to 15 s.
"""
import json
import math
+from contextlib import nullcontext
from pathlib import Path
@@ -153,52 +154,62 @@ def prepare(media, canvas, directory):
return result, {'images': key_images} if key_images else {'minimax_ref_items': ref_items} if ref_items else {}
-def encode_latents(normalized, value, base, canvas, *, resident=None):
+def encode_latents(normalized, value, base, canvas, *, resident=None, device='cuda'):
import gc
import numpy as np
import torch
from diffusers.modular_pipelines.minimax_h3.encoders import encode_vae_condition
from .vae_weights import load_audio_vae, load_video_encoder
from src.inference.render import PIXEL_MEAN, PIXEL_STD
+ if torch.device(device).type not in ('cuda', 'mps'):
+ raise ValueError('Media encoding requires a CUDA or MPS device')
+ empty_cache = torch.mps.empty_cache if torch.device(device).type == 'mps' else torch.cuda.empty_cache
refs = [{'kind': row['kind']} for row in normalized]
if any(row.get('pixels') for row in normalized):
print(json.dumps({'event': 'media_encode_phase', 'phase': 'Encoding image/video references'}), flush=True)
# Conditioning never decodes: the 9.0 GiB decoder in the shared shards
# is not read. The independent output decoder is loaded after sampling.
vae, _ = load_video_encoder(base, before_upload=None if resident is None else
- lambda model: resident.input_vae_room(model, canvas))
- for row, ref in zip(normalized, refs):
- if row.get('pixels'):
- mapped = np.load(row['pixels'], mmap_mode='r', allow_pickle=False)
- if row['frames'] == 1:
- pixels = torch.from_numpy(np.array(mapped[:1])).to('cuda').permute(3, 0, 1, 2)[None]
- ref['latent'] = encode_vae_condition(vae, pixels, PIXEL_MEAN, PIXEL_STD, 42).cpu()
- del pixels
- else:
- ref['latent'] = encode_visual(vae, mapped[:row['frames']])
- del mapped
- from .streamed_weights import release_file_pages
- release_file_pages([Path(row['pixels'])])
+ lambda model: resident.input_vae_room(model, canvas), device=device)
+ lifetime = nullcontext()
+ if torch.device(device).type == 'mps':
+ from .backends.mps_vae_encode import bounded_encoder
+ lifetime = bounded_encoder(vae)
+ with lifetime as memory:
+ for row, ref in zip(normalized, refs):
+ if row.get('pixels'):
+ mapped = np.load(row['pixels'], mmap_mode='r', allow_pickle=False)
+ if row['frames'] == 1:
+ pixels = torch.from_numpy(np.array(mapped[:1])).to(device).permute(3, 0, 1, 2)[None]
+ ref['latent'] = encode_vae_condition(vae, pixels, PIXEL_MEAN, PIXEL_STD, 42).cpu()
+ del pixels
+ else:
+ ref['latent'] = encode_visual(vae, mapped[:row['frames']], device=device)
+ del mapped
+ from .streamed_weights import release_file_pages
+ release_file_pages([Path(row['pixels'])])
+ if memory is not None:
+ print(json.dumps(dict(event='media_encode_memory', video_encoder=memory)), flush=True)
del vae
gc.collect()
- torch.cuda.empty_cache()
+ empty_cache()
if any(row.get('audio') for row in normalized):
print(json.dumps({'event': 'media_encode_phase', 'phase': 'Encoding reference audio'}), flush=True)
vae, _ = load_audio_vae(base, before_upload=None if resident is None else
- lambda model: resident.input_vae_room(model, canvas, audio=True))
+ lambda model: resident.input_vae_room(model, canvas, audio=True), device=device)
mean = torch.tensor(vae.config.latents_mean).view(1, 1, -1)
std = torch.tensor(vae.config.latents_std).view(1, 1, -1)
if vae.config.sampling_rate != 32000:
raise ValueError('Reference audio normalization requires the pinned 32 kHz H3 VAE')
for row, ref in zip(normalized, refs):
if row.get('audio'):
- audio = torch.from_numpy(np.load(row['audio'], allow_pickle=False)).to('cuda')
+ audio = torch.from_numpy(np.load(row['audio'], allow_pickle=False)).to(device)
latent = vae.encode(audio[:, None], return_dict=False)[0].mode().float().cpu().transpose(1, 2)
ref['audio_latent'] = ((latent - mean) / std).reshape(-1, 32).contiguous()
del audio, latent
del vae
gc.collect()
- torch.cuda.empty_cache()
+ empty_cache()
if any(row.get('anchor') for row in normalized):
value.update(keyframe_anchors=[row['anchor'] for row in normalized],
condition_latents=[row['latent'] for row in refs])
diff --git a/freevideo_engine/model_guidance.py b/freevideo_engine/model_guidance.py
index 5d1e8f6..26020de 100644
--- a/freevideo_engine/model_guidance.py
+++ b/freevideo_engine/model_guidance.py
@@ -1,9 +1,38 @@
"""User-facing model download destinations, from the installation manifests."""
import json
from pathlib import Path
+import sys
from urllib.parse import quote, urlsplit
+def runtime_packages_supported():
+ return sys.platform != 'darwin'
+
+
+def package_instructions(new_comfy, zh=False):
+ """Describe the payloads this host can actually import."""
+ if sys.platform == 'darwin':
+ return (
+ 'Get Common models and the RTX 30/40 model pack; these model files also work on Mac. '
+ 'The installer downloads the Mac environment automatically. Do not download the Windows Environment package.',
+ '下载「公用模型」和「30/40 系模型包」,其中的模型文件也适用于 Mac。'
+ 'Mac 运行环境由安装器自动下载,无需下载 Windows「运行环境」包。')[bool(zh)]
+ text = ('Get Common models and the pack for your GPU (RTX 30/40 or RTX 50).',
+ '下载「公用模型」和对应显卡包(30/40 系或 50 系)。')[bool(zh)]
+ if new_comfy:
+ text += '\n' + ('For a new installation, also get the Environment package.',
+ '全新安装还需「运行环境」包。')[bool(zh)]
+ return text
+
+
+def video_instructions(zh=False):
+ if sys.platform == 'darwin':
+ return ('For Mac, choose the RTX 30/40 model files and keep their folder structure.',
+ 'Mac 请选择 30/40 系模型文件,并保留下载的目录结构。')[bool(zh)]
+ return ('Choose your GPU variant on the model page and keep its folder structure.',
+ '按模型页说明选择显卡版本,保留下载的目录结构。')[bool(zh)]
+
+
def links():
root = Path(__file__).parent
spec = json.loads((root / 'dependencies.json').read_text(encoding='utf-8'))['models']
diff --git a/freevideo_engine/modern_launcher.py b/freevideo_engine/modern_launcher.py
index 40d35b8..7e322e0 100644
--- a/freevideo_engine/modern_launcher.py
+++ b/freevideo_engine/modern_launcher.py
@@ -29,11 +29,24 @@ def theme():
heightSm=32, height=36, heightLg=44, mono=b.MONO)
+def launcher_icon():
+ from PySide6.QtGui import QIcon
+ if sys.platform == 'darwin' and getattr(sys, 'frozen', False):
+ # Keep the padded native icon after Qt takes ownership of the Dock icon.
+ icon = QIcon(str(Path(sys.executable).parent.parent / 'Resources/FreeVideo.icns'))
+ if not icon.isNull():
+ return icon
+ icon = QIcon(str(Path(__file__).parent / 'assets/icon.ico'))
+ if icon.isNull():
+ icon = QIcon(str(Path(__file__).parent / 'assets/icon.png'))
+ return icon
+
+
def create_ui(session, *, show=True):
from .windows_ux import taskbar_identity
taskbar_identity()
from PySide6.QtCore import QObject, Property, QTimer, QUrl, Signal, Slot, Qt
- from PySide6.QtGui import QFont, QIcon
+ from PySide6.QtGui import QFont
from PySide6.QtWidgets import QApplication, QFileDialog
from PySide6.QtQml import QQmlApplicationEngine
from PySide6.QtQuick import QQuickWindow, QSGRendererInterface
@@ -49,9 +62,7 @@ def create_ui(session, *, show=True):
font.setFamilies(['Segoe UI', 'Microsoft YaHei UI', 'Noto Sans', 'Noto Sans CJK SC', 'sans-serif'])
font.setPointSize(10)
app.setFont(font)
- icon = QIcon(str(Path(__file__).parent / 'assets/icon.ico'))
- if icon.isNull():
- icon = QIcon(str(Path(__file__).parent / 'assets/icon.png'))
+ icon = launcher_icon()
app.setWindowIcon(icon)
class Bridge(QObject):
@@ -252,6 +263,11 @@ def create_ui(session, *, show=True):
raise RuntimeError('FreeVideo desktop layout could not be loaded')
window = engine.rootObjects()[0]
window.setIcon(icon)
+ if sys.platform == 'darwin':
+ # Native traffic lights and resizing, with content behind the titlebar.
+ # ApplicationWindow keeps controls inside the platform's safe area.
+ window.setFlag(Qt.ExpandedClientAreaHint, True)
+ window.setFlag(Qt.NoTitleBarBackgroundHint, True)
available = app.primaryScreen().availableGeometry()
width = min(1440, int(available.width() * .86))
height = min(1020, int(available.height() * .88))
@@ -329,6 +345,23 @@ def smoke_test(app, engine, window, bridge, destination):
def main(session=None):
+ if (getattr(sys, 'frozen', False) and sys.platform == 'darwin'
+ and sys.argv[1:2] == ['--macos-process-host']):
+ from .macos_process_host import main as supervise
+ raise SystemExit(supervise(sys.argv[2:]))
+ # A Mac app carries its own lightweight interpreter. Dispatch managed
+ # children before Qt and run from the durable deployed source, so a fresh
+ # Mac does not need a system Python or Homebrew merely to review setup.
+ if (getattr(sys, 'frozen', False) and sys.platform == 'darwin'
+ and len(sys.argv) >= 3 and sys.argv[1] == '--managed'):
+ source = Path(sys.argv[2])
+ if not (source / 'freevideo_engine/managed.py').is_file():
+ raise ValueError('The managed launcher source is missing')
+ sys.path.insert(0, str(source))
+ import freevideo_engine
+ freevideo_engine.__path__.insert(0, str(source / 'freevideo_engine'))
+ from .managed import main as managed
+ raise SystemExit(managed(sys.argv[3:]))
# Linux process supervision reexecutes sys.executable. A frozen GUI must
# dispatch this helper before creating another application window.
if (getattr(sys, 'frozen', False) and sys.platform == 'linux'
diff --git a/freevideo_engine/network.py b/freevideo_engine/network.py
index 06ce5dc..039e073 100644
--- a/freevideo_engine/network.py
+++ b/freevideo_engine/network.py
@@ -263,7 +263,7 @@ def probe(family, name, spec, versions, timeout, env, *, measure_speed=False):
url = model_url({'repo': mirror['repo'], 'revision': mirror['hf_revision'],
'file': mirror['probe_file']}, name, env, spec=spec)
elif family == 'github':
- url = versions['uv']['url'].replace(SOURCES['github']['official'], base, 1)
+ url = versions.get('github_probe_url', versions['uv']['url']).replace(SOURCES['github']['official'], base, 1)
elif family == 'git':
endpoint = spec['vdn']['url'].replace(SOURCES['github']['official'], base, 1)
kind = 'Git remote availability with effective Git configuration'
@@ -354,9 +354,9 @@ def plan(spec, versions, layout='unified', *, mode='auto', timeout=5, offline=Fa
families = ['pypi', 'models', 'vdn-models', 'github', 'git', 'cuda']
if spec['models'].get('edge_modelscope'):
families.insert(3, 'edge-models')
- if versions.get('target_system') == 'Windows':
+ if versions.get('target_system') in ('Windows', 'Darwin'):
families.remove('cuda')
- for name in environment_names(layout):
+ for name in (() if versions.get('target_system') == 'Darwin' else environment_names(layout)):
role = ENVIRONMENTS[name]
family = 'torch-' + role['cuda'] + '-' + role['torch'][0].split('==')[1]
if family not in families:
diff --git a/freevideo_engine/offline_packages.py b/freevideo_engine/offline_packages.py
index 1ba56bf..e68a76a 100644
--- a/freevideo_engine/offline_packages.py
+++ b/freevideo_engine/offline_packages.py
@@ -44,6 +44,12 @@ def inventory(rows):
raise ValueError('Offline package exceeds supported size')
+def check_runtime_platform():
+ import sys
+ if sys.platform == 'darwin':
+ raise ValueError('这是 Windows 运行环境包,不能用于 Mac。请导入模型包后继续安装,安装器会自动下载 Mac 运行环境。')
+
+
def inspect_archive(path):
"""Read only bounded metadata; file contents are checked during import."""
with zipfile.ZipFile(path) as archive:
@@ -58,11 +64,15 @@ def inspect_archive(path):
raw = archive.read(info)
value = json.loads(raw)
if marker == 'runtime.json':
+ check_runtime_platform()
if value.get('schema_version') != 2 or value.get('dependency_id') != dependency_id():
raise ValueError('运行环境包版本不匹配,请从下载页面获取配套的运行环境包。')
value = dict(value, kind='runtime', variant=None)
elif value.get('schema_version') != 1 or value.get('kind') != 'models' or value.get('variant') not in ('common', 'rowwise', 'per_tensor'):
raise ValueError('Invalid model package')
+ import sys
+ if sys.platform == 'darwin' and value.get('variant') == 'per_tensor':
+ raise ValueError('Mac 请使用「30/40 系模型包」;「公用模型」包可以通用。此处无需导入 50 系模型包。')
rows = value['files']
if not isinstance(rows, list) or not rows:
raise ValueError('Empty offline package')
@@ -138,6 +148,7 @@ def import_archive(path, destination, progress=lambda **kw: None, cancelled=lamb
def assemble(runtime, models, source):
"""Bind imported components to the current EXE's engine, without running it."""
from .desktop_runtime import materialize_source
+ check_runtime_platform()
runtime = Path(runtime)
config = json.loads((runtime / 'runtime.json').read_text(encoding='utf-8'))
if config.get('schema_version') != 2 or config.get('dependency_id') != dependency_id():
diff --git a/freevideo_engine/pass_configuration.py b/freevideo_engine/pass_configuration.py
index 913e536..aa67abf 100644
--- a/freevideo_engine/pass_configuration.py
+++ b/freevideo_engine/pass_configuration.py
@@ -35,9 +35,8 @@ def configuration(engine, selected):
grouped_outputs=values['grouped_attention_outputs'], parallelism=previous.get('head_parallelism', 1))
if changed.intersection(('ff_chunk', 'fp8_ff_recompute')):
if previous.get('precision') == 'fp8' and previous.get('linear_compute') == 'native-fp8':
- from .fp8_ops import install_chunked_ff
for block in model.transformer_blocks:
- install_chunked_ff(block.ff, values['ff_chunk'], recompute=values['fp8_ff_recompute'])
+ engine.device_backend.install_chunked_ff(block.ff, values['ff_chunk'], recompute=values['fp8_ff_recompute'])
elif 'ff_chunk' in changed:
# Ampere keeps its existing weight-only arithmetic. Replace
# the outer row tiling without nesting the old tiling wrapper.
diff --git a/freevideo_engine/prepared_model.py b/freevideo_engine/prepared_model.py
index 20cb003..3b39f36 100644
--- a/freevideo_engine/prepared_model.py
+++ b/freevideo_engine/prepared_model.py
@@ -1,7 +1,8 @@
"""Pinned prebuilt model selection and access checks, without Torch or Hub SDKs.
The catalog is shipped with the engine, never learned from an unverified remote
-manifest. Each architecture keeps its existing FP8 quantization granularity.
+manifest. Each CUDA architecture keeps its existing FP8 quantization granularity;
+Macs use the ConvRot int8 export (int8 products on Apple M5 and newer).
"""
import json
import os
@@ -38,9 +39,11 @@ def catalog():
return value
-def select(capability, root):
+def select(capability, root, *, scale_granularity=None):
value = catalog()
- scale = 'per_tensor' if capability[0] >= 10 else 'rowwise'
+ scale = scale_granularity or ('per_tensor' if capability[0] >= 10 else 'rowwise')
+ if scale not in ('rowwise', 'per_tensor', 'int8_convrot'):
+ raise ValueError('Unknown prepared model scale format')
variant = value['variants'].get(scale)
if variant is None:
return None # Never change quantization to make an artifact fit a GPU.
diff --git a/freevideo_engine/prepared_models.json b/freevideo_engine/prepared_models.json
index 0318219..76a12e7 100644
--- a/freevideo_engine/prepared_models.json
+++ b/freevideo_engine/prepared_models.json
@@ -2792,6 +2792,1402 @@
"sha256": "0a47d21f4ba8079a3cfd4fdc6f60d2779f2d2c76dc38fe3ad4bc6f539f33eba1"
}
]
+ },
+ "int8_convrot": {
+ "revision": "da37681f5a1f7015fdb63482142b865111b687d3",
+ "cache_prefix": "int8-convrot/cache",
+ "files": [
+ {
+ "file": "LICENSE",
+ "bytes": 17604,
+ "sha256": "59b99642b95ea21630e311198ddbfffbfe05aadba0c2f5d884cbdf4efcc90f44"
+ },
+ {
+ "file": "MODIFICATIONS.md",
+ "bytes": 1813,
+ "sha256": "fe13fc06b364ca13861cf10644d923e91fc98b26eb8963acb3e288f94b7bb2ca"
+ },
+ {
+ "file": "NOTICE",
+ "bytes": 2320,
+ "sha256": "6b6671af343af83d5c8bff1b13875e9fe8ffd338f43d4343fa9efa96f49cf81f"
+ },
+ {
+ "file": "OPENVDN-CODE-LICENSE",
+ "bytes": 11358,
+ "sha256": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30"
+ },
+ {
+ "file": "README.md",
+ "bytes": 5691,
+ "sha256": "695ab321638eaa4c562a2459d5886d664ab60df97c3639d4e62a03302a2075da"
+ },
+ {
+ "file": "SHA256SUMS",
+ "bytes": 64864,
+ "sha256": "041b9c02f324e47952901b306876f1137b62e9ac5707798d669c177831747f75"
+ },
+ {
+ "file": "bundle.json",
+ "bytes": 246317,
+ "sha256": "61723f4193be73eba18216f8bb441b30444fc9912cdfb36dd6b05e6067875c51"
+ },
+ {
+ "file": "config/h3-base/audio_scheduler/scheduler_config.json",
+ "bytes": 96,
+ "sha256": "804780f7133477067bd6bbfbc02dc8b3cf9feeb400f97c08f5b1d5f6cbab3840"
+ },
+ {
+ "file": "config/h3-base/audio_vae/config.json",
+ "bytes": 2271,
+ "sha256": "9a3c645ff892b376c6f5f4c8685964cd75474731af594ff058492a0000caabb6"
+ },
+ {
+ "file": "config/h3-base/model_index.json",
+ "bytes": 2936,
+ "sha256": "5a587fe13b2371427415ac892463142683aefcd8d322e274a3a095eac37ac7d2"
+ },
+ {
+ "file": "config/h3-base/modular_model_index.json",
+ "bytes": 2935,
+ "sha256": "a2b6a210e482ffb78e613b553f570c44e101afce6741bd4ed91429d0559af031"
+ },
+ {
+ "file": "config/h3-base/scheduler/scheduler_config.json",
+ "bytes": 97,
+ "sha256": "8fa6c3aa70dc9e691e1a6df899fd1b6f75f70481a27cee6e18a303817075c304"
+ },
+ {
+ "file": "config/h3-base/transformer/config.json",
+ "bytes": 546,
+ "sha256": "74c11bff524336576096993cbfcdcdc2ef4fa2fa4409df693bdcbc6c666282ae"
+ },
+ {
+ "file": "config/h3-base/transformer/diffusion_pytorch_model.safetensors.index.json",
+ "bytes": 64488,
+ "sha256": "ac30a3b58963f2e735d493475fbb81853a5735ec947619648b3e045acda6783e"
+ },
+ {
+ "file": "config/h3-base/vae/config.json",
+ "bytes": 2011,
+ "sha256": "78f67deec3d63aae807f2bfe7154bc1e26f6372cb20b63265fcbae1b62bb5745"
+ },
+ {
+ "file": "config/h3-base/vae/diffusion_pytorch_model.safetensors.index.json",
+ "bytes": 74228,
+ "sha256": "15f6d44553c3c616b0dc999920aa784f92ecee7e4201f1f99ac405cfbf3061ca"
+ },
+ {
+ "file": "config/stage-dmd-step-250/adapters/default/adapter_config.json",
+ "bytes": 415,
+ "sha256": "89e0ff8920b9629b826eb99ab6150cce6924a53aa445186d1b493225fd091b96"
+ },
+ {
+ "file": "config/stage-dmd-step-250/adapters/turbo/adapter_config.json",
+ "bytes": 22264,
+ "sha256": "627968f670747c29cd7a0d3f8c75166e501d70f9e829b5cd3242a8f14cefbc18"
+ },
+ {
+ "file": "config/stage-dmd-step-250/linear_branch/config.json",
+ "bytes": 465,
+ "sha256": "decb06ac7e664610f677fb445318502b3c51f9c1b8603a2cdd00b16042be5bc8"
+ },
+ {
+ "file": "config/stage-dmd-step-250/metadata.json",
+ "bytes": 463,
+ "sha256": "54054ceb1c91b3fdf7fa0278e4a8841c127e8cf666b5e240d69613661f9d3e9e"
+ },
+ {
+ "file": "config/stage-dmd-step-250/model_spec.json",
+ "bytes": 25705,
+ "sha256": "4171f4384e952f1f73467981a893440c03298af4956b947e2c8a857ba9f5a62b"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/00.json",
+ "bytes": 103,
+ "sha256": "9f4e7a1a78227586e374f8400e5e43691d7acddea4a7025b8285faa29e72a166"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/00.safetensors",
+ "bytes": 4456040,
+ "sha256": "5f8393a55e4508b4f03a2325848cf74fa854dfdf84a0d949e9614079acd2bf80"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/01.json",
+ "bytes": 103,
+ "sha256": "df9828c32a00ad365559189433b3f9fb00fa5eb5ba8305479c8ad19f4e16e12e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/01.safetensors",
+ "bytes": 4456040,
+ "sha256": "77bb900f64a824f59337498db5734c60f5c63517dca576c1b41a08db81cdc122"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/02.json",
+ "bytes": 103,
+ "sha256": "a1d674d4625648e4bfa7d49c41ccb1df365bf8547c2a838e29b3ec1ec6773ac0"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/02.safetensors",
+ "bytes": 4456040,
+ "sha256": "14e9486da0c80467e24aeb11ac95c0cef3c8de3ce6726d65c4568ab5a50c1011"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/03.json",
+ "bytes": 103,
+ "sha256": "b57783199d8bcb461b988fb4d1c3099493a8a002bb6c451f291942269887b9e8"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/03.safetensors",
+ "bytes": 4456040,
+ "sha256": "4d3bad61fc4cb241a4c4ffca7be68fdcf6d39df2d92696ee509a84f35cb2d7fa"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/04.json",
+ "bytes": 103,
+ "sha256": "c01364b637d1e4b287c063e236e1537f293bb4f0f10b624b2ff0b8aef019526d"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/04.safetensors",
+ "bytes": 4456040,
+ "sha256": "6d70b16a07e8567cb46662515d50ace7cadda46a1e261d209a6c87fad9fe7526"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/05.json",
+ "bytes": 103,
+ "sha256": "53dfefeaffe68c2c3cc4690189d0e55ff7048019cfa99536f2a089f954bc0c8e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/05.safetensors",
+ "bytes": 4456040,
+ "sha256": "9a24951daec182dddb6ce26bd6d126f61dc6d2bf18b8b79d4a70acf58a4170e9"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/06.json",
+ "bytes": 103,
+ "sha256": "430fcab5a7d27589337f052f453a185c96ad863b86ab4539ec0bf140fbf811e2"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/06.safetensors",
+ "bytes": 4456040,
+ "sha256": "85914eb7fce42adcd50099cea5b94ce2bad2b5cb79801a35ee50a9937adc2417"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/07.json",
+ "bytes": 103,
+ "sha256": "8c7b6a8f88b924d7bddb0e7065dc18c8647911fe2d9bca6af135801fc8a59bd3"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/07.safetensors",
+ "bytes": 4456040,
+ "sha256": "70c91870a43f75433a138d1b25512101411d9be9b8cb0ea698c80d608fdf35ce"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/08.json",
+ "bytes": 103,
+ "sha256": "0657f0bf73d8e83a389f90036399fd709d5cf54be0e125b5014016b77e8912ec"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/08.safetensors",
+ "bytes": 4456040,
+ "sha256": "6ea4f9049e4d122f4b2a3605693303a4d641eee51761a40c2051cbe55e4a272e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/09.json",
+ "bytes": 103,
+ "sha256": "bfb87bf7c84f37b28a46c8c7dd0c3b234e859f472c50b4d8bbc92098cf159f9a"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/09.safetensors",
+ "bytes": 4456040,
+ "sha256": "27cf9a8e782978097d4f2f03dd1850c7fab6ca5fd26b07c862ff0ea2ca38f434"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/10.json",
+ "bytes": 103,
+ "sha256": "5bec30a89a118f2df88647854e21cbebdbdce4aaea94c946e7eec2268e1c97eb"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/10.safetensors",
+ "bytes": 4456040,
+ "sha256": "c1ec60a934fc204428cd9024055d00f7fa47d3559df59d2d7027ebf7ccb7701e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/11.json",
+ "bytes": 103,
+ "sha256": "be4c002eb1dc8147b97e4d26bdfae0454a48a429658832efa84a5664cf4d72e3"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/11.safetensors",
+ "bytes": 4456040,
+ "sha256": "b8e355d21647fa4e469751adaea39f06d62ed199a2992ac72ac5c90770d1d568"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/12.json",
+ "bytes": 103,
+ "sha256": "6b00e52bd9cd5a31bf8874f1f15354e5b9bc61e4b1da57576d9514c4085def57"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/12.safetensors",
+ "bytes": 4456040,
+ "sha256": "a5d354c48003a089291691bf56d4331706a472f648bb62912cc8af409c25578e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/13.json",
+ "bytes": 103,
+ "sha256": "ee3d624e7d3f960c09a455bd3234c442e6bffccd5077c8fd386d943c73c4e02d"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/13.safetensors",
+ "bytes": 4456040,
+ "sha256": "4122d04f791a8016ff49dfd231882f74687b82b1c9a06a10a880ef59bf2a7d69"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/14.json",
+ "bytes": 103,
+ "sha256": "7b291de7d7c8e41af72c58365021eb056a522769f1f5469cb26215f528355185"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/14.safetensors",
+ "bytes": 4456040,
+ "sha256": "ee95aa1af4119eae75a1a0ccfd2025e027c86d8b7d2b3df3250c25a8bd138b74"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/15.json",
+ "bytes": 103,
+ "sha256": "46af01a80546e13333e5c953a7bd3357ad29753ab3feab23a3e9169c1dd3c039"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/15.safetensors",
+ "bytes": 4456040,
+ "sha256": "b89596e56262b0df121edb2326a28686440648ddcc1127412338a0d55d98899d"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/16.json",
+ "bytes": 103,
+ "sha256": "1032ebb5fd59ad41ec0e3dec041c97fd04eed75beacb0cb4b9226f8109ccde02"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/16.safetensors",
+ "bytes": 4456040,
+ "sha256": "1e7be09355ee83361a728cd36c8afb8ab8ab37ebe4b51b52f8229a4cb3d1f1ed"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/17.json",
+ "bytes": 103,
+ "sha256": "d233a342c828941dcfd5f2348b0ce913bc758b55d5c642504adb544bab98bb97"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/17.safetensors",
+ "bytes": 4456040,
+ "sha256": "78244289bb051cceb4dace8bce6e067142084cee5e8d553a762295d5cb9f334f"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/18.json",
+ "bytes": 103,
+ "sha256": "97c77fe5aa17f48076237ebb6f6d8544ede7cd8502f8d2ffd688961b2f9dedd5"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/18.safetensors",
+ "bytes": 4456040,
+ "sha256": "59ca9c3c668d2e9ed20604795a174ae6ddee215fee748e487dc82ee23b534ad2"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/19.json",
+ "bytes": 103,
+ "sha256": "3cf14069cf7c8a943966dd4e8c50097796027b916cd54c18d4c8e589295cd41f"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/19.safetensors",
+ "bytes": 4456040,
+ "sha256": "d0a9deb167d4ac5d7f411a5dd14909138b09c8061755f84e5e3f1378b9dcf894"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/20.json",
+ "bytes": 103,
+ "sha256": "d56ddff6182dae0858ebecf44f8f787858d9ad238eaf7a1563b4e7797323bb6b"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/20.safetensors",
+ "bytes": 4456040,
+ "sha256": "40feb488ac29ba6e99cf1fff1b9d4b9078a422449e648f24553d3ec93fee6530"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/21.json",
+ "bytes": 103,
+ "sha256": "069977435cb785cbfb0c3a64f7f21f6b25ad3db546e906808f2caf8bcae58742"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/21.safetensors",
+ "bytes": 4456040,
+ "sha256": "cd1a3c5737e3a82f15d79d3f37ba3df3c0430c3a6df832752826e786b6893b59"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/22.json",
+ "bytes": 103,
+ "sha256": "e5393d760b3a4c7637b7360fc900ae791c7186257fc9bac82f20f35eb80462da"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/22.safetensors",
+ "bytes": 4456040,
+ "sha256": "935c5019a9862e16f94920090040d7b09ba7ef786678ca453aacc91bd7e2d67e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/23.json",
+ "bytes": 103,
+ "sha256": "a4f90e63f9d5f3d493922fd380f74eb69b58dbbb2e6862df9129d2687ffa15ae"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/23.safetensors",
+ "bytes": 4456040,
+ "sha256": "5215c662929c9a036155a21726d9b6775644bccd0cefaca79477b4c65fadf3b6"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/24.json",
+ "bytes": 103,
+ "sha256": "2aaa013e47a920bafc20e8b61095fd07f9d49bfd5e7e96b312cc4d7c0e6ef133"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/24.safetensors",
+ "bytes": 4456040,
+ "sha256": "8c651e18158f3c70e9e335b18962ee0a1f1843b6d040630dceb3e979440c657c"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/25.json",
+ "bytes": 103,
+ "sha256": "11cf276b0e9d79ea7336b63c9a0ac31aa09aec2687612024da948e11dc47f3d8"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/25.safetensors",
+ "bytes": 4456040,
+ "sha256": "530db57adcf090f8fe18e282373fca02fa3ad13820a2075c804344d6bad732ed"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/26.json",
+ "bytes": 103,
+ "sha256": "dc5db4988090533757f84bc254feb444b67a18f775cd7c4290f0004ae690bbaa"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/26.safetensors",
+ "bytes": 4456040,
+ "sha256": "de0e8a74e0b02a9d2122f0d461311b0f6b8645aef362ff37aab529ef92c3070a"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/27.json",
+ "bytes": 103,
+ "sha256": "35b1e9adc2427f82940094336727e241139044f6e2b98e12941566da2c6e1807"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/27.safetensors",
+ "bytes": 4456040,
+ "sha256": "51b073c5b5c60fa7154c94ac5e7e1c52fbdb9b1078c889d9a73654dbf6973141"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/28.json",
+ "bytes": 103,
+ "sha256": "0fd01ed5a6f838430fd4aa1a131ec57427c999a031acb3ecb40a1b100173f0a2"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/28.safetensors",
+ "bytes": 4456040,
+ "sha256": "6ea5a5e0449409acc444a0913d563118da5ead01020a89ad125b98f9bebacfdd"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/29.json",
+ "bytes": 103,
+ "sha256": "c13df43492f01fa37a048d1a7f93651dbffc5ed4aa7c7982fe002d22dfdea6e0"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/29.safetensors",
+ "bytes": 4456040,
+ "sha256": "a0c4032012c322636c3eb6b7450e54b9533aa2ed068f5508d39eb43ae85d5b9e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/30.json",
+ "bytes": 103,
+ "sha256": "0d63f1bca1a2ec1ce1e276a9016f3c7bd953b9fee41ee7d7aea6c8f924db2b52"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/30.safetensors",
+ "bytes": 4456040,
+ "sha256": "97ca1ccf7058ffa78e9c1e189dd15be748b642f3a27a719d646a2c24d2c7a441"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/31.json",
+ "bytes": 103,
+ "sha256": "19a92b4de6d7f29bf5fe75cc1848d46729df61c72ec959d78958d4ed55741e5e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/31.safetensors",
+ "bytes": 4456040,
+ "sha256": "3ed5af4d246b86a3476d5fc2c26f8d62a0d3b656e912842a5dfa062b4d9c8110"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/32.json",
+ "bytes": 103,
+ "sha256": "ef3e4309ab2218c75e7ce25e5c31275bc7c149517d7dd88e18b7e2cb136ea108"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/32.safetensors",
+ "bytes": 4456040,
+ "sha256": "a3ca9911208514fdffc270d697fd9b83fc9cc16acdbeac52cfe632eddbb399b5"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/33.json",
+ "bytes": 103,
+ "sha256": "cc38c662c44da10e78882b7e7aab6147cd84b08286004425be6deba9752752bc"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/33.safetensors",
+ "bytes": 4456040,
+ "sha256": "bb2206782ec88c8ec191f269ed39053c80199b4ca16397a036166b30998c6c00"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/34.json",
+ "bytes": 103,
+ "sha256": "07e21ca84b90eb7f3c193758e101b412cd6c7c5ca088754fa967f79948dfb583"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/34.safetensors",
+ "bytes": 4456040,
+ "sha256": "50b7ed03cdf37d7fcf504c5fa8cf04155d2c1d2e196f55b74eeec081cdf3a183"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/35.json",
+ "bytes": 103,
+ "sha256": "7bd4289495b52ad01de6512d3101dc8303b02f1398a079adc93ba3ada8b81198"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/35.safetensors",
+ "bytes": 4456040,
+ "sha256": "b9b4716db16d3c7e9cc858336c78035f9f768ffac8e65edbd1694769077f0940"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/36.json",
+ "bytes": 103,
+ "sha256": "a9b26ddf7e07b93186beebf2d2911ca42890eef6ce87d0fa8e64fbf42a835368"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/36.safetensors",
+ "bytes": 4456040,
+ "sha256": "4c273b5502e98cd1cc9450b95b6c5dc51ab3fe280458bc330fec629ea1a73119"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/37.json",
+ "bytes": 103,
+ "sha256": "d7577501165ec702c5a1c89336adfb38ae0e825d17cda6492d54d1f5f07b93ac"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/37.safetensors",
+ "bytes": 4456040,
+ "sha256": "f360e96b1e937c01890be5920e759ee1247b61c064bccd29788e17af8fbab8b5"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/38.json",
+ "bytes": 103,
+ "sha256": "1662ea2e2407ea033ffb6d89798de30915fdde34af816e757ef71257f5a9d232"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/38.safetensors",
+ "bytes": 4456040,
+ "sha256": "f0e9d4f1beb3630b929b21cd42bbc034d3ac511a6d043d211932fb3dc0ef11d7"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/39.json",
+ "bytes": 103,
+ "sha256": "c3b4f1cf9230fd68c39f88371b7b84e7bdd1dd3dcd06b7a9a43953271b2011e5"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/39.safetensors",
+ "bytes": 4456040,
+ "sha256": "594aa08ea6e0bef7e8a2796de5bac73c37995bdffc7606ad8dd4a291c77fbf2d"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/40.json",
+ "bytes": 103,
+ "sha256": "7f06906a48dd0be4f76b7db7c3366600aa771231b995dad056a05c0cc9d2ea5a"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/40.safetensors",
+ "bytes": 4456040,
+ "sha256": "cde25e4972edab376eb033fd5dbe5426fb0e6e53c428f4b1055e4a8ad6426b83"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/41.json",
+ "bytes": 103,
+ "sha256": "b66e7f7622a8835620bf38da55518215715f0ad5a153995668329dcdb941dfbb"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/41.safetensors",
+ "bytes": 4456040,
+ "sha256": "dca8e3a48637bc8325b0ea9443640c9e0274be695da6ab6da0a956b87f76e548"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/42.json",
+ "bytes": 103,
+ "sha256": "0bee835ba2ad2fd4955a22a3d133f11916c1dd4f718c20b4d4c428982e0926f5"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/42.safetensors",
+ "bytes": 4456040,
+ "sha256": "7ac8988dfbcab4ca00327f57d465d42b8d46731100d9a134e0f8df821692df6a"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/43.json",
+ "bytes": 103,
+ "sha256": "3d4390a37490e08e0745fc6bb471d1d2b8ebd513da99e7053356a9912334da79"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/43.safetensors",
+ "bytes": 4456040,
+ "sha256": "812e95c1bcbabc5de610263565ac6f2c2b58dfa0914f40185e23d220db8d7804"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/44.json",
+ "bytes": 103,
+ "sha256": "43830b47c2bfd74350574e9cecce467a2879acdadea63ed937462da8ab6fd4c8"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/44.safetensors",
+ "bytes": 4456040,
+ "sha256": "0f9e2d100da4f13603d0c039e06c4b6e7cb7a5bd60c96d686eb0f38af47d4702"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/45.json",
+ "bytes": 103,
+ "sha256": "204d32d3ceb7f2f520640673867ab62a4c51d2b9f076d328f1509b76c17f5ca2"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/45.safetensors",
+ "bytes": 4456040,
+ "sha256": "6d3135c8ed28bae050426ed074e86ad2a5a3352f43a2156dc4fd22992a5d7f8c"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/46.json",
+ "bytes": 103,
+ "sha256": "30dd134e38e4082c1f913d62636c52f0570f3810e2c0376f27c48d10efdbf65f"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/46.safetensors",
+ "bytes": 4456040,
+ "sha256": "fc2f7f62f2b1d170bb39fdf79d915286a6df287f387bc3608efa7c2d35240728"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/47.json",
+ "bytes": 103,
+ "sha256": "ffb19c1e9b3516309a79a1c2d46f1a22ad781895dd8ee3de995ba44f5ebd7223"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/47.safetensors",
+ "bytes": 4456040,
+ "sha256": "fc7a88951bf1957030413bb74a646f9b90b9b278486321eccc20b223d0216137"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/48.json",
+ "bytes": 103,
+ "sha256": "335b485652d0abcba0abf2af3366c4fc6523d6be3c56b2c6a16db135293f0441"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/48.safetensors",
+ "bytes": 4456040,
+ "sha256": "059fdd282e83c3ddff605d1b4ad3df1bac9711a02eed0c4a61dc1d86200fe0c2"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/49.json",
+ "bytes": 103,
+ "sha256": "a7a009e98a609361662c5499988c747aaf232a68fe9f1b0d65bf78ad2ba5dcb3"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/49.safetensors",
+ "bytes": 4456040,
+ "sha256": "ab8a45b126e168cc7ae3ba863a68419a9ca874ffedee961260a27722d162f616"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/identity.json",
+ "bytes": 931,
+ "sha256": "e25d680c1c6fe8942d8c063dee5304dadbb68023296cbd7ff7dae4daa115af66"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-222c457ff086c1fbf4b633e1/producer.json",
+ "bytes": 673,
+ "sha256": "6f5d42ef915bc1e5b58a7def1048c93381705344a89306a2ca14fb4619c3948c"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/00.json",
+ "bytes": 103,
+ "sha256": "f9e6e6b8eb252c9aa82f858604d7dc8a7b5550c4f86b46c067f1a9eae36f50b9"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/00.safetensors",
+ "bytes": 2907752,
+ "sha256": "504965de57302f0b18a5ea0b01d021635f26d47feac6e07d72ef7225657893e3"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/01.json",
+ "bytes": 103,
+ "sha256": "667288e0dbdf9a2e4dd8c2edbbd4b440c32f05f53a5dcf95f0781ff8f73c9e24"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/01.safetensors",
+ "bytes": 2907752,
+ "sha256": "3933338a466004538a5279fb32b1ee92c7694bb45a5d8e442ec9988a89ff50bf"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/02.json",
+ "bytes": 103,
+ "sha256": "ee2abbfab26a5ff44891b78d13280b920bb9903ef20ea74cd24eec01c37669c8"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/02.safetensors",
+ "bytes": 2907752,
+ "sha256": "76e929aa66455d87b31db7352892b0bdd3b7b0827d7359796b67915ab168cbac"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/03.json",
+ "bytes": 103,
+ "sha256": "d874fb4f15f188faade2edbaa89051eec7ae524ce33de96c30c13f133cf1da55"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/03.safetensors",
+ "bytes": 2907752,
+ "sha256": "e46b70ffbd459f848e056e1f0cfa9bdc6787f1096628baefa04bbcb5a2c7e496"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/04.json",
+ "bytes": 103,
+ "sha256": "1b21fee106806e5391c35dbe38e1ef7cae164afc6afd1aadf7156a939b509463"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/04.safetensors",
+ "bytes": 2907752,
+ "sha256": "cca36815e9a66e63b9ef0cbdcf3ad27b0013d858cd8077b7aee8fdff349074cb"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/05.json",
+ "bytes": 103,
+ "sha256": "143e16c046d56cac85ea87c6ad07f6ffad28b6225ef7b333c6cd7100857cb31f"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/05.safetensors",
+ "bytes": 2907752,
+ "sha256": "91a93b8ebd7efb2b313cccdaadca4334c851cf91fde9ef15be7a2c2bd30fcaab"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/06.json",
+ "bytes": 103,
+ "sha256": "403be70cb9593e105e36901bac8ace3b30a4ad20802cf6edf822e0ff6e8a370e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/06.safetensors",
+ "bytes": 2907752,
+ "sha256": "c0cdf2f5afdc975ea53e5bb519ced8796e91c1fcdc0ea95142e5075134e727a2"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/07.json",
+ "bytes": 103,
+ "sha256": "6104c665d45e661dd85e0a5298ab1d99cdb487cb0bbb08dbaba42b0feefac69d"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/07.safetensors",
+ "bytes": 2907752,
+ "sha256": "056e7f109ab6affd7d970d3b41288cef1648c68b2d4626c208b554b7cbb9c5c1"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/08.json",
+ "bytes": 103,
+ "sha256": "23fd49a92fd34a9fa429f3fa5ca824c8034ffc4ebf214a5aa6bc27c73f2df7fc"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/08.safetensors",
+ "bytes": 2907752,
+ "sha256": "616d1c9354fd077aee1b650ccadbb8646eca871bd023b20c313a96b4af21d175"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/09.json",
+ "bytes": 103,
+ "sha256": "78e1088d5210dac80c7681bbf3bdbcae4d54314bf033002007bb78d64b132c87"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/09.safetensors",
+ "bytes": 2907752,
+ "sha256": "7ef4add104c271dd30c7330573ed239648190d47fcec80a0dc5a892a9912ac45"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/10.json",
+ "bytes": 103,
+ "sha256": "3b47a8cf90f7ee2d7098b065ee4418a7182dee88497e1f312dbde645fef49e5d"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/10.safetensors",
+ "bytes": 2907752,
+ "sha256": "3dd6c92a39d73f3c6e20c62ce472b0ef13a78d39495a1434e19464e9ce8c26bb"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/11.json",
+ "bytes": 103,
+ "sha256": "8d74197e07d83725fc1fc35ca35512a7695c25d4e110091d8873ab1ca7afc069"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/11.safetensors",
+ "bytes": 2907752,
+ "sha256": "6e9cb9bd31dcfff944232584a170fe69ee7976dee3b08ec8d96ecfca76d5dae3"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/12.json",
+ "bytes": 103,
+ "sha256": "912a5e1701d8c6a47f94ab661cb789896f6bd58f11b9ade74aef6a6243496c93"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/12.safetensors",
+ "bytes": 2907752,
+ "sha256": "3259bb9332233444035ad0d7d638ec1b545970e61c75423ad03f80f8e0144930"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/13.json",
+ "bytes": 103,
+ "sha256": "3757baf3ce4b46d5446f703d364001f71faf3f4bb6a2695c44e54b8713722540"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/13.safetensors",
+ "bytes": 2907752,
+ "sha256": "3a37bf16fea5f480c76aef7d40a9fa81060315277e5fd4f4665f2b0a6873f665"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/14.json",
+ "bytes": 103,
+ "sha256": "8db7dc32ab897398f56ac03512ab34f5c5c0135f488c9560a684c8294bd085bb"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/14.safetensors",
+ "bytes": 2907752,
+ "sha256": "2c73459bb7162d80fbf26c8dd9b8ec86e70f738ab16b9af3c32271ae4906b4c6"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/15.json",
+ "bytes": 103,
+ "sha256": "aa61f9f24888d56ccb0bc2881bd153ff94711c385f7ef837e899ffcff66f2b65"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/15.safetensors",
+ "bytes": 2907752,
+ "sha256": "2ccd0199c9a4fbae4e2de5310458eeb82499d4af08bbed855e1b49c15976376c"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/16.json",
+ "bytes": 103,
+ "sha256": "d7561665bc1d3ed3e09b2da3afd4c2b4f041203d9f6563e26a90ff3d6af38c11"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/16.safetensors",
+ "bytes": 2907752,
+ "sha256": "2fc98d5537b68b075f03b08ad0672c761a8704fa9d6396274223ec8af5678c37"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/17.json",
+ "bytes": 103,
+ "sha256": "07184db3712a2bc45cc73c136cf6b3afb60aaa004f5f818e6eeb8822dc71d4ae"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/17.safetensors",
+ "bytes": 2907752,
+ "sha256": "1192769428faf5d9825387c74beba5382bdde6beb8954801eecc0edec64f999d"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/18.json",
+ "bytes": 103,
+ "sha256": "e199d6d72ce9daff49fe318bf7610301de7aa9d59d2a56db6feb514989e4de9a"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/18.safetensors",
+ "bytes": 2907752,
+ "sha256": "456f5adeb6dd619eed554fe5a875cd1cdcbeaad326284a403eede95ae51c477a"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/19.json",
+ "bytes": 103,
+ "sha256": "4638884349dc0fe19444c4e351ccc13ce841f1c02a98f86d17fb55f1bd6fd295"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/19.safetensors",
+ "bytes": 2907752,
+ "sha256": "9dedbc8647b730c39625ed3d5fa2a77748415fbeb1870cd91428522ed3bd6f53"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/20.json",
+ "bytes": 103,
+ "sha256": "4fa40d8a400ff82f8246b29fce691237a6150181c28d87d1932c3a39d3a22bcc"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/20.safetensors",
+ "bytes": 2907752,
+ "sha256": "298dd809a0f26089cf8d6ea1a6f140e343fa9d923c55a89842efe97f51d717b5"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/21.json",
+ "bytes": 103,
+ "sha256": "d41c0a23a803aff40774435d078ecae0b9fac1938dc6a76db2cd2cb8306b6efe"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/21.safetensors",
+ "bytes": 2907752,
+ "sha256": "17d9e0e93144063e28d77b4ec937c088a2657918e55dd8c2c5f382475d1a3d7e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/22.json",
+ "bytes": 103,
+ "sha256": "21d6ac56d4f9e4481c6ff48d5f668c9928ff8b99848ad9d63d6a9c3a56059033"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/22.safetensors",
+ "bytes": 2907752,
+ "sha256": "89d6a15a3e9fca27681133ce2cf7d4f831aa0c53ace7923a8fcf2e0cf1d1809f"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/23.json",
+ "bytes": 103,
+ "sha256": "cbdaeb28f128d2f42919eab76a8f846b1917bc00edc0500c56815d51b3cb2665"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/23.safetensors",
+ "bytes": 2907752,
+ "sha256": "c1e77d41f521abbe35c124b46fb0636a3ef8c7ad4197bbfb95feaa00020ca6d3"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/24.json",
+ "bytes": 103,
+ "sha256": "810e04bca0e409c93ac24564c48ede12086c2eb5bfda8074aad8615e180edc86"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/24.safetensors",
+ "bytes": 2907752,
+ "sha256": "7c591cbafc2d41483bb6f9decd773ed274c5b4032a89888d600bcf1a46829a3b"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/25.json",
+ "bytes": 103,
+ "sha256": "0c0f112fc2b35f10ad0706d180be4f61e8136e19f07064d7472c9fedddfa31b0"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/25.safetensors",
+ "bytes": 2907752,
+ "sha256": "3e03ae0f82c3b2b7e4fe146bfbaa6605bc636823fcc5e282ffcb9abf7216deec"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/26.json",
+ "bytes": 103,
+ "sha256": "4c1061b6bffd9173aec8d113e5538a359dc4d5917d028997a41b50d93bffee23"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/26.safetensors",
+ "bytes": 2907752,
+ "sha256": "7ab35cc41e65d0431db53a06f4884c97eeb3f688ed841105b8dba4d58106f287"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/27.json",
+ "bytes": 103,
+ "sha256": "a30980f0c1671db04a68014a210b68dfc5b97bd71b7e4d570c74528a727bd4e1"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/27.safetensors",
+ "bytes": 2907752,
+ "sha256": "990084df00fc135b5456873456b7d6c2b31a389bec157cddfbfaff0dd5624e57"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/28.json",
+ "bytes": 103,
+ "sha256": "237bf4dacb03d5a36f7cb7c4e56ce90c35ff52e68285425bb1023089f63f4348"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/28.safetensors",
+ "bytes": 2907752,
+ "sha256": "3e7bf8dcdf9b98af8dee62e742ec02071e79c6fa6abe717767155fecf40dcae0"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/29.json",
+ "bytes": 103,
+ "sha256": "d65b87005794c9fee3f880a5b70126d9452df1165f72f2d2ad366e6a372a67fa"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/29.safetensors",
+ "bytes": 2907752,
+ "sha256": "348a7edf18bb195f0972abde268560f6b6d90acd0872dc1808650a2c5ed82b5b"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/30.json",
+ "bytes": 103,
+ "sha256": "52048b02c2bac938404e5a8e8ff2f65719269592bdf681d0753747e41c6f5326"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/30.safetensors",
+ "bytes": 2907752,
+ "sha256": "f7dc17603c0b257e480479fcb45b35dc261099cbf9f1c08e5c72f83b82f1328c"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/31.json",
+ "bytes": 103,
+ "sha256": "c6ad32ea9a7c5b56456436563f007b84e481270a704ac7439be25de4676f4837"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/31.safetensors",
+ "bytes": 2907752,
+ "sha256": "9af528ffbd8e1ea01a7f183cce0a30c561add5bca4d095e1826a1ffff935cf51"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/32.json",
+ "bytes": 103,
+ "sha256": "b45013ed66d521ab7a4b8e7a8a86bb47f571d19c3ed5c85adf1116189cfb8260"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/32.safetensors",
+ "bytes": 2907752,
+ "sha256": "2b49977f572aa9b4efcd2f6da30d8125ddfc2f84604a821283791790856bfebd"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/33.json",
+ "bytes": 103,
+ "sha256": "990ef6d77bbc989b9bd14d37ba1f644eaf36fff8dd65461f9f72fa84d8b0fa9c"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/33.safetensors",
+ "bytes": 2907752,
+ "sha256": "0d842ee71fd2ae4d911a09aacdf5984fe6ac8665ebc4f0b77b867abf39e9ec08"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/34.json",
+ "bytes": 103,
+ "sha256": "29b152efa3120d46cf7c26eaf201b246028488023c85efb3baf968576708f3dd"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/34.safetensors",
+ "bytes": 2907752,
+ "sha256": "763c6e88f93285283f4f7d7aa60ac9c5863d3436080404384599f4a5eb051e8b"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/35.json",
+ "bytes": 103,
+ "sha256": "e0054f4705847c3b611101d855e0039be9fcbf31b5db8160a2ee1f24d0a63799"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/35.safetensors",
+ "bytes": 2907752,
+ "sha256": "a3addbac96f3444e752ce21e8279deff0806633ae08e4a7c676b40c876bc366a"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/36.json",
+ "bytes": 103,
+ "sha256": "a47f7adfdf1fd286a64098263fa5dee759fde7ae6c49efe3267a53a4f4d4efae"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/36.safetensors",
+ "bytes": 2907752,
+ "sha256": "006c53def3a3af3b6cfdc5e4c3a98d122a5af2b8f88601ab9de804a38c559b84"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/37.json",
+ "bytes": 103,
+ "sha256": "f9272e762e683689bac14b2f9ad9b8cb72453ebad82312cc336358100cb623d8"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/37.safetensors",
+ "bytes": 2907752,
+ "sha256": "5a5a07ca72d25c3304df588aeb24e5ed81ca9ff029e398f3965e14e53ff5dc4f"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/38.json",
+ "bytes": 103,
+ "sha256": "a83d91338fb3003d1fd2135d18c3db27336d698c4e6d3d48ca7dae46cdff69b8"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/38.safetensors",
+ "bytes": 2907752,
+ "sha256": "52d97b816432d3036f44f551532ca3e1703c3d00a57a23b42e1bcb3f3992790d"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/39.json",
+ "bytes": 103,
+ "sha256": "d7d4cc02a77e8ed4d22c9ad13d62f8c3fc65fb27bec04de1bbfaa7fcaf487754"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/39.safetensors",
+ "bytes": 2907752,
+ "sha256": "fce501da767380acdcdc207a57e4fd320424b89593ae4f2a6dabfa21aa3de778"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/40.json",
+ "bytes": 103,
+ "sha256": "31c0ad0dde0029f66701774c819e5f3194e2ad8d30901d1936c92f79fafa54bf"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/40.safetensors",
+ "bytes": 2907752,
+ "sha256": "99943d87d442079dcd0188c125ee625923d126ed2170a798ca79224dd13fc6bc"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/41.json",
+ "bytes": 103,
+ "sha256": "0a5fcac7bd22c378fef0e3241d02be62e5c0fff38af41700bcf4ed2cb858c781"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/41.safetensors",
+ "bytes": 2907752,
+ "sha256": "f9cd78e7d7eb32236cc9d23136298e7957aedb7b86d54725f953fb4998a7b696"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/42.json",
+ "bytes": 103,
+ "sha256": "1b8afea6c9d080d637e7d6051612774803e602ebce550bb37c9b785e464ef3e6"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/42.safetensors",
+ "bytes": 2907752,
+ "sha256": "4e40a578184f9f5eb20698ed5e21dcf9245cf8e5bf519bd1457059facb59f780"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/43.json",
+ "bytes": 103,
+ "sha256": "69c73f5564ae252170f99aec65d4cc1bf1720f1745492f09717e1f383fe5fe22"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/43.safetensors",
+ "bytes": 2907752,
+ "sha256": "fc6928999a88ca8e7e952bd3156971ff83515332b77beb6a32219c14e218d455"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/44.json",
+ "bytes": 103,
+ "sha256": "7501a07a200d4203f29c283609ddc9d3ba3f2bf27026c2b2dffaa7632a25a666"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/44.safetensors",
+ "bytes": 2907752,
+ "sha256": "f530a54d19af7d107d51753a6b7a5a421ddc5886a37adfaae18ea50c189d0675"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/45.json",
+ "bytes": 103,
+ "sha256": "839e60a4534ef68e27f3ac0877dfebb006f69ca5056e784d900c7a85dee645fb"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/45.safetensors",
+ "bytes": 2907752,
+ "sha256": "c7684401bf33f5ae9014126848148c1864c7003a191c93f1ca4ed5d4cb13b429"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/46.json",
+ "bytes": 103,
+ "sha256": "230f820c14d1846b0b395aa869c51e2221091d7e9655077f3a5254af47d5bcb0"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/46.safetensors",
+ "bytes": 2907752,
+ "sha256": "b71a67fd54a45ee9d74c808940cb99aa8b9f4a0253220e03e0ff2bd0095df33f"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/47.json",
+ "bytes": 103,
+ "sha256": "fc5b77e56e0fdb1eb82859cbee5c03d1038466e2827959cff535410ad6f7ebd2"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/47.safetensors",
+ "bytes": 2907752,
+ "sha256": "c242a36f612c5bc688eb77b3cdcaf44e6cf0f739234e1358c4a7c1747b85e2d3"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/48.json",
+ "bytes": 103,
+ "sha256": "70fc8a96a8958d7e7c1ad855d8bb577c62c342db18321e886a1b209f0ef3904e"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/48.safetensors",
+ "bytes": 2907752,
+ "sha256": "59ca5ce7c1b6814df2c2cdf68117b670231c07c6ff9a4ff5dfd5d235acdade24"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/49.json",
+ "bytes": 103,
+ "sha256": "76b3524064769d7635c6587e960fd4f6d3bc5c5ef672ed8c8ad5cafe61c31c0f"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/49.safetensors",
+ "bytes": 2907752,
+ "sha256": "842557f5218c789c35c186a42ba718e82dc2bad0c36edc1b4c8e4fc4a3ea75a8"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/identity.json",
+ "bytes": 723,
+ "sha256": "6ee4ab1773216749667fcabd2c1f2e25e52b71b21a060a22d133f52858395160"
+ },
+ {
+ "file": "int8-convrot/cache/adaln-tables-v2-bb59bb4aa370f50c71ca925e/producer.json",
+ "bytes": 642,
+ "sha256": "4dbd4576fe79b8cabe681d8ddb2706f4d07be12e3f5ca6670ee74beeed20af85"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/00.safetensors",
+ "bytes": 432694768,
+ "sha256": "595503065a6c696f91a837c6c5719103ab434a881f09e860a698daf533e94869"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/01.safetensors",
+ "bytes": 432694768,
+ "sha256": "a7bde59096115a80be8da37ba57b0dccec9a439e65ce2d39dd8ec35fc65ac877"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/02.safetensors",
+ "bytes": 432694768,
+ "sha256": "efbb593f8065a7f17cc5811334cbcd7091dd36384725bb9ef4ae19f61ccc67c3"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/03.safetensors",
+ "bytes": 432694768,
+ "sha256": "5a6b7575e3fd81578aa14641116c9e13bae25abc204804e29eec3ba966aae990"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/04.safetensors",
+ "bytes": 432694768,
+ "sha256": "8c0a35f7c42a1131acc8d09b79bbca6e1d375bf4b8b8a1bf6fe56751291d50ce"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/05.safetensors",
+ "bytes": 432694768,
+ "sha256": "64880289097ad61faabb1c3934f5b7f6652dce8ebb89da8bfb3a2133ccbca7ec"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/06.safetensors",
+ "bytes": 432694768,
+ "sha256": "b850acc81cf27f89af167bdaa3bfd17a314bdc260b8f9d02c3b019ca89c5c6fa"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/07.safetensors",
+ "bytes": 432694768,
+ "sha256": "34432ff1dd069f18c23ca0e59e0ca278069546415c309d02fea29ed7117a62d5"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/08.safetensors",
+ "bytes": 432694768,
+ "sha256": "8bc9e88a194f043f93d74a4b5f34f1763a798f2ebfe71afe90b012666189b39f"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/09.safetensors",
+ "bytes": 432694768,
+ "sha256": "f4830349dc1f48cd5b1931ee0235449e616eb06ee6f7bdf2394b9092ea179433"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/10.safetensors",
+ "bytes": 432694800,
+ "sha256": "27b7905db5a374cbe86332cf1755fa7b9993383b5fc81896cebfb493e6e5ee5c"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/11.safetensors",
+ "bytes": 432694800,
+ "sha256": "39cd2a031e17ece290b651e51d16b88c3662e958afcfec86643fce45fb16b346"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/12.safetensors",
+ "bytes": 432694800,
+ "sha256": "eb154ad7ea056baa47e7bb5d60dd58ed2f0c1ec4f848defe1ab9ecd497d9a244"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/13.safetensors",
+ "bytes": 432694800,
+ "sha256": "51753836833611c4114529e6fec91fca6b93c53394fc00b86d0c2a0fc08ea193"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/14.safetensors",
+ "bytes": 432694800,
+ "sha256": "21724ba259bed64363f45293ea701054226474807db3d2e28fd30602914c85e5"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/15.safetensors",
+ "bytes": 432694800,
+ "sha256": "6da1e1747cd9de6dabc706ca4153e68aed76527a8186b98ebc2f8d41ae903cc5"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/16.safetensors",
+ "bytes": 432694800,
+ "sha256": "07ce6f2bbdc171b4262f0a1836af1993c9f2a89988a32c2a14cbf3c35721231d"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/17.safetensors",
+ "bytes": 432694800,
+ "sha256": "7bef2f07ac529c7d1aaed786f14a2a2e50696bc4a5cf61cf4779431950220074"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/18.safetensors",
+ "bytes": 432694800,
+ "sha256": "7ab703c052e18de94fbd2d5bbe6a26ab739217512139ee3e79baa1e2ac9056fb"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/19.safetensors",
+ "bytes": 432694800,
+ "sha256": "616ee7a8663e8f533c0e77b979d5a886fb2d06e19f3537e8816866ba6659b057"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/20.safetensors",
+ "bytes": 432694800,
+ "sha256": "c31a0d15b63b37f7248115ee131e7bad56f18a9ae8d19e39536675c4c7a8ca61"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/21.safetensors",
+ "bytes": 432694800,
+ "sha256": "6ad68637b0d7fa2146b4bbe44256c92535dd636448b27e663db89d12b9b3739a"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/22.safetensors",
+ "bytes": 432694800,
+ "sha256": "7dffc74cab487d0b7dcd1daf4bbdecd0e7da6670e48e8c964a64c325293cb2cd"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/23.safetensors",
+ "bytes": 432694800,
+ "sha256": "33f34cfddf6cd7cade6204216ad5797b5a1a674f1d0db16c7d921a8fe076b317"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/24.safetensors",
+ "bytes": 432694800,
+ "sha256": "8f33dfecf948cca695f739f86246cf5b526b5e3add8f714f9f06c9df563a3cb2"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/25.safetensors",
+ "bytes": 432694800,
+ "sha256": "e86ea198abbae3ccd1335d05011653461fc6bbb86ff08bc87b0f37f766f31587"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/26.safetensors",
+ "bytes": 432694800,
+ "sha256": "bcae571d0c5f5a7d75cca16a33a0fc290b244af071d9386d6e9ff036f992fe4c"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/27.safetensors",
+ "bytes": 432694800,
+ "sha256": "d9559fa2365bed8c5ae7a1c0212f1aa0a76f5aa634f1be93508b2c6f77ee6892"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/28.safetensors",
+ "bytes": 432694800,
+ "sha256": "8deee4f22d29eb4d8d34efb3c9b7e49a51b6dc58c7836e6808bfb27b3fe18689"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/29.safetensors",
+ "bytes": 432694800,
+ "sha256": "2ba2be400cc4278608cf0dd708c5567ebf5b507732eacd5c09450ced39e21987"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/30.safetensors",
+ "bytes": 432694800,
+ "sha256": "f269b15745528949f3c8e1c642208a2a14771ce9c5ade2fc84533c8d50cfdfcf"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/31.safetensors",
+ "bytes": 432694800,
+ "sha256": "2852cf29642167da04a65534cc7a03c341981758e7f58765869f7b15a0086fe6"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/32.safetensors",
+ "bytes": 432694800,
+ "sha256": "b9f315393cffb0aadc2493b2e231e9f59ea94825fcff75a480214b5d9d88425b"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/33.safetensors",
+ "bytes": 432694800,
+ "sha256": "fbb767a3944a9a9804bf155dbdacf5c774caea06461255fd58657c997fd2973d"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/34.safetensors",
+ "bytes": 432694800,
+ "sha256": "35aae3b946feb9a4773b4856691db8558852a62283005d57e576c1c46cb406d7"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/35.safetensors",
+ "bytes": 432694800,
+ "sha256": "aba4ce32220517c650d977f5739c951eda8cff1959ed4783be9d3d27ac63a160"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/36.safetensors",
+ "bytes": 432694800,
+ "sha256": "817321a6a3694838a85b2c8a98272b2275ace0f7995d63593bcd9d87de17389f"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/37.safetensors",
+ "bytes": 432694800,
+ "sha256": "0ffa9d1a4b0460c86142ea2f57b7d822e51bd8980ff5c65ecb493d0b46c698b6"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/38.safetensors",
+ "bytes": 432694800,
+ "sha256": "7cdf590c4408260e7ceebc843a52e5fb74eb6e13f8a339360f78133702608897"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/39.safetensors",
+ "bytes": 432694800,
+ "sha256": "42b24c64167c48852295258d8d00b938a62867fb458958cb7b31384b06e7343c"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/40.safetensors",
+ "bytes": 432694800,
+ "sha256": "21fec61dfcc0edfb43fc0f260e040d781abd4f6272d35a2796bda5fb1d152138"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/41.safetensors",
+ "bytes": 432694800,
+ "sha256": "eaa46ffba74e8cd19c3ef5e104710621bfccb2fe57e52a917e412890e005667e"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/42.safetensors",
+ "bytes": 432694800,
+ "sha256": "5bf03e574ead58b12e1057b82275ab42f227efe055ca342f27e89ecd7651f5be"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/43.safetensors",
+ "bytes": 432694800,
+ "sha256": "ea4b65cffcda4076fe3b5cee6229269e7e7e178cf3c4d62660e408326dfab10e"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/44.safetensors",
+ "bytes": 432694800,
+ "sha256": "3633f97b8070696be6c60864eb56ebc5f3fd8eff5d32435f6202462193f8734a"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/45.safetensors",
+ "bytes": 432694800,
+ "sha256": "9c29db43ae3576acb5b5a70fd418c56a814a72461d6322a81508de07b99a5bfc"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/46.safetensors",
+ "bytes": 432694800,
+ "sha256": "b0c8b3e4c8f7dd2c4204812a5fc1c6cf880124ac1c647cb134f29208b211eeeb"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/47.safetensors",
+ "bytes": 432694800,
+ "sha256": "e0ac277801e8c8f3e2cd8ee3949ca9275e225a9669b809e42e9afc9f317cc873"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/48.safetensors",
+ "bytes": 432694800,
+ "sha256": "19143fe0df8b6acaa5ef5fce321570a327350e6469b4fb16fcd80daa67324f3a"
+ },
+ {
+ "file": "int8-convrot/cache/blocks/49.safetensors",
+ "bytes": 432694800,
+ "sha256": "1d7a710bc0552a2f655244970ba525de67cf02c36f66fe2b9e718eee1ceb42f0"
+ },
+ {
+ "file": "int8-convrot/cache/manifest.json",
+ "bytes": 258122,
+ "sha256": "58a5d48cb4b3769e69cf6b8f5f990d6801edd4f217e798635acf4840e8171fdf"
+ },
+ {
+ "file": "int8-convrot/cache/publication.json",
+ "bytes": 47203,
+ "sha256": "50a5ea911d8dddd376ef5f744a3187fa5f94a24a3529d562f376c28247f3339b"
+ },
+ {
+ "file": "int8-convrot/cache/root.safetensors",
+ "bytes": 925532864,
+ "sha256": "ea53e89f578e73295c1a288f87848796cbc4aa6d56188d70695ba21e2e9d8aad"
+ }
+ ]
}
}
}
diff --git a/freevideo_engine/processes.py b/freevideo_engine/processes.py
index 934bf1e..8c0f87e 100644
--- a/freevideo_engine/processes.py
+++ b/freevideo_engine/processes.py
@@ -1,4 +1,4 @@
-"""Worker creation, inherited leases and bounded cleanup on Linux and Windows."""
+"""Worker creation, inherited leases and platform-specific bounded cleanup."""
import os
from pathlib import Path
import signal
@@ -127,6 +127,15 @@ class WindowsPopen(subprocess.Popen):
def popen(command, *, pass_fds=(), supervise=False, **kwargs):
if windows():
return WindowsPopen(command, pass_fds=pass_fds, **kwargs)
+ if sys.platform == 'darwin':
+ import shutil
+ from .macos_process_host import command as watched
+ executable = str(command[0])
+ if os.sep in executable and not os.path.isabs(executable):
+ executable = str(Path(kwargs.get('cwd') or os.getcwd()) / executable)
+ if shutil.which(executable, path=(kwargs.get('env') or os.environ).get('PATH')) is None:
+ raise FileNotFoundError(2, 'Install executable not found', str(command[0]))
+ command = watched(command, pass_fds)
if supervise and sys.platform == 'linux':
import shutil
executable = str(command[0])
@@ -142,6 +151,9 @@ def popen(command, *, pass_fds=(), supervise=False, **kwargs):
def stop(process, grace=10):
if hasattr(process, 'stop_request'):
return process.stop_request(grace=grace)
+ if sys.platform == 'darwin':
+ from .macos_process_host import stop as stop_native
+ return stop_native(process, grace=grace)
if process.poll() is not None:
return
try:
diff --git a/freevideo_engine/provision.py b/freevideo_engine/provision.py
index 4077458..0ad7993 100644
--- a/freevideo_engine/provision.py
+++ b/freevideo_engine/provision.py
@@ -323,14 +323,14 @@ def verify_cache(plan, cache):
manifest = json.loads((cache / 'manifest.json').read_text(encoding='utf-8'))
config = json.loads((Path(plan['model_dir']) / 'h3-base/transformer/config.json').read_text(encoding='utf-8'))
count = config['num_layers']
- from .adaln_assets import SLIM_FORMAT, validate_catalog, check_table, asset_path
- slim = manifest.get('format') == SLIM_FORMAT
+ from .adaln_assets import SLIM_FORMATS, validate_catalog, check_table, asset_path
+ slim = manifest.get('format') in SLIM_FORMATS
kinds = ('blocks',) if slim else ('blocks', 'adaln')
expected = {'root'} | {kind + '/' + '%02d' % i for kind in kinds for i in range(count)}
groups = manifest.get('groups', [])
- if (manifest.get('precision') != 'fp8' or not manifest.get('linears')
+ if (manifest.get('precision') not in ('fp8', 'int8') or not manifest.get('linears')
or len(groups) != len(expected) or {r.get('group') for r in groups} != expected):
- raise ValueError('FP8 cache is not complete; original model files retained')
+ raise ValueError('Prepared cache is not complete; original model files retained')
ledger = Path(plan['root']) / 'verified-cache.json'
stamps = json.loads(ledger.read_text(encoding='utf-8')) if ledger.is_file() else {}
for row in groups:
@@ -351,22 +351,26 @@ def verify_cache(plan, cache):
def prepare(plan, out):
root = Path(plan['root'])
prepared = plan.get('prepared_model')
+ cache_format = dict(capability=plan.get('inventory', {}).get('hardware', {}).get('capability'),
+ scale_granularity=plan.get('model_scale_granularity'))
if prepared:
from .prepared_model import verify_manifest
verify_manifest(prepared)
cache = Path(prepared['cache'])
from .install_tuning import cache_compatible
- if not cache_compatible(cache, plan['inventory']['hardware']['capability']):
+ if not cache_compatible(cache, **cache_format):
raise ValueError('Downloaded prepared model differs from this GPU scale format')
elif plan.get('reuse_cache'):
cache = Path(plan['reuse_cache'])
from .install_tuning import cache_compatible
manifest = json.loads((cache / 'manifest.json').read_text(encoding='utf-8'))
- if manifest.get('precision') != 'fp8':
- raise ValueError('Reuse cache must contain FP8 storage.')
- if not cache_compatible(cache, plan['inventory']['hardware']['capability']):
+ if manifest.get('precision') not in ('fp8', 'int8'):
+ raise ValueError('Reuse cache must contain FP8 or int8 storage.')
+ if not cache_compatible(cache, **cache_format):
raise ValueError('FP8 scale format differs from this GPU. Omit --cache to prepare the correct one.')
else:
+ if plan.get('device_backend') == 'mps':
+ raise ValueError('Mac setup requires verified prepared weights; select the prepared model source')
from .paths import add_vdn
add_vdn()
import torch
diff --git a/freevideo_engine/ram.py b/freevideo_engine/ram.py
index c7325c6..1df1d7f 100644
--- a/freevideo_engine/ram.py
+++ b/freevideo_engine/ram.py
@@ -1,5 +1,6 @@
"""Observed process memory and dedicated cgroup limits; no GPU dependencies."""
from pathlib import Path
+import sys
from .system import windows
@@ -27,6 +28,10 @@ class ProcessMemory:
"""
def __init__(self):
+ self.macos = None
+ if sys.platform == 'darwin':
+ from .macos_process_memory import ProcessMemory as MacMemory
+ self.macos = MacMemory()
self.windows = None
if windows():
from .win32 import ProcessMemory as WindowsMemory
@@ -48,6 +53,8 @@ class ProcessMemory:
if value.strip().endswith('kB')}
def sample(self, root_pid):
+ if self.macos is not None:
+ return self.macos.sample(root_pid)
if self.windows is not None:
return self.windows.sample(root_pid)
parents = {}
@@ -155,6 +162,8 @@ class ProcessMemory:
'system_writeback_bytes': system.get('Writeback'), 'cgroup_memory': self.last_cgroup}
def result(self):
+ if self.macos is not None:
+ return self.macos.result()
if self.windows is not None:
return self.windows.result()
return {'process_tree_peak_rss_bytes': self.peak_rss,
diff --git a/freevideo_engine/reference_sampler.py b/freevideo_engine/reference_sampler.py
index 187935f..9c4471b 100644
--- a/freevideo_engine/reference_sampler.py
+++ b/freevideo_engine/reference_sampler.py
@@ -54,6 +54,10 @@ def generate_latents(transformer, prompt_embeds, text_token_tags, num_frames, nu
patch, AUDIO_CHANNELS, AUDIO_TAG, VIDEO_TAG,
)
)
+ if torch.device(device).type == 'mps':
+ # RoPE consumes FP32 coordinates; MPS cannot stage the layout's FP64
+ # storage first. Keep the existing CUDA transfer and arithmetic.
+ position_ids = position_ids.float()
position_ids, token_tags = position_ids.to(device), token_tags.to(device)
video_indices, audio_indices, text_indices = (
video_indices.to(device), audio_indices.to(device), text_indices.to(device),
@@ -99,9 +103,15 @@ def generate_latents(transformer, prompt_embeds, text_token_tags, num_frames, nu
if audio_rows.shape[0] != audio_indices.numel():
raise ValueError('Reference audio rows disagree with packed layout')
+ def synchronize():
+ if torch.device(device).type == 'cuda':
+ torch.cuda.synchronize(device)
+ elif torch.device(device).type == 'mps':
+ torch.mps.synchronize()
+
if runtime is not None:
runtime.barrier()
- torch.cuda.synchronize(device)
+ synchronize()
seq_len = position_ids.shape[0]
for t, audio_t in zip(scheduler.timesteps, audio_scheduler.timesteps):
@@ -134,11 +144,11 @@ def generate_latents(transformer, prompt_embeds, text_token_tags, num_frames, nu
audio_rows[num_audio_condition_rows:], return_dict=False)[0]
if step_seconds is not None:
- torch.cuda.synchronize(device)
+ synchronize()
step_seconds.append(time.perf_counter() - step_started)
if runtime is not None:
- torch.cuda.synchronize(device)
+ synchronize()
runtime.barrier()
# Unpatchify (the AfterDenoise step's reshape) and unpack the channel-major audio rows.
diff --git a/freevideo_engine/refine.py b/freevideo_engine/refine.py
index db76547..304da47 100644
--- a/freevideo_engine/refine.py
+++ b/freevideo_engine/refine.py
@@ -67,6 +67,10 @@ def generate_latents(transformer, prompt_embeds, text_token_tags, num_frames, nu
text_token_tags, latent_frames, LATENT_H, LATENT_W, audio_frames,
patch, AUDIO_CHANNELS, AUDIO_TAG, VIDEO_TAG, keyframe_anchors=anchors)
positions, tags, video_ids, audio_ids, text_ids, condition_rows, audio_condition_rows = layout
+ if torch.device(device).type == 'mps':
+ # RoPE evaluates coordinates in FP32. MPS cannot first stage the
+ # layout builder's FP64 storage on-device as CUDA does.
+ positions = positions.float()
positions, tags, video_ids, audio_ids, text_ids = (
value.to(device) for value in (positions, tags, video_ids, audio_ids, text_ids))
frame_h, frame_w = LATENT_H // patch[1], LATENT_W // patch[2]
@@ -121,6 +125,8 @@ def generate_latents(transformer, prompt_embeds, text_token_tags, num_frames, nu
if step_seconds is not None:
if str(device).startswith('cuda'):
torch.cuda.synchronize(device)
+ elif torch.device(device).type == 'mps':
+ torch.mps.synchronize()
step_seconds.append(time.perf_counter() - tick)
rows = video_rows[condition_rows:].reshape(-1, latent_frames, frame_h, frame_w, channels, *patch)
rows = rows.permute(0, 4, 1, 5, 2, 6, 3, 7)
diff --git a/freevideo_engine/release_notes.json b/freevideo_engine/release_notes.json
new file mode 100644
index 0000000..debfe4f
--- /dev/null
+++ b/freevideo_engine/release_notes.json
@@ -0,0 +1,22 @@
+{
+ "schema": 1,
+ "product_version": "0.1.0",
+ "en": {
+ "summary": "FreeVideo now runs on Apple silicon Macs, and every update tells you what changed.",
+ "changes": [
+ "Mac preview: FreeVideo runs on Apple silicon Macs with macOS 14 or later.",
+ "A short product version is now shown in the launcher and creative workspace. The build number remains available in version details.",
+ "Update reminders include release notes in your selected language: English or Simplified Chinese.",
+ "Open Version & release notes at any time, including after updating or while offline, to read the notes included with your installed version."
+ ]
+ },
+ "zh": {
+ "summary": "FreeVideo 推出 Apple 芯片 Mac 预览版,每次更新都会说明改了什么。",
+ "changes": [
+ "Mac 预览版:支持 macOS 14 及以上的 Apple 芯片 Mac。",
+ "启动器和创作面板显示简短产品版本,构建号可在版本详情中查看。",
+ "更新提醒附带更新说明,跟随界面语言显示中文或英文。",
+ "随时打开「版本与更新说明」,更新后或离线时也能查看当前版本自带的说明。"
+ ]
+ }
+}
diff --git a/freevideo_engine/release_notes.py b/freevideo_engine/release_notes.py
new file mode 100644
index 0000000..625e168
--- /dev/null
+++ b/freevideo_engine/release_notes.py
@@ -0,0 +1,121 @@
+"""Small, offline release descriptions shared by the launcher and workspace.
+
+The product version is editorial; the existing build timestamp/revision still
+decides whether an update is newer. Notes never authorize an update.
+"""
+import argparse
+import json
+from pathlib import Path
+import re
+
+PRODUCT_VERSION = re.compile(r'(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)')
+MAX_NOTES_BYTES = 24000
+
+
+def product_version(value):
+ return value if isinstance(value, str) and len(value) <= 32 and PRODUCT_VERSION.fullmatch(value) else None
+
+
+def _text(value, limit):
+ return (isinstance(value, str) and 0 < len(value.strip()) <= limit
+ and not any(ord(c) < 32 for c in value))
+
+
+def notes(value):
+ """Ignore malformed optional metadata so legacy/update checks still work."""
+ if not isinstance(value, dict) or value.get('schema') != 1:
+ return None
+ result = dict(schema=1)
+ for language in ('en', 'zh'):
+ row = value.get(language)
+ if not isinstance(row, dict) or not _text(row.get('summary'), 400):
+ return None
+ changes = row.get('changes')
+ if (not isinstance(changes, list) or not 1 <= len(changes) <= 12
+ or not all(_text(item, 600) for item in changes)):
+ return None
+ result[language] = dict(summary=row['summary'].strip(), changes=[item.strip() for item in changes])
+ return result if len(json.dumps(result).encode('utf-8')) <= MAX_NOTES_BYTES else None
+
+
+def optional_fields(value):
+ result = {}
+ if not isinstance(value, dict):
+ return result
+ version, release = product_version(value.get('product_version')), notes(value.get('release_notes'))
+ if version:
+ result['product_version'] = version
+ if release:
+ result['release_notes'] = release
+ return result
+
+
+def catalog(package=None):
+ """Builds must fail on incomplete translations, before uploading anything."""
+ package = Path(package) if package is not None else Path(__file__).parent
+ value = json.loads((package / 'release_notes.json').read_text(encoding='utf-8'))
+ version, release = product_version(value.get('product_version')), notes(value)
+ if not version or not release:
+ raise ValueError('Release notes need a product version and complete English/Chinese text')
+ return dict(product_version=version, release_notes=release)
+
+
+def public_details(value):
+ """Allowlisted display fields, without download credentials or URLs."""
+ if not isinstance(value, dict):
+ return {}
+ result = {key: value[key] for key in ('version', 'revision', 'built_at') if key in value}
+ result.update(optional_fields(value))
+ return result
+
+
+def installed_details(package, fallback=None):
+ package = Path(package)
+ try:
+ from .launcher_update import build_identity
+ return public_details(build_identity(json.loads((package / 'build-identity.json').read_text(encoding='utf-8'))))
+ except (OSError, ValueError, TypeError):
+ # Do not attach today's notes to an old stamped build.
+ try:
+ return dict(version=(package / 'build-version.txt').read_text(encoding='utf-8').strip())
+ except OSError:
+ result = dict(version=fallback, development=True)
+ try:
+ result.update(catalog(package))
+ except (OSError, ValueError, TypeError):
+ pass
+ return result
+
+
+def markdown(value):
+ """Render both languages from the exact metadata shipped in this artifact."""
+ data = optional_fields(value)
+ release = data.get('release_notes')
+ if not release or not data.get('product_version'):
+ raise ValueError('Build has no bilingual release notes')
+ def escape(text):
+ return re.sub(r'([\\`*_{}\[\]()#+.!<>|~-])', r'\\\1', text)
+ title = 'FreeVideo v' + data['product_version']
+ rows = ['# ' + title, '', 'Build / 构建号: ' + escape(str(value['version'])), '']
+ for language, heading in (('en', "What's new"), ('zh', '更新内容')):
+ row = release[language]
+ rows.extend(['## ' + heading, '', escape(row['summary']), ''])
+ rows.extend('- ' + escape(item) for item in row['changes'])
+ rows.append('')
+ return '\n'.join(rows) + '\n'
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Render the release notes stamped into a build')
+ parser.add_argument('--build', type=Path, required=True)
+ parser.add_argument('--out', type=Path, required=True)
+ parser.add_argument('--prepend', action='store_true', help='Keep existing installation instructions after the notes')
+ args = parser.parse_args()
+ rendered = markdown(json.loads(args.build.read_text(encoding='utf-8')))
+ if args.prepend:
+ rendered += args.out.read_text(encoding='utf-8')
+ args.out.write_text(rendered, encoding='utf-8')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/freevideo_engine/resource_settings.py b/freevideo_engine/resource_settings.py
index fdfe7f6..4fc0e7c 100644
--- a/freevideo_engine/resource_settings.py
+++ b/freevideo_engine/resource_settings.py
@@ -6,25 +6,36 @@ from pathlib import Path
from .monitoring import save
-def validate(value):
+def setting(backend):
+ if backend == 'mps':
+ return 'ram_reserve_gib', 1., 'Reserved unified RAM'
+ if backend != 'cuda':
+ raise ValueError('Unknown resource backend')
+ return 'gpu_reserve_gib', .2, 'Reserved VRAM'
+
+
+def validate(value, *, backend='cuda'):
+ _, minimum, label = setting(backend)
if value is None:
return None # Leave the automatic policy in charge, including tight fits.
- if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value < .2:
- raise ValueError('Reserved VRAM must be automatic or a finite number of at least 0.2 GiB')
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value < minimum:
+ raise ValueError(label + ' must be automatic or a finite number of at least %g GiB' % minimum)
return float(value)
-def read(root):
+def read(root, *, backend='cuda'):
+ field, _, _ = setting(backend)
path = Path(root) / 'resource-settings.json'
if not path.exists():
- return {'gpu_reserve_gib': None}
+ return {field: None}
value = json.loads(path.read_text(encoding='utf-8'))
if not isinstance(value, dict):
raise ValueError('Invalid resource settings')
- return {'gpu_reserve_gib': validate(value.get('gpu_reserve_gib'))}
+ return {field: validate(value.get(field), backend=backend)}
-def write(root, value):
- result = {'gpu_reserve_gib': validate(value)}
+def write(root, value, *, backend='cuda'):
+ field, _, _ = setting(backend)
+ result = {field: validate(value, backend=backend)}
save(Path(root) / 'resource-settings.json', result)
return result
diff --git a/freevideo_engine/result_cache.py b/freevideo_engine/result_cache.py
index 74525f9..fe81d25 100644
--- a/freevideo_engine/result_cache.py
+++ b/freevideo_engine/result_cache.py
@@ -198,9 +198,19 @@ def request_key(prompt, seed, canvas, sampling_plan, extra, machine, resources,
if sampling_plan.get('upscaler_sha256'):
from .two_pass import UPSCALER
models['upscaler'] = file(Path(machine['model_root']) / 'latent_upscaler' / Path(UPSCALER['file']).name)
- from .compatibility import Store
- compatibility = phase('settings', lambda: Store(root).status({'gpu_uuid': machine['gpu_uuid'], 'system': platform.system()}))
- settings = dict(resources=resources, compatibility=compatibility['level'])
+ native = machine.get('device_backend') == 'mps'
+ if native:
+ identity = machine.get('device_identity')
+ if not isinstance(identity, dict) or identity.get('backend') != 'mps' or not identity.get('name'):
+ raise ValueError('Native device identity is unavailable')
+ # Mac placement has its own unified-memory policy. NVIDIA's
+ # compatibility levels do not apply; machine below retains the
+ # actual Apple device identity, without a fabricated GPU UUID.
+ settings = dict(resources=resources, macos=platform.mac_ver()[0])
+ else:
+ from .compatibility import Store
+ compatibility = phase('settings', lambda: Store(root).status({'gpu_uuid': machine['gpu_uuid'], 'system': platform.system()}))
+ settings = dict(resources=resources, compatibility=compatibility['level'])
tuning = root / 'tuning' / 'state.json'
if tuning.exists():
saved = json.loads(tuning.read_text(encoding='utf-8'))
@@ -237,8 +247,10 @@ def request_key(prompt, seed, canvas, sampling_plan, extra, machine, resources,
inspection.phases['inputs'] = time.monotonic() - input_started
inspection.check()
ignored = {'FREEVIDEO_RESIDENT_SESSION', 'FREEVIDEO_RUNTIME_LOCK_FD', 'FREEVIDEO_RUNTIME_LOCK_HANDLE'}
- compute_env = {k: v for k, v in environment.items() if k not in ignored
- and k.startswith(('FREEVIDEO_', 'CUDA_', 'NVIDIA_', 'PYTORCH_', 'TORCH_', 'TRITON_'))}
+ prefixes = ('FREEVIDEO_', 'CUDA_', 'NVIDIA_', 'PYTORCH_', 'TORCH_', 'TRITON_')
+ if native:
+ prefixes += ('MLX_', 'MTL_', 'METAL_')
+ compute_env = {k: v for k, v in environment.items() if k not in ignored and k.startswith(prefixes)}
return _key(dict(schema=2, prompt=prompt, seed=seed, canvas=canvas, sampling_plan=sampling_plan,
media=media, conditioning=conditioning, machine=machine, settings=settings,
models=models, code=code, packages=packages, environment=compute_env))
diff --git a/freevideo_engine/runtime.py b/freevideo_engine/runtime.py
index f1ec4b0..9858e36 100644
--- a/freevideo_engine/runtime.py
+++ b/freevideo_engine/runtime.py
@@ -12,7 +12,7 @@ import torch
from .adaln import CachedModulation, TableCache, ScheduleCursor, schedule_embeddings, schedule_timesteps
from .attention import WindowAttention
-from .offload import LayerOffloader, pin_layer_weights, unload_streamed_layer, prepare_streamed_layer
+from .backends import get_backend
from .weights import skeleton
from .paths import base_path, checkpoint_path
from .torch_compat import empty_host_cache
@@ -56,7 +56,10 @@ class Engine:
window_batch=1, linear_compute='native-fp8', input_cache_dir=None,
fp8_gemm='auto', window_varlen=False, varlen_smooth_k=True,
task='t2va', stream_weights=False, canvas=None, head_parallelism=1,
- residual_offload=False):
+ residual_offload=False, device_backend=None):
+ self.device_backend = device_backend if device_backend is not None else get_backend()
+ if self.device_backend.capabilities.name != 'cuda':
+ raise NotImplementedError('Engine model execution currently requires the CUDA backend')
from .media_request import TASKS
if task not in TASKS:
raise ValueError('Unsupported Engine task: ' + str(task))
@@ -120,8 +123,8 @@ class Engine:
raise ValueError('Online LoRA requires bounded attention; select the automatic generation profile')
ff_chunk = ff_chunk or 2048
lora_paths = [self.cache / spec['file'] for spec in online_lora.get('blocks', {}).values()]
- from .adaln_assets import SLIM_FORMAT, validate_catalog, restore_projections
- portable_adaln = manifest.get('format') == SLIM_FORMAT
+ from .adaln_assets import SLIM_FORMATS, validate_catalog, restore_projections
+ portable_adaln = manifest.get('format') in SLIM_FORMATS
if portable_adaln:
# In the slim format these constants are model parameters, not a
# disposable optimization cache. The effective mode is reported.
@@ -131,7 +134,7 @@ class Engine:
raise ValueError('Incomplete prepared weights')
self.attention = WindowAttention(attention, query_chunk, window_batch,
window_varlen=window_varlen,
- varlen_smooth_k=varlen_smooth_k)
+ varlen_smooth_k=varlen_smooth_k, device_backend=self.device_backend)
model = skeleton(self.base, Path(checkpoint))
validate_catalog(manifest, len(model.transformer_blocks))
# Locked buffers allocated after the weights must also fit the Windows
@@ -193,7 +196,7 @@ class Engine:
logical = 0
if incremental_pinning:
tick = time.perf_counter()
- logical, reserved = prepare_streamed_layer(block, streamed_source, index,
+ logical, reserved = self.device_backend.prepare_streamed_layer(block, streamed_source, index,
pin_budget_bytes=max(0, int(pin_host_gb * 1e9) - prepared_pins['reserved']),
headroom_bytes=self.weight_cache_headroom_bytes,
nonlocal_reserve_bytes=self.nonlocal_reserve_bytes)
@@ -201,28 +204,14 @@ class Engine:
prepared_pins['reserved'] += reserved
prepared_pins['seconds'] += time.perf_counter() - tick
else:
- unload_streamed_layer(block, streamed_source, index)
+ self.device_backend.unload_streamed_layer(block, streamed_source, index)
if not logical:
# Its bytes are still in the file cache; later pins would evict them.
prepared_pins['views'] += int(streamed_source.adopt(index))
precision = manifest.get('precision', 'bf16')
- actual_fp8_gemm = None
- if precision == 'fp8':
- from src.models.ops.fp8_linear import per_tensor_gemm
- from .fp8 import install_cached_linears
- expected = 'per_tensor' if per_tensor_gemm() else 'rowwise'
- if linear_compute == 'native-fp8' and torch.cuda.get_device_capability() < (8, 9):
- raise ValueError('Native FP8 GEMM requires Ada or newer; choose bf16-weight-only on Ampere')
- if linear_compute == 'native-fp8' and manifest['scale_granularity'] != expected:
- raise ValueError('FP8 cache scale granularity does not match this GPU; prepare a separate cache')
- install_cached_linears(model, manifest['linears'], weight_only=linear_compute == 'bf16-weight-only')
- if linear_compute == 'native-fp8':
- from .fp8_gemm import install
- actual_fp8_gemm = install(model, manifest['scale_granularity'], requested=fp8_gemm)
- elif precision != 'bf16':
- raise ValueError('Unknown prepared weight precision')
+ actual_fp8_gemm = self.device_backend.prepare_linears(model, manifest, linear_compute, fp8_gemm)
root_weights = _load_safetensors(self.cache / 'root.safetensors')
- root_weights = {name: value if offload_refiner and name.startswith('token_refiner.refiner_blocks.') else value.to('cuda')
+ root_weights = {name: value if offload_refiner and name.startswith('token_refiner.refiner_blocks.') else value.to(self.device_backend.device)
for name, value in root_weights.items()}
result = model.load_state_dict(root_weights, strict=False, assign=True)
if result.unexpected_keys or any(not key.startswith('transformer_blocks.') for key in result.missing_keys):
@@ -231,7 +220,7 @@ class Engine:
if online_lora:
from .lora_online import attach_block
attach_block(model, 'root', self.cache, manifest, _load_safetensors,
- device='cpu' if offload_refiner else 'cuda')
+ device='cpu' if offload_refiner else self.device_backend.device)
if streamed_source is not None and streamed_refiner_count:
# Refiner weights live in root.safetensors and otherwise remain a
# second large CPU allocation until LayerOffloader is constructed.
@@ -239,7 +228,7 @@ class Engine:
# blocks immediately after binding the root state.
for index, block in enumerate(model.token_refiner.refiner_blocks):
prepare_streamed(block, index)
- model.rope.to('cuda')
+ model.rope.to(self.device_backend.device)
self.cursor = None
self.schedule_hook = None
embeddings = None
@@ -259,7 +248,7 @@ class Engine:
table = table_cache.load(index, steps) if table_cache is not None else None
cache_hit = table is not None
if cache_hit:
- block.adaln_proj = CachedModulation(table, self.cursor).to('cuda', non_blocking=True)
+ block.adaln_proj = CachedModulation(table, self.cursor).to(self.device_backend.device, non_blocking=True)
table_cache_hits += 1
del table
else:
@@ -270,7 +259,7 @@ class Engine:
if adaln_cache and not cache_hit:
if embeddings is None:
_, embeddings = schedule_embeddings(model, steps, task=task)
- block.load_state_dict({name: value.to('cuda') for name, value in adaln.items()}, strict=False, assign=True)
+ block.load_state_dict({name: value.to(self.device_backend.device) for name, value in adaln.items()}, strict=False, assign=True)
table = [block.adaln_proj(embedding) for embedding in embeddings]
block.adaln_proj = CachedModulation(table, self.cursor)
if table_cache is not None:
@@ -303,7 +292,7 @@ class Engine:
from .offload import cpu_weights
self.resident_weight_bytes += sum(value.numel() * value.element_size() for _, value in cpu_weights(block))
upload_started = time.perf_counter()
- block.to('cuda', non_blocking=True)
+ block.to(self.device_backend.device, non_blocking=True)
upload_submit_seconds += time.perf_counter() - upload_started
elif streamed_source is not None:
# Keep only the bounded pinned subset or metadata. Immutable
@@ -340,8 +329,7 @@ class Engine:
if precision == 'fp8' and linear_compute == 'native-fp8':
if not inference_kernels:
raise ValueError('FP8 FF chunks require the official inference kernels')
- from .fp8_ops import install_chunked_ff
- install_chunked_ff(block.ff, ff_chunk, recompute=fp8_ff_recompute)
+ self.device_backend.install_chunked_ff(block.ff, ff_chunk, recompute=fp8_ff_recompute)
continue
original = block.ff.forward
block.ff._freevideo_unchunked_forward = original
@@ -387,11 +375,11 @@ class Engine:
from .streamed_weights import interleaved_layer_order
pin_layers = [self.offload_layers[index] for index in interleaved_layer_order(len(self.offload_layers))]
pin_order = 'interleaved'
- self.pinned_model_bytes = pin_layer_weights(pin_layers, max_bytes=int(pin_host_gb * 1e9) if pin_host_gb else None,
+ self.pinned_model_bytes = self.device_backend.pin_layer_weights(pin_layers, max_bytes=int(pin_host_gb * 1e9) if pin_host_gb else None,
headroom_bytes=host_headroom,
nonlocal_reserve_bytes=self.nonlocal_reserve_bytes)
pin_seconds = time.perf_counter() - pin_start
- self.pinned_host_allocated_bytes = torch.cuda.memory.host_memory_stats()['allocated_bytes.current']
+ self.pinned_host_allocated_bytes = self.device_backend.host_memory_stats()['allocated_bytes.current']
print(json.dumps({'event': 'host_weights_pinned', 'seconds': pin_seconds,
'logical_bytes': self.pinned_model_bytes,
'working_headroom_bytes': host_headroom,
@@ -410,8 +398,8 @@ class Engine:
del buffer
self.host_preload_seconds = time.perf_counter() - preload_start
print(json.dumps({'event': 'host_weights_read', 'seconds': self.host_preload_seconds}), flush=True)
- torch.cuda.synchronize()
- torch.cuda.empty_cache()
+ self.device_backend.synchronize()
+ self.device_backend.empty_cache()
self.load_seconds = time.perf_counter() - started
self.load_breakdown = {'adaln_prepare_seconds': adaln_prepare_seconds, 'pin_weights_seconds': pin_seconds,
'block_bind_seconds': block_bind_seconds,
@@ -428,7 +416,7 @@ class Engine:
'scope': 'Host wall time within model load; AdaLN includes table reads or computation and writes.'}
fa4_module = sys.modules.get('flash_attn.cute.flash_fwd')
fa4_path = Path(fa4_module.__file__).resolve() if fa4_module is not None else None
- self.config = {'task': task, 'attention': attention, 'prefetch': prefetch, 'adaln_cache': adaln_cache,
+ self.config = {'device_backend': self.device_backend.capabilities.name, 'task': task, 'attention': attention, 'prefetch': prefetch, 'adaln_cache': adaln_cache,
'adaln_mode': 'portable-model-asset' if table_cache is not None and table_cache.asset else 'local-precompute' if adaln_cache else 'original-projections',
'adaln_table_identity': table_cache.identity if table_cache is not None else None,
'adaln_table_producer': table_cache.producer if table_cache is not None else None,
@@ -514,9 +502,9 @@ class Engine:
if info['task'] != self.task:
raise ValueError('Reference modalities changed the precomputed schedule')
conditions = value['references']
- prompt, tags = value['prompt_embeds'].to('cuda', torch.bfloat16), value['text_token_tags']
+ prompt, tags = value['prompt_embeds'].to(self.device_backend.device, torch.bfloat16), value['text_token_tags']
else:
- prompt, tags, conditions = load_prompt(str(conditioning), 'cuda')
+ prompt, tags, conditions = load_prompt(str(conditioning), self.device_backend.device)
from .keyframes import validate_conditioning
source_canvas = self.canvas if allow_smaller_canvas and self.canvas is not None else canvas
validate_conditioning(prompt, tags, conditions, self.task,
@@ -562,7 +550,7 @@ class Engine:
def append(self, value):
super().append(value)
cached = offloader.cached_bytes() if budget_refresh is not None else 0
- peak = torch.cuda.max_memory_reserved()
+ peak = owner.device_backend.max_memory_reserved()
if budget_refresh is not None:
# Cache tensors are idle here; no forward hook or transfer
# owns them. Drop optional residency before lowering a cap.
@@ -579,7 +567,7 @@ class Engine:
from .two_pass import pass_cache_allowance
from .system import system_memory
cached = offloader.cached_bytes()
- free, _ = torch.cuda.mem_get_info()
+ free, _ = owner.device_backend.memory_info()
commit = system_memory().get('commit_available_bytes')
allowance = pass_cache_allowance(live_budget, base_peak, free + cached,
gpu_reserve_bytes, None if commit is None else commit + cached)
@@ -593,8 +581,8 @@ class Engine:
and owner.canvas is not None and canvas['video_tokens'] < owner.canvas['video_tokens']):
from .two_pass import pass_cache_allowance
from .system import system_memory
- free, _ = torch.cuda.mem_get_info()
- peak = torch.cuda.max_memory_reserved()
+ free, _ = owner.device_backend.memory_info()
+ peak = owner.device_backend.max_memory_reserved()
commit = system_memory().get('commit_available_bytes')
allowance = pass_cache_allowance(pass_cache_budget_bytes, peak, free, gpu_reserve_bytes, commit)
pass_cache.update(measured_peak_reserved_bytes=peak, live_free_bytes=free,
@@ -623,8 +611,8 @@ class Engine:
gemm_before = execution_counts()
parallel_before = {name: getattr(self.attention, name, 0)
for name in ('parallel_head_calls', 'parallel_head_warmups')}
- torch.cuda.reset_peak_memory_stats()
- torch.cuda.synchronize()
+ self.device_backend.reset_peak_memory_stats()
+ self.device_backend.synchronize()
started = time.perf_counter()
refinement = None
if self.cache_refined_text:
@@ -633,10 +621,10 @@ class Engine:
trigger_prefetch()
checkpoint_seconds = 0.
try:
- with progress.layers(self.transformer.transformer_blocks), LayerOffloader(
+ with progress.layers(self.transformer.transformer_blocks), self.device_backend.make_offloader(
self.offload_layers, prefetch=self.prefetch, weight_source=self.stream_weight_source) as offloader:
latents, audio = generate_latents(self.transformer, prompt, tags, frames,
- self.steps, seed, 'cuda', step_seconds=step_seconds,
+ self.steps, seed, self.device_backend.device, step_seconds=step_seconds,
conditions=conditions)
stats = offloader.stats()
# StepTimes.append closes over the live offloader. Retaining
@@ -659,8 +647,8 @@ class Engine:
**{name: getattr(self.attention, name, 0) - count
for name, count in parallel_before.items()}),
'text_refinement': refinement,
- 'torch_peak_allocated_bytes': torch.cuda.max_memory_allocated(),
- 'torch_peak_reserved_bytes': torch.cuda.max_memory_reserved()}
+ 'torch_peak_allocated_bytes': self.device_backend.max_memory_allocated(),
+ 'torch_peak_reserved_bytes': self.device_backend.max_memory_reserved()}
if refining:
sampled['refinement'] = dict(base_steps=self.steps, steps=refine_steps,
start_index=self.steps - refine_steps, restart_seed=seed,
@@ -673,11 +661,11 @@ class Engine:
checkpoint_seconds = time.perf_counter() - tick
finally:
self.transformer._freevideo_refined_text = None
- torch.cuda.synchronize()
+ self.device_backend.synchronize()
elapsed = time.perf_counter() - started - checkpoint_seconds
- torch.cuda.empty_cache()
- sampled.update(sample_seconds=elapsed, torch_peak_allocated_bytes=torch.cuda.max_memory_allocated(),
- torch_peak_reserved_bytes=torch.cuda.max_memory_reserved())
+ self.device_backend.empty_cache()
+ sampled.update(sample_seconds=elapsed, torch_peak_allocated_bytes=self.device_backend.max_memory_allocated(),
+ torch_peak_reserved_bytes=self.device_backend.max_memory_reserved())
return latents, audio, sampled
@torch.no_grad()
@@ -700,10 +688,7 @@ class Engine:
identity = dict(manifest=digest(self.cache / 'manifest.json'), weights=fingerprint(self.cache / 'root.safetensors'),
engine=digest(Path(__file__)), upstream=digest(implementation), torch=str(torch.__version__),
arithmetic={k: self.config[k] for k in ('attention', 'linear_compute', 'fp8_gemm', 'inference_kernels', 'head_chunk', 'projection_chunk')},
- cuda=torch.version.cuda, gpu=torch.cuda.get_device_name(),
- tf32=torch.backends.cuda.matmul.allow_tf32,
- bf16_reduced_reduction=torch.backends.cuda.matmul.allow_bf16_reduced_precision_reduction,
- deterministic=torch.are_deterministic_algorithms_enabled())
+ **self.device_backend.arithmetic_identity())
cache = InputCache(identity, root=self.input_cache_dir, kind='refined-text')
cpu = prompt.detach().to('cpu').contiguous()
cache_key = str(cpu.dtype) + str(list(cpu.shape)) + hashlib.sha256(cpu.view(torch.uint8).numpy().tobytes()).hexdigest()
@@ -711,7 +696,7 @@ class Engine:
found = cache.lookup(cache_key)
if found:
path, entry = found
- text = torch.load(path, map_location='cuda', weights_only=True)
+ text = torch.load(path, map_location=self.device_backend.device, weights_only=True)
expected_shape = [1, prompt.shape[-2], self.transformer.context_embedder.out_features]
if (isinstance(text, torch.Tensor) and list(text.shape) == expected_shape
and str(text.dtype) == entry['metrics'].get('dtype') and bool(torch.isfinite(text).all())):
@@ -739,12 +724,12 @@ class Engine:
if prompt.ndim != 3 or prompt.shape[0] != 1:
raise ValueError('Expected one text prompt for refinement')
text = self.transformer.context_embedder(prompt.to(input_dtype(self.transformer.context_embedder)))
- with LayerOffloader(refiner, prefetch=False,
+ with self.device_backend.make_offloader(refiner, prefetch=False,
weight_source=self.stream_weight_source if self.stream_refiner_count else None) as loader:
text = self.transformer.token_refiner(text)
stats = loader.stats()
del loader
- torch.cuda.synchronize()
+ self.device_backend.synchronize()
if not self.stream_refiner_count:
refiner.to('meta')
self.refiner_released = True
@@ -761,7 +746,7 @@ class Engine:
except (OSError, ValueError) as error:
note = str(error)
gc.collect()
- torch.cuda.empty_cache()
+ self.device_backend.empty_cache()
empty_host_cache(torch)
return {'seconds': time.perf_counter() - started, 'shape': list(text.shape),
'refiner_weights_released': True, 'offload': stats, 'cache_hit': False, 'cache_saved': saved, 'cache_note': note}
@@ -779,5 +764,5 @@ class Engine:
self.attention = None
self.closed = True
gc.collect()
- torch.cuda.empty_cache()
+ self.device_backend.empty_cache()
empty_host_cache(torch)
diff --git a/freevideo_engine/support_report.py b/freevideo_engine/support_report.py
index d1e920a..9d4a3a0 100644
--- a/freevideo_engine/support_report.py
+++ b/freevideo_engine/support_report.py
@@ -4,6 +4,7 @@ import json
import math
from pathlib import Path
import statistics
+import sys
import time
from . import __version__
@@ -24,6 +25,16 @@ def code_identity():
package = Path(__file__).parent
names = ('generate.py', 'policy.py', 'runtime.py', 'attention.py', 'decode.py', 'worker.py',
'encode_worker.py', 'encoder_checkpoint.py', 'system.py')
+ if sys.platform == 'darwin':
+ names = ('macos_generate.py', 'macos_stages.py', 'macos_runtime.py', 'macos_encoder.py', 'macos_decode.py',
+ 'macos_vdn.py', 'backends/mps.py', 'backends/mps_weights.py', 'backends/mps_fp8.py',
+ 'backends/mps_linear.py', 'backends/mps_attention.py', 'backends/mps_nvfp4.py',
+ 'backends/mps_delta.py', 'backends/mps_features.py', 'backends/mps_qk.py',
+ 'backends/mps_mlx_attention.py', 'backends/mps_vae_encode.py', 'backends/mps_modulation.py',
+ 'macos_compute.py', 'macos_decode_tiles.py',
+ 'macos_memory.py', 'macos_process_memory.py',
+ 'attention.py', 'refine.py', 'reference_sampler.py', 'adaln.py', 'latent_upscale.py',
+ 'media_encoding.py', 'media_conditioning.py', 'encoder_checkpoint.py', 'system.py')
values = {}
for name in names:
try:
diff --git a/freevideo_engine/system.py b/freevideo_engine/system.py
index d73191b..8c798cd 100644
--- a/freevideo_engine/system.py
+++ b/freevideo_engine/system.py
@@ -55,6 +55,9 @@ def system_memory():
if windows():
from .win32 import memory_status
return memory_status()
+ if sys.platform == 'darwin':
+ from .macos_memory import memory_status
+ return memory_status()
values = {k: int(v.split()[0]) * 1024 for k, v in
(line.split(':', 1) for line in Path('/proc/meminfo').read_text(encoding='utf-8').splitlines())
if v.strip().endswith('kB')}
diff --git a/freevideo_engine/testing.py b/freevideo_engine/testing.py
index dbcb22c..0f69e3c 100644
--- a/freevideo_engine/testing.py
+++ b/freevideo_engine/testing.py
@@ -232,10 +232,13 @@ def environment(machine):
PATH=(str(Path(machine['git']).parent) + os.pathsep if machine.get('git') else '') + os.environ.get('PATH', ''),
FREEVIDEO_MODEL_ROOT=machine['model_root'], FREEVIDEO_COMFY_ROOT=machine['comfy_root'],
FREEVIDEO_COMFY_PYTHON=machine['comfy_python'],
- CUDA_VISIBLE_DEVICES=inherited('CUDA_VISIBLE_DEVICES', machine['gpu_uuid']),
PYTHONUNBUFFERED='1', PYTHONUTF8='1', PYTHONIOENCODING='utf-8',
FREEVIDEO_LOCK_PATH=inherited('FREEVIDEO_LOCK_PATH', str(Path(machine['root']) / 'engine.lock')),
OMP_NUM_THREADS='8', MKL_NUM_THREADS='8')
+ if machine.get('device_backend') == 'mps':
+ from .macos_bootstrap import environment as native_environment
+ return native_environment(machine['root'], dict(env, OMP_NUM_THREADS='2', MKL_NUM_THREADS='2'))
+ env['CUDA_VISIBLE_DEVICES'] = inherited('CUDA_VISIBLE_DEVICES', machine['gpu_uuid'])
from .triton_compat import environment as compiler_environment
return compiler_environment(machine['root'], env)
diff --git a/freevideo_engine/worker.py b/freevideo_engine/worker.py
index cf47f2f..639c132 100644
--- a/freevideo_engine/worker.py
+++ b/freevideo_engine/worker.py
@@ -52,9 +52,9 @@ def prefetch_compiler_keys():
def device_memory_report(budget_bytes, allocator_limit_bytes=None, *, reserve_bytes=0, capacity_trial=False):
- from .gpu_budget import configure
- return configure(torch, budget_bytes, allocator_limit_bytes, reserve_bytes=reserve_bytes,
- capacity_trial=capacity_trial)
+ from .backends import get_backend
+ return get_backend(torch_module=torch).configure_budget(
+ budget_bytes, allocator_limit_bytes, reserve_bytes=reserve_bytes, capacity_trial=capacity_trial)
def generate(request, resident=None):
diff --git a/pyproject.toml b/pyproject.toml
index 4dc39f5..a425e88 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -31,4 +31,4 @@ freevideo = "freevideo_engine.cli:main"
include = ["freevideo_engine*"]
[tool.setuptools.package-data]
-freevideo_engine = ["build-version.txt", "build-identity.json", "dependencies.json", "model_files.json", "model_shares.json", "prepared_models.json", "bootstrap_versions.json", "uv_downloads.json", "torch_downloads.json", "test_prompts.json", "windows_bootstrap.ps1", "assets/*.png", "assets/*.ico", "launcher/*.qml", "launcher/licenses/*.txt", "licenses/*.txt"]
+freevideo_engine = ["build-version.txt", "build-identity.json", "release_notes.json", "dependencies.json", "model_files.json", "model_shares.json", "prepared_models.json", "macos_reference_catalog.json", "bootstrap_versions.json", "uv_downloads.json", "torch_downloads.json", "test_prompts.json", "windows_bootstrap.ps1", "assets/*.png", "assets/*.ico", "launcher/*.qml", "launcher/licenses/*.txt", "licenses/*.txt"]
diff --git a/scripts/build_macos.py b/scripts/build_macos.py
new file mode 100644
index 0000000..92ac8d3
--- /dev/null
+++ b/scripts/build_macos.py
@@ -0,0 +1,204 @@
+"""Build the shared launcher as an arm64 Mac app using Python 3.12.
+
+Build outputs are private until native installation and generation pass. Local
+builds are ad-hoc signed; this does not establish Developer ID notarization.
+"""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import platform
+import shutil
+import subprocess
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from freevideo_engine.desktop_runtime import check_launcher_dependencies, package_data_files, source_files
+from freevideo_engine.launcher_update import MAC_CHANNEL, build_identity
+from scripts.build_windows import build_info, stamp_source
+from freevideo_engine.release_notes import markdown
+from scripts.build_launcher_notices import collect as collect_notices
+
+
+OPEN_GUIDE_NAME = 'Open FreeVideo.txt'
+OPEN_GUIDE = '''FreeVideo for Mac — 首次打开 / First open
+
+安装
+1. 将 FreeVideo.app 拖入 Applications(应用程序)。
+2. 从“应用程序”打开 FreeVideo,按安装器引导配置运行环境和模型。
+
+如果 macOS 提示无法验证开发者或无法检查恶意软件
+这是因为预览版暂未进行 Apple 公证。放行前请先确认安装包来自官方:
+1. 只从 https://github.com/FlashML-org/FreeVideo/releases/tag/macos-preview 下载。
+2. 在“终端”运行 shasum -a 256 ~/Downloads/FreeVideo-Mac-arm64.dmg,结果应与该页面 SHA256SUMS.txt 中的值一致。
+然后:
+3. 先尝试打开 FreeVideo,再关闭系统提示。
+4. 打开“系统设置” → “隐私与安全”,向下找到 FreeVideo,点击“仍要打开”。
+5. 在确认窗口点击“打开”,按系统要求验证身份。
+这只放行 FreeVideo,不会关闭 Gatekeeper 或改动其他安全设置。系统会记住此次允许;更新应用后可能需要重新确认。
+如果没有“仍要打开”,请向 FreeVideo 反馈完整提示;设备管理策略可能限制打开。
+如果提示应用已损坏或包含恶意软件,请停止打开并向 FreeVideo 反馈。
+
+Install
+1. Drag FreeVideo.app into Applications.
+2. Open FreeVideo from Applications and follow the installer to set up the runtime and models.
+
+If macOS cannot verify the developer or check the app for malicious software
+This happens because the preview isn't notarized by Apple yet. Before approving it, make sure the file is the official one:
+1. Download it only from https://github.com/FlashML-org/FreeVideo/releases/tag/macos-preview.
+2. In Terminal, run shasum -a 256 ~/Downloads/FreeVideo-Mac-arm64.dmg. The result should match the value in SHA256SUMS.txt on that page.
+Then:
+3. Try opening FreeVideo, then dismiss the system alert.
+4. Open System Settings → Privacy & Security, scroll to FreeVideo and click Open Anyway.
+5. Click Open in the confirmation and authenticate if asked.
+This approves FreeVideo only. It doesn't turn off Gatekeeper or change other security settings. macOS remembers this approval; an app update may ask again.
+If Open Anyway is unavailable, report the full alert to FreeVideo; device management may restrict opening.
+If the alert says the app is damaged or contains malware, stop and report it to FreeVideo.
+
+Apple 官方说明 / Apple instructions:
+https://support.apple.com/102445
+'''
+
+
+def write_open_guide(directory):
+ path = directory / OPEN_GUIDE_NAME
+ payload = OPEN_GUIDE.encode('utf-8')
+ path.write_bytes(payload)
+ return dict(name=path.name, bytes=len(payload), sha256=hashlib.sha256(payload).hexdigest())
+
+
+def identity(root):
+ value = build_info(root)
+ rows = {p.relative_to(root).as_posix(): hashlib.sha256(p.read_bytes()).hexdigest()
+ for p in source_files(root)}
+ # Include uncommitted development changes; do not label them as HEAD.
+ value.update(revision=hashlib.sha256(json.dumps(rows, sort_keys=True).encode()).hexdigest(),
+ channel=MAC_CHANNEL, target='macos-arm64', packaging='app')
+ return build_identity(value)
+
+
+def render_icon(source, pixels):
+ """Give the Mac icon a transparent margin without changing shared artwork."""
+ from PySide6.QtCore import Qt
+ from PySide6.QtGui import QImage, QPainter
+ # The shared rounded tile fills its canvas. Inset it to 824/1024 of the
+ # Mac icon so Finder and the Dock don't display an oversized tile.
+ extent = round(pixels * 824 / 1024)
+ artwork = source.scaled(extent, extent, Qt.KeepAspectRatio, Qt.SmoothTransformation)
+ canvas = QImage(pixels, pixels, QImage.Format_ARGB32_Premultiplied)
+ canvas.fill(Qt.transparent)
+ painter = QPainter(canvas)
+ try:
+ painter.drawImage((pixels - artwork.width()) // 2,
+ (pixels - artwork.height()) // 2, artwork)
+ finally:
+ painter.end()
+ return canvas
+
+
+def make_icon(destination):
+ from PySide6.QtGui import QImage
+ source = QImage(str(ROOT / 'freevideo_engine/assets/icon.png'))
+ if source.isNull():
+ raise ValueError('Launcher icon is missing')
+ folder = destination / 'FreeVideo.iconset'
+ folder.mkdir()
+ for size in (16, 32, 128, 256, 512):
+ for scale in (1, 2):
+ suffix = '@2x' if scale == 2 else ''
+ output = folder / ('icon_%dx%d%s.png' % (size, size, suffix))
+ if not render_icon(source, size * scale).save(str(output)):
+ raise OSError('Could not write Mac icon')
+ result = destination / 'FreeVideo.icns'
+ subprocess.run(['/usr/bin/iconutil', '-c', 'icns', str(folder), '-o', str(result)], check=True)
+ return result
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--out', type=Path, required=True)
+ args = parser.parse_args()
+ if platform.system() != 'Darwin' or platform.machine() != 'arm64' or sys.version_info[:2] != (3, 12):
+ parser.error('Build on native Apple Silicon with Python 3.12')
+ check_launcher_dependencies()
+ out = args.out.expanduser().resolve()
+ out.mkdir(parents=True, exist_ok=False)
+ build = identity(ROOT)
+ staged = out / 'engine-source'
+ for path in source_files(ROOT):
+ if path.is_relative_to(ROOT / 'freevideo_engine/launcher/licenses/bundled'):
+ continue
+ target = staged / path.relative_to(ROOT)
+ target.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(path, target)
+ stamp = stamp_source(staged, build)
+ notices = staged / 'freevideo_engine/launcher/licenses/bundled'
+ collect_notices(ROOT, notices)
+ build_file = out / 'launcher-build.json'
+ build_file.write_text(json.dumps(build, indent=2) + '\n', encoding='utf-8')
+ icon = make_icon(out)
+ data = [(str(staged), 'engine-source'), (str(build_file), '.'),
+ (str(stamp), 'freevideo_engine'),
+ (str(stamp.parent / 'build-identity.json'), 'freevideo_engine'),
+ (str(notices), 'freevideo_engine/launcher/licenses/bundled')]
+ data += [(str(path), str(path.parent.relative_to(ROOT))) for path in package_data_files(ROOT)
+ if path.name not in ('build-version.txt', 'build-identity.json')
+ and not path.is_relative_to(ROOT / 'freevideo_engine/launcher/licenses/bundled')]
+ spec = out / 'FreeVideo.spec'
+ # Shared QML, controller, diagnostics and network services. Never bundle
+ # Torch/model weights or pick up packages from a generation environment.
+ short_version = build['product_version']
+ plist = dict(CFBundleDisplayName='FreeVideo', CFBundleShortVersionString=short_version,
+ CFBundleVersion='.'.join(build['version'].split('.')[:3]), FreeVideoVersion=build['version'],
+ CFBundleDevelopmentRegion='en', CFBundleLocalizations=['en', 'zh-Hans'],
+ CFBundleAllowMixedLocalizations=True,
+ LSMinimumSystemVersion='14.0', NSHighResolutionCapable=True,
+ NSPrincipalClass='NSApplication')
+ text = f'''# Generated by scripts/build_macos.py
+a = Analysis([{str(ROOT / 'scripts/macos_app.py')!r}], pathex=[{str(ROOT)!r}],
+ binaries=[], datas={data!r},
+ hiddenimports=['psutil', 'PySide6.QtQml', 'PySide6.QtQuick',
+ 'PySide6.QtQuickControls2', 'PySide6.QtWidgets', 'freevideo_engine.managed'],
+ excludes=['torch', 'triton', 'numpy', 'transformers', 'tkinter'])
+pyz = PYZ(a.pure)
+exe = EXE(pyz, a.scripts, [], exclude_binaries=True, name='FreeVideo',
+ debug=False, strip=False, upx=False, console=False, target_arch='arm64')
+coll = COLLECT(exe, a.binaries, a.datas, strip=False, upx=False, name='FreeVideo')
+app = BUNDLE(coll, name='FreeVideo.app', icon={str(icon)!r},
+ bundle_identifier='org.flashml.FreeVideo', info_plist={plist!r})
+'''
+ spec.write_text(text, encoding='utf-8')
+ # Historical app bundles must not fill the user's application search with
+ # duplicate FreeVideo entries. The exported disk image stays in dist.
+ application_dist = out / 'applications.noindex'
+ subprocess.run([sys.executable, '-m', 'PyInstaller', '--noconfirm',
+ '--distpath', str(application_dist), '--workpath', str(out / 'build'), str(spec)],
+ cwd=ROOT, check=True)
+ app = application_dist / 'FreeVideo.app'
+ subprocess.run(['/usr/bin/codesign', '--verify', '--deep', '--strict', str(app)], check=True)
+ (out / 'dist').mkdir(exist_ok=True)
+ (out / 'dist/RELEASE_NOTES.md').write_text(markdown(build), encoding='utf-8')
+ guide = write_open_guide(out / 'dist')
+ # The disk image is the only download. Keep the guide beside the app: it
+ # must be readable before Gatekeeper allows the app to run.
+ image_root = out / 'dmg-root.noindex'
+ image_root.mkdir()
+ subprocess.run(['/usr/bin/ditto', str(app), str(image_root / app.name)], check=True)
+ (image_root / 'Applications').symlink_to('/Applications', target_is_directory=True)
+ shutil.copyfile(out / 'dist' / guide['name'], image_root / guide['name'])
+ dmg = out / 'dist/FreeVideo-Mac-arm64.dmg'
+ subprocess.run(['/usr/bin/hdiutil', 'create', '-volname', 'FreeVideo', '-srcfolder',
+ str(image_root), '-format', 'UDZO', str(dmg)], check=True)
+ sha = hashlib.sha256(dmg.read_bytes()).hexdigest()
+ (out / 'dist/SHA256SUMS.txt').write_text(sha + ' ' + dmg.name + '\n', encoding='utf-8')
+ result = dict(app=str(app), dmg=str(dmg), dmg_bytes=dmg.stat().st_size, dmg_sha256=sha,
+ build=build, signing='ad-hoc', notarized=False, first_open_guide=guide,
+ native_installation_validation='pending', native_generation_validation='pending')
+ (out / 'build-result.json').write_text(json.dumps(result, indent=2) + '\n', encoding='utf-8')
+ print(json.dumps(result))
+
+
+if __name__ == '__main__':
+ main()
diff --git a/scripts/build_windows.py b/scripts/build_windows.py
index b70db16..ca4aa38 100644
--- a/scripts/build_windows.py
+++ b/scripts/build_windows.py
@@ -14,6 +14,7 @@ ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from freevideo_engine.desktop_runtime import check_launcher_dependencies, package_data_files, source_files
from freevideo_engine.launcher_update import REPOSITORY, CHANNEL
+from freevideo_engine.release_notes import catalog, markdown
from scripts.build_launcher_notices import collect as collect_notices
@@ -28,7 +29,7 @@ def build_info(root):
# Numeric UTC date + HHMMSS is also a valid Python package version.
version = '.'.join(str(int(part)) for part in time.strftime('%Y.%m.%d.%H%M%S', time.gmtime(built_at)).split('.'))
return dict(schema=1, repository=REPOSITORY, channel=CHANNEL, revision=revision,
- built_at=built_at, version=version)
+ built_at=built_at, version=version, **catalog(root / 'freevideo_engine'))
def stamp_source(staged, identity):
@@ -78,7 +79,7 @@ VSVersionInfo(
VarFileInfo([VarStruct('Translation', [1033, 1200])])
]
)
-''' % (version, version, identity['version'], identity['version'])
+''' % (version, version, identity['version'], identity.get('product_version', identity['version']))
path = out / 'version-info.txt'
path.write_text(text, encoding='utf-8')
return path
@@ -135,6 +136,7 @@ def main():
digest = hashlib.sha256(executable.read_bytes()).hexdigest()
(executable.parent / 'SHA256SUMS.txt').write_text(digest + ' FreeVideo.exe\n', encoding='utf-8')
(executable.parent / 'launcher-build.json').write_text(json.dumps(identity, indent=2), encoding='utf-8')
+ (executable.parent / 'RELEASE_NOTES.md').write_text(markdown(identity), encoding='utf-8')
shutil.copytree(notices, executable.parent / 'licenses')
if args.onefolder:
shutil.make_archive(str(out / 'dist/FreeVideo-Windows-folder'), 'zip',
diff --git a/scripts/macos_app.py b/scripts/macos_app.py
new file mode 100644
index 0000000..7fafd74
--- /dev/null
+++ b/scripts/macos_app.py
@@ -0,0 +1,5 @@
+"""Native Apple Silicon application; the interface is shared with Windows."""
+from freevideo_engine.modern_launcher import main
+
+if __name__ == '__main__':
+ main()
diff --git a/scripts/verify_macos_build.py b/scripts/verify_macos_build.py
new file mode 100644
index 0000000..f4c955d
--- /dev/null
+++ b/scripts/verify_macos_build.py
@@ -0,0 +1,127 @@
+"""Verify a built Mac DMG payload, signatures and image fidelity on macOS."""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+import stat
+import sys
+import subprocess
+import time
+import traceback
+
+
+
+def digest(path):
+ with path.open('rb') as stream:
+ return hashlib.file_digest(stream, 'sha256').hexdigest()
+
+
+def snapshot(root):
+ rows = {}
+ for folder, dirs, files in os.walk(root, followlinks=False):
+ for name in sorted(dirs + files):
+ path = Path(folder) / name
+ record = dict(mode=stat.S_IMODE(path.lstat().st_mode))
+ if path.is_symlink():
+ record.update(kind='symlink', target=os.readlink(path))
+ elif path.is_file():
+ record.update(kind='file', bytes=path.stat().st_size, sha256=digest(path))
+ elif path.is_dir():
+ record['kind'] = 'directory'
+ else:
+ raise ValueError('Unsupported app bundle entry: ' + str(path))
+ rows[path.relative_to(root).as_posix()] = record
+ return rows
+
+
+def verify(build_directory, report_directory):
+ build_directory = Path(build_directory).resolve()
+ report_directory = Path(report_directory).absolute()
+ report_directory.mkdir(parents=True, exist_ok=False)
+ build = json.loads((build_directory / 'build-result.json').read_text())
+ result = dict(success=False, scope=__doc__, started_at=time.time(), build=build)
+ (report_directory / 'run.json').write_text(json.dumps(result, indent=2) + '\n')
+ commands = []
+ mounted = False
+ mount = report_directory / 'mounted.noindex'
+ mount.mkdir()
+ started = time.monotonic()
+
+ def run(command, timeout=120):
+ output = subprocess.run(command, capture_output=True, text=True, timeout=timeout)
+ commands.append(dict(command=command, returncode=output.returncode,
+ stdout=output.stdout, stderr=output.stderr))
+ output.check_returncode()
+ return output
+
+ try:
+ if shutil.disk_usage(report_directory).free < 2 * 2**30:
+ raise OSError('Insufficient scratch disk for artifact verification')
+ image = Path(build['dmg'])
+ if image.stat().st_size != build['dmg_bytes'] or digest(image) != build['dmg_sha256']:
+ raise ValueError('Artifact differs from build receipt: ' + image.name)
+ result['image_hash_passed'] = True
+ guide = build.get('first_open_guide')
+ guide_payload = None
+ if guide is not None:
+ if guide.get('name') != 'Open FreeVideo.txt':
+ raise ValueError('Unexpected first-open guide name')
+ guide_path = image.parent / guide['name']
+ if guide_path.is_symlink():
+ raise ValueError('First-open guide must be a regular file')
+ guide_payload = guide_path.read_bytes()
+ if (len(guide_payload) != guide['bytes'] or
+ hashlib.sha256(guide_payload).hexdigest() != guide['sha256']):
+ raise ValueError('First-open guide differs from build receipt')
+ original = snapshot(Path(build['app']))
+ run(['/usr/bin/hdiutil', 'verify', build['dmg']])
+ run(['/usr/bin/hdiutil', 'attach', '-readonly', '-nobrowse', '-noautoopen',
+ '-mountpoint', str(mount), build['dmg']])
+ mounted = True
+ if not (mount / 'Applications').is_symlink() or os.readlink(mount / 'Applications') != '/Applications':
+ raise ValueError('DMG Applications shortcut changed')
+ if guide is not None:
+ image_guide = mount / guide['name']
+ if image_guide.is_symlink() or image_guide.read_bytes() != guide_payload:
+ raise ValueError('DMG first-open guide differs from build receipt')
+ result['first_open_guide_exact'] = True
+ imaged = snapshot(mount / 'FreeVideo.app')
+ if imaged != original:
+ result['dmg_differences'] = [k for k in sorted(set(imaged) | set(original))
+ if imaged.get(k) != original.get(k)]
+ raise ValueError('DMG app differs from built app')
+ run(['/usr/bin/codesign', '--verify', '--deep', '--strict', str(mount / 'FreeVideo.app')])
+ result.update(dmg_app_exact=True, bundle_entries=len(original),
+ gatekeeper_accepted=False, notarized=False)
+ (report_directory / 'bundle-manifest.json').write_text(json.dumps(original, indent=2) + '\n')
+ result['success'] = True
+ except BaseException:
+ result['error'] = traceback.format_exc()
+ finally:
+ if mounted:
+ try:
+ run(['/usr/bin/hdiutil', 'detach', str(mount)], timeout=60)
+ result['mounted_image_detached'] = True
+ except BaseException:
+ result.update(success=False, detach_error=traceback.format_exc())
+ result.update(elapsed_seconds=time.monotonic()-started, commands=commands)
+ (report_directory / 'result.json').write_text(json.dumps(result, indent=2) + '\n')
+ print(json.dumps({k:v for k,v in result.items() if k not in ('commands','build')}), flush=True)
+ return result
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--build', type=Path, required=True)
+ parser.add_argument('--out', type=Path, required=True)
+ args = parser.parse_args()
+ if sys.platform != 'darwin':
+ parser.error('Verify the disk image on native macOS')
+ result = verify(args.build, args.out)
+ raise SystemExit(not result['success'])
+
+
+if __name__ == '__main__':
+ main()
diff --git a/web/error_panel.js b/web/error_panel.js
index 3950e1c..7738625 100644
--- a/web/error_panel.js
+++ b/web/error_panel.js
@@ -156,6 +156,10 @@ export function failureAdvice(value, t) {
return row('commit', ['Windows memory allocation limit reached', 'Windows 内存提交额度不足'],
['Windows cannot back another memory allocation, even if physical RAM is still available.', 'Windows 已没有足够的提交额度;这与物理 RAM 是否还有空闲是两回事。'],
['Close memory-heavy applications and retry. In Windows virtual memory settings, use a system-managed paging file on a drive with free space.', '关闭占用内存较多的程序后重试。在 Windows 虚拟内存设置中,使用系统管理的分页文件,并确保所在磁盘有空闲空间。']);
+ if (/MPS backend out of memory|MPS (?:generation|encoding|decoding) reached|No unified-memory allowance|Native generation needs at least .* unified memory/i.test(text))
+ return row('unified-memory', ['Unified memory is insufficient', '统一内存不足'],
+ ['Mac CPU and GPU share memory. This stage exceeded the MPS allocation limit or the system memory safety threshold.', 'Mac 的 CPU 与 GPU 共用内存。这一阶段触及了 MPS 分配上限或系统内存保护线。'],
+ ['Close memory-heavy applications and retry. Review any manual RAM limit or reserve; a lower resolution or shorter duration may also help. Export the report if it still fails.', '关闭占用内存较多的程序后重试,检查手动 RAM 限额和预留设置;也可降低分辨率或缩短时长。仍失败时请导出报告。']);
if (/CUDA out of memory|torch\.OutOfMemoryError|cudaErrorMemoryAllocation/i.test(text))
return row('vram', ['GPU memory allocation failed', '显存分配失败'],
['The GPU could not allocate the memory needed at this stage.', '这一阶段的显存申请没有成功。'],
diff --git a/web/freevideo.js b/web/freevideo.js
index 30ab1db..a1f3ab2 100644
--- a/web/freevideo.js
+++ b/web/freevideo.js
@@ -207,9 +207,7 @@ function resultPanel(node) {
const progress = createGenerationProgress(text, undefined, {api}); panel.append(progress.element, progress.report);
let showingResult = false;
node.freevideoReportProgress = message => {
- progress.updateReport(message);
- if (message.new_request) node.freevideoReportId = null;
- if (message.report_id) node.freevideoReportId = message.report_id;
+ node.freevideoReportId = progress.updateReport(message);
};
node.freevideoShowProgress = message => {
if (showingResult) {
@@ -217,6 +215,7 @@ function resultPanel(node) {
panel.title = ''; node.freevideoPrewarm = '';
showingResult = false; warn();
}
+ node.freevideoReportProgress(message);
const retry = message.reset ? undefined : message.retry || node.freevideoProgress?.retry;
node.freevideoProgress = {...message, retry, received_at: message.received_at ?? Date.now()}; progress.update(node.freevideoProgress);
if (panel.firstElementChild !== progress.element) panel.prepend(progress.element);
@@ -271,7 +270,6 @@ function resultPanel(node) {
node.freevideoShowResult = function (message) {
const value = message?.freevideo_summary?.[0]; if (!value) return;
showingResult = true;
- node.freevideoReportId = null; progress.report.hidden = true;
node.freevideoStopProgress();
node.freevideoClearFailure();
node.freevideoLastResult = value;
@@ -279,7 +277,8 @@ function resultPanel(node) {
panel.replaceChildren(); const stats = el("div", undefined, "fv-stats");
stats.hidden = !!value.result_cache_hit;
const number = (value, scale, unit) => Number.isFinite(value) && value >= 0 ? `${(value / scale).toFixed(1)} ${unit}` : "—";
- for (const [label, shown] of [[text("Sampling", "采样"), number(value.sample_seconds, 1, "s")], [text("Request total", "请求总计"), number(value.request_seconds, 1, "s")], [text("VRAM peak", "显存峰值"), number(value.vram_peak_bytes, 2 ** 30, "GiB")], [text("RAM peak", "内存峰值"), number(value.ram_peak_bytes, 2 ** 30, "GiB")]]) {
+ const unified = value.memory_model === 'unified';
+ for (const [label, shown] of [[text("Sampling", "采样"), number(value.sample_seconds, 1, "s")], [text("Request total", "请求总计"), number(value.request_seconds, 1, "s")], [unified ? text("Unified memory", "统一内存总量") : text("VRAM peak", "显存峰值"), number(unified ? value.unified_total_bytes : value.vram_peak_bytes, 2 ** 30, "GiB")], [unified ? text("Process RAM peak", "进程内存峰值") : text("RAM peak", "内存峰值"), number(value.ram_peak_bytes, 2 ** 30, "GiB")]]) {
const stat = el("div", undefined, "fv-stat"); stat.append(el("strong", shown), el("span", label)); stats.append(stat);
}
const links = el("div", undefined, "fv-links");
@@ -297,9 +296,11 @@ function resultPanel(node) {
};
links.append(again);
}
- panel.append(stats, links);
+ panel.append(stats, links, progress.report);
warn();
- panel.title = text("VRAM: engine allocator peak. RAM: measured request processes, ", "显存为引擎分配器峰值,内存为请求进程实测,") + (value.ram_metric || "unknown");
+ panel.title = (unified
+ ? text("Unified memory: device capacity. Process RAM is not total GPU memory, ", "统一内存为设备总量;进程内存不代表 GPU 内存总占用,")
+ : text("VRAM: engine allocator peak. RAM: measured request processes, ", "显存为引擎分配器峰值,内存为请求进程实测,")) + (value.ram_metric || "unknown");
};
node.freevideoRegenerateResult = async value => {
if (node.freevideoRegenerating) return;
diff --git a/web/generation_progress.js b/web/generation_progress.js
index 1376e67..dd31fa0 100644
--- a/web/generation_progress.js
+++ b/web/generation_progress.js
@@ -93,7 +93,10 @@ export function createGenerationProgress(t, now = () => Date.now(), {compact = f
if (reportId !== message.report_id) { report.disabled = false; report.textContent = reportLabel(); }
reportId = message.report_id; report.hidden = false;
}
- if (message.result) report.hidden = true; // The saved video's report link takes over.
+ // The saved video's request record is different from the redacted
+ // diagnostic download. Keep this token available after completion;
+ // only a new request clears it.
+ return reportId;
}
report.onclick = async () => {
if (!reportId || report.disabled) return;
diff --git a/web/setup.js b/web/setup.js
index a1fdd34..64feddf 100644
--- a/web/setup.js
+++ b/web/setup.js
@@ -76,7 +76,8 @@ export async function openSetup() {
compatibility.onclick = openCompatibility;
advanced.append(compatibility);
const resources = node('details');
- resources.append(node('summary', t('Reserved VRAM', '预留显存')));
+ const reserveSummary = node('summary', t('Reserved VRAM', '预留显存'));
+ resources.append(reserveSummary);
const reserveLabel = node('label', t('Reserved VRAM', '预留显存'));
const reserveAuto = node('input'); reserveAuto.type = 'checkbox'; reserveAuto.checked = true;
const autoLabel = node('label'); autoLabel.className = 'fv-check'; autoLabel.append(reserveAuto, node('span', t('Automatic optimization', '自动优化')));
@@ -84,7 +85,8 @@ export async function openSetup() {
reserve.value = '1.0'; reserve.disabled = true; reserve.className = 'fv-number';
reserveLabel.append(reserve, document.createTextNode('GiB'));
const saveReserve = node('button', t('Save', '保存')), reserveStatus = note('');
- resources.append(autoLabel, reserveLabel, note(t('Keep this much additional VRAM free. Applies to new requests; current usage is already accounted for.', '额外保留的空闲显存。对后续请求生效;其他程序当前的占用已单独计入。')), saveReserve, reserveStatus);
+ const reserveHelp = note(t('Keep this much additional VRAM free. Applies to new requests; current usage is already accounted for.', '额外保留的空闲显存。对后续请求生效;其他程序当前的占用已单独计入。'));
+ resources.append(autoLabel, reserveLabel, reserveHelp, saveReserve, reserveStatus);
advanced.append(resources);
reserveAuto.onchange = () => { reserve.disabled = reserveAuto.checked; };
// Placement calibration. A measurement, not a setting: it changes nothing
@@ -135,10 +137,19 @@ export async function openSetup() {
} : {});
const result = await response.json(); if (!response.ok || result.error) throw new Error(result.error || response.statusText); return result;
};
+ let reserveField = 'gpu_reserve_gib';
const showResources = value => {
- reserveAuto.checked = value?.gpu_reserve_gib == null;
+ const unified = value && Object.hasOwn(value, 'ram_reserve_gib');
+ reserveField = unified ? 'ram_reserve_gib' : 'gpu_reserve_gib';
+ reserveSummary.textContent = unified ? t('Reserved unified memory', '预留统一内存') : t('Reserved VRAM', '预留显存');
+ reserveLabel.firstChild.textContent = reserveSummary.textContent;
+ reserve.min = unified ? '1' : '0.2';
+ reserveAuto.checked = value?.[reserveField] == null;
reserve.disabled = reserveAuto.checked;
- if (!reserveAuto.checked) reserve.value = String(value.gpu_reserve_gib);
+ reserve.value = reserveAuto.checked ? (unified ? '2.0' : '1.0') : String(value[reserveField]);
+ reserveHelp.textContent = unified
+ ? t('CPU and GPU share unified memory. Keep this much additional RAM available for macOS and other applications. Applies to new requests.', 'CPU 与 GPU 共用统一内存。额外保留这些 RAM 供 macOS 和其他程序使用,对后续请求生效。')
+ : t('Keep this much additional VRAM free. Applies to new requests; current usage is already accounted for.', '额外保留的空闲显存。对后续请求生效;其他程序当前的占用已单独计入。');
};
calibrateButton.onclick = async () => {
if (!calibrateRepeats.checkValidity()) { calibrateRepeats.reportValidity(); return; }
@@ -160,7 +171,7 @@ export async function openSetup() {
if (!reserveAuto.checked && (!reserve.value || !reserve.checkValidity())) { reserve.reportValidity(); return; }
saveReserve.disabled = true;
try {
- showResources(await request('resources', {gpu_reserve_gib: reserveAuto.checked ? null : Number(reserve.value)}));
+ showResources(await request('resources', {[reserveField]: reserveAuto.checked ? null : Number(reserve.value)}));
reserveStatus.textContent = t('Saved · applies to the next request', '已保存 · 下次生成生效');
} catch (error) { reserveStatus.textContent = error.message; }
finally { saveReserve.disabled = false; }
@@ -243,7 +254,9 @@ export async function openSetup() {
[t("Hardlinked / copied", "硬链接/复制"), `${gib(local.linked_bytes || 0)} / ${gib(local.copy_bytes || 0)}`],
[t("Additional disk estimate", "额外磁盘预估"), gib(value.disks?.reduce((sum, d) => sum + d.needed_bytes, 0))],
];
- if (value.prepared_model) facts.push([t("Model", "模型"), `${value.prepared_model.repo} · ${t("slim FP8, no local conversion", "精简 FP8,无需本地转换")}`]);
+ if (value.prepared_model) facts.push([t("Model", "模型"), `${value.prepared_model.repo} · ${value.prepared_model.scale_granularity === "int8_convrot"
+ ? t("slim ConvRot int8, no local conversion", "精简 ConvRot int8,无需本地转换")
+ : t("slim FP8, no local conversion", "精简 FP8,无需本地转换")}`]);
const list = node('dl'); list.className = 'fv-facts';
for (const [key, shown] of facts) list.append(node('dt', key), node('dd', shown));
plan.append(list);
diff --git a/web/studio.js b/web/studio.js
index d139858..1b41f45 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -5,7 +5,7 @@ import { openSetup } from './setup.js';
import { wordmark } from './branding.js';
import { createGenerationProgress } from './generation_progress.js';
import { viewSwitch, viewChanged } from './view_navigation.js';
-import { createUpdateNotice } from './updates.js';
+import { createUpdateNotice, createVersionInfo } from './updates.js';
import { createPreviewScene } from './preview_scene.js?v=20260929-swell';
import { animateDetails, closeDialog } from './motion.js';
import { openLibrary, latestVideo } from './library.js';
@@ -120,6 +120,7 @@ export function openStudio(node) {
const header = el('header', null, 'fv-header'), brand = el('div', null, 'fv-brand');
brand.append(wordmark());
const tools = el('div', null, 'fv-header-actions');
+ const versionInfo = createVersionInfo(cn); tools.append(versionInfo.element); cleanup.push(versionInfo.dispose);
tools.append(button(t('Settings', '设置'), openSetup, 'fv-quiet'));
const navigation = viewSwitch('studio', () => {}, () => {
closeDialog(dialog);
@@ -309,8 +310,8 @@ export function openStudio(node) {
const status = el('div', '', 'fv-status'); status.setAttribute('role', 'status');
const stats = el('div', null, 'fv-stats'), budget = el('div', '', 'fv-budget'), links = el('div', null, 'fv-result-links');
stats.hidden = true;
- const metrics = [];
- for (const label of [t('Sampling', '采样耗时'), t('Request total', '请求总计'), t('VRAM peak', '显存峰值'), t('RAM peak', '内存峰值')]) { const box = el('div', null, 'fv-stat'), n = el('strong', '—'); box.append(n, el('span', label)); stats.append(box); metrics.push(n); }
+ const metrics = [], metricLabels = [];
+ for (const label of [t('Sampling', '采样耗时'), t('Request total', '请求总计'), t('VRAM peak', '显存峰值'), t('RAM peak', '内存峰值')]) { const box = el('div', null, 'fv-stat'), n = el('strong', '—'), caption = el('span', label); box.append(n, caption); stats.append(box); metrics.push(n); metricLabels.push(caption); }
const prewarm = el('div', node.freevideoPrewarm || '', 'fv-prewarm');
const reuseRow = el('div', null, 'fv-reuse-result'); reuseRow.hidden = true;
const reuseNotice = el('span', t('Reused previous result', '已复用上次结果'));
@@ -327,14 +328,19 @@ export function openStudio(node) {
let result = node.freevideoLastResult || app.nodeOutputs?.[node.id]?.freevideo_summary?.[0];
function showResult(r) {
if (!r?.video || disposed) return; result = r;
- progress.report.hidden = !node.freevideoReportId;
+ progress.updateReport({report_id: node.freevideoReportId});
stage.querySelector('video')?.pause(); stageMedia.replaceChildren();
const video = el('video'); video.src = view(r.video, 'output'); video.controls = true; video.preload = 'metadata'; video.playsInline = true; stageMedia.append(video);
stats.hidden = !!r.result_cache_hit;
reuseRow.hidden = !r.result_cache_hit;
regenerate.disabled = false; regenerate.textContent = t('Regenerate', '重新生成');
- const shown = [number(r.sample_seconds), number(r.request_seconds), number(r.vram_peak_bytes, 2 ** 30, 'GiB'), number(r.ram_peak_bytes, 2 ** 30, 'GiB')]; metrics.forEach((e, i) => e.textContent = shown[i]);
- budget.textContent = !r.result_cache_hit && Number.isFinite(r.gpu_budget_bytes) ? `${t('VRAM budget', '可用显存预算')} ${number(r.gpu_budget_bytes, 2 ** 30, 'GiB')} · ${t('Device', '显卡总量')} ${number(r.gpu_total_bytes, 2 ** 30, 'GiB')}` : '';
+ const unified = r.memory_model === 'unified';
+ metricLabels[2].textContent = unified ? t('Unified memory', '统一内存总量') : t('VRAM peak', '显存峰值');
+ metricLabels[3].textContent = unified ? t('Process RAM peak', '进程内存峰值') : t('RAM peak', '内存峰值');
+ const shown = [number(r.sample_seconds), number(r.request_seconds), number(unified ? r.unified_total_bytes : r.vram_peak_bytes, 2 ** 30, 'GiB'), number(r.ram_peak_bytes, 2 ** 30, 'GiB')]; metrics.forEach((e, i) => e.textContent = shown[i]);
+ budget.textContent = r.result_cache_hit ? '' : unified
+ ? (Number.isFinite(r.unified_reserve_bytes) ? `${t('Reserved unified memory', '预留统一内存')} ${number(r.unified_reserve_bytes, 2 ** 30, 'GiB')}` : '')
+ : (Number.isFinite(r.gpu_budget_bytes) ? `${t('VRAM budget', '可用显存预算')} ${number(r.gpu_budget_bytes, 2 ** 30, 'GiB')} · ${t('Device', '显卡总量')} ${number(r.gpu_total_bytes, 2 ** 30, 'GiB')}` : '');
links.replaceChildren();
for (const [label, file, cls] of [[t('Download video', '下载视频'), r.video, 'fv-primary'], [t('Report', '查看报告'), r.report, 'fv-quiet']]) { if (!file) continue; const a = el('a', label, cls); a.href = outputDownloadURL(api, file); a.download = file === r.video ? '' : file.split('/').pop(); links.append(a); }
const g = r.geometry; if (g?.width && g?.height) previewSize(g.width, g.height);
diff --git a/web/theme.css b/web/theme.css
index 4fca3d9..bccbdac 100644
--- a/web/theme.css
+++ b/web/theme.css
@@ -1,7 +1,7 @@
/* One token table for the web views, mirroring freevideo_engine/branding.py so
a control looks the same in the launcher and in ComfyUI. Scope the tokens to
our own views; never change ComfyUI's theme. */
-:where(.fv-studio,.fv-setup,.fv-panel,.fv-generation-progress,.fv-view-navigation,.fv-prompt-guide,.fv-failure-dialog,.fv-reference-picker){
+:where(.fv-studio,.fv-setup,.fv-panel,.fv-generation-progress,.fv-view-navigation,.fv-prompt-guide,.fv-failure-dialog,.fv-reference-picker,.fv-release-notes){
/* Surfaces, from the backdrop up to a hovered control; mirrors branding.py. */
--fv-bg:#111720;--fv-canvas:#161e29;--fv-card:#1a222e;--fv-raised:#212a37;--fv-hover:#2a3341;
--fv-border:#2a3443;--fv-sheen:#35404e;
diff --git a/web/updates.css b/web/updates.css
index 4f68ae8..d3c2f00 100644
--- a/web/updates.css
+++ b/web/updates.css
@@ -10,3 +10,9 @@
@keyframes fv-update-spin{to{transform:rotate(360deg)}}
.fv-update-notice :focus-visible{outline:2px solid var(--fv-accent);outline-offset:2px}.fv-view-navigation>.fv-update-notice{margin-top:8px;max-width:560px}
@media(prefers-reduced-motion:reduce){.fv-update-notice{animation:none}.fv-update-working>span::before{animation:none}}
+.fv-update-summary{flex-basis:100%;font-weight:400;color:var(--fv-muted);overflow-wrap:anywhere}.fv-update-summary[hidden]{display:none}
+.fv-version-info{font:inherit;font-size:12px;color:var(--fv-muted);background:transparent;border:0;border-radius:6px;padding:6px 10px;cursor:pointer;white-space:nowrap}
+.fv-version-info:hover{background:var(--fv-hover);color:var(--fv-ink)}
+.fv-release-notes{box-sizing:border-box;width:min(580px,calc(100vw - 32px));max-height:calc(100dvh - 48px);padding:24px;border:1px solid var(--fv-border,#354152);border-radius:16px;background:var(--fv-canvas,#161e29);color:var(--fv-ink,#e7edf7);font:14px/1.7 var(--fv-font,system-ui);overflow:auto;overflow-wrap:anywhere}
+.fv-release-notes::backdrop{background:#0009}.fv-release-notes h2{margin:0 0 20px;font-size:20px}.fv-release-notes h3{font-size:16px;margin:0 0 4px}.fv-release-notes section+section{border-top:1px solid var(--fv-border,#354152);margin-top:24px;padding-top:20px}.fv-release-notes p{margin:8px 0}.fv-release-notes .fv-release-build{font-size:12px;color:var(--fv-muted,#a5b3c6)}.fv-release-notes ul{padding-left:22px}.fv-release-notes li+li{margin-top:8px}
+.fv-release-notes button{font:inherit;color:inherit;background:var(--fv-hover,#2a3341);border:0;border-radius:8px;padding:6px 18px;cursor:pointer}.fv-release-notes :focus-visible,.fv-version-info:focus-visible{outline:2px solid var(--fv-accent,#8eb8fb);outline-offset:2px}
diff --git a/web/updates.js b/web/updates.js
index ead2a86..a3f2af4 100644
--- a/web/updates.js
+++ b/web/updates.js
@@ -1,6 +1,7 @@
import { api } from '../../scripts/api.js';
const releasePage = 'https://github.com/FlashML-org/FreeVideo/releases/tag/windows-preview';
+const macReleasePage = 'https://github.com/FlashML-org/FreeVideo/releases/tag/macos-preview';
const storageKey = 'freevideo.dismissed-update';
const listeners = new Set();
// Launcher phases during which the server may disappear and come back updated.
@@ -11,7 +12,9 @@ try { dismissed = sessionStorage.getItem(storageKey); } catch { /* Session memor
// The launcher passes its language in the first address, which ComfyUI later
// rewrites; keep it when reloading into an updated engine.
const languageHint = (() => { try { return new URLSearchParams(location.search).get('freevideo_lang'); } catch { return null; } })();
-const identity = candidate => candidate ? String(candidate.version || '') : '';
+const identity = candidate => candidate ? [candidate.version, candidate.revision, candidate.built_at].join(':') : '';
+const displayVersion = release => release?.product_version ? 'v' + release.product_version : release?.version || '—';
+const localizedNotes = (release, cn) => release?.release_notes?.[cn ? 'zh' : 'en'];
const publish = () => { for (const render of listeners) render(); };
const later = ms => { clearTimeout(timer); timer = setTimeout(checkUpdates, ms); };
@@ -90,6 +93,11 @@ export function createUpdateNotice(cn) {
const element = document.createElement('aside'); element.className = 'fv-update-notice';
element.hidden = true; element.setAttribute('role', 'status');
const label = document.createElement('span');
+ const summary = document.createElement('small'); summary.className = 'fv-update-summary';
+ const details = document.createElement('button'); details.type = 'button';
+ details.textContent = t("What's new", '更新内容');
+ let closeNotes = () => {};
+ details.onclick = () => { closeNotes(); closeNotes = showReleaseNotes(cn); };
const apply = document.createElement('button'); apply.type = 'button'; apply.className = 'fv-update-apply';
apply.textContent = t('Update now', '立即更新');
apply.title = t('FreeVideo restarts once; running videos finish first.', 'FreeVideo 会重启一次,正在生成的视频会先完成。');
@@ -109,9 +117,14 @@ export function createUpdateNotice(cn) {
const stop = document.createElement('button'); stop.type = 'button';
stop.textContent = t('Cancel update', '取消更新');
stop.onclick = () => { stop.disabled = true; void cancelUpdate().finally(() => { stop.disabled = false; }); };
- element.append(label, apply, link, dismiss, stop);
+ element.append(label, details, apply, link, dismiss, stop, summary);
const render = () => {
const launcher = value?.launcher, phase = launcher?.phase || '', candidate = value?.available;
+ const mac = value?.channel === 'macos-preview';
+ link.href = mac ? macReleasePage : releasePage;
+ link.title = mac
+ ? t('After your task finishes, open the new FreeVideo.app to update.', '当前任务完成后,打开新版 FreeVideo.app 更新。')
+ : t('After your task finishes, open the new FreeVideo.exe to update.', '当前任务完成后,打开新版 FreeVideo.exe 更新。');
const progress = launcher?.progress, percent = progress?.total ? ' ' + Math.floor(100 * progress.done / progress.total) + '%' : '';
const busy = updating && (working.has(phase) || offline);
let text = '', actions = false;
@@ -127,13 +140,16 @@ export function createUpdateNotice(cn) {
text = t('Open the FreeVideo launcher to update, or download the new version.', '请在 FreeVideo 启动器中更新,或下载新版。');
actions = true;
} else if (candidate && dismissed !== identity(candidate)) {
- text = t('FreeVideo update available', 'FreeVideo 有新版本') + ' · ' + candidate.version;
+ text = t('FreeVideo update available', 'FreeVideo 有新版本') + ' · ' + displayVersion(candidate);
if (launcher?.status === 'error' && launcher.error) text += ' · ' + t('last attempt failed', '上次更新未完成');
actions = true;
}
element.hidden = !text;
element.classList.toggle('fv-update-working', busy);
label.textContent = text;
+ summary.textContent = actions ? localizedNotes(candidate, cn)?.summary || '' : '';
+ summary.hidden = !summary.textContent;
+ details.hidden = !actions;
const direct = !!launcher && !launcher.manual && !failure;
apply.hidden = !actions || !direct;
link.hidden = !actions || direct;
@@ -141,5 +157,55 @@ export function createUpdateNotice(cn) {
stop.hidden = !(busy && phase === 'waiting' && !offline);
};
listeners.add(render); render();
- return {element, dispose: () => listeners.delete(render)};
+ return {element, dispose: () => { listeners.delete(render); closeNotes(); }};
+}
+
+function showReleaseNotes(cn) {
+ const t = (en, zh) => cn ? zh : en;
+ const dialog = document.createElement('dialog'); dialog.className = 'fv-release-notes';
+ const title = document.createElement('h2'); title.textContent = t('Version & release notes', '版本与更新说明');
+ dialog.setAttribute('aria-label', title.textContent);
+ const body = document.createElement('div'); body.className = 'fv-release-body';
+ const close = document.createElement('button'); close.type = 'button'; close.autofocus = true;
+ close.textContent = t('Close', '关闭'); close.onclick = () => dialog.close();
+ dialog.append(title, body, close);
+ const render = () => {
+ body.replaceChildren();
+ for (const [label, release] of [[t('Available update', '可用更新'), value?.available],
+ [t('Current version', '当前版本'), value?.current_release || (value?.current_version ? {version: value.current_version} : null)]]) {
+ if (!release) continue;
+ const section = document.createElement('section'), heading = document.createElement('h3');
+ heading.textContent = label + ' · ' + displayVersion(release); section.append(heading);
+ const build = document.createElement('p'); build.className = 'fv-release-build';
+ build.textContent = release.development ? t('Development version', '开发版本') : t('Build: ', '构建号:') + (release.version || '—');
+ section.append(build);
+ const notes = localizedNotes(release, cn), summary = document.createElement('p');
+ summary.textContent = notes?.summary || t('No release notes were included with this version.', '此版本未附带更新说明。'); section.append(summary);
+ const list = document.createElement('ul');
+ for (const item of notes?.changes || []) {
+ const row = document.createElement('li'); row.textContent = item; list.append(row);
+ }
+ section.append(list); body.append(section);
+ }
+ if (!body.childElementCount) body.textContent = t('Version information is not available yet.', '暂时无法获取版本信息。');
+ };
+ const dispose = () => { listeners.delete(render); dialog.remove(); };
+ dialog.addEventListener('close', dispose, {once: true});
+ // Keep Escape local to this sheet; the creative workspace stays open.
+ dialog.addEventListener('keydown', event => event.stopPropagation());
+ listeners.add(render); render(); document.body.append(dialog); dialog.showModal();
+ return () => { if (dialog.open) dialog.close(); dispose(); };
+}
+
+export function createVersionInfo(cn) {
+ const element = document.createElement('button'); element.type = 'button'; element.className = 'fv-version-info';
+ element.title = cn ? '版本与更新说明' : 'Version & release notes'; element.setAttribute('aria-label', element.title);
+ let closeNotes = () => {};
+ element.onclick = () => { closeNotes(); closeNotes = showReleaseNotes(cn); };
+ const render = () => {
+ const current = value?.current_release || (value?.current_version ? {version: value.current_version} : null);
+ element.textContent = current ? displayVersion(current) : cn ? '版本' : 'Version';
+ };
+ listeners.add(render); render();
+ return {element, dispose: () => { listeners.delete(render); closeNotes(); }};
}
diff --git a/web/view_navigation.js b/web/view_navigation.js
index d425e4e..3a05ae8 100644
--- a/web/view_navigation.js
+++ b/web/view_navigation.js
@@ -1,7 +1,7 @@
import { app } from '../../scripts/app.js';
import { openSetup } from './setup.js';
import { wordmark } from './branding.js';
-import { createUpdateNotice } from './updates.js';
+import { createUpdateNotice, createVersionInfo } from './updates.js';
const languageOverride = typeof location !== 'undefined'
? new URLSearchParams(location.search).get('freevideo_lang') : null;
@@ -60,7 +60,7 @@ export function installNavigation(openStudio) {
};
const settings = document.createElement('button'); settings.type = 'button';
settings.textContent = t('Settings', '设置'); settings.className = 'fv-view-settings'; settings.onclick = openSetup;
- row.append(brand, viewSwitch('nodes', choose, () => {}), settings); toolbar.append(row);
+ row.append(brand, viewSwitch('nodes', choose, () => {}), createVersionInfo(cn).element, settings); toolbar.append(row);
let shown = false;
try { shown = localStorage.getItem('freevideo.view-guide') === '1'; } catch { /* Show once this session. */ }
if (!shown) {