annotate src/flacng/README @ 2498:194c2f8c2a92

Include cleanups, part #3.

/*
 *  A FLAC decoder plugin for the Audacious Media Player
 *  Copyright (C) 2005 Ralf Ertzinger
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

INTRODUCTION
============

This is an input plugin for the Audacious Media Player enabling the playback
of FLAC compressed audio files.

The Audacious Media Player (http://www.audacious-media-player.org) is a port of
the XMMS audio player to GTK2.

FLAC (http://flac.sourceforge.net/) is an Open Source lossless audio
codec developed by Josh Coalson.



STATUS
======

This plugin is to be considered of alpha quality. Use at your own risk.


OK, let's be brief with this and first list the things that do _not_ work
at the current time.

- No display of bitrate
- Visualizer plugins do not work with FLAC streams (*)
- No OGGFlac streams (*)
- Maximum of 2 channels (Stereo) (*)
- No configuration options at all (*)

Still interested? Good.
The items marked with a (*) above can be fixed, this just takes some code
that has not been written yet (har har).
The FLAC decoder does not emit the current bitrate, so you'll have to
settle for "VBR", which is true enough.
As for configuration options, so far I have not found anything worth
configuring, maybe you can think of something.

Nonetheless.

Given all the restrictions above, when presented with a 8/16/24 bit, stereo
not-packed-in-ogg FLAC stream, this plugin will do it's best to produce
some sound out of it. This may even work. It may, on the other hand, crash
your machine and eat your data.

Did I mention that the code is alpha quality?



HOW TO BUILD
============

You will need the following to compile the code:

1) A working compiler environment (if you do not know what this means
   you probably do not want to use this code now, anyway)

2) The Audacious media player, including development header files

3) The FLAC libraries, including development header files

If you have all this the rest is easy.
Unpack the tar ball, change into the directory created and
issue "configure" (without the quotes). This will try and find the
necessary stuff on your system. When it finishes successfully, type
"make". This will build the plugin library.
To enable debugging messages (and you probably want those at this
point) use "configure --debug"

To install the plugin in your home directory (no special permissions
needed, ideal for testing) use "make localinstall" (you can use
"make localremove" to remove the plugin again). To install the plugin
for all users use "make install" instead.



TESTING
=======

After successful installation start Audacious (preferrably from the command
line so you can see error or debug messages) and look in the configuration
panel under plugins. The FLAC plugin ought to appear there, looking
like "FLAC audio plugin". Now add a FLAC file to
the playlist and try it.



BUGS
====

Sure. Tons of 'em. Report to <[e-mail]> for the time being.