Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.
TypeScript ai-photo-editorcomfyui-alternativegenerative-fillimage-editingimage-generationinpaintinglinuxlocal-aimacosmcpmcp-servernano-banana-alternativeofflinephoto-editorprivacyqwen-imageqwen-image-2-1stable-diffusion-cppvulkanwindows
Turbo by default (official Qwen-Image 2.1 Turbo), faster Fast on Macs, honest Mac requirements
Gabriele Lozupone9e92141a8135
diff --git a/README.md b/README.mdindex feff5fb..bf4ef9a 100644--- a/README.md+++ b/README.md@@ -21,7 +21,7 @@<img src="https://img.shields.io/badge/NVIDIA-12%20GB%2B%20VRAM-6b6b6b?labelColor=333&style=flat-square&logo=nvidia&logoColor=76B900" alt="NVIDIA, 12 GB of VRAM or more"><img src="https://img.shields.io/badge/AMD-12%20GB%2B%20VRAM%20(beta)-6b6b6b?labelColor=333&style=flat-square&logo=amd&logoColor=white" alt="AMD, 12 GB of VRAM or more, beta"><img src="https://img.shields.io/badge/Intel%20Arc-12%20GB%2B%20VRAM%20(beta)-6b6b6b?labelColor=333&style=flat-square&logo=intel&logoColor=white" alt="Intel Arc, 12 GB of VRAM or more, beta">- <img src="https://img.shields.io/badge/Apple%20Silicon-16%20GB%2B%20unified%20memory%20(beta)-6b6b6b?labelColor=333&style=flat-square&logo=apple&logoColor=white" alt="Apple Silicon, 16 GB of unified memory or more, beta">+ <img src="https://img.shields.io/badge/Apple%20Silicon-32%20GB%20recommended%20(beta)-6b6b6b?labelColor=333&style=flat-square&logo=apple&logoColor=white" alt="Apple Silicon, 32 GB of unified memory recommended, beta"><br><a href="#use-it-from-your-ai-agent"><img src="https://img.shields.io/badge/MCP-server%20included-6b6b6b?labelColor=333&style=flat-square" alt="MCP server included"></a><a href="LICENSE"><img src="https://img.shields.io/github/license/GabrieleLozupone/kokon?style=flat-square&color=6b6b6b&labelColor=333" alt="License"></a>@@ -150,11 +150,11 @@ whole thing takes a few minutes, and the setup screen shows what Kokon can do wh| | Minimum | Recommended || --- | --- | --- |-| **Chip** | Apple M1 or newer (Intel Macs are not supported) | M-series Pro, Max or Ultra |+| **Chip** | Apple M1 or newer (Intel Macs are not supported) | M-series Pro, Max or Ultra (the GPU cores set the speed) || **macOS** | 26 Tahoe | latest |-| **Unified memory** | 16 GB (lightest mode, about 1 megapixel) | 24 GB or more; 32 GB+ for native 2K |+| **Unified memory** | 16 GB: works, but slowly (lightest mode, about 1 megapixel) | 32 GB or more (also gets native 2K) || **Disk** | 15 GB free | 25 GB free |-| **Time per image** | Minutes: a 512×512 image took about 2 minutes on a 16 GB M2 Pro | Faster on Pro/Max chips with more memory |+| **Time per image** | About 10 minutes for 1024×1024 on a 16 GB M2 Pro; Fast renders at 768×768 and enlarges, which is quicker | Faster on Max/Ultra chips with more memory; Turbo (the default) needs 8 steps instead of 20 |Kokon measures your machine's speed with the first image and shows realistic time estimatesfrom then on.@@ -183,7 +183,7 @@ preset later from Settings → Models → **Set up models…**| 32 GB+ | Qwen-Image 2.1 Q8_0 | Qwen3-VL 8B Q8_0 (8.7 GB) | ~19 GB | not yet |Every preset also gets stable-diffusion.cpp (the CUDA 12 build on NVIDIA, the Vulkan build on AMD and Intel, the Metal build on a Mac), the Qwen-Image 2.1 VAE, the-Qwen3-VL vision projector and, optionally, the 4x-UltraSharp upscaler. The sources are the+Qwen3-VL vision projector, the 8-step Qwen-Image 2.1 Turbo model and, optionally, the 4x-UltraSharp upscaler. The sources are theofficial [Qwen-Image 2.1](https://huggingface.co/Qwen/Qwen-Image-2.1) weights through[unsloth/Qwen-Image-2.1-GGUF](https://huggingface.co/unsloth/Qwen-Image-2.1-GGUF),[Qwen/Qwen3-VL-8B-Instruct-GGUF](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct-GGUF) and@@ -218,8 +218,9 @@ opened in Explorer or Finder. A few things make that loop fast:Undo returns to the version the current one came from, and nothing is ever deleted.- **Gallery**: every image keeps its full recipe (prompt, seed, settings, pipeline) and reopenswith one click. The recipe is also embedded in the PNG.-- **Quality presets**: Fast, Balanced, Quality (native 2K) and Ultra (native 2K with the- official 40 steps), so you never need to tune steps or guidance.+- **Quality presets**: **Turbo** (the default: ~1 MP in 8 steps with Qwen's official+ distilled model, about twice as fast), Fast, Balanced, Quality (native 2K) and Ultra (native 2K+ with the official 40 steps), so you never need to tune steps or guidance.## How it works@@ -427,7 +428,8 @@ been verified on a real AMD or Intel card yet; integrated graphics are not suppo[open an issue](https://github.com/GabrieleLozupone/kokon/issues) with your card and how it went.Mac: yes, in beta, on Apple Silicon (M1 or newer) with macOS 26. It runs on a 16 GB Mac in a-lighter mode; 24 GB or more is recommended. See the [requirements](#requirements) and+lighter mode, but slowly (about 10 minutes per 1-megapixel image on an M2 Pro); 32 GB or more+and a Pro, Max or Ultra chip are recommended. See the [requirements](#requirements) and[docs/platforms.md](docs/platforms.md).</details>@@ -448,7 +450,9 @@ Kokon is designed for. Smaller cards may come with lighter models in the future.Kokon's code is open source (see [License](#license)). The models have their own licenses:Qwen-Image 2.1 is released under the Qwen license (see the[model page](https://huggingface.co/Qwen/Qwen-Image-2.1)), and the optional 4x-UltraSharp-upscaler is CC BY-NC-SA 4.0, which means non-commercial use only. Check each license for your+upscaler is CC BY-NC-SA 4.0, which means non-commercial use only. Qwen-Image 2.1 Turbo+([model page](https://huggingface.co/Qwen/Qwen-Image-2.1-Turbo)) has the same license as+Qwen-Image 2.1. Check each license for youruse case.</details>diff --git a/crates/qls-core/src/catalog.rs b/crates/qls-core/src/catalog.rsindex f4881dc..98d0b64 100644--- a/crates/qls-core/src/catalog.rs+++ b/crates/qls-core/src/catalog.rs@@ -227,6 +227,23 @@ pub const UPSCALER: Download = Download {provides: &[],};+/// Turbo: Qwen's official 8-step distilled Qwen-Image 2.1 (Qwen/Qwen-Image-2.1-Turbo, Qwen+/// Research License like the base model), as a GGUF converted with stable-diffusion.cpp.+/// A separate diffusion model: the server restarts when a job switches between it and the+/// base model. Same-seed A/B on an RTX 5070 Ti (2026-10-10): ~2x faster than 20-step Fast,+/// equal quality, more faithful edits than the Viggle LoRA.+pub const TURBO_Q4_K: Download = Download {+ id: "turbo",+ label: "Qwen-Image 2.1 Turbo Q4_K (8 steps)",+ kind: FileKind::Model,+ url: "https://huggingface.co/DogukanUrker/Qwen-Image-2.1-Turbo-GGUF/resolve/main/qwen-image-2.1-turbo-Q4_K.gguf",+ page: "https://huggingface.co/DogukanUrker/Qwen-Image-2.1-Turbo-GGUF",+ size: 4_050_916_384,+ sha256: "f8d5611b495848b632f8ae14dc7da6525fe2796eb80998f8dee5e04d0a2f69eb",+ dest: "models/qwen21/qwen-image-2.1-turbo-Q4_K.gguf",+ provides: &[],+};+/// Hardware presets: which weights to download and how to run them, by VRAM.#[derive(Debug, Clone, Copy, Serialize)]pub struct Preset {@@ -240,6 +257,8 @@ pub struct Preset {/// `summary` for a Mac (no "system RAM": it is the same memory).pub unified_summary: &'static str,pub diffusion: Download,+ /// The 8-step Turbo model (the default quality level).+ pub turbo: Download,pub text_encoder: Download,pub text_encoder_placement: TextEncoderPlacement,/// Measured on real hardware of this class (otherwise only derived).@@ -257,6 +276,7 @@ pub const PRESETS: &[Preset] = &[unified_summary: "4-bit image model and text encoder; images of about 1–1.5 megapixels",min_vram_mib: 0,diffusion: DIFFUSION_Q4_K_M,+ turbo: TURBO_Q4_K,text_encoder: TEXT_ENCODER_Q4_K_M,text_encoder_placement: TextEncoderPlacement::Ram,verified: true,@@ -269,6 +289,7 @@ pub const PRESETS: &[Preset] = &[unified_summary: "4-bit image model and text encoder; native 2K for Quality",min_vram_mib: 14 * 1024,diffusion: DIFFUSION_Q4_K_M,+ turbo: TURBO_Q4_K,text_encoder: TEXT_ENCODER_Q4_K_M,text_encoder_placement: TextEncoderPlacement::Ram,verified: true,@@ -281,6 +302,7 @@ pub const PRESETS: &[Preset] = &[unified_summary: "8-bit image model (closest to the original); larger edits fit",min_vram_mib: 20 * 1024,diffusion: DIFFUSION_Q8_0,+ turbo: TURBO_Q4_K,text_encoder: TEXT_ENCODER_Q4_K_M,text_encoder_placement: TextEncoderPlacement::Ram,verified: false,@@ -293,6 +315,7 @@ pub const PRESETS: &[Preset] = &[unified_summary: "8-bit image model and 8-bit text encoder",min_vram_mib: 28 * 1024,diffusion: DIFFUSION_Q8_0,+ turbo: TURBO_Q4_K,text_encoder: TEXT_ENCODER_Q8_0,text_encoder_placement: TextEncoderPlacement::Ram,verified: false,@@ -317,7 +340,7 @@ pub fn recommended_preset(vram_mib: Option<u64>) -> &'static Preset {/// Everything a preset needs on `backend`, in download order (small, essential files first).pub fn downloads_for(p: &Preset, backend: GpuBackend, with_upscaler: bool) -> Vec<Download> {let mut v = engine_downloads(backend);- v.extend([VAE, VISION_PROJECTOR, p.text_encoder, p.diffusion]);+ v.extend([VAE, VISION_PROJECTOR, p.text_encoder, p.turbo, p.diffusion]);if with_upscaler {v.push(UPSCALER);}@@ -368,9 +391,9 @@ mod tests {// The default upscaler matches the one Settings offers first.assert!(UPSCALER.dest.ends_with(&format!("{}.pth", crate::config::DEFAULT_UPSCALER)));for p in PRESETS {- assert_eq!(downloads_for(p, GpuBackend::Cuda, true).len(), 7);+ assert_eq!(downloads_for(p, GpuBackend::Cuda, true).len(), 8);let vk = downloads_for(p, GpuBackend::Vulkan, false);- assert_eq!(vk.len(), 5);+ assert_eq!(vk.len(), 6);assert!(vk.iter().all(|d| d.id != "engine_cuda" && d.id != "cuda_runtime"));}}diff --git a/crates/qls-core/src/config.rs b/crates/qls-core/src/config.rsindex 0f1a5ca..54ae183 100644--- a/crates/qls-core/src/config.rs+++ b/crates/qls-core/src/config.rs@@ -620,6 +620,22 @@ impl AppConfig {}}+ /// The Turbo model of the hardware preset, if it is installed.+ pub fn turbo_model(&self) -> Option<PathBuf> {+ let t = self.preset().turbo;+ t.is_present(&self.sdcpp_dir).then(|| t.path(&self.sdcpp_dir))+ }++ /// This configuration with the server running the Turbo model instead of the active+ /// profile's diffusion model (same encoder, VAE and launch flags). None if not installed.+ pub fn with_turbo(&self) -> Option<AppConfig> {+ let path = self.turbo_model()?;+ let mut c = self.clone();+ let id = c.active_profile.clone();+ c.profiles.iter_mut().find(|p| p.id == id)?.diffusion_model = path;+ Some(c)+ }+/// The configured ESRGAN model file, if present. sd-server resolves names the same/// way: `<dir>/<name>.<ext>`, top level only.pub fn upscaler_file(&self) -> Option<PathBuf> {diff --git a/crates/qls-core/src/engine.rs b/crates/qls-core/src/engine.rsindex 75986ae..ea90562 100644--- a/crates/qls-core/src/engine.rs+++ b/crates/qls-core/src/engine.rs@@ -4,6 +4,7 @@use std::collections::{HashMap, VecDeque};use std::path::{Path, PathBuf};+use std::sync::atomic::{AtomicBool, Ordering};use std::sync::{Arc, Mutex, RwLock};use std::time::{Duration, Instant};@@ -86,6 +87,9 @@ pub enum Event {pub struct Engine {cfg: RwLock<AppConfig>,+ /// The server should run the Turbo model (the last job's choice; Turbo is the default),+ /// so starting it ahead of a job loads the model that job will most likely need.+ prefer_turbo: AtomicBool,pub server: Arc<ServerManager>,pub store: Arc<Store>,/// Private mode: records in memory, files under `private_dir`; wiped by `clear_private`,@@ -129,6 +133,8 @@ pub fn plan_inputs(cfg: &AppConfig, image_sizes: Vec<Size>, mask: Option<(Size,sage_attention: cfg.uses_sage_attention(),speed_factor: None,hide_uncalibrated: !crate::speed::trust_uncalibrated(cfg),+ unified_memory: false,+ turbo_available: cfg.turbo_model().is_some(),}}@@ -159,6 +165,7 @@ impl Engine {installer: crate::installer::Installer::new(),backend_version: Mutex::new(None),last_activity: Mutex::new(Instant::now()),+ prefer_turbo: AtomicBool::new(true),}))}@@ -464,6 +471,16 @@ impl Engine {Ok((img, rec))}+ /// The configuration to start the server with: the Turbo model when the last job used it+ /// (or no job ran yet) and it is installed, otherwise the active profile's model.+ pub fn server_config(&self) -> AppConfig {+ self.server_config_for(&self.config(), self.prefer_turbo.load(Ordering::Relaxed))+ }++ fn server_config_for(&self, cfg: &AppConfig, turbo: bool) -> AppConfig {+ turbo.then(|| cfg.with_turbo()).flatten().unwrap_or_else(|| cfg.clone())+ }+/// How this machine's measured speed compares with the time model (None: not measured).fn speed_factor(&self, cfg: &AppConfig) -> Option<f32> {self.speed.get(&crate::speed::machine_key(cfg, self.gpu().as_ref())).map(|c| c.factor)@@ -475,6 +492,7 @@ impl Engine {let vram = cfg.planning_vram_mib(self.gpu().map(|g| g.planning_mib()));let mut inputs = plan_inputs(&cfg, sizes, mask, vram);inputs.speed_factor = self.speed_factor(&cfg);+ inputs.unified_memory = self.gpu().is_some_and(|g| g.unified);planner::plan(req, &inputs, &cfg.profile().recommended_settings)}@@ -523,6 +541,7 @@ impl Engine {let mask_info = mask.as_ref().map(|(m, _)| (Size::new(m.width(), m.height()), imaging::mask_bbox(m, 16), imaging::mask_coverage(m, 16)));let mut plan_inputs = plan_inputs(&cfg, images.iter().map(|i| i.size()).collect(), mask_info, vram);plan_inputs.speed_factor = self.speed_factor(&cfg);+ plan_inputs.unified_memory = self.gpu().is_some_and(|g| g.unified);let plan = planner::plan(&request, &plan_inputs, &profile.recommended_settings)?;let seed = request.seed.unwrap_or_else(random_seed);let mut request = request;@@ -537,12 +556,16 @@ impl Engine {// 3. Backend.// A job that also starts the server is not a fair speed sample (startup, first load).+ // Turbo runs on its own diffusion model: switching restarts the server with the other one.+ self.prefer_turbo.store(plan.turbo, Ordering::Relaxed);+ let run_cfg = self.server_config_for(&cfg, plan.turbo);+ let model_loaded = self.server.capabilities().is_some_and(|c| c.model_matches(&run_cfg.profile().diffusion_model));let mut cold_start = false;- if self.server.status().state != ServerState::Ready || self.server.owned_alive() == Some(false) {+ if self.server.status().state != ServerState::Ready || self.server.owned_alive() == Some(false) || !model_loaded {cold_start = true;self.update(id, |j| j.view.status = JobStatus::StartingBackend);self.emit_server();- let r = self.server.ensure_ready(&cfg).await;+ let r = self.server.ensure_ready(&run_cfg).await;self.emit_server();r?;}@@ -635,7 +658,7 @@ impl Engine {}}if self.is_cancelled(id) {- return self.cancel_running(id, &client, &accepted.id, &cfg).await;+ return self.cancel_running(id, &client, &accepted.id, &self.server_config()).await;}if last_poll.elapsed() >= Duration::from_millis(500) {last_poll = Instant::now();diff --git a/crates/qls-core/src/pipeline.rs b/crates/qls-core/src/pipeline.rsindex ede1136..0ccd287 100644--- a/crates/qls-core/src/pipeline.rs+++ b/crates/qls-core/src/pipeline.rs@@ -172,6 +172,7 @@ pub fn prepare(plan: &Plan, prompt: &str, seed: i64, images: &[LoadedImage], masscheduler: plan.scheduler.clone(),sample_steps: plan.steps,flow_shift: plan.flow_shift,+ custom_sigmas: plan.custom_sigmas.clone(),guidance: Guidance { txt_cfg: plan.cfg, img_cfg: None },},vae_tiling_params: vae_tiling_params(plan.vae_tiling, opts.server_vae_tile_size),diff --git a/crates/qls-core/src/planner.rs b/crates/qls-core/src/planner.rsindex 09c0f9b..9e798dd 100644--- a/crates/qls-core/src/planner.rs+++ b/crates/qls-core/src/planner.rs@@ -132,10 +132,13 @@ pub const UPSCALE_PROMPT: &str = "A sharp, highly detailed, high-quality image w#[serde(rename_all = "snake_case")]pub enum Quality {Fast,- #[default]Balanced,Quality,Ultra,+ /// ~1 MP in 8 steps with Qwen's distilled Turbo model (`catalog::TURBO_Q4_K`). The+ /// default; plans fall back to Balanced when the Turbo model is not installed.+ #[default]+ Turbo,}#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]@@ -321,6 +324,12 @@ pub struct Plan {pub upscaler: Option<String>,#[serde(default)]pub upscale: Option<UpscalePlan>,+ /// Run on the Turbo model instead of the profile's diffusion model.+ #[serde(default)]+ pub turbo: bool,+ /// Exact noise schedule (Turbo); empty = the server's default for `steps`.+ #[serde(default)]+ pub custom_sigmas: Vec<f32>,}/// Facts about inputs and the environment, measured before planning.@@ -343,6 +352,11 @@ pub struct PlanInputs {/// Without a measurement, report `estimated_seconds` = 0 (unknown until the first image)/// instead of the uncalibrated model, which only fits the hardware it was measured on.pub hide_uncalibrated: bool,+ /// Apple Silicon (unified memory): the GPU is several times slower than the discrete+ /// cards the presets were tuned on, so Fast renders smaller (`UNIFIED_FAST_AREA`).+ pub unified_memory: bool,+ /// The Turbo model is installed (`AppConfig::turbo_model`).+ pub turbo_available: bool,}// ---------------------------------------------------------------------------------------@@ -496,6 +510,8 @@ pub fn resolution_area(mode: ResolutionMode, quality: Quality, rec: &RecommendedQuality::Balanced => rec.area_balanced,Quality::Quality => rec.area_quality,Quality::Ultra => rec.area_ultra,+ // ~1 MP, like the distillation's training and Fast.+ Quality::Turbo => rec.area_fast,}),ResolutionMode::K1 => Some(1024 * 1024),ResolutionMode::K15 => Some(1536 * 1536),@@ -535,8 +551,18 @@ pub fn unified_memory_planning_mib(ram_mib: u64, text_encoder_mib: u64) -> u64 {gpu_share.saturating_sub(text_encoder_mib)}+/// Working area of Fast (Auto resolution) on Apple Silicon. Sampling time grows faster than+/// the area, so 768² takes well under half of 1 MP; the upscaler model then enlarges the+/// result to the size Fast would have rendered.+pub const UNIFIED_FAST_AREA: u64 = 768 * 768;+pub const PIXELS_PER_TOKEN: u64 = 256; // 8x VAE downscale, 2x2 patches+/// Turbo's noise schedule: `sample_sigmas` of Qwen/Qwen-Image-2.1-Turbo's model_index.json+/// (8 steps, fixed at every resolution, no dynamic shift), sent verbatim because sd.cpp's+/// own Qwen schedule shifts by resolution and has a 0.02 terminal shift.+pub const TURBO_SIGMAS: [f32; 9] = [1.0, 0.978453, 0.95418, 0.926626, 0.89508, 0.845148, 0.704534, 0.414568, 0.0];+/// Area of the inpaint guide reference (the region with the painted area marked), as a/// share of the working canvas: enough to locate the area, cheap in tokens.pub const INPAINT_GUIDE_AREA: f64 = 0.25;@@ -592,6 +618,7 @@ fn steps_for(q: Quality, rec: &RecommendedSettings) -> u32 {Quality::Balanced => rec.steps_balanced,Quality::Quality => rec.steps_quality,Quality::Ultra => rec.steps_ultra,+ Quality::Turbo => TURBO_SIGMAS.len() as u32 - 1,}}@@ -702,16 +729,27 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSettiif req.prompt.trim().is_empty() && !prompt_optional {return Err(AppError::invalid("Describe what to generate or change."));}- let default_cfg = if mode == ResolvedMode::Generate { rec.cfg } else { rec.cfg_edit };- let cfg = req.advanced.cfg.unwrap_or(default_cfg).clamp(0.0, 30.0);let mut notes = Vec::new();+ // Turbo (the default) needs its model; without it the job runs as Balanced.+ let quality = if req.quality == Quality::Turbo && !inputs.turbo_available {+ notes.push("The Turbo model is not installed, so this used Balanced. Add it in Settings → Models → Set up models….".into());+ Quality::Balanced+ } else {+ req.quality+ };+ // Turbo: its fixed schedule, CFG 1 (an upscale keeps its own settings).+ let turbo = quality == Quality::Turbo && mode != ResolvedMode::Upscale;+ let default_cfg = if mode == ResolvedMode::Generate { rec.cfg } else { rec.cfg_edit };+ let cfg = if turbo { 1.0 } else { req.advanced.cfg.unwrap_or(default_cfg).clamp(0.0, 30.0) };let budget_tokens = token_budget(inputs.vram_total_mib);let budget_area = budget_tokens * PIXELS_PER_TOKEN;- let tier_area = resolution_area(req.resolution, req.quality, rec);+ let tier_area = resolution_area(req.resolution, quality, rec);let adv = &req.advanced;- let mut steps = adv.steps.unwrap_or_else(|| steps_for(req.quality, rec)).clamp(1, 150);+ let mut steps = if turbo { steps_for(Quality::Turbo, rec) } else { adv.steps.unwrap_or_else(|| steps_for(quality, rec)).clamp(1, 150) };let batch_count = if mode == ResolvedMode::Upscale { 1 } else { adv.batch_count.unwrap_or(1).clamp(1, 8) };let mut optimized = false;+ // Largest area actually rendered; the output keeps its size and is enlarged afterwards.+ let render_cap = (inputs.unified_memory && quality == Quality::Fast && req.resolution == ResolutionMode::Auto).then_some(UNIFIED_FAST_AREA);// Diffusion always runs in one pass; larger outputs are enlarged with the upscaler// model (user A/B test, 2026-10-06: the two-pass refine made results worse).// `refine` only sets the effort of a Detailed upscale.@@ -787,7 +825,8 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSettilet wanted = tier_area.unwrap_or(rec.area_balanced);let area = cap_for_refs(wanted, 0.0, &mut notes);let size = size_for_aspect(aspect, area, rec);- working = plan_working_canvas(size, &limits(size.area(), rec));+ let render = render_cap.map_or(size.area(), |c| c.min(size.area()));+ working = plan_working_canvas(size, &limits(render, rec));output = size;}}@@ -822,12 +861,16 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSetti// than the target's area (see `ref_canvas`), so small references leave room.let area = cap_for_sources(wanted, &inputs.image_sizes, &mut notes);sources_reduced = area < wanted;- working = plan_working_canvas(target, &limits(area, rec));+ let full = plan_working_canvas(target, &limits(area, rec));+ working = match render_cap {+ Some(c) if c < area => plan_working_canvas(target, &limits(c, rec)),+ _ => full,+ };for (i, s) in inputs.image_sizes.iter().enumerate() {let c = if i == 0 && *s == target { working } else { ref_canvas(*s, working.canvas.area(), rec) };references.push(RefPlan { index: i, source: *s, canvas: c });}- output = if req.preserve_dimensions || tier || chosen_aspect.is_some() { target } else { working.content };+ output = if req.preserve_dimensions || tier || chosen_aspect.is_some() { target } else { full.content };strength = adv.strength.map(|s| s.clamp(0.0, 1.0));}ResolvedMode::Upscale => {@@ -983,7 +1026,7 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSettioutpaint,inpaint_region,inpaint_action,- quality: req.quality,+ quality,resolution: req.resolution,notes,optimized_for_vram: optimized,@@ -991,6 +1034,8 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSetticache_threshold,upscaler: inputs.upscaler.clone(),upscale,+ custom_sigmas: if turbo { TURBO_SIGMAS.to_vec() } else { Vec::new() },+ turbo,})}@@ -1038,7 +1083,7 @@ mod tests {RecommendedSettings::default()}fn req(prompt: &str) -> GenerationRequest {- GenerationRequest { prompt: prompt.into(), preserve_dimensions: true, ..Default::default() }+ GenerationRequest { prompt: prompt.into(), preserve_dimensions: true, quality: Quality::Balanced, ..Default::default() }}fn inputs(sizes: &[(u32, u32)]) -> PlanInputs {PlanInputs { image_sizes: sizes.iter().map(|(w, h)| Size::new(*w, *h)).collect(), mask: None, vram_total_mib: Some(16303), ..Default::default() }@@ -1056,6 +1101,54 @@ mod tests {assert!(p.references.is_empty());}+ #[test]+ fn turbo_is_the_default_and_uses_its_model_and_schedule() {+ assert_eq!(GenerationRequest::default().quality, Quality::Turbo, "the default");+ let mut r = req("a lighthouse at dusk");+ r.quality = Quality::Turbo;+ r.advanced.cfg = Some(4.0);+ r.advanced.steps = Some(30);+ let i = PlanInputs { turbo_available: true, ..inputs(&[]) };+ let p = plan(&r, &i, &rec()).unwrap();+ assert_eq!(p.working, Size::new(1024, 1024), "~1 MP");+ assert_eq!((p.steps, p.cfg, p.turbo), (8, 1.0, true), "fixed steps, no CFG");+ assert_eq!(p.custom_sigmas, TURBO_SIGMAS.to_vec());+ // Edits too; other qualities never run on the Turbo model.+ let p = plan(&r, &PlanInputs { turbo_available: true, ..inputs(&[(1200, 800)]) }, &rec()).unwrap();+ assert!(p.turbo && p.custom_sigmas.len() == 9);+ r.quality = Quality::Fast;+ let p = plan(&r, &i, &rec()).unwrap();+ assert!(!p.turbo && p.custom_sigmas.is_empty());+ // Not installed: Balanced, with a note.+ r.quality = Quality::Turbo;+ r.advanced = Default::default();+ let p = plan(&r, &inputs(&[]), &rec()).unwrap();+ assert!(!p.turbo && p.quality == Quality::Balanced && p.steps == 20);+ assert!(p.notes.iter().any(|n| n.contains("Turbo model is not installed")));+ }++ #[test]+ fn mac_fast_renders_smaller_and_keeps_the_output_size() {+ let mac = |sizes: &[(u32, u32)]| PlanInputs { unified_memory: true, vram_total_mib: Some(4600), upscaler: Some("4x-UltraSharp".into()), ..inputs(sizes) };+ let mut r = req("a lighthouse at dusk");+ r.quality = Quality::Fast;+ let p = plan(&r, &mac(&[]), &rec()).unwrap();+ assert_eq!(p.output, Size::new(1024, 1024), "same output as Fast on a PC");+ assert_eq!(p.working, Size::new(768, 768));+ assert!(p.notes.iter().any(|n| n.contains("enlarged")));+ // Edits too: smaller render, source size kept.+ let p = plan(&r, &mac(&[(1024, 768)]), &rec()).unwrap();+ assert_eq!(p.output, Size::new(1024, 768));+ assert!(p.working.area() <= UNIFIED_FAST_AREA + 32 * 1024, "{:?}", p.working);+ // Other qualities, explicit sizes and PCs are unchanged.+ r.quality = Quality::Balanced;+ assert_eq!(plan(&r, &mac(&[]), &rec()).unwrap().working, Size::new(1024, 1024), "budget-capped 1 MP");+ r.quality = Quality::Fast;+ assert_eq!(plan(&r, &inputs(&[]), &rec()).unwrap().working, Size::new(1024, 1024));+ r.resolution = ResolutionMode::K1;+ assert_eq!(plan(&r, &mac(&[]), &rec()).unwrap().working, Size::new(1024, 1024));+ }+#[test]fn negative_prompt_needs_cfg() {let mut r = req("a lighthouse at dusk");diff --git a/crates/qls-core/src/sdcpp.rs b/crates/qls-core/src/sdcpp.rsindex 03b86c2..5c55105 100644--- a/crates/qls-core/src/sdcpp.rs+++ b/crates/qls-core/src/sdcpp.rs@@ -38,6 +38,9 @@ pub struct SampleParams {pub sample_steps: u32,#[serde(skip_serializing_if = "Option::is_none")]pub flow_shift: Option<f32>,+ /// Exact noise schedule, used verbatim (steps = len - 1, no shift).+ #[serde(skip_serializing_if = "Vec::is_empty")]+ pub custom_sigmas: Vec<f32>,pub guidance: Guidance,}@@ -457,6 +460,7 @@ mod tests {scheduler: None,sample_steps: 30,flow_shift: None,+ custom_sigmas: Vec::new(),guidance: Guidance { txt_cfg: 6.0, img_cfg: None },},vae_tiling_params: None,@@ -483,6 +487,11 @@ mod tests {assert_eq!(v["embed_image_metadata"], false);assert_eq!(v["image_preprocess"][0], "target=ref,mode=none");assert!(v.get("hires").is_none() && v.get("cache_mode").is_none() && v.get("cache_option").is_none(), "server defaults apply");+ assert!(v["sample_params"].get("custom_sigmas").is_none(), "default schedule");+ // Turbo: exact schedule.+ let turbo = ImgGenRequest { sample_params: SampleParams { custom_sigmas: vec![1.0, 0.5, 0.0], ..req.sample_params.clone() }, ..req };+ let v = serde_json::to_value(&turbo).unwrap();+ assert_eq!(v["sample_params"]["custom_sigmas"][1], 0.5);}#[test]diff --git a/crates/qls-service/src/api.rs b/crates/qls-service/src/api.rsindex 4cfc4e9..40514e2 100644--- a/crates/qls-service/src/api.rs+++ b/crates/qls-service/src/api.rs@@ -189,6 +189,7 @@ async fn status(State(s): St) -> Json<Value> {"upscale": srv.capabilities.as_ref().map(|c| c.upscale),},"upscaler": { "model": cfg.upscaler_model, "available": cfg.upscaler_file().is_some(), "refine_mode": cfg.refine_mode },+ "turbo": { "available": cfg.turbo_model().is_some() },"profile": { "id": cfg.profile().id, "display_name": cfg.profile().display_name },"gpu": gpu,"active_job": s.engine.active_job(),@@ -334,7 +335,7 @@ async fn put_config(State(s): St, Json(cfg): Json<AppConfig>) -> ApiResult<Json<}async fn backend_start(State(s): St) -> ApiResult<Json<Value>> {- let cfg = s.engine.config();+ let cfg = s.engine.server_config();let engine = s.engine.clone();engine.emit_server();let r = engine.server.ensure_ready(&cfg).await;diff --git a/docs/engineering-notes.md b/docs/engineering-notes.mdindex 5e81bbc..7855457 100644--- a/docs/engineering-notes.md+++ b/docs/engineering-notes.md@@ -117,6 +117,42 @@ Whenever a result is larger than what the model rendered (edits restored to theoutpaint, sizes above the VRAM budget) it is enlarged with ESRGAN ×4 and then resized down tothe exact size; Lanczos is only used for shrinking or factors below 1.1×.+On Apple Silicon, Fast at Auto resolution renders at most 768² (`planner::UNIFIED_FAST_AREA`)+and is enlarged to the 1 MP output, because Mac GPUs are several times slower.++### Turbo (the default quality, 2026-10-10)++Quality level **Turbo** = ~1 MP in 8 steps on Qwen's official distilled model+([Qwen/Qwen-Image-2.1-Turbo](https://huggingface.co/Qwen/Qwen-Image-2.1-Turbo), released+2026-10-09, Qwen Research License like the base), as the stable-diffusion.cpp conversion+[DogukanUrker/Qwen-Image-2.1-Turbo-GGUF](https://huggingface.co/DogukanUrker/Qwen-Image-2.1-Turbo-GGUF)+Q4_K (4.05 GB, `catalog::TURBO_Q4_K`, part of every preset). t2i and edits.++- It is a separate diffusion model. `AppConfig::with_turbo` swaps it into the active profile;+ the engine restarts the server when a job needs the other model (`Engine::server_config_for`),+ and starts the server with the model of the last job (Turbo before any job). Switching costs a+ full server start (encoder included), so mixing Turbo and other levels is slow.+- Schedule: `planner::TURBO_SIGMAS` = `sample_sigmas` of the checkpoint's model_index.json+ ([1, .978453, .95418, .926626, .89508, .845148, .704534, .414568, 0], fixed at every+ resolution), sent as `sample_params.custom_sigmas` (used verbatim, steps = len − 1). sd.cpp's+ default Qwen schedule shifts by resolution and has a 0.02 terminal shift. CFG is forced to 1;+ Advanced steps/CFG are ignored.+- Not installed (configs from before Turbo): Turbo requests run as Balanced with a note.+- **Same-seed A/B, RTX 5070 Ti, 1024², 3 t2i + 3 edits** (`scripts/dev/compare-fast-modes.py`):+ Fast (20 steps) 19.1 s t2i / 23.8 s edit; Viggle v0.3 LoRA (6 steps) 10.1 / 13.6 s; official+ Turbo (8 steps) 9.5 / 13.1 s. ~4.5 s per image are fixed (encode, 2.7 s decode), so the+ sampling speed-up (18.4 → 7.8 s) shows less here than on a Mac. The LoRA made every step 30%+ slower (runtime LoRA on GGUF: 1.15 vs 0.85–0.88 s/step). Quality equal by eye; in the poster+ edit ("title → PORTO, tram blue") Fast and Viggle dropped the subtitle, Turbo kept it.+- Candidates rejected or not adopted: Viggle turbo v0.3 LoRA (works, slower per step, third+ party); Turbo8 and Pruna 8-step LoRAs (unofficial; Turbo8 reports text exact-match 75% vs+ 95%); Sarvam Tez 2-step (t2i only, precision-sensitive); **Alibaba Fun-Acc 4-step**: a PDD+ bundle, not a plain LoRA (keys without `.weight` that sd.cpp ignores silently, replacement norm+ weights, `proj_out.weight [4,64,4096]` = one output head per step), would need an sd.cpp+ patch. LightX2V Lightning for 2.1: not released (issue #1548).+- Open: Turbo Q6_K / Q8_0 vs Q4_K (the comparison script has `official8_q6_k`,+ `official8_q8_0`); Turbo above 1 MP.+The **Upscale** action has two methods: **Quick** (ESRGAN only) and **Detailed** (a low-denoise0.3 img2img pass at about 2K, then ESRGAN to the target).diff --git a/docs/platforms.md b/docs/platforms.mdindex bd1f589..0f2459e 100644--- a/docs/platforms.md+++ b/docs/platforms.md@@ -8,7 +8,7 @@ so model behaviour is identical everywhere; only speed and memory differ.| --- | --- | --- || Windows + NVIDIA | CUDA 12 build | ✅ verified (RTX 5070 Ti 16 GB, RTX 5070 12 GB) || Windows + AMD / Intel | Vulkan build (30 MB, uses the driver's Vulkan runtime) | 🟡 beta: works on NVIDIA (RTX 5070 Ti, 2K/20 steps, slower than CUDA); AMD / Intel to verify |-| macOS + Apple Silicon | Metal build (universal binary, shaders embedded) | 🟡 beta: runs on an M2 Pro 16 GB (512² in ~2 min, lightest mode); `.dmg` build script ready, first packaged build pending |+| macOS + Apple Silicon | Metal build (universal binary, shaders embedded) | 🟡 beta: packaged 0.9.0 runs on an M2 Pro 16 GB (1024² in ~10 min, 512² in ~2 min, lightest mode) || Windows + AMD via ROCm | ROCm build | ✗ not planned: open crashes (#2008), DLL conflicts (#2012), black images with k-quants (#1385) || Linux | Vulkan / CUDA builds exist | later |@@ -50,12 +50,18 @@ pass. Kokon uses CFG 1, which is one pass per step.| --- | --- | --- || **Chip** | Apple M1 or newer (Intel Macs: no) | M-series Pro / Max / Ultra || **macOS** | 26 Tahoe (the engine binary's minimum) | latest |-| **Unified memory** | 16 GB (lightest mode, ~1 MP; verified on an M2 Pro) | 24 GB+ (everything stays loaded); 32 GB+ for Quality 2K; 48 GB+ gets the 8-bit model |+| **Unified memory** | 16 GB: works, but slowly (lightest mode, ~1 MP, ~10 min on an M2 Pro) | 32 GB+ (everything stays loaded, Quality 2K); 48 GB+ gets the 8-bit model || **Disk** | 15 GB free | 25 GB on the internal SSD |16 GB Macs run in the lightest setup: 1 MP, with each model's weights loaded when it runs andreleased afterwards. That costs only a few seconds per image; the GPU compute is what makes it-slow (a 512² image took ~2 min on the M2 Pro). The setup screen says so before downloading.+slow (on the M2 Pro 16 GB with the packaged 0.9.0: 512² ~2 min, 1024² ~10 min). The setup+screen says so before downloading, and recommends 32 GB and a Pro/Max/Ultra chip.++**Fast on a Mac renders smaller** (2026-10-09): on unified memory, Fast at Auto resolution+renders at most 768² (`planner::UNIFIED_FAST_AREA`) and the upscaler model enlarges the result+to the size Fast renders on a PC (1 MP). Sampling cost grows faster than the area, so this is+well under half the sampling time. Balanced, Quality, Ultra and explicit sizes are unchanged.### Why macOS paging does not help here (verified in the source, 2026-10-09)@@ -156,3 +162,18 @@ so nobody with a base chip is surprised.6. Testing: runs on the M2 Pro 16 GB (device name `mtl0` fixed from that run); an M4 Pro 24 GBrun is planned. Originally: needs a real Apple Silicon Mac with 24 GB+ (GitHub's runners have 7 GB: buildonly). Without one, ship as "beta, untested".++### Speed roadmap for Macs++1. ✅ **Turbo**: Qwen's official 8-step model, now the default quality; the largest gain on+ every platform. See the Turbo notes in `docs/engineering-notes.md`. Mac speed not measured yet.+2. ✅ Honest requirements: 16 GB works but slowly; 32 GB+ and a Pro/Max/Ultra chip recommended.+3. ✅ Fast renders at 768² on Macs and enlarges (above).+4. **Later: an MLX engine.** Apple's MLX framework (through [mflux](https://github.com/filipstrand/mflux))+ may be faster than ggml's Metal backend; a community 4-bit MLX build of Qwen-Image 2.1+ exists (about 6.7 s/step at 768² on an M1 Max, ~7 GB peak; ~78 s per 1024² image on an+ M5 Max 64 GB, per third-party reports, unverified). Not done now because: the gain over+ sd.cpp Metal is unmeasured (maybe 1.3–2×), it needs a bundled Python runtime and a second+ backend path (request mapping, edits, inpaint semantics, upscaler) to maintain, and it does+ not fix 16 GB Macs, where memory, not the engine, is the limit. Revisit after Turbo ships,+ with a same-machine benchmark of both engines first.diff --git a/mcp/src/tools.ts b/mcp/src/tools.tsindex 26e4cc8..6e08da2 100644--- a/mcp/src/tools.ts+++ b/mcp/src/tools.ts@@ -6,8 +6,8 @@ import { allowedRoots, checkInput, checkOutput, PathError } from "./paths.js";import { ServiceClient, ServiceError } from "./service.js";const quality = z- .enum(["fast", "balanced", "quality", "ultra"])- .describe("fast = ~1 MP, 20 steps; balanced = ~1.5K, 20 steps (the default); quality = native 2K, 20 steps (slower; edits share 2K with their references); ultra = native 2K, 40 steps (slowest)");+ .enum(["turbo", "fast", "balanced", "quality", "ultra"])+ .describe("turbo = ~1 MP in 8 steps with Qwen's distilled Turbo model (the default, fastest; runs as balanced if the Turbo model is not installed); fast = ~1 MP, 20 steps; balanced = ~1.5K, 20 steps; quality = native 2K, 20 steps (slower; edits share 2K with their references); ultra = native 2K, 40 steps (slowest)");const seed = z.number().int().min(-1).max(2_147_483_647).describe("Seed for reproducible results; omit or -1 for random");const dim = z.number().int().min(64).max(4096);const aspect = z@@ -264,7 +264,7 @@ export const handlers = {height: a.height,resolution: a.width ? "custom" : "auto",aspect_ratio: a.aspect_ratio,- quality: a.quality ?? "balanced",+ quality: a.quality ?? "turbo",seed: a.seed,output_path: out,advanced: {},@@ -279,7 +279,7 @@ export const handlers = {const out = a.output_path ? checkOutput(a.output_path, ctx.cwd, r) : undefined;return runJob(ctx,- { prompt: a.prompt, negative_prompt: a.negative_prompt, mode: "edit", images: [img], quality: a.quality ?? "balanced", seed: a.seed, preserve_dimensions: a.preserve_dimensions ?? true, output_path: out, advanced: {} },+ { prompt: a.prompt, negative_prompt: a.negative_prompt, mode: "edit", images: [img], quality: a.quality ?? "turbo", seed: a.seed, preserve_dimensions: a.preserve_dimensions ?? true, output_path: out, advanced: {} },!!a.include_preview,);},@@ -299,7 +299,7 @@ export const handlers = {height: a.height,resolution: a.width ? "custom" : "auto",aspect_ratio: a.aspect_ratio,- quality: a.quality ?? "balanced",+ quality: a.quality ?? "turbo",seed: a.seed,output_path: out,advanced: {},@@ -320,7 +320,7 @@ export const handlers = {mode: "outpaint",images: [img],outpaint: { left: a.left, right: a.right, top: a.top, bottom: a.bottom, units: a.units },- quality: a.quality ?? "balanced",+ quality: a.quality ?? "turbo",seed: a.seed,output_path: out,advanced: {},@@ -337,7 +337,7 @@ export const handlers = {if (!a.prompt && a.action !== "remove") throw new PathError("prompt must not be empty (only action 'remove' works without one).");return runJob(ctx,- { prompt: a.prompt, mode: "inpaint", inpaint_action: a.action, images: [img], mask, quality: a.quality ?? "balanced", seed: a.seed, output_path: out, advanced: {} },+ { prompt: a.prompt, mode: "inpaint", inpaint_action: a.action, images: [img], mask, quality: a.quality ?? "turbo", seed: a.seed, output_path: out, advanced: {} },!!a.include_preview,);},diff --git a/scripts/dev/compare-fast-modes.py b/scripts/dev/compare-fast-modes.pynew file mode 100644index 0000000..3a51e92--- /dev/null+++ b/scripts/dev/compare-fast-modes.py@@ -0,0 +1,417 @@+"""Same-seed A/B of Kokon's quality levels and few-step LoRAs (text-to-image and edits).++Close Kokon first: this starts its own sd-server with the exact launch flags of Kokon's last+run (from the service log) plus `--lora-model-dir`, so every variant runs on the same engine+settings. Each case uses one fixed seed for every variant. Variants at the same size start+from the same noise, so their compositions are directly comparable (Fast = the full model at+1 MP, the reference for the 1 MP few-step LoRAs).++ python -I scripts/dev/compare-fast-modes.py # all variants, 10 t2i + 6 edits+ python -I scripts/dev/compare-fast-modes.py --only fast,viggle6,official8 --cases 3++Writes <out>/report.html (side-by-side grid + timing table), results.json and the images.+Missing LoRAs and checkpoints (about 7 GB for all) are downloaded into Kokon's model folders+and checked against their SHA-256. official8 is another diffusion model, so it runs on a+second server after the first one.+"""++import argparse+import base64+import hashlib+import html+import io+import json+import math+import os+import re+import shutil+import statistics+import subprocess+import sys+import time+import urllib.request+from pathlib import Path++from PIL import Image++LOCAL = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData/Local")) / "KokonData"+LOG = LOCAL / "logs" / "service.log"+LORA_DIR = LOCAL / "sdcpp" / "models" / "loras"+PORT = 39160++# ---------------------------------------------------------------------------------------+# Few-step schedules+# ---------------------------------------------------------------------------------------+++def dynamic_shift(nodes, w, h, base_shift=0.5, max_shift=0.9, base_seq=256, max_seq=8192):+ """Timesteps under diffusers' dynamic exponential shift (mu linear in the token count,+ extrapolated past max_seq), then 0. Same as `planner::turbo_sigmas` in the app."""+ tokens = (w // 16) * (h // 16)+ e = math.exp(base_shift + (max_shift - base_shift) * (tokens - base_seq) / (max_seq - base_seq))+ return [e / (e + 1 / t - 1) for t in nodes] + [0.0]+++def tez_sigmas(w, h):+ # Sarvam Tez: {1, s, 0} with s = index 20 of the base 40-step schedule (stretch 0.02);+ # the model card's value at 1024², the only size the LoRA variants run at here.+ assert (w, h) == (1024, 1024), "tez sigmas are only known for 1024x1024"+ return [1.0, 0.65667, 0.0]+++HF = "https://huggingface.co"+MODELS_DIR = LOCAL / "sdcpp" / "models" / "qwen21"++# name -> settings. `area` = working pixels; `lora` = file in LORA_DIR, `model` = another+# diffusion model in MODELS_DIR (run on a separate server), each with url/size/sha256 to+# download it; `sigmas(w, h)` = exact schedule (None: the server's default for `steps`);+# `t2i_only` = skipped for edits.+VARIANTS = {+ "balanced": {"label": "Balanced (1.5K, 20 steps)", "area": 1536 * 1536, "steps": 20},+ "fast": {"label": "Fast (1 MP, 20 steps)", "area": 1024 * 1024, "steps": 20},+ "viggle6": {+ "label": "Viggle turbo v0.3 (6 steps)",+ "area": 1024 * 1024,+ "lora": "viggle-turbo-v0.3-r128.safetensors",+ "url": "https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo/resolve/main/Qwen-Image-2.1-viggle-turbo-v0.3-6step-lora-r128.safetensors",+ "size": 679_604_800,+ "sha256": "0c98591700346f9777051d4e6fa29aa94519abec0d85b1f1f672a2a3db8c94b3",+ "sigmas": lambda w, h: dynamic_shift([1.0, 0.9375, 0.875, 0.75, 0.5, 0.25], w, h),+ },+ "turbo8": {+ "label": "Turbo8 LoRA (8 steps)",+ "area": 1024 * 1024,+ "lora": "turbo8_lora_step2500.safetensors",+ "url": f"{HF}/chriswritescode/Turbo8-LoRA-Qwen-Image-2.1/resolve/main/turbo8_lora_step2500.safetensors",+ "size": 1_359_148_744,+ "sha256": "a0b7a7634ff2f82ccbe209e16b0ba19b25e2d9e18624d89edc490503b6a75d39",+ "sigmas": lambda w, h: dynamic_shift([1 - i / 8 for i in range(8)], w, h),+ },+ "pruna8": {+ "label": "Pruna 8-step LoRA v0.1",+ "area": 1024 * 1024,+ "lora": "p_qwen_image_2.1_8step_v0.1.safetensors",+ "url": f"{HF}/PrunaAI/Pruna-Qwen-Image-2.1/resolve/main/p_qwen_image_2.1_8step_v0.1.safetensors",+ "size": 335_606_104,+ "sha256": "f0865d68b02511a3a0ed232d9d1aa99cac3a94166f574b38bcbab1a7a297bb15",+ # r64 with alpha 128 only in the file metadata, which sd.cpp ignores (scale 1); 2.0+ # matches diffusers' strength 1.+ "multiplier": 2.0,+ "sigmas": lambda w, h: [1, 14 / 15, 6 / 7, 10 / 13, 2 / 3, 6 / 11, 0.4, 2 / 9, 0.0],+ },+ "tez2": {+ "label": "Sarvam Tez LoRA (2 steps, t2i only)",+ "area": 1024 * 1024,+ "t2i_only": True,+ "lora": "Qwen-Image-2.1-sarvam-tez-2step-lora-r256.safetensors",+ "url": f"{HF}/sarvamaigc/Qwen-Image-2.1-Sarvam-Tez/resolve/main/Qwen-Image-2.1-sarvam-tez-2step-lora-r256.safetensors",+ "size": 1_342_238_184,+ "sha256": "1f964e6e9621c973a13868d277f3747a7c8cb0682bc432835679b4063392682a",+ "sigmas": tez_sigmas,+ },+ "official8": {+ "label": "Official Qwen-Image-2.1-Turbo Q4_K (8 steps)",+ "area": 1024 * 1024,+ "model": "qwen-image-2.1-turbo-Q4_K.gguf",+ "url": f"{HF}/DogukanUrker/Qwen-Image-2.1-Turbo-GGUF/resolve/main/qwen-image-2.1-turbo-Q4_K.gguf",+ "size": 4_050_916_384,+ "sha256": "f8d5611b495848b632f8ae14dc7da6525fe2796eb80998f8dee5e04d0a2f69eb",+ # Fixed schedule from the checkpoint's model_index.json (no dynamic shift).+ "sigmas": lambda w, h: [1.0, 0.978453, 0.95418, 0.926626, 0.89508, 0.845148, 0.704534, 0.414568, 0.0],+ },+}+# The same official Turbo at higher precision (quantization A/B; each is its own server run).+for _q, _size, _sha in [+ ("Q6_K", 5_876_562_976, "a61e8bfe4318a2df2a2321bfaa23796eb157d184fa53200539507cea5555658d"),+ ("Q8_0", 7_591_558_176, "228d7931adade6cdd9ce2c8fcba0fc2a54552679efaef2dd34b83413750c8c76"),+]:+ VARIANTS[f"official8_{_q.lower()}"] = {+ **VARIANTS["official8"],+ "label": f"Official Turbo {_q} (8 steps)",+ "model": f"qwen-image-2.1-turbo-{_q}.gguf",+ "url": f"{HF}/DogukanUrker/Qwen-Image-2.1-Turbo-GGUF/resolve/main/qwen-image-2.1-turbo-{_q}.gguf",+ "size": _size,+ "sha256": _sha,+ }++# ---------------------------------------------------------------------------------------+# Test cases: 10 text-to-image prompts, then edits of the Fast results (so every variant edits+# the same input) and one two-image combine.+# ---------------------------------------------------------------------------------------++T2I = [+ ("portrait", "Close-up portrait of an elderly fisherman with a weathered face and a grey beard, soft window light, shallow depth of field, photorealistic"),+ ("poster", 'A vintage travel poster for Lisbon with the title "LISBOA" in large bold letters and the subtitle "City of Seven Hills" below, yellow tram, sunset colours'),+ ("landscape", "Misty pine forest in the mountains at sunrise, a lake reflecting the peaks, golden light, ultra-detailed landscape photograph"),+ ("product", "Studio product photo of a matte black wireless headphone on a marble pedestal, soft shadows, minimal beige background"),+ ("animal", "A red fox sitting in fresh snow, looking at the camera, fine fur detail, telephoto wildlife photograph"),+ ("architecture", "Interior of a modern library with curved wooden shelves, skylights, people reading, wide-angle architectural photo"),+ ("illustration", "Cozy watercolor illustration of a small bakery on a rainy street at night, warm light in the windows, a cat on the doorstep"),+ ("food", "Overhead photo of a Neapolitan pizza margherita on a wooden table, basil leaves, flour dust, natural light"),+ ("signage", 'A small café chalkboard menu on the sidewalk that reads "TODAY: Espresso 1.20, Cappuccino 1.80, Cornetto 1.50" in neat chalk handwriting'),+ ("hands", "Two hands of a potter shaping a clay bowl on a spinning wheel, workshop background, detailed fingers, documentary photo"),+]++EDITS = [+ ("portrait", "Change the background to a busy harbour with boats, keep the man identical"),+ ("poster", 'Change the title text to "PORTO" and make the tram blue'),+ ("landscape", "Make it a winter scene with snow on the trees and a frozen lake"),+ ("product", "Change the headphone colour to bright red and add a small plant next to the pedestal"),+ ("animal", "Turn the fox into an oil painting in the style of Van Gogh"),+ ("food", "Remove the basil leaves and add slices of salami"),+]++COMBINE = ("Put the fox from image 1 in front of the bakery from image 2, matching the watercolor style", ["animal", "illustration"])+++def dims(aspect, area, align=32):+ w = math.sqrt(area * aspect)+ h = w / aspect+ return max(align, round(w / align) * align), max(align, round(h / align) * align)+++# ---------------------------------------------------------------------------------------+# Server+# ---------------------------------------------------------------------------------------+++def kokon_server_args(model=None):+ """sd-server command of Kokon's last launch, from the service log."""+ if not LOG.is_file():+ sys.exit(f"No Kokon log at {LOG}: start Kokon once and generate an image first.")+ lines = [l for l in LOG.read_text(encoding="utf-8", errors="replace").splitlines() if "qls_core::process: starting " in l and "sd-server" in l]+ if not lines:+ sys.exit("The Kokon log has no sd-server launch line; generate one image in Kokon first.")+ cmd = lines[-1].split("qls_core::process: starting ", 1)[1].strip()+ exe, _, rest = cmd.partition(" --")+ args = []+ # Flags start with " --"; a value may contain spaces (paths).+ for part in ("--" + rest).split(" --"):+ part = part.strip()+ if not part:+ continue+ part = part if part.startswith("--") else "--" + part+ name, _, value = part.partition(" ")+ args.append(name)+ if value:+ args.append(value)+ # Our own port, and the LoRA folder.+ i = args.index("--listen-port")+ args[i + 1] = str(PORT)+ if "--lora-model-dir" not in args:+ args += ["--lora-model-dir", str(LORA_DIR)]+ if model:+ args[args.index("--diffusion-model") + 1] = str(MODELS_DIR / model)+ return exe.strip(), args+++def http(method, path, body=None, timeout=60):+ req = urllib.request.Request(f"http://127.0.0.1:{PORT}{path}", method=method, data=None if body is None else json.dumps(body).encode(), headers={"Content-Type": "application/json"})+ with urllib.request.urlopen(req, timeout=timeout) as r:+ return json.loads(r.read() or b"{}")+++def start_server(out, model=None):+ exe, args = kokon_server_args(model)+ print("starting", exe, " ".join(args))+ log = open(out / f"sd-server-{model or 'kokon'}.log", "w", encoding="utf-8", errors="replace")+ proc = subprocess.Popen([exe, *args], cwd=str(Path(exe).parent), stdout=log, stderr=subprocess.STDOUT)+ for _ in range(600):+ if proc.poll() is not None:+ sys.exit(f"sd-server exited (code {proc.returncode}); see {log.name}. Is Kokon still running?")+ try:+ caps = http("GET", "/sdcpp/v1/capabilities", timeout=5)+ return proc, caps+ except Exception:+ time.sleep(1)+ proc.kill()+ sys.exit("sd-server did not come up in 10 minutes.")+++def generate(body):+ """Submit, wait, return (PIL image, seconds from submit to result)."""+ t0 = time.perf_counter()+ job = http("POST", "/sdcpp/v1/img_gen", body)+ while True:+ j = http("GET", f"/sdcpp/v1/jobs/{job['id']}")+ if j["status"] == "completed":+ img = Image.open(io.BytesIO(base64.b64decode(j["result"]["images"][0]["b64_json"]))).convert("RGB")+ return img, time.perf_counter() - t0+ if j["status"] in ("failed", "cancelled"):+ raise RuntimeError(json.dumps(j.get("error")))+ time.sleep(0.5)+++def b64png(img):+ buf = io.BytesIO()+ img.save(buf, "PNG")+ return base64.b64encode(buf.getvalue()).decode()+++def request(v, prompt, seed, w, h, refs=()):+ sp = {"sample_method": "euler", "sample_steps": v.get("steps", 20), "guidance": {"txt_cfg": 1.0}}+ if v.get("sigmas"):+ sp["custom_sigmas"] = v["sigmas"](w, h)+ sp["sample_steps"] = len(sp["custom_sigmas"]) - 1+ body = {+ "prompt": prompt, "negative_prompt": "", "width": w, "height": h, "seed": seed, "batch_count": 1,+ "sample_params": sp, "output_format": "png", "embed_image_metadata": False,+ }+ if refs:+ # References at the working size, as Kokon sends them (no server-side transforms).+ body["ref_images"] = [b64png(r.resize(dims(r.width / r.height, w * h), Image.LANCZOS)) for r in refs]+ body["image_preprocess"] = ["target=ref,mode=none"]+ if v.get("lora"):+ body["lora"] = [{"path": v["lora"], "multiplier": v.get("multiplier", 1.0)}]+ return body+++# ---------------------------------------------------------------------------------------+# LoRA files+# ---------------------------------------------------------------------------------------+++def ensure_files(v):+ if v.get("lora"):+ dest = LORA_DIR / v["lora"]+ elif v.get("model"):+ dest = MODELS_DIR / v["model"]+ else:+ return+ if dest.is_file() and dest.stat().st_size == v["size"]:+ return+ dest.parent.mkdir(parents=True, exist_ok=True)+ # The copy from earlier sd.cpp tests, if it is there.+ old = Path(r"C:\AI\sdcpp\models\loras") / dest.name+ if old.is_file() and old.stat().st_size == v["size"]:+ print(f"copying {old}")+ shutil.copyfile(old, dest)+ return+ print(f"downloading {v['url']} ({v['size'] / 1e6:.0f} MB)")+ tmp = dest.with_suffix(".part")+ h = hashlib.sha256()+ with urllib.request.urlopen(v["url"]) as r, open(tmp, "wb") as f:+ while chunk := r.read(1 << 20):+ h.update(chunk)+ f.write(chunk)+ if h.hexdigest() != v["sha256"]:+ tmp.unlink()+ sys.exit(f"checksum mismatch for {dest.name}")+ tmp.replace(dest)+++# ---------------------------------------------------------------------------------------+# Report+# ---------------------------------------------------------------------------------------+++def report(out, names, results):+ by_case = {}+ for r in results:+ by_case.setdefault((r["kind"], r["case"]), {})[r["variant"]] = r+ rows = []+ for (kind, case), cells in by_case.items():+ prompt = next(iter(cells.values()))["prompt"]+ tds = []+ for n in names:+ r = cells.get(n)+ if not r:+ tds.append("<td>–</td>")+ elif r.get("error"):+ tds.append(f"<td class=err>{html.escape(r['error'][:200])}</td>")+ else:+ tds.append(f'<td><a href="{r["file"]}"><img src="{r["file"]}" loading=lazy></a><div>{r["seconds"]:.1f} s · {r["width"]}×{r["height"]}</div></td>')+ rows.append(f"<tr><th><b>{kind}: {case}</b><p>{html.escape(prompt)}</p></th>{''.join(tds)}</tr>")+ summary = []+ for n in names:+ for kind in ("t2i", "edit"):+ t = [r["seconds"] for r in results if r["variant"] == n and r["kind"] == kind and not r.get("error")]+ if t:+ summary.append(f"<tr><td>{html.escape(VARIANTS[n]['label'])}</td><td>{kind}</td><td>{len(t)}</td><td>{statistics.median(t):.1f} s</td><td>{statistics.mean(t):.1f} s</td></tr>")+ head = "".join(f"<th>{html.escape(VARIANTS[n]['label'])}</th>" for n in names)+ page = f"""<!doctype html><meta charset=utf-8><title>Kokon fast modes</title>+<style>body{{font:14px system-ui;margin:16px;background:#111;color:#ddd}}table{{border-collapse:collapse}}+td,th{{border:1px solid #333;padding:6px;vertical-align:top;text-align:left}}img{{width:300px;display:block}}+th p{{font-weight:normal;max-width:220px;color:#aaa}}.err{{color:#f77;max-width:300px}}</style>+<h1>Same-seed comparison</h1><p>Time = submit to result (encode + sampling + decode), one job at a time; the first job also loads the models.</p>+<table><tr><th>Variant</th><th>Mode</th><th>n</th><th>Median</th><th>Mean</th></tr>{''.join(summary)}</table><br>+<table><tr><th>Case</th>{head}</tr>{''.join(rows)}</table>"""+ (out / "report.html").write_text(page, encoding="utf-8")+++def main():+ ap = argparse.ArgumentParser()+ ap.add_argument("--out", default=str(Path.home() / "Desktop" / "kokon-fast-compare"))+ ap.add_argument("--only", help="comma-separated variants (default: all)")+ ap.add_argument("--cases", type=int, default=len(T2I), help="text-to-image cases to run (edits use the first ones)")+ ap.add_argument("--seed", type=int, default=1234)+ a = ap.parse_args()+ names = a.only.split(",") if a.only else list(VARIANTS)+ for n in names:+ if n not in VARIANTS:+ sys.exit(f"unknown variant {n}; known: {', '.join(VARIANTS)}")+ out = Path(a.out)+ out.mkdir(parents=True, exist_ok=True)+ LORA_DIR.mkdir(parents=True, exist_ok=True)+ for n in names:+ ensure_files(VARIANTS[n])+ results = []++ def run(kind, case, prompt, seed, n, aspect=1.0, refs=()):+ v = VARIANTS[n]+ w, h = dims(aspect, v["area"])+ name = f"{kind}-{case}-{n}.png"+ try:+ img, secs = generate(request(v, prompt, seed, w, h, refs))+ img.save(out / name)+ r = {"file": name, "seconds": round(secs, 2), "width": w, "height": h}+ print(f"{kind:4} {case:12} {n:10} {secs:6.1f} s")+ except Exception as e:+ r = {"error": str(e)}+ print(f"{kind:4} {case:12} {n:10} FAILED {e}")+ results.append({"kind": kind, "case": case, "variant": n, "prompt": prompt, "seed": seed, **r})+ (out / "results.json").write_text(json.dumps(results, indent=1), encoding="utf-8")+ report(out, names, results)++ cases = T2I[: a.cases]+ # One server per diffusion model: Kokon's first (it also makes the edit inputs), then each+ # other checkpoint.+ for model in [None] + sorted({VARIANTS[n]["model"] for n in names if VARIANTS[n].get("model")}):+ members = [n for n in names if VARIANTS[n].get("model") == model]+ proc, caps = start_server(out, model)+ try:+ known = {l.get("path") for l in caps.get("loras", [])}+ for n in members:+ if VARIANTS[n].get("lora") and VARIANTS[n]["lora"] not in known:+ print(f"warning: the server does not list {VARIANTS[n]['lora']} (loras: {sorted(known)})")+ # Warm-up so the first measured job does not pay for loading the models.+ generate(request(VARIANTS[members[0]] if members else VARIANTS["fast"], "warm-up", 1, 1024, 1024))+ for i, (case, prompt) in enumerate(cases):+ for n in members:+ run("t2i", case, prompt, a.seed + i, n)+ # Edits start from the Fast result (the full model at 1 MP), the same input for all.+ base = {}+ for i, (case, prompt) in enumerate(cases):+ p = out / f"t2i-{case}-fast.png"+ if not p.is_file() and model is None:+ img, _ = generate(request(VARIANTS["fast"], prompt, a.seed + i, 1024, 1024))+ img.save(p)+ if p.is_file():+ base[case] = Image.open(p).convert("RGB")+ editors = [n for n in members if not VARIANTS[n].get("t2i_only")]+ for i, (case, prompt) in enumerate(EDITS):+ if case in base:+ for n in editors:+ run("edit", case, prompt, a.seed + 100 + i, n, refs=[base[case]])+ prompt, pair = COMBINE+ if all(c in base for c in pair):+ for n in editors:+ run("edit", "combine", prompt, a.seed + 200, n, refs=[base[c] for c in pair])+ finally:+ proc.terminate()+ proc.wait(timeout=60)+ print(f"\nReport: {out / 'report.html'}")+++if __name__ == "__main__":+ main()diff --git a/src/components/Composer.tsx b/src/components/Composer.tsxindex 9003b14..fb77c8d 100644--- a/src/components/Composer.tsx+++ b/src/components/Composer.tsx@@ -12,8 +12,9 @@ import { AspectGrid, pickAspect, RatioIcon, resolutionLabel, ResolutionMenu } frimport { Option, Popover, Seg } from "./ui";const QUALITY: { value: Quality; label: string; sub: string }[] = [+ { value: "turbo", label: "Turbo", sub: "~1 MP, 8 steps · fastest, recommended" },{ value: "fast", label: "Fast", sub: "~1 MP, 20 steps" },- { value: "balanced", label: "Balanced", sub: "~1.5K, 20 steps · recommended" },+ { value: "balanced", label: "Balanced", sub: "~1.5K, 20 steps" },{ value: "quality", label: "Quality", sub: "native 2K, 20 steps · slower" },{ value: "ultra", label: "Ultra", sub: "native 2K, 40 steps · slowest" },];@@ -284,6 +285,7 @@ function usePlanPreview(): { plan: Plan | null; error: string | null } {export function Composer() {const c = useStore((s) => s.composer);+ const turboAvailable = useStore((s) => s.status?.turbo?.available ?? false);const hasProject = useStore((s) => s.session.length > 0);const { plan, error } = usePlanPreview();const taRef = useRef<HTMLTextAreaElement>(null);@@ -405,7 +407,7 @@ export function Composer() {)}>{(close) =>- QUALITY.map((q) => <Option key={q.value} selected={c.quality === q.value} label={q.label} sub={q.sub} onClick={() => (updateComposer({ quality: q.value }), close())} />)+ QUALITY.map((q) => <Option key={q.value} selected={c.quality === q.value} label={q.label} sub={q.value === "turbo" && !turboAvailable ? "model not installed: runs as Balanced" : q.sub} onClick={() => (updateComposer({ quality: q.value }), close())} />)}</Popover>diff --git a/src/components/Setup.tsx b/src/components/Setup.tsxindex 69d21c5..1d41f00 100644--- a/src/components/Setup.tsx+++ b/src/components/Setup.tsx@@ -165,7 +165,7 @@ export function Setup() {const running = inst?.running ?? false;// While (or after) installing this preset, show the live list; otherwise what is on disk.const live = !!inst && inst.preset === preset && inst.items.length > 0 && (running || inst.items.some((i) => i.state !== "pending" && i.state !== "present"));- const items = (live ? inst!.items : chosen?.files ?? []).filter((i) => upscaler || i.kind !== "optional" || live);+ const items = (live ? inst!.items : chosen?.files ?? []).filter((i) => i.kind !== "optional" || live || upscaler);const missing = items.filter((i) => i.state !== "present" && i.state !== "done");const failed = items.filter((i) => i.state === "failed");const paused = !running && items.some((i) => i.state === "cancelled" || (i.state === "pending" && i.received > 0));@@ -177,6 +177,8 @@ export function Setup() {const rate = inst?.bytes_per_sec ?? 0;const vram = hw?.vram_mib ?? null;const optionalMissing = chosen?.files.some((f) => f.kind === "optional" && f.state !== "present");+ // Wanted extras not on disk yet (e.g. the upscaler added after the first setup).+ const extrasMissing = missing.some((i) => i.kind === "optional");return (<div className="setup">@@ -209,10 +211,16 @@ export function Setup() {</div>)}{hw.gpu?.unified ? (- hw.gpu.memory_total_mib < 23 * 1024 && (+ hw.gpu.memory_total_mib < 23 * 1024 ? (<div className="setup-note">- With {gb(hw.gpu.memory_total_mib)} of unified memory Kokon runs in its lightest mode: model weights are read from disk as needed and images are made at about 1 megapixel. Expect several minutes per image; 24 GB or more is recommended. Close other apps while generating.+ With {gb(hw.gpu.memory_total_mib)} of unified memory Kokon works, but slowly: model weights are read from disk as needed and images are made at about 1 megapixel, which took about 10 minutes on an M2 Pro. Fast renders smaller and enlarges the result, so it is quicker. 32 GB or more and a Pro, Max or Ultra chip are recommended. Close other apps while generating.</div>+ ) : (+ hw.gpu.memory_total_mib < 31 * 1024 && (+ <div className="setup-note">+ With {gb(hw.gpu.memory_total_mib)} of unified memory expect several minutes per image. 32 GB or more and a Pro, Max or Ultra chip are recommended.+ </div>+ ))) : (<>@@ -341,7 +349,7 @@ export function Setup() {)}<div className="setup-actions">- {hw && !running && !paused && !presetInstalled && (+ {hw && !running && !paused && (!presetInstalled || extrasMissing) && (<button className="btn primary big" disabled={!chosen || lowSpace} onClick={install}><Download size={16} /> {failed.length ? "Try again" : `Install · ${formatBytes(toDownload)}`}</button>diff --git a/src/lib/logic.ts b/src/lib/logic.tsindex edbd875..b5912a8 100644--- a/src/lib/logic.ts+++ b/src/lib/logic.ts@@ -41,7 +41,7 @@ export const emptyComposer = (prefs?: Partial<Composer>): Composer => ({outpaint: null,mode: "auto",aspect: prefs?.aspect ?? "auto",- quality: prefs?.quality ?? "balanced",+ quality: prefs?.quality ?? "turbo",resolution: prefs?.resolution ?? "auto",customWidth: prefs?.customWidth ?? 1024,customHeight: prefs?.customHeight ?? 1024,diff --git a/src/lib/types.ts b/src/lib/types.tsindex 58abf44..a333163 100644--- a/src/lib/types.ts+++ b/src/lib/types.ts@@ -4,7 +4,7 @@ export type Mode = "auto" | "generate" | "edit" | "inpaint" | "outpaint" | "multexport type ResolvedMode = Exclude<Mode, "auto">;/** What an inpaint does in the painted area. */export type InpaintAction = "edit" | "remove" | "replace" | "add";-export type Quality = "fast" | "balanced" | "quality" | "ultra";+export type Quality = "fast" | "balanced" | "quality" | "ultra" | "turbo";export type ResolutionMode = "auto" | "source" | "1k" | "1.5k" | "2k" | "custom";export type OutputFormat = "png" | "jpeg" | "webp";export type Units = "pixels" | "percent";@@ -179,6 +179,7 @@ export interface StatusResponse {active_job: JobView | null;queue: { queued: number; jobs: JobView[] };upscaler?: { model: string; available: boolean; refine_mode: RefineMode };+ turbo?: { available: boolean };setup_complete: boolean;}