View Javadoc
1   /*
2    * Copyright (c) 1999, 2013, 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.sampled;
27  
28  import java.util.Collections;
29  import java.util.HashMap;
30  import java.util.Map;
31  
32  /**
33   * <code>AudioFormat</code> is the class that specifies a particular arrangement of data in a sound stream.
34   * By examining the information stored in the audio format, you can discover how to interpret the bits in the
35   * binary sound data.
36   * <p>
37   * Every data line has an audio format associated with its data stream. The audio format of a source (playback) data line indicates
38   * what kind of data the data line expects to receive for output.  For a target (capture) data line, the audio format specifies the kind
39   * of the data that can be read from the line.
40   * Sound files also have audio formats, of course.  The <code>{@link AudioFileFormat}</code>
41   * class encapsulates an <code>AudioFormat</code> in addition to other,
42   * file-specific information.  Similarly, an <code>{@link AudioInputStream}</code> has an
43   * <code>AudioFormat</code>.
44   * <p>
45   * The <code>AudioFormat</code> class accommodates a number of common sound-file encoding techniques, including
46   * pulse-code modulation (PCM), mu-law encoding, and a-law encoding.  These encoding techniques are predefined,
47   * but service providers can create new encoding types.
48   * The encoding that a specific format uses is named by its <code>encoding</code> field.
49   *<p>
50   * In addition to the encoding, the audio format includes other properties that further specify the exact
51   * arrangement of the data.
52   * These include the number of channels, sample rate, sample size, byte order, frame rate, and frame size.
53   * Sounds may have different numbers of audio channels: one for mono, two for stereo.
54   * The sample rate measures how many "snapshots" (samples) of the sound pressure are taken per second, per channel.
55   * (If the sound is stereo rather than mono, two samples are actually measured at each instant of time: one for the left channel,
56   * and another for the right channel; however, the sample rate still measures the number per channel, so the rate is the same
57   * regardless of the number of channels.   This is the standard use of the term.)
58   * The sample size indicates how many bits are used to store each snapshot; 8 and 16 are typical values.
59   * For 16-bit samples (or any other sample size larger than a byte),
60   * byte order is important; the bytes in each sample are arranged in
61   * either the "little-endian" or "big-endian" style.
62   * For encodings like PCM, a frame consists of the set of samples for all channels at a given
63   * point in time, and so the size of a frame (in bytes) is always equal to the size of a sample (in bytes) times
64   * the number of channels.  However, with some other sorts of encodings a frame can contain
65   * a bundle of compressed data for a whole series of samples, as well as additional, non-sample
66   * data.  For such encodings, the sample rate and sample size refer to the data after it is decoded into PCM,
67   * and so they are completely different from the frame rate and frame size.
68   *
69   * <p>An <code>AudioFormat</code> object can include a set of
70   * properties. A property is a pair of key and value: the key
71   * is of type <code>String</code>, the associated property
72   * value is an arbitrary object. Properties specify
73   * additional format specifications, like the bit rate for
74   * compressed formats. Properties are mainly used as a means
75   * to transport additional information of the audio format
76   * to and from the service providers. Therefore, properties
77   * are ignored in the {@link #matches(AudioFormat)} method.
78   * However, methods which rely on the installed service
79   * providers, like {@link AudioSystem#isConversionSupported
80   * (AudioFormat, AudioFormat) isConversionSupported} may consider
81   * properties, depending on the respective service provider
82   * implementation.
83   *
84   * <p>The following table lists some common properties which
85   * service providers should use, if applicable:
86   *
87   * <table border=0>
88   *  <caption>Audio Format Properties</caption>
89   *  <tr>
90   *   <th>Property key</th>
91   *   <th>Value type</th>
92   *   <th>Description</th>
93   *  </tr>
94   *  <tr>
95   *   <td>&quot;bitrate&quot;</td>
96   *   <td>{@link java.lang.Integer Integer}</td>
97   *   <td>average bit rate in bits per second</td>
98   *  </tr>
99   *  <tr>
100  *   <td>&quot;vbr&quot;</td>
101  *   <td>{@link java.lang.Boolean Boolean}</td>
102  *   <td><code>true</code>, if the file is encoded in variable bit
103  *       rate (VBR)</td>
104  *  </tr>
105  *  <tr>
106  *   <td>&quot;quality&quot;</td>
107  *   <td>{@link java.lang.Integer Integer}</td>
108  *   <td>encoding/conversion quality, 1..100</td>
109  *  </tr>
110  * </table>
111  *
112  * <p>Vendors of service providers (plugins) are encouraged
113  * to seek information about other already established
114  * properties in third party plugins, and follow the same
115  * conventions.
116  *
117  * @author Kara Kytle
118  * @author Florian Bomers
119  * @see DataLine#getFormat
120  * @see AudioInputStream#getFormat
121  * @see AudioFileFormat
122  * @see javax.sound.sampled.spi.FormatConversionProvider
123  * @since 1.3
124  */
125 public class AudioFormat {
126 
127     // INSTANCE VARIABLES
128 
129 
130     /**
131      * The audio encoding technique used by this format.
132      */
133     protected Encoding encoding;
134 
135     /**
136      * The number of samples played or recorded per second, for sounds that have this format.
137      */
138     protected float sampleRate;
139 
140     /**
141      * The number of bits in each sample of a sound that has this format.
142      */
143     protected int sampleSizeInBits;
144 
145     /**
146      * The number of audio channels in this format (1 for mono, 2 for stereo).
147      */
148     protected int channels;
149 
150     /**
151      * The number of bytes in each frame of a sound that has this format.
152      */
153     protected int frameSize;
154 
155     /**
156      * The number of frames played or recorded per second, for sounds that have this format.
157      */
158     protected float frameRate;
159 
160     /**
161      * Indicates whether the audio data is stored in big-endian or little-endian order.
162      */
163     protected boolean bigEndian;
164 
165 
166     /** The set of properties */
167     private HashMap<String, Object> properties;
168 
169 
170     /**
171      * Constructs an <code>AudioFormat</code> with the given parameters.
172      * The encoding specifies the convention used to represent the data.
173      * The other parameters are further explained in the {@link AudioFormat
174      * class description}.
175      * @param encoding                  the audio encoding technique
176      * @param sampleRate                the number of samples per second
177      * @param sampleSizeInBits  the number of bits in each sample
178      * @param channels                  the number of channels (1 for mono, 2 for stereo, and so on)
179      * @param frameSize                 the number of bytes in each frame
180      * @param frameRate                 the number of frames per second
181      * @param bigEndian                 indicates whether the data for a single sample
182      *                                                  is stored in big-endian byte order (<code>false</code>
183      *                                                  means little-endian)
184      */
185     public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits,
186                        int channels, int frameSize, float frameRate, boolean bigEndian) {
187 
188         this.encoding = encoding;
189         this.sampleRate = sampleRate;
190         this.sampleSizeInBits = sampleSizeInBits;
191         this.channels = channels;
192         this.frameSize = frameSize;
193         this.frameRate = frameRate;
194         this.bigEndian = bigEndian;
195         this.properties = null;
196     }
197 
198 
199     /**
200      * Constructs an <code>AudioFormat</code> with the given parameters.
201      * The encoding specifies the convention used to represent the data.
202      * The other parameters are further explained in the {@link AudioFormat
203      * class description}.
204      * @param encoding         the audio encoding technique
205      * @param sampleRate       the number of samples per second
206      * @param sampleSizeInBits the number of bits in each sample
207      * @param channels         the number of channels (1 for mono, 2 for
208      *                         stereo, and so on)
209      * @param frameSize        the number of bytes in each frame
210      * @param frameRate        the number of frames per second
211      * @param bigEndian        indicates whether the data for a single sample
212      *                         is stored in big-endian byte order
213      *                         (<code>false</code> means little-endian)
214      * @param properties       a <code>Map&lt;String,Object&gt;</code> object
215      *                         containing format properties
216      *
217      * @since 1.5
218      */
219     public AudioFormat(Encoding encoding, float sampleRate,
220                        int sampleSizeInBits, int channels,
221                        int frameSize, float frameRate,
222                        boolean bigEndian, Map<String, Object> properties) {
223         this(encoding, sampleRate, sampleSizeInBits, channels,
224              frameSize, frameRate, bigEndian);
225         this.properties = new HashMap<String, Object>(properties);
226     }
227 
228 
229     /**
230      * Constructs an <code>AudioFormat</code> with a linear PCM encoding and
231      * the given parameters.  The frame size is set to the number of bytes
232      * required to contain one sample from each channel, and the frame rate
233      * is set to the sample rate.
234      *
235      * @param sampleRate                the number of samples per second
236      * @param sampleSizeInBits  the number of bits in each sample
237      * @param channels                  the number of channels (1 for mono, 2 for stereo, and so on)
238      * @param signed                    indicates whether the data is signed or unsigned
239      * @param bigEndian                 indicates whether the data for a single sample
240      *                                                  is stored in big-endian byte order (<code>false</code>
241      *                                                  means little-endian)
242      */
243     public AudioFormat(float sampleRate, int sampleSizeInBits,
244                        int channels, boolean signed, boolean bigEndian) {
245 
246         this((signed == true ? Encoding.PCM_SIGNED : Encoding.PCM_UNSIGNED),
247              sampleRate,
248              sampleSizeInBits,
249              channels,
250              (channels == AudioSystem.NOT_SPECIFIED || sampleSizeInBits == AudioSystem.NOT_SPECIFIED)?
251              AudioSystem.NOT_SPECIFIED:
252              ((sampleSizeInBits + 7) / 8) * channels,
253              sampleRate,
254              bigEndian);
255     }
256 
257     /**
258      * Obtains the type of encoding for sounds in this format.
259      *
260      * @return the encoding type
261      * @see Encoding#PCM_SIGNED
262      * @see Encoding#PCM_UNSIGNED
263      * @see Encoding#ULAW
264      * @see Encoding#ALAW
265      */
266     public Encoding getEncoding() {
267 
268         return encoding;
269     }
270 
271     /**
272      * Obtains the sample rate.
273      * For compressed formats, the return value is the sample rate of the uncompressed
274      * audio data.
275      * When this AudioFormat is used for queries (e.g. {@link
276      * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
277      * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
278      * DataLine.Info#getFormats() DataLine.Info.getFormats}), a sample rate of
279      * <code>AudioSystem.NOT_SPECIFIED</code> means that any sample rate is
280      * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
281      * the sample rate is not defined for this audio format.
282      * @return the number of samples per second,
283      * or <code>AudioSystem.NOT_SPECIFIED</code>
284      *
285      * @see #getFrameRate()
286      * @see AudioSystem#NOT_SPECIFIED
287      */
288     public float getSampleRate() {
289 
290         return sampleRate;
291     }
292 
293     /**
294      * Obtains the size of a sample.
295      * For compressed formats, the return value is the sample size of the
296      * uncompressed audio data.
297      * When this AudioFormat is used for queries (e.g. {@link
298      * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
299      * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
300      * DataLine.Info#getFormats() DataLine.Info.getFormats}), a sample size of
301      * <code>AudioSystem.NOT_SPECIFIED</code> means that any sample size is
302      * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
303      * the sample size is not defined for this audio format.
304      * @return the number of bits in each sample,
305      * or <code>AudioSystem.NOT_SPECIFIED</code>
306      *
307      * @see #getFrameSize()
308      * @see AudioSystem#NOT_SPECIFIED
309      */
310     public int getSampleSizeInBits() {
311 
312         return sampleSizeInBits;
313     }
314 
315     /**
316      * Obtains the number of channels.
317      * When this AudioFormat is used for queries (e.g. {@link
318      * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
319      * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
320      * DataLine.Info#getFormats() DataLine.Info.getFormats}), a return value of
321      * <code>AudioSystem.NOT_SPECIFIED</code> means that any (positive) number of channels is
322      * acceptable.
323      * @return The number of channels (1 for mono, 2 for stereo, etc.),
324      * or <code>AudioSystem.NOT_SPECIFIED</code>
325      *
326      * @see AudioSystem#NOT_SPECIFIED
327      */
328     public int getChannels() {
329 
330         return channels;
331     }
332 
333     /**
334      * Obtains the frame size in bytes.
335      * When this AudioFormat is used for queries (e.g. {@link
336      * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
337      * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
338      * DataLine.Info#getFormats() DataLine.Info.getFormats}), a frame size of
339      * <code>AudioSystem.NOT_SPECIFIED</code> means that any frame size is
340      * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
341      * the frame size is not defined for this audio format.
342      * @return the number of bytes per frame,
343      * or <code>AudioSystem.NOT_SPECIFIED</code>
344      *
345      * @see #getSampleSizeInBits()
346      * @see AudioSystem#NOT_SPECIFIED
347      */
348     public int getFrameSize() {
349 
350         return frameSize;
351     }
352 
353     /**
354      * Obtains the frame rate in frames per second.
355      * When this AudioFormat is used for queries (e.g. {@link
356      * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
357      * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
358      * DataLine.Info#getFormats() DataLine.Info.getFormats}), a frame rate of
359      * <code>AudioSystem.NOT_SPECIFIED</code> means that any frame rate is
360      * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
361      * the frame rate is not defined for this audio format.
362      * @return the number of frames per second,
363      * or <code>AudioSystem.NOT_SPECIFIED</code>
364      *
365      * @see #getSampleRate()
366      * @see AudioSystem#NOT_SPECIFIED
367      */
368     public float getFrameRate() {
369 
370         return frameRate;
371     }
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 value is
377      * irrelevant.
378      * @return <code>true</code> if the data is stored in big-endian byte order,
379      * <code>false</code> if little-endian
380      */
381     public boolean isBigEndian() {
382 
383         return bigEndian;
384     }
385 
386 
387     /**
388      * Obtain an unmodifiable map of properties.
389      * The concept of properties is further explained in
390      * the {@link AudioFileFormat class description}.
391      *
392      * @return a <code>Map&lt;String,Object&gt;</code> object containing
393      *         all properties. If no properties are recognized, an empty map is
394      *         returned.
395      *
396      * @see #getProperty(String)
397      * @since 1.5
398      */
399     public Map<String,Object> properties() {
400         Map<String,Object> ret;
401         if (properties == null) {
402             ret = new HashMap<String,Object>(0);
403         } else {
404             ret = (Map<String,Object>) (properties.clone());
405         }
406         return (Map<String,Object>) Collections.unmodifiableMap(ret);
407     }
408 
409 
410     /**
411      * Obtain the property value specified by the key.
412      * The concept of properties is further explained in
413      * the {@link AudioFileFormat class description}.
414      *
415      * <p>If the specified property is not defined for a
416      * particular file format, this method returns
417      * <code>null</code>.
418      *
419      * @param key the key of the desired property
420      * @return the value of the property with the specified key,
421      *         or <code>null</code> if the property does not exist.
422      *
423      * @see #properties()
424      * @since 1.5
425      */
426     public Object getProperty(String key) {
427         if (properties == null) {
428             return null;
429         }
430         return properties.get(key);
431     }
432 
433 
434     /**
435      * Indicates whether this format matches the one specified.
436      * To match, two formats must have the same encoding,
437      * and consistent values of the number of channels, sample rate, sample size,
438      * frame rate, and frame size.
439      * The values of the property are consistent if they are equal
440      * or the specified format has the property value
441      * {@code AudioSystem.NOT_SPECIFIED}.
442      * The byte order (big-endian or little-endian) must be the same
443      * if the sample size is greater than one byte.
444      *
445      * @param format format to test for match
446      * @return {@code true} if this format matches the one specified,
447      *         {@code false} otherwise.
448      */
449     public boolean matches(AudioFormat format) {
450         if (format.getEncoding().equals(getEncoding())
451                 && (format.getChannels() == AudioSystem.NOT_SPECIFIED
452                     || format.getChannels() == getChannels())
453                 && (format.getSampleRate() == (float)AudioSystem.NOT_SPECIFIED
454                     || format.getSampleRate() == getSampleRate())
455                 && (format.getSampleSizeInBits() == AudioSystem.NOT_SPECIFIED
456                     || format.getSampleSizeInBits() == getSampleSizeInBits())
457                 && (format.getFrameRate() == (float)AudioSystem.NOT_SPECIFIED
458                     || format.getFrameRate() == getFrameRate())
459                 && (format.getFrameSize() == AudioSystem.NOT_SPECIFIED
460                     || format.getFrameSize() == getFrameSize())
461                 && (getSampleSizeInBits() <= 8
462                     || format.isBigEndian() == isBigEndian())) {
463             return true;
464         }
465         return false;
466     }
467 
468 
469     /**
470      * Returns a string that describes the format, such as:
471      * "PCM SIGNED 22050 Hz 16 bit mono big-endian".  The contents of the string
472      * may vary between implementations of Java Sound.
473      *
474      * @return a string that describes the format parameters
475      */
476     public String toString() {
477         String sEncoding = "";
478         if (getEncoding() != null) {
479             sEncoding = getEncoding().toString() + " ";
480         }
481 
482         String sSampleRate;
483         if (getSampleRate() == (float) AudioSystem.NOT_SPECIFIED) {
484             sSampleRate = "unknown sample rate, ";
485         } else {
486             sSampleRate = "" + getSampleRate() + " Hz, ";
487         }
488 
489         String sSampleSizeInBits;
490         if (getSampleSizeInBits() == (float) AudioSystem.NOT_SPECIFIED) {
491             sSampleSizeInBits = "unknown bits per sample, ";
492         } else {
493             sSampleSizeInBits = "" + getSampleSizeInBits() + " bit, ";
494         }
495 
496         String sChannels;
497         if (getChannels() == 1) {
498             sChannels = "mono, ";
499         } else
500             if (getChannels() == 2) {
501                 sChannels = "stereo, ";
502             } else {
503                 if (getChannels() == AudioSystem.NOT_SPECIFIED) {
504                     sChannels = " unknown number of channels, ";
505                 } else {
506                     sChannels = ""+getChannels()+" channels, ";
507                 }
508             }
509 
510         String sFrameSize;
511         if (getFrameSize() == (float) AudioSystem.NOT_SPECIFIED) {
512             sFrameSize = "unknown frame size, ";
513         } else {
514             sFrameSize = "" + getFrameSize()+ " bytes/frame, ";
515         }
516 
517         String sFrameRate = "";
518         if (Math.abs(getSampleRate() - getFrameRate()) > 0.00001) {
519             if (getFrameRate() == (float) AudioSystem.NOT_SPECIFIED) {
520                 sFrameRate = "unknown frame rate, ";
521             } else {
522                 sFrameRate = getFrameRate() + " frames/second, ";
523             }
524         }
525 
526         String sEndian = "";
527         if ((getEncoding().equals(Encoding.PCM_SIGNED)
528              || getEncoding().equals(Encoding.PCM_UNSIGNED))
529             && ((getSampleSizeInBits() > 8)
530                 || (getSampleSizeInBits() == AudioSystem.NOT_SPECIFIED))) {
531             if (isBigEndian()) {
532                 sEndian = "big-endian";
533             } else {
534                 sEndian = "little-endian";
535             }
536         }
537 
538         return sEncoding
539             + sSampleRate
540             + sSampleSizeInBits
541             + sChannels
542             + sFrameSize
543             + sFrameRate
544             + sEndian;
545 
546     }
547 
548     /**
549      * The <code>Encoding</code> class  names the  specific type of data representation
550      * used for an audio stream.   The encoding includes aspects of the
551      * sound format other than the number of channels, sample rate, sample size,
552      * frame rate, frame size, and byte order.
553      * <p>
554      * One ubiquitous type of audio encoding is pulse-code modulation (PCM),
555      * which is simply a linear (proportional) representation of the sound
556      * waveform.  With PCM, the number stored in each sample is proportional
557      * to the instantaneous amplitude of the sound pressure at that point in
558      * time.  The numbers may be signed or unsigned integers or floats.
559      * Besides PCM, other encodings include mu-law and a-law, which are nonlinear
560      * mappings of the sound amplitude that are often used for recording speech.
561      * <p>
562      * You can use a predefined encoding by referring to one of the static
563      * objects created by this class, such as PCM_SIGNED or
564      * PCM_UNSIGNED.  Service providers can create new encodings, such as
565      * compressed audio formats, and make
566      * these available through the <code>{@link AudioSystem}</code> class.
567      * <p>
568      * The <code>Encoding</code> class is static, so that all
569      * <code>AudioFormat</code> objects that have the same encoding will refer
570      * to the same object (rather than different instances of the same class).
571      * This allows matches to be made by checking that two format's encodings
572      * are equal.
573      *
574      * @see AudioFormat
575      * @see javax.sound.sampled.spi.FormatConversionProvider
576      *
577      * @author Kara Kytle
578      * @since 1.3
579      */
580     public static class Encoding {
581 
582 
583         // ENCODING DEFINES
584 
585         /**
586          * Specifies signed, linear PCM data.
587          */
588         public static final Encoding PCM_SIGNED = new Encoding("PCM_SIGNED");
589 
590         /**
591          * Specifies unsigned, linear PCM data.
592          */
593         public static final Encoding PCM_UNSIGNED = new Encoding("PCM_UNSIGNED");
594 
595         /**
596          * Specifies floating-point PCM data.
597          *
598          * @since 1.7
599          */
600         public static final Encoding PCM_FLOAT = new Encoding("PCM_FLOAT");
601 
602         /**
603          * Specifies u-law encoded data.
604          */
605         public static final Encoding ULAW = new Encoding("ULAW");
606 
607         /**
608          * Specifies a-law encoded data.
609          */
610         public static final Encoding ALAW = new Encoding("ALAW");
611 
612 
613         // INSTANCE VARIABLES
614 
615         /**
616          * Encoding name.
617          */
618         private String name;
619 
620 
621         // CONSTRUCTOR
622 
623         /**
624          * Constructs a new encoding.
625          * @param name  the name of the new type of encoding
626          */
627         public Encoding(String name) {
628             this.name = name;
629         }
630 
631 
632         // METHODS
633 
634         /**
635          * Finalizes the equals method
636          */
637         public final boolean equals(Object obj) {
638             if (toString() == null) {
639                 return (obj != null) && (obj.toString() == null);
640             }
641             if (obj instanceof Encoding) {
642                 return toString().equals(obj.toString());
643             }
644             return false;
645         }
646 
647         /**
648          * Finalizes the hashCode method
649          */
650         public final int hashCode() {
651             if (toString() == null) {
652                 return 0;
653             }
654             return toString().hashCode();
655         }
656 
657         /**
658          * Provides the <code>String</code> representation of the encoding.  This <code>String</code> is
659          * the same name that was passed to the constructor.  For the predefined encodings, the name
660          * is similar to the encoding's variable (field) name.  For example, <code>PCM_SIGNED.toString()</code> returns
661          * the name "pcm_signed".
662          *
663          * @return the encoding name
664          */
665         public final String toString() {
666             return name;
667         }
668 
669     } // class Encoding
670 }