Обработка звука
===============

В состав данной библиотеки входят 2 подмодуля:
 
  - эквалайзер;
  - набор функций для работы с разными единицами и шкалами для измерения громкости.
  
Оба подмодуля несут исключительно вспомогательную функцию, для работы самой библиотеки их использование не требуется. Также эти модули можно применять не только к самому плееру.
 
Web Audio API
-------------

Стоит сразу оговориться, что эквалайзер - это технология Web Audio API и нужно понимать то, как данная библиотека работает с этим самым API. Есть несколько особенностей, которые стоит учитывать проектируя собственные фильтры препроцессора (да и просто для использования эквалайзера не плохо знать это).

  1. При использовании YandexAudio API не требуется вручную создавать контекст AudioContext. Этот объект создается библиотекой YandexAudio автоматически, после ее загрузки на страницу (если есть поддержка технологии Web Audio API в браузере). Созданный аудио-контекст доступен через `ya.music.Audio.audioContext`.
  
  2. Web Audio API более требователен к контенту - в случае если аудио-данные берутся со стороннего домена, требуется чтобы был включен режим CORS и целевой домен проставлял корректные заголовки `Access-Control-Allow-Origin`. Для включения данного режима используется метод `YadexAudio#toggleCrossDomain(true)`. **Важно** - если сервер не отправляет необходимые заголовки включение данного режима не позволит загрузить трек даже если не используется Web Audio API, так что не стоит включать этот режим превентивно, если не планируется использование Web Audio API. 

  3. Web Audio API не умеет напрямую использовать элементы `audio` в графе. Для их использования требуется создать элемент `MediaElementAudioSourceNode`, указав `audio` элемент как источник звука (опять же, подробнее в статье [Web Audio API](web-audio-api.md) в разделе **Источники сигнала**). Далее, так как мы хотим работать с изначальным сигналом без всяких искажений (включая изменение громкости, которое очень критично для некоторых фильтров), нам потребуется создать элемент `GainNode`, который будет управлять итоговой громкостью, а самому элементу `audio` выставить максимальную громкость. Именно это проделывает вызов `YandexAudio#toggleWebAudioAPI(true)` - создает необходимое окружение для использования Web Audio API.
  <img src="http://trunk-d-ogorbacheva-d-api.doccenter-dev.yandex.ru/audio/freeze/Dz2Hrdk4onWg3Inqq3CUpeEmzQk.png" width="100%" />
  
  4. **Важно**. Однажды включенный режим Web Audio API отключить нельзя! Когда вызывается метод `YandexAudio#toggleWebAudioAPI(false)` граф просто максимально сокращается. Из него удаляется препроцессор, управление громкостью при этом по-прежнему ведется через `GainNode`, так как некоторые браузеры не возвращают корректно управление громкостью элементу `audio`.
  
Сам процесс подключения различных препроцессоров и фильтров предельно прост. Препроцессор описывается двумя нодами - входной и выходной (для простых фильтров это может быть одна и та же нода). Выход `MediaElementAudioSourceNode` подключается ко входу входной ноды, а выход выходной ноды препроцессора подключается к входу `GainNode`. Таким образом, если требуется подключить более одного фильтра, то достаточно соединить их в нужной последовательности и передать в качестве входной и выходной ноды соответствующие ноды этой конструкции.
       
```(javascript)
equalizer.output.connect(convolverNode);
convolverNode.connect(dynamicsCompressorNode);
dynamicsCompressorNode.connect(analyzerNode);

player.setAudioPreprocessor({
 input: equalizer.input,
 output: dynamicsCompressorNode // нам не нужен выход analyzerNode, и ее не обязательно подключать к какому-либо выходу
});
```

<img src="http://trunk-d-ogorbacheva-d-api.doccenter-dev.yandex.ru/audio/freeze/9JZDp-EpE-DqYY9i7ZzVuau-iN0.png" width="100%" />

 
Эквалайзер
----------

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

Стоит сразу упомянуть, что эквалайзер реализован только для html5-версии плеера, т.к. он использует технологию [Web Audio API](web-audio-api.md). Рассмотрим небольшой пример того, как подключить и использовать эквалайзер:
 
```(javascript)
// Сахар для удобства доступа
var YandexAudio = ya.music.Audio;
var Equalizer = YandexAudio.fx.Equalizer;

// При создании плеера непосредственно указываем html5, т.к. эквалайзер не будет работать с flash-плеером
var player = new YandexAudio("html5");
var equalizer = null;

// Дожидаемся завершения инициализации плеера
player.initPromise().then(function() {
    if (!player.toggleWebAudioAPI(true)) {
        // Если не удается включить Web Audio API, значит либо запустился flash-плеер, либо нет поддержки Web Audio API
        console.warn("Эквалайзер недоступен");
    } else {
        // Создаем эквалайзер со стандартным набором полос пропускания
        equalizer = new Equalizer(YandexAudio.audioContext, Equalizer.DEFAULT_BANDS);
        
        // Находим нужный пресет из списка стандартных
        for (var i = 0, l = Equalizer.DEFAULT_PRESETS.length; i < l; i++) {
            if (Equalizer.DEFAULT_PRESETS[i].id === "Full Bass & Treble") {
                var preset = Equalizer.DEFAULT_PRESETS[i];
                break;
            }
        }

        // Загружаем пресет в эквалайзер
        equalizer.loadPreset(preset);
        
        // Подключаем эквалайзер к плееру
        player.setAudioPreprocessor(equalizer);
    }
});
```

Тут стоит пояснить некоторые вещи. 

Полосой пропускания называется диапазон частот, к которому применяется некий фильтр. В нашем случае этот фильтр реализован с помощью `BiquadFilterNode`, для первой и последней полосы он имеет тип `lowshelf` и `highshelf` соответственно, а для всех остальных - `peaking`. Подробнее про это можно почитать в статье [Web Audio API](web-audio-api.md) в разделе **BiquadFilterNode**. Фильтры для каждой полосы соединены последовательно начиная с самой маленькой частоты и заканчивая самой высокой. В данном примере используется стандартный набор из 10 полос с частотами `[60, 170, 310, 600, 1000, 3000, 6000, 12000, 14000, 16000]` (значения указаны в герцах).

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



Громкость
---------

С данным подмодулем все намного проще - это всего лишь набор формул для перевода следующих величин: 

  - **dBFS** - полный динамический диапазон. Шкала в децибелах от минус бесконечности до нуля (подробнее в статье про [теорию звука](sound.md) в разделе **Уровень сигнала**),
  - экспоненциальная шкала - шкала относительной громкости (от 0 до 1) с экспоненциальным шагом. Позволяет более точно регулировать громкость вблизи нижней границы и делает более существенные изменения громкости вблизи верхней границы.

Оригинальная шкала громкости, является линейной шкалой относительной громкости (от 0 до 1). Все методы данного подмодуля переводят значения из этой шкалы или в эту шкалу.