gaea-plugin-ltx

Lightricks' LTX 2.5 distilled as a Gaea plugin: video with sound, on MES Video 0.1's video.generate, video.extend and video.retake. It is built on GaeaPluginKit over ltx-2-mlx-swift (MLXLTX25Package), runs in its own process, and speaks the Gaea Plugin Protocol v1. Add it to Gaea by its repo URL:

gaea plugins add https://github.com/xocialize-code/gaea-plugin-ltx

The licence

LTX 2.5's weights are under the LTX-2 Community License. Its use restrictions bind everyone who uses the model, an entity with US$10 million or more in annual revenue needs a commercial licence from Lightricks, and what it makes must not be presented without saying it is machine-generated.

• The operator accepts it by enabling each tier: the offers say accepted_required, so Gaea lists them off until gaea models enable ltx-2.5-<tier> (or the switch in Gaea's models list).
• Each user accepts it through their client: the offers say user_accept_required, so a job runs only when its policy.accepted lists LicenseRef-LTX-2-Community. Otherwise it is 422 policy_unmet with reason terms_not_accepted.
• Disclosure. Gaea writes AI-generated by LTX 2.5 (<tier>) into every clip's comment item, or AI-generated in part by … after a source's own comment for extend and retake (Video §1.9).

What it offers

One model per tier, each with one lane, so a client sees what each tier can do (VIDEO-EVALUATION §6.1):

Model	quality	Size (from a first frame or a clip)	Frames	Stages	DiT
ltx-2.5-compact24	draft	704×512 (512×288)	121	one	int8, streamed; int8 text encoder
ltx-2.5-balanced32	draft, standard	576×320	161	one	int8, streamed; int8 text encoder
ltx-2.5-standard64	standard, best	1280×704	161	two	int8, streamed
ltx-2.5-max128	best	1920×1088	481	two	bf16, streamed

With no model named, a request runs on the first tier, in that order, whose gates and limits admit it and that lists its quality. A request for a last frame, say, goes to standard64.

• video.generate makes a clip with 48 kHz stereo sound from a prompt.
  • Every tier takes a first frame.
  • Two-stage tiers also take a last frame, up to 5 keyframes at times (keyframe_times), and a soundtrack. The clip follows the soundtrack, which is its sound, unchanged; without duration_s the clip is the soundtrack's length.
  • Defaults: LTX's own, 704×512 (within the tier), 9 frames at 24 fps.
• video.extend adds after_s (default 1 s) after a clip, in whole 8-frame steps. The model reworks the last 0.5 s of the source so the join is seamless (overlap_s).
• video.retake makes a span of a clip again: picture, sound or both (the default when the clip has sound). The span widens to the model's latent frames (frame 0, then eight at a time), with span_snapped.
• Kept frames. LTX decodes the whole clip, so the frames an edit holds come back close to the source, not as they were. Gaea puts the source's own frames back outside a retake's span and before an extend's last 0.5 s.
• Grids. LTX makes 8k + 1 frames (frame_step), on a 32-pixel grid (64 on two-stage tiers, size_step).
  • Generating, the plugin snaps a request to the nearest value within the tier and warns duration_snapped, size_snapped or keyframe_moved. A value past the tier is 422 out_of_limits.
  • Editing keeps the clip's size and frames, so a clip off the grid (24 frames, or 120 pixels wide) is 422 input_invalid.
• Seeds. max128 (bf16) gives identical frames for a seed (deterministic: true). The int8 tiers declare false: two processes given the same seed often agree byte for byte, but not always. Generating, they differ by 32–50 dB on every frame when they don't; an extend or retake drifts further, to about 28 dB by its last frames. A job without a seed gets one, reported in effective.seed.
• Memory. Each tier keeps to the package's measured pixel-frame ceiling (width × height × frames): compact24 makes 704×512 for 49 frames or 512×288 for 121, balanced32 576×320 for 161, standard64 1280×704 for 161, and max128 1920×1088 for 481. A request past it is 422 out_of_limits.
• audio: false gives a silent clip: Gaea leaves the track out.
• Not yet: LoRAs and IC-LoRAs (they wait on typed adapters in MLXToolKit, AB-A-0197), extending before a clip, and prompt enhancement (prompt_enhance: on warns prompt_enhance_ignored).

Weights and memory

The tiers share LTX 2.5's components and its granule tree, which the DiT streams from:

Repo	Size	Tiers
mlx-community/ltx-2.5-mlx	67 GB	standard64, max128 (bf16 encoder and VAEs)
mlx-community/ltx-2.5-mlx-q8	24.6 GB	compact24, balanced32 (int8 encoder, lean decoder)
xocialize/ltx-2.5-granules	q8/ and bf16/	every tier

The engine fetches what a tier's prepare finds missing into Gaea's models root. The package's measured peaks (AB-R-0106) are about 15 GB on compact24, 17 GB on balanced32, 19–34 GB on standard64, and 74 GB on max128 at 1080p × 481 frames. max128's bf16 lane needs a volume that reads at least 1 GB/s.

Build and check locally

scripts/build-plugin.sh

scripts/check-plugin.sh

check-plugin.sh generates a 256×256, 9-frame clip on max128 over GPP on the signed bundle, with every .build folder hidden. It then shows that the bare worker, outside the bundle, finds no metallib. Its weights come from CHECK_MODELS_ROOT (DEV_VOL1's models folder by default).

scripts/release.sh builds, checks, notarizes with the fleet's mlx-notary profile, and publishes the GitHub release. The release workflow does the same in CI when a v<version> tag is pushed.

ltx-inproc (its header lists the options) is not part of the plugin. It runs a tier in-process through MLXServeEngine, with the request the worker builds: the reference Gaea's runs are compared against.

scripts/golden.sh <out-dir>

golden.sh runs each case over GPP on the signed bundle and through ltx-inproc at seed 7. Each pair must be at the reported size and frame count, with 48 kHz stereo sound. On max128 the pair must decode to the same frames, byte for byte (ffmpeg's framemd5); on the int8 tiers, the same frames or every frame within 25 dB. The cases:

• a 256×256, 9-frame clip on each tier;
• a first frame on compact24, and a first and last frame on standard64;
• extend and retake of Tests/Fixtures/clip.mp4 (128×96, 17 frames, with sound) on compact24.

The kite frames in Tests/Fixtures were made by LTX 2.5 itself.

CI secrets

The release workflow signs with Developer ID and notarizes. It reads four organization secrets on xocialize-code: DEVELOPER_ID_P12_BASE64, DEVELOPER_ID_P12_PASSWORD, NOTARY_APPLE_ID and NOTARY_APP_PASSWORD (Gaea's Docs/Signing secrets.md).

Licence

The plugin is Apache-2.0 (Gaea G-21), and so is the port, ltx-2-mlx-swift. LTX 2.5's weights are under the LTX-2 Community License (Lightricks).