Аудио

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

  • Opus

  • Ogg Vorbis

  • MP3

  • MP2

  • FLAC

  • WAV (только несжатый 16-битный PCM со знаком)

В веб-браузере Ren'Py проверяет список аудиоформатов и включает режим, который работает быстрее и менее подвержен пропускам, если браузер поддерживает все режимы из списка. Если ваша игра использует только mp3 и пропускает звук в Safari, рассмотрите возможность изменения config.webaudio_required_types.

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

  • music — канал для воспроизведения музыки.

  • sound — канал для звуковых эффектов.

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

Настройки Music Volume (Громкость музыки), Sound Volume (Громкость звуков) и Voice Volume (Громкость голоса) в меню настроек игры используются для установки индивидуальной громкости для этих каналов. Для получения дополнительной информации см. Громкость.

В дополнение к обычным каналам есть два специальных:

  • audio — Аудиоканал поддерживает одновременное воспроизведение нескольких аудиофайлов, но не поддерживает постановку звука в очередь или остановку воспроизведения.

  • voice — Канал voice используется голосовой системой Ren'Py. Ren'Py будет автоматически воспроизводить и останавливать голосовые файлы, когда персонажи говорят, и может регулировать громкость этого канала.

Звуки также можно настроить на воспроизведение, когда кнопки, пункты меню или карты изображений (imagemaps) переходят в состояние наведения (hovered) или активации (activated). См. Свойства стиля кнопок. Две переменные конфигурации, config.main_menu_music и config.game_menu_music позволяют воспроизводить указанные музыкальные файлы в качестве музыки главного и игрового меню соответственно.

Внутри игры обычным способом воспроизведения музыки и звука в Ren'Py является использование трёх инструкций для музыки/звука. Аудиофайлы могут быть предоставлены непосредственно в виде строк или как определённые имена в пространстве имён аудио.

Директория и пространство имён аудио

Когда Ren'Py ищет аудиофайл, используемый инструкциями или функциями для аудио, поиск начинается в директории game. Если указанный файл там не найден, поиск также будет произведён в директории game/audio. Например:

play music "opening.ogg"

сначала будет искать game/opening.ogg. Если файл не найден, Ren'Py будет искать game/audio/opening.ogg. Это также справедливо для аудиофайлов в дальнейших поддиректориях. Следующая инструкция:

play music "my_music/opening.ogg"

сначала будет искать game/my_music/opening.ogg, а если не найдёт, то game/audio/my_music/opening.ogg.

Файлы, найденные в директории game/audio, а также в её поддиректориях, которые заканчиваются поддерживаемым расширением (в настоящее время .wav, .mp2, .mp3, .ogg и .opus), также автоматически помещаются Ren'Py в пространство имён аудио. Это означает, что game/audio/Town_theme.ogg можно воспроизвести с помощью:

play music town_theme

Используемое имя определяется путём удаления расширения и приведения оставшейся части имени файла к нижнему регистру. Это работает только для аудиофайлов с именами, которые могут быть выражены как переменные Python, например, my song.mp3, 8track.opus или this-is-a-song.ogg не будут работать. Кроме того, если два или более файла в итоге будут определены под одним и тем же именем, будет определён только первый файл (определяемый по алфавиту по его пути и имени файла, включая расширение).

Когда файл не помещается автоматически в пространство имён аудио из-за несовместимого имени или нахождения в другой директории, его всё равно можно поместить туда вручную с помощью инструкции define.

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

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

а затем использовать:

play music sunflower

Инструкции play и queue всегда оценивают свои аргументы в пространстве имён аудио. Функции этого не делают, что означает, что они не будут работать с sunflower, но будут работать с audio.sunflower.

Инструкция Play

Инструкция play — это самый распространённый способ воспроизведения звука и музыки. Если на обычном канале в данный момент воспроизводится файл, он прерывается и заменяется новым файлом.

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

Параметры fadein и fadeout не обязательны. Fadeout задаёт время затухания для текущей музыки в секундах, а fadein — время нарастания громкости для новой музыки. Если fadeout не указан, используется config.fadeout_audio.

Параметры 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

Если указан параметр if_changed, и если данный трек в данный момент воспроизводится на канале, инструкция play не прерывает его.

label market_side:
    play music market
    "Мы входим на рынок."
    jump market_main

label market_main:
    play music market if_changed
    "Может быть, мы только что вошли на рынок, а может, уже были там."
    "Если мы уже были там, музыка не остановилась и не началась заново, а просто продолжилась."
    jump market_main

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

play sound "woof.mp3" volume 0.5

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

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

Здесь вместо строки можно использовать переменную. Если переменная существует в пространстве имён аудио, она используется с предпочтением перед пространством имён по умолчанию:

play music illurock

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

Ren'Py поддерживает функцию, которая может гарантировать одновременное начало воспроизведения аудиофайлов. Эта функция включена по умолчанию на зацикленных аудиоканалах (таких как music), но также может быть включена с помощью опции synchro_start для renpy.music.register_channel() или renpy.music.play().

Когда synchro start включен и несколько инструкций play выполняются одновременно, аудио в каждом канале начнётся синхронно. В частности, аудио начнётся:

  • Когда аудиофайлы на каждом канале загружены и доступны аудиосэмплы.

  • Когда все каналы завершили затухание (fade out).

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

Инструкция Stop

Инструкция stop начинается с ключевого слова stop, за которым следует имя канала, на котором нужно остановить звук. Она может опционально иметь параметр fadeout. Если параметр fadeout не указан, используется config.fadeout_audio.

stop sound
stop music fadeout 1.0

Инструкция Queue

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

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

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

Queue также принимает параметр volume.

play sound "woof.mp3" volume 0.25
queue sound "woof.mp3" volume 0.5
queue sound "woof.mp3" volume 0.75
queue sound "woof.mp3" volume 1.0

Когда даётся несколько инструкций queue без взаимодействия между ними, все звуковые файлы добавляются в очередь. После того как произошло взаимодействие, первая инструкция queue очищает очередь, если она ещё не была очищена инструкцией play или stop.

Здесь вместо строки можно использовать переменную. Если переменная существует в пространстве имён аудио, она используется с предпочтением перед пространством имён по умолчанию:

define audio.woof = "woof.mp3"

# ...

play sound woof

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

Частичное воспроизведение

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 секунды перед повторным воспроизведением до конца.

Синхронизация начальной позиции

Позиция в файле, с которой начинается воспроизведение клипа, также может быть синхронизирована с другим каналом с текущим треком, используя имя файла вида "<sync channelname>track.opus", где channelname — это имя канала, которое может быть "music", "sound" или любым другим зарегистрированным каналом.

Это можно использовать для синхронизации многослойных зацикленных треков. Например:

play music_2 [ "<sync music_1>layer_2.opus", "layer_2.opus" ]

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

Громкость

Громкость, с которой будет воспроизводиться данный трек, зависит от ряда переменных:

  • громкость "главного" микшера

  • громкость микшера, с которым связан канал

  • громкость канала

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

  • относительная амплитуда, связанная с именем файла

Все эти громкости — это значения от 0 до 1, и их произведение даёт итоговую громкость, с которой будет воспроизводиться трек.

Например, если общая громкость 80% (0.8), громкость микшера 100%, громкость канала 50% (0.5), относительная громкость трека 25% (0.25), а относительная громкость, связанная с именем файла, 50% (0.5), итоговая громкость будет 0.8 * 1.0 * 0.5 * 0.25 * 0.5 = 0.05, то есть 5%.

Обратите внимание, что хотя все эти громкости являются амплитудами, в меню настроек микшеры представлены в децибелах.

Громкость микшеров можно установить с помощью preferences.set_mixer(), используя действие SetMixer() или действие Preference() с ключом "mixer <mixer> volume". Каналы "audio" и "sound" относятся к микшеру "sfx", канал "music" — к микшеру "music", а канал "voice" — к микшеру "voice". Кроме того, каждый канал связан с микшером "main", как показано выше.

Громкость канала можно установить с помощью renpy.music.set_volume(). Это полезно только тогда, когда несколько каналов используют один и тот же микшер. Параметр mixer функции renpy.music.register_channel() устанавливает, к какому микшеру относится зарегистрированный канал, создавая его при необходимости, если он ещё не существует.

Относительная громкость трека устанавливается с помощью параметра volume инструкции play.

Относительная громкость файла устанавливается с помощью параметра volume в угловых скобках, например, "<volume 0.5>track.opus".

В дополнение к этим значениям громкости существует флаг mute (без звука) микшера, к которому относится канал. Если он включен, громкость воспроизведения будет снижена до 0. Их можно установить с помощью действий SetMute() или ToggleMute(), или с помощью действия Preference() с ключом "mixer <mixer> mute", или с помощью функции preferences.set_mute().

Воспроизведение тишины

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

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

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

Действия

См. Аудио-действия.

Функции

class AudioData(data, filename)

Этот класс оборачивает байтовый объект, содержащий аудио- или видеоданные, чтобы его можно было передать в систему воспроизведения аудио/видео. Аудио- или видеоданные должны быть в формате, поддерживаемом Ren'Py (например, с заголовками формата RIFF WAV, а не чистые семплы).

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

data

Байтовый объект, содержащий данные аудиофайла.

filename

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

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

После создания его можно использовать везде, где допускается имя аудиофайла. Например:

define audio.easteregg = AudioData(b'...', 'sample.wav')
play sound easteregg
renpy.mark_audio_seen(filename)

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

renpy.mark_audio_unseen(filename)

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

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

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

renpy.seen_audio(filename)

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

renpy.music.channel_defined(channel)

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

renpy.music.get_all_mixers()

Получает все используемые микшеры.

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

Возвращает длительность аудио- или видеофайла на channel. Возвращает 0.0, если на channel не воспроизводится файл, или если длительность неизвестна. Некоторые форматы — в частности, MP3 — не содержат информацию о длительности в формате, доступном для Ren'Py.

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

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

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

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

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

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

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

Возвращает текущую позицию аудио- или видеофайла на channel в секундах. Возвращает None, если на channel не воспроизводится аудио.

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

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

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

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

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

filenames

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

channel

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

loop

Если True, треки будут зацикливаться, пока они являются последними в очереди.

fadeout

Если не None, это время в секундах для затухания. В противном случае время затухания берется из config.fadeout_audio. Этот параметр игнорируется, если канал был на паузе во время воспроизведения музыки.

synchro_start

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

Если None, значение берется из настроек канала.

fadein

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

tight

Если True, затухания будут переходить на следующий звук в очереди. Если None, это значение равно true, когда loop равно True, и false в противном случае.

if_changed

Если True, и музыкальный файл в данный момент воспроизводится, он не будет остановлен/затушен и снова включен с нарастанием, а продолжит играть. (Это всегда добавит в очередь дополнительный цикл воспроизведения музыки.)

relative_volume

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

Это сбрасывает флаг паузы для channel.

renpy.music.pump()

Эта функция 'прокачивает' аудиосистему. Обычно эффекты от инструкций play, queue и stop и их функциональных эквивалентов вступают в силу в начале следующего взаимодействия. В некоторых случаях эффекты нескольких инструкций могут отменять друг друга — например, a play, за которым следует stop, приводит к тому, что трек никогда не воспроизводится.

Если эта функция вызвана между play и stop, трек начнет воспроизводиться до того, как эта функция вернет управление, что затем позволяет плавно заглушить трек.

play music "mytrack.opus"
$ renpy.music.pump()
stop music fadeout 4
renpy.music.queue(filenames, channel='music', loop=None, clear_queue=True, fadein=0, tight=None, relative_volume=1.0)

Ставит указанные имена файлов в очередь на указанном канале.

filenames

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

channel

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

loop

Если True, треки будут зацикливаться, пока они являются последними в очереди.

clear_queue

Если True, очередь очищается, и эти файлы будут воспроизводиться после окончания текущего файла. Если False, эти файлы помещаются в конец очереди. В любом случае, если музыка не воспроизводится, эти файлы начнут играть немедленно.

fadein

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

tight

Если True, затухания будут переходить на следующий звук в очереди. Если None, это значение равно true, когда loop равно True, и false в противном случае.

relative_volume

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

Это сбрасывает флаг паузы для channel.

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

Регистрирует новый аудиоканал с именем name. Затем на этом канале можно воспроизводить аудио, передавая имя канала в инструкции play или queue.

name

Имя канала. Оно не должно содержать пробелов, так как это зарезервировано для внутреннего использования Ren'Py, и должно быть допустимым идентификатором чтобы синтаксис Инструкция Play был применим.

mixer

Имя микшера, который использует канал. По умолчанию, Ren'Py знает о микшерах "music", "sfx" и "voice". Возможно использование других имен, что создаст микшер, если он еще не существует, но чтобы сделать новые микшеры доступными для игрока, потребуется изменить экраны настроек.

loop

Если True или None, звуки на этом канале по умолчанию зацикливаются. Если False, звуки на этом канале по умолчанию не зацикливаются.

stop_on_mute

Если true, музыка на канале останавливается, когда канал заглушен.

tight

Если true, звуки будут зацикливаться даже во время затухания. Это значение следует установить в True для канала звуковых эффектов или бесшовной музыки, и в False , если музыка затухает сама по себе.

file_prefix

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

file_suffix

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

buffer_queue

Следует ли буферизовать первую секунду или около того файла в очереди? Это должно быть True для аудио и False для воспроизведения видео.

movie

Если true, этот канал будет настроен для воспроизведения видео.

framedrop

Управляет поведением видео при запаздывании. Если true, кадры будут пропускаться, чтобы соответствовать реальному времени и звуковой дорожке. Если false, Ren'Py будет отображать кадры с задержкой, а не пропускать их.

synchro_start

Участвует ли этот канал в synchro start? Synchro start определяет, начнет ли канал воспроизведение одновременно с другими каналами. Если None, по умолчанию используется loop, если movie равно False, и False в противном случае.

renpy.music.set_audio_filter(channel, audio_filter, replace=False, duration=0.016)

Устанавливает аудиофильтр для звуков, которые будут поставлены в очередь, на audio_filter.

audio_filter

Должен быть аудиофильтром или списком аудиофильтров, или None для удаления аудиофильтра.

replace

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

duration

Длительность перехода от текущего к новому фильтру в секундах. Это предотвращает щелчки при смене фильтров.

renpy.music.set_mixer(channel, mixer, default=False)

Устанавливает имя микшера, связанного с данным каналом. По умолчанию существует два микшера: 'sfx' и 'music'. 'sfx' находится на каналах с 0 по 3, а 'music' с 3 по 7. Модуль voice вызывает эту функцию для установки канала 2 в voice. Вы можете создать свой собственный микшер, но вам потребуется добавить опцию в настройках, если вы хотите позволить пользователю его настраивать.

Эту функцию следует вызывать только в блоке init.

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

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

pan

Число от -1 до 1, которое управляет расположением аудио. Если оно равно -1, все аудио направляется в левый канал. Если 0, оба канала сбалансированы. Если 1, все аудио направляется в правое ухо.

delay

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

channel

Канал, на котором происходит панорамирование, по умолчанию — музыкальный.

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

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

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

Устанавливает callback-функцию, которая вызывается, когда очередь пуста. Эта функция вызывается, когда очередь впервые становится пустой, и по крайней мере один раз за каждое взаимодействие, пока очередь пуста.

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

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

Устанавливает громкость этого канала как долю от громкости микшера, управляющего каналом.

volume

Это число от 0.0 до 1.0, которое интерпретируется как доля громкости микшера для данного канала.

delay

Требуется delay секунд, чтобы изменить/плавно перейти от старого значения громкости к новому. Это значение сохраняется и участвует в откате (rollback).

channel

Канал для установки

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

Останавливает воспроизводимую музыку и удаляет всю музыку из очереди. Если fadeout равен None, музыка затухает за время, указанное в config.fadeout_audio, в противном случае она затухает в течение fadeout секунд.

Это устанавливает последний поставленный в очередь файл в None.

channel

Канал, на котором нужно остановить звук.

fadeout

Если не None, это время затухания в секундах. В противном случае время затухания берется из config.fadeout_audio. Этот параметр игнорируется, если канал на паузе.

Функции звука

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