Skip to main content
This guide will help you set up your development environment to start contributing to ZZAR.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.14 or higher
  • Git for version control
  • pip for Python package management

​
Platform-Specific Requirements

# Python 3.14+ (download from python.org)
# Git (download from git-scm.com)

# Verify installations
python --version
git --version

​
Optional Tools

These tools are handled automatically by ZZAR’s setup wizards, but you can install them manually:
  • FFmpeg - Audio format conversion (Linux: sudo apt install ffmpeg)
  • vgmstream - WEM playback and conversion (Linux: sudo apt install vgmstream-cli)
  • Wine - Required on Linux to run Wwise (Linux: sudo apt install wine)

​
Clone the Repository

1

Clone ZZAR

Clone the repository to your local machine:
git clone https://github.com/Pucas01/ZZAR.git
cd ZZAR
2

Install Python Dependencies

Install all required Python packages from requirements.txt:
pip install -r requirements.txt
Core dependencies include:
  • requests>=2.31.0 - HTTP requests
  • pydub>=0.25.1 - Audio processing
  • numpy>=1.24.0 - Numerical operations
  • scipy>=1.10.0 - Scientific computing
  • Pillow>=10.0.0 - Image processing
  • PyQt5>=5.15.0 - GUI framework
3

Set Up Wwise (First Launch)

On first launch, ZZAR will prompt you to set up Wwise (needed for audio encoding):
# Launch ZZAR
python ZZAR.py

# Or use the provided launcher
start_gui.bat
ZZAR will automatically download and configure Wwise. You can also run the setup manually:
python setup_wwise.py
4

Configure Game Path

On first launch, ZZAR will try to auto-detect your Zenless Zone Zero installation. If it can’t find it, point it to your game’s data folder:
HoYoPlay/games/ZenlessZoneZero Game/ZenlessZoneZero_Data

​
Verify Installation

Test that everything is working: 
# Run ZZAR
python ZZAR.py
The application should launch with the main GUI. You can now:
  • Browse the audio browser to see game sounds
  • Test audio conversion features
  • Create and install mods

​
Development Mode

To enable development mode with additional debugging output:
  1. Open ZZAR.py
  2. Set DEV_MODE = True
  3. Run the application

​
Troubleshooting

​
ImportError: No module named ‘PyQt5’

Solution: Reinstall PyQt5 
pip install --force-reinstall PyQt5>=5.15.0

​
Wine not found (Linux)

Solution: Install Wine for Wwise support 
# Arch Linux
sudo pacman -S wine

# Debian/Ubuntu
sudo apt install wine

​
Audio playback issues (Linux)

Solution: Install GStreamer plugins 
sudo apt install gstreamer1.0-plugins-good gstreamer1.0-plugins-bad

​
Next Steps

Now that your environment is set up:
  1. Read the Development Guide to understand the codebase structure
  2. Learn how to Build Releases for distribution
  3. Check the GitHub Issues for tasks to work on

Build docs developers (and LLMs) love

Get started for freeTalk to us