HARP Files

HARP Documentation

Contents:
	I.Installation and Setup
	II.Manager Interface
		1)Insert
		2)Edit
		3)List
		4)Admin
	III.Customization
		1)Configuration File
	IV.Requirements


I.	Installation and Setup

Installing harp:
	./configure
		To build without certain plugins use --without-pluginname:
			./configure --without-flac --without-vorbis
		Currently available are mp3, aac, vorbis, flac and stream

		To use a different sound output (OSS is the default), use:
			./configure --with-jack
			or
			./configure --with-alsa

		MacPorts users may wish to use:
			./configure --with-jack CFLAGS="-I/opt/local/include" LDFLAGS="-L/opt/local/lib -L/opt/local/lib/jack"
	make
	make install

		see also: osx_install.sh

Enable the plugins in harp:
	harp -a
		select plugin management:
	Admin> p
		add a plugin:
	Plugins> a
	Library (e.g., libharpmp3): libharpmp3
	Plugins> a
	Library (e.g., libharpmp3): libharpaac
		...

Check that the plugins have been installed:
		list added plugins:
	manage plugins> l

(optional) Create a configuration file:
Note: your paths may be different.
	cp /usr/local/share/harp/defaults.conf ~/.harp/defaults.conf




II.	Manager Interface

1.  Insert
Song
	Insert a song into the system. If the insert flag is given with no 
	argument, songs may be entered at the prompt. Inserts may be given with
	an argument of the song path to add a song from the command line. If a
	directory is given as an argument, HARP will scan the directory
	recursively and add all valid files into the system.

2.  List
	List detailed song information or list the songs related to an album,
	artist, or playlist. If given no argument, all members of that category
	are listed.


3.  Edit
Global commands:
	q	Quit
	p	Previous menu
	?	Print help

Edit commands:
		NOTE: These commands take an argument of the IDs(or names) separated by commas.
	s	Edit song(s).
	sa	Edit songs in specified album.
	sr	Edit songs in specified artist.
	sg	Edit songs in specified genre.
	a	Edit album(s).
	r	Edit artist(s).
	p	Edit playlist(s).
	g	Edit genre(s).

Song commands:
		NOTE: Commands that require additional input can take it as an argument
						(e.g., t NewTitle)
	L	List the songs that will be affected.
	t	Change the title of the song.
	l	Change the location of the song.
	r	Change the song's artist.
	a	Change the song's album.
	d	Remove the song from the database.
			The original file will remain intact.
	v	Toggle Activation: Toggle the active status of the song. Provide an
			argument of 0 to deactivate or 1 to activate the selected songs.
			Default behaviour is to flip the status of each song.
			Deactivated songs are similar to deleted songs except that
			they keep their play statistics and may be played only if
			reactivated or if directly chosen to be played with the
			--type=s flag.
	g	Change which genres the song belongs to.
		
			Song-Genre commands:
				L	List the genres the song belongs to.
				a	Add the song to a genre.
				r	Remove the song from a genre.

Album commands:
		NOTE: Commands that require additional input can take it as an argument
						(e.g., t NewTitle)
	L	List the albums that will be affected.
	t	Change the album's title.
	r	Change the album's artist.

Artist commands:
		NOTE: Commands that require additional input can take it as an argument
						(e.g., n NewName)
	L	List the artists that will be affected.
	n	Change the artist's name.

Playlist commands:
		NOTE: Commands that require additional input can take it as an argument
						(n NewName) or (o 10 4)
	L	List playlists that will be affected
	LC	List contents of the playlists that will be affected
	c	Create a new playlist.
	n	Change the name of the playlist.
	d	Delete the playlist. Songs will remain in the database.
	a	Add a song to the playlist.
	r	Remove a song from the playlist.
			(Takes an argument of Order. Not SongID)
	o	Change the order of a song in the playlist.
			(Takes two arguments: current order and new order)

Genre commands:
		NOTE: Commands that require additional input can take it as an argument
						(e.g., n NewName)
	L	List genres that will be affected
	LC	List contents of the genres that will be affected
	a	Add a genre.
	n	Change the name of the genre.
	o	Change the genre's owner (parent).
	d	Delete the genre. If a song is left without any genres, it will be
		added to the 'Unknown' genre at the end of the session.


4.  Admin

Manage Plugins (p)
	a Add
		Add a plugin to the system. Plugin must already be installed.
	l List
		List all plugins in the system
	r Remove
		Remove a plugin from the system.
	t Toggle activation
		Toggle the activation status of a plugin. Deactivated plugins will
		only be used if all activated plugins of the correct type are
		unavailable.
		PluginID can either be given as:
			manage plugins> t x
				or
			manage plugins> t
			PluginID: x
		where x is the PluginID

Manage Stats (s)
	r Reset stats
		a Reset all
		r Reset ratings
		d Reset play count
		s Reset skip count
		l Reset last play time
	e Export stats
		Stats will be output to a file in tab separated columns sorted by
		file location.


III.	Customization

1.	Configuration File:
	This located at ~/.harp/defaults.conf

General format for this file:
	-Comments start with #
	-Section names are enclosed in []
	-Options are in the format: option=setting



IV.  Requirements

Sound output: 
	ALSA, OSS, JACK
Database: 
	SQLite3
Default Decoders: 
	MP3: libmpg123
		- http://www.mpg123.de/
	AAC: libfaad2
		- http://www.audiocoding.com/downloads.html
	OGG: libvorbisfile
		- http://www.xiph.org/downloads/
	FLAC: libFLAC
		- http://www.xiph.org/downloads/