Prerequisites & Preparation

If you want to use CosyVoice, it is recommended to start preparing your environment with Miniconda.

What You Need to Prepare

  1. A computer or server capable of running CosyVoice — an NVIDIA GPU is recommended
  2. Miniconda, Git, and FFmpeg
  3. The CosyVoice repository and model files
  4. Your phone and host on the same local network, or a Cloudflare Tunnel already configured

One-Click Installer (Recommended)

There is a Windows script that wraps the whole "check → install → verify" chain. Download it and double-click.

Default install locations:

WhatDefault location
CosyVoice checkout, model weights, generated launcher%USERPROFILE%\NovelPlayer\CosyVoice (for example C:\Users\you\NovelPlayer\CosyVoice)
Installer cache, portable FFmpeg, logs, state file%LOCALAPPDATA%\NovelPlayer\CosyVoice

Plan on roughly 20 GB of free space on the target drive (PyTorch plus the model weights); the script warns and asks before continuing when less is available.

Download both files into the same folder:

These scripts are not digitally signed, so Windows may warn about an "unknown publisher" or SmartScreen, and running cosyvoice-install.ps1 directly is blocked by the execution policy - that is why you start it through the .bat. You can conduct security reviews yourself or use AI.

When it finishes, the script prints the address to paste into NovelPlayer, for example http://192.168.0.105:50001/.

Double-clicking cosyvoice-install.bat does not start installing straight away - it shows a small menu first:

  [1]  Install or continue         - recommended
  [2]  Install without model weights
  [3]  Install for CPU only        - no NVIDIA GPU
  [4]  Check only, do not install
  [5]  Change the Web UI password
  [0]  Cancel

Choosing 1-3 then asks for the following, and every one of them accepts the default when you just press Enter:

  • Install folder: defaults to %USERPROFILE%\NovelPlayer\CosyVoice, change it to something like D:\CosyVoice if you prefer
  • Port: defaults to 50001
  • Model name: defaults to Fun-CosyVoice3-0.5B
  • Web UI password: defaults to keeping novelplayer; answer no and you are asked for your own password after the install
  • Optional extras: download the model weights now, open the firewall port, run a smoke test, answer yes to everything from then on

On every start it compares webui.py against the latest revision on GitHub, shows you what changed, and asks whether to update. Declining is remembered, so the same revision will not ask again. Add -NoCheck to skip the check (useful offline).

Handy launcher options:

.\start-cosyvoice.bat -CheckOnly     # check only, do not start - good for diagnosing
.\start-cosyvoice.bat -NoCheck       # start without the online check
.\start-cosyvoice.bat -ForceUpdate   # apply a webui.py update without asking
.\start-cosyvoice.bat -SetPassword   # change the Web UI login password (any time)

Common Options

The menu builds these for you; to skip the menu and pass them yourself, put the arguments after the .bat (they are forwarded to cosyvoice-install.ps1 unchanged):

# install on drive D, download the model, and run a start-up self test
.\cosyvoice-install.bat -InstallDir D:\CosyVoice -DownloadModel -Yes -SmokeTest

# CPU only (no NVIDIA GPU)
.\cosyvoice-install.bat -CpuOnly

# also open the firewall port so your phone can connect (needs an admin PowerShell)
.\cosyvoice-install.bat -OpenFirewall

# also set the Web UI login password
.\cosyvoice-install.bat -Password "your own password"

Do not add -File in front of these - double-click the .bat or call it as shown. When passing arguments from PowerShell, quote the -InstallDir path, for example -InstallDir "D:\CosyVoice".

Started on CPU, Added a GPU Later

If no GPU was detected at install time, the CPU build of PyTorch was installed and synthesis is slow. You do not need to reinstall - just run the installer again:

  1. Double-click start-cosyvoice.bat. It notices that an NVIDIA GPU is now present while PyTorch is still the CPU build.
  2. It asks whether to switch to the CUDA build. Answer yes.
  3. It hands over to the installer, which downloads the CUDA build (a few GB). Restart when it finishes.

You can also switch from the command line, and -Yes skips the question:

.\cosyvoice-install.bat -InstallDir "D:\CosyVoice" -Yes

Or double-click start-cosyvoice.bat and answer yes when it asks about switching to the CUDA build - it hands back to the installer as well.

One related case: a GPU can be present while the NVIDIA driver is too old for CUDA 12.1, in which case even the CUDA build cannot use it. The scripts detect that and tell you to update the driver; run the installer again afterwards to move onto the GPU.

About the Script

Software it will install (anything already present is skipped, never overwritten)

ComponentNotes
GitInstalled via winget when available, otherwise the official installer runs silently
MinicondaCommon install locations are checked first; otherwise it goes into your user profile, so no admin rights are needed
FFmpegSkipped when it is already on PATH; otherwise a portable build is installed and added to your user-level PATH

What it puts on disk

ItemNotes
conda environmentCreates cosyvoice (Python 3.10) and calls it by absolute path, so you never need conda activate
CosyVoice sourcegit clone --recursive; submodule downloads that fail are retried automatically
webui.pySwapped for the NovelPlayer-compatible version (only when it does not match)
launcher-config.jsonRecords the install location, the port, the Web UI password and more; change the password later with start-cosyvoice.bat -SetPassword, and a rerun will not overwrite it
Python dependenciesInstalls requirements.txt; CUDA PyTorch when an NVIDIA GPU is present, CPU PyTorch otherwise
Model weightsSeveral GB, so it asks you first

What you end up with

ResultPurpose
start-cosyvoice.batLater starts are a double-click; it also runs the online update check and tells you whether synthesis runs on the GPU or the CPU
Logs and state fileRecord the result of every step; a rerun continues where it left off, and problems are diagnosed from here
  • The script never changes machine-wide settings and installs no system services; uninstalling means deleting the two folders listed above.
  • Losing your network or closing the window is safe: finished steps are recorded in a state file, so just run it again to continue.
  • The "Minimal Installation Flow" below is the manual route, useful if you want to control every step or to review what the script actually did.
  • The actual steps and results are whatever the script output and logs report.

Start with Miniconda

The upstream CosyVoice project recommends using a conda environment. For most users, installing Miniconda directly is lighter and simpler than the full Anaconda.

You can use the following official entry points:

Minimal Preparation Flow

  1. Install Miniconda and Git.
  2. Download FFmpeg and configure its environment variable.
  3. Create the cosyvoice environment.
  4. Clone the CosyVoice repository and models, and start the Web UI in the cosyvoice environment to verify.
  5. Replace with a compatible webui.py (GitHub source) and restart the Web UI or server.
  6. Fill the endpoint back into the NovelPlayer client.

Frequently asked questions

Minimal Installation Flow

After installing Miniconda, run the following commands:

git clone --recursive https://github.com/FunAudioLLM/CosyVoice.git

cd CosyVoice

conda create -n cosyvoice -y python=3.10

conda activate cosyvoice

pip install -r requirements.txt

Model downloads, ttsfrd, vllm, and Docker deployment steps change quickly, so please refer to the official CosyVoice documentation as the source of truth.

Reference launch command

conda activate cosyvoice

python webui.py --port 50001 --model_dir pretrained_models/Fun-CosyVoice3-0.5B

Target State After Launch

You can get a reachable CosyVoice address, for example:

http://192.168.1.119:50000/

Then, in the "Management" screen of NovelPlayer, fill it into the "CosyVoice address" field.

Boundaries You Should Know

  • CosyVoice is an external dependency and is not installed together with NovelPlayer.
  • NovelPlayer is responsible for consuming the CosyVoice API, not for deploying CosyVoice on your behalf.
  • When no CosyVoice endpoint is configured, the reader still works, but the audiobook pipeline is unavailable.

Important Notice

CosyVoice is an independent third-party open-source project (GitHub: FunAudioLLM/CosyVoice) that you deploy and manage yourself.

  • NovelPlayer does not provide voice cloning features. NovelPlayer itself does not include voice cloning, speech synthesis, or a TTS engine.
  • NovelPlayer only acts as a consumer, sending audio requests to an endpoint you specify.
  • You are fully responsible for having legal authorization for any voice samples you use. You must ensure you hold all necessary rights and licenses for any input voice sample.
  • Cloning, imitating, or impersonating another person's voice without explicit legal authorization is prohibited.

If your use of CosyVoice or another voice service involves voice cloning capabilities, please make sure to comply with applicable laws, regulations, and terms of service on your own.

Boundaries between preset audio samples and self-hosted samples:

  • Preset audio samples are original AI-designed virtual voices and are not based on any real human voice samples; the platform is responsible for their source and compliance.
  • Preset audio samples are provided with NovelPlayer as reference audio assets and do not depend on any cloud voice service; synthesis still happens in your own environment, and NovelPlayer does not participate in the final audio synthesis.
  • You are still responsible for: the text copyright of synthesized content, and the scope of use of preset audio samples (no resale, and no use for impersonation, defamation, or misleading purposes).
  • If you distribute audiobooks synthesized with preset audio samples externally, please clearly label the AI-generated content in accordance with applicable laws and regulations to avoid confusion or misidentification.
Visual Novel Experience
A scene-based reading experience that gives text novels more of a visual-novel feel.
Local Access to Your Voice Service
Get things working on the same Wi-Fi or LAN first — this is the most recommended first-stage advanced integration.