Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aspiers/ly2video

generating videos from LilyPond projects
https://github.com/aspiers/ly2video

lilypond music music-notation python sheet-music video-generator

Last synced: about 21 hours ago
JSON representation

generating videos from LilyPond projects

Awesome Lists containing this project

README 

        
# ly2video



`ly2video` is a Python script which converts music represented by a [GNU

LilyPond](http://lilypond.org) 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](doc/how-to-audio-sync.md), such as a live performance, even

when the audio uses [*tempo rubato*](https://en.wikipedia.org/wiki/Tempo_rubato)

or is not precisely metronomic.



## Examples



Here are some [examples of videos generated by ly2video](http://www.youtube.com/playlist?list=PLfRwjd606WZlxRU_kaUPagX3-Uv-SYRMH).



## Caveat emptor



Beware, here be dragons!



Unfortunately I don't currently have the time to work on ly2video

much.  These means that in some places bitrot has set in.



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`](http://www.lilypond.org/doc/v2.17/Documentation/notation/one_002dline-page-breaking) support)

*   FFmpeg (if you are on Ubuntu or Debian, see first see

    [issue 32](https://github.com/aspiers/ly2video/issues/32))

*   TiMidity++

*   Python >= 3.5

*   Python's [pip installer](http://www.pip-installer.org)



## Installation



### Installing dependencies on openSUSE 12.2



Install the `ffmpeg` package from Packman via [1-click

install](http://packman.links2linux.org/install/ffmpeg) (you can also

find the button on [this

page](http://packman.links2linux.org/package/ffmpeg)), or via [YaST

and/or

zypper](http://wiki.links2linux.de/packman:faq_en#software_installation_updates_deinstallation).



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`](https://github.com/aspiers/ly2video/issues/32).  See [issue #32](https://github.com/aspiers/ly2video/issues/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



### Installing dependencies on Arch-based Linux distributions



Download and install [the AUR package `ly2video-git`](https://aur.archlinux.org/packages/ly2video-git/). See the [the Arch wiki](https://wiki.archlinux.org/title/Arch_User_Repository#Installing_and_upgrading_packages) 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](https://github.com/aspiers/ly2video/issues) containing the

information, so that this README can be updated.  Thanks!



### Installing required Python module dependencies



[ly2video requires some specific Python modules](https://github.com/aspiers/ly2video/blob/master/requirements.txt) - **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`](http://www.virtualenv.org/en/latest/).  The most

convenient way to do this is via

[`virtualenvwrapper`](http://virtualenvwrapper.readthedocs.org/en/latest/).

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](https://packaging.python.org/tutorials/installing-packages/).



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](https://github.com/aspiers/ly2video/issues)

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](https://github.com/aspiers/ly2video/fork),

commit your fix, and then send a [pull request](https://help.github.com/articles/using-pull-requests)!



## 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](http://is.muni.cz/th/359741/fi_b/text_prace.pdf) :-) Work on

an English translation has begun and is being tracked in

[issue 15](https://github.com/aspiers/ly2video/issues/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](http://www.gnu.org/licenses/gpl.html).