HARP Documentation

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


I.	Installation and Setup

Installing harp:
	mkdir build && cd build
	cmake {options} ..
		To select a sound output (REQUIRED) use one of:
			cmake -DWITH_OSS=ON ..
			or
			cmake -DWITH_JACK=ON ..
			or
			cmake -DWITH_ALSA=ON ..
			or
			cmake -DWITH_PULSE=ON ..

		To build without certain plugins use -DWITH_pluginname=OFF:
			cmake -DWITH_MP3=OFF -DWITH_FLAC=OFF ..
		Currently available are mp3, aac, vorbis, flac and stream
	make
	sudo make install

(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
	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.


3a.	Edit Shell

Commands are accepted in the following pattern:
	selector(...) action[(...)] [action[(...)] [ ... ]]

	The name used for selector determines which class of items the
	actions are applied to. The selector's arguments (...) select
	items of that type and can be one or more numeric IDs, "names",
	or subselectors(...). Names may be enclosed by double quotes(")
	to match similar names, or single quotes(') to match exact
	names. Action changes those selected items in the database. If
	multiple actions are provided, they will be run one after the
	other as they were specified from left to right. If an action
	does not use arguments, no () are needed. Otherwise, the required
	number of arguments should be provided separated by commas.

Selection commands:
	song	Edit song(s).
	album	Edit album(s).
	artist	Edit artist(s).
	playlist	Edit playlist(s).
	tag	Edit tag(s).

Selection filters:
	Selection commands can be filtered by ID, name, or through
	subcommands.
	For example, to select only the song with ID 12 and songs that
	are in either an album named foo or by an artist named bar:
		song(12,album("foo"),artist("bar"))

Song actions:
	list	List the state of the selected songs.
	title	Change the title of the songs.
			  (1 string arg - new title)
	track	Change the track number of the songs.
			  (1 numeric arg - track number)
	location	Change the location of the songs.
				  (1 string arg - absolute path)
	albumArtist	Change the album and artist of the songs.
				  (2 args: name string or id - album, artist)
	delete	Delete the selected songs.
	activate	Toggle the activation status of the songs.

Album actions
	list	List the state of the selected albums.
	title	Change the title of the albums.
			  (1 string arg - new title)
	artist	Change the artist of the selected albms.
			  (1 arg as either name string or id - artist)
	date	Change the date of the selected albums.
			  (1 numeric arg - new date)

Artist actions
	list	List the state of the selected artists.
	name	Change the name of the artists.
			  (1 string arg - new name)

Playlist actions
	list	List the state of the selected playlists.
	contents	List the songs in the selected playlists.
	name	Change the name of the playlists.
			  (1 string arg - new name)
	delete	Delete the playlists.
	order	Change the order of a song in the playlist.
			  (2 numeric args - old order, new order)
	add	Add a song to the playlist.
			  (2 args - song name string or ID, numeric order)
	removeOrder	Remove a song from the playlists.
				  (1 numeric arg - order number to remove)
	removeSong	Remove a song from the playlists.
				  (1 numeric arg - name string or ID)

Tag actions
	list	List the state of the selected tags.
	contents	List the songs in the selected tags.
	name	Change the name of the tags.
			  (1 string arg - new name)
	delete	Delete the tags.
	add	Add a song to the tags.
			  (1 arg - song name string or ID)
	remove	Remove a song from the tags.
			  (1 numeric arg - name string or ID of song to remove)


3b.	Edit Portal (deprecated)

Song commands:
	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 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: 
	One of: ALSA, OSS, JACK, or PulseAudio
	JACK also requires libsamplerate
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/