ChiptuneSAK

ChiptuneSAK (Swiss Army Knife) is a generalized pipeline for processing music note data and targeting various constrained playback environments.

ChiptuneSAK can import music from many formats and converts it to a common representation called chirp (CHiptunesak Intermediate RePresentation). Chirp can be processed and transformed in many ways, and then exported to various playback formats and environments.

ChiptuneSAK documention is on readthedocs.io

Background

In the past, we've written a number of one-off note data processing tools for previous projects (e.g. the ten-Commodore Orchestrion, an Unknown Realm Bard midi->ml64 importer, etc.). And with more similar projects on the way, it became apparent that there were opportunities to introduce generality and reusability into our processing pipelines. Therefore, our separate efforts have been redirected into this library. Its workflow is inspired by the LLVM compiler framework, which accepts many programming languages, "raises" them to a common intermediate format that can be manipulated, then "lowers" the code to many target platforms.

Team

David Knapp: core developer
David Youd: core developer
Ian Lee: python practices consultant
We are particularly grateful to:
- Hasse Axəlsson-Svala: For offering up much-needed GoatTracker and GoatTracker stereo sample data
- Markus Brenner: For providing an Apple II Mockingboard Ultima music import example in our framework

Project Status

The code is currently in an alpha state. Fundamental data representations have mostly stabilized. We are currently working on a variety of concrete importers and exporters from which to continue to generalize the processing pipeline. These importers and exporters include:

Music importers

Standard MIDI file (type 0 or 1): Contains note on/off events in delta time format
Commodore 64 SID files: C64 code that plays music (minus the playloop), wrapped with metadata and well-defined entry points. ChiptuneSAK supports PSID and some RSID. The importer is proposed as open-source alternative to SID2MIDI.
GoatTracker 2: A Commodore 64 pattern-based music editor for Windows/linux/MacOS
GoatTracker 2 Stereo (2SID)

Importers: under development

Importers: proposed

Subset of MusicXML: A digital sheet music interchange format
MOD (Amiga Module) files
NSF (Nintendo Sound Format). We already have a pure-python 6502 emulator working for the C64 SID importer that can be reused.
SAP (Slight Atari Player). Atari 8-bit music file, again 6502-based.
Many opportunities with VGM (Video Game Music) -- a sample-accurate sound logging format for many machines and many sound chips
COMPUTE!'s Sidplayer format

ChIRp processing / transformations

Quantizing of note onset and duration
Tick scaling, truncation, voice projection and reordering
Arbitrary metric modulation with support for music with varying meters
Transposition
Separation of polyphony into separate voices ("explode")
Music compression for trackers: identification and exploitation of patterns, including reuse with transpositions and differing tempos

ChIRp processing: under development

Additional tracker compression schemes

ChIRp processing: proposed

Music exporters

MIDI (type 1 files)
LilyPond: Sheet music markup language
Commodore 128 BASIC music program
GoatTracker 2 and GoatTracker 2 Stereo (2SID), both with optional pattern-based compression
ML64: Human-readable music format for Unknown Realm music contributions from those supporting at the "bard tier"

Exporters: Under development

SID-Wizard 1.8 (targeting dual and triple SID, as SID-Wizard only supports midi->single SID)

Exporters: Proposed

Minecraft Note Blocks
Mario Paint Composer
Markus's yet-unnamed Dr. Cat-derived 3-SID C64 player
ABC Notation: Human-readable music format. Used to allow user-submitted music in online games including Starbound, Lord of the Rings Online, and Shroud of the Avatar
jellybiscuits Music Box Composer file format
A Rob Hubbard engine
Other tracker file formats, such as JCH's SID Factory II

Requirements/Building

Python 3.8+
Lilypond
- Must be in your path (e.g., "C:\Program Files (x86)\LilyPond\usr\bin")
MidiEditor - optional, useful for visualizing what is happening to the midi files

Bootstrap: Ubuntu 20.04

# Install system dependencies
sudo apt install lilypond python3-venv build-essential

# Convenience Make target for setting things up
make venv
source venv/bin/activate

## Or if you prefer setting things up manually, you might do something like:

# Make and activate a Python virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python development dependencies
pip3 install -r requirements.txt

# Install ChiptuneSAK in editable mode
pip3 install --editable .

# Run the unittests to make sure things are working as expected
python3 -m unittest discover -p "*Test.py"

Bootstrap: Windows 10

The following instructions make the following assumptions:

You installed Python 3.8 from the Windows Store
You are installing using Windows PowerShell or the Command Prompt

# If PowerShell, run as Admin:

# Set Powershell Execution Policy to all running local scripts:
Set-ExecutionPolicy RemoteSigned
# Answer "[A] Yes to All" when prompted

# Compare your Python version to what was used writing this README
python --version  # Python 3.8.3

# Create a Python virtual environment (EXPLICITLY use `python` instead of `python3`)
python -m venv venv
.\venv\Scripts\Activate

# Install requirements in to virtualenv
pip install -r .\requirements.txt

# Install ChiptuneSAK in editable mode
pip install --editable .

# Run the unittests to make sure things are working as expected
tests\testall.bat

Generating Documentation

from docs folder:

make html

Running Tests

from the root folder, download the test data:

python3 res/downloadTestResources.py

from test folder:

python3 -m unittest discover -p "*Test.py" -v

or for an individual test:

python3 -m unittest chirpTest.py

Run a simple example

from examples/ folder:

python3 lechuck.py

c64cryptoboy/ChiptuneSAK