Звук (Audio)
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, и не зацикливаются по умолчанию.
Источник[править | править код]
- Статья "Audio" на английском языке.
- Помощь при переводе статьи "Audio" на русский язык: "Launchpad: audio"
На главную страницу | Официальная документация движка | Вернуться к началу статьи |