java.lang.Object
- ptolemy.media.Audio

public class Audio
extends java.lang.Object

Instances of this class represent audio data equivalent to that contained by a Sun/NeXT audio file (.au file). The class also includes a set of utility static methods for manipulating audio signals. Currently, only an 8kHz sample rate, mu-law encoded, monophonic audio format is supported.

The format of an audio file is:

Audio File Format
byte	type	field name	field value
0x00	byte	magic[4]	0x2E736E64 '.snd' in ASCII
0x04	int	offset	offset of audio data relative to the start of the stream
0x08	int	size	number of bytes of data
0x0C	int	format	format code: 1 for 8-bit u-law
0x10	int	samplingRate	the sampling rate
0x14	int	numChannels	the number of channels
0x18	byte	info[]	optional text information

The design of this class is based on the web page of Billy Donahue. http://www.cooper.edu/~donahu/auformat/auFormat.html. That page no longer exists. This file was created on 1998-08-31, The Wayback machine yields this page for that date: http://web.archive.org/web/19980709194800/http://www.cooper.edu/~donahu/auformat/auFormat.html.

Note that this class serves the same role as the class by the same name in the sun.audio package, but is much more public about its information. For example, the Sun version does not give any access to the audio data itself.

Since:: Ptolemy II 0.2
Version:: $Id$
Author:: Edward A. Lee
Pt.AcceptedRating:: Red (cxh)
Pt.ProposedRating:: Red (eal)

Field Summary

Fields
Modifier and Type	Field	Description
`byte[][]`	`audio`	Audio data, by channel.
`int`	`format`	Format code; 1 for 8-bit mu-law.
`byte[]`	`info`	Four byte info field.
`byte[]`	`magic`	The file type identifier, 0x2E736E64 or '.snd' in ASCII.
`int`	`numChannels`	The number of channels.
`int`	`offset`	Offset of audio data relative to the start of the stream.
`int`	`sampleRate`	The sampling rate.
`int`	`size`	Number of bytes of audio data.

Constructor Summary

Constructors
Constructor	Description
`Audio(byte[] audio)`	Construct an instance initialized with the audio signal given by the argument.
`Audio(double[] audio)`	Construct an instance initialized with the audio signal given by the argument.
`Audio(java.io.DataInputStream input)`	Construct an instance and initialize it by reading the specified stream.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`static byte`	`lin2mu(int sample)`	Convert an integer linear representation of an audio sample into a mu-255 companded representation.
`static int`	`mu2lin(byte b)`	Convert mu-255 companded representation of an audio sample into an integer linear representation.
`static double[]`	`readAudio(java.io.DataInputStream input)`	Read Sun audio file (.au) format and return the audio data as an array.
`static void`	`setZeroTrap(boolean boole)`	Configure all instances of this class to use the MIL-STD zero trap.
`double[]`	`toDouble(int channel)`	Convert the audio data to linear double encoding (from mu-law).
`int[]`	`toLinear(int channel)`	Convert the audio data to linear integer encoding (from mu-law).
`java.lang.String`	`toString()`	Return a readable representation of the header data.
`void`	`write(java.io.DataOutputStream output)`	Write the audio data to an output stream in the Sun audio format.
`static void`	`writeAudio(double[] audio, java.io.DataOutputStream output)`	Write Sun audio file (.au) format from an array.
`void`	`writeRaw(java.io.DataOutputStream output)`	Write the raw audio data to an output stream.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - magic
```
public byte[] magic
```
    The file type identifier, 0x2E736E64 or '.snd' in ASCII.
  - offset
```
public int offset
```
    Offset of audio data relative to the start of the stream.
  - size
```
public int size
```
    Number of bytes of audio data.
  - format
```
public int format
```
    Format code; 1 for 8-bit mu-law.
  - sampleRate
```
public int sampleRate
```
    The sampling rate.
  - numChannels
```
public int numChannels
```
    The number of channels.
  - info
```
public byte[] info
```
    Four byte info field.
  - audio
```
public byte[][] audio
```
    Audio data, by channel.
- Constructor Detail
  - Audio
```
public Audio(byte[] audio)
```
    Construct an instance initialized with the audio signal given by the argument. The argument is an array of bytes that are mu-law encoded. The audio signal is assumed to have an 8kHz sample rate, with a single channel.
    
    Parameters:
    
    audio - An audio signal.
  - Audio
```
public Audio(double[] audio)
```
    Construct an instance initialized with the audio signal given by the argument. The argument is an array of double-precision, floating point audio samples assumed to be normalized to be in the range -1.0 to 1.0. The data will be encoded according to the mu-law standard at an 8kHz sample rate, with a single channel.
    
    Parameters:
    
    audio - An audio signal.
  - Audio
```
public Audio(java.io.DataInputStream input)
      throws java.io.IOException
```
    Construct an instance and initialize it by reading the specified stream.
    
    Parameters:
    
    input - The input stream.
    
    Throws:
    
    java.io.IOException - If an error occurs reading the input data (e.g. a premature end of file).
- Method Detail
  - lin2mu
```
public static byte lin2mu(int sample)
```
    Convert an integer linear representation of an audio sample into a mu-255 companded representation. Mu law is the standard used in Sun .au files as well as throughout the telephone network.
    The integer argument is a 16-bit representation of the sample. Anything outside the range -32635 to 32635 will be clipped to within that range.
    The mu-255 representation is a byte SEEEMMMM where S is the sign bit, EEE is the three-bit exponent, and MMMM is the four-bit mantissa. The bits are flipped, so that the binary 10000000 is the largest positive number and 00000000 is the largest negative number. If you have called that static method setZeroTrap() with a true argument, then per MIL-STD-188-113, the 00000000 representation is never used, replaced instead with 00000010 (0x02). By default, this trap is not used.
    This implementation was written by Anthony Hursh, who included with it the following information:
    Copyright 1997 by Anthony Hursh <hursha@saturn.math.uaa.alaska.edu> This code may be freely used as long as proper credit is given. It was originally written in C by Craig Reese (IDA/Supercomputing Research Center) and Joe Campbell (Department of Defense), and ported to Java by Tony Hursh, January 1997. References:
    
    CCITT Recommendation G.711 (very difficult to follow)
    "A New Digital Technique for Implementation of Any Continuous PCM Companding Law," Villeret, Michel, et al. 1973 IEEE Int. Conf. on Communications, Vol 1, 1973, pg. 11.12-11.17
    MIL-STD-188-113,"Interoperability and Performance Standards for Analog-to_Digital Conversion Techniques," 17 February 1987
    Parameters:
    
    sample - A linear representation of the sample.
    
    Returns:
    
    A mu-255 representation of the sample.
  - mu2lin
```
public static int mu2lin(byte b)
```
    Convert mu-255 companded representation of an audio sample into an integer linear representation. Mu law is the standard used in Sun .au files as well as throughout the telephone network. This implementation is based on the web page by Billy Donahue: http://www.cooper.edu/~donahu/auformat/auFormat.html. The resulting integer values are scaled to be in the range -31616 to 31616. This uses the low order 16 bits of the resulting integer, and thus provides a convenient 16-bit linear encoding.
    The mu-255 representation is a byte SEEEMMMM where S is the sign bit, EEE is the three-bit exponent, and MMMM is the four-bit mantissa. The bits are flipped, so that the binary 10000000 is the largest positive number and 00000000 is the largest negative number.
    If you have called setZeroTrap() with a true argument, then this will not be an exact inverse of lin2mu because the zero code is interpreted as being the largest negative number, -31616.
    
    Parameters:
    
    b - A mu-255 representation of the sample.
    
    Returns:
    
    A linear representation of the sample.
  - readAudio
```
public static double[] readAudio(java.io.DataInputStream input)
                          throws java.io.IOException
```
    Read Sun audio file (.au) format and return the audio data as an array. The argument stream may represent a file, a URL, or a byte array that contains the .au format. For example, given a URL called "url," you can read the audio file as follows:
    double audio[] = readAudio(new DataInputStream(url.openStream());
    
    The returned values lie in the range -1.0 to 1.0.
    Parameters:
    
    input - The input stream.
    
    Returns:
    
    The audio data as an array of doubles.
    
    Throws:
    
    java.io.IOException - If an I/O error occurs reading the stream.
  - setZeroTrap
```
public static void setZeroTrap(boolean boole)
```
    Configure all instances of this class to use the MIL-STD zero trap. I.e., per MIL-STD-188-113, the 00000000 representation is never used, replaced instead with 00000010 (0x02). For some reason, an all zero mu-law code is sometimes undesirable. By default, this class does not use this trap, so you must call this with a true argument to use the trap.
    
    Parameters:
    
    boole - If true, use zero-trap encoding.
  - toDouble
```
public double[] toDouble(int channel)
```
    Convert the audio data to linear double encoding (from mu-law). The returned numbers lie in the range -1.0 to 1.0.
    
    Parameters:
    
    channel - The channel number.
    
    Returns:
    
    A new array of integers, or null if there is no audio data.
  - toLinear
```
public int[] toLinear(int channel)
```
    Convert the audio data to linear integer encoding (from mu-law). The returned integers use the low-order 16 bits only, lying in the range -31616 to 31616.
    
    Parameters:
    
    channel - The channel number.
    
    Returns:
    
    A new array of integers, or null if there is no audio data.
  - toString
```
public java.lang.String toString()
```
    Return a readable representation of the header data.
    
    Overrides:
    
    toString in class java.lang.Object
  - write
```
public void write(java.io.DataOutputStream output)
           throws java.io.IOException
```
    Write the audio data to an output stream in the Sun audio format.
    
    Parameters:
    
    output - The output stream.
    
    Throws:
    
    java.io.IOException - If an error occurs writing to the stream.
  - writeRaw
```
public void writeRaw(java.io.DataOutputStream output)
              throws java.io.IOException
```
    Write the raw audio data to an output stream. This method can be used to play the audio data using the (undocumented and unsupported) sun.audio package as follows:
    // The constructor argument below is optional ByteArrayOutputStream out = new ByteArrayOutputStream(sound.size); try { sound.writeRaw(new DataOutputStream(out)); } catch (IOException ex) { throw new RuntimeException("Audio output failed"); } byte[] iobuffer = out.toByteArray(); ByteArrayInputStream instream = new ByteArrayInputStream(_iobuffer); AudioPlayer.player.start(instream);
    The above code assumes we have an sun.audio.AudioData object called "sound". Although it would seem reasonable to include a "play" method in this class to do this, we wish to avoid a dependence on the sun.audio package in this Ptolemy package, so you will have to implement the above code yourself.
    Parameters:
    
    output - The output stream.
    
    Throws:
    
    java.io.IOException - If an error occurs writing to the stream.
  - writeAudio
```
public static void writeAudio(double[] audio,
                              java.io.DataOutputStream output)
                       throws java.io.IOException
```
    Write Sun audio file (.au) format from an array. The argument is an array of doubles assumed to lie in the range of -1.0 to 1.0. The data is converted to one-channel mu-law samples at 8kHz.
    
    Parameters:
    
    audio - The audio data, as an array of doubles.
    
    output - The output stream.
    
    Throws:
    
    java.io.IOException - If an I/O error occurs writing to the stream.

Class Audio

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

magic

offset

size

format

sampleRate

numChannels

info

audio

Constructor Detail

Audio

Audio

Audio

Method Detail

lin2mu

mu2lin

readAudio

setZeroTrap

toDouble

toLinear

toString

write

writeRaw

writeAudio