23 * questions.
24 */
25
26 package javax.sound.sampled;
27
28 import java.util.Collections;
29 import java.util.HashMap;
30 import java.util.Map;
31 import java.util.Objects;
32
33 /**
34 * {@code AudioFormat} is the class that specifies a particular arrangement of
35 * data in a sound stream. By examining the information stored in the audio
36 * format, you can discover how to interpret the bits in the binary sound data.
37 * <p>
38 * Every data line has an audio format associated with its data stream. The
39 * audio format of a source (playback) data line indicates what kind of data the
40 * data line expects to receive for output. For a target (capture) data line,
41 * the audio format specifies the kind of the data that can be read from the
42 * line.
43 * Sound files also have audio formats, of course. The {@link AudioFileFormat}
44 * class encapsulates an {@code AudioFormat} in addition to other, file-specific
45 * information. Similarly, an {@link AudioInputStream} has an
46 * {@code AudioFormat}.
47 * <p>
48 * The {@code AudioFormat} class accommodates a number of common sound-file
49 * encoding techniques, including pulse-code modulation (PCM), mu-law encoding,
50 * and a-law encoding. These encoding techniques are predefined, but service
51 * providers can create new encoding types. The encoding that a specific format
52 * uses is named by its {@code encoding} field.
53 * <p>
54 * In addition to the encoding, the audio format includes other properties that
55 * further specify the exact arrangement of the data. These include the number
56 * of channels, sample rate, sample size, byte order, frame rate, and frame
57 * size. Sounds may have different numbers of audio channels: one for mono, two
58 * for stereo. The sample rate measures how many "snapshots" (samples) of the
59 * sound pressure are taken per second, per channel. (If the sound is stereo
60 * rather than mono, two samples are actually measured at each instant of time:
61 * one for the left channel, and another for the right channel; however, the
62 * sample rate still measures the number per channel, so the rate is the same
76 * <p>
77 * An {@code AudioFormat} object can include a set of properties. A property is
78 * a pair of key and value: the key is of type {@code String}, the associated
79 * property value is an arbitrary object. Properties specify additional format
80 * specifications, like the bit rate for compressed formats. Properties are
81 * mainly used as a means to transport additional information of the audio
82 * format to and from the service providers. Therefore, properties are ignored
83 * in the {@link #matches(AudioFormat)} method. However, methods which rely on
84 * the installed service providers, like
85 * {@link AudioSystem#isConversionSupported (AudioFormat, AudioFormat)
86 * isConversionSupported} may consider properties, depending on the respective
87 * service provider implementation.
88 * <p>
89 * The following table lists some common properties which service providers
90 * should use, if applicable:
91 *
92 * <table class="striped">
93 * <caption>Audio Format Properties</caption>
94 * <thead>
95 * <tr>
96 * <th>Property key</th>
97 * <th>Value type</th>
98 * <th>Description</th>
99 * </tr>
100 * </thead>
101 * <tbody>
102 * <tr>
103 * <td>"bitrate"</td>
104 * <td>{@link java.lang.Integer Integer}</td>
105 * <td>average bit rate in bits per second</td>
106 * </tr>
107 * <tr>
108 * <td>"vbr"</td>
109 * <td>{@link java.lang.Boolean Boolean}</td>
110 * <td>{@code true}, if the file is encoded in variable bit
111 * rate (VBR)</td>
112 * </tr>
113 * <tr>
114 * <td>"quality"</td>
115 * <td>{@link java.lang.Integer Integer}</td>
116 * <td>encoding/conversion quality, 1..100</td>
117 * </tr>
118 * </tbody>
119 * </table>
120 * <p>
121 * Vendors of service providers (plugins) are encouraged to seek information
122 * about other already established properties in third party plugins, and follow
123 * the same conventions.
124 *
125 * @author Kara Kytle
126 * @author Florian Bomers
127 * @see DataLine#getFormat
128 * @see AudioInputStream#getFormat
129 * @see AudioFileFormat
130 * @see javax.sound.sampled.spi.FormatConversionProvider
131 * @since 1.3
132 */
133 public class AudioFormat {
134
135 /**
136 * The audio encoding technique used by this format.
137 */
166
167 /**
168 * Indicates whether the audio data is stored in big-endian or little-endian
169 * order.
170 */
171 protected boolean bigEndian;
172
173 /**
174 * The set of properties.
175 */
176 private HashMap<String, Object> properties;
177
178 /**
179 * Constructs an {@code AudioFormat} with the given parameters. The encoding
180 * specifies the convention used to represent the data. The other parameters
181 * are further explained in the {@link AudioFormat class description}.
182 *
183 * @param encoding the audio encoding technique
184 * @param sampleRate the number of samples per second
185 * @param sampleSizeInBits the number of bits in each sample
186 * @param channels the number of channels (1 for mono, 2 for stereo,
187 * and so on)
188 * @param frameSize the number of bytes in each frame
189 * @param frameRate the number of frames per second
190 * @param bigEndian indicates whether the data for a single sample is
191 * stored in big-endian byte order ({@code false} means
192 * little-endian)
193 */
194 public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits,
195 int channels, int frameSize, float frameRate, boolean bigEndian) {
196
197 this.encoding = encoding;
198 this.sampleRate = sampleRate;
199 this.sampleSizeInBits = sampleSizeInBits;
200 this.channels = channels;
201 this.frameSize = frameSize;
202 this.frameRate = frameRate;
203 this.bigEndian = bigEndian;
204 this.properties = null;
205 }
206
207 /**
208 * Constructs an {@code AudioFormat} with the given parameters. The encoding
209 * specifies the convention used to represent the data. The other parameters
210 * are further explained in the {@link AudioFormat class description}.
211 *
212 * @param encoding the audio encoding technique
213 * @param sampleRate the number of samples per second
214 * @param sampleSizeInBits the number of bits in each sample
215 * @param channels the number of channels (1 for mono, 2 for stereo, and so
216 * on)
217 * @param frameSize the number of bytes in each frame
218 * @param frameRate the number of frames per second
219 * @param bigEndian indicates whether the data for a single sample is
220 * stored in big-endian byte order ({@code false} means little-endian)
221 * @param properties a {@code Map<String, Object>} object containing format
222 * properties
223 * @since 1.5
224 */
225 public AudioFormat(Encoding encoding, float sampleRate,
226 int sampleSizeInBits, int channels,
227 int frameSize, float frameRate,
228 boolean bigEndian, Map<String, Object> properties) {
229 this(encoding, sampleRate, sampleSizeInBits, channels,
230 frameSize, frameRate, bigEndian);
231 this.properties = new HashMap<>(properties);
232 }
233
234 /**
235 * Constructs an {@code AudioFormat} with a linear PCM encoding and the
236 * given parameters. The frame size is set to the number of bytes required
237 * to contain one sample from each channel, and the frame rate is set to the
238 * sample rate.
239 *
240 * @param sampleRate the number of samples per second
259 sampleRate,
260 bigEndian);
261 }
262
263 /**
264 * Obtains the type of encoding for sounds in this format.
265 *
266 * @return the encoding type
267 * @see Encoding#PCM_SIGNED
268 * @see Encoding#PCM_UNSIGNED
269 * @see Encoding#ULAW
270 * @see Encoding#ALAW
271 */
272 public Encoding getEncoding() {
273
274 return encoding;
275 }
276
277 /**
278 * Obtains the sample rate. For compressed formats, the return value is the
279 * sample rate of the uncompressed audio data. When this AudioFormat is used
280 * for queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
281 * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
282 * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a sample rate
283 * of {@code AudioSystem.NOT_SPECIFIED} means that any sample rate is
284 * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
285 * sample rate is not defined for this audio format.
286 *
287 * @return the number of samples per second, or
288 * {@code AudioSystem.NOT_SPECIFIED}
289 * @see #getFrameRate()
290 * @see AudioSystem#NOT_SPECIFIED
291 */
292 public float getSampleRate() {
293
294 return sampleRate;
295 }
296
297 /**
298 * Obtains the size of a sample. For compressed formats, the return value is
299 * the sample size of the uncompressed audio data. When this AudioFormat is
300 * used for queries (e.g. {@link AudioSystem#isConversionSupported(
301 * AudioFormat,AudioFormat) AudioSystem.isConversionSupported}) or
302 * capabilities (e.g.
303 * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a sample size
304 * of {@code AudioSystem.NOT_SPECIFIED} means that any sample size is
305 * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
306 * sample size is not defined for this audio format.
307 *
308 * @return the number of bits in each sample, or
309 * {@code AudioSystem.NOT_SPECIFIED}
310 * @see #getFrameSize()
311 * @see AudioSystem#NOT_SPECIFIED
312 */
313 public int getSampleSizeInBits() {
314
315 return sampleSizeInBits;
316 }
317
318 /**
319 * Obtains the number of channels. When this AudioFormat is used for queries
320 * (e.g. {@link AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
321 * AudioSystem.isConversionSupported}) or capabilities (e.g.
322 * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a return
323 * value of {@code AudioSystem.NOT_SPECIFIED} means that any (positive)
324 * number of channels is acceptable.
325 *
326 * @return The number of channels (1 for mono, 2 for stereo, etc.), or
327 * {@code AudioSystem.NOT_SPECIFIED}
328 * @see AudioSystem#NOT_SPECIFIED
329 */
330 public int getChannels() {
331
332 return channels;
333 }
334
335 /**
336 * Obtains the frame size in bytes. When this AudioFormat is used for
337 * queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
338 * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
339 * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a frame size
340 * of {@code AudioSystem.NOT_SPECIFIED} means that any frame size is
341 * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
342 * frame size is not defined for this audio format.
343 *
344 * @return the number of bytes per frame, or
345 * {@code AudioSystem.NOT_SPECIFIED}
346 * @see #getSampleSizeInBits()
347 * @see AudioSystem#NOT_SPECIFIED
348 */
349 public int getFrameSize() {
350
351 return frameSize;
352 }
353
354 /**
355 * Obtains the frame rate in frames per second. When this AudioFormat is
356 * used for queries (e.g. {@link AudioSystem#isConversionSupported(
357 * AudioFormat,AudioFormat) AudioSystem.isConversionSupported}) or
358 * capabilities (e.g.
359 * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a frame rate
360 * of {@code AudioSystem.NOT_SPECIFIED} means that any frame rate is
361 * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
362 * frame rate is not defined for this audio format.
363 *
364 * @return the number of frames per second, or
365 * {@code AudioSystem.NOT_SPECIFIED}
366 * @see #getSampleRate()
367 * @see AudioSystem#NOT_SPECIFIED
368 */
369 public float getFrameRate() {
370
371 return frameRate;
372 }
373
374 /**
375 * Indicates whether the audio data is stored in big-endian or little-endian
376 * byte order. If the sample size is not more than one byte, the return
377 * value is irrelevant.
378 *
534 + sFrameRate
535 + sEndian;
536
537 }
538
539 /**
540 * The {@code Encoding} class names the specific type of data representation
541 * used for an audio stream. The encoding includes aspects of the sound
542 * format other than the number of channels, sample rate, sample size, frame
543 * rate, frame size, and byte order.
544 * <p>
545 * One ubiquitous type of audio encoding is pulse-code modulation (PCM),
546 * which is simply a linear (proportional) representation of the sound
547 * waveform. With PCM, the number stored in each sample is proportional to
548 * the instantaneous amplitude of the sound pressure at that point in time.
549 * The numbers may be signed or unsigned integers or floats. Besides PCM,
550 * other encodings include mu-law and a-law, which are nonlinear mappings of
551 * the sound amplitude that are often used for recording speech.
552 * <p>
553 * You can use a predefined encoding by referring to one of the static
554 * objects created by this class, such as PCM_SIGNED or PCM_UNSIGNED.
555 * Service providers can create new encodings, such as compressed audio
556 * formats, and make these available through the {@link AudioSystem} class.
557 * <p>
558 * The {@code Encoding} class is static, so that all {@code AudioFormat}
559 * objects that have the same encoding will refer to the same object (rather
560 * than different instances of the same class). This allows matches to be
561 * made by checking that two format's encodings are equal.
562 *
563 * @author Kara Kytle
564 * @see AudioFormat
565 * @see javax.sound.sampled.spi.FormatConversionProvider
566 * @since 1.3
567 */
568 public static class Encoding {
569
570 /**
571 * Specifies signed, linear PCM data.
572 */
573 public static final Encoding PCM_SIGNED = new Encoding("PCM_SIGNED");
574
575 /**
576 * Specifies unsigned, linear PCM data.
592 /**
593 * Specifies a-law encoded data.
594 */
595 public static final Encoding ALAW = new Encoding("ALAW");
596
597 /**
598 * Encoding name.
599 */
600 private final String name;
601
602 /**
603 * Constructs a new encoding.
604 *
605 * @param name the name of the new type of encoding
606 */
607 public Encoding(final String name) {
608 this.name = name;
609 }
610
611 /**
612 * Finalizes the equals method.
613 */
614 @Override
615 public final boolean equals(final Object obj) {
616 if (this == obj) {
617 return true;
618 }
619 if (!(obj instanceof Encoding)) {
620 return false;
621 }
622 return Objects.equals(name, ((Encoding) obj).name);
623 }
624
625 /**
626 * Finalizes the hashCode method.
627 */
628 @Override
629 public final int hashCode() {
630 return name != null ? name.hashCode() : 0;
631 }
632
633 /**
634 * Provides the {@code String} representation of the encoding. This
635 * {@code String} is the same name that was passed to the constructor.
636 * For the predefined encodings, the name is similar to the encoding's
637 * variable (field) name. For example, {@code PCM_SIGNED.toString()}
638 * returns the name "PCM_SIGNED".
639 *
640 * @return the encoding name
641 */
642 @Override
643 public final String toString() {
644 return name;
645 }
646 }
|
23 * questions.
24 */
25
26 package javax.sound.sampled;
27
28 import java.util.Collections;
29 import java.util.HashMap;
30 import java.util.Map;
31 import java.util.Objects;
32
33 /**
34 * {@code AudioFormat} is the class that specifies a particular arrangement of
35 * data in a sound stream. By examining the information stored in the audio
36 * format, you can discover how to interpret the bits in the binary sound data.
37 * <p>
38 * Every data line has an audio format associated with its data stream. The
39 * audio format of a source (playback) data line indicates what kind of data the
40 * data line expects to receive for output. For a target (capture) data line,
41 * the audio format specifies the kind of the data that can be read from the
42 * line.
43 * <p>
44 * Sound files also have audio formats, of course. The {@link AudioFileFormat}
45 * class encapsulates an {@code AudioFormat} in addition to other, file-specific
46 * information. Similarly, an {@link AudioInputStream} has an
47 * {@code AudioFormat}.
48 * <p>
49 * The {@code AudioFormat} class accommodates a number of common sound-file
50 * encoding techniques, including pulse-code modulation (PCM), mu-law encoding,
51 * and a-law encoding. These encoding techniques are predefined, but service
52 * providers can create new encoding types. The encoding that a specific format
53 * uses is named by its {@code encoding} field.
54 * <p>
55 * In addition to the encoding, the audio format includes other properties that
56 * further specify the exact arrangement of the data. These include the number
57 * of channels, sample rate, sample size, byte order, frame rate, and frame
58 * size. Sounds may have different numbers of audio channels: one for mono, two
59 * for stereo. The sample rate measures how many "snapshots" (samples) of the
60 * sound pressure are taken per second, per channel. (If the sound is stereo
61 * rather than mono, two samples are actually measured at each instant of time:
62 * one for the left channel, and another for the right channel; however, the
63 * sample rate still measures the number per channel, so the rate is the same
77 * <p>
78 * An {@code AudioFormat} object can include a set of properties. A property is
79 * a pair of key and value: the key is of type {@code String}, the associated
80 * property value is an arbitrary object. Properties specify additional format
81 * specifications, like the bit rate for compressed formats. Properties are
82 * mainly used as a means to transport additional information of the audio
83 * format to and from the service providers. Therefore, properties are ignored
84 * in the {@link #matches(AudioFormat)} method. However, methods which rely on
85 * the installed service providers, like
86 * {@link AudioSystem#isConversionSupported (AudioFormat, AudioFormat)
87 * isConversionSupported} may consider properties, depending on the respective
88 * service provider implementation.
89 * <p>
90 * The following table lists some common properties which service providers
91 * should use, if applicable:
92 *
93 * <table class="striped">
94 * <caption>Audio Format Properties</caption>
95 * <thead>
96 * <tr>
97 * <th>Property key
98 * <th>Value type
99 * <th>Description
100 * </thead>
101 * <tbody>
102 * <tr>
103 * <td>"bitrate"
104 * <td>{@link java.lang.Integer Integer}
105 * <td>average bit rate in bits per second
106 * <tr>
107 * <td>"vbr"
108 * <td>{@link java.lang.Boolean Boolean}
109 * <td>{@code true}, if the file is encoded in variable bit rate (VBR)
110 * <tr>
111 * <td>"quality"
112 * <td>{@link java.lang.Integer Integer}
113 * <td>encoding/conversion quality, 1..100
114 * </tbody>
115 * </table>
116 * <p>
117 * Vendors of service providers (plugins) are encouraged to seek information
118 * about other already established properties in third party plugins, and follow
119 * the same conventions.
120 *
121 * @author Kara Kytle
122 * @author Florian Bomers
123 * @see DataLine#getFormat
124 * @see AudioInputStream#getFormat
125 * @see AudioFileFormat
126 * @see javax.sound.sampled.spi.FormatConversionProvider
127 * @since 1.3
128 */
129 public class AudioFormat {
130
131 /**
132 * The audio encoding technique used by this format.
133 */
162
163 /**
164 * Indicates whether the audio data is stored in big-endian or little-endian
165 * order.
166 */
167 protected boolean bigEndian;
168
169 /**
170 * The set of properties.
171 */
172 private HashMap<String, Object> properties;
173
174 /**
175 * Constructs an {@code AudioFormat} with the given parameters. The encoding
176 * specifies the convention used to represent the data. The other parameters
177 * are further explained in the {@link AudioFormat class description}.
178 *
179 * @param encoding the audio encoding technique
180 * @param sampleRate the number of samples per second
181 * @param sampleSizeInBits the number of bits in each sample
182 * @param channels the number of channels (1 for mono, 2 for stereo, and so
183 * on)
184 * @param frameSize the number of bytes in each frame
185 * @param frameRate the number of frames per second
186 * @param bigEndian indicates whether the data for a single sample is
187 * stored in big-endian byte order ({@code false} means
188 * little-endian)
189 */
190 public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits,
191 int channels, int frameSize, float frameRate, boolean bigEndian) {
192
193 this.encoding = encoding;
194 this.sampleRate = sampleRate;
195 this.sampleSizeInBits = sampleSizeInBits;
196 this.channels = channels;
197 this.frameSize = frameSize;
198 this.frameRate = frameRate;
199 this.bigEndian = bigEndian;
200 this.properties = null;
201 }
202
203 /**
204 * Constructs an {@code AudioFormat} with the given parameters. The encoding
205 * specifies the convention used to represent the data. The other parameters
206 * are further explained in the {@link AudioFormat class description}.
207 *
208 * @param encoding the audio encoding technique
209 * @param sampleRate the number of samples per second
210 * @param sampleSizeInBits the number of bits in each sample
211 * @param channels the number of channels (1 for mono, 2 for stereo, and so
212 * on)
213 * @param frameSize the number of bytes in each frame
214 * @param frameRate the number of frames per second
215 * @param bigEndian indicates whether the data for a single sample is
216 * stored in big-endian byte order ({@code false} means
217 * little-endian)
218 * @param properties a {@code Map<String, Object>} object containing format
219 * properties
220 * @since 1.5
221 */
222 public AudioFormat(Encoding encoding, float sampleRate,
223 int sampleSizeInBits, int channels,
224 int frameSize, float frameRate,
225 boolean bigEndian, Map<String, Object> properties) {
226 this(encoding, sampleRate, sampleSizeInBits, channels,
227 frameSize, frameRate, bigEndian);
228 this.properties = new HashMap<>(properties);
229 }
230
231 /**
232 * Constructs an {@code AudioFormat} with a linear PCM encoding and the
233 * given parameters. The frame size is set to the number of bytes required
234 * to contain one sample from each channel, and the frame rate is set to the
235 * sample rate.
236 *
237 * @param sampleRate the number of samples per second
256 sampleRate,
257 bigEndian);
258 }
259
260 /**
261 * Obtains the type of encoding for sounds in this format.
262 *
263 * @return the encoding type
264 * @see Encoding#PCM_SIGNED
265 * @see Encoding#PCM_UNSIGNED
266 * @see Encoding#ULAW
267 * @see Encoding#ALAW
268 */
269 public Encoding getEncoding() {
270
271 return encoding;
272 }
273
274 /**
275 * Obtains the sample rate. For compressed formats, the return value is the
276 * sample rate of the uncompressed audio data. When this {@code AudioFormat}
277 * is used for queries (e.g.
278 * {@link AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
279 * AudioSystem.isConversionSupported}) or capabilities (e.g.
280 * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a sample rate
281 * of {@code AudioSystem.NOT_SPECIFIED} means that any sample rate is
282 * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
283 * sample rate is not defined for this audio format.
284 *
285 * @return the number of samples per second, or
286 * {@code AudioSystem.NOT_SPECIFIED}
287 * @see #getFrameRate()
288 * @see AudioSystem#NOT_SPECIFIED
289 */
290 public float getSampleRate() {
291
292 return sampleRate;
293 }
294
295 /**
296 * Obtains the size of a sample. For compressed formats, the return value is
297 * the sample size of the uncompressed audio data. When this
298 * {@code AudioFormat} is used for queries (e.g.
299 * {@link AudioSystem#isConversionSupported(AudioFormat,AudioFormat)
300 * AudioSystem.isConversionSupported}) or capabilities (e.g.
301 * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a sample size
302 * of {@code AudioSystem.NOT_SPECIFIED} means that any sample size is
303 * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
304 * sample size is not defined for this audio format.
305 *
306 * @return the number of bits in each sample, or
307 * {@code AudioSystem.NOT_SPECIFIED}
308 * @see #getFrameSize()
309 * @see AudioSystem#NOT_SPECIFIED
310 */
311 public int getSampleSizeInBits() {
312
313 return sampleSizeInBits;
314 }
315
316 /**
317 * Obtains the number of channels. When this {@code AudioFormat} is used for
318 * queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
319 * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
320 * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a return
321 * value of {@code AudioSystem.NOT_SPECIFIED} means that any (positive)
322 * number of channels is acceptable.
323 *
324 * @return The number of channels (1 for mono, 2 for stereo, etc.), or
325 * {@code AudioSystem.NOT_SPECIFIED}
326 * @see AudioSystem#NOT_SPECIFIED
327 */
328 public int getChannels() {
329
330 return channels;
331 }
332
333 /**
334 * Obtains the frame size in bytes. When this {@code AudioFormat} is used
335 * for queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
336 * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
337 * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a frame size
338 * of {@code AudioSystem.NOT_SPECIFIED} means that any frame size is
339 * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
340 * frame size is not defined for this audio format.
341 *
342 * @return the number of bytes per frame, or
343 * {@code AudioSystem.NOT_SPECIFIED}
344 * @see #getSampleSizeInBits()
345 * @see AudioSystem#NOT_SPECIFIED
346 */
347 public int getFrameSize() {
348
349 return frameSize;
350 }
351
352 /**
353 * Obtains the frame rate in frames per second. When this
354 * {@code AudioFormat} is used for queries (e.g.
355 * {@link AudioSystem#isConversionSupported(AudioFormat,AudioFormat)
356 * AudioSystem.isConversionSupported}) or capabilities (e.g.
357 * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a frame rate
358 * of {@code AudioSystem.NOT_SPECIFIED} means that any frame rate is
359 * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
360 * frame rate is not defined for this audio format.
361 *
362 * @return the number of frames per second, or
363 * {@code AudioSystem.NOT_SPECIFIED}
364 * @see #getSampleRate()
365 * @see AudioSystem#NOT_SPECIFIED
366 */
367 public float getFrameRate() {
368
369 return frameRate;
370 }
371
372 /**
373 * Indicates whether the audio data is stored in big-endian or little-endian
374 * byte order. If the sample size is not more than one byte, the return
375 * value is irrelevant.
376 *
532 + sFrameRate
533 + sEndian;
534
535 }
536
537 /**
538 * The {@code Encoding} class names the specific type of data representation
539 * used for an audio stream. The encoding includes aspects of the sound
540 * format other than the number of channels, sample rate, sample size, frame
541 * rate, frame size, and byte order.
542 * <p>
543 * One ubiquitous type of audio encoding is pulse-code modulation (PCM),
544 * which is simply a linear (proportional) representation of the sound
545 * waveform. With PCM, the number stored in each sample is proportional to
546 * the instantaneous amplitude of the sound pressure at that point in time.
547 * The numbers may be signed or unsigned integers or floats. Besides PCM,
548 * other encodings include mu-law and a-law, which are nonlinear mappings of
549 * the sound amplitude that are often used for recording speech.
550 * <p>
551 * You can use a predefined encoding by referring to one of the static
552 * objects created by this class, such as {@code PCM_SIGNED} or
553 * {@code PCM_UNSIGNED}. Service providers can create new encodings, such as
554 * compressed audio formats, and make these available through the
555 * {@link AudioSystem} class.
556 * <p>
557 * The {@code Encoding} class is static, so that all {@code AudioFormat}
558 * objects that have the same encoding will refer to the same object (rather
559 * than different instances of the same class). This allows matches to be
560 * made by checking that two format's encodings are equal.
561 *
562 * @author Kara Kytle
563 * @see AudioFormat
564 * @see javax.sound.sampled.spi.FormatConversionProvider
565 * @since 1.3
566 */
567 public static class Encoding {
568
569 /**
570 * Specifies signed, linear PCM data.
571 */
572 public static final Encoding PCM_SIGNED = new Encoding("PCM_SIGNED");
573
574 /**
575 * Specifies unsigned, linear PCM data.
591 /**
592 * Specifies a-law encoded data.
593 */
594 public static final Encoding ALAW = new Encoding("ALAW");
595
596 /**
597 * Encoding name.
598 */
599 private final String name;
600
601 /**
602 * Constructs a new encoding.
603 *
604 * @param name the name of the new type of encoding
605 */
606 public Encoding(final String name) {
607 this.name = name;
608 }
609
610 /**
611 * Indicates whether the specified object is equal to this encoding,
612 * returning {@code true} if the objects are the same.
613 *
614 * @param obj the reference object with which to compare
615 * @return {@code true} if this encoding is the same as the {@code obj}
616 * argument; {@code false} otherwise
617 */
618 @Override
619 public final boolean equals(final Object obj) {
620 if (this == obj) {
621 return true;
622 }
623 if (!(obj instanceof Encoding)) {
624 return false;
625 }
626 return Objects.equals(name, ((Encoding) obj).name);
627 }
628
629 /**
630 * Returns a hash code value for this encoding.
631 *
632 * @return a hash code value for this encoding
633 */
634 @Override
635 public final int hashCode() {
636 return name != null ? name.hashCode() : 0;
637 }
638
639 /**
640 * Provides the {@code String} representation of the encoding. This
641 * {@code String} is the same name that was passed to the constructor.
642 * For the predefined encodings, the name is similar to the encoding's
643 * variable (field) name. For example, {@code PCM_SIGNED.toString()}
644 * returns the name "PCM_SIGNED".
645 *
646 * @return the encoding name
647 */
648 @Override
649 public final String toString() {
650 return name;
651 }
652 }
|