Johan Vromans
and 1 contributors

NAME

irealcvt - parse and convert iRealPro data

SYNOPSIS

irealcvt [options] file [...]

 Options:

    --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

DESCRIPTION

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:

PDF

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

PNG

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.

JSON

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

TEXT

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.

HTML

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).

OPTIONS

--output=XXX

Specifies the desired output file name.

The file name extension controls the output type.

--select=NN

Selects a single song from a playlist.

--list

Prints the titles of the songs from a playlist.

Output defaults to standard output.

--split

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

Note: --output is ignored.

--dir=XXX

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

--npp=variant

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.

--[no]toc

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.

--[no-]suppress-upbeat

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

This is enabled by default.

--[no-]override-alt

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

This is enabled by default.

--[no-]condense

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

This is enabled by default.

--[no-]suppress-text

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

--[no-]musescore

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

--help

Prints a brief help message and exits.

--man

Prints the manual page and exits.

--ident

Prints program identification.

--verbose

Provides more verbose information.

file

The input file(s) to process.

NPP IMAGING

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.

AUTHOR

Johan Vromans, <jv at cpan.org>

BUGS

Please report any bugs or feature requests to bug-data-irealpro at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-iRealPro. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

    perldoc irealcvt

ACKNOWLEDGEMENTS

Massimo Biolcati of Technimo LLC, for writing iRealPro.

The iRealPro community, for contributing many, many songs.

COPYRIGHT & LICENSE

Copyright 2013,2016 Johan Vromans, all rights reserved.

Clone me at GitHub