Класс 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

См. также:

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. Подробное описание поведения open/close см. в описании класса 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. Подробное описание поведения open/close см. в описании класса 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

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

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

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

Возвращает:

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

Исключения:

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

См. также:

getSequencer

public static Sequencer getSequencer(boolean connected) throws MidiUnavailableException

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

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

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

Параметры:

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

Возвращает:

последователь по умолчанию

Исключения:

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

С момента:

1.5

См. также:

getSoundbank

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

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

Parameters:

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

Returns:

звуковой банк

Throws:

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

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

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

See Also:

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

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:

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

END_OF_DOCUMENT_MARKER

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-файла.

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

getMidiFileTypes

public static int[] getMidiFileTypes(Sequence sequence)

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

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

isFileTypeSupported

public static boolean isFileTypeSupported(int fileType, Sequence sequence)

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

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

write

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

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

Parameters:

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

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

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

Returns:

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

Throws:

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

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

NullPointerException - если in или out являются null

See Also:

write

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

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

Parameters:

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

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

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

Returns:

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

Throws:

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

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

NullPointerException - если in или out являются null

See Also:

© 1993, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.desktop/javax/sound/midi/MidiSystem.html