UltraStar Lyrics Rewriter
=========================
Version 0.1

README and USER MANUAL

i  SUMMARY
UltraStar Lyrics Rewriter (USLR) is a work-in-progress that aims to be a rapid
lyrics editor for UltraStar songs.

The original motive behind its creation was the need to convert Korean songs
with romanized lyrics to actual Korean script.

As this project fills a very small niche, features will be added only as I need
them, or as they are requested.

ii AUTHOR
USLR has been created by Sebastian Beschke.

I welcome all feedback. Please send it to s.beschke@gmx.de.

I also accept feature requests, but I can make no guarantees as to whether/when
I will be able to attend to them.

If you extend USLR and send me your patch, I will try to integrate it if it
is of acceptable quality and credit you here.

For bug reports, in addition to a detailed description of what went wrong,
please include the contents of the <Log> tab at the time when the problem
occured. If possible, also include the program's console output.

USLR's central home page is:
http://github.com/sbeschke/UltraStar-Lyrics-Rewriter

Enjoy!

iii LICENSE
To do.

1  INTRODUCTION
There are several song editors for UltraStar to be found on the internet.
However, most of them share the same fallacy as the original UltraStar software
in that they only support the ANSI encoding used by legacy Windows software.
This encoding is unable to represent any non-latin scripts, as is required
e.g. for Asian languages.

The famous UltraStar fork called UltraStar Deluxe has recently introduced
support for Unicode encoded files, using the UTF-8 encoding, enabling the
creation and playback of songs in all languages of the world. However, this has
made two problems obvious:

  * There is a lack of song editing tools that can handle UTF-8 encoded files,
    forcing anyone wishing to create such songs to edit the .txt file by hand
    using a plain text editor, which is very cumbersome.
  * Especially Asian song files have so far been - and will probably
    continue to be - distributed in romanized script. Depending on the players'
    language skills, it may be desirable to display the lyrics in the original
    script. Therefore, a tool facilitating the job of going through the lyrics
    of a song and replacing romanized text by the original script may turn out
    to be a big time saver.

USLR has been created as a response to both problems. It does not aim to be
a complete song editor; instead, its design focuses on streamlining the lyrics
editing process.

NOTE. USLR saves lyrics using the UTF-8 encoding. This encoding is required to
support non-latin scripts; however, it is currently (as of August 2010) only
supported by UltraStar Deluxe. This means that the files you create using USLR
will generally only play with UltraStar Deluxe, but not with UltraStar.

NOTE. Although USLR won't save files in the ANSI encoding used by UltraStar and
older versions of UltraStar Deluxe, it will happily load both UTF-8 and ANSI
encoded files.

2  HOW TO USE
This section briefly details the usage of USLR. It is assumed that you know the
basics of UltraStar song organization and the structure of an UltraStar song
.txt file. If you are not familiar with this, you should read the UltraStar
Deluxe user manual and/or other web resources.

2.1  Running USLR
Download the most current version of USLR at the home page mentioned at the
beginning of this file. This will be a file called something like USLR-x.x.jar,
depending on the version. Run it by opening a text console and navigating to
the directory where you saved USLR. Then type "java -jar USLR-x.x.jar",
substituting for the file's actual name.

2.2  Editing a song
Load a song by selecting the <Open Song...> command from the <File> menu.
(USLR is not able to create song files from scratch. You need, at the very
least, a song file containing the pitches and timings, as well as some dummy
lyrics.)

The first line of the song will be displayed in the *line display* in the top
half of the <Lyrics> tab. Also, the first syllable will appear highlighted in
the *edit box* directly underneath it. This edit box is where you can make
changes to the lyrics. Whatever is in the edit box will replace the syllable's
original text as soon as you navigate to another syllable.

You can move through the song by using CTRL in combination with the arrow keys:
CTRL+Arrow Left and CTRL+Arrow Right move to the previous/next syllable, while
CTRL+Arrow Up and CTRL+Arrow Down move to the first syllable of the
previous/next line. (The cursor needs to be in the edit box in order for this
to work.)

Whenever you move to a new syllable, its text will automatically be selected
in the edit box. This allows you to simply start typing and what you type will
replace the present text. Note that you need to add a space to seperate words
from each other. This can be placed either at the end of the first or the
beginning of the second word; both variants are displayed correctly by
UltraStar Deluxe.

NOTE. USLR currently lacks an Undo function. This is a possible feature for
future versions that would greatly enhance usability; for the time being, you
will just have to be careful editing your songs.

An alternative to typing in the whole lyrics, especially when you are converting
between romanization and script, is to find the song's lyrics on the internet
and paste them into the *paste box* at the bottom of the <Lyrics> pane. Then you
can use the shortcut CTRL+q to remove the first character from the paste box and
insert it into the edit box. If there are any extra characters in your pasted
lyrics, you can skip them using CTRL+w. (Again, these shortcuts only work if
the cursor is in the edit box.) This way, you can go through a song's lyrics
quite efficiently, getting the characters for a syllable from the paste box and
then moving on to the next syllable. If a character is missing in your pasted
lyrics, you can simply type it in.

Finally, when you are finished editing your song, save it using the <Save as...>
command from the <File> menu.

TIP. If you would like to keep both a romanized and a non-latin version of a
song, you can avoid duplicating files (which may take up a lot of space,
especially if your song uses a video) by placing both .txt files alongside each
other in the same directory.

NOTE. USLR does not currently support metadata editing. You will have to do
this by hand by opening the song .txt file using a text editor. Especially if
you follow the above tip and keep two versions of the same song, you will want
to edit their titles in order to be able to distinguish them.

NOTE. If your file is not being opened or there are other problems, you should
observe the contents of the <Log> tab. Any errors logged there may point you
to a problem there may be with your song file. If you cannot find any problem
with your file, you are welcome to contact me using the email address listed
at the beginning of this file. It may well be a bug.

2.3  Creating a song list
USLR contains a very rudimentary way to create a song list from an UltraStar
song collection. You can access it by selecting the <Create song list...>
command from the <Tools> menu. You may then pick your songs directory, which
normally is the "songs" subdirectory of you UltraStar Deluxe folder. You
also need to pick a directory where USLR will save the generated list file.

Once you have picked both directories, start the list generation process by
clicking the "Generate Song List" button. Depending on the size of your
collection, USLR will then stop responding until it has finished generating the
list. Once it starts responding again, you can find the list file in the
output directory you indicated.

WARNING. If there already is a list file in the output directory, it will be
overwritten.

This list is in HTML format and can be formatted using an external CSS file.
Open the HTML file using a text editor and you can easily see what style classes
you can use.

NOTE. Check the <Log> tab to find out about any problems there may be with the
songs in your collection. Songs that USLR cannot load because of problems
will not appear in the generated list.

3. FOR DEVELOPERS
You can get USLR's source code at the github address indicated above.
Unfortunately, the code is not well documented at the moment, but neither
is it very complex, so you should not have a very difficult time adding or
fixing things.

The NetBeans IDE 6.8 has been used to create the code, and using NetBeans to
work on the code will be the most convenient way, especially due to the
integrated GUI editor.

I'll be very happy to include your patches in future USLR versions.

4. POSSIBLE FUTURE DEVELOPMENTS
There is a number of features that would be very nice to have in USLR.
However, future development of USLR is always subject to how much free time
I have available, so it may take a long time until these features are
implemented. You're welcome to work on any of these; just notify me as soon
as you start working.

  - An Undo feature would be extremely useful for editing lyrics.
  - The list generation feature could be extended into something you can
    actually call a "feature", instead of the dirty hack it is now. Ideas:
    Select what columns to include; filter songs based on metadata via regex
    conditions (e.g. to create separate lists by language); allow two-column
    output (LaTeX? ODT?)
  - Add metadata editor tab.
  - The previous two could be combined into a more general song list manager
    feature similar to UltraStar Manager, but with UTF-8 support.

5. CONCLUSION
Thank you for reading this README file. Enjoy UltraStar Lyrics Rewriter.