Класс MidiSystem

java.lang.Object

javax.sound.midi.MidiSystem

public class MidiSystem extends Object

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

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

Создать экземпляр 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. Имя устройства сопоставляется со значением String, возвращаемым методом getName класса MidiDevice.Info. Имя класса или имя устройства можно опустить. Если указано только имя класса, завершающий символ решётки можно не указывать.

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

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

Например, свойство 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-файла.

Методы, объявленные в классе 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. Чтобы освободить системные ресурсы, занятые MidiDevice, необходимо закрыть все открытые экземпляры Receiver. Подробное описание поведения при открытии и закрытии см. в описании интерфейса 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. Чтобы освободить системные ресурсы, занятые MidiDevice, необходимо закрыть все открытые экземпляры Transmitter. Подробное описание поведения при открытии и закрытии см. в описании интерфейса 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(). Для подключения из Sequencer получается экземпляр Transmitter, после чего задаётся его Receiver. Закрытие и повторное открытие секвенсора восстанавливает подключение к устройству по умолчанию.

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

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

Возвращает:

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

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

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

См. также:

getSequencer

public static Sequencer getSequencer(boolean connected) throws MidiUnavailableException

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

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

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

Параметры:

connected — указывает, подключён ли возвращаемый Sequencer к Synthesizer по умолчанию

Возвращает:

секвенсор по умолчанию

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

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

Начиная с:

1.5

См. также:

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.

Параметры:: url — источник данных банка звуков
Возвращает:: банк звуков
Выбрасывает:: InvalidMidiDataException — если URL не указывает на допустимые данные банка звуков MIDI, распознаваемые системой; IOException — если при загрузке банка звуков произошла ошибка ввода-вывода; NullPointerException — если url имеет значение null

getSoundbank

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

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

Параметры:: file — источник данных банка звуков
Возвращает:: банк звуков
Выбрасывает:: InvalidMidiDataException — если File не указывает на допустимые данные банка звуков MIDI, распознаваемые системой; IOException — если при загрузке банка звуков произошла ошибка ввода-вывода; NullPointerException — если file имеет значение null

getMidiFileFormat

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

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

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

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

Параметры:

stream — входной поток, из которого следует извлечь информацию о формате файла

Возвращает:

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

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

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

IOException — если при обращении к потоку возникает исключение ввода-вывода

NullPointerException — если stream имеет значение null

См. также:

getMidiFileFormat

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

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

Параметры:

url — URL, из которого следует извлечь информацию о формате файла

Возвращает:

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

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

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

IOException — если при обращении к URL возникает исключение ввода-вывода

NullPointerException — если url имеет значение null

См. также:

getMidiFileFormat

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

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

Параметры:

file — File, из которого следует извлечь информацию о формате файла

Возвращает:

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

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

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

IOException — если при обращении к файлу возникает исключение ввода-вывода

NullPointerException — если file имеет значение null

См. также:

getSequence

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

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

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

Параметры:

stream — входной поток, из которого следует создать Sequence

Возвращает:

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

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

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

IOException — если при обращении к потоку возникает исключение ввода-вывода

NullPointerException — если stream имеет значение null

См. также:

getSequence

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

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

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

Параметры:: url — URL, из которого следует создать Sequence
Возвращает:: объект Sequence, созданный на основе данных MIDI-файла, на который указывает URL
Выбрасывает:: 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 из данных файла возникают ошибки.

Параметры:: file — File, из которого следует создать Sequence
Возвращает:: объект Sequence, созданный на основе данных MIDI-файла, на который указывает File
Выбрасывает:: InvalidMidiDataException — если File не указывает на допустимые данные MIDI-файла, распознаваемые системой; IOException — если возникает исключение ввода-вывода; NullPointerException — если file имеет значение null

getMidiFileTypes

public static int[] getMidiFileTypes()

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

Возвращает:: массив уникальных типов файлов. Если ни один тип файлов не поддерживается, возвращается массив длины 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

См. также:

write

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

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

Параметры:

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

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

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

Возвращает:

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

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

IOException — если возникает исключение ввода-вывода

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

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

См. также:

© 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://docs.oracle.com/en/java/javase/25/docs/api/java.desktop/javax/sound/midi/MidiSystem.html