punchline 1.4.0

Description:

punchline 1.4.0

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:

Written on modern Python.
Has friendly CLI.
Well documented source code (if you really want to tweak something).
Highly configurable.
Has only necessary dependencies.
Automatically finds the best transposition.
Finds the best fit for notes that aren't present on the music box.
Supports all kinds of music boxes.
Works offline.
Detects notes that might be silent.
Laser cutter friendly output.

Installation
You'll need:

Python version 3.9 or later
pip
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 20-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 20 --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.
You can find a few more examples in presets.md.
Editing tips

You can use Inkscape to edit generated SVG images. It's free and powerful.
To mass-edit a specific type of element:

Select an element of this type
Right-click on it.
Open "Select same" menu.
Select "Fill and stroke"


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.
Pay attention to the outlined circles (filled with white instead of a color). They indicate sounds that are too close to the previous one on the same line. They 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. The minimal distance between circles (their centers) is configured by --min-distance.

Acknowledgments

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