Класс AudioSystem

public class AudioSystem
extends Object

Класс AudioSystem служит точкой входа в ресурсы системы сэмплированного звука. Этот класс позволяет запросить и получить доступ к установленным на системе микшерам. AudioSystem включает в себя ряд методов для преобразования аудиоданных между различными форматами, а также для преобразования между аудиофайлами и потоками. Он также предоставляет метод для получения Line непосредственно из AudioSystem без явного обращения к микшерам.

Свойства могут быть использованы для задания значения по умолчанию для миксера определенного типа линии. При этом учитываются как системные свойства, так и файл свойств. Файл свойств sound.properties считывается из места, специфичного для реализации (обычно это каталог lib в каталоге установки Java). Если свойство существует как системное свойство, так и в файле свойств, имеет приоритет системное свойство. Если ни одно из них не указано, выбирается подходящее значение по умолчанию среди доступных устройств. Синтаксис файла свойств указан в Properties.load. В следующей таблице перечислены доступные ключи свойств и методы, которые их учитывают:

Ключ свойства	Интерфейс	Затронутые методы
javax.sound.sampled.Clip	Clip	getLine(javax.sound.sampled.Line.Info), getClip()
javax.sound.sampled.Port	Port	getLine(javax.sound.sampled.Line.Info)
javax.sound.sampled.SourceDataLine	SourceDataLine	getLine(javax.sound.sampled.Line.Info), getSourceDataLine(javax.sound.sampled.AudioFormat)
javax.sound.sampled.TargetDataLine	TargetDataLine	getLine(javax.sound.sampled.Line.Info), getTargetDataLine(javax.sound.sampled.AudioFormat)

Значение свойства состоит из имени класса провайдера и имени миксера, разделенных символом «#». Имя класса провайдера — это полное имя конкретного класса mixer provider. Имя миксера сравнивается с именем String, возвращаемым методом getName объекта Mixer.Info. Может быть опущено либо имя класса, либо имя миксера. Если указано только имя класса, символ «#» в конце необязателен.

Если указан класс провайдера, и его можно успешно получить из установленных провайдеров, список объектов Mixer.Info извлекается из провайдера. В противном случае или когда эти микшеры не обеспечивают последующий соответствие, список извлекается из getMixerInfo() для включения всех доступных объектов Mixer.Info.

Если указано имя миксера, полученный список объектов Mixer.Info просматривается: первый объект с совпадающим именем, и чей Mixer обеспечивает соответствующий интерфейс линии, будет возвращён. Если такой объект не найден или имя миксера не указано, будет возвращён первый микшер из полученного списка, который обеспечивает соответствующий интерфейс линии. Например, свойство javax.sound.sampled.Clip со значением "com.sun.media.sound.MixerProvider#SunClip" будет иметь следующие последствия при вызове getLine для получения экземпляра Clip: если класс com.sun.media.sound.MixerProvider существует в списке установленных провайдеров миксеров, будет возвращён первый Clip из первого миксера с именем "SunClip" . Если его не удаётся найти, будет возвращён первый Clip из первого миксера указанного провайдера, независимо от имени. Если и этого нет, будет возвращён первый Clip из первого Mixer с именем "SunClip" в списке всех миксеров (как возвращается методом getMixerInfo). Если и этого нет, будет возвращён первый Clip из первого Mixer, который можно найти в списке всех миксеров. Если это тоже не удаётся, будет брошено исключение IllegalArgumentException.

Поля

НЕ_ЗАДАНО

public static final int NOT_SPECIFIED

Целое число, представляющее неизвестное числовое значение. Это значение подходит только для знаковых величин, которые обычно не принимают отрицательные значения. Примеры включают размер файлов, размер кадров, размер буферов и частоты дискретизации. Ряд конструкторов Java Sound принимают значение NOT_SPECIFIED для таких параметров. Другие методы также могут принимать или возвращать это значение, как указано в документации.

См. также:

Значения константных полей

Методы

getMixerInfo

public static Mixer.Info[] getMixerInfo()

Получает массив объектов mixer info, представляющих набор аудиомикшеров, которые в настоящее время установлены в системе.

Возвращает:

массив объектов info для текущих установленных микшеров. Если в системе нет микшеров, возвращается массив длиной 0.

См. также:

getMixer(javax.sound.sampled.Mixer.Info)

getMixer

public static Mixer getMixer(Mixer.Info info)

Получает запрашиваемый аудиомикшер.

Параметры:

info - объект Mixer.Info, представляющий желаемый микшер, или null для системного микшера по умолчанию

Возвращает:

запрашиваемый микшер

Исключения:

SecurityException - если запрашиваемый микшер недоступен из-за ограничений безопасности

IllegalArgumentException - если объект info не представляет установленный в системе микшер

См. также:

getMixerInfo()

getSourceLineInfo

public static Line.Info[] getSourceLineInfo(Line.Info info)

Получает информацию обо всех линиях-источниках определенного типа, которые поддерживаются установленными микшерами.

Параметры:

info - объект Line.Info, который указывает вид линий, о которых запрашивается информация

Возвращает:

массив объектов Line.Info, описывающих линии-источники, соответствующие запрошенному типу. Если поддерживаются линии-источники, соответствующие запросу, возвращается массив длиной 0.

См. также:

Mixer.getSourceLineInfo(Line.Info)

getTargetLineInfo

public static Line.Info[] getTargetLineInfo(Line.Info info)

Получает информацию обо всех целевых линиях определенного типа, которые поддерживаются установленными микшерами.

Параметры:

info - объект Line.Info, который указывает вид линий, о которых запрашивается информация

Возвращает:

массив объектов Line.Info, описывающих целевые линии, соответствующие запрошенному типу. Если поддерживаются целевые линии, соответствующие запросу, возвращается массив длиной 0.

См. также:

Mixer.getTargetLineInfo(Line.Info)

isLineSupported

public static boolean isLineSupported(Line.Info info)

Указывает, поддерживает ли система какие-либо линии, соответствующие указанному объекту Line.Info. Линия поддерживается, если её поддерживает любой установленный микшер.

Параметры:

info - объект Line.Info, описывающий линию, для которой запрашивается поддержка

Возвращает:

true если хотя бы одна соответствующая линия поддерживается, в противном случае false

См. также:

Mixer.isLineSupported(Line.Info)

getLine

public static Line getLine(Line.Info info)
                    throws LineUnavailableException

Параметры:

info - объект Line.Info, описывающий требуемый вид линии

Возвращает:

линию требуемого вида

Исключения:

LineUnavailableException - если соответствующая линия недоступна из-за ограничений ресурсов

SecurityException - если соответствующая линия недоступна из-за ограничений безопасности

IllegalArgumentException - если система не поддерживает по крайней мере одну линию, соответствующую указанному объекту Line.Info через любой установленный микшер

getClip

public static Clip getClip()
                    throws LineUnavailableException

Возвращает:

требуемый объект clip

Исключения:

LineUnavailableException - если объект clip недоступен из-за ограничений ресурсов

SecurityException - если объект clip недоступен из-за ограничений безопасности

IllegalArgumentException - если система не поддерживает по крайней мере одну инстанцию clip через любой установленный микшер

С:

1.5

См. также:

getClip(Mixer.Info)

getClip

public static Clip getClip(Mixer.Info mixerInfo)
                    throws LineUnavailableException

Параметры:

mixerInfo - объект Mixer.Info , представляющий желаемый микшер, или null для системного микшера по умолчанию

Возвращает:

объект clip из указанного микшера

Исключения:

LineUnavailableException - если объект clip недоступен из этого микшера из-за ограничений ресурсов

SecurityException - если объект clip недоступен из этого микшера из-за ограничений безопасности

IllegalArgumentException - если система не поддерживает по крайней мере один объект clip через указанный микшер

С:

1.5

См. также:

getClip()

getSourceDataLine

public static SourceDataLine getSourceDataLine(AudioFormat format)
                                        throws LineUnavailableException

Параметры:

format - объект AudioFormat , указывающий поддерживаемый аудиоформат возвращаемой линии, или null для любого аудиоформата

Возвращает:

требуемый объект SourceDataLine

Исключения:

LineUnavailableException - если соответствующая линия-источник данных недоступна из-за ограничений ресурсов

SecurityException - если соответствующая линия-источник данных недоступна из-за ограничений безопасности

IllegalArgumentException - если система не поддерживает по крайней мере одну линию-источник данных, поддерживающую указанный аудиоформат, через любой установленный микшер

С:

1.5

См. также:

getSourceDataLine(AudioFormat, Mixer.Info)

getSourceDataLine

public static SourceDataLine getSourceDataLine(AudioFormat format,
                                               Mixer.Info mixerinfo)
                                        throws LineUnavailableException

Параметры:

format - объект AudioFormat, определяющий поддерживаемый аудиоформат возвращаемой строки, или null для любого аудиоформата

mixerinfo - объект Mixer.Info, представляющий желаемый микшер, или null для системного микшера по умолчанию

Возвращает:

желаемый объект SourceDataLine

Исключения:

LineUnavailableException - если совпадающая строка данных источника недоступна из указанного микшера из-за ограничений ресурсов

SecurityException - если совпадающая строка данных источника недоступна из указанного микшера из-за ограничений безопасности

IllegalArgumentException - если указанный микшер не поддерживает хотя бы одну строку данных источника, поддерживающую указанный аудиоформат

С:

1.5

См. также:

getSourceDataLine(AudioFormat)

getTargetDataLine

public static TargetDataLine getTargetDataLine(AudioFormat format)
                                        throws LineUnavailableException

Параметры:

format - объект AudioFormat, определяющий поддерживаемый аудиоформат возвращаемой строки, или null для любого аудиоформата

Возвращает:

желаемый объект TargetDataLine

Исключения:

LineUnavailableException - если соответствующая целевая линия данных недоступна из-за ограничений ресурсов

SecurityException - если соответствующая целевая линия данных недоступна из-за ограничений безопасности

IllegalArgumentException - если система не поддерживает по крайней мере одну целевую линию данных, поддерживающую указанный аудиоформат через любой установленный микшер

С:

1.5

См. также:

getTargetDataLine(AudioFormat, Mixer.Info), AudioPermission

getTargetDataLine

public static TargetDataLine getTargetDataLine(AudioFormat format,
                                               Mixer.Info mixerinfo)
                                        throws LineUnavailableException

Параметры:

format - объект AudioFormat, определяющий поддерживаемый аудиоформат возвращаемой строки, или null для любого аудиоформата

mixerinfo - объект Mixer.Info, представляющий желаемый микшер, или null для системного микшера по умолчанию

Возвращает:

желаемый объект TargetDataLine

Исключения:

LineUnavailableException - если соответствующая целевая линия данных недоступна из указанного микшера из-за ограничений ресурсов

SecurityException - если соответствующая целевая линия данных недоступна из указанного микшера из-за ограничений безопасности

IllegalArgumentException - если указанный микшер не поддерживает по крайней мере одну целевую линию данных, поддерживающую указанный аудиоформат

С:

1.5

См. также:

getTargetDataLine(AudioFormat), AudioPermission

getTargetEncodings

public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.Encoding sourceEncoding)

Получает кодировки, которые система может получить из потока аудио ввода с указанной кодировкой, используя набор установленных преобразователей форматов.

Параметры:

sourceEncoding - кодировка, для которой запрашивается поддержка преобразования

Возвращает:

массив кодировок. Если sourceEncoding не поддерживается, возвращается массив длиной 0. В противном случае массив будет иметь длину как минимум 1, представляющую sourceEncoding (без преобразования).

getTargetEncodings

public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat)

Получает кодировки, которые система может получить из потока аудио ввода с указанным форматом, используя набор установленных преобразователей форматов.

Параметры:

sourceFormat - аудиоформат, для которого запрашивается преобразование

Возвращает:

массив кодировок. Если sourceFormat не поддерживается, возвращается массив длиной 0. В противном случае массив будет иметь длину как минимум 1, представляющую кодировку sourceFormat (без преобразования).

isConversionSupported

public static boolean isConversionSupported(AudioFormat.Encoding targetEncoding,
                                            AudioFormat sourceFormat)

Указывает, может ли быть получен поток аудио ввода с указанной кодировкой из потока аудио ввода, имеющего указанный формат.

Параметры:

targetEncoding - желаемая кодировка после преобразования

sourceFormat - аудиоформат до преобразования

Возвращает:

true если преобразование поддерживается, в противном случае false

getAudioInputStream

public static AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding,
                                                   AudioInputStream sourceStream)

Получает поток аудио ввода с указанной кодировкой, преобразуя предоставленный поток аудио ввода.

Параметры:

targetEncoding - желаемая кодировка после преобразования

sourceStream - преобразуемый поток

Возвращает:

поток аудио ввода с указанной кодировкой

Исключения:

IllegalArgumentException - если преобразование не поддерживается

См. также:

getTargetEncodings(AudioFormat.Encoding), getTargetEncodings(AudioFormat), isConversionSupported(AudioFormat.Encoding, AudioFormat), getAudioInputStream(AudioFormat, AudioInputStream)

getTargetFormats

public static AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding,
                                             AudioFormat sourceFormat)

Получает форматы, имеющие определенную кодировку, и которые система может получить из потока с указанным форматом, используя набор установленных преобразователей форматов.

Параметры:

targetEncoding - желаемая кодировка после преобразования

sourceFormat - аудиоформат до преобразования

Возвращает:

массив форматов. Если форматы с указанной кодировкой не поддерживаются, возвращается массив длиной 0.

isConversionSupported

public static boolean isConversionSupported(AudioFormat targetFormat,
                                            AudioFormat sourceFormat)

Указывает, может ли быть получен поток аудио ввода с указанным форматом из потока аудио ввода другого указанного формата.

Параметры:

targetFormat - желаемый аудиоформат после преобразования

sourceFormat - аудиоформат до преобразования

Возвращает:

true если преобразование поддерживается, в противном случае false

getAudioInputStream

public static AudioInputStream getAudioInputStream(AudioFormat targetFormat,
                                                   AudioInputStream sourceStream)

Получает поток аудио ввода с указанным форматом, преобразуя предоставленный поток аудио ввода.

Параметры:

targetFormat - желаемый аудиоформат после преобразования

sourceStream - преобразуемый поток

Возвращает:

поток аудио ввода с указанным форматом

Исключения:

IllegalArgumentException - если преобразование не поддерживается #см #getTargetEncodings(AudioFormat)

См. также:

getTargetFormats(AudioFormat.Encoding, AudioFormat), isConversionSupported(AudioFormat, AudioFormat), getAudioInputStream(AudioFormat.Encoding, AudioInputStream)

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(InputStream stream)
                                          throws UnsupportedAudioFileException,
                                                 IOException

Получает аудиоформат файла из предоставленного потока ввода. Поток должен указывать на данные действительного аудиофайла. Реализация этого метода может потребовать нескольких парсеров для проверки потока, чтобы определить, поддерживает ли его кто-то. Эти парсеры должны уметь помечать поток, читать достаточно данных, чтобы определить, поддерживают ли они поток, и, если нет, сбрасывать указатель чтения потока в исходную позицию. Если поток ввода не поддерживает эти операции, этот метод может завершиться ошибкой IOException.

Параметры:

stream - поток ввода, из которого должна быть извлечена информация о формате файла

Возвращает:

объект AudioFileFormat, описывающий аудиоформат файла потока

Исключения:

UnsupportedAudioFileException - если поток не указывает на данные действительного аудиофайла, распознанные системой

IOException - если происходит исключение ввода/вывода

См. также:

InputStream.markSupported(), InputStream.mark(int)

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(URL url)
                                          throws UnsupportedAudioFileException,
                                                 IOException

Получает аудиоформат файла по указанному URL-адресу. URL-адрес должен указывать на данные действительного аудиофайла.

Параметры:

url — URL, из которого должна быть извлечена информация о формате файла

Возвращает:

объект AudioFileFormat, описывающий формат аудиофайла

Выбрасывает:

UnsupportedAudioFileException — если URL не указывает на данные валидного аудиофайла, распознанные системой

IOException — если произошла ошибка ввода/вывода

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(File file)
                                          throws UnsupportedAudioFileException,
                                                 IOException

Получает формат аудиофайла указанного File. File должен указывать на данные валидного аудиофайла.

Параметры:

file — File, из которого должна быть извлечена информация о формате файла

Возвращает:

объект AudioFileFormat, описывающий формат аудиофайла

Выбрасывает:

UnsupportedAudioFileException — если File не указывает на данные валидного аудиофайла, распознанные системой

IOException — если произошла ошибка ввода/вывода

getAudioInputStream

public static AudioInputStream getAudioInputStream(InputStream stream)
                                            throws UnsupportedAudioFileException,
                                                   IOException

Получает аудиопоток ввода из предоставленного потока ввода. Поток должен указывать на данные валидного аудиофайла. Реализация этого метода может потребовать нескольких парсеров для проверки потока, чтобы определить, поддерживает ли его какой-либо из них. Эти парсеры должны иметь возможность помечать поток, читать достаточно данных, чтобы определить, поддерживают ли они поток, и, если нет, сбрасывать указатель чтения потока в исходную позицию. Если поток ввода не поддерживает эти операции, этот метод может завершиться ошибкой IOException.

Параметры:

stream — поток ввода, из которого должен быть построен AudioInputStream

Возвращает:

объект AudioInputStream, основанный на данных аудиофайла, содержащихся в потоке ввода.

Выбрасывает:

UnsupportedAudioFileException — если поток не указывает на данные валидного аудиофайла, распознанные системой

IOException — если произошла ошибка ввода/вывода

См. также:

InputStream.markSupported(), InputStream.mark(int)

getAudioInputStream

public static AudioInputStream getAudioInputStream(URL url)
                                            throws UnsupportedAudioFileException,
                                                   IOException

Получает аудиопоток ввода из предоставленного URL. URL должен указывать на данные валидного аудиофайла.

Параметры:

url — URL, для которого должен быть построен AudioInputStream

Возвращает:

объект AudioInputStream, основанный на данных аудиофайла, на которые указывает URL

Выбрасывает:

UnsupportedAudioFileException — если URL не указывает на данные валидного аудиофайла, распознанные системой

IOException — если произошла ошибка ввода/вывода

getAudioInputStream

public static AudioInputStream getAudioInputStream(File file)
                                            throws UnsupportedAudioFileException,
                                                   IOException

Получает аудиопоток ввода из предоставленного File. File должен указывать на данные валидного аудиофайла.

Параметры:

file — File, для которого должен быть построен AudioInputStream

Возвращает:

объект AudioInputStream, основанный на данных аудиофайла, на которые указывает File

Выбрасывает:

UnsupportedAudioFileException — если File не указывает на данные валидного аудиофайла, распознанные системой

IOException — если произошла ошибка ввода/вывода

getAudioFileTypes

public static AudioFileFormat.Type[] getAudioFileTypes()

Получает типы файлов, для которых система предоставляет поддержку записи файлов.

Возвращает:

массив уникальных типов файлов. Если типы файлов не поддерживаются, возвращается массив длиной 0.

isFileTypeSupported

public static boolean isFileTypeSupported(AudioFileFormat.Type fileType)

Указывает, предоставляется ли системой поддержка записи файлов для указанного типа файла.

Параметры:

fileType — тип файла, для которого запрашиваются возможности записи

Возвращает:

true если тип файла поддерживается, в противном случае false

getAudioFileTypes

public static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream)

Получает типы файлов, которые система может записать из указанного потока аудио ввода.

Параметры:

stream — поток аудио ввода, для которого запрашивается поддержка типа аудиофайла

Возвращает:

массив типов файлов. Если типы файлов не поддерживаются, возвращается массив длиной 0.

isFileTypeSupported

public static boolean isFileTypeSupported(AudioFileFormat.Type fileType,
                                          AudioInputStream stream)

Указывает, можно ли записать аудиофайл указанного типа из указанного потока аудио ввода.

Параметры:

fileType — тип файла, для которого запрашиваются возможности записи

stream — поток, для которого запрашивается поддержка записи файлов

Возвращает:

true если тип файла поддерживается для этого потока аудио ввода, в противном случае false

write

public static int write(AudioInputStream stream,
                        AudioFileFormat.Type fileType,
                        OutputStream out)
                 throws IOException

Записывает поток байтов, представляющий аудиофайл указанного типа, в предоставленный поток вывода. Некоторые типы файлов требуют, чтобы длина была записана в заголовок файла; такие файлы нельзя записать от начала до конца, если длина не известна заранее. Попытка записать файл такого типа завершится ошибкой IOException, если длина в типе аудиофайла AudioSystem.NOT_SPECIFIED.

Параметры:

stream — поток аудио ввода, содержащий данные аудио, которые будут записаны в файл

fileType — тип аудиофайла для записи

out — поток, в который должны быть записаны данные файла

Возвращает:

количество байтов, записанных в поток вывода

Выбрасывает:

IOException — если произошла ошибка ввода/вывода

IllegalArgumentException — если тип файла не поддерживается системой

См. также:

isFileTypeSupported(javax.sound.sampled.AudioFileFormat.Type), getAudioFileTypes()

write

public static int write(AudioInputStream stream,
                        AudioFileFormat.Type fileType,
                        File out)
                 throws IOException

Записывает поток байтов, представляющий аудиофайл указанного типа, в предоставленный внешний файл.

Параметры:

stream — поток аудио ввода, содержащий данные аудио, которые будут записаны в файл

fileType — тип аудиофайла для записи

out — внешний файл, в который должны быть записаны данные файла

Возвращает:

количество байтов, записанных в файл

Выбрасывает:

IOException — если произошла ошибка ввода/вывода

IllegalArgumentException — если тип файла не поддерживается системой

См. также:

isFileTypeSupported(javax.sound.sampled.AudioFileFormat.Type), getAudioFileTypes()