Upload folder using huggingface_hub

.gitattributes

@@ -1,35 +1,2 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+# Auto detect text files and perform LF normalization
+* text=auto

.gitignore

@@ -0,0 +1,160 @@
+# Ultimate RVC project
+audio
+models
+temp
+uv
+uv.lock
+
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintainted in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/

.gradio/certificate.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 JackismyShephard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,12 +1,254 @@
 ---
 title: HRVC
-emoji: 🌖
-colorFrom: green
-colorTo: gray
+app_file: src/ultimate_rvc/web/main.py
 sdk: gradio
 sdk_version: 5.6.0
-app_file: app.py
-pinned: false
 ---
+# Ultimate RVC
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+An extension of [AiCoverGen](https://github.com/SociallyIneptWeeb/AICoverGen), which provides several new features and improvements, enabling users to generate song covers using RVC with ease. Ideal for people who want to incorporate singing functionality into their AI assistant/chatbot/vtuber, or for people who want to hear their favourite characters sing their favourite song.
+
+<!-- Showcase: TBA -->
+
+![ ](images/webui_generate.png?raw=true)
+
+Ultimate RVC is under constant development and testing, but you can try it out right now locally or on Google Colab!
+
+## New Features
+
+* Easy and automated setup using launcher scripts for both windows and Debian-based linux systems
+* Caching system which saves intermediate audio files as needed, thereby reducing inference time as much as possible. For example, if song A has already been converted using model B and now you want to convert song A using model C, then vocal extraction can be skipped and inference time reduced drastically
+* Ability to listen to intermediate audio files in the UI. This is useful for getting an idea of what is happening in each step of the song cover generation pipeline
+* A "multi-step" song cover generation tab: here you can try out each step of the song cover generation pipeline in isolation. For example, if you already have extracted vocals available and only want to convert these using your voice model, then you can do that here. Besides, this tab is useful for experimenting with settings for each step of the song cover generation pipeline
+* An overhaul of the song input component for the song cover generation pipeline. Now cached input songs can be selected from a dropdown, so that you don't have to supply the Youtube link of a song each time you want to convert it.
+* A new "manage models" tab, which collects and revamps all existing functionality for managing voice models, as well as adds some new features, such as the ability to delete existing models
+* A new "manage audio" tab, which allows you to interact with all audio generated by the app. Currently, this tab supports deleting audio files.
+* Lots of visual and performance improvements resulting from updating from Gradio 3 to Gradio 5 and from python 3.9 to python 3.12
+* A redistributable package on PyPI, which allows you to access the Ultimate RVC project without cloning any repositories.
+
+## Colab notebook
+
+For those without a powerful enough NVIDIA GPU, you may try Ultimate RVC out using Google Colab.
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/JackismyShephard/ultimate-rvc/blob/main/notebooks/ultimate_rvc_colab.ipynb)
+
+For those who want to run the Ultimate RVC project locally, follow the setup guide below.
+
+## Setup
+
+The Ultimate RVC project currently supports Windows and Debian-based Linux distributions, namely Ubuntu 22.04 and Ubuntu 24.04. Support for other platforms is not guaranteed.
+
+To setup the project follow the steps below and execute the provided commands in an appropriate terminal. On windows this terminal should be **powershell**, while on Debian-based linux distributions it should be a **bash**-compliant shell.
+
+### Install Git
+
+Follow the instructions [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install Git on your computer.
+
+### Set execution policy (Windows only)
+
+To execute the subsequent commands on Windows, it is necessary to first grant
+powershell permission to run scripts. This can be done at a user level as follows:
+
+```console
+Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+### Clone Ultimate RVC repository
+
+```console
+git clone https://github.com/JackismyShephard/ultimate-rvc
+cd ultimate-rvc
+```
+
+### Install dependencies
+
+```console
+./urvc install 
+```
+Note that on Linux, this command will install the CUDA 12.4 toolkit system-wide, if it is not already available. In case you have problems, you may need to install the toolkit manually.
+
+## Usage
+
+### Start the app
+
+```console
+./urvc run
+```
+
+Once the following output message `Running on local URL:  http://127.0.0.1:7860` appears, you can click on the link to open a tab with the web app.
+
+### Manage models
+
+#### Download models
+
+![ ](images/webui_dl_model.png?raw=true)
+
+Navigate to the `Download model` subtab under the `Manage models` tab, and paste the download link to an RVC model and give it a unique name.
+You may search the [AI Hub Discord](https://discord.gg/aihub) where already trained voice models are available for download.
+The downloaded zip file should contain the .pth model file and an optional .index file.
+
+Once the 2 input fields are filled in, simply click `Download`! Once the output message says `[NAME] Model successfully downloaded!`, you should be able to use it in the `Generate song covers` tab!
+
+#### Upload models
+
+![ ](images/webui_upload_model.png?raw=true)
+
+For people who have trained RVC v2 models locally and would like to use them for AI cover generations.
+Navigate to the `Upload model` subtab under the `Manage models` tab, and follow the instructions.
+Once the output message says `Model with name [NAME] successfully uploaded!`, you should be able to use it in the `Generate song covers` tab!
+
+#### Delete RVC models
+
+TBA
+
+### Generate song covers
+
+#### One-click generation
+
+![ ](images/webui_generate.png?raw=true)
+
+* From the Voice model dropdown menu, select the voice model to use.
+* In the song input field, copy and paste the link to any song on YouTube, the full path to a local audio file, or select a cached input song.
+* Pitch should be set to either -12, 0, or 12 depending on the original vocals and the RVC AI modal. This ensures the voice is not *out of tune*.
+* Other advanced options for vocal conversion, audio mixing and etc. can be viewed by clicking the appropriate accordion arrow to expand.
+
+Once all options are filled in, click `Generate` and the AI generated cover should appear in a less than a few minutes depending on your GPU.
+
+#### Multi-step generation
+
+TBA
+
+## CLI
+
+### Manual download of RVC models
+
+Unzip (if needed) and transfer the `.pth` and `.index` files to a new folder in the [rvc models](models/rvc) directory. Each folder should only contain one `.pth` and one `.index` file.
+
+The directory structure should look something like this:
+
+```text
+├── models
+|   ├── audio_separator
+|   ├── rvc
+│       ├── John
+│       │   ├── JohnV2.pth
+│       │   └── added_IVF2237_Flat_nprobe_1_v2.index
+│       ├── May
+│       │   ├── May.pth
+│       │   └── added_IVF2237_Flat_nprobe_1_v2.index
+│       └── hubert_base.pt
+├── notebooks
+├── notes
+└── src
+```
+
+### Running the pipeline
+
+#### Usage
+
+```console
+./urvc cli song-cover run-pipeline [OPTIONS] SOURCE MODEL_NAME 
+```
+
+##### Arguments
+
+* `SOURCE`: A Youtube URL, the path to a local audio file or the path to a song directory.  [required]
+* `MODEL_NAME`: The name of the voice model to use for vocal conversion.  [required]
+
+##### Options
+
+* `--n-octaves INTEGER`: The number of octaves to pitch-shift the converted vocals by.Use 1 for male-to-female and -1 for vice-versa.  [default: 0]
+* `--n-semitones INTEGER`: The number of semi-tones to pitch-shift the converted vocals, instrumentals, and backup vocals by. Altering this slightly reduces sound quality  [default: 0]
+* `--f0-method [rmvpe|mangio-crepe]`: The method to use for pitch detection during vocal conversion. Best option is RMVPE (clarity in vocals), then Mangio-Crepe (smoother vocals).  [default: rmvpe]
+* `--index-rate FLOAT RANGE`: A decimal number e.g. 0.5, Controls how much of the accent in the voice model to keep in the converted vocals. Increase to bias the conversion towards the accent of the voice model.  [default: 0.5; 0<=x<=1]
+* `--filter-radius INTEGER RANGE`: A number between 0 and 7. If >=3: apply median filtering to the pitch results harvested during vocal conversion. Can help reduce breathiness in the converted vocals.  [default: 3; 0<=x<=7]
+* `--rms-mix-rate FLOAT RANGE`: A decimal number e.g. 0.25. Controls how much to mimic the loudness of the input vocals (0) or a fixed loudness (1) during vocal conversion.  [default: 0.25; 0<=x<=1]
+* `--protect FLOAT RANGE`: A decimal number e.g. 0.33. Controls protection of voiceless consonants and breath sounds during vocal conversion. Decrease to increase protection at the cost of indexing accuracy. Set to 0.5 to disable.  [default: 0.33; 0<=x<=0.5]
+* `--hop-length INTEGER`: Controls how often the CREPE-based pitch detection algorithm checks for pitch changes during vocal conversion. Measured in milliseconds. Lower values lead to longer conversion times and a higher risk of voice cracks, but better pitch accuracy. Recommended value: 128.  [default: 128]
+* `--room-size FLOAT RANGE`: The room size of the reverb effect applied to the converted vocals. Increase for longer reverb time. Should be a value between 0 and 1.  [default: 0.15; 0<=x<=1]
+* `--wet-level FLOAT RANGE`: The loudness of the converted vocals with reverb effect applied. Should be a value between 0 and 1  [default: 0.2; 0<=x<=1]
+* `--dry-level FLOAT RANGE`: The loudness of the converted vocals wihout reverb effect applied. Should be a value between 0 and 1.  [default: 0.8; 0<=x<=1]
+* `--damping FLOAT RANGE`: The absorption of high frequencies in the reverb effect applied to the converted vocals. Should be a value between 0 and 1.  [default: 0.7; 0<=x<=1]
+* `--main-gain INTEGER`: The gain to apply to the post-processed vocals. Measured in dB.  [default: 0]
+* `--inst-gain INTEGER`: The gain to apply to the pitch-shifted instrumentals. Measured in dB.  [default: 0]
+* `--backup-gain INTEGER`: The gain to apply to the pitch-shifted backup vocals. Measured in dB.  [default: 0]
+* `--output-sr INTEGER`: The sample rate of the song cover.  [default: 44100]
+* `--output-format [mp3|wav|flac|ogg|m4a|aac]`: The audio format of the song cover.  [default: mp3]
+* `--output-name TEXT`: The name of the song cover.
+* `--help`: Show this message and exit.
+
+## Update to latest version
+
+```console
+./urvc update
+```
+
+## Development mode
+
+When developing new features or debugging, it is recommended to run the app in development mode. This enables hot reloading, which means that the app will automatically reload when changes are made to the code.
+
+```console
+./urvc dev
+```
+
+## PyPI package
+
+The Ultimate RVC project is also available as a [distributable package](https://pypi.org/project/ultimate-rvc/) on [PyPI](https://pypi.org/).
+
+### Installation
+
+The package can be installed with pip in a **Python 3.12**-based environment. To do so requires first installing PyTorch with Cuda support:
+
+```console
+pip install torch==2.5.1+cu124 torchaudio==2.5.1+cu124 --index-url https://download.pytorch.org/whl/cu124
+```
+
+Additionally, on Windows the `diffq` package must be installed manually as follows:
+
+```console
+pip install https://huggingface.co/JackismyShephard/ultimate-rvc/resolve/main/diffq-0.2.4-cp312-cp312-win_amd64.whl
+```
+
+The Ultimate RVC project package can then be installed as follows:
+
+```console
+pip install ultimate-rvc
+```
+
+### Usage
+
+The `ultimate-rvc` package can be used as a python library but is primarily intended to be used as a command line tool. The package exposes two top-level commands:
+
+* `urvc` which lets the user generate song covers directly from their terminal
+* `urvc-web` which starts a local instance of the Ultimate RVC web application
+
+For more information on either command supply the option `--help`.
+
+## Environment Variables
+
+The behaviour of the Ultimate RVC project can be customized via a number of environment variables. Currently these environment variables control only logging behaviour. They are as follows:
+
+* `URVC_CONSOLE_LOG_LEVEL`: The log level for console logging. If not set, defaults to `ERROR`.
+* `URVC_FILE_LOG_LEVEL`: The log level for file logging. If not set, defaults to `INFO`.
+* `URVC_LOGS_DIR`: The directory in which log files will be stored. If not set, logs will be stored in a `logs` directory in the current working directory.
+* `URVC_NO_LOGGING`: If set to `1`, logging will be disabled.
+
+## Terms of Use
+
+The use of the converted voice for the following purposes is prohibited.
+
+* Criticizing or attacking individuals.
+
+* Advocating for or opposing specific political positions, religions, or ideologies.
+
+* Publicly displaying strongly stimulating expressions without proper zoning.
+
+* Selling of voice models and generated voice clips.
+
+* Impersonation of the original owner of the voice with malicious intentions to harm/hurt others.
+
+* Fraudulent purposes that lead to identity theft or fraudulent phone calls.
+
+## Disclaimer
+
+I am not liable for any direct, indirect, consequential, incidental, or special damages arising out of or in any way connected with the use/misuse or inability to use this software.

notebooks/ultimate_rvc_colab.ipynb

@@ -0,0 +1,109 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "kmyCzJVyCymN"
+   },
+   "source": [
+    "Colab for [Ultimate RVC](https://github.com/JackismyShephard/ultimate-rvc)\n",
+    "\n",
+    "This Colab notebook will **help** you if you don’t have a GPU or if your PC isn’t very powerful.\n",
+    "\n",
+    "Simply click `Runtime` in the top navigation bar and `Run all`. Wait for the output of the final cell to show the public gradio url and click on it.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# @title 0: Initialize notebook\n",
+    "%pip install ipython-autotime\n",
+    "%load_ext autotime\n",
+    "\n",
+    "import codecs\n",
+    "import os\n",
+    "\n",
+    "from IPython.display import clear_output\n",
+    "\n",
+    "clear_output()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "cellView": "form",
+    "id": "aaokDv1VzpAX"
+   },
+   "outputs": [],
+   "source": [
+    "# @title 1: Clone repository\n",
+    "cloneing = codecs.decode(\n",
+    "    \"uggcf://tvguho.pbz/WnpxvfzlFurcuneq/hygvzngr-eip.tvg\",\n",
+    "    \"rot_13\",\n",
+    ")\n",
+    "\n",
+    "!git clone $cloneing HRVC\n",
+    "%cd /content/HRVC\n",
+    "clear_output()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "cellView": "form",
+    "id": "lVGNygIa0F_1"
+   },
+   "outputs": [],
+   "source": [
+    "# @title 2: Install dependencies\n",
+    "\n",
+    "light = codecs.decode(\"uggcf://nfgeny.fu/hi/0.5.0/vafgnyy.fu\", \"rot_13\")\n",
+    "inits = codecs.decode(\"./fep/hygvzngr_eip/pber/znva.cl\", \"rot_13\")\n",
+    "\n",
+    "!apt install -y python3-dev unzip\n",
+    "!curl -LsSf $light | sh\n",
+    "\n",
+    "os.environ[\"URVC_CONSOLE_LOG_LEVEL\"] = \"WARNING\"\n",
+    "!uv run -q $inits\n",
+    "clear_output()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "cellView": "form",
+    "id": "lVGNygIa0F_2"
+   },
+   "outputs": [],
+   "source": [
+    "# @title 3: Run Ultimate RVC\n",
+    "\n",
+    "runpice = codecs.decode(\"./fep/hygvzngr_eip/jro/znva.cl\", \"rot_13\")\n",
+    "\n",
+    "!uv run $runpice --share"
+   ]
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "colab": {
+   "gpuType": "T4",
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

notes/TODO.md

@@ -0,0 +1,462 @@
+# TODO
+
+* should rename instances of "models" to "voice models"
+
+## Project/task management
+
+* Should find tool for project/task management
+* Tool should support:
+  * hierarchical tasks
+  * custom labels and or priorities on tasks
+  * being able to filter tasks based on those labels
+  * being able to close and resolve tasks
+  * Being able to integrate with vscode
+  * Access for multiple people (in a team)
+* Should migrate the content of this file into tool
+* Potential candidates
+  * GitHub projects
+    * Does not yet support hierarchical tasks so no
+  * Trello
+    * Does not seem to support hierarchical tasks either
+  * Notion
+    * Seems to support hierarchical tasks, but is complicated
+  * Todoist
+    * seems to support both hierarchical tasks, custom labels, filtering on those labels, multiple users and there are unofficial plugins for vscode.
+
+## Front end
+
+### Modularization
+
+* Improve modularization of web code using helper functions defined [here](https://huggingface.co/spaces/WoWoWoWololo/wrapping-layouts/blob/main/app.py)
+* Split front-end modules into further sub-modules.
+  * Structure of web folder should be:
+    * `web`
+      * `manage_models`
+        * `__init__.py`
+        * `main.py`
+      * `manage_audio`
+        * `__init__.py`
+        * `main.py`
+      * `generate_song_covers`
+        * `__init__.py`
+        * `main.py`
+        * `one_click_generation`
+          * `__init__.py`
+          * `main.py`
+          * `accordions`
+            * `__init__.py`
+            * `options_x.py` ... ?
+        * `multi_step_generation`
+          * `__init__.py`
+          * `main.py`
+          * `accordions`
+            * `__init__.py`
+            * `step_X.py` ...
+      * `common.py`
+    * For `multi_step_generation/step_X.py`, its potential render function might have to take the set of all "input tracks" in the multi-step generation tab, so these will then have to be defined in `multi_step_generation/main.py`. Other components passed to `multi_step_generation/main.py` might also need to be passed further down to `multi_step_generation/step_X.py`
+    * For `one_click_generation/option_X.py`, its potential render function should
+        render the accordion for the given options and return the components defined in the accordion? Other components passed to `one_click_generation/main.py` might also need to be passed further down to `one_click_generation/option_X.py`
+  * Import components instead of passing them as inputs to render functions (DIFFICULT TO IMPLEMENT)
+    * We have had problems before with component ids when components are instantiated outside a Blocks context in a separate module and then import into other modules and rendered in their blocks contexts.
+
+### Multi-step generation
+
+* If possible merge two consecutive event listeners using `update_cached_songs` in the song retrieval accordion.
+* add description describing how to use each accordion and suggestions for workflows
+
+* add option for adding more input tracks to the mix song step
+  * new components should be created dynamically based on a textfield with names and a button for creating new component
+  * when creating a new component a new transfer button and dropdown should also be created
+  * and the transfer choices for all dropdowns should be updated to also include the new input track
+  * we need to consider how to want to handle vertical space
+    * should be we make a new row once more than 3 tracks are on one row?
+      * yes and there should be also created the new slider on a new row
+      * right under the first row (which itself is under the row with song dir dropdown)
+
+* should also have the possiblity to add more tracks to the pitch shift accordion.
+
+* add a confirmation box with warning if trying to transfer output track to input track that is not empty.
+  * could also have the possibility to ask the user to transfer to create a new input track and transfer the output track to it.
+  * this would just be the same pop up confirmation box as before but in addition to yes and cancel options it will also have a "transfer to new input track" option.
+  * we need custom javasctip for this.
+
+### Common
+
+* fix problem with typing of block.launch()
+  * problem stems from doing from gradio import routes
+  * so instead should import from gradio.routes directly
+  * open a pr with changes
+* save default values for options for song generation in an `SongCoverOptionDefault` enum.
+  * then reference this enum across the two tabs
+  * and also use `list[SongCoverOptionDefault]` as input to reset settings click event listener in single click generation tab.
+* Persist state of app (currently selected settings etc.) across re-renders
+  * This includes:
+    * refreshing a browser windows
+    * Opening app in new browser window
+    * Maybe it should also include when app is started anew?
+  * Possible solutions
+    * use gr.browserstate to allow state to be preserved acrross page loads.
+    * Save any changes to components to a session dictionary and load from it upon refresh
+      * See [here](https://github.com/gradio-app/gradio/issues/3106#issuecomment-1694704623)
+      * Problem is that this solution might not work with accordions or other types of blocks
+            * should use .expand() and .collapse() event listeners on accordions to programmatically reset the state of accordions to what they were before after user has refreshed the page
+    * Use localstorage
+      * see [here](https://huggingface.co/spaces/YiXinCoding/gradio-chat-history/blob/main/app.py) and [here](https://huggingface.co/spaces/radames/gradio_window_localStorage/blob/main/app.py)
+
+    * Whenever the state of a component is changed save the new state to a custom JSON file.
+      * Then whenever the app is refreshed load the current state of components from the JSON file
+      * This solution should probably work for Block types that are not components
+* need to fix the `INFO: Could not find files for the given pattern(s)` on startup of web application on windows (DIFFICULT TO IMPLEMENT)
+  * this is an error that gradio needs to fix
+* Remove reset button on slider components (DIFFICULT TO IMPLEMENT)
+  * this is a gradio feature that needs to be removed.
+* Fix that gradio removes special symbols from audio paths when loaded into audio components (DIFFICULT TO IMPLEMENT)
+  * includes parenthesis, question marks, etc.
+  * its a gradio bug so report?
+* Add button for cancelling any currently running jobs (DIFFICULT TO IMPLEMENT)
+  * Not supported by Gradio natively
+  * Also difficult to implement manually as Gradio seems to be running called backend functions in thread environments
+* dont show error upon missing confirmation (DIFFICULT TO IMPLEMENT)
+  * can return `gr.update()`instead of raising an error in relevant event listener function
+  * but problem is that subsequent steps will still be executed in this case
+* clearing temporary files with the `delete_cache` parameter only seems to work if all windows are closed before closing the app process (DIFFICULT TO IMPLEMENT)
+  * this is a gradio bug so report?
+
+## Online hosting optimization
+
+* make concurrency_id and concurrency limit on components be dependent on whether gpu is used or not
+  * if only cpu then there should be no limit
+* increase value of `default_concurrency_limit` in `Block.queue` so that the same event listener
+  * can be called multiple times concurrently
+* use `Block.launch()` with `max_file_size` to prevent too large uploads
+* define as many functions with async as possible to increase responsiveness of app
+  * and then use `Block.launch()` with `max_threads`set to an appropriate value representing the number of concurrent threads that can be run on the server (default is 40)
+* Persist state of app (currently selected settings etc.) across re-renders
+* consider setting `max_size` in `Block.queue()` to explicitly limit the number of people that can be in the queue at the same time
+* clearing of temporary files should happen after a user logs in and out
+  * and in this case it should only be temporary files for the active user that are cleared
+    * Is that even possible to control?
+* enable server side rendering (requires installing node and setting ssr_mode = true in .launch) (DIFFICULT TO IMPLEMENT)
+  * Also needs to set GRADIO_NODE_PATH to point to the node executable
+  * problem is that on windows there is a ERR_UNSUPPORTED_ESM_URL_SCHEME which needs to be fixed by gradio
+    * see here https://github.com/nodejs/node/issues/31710
+  * on linux it works but it is not possible to shutdown server using CTRL+ C
+
+
+## Back end
+
+### `generate_song_cover.py`
+
+* intermediate file prefixes should be made into enums 
+* find framework for caching intermediate results rather than relying on your homemade system
+
+  * Joblib: <https://medium.com/@yuxuzi/unlocking-efficiency-in-machine-learning-projects-with-joblib-a-python-pipeline-powerhouse-feb0ebfdf4df>
+  * scikit learn: <https://scikit-learn.org/stable/modules/compose.html#pipeline>
+
+  * <https://softwarepatternslexicon.com/machine-learning/infrastructure-and-scalability/workflow-management/pipeline-caching/>
+  * <https://github.com/bmabey/provenance>
+  * <https://docs.sweep.dev/blogs/file-cache>
+
+* Support specific audio formats for intermediate audio file?
+  * it might require some more code to support custom output format for all pipeline functions.
+
+* expand `_get_model_name` so that it can take any audio file in an intermediate audio folder as input (DIFFICULT TO IMPLEMENT)
+  * Function should then try to recursively
+    * look for a corresponding json metadata file
+    * find the model name in that file if it exists
+    * otherwise find the path in the input field in the metadata file
+    * repeat
+  * should also consider whether input audio file belongs to step before audio conversion step
+* use pydantic models to constrain numeric inputs (DIFFICULT TO IMPLEMENT)
+  * for inputs to `convert` function for example
+  * Use `Annotated[basic type, Field[constraint]]` syntax along with a @validate_call decorator on functions
+  * Problem is that pyright does not support `Annotated` so we would have to switch to mypy
+  
+### `manage_models.py`
+
+* use pandas.read_json to load public models table (DIFFICULT TO IMPLEMENT)
+
+## CLI
+
+### Add remaining CLI interfaces
+
+* Interface for `core.manage_models`
+* Interface for `core.manage_audio`
+* Interfaces for individual pipeline functions defined in `core.generate_song_covers`
+
+## python package management
+
+* need to make project version (in `pyproject.toml`) dynamic so that it is updated automatically when a new release is made
+* once diffq-fixed is used by audio-separator we can remove the url dependency on windows
+  * we will still need to wait for uv to make it easy to install package with torch dependency
+  * also it is still necessary to install pytorch first as it is not on pypi index
+* figure out way of making ./urvc commands execute faster
+  * when ultimate rvc is downloaded as a pypi package the exposed commands are much faster so investigate this
+* update dependencies in pyproject.toml
+  * use latest compatible version of all packages
+  * remove commented out code, unless strictly necessary
+
+## Audio separation
+
+* expand back-end function(s) so that they are parametrized by both model type as well as model settings
+  * Need to decide whether we only want to support common model settings or also settings that are unique to each model
+    * It will probably be the latter, which will then require some extra checks.
+  * Need to decide which models supported by `audio_separator` that we want to support
+    * Not all of them seem to work
+    * Probably MDX models and MDXC models
+    * Maybe also VR and demucs?
+  * Revisit online guide for optimal models and settings
+* In multi-step generation tab
+  * Expand audio-separation accordion so that model can be selected and appropriate settings for that model can then be selected.
+    * Model specific settings should expand based on selected model
+* In one-click generation
+  * Should have an "vocal extration" option accordion
+    * Should be able to choose which audio separation steps to include in pipeline
+      * possible steps
+        * step 1: separating audio form instrumentals
+        * step 2: separating main vocals from background vocals:
+        * step 3: de-reverbing vocals
+      * Should pick steps from dropdown?
+      * For each selected step a new sub-accordion with options for that step will then appear
+        * Each accordion should include general settings
+        * We should decide whether model specific settings should also be supported
+        * We Should also decide whether sub-accordion should setting for choosing a model and if so render specific settings based the chosen model
+    * Alternative layout:
+      * have option to choose number of separation steps
+      * then dynamically render sub accordions for each of the selected number of steps
+        * In this case it should be possible to choose models for each accordion
+          * this field should be iniitally empty
+        * Other setttings should probably have sensible defaults that are the same
+      * It might also be a good idea to then have an "examples" pane with recommended combinations of extractions steps
+      * When one of these is selected, then the selected number of accordions with the preset settings should be filled out
+  * optimize pre-processing
+    * check <https://github.com/ArkanDash/Multi-Model-RVC-Inference>
+  * Alternatives to `audio-separator` package:
+    * [Deezer Spleeter](https://github.com/deezer/spleeter)
+      * supports both CLI and python package
+    * [Asteroid](https://github.com/asteroid-team/asteroid)
+    * [Nuzzle](https://github.com/nussl/nussl)
+
+## GitHub
+
+### Actions
+
+* linting with Ruff
+* typechecking with Pyright
+* running all tests
+* automatic building and publishing of project to pypi
+  * includes automatic update of project version number
+* or use pre-commit?
+
+### README
+
+* Fill out TBA sections in README
+* Add note about not using with VPN?
+* Add different emblems/badges in header
+  * like test coverage, build status, etc. (look at other projects for inspiration)
+* spice up text with emojis (look at tiango's projects for inspiration)
+
+### Releases
+
+* Make regular releases like done for Applio
+  * Will be an `.exe` file that when run unzips contents into application folder, where `./urvc run` can then be executed.
+  * Could it be possible to have `.exe` file just start webapp when clicked?
+* Could also include pypi package as a release?
+
+* use pyinstaller to install app into executable that also includes sox and ffmpeg as dependencies (DLLs)
+
+### Other
+
+* In the future consider detaching repo from where it is forked from:
+  * because it is not possible to make the repo private otherwise
+  * see: <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/detaching-a-fork>
+
+## Incorporate upstream changes
+
+* Incorporate RVC code from [rvc-cli](https://github.com/blaisewf/rvc-cli) (i.e. changes from Applio)
+  * more options for voice conversion and more efficient voice conversion
+  * batch conversion sub-tab
+  * TTS tab
+  * Model training tab
+  * support more pre-trained models
+    * sub-tab under "manage models" tab
+  * support for querying online database with many models that can be downloaded
+  * support for audio and model analysis.
+  * Voice blending tab
+* Incorporate latest changes from [RVC-WebUI](https://github.com/RVC-Project/Retrieval-based-Voice-Conversion-WebUI)
+
+## Vocal Conversion
+
+* support arbitrary combination of pitch detection algorithms
+  * source: <https://github.com/gitmylo/audio-webui>
+* Investigate using onnx models for inference speedup on cpu
+* Add more pitch detection methods
+  * pm
+  * harvest
+  * dio
+  * rvmpe+
+* Implement multi-gpu Inference
+
+## TTS conversion
+
+* also include original edge voice as output
+  * source: <https://github.com/litagin02/rvc-tts-webui>
+
+## Model management
+
+### Training models
+
+* have learning rate for training
+  * source: <https://github.com/gitmylo/audio-webui>
+* have a quick training button
+  * or have preprocess dataset, extract features and generate index happen by default
+* Support a loss/training graph
+  * source: <https://github.com/gitmylo/audio-webui>
+
+### Download models
+
+* Support batch downloading multiple models
+  * requires a tabular request form where both a link column and a name column has to be filled out
+  * we can allow selecting multiple items from public models table and then copying them over
+* support quering online database for models matching a given search string like what is done in applio app
+  * first n rows of online database should be shown by default in public models table
+    * more rows should be retrieved by scrolling down or clicking a button
+  * user search string should filter/narrow returned number of rows in public models table
+  * When clicking a set of rows they should then be copied over for downloading in the "download" table
+* support a column with preview sample in public models table
+  * Only possible if voice snippets are also returned when querying the online database
+* Otherwise we can always support voice snippets for voice models that have already been downloaded
+  * run model on sample text ("quick brown fox runs over the lazy") after it is downloaded
+  * save the results in a `audio/model_preview` folder
+  * Preview can then be loaded into a preview audio component when selecting a model from a dropdown
+  * or if we replace the dropdown with a table with two columns we can have the audio track displayed in the second column
+
+### Model analysis
+
+* we could provide a new tab to analyze an existing model like what is done in applio
+  * or this tab could be consolidated with the delete model tab?
+
+* we could also provide extra model information after model is downloaded
+  * potentialy in dropdown to expand?
+
+## Audio management
+
+### General
+
+* Support audio information tool like in applio?
+  * A new tab where you can upload a song to analyze?
+* more elaborate solution:
+  * tab where where you
+    * can select any song directory
+    * select any step in the audio generation pipeline
+    * then select any intermediate audio file generated in that step
+    * Then have the possibility to
+      * Listen to the song
+      * see a table with its metadata (based on its associated `.json` file)
+        * add timestamp to json files so they can be sorted in table according to creation date
+      * And other statistics in a separate component (graph etc.)
+  * Could have delete buttons both at the level of song_directory, step, and for each song?
+  * Also consider splitting intermediate audio tracks for each step in to subfolder (0,1,2,3...)
+
+## Other settings
+
+* rework other settings tab
+  * this should also contain other settings such as the ability to change the theme of the app
+  * there should be a button to apply settings which will reload the app with the new settings
+
+## Audio post-processing
+
+* Support more effects from the `pedalboard` pakcage.
+  * Guitar-style effects: Chorus, Distortion, Phaser, Clipping
+  * Loudness and dynamic range effects: Compressor, Gain, Limiter
+  * Equalizers and filters: HighpassFilter, LadderFilter, LowpassFilter
+  * Spatial effects: Convolution, Delay, Reverb
+  * Pitch effects: PitchShift
+  * Lossy compression: GSMFullRateCompressor, MP3Compressor
+  * Quality reduction: Resample, Bitcrush
+  * NoiseGate
+  * PeakFilter
+
+## Audio Mixing
+
+* Add main gain loudness slider?
+* Add option to equalize output audio with respect to input audio
+  * i.e. song cover gain (and possibly also more general dynamics) should be the same as those for source song.
+  * check to see if pydub has functionality for this
+  * otherwise a simple solution would be computing the RMS of the difference between the loudness of the input and output track
+
+  ```python
+    rms = np.sqrt(np.mean(np.square(signal)))
+    dB  = 20*np.log10(rms)
+    #add db to output file in mixing function (using pydub)
+  ```
+
+  * When this option is selected the option to set main gain of ouput should be disabled?
+
+* add more equalization options
+  * using `pydub.effects` and `pydub.scipy_effects`?
+
+## Custom UI
+
+* Experiment with new themes including [Building new ones](https://www.gradio.app/guides/theming-guid)
+  * first of all make new theme that is like the default gradio 4 theme in terms of using semi transparent orange as the main color and semi-transparent grey for secondary color. The new gradio 5 theme is good apart from using solid colors so maybe use that as base theme.
+  * Support both dark and light theme in app?
+  * Add Support for changing theme in app?
+  * Use Applio theme as inspiration for default theme?
+* Experiment with using custom CSS
+  * Pass `css = {css_string}` to `gr.Blocks` and use `elem_classes` and `elem_id` to have components target the styles define in the CSS string.
+* Experiment with [custom DataFrame styling](https://www.gradio.app/guides/styling-the-gradio-dataframe)
+* Experiment with custom Javascript
+* Look for opportunities for defining new useful custom components
+
+## Real-time vocal conversion
+
+* Should support being used as OBS plugin
+* Latency is real issue
+* Implementations details:
+  * implement back-end in Rust?
+  * implement front-end using svelte?
+  * implement desktop application using C++ or C#?
+* see <https://github.com/w-okada/voice-changer> and <https://github.com/RVC-Project/obs-rvc> for inspiration
+
+## AI assistant mode
+
+* similar to vocal conversion streaming but instead of converting your voice on the fly, it should:
+  * take your voice,
+  * do some language modelling (with an LLM or something)
+  * then produce an appropriate verbal response
+* We already have Kyutais [moshi](https://moshi.chat/?queue_id=talktomoshi)
+  * Maybe that model can be finetuned to reply with a voice
+  * i.e. your favorite singer, actor, best friend, family member.
+
+## Ultimate RVC bot for discord
+
+* maybe also make a forum on  discord?
+
+## Make app production ready
+
+* have a "report a bug" tab like in applio?
+* should have separate accounts for users when hosting online
+  * use `gr.LoginButton` and `gr.LogoutButton`?
+
+* deploy using docker
+  * See <https://www.gradio.app/guides/deploying-gradio-with-docker>
+* Host on own web-server with Nginx
+  * see <https://www.gradio.app/guides/running-gradio-on-your-web-server-with-nginx>
+
+* Consider having concurrency limit be dynamic, i.e. instead of always being 1 for jobs using gpu consider having it depend upon what resources are available.
+  * We can app set the GPU_CONCURRENCY limit to be os.envrion["GPU_CONCURRENCY_LIMIT] or 1 and then pass GPU_CONCURRENCY as input to places where event listeners are defined
+
+## Colab notebook
+
+* find way of saving virtual environment with python 3.11 in colab notebook (DIFFICULT TO IMPLEMENT)
+  * so that this environment can be loaded directly rather than downloading all dependencies every time app is opened
+
+## Testing
+
+* Add example audio files to use for testing
+  * Should be located in `audio/examples`
+  * could have sub-folders `input` and `output`
+    * in `output` folder we have `output_audio.ext` files each with a corresponding `input_audio.json` file containing metadata explaining arguments used to generate output
+    * We can then test that actual output is close enough to expected output using audio similarity metric.
+* Setup unit testing framework using pytest

notes/app-doc.md

@@ -0,0 +1,19 @@
+# `main`
+
+Run the Ultimate RVC web application.
+
+**Usage**:
+
+```console
+$ main [OPTIONS]
+```
+
+**Options**:
+
+* `-s, --share`: Enable sharing
+* `-l, --listen`: Make the web application reachable from your local network.
+* `-h, --listen-host TEXT`: The hostname that the server will use.
+* `-p, --listen-port INTEGER`: The listening port that the server will use.
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.

notes/cli-doc.md

@@ -0,0 +1,74 @@
+# `urvc-cli`
+
+CLI for the Ultimate RVC project
+
+**Usage**:
+
+```console
+$ urvc-cli [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `song-cover`: Generate song covers
+
+## `urvc-cli song-cover`
+
+Generate song covers
+
+**Usage**:
+
+```console
+$ urvc-cli song-cover [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `run-pipeline`: Run the song cover generation pipeline.
+
+### `urvc-cli song-cover run-pipeline`
+
+Run the song cover generation pipeline.
+
+**Usage**:
+
+```console
+$ urvc-cli song-cover run-pipeline [OPTIONS] SOURCE MODEL_NAME
+```
+
+**Arguments**:
+
+* `SOURCE`: A Youtube URL, the path to a local audio file or the path to a song directory.  [required]
+* `MODEL_NAME`: The name of the voice model to use for vocal conversion.  [required]
+
+**Options**:
+
+* `--n-octaves INTEGER`: The number of octaves to pitch-shift the converted vocals by.Use 1 for male-to-female and -1 for vice-versa.  [default: 0]
+* `--n-semitones INTEGER`: The number of semi-tones to pitch-shift the converted vocals, instrumentals, and backup vocals by. Altering this slightly reduces sound quality  [default: 0]
+* `--f0-method [rmvpe|mangio-crepe]`: The method to use for pitch detection during vocal conversion. Best option is RMVPE (clarity in vocals), then Mangio-Crepe (smoother vocals).  [default: rmvpe]
+* `--index-rate FLOAT RANGE`: A decimal number e.g. 0.5, Controls how much of the accent in the voice model to keep in the converted vocals. Increase to bias the conversion towards the accent of the voice model.  [default: 0.5; 0<=x<=1]
+* `--filter-radius INTEGER RANGE`: A number between 0 and 7. If >=3: apply median filtering to the pitch results harvested during vocal conversion. Can help reduce breathiness in the converted vocals.  [default: 3; 0<=x<=7]
+* `--rms-mix-rate FLOAT RANGE`: A decimal number e.g. 0.25. Controls how much to mimic the loudness of the input vocals (0) or a fixed loudness (1) during vocal conversion.  [default: 0.25; 0<=x<=1]
+* `--protect FLOAT RANGE`: A decimal number e.g. 0.33. Controls protection of voiceless consonants and breath sounds during vocal conversion. Decrease to increase protection at the cost of indexing accuracy. Set to 0.5 to disable.  [default: 0.33; 0<=x<=0.5]
+* `--hop-length INTEGER`: Controls how often the CREPE-based pitch detection algorithm checks for pitch changes during vocal conversion. Measured in milliseconds. Lower values lead to longer conversion times and a higher risk of voice cracks, but better pitch accuracy. Recommended value: 128.  [default: 128]
+* `--room-size FLOAT RANGE`: The room size of the reverb effect applied to the converted vocals. Increase for longer reverb time. Should be a value between 0 and 1.  [default: 0.15; 0<=x<=1]
+* `--wet-level FLOAT RANGE`: The loudness of the converted vocals with reverb effect applied. Should be a value between 0 and 1  [default: 0.2; 0<=x<=1]
+* `--dry-level FLOAT RANGE`: The loudness of the converted vocals wihout reverb effect applied. Should be a value between 0 and 1.  [default: 0.8; 0<=x<=1]
+* `--damping FLOAT RANGE`: The absorption of high frequencies in the reverb effect applied to the converted vocals. Should be a value between 0 and 1.  [default: 0.7; 0<=x<=1]
+* `--main-gain INTEGER`: The gain to apply to the post-processed vocals. Measured in dB.  [default: 0]
+* `--inst-gain INTEGER`: The gain to apply to the pitch-shifted instrumentals. Measured in dB.  [default: 0]
+* `--backup-gain INTEGER`: The gain to apply to the pitch-shifted backup vocals. Measured in dB.  [default: 0]
+* `--output-sr INTEGER`: The sample rate of the song cover.  [default: 44100]
+* `--output-format [mp3|wav|flac|ogg|m4a|aac]`: The audio format of the song cover.  [default: mp3]
+* `--output-name TEXT`: The name of the song cover.
+* `--help`: Show this message and exit.

notes/gradio.md

@@ -0,0 +1,615 @@
+
+# Gradio notes
+
+## Modularizing large gradio codebases
+
+See this [tutorial](https://www.gradio.app/guides/wrapping-layouts) and corresponding [code](https://huggingface.co/spaces/WoWoWoWololo/wrapping-layouts/blob/main/app.py).
+
+## Event listeners
+
+### Attaching event listeners using decorators
+
+```python
+@greet_btn.click(inputs=name, outputs=output)
+def greet(name):
+    return "Hello " + name + "!"
+```
+
+### Function input using dicts
+
+```python
+a = gr.Number(label="a")
+b = gr.Number(label="b")
+
+def sub(data):
+    return data[a] - data[b]
+sub_btn.click(sub, inputs={a, b}, outputs=c)
+```
+
+This syntax may be better for functions with many inputs
+
+### Function output using dicts
+
+```python
+food_box = gr.Number(value=10, label="Food Count")
+status_box = gr.Textbox()
+
+def eat(food):
+    if food > 0:
+        return {food_box: food - 1, status_box: "full"}
+    else:
+        return {status_box: "hungry"}
+
+gr.Button("Eat").click(
+    fn=eat,
+    inputs=food_box,
+    outputs=[food_box, status_box]
+)
+```
+
+Allows you to skip updating some output components.
+
+### Binding multiple event listeners to one function
+
+```python
+name = gr.Textbox(label="Name")
+output = gr.Textbox(label="Output Box")
+greet_btn = gr.Button("Greet")
+trigger = gr.Textbox(label="Trigger Box")
+
+def greet(name, evt_data: gr.EventData):
+    return "Hello " + name + "!", evt_data.target.__class__.__name__
+
+def clear_name(evt_data: gr.EventData):
+    return ""
+
+gr.on(
+    triggers=[name.submit, greet_btn.click],
+    fn=greet,
+    inputs=name,
+    outputs=[output, trigger],
+).then(clear_name, outputs=[name])
+```
+
+* Use `gr.on` with optional `triggers` argument. If `triggers` is not set then the given function will be called for all `.change` event listeners in the app.
+* Allows you to DRY a lot of code potentially.
+
+### Running events continuously
+
+```python
+with gr.Blocks as demo:
+    timer = gr.Timer(5)
+    textbox = gr.Textbox()
+    textbox2 = gr.Textbox()
+    timer.tick(set_textbox_fn, textbox, textbox2)
+```
+
+Or alternatively the following semantics can be used:
+
+```python
+with gr.Blocks as demo:
+timer = gr.Timer(5)
+textbox = gr.Textbox()
+textbox2 = gr.Textbox(set_textbox_fn, inputs=[textbox], every=timer)
+```
+
+## Other semantics
+
+### Conditional component values
+
+```python
+with gr.Blocks() as demo:
+    num1 = gr.Number()
+    num2 = gr.Number()
+    product = gr.Number(lambda a, b: a * b, inputs=[num1, num2])
+```
+
+* Value of component must be a function taking two component values and returning a new component value
+* Component must also take a list of inputs indicating which other components should be used to compute its value
+* Components value will always be updated whenever the other components `.change` event listeners are called.
+* Hence this method can be used to DRY code with many `.change` event listeners
+
+### Dynamic behavior
+
+We can use the `@gr.render` decorator to dynamically define components and event listeners while an app is executing
+
+#### Dynamic components
+
+```python
+import gradio as gr
+
+    with gr.Blocks() as demo:
+        input_text = gr.Textbox(label="input")
+
+        @gr.render(inputs=input_text)
+        def show_split(text):
+            if len(text) == 0:
+                gr.Markdown("## No Input Provided")
+            else:
+                for letter in text:
+                    gr.Textbox(letter)
+
+    demo.launch()
+```
+
+By default `@gr.render` is called whenever the `.change` event for the given input components are executed or when the app is loaded. This can be overriden by also giving a triggers argument to the decorator:
+
+```python
+@gr.render(inputs=input_text, triggers = [input_text.submit])
+...
+```
+
+#### Dynamic event listeners
+
+```python
+with gr.Blocks() as demo:
+    text_count = gr.State(1)
+    add_btn = gr.Button("Add Box")
+    add_btn.click(lambda x: x + 1, text_count, text_count)
+
+    @gr.render(inputs=text_count)
+    def render_count(count):
+        boxes = []
+        for i in range(count):
+            box = gr.Textbox(key=i, label=f"Box {i}")
+            boxes.append(box)
+
+        def merge(*args):
+            return " ".join(args)
+
+        merge_btn.click(merge, boxes, output)
+
+    merge_btn = gr.Button("Merge")
+    output = gr.Textbox(label="Merged Output")
+```
+
+* All event listeners that use components created inside a render function must also be defined inside that render function
+* The event listener can still reference components outside the render function
+* Just as with components, whenever a function re-renders, the event listeners created from the previous render are cleared and the new event listeners from the latest run are attached.
+* setting `key = ...` when instantiating a  component ensures that the value of the component is preserved upon rerender
+  * This is might also allow us to preserve session state easily across browser refresh?
+
+#### A more elaborate example
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+
+    tasks = gr.State([])
+    new_task = gr.Textbox(label="Task Name", autofocus=True)
+
+    def add_task(tasks, new_task_name):
+        return tasks + [{"name": new_task_name, "complete": False}], ""
+
+    new_task.submit(add_task, [tasks, new_task], [tasks, new_task])
+
+    @gr.render(inputs=tasks)
+    def render_todos(task_list):
+        complete = [task for task in task_list if task["complete"]]
+        incomplete = [task for task in task_list if not task["complete"]]
+        gr.Markdown(f"### Incomplete Tasks ({len(incomplete)})")
+        for task in incomplete:
+            with gr.Row():
+                gr.Textbox(task['name'], show_label=False, container=False)
+                done_btn = gr.Button("Done", scale=0)
+                def mark_done(task=task):
+                    task["complete"] = True
+                    return task_list
+                done_btn.click(mark_done, None, [tasks])
+
+                delete_btn = gr.Button("Delete", scale=0, variant="stop")
+                def delete(task=task):
+                    task_list.remove(task)
+                    return task_list
+                delete_btn.click(delete, None, [tasks])
+
+        gr.Markdown(f"### Complete Tasks ({len(complete)})")
+        for task in complete:
+            gr.Textbox(task['name'], show_label=False, container=False)
+
+demo.launch()
+```
+
+* Any event listener that modifies a state variable in a manner that should trigger a re-render must set the state variable as an output. This lets Gradio know to check if the variable has changed behind the scenes.
+* In a `gr.render`, if a variable in a loop is used inside an event listener function, that variable should be "frozen" via setting it to itself as a default argument in the function header. See how we have task=task in both mark_done and delete. This freezes the variable to its "loop-time" value.
+
+### Progress bars
+
+Instead of doing `gr.progress(percentage, desc= "...")` in core helper functions you can just use tqdm directly in your code by instantiating `gr.progress(track_tqdm = true)` in a web helper function/harness.
+
+Alternatively, you can also do `gr.Progress().tqdm(iterable, description, total, unit)` to attach a tqdm iterable to the progress bar
+
+Benefits of either approach is:
+
+* we do not have to supply a `gr.Progress` object to core functions.
+* Perhaps it will also be possible to get a progress bar that automatically generates several update steps for a given caption, rather than just one step as is the case when using `gr.Progress`
+
+### State
+
+Any variable created outside a function call is shared by all users of app
+
+So when deploying app in future need to use `gr.State()` for all variables declared outside functions?
+
+## Notes on Gradio classes
+
+* `Blocks.launch()`
+  * `prevent_thread_lock` can be used to have an easier way of shutting down app?
+  * `show_error`: if `True`can allow us not to have to reraise core exceptions as `gr.Error`?
+* `Tab`
+  * event listener triggered when tab is selected could be useful?
+* `File`
+  * `file_type`: can use this to limit input types to .pth, .index and .zip when downloading a model
+* `Label`
+  * Intended for output of classification models
+  * for actual labels in UI maybe use `gr.Markdown`?
+
+* `Button`
+  * `link`: link to open when button is clicked?
+  * `icon`: path to icon to display on button
+
+* `Audio`: relevant event listeners:
+  * `upload`: when a value is uploaded
+  * `input`: when a value is changed
+  * `clear`: when a value is cleared
+* `Dropdown`
+  * `height`
+  * `min_width`
+  * `wrap`: if text in cells should wrap
+  * `column_widths`: width of each column
+  * `datatype`: list of `"str"`, `"number"`, `"bool"`, `"date"`, `"markdown"`
+
+## Performance optimization
+
+* Can set `max_threads` argument for `Block.launch()`
+if you have any async definitions in your code (`async def`).
+* can set `max_size` argument on `Block.queue()`. This limits how many people can wait in line in the queue. If too many people are in line, new people trying to join will receive an error message. This can be better than default which is just having people wait indefinitely
+* Can increase `default_concurrency_limit` for `Block.queue()`. Default is `1`. Increasing to more might make operations more effective.
+* Rewrite functions so that they take a batched input and set `batched = True` on the event listener calling the function
+
+## Environment Variables
+
+Gradio supports environment variables which can be used to customize the behavior
+of your app from the command line instead of setting these parameters in `Blocks.launch()`
+
+* GRADIO_ANALYTICS_ENABLED
+* GRADIO_SERVER_PORT
+* GRADIO_SERVER_NAME
+* GRADIO_TEMP_DIR
+* GRADIO_SHARE
+* GRADIO_ALLOWED_PATHS
+* GRADIO_BLOCKED_PATHS
+
+These could be useful when running gradio apps from a shell script.
+
+## Networking
+
+### File Access
+
+Users can access:
+
+* Temporary files created by gradio
+* Files that are allowed via the `allowed_paths` parameter set in `Block.launch()`
+* static files that are set via [gr.set_static_paths](https://www.gradio.app/docs/gradio/set_static_paths)
+  * Accepts a list of directories or files names that will not be copied to the cached but served directly from computer.
+  * BONUS: This can be used in ULTIMATE RVC for dispensing with the temp gradio directory. Need to consider possible ramifications before implementing this though.
+
+Users cannot access:
+
+* Files that are blocked via the `blocked_paths` parameter set in `Block.launch()`
+  * This parameter takes precedence over the `allowed_paths` parameter and over default allowed paths
+* Any other paths on the host machine
+  * This is something to consider when hosting app online
+
+#### Limiting file upload size
+
+you can use `Block.launch(max_file_size= ...)` to limit max file size in MBs for each user.
+
+### Access network request
+
+you can access information from a network request directly within a gradio app:
+
+```python
+import gradio as gr
+
+def echo(text, request: gr.Request):
+    if request:
+        print("Request headers dictionary:", request.headers)
+        print("IP address:", request.client.host)
+        print("Query parameters:", dict(request.query_params))
+    return text
+
+io = gr.Interface(echo, "textbox", "textbox").launch()
+```
+
+If the network request is not done via the gradio UI then it will be `None` so always check if it exists
+
+### Authentication
+
+#### Password protection
+
+You can have an authentication page in front of your app by doing:
+
+```python
+demo.launch(auth=("admin", "pass1234"))
+```
+
+More complex handling can be achieved by giving a function as input:
+
+```python
+def same_auth(username, password):
+    return username == password
+demo.launch(auth=same_auth)
+```
+
+Also support a logout page:
+
+```python
+import gradio as gr
+
+def update_message(request: gr.Request):
+    return f"Welcome, {request.username}"
+
+with gr.Blocks() as demo:
+    m = gr.Markdown()
+    logout_button = gr.Button("Logout", link="/logout")
+    demo.load(update_message, None, m)
+    
+demo.launch(auth=[("Pete", "Pete"), ("Dawood", "Dawood")])
+```
+
+NOTE:
+
+* For authentication to work properly, third party cookies must be enabled in your browser. This is not the case by default for Safari or for Chrome Incognito Mode.
+* Gradio's built-in authentication provides a straightforward and basic layer of access control but does not offer robust security features for applications that require stringent access controls (e.g. multi-factor authentication, rate limiting, or automatic lockout policies).
+
+##### Custom user content
+
+Customize content for each user by accessing the network request directly:
+
+```python
+import gradio as gr
+
+def update_message(request: gr.Request):
+    return f"Welcome, {request.username}"
+
+with gr.Blocks() as demo:
+    m = gr.Markdown()
+    demo.load(update_message, None, m)
+    
+demo.launch(auth=[("Abubakar", "Abubakar"), ("Ali", "Ali")])
+```
+
+#### OAuth Authentication
+
+See <https://www.gradio.app/guides/sharing-your-app#o-auth-with-external-providers>
+
+## Styling
+
+### UI Layout
+
+#### `gr.Row`
+
+* `equal_height = false` will not force component on the same row to have the same height
+* experiment with `variant = 'panel'` or `variant = 'compact'` for different look
+
+#### `gr.Column`
+
+* experiment with `variant = 'panel'` or `variant = 'compact'` for different look
+
+#### `gr.Block`
+
+* `fill_height = True` and `fill_width = True` can be used to fill browser window
+
+#### `gr.Component`
+
+* `scale = 0` can be used to prevent component from expanding to take up space.
+
+### DataFrame styling
+
+See <https://www.gradio.app/guides/styling-the-gradio-dataframe>
+
+### Themes
+
+```python
+with gr.Blocks(theme=gr.themes.Glass()):
+...
+```
+
+See this [theming guide](https://www.gradio.app/guides/theming-guide) for how to create new custom themes both using the gradio theme builder
+
+### Custom CSS
+
+Change background color to red:
+
+```python
+with gr.Blocks(css=".gradio-container {background-color: red}") as demo:
+...
+```
+
+Set background to image file:
+
+```python
+with gr.Blocks(css=".gradio-container {background: url('file=clouds.jpg')}") as demo:
+...
+```
+
+#### Customize Component style
+
+Use `elem_id` and `elem_classes` when instantiating component. This will allow you to select elements more easily with CSS:
+
+```python
+css = """
+#warning {background-color: #FFCCCB}
+.feedback textarea {font-size: 24px !important}
+"""
+
+with gr.Blocks(css=css) as demo:
+    box1 = gr.Textbox(value="Good Job", elem_classes="feedback")
+    box2 = gr.Textbox(value="Failure", elem_id="warning", elem_classes="feedback")
+```
+
+* `elem_id` adds an HTML element id to the specific component
+* `elem_classes`adds a class or list of classes to the component.
+
+## Custom front-end logic
+
+### Custom Javascript
+
+You can add javascript
+
+* as a string or file path when instantiating a block:
+```blocks(js = path or string)```
+  * Javascript will be executed when app loads?
+* as a string to an event listener. This javascript code will be executed before the main function attached to the event listner.
+* add javascript code to the head param of the blocks initializer. This will add the code to the head of the HTML document:
+
+    ```python
+    head = f"""
+    <script async src="https://www.googletagmanager.com/gtag/js?id={google_analytics_tracking_id}"></script>
+    <script>
+        window.dataLayer = window.dataLayer || [];
+        function gtag(){{dataLayer.push(arguments);}}
+        gtag('js', new Date());
+        gtag('config', '{google_analytics_tracking_id}');
+    </script>
+    """
+
+    with gr.Blocks(head=head) as demo:
+        ...demo code...
+    ```
+
+### Custom Components
+
+See <https://www.gradio.app/guides/custom-components-in-five-minutes>
+
+## Connecting to databases
+
+Might be useful when we need to retrieve voice models hosted online later.
+
+Can import data using a combination of `sqlalchemy.create_engine` and `pandas.read_sql_query`:
+
+```python
+from sqlalchemy import create_engine
+import pandas as pd
+
+engine = create_engine('sqlite:///your_database.db')
+
+with gr.Blocks() as demo:
+    origin = gr.Dropdown(["DFW", "DAL", "HOU"], value="DFW", label="Origin")
+
+    gr.LinePlot(
+        lambda origin: pd.read_sql_query(
+            f"SELECT time, price from flight_info WHERE origin = {origin};", 
+            engine
+        ), inputs=origin, x="time", y="price")
+```
+
+## Sharing a Gradio App
+
+### Direct sharing
+
+* You can do `Blocks.launch(share = True)` to launch app on a public link that expires in 72 hours
+* IT is possible to set up your own Share Server on your own cloud server to overcome this restriction
+  * See <https://github.com/huggingface/frp/>
+
+### Embedding hosted HF space
+
+You can embed a gradio app hosted on huggingface spaces into any other web app.
+
+## Gradio app in production
+
+Useful information for migrating gradio app to production.
+
+### App hosting
+
+#### Custom web-server with Nginx
+
+see <https://www.gradio.app/guides/running-gradio-on-your-web-server-with-nginx>
+
+#### Deploying a gradio app with docker
+
+See <https://www.gradio.app/guides/deploying-gradio-with-docker>
+
+#### Running serverless apps
+
+Web apps hosted completely in your browser (without any server for backend) can be implemented using a combination of Gradio lite + transformers.js.
+
+More information:
+
+* <https://www.gradio.app/guides/gradio-lite>
+* <https://www.gradio.app/guides/gradio-lite-and-transformers-js>
+
+#### Zero-GPU spaces
+
+In development.
+
+see <https://www.gradio.app/main/docs/python-client/using-zero-gpu-spaces>
+
+#### Analytics dashboard
+
+Used for monitoring traffic.
+
+Analytics can be disabled by setting `analytics_enabled = False` as argument to `gr.Blocks()`
+
+### Gradio App as API
+
+Each gradio app has a button that redirects you to documentation for a corresponding API. This API can be called via:
+
+* Dedicated [Python](https://www.gradio.app/guides/getting-started-with-the-python-client) or [Javascript](https://www.gradio.app/guides/getting-started-with-the-js-client) API clients.
+* [Curl](https://www.gradio.app/guides/querying-gradio-apps-with-curl)
+* Community made [Rust client](https://www.gradio.app/docs/third-party-clients/rust-client).
+
+Alternatively, one can
+
+* mount gradio app within existing fastapi application
+* do a combination where the python gradio client is used inside fastapi app to query an endpoint from a gradio app.
+
+#### Mounting app within FastAPI app
+
+```python
+from fastapi import FastAPI
+import gradio as gr
+
+CUSTOM_PATH = "/gradio"
+
+app = FastAPI()
+
+@app.get("/")
+def read_main():
+    return {"message": "This is your main app"}
+
+io = gr.Interface(lambda x: "Hello, " + x + "!", "textbox", "textbox")
+app = gr.mount_gradio_app(app, io, path=CUSTOM_PATH)
+```
+
+* Run this from the terminal as you would normally start a FastAPI app: `uvicorn run:app`
+* and navigate to <http://localhost:8000/gradio> in your browser.
+
+#### Using a block context as a function to call
+
+```python
+english_translator = gr.load(name="spaces/gradio/english_translator")
+def generate_text(text):
+    english_text = english_generator(text)[0]["generated_text"]
+```
+
+If the app you are loading defines more than one function, you can specify which function to use with the `fn_index` and `api_name` parameters:
+
+```python
+translate_btn.click(translate, inputs=english, outputs=german, api_name="translate-to-german")
+....
+english_generator(text, api_name="translate-to-german")[0]["generated_text"]
+```
+
+#### Automatic API documentation
+
+1. Record api calls to generate snippets of calls made in app. Gradio
+
+2. Gradio can then reconstruct documentation describing what happened
+
+#### LLM agents
+
+LLM agents such as those defined using LangChain can call gradio apps and compose the results they produce.
+
+More information: <https://www.gradio.app/guides/gradio-and-llm-agents>

pyproject.toml

@@ -0,0 +1,225 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ultimate-rvc"
+version = "0.1.24"
+description = "Ultimate RVC"
+readme = "README.md"
+requires-python = "==3.12.*"
+dependencies = [
+    # General
+    "lib==4.0.0",
+
+    #Validation
+    "pydantic==2.9.2",
+
+    # CLI
+    "typer==0.12.5",
+    
+    # Networking
+    "requests==2.32.3",
+    "yt_dlp==2024.11.4",
+    "nodejs-wheel-binaries==22.11.0",
+    # TODO add these later
+    # "deemix",
+    # "wget",
+    # "flask",
+    # "beautifulsoup4",
+    # "pypresence",
+
+    # Data science
+    "numpy==1.26.4",
+    "scipy==1.14.1",
+    "matplotlib==3.9.2",
+    "tqdm==4.66.6",
+    "gradio==5.6.0",
+    
+    # Machine learning
+    "torch==2.5.1+cu124",
+    "torchaudio==2.5.1+cu124",
+    "torchcrepe==0.0.23",
+    "fairseq-fixed==0.12.3.1",
+    "faiss-cpu==1.9.0",
+    # Version of onnxruntime-gpu needs to align with what 
+    # version audio-separator package uses.
+    "onnxruntime-gpu==1.19.2", 
+    "tensorboardX==2.6.2.2",
+    # TODO add these later
+    # "tensorboard",
+    # "torchfcpe",
+    # "local-attention",
+    # "libf0",
+    # "einops",
+    # "numba; sys_platform == 'linux'",
+    # "numba==0.57.0; sys_platform == 'darwin' or sys_platform == 'win32'",
+    
+    # Audio
+    "static-ffmpeg==2.7",
+    "static-sox==1.0.1",
+    "typed-ffmpeg==2.1.0",
+    "soundfile==0.12.1",
+    "librosa==0.10.2",
+    "sox==1.5.0",
+    "pydub==0.25.1",
+    "pydub-stubs==0.25.1.2",
+    "pedalboard==0.9.16",
+    "audio-separator[gpu]==0.24.1",
+    "praat-parselmouth==0.4.5",
+    "pyworld-fixed==0.3.8",
+    "diffq==0.2.4"
+    # TODO add the later
+    # "noisereduce",
+    # "audio_upscaler==0.1.4",
+    # "edge-tts==6.1.9",
+    # "ffmpeg-python>=0.2.0",
+    # "ffmpy==0.3.1"
+]
+
+[project.scripts]
+urvc = "ultimate_rvc.cli.main:app"
+urvc-web = "ultimate_rvc.web.main:app_wrapper"
+
+[tool.uv]
+environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+cache-dir = "./uv/cache"
+compile-bytecode = true
+
+[tool.uv.sources]
+torch = { index = "torch-cu124"}
+torchaudio = { index = "torch-cu124"}
+diffq = { url = "https://huggingface.co/JackismyShephard/ultimate-rvc/resolve/main/diffq-0.2.4-cp312-cp312-win_amd64.whl", marker = "sys_platform == 'win32'"}
+
+[[tool.uv.index]]
+name = "torch-cu124"
+url = "https://download.pytorch.org/whl/cu124"
+explicit = true
+
+[tool.pyright]
+stubPath = "src/ultimate_rvc/stubs"
+pythonVersion = "3.12"
+pythonPlatform = "All"
+typeCheckingMode = "strict"
+ignore = ["**/.venv"]
+exclude = ["./uv"]
+
+[tool.black]
+target-version = ['py312']
+preview = true
+enable-unstable-feature = ["string_processing"]
+
+[tool.ruff]
+target-version = "py312"
+fix = true
+required-version = ">=0.5.7"
+
+[tool.ruff.format]
+docstring-code-format = true
+preview = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+extend-select = ["I"]
+ignore = [
+    # Ignore missing blank before between class name and docstring
+    "D203", 
+    # Do not require a description after summary line in docstring
+    "D205",
+    # Do not require summary line to be located on first physical line of docstring
+    "D212", 
+    # Do not require docstring section names to end with colon
+    "D416",  
+    # Ignore TODO notes
+    "FIX002",
+    "TD002",
+    "TD003",
+    "TD004",
+    # Ignore missing copyright notice
+    "CPY001", 
+    # Ignore function signatures with too many arguments
+    "PLR0913",
+    # ignore function signatures with too many positional arguments
+    "PLR0917", 
+    # Ignore boolean positional argument in function signature
+    "FBT002", 
+    "FBT001",
+]
+unfixable = ["F401"]
+preview = true
+
+[tool.ruff.lint.flake8-annotations]
+#ignore-fully-untyped = true
+
+[tool.ruff.lint.isort]
+relative-imports-order = "closest-to-furthest"
+section-order = [
+    "future",
+    "typing",
+    "standard-library",
+    "third-party",
+    "networking",
+    "validation",
+    "data-science",
+    "machine-learning",
+    "audio",
+    "cli",
+    "first-party",
+    "ultimate_rvc",
+    "local-folder",
+]
+
+[tool.ruff.lint.isort.sections]
+"typing" = ["typing", "typing_extensions"]
+"networking" = [
+    "requests",
+    "yt_dlp",
+    "deemix",
+    "wget",
+    "flask",
+    "beautifulsoup4",
+    "pypresence",
+]
+"validation" = ["pydantic"]
+"data-science" = [
+    "numpy", 
+    "scipy", 
+    "matplotlib", 
+    "tqdm", 
+    "pandas", 
+    "gradio"
+]
+"machine-learning" = [
+    "torch",
+    "torchaudio",
+    "torchcrepe",
+    "fairseq",
+    "faiss",
+    "tensorboard",
+    "torchfcpe",
+    "local_attention",
+    "libf0",
+    "einops",
+    "numba",
+]
+"audio" = [
+    "static_ffmpeg",
+    "static_sox",
+    "ffmpeg",
+    "soundfile",
+    "librosa",
+    "sox",
+    "pydub",
+    "pedalboard",
+    "audio_separator",
+    "parselmouth",
+    "pyworld",
+    "noisereduce",
+    "audio_upscaler",
+    "edge_tts",
+    "ffmpy",
+]
+"cli" = ["typer", "rich"]
+"ultimate_rvc" = ["ultimate_rvc"]
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 72

src/ultimate_rvc/__init__.py

@@ -0,0 +1,40 @@
+"""The Ultimate RVC project."""
+
+import logging
+import os
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from ultimate_rvc.common import BASE_DIR
+
+logger = logging.getLogger()
+
+URVC_NO_LOGGING = os.getenv("URVC_NO_LOGGING", "0") == "1"
+URVC_LOGS_DIR = Path(os.getenv("URVC_LOGS_DIR") or BASE_DIR / "logs")
+URVC_CONSOLE_LOG_LEVEL = os.getenv("URVC_CONSOLE_LOG_LEVEL", "ERROR")
+URVC_FILE_LOG_LEVEL = os.getenv("URVC_FILE_LOG_LEVEL", "INFO")
+
+if URVC_NO_LOGGING:
+    logging.basicConfig(handlers=[logging.NullHandler()])
+
+else:
+    stream_handler = logging.StreamHandler()
+    stream_handler.setLevel(URVC_CONSOLE_LOG_LEVEL)
+
+    URVC_LOGS_DIR.mkdir(exist_ok=True, parents=True)
+    file_handler = RotatingFileHandler(
+        URVC_LOGS_DIR / "ultimate_rvc.log",
+        mode="a",
+        maxBytes=1024 * 1024 * 5,
+        backupCount=1,
+        encoding="utf-8",
+    )
+    file_handler.setLevel(URVC_FILE_LOG_LEVEL)
+
+    logging.basicConfig(
+        format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        style="%",
+        level=logging.DEBUG,
+        handlers=[stream_handler, file_handler],
+    )

src/ultimate_rvc/cli/__init__.py

@@ -0,0 +1,8 @@
+"""
+Package which defines the command-line interface for the Ultimate RVC
+project.
+"""
+
+from ultimate_rvc.core.main import initialize
+
+initialize()

src/ultimate_rvc/cli/generate/song_cover.py

@@ -0,0 +1,409 @@
+"""
+Module which defines the command-line interface for generating a song
+cover.
+"""
+
+from typing import Annotated
+
+from pathlib import Path
+
+import typer
+from rich import print as rprint
+from rich.panel import Panel
+from rich.table import Table
+
+from ultimate_rvc.core.generate.song_cover import run_pipeline as _run_pipeline
+from ultimate_rvc.core.generate.song_cover import to_wav as _to_wav
+from ultimate_rvc.typing_extra import AudioExt, F0Method
+
+app = typer.Typer(
+    name="song-cover",
+    no_args_is_help=True,
+    help="Generate song covers",
+    rich_markup_mode="markdown",
+)
+
+
+def complete_name(incomplete: str, enumeration: list[str]) -> list[str]:
+    """
+    Return a list of names that start with the incomplete string.
+
+    Parameters
+    ----------
+    incomplete : str
+        The incomplete string to complete.
+    enumeration : list[str]
+        The list of names to complete from.
+
+    Returns
+    -------
+    list[str]
+        The list of names that start with the incomplete string.
+
+    """
+    return [name for name in list(enumeration) if name.startswith(incomplete)]
+
+
+def complete_audio_ext(incomplete: str) -> list[str]:
+    """
+    Return a list of audio extensions that start with the incomplete
+    string.
+
+    Parameters
+    ----------
+    incomplete : str
+        The incomplete string to complete.
+
+    Returns
+    -------
+    list[str]
+        The list of audio extensions that start with the incomplete
+        string.
+
+    """
+    return complete_name(incomplete, list(AudioExt))
+
+
+def complete_f0_method(incomplete: str) -> list[str]:
+    """
+    Return a list of F0 methods that start with the incomplete string.
+
+    Parameters
+    ----------
+    incomplete : str
+        The incomplete string to complete.
+
+    Returns
+    -------
+    list[str]
+        The list of F0 methods that start with the incomplete string.
+
+    """
+    return complete_name(incomplete, list(F0Method))
+
+
+@app.command(no_args_is_help=True)
+def to_wav(
+    audio_track: Annotated[
+        Path,
+        typer.Argument(
+            help="The path to the audio track to convert.",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            resolve_path=True,
+        ),
+    ],
+    song_dir: Annotated[
+        Path,
+        typer.Argument(
+            help=(
+                "The path to the song directory where the converted audio track will be"
+                " saved."
+            ),
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            resolve_path=True,
+        ),
+    ],
+    prefix: Annotated[
+        str,
+        typer.Argument(
+            help="The prefix to use for the name of the converted audio track.",
+        ),
+    ],
+    accepted_format: Annotated[
+        list[AudioExt] | None,
+        typer.Option(
+            case_sensitive=False,
+            autocompletion=complete_audio_ext,
+            help=(
+                "An audio format to accept for conversion. This option can be used"
+                " multiple times to accept multiple formats. If not provided, the"
+                " default accepted formats are mp3, ogg, flac, m4a and aac."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """
+    Convert a given audio track to wav format if its current format
+    is an accepted format. See the --accepted-formats option for more
+    information on accepted formats.
+
+    """
+    rprint()
+    wav_path = _to_wav(
+        audio_track=audio_track,
+        song_dir=song_dir,
+        prefix=prefix,
+        accepted_formats=set(accepted_format) if accepted_format else None,
+    )
+    if wav_path == audio_track:
+        rprint(
+            "[+] Audio track was not converted to WAV format. Presumably, "
+            "its format is not in the given list of accepted formats.",
+        )
+    else:
+        rprint("[+] Audio track succesfully converted to WAV format!")
+        rprint(Panel(f"[green]{wav_path}", title="WAV Audio Track Path"))
+
+
+@app.command(no_args_is_help=True)
+def run_pipeline(
+    source: Annotated[
+        str,
+        typer.Argument(
+            help=(
+                "A Youtube URL, the path to a local audio file or the path to a"
+                " song directory."
+            ),
+        ),
+    ],
+    model_name: Annotated[
+        str,
+        typer.Argument(help="The name of the voice model to use for vocal conversion."),
+    ],
+    n_octaves: Annotated[
+        int,
+        typer.Option(
+            rich_help_panel="Vocal Conversion Options",
+            help=(
+                "The number of octaves to pitch-shift the converted vocals by.Use 1 for"
+                " male-to-female and -1 for vice-versa."
+            ),
+        ),
+    ] = 0,
+    n_semitones: Annotated[
+        int,
+        typer.Option(
+            rich_help_panel="Vocal Conversion Options",
+            help=(
+                "The number of semi-tones to pitch-shift the converted vocals,"
+                " instrumentals, and backup vocals by. Altering this slightly reduces"
+                " sound quality"
+            ),
+        ),
+    ] = 0,
+    f0_method: Annotated[
+        F0Method,
+        typer.Option(
+            case_sensitive=False,
+            autocompletion=complete_f0_method,
+            rich_help_panel="Vocal Conversion Options",
+            help=(
+                "The method to use for pitch detection during vocal conversion. Best"
+                " option is RMVPE (clarity in vocals), then Mangio-Crepe (smoother"
+                " vocals)."
+            ),
+        ),
+    ] = F0Method.RMVPE,
+    index_rate: Annotated[
+        float,
+        typer.Option(
+            min=0,
+            max=1,
+            rich_help_panel="Vocal Conversion Options",
+            help=(
+                "A decimal number e.g. 0.5, Controls how much of the accent in the"
+                " voice model to keep in the converted vocals. Increase to bias the"
+                " conversion towards the accent of the voice model."
+            ),
+        ),
+    ] = 0.5,
+    filter_radius: Annotated[
+        int,
+        typer.Option(
+            min=0,
+            max=7,
+            rich_help_panel="Vocal Conversion Options",
+            help=(
+                "A number between 0 and 7. If >=3: apply median filtering to the pitch"
+                " results harvested during vocal conversion. Can help reduce"
+                " breathiness in the converted vocals."
+            ),
+        ),
+    ] = 3,
+    rms_mix_rate: Annotated[
+        float,
+        typer.Option(
+            min=0,
+            max=1,
+            rich_help_panel="Vocal Conversion Options",
+            help=(
+                "A decimal number e.g. 0.25. Controls how much to mimic the loudness of"
+                " the input vocals (0) or a fixed loudness (1) during vocal conversion."
+            ),
+        ),
+    ] = 0.25,
+    protect: Annotated[
+        float,
+        typer.Option(
+            min=0,
+            max=0.5,
+            rich_help_panel="Vocal Conversion Options",
+            help=(
+                "A decimal number e.g. 0.33. Controls protection of voiceless"
+                " consonants and breath sounds during vocal conversion. Decrease to"
+                " increase protection at the cost of indexing accuracy. Set to 0.5 to"
+                " disable."
+            ),
+        ),
+    ] = 0.33,
+    hop_length: Annotated[
+        int,
+        typer.Option(
+            rich_help_panel="Vocal Conversion Options",
+            help=(
+                "Controls how often the CREPE-based pitch detection algorithm checks"
+                " for pitch changes during vocal conversion. Measured in milliseconds."
+                " Lower values lead to longer conversion times and a higher risk of"
+                " voice cracks, but better pitch accuracy. Recommended value: 128."
+            ),
+        ),
+    ] = 128,
+    room_size: Annotated[
+        float,
+        typer.Option(
+            min=0,
+            max=1,
+            rich_help_panel="Vocal Post-processing Options",
+            help=(
+                "The room size of the reverb effect applied to the converted vocals."
+                " Increase for longer reverb time. Should be a value between 0 and 1."
+            ),
+        ),
+    ] = 0.15,
+    wet_level: Annotated[
+        float,
+        typer.Option(
+            min=0,
+            max=1,
+            rich_help_panel="Vocal Post-processing Options",
+            help=(
+                "The loudness of the converted vocals with reverb effect applied."
+                " Should be a value between 0 and 1"
+            ),
+        ),
+    ] = 0.2,
+    dry_level: Annotated[
+        float,
+        typer.Option(
+            min=0,
+            max=1,
+            rich_help_panel="Vocal Post-processing Options",
+            help=(
+                "The loudness of the converted vocals wihout reverb effect applied."
+                " Should be a value between 0 and 1."
+            ),
+        ),
+    ] = 0.8,
+    damping: Annotated[
+        float,
+        typer.Option(
+            min=0,
+            max=1,
+            rich_help_panel="Vocal Post-processing Options",
+            help=(
+                "The absorption of high frequencies in the reverb effect applied to the"
+                " converted vocals. Should be a value between 0 and 1."
+            ),
+        ),
+    ] = 0.7,
+    main_gain: Annotated[
+        int,
+        typer.Option(
+            rich_help_panel="Audio Mixing Options",
+            help="The gain to apply to the post-processed vocals. Measured in dB.",
+        ),
+    ] = 0,
+    inst_gain: Annotated[
+        int,
+        typer.Option(
+            rich_help_panel="Audio Mixing Options",
+            help=(
+                "The gain to apply to the pitch-shifted instrumentals. Measured in dB."
+            ),
+        ),
+    ] = 0,
+    backup_gain: Annotated[
+        int,
+        typer.Option(
+            rich_help_panel="Audio Mixing Options",
+            help=(
+                "The gain to apply to the pitch-shifted backup vocals. Measured in dB."
+            ),
+        ),
+    ] = 0,
+    output_sr: Annotated[
+        int,
+        typer.Option(
+            rich_help_panel="Audio Mixing Options",
+            help="The sample rate of the song cover.",
+        ),
+    ] = 44100,
+    output_format: Annotated[
+        AudioExt,
+        typer.Option(
+            case_sensitive=False,
+            autocompletion=complete_audio_ext,
+            rich_help_panel="Audio Mixing Options",
+            help="The audio format of the song cover.",
+        ),
+    ] = AudioExt.MP3,
+    output_name: Annotated[
+        str | None,
+        typer.Option(
+            rich_help_panel="Audio Mixing Options",
+            help="The name of the song cover.",
+        ),
+    ] = None,
+) -> None:
+    """Run the song cover generation pipeline."""
+    [song_cover_path, *intermediate_audio_file_paths] = _run_pipeline(
+        source=source,
+        model_name=model_name,
+        n_octaves=n_octaves,
+        n_semitones=n_semitones,
+        f0_method=f0_method,
+        index_rate=index_rate,
+        filter_radius=filter_radius,
+        rms_mix_rate=rms_mix_rate,
+        protect=protect,
+        hop_length=hop_length,
+        room_size=room_size,
+        wet_level=wet_level,
+        dry_level=dry_level,
+        damping=damping,
+        main_gain=main_gain,
+        inst_gain=inst_gain,
+        backup_gain=backup_gain,
+        output_sr=output_sr,
+        output_format=output_format,
+        output_name=output_name,
+        progress_bar=None,
+    )
+    table = Table()
+    table.add_column("Type")
+    table.add_column("Path")
+    for name, path in zip(
+        [
+            "Song",
+            "Vocals",
+            "Instrumentals",
+            "Main vocals",
+            "Backup vocals",
+            "De-reverbed main vocals",
+            "Main vocals reverb",
+            "Converted vocals",
+            "Post-processed vocals",
+            "Pitch-shifted instrumentals",
+            "Pitch-shifted backup vocals",
+        ],
+        intermediate_audio_file_paths,
+        strict=True,
+    ):
+        table.add_row(name, f"[green]{path}")
+    rprint("[+] Song cover succesfully generated!")
+    rprint(Panel(f"[green]{song_cover_path}", title="Song Cover Path"))
+    rprint(Panel(table, title="Intermediate Audio Files"))

src/ultimate_rvc/cli/main.py

@@ -0,0 +1,21 @@
+"""
+Module which defines the command-line interface for the Ultimate RVC
+project.
+"""
+
+import typer
+
+from ultimate_rvc.cli.generate.song_cover import app as song_cover_app
+
+app = typer.Typer(
+    name="urvc-cli",
+    no_args_is_help=True,
+    help="CLI for the Ultimate RVC project",
+    rich_markup_mode="markdown",
+)
+
+app.add_typer(song_cover_app)
+
+
+if __name__ == "__main__":
+    app()

src/ultimate_rvc/common.py

@@ -0,0 +1,10 @@
+"""Common variables used in the Ultimate RVC project."""
+
+from pathlib import Path
+
+BASE_DIR = Path.cwd()
+MODELS_DIR = BASE_DIR / "models"
+RVC_MODELS_DIR = MODELS_DIR / "rvc"
+SEPARATOR_MODELS_DIR = MODELS_DIR / "audio_separator"
+AUDIO_DIR = BASE_DIR / "audio"
+TEMP_DIR = BASE_DIR / "temp"

src/ultimate_rvc/core/__init__.py

@@ -0,0 +1,7 @@
+"""
+core package for the Ultimate RVC project.
+
+This package contains modules for managing date and settings as well as
+generating audio using RVC based methods.
+
+"""

src/ultimate_rvc/core/common.py

@@ -0,0 +1,285 @@
+"""Common utility functions for the core of the Ultimate RVC project."""
+
+import hashlib
+import json
+import shutil
+from collections.abc import Sequence
+from pathlib import Path
+
+import requests
+
+from pydantic import AnyHttpUrl, TypeAdapter, ValidationError
+
+import gradio as gr
+
+from rich import print as rprint
+
+from ultimate_rvc.common import AUDIO_DIR, RVC_MODELS_DIR
+from ultimate_rvc.core.exceptions import Entity, HttpUrlError, NotFoundError
+from ultimate_rvc.typing_extra import Json, StrPath
+
+RVC_DOWNLOAD_URL = "https://huggingface.co/lj1995/VoiceConversionWebUI/resolve/main/"
+INTERMEDIATE_AUDIO_BASE_DIR = AUDIO_DIR / "intermediate"
+OUTPUT_AUDIO_DIR = AUDIO_DIR / "output"
+FLAG_FILE = RVC_MODELS_DIR / ".initialized"
+
+
+def display_progress(
+    message: str,
+    percentage: float | None = None,
+    progress_bar: gr.Progress | None = None,
+) -> None:
+    """
+    Display progress message and percentage in console and potentially
+    also Gradio progress bar.
+
+    Parameters
+    ----------
+    message : str
+        Message to display.
+    percentage : float, optional
+        Percentage to display.
+    progress_bar : gr.Progress, optional
+        The Gradio progress bar to update.
+
+    """
+    rprint(message)
+    if progress_bar is not None:
+        progress_bar(percentage, desc=message)
+
+
+def remove_suffix_after(text: str, occurrence: str) -> str:
+    """
+    Remove suffix after the first occurrence of a substring in a string.
+
+    Parameters
+    ----------
+    text : str
+        The string to remove the suffix from.
+    occurrence : str
+        The substring to remove the suffix after.
+
+    Returns
+    -------
+    str
+        The string with the suffix removed.
+
+    """
+    location = text.rfind(occurrence)
+    if location == -1:
+        return text
+    return text[: location + len(occurrence)]
+
+
+def copy_files_to_new_dir(files: Sequence[StrPath], directory: StrPath) -> None:
+    """
+    Copy files to a new directory.
+
+    Parameters
+    ----------
+    files : Sequence[StrPath]
+        Paths to the files to copy.
+    directory : StrPath
+        Path to the directory to copy the files to.
+
+    Raises
+    ------
+    NotFoundError
+        If a file does not exist.
+
+    """
+    dir_path = Path(directory)
+    dir_path.mkdir(parents=True)
+    for file in files:
+        file_path = Path(file)
+        if not file_path.exists():
+            raise NotFoundError(entity=Entity.FILE, location=file_path)
+        shutil.copyfile(file_path, dir_path / file_path.name)
+
+
+def copy_file_safe(src: StrPath, dest: StrPath) -> Path:
+    """
+    Copy a file to a new location, appending a number if a file with the
+    same name already exists.
+
+    Parameters
+    ----------
+    src : strPath
+        The source file path.
+    dest : strPath
+        The candidate destination file path.
+
+    Returns
+    -------
+    Path
+        The final destination file path.
+
+    """
+    dest_path = Path(dest)
+    src_path = Path(src)
+    dest_dir = dest_path.parent
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest_file = dest_path
+    counter = 1
+
+    while dest_file.exists():
+        dest_file = dest_dir / f"{dest_path.stem} ({counter}){src_path.suffix}"
+        counter += 1
+
+    shutil.copyfile(src, dest_file)
+    return dest_file
+
+
+def json_dumps(thing: Json) -> str:
+    """
+    Dump a JSON-serializable object to a JSON string.
+
+    Parameters
+    ----------
+    thing : Json
+        The JSON-serializable object to dump.
+
+    Returns
+    -------
+    str
+        The JSON string representation of the object.
+
+    """
+    return json.dumps(thing, ensure_ascii=False, indent=4)
+
+
+def json_dump(thing: Json, file: StrPath) -> None:
+    """
+    Dump a JSON-serializable object to a JSON file.
+
+    Parameters
+    ----------
+    thing : Json
+        The JSON-serializable object to dump.
+    file : StrPath
+        The path to the JSON file.
+
+    """
+    with Path(file).open("w", encoding="utf-8") as fp:
+        json.dump(thing, fp, ensure_ascii=False, indent=4)
+
+
+def json_load(file: StrPath, encoding: str = "utf-8") -> Json:
+    """
+    Load a JSON-serializable object from a JSON file.
+
+    Parameters
+    ----------
+    file : StrPath
+        The path to the JSON file.
+    encoding : str, default='utf-8'
+        The encoding of the JSON file.
+
+    Returns
+    -------
+    Json
+        The JSON-serializable object loaded from the JSON file.
+
+    """
+    with Path(file).open(encoding=encoding) as fp:
+        return json.load(fp)
+
+
+def get_hash(thing: Json, size: int = 5) -> str:
+    """
+    Get the hash of a JSON-serializable object.
+
+    Parameters
+    ----------
+    thing : Json
+        The JSON-serializable object to hash.
+    size : int, default=5
+        The size of the hash in bytes.
+
+    Returns
+    -------
+    str
+        The hash of the JSON-serializable object.
+
+    """
+    return hashlib.blake2b(
+        json_dumps(thing).encode("utf-8"),
+        digest_size=size,
+    ).hexdigest()
+
+
+# NOTE consider increasing size to 16 otherwise we might have problems
+# with hash collisions
+def get_file_hash(file: StrPath, size: int = 5) -> str:
+    """
+    Get the hash of a file.
+
+    Parameters
+    ----------
+    file : StrPath
+        The path to the file.
+    size : int, default=5
+        The size of the hash in bytes.
+
+    Returns
+    -------
+    str
+        The hash of the file.
+
+    """
+    with Path(file).open("rb") as fp:
+        file_hash = hashlib.file_digest(fp, lambda: hashlib.blake2b(digest_size=size))
+    return file_hash.hexdigest()
+
+
+def validate_url(url: str) -> None:
+    """
+    Validate a HTTP-based URL.
+
+    Parameters
+    ----------
+    url : str
+        The URL to validate.
+
+    Raises
+    ------
+    HttpUrlError
+        If the URL is invalid.
+
+    """
+    try:
+        TypeAdapter(AnyHttpUrl).validate_python(url)
+    except ValidationError:
+        raise HttpUrlError(url) from None
+
+
+def _download_base_model(url: str, name: str, directory: StrPath) -> None:
+    """
+    Download a base model and save it to an existing directory.
+
+    Parameters
+    ----------
+    url : str
+        An URL pointing to a location where a base model is hosted.
+    name : str
+        The name of the base model to download.
+    directory : str
+        The path to the directory where the base model should be saved.
+
+    """
+    dir_path = Path(directory)
+    with requests.get(f"{url}{name}", timeout=10) as r:
+        r.raise_for_status()
+        with (dir_path / name).open("wb") as f:
+            for chunk in r.iter_content(chunk_size=8192):
+                f.write(chunk)
+
+
+def download_base_models() -> None:
+    """Download base models."""
+    RVC_MODELS_DIR.mkdir(parents=True, exist_ok=True)
+    base_model_names = ["hubert_base.pt", "rmvpe.pt"]
+    for base_model_name in base_model_names:
+        if not Path(RVC_MODELS_DIR / base_model_name).is_file():
+            rprint(f"Downloading {base_model_name}...")
+            _download_base_model(RVC_DOWNLOAD_URL, base_model_name, RVC_MODELS_DIR)

src/ultimate_rvc/core/exceptions.py

@@ -0,0 +1,297 @@
+"""
+Module which defines custom exception and enumerations used when
+instiating and re-raising those exceptions.
+"""
+
+from enum import StrEnum
+
+from ultimate_rvc.typing_extra import StrPath
+
+
+class Entity(StrEnum):
+    """Enumeration of entities that can be provided."""
+
+    DIRECTORY = "directory"
+    DIRECTORIES = "directories"
+    FILE = "file"
+    FILES = "files"
+    URL = "URL"
+    MODEL_NAME = "model name"
+    MODEL_NAMES = "model names"
+    MODEL_FILE = "model file"
+    SOURCE = "source"
+    SONG_DIR = "song directory"
+    AUDIO_TRACK = "audio track"
+    AUDIO_TRACK_GAIN_PAIRS = "pairs of audio track and gain"
+    SONG = "song"
+    VOCALS_TRACK = "vocals track"
+    INSTRUMENTALS_TRACK = "instrumentals track"
+    BACKUP_VOCALS_TRACK = "backup vocals track"
+    MAIN_VOCALS_TRACK = "main vocals track"
+
+
+class Location(StrEnum):
+    """Enumeration of locations where entities can be found."""
+
+    INTERMEDIATE_AUDIO_ROOT = "the root of the intermediate audio base directory"
+    OUTPUT_AUDIO_ROOT = "the root of the output audio directory"
+    EXTRACTED_ZIP_FILE = "extracted zip file"
+
+
+class UIMessage(StrEnum):
+    """
+    Enumeration of messages that can be displayed in the UI
+    in place of core exception messages.
+    """
+
+    NO_AUDIO_TRACK = "No audio tracks provided."
+    NO_SONG_DIR = "No song directory selected."
+    NO_SONG_DIRS = (
+        "No song directories selected. Please select one or more song directories"
+        " containing intermediate audio files to delete."
+    )
+    NO_OUTPUT_AUDIO_FILES = (
+        "No files selected. Please select one or more output audio files to delete."
+    )
+    NO_UPLOADED_FILES = "No files selected."
+    NO_VOICE_MODEL = "No voice model selected."
+    NO_VOICE_MODELS = "No voice models selected."
+    NO_SOURCE = (
+        "No source provided. Please provide a valid Youtube URL, local audio file"
+        " or song directory."
+    )
+
+
+class NotProvidedError(ValueError):
+    """Raised when an entity is not provided."""
+
+    def __init__(self, entity: Entity, ui_msg: UIMessage | None = None) -> None:
+        """
+        Initialize a NotProvidedError instance.
+
+        Exception message will be formatted as:
+
+        "No `<entity>` provided."
+
+        Parameters
+        ----------
+        entity : Entity
+            The entity that was not provided.
+        ui_msg : UIMessage, default=None
+            Message which, if provided, is displayed in the UI
+            instead of the default exception message.
+
+        """
+        super().__init__(f"No {entity} provided.")
+        self.ui_msg = ui_msg
+
+
+class NotFoundError(OSError):
+    """Raised when an entity is not found."""
+
+    def __init__(
+        self,
+        entity: Entity,
+        location: StrPath | Location,
+        is_path: bool = True,
+    ) -> None:
+        """
+        Initialize a NotFoundError instance.
+
+        Exception message will be formatted as:
+
+        "`<entity>` not found `(`in `|` as:`)` `<location>`."
+
+        Parameters
+        ----------
+        entity : Entity
+            The entity that was not found.
+        location : StrPath | Location
+            The location where the entity was not found.
+        is_path : bool, default=True
+            Whether the location is a path to the entity.
+
+        """
+        proposition = "at:" if is_path else "in"
+        entity_cap = entity.capitalize() if not entity.isupper() else entity
+        super().__init__(
+            f"{entity_cap} not found {proposition} {location}",
+        )
+
+
+class VoiceModelNotFoundError(OSError):
+    """Raised when a voice model is not found."""
+
+    def __init__(self, name: str) -> None:
+        r"""
+        Initialize a VoiceModelNotFoundError instance.
+
+        Exception message will be formatted as:
+
+        'Voice model with name "`<name>`" not found.'
+
+        Parameters
+        ----------
+        name : str
+            The name of the voice model that was not found.
+
+        """
+        super().__init__(f'Voice model with name "{name}" not found.')
+
+
+class VoiceModelExistsError(OSError):
+    """Raised when a voice model already exists."""
+
+    def __init__(self, name: str) -> None:
+        r"""
+        Initialize a VoiceModelExistsError instance.
+
+        Exception message will be formatted as:
+
+        "Voice model with name '`<name>`' already exists. Please provide
+        a different name for your voice model."
+
+        Parameters
+        ----------
+        name : str
+            The name of the voice model that already exists.
+
+        """
+        super().__init__(
+            f'Voice model with name "{name}" already exists. Please provide a different'
+            " name for your voice model.",
+        )
+
+
+class InvalidLocationError(OSError):
+    """Raised when an entity is in a wrong location."""
+
+    def __init__(self, entity: Entity, location: Location, path: StrPath) -> None:
+        r"""
+        Initialize an InvalidLocationError instance.
+
+        Exception message will be formatted as:
+
+        "`<entity>` should be located in `<location>` but found at:
+        `<path>`"
+
+        Parameters
+        ----------
+        entity : Entity
+            The entity that is in a wrong location.
+        location : Location
+            The correct location for the entity.
+        path : StrPath
+            The path to the entity.
+
+        """
+        entity_cap = entity.capitalize() if not entity.isupper() else entity
+        super().__init__(
+            f"{entity_cap} should be located in {location} but found at: {path}",
+        )
+
+
+class HttpUrlError(OSError):
+    """Raised when a HTTP-based URL is invalid."""
+
+    def __init__(self, url: str) -> None:
+        """
+        Initialize a HttpUrlError instance.
+
+        Exception message will be formatted as:
+
+        "Invalid HTTP-based URL: `<url>`"
+
+        Parameters
+        ----------
+        url : str
+            The invalid HTTP-based URL.
+
+        """
+        super().__init__(
+            f"Invalid HTTP-based URL: {url}",
+        )
+
+
+class YoutubeUrlError(OSError):
+    """
+    Raised when an URL does not point to a YouTube video or
+    , potentially, a Youtube playlist.
+    """
+
+    def __init__(self, url: str, playlist: bool) -> None:
+        """
+        Initialize a YoutubeURlError instance.
+
+        Exception message will be formatted as:
+
+        "URL does not point to a YouTube video `[`or playlist`]`:
+         `<url>`"
+
+        Parameters
+        ----------
+        url : str
+            The URL that does not point to a YouTube video or playlist.
+        playlist : bool
+            Whether the URL might point to a YouTube playlist.
+
+        """
+        suffix = "or playlist" if playlist else ""
+        super().__init__(
+            f"Not able to access Youtube video {suffix} at: {url}",
+        )
+
+
+class UploadLimitError(ValueError):
+    """Raised when the upload limit for an entity is exceeded."""
+
+    def __init__(self, entity: Entity, limit: str | float) -> None:
+        """
+        Initialize an UploadLimitError instance.
+
+        Exception message will be formatted as:
+
+        "At most `<limit>` `<entity>` can be uploaded."
+
+        Parameters
+        ----------
+        entity : Entity
+            The entity for which the upload limit was exceeded.
+        limit : str
+            The upload limit.
+
+        """
+        super().__init__(f"At most {limit} {entity} can be uploaded.")
+
+
+class UploadFormatError(ValueError):
+    """
+    Raised when one or more uploaded entities have an invalid format
+    .
+    """
+
+    def __init__(self, entity: Entity, formats: list[str], multiple: bool) -> None:
+        """
+        Initialize an UploadFileFormatError instance.
+
+
+        Exception message will be formatted as:
+
+        "Only `<entity>` with the following formats can be uploaded
+        `(`by themselves | together`)`: `<formats>`."
+
+        Parameters
+        ----------
+        entity : Entity
+            The entity that was uploaded with an invalid format.
+        formats : list[str]
+            Valid formats.
+        multiple : bool
+            Whether multiple entities are uploaded.
+
+        """
+        suffix = "by themselves" if not multiple else "together (at most one of each)"
+        super().__init__(
+            f"Only {entity} with the following formats can be uploaded {suffix}:"
+            f" {', '.join(formats)}.",
+        )

src/ultimate_rvc/core/generate/__init__.py

@@ -0,0 +1,13 @@
+"""
+Package which defines modules that facilitate RVC based audio
+generation.
+"""
+
+import static_ffmpeg
+import static_sox
+
+from ultimate_rvc.core.common import download_base_models
+
+download_base_models()
+static_ffmpeg.add_paths()
+static_sox.add_paths()

src/ultimate_rvc/core/generate/song_cover.py

@@ -0,0 +1,1728 @@
+"""
+Module which defines functions that faciliatate song cover generation
+using RVC.
+"""
+
+import gc
+import logging
+import operator
+import shutil
+from collections.abc import Sequence
+from contextlib import suppress
+from functools import reduce
+from itertools import starmap
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+import yt_dlp
+
+from pydantic import ValidationError
+
+import gradio as gr
+
+import ffmpeg
+import soundfile as sf
+import sox
+from audio_separator.separator import Separator
+from pedalboard import Compressor, HighpassFilter, Reverb
+from pedalboard._pedalboard import Pedalboard  # noqa: PLC2701
+from pedalboard.io import AudioFile
+from pydub import AudioSegment
+from pydub import utils as pydub_utils
+
+from ultimate_rvc.common import RVC_MODELS_DIR, SEPARATOR_MODELS_DIR
+from ultimate_rvc.core.common import (
+    INTERMEDIATE_AUDIO_BASE_DIR,
+    OUTPUT_AUDIO_DIR,
+    copy_file_safe,
+    display_progress,
+    get_file_hash,
+    get_hash,
+    json_dump,
+    json_dumps,
+    json_load,
+    validate_url,
+)
+from ultimate_rvc.core.exceptions import (
+    Entity,
+    InvalidLocationError,
+    Location,
+    NotFoundError,
+    NotProvidedError,
+    UIMessage,
+    VoiceModelNotFoundError,
+    YoutubeUrlError,
+)
+from ultimate_rvc.core.typing_extra import (
+    AudioExtInternal,
+    ConvertedVocalsMetaData,
+    EffectedVocalsMetaData,
+    FileMetaData,
+    MixedSongMetaData,
+    PitchShiftMetaData,
+    SeparatedAudioMetaData,
+    SourceType,
+    StagedAudioMetaData,
+    WaveifiedAudioMetaData,
+)
+from ultimate_rvc.typing_extra import (
+    AudioExt,
+    F0Method,
+    Json,
+    SegmentSize,
+    SeparationModel,
+    StrPath,
+)
+from ultimate_rvc.vc.rvc import Config, get_vc, load_hubert, rvc_infer
+
+logger = logging.getLogger(__name__)
+
+
+def _get_audio_separator(
+    output_dir: StrPath = INTERMEDIATE_AUDIO_BASE_DIR,
+    output_format: str = AudioExt.WAV,
+    segment_size: int = SegmentSize.SEG_256,
+    sample_rate: int = 44100,
+) -> Separator:
+    """
+    Get an audio separator.
+
+    Parameters
+    ----------
+    output_dir : StrPath, default=INTERMEDIATE_AUDIO_BASE_DIR
+        The directory to save the separated audio to.
+    output_format : str, default=AudioExt.WAV
+        The format to save the separated audio in.
+    segment_size : int, default=SegmentSize.SEG_256
+        The segment size to use for separation.
+    sample_rate : int, default=44100
+        The sample rate to use for separation.
+
+    Returns
+    -------
+    Separator
+        An audio separator.
+
+    """
+    return Separator(
+        model_file_dir=SEPARATOR_MODELS_DIR,
+        output_dir=output_dir,
+        output_format=output_format,
+        sample_rate=sample_rate,
+        mdx_params={
+            "hop_length": 1024,
+            "segment_size": segment_size,
+            "overlap": 0.001,
+            "batch_size": 1,
+            "enable_denoise": False,
+        },
+    )
+
+
+def initialize_audio_separator(progress_bar: gr.Progress | None = None) -> None:
+    """
+    Initialize the audio separator by downloading the models it uses.
+
+    Parameters
+    ----------
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+
+    """
+    audio_separator = _get_audio_separator()
+    for i, separator_model in enumerate(SeparationModel):
+        if not Path(SEPARATOR_MODELS_DIR / separator_model).is_file():
+            display_progress(
+                f"Downloading {separator_model}...",
+                i / len(SeparationModel),
+                progress_bar,
+            )
+            audio_separator.download_model_files(separator_model)
+
+
+def _get_input_audio_path(directory: StrPath) -> Path | None:
+    """
+    Get the path to the input audio file in the provided directory, if
+    it exists.
+
+    The provided directory must be located in the root of the
+    intermediate audio base directory.
+
+    Parameters
+    ----------
+    directory : StrPath
+        The path to a directory.
+
+    Returns
+    -------
+    Path | None
+        The path to the input audio file in the provided directory, if
+        it exists.
+
+    Raises
+    ------
+    NotFoundError
+        If the provided path does not point to an existing directory.
+    InvalidLocationError
+        If the provided path is not located in the root of the
+        intermediate audio base directory"
+
+    """
+    dir_path = Path(directory)
+
+    if not dir_path.is_dir():
+        raise NotFoundError(entity=Entity.DIRECTORY, location=dir_path)
+
+    if dir_path.parent != INTERMEDIATE_AUDIO_BASE_DIR:
+        raise InvalidLocationError(
+            entity=Entity.DIRECTORY,
+            location=Location.INTERMEDIATE_AUDIO_ROOT,
+            path=dir_path,
+        )
+    # NOTE directory should never contain more than one element which
+    # matches the pattern "00_*"
+    return next(dir_path.glob("00_*"), None)
+
+
+def _get_input_audio_paths() -> list[Path]:
+    """
+    Get the paths to all input audio files in the intermediate audio
+    base directory.
+
+    Returns
+    -------
+    list[Path]
+        The paths to all input audio files in the intermediate audio
+        base directory.
+
+    """
+    # NOTE if we later add .json file for input then
+    # we need to exclude those here
+    return list(INTERMEDIATE_AUDIO_BASE_DIR.glob("*/00_*"))
+
+
+def get_named_song_dirs() -> list[tuple[str, str]]:
+    """
+    Get the names of all saved songs and the paths to the
+    directories where they are stored.
+
+    Returns
+    -------
+    list[tuple[str, Path]]
+        A list of tuples containing the name of each saved song
+        and the path to the directory where it is stored.
+
+    """
+    return sorted(
+        [
+            (
+                path.stem.removeprefix("00_"),
+                str(path.parent),
+            )
+            for path in _get_input_audio_paths()
+        ],
+        key=operator.itemgetter(0),
+    )
+
+
+def _get_model_name(
+    effected_vocals_track: StrPath | None = None,
+    song_dir: StrPath | None = None,
+) -> str:
+    """
+    Infer the name of the voice model used for vocal conversion from a
+    an effected vocals track in a given song directory.
+
+    If a voice model name cannot be inferred, "Unknown" is returned.
+
+    Parameters
+    ----------
+    effected_vocals_track : StrPath, optional
+        The path to an effected vocals track.
+    song_dir : StrPath, optional
+        The path to a song directory.
+
+    Returns
+    -------
+    str
+        The name of the voice model used for vocal conversion.
+
+    """
+    model_name = "Unknown"
+    if not (effected_vocals_track and song_dir):
+        return model_name
+    effected_vocals_path = Path(effected_vocals_track)
+    song_dir_path = Path(song_dir)
+    effected_vocals_json_path = song_dir_path / f"{effected_vocals_path.stem}.json"
+    if not effected_vocals_json_path.is_file():
+        return model_name
+    effected_vocals_dict = json_load(effected_vocals_json_path)
+    try:
+        effected_vocals_metadata = EffectedVocalsMetaData.model_validate(
+            effected_vocals_dict,
+        )
+    except ValidationError:
+        return model_name
+    converted_vocals_track_name = effected_vocals_metadata.vocals_track.name
+    converted_vocals_json_path = song_dir_path / Path(
+        converted_vocals_track_name,
+    ).with_suffix(
+        ".json",
+    )
+    if not converted_vocals_json_path.is_file():
+        return model_name
+    converted_vocals_dict = json_load(converted_vocals_json_path)
+    try:
+        converted_vocals_metadata = ConvertedVocalsMetaData.model_validate(
+            converted_vocals_dict,
+        )
+    except ValidationError:
+        return model_name
+    return converted_vocals_metadata.model_name
+
+
+def get_song_cover_name(
+    effected_vocals_track: StrPath | None = None,
+    song_dir: StrPath | None = None,
+    model_name: str | None = None,
+) -> str:
+    """
+    Generate a suitable name for a cover of a song based on the name
+    of that song and the voice model used for vocal conversion.
+
+    If the path of an existing song directory is provided, the name
+    of the song is inferred from that directory. If a voice model is not
+    provided but the path of an existing song directory and the path of
+    an effected vocals track in that directory are provided, then the
+    voice model is inferred from the effected vocals track.
+
+    Parameters
+    ----------
+    effected_vocals_track : StrPath, optional
+        The path to an effected vocals track.
+    song_dir : StrPath, optional
+        The path to a song directory.
+    model_name : str, optional
+        The name of a voice model.
+
+    Returns
+    -------
+    str
+        The song cover name
+
+    """
+    song_name = "Unknown"
+    if song_dir and (song_path := _get_input_audio_path(song_dir)):
+        song_name = song_path.stem.removeprefix("00_")
+    model_name = model_name or _get_model_name(effected_vocals_track, song_dir)
+
+    return f"{song_name} ({model_name} Ver)"
+
+
+def _get_youtube_id(url: str, ignore_playlist: bool = True) -> str:
+    """
+    Get the id of a YouTube video or playlist.
+
+    Parameters
+    ----------
+    url : str
+        URL which points to a YouTube video or playlist.
+    ignore_playlist : bool, default=True
+        Whether to get the id of the first video in a playlist or the
+        playlist id itself.
+
+    Returns
+    -------
+    str
+        The id of a YouTube video or playlist.
+
+    Raises
+    ------
+    YoutubeUrlError
+        If the provided URL does not point to a YouTube video
+        or playlist.
+
+    """
+    yt_id = None
+    validate_url(url)
+    query = urlparse(url)
+    if query.hostname == "youtu.be":
+        yt_id = query.query[2:] if query.path[1:] == "watch" else query.path[1:]
+
+    elif query.hostname in {"www.youtube.com", "youtube.com", "music.youtube.com"}:
+        if not ignore_playlist:
+            with suppress(KeyError):
+                yt_id = parse_qs(query.query)["list"][0]
+        elif query.path == "/watch":
+            yt_id = parse_qs(query.query)["v"][0]
+        elif query.path[:7] == "/watch/":
+            yt_id = query.path.split("/")[1]
+        elif query.path[:7] == "/embed/" or query.path[:3] == "/v/":
+            yt_id = query.path.split("/")[2]
+    if yt_id is None:
+        raise YoutubeUrlError(url=url, playlist=True)
+
+    return yt_id
+
+
+def init_song_dir(
+    source: str,
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> tuple[Path, SourceType]:
+    """
+    Initialize a directory for a song provided by a given source.
+
+
+    The song directory is initialized as follows:
+
+    * If the source is a YouTube URL, the id of the video which
+    that URL points to is extracted. A new song directory with the name
+    of that id is then created, if it does not already exist.
+    * If the source is a path to a local audio file, the hash of
+    that audio file is extracted. A new song directory with the name of
+    that hash is then created, if it does not already exist.
+    * if the source is a path to an existing song directory, then
+    that song directory is used as is.
+
+    Parameters
+    ----------
+    source : str
+        The source providing the song to initialize a directory for.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Returns
+    -------
+    song_dir : Path
+        The path to the initialized song directory.
+    source_type : SourceType
+        The type of source provided.
+
+    Raises
+    ------
+    NotProvidedError
+        If no source is provided.
+    InvalidLocationError
+        If a provided path points to a directory that is not located in
+        the root of the intermediate audio base directory.
+    NotFoundError
+        If the provided source is a path to a file that does not exist.
+
+    """
+    if not source:
+        raise NotProvidedError(entity=Entity.SOURCE, ui_msg=UIMessage.NO_SOURCE)
+    source_path = Path(source)
+
+    display_progress("[~] Initializing song directory...", percentage, progress_bar)
+
+    # if source is a path to an existing song directory
+    if source_path.is_dir():
+        if source_path.parent != INTERMEDIATE_AUDIO_BASE_DIR:
+            raise InvalidLocationError(
+                entity=Entity.DIRECTORY,
+                location=Location.INTERMEDIATE_AUDIO_ROOT,
+                path=source_path,
+            )
+        display_progress(
+            "[~] Using existing song directory...",
+            percentage,
+            progress_bar,
+        )
+        source_type = SourceType.SONG_DIR
+        return source_path, source_type
+
+    # if source is a URL
+    if urlparse(source).scheme == "https":
+        source_type = SourceType.URL
+        song_id = _get_youtube_id(source)
+
+    # if source is a path to a local audio file
+    elif source_path.is_file():
+        source_type = SourceType.FILE
+        song_id = get_file_hash(source_path)
+    else:
+        raise NotFoundError(entity=Entity.FILE, location=source_path)
+
+    song_dir_path = INTERMEDIATE_AUDIO_BASE_DIR / song_id
+
+    song_dir_path.mkdir(parents=True, exist_ok=True)
+
+    return song_dir_path, source_type
+
+
+# NOTE consider increasing hash_size to 16. Otherwise
+# we might have problems with hash collisions when using app as CLI
+def get_unique_base_path(
+    song_dir: StrPath,
+    prefix: str,
+    args_dict: Json,
+    hash_size: int = 5,
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> Path:
+    """
+    Get a unique base path (a path without any extension) for a file in
+    a song directory by hashing the arguments used to generate
+    the audio that is stored or will be stored in that file.
+
+    Parameters
+    ----------
+    song_dir :StrPath
+        The path to a song directory.
+    prefix : str
+        The prefix to use for the base path.
+    args_dict : Json
+        A JSON-serializable dictionary of named arguments used to
+        generate the audio that is stored or will be stored in a file
+        in the song directory.
+    hash_size : int, default=5
+        The size (in bytes) of the hash to use for the base path.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Returns
+    -------
+    Path
+        The unique base path for a file in a song directory.
+
+    Raises
+    ------
+    NotProvidedError
+        If no song directory is provided.
+
+    """
+    if not song_dir:
+        raise NotProvidedError(entity=Entity.SONG_DIR, ui_msg=UIMessage.NO_SONG_DIR)
+    song_dir_path = Path(song_dir)
+    dict_hash = get_hash(args_dict, size=hash_size)
+    while True:
+        base_path = song_dir_path / f"{prefix}_{dict_hash}"
+        json_path = base_path.with_suffix(".json")
+        if json_path.exists():
+            file_dict = json_load(json_path)
+            if file_dict == args_dict:
+                return base_path
+            display_progress("[~] Rehashing...", percentage, progress_bar)
+            dict_hash = get_hash(dict_hash, size=hash_size)
+        else:
+            return base_path
+
+
+def _get_youtube_audio(url: str, directory: StrPath) -> Path:
+    """
+    Download audio from a YouTube video.
+
+    Parameters
+    ----------
+    url : str
+        URL which points to a YouTube video.
+    directory : StrPath
+        The directory to save the downloaded audio file to.
+
+    Returns
+    -------
+    Path
+        The path to the downloaded audio file.
+
+    Raises
+    ------
+    YoutubeUrlError
+        If the provided URL does not point to a YouTube video.
+
+    """
+    validate_url(url)
+    outtmpl = str(Path(directory, "00_%(title)s"))
+    ydl_opts = {
+        "quiet": True,
+        "no_warnings": True,
+        "format": "bestaudio",
+        "outtmpl": outtmpl,
+        "ignoreerrors": True,
+        "nocheckcertificate": True,
+        "postprocessors": [
+            {
+                "key": "FFmpegExtractAudio",
+                "preferredcodec": "wav",
+                "preferredquality": 0,
+            },
+        ],
+    }
+    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+        result = ydl.extract_info(url, download=True)
+        if not result:
+            raise YoutubeUrlError(url, playlist=False)
+        file = ydl.prepare_filename(result, outtmpl=f"{outtmpl}.wav")
+
+    return Path(file)
+
+
+def retrieve_song(
+    source: str,
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> tuple[Path, Path]:
+    """
+    Retrieve a song from a source that can either be a YouTube URL, a
+    local audio file or a song directory.
+
+    Parameters
+    ----------
+    source : str
+        A Youtube URL, the path to a local audio file or the path to a
+        song directory.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Returns
+    -------
+    song : Path
+        The path to the retrieved song.
+    song_dir : Path
+        The path to the song directory containing the retrieved song.
+
+    Raises
+    ------
+    NotProvidedError
+        If no source is provided.
+
+    """
+    if not source:
+        raise NotProvidedError(entity=Entity.SOURCE, ui_msg=UIMessage.NO_SOURCE)
+
+    song_dir_path, source_type = init_song_dir(source, progress_bar, percentage)
+    song_path = _get_input_audio_path(song_dir_path)
+
+    if not song_path:
+        if source_type == SourceType.URL:
+            display_progress("[~] Downloading song...", percentage, progress_bar)
+            song_url = source.split("&")[0]
+            song_path = _get_youtube_audio(song_url, song_dir_path)
+
+        else:
+            display_progress("[~] Copying song...", percentage, progress_bar)
+            source_path = Path(source)
+            song_name = f"00_{source_path.name}"
+            song_path = song_dir_path / song_name
+            shutil.copyfile(source_path, song_path)
+
+    return song_path, song_dir_path
+
+
+def _validate_exists(
+    identifier: StrPath,
+    entity: Entity,
+) -> Path:
+    """
+    Validate that the provided identifier is not none and that it
+    identifies an existing entity, which can be either a voice model,
+    a song directory or an audio track.
+
+    Parameters
+    ----------
+    identifier : StrPath
+        The identifier to validate.
+    entity : Entity
+        The entity that the identifier should identify.
+
+    Returns
+    -------
+    Path
+        The path to the identified entity.
+
+    Raises
+    ------
+    NotProvidedError
+        If the identifier is None.
+    NotFoundError
+        If the identifier does not identify an existing entity.
+    VoiceModelNotFoundError
+        If the identifier does not identify an existing voice model.
+    NotImplementedError
+        If the provided entity is not supported.
+
+    """
+    match entity:
+        case Entity.MODEL_NAME:
+            if not identifier:
+                raise NotProvidedError(entity=entity, ui_msg=UIMessage.NO_VOICE_MODEL)
+            path = RVC_MODELS_DIR / identifier
+            if not path.is_dir():
+                raise VoiceModelNotFoundError(str(identifier))
+        case Entity.SONG_DIR:
+            if not identifier:
+                raise NotProvidedError(entity=entity, ui_msg=UIMessage.NO_SONG_DIR)
+            path = Path(identifier)
+            if not path.is_dir():
+                raise NotFoundError(entity=entity, location=path)
+        case (
+            Entity.SONG
+            | Entity.AUDIO_TRACK
+            | Entity.VOCALS_TRACK
+            | Entity.INSTRUMENTALS_TRACK
+            | Entity.MAIN_VOCALS_TRACK
+            | Entity.BACKUP_VOCALS_TRACK
+        ):
+            if not identifier:
+                raise NotProvidedError(entity=entity)
+            path = Path(identifier)
+            if not path.is_file():
+                raise NotFoundError(entity=entity, location=path)
+        case _:
+            error_msg = f"Entity {entity} not supported."
+            raise NotImplementedError(error_msg)
+    return path
+
+
+def _validate_all_exist(
+    identifier_entity_pairs: Sequence[tuple[StrPath, Entity]],
+) -> list[Path]:
+    """
+    Validate that all provided identifiers are not none and that they
+    identify existing entities, which can be either voice models, song
+    directories or audio tracks.
+
+    Parameters
+    ----------
+    identifier_entity_pairs : Sequence[tuple[StrPath, Entity]]
+        The pairs of identifiers and entities to validate.
+
+    Returns
+    -------
+    list[Path]
+        The paths to the identified entities.
+
+    """
+    return list(starmap(_validate_exists, identifier_entity_pairs))
+
+
+def separate_audio(
+    audio_track: StrPath,
+    song_dir: StrPath,
+    model_name: SeparationModel,
+    segment_size: int,
+    display_msg: str = "[~] Separating audio...",
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> tuple[Path, Path]:
+    """
+    Separate an audio track into a primary stem and a secondary stem.
+
+    Parameters
+    ----------
+    audio_track : StrPath
+        The path to the audio track to separate.
+    song_dir : StrPath
+        The path to the song directory where the separated primary stem
+        and secondary stem will be saved.
+    model_name : str
+        The name of the model to use for audio separation.
+    segment_size : int
+        The segment size to use for audio separation.
+    display_msg : str
+        The message to display when separating the audio track.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Returns
+    -------
+    primary_path : Path
+        The path to the separated primary stem.
+    secondary_path : Path
+        The path to the separated secondary stem.
+
+    """
+    audio_path, song_dir_path = _validate_all_exist(
+        [(audio_track, Entity.AUDIO_TRACK), (song_dir, Entity.SONG_DIR)],
+    )
+
+    args_dict = SeparatedAudioMetaData(
+        audio_track=FileMetaData(
+            name=audio_path.name,
+            hash_id=get_file_hash(audio_path),
+        ),
+        model_name=model_name,
+        segment_size=segment_size,
+    ).model_dump()
+
+    paths = [
+        get_unique_base_path(
+            song_dir_path,
+            prefix,
+            args_dict,
+            progress_bar=progress_bar,
+            percentage=percentage,
+        ).with_suffix(suffix)
+        for prefix in ["11_Stem_Primary", "11_Stem_Secondary"]
+        for suffix in [".wav", ".json"]
+    ]
+
+    (
+        primary_path,
+        primary_json_path,
+        secondary_path,
+        secondary_json_path,
+    ) = paths
+
+    if not all(path.exists() for path in paths):
+        display_progress(display_msg, percentage, progress_bar)
+        audio_separator = _get_audio_separator(
+            output_dir=song_dir_path,
+            segment_size=segment_size,
+        )
+        audio_separator.load_model(model_name)
+        audio_separator.separate(
+            str(audio_path),
+            primary_output_name=primary_path.stem,
+            secondary_output_name=secondary_path.stem,
+        )
+        json_dump(args_dict, primary_json_path)
+        json_dump(args_dict, secondary_json_path)
+
+    return primary_path, secondary_path
+
+
+def _get_rvc_files(model_name: str) -> tuple[Path, Path | None]:
+    """
+    Get the RVC model file and potential index file of a voice model.
+
+    Parameters
+    ----------
+    model_name : str
+        The name of the voice model to get the RVC files of.
+
+    Returns
+    -------
+    model_file : Path
+        The path to the RVC model file.
+    index_file : Path | None
+        The path to the RVC index file, if it exists.
+
+    Raises
+    ------
+    NotFoundError
+        If no model file exists in the voice model directory.
+
+
+    """
+    model_dir_path = _validate_exists(model_name, Entity.MODEL_NAME)
+    file_path_map = {
+        ext: path
+        for path in model_dir_path.iterdir()
+        for ext in [".pth", ".index"]
+        if ext == path.suffix
+    }
+
+    if ".pth" not in file_path_map:
+        raise NotFoundError(
+            entity=Entity.MODEL_FILE,
+            location=model_dir_path,
+            is_path=False,
+        )
+
+    model_file = model_dir_path / file_path_map[".pth"]
+    index_file = (
+        model_dir_path / file_path_map[".index"] if ".index" in file_path_map else None
+    )
+
+    return model_file, index_file
+
+
+def _convert(
+    voice_track: StrPath,
+    output_file: StrPath,
+    model_name: str,
+    n_semitones: int = 0,
+    f0_method: F0Method = F0Method.RMVPE,
+    index_rate: float = 0.5,
+    filter_radius: int = 3,
+    rms_mix_rate: float = 0.25,
+    protect: float = 0.33,
+    hop_length: int = 128,
+    output_sr: int = 44100,
+) -> None:
+    """
+    Convert a voice track using a voice model and save the result to a
+    an output file.
+
+    Parameters
+    ----------
+    voice_track : StrPath
+        The path to the voice track to convert.
+    output_file : StrPath
+        The path to the file to save the converted voice track to.
+    model_name : str
+        The name of the model to use for voice conversion.
+    n_semitones : int, default=0
+        The number of semitones to pitch-shift the converted voice by.
+    f0_method : F0Method, default=F0Method.RMVPE
+        The method to use for pitch detection.
+    index_rate : float, default=0.5
+        The influence of the index file on the voice conversion.
+    filter_radius : int, default=3
+        The filter radius to use for the voice conversion.
+    rms_mix_rate : float, default=0.25
+        The blending rate of the volume envelope of the converted voice.
+    protect : float, default=0.33
+        The protection rate for consonants and breathing sounds.
+    hop_length : int, default=128
+        The hop length to use for crepe-based pitch detection.
+    output_sr : int, default=44100
+        The sample rate of the output audio file.
+
+    """
+    rvc_model_path, rvc_index_path = _get_rvc_files(model_name)
+    device = "cuda:0"
+    config = Config(device, is_half=True)
+    hubert_model = load_hubert(
+        device,
+        str(RVC_MODELS_DIR / "hubert_base.pt"),
+        is_half=config.is_half,
+    )
+    cpt, version, net_g, tgt_sr, vc = get_vc(
+        device,
+        config,
+        str(rvc_model_path),
+        is_half=config.is_half,
+    )
+
+    # convert main vocals
+    rvc_infer(
+        str(rvc_index_path) if rvc_index_path else "",
+        index_rate,
+        str(voice_track),
+        str(output_file),
+        n_semitones,
+        f0_method,
+        cpt,
+        version,
+        net_g,
+        filter_radius,
+        tgt_sr,
+        rms_mix_rate,
+        protect,
+        hop_length,
+        vc,
+        hubert_model,
+        output_sr,
+    )
+    del hubert_model, cpt
+    gc.collect()
+
+
+def convert(
+    vocals_track: StrPath,
+    song_dir: StrPath,
+    model_name: str,
+    n_octaves: int = 0,
+    n_semitones: int = 0,
+    f0_method: F0Method = F0Method.RMVPE,
+    index_rate: float = 0.5,
+    filter_radius: int = 3,
+    rms_mix_rate: float = 0.25,
+    protect: float = 0.33,
+    hop_length: int = 128,
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> Path:
+    """
+    Convert a vocals track using a voice model.
+
+    Parameters
+    ----------
+    vocals_track : StrPath
+        The path to the vocals track to convert.
+    song_dir : StrPath
+        The path to the song directory where the converted vocals track
+        will be saved.
+    model_name : str
+        The name of the model to use for vocal conversion.
+    n_octaves : int, default=0
+        The number of octaves to pitch-shift the converted vocals by.
+    n_semitones : int, default=0
+        The number of semitones to pitch-shift the converted vocals by.
+    f0_method : F0Method, default=F0Method.RMVPE
+        The method to use for pitch detection.
+    index_rate : float, default=0.5
+        The influence of the index file on the vocal conversion.
+    filter_radius : int, default=3
+        The filter radius to use for the vocal conversion.
+    rms_mix_rate : float, default=0.25
+        The blending rate of the volume envelope of the converted
+        vocals.
+    protect : float, default=0.33
+        The protection rate for consonants and breathing sounds.
+    hop_length : int, default=128
+        The hop length to use for crepe-based pitch detection.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Returns
+    -------
+    Path
+        The path to the converted vocals track.
+
+    """
+    vocals_path, song_dir_path, _ = _validate_all_exist(
+        [
+            (vocals_track, Entity.VOCALS_TRACK),
+            (song_dir, Entity.SONG_DIR),
+            (model_name, Entity.MODEL_NAME),
+        ],
+    )
+
+    n_semitones = n_octaves * 12 + n_semitones
+
+    args_dict = ConvertedVocalsMetaData(
+        vocals_track=FileMetaData(
+            name=vocals_path.name,
+            hash_id=get_file_hash(vocals_path),
+        ),
+        model_name=model_name,
+        n_semitones=n_semitones,
+        f0_method=f0_method,
+        index_rate=index_rate,
+        filter_radius=filter_radius,
+        rms_mix_rate=rms_mix_rate,
+        protect=protect,
+        hop_length=hop_length,
+    ).model_dump()
+
+    paths = [
+        get_unique_base_path(
+            song_dir_path,
+            "21_Vocals_Converted",
+            args_dict,
+            progress_bar=progress_bar,
+            percentage=percentage,
+        ).with_suffix(suffix)
+        for suffix in [".wav", ".json"]
+    ]
+
+    converted_vocals_path, converted_vocals_json_path = paths
+
+    if not all(path.exists() for path in paths):
+        display_progress("[~] Converting vocals using RVC...", percentage, progress_bar)
+        _convert(
+            vocals_path,
+            converted_vocals_path,
+            model_name,
+            n_semitones,
+            f0_method,
+            index_rate,
+            filter_radius,
+            rms_mix_rate,
+            protect,
+            hop_length,
+            output_sr=44100,
+        )
+        json_dump(args_dict, converted_vocals_json_path)
+    return converted_vocals_path
+
+
+def to_wav(
+    audio_track: StrPath,
+    song_dir: StrPath,
+    prefix: str,
+    accepted_formats: set[AudioExt] | None = None,
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> Path:
+    """
+    Convert a given audio track to wav format if its current format is
+    one of the given accepted formats.
+
+    Parameters
+    ----------
+    audio_track : StrPath
+        The path to the audio track to convert.
+    song_dir : StrPath
+        The path to the song directory where the converted audio track
+        will be saved.
+    prefix : str
+        The prefix to use for the name of the converted audio track.
+    accepted_formats : set[AudioExt], optional
+        The audio formats to accept for conversion. If None, the
+        accepted formats are mp3, ogg, flac, m4a and aac.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Returns
+    -------
+    Path
+        The path to the audio track in wav format or the original audio
+        track if it is not in one of the accepted formats.
+
+    """
+    if accepted_formats is None:
+        accepted_formats = set(AudioExt) - {AudioExt.WAV}
+
+    audio_path, song_dir_path = _validate_all_exist(
+        [(audio_track, Entity.AUDIO_TRACK), (song_dir, Entity.SONG_DIR)],
+    )
+
+    wav_path = audio_path
+
+    song_info = pydub_utils.mediainfo(str(audio_path))
+    logger.info("Song Info:\n%s", json_dumps(song_info))
+    if any(
+        accepted_format in song_info["format_name"]
+        if accepted_format == AudioExt.M4A
+        else accepted_format == song_info["format_name"]
+        for accepted_format in accepted_formats
+    ):
+        args_dict = WaveifiedAudioMetaData(
+            audio_track=FileMetaData(
+                name=audio_path.name,
+                hash_id=get_file_hash(audio_path),
+            ),
+        ).model_dump()
+
+        paths = [
+            get_unique_base_path(
+                song_dir_path,
+                prefix,
+                args_dict,
+                progress_bar=progress_bar,
+                percentage=percentage,
+            ).with_suffix(suffix)
+            for suffix in [".wav", ".json"]
+        ]
+        wav_path, wav_json_path = paths
+        if not all(path.exists() for path in paths):
+            display_progress(
+                "[~] Converting audio track to wav format...",
+                percentage,
+                progress_bar,
+            )
+
+            _, stderr = (
+                ffmpeg.input(audio_path)
+                .output(filename=wav_path, f="wav")
+                .run(
+                    overwrite_output=True,
+                    quiet=True,
+                )
+            )
+            logger.info("FFmpeg stderr:\n%s", stderr.decode("utf-8"))
+            json_dump(args_dict, wav_json_path)
+
+    return wav_path
+
+
+def _add_effects(
+    audio_track: StrPath,
+    output_file: StrPath,
+    room_size: float = 0.15,
+    wet_level: float = 0.2,
+    dry_level: float = 0.8,
+    damping: float = 0.7,
+) -> None:
+    """
+    Add high-pass filter, compressor and reverb effects to an audio
+    track.
+
+    Parameters
+    ----------
+    audio_track : StrPath
+        The path to the audio track to add effects to.
+    output_file : StrPath
+        The path to the file to save the effected audio track to.
+    room_size : float, default=0.15
+        The room size of the reverb effect.
+    wet_level : float, default=0.2
+        The wetness level of the reverb effect.
+    dry_level : float, default=0.8
+        The dryness level of the reverb effect.
+    damping : float, default=0.7
+        The damping of the reverb effect.
+
+    """
+    board = Pedalboard(
+        [
+            HighpassFilter(),
+            Compressor(ratio=4, threshold_db=-15),
+            Reverb(
+                room_size=room_size,
+                dry_level=dry_level,
+                wet_level=wet_level,
+                damping=damping,
+            ),
+        ],
+    )
+
+    with (
+        AudioFile(str(audio_track)) as f,
+        AudioFile(str(output_file), "w", f.samplerate, f.num_channels) as o,
+    ):
+        # Read one second of audio at a time, until the file is empty:
+        while f.tell() < f.frames:
+            chunk = f.read(int(f.samplerate))
+            effected = board(chunk, f.samplerate, reset=False)
+            o.write(effected)
+
+
+def postprocess(
+    vocals_track: StrPath,
+    song_dir: StrPath,
+    room_size: float = 0.15,
+    wet_level: float = 0.2,
+    dry_level: float = 0.8,
+    damping: float = 0.7,
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> Path:
+    """
+    Apply high-pass filter, compressor and reverb effects to a vocals
+    track.
+
+    Parameters
+    ----------
+    vocals_track : StrPath
+        The path to the vocals track to add effects to.
+    song_dir : StrPath
+        The path to the song directory where the effected vocals track
+        will be saved.
+    room_size : float, default=0.15
+        The room size of the reverb effect.
+    wet_level : float, default=0.2
+        The wetness level of the reverb effect.
+    dry_level : float, default=0.8
+        The dryness level of the reverb effect.
+    damping : float, default=0.7
+        The damping of the reverb effect.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Returns
+    -------
+    Path
+        The path to the effected vocals track.
+
+    """
+    vocals_path, song_dir_path = _validate_all_exist(
+        [(vocals_track, Entity.VOCALS_TRACK), (song_dir, Entity.SONG_DIR)],
+    )
+
+    vocals_path = to_wav(
+        vocals_path,
+        song_dir_path,
+        "30_Input",
+        accepted_formats={AudioExt.M4A, AudioExt.AAC},
+        progress_bar=progress_bar,
+        percentage=percentage,
+    )
+
+    args_dict = EffectedVocalsMetaData(
+        vocals_track=FileMetaData(
+            name=vocals_path.name,
+            hash_id=get_file_hash(vocals_path),
+        ),
+        room_size=room_size,
+        wet_level=wet_level,
+        dry_level=dry_level,
+        damping=damping,
+    ).model_dump()
+
+    paths = [
+        get_unique_base_path(
+            song_dir_path,
+            "31_Vocals_Effected",
+            args_dict,
+            progress_bar=progress_bar,
+            percentage=percentage,
+        ).with_suffix(suffix)
+        for suffix in [".wav", ".json"]
+    ]
+
+    effected_vocals_path, effected_vocals_json_path = paths
+
+    if not all(path.exists() for path in paths):
+        display_progress(
+            "[~] Applying audio effects to vocals...",
+            percentage,
+            progress_bar,
+        )
+        _add_effects(
+            vocals_path,
+            effected_vocals_path,
+            room_size,
+            wet_level,
+            dry_level,
+            damping,
+        )
+        json_dump(args_dict, effected_vocals_json_path)
+    return effected_vocals_path
+
+
+def _pitch_shift(audio_track: StrPath, output_file: StrPath, n_semi_tones: int) -> None:
+    """
+    Pitch-shift an audio track.
+
+    Parameters
+    ----------
+    audio_track : StrPath
+        The path to the audio track to pitch-shift.
+    output_file : StrPath
+        The path to the file to save the pitch-shifted audio track to.
+    n_semi_tones : int
+        The number of semi-tones to pitch-shift the audio track by.
+
+    """
+    y, sr = sf.read(audio_track)
+    tfm = sox.Transformer()
+    tfm.pitch(n_semi_tones)
+    y_shifted = tfm.build_array(input_array=y, sample_rate_in=sr)
+    sf.write(output_file, y_shifted, sr)
+
+
+def pitch_shift(
+    audio_track: StrPath,
+    song_dir: StrPath,
+    n_semitones: int,
+    display_msg: str = "[~] Pitch-shifting audio...",
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> Path:
+    """
+    Pitch shift an audio track by a given number of semi-tones.
+
+    Parameters
+    ----------
+    audio_track : StrPath
+        The path to the audio track to pitch shift.
+    song_dir : StrPath
+        The path to the song directory where the pitch-shifted audio
+        track will be saved.
+    n_semitones : int
+        The number of semi-tones to pitch-shift the audio track by.
+    display_msg : str
+        The message to display when pitch-shifting the audio track.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Returns
+    -------
+    Path
+        The path to the pitch-shifted audio track.
+
+    """
+    audio_path, song_dir_path = _validate_all_exist(
+        [(audio_track, Entity.AUDIO_TRACK), (song_dir, Entity.SONG_DIR)],
+    )
+
+    audio_path = to_wav(
+        audio_path,
+        song_dir_path,
+        "40_Input",
+        accepted_formats={AudioExt.M4A, AudioExt.AAC},
+        progress_bar=progress_bar,
+        percentage=percentage,
+    )
+
+    shifted_audio_path = audio_path
+
+    if n_semitones != 0:
+        args_dict = PitchShiftMetaData(
+            audio_track=FileMetaData(
+                name=audio_path.name,
+                hash_id=get_file_hash(audio_path),
+            ),
+            n_semitones=n_semitones,
+        ).model_dump()
+
+        paths = [
+            get_unique_base_path(
+                song_dir_path,
+                "41_Audio_Shifted",
+                args_dict,
+                progress_bar=progress_bar,
+                percentage=percentage,
+            ).with_suffix(suffix)
+            for suffix in [".wav", ".json"]
+        ]
+
+        shifted_audio_path, shifted_audio_json_path = paths
+
+        if not all(path.exists() for path in paths):
+            display_progress(display_msg, percentage, progress_bar)
+            _pitch_shift(audio_path, shifted_audio_path, n_semitones)
+            json_dump(args_dict, shifted_audio_json_path)
+
+    return shifted_audio_path
+
+
+def _to_internal(audio_ext: AudioExt) -> AudioExtInternal:
+    """
+    Map an audio extension to an internally recognized format.
+
+    Parameters
+    ----------
+    audio_ext : AudioExt
+        The audio extension to map.
+
+    Returns
+    -------
+    AudioExtInternal
+        The internal audio extension.
+
+    """
+    match audio_ext:
+        case AudioExt.M4A:
+            return AudioExtInternal.IPOD
+        case AudioExt.AAC:
+            return AudioExtInternal.ADTS
+        case _:
+            return AudioExtInternal(audio_ext)
+
+
+def _mix_song(
+    audio_track_gain_pairs: Sequence[tuple[StrPath, int]],
+    output_file: StrPath,
+    output_sr: int = 44100,
+    output_format: AudioExt = AudioExt.MP3,
+) -> None:
+    """
+    Mix multiple audio tracks to create a song.
+
+    Parameters
+    ----------
+    audio_track_gain_pairs : Sequence[tuple[StrPath, int]]
+        A sequence of pairs each containing the path to an audio track
+        and the gain to apply to it.
+    output_file : StrPath
+        The path to the file to save the mixed song to.
+    output_sr : int, default=44100
+        The sample rate of the mixed song.
+    output_format : AudioExt, default=AudioExt.MP3
+        The audio format of the mixed song.
+
+    """
+    mixed_audio = reduce(
+        lambda a1, a2: a1.overlay(a2),
+        [
+            AudioSegment.from_wav(audio_track) + gain
+            for audio_track, gain in audio_track_gain_pairs
+        ],
+    )
+    mixed_audio_resampled = mixed_audio.set_frame_rate(output_sr)
+    mixed_audio_resampled.export(
+        output_file,
+        format=_to_internal(output_format),
+    )
+
+
+def mix_song(
+    audio_track_gain_pairs: Sequence[tuple[StrPath, int]],
+    song_dir: StrPath,
+    output_sr: int = 44100,
+    output_format: AudioExt = AudioExt.MP3,
+    output_name: str | None = None,
+    display_msg: str = "[~] Mixing audio tracks...",
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> Path:
+    """
+    Mix multiple audio tracks to create a song.
+
+    Parameters
+    ----------
+    audio_track_gain_pairs : Sequence[tuple[StrPath, int]]
+        A sequence of pairs each containing the path to an audio track
+        and the gain to apply to it.
+    song_dir : StrPath
+        The path to the song directory where the song will be saved.
+    output_sr : int, default=44100
+        The sample rate of the mixed song.
+    output_format : AudioExt, default=AudioExt.MP3
+        The audio format of the mixed song.
+    output_name : str, optional
+        The name of the mixed song.
+    display_msg : str, default="[~] Mixing audio tracks..."
+        The message to display when mixing the audio tracks.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Returns
+    -------
+    Path
+        The path to the song cover.
+
+    Raises
+    ------
+    NotProvidedError
+        If no audio tracks are provided.
+
+    """
+    if not audio_track_gain_pairs:
+        raise NotProvidedError(
+            entity=Entity.AUDIO_TRACK_GAIN_PAIRS,
+            ui_msg=UIMessage.NO_AUDIO_TRACK,
+        )
+
+    audio_path_gain_pairs = [
+        (
+            to_wav(
+                _validate_exists(audio_track, Entity.AUDIO_TRACK),
+                song_dir,
+                "50_Input",
+                progress_bar=progress_bar,
+                percentage=percentage,
+            ),
+            gain,
+        )
+        for audio_track, gain in audio_track_gain_pairs
+    ]
+    song_dir_path = _validate_exists(song_dir, Entity.SONG_DIR)
+    args_dict = MixedSongMetaData(
+        staged_audio_tracks=[
+            StagedAudioMetaData(
+                audio_track=FileMetaData(
+                    name=audio_path.name,
+                    hash_id=get_file_hash(audio_path),
+                ),
+                gain=gain,
+            )
+            for audio_path, gain in audio_path_gain_pairs
+        ],
+        output_sr=output_sr,
+        output_format=output_format,
+    ).model_dump()
+
+    paths = [
+        get_unique_base_path(
+            song_dir_path,
+            "51_Mix",
+            args_dict,
+            progress_bar=progress_bar,
+            percentage=percentage,
+        ).with_suffix(suffix)
+        for suffix in ["." + output_format, ".json"]
+    ]
+
+    mix_path, mix_json_path = paths
+
+    if not all(path.exists() for path in paths):
+        display_progress(display_msg, percentage, progress_bar)
+
+        _mix_song(audio_path_gain_pairs, mix_path, output_sr, output_format)
+        json_dump(args_dict, mix_json_path)
+    output_name = output_name or get_song_cover_name(
+        audio_path_gain_pairs[0][0],
+        song_dir_path,
+        None,
+    )
+    song_path = OUTPUT_AUDIO_DIR / f"{output_name}.{output_format}"
+    return copy_file_safe(mix_path, song_path)
+
+
+def run_pipeline(
+    source: str,
+    model_name: str,
+    n_octaves: int = 0,
+    n_semitones: int = 0,
+    f0_method: F0Method = F0Method.RMVPE,
+    index_rate: float = 0.5,
+    filter_radius: int = 3,
+    rms_mix_rate: float = 0.25,
+    protect: float = 0.33,
+    hop_length: int = 128,
+    room_size: float = 0.15,
+    wet_level: float = 0.2,
+    dry_level: float = 0.8,
+    damping: float = 0.7,
+    main_gain: int = 0,
+    inst_gain: int = 0,
+    backup_gain: int = 0,
+    output_sr: int = 44100,
+    output_format: AudioExt = AudioExt.MP3,
+    output_name: str | None = None,
+    progress_bar: gr.Progress | None = None,
+) -> tuple[Path, ...]:
+    """
+    Run the song cover generation pipeline.
+
+    Parameters
+    ----------
+    source : str
+        A Youtube URL, the path to a local audio file or the path to a
+        song directory.
+    model_name : str
+        The name of the voice model to use for vocal conversion.
+    n_octaves : int, default=0
+        The number of octaves to pitch-shift the converted vocals by.
+    n_semitones : int, default=0
+        The number of semi-tones to pitch-shift the converted vocals,
+        instrumentals, and backup vocals by.
+    f0_method : F0Method, default=F0Method.RMVPE
+        The method to use for pitch detection during vocal conversion.
+    index_rate : float, default=0.5
+        The influence of the index file on the vocal conversion.
+    filter_radius : int, default=3
+        The filter radius to use for the vocal conversion.
+    rms_mix_rate : float, default=0.25
+        The blending rate of the volume envelope of the converted
+        vocals.
+    protect : float, default=0.33
+        The protection rate for consonants and breathing sounds during
+        vocal conversion.
+    hop_length : int, default=128
+        The hop length to use for crepe-based pitch detection.
+    room_size : float, default=0.15
+        The room size of the reverb effect to apply to the converted
+        vocals.
+    wet_level : float, default=0.2
+        The wetness level of the reverb effect to apply to the converted
+        vocals.
+    dry_level : float, default=0.8
+        The dryness level of the reverb effect to apply to the converted
+        vocals.
+    damping : float, default=0.7
+        The damping of the reverb effect to apply to the converted
+        vocals.
+    main_gain : int, default=0
+        The gain to apply to the post-processed vocals.
+    inst_gain : int, default=0
+        The gain to apply to the pitch-shifted instrumentals.
+    backup_gain : int, default=0
+        The gain to apply to the pitch-shifted backup vocals.
+    output_sr : int, default=44100
+        The sample rate of the song cover.
+    output_format : AudioExt, default=AudioExt.MP3
+        The audio format of the song cover.
+    output_name : str, optional
+        The name of the song cover.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+
+    Returns
+    -------
+    tuple[Path,...]
+        The path to the generated song cover and the paths to any
+        intermediate audio files that were generated.
+
+    """
+    _validate_exists(model_name, Entity.MODEL_NAME)
+    display_progress("[~] Starting song cover generation pipeline...", 0, progress_bar)
+    song, song_dir = retrieve_song(
+        source,
+        progress_bar=progress_bar,
+        percentage=0 / 9,
+    )
+    vocals_track, instrumentals_track = separate_audio(
+        song,
+        song_dir,
+        SeparationModel.UVR_MDX_NET_VOC_FT,
+        SegmentSize.SEG_512,
+        display_msg="[~] Separating vocals from instrumentals...",
+        progress_bar=progress_bar,
+        percentage=1 / 9,
+    )
+    backup_vocals_track, main_vocals_track = separate_audio(
+        vocals_track,
+        song_dir,
+        SeparationModel.UVR_MDX_NET_KARA_2,
+        SegmentSize.SEG_512,
+        display_msg="[~] Separating main vocals from backup vocals...",
+        progress_bar=progress_bar,
+        percentage=2 / 9,
+    )
+
+    reverb_track, vocals_dereverb_track = separate_audio(
+        main_vocals_track,
+        song_dir,
+        SeparationModel.REVERB_HQ_BY_FOXJOY,
+        SegmentSize.SEG_256,
+        display_msg="[~] De-reverbing vocals...",
+        progress_bar=progress_bar,
+        percentage=3 / 9,
+    )
+    converted_vocals_track = convert(
+        vocals_dereverb_track,
+        song_dir,
+        model_name,
+        n_octaves,
+        n_semitones,
+        f0_method,
+        index_rate,
+        filter_radius,
+        rms_mix_rate,
+        protect,
+        hop_length,
+        progress_bar=progress_bar,
+        percentage=4 / 9,
+    )
+    effected_vocals_track = postprocess(
+        converted_vocals_track,
+        song_dir,
+        room_size,
+        wet_level,
+        dry_level,
+        damping,
+        progress_bar=progress_bar,
+        percentage=5 / 9,
+    )
+    shifted_instrumentals_track = pitch_shift(
+        instrumentals_track,
+        song_dir,
+        n_semitones,
+        display_msg="[~] Pitch-shifting instrumentals...",
+        progress_bar=progress_bar,
+        percentage=6 / 9,
+    )
+
+    shifted_backup_vocals_track = pitch_shift(
+        backup_vocals_track,
+        song_dir,
+        n_semitones,
+        display_msg="[~] Pitch-shifting backup vocals...",
+        progress_bar=progress_bar,
+        percentage=7 / 9,
+    )
+
+    song_cover = mix_song(
+        [
+            (effected_vocals_track, main_gain),
+            (shifted_instrumentals_track, inst_gain),
+            (shifted_backup_vocals_track, backup_gain),
+        ],
+        song_dir,
+        output_sr,
+        output_format,
+        output_name,
+        display_msg="[~] Mixing main vocals, instrumentals, and backup vocals...",
+        progress_bar=progress_bar,
+        percentage=8 / 9,
+    )
+    return (
+        song_cover,
+        song,
+        vocals_track,
+        instrumentals_track,
+        main_vocals_track,
+        backup_vocals_track,
+        vocals_dereverb_track,
+        reverb_track,
+        converted_vocals_track,
+        effected_vocals_track,
+        shifted_instrumentals_track,
+        shifted_backup_vocals_track,
+    )

src/ultimate_rvc/core/main.py

@@ -0,0 +1,48 @@
+"""
+Module which defines functions for initializing the core of the Ultimate
+RVC project.
+"""
+
+from pathlib import Path
+
+from rich import print as rprint
+
+from ultimate_rvc.common import RVC_MODELS_DIR
+from ultimate_rvc.core.common import FLAG_FILE, download_base_models
+from ultimate_rvc.core.generate.song_cover import initialize_audio_separator
+from ultimate_rvc.core.manage.models import download_model
+
+
+def download_sample_models() -> None:
+    """Download sample RVC models."""
+    named_model_links = [
+        (
+            "https://huggingface.co/damnedraxx/TaylorSwift/resolve/main/TaylorSwift.zip",
+            "Taylor Swift",
+        ),
+        (
+            "https://huggingface.co/Vermiculos/balladjames/resolve/main/Ballad%20James.zip?download=true",
+            "James Hetfield",
+        ),
+        ("https://huggingface.co/ryolez/MMLP/resolve/main/MMLP.zip", "Eminem"),
+    ]
+    for model_url, model_name in named_model_links:
+        if not Path(RVC_MODELS_DIR / model_name).is_dir():
+            rprint(f"Downloading {model_name}...")
+            try:
+                download_model(model_url, model_name)
+            except Exception as e:
+                rprint(f"Failed to download {model_name}: {e}")
+
+
+def initialize() -> None:
+    """Initialize the Ultimate RVC project."""
+    download_base_models()
+    if not FLAG_FILE.is_file():
+        download_sample_models()
+        FLAG_FILE.touch()
+    initialize_audio_separator()
+
+
+if __name__ == "__main__":
+    initialize()

src/ultimate_rvc/core/manage/__init__.py

@@ -0,0 +1,4 @@
+"""
+Package which defines modules that facilitate managing settings and
+data.
+"""

src/ultimate_rvc/core/manage/audio.py

@@ -0,0 +1,214 @@
+"""Module which defines functions to manage audio files."""
+
+import operator
+import shutil
+from collections.abc import Sequence
+from pathlib import Path
+
+import gradio as gr
+
+from ultimate_rvc.core.common import (
+    INTERMEDIATE_AUDIO_BASE_DIR,
+    OUTPUT_AUDIO_DIR,
+    display_progress,
+)
+from ultimate_rvc.core.exceptions import (
+    Entity,
+    InvalidLocationError,
+    Location,
+    NotFoundError,
+    NotProvidedError,
+    UIMessage,
+)
+from ultimate_rvc.typing_extra import StrPath
+
+
+def get_saved_output_audio() -> list[tuple[str, str]]:
+    """
+    Get the name and path of all output audio files.
+
+    Returns
+    -------
+    list[tuple[str, Path]]
+        A list of tuples containing the name and path of each output
+        audio file.
+
+    """
+    if OUTPUT_AUDIO_DIR.is_dir():
+        named_output_files = [
+            (file_path.name, str(file_path)) for file_path in OUTPUT_AUDIO_DIR.iterdir()
+        ]
+        return sorted(named_output_files, key=operator.itemgetter(0))
+    return []
+
+
+def delete_intermediate_audio(
+    directories: Sequence[StrPath],
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> None:
+    """
+    Delete provided directories containing intermediate audio files.
+
+    The provided directories must be located in the root of the
+    intermediate audio base directory.
+
+    Parameters
+    ----------
+    directories : Sequence[StrPath]
+        Paths to directories containing intermediate audio files to
+        delete.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Raises
+    ------
+    NotProvidedError
+        If no paths are provided.
+    NotFoundError
+        if a provided path does not point to an existing directory.
+    InvalidLocationError
+        If a provided path does not point to a location in the root of
+        the intermediate audio base directory.
+
+    """
+    if not directories:
+        raise NotProvidedError(entity=Entity.DIRECTORIES, ui_msg=UIMessage.NO_SONG_DIRS)
+    display_progress(
+        "[~] Deleting directories ...",
+        percentage,
+        progress_bar,
+    )
+    for directory in directories:
+        dir_path = Path(directory)
+        if not dir_path.is_dir():
+            raise NotFoundError(entity=Entity.DIRECTORY, location=dir_path)
+        if dir_path.parent != INTERMEDIATE_AUDIO_BASE_DIR:
+            raise InvalidLocationError(
+                entity=Entity.DIRECTORY,
+                location=Location.INTERMEDIATE_AUDIO_ROOT,
+                path=dir_path,
+            )
+        shutil.rmtree(dir_path)
+
+
+def delete_all_intermediate_audio(
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> None:
+    """
+    Delete all intermediate audio files.
+
+    Parameters
+    ----------
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    """
+    display_progress(
+        "[~] Deleting all intermediate audio files...",
+        percentage,
+        progress_bar,
+    )
+    if INTERMEDIATE_AUDIO_BASE_DIR.is_dir():
+        shutil.rmtree(INTERMEDIATE_AUDIO_BASE_DIR)
+
+
+def delete_output_audio(
+    files: Sequence[StrPath],
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> None:
+    """
+    Delete provided output audio files.
+
+    The provided files must be located in the root of the output audio
+    directory.
+
+    Parameters
+    ----------
+    files : Sequence[StrPath]
+        Paths to the output audio files to delete.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Raises
+    ------
+    NotProvidedError
+        If no paths are provided.
+    NotFoundError
+        If a provided path does not point to an existing file.
+    InvalidLocationError
+        If a provided path does not point to a location in the root of
+        the output audio directory.
+
+    """
+    if not files:
+        raise NotProvidedError(
+            entity=Entity.FILES,
+            ui_msg=UIMessage.NO_OUTPUT_AUDIO_FILES,
+        )
+    display_progress(
+        "[~] Deleting output audio files...",
+        percentage,
+        progress_bar,
+    )
+    for file in files:
+        file_path = Path(file)
+        if not file_path.is_file():
+            raise NotFoundError(entity=Entity.FILE, location=file_path)
+        if file_path.parent != OUTPUT_AUDIO_DIR:
+            raise InvalidLocationError(
+                entity=Entity.FILE,
+                location=Location.OUTPUT_AUDIO_ROOT,
+                path=file_path,
+            )
+        file_path.unlink()
+
+
+def delete_all_output_audio(
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> None:
+    """
+    Delete all output audio files.
+
+    Parameters
+    ----------
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    """
+    display_progress("[~] Deleting all output audio files...", percentage, progress_bar)
+    if OUTPUT_AUDIO_DIR.is_dir():
+        shutil.rmtree(OUTPUT_AUDIO_DIR)
+
+
+def delete_all_audio(
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> None:
+    """
+    Delete all audio files.
+
+    Parameters
+    ----------
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    """
+    display_progress("[~] Deleting all audio files...", percentage, progress_bar)
+    if INTERMEDIATE_AUDIO_BASE_DIR.is_dir():
+        shutil.rmtree(INTERMEDIATE_AUDIO_BASE_DIR)
+    if OUTPUT_AUDIO_DIR.is_dir():
+        shutil.rmtree(OUTPUT_AUDIO_DIR)

src/ultimate_rvc/core/manage/models.py

@@ -0,0 +1,424 @@
+"""Module which defines functions to manage voice models."""
+
+import re
+import shutil
+import urllib.request
+import zipfile
+from _collections_abc import Sequence
+from pathlib import Path
+
+import gradio as gr
+
+from ultimate_rvc.common import RVC_MODELS_DIR
+from ultimate_rvc.core.common import (
+    FLAG_FILE,
+    copy_files_to_new_dir,
+    display_progress,
+    json_load,
+    validate_url,
+)
+from ultimate_rvc.core.exceptions import (
+    Entity,
+    Location,
+    NotFoundError,
+    NotProvidedError,
+    UIMessage,
+    UploadFormatError,
+    UploadLimitError,
+    VoiceModelExistsError,
+    VoiceModelNotFoundError,
+)
+from ultimate_rvc.core.typing_extra import (
+    ModelMetaData,
+    ModelMetaDataList,
+    ModelMetaDataPredicate,
+    ModelMetaDataTable,
+    ModelTagName,
+)
+from ultimate_rvc.typing_extra import StrPath
+
+PUBLIC_MODELS_JSON = json_load(Path(__file__).parent / "public_models.json")
+PUBLIC_MODELS_TABLE = ModelMetaDataTable.model_validate(PUBLIC_MODELS_JSON)
+
+
+def get_saved_model_names() -> list[str]:
+    """
+    Get the names of all saved voice models.
+
+    Returns
+    -------
+    list[str]
+        A list of names of all saved voice models.
+
+    """
+    model_paths = RVC_MODELS_DIR.iterdir()
+    names_to_remove = ["hubert_base.pt", "rmvpe.pt", FLAG_FILE.name]
+    return sorted([
+        model_path.name
+        for model_path in model_paths
+        if model_path.name not in names_to_remove
+    ])
+
+
+def load_public_models_table(
+    predicates: Sequence[ModelMetaDataPredicate],
+) -> ModelMetaDataList:
+    """
+    Load table containing metadata of public voice models, optionally
+    filtered by a set of predicates.
+
+    Parameters
+    ----------
+    predicates : Sequence[ModelMetaDataPredicate]
+        Predicates to filter the metadata table by.
+
+    Returns
+    -------
+    ModelMetaDataList
+        List containing metadata for each public voice model that
+        satisfies the given predicates.
+
+    """
+    return [
+        [
+            model.name,
+            model.description,
+            model.tags,
+            model.credit,
+            model.added,
+            model.url,
+        ]
+        for model in PUBLIC_MODELS_TABLE.models
+        if all(predicate(model) for predicate in predicates)
+    ]
+
+
+def get_public_model_tags() -> list[ModelTagName]:
+    """
+    get the names of all valid public voice model tags.
+
+    Returns
+    -------
+    list[str]
+        A list of names of all valid public voice model tags.
+
+    """
+    return [tag.name for tag in PUBLIC_MODELS_TABLE.tags]
+
+
+def filter_public_models_table(
+    tags: Sequence[str],
+    query: str,
+) -> ModelMetaDataList:
+    """
+    Filter table containing metadata of public voice models by tags and
+    a search query.
+
+
+    The search query is matched against the name, description, tags,
+    credit,and added date of each entry in the metadata table. Case
+    insensitive search is performed. If the search query is empty, the
+    metadata table is filtered only bythe given tags.
+
+    Parameters
+    ----------
+    tags : Sequence[str]
+        Tags to filter the metadata table by.
+    query : str
+        Search query to filter the metadata table by.
+
+    Returns
+    -------
+    ModelMetaDataList
+        List containing metadata for each public voice model that
+        match the given tags and search query.
+
+    """
+
+    def _tags_predicate(model: ModelMetaData) -> bool:
+        return all(tag in model.tags for tag in tags)
+
+    def _query_predicate(model: ModelMetaData) -> bool:
+        return (
+            query.lower()
+            in (
+                f"{model.name} {model.description} {' '.join(model.tags)} "
+                f"{model.credit} {model.added}"
+            ).lower()
+            if query
+            else True
+        )
+
+    filter_fns = [_tags_predicate, _query_predicate]
+
+    return load_public_models_table(filter_fns)
+
+
+def _extract_model(
+    zip_file: StrPath,
+    extraction_dir: StrPath,
+    remove_incomplete: bool = True,
+    remove_zip: bool = False,
+) -> None:
+    """
+    Extract a zipped voice model to a directory.
+
+    Parameters
+    ----------
+    zip_file : StrPath
+        The path to a zip file containing the voice model to extract.
+    extraction_dir : StrPath
+        The path to the directory to extract the voice model to.
+
+    remove_incomplete : bool, default=True
+        Whether to remove the extraction directory if the extraction
+        process fails.
+    remove_zip : bool, default=False
+        Whether to remove the zip file once the extraction process is
+        complete.
+
+    Raises
+    ------
+    NotFoundError
+        If no model file is found in the extracted zip file.
+
+    """
+    extraction_path = Path(extraction_dir)
+    zip_path = Path(zip_file)
+    extraction_completed = False
+    try:
+        extraction_path.mkdir(parents=True)
+        with zipfile.ZipFile(zip_path, "r") as zip_ref:
+            zip_ref.extractall(extraction_path)
+        file_path_map = {
+            ext: Path(root, name)
+            for root, _, files in extraction_path.walk()
+            for name in files
+            for ext in [".index", ".pth"]
+            if Path(name).suffix == ext
+            and Path(root, name).stat().st_size
+            > 1024 * (100 if ext == ".index" else 1024 * 40)
+        }
+        if ".pth" not in file_path_map:
+            raise NotFoundError(
+                entity=Entity.MODEL_FILE,
+                location=Location.EXTRACTED_ZIP_FILE,
+                is_path=False,
+            )
+
+        # move model and index file to root of the extraction directory
+        for file_path in file_path_map.values():
+            file_path.rename(extraction_path / file_path.name)
+
+        # remove any sub-directories within the extraction directory
+        for path in extraction_path.iterdir():
+            if path.is_dir():
+                shutil.rmtree(path)
+        extraction_completed = True
+    finally:
+        if not extraction_completed and remove_incomplete and extraction_path.is_dir():
+            shutil.rmtree(extraction_path)
+        if remove_zip and zip_path.exists():
+            zip_path.unlink()
+
+
+def download_model(
+    url: str,
+    name: str,
+    progress_bar: gr.Progress | None = None,
+    percentages: tuple[float, float] = (0.0, 0.5),
+) -> None:
+    """
+    Download a zipped voice model.
+
+    Parameters
+    ----------
+    url : str
+        An URL pointing to a location where the zipped voice model can
+        be downloaded from.
+    name : str
+        The name to give to the downloaded voice model.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentages : tuple[float, float], default=(0.0, 0.5)
+        Percentages to display in the progress bar.
+
+    Raises
+    ------
+    NotProvidedError
+        If no URL or name is provided.
+    VoiceModelExistsError
+        If a voice model with the provided name already exists.
+
+    """
+    if not url:
+        raise NotProvidedError(entity=Entity.URL)
+    if not name:
+        raise NotProvidedError(entity=Entity.MODEL_NAME)
+    extraction_path = RVC_MODELS_DIR / name
+    if extraction_path.exists():
+        raise VoiceModelExistsError(name)
+
+    validate_url(url)
+    zip_name = url.split("/")[-1].split("?")[0]
+
+    # NOTE in case huggingface link is a direct link rather
+    # than a resolve link then convert it to a resolve link
+    url = re.sub(
+        r"https://huggingface.co/([^/]+)/([^/]+)/blob/(.*)",
+        r"https://huggingface.co/\1/\2/resolve/\3",
+        url,
+    )
+    if "pixeldrain.com" in url:
+        url = f"https://pixeldrain.com/api/file/{zip_name}"
+
+    display_progress(
+        "[~] Downloading voice model ...",
+        percentages[0],
+        progress_bar,
+    )
+    urllib.request.urlretrieve(url, zip_name)  # noqa: S310
+
+    display_progress("[~] Extracting zip file...", percentages[1], progress_bar)
+    _extract_model(zip_name, extraction_path, remove_zip=True)
+
+
+def upload_model(
+    files: Sequence[StrPath],
+    name: str,
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> None:
+    """
+    Upload a voice model from either a zip file or a .pth file and an
+    optional index file.
+
+    Parameters
+    ----------
+    files : Sequence[StrPath]
+        Paths to the files to upload.
+    name : str
+        The name to give to the uploaded voice model.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Raises
+    ------
+    NotProvidedError
+        If no file paths or name are provided.
+    VoiceModelExistsError
+        If a voice model with the provided name already
+        exists.
+    UploadFormatError
+        If a single uploaded file is not a .pth file or a .zip file.
+        If two uploaded files are not a .pth file and an .index file.
+    UploadLimitError
+        If more than two file paths are provided.
+
+    """
+    if not files:
+        raise NotProvidedError(entity=Entity.FILES, ui_msg=UIMessage.NO_UPLOADED_FILES)
+    if not name:
+        raise NotProvidedError(entity=Entity.MODEL_NAME)
+    model_dir_path = RVC_MODELS_DIR / name
+    if model_dir_path.exists():
+        raise VoiceModelExistsError(name)
+    sorted_file_paths = sorted([Path(f) for f in files], key=lambda f: f.suffix)
+    match sorted_file_paths:
+        case [file_path]:
+            if file_path.suffix == ".pth":
+                display_progress("[~] Copying .pth file ...", percentage, progress_bar)
+                copy_files_to_new_dir([file_path], model_dir_path)
+            # NOTE a .pth file is actually itself a zip file
+            elif zipfile.is_zipfile(file_path):
+                display_progress("[~] Extracting zip file...", percentage, progress_bar)
+                _extract_model(file_path, model_dir_path)
+            else:
+                raise UploadFormatError(
+                    entity=Entity.FILES,
+                    formats=[".pth", ".zip"],
+                    multiple=False,
+                )
+        case [index_path, pth_path]:
+            if index_path.suffix == ".index" and pth_path.suffix == ".pth":
+                display_progress(
+                    "[~] Copying .pth file and index file ...",
+                    percentage,
+                    progress_bar,
+                )
+                copy_files_to_new_dir([index_path, pth_path], model_dir_path)
+            else:
+                raise UploadFormatError(
+                    entity=Entity.FILES,
+                    formats=[".pth", ".index"],
+                    multiple=True,
+                )
+        case _:
+            raise UploadLimitError(entity=Entity.FILES, limit="two")
+
+
+def delete_models(
+    names: Sequence[str],
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> None:
+    """
+    Delete one or more voice models.
+
+    Parameters
+    ----------
+    names : Sequence[str]
+        Names of the voice models to delete.
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    Raises
+    ------
+    NotProvidedError
+        If no names are provided.
+    VoiceModelNotFoundError
+        If a voice model with a provided name does not exist.
+
+    """
+    if not names:
+        raise NotProvidedError(
+            entity=Entity.MODEL_NAMES,
+            ui_msg=UIMessage.NO_VOICE_MODELS,
+        )
+    display_progress(
+        "[~] Deleting voice models ...",
+        percentage,
+        progress_bar,
+    )
+    for name in names:
+        model_dir_path = RVC_MODELS_DIR / name
+        if not model_dir_path.is_dir():
+            raise VoiceModelNotFoundError(name)
+        shutil.rmtree(model_dir_path)
+
+
+def delete_all_models(
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> None:
+    """
+    Delete all voice models.
+
+    Parameters
+    ----------
+    progress_bar : gr.Progress, optional
+        Gradio progress bar to update.
+    percentage : float, default=0.5
+        Percentage to display in the progress bar.
+
+    """
+    all_model_names = get_saved_model_names()
+    display_progress("[~] Deleting all voice models ...", percentage, progress_bar)
+    for model_name in all_model_names:
+        model_dir_path = RVC_MODELS_DIR / model_name
+        if model_dir_path.is_dir():
+            shutil.rmtree(model_dir_path)

src/ultimate_rvc/core/manage/other_settings.py

@@ -0,0 +1,29 @@
+"""Module which defines functions used for managing various settings."""
+
+import shutil
+
+import gradio as gr
+
+from ultimate_rvc.common import TEMP_DIR
+from ultimate_rvc.core.common import display_progress
+
+
+def delete_temp_files(
+    progress_bar: gr.Progress | None = None,
+    percentage: float = 0.5,
+) -> None:
+    """
+
+    Delete all temporary files.
+
+    Parameters
+    ----------
+    progress_bar : gr.Progress, optional
+        Progress bar to update.
+    percentage : float, optional
+        The percentage to display in the progress bar.
+
+    """
+    display_progress("[~] Deleting all temporary files...", percentage, progress_bar)
+    if TEMP_DIR.is_dir():
+        shutil.rmtree(TEMP_DIR)

src/ultimate_rvc/core/manage/public_models.json

@@ -0,0 +1,646 @@
+{
+    "tags": [
+        {
+            "name": "English",
+            "description": "Character speaks English"
+        },
+        {
+            "name": "Japanese",
+            "description": "Character speaks Japanese"
+        },
+        {
+            "name": "Other Language",
+            "description": "The character speaks Other Language"
+        },
+        {
+            "name": "Anime",
+            "description": "Character from anime"
+        },
+        {
+            "name": "Vtuber",
+            "description": "Character is a vtuber"
+        },
+        {
+            "name": "Real person",
+            "description": "A person who exists in the real world"
+        },
+        {
+            "name": "Game character",
+            "description": "A character from the game"
+        }
+    ],
+    "models": [
+        {
+            "name": "Emilia",
+            "url": "https://huggingface.co/RinkaEmina/RVC_Sharing/resolve/main/Emilia%20V2%2048000.zip",
+            "description": "Emilia from Re:Zero",
+            "added": "2023-07-31",
+            "credit": "rinka4759",
+            "tags": [
+                "Anime"
+            ]
+        },
+        {
+            "name": "Klee",
+            "url": "https://huggingface.co/qweshkka/Klee/resolve/main/Klee.zip",
+            "description": "Klee from Genshin Impact",
+            "added": "2023-07-31",
+            "credit": "qweshsmashjuicefruity",
+            "tags": [
+                "Game character",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Yelan",
+            "url": "https://huggingface.co/iroaK/RVC2_Yelan_GenshinImpact/resolve/main/YelanJP.zip",
+            "description": "Yelan from Genshin Impact",
+            "added": "2023-07-31",
+            "credit": "iroak",
+            "tags": [
+                "Game character",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Yae Miko",
+            "url": "https://huggingface.co/iroaK/RVC2_YaeMiko_GenshinImpact/resolve/main/Yae_MikoJP.zip",
+            "description": "Yae Miko from Genshin Impact",
+            "added": "2023-07-31",
+            "credit": "iroak",
+            "tags": [
+                "Game character",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Lisa",
+            "url": "https://huggingface.co/qweshkka/Lisa2ver/resolve/main/Lisa.zip",
+            "description": "Lisa from Genshin Impact",
+            "added": "2023-07-31",
+            "credit": "qweshsmashjuicefruity",
+            "tags": [
+                "Game character",
+                "English"
+            ]
+        },
+        {
+            "name": "Kazuha",
+            "url": "https://huggingface.co/iroaK/RVC2_Kazuha_GenshinImpact/resolve/main/Kazuha.zip",
+            "description": "Kaedehara Kazuha from Genshin Impact",
+            "added": "2023-07-31",
+            "credit": "iroak",
+            "tags": [
+                "Game character",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Barbara",
+            "url": "https://huggingface.co/iroaK/RVC2_Barbara_GenshinImpact/resolve/main/BarbaraJP.zip",
+            "description": "Barbara from Genshin Impact",
+            "added": "2023-07-31",
+            "credit": "iroak",
+            "tags": [
+                "Game character",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Tom Holland",
+            "url": "https://huggingface.co/TJKAI/TomHolland/resolve/main/TomHolland.zip",
+            "description": "Tom Holland (Spider-Man)",
+            "added": "2023-08-03",
+            "credit": "tjkcreative",
+            "tags": [
+                "Real person",
+                "English"
+            ]
+        },
+        {
+            "name": "Kamisato Ayaka",
+            "url": "https://huggingface.co/benitheworld/ayaka-cn/resolve/main/ayaka-cn.zip",
+            "description": "Kamisato Ayaka from Genshin Impact - CN voice actor",
+            "added": "2023-08-03",
+            "credit": "kannysoap",
+            "tags": [
+                "Game character",
+                "Other Language"
+            ]
+        },
+        {
+            "name": "Amai Odayaka",
+            "url": "https://huggingface.co/NoIdea4Username/NoIdeaRVCCollection/resolve/main/Amai-Odayaka.zip",
+            "description": "Amai Odayaka from Yandere Simulator",
+            "added": "2023-08-03",
+            "credit": "minecraftian47",
+            "tags": [
+                "Anime",
+                "English"
+            ]
+        },
+        {
+            "name": "Compa - Hyperdimension Neptunia",
+            "url": "https://huggingface.co/zeerowiibu/WiibuRVCCollection/resolve/main/Compa%20(Choujigen%20Game%20Neptunia)%20(JPN)%20(RVC%20v2)%20(150%20Epochs).zip",
+            "description": "Compa from Choujigen Game Neptune (aka Hyperdimension Neptunia)",
+            "added": "2023-08-03",
+            "credit": "zeerowiibu",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Fu Xuan",
+            "url": "https://huggingface.co/Juneuarie/FuXuan/resolve/main/FuXuan.zip",
+            "description": "Fu Xuan from Honkai Star Rail (HSR)",
+            "added": "2023-08-03",
+            "credit": "__june",
+            "tags": [
+                "Game character",
+                "English"
+            ]
+        },
+        {
+            "name": "Xinyan",
+            "url": "https://huggingface.co/AnimeSessions/rvc_voice_models/resolve/main/XinyanRVC.zip",
+            "description": "Xinyan from Genshin Impact",
+            "added": "2023-08-03",
+            "credit": "shyelijah",
+            "tags": [
+                "Game character",
+                "English"
+            ]
+        },
+        {
+            "name": "Enterprise",
+            "url": "https://huggingface.co/NoIdea4Username/NoIdeaRVCCollection/resolve/main/Enterprise-JP.zip",
+            "description": "Enterprise from Azur Lane",
+            "added": "2023-08-03",
+            "credit": "minecraftian47",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Kurt Cobain",
+            "url": "https://huggingface.co/Florstie/Kurt_Cobain_byFlorst/resolve/main/Kurt_Florst.zip",
+            "description": "singer Kurt Cobain",
+            "added": "2023-08-03",
+            "credit": "florst",
+            "tags": [
+                "Real person",
+                "English"
+            ]
+        },
+        {
+            "name": "Ironmouse",
+            "url": "https://huggingface.co/Tempo-Hawk/IronmouseV2/resolve/main/IronmouseV2.zip",
+            "description": "Ironmouse",
+            "added": "2023-08-03",
+            "credit": "ladyimpa",
+            "tags": [
+                "Vtuber",
+                "English"
+            ]
+        },
+        {
+            "name": "Bratishkinoff",
+            "url": "https://huggingface.co/JHmashups/Bratishkinoff/resolve/main/bratishkin.zip",
+            "description": "Bratishkinoff (Bratishkin | Братишкин) - russian steamer ",
+            "added": "2023-08-03",
+            "credit": ".caddii",
+            "tags": [
+                "Real person",
+                "Other Language"
+            ]
+        },
+        {
+            "name": "Yagami Light",
+            "url": "https://huggingface.co/geekdom-tr/Yagami-Light/resolve/main/Yagami-Light.zip",
+            "description": "Yagami Light (Miyano Mamoru) from death note",
+            "added": "2023-08-03",
+            "credit": "takka / takka#7700",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Itashi",
+            "url": "https://huggingface.co/4uGGun/4uGGunRVC/resolve/main/itashi.zip",
+            "description": "Itashi (Russian fandubber AniLibria) ",
+            "added": "2023-08-03",
+            "credit": "BelochkaOff",
+            "tags": [
+                "Anime",
+                "Other Language",
+                "Real person"
+            ]
+        },
+        {
+            "name": "Michiru Kagemori",
+            "url": "https://huggingface.co/WolfMK/MichiruKagemori/resolve/main/MichiruKagemori_RVC_V2.zip",
+            "description": "Michiru Kagemori from Brand New Animal (300 Epochs)",
+            "added": "2023-08-03",
+            "credit": "wolfmk",
+            "tags": [
+                "Anime",
+                "English"
+            ]
+        },
+        {
+            "name": "Kaeya",
+            "url": "https://huggingface.co/nlordqting4444/nlordqtingRVC/resolve/main/Kaeya.zip",
+            "description": "Kaeya (VA: Kohsuke Toriumi) from Genshin Impact (300 Epochs)",
+            "added": "2023-08-03",
+            "credit": "nlordqting4444",
+            "tags": [
+                "Game character",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Mona Megistus",
+            "url": "https://huggingface.co/AnimeSessions/rvc_voice_models/resolve/main/MonaRVC.zip",
+            "description": "Mona Megistus (VA: Felecia Angelle) from Genshin Impact (250 Epochs)",
+            "added": "2023-08-03",
+            "credit": "shyelijah",
+            "tags": [
+                "Game character",
+                "English"
+            ]
+        },
+        {
+            "name": "Klee",
+            "url": "https://huggingface.co/hardbop/AI_MODEL_THINGY/resolve/main/kleeeng_rvc.zip",
+            "description": "Klee from Genshin Impact (400 Epochs)",
+            "added": "2023-08-03",
+            "credit": "hardbop",
+            "tags": [
+                "Game character",
+                "English"
+            ]
+        },
+        {
+            "name": "Sakurakoji Kinako",
+            "url": "https://huggingface.co/Gorodogi/RVC2MangioCrepe/resolve/main/kinakobetatwo700.zip",
+            "description": "Sakurakoji Kinako (Suzuhara Nozomi) from Love Live! Superstar!! (700 Epoch)",
+            "added": "2023-08-03",
+            "credit": "ck1089",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Minamo Kurosawa",
+            "url": "https://huggingface.co/timothy10583/RVC/resolve/main/minamo-kurosawa.zip",
+            "description": "Minamo (Nyamo) Kurosawa (Azumanga Daioh US DUB) (300 Epochs)",
+            "added": "2023-08-03",
+            "credit": "timothy10583",
+            "tags": [
+                "Anime"
+            ]
+        },
+        {
+            "name": "Neco Arc",
+            "url": "https://huggingface.co/Ozzy-Helix/Neko_Arc_Neko_Aruku.RVCv2/resolve/main/Neko_Arc-V3-E600.zip",
+            "description": "Neco Arc (Neco-Aruku) (Epochs 600)",
+            "added": "2023-08-03",
+            "credit": "ozzy_helix_",
+            "tags": [
+                "Anime"
+            ]
+        },
+        {
+            "name": "Makima",
+            "url": "https://huggingface.co/andolei/makimaen/resolve/main/makima-en-dub.zip",
+            "description": "Makima from Chainsaw Man (300 Epochs)",
+            "added": "2023-08-03",
+            "credit": "andpproximately",
+            "tags": [
+                "Anime",
+                "English"
+            ]
+        },
+        {
+            "name": "PomPom",
+            "url": "https://huggingface.co/benitheworld/pom-pom/resolve/main/pom-pom.zip",
+            "description": "PomPom from Honkai Star Rail (HSR) (200 Epochs)",
+            "added": "2023-08-03",
+            "credit": "kannysoap",
+            "tags": [
+                "Game character",
+                "English"
+            ]
+        },
+        {
+            "name": "Asuka Langley Soryu",
+            "url": "https://huggingface.co/Piegirl/asukaadv/resolve/main/asuka.zip",
+            "description": "Asuka Langley Soryu/Tiffany Grant from Neon Genesis Evangelion (400 Epochs)",
+            "added": "2023-08-03",
+            "credit": "piegirl",
+            "tags": [
+                "Anime",
+                "English"
+            ]
+        },
+        {
+            "name": "Ochaco Uraraka",
+            "url": "https://huggingface.co/legitdark/JP-Uraraka-By-Dan/resolve/main/JP-Uraraka-By-Dan.zip",
+            "description": "Ochaco Uraraka from Boku no Hero Academia (320 Epochs)",
+            "added": "2023-08-03",
+            "credit": "danthevegetable",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Sunaokami Shiroko",
+            "url": "https://huggingface.co/LordDavis778/BlueArchivevoicemodels/resolve/main/SunaokamiShiroko.zip",
+            "description": "Sunaokami Shiroko from Blue Archive (500 Epochs)",
+            "added": "2023-08-03",
+            "credit": "lorddavis778",
+            "tags": [
+                "Anime"
+            ]
+        },
+        {
+            "name": "Dainsleif",
+            "url": "https://huggingface.co/Nasleyy/NasleyRVC/resolve/main/Voices/Dainsleif/Dainsleif.zip",
+            "description": "Dainsleif from Genshin Impact (335 Epochs)",
+            "added": "2023-08-03",
+            "credit": "nasley",
+            "tags": [
+                "Game character",
+                "English"
+            ]
+        },
+        {
+            "name": "Mae Asmr",
+            "url": "https://huggingface.co/ctian/VRC/resolve/main/MaeASMR.zip",
+            "description": "Mae Asmr - harvest mommy voice (YOUTUBE) (300 Epochs)",
+            "added": "2023-08-03",
+            "credit": "ctian_04",
+            "tags": [
+                "English",
+                "Real person",
+                "Vtuber"
+            ]
+        },
+        {
+            "name": "Hana Shirosaki ",
+            "url": "https://huggingface.co/Pawlik17/HanaWataten/resolve/main/HanaWATATEN.zip",
+            "description": "Hana Shirosaki / 白 咲 花 From Watashi ni Tenshi ga Maiorita! (570 Epochs)",
+            "added": "2023-08-03",
+            "credit": "tamalik",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Kaguya Shinomiya ",
+            "url": "https://huggingface.co/1ski/1skiRVCModels/resolve/main/kaguyav5.zip",
+            "description": "Kaguya Shinomiya from Kaguya-Sama Love is war (200 Epochs)",
+            "added": "2023-08-03",
+            "credit": "1ski",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Nai Shiro",
+            "url": "https://huggingface.co/kuushiro/Shiro-RVC-No-Game-No-Life/resolve/main/shiro-jp-360-epochs.zip",
+            "description": "Nai Shiro (Ai Kayano) from No Game No Life (360 Epochs)",
+            "added": "2023-08-03",
+            "credit": "kxouyou",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Yuigahama Yui",
+            "url": "https://huggingface.co/Zerokano/Yuigahama_Yui-RVCv2/resolve/main/Yuigahama_Yui.zip",
+            "description": "Yuigahama Yui from Yahari Ore no Seishun Love Comedy wa Machigatteiru (250 Epochs)",
+            "added": "2023-08-03",
+            "credit": "zerokano",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Fuwawa Abyssgard",
+            "url": "https://huggingface.co/megaaziib/my-rvc-models-collection/resolve/main/fuwawa.zip",
+            "description": "Fuwawa Abyssgard (FUWAMOCO) from Hololive gen 3 (250 Epochs)",
+            "added": "2023-08-03",
+            "credit": "megaaziib",
+            "tags": [
+                "Vtuber",
+                "English"
+            ]
+        },
+        {
+            "name": "Kana Arima",
+            "url": "https://huggingface.co/ddoumakunn/arimakanna/resolve/main/arimakanna.zip",
+            "description": "Kana Arima from Oshi no Ko (250 Epochs)",
+            "added": "2023-08-03",
+            "credit": "ddoumakunn",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Raiden Shogun",
+            "url": "https://huggingface.co/Nasleyy/NasleyRVC/resolve/main/Voices/RaidenShogun/RaidenShogun.zip",
+            "description": "Raiden Shogun from Genshin Impact (310 Epochs)",
+            "added": "2023-08-03",
+            "credit": "nasley",
+            "tags": [
+                "Game character",
+                "English"
+            ]
+        },
+        {
+            "name": "Alhaitham",
+            "url": "https://huggingface.co/Nasleyy/NasleyRVC/resolve/main/Voices/Alhaitham/Alhaitham.zip",
+            "description": "Alhaitham from Genshin Impact (320 Epochs)",
+            "added": "2023-08-03",
+            "credit": "nasley",
+            "tags": [
+                "Game character",
+                "English"
+            ]
+        },
+        {
+            "name": "Izuku Midoriya",
+            "url": "https://huggingface.co/BigGuy635/MHA/resolve/main/DekuJP.zip",
+            "description": "Izuku Midoriya from Boku no Hero Academia (100 Epochs)",
+            "added": "2023-08-03",
+            "credit": "khjjnoffical",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Kurumi Shiratori",
+            "url": "https://huggingface.co/HarunaKasuga/YoshikoTsushima/resolve/main/KurumiShiratori.zip",
+            "description": "Kurumi Shiratori (VA: Ruka Fukagawa) from D4DJ (500 Epochs)",
+            "added": "2023-08-03",
+            "credit": "seakrait",
+            "tags": [
+                "Anime",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Veibae",
+            "url": "https://huggingface.co/datasets/Papaquans/Veibae/resolve/main/veibae_e165_s125565.zip",
+            "description": "Veibae (165 Epochs)",
+            "added": "2023-08-03",
+            "credit": "recairo",
+            "tags": [
+                "Vtuber",
+                "English"
+            ]
+        },
+        {
+            "name": "Black Panther",
+            "url": "https://huggingface.co/TJKAI/BlackPannther/resolve/main/BlackPanther.zip",
+            "description": "Black Panther (Chadwick Boseman) (300 Epochs)",
+            "added": "2023-08-03",
+            "credit": "tjkcreative",
+            "tags": [
+                "Real person",
+                "English"
+            ]
+        },
+        {
+            "name": "Gawr Gura",
+            "url": "https://pixeldrain.com/u/3tJmABXA",
+            "description": "Gawr Gura from Hololive EN",
+            "added": "2023-08-05",
+            "credit": "dacoolkid44 & hijack",
+            "tags": [
+                "Vtuber"
+            ]
+        },
+        {
+            "name": "Houshou Marine",
+            "url": "https://pixeldrain.com/u/L1YLfZyU",
+            "description": "Houshou Marine from Hololive JP",
+            "added": "2023-08-05",
+            "credit": "dacoolkid44 & hijack",
+            "tags": [
+                "Vtuber",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Hoshimachi Suisei",
+            "url": "https://pixeldrain.com/u/YP89C21u",
+            "description": "Hoshimachi Suisei from Hololive JP",
+            "added": "2023-08-05",
+            "credit": "dacoolkid44 & hijack & Maki Ligon",
+            "tags": [
+                "Vtuber",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Laplus Darkness",
+            "url": "https://pixeldrain.com/u/zmuxv5Bf",
+            "description": "Laplus Darkness from Hololive JP",
+            "added": "2023-08-05",
+            "credit": "dacoolkid44 & hijack",
+            "tags": [
+                "Vtuber",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "AZKi",
+            "url": "https://huggingface.co/Kit-Lemonfoot/kitlemonfoot_rvc_models/resolve/main/AZKi%20(Hybrid).zip",
+            "description": "AZKi from Hololive JP",
+            "added": "2023-08-05",
+            "credit": "Kit Lemonfoot / NSHFB",
+            "tags": [
+                "Vtuber",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Ado",
+            "url": "https://huggingface.co/pjesek/AdoRVCv2/resolve/main/AdoRVCv2.zip",
+            "description": "Talented JP artist (500 epochs using every song from her first album)",
+            "added": "2023-08-05",
+            "credit": "pjesek",
+            "tags": [
+                "Real person",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "LiSA",
+            "url": "https://huggingface.co/phant0m4r/LiSA/resolve/main/LiSA.zip",
+            "description": "Talented JP artist (400 epochs)",
+            "added": "2023-08-05",
+            "credit": "Phant0m",
+            "tags": [
+                "Real person",
+                "Japanese"
+            ]
+        },
+        {
+            "name": "Kokomi",
+            "url": "https://huggingface.co/benitheworld/kokomi-kr/resolve/main/kokomi-kr.zip",
+            "description": "Kokomi from Genshin Impact KR (300 Epochs)",
+            "added": "2023-08-09",
+            "credit": "kannysoap",
+            "tags": [
+                "Game character",
+                "Other Language"
+            ]
+        },
+        {
+            "name": "Ivanzolo",
+            "url": "https://huggingface.co/fenikkusugosuto/IvanZolo2004/resolve/main/ivanZolo.zip",
+            "description": "Ivanzolo2004 russian streamer | Иван Золо 2004",
+            "added": "2023-08-09",
+            "credit": "prezervativ_naruto2009",
+            "tags": [
+                "Other Language",
+                "Real person"
+            ]
+        },
+        {
+            "name": "Nilou",
+            "url": "https://huggingface.co/benitheworld/nilou-kr/resolve/main/nilou-kr.zip",
+            "description": "Nilou from Genshin Impact KR (300 Epochs)",
+            "added": "2023-08-09",
+            "credit": "kannysoap",
+            "tags": [
+                "Game character",
+                "Other Language"
+            ]
+        },
+        {
+            "name": "Dr. Doofenshmirtz",
+            "url": "https://huggingface.co/Argax/doofenshmirtz-RUS/resolve/main/doofenshmirtz.zip",
+            "description": "RUS Dr. Doofenshmirtz from Phineas and Ferb  (300 epochs)",
+            "added": "2023-08-09",
+            "credit": "argaxus",
+            "tags": [
+                "Other Language"
+            ]
+        }
+    ]
+}

src/ultimate_rvc/core/typing_extra.py

@@ -0,0 +1,294 @@
+"""
+Module which defines extra types for the core of the Ultimate RVC
+project.
+"""
+
+from collections.abc import Callable
+from enum import StrEnum, auto
+
+from pydantic import BaseModel, ConfigDict
+
+from ultimate_rvc.typing_extra import AudioExt, F0Method
+
+# Voice model management
+
+
+class ModelTagName(StrEnum):
+    """Names of valid voice model tags."""
+
+    ENGLISH = "English"
+    JAPANESE = "Japanese"
+    OTHER_LANGUAGE = "Other Language"
+    ANIME = "Anime"
+    VTUBER = "Vtuber"
+    REAL_PERSON = "Real person"
+    GAME_CHARACTER = "Game character"
+
+
+class ModelTagMetaData(BaseModel):
+    """
+    Metadata for a voice model tag.
+
+    Attributes
+    ----------
+    name : ModelTagName
+        The name of the tag.
+    description : str
+        The description of the tag.
+
+    """
+
+    name: ModelTagName
+    description: str
+
+
+class ModelMetaData(BaseModel):
+    """
+    Metadata for a voice model.
+
+    Attributes
+    ----------
+    name : str
+        The name of the voice model.
+    description : str
+        A description of the voice model.
+    tags : list[ModelTagName]
+        The tags associated with the voice model.
+    credit : str
+        Who created the voice model.
+    added : str
+        The date the voice model was created.
+    url : str
+        An URL pointing to a location where the voice model can be
+        downloaded.
+
+    """
+
+    name: str
+    description: str
+    tags: list[ModelTagName]
+    credit: str
+    added: str
+    url: str
+
+
+class ModelMetaDataTable(BaseModel):
+    """
+    Table with metadata for a set of voice models.
+
+    Attributes
+    ----------
+    tags : list[ModelTagMetaData]
+        Metadata for the tags associated with the given set of voice
+        models.
+    models : list[ModelMetaData]
+        Metadata for the given set of voice models.
+
+    """
+
+    tags: list[ModelTagMetaData]
+    models: list[ModelMetaData]
+
+
+ModelMetaDataPredicate = Callable[[ModelMetaData], bool]
+
+ModelMetaDataList = list[list[str | list[ModelTagName]]]
+
+
+# Song cover generation
+
+
+class SourceType(StrEnum):
+    """The type of source providing the song to generate a cover of."""
+
+    URL = auto()
+    FILE = auto()
+    SONG_DIR = auto()
+
+
+class AudioExtInternal(StrEnum):
+    """Audio file formats for internal use."""
+
+    MP3 = "mp3"
+    WAV = "wav"
+    FLAC = "flac"
+    OGG = "ogg"
+    IPOD = "ipod"
+    ADTS = "adts"
+
+
+class FileMetaData(BaseModel):
+    """
+    Metadata for a file.
+
+    Attributes
+    ----------
+    name : str
+        The name of the file.
+    hash_id : str
+        The hash ID of the file.
+
+    """
+
+    name: str
+    hash_id: str
+
+
+class WaveifiedAudioMetaData(BaseModel):
+    """
+    Metadata for a waveified audio track.
+
+    Attributes
+    ----------
+    audio_track : FileMetaData
+        Metadata for the audio track that was waveified.
+
+    """
+
+    audio_track: FileMetaData
+
+
+class SeparatedAudioMetaData(BaseModel):
+    """
+    Metadata for a separated audio track.
+
+    Attributes
+    ----------
+    audio_track : FileMetaData
+        Metadata for the audio track that was separated.
+    model_name : str
+        The name of the model used for separation.
+    segment_size : int
+        The segment size used for separation.
+
+    """
+
+    audio_track: FileMetaData
+    model_name: str
+    segment_size: int
+
+    model_config = ConfigDict(protected_namespaces=())
+
+
+class ConvertedVocalsMetaData(BaseModel):
+    """
+    Metadata for an RVC converted vocals track.
+
+    Attributes
+    ----------
+    vocals_track : FileMetaData
+        Metadata for the vocals track that was converted.
+    model_name : str
+        The name of the model used for vocal conversion.
+    n_semitones : int
+        The number of semitones the converted vocals were pitch-shifted
+        by.
+    f0_method : F0Method
+        The method used for pitch detection.
+    index_rate : float
+        The influence of the index file on the vocal conversion.
+    filter_radius : int
+        The filter radius used for the vocal conversion.
+    rms_mix_rate : float
+        The blending of the volume envelope of the converted vocals.
+    protect : float
+        The protection rate used for consonants and breathing sounds.
+    hop_length : int
+        The hop length used for crepe-based pitch detection.
+
+    """
+
+    vocals_track: FileMetaData
+    model_name: str
+    n_semitones: int
+    f0_method: F0Method
+    index_rate: float
+    filter_radius: int
+    rms_mix_rate: float
+    protect: float
+    hop_length: int
+
+    model_config = ConfigDict(protected_namespaces=())
+
+
+class EffectedVocalsMetaData(BaseModel):
+    """
+    Metadata for an effected vocals track.
+
+    Attributes
+    ----------
+    vocals_track : FileMetaData
+        Metadata for the vocals track that effects were applied to.
+    room_size : float
+        The room size of the reverb effect applied to the vocals track.
+    wet_level : float
+        The wetness level of the reverb effect applied to the vocals
+        track.
+    dry_level : float
+        The dryness level of the reverb effect. applied to the vocals
+        track.
+    damping : float
+        The damping of the reverb effect applied to the vocals track.
+
+    """
+
+    vocals_track: FileMetaData
+    room_size: float
+    wet_level: float
+    dry_level: float
+    damping: float
+
+
+class PitchShiftMetaData(BaseModel):
+    """
+    Metadata for a pitch-shifted audio track.
+
+    Attributes
+    ----------
+    audio_track : FileMetaData
+        Metadata for the audio track that was pitch-shifted.
+    n_semitones : int
+        The number of semitones the audio track was pitch-shifted by.
+
+    """
+
+    audio_track: FileMetaData
+    n_semitones: int
+
+
+class StagedAudioMetaData(BaseModel):
+    """
+    Metadata for a staged audio track.
+
+    Attributes
+    ----------
+    audio_track : FileMetaData
+        Metadata for the audio track that was staged.
+    gain : float
+        The gain applied to the audio track.
+
+    """
+
+    audio_track: FileMetaData
+    gain: float
+
+
+class MixedSongMetaData(BaseModel):
+    """
+    Metadata for a mixed song.
+
+    Attributes
+    ----------
+    staged_audio_tracks : list[StagedAudioMetaData]
+        Metadata for the staged audio tracks that were mixed.
+
+    output_sr : int
+        The sample rate of the mixed song.
+    output_format : AudioExt
+        The audio file format of the mixed song.
+
+    """
+
+    staged_audio_tracks: list[StagedAudioMetaData]
+    output_sr: int
+    output_format: AudioExt

src/ultimate_rvc/stubs/audio_separator/separator/__init__.pyi

@@ -0,0 +1,100 @@
+from typing import TypedDict
+
+import logging
+
+from ultimate_rvc.typing_extra import StrPath
+
+class MDXParams(TypedDict):
+    hop_length: int
+    segment_size: int
+    overlap: float
+    batch_size: int
+    enable_denoise: bool
+
+class VRParams(TypedDict):
+    batch_size: int
+    window_size: int
+    aggression: int
+    enable_tta: bool
+    enable_post_process: bool
+    post_process_threshold: float
+    high_end_process: bool
+
+class DemucsParams(TypedDict):
+    segment_size: str
+    shifts: int
+    overlap: float
+    segments_enabled: bool
+
+class MDXCParams(TypedDict):
+    segment_size: int
+    override_model_segment_size: bool
+    batch_size: int
+    overlap: int
+    pitch_shift: int
+
+class ArchSpecificParams(TypedDict):
+    MDX: MDXParams
+    VR: VRParams
+    Demucs: DemucsParams
+    MDXC: MDXCParams
+
+class Separator:
+    arch_specific_params: ArchSpecificParams
+    def __init__(
+        self,
+        log_level: int = ...,
+        log_formatter: logging.Formatter | None = None,
+        model_file_dir: StrPath = "/tmp/audio-separator-models/",  # noqa: S108
+        output_dir: StrPath | None = None,
+        output_format: str = "WAV",
+        output_bitrate: str | None = None,
+        normalization_threshold: float = 0.9,
+        amplification_threshold: float = 0.6,
+        output_single_stem: str | None = None,
+        invert_using_spec: bool = False,
+        sample_rate: int = 44100,
+        mdx_params: MDXParams = {
+            "hop_length": 1024,
+            "segment_size": 256,
+            "overlap": 0.25,
+            "batch_size": 1,
+            "enable_denoise": False,
+        },
+        vr_params: VRParams = {
+            "batch_size": 1,
+            "window_size": 512,
+            "aggression": 5,
+            "enable_tta": False,
+            "enable_post_process": False,
+            "post_process_threshold": 0.2,
+            "high_end_process": False,
+        },
+        demucs_params: DemucsParams = {
+            "segment_size": "Default",
+            "shifts": 2,
+            "overlap": 0.25,
+            "segments_enabled": True,
+        },
+        mdxc_params: MDXCParams = {
+            "segment_size": 256,
+            "override_model_segment_size": False,
+            "batch_size": 1,
+            "overlap": 8,
+            "pitch_shift": 0,
+        },
+    ) -> None: ...
+    def download_model_files(
+        self,
+        model_filename: str,
+    ) -> tuple[str, str, str, str, str | None]: ...
+    def load_model(
+        self,
+        model_filename: str = "model_mel_band_roformer_ep_3005_sdr_11.4360.ckpt",
+    ) -> None: ...
+    def separate(
+        self,
+        audio_file_path: str,
+        primary_output_name: str | None = None,
+        secondary_output_name: str | None = None,
+    ) -> list[str]: ...

src/ultimate_rvc/stubs/gradio/__init__.pyi

@@ -0,0 +1,245 @@
+import json
+
+from gradio import (
+    _simple_templates,
+    components,
+    image_utils,
+    layouts,
+    processing_utils,
+    templates,
+    themes,
+)
+from gradio.blocks import Blocks
+from gradio.chat_interface import ChatInterface
+from gradio.components import (
+    HTML,
+    JSON,
+    AnnotatedImage,
+    Annotatedimage,
+    Audio,
+    BarPlot,
+    BrowserState,
+    Button,
+    Chatbot,
+    ChatMessage,
+    Checkbox,
+    CheckboxGroup,
+    Checkboxgroup,
+    ClearButton,
+    Code,
+    ColorPicker,
+    DataFrame,
+    Dataframe,
+    Dataset,
+    DateTime,
+    DownloadButton,
+    Dropdown,
+    DuplicateButton,
+    File,
+    FileExplorer,
+    Gallery,
+    Highlight,
+    HighlightedText,
+    Highlightedtext,
+    Image,
+    ImageEditor,
+    Json,
+    Label,
+    LinePlot,
+    LoginButton,
+    Markdown,
+    MessageDict,
+    Model3D,
+    MultimodalTextbox,
+    Number,
+    ParamViewer,
+    Plot,
+    Radio,
+    ScatterPlot,
+    Slider,
+    State,
+    Text,
+    Textbox,
+    Timer,
+    UploadButton,
+    Video,
+    component,
+)
+from gradio.components.audio import WaveformOptions
+from gradio.components.image_editor import Brush, Eraser
+from gradio.data_classes import FileData
+from gradio.events import (
+    DeletedFileData,
+    DownloadData,
+    EventData,
+    KeyUpData,
+    LikeData,
+    RetryData,
+    SelectData,
+    UndoData,
+    on,
+)
+from gradio.exceptions import Error
+from gradio.external import load
+from gradio.flagging import (
+    CSVLogger,
+    FlaggingCallback,
+    SimpleCSVLogger,
+)
+from gradio.helpers import (
+    Info,
+    Progress,
+    Warning,
+    skip,
+    update,
+)
+from gradio.helpers import create_examples as Examples  # noqa: N812
+from gradio.interface import Interface, TabbedInterface, close_all
+from gradio.layouts import Accordion, Column, Group, Row, Tab, TabItem, Tabs
+from gradio.oauth import OAuthProfile, OAuthToken
+from gradio.renderable import render
+from gradio.routes import Request, mount_gradio_app
+from gradio.templates import (
+    Files,
+    ImageMask,
+    List,
+    Matrix,
+    Mic,
+    Microphone,
+    Numpy,
+    Paint,
+    PlayableVideo,
+    Sketchpad,
+    TextArea,
+)
+from gradio.themes import Base as Theme
+from gradio.utils import NO_RELOAD, FileSize, get_package_version, set_static_paths
+from gradio.wasm_utils import IS_WASM
+
+if not IS_WASM:  # noqa: PYI002
+    from gradio.cli import deploy
+    from gradio.ipython_ext import load_ipython_extension
+
+__version__ = ...
+__all__ = [
+    "HTML",
+    "IS_WASM",
+    "JSON",
+    "NO_RELOAD",
+    "Accordion",
+    "AnnotatedImage",
+    "Annotatedimage",
+    "Audio",
+    "BarPlot",
+    "Blocks",
+    "BrowserState",
+    "Brush",
+    "Button",
+    "CSVLogger",
+    "ChatInterface",
+    "ChatMessage",
+    "Chatbot",
+    "Checkbox",
+    "CheckboxGroup",
+    "Checkboxgroup",
+    "ClearButton",
+    "Code",
+    "ColorPicker",
+    "Column",
+    "DataFrame",
+    "Dataframe",
+    "Dataset",
+    "DateTime",
+    "DeletedFileData",
+    "DownloadButton",
+    "DownloadData",
+    "Dropdown",
+    "DuplicateButton",
+    "Eraser",
+    "Error",
+    "EventData",
+    "Examples",
+    "File",
+    "FileData",
+    "FileExplorer",
+    "FileSize",
+    "Files",
+    "FlaggingCallback",
+    "Gallery",
+    "Group",
+    "Highlight",
+    "HighlightedText",
+    "Highlightedtext",
+    "Image",
+    "ImageEditor",
+    "ImageMask",
+    "Info",
+    "Interface",
+    "Json",
+    "KeyUpData",
+    "Label",
+    "LikeData",
+    "LinePlot",
+    "List",
+    "LoginButton",
+    "Markdown",
+    "Matrix",
+    "MessageDict",
+    "Mic",
+    "Microphone",
+    "Model3D",
+    "MultimodalTextbox",
+    "Number",
+    "Numpy",
+    "OAuthProfile",
+    "OAuthToken",
+    "Paint",
+    "ParamViewer",
+    "PlayableVideo",
+    "Plot",
+    "Progress",
+    "Radio",
+    "Request",
+    "RetryData",
+    "Row",
+    "ScatterPlot",
+    "SelectData",
+    "SimpleCSVLogger",
+    "Sketchpad",
+    "Slider",
+    "State",
+    "Tab",
+    "TabItem",
+    "TabbedInterface",
+    "Tabs",
+    "Text",
+    "TextArea",
+    "Textbox",
+    "Theme",
+    "Timer",
+    "UndoData",
+    "UploadButton",
+    "Video",
+    "Warning",
+    "WaveformOptions",
+    "_simple_templates",
+    "close_all",
+    "component",
+    "components",
+    "deploy",
+    "get_package_version",
+    "image_utils",
+    "json",
+    "layouts",
+    "load",
+    "load_ipython_extension",
+    "mount_gradio_app",
+    "on",
+    "processing_utils",
+    "render",
+    "set_static_paths",
+    "skip",
+    "templates",
+    "themes",
+    "update",
+]

src/ultimate_rvc/stubs/gradio/events.pyi

@@ -0,0 +1,344 @@
+from typing import Any, Literal, NotRequired, Protocol, Self, TypedDict
+
+import dataclasses
+from collections import UserString
+from collections.abc import Callable, Sequence
+from collections.abc import Set as AbstractSet
+
+from _typeshed import SupportsKeysAndGetItem
+
+from gradio.blocks import Block, BlockContext, Component
+from gradio.components import Timer
+from gradio.data_classes import FileData, FileDataDict
+
+type Dependency = _Dependency[Any, Any, Any]
+type EventListenerCallable = _EventListenerCallable[Any, Any, Any]
+type EventListener = _EventListener[Any, Any, Any]
+
+class _EventListenerCallable[T, V, **P](Protocol):
+    def __call__(
+        self,
+        fn: Callable[P, T] | Literal["decorator"] | None = "decorator",
+        inputs: (
+            Component
+            | BlockContext
+            | Sequence[Component | BlockContext]
+            | AbstractSet[Component | BlockContext]
+            | None
+        ) = None,
+        outputs: (
+            Component
+            | BlockContext
+            | Sequence[Component | BlockContext]
+            | AbstractSet[Component | BlockContext]
+            | None
+        ) = None,
+        api_name: str | Literal[False] | None = None,
+        scroll_to_output: bool = False,
+        show_progress: Literal["full", "minimal", "hidden"] = "full",
+        queue: bool = True,
+        batch: bool = False,
+        max_batch_size: int = 4,
+        preprocess: bool = True,
+        postprocess: bool = True,
+        cancels: Dependency | list[Dependency] | None = None,
+        trigger_mode: Literal["once", "multiple", "always_last"] | None = None,
+        js: str | None = None,
+        concurrency_limit: int | Literal["default"] | None = "default",
+        concurrency_id: str | None = None,
+        show_api: bool = True,
+        stream_every: float = 0.5,
+        like_user_message: bool = False,
+    ) -> _Dependency[T, V, P]: ...
+
+class _EventListenerCallableFull[T, V, **P](Protocol):
+    def __call__(
+        self,
+        block: Block | None,
+        fn: Callable[P, T] | Literal["decorator"] | None = "decorator",
+        inputs: (
+            Component
+            | BlockContext
+            | Sequence[Component | BlockContext]
+            | AbstractSet[Component | BlockContext]
+            | None
+        ) = None,
+        outputs: (
+            Component
+            | BlockContext
+            | Sequence[Component | BlockContext]
+            | AbstractSet[Component | BlockContext]
+            | None
+        ) = None,
+        api_name: str | Literal[False] | None = None,
+        scroll_to_output: bool = False,
+        show_progress: Literal["full", "minimal", "hidden"] = "full",
+        queue: bool = True,
+        batch: bool = False,
+        max_batch_size: int = 4,
+        preprocess: bool = True,
+        postprocess: bool = True,
+        cancels: Dependency | list[Dependency] | None = None,
+        trigger_mode: Literal["once", "multiple", "always_last"] | None = None,
+        js: str | None = None,
+        concurrency_limit: int | Literal["default"] | None = "default",
+        concurrency_id: str | None = None,
+        show_api: bool = True,
+        time_limit: int | None = None,
+        stream_every: float = 0.5,
+        like_user_message: bool = False,
+    ) -> _Dependency[T, V, P]: ...
+
+def set_cancel_events(
+    triggers: Sequence[EventListenerMethod],
+    cancels: Dependency | list[Dependency] | None,
+) -> None: ...
+
+class _Dependency[T, V, **P](dict[str, V]):
+    fn: Callable[P, T]
+    associated_timer: Timer | None
+    then: EventListenerCallable
+    success: EventListenerCallable
+
+    def __init__(
+        self,
+        trigger: Block | None,
+        key_vals: SupportsKeysAndGetItem[str, V],
+        dep_index: int | None,
+        fn: Callable[P, T],
+        associated_timer: Timer | None = None,
+    ) -> None: ...
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T: ...
+
+class EventData[T]:
+    target: Block | None
+    _data: T
+
+    def __init__(self, target: Block | None, _data: T) -> None: ...
+
+class _SelectData(TypedDict):
+    index: int | tuple[int, int]
+    value: Any
+    row_value: NotRequired[list[Any]]
+    col_value: NotRequired[list[Any]]
+    selected: NotRequired[bool]
+
+class SelectData(EventData[_SelectData]):
+    index: int | tuple[int, int]
+    value: Any
+    row_value: list[Any] | None
+    col_value: list[Any] | None
+    selected: bool
+
+    def __init__(self, target: Block | None, data: _SelectData) -> None: ...
+
+class _KeyUpData(TypedDict):
+    key: str
+    input_value: str
+
+class KeyUpData(EventData[_KeyUpData]):
+    key: str
+    input_value: str
+
+    def __init__(self, target: Block | None, data: _KeyUpData) -> None: ...
+
+class DeletedFileData(EventData[FileDataDict]):
+    file: FileData
+
+    def __init__(self, target: Block | None, data: FileDataDict) -> None: ...
+
+class _LikeData(TypedDict):
+    index: int | tuple[int, int]
+    value: Any
+    liked: NotRequired[bool]
+
+class LikeData(EventData[_LikeData]):
+    index: int | tuple[int, int]
+    value: Any
+    liked: bool
+
+    def __init__(self, target: Block | None, data: _LikeData) -> None: ...
+
+class _RetryData(TypedDict):
+    index: int | tuple[int, int]
+    value: Any
+
+class RetryData(EventData[_RetryData]):
+    index: int | tuple[int, int]
+    value: Any
+
+    def __init__(self, target: Block | None, data: _RetryData) -> None: ...
+
+class _UndoData(TypedDict):
+    index: int | tuple[int, int]
+    value: Any
+
+class UndoData(EventData[_UndoData]):
+    index: int | tuple[int, int]
+    value: Any
+
+    def __init__(self, target: Block | None, data: _UndoData) -> None: ...
+
+class DownloadData(EventData[FileDataDict]):
+    file: FileData
+
+    def __init__(self, target: Block | None, data: FileDataDict) -> None: ...
+
+@dataclasses.dataclass
+class EventListenerMethod:
+    block: Block | None
+    event_name: str
+
+class _EventListener[T, V, **P](UserString):
+    __slots__ = (
+        "callback",
+        "config_data",
+        "connection",
+        "doc",
+        "event_name",
+        "event_specific_args",
+        "has_trigger",
+        "listener",
+        "show_progress",
+        "trigger_after",
+        "trigger_only_on_success",
+    )
+
+    event_name: str
+    has_trigger: bool
+    config_data: Callable[..., dict[str, T]]
+    show_progress: Literal["full", "minimal", "hidden"]
+    callback: Callable[[Block], None] | None
+    trigger_after: int | None
+    trigger_only_on_success: bool
+    doc: str
+    connection: Literal["sse", "stream"]
+    event_specific_args: list[dict[str, str]]
+    listener: _EventListenerCallableFull[T, V, P]
+
+    def __new__(
+        cls,
+        event_name: str,
+        has_trigger: bool = True,
+        config_data: Callable[..., dict[str, T]] = dict,  # noqa: PYI011
+        show_progress: Literal["full", "minimal", "hidden"] = "full",
+        callback: Callable[[Block], None] | None = None,
+        trigger_after: int | None = None,
+        trigger_only_on_success: bool = False,
+        doc: str = "",
+        connection: Literal["sse", "stream"] = "sse",
+        event_specific_args: list[dict[str, str]] | None = None,
+    ) -> Self: ...
+    def __init__(
+        self,
+        event_name: str,
+        has_trigger: bool = True,
+        config_data: Callable[..., dict[str, T]] = dict,  # noqa: PYI011
+        show_progress: Literal["full", "minimal", "hidden"] = "full",
+        callback: Callable[[Block], None] | None = None,
+        trigger_after: int | None = None,
+        trigger_only_on_success: bool = False,
+        doc: str = "",
+        connection: Literal["sse", "stream"] = "sse",
+        event_specific_args: list[dict[str, str]] | None = None,
+    ) -> None: ...
+    def set_doc(self, component: str) -> None: ...
+    def copy(self) -> _EventListener[T, V, P]: ...
+    @staticmethod
+    def _setup(
+        _event_name: str,
+        _has_trigger: bool,
+        _show_progress: Literal["full", "minimal", "hidden"],
+        _callback: Callable[[Block], None] | None,
+        _trigger_after: int | None,
+        _trigger_only_on_success: bool,
+        _event_specific_args: list[dict[str, str]],
+        _connection: Literal["sse", "stream"] = "sse",
+    ) -> _EventListenerCallableFull[T, V, P]: ...
+
+def on[T, **P](
+    triggers: Sequence[EventListenerCallable] | EventListenerCallable | None = None,
+    fn: Callable[P, T] | Literal["decorator"] | None = "decorator",
+    inputs: (
+        Component
+        | BlockContext
+        | Sequence[Component | BlockContext]
+        | AbstractSet[Component | BlockContext]
+        | None
+    ) = None,
+    outputs: (
+        Component
+        | BlockContext
+        | Sequence[Component | BlockContext]
+        | AbstractSet[Component | BlockContext]
+        | None
+    ) = None,
+    *,
+    api_name: str | Literal[False] | None = None,
+    scroll_to_output: bool = False,
+    show_progress: Literal["full", "minimal", "hidden"] = "full",
+    queue: bool = True,
+    batch: bool = False,
+    max_batch_size: int = 4,
+    preprocess: bool = True,
+    postprocess: bool = True,
+    cancels: Dependency | list[Dependency] | None = None,
+    trigger_mode: Literal["once", "multiple", "always_last"] | None = None,
+    js: str | None = None,
+    concurrency_limit: int | Literal["default"] | None = "default",
+    concurrency_id: str | None = None,
+    show_api: bool = True,
+    time_limit: int | None = None,
+    stream_every: float = 0.5,
+) -> _Dependency[T, Any, P]: ...
+
+class Events:
+    change: EventListener
+    input: EventListener
+    click: EventListener
+    double_click: EventListener
+    submit: EventListener
+    edit: EventListener
+    clear: EventListener
+    play: EventListener
+    pause: EventListener
+    stop: EventListener
+    end: EventListener
+    start_recording: EventListener
+    pause_recording: EventListener
+    stop_recording: EventListener
+    focus: EventListener
+    blur: EventListener
+    upload: EventListener
+    release: EventListener
+    select: EventListener
+    stream: EventListener
+    like: EventListener
+    example_select: EventListener
+    load: EventListener
+    key_up: EventListener
+    apply: EventListener
+    delete: EventListener
+    tick: EventListener
+    undo: EventListener
+    retry: EventListener
+    expand: EventListener
+    collapse: EventListener
+    download: EventListener
+
+__all__ = [
+    "DeletedFileData",
+    "Dependency",
+    "DownloadData",
+    "EventData",
+    "EventListener",
+    "EventListenerMethod",
+    "Events",
+    "KeyUpData",
+    "LikeData",
+    "RetryData",
+    "SelectData",
+    "UndoData",
+    "on",
+    "set_cancel_events",
+]

src/ultimate_rvc/stubs/pedalboard_native/io/__init__.pyi

@@ -0,0 +1,41 @@
+from typing import Literal, Self, overload
+
+import numpy as np
+from numpy.typing import NDArray
+
+class AudioFile:
+    @classmethod
+    @overload
+    def __new__(
+        cls: object,
+        filename: str,
+        mode: Literal["r"] = "r",
+    ) -> ReadableAudioFile: ...
+    @classmethod
+    @overload
+    def __new__(
+        cls: object,
+        filename: str,
+        mode: Literal["w"],
+        samplerate: float | None = None,
+        num_channels: int = 1,
+        bit_depth: int = 16,
+        quality: str | float | None = None,
+    ) -> WriteableAudioFile: ...
+
+class ReadableAudioFile(AudioFile):
+    def __enter__(self) -> Self: ...
+    def __exit__(self, arg0: object, arg1: object, arg2: object) -> None: ...
+    def read(self, num_frames: float = 0) -> NDArray[np.float32]: ...
+    def tell(self) -> int: ...
+    @property
+    def frames(self) -> int: ...
+    @property
+    def num_channels(self) -> int: ...
+    @property
+    def samplerate(self) -> float | int: ...
+
+class WriteableAudioFile(AudioFile):
+    def __enter__(self) -> Self: ...
+    def __exit__(self, arg0: object, arg1: object, arg2: object) -> None: ...
+    def write(self, samples: NDArray[...]) -> None: ...

src/ultimate_rvc/stubs/soundfile/__init__.pyi

@@ -0,0 +1,34 @@
+from typing import Literal
+
+from os import PathLike
+
+import numpy as np
+from numpy.typing import NDArray
+
+type DEFAULT_NDARRAY = NDArray[np.float64 | np.float32 | np.int32 | np.int16]
+
+def read(
+    file: int | str | PathLike[str] | PathLike[bytes],
+    frames: int = -1,
+    start: int = 0,
+    stop: int | None = None,
+    dtype: Literal["float64", "float32", "int32", "int16"] = "float64",
+    always_2d: bool = False,
+    fill_value: float | None = None,
+    out: DEFAULT_NDARRAY | None = None,
+    samplerate: int | None = None,
+    channels: int | None = None,
+    format: str | None = None,  # noqa: A002
+    subtype: str | None = None,
+    endian: Literal["FILE", "LITTLE", "BIG", "CPU"] | None = None,
+    closefd: bool | None = True,
+) -> tuple[DEFAULT_NDARRAY, int]: ...
+def write(
+    file: int | str | PathLike[str] | PathLike[bytes],
+    data: DEFAULT_NDARRAY,
+    samplerate: int,
+    subtype: str | None = None,
+    endian: Literal["FILE", "LITTLE", "BIG", "CPU"] | None = None,
+    format: str | None = None,  # noqa: A002
+    closefd: bool | None = True,
+) -> None: ...

src/ultimate_rvc/stubs/sox/__init__.pyi

@@ -0,0 +1,19 @@
+from typing import Self
+
+from pathlib import Path
+
+from numpy.typing import NDArray
+
+class Transformer:
+    def pitch(
+        self,
+        n_semitones: float,
+        quick: bool = False,
+    ) -> Self: ...
+    def build_array(
+        self,
+        input_filepath: str | Path | None = None,
+        input_array: NDArray[...] | None = None,
+        sample_rate_in: float | None = None,
+        extra_args: list[str] | None = None,
+    ) -> NDArray[...]: ...

src/ultimate_rvc/stubs/static_ffmpeg/__init__.pyi

@@ -0,0 +1 @@
+def add_paths(weak: bool = False) -> bool: ...

src/ultimate_rvc/stubs/static_sox/__init__.pyi

@@ -0,0 +1 @@
+def add_paths(weak: bool = False) -> bool: ...

src/ultimate_rvc/stubs/yt_dlp/__init__.pyi

@@ -0,0 +1,27 @@
+from typing import Any, Self
+
+class YoutubeDL:
+    def __init__(
+        self,
+        params: dict[str, Any] | None = None,
+        auto_init: bool = True,
+    ) -> None: ...
+    def extract_info(
+        self,
+        url: str,
+        download: bool = True,
+        ie_key: str | None = None,
+        extra_info: dict[str, Any] | None = None,
+        process: bool = True,
+        force_generic_extractor: bool = False,
+    ) -> dict[str, Any]: ...
+    def prepare_filename(
+        self,
+        info_dict: dict[str, Any],
+        dir_type: str = "",
+        *,
+        outtmpl: str | None = None,
+        warn: bool = False,
+    ) -> str: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(self, *args: object) -> None: ...

src/ultimate_rvc/typing_extra.py

@@ -0,0 +1,56 @@
+"""Extra typing for the Ultimate RVC project."""
+
+from collections.abc import Mapping, Sequence
+from enum import IntEnum, StrEnum
+from os import PathLike
+
+type StrPath = str | PathLike[str]
+
+type Json = Mapping[str, Json] | Sequence[Json] | str | int | float | bool | None
+
+
+class SeparationModel(StrEnum):
+    """The model to use for audio separation."""
+
+    UVR_MDX_NET_VOC_FT = "UVR-MDX-NET-Voc_FT.onnx"
+    UVR_MDX_NET_KARA_2 = "UVR_MDXNET_KARA_2.onnx"
+    REVERB_HQ_BY_FOXJOY = "Reverb_HQ_By_FoxJoy.onnx"
+
+
+class SegmentSize(IntEnum):
+    """The segment size to use for audio separation."""
+
+    SEG_64 = 64
+    SEG_128 = 128
+    SEG_256 = 256
+    SEG_512 = 512
+    SEG_1024 = 1024
+    SEG_2048 = 2048
+
+
+class F0Method(StrEnum):
+    """The method to use for pitch detection."""
+
+    RMVPE = "rmvpe"
+    MANGIO_CREPE = "mangio-crepe"
+
+
+class SampleRate(IntEnum):
+    """The sample rate of an audio file."""
+
+    HZ_16000 = 16000
+    HZ_44100 = 44100
+    HZ_48000 = 48000
+    HZ_96000 = 96000
+    HZ_192000 = 192000
+
+
+class AudioExt(StrEnum):
+    """Audio file formats."""
+
+    MP3 = "mp3"
+    WAV = "wav"
+    FLAC = "flac"
+    OGG = "ogg"
+    M4A = "m4a"
+    AAC = "aac"

src/ultimate_rvc/vc/__init__.py

@@ -0,0 +1,8 @@
+"""
+Voice conversion package for the Ultimate RVC project.
+
+This package contains modules exposing functionality that enable voice
+conversion using RVC. The implementation code is primarily built on
+PyTorch to achieve high-performant processing using GPU acceleration.
+
+"""

src/ultimate_rvc/vc/configs/32k.json

@@ -0,0 +1,46 @@
+{
+  "train": {
+    "log_interval": 200,
+    "seed": 1234,
+    "epochs": 20000,
+    "learning_rate": 1e-4,
+    "betas": [0.8, 0.99],
+    "eps": 1e-9,
+    "batch_size": 4,
+    "fp16_run": false,
+    "lr_decay": 0.999875,
+    "segment_size": 12800,
+    "init_lr_ratio": 1,
+    "warmup_epochs": 0,
+    "c_mel": 45,
+    "c_kl": 1.0
+  },
+  "data": {
+    "max_wav_value": 32768.0,
+    "sampling_rate": 32000,
+    "filter_length": 1024,
+    "hop_length": 320,
+    "win_length": 1024,
+    "n_mel_channels": 80,
+    "mel_fmin": 0.0,
+    "mel_fmax": null
+  },
+  "model": {
+    "inter_channels": 192,
+    "hidden_channels": 192,
+    "filter_channels": 768,
+    "n_heads": 2,
+    "n_layers": 6,
+    "kernel_size": 3,
+    "p_dropout": 0,
+    "resblock": "1",
+    "resblock_kernel_sizes": [3,7,11],
+    "resblock_dilation_sizes": [[1,3,5], [1,3,5], [1,3,5]],
+    "upsample_rates": [10,4,2,2,2],
+    "upsample_initial_channel": 512,
+    "upsample_kernel_sizes": [16,16,4,4,4],
+    "use_spectral_norm": false,
+    "gin_channels": 256,
+    "spk_embed_dim": 109
+  }
+}

src/ultimate_rvc/vc/configs/32k_v2.json

@@ -0,0 +1,46 @@
+{
+  "train": {
+    "log_interval": 200,
+    "seed": 1234,
+    "epochs": 20000,
+    "learning_rate": 1e-4,
+    "betas": [0.8, 0.99],
+    "eps": 1e-9,
+    "batch_size": 4,
+    "fp16_run": true,
+    "lr_decay": 0.999875,
+    "segment_size": 12800,
+    "init_lr_ratio": 1,
+    "warmup_epochs": 0,
+    "c_mel": 45,
+    "c_kl": 1.0
+  },
+  "data": {
+    "max_wav_value": 32768.0,
+    "sampling_rate": 32000,
+    "filter_length": 1024,
+    "hop_length": 320,
+    "win_length": 1024,
+    "n_mel_channels": 80,
+    "mel_fmin": 0.0,
+    "mel_fmax": null
+  },
+  "model": {
+    "inter_channels": 192,
+    "hidden_channels": 192,
+    "filter_channels": 768,
+    "n_heads": 2,
+    "n_layers": 6,
+    "kernel_size": 3,
+    "p_dropout": 0,
+    "resblock": "1",
+    "resblock_kernel_sizes": [3,7,11],
+    "resblock_dilation_sizes": [[1,3,5], [1,3,5], [1,3,5]],
+    "upsample_rates": [10,8,2,2],
+    "upsample_initial_channel": 512,
+    "upsample_kernel_sizes": [20,16,4,4],
+    "use_spectral_norm": false,
+    "gin_channels": 256,
+    "spk_embed_dim": 109
+  }
+}

src/ultimate_rvc/vc/configs/40k.json

@@ -0,0 +1,46 @@
+{
+  "train": {
+    "log_interval": 200,
+    "seed": 1234,
+    "epochs": 20000,
+    "learning_rate": 1e-4,
+    "betas": [0.8, 0.99],
+    "eps": 1e-9,
+    "batch_size": 4,
+    "fp16_run": false,
+    "lr_decay": 0.999875,
+    "segment_size": 12800,
+    "init_lr_ratio": 1,
+    "warmup_epochs": 0,
+    "c_mel": 45,
+    "c_kl": 1.0
+  },
+  "data": {
+    "max_wav_value": 32768.0,
+    "sampling_rate": 40000,
+    "filter_length": 2048,
+    "hop_length": 400,
+    "win_length": 2048,
+    "n_mel_channels": 125,
+    "mel_fmin": 0.0,
+    "mel_fmax": null
+  },
+  "model": {
+    "inter_channels": 192,
+    "hidden_channels": 192,
+    "filter_channels": 768,
+    "n_heads": 2,
+    "n_layers": 6,
+    "kernel_size": 3,
+    "p_dropout": 0,
+    "resblock": "1",
+    "resblock_kernel_sizes": [3,7,11],
+    "resblock_dilation_sizes": [[1,3,5], [1,3,5], [1,3,5]],
+    "upsample_rates": [10,10,2,2],
+    "upsample_initial_channel": 512,
+    "upsample_kernel_sizes": [16,16,4,4],
+    "use_spectral_norm": false,
+    "gin_channels": 256,
+    "spk_embed_dim": 109
+  }
+}

src/ultimate_rvc/vc/configs/48k.json

@@ -0,0 +1,46 @@
+{
+  "train": {
+    "log_interval": 200,
+    "seed": 1234,
+    "epochs": 20000,
+    "learning_rate": 1e-4,
+    "betas": [0.8, 0.99],
+    "eps": 1e-9,
+    "batch_size": 4,
+    "fp16_run": false,
+    "lr_decay": 0.999875,
+    "segment_size": 11520,
+    "init_lr_ratio": 1,
+    "warmup_epochs": 0,
+    "c_mel": 45,
+    "c_kl": 1.0
+  },
+  "data": {
+    "max_wav_value": 32768.0,
+    "sampling_rate": 48000,
+    "filter_length": 2048,
+    "hop_length": 480,
+    "win_length": 2048,
+    "n_mel_channels": 128,
+    "mel_fmin": 0.0,
+    "mel_fmax": null
+  },
+  "model": {
+    "inter_channels": 192,
+    "hidden_channels": 192,
+    "filter_channels": 768,
+    "n_heads": 2,
+    "n_layers": 6,
+    "kernel_size": 3,
+    "p_dropout": 0,
+    "resblock": "1",
+    "resblock_kernel_sizes": [3,7,11],
+    "resblock_dilation_sizes": [[1,3,5], [1,3,5], [1,3,5]],
+    "upsample_rates": [10,6,2,2,2],
+    "upsample_initial_channel": 512,
+    "upsample_kernel_sizes": [16,16,4,4,4],
+    "use_spectral_norm": false,
+    "gin_channels": 256,
+    "spk_embed_dim": 109
+  }
+}

src/ultimate_rvc/vc/configs/48k_v2.json

@@ -0,0 +1,46 @@
+{
+  "train": {
+    "log_interval": 200,
+    "seed": 1234,
+    "epochs": 20000,
+    "learning_rate": 1e-4,
+    "betas": [0.8, 0.99],
+    "eps": 1e-9,
+    "batch_size": 4,
+    "fp16_run": true,
+    "lr_decay": 0.999875,
+    "segment_size": 17280,
+    "init_lr_ratio": 1,
+    "warmup_epochs": 0,
+    "c_mel": 45,
+    "c_kl": 1.0
+  },
+  "data": {
+    "max_wav_value": 32768.0,
+    "sampling_rate": 48000,
+    "filter_length": 2048,
+    "hop_length": 480,
+    "win_length": 2048,
+    "n_mel_channels": 128,
+    "mel_fmin": 0.0,
+    "mel_fmax": null
+  },
+  "model": {
+    "inter_channels": 192,
+    "hidden_channels": 192,
+    "filter_channels": 768,
+    "n_heads": 2,
+    "n_layers": 6,
+    "kernel_size": 3,
+    "p_dropout": 0,
+    "resblock": "1",
+    "resblock_kernel_sizes": [3,7,11],
+    "resblock_dilation_sizes": [[1,3,5], [1,3,5], [1,3,5]],
+    "upsample_rates": [12,10,2,2],
+    "upsample_initial_channel": 512,
+    "upsample_kernel_sizes": [24,20,4,4],
+    "use_spectral_norm": false,
+    "gin_channels": 256,
+    "spk_embed_dim": 109
+  }
+}

src/ultimate_rvc/vc/infer_pack/attentions.py

@@ -0,0 +1,417 @@
+import copy
+import math
+import numpy as np
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+from ultimate_rvc.vc.infer_pack import commons
+from ultimate_rvc.vc.infer_pack import modules
+from ultimate_rvc.vc.infer_pack.modules import LayerNorm
+
+
+class Encoder(nn.Module):
+    def __init__(
+        self,
+        hidden_channels,
+        filter_channels,
+        n_heads,
+        n_layers,
+        kernel_size=1,
+        p_dropout=0.0,
+        window_size=10,
+        **kwargs
+    ):
+        super().__init__()
+        self.hidden_channels = hidden_channels
+        self.filter_channels = filter_channels
+        self.n_heads = n_heads
+        self.n_layers = n_layers
+        self.kernel_size = kernel_size
+        self.p_dropout = p_dropout
+        self.window_size = window_size
+
+        self.drop = nn.Dropout(p_dropout)
+        self.attn_layers = nn.ModuleList()
+        self.norm_layers_1 = nn.ModuleList()
+        self.ffn_layers = nn.ModuleList()
+        self.norm_layers_2 = nn.ModuleList()
+        for i in range(self.n_layers):
+            self.attn_layers.append(
+                MultiHeadAttention(
+                    hidden_channels,
+                    hidden_channels,
+                    n_heads,
+                    p_dropout=p_dropout,
+                    window_size=window_size,
+                )
+            )
+            self.norm_layers_1.append(LayerNorm(hidden_channels))
+            self.ffn_layers.append(
+                FFN(
+                    hidden_channels,
+                    hidden_channels,
+                    filter_channels,
+                    kernel_size,
+                    p_dropout=p_dropout,
+                )
+            )
+            self.norm_layers_2.append(LayerNorm(hidden_channels))
+
+    def forward(self, x, x_mask):
+        attn_mask = x_mask.unsqueeze(2) * x_mask.unsqueeze(-1)
+        x = x * x_mask
+        for i in range(self.n_layers):
+            y = self.attn_layers[i](x, x, attn_mask)
+            y = self.drop(y)
+            x = self.norm_layers_1[i](x + y)
+
+            y = self.ffn_layers[i](x, x_mask)
+            y = self.drop(y)
+            x = self.norm_layers_2[i](x + y)
+        x = x * x_mask
+        return x
+
+
+class Decoder(nn.Module):
+    def __init__(
+        self,
+        hidden_channels,
+        filter_channels,
+        n_heads,
+        n_layers,
+        kernel_size=1,
+        p_dropout=0.0,
+        proximal_bias=False,
+        proximal_init=True,
+        **kwargs
+    ):
+        super().__init__()
+        self.hidden_channels = hidden_channels
+        self.filter_channels = filter_channels
+        self.n_heads = n_heads
+        self.n_layers = n_layers
+        self.kernel_size = kernel_size
+        self.p_dropout = p_dropout
+        self.proximal_bias = proximal_bias
+        self.proximal_init = proximal_init
+
+        self.drop = nn.Dropout(p_dropout)
+        self.self_attn_layers = nn.ModuleList()
+        self.norm_layers_0 = nn.ModuleList()
+        self.encdec_attn_layers = nn.ModuleList()
+        self.norm_layers_1 = nn.ModuleList()
+        self.ffn_layers = nn.ModuleList()
+        self.norm_layers_2 = nn.ModuleList()
+        for i in range(self.n_layers):
+            self.self_attn_layers.append(
+                MultiHeadAttention(
+                    hidden_channels,
+                    hidden_channels,
+                    n_heads,
+                    p_dropout=p_dropout,
+                    proximal_bias=proximal_bias,
+                    proximal_init=proximal_init,
+                )
+            )
+            self.norm_layers_0.append(LayerNorm(hidden_channels))
+            self.encdec_attn_layers.append(
+                MultiHeadAttention(
+                    hidden_channels, hidden_channels, n_heads, p_dropout=p_dropout
+                )
+            )
+            self.norm_layers_1.append(LayerNorm(hidden_channels))
+            self.ffn_layers.append(
+                FFN(
+                    hidden_channels,
+                    hidden_channels,
+                    filter_channels,
+                    kernel_size,
+                    p_dropout=p_dropout,
+                    causal=True,
+                )
+            )
+            self.norm_layers_2.append(LayerNorm(hidden_channels))
+
+    def forward(self, x, x_mask, h, h_mask):
+        """
+        x: decoder input
+        h: encoder output
+        """
+        self_attn_mask = commons.subsequent_mask(x_mask.size(2)).to(
+            device=x.device, dtype=x.dtype
+        )
+        encdec_attn_mask = h_mask.unsqueeze(2) * x_mask.unsqueeze(-1)
+        x = x * x_mask
+        for i in range(self.n_layers):
+            y = self.self_attn_layers[i](x, x, self_attn_mask)
+            y = self.drop(y)
+            x = self.norm_layers_0[i](x + y)
+
+            y = self.encdec_attn_layers[i](x, h, encdec_attn_mask)
+            y = self.drop(y)
+            x = self.norm_layers_1[i](x + y)
+
+            y = self.ffn_layers[i](x, x_mask)
+            y = self.drop(y)
+            x = self.norm_layers_2[i](x + y)
+        x = x * x_mask
+        return x
+
+
+class MultiHeadAttention(nn.Module):
+    def __init__(
+        self,
+        channels,
+        out_channels,
+        n_heads,
+        p_dropout=0.0,
+        window_size=None,
+        heads_share=True,
+        block_length=None,
+        proximal_bias=False,
+        proximal_init=False,
+    ):
+        super().__init__()
+        assert channels % n_heads == 0
+
+        self.channels = channels
+        self.out_channels = out_channels
+        self.n_heads = n_heads
+        self.p_dropout = p_dropout
+        self.window_size = window_size
+        self.heads_share = heads_share
+        self.block_length = block_length
+        self.proximal_bias = proximal_bias
+        self.proximal_init = proximal_init
+        self.attn = None
+
+        self.k_channels = channels // n_heads
+        self.conv_q = nn.Conv1d(channels, channels, 1)
+        self.conv_k = nn.Conv1d(channels, channels, 1)
+        self.conv_v = nn.Conv1d(channels, channels, 1)
+        self.conv_o = nn.Conv1d(channels, out_channels, 1)
+        self.drop = nn.Dropout(p_dropout)
+
+        if window_size is not None:
+            n_heads_rel = 1 if heads_share else n_heads
+            rel_stddev = self.k_channels**-0.5
+            self.emb_rel_k = nn.Parameter(
+                torch.randn(n_heads_rel, window_size * 2 + 1, self.k_channels)
+                * rel_stddev
+            )
+            self.emb_rel_v = nn.Parameter(
+                torch.randn(n_heads_rel, window_size * 2 + 1, self.k_channels)
+                * rel_stddev
+            )
+
+        nn.init.xavier_uniform_(self.conv_q.weight)
+        nn.init.xavier_uniform_(self.conv_k.weight)
+        nn.init.xavier_uniform_(self.conv_v.weight)
+        if proximal_init:
+            with torch.no_grad():
+                self.conv_k.weight.copy_(self.conv_q.weight)
+                self.conv_k.bias.copy_(self.conv_q.bias)
+
+    def forward(self, x, c, attn_mask=None):
+        q = self.conv_q(x)
+        k = self.conv_k(c)
+        v = self.conv_v(c)
+
+        x, self.attn = self.attention(q, k, v, mask=attn_mask)
+
+        x = self.conv_o(x)
+        return x
+
+    def attention(self, query, key, value, mask=None):
+        # reshape [b, d, t] -> [b, n_h, t, d_k]
+        b, d, t_s, t_t = (*key.size(), query.size(2))
+        query = query.view(b, self.n_heads, self.k_channels, t_t).transpose(2, 3)
+        key = key.view(b, self.n_heads, self.k_channels, t_s).transpose(2, 3)
+        value = value.view(b, self.n_heads, self.k_channels, t_s).transpose(2, 3)
+
+        scores = torch.matmul(query / math.sqrt(self.k_channels), key.transpose(-2, -1))
+        if self.window_size is not None:
+            assert (
+                t_s == t_t
+            ), "Relative attention is only available for self-attention."
+            key_relative_embeddings = self._get_relative_embeddings(self.emb_rel_k, t_s)
+            rel_logits = self._matmul_with_relative_keys(
+                query / math.sqrt(self.k_channels), key_relative_embeddings
+            )
+            scores_local = self._relative_position_to_absolute_position(rel_logits)
+            scores = scores + scores_local
+        if self.proximal_bias:
+            assert t_s == t_t, "Proximal bias is only available for self-attention."
+            scores = scores + self._attention_bias_proximal(t_s).to(
+                device=scores.device, dtype=scores.dtype
+            )
+        if mask is not None:
+            scores = scores.masked_fill(mask == 0, -1e4)
+            if self.block_length is not None:
+                assert (
+                    t_s == t_t
+                ), "Local attention is only available for self-attention."
+                block_mask = (
+                    torch.ones_like(scores)
+                    .triu(-self.block_length)
+                    .tril(self.block_length)
+                )
+                scores = scores.masked_fill(block_mask == 0, -1e4)
+        p_attn = F.softmax(scores, dim=-1)  # [b, n_h, t_t, t_s]
+        p_attn = self.drop(p_attn)
+        output = torch.matmul(p_attn, value)
+        if self.window_size is not None:
+            relative_weights = self._absolute_position_to_relative_position(p_attn)
+            value_relative_embeddings = self._get_relative_embeddings(
+                self.emb_rel_v, t_s
+            )
+            output = output + self._matmul_with_relative_values(
+                relative_weights, value_relative_embeddings
+            )
+        output = (
+            output.transpose(2, 3).contiguous().view(b, d, t_t)
+        )  # [b, n_h, t_t, d_k] -> [b, d, t_t]
+        return output, p_attn
+
+    def _matmul_with_relative_values(self, x, y):
+        """
+        x: [b, h, l, m]
+        y: [h or 1, m, d]
+        ret: [b, h, l, d]
+        """
+        ret = torch.matmul(x, y.unsqueeze(0))
+        return ret
+
+    def _matmul_with_relative_keys(self, x, y):
+        """
+        x: [b, h, l, d]
+        y: [h or 1, m, d]
+        ret: [b, h, l, m]
+        """
+        ret = torch.matmul(x, y.unsqueeze(0).transpose(-2, -1))
+        return ret
+
+    def _get_relative_embeddings(self, relative_embeddings, length):
+        max_relative_position = 2 * self.window_size + 1
+        # Pad first before slice to avoid using cond ops.
+        pad_length = max(length - (self.window_size + 1), 0)
+        slice_start_position = max((self.window_size + 1) - length, 0)
+        slice_end_position = slice_start_position + 2 * length - 1
+        if pad_length > 0:
+            padded_relative_embeddings = F.pad(
+                relative_embeddings,
+                commons.convert_pad_shape([[0, 0], [pad_length, pad_length], [0, 0]]),
+            )
+        else:
+            padded_relative_embeddings = relative_embeddings
+        used_relative_embeddings = padded_relative_embeddings[
+            :, slice_start_position:slice_end_position
+        ]
+        return used_relative_embeddings
+
+    def _relative_position_to_absolute_position(self, x):
+        """
+        x: [b, h, l, 2*l-1]
+        ret: [b, h, l, l]
+        """
+        batch, heads, length, _ = x.size()
+        # Concat columns of pad to shift from relative to absolute indexing.
+        x = F.pad(x, commons.convert_pad_shape([[0, 0], [0, 0], [0, 0], [0, 1]]))
+
+        # Concat extra elements so to add up to shape (len+1, 2*len-1).
+        x_flat = x.view([batch, heads, length * 2 * length])
+        x_flat = F.pad(
+            x_flat, commons.convert_pad_shape([[0, 0], [0, 0], [0, length - 1]])
+        )
+
+        # Reshape and slice out the padded elements.
+        x_final = x_flat.view([batch, heads, length + 1, 2 * length - 1])[
+            :, :, :length, length - 1 :
+        ]
+        return x_final
+
+    def _absolute_position_to_relative_position(self, x):
+        """
+        x: [b, h, l, l]
+        ret: [b, h, l, 2*l-1]
+        """
+        batch, heads, length, _ = x.size()
+        # padd along column
+        x = F.pad(
+            x, commons.convert_pad_shape([[0, 0], [0, 0], [0, 0], [0, length - 1]])
+        )
+        x_flat = x.view([batch, heads, length**2 + length * (length - 1)])
+        # add 0's in the beginning that will skew the elements after reshape
+        x_flat = F.pad(x_flat, commons.convert_pad_shape([[0, 0], [0, 0], [length, 0]]))
+        x_final = x_flat.view([batch, heads, length, 2 * length])[:, :, :, 1:]
+        return x_final
+
+    def _attention_bias_proximal(self, length):
+        """Bias for self-attention to encourage attention to close positions.
+        Args:
+          length: an integer scalar.
+        Returns:
+          a Tensor with shape [1, 1, length, length]
+        """
+        r = torch.arange(length, dtype=torch.float32)
+        diff = torch.unsqueeze(r, 0) - torch.unsqueeze(r, 1)
+        return torch.unsqueeze(torch.unsqueeze(-torch.log1p(torch.abs(diff)), 0), 0)
+
+
+class FFN(nn.Module):
+    def __init__(
+        self,
+        in_channels,
+        out_channels,
+        filter_channels,
+        kernel_size,
+        p_dropout=0.0,
+        activation=None,
+        causal=False,
+    ):
+        super().__init__()
+        self.in_channels = in_channels
+        self.out_channels = out_channels
+        self.filter_channels = filter_channels
+        self.kernel_size = kernel_size
+        self.p_dropout = p_dropout
+        self.activation = activation
+        self.causal = causal
+
+        if causal:
+            self.padding = self._causal_padding
+        else:
+            self.padding = self._same_padding
+
+        self.conv_1 = nn.Conv1d(in_channels, filter_channels, kernel_size)
+        self.conv_2 = nn.Conv1d(filter_channels, out_channels, kernel_size)
+        self.drop = nn.Dropout(p_dropout)
+
+    def forward(self, x, x_mask):
+        x = self.conv_1(self.padding(x * x_mask))
+        if self.activation == "gelu":
+            x = x * torch.sigmoid(1.702 * x)
+        else:
+            x = torch.relu(x)
+        x = self.drop(x)
+        x = self.conv_2(self.padding(x * x_mask))
+        return x * x_mask
+
+    def _causal_padding(self, x):
+        if self.kernel_size == 1:
+            return x
+        pad_l = self.kernel_size - 1
+        pad_r = 0
+        padding = [[0, 0], [0, 0], [pad_l, pad_r]]
+        x = F.pad(x, commons.convert_pad_shape(padding))
+        return x
+
+    def _same_padding(self, x):
+        if self.kernel_size == 1:
+            return x
+        pad_l = (self.kernel_size - 1) // 2
+        pad_r = self.kernel_size // 2
+        padding = [[0, 0], [0, 0], [pad_l, pad_r]]
+        x = F.pad(x, commons.convert_pad_shape(padding))
+        return x

src/ultimate_rvc/vc/infer_pack/commons.py

@@ -0,0 +1,166 @@
+import math
+import numpy as np
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+
+def init_weights(m, mean=0.0, std=0.01):
+    classname = m.__class__.__name__
+    if classname.find("Conv") != -1:
+        m.weight.data.normal_(mean, std)
+
+
+def get_padding(kernel_size, dilation=1):
+    return int((kernel_size * dilation - dilation) / 2)
+
+
+def convert_pad_shape(pad_shape):
+    l = pad_shape[::-1]
+    pad_shape = [item for sublist in l for item in sublist]
+    return pad_shape
+
+
+def kl_divergence(m_p, logs_p, m_q, logs_q):
+    """KL(P||Q)"""
+    kl = (logs_q - logs_p) - 0.5
+    kl += (
+        0.5 * (torch.exp(2.0 * logs_p) + ((m_p - m_q) ** 2)) * torch.exp(-2.0 * logs_q)
+    )
+    return kl
+
+
+def rand_gumbel(shape):
+    """Sample from the Gumbel distribution, protect from overflows."""
+    uniform_samples = torch.rand(shape) * 0.99998 + 0.00001
+    return -torch.log(-torch.log(uniform_samples))
+
+
+def rand_gumbel_like(x):
+    g = rand_gumbel(x.size()).to(dtype=x.dtype, device=x.device)
+    return g
+
+
+def slice_segments(x, ids_str, segment_size=4):
+    ret = torch.zeros_like(x[:, :, :segment_size])
+    for i in range(x.size(0)):
+        idx_str = ids_str[i]
+        idx_end = idx_str + segment_size
+        ret[i] = x[i, :, idx_str:idx_end]
+    return ret
+
+
+def slice_segments2(x, ids_str, segment_size=4):
+    ret = torch.zeros_like(x[:, :segment_size])
+    for i in range(x.size(0)):
+        idx_str = ids_str[i]
+        idx_end = idx_str + segment_size
+        ret[i] = x[i, idx_str:idx_end]
+    return ret
+
+
+def rand_slice_segments(x, x_lengths=None, segment_size=4):
+    b, d, t = x.size()
+    if x_lengths is None:
+        x_lengths = t
+    ids_str_max = x_lengths - segment_size + 1
+    ids_str = (torch.rand([b]).to(device=x.device) * ids_str_max).to(dtype=torch.long)
+    ret = slice_segments(x, ids_str, segment_size)
+    return ret, ids_str
+
+
+def get_timing_signal_1d(length, channels, min_timescale=1.0, max_timescale=1.0e4):
+    position = torch.arange(length, dtype=torch.float)
+    num_timescales = channels // 2
+    log_timescale_increment = math.log(float(max_timescale) / float(min_timescale)) / (
+        num_timescales - 1
+    )
+    inv_timescales = min_timescale * torch.exp(
+        torch.arange(num_timescales, dtype=torch.float) * -log_timescale_increment
+    )
+    scaled_time = position.unsqueeze(0) * inv_timescales.unsqueeze(1)
+    signal = torch.cat([torch.sin(scaled_time), torch.cos(scaled_time)], 0)
+    signal = F.pad(signal, [0, 0, 0, channels % 2])
+    signal = signal.view(1, channels, length)
+    return signal
+
+
+def add_timing_signal_1d(x, min_timescale=1.0, max_timescale=1.0e4):
+    b, channels, length = x.size()
+    signal = get_timing_signal_1d(length, channels, min_timescale, max_timescale)
+    return x + signal.to(dtype=x.dtype, device=x.device)
+
+
+def cat_timing_signal_1d(x, min_timescale=1.0, max_timescale=1.0e4, axis=1):
+    b, channels, length = x.size()
+    signal = get_timing_signal_1d(length, channels, min_timescale, max_timescale)
+    return torch.cat([x, signal.to(dtype=x.dtype, device=x.device)], axis)
+
+
+def subsequent_mask(length):
+    mask = torch.tril(torch.ones(length, length)).unsqueeze(0).unsqueeze(0)
+    return mask
+
+
+@torch.jit.script
+def fused_add_tanh_sigmoid_multiply(input_a, input_b, n_channels):
+    n_channels_int = n_channels[0]
+    in_act = input_a + input_b
+    t_act = torch.tanh(in_act[:, :n_channels_int, :])
+    s_act = torch.sigmoid(in_act[:, n_channels_int:, :])
+    acts = t_act * s_act
+    return acts
+
+
+def convert_pad_shape(pad_shape):
+    l = pad_shape[::-1]
+    pad_shape = [item for sublist in l for item in sublist]
+    return pad_shape
+
+
+def shift_1d(x):
+    x = F.pad(x, convert_pad_shape([[0, 0], [0, 0], [1, 0]]))[:, :, :-1]
+    return x
+
+
+def sequence_mask(length, max_length=None):
+    if max_length is None:
+        max_length = length.max()
+    x = torch.arange(max_length, dtype=length.dtype, device=length.device)
+    return x.unsqueeze(0) < length.unsqueeze(1)
+
+
+def generate_path(duration, mask):
+    """
+    duration: [b, 1, t_x]
+    mask: [b, 1, t_y, t_x]
+    """
+    device = duration.device
+
+    b, _, t_y, t_x = mask.shape
+    cum_duration = torch.cumsum(duration, -1)
+
+    cum_duration_flat = cum_duration.view(b * t_x)
+    path = sequence_mask(cum_duration_flat, t_y).to(mask.dtype)
+    path = path.view(b, t_x, t_y)
+    path = path - F.pad(path, convert_pad_shape([[0, 0], [1, 0], [0, 0]]))[:, :-1]
+    path = path.unsqueeze(1).transpose(2, 3) * mask
+    return path
+
+
+def clip_grad_value_(parameters, clip_value, norm_type=2):
+    if isinstance(parameters, torch.Tensor):
+        parameters = [parameters]
+    parameters = list(filter(lambda p: p.grad is not None, parameters))
+    norm_type = float(norm_type)
+    if clip_value is not None:
+        clip_value = float(clip_value)
+
+    total_norm = 0
+    for p in parameters:
+        param_norm = p.grad.data.norm(norm_type)
+        total_norm += param_norm.item() ** norm_type
+        if clip_value is not None:
+            p.grad.data.clamp_(min=-clip_value, max=clip_value)
+    total_norm = total_norm ** (1.0 / norm_type)
+    return total_norm