chiptunesak 0.3.0

Generalized pipeline for processing music and targeting various constrained playback environments

ChiptuneSAK

ChiptuneSAK (swiss army knife) is a generalized pipeline for processing music and targeting various constrained playback environments.

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

Background

Many one-off music processing tools were created for the Youd/Knapp/Van Haren ten-Commodore Orchestrion, as well as for processing the music format for user-contributed content to Unknown Realm (Note: we know nothing about the status of the game, so please don't ask). Recently, Youd/Brenner began work on a (not-yet-released) Commodore 64 Ultima-game music demo, requiring similar processing pipelines.

It became apparent that there were low-hanging opportunities to introduce generality into our workflow. Therefore, these separate efforts have been redirected into this standalone tool / 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:

  • Markus Brenner: For providing Apple II Mockingboard Ultima music importing/exporting
  • Hasse Axəlsson-Svala: For offering up much-needed GoatTracker and GoatTracker stereo sample data

Project Status

The code is currently in a pre-alpha state. Features are being debated and fundamental data representations are in flux. Currently working on a variety of concrete importers and exporters from which to generalize the processing pipeline. Details:

Music importers

• Standard MIDI file (type 0 or 1): Contains note on/off events in delta time
• GoatTracker 2: A Commodore 64 pattern-based music editor for Windows/linux/MacOS
• GoatTracker 2 Stereo (2SID)

Importers: under development

• Commodore 64 SID files: Arbitrary C64 code that plays music (minus the playloop), wrapped with metadata and well-defined entry points. Will support PSID and some RSID. Importer is proposed as alternative to the closed-source SID2MIDI.

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.
• 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
• Transpose score
• Separate ("explode") polyphony into separate voices
• Music compression for trackers: compute patterns, including reused based on transposition and differing tempos

ChIRp processing: under development

• Additional tracker compression schemes

ChIRp processing: proposed

• tbd

Music exporters

• MIDI
• LilyPond: Sheet music markup language
• Commodore 128 BASIC music program
• GoatTracker 2 and GoatTracker 2 Stereo (2SID), both automatically compute patterns for smaller files
• 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
• RobTracker v1.11 (publicly released Dec 25th. 2019)

Recent milestones

• Exported some Monkey Island (MS-DOS 1990) midi capture into 2SID GoatTracker. Patterns automatically computed to reduce file size.
• Created 6502 emulator for upcoming SID importer
• Exported some Betrayal at Krondor (MS-DOS, 1993) midi capture to pdf sheet music, goat tracker, and Commodore 128 BASIC program

Requirements/Building

• Python 3.7+
  • pip install
    • matplotlib
    • mido
    • more-itertools
    • numpy
    • parameterized
    • sphinx
• Lilypond
• 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 doing your development in Windows PowerShell

# In a PowerShell Admin window:

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

# 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.ps1

# 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
python -m unittest discover -p "*Test.py"

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