Этот модуль содержит классы для загрузки объектов Sound и управления воспроизведением. Модуль mixer является необязательным и зависит от SDL_mixer. Ваша программа должна проверить, что pygame.mixer доступен и инициализирован перед его использованием.

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

Все воспроизведение звука смешивается в фоновых потоках. Когда вы начинаете воспроизводить объект Sound, он вернётся немедленно, а звук продолжит воспроизведение. Один объект Sound также может быть активно воспроизведён несколько раз.

Mixer также имеет специальный канал потоковой передачи. Он предназначен для воспроизведения музыки и доступен через pygame.mixer.music модуль. Рассмотрите возможность использования этого модуля для воспроизведения длительной музыки. В отличие от модуля mixer, модуль music потоково передает музыку из файлов, не загружая всю музыку сразу в память.

Модуль mixer должен быть инициализирован, как и другие модули pygame, но у него есть дополнительные условия. Функция pygame.mixer.init() принимает несколько необязательных аргументов для управления скоростью воспроизведения и размером выборки. Pygame использует разумные значения по умолчанию, но pygame не может выполнять пересэмплирование звука, поэтому mixer должен быть инициализирован в соответствии со значениями ваших аудиоресурсов.

NOTE: для уменьшения задержки при воспроизведении звука используйте меньший размер буфера. По умолчанию он настроен для уменьшения вероятности появления хрипов звука на некоторых компьютерах. Вы можете изменить буфер по умолчанию, вызвав pygame.mixer.pre_init() перед pygame.mixer.init() или вызовом pygame.init(). Например: pygame.mixer.pre_init(44100,-16,2, 1024)

pygame.mixer.init()

инициализация модуля mixer

init(frequency=44100, size=-16, channels=2, buffer=512, devicename=None, allowedchanges=AUDIO_ALLOW_FREQUENCY_CHANGE | AUDIO_ALLOW_CHANNELS_CHANGE) -> None

Инициализирует модуль mixer для загрузки и воспроизведения звука. Значения аргументов по умолчанию могут быть изменены для предоставления конкретных параметров смешивания аудио. Принимаются аргументы по ключевому слову. Для обратной совместимости значения аргументов 0 заменяются значениями по умолчанию при запуске, за исключением allowedchanges, где используется -1. (Значения по умолчанию при запуске могут быть изменены вызовом pre_init()).

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

Аргумент channels используется для указания использования моно или стерео. 1 для моно и 2 для стерео.

Аргумент buffer управляет количеством внутренних сэмплов, используемых в миксере звука. Значение по умолчанию должно подойти для большинства случаев. Его можно уменьшить, чтобы уменьшить задержку, но может произойти пропуск звука. Его можно увеличить для обеспечения того, что воспроизведение никогда не пропускает звук, но это наложит задержку на воспроизведение звука. Размер буфера должен быть степенью двойки (если нет, он округляется до ближайшей большей степени двойки).

Некоторые платформы требуют, чтобы модуль pygame.mixer был инициализирован после инициализации модулей отображения. Основной pygame.init() автоматически позаботится об этом, но не сможет передавать любые аргументы в mixer init. Для решения этой проблемы, mixer имеет функцию pygame.mixer.pre_init() для установки надлежащих значений по умолчанию перед использованием верхнего уровня init.

При использовании allowedchanges=0 он будет преобразовывать сэмплы во время выполнения, чтобы соответствовать тому, что поддерживает оборудование. Например, звуковая карта может не поддерживать 16-битные звуковые сэмплы, поэтому вместо этого она будет использовать 8-битные сэмплы внутри. Если указано AUDIO_ALLOW_FORMAT_CHANGE, запрашиваемый формат будет изменён на ближайший поддерживаемый SDL2.

Помимо 0, allowedchanged принимает следующие константы, объединённые с помощью ORed:

• AUDIO_ALLOW_FREQUENCY_CHANGE

• AUDIO_ALLOW_FORMAT_CHANGE

• AUDIO_ALLOW_CHANNELS_CHANGE

• AUDIO_ALLOW_ANY_CHANGE

Безопасно вызывать это более одного раза, но после инициализации mixer вы не можете изменить аргументы воспроизведения, не вызвав сначала pygame.mixer.quit().

Изменено в pygame 1.8: Значение по умолчанию buffersize изменилось с 1024 на 3072.

Изменено в pygame 1.9.1: Значение по умолчанию buffersize изменилось с 3072 на 4096.

Изменено в pygame 2.0.0: Значение по умолчанию buffersize изменилось с 4096 на 512.

Изменено в pygame 2.0.0: Значение по умолчанию frequency изменилось с 22050 на 44100.

Изменено в pygame 2.0.0: size может быть 32 (32-битные числа с плавающей точкой).

Изменено в pygame 2.0.0: channels также может быть 4 или 6.

Добавлена в pygame 2.0.0: allowedchanges, devicename добавлены как аргументы

pygame.mixer.pre_init()

установка значений аргументов для mixer init

pre_init(frequency=44100, size=-16, channels=2, buffer=512, devicename=None, allowedchanges=AUDIO_ALLOW_FREQUENCY_CHANGE | AUDIO_ALLOW_CHANNELS_CHANGE) -> None

Вызов pre_init для изменения значений по умолчанию, используемых при вызове реального pygame.mixer.init(). Принимаются аргументы по ключевому слову. Лучший способ установить пользовательские значения воспроизведения mixer - вызвать pygame.mixer.pre_init() перед вызовом верхнего уровня pygame.init(). Для обратной совместимости значения аргументов 0 заменяются значениями по умолчанию при запуске, за исключением allowedchanges, где используется -1.

Изменено в pygame 1.8: Значение по умолчанию buffersize изменилось с 1024 на 3072.

Изменено в pygame 1.9.1: Значение по умолчанию buffersize изменилось с 3072 на 4096.

Изменено в pygame 2.0.0: Значение по умолчанию buffersize изменилось с 4096 на 512.

Изменено в pygame 2.0.0: Значение по умолчанию frequency изменилось с 22050 на 44100.

Добавлена в pygame 2.0.0: allowedchanges, devicename добавлены как аргументы

pygame.mixer.quit()

деинициализация mixer

quit() -> None

Это деинициализирует pygame.mixer. Все воспроизведение прекратится, и любые загруженные объекты Sound могут быть несовместимы с mixer, если он будет повторно инициализирован позднее.

pygame.mixer.get_init()

проверка, инициализирован ли mixer

get_init() -> (frequency, format, channels)

Если mixer инициализирован, возвращает используемые аргументы воспроизведения. Если mixer не был инициализирован, возвращает None.

pygame.mixer.stop()

остановка воспроизведения всех звуковых каналов

stop() -> None

Это остановит все воспроизведение всех активных каналов mixer.

pygame.mixer.pause()

временная остановка воспроизведения всех звуковых каналов

pause() -> None

Это временно остановит всё воспроизведение на активных каналах mixer. Воспроизведение может быть возобновлено позже с помощью pygame.mixer.unpause()

pygame.mixer.unpause()

возобновление приостановленного воспроизведения звуковых каналов

unpause() -> None

Это возобновит все активные звуковые каналы после их приостановки.

pygame.mixer.fadeout()

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

fadeout(time) -> None

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

pygame.mixer.set_num_channels()

установка общего числа каналов воспроизведения

set_num_channels(count) -> None

Устанавливает количество доступных каналов для mixer. Значение по умолчанию равно 8. Значение можно увеличить или уменьшить. Если значение уменьшается, воспроизведение на усечённых каналах останавливается.

pygame.mixer.get_num_channels()

получить общее количество каналов воспроизведения

get_num_channels() -> count

Возвращает количество активных каналов воспроизведения.

pygame.mixer.set_reserved()

зарезервировать каналы от автоматического использования

set_reserved(count) -> count

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

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

Возвращает фактическое количество зарезервированных каналов, это может быть меньше запрошенного в зависимости от количества ранее выделенных каналов.

pygame.mixer.find_channel()

найти свободный канал

find_channel(force=False) -> Channel

Это найдёт и вернёт объект неактивного канала. Если неактивных каналов нет, эта функция вернёт None. Если неактивных каналов нет и аргумент force равен True, это найдёт канал с самым долгим звуком и вернёт его.

pygame.mixer.get_busy()

проверить, смешивается ли какой-либо звук

get_busy() -> bool

Возвращает True если микшер занят смешиванием каналов. Если микшер простаивает, то возвращает False.

pygame.mixer.get_sdl_mixer_version()

получить версию SDL микшера

get_sdl_mixer_version() -> (major, minor, patch)

get_sdl_mixer_version(linked=True) -> (major, minor, patch)

Параметры

linked (bool) -- если True (по умолчанию) возвращается связанный номер версии, в противном случае возвращается собранный номер версии

Возвращает

номер версии библиотеки SDL микшера (связанный или собранный, в зависимости от linked параметра) в виде кортежа из 3 целых чисел (major, minor, patch)

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

кортеж

Примечание

Связанные и собранные номера версий должны быть одинаковыми.

Введено в pygame 2.0.0.

pygame.mixer.Sound

Создать новый объект Sound из файла или объекта буфера

Sound(filename) -> Sound

Sound(file=filename) -> Sound

Sound(file=pathlib_path) -> Sound

Sound(buffer) -> Sound

Sound(buffer=buffer) -> Sound

Sound(object) -> Sound

Sound(file=object) -> Sound

Sound(array=object) -> Sound

Загрузить новый буфер звука из имени файла, объекта файла Python или объекта буфера для чтения. Ограниченное пересэмплирование будет выполнено, чтобы помочь образцу соответствовать аргументам инициализации для микшера. Строка Unicode может быть только путем к файлу. Объект типа bytes может быть либо путем к файлу, либо объектом буфера. Используйте ключевые слова 'file' или 'buffer', чтобы избежать неоднозначности; в противном случае Sound может ошибиться. Если используется ключевое слово 'array', объект должен экспортировать новый интерфейс буфера (сначала проверяется наличие интерфейса буфера у объекта).

Объект Sound представляет фактические данные образца звука. Методы, которые изменяют состояние объекта Sound, будут влиять на все экземпляры воспроизведения звука. Объект Sound также экспортирует новый интерфейс буфера.

Звук может быть загружен из аудиофайла OGG или из несжатого WAV.

Примечание: буфер будет скопирован внутри, данные не будут совместно использоваться между ним и объектом Sound.

На данный момент поддержка буфера и массива согласуется с sndarray.make_sound для массивов Numeric, в том, что знак образца и порядок байтов игнорируются. Это изменится, либо путем правильной обработки знака и порядка байтов, либо путем вывода исключения при их различиях. Кроме того, исходные образцы усекаются, чтобы соответствовать размеру образца аудио.

Введено в pygame 1.8: pygame.mixer.Sound(buffer)

Введено в pygame 1.9.2: pygame.mixer.Sound ключевые аргументы и поддержка интерфейса массива

Введено в pygame 2.0.1: поддержка pathlib.Path на Python 3.

play()

начало воспроизведения звука

play(loops=0, maxtime=0, fade_ms=0) -> Channel

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

Аргумент loops управляет тем, сколько раз образец будет повторяться после первого воспроизведения. Значение 5 означает, что звук будет воспроизведён один раз, затем будет повторено пять раз, и в итоге воспроизведётся шесть раз. Значение по умолчанию (ноль) означает, что звук не повторяется, а воспроизводится только один раз. Если loops установлен на -1, звук будет воспроизводиться бесконечно (хотя вы по-прежнему можете вызвать stop() чтобы его остановить).

Аргумент maxtime можно использовать для остановки воспроизведения через заданное количество миллисекунд.

Аргумент fade_ms сделает так, чтобы звук начинался с 0 громкости и плавно нарастал до полной громкости за заданное время. Образец может закончиться до завершения плавного увеличения громкости.

Возвращает объект канала для выбранного канала.

stop()

остановить воспроизведение звука

stop() -> None

Это остановит воспроизведение этого звука на любых активных каналах.

fadeout()

остановить воспроизведение звука после плавного уменьшения громкости

fadeout(time) -> None

Это остановит воспроизведение звука после плавного уменьшения громкости за время, указанное в аргументе в миллисекундах. Звук будет уменьшаться и останавливаться на всех активно воспроизводящихся каналах.

set_volume()

установить громкость воспроизведения для этого звука

set_volume(value) -> None

Это установит громкость (громкость) для этого звука. Это немедленно повлияет на звук, если он воспроизводится. Это также повлияет на любое последующее воспроизведение этого звука.

Параметры

value (float) --

громкость в диапазоне от 0.0 до 1.0 (включительно)

Если value < 0.0, громкость не будет изменена

Если value > 1.0, громкость будет установлена в 1.0

get_volume()

получить громкость воспроизведения

get_volume() -> value

Возвращает значение от 0.0 до 1.0, представляющее громкость для этого звука.

get_num_channels()

подсчитать сколько раз этот звук воспроизводится

get_num_channels() -> count

Возвращает количество активных каналов, на которых воспроизводится этот звук.

get_length()

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

get_length() -> seconds

Возвращает длительность этого звука в секундах.

get_raw()

возвращает копию образцов звука в виде строкового объекта типа bytes.

get_raw() -> bytes

Возвращает копию буфера объекта Sound в виде объекта типа bytes.

Введено в pygame 1.9.2.

pygame.mixer.Channel

Создать объект Channel для управления воспроизведением

Channel(id) -> Channel

Возвращает объект Channel для одного из текущих каналов. ID должен быть значением от 0 до значения pygame.mixer.get_num_channels().

Объект Channel может использоваться для точного управления воспроизведением звуков. Канал может воспроизводить только один звук одновременно. Использование каналов полностью необязательно, так как pygame может управлять ими по умолчанию.

play()

Воспроизвести звук на конкретном канале

play(Sound, loops=0, maxtime=0, fade_ms=0) -> None

Начинает воспроизведение звука на конкретном канале. Если на канале уже воспроизводится другой звук, он будет остановлен.

Аргумент loops имеет такое же значение, как и в Sound.play(): это количество повторов звука после первого воспроизведения. Если он равен 3, звук будет воспроизведён 4 раза (в первый раз, а затем ещё три). Если loops равен -1, воспроизведение будет повторяться бесконечно.

Как и в Sound.play(), аргумент maxtime можно использовать для остановки воспроизведения звука после заданного количества миллисекунд.

Как и в Sound.play(), аргумент fade_ms можно использовать для плавного запуска звука.

stop()

Остановить воспроизведение на канале

stop() -> None

Останавливает воспроизведение звука на канале. После остановки воспроизведения канал становится доступным для воспроизведения новых звуков.

pause()

Временно остановить воспроизведение канала

pause() -> None

Временно останавливает воспроизведение звука на канале. Возобновить его можно позже с помощью Channel.unpause()

unpause()

Возобновить воспроизведение приостановленного канала

unpause() -> None

Возобновляет воспроизведение на приостановленном канале.

fadeout()

Остановить воспроизведение после плавного вывода канала

fadeout(time) -> None

Остановить воспроизведение канала после плавного вывода звука за указанное время в миллисекундах.

set_volume()

Установить громкость воспроизводимого канала

set_volume(value) -> None

set_volume(left, right) -> None

Установить громкость (громкость) воспроизводимого звука. При запуске канала его значение громкости сбрасывается. Это влияет только на текущий звук. Значение аргумента находится в диапазоне от 0,0 до 1,0.

Если передано одно значение, оно будет громкостью для обоих динамиков. Если передано два значения, и микшер в стерео режиме, первое значение будет громкостью левого динамика, а второе — правого. (Если второе значение None, первое значение будет громкостью обоих динамиков.)

Если на канале воспроизводится звук, для которого также был вызван set_volume(), оба вызова учитываются. Например:

sound = pygame.mixer.Sound("s.wav")
channel = s.play()      # Sound plays at full volume by default
sound.set_volume(0.9)   # Now plays at 90% of full volume.
sound.set_volume(0.6)   # Now plays at 60% (previous value replaced).
channel.set_volume(0.5) # Now plays at 30% (0.6 * 0.5).

get_volume()

Получить громкость воспроизводимого канала

get_volume() -> value

Возвращает громкость канала для текущего воспроизводимого звука. Это не учитывает стерео разделение, используемое функцией Channel.set_volume(). Объект Sound также имеет свою громкость, которая смешивается с каналом.

get_busy()

Проверить активность канала

get_busy() -> bool

Возвращает True, если канал активно обрабатывает звук. Если канал не активен, возвращает False.

get_sound()

Получить текущий воспроизводимый звук

get_sound() -> Sound

Возвращает фактический объект Sound, который в данный момент воспроизводится на этом канале. Если канал не активен, возвращается None.

queue()

Поместить объект Sound в очередь для последующего воспроизведения

queue(Sound) -> None

Когда объект Sound помещен в очередь на канале, он начнет воспроизводиться сразу после завершения текущего звука. Каждый канал может содержать только один звук в очереди. Воспроизводимый звук из очереди будет воспроизведён, только если текущее воспроизведение завершится автоматически. Он очищается при любом другом вызове Channel.stop() или Channel.play().

Если на канале нет активного звука, то звук из очереди начнёт воспроизводиться сразу.

get_queue()

Возвращает любой звук, находящийся в очереди

get_queue() -> Sound

Если на канале уже находится звук в очереди, он будет возвращён. После начала воспроизведения звука из очереди он больше не будет находиться в очереди.

set_endevent()

Сгенерировать событие при остановке воспроизведения на канале

set_endevent() -> None

set_endevent(type) -> None

Когда для канала задано событие завершения, оно будет отправлять событие в очередь pygame каждый раз, когда звук на этом канале заканчивает воспроизведение (не только в первый раз). Используйте pygame.event.get() для получения события завершения, после его отправки.

Обратите внимание, что если вы вызываете Sound.play(n) или Channel.play(sound,n), событие завершения отправляется только один раз: после того, как звук был воспроизведён «n+1» раз (см. документацию Sound.play).

Если Channel.stop() или Channel.play() вызваны, когда звук всё ещё воспроизводится, событие будет размещено немедленно.

Аргумент type будет идентификатором события, отправляемого в очередь. Это может быть любой допустимый тип события, но хорошим выбором будет значение в диапазоне от pygame.locals.USEREVENT до pygame.locals.NUMEVENTS. Если аргумент type не указан, то канал перестанет отправлять события завершения.

get_endevent()

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

get_endevent() -> type

Возвращает тип события, которое отправляется каждый раз, когда канал завершает воспроизведение звука. Если событие завершения отсутствует, функция возвращает pygame.NOEVENT.