23 * questions. |
23 * questions. |
24 */ |
24 */ |
25 |
25 |
26 package javax.sound.midi; |
26 package javax.sound.midi; |
27 |
27 |
28 |
|
29 /** |
28 /** |
30 * A <code>MetaMessage</code> is a <code>{@link MidiMessage}</code> that is not meaningful to synthesizers, but |
29 * A {@code MetaMessage} is a {@link MidiMessage} that is not meaningful to |
31 * that can be stored in a MIDI file and interpreted by a sequencer program. |
30 * synthesizers, but that can be stored in a MIDI file and interpreted by a |
32 * (See the discussion in the <code>MidiMessage</code> |
31 * sequencer program. (See the discussion in the {@code MidiMessage} class |
33 * class description.) The Standard MIDI Files specification defines |
32 * description.) The Standard MIDI Files specification defines various types of |
34 * various types of meta-events, such as sequence number, lyric, cue point, |
33 * meta-events, such as sequence number, lyric, cue point, and set tempo. There |
35 * and set tempo. There are also meta-events |
34 * are also meta-events for such information as lyrics, copyrights, tempo |
36 * for such information as lyrics, copyrights, tempo indications, time and key |
35 * indications, time and key signatures, markers, etc. For more information, see |
37 * signatures, markers, etc. For more information, see the Standard MIDI Files 1.0 |
36 * the Standard MIDI Files 1.0 specification, which is part of the Complete MIDI |
38 * specification, which is part of the Complete MIDI 1.0 Detailed Specification |
37 * 1.0 Detailed Specification published by the MIDI Manufacturer's Association |
39 * published by the MIDI Manufacturer's Association |
|
40 * (<a href = http://www.midi.org>http://www.midi.org</a>). |
38 * (<a href = http://www.midi.org>http://www.midi.org</a>). |
41 * |
|
42 * <p> |
39 * <p> |
43 * When data is being transported using MIDI wire protocol, |
40 * When data is being transported using MIDI wire protocol, a |
44 * a <code>{@link ShortMessage}</code> with the status value <code>0xFF</code> represents |
41 * {@link ShortMessage} with the status value {@code 0xFF} represents a system |
45 * a system reset message. In MIDI files, this same status value denotes a <code>MetaMessage</code>. |
42 * reset message. In MIDI files, this same status value denotes a |
46 * The types of meta-message are distinguished from each other by the first byte |
43 * {@code MetaMessage}. The types of meta-message are distinguished from each |
47 * that follows the status byte <code>0xFF</code>. The subsequent bytes are data |
44 * other by the first byte that follows the status byte {@code 0xFF}. The |
48 * bytes. As with system exclusive messages, there are an arbitrary number of |
45 * subsequent bytes are data bytes. As with system exclusive messages, there are |
49 * data bytes, depending on the type of <code>MetaMessage</code>. |
46 * an arbitrary number of data bytes, depending on the type of |
50 * |
47 * {@code MetaMessage}. |
51 * @see MetaEventListener |
|
52 * |
48 * |
53 * @author David Rivas |
49 * @author David Rivas |
54 * @author Kara Kytle |
50 * @author Kara Kytle |
|
51 * @see MetaEventListener |
55 */ |
52 */ |
56 |
|
57 public class MetaMessage extends MidiMessage { |
53 public class MetaMessage extends MidiMessage { |
58 |
54 |
59 |
55 /** |
60 // Status byte defines |
56 * Status byte for {@code MetaMessage} (0xFF, or 255), which is used in MIDI |
61 |
57 * files. It has the same value as SYSTEM_RESET, which is used in the |
62 /** |
58 * real-time "MIDI wire" protocol. |
63 * Status byte for <code>MetaMessage</code> (0xFF, or 255), which is used |
59 * |
64 * in MIDI files. It has the same value as SYSTEM_RESET, which |
|
65 * is used in the real-time "MIDI wire" protocol. |
|
66 * @see MidiMessage#getStatus |
60 * @see MidiMessage#getStatus |
67 */ |
61 */ |
68 public static final int META = 0xFF; // 255 |
62 public static final int META = 0xFF; // 255 |
69 |
63 |
70 // Instance variables |
64 /** |
71 |
65 * The length of the actual message in the data array. This is used to |
72 /** |
66 * determine how many bytes of the data array is the message, and how many |
73 * The length of the actual message in the data array. |
67 * are the status byte, the type byte, and the variable-length-int |
74 * This is used to determine how many bytes of the data array |
68 * describing the length of the message. |
75 * is the message, and how many are the status byte, the |
|
76 * type byte, and the variable-length-int describing the |
|
77 * length of the message. |
|
78 */ |
69 */ |
79 private int dataLength = 0; |
70 private int dataLength = 0; |
80 |
71 |
81 |
72 /** |
82 /** |
73 * Constructs a new {@code MetaMessage}. The contents of the message are not |
83 * Constructs a new <code>MetaMessage</code>. The contents of |
74 * set here; use {@link #setMessage(int, byte[], int) setMessage} to set |
84 * the message are not set here; use |
75 * them subsequently. |
85 * {@link #setMessage(int, byte[], int) setMessage} |
|
86 * to set them subsequently. |
|
87 */ |
76 */ |
88 public MetaMessage() { |
77 public MetaMessage() { |
89 // Default meta message data: just the META status byte value |
78 // Default meta message data: just the META status byte value |
90 this(new byte[]{(byte) META, 0}); |
79 this(new byte[]{(byte) META, 0}); |
91 } |
80 } |
92 |
81 |
93 /** |
82 /** |
94 * Constructs a new {@code MetaMessage} and sets the message parameters. |
83 * Constructs a new {@code MetaMessage} and sets the message parameters. The |
95 * The contents of the message can be changed by using |
84 * contents of the message can be changed by using the {@code setMessage} |
96 * the {@code setMessage} method. |
85 * method. |
97 * |
86 * |
98 * @param type meta-message type (must be less than 128) |
87 * @param type meta-message type (must be less than 128) |
99 * @param data the data bytes in the MIDI message |
88 * @param data the data bytes in the MIDI message |
100 * @param length an amount of bytes in the {@code data} byte array; |
89 * @param length an amount of bytes in the {@code data} byte array; it |
101 * it should be non-negative and less than or equal to |
90 * should be non-negative and less than or equal to |
102 * {@code data.length} |
91 * {@code data.length} |
103 * @throws InvalidMidiDataException if the parameter values do not specify |
92 * @throws InvalidMidiDataException if the parameter values do not specify a |
104 * a valid MIDI meta message |
93 * valid MIDI meta message |
105 * @see #setMessage(int, byte[], int) |
94 * @see #setMessage(int, byte[], int) |
106 * @see #getType() |
95 * @see #getType() |
107 * @see #getData() |
96 * @see #getData() |
108 * @since 1.7 |
97 * @since 1.7 |
109 */ |
98 */ |
131 dataLength--; pos++; |
119 dataLength--; pos++; |
132 } |
120 } |
133 } |
121 } |
134 } |
122 } |
135 |
123 |
136 |
124 /** |
137 /** |
125 * Sets the message parameters for a {@code MetaMessage}. Since only one |
138 * Sets the message parameters for a <code>MetaMessage</code>. |
126 * status byte value, {@code 0xFF}, is allowed for meta-messages, it does |
139 * Since only one status byte value, <code>0xFF</code>, is allowed for meta-messages, |
127 * not need to be specified here. Calls to |
140 * it does not need to be specified here. Calls to <code>{@link MidiMessage#getStatus getStatus}</code> return |
128 * {@link MidiMessage#getStatus getStatus} return {@code 0xFF} for all |
141 * <code>0xFF</code> for all meta-messages. |
129 * meta-messages. |
142 * <p> |
130 * <p> |
143 * The <code>type</code> argument should be a valid value for the byte that |
131 * The {@code type} argument should be a valid value for the byte that |
144 * follows the status byte in the <code>MetaMessage</code>. The <code>data</code> argument |
132 * follows the status byte in the {@code MetaMessage}. The {@code data} |
145 * should contain all the subsequent bytes of the <code>MetaMessage</code>. In other words, |
133 * argument should contain all the subsequent bytes of the |
146 * the byte that specifies the type of <code>MetaMessage</code> is not considered a data byte. |
134 * {@code MetaMessage}. In other words, the byte that specifies the type of |
147 * |
135 * {@code MetaMessage} is not considered a data byte. |
148 * @param type meta-message type (must be less than 128) |
136 * |
149 * @param data the data bytes in the MIDI message |
137 * @param type meta-message type (must be less than 128) |
150 * @param length the number of bytes in the <code>data</code> |
138 * @param data the data bytes in the MIDI message |
151 * byte array |
139 * @param length the number of bytes in the {@code data} byte array |
152 * @throws InvalidMidiDataException if the |
140 * @throws InvalidMidiDataException if the parameter values do not specify a |
153 * parameter values do not specify a valid MIDI meta message |
141 * valid MIDI meta message |
154 */ |
142 */ |
155 public void setMessage(int type, byte[] data, int length) throws InvalidMidiDataException { |
143 public void setMessage(int type, byte[] data, int length) throws InvalidMidiDataException { |
156 |
144 |
157 if (type >= 128 || type < 0) { |
145 if (type >= 128 || type < 0) { |
158 throw new InvalidMidiDataException("Invalid meta event with type " + type); |
146 throw new InvalidMidiDataException("Invalid meta event with type " + type); |
170 if (length > 0) { |
158 if (length > 0) { |
171 System.arraycopy(data, 0, this.data, this.length - this.dataLength, this.dataLength); |
159 System.arraycopy(data, 0, this.data, this.length - this.dataLength, this.dataLength); |
172 } |
160 } |
173 } |
161 } |
174 |
162 |
175 |
163 /** |
176 /** |
164 * Obtains the type of the {@code MetaMessage}. |
177 * Obtains the type of the <code>MetaMessage</code>. |
165 * |
178 * @return an integer representing the <code>MetaMessage</code> type |
166 * @return an integer representing the {@code MetaMessage} type |
179 */ |
167 */ |
180 public int getType() { |
168 public int getType() { |
181 if (length>=2) { |
169 if (length>=2) { |
182 return data[1] & 0xFF; |
170 return data[1] & 0xFF; |
183 } |
171 } |
184 return 0; |
172 return 0; |
185 } |
173 } |
186 |
174 |
187 |
175 /** |
188 |
176 * Obtains a copy of the data for the meta message. The returned array of |
189 /** |
177 * bytes does not include the status byte or the message length data. The |
190 * Obtains a copy of the data for the meta message. The returned |
178 * length of the data for the meta message is the length of the array. Note |
191 * array of bytes does not include the status byte or the message |
179 * that the length of the entire message includes the status byte and the |
192 * length data. The length of the data for the meta message is |
180 * meta message type byte, and therefore may be longer than the returned |
193 * the length of the array. Note that the length of the entire |
181 * array. |
194 * message includes the status byte and the meta message type |
182 * |
195 * byte, and therefore may be longer than the returned array. |
183 * @return array containing the meta message data |
196 * @return array containing the meta message data. |
|
197 * @see MidiMessage#getLength |
184 * @see MidiMessage#getLength |
198 */ |
185 */ |
199 public byte[] getData() { |
186 public byte[] getData() { |
200 byte[] returnedArray = new byte[dataLength]; |
187 byte[] returnedArray = new byte[dataLength]; |
201 System.arraycopy(data, (length - dataLength), returnedArray, 0, dataLength); |
188 System.arraycopy(data, (length - dataLength), returnedArray, 0, dataLength); |
202 return returnedArray; |
189 return returnedArray; |
203 } |
190 } |
204 |
191 |
205 |
192 /** |
206 /** |
193 * Creates a new object of the same class and with the same contents as this |
207 * Creates a new object of the same class and with the same contents |
194 * object. |
208 * as this object. |
195 * |
209 * @return a clone of this instance |
196 * @return a clone of this instance |
210 */ |
197 */ |
211 public Object clone() { |
198 public Object clone() { |
212 byte[] newData = new byte[length]; |
199 byte[] newData = new byte[length]; |
213 System.arraycopy(data, 0, newData, 0, newData.length); |
200 System.arraycopy(data, 0, newData, 0, newData.length); |