README
1HARP Documentation
2
3Contents:
4 I.Installation and Setup
5 II.Manager Interface
6 1)Insert
7 2)List
8 3)Edit
9 4)Admin
10 III.Customization
11 1)Configuration File
12 IV.Requirements
13
14
15I. Installation and Setup
16
17Installing harp:
18 mkdir build && cd build
19 cmake {options} ..
20 To select a sound output (REQUIRED) use one of:
21 cmake -DWITH_OSS=ON ..
22 or
23 cmake -DWITH_JACK=ON ..
24 or
25 cmake -DWITH_ALSA=ON ..
26 or
27 cmake -DWITH_PULSE=ON ..
28
29 To build without certain plugins use -DWITH_pluginname=OFF:
30 cmake -DWITH_MP3=OFF -DWITH_FLAC=OFF ..
31 Currently available are mp3, aac, vorbis, flac and stream
32 make
33 sudo make install
34
35(optional) Create a configuration file:
36Note: your paths may be different.
37 cp /usr/local/share/harp/defaults.conf ~/.harp/defaults.conf
38
39
40II. Manager Interface
41
421. Insert
43 Insert a song into the system. If the insert flag is given with no
44 argument, songs may be entered at the prompt. Inserts may be given
45 with an argument of the song path to add a song from the command
46 line. If a directory is given as an argument, HARP will scan
47 the directory recursively and add all valid files into the system.
48
492. List
50 List detailed song information or list the songs related to an
51 album, artist, or playlist. If given no argument, all members
52 of that category are listed.
53
54
553a. Edit Shell
56
57Commands are accepted in the following pattern:
58 selector(...) action[(...)] [action[(...)] [ ... ]]
59
60 The name used for selector determines which class of items the
61 actions are applied to. The selector's arguments (...) select
62 items of that type and can be one or more numeric IDs, "names",
63 or subselectors(...). Names may be enclosed by double quotes(")
64 to match similar names, or single quotes(') to match exact
65 names. Action changes those selected items in the database. If
66 multiple actions are provided, they will be run one after the
67 other as they were specified from left to right. If an action
68 does not use arguments, no () are needed. Otherwise, the required
69 number of arguments should be provided separated by commas.
70
71Selection commands:
72 song Edit song(s).
73 album Edit album(s).
74 artist Edit artist(s).
75 playlist Edit playlist(s).
76 tag Edit tag(s).
77
78Selection filters:
79 Selection commands can be filtered by ID, name, or through
80 subcommands.
81 For example, to select only the song with ID 12 and songs that
82 are in either an album named foo or by an artist named bar:
83 song(12,album("foo"),artist("bar"))
84
85Song actions:
86 list List the state of the selected songs.
87 title Change the title of the songs.
88 (1 string arg - new title)
89 track Change the track number of the songs.
90 (1 numeric arg - track number)
91 location Change the location of the songs.
92 (1 string arg - absolute path)
93 albumArtist Change the album and artist of the songs.
94 (2 args: name string or id - album, artist)
95 delete Delete the selected songs.
96 activate Toggle the activation status of the songs.
97
98Album actions
99 list List the state of the selected albums.
100 title Change the title of the albums.
101 (1 string arg - new title)
102 artist Change the artist of the selected albms.
103 (1 arg as either name string or id - artist)
104 date Change the date of the selected albums.
105 (1 numeric arg - new date)
106
107Artist actions
108 list List the state of the selected artists.
109 name Change the name of the artists.
110 (1 string arg - new name)
111
112Playlist actions
113 list List the state of the selected playlists.
114 contents List the songs in the selected playlists.
115 name Change the name of the playlists.
116 (1 string arg - new name)
117 delete Delete the playlists.
118 order Change the order of a song in the playlist.
119 (2 numeric args - old order, new order)
120 add Add a song to the playlist.
121 (2 args - song name string or ID, numeric order)
122 removeOrder Remove a song from the playlists.
123 (1 numeric arg - order number to remove)
124 removeSong Remove a song from the playlists.
125 (1 numeric arg - name string or ID)
126
127Tag actions
128 list List the state of the selected tags.
129 contents List the songs in the selected tags.
130 name Change the name of the tags.
131 (1 string arg - new name)
132 delete Delete the tags.
133 add Add a song to the tags.
134 (1 arg - song name string or ID)
135 remove Remove a song from the tags.
136 (1 numeric arg - name string or ID of song to remove)
137
138
1393b. Edit Portal (deprecated)
140
141Song commands:
142 L List the songs that will be affected.
143 t Change the title of the song.
144 l Change the location of the song.
145 r Change the song's artist.
146 a Change the song's album.
147 d Remove the song from the database.
148 The original file will remain intact.
149 v Toggle Activation: Toggle the active status of
150 the song. Provide an argument of 0 to deactivate or 1
151 to activate the selected songs. Default behaviour is
152 to flip the status of each song. Deactivated songs are
153 similar to deleted songs except that they keep their
154 play statistics and may be played only if reactivated
155 or if directly chosen to be played with the --type=s flag.
156 g Change which genres the song belongs to.
157 Song-Genre commands:
158 L List the genres the song belongs to.
159 a Add the song to a genre.
160 r Remove the song from a genre.
161
162Album commands:
163 NOTE: Commands that require additional input can take
164 it as an argument
165 (e.g., t NewTitle)
166 L List the albums that will be affected.
167 t Change the album's title.
168 r Change the album's artist.
169
170Artist commands:
171 NOTE: Commands that require additional input can take
172 it as an argument
173 (e.g., n NewName)
174 L List the artists that will be affected.
175 n Change the artist's name.
176
177Playlist commands:
178 NOTE: Commands that require additional input can take
179 it as an argument
180 (n NewName) or (o 10 4)
181 L List playlists that will be affected
182 LC List contents of the playlists that will be affected
183 c Create a new playlist.
184 n Change the name of the playlist.
185 d Delete the playlist. Songs will remain in the database.
186 a Add a song to the playlist.
187 r Remove a song from the playlist.
188 (Takes an argument of Order. Not SongID)
189 o Change the order of a song in the playlist.
190 (Takes two arguments: current order and new order)
191
192Genre commands:
193 NOTE: Commands that require additional input can take
194 it as an argument
195 (e.g., n NewName)
196 L List genres that will be affected
197 LC List contents of the genres that will be affected
198 a Add a genre.
199 n Change the name of the genre.
200 o Change the genre's owner (parent).
201 d Delete the genre. If a song is left without any genres,
202 it will be added to the 'Unknown' genre at the end of
203 the session.
204
205
2064. Admin
207
208Manage Stats (s)
209 r Reset stats
210 a Reset all
211 r Reset ratings
212 d Reset play count
213 s Reset skip count
214 l Reset last play time
215 e Export stats
216 Stats will be output to a file in tab separated columns
217 sorted by file location.
218
219
220III. Customization
221
2221. Configuration File:
223 This located at ~/.harp/defaults.conf
224
225General format for this file:
226 -Comments start with #
227 -Section names are enclosed in []
228 -Options are in the format: option=setting
229
230
231IV. Requirements
232
233Sound output:
234 One of: ALSA, OSS, JACK, or PulseAudio
235 JACK also requires libsamplerate
236Database:
237 SQLite3
238Default Decoders:
239 MP3: libmpg123
240 - http://www.mpg123.de/
241 AAC: libfaad2
242 - http://www.audiocoding.com/downloads.html
243 OGG: libvorbisfile
244 - http://www.xiph.org/downloads/
245 FLAC: libFLAC
246 - http://www.xiph.org/downloads/
247