Музыка воспроизводится на указанном звуковом канале.  
Громкость каждого канала можно регулировать отдельно, но также можно изменять и микшеры (mixers).  
Микшеры - это, если упрощённо, группы звуковых каналов.

Они автоматически создаются при первом упоминании.
По умолчанию используются такие:
* `ambience` - окружение,
* `music` - музыка,
* `sfx` - звуки.

***

## Звуковые каналы

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

По умолчанию существуют такие:
* `music` - микшер `music`, повтор,
* `sound`, `sound2`, `sound3` - микшер `sfx`, без повтора,
* `ambience`, `sound_loop`, `sound_loop2`, `sound_loop3` - микшер `ambience`, повтор.

Они зарегистрированы в файле `Ren-Engine/rpy/sound_channels.rpy`.

***

## Регистрация звуковых каналов

`renpy.music.register_channel("name", "mixer", loop)`  
Где
* `name` - имя регистрируемого канала,
* `mixer` - используемый микшер,
* `loop` - `True` - зациклить, `False` - без повторов.

Например, канал `sound` зарегистрирован так:  
`renpy.music.register_channel("sound", "sfx", False)`

***

## Есть ли канал

Проверить, был ли зарегистрирован канал с именем `name`:  
`renpy.music.has_channel("name")`

***

## Проигрывание

В сценарии:  
`play channel file_name [fadein time = 0] [volume value = 1.0]`  
Где
* `channel` - звуковой канал,
* `file_name` - имя проигрываемого файла,
* `time` - время (в сек.) усиления звука от нуля до полной громкости (по умолчанию `0`),
* `value` - относительная громкость (от `0.0` до `1.0`) конкретно для этого проигрываемого файла,
без смены громкости у канала или микшера.

Примеры:  
`play sound sfx_intro_bus_stop_steps`  
`play music music_list["a_promise_from_distant_days_v2"] fadein 1.5`  
`play sound 'sound/music/file.ogg' volume 0.2`

В питоне:  
`renpy.play(file_name, channel, fadein = 0, relative_volume = 1.0)`  
или, что тоже самое  
`renpy.music.play(file_name, channel, fadein = 0, relative_volume = 1.0)`

Примеры:  
`renpy.play(sfx_intro_bus_stop_steps, 'sound')`  
`renpy.music.play(music_list["scarytale"], 'music', fadein = 1.5)`  
`renpy.music.play('sound/music/file.ogg', 'music', fadein = 1, relative_volume = 0.5)`  


Обычно рекомендуется не пользоваться прямым указанием пути.
Дело в том, что в процессе разработки, особенно ближе к её окончанию, файл может быть заменён или переименован.  
В этом случае вам понадобится изменить пути к файлу по всему сценарию, что долго и муторно (+можно что-то пропустить).  
Тогда как в случае использования словаря (или хотя бы простых переменных) вам нужно было бы изменить лишь 1 строчку,
и при этом можно было бы быть уверенным, что всё продолжит работать, как и раньше.

Простой пример создания словаря:
```renpy
init python:
	music_list = {
		'some_song': 'sound/music/some_song.mp3',
		'my_file': 'path/to/my_file.ogg',
	}

# использование:
label some:
	play music music_list['some_song']
	# или питоном:
	$ renpy.play(music_list['my_file'], 'music')
```

***

## Остановка воспроизведения

В сценарии:  
`stop channel [fadeout time = 0]`  
Где
* `channel` - звуковой канал.
* `time` - время (в сек.) убавления звука от полной громкости до нуля (по умолчанию `0`).

Примеры:  
`stop ambience`  
`stop music fadeout 1.5`

В питоне:  
`renpy.stop(channel, fadeout = 0)`  
или, что тоже самое  
`renpy.music.stop(channel, fadeout = 0)`

Примеры:  
`renpy.stop('ambience')`  
`renpy.music.stop('music', fadeout = 1.5)`

***

## Установка громкости

Для отдельного канала:  
`renpy.music.set_volume(vol, 'channel')`  
Где
* `vol` - громкость от `0` (0%) до `1.0` (100%),
* `channel` - звуковой канал.

Для управления громкостью всех каналов с определённым микшером есть свой набор функций:  
1. Установить: `renpy.music.set_mixer_volume(vol, 'mixer')`
2. Получить: `renpy.music.get_mixer_volume('mixer')`
3. Добавить (можно и отрицательное значение): `renpy.music.add_mixer_volume(d, 'mixer')`

***

## Пауза

Поставить канал `ambience` на паузу:  
`renpy.music.set_pause(True, 'ambience')`

Снять паузу на канале `ambience`:  
`renpy.music.set_pause(False, 'ambience')`

Функция ничего не делает, если на канале ничего не проигрывается.

Узнать, поставлен ли канал на паузу:  
`renpy.music.get_pause('ambience')`  
Вернёт `True` (на паузе), `False` (проигрывается) или `None` (на канале ничего не воспроизводится).

***

## Позиция

Перемотать проигрываемый на канале `sound` файл к позиции `10.5` (в секундах):  
`renpy.music.set_pos(10.5, 'sound')`  
Ничего не делает, если на канале ничего не воспроизводится.

Получить позицию на канале `sound`:  
`renpy.music.get_pos('sound')`  
Вернёт время (нецелое число, в секундах) либо `None` (если на канале ничего не воспроизводится).

***

## Длительность

Узнать длительность файла (в секундах, нецелое число):  
`renpy.music.get_audio_len('path/to/file.ogg')`

Функция поддерживает все форматы аудио-файлов, поддерживаемые движком Ren-Engine.

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

***

Наверно, будут вопросы, почему тут так часто встречается renpy?  
Для облегчения портирования с самого RenPy.  
Да и запутывать то, что и так не является слишком понятным, явно не стоит.

***

[<- Назад](./Изображения-(ВН-спрайты))
