Add M5 benchmark handoff

HANDOFF.md

@@ -0,0 +1,124 @@
+# Handoff: benchmark FastH3 Omni (MLX) on an Apple M5 Mac Studio
+
+You are an agent on an Apple M5 Mac Studio. Your job is to **install, build the model, run one fixed benchmark, and post the results, videos included**.
+
+**Rules for code changes:**
+- You MAY fix small, clear bugs that block the run. Examples: a crash, a wrong path, a flag typo, an install or dependency problem, an mlx API difference on newer mlx.
+- Keep each fix minimal and commit it on a branch. Step 7 covers how. Describe every fix in your report.
+- You must NOT change what is measured. That means no performance tuning, no changes to prompts, seeds, resolution, frame count, steps or decoder, and no lossy shortcuts.
+- If a fix would need more than a few lines, or touches model math, stop, record the error and logs, and report instead.
+
+## What is being measured
+FastH3 Omni is a reference-conditioned video+audio model that runs through FastVideo's native MLX runtime. Measure end-to-end time per clip for **5 s clips (124 frames) at 480p (832x480) with the 36-layer decoder**. Run five reference compositions (`image`, `image-voice`, `images3`, `clip`, `video`) with the same prompts, references and seeds as our DGX Spark benchmark. Each composition gets one excluded warmup (seed 42), then measured seeds 0, 1 and 2.
+
+## 0. Prerequisites (about 5 min)
+- Plug in power. Close other GPU-heavy apps. Keep the Mac awake for the whole run: prefix long commands with `caffeinate -dims`.
+- Free disk: about 130 GB (about 95 GB of downloaded sources, which are deleted after the build, plus about 35 GB of model).
+- Install tools:
+  ```bash
+  brew install ffmpeg uv git
+  uv tool install "huggingface_hub[cli]"   # provides `hf`; optional: `hf auth login`
+  ```
+- Copy the input bundle you received, `omniref-handoff-inputs.tar.gz` (24.6 MB), to the home folder, then:
+  ```bash
+  cd ~ && shasum -a 256 omniref-handoff-inputs.tar.gz
+  # expect 2372442d7350d2c721b9b6ded7546199cf90558c4e135d1f6da9bcc27933b19b
+  tar -xzf omniref-handoff-inputs.tar.gz      # creates ~/omniref-handoff
+  ```
+
+## 1. Code (pinned commit)
+```bash
+mkdir -p ~/fasth3-mlx && cd ~/fasth3-mlx
+git clone https://github.com/aryan5v/FastVideo.git && cd FastVideo
+git checkout c4bf423ac        # branch aryan/fasth3-omni-mlx (hao-ai-lab/FastVideo#2000)
+uv venv --python 3.12 --seed && source .venv/bin/activate
+uv pip install -e ".[mlx]"
+python -c "import mlx.core as mx; print(mx.__version__, mx.device_info())"   # record this output
+```
+mlx must be **0.32.2 or newer**. If it is older, run `uv pip install -U mlx` and record the version.
+
+## 2. Benchmark kit
+```bash
+hf download aryan5v/FastH3-Omni-MLX --local-dir ~/fasth3-mlx/kit
+```
+
+## 3. Build the model directory (the download dominates; conversion is about 5 min)
+```bash
+cd ~/fasth3-mlx/kit/bench
+caffeinate -dims bash prepare_model_dir.sh \
+  --fastvideo ~/fasth3-mlx/FastVideo \
+  --python ~/fasth3-mlx/FastVideo/.venv/bin/python \
+  --model-dir ~/fasth3-mlx/model --sources ~/fasth3-mlx/sources \
+  --formats "int6"
+```
+- The script downloads the public weights at pinned revisions, converts the INT6 transformer and the text encoder, and verifies SHA-256.
+- It is resumable: if it is interrupted, re-run the same command.
+- **Required:** it must end with the verification passing. Hash warnings on `dit/*` or the encoder `model.safetensors` are acceptable, but record them. Any other failure means stop and report.
+
+## 4. Smoke test (about 3–5 min)
+```bash
+cd ~/fasth3-mlx/kit/bench
+PY=~/fasth3-mlx/FastVideo/.venv/bin/python
+$PY run_matrix.py --self-test --data-root ~/omniref-handoff
+caffeinate -dims $PY run_matrix.py --smoke --model-dir ~/fasth3-mlx/model --data-root ~/omniref-handoff \
+  --fastvideo-root ~/fasth3-mlx/FastVideo --python $PY --out ~/fasth3-mlx/results-smoke
+```
+It must produce an MP4 with an audio stream. If it does not, stop and report.
+
+## 5. The benchmark (the main deliverable)
+```bash
+caffeinate -dims $PY run_matrix.py \
+  --model-dir ~/fasth3-mlx/model --data-root ~/omniref-handoff \
+  --fastvideo-root ~/fasth3-mlx/FastVideo --python $PY \
+  --seconds 5 --canvases 480p --decoders 36l \
+  --compositions image,image-voice,images3,clip,video \
+  --out ~/fasth3-mlx/results-480p-36l
+```
+- This is 5 cells, each with 1 warmup and 3 measured seeds, run strictly one at a time. Do not run anything else on the GPU meanwhile.
+- It is resumable: if it is interrupted, re-run the same command and finished cells are skipped. A failed cell (for example out of memory) is recorded and the matrix continues; do not retry it unless asked.
+- If time is short, add `--seeds 0` and say so in the report.
+
+## 6. Optional, only after step 5 finishes: fastest-configuration sweep
+This builds INT8 (and BF16 if the Mac has 64 GB or more) and ranks GEMM paths on one cell:
+```bash
+cd ~/fasth3-mlx/kit/bench
+caffeinate -dims bash prepare_model_dir.sh --fastvideo ~/fasth3-mlx/FastVideo --python $PY \
+  --model-dir ~/fasth3-mlx/model --sources ~/fasth3-mlx/sources --formats "int8 bf16"
+caffeinate -dims $PY run_matrix.py --m5-sweep --model-dir ~/fasth3-mlx/model --data-root ~/omniref-handoff \
+  --fastvideo-root ~/fasth3-mlx/FastVideo --python $PY --out ~/fasth3-mlx/results-m5-sweep
+```
+The INT8/BF16 conversion re-downloads the BF16 release if the sources were deleted. That is expected.
+
+## 7. Post the results (needs the owner's GitHub and Hugging Face logins on this Mac)
+The human operator should run `gh auth login` and `hf auth login` beforehand. These are interactive, and you must never handle passwords or tokens yourself. If either is missing, skip that part, and at the end tell the operator to send `SEND_BACK.tar.gz` and your report manually (AirDrop or Drive).
+
+**a. Videos and full results go to a Hugging Face dataset.** This includes every MP4, the per-request records, latency.csv, prompts, logs and the environment receipt.
+```bash
+HFUSER=$(hf auth whoami | head -1 | awk -F= '{print $NF}')   # check the printed username
+hf repo create $HFUSER/fasth3-omni-mlx-m5-results --repo-type dataset
+hf upload $HFUSER/fasth3-omni-mlx-m5-results ~/fasth3-mlx/results-480p-36l results-480p-36l --repo-type dataset
+# also upload results-smoke/ and results-m5-sweep/ the same way if they exist
+```
+Make the dataset public, or add the requester as a collaborator if the operator prefers it private.
+
+**b. Code fixes, if you made any.**
+- If GitHub is available: fork `aryan5v/FastVideo`, push your branch, then open a PR **into branch `aryan/fasth3-omni-mlx` of `aryan5v/FastVideo`**, not into hao-ai-lab:
+  ```bash
+  gh repo fork aryan5v/FastVideo --remote --remote-name mine
+  git push mine HEAD:fasth3-omni-mlx-m5-fixes
+  gh pr create --repo aryan5v/FastVideo --base aryan/fasth3-omni-mlx --head <you>:fasth3-omni-mlx-m5-fixes
+  ```
+  Give it the title `[bugfix]: fixes found running FastH3 Omni MLX on M5` and list each fix in the body.
+- If GitHub is not available, run `git format-patch c4bf423ac -o ~/fasth3-mlx/results-480p-36l/fixes/` before uploading in step 7a.
+
+**c. Results comment on the upstream draft PR** [hao-ai-lab/FastVideo#2000](https://github.com/hao-ai-lab/FastVideo/pull/2000):
+```bash
+gh pr comment 2000 --repo hao-ai-lab/FastVideo --body-file ~/fasth3-mlx/m5_report.md
+```
+Write `m5_report.md` with exactly these parts:
+1. **Hardware:** chip, GPU cores, unified memory (`sysctl -n machdep.cpu.brand_string hw.memsize`), macOS (`sw_vers`), mlx version and `mx.device_info()`.
+2. **Code:** commit `c4bf423ac`, plus any fixes (link the fix PR or patch).
+3. **Results table:** rows are the compositions; columns are mean ± SD end-to-end seconds over seeds 0/1/2, then mean denoise s, decode s, conditioning s, and peak memory GiB. Use the generated `results-480p-36l/README.md` and `per-request-records.jsonl`.
+4. **Link** to the HF dataset with the videos.
+5. **Issues:** anything that failed, was skipped (for example `--seeds 0`) or was changed. Also note the `prepare_model_dir.sh` verification summary, including any hash warnings.
+6. The `--m5-sweep` ranking (`results-m5-sweep/m5-sweep.md`), if you ran it.