The FatHead Project
Copyright 2004, Autumn Umanetz 
<brain at thundersun.ca>

////////////////////////////////////////////////////////////////////////////////
// Whatinole is all this?
////////////////////////////////////////////////////////////////////////////////

FatHead is an album-based full-screen remote controller for XMMS.  It is 
	intended to turn a laptop into a stereo component which you can 
	comfortably use from across the room with an IR remote control.  
		
Because the laptop may not actually be your music server, it is broken 
	into a small and fast GUI client, and a server portion which runs on the 
	same computer as xmms.  This may or may not be the same machine.  

This is alpha software.  It does not change your music repository in any 
	way, so it is very low risk.  However, it is severely limited.  Your music 
	database must be entirely contained within one directory, and formatted as 
	one album per subdirectory, which must be named in the format Artist-Album.

////////////////////////////////////////////////////////////////////////////////
// Building
////////////////////////////////////////////////////////////////////////////////
	
Geez, I dunno.  This really shouldn't be rocket science.  You'll need
	a few development libraries and the QT3 dev tools to compile.  Specfically,
	at least on debian, you'll need the following packages:
	
	qt3-dev-tools libxmms-dev libqt3-dev liblircclient-dev 

Steps to compile:
	1. Server
	cd brain
	ln -s ../common/* .
	qmake brain.pro
	make
	
	2. Client
	cd face
	ln -s ../common/* .
	qmake face.pro
	make

////////////////////////////////////////////////////////////////////////////////
// Setup and Configuration
////////////////////////////////////////////////////////////////////////////////

Unfortunately, because this is still alpha software, you need to build 
	your config files by hand.  There are decent examples of all of the config 
	files (with the '.' prefix removed) in ./examples/ 
		
Any commandline option (like --debug 5) can be placed in a config file, in 
	the format "debug = 5".  Alternately, it can be specified in the 
	environment, in the format BRAIN_DEBUG=5, or for face, as FACE_DEBUG=5.  

--------------------------------------------------------------------------------
-- Configuration: Brain
--------------------------------------------------------------------------------

Your first step is to get the server up and running.  This isn't too hard.  

1. ~/.brain

	- The only thing you really need to specify here is "music = ".  Point it 
	to the directory which contains all of your albums, one per sub-directory.  
	- N.B., the output of brain --dump is suitable for pasting into .brain 

2. ~/.braincats

	- This file describes the legal genres and music categories.  The format 
	is described at the top of examples/braincats 
	- This file isn't mandatory, but if you don't have it, you won't be able 
	to filter by genre and category.  No big deal, really.  
	
3. ~/.braincds

	- This file contains a coded description of each album.  A description of 
	the format is at the top of examples/braincds 
	- Again, not mandatory unless you want to filter by 	
	
--------------------------------------------------------------------------------
-- Configuration: Face
--------------------------------------------------------------------------------
	
Next, you'll probably want the client portion, "face," to run.  This is 
	substantially simpler than getting the server going.  Again, it's just a 
	couple of config files.
  
1. ~/.face
	
	- If the server is running on a different host, specify it with brainhost
	- If you want fullscreen mode, specify fs

2. .face.lircconf

	- if you want to use your remote control, you'll need to have lirc up and
		running.  This is not necessarily a trivial exercise, but it's beyond
		the scope of my pitiful little readme.
	- You'll need to set up mappings between your remote control buttons (as
		named in your /etc/lirc/lircd.conf), and face's commandname, which 
		aren't presently documented anywhere except examples/.face.lircconf

////////////////////////////////////////////////////////////////////////////////
// FAQ
////////////////////////////////////////////////////////////////////////////////

	Nobody has yet asked me a single question about setting up and using this
	application.  I suspect this is a testament to its unpopularity rather than
	its ease-of-use.  However, I have invented a couple to document things that
	don't seem to fit elsewhere in the documentation.

Q. I use xscreensaver, but it doesn't wake up when I use the remote control.
A. It doesn't pay attention to the serial ports, probably for some good reason.
	You can rebuild it using examples/xscreensaver_timers.c, and it will watch
	for interrupts on lirc_serial.