Comprehensive Guide to Installing CosyVoice on Ubuntu 24.04

Step-by-Step Instructions for a Successful Deployment

Key Takeaways

• Preparation is Crucial: Ensure your system meets all prerequisites before installation.
• Utilize Docker for Efficient Deployment: Docker simplifies the setup process and manages dependencies effectively.
• Post-Installation Verification: Always verify the installation to ensure CosyVoice is running correctly.

Introduction

Installing CosyVoice on Ubuntu 24.04 involves a series of methodical steps to ensure a smooth and successful deployment. This guide provides a comprehensive walkthrough, integrating best practices and consensus methodologies to help you set up CosyVoice effectively.

System Requirements and Preparation

Verify System Compatibility

Before initiating the installation process, ensure that your system meets the necessary requirements to run CosyVoice efficiently:

• Operating System: Ubuntu 24.04 (Noble Numbat)
• Processor: Minimum dual-core CPU
• Memory: At least 8 GB RAM
• Storage: Minimum 20 GB free space
• GPU Support (Optional): NVIDIA GPU with appropriate drivers for enhanced performance

Update System Packages

Keeping your system updated ensures compatibility and stability during the installation process. Execute the following commands to update your package lists and upgrade existing packages:

sudo apt update && sudo apt upgrade -y

Install Essential Dependencies

CosyVoice requires several dependencies to function correctly. Install them using the following command:

sudo apt install docker.io git python3.8 python3.8-venv -y

If you plan to leverage GPU capabilities, install the NVIDIA drivers:

sudo apt install nvidia-driver-525 -y

Enable and start the Docker service:

sudo systemctl enable docker
sudo systemctl start docker

Installation Steps

Step 1: Install Docker and NVIDIA Drivers

Docker provides a containerized environment that simplifies the deployment of CosyVoice. Follow these steps to install Docker and NVIDIA drivers:

1. Install Docker:

   sudo apt-get update && sudo apt-get install docker.io -y

   After installation, verify Docker is running:

   sudo systemctl status docker

2. Install NVIDIA Drivers (Optional for GPU Support):

   For enhanced performance, especially for tasks involving speech synthesis, installing NVIDIA drivers is recommended. Visit the official NVIDIA website or use the following command:

   sudo apt install nvidia-driver-525 -y

   After installation, reboot your system:

   sudo reboot

Step 2: Clone the CosyVoice Repository

Obtaining the latest version of CosyVoice is essential. Clone the repository from GitHub using the following command:

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

This command ensures that all submodules are included, providing a complete and functional setup.

Step 3: Set Up the Docker Environment

Create a dedicated directory for Docker configurations within the project:

cd CosyVoice
mkdir docker

Move the necessary configuration files into the Docker directory:

cp compose.yaml requirements.txt docker/

Ensure that the compose.yaml file is correctly configured. An example configuration is as follows:

services:
  cosyvoice:
    container_name: cosyvoice
    image: cosyvoice:1.0
    restart: always
    ports:
      - 8888:8888
    environment:
      - TZ=Asia/Tokyo
      - NVIDIA_VISIBLE_DEVICES=all
    volumes:
      - ../../CosyVoice:/workspace/CosyVoice
    command: sh -c "docker/start.sh"

Step 4: Create and Activate Conda Environment

Using Conda ensures that all Python dependencies are isolated and managed efficiently:

conda create -n cosyvoice python=3.8 -y
conda activate cosyvoice

Navigate to the cloned repository directory:

cd CosyVoice

Step 5: Install Required Dependencies

Install the necessary Python packages as specified in the requirements.txt file:

pip install -r docker/requirements.txt

This step ensures that all libraries and frameworks needed by CosyVoice are available in your environment.

Step 6: Download Pre-Trained Models

CosyVoice relies on pre-trained models for speech synthesis. Use the following Python script to download them:

from modelscope import snapshot_download

snapshot_download('iic/CosyVoice2-0.5B', local_dir='pretrained_models/CosyVoice2-0.5B')
snapshot_download('iic/CosyVoice-300M', local_dir='pretrained_models/CosyVoice-300M')

Ensure that the models are downloaded to the specified directories.

Step 7: Launch the Docker Container

Start the Docker container to run CosyVoice:

cd docker
docker-compose -f compose.yaml up -d

This command runs CosyVoice in detached mode, allowing it to operate in the background.

Step 8: Verify Deployment

To confirm that CosyVoice is running correctly, open your web browser and navigate to:

http://localhost:8888

You should see the CosyVoice interface, indicating a successful deployment.

Post-Installation Configuration

Customize Settings

After installation, you may want to customize CosyVoice settings to better suit your needs. Locate the configuration files in the docker directory and adjust parameters such as language preferences, voice settings, and performance options.

Update and Maintain

Regularly update CosyVoice and its dependencies to ensure optimal performance and security. Use the following commands to update the repository and Docker images:

cd CosyVoice
git pull origin main
cd docker
docker-compose pull
docker-compose up -d

These commands fetch the latest updates and restart the Docker containers with the new configurations.

Troubleshooting

Common Issues and Solutions

• Docker Not Starting: Ensure that Docker is installed correctly and the service is running. Use sudo systemctl status docker to check the status.
• Dependency Errors: Verify that all dependencies are installed. Reinstall missing packages using pip install -r docker/requirements.txt.
• Model Download Failures: Check your internet connection and ensure that the download links are accessible. Retry the download if necessary.
• Port Conflicts: If port 8888 is in use, modify the compose.yaml file to use a different port.

Accessing Logs for Diagnosis

Inspect Docker container logs to identify and resolve issues:

docker logs cosyvoice

The logs provide detailed information about the container's operations and any errors encountered during runtime.

Advanced Configuration

Enabling GPU Acceleration

If you have an NVIDIA GPU, enabling GPU acceleration can significantly enhance CosyVoice's performance. Ensure that the NVIDIA drivers are correctly installed and the NVIDIA_VISIBLE_DEVICES environment variable is set in the compose.yaml file:

environment:
  - TZ=Asia/Tokyo
  - NVIDIA_VISIBLE_DEVICES=all

Restart the Docker container after making changes:

docker-compose down
docker-compose up -d

Integrating with Other Services

CosyVoice can be integrated with various services for enhanced functionality. For example, you can connect it with APIs for data input or output, or integrate with front-end interfaces for improved user interaction. Refer to the official documentation for detailed integration guides.

Conclusion

Installing CosyVoice on Ubuntu 24.04 is a straightforward process when following the outlined steps carefully. By preparing your system, utilizing Docker for deployment, and performing thorough post-installation checks, you can ensure a smooth and efficient setup. Regular maintenance and updates will keep CosyVoice running optimally, providing you with robust speech synthesis capabilities.

References

github.com

CosyVoice GitHub Repository

gpu-mart.com

GPU-Mart CosyVoice Installation Instructions