====== @amperka/ringtone ======

Модуль позволяет воспроизводить мелодии заданные в формате [[https://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language|RTTTL]] (Ring Tone Text Transfer Language). Формат был распространён на старых мобильных телефонах, когда они ещё не поддерживали проигрывание полноценных звуковых файлов.

Целевым устройством может быть [[amp>/product/troyka-buzzer|модуль-зуммер]], динамик или даже шаговый мотор, подключённый через [[amp>/product/troyka-stepper-motor-driver|драйвер]] с интерфейсом STEP/DIR.

<code javascript>
var player = require('@amperka/ringtone').create(P3);

var melody = 'Flinstones:d=4,o=5,b=40:32p,16f6,16a#,' +
  '16a#6,32g6,16f6,16a#.,16f6,32d#6,32d6,32d6,32d#6,' +
  '32f6,16a#,16c6,d6,16f6,16a#.,16a#6,32g6,16f6,16a#.,' + 
  '32f6,32f6,32d#6,32d6,32d6,32d#6,32f6,16a#,16c6,a#,' + 
  '16a6,16d.6,16a#6,32a6,32a6,32g6,32f#6,32a6,8g6,16g6,' + 
  '16c.6,32a6,32a6,32g6,32g6,32f6,32e6,32g6,8f6,16f6,' +
  '16a#.,16a#6,32g6,16f6,16a#.,16f6,32d#6,32d6,32d6,' +
  '32d#6,32f6,16a#,16c.6,32d6,32d#6,32f6,16a#,16c.6,' +
  '32d6,32d#6,32f6,16a#6,16c7,8a#.6';

player.play(melody).then(function() {
  print('Melody completed');
});

</code>

===== Примеры мелодий =====

  * Cantina:d=4,o=5,b=250:8a,8p,8d6,8p,8a,8p,8d6,8p,8a,8d6,8p,8a,8p,8g#,a,8a,8g#,8a,g,8f#,8g,8f#,f.,8d.,16p,p.,8a,8p,8d6,8p,8a,8p,8d6,8p,8a,8d6,8p,8a,8p,8g#,8a,8p,8g,8p,g.,8f#,8g,8p,8c6,a#,a,g
  * StWars:d=4,o=5,b=180:8f,8f,8f,2a#.,2f.6,8d#6,8d6,8c6,2a#.6,f.6,8d#6,8d6,8c6,2a#.6,f.6,8d#6,8d6,8d#6,2c6,p,8f,8f,8f,2a#.,2f.6,8d#6,8d6,8c6,2a#.6,f.6,8d#6,8d6,8c6,2a#.6,f.6,8d#6,8d6,8d#6,2c6
  * Popcorn:d=4,o=5,b=112:8c6,8a#,8c6,8g,8d#,8g,c,8c6,8a#,8c6,8g,8d#,8g,c,8c6,8d6,8d#6,16c6,8d#6,16c6,8d#6,8d6,16a#,8d6,16a#,8d6,8c6,8a#,8g,8a#,c6 
  * PinkPanther:d=4,o=5,b=160:8d#,8e,2p,8f#,8g,2p,8d#,8e,16p,8f#,8g,16p,8c6,8b,16p,8d#,8e,16p,8b,2a#,2p,16a,16g,16e,16d,2e
  * Macarena:d=4,o=5,b=180:f,8f,8f,f,8f,8f,8f,8f,8f,8f,8f,8a,8c,8c,f,8f,8f,f,8f,8f,8f,8f,8f,8f,8d,8c,p,f,8f,8f,f,8f,8f,8f,8f,8f,8f,8f,8a,p,2c.6,a,8c6,8a,8f,p,2p

Больше мелодий: http://syspace.ru/nokiatone/rtttf.htm

===== Функции модуля =====

func:: create(opts)

Создаёт новый объект-плеер. В качестве ''opts'' принимает пин для проигрывания или объект с полями:

  * ''pin'' — пин для проигрывания;
  * ''melody'' — RTTTL-мелодия по умолчанию.

Поля ''opts'' могут быть опущены.

class:: Player

Класс объектов-плееров. Используйте ''create'' для создания экземпляров.

meth:: Player.play([melody][, noteCallback])

Начинает проигрывать RTTTL-мелодию ''melody''. При переходе к очередной ноте вызывает ''noteCallback'' с параметрами частоты и длительности ноты. При переходе к паузе вызывает ''noteCallback'' с параметром частоты равным ''0''.

<code javascript>
var player = require('@amperka/ringtone').create();
player.play(':d=4,o=5,b=90:g,d,g,d,g,b,a#,a,g,d,g,d,g', function(freq, duration) {
  print('Tone at', freq, 'Herz for', duration, 'seconds');
});
</code>

Если при создании объекта был указан пин, воспроизводит необходимые частоты на этом пине с помощью ШИМ-сигнала.
Если параметр ''melody'' опущен, используется мелодия заданная при создании.

<code javascript>
var player = require('@amperka/ringtone').create({
  pin: P3,
  melody: ':d=4,o=5,b=90:g,d,g,d,g,b,a#,a,g,d,g,d,g'
});

player.play();
</code>

Функция возвращает объект-обещание, который можно использовать для вызова функции по завершению проигрывания:

<code javascript>
// ...
player.play(melody).then(function() {
  print('Melody completed');
});
</code>

meth:: Player.stop()

Прерывает воспроизведение мелодии. Приводит к моментальному переходу к ноте-паузе: пин проигрывания будет выключен, функция обратного вызова для ''play'' будет вызвана с нулевыми параметрами.