# MooshieUI Wiki (complete) Every page of the MooshieUI wiki, then the key documents from the MooshieUI repository, in one file. Wiki source: https://github.com/Mooshieblob1/MooshieUI/wiki (commit 50dab2d, 2026-11-18T04:03:16+08:00). Repository docs: https://github.com/Mooshieblob1/MooshieUI (main at 66eb40d, 2026-11-18T04:09:38+08:00). Web version: https://mooshieui.com/wiki "Added in" gives the MooshieUI release a feature first shipped in. --- # MooshieUI Wiki MooshieUI is a beginner-friendly interface for image, video, music and 3D generation through [ComfyUI](https://github.com/comfyanonymous/ComfyUI), with optional image generation through the NovelAI API using your own key. It hides node-graph complexity behind a guided UI. It runs two ways: - **Desktop app** via Tauri (Windows, Linux and Apple Silicon macOS releases) - **Browser/server mode** via a built-in web server (LAN/Docker friendly, mobile UI included) ## Start here - [[Installation]] - one-click setup, Docker, remote ComfyUI, macOS - [[Generation Basics]] - image modes, pause/continue, queue, dimensions and sampling controls - [[Prompting Guide]] - Prompt Chunks, random syntax, Style Creator, Artist Styles, scheduling and autocomplete - [[Anima Prompting]] - tag order, quality and score tags, @artists and the Turbo, Aesthetic and Base versions, from the official model card - [[NovelAI Prompting]] - special tags, emphasis, multi-character and text prompts for V5 and V4.5, from NovelAI's official docs - [[Prompt Assistant]] - write, edit or polish prompts with a local or external LLM ## Features by area - [[NovelAI Backend]] - personal API keys, characters/references, face detailing, Director Tools, Enhance and Anlas estimates - [[Video Generation]] - the MiniMax H3 video mode, shot timeline, player and export - [[Music Generation]] - YuE2 songs, lyric writing, playlists, shared playback and manual lyric timing - [[Anime Scenes]] - voiced, lip-synced character clips through ElevenLabs and fal.ai with your own keys - [[Image to 3D]] (experimental) - turn one image into a textured mesh (Pixal3D) or a Gaussian splat (Idol) - [[Image Edit Mode]] - Qwen Image Edit/Edit Plus, Flux.1 Kontext, FLUX 3 Klein and Anima ReStyler - [[Upscaling and Face Fix]] - tiled diffusion upscaling, guidance nodes, face detailer - [[ControlNet and Style Transfer]] - structural guidance and reference-image style transfer - [[Inpainting and the Canvas Editor]] - multi-layer canvas, mask painting, staging strip - [[Compare Grid]] - XYZ-style parameter sweeps with stitched output - [[Image Comparison]] - A/B viewer with slider, fade, difference and side-by-side modes - [[Models and the Model Hub]] - smart model detection, CivitAI/HuggingFace browser, model manager - [[Gallery and Metadata]] - image/video saving, PNG/JXL/WebP and NovelAI metadata, drag-drop remix - [[Server, LAN and Multi-User]] - hosting MooshieUI for phones and other machines, roles and auth - [[Settings and Accessibility]] - categorized Settings, themes, notifications, retention, 12 languages and accessibility - [[AI Assistants and MCP]] - let Claude, Cursor and other assistants generate through the opt-in MCP server - [[FAQ]] - [[Contributing]] and [[Project Scope]] ## Notes on this wiki Each page says which version a feature arrived in where that matters. Controls and supported workflows depend on the selected backend and model. NovelAI provides txt2img, img2img and inpainting; Image Edit, video, music, Image to 3D and pause/continue use ComfyUI; Anime Scenes uses cloud providers only. Apple Silicon DMGs ship with every release since v2.3.9 and are user-tested rather than fully qualified on hardware. For technical references see the [documentation index](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/README.md). Contributor/build instructions live in [CONTRIBUTING.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/.github/CONTRIBUTING.md) and [push-instructions.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/push-instructions.md); version history lives in [CHANGELOG.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/CHANGELOG.md). --- # Installation MooshieUI can run as a desktop app, a self-hosted web server, or a thin client against a remote ComfyUI. ## One-click setup (Windows/Linux releases) 1. Download a release from [Releases](https://github.com/Mooshieblob1/MooshieUI/releases): the `_x64-setup.exe` installer for Windows, or an `.AppImage`, `.deb` or `.rpm` for Linux. For Mac, see [macOS (Apple Silicon)](#macos-apple-silicon). On Debian, Ubuntu and Fedora you can instead install from MooshieUI's signed apt or dnf repo, so it updates with the rest of your system; see the [Linux install guide](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/LINUX.md). 2. Run the app. The setup wizard will: - download [uv](https://github.com/astral-sh/uv) (fast Python package manager) - install an isolated Python runtime (normally 3.11; the AMD Windows preview uses 3.12) - download the ComfyUI version pinned by your MooshieUI release - create a virtual environment - auto-detect your GPU (NVIDIA CUDA / AMD ROCm / Intel XPU / CPU) - install PyTorch with the right backend (including CUDA 13.0 for Blackwell GPUs) - install ComfyUI dependencies and MooshieUI's custom nodes 3. Start generating. ComfyUI launches automatically with no visible terminal windows. The installer streams real-time output as a matrix-style backdrop with per-step progress bars and a checklist. > Disk space: roughly 5 to 10 GB for Python, PyTorch and ComfyUI, plus model downloads. Install typically takes 5 to 15 minutes depending on your connection. On a slow connection the CUDA PyTorch download can take a long time. Since v2.3.41 setup waits for it instead of failing with "Failed to acquire lock on the client cache" after 5 minutes, and setup's downloads stop when you close MooshieUI, so a hidden leftover download cannot hold up the next attempt. If the setup log still reports a lock timeout, it explains what usually holds the lock and what to do. While PyTorch downloads, the status line shows how much has arrived and the speed, and the last few installer lines show under the progress bar. If no data arrives for 90 seconds, setup says so and the log lists the usual causes (slow link, VPN, proxy, firewall, antivirus). Setup gives uv a 120 second network timeout and 6 retries unless you set `UV_HTTP_TIMEOUT` or `UV_HTTP_RETRIES` yourself. Before a fresh PyTorch install it checks free space and stops with a clear message when the install drive or uv's cache drive (C: by default on Windows) has under 6 GB free (2 GB for CPU and Metal). **Update ComfyUI** targets the version pinned by the app. An interrupted update remains retryable. If ComfyUI crashes at startup because its environment needs repair, use the error dialog's **Repair and restart** action to reinstall the dependencies for the installed version. ### Music runtime Music requires native YuE2 support, which ComfyUI includes from v0.36.0. Managed installs and the default Docker build use a pinned, tested ComfyUI release (v0.43.0 as of v2.3.41). Older installations missing those nodes can use **Update and restart ComfyUI** from Music, then download a YuE2 checkpoint. Remote hosts need their operator to update and restart ComfyUI. See [[Music Generation]] for setup, model requirements and license details. ### AMD ROCm on Windows (preview) On Windows, setup detects a specific allowlist of AMD GPUs (RX 9070 / 9070 XT, RX 9060 XT, Radeon AI PRO R9700, RX 7900 XTX, Radeon PRO W7900, RX 7700 — note RX 7700 XT is not supported) and installs AMD's ROCm 7.2.1 preview build of PyTorch instead of the CPU fallback. This path uses an isolated Python 3.12 environment (the preview wheels are cp312-only) instead of the usual 3.11. Unsupported AMD GPUs on Windows still fall back to CPU mode. ## Managed ComfyUI connections New managed installations prefer port **18288**. Existing saved port settings are retained; when the preferred port is occupied, MooshieUI selects a free port and updates its connection. You can leave another ComfyUI application running. Restart, setup and shutdown stop only processes identified as MooshieUI's own. Verified kept-alive processes can be reclaimed after reopening the app. To use an existing ComfyUI installation intentionally, choose **Remote** in connection settings (see [Use your own ComfyUI](#use-your-own-comfyui-no-docker-no-managed-venv)). Windows setup checks installed Git locations even when Explorer has an older PATH. If necessary, it downloads a portable Git copy and verifies the archive checksum. Setup and update operations run one at a time, and an update prepares the pinned source before applying it. ## Self-host / server mode (Docker) MooshieUI can run headless and serve the same web UI over your network. ```bash # Required on first launch: create your configuration cp .env.example .env # Edit .env and set a strong MOOSHIEUI_ADMIN_PASS before continuing. # build and run docker compose up -d --build ``` Then open `http://localhost:3200` (or your configured `MOOSHIEUI_PORT`). Sign in with `MOOSHIEUI_ADMIN_USER` and the password you set. Account creation rejects empty passwords, passwords shorter than four characters, and `changeme`; use a strong unique password. In v2.3.8 and later the container exits at startup if `MOOSHIEUI_ADMIN_PASS` is `changeme` or `REPLACE_ME`, and new usernames use letters, numbers, `_` and `-`, up to 32 characters. There is no public self-registration. These variables bootstrap a new account and do not reset the password of an existing one. The default compose file includes a persistent data volume (`mooshie-data`), a models-directory mount (`MODELS_PATH`, default `./models`), admin bootstrap via `MOOSHIEUI_ADMIN_USER` / `MOOSHIEUI_ADMIN_PASS`, and NVIDIA GPU reservation. The Docker image targets NVIDIA CUDA and needs Docker GPU support; the desktop AMD/Intel setup paths do not apply to this image. `MOOSHIEUI_PORT` changes the published host port; the container uses port 3200. In v2.3.8 and later the image runs as the unprivileged user `mooshie` (uid and gid 10001). Data volumes and model folders created by older images belong to root, so hand them over once when upgrading: ```bash docker run --rm --user 0 -v mooshie-data:/data --entrypoint chown -R 10001:10001 /data sudo chown -R 10001:10001 ./models ``` Compose prefixes the volume with the project name, so check `docker volume ls` for the exact name. If `/data` or `/data/models` is not writable, the container prints these commands and exits. On Kubernetes, set the pod's `securityContext.fsGroup` to 10001 (see `deploy/k8s/deployment.yaml`). See [[Server, LAN and Multi-User]] for roles, auth, and LAN exposure. ## Use your own ComfyUI (no Docker, no managed venv) MooshieUI's managed install always puts ComfyUI in its own Python environment. If you would rather run ComfyUI yourself, with your system Python, conda, a portable build or anything else, MooshieUI can connect to it instead and skips its own install completely. 1. **Install and start ComfyUI your way.** Use ComfyUI v0.43.0 or newer, which is the version managed installs use. MOSS-Image needs at least v0.43.0. 2. **Add MooshieUI's custom nodes.** From a clone of this repository, run the installer against your ComfyUI folder: ```bash git clone https://github.com/Mooshieblob1/MooshieUI MooshieUI/comfyui-nodes/install.sh /path/to/ComfyUI ``` On Windows, run it from Git Bash, which comes with Git for Windows. Then install the nodes' Python requirements with the same Python your ComfyUI runs on (the script prints the exact command): ```bash python -m pip install -r /path/to/ComfyUI/custom_nodes/mooshie-nodes/requirements.txt ``` Restart ComfyUI so it loads the new nodes. Run the script again after updating MooshieUI to pick up node changes. 3. **Connect.** On first launch choose **Remote server**, enter your ComfyUI address (usually `http://127.0.0.1:8188` for a local install) and click **Validate remote server**. You can change it later in **Settings -> Connection**. Node packs from other authors (ComfyUI-GGUF, comfyui_controlnet_aux, Frame Interpolation and so on) are only installed automatically when MooshieUI manages ComfyUI. Install the ones you need yourself, for example with ComfyUI-Manager. MooshieUI names the missing pack when a feature needs one. With your own ComfyUI, MooshieUI does not start, stop or update it, and **Update and restart ComfyUI** is not available. Keep it up to date yourself. ## Remote / cloud ComfyUI (RunPod, Vast.ai, etc.) Use this when MooshieUI runs on your desktop but ComfyUI runs on a cloud GPU. 1. **Deploy the MooshieUI server build on the cloud instance.** The Docker image ships ComfyUI, PyTorch, and all MooshieUI custom nodes pre-installed. This is the easiest way to get the required nodes onto a remote server. For a ComfyUI you already run, see [[Installation#use-your-own-comfyui-no-docker-no-managed-venv]]. ```bash docker compose up -d --build # or: docker pull ghcr.io/mooshieblob1/mooshieui:latest ``` 2. **Expose ComfyUI.** Either use the web UI on port `3200`, or expose the configured ComfyUI port and use the desktop app as a thin client. New managed installs prefer `18288`; existing installs may retain `8188` or another saved port. Match the proxy URL to the actual configured port. 3. **Connect from desktop.** On first launch choose **Remote server**, paste the public ComfyUI URL, and click **Validate remote server**. MooshieUI skips the local install entirely. You can change the endpoint later in **Settings -> Connection**. If validation reports missing custom nodes, redeploy or update the server build and fully restart ComfyUI before retrying. ## macOS (Apple Silicon) Since v2.3.9 every release includes an Apple Silicon DMG, with automatic updates. It passes the automated Mac checks but has not been tested feature by feature on real Macs, so please report anything that breaks. Use **macOS 14 or later**. Download `MooshieUI__aarch64.dmg` from the [latest release](https://github.com/Mooshieblob1/MooshieUI/releases/latest). 1. Compare the DMG's SHA-256 with the release's `SHA256SUMS` using `shasum -a 256 .dmg`. 2. Open the DMG and copy MooshieUI into Applications. 3. Open it from Finder. The app is ad-hoc signed and **not notarized by Apple**. If macOS blocks it, try opening once, then use **System Settings > Privacy & Security > Open Anyway**. See [Apple's instructions](https://support.apple.com/en-us/102445). 4. Complete setup with **Apple Silicon (Metal)**, or explicitly choose **CPU only**. Setup installs native ARM Python and constrained PyTorch packages and checks a real Metal tensor operation before accepting MPS. Keep default attention and precision. Apple memory is shared with macOS; model size and optional node support still need testing on the target machine. Xcode Command Line Tools may be needed for Git-based custom nodes or dependencies without prebuilt wheels. Intel Macs can use the browser connected to a remote MooshieUI server. See [Mac installation and validation](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/MACOS.md) for what the automated checks cover and the hardware checklist still to be confirmed on real Macs. ## Development setup (all platforms) Prerequisites: Node.js 22.12+ or 24+, stable Rust, and the Tauri v2 prerequisites for your platform. The locked Svelte Vite plugin requires Node `^20.19 || ^22.12 || >=24`; Node 18 is not supported by the current frontend toolchain. ```bash git clone https://github.com/Mooshieblob1/MooshieUI.git cd MooshieUI npm install npm run tauri dev ``` See [CONTRIBUTING.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/.github/CONTRIBUTING.md) for frontend checks and both Rust build targets. `npm run dev` starts only the frontend; `npm run tauri dev` starts the full desktop development app. --- # Generation Basics ## Four generation modes | Mode | Description | |------|-------------| | **Txt2Img** | Generate from positive and negative prompts | | **Img2Img** | Transform an existing image with adjustable denoise strength | | **Inpainting** | Selectively edit parts of an image with a built-in canvas mask editor | | **Image Edit** | Edit a reference image by describing the change in the prompt | Switch modes with a single click. Settings carry over between modes. For the inpaint canvas see [[Inpainting and the Canvas Editor]]. For instruction-driven editing see [[Image Edit Mode]]. These four are the image modes under **Generate**. In v2.3.7 and later, **Video** has its own entry in primary navigation beside **Generate** and **Music**, on desktop and mobile. Returning to **Generate** restores the image mode you last used during the session. Video has its own models and settings panel; see [[Video Generation]]. With a NovelAI model selected, **Txt2Img**, **Img2Img** and **Inpainting** run on NovelAI. **Video** and the **Image Edit** tab stay available: Video always runs on ComfyUI with its own models, and a plain Image Edit run with a NovelAI model stops with a message instead of spending Anlas. The model picker switches the backend, and the panels adapt: VAE/LoRA and ComfyUI-only controls are hidden, while NovelAI's characters, references and sampling options appear. See [[NovelAI Backend]] for its model limits and costs. ## Page layout On desktop the Generate page is split into rounded cards: a left panel, a right panel, the preview and the bottom drawer. - **Mode bar**: the mode tabs, the **Canvas Editor** toggle and the **Layout** menu sit in a bar above the preview. - **Layout menu**: **Swap left/right panels**, **Everything on the left**, **Everything on the right** and **Reset layout** (default sides, section order and panel widths). A fresh install puts Model, Prompts and Dimensions on the left. - **Sections**: drag a section by its grip to reorder it, use its arrow to move it to the other side, or collapse it with the chevron. Help text for a control is in the tooltip next to its label. - **Resizing**: drag the gap between two cards to resize them. The small button in the middle of each gap hides or shows that side. - **Preview**: the preview takes the shape of the image or video it shows (or of the size you set, before there is one) and fills the free space. - **Bottom drawer**: the button at the right of the drawer's tab row collapses it to just the tab row. Click any tab to open it again. Image modes and Video each keep their own drawer height and collapsed state. - **Generate footer**: pinned under the left panel. It shows the Anlas row when a NovelAI model is selected, a batch stepper (1 to 8, the same value as **Batch size**), a Stop button while generating (click skips the current image, right-click cancels all), and the Generate button with the estimated Anlas cost inside it. ## Settings tabs The generate page supports multiple independent settings tabs. The tab strip sits at the top of the main column, beside the sidebar, and is always visible, even with only one tab open. Use it to switch tabs, open a new one or close one. **New tab** opens a copy of the current settings. Each tab keeps its own prompt, model, sampler, steps, resolution and generation mode. What stays shared across all tabs: the queue, gallery, canvas input image and app-wide preferences (output format, notifications, autosave directories). Tabs are remembered across restarts. Each tab keeps its own last image in the preview, so switching tabs switches the preview too. An image that finishes in a background tab waits there instead of replacing what you are looking at. **Profiles** saves the current tab's settings under a name. Pick a profile to open it in a new tab, or use **Load into this tab** to apply it over the current one. Saving under an existing name updates that profile. Profiles only hold tab settings, so app-wide preferences stay as they are, and in browser mode they sync per user. On desktop: **Ctrl+T** opens a new tab, **Ctrl+W** closes the active one, and **Ctrl+Tab** / **Ctrl+Shift+Tab** cycles between them. ## Core controls - **Positive and negative prompts** - multi-line, manually resizable, with a live CLIP token count (`count/limit`) in the top-right corner of each box that turns amber once a prompt spills past the 75-token chunk boundary. An **Add Prompt Block** button below each box adds extra named prompt blocks that join in order at send time. A toggle beside the **Regional prompt** button can fold the two boxes into a single **combined view** with a Positive/Negative tab switcher. See [[Prompting Guide]] for the combined view, weighting, additive blocks, wildcards, presets, scheduling, and more. - **Checkpoint selector** - searchable, auto-populated from ComfyUI, with recommended models that auto-download on selection (progress bar + file size). - **VAE selector** - optional override; defaults to the checkpoint's built-in VAE. On split models (Anima, Krea 2, Qwen, Flux 2 and others) the VAE you pick is kept as long as it is installed and fits the model, so a fine-tuned decoder such as a sharpened Qwen Image VAE stays selected. Qwen-based models default to the stock `qwen_image_vae`. - **LoRA support** - add unlimited LoRAs with a **Strength** slider (0 to 2 in 0.05 steps; double-click resets to 1) that drives both model and CLIP strength together. Click the link icon beside the slider to split them into separate **Model Strength** and **CLIP Strength** sliders; click it again to merge back. Per-LoRA enable/disable, searchable dropdown, and an active-count badge. The LoRA list can be collapsed to save space; the state is remembered between sessions. Each LoRA card has a **Trigger words** field: text you enter there is added to the positive prompt when the LoRA turns on and removed when it turns off. It works offline and does not require CivitAI metadata. Clicking any displayed trigger chip also inserts the word into the positive prompt. See also LoRA presets in the [[Prompting Guide]]. - **Sampler and scheduler** - all ComfyUI samplers and schedulers. The scheduler dropdown is locked for Flux 2 models, which use a fixed internal scheduler; the panel notes "Flux2 uses a fixed internal scheduler" when this applies. - **Recommended settings** - selecting a checkpoint applies the recommended steps, CFG, sampler, scheduler and resolution for its model family, and the sampler panel shows a short card with those values for families that have one (Anima, Nanosaur, NovelAI and others). **Advanced Mode** in Settings > Quality Tags turns the auto-apply off so your settings carry over between models. See [[Settings and Accessibility]]. - **RDBT-Anima LoRA (Anima)** - a toggle in the Anima recommended settings card that downloads (about 92 MB, from an unofficial mirror) and applies the community RDBT-Anima guidance-distilled LoRA. It speeds up generation by removing the need for CFG. - **TeaCache (Anima)** - when an Anima checkpoint is selected, the sampler panel adds a TeaCache toggle. It reuses the previous step's output on steps where little changed, skipping the forward pass. Off by default; small risk of softer detail when enabled. - **Painterly textures - beta57 (Anima)** - when an Anima checkpoint is selected and the RES4LYF node pack is installed, the sampler panel also shows a **Painterly textures (beta57)** toggle. Enabling it switches the scheduler to the beta57 scheduler from RES4LYF. Steps, CFG and sampler are unchanged; turn it off to go back to the normal scheduler. - **Krea 2 Turbo steps** - when a Krea 2 Turbo model (or Wulver) is selected, the sampler panel shows a **Krea 2 Turbo steps** picker with **8 steps**, **4 steps** and **2 steps**. Picking 4 or 2 downloads a community speed LoRA (418 MB) and sets euler / simple, CFG 1 and the step count. Picking 8 uses stock Turbo with no LoRA. The 2-step option can smear small faces and wide scenes; use 4 steps for final renders. - **Steps** - 1 to 150. - **CFG scale** - 0 to 30, 0.1 precision. - **Seed** - fixed, or -1 for a new random seed each generation. - **Batch size** - 1 to 8 images per prompt. - **Denoise strength** - 0 to 1 for img2img and inpainting. ## Guidance options Optional guidance controls appear where the model supports them. **NAG** and **APG** are offered for SDXL-family ComfyUI models; they are disabled when the connected ComfyUI lacks the required node/input schema, with a hint to update. These are separate from NovelAI's own guidance controls. - **RescaleCFG** - rescales the guidance vector each step so v-prediction checkpoints stop blowing out contrast and saturation at normal CFG. Recommended on for v-pred models. **Rescale strength** sets how hard the rescale bites; 0.7 is the standard value and lower keeps more of the raw CFG look. - **NAG (attention guidance)** - Normalized Attention Guidance applies the negative prompt inside attention, so it keeps working at low CFG and low step counts where ordinary CFG stops doing anything. **NAG scale** controls how strongly the negative is pushed away; 5 is the default and higher can distort. - **APG (projected guidance)** - Adaptive Projected Guidance splits the guidance update into direction and magnitude, so a high CFG improves prompt adherence without oversaturating colors. **Eta** sets how much of the saturating parallel component is kept (1 behaves like normal CFG, 0 removes it), **Norm threshold** caps how large the push can get, and **Momentum** smooths guidance across steps. APG does nothing at CFG 1 or below, and the panel says so rather than staying silent. ## Pause and continue a generation In **Text to Image** with a ComfyUI model, **Pause at step** stops sampling partway and saves a preview. Set it between 1 and the step before the end; 0 completes the image normally. After the preview appears, change the prompt, CFG, sampler or LoRAs and press **Continue from step …**. Size, batch size and model must match the paused run, and continuing keeps its original seed. A final continuation can change **Steps** and **Scheduler**; Steps is the total, so a run paused at 8 with Steps set to 30 samples 22 more steps. To pause again, choose a later step and keep the original step count, scheduler and sampler noise schedule. Switching between DPM2/UniPC and other samplers is available on a final continuation. **Paint a correction** opens the paused preview in the inpaint canvas. Paint the change, mask the area to replace, then press **Continue with edit from step …**. The correction is blended into the paused latent before the remaining steps run. The pause stays available after a completed continuation so you can try different endings. **Discard paused run** starts fresh next time. Pauses live in the current app session; reloading the page or restarting the app clears them. ComfyUI can reuse cached stages when available, or sample those stages again after a cache clear or worker change. Early previews can be noisy, and restarting a sampler does not preserve its internal multi-step history. Style transfer and Anima TeaCache are disabled for paused runs. Upscaling and face/segment refinement wait until the continuation finishes. Pause and continue do not apply to NovelAI generations. ## Continuous generation The repeat button next to the batch stepper opens **Continuous generation**. Set **Runs** (1 to 999) or pick **Until stopped**, an optional **Delay (s)** between runs, and **Stop on error**. One Generate click then runs the normal generation again and again. Each run waits for the previous image to finish, so nothing piles up in the queue, and each run builds fresh settings, so random seeds and `{a|b}` wildcards reroll. The Generate button shows the progress (for example "Generating 3/10"), and the stop button stays visible during the pause between runs. With **Stop on error** off, a failed image is skipped, but the run still stops after 3 failures in a row. Combined with an **In order** file wildcard, a set number of runs walks a list one line at a time. See [[Prompting Guide#file-wildcards]]. ## DMD2 4-step preset (SDXL) **Use DMD2 (4 steps, CFG 1)** is a single toggle that downloads the DMD2 distillation LoRA and switches the sampler to 4 steps, CFG 1, LCM sampler, SGM uniform scheduler. Turning it back off removes the LoRA but leaves the sampler settings alone so you can restore your own. Because it runs at CFG 1, ordinary negative prompts stop applying; NAG is the guidance method that still works there, so pair the two if you need a negative. ## Dimension controls - **Aspect ratio presets** - 1:1, 4:3, 3:2, 16:9, 21:9, 3:4, 2:3, 9:16 on every backend. Any ratio can be typed; with a NovelAI model selected only the pixel grid differs (multiples of 64 instead of 8). - **Custom aspect ratio** - enter any width/height; the ratio is maintained when you adjust resolution. - **Loaded images set the aspect ratio, not the pixel size** - browsing, dropping or pasting an image into img2img, and dropping an image for a metadata import, adopt the image's shape as the aspect ratio at your current side length, exactly as clicking that preset would. The ratio is reduced and snapped to the nearest preset within a small tolerance, so a 1216x832 image reads 3 : 2, and a 1024x1536 image at a 1024 side becomes 832x1216 rather than 1024x1536. The source is fitted to that size when you generate. Two exceptions: dropping an image directly onto the Dimensions section applies its size, and inpainting sizes the canvas to the image so the mask matches it. A locked resolution ignores the image entirely. - **Swap dimensions** - one-click width/height swap. - **Resolution slider** - 64px to 2048px, dimensions computed from your aspect ratio. - **Lock resolution** - toggle next to the resolution controls. Switching checkpoints normally resets width/height to that model's default resolution; enabling the lock keeps your current dimensions fixed through model swaps, the Anima minimum size at generate time, and image edit reference uploads. ## Smart model detection MooshieUI recognizes a wide range of model architectures and auto-applies optimal sampler, scheduler, steps, CFG, and resolution for each. Highlights: - Accelerated variants (turbo, lightning, lcm, hyper in the name) get reduced steps and lower CFG automatically. - Rectified-flow models (SD3, Flux, AuraFlow, Mugen, Nanosaur, and others) inject the correct ModelSampling node with architecture-specific shift values. - Flux Dev models auto-inject FluxGuidance; Flux Schnell is detected and skipped. - Models are identified by SHA256 hash (CivitAI AutoV2 format), so renamed files are still recognized. See [[Models and the Model Hub]] for the full list and the model browser. ## Queue panel When you queue multiple generations, a list icon with a count badge appears on the Generate button. Clicking it opens the **Your Queue** panel. The panel shows the currently running item labeled **Running** with an elapsed-time counter, followed by each pending item in order with its queue position. Per-item actions: | Action | What it does | |--------|--------------| | **Move to front** | Jumps the item to the top of the pending list | | **Move up** | Moves the item one slot earlier | | **Move down** | Moves the item one slot later | | **Cancel** | Removes the item from the queue | Two panel-level actions sit at the bottom: **Interrupt running** stops the active generation immediately (equivalent to the Cancel button in the progress bar), and **Clear pending** removes every queued item that has not started yet. The panel closes itself when the queue empties. ## Real-time progress - **Live preview** of the image as it generates (latent previews over WebSocket). - **Phase labels** ("Generating...", "Upscaling...", "Preparing...") with a step counter. - **Progress bar** (indigo for generation, emerald for the upscale pass). - **Cancel button** to interrupt any generation. A persistent **download banner** shows active downloads (models, ControlNet, LLM, etc.) with per-file speed and progress. A **notification bell** keeps a history of success/warning/error/info messages. On desktop, a collapsible **terminal log** panel streams live ComfyUI and app output. ## Characters tab The **Characters** tab in the bottom panel saves character descriptions for reuse across sessions. Every user starts with one sample character, Yue, saved for NovelAI and for each local tag model (Illustrious, SDXL, Pony, Anima, SD 1.5). Natural-language models such as Flux get no sample. Delete her like any card and she stays deleted, on every synced device. The **Card size** slider in the tab header scales each card's picture from 48 px (the default) to 192 px; bigger cards show more of the prompt. It is saved per device. **Extract from prompt** sends your positive and negative prompts, plus any NovelAI character boxes, to the prompt assistant. It returns each character's name, appearance and character tags, and the undesired content (UC) that applies to them. Characters are saved per model architecture; the tab only shows characters saved for the architecture of the model currently selected. Nothing is saved straight away. Extract opens **Name your characters**, where each new character has a **Character name** field filled with the prompt assistant's suggestion. Change any name you like, or untick one to leave it out. Extract also checks what is already saved. A character that matches a saved card (same name, part of it, a nickname, or the same character by appearance) is not added twice. If it matches word for word it is skipped; if it differs, the same dialog lists it under **Already saved**, shows the saved card beside what was found and asks **Update saved**, **Save as variant** or **Disregard**. **Use** has the prompt assistant work the character into your current prompt: it takes over an unnamed character or joins the cast, updates count tags, and folds in the character's UC. With a NovelAI V4 or V5 model the character goes into a new character box. The result opens in a review showing **Now** and **After**, and nothing changes until **Apply**. **Insert as is** keeps the plain insert: the prompt text goes into the positive prompt (or an empty character box on NovelAI) and the UC into the negative prompt, without the prompt assistant. **Update** refreshes a card from the current prompt. The prompt assistant picks out what the prompt says about that character and ignores the others. **Undo** restores the card. Each card shows the character's name on its first line and a picture slot: use the current image, **Upload**, pick one **From gallery**, generate a **Portrait**, or **Remove** it. **Portrait** renders a front-on, neck-up portrait with the selected model from the card's prompt (editable), with optional **Artist tags**, **Chunks** and **Artist Styles** on top. NovelAI portraits are 1024 x 1024; local models get a square of about your current pixel count. The portrait goes through the normal queue and becomes the card's picture, with Undo. On NovelAI models that take a Precise Reference (V4.5 today), **Use** also attaches the picture as a character reference, unless Vibe Transfer is in use or every reference slot is taken, and a notification says which. The portrait prompt leaves out what a neck-up picture can't show: legwear, shoes, skirts, hands, poses, held items and full-body framing. What was dropped shows under the prompt as **Left out** chips; click one to put it back. This works on tag and sentence prompts in English, Japanese, Chinese, German, Spanish and Portuguese, and on picked chunks. The **Expression** box is filled from the last portrait, the card's own expression tags or the usual expression in the character's memory. The ✨ button asks the prompt assistant to pick one from memory or canon. After Generate, the expression is saved to memory as the character's usual expression (with an external LLM provider). The card's menu also has: - **Add variant** and **Variant of** - variants (an outfit, an older version) sit folded under their character's card. A variant whose parent is deleted stands on its own. - **Copy to** - copies the card to another model architecture. Between a tag model and a natural language model the prompt assistant rewrites it for the target; between two tag models it is copied as is. **Export** in the tab header saves every character, for every model, to a JSON file. **Import** adds characters from such a file, skipping any already saved and keeping variants under their parent. Saved NovelAI characters are also known to [[NovelAI Backend#enhance-for-v5|Enhance for V5]]. On NovelAI V4 and later, the portrait uses a **Character prompt** for the character's appearance and keeps framing, count and style in the main prompt, matching the way a **Use** card works. The **Character prompt** field is editable in the portrait window. ### Editing and memory **Edit** opens a window with two tabs. **Details** holds the name, character prompt and UC. **Memory** holds the character's memory files: short Markdown notes on who they are beyond their look (personality, backstory, relationships, outfits). Add a **New file**, start from the suggested files, or import `.md` and `.txt` files; each file can be renamed, exported or deleted. **Remember** asks the prompt assistant to write a fact up as a proper note, tie it to what the notes already say and file it, and shows the change for review first. It also reads the notes of other saved characters the fact names, and a relationship goes both ways: "Mumei is Miku's sister" adds the matching line to Miku's memory too. **Write with AI** drafts the memory files from canon, the character's prompt and an optional brief, for review. For a variant or other take on a known character (gender-swapped, alternate universe, an original design), what you wrote wins over canon. Nothing is saved until **Save**. Variants share their parent's memory. With an external LLM provider (Claude, ChatGPT, Gemini, Grok or a capable model on your own endpoint), **Use**, **Update** and Enhance read the notes and turn them into visible details where the scene calls for them. When Enhance works out a lasting detail a note does not have yet (for example the uniform of a character's school), it saves it and shows **Saved to memory for next time**, with Undo. A card with notes shows a **Memory** button with the file count. Characters can be renamed, edited and deleted from the tab. The tab is hidden in video mode and disabled until a model with a known architecture is selected. --- # Prompting Guide MooshieUI has a rich prompt system layered on top of the plain positive/negative text boxes. This page covers everything you can do beyond typing tags. ## Quick reference of prompt syntax | Syntax | What it does | |--------|--------------| | `(tag:1.2)` | Weight a tag (A1111 native, passed straight to ComfyUI) | | `1.2::tag::` | Weight prefix, translated to `(tag:1.2)` at send | | `{tag}` / `[tag]` | Emphasis / de-emphasis (x1.05 / x0.95 per layer, nests) | | `(tag)1.2` | InvokeAI trailing weight, translated to `(tag:1.2)` at send | | `(tag)++` / `(tag)--` | InvokeAI emphasis (x1.1 / x0.9 per mark); `word++` works too | | `{a\|b\|c}` | Random alternation: pick one option per generation | | `{2$$a\|b\|c}` | Pick exactly 2 distinct options, joined with ", " | | `{1-3$$a\|b\|c}` | Pick a random count in a range | | `{3::a\|1::b}` | Weighted alternation: `a` is three times as likely as `b` | | `__name__` | Pick a line from a file in the wildcards folder (see [File wildcards](#file-wildcards)) | | `// note` | Comment out the rest of the line; never sent | | `@[Chunk Name]` / `@preset:` | Splice a saved Prompt Preset in at that exact spot (wildcards roll here) | | `@artist_name` | Insert an artist tag (normalized, parentheses escaped) | | `` | Prompt scheduling: swap text at step/fraction N | | `text` | Scheduling: add text starting at N | | `text` | Scheduling: add text until N | | `text` | Scheduling: add text only between N and M | | `prompt` | Re-detail a region matching `target` (eyes, face, hair, hands, etc.) | Everything below explains where to set these up. The weight conversions in this table describe the ComfyUI path. NovelAI requests use NovelAI-compatible weights; ComfyUI scheduling, regional conditioning and segment refinement do not become NovelAI sampling features. See [[NovelAI Backend]]. ## Random prompt syntax MooshieUI supports Dynamic-Prompts-compatible alternation syntax in both the positive and negative prompt boxes, on ComfyUI and NovelAI. Each submission resolves the alternation before it reaches the backend. The gallery stores the resolved text, so importing metadata restores those choices without rerolling. Identical pixels also depend on the model, settings and runtime. **Basic alternation** - pick one option at random: ``` {red|green|blue} car ``` **Picking multiple options** - pick exactly N distinct options, joined with ", ": ``` {2$$fluffy|sleek|shiny|matte} texture ``` Pick a random count in a range: ``` {1-3$$bokeh|depth of field|lens flare} ``` Use a custom separator (between the two `$$` markers): ``` {2$$ and $$watercolor|oil paint|pencil sketch} ``` **Weights** - make one option more likely with an `N::` prefix (default weight is 1): ``` {3::masterpiece|1::rough sketch} ``` **Nesting** - inner blocks are resolved first: ``` {a sunny {morning|afternoon}|a rainy evening} ``` **NovelAI brace emphasis is preserved.** Any `{...}` block that contains no top-level `|` is left completely untouched, so `{tag}` for emphasis and `{tag:1.5}` for weighted emphasis continue to work exactly as before, and prompt scheduling tags are unaffected. **Seed determinism** - alternation is seeded from your seed value, so the same seed always picks the same options. When seed is -1 (random), a fresh integer is chosen for each submission. The negative prompt rolls from a separate stream (seed + 1) so positive and negative options do not correlate. **UI indicator** - when the prompt box contains alternation syntax, a small **random** badge appears next to the prompt header. Hover to see an example roll with the current seed. Click to preview a different roll without generating. The prompt box always shows your template; only the submitted prompt changes. ## Weighting and emphasis On ComfyUI, MooshieUI translates supported forms to native `(tag:weight)` syntax at send time. NovelAI uses its own outgoing syntax instead. Your prompt box keeps what you typed; only the outgoing payload is converted. Supported forms: - **A1111 native** `(tag:1.2)` - passed straight through. - **Weight prefix** `1.2::tag::` -> `(tag:1.2)`. - **Brace emphasis** `{tag}` -> `(tag:1.05)` and `[tag]` -> `(tag:0.95)`. These nest, so `{{tag}}` compounds to roughly `(tag:1.10)`. - **InvokeAI trailing weight** `(tag)1.2` -> `(tag:1.2)`, with the number outside the parentheses. - **InvokeAI emphasis** `(tag)++` and `(tag)--` raise or lower by x1.1 / x0.9 per mark, so `(tag)++` is about `1.21` and `(tag)--` about `0.81`. A bare word works too: `word++`, `word--`. Blend and swap operators are intentionally not translated. **Weight buttons:** with the clickable overlay on (see Autocomplete below), the +/- buttons nudge a tag's weight by 0.05 in place, keeping whatever syntax you used. An A1111 tag stays A1111, a `1.2::tag::` stays that form, an InvokeAI `(tag)1.2` stays InvokeAI, and a plain tag gets wrapped in A1111 syntax. Landing exactly on 1.0 collapses back to the bare tag. Emphasis-mark forms (`(tag)++`, `{tag}`) are recognized but not numerically nudged, so the buttons grey out for them. ## Combined prompt view By default the positive and negative prompts sit in two separate boxes. A small split-pane toggle at the right end of the prompt action row, next to the **Regional prompt** button, switches to a **combined view**: a single box with a **Positive / Negative** tab switcher above it, in the style of NovelAI. (On the combined view's Negative tab that row is hidden, so the toggle sits in the prompt header instead.) The toggle's tooltip reads "Switch to combined prompt view" and flips to "Switch to split prompt view" to go back. Your choice is remembered between sessions. Both views drive the same two prompts underneath, so token counts, autocomplete, weighting, spell check, presets, and additive blocks all behave identically, and generation output is unchanged. In combined view the quality, style, preset, and artist badges stay visible on both tabs, and the Negative tab shows a small marker when the current model ignores the negative prompt. ## Additive prompt blocks Below the positive and the negative prompt box is an **Add Prompt Block** button. It adds an extra prompt box that behaves like its own mini prompt (autocomplete, weights, token gauge, spell check all work inside it). At send time every block joins together in order into one clean prompt, the same result you would get by chaining ComfyUI concatenate nodes. A combined token count above the positive box shows the estimate across every block. This exists mainly for split-encoder models (Anima and other Qwen-based checkpoints) where the text encoder reads your formatting literally. To keep those prompts clean: - **ComfyUI prompts** remove `BREAK`/`` markers and flatten line breaks when sent. Your box keeps its layout. (`BREAK` as a whole word is removed; `BREAKFAST` is left alone.) **NovelAI prompts retain line breaks**, including manual `Text:` lettering blocks; added style/chunk tags are placed ahead of that block. - Blank blocks contribute nothing, and duplicate commas from joining are collapsed automatically. Each block has an optional name field and a **Save as preset** button that drops its content straight into your Prompt Presets, so a reusable block (a quality tail, a negative baseline) can be recalled later or referenced with `@preset:`. Importing a prompt from an image, or restoring one from history, clears the extra blocks since that restored prompt is already complete. ## Prompt Chunks (presets) and wildcards Saved **Prompt Chunks** (also called Prompt Presets in older labels and metadata) provide reusable text and multi-line wildcard lists. They coexist with inline `{red|blue|green}` random syntax and with `__name__` [file wildcards](#file-wildcards). **Where:** use **Chunks** in the prompt toolbar, or the **Chunks** tab in the Styles manager. Create a chunk and give it a name. **Authoring a wildcard:** put each choice on its own line. Commas within a line stay grouped, so `1girl, solo` on one line is picked as a single block rather than split apart. Example content: ``` blue hair red hair green hair, twintails ``` **Two ways to use a preset:** 1. **Activate it** (no prompt syntax needed). Click the preset and choose a mode: - **Prepend** - whole content inserted at the start of the positive prompt - **Append** - whole content inserted at the end - **Wildcard (random)** - one line picked at random per generation, re-rolled each time - **Wildcard (in order)** - walks the lines in order, one per generation, wrapping around. The Generate button can queue the whole ordered run in one click. Activated content is spliced in at generation time and does **not** appear in your prompt textbox. 2. **Inline token** `@[Chunk Name]` or `@preset:` - drop it anywhere in your prompt to splice the preset in at that exact spot. The bracket form takes the preset name as written (`@[Cool hair colors]`); the slug form is the name lowercased with non-alphanumeric runs collapsed to `_` (`@preset:cool_hair_colors`). The editor shows the exact token to copy. A multi-line preset rolls one random line per occurrence, and each occurrence rolls independently, so `@preset:hair, @preset:hair` rolls twice. A single-line preset is inserted verbatim. Unknown slugs are left untouched so typos are visible. Presets can be imported/exported as `.txt` files and sync across browser sessions. ## File wildcards `__name__` in any prompt box picks a line from a wildcard file in the `wildcards` folder inside the app data folder. The layout follows Dynamic Prompts, so existing community packs drop in unchanged. - `colors.txt` becomes `__colors__`: one option per line, and lines starting with `#` are comments. - Subfolders become part of the name: `hair/styles.txt` is `__hair/styles__`. - YAML and JSON files with nested keys work too: `__outfits/casual__`. A key on its own pools every option under it, and `*` matches across names (`__hair/*__`). - An option can hold `{a|b}` alternation, and alternation can hold a wildcard. Wildcards also work in NovelAI character prompts. - A fixed seed repeats its picks. Unknown names are left as written so typos are visible. - The gallery and metadata store the resolved prompt. **Wildcards tab:** the **Wildcards** tab in the bottom panel lists your files with search and has an editor (Ctrl+S saves), new file, delete, reload and open folder (desktop). For each name a file provides it shows a click-to-insert token and the option count. **In order:** turn on **In order** for a name and each sent request takes the next line instead of a random one, independent of the seed. The tab shows the next position, and **Restart** goes back to the first line. Pair it with [[Generation Basics#continuous-generation|continuous generation]] to walk a whole list. ## Comments and find/replace - `//` starts a comment that runs to the end of the line. It only counts at the start of a line or after a space or comma, so URLs like `http://...` stay as they are. Comments stay in the box, greyed out, and are stripped before sending. Token counters ignore them, and prompt history keeps the raw text. - **Ctrl+/** comments out the selected lines, or uncomments them when they are all commented. - **Ctrl+F** opens a find bar above the focused prompt box and **Ctrl+H** adds a replace row. Matching is plain text, with **Match case**, a match counter, Enter / Shift+Enter for next and previous, and **Replace** / **Replace all**. Everything is undoable, and Esc closes the bar. ## Related tags Select a tag in a prompt box (click it or highlight it) and press **Related** in the prompt toolbar. A panel lists tags that go with it: - **Danbooru:** tags that often appear with it, coloured by category like the autocomplete list. Only the tag itself is sent to Danbooru. - **Your gallery:** tags that appear with it in your own saved prompts, with how many images held it. This works offline. Click a chip to add it right after the selected tag (after its weight, so `(red hair:1.2)` stays intact). Tags already in the prompt are dimmed, and Ctrl+Z undoes an add. If Danbooru is unreachable the panel says so and still shows your gallery's tags. ## LoRA presets Separate from prompt presets. The **LoRA Presets** section in the LoRA panel folds away and starts closed; click the section header to expand it. A LoRA preset stores a named set of LoRAs, each with its own model/CLIP strength and enabled state. Apply in **replace** mode (swap the current LoRA set) or **merge** mode (add/update without removing what you already have). After applying, MooshieUI reports any LoRA filenames that were not found locally. ## Prompt scheduling Use the **Schedule** builder (a tab in the bottom panel) to generate SwarmUI-compatible scheduling tokens with a live preview instead of typing them by hand. Four modes: - **From/To** -> `` - **From** -> `text` - **To** -> `text` - **Range** -> `text` The builder auto-picks the least intrusive separator and shows the resulting token before you insert it. ## Segment detailing Type `prompt` in the positive prompt to re-detail a matching region. MooshieUI auto-detects these tags and shows an editable panel listing each segment's target and local prompt. Built-in target suggestions include eyes, face, hair, hands, mouth, and background. The panel hides itself when no segments are present. ## Regional prompting Open the **Regional Prompt** modal to paint regions on a canvas and give each one its own prompt and strength (0 to 2). Tools include select, box, circle, and lasso, with drag-to-create and 8-point resize handles, plus reorder/duplicate/delete and snap-to-grid. Two strategies are available: **conditioning** and **inpaint chain** (Anima models force the inpaint-chain strategy). ## Artists and characters - **Artists tab** (bottom panel): browse a server-hosted artist gallery, mark favourites, and insert artist tags. Inserting handles conflicts with any existing `@artist` tag (replace or add), and clicking an artist that is already in the prompt removes it again. Only the line holding that tag is rewritten; the rest of the prompt, including a NovelAI `Text:` block, stays as you typed it. The `@artist_name` syntax is normalized (underscores become spaces, parentheses are escaped). Favourite cards show the same preview image the Artists page does: switch every card with **Image 1** / **Image 2** in the tab toolbar, or one card with its ⇄ button. The choice is shared with the Artists page and remembered between sessions. The **No-preview** toggle also shows artists the model knows that don't have a CDN preview image yet; each of those cards has a ⚡ **Generate** action to render a preview locally using the same parameters the CDN previews used. - **Artist categories**: right-click any artist card to assign it to a category, or to create a new one. Cards with no category show a dashed "+" chip where the category dot would be, and the filter bar above the grid has a **New category** button. Once categories exist you can filter the grid by them, and searching stays inside whichever filter (including Favourites) is active. - **Sort and group favourites**: the Artists tab toolbar sorts favourites newest or oldest first, by name (A to Z or Z to A), or by most or fewest posts, and groups them by category or by first letter with collapsible headers. The choice is remembered. Right-clicking a favourite card also lets you open category management or unfavourite it. On the Artist Gallery page, a **Date Added** sort appears while the favourites filter is on. - **Animadex character browser**: search a character index filtered by copyright, hair color, hair length, eye color, and gender; sort by count or random; toggle "LoRAs only." Search includes characters with fewer than 50 posts and combines duplicate aliases. Selecting a character walks through a guided insertion flow that writes the character tags into your active prompt. Choose **Character name only**, **Name + series (copyright)**, or **Name, series, and appearance tags**. Inserting tags keeps existing subject counts and composition. When the flow offers **Add character** or **Replace character**, Add increases the girl count and changes solo to multiple girls; Replace keeps the scene's count and composition. Appearance tags do not add conflicting counts or solo tags. ## Artist Styles **Where:** open the bottom panel and pick the **Artist Styles** tab. An Artist Style is a named set of artist tags with a weight, saved so you can switch a whole look on and off in one click. Style Creator saves combinations with multiple artists here, and you can also build a style by hand in the style editor. **Favourite an existing single-artist style.** In v2.3.7 and later, a style containing one artist has a **Favourite artist** button. It adds the artist to **Artists** with the standard Miku preview and keeps the original style, its weights and its thumbnail. Existing favourites keep their category. Imported styles without a stored artist ID need a matching tag in the loaded Artists index before the button becomes available. **Thumbnails.** A style saved from Style Creator keeps the image it was picked from as its tile. Clicking the tile opens the picture full size in an overlay that covers the whole app, not just the bottom panel, and it loads the original gallery image rather than blowing up the small tile. If the gallery entry has been deleted the tile itself is shown instead. A style with no picture shows a **no thumb** tile that doubles as a **Generate thumbnail** button. It renders one image from whatever you currently have in the prompt boxes plus that style's artist tags, ignoring any other styles you have active, and saves the result as the tile. The style editor has the same action as **Generate**, next to **Use last gen** and **Upload**. Both are unavailable while a generation is already running, and on a style that has no artists in it. ## Style Creator **Where:** open the bottom panel and pick the **Style Creator** tab. It is available on the normal backend and on the NovelAI backend. Style Creator is for finding artist tag combinations you would never have thought to try. Each round it draws random artists from the Artists index, generates a candidate image per combination on one shared seed, and shows them full screen in a lightbox. A pick with multiple artists becomes a saved Artist Style with that image as its thumbnail. In v2.3.7 and later, a pick containing one artist becomes an artist favourite with the standard Miku preview. **A round:** 1. Press **Start**. Normally two cards generate using the same seed and generation settings, with different artist tags. NovelAI's **Two per round** toggle can reduce this to one. The lightbox opens straight away and shows a spinner until each image lands. 2. Move the mouse over the image to bring up the control bar at the bottom, and move away again to hide it. The bar has a view toggle: **Side by side** splits the frame between both cards, **One at a time** gives one card the whole frame. The choice is remembered for the next round. In one at a time mode, **Switch** flips to the other card and the left and right arrow keys do the same, with a counter next to the button showing which card you are on. A round that only drew one card always uses the whole frame. 3. For a combination with multiple artists, press **Pick** to save it, **Pick and edit** to save it and open the style editor, or **Save both** to keep both candidates. Single-artist cards instead show **Favourite artist**, with **Favourite both** when both candidates contain one artist. These cards have no style name or editor controls. **Skip** rejects the round and draws again. 4. Rounds keep coming until you press **Stop**, which is on the lightbox control bar as well as in the Style Creator tab. Stopping while a pair is on screen leaves that pair up, so you can still pick or skip it before the run ends. 5. **Start** resumes a stopped run. A round still waiting for a pick stays on screen until you pick or skip it. **Escape** closes the lightbox without ending the round. The Style Creator tab then shows a **Show round** button that puts it back on screen. **Settings in the Style Creator tab:** - **Anchor artists** - pin one or more artist tags that every card must include. Type a tag and press **Add**, or use **Load from style** to pull the artists out of a style you already saved. **Clear anchor** empties it. A tag that is not in the Artists index is kept as typed and marked in amber. - **Artists per combination** - how many artists each card gets. With an anchor set this becomes **Extra artists**, the number drawn on top of the anchor. A candidate with an anchor plus one extra artist still saves as an Artist Style because it contains multiple artists. In two-card rounds, the anchor is also shown on its own as **Anchor only** for comparison; picking that reference saves nothing. - **Favourites only** - draw only from artists you have favourited in the Artists tab. - **Vary weights** - give the drawn tags randomised weights instead of a flat 1.0, so the same set of artists can be tried at different strengths. - **Two per round** (NovelAI only) - on when you want both cards generated. Turn it off to generate one card per round and halve the Anlas spend. The badge next to it shows the estimated Anlas cost per round at your current settings. **What it will not repeat.** Every combination you pick or skip is remembered, and so is every Artist Style you have already saved. A combination counts as the same one regardless of tag order, so the same artists in a different order or reversed will not come back. Individual artists are free to reappear in new combinations. **Clear history** wipes the picked and skipped record, but saved styles stay blocked because you already have them. When nothing new can be drawn you get "Every combination has been tried", which means it is time to clear the history or change the settings. **Other behaviour:** - The artist pool skips anything already in your anchor or already in your positive prompt, and skips very low post count entries. - The seed is whatever you have pinned in the generation settings. If the seed is random, one seed is rolled per round and shared by both cards. - For combinations with multiple artists, the style name is pre-filled from the artists in the card (and from the source style, if the anchor came from one). Edit it in the box on the control bar before you pick. Typing in that box does not steal the arrow keys, so you can move the caret normally. - On the NovelAI backend the artist tags are written without the leading `@`, matching how NovelAI expects them. - On the NovelAI backend the two images are generated one after the other rather than at the same time, because NovelAI rate limits parallel generations. The lightbox says so while the second one is waiting. - Style Creator needs the Artists index, so an Artist Gallery manifest URL has to be configured. On the NovelAI backend it also needs a NovelAI API key in **Settings > NovelAI**. ## Image interrogation (reverse a prompt from an image) Open the interrogator from the sidebar button near the bottom of the left rail (tooltip: "Interrogate Image"). It opens a compact window with two choices, **Paste from Clipboard** and **Browse for Image**. You can also drag an image onto that sidebar button and hold for about a second to pop the window open, then drop the image on it to start. Either way the image runs through a WD v3-family ONNX tagger (EVA02 by default). The **Interrogator** section in Settings picks which tagger runs. The dropdown lists the built-in WD v3 models, which download on first use, and **Add custom tagger folder** registers any local folder that holds a `model.onnx` and `selected_tags.csv` pair from a compatible tagger. Custom entries are marked `(custom)`, can be removed from the same section without touching the files, and are validated when loaded, so a model whose input shape or tag list does not match is reported instead of producing garbage tags. The image stays in view beside the results (above them on narrow screens), uncropped, whichever way you opened it. Results are grouped into character/artist/general/copyright categories with confidence percentages and a content rating badge. Select the tags you want and apply them to your prompt as **replace** or **append**. Anima `@artist` tags are converted automatically. To interrogate an image already in your gallery, right-click it and choose **Get Image Tags** (see [[Gallery and Metadata]]). **Describe in words** below the tags writes a natural-language prompt for the image instead, for Flux, Krea, H3 and other models that read prose rather than tags. Pick **Short** or **Detailed** and press **Describe**. You can edit the result, **Copy** it, **Append to prompt** or **Replace prompt**. It uses the [[Prompt Assistant]] provider when one is set up (the model has to be able to see images); otherwise it uses a local model that can, **JoyCaption Beta One** when installed or **Qwen3-VL 4B Instruct**. With neither, the panel offers to install one. Installing one here does not change your prompt assistant model. The WD v3 taggers have no artist category, so **Detect artists (Kaloscope 3.0)** in Settings > Interrogator (on by default) fills it in: each interrogation also runs the Kaloscope 3.0 artist classifier (about 44,000 Danbooru artists) and adds up to 3 artists scoring at or above the **Artist Threshold** (default 0.10). The model is about 169 MB and downloads the first time. Guesses can be wrong, so check them before using them. The Artists section always shows: when no artist reaches the threshold it lists Kaloscope's closest guesses unticked (click one to add it), and when detection is off it says so with a **Turn on** button. **Detect saved characters** in the same section (also on by default) asks the [[Prompt Assistant]] which of your saved characters for the current model are in the image (see [[Generation Basics#characters-tab|Characters tab]]). Matches show as chips above the tags. Picking one switches off the tags its saved prompt already covers, and applying to the prompt inserts the saved character, into a NovelAI character box when there is room. Nothing is added until you pick one. It needs the prompt assistant to be set up. ## Prompt box editing The positive and negative prompt boxes support standard text editing plus a few extras: - **Right-click menu** - right-clicking anywhere in the box opens a context menu with Cut, Copy, Paste and Select all. - **Drag-select across tags** - you can drag-select across highlighted tags the same way you would select any text. - **Weights survive autocomplete and spell check** - accepting an autocomplete suggestion or a spell check fix no longer strips weight syntax around the tag. Forms like `-2::tag::`, `{tag}` and `(tag:1.2)` are preserved. ## Autocomplete As you type, MooshieUI suggests tags from the Danbooru and Anima tag databases (and any custom source you add). You can: - add a custom tag source by URL or file upload (JSON or CSV) - set the maximum number of suggestions (1 to 50) - enable the **clickable overlay**, which makes every tag in the prompt individually clickable so you can adjust its weight inline with +/- buttons (see [Weighting and emphasis](#weighting-and-emphasis) for how it preserves each syntax) Autocomplete is aware of scheduling brackets and will not trigger inside `<...>` tokens. **LoRA keywords first:** when a LoRA with trigger words is switched on, its matching keywords show at the top of the suggestions with a **LoRA** badge (hover to see which LoRA). They are the same words the LoRA gallery shows as chips. Picking one inserts it exactly as written, and in the main positive prompt it is removed again when you switch the LoRA off. Keywords are not offered in negative prompts. Turn this off in Settings > Autocomplete. **Tag spell check:** with this enabled in Settings, tags that aren't known Danbooru tags are underlined, and right-clicking one offers "did you mean" corrections from the Danbooru tag set. The browser's native spell check is disabled inside the prompt so it doesn't fight the tag checker. Spell check only runs for tag-based models (SDXL, Illustrious, Pony, SD 1.5, Anima) and NovelAI; natural-language models such as Flux, Krea and Qwen are not checked. Inside a tag prompt, lines that read as sentences are skipped. Common quality, year and score tokens (`masterpiece`, `very aesthetic`, `year 2024`, `score_9_up`) count as known. In NovelAI mode the checker also knows V5 custom tags, quality toggle tokens, `artist:` tokens, `source#` / `target#` / `mutual#` prefixes and `-N::tag::` weights, and skips the `Text:` block. ## Prompt history The **Prompts** tab in the bottom panel keeps your past generation prompts with timestamps. Mark entries as favourites (they float to the top), search the full text, and re-apply any entry with one click. Mobile has a dedicated prompt history page. ## Notes The **Notes** tab in the bottom panel is a freeform scratchpad for prompt ideas, parameter tweaks, and things to try. Notes save automatically as you type and persist between sessions; in browser/LAN mode they sync to your user profile so they follow you across devices, and the desktop app and browser mode on the same machine share them. ## See also - [[Prompt Assistant]] for AI-assisted prompt enhancement and composition - [[Generation Basics]] for the core controls --- # Anima Prompting How to write prompts for **Anima**, the 2B anime and illustration model from CircleStone Labs and Comfy Org, and what MooshieUI does with them for you. The rules here come from the official model card ([circlestone-labs/Anima on Hugging Face](https://huggingface.co/circlestone-labs/Anima)); the MooshieUI parts describe the current app. For the general prompt syntax (weights, random choices, blocks, presets) see [[Prompting Guide]]. Anima is built for illustration. It is not made for photorealism and only manages single words or short phrases of text in the image. ## Pick a version | Version | Use it for | Settings MooshieUI applies | |---------|-----------|----------------------------| | **Anima Turbo** | Fast prompt iteration. The model card recommends starting here: only slightly behind Aesthetic on average, more stable, with a stronger default style and less variety. | 10 steps, CFG 1, `euler`, `sgm_uniform` | | **Anima Aesthetic** | Polished final images in a consistent, higher quality default style. v1.0b is a plain aesthetic finetune without the merged style LoRAs; the author prefers v1.0. | 30 steps, CFG 4, `er_sde`, `sgm_uniform` | | **Anima Base** | Maximum flexibility, diversity and artist style adherence. Plain and neutral without quality or artist tags. Train LoRAs on this one. | 30 steps, CFG 4, `er_sde`, `sgm_uniform` | Selecting an Anima model applies these settings and shows the **Anima Recommended Settings** card in the sampler panel (see [[Generation Basics]]). The model card's own ranges are 30 to 50 steps at CFG 4 to 5 for Base and Aesthetic, and CFG 1 with 8 to 12 steps for Turbo. Resolutions between 512² and 1536² pixels work; MooshieUI starts at 1024 × 1024. **Samplers the model card likes:** - `er_sde`: neutral style, flat colours, sharp lines. A good default. - `euler_a`: softer, thinner lines, sometimes a 2.5D look. Tolerates a slightly higher CFG without burning. - `dpmpp_2m_sde_gpu`: like `er_sde` but more varied and "creative"; can get too wild on some prompts. - `euler`: a little more creative than `er_sde`. Good with Turbo and Aesthetic, which are already stable. For a more painterly look, turn on **Painterly textures (beta57)** in the sampler panel. It switches the scheduler to `beta57` from the RES4LYF node pack, which the model card suggests because it puts more emphasis on low-noise steps. ## Tags, natural language, or both Anima was trained on Danbooru-style tags, natural language captions and mixtures of the two, so all three work. - Write tags in **lowercase with spaces**, not underscores: `long hair`, not `long_hair`. Score tags are the only exception (`score_7`). - When Danbooru and Gelbooru name a tag differently, use the **Gelbooru** version. - The model was trained with random tag dropout, so you do not need every relevant tag. - Natural language works best when it is descriptive: aim for at least two sentences. Very short prose prompts give unexpected results. - Use normal English capitalisation for character and series names in prose. - Tags and prose mix in any order, and quality or artist tags can lead a prose prompt: `masterpiece, best quality, @artist name. An anime girl with medium-length blonde hair is...` ## Tag order The model card's order is: ```text [quality / meta / year / safety] [1girl / 1boy / 1other ...] [character] [series] [artist] [general tags] ``` Inside each section the order does not matter. A full example from the model card: ```text year 2025, newest, normal quality, score_5, highres, safe, 1girl, oomuro sakurako, yuru yuri, @nnn yryr, smile, brown hair, hat, solo, fur-trimmed gloves, open mouth, long hair, gift box, fang, skirt, red gloves, blunt bangs, gloves, one eye closed, shirt, brown eyes, santa costume, red hat, skin fang, twitter username, white background, holding bag, fur trim, simple background, brown skirt, bag, gift bag, looking at viewer, santa hat, ;d, red shirt, box, gift, fur-trimmed headwear, holding, red capelet, holding box, capelet ``` ## Special tags | Kind | Tags | |------|------| | Quality (human rated) | `masterpiece`, `best quality`, `good quality`, `normal quality`, `low quality`, `worst quality` | | Quality (aesthetic model) | `score_9` down to `score_1` | | Year | `year 2025`, `year 2024`, ... | | Period | `newest`, `recent`, `mid`, `early`, `old` | | Meta | `highres`, `absurdres`, `anime screenshot`, `jpeg artifacts`, `official art`, ... | | Safety | `safe`, `sensitive`, `nsfw`, `explicit` | You can use the human quality tags, the score tags, both, or neither. Put a safety tag in the positive prompt (and the ones you do not want in the negative): the model card warns that short or vague prompts can produce unwanted content otherwise. ### Artists need an @ Write artist tags with an `@` in front, for example `@big chungus`. Without the `@` the effect is very weak. MooshieUI's Anima prompt box shows a reminder, the Artists tab inserts the `@` for you, and image interrogation converts artist tags to the `@` form (see [[Prompting Guide#artists-and-characters|Artists and characters]]). ### Weights need to be higher than on SDXL Prompt weighting works, but Anima needs stronger weights than SDXL to show an effect, for example `(chibi:2)`. All the weight forms in [[Prompting Guide#weighting-and-emphasis|Weighting and emphasis]] are converted to this syntax when the prompt is sent. ## Quality tags in MooshieUI With **Auto-apply quality tags** on (Settings > Performance, see [[Settings and Accessibility]]), MooshieUI adds Anima's quality tags at send time. Your prompt box stays as you typed it. | | Default tags MooshieUI adds | |-|----------------------------| | Positive | `newest, masterpiece, best quality, score_9, score_8, safe, highres` | | Negative | `worst quality, low quality, score_1, score_2, score_3, blurry, jpeg artifacts, sepia` plus MooshieUI's standard negative tags | **Customize quality tags** in the same section lets you replace them. The model card's own suggestions, if you prefer them: - Positive prefix: `masterpiece, best quality, score_7, safe, ` - Negative: `worst quality, low quality, score_1, score_2, score_3, artist name, blurry, jpeg artifacts, chromatic aberration` **Anima Aesthetic** was fine-tuned on high quality images with every quality tag removed from the captions. The model card advises against `score_*` tags in both prompts because they push it into "slop territory", so MooshieUI strips the score tags from the injected set when the model file name contains `aesthetic`. `masterpiece, best quality` stays, which the model card says is safe. Anima Light Lavender, a community fine-tune of Base trained on natural language captions, gets no quality tags and runs at 25 steps, CFG 4, `euler`, `simple`, as its author recommends. ## Natural language and several characters Name a character, then describe what they look like. The model card's example: ```text Digital artwork of Fern from Sousou no Frieren, with long purple hair and purple eyes, wearing a black coat over a white dress with puffy sleeves... ``` This matters most with several characters: a bare list of names confuses the model, a name plus a short appearance for each does not. For placing characters in separate parts of the image, MooshieUI's **Regional Prompt** works on Anima through the inpaint-chain strategy (see [[Prompting Guide#regional-prompting|Regional prompting]]). ## Non-anime styles: dataset tags Besides anime, Anima saw about 800k non-photo artworks from LAION-POP (ye-pop) and DeviantArt. Those captions start with a **dataset tag** on its own line, optionally followed by the alt text (ye-pop) or the title of the work (DeviantArt) on the second line: ```text deviantart Flame Digital painting of a fiery dragon with glowing yellow eyes, black horns, and a long, sinuous tail, perched on a glowing, molten rock formation. The background is a gradient of dark purple to orange. ``` ```text ye-pop For Sale: Others by Arun Prem Abstract, oil painting of three faceless, blue-skinned figures. Left: white, draped figure; center: yellow-shirted, dark-haired figure; right: red-veiled, dark-haired figure carrying another. Bold, textured colors, minimalist style. ``` On ComfyUI, MooshieUI turns line breaks into `, ` when it sends a prompt (see [[Prompting Guide#additive-prompt-blocks|Additive prompt blocks]]), so the dataset tag reaches the model followed by a comma rather than a newline. It still leads the prompt, which is the part the model card stresses. Leave auto quality tags off for these prompts if you want the dataset tag to come first, because the quality tags are added at the front. ## Anima tools in MooshieUI - **Anima Reference Adapter**: keeps a character from a reference image; describe only the scene. See [[ControlNet and Style Transfer]]. - **Style transfer (Untwisting RoPE)**: training-free style transfer from a reference image, Anima only. See [[ControlNet and Style Transfer]]. - **Anima ReStyler** in Image Edit redraws a character from a reference in the Anima style. See [[Image Edit Mode]]. - **ControlNet (Anima LLLite)** needs ComfyUI 0.29 or newer. - **TeaCache** and the community **RDBT-Anima LoRA** speed up generation. See [[Generation Basics]]. - **Autocomplete** suggests tags from the Anima tag database alongside Danbooru's. ## Training LoRAs From the model card, for anyone training on Anima Base: - **Do not train the LLM adapter.** It shapes the text embeddings before they reach the diffusion model and is easy to degrade. In diffusion-pipe set `llm_adapter_lr=0` (the example config does); other trainers have similar options. - Use a low learning rate. For a rank 32 LoRA, start at `2e-5` and adjust. ## License Anima is under the CircleStone Labs Non-Commercial License. The model and its derivatives are non-commercial, but the images you generate can be used commercially. See the model card for the details. ## See also - [[Prompting Guide]] - [[NovelAI Prompting]] - [[Models and the Model Hub]] - [Anima model card](https://huggingface.co/circlestone-labs/Anima) --- # NovelAI Prompting How to write prompts for NovelAI Diffusion V5 and V4.5/V4 in MooshieUI. The prompting rules come from NovelAI's official documentation at [docs.novelai.net](https://docs.novelai.net/en/image/basics); the MooshieUI parts describe what the app does with your prompt. For setup, models, costs and the options panel see [[NovelAI Backend]]. ## The basics - **Tags, prose, or both.** NovelAI understands Danbooru-style tags and full sentences, and you can mix them. Tag suggestions in NovelAI's own site show how well the model knows a tag; MooshieUI's autocomplete draws on the Danbooru tag database (see [[Prompting Guide#autocomplete|Autocomplete]]). - **Important things first.** Keep the subject and what matters most in the front half of the prompt. NovelAI's suggested order is `1boy, 1girl, characters, series, everything else`. On V3 and older, earlier tags weigh more; V4 and later are less sensitive to order, but the convention still helps. - **Mind the length.** Each model has a token limit, and MooshieUI shows a counter under every prompt box against it. | Model | Prompt limit (NovelAI) | Text rendering limit | |-------|-------------------------|----------------------| | V5 Full | about 1,471 tokens over the base prompt | 750 characters | | V5 Curated | about 703 tokens over the base prompt | 374 characters | | V4.5 Full, V4 Full | about 512 T5 tokens over the base prompt and all character prompts combined | 118 characters | V4.5 and V4 use the T5 tokenizer, which does not support most Unicode characters (emoji, Japanese). V5 supports prompting in Japanese and other languages. ## Special tags | Kind | Tags | Models | |------|------|--------| | Quality | `best quality`, `amazing quality`, `great quality`, `normal quality`, `bad quality`, `worst quality` | All | | Aesthetic | `masterpiece` (V4.5+), `top aesthetic` (V4+), `very aesthetic`, `aesthetic`, `displeasing`, `very displeasing` | As noted | | Complexity | `low complexity`, `medium complexity`, `high complexity`, `ultra complexity` | V5 | | Year | `year 2014` (any year) | All | | Dataset | `fur dataset` (V4+), `background dataset` (V4.5+), at the very start of the base prompt | As noted | | Transparency | `transparent background`, `has alpha`, `alpha transparency` | V5 | | Other | `location` (indoors or outdoors, unspecified), `depthness`, `attractive male`, `meta:novel era`, `meta:golden era`, `visual novel art` / `bg` / `cg` / `chibi` / `sprite` | `location` all, the rest V5 | NovelAI suggests `high complexity` for normal, good-looking images; `ultra` and even `low` can suit stylised ones. Some tags were renamed because `|` is reserved: write `peace sign` (not `v`), `double peace`, `bar eyes`, `open \m/`, `neutral face`, `neco-arc eyes`, `square bikini` (not `eyepatch bikini`) and `character image` (not `tachi-e`). **Transparent backgrounds.** On V5, MooshieUI's **Transparent BG** option asks for a real alpha channel, like NovelAI's toggle. You can also prompt the tags yourself; NovelAI notes that strengthening helps, for example `2.1::transparent background::`. **Artists.** Write the artist's name as a plain tag. MooshieUI removes an `artist:` prefix before the request goes out (see [[NovelAI Backend#models|Models]]), and the `@` prefix used for Anima is not added on NovelAI, because `@` starts a Prompt Chunk reference there. ## Emphasis | Syntax | Effect | Models | |--------|--------|--------| | `{tag}` | × 1.05 per pair, nests: `{{tag}}` is × 1.1025 | All | | `[tag]` | ÷ 1.05 per pair | All | | `1.5::rain, night ::` | Numeric weight for everything up to the closing `::` | V4+ | | `0.5::coat ::` | Numeric weakening (between 0 and 1) | V4+ | | `-1::hat ::` | Negative emphasis: removes or inverts a concept | V4.5+ | A bare `::` also closes any open braces, so `{{{{{rain ::` needs no counting. In Undesired Content the meaning flips: `{}` avoids a tag more, `[]` less. **Negative emphasis** is NovelAI's targeted alternative to Undesired Content. `-1::hat ::` (or `-3::hat ::` for a stubborn hat) takes off a character's usual hat; `-1::monochrome ::` brings colour back; `-2.5::flat color ::` adds detail; `-1::simple background ::, location` gets characters out of a white void. Use Undesired Content for long lists of things to avoid, and negative emphasis for one concept at a time. **What MooshieUI converts.** You can write ComfyUI-style weights on NovelAI too. When the prompt is sent, `(tag:1.2)` becomes `1.2::tag::`, and weights of exactly 1.05 and 0.95 become `{tag}` and `[tag]`. NovelAI syntax such as `1.2::rain, night::` or `-1::hat::` is sent exactly as written, and prompts imported from NovelAI images keep their NovelAI syntax. Your prompt box keeps what you typed. See [[Prompting Guide#weighting-and-emphasis|Weighting and emphasis]] for every accepted form. ## Quality tags and Undesired Content presets The **Quality tags** option in the NovelAI options panel appends NovelAI's quality tags to the end of the prompt, the way NovelAI's own toggle does. They do not show in your prompt box but count against the token limit. | Model | Standard | Light | |-------|----------|-------| | V5 Full, V5 Curated | `, very aesthetic, masterpiece, no text` | `, very aesthetic, amazing quality, no text` | | V4.5 Full | `, location, very aesthetic, masterpiece, no text` | Not offered | | V4 Full | `, no text, best quality, very aesthetic, absurdres` | Not offered | These match NovelAI's own toggle for every model. Up to v2.3.41, MooshieUI left the leading `location` out on V4.5 Full; releases after v2.3.41 include it. The **Undesired content preset** (Heavy, Light, Human focus, Furry focus, or None) puts NovelAI's preset tags ahead of your own Undesired Content. The panel only lists what the selected model supports. On V5 Full with **Effort: Medium**, the preset is fixed to Heavy and your own Undesired Content is not sent, so use negative emphasis instead. ## Several characters V4 and later can keep characters apart: a **base prompt** for the scene and style, and one **character prompt** per character. V5 takes up to 22 characters, V4.5 and V4 up to 6. In MooshieUI these are the boxes in the **Characters** panel (see [[NovelAI Backend#characters|Characters]]). - Put the **count tags** in the base prompt (`2girls, 1boy, outdoors`), and start each character prompt with `girl`, `boy` or `other` without a number. - Characters are placed in list order, top to bottom and left to right, unless you set positions. With **Position: Custom**, MooshieUI's position editor works like NovelAI's; V4 and V4.5 snap to a 5 × 5 grid. NovelAI advises keeping positions consistent with the list order and backing them up in the prose. - If something leaks from one character to another, use that character's own negative box. - **Action tags** say who does what: `source#hug` on the hugger, `target#hug` on the one being hugged, `mutual#hug` on both. NovelAI notes these are not always reliable. - NovelAI's site also accepts `|` to separate the base prompt from character prompts in one box, but only when no character boxes exist. Prompt mixing with `|` is V3 and older only. ## Text in the image V4 and later can render text; V5 handles English, Japanese and Chinese, V4.5 and V4 English only. 1. Add `text, english text` to the prompt. 2. End the base prompt with `Text:` followed by the words. `Text:` must be the very last thing, or whatever follows it may appear in the image. Separate several strings with a blank line. 3. Describe in prose how and where the text should look, unless tags like `speech bubble` already make that clear. Repeating the text in the prose helps reliability. **In MooshieUI** on V5, anything in quotes in the prompt is turned into a `Text:` block for you, and tags the app adds (style presets, Artist Styles, Prompt Chunks, Transparent BG) are placed ahead of it. Prompts sent to NovelAI keep their line breaks, so a hand-written `Text:` block arrives as typed. See [[NovelAI Backend#models|Models]]. If short text does not appear, set Quality tags to None: the quality tags include `no text`. On V4, writing the text in capitals can help spelling. ## Steps, guidance and samplers Picking a NovelAI model sets 23 steps, guidance 7, Euler Ancestral and Karras. NovelAI's guide suggests guidance around 5 to 6 on V3 and later as a starting point: lower is softer and more painterly, higher is sharper but can overcook. **Dynamic thresholding** in MooshieUI (NovelAI calls it Decrisper) and **Guidance rescale** tame colour problems at high guidance. Keep steps low while you look for a composition, then refine the one you like with **Enhance** (see [[NovelAI Backend#enhance-upscale-and-variations|Enhance, Upscale and Variations]]). On Opus, NovelAI does not charge Anlas for single images at 28 steps or fewer at normal sizes (V5 has a usage limit on these). **Effort** (V5 Full only): **Medium** runs NovelAI's distilled model at 14 steps with Euler Ancestral, for about 40% less cost. Guidance still applies, guidance rescale does not, and Undesired Content is fixed as described above. ## Image references - **Vibe Transfer** (V4 and V4.5 in MooshieUI) carries the mood, colours and style of up to 16 images. Keep all strengths adding up to 1 or less (**Normalize strengths** does it for you). Lowering **Information extracted** drops fine texture first, keeping more composition and less style; it also helps when a reference's plain background keeps leaking in. Encoding a vibe costs 2 Anlas, and each vibe beyond four adds 2 Anlas per image. - **Precise Reference** (V4.5) copies a character, a style, or both. **Strength** is how much the reference is followed (high values copy pose and expression too); **Fidelity** is how hard it is to override from the prompt. 5 Anlas per reference per image. It cannot be combined with Vibe Transfer. ## See also - [[NovelAI Backend]] - [[Prompting Guide]] - [[Anima Prompting]] - NovelAI docs: [Tagging](https://docs.novelai.net/en/image/tags), [Strengthening and weakening](https://docs.novelai.net/en/image/strengthening-weakening), [Quality tags](https://docs.novelai.net/en/image/qualitytags), [Undesired Content](https://docs.novelai.net/en/image/undesiredcontent), [Multi-character prompting](https://docs.novelai.net/en/image/multiplecharacters), [Text rendering](https://docs.novelai.net/en/image/textrendering), [Effort](https://docs.novelai.net/en/image/effort), [Vibe Transfer](https://docs.novelai.net/en/image/vibetransfer), [Precise Reference](https://docs.novelai.net/en/image/precisereference), [Models](https://docs.novelai.net/en/image/models) --- # Prompt Assistant MooshieUI's Prompt Assistant writes, edits and polishes prompts using a local llama.cpp GGUF server, a configured external LLM endpoint, or an official account sign-in companion. With the local backend, inference runs on the machine hosting MooshieUI. With an external endpoint, prompts and any attached reference images are sent to that endpoint. ## What it does The **Enhance** button above the prompt box opens a chat window. Applying an answer closes it, and pressing **Enhance** again reopens the same conversation. Long chats show the newest 12 exchanges, with **Show earlier messages** to load the rest. With a NovelAI V5 model the button reads **Enhance for V5** (see [[NovelAI Backend]]), and in Video it reads **Enhance for H3** (see [[Video Generation]]). All three work the same way: - **Edit current prompt** ticked, box empty: rewrites and improves your current prompt. - **Edit current prompt** ticked, with text: applies your text as a change, for example "make it a rainy night". Anything the change does not mention stays as it was, and a tag you ask to remove stays removed. - **Edit current prompt** unticked: writes a new prompt from your description. **Copy existing prompt** pastes your current prompt into the box. For image models you also choose a **Length** (Short, Medium or Detailed) and whether to **Include artists**. **Use memory notes** (Enhance and Enhance for V5, shown when saved characters have memory) is ticked each time the chat opens. Untick it when a composition keeps failing: that rewrite sends no memory notes and learns nothing, so it works from your text and the saved looks alone. Facts a rewrite learns are saved to memory only when you apply it. **Reference images** attaches up to four pictures to point at, for example "use the outfit from image 1". Add them with **Upload**, **Paste** or **Gallery**, with an optional **Label** each. They need a model that can see images: a vision-capable model on an external provider, or the local Qwen3-VL 4B Instruct model. Other local models cannot see them and write from your text alone. Nothing changes until you choose. Each answer arrives in the chat and you can ask follow-up questions or give feedback before applying it. When an answer is ready, the action buttons appear: - **Replace** swaps your prompt for the new one. - **Append** adds it after your current prompt (not offered for H3). - **Apply** applies the answer directly. - **Review** opens the side-by-side review for V5 rewrites, where you can pick individual fields before applying. **Undo** next to the Enhance button reverses the last apply. Pressing **Stop** while an answer is generating cancels it. For models that accept natural-language prompts (Krea 2, Flux, Z-Image, Chroma, Qwen-Image, and similar), Enhance writes full sentences instead of danbooru-style tags. Names, counts and positional descriptions (left/right) are preserved in prose form. Tag upsamplers such as DanTagGen still write tags regardless of the loaded model. ## Sessions The assistant remembers the conversation. **Enhance**, **Enhance for H3** and **Enhance for V5** each keep their own session, so a follow-up such as "make it night" builds on the previous answer instead of starting over. Sessions survive closing the panel and restarting the app; in LAN mode each account has its own. Once a session has history, the panel shows a **New chat** button to start over. When a session grows too long for the model, the oldest exchanges are left out of the request (the window says **older ones not sent**) but stay saved. Since v2.3.42 only a rewrite you apply joins the session: closing the review without applying leaves it out, and **Undo** takes it back out. An answer that failed its format check or was cancelled is not remembered. A tag-only local model such as DanTagGen never receives the session. ## Minors and explicit content Enhance, Remember, Update, Use and Write with AI refuse to send a request that pairs a clear minor (child, kid, schoolgirl, an age under 18, or a saved character marked as a minor) with explicit words in what you typed. In all three Enhance flows (since v2.3.42) the check also covers the prompt being edited and your earlier requests in the session, since those are sent too. Since v2.3.40 the check never reads saved memory notes, so a note mentioning a character's age cannot block an unrelated request. Suggestive words alone, ambiguous words, and phrases such as "minor changes" or "remove all sexual content" do not trip it. The refusal names the words that tripped it. Since v2.3.41, anything that writes memory notes (Remember, Write with AI, Update suggestions and the V5 memory field) states a character's age as what it is ("an adult", "24 years old"), never as what it is not, and rewrites an old line that does. Notes already worded like "not a child or a teenager" or "no longer a child" are read as negations and do not count as a minor. ## Music writing In Music, **Enhance style** and **Generate lyrics** use the configured assistant with YuE2 writing guidance. Generate lyrics opens a topic popup and uses the current style and **Max length**. **Use existing lyrics as context** is unchecked by default; check it to revise a draft. Fresh lyric requests exclude the existing lyrics and earlier songs. Style enhancement can use the current lyrics as context. Undo restores the previous field. **Edit composition** also uses this assistant with guidance adapted from the upstream yue2-music skill. It proposes complete score, style and lyric edits, then checks the preservation constraints you selected before offering Apply to draft. The lyric budget leaves room for breathing, instruments and an ending, but sung timing is approximate. See [[Music Generation]] for the full workflow, library and manual lyric timing. ## How it runs - With a local model selected, the assistant starts a llama.cpp server on demand. - It is hardware-aware: it offloads layers to the GPU when there is room and falls back to CPU if ComfyUI is already using your VRAM. - The local server runs with a 16k context so sessions fit. That takes roughly 0.7 to 1.7 GB more VRAM than before, which the GPU check accounts for; on a 4 GB card the recommended model now runs on the CPU. - An idle watchdog stops the server automatically when it has not been used for a while, freeing memory. ## External LLM endpoint If you'd rather not use the bundled local model, turn on **External LLM endpoint** in Settings and pick a **Provider**: - **ChatGPT (subscription)** - **Gemini (Google sign-in)** - **Anthropic (Claude)** - **OpenAI** - **xAI (Grok)** - **xAI (Grok, SuperGrok sign-in)** - **OpenRouter** - **Nous Research** - **Self-hosted (OpenAI-compatible)** for LM Studio, Ollama, vLLM, and anything else that speaks the OpenAI chat API. The API-key providers come with their base URL and a default model already set, so all you add is a key. Only the self-hosted option shows an **API base URL** field. A bare base URL that omits the `/v1` path works (for example `http://localhost:11434`); the app retries at `/v1/chat/completions` automatically and also accepts a fully pasted `.../chat/completions` endpoint. ### Keys and sign-in Paste a key into **API key** and it is saved on the machine running MooshieUI, never in the browser. Once saved the field shows **Key saved** and stays empty; pasting a new key replaces it, and **Clear** removes it. Keyless local servers need no key at all. The instance owner can instead choose **Use an environment variable instead** and name a variable that holds the key, so it is never written to disk; see [[Settings and Accessibility]]. Sign-in starts from the desktop app, where the provider can open its browser login flow. Browser clients cannot start that flow. - **OpenRouter** opens your browser, completes the sign-in, and stores the key it issues. That key does not expire. - **Nous Research** registers this install as its own OAuth client and signs you in the same way. It issues a short-lived token rather than a key, so the app refreshes it in the background and you stay signed in. - **xAI (Grok, SuperGrok sign-in)** is a device code flow: the app shows a code to enter on the xAI sign-in page. This is what lets a SuperGrok subscription pay for inference instead of prepaid API credits. xAI hands out OAuth client ids by arrangement and has issued none to this project, so sign-in uses the public client id of xAI's own CLI, the same one other third-party Grok clients use, which means the consent screen names xAI's app rather than MooshieUI. **xAI OAuth client ID (optional)** overrides it if you have been issued one, and **Scope (optional)** goes with it. Neither is a secret. Whether an account may mint a token at all is decided per account, so some accounts are refused whichever client id is used. **xAI (Grok)** without the sign-in is still there as the plain API-key provider. ### ChatGPT and Google account sign-in Account sign-in is available in v2.3.6 and later. Choose **ChatGPT (subscription)** or **Gemini (Google sign-in)**, then **Sign in**. MooshieUI downloads a pinned, checksum-verified official companion into its own data directory. Setup needs no global CLI installation or manual token copying. **Cancel** stops a pending sign-in; **Sign out** removes this app's local account storage. Your separately installed provider tools keep their own sign-ins. ChatGPT uses the official Codex app server for text and images. Google uses the official Antigravity ACP companion for text, images and music audio-style analysis. Account eligibility and usage limits apply. ChatGPT subscription sign-in does not accept music audio analysis, and Claude retains its API-key route. Leave **Model** empty to use the companion default, or choose **Load models**. Submitted prompts and attachments go to the selected provider. Agent tools are disabled. Temporary request workspaces and local conversation caches are cleaned after requests; login state remains until sign-out. A browser/server deployment can use an account already configured on the same host and app-data directory. It uses the host operator's account, not a separate subscription for every browser user. Provider settings still require moderator permission. See the [account sign-in guide](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/PROMPT-ASSISTANT-SIGN-IN.md) for supported platforms and validation limits. ### Model **Model** is a free-text field with suggestions. **Load models** asks the endpoint for its model list and fills the suggestions; endpoints that do not publish a list still work if you type the model id yourself. Switching provider clears the stored key and resets the base URL and model to that provider's defaults, so keys never travel from one provider to another. Signing out clears the stored token along with it. Reference images in the Enhance window need a model that can see images: a vision-capable model on an external provider, or the local **Qwen3-VL 4B Instruct** model. ### Reasoning effort **Reasoning effort** sets how long models that think before answering spend thinking: **Low (fastest, recommended)**, **Medium**, **High (slowest)** or **Model default**. It shows only for providers whose models accept an effort, and each model gets the nearest level it supports. Low is the default and suits prompt work. Before v2.3.34 no effort was sent, so some models (Grok 4.6 and 4.7, for example) thought at their slow default and often timed out. Thinking models also get a longer timeout and extra room in their answer budget. ### Fallback models For API-key providers, **Fallback models** lists up to 4 more models on the same provider, separated by commas. They are tried in order when the model above times out, is rate limited or its server fails. A refusal (bad key, missing model, content policy) is not retried on another model. Switching provider clears the list. Sign-in companions (ChatGPT, Gemini) do not show it. **Fall back to the local model** goes one step further: when the provider cannot answer at all, an installed local writing model answers instead (never DanTagGen), without the reference images. ## Hosted / Docker notes - In GPU Docker builds you can point the assistant at a specific llama.cpp binary directory with the `MOOSHIEUI_LLAMA_BIN_DIR` environment variable. - On multi-GPU hosts you may want to pin the llama server to a specific device (for example `CUDA_VISIBLE_DEVICES`) so it does not compete with ComfyUI. - The model used by the assistant is configured by the deployment. If no assistant model is configured, a fallback tag-generation model may load instead. ## See also - [[Prompting Guide]] for wildcards, presets, scheduling, and the rest of the prompt system. --- # NovelAI Backend MooshieUI can generate through NovelAI's image API as a second backend alongside ComfyUI. Paste an API key in Settings and four NovelAI models appear in the normal model dropdown. Selecting one switches the whole generation page over: the controls NovelAI does not have are hidden, and NovelAI's own controls take their place. Generations run on NovelAI's servers and may spend Anlas depending on the request and your allowance. Gallery and comparison tools remain available; local upscaling and face detection need a running ComfyUI. Image Edit, video and sampling pause/continue are ComfyUI features. ## Setup 1. In NovelAI, open **User Settings, Account** and create a persistent API token. 2. In MooshieUI, open **Settings, NovelAI** and paste it into **API Key**, then **Save**. 3. The saved-key field stays blank and shows its configured status. **Clear** removes it. Personal account keys are encrypted; desktop/admin keys remain in the owner's app config and are accessible to trusted admins. The same section shows your **Anlas** balance, whether an **Opus subscription** is active, and your remaining **Opus Generation Allowance** with the daily refill rate. V5 is not covered by Opus unlimited: its free generations come out of that allowance, so once it is empty a V5 generation costs real Anlas until it refills, and the cost badges say so. V4.5 and V4 keep the unconditional Opus discount inside the 1MP, 28-step window. **Refresh** re-checks with NovelAI. Turn on **Show Anlas above the generate button** to pin a compact version of that readout to the generation page. **Saved keys:** under **Saved keys**, name a key and save it to keep several NovelAI accounts at hand. **Use** switches to a saved key and **x** forgets it; saving a key does not switch to it. With two or more saved, a small account picker appears on the Anlas line above Generate. Saved keys are kept in their own file, out of the app config, and the app only ever shows a name and the last four characters. Saved keys are for the owner; hosted accounts keep their single key. **Paid-through date:** the account panel shows "Paid through" with the date and days left, from NovelAI's subscription data. For a renewing plan that is the next renewal; for a cancelled one it is the end date. The Anlas line shows the days left too, in amber for the last three days. ## Hosted accounts On a shared server, regular users and moderators each add their own key in **Settings, NovelAI**. **Save** changes only that account's key, and **Clear** removes only that account's key. Without one, the NovelAI models are hidden and NovelAI requests fail without using the host's subscription. Account keys are encrypted on the server and survive a restart. Deleting an account removes its key even when its gallery is kept. Moderators can manage shared settings but cannot read or replace the host's NovelAI key through those settings. The desktop app, localhost connections, and admin-role accounts use the instance owner's key in the existing app config. Promoting an account to admin switches it to that owner key; demoting it restores use of its own saved key. Server operators can supply `MOOSHIEUI_SECRET_KEY` as base64-encoded 32 bytes. Otherwise, MooshieUI creates `secrets.key` in its data directory. Keep that master key with a recoverable backup, or users must enter their NovelAI keys again. For hosted deployments, supply it through a secret store separate from the account-data volume. ## Models Four entries join the model dropdown: - **NovelAI V5 Full** - **NovelAI V5 Curated** - **NovelAI V4.5 Full** - **NovelAI V4 Full** The three Full models show an **18+** pill in the model picker. V5 Curated has none. | Model | Character slots | Vibe Transfer | Precise Reference | Transparent BG | |-------|-----------------|---------------|-------------------|----------------| | V5 Full / Curated | 22 | Disabled in this release | Disabled in this release | Yes | | V4.5 Full | 6 | Yes | Yes | No | | V4 Full | 6 | Yes | No | No | Per-character prompts, Vibe Transfer and Precise Reference are per-model capabilities. Where a model does not support one, the panel says so instead of letting you build a request that would be rejected. Picking a NovelAI model applies NovelAI's recommended sampling defaults: 23 steps, guidance 7.0, Euler Ancestral, Karras, guidance rescale 0. **Text in the image (V5).** On a V5 model, anything you put in quotes in the prompt is automatically formatted the way NovelAI's own site formats text to render, so `a sign saying "open"` works without extra syntax. Straight quotes, curly quotes and Japanese corner brackets are all recognised. If you write your own `Text:` line in the prompt, the automatic formatting stays out of the way. Prompts sent to NovelAI keep their line breaks, so a `Text:` line followed by the words to render on the next line reaches NovelAI as you typed it, and a blank line separates one rendered string from the next. Tags the app adds on its own, from a style preset, an active Artist Style, a Prompt Chunk or **Transparent BG**, are spliced in ahead of the `Text:` block, so nothing lands in the lettering. **The `artist:` prefix is dropped on the way out.** Danbooru tags its posts with the bare artist name, so `artist:` is a search box filter the model was never trained on and it only spends tokens. MooshieUI strips it from the base prompt, the undesired content, and every character prompt and undesired content box before the request goes to NovelAI. It is only removed at the start of a tag, so `artist name`, `artist_name` and `subartist:` are left alone, and anything inside a `Text:` block is handed over byte for byte. Your prompt boxes and the metadata saved with the image keep exactly what you typed. **V5 Curated inpainting** currently runs on V4.5 Curated's inpainting model, because V5 Curated's own is still training upstream. NovelAI's own client does the same. ## Characters NovelAI keeps characters apart rather than blending them into one description. The **Characters** panel gives each one its own positive and negative box, so "one in a red coat, one in a blue coat" stays that way. **Position** decides who stands where. **Let NAI decide** leaves the placement to NovelAI. **Custom** turns on explicit positions and adds an **Edit positions** button, which opens a canvas drawn at the aspect ratio you have selected, with one numbered circle per enabled character. Drag a circle anywhere on it, or tab to one and nudge it with the arrow keys. Characters dropped on top of each other are flagged, because overlapping placements tend to come back as low quality results. The panel itself can be dragged wider, and a double-click resets its width. V5 seats up to 22 characters; V4.5 and V4 stop at 6. The **Add** button disables at the cap and the panel states the number when you reach it. Positioning is only honoured with two or more characters. With a single character, V5 centres the subject regardless of where the circle sits, and NovelAI's own site behaves the same way. ## Image references Two reference types, and they cannot be combined. Adding to one clears the other. - **Vibe Transfer** carries the mood, palette and style of a reference image into the result. Each new image costs Anlas to encode, and the panel shows the amount before you commit. **Normalize strengths** scales multiple vibes so they add up to 1, matching the option in NovelAI's own client. - **Precise Reference** copies a character or a style with more control than Vibe Transfer. Each image picks what to take from it (Character, Style, or Character and style) and carries a **Strength** slider and a **Fidelity** slider, where Fidelity is how closely the result follows the reference image. Reference images are reshaped to one of the three canvas sizes NovelAI's encoder accepts before they are sent, so you can use any aspect ratio and the image you are generating is unaffected. Each Precise Reference costs 5 Anlas per image, even on Opus, and the cost estimate includes it. ## NovelAI options The **NovelAI options** panel carries the settings that only exist on this backend: - **Quality tags**: Standard, Light, or None. Appends NovelAI's own quality tags to the prompt the same way the official client does. Light is offered on V5 models only. - **Undesired content preset**: Heavy, Light, Human focus, Furry focus, or None. The preset's tags are put ahead of your undesired content before sending. Both dropdowns list only what the selected model supports. - **Effort**: **Medium** or **High**, shown for V5 Full only. Medium runs NovelAI's distilled V5 Full checkpoint, which NovelAI says costs about 40% fewer Anlas at comparable quality. It fixes 14 steps, Euler Ancestral and the Heavy undesired content preset; your own undesired content is not sent on Medium, so steer unwanted content with negative emphasis in the prompt instead (for example, `-3::hat::`). CFG rescale is also disabled on Medium. High is the default. Face-detail crops always run at High. - **Variety+** adds variation to the first steps for livelier compositions. - **Dynamic thresholding** reins in oversaturated color at high guidance. - **Guidance rescale** and **Undesired content strength**. Setting the latter to anything other than 1.00 costs 30 percent more Anlas, and the panel says so. - **Legacy undesired content** for matching older images. - **Transparent BG** on V5 asks for a real alpha channel. Local post-processing and face detailing are skipped when it is enabled to avoid flattening transparency. A token counter sits under each prompt box, showing the estimate against NovelAI's limit. ## Cost The generate button shows an **estimated** Anlas cost before submission. Estimates are calculated by the app, not a billing quote from NovelAI. Check your refreshed balance/allowance for actual usage; face crops, vibe encoding and enhancement operations can add their own costs. **Repeat warning:** if a request is identical to the last one sent (fixed seed, same settings), the first Generate click shows a warning and a second click sends it, so a duplicate never spends Anlas by accident. ## Queueing NovelAI runs one image request per account at a time. In v2.3.36 and later MooshieUI sends queued NovelAI generations one after another per account, in queue order, so a batch no longer times out. A busy answer (429) is retried on its own after a short wait. Two different API keys still run side by side. ## Local post-processing Upscaling runs on your own machine after NovelAI returns the image, so it costs no Anlas. Pick a local checkpoint in the **Local post-processing** panel. Faces have their own panel now, see Face detailer below. Anima at denoise 0.15 to 0.2 works well as a refiner. Split-file models are handled: the panel names the text encoder and VAE it paired, or tells you which companion file is missing. See [[Upscaling and Face Fix]]. If the upscaler set in the Refiner is a recommended model that is not installed, it is downloaded automatically before the generation starts. A non-recommended upscaler that is missing stops the generation with a message naming the file. If the local pass is skipped or fails, a **Local refine skipped** or **Local refine failed** notification in the notification bell says why; the original NovelAI image is saved as-is. When a Krea 2 model is selected as the local refine checkpoint, the pass uses Krea 2's own sampling: CFG 1, euler / simple for Turbo; CFG 4, er_sde / sgm_uniform for Raw. The **Refine** button on the live preview follows the same split. With a NovelAI model selected and a key saved it opens NovelAI's **Enhance** instead of the local chain, because a paid img2img pass at a larger canvas is a different operation with its own controls. With no key it falls back to the local chain, and if no local checkpoint is picked here it says so rather than failing on a missing model. The missing-upscaler check also runs when Refine triggers a local pass. ## Face detailer In NovelAI mode the Face Fix panel is replaced by **NovelAI Face Detailer**, its own panel with its own settings. Faces are found locally with a YOLO detector, which needs ComfyUI running with `ultralytics` installed; only the repaint goes out to NovelAI. **Detailer Engine** picks who repaints each face: - **NovelAI (matches style)** sends each face crop back to the same NovelAI model that drew the image, as img2img at low strength, then blends it back with a soft edge. The face keeps the style of the picture. - **Local checkpoint** uses the checkpoint from the Local post-processing panel. Always free, but it paints faces in its own style. On the NovelAI engine each face is a separate request. **Anlas Policy** controls its step limit: **Fit Opus size/step limits** keeps crops within 1 MP and caps steps at 28; **Allow paid crops** keeps the requested face steps. Crops use **Guide Size**, capped within 1024×1024 under either policy. Fitting the window is only covered when your account/model has an available free allowance. A plan without that allowance, or an exhausted V5 allowance, still incurs Anlas charges, and the panel warns you. **Face Prompt** controls what each crop is conditioned on. **Auto** merges identity tags from your prompt with tags read off the crop by the tagger (the interrogator's model; without it auto falls back to prompt identity only). **Generic** uses quality tags only, and **Custom** uses your own text. The full prompt is never sent with a crop, so scene and pose tags cannot bleed into a face. On the local engine auto uses prompt identity only, since the tagger does not run there. **Steps** in the face detailer follows the main Steps setting. Changing the detailer slider gives it a separate value until you next change the main Steps setting. The free-window policy still caps crop requests where needed. New settings start with **Confidence** at 0.4 and **Strength** at 0.5. Each face pass streams its own preview and step progress. A notification explains skipped, failed or partially completed passes, including no detected faces, batches with more than one image, and V5 transparent backgrounds. Successful crops remain in a partially completed result. Composited face-detail results retain the original NovelAI PNG text metadata as well as their post-processing information. Importing a V5 image ignores its placeholder zero for undesired content strength; older models can still restore a real zero. ### Refiner order and oversized faces This behavior requires **v2.3.2 or later**. With the local refiner enabled, the order is **NovelAI generation → local refiner/upscale → NovelAI face detailing → final image**. Detection uses the refined image at its actual dimensions. The refiner reports progress and previews under the same generation, and releases its GPU worker before the NovelAI face requests. If face detailing fails, the refined image is retained; if the local refiner fails, the face pass can still use the original NovelAI image. Each detected face uses **one crop request**. Crops wider or taller than 1024 px are downscaled to fit within **1024×1024**, repainted, then resized back and blended into the original face area. The final image keeps its original dimensions. Aspect ratio is maintained subject to NovelAI’s 64 px request grid. **Guide Size** still controls the working resolution, including enlarging small faces. The 1024×1024 ceiling applies even to imported settings above 1024 and to **Allow paid crops**. There is no tiled face pass. Close-up faces are still processed when the detailer is enabled; turn it off when the original face already looks good. **Each face is a separate NovelAI request**, consuming model allowance or Anlas. The base generation estimate excludes these detector-dependent requests. The Opus size/step policy caps each request at 1 MP and 28 steps, but coverage still depends on your plan and remaining allowance. Completed faces remain in a partial result if a later request fails. The existing single-image and transparent-background limits remain. ## Director Tools Director Tools run one of NovelAI's image passes over a picture you already have. Cost follows the size of the source image, not the tool you pick. Opus covers one image of 1MP or under; a larger or upscaled source costs Anlas on every plan (around 30 at 2MP, 60 at 3MP). **Background Removal is never covered and costs about three times as much.** | Tool | What it does | |------|--------------| | **Background Removal** | Cuts the subject out onto transparency | | **Line Art** | Reduces the image to clean line work | | **Sketch** | Redraws it as a rough sketch | | **Colorize** | Adds color to line art or a sketch | | **Change Emotion** | Changes the expression on a face | | **Declutter** | Removes text, panels and other clutter | Open the modal from any image you already have: right-click a session output, right-click the live preview once a generation has finished, right-click a gallery image, or use the **Director Tools** button in the gallery (a labelled button in details view, a **DT** button on hover in grid view). Opening a gallery image full size gives you a **Director Tools** button in the lightbox toolbar as well. Every entry only appears while a NovelAI model is selected and a key is saved, and never on a video. Colorize and Change Emotion take two extra fields. **Guidance (optional)** is free-text direction, for example "blonde hair, blue eyes". **Defry** (0 to 5) sets how far the tool may stray from the source, with 0 staying closest. Change Emotion also requires an **Emotion**, one word in English, and will not run without it. The other four tools ignore all three fields and hide them. Results arrive in the session grid and the gallery like any other generation. Ctrl+Enter submits from a text field, Escape closes. ## Enhance, Upscale and Variations Three NovelAI passes over an image you already have, sharing one modal with a tab each: **Enhance**, **Upscale 2x** and **Variations**. None of them is the local upscaler, and none is the prompt **Enhance for V5** below. Open the modal from the lightbox toolbar, from the hover buttons on a gallery tile, or by right-clicking a gallery image. All three get their own button, in the same order everywhere, because they cost very different amounts and the cheap one should not sit behind the expensive one. They only appear while a NovelAI model is selected and a key is saved, and never on a video. Results arrive in the session grid and the gallery like any other generation. Started from the lightbox, the result takes over the lightbox rather than landing silently behind it. Escape closes the modal, and Ctrl+Enter submits from whichever modal is on top. ### Enhance Redraws the image at a larger size. This is NovelAI's own upscale-and-redraw pass. **Upscale Amount** is **1x**, which redraws at the original size, **1.5x**, or **Max**, the largest whole multiple that still fits NovelAI's 3MP ceiling for this particular image. A button hides itself when the source is already close enough to the ceiling that there is nothing to gain. Each one shows the size it will produce and an estimated Anlas cost, and says **Free on Opus** when the Opus allowance covers it. **Magnitude** is how much the redraw may change the image, from 1 to 5, with 3 as the default. The slider moves in whole steps, but you can type a value with two decimals (1.25 and so on) into the box next to it. **Show Advanced** replaces it with the raw **Strength** and **Noise** the magnitude was standing in for, seeded from wherever the slider was. There is no prompt box. Enhance uses the prompt, undesired content and characters that are in the generation panel right now, so change them there to change what the enhance draws. Leaving them as they are keeps the image close to what it was. ### Upscale 2x Enlarges the image 2x with NovelAI's own upscaler, a V5 model. No prompt is sent, so the prompt and characters in the generation panel are ignored. The factor is fixed, so there is no amount to choose, only a **Result** size to read. The price follows the size of the image going in, not the size coming out, which makes it far cheaper than a redraw. The upscaler takes images up to 3MP; past that the tab says so and points you at Enhance instead. ### Variations Redraws the image several times at the same size, using the prompt in the generation panel. **Variations** is how many to make, 1 to 8, with 4 as the default. Every one is charged in full. **Variety** is how far each may stray from the source, from 0.10 to 0.90, with 0.40 as the default. A finished set opens in the lightbox as a grid rather than as one image. The toolbar toggles between **Show all variations** and **Show one image**, and any tile can be opened on its own or fed straight back into one of the three passes. The grouping is session state and is never written to disk, so a batch reopened after a restart is a plain set of gallery images again. ## Enhance for V5 With a V5 model selected, the prompt box offers **Enhance for V5** in place of the normal **Enhance**. V5 wants a natural language scene body and structured character boxes, which is the opposite of what the danbooru-style enhance produces, so this is a separate path. V4.5 and V4 keep the existing one. It uses the configured [[Prompt Assistant]] (local or external LLM). It spends no NovelAI Anlas, though an external LLM may have its own charges. Describe a scene in its instruction box, paste a prompt to rewrite, or give an instruction like "make my prompt more cinematic". **Copy existing prompt** fills it from what you already have. **Rewrite language** picks the language the scene description is written in, and Auto detects it from your prompt. **Edit current prompt** sends your current prompt, undesired content and character boxes along with your instruction, so the rewrite edits what you already have instead of starting over. The rewrite also remembers the session: earlier instructions and answers go along with each new one, so "now make it night" applies to the last rewrite even without **Edit current prompt**. With it ticked, your current boxes win over the remembered answer. **New chat** in the panel starts over; see [[Prompt Assistant]]. **Saved characters**: the rewrite knows the NovelAI characters saved in the [[Generation Basics#characters-tab|Characters tab]], and the window lists their names. A full name, a first name or surname alone, or a close approximation resolves to the saved character, who gets a character box from the saved appearance with their avoid list in UC. Text that plainly means someone else is left alone, and characters you do not mention are never added. A variant is picked when the text asks for what it describes. For a saved canon character (for example Brock from Pokemon), the rewrite uses the canon tags and look plus your saved details; where they disagree, the review lists the differences and asks **Keep saved details** (the default) or **Use canon**, which redoes the rewrite. **Reference images** attaches up to four pictures you can point at in the instruction, for example "put the outfit from image 1 on her". Add them with **Upload**, **Paste** or **Gallery**, and give each an optional **Label** if you would rather name one than number it. The assistant describes what it sees in words before it rewrites, so this needs a model that can see images. The bundled local model cannot, so attach references only with a vision-capable model on an external provider; see [[Prompt Assistant]]. **Curate it** is a checkbox in the input stage, next to **Rewrite language**. Off by default; it resets each time the window opens. When ticked, the rewrite targets V5 Full against the Heavy UC preset. Applying the rewrite also switches to V5 Full and applies a fixed set of settings: Standard quality tags, Heavy UC, guidance 5, 25 steps, Euler Ancestral with Karras, guidance rescale 0, Variety+ off, batch 1 and High effort, and appends a set of extra avoids to the undesired content box, skipping any already there. **Undo** after applying reverses both the prompt fields and the settings change. Your width and height are kept, only rounded to NovelAI's 64 px grid. **Keep artists** keeps the artist tags from your current prompt in the rewrite, weights and emphasis included (weighted spans, `{}` and `[]`, and `artist:` prefixes). Any the rewrite drops are added back at the end of the base tag line. The choice is remembered. **Minors rule** (v2.3.40 and later) sits in the same row and is on by default. When the request mentions a child or a school-age character, it adds a rule telling the model to keep them non-sexual. Some hosted providers refuse ordinary SFW school or family prompts because of that rule's wording; turning it off sends the normal SFW guidance instead. A minor together with explicit content is still never sent, and a request that mixes a minor with suggestive words always gets the rule. The rewrite follows NovelAI's V5 Full and V5 Curated prompting rules. The base prompt is a tag line that locks identity plus a few natural language sentences for camera, layout and mood, with `high complexity` by default. Emphasis is used to lock or kill a motif, not sprinkled on every tag. Every tag has to change the image: a named character's canon look is not restated (momo velia deviluke already has pink hair), and undesired content holds only what would otherwise show up, so `chibi` or `mitten hands` stay out of an ordinary character's list. It can be empty when the **Undesired content preset** is on; quality filler such as `masterpiece` or `best quality` is never added, since **Quality tags** covers that. Artist names ending in digits are put first inside a `1.2::...::` span, and a character box is made to start with `girl`, `boy` or `other` rather than a count or a `Character 1` label. Nothing is applied until you choose. The review screen lists the base prompt, undesired content, and each character side by side as **Now** and **Proposed**, with a checkbox on each and a running token count against the budget. **Apply selected** takes only what you ticked, and **Undo V5 rewrite** reverses it afterwards. A rewrite that drops a character removes the box rather than leaving it behind. Asking for a one character scene with two boxes open used to rewrite the first and leave the second standing, so the extra character still went into the image. Each box the rewrite no longer wants now appears in the review as a ticked row reading `(empty)` under **Proposed** with a **removed** chip, and untick it if you would rather keep that box. A box the rewrite adds is marked **new** the same way. **Comic dialogue:** for comic pages and speech bubbles, the `Text:` block holds only the spoken words, one bubble per paragraph in reading order. Speaker names, page or panel headings and quote marks stay out of it, because NovelAI draws everything after `Text:` into the image. The speaker is named in the prose instead, with the line quoted in the sentence that describes that panel. See also [[Comic Pages]]. ### Keeping outfits apart With two or more characters, clothes tend to leak between them: a garment restated in the base prompt, or the same piece in two boxes. Since v2.3.41 the rewrite keeps every garment in exactly one character box. The base prompt holds only the count, framing, setting, the shared action and one short sentence placing each character, and it is retried once if its tag line repeats a box's clothing or hair tag. Each character's side is named in both the base and the box, and an interaction the prompt describes (a hug, a headpat, holding hands) gets its `source#`, `target#` or `mutual#` tags. With **Edit current prompt** or a follow-up, existing box outfits are kept word for word unless the instruction changes them. After every rewrite, each box's own undesired content also gets the other characters' distinctive garments, skipping anything that character wears or already avoids, so a girl in a black hoodie never gets `hoodie` in hers. The review shows each box's undesired content as **Now** and **Proposed**, and **Apply selected** writes it. The review flags leak risk before you generate: - **Possible overlap:** chips appear under a row when a clothing or hair tag in the base tag line is also in a box, or a garment is in two boxes. Click a chip to keep the tag in that box only, take it out of the base and the other boxes, and add it to their undesired content (unless they wear it). Hair two boxes share is not flagged, since twins or sisters can look alike on purpose. - **Isolate outfits** does the same cleanup with no LLM call: it takes restated outfit and hair tags out of the base tag line (prose is left alone), gives each box without placement words its side from the position grid when **Custom** positions are on, and adds the opposite-outfit undesired content. Garments two boxes share stay and keep their chip, since matching clothes can be intended. It is in the review toolbar, on the Enhance input stage and in the **Characters** panel header (V5 models with two or more filled boxes). From the input stage or the panel it opens the review on your current prompt, so nothing changes until you apply, and **Undo V5 rewrite** works as usual. - When two characters share a hair colour or two or more body tags but wear different clothes, a line reads **Similar bodies, different outfits: opposite-outfit UC recommended**, with an **Add** button (or **Added** once it is there). ### Scene objects and layout Since v2.3.42, objects and where things sit relative to them (`table in foreground`, `behind table`, `sitting in chair`) go in the base prompt as short tags plus one short sentence. Character boxes keep pose and side of frame only, with no object words, and clothing the object hides is left out. The rewrite never adds tags such as `opaque` or `not on table`, never puts an object the scene contains in undesired content, and moves layout tags it finds in a box to the base tag line. If a layout keeps failing, untick **Use memory notes** (see [[Prompt Assistant]]) so earlier notes do not pull the old composition back in. ## Aspect ratios and resolution NovelAI mode accepts any aspect ratio: the same eight presets as a local model, plus anything you type. Width and height always land on multiples of 64, rounded down so the area never exceeds what the side length allows (2:3 at a 1024 side is 832x1216, 16:9 is 1344x768). Switching backends only snaps the current width and height to that grid; it never recalculates them from the ratio. ## Copying NovelAI images **Copy to clipboard** on the preview and **Copy to Clipboard** in the gallery preserve the original NovelAI PNG text metadata. On desktop, copying waits for a pending gallery save so an image copied immediately after generation can use the saved file. You can paste the PNG back into NovelAI and recover its recorded settings. ## Importing NovelAI images Drop a NovelAI image onto the app and it asks what you want to do with it: **Image2Image**, **Vibe Transfer**, or **Precise Reference**. If the file carries NovelAI metadata, it offers to import that instead. The import screen lets you choose which parts to take: prompt, undesired content, characters, settings, seed. Characters can **Append** to the ones already in the panel or replace them, and **Remove Existing Characters** clears the panel first so an image with no characters of its own does not leave the old ones behind. **Clean Imports** strips the quality tags this app adds on its own along with inline syntax no backend here supports. On a NovelAI image it also strips NovelAI's own quality tags, since **Quality tags** puts them back at send time. Importing the settings restores the **Quality tags** and **Undesired content preset** the image was generated with. With **Clean Imports** off, the prompt and undesired content keep the tags and preset text exactly as the image carries them, so the import turns **Quality tags** off and sets the preset to **None** so nothing is sent twice. An image made with img2img has no source image in its metadata, so importing its settings starts a fresh image2image rather than reproducing the original. The dialog says so at the time. Importing the settings applies the model and sampler but leaves width and height as they are. ## Inpainting and img2img While a NovelAI model is selected, NovelAI's own inpainting and img2img replace the ComfyUI ones. The canvas and mask painting work as they do elsewhere, see [[Inpainting and the Canvas Editor]]. **Strength** and **Noise** sit directly under the image upload as **Image settings**, in the place the **Denoise** slider takes with a local model. In inpainting the same block adds **Keep the area outside the mask**, which pastes the untouched original back over everything outside the mask. Loading a source image adopts its shape as the aspect ratio at your current side length, so a 1024x1536 source at a 1024 side becomes 832x1216. It never copies the raw pixel size, and a locked resolution ignores it. The image (and the mask, in inpainting) is fitted to those dimensions right before it is sent. Inpainting is the exception: the canvas takes the image's exact size so the mask lines up. --- # Video Generation In v2.3.7 and later, open **Video** from primary navigation beside **Generate** and **Music**, on desktop or mobile. Video runs the MiniMax H3 stack: you write a prompt, choose a length and a shape, and the clip lands in the gallery alongside your images with its parameters attached, plays inline in the grid and in the lightbox, and can be exported to a file you can post. With **Manual save mode** turned on in Settings, finished clips are held in the preview instead of being written to the gallery automatically. A **Save to Gallery** button writes the clip you want to keep, and a **Discard** button drops it without saving. If additional clips finish while you are reviewing one, a "+N more" indicator appears below the preview showing how many unsaved clips are waiting. **Generate** returns to the image mode you last used during the session. Image and video prompts stay separate, and generation indicators appear on the relevant navigation entry. Video stays available while a NovelAI model is selected for images; it always runs on ComfyUI, since NovelAI has no video endpoint. ## Models Video mode does not use your image checkpoints. Each quality tier is a stack of five files: a diffusion model for **First / Last Frame**, a separate diffusion model for **Reference Images**, a shared text encoder, and two shared VAEs. Pick a tier under **Models** and MooshieUI lists all five, tags whichever diffusion model matches your current workflow as "in use", and downloads whatever is missing. | Tier | Size per diffusion file | Notes | |------|------|-------| | **NVFP4** | 12.5 GB | Blackwell (RTX 50 series) only. On older cards the weights are widened at runtime, which costs both speed and memory. | | **int8** | 21 GB | Recommended. | | **fp8** | 21 GB | | | **bf16** | 40 GB | Unquantized bfloat16 weights. | | **Custom** | varies | Bring your own files. | The **Custom** tier skips the presets and lets you pick every file yourself: the **Diffusion Model**, **Text Encoder**, **Video VAE** and **Audio VAE** from your local model folders, plus the **Turbo LoRA**, **Sampler** and **Scheduler**. `.gguf` diffusion models and text encoders are routed through the GGUF loaders automatically. Use it for community quantizations (W4A8 and similar) or a fine-tuned H3 that the preset tiers do not know about. While Turbo is on, a LightX2V or PDD turbo preset sets the **Turbo LoRA** file itself, so the picker is locked and names the preset; pick **Larryvrh v4** under **Turbo preset** to choose your own. With Turbo off the picker is never locked. The native Reference Images workflow uses the audio VAE for final audio decoding; it does not pass it into the reference-conditioning node. Generating only needs four of the five files: the diffusion model for your active workflow plus the text encoder and both VAEs. Downloading a tier grabs both diffusion models at once, so switching between First / Last Frame and Reference Images later does not require a second download. The table lists diffusion weights only, not the full download or VRAM requirement. Preset stacks additionally share a roughly 15.7 GB text encoder, 5.2 GB video VAE and 0.6 GB audio VAE; downloading both diffusion variants increases disk use again. The app lists each file and what is already installed. Video runs through ComfyUI, not NovelAI. ## LoRAs In v2.4.0 and later, the **LoRAs** list in Video mode takes your own MiniMax H3 LoRAs (style, character, camera motion and so on). Click **+ Add LoRA** and pick one; only H3 LoRAs are listed, and the Model Hub has them under the base model "MiniMax H3". They load before Turbo and stay on for retakes and 2x refinement. Acceleration adapters (Turbo, LightX2V, PDD) are skipped if added here, so they are never applied twice. The LoRAs are saved in the video's metadata and come back when you reuse its settings. ## Workflows The **Workflow** selector picks the graph the clip runs through. Each workflow needs its own H3 diffusion model file. | Workflow | What it takes | |----------|---------------| | **First / Last Frame** | Both frame slots are optional. Leave them empty for plain text to video, set only the first frame for image to video, or set both to interpolate between them. | | **Reference Images** | Up to 9 images describing subjects, style, or setting. At least one is required. | Under First / Last Frame there is a **Use first frame as last frame** toggle, which sends the opening image to the closing slot so the clip ends where it started and loops cleanly. A last frame you uploaded separately is remembered and comes back when you turn the toggle off. Every frame and reference slot has a **Choose from gallery** button next to the upload control, for pulling in an image you already generated instead of uploading a fresh file. It opens a picker over the gallery; frame slots take one image, reference slots let you pick as many as you have room for. The gallery works the other way too: hover any still image and use **Make video** to send it straight into a new video generation as the first frame, or **Add as video reference** to add it to the reference slots. Both actions switch you to Video mode with the slot already filled. ## Length, shape and resolution **Duration** is requested in seconds (1–15). H3 accepts frame counts of the form 17n+5 at 24 fps, so the count snaps **up** to a valid length. For example, a 4-second request becomes 107 frames at 24 fps (about 4.46 seconds). Read the panel's resulting frame count and duration. **Aspect Ratio** offers the usual presets plus **Match image shape**, which takes the shape of the uploaded frame instead. With no frame uploaded it falls back to 16:9 and says so. **Pixel Budget** sets the total pixels per frame in megapixels. Width and height are derived from the budget and the aspect ratio, snapped to multiples of 32, and the resulting resolution is printed under the slider. Pixel budget and duration drive VRAM use. MooshieUI shows a rough estimate without CPU offloading, compared with estimated usable GPU memory. This is not measured free memory or a minimum GPU requirement: ComfyUI can offload to system RAM, and custom models and memory settings affect actual use. The note is advisory and never blocks generation; it can suggest a lower pixel budget. A separate warning appears if VRAM Mode is set to high in Settings, which keeps the whole model resident and usually makes video much slower. When the H3 model would leave less than 6 GB of the card free, MooshieUI launches ComfyUI without High VRAM anyway, so the 20 GB INT8 model on a 24 GB card no longer stalls before the first step. ## Writing the prompt H3 was not trained on free prose. It expects prompts written as labelled sections, and prompts that ignore the format tend to produce weak motion. The **H3 prompt format** guide next to the prompt box explains the whole thing, in four tabs: - **Structure** lists each section in order and what belongs in it, with your current setup (task, frame count, fps, seconds) shown at the top. - **Rules** covers the parts that matter most: Shot 1 carries no timestamp and every later shot opens with one in increasing order, the visual style is stated once right after `[Shot 1]`, camera moves need a type, an amplitude and a speed, speaker tags sit outside the quotation marks, and on-screen text is copied exactly inside double quotes and never translated. - **Full example** is a complete prompt for the setup you have right now. Replace the content, keep the shape. - **Template** is the same thing as a skeleton with angle-bracket placeholders, with a copy button. **Enhance for H3** above the prompt box writes the format for you with the [[Prompt Assistant]]. Describe the video you want, or tick **Edit current prompt** and say what to change, such as "make the camera slowly push in". With it ticked and the box empty, it rewrites your current prompt into the H3 format. For image-to-video and first/last-frame clips the first frame goes along so the opening matches it, and **Reference images** can add more pictures to describe (external vision models only). **Review rewrite** shows the result next to your prompt before **Replace** applies it; a result that misses part of the format, or a Live2D idle rewrite, is flagged there. There are two formats. The standard format has 3 fields and covers ordinary text to video. The reference format has 6 sections and is what you want when you are feeding labelled inputs such as `` or ``, since it carries the summary, the per-input descriptions, and the retention strengths that say how closely each one should be followed. ## Timeline For anything longer than a single shot, turn on **Use timeline** to storyboard the shot list rather than describing it all in one block of prose. The timeline has three tracks. **Shots** is the sequence itself: each segment carries its own prompt, a start and a length in frames, and optionally a still or a clip as its source. **Motion refs** and **Audio refs** are optional and replace the generated motion or sound where they sit. Alongside it are: - **Cast**, up to three recurring characters with a description and a photo, referenced from shot prompts as `@character1`, `@character2` and `@character3`. - **Sound**, split into an overall soundscape (ambient sound inside the scene) and non-diegetic music (score sitting over it). The header shows how much of the render window the shot list currently fills, and warns you when the timeline runs past it. Turning the timeline off hands control back to the settings panel. In the first/last-frame workflow, stills at the start and end of the clip become its first and last keyframes. In v2.3.8 and later, a shot whose still starts partway through is pinned at that shot's start frame instead of being dropped, using ComfyUI's `MiniMaxH3AddGuide` (ComfyUI v0.34.0 or newer). A clip segment contributes its first frame. How closely H3 follows a mid-clip anchor has not yet been measured on a GPU. ## Going faster In v2.3.6 and later, use **Generation method** to choose **Standard** or **Turbo**. | Turbo preset | Steps | Use | |---|---|---| | Larryvrh v4 | 4-8, default 6 | First/last-frame and reference workflows | | LightX2V FL2V v1.2 | 4 | First/last-frame workflow | | LightX2V FL2V v1.0 | 8 | First/last-frame workflow | | LightX2V Ref2V v1.0 | 8 | Reference workflow | | PDD FL2VA · 8 | 8 | First/last-frame workflow | | PDD Ref2VA · 8 | 8 | Reference workflow | Choose the matching **Turbo preset**. LightX2V presets pair fixed steps with Euler/simple and their required sigma shifts; Larryvrh uses the Turbo sampler. The app preserves custom sampler settings when switching methods. Switching workflows maps LightX2V to its matching eight-step preset, and PDD to the other PDD preset. Managed setup can install adapters; remote servers need the matching model files and nodes on that server. The PDD presets (v2.3.8 and later) use Alibaba PAI's Parallel Decoding Distillation adapters with eight Euler/simple steps. They need ComfyUI v0.35.0 or newer on the connected server. Historical VDN selections migrate to Standard. VDN is no longer selectable after local testing found it slower and unstable. Performance depends on the stack, resolution and duration; extra Turbo steps do not guarantee better motion. **TeaCache** skips the model's forward pass on steps where the output barely changed from the last one, reusing the cached result instead. Faster with a small risk of softer motion, and stacks with Turbo. It is skipped with the PDD presets, where each step uses its own output heads. Turning it on installs the TeaCache nodes, then restarts ComfyUI. **Live preview** (v2.3.8 and later) plays a rough animated preview of the whole clip while it samples, decoded with the small taeh3 autoencoder. It adds a little time and memory to each step. Turning it on downloads taeh3 (23 MB) into `models/vae_approx` with no restart. On a remote ComfyUI server, put `taeh3.safetensors` in that folder yourself. **Frame Interpolation** generates in-between frames after sampling, so playback looks smoother without changing the clip's length. **Interpolation** sets how many frames are created per original frame, and the panel tells you the resulting playback fps. Advanced exposes flow scale, fast mode, and ensemble. Turning it on installs the interpolation nodes and a 20 MB checkpoint, then restarts ComfyUI. **Engine** picks which interpolator runs. RIFE is fast and light. GMFSS is slower but built for anime, with cleaner line art and flat shading and less warping. Both ship in the same node pack, so switching needs no extra install, but GMFSS downloads its own checkpoints on first use and that first job pauses for a while with no progress shown. You can also smooth a clip after the fact: the **Smooth** action on a gallery video runs interpolation on it without regenerating, with the same RIFE or GMFSS choice. Length and audio stay the same. ## Concise motion and Live2D prompts For a simple shot, keep the motion request brief and specific. **Live2D this image** guides gentle breathing, quick natural blinks, small secondary motion, a fixed camera and quiet ambience. Avoid prescribing a movement for every detail. The enhancer preserves explicitly requested closed eyes or different blink behavior. A matching final frame helps return to the opening pose, but does not guarantee a seamless loop. ## Retained drafts, retakes and 2× refinement (experimental) Enable **Keep draft for 2× refinement** before generating a small draft, usually about 0.5 MP or less. The doubled dimensions must fit within 2.2 MP. Save the result, open its video player and choose **Retake or refine**. Under **2× refinement**, install the 59 MB H3 latent upscaler if prompted, then choose **Queue 2× refinement**. Defaults are eight steps and strength 0.35. The result is a new clip with the original audio preserved. In v2.3.8 and later, **Retake a range** in the same panel regenerates only the seconds between **From (s)** and **To (s)** with a new seed, then saves a new clip. The rest of the video and the whole soundtrack stay exactly as they were, and the new frames are generated against the original sound. It does not need the upscaler, but the ComfyUI server needs v0.34.0 or newer and the updated MooshieUI nodes. Retained data stays on the ComfyUI server that generated it and can use up to 2 GiB per clip, separately from gallery storage. Refinement needs that original installation, its worker and model stack. An MP4 alone cannot reconstruct the retained data. **Delete retained data, keep clip** removes the extra data separately. Deleting a retained clip also cleans its draft; reconnect an unavailable server and finish queued refinements first. CPU checks cover the learned upscaler, dimensions, conditioning and audio preservation. Full two-pass GPU quality, memory use and live remote execution remain unqualified. See the [video guide](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/VIDEO.md) for setup and recovery details. ## Watching the result Video in the gallery gets a real player rather than a bare HTML5 element. Play and pause, mute and set volume, toggle loop, step to the previous or next frame, change playback speed, and go fullscreen. The scrubber and the timeline are sized for a mouse rather than pixel-hunted. **Seam check** loops just the last and first second on their own so you can judge how cleanly the clip wraps, with a percentage showing how far apart the two ends are. Use it before exporting, since a bad seam is what makes a loop visibly stutter. ## Exporting **Export** opens a popover that estimates the file size before you commit to it. | Format | Notes | |--------|-------| | **AVIF** | Smallest file by a wide margin. Plays in current browsers, but Discord and most chat apps will not animate it inline. | | **WebP** | Animates inline on Discord and in every current browser. The safe pick for sharing. | | **GIF** | Plays anywhere, including old clients. Much larger files. | | **MP4** | Plays everywhere and is the only format that keeps the audio. It is a video rather than an animated image, so it will not autoplay inline the way a GIF does. | MP4 needs an H.264 encoder and is unavailable if the ComfyUI environment does not have one. Presets cover **Smooth**, **Balanced** and **Max quality**, with a **Discord-safe** preset for GIF. **Advanced** exposes frame rate, width, quality, colors, and repeat count. **Loop fix** decides how the ends are joined: | Mode | What it does | |------|--------------| | **Auto** | Measures the seam and trims the duplicate frame when the ends already match. | | **None** | Encodes the frames exactly as generated. | | **Trim last frame** | Drops the final frame so a matching first and last frame do not play twice. | | **Crossfade** | Blends the tail into the head to hide a near-match seam. | | **Ping-pong** | Plays forward then backward. Always seamless, roughly double the size. | Set a **Size limit** of Discord (free) 10 MB or Discord Nitro 500 MB and the popover flags an export that will not fit before you try to upload it. Finished exports can be saved, copied to the clipboard, or downloaded in browser mode. ## Using it 1. Open **Video** from the primary navigation. 2. Pick a quality tier under **Models** and download whatever is missing. 3. Choose a workflow, and fill the frame slots or reference slots it asks for. 4. Set the duration, aspect ratio, and pixel budget. Check the VRAM note. 5. Write the prompt in the H3 format. Open the guide and copy the template if you have not used it before. 6. Generate. 7. Review the clip in the player, run a seam check if it is meant to loop, then export. ## See also - [[Generation Basics]] for the settings shared with image generation - [[Prompting Guide]] for prompt writing in general - [[Gallery and Metadata]] for how clips are stored and filtered - [[Models and the Model Hub]] for image checkpoints, which are separate from the H3 stack --- # Anime Scenes In v2.3.20 and later, the **Scenes** page turns a character into a short voiced, lip-synced anime clip. It is optional and runs on cloud providers with your own API keys: ElevenLabs for the voice, fal.ai (Seedance 2.5) for the video, and optionally NovelAI for shot keyframes. Each provider bills your own account. Nothing on this page runs on ComfyUI. Every step that costs money opens a confirmation first. It lists what will be billed, what is already cached and free, your remaining balance where the provider reports one, and the date the price was checked. Prices are estimates; your provider balance is authoritative. ## Keys Add keys in Settings under **Cloud voice and video**. There is one field per provider (ElevenLabs and fal.ai). Builds up to v2.3.41 also show a Segmind field, but nothing uses that key. A saved key is never shown again; **Clear** removes it. On a server, each account uses only its own keys, which are stored encrypted, and the owner's keys are never sent to any client. See [[Settings and Accessibility]]. You need an ElevenLabs key to start. Video needs a fal.ai key, and keyframes need a NovelAI key. ## Character Give the character a name. **This character is a minor** turns on stricter safety rules: if a provider refuses something for this character, that refusal is final and is not retried, and the flag cannot be turned off afterwards to get around it. **New scene** clears the page. Provider refusals are always shown as they are. MooshieUI never rewords a prompt to get past a provider's safety filter. ## Voice Pick one of your ElevenLabs voices, or **Design a new voice**: describe it with the brief fields (language and accent, gender, age, voice quality and so on), and ElevenLabs returns three previews to choose from. The voice is saved to your ElevenLabs account. The panel shows your remaining credits and voice slots, and **Delete** removes a voice from your ElevenLabs account permanently. Then write the scene's lines and record them as takes. Takes are cached per account, so the same take is never paid for twice; a fresh take of a line is only made when you ask for one. Pick the take you want for each line. ## Keyframes (optional) With a NovelAI key, each shot can get a NovelAI V4.5 keyframe made from the character image with Precise Reference. It keeps the character on model and the shot framed as described, lands in the gallery, and becomes that shot's reference image. Enter the **Character tags** (English, `1girl` first) or use **Copy from the character image**, then **Keyframe tags** per shot, and press **Make keyframe**. Precise Reference costs 5 Anlas per image even on Opus, and the button shows the estimate. For a minor, body-shape and revealing tags are removed and `nsfw` always goes in Undesired Content. ## Video - **Reference images**: **Add from gallery**, then mark what each image controls: the **Character**, the **Location**, or one shot's framing. Images are sent without their embedded prompts and settings. - **Shots**: shots play in order. Each can speak one line (or be a silent shot) with a pause before it, and its timing comes from the length of the chosen take. Add the framing and action for each shot. - **Scene details**: traits that must stay the same, starting and ending state, ambient sound, spoken language, silence after the last line, and **One continuous take, no cuts**. - **Resolution** (480p, 720p, 1080p), **Aspect ratio** (16:9, 9:16, 4:3, 3:4, 1:1, 21:9) and **Seed**. A clip can be up to 30 seconds. - **Draft (480p, cheaper)** renders at 480p and is billed as 480p. A draft can be completed at 1080p later (see below). - **Mouth map**: **Measure mouth timing** measures each take with ElevenLabs alignment so the prompt says exactly when the mouth moves. It costs a little ElevenLabs speech-to-text time, once per take. **Preview prompt and price** builds the prompt and estimate for free. The prompt can be edited before rendering; **Reset to the built prompt** undoes your edits. **Generate video** opens the confirmation and starts the render. Progress shows in the queue, and the clip lands in the gallery with a poster and the full scene recipe in its metadata, even in manual save mode. If you close the app mid-render, reopening the Scenes page picks the job back up instead of paying for it again. Cancelling stops MooshieUI from waiting, but a render fal.ai has already started usually finishes and is billed anyway. ## Finished scenes Clips made on the page are listed under **Finished scenes**. They are already in the gallery; this list holds what you can still do with them. A clip deleted or renamed in the gallery drops out of the list. - **Complete at 1080p** renders a draft again at 1080p and is billed as a new 1080p clip. fal.ai keeps drafts for seven days, and it only works with the fal.ai key that made the draft. - **Use my exact voice** makes a free copy with your recorded voice track in place of the model's speech. The model does not follow the track's timing exactly, so the lips may drift. - **Remove from list** forgets the entry without touching the gallery. --- # Comic Pages In v2.3.49 and later, the **Comic pages** page builds a comic page panel by panel. It is in the desktop navigation and on mobile. ## Model and settings In v2.4.2 and later, the **Model and settings** section picks the model, sampler and size for the Comic page. They are kept apart from the Generate page, and the Comic page always generates images, so a Generate page in Video mode does not block it. ## Layout - Pick one of 15 templates (1 to 6 panels), or split any panel across or down (up to 9 panels) and drag the borders to resize. Undo with the button or Ctrl+Z. - Choose a portrait, landscape or square page and set the gutter with the slider. - Right-to-left reading order is there for manga. Panel numbers follow the reading order. ## Panels Each panel has a story beat, a prompt, its own negative, a **Dialogue** field and an on switch. Generate one panel or all of them. - **Each panel** makes one image per panel at the panel's own shape on the page's own model, then crops them into the page. Very tall or wide panels are clamped to between 1:3 and 3:1. - **Whole page** makes the page in one NovelAI image (up to 6 panels), with each panel's prompt placed at its position. It needs a NovelAI model. See [[NovelAI Backend]]. ### Dialogue The **Dialogue** field holds the spoken words for one panel, one speech bubble per line. On NovelAI models the lines are lettered into speech bubbles automatically. When generating in **Whole page** mode, all bubbles across the page are lettered in reading order. Enter only the spoken words, not speaker names or quotation marks. ### Enhance for V5 When a NovelAI V5 model is selected and a [[Prompt Assistant]] is configured, each panel shows an **Enhance** button (tooltip: "The Prompt Assistant rewrites this panel by the NovelAI V5 Enhance rules, dialogue included"). It rewrites that one panel's prompt and dialogue with the rest of the page as context. **Write prompts from beats** in whole-page mode also applies the V5 Enhance rules when V5 is selected, writing each panel's prompt and dialogue from its story beat. ## Continuity - **Cast:** describe each character once and pick them per panel. Their look is added to every panel they appear in. - **Setting:** the page setting is added to every panel, and a panel can override it. - **Panel check:** after a panel finishes, the tagger compares it with the cast and setting and flags missing or changed hair, eyes or setting, with a redo button. - **Check story** has the [[Prompt Assistant]] read the panels in order and point out contradictions. - **Write prompts from beats** has the Prompt Assistant draft each panel's prompt from its one-line story beat. It can be undone. For speech bubbles on NovelAI V5, put only the spoken words in the `Text:` block. See [[NovelAI Backend#enhance-for-v5]]. ## Saving Panel images go to the gallery as they finish and come back after a restart. **Save page** writes the assembled page to the gallery with the panel prompts in its metadata. --- # Music Generation Open **Music**, then use **Create** to compose a song or **Library** to browse your saved tracks and playlists. Music uses YuE2 through ComfyUI and is available in the desktop, browser and mobile layouts. ## Models and setup Connect to ComfyUI, open **Generation settings**, then **Models and setup**. Choose **Download INT8 · 4.0 GB** or **Download BF16 · 7.8 GB**, then **Refresh** and select the **YuE2 checkpoint**. Downloads follow the account's model-download permissions. The official Comfy-Org checkpoints belong in `ComfyUI/models/checkpoints` and include the generator, text encoder and audio VAE. If native YuE2 support is missing, a managed installation offers **Update and restart ComfyUI**. It moves the install to the ComfyUI release MooshieUI pins (v0.43.0 as of v2.3.41). YuE2 is native from ComfyUI v0.36.0, and earlier releases do not contain the required music nodes. For a remote ComfyUI server, its operator must update and restart that server. Refresh Music after it reconnects. The official BF16 baseline is an NVIDIA GPU with 24 GB VRAM. INT8 generation has been tested on an RTX 5070 with 12 GB, including a 47.6-second song; this does not establish support for every GPU or longer arrangement. Apple Silicon music generation remains unqualified. The checkpoint weights use **CC BY-NC 4.0**, a non-commercial license. See the [official models and license](https://huggingface.co/Comfy-Org/YuE2). ## Compose a song 1. Enter an optional **Song title**. 2. In **Style**, describe the genre, lyric language, mood, vocal delivery, instruments, groove, tempo and production sound. 3. In **Lyrics**, put each sung phrase on its own line. Separate sections with labels such as `[verse]`, `[chorus]` and `[bridge]`. **Add verse** and **Add chorus** insert section labels. Keep musical instructions in Style. 4. Set **Max length** from 1 to 360 seconds. This is a cutoff, so leave time for breaths, instrumental transitions and the ending. A song may finish before the limit, or be cut off when it reaches it. 5. Open **Generation settings** to choose the checkpoint, steps, seed and **Score planning**. **Melody and chords** plans the full score; **Melody only** plans melody; **Off** skips score planning. An optional **ABC score** can replace automatic planning. Clear the score to use Off. 6. Choose **Generate song**. The progress panel follows model loading, score writing, composition, rendering, decoding and FLAC saving. The first run can take longer while the model loads. Completed songs retain their generation settings. When a score is available, **Use this score and settings** loads it back into the composer. Review or clear an existing score when changing lyrics, since the new words may not fit it. ## Generate lyrics or enhance a style Set up a model or API provider in **Settings > Prompt Assistant** first. Music uses that same configuration, with writing and score-editing guidance adapted from the upstream yue2-music skill. When an external provider is selected, the supplied writing context is sent to it. - **Enhance style**, above Style, expands the musical direction with compatible details about vocals, instruments, rhythm, tempo, production and arrangement. Current lyrics can guide this rewrite. - **Generate lyrics**, above Lyrics, opens a popup asking **What should the lyrics be about?** Describe the topic, story, mood, perspective or language, then submit. The current style and Max length guide a compact draft. - **Use existing lyrics as context** starts unchecked. Check it when you want the instructions to revise the current draft. Leave it unchecked for fresh lyrics; the existing lyrics are then excluded from that request. Earlier song lyrics are not added as writing history. - **Undo style enhancement** and **Undo generated lyrics** restore the previous field. Cancelling or editing the draft while a request is running prevents a late result from overwriting your work. The assistant uses a conservative text budget that includes repeated choruses and reserves time for instruments and breathing. This helps fit the requested length but cannot guarantee the timing of sung audio. Short clips need a brief hook rather than a full verse, chorus and bridge. ## Reference styles, imports and arrangement tools The following tools are available in v2.3.6 and later. - **Auto style from audio** analyzes an uploaded reference or the current cover source with the selected audio-capable provider. The panel names the destination before sending audio. Google sign-in, audio-input OpenRouter models and compatible Custom endpoints are supported. Choose an excerpt when only part of a recording should guide the style, then review the editable draft and uncertainties. Existing Styles text is preserved; with Styles empty, generation can analyze the selected reference and apply its style automatically. - **Saved style profiles** stores style text and analysis estimates on this device for this account, without retaining the source audio. Adapt a saved style to the current duration and vocal/instrumental choice, preview it, then apply it. Up to 100 profiles can be saved. - **Use a reference song** looks up a title and artist in the Apple Music catalog, with optional Wikipedia song context. Choose the matching recording and **Find style**, review the sources and estimates, then **Apply to Styles**. This uses catalog information and the assistant's knowledge; it does not listen to the recording. - **Or paste a song link** accepts a single YouTube, YouTube Music, Spotify, Deezer, Dailymotion or Tidal song up to six minutes. Spotify, Deezer and Tidal links find a matching YouTube recording, so listen and check the version before transcription. **Import song** creates temporary audio, discarded when the source is replaced or the panel closes. Required tools are prepared automatically in the background; **Retry setup** retries a failed setup. - **Arrangement planner · Prototype** suggests and reorders sections, fits their durations to Max length, and previews timing guidance for Styles. It does not rewrite an existing ABC score, and its timing is approximate. Leave Lyrics empty for an instrumental song, score draft or cover. Audio analysis and writing requests use the configured provider; they do not transfer the original singer's voice. A/B comparisons offer optional loudness matching, per-account comparison notes and export of selected versions or the full project. Stale edit results cannot overwrite a draft changed during a request. See the [music guide](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/MUSIC.md) for the detailed controls, privacy behavior and validation limits. ## Cover a song Choose **Cover a song** in Create. Import an ABC score, try the included original melody, or expand **Transcribe a source recording**. For native transcription, select **ComfyUI SheetSage2**. An administrator or moderator can use **Download SheetSage2 (1.39 GB)**, then refresh and select its **Audio encoder**. The file is `sheetsage2_bf16.safetensors` under the host's `models/audio_encoders`. A remote worker needs the encoder on that worker, not just on the desktop computer. The separate Python environment route is also available; see the [setup guide](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/research/yue2-integration.md#source-recording-transcription). Import a source recording up to 64 MiB and six minutes, then transcribe it. Import sets **Maximum length** from the recording's duration, rounded up to a whole second. You can extend it afterward or choose **Use source length** to restore the default. If the browser cannot read the duration, enter it manually. Transcription creates a separate draft. Review the melody, meter, section order and lyric fit before applying it to the score editor. A completed job does not overwrite the editor automatically. - **Keep melody, adapt harmony** uses melody planning and removes chord symbols so the accompaniment can adapt to the requested style. - **Keep melody and harmony** uses the supplied chords with full planning. - Part selection can retain the vocal melody, instrumental melody, or both. Removing a part replaces its notes with rests; Undo or the transcription draft can restore it. Enter the lyrics and target style, review the current score, check the review box, then choose **Generate cover**. The cover is a new performance. It does not clone the original singer, preserve its waveform or force words to their original sung timestamps. The source-length ceiling can cut off a performance that runs long. Uploaded source recordings are not saved in library projects. Active native transcription jobs can be recovered after reload while the host retains their ownership and ComfyUI retains their history. ## Plan, preview and export a score Use **Generate score first** to create ABC without rendering audio. Saved score drafts retain style, lyrics and seed. Review the draft, then choose **Use this score, style and lyrics** to apply them together. Undo restores the previous unchanged draft. The score tools check the native YuE2 format, including bars, ties, supported chords, key and meter. The duration is a score estimate, not a guarantee of audio length. - **Preview score** displays a piano roll and plays selected melodies with an optional basic chord accompaniment. This is a small synthesizer, not the generated singer. - **Apply tempo** changes the quarter-note tempo while checking that notes and their timing in beats stay intact. - **Export MIDI** saves selected melody parts and optional reference chords. - **Export printable SVG** saves the displayed page, up to 32 bars. Longer scores have page controls; ABC and MIDI exports include the complete score. ## Edit a composition Open **Edit composition** for the current draft or from a saved song. Choose a starting request for reharmonization, tempo, transposition, structure or lyric translation, then describe the change. Select which melodies, note timing, tempo, exact lyrics and section structure to preserve. The configured Prompt Assistant proposes complete ABC, style and lyrics. MooshieUI checks the selected constraints before showing the proposal. Review it and choose **Apply to draft**, then generate a new version. Editing a saved recording keeps its original audio. Closing the dialog, changing accounts or editing the draft prevents a late reply from overwriting your work. These checks compare the symbolic score and text. They do not establish that the rendered singing follows every note or that the new arrangement sounds better. ## Candidates and sampling Choose **Candidates** of 1, 2, 4 or 8. Attempts run sequentially with different seeds and retain their individual settings and results. A failed attempt is recorded and the batch continues; Cancel stops the current job and pending attempts. After a reload, the app observes submitted work rather than submitting it again. **Resume pending candidates** continues unsubmitted attempts. If the backend restarted or a submission response was lost, check ComfyUI's queue before starting another batch. **Advanced sampling** exposes temperature, top-p, top-k, repetition penalty, the ABC token budget and semantic guidance. Reset restores defaults. Acoustic sampling CFG stays at 1. Automatic semantic guidance uses 1 with a score and 1.01 without. Current adapter nodes can report score-planning and semantic truncation separately. Older results keep an unknown status rather than inferring completion from recording length. ## Versions and project export Use **Create version from this song** to copy a recording's score, settings and actual seed into the editor. The new result retains a parent relationship. Each version stays a separate library entry. Open **Versions, compare and export**, select A and B, and play either recording. Starting one pauses the other. Keep the playback position when switching or loop an excerpt. Identical seconds may refer to different passages after tempo or structure edits. Symbolic melody, timing and tempo differences are shown separately from playback. Export selected recordings or the versions in A's project as a ZIP containing original FLAC, ABC, lyrics, style, request settings, actual seeds, lineage and available receipts. Exports are limited to eight versions and 256 MiB at once. They do not contain uploaded source recordings, model weights, semantic tokens or acoustic latents. The ZIP is an export bundle, not a project import format. ## Review recognized lyrics and approximate timing **Review lyric timing** can compare a source and generated recording with xAI speech-to-text, then ask the configured assistant to explain the measured evidence. Configure xAI access to its speech-to-text endpoint first. The action discloses which recordings it sends; it also sends the resulting evidence and musical context to the configured assistant. Use the same-lyrics-and-tempo option only when both recordings share them. Results include recognized lyric coverage, approximate line evidence and playable timestamps. Repeated lines are excluded from timing comparisons, and an overall estimate needs at least three distinct matched lines spanning five seconds. Reports and transcripts are saved with the song on this device. Source audio is session-only: reattach the exact recording to restore its saved playback links after reload. **Explain saved results** retries the explanation without transcribing again. Speech recognition can mishear singing or return no words. Such a result is inconclusive, not proof of missing singing. The assistant explains text evidence; it does not listen to or grade the music. This action does not correct sung timing. The experimental retiming and voice conversion approaches were dropped after unsuccessful listening tests. ## Library, titles and playlists **Library** shows **All songs** and your playlists. **Search songs** matches titles and musical styles. **Sort songs** offers Song title or Date added for the full library, and Song title or Playlist order inside a playlist. Use **Create playlist** above the playlist list. Each song's **Edit song** menu lets you change its title and tick the playlists it belongs to. A selected playlist offers **Rename playlist** and Delete. Deleting a playlist keeps its songs in the library. **Play all** plays the displayed list in order; **Shuffle** starts a shuffled queue. Click a song to play it. The list shows its title, style and length, with Date added on wider screens. Songs, audio, titles, playlists and manual lyric timings are stored on this device for the current account. Saved tracks survive a page reload and do not depend on ComfyUI retaining its job history. The library is not shared between devices or browser profiles and does not scan older files in ComfyUI's output folder. Clearing site/app data can remove it. If a save fails, the app shows an error and marks the song as not saved; retry or download the audio. ## Playback and export The bottom player stays available while you browse other pages. It shares playback with the main player in Create: play/pause, seek position, volume and repeat stay together. Previous and next follow the current queue. **Open main player** returns to Create; **Stop and close player** ends playback and hides the bar. A song finishing generation does not interrupt a track already playing. **Download FLAC** saves the original lossless recording, using the song title in the filename. Desktop opens a Save dialog; browser mode starts a download. ComfyUI also writes generated files under `ComfyUI/output/audio`. Download files for backups or sharing, since the local library is device-specific. ## Sync lyrics manually In the main player, choose **Sync manually**. Play the song and press **Mark next line** when each sung line starts. **Set to now** marks a specific line, or enter a start time in seconds directly. Start times must increase and fall within the song's length. Leave unmarked lines blank. Each marked line stays active until the next marked line or the end of the song. **Save** keeps the timings, **Cancel** discards the draft, and **Clear timings** clears the draft marks before saving. After saving, **Follow** scrolls with the active lyric. Click a timed line to jump to it. Scrolling the lyric pane manually turns Follow off. Playback lyric synchronization is manual; it does not load a speech recognition model. The separate Review lyric timing action uses the hosted xAI service. ## See also - [[Prompt Assistant]] for model and endpoint setup - [[Models and the Model Hub]] for download permissions and model management - [[Server, LAN and Multi-User]] for hosted accounts - [[AI Assistants and MCP]] for generating songs from an AI assistant --- # Image to 3D The **3D** page turns one picture of a character or object into a 3D model, back side included. It runs on ComfyUI's own nodes, so no custom nodes are needed. **Experimental, off by default.** Turn on **Experimental: Image to 3D** in Settings > Appearance to show the **3D** page and the gallery's **3D** button. The setting is per device. Results are often much rougher than the published examples. Both methods work best on a single object or figure on a plain background; anime illustrations, scenes and flat 2D artwork come out rougher. ## Methods Pick a **Method** at the top of the form: - **Textured mesh (Pixal3D)**, the default. [Pixal3D](https://github.com/TencentARC/Pixal3D) by Tencent ARC (MIT) on ComfyUI's TRELLIS.2, MoGe and mesh nodes. It makes a solid mesh with baked colour, roughness/metal/occlusion and normal maps, saved as `.glb`, which opens in Blender, game engines and any glTF viewer. Its VRAM needs are not published; expect more than Idol and minutes rather than seconds. - **Gaussian splat (Idol)**. [Idol](https://huggingface.co/speridlabs/idol) by Speridlabs (Apache 2.0), a fine-tune of TripoSplat. It makes a cloud of soft points that looks right from every side, but only splat tools open it. It is faster and lighter, at about 7 GB of VRAM. Both need ComfyUI v0.41 or newer. The managed ComfyUI is already new enough; for an older remote server, its operator must update it, then press **Refresh** on the 3D page. ## Model files When files are missing, the page lists them and offers **Download Pixal3D** or **Download Idol**. Only missing files are fetched, from Comfy-Org's ungated repackages, so no Hugging Face token is needed. On a shared server only admins and moderators can download; other accounts see a note to ask the host. | Method | Folder | File | |--------|--------|------| | Pixal3D | `models/diffusion_models` | `pixal3d_int8_convrot.safetensors` | | Pixal3D | `models/clip_vision` | `dino_v3_L_naf_fp32.safetensors` | | Pixal3D | `models/vae` | `trellis_2_shape_vae_bf16.safetensors`, `trellis_2_texture_vae_bf16.safetensors` | | Pixal3D | `models/geometry_estimation` | `moge_2_vitl_normal_fp16.safetensors` (MoGe 2) | | Idol | `models/diffusion_models` | `idol_fp16.safetensors` | | Idol | `models/clip_vision` | `dino_v3_vit_h_bf16.safetensors` | | Idol | `models/vae` | `idol_decoder_fp16.safetensors`, `flux2-vae.safetensors` (shared with FLUX.2 / Klein) | | Both | `models/background_removal` | `birefnet.safetensors` (only for Remove background) | Pixal3D is about 10 GB in total and Idol about 3.8 GB. ## Make a 3D model 1. Set the **Source image**: drop or paste an image, use **Choose file** or **From gallery**, or press **3D** on a still image in the [[Gallery and Metadata|gallery]]. Use a PNG, JPEG or WebP. 2. Keep **Remove background** on unless the image already has a transparent background. It cuts the subject out with BiRefNet. 3. Pick a **Detail** level. For Pixal3D, **Standard** is 300,000 faces with 2048 px textures and **High** is 700,000 faces with 4096 px textures. For Idol, Draft to Maximum sets 131,072 to 1,048,576 Gaussians; more is denser but not sharper. 4. Under **Advanced**, set the **Seed** (-1 for random). Pixal3D's sampler settings follow its own pipeline. Idol also offers **Steps** and **Guidance**, which default to Idol's own reference settings (50 steps, guidance 4). 5. Press **Make 3D model**. Progress shows the queue position and each stage. 3D jobs never enter the image gallery or image progress. ## Viewer The result opens in a built-in WebGL 2 viewer, in the desktop app and in browser mode. Drag to orbit, right-drag or Shift-drag to pan, scroll or pinch to zoom, and double-click (or **Reset view**) to reset. Arrow keys work when the viewer has focus. **Spin** turns the model on a turntable. ## Library and export Finished models are kept under **Your 3D models**, per account, in this browser (like the music library), so they are not shared between devices. Give a model a **Name**, or **Delete** it. - **Save .glb** (meshes) writes the textured mesh. - **Save .ply** (splats) writes the file ComfyUI produced (standard 3DGS PLY). - **Save .splat** (splats) writes the compact format most web splat viewers open. Splats open in SuperSplat, Blender add-ons and other Gaussian splat tools. They use the usual 3DGS convention (+Y down), so some tools show them upside down until you flip them. ComfyUI also keeps its own copy in `output/3d/`. --- # Upscaling and Face Fix ## Upscale (tiled diffusion) MooshieUI upscales with MultiDiffusion tiled diffusion, the same approach used by SwarmUI. There is no slow tile-by-tile processing; all tiles are denoised together each step for seamless results. The tiled diffusion node is also published as a standalone ComfyUI custom node for use outside MooshieUI: [ComfyUI-MooshieTiledDiffusion](https://github.com/Mooshieblob1/ComfyUI-MooshieTiledDiffusion). It is the same node MooshieUI uses, so it supports Anima (COSMOS) and 5D latents, MultiDiffusion and SpotDiffusion, and txt2img, img2img, and inpainting, and it works above 2.4 MP where a single pass shows artifacts. Install it with ComfyUI-Manager (search Mooshie Tiled Diffusion), the Comfy Registry (`comfyui-mooshietileddiffusion`), or by cloning into `custom_nodes`. It is a one-off export with no promise of ongoing maintenance; the canonical source stays in MooshieUI. ### Methods - **Model-based** - uses a dedicated upscale model (for example Omni-SR). Scale is fixed by the model (2x, 4x, etc.). - **Algorithmic (Lanczos)** - fast pixel-space upscaling with an adjustable 1 to 4x scale. - **SeedVR2 (restoration)** - one-step diffusion restoration that rebuilds real detail while upscaling instead of just resizing. It runs after sampling with its own model, so there is no denoise or step count to tune. The model and VAE (around 3.7 GB) download from within the app the first time you use it. ### Cap target scale By default a model-based pass upscales to the upscale model's full native factor, so a 4x model like RealESRGAN_x4plus always runs a full 4x pass even when you only want a smaller bump. Turn on **Cap target scale** in the Refiner settings and set a **Target Scale** (for example 1.5x or 2x) to refine only up to that lower multiplier instead. It is off by default, so existing behavior is unchanged unless you enable it. Capping the scale means less work per pass, which cuts the time and system load a lot on lower-end PCs. ### Recommended upscale models (auto-download) When you pick a recommended model that is not installed, MooshieUI downloads it to ComfyUI's `models/upscale_models/`: | Model | Scale | Source | |-------|-------|--------| | Omni 2x | 2x | [Acly/Omni-SR](https://huggingface.co/Acly/Omni-SR) | | Omni 4x | 4x | [Acly/Omni-SR](https://huggingface.co/Acly/Omni-SR) | Any other models in `models/upscale_models/` also appear in the dropdown. ### Tiled diffusion options - Toggle per generation. Recommended for large images and required for Anima (COSMOS) models. - Adjustable tile size (256 to 2048px). - Cosine-feathered blending for seamless boundaries. - Supports both MultiDiffusion and SpotDiffusion algorithms. ### Guidance nodes (anti-hallucination) - **Soft Guidance (CFG Rescale)** - toggle in Upscale Settings to reduce extra hands/objects at low denoise. Adjustable multiplier (0.0 to 1.0, default 0.4). - **Smart Guidance (positive-biased adaptive)** - toggle in Sampler Settings to bias the model toward positive conditioning across all passes. These are custom nodes (`MooshieSoftGuidance`, `MooshieSmartGuidance`) installed automatically. ### Upscale sampler controls - **Denoise** - 0 to 1 (lower preserves more of the original). - **Steps** - 1 to 50. ### One-click upscale Hover any generated image and click **Upscale** to upscale the last output without changing your settings. ## Face Fix (face detailer) Enable a post-generation pass that detects faces and re-denoises them at higher resolution, then composites them back with smooth cosine-falloff blending. No Impact Pack dependency; it is a self-contained node. This panel is for ComfyUI mode. In NovelAI mode it is hidden and **NovelAI Face Detailer** takes its place, with its own settings and a choice between repainting faces on NovelAI or on a local checkpoint. See [[NovelAI Backend]]. Controls in Face Fix Settings: - **Detector model** - choose from recommended detectors (for example an Anzhc face segmentation model or `face_yolov8n`). Missing models are auto-downloaded with SHA256 verification, and the `ultralytics` Python package is installed automatically. - **Denoise** - 0 to 1. - **Steps** - 1 to 50. - **Guide size** - 256 to 1024px. - **Auto-prompt** toggle. --- # ControlNet and Style Transfer ## ControlNet A full ControlNet panel ships in the generation UI. Two ways to use it: - **Preset mode** - a grid of presets (Canny, Depth, OpenPose, LineArt, Scribble, Soft Edge, and more), filtered to what suits the active model family. In preset mode your reference image is preprocessed (for example edge detection) before being used as guidance. - **Custom mode** - pick the ControlNet model and preprocessor manually. Capabilities: - Reference image via upload, paste, or drag-and-drop. - Preprocessor preview so you can see the control map before generating. - Strength slider plus start% / end% timing sliders. - Auto-setup: missing ControlNet models are downloaded automatically, the `comfyui_controlnet_aux` preprocessor pack is cloned from GitHub, ComfyUI is restarted, and the install is verified. ControlNet setup failures do not block core generation. ### Anima (COSMOS) models Anima-based checkpoints are DiT models (a Cosmos-Predict2 backbone paired with a Qwen3 text-encoder adapter), not classic UNets, so standard ControlNet cannot be applied to them. When an Anima model is active, ControlNet automatically routes through the Anima LLLite path, which uses ComfyUI's built-in `ModelPatchLoader` and `AnimaLLLiteApply` nodes and needs ComfyUI 0.29 or newer. There is no extension to install: LLLite weights are downloaded into `models/model_patches`, and weights left in the controlnet folder by MooshieUI 1.9.0 or earlier are moved there the next time ComfyUI starts. On an older ComfyUI the panel tells you to update instead. This routing depends on the model being detected as the Anima family. Detection works even for Anima fine-tunes that were renamed without an `anima` or `yume` token in the filename (for example PerfectDeliberate): MooshieUI inspects the safetensors tensor structure, recognizes the Cosmos-Predict2 blocks and the Qwen3 adapter, and treats the checkpoint as Anima. The same structural check picks the matching Qwen3-0.6B text encoder, so a renamed or quantized Anima build still loads the right one. If a model is still misdetected, you can set its family manually with the family override in the model picker. ## Style Transfer (Anima RFInversion) The **Style Transfer** panel uses RFInversion through ComfyUi-Untwisting-RoPE and an advanced image-scaling node. It is an experimental Anima txt2img workflow, separate from the Anima Edit LoRA workflow called **Anima ReStyler** in [[Image Edit Mode]] and from the Style Reference panel below. - Reference image via upload, paste, or drag-and-drop. - MooshieUI checks that the required nodes are available. - It warns you if you have selected an ancestral sampler, which is not compatible with this technique. - It is unavailable during pause/continue and cannot be combined with ControlNet or the upscale pass. ## Style Reference (IP-Adapter / Flux Redux / Anima) **Style Reference** is a separate section in the generation sidebar (visible in txt2img, img2img, and inpainting). It uploads a reference image and guides the generation toward its colors, textures, and composition without replacing your text prompt. On Anima it works as a character reference instead (see [Anima character reference](#anima-character-reference)). The technique is chosen automatically from the active model family. | Model family | Technique | Required | |---|---|---| | Flux.1 dev / schnell / krea | Flux Redux | `flux1-redux-dev.safetensors` in `models/style_models/` + `sigclip_vision_patch14_384.safetensors` in `models/clip_vision/` | | SD1.5 | IP-Adapter Plus | `ip-adapter-plus_sd15.safetensors` in `models/ipadapter/` + `CLIP-ViT-H-14-laion2B-s32B-b79K.safetensors` in `models/clip_vision/` | | SDXL / Illustrious / Pony | IP-Adapter Plus | `ip-adapter-plus_sdxl_vit-h.safetensors` in `models/ipadapter/` + `CLIP-ViT-H-14-laion2B-s32B-b79K.safetensors` | | Anima | Anima Reference Adapter v2 (character reference) or Art style (training-free, no download) | `anima_ref_adapter_v2_r64.safetensors` in `models/loras/` for character mode (downloaded from the panel or on the first run); Art style needs no extra file | | All other families | Not supported | -- | ### Using the panel 1. Enable the **Style Reference** toggle in the sidebar. 2. Drop or browse to a style image. 3. Adjust **Strength** (0.0 to 1.0; 0.6 is a good starting point). 4. Choose a **Weight type**: - Flux Redux options: multiply (default), attn_bias, average - IP-Adapter options: linear (balanced), style transfer (emphasizes style over composition), composition, strong style transfer 5. For IP-Adapter only: adjust **Start** and **End** to control which fraction of steps the style reference applies for. 6. Generate as normal. ### Installing IP-Adapter Plus The ComfyUI_IPAdapter_plus custom node pack is required for SD1.5 and SDXL but is not installed by default. If it is missing, the panel shows an **Install IP-Adapter Plus** button. Clicking it clones the pack and installs its dependencies, then restarts ComfyUI. Flux.1 uses core ComfyUI nodes and needs no extra install. If a required model file is missing, the panel shows its expected path and a download link. ### Anima character reference On Anima, Style Reference uses the Anima Reference Adapter v2. It keeps who is drawn in the reference (hair, eyes, outfit and much of the art style), so you need no character LoRA or name tags. 1. Pick an Anima model and enable the **Style Reference** toggle. The panel shows **Anima Reference Adapter**. 2. Press **Download Anima Reference Adapter v2 (183 MB)**, or skip it and ComfyUI downloads it on the first run. 3. Drop or browse to a picture of the character under **Character**. 4. Write a prompt that describes only the scene: pose, place and framing. Leave out the character name and outfit tags. 5. Generate as normal. For two characters, add a picture under **Second character (optional, right side)**. In the prompt, say in a few words who is on the left and who is on the right, use `2girls` or `1boy, 1girl` instead of `solo`, and pick a landscape size. Settings: - **Reference guidance** (default 4.5): how hard the image is pushed toward the reference. Higher keeps more detail and style but adds saturation. At 1 there is no extra model call per step, so it is fastest but weaker; at the default a generation takes about twice as long. - **Colour correction**: keeps colours in check at high CFG and reference guidance. APG is recommended. - **End**: the fraction of steps that use reference guidance. Around 0.6 is faster with nearly the same image. Anima TeaCache is switched off while the character reference is on, and it cannot be combined with the Anima **Style Transfer** panel. The node pack installs automatically when ComfyUI launches. For manual setup, follow the [Style Reference model-file guide](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/STYLE_REFERENCE.md). The IP-Adapter image encoder is published as `models/image_encoder/model.safetensors` upstream; save it in `models/clip_vision/` with the expected `CLIP-ViT-H-14-laion2B-s32B-b79K.safetensors` filename. ### Anima Art Style mode Switch the Anima Style Reference mode from **Character** to **Art style** to take a picture's palette, shading and texture without its subject or characters. Describe the whole image in the prompt as normal; no character name or outfit tags from the reference are carried over. No additional downloads are needed. Controls: - **Style picture** - the reference image to draw the art style from. - **Style match** - how far the image moves towards the picture's colours and texture after each block. 0.6 is a good starting point; near 1 the image can break down. - **Keep my composition** - leaves the first quarter of the steps alone so the layout comes from your prompt. Turn it off for a stronger style change that may drift toward the reference's own layout. - **Picture size (megapixels)** - the reference is shrunk to this area before use, never enlarged. About the size of your output image works best (1 for 1024x1024). This method adds one model pass per step, so it is slower than the character reference. It has been tested mostly on Anima Turbo. ### Note on Anima ReStyler **Anima ReStyler** in [[Image Edit Mode]] uses the Anima Edit LoRA, with Reference strength and Drastic restyle controls. The older **Style Transfer** panel above uses RFInversion. **Style Reference** uses Flux Redux or IP-Adapter on its supported families, and the Anima Reference Adapter (a character reference or art-style reference) on Anima. These are distinct workflows with different model requirements; NovelAI Vibe Transfer and Precise Reference are documented in [[NovelAI Backend]]. --- # Inpainting and the Canvas Editor Inpainting mode lets you edit parts of an image using a built-in canvas instead of the ComfyUI node graph. The canvas opens automatically when you switch to inpainting mode. ## Multi-layer canvas The canvas editor is a full multi-layer editor: - **Tools** - Brush (B), Eraser (E), Rectangle (U), Lasso (Q), Eyedropper (I), Move (V), and Pan (H), selected from the canvas toolbar. Hold Alt to quick-pick a color with the eyedropper; releasing Alt returns to your previous tool. - **Draw mode** - in inpainting mode the toolbar has an Inpaint Mask / Regular Inpaint toggle that decides whether your strokes paint the mask or paint regular pixels. - **Layer panel** - layers are grouped into Inpaint Masks and Layers, each collapsible with a count badge and its own add button. Every row shows a live thumbnail, an enable toggle, and a lock, and you can reorder, duplicate, delete, or double-click to rename. The selected layer gets an opacity slider. - **Dimensions** - the canvas auto-syncs its size with your generation settings. Loading an image into inpainting (**Send to inpaint** from the gallery, or a drop) sets the canvas and the generation size to the image instead, so the mask matches it pixel for pixel. Very large images are scaled down to a 4 megapixel cap first. - **Live preview** - the in-progress generation is shown as an overlay on the canvas. - On generate, the editor exports a flattened raster composite plus the mask. ## Mask painting Paint a mask over the area you want to regenerate, using the brush, the Rectangle tool, or the Lasso for a freehand selection. Denoise strength (0 to 1) controls how much the masked area changes. With NovelAI selected, **Strength**, **Noise** and **Keep the area outside the mask** replace the ComfyUI denoise controls under the image upload. See [[NovelAI Backend]] for model-specific inpainting behavior. While you are painting, the mask stays visible. Once a result finishes it hides so you can see the clean output, and it comes back automatically during a re-roll or as soon as you paint more mask. ## Reviewing and accepting results Each Generate re-rolls the masked region from the original base image, so you can keep rolling variations of the same area without your earlier attempts stacking up. - **Accept** - when a result is ready an Accept button appears at the bottom of the canvas (and in the staging strip). Accepting promotes the current result to be the new base image so you can continue editing from it. - **Undo inpaint** - steps back through previously accepted bases. - **Staging strip** - lists the edit sources from the current session so you can send any of them back into inpainting. ## Correcting a paused generation For a paused ComfyUI Text to Image run, **Paint a correction** opens its preview here. Paint the correction, mask the area to replace and choose **Continue with edit from step …**. This blends the edit into the paused latent and runs the remaining sampling steps. See [[Generation Basics]] for continuation constraints and session lifetime. --- # Image Edit Mode Image Edit is the fourth generation mode, next to Txt2Img, Img2Img, and Inpainting. Instead of generating from scratch or denoising over an existing picture, you give the model one or more reference images and describe the change you want in words. "Make the sky purple", "put the character in a red jacket", "remove the car on the left". This is different from [[Inpainting and the Canvas Editor]], where you paint a mask to say *where* the change goes. In Image Edit you say *what* the change is and the model works out the rest, so no mask is involved. ## Supported models Image Edit needs a model trained for instruction editing. These families are supported: | Family | Reference images | Notes | |--------|------------------|-------| | **Qwen Image Edit** | 1 | Stock ComfyUI nodes | | **Qwen Image Edit Plus** | up to 3 | Stock ComfyUI nodes | | **Qwen Image Edit 2.1** | up to 10 | Includes Qwen Image Edit 2.1 Turbo (8-step schedule) | | **Flux.2 Klein** | up to 10 | 4B and 9B, distilled and Base; 9B KV files use the KV cache | | **FLUX 3 Klein** | up to 10 | Stock ComfyUI nodes (ComfyUI v0.41.0 or newer) | | **Flux.1 Kontext** | 1 | Stock ComfyUI nodes | | **MiniMax-H3-Image** | up to 16 | Stock ComfyUI nodes (ComfyUI v0.45.0 or newer) | | **MOSS-Image** | 1 to 4 | Uses the MOSS-Image Edit LoRA, downloaded automatically | | **Ming-Image Design** | up to 8 | Stock ComfyUI nodes | | **Krea 2** | 1 or 2 | Needs an edit LoRA; pick the method under Edit LoRA | | **Anima ReStyler** | 1 | Needs the Anima Edit LoRA | The family is detected from the loaded model, and the matching workflow is selected automatically. A badge in the Image Edit panel shows which one is active. Qwen Image Edit Plus taking three references is what makes it useful for combining pictures, for example putting a subject from one image into the setting of another. **FLUX 3 Klein** (distilled or Base) takes up to 10 references. The panel starts with three slots and adds one each time you fill the last. Refer to the images by order in the prompt (the first image, the second image) and describe the whole result, not only the change. The output size follows your width and height. **Anima ReStyler** works differently from the instruction families: instead of applying a described change, it redraws the character from your reference image in the Anima style, and the output matches the reference image's own size. It runs on an Anima checkpoint plus the Anima Edit LoRA, which downloads from within the app with the **Download Anima Edit LoRA (350 MB)** button. The LoRA comes from Civitai, so an API key or a VPN may be needed. If you switch to Image Edit while a model that cannot edit images is loaded, the panel warns you and asks for an edit-capable model. Load one from [[Models and the Model Hub]]. ## Using it 1. Select an edit-capable checkpoint. 2. Switch the mode tab to **Image Edit**. 3. Fill the reference slots. Each slot accepts a dropped file, a paste from the clipboard, or the **browse** link to pick a file. 4. Write the edit instruction in the positive prompt. 5. Generate. The prompt is an instruction, not a description of the finished picture. "Make the sky purple" works better than a full scene description, because the model is being asked what to change rather than what to draw. Reference images are downscaled so the long edge is at most 1536px before upload. For the Qwen families the first slot also sets the output dimensions, snapped to a multiple of 16. Flux.1 Kontext rescales internally, so its output size follows the model rather than the slot. Uploads work the same in the desktop app and in browser mode. ## Settings Steps, CFG, sampler, scheduler, and seed behave as they do elsewhere, and the usual per-family defaults apply when you load a model. Denoise is not used: an edit pass is not a partial-denoise pass the way img2img is. Anima ReStyler adds two of its own: - **Reference strength** - how closely the output follows the reference image. 1.0 keeps the composition and details intact; lower it (try 0.5 to 0.8) to let the prompt and style change the image more. - **Drastic restyle** - runs the original ReStyler split-screen recipe, generating the reference and a blank canvas side by side and cropping the new half as the output. Much stronger style changes, at roughly twice the generation time. ## Krea 2 Image Edit With a Krea 2 model loaded, the **Edit LoRA** picker lets you choose one of three methods. Each method downloads its own LoRA the first time: | Method | What it does | |--------|--------------| | **General Edit** | Plain-language edits: remove, recolor, relight, swap the background, add objects, rewrite text, restyle. Use Turbo at 8 steps, CFG 1 for most edits; for removals try Raw at around 20 steps, CFG 3. | | **Identity Edit** | Takes the person from your reference and places them in a new scene, pose, outfit or lighting. Describe how much of them is visible and the new context. | | **Style Reference** | Generates a new picture from your prompt in the style of one or two reference images. | **General Edit** and **Identity Edit** accept up to 2 reference images. Image 1 is the picture to edit; add a person as Image 2 to place them into it. Keep the total under 2 MP for best results. **Style Reference** uses one or two style images and the prompt describes the new picture. **Reference fidelity** controls how closely the output holds to the reference (higher preserves more likeness; lower gives the edit instruction more room). **Restage freely** places the person next to the canvas rather than pinned to its layout, so pose and framing can change more. ## Camera Angle (Qwen Image Edit Plus) With a Qwen Image Edit Plus model loaded, the panel shows a **Camera Angle** switch. Turn it on to re-shoot the reference from another angle: - **Direction** - eight steps of 45 degrees around the subject, from **Front** to **Back**. - **Height** - **Low**, **Eye level**, **Elevated** or **High**. - **Distance** - **Close-up**, **Medium** or **Wide**. The matching shot phrase is added to the start of your prompt, and **Added to the prompt** shows exactly what goes out. The words follow the Multiple-Angles LoRA's vocabulary, the same ones ComfyUI's CameraAngle node uses. When that LoRA is installed it is applied at strength 0.9 with its trigger word, which makes the angle much more precise. Without it only the shot words are sent. Use **Download Multiple-Angles LoRA (295 MB)** in the panel to install it. Results land in the gallery tagged with the Image Edit mode, so you can filter for them later. See [[Gallery and Metadata]]. --- # Image Editor MooshieUI has a built-in image editor for touching up results without losing their generation metadata. Editing in an outside program usually strips the prompt and settings from the file. Here, every save writes the source image's metadata onto the edited pixels, following your metadata settings. ## Opening it - **Edit** on the generation preview's hover buttons. - **Edit** on a gallery tile, in the grid or in Detailed View. The editor opens full screen. Layout and shortcuts follow Photoshop: tools on the left, tool options and actions along the top, adjustments and layers on the right, and a status bar with zoom, image size and a metadata badge. ## Tools | Tool | Key | Notes | |------|-----|-------| | Move | V | Drag the active layer, or drag a handle to resize it (Shift frees the proportions). Arrow keys nudge by 1 px, Shift+arrow by 10. | | Hand | H, or hold Space | Pan the view. | | Zoom | Z | Also the mouse wheel. Ctrl+0 fits, Ctrl+1 is 100%, Ctrl+= and Ctrl+- zoom in and out. | | Crop | C | Free, Original, 1:1, 4:5, 2:3, 3:2, 16:9, 9:16. Enter applies, Esc cancels. | | Brush | B | Size, hardness and opacity. `[` and `]` change size, Shift+`[` / `]` hardness. | | Eraser | E | Same options as the brush. | | Clone stamp | S | Alt+click sets the source. | | Eyedropper | I | Or Alt+click with the brush. | | Rectangular marquee | M | Ctrl+A selects all, Ctrl+D deselects, Ctrl+Shift+I inverts. | | Lasso | L | Freehand selection. | | Text | T | Click to place a line, type in the options bar, pick font, size, bold, italic and colour. | A selection limits the brush, eraser, clone stamp, Fill (Alt+Backspace) and Clear (Delete). Adjustments always apply to the whole image. The top bar also has rotate left and right, flip horizontal and vertical, and Image size (Ctrl+Alt+I) with a proportions lock. ## Layers - New layer (Ctrl+Shift+N), duplicate or copy the selection to a new layer (Ctrl+J), merge down (Ctrl+E), reorder and delete. - Each layer has visibility, opacity and a blend mode (15 modes, Normal to Luminosity). Up to 16 layers; they are flattened when you save. - **Layer masks**: Add mask creates a mask from the selection, or the whole layer. With Paint on, the brush hides and the eraser reveals, and Fill and Clear do the same for a selection. Enabled turns the mask off without losing it. - Text stays editable through crop, resize and Move. Painting on it, rotating, flipping or merging turns it into pixels. ## Adjustments Adjustments are non-destructive until you save. Double-click a slider to reset it. - **Light**: brightness, contrast, highlights, shadows. - **Curve**: click to add a point, drag to shape, double-click a point to remove it. - **Color**: temperature, tint, saturation, vibrance, hue. - **Detail**: sharpen, blur. - **Effects**: vignette. - **Preset**: save the current adjustments under a name and apply them to any other image. Presets are stored per browser or device. ## Undo and saving - Undo (Ctrl+Z) and redo (Ctrl+Shift+Z or Ctrl+Y) go back 30 steps. Very large images keep fewer steps, since each paint stroke keeps a copy of its layer. - **Save to gallery** (Ctrl+S) adds a new gallery item. The original is never overwritten. - **Save as file** (Ctrl+Shift+S) writes a PNG with the same metadata embedded. - Closing with unsaved changes asks **Discard changes?** first. ## NovelAI images Editing a PNG made by NovelAI keeps NovelAI's own PNG text chunks on the saved file, so novelai.net still recognises it and can read its settings. NovelAI's hidden alpha-channel data cannot survive edited pixels; the text chunks are what is kept. ## See also - [[Gallery and Metadata]] for how metadata is stored and read back. - [[Inpainting and the Canvas Editor]] to change part of an image with the model instead of by hand. --- # Compare Grid (XYZ Grid) The Compare tab (bottom panel) builds a grid of cells for side-by-side parameter comparison. - **Per-cell parameters** - each cell has its own generation settings. Tweak prompts, checkpoints, samplers, seeds, or any setting per cell. - **Grid generation** - pressing Generate queues every cell sequentially, sharing one random seed for a fair comparison. - **Auto-stitching** - finished grids are stitched into a single labelled image. Annotations show only what differs between cells (for example "blue eyes" vs "green eyes") plus a MooshieUI watermark. - **Spreadsheet naming** - cells use A1/B1/C1 labels with position-stable colors. - **Add/remove columns and rows** - new cells clone the adjacent neighbor so you can vary one parameter quickly. To hold two finished images against each other instead of generating a sweep, see [[Image Comparison]]. --- # Image Comparison The comparison viewer holds two images against each other so you can judge one against the other without opening them in a separate program. For parameter sweeps that build a grid of variations in one go, see [[Compare Grid]] instead. ## Opening a comparison 1. Press **Compare with...** on an image. It is pinned as side **A**. 2. Pick a second image and press **Compare with pinned image**. The viewer opens with that image as side **B**. **Cancel compare** drops the pin without opening anything. Compare is reachable from the gallery grid, the gallery list, the lightbox toolbar, and the right-click menu on a freshly generated image. ## Modes | Mode | What it does | |------|--------------| | **Slider** | Drags a divider across the pair, **Horizontal** or **Vertical**. | | **Fade** | Blends between A and B with a **Blend** slider. | | **Difference** | Shows only what changed, for spotting a subtle seed or CFG shift. | | **Side by side** | Puts the two images next to each other. | Difference needs two images of the same size. When they differ the viewer says so, and the other three modes still work. ## Moving around - Both images zoom and pan together, so a detail stays aligned as you look closer. Scroll to zoom, drag to pan, double-click to reset. - **Left** and **Right** arrows step image B through the rest of the gallery. Hold **Shift** to step image A instead, so you can keep one image fixed and flip through candidates against it. - With the divider focused, the arrow keys nudge it. - **Swap A and B** flips the pair, **Reset zoom and pan** returns to the fitted view, and **Escape** closes the viewer. --- # Models and the Model Hub ## Smart model detection and architecture presets MooshieUI recognizes a broad set of model architectures and auto-applies an optimal sampler, scheduler, steps, CFG, and resolution for each. Families include (among others): SD 1.5, SD 2.x, SDXL, Illustrious/NoobAI, Pony Diffusion, SD3/SD3.5, the Flux family (Flux.1 Dev/Schnell/Krea, Flux 2 Klein variants and FLUX 3 Image Klein), MOSS-Image, Chroma, Z-Image, Wan, Qwen, Krea 2, Ideogram 4 (Flux2 VAE path), AuraFlow, PixArt, HunyuanDiT, Stable Cascade, Kolors, Ming-Image, Anima (COSMOS), Mugen (SDXL + Flux2 VAE), and Nanosaur (1.2B DiT). The instruction-editing families (Qwen Image Edit, Qwen Image Edit Plus, Flux.1 Kontext, Flux.2 Klein, FLUX 3 Klein, MiniMax-H3-Image, MOSS-Image and Ming-Image Design) are detected too, and unlock [[Image Edit Mode]] when loaded. Behavior worth knowing: - **Accelerated models** (turbo, lightning, lcm, hyper in the name) get reduced steps and lower CFG automatically. - **Rectified flow** models inject the correct ModelSampling node with architecture-specific shift values. - **FluxGuidance** is injected for Flux Dev; Flux Schnell is detected and skipped. - **Hash-based identification** - models are recognized by SHA256 hash (CivitAI AutoV2), so renamed files still resolve. - **Transparent backgrounds** - images with a real alpha channel (for example from NovelAI V5 Transparent BG) are saved with their transparency instead of being made opaque. - **Structural identification** - MooshieUI inspects the safetensors tensor keys and identifies the architecture from the weights themselves, and when those weights clearly disagree with the filename the weights win (so an SDXL model misnamed like a Flux one is still classified as SDXL). Anima (COSMOS), Cosmos Predict2, Wan 2.1, Flux, Qwen-Image, SD3, SDXL, and SD 1.5 are all recognized this way, whatever the file is named, so an Anima fine-tune renamed without an `anima`/`yume` token (for example PerfectDeliberate) or a quantized FP8 build is still classified as the Anima family. An Anima fine-tune that ships its own text encoder named after the model (for example `name_txt.safetensors` beside `name.safetensors`) gets that encoder picked automatically. This matters twice over: it selects the matching text encoder for split models, and it routes ControlNet through the Anima LLLite path where that is required. See [[ControlNet and Style Transfer]]. ## Availability on the connected server Generation pickers use filenames advertised by the connected ComfyUI server. Recommended entries distinguish **Available in ComfyUI**, **Downloaded locally, unavailable to ComfyUI**, and **Unavailable in ComfyUI**. A file on the desktop is not automatically available to a remote worker. Refresh after installing the required files on that server; selecting a missing remote model does not start a local download. When the connection changes, previous server inventory and stale refresh results are discarded. Renamed or nested files resolve to an advertised server filename; ambiguous basenames remain separate choices. ## Misfiled models still load ComfyUI's own loaders only accept files from their own folder, so a diffusion model (unet or DiT only) dropped into the checkpoints folder, or a full checkpoint sitting in diffusion models, used to fail at generation time. MooshieUI now reads the weights to tell which kind a file really is, switches to the matching loader without asking, and loads the file by its full path. Misfiled models simply work, with nothing to move and no error to decipher. Quantized GGUF files are the exception, since their loader comes from a third-party node that takes no path. Keep those in the folder their category expects. A component in the wrong picker is different, because it cannot be loaded as something else. Text encoders and VAEs on their own cannot generate images, so when one is picked as the model, MooshieUI shows a red error under the picker that names the file, says what it is, and says where it goes (for example under **Text Encoder** or **VAE**). The same check covers a text encoder or model picked under **VAE**, and a VAE or model picked under **Text Encoder**, and **Generate** stops with the same message instead of failing inside ComfyUI. Detection reads the file's tensor layout, GGUF text encoders included, so renaming a file does not change the result. ## Model information Selecting a model shows what the file itself declares: the preview thumbnail stored inside it, plus **Date**, **Implementation**, **SHA256**, **Merged from**, **Preprocessor**, **Encoder layer** and **ModelSpec version** where the author filled them in. An architecture worked out from the weights rather than declared in the file is marked **inferred**. Anything else the file declares is listed under **Other ModelSpec fields**, so nothing a model author wrote is hidden. ## GGUF quantized models `.gguf` diffusion models and text encoders generate like any other model, so you can run large architectures (Krea 2 and similar) on cards that cannot hold the full-precision weights. - Turn on **Use Split Model Components**, then pick the `.gguf` file under **Diffusion Model**. Quantized encoders work the same way under **Text Encoder**, which lists files from both the `text_encoders/` and `clip/` folders. - Routing is automatic. ComfyUI's core loaders cannot read `.gguf`, so MooshieUI sends those files to the ComfyUI-GGUF loaders instead. There is nothing to configure. - The ComfyUI-GGUF nodes install during ComfyUI setup and are re-checked on every start. If the install fails, ComfyUI still starts normally and only GGUF models are unavailable until it succeeds. - Detection works on GGUF files too. The family now resolves from the GGUF header itself (its architecture field and tensor names) as well as the filename, sidecar metadata, and hash, so a renamed GGUF still lands on the right family; the accelerated variant and recommended encoder round out the preset. A file like `Krea-2-Turbo-Q5_K_S.gguf` gets the correct settings instead of falling back to unknown. Wulver (a Krea 2 fine-tune whose filenames carry no Krea marker) is also detected: files without `non_turbo` in the name are classified as Krea 2 Turbo, and `non_turbo` files get the standard Krea 2 defaults. Put `.gguf` diffusion models in your diffusion models folder and quantized encoders in `text_encoders/`. The model manager (below) handles both categories. ## INT8-Fast quantized models INT8 W8A8 and ConvRot builds (Flux 2, Flux 2 Klein, Z-Image, Chroma, Krea 2, Qwen-Image, Anima and Ideogram 4) need the ComfyUI-INT8-Fast loader rather than ComfyUI's core loader. It is NVIDIA-only. - Turn on **Use Split Model Components**, pick the INT8 file under **Diffusion Model**, then turn on the **INT8-Fast loader** toggle. **Enable ConvRot** underneath is on by default and should stay on for ConvRot files. - The node pack is not installed by default. The toggle shows **Install ComfyUI-INT8-Fast** the first time; installing restarts ComfyUI. - If a filename looks like an INT8 or ConvRot build while the toggle is off, MooshieUI points this out under the model picker. A generation that fails with `unknown quantization format for layer` is the same problem. - The toggle is disabled (greyed out) when the selected diffusion model is a `.gguf` file. The tooltip reads "Not available for .gguf models (already optimized)" to explain why. Use the GGUF loaders for those files instead. ## FLUX 3 Image Klein FLUX 3 Image Klein comes as a distilled model and a Base model. Both are detected from BFL and community file names, CivitAI base model names and the file's own tensors, so a renamed file still gets the right preset: 16 steps at CFG 1 for distilled, 50 steps at CFG 3.5 for Base, Euler on simple. Klein needs the Qwen3-VL 4B text encoder (the same one Krea 2 uses) and the Flux 2 VAE. If either is missing it downloads on its own, and generating with a different encoder or VAE stops with a message naming the right one. Klein also works in [[Image Edit Mode]] with up to 10 references. It needs ComfyUI v0.41.0 or newer. The Model Hub quick links include **FLUX 3 Klein INT8 (HF access)** and **FLUX 3 Klein Base INT8 (HF access)**. These come from BFL's gated Hugging Face repo, so they need a Hugging Face token from an account that has accepted the FLUX license. ComfyUI loads these INT8 ConvRot files itself, so leave the INT8-Fast loader off for FLUX 3. ## MiniMax-H3-Image MiniMax-H3-Image is the 33B MiniMax H3 image model. Txt2img and Image Edit (up to 16 references) share one checkpoint. It uses the same Qwen3-VL-32B text encoder as the H3 video model, so a copy already downloaded for video is reused automatically. - **Default preset**: 6 steps at CFG 1, using the model's own sigma grid. - **pDMD 2-step mode**: a separate LoRA (`minimax_h3_pdmd_2nfe_comfyui.safetensors`) or a checkpoint with it merged in reduces generation to 2 steps. The model is detected as the pDMD family and the preset is applied automatically. - **Resolution**: works best from 4 to 20 MP (native around 16 MP, 4096x4096). Batch size is always 1 (the model's own limit); larger batches run as sequential samplers. - **Model Hub**: INT8 and W4A8 downloads are available. - **License**: the MiniMax-H3-Image Community License. Written permission from MiniMax is needed above US$1M annual revenue or to offer it as a hosted service. A notice appears under the model picker when this model is selected. ## Qwen-Image 2.1 and Qwen-Image 2.1 Turbo Qwen-Image 2.1 and Qwen-Image 2.1 Turbo are detected as a distinct architecture from Qwen-Image 1 (earlier releases misidentified them and they could not generate). Both use the right encoder and VAE automatically. - **Qwen-Image 2.1** is detected from its tensor layout and the 2.1 marker in the filename. - **Qwen-Image 2.1 Turbo** runs on its own 8-step schedule, which the preset applies automatically when the Turbo variant is detected. - Both are available in [[Image Edit Mode]] with up to 10 references. - Downloads are available from the Model Hub quick links. ## Architecture registry From v2.4.0, model families are declared once in a registry that sets detection, the text encoder and VAE, extra model files, supported modes, sampling defaults and Model Hub downloads. A family on the registry downloads its missing encoder and VAE on its own and refuses a mode it cannot run with a message, instead of producing a broken image. The families below moved onto it in v2.4.0. ## Flux.2 Klein Flux.2 Klein 4B and 9B, distilled and Base, run txt2img and [[Image Edit Mode]] with up to 10 reference images. Defaults follow ComfyUI's bundled Klein templates: 4 steps at CFG 1 for distilled, 20 steps at CFG 5 for Base. A Klein 9B KV file (`klein`, `9b` and `kv` in the name) also gets the KV cache. Klein is told apart from Flux.1 by its tensors, so a renamed file is no longer read as Flux.1. The Model Hub links BFL's FP8 files; the 9B repos are gated and need a Hugging Face token. ## Flux.1 and SD3 from split files Split Flux.1 files (dev, schnell, Krea, Kontext) load T5-XXL and CLIP-L together, as ComfyUI does. Earlier releases loaded T5 alone, which degraded every image without an error. CLIP-L and the Flux VAE download when missing. SD3 and SD3.5 split files load CLIP-L, CLIP-G and T5-XXL together, and Stability's own release files (`sd3_medium`, `sd3.5_large`, `sd3.5_medium`, `sd3.5_large_turbo`) work as they are. SD3.5 Large Turbo runs at 4 steps, CFG 1. The encoders download from Comfy-Org's ungated repo; the SD3 VAE is only in Stability's gated repos, so a GGUF model without one stops with a message pointing at its Model Hub entry. ## Stable Cascade Stable Cascade generates with the official two-stage workflow: stage C at your settings, then stage B (10 steps, CFG 1.1) and stage A to decode. Txt2img, img2img, hires fix and face fix are supported. Stage B is the official all-in-one ComfyUI checkpoint, or a stage B UNet plus stage A; the model panel uses one you have or downloads the checkpoint (about 4.6 GB). ControlNet and pause/resume are not available for Cascade. ## Wan as an image model Wan 2.1 (1.3B and 14B), Wan 2.2 A14B and Wan 2.2 TI2V 5B generate stills with the umT5 text encoder. Each gets its own VAE (TI2V 5B uses the 48-channel Wan 2.2 VAE), and Wan 2.2 A14B runs its high-noise and low-noise experts in turn. ## Kolors Kolors runs through a loader node bundled with MooshieUI, so no third-party node pack is needed. It needs the Kolors UNet, the Kolors VAE and all shards of the ChatGLM3 text encoder; the Model Hub entry downloads the full set (about 17.8 GB). The tokenizer downloads once on first use. ControlNet is not available for Kolors. ## Ming-Image 0.1 inclusionAI's Ming-Image comes as two models: - **Ming-Image Design**: txt2img, img2img, inpainting and [[Image Edit Mode]] with up to 8 references. Defaults are 12 steps at CFG 1 and 2048x2048, so the negative prompt box is hidden. A **Transparent background** checkbox under Dimensions asks for a cut-out, and the PNG keeps its transparency. Upscaling, face fix and segment detail drop the alpha channel. - **Ming-Image Layer**: a separate checkpoint with its own text encoder. ## MOSS-Image OpenMOSS's MOSS-Image comes as MOSS-Image (SFT) and MOSS-Image Base, for txt2img, img2img and [[Image Edit Mode]]. Both are detected from Comfy-Org and community file names, CivitAI base model names and the file's own tensors; only a `base` marker in the name selects Base, since both share the same tensors. The preset follows Comfy-Org's templates: 25 steps at CFG 2.5, er_sde on simple, 1024x1024, with the negative prompt kept on. MOSS-Image needs the Qwen3.5 9B text encoder and the Flux 2 VAE. If either is missing it downloads on its own, and generating with a different encoder or VAE stops with a message naming the right one. It needs ComfyUI v0.43.0 or newer, which the managed ComfyUI uses from v2.3.34. The Model Hub quick links include **MOSS-Image INT8**, **MOSS-Image Base INT8** and **Qwen3.5 9B W4A8 (MOSS-Image)**, from Comfy-Org's ungated repo. ComfyUI loads these INT8 files itself, so leave the INT8-Fast loader off for MOSS-Image. ## PixArt Sigma and PixArt Alpha Both models now generate (earlier releases detected them but could not generate). They always load split: the DiT through the diffusion model loader and the T5-XXL text encoder through the text encoder picker. No custom nodes are needed; ComfyUI's core loaders handle both the original `.pth` keys and diffusers safetensors format. - **Text encoder**: T5 v1.1 XXL (`t5xxl_fp16` or `t5xxl_fp8_e4m3fn`). MooshieUI downloads the FP8 version automatically when it is missing. - **VAE**: PixArt Sigma uses the SDXL VAE (`sdxl_vae.safetensors`); PixArt Alpha uses the SD 1.5 VAE. Both download automatically when missing. - **Preset**: 20 steps, CFG 4.5, DPM++ 2M sampler, normal scheduler, 1024x1024. - **Detection**: Sigma and Alpha are told apart by their tensor structure (Sigma has no micro-conditioning weights; Alpha does), so renaming a file does not confuse them. - **Prompt style**: natural language (full sentences, not tags). ## Krea 2 uncensored mode Krea 2 reads your prompt through Qwen3-VL-4B, a chat model trained to refuse some requests, and its TextFusion layers (which turn that encoder output into conditioning for the image model) learned to tone those concepts down. Things can come out weakened or missing, and not only NSFW ones. When a Krea 2 model is selected, an **Uncensored mode** panel appears under the **Text Encoder** picker. - Uncensored mode combines two fixes for the two stages: an abliterated (Heretic) copy of the same encoder at the same fp8 precision (DreamFast/Qwen3-VL-4b-Heretic-ComfyUI), and Capitan01R's TextFusion refusal-reduction LoRA (v2.0 full rank) at strength 1.0. - **Download and turn on** fetches whatever is missing (about 7.4 GB for both) and switches the mode on when the downloads finish. If you set up the uncensored encoder in v2.3.16, the panel shows **Finish setup** to add the LoRA (2.6 GB). You also get a one-time notification with a **Download and turn on** button that does the same; download progress shows in the download banner. - **Turn on** and **Turn off** switch between uncensored mode and the standard encoder. The panel shows **Active** while it is on. The choice is remembered across models and restarts, and picking an encoder by hand in the **Text Encoder** picker updates it too. - The LoRA is applied automatically to Krea 2 generations only and does not appear in your LoRA list, so it never carries over to another model family. It is skipped if you already have a version of it enabled yourself, and it is recorded in the image metadata. - It cannot add concepts the image model itself never learned. If something still does not appear in uncensored mode, the limit is in Krea 2's own training. ## Recommended models (auto-download) In managed local mode, a few curated checkpoints can auto-download on selection with a live progress bar and file size, including a NoobAI/Illustrious checkpoint Anima Base v1.0 (~5.6 GB), and Anima Turbo and Aesthetic v1.1. The exact recommended list evolves between releases, so treat the in-app list as the source of truth. ## Model Hub (CivitAI / HuggingFace browser) Browse and download models from inside the app: - Filter by type (Checkpoint, LoRA, ControlNet, Upscaler, VAE, Textual Inversion), sort (Highest Rated, Most Downloaded, Newest), time period, architecture, and file format (SafeTensor, PickleTensor, GGUF, Diffusers, CoreML, ONNX, Other). - Add a CivitAI API key for gated content. - **Open on CivitAI** opens the model's page. Mature models open on civitai.red, where CivitAI serves them; pasted civitai.red model links work too. - One-click download routes the file to the correct folder with a real-time progress bar. Switch the source from **CivitAI** to **Direct URL** to install from any legal direct model link (Hugging Face, a mirror, a private host). Paste the **Model URL**, confirm the **Filename**, and choose where it lands under **Category**: Checkpoint, Diffusion Model, LoRA, Upscaler, VAE, ControlNet, Textual Inversion, or Text Encoder. Diffusion Model is the right home for a bare DiT checkpoint that carries no built-in text encoder. Hugging Face links must be `/resolve/main/` file URLs, not model page URLs; the field tells you if you paste the wrong one. Quick links cover common downloads, including SDXL Base 1.0, the OmniSR upscalers, the Qwen3-VL 4B FP8 encoder that Krea 2 uses, and Krea 2 - Wulver v0.5 FP8 (Turbo). ## CivitAI-enriched galleries The bottom-panel LoRA and Checkpoint galleries auto-fetch CivitAI metadata (name, preview images, model ID) for your local files and cache it for 24 hours. Their CivitAI links open mature models on civitai.red. The LoRA gallery lets you set a thumbnail from a CivitAI image URL. Both support search and sort by name, date, or family, plus right-click actions. The sort dropdown also has **Folder** and **Tree** modes that group your LoRAs by their on-disk folders (Tree mirrors the Model Manager's collapsible folder view), handy when your LoRAs are organised into subfolders. ## Bulk CivitAI scan Above the search bar in the LoRA gallery, a **Scan all models on CivitAI** button hashes every LoRA, checkpoint, diffusion model, and embedding in your library, queries CivitAI by hash, and writes a `.civitai.info` sidecar file next to each match. This populates the gallery thumbnails, names, and model IDs in one pass rather than waiting for them to be fetched on demand. While the scan runs, a progress bar shows the current file being hashed ("Hashing filename...") and a "{current} / {total}" counter. A **Cancel** button stops the scan at any point (it drains to "Cancelling..." before halting). When complete, a summary line reports how many files were found on CivitAI, how many were not found, and how many were skipped. Files that already have a cached `.civitai.info` sidecar are skipped by default. Once a scan has finished, the button label changes to **Re-scan all models**, which forces a fresh hash and lookup even for already-cached files. Use **Re-scan all models** if a model's CivitAI page was updated after your original scan. A **Dismiss** button closes the progress panel after the scan completes. ## YuE2 music checkpoints Music has a separate **YuE2 checkpoint** selector under **Generation settings**. **Models and setup** offers the official INT8 (4.0 GB) and BF16 (7.8 GB) downloads, subject to the account's download permissions. These files go in `ComfyUI/models/checkpoints` and include the generator, text encoder and audio VAE. The weights have a non-commercial license. See [[Music Generation]] for runtime and hardware requirements. Native covers also need **SheetSage2** under the separate **Audio encoder** selector. Its download is 1.39 GB and belongs in the transcription worker's `models/audio_encoders` folder. It is not a YuE2 checkpoint. See [[Music Generation]] for transcription and score review. ## Model manager In Settings you can manage local model files across categories (checkpoints, loras, vae, upscale, controlnet, embeddings, ultralytics, text encoders, diffusion models): search by filename, delete files, move files between configured directories or to a different category (for example a checkpoint into your diffusion models folder), and see total disk usage per category. Switch between **List** and **Tree** view: List is a flat, sorted list, while Tree groups files by the folders they're stored in so large collections mirror your actual on-disk folder structure. You can create folders (**New Folder**) and move models into them. ## Model requests (multi-user) In hosted/multi-user deployments, non-admin users can request a model download by CivitAI URL. Admins and moderators see a pending/approved/denied queue and can approve (which starts the download) or deny with a reason. See [[Server, LAN and Multi-User]]. --- # Gallery and Metadata ## Gallery - **Persistent** - saved images and videos are discovered from the gallery directory; SQLite caches metadata. Saved items remain available across sessions, subject to retention settings. With **Manual save mode** enabled, finished results wait in the preview until you choose **Save to Gallery**; **Discard** drops an unsaved result. - **Thumbnail grid** - responsive, sortable by date. - **Lightbox** - click any image for full size: scroll-wheel zoom at the cursor, double-click to reset, Escape or click-outside to close. Deleting from the lightbox moves on to the next image (the previous one at the end of the list) instead of closing, so you can review and cull at full size. The metadata panel includes how long the image or video took to generate. - **Image management** - rename, delete, copy to clipboard, and upscale from the gallery. Deleting from a tile, a Detailed View row or the selection bar removes the images at once and shows a **Deleted N** toast with **Undo** for 7 seconds. The files only go to the bin when the toast closes, and **Undo** brings them back with their board, favourite and rating. Originals in a linked folder, and deletes from a right-click menu, ask **Delete this image?** first, and deleting more than 10 selected images asks before the toast. The lightbox trash button and the bottom panel's selection bar delete in one click for quick culling. Deleted images and videos go to the OS Recycle Bin (Windows), Trash (macOS), or desktop trash (Linux) rather than being permanently removed. If no usable bin is available, the file is deleted for good. - **Touch screens** - tapping a tile opens the preview. To reach a tile's buttons, tap the **⋯** (Actions) button in its bottom-right corner; tap it again to close the tray. Keyboard focus inside a tile also shows the tray. - **Video actions** - hover a still image for **Make video** (send it to a new video generation as the first frame) or **Add as video reference** (add it to the reference slots). See [[Video Generation]]. - **3D** - on a still image, opens the 3D page with that image as the source. See [[Image to 3D]]. - **Boards** - sort images into named boards. **Create Board** adds one, **Assign board** on an image moves it there, and the **Board Filter** shows one board, **All Boards** or **Unsorted**, with each board's image count. With a board picked, **Rename board** and **Delete board** appear beside the filter. Renaming to an existing board's name merges the two, and deleting a board sends its images back to Unsorted. A row of board chips above the grid sets the filter in one click; drag a tile (or a selected tile, to move the whole selection) onto a chip to move it there. Past 10 boards the row shows the 8 with the most images (plus the selected one), and **More boards** opens a searchable list of every board with its count. The gallery can also be grouped by board. **Sort by Artist** assigns images to boards automatically from the artist tags in their prompts, with **Undo** in its toast. For an earlier sort, **Remove artist boards (N)** deletes the `@name` boards and sends their images back to Unsorted, also with Undo. Boards belong to your account and sync across devices. - **Edit** - the Edit button on a gallery tile opens the built-in editor, which keeps the image's generation metadata on every save. See [[Image Editor]]. - **Edit in Photopea** - the pencil button in the lightbox opens the image in the embedded [Photopea](https://www.photopea.com/) editor. **File > Save** (Ctrl+S) inside Photopea saves the result back to the gallery as a new image; the original is kept. Photopea loads from photopea.com, so it needs an internet connection. - **Compare** - hold any two images against each other in a slider, fade, difference or side-by-side view. See [[Image Comparison]]. - **Mode labels** - output records its generation mode, including Image Edit and video. - **Show Generation Time** - a checkbox in the gallery toolbar that displays each item's generation time directly on the grid and details view, instead of only on hover. - **Large galleries** - only the rows near the screen are drawn, and thumbnails are cached on disk (up to 1 GiB), so galleries with thousands of images scroll and reopen quickly. In hosted/multi-user mode regular users and moderators have isolated galleries. Their saved images and videos expire after 7 days by default; an admin can disable this with **Never auto-delete gallery images** in Settings > Gallery. The shared root gallery used by desktop/localhost/admin accounts is not expired by this cleanup. Account storage quotas are separate from expiry. ## Selecting and bulk actions Every tile and Detailed View row has a checkbox (shown on hover, always shown on touch screens or once anything is selected). A plain click still opens the image. - **Shift+click** selects a range, **Ctrl/Cmd+click** picks single images, **Ctrl/Cmd+A** selects everything the current filters show. **Escape** clears and **Delete** deletes. With **Group By** on, each group header has its own checkbox. - **Arrow keys** move a cursor through the grid. **Shift+arrow** extends the selection, **Space** selects, **Enter** opens the image. - The bar at the bottom moves the selection to a board, sets rating, favourite or NSFW, compares two images, or deletes. - **Eagle** sends the selected images to Eagle when Eagle export is on. See [Eagle export](#eagle-export). - **Export** (desktop) asks for a folder and writes a copy of every selected image there with its metadata embedded. Videos are copied as they are. Changing a filter drops selected images it hides, so a bulk action never touches an image you cannot see. ## Eagle export MooshieUI can send images to [Eagle](https://eagle.cool) through Eagle's local API. Turn it on in **Settings > Connection > Eagle export**; Eagle must be open on the same computer. - **Send every image as it is saved** (on by default) sends each new image in the background, so a closed Eagle never slows a save. Turn it off to send only with the **Eagle** button in the selection bar. - **Eagle folder ID (optional)** picks the Eagle folder; leave it empty to send to Eagle's inbox. - **Test** reports Eagle's version, or says Eagle isn't reachable. Eagle copies the original file, nothing is re-encoded. Tags come from the prompt with weights and emphasis removed, plus a `model:` tag (up to 40 tags). The annotation holds the full prompt, negative and seed. Only the owner's own gallery is sent; on a shared server, other accounts' images never reach the owner's Eagle library. ## Finding repeats The **Repeats** filter shows only images generated more than once with the same prompt, negative, seed, model, sampler settings and size, grouped per set with the oldest first. **Select extras** selects every copy but the oldest, ready to delete. Images from one batch share a seed but are not counted as copies of each other. This compares saved settings, not pixels. ## Characters in the gallery Once you have saved characters, the gallery matches them to images by the tags in each image's prompt, with no model run. A card tagged `1girl` only matches images with a girl; otherwise the character's name as a tag, or most of its identity tags (hair, eyes, ears and the like), make a match. NovelAI images are checked one character box at a time. - The **Character** filter shows each character with a count, and **Group By** can group by character. Detailed View lists the characters found under the file name. - **Sort by Character** moves Unsorted images with exactly one character into a board named after it, with **Undo** in its toast. **Remove character boards (N)** takes those boards away again later. The counts in the Character filter are worked out in the background and appear once ready, so the gallery opens without waiting for them. - **Scan for characters** runs the built-in tagger on images with no saved prompt (imports, stripped metadata), on the selection or on everything shown. Each image is tagged once and remembered. Over 100 images it asks first; while it runs the button shows **Stop scan (done/total)**. Linked folders and videos are not scanned. ## Folding the filters The **Filters** button next to the search box folds the filter panel down to the search row. The choice is remembered, and a dot on the button shows when a folded filter is narrowing the gallery. **Reset filters**, at the end of the board row, appears whenever a search or any filter is narrowing the gallery and clears all of them at once. Sort, grouping and view stay as they are. It stays visible with the filters folded. ## Search, favourites and NSFW In v2.3.21 and later the gallery toolbar has a search box and more filters. - **Search** looks through each image's prompt, model, LoRAs and file name. Every word must appear. `"red scarf"` in quotes matches the exact phrase, and `-hat` leaves out images that contain hat. The fields `neg:`, `model:`, `lora:`, `sampler:`, `scheduler:` and `file:` search one part only, for example `neg:blurry` or `model:illustrious`. `seed:`, `steps:` and `cfg:` take a number with `=`, `>`, `>=`, `<` or `<=`, for example `steps:>=30`. The **?** button next to the box lists the syntax. - **Favourites and ratings** - mark an image as a **Favourite** or give it 1 to 5 stars. Filter with **Favourites only** and the **Rating** filter, or sort by rating. In the lightbox, `1` to `5` set the rating, `0` clears it, `F` toggles favourite and `N` toggles NSFW. - **NSFW** - images whose prompt contains one of the keywords in Settings > Gallery are flagged NSFW automatically, unless you have marked them yourself. The **NSFW** filter offers **Show all**, **Hide NSFW** and **Only NSFW**. **Blur NSFW** (off by default) blurs them in the gallery, the bottom strip and the image picker, and the lightbox covers them until you choose **Show NSFW image**. Favourites, ratings and NSFW marks belong to your account and sync like boards, so browser and LAN users keep them across devices. ## Linked folders (desktop) Settings > Gallery > **Linked folders** shows the images in other folders and their subfolders in the gallery without copying them. Search, ratings and boards work on them too, and they get thumbnails, metadata, the lightbox, copy and export. The **Source** filter switches between **All sources**, the **MooshieUI gallery** and each linked folder. Deleting a linked image asks first and moves the original file to the recycle bin. **Stop showing this folder** removes a folder without touching its files. Linked folders are not available in browser or LAN mode. ## Refresh gallery MooshieUI v2.3.6 adds **Refresh gallery** to the toolbar. Use it after adding, replacing or deleting files outside the app. It reads the gallery directory again, refreshes metadata and thumbnails, adds newly discovered files and removes missing saved files. Unsaved results and saves already in progress are preserved. Refresh does not rename files or run the legacy metadata migration. ## Save format **Format** in the sampler settings picks how generated images are written to disk. | Format | Notes | |--------|-------| | **PNG** | The standard, widest support. | | **JXL** | JPEG XL, lossless and roughly 40% smaller than PNG, with metadata in a SwarmUI-compatible XMP box. Not every viewer opens it. | | **WebP** | Lossless (VP8L), smaller than PNG, and openable by any browser, phone or image viewer, so it suits images headed somewhere outside the app. | WebP has no 16-bit mode, so choosing it locks **Bit Depth** to 8-bit and the 16-bit button explains why. Exporting a WebP out of the gallery keeps the original file rather than converting it. ## Metadata embedding Generation parameters are embedded into your saved images so they can be read back later. - **PNG text chunks** - standard tEXt metadata, and UTF-8 iTXt when the prompt contains characters tEXt cannot hold (Japanese, Chinese, Korean, emoji). Reading also handles iTXt and compressed zTXt, so images written by other tools that use them are not treated as having no metadata. - **Stealth alpha** - parameters can also be hidden in the least-significant bits of the alpha channel, readable client-side without a server round-trip. It works with PNG and with lossless WebP. - **JPEG XL (JXL)** - metadata goes in a SwarmUI-compatible XMP box. - **WebP** - parameters are stored as an EXIF UserComment following the A1111 convention, so exiftool, CivitAI and the usual web UIs read them back. - **NovelAI PNGs** - original provider text chunks and NovelAI's own stealth data survive saving, clipboard copying and face-detail compositing, so novelai.net still recognises the file. To show it was made with MooshieUI, the app adds one small `MooshieUI` text chunk at the end of the file (app version, NovelAI model, time and whether it came from the app or MCP, no prompt) and changes nothing else: no pixels, whatever the Metadata setting. Copying or exporting the same image again never adds a second one. The metadata panel shows **Source: MooshieUI (NovelAI)** for these and **NovelAI** for images straight from novelai.net, while the settings still come from NovelAI's own data. The import dialog understands their characters and NovelAI options. See [[NovelAI Backend]]. ## Image Info The **Image Info** panel shows the generation parameters for the selected image in the gallery lightbox or details view. - **Stable field order** - fields appear in the same order on every image, regardless of how they were saved. - **Choose fields** - the button in the Image Info header opens a **Fields** editor where you can hide individual fields and drag them to reorder them. The choice is remembered. - **LoRAs one per line** - each LoRA appears on its own line, with the weight shown in a small coloured pill. ## Video metadata and export Gallery videos retain generation parameters and timing. Export supports MP4, animated WebP, AVIF and GIF; MP4 keeps audio. Each has a metadata carrier, and MP4/AVIF also receive an XMP box. Sharing or re-encoding can remove metadata, so retain the original when you need to recover settings. See [[Video Generation]] and the [metadata-carrier reference](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/METADATA_CARRIERS.md). ## Remix and Reuse Settings On a saved gallery image, **Remix** restores its settings with a new random seed. **Reuse Settings** also restores the saved seed. In v2.3.7 and later, both actions restore the saved LoRA list, including separate model and CLIP strengths of zero. Restoring an image made without LoRAs clears the current LoRA selection. Only LoRAs present in the connected server's loaded model list are restored. Missing LoRA files are skipped. **Reuse Seed** changes only the seed and leaves your LoRA selection alone. ## Invisible watermark and fingerprint Text chunks and stealth alpha are lost when a site re-encodes an image, it is resized, or someone screenshots it. Two invisible layers let a stripped copy find its gallery record, which still holds every setting. - **Fingerprint** (always on, no setting): every gallery save stores a perceptual hash in the gallery index. Nothing in the image file changes. - **Watermark** (off by default): the **Watermark** Off/On chips under **Metadata** hide an invisible ID in the pixels of every saved image, with no visible change. The first use downloads about 65 MB. NovelAI PNGs, 16-bit images, videos, images under 256 px and JXL saves are not marked. When you drop or open an image with no metadata of its own, MooshieUI reads the watermark, then looks for the closest fingerprint among the images in your own gallery folder, and restores that image's settings. The toast says **Restored ... from the watermark** or **Restored ... from a gallery match**. A MooshieUI watermark with no record in your gallery shows **Made with MooshieUI, but not in your gallery**. ## Drag-and-drop remix (metadata import) Drag or paste a previously generated image into MooshieUI to read its embedded settings. It understands SwarmUI JSON (`sui_image_params`), A1111-style text and NovelAI metadata; NovelAI imports offer a choice of fields to restore. PNG parsing can happen client-side; other formats are read by the app. An image without metadata can still be matched to your gallery (see Invisible watermark and fingerprint above). Missing metadata cannot restore an original img2img source or guarantee identical pixels. Imports normally adopt the image's aspect ratio at your current resolution rather than replacing the pixel dimensions. Inpainting aligns the canvas to the image, a direct drop onto Dimensions explicitly requests its size, and resolution locking changes the import behavior. See [[Generation Basics]]. This pairs well with image interrogation (see [[Prompting Guide]]) when you want to recover a prompt from an image that has no embedded metadata. --- # Server, LAN and Multi-User MooshieUI can run as a headless web server that serves the same Svelte UI over your network, including a dedicated mobile layout for phones and tablets. ## Phone layout On a phone the app uses a bottom bar with **Generate**, **Video**, **Gallery**, **Music** and **More**. **More** holds Artists, Characters, Scenes, Image to 3D (when its experimental toggle is on), the Model Hub (when allowed), Settings, Interrogate, notifications, bug reports, the connection status and **Switch to desktop layout**. A dot on **More** means unread notifications or a lost connection. On the Generate page the header holds the settings tabs, Profiles, the mode switcher and the Canvas Editor toggle. A dock above the bar keeps **Prompt**, **Model**, **Library** and the Generate button in reach. Tap or drag the grab bar on an open panel to close it. Prompts are the first section by default. ## Running the server See [[Installation]] for Docker and remote-ComfyUI setup. The desktop app's browser server binds `127.0.0.1` when LAN access is off and `0.0.0.0` when it is on. The headless server always enables LAN access and binds all interfaces. The default internal port is `3200`; the supplied Compose file's `MOOSHIEUI_PORT` sets the published host port. Outside Compose, the internal port comes from `ui_server_port` in the app config. The desktop browser-mode heartbeat watchdog can shut down the app after its browser closes; LAN mode disables that idle shutdown. In v2.3.36 and later the desktop window does not need browser mode to share: with LAN access on, the app starts the web server on your network at launch and keeps its window open, so other devices can connect while you work in the app. The headless server runs independently of any browser tab. ## Sharing on your network (LAN mode) Turn on LAN access in Settings > App Mode, from the desktop window (v2.3.36 and later) or from browser mode. In v2.3.22 and later the LAN section lists the addresses other devices can use, each with a **Copy** button: - `http://mooshieui.local:PORT` comes first (desktop builds). The desktop app announces this name on the local network, so devices on the same Wi-Fi can open it without knowing the PC's IP. If another machine already uses the name, MooshieUI takes `mooshieui-2.local` and shows that instead. If a device can't open the `.local` address (some Android phones and Windows PCs), use the IP address instead. - Then this PC's network IP addresses. VPN, VM and container adapters are skipped, and each address uses the port and scheme the server actually listens on. The server only becomes reachable from other devices after a restart, and the section says so right after LAN access is turned on. ### Windows Firewall On Windows, turning on LAN access checks the firewall. If other devices would be blocked, MooshieUI adds an allow rule named "MooshieUI LAN access" after one admin (UAC) prompt, and removes any block rules Windows added for it earlier. The LAN section shows the firewall state and an **Allow in firewall** button while it is still closed. The rule covers Private and Domain networks only. If Windows treats your network as Public, the section warns that other devices can't connect; set it to Private in Windows Settings > Network & internet if it is your home network. The firewall can only be changed from the PC running MooshieUI. ### Access from outside your home network **Allow access from outside your home network** (off by default, admin only) asks your router (UPnP) to forward the server's port to this PC and shows the public address with a **Copy** button. The port closes again when you turn the option off or close MooshieUI, and the router lease expires within an hour if the app crashes. Anyone on the internet can then reach the sign-in page, so give every account a strong password; without HTTPS, passwords are sent unencrypted. If it does not work, the section says why: no router answered (turn on UPnP in the router's settings, then switch the option off and on again), the router refused, another device already uses the port, or the router has no public address of its own because your provider shares one or there is a second router. Admin commands that read or write files at a path sent by the client (saving files, uploading or importing from a folder, changing the gallery folder) only run from the PC running MooshieUI, so a stolen admin password cannot be used to read or write arbitrary files on it. ### HTTPS The web server can serve HTTPS itself. Set `MOOSHIEUI_TLS_CERT_PATH` and `MOOSHIEUI_TLS_KEY_PATH` to a PEM certificate (full chain) and its private key before starting the server; both are needed, and with only one set the server logs a warning and stays on HTTP. In Docker, mount the files into the container and add both variables to the service's `environment:` list in `docker-compose.yml`; the supplied compose file does not pass them through from `.env`. Browsers only allow some features, such as copying to the clipboard, on HTTPS or `localhost`, so this is worth setting up for regular LAN use. A reverse proxy or tunnel that terminates HTTPS in front of MooshieUI works too. ## Roles and permissions Four roles control what each user can do: | Role | Capabilities | |------|--------------| | **Admin** | Full control. Opening the app on the server's own computer at `localhost` or an IP address is admin without signing in, unless that is turned off (see [Authentication](#authentication)); a LAN account can also be promoted. Admins use the shared root gallery. | | **Moderator** | Shared settings, model files and local LLM models, except settings that decide what the host runs, which folders it uses or how the server is exposed (generation mode, LAN access, paths). Installs only the node packs MooshieUI offers. Moving the installation, changing the gallery folder and saving to arbitrary paths are admin-only. | | **User** | Generate and use their own gallery. | | **Anonymous** | Unauthenticated remote visitor; must sign in to use protected commands and gallery resources. | Other multi-user behavior: - Per-user gallery isolation. Each user and moderator account gets its own gallery folder; only admins see the shared root gallery. - In v2.3.8 and later, generated images, videos and exports are served only to the account that made them, and each account keeps its own browser-side preferences. API keys and other secrets are sent only to admins. - To reach the desktop gallery from a phone, promote that login: open the account's gear menu in Settings > App Mode and press **Make Admin** (**Revoke Admin** undoes it). The user refreshes the page afterwards. Images already generated under the account stay in its own folder. An admin cannot change its own role. - Regular users and moderators each manage their own encrypted NovelAI key in Settings > NovelAI. Admins use the instance owner's key. See [[NovelAI Backend]] for key storage and account promotion behavior. - Per-user storage limit (default 1 GB). - User/moderator gallery images and videos expire after 7 days by default; an admin can disable this with **Never auto-delete gallery images** in Settings > Gallery. The shared root gallery is exempt from automatic expiry. - Non-admin users can submit model-download requests for admin/moderator approval (see [[Models and the Model Hub]]). ## Authentication - Bearer-token auth for API requests. - Passwords hashed with Argon2id, with an upgrade path from legacy SHA-256 hashes. - Account lockout after 15 failed logins (15-minute lockout). In v2.3.8 and later, one address is also refused for 15 minutes after 10 failed logins, so a single client cannot lock someone else's account. - Changing a password signs out that account's other sessions. - New usernames use letters, numbers, `_` and `-`, up to 32 characters. - Sessions last 7 days. - Bootstrap the first admin with `MOOSHIEUI_ADMIN_USER` / `MOOSHIEUI_ADMIN_PASS` before the first server launch. Empty or short passwords and `changeme` are not accepted. Existing accounts keep their stored password when these environment variables change; there is no public self-registration. Admin without a token needs all of these: the connection comes from the same computer, the address is `localhost`, a `*.localhost` name or an IP address, the request comes from MooshieUI's own page, and no proxy relayed it. A website you visit cannot use your browser to send commands, and opening the server by machine name or through a tunnel or reverse proxy means signing in like any LAN user. A request carrying `Forwarded`, `X-Forwarded-For`, `X-Forwarded-Host`, `X-Real-IP`, `CF-Connecting-IP` or `True-Client-IP` counts as relayed. Browsers never send these, but most proxies and tunnels do, including cloudflared. A proxy that rewrites the host name to `127.0.0.1` and adds none of them, as a bare nginx `proxy_pass` does, still looks local. For that setup, add `proxy_set_header X-Forwarded-For $remote_addr;` or `proxy_set_header Host $host;` to the proxy, or turn off automatic sign-in as described below. Forwarded headers never grant a role. In v2.3.8 and later, **Sign in automatically on this computer** in Settings > App Mode turns off admin without a token entirely, so everyone signs in with an account, including you. It applies immediately. On the headless server, `MOOSHIEUI_TRUST_LOCALHOST=false` does the same and overrides the setting; the supplied Compose file passes it through from `.env`. Automatic sign-in stays on until an admin account exists, so turning it off cannot lock you out. Personal NovelAI credentials are encrypted in the data directory. Preserve the generated `secrets.key`, or supply a persistent `MOOSHIEUI_SECRET_KEY` (base64-encoded 32 bytes) to the server process. In Docker, setting an extra value in `.env` alone does not pass it into the container: add it to the service's `environment` or your deployment's secret configuration. See [[NovelAI Backend]]. ## Auto-update - **Desktop** - the updater checks GitHub releases, shows a dismissable banner, downloads with a progress bar, and offers "Restart Now." - **Browser/LAN** - the client polls the server for a newer build; admins and moderators see a banner when a server update is available. --- # Settings and Accessibility ## Persistence Settings are saved to disk automatically and restored on next launch: generation mode, prompts, model selections, sampler/scheduler/steps/CFG/seed/dimensions, and all upscale settings. Collapsed/expanded state of the left, right, and bottom panels persists too, so your layout is restored the way you left it. In browser mode, settings also sync per user. In v2.3.22 and later, the desktop app and browser mode on the same machine share one copy of your saved data: settings, saved characters, prompt presets, artist styles and favourites, LoRA presets, prompt history, notes, and gallery boards, favourites and ratings. Something saved in one mode shows up in the other, even with both open. Data you already had in both modes was merged once on first start after updating. Window layout, caches and generation tabs stay separate. While the app starts, an "Initializing..." overlay covers the content area until your saved settings have loaded and ComfyUI is reachable. This keeps a half-loaded session from saving over your settings. The overlay clears as soon as ComfyUI connects, and right away if auto-start is off or startup fails, so the status banner and its start button stay usable. ## Finding a setting Settings is split into categories, each on its own page, picked from a sidebar on the left: App Mode, Connection, Appearance, Performance, Quality Tags, GPU Workers, Models, Model Requests, Paths, Notifications, Gallery, Autocomplete, Interrogator, Prompt Assistant, AI assistants (MCP), CivitAI, NovelAI, Cloud voice and video, Queue, Account, Help & Updates, and Developer. Available categories depend on your role and deployment. - **Search settings** - the search box above the sidebar narrows it to the categories whose name or contents match. If nothing matches, the page says "No settings match your search." - The category you were on is remembered, so reopening Settings returns you to it. - On narrow screens the sidebar becomes a row of chips across the top. ## Appearance and i18n - **Languages** - 12 languages (English, German, Spanish, French, Italian, Japanese, Korean, Polish, Portuguese, Russian, Chinese Simplified, Chinese Traditional). Switch instantly in Settings -> Appearance with no restart. All keys exist in every locale; missing keys fall back to English. - **Theme** - **Dark** or **Light**, with a **Palette** of built-in colour schemes (Mooshie, Nord and others). - **Custom themes** - **Create theme** opens an editor for your own colours in dark and light mode, with an optional **Background image**, **Background fade** and **Logo image**. While a custom theme is active the built-in palette is ignored. **Export themes** and **Import themes** move them between installs. - **Hide MooshieUI branding** - a custom theme option that hides the MooshieUI branding, including the support card in Help & Updates. - **Font Scale** - scales the interface text from 0.75x to 1.5x. - **Layout** - **Switch to mobile layout** or **Switch to desktop layout** picks between the touch layout and the full desktop interface on this device. - **Style presets** - optional Fooocus-style presets can be enabled to show in the prompt panel (off by default). - **Experimental: Image to 3D** - shows the [[Image to 3D]] page and the gallery's **3D** button. Off by default, saved per device. ## Autocomplete settings - Choose tag sources (Danbooru, Anima, and custom). - Add a custom tag source by URL or file (JSON or CSV). - Set maximum suggestions (1 to 50). - Enable the clickable overlay to edit tag weights inline. See [[Prompting Guide]]. - **Tag spell check** - underline tags that aren't known Danbooru tags and offer "did you mean" corrections on right-click. Toggle on or off. - **LoRA keywords first** - suggest the trigger words of switched-on LoRAs at the top of the list. On by default. ## Accessibility - **Vision simulator** - apply a color-vision filter over the whole UI (none, protanopia, deuteranopia, tritanopia). - **Dyslexic-Friendly Font** - uses the OpenDyslexic font throughout the interface. - **Help bubbles** - toggle info-tip help bubbles on or off. Both settings persist and sync to the server. ## Connection - Auto-connect to ComfyUI on startup. - Status indicator (green/red dot) with the ComfyUI version number. - Switch between local and remote ComfyUI in Settings -> Connection. See [[Installation]] for remote setup. - A GPU status panel shows VRAM used/total and the ComfyUI process state, polled live. - Managed local ComfyUI prefers port 18288 for new installs, retains saved settings, and selects another free port when needed. Restart and shutdown target only MooshieUI-owned processes. Choose Remote to use another running ComfyUI installation. - **Free VRAM when idle** - off by default. When on, pick **Unload after** (5, 10, 15, 30 or 60 min). After that long with no generations, the managed ComfyUI unloads its models and gives back VRAM and RAM. ComfyUI keeps running, and the next generation reloads the model (a few seconds, longer for large models). A remote ComfyUI is never unloaded. - **Eagle export** - sends images to Eagle on this computer. See [[Gallery and Metadata#eagle-export]]. While you are not using the app, it also rests on its own: after 2 minutes with no mouse or keyboard input, or while the window is hidden, UI animations pause until your next input. On Windows the WebView is also hidden while the window is minimised and set to use less memory while the app rests. ## Performance Settings -> Performance controls how ComfyUI uses your GPU. - **VRAM Mode** - High / Normal / Low / None. Auto-detected during setup; lower it if you run out of VRAM, raise it if generation is slow and you have headroom. High is meant for 24 GB and up, and is dropped when the largest installed model would leave less than 6 GB free. - **Keep ComfyUI running after app closes** - leaves the ComfyUI process alive in the background. Off by default, since it keeps using VRAM while the app is closed. With it off, a ComfyUI left running by a crashed or killed MooshieUI is stopped on the next launch instead of reused, and on Windows the managed ComfyUI closes with the app however it exits. - **Attention Backend** - swaps ComfyUI's attention implementation for a faster one: **Default (PyTorch SDPA)**, **SageAttention v1/v2**, or **FlashAttention v1/v2**. These are NVIDIA-only accelerators, so each option is greyed out when your hardware cannot use it, with the reason shown inline: - "Requires an NVIDIA GPU" when no supported GPU is detected. - "Requires compute capability N+ (detected M)" when the GPU is too old for that backend. - "Requires the CUDA toolkit (nvcc) to build from source" for the backends that compile on install when the toolkit is missing: FlashAttention v1/v2 on every platform, plus SageAttention v2 on Linux. On Windows, SageAttention v2 installs a prebuilt wheel matched to the venv's PyTorch, CUDA, and Python versions, so it does not need the toolkit. Picking a supported backend installs the needed packages (on Windows the SageAttention options also pull in `triton-windows`), verifies they import, and asks you to restart ComfyUI for the change to take effect. If an install fails it is rolled back and your previous backend is kept, so a bad install never leaves ComfyUI unable to start. A status panel below the selector shows what is currently installed in the active venv and your detected compute capability. ## Gallery and account settings - **Manual save mode** holds completed images and videos in the preview until you choose **Save to Gallery** or **Discard**. - **Never auto-delete gallery images** disables the default seven-day cleanup of user/moderator galleries, including videos. Admin/root-gallery files are exempt from that cleanup already. - **Flag NSFW images by prompt keywords** sets the keywords that mark images as NSFW for the gallery's NSFW filter and blur. **Reset to defaults** restores the list. See [[Gallery and Metadata]]. - **Linked folders** (desktop) shows images from other folders in the gallery without copying them. See [[Gallery and Metadata]]. - **Import Images from Directory** copies images from a SwarmUI output, ComfyUI output or any other image folder into your gallery, keeping their metadata. - **Interrogator** selects a built-in WD v3 tagger or registers a custom folder containing `model.onnx` and `selected_tags.csv`. **Detect artists (Kaloscope 3.0)** and **Detect saved characters** are both on by default for new installs (existing settings are kept); see [[Prompting Guide]]. - **AI assistants (MCP)** turns on the local MCP server that lets AI assistants generate and search your gallery; see [[AI Assistants and MCP]]. - **NovelAI** manages your saved API key and Anlas/Opus readout. Users and moderators use their own encrypted key; admins use the owner's key. See [[NovelAI Backend]]. - **Cloud voice and video** stores ElevenLabs and fal.ai API keys for the [[Anime Scenes]] page, one write-only field per provider. Builds up to v2.3.41 also show a Segmind field; nothing uses that key, and later builds only show it so a saved key can be cleared. A saved key is never shown again, and **Clear** removes it. On a server each account has its own encrypted keys; the owner's keys are never sent to any client. ### API keys from environment variables The instance owner can keep API keys out of MooshieUI's config. Under each API key field (cloud voice and video, NovelAI, CivitAI and the prompt assistant's external LLM), **Use an environment variable instead** switches the field to take a variable name such as `FAL_KEY`. The key is then read from MooshieUI's environment every time it is used and never written to disk. A status line reads "Reading the key from FAL_KEY." or warns that the variable is not set. Only the owner can name a variable; other accounts keep their own saved keys. ### Help & Updates The update check retries a couple of times before giving up. If GitHub still cannot be reached, Help & Updates says so and offers **Open releases page** next to **Try again**, so you can download the latest version by hand. When MooshieUI on Linux was installed from the apt, dnf or zypper repo (or the AUR package), the update banner and Help & Updates show the package manager's update command instead of a download button. A small **Support MooshieUI** card at the bottom of Help & Updates links to **Support on Ko-fi** and **Sponsor on GitHub**. It follows the active theme, and **Hide MooshieUI branding** in Appearance hides it. The About dialog has the same two buttons. ## Quality Tags - **Auto-apply quality tags** - prepends the recommended quality tags for supported models (Anima, Illustrious/NoobAI, Nanosaur). If results look blurry or low quality, check that this is still on. - **Customize quality tags** - overrides the default tags. The defaults work well for most models; reset them if results get worse. - **Advanced Mode** - stops MooshieUI from applying the recommended steps, CFG, sampler, scheduler and dimensions when you switch checkpoints, so your current settings carry over to every model. Model family detection still works. Off by default, and it asks for confirmation before turning on. ## GPU Workers Shows each detected GPU with its VRAM, utilization, temperature, power draw and the worker assigned to it, refreshed every 5 seconds. Under **GPU worker config**, **Auto-detect** proposes one worker per GPU, and each worker has a GPU, port, label, VRAM mode and an on/off switch. With no workers configured, MooshieUI runs in single-worker mode. ## Paths (admin) - **Data Location** and **Move Installation to New Location** - moves the runtime and its data (about 5 to 10 GB) to another folder. ComfyUI is stopped while it copies, and the app needs a restart afterwards. - **Rerun Setup Wizard** - reopens first-run setup to pick a different GPU or reinstall ComfyUI and PyTorch. - **ComfyUI Installation** and **Python Virtual Environment** - the folders the managed ComfyUI runs from. - **Shared Model Directories** - point MooshieUI at a models folder from another tool (ComfyUI, A1111, Forge). Subfolders such as `checkpoints/`, `loras/` and `vae/` are picked up automatically, and **Auto-Detect** scans for folders from other AI tools. - **Extra CLI Arguments** - extra arguments passed to ComfyUI when it launches, for example `--force-channels-last`. ## Queue Lists the running and pending generations and refreshes every 3 seconds. Admins also get **Clear Queue**, which interrupts every active and queued generation for everyone after a confirmation. To reorder or cancel your own jobs, use the queue panel described in [[Generation Basics#queue-panel|Generation Basics]]. ## Notifications Settings -> Notifications controls OS-level completion alerts. - **Desktop notifications** - when enabled, MooshieUI sends a system notification when an image batch finishes, a video finishes, or a generation error occurs. On desktop (Tauri) the native OS notification API is used; in browser mode the Web Notifications API is used and the browser asks for permission the first time you enable this. If permission is denied, a message reads "Permission denied. Enable notifications for MooshieUI in your system settings." - **Only when window is unfocused** - when checked, notifications are suppressed while the app window is in the foreground and only fire when you have switched to another app. - **Play a sound when an image is ready** - plays a short chime when an image finishes. A batch rings once. ## Diagnostics - **Terminal log** (desktop) - a collapsible, resizable panel streaming live ComfyUI and app output, with separate "comfyui" and "app" tabs. - **Notification bell** - keeps a history of success/warning/error/info messages with timestamps. - **Log export** - logs are captured in a ring buffer and can be exported for bug reports. - **Report a problem** - a bug icon in the left sidebar (below the connection indicator) opens a one-click report flow any time. Your note, app version, OS, and recent logs are bundled and filed as a GitHub issue for you, no GitHub account needed. Nothing is sent unless you choose to submit. --- # AI Assistants and MCP MooshieUI can run a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so AI assistants such as Claude Code, Claude Desktop, Cursor or LM Studio can generate images and music, check the queue and search your gallery. ## Turning it on The server is off by default. Open **Settings > AI assistants (MCP)** and turn on **Enable MCP server**. The panel shows the address it runs at, the **Port** (default `3210`), and the **Token** assistants need. **New token** replaces it; apps using the old token stop working until you give them the new one. The server only listens on `127.0.0.1`, even with LAN mode on, so only apps on the same computer can connect unless you add a public address (see below). Every request needs the token, and requests from web pages are refused. Anyone with the token can generate images and read your gallery, so keep it private. ## Connecting an assistant The panel has ready-to-copy setup for **Claude Code** (a `claude mcp add` command) and **Other apps (JSON config)**. Claude Desktop only starts local servers as commands, so it connects through `mcp-remote` (needs Node.js). The repository's `docs/MCP.md` has the full examples. Apps on this computer that take only a URL can use the **URL only (apps on this computer)** link, which carries the token in its path. ## Claude and other cloud apps Claude's custom connectors (Claude Desktop, claude.ai, mobile) and ChatGPT connect from their own servers, not from your computer, so they cannot reach `127.0.0.1`. They need a public https address, set up under **Claude and other cloud apps** in the same panel: - **Cloudflare tunnel** gives the server a temporary public address through Cloudflare, with no account needed. MooshieUI downloads a pinned, checksum-verified `cloudflared` the first time. The status changes to running only once the tunnel has actually connected, not when the process starts. If the tunnel fails to start, the panel explains the most common cause: port 7844 blocked by a VPN or firewall. The address changes every time MooshieUI starts, so update the connector after a restart. The tunnel stops when MooshieUI closes or the MCP server is turned off. - **Your own address** is for a tunnel or reverse proxy you run yourself (Cloudflare named tunnel, Tailscale Funnel, ngrok). Point it at the local address shown and enter its https address for a URL that never changes. Copy the **Connector URL** and, in Claude, paste it under **Settings > Connectors > Add custom connector**. The token is part of this URL, so anyone who has it can use MooshieUI from anywhere. Keep it private and press **New token** if it leaks. Requests that arrive through a tunnel return a job id after about 75 seconds instead of waiting for the image, and the assistant checks on it with `get_job`. ## Generating images Assistants never pick sampler, encoder or family settings on their own. Each time you run a plain txt2img generation with a model, MooshieUI saves those settings (without the prompt or input images) as that model's setup, and assistants start from it. The panel shows how many models are ready. A model becomes usable once you have generated one txt2img image with it. NovelAI, img2img, inpainting, Image Edit and video runs do not create setups. An assistant can change the prompt, negative prompt, model, size, steps, CFG, seed, batch size (1 to 8), sampler, scheduler and LoRAs. Images are saved to your gallery with normal metadata and show up in an open window right away. **NovelAI over MCP** is available inside the Opus free window only (at most 1 MP, 28 steps, one image per request), so it never spends Anlas. NovelAI models appear in the model list when a key is saved. **Prompt ingredients by name** - prompts sent to `generate_image` can reference the owner's saved resources by name: `__wildcard_name__` picks a line from a wildcard file, and saved characters, artist styles and prompt chunks can be added by name (use `list_library` to see what is available). ## Editing and upscaling images Two additional tools let assistants work on images already in the gallery: - `edit_image` - edits a gallery image with an instruction using an Image Edit model (Qwen Image Edit, Flux.1 Kontext, FLUX 3 Klein, Anima ReStyler). Pass the gallery image ID and a text instruction; the result is saved to the gallery like any other generation. - `upscale_image` - upscales and refines a gallery image the way MooshieUI's Refine button does, using the setup of the model that made it. Both tools return a signed download link for the full-size result. ## Comics over MCP Assistants can build a full comic page with `create_comic`. Provide the layout, panel prompts, cast appearance tags, the page setting and optional dialogue per panel. Each panel is generated separately and assembled into the page; panel images and the final page are saved to the gallery. `redo_comic_panels` remakes specific panels without regenerating the whole page. ## Gallery boards and Eagle `list_boards` returns all gallery boards with image counts. `search_gallery` can filter by board, favourites or rating, and every result includes a signed download link. For Eagle users, `search_eagle`, `get_eagle_image` and `send_to_eagle` let assistants search the Eagle library, inspect items and add new gallery images to it. ## Generating music The `generate_music` tool makes a YuE2 song from a style, optional lyrics (leave them out for an instrumental) and a duration of up to 6 minutes, using the same backend as [[Music Generation]]. It needs no setup. Finished songs are saved as FLAC, with the planned ABC score, in the `music` folder in the app data folder. They do not appear in the Music page library. ## Tools | Tool | What it does | |------|--------------| | `get_status` | ComfyUI status and GPUs, queue length, recent image and music jobs, and the saved setups | | `list_models` | Installed checkpoints, diffusion models, LoRAs, or YuE2 music checkpoints | | `generate_image` | txt2img from a model's setup, with optional overrides. Supports NovelAI (Opus free window), wildcards, saved characters, styles and chunks by name | | `generate_music` | A YuE2 song from a style, lyrics and duration | | `create_comic` | Lay out a comic page, generate every panel and assemble it | | `redo_comic_panels` | Remake specific panels of a finished comic page | | `get_job` | Status and results of an image, comic or music job | | `cancel_generation` | Cancels assistant jobs only, never generations started in the window | | `search_gallery` | Searches prompts and models, or lists the newest images; filter by board, favourites or rating | | `get_image` | A preview of a gallery image and its generation settings, with a signed download link | | `list_library` | The owner's saved characters, artist styles, prompt chunks and wildcard files | | `get_character` | A saved character's full prompt, UC and memory files | | `edit_image` | Edit a gallery image with an instruction, using an Image Edit model | | `upscale_image` | Upscale and refine a gallery image | | `list_boards` | Gallery boards with image counts, plus favourited and rated counts | | `search_eagle` | Search the Eagle library (Eagle must be open); list folders with list_folders | | `get_eagle_image` | Preview an Eagle item with tags, notes and a download link | | `send_to_eagle` | Add gallery images to Eagle with prompt tags and annotation | ## See also - [[Settings and Accessibility]] - [[Server, LAN and Multi-User]] - [[Music Generation]] --- # FAQ ## Where do I put wildcards and what is the prompt syntax? For inline choices, use `{red|blue|green}`. Multiple choices, weights and nested blocks are supported, and the generation seed determines the roll. For reusable lists, use **Prompt Chunks** (also called Prompt Presets). Classic `__filename__` text-file wildcards are not the app's wildcard mechanism. 1. Open **Chunks** from the prompt toolbar. Create a chunk and put each choice on its own line (commas within a line stay grouped). 2. Either activate the preset with a **Wildcard (random)** or **Wildcard (in order)** mode, or drop the inline token `@[Chunk Name]` (or `@preset:`) anywhere in your prompt to roll it at that exact spot. Full details: [[Prompting Guide]]. ## How do I recover the prompt/settings from an image I made earlier? Drag or paste the PNG back into MooshieUI. It reads the embedded metadata and fills in your settings. If the image has no embedded metadata, use image interrogation to reverse-engineer tags. See [[Gallery and Metadata]] and [[Prompting Guide]]. ## How do I queue many variations at once? Use a **Wildcard (in order)** preset (the Generate button can queue the whole ordered run), or use the [[Compare Grid]] for explicit per-cell parameter sweeps. ## Can I run this on my phone? Yes. Run MooshieUI in server mode and open it in your phone's browser; there is a dedicated mobile layout. See [[Server, LAN and Multi-User]]. ## ComfyUI is on a cloud GPU. Can I still use the desktop app? Yes, as a thin client against a remote ComfyUI. See the remote/cloud section of [[Installation]]. ## A model is not detected correctly. Why? Detection combines hashes, sidecar/model metadata, safetensors or GGUF structure, and filename hints. Many renamed models still resolve correctly. Check the supported families, companion encoders/VAEs and the family override in the model picker. See [[Models and the Model Hub]]. ## Generation fails with a quantization format error. What now? Check both the ComfyUI version and the loader. Update ComfyUI to the app's pinned version. Supported W8A8/ConvRot models also need the optional **INT8-Fast loader** enabled and installed; updating core ComfyUI alone does not install it. GGUF models use their own loader and cannot use the INT8-Fast toggle. If the format or hardware is unsupported, use a supported quantization or full-precision model. See [[Models and the Model Hub]]. ## Generation says a setting is not in the allowed list. Is my model missing? Read the rejected setting in the error detail. An invalid sampler or quantization option is a settings validation error; a missing model message names a model-file input. If an older app rejects the INT8-Fast loader's `lora_mode` value `default`, update to v2.3.3 or later, which uses the loader's supported default. See [[Models and the Model Hub]]. ## Can I use NovelAI on a shared server? Yes. Regular users and moderators add their own key in **Settings > NovelAI**. Their requests never fall back to the host's key. Admin accounts use the owner's key, so promotion changes both gallery access and which NovelAI account is billed. See [[NovelAI Backend]]. ## Can I pause a generation and change its ending? Yes, for ComfyUI **Text to Image**. Set **Pause at step**, inspect the preview, adjust supported controls or paint a masked correction, then continue. Pauses are session state and do not apply to NovelAI. See [[Generation Basics]]. ## Why did an image or video disappear from the gallery? Check **Manual save mode** and the gallery retention setting. Manual mode requires **Save to Gallery**; otherwise the result is only held for review. User/moderator gallery items expire after seven days by default unless **Never auto-delete gallery images** is enabled; admin/root-gallery files are exempt. See [[Gallery and Metadata]]. ## How do I report a bug? Click the bug icon in the left sidebar (just below the connection indicator) to open **Report a problem** any time. Add a note and submit, and your app version, OS, and recent logs are bundled and filed as a GitHub issue for you, no GitHub account required. Nothing is sent unless you submit. If a problem is upscale or generation related, running the affected action first so it's captured in the logs helps a lot. See the diagnostics notes in [[Settings and Accessibility]]. ## Where are the contributor/build docs? In the repo: [README.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/README.md), [push-instructions.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/push-instructions.md), and [CHANGELOG.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/CHANGELOG.md). --- # Contributing MooshieUI welcomes contributions. The repository's [CONTRIBUTING.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/.github/CONTRIBUTING.md) is the authoritative guide; this page summarizes it. ## Setup Install Node.js 22.12+ or 24+, stable Rust and your platform's Tauri v2 prerequisites. Run `npm install`, then `npm run tauri dev` for full desktop development or `npm run dev` for the frontend alone. ## Before opening a PR Run `npm run check`. It builds the frontend, checks i18n parity, checks that every full-screen overlay is portaled, and runs svelte-check. Do not add new type errors or a11y warnings in the files you change. Rust changes need both the default desktop build and the headless server check (`--no-default-features --features server`), plus relevant tests, formatting and linting. A Tauri reference in shared code must be gated for the desktop feature. Documentation-only changes need behavior and link checks, not a native build. ## The three core guidelines - i18n: every user-facing string uses `locale.t('key')`, and every key plus its `{placeholder}` names exist in all files under `src/lib/locales/`. CI blocks on parity gaps. - a11y: interactive elements are keyboard- and screen-reader-accessible. CI posts a non-blocking a11y summary for the files you change. - Scope: changes stay within the project charter. See [[Project Scope]]. Full detail, including the "what CI checks and how to fix each" table, is in [CONTRIBUTING.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/.github/CONTRIBUTING.md) in the repository. --- # Project Scope This charter defines what MooshieUI is and is not. Use it to judge whether a feature or change belongs in the project before writing code. When in doubt, open an issue with the feature template and ask. ## What MooshieUI is - A desktop (Tauri) and browser front-end for image, video, music and experimental image-to-3D generation through local or remote ComfyUI, with optional NovelAI image generation, and optional cloud voice and video generation (for example ElevenLabs and Seedance), each using the user's own API key and billed by that provider. - A polished UI over generation workflows: prompt building, generation settings, gallery management, model hub, and related in-app tooling. - Video generation on the same footing as images: shot planning through the timeline director, playback, frame interpolation, and clip export. The timeline is a shot list that feeds a ComfyUI graph, not a node editor. - Music composition through ComfyUI, with style and lyric writing, a local song library, playlists, playback, manual lyric timing and audio export. - Self-hosting with LAN accounts, roles, per-user galleries and configured GPU workers. Regular users and moderators manage their own NovelAI and cloud provider credentials. - Windows, Linux and Apple Silicon macOS releases (Mac builds are user-tested), with native desktop and embedded browser-server modes sharing one codebase. See [Mac support status](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/MACOS.md). - An opt-in, local, token-protected MCP server so AI assistants can drive the owner's existing generation setups, queue and gallery. See [[AI Assistants and MCP]]. - Localized (i18n across all supported locales) and accessible (a11y). ## What MooshieUI is not - Not a ComfyUI replacement or a general node-graph editor. It orchestrates ComfyUI; it does not reimplement it. - Not an operated hosted SaaS service. Users run their own desktop or server; the existing multi-user self-hosting features are part of that scope. - Not a model training or dataset-management tool. - Not a general-purpose image editor beyond the specific in-app editing features already shipped. - Not a video editor or non-linear editing suite. Clips are planned before generation and exported afterwards; MooshieUI does not cut, composite, or grade footage. Joining a generated voice track to a generated clip at generation time is muxing, not editing. - Never a way around a provider's safety filters. A provider's moderation block is shown to the user as final, not retried with a reworded prompt. - Not a plugin marketplace or arbitrary third-party extension host. ## How scope is enforced - Features are discussed in an issue (feature template) before implementation. - Every PR states how it fits this charter (PR template). - The maintainer judges scope against this document. Out-of-scope changes are declined regardless of code quality. The repository [SCOPE.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/SCOPE.md) is the authoritative charter. --- # MooshieUI MooshieUI is a beginner-friendly interface for image, video, music and 3D generation through [ComfyUI](https://github.com/comfyanonymous/ComfyUI), with optional image generation through the **NovelAI API** using your own key. It runs in two modes: - **Desktop app** via Tauri (Windows, Linux and [Apple Silicon macOS](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/MACOS.md); Mac builds are user-tested) - **Browser/server mode** via the built-in web server (LAN/Docker friendly, mobile UI) Built with **Svelte 5** + **Rust**, it hides ComfyUI's node-graph complexity behind a clean, guided workflow so you can generate without hand-editing graphs. ![License](https://img.shields.io/github/license/Mooshieblob1/MooshieUI?v=2) [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/Mooshieblob1) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-ff5e5b?logo=kofi&logoColor=white)](https://ko-fi.com/mooshieui)

Logo

Sponsor MooshieUI on GitHub Sponsors

Support MooshieUI on Ko-fi

MooshieUI is free and open source. If it saves you time or sparks joy, a sponsorship or a Ko-fi tip keeps the updates coming. No pressure, just gratitude. 🙏 (where does the money go?)

![MooshieUI Screenshot](https://raw.githubusercontent.com/Mooshieblob1/MooshieUI/main/docs/screenshot.avif) --- ## 📚 Documentation Full guides live in the **[MooshieUI Wiki](https://github.com/Mooshieblob1/MooshieUI/wiki)**: | Guide | Covers | |-------|--------| | [Installation](https://github.com/Mooshieblob1/MooshieUI/wiki/Installation) | Desktop, Docker, remote/cloud ComfyUI, Apple Silicon macOS | | [Generation Basics](https://github.com/Mooshieblob1/MooshieUI/wiki/Generation-Basics) | Image modes, tabs and Profiles, pause/continue, queue, dimensions, guidance and the Characters tab | | [NovelAI Backend](https://github.com/Mooshieblob1/MooshieUI/wiki/NovelAI-Backend) | Personal API keys, characters, references, costs, face detailing and Director Tools | | [Video Generation](https://github.com/Mooshieblob1/MooshieUI/wiki/Video-Generation) | MiniMax H3, model stacks, timeline, interpolation, playback and export | | [Music Generation](https://github.com/Mooshieblob1/MooshieUI/wiki/Music-Generation) | YuE2 songs, lyric writing, playlists, shared playback and manual lyric timing | | [Anime Scenes](https://github.com/Mooshieblob1/MooshieUI/wiki/Anime-Scenes) | Voiced, lip-synced character clips through ElevenLabs and fal.ai with your own keys | | [Image to 3D](https://github.com/Mooshieblob1/MooshieUI/wiki/Image-to-3D) | Experimental textured meshes (Pixal3D) and Gaussian splats (Idol) from one image | | [Image Edit Mode](https://github.com/Mooshieblob1/MooshieUI/wiki/Image-Edit-Mode) | Qwen Image Edit, Flux Kontext, Flux.2 Klein, FLUX 3 Klein, Krea 2 edit LoRAs, MiniMax-H3-Image and Anima ReStyler | | [Prompting Guide](https://github.com/Mooshieblob1/MooshieUI/wiki/Prompting-Guide) | Prompt Chunks, random syntax, Artist Styles, Style Creator and interrogation | | [Prompt Assistant](https://github.com/Mooshieblob1/MooshieUI/wiki/Prompt-Assistant) | Local or external LLM-assisted prompt building | | [Models & the Model Hub](https://github.com/Mooshieblob1/MooshieUI/wiki/Models-and-the-Model-Hub) | Supported architectures, auto-detection, downloads | | [Upscaling & Face Fix](https://github.com/Mooshieblob1/MooshieUI/wiki/Upscaling-and-Face-Fix) | Tiled diffusion, guidance nodes, face fix | | [ControlNet & Style Transfer](https://github.com/Mooshieblob1/MooshieUI/wiki/ControlNet-and-Style-Transfer) | ControlNet and reference/style transfer | | [Inpainting & the Canvas Editor](https://github.com/Mooshieblob1/MooshieUI/wiki/Inpainting-and-the-Canvas-Editor) | Mask painting and selective edits | | [Compare Grid](https://github.com/Mooshieblob1/MooshieUI/wiki/Compare-Grid) | XYZ parameter sweeps | | [Image Comparison](https://github.com/Mooshieblob1/MooshieUI/wiki/Image-Comparison) | Slider, fade, difference and side-by-side comparison | | [Gallery & Metadata](https://github.com/Mooshieblob1/MooshieUI/wiki/Gallery-and-Metadata) | Persistent gallery, search, ratings, boards, linked folders, metadata import/remix | | [Server, LAN & Multi-User](https://github.com/Mooshieblob1/MooshieUI/wiki/Server,-LAN-and-Multi-User) | Self-hosting, roles, auth, mobile | | [Settings & Accessibility](https://github.com/Mooshieblob1/MooshieUI/wiki/Settings-and-Accessibility) | Persistence, themes, i18n, accessibility | | [AI Assistants & MCP](https://github.com/Mooshieblob1/MooshieUI/wiki/AI-Assistants-and-MCP) | Let Claude, Cursor and other assistants generate through the opt-in MCP server | | [FAQ](https://github.com/Mooshieblob1/MooshieUI/wiki/FAQ) | Common questions | | [Contributing](https://github.com/Mooshieblob1/MooshieUI/wiki/Contributing) | Setup, checks and the PR workflow | | [Project Scope](https://github.com/Mooshieblob1/MooshieUI/wiki/Project-Scope) | What MooshieUI is and is not | Technical references and project planning documents are indexed in [docs/README.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/README.md). --- ## ✨ Highlights > New features land in most releases. See [the release notes](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/RELEASE_NOTES.md) for what changed in the latest version. - **Image generation and editing** - text to image, image to image, inpainting with a built-in canvas/mask editor, and Image Edit for Qwen Image Edit/Edit Plus, Flux.1 Kontext, Flux.2 Klein, FLUX 3 Klein, Krea 2 (Identity Edit, General Edit and Style Reference LoRAs), MiniMax-H3-Image (up to 16 references) and Anima ReStyler. Work in several generation tabs at once and save a tab's settings as a Profile. - **NovelAI backend** - V5 Full/Curated, V4.5 Full and V4 Full, with character prompts and positioning, supported reference modes, Anlas estimates, Enhance/Upscale/Variations, Director Tools and a dedicated face detailer. Hosted users and moderators can save their own encrypted API key. - **Video generation** - MiniMax H3 text-to-video, first/last frames and reference images; preset or custom model stacks, a shot timeline, [Standard and Larryvrh/LightX2V/PDD Turbo methods](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/VIDEO.md), retained drafts with experimental 2× refinement, TeaCache, animated live previews, RIFE/GMFSS interpolation, a gallery player and MP4/animated-image export. - **Music studio** - YuE2 songs, native SheetSage2 covers and score-aware assistance through your configured Prompt Assistant. [Review and edit scores](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/MUSIC.md), preview melodies, export MIDI, generate sequential candidates, compare saved versions and export projects with original FLAC and settings. Review recognized lyrics and approximate cover timing using xAI transcription and your assistant, with playable evidence. Includes playlists, shared playback, manual lyric timing, reference-song lookup, temporary song-link imports, style analysis from selected audio sections, reusable style profiles, volume-matched A/B listening, scoped edits with before/after previews, and an arrangement-planning prototype. - **Image to 3D (experimental, off by default)** - turn one picture of a character or object into a textured mesh (`.glb`) with [Pixal3D](https://github.com/TencentARC/Pixal3D), or a 3D Gaussian splat with [Idol](https://huggingface.co/speridlabs/idol) (about 7 GB of VRAM), both on ComfyUI's own nodes. Spin it in the built-in viewer, keep it in a device-local library and export `.glb`, `.ply` or `.splat`. Start from a file, a paste or any gallery image. [Details](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/IMAGE_TO_3D.md). - **Anime Scenes (optional, cloud)** - turn a character into a short voiced, lip-synced clip with your own ElevenLabs (voice) and fal.ai Seedance 2.5 (video) keys, with optional NovelAI keyframes. Every paid step shows a cost confirmation first, and nothing in it runs on ComfyUI. - **AI assistants (MCP, off by default)** - a local, token-protected [MCP server](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/MCP.md) lets Claude Code, Claude Desktop, Cursor and similar assistants generate images and music, check the queue and search the gallery. Cloud assistants connect through an opt-in Cloudflare tunnel or your own address. - **Pause and continue** - pause ComfyUI text-to-image sampling, inspect a preview, change prompts or sampling settings, or paint a masked correction before continuing. Keep a pause to try different endings. - **Full generation controls** - searchable checkpoint/VAE/LoRA pickers with auto-download, all ComfyUI samplers and schedulers, steps/CFG/seed/batch, and smart dimension presets. - **Smart model detection** - 30+ model families, including Krea 2, FLUX 3 Klein, MOSS-Image, MiniMax-H3-Image and Kolors, identified through hashes, model metadata, tensor structure and filenames, with sampler/scheduler/CFG presets, split components, GGUF support and optional INT8-Fast loading. - **Prompt and style tools** - autocomplete, Prompt Chunks and wildcards, seeded random prompt syntax, scheduling, regional prompts, a local or external Prompt Assistant, Style Creator rounds for discovering artist combinations, and an image interrogator that returns tags, detected artists (Kaloscope) or a description in words. - **Characters** - save characters with a name, prompt, portraits and Markdown memory files, and reuse them across sessions and in NovelAI character boxes. - **Refinement and references** - MultiDiffusion/SpotDiffusion upscaling, SeedVR2 restoration, face detailing, ControlNet, IP-Adapter/Flux Redux style references, sampler guidance and the SDXL DMD2 preset. - **Compare Grid (XYZ)** - per-cell parameter sweeps stitched into a single labelled image. - **Queue and feedback** - reorder or cancel pending jobs, interrupt a run, watch previews and progress, and opt into completion notifications. - **Gallery & metadata** - Persistent image and video gallery with search, favourites, 1 to 5 star ratings, boards you can rename and delete, multi-select with bulk move, rate, favourite and delete (checkbox, Shift+click, Ctrl+click, Ctrl+A), Undo after a delete, a filter panel that folds away, board chips you can drop images onto (the busiest boards plus a searchable list once there are many), Reset filters, Undo and one-click removal for Sort by Artist and Sort by Character boards, arrow key navigation, export of a selection to a folder on desktop, a Repeats filter for images generated more than once with the same seed and settings, saved characters found in images by their prompt tags, or by a tagger scan for images with no saved prompt (filter, group or sort into boards by character), linked folders on desktop, a Refresh gallery action for externally added, restored or removed files, manual save mode, generation times and A/B comparison; import SwarmUI, A1111 and NovelAI settings, with original NovelAI PNG metadata preserved when copying. Refresh scans the current user's gallery folder and reloads embedded metadata without renaming files. An optional invisible watermark and an always-on gallery fingerprint can restore settings for an image that has lost its metadata. - **Self-hostable** - headless web server with roles, per-user galleries, auth, and a dedicated mobile layout. - **Themes** - dark and light modes, built-in palettes, and custom themes with your own background and logo that can be imported and exported. - **12 languages** - English, German, Spanish, French, Italian, Japanese, Korean, Polish, Portuguese, Russian, Simplified Chinese and Traditional Chinese, switchable without restart. Controls depend on the selected backend and model. NovelAI offers the three standard image modes; Image Edit, video, music, Image to 3D and pause/continue use ComfyUI; Anime Scenes uses cloud providers only. YuE2 requires its own checkpoint and native ComfyUI support; managed installs offer the tested runtime update. See the [Wiki](https://github.com/Mooshieblob1/MooshieUI/wiki) for each feature's requirements. --- ## 📦 Quick Start ### Desktop (Windows, Linux, Apple Silicon macOS) 1. Download a release from [Releases](https://github.com/Mooshieblob1/MooshieUI/releases): the `.exe` installer for Windows, an `.AppImage`, `.deb` or `.rpm` for Linux (or install it with `apt`, `dnf` or the AUR, see the [Linux guide](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/LINUX.md)), or the `_aarch64.dmg` for macOS 14 or later (see the [Mac guide](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/MACOS.md)). 2. Run the app. The setup wizard downloads uv, Python, ComfyUI, and PyTorch (NVIDIA, AMD, or Intel Arc GPU auto-detected; Apple Metal on Mac) and installs MooshieUI's custom nodes - no Python or pip setup required. On Windows, it also installs an app-local copy of Git when a working Git installation cannot be found. 3. Start generating; ComfyUI launches automatically. Managed ComfyUI uses port **18288** for new installations, preserves saved port settings, and chooses another free port if needed. Setup, restart, and shutdown stop only processes identified as MooshieUI's own, including verified keep-alive instances. Existing ComfyUI applications can stay running. To connect to one intentionally, choose **Remote** in the connection settings. The generation model picker uses the connected ComfyUI server's model inventory. A file downloaded locally may still be unavailable to that server; the picker and model manager show this separately. For an external server, install models on that server and refresh the model list. Startup progress appears above the page, keeping the tips readable while controls initialize. > Allow roughly 5–10 GB for the runtime, plus space for model downloads; first setup typically takes 5–15 minutes depending on your connection. GPU support varies by platform, including an allowlisted AMD Windows preview. See [Installation](https://github.com/Mooshieblob1/MooshieUI/wiki/Installation) for details. ### Generate with NovelAI Save your API key in **Settings > NovelAI**, then select a NovelAI model in the model picker. The generation page adapts to that backend and shows an estimated Anlas cost before submission. Local upscaling and face detection still need a running ComfyUI; NovelAI requests use your account's subscription and balance. See [NovelAI Backend](https://github.com/Mooshieblob1/MooshieUI/wiki/NovelAI-Backend). ### Self-host (Docker) ```bash cp .env.example .env # Edit .env: set MOOSHIEUI_ADMIN_USER and a strong MOOSHIEUI_ADMIN_PASS before first launch. docker compose up -d --build ``` Open `http://localhost:3200` (or the host port set by `MOOSHIEUI_PORT`) and sign in with the initial admin account. Empty passwords and `changeme` are not accepted for account creation. The supplied Docker stack targets NVIDIA GPUs and requires GPU support in Docker; it is separate from the desktop wizard's AMD/Intel setup. Full server/LAN/multi-user setup: [Server, LAN & Multi-User](https://github.com/Mooshieblob1/MooshieUI/wiki/Server,-LAN-and-Multi-User). ### Build from source Use Node.js 22.12+ or 24+, stable Rust, and the platform's Tauri v2 build prerequisites. See [CONTRIBUTING.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/.github/CONTRIBUTING.md) for validation and both Rust build targets. ```bash git clone https://github.com/Mooshieblob1/MooshieUI.git cd MooshieUI npm install npm run tauri dev # hot-reload dev npm run tauri build # production build ``` --- ## 🏗️ How it works 1. You adjust settings in the Svelte UI. 2. On Generate, `ipcInvoke()` sends settings to Rust through Tauri IPC on desktop or HTTP in browser mode; `ipcListen()` receives events through Tauri or SSE. 3. Rust builds an image, video, music or image-to-3D ComfyUI workflow from templates, or a NovelAI image request using the selected account's key. 4. ComfyUI workflows go to its `/prompt` API; NovelAI requests go to its image API. Optional local post-processing sends returned NovelAI images through ComfyUI. 5. ComfyUI WebSocket events and NovelAI streaming responses feed progress and previews. Images and videos use the gallery; music and 3D models each have their own device-local library. MooshieUI also ships custom ComfyUI nodes (tiled diffusion, soft/smart guidance, an SDXL↔Flux2 VAE adapter, Nanosaur DiT support, and face fix) that are auto-installed into ComfyUI. Details live in [Models & the Model Hub](https://github.com/Mooshieblob1/MooshieUI/wiki/Models-and-the-Model-Hub). The tiled diffusion node is also available as a standalone ComfyUI custom node: [ComfyUI-MooshieTiledDiffusion](https://github.com/Mooshieblob1/ComfyUI-MooshieTiledDiffusion). --- ## 🛠️ Tech Stack | Layer | Technology | |-------|------------| | Frontend | Svelte 5, TypeScript 6, Tailwind CSS 4 | | Runtime | Tauri desktop app + axum headless web server | | State | Svelte 5 runes - class-based singleton stores | | Persistence | Tauri Store (JSON), SQLite (`rusqlite`), and per-account IndexedDB for the music and 3D libraries | | Generation transport | ComfyUI REST/WebSocket and NovelAI HTTP/streaming through Rust | | Prompt Assistant | Local llama.cpp, configured external LLM endpoint, or [ChatGPT / Gemini account sign-in](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/PROMPT-ASSISTANT-SIGN-IN.md) | | Inference | ONNX Runtime (`ort`) for WD v3 image interrogation | | Autocomplete | Danbooru + Anima tag databases (~140k tags) | | i18n | 12 languages, checked key/placeholder parity, runtime switching | | Build | Vite 6 + `@sveltejs/vite-plugin-svelte` | --- ## 🔒 Security Automated **GlassWorm resistance checks** run on every push and pull request to catch supply-chain attacks that hide payloads in invisible Unicode variation selectors or tamper with git timestamps. The CI workflow (`.github/workflows/glassworm-scan.yml`) blocks merges on failure. Contributors should enable the same checks locally: ```bash bash scripts/setup-hooks.sh ``` --- ## 💛 Support & Where the Money Goes First off, to be clear: **this is not meant to be income.** MooshieUI is a passion project. I build it in my spare time around a regular day job, I don't expect to earn anything from it, and right now the running costs come straight out of my own pocket. If you support the project through [GitHub Sponsors](https://github.com/sponsors/Mooshieblob1) or [Ko-fi](https://ko-fi.com/mooshieui), here is exactly where it goes: - **Domain & hosting** - keeping the project site and download links online. - **SaaS & dev tooling** - the paid services and tools used to actually build and ship MooshieUI. - **GitHub Pro+** - CI/CD minutes for the build, release, and security-scan pipelines. [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/R1F628M29D) The goal is simply to stop the project from costing me money to keep alive. Anything beyond covering costs just goes right back into building more features, faster. Longer term, the ideal is that MooshieUI can outlast my own availability. I intend to support this project for as long as I can, but every maintainer has lulls, and life can pull you away for a stretch. A small buffer means the domain, hosting, and infrastructure stay paid up through those quiet periods, so the project stays online and usable even when I am not actively maintaining it. Ko-fi is there for anyone who can't use GitHub Sponsors: it takes PayPal and cards, and you don't need an account. Supporting is completely optional and the app will always be free and open source either way. Thank you for even considering it. 🙏 --- ## 🤝 Contributing Pull requests are welcome. `main` is protected: open a PR from a `chore/` branch after local validation (`npm run check`) and GlassWorm pre-commit checks. CI runs the GlassWorm audit, the Guardrails checks and the Rust checks. See **[docs/push-instructions.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/push-instructions.md)** for the full workflow (branch naming, build gates, IPC/gallery conventions, and CI). --- ## 📋 Changelog See [CHANGELOG.md](https://github.com/Mooshieblob1/MooshieUI/blob/main/CHANGELOG.md) for the full version history. --- ## 📄 License Licensed under the [GNU Affero General Public License v3.0](https://github.com/Mooshieblob1/MooshieUI/blob/main/LICENSE). --- ## 🙏 Acknowledgments MooshieUI stands on the shoulders of a huge amount of open-source work. Sincere thanks to every project, researcher, model creator, and service below. ### Core foundations - **[ComfyUI](https://github.com/comfyanonymous/ComfyUI)** (comfyanonymous) - the local image/video backend and optional post-processing for NovelAI output. MooshieUI would not exist without it. - **[Tauri](https://tauri.app/)** - the Rust desktop app framework, plus its store, shell, dialog, fs, clipboard, updater, and process plugins. - **[Svelte](https://svelte.dev/)**, **[Tailwind CSS](https://tailwindcss.com/)**, **[Vite](https://vite.dev/)**, and **[TypeScript](https://www.typescriptlang.org/)** - the frontend stack. - **[PyTorch](https://pytorch.org/)** - the ML framework behind ComfyUI inference. - **[uv](https://github.com/astral-sh/uv)** (Astral) - manages Python and the ComfyUI environment during setup. - **[MinGit](https://gitforwindows.org/mingit)** (Git for Windows) - downloaded when needed for ComfyUI updates and custom-node installation on Windows. ### Inference runtimes - **[llama.cpp](https://github.com/ggml-org/llama.cpp)** (ggml-org) - local LLM inference for the Prompt Assistant. - **[ONNX Runtime](https://onnxruntime.ai/)** (Microsoft) via the **[ort](https://github.com/pykeio/ort)** Rust crate - runs the image interrogator. - **[Ultralytics](https://github.com/ultralytics/ultralytics)** - YOLOv8/YOLO11 detection powering Face Fix and segment refinement. ### Bundled third-party ComfyUI nodes Auto-installed into ComfyUI alongside MooshieUI's own nodes: - **[comfyui_controlnet_aux](https://github.com/Fannovel16/comfyui_controlnet_aux)** (Fannovel16) - ControlNet preprocessors (Canny, Depth, OpenPose, LineArt, and more). - **[ComfyUI-Frame-Interpolation](https://github.com/Fannovel16/ComfyUI-Frame-Interpolation)** (Fannovel16) - RIFE and GMFSS video frame interpolation. - **[ComfyUI_IPAdapter_plus](https://github.com/cubiq/ComfyUI_IPAdapter_plus)** (cubiq) - IP-Adapter style references. - **[ComfyUI-GGUF](https://github.com/city96/ComfyUI-GGUF)** (city96) - GGUF diffusion model and text encoder loading. - **[ComfyUI-INT8-Fast](https://github.com/BobJohnson24/ComfyUI-INT8-Fast)** (BobJohnson24) - the optional INT8 loader. - **[ComfyUI-MiniMax-H3-Turbo](https://github.com/Larryvrh/ComfyUI-MiniMax-H3-Turbo)** (Larryvrh) and **[ComfyUI-MiniMaxH3-TeaCache](https://github.com/Icyoung/ComfyUI-MiniMaxH3-TeaCache)** (Icyoung) - H3 video Turbo methods and TeaCache. - **[ComfyUI-Anima-Ref-Adapter](https://github.com/ElectronGirl/ComfyUI-Anima-Ref-Adapter)** (ElectronGirl) - Anima character references in the Style Reference panel. - **[ComfyUI-Cosmos-Reference](https://github.com/Mirumo0u0/ComfyUI-Cosmos-Reference)** (Mirumo0u0) - the reference latent behind Anima ReStyler in Image Edit. - **[ComfyUi-Untwisting-RoPE](https://github.com/BigStationW/ComfyUi-Untwisting-RoPE)** and **[ComfyUi-Scale-Image-to-Total-Pixels-Advanced](https://github.com/BigStationW/ComfyUi-Scale-Image-to-Total-Pixels-Advanced)** (BigStationW) - training-free style transfer (the Anima style-transfer workflow is ported from Untwisting-RoPE's examples) and advanced image scaling. ### Research implemented by MooshieUI's own nodes - **MultiDiffusion** - [Bar-Tal et al., ICML 2023 (arXiv:2302.08113)](https://arxiv.org/abs/2302.08113) - overlapping-tile fusion for tiled diffusion upscaling. - **SpotDiffusion** - [Frolov et al., 2024 (arXiv:2407.15507)](https://arxiv.org/abs/2407.15507) - seam-free shifted-window tiling. - **CFG Rescale** - ["Common Diffusion Noise Schedules and Sample Steps are Flawed" (Lin et al., arXiv:2305.08891)](https://arxiv.org/abs/2305.08891) - the basis of MooshieSoftGuidance, plus community "Mahiro"-style positive-biased guidance behind MooshieSmartGuidance. - **OmniSR** - ["Omni Aggregation Networks for Lightweight Image Super-Resolution" (CVPR 2023, arXiv:2304.10244)](https://arxiv.org/abs/2304.10244) - lightweight super-resolution. ### Models & model creators - **[WD Taggers v3](https://huggingface.co/SmilingWolf)** (SmilingWolf) - image interrogation/tagging. EVA02 Large is the default; ViT Large, SwinV2, ConvNeXt, and ViT are selectable in Settings. You can also register a custom tagger folder in Settings by pointing MooshieUI at any local folder that contains a WD v3-compatible model.onnx and matching selected_tags.csv; the folder is never modified by the app. - **[Kaloscope 3.0](https://huggingface.co/heathcliff01/Kaloscope3.0-preview)** (heathcliff01) - the artist classifier behind **Detect artists** in the interrogator. - **[CLIPSeg](https://huggingface.co/CIDAS/clipseg-rd64-refined)** (CIDAS) - text-prompted region detection for `` refinement. - **Face detection models** - [Anzhc's YOLOs](https://huggingface.co/Anzhc/Anzhcs_YOLOs) (default face segmentation) and [ADetailer models](https://huggingface.co/Bingsu/adetailer) (Bingsu) for Face Fix. - **Upscalers** - OmniSR, SPAN, and DAT (IllustrationJaNai) model weights hosted by [Acly](https://huggingface.co/Acly/Omni-SR) and [AshtakaOOf](https://huggingface.co/AshtakaOOf/safetensored-upscalers). - **Prompt Assistant LLMs** - [Qwen](https://huggingface.co/Qwen) (Alibaba) instruct and vision models and [DanTagGen](https://huggingface.co/KBlueLeaf/DanTagGen-delta) (KBlueLeaf), with GGUF quantizations by [bartowski](https://huggingface.co/bartowski); [JoyCaption](https://huggingface.co/fancyfeast/llama-joycaption-beta-one-hf-llava) (fancyfeast) for image descriptions, GGUF by [concedo](https://huggingface.co/concedo). - **Supported architectures & recommended models** - [Anima](https://huggingface.co/circlestone-labs/Anima) (Circlestone Labs), [Mugen](https://huggingface.co/CabalResearch/Mugen) (CabalResearch), Nanosaur (whose VAE builds on [Meta's DINOv3](https://github.com/facebookresearch/dinov3) and whose text encoder uses [Google's Gemma 3](https://huggingface.co/google/gemma-3-270m)), [SDXL and its VAE](https://huggingface.co/stabilityai) (Stability AI), and [Juice](https://huggingface.co/Enferlain/juice) (Enferlain). ### Watermarking - **[TrustMark](https://github.com/adobe/trustmark)** (Adobe) - the invisible watermark behind the optional gallery watermark. ### Ecosystem compatibility & inspiration - **[SwarmUI](https://github.com/mcmonkeyprojects/SwarmUI)** - MooshieUI reads and writes SwarmUI-compatible metadata, supports its ``/`` prompt syntax, and borrows its backend-handler and in-memory image delivery patterns. - **[AUTOMATIC1111 Stable Diffusion WebUI](https://github.com/AUTOMATIC1111/stable-diffusion-webui)** - legacy metadata parsing and the `(tag:1.1)` weight syntax. - **[InvokeAI](https://github.com/invoke-ai/InvokeAI)** and **[NovelAI](https://novelai.net/)** - additional prompt weight syntaxes MooshieUI understands and converts. - **[stealth-pnginfo](https://github.com/ashen-sensored/sd_webui_stealth_pnginfo)** (ashen-sensored) - the alpha-channel metadata embedding technique. - **[ComfyUI Impact Pack](https://github.com/ltdrdata/ComfyUI-Impact-Pack)** (ltdrdata) - the face-detailer concept that MooshieUI's lightweight FaceDetailer node reimplements. ### Data & services - **[CivitAI](https://civitai.com/)** - model search, hash lookup, and metadata. - **[Hugging Face](https://huggingface.co/)** - hosting for nearly every model MooshieUI downloads. - **[Danbooru](https://danbooru.donmai.us/)** and **[Gelbooru](https://gelbooru.com/)** - the tag taxonomies behind autocomplete (~140k tags; Gelbooru-derived Anima list curated by [BetaDoggo](https://huggingface.co/BetaDoggo)). - **[Animadex](https://animadex.net/)** - the character and LoRA database integration. - **[NovelAI](https://novelai.net/)** - the optional hosted image-generation backend, enhancement passes and Director Tools. - **[ElevenLabs](https://elevenlabs.io/)** and **[fal.ai](https://fal.ai/)** - the optional cloud voice and video providers behind Anime Scenes. - **[Photopea](https://www.photopea.com/)** - the embedded full image editor. - **GitHub** and **Cloudflare** - code hosting, CI/CD, releases, the CDN behind the artist gallery, and [cloudflared](https://github.com/cloudflare/cloudflared) for the optional MCP quick tunnel. ### Libraries - **Frontend**: [Konva](https://konvajs.org/) + [svelte-konva](https://github.com/konvajs/svelte-konva) (canvas editor), [marked](https://github.com/markedjs/marked) (markdown), [DOMPurify](https://github.com/cure53/DOMPurify) (sanitization), [SortableJS](https://github.com/SortableJS/Sortable) (drag & drop), and [ntc-ts](https://github.com/Danetag/ntc-ts) (a TypeScript port of [Chirag Mehta's "Name that Color"](https://chir.ag/projects/ntc/)). - **Rust**: [Tokio](https://tokio.rs/), [axum](https://github.com/tokio-rs/axum), [reqwest](https://github.com/seanmonstar/reqwest), [tokio-tungstenite](https://github.com/snapview/tokio-tungstenite), [rusqlite](https://github.com/rusqlite/rusqlite) + [SQLite](https://sqlite.org/), [jxl-oxide](https://github.com/tirr-c/jxl-oxide) and jxl-encoder ([JPEG XL](https://github.com/libjxl/libjxl) gallery storage), and [RustCrypto's Argon2](https://github.com/RustCrypto/password-hashes) (password hashing). If your work is used in MooshieUI and you feel it isn't credited properly here, please [open an issue](https://github.com/Mooshieblob1/MooshieUI/issues), it will be fixed promptly. --- # Contributing to MooshieUI Thanks for contributing. This guide covers how to set up, the checks your PR must pass, and the three core guidelines every change follows: i18n, a11y, and staying in scope. ## Setup Use Node.js 22.12+ or 24+, stable Rust, and the Tauri v2 prerequisites for your platform. The locked Svelte Vite plugin requires Node `^20.19 || ^22.12 || >=24`; Node 18 is not supported by the current frontend toolchain. Installation and Mac support are covered in the [wiki](https://github.com/Mooshieblob1/MooshieUI/wiki/Installation) and [Mac guide](https://github.com/Mooshieblob1/MooshieUI/blob/main/docs/MACOS.md). ```bash npm install npm run tauri dev # full desktop dev (Vite hot-reload) npm run dev # frontend only ``` Rust has two build targets. If you touch `src-tauri/`, check both so a desktop-only Tauri reference does not break the headless server: ```bash cargo check --manifest-path src-tauri/Cargo.toml cargo check --manifest-path src-tauri/Cargo.toml --no-default-features --features server cargo test --manifest-path src-tauri/Cargo.toml cargo fmt --manifest-path src-tauri/Cargo.toml --check cargo clippy --manifest-path src-tauri/Cargo.toml ``` There is no vitest/jest suite. A few pure-logic `node:test` files live in `scripts/tests/`; CI bundles them with esbuild and runs them in the Guardrails job. For documentation-only changes, review the documented behavior against the code and validate links; a native build is not needed unless executable code or build configuration also changes. ## Before you open a PR Run the local pre-flight: ```bash npm run check ``` This runs, in order: 1. `npm run build` (must pass), 2. `npm run check:i18n` (i18n parity, must pass), 3. `npm run check:portals` (every `fixed inset-0` overlay uses `use:portal`, must pass), 4. `npm run check:types` (svelte-check, must pass with no errors). Note on `check:types`: main has no svelte-check errors, so any error fails both `npm run check` and CI. Warnings (including a11y) are reported but don't fail; don't add new ones in the files you change. ## The three core guidelines ### i18n (blocking) All user-facing strings go through `locale.t('key')`. Never hardcode display text. When you add or change a string: - Add the key to `src/lib/locales/en.ts` (the source of truth). - Add the same key to every other locale file in `src/lib/locales/`. Missing keys fall back to English silently, so the gate catches them for you. - Keep every `{placeholder}` identical across locales for a given key. `npm run check:i18n` (and CI) fails on any missing key, extra key, or placeholder mismatch, and tells you exactly which file and key. ### a11y (advisory, becoming stricter) Interactive elements must be keyboard- and screen-reader-accessible: - Use real interactive elements (`