Модуль midi может отправлять выходные данные на MIDI-устройства и получать входные данные с MIDI-устройств. Он также может перечислять MIDI-устройства в системе.

Модуль midi поддерживает реальные и виртуальные MIDI-устройства.

Он использует библиотеку portmidi. Портируется на любые платформы, поддерживаемые portmidi (в настоящее время Windows, Mac OS X и Linux).

В настоящее время используется pyportmidi, но в будущем может использовать собственные связи. Связи pyportmidi включены в pygame.

Это события pygame (pygame.event), предназначенные для использования с MIDI. Событие MIDIIN используется pygame.midi.midis2events() при преобразовании MIDI-событий в события pygame.

MIDIIN
MIDIOUT

pygame.midi.init()

инициализирует модуль midi

init() -> None

Инициализирует модуль pygame.midi. Должен быть вызван перед использованием модуля pygame.midi.

Безопасно вызывать это несколько раз.

pygame.midi.quit()

деиннициализирует модуль midi

quit() -> None

Деиннициализирует модуль pygame.midi. Если pygame.midi.init() был вызван для инициализации модуля pygame.midi, то эта функция будет вызвана автоматически при завершении программы.

Безопасно вызывать эту функцию несколько раз.

pygame.midi.get_init()

возвращает True, если модуль midi в настоящее время инициализирован

get_init() -> bool

Получает состояние инициализации модуля pygame.midi.

Возвращает

True если модуль pygame.midi в настоящее время инициализирован.

Тип возвращаемого значения

bool

Новый в pygame 1.9.5.

pygame.midi.Input

Input используется для получения MIDI-входа с MIDI-устройств.

Input(device_id) -> None

Input(device_id, buffer_size) -> None

Параметры

• device_id (int) -- идентификатор MIDI-устройства

• buffer_size (int) -- (необязательно) количество буферизуемых событий ввода

close()

закрывает MIDI-поток, очищая все ожидающие буферы.

close() -> None

PortMidi пытается закрыть открытые потоки при выходе приложения.

Примечание

Это особенно сложно в Windows.

poll()

возвращает True, если есть данные, или False, если нет.

poll() -> bool

Используется для указания наличия данных.

Возвращает

True если есть данные, False в противном случае

Тип возвращаемого значения

bool

Возможные исключения

MidiException -- при ошибке

read()

считывает num_events MIDI-событий из буфера.

read(num_events) -> midi_event_list

Считывает данные из буфера ввода и возвращает MIDI-события.

Параметры

num_events (int) -- количество считываемых событий ввода

Возвращает

формат midi_event_list [[[status, data1, data2, data3], timestamp], ...]

Тип возвращаемого значения

list

pygame.midi.Output

Output используется для отправки midi на устройство вывода

Output(device_id) -> None

Output(device_id, latency=0) -> None

Output(device_id, buffer_size=256) -> None

Output(device_id, latency, buffer_size) -> None

buffer_size определяет количество событий вывода, которые будут буферизованы, ожидая вывода. В некоторых случаях (см. ниже) PortMidi вообще не буферизует вывод и просто передает данные в API более низкого уровня, в этом случае buffersize игнорируется.

latency — задержка в миллисекундах, применяемая к отметкам времени, чтобы определить, когда фактически должен произойти вывод. Если latency меньше 0, предполагается 0.

Если latency равно нулю, отметки времени игнорируются, и весь вывод передается немедленно. Если latency больше нуля, вывод откладывается до момента времени сообщения плюс latency. В некоторых случаях PortMidi может обеспечить более точное время, чем ваше приложение, передавая отметки времени драйверу устройства или оборудованию. Задержка также может помочь вам синхронизировать midi-данные с аудиоданными, согласовав задержку midi с задержкой буфера аудио.

Примечание

Время измеряется относительно источника времени, указанного в time_proc. Отметки времени являются абсолютными, а не относительными задержками или смещениями.

abort()

немедленно прерывает исходящие сообщения

abort() -> None

Вызывающий должен немедленно закрыть порт вывода; этот вызов может привести к передаче частичного midi-сообщения. Для Midi ввода нет команды прерывания, так как пользователь может просто игнорировать сообщения в буфере и закрыть устройство ввода в любое время.

close()

закрывает midi-поток, очищая все ожидающие буферы.

close() -> None

PortMidi пытается закрыть открытые потоки при выходе приложения.

Примечание

Это особенно сложно в Windows.

note_off()

выключает midi-ноту (нота должна быть включена)

note_off(note, velocity=None, channel=0) -> None

Отключает ноту в потоке вывода. Нота должна быть включена, чтобы это работало правильно.

note_on()

включает midi-ноту (нота должна быть выключена)

note_on(note, velocity=None, channel=0) -> None

Включает ноту в потоке вывода. Нота должна быть выключена, чтобы это работало правильно.

set_instrument()

выбирает инструмент со значением от 0 до 127

set_instrument(instrument_id, channel=0) -> None

Выбирает инструмент.

pitch_bend()

изменяет высоту канала.

set_instrument(value=0, channel=0) -> None

Настройка высоты канала. Значение — целое число со знаком от -8192 до +8191. Например, 0 означает «без изменений», +4096 — обычно на полутон выше, а -8192 — на целую октаву ниже (хотя музыкальный диапазон, соответствующий диапазону изменения высоты тона, также может быть изменён в некоторых синтезаторах).

Если значение не указано, изменение высоты тона возвращается к «без изменений».

Добавлен в pygame 1.9.4.

write()

записывает список midi-данных в Output

write(data) -> None

Запись серии MIDI-информации в виде списка.

Параметры

data (список) — данные для записи, ожидаемый формат [[[status, data1=0, data2=0, ...], timestamp], ...], где поля data# являются необязательными

Исключения

IndexError — если в списке данных более 1024 элементов

Пример:

# Program change at time 20000 and 500ms later send note 65 with
# velocity 100.
write([[[0xc0, 0, 0], 20000], [[0x90, 60, 100], 20500]])

Примечание

• Отметки времени будут проигнорированы, если latency = 0

• Чтобы нота игралась немедленно, отправляйте MIDI-информацию с отметкой времени, взятой из функции Time

• Необязательные поля данных: write([[[0xc0, 0, 0], 20000]]) эквивалентно write([[[0xc0], 20000]])

write_short()

записывает до 3 байт midi-данных в Output

write_short(status) -> None

write_short(status, data1=0, data2=0) -> None

Вывод MIDI-информации объёмом 3 байта или меньше. Поля data необязательны и считаются равными 0, если опущены.

Примеры значений байта состояния:

0xc0  # program change
0x90  # note on
# etc.

Пример:

# note 65 on with velocity 100
write_short(0x90, 65, 100)

write_sys_ex()

записывает системное исключительное midi-сообщение с отметкой времени.

write_sys_ex(when, msg) -> None

Записывает системное исключительное midi-сообщение с отметкой времени.

Параметры

• msg (список[int] или str) — midi-сообщение

• when — отметка времени в миллисекундах

Пример:

midi_output.write_sys_ex(0, '\xF0\x7D\x10\x11\x12\x13\xF7')

# is equivalent to

midi_output.write_sys_ex(pygame.midi.time(),
                         [0xF0, 0x7D, 0x10, 0x11, 0x12, 0x13, 0xF7])

pygame.midi.get_count()

возвращает количество устройств.

get_count() -> num_devices

Идентификаторы устройств изменяются от 0 до get_count() - 1

pygame.midi.get_default_input_id()

возвращает номер устройства стандартного ввода

get_default_input_id() -> default_id

Ниже описаны подробности использования этой функции и функции get_default_output_id().

Возвращает идентификатор стандартного устройства или -1, если устройств нет. Результат можно передать в класс Input/Output.

В ОС пользователь может указать стандартное устройство, установив переменную среды. Например, для использования устройства №1:

set PM_RECOMMENDED_INPUT_DEVICE=1
or
set PM_RECOMMENDED_OUTPUT_DEVICE=1

Сначала пользователь должен определить доступные идентификаторы устройств, используя приложение «testin» или «testout».

В целом, реестр — более подходящее место для такой информации. В случае USB-устройств, которые могут появляться и исчезать, использование целых чисел не очень надёжно для идентификации устройств. В Windows, если PM_RECOMMENDED_INPUT_DEVICE (или PM_RECOMMENDED_OUTPUT_DEVICE) не найдено в среде, то стандартное устройство определяется по строке в реестре по адресу:

HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Input_Device
or
HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Output_Device

Возвращается номер первого устройства, содержащего строку, точно соответствующую заданной строке. Например, если строка в реестре — «USB», и устройство 1 называется «Вх USB MidiSport 1x1», то это будет стандартный ввод, потому что содержит строку «USB».

Помимо имени, get_device_info() возвращает «interf», что является именем интерфейса. «Интерфейс» — это базовая программная система или API, используемая PortMidi для доступа к устройствам. Поддерживаемые интерфейсы:

MMSystem   # the only Win32 interface currently supported
ALSA       # the only Linux interface currently supported
CoreMIDI   # the only Mac OS X interface currently supported
# DirectX - not implemented
# OSS     - not implemented

Чтобы указать и интерфейс, и имя устройства в реестре, разделите их запятой и пробелом. Строка перед запятой должна быть подстрокой строки «interf», а строка после пробела — подстрокой имени «name» для сопоставления устройства. Например:

MMSystem, In USB MidiSport 1x1

Примечание

В текущей версии стандартным устройством является просто первое устройство (устройство ввода или вывода с наименьшим PmDeviceID).

pygame.midi.get_default_output_id()

возвращает номер устройства стандартного вывода

get_default_output_id() -> default_id

См. get_default_input_id() для подробностей использования.

pygame.midi.get_device_info()

возвращает информацию об устройстве MIDI

get_device_info(an_id) -> (interf, name, input, output, opened)

get_device_info(an_id) -> None

Получает информацию об устройстве с заданным идентификатором.

Параметры

an_id (int) -- id MIDI-устройства, которое запрашивается

Возвращаемое значение

если идентификатор вне допустимого диапазона, возвращается None, в противном случае возвращается кортеж (interf, name, input, output, opened).

• interf: строка, описывающая интерфейс устройства (например, 'ALSA')

• name: строка, имя устройства (например, 'Midi Through Port-0')

• input: 1, если устройство является устройством ввода, иначе 0

• output: 1, если устройство является устройством вывода, иначе 0

• opened: 1, если устройство открыто, иначе 0

Тип возвращаемого значения

кортеж или None

pygame.midi.midis2events()

преобразует события MIDI в события pygame

midis2events(midi_events, device_id) -> [Event, ...]

Принимает последовательность событий MIDI и возвращает список событий pygame.

Ожидается, что данные midi_events будут последовательностью ((status, data1, data2, data3), timestamp) событий MIDI (все необходимые значения).

Возвращаемое значение

список событий pygame типа MIDIIN

Тип возвращаемого значения

список

pygame.midi.time()

возвращает текущее время в мс таймера PortMidi

time() -> time

Время сбрасывается до 0 при инициализации модуля pygame.midi.

pygame.midi.frequency_to_midi()

Преобразует частоту в MIDI-ноту. Округляет до ближайшей MIDI-ноты.

frequency_to_midi(midi_note) -> midi_note

пример:

frequency_to_midi(27.5) == 21

Новое в pygame 1.9.5.

pygame.midi.midi_to_frequency()

Преобразует MIDI-ноту в частоту.

midi_to_frequency(midi_note) -> frequency

пример:

midi_to_frequency(21) == 27.5

Новое в pygame 1.9.5.

pygame.midi.midi_to_ansi_note()

Возвращает имя Ansi Note для MIDI-номера.

midi_to_ansi_note(midi_note) -> ansi_note

пример:

midi_to_ansi_note(21) == 'A0'

Новое в pygame 1.9.5.

exception pygame.midi.MidiException

исключение, которое могут генерировать функции и классы pygame.midi

MidiException(errno) -> None