Author image Johan Vromans
and 1 contributors


irealcvt - parse and convert iRealPro data


irealcvt [options] file [...]


    --output=XXX        Desired output file name.
                        File name extension controls the output type.
    --select=NN         Select a single song from a playlist.
    --list              Prints the titles of the songs from a playlist.
    --transpose=[+-]NN  -x  Transpose up/down semitones.

  iRealPro (HTML) output options:

    --split             Splits the songs from a playlist into individual
                        HTML files. Use --dir to control where the
                        files will be written.
    --dir=XXX           Specifies the result directory for --split.

  Imager (PDF/PNG) output options:

    --npp=[hand|hand_strict|standard]   Near pixel-perfect output.
    --[no]toc           Produces [suppresses] the table of contents.

  MusicXML input options:

    --[no-]suppress-upbeat  Suppress an initial upbeat (default).
    --[no-]suppress-text    Suppress all texts.
    --[no-]override-alt     Change series of alt modifications to a single
                            'alt' quality (default).
    --[no-]condense         Condense chords that may not have enough
                            space to be shown (default).
    --[no-]musescore        Deals with some peculiarities of MuseScore
                            generated XML. If not set, it will be
                            automatically detected.

  Miscellaneous options:

    --help  -h          this message
    --man               full documentation
    --ident             show identification
    --verbose           verbose information


This program will read the given input file(s) and parse them. The input files are assumed to contain valid iRealPro data as exported by the iRealPro app on Android and iOS.

If Multiple input files are given, their contents will be combined into a single playlist, named after the first playlist or, if the first file contains a single song, the title of this song.

Finally, the resultant playlist is converted. Several conversions are possible:


Produces a single PDF document containing a nicely formatted version of the songs.


Produces one or more PNG files, one for each song. The contents of the PNG is visually identical to the PDF.

Optionally, a 'near pixel perfect' PNG may be produced that is near pixel perfect identical to the images generated by the iRealPro app. See the --npp option for details.

See also "NPP IMAGING".

If multiple output pages are to be generated you can add a sprintf() compliant %d sequence in the output file name. For example, with --output=img%04d.png output files will be img0001.png, img0002.png, and so on.


This is basically a low-level representation of the contents of the songs.


This is a textual, editable representation of the contents of the songs. It may be edited and used as input to this program for further processing.


A single HTML document very similar to the documents exported by the iRealPro app itself.

Optionally, a playlist can be split (see --split) into a series of HTML documents each containing one song. The documents are named after the song title and can be stored in a separate directory (see --dir).



Specifies the desired output file name.

The file name extension controls the output type.


Selects a single song from a playlist.


Prints the titles of the songs from a playlist.

Output defaults to standard output.


Splits the songs from a playlist into individual HTML files. Use --dir to control where the files will be written.

Note: --output is ignored.


With --split, specifies the directory where the individual HTML files will be written.


With PNG output, produces near pixel-perfect iRealPro output.

variant must be 'hand' (for the hand-written style) or 'standard'. iRealPro uses some non-hand symbols although hand-written versions are available. To obtain this exact behaviour, set the variant to 'hand_strict'.

Add a minus at the end of the variant to select to get minor chords with an 'm' instead of the default '-'.

See also "NPP IMAGING".

--transpose=[+-]NN -x

Transposes up/down semitones.

Currently implemented for PDF and PNG output only.


With PDF output, produces or suppresses the table of contents.

By default, A ToC is automatically generated if a playlist contains more than one song.


With MusicXML input, suppresses an initial upbeat. iRealPro doesn't deal with upbeats anyway.

This is enabled by default.


With MusicXML input, replaces series of alt modifications (e.g. 7b5#5b9#9) with alt.

This is enabled by default.


With MusicXML input, uses condensed chords when there may not be sufficient space to show a chord without overlapping.

This is enabled by default.


With MusicXML input, ignore the directives written on top of or below the staffs. Often these texts lead to unreadable results.


With MusicXML input, deals with a number of peculiarities in the XML as generated by MuseScore. This implies b<--supress-text>.


Prints a brief help message and exits.


Prints the manual page and exits.


Prints program identification.


Provides more verbose information.


The input file(s) to process.


To enable pixel perfect images some proprietary files from the iRealPro app are required. For copyright reasons, these files cannot be included with this program.

The necessary files can be found in the iRealPro APK, folder res/drawable-nodpi-v4. Just copy these files to the res/drawable-nodpi-v4 folder of irealcvt and NPP imaging should be functional.


Johan Vromans, <jv at>


Please report any bugs or feature requests to bug-data-irealpro at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this program with the perldoc command.

    perldoc irealcvt


Massimo Biolcati of Technimo LLC, for writing iRealPro.

The iRealPro community, for contributing many, many songs.


Copyright 2013,2016 Johan Vromans, all rights reserved.

Clone me at GitHub