Metadata-Version: 2.4
Name: auto-chart-engine
Version: 2.0.0
Summary: This project streamlines charting for Clone Hero, the free PC rhythm game inspired by Guitar Hero/Rock Band. It generates highly accurate, playable charts directly from audio tracks using advanced extraction techniques like isolating drum tracks from MIDI and extracting precise note data. The engine dramatically reduces the time and effort needed to create custom song charts, enabling efficient creation of multiple songs.
Author: Ryan Roche, Bryant Vencill
Project-URL: Homepage, https://github.com/ryan-w-roche/auto-chart-engine
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Classifier: Intended Audience :: End Users/Desktop
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mido
Requires-Dist: rich
Dynamic: license-file

# Auto-Chart Engine (ACE)

## Overview
Clone Hero is a free rhythm game for PC, inspired by Guitar Hero and Rock Band, that allows players to create and play custom charts for any song. This project seeks to streamline and elevate the charting process by leveraging advanced extraction techniques to generate playable chart files directly from audio tracks. By isolating drum tracks from MIDI files and extracting precise note data, the engine produces highly accurate Clone Hero charts that accurately represent the original MIDI composition. This engine reduces the time required to chart a song, streamlining the creation of multiple songs in Clone Hero.


## Links
- **CLI Demonstration:** https://youtu.be/5lndr9maaSY?si=u9W6KzgyaVSeP5da
- **Git Repo:** https://github.com/ryan-w-roche/auto-chart-engine


## Install Instructions
**Dependencies:**
1. In the terminal, enter in the following command:
```Python
pip install -r requirements.txt
```
2. Install `fluidsynth` with `chocolatey (Windows)` or `homebrew (Mac)` or your Linux package manager:
```
choco install fluidsynth
```

**Software:**
- Moonscraper (testing/BPM editing): https://github.com/FireFox2000000/Moonscraper-Chart-Editor
- Clone Hero (song playability): https://clonehero.net


## CLI Usage
The Auto-Chart Engine CLI allows you to extract drum tracks from MIDI files and convert them into `.chart` files compatible with Clone Hero.

### Basic Usage
```
python -m ace -i /path/to/your/midi/file.mid -o /optional/output/directory
```

#### Required Arguments:
- `-i, --input_dir`: Path to the MIDI file you want to convert

#### Optional Arguments:
- `-o, --output_dir`: Directory where output files will be saved (defaults to your Downloads folder)

### Example
```
python -m ace -i "C:/Users/username/Music/my_song.mid" -o "C:/Users/username/Documents/CloneHero"
```

### How It Works
1. The CLI extracts the drum tracks from your MIDI file
2. Generates a new MIDI file containing only the drum tracks (saved with suffix "_DRUMS")
3. Based on the MIDI with the extracted drums, a `.ogg` version of the midi is generated
4. Converts this drum-only MIDI file into a Clone Hero compatible `.chart` file

### Generated Files
When you run the CLI, it produces 3 outputs:
1. A MIDI file containing only the drum tracks (named `<original_filename>_DRUMS.mid`)
2. A `.chart` file (named `<original_filename>_DRUMS.chart`)
3. A folder named `artist - <song_name> (ACE)`
      - Contains `notes.chart` and `song.ogg` files for Clone Hero

### Drum Mapping
The CLI maps standard drum notes to Clone Hero's drum notes:
- Kick → Line 
- Snare → Red note 
- Hi-Hat → Yellow cymbal
- 1st Tom → Yellow note
- 2nd Tom → Blue note
- 3rd Tom → Green note
- Crash → Green cymbal
- Ride → Blue cymbal

### Troubleshooting
- For best results, use standard MIDI files with proper drum channel mapping (channel 10/9)

## Import to Clone Hero Instructions
1. Locate the generated folder titled `artist - <song> (ACE)`
2. Copy/cut and paste into your Clone Her songs path
3. In Clone Hero, go to `Settings` → `General` → `Scan Songs` → `Yes`
      - This should create a `song.ini` file in the folder that was copied into the Clone Hero songs path
4. In the `song.ini` file is more metadata you can edit, but the important one to edit is the `diff_drums` which categorizes the song based on drumming difficulty
5. Repeat the process in step `3` to see the drum difficulty change
6. You are now ready to play your newly imported song!
