Интерфейс Sequencer

public interface Sequencer
extends MidiDevice

Устройство (аппаратное или программное), воспроизводящее MIDI sequence , называется секвенсором. MIDI-последовательность содержит списки временных меток MIDI-данных, например, таких, которые могут быть прочитаны из стандартного MIDI-файла. Большинство секвенсоров также предоставляют функции для создания и редактирования последовательностей.

Интерфейс Sequencer включает методы для следующих основных операций с MIDI-секвенсором:

• получение последовательности из данных MIDI-файла
• запуск и остановка воспроизведения
• переход к произвольной позиции в последовательности
• изменение темпа (скорости) воспроизведения
• синхронизация воспроизведения с внутренним часом или с полученными MIDI-сообщениями
• управление временем другого устройства

Кроме того, поддерживаются следующие операции, напрямую или косвенно через объекты, к которым Sequencer имеет доступ:

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

Поля

LOOP_CONTINUOUSLY

static final int LOOP_CONTINUOUSLY

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

Since:

1.5

См. также:

setLoopCount(int), Значения константных полей

Методы

setSequence

void setSequence(Sequence sequence)
          throws InvalidMidiDataException

Параметры:

sequence - последовательность, которая должна быть загружена.

Исключения:

InvalidMidiDataException - если последовательность содержит некорректные данные MIDI или не поддерживается.

setSequence

void setSequence(InputStream stream)
          throws IOException,
                 InvalidMidiDataException

Параметры:

stream - поток, содержащий данные файла MIDI.

Исключения:

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

InvalidMidiDataException - если в потоке обнаружены некорректные данные или поток не поддерживается.

getSequence

Sequence getSequence()

Возвращает:

текущую последовательность или null, если последовательность не установлена.

start

void start()

Исключения:

IllegalStateException - если Sequencer закрыт.

См. также:

setLoopStartPoint(long), setLoopEndPoint(long), setLoopCount(int), stop()

stop

void stop()

Останавливает запись, если она активна, и воспроизведение текущей загруженной последовательности, если таковая имеется.

Исключения:

IllegalStateException - если Sequencer закрыт.

См. также:

start(), isRunning()

isRunning

boolean isRunning()

Указывает, запущена ли Sequencer в данный момент. По умолчанию false. Sequencer запускается, когда вызывается либо start() , либо startRecording(). isRunning возвращает true , пока воспроизведение последовательности не завершится или не вызовется stop().

Возвращает:

true если Sequencer запущен, в противном случае false

startRecording

void startRecording()

Исключения:

IllegalStateException - если Sequencer закрыт.

См. также:

startRecording(), recordEnable(javax.sound.midi.Track, int), recordDisable(javax.sound.midi.Track)

stopRecording

void stopRecording()

Останавливает запись, если она активна. Воспроизведение текущей последовательности продолжается.

Исключения:

IllegalStateException - если Sequencer закрыт.

См. также:

startRecording(), isRecording()

isRecording

boolean isRecording()

Указывает, ведется ли в данный момент запись в Sequencer. По умолчанию false. Sequencer начинает запись, когда вызывается startRecording(), а затем возвращает true, пока не вызовется stop() или stopRecording().

Возвращает:

true если Sequencer записывает, в противном случае false

recordEnable

void recordEnable(Track track,
                  int channel)

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

Параметры:

track - дорожка, в которую будут записываться события

channel - канал, с которого будут приниматься события. Если для значения канала указано -1, дорожка будет получать данные со всех каналов.

Исключения:

IllegalArgumentException - выбрасывается, если дорожка не является частью текущей последовательности.

recordDisable

void recordDisable(Track track)

Отключает запись в указанную дорожку. События больше не будут записываться в эту дорожку.

Параметры:

track - дорожка для отключения записи или null для отключения записи для всех дорожек.

getTempoInBPM

float getTempoInBPM()

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

Возвращает:

текущий темп в ударах в минуту

См. также:

getTempoFactor(), setTempoInBPM(float), getTempoInMPQ()

setTempoInBPM

void setTempoInBPM(float bpm)

Устанавливает темп в ударах в минуту. Фактический темп воспроизведения является произведением заданного значения и множителя темпа.

Параметры:

bpm - желаемый новый темп в ударах в минуту

См. также:

getTempoFactor(), setTempoInMPQ(float), getTempoInBPM()

getTempoInMPQ

float getTempoInMPQ()

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

Возвращает:

текущий темп в микросекундах на четверть ноты

См. также:

getTempoFactor(), setTempoInMPQ(float), getTempoInBPM()

setTempoInMPQ

void setTempoInMPQ(float mpq)

Устанавливает темп в микросекундах на четверть ноты. Фактический темп воспроизведения является произведением заданного значения и множителя темпа.

Параметры:

mpq - желаемый новый темп в микросекундах на четверть ноты.

См. также:

getTempoFactor(), setTempoInBPM(float), getTempoInMPQ()

setTempoFactor

void setTempoFactor(float factor)

Параметры:

factor - требуемый множитель темпа

См. также:

getTempoFactor()

getTempoFactor

float getTempoFactor()

Возвращает текущий множитель темпа для секвенсора. По умолчанию 1.0.

Возвращает:

множитель темпа.

См. также:

setTempoFactor(float)

getTickLength

long getTickLength()

Получает длину текущей последовательности, выраженную в тиках MIDI, или 0, если последовательность не установлена.

Возвращает:

длину последовательности в тиках

getTickPosition

long getTickPosition()

Получает текущую позицию в последовательности, выраженную в тиках MIDI. (Продолжительность тика в секундах определяется как темпом, так и разрешением временной шкалы, хранящейся в Sequence.)

Возвращает:

текущий тик

См. также:

setTickPosition(long)

setTickPosition

void setTickPosition(long tick)

Устанавливает текущую позицию секвенсора в тиках MIDI

Параметры:

tick - желаемая позиция тика

См. также:

getTickPosition()

getMicrosecondLength

long getMicrosecondLength()

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

Возвращает:

длину последовательности в микросекундах.

getMicrosecondPosition

long getMicrosecondPosition()

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

Указано:

getMicrosecondPosition в интерфейсе MidiDevice

Возвращает:

текущую позицию в микросекундах

См. также:

setMicrosecondPosition(long)

setMicrosecondPosition

void setMicrosecondPosition(long microseconds)

Устанавливает текущую позицию в последовательности, выраженную в микросекундах

Параметры:

microseconds - желаемая позиция в микросекундах

См. также:

getMicrosecondPosition()

setMasterSyncMode

void setMasterSyncMode(Sequencer.SyncMode sync)

Устанавливает источник информации о времени, используемый этим секвенсором. Секвенсор синхронизируется с главным источником, который представляет собой внутренние часы, MIDI-часы или MIDI-код времени, в зависимости от значения sync. Аргумент sync должен быть одним из поддерживаемых режимов, как возвращаемых getMasterSyncModes().

Параметры:

sync - желаемый режим синхронизации главного источника

См. также:

Sequencer.SyncMode.INTERNAL_CLOCK, Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, getMasterSyncMode()

getMasterSyncMode

Sequencer.SyncMode getMasterSyncMode()

Получает текущий режим синхронизации главного источника для этого секвенсора.

Возвращает:

текущий режим синхронизации главного источника

См. также:

setMasterSyncMode(Sequencer.SyncMode), getMasterSyncModes()

getMasterSyncModes

Sequencer.SyncMode[] getMasterSyncModes()

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

Возвращает:

доступные режимы синхронизации главного источника

См. также:

Sequencer.SyncMode.INTERNAL_CLOCK, Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, getMasterSyncMode(), setMasterSyncMode(Sequencer.SyncMode)

setSlaveSyncMode

void setSlaveSyncMode(Sequencer.SyncMode sync)

Устанавливает режим синхронизации ведомого источника для секвенсора. Это указывает на тип информации о времени, отправляемой секвенсором его получателю. Аргумент sync должен быть одним из поддерживаемых режимов, как возвращаемых getSlaveSyncModes().

Параметры:

sync - желаемый режим синхронизации ведомого источника

См. также:

Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, Sequencer.SyncMode.NO_SYNC, getSlaveSyncModes()

getSlaveSyncMode

Sequencer.SyncMode getSlaveSyncMode()

Получает текущий режим синхронизации ведомого источника для этого секвенсора.

Возвращает:

текущий режим синхронизации ведомого источника

См. также:

setSlaveSyncMode(Sequencer.SyncMode), getSlaveSyncModes()

getSlaveSyncModes

Sequencer.SyncMode[] getSlaveSyncModes()

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

Возвращает:

доступные режимы синхронизации ведомого источника

См. также:

Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, Sequencer.SyncMode.NO_SYNC

setTrackMute

void setTrackMute(int track,
                  boolean mute)

Устанавливает состояние отключения трека. Этот метод может завершиться неудачей по ряду причин. Например, указанный номер трека может быть недействительным для текущей последовательности, или секвенсор может не поддерживать эту функциональность. Приложение, которому необходимо проверить, выполнилась ли эта операция успешно, должно последовать за этим вызовом вызовом getTrackMute(int).

Параметры:

track - номер трека. Трек в текущей последовательности пронумерованы с 0 до количества треков в последовательности минус 1.

mute - новое состояние отключения для трека. true означает, что трек должен быть отключен, false означает, что трек должен быть включен.

См. также:

getSequence()

getTrackMute

boolean getTrackMute(int track)

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

Параметры:

track - номер трека. Трек в текущей последовательности пронумерованы с 0 до количества треков в последовательности минус 1.

Возвращает:

true если отключен, false если нет.

setTrackSolo

void setTrackSolo(int track,
                  boolean solo)

Параметры:

track - номер трека. Трек в текущей последовательности пронумерованы с 0 до количества треков в последовательности минус 1.

solo - новое состояние сопоставления для трека. true означает, что трек должен быть включен в режим сопоставления, false означает, что трек не должен быть включен в режим сопоставления.

См. также:

getSequence()

getTrackSolo

boolean getTrackSolo(int track)

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

Параметры:

track - номер трека. Трек в текущей последовательности пронумерованы с 0 до количества треков в последовательности минус 1.

Возвращает:

true если включен в режим сопоставления, false если нет.

addMetaEventListener

boolean addMetaEventListener(MetaEventListener listener)

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

Параметры:

listener - добавляемый слушатель

Возвращает:

true если слушатель был успешно добавлен, в противном случае false

См. также:

removeMetaEventListener(javax.sound.midi.MetaEventListener), MetaEventListener, MetaMessage

removeMetaEventListener

void removeMetaEventListener(MetaEventListener listener)

Удаляет указанного слушателя мета-событий из списка зарегистрированных слушателей этого секвенсора, если он, на самом деле, зарегистрирован.

Параметры:

listener - слушатель мета-событий для удаления

См. также:

addMetaEventListener(javax.sound.midi.MetaEventListener)

addControllerEventListener

int[] addControllerEventListener(ControllerEventListener listener,
                                 int[] controllers)

Параметры:

listener - слушатель событий управления, добавляемый в список зарегистрированных слушателей

controllers - номера MIDI-контроллеров, для которых требуется уведомление об изменениях

Возвращает:

номера всех MIDI-контроллеров, изменения которых теперь будут сообщаться указанному слушателю

См. также:

removeControllerEventListener(javax.sound.midi.ControllerEventListener, int[]), ControllerEventListener

removeControllerEventListener

int[] removeControllerEventListener(ControllerEventListener listener,
                                    int[] controllers)

Удаляет интерес слушателя событий управления к одному или нескольким типам событий управления. Аргумент controllers — массив MIDI-номеров, соответствующих контроллерам, для которых слушатель больше не должен получать уведомления об изменениях. Чтобы полностью удалить этого слушателя из списка зарегистрированных слушателей, передайте null для controllers. Возвращаемый массив содержит номера MIDI-контроллеров, изменения которых теперь будут сообщаться слушателю. Длина массива равна 0, если слушатель не будет получать уведомления об изменениях для каких-либо контроллеров.

Параметры:

listener - старый слушатель

controllers - номера MIDI-контроллеров, для которых должна быть отменена уведомление о изменении, или null для отмены для всех контроллеров

Возвращает:

номера всех MIDI-контроллеров, изменения которых теперь будут сообщаться указанному слушателю

См. также:

addControllerEventListener(javax.sound.midi.ControllerEventListener, int[])

установить начальную точку цикла

void setLoopStartPoint(long tick)

Параметры:

tick - начальная позиция цикла в MIDI-метках (нумерация с нуля)

Исключения:

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

С:

1.5

См. также:

setLoopEndPoint(long), setLoopCount(int), getLoopStartPoint(), start()

получить начальную точку цикла

long getLoopStartPoint()

Получает начальную позицию цикла в MIDI-метках.

Возвращает:

начальную позицию цикла в MIDI-метках (нумерация с нуля)

С:

1.5

См. также:

setLoopStartPoint(long)

установить конечную точку цикла

void setLoopEndPoint(long tick)

Параметры:

tick - конечная позиция цикла в MIDI-метках (нумерация с нуля) или -1 для обозначения последней метки

Исключения:

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

С:

1.5

См. также:

setLoopStartPoint(long), setLoopCount(int), getLoopEndPoint(), start()

получить конечную точку цикла

long getLoopEndPoint()

Получает конечную позицию цикла в MIDI-метках.

Возвращает:

конечную позицию цикла в MIDI-метках (нумерация с нуля) или -1 для обозначения конца последовательности

С:

1.5

См. также:

setLoopEndPoint(long)

установить количество повторений цикла

void setLoopCount(int count)

Параметры:

count - количество раз, когда воспроизведение должно возвращаться из конечной позиции цикла в начальную позицию цикла, или LOOP_CONTINUOUSLY для обозначения непрерывного циклирования до его прерывания

Исключения:

IllegalArgumentException - если count отрицательно и не равно LOOP_CONTINUOUSLY

С:

1.5

См. также:

setLoopStartPoint(long), setLoopEndPoint(long), getLoopCount(), start()

получить количество повторений цикла

int getLoopCount()

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

Возвращает:

количество циклов после которого воспроизведение переходит к концу последовательности

С:

1.5

См. также:

setLoopCount(int), start()