Класс MidiSystem

java.lang.Object

javax.sound.midi.MidiSystem

public class MidiSystem extends Object

Класс MidiSystem предоставляет доступ к ресурсам установленной MIDI-системы, включая устройства, такие как синтезаторы, секвенсоры и порты MIDI-ввода и -вывода. Типичное простое MIDI-приложение может начать работу, вызвав один или несколько методов MidiSystem, чтобы узнать, какие устройства установлены, и получить нужные для приложения.

Класс также содержит методы для чтения файлов, потоков и URL-адресов, содержащих стандартные данные MIDI-файлов или звуковые банки. Вы можете запросить формат указанного MIDI-файла у MidiSystem.

Невозможно создать экземпляр MidiSystem; все методы являются статическими.

Свойства могут использоваться для указания стандартных устройств MIDI. Рассматриваются как системные свойства, так и файл свойств. Файл свойств "sound.properties" читается из места, специфичного для реализации (обычно это каталог conf в каталоге установки Java). Необязательное системное свойство "javax.sound.config.file" может использоваться для указания файла свойств, который будет считаться начальной конфигурацией. Если свойство существует как системное свойство, так и в файле свойств, приоритет имеет системное свойство. Если ни то, ни другое не указано, выбирается подходящий по умолчанию среди доступных устройств. Синтаксис файла свойств описан в Properties.load. В следующей таблице перечислены доступные ключи свойств и методы, которые их учитывают:

Ключи свойств MIDI-системы
Ключ свойства	Интерфейс	Затронутый метод
`javax.sound.midi.Receiver`	`Receiver`	`getReceiver()`
`javax.sound.midi.Sequencer`	`Sequencer`	`getSequencer()`
`javax.sound.midi.Synthesizer`	`Synthesizer`	`getSynthesizer()`
`javax.sound.midi.Transmitter`	`Transmitter`	`getTransmitter()`

Значение свойства состоит из имени класса провайдера и имени устройства, разделенных символом хэша ("#"). Имя класса провайдера — полное имя конкретного класса MIDI device provider. Имя устройства сопоставляется с именем, возвращаемым методом getName объекта MidiDevice.Info. Можно опустить либо имя класса, либо имя устройства. Если указано только имя класса, конечный символ хэша является необязательным.

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

Если указано имя устройства, результат поиска объектов MidiDevice.Info осуществляется следующим образом: будет возвращен первый объект, имя которого совпадает, и чей объект MidiDevice реализует соответствующий интерфейс. Если подходящий объект MidiDevice.Info не найден или имя устройства не указано, будет возвращено первое подходящее устройство из полученного списка. Для секвенсора и синтезатора устройство подходит, если оно реализует соответствующий интерфейс; для приемника и передатчика устройство подходит, если оно не реализует ни секвенсор, ни синтезатор, и предоставляет по крайней мере одного приемника или передатчика, соответственно.

Например, свойство javax.sound.midi.Receiver со значением "com.sun.media.sound.MidiProvider#SunMIDI1" приведет к следующим последствиям при вызове getReceiver: если класс com.sun.media.sound.MidiProvider существует в списке установленных провайдеров устройств MIDI, будет возвращено первое устройство Receiver с именем "SunMIDI1". Если его невозможно найти, будет возвращено первое устройство Receiver из этого провайдера, независимо от имени. Если такого нет, будет возвращено первое устройство Receiver с именем "SunMIDI1" в списке всех устройств (как возвращается getMidiDeviceInfo), или, если и это не найдено, будет возвращено первое устройство Receiver, которое можно найти в списке всех устройств. Если и это не сработает, будет выброшено исключение MidiUnavailableException.

Краткое описание методов

Модификатор и тип	Метод	Описание
`static MidiDevice`	`getMidiDevice(MidiDevice.Info info)`	Получает запрашиваемое MIDI-устройство.
`static MidiDevice.Info[]`	`getMidiDeviceInfo()`	Получает массив объектов информации, представляющих набор всех доступных на системе MIDI-устройств.
`static MidiFileFormat`	`getMidiFileFormat(File file)`	Получает формат MIDI-файла указанного `File`.
`static MidiFileFormat`	`getMidiFileFormat(InputStream stream)`	Получает формат MIDI-файла данных в указанном входном потоке.
`static MidiFileFormat`	`getMidiFileFormat(URL url)`	Получает формат MIDI-файла данных в указанном URL.
`static int[]`	`getMidiFileTypes()`	Получает набор типов MIDI-файлов, для которых система предоставляет поддержку записи файлов.
`static int[]`	`getMidiFileTypes(Sequence sequence)`	Получает набор типов MIDI-файлов, которые система может записать из указанной последовательности.
`static Receiver`	`getReceiver()`	Получает MIDI-приемник из внешнего порта MIDI или другого устройства по умолчанию.
`static Sequence`	`getSequence(File file)`	Получает MIDI-последовательность из указанного `File`.
`static Sequence`	`getSequence(InputStream stream)`	Получает MIDI-последовательность из указанного входного потока.
`static Sequence`	`getSequence(URL url)`	Получает MIDI-последовательность из указанного URL.
`static Sequencer`	`getSequencer()`	Получает стандартный `Sequencer`, подключенный к устройству по умолчанию.
`static Sequencer`	`getSequencer(boolean connected)`	Получает стандартный `Sequencer`, необязательно подключенный к устройству по умолчанию.
`static Soundbank`	`getSoundbank(File file)`	Создаёт `Soundbank`, считывая его из указанного `File`.
`static Soundbank`	`getSoundbank(InputStream stream)`	Создаёт звуковой банк MIDI, считывая его из указанного потока.
`static Soundbank`	`getSoundbank(URL url)`	Создаёт `Soundbank`, считывая его из указанного URL.
`static Synthesizer`	`getSynthesizer()`	Получает стандартный синтезатор.
`static Transmitter`	`getTransmitter()`	Получает MIDI-передатчик из внешнего порта MIDI или другого источника по умолчанию.
`static boolean`	`isFileTypeSupported(int fileType)`	Указывает, предоставляется ли системой поддержка записи файлов для указанного типа MIDI-файлов.
`static boolean`	`isFileTypeSupported(int fileType, Sequence sequence)`	Указывает, можно ли записать MIDI-файл указанного типа из указанной последовательности.
`static int`	`write(Sequence in, int type, File out)`	Записывает поток байтов, представляющий файл указанного типа MIDI-файла, во внешний файл.
`static int`	`write(Sequence in, int fileType, OutputStream out)`	Записывает поток байтов, представляющий файл указанного типа MIDI-файла, в предоставленный выходной поток.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Подробное описание методов

getMidiDeviceInfo

public static MidiDevice.Info[] getMidiDeviceInfo()

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

Возвращает:: массив объектов MidiDevice.Info, по одному для каждого установленного устройства MIDI. Если такие устройства не установлены, возвращается массив длиной 0.

getMidiDevice

public static MidiDevice getMidiDevice(MidiDevice.Info info) throws MidiUnavailableException

Получает запрашиваемое устройство MIDI.

Параметры:

info - объект информации об устройстве, представляющий желаемое устройство

Возвращает:

запрашиваемое устройство

Исключение:

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

IllegalArgumentException - если объект информации не представляет установленное на системе устройство MIDI

NullPointerException - если info является null

См. также:

getMidiDeviceInfo()

getReceiver

public static Receiver getReceiver() throws MidiUnavailableException

Получает приемник MIDI из внешнего порта MIDI или другого устройства по умолчанию. Возвращаемый приемник всегда реализует интерфейс MidiDeviceReceiver.

Если системная переменная javax.sound.midi.Receiver определена, или она определена в файле "sound.properties", она используется для идентификации устройства, предоставляющего приемник по умолчанию. Подробности см. в class description.

Если подходящий порт MIDI недоступен, приемник извлекается из установленного синтезатора.

Если родной приемник, предоставляемый устройством по умолчанию, не реализует интерфейс MidiDeviceReceiver, он будет обернут в класс-обертку, реализующий интерфейс MidiDeviceReceiver. Соответствующие вызовы методов Receiver будут перенаправлены на родной приемник.

Если этот метод выполняется успешно, MidiDevice к которому принадлежит Receiver, открывается неявно, если он еще не открыт. Можно закрыть неявно открытое устройство, вызвав close у возвращенного Receiver. Все открытые экземпляры Receiver должны быть закрыты, чтобы освободить системные ресурсы, удерживаемые MidiDevice. Подробное описание поведения открывания/закрытия см. в описании класса MidiDevice.

Возвращает:: приемник MIDI по умолчанию
Исключение:: MidiUnavailableException - если приемник по умолчанию недоступен из-за ограничений ресурсов или в системе нет устройства, предоставляющего приемники

getTransmitter

public static Transmitter getTransmitter() throws MidiUnavailableException

Получает передатчик MIDI из внешнего порта MIDI или другого источника по умолчанию. Возвращаемый передатчик всегда реализует интерфейс MidiDeviceTransmitter.

Если системная переменная javax.sound.midi.Transmitter определена, или она определена в файле "sound.properties", она используется для идентификации устройства, предоставляющего передатчик по умолчанию. Подробности см. в class description.

Если родной передатчик, предоставляемый устройством по умолчанию, не реализует интерфейс MidiDeviceTransmitter, он будет обернут в класс-обертку, реализующий интерфейс MidiDeviceTransmitter. Соответствующие вызовы методов Transmitter будут перенаправлены на родной передатчик.

Если этот метод выполняется успешно, MidiDevice к которому принадлежит Transmitter, открывается неявно, если он еще не открыт. Можно закрыть неявно открытое устройство, вызвав close у возвращенного Transmitter. Все открытые экземпляры Transmitter должны быть закрыты, чтобы освободить системные ресурсы, удерживаемые MidiDevice. Подробное описание поведения открывания/закрытия см. в описании класса MidiDevice.

Возвращает:: передатчик MIDI по умолчанию
Исключение:: MidiUnavailableException - если передатчик по умолчанию недоступен из-за ограничений ресурсов, или в системе нет устройства, предоставляющего передатчики

getSynthesizer

public static Synthesizer getSynthesizer() throws MidiUnavailableException

Получает синтезатор по умолчанию.

Если системная переменная javax.sound.midi.Synthesizer определена, или она определена в файле "sound.properties", она используется для идентификации синтезатора по умолчанию. Подробности см. в class description.

Возвращает:: синтезатор по умолчанию
Исключение:: MidiUnavailableException - если синтезатор недоступен из-за ограничений ресурсов, или синтезатор не установлен в системе

getSequencer

public static Sequencer getSequencer() throws MidiUnavailableException

Получает последователь Sequencer, подключенный к устройству по умолчанию. Возвращаемый экземпляр Sequencer подключен к стандартному Synthesizer, как возвращается getSynthesizer(). Если Synthesizer недоступен или стандартный Synthesizer не может быть открыт, sequencer подключается к стандартному Receiver, как возвращается getReceiver(). Подключение выполняется путем получения экземпляра Transmitter из Sequencer и установки его Receiver. Закрытие и повторное открытие последователя восстановит подключение к устройству по умолчанию.

Этот метод эквивалентен вызову getSequencer(true).

Если системная переменная javax.sound.midi.Sequencer определена, или она определена в файле "sound.properties", она используется для идентификации последователя по умолчанию. Подробности см. в class description.

Возвращает:

стандартный последователь, подключенный к стандартному приемнику

Исключение:

MidiUnavailableException - если последователь недоступен из-за ограничений ресурсов, или Receiver недоступен ни одним установленным MidiDevice, или последователь не установлен в системе

См. также:

getSequencer(boolean)
getSynthesizer()
getReceiver()

getSequencer

public static Sequencer getSequencer(boolean connected) throws MidiUnavailableException

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

Если connected равно true, возвращаемый экземпляр Sequencer подключается к стандартному Synthesizer, как возвращается getSynthesizer(). Если Synthesizer недоступен, или стандартный Synthesizer не может быть открыт, sequencer подключается к стандартному Receiver, как возвращается getReceiver(). Подключение выполняется путем получения экземпляра Transmitter из Sequencer и установки его Receiver. Закрытие и повторное открытие последователя восстановит подключение к устройству по умолчанию.

Если connected равно false, возвращаемый экземпляр Sequencer не подключен, у него нет открытых Transmitters. Для воспроизведения последователя на устройстве MIDI или Synthesizer необходимо получить Transmitter и установить его Receiver.

Параметры:

connected - подключать ли возвращаемый Sequencer к стандартному Synthesizer

Возвращает:

стандартный последователь

Исключение:

MidiUnavailableException - если последователь недоступен из-за ограничений ресурсов, или последователь не установлен в системе, или если connected равно true, и Receiver недоступен ни одним установленным MidiDevice

С:

1.5

См. также:

getSynthesizer()
getReceiver()

getSoundbank

public static Soundbank getSoundbank(InputStream stream) throws InvalidMidiDataException, IOException

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

Параметры:

stream - источник данных звуковой библиотеки

Возвращает:

звуковая библиотека

Исключение:

InvalidMidiDataException - если поток не указывает на действительные данные звуковой библиотеки MIDI, распознаваемые системой

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

NullPointerException - если stream является null

См. также:

getSoundbank

public static Soundbank getSoundbank(URL url) throws InvalidMidiDataException, IOException

Создаёт Soundbank , считывая его из указанного URL. URL должен указывать на допустимый MIDI-файл звуковой библиотеки.

Parameters:: url - источник данных звуковой библиотеки
Returns:: звуковая библиотека
Throws:: InvalidMidiDataException - если URL не указывает на допустимые данные MIDI-звуковой библиотеки, распознаваемые системой; IOException - если произошла ошибка ввода/вывода при загрузке звуковой библиотеки; NullPointerException - если url является null

getSoundbank

public static Soundbank getSoundbank(File file) throws InvalidMidiDataException, IOException

Создаёт Soundbank , считывая его из указанного File. File должен указывать на допустимый MIDI-файл звуковой библиотеки.

Parameters:: file - источник данных звуковой библиотеки
Returns:: звуковая библиотека
Throws:: InvalidMidiDataException - если File не указывает на допустимые данные MIDI-звуковой библиотеки, распознаваемые системой; IOException - если произошла ошибка ввода/вывода при загрузке звуковой библиотеки; NullPointerException - если file является null

getMidiFileFormat

public static MidiFileFormat getMidiFileFormat(InputStream stream) throws InvalidMidiDataException, IOException

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

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

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

Parameters:

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

Returns:

объект MidiFileFormat, описывающий формат MIDI-файла

Throws:

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

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

NullPointerException - если stream является null

See Also:

getMidiFileFormat

public static MidiFileFormat getMidiFileFormat(URL url) throws InvalidMidiDataException, IOException

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

Parameters:

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

Returns:

объект MidiFileFormat, описывающий формат MIDI-файла

Throws:

InvalidMidiDataException - если URL не указывает на допустимые данные MIDI-файла, распознаваемые системой

IOException - если при доступе к URL произошла ошибка ввода/вывода

NullPointerException - если url является null

See Also:

getMidiFileFormat(InputStream)
getMidiFileFormat(File)

getMidiFileFormat

public static MidiFileFormat getMidiFileFormat(File file) throws InvalidMidiDataException, IOException

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

Parameters:

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

Returns:

объект MidiFileFormat, описывающий формат MIDI-файла

Throws:

InvalidMidiDataException - если File не указывает на допустимые данные MIDI-файла, распознаваемые системой

IOException - если при доступе к файлу произошла ошибка ввода/вывода

NullPointerException - если file является null

See Also:

getMidiFileFormat(InputStream)
getMidiFileFormat(URL)

getSequence

public static Sequence getSequence(InputStream stream) throws InvalidMidiDataException, IOException

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

Эта операция может быть успешной только для файлов типа, который может быть проанализирован установленным читателем файлов. Она может завершиться с ошибкой InvalidMidiDataException даже для допустимых файлов, если установленный читатель файлов несовместим. Она также завершится с ошибкой InvalidMidiDataException , если совместимый читатель файлов установлен, но при построении объекта Sequence из данных файла возникают ошибки.

Parameters:

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

Returns:

объект Sequence, основанный на данных MIDI-файла, содержащихся в потоке ввода

Throws:

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

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

NullPointerException - если stream является null

See Also:

getSequence

public static Sequence getSequence(URL url) throws InvalidMidiDataException, IOException

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

Эта операция может быть успешной только для файлов типа, который может быть проанализирован установленным читателем файлов. Она может завершиться с ошибкой InvalidMidiDataException даже для допустимых файлов, если установленный читатель файлов несовместим. Она также завершится с ошибкой InvalidMidiDataException , если совместимый читатель файлов установлен, но при построении объекта Sequence из данных файла возникают ошибки.

Parameters:: url - URL, из которого должна быть построена Sequence
Returns:: объект Sequence, основанный на данных MIDI-файла, на который указывает URL
Throws:: InvalidMidiDataException - если URL не указывает на допустимые данные MIDI-файла, распознаваемые системой; IOException - если при доступе к URL произошла ошибка ввода/вывода; NullPointerException - если url является null

getSequence

public static Sequence getSequence(File file) throws InvalidMidiDataException, IOException

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

Эта операция может быть успешной только для файлов типа, который может быть проанализирован установленным читателем файлов. Она может завершиться с ошибкой InvalidMidiDataException даже для допустимых файлов, если установленный читатель файлов несовместим. Она также завершится с ошибкой InvalidMidiDataException , если совместимый читатель файлов установлен, но при построении объекта Sequence из данных файла возникают ошибки.

Parameters:: file - File , из которого должна быть построена Sequence
Returns:: объект Sequence, основанный на данных MIDI-файла, на который указывает File
Throws:: InvalidMidiDataException - если File не указывает на допустимые данные MIDI-файла, распознаваемые системой; IOException - если произошла ошибка ввода/вывода; NullPointerException - если file является null

getMidiFileTypes

public static int[] getMidiFileTypes()

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

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

isFileTypeSupported

public static boolean isFileTypeSupported(int fileType)

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

Параметры:: fileType - тип файла, для которого запрашиваются возможности записи
Возвращает:: true если тип файла поддерживается, иначе false

getMidiFileTypes

public static int[] getMidiFileTypes(Sequence sequence)

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

Параметры:: sequence - последовательность, для которой запрашивается поддержка типа файла MIDI
Возвращает:: набор уникальных поддерживаемых типов файлов. Если типы файлов не поддерживаются, возвращает массив длиной 0.
Исключения:: NullPointerException - если sequence имеет значение null

isFileTypeSupported

public static boolean isFileTypeSupported(int fileType, Sequence sequence)

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

Параметры:: fileType - тип файла, для которого запрашиваются возможности записи; sequence - последовательность, для которой запрашивается поддержка записи файла
Возвращает:: true если тип файла поддерживается для этой последовательности, иначе false
Исключения:: NullPointerException - если sequence имеет значение null

write

public static int write(Sequence in, int fileType, OutputStream out) throws IOException

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

Параметры:

in - последовательность, содержащая данные MIDI, которые должны быть записаны в файл

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

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

Возвращает:

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

Исключения:

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

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

NullPointerException - если in или out имеют значение null

См. также:

isFileTypeSupported(int, Sequence)
getMidiFileTypes(Sequence)

write

public static int write(Sequence in, int type, File out) throws IOException

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

Параметры:

in - последовательность, содержащая данные MIDI, которые должны быть записаны в файл

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

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

Возвращает:

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

Исключения:

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

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

NullPointerException - если in или out имеют значение null

См. также:

isFileTypeSupported(int, Sequence)
getMidiFileTypes(Sequence)

© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/javax/sound/midi/MidiSystem.html