annotate README @ 4625:8c36787807de

remove some old unused functions from plugin API

Audacious
A relatively powerful media player

Copyright (c) 2005-2008 Audacious Development Team (see AUTHORS)

Based on:
  BMP - Beep Media Player (c)2002-2005

Which was based on:
  XMMS - X Multimedia System (c)1997-2001

  A Cross platform Multimedia Player

  Peter Alm, Thomas Nilsson, Olle Hallnas, Håvard Kvålen


NOTE: This document is hardly maintained. Please check the Users' Guide
on the Audacious website.


TABLE OF CONTENTS
*****************

1. Disclaimer
2. Installation
   2.1. Basic Installation
   2.2. Borderless Installation
   2.3. Skin Installation
3. Documentation
   3.1. Controlling Audacious
        3.1.1. Key bindings
   3.2. Playlist editor
   3.3. Equalizer
   3.4. Menu
   3.5. Preferences
        3.5.1. Appearance
        3.5.2. Mouse
        3.5.3. Playlist
        3.5.4. Plugins
        3.5.5. Audio
   3.6. Plugins
   3.7. Playlist Manager
4. Obtaining Audacious
   4.1. Obtaining Skins
5. Bugs
6. Contact




1. Disclaimer
-------------

We are not liable for any damage caused by the use of this program.

Audacious is NOT a port of WinAmp (http://www.winamp.com). Audacious is
a fork of XMMS (http://xmms.org) and BMP which borrowed the WinAmp GUI.

However, Audacious is neither XMMS, or BMP, but takes a direction of
its own.


2. Installation
---------------

Audacious requires the following libraries and their development
packages installed:

  Glib 2.14.0
    http://www.gtk.org/download/

  GTK+ 2.10.0
    http://www.gtk.org/download/

  mcs >= 0.7
    http://www.atheme.org/projects/mcs.shtml

  libmowgli >= 0.4
    http://www.atheme.org/projects/mowgli.shtml

  GNU Make >= 3.80

If you compile Audacious from a fresh Mercurial checkout, you will also
need the following tools:

  autoconf >= 2.59

Note that these tools and libraries are bundled with major Linux
distributions. Use the packages provided with them where possible. If
those packages are not sufficiently new, you may need to search
third-party repositories for them.


2.1. Basic Installation
-----------------------

cd audacious-VERSION
./configure
make
make install

This will put the binary in /usr/local/bin and plugins in
/usr/local/lib/audacious/

If you want to use the automatic character detection system, then you
should use --enable-chardet.


2.2. Borderless Installation
----------------------------

As far as I know most WM's accepts GTK decoration hints so it will
not have borders.  But some WM's can't handle this so you have to
set in manually.

AfterStep 1.0 ~/.steprc
Style "XMMS_Player" NoTitle, NoHandles
Style "XMMS_Playlist" NoTitle, NoHandles
Style "XMMS_Equalizer" NoTitle, NoHandles

AfterStep 1.4 ~/GNUstep/Library/AfterStep/database
Style "XMMS_Player" NoTitle, NoHandles
Style "XMMS_Playlist" NoTitle, NoHandles
Style "XMMS_Equalizer" NoTitle, NoHandles

Fvwm's ~/.fvwm95rc
Style "XMMS_Player" NoTitle
Style "XMMS_Playlist" NoTitle
Style "XMMS_Equalizer" NoTitle

CTWM's ~/.ctwmrc
NoTitle and NoBorder sections:
NoTitle {
    "xmms"
}

NoBorder {
    "xmms"
}


2.3. Skin Installation
----------------------

Audacious will create a directory called ~/.local/share/audacious/Skins.
You can unarchive the skins the same way as you do for Winamp.

However, you don't need to as Audacious supports archived skins. Audacious
currently reads the following formats: zip, wsz, tar, tar.gz and
tar.bz2

Just copy the archive to one of the skin paths and Audacious will take
care of the rest.

In order to support zipped skins you will need to have unzip. Unzip
is bundled with most Linux distributions.

Audacious looks for skins in these directories (in listing order):

<prefix>/share/audacious/Skins
~/.local/share/audacious/Skins
~/.audacious/Skins

You can set the environment variable SKINSDIR to another location of
your choice:

For BASH: 
  export SKINSDIR=/path/to/Skins:/more/paths/to/other/locations/of/Skins

For C Shell:
  setenv SKINSDIR /path/to/Skins:/more/paths/to/other/locations/of/Skins

You should note that skins designed specifically for Audacious are not
compatible with Winamp. Likewise, we do not support Winamp "modern" skins as
there is a lot of Winamp-specifics that would have to be reverse-engineered
or emulated to properly support those skins.

3. Documentation
----------------

This file or http://audacious-media-player.org/


3.1. Controlling Audacious
--------------------------

When you start up Audacious, you will get a console very similar to that of
Winamp.

- On the top is the window title bar. To the right you will see 3 buttons,
   Left button will minimize Audacious.
   Middle button will make Audacious only display the title bar.
   Right button will end the Audacious session.

- The area in the upper left part displays the following:
   - Play state: Paused, Stopped, or Playing
   - Time elapsed in the current song or if you click on it, the reversed.
   - Spectrum analyzer of the sound being played. Right mouse click will
     bring up the Visualization menu. Left mouse button will change the
     analyzer to an oscilloscope and/or none.

- To the right of the Spectrum analyzer is the title of the file being
  played. This also contains the length of the song being played, as well
  as its position in the [unsorted] playlist. Right clicking in this window
  will bring up a new menu with some more options that are self explaining.

- In the left part of the Spectrum analyzer you'll have letters (at least
  if you use the default skin) O A I D V. This is known as the "clutterbar'.
  Left-clicking on these will open up menus or perform the listed actions.
  O : Options menu
  A : Always on top
  I : File info box
  D : Double size mode
  V : Visualization menu

- Underneath the track title are the following static informational data:
   - bit rate in KBps (usually 128 or 112)
   - Sample Rate in KHz (usually 44)
   - Stereo or Mono channel mixing

- Underneath the informational data are a few controls you can play with:
   - The first slider controls the volume
   - The second slider controls the balance between speakers
   - The button marked "EQ" loads up the graphic equalizer
   - The button marked "PL" loads up the playlist editor
   - The LARGE slide bar moves from left to right as the song plays. You
     can drag this to jump to another location in the current file.

- On the bottom of the console are the standard buttons you would see on
  a CD player: Previous track, Play, Pause, Stop, Next track, eject,
  shuffle and repeat.

   - The eject button doesn't REALLY eject, of course. :) It opens up the
     file requester. The File Requester builds a playlist for the current
     Audacious session. You can use it to load files, add files to the list,
     or load all mp3s in a directory.

   - The shuffle button randomizes the sequence of the playlist.

   - The repeat button when enabled makes the playlist loop when it reaches
     end of the playlist.


3.1.1. Key bindings
-------------------

Global: (Main, Equalizer and Playlist window)

  z = Previous song
  x = Play
  c = Pause
  v = Stop
  b = Next song
  l = Play file (brings up the Load file(s) dialog)
  j = Jump to file (in the existing playlist)
  r = Toggle Repeat
  s = Toggle Shuffle

  Control + h = Play location (url)
  Control + p = Preferences dialog
  Control + r = Time remaining
  Control + o = Always on top
  Control + w = Winshade mode
  Control + j = Jump to time
  Control + z = Start of list
  Control + n = No Playlist Advance
  Control + 3 = File info dialog

  Control + Alt + w = Toggle Equalizer winshade mode
  Shift + Control + w = Toggle Playlist winshade mode

  Alt + e = Toggle playlist window
  Alt + g = Toggle equalizer window

Main window:

  Arrow key up    = Volume up 2%
  Arrow key down  = Volume down 2%
  Arrow key right = Skip 5 seconds forward in song
  Arrow key left  = Skip 5 seconds back in song

Playlist window:

  Arrow key up    = up one step in playlist
  Arrow key down  = Down one step in playlist

  Delete         = Remove selected songs from playlist
  Page Up        = Move one page up
  Page Down      = Move one page down
  Home           = Go to the first song
  End            = Go to the last song
  Enter          = Play selected song
  Insert         = Add file dialog
  Shift + Insert = Add directory dialog
  Alt + Insert   = Add url dialog

Equalizer shade mode:

  Arrow key up    = Volume up 2%
  Arrow key down  = Volume down 2%
  Arrow key right = Balance 4% to right
  Arrow key left  = Balance 4% to left


3.2. Playlist editor
--------------------

To access the Playlist editor, select the button labeled "PL" on the right
side of the Audacious console.

This will bring up the actual playlist window, here you'll find 5 buttons.
All of these buttons can be held down to bring up an extra menu.
From left to right:

file +    : will add a file to current playlist, held down mode you'll have
            2 extra options
dir       : will let you pick a directory (recursive)
url       : will let you add an url for streaming

file -    : will delete the highlighted file, held down mode you'll have 3
            more options
crop      : delete all files except the highlighted in the list
all       : delete all files in the list
misc      : *** NOT FUNCTIONAL ***

sel all   : select all files in current playlist, held down mode you'll have
            2 extra options
sel zero  : select none
inv sel   : invert you selection

misc opts : held down you'll have 2 extra options
fileinfo  : opens the file info dialog.
sort      : release button on this will bring up another menu with sort
            options

load list : will let you pick a playlist to load, held down you'll have
            2 extra options
save      : will let you save your playlist
new       : will empty the playlist and let you create a new playlist

If you want to select/deselect files in the filrequester/playlist editor use
CTRL for files and SHIFT key for blocks of files. You can also browse the PL
using the cursor keys and enter to select song. Pressing the delete button
will remove the song from the playlist. If your mouse is equipped with a
mouse wheel, you can use this to scroll up and down.


3.3. Equalizer
--------------

To access the Equalizer, select the button labeled "EQ" on the right side
of the Audacious console.

That will bring up the Equalizer window. It looks like an equalizer on a
stereo and behaves like one as well. Press the button labeled ON to enable
the use of the equalizer, once you turned it on you use it as a normal
equalizer.

EQ presets will be saved in ~/.audacious/config when you close Audacious. You
can also have your own presets for different song using the "Preset" button,
Audacious can also import/export from Winamp's preset files.

If 'Auto' is enabled, Audacious will try to load equalizer presets like this:

1: Look for a preset file in the directory of the file we are about to play.
2: Look for a directory preset file in the same directory.
3: Look for a preset saved with the "auto-load" feature.
4: Finally, try to load the "default" preset.

The 'preset' button will open up a menu with the following options:

Load
   Preset               : Will open a window with all available presets.
   Auto-load preset     : Will open a window with all available auto-load
                          presets.
   Default              : Will load the default preset.
   Zero                 : Will reset the equalizer to zero.
   From file            : Will load from a .preset file
   From Winamp EQF file : Will load from a Winamp equalizer file. If you
                          choose a library file only the first entry will
                          be loaded.
Import
   Winamp presets       : Imports the presets contained in an Winamp equalizer
                          library file (often named Winamp.q1) and add all
                          the entries to the Preset window.
Save
   Preset               : Let you name the current preset and save it.
   Auto-load preset     : Saves the current settings as a preset for the song
                          currently playing.
   Default              : Saves the default value for the equalizer.
   From file            : Saves the current settings in a preset file.
   From Winamp EQF file : Exports the current settings to a file readable by
                          Winamp.
Delete
   Preset               : Let you delete a preset from the list.
   Auto-load preset     : Let you delete a auto-load preset from the list.

Configure Equalizer     : Change the default names of directory based
                          preset files.

3.4. Menu
---------

There are several menu hot spots on the Audacious window. One place is at the
left hand side of the visual window described in sections 3.1 If you click
the right mouse button in the main window, the menus will also pop up (same
as clicking the button on the top left corner).


3.5. Preferences
----------------

Use the menu to open Options / Preferences or press CTRL-P to bring the
preferences dialog up.


3.5.1. Appearance
-----------------

Skins
In the skinlist you can choose a skin. How to install skins is described
above. Click on a skin in the list to change to it.

Fonts
You can set the font in the main window by setting the 'Player' font. You
can change the playlist font by setting the 'Playlist' font.

Miscellaneous
Show track numbers in playlist - Enable/disable displaying of track numbers
                                 in the playlist.
Use custom cursors             - Enable/disable custom cursors set by the
                                 skin.


3.5.2. Mouse
------------

Mouse wheel
Change how Audacious handles scroll behaviours.


3.5.3. Playlist
---------------

Filename
Convert underscores to blanks - Converts '_' (underscores) to ' ' in the
                                playlist.
Convert %20 to blanks         - Converts '%20' to ' ' in the
                                playlist.

Metadata
Load metadata from playlists and files - Loads metadata from files and
                                         playlists (e.g. ID3 tags).

Playback
Don't advance in playlist - Don't advance to the next song in the playlist
                            when the current song ends.
Pause between songs       - Set the time (in secons) to pause on songchange

Song display
Title format  - Choose the format to display the song names in the playlist.
Custom string - When the above option is set to 'Custom' insert a string of
                substitutes here.

3.5.4. Plugins
--------------

Enable/disable and configure plugins in this section.

Choose a tab to list one of the types of plugins:
  - Decoders (filetype/device support)
  - General (general plugins)
  - Visualization (visualization plugins)
  - Effects (effect plugins)

3.5.5. Audio
------------

The settings in this section are related to the audio system.


3.6. Plugins
------------

Plugins are what makes Audacious work, by moving most of the code out of
Audacious and into a plugin architecture it's possible to change almost
everything in Audacious. There are today 8 different types of plugins.

However to promote maximum flexibility of the platform itself, we no longer
include any plugins with the Audacious core.

You will need to download and install our plugin pack for Audacious if you
expect it to do anything useful (or install someone else's plugin pack if
one should exist).

Additionally, you can find a list of plugins at:
  http://audacious-media-player.org/Plugins

You should note that third-party plugins are not supported by the Audacious
development team, and that you should report any issues with them on our
forums, but NEVER on our bugtracker.


3.7. Playlist Manager
---------------------

Audacious supports multiple playlists (think foobar2000). For the manipulation
of playlists, we have included a playlist manager tool.

It is accessible from the Playlist menu.


4. Obtaining Audacious
----------------------

Currently, we only provide source tarballs at:

   http://audacious-media-player.org/Downloads

Audacious source is managed and also available via Atheme.org
Mercurial repository, refer to following web-page for information:

   http://audacious-media-player.org/index.php?title=Mercurial_Information

You may also want to read file "Mercurial-Access".


4.1. Obtaining Skins
--------------------

You can find Audacious/XMMS skins made by Audacious/XMMS users at:

   http://www.xmms.org/skins.html
   http://themes.org/skins/xmms

You can find more places on our website, at:

   http://audacious-media-player.org/Skins


5. Bugs
-------

Audacious is under heavy development and as such, has quite a number of
bugs. Our bug tracker page is maintained at:

  http://bugzilla.atheme.org/

It will continue to have bugs as we fix and introduce new ones through
rewriting and enhancement. Help us along by reporting new bugs, and
verifying existing ones.


6. Contact
----------

Primarily any end-user type questions should be directed to the
Audacious web forums:

  http://boards.nenolod.net/

There is also an IRC channel at irc.atheme.org #audacious. You should note
that this IRC presence is mainly for development issues and internal project
use, but that doesn't seem to stop 50-someodd people from visiting there.

Project admins:

  William Pitcock       email: nenolod at sacredspiral.co.uk
  Tony Vroon            email: chainsaw at gentoo.org