001    /* An audio format
002       Copyright (C) 2005 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.sound.sampled;
040    
041    import gnu.java.lang.CPStringBuilder;
042    
043    import java.util.Collections;
044    import java.util.HashMap;
045    import java.util.Map;
046    
047    /**
048     * This class describes an audio format, including its encoding,
049     * the number of channels, its frame rate, etc.
050     * @since 1.3
051     */
052    public class AudioFormat
053    {
054      /**
055       * This describes a given audio format encoding.
056       * @since 1.3
057       */
058      public static class Encoding
059      {
060        /** The ALAW encoding.  */
061        public static final Encoding ALAW = new Encoding("alaw");
062    
063        /** The signed PCM encoding.  */
064        public static final Encoding PCM_SIGNED = new Encoding("pcm_signed");
065    
066        /** The unsigned PCM encoding.  */
067        public static final Encoding PCM_UNSIGNED = new Encoding("pcm_unsigned");
068    
069        /** The ULAW encoding.  */
070        public static final Encoding ULAW = new Encoding("ulaw");
071    
072        private String name;
073    
074        /**
075         * Create a new encoding descriptor, given its name.
076         * @param name the name
077         */
078        public Encoding(String name)
079        {
080          this.name = name;
081        }
082    
083        public final boolean equals(Object o)
084        {
085          return super.equals(o);
086        }
087    
088        public final int hashCode()
089        {
090          return super.hashCode();
091        }
092    
093        /**
094         * Return the name of this encoding.
095         */
096        public final String toString()
097        {
098          return name;
099        }
100      }
101    
102      /**
103       * True if the audio data is stored big-endian.
104       */
105      protected boolean bigEndian;
106    
107      /**
108       * The number of channels of data in this format.
109       */
110      protected int channels;
111    
112      /**
113       * The encoding of this format.
114       */
115      protected Encoding encoding;
116    
117      /**
118       * The frame rate of this format.  This is the number of frames
119       * per second.
120       */
121      protected float frameRate;
122    
123      /**
124       * The number of bytes per frame in this format.
125       */
126      protected int frameSize;
127    
128      /**
129       * The number of samples per second.
130       */
131      protected float sampleRate;
132    
133      /**
134       * The number of bits in each sample.
135       */
136      protected int sampleSizeInBits;
137    
138      private Map<String, Object> properties;
139    
140      /**
141       * Create a new audio format, given various attributes of it.
142       * The properties map for this format will be empty.
143       * 
144       * @param encoding the encoding for this format
145       * @param sampleRate the sample rate
146       * @param sampleSizeInBits the sample size, in bits
147       * @param channels the number of channels
148       * @param frameSize the frame size, in bytes
149       * @param frameRate the frame rate, in frames per second
150       * @param bigEndian true if the data is stored big-endian
151       */
152      public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits,
153                         int channels, int frameSize, float frameRate,
154                         boolean bigEndian)
155      {
156        this.encoding = encoding;
157        this.sampleRate = sampleRate;
158        this.sampleSizeInBits = sampleSizeInBits;
159        this.channels = channels;
160        this.frameSize = frameSize;
161        this.frameRate = frameRate;
162        this.bigEndian = bigEndian;
163        this.properties = Collections.<String, Object> emptyMap();
164      }
165    
166      /**
167       * Create a new audio format, given various attributes of it.
168       * The properties map is copied by this constructor, so changes
169       * to the argument Map will not affect the new object.
170       *
171       * @param encoding the encoding for this format
172       * @param sampleRate the sample rate
173       * @param sampleSizeInBits the sample size, in bits
174       * @param channels the number of channels
175       * @param frameSize the frame size, in bytes
176       * @param frameRate the frame rate, in frames per second
177       * @param bigEndian true if the data is stored big-endian
178       * @param properties a map describing properties of this format
179       */
180      public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits,
181                         int channels, int frameSize, float frameRate,
182                         boolean bigEndian, Map<String, Object> properties)
183      {
184        this.encoding = encoding;
185        this.sampleRate = sampleRate;
186        this.sampleSizeInBits = sampleSizeInBits;
187        this.channels = channels;
188        this.frameSize = frameSize;
189        this.frameRate = frameRate;
190        this.bigEndian = bigEndian;
191        this.properties = Collections.unmodifiableMap(new HashMap<String, Object>(properties));
192      }
193    
194      /**
195       * Create a new PCM-based audio format, given various attributes of it.
196       * The encoding will either be Encoding#PCM_SIGNED or Encoding#PCM_UNSIGNED.
197       * The frame size for this format will be derived from the sample size in
198       * bits and the number of channels, unless one of those is
199       * AudioSystem#NOT_SPECIFIED.  The frame rate will be the same as the sample
200       * rate, and the properties map will be empty.
201       * 
202       * @param sampleRate the sample rate
203       * @param sampleSizeInBits the sample size, in bits
204       * @param channels the number of channels
205       * @param signed true if this is a signed encoding
206       * @param bigEndian true if the data is stored big-endian
207       */
208      public AudioFormat(float sampleRate, int sampleSizeInBits,
209                         int channels, boolean signed, boolean bigEndian)
210      {
211        this.encoding = signed ? Encoding.PCM_SIGNED : Encoding.PCM_UNSIGNED;
212        this.sampleRate = sampleRate;
213        this.sampleSizeInBits = sampleSizeInBits;
214        this.channels = channels;
215        // It isn't clear whether channels can be NOT_SPECIFIED.
216        if (sampleSizeInBits == AudioSystem.NOT_SPECIFIED
217            || channels == AudioSystem.NOT_SPECIFIED)
218          this.frameSize = AudioSystem.NOT_SPECIFIED;
219        else
220          this.frameSize = (sampleSizeInBits + 7) / 8 * channels;
221        this.frameRate = sampleRate;
222        this.bigEndian = bigEndian;
223        this.properties = Collections.<String, Object> emptyMap();
224      }
225    
226      /**
227       * Return the number of channels in this format.
228       */
229      public int getChannels()
230      {
231        return channels;
232      }
233    
234      /**
235       * Return the encoding of this format.
236       */
237      public Encoding getEncoding()
238      {
239        return encoding;
240      }
241    
242      /**
243       * Return the frame rate of this format.
244       */
245      public float getFrameRate()
246      {
247        return frameRate;
248      }
249    
250      /**
251       * Return the frame size of this format.
252       */
253      public int getFrameSize()
254      {
255        return frameSize;
256      }
257    
258      /**
259       * Given a key, return a property associated with this format;
260       * or null if this property is not set. 
261       * @param key the name of the property
262       * @return the value of the property, or null if the property is not set
263       */
264      public Object getProperty(String key)
265      {
266        return properties.get(key);
267      }
268    
269      /**
270       * Return the sample rate of this format.
271       */
272      public float getSampleRate()
273      {
274        return sampleRate;
275      }
276    
277      /**
278       * Return the sample size of this format, in bits.
279       */
280      public int getSampleSizeInBits()
281      {
282        return sampleSizeInBits;
283      }
284    
285      /**
286       * Return true if this format is big endian, false otherwise.
287       * This only matters for formats whose sample size is greater than
288       * one byte.
289       */
290      public boolean isBigEndian()
291      {
292        return bigEndian;
293      }
294    
295      /**
296       * Return true if this audio format matches another.
297       * @param fmt the format to match against
298       * @return true if they match, false otherwise
299       */
300      public boolean matches(AudioFormat fmt)
301      {
302        if (! encoding.equals(fmt.encoding)
303            || channels != fmt.channels
304            || sampleSizeInBits != fmt.sampleSizeInBits
305            || frameSize != fmt.frameSize)
306          return false;
307        if (sampleRate != AudioSystem.NOT_SPECIFIED
308            && fmt.sampleRate != AudioSystem.NOT_SPECIFIED
309            && sampleRate != fmt.sampleRate)
310          return false;
311        if (frameRate != AudioSystem.NOT_SPECIFIED
312            && fmt.frameRate != AudioSystem.NOT_SPECIFIED
313            && frameRate != fmt.frameRate)
314          return false;
315        if (sampleSizeInBits > 8)
316          return bigEndian == fmt.bigEndian;
317        return true;
318      }
319    
320      /**
321       * Return a read-only Map holding the properties associated with 
322       * this format.
323       */
324      public Map<String, Object> properties()
325      {
326        return properties;
327      }
328    
329      /**
330       * Return a description of this format.
331       */
332      public String toString()
333      {
334        CPStringBuilder result = new CPStringBuilder();
335        
336        // usually at least encoding should be somewhat specified
337        result.append(encoding);
338        
339        if (sampleRate != AudioSystem.NOT_SPECIFIED)
340          {
341            result.append(" ");
342            result.append(sampleRate);
343            result.append(" Hz");
344          }
345        
346        if (sampleSizeInBits != AudioSystem.NOT_SPECIFIED)
347          {
348            result.append(" ");
349            result.append(sampleSizeInBits);
350            result.append(" bits");
351          }
352        
353        if (channels != AudioSystem.NOT_SPECIFIED)
354          {
355            result.append(" ");
356            result.append(channels);
357            result.append(" channel");
358            if (channels > 1) result.append("s");
359          }
360        
361        if (sampleSizeInBits > 8)
362          result.append(bigEndian ? " big endian" : " little endian");
363        
364        return result.toString();
365      }
366    }