Generalized pipeline for processing music and targeting various constrained playback environments
Project description
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
- pip install
- 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