Some mentions from the author about lyric hosting in germany
------------------------------------------------------------

People ask me if I could put their lyrics on my homepage. In germany
it's not "allowed" to offer lyrics in the internet (copyright of the labels).
It's not really illegal but it's some kind of "grey" zone in the law because
there has never been a real "lawsuit".
There is also a strict (and sometimes stupid) "label right". You may get a
letter from the lawyer of a label, which tells you not to use their lyrics.
Just this letter can cost you about 10.000 DM (4000 $).
Also my homepage is on the server of my university. There are some german
lyric pages, which have made contracts with some labels, but this would be to
much work for me in my spare freetime ;-(


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. Quick install instructions
3. Configuration
4. Lyrics editor
  1. Timestamp mode
  2. Text mode
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
9. License
10. Credits and others


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

This "X Multi Media System" (XMMS) plugin displays formated lyrics.
If you don't know XMMS visit the homepage (see 10. Credits).

At the beginning it was mainly inspired by a WinAmp lyric plugin called
"Kuo's Lyrics Visualization Plugin" by Kuo Shiang-Shiang.

The plugin has some remote functions, so you don't need
to switch to XMMS for basic manipulations.

Parts of the plugin use functions of "libID3" (see 10. Credits).
It still works without the lib but you don't get the id3v2xx-Dialog.

Just install...

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 (at least for one more year (2000-12-06)):

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

<!--  http://stud.vas.fh-darmstadt.de/glogowski //-->


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

See NEWS (if you have a version 0.1.x it is out of date)
In development Version also see ChangeLog


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

1.) ./configure
2.) make
3.) strip xmms-singit/.libs/libxmms_singit.so (removes debugging code)
4.) 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

If you want to view console debug output: ./configure --enable-debug
To pipe the 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.

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

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


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

If you want to update a translation use msgmerge (see "info msgmerge").
Expl: msgmerge de.po xmms-singit.pot > de.new

If your language doesn't exist make a copy for your preferred language.
Expl.: cp po/xmms-singit.pot po/xmms-singit.fr (for french)


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)
Write to the
  Free Software Foundation, Inc.
  59 Temple Place - Suite 330
  Boston, MA 02111-1307, USA.


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

XMMS   -    http://www.xmms.org

Library to modify id3 informations (just v.3.7.x - v3.8.x doesnt't work)
libID3 -    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
       -    http://gltt.sourceforge.net

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

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

GtkGLArea (v1.2.3)
       -    http://www.student.oulu.fi/~jlof/gtkglarea

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


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

Last modified: 2002-02-21