Музыка воспроизводится на указанном звуковом канале.
Громкость каждого канала можно регулировать отдельно, но также можно изменять и микшеры (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 строчку, и при этом можно было бы быть уверенным, что всё продолжит работать, как и раньше.

Простой пример создания словаря:

    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.
Да и запутывать то, что и так не является слишком понятным, явно не стоит.

<- Назад