Этот модуль содержит функции для генерации звуковых тонов, подключая пьезо зуммер или динамик к выходному GPIO. Модуль можно использовать двумя способами:

Прямая нотация, в которой тоны описываются в терминах их частоты и длительности.
Музыкальная нотация, в которой тоны описываются в терминах музыкальной ноты, длительности ноты, октавы, размера такта и т. д.
RTTTL, в которой вся мелодия, включая темп и длительности нот, задаётся одной строкой.

Генератор тонов

Тоны синтезируются модулем с использованием генератора тонов:

Генератор	Id	Описание
PWM	sound.PWM	Тон синтезируется аппаратным модулем PWM, который генерирует квадратную волну с коэффициентом заполнения 50%.
DAC	sound.DAC	Тон синтезируется аппаратным модулем I2S/DAC, который генерирует синусоидальную волну с частотой дискретизации 38 кГц.

Функции конфигурации

instance = sound.attach(tone_generator, pin)

Подключение генератора тонов к пьезо зуммеру или динамику.

Аргументы:

tone_generator: генератор тонов, используемый для синтеза тонов.
pin: GPIO, к которому подключен пьезо зуммер или динамик. Для sound.PWM это должен быть GPIO с поддержкой выхода; для sound.DAC допустимы только GPIO25 и GPIO26.

Возвращает: экземпляр звука или исключение. Этот экземпляр необходимо сохранить в переменной для дальнейших операций с ним.

DAC-генератор эксклюзивно устанавливает драйвер I2S0. Если I2S0 уже занят, sound.attach() возвращает исключение и не изменяет и не удаляет чужой драйвер. detach() освобождает I2S0 только после успешной установки данным экземпляром.

instance:detach()

Отсоединение генератора тонов и освобождение всех используемых ресурсов.

Аргументы: нет.

Возвращает: ничего или исключение.

Функции операций

instance:setvolume(volume)

Устанавливает громкость генератора.

volume: конечное число от 0 до 1; 0 включает беззвучный режим.

Для DAC значение изменяет амплитуду сигнала. PWM-генератор не поддерживает регулировку амплитуды, поэтому значение проверяется, но его коэффициент заполнения остаётся 50%.

Возвращает: ничего или исключение.

instance:playnote(note, octave)

Воспроизведение музыкальной ноты в желаемой октаве.

Аргументы:

note: отформатированная строка (name [accidental] duration), описывающая музыкальную ноту для воспроизведения и её длительность.
octave: октава, в которой должна воспроизводиться нота.

Возвращает: ничего или исключение.

instance:playrtttl(melody)

Воспроизведение мелодии, записанной одной строкой в формате RTTTL. Метод instance:play(melody) является его коротким псевдонимом.

Строка состоит из трёх частей, разделённых двоеточиями:

name:d=duration,o=octave,b=bpm:notes

name: непустое имя мелодии; на воспроизведение не влияет.
d: длительность ноты по умолчанию. Допустимые значения: 1, 2, 4, 8, 16, 32 и 64.
o: октава по умолчанию от 0 до 9.
b: темп от 1 до 900 ударов в минуту.
notes: список нот через запятую.

Параметры d, o и b можно не указывать. В этом случае используются значения d=4, o=6 и b=63.

Нота имеет формат [duration]note[#|b][octave][.], где:

duration: необязательная длительность конкретной ноты;
note: нота от a до g или p для паузы;
# и b: необязательные диез и бемоль;
octave: необязательная октава от 0 до 9;
. увеличивает длительность ноты в полтора раза.

Перед воспроизведением модуль проверяет всю строку. Если формат неверен, возвращается исключение invalid RTTTL melody, и воспроизведение не начинается.

local buzzer = sound.attach(sound.PWM, pio.GPIO21)

-- Длительность по умолчанию 1/8, пятая октава, 180 BPM
buzzer:playrtttl("ready:d=8,o=5,b=180:c,e,g,4c6")

-- play() принимает тот же формат; p обозначает паузу
buzzer:play("error:d=4,o=4,b=120:g,p,d2")

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

instance:timesignature(upper, lower, bpm)

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

Аргументы:

upper: верхнее значение размера такта, которое указывает, сколько ударов содержится в каждом такте.
lower: нижнее значение размера такта, которое указывает, какая длительность ноты эквивалентна 1 удару.
bpm: удары в минуту.
Темп bpm
Adagio 66–76
Adagietto 70–80
Andante 76–108
Andantino 80–108
Marcia moderato 83–85
Andante moderato 92–112
Moderato 108–120
Allegretto 112–120
Allegro moderato 116–120
Allegro 120–156
Некоторые основные обозначения темпа и их соответствие bpm.

Темп	bpm
Adagio	66–76
Adagietto	70–80
Andante	76–108
Andantino	80–108
Marcia moderato	83–85
Andante moderato	92–112
Moderato	108–120
Allegretto	112–120
Allegro moderato	116–120
Allegro	120–156

Возвращает: ничего или исключение.

Примеры:

Пример	Как кодировать
	instance:timesignature(3,4,120)
	instance:timesignature(4,4,120)
	instance:timesignature(4,4,120)

instance:playsilence(duration)

Воспроизвести тишину указанной длительности.

Аргументы:

duration: длительность тишины, относительно целой ноты продолжительностью в 1 временную единицу.
Длительность тишины может быть увеличена наполовину от длительности ноты, добавив точку (.).

instance:playtone(frequency, duration)

Воспроизвести тон указанной частоты и длительности.

Аргументы:

frequency: строго положительная частота тона в герцах.
duration: строго положительная длительность тона в миллисекундах.

Возвращает: ничего или исключение.

-- Воспроизвести звуковой тон на частоте 440 Гц в течение 1 секунды
buzzer = sound.attach(sound.DAC, pio.GPIO26)

buzzer:playtone(440, 1000)

Пример

В следующем примере показано, как перевести первые 8 тактов нотной записи из музыки Гарри Поттера.

buzzer = sound.attach(sound.DAC, pio.GPIO26)

buzzer:timesignature(3, 4, 240)

buzzer:playsilence("4")
buzzer:playsilence("4")
buzzer:playnote("B4",   4)
buzzer:playnote("E4.",  5)
buzzer:playnote("G8",   5)
buzzer:playnote("F#4",  5)
buzzer:playnote("E2",   5)
buzzer:playnote("B4",   5)
buzzer:playnote("A2.",  5)
buzzer:playnote("F#2.", 5)
buzzer:playnote("E4.",  5)
buzzer:playnote("G8",   5)
buzzer:playnote("F#4",  5)
buzzer:playnote("D2",   5)
buzzer:playnote("F4",   5)
buzzer:playnote("B2.",  4)