# Hy-Nomas MLX 0.1.0 — Apple Silicon research preview

Run Tencent's Hy-Nomas locally on an Apple Silicon Mac with the exact optimized
MLX inference core used in the Lint Labs demonstration. This download contains
source code and setup tools. Setup downloads about **27.14 GB of model weights**
directly from pinned Hugging Face revisions; the ZIP does not contain weights.

This is offline video generation, not a real-time game engine. A three-second
video takes minutes to generate. The optional camera test queues W/D inputs in
advance; live keyboard-to-frame interaction is not implemented.

## Before you start

- **Apple Silicon Mac** running **macOS 15 or newer**. Use native ARM64 Terminal
  and Python, not an Intel Python under Rosetta.
- **16 GB unified memory** is the smallest tested configuration for the default
  three-second clip (M4 Mac Mini). Close other large applications and generate
  one job at a time. We have not tested every M-series Mac or longer runs on 16 GB.
- **60 GB free disk space recommended** for weights, the Python environment,
  download/cache overhead and outputs. The four weight files alone total
  27,138,102,551 bytes (27.14 GB / 25.28 GiB).
- **Python 3.12**, an internet connection for setup, and time for a large download.
  If you use [Homebrew](https://brew.sh), install the tools with
  `brew install python@3.12 ffmpeg`. FFmpeg/FFprobe on PATH are required only for
  the optional camera harness; normal generation uses ImageIO's bundled encoder.
- Read [LICENSING.md](LICENSING.md). This is a **research/evaluation preview**:
  PixelUMM decoder weights have a noncommercial notice. The source-code license
  does not grant unrestricted commercial rights to every downloaded component.

## Install and make your first clip

Download `hynomas-mlx-0.1.0.zip` from [the download and running page](https://lintlabs.org/nomas/run),
then open Terminal. These commands assume the ZIP is in your Downloads folder:

```sh
cd ~/Downloads
unzip hynomas-mlx-0.1.0.zip
cd hynomas-mlx-0.1.0
./setup.sh
./run.sh --prompts-file prompts/fox-quality.json --output outputs/fox.mp4
open outputs/fox.mp4
```

If macOS Finder already expanded the ZIP, skip the `unzip` line. Setup checks the
platform, creates a local `.venv`, installs the pinned package versions, downloads
the original weights, and verifies all four weight SHA256 checksums. Downloads
can be resumed by running `./setup.sh` again. Setup does not change system memory
limits, install a service, configure a tunnel, or require a password.

Wait for `Video:` in Terminal before opening the result. Progress is printed for
text encoding, diffusion layers/steps, then decoding. The default clip is
**1280 × 704, 72 frames, 24 fps, eight denoising steps, seed 42**. Playback frame
rate is unrelated to generation speed. Keep the Mac awake while it works:

```sh
caffeinate -i ./run.sh --prompts-file prompts/fox-quality.json --output outputs/fox.mp4
```

After setup, generation runs locally. The built-in prompts and tokenizer/model
files are on disk. No account, API key or Lint Labs backend is needed.

## Your own prompt

```sh
./run.sh --prompt "A red fox exploring a snowy pine forest" --output outputs/snow.mp4
```

Structured prompts provide separate appearance, framing and timed-action fields.
Start by editing a copy of `prompts/fox-quality.json`. For the tested five-second
duration, use its matching fixture so action timestamps remain aligned:

```sh
./run.sh --frames 120 --prompts-file prompts/fox-quality-5s.json --output outputs/fox-5s.mp4
```

The five-second configuration was tested on a 96 GB M3 Ultra Studio. Do not assume
longer clips or multiple segments have the same memory requirement as the default.
Use `./run.sh --help` for options. Lowering steps/resolution changes the tested
quality settings. Additional 4-bit conversion is not part of this release path.

## Measured speed and quality

| Hardware | Output | Measured end-to-end time |
| --- | --- | --- |
| M4 Mac Mini, 16 GB | 3 s / 72 frames | 19 min 51.41 s |
| M3 Ultra Mac Studio, 60 GPU cores, 96 GB | 3 s / 72 frames | 4 min 17.39 s |
| M3 Ultra Mac Studio, 60 GPU cores, 96 GB | 5 s / 120 frames | 7 min 57.01 s |

The matched three-second runs used the same cached text, prompt, original weights,
resolution, eight steps and seed, with fresh diffusion and decoding. The Studio
was 4.63× faster. First-time/new-prompt encoding, other workloads and hardware can
change these times. The five-second run included fresh text encoding and is a
separate duration test. A separate public Mini job with a different prompt took
23 min 34.82 s including fresh encoding.

The optimized Mini output matched its unoptimized reference MP4 byte for byte.
Between Mini and Studio, the latents and all 18 saved pre-encoding PNG samples
matched byte for byte; compressed MP4 encodings differed slightly. These checks
do not guarantee perfect anatomy or prompt following. Our fox samples still have
synthetic fur/paw artifacts, and some requested actions/directions were missed.

## Optional: planned W → D camera and prompt continuation

Use a Mac with ample memory; **32 GB or more is a headroom recommendation**, not
a verified minimum. This test was measured on the **96 GB Studio**. Its peak MLX
diffusion allocation was **17.84 GB**, before allowing for the OS and other apps,
which exceeds the Mini's 16 GB physical memory.

```sh
brew install ffmpeg
ffmpeg -version
ffprobe -version
.venv/bin/python -m pip install --no-deps -r experiments/camera_demo/requirements-camera.txt
.venv/bin/python experiments/camera_demo/run_demo.py --plan-only --label wasd-plan
.venv/bin/python -u experiments/camera_demo/run_demo.py --frames 72 --keys w,d --label wasd-text-continuation
```

The packaged harness checks for FFmpeg and FFprobe before starting generation.
`--plan-only` still works without these media tools. The six-second run retains
world history across two three-second segments.
It supplies real camera matrices, holds W in the first segment, then D with a
new text instruction. It took **10 min 41.50 s**, including decode and media
validation. Output is `outputs/camera-demo/<label>-<UTC>/interactive-demo.mp4`;
the adjacent timeline, camera archives, logs and metrics record what was supplied.

The scene remained coherent, but the fox did not follow the second instruction to
stop and look at the observer. A distinct D-controlled glide was not established
visually. Text and camera conditions were changed together, so this one experiment
does not isolate camera causality. There is no live key listener, and the final
video is decoded after generation. See the harness README for details.

## Files, checks and troubleshooting

- Models: `models/source/` and `models/text-quality/`.
- Videos: the path passed to `--output`.
- Run settings, latent intermediates, timing and review frames: `outputs/runs/`.
- Cached text: `outputs/text_cache/`.
- Package files and original core checksum: `release-manifest.json`.
- Weight revisions, direct official URLs, byte sizes and SHA256: `models-manifest.json`.

Verify the downloaded package before setup, without importing MLX:

```sh
python3.12 scripts/verify_release.py --source-only
```

Verify all installed weight bytes (reads 27 GB from disk):

```sh
.venv/bin/python scripts/verify_release.py --weights
```

Optional regression tests after setup:

```sh
.venv/bin/python -m unittest discover -s tests -v
```

If `python3.12` is missing, install native Python 3.12 and open a new Terminal.
If installation reports a different Python version or x86_64, use an ARM64
Python 3.12 environment. If download fails, rerun setup; do not rename partially
downloaded files. If a checksum fails, remove only the named failed model file
and run setup again. Never bypass the checksum to reuse a different model revision.

On memory pressure, close other large apps and return to the default 72-frame
single-segment setting. Do not raise the system GPU memory limit to copy a
benchmark. Cancel a foreground run with Ctrl-C. Completed stages may be reused
when you repeat the exact command; pass `--force` when timing a fresh generation.
Keep outputs you need before removing their run folders to reclaim disk space.

## What was optimized

The architecture and source generation weights are unchanged: released INT8 DiT
weights with FP32 scales, mixed FP8/BF16 PixelUMM weights, and 8-bit MLX Qwen text
conditioning. The implementation uses bounded native Safetensors loading, fused
Metal weight reconstruction, compiled BF16 elementwise operations, and larger
attention work where masks are proved redundant. Stages run in separate processes
to release memory between text encoding, diffusion and decoding. See `NOTICE`
for attribution and modification provenance.

The exact inference core SHA256 is
`a7547b62853d8d737d5419b1078281bc9867fc28c75c26400dc8b83800105cfa`
(SHA256 of concatenated `hynomas_mlx/*.py` bytes, sorted by filename).

This independent Apple Silicon port is not an official Tencent, NVIDIA or Apple
release and is not endorsed by those projects.