DOC: Set default format with DataLine.Info object

Name: fb126949 Date: 06/23/2004


Java Sound has an undocumented feature for the default format of DataLines: if you use an DataLine.Info object with just one fully qualified AudioFormat for retrieving that DataLine, the default audio format of that DataLine will be the format in the Info object and calling open() without parameters will open the data line with that format.

The correct way of retrieving a line and opening it with a specific format is this:
  // retrieve a line that is capable of "format"
  info = new DataLine.Info(SourceDataLine.class, format);
  sdl = (SourceDataLine) AudioSystem.getLine(info);
  // open the line with the format
  sdl.open(format);

The spec does not say that the DataLine.Info's format list is used for anything else than finding a suitable DataLine. But, apparently, quite a number of applications exploit an undocumented behavior in Java Sound that initializes a line's default format with the first format in the DataLine.Info's format list, so that the following calling sequence leads to the same result:

  // retrieve a line that is capable of "format"
  info = new DataLine.Info(SourceDataLine.class, format);
  sdl = (SourceDataLine) AudioSystem.getLine(info);
  // open the line
  sdl.open();
or
  sdl.open(sdl.getFormat());

The spec for Line.open() and AudioSystem.getLine should be extended with clarification about this behavior.

======================================================================