Класс 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. Имя устройства сопоставляется с String, возвращаемым методом 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 - если объект info не представляет устройство 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

Получает Sequencer, подключенный к устройству по умолчанию. Возвращаемый Sequencer подключен к по умолчанию Synthesizer, как возвращается getSynthesizer(). Если нет Synthesizer доступно, или по умолчанию Synthesizer не может быть открыто, то sequencer подключен к по умолчанию 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, возвращаемый экземпляр 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

См. также:

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

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-данные файла для типа файла, распознаваемого системой.

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-данные файла для типа файла, распознаваемого системой.

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-данные файла для типа файла, распознаваемого системой.

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

См. также:

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, 2023, 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/21/docs/api/java.desktop/javax/sound/midi/MidiSystem.html