Musubi Tuner Simple GUI

Experimental modern interface: this fork also includes the parallel local web workspace Musubi Studio. Run LAUNCH_MODERN_GUI.bat to try its modern configuration, dataset/TOML, monitoring, job, stage, and sample workflows. The established Tkinter interface remains available through LAUNCH_GUI.bat; no existing workflow was removed. See modern_gui/README.md for architecture and safety details.

A Windows-focused desktop GUI for kohya-ss/musubi-tuner.

Old GUI (click to expand)

This fork is no longer just a Wan 2.2 front-end. The GUI now supports multiple musubi-tuner training flows from one app:

• Wan 2.2
• Flux.2 Klein
• Flux.2 Dev
• Krea 2
• MiniMax H3 (Experimental) — still-image LoRA directly from the pruned ConvRot INT8 base
• MOSS-Image (Experimental) — image LoRA using the MOSS-Image Base model, including ComfyUI ConvRot checkpoints

It keeps the underlying musubi-tuner workflow intact, but makes setup, sampling, monitoring, continuation training, and conversion easier to manage from a single interface.

What This GUI Adds

• Modern light and dark themes
• Mode-aware forms for different model families
• Dataset, model, and output path management
• Built-in sample prompt editor with enable/disable, duplicate, and test generation support
• Sample gallery with thumbnail previews inside the app
• Live monitor with console, loss graph, VRAM usage, epoch/step counters, and next-epoch progress
• Local job history workspace for finished, failed, and stopped runs, including verified true-state recovery with preserved monitoring history
• Save/load settings and auto-restore of your last session
• LoRA conversion tools
• Accelerate setup tab for first-time installation
• Guided Differential Output Preservation (DOP) for Krea 2, experimental MiniMax H3 and MOSS-Image, and FLUX.2 Klein, including signed class-caption caches, live loss reporting, and per-stage overrides
• Dedicated Training Notes workspace with permanent custom comments plus a concise automatic summary, enabled by default for new recipes and rebuilt for each run/stage: source batch sizes, gradient accumulation, optimizer, noise schedule, precision and active experimental features are embedded in LoRA metadata. Explicit saved Off choices remain Off.

Current Workspace Layout

The app is organized into these main pages:

• Models
• Training
• Advanced
• Samples
• Monitor
• Jobs
• Convert
• Setup

The GUI adjusts required fields and available options based on the selected training mode.

Supported Modes

MOSS-Image (Experimental)

Train image LoRAs from a MOSS-Image Base checkpoint, Qwen3.5-9B text encoder, and Flux.2 VAE. Both interfaces expose caption/latent caching, image previews, block swapping, optional DOP, REPA visual guidance and depth anchoring, Automagic3, optional EMA smoothed checkpoints, and experimental staged face refinement. The DiT accepts ComfyUI ConvRot INT8 or BF16 weights; the text encoder also accepts ComfyUI W4A8 with an experimental portable decoder. Short real-model GPU smoke tests have passed, including a 1024px LoRA update. Long-run quality and memory requirements across configurations are not yet established.

Docs: MOSS-Image experimental guide

Wan 2.2

• High-noise and low-noise DiT workflows
• Timestep boundary controls
• Combined or split training setups
• Optional low-VRAM strategies such as block swap and offloading

Docs: docs/wan.md

Flux.2 Klein / Dev

• Flux.2 DiT path selection
• Qwen3 or Mistral3 text encoder input
• FP8 text encoder option
• Experimental DOP class preservation for Klein 4B/9B
• Experimental reference-guided Klein training: a frozen teacher can see either the training image itself or separate control_path images while the LoRA student learns caption-only behavior. This is the practical one-extra-pass method, not the much heavier multi-step EMA D-OPSD paper implementation.

Docs: docs/flux_2.md

Krea 2

• RAW DiT training
• Optional Turbo DiT sampling path
• Optional projector patch and patch strength
• Krea-specific timestep sampling and prompt controls
• In-app Krea test sample generation
• Experimental small-dataset generalization presets with adapter weight noise, automatic depth anchoring, and an optional faster keep-on-GPU helper mode
• Experimental DOP class preservation with caption validation and staged-training controls

Docs: docs/krea2.md

DOP guide: docs/dop.md

MiniMax H3 (Experimental)

An opt-in automatic block-memory mode is available in both GUIs. It measures complete training steps and adjusts frozen-block residency for different batch sizes; fixed swapping remains the default.

• Still-image LoRA over the frozen ~20.97 GB pruned ConvRot INT8 FL2VA checkpoint
• Does not require the ~66 GB BF16 transformer
• 24 GB-oriented safe defaults: rank 16, BF16 LoRA/backward, gradient checkpointing, and 30 H2D-only swapped blocks
• Advanced speed tuning: 15 swapped blocks completed two epochs at roughly 19–20 GB on an RTX 4090 and produced a working likeness LoRA, but has less safety margin and is not the automatic default
• FP32-policy latent caching, compact NVFP4/AWQ caption caching, scheduled training previews, and sequential standalone LoRA image inference
• H3 quality controls: proven Dynamic Sigma, Ostris's frozen assistant in both compact and native video training, native Teacher Matching, and an optional compact-only scheduled drift check
• Experimental DOP, adapter weight noise, differentiable depth anchoring, and DRaFT face refinement, disabled by default
• Focused 24 GB GPU smokes completed for previews, DOP/weight noise, depth, and the H3 DRaFT graph with the real AntelopeV2 reward; useful long-run advanced recipes remain experimental
• Three backward-compatible workflows: the proven compact still-image trainer, native video/joint-audio training, or upstream-style mixed image/video T2VA and FL2VA training
• Official multimodal workflow supports T2VA, first/last-frame FL2VA, and reference-based Ref2VA datasets; choose joint video+audio, video-only, or experimental audio-only learning without pretending missing audio is real silence
• Mixed T2VA/FL2VA accepts image and video sections in one TOML; images remain true one-frame targets, FL2VA images may use arbitrary ordered time anchors, and clips retain their configured frame counts
• Native T2VA optionally supports upstream teacher matching (endpoint or self-reference teacher), including preservation anchoring, decomposed magnitude/direction loss, and focus-band sampling; it remains disabled by default and requires a matching text-cache rebuild
• Compact still-image training keeps the proven krea2_shift default and exposes h3_shifted_uniform as an experimental full-schedule alternative for community comparison
• Modern and Classic dataset builders detect embedded/sidecar audio, create valid 24 fps H3 clips from still images plus audio, validate frame geometry, and guide Ref2VA JSONL construction (visual Ref2VA editing is in the Modern UI)
• Low-VRAM text encoding can stream up to all 50 Qwen language layers from system RAM; the GUI recommends 50 for smaller GPUs
• Real 1024x1024 rank-16 CUDA smoke completed at a 14,397 MiB physical peak; the longer two-epoch 15-block run used roughly 19–20 GB

Docs: compact still-image workflow · official video/audio workflow

Need captions for a video dataset? TagGUI Video is the companion video-captioning fork used by this project. It can prepare per-clip captions before you build the Musubi dataset TOML/JSONL.

Installation

Requirements

• Windows is the primary target
• Python 3.10, 3.11, or 3.12
• NVIDIA GPU recommended
• Enough VRAM for the model family you plan to train

This GUI is only a front-end. Model requirements and training memory use still depend on musubi-tuner and the selected backend.

Quick setup

1. Clone or download the repository.

git clone https://github.com/diodiogod/musubi-tuner_simple_GUI.git
cd musubi-tuner_simple_GUI

2. Start the interface you want. You do not need to create or activate a virtual environment manually. The launcher handles that automatically.

On Windows, double-click:

LAUNCH_MODERN_GUI.bat  (recommended browser interface)
LAUNCH_GUI.bat         (Classic desktop interface)

On Linux:

chmod +x LAUNCH_MODERN_GUI_LINUX.sh
./LAUNCH_MODERN_GUI_LINUX.sh

Manual/developer installation

Use these commands only when you deliberately want to manage the environment yourself or troubleshoot the automatic setup.

Create and activate a virtual environment:

python -m venv venv
# Windows: venv\Scripts\activate
# Linux:   source venv/bin/activate

Install PyTorch for your CUDA version. Example for CUDA 12.4:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

Install the project:

pip install -e .

Optional monitor/logging extras:

pip install matplotlib pynvml tensorboard wandb

Automatic launcher setup

Both Windows launchers use the same environment setup. On first launch they create venv, select a compatible PyTorch build, install the project dependencies, verify the environment, and then open the selected interface. Later launches perform a quick check and skip installation while the environment is healthy and pyproject.toml is unchanged. Setup details and errors are written to logs/setup.log.

Python 3.10, 3.11, or 3.12 must already be installed. To explicitly repair an environment, run venv\Scripts\python.exe tools\bootstrap_environment.py --force-repair. To reinstall PyTorch, add --refresh-torch; set MUSUBI_CUDA=cu124, cu128, cu130, cu132, or cu134 first when automatic driver detection needs to be overridden.

MOSS's optional Fizgig-style speed controls include batched Muon, BF16 LoRA compute, unpadded image passes, and compiled blocks. The compiled Inductor path uses an opt-in newer runtime: run venv\Scripts\python.exe tools\bootstrap_environment.py --performance-runtime while this trainer is closed. Existing environments are not upgraded automatically. See MOSS speed settings and runtime requirements.

Experimental Linux launcher

The browser-based Modern UI has an experimental Linux launcher. Python 3.10, 3.11, or 3.12 and the NVIDIA driver must already be installed; the launcher creates venv and installs or verifies the Python, PyTorch, and project dependencies automatically.

chmod +x LAUNCH_MODERN_GUI_LINUX.sh
./LAUNCH_MODERN_GUI_LINUX.sh

It uses venv/bin/python when present and otherwise discovers a supported python3. Set MUSUBI_PYTHON=/path/to/python to select another environment. On a headless machine it automatically avoids opening a browser. Additional server arguments are passed through, for example:

./LAUNCH_MODERN_GUI_LINUX.sh --host 127.0.0.1 --port 8675

Linux support is currently experimental. The Modern UI is the supported Linux interface; the Classic desktop GUI remains Windows-focused. Binding the server to a public interface is not recommended because it does not yet provide user authentication. Use an SSH tunnel or another authenticated proxy for remote access.

Experimental RunPod guide (untested — testers wanted)

This project has not yet been tested by the maintainer on RunPod. Treat this as a community test procedure, keep backups of datasets and outputs, and please report the Pod image, GPU, setup log, and full error when something fails.

1. Create a Pod (not a Serverless endpoint) using a current Ubuntu/PyTorch image. Choose an NVIDIA GPU appropriate for the model; MiniMax H3 training is currently aimed at 24 GB cards. Allocate enough persistent /workspace storage for the repository, model files, caches, datasets, and checkpoints. RunPod documents which data survives stops and termination in its storage guide.

2. Open the Pod terminal and clone the project inside /workspace:

   cd /workspace
   git clone https://github.com/diodiogod/musubi-tuner_Wan2.2_GUI.git
   cd musubi-tuner_Wan2.2_GUI
   chmod +x LAUNCH_MODERN_GUI_LINUX.sh
   ./LAUNCH_MODERN_GUI_LINUX.sh

   The first launch creates venv and installs the Python dependencies. It can take several minutes. If setup fails, inspect /workspace/musubi-tuner_Wan2.2_GUI/logs/setup.log.

3. For the initial experiment, keep the GUI bound to 127.0.0.1 and reach it through an SSH tunnel. In a terminal on your own computer, use the public IP and mapped SSH port shown by RunPod's Connect panel:

   ssh -L 8675:127.0.0.1:8675 root@RUNPOD_PUBLIC_IP -p RUNPOD_SSH_PORT

   Then open http://127.0.0.1:8675 locally. RunPod documents SSH and port access in its connection guide.

4. Store models, datasets, caches, and outputs under /workspace, not temporary container paths. Download completed checkpoints before terminating the Pod; ordinary volume storage survives a stop but not Pod termination.

Do not start the GUI with --host 0.0.0.0 or expose port 8675 publicly yet. The current GUI has no login system. RunPod's HTTP proxy can publish an exposed web port, and its own documentation recommends application authentication for public services: exposing HTTP ports.

When reporting a test, please include:

• RunPod image/template name and Python version
• GPU model and VRAM
• whether first-time setup completed
• logs/setup.log when installation failed
• the job log and generated command when training failed

The launcher now closes automatically when the GUI exits normally, and only stays open if startup fails or Python returns an error.

You can also launch directly:

python musubi_tuner_gui.py

Basic Workflow

1. Prepare your dataset TOML.
2. Open the GUI and choose the training mode.
3. Fill the model paths required for that mode.
4. Set output directory and output name.
5. Configure training rank, alpha, optimizer, precision, and memory settings.
6. Optionally enable latent/text recaching.
7. Add sample prompts in the Samples page.
8. Start training from the Monitor page.
9. Watch live loss, VRAM, console output, and step/epoch progress.
10. Review finished runs later in the Jobs page.

Notable Features

Krea 2 Generalization (Experimental)

The Krea 2 training page includes three starting presets:

• Off (Baseline): original Musubi training behavior
• Weight Noise Only: the safer first experiment for resisting overtraining on small datasets
• Balanced Experimental: weight noise plus a conservative depth anchor

Depth anchoring automatically estimates a depth map for each training image. During training, it checks whether Krea's predicted image has a similar 3D structure. Users do not create or supply depth maps, and Krea does not receive them as reference-image or ControlNet input—the depth model only acts as an additional training judge.

This may help preserve subject, face, body, or object shape without forcing the LoRA to reproduce the exact background, colors, or lighting. It also performs an extra VAE decode and depth-model pass, so it increases training time and VRAM use. Its best settings for Krea 2 are not yet established.

The same DOP, adapter-weight-noise, and depth-anchor controls are exposed for experimental MiniMax H3. Their H3 math and cache keys are model-specific, and all remain disabled by default. On 24 GB, test one technique at a time with the conservative swap setting; see the MiniMax H3 guide.

For a meaningful first test, compare Off, Weight Noise Only, and Balanced Experimental using the same dataset, seed, step count, and sample prompts. Start with weight-noise strength 0.0125 and depth-anchor strength 0.01. See the Krea 2 guide for implementation details, cautions, and attribution.

Krea 2 / MiniMax H3 / MOSS Face Refinement (DRaFT, Experimental)

Face Refinement is an optional staged-training step for human-identity LoRAs. It can follow standard training automatically or run by itself from an existing LoRA for one of these models. In refinement-only mode, select the source LoRA in the Face Refinement window; no dataset TOML or dummy training stage is required. Once the starting LoRA has learned the subject, the selected model generates temporary images from a varied prompt list. A frozen face-recognition model compares each generated face with embeddings prepared from your reference folder, and the similarity reward updates the LoRA through the final denoising step.

• It does not use a second dataset TOML. Settings and prompts live in the GUI/job snapshot.
• It can use the previous standard stage's LoRA or an explicitly selected existing LoRA from the active model family.
• Automatic handoff uses the previous stage's LoRA file, not its optimizer-state directory.
• Reference images establish identity but are not pixel targets during refinement.
• Review Results… shows each detected face's similarity score separately from images skipped because no complete face was visible. Flagged detections can be previewed and excluded without moving or deleting the source image.
• Optional pose-aware identity matching virtually buckets one mixed folder into frontal, three-quarter, profile, looking-up/down, and uncertain groups. Nothing is moved. The review window shows pose confidence and supports manual correction. Tagged prompts such as [profile_left] use a bounded matching-pose reward while overall identity stays dominant; [auto] uses the generated face's detected pose, with safe fallback for sparse buckets.
• Configure Pose Training Plan… adds Balanced Identity, Improve Side Profiles, Improve Three-Quarter Views, and Custom goals. Its advanced table controls sampling share, target, target patience, plateau patience, and minimum evaluations per pose. Seven grouped prompt editors add tags automatically and can generate editable offline suggestions or import tagged TXT/JSON prompts. Monitor output reports each pose against its target and the final stop reason.
• The dedicated Face Refinement page keeps setup, reference-analysis status, pose planning, Turbo evaluation, the latest report, and staged-run actions together. Evaluation returns to this page automatically instead of leaving its report only in a pop-up.
• Evaluate LoRA… performs a read-only fixed-seed baseline with Krea Turbo—the renderer users actually see, not RAW. It reports overall and matching-pose identity, requested pose success, detection, worst cases, and before/after deltas. Any saved LoRA checkpoint can be compared against the baseline, then Build Plan from Weak Poses prepares an editable plan. The UI shows the trigger and LoRA strength used. Unique prompts are encoded once before the image model loads, then reused while seed variants generate sequentially.
• MiniMax H3 and MOSS use their standalone previews instead of the Krea-only fixed Turbo evaluator. MiniMax's heavier DRaFT path starts at 35 swapped blocks on 24 GB; MOSS face refinement has only a short real-model smoke test so far.
• Double-click a pose in the embedded evaluation report to inspect all generated images for that angle in a thumbnail gallery. Refinement setup also exposes the intermediate LoRA save interval; 0 disables intermediate checkpoints, while the final LoRA is always saved.
• It is intended for recognizable human faces, not clothing, body shape, tattoos, or general style.
• Built-in saturation, Q/K/V/O-only training, face-detection monitoring, previews, and early stopping reduce—but cannot eliminate—the risk of overfitting or a pasted-on “face swap” appearance.

Open Face Refinement, choose the starting-LoRA mode and trigger word in Configure Setup…, acknowledge the third-party face-model notice, download or select AntelopeV2, run Analyze Faces & Poses, then add a face_refinement stage in the staged-training window. The recommended starting point is 30 updates at 512px with 12 denoising steps and draft_k=1. Optional dependencies are installed with pip install -e ".[face_refinement]". For a recorded Krea, MiniMax H3, or MOSS run, the Jobs page also provides Refine Face Identity… in the right-click menu; it restores the run's model paths, finds its complete LoRA, and prepares a refinement-only plan without starting it.

This workflow adapts the Apache-2.0 face reward from KONAKONA666/krea-2 and the DRaFT paper. AntelopeV2 model files are not bundled and have separate terms; see THIRD_PARTY_NOTICES.md.

Sample Tools

• Save prompt presets without deleting older ones
• Enable only the prompts you want active for a run
• Duplicate a prompt and edit the copy
• Test Krea 2, MiniMax H3, and MOSS prompts directly from the GUI
• Preview generated sample images inside the app
• Open a global prompt library with search, tags, collections, favorites, and model filters
• Collect and deduplicate prompts from current settings or historical jobs
• Copy library prompts into a run without creating a live dependency on the library
• Automatically preserve a model-badged library thumbnail after a successful standalone prompt test
• Generate base-model covers before training, keep separate covers per checkpoint, and add portable starter prompts

MOSS sample cards support a 25-step DDIM + Simple recipe with CFG 3 and an optional sampling-only Turbo LoRA at 0.6. Configure the Turbo file in Training plan → Sample prompts (Classic: Samples). It applies only during generation; your trained LoRA remains separate. Generate base cover omits the trained LoRA and keeps the same optional Turbo adapter for comparison.

The global library is user data, stored outside the repository at %APPDATA%\MusubiTuner\prompt_library on Windows. Each run and job snapshot still stores a complete copy of its prompts so later library edits cannot change an existing run configuration.

Job History

The Jobs page stores local machine history only. It is intended for day-to-day use, not for committing into the repo.

It records or imports:

• completed runs
• stopped runs
• failed runs
• conversion jobs
• Krea test sample jobs

For imported historical jobs, the GUI tries to recover progress and metadata from:

• saved settings JSON files
• model/state folders
• wandb-summary.json
• output.log
• log directories

Continuation Training

The GUI supports both:

• resuming from a full saved training state
• continuing from existing LoRA weights

This is useful for staged training such as 256 -> 512 -> 1024.

At each standard-to-standard boundary, choose Full training state to preserve optimizer momentum and the scheduler exactly, or LoRA weights + fresh optimizer when the next stage should deliberately use a different learning rate, optimizer, scheduler, warmup, or timestep-sampling recipe. Existing saved plans continue to use full-state handoff by default. Rank, alpha, and network type remain shared because changing adapter tensor shapes at a handoff is unsafe.

Documentation

This fork rides on top of upstream musubi-tuner, so the backend documentation is still important.

• Wan: docs/wan.md
• Flux.2: docs/flux_2.md
• Krea 2: docs/krea2.md
• MiniMax H3 experimental image training: docs/minimax_h3_experimental.md
• MiniMax H3 official video and joint-audio training: docs/minimax_h3.md
• Dataset config: docs/dataset_config.md
• Sampling during training: docs/sampling_during_training.md
• Advanced config: docs/advanced_config.md
• LoHa / LoKr notes: docs/loha_lokr.md
• Differential Output Preservation: docs/dop.md

Notes

• This repo is opinionated toward Windows desktop use.
• Some advanced backend capabilities still depend on the upstream CLI behavior.
• Different modes have different model-format requirements. Read the matching backend doc before downloading large checkpoints.

Credits

• Upstream training backend: kohya-ss/musubi-tuner
• The experimental Krea 2 weight-noise and depth-anchor features were inspired by Perceptual LoRA Toolkit by BuffaloBuffaloBuffaloBuffalo. That project documented practical LoRA applications of adapter weight noise and frozen depth-perceptor losses. This repository contains an independent Musubi/Krea 2 adaptation and is not endorsed by the reference project. Weight noise and perceptual loss are broader techniques that predate both projects.
• Differential Output Preservation was studied from Ostris AI Toolkit. This repository contains an independent Musubi implementation for cached-text Krea 2 and FLUX.2 Klein training.
• This repo builds a GUI workflow around that backend and adds mode-specific UX, sampling, monitoring, and local job tracking.

License

Same overall licensing direction as the upstream musubi-tuner project. See the repository license files and upstream project for details.