1 /* 2 * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 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 116 eotEvent.setTick(lastEvent.getTick()); 117 } else { 118 // if the events list is empty, just set the tick to 0 119 eotEvent.setTick(0); 120 } 121 // we needn't check for a duplicate of eotEvent in "eventsList", 122 // since then it would appear in the set. 123 eventsList.add(eotEvent); 124 set.add(eotEvent); 125 eventsCount = eventsList.size(); 126 } 127 128 // first see if we are trying to add 129 // and endoftrack event. 130 if (MidiUtils.isMetaEndOfTrack(event.getMessage())) { 131 // since end of track event is useful 132 // for delays at the end of a track, we want to keep 133 // the tick value requested here if it is greater 134 // than the one on the eot we are maintaining. 135 // Otherwise, we only want a single eot event, so ignore. 136 if (event.getTick() > eotEvent.getTick()) { 137 eotEvent.setTick(event.getTick()); 138 } 139 return true; 140 } 141 142 // prevent duplicates 143 set.add(event); 144 145 // insert event such that events is sorted in increasing 146 // tick order 147 int i = eventsCount; 148 for ( ; i > 0; i--) { 149 if (event.getTick() >= (eventsList.get(i-1)).getTick()) { 150 break; 151 } 152 } 153 if (i == eventsCount) { 154 // we're adding an event after the 155 // tick value of our eot, so push the eot out. 156 // Always add at the end for better performance: 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 }