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/