Звук (Audio)

Материал из Ren'Py Wiki
Перейти к навигации Перейти к поиску

Ren'Py поддерживает воспроизведение музыки и звуковых эффектов в фоновом режиме, используя следующие форматы аудиофайлов:

  • OPUS
  • OGG Vorbis
  • MP3
  • WAV (только несжатый PCM)


Ren'Py поддерживает произвольное количество звуковых каналов. По умолчанию определены три стандартных канала:

  • music – канал для воспроизведения музыки.
  • sound – канал для звуковых эффектов.
  • voice – канал для голосовой озвучки.

Стандартные каналы поддерживают воспроизведение и формирование очереди воспроизведения аудио, но одновременно воспроизводят только один аудиофайл. Новые стандартные каналы можно зарегистрировать с помощью renpy.music.register_channel().

Параметры меню внутриигровых настроек «Громкость музыки», «Громкость звука» и «Громкость голоса» используются для настройки отдельных уровней громкости для этих каналов.


Помимо стандартного канала, есть один специальный канал – audio. Канал audio поддерживает одновременное воспроизведение нескольких аудиофайлов, но не поддерживает формирование очереди воспроизведения звука или остановку воспроизведения.


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


Две переменные конфигурации, config.main_menu_music и config.game_menu_music, позволяют воспроизводить указанные музыкальные файлы, как в главном, так и игровом меню.


В играх, созданных с помощью Ren'Py, принято воспроизводить музыку или звук, используя три оператора music/sound, приведенных ниже.

Оператор play (Play Statement)[править | править код]

Оператор play используется для воспроизведения звука и музыки. Если в данный момент файл воспроизводится на стандартном канале, он прерывается и заменяется новым файлом.

Предполагается, что после ключевого слова play следует название канала, как правило, это либо "sound", "music", "voice" или "audio". Затем следует следует аудиофайл(ы), где аудиофайлом(и) может быть один файл или список файлов. Когда список задан, элементы в нём воспроизводятся по порядку.


Параметры fadein и fadeout необязательны. Fadeout дает время на затухание проигрываемой музыки (в секундах), тогда как fadein предоставляет время, требуемое на постепенное увеличение громкости звука нового аудиофайла. Если fadeout не указан, используется config.fade_music.

Параметры loop и noloop также являются необязательными. Loop приводит к зацикливанию музыки, тогда как noloop приводит к проигрыванию музыки всего один раз. Если ни один из параметров не указан, используется канал по умолчанию.

play music "mozart.ogg"
play sound "woof.mp3"
play myChannel "punch.wav" # 'myChannel' необходимо определить с помощью renpy.music.register_channel().

"Мы также можем воспроизвести список звуков или музыки."
play music [ "a.ogg", "b.ogg" ] fadeout 1.0 fadein 1.0


На канале audio несколько операторов play воспроизводят сразу несколько звуков одновременно:

play audio "sfx1.opus"
play audio "sfx2.opus"

Оператор stop (Stop Statement)[править | править код]

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

stop sound
stop music fadeout 1.0

Оператор queue (Queue Statement)[править | править код]

Оператор queue используется для постановки аудиофайлов в очередь. Они будут воспроизведены, когда канал завершит воспроизведение текущего проигрываемого файла.

Оператор queue начинается с ключевого слова queue, за которым следует название канала для воспроизведения звука на нём. Оператор queue может дополнительно использовать параметры loop и noloop.

queue sound "woof.ogg"
queue music [ "a.ogg", "b.ogg" ]

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


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

Частичное воспроизведение (Partial Playback)[править | править код]

Ren'Py поддерживает частичное воспроизведение аудиофайлов. Это достигается путём размещения спецификации воспроизведения, заключенной в угловые скобки, в начале файла. Спецификация частичного воспроизведения должна состоять из чередующихся пар "имя свойства" и "значения", разделенных пробелами. Значения всегда интерпретируются, как количество секунд от начала файла.


Ниже представлено три свойства:

from
Определяет позицию в файле, с которой начинается воспроизведение (по умолчанию 0.0 секунд).
to
Определяет позицию в файле, в которой файл заканчивает воспроизведение (по умолчанию вся продолжительность файла).
loop
Указывает позицию в файле, с которой начинается воспроизведение второго и последующих прогонов (по умолчанию это время начала, заданное from, если свойство указано, или начало файла).


Например этот код:

play music "<from 5 to 15.5>waves.opus"

Будет воспроизводить 10.5 секунд waves.opus, начиная с 5-ти секундной отметки.


Следующий код:

play music "<loop 6.333>song.opus"

Будет воспроизводить song.opus один раз от начала до конца, затем вернётся к отметке 6.333, прежде чем снова воспроизвести файл до конца.

Воспроизведение временного молчания (Playing Silence)[править | править код]

Установленный интервал времени паузы можно воспроизвести, используя имя файла, например "<silence 3.0>", где 3.0 – требуемое количество секунд тишины. Это можно использовать, чтобы отсрочить начало воспроизведения звукового файла. Например:

play audio [ "<silence .5>", "boom.opus" ]

Код будет полсекунды воспроизводить тишину, а затем воспроизведёт звук взрыва.

Пространство имён audio (Audio Namespace)[править | править код]

Операторы play и queue вычисляют свои аргументы в пространстве имён audio. Это означает, что можно использовать оператор define для создания псевдонима для аудиофайла.

Например, можно прописать псевдоним в коде:

define audio.sunflower = "music/sun-flower-slow-jam.ogg"

и потом использовать его в дальнейшем, как например:

play music sunflower

Функции (Functions)[править | править код]

AudioData(data, filename)
Этот класс упаковывает байтовый объект, содержащий аудиоданные, чтобы он мог быть передан в систему воспроизведения звука. Аудиоданные должны содержаться в формате, поддерживаемом Ren'Py. Например, заголовки формата RIFF WAV, а не сэмплы без каких-либо добавлений.
data
Байтовый объект, содержащий данные аудиофайла.
filename
Синтетическое имя файла, связанное с этими данными. Может быть использовано, чтобы предложить формат данных, и сообщается как часть сообщений об ошибках.
После создания можно использовать везде, где разрешено звуковое имя файла. Например:
define audio.easteregg = AudioData(b'...', 'sample.wav')
play sound easteregg


renpy.play(filename, channel=None, **kwargs)

Воспроизведение звукового эффекта. Если channel принимает значение None, то по умолчанию используется переменная конфигурации config.play_channel. Функция используется для воспроизведения звуков, определенных в стилях hover_sound и activate_sound.


renpy.seen_audio(filename)

Возвращает значение True, если заданный filename хотя бы один раз был воспроизведен в текущей системе пользователя.


renpy.music.get_duration(channel='music')

Вычисляет продолжительность аудио или видеофайла на channel. Возвращает нулевое значение (0.0), если на канале не воспроизводится файл.


renpy.music.get_pause(channel='music')

Возвращает флаг паузы для channel.


renpy.music.get_playing(channel='music')

Если заданный channel воспроизводится, то функция вычисляет имя проигрываемого файла. Иначе, возвращает значение None.


renpy.music.get_pos(channel='music')

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


renpy.music.is_playing(channel='music')

Возвращает значение True, если в данный момент канал воспроизводит звук. Возвращает значение False, если звук не воспроизводится или же акустическая система не работает.


renpy.music.play(filenames, channel='music', loop=None, fadeout=None, synchro_start=False, fadein=0, tight=None, if_changed=False)

Останавливает музыку, воспроизводимую в данный момент на пронумерованном канале, удаляет из очереди воспроизведения любую музыку, поставленную в очередь, и начинает воспроизведение указанного файла или файлов.
filenames
Это может быть один файл или список файлов для воспроизведения.
channel
Канал для воспроизведения звука на указанном channel.
loop
Если принимает значение True, треки будут зациклены, пока они являются последними в очереди воспроизведения.
fadeout
Если принимает значение не None, то это время в секундах на затухание проигрываемой музыки. Иначе это время берется из config.fade_music.
synchro_start
Ren'Py гарантирует, что все каналы с synchro_start со значением True начнут воспроизведение в одно и тоже время. Synchro_start должен иметь значение True при воспроизведении двух аудиофайлов, которые предназначены для синхронизации друг с другом.
fadein
Количество секунд на постепенное увеличение громкости звука проигрываемой музыки, только в первом цикле.
tight
Если принимает значение True, то затухание будет переходить в следующий звук в очереди. Если установлено значение None, параметр принимает значение True, когда loop=True, иначе значение False.
if_changed
Если принимает значение True и музыкальный файл воспроизводится в данный момент, то он не остановится/не затухнет и снова не исчезнет, а вместо этого продолжит проигрываться. Параметр всегда будет помещать в очередь дополнительный цикл музыки.
Функция очищает флаг паузы для channel.


renpy.music.queue(filenames, channel='music', loop=None, clear_queue=True, fadein=0, tight=None)

Помещает в очередь указанные имена файлов на указанном канале.
filenames
Это может быть один файл или список файлов для воспроизведения.
channel
Канал для воспроизведения звука на указанном channel.
loop
Если принимает значение True, треки будут зациклены, пока они являются последними в очереди воспроизведения.
clear_queue
Если принимает значение True, то очередь очищается, что делает указанные файлы файлами, которые воспроизводятся, когда заканчивается воспроизведение текущего файла. Если принимает значение False, то эти файлы помещаются в конец очереди. В любом случае, если музыка не воспроизводится, эти файлы начинают немедленно воспроизводиться.
fadein
Количество секунд на постепенное увеличение громкости звука проигрываемой музыки, только в первом цикле.
tight
Если принимает значение True, то затухание будет переходить в следующий звук в очереди. Если установлено значение None, параметр принимает значение True, когда loop=True, иначе значение False.
Функция очищает флаг паузы для channel.


renpy.music.register_channel(name, mixer=None, loop=None, stop_on_mute=True, tight=False, file_prefix=, file_suffix=, buffer_queue=True, movie=False, framedrop=True)

Регистрирует новый звуковой канал с именем name. После этого на созданном канале можно воспроизводить звук, указав название канала в операторах play или queue.
mixer
Название микшера, который использует канал. По умолчанию Ren'Py знает о "music", "sfx" и "voice" микшерах. Использование других названий возможно, но может потребоваться изменить экраны настроек игры.
loop
Если принимает значение True, звуки на этом канале зацикливаются по умолчанию.
stop_on_mute
Если принимает значение True, музыка на этом канале останавливается, когда канал отключён.
tight
Если принимает значение True, звуки будут зацикливаться, даже когда происходит их затухание. Значение True следует установить для звуковых эффектов или бесшовного канала music, а значение False, если музыка затухает сама по себе.
file_prefix
Префикс, который добавляется к началу имён звуковых файлов, воспроизводимых на этом канале.
file_suffix
Суффикс, который присоединяется после имён звуковых файлов, воспроизводимых на этом канале.
buffer_queue
Следует ли нам буферизовать первую или около того файла в очереди? Для воспроизведения звука параметру необходимо принять значение True, для воспроизведения видео - False.
movie
Если принимает значение True, этот канал будет настроен для воспроизведения видео.
framedrop
Управляет тем, что видео делает при задержке. Если принимает значение True, уменьшает частоту кадров, чтобы не отставать от реального времени и саундтрека. Если принимает значение False, Ren'Py будет отображать кадры с запозданием, а не уменьшать частоту кадров.


renpy.music.set_pan(pan, delay, channel='music')

Устанавливает панораму этого канала.
pan
Число между -1 и 1, которое управляет размещением звука в звуковом поле. Если число -1, то весь звук направляется в левый канал. Если 0, то оба канала одинаково сбалансированы. Если 1, то весь звук направляется в правый канал.
delay
Количество времени, необходимое для панорамирования.
channel
Канал, на котором происходит панорамирование. Это может быть канал sound или music. Чаще всего это канал 7, канал music по умолчанию.


renpy.music.set_pause(value, channel='music')

Устанавливает флаг паузы для channel с value. Если принимает значение True, воспроизведение на канале приостановится, иначе канал будет воспроизводиться как обычно.


renpy.music.set_queue_empty_callback(callback, channel='music')

Устанавливает функцию обратного вызова, которая вызывается, когда очередь воспроизведения пуста. Функция обратного вызова вызывается, когда очередь сначала становится пустой, и по крайней мере раз за взаимодействие с пользователем, пока очередь воспроизведения пуста.
Функция обратного вызова вызывается без параметров. Она может помещать в очередь звуки, вызывая renpy.music.queue с соответствующими аргументами. Обратите внимание, что обратный вызов может быть вызван во время воспроизведения звука, если слот очереди пуст.


renpy.music.set_volume(volume, delay=0, channel='music')

Устанавливает громкость этого канала, как долю громкости микшера, управляющего каналом.
volume
Это число от 0.0 до 1.0, которое интерпретируется как доля громкости микшера для канала.
delay
Для изменения/уменьшения громкости со старого значения на новое требуется несколько секунд. Это значение сохраняется в сохраненных играх и участвует в откате.
channel
Канал, который будет установлен.


renpy.music.stop(channel='music', fadeout=None)

Останавливает музыку, которая воспроизводится в данный момент, и удаляет всю музыку в очереди. Если fadeout принимает значение None, музыка затухает за время, указанное в config.fade_music, иначе она исчезнет в течение fadeout секунд.
Устанавливает значение None последнему файлу в очереди.
channel
Канал для остановки звука на указанном channel.
fadeout
Если принимает значение не None, то это время в секундах на затухание проигрываемой музыки. Иначе это время берется из config.fade_music.

Звуковые функции (Sound Functions)[править | править код]

Большинство renpy.music функций имеют альтернативные имена в renpy.sound. Эти функции сходны, за исключением того, что по умолчанию они используют канал sound, а не канал music, и не зацикливаются по умолчанию.

Источник[править | править код]

  1. Статья "Audio" на английском языке.
  2. Помощь при переводе статьи "Audio" на русский язык: "Launchpad: audio"

На главную страницу Официальная документация движка Вернуться к началу статьи