From 42df4ae5875d3f5623522085f547988640da978b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 14:22:53 +0000
Subject: [PATCH 1/4] Initial plan


From 8dbee0f01cf537f298222624a4cb15ac6e69a71d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 14:26:05 +0000
Subject: [PATCH 2/4] Add model download functionality to run.sh and create
 download_models.py script

Co-authored-by: lmangani <1423657+lmangani@users.noreply.github.com>
---
 README.md          | 87 +++++++++++++++++++++++++++++++++++++++++-----
 download_models.py | 74 +++++++++++++++++++++++++++++++++++++++
 run.sh             | 35 +++++++++++++++++++
 3 files changed, 188 insertions(+), 8 deletions(-)
 create mode 100644 download_models.py

diff --git a/README.md b/README.md
index 65af2ee..b391162 100644
--- a/README.md
+++ b/README.md
@@ -57,9 +57,18 @@ python --version # 3.8 <= Python < 3.11
 
 ### MacOS One-click Dependency Installation & Startup Script
 By executing `run.sh` in the project root directory, you can configure the `venv` virtual environment, automatically install the required dependencies, and start the main program with one click.
+
+#### Quick Start (without models)
 ```bash
 sh ./run.sh
 ```
+This will start the application. Models will be checked and can be downloaded automatically when needed.
+
+#### First-time Setup (with automatic model download)
+```bash
+sh ./run.sh --download-models
+```
+This will download all required models before starting the application. This is recommended for first-time setup and may take several minutes depending on your internet connection.
 
 ### Manual Installation of Dependencies
 1. Install `pytorch` and its core dependencies, skip if already installed. Refer to: https://pytorch.org/get-started/locally/
@@ -75,12 +84,27 @@ sh ./run.sh
 ## Preparation of Other Files
 ### 1. Assets
 > RVC requires some models located in the `assets` folder for inference and training.
-#### Check/Download Automatically (Default)
+
+#### Automatic Download (Recommended)
+The easiest way to download all required models is using the included download script:
+```bash
+python download_models.py
+```
+
+Or use the run.sh script with the --download-models flag:
+```bash
+sh ./run.sh --download-models
+```
+
+#### Check/Download via Web Interface
 > By default, RVC can automatically check the integrity of the required resources when the main program starts.
 
 > Even if the resources are not complete, the program will continue to start.
 
-- If you want to download all resources, please add the `--update` parameter.
+- If you want to download all resources when starting the web interface, please add the `--update` parameter:
+  ```bash
+  python web.py --update
+  ```
 - If you want to skip the resource integrity check at startup, please add the `--nocheck` parameter.
 
 #### Download Manually
@@ -121,14 +145,26 @@ If you want to use the latest RMVPE vocal pitch extraction algorithm, you need t
 	```
 
 ## Getting Started
+### MacOS (Recommended)
+For first-time setup with automatic model download:
+```bash
+./run.sh --download-models
+```
+
+For subsequent runs:
+```bash
+./run.sh
+```
+
 ### Direct Launch
 Use the following command to start the WebUI.
 ```bash
 python web.py
 ```
-### MacOS
+
+To download all required models before starting:
 ```bash
-./run.sh
+python web.py --update
 ```
 
 ## Credits
@@ -151,12 +187,12 @@ A macOS-optimized version of the Retrieval-based Voice Conversion WebUI, specifi
 ## Features
 
 - Voice conversion with high-quality results
+- Easy one-click setup with automatic model download
 - Optimized for Apple Silicon (M1/M2/M3) Macs
 - User-friendly web interface
 - Support for various audio formats
 - Real-time voice conversion
 - Training capabilities for custom voice models
-- All required models included - no additional downloads needed!
 
 ## Requirements
 
@@ -168,6 +204,27 @@ A macOS-optimized version of the Retrieval-based Voice Conversion WebUI, specifi
 
 ## Installation
 
+### Option 1: Quick Setup with run.sh (Recommended)
+
+1. Clone this repository:
+```bash
+git clone https://github.com/audiohacking/RVC-WebUI-MacOS.git
+cd RVC-WebUI-MacOS
+```
+
+2. Run the setup script with automatic model download:
+```bash
+sh ./run.sh --download-models
+```
+
+This will automatically:
+- Create a virtual environment
+- Install all dependencies
+- Download all required models
+- Start the web interface
+
+### Option 2: Manual Installation
+
 1. Clone this repository:
 ```bash
 git clone https://github.com/audiohacking/RVC-WebUI-MacOS.git
@@ -185,16 +242,30 @@ source .venv/bin/activate
 pip install -r requirements/gui.txt
 ```
 
-> **Note**: This repository includes all necessary model files. You don't need to download any additional models. However, if you want to use different models, you can download them from the original repository.
+4. Download models:
+```bash
+python web.py --update
+```
 
 ## Usage
 
-1. Start the web interface:
+### Using run.sh (Recommended)
+```bash
+./run.sh
+```
+
+### Manual Launch
+1. Activate the virtual environment:
+```bash
+source .venv/bin/activate
+```
+
+2. Start the web interface:
 ```bash
 python web.py --port 7860
 ```
 
-2. Open your web browser and navigate to:
+3. Open your web browser and navigate to:
 ```
 http://localhost:7860
 ```
diff --git a/download_models.py b/download_models.py
new file mode 100644
index 0000000..d5a706e
--- /dev/null
+++ b/download_models.py
@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""
+Script to download all required models for RVC-WebUI-MacOS.
+This script downloads models without starting the web interface.
+"""
+import os
+import sys
+import shutil
+from dotenv import load_dotenv
+
+# Add current directory to path
+now_dir = os.getcwd()
+sys.path.append(now_dir)
+
+# Load environment variables
+load_dotenv()
+load_dotenv("sha256.env")
+
+# Create temp directory
+tmp = os.path.join(now_dir, "TEMP")
+shutil.rmtree(tmp, ignore_errors=True)
+os.makedirs(tmp, exist_ok=True)
+
+# Import model checking and downloading functions
+from infer.lib.rvcmd import check_all_assets, download_all_assets
+
+print("=" * 60)
+print("RVC-WebUI-MacOS Model Downloader")
+print("=" * 60)
+print()
+
+# Check if models are already present
+print("Checking for existing models...")
+if check_all_assets(update=False):
+    print("✓ All required models are already present!")
+    print("  No download needed.")
+    sys.exit(0)
+
+print()
+print("Some models are missing or outdated.")
+print("Starting download process...")
+print("This may take several minutes depending on your connection.")
+print()
+
+try:
+    # Download all assets
+    download_all_assets(tmpdir=tmp)
+    
+    # Verify download was successful
+    print()
+    print("Verifying downloaded models...")
+    if check_all_assets(update=True):
+        print()
+        print("=" * 60)
+        print("✓ SUCCESS! All models downloaded successfully!")
+        print("=" * 60)
+        print()
+        print("You can now run: ./run.sh")
+        sys.exit(0)
+    else:
+        print()
+        print("⚠ Warning: Some models may not have downloaded correctly.")
+        print("  The application will still start but may have limited functionality.")
+        sys.exit(1)
+        
+except Exception as e:
+    print()
+    print(f"✗ Error during download: {e}")
+    print("  You can try running this script again, or download models manually.")
+    print("  See README.md for manual download instructions.")
+    sys.exit(1)
+finally:
+    # Cleanup
+    shutil.rmtree(tmp, ignore_errors=True)
diff --git a/run.sh b/run.sh
index f011baf..5e9745d 100755
--- a/run.sh
+++ b/run.sh
@@ -11,6 +11,19 @@ fi
 requirements_file="requirements/main.txt"
 venv_path=".venv"
 
+# Parse command line arguments
+download_models=false
+for arg in "$@"; do
+  case $arg in
+    --download-models)
+      download_models=true
+      shift
+      ;;
+    *)
+      ;;
+  esac
+done
+
 if [[ ! -d "${venv_path}" ]]; then
   echo "Creating venv..."
 
@@ -23,5 +36,27 @@ fi
 echo "Activating venv..."
 source "${venv_path}/bin/activate"
 
+# Download models if requested
+if [ "$download_models" = true ]; then
+  echo ""
+  echo "Running model downloader..."
+  python download_models.py
+  download_exit_code=$?
+  
+  if [ $download_exit_code -eq 0 ]; then
+    echo ""
+    echo "Models are ready!"
+  else
+    echo ""
+    echo "Note: Model download completed with warnings."
+    echo "The application will still start."
+  fi
+  
+  echo ""
+  read -p "Press Enter to continue and start the application..."
+  echo ""
+fi
+
 # Run the main script
+echo "Starting RVC WebUI..."
 python web.py --pycmd python

From b17da15084040b361475151fd158eb88adc97a42 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 14:27:48 +0000
Subject: [PATCH 3/4] Fix code review issues: remove shift from loop, improve
 exit codes, clarify README

Co-authored-by: lmangani <1423657+lmangani@users.noreply.github.com>
---
 README.md          |  2 +-
 download_models.py |  5 +++--
 run.sh             | 10 +++++++---
 3 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index b391162..f9dc878 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,7 @@ By executing `run.sh` in the project root directory, you can configure the `venv
 ```bash
 sh ./run.sh
 ```
-This will start the application. Models will be checked and can be downloaded automatically when needed.
+This will start the application. If models are missing, you'll need to download them using one of the methods described in the "Preparation of Other Files" section below.
 
 #### First-time Setup (with automatic model download)
 ```bash
diff --git a/download_models.py b/download_models.py
index d5a706e..d3617d0 100644
--- a/download_models.py
+++ b/download_models.py
@@ -60,8 +60,9 @@
     else:
         print()
         print("⚠ Warning: Some models may not have downloaded correctly.")
-        print("  The application will still start but may have limited functionality.")
-        sys.exit(1)
+        print("  You may want to try running this script again.")
+        print("  The application may have limited functionality without all models.")
+        sys.exit(2)
         
 except Exception as e:
     print()
diff --git a/run.sh b/run.sh
index 5e9745d..eef624b 100755
--- a/run.sh
+++ b/run.sh
@@ -17,7 +17,6 @@ for arg in "$@"; do
   case $arg in
     --download-models)
       download_models=true
-      shift
       ;;
     *)
       ;;
@@ -46,10 +45,15 @@ if [ "$download_models" = true ]; then
   if [ $download_exit_code -eq 0 ]; then
     echo ""
     echo "Models are ready!"
-  else
+  elif [ $download_exit_code -eq 2 ]; then
     echo ""
     echo "Note: Model download completed with warnings."
-    echo "The application will still start."
+    echo "Some models may not have downloaded correctly."
+  else
+    echo ""
+    echo "Error: Model download failed."
+    echo "Please check the error messages above and try again."
+    exit 1
   fi
   
   echo ""

From 9b5a46c56eaead489cbe50f6138362e4ee1946a4 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 14:28:17 +0000
Subject: [PATCH 4/4] Improve documentation clarity per code review feedback

Co-authored-by: lmangani <1423657+lmangani@users.noreply.github.com>
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f9dc878..2e5c6ce 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,7 @@ By executing `run.sh` in the project root directory, you can configure the `venv
 ```bash
 sh ./run.sh
 ```
-This will start the application. If models are missing, you'll need to download them using one of the methods described in the "Preparation of Other Files" section below.
+This will start the application. If models are missing, you'll need to download them first - see "Automatic Download" under the Assets section below.
 
 #### First-time Setup (with automatic model download)
 ```bash
@@ -187,7 +187,7 @@ A macOS-optimized version of the Retrieval-based Voice Conversion WebUI, specifi
 ## Features
 
 - Voice conversion with high-quality results
-- Easy one-click setup with automatic model download
+- Easy automated setup with automatic model download
 - Optimized for Apple Silicon (M1/M2/M3) Macs
 - User-friendly web interface
 - Support for various audio formats