|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectmckay.utilities.sound.sampled.AudioMethodsGeneral
public class AudioMethodsGeneral
A holder class for general static methods relating to sampled audio. Includes methods for use in converting back and forth between audio stored using the javax.sound.sampled package and audio stored as samples in arrays of doubles.
Constructor Summary | |
---|---|
AudioMethodsGeneral()
|
Method Summary | |
---|---|
static javax.sound.sampled.AudioInputStream |
convertToAudioInputStream(double[][] samples,
javax.sound.sampled.AudioFormat audio_format)
Returns an AudioInputStream containing the given samples encoded using the given AudioFormat. |
static javax.sound.sampled.AudioInputStream |
convertUnsupportedFormat(javax.sound.sampled.AudioInputStream audio_input_stream)
Takes the given AudioInputStream and tests if it is playable. |
static double[][] |
extractSampleValues(javax.sound.sampled.AudioInputStream audio_input_stream)
Returns an array of doubles representing the samples for each channel in the given AudioInputStream. |
static java.lang.String |
getAudioFileFormatData(java.io.File file)
Returns information regarding a given audio file. |
static javax.sound.sampled.AudioFileFormat.Type |
getAudioFileFormatType(java.lang.String file_type_name)
Returns the appropriate AudioFileFormat.Type corresponding
to the given String . |
static java.lang.String |
getAudioFormatData(javax.sound.sampled.AudioFormat audio_format)
Returns information regarding a given AudioFormat . |
static java.lang.String[] |
getAvailableFileFormatTypes()
Returns the names of file types for which file writing support is provided by the system. |
static java.lang.String |
getAvailableMixerData()
Returns information in String form regarding all available
system mixers. |
static byte[] |
getBytesFromAudioInputStream(javax.sound.sampled.AudioInputStream audio_input_stream)
Generates an array of audio bytes based on the contents of the given AudioInputStream . |
static javax.sound.sampled.AudioFormat |
getConvertedAudioFormat(javax.sound.sampled.AudioFormat original_format)
Returns an AudioFormat with the same sampling rate and number of channels as the passed AudioFormat. |
static javax.sound.sampled.AudioInputStream |
getConvertedAudioStream(javax.sound.sampled.AudioInputStream audio_input_stream)
Returns a copy of the given AudioInputStream that uses big-endian signed linear PCM encoding, regardless of the original encoding. |
static javax.sound.sampled.AudioFormat |
getCopyOfAudioFormat(javax.sound.sampled.AudioFormat old_audio_format)
Returns a copy of the given AudioFormat. |
static javax.sound.sampled.AudioInputStream |
getInputStream(byte[] audio_bytes,
javax.sound.sampled.AudioFormat audio_format)
Generates an AudioInputStream based on the given array of
bytes and the given AudioFormat . |
static javax.sound.sampled.AudioInputStream |
getInputStream(java.io.ByteArrayOutputStream byte_stream,
javax.sound.sampled.AudioFormat audio_format)
Generates an AudioInputStream based on the given
ByteArrayOutputStream and the given
AudioFormat . |
static javax.sound.sampled.AudioInputStream |
getInputStream(java.io.File audio_file)
Generates an AudioInputStream based on the contents of the
given File . |
static javax.sound.sampled.Mixer |
getMixer(int mixer_index,
AudioEventLineListener listener)
Returns the Mixer object with the specified index. |
static int |
getNumberBytesNeeded(double duration_in_seconds,
javax.sound.sampled.AudioFormat audio_format)
Returns the number of bytes needed to store samples corresponding to audio of fixed duration. |
static int |
getNumberBytesNeeded(int number_samples,
javax.sound.sampled.AudioFormat audio_format)
Returns the number of bytes needed to store samples corresponding to the given number of samples in a given AudioFormat . |
static javax.sound.sampled.SourceDataLine |
getSourceDataLine(javax.sound.sampled.AudioFormat audio_format,
AudioEventLineListener listener)
Gets a SourceDataLine that can be used for purposes such as
writing directly to a speaker. |
static javax.sound.sampled.TargetDataLine |
getTargetDataLine(javax.sound.sampled.AudioFormat audio_format,
AudioEventLineListener listener)
Returns a TargetDataLine that can be used for purposes such
as recording from a mic. |
static javax.sound.sampled.TargetDataLine |
getTargetDataLine(javax.sound.sampled.AudioFormat audio_format,
javax.sound.sampled.Mixer mixer,
AudioEventLineListener listener)
Returns a TargetDataLine that can be used for purposes such
as recording from a mic. |
static void |
saveByteArrayOutputStream(java.io.ByteArrayOutputStream audio,
javax.sound.sampled.AudioFormat audio_format,
java.io.File save_file,
javax.sound.sampled.AudioFileFormat.Type file_type)
Stores the samples on the ByteArrayOutputStream to
the given file. |
static void |
saveToFile(javax.sound.sampled.AudioInputStream audio_input_stream,
java.io.File file_to_save_to,
javax.sound.sampled.AudioFileFormat.Type file_type)
Stores the samples coming in on the given AudioInputStream
to the given file. |
static void |
writeSamplesToBuffer(double[][] sample_values,
int bit_depth,
byte[] buffer)
Writes the samples in the sample_values parameter to the buffer parameter. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public AudioMethodsGeneral()
Method Detail |
---|
public static javax.sound.sampled.AudioFormat getCopyOfAudioFormat(javax.sound.sampled.AudioFormat old_audio_format)
old_audio_format
- The AudioFormat to copy.
public static java.lang.String getAudioFormatData(javax.sound.sampled.AudioFormat audio_format)
AudioFormat
. This
information consists of mixer index, name, version, vendor and
description, in that order. A list of any additional property names are
also included. The getProperty
method of the
AudioFormat
class may then be used to access the values of
these properties using the key listed here. Three common property keys
are bitrate, vbr and quality (see the AudioFormat
API).
These may not be visible, depending on whether they were encoded and on
whether the file reader used can see them.
audio_format
- The AudioFormat
to return data
about.
AudioFormat
.public static java.lang.String getAudioFileFormatData(java.io.File file) throws java.lang.Exception
getProperty
method of the
AudioFileFormat
class may then be used to access the values
of these properties using the key listed here. Six common property keys
are duration, author, title, copyright, date and comment. These may not
be visible, depending on whether they were encoded and on whether the
file reader used can see them. The AudioFormat
properties
are also returned (see the getAudioFormatData
method of
this class).
file
- The file to return data about.
AudioFormat
.
java.lang.Exception
- Throws informative exceptions if the file is
invalid or has an unsupported format.public static java.lang.String[] getAvailableFileFormatTypes()
AudioSystem.getAudioFileTypes
method returns them.
public static javax.sound.sampled.AudioFileFormat.Type getAudioFileFormatType(java.lang.String file_type_name)
AudioFileFormat.Type
corresponding
to the given String
.
WARNING: Future additions to the Java SDK may make further formats available that are not accounted for here.
file_type_name
- The name of the format type desired.
AudioFileFormat.Type
corresponding to the given
file_type_name. Returns null if the
file_type_name does not correspond to
any known AudioFileFormat.Type
.public static java.lang.String getAvailableMixerData()
String
form regarding all available
system mixers. This information consists of mixer index, name, version,
vendor and description, in that order.
public static javax.sound.sampled.Mixer getMixer(int mixer_index, AudioEventLineListener listener)
Mixer
object with the specified index. The
mixers corresponding to the given index may be obtained by calling the
printAvailableMixers
method.
If the listener parameter is not null, then open, start, stop and close events will be sent to the passed listener. If it is null, then the line is returned without any attached listener.
WARNING: The Mixer
correxponding to particular
indices will vary from system to system.
mixer_index
- The index (on the current system) of the
mixer to be returned.listener
- Responds to open, start, stop and close
events on the returned line. May be null.
Mixer
.public static javax.sound.sampled.TargetDataLine getTargetDataLine(javax.sound.sampled.AudioFormat audio_format, AudioEventLineListener listener) throws java.lang.Exception
TargetDataLine
that can be used for purposes such
as recording from a mic. This line will correspond to a system-specified
mixer. This line will be opened and started, and will therefore be
recording data when it is returned.
If the listener parameter is not null, then open, start, stop
and close events will be sent to the passed listener. If it is null,
then the line is returned without any attached listener.
WARNING: The TargetDataLine
opened here will begin
capturing data and storing it in an internal a buffer. The user must be
sure to take data from this line quickly enough that its buffer does not
overflow, with the result that data is lost.
audio_format
- The audio format to be used by the
TargetDataLine
listener
- Responds to open, start, stop and close events on
the returned line. May be null.
TargetDataLine
that can be used for
purposes such as recording from a mic.
java.lang.Exception
- Throws an exception if cannot get a valid
TargetDataLine
.public static javax.sound.sampled.TargetDataLine getTargetDataLine(javax.sound.sampled.AudioFormat audio_format, javax.sound.sampled.Mixer mixer, AudioEventLineListener listener) throws java.lang.Exception
TargetDataLine
that can be used for purposes such
as recording from a mic. This line will correspond to the specified
Mixer
. This line will be opened and started, and will
therefore be recording data when it is returned.
If the listener parameter is not null, then open, start, stop
and close events will be sent to the passed listener. If it is null,
then the line is returned without any attached listener.
WARNING: The TargetDataLine
opened here will begin
capturing data and storing it in an internal buffer. The user must be
sure to take data from this line quickly enough that its buffer does not
overflow, and data is lost.
audio_format
- The audio format to be used by the
TargetDataLine
mixer
- The Mixer
corresponding to the
TargetDataLine
.listener
- Responds to open, start, stop and close
events on the returned line. May be null.
TargetDataLine
that can be
used for purposes such as recording from a
mic.
java.lang.Exception
- Throws an exception if cannot get a valid
TargetDataLine
.public static javax.sound.sampled.SourceDataLine getSourceDataLine(javax.sound.sampled.AudioFormat audio_format, AudioEventLineListener listener)
SourceDataLine
that can be used for purposes such as
writing directly to a speaker. This line will correspond to a
system-specified mixer. This line will be opened and started, and will
therefore be ready to write data when it is returned.
If the listener parameter is not null, then open, start, stop and close events will be sent to the passed listener. If it is null, then the line is returned without any attached listener.
audio_format
- The audio format to be used by the
SourceDataLine
.listener
- Responds to open, start, stop and close
events on the returned line. May be null.
SourceDataLine
that can be
used for purposes such as writing directly to
a speaker.public static javax.sound.sampled.AudioInputStream getInputStream(java.io.ByteArrayOutputStream byte_stream, javax.sound.sampled.AudioFormat audio_format)
AudioInputStream
based on the given
ByteArrayOutputStream
and the given
AudioFormat
.
It is important to note that the ByteArrayOutputStream
is turned into a fixed size array before playback, so additional
information should not be added to it once this mehtod is called. This
method is not intended for real-time streamed data, but rather
pre-recorded data.
In general, the AudioFormat
used for the
AudioInputStream
and the ByteArrayOutputStream
should be the same.
byte_stream
- The audio bytes to be played.audio_format
- The AudioFormat
to use for
encoding the AudioInputStream
.
Should also correspond to the
AudioFormat
of the bytes of the
ByteArrayOutputStream
.
AudioInputStream
corresponding to the given samples and the
given AudioFormat
.public static javax.sound.sampled.AudioInputStream getInputStream(byte[] audio_bytes, javax.sound.sampled.AudioFormat audio_format)
AudioInputStream
based on the given array of
bytes and the given AudioFormat
. Because of the fixed size
of the bytes array, this method is not intended for real-time streamed
data, but rather pre-recorded data.
In general, the AudioFormat
used for the
AudioInputStream
and the array of bytes should be the same.
audio_bytes
- The audio bytes to be played.audio_format
- The AudioFormat
to use for
encoding the AudioInputStream
.
Should also correspond to the
AudioFormat
of
audio_bytes.
AudioInputStream
corresponding to the given samples and the
given AudioFormat
.public static javax.sound.sampled.AudioInputStream getInputStream(java.io.File audio_file) throws java.lang.Exception
AudioInputStream
based on the contents of the
given File
.
audio_file
- The audio file to extract the
AudioInputStream
from.
AudioInputStream
extracted
from the specified file.
java.lang.Exception
- Throws informative exceptions if the file is
invalid or has an unsupported file format.public static javax.sound.sampled.AudioFormat getConvertedAudioFormat(javax.sound.sampled.AudioFormat original_format)
original_format
- The format from which to extract
sampling rate, bit depth and number of
channels.
public static javax.sound.sampled.AudioInputStream getConvertedAudioStream(javax.sound.sampled.AudioInputStream audio_input_stream)
audio_input_stream
- The AudioInputStream to convert to a new
encoding.
public static javax.sound.sampled.AudioInputStream convertUnsupportedFormat(javax.sound.sampled.AudioInputStream audio_input_stream)
audio_input_stream
- The audio data to test and possibly
convert.
public static double[][] extractSampleValues(javax.sound.sampled.AudioInputStream audio_input_stream) throws java.lang.Exception
This method is only compatible with audio with bit depths of 8 or 16 bits that is encoded using signed PCM with big endian byte order.
audio_input_stream
- The AudioInputStream to convert to
sample values.
java.lang.Exception
- Throws an informative exception if an
invalid paramter is provided.public static byte[] getBytesFromAudioInputStream(javax.sound.sampled.AudioInputStream audio_input_stream) throws java.lang.Exception
AudioInputStream
. Extracts all of the bytes available in
the AudioInputStream
at the moment that this method is
called.
audio_input_stream
- The AudioInputStream
to
extract the bytes from.
AudioInputStream
. Has the
same AudioFileFormat
as the
specified AudioInputStream
.
java.lang.Exception
- Throws an exception if a problem occurs.public static int getNumberBytesNeeded(double duration_in_seconds, javax.sound.sampled.AudioFormat audio_format)
duration_in_seconds
- The duration, in seconds, of the audio
that needs to be stored.audio_format
- The AudioFormat
of the
samples to be stored.
public static int getNumberBytesNeeded(int number_samples, javax.sound.sampled.AudioFormat audio_format)
AudioFormat
.
number_samples
- The number of samples to be encoded.audio_format
- The AudioFormat
of the samples
to be stored.
public static javax.sound.sampled.AudioInputStream convertToAudioInputStream(double[][] samples, javax.sound.sampled.AudioFormat audio_format) throws java.lang.Exception
samples
- The audio samples to convert. The first
indice indicates channel and the second
indicates sample number. Sample values vary
from -1 to +1.audio_format
- The AudioFormat to use for encoding.
java.lang.Exception
- Throws an exception if an error occurs during
conversion.public static void writeSamplesToBuffer(double[][] sample_values, int bit_depth, byte[] buffer) throws java.lang.Exception
sample_values
- A 2-D array of doubles whose first indice
indicates channel and whose second indice
indicates sample value. In stereo, indice 0
corresponds to left and 1 to right. All samples
should fall between -1 and +1.bit_depth
- The bit depth to use for encoding the doubles
stored in samples_to_modify. Only bit
depths of 8 or 16 bits are accepted.buffer
- The buffer of bytes to write synthesized samples
to.
java.lang.Exception
public static void saveByteArrayOutputStream(java.io.ByteArrayOutputStream audio, javax.sound.sampled.AudioFormat audio_format, java.io.File save_file, javax.sound.sampled.AudioFileFormat.Type file_type) throws java.lang.Exception
ByteArrayOutputStream
to
the given file.
audio
- The audio data to be recorded.audio_format
- The AudioFormat of the audio.save_file
- The file to save the audio to.file_type
- The type of audio file to save to.
java.lang.Exception
- Throws an exception if an error writing to the
file occurs of if null parameters are passed.public static void saveToFile(javax.sound.sampled.AudioInputStream audio_input_stream, java.io.File file_to_save_to, javax.sound.sampled.AudioFileFormat.Type file_type) throws java.lang.Exception
AudioInputStream
to the given file. Just repeats the functionality of the
AudioSystem.write
method, but with better documentation and
exceptions. Useful for non-real-time recording, as well as possibly
real-time recording.
audio_input_stream
- The audio data to be recorded.file_to_save_to
- The file to save the audio to.file_type
- The type of audio file to save to.
java.lang.Exception
- Throws an exception if an error writing to
the file occurs of if null parameters are
passed.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |