ly2video

ly2video is a Python script which converts music represented by a GNU LilyPond file into a video containing a horizontally scrolling music staff which is synchronized with a MIDI-generated audio rendering of the music.

It is also possible to synchronize the video of the scrolling music notation with a previously recorded audio track of the same music, such as a live performance, even when the audio uses tempo rubato or is not precisely metronomic.

Examples

Here are some examples of videos generated by ly2video.

Caveat emptor

Beware, here be dragons!

Unfortunately I don't currently have the time to work on ly2video much. These means that bitrot has set in, for example see issue #75.

Having said that, I'll do my best to support anyone who is trying to get it working - please see below for how to get support.

Requirements

Please also read the Installation section below before you start installing anything!

• GNU LilyPond >= 2.15.41 (needs one-line-breaking support)
• FFmpeg (if you are on Ubuntu or Debian, see first see issue 32)
• TiMidity++
• Python >= 3.5
• Python's pip installer
• swig and ALSA development libraries (python-midi requires these in order to build its sequencer code successfully, although ly2video doesn't use that code)

Installation

Installing dependencies on openSUSE 12.2

Install the ffmpeg package from Packman via 1-click install (you can also find the button on this page), or via YaST and/or zypper.

You can ensure the remaining dependencies are installed via something like:

sudo zypper install lilypond timidity python3-pip python-imaging alsa-devel

Installing dependencies on Debian- and Ubuntu-based Linux distributions

There is currently a known issue on these distributions, since Debian and Ubuntu switched from ffmpeg to the libav fork. See issue #32 for a suggested workaround.

Additionally, Debian and Ubuntu both currently ship very old versions of LilyPond, so you might need to install a newer one via the "Generic Packages" section near the top of: http://lilypond.org/unix.html

You can ensure the remaining dependencies are installed via something like:

sudo apt-get install timidity python3-pip python3-pil swig libasound-dev

Installing dependencies on Arch-based Linux distributions

Download and install the AUR package ly2video-git. See the the Arch wiki for further instructions.

Installing dependencies on other platforms

If you have figured out how to install the dependencies and get ly2video working on another platform, please file a new issue containing the information, so that this README can be updated. Thanks!

Installing required Python module dependencies

ly2video requires some specific Python modules - do NOT install these manually! (unless you are a Python expert.) They can be installed system-wide via:

sudo pip install -r requirements.txt

or for the current user via:

pip install --user -r requirements.txt

You can optionally protect against the risk of installation of these Python modules destabilising any other Python applications you may use, by isolating them in a virtual environment using virtualenv. The most convenient way to do this is via virtualenvwrapper. Once you have virtualenvwrapper installed, it's as simple as:

mkvirtualenv ly2video
pip install -r requirements.txt

Installing ly2video itself

This is done via Python's standard package installation mechanism.

For example, to install system-wide, just run

sudo pip install .

or for the current user via:

pip install --user .

If something fails, please double-check you correctly met the requirements and dependencies detailed above.

Usage

Run ly2video --help to display usage information.

You must ensure that your .ly input file contains both \layout { } and \midi commands, which ensure that valid .midi and .png files are generated when it is run through lilypond --png.

Usage with docker container

Set up your path to argument LILY_FILES in makefile.

Build docker container with workable ly2video inside

make build

Run docker container with access to direcory you point at LILY_FILES

make run

Use ly2video usually. All actions applied in container to your files (LILY_FILES) will change your files (LILY_FILES) outside container.

Support, bugs, development etc.

Firstly, please check the issue tracker for known issues, and if yours is not there, please submit it.

Secondly, if you are able to perform some [[trouble-shooting|TROUBLE-SHOOTING]] yourself, even if you can't identify the exact problem or suggest a fix, any extra light you can shed will greatly increase the chances of it being fixed. Please see the [[trouble-shooting|TROUBLE-SHOOTING]] guide for information on how to do this.

If you know how to fix a problem or contribute an enhancement, you are extremely welcome to fork this repository, commit your fix, and then send a pull request!

Acknowledgements

Huge credits for the initial implementation go to Jiří "FireTight" Szabó, who wrote it as part of his Bachelor's degree. If you are lucky enough to understand Czech, you can read his thesis on ly2video in the doc/thesis/ subdirectory, or online :-) Work on an English translation has begun and is being tracked in issue 15 but is unlikely to be finished any time soon unless someone else volunteers to help out.

Very big thanks also to Jan Nieuwenhuizen not only for co-inventing LilyPond in the first place, but also for helping me implement the complete revamp of the synchronization algorithm, which should be much more robust than the previous one.

And finally of course, much gratitude to the many great people who have contributed to LilyPond over the years. This would not have been possible without you.

License

ly2video is released under the GNU GPL v3.