8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.sound.midi;
27
28 import java.util.Vector;
29 import java.util.ArrayList;
30 import java.util.HashSet;
31 import com.sun.media.sound.MidiUtils;
32
33 /**
34 * A MIDI track is an independent stream of MIDI events (time-stamped MIDI
35 * data) that can be stored along with other tracks in a standard MIDI file.
36 * The MIDI specification allows only 16 channels of MIDI data, but tracks
37 * are a way to get around this limitation. A MIDI file can contain any number
38 * of tracks, each containing its own stream of up to 16 channels of MIDI data.
39 * <p>
40 * A <code>Track</code> occupies a middle level in the hierarchy of data played
41 * by a <code>{@link Sequencer}</code>: sequencers play sequences, which contain tracks,
42 * which contain MIDI events. A sequencer may provide controls that mute
43 * or solo individual tracks.
44 * <p>
45 * The timing information and resolution for a track is controlled by and stored
46 * in the sequence containing the track. A given <code>Track</code>
47 * is considered to belong to the particular <code>{@link Sequence}</code> that
48 * maintains its timing. For this reason, a new (empty) track is created by calling the
49 * <code>{@link Sequence#createTrack}</code> method, rather than by directly invoking a
50 * <code>Track</code> constructor.
51 * <p>
52 * The <code>Track</code> class provides methods to edit the track by adding
53 * or removing <code>MidiEvent</code> objects from it. These operations keep
54 * the event list in the correct time order. Methods are also
55 * included to obtain the track's size, in terms of either the number of events
56 * it contains or its duration in ticks.
57 *
58 * @see Sequencer#setTrackMute
59 * @see Sequencer#setTrackSolo
60 *
61 * @author Kara Kytle
62 * @author Florian Bomers
63 */
64 public class Track {
65
66 // TODO: use arrays for faster access
67
68 // the list containing the events
69 private ArrayList<MidiEvent> eventsList = new ArrayList<>();
70
71 // use a hashset to detect duplicate events in add(MidiEvent)
72 private HashSet<MidiEvent> set = new HashSet<>();
73
74 private MidiEvent eotEvent;
75
76
77 /**
78 * Package-private constructor. Constructs a new, empty Track object,
79 * which initially contains one event, the meta-event End of Track.
80 */
81 Track() {
82 // start with the end of track event
83 MetaMessage eot = new ImmutableEndOfTrack();
84 eotEvent = new MidiEvent(eot, 0);
85 eventsList.add(eotEvent);
86 set.add(eotEvent);
87 }
88
89 /**
90 * Adds a new event to the track. However, if the event is already
91 * contained in the track, it is not added again. The list of events
92 * is kept in time order, meaning that this event inserted at the
93 * appropriate place in the list, not necessarily at the end.
94 *
95 * @param event the event to add
96 * @return <code>true</code> if the event did not already exist in the
97 * track and was added, otherwise <code>false</code>
98 */
99 public boolean add(MidiEvent event) {
100 if (event == null) {
101 return false;
102 }
103 synchronized(eventsList) {
104
105 if (!set.contains(event)) {
106 int eventsCount = eventsList.size();
107
108 // get the last event
109 MidiEvent lastEvent = null;
110 if (eventsCount > 0) {
111 lastEvent = eventsList.get(eventsCount - 1);
112 }
113 // sanity check that we have a correct end-of-track
114 if (lastEvent != eotEvent) {
115 // if there is no eot event, add our immutable instance again
116 if (lastEvent != null) {
117 // set eotEvent's tick to the last tick of the track
159 // this saves all the checks and arraycopy when inserting
160
161 // overwrite eot with new event
162 eventsList.set(eventsCount - 1, event);
163 // set new time of eot, if necessary
164 if (eotEvent.getTick() < event.getTick()) {
165 eotEvent.setTick(event.getTick());
166 }
167 // add eot again at the end
168 eventsList.add(eotEvent);
169 } else {
170 eventsList.add(i, event);
171 }
172 return true;
173 }
174 }
175
176 return false;
177 }
178
179
180 /**
181 * Removes the specified event from the track.
182 * @param event the event to remove
183 * @return <code>true</code> if the event existed in the track and was removed,
184 * otherwise <code>false</code>
185 */
186 public boolean remove(MidiEvent event) {
187
188 // this implementation allows removing the EOT event.
189 // pretty bad, but would probably be too risky to
190 // change behavior now, in case someone does tricks like:
191 //
192 // while (track.size() > 0) track.remove(track.get(track.size() - 1));
193
194 // also, would it make sense to adjust the EOT's time
195 // to the last event, if the last non-EOT event is removed?
196 // Or: document that the ticks() length will not be reduced
197 // by deleting events (unless the EOT event is removed)
198 synchronized(eventsList) {
199 if (set.remove(event)) {
200 int i = eventsList.indexOf(event);
201 if (i >= 0) {
202 eventsList.remove(i);
203 return true;
204 }
205 }
206 }
207 return false;
208 }
209
210
211 /**
212 * Obtains the event at the specified index.
213 * @param index the location of the desired event in the event vector
214 * @throws ArrayIndexOutOfBoundsException if the
215 * specified index is negative or not less than the current size of
216 * this track.
217 * @see #size
218 * @return the event at the specified index
219 */
220 public MidiEvent get(int index) throws ArrayIndexOutOfBoundsException {
221 try {
222 synchronized(eventsList) {
223 return eventsList.get(index);
224 }
225 } catch (IndexOutOfBoundsException ioobe) {
226 throw new ArrayIndexOutOfBoundsException(ioobe.getMessage());
227 }
228 }
229
230
231 /**
232 * Obtains the number of events in this track.
233 * @return the size of the track's event vector
234 */
235 public int size() {
236 synchronized(eventsList) {
237 return eventsList.size();
238 }
239 }
240
241
242 /**
243 * Obtains the length of the track, expressed in MIDI ticks. (The
244 * duration of a tick in seconds is determined by the timing resolution
245 * of the <code>Sequence</code> containing this track, and also by
246 * the tempo of the music as set by the sequencer.)
247 * @return the duration, in ticks
248 * @see Sequence#Sequence(float, int)
249 * @see Sequencer#setTempoInBPM(float)
250 * @see Sequencer#getTickPosition()
251 */
252 public long ticks() {
253 long ret = 0;
254 synchronized (eventsList) {
255 if (eventsList.size() > 0) {
256 ret = (eventsList.get(eventsList.size() - 1)).getTick();
257 }
258 }
259 return ret;
260 }
261
262 private static class ImmutableEndOfTrack extends MetaMessage {
263 private ImmutableEndOfTrack() {
264 super(new byte[3]);
265 data[0] = (byte) META;
266 data[1] = MidiUtils.META_END_OF_TRACK_TYPE;
267 data[2] = 0;
268 }
269
270 public void setMessage(int type, byte[] data, int length) throws InvalidMidiDataException {
271 throw new InvalidMidiDataException("cannot modify end of track message");
272 }
273 }
274
275 }
|
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.sound.midi;
27
28 import java.util.ArrayList;
29 import java.util.HashSet;
30
31 import com.sun.media.sound.MidiUtils;
32
33 /**
34 * A MIDI track is an independent stream of MIDI events (time-stamped MIDI data)
35 * that can be stored along with other tracks in a standard MIDI file. The MIDI
36 * specification allows only 16 channels of MIDI data, but tracks are a way to
37 * get around this limitation. A MIDI file can contain any number of tracks,
38 * each containing its own stream of up to 16 channels of MIDI data.
39 * <p>
40 * A {@code Track} occupies a middle level in the hierarchy of data played by a
41 * {@link Sequencer}: sequencers play sequences, which contain tracks, which
42 * contain MIDI events. A sequencer may provide controls that mute or solo
43 * individual tracks.
44 * <p>
45 * The timing information and resolution for a track is controlled by and stored
46 * in the sequence containing the track. A given {@code Track} is considered to
47 * belong to the particular {@link Sequence} that maintains its timing. For this
48 * reason, a new (empty) track is created by calling the
49 * {@link Sequence#createTrack} method, rather than by directly invoking a
50 * {@code Track} constructor.
51 * <p>
52 * The {@code Track} class provides methods to edit the track by adding or
53 * removing {@code MidiEvent} objects from it. These operations keep the event
54 * list in the correct time order. Methods are also included to obtain the
55 * track's size, in terms of either the number of events it contains or its
56 * duration in ticks.
57 *
58 * @author Kara Kytle
59 * @author Florian Bomers
60 * @see Sequencer#setTrackMute
61 * @see Sequencer#setTrackSolo
62 */
63 public class Track {
64
65 // TODO: use arrays for faster access
66
67 // the list containing the events
68 private ArrayList<MidiEvent> eventsList = new ArrayList<>();
69
70 // use a hashset to detect duplicate events in add(MidiEvent)
71 private HashSet<MidiEvent> set = new HashSet<>();
72
73 private MidiEvent eotEvent;
74
75 /**
76 * Package-private constructor. Constructs a new, empty Track object, which
77 * initially contains one event, the meta-event End of Track.
78 */
79 Track() {
80 // start with the end of track event
81 MetaMessage eot = new ImmutableEndOfTrack();
82 eotEvent = new MidiEvent(eot, 0);
83 eventsList.add(eotEvent);
84 set.add(eotEvent);
85 }
86
87 /**
88 * Adds a new event to the track. However, if the event is already contained
89 * in the track, it is not added again. The list of events is kept in time
90 * order, meaning that this event inserted at the appropriate place in the
91 * list, not necessarily at the end.
92 *
93 * @param event the event to add
94 * @return {@code true} if the event did not already exist in the track and
95 * was added, otherwise {@code false}
96 */
97 public boolean add(MidiEvent event) {
98 if (event == null) {
99 return false;
100 }
101 synchronized(eventsList) {
102
103 if (!set.contains(event)) {
104 int eventsCount = eventsList.size();
105
106 // get the last event
107 MidiEvent lastEvent = null;
108 if (eventsCount > 0) {
109 lastEvent = eventsList.get(eventsCount - 1);
110 }
111 // sanity check that we have a correct end-of-track
112 if (lastEvent != eotEvent) {
113 // if there is no eot event, add our immutable instance again
114 if (lastEvent != null) {
115 // set eotEvent's tick to the last tick of the track
157 // this saves all the checks and arraycopy when inserting
158
159 // overwrite eot with new event
160 eventsList.set(eventsCount - 1, event);
161 // set new time of eot, if necessary
162 if (eotEvent.getTick() < event.getTick()) {
163 eotEvent.setTick(event.getTick());
164 }
165 // add eot again at the end
166 eventsList.add(eotEvent);
167 } else {
168 eventsList.add(i, event);
169 }
170 return true;
171 }
172 }
173
174 return false;
175 }
176
177 /**
178 * Removes the specified event from the track.
179 *
180 * @param event the event to remove
181 * @return {@code true} if the event existed in the track and was removed,
182 * otherwise {@code false}
183 */
184 public boolean remove(MidiEvent event) {
185
186 // this implementation allows removing the EOT event.
187 // pretty bad, but would probably be too risky to
188 // change behavior now, in case someone does tricks like:
189 //
190 // while (track.size() > 0) track.remove(track.get(track.size() - 1));
191
192 // also, would it make sense to adjust the EOT's time
193 // to the last event, if the last non-EOT event is removed?
194 // Or: document that the ticks() length will not be reduced
195 // by deleting events (unless the EOT event is removed)
196 synchronized(eventsList) {
197 if (set.remove(event)) {
198 int i = eventsList.indexOf(event);
199 if (i >= 0) {
200 eventsList.remove(i);
201 return true;
202 }
203 }
204 }
205 return false;
206 }
207
208 /**
209 * Obtains the event at the specified index.
210 *
211 * @param index the location of the desired event in the event vector
212 * @return the event at the specified index
213 * @throws ArrayIndexOutOfBoundsException if the specified index is negative
214 * or not less than the current size of this track
215 * @see #size
216 */
217 public MidiEvent get(int index) throws ArrayIndexOutOfBoundsException {
218 try {
219 synchronized(eventsList) {
220 return eventsList.get(index);
221 }
222 } catch (IndexOutOfBoundsException ioobe) {
223 throw new ArrayIndexOutOfBoundsException(ioobe.getMessage());
224 }
225 }
226
227 /**
228 * Obtains the number of events in this track.
229 *
230 * @return the size of the track's event vector
231 */
232 public int size() {
233 synchronized(eventsList) {
234 return eventsList.size();
235 }
236 }
237
238 /**
239 * Obtains the length of the track, expressed in MIDI ticks. (The duration
240 * of a tick in seconds is determined by the timing resolution of the
241 * {@code Sequence} containing this track, and also by the tempo of the
242 * music as set by the sequencer.)
243 *
244 * @return the duration, in ticks
245 * @see Sequence#Sequence(float, int)
246 * @see Sequencer#setTempoInBPM(float)
247 * @see Sequencer#getTickPosition()
248 */
249 public long ticks() {
250 long ret = 0;
251 synchronized (eventsList) {
252 if (eventsList.size() > 0) {
253 ret = (eventsList.get(eventsList.size() - 1)).getTick();
254 }
255 }
256 return ret;
257 }
258
259 private static class ImmutableEndOfTrack extends MetaMessage {
260 private ImmutableEndOfTrack() {
261 super(new byte[3]);
262 data[0] = (byte) META;
263 data[1] = MidiUtils.META_END_OF_TRACK_TYPE;
264 data[2] = 0;
265 }
266
267 public void setMessage(int type, byte[] data, int length) throws InvalidMidiDataException {
268 throw new InvalidMidiDataException("cannot modify end of track message");
269 }
270 }
271 }
|