NAIWeaver

An unofficial cross-platform frontend for NovelAI's image generation API (Diffusion V5 and V4.5). Built with Flutter for Windows, Linux, Android, and Web.

Check out the github page to test it out, https://ststoryweaver.github.io/NAIWeaver/

• NovelAI V5 + V4.5 API integration (txt2img, img2img, inpainting, precise reference, vibe transfer, multiple characters) with a per-model capability layer — V5 adds free character positioning (32 characters), native transparency, auto-Text and the Opus usage battery; Vibe Transfer / Character Reference stay on V4.5 until NovelAI enables them for V5
• Multi-character generation with pixel-level positioning and multi-participant interactions
• Expanded inline character editor with tag suggestions, UC editing, position grid, and character presets (save/load)
• Multi-layer canvas editor for img2img source creation (paint, erase, shapes, text with Google Fonts, layers, selection tools, blur, clone stamp, zoom/pan)
• Custom resolution dialog with 64-snap validation and save-for-reuse
• Anlas balance tracker in app bar with auto-refresh after generation
• Furry mode toggle for fur dataset prefix in txt2img and Cascade
• In-app update checker via GitHub releases API
• PNG metadata round-trip — settings embedded in images, re-importable via drag-and-drop
• Seed control with randomization toggle for reproducible generations
• Duplicate generation detection with warning snackbar and quick randomize action
• Widescreen sidebar layout mode for ultrawide and multi-monitor setups
• Keyboard shortcuts: Ctrl+Enter to generate, Alt+Left/Right to cycle styles, Ctrl+Up/Down to adjust tag weight, canvas tool shortcuts
• Steps and CFG are remembered per model family (V4.5 / V5), and a style can carry its own steps/CFG override that applies while it is selected
• Prompt styles declare which model family they work with (V4.5, V5 or both); the STYLES panel, cascade beats and style cycling only offer styles made for the active model
• Custom filename and save-subfolder patterns (<prompt>, <seed>, <album>, date/time tokens, <digits> counters) with a live preview — subfolders are created under the output folder and under a custom export folder, including an SD card / picked folder on Android

Upload reference images to guide character appearance or artistic style. Supports three reference types (Character, Style, Character & Style) with per-reference strength and fidelity sliders. The REF button provides quick access to saved references via a popup menu for instant loading.

Apply the aesthetic "vibe" of reference images to generations. Each vibe has independent strength and information extraction controls, allowing fine-tuned style influence without precise character matching.

Sequential scene generation. Define setting, placement, actions, emotion, and state for each scene — add, remove, or reorder characters per beat, pick who interacts with whom, and toggle AI vs manual placement per beat. Once your story is made, use the Cast button to return to the main editor, add your characters, and watch them play out the scenes. The cast sheet only prompts for characters on the selected beat, and the ALBUM action adds that beat's image. An optional setting (off by default) saves each beat's last image so it comes back when you reopen the cascade. Includes unsaved-changes detection with save/discard confirmation.

Build reusable personas with split appearance buckets (base / face / hair / body, plus NSFW sub-buckets) and a per-character closet of outfits — each character is one local JSON file, with its closet stored separately so wardrobes stay portable. A ✨ generator drafts a character and a starter wardrobe from a free-text vibe + era + location (a catalogue of historical era presets, period-correct undergarment rules that are gender- and era-aware) and an optional artist style tag. Outfits track per-slot dressing state (intact → removed) with automatic concealment of layered pieces. Saved characters appear in the tag autocomplete as [Name] and [Name (Outfit)], expanding into the full body + outfit tag block, with per-character and per-outfit negative tags routed automatically. Photoshoot mode dresses a character in-place for a session — pull-up Dress / Scene / Prompt drawer, curated pose and environment presets, large image preview, and one-tap generate — without disturbing the saved closet. Requires Text Generation (a NovelAI text model) for the AI generators.

A NovelAI text-model tool with a continue-style multiline input, model picker, full parameter controls (temperature, max length, top-P/K, repetition and phrase-repetition penalties), client-side stop strings, live streaming output, and a local history. Model-aware transport routes GLM/Xialong models through the OpenAI-style completions endpoint (GLM-4.6 through the chat endpoint) and legacy Kayra/Clio/Erato through /ai/generate, all on the same pst- token as image generation. For GLM models, an "enable thinking" switch surfaces the model's reasoning block in a collapsible section. Also powers the Characters and Wardrobe AI generators.

• Background removal, image upscaling, and interactive segmentation via ONNX Runtime
• 8 downloadable ML models with SHA-256 integrity verification and device-aware recommendations
• Batch processing for gallery-wide BG removal and upscaling
• Before/after comparison slider with zoom and pan

• 6 NovelAI augment-image tools: Remove BG, Line Art, Sketch, Colorize, Emotion, Declutter
• Emotion supports 24 mood presets; Colorize supports defry and prompt input

• Quick img2img refinement with strength, noise, and scale controls; the scale chips follow NovelAI's 2× / 1.5× / 1× rule
• On V5, a MAX ✨ option sends the source at its own size with upscaled_enhance and returns it at 2× (or scaled to ~3.1 MP when 2× would exceed NovelAI's cap), with a predicted output size and an Anlas estimate fit to live runs (Max costs Anlas even on Opus)

• Floating action buttons on generated images (Save, Edit, Remove BG, Upscale, Enhance, Director Tools, Export to Device)
• Each button individually toggleable; context-aware based on downloaded models

• Full-screen image detail view with swipe navigation, zoom, and metadata display (grey screen bug fixed)
• Pin button in the viewer's top bar keeps the controls on screen instead of auto-hiding them; the choice is remembered across sessions and backups
• Bottom action bar with integrated ML, Director Tools, Enhance, and reference actions
• Gallery import preserves original creation dates from EXIF metadata
• Favorites, search, multi-select with drag-to-select
• Virtual albums (folder-like organization without moving files)
• Sort by date, name, or file size
• Image info overlay on hover
• Demo mode with PIN lock and biometric unlock for privacy
• Android data protection: "Keep app data?" prompt on uninstall, auto-backup to Google Drive

English, Japanese, and Simplified Chinese out of the box. Extensible via .arb files — see Contributing for adding new languages.

Token-based theming with 8 built-in themes (OLED Dark, Soft Dark, Midnight, Pastel Purple, Rose Quartz, Emerald, Amber Terminal, Cyberpunk) and unlimited custom themes. 17 configurable color tokens including bgRemoval and upscale. All colors and fonts flow through semantic design tokens.

• A NovelAI API key (subscription required)
• For building from source: Flutter stable with Dart SDK ^3.10.7 (the SDK constraint in pubspec.yaml is a Dart version)

Download the x86_64 AppImage from Releases, then run:

chmod +x NAIWeaver-x86_64.AppImage
./NAIWeaver-x86_64.AppImage

Use the downloaded filename if you chose a localized build. Flutter is only required for source builds. See the Linux installation and troubleshooting guide for system dependencies, FUSE errors, and source-build instructions.

Steam Deck users: see the Steam Deck notes and experimental Flatpak installation instructions. Releases from 0.9.6 include Flatpak bundles; verification on Deck hardware remains pending.

Linux builds from this source bundle ONNX Runtime 1.22.0 (CPU), matching the locked flutter_onnxruntime 1.6.3 plugin. You do not need to install or downgrade your system's ONNX packages. Older AppImages may be missing the versioned runtime library; the guide includes a per-app workaround.

On-device ML features (background removal, upscaling, segmentation) work on CPU out of the box. For faster inference on NVIDIA GPUs, install:

1. CUDA Toolkit 12.x — download
2. cuDNN 9.x — download (free NVIDIA account required)
   • Copy cuDNN DLLs into your CUDA Toolkit bin directory, or add cuDNN's bin to your system PATH

Ensure C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.x\bin is on your system PATH, then restart the app.

If CUDA is not installed, the app automatically falls back to DirectML (Windows) or CPU.

The bundled Linux runtime uses CPU inference; installing CUDA alone does not add GPU support to that build.

# Clone
git clone https://github.com/ststoryweaver/NAIWeaver.git
cd NAIWeaver

# Install dependencies
flutter pub get

# Run
flutter run -d windows    # Windows
flutter run -d linux       # Linux
flutter run -d chrome      # Web
flutter run                # Android (with device connected)

flutter build windows     # Windows release
flutter build linux        # Linux release
flutter build apk         # Android APK
flutter build web         # Web build

On Linux, install the build prerequisites first. To package an AppImage, run bash scripts/build-appimage.sh. Keep the entire build/linux/x64/release/bundle/ directory together when distributing a plain Linux build.

1. Launch the app
2. Go to TOOLS > SETTINGS
3. Enter your NovelAI API key
4. Start generating

On native platforms, TOOLS > SETTINGS offers optional persistence of Cascade beat previews. It is off by default. Enabling it restores each beat's last image and generation metadata when that story is reopened; deleting the story removes its stored previews. Web does not show this setting because browser persistence is not implemented.

Generation results stay attached to their originating story session and beat, including when beats move. Exiting or replacing the story discards its pending Cascade completion. Switching the viewed beat during saving or exporting preserves the new image's own metadata and filename.

See the 0.9.6 changelog and the release checklist for validation status and known limitations.

lib/
  main.dart                    # Entry point, provider setup
  core/
    ml/                        # On-device ML inference pipeline (ONNX Runtime)
    theme/                     # Token-based theme system
    l10n/                      # Locale state management
    services/                  # NovelAI API, preferences, paths, pack service, presets, styles, tags, wildcards
    utils/                     # Image utils, responsive helpers, snackbar, timestamps
    widgets/                   # Shared widgets (comparison slider, quick actions, dialogs, etc.)
  l10n/                        # ARB translation files (en, ja, zh)
  features/
    generation/                # Main generation UI, character editor, services
    characters/                # Saved-character library, AI char/wardrobe gen, outfits, photoshoot
    text_gen/                  # NovelAI text-model generation (streaming, reasoning, history)
    gallery/                   # Image gallery with albums, detail view, services
    director_ref/              # Director Reference system
    vibe_transfer/             # Vibe Transfer system
    tools/                     # Tools Hub (16 tools)
      canvas/                  # Multi-layer canvas editor with text/font tools
      cascade/                 # Multi-beat sequential generation
      director_tools/          # Director Tools (6 augmentation tools)
      enhance/                 # Enhance (quick img2img refinement)
      img2img/                 # Img2Img with inpainting
      ml/                      # ML model manager UI
      slideshow/               # Configurable slideshow player

See ARCHITECTURE.md for a detailed breakdown.

Share your presets, styles, wildcards, director references, characters, themes, albums and imported tag lists with others using .vpack files:

• Export: TOOLS > PACKS > Export Pack — select items, name your pack, save as .vpack
• Import: TOOLS > PACKS > Import Pack — open a .vpack, preview contents, import selected items
• Packs are ZIP archives containing JSON presets/styles and wildcard text files
• Director Reference images are extracted and re-embedded automatically

See ROADMAP.md for development principles, completed milestones, and planned features.

Contributions are welcome! See CONTRIBUTING.md for development setup, code style guidelines, and PR process.

Feature requests and bug reports are encouraged — please open a GitHub Issue.

These projects were great resources and inspiration:

• novelai-python by @LlmKira — NovelAI API Python SDK
• NAI_UI_2 by @EctoplasmicNeko — NovelAI desktop app with additional features
• ComfyUI_NAIDGenerator by @bedovyy — NovelAI Diffusion generator for ComfyUI
• Special thanks to Glockamoli and his TamperMonkey script for the comparison tool

• @baisumang — Simplified Chinese translation
• @andreiagmu
• @freakachu — Cascade editor: per-beat roster, placement, and interaction targeting

MIT