1 /***
2 * Ambient - A music player for the Android platform
3 Copyright (C) 2007 Martin Vysny
4
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18 package sk.baka.ambient.playlist;
19
20 import java.util.List;
21 import java.util.Map;
22
23 import sk.baka.ambient.collection.TrackMetadataBean;
24 import sk.baka.ambient.commons.Interval;
25 import android.os.Handler;
26
27 /***
28 * <p>
29 * An interface for a playlist. There are two playlist implementations -
30 * {@link StaticPlaylistStrategy} which holds a static playlist and supports
31 * random/repeat playmodes, and {@link DynamicPlaylistStrategy} which
32 * dynamically polls its datasource and modifies itself as the player propagates
33 * through the playlist.
34 * </p>
35 * <p>
36 * All implementations should be serializable. Thread-unsafe - it is recommended
37 * that all methods are invoked in the {@link Handler} thread.
38 * </p>
39 *
40 * @author Martin Vysny
41 */
42 public interface IPlaylistStrategy {
43 /***
44 * Sets the random mode. Currently played track must be preserved.
45 *
46 * @param random
47 * the random mode, never <code>null</code>.
48 */
49 void setRandom(final Random random);
50
51 /***
52 * Returns current random mode.
53 *
54 * @return the random mode, never <code>null</code>.
55 */
56 Random getRandom();
57
58 /***
59 * Sorts the playlist with album order ordering.
60 */
61 void sortByAlbumOrder();
62
63 /***
64 * Randomize the playlist.
65 */
66 void shuffle();
67
68 /***
69 * Returns currently playing track. Note that the playlist is not connected
70 * to the player and the player itself may be paused or stopped.
71 *
72 * @return currently playing track or <code>-1</code> if nothing is being
73 * played. Index to the {@link #getPlayItems()} list.
74 */
75 int getCurrentlyPlaying();
76
77 /***
78 * Moves to next track to be played. Returns <code>-1</code> if no more
79 * tracks are to be played - this also causes the
80 * {@link #getCurrentlyPlaying()} method to return <code>-1</code>.
81 * Calling this method while not playing anything will start to play first
82 * track.
83 *
84 * @return play item to play next or <code>-1</code> if no more items are
85 * to be played. Index to the {@link #getPlayItems()} list.
86 */
87 int next();
88
89 /***
90 * Plays given track. The playback continues from this track forward, unless
91 * random play is activated.
92 *
93 * @param track
94 * the track to play. Index to the {@link #getPlayItems()} list.
95 * If <code>-1</code> then the current track pointer is moved
96 * before first track and the playback is stopped.
97 * @return the track that is being played.
98 */
99 int play(final int track);
100
101 /***
102 * Returns previous track to be played. Returns <code>-1</code> if we are
103 * at the beginning of the playing track sequence. Calling this method while
104 * not playing anything will start to play last track.
105 *
106 * @return which item was played prior current track or <code>-1</code> if
107 * we are at the beginning of the playing track sequence.
108 */
109 int previous();
110
111 /***
112 * Queue this track for playing, after all other queued tracks. Does nothing
113 * if the track is already queued.
114 *
115 * @param tracks
116 * the tracks to queue, index to the {@link #getPlayItems()}
117 * list.
118 */
119 void queue(final Interval tracks);
120
121 /***
122 * Dequeues given track if it was queued previously. Does nothing if the
123 * track is not present in the queue anymore.
124 *
125 * @param track
126 * the track to dequeue.
127 */
128 void dequeue(final int track);
129
130 /***
131 * Clears queue from queued.
132 */
133 void clearQueue();
134
135 /***
136 * Returns currently queued tracks.
137 *
138 * @return queued tracks, never <code>null</code>.
139 */
140 List<Integer> getQueue();
141
142 /***
143 * Returns the playlist length.
144 *
145 * @return the playlist length.
146 */
147 int size();
148
149 /***
150 * <p>
151 * Returns list of playlist items. The operation must be quick - it should
152 * for example provide immutable view on an internal playlist structure, it
153 * should not recompute the list anew on each call.
154 * </p>
155 * <p>
156 * Each PlaylistItem in the list must be an unique instance.
157 * </p>
158 *
159 * @return list of playlist items, will not be modified.
160 */
161 List<PlaylistItem> getPlayItems();
162
163 /***
164 * Reinitializes the playlist - recomputes new random track ordering etc.
165 * Removes all queued tracks and stops the playback ({@link #getCurrentlyPlaying()}
166 * will return <code>-1</code>).
167 */
168 void reinit();
169
170 /***
171 * Inserts given tracks before track with given index.
172 *
173 * @param index
174 * the index, must not be negative.
175 * @param tracks
176 * the tracks meta, must not be <code>null</code>.
177 */
178 void add(final int index, final List<TrackMetadataBean> tracks);
179
180 /***
181 * Removes tracks with given index from the playlist. If currently played
182 * track is removed then the current song must be set to <code>-1</code>.
183 *
184 * @param interval
185 * the interval to remove
186 */
187 void remove(final Interval interval);
188
189 /***
190 * Moves selected tracks before track with given index. Correctly updates
191 * queue indices. Currently played track will not be changed, although the
192 * track index may change.
193 *
194 * @param interval
195 * the interval to move
196 * @param targetIndex
197 * move tracks before track with this index. If this index is
198 * contained in the interval then nothing is done.
199 * @return a new interval which contains all moved tracks.
200 * @throws IllegalArgumentException
201 * if the interval exceeds the playlist.
202 */
203 Interval move(final Interval interval, final int targetIndex);
204
205 /***
206 * <p>
207 * Moves selected tracks up or down at least <code>delta</code> tracks,
208 * depending on the 'delta' value. The playlist may decide to move tracks by
209 * more tracks than requested - for example, the dynamic playlist will skip
210 * the currently playing/queued tracks. If the move is not possible (for
211 * example there are not enough tracks) then move the tracks to the
212 * beginning (or end) of the playlist.
213 * </p>
214 * <p>
215 * Currently played track will not be changed, although the queue indices.
216 * Currently played track will not be changed, although the track index may
217 * change.
218 * </p>
219 *
220 * @param interval
221 * the interval to move
222 * @param delta
223 * move tracks up 'delta' tracks (if delta is negative), or down
224 * 'delta' tracks (if delta is positive). Do nothing if delta is
225 * zero.
226 * @return a new interval which contains all moved tracks.
227 * @throws IllegalArgumentException
228 * if the interval exceeds the playlist.
229 */
230 Interval moveBy(final Interval interval, final int delta);
231
232 /***
233 * Peeks at the next track without actually changing the current track.
234 *
235 * @return next track index. Returns <code>-1</code> when there's no track
236 * left. Dynamic playlist may return <code>-1</code> when there
237 * are no upcoming tracks and the queue is empty.
238 */
239 int peekNext();
240
241 /***
242 * Modifies the playlist by changing all {@link PlaylistItem} locations.
243 *
244 * @param locationMap
245 * maps old locations to new locations.
246 */
247 void replaceLocations(final Map<String, String> locationMap);
248 }