Last modified: 2003-08-28
Jan-Marek Glogowski <glogow@stud.fbi.fh-darmstadt.de>


Dates and times
----------------

All dates and times should be ISO 8601 (YYYY-MM-DD hh:mm:ss.sTZD)

 YYYY = four-digit year
 MM   = two-digit month (01=January, etc.)
 DD   = two-digit day of month (01 through 31)
 hh   = two digits of hour (00 through 23) (am/pm NOT allowed)
 mm   = two digits of minute (00 through 59)
 ss   = two digits of second (00 through 59)
 s    = one or more digits representing a decimal fraction of a second
 TZD  = time zone designator (Z or +hh:mm or -hh:mm)

http://www.w3.org/TR/NOTE-datetime



============================
XMMS SingIt Lyrics Displayer
============================

1. Introduction
  1. Features
  2. Mailing List(s)

2. Quick install instructions

3. Configuration

4. Lyrics editor
  1. Timestamp mode
  2. Text mode
  3. Synced mode
  4. Lyrics query
  5. Options

5. Lyrics structure

6. Key bindings
  1. Displayer key bindings
  2. Quick key access to songs in the playlist
  3. Editor key bindings

7. Development

8. Translations
  1. New
  2. Update
  3. Testing

9. License

10. Credits and others


1. Introduction
----------------

Singit is a karaoke / lyrics plugin for the "X Multi Media System" (XMMS).

It consists of an editor component, which helps to create and
synchronize the lyric files, an id3 tagger and a displayer plugin
interface. The main distribution contains OpenGL, SDL (G-Force) and
gtk+ based plugins.


Hints, bugfixes, ideas, comments, constructive criticism, code,
translations ... (everything you can add to this list) welcome

Write to:

  Jan-Marek Glogowski <glogow@stud.fbi.fh-darmstadt.de>

Homepage:

  http://xmms-singit.sourceforge.net (redirect)

  or

  http://stud.fbi.fh-darmstadt.de/~glogow


1.1. Features
--------------

  * Plugin interface to support multiple displayer
  * Integrated lyric editor
  * Gtk+ karaoke widget
  * Windowed, fullscreen, OpenGL and SDL displayer(s)
  * Many configuration options
  * Tag editor
  * Multi threaded


1.2. Mailing List(s)
---------------------

There is a mailing list available at sourceforge for SingIt users.

  http://lists.sourceforge.net/lists/listinfo/xmms-singit-users

This list is open for anything related to SingIt.


2. Quick install instructions
------------------------------

1.) ./configure
2.) make
3.) su -c "make install" and <root password>
    or become root and "make install"

Hint:
- - -

If there doesn't exist the "./configure" script run

	make -f admin/Makefile.create

To pipe the debug output into a file:     make > cout.log
If you want to include error mesages:     make >& cout.log


3. Configuration
-----------------

The lyric filename is constructed from:

	Lyric dir + song filename without the (last) extension + lyric extension

Defaults:
	Lyric dir        :   "~/lyrics/,~~/lyrics/"
	Lyric extension  :   "txt,tag"
	Lyric font       :   "-adobe-helvetica-bold-r-*-*-14-*"

Example:
	Song file        :   "/data/mp3/PUR_-_Lena.mp3"
	Home             :   "/home/jmg"

	Result           :   1. "/home/jmg/lyrics/PUR_-_Lena.txt"
			     2. "/data/mp3/lyrics/PUR_-_Lena.txt"

Special start name sequences
	~   = Home directory (u*ix like)
	~~  = Song directory


4. Lyrics editor
----------------

First look at the tooltips of the button ;-)

The editor consits of three modes, represented by the three tabs.
See the folloeing sections for further information.

The toolbar contains the following buttons:

  * New file -> clear lyrics
  * Open file -> open a lyrics file
  * Catch lyrics from current song
  * Reload lyrics from source

  * Guess a filename from current song

  * Save file
  * Save file with other filename (save as)
  * Export as html-file

  * Strip HTML
    Removes HTML-Tags (everything between <>) from the file
    (If you get lyrics from the internet as HTML files)
  * Strip timetags
    (if you want to print the lyrics...)
  * Nice Text
    (left alignment / strip whitespace / upper first letter)

  * Auto time
    Changes all marked timestambs the way, that the first
    and the second timestamp are equal (same refrain - just copy a further
    one - tag the next refrains position - mark the tag and the refrain -
    hit the button - voila)
  * Change the timestamps of the selected test
    To add or subtract time
    Can speed up syncronization a lot, because you just have to copy
    a block and add correct the overall time
    (Result: see bottom right corner)
  * Test if the timestamps are chronological correct
    SingIt will mess up your text on save if its not correct

  * Show "id3v2xx" window (just available when compiled with libid3)
  * Show preferences window
  * Show keybindings (about window)

  * Close editor


4.1. Timestamp mode
-------------------

Left-Click          : The program prepends the current time to the line
                      Moves the next line to the middle of the box if possible
Shift + Left-Click  : As Left-Click
                      Doesn't alter the line pos

Ctrl + Left-Click   : The program removes the first item (if existing)
                      Doesn't alter the line pos


4.2. Text mode
--------------

In this mode you can edit the text. This removes the annoying "misfeature"
of Kyo's WinAmp plugin. It wasn't very handy to edit the textfile.
(You had to select the line and edit it - also it was a little bit tricky to
insert or remove a line - best way was to use an extra editor)


4.3. Synced mode
----------------

This mode is a little bit tricky.
Click in the lower window to add the word to the upper window

Left-Click          : Insert stamp and jump to next word
Right-Click         : Jump to next word

CTRL + Left-Click   : Insert stamp and jump to the end or start of the (next) line
CTRL + Right-Click  : Jump to the end or start of the (next) line


4.4. Lyrics query
-----------------

The plugin uses the lyrix plugin servers to allow the user to search for lyrics.
It cashes the lyrics from the current search.
Latest servers do not support the album query but that might change.
Later versions will also support to submit new lyrics to the database.
Someone volunteers to write a local DB backend?


4.5. Options
-------------

 * Ext. timetags
   Use extended timetags ([xx:xx_:xxx_])
 * Show tooltips
   Show tooltips in the toolbar
 * Multi open
   Keep file selector open after selection
 * Automatically check sync before save
 -----------------------------------------
 * Strip HTML
   * <BR> + '\n'
     Include a break at <BR>-Tag and keep the normal one
   * \n
     Just keep the breaks and ignore <BR>
   * <BR>
     Include a break at <BR>-Tag and ignore linebreaks
 * Convert
   On save as exchange the white spaces or underscores in the
   selected file name

   * disabled
     Don't convert
   * To spaces
     Replace underscores with spaces
   * To underscores
     Replace spaces with underscores
 -----------------------------------------
 * More options...
   Display the dialogs page of the preferences dialog
 * Save options
   ...


5. Lyrics structure
--------------------

[Timestamp] Lyrictext

Example:

[00:00]Lalila
[00:17][00:08]Lilola - this line two times ;-)
[00:20]
[00:25:930]Extended Lyric tag - more precise
[00:28:930]Extended Lyric tag - [00:32:330]even more precise[00:34:567]

See the example.tag in the doc/ directory


6. Key bindings
----------------

6.1. Displayer key bindings
----------------------------

You can also see the key bindings at the about window
! These keys just work when the displayer has the focus !

[zy]		Previous song
 x		Play
 c		Pause
 v		Stop
 b		Next song

CTRL + p	Show the configuration window
CTRL + e	Show the lyrics editor
CTRL + a	Show the about window (incl. key bindings)
CTRL + i	Show the id3 tag window
CTRL + [0-9]    Start displayer plugin
ESC             Stop displayer plugin (importent for fullscreen :-)
CTRL + c        Show displayer spezific configuration

[Key pad]
 +	        Volume up
 -	        Volume down


6.2. Quick key access to songs in the playlist
-----------------------------------------------

Enable NumLock on your keyboard.
Type the number of the playlist entry and hit "enter".
The "decimal" (,.) clears the internal buffer.
No numbers > playlist length are accepted.

Example:

Playlist entries  : 320
  Input           : 123456789
  "Output"        : 123 45 67 89
  Current Buffer  : 89


6.3. Editor key bindings
-------------------------

CTRL + l        Load current song lyrics
CTRL + n        Start new lyrics
CTRL + o        Open lyric file
CTRL + s        Save Lyrics
CTRL + t        Toggle editor mode


7. Development
---------------

Ok - you want to develop something for the plugin, or want to contribute
a "missing" feature. First read the TODO of the latest development release.
If the feature doesn't appear in the list, please send me a small mail
explaining the feature. I will add it to the TODO list, so that nobody
else will start the same. That's it...

A good point to start is the "FILES" file.
It explains most files and the the "workflow" of the plugin.


8. Translations
----------------

More detailed information is available in the gettext info manual or in the
online manual at:
  http://www.gnu.org/manual/gettext-<gettext version>


8.1. New
---------

If your language (<lang>.po) doesn't exist create a new one.
The easiest way is to go to the "po" directory and invoke msginit
(as far as I know you need a internet connection):

  # cd xmms-singit-<version>/po
  # msginit --verbose

An other possibility is to copy the language template (expl: for Italian):

  # cd xmms-singit-<version>/po
  # cp xmms-singit.pot it.po

This requires to manually fill the initially comment and the header, which
can be a little bit tricky.

To have a translation start you may use the .po file from xmms and merge it

  # msgmerge -C <path to xmms source>/po/it.po it.po xmms-singit.pot > it.new

At least you should go throught the translation and correct the "fuzzy"
(guessed) entries. When the translation is correct remove the "#, fuzzy" line,
or remove the ", fuzzy" if it contains additional data.

Finally add your language to "LINGUAS.in" (it) and rename the new translation

  # mv it.new it.po


8.2. Update
------------

If you want to update a translation use msgmerge (see "info msgmerge").

  # cd xmms-singit-<version>/po

  # msgmerge de.po xmms-singit.pot > de.new

You may also use other translated po files as a reference, i.e. the xmms
translations when invoking msgmerge. But running it on pretranslated files may
cause a lot of fuzzy messges because fuzzy hits are preferred to catalog
entries:

  # msgmerge -C <path to xmms source>/po/de.po de.po xmms-singit.pot > de.new

After translating at least the fuzzy entries

  # mv de.new de.po


8.3. Testing
-------------

A quick test of a translation can be performed by opening a terminal (console),
typing:

  # LANG=<my_lang>

  # xmms

where <mylang> is composed like "de_DE". Most times upper and lower case
letters don't differ. Most common differences are "en_GB" or "en_US".


9. License
-----------

See COPYING.
If this file doesn't exist (should not be possible, but who knows)
get a copy of the "GNU Public License v2" (GPL) from the net or
write to the
  Free Software Foundation, Inc.
  59 Temple Place - Suite 330
  Boston, MA 02111-1307, USA.


10. Credits
------------

The plugin uses the lyrix servers to find lyrics. Thanks to all the people
maintaining and updating the servers.
       -    http://lyrix.best.cd

XMMS (X Multi Media System)
       -    http://www.xmms.org

libID3 (Library to modify id3 informations)
       -    http://www.id3lib.sourceforge.net

Kuo's Lyrics Visualization Plugin (WinAmp) - first inspiration
       -    http://come.to/djohan

SingIT for Windows (not mine) - I took its name ;-)
       -    http://www.glop.org/singit/

GLTT (Open GL True Type Font renderer)
       -    http://gltt.sourceforge.net

SDL (Simple Direct Media Layer)
       -     http://www.libsdl.org

The plugin uses parts of the following projects.
Normally the files are integrated in libraries or other plugins, but the sources
are small or essential for the plugin, so I
decided to integrate them into the plugin directly - makes compilation easier.

GtkGLMaterialDialog
       -    http://www.pvv.org/~lilles/gtkglmatdlg

GtkGLArea
       -    http://www.student.oulu.fi/~jlof/gtkglarea

test (XMMS OpenGL plugin)
       -    http://umiushi.no-ip.com/~wac/linux.html

SDL_prim
       -    http://www.libsdl.org

GForce (Visualization Plugin)
       -    http://www.xmms.org