ptolemy.media

Class Audio

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: Audio.java 70402 2014-10-23 00:52:20Z cxh $

Author:

Edward A. Lee

Accepted Rating:

Red (cxh)

Proposed Rating:

Red (eal)

Field Summary

Fields

Modifier and Type	Field and 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 and Description
Audio(byte[] 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.
Audio(double[] audio) Construct an instance initialized with the audio signal given by the argument.

Method Summary

Modifier and Type	Method and 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:

1. CCITT Recommendation G.711 (very difficult to follow)
2. "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
3. 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.