diff --git a/.gitignore b/.gitignore
index ecdc746..505be3f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -196,3 +196,7 @@ outputs/*
!outputs/
save_checkpoint.ipynb
repos/*
+app_demo.py
+ui/components_demo.py
+data_sampler_demo.py
+pipeline_ace_step_demo.py
diff --git a/README.md b/README.md
index caf8133..28e6e4d 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,114 @@
-# ACE-Step
+โจ ACE-Step โจ
+๐ต A Step Towards Music Generation Foundation Model ๐ต
+
+ Project |
+ Checkpoints |
+ Space Demo
+
+
+---
+
+ 
+
+
+## ๐ข News and Updates
+
+- ๐ 2025.05.06: Open source demo code and model
+- ๐ Open source training LoRA code
+- ๐ฎ Open source training ControlNet code
+
+
+## ๐๏ธ Architecture
+
+
+ 
+
+
+
+## ๐ Abstract
+
+We introduce ACE-Step, a novel open-source foundation model for music generation that addresses critical limitations in existing approaches, achieving state-of-the-art performance through a holistic architecture design. Current methods face inherent trade-offs among generation speed, musical coherence, and controllability: while LLM-based models (e.g., Yue, SongGen) excel in lyric alignment, they suffer from slow inference and structural artifacts; diffusion models (e.g., DiffRhythm) enable faster synthesis but lack long-range structural coherence.
+
+ACE-Step integrates advances in diffusion-based generation with Sana's Deep Compression AutoEncoder (DCAE) and a lightweight linear transformer, leveraging Mert and m-hubert to align semantic representations (REPA) during training for rapid convergence. Our model synthesizes 4-minute music in 20 seconds on an A100 GPUโ15ร faster than LLM-based baselinesโwhile achieving exceptional musical coherence and lyric alignment across metrics for melody, harmony, and rhythmic consistency. By preserving fine-grained acoustic details, ACE-Step supports sophisticated control mechanisms, including voice cloning, lyric-editing, remixing, and track generation (e.g., lyric2vocal or Singing2Accompaniment).
+
+We're not aiming to build yet another end-to-end text-to-music solution. Instead, our goal is to create a foundation model for the music AI spaceโone with a generic, fast, and efficient architecture that makes it easy to train sub-tasks on top of it. This enables the development of new tools that seamlessly integrate into the creative workflows of music artists, producers, and content creators.
+
+In a word, we are building Stable Diffusion Moment in the music.
+
+## โจ Features
+
+
+ 
+
+
+### ๐ฏ Baseline Quality
+
+#### ๐ Diverse Styles & Genres
+- ๐ธ Supports all mainstream music styles with various description formats including short tags, descriptive text, or use-case scenarios
+- ๐ท Capable of generating music across different genres with appropriate instrumentation and style
+
+#### ๐ Multiple Languages
+- ๐ฃ๏ธ Supports 19 languages with top 10 well-performing languages including:
+ - ๐บ๐ธ English, ๐จ๐ณ Chinese, ๐ท๐บ Russian, ๐ช๐ธ Spanish, ๐ฏ๐ต Japanese, ๐ฉ๐ช German, ๐ซ๐ท French, ๐ต๐น Portuguese, ๐ฎ๐น Italian, ๐ฐ๐ท Korean
+- โ ๏ธ Due to data imbalance, less common languages may underperform
+
+#### ๐ป Instrumental Styles
+- ๐น Supports various instrumental music generation across different genres and styles
+- ๐บ Capable of producing realistic instrumental tracks with appropriate timbre and expression for each instrument
+- ๐ผ Can generate complex arrangements with multiple instruments while maintaining musical coherence
+
+#### ๐ค Vocal Techniques
+- ๐๏ธ Capable of rendering various vocal styles and techniques with good quality
+- ๐ฃ๏ธ Supports different vocal expressions including various singing techniques and styles
+
+### ๐๏ธ Controllability
+
+#### ๐ Variations Generation
+- โ๏ธ Implemented using training-free, inference-time optimization techniques
+- ๐ Flow-matching model generates initial noise, then uses trigFlow's noise formula to add additional Gaussian noise
+- ๐๏ธ Adjustable mixing ratio between original initial noise and new Gaussian noise to control variation degree
+
+#### ๐จ Repainting
+- ๐๏ธ Implemented by adding noise to the target audio input and applying mask constraints during the ODE process
+- ๐ When input conditions change from the original generation, only specific aspects can be modified while preserving the rest
+- ๐ Can be combined with Variations Generation techniques to create localized variations in style, lyrics, or vocals
+
+#### โ๏ธ Lyric Editing
+- ๐ก Innovatively applies flow-edit technology to enable localized lyric modifications while preserving melody, vocals, and accompaniment
+- ๐ Works with both generated content and uploaded audio, greatly enhancing creative possibilities
+- โน๏ธ Current limitation: can only modify small segments of lyrics at once to avoid distortion, but multiple edits can be applied sequentially
+
+### ๐ Applications
+
+#### ๐ค Lyric2Vocal (LoRA)
+- ๐ Based on a LoRA fine-tuned on pure vocal data, allowing direct generation of vocal samples from lyrics
+- ๐ ๏ธ Offers numerous practical applications such as vocal demos, guide tracks, songwriting assistance, and vocal arrangement experimentation
+- โฑ๏ธ Provides a quick way to test how lyrics might sound when sung, helping songwriters iterate faster
+
+#### ๐ Text2Samples (LoRA)
+- ๐๏ธ Similar to Lyric2Vocal, but fine-tuned on pure instrumental and sample data
+- ๐ต Capable of generating conceptual music production samples from text descriptions
+- ๐งฐ Useful for quickly creating instrument loops, sound effects, and musical elements for production
+
+### ๐ฎ Coming Soon
+
+#### ๐ค RapMachine
+- ๐ฅ Fine-tuned on pure rap data to create an AI system specialized in rap generation
+- ๐ Expected capabilities include AI rap battles and narrative expression through rap
+- ๐ Rap has exceptional storytelling and expressive capabilities, offering extraordinary application potential
+
+#### ๐๏ธ StemGen
+- ๐๏ธ A controlnet-lora trained on multi-track data to generate individual instrument stems
+- ๐ฏ Takes a reference track and specified instrument (or instrument reference audio) as input
+- ๐น Outputs an instrument stem that complements the reference track, such as creating a piano accompaniment for a flute melody or adding jazz drums to a lead guitar
+
+#### ๐ค Singing2Accompaniment
+- ๐ The reverse process of StemGen, generating a mixed master track from a single vocal track
+- ๐ต Takes a vocal track and specified style as input to produce a complete vocal accompaniment
+- ๐ธ Creates full instrumental backing that complements the input vocals, making it easy to add professional-sounding accompaniment to any vocal recording
+
+## ๐ป Installation
-# Installation
```bash
conda create -n ace_step python==3.10
conda activate ace_step
@@ -8,7 +116,99 @@ pip install -r requirements.txt
conda install ffmpeg
```
-# Usage
+## ๐ Usage
+
+
+
+### ๐ Basic Usage
+
```bash
python app.py
```
+
+### โ๏ธ Advanced Usage
+
+```bash
+python app.py --checkpoint_path /path/to/checkpoint --port 7865 --device_id 0 --share --bf16
+```
+
+#### ๐ ๏ธ Command Line Arguments
+
+- `--checkpoint_path`: Path to the model checkpoint (default: downloads automatically)
+- `--port`: Port to run the Gradio server on (default: 7865)
+- `--device_id`: GPU device ID to use (default: 0)
+- `--share`: Enable Gradio sharing link (default: False)
+- `--bf16`: Use bfloat16 precision for faster inference (default: True)
+
+## ๐ฑ User Interface Guide
+
+The ACE-Step interface provides several tabs for different music generation and editing tasks:
+
+### ๐ Text2Music Tab
+
+1. **๐ Input Fields**:
+ - **๐ท๏ธ Tags**: Enter descriptive tags, genres, or scene descriptions separated by commas
+ - **๐ Lyrics**: Enter lyrics with structure tags like [verse], [chorus], and [bridge]
+ - **โฑ๏ธ Audio Duration**: Set the desired duration of the generated audio (-1 for random)
+
+2. **โ๏ธ Settings**:
+ - **๐ง Basic Settings**: Adjust inference steps, guidance scale, and seeds
+ - **๐ฌ Advanced Settings**: Fine-tune scheduler type, CFG type, ERG settings, and more
+
+3. **๐ Generation**: Click "Generate" to create music based on your inputs
+
+### ๐ Retake Tab
+
+- ๐ฒ Regenerate music with slight variations using different seeds
+- ๐๏ธ Adjust variance to control how much the retake differs from the original
+
+### ๐จ Repainting Tab
+
+- ๐๏ธ Selectively regenerate specific sections of the music
+- โฑ๏ธ Specify start and end times for the section to repaint
+- ๐ Choose the source audio (text2music output, last repaint, or upload)
+
+### โ๏ธ Edit Tab
+
+- ๐ Modify existing music by changing tags or lyrics
+- ๐๏ธ Choose between "only_lyrics" mode (preserves melody) or "remix" mode (changes melody)
+- ๐๏ธ Adjust edit parameters to control how much of the original is preserved
+
+### ๐ Extend Tab
+
+- โ Add music to the beginning or end of an existing piece
+- ๐ Specify left and right extension lengths
+- ๐ Choose the source audio to extend
+
+## ๐ฌ Technical Details
+
+ACE-Step uses a two-stage pipeline:
+
+1. **๐ Text Encoding**: Processes text descriptions and lyrics using a UMT5 encoder
+2. **๐ต Music Generation**: Uses a transformer-based diffusion model to generate music latents
+3. **๐ Audio Decoding**: Converts latents to audio using a music DCAE (Diffusion Convolutional Auto-Encoder)
+
+The system supports various guidance techniques:
+- ๐งญ Classifier-Free Guidance (CFG)
+- ๐ Adaptive Guidance (APG)
+- ๐ Entropy Rectifying Guidance (ERG)
+
+## ๐ Examples
+
+The `examples/input_params` directory contains sample input parameters that can be used as references for generating music.
+
+## ๐ License
+
+[License information]
+
+## ๐ Acknowledgements
+
+This project is co-led by ACE Studio and StepFun.
+
+
+## ๐ Citation
+
+If you find this project useful for your research, please consider citing:
+
+```bibtex
+[Citation information]
diff --git a/fig/ACE-Step_framework.png b/fig/ACE-Step_framework.png
new file mode 100644
index 0000000..a0749e2
Binary files /dev/null and b/fig/ACE-Step_framework.png differ
diff --git a/fig/acestudio_logo.png b/fig/acestudio_logo.png
new file mode 100644
index 0000000..abf4cb2
Binary files /dev/null and b/fig/acestudio_logo.png differ
diff --git a/fig/application_map.png b/fig/application_map.png
new file mode 100644
index 0000000..5beb4d2
Binary files /dev/null and b/fig/application_map.png differ
diff --git a/fig/demo_interface.png b/fig/demo_interface.png
new file mode 100644
index 0000000..3c5f141
Binary files /dev/null and b/fig/demo_interface.png differ
diff --git a/fig/orgnization_logos.png b/fig/orgnization_logos.png
new file mode 100644
index 0000000..496975b
Binary files /dev/null and b/fig/orgnization_logos.png differ
diff --git a/fig/stepfun_logo.png b/fig/stepfun_logo.png
new file mode 100644
index 0000000..966e02a
Binary files /dev/null and b/fig/stepfun_logo.png differ