punchline

CLI tool to generate SVG punch cards (stripes with melodies) for a DIY music box from MIDI melodies.

Some basics:

• SVG is a vector format of images, meaning that you can scale the image as much as you want and print it on any printer, pen plotter, or laser cutter.
• MIDI is a sound format that instead of exact sounds describes which musical instruments should play which note at which moment. You can find a free MIDI file for any popular melody online.
• DIY music box is a type of music box which instead of playing a predefined melody can play any melody from a paper stripe with holes in it. You can buy one online for a pretty low price.

Features:

1. Written on modern Python.
2. Has friendly CLI.
3. Well documented source code (if you really want to tweak something).
4. Highly configurable.
5. Has only necessary dependencies.
6. Automatically finds the best transposition.
7. Finds the best fit for notes that aren't present on the music box.
8. Supports all kinds of music boxes.
9. Works offline.

Output example

Seven Nation Army for 15 notes music box:

Installation

You'll need:

1. Python version 3.9 or later
2. pip
3. Knowledge of how to use terminal.

python3.9 -m pip install punchline

Usage

Get help:

python3.9 -m punchline --help

Generate punch cards from 3rd track in SevenNationArmy.mid for 35-notes music box that supports sharp notes and save the result into "7nation" directory:

python3.9 -m punchline --input SevenNationArmy.mid --tracks 3 --sharps --notes-count 35 --output 7nation

The only required argument is --input. By default, it will generate stripes from all tracks for 15-notes non-sharp music box and store the result in the "output" directory.

Editing tips

1. You can use Inkscape to edit generated SVG images. It's free and powerful.
2. To mass-edit a specific type of element:
   1. Select an element of this type
   2. Right-click on it.
   3. Open "Select same" menu.
   4. Select "Fill and stroke"
3. Red circles indicate sounds that aren't perfectly fit on the music box. They are either in a different octave comparing to most of the other sounds or they are semitones (sharp notes) when your music box doesn't support semitones. Punchline tries its best to place them where it will sound OK but you may want to edit them or remove altogether.
4. Pay attention to the sounds that have the same note and go close to each other. The second one might be silent because of limitations of the music box. You may want to decrease the --speed for the whole melody or manually move (or remove) colliding sounds.

Acknowledgments

1. The initial implementation is based on punchbox.
2. mido is used to read MIDI files.
3. svg.py is used to generate SVG files.