https://github.com/xororz/local-dream
Run Stable Diffusion on Android Devices with Snapdragon NPU acceleration. Also supports CPU/GPU inference.
https://github.com/xororz/local-dream
img2img inpainting stable-diffusion stable-diffusion-android txt2img
Last synced: 2 months ago
JSON representation
Run Stable Diffusion on Android Devices with Snapdragon NPU acceleration. Also supports CPU/GPU inference.
- Host: GitHub
- URL: https://github.com/xororz/local-dream
- Owner: xororz
- License: other
- Created: 2025-01-25T07:14:07.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-10-06T14:52:44.000Z (9 months ago)
- Last Synced: 2025-10-06T16:33:29.362Z (9 months ago)
- Topics: img2img, inpainting, stable-diffusion, stable-diffusion-android, txt2img
- Language: Kotlin
- Homepage: https://play.google.com/store/apps/details?id=io.github.xororz.localdream
- Size: 12.6 MB
- Stars: 512
- Watchers: 9
- Forks: 22
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Local Dream 
**Android Stable Diffusion with Snapdragon NPU acceleration**
_Also supports CPU/GPU inference_
## About this Repo
This project is **now open sourced and completely free**. Hope you enjoy it!
If you like it, please consider [sponsor](https://github.com/xororz/local-dream?tab=readme-ov-file#-support-this-project) this project.
> [!NOTE]
> Currently focus on SD1.5 and SDXL models. SD2.1 models are no longer maintained due to poor quality and not popular. SDXL models are only available for Snapdragon 8 Gen 3, Snapdragon 8 Elite and Snapdragon 8 Elite Gen 5/ 8 Gen 5.
>
> Most users don't get how to properly use highres mode for SD1.5. Please check [here](#npu-high-resolution-support).
>
> Now you can import your own NPU models converted using our easy-to-follow [NPU Model Conversion Guide](https://github.com/xororz/local-dream/tree/master/convert). And you can also download some pre-converted models from [xororz/sd-qnn](https://huggingface.co/xororz/sd-qnn/tree/main) or [xororz/sdxl-qnn](https://huggingface.co/xororz/sdxl-qnn/tree/main) or [Mr-J-369](https://huggingface.co/Mr-J-369). For SD1.5 models, download `_min` if you are using non-flagship chips. Download `_8gen1` if you are using 8gen1. Download `_8gen2` if you are using 8gen2/3/4/5. We recommend checking the instructions on the original model page to set up prompts and parameters.
>
> You can join our [telegram group](https://t.me/local_dream) for discussion or help with testing.
## 🚀 Quick Start
1. **Download**: Get the APK from [Releases](https://github.com/xororz/local-dream/releases) or [Google Play](https://play.google.com/store/apps/details?id=io.github.xororz.localdream)(NSFW filtered)
2. **Install**: Install the APK on your Android device
3. **Select Models**: Open the app and download the model(s) you want to use
## ✨ Features
- 🎨 **txt2img** - Generate images from text descriptions
- 🖼️ **img2img** - Transform existing images
- 🎭 **inpaint** - Redraw selected areas of images
- **custom models** - Import your own SD1.5 models for CPU (in app), SD1.5 and SDXL for NPU (follow [conversion guide](https://github.com/xororz/local-dream/tree/master/convert)). You can get some pre-converted models from [xororz/sd-qnn](https://huggingface.co/xororz/sd-qnn/tree/main) or [xororz/sdxl-qnn](https://huggingface.co/xororz/sdxl-qnn/tree/main) or [Mr-J-369](https://huggingface.co/Mr-J-369)
- **lora support** - Support adding LoRA weights to custom CPU models when importing.
- **prompt weights** - Emphasize certain words in prompts. E.g., `(masterpiece:1.5)`. Same format as [Automatic1111](https://github.com/AUTOMATIC1111/stable-diffusion-webui)
- **embeddings** - Support for custom embeddings like [EasyNegative](https://civitai.com/models/7808/easynegative). SafeTensor format is required. Convert `pt` to `safetensors` using [this](https://chino.icu/local-dream/pt2sf.py)
- **upscalers** - 4x upscaling with [realesrgan_x4plus_anime_6b](https://github.com/xinntao/Real-ESRGAN/) and [4x-UltraSharpV2_Lite](https://huggingface.co/Kim2091/UltraSharpV2)
## 🔧 Build Instructions
> **Note**: Building on Linux/WSL is recommended. Other platforms are not verified.
### Prerequisites
The following tools are required for building:
- **Rust** - Install [rustup](https://rustup.rs/), then run:
```bash
# rustup default stable
rustup default 1.84.0 # Please use 1.84.0 for compatibility. Newer versions may cause build failures.
rustup target add aarch64-linux-android
```
- **Ninja** - Build system
- **CMake** - Build configuration
### 1. Clone Repository
```bash
git clone --recursive https://github.com/xororz/local-dream.git
```
### 2. Prepare SDKs
1. **Download QNN SDK**: Get [QNN_SDK_2.39](https://apigwx-aws.qualcomm.com/qsc/public/v1/api/download/software/sdks/Qualcomm_AI_Runtime_Community/All/2.39.0.250926/v2.39.0.250926.zip) and extract
2. **Download Android NDK**: Get [Android NDK](https://developer.android.com/ndk/downloads) and extract
3. **Configure paths**:
- Update `QNN_SDK_ROOT` in `app/src/main/cpp/CMakeLists.txt`
- Update `ANDROID_NDK_ROOT` in `app/src/main/cpp/CMakePresets.json`
### 3. Build Libraries
**Linux**
```bash
cd app/src/main/cpp/
bash ./build.sh
```
Windows
```powershell
# Install dependencies if needed:
# winget install Kitware.CMake
# winget install Ninja-build.Ninja
# winget install Rustlang.Rustup
cd app\src\main\cpp\
# Convert patch file (install dos2unix if needed: winget install -e --id waterlan.dos2unix)
dos2unix SampleApp.patch
.\build.bat
```
macOS
```bash
# Install dependencies with Homebrew:
# brew install cmake rust ninja
# Fix CMake version compatibility
sed -i '' '2s/$/ -DCMAKE_POLICY_VERSION_MINIMUM=3.5/' build.sh
bash ./build.sh
```
### 4. Build APK
Open this project in Android Studio and navigate to:
**Build → Generate App Bundles or APKs → Generate APKs**
## Technical Implementation
### NPU Acceleration
- **SDK**: Qualcomm QNN SDK leveraging Hexagon NPU
- **Quantization**: W8A16 static quantization for optimal performance
- **Resolution**: For SD1.5, fixed 512×512 base model shape, more shapes available using patches. For SDXL, fixed 1024x1024 model shape
- **Performance**: Extremely fast inference speed
### CPU/GPU Inference
- **Framework**: Powered by MNN framework
- **Quantization**: W8 dynamic quantization
- **Resolution**: Flexible sizes (128×128, 256×256, 384×384, 512×512)
- **Performance**: Moderate speed with high compatibility
## NPU High Resolution Support
> [!IMPORTANT]
> Please note that quantized high-resolution(>768x768) SD1.5 models may produce images with poor layout. We recommend first generating at 512 resolution (optionally you can upscale it), then using the high-resolution model for img2img (which is essentially Highres.fix). The suggested img2img denoise_strength is around 0.8. After that, you can get images with better layout and details.
## Device Compatibility
### NPU Acceleration Support
SD1.5 compatible with devices featuring:
- **Snapdragon 8 Gen 1/8+ Gen 1**
- **Snapdragon 8 Gen 2**
- **Snapdragon 8 Gen 3**
- **Snapdragon 8 Elite**
- **Snapdragon 8 Elite Gen 5/8 Gen 5**
- Non-flagship chips with Hexagon V68 or above (e.g., Snapdragon 7 Gen 1, 8s Gen 3)
SDXL compatible with devices featuring:
- **Snapdragon 8 Gen 3**
- **Snapdragon 8 Elite**
- **Snapdragon 8 Elite Gen 5/8 Gen 5**
> **Note**: Other devices cannot download NPU models
### CPU/GPU Support
- **RAM Requirement**: ~2GB available memory
- **Compatibility**: Most Android devices from recent years
## Available Models
The following models are built-in and can be downloaded directly in the app:
| Model | Type | CPU/GPU | NPU | Clip Skip | Source |
| -------------------- | ----- | :-----: | :-: | :-------: | ------------------------------------------------------------------------------- |
| **SDXL Base 1.0** | SDXL | ❌ | ✅ | - | [HuggingFace](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) |
| **Illustrious v16** | SDXL | ❌ | ✅ | - | [CivitAI](https://civitai.com/models/827184/wai-illustrious-sdxl) |
| **AnythingV5** | SD1.5 | ✅ | ✅ | 2 | [CivitAI](https://civitai.com/models/9409?modelVersionId=30163) |
| **ChilloutMix** | SD1.5 | ✅ | ✅ | 1 | [CivitAI](https://civitai.com/models/6424/chilloutmix?modelVersionId=11732) |
| **Absolute Reality** | SD1.5 | ✅ | ✅ | 2 | [CivitAI](https://civitai.com/models/81458?modelVersionId=132760) |
| **QteaMix** | SD1.5 | ✅ | ✅ | 2 | [CivitAI](https://civitai.com/models/50696/qteamix-q?modelVersionId=94654) |
| **CuteYukiMix** | SD1.5 | ✅ | ✅ | 2 | [CivitAI](https://civitai.com/models/28169?modelVersionId=265102) |
## 🎲 Seed Settings
Custom seed support for reproducible image generation:
- **CPU Mode**: Seeds guarantee identical results across different devices with same parameters
- **GPU Mode**: Results may differ from CPU mode and can vary between different devices
- **NPU Mode**: Seeds ensure consistent results only on devices with identical chipsets
## Credits & Acknowledgments
### C++ Libraries
- **[Qualcomm QNN SDK](https://www.qualcomm.com/developer/software/neural-processing-sdk-for-ai)** - NPU model execution
- **[alibaba/MNN](https://github.com/alibaba/MNN/)** - CPU model execution
- **[xtensor-stack](https://github.com/xtensor-stack)** - Tensor operations & scheduling
- **[mlc-ai/tokenizers-cpp](https://github.com/mlc-ai/tokenizers-cpp)** - Text tokenization
- **[yhirose/cpp-httplib](https://github.com/yhirose/cpp-httplib)** - HTTP server
- **[nothings/stb](https://github.com/nothings/stb)** - Image processing
- **[facebook/zstd](https://github.com/facebook/zstd)** - Model compression
- **[nlohmann/json](https://github.com/nlohmann/json)** - JSON processing
### Android Libraries
- **[square/okhttp](https://github.com/square/okhttp)** - HTTP client
- **[coil-kt/coil](https://github.com/coil-kt/coil)** - Image loading & processing
- **[MoyuruAizawa/Cropify](https://github.com/MoyuruAizawa/Cropify)** - Image cropping
- **AOSP, Material Design, Jetpack Compose** - UI framework
### Models
- **[CompVis/stable-diffusion](https://github.com/CompVis/stable-diffusion)** and all other model creators
- **[xinntao/Real-ESRGAN](https://github.com/xinntao/Real-ESRGAN)** - Image upscaling
- **[Kim2091/UltraSharpV2](https://huggingface.co/Kim2091/UltraSharpV2)** - Image upscaling
- **[bhky/opennsfw2](https://github.com/bhky/opennsfw2)** - NSFW content filtering
---
## 💖 Support This Project
If you find Local Dream useful, please consider supporting its development:
### What Your Support Helps With:
- **Additional Models** - More AI model integrations
- **New Features** - Enhanced functionality and capabilities
- **Bug Fixes** - Continuous improvement and maintenance
Your sponsorship helps maintain and improve Local Dream for everyone!