###################################################################
##                          GQmpeg 0.9.0         (March 19, 2001)##
##     This software is Copyright (C) 2001 by John Ellis.        ##
##  Use this software at your own risk. I am not responsible for ##
##        anything this software may do to your computer.        ##
## This software falls under the GNU Public License. Please read ##
##              the COPYING file for more information.           ##
###################################################################

==========

well if you don't know it by now, then you didn't read the README,
so shame on you.

==========

Author: John Ellis
e-mail: gqview@email.com
homepage: http://gqmpeg.sourceforge.net

======== Major sections of this document

  - Requirements
  - Notes and changes for this release
  - Installation
  - Description / Features
  - Command Line options
  - Skins
  - Documentation (brief) [lists keyboard controls]
  - Skin editing notes
  - Credits

======== Requirements

  GTK+-1.2.x: ftp://ftp.gtk.org/pub/gtk (1.0.x will not work!)
  gdk-pixbuf >= 0.7.0
  mpg123 >= 0.59o http://ftp.tu-clausthal.de/pub/unix/audio/mpg123/
  (mpg123 >= 0.59p required for streaming (http://, shoutcast, etc))

  optional components:
  (support disabled if not found)

    - xmp for mod (.mod, and others) files.
      http://xmp.helllabs.org

    - ogg123 for Ogg Vorbis (.ogg) files. (ogg123 is in vorbis-tools package)
      http://www.xiph.org/ogg/vorbis/     (only tested with Ogg123 0.1)

======== Notes and changes for this release

  Changes:

    > Added preset list widget to the skin spec.
    - All widgets in the skin spec should now be documented in SKIN-SPECS file.
    - Single clicking on a playlist in a skin now selects the song, double
      clicking will play the song if stopped.
    - Minor Japanese translation update.
    * Fixed the window manager classes so everything is unique, the main window
      is now GQmpeg:gqmpeg and the playlist is GQmpeg:playlist.

   SLIK (0.6.0) related changes:

     > New font widget, for use by text in the same method digits are used by
       numbers to conserve memory.
     > For text, the data field is now used as the default text when the
       application does not register a matching text key. Useful when labels
       are needed in a skin.
     - Skin sizes are now remembered for sizeable skins.
     - Improved list widget button press handling (to work more like a button).
     * Fixed the parser so that spaces are accepted in keys and data fields.
     * Digits (and fonts) can now only be removed in the editor when no widgets
       reference them.
     * Fixed background updates for hidden widgets (fixes transparent items
       linked to sliders and dials).
     * Fixed calculations for list widget row borders.
     * Fixed broken widget placement when setting background in the editor.
     * When opening the editor, the skindata entry field used for load and save
       is now set correctly to match the active skin.

  Notes:
    - xmp {mod} support is buggy, seeking is at best an estimate/ unreliable.
    - Streams are loaded by right clicking and choosing Open->Custom, and
      added to the playlist by pressing the 'add custom' button in the
      playlist window. To change a stream in the playlist, right click it and
      choose 'edit'.
    - Multiple file selection is done by [ctrl] - clicking and
      [shift] - clicking, also [ctrl] - [space] turns on a mode in the clist
      so that pressing space on an item toggles it's selection. (these are
      standard keys and operations for gtk, nothing special).
    - Drag and drop is available in the playlist window to add files /
      directories and to move items in the playlist. Files can also be dropped
      on the main window.

  Bugs:


======== Installation

  Compilation: ./configure ; make
     - I18N note: Set the shell variable LINGUAS with a list of required
                  translations before configure (supported: cs de fr ja pt_BR).
     - Use the --enable-japanese option to enable japanese ID3 tag support.
     - To build an RPM binary use 'rpm -tb gqmpeg-x.x.x.tar.gz'.

  Installation: make install

  Removal: make uninstall

======== Description / Features

  GQmpeg is a frontend to mpg123 with extensive themeability and playlist
  support.

  Features:
    - Extensive mpg123 option support.
    - Shuffle, repeat.
    - Shuffle and repeat preferences can be saved in each playlist.
    - Customizable skins, including winamp skin support.
    - A skin can contain an alternative face (shade mode for instance)
    - ID3 tag reading/writing support (v1)
    - Volume controls (can be connected to any available device)
    - Basic file management (move/copy/rename/delete)
    - Tab completion in most dialogs.
    - Presets for playlists.
    - Drag and drop support.
    - Shoutcast (http://server:port) support.

======== Command Line options:

   Note: 'gqmpeg --help' to list all options, this list is probably outdated.

    --skin:skindir   tells GQmpeg to use the skin in the directory named
                     skindir, GQmpeg searches for skinfile in the current dir,
                     HOME/.gqmpeg/skins/, and /PREFIX/share/gqmpeg/skins directories.
    --dock           enable docking behavior
    --dockwm         enable Window Maker docking
    --skinhelp       shows the mouse coordinates as you move the mouse to help
                     position items when designing skins
    --debug          enable debug mode (spews lots of weird junk :)
    --blank          start with empty playlist

   The following commands send a command to another running gqmpeg and exit.
   (requires 'allow command parsing' to be enabled)

     option:                               ipc_function:
     -p          --play                     play
     -s          --stop                     stop
     -ps         --pause                    pause
     -n          --next                     next
     -b          --back                     prev
     -pladd      --playlist_add <f>[..]     pladd "<f>"
     -pladdplay  --playlist_add_play <f>    pladd_play "<f>"
     -plrm       --playlist_remove <f>[..]  plrm "<f>"
     -plclr      --playlist_clear           plclr
     -pl         --playlist <f>             plload "<f>"
     -plappend   --playlist_append <f>[..]  plappend "<f>"
     -f          --file <f>[..]             play_file "<f>"
                 --skin_set <f>             set skin
                 --status                   print status (track, song, time)
                 --volume [+|-]n            set or increment volume by n%
     -q          --quit                     quit

     Note: also echoing the ipc_function above to ~/.gqmpeg/command will work
     example: `echo next > ~/.gqmpeg/command` will tell gqmpeg to skip to
              the next song.

======== Skins

  Also see (Skin editing notes), below.

  To specify a skin use the -skin:skinfile command line parameter (see above).
  When specifying a default skin in the config dialog, the skin must reside
  in HOME/.gqmpeg/skins 
  If valid, a new default skin is loaded when 'ok' or 'apply' is pressed.

  A skin is a directory which contains a file named skindata and xpm files for
  the skin. Creating a skin is explained in the SKIN-SPECS file, you can
  download sample skins to use as a template from the GQmpeg web site:

     http://gqview.netpedia.net

  Winamp skin support:
    All files must be lowercase.
    Support is an added bonus. Most skins will work, however a few will not.
    Please  do not request support to get a particular skin to work.

======== Documentation (brief)

  Shoutcast support:
    (unsupported, very buggy) (not available in binary packages)
    Shoutcast support _requires_ mpg123 0.59pre-p ..
              ... mpg123 0.59o WILL NOT WORK!
    The shoutcast directory of the source code includes a script and
    instructions to use GQmpeg as a netscape plugin for shoutcast(.com)
    pls files.

  Keyboard controls:
       p, [SPACE]     play/pause
       s              stop
       n              next
       b              back
       l              playlist
       m              run mixer
       w              switch skin mode
       i              song information
       -              volume down
       +, =           volume up
       [CTRL] -       balance left
       [CTRL] +, =    balance right
       1 .. 0         presets 1 through 10, respectively

       [CTRL] s       shuffle
       [CTRL] r       repeat
       [CTRL] 1       repeat 1
       a              loop a-b (set start, set end, off)
       Escape         cancel loop a-b
       [CTRL] t       time display
       [CTRL] o       options/preferences
       [CTRL] i       iconify
       [CTRL] a       about
       [CTRL] q       quit

       ~, `           open skin editor window

  IPC (external control and status):
    control:
      Send commands to gqmpeg through "$HOME/.gqmpeg/command", send text 'help'
       and a brief list of available commands will be printed.
      Note: "$HOME/.gqmpeg/command.pid" will contain the current PID of the
            gqmpeg process (if any) that is listening for commands.

    status:
      Send this command to have gqmpeg start printing it's status to a file:

         status_add "key" "/path/to/file"

      and use this to stop it:

         status_rm ["key"|"/path/to/file"]

      You can stop it by using the key or path. When the updating is stopped,
      two things may be printed: 'close' is printed when status_rm is used;
      or 'exit' is printed just before gqmpeg shuts down (quits).

      Information printed is the current song path, title, track position,
      status (play, stop, pause), and seconds played/remaining.
      Status is only updated when items change, for instance when the song
      changes, the time count changes, or the play/pause/stop status changes.
      Note: If the length of path is 0, no song is loaded in the player. Use
            this to determine 'no song selected', because 'track: 0 of 0'
            may be a valid song if the current active song is not in the
            playlist, and the playlist is empty.

======== Skin editing notes

   Mouse control:
    - The mouse in the skin editor uses these buttons in the skin display area:
        - Button 1 : Same as in the normal main window (press buttons, etc.)
        - Button 2 : Click to select widget, drag to move selected a widget.
               (when click to focus is disabled, widgets are always draggable)
        - Button 3 : same as button 2

   Converting version 1 skins:
    - To convert a version 1 skin to a version 2 skin, load the skin into the
      skin editor (tilde '~' key) then save it, do this for all skindata_alt
      files too.

   Extracting widget from other skins:
    - To generate a list, and use widgets from any installed skin, press the
      'extract' button from the 'add' dialog of the skin editor.

   Editing / extracting widgets from the built-in or winamp skins:
    - To re-use widgets from the default skin or winamp skins, first load them
      into the skin editor and save them as a new skin (reason, widget
      extraction only works on offical (version 1 and version 2) skins. To make
      the new widgets show up in the widget lists, close the skin editor, then
      reopen it and press the extract button on the add dialog.

   Skin toggle buttons:
    - The "skin_toggle" button is a special case, the data field must contain
      the filename of the skin the button is to switch to. If the data field is
      left blank the default skin (skindata) will be loaded. If the filename
      does not exist or is an invalid skin file, the button will do nothing.

      (NOTE on naming of the skindata type files: the widget extraction
       feature only extracts widgets from skins defined by files matching the
       pattern "skindata*" but _not_ including '.bak'. All others are ignored.)

   Writing a skin to disk:
    - When saving a skin, existing files are never overwritten: the skindata
      file is backed up with an extension of .bak or .bakXXX; graphics files
      will first be compared by file length and checksum, if they match it
      will keep the existing file, otherwise the new graphics file will be
      written to a new filename with an appended number increment (name_1.png).

   Dial and Slider 'item link key':
    - Dials and sliders have a 'Item link key' field, this is for use when you
      want an item with that key to update with the dial or slider in such a
      way that the dial/slider handle is drawn over top of the item. This is
      useful for example when it is desired that a slider that controls the
      volume also shows the volume level. If you want the item to be the only
      thing displayed with slider-like interaction, the slider handle size can
      be set to zero by specifying a trough length equal to the image
      dimensions.

   Limits:
    - You can add as many widgets of the same function as you want and they
      will all work. (For example 100 play buttons :).

   Invalid UI keys:
    - If an invalid key is assigned to a widget, the widget will still load
      but be ignored when activated/operated.

   Detailed skin specs (VERSION 1 or VERSION 2)
    - See SKIN-SPECS or SKIN-SPECS-V2, respectively.


======== Thanks go to the following for fixes, additions, and patches:

  Translations:

     Eric Lassauge <lassauge@mail.dotcom.fr>
        for French translation.

     Tomas Prochazka <xprocha2@informatics.muni.cz>
        for Czech translation.

     Yuuki NINOMIYA <gm@smn.enjoy.ne.jp>
        for Japanese translation, japanese id3 tags.

     Matthias Warkus <mawarkus@t-online.de>
        for German translation.

     Hellbrasil <hellbrasil@ig.com.br>
	for Brazilian Portuguese translation

  Fixes, additions, and patches:

     Hubert Feyrer <hubert.feyrer@rz.uni-regensburg.de> and
     Rui-Xiang Guo <rxg@ms25.url.com.tw>
        for NetBSD patches.

     Kimball Thurston <kimball@sgrail.com>
        for sgi mixer support

     BALATON Zoltan <balaton@eik.bme.hu>
        for Window Maker dock support.

     Bruno Rohee <rohee@OpenBSD.ORG>
        for BSD cpu utilization code.

     Michael Bruun Petersen <mbp@image.dk>
        for playlist window enhancements.

     Lszl, Rbert - rob@sch.bme.hu
        for additional skin widgets: Numbers and fonts, other fixes.

     Yick W. Tse <ywtse@mailcity.com>
        for ID3 genre updates.

     Sampo Niskanen <sampo@compart.fi>
        for early help with playlists, misc.

     Tino Schwarze <tino.schwarze@informatik.tu-chemnitz.de>.
        for ipc crash fixes.

     [more] (I know, there are more, I don't have time right now to update this)

===========


