Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.
Python ai-filmmakingai-videoai-video-generatorapple-siliconhailuoimage-to-videolip-synclocal-ailora-trainingltx-2ltx-2-5ltx-videomacosminimax-h3mlxmusic-generationoffline-aipinokiotext-to-videovideo-generation
feat(train): letterbox crop strategy — preserve wide-shot proportions
mrbizarro7a46b96a4c56
diff --git a/lora_lab/train_character.py b/lora_lab/train_character.pyindex 1a1bc9f..0a71225 100644--- a/lora_lab/train_character.py+++ b/lora_lab/train_character.py@@ -267,8 +267,30 @@ def crop_and_caption(trigger: str,caption_strategy: str,resolution: int,+ crop_strategy: str = "center",) -> tuple[list[Path], list[str]]:- """Center-crop sources to `resolution`x`resolution`, rename sequentially, write captions.+ """Scale + (optionally) crop sources to a `resolution`x`resolution` square,+ rename sequentially, write captions.++ `crop_strategy` ∈ {"center", "letterbox"} controls how non-square sources+ fit into the square training canvas:++ "center" (default, legacy behavior):+ Scale so the SHORTER source dim = target, then center-crop the+ longer dim to target. Image fills the square; content on the+ longer dim is clipped. Good for character close-ups where the+ face is centered. Bad for wide shots — long-shot proportions are+ never seen by the model, which is why generated long shots tend+ to look mushy / wrong-scale.++ "letterbox":+ Scale so the LONGER source dim = target, then pad the shorter+ dim with black to fill the square. Image content keeps its+ native aspect ratio inside the square. Model learns to ignore+ the consistent black bars (they're a constant factor across+ training samples). Trade-off: ~30% pixel-budget waste on bars+ for portraits/landscapes, but generated long shots / wide+ shots reproduce real proportions.Returns (renamed_image_paths, caption_strings) in matching order.@@ -283,7 +305,13 @@ def crop_and_caption(captions_dir.mkdir(parents=True, exist_ok=True)images_renamed_dir.mkdir(parents=True, exist_ok=True)- emit("crop_start", total=len(source_files))+ if crop_strategy not in ("center", "letterbox"):+ raise ValueError(+ f"unknown crop_strategy: {crop_strategy!r} "+ f"(want 'center' or 'letterbox')"+ )++ emit("crop_start", total=len(source_files), crop_strategy=crop_strategy)out_paths: list[Path] = []out_captions: list[str] = []@@ -292,21 +320,40 @@ def crop_and_caption(try:img = Image.open(src).convert("RGB")src_w, src_h = img.size-- # Scale-and-center-crop to a SQUARE at `resolution`. Mirrors the- # logic in preprocess_images._load_image_as_1frame_tensor (square- # crop is the right call for char training — the preprocessor will- # re-crop to whatever target_h/target_w is configured downstream;- # we keep this square + lossless so the same source can be reused- # for any preset).target = resolution- scale = max(target / src_w, target / src_h)- new_w = int(round(src_w * scale))- new_h = int(round(src_h * scale))- scaled = img.resize((new_w, new_h), Image.LANCZOS)- left = (new_w - target) // 2- top = (new_h - target) // 2- cropped_full = scaled.crop((left, top, left + target, top + target))++ if crop_strategy == "letterbox":+ # Scale so the LONGER source dim = target. Pad the shorter+ # dim with black bars to fill the square. Trainer sees a+ # uniform (target × target) canvas across all samples —+ # preprocess + dataloader unchanged — but each image+ # retains its native aspect ratio. Model learns the bars+ # as a constant feature (they're identical across every+ # training sample) and the actual subject geometry stays+ # uncompressed.+ scale = min(target / src_w, target / src_h)+ new_w = int(round(src_w * scale))+ new_h = int(round(src_h * scale))+ scaled = img.resize((new_w, new_h), Image.LANCZOS)+ cropped_full = Image.new("RGB", (target, target), (0, 0, 0))+ paste_x = (target - new_w) // 2+ paste_y = (target - new_h) // 2+ cropped_full.paste(scaled, (paste_x, paste_y))+ else:+ # "center" — scale-and-center-crop to a SQUARE at+ # `resolution`. Mirrors the logic in preprocess_images.+ # _load_image_as_1frame_tensor (square crop is the right+ # call for character training — the preprocessor will+ # re-crop to whatever target_h/target_w is configured+ # downstream; we keep this square + lossless so the same+ # source can be reused for any preset).+ scale = max(target / src_w, target / src_h)+ new_w = int(round(src_w * scale))+ new_h = int(round(src_h * scale))+ scaled = img.resize((new_w, new_h), Image.LANCZOS)+ left = (new_w - target) // 2+ top = (new_h - target) // 2+ cropped_full = scaled.crop((left, top, left + target, top + target))stem = f"char_{i:03d}"png_path = images_renamed_dir / f"{stem}.png"@@ -660,12 +707,13 @@ def run_pipeline(spec_path: Path) -> int:)crop_strategy = advanced.get("crop_strategy") or "center"- if crop_strategy != "center":+ if crop_strategy not in ("center", "letterbox"):emit("warning",stage="crop",message=f"crop_strategy={crop_strategy!r} not implemented; using center",)+ crop_strategy = "center"# Validate resolution.resolution = int(cfg["resolution"])@@ -715,6 +763,7 @@ def run_pipeline(spec_path: Path) -> int:trigger=trigger,caption_strategy=caption_strategy,resolution=resolution,+ crop_strategy=crop_strategy,)except Exception as exc: # noqa: BLE001traceback.print_exc(file=sys.stderr)diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex a95cf1c..b788136 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -4123,6 +4123,22 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,resolution = _int_or("resolution", cfg["resolution"])caption_strategy = (f("caption_strategy", "trigger_simple")or "trigger_simple").lower()+ # Crop strategy for the training preprocess.+ # "center" — current behavior, scale + center-crop to a square.+ # Best for tightly-framed character close-ups; biases+ # the model toward those framings.+ # "letterbox" — preserve native aspect, pad with black bars to a+ # square. Captures wide-shot / long-shot proportions+ # the center-crop path destroys, at the cost of+ # ~30% pixel-budget waste on bars for non-square+ # sources. Salo flagged 2026-05-17: medium-long+ # shots from center-crop-trained LoRAs come out+ # blurry because the model never saw those+ # proportions during training.+ crop_strategy = (f("crop_strategy", "center")+ or "center").lower()+ if crop_strategy not in ("center", "letterbox"):+ crop_strategy = "center"eta_sec = _train_estimate_seconds(preset, image_count,steps_override=steps,is_style=is_style)@@ -4169,6 +4185,7 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,"lr": lr,"resolution": resolution,"caption_strategy": caption_strategy,+ "crop_strategy": crop_strategy,"image_count": image_count,"eta_sec": eta_sec,"ram_peak_gb": cfg["ram_peak_gb"],@@ -4990,6 +5007,7 @@ def run_train_job_inner(job: dict) -> None:"lr": p.get("lr"),"resolution": p.get("resolution"),"caption_strategy": caption_strategy,+ "crop_strategy": p.get("crop_strategy", "center"),"images_dir": str(images_dir),"captions_dir": str(captions_dir),"checkpoints_dir": str(dataset_dir / "checkpoints"),@@ -16763,6 +16781,29 @@ HTML = r"""<!doctype html><button type="button" class="pill-btn" data-train-preset="high"><span>High</span><span class="sub" id="trainPresetHighSub">~2 h 50 min · rank 32 · 5000 steps · 512px</span></button></div>+ <!-- Crop strategy — primary control (not buried in Advanced) because+ it has a big visible effect on what the model learns. Salo 2026-05-17:+ "we are using such a limited cropping of the images, all the images+ are kind of close-up medium close-ups. That's the reason why the+ medium long shots are so shit and blurry." Letterbox preserves+ wide-shot proportions at the cost of pixel-budget waste on black+ bars. The trainer sees a uniform square canvas either way, so+ this doesn't change wall time or memory. -->+ <h2 style="margin-top:14px">Crop strategy+ <span class="h2-hint">how non-square images fit the training canvas</span>+ </h2>+ <div class="pill-group cols-2" id="trainCropStrategyGroup">+ <button type="button" class="pill-btn active" data-train-crop="center">+ <span>Center crop</span>+ <span class="sub">scale + crop to square · best for tight portraits</span>+ </button>+ <button type="button" class="pill-btn" data-train-crop="letterbox">+ <span>Letterbox <span class="rec-badge" style="background:rgba(94,234,255,0.18);color:var(--accent-bright)">Preserve aspect</span></span>+ <span class="sub">pad with black · keeps wide-shot proportions</span>+ </button>+ </div>+ <input type="hidden" name="crop_strategy" id="trainCropStrategy" value="center">+<details class="train-advanced"><summary>Advanced</summary><div class="train-advanced-grid">@@ -19125,6 +19166,19 @@ function trainWirePresetButtons() {trainUpdateEstimate();});});+ // Crop strategy pills — same click pattern. Updates the hidden+ // #trainCropStrategy input which rides the form on submit. No estimate+ // change because letterbox uses the same square canvas as center crop;+ // wall time + memory are unaffected.+ document.querySelectorAll('#trainCropStrategyGroup .pill-btn').forEach(b => {+ b.addEventListener('click', () => {+ const v = b.dataset.trainCrop;+ const inp = document.getElementById('trainCropStrategy');+ if (inp) inp.value = v;+ document.querySelectorAll('#trainCropStrategyGroup .pill-btn').forEach(x =>+ x.classList.toggle('active', x === b));+ });+ });}function trainWireAdvancedFields() {@@ -19622,6 +19676,9 @@ async function trainStart() {fd.set('preset', TRAIN.preset);fd.set('image_count', String(TRAIN.images.length));fd.set('caption_strategy', captionStrategy);+ // Crop strategy chip — center (default) or letterbox.+ const cropInp = document.getElementById('trainCropStrategy');+ if (cropInp && cropInp.value) fd.set('crop_strategy', cropInp.value);const rank = document.getElementById('trainRank').value;if (rank) fd.set('rank', rank);const stepsVal = document.getElementById('trainSteps').value;