audioop.md
1> **Источник:** https://python-all.ru/3.1/library/audioop.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 21.1. `audioop` – Обработка сырых аудиоданных89Модуль `audioop` содержит несколько полезных операций для работы со звуковыми фрагментами. Он работает со звуковыми фрагментами, состоящими из знаковых целочисленных отсчётов с разрядностью 8, 16 или 32 бита, хранящихся в строках Python. Все скалярные значения являются целыми числами, если не указано иное.1011Этот модуль предоставляет поддержку кодировок a-LAW, u-LAW и Intel/DVI ADPCM.1213Некоторые более сложные операции работают только с 16-битными отсчётами, в остальных случаях размер отсчёта (в байтах) всегда является параметром операции.1415Модуль определяет следующие переменные и функции:1617#### `exception audioop.error`1819Это исключение возникает при любых ошибках, например при неизвестном числе байт на отсчёт и т.п.2021#### `audioop.add(fragment1, fragment2, width)`2223Возвращает фрагмент, представляющий собой сумму двух сэмплов, переданных в качестве параметров.2425*width*2627– это ширина сэмпла в байтах:2829`1`3031,3233`2`3435или3637`4`3839. Оба фрагмента должны быть одинаковой длины.4041#### `audioop.adpcm2lin(adpcmfragment, width, state)`4243Декодирует фрагмент, закодированный в формате Intel/DVI ADPCM, в линейный фрагмент. Описание кодирования ADPCM см. в4445[`lin2adpcm()`](https://python-all.ru/3.1/library/audioop.html#audioop.lin2adpcm)4647. Возвращает кортеж4849`(sample, newstate)`5051, где sample имеет ширину, указанную в5253*width*5455.5657#### `audioop.alaw2lin(fragment, width)`5859Convert sound fragments in a-LAW encoding to linearly encoded sound fragments. a-LAW encoding always uses 8 bits samples, so6061*width*6263refers only to the sample width of the output fragment here.6465#### `audioop.avg(fragment, width)`6667Возвращает среднее арифметическое всех отсчётов во фрагменте.6869#### `audioop.avgpp(fragment, width)`7071Возвращает среднее размаха (пик-пик) по всем отсчётам во фрагменте. Фильтрация не производится, поэтому полезность этой функции сомнительна.7273#### `audioop.bias(fragment, width, bias)`7475Возвращает фрагмент, полученный из исходного фрагмента путём добавления смещения (bias) к каждому сэмплу.7677#### `audioop.cross(fragment, width)`7879Возвращает количество пересечений нуля во фрагменте, переданном в качестве аргумента.8081#### `audioop.findfactor(fragment, reference)`8283Возвращает коэффициент *F*, при котором `rms(add(fragment, mul(reference, -F)))` минимально, т.е. возвращает коэффициент, на который следует умножить *reference*, чтобы он как можно точнее соответствовал *fragment*. Оба фрагмента должны содержать 2-байтовые отсчёты.8485Время выполнения этой процедуры пропорционально `len(fragment)`.8687#### `audioop.findfit(fragment, reference)`8889Пытается подобрать9091*reference*9293как можно точнее к части9495*fragment*9697(которая должна быть более длинным фрагментом). Концептуально это делается путём извлечения срезов из9899*fragment*100101, используя102103[`findfactor()`](https://python-all.ru/3.1/library/audioop.html#audioop.findfactor)104105для вычисления наилучшего соответствия и минимизации результата. Оба фрагмента должны содержать 2-байтовые отсчёты. Возвращает кортеж106107`(offset, factor)`108109, где110111*offset*112113– это (целочисленное) смещение в114115*fragment*116117, с которого началось оптимальное совпадение, а118119*factor*120121– это (вещественный) коэффициент, как в122123[`findfactor()`](https://python-all.ru/3.1/library/audioop.html#audioop.findfactor)124125.126127#### `audioop.findmax(fragment, length)`128129Ищет в *fragment* срез длиной *length* отсчётов (не байтов!) с максимальной энергией, т.е. возвращает *i*, для которого `rms(fragment[i*2:(i+length)*2])` максимально. Оба фрагмента должны содержать 2-байтовые отсчёты.130131Время выполнения процедуры пропорционально `len(fragment)`.132133#### `audioop.getsample(fragment, width, index)`134135Возвращает значение сэмпла136137*index*138139из фрагмента.140141#### `audioop.lin2adpcm(fragment, width, state)`142143Преобразует сэмплы в 4-битное кодирование Intel/DVI ADPCM. Кодирование ADPCM – это адаптивная схема кодирования, в которой каждое 4-битное число представляет собой разность между одним сэмплом и следующим, делённую на (изменяемый) шаг. Алгоритм Intel/DVI ADPCM был выбран для использования IMA, так что он вполне может стать стандартом.144145*state* – это кортеж, содержащий состояние кодера. Кодер возвращает кортеж `(adpcmfrag, newstate)`, и *newstate* следует передавать в следующий вызов [`lin2adpcm()`](https://python-all.ru/3.1/library/audioop.html#audioop.lin2adpcm). В начальном вызове в качестве состояния можно передать `None`. *adpcmfrag* – это ADPCM-кодированный фрагмент, упакованный по 2 4-битных значения на байт.146147#### `audioop.lin2alaw(fragment, width)`148149Преобразует сэмплы звукового фрагмента в кодировку a-LAW и возвращает результат в виде строки Python. a-LAW – это формат аудиокодирования, при котором можно получить динамический диапазон около 13 бит, используя только 8-битные сэмплы. Он применяется, в частности, в звуковом оборудовании Sun.150151#### `audioop.lin2lin(fragment, width, newwidth)`152153Преобразует сэмплы между одно-, двух- и четырёхбайтовыми форматами.154155> **Примечание**156>157> В некоторых аудиоформатах, таких как .WAV, 16- и 32-битные сэмплы являются знаковыми, а 8-битные – беззнаковыми. Поэтому при преобразовании в 8-битные сэмплы для этих форматов к результату необходимо также прибавить 128:158>159> ```python160> new_frames = audioop.lin2lin(frames, old_width, 1)161> new_frames = audioop.bias(new_frames, 1, 128)162> ```163>164> То же самое в обратном порядке следует применять при преобразовании из 8-битных сэмплов в 16- или 32-битные.165166#### `audioop.lin2ulaw(fragment, width)`167168Преобразует сэмплы звукового фрагмента в кодировку u-LAW и возвращает результат в виде строки Python. u-LAW – это формат аудиокодирования, при котором можно получить динамический диапазон около 14 бит, используя только 8-битные сэмплы. Он применяется, в частности, в звуковом оборудовании Sun.169170#### `audioop.minmax(fragment, width)`171172Возвращает кортеж, состоящий из минимального и максимального значений всех сэмплов в звуковом фрагменте.173174#### `audioop.max(fragment, width)`175176Возвращает максимум177178*абсолютных значений*179180всех сэмплов во фрагменте.181182#### `audioop.maxpp(fragment, width)`183184Возвращает максимальное пик-пик значение в звуковом фрагменте.185186#### `audioop.mul(fragment, width, factor)`187188Возвращает фрагмент, в котором все сэмплы исходного фрагмента умножаются на значение с плавающей точкой189190*factor*191192. Переполнение молча игнорируется.193194#### `audioop.ratecv(fragment, width, nchannels, inrate, outrate, state[, weightA[, weightB]])`195196Преобразует частоту кадров входного фрагмента.197198*state* – кортеж, содержащий состояние преобразователя. Преобразователь возвращает кортеж `(newfragment, newstate)`, и *newstate* должен передаваться при следующем вызове [`ratecv()`](https://python-all.ru/3.1/library/audioop.html#audioop.ratecv). Первый вызов должен передавать `None` в качестве состояния.199200Аргументы *weightA* и *weightB* – это параметры простого цифрового фильтра; по умолчанию они равны `1` и `0` соответственно.201202#### `audioop.reverse(fragment, width)`203204Разворачивает сэмплы во фрагменте и возвращает изменённый фрагмент.205206#### `audioop.rms(fragment, width)`207208Возвращает среднеквадратичное значение фрагмента, т.е. `sqrt(sum(S_i^2)/n)`.209210Это мера мощности аудиосигнала.211212#### `audioop.tomono(fragment, width, lfactor, rfactor)`213214Преобразует стереофрагмент в монофрагмент. Левый канал умножается на215216*lfactor*217218, а правый – на219220*rfactor*221222, после чего два канала складываются для получения моносигнала.223224#### `audioop.tostereo(fragment, width, lfactor, rfactor)`225226Создаёт стереофрагмент из монофрагмента. Каждая пара сэмплов в стереофрагменте вычисляется из моно-сэмпла, при этом сэмплы левого канала умножаются на227228*lfactor*229230, а правого – на231232*rfactor*233234.235236#### `audioop.ulaw2lin(fragment, width)`237238Преобразует звуковые фрагменты в кодировке u-LAW во фрагменты с линейным кодированием. Кодировка u-LAW всегда использует 8-битные сэмплы, поэтому239240*width*241242здесь относится только к ширине сэмпла выходного фрагмента.243244Обратите внимание, что такие операции, как [`mul()`](https://python-all.ru/3.1/library/audioop.html#audioop.mul) или [`max()`](https://python-all.ru/3.1/library/audioop.html#audioop.max), не различают моно- и стереофрагменты, то есть все семплы обрабатываются одинаково. Если это проблема, стереофрагмент следует сначала разделить на два монофрагмента, а затем объединить обратно. Вот пример того, как это сделать:245246```python247def mul_stereo(sample, width, lfactor, rfactor):248 lsample = audioop.tomono(sample, width, 1, 0)249 rsample = audioop.tomono(sample, width, 0, 1)250 lsample = audioop.mul(lsample, width, lfactor)251 rsample = audioop.mul(rsample, width, rfactor)252 lsample = audioop.tostereo(lsample, width, 1, 0)253 rsample = audioop.tostereo(rsample, width, 0, 1)254 return audioop.add(lsample, rsample, width)255```256257Если вы используете кодер ADPCM для сборки сетевых пакетов и хотите, чтобы протокол был без состояния (т.е. допускал потерю пакетов), вам нужно не только передавать данные, но и состояние. Обратите внимание, что декодеру следует передавать *начальное* состояние (то, которое было передано в [`lin2adpcm()`](https://python-all.ru/3.1/library/audioop.html#audioop.lin2adpcm)) декодеру, а не конечное (возвращаемое кодером). Если вы хотите использовать `struct.struct()` для двоичного хранения состояния, первый элемент (предсказанное значение) можно кодировать 16 битами, а второй (индекс дельты) – 8.258259ADPCM-кодеры никогда не тестировались с другими ADPCM-кодерами, только друг с другом. Вполне возможно, что я неправильно интерпретировал стандарты, и в этом случае они не будут совместимы с соответствующими стандартами.260261Функции `find*()` могут показаться на первый взгляд немного странными. В первую очередь они предназначены для подавления эха. Достаточно быстрый способ сделать это – выбрать наиболее энергичный участок выходного семпла, найти его во входном семпле и вычесть весь выходной семпл из входного:262263```python264def echocancel(outputdata, inputdata):265 pos = audioop.findmax(outputdata, 800) # одна десятая секунды266 out_test = outputdata[pos*2:]267 in_test = inputdata[pos*2:]268 ipos, factor = audioop.findfit(in_test, out_test)269 # Необязательно (для лучшего подавления):270 # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],271 # out_test)272 prefill = '\0'*(pos+ipos)*2273 postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))274 outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill275 return audioop.add(inputdata, outputdata, 2)276```277