audioop — Обработка необработанных аудиоданных

Модуль audioop содержит полезные операции над фрагментами звука. Он работает с фрагментами звука, состоящими из сэмплов со знаком целого типа 8, 16, 24 или 32 бита, хранящихся в байт-подобных объектах. Все скалярные элементы — целые числа, если не указано иначе.

Этот модуль предоставляет поддержку кодировок a-LAW, u-LAW и Intel/DVI ADPCM.

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

Модуль определяет следующие переменные и функции:

exception audioop.error

Эта исключение возникает при всех ошибках, таких как неизвестное количество байтов на сэмпл и т.д.

audioop.add(fragment1, fragment2, width)

Возвращает фрагмент, являющийся суммой двух сэмплов, переданных в качестве параметров. width — ширина сэмпла в байтах, либо 1, 2, 3 или 4. Оба фрагмента должны иметь одинаковую длину. Сэмплы усекаются в случае переполнения.

audioop.adpcm2lin(adpcmfragment, width, state)

Декодирует фрагмент, закодированный в формате Intel/DVI ADPCM, в линейный фрагмент. Смотрите описание lin2adpcm() для получения подробностей о кодировании ADPCM. Возвращает кортеж (sample, newstate), где сэмпл имеет ширину, указанную в width.

audioop.alaw2lin(fragment, width)

Преобразует фрагменты звука в кодировке a-LAW в линейные фрагменты звука. Кодирование a-LAW всегда использует сэмплы 8 бит, поэтому width здесь относится только к ширине сэмпла выходного фрагмента.

audioop.avg(fragment, width)

Возвращает среднее значение по всем сэмплам во фрагменте.

audioop.avgpp(fragment, width)

Возвращает среднее значение пик-пик по всем сэмплам во фрагменте. Фильтрация не выполняется, поэтому полезность этой функции сомнительна.

audioop.bias(fragment, width, bias)

Возвращает фрагмент, который является исходным фрагментом с добавленным смещением к каждому сэмплу. Сэмплы переполняются в случае переполнения.

audioop.byteswap(fragment, width)

«Переставляет байты» всех сэмплов во фрагменте и возвращает изменённый фрагмент. Преобразует сэмплы большого порядка в сэмплы малого порядка и наоборот.

Новая в версии 3.4.

audioop.cross(fragment, width)

Возвращает количество нулевых переходов во фрагменте, переданном в качестве аргумента.

audioop.findfactor(fragment, reference)

Возвращает множитель F такой, что rms(add(fragment, mul(reference, -F))) минимально, то есть возвращает множитель, с помощью которого вы должны умножить reference, чтобы максимально приблизить его к fragment. Оба фрагмента должны содержать 2-байтовые сэмплы.

Время выполнения этой функции пропорционально len(fragment).

audioop.findfit(fragment, reference)

Попытается максимально приблизить reference к части fragment (который должен быть более длинным фрагментом). Это (понятийно) делается путем взятия срезов из fragment, используя findfactor() для вычисления наилучшего соответствия и минимизации результата. Оба фрагмента должны содержать 2-байтовые сэмплы. Возвращает кортеж (offset, factor), где offset — (целое) смещение в fragment, где началось оптимальное соответствие, а factor — (вещественный) множитель, как в findfactor().

audioop.findmax(fragment, length)

Ищет в fragment срез длиной length сэмплов (а не байтов!) с максимальной энергией, т.е. возвращает i, для которого rms(fragment[i*2:(i+length)*2]) максимальна. Оба фрагмента должны содержать 2-байтовые сэмплы.

Функция занимает время, пропорциональное len(fragment).

audioop.getsample(fragment, width, index)

Возвращает значение сэмпла index из фрагмента.

audioop.lin2adpcm(fragment, width, state)

Преобразует сэмплы в 4-битное кодирование Intel/DVI ADPCM. Кодирование ADPCM — адаптивная схема кодирования, в которой каждое 4-битное число является разностью между одним сэмплом и следующим, деленной на (переменную) ступень. Алгоритм Intel/DVI ADPCM выбран IMA, поэтому он может стать стандартом.

state — кортеж, содержащий состояние кодера. Кодер возвращает кортеж (adpcmfrag, newstate), а newstate должен быть передан следующему вызову lin2adpcm(). При начальном вызове None может быть передан в качестве состояния. adpcmfrag — фрагмент, закодированный в формате ADPCM, упакованный по 2 значениям по 4 бита на байт.

audioop.lin2alaw(fragment, width)

Преобразует сэмплы в фрагменте аудио в кодировку a-LAW и возвращает это как байтовый объект. a-LAW — формат кодирования аудио, в котором вы получаете динамический диапазон около 13 бит, используя только 8-битные сэмплы. Он используется, в частности, звуковой аппаратной частью Sun.

audioop.lin2lin(fragment, width, newwidth)

Преобразует сэмплы между форматами 1, 2, 3 и 4 байта.

Примечание

В некоторых аудиоформатах, таких как файлы .WAV, 16-, 24- и 32-битные сэмплы со знаком, но 8-битные сэмплы без знака. Поэтому при преобразовании в 8-битные сэмплы для этих форматов вам необходимо также добавить 128 к результату:

new_frames = audioop.lin2lin(frames, old_width, 1)
new_frames = audioop.bias(new_frames, 1, 128)

То же самое, наоборот, необходимо применить при преобразовании из 8 в 16, 24 или 32-битные сэмплы.

audioop.lin2ulaw(fragment, width)

Преобразует сэмплы во фрагменте аудио в кодировку u-LAW и возвращает это как байтовый объект. u-LAW — формат кодирования аудио, в котором вы получаете динамический диапазон около 14 бит, используя только 8-битные сэмплы. Он используется, в частности, звуковой аппаратной частью Sun.

audioop.max(fragment, width)

Возвращает максимальное значение из абсолютного значения всех сэмплов во фрагменте.

audioop.maxpp(fragment, width)

Возвращает максимальное значение пик-пик во фрагменте звука.

audioop.minmax(fragment, width)

Возвращает кортеж, состоящий из минимального и максимального значений всех сэмплов во фрагменте звука.

audioop.mul(fragment, width, factor)

Возвращает фрагмент, в котором все сэмплы в исходном фрагменте умножаются на вещественное значение factor. Сэмплы усекаются в случае переполнения.

audioop.ratecv(fragment, width, nchannels, inrate, outrate, state[, weightA[, weightB]])

Преобразует частоту кадров входного фрагмента.

state — кортеж, содержащий состояние преобразователя. Преобразователь возвращает кортеж (newfragment, newstate), а newstate должен быть передан следующему вызову ratecv(). При первоначальном вызове должен быть передан None в качестве состояния.

Аргументы weightA и weightB являются параметрами простого цифрового фильтра и по умолчанию равны 1 и 0 соответственно.

audioop.reverse(fragment, width)

Обращает порядок сэмплов во фрагменте и возвращает изменённый фрагмент.

audioop.rms(fragment, width)

Возвращает среднеквадратичное отклонение (RMS) фрагмента, т.е. sqrt(sum(S_i^2)/n).

Это мера мощности в аудиосигнале.

audioop.tomono(fragment, width, lfactor, rfactor)

Преобразует стерео фрагмент в моно фрагмент. Левый канал умножается на lfactor, а правый канал на rfactor перед добавлением двух каналов для получения моносигнала.

audioop.tostereo(fragment, width, lfactor, rfactor)

Генерирует стерео фрагмент из моно фрагмента. Каждая пара сэмплов в стерео фрагменте вычисляется из моно сэмпла, где сэмплы левого канала умножаются на lfactor, а сэмплы правого канала — на rfactor.

audioop.ulaw2lin(fragment, width)

Преобразует фрагменты звука в кодировке u-LAW в линейные фрагменты звука. Кодирование u-LAW всегда использует сэмплы 8 бит, поэтому width здесь относится только к ширине сэмпла выходного фрагмента.

Обратите внимание, что такие операции, как mul() или max(), не различают моно- и стерео-фрагменты, т.е. все сэмплы обрабатываются одинаково. Если это проблема, стерео фрагмент следует сначала разделить на два моно фрагмента, а затем объединить их. Вот пример того, как это сделать:

def mul_stereo(sample, width, lfactor, rfactor):
    lsample = audioop.tomono(sample, width, 1, 0)
    rsample = audioop.tomono(sample, width, 0, 1)
    lsample = audioop.mul(lsample, width, lfactor)
    rsample = audioop.mul(rsample, width, rfactor)
    lsample = audioop.tostereo(lsample, width, 1, 0)
    rsample = audioop.tostereo(rsample, width, 0, 1)
    return audioop.add(lsample, rsample, width)

Если вы используете кодер ADPCM для построения сетевых пакетов и хотите, чтобы ваш протокол был бессостоятельным (т.е. мог выдержать потерю пакетов), вы должны не только передавать данные, но и состояние. Обратите внимание, что вы должны отправлять начальное состояние (то, которое вы передали в lin2adpcm()) вместе с декодером, а не конечное состояние (возвращенное кодером). Если вы хотите использовать struct.Struct для хранения состояния в двоичном виде, вы можете закодировать первый элемент (предсказанное значение) в 16 бит, а второй (индекс разницы) — в 8.

Кодеры ADPCM никогда не тестировались против других кодеров ADPCM, только против самих себя. Вполне возможно, что я неправильно интерпретировал стандарты, в таком случае они не будут совместимы с соответствующими стандартами.

Процедуры find*() на первый взгляд могут показаться немного странными. Они в первую очередь предназначены для отмены эха. Достаточно быстрый способ сделать это — выбрать наиболее энергичный фрагмент выходного образца, найти его в входном образце и вычесть весь выходной образец из входного образца:

def echocancel(outputdata, inputdata):
    pos = audioop.findmax(outputdata, 800)    # one tenth second
    out_test = outputdata[pos*2:]
    in_test = inputdata[pos*2:]
    ipos, factor = audioop.findfit(in_test, out_test)
    # Optional (for better cancellation):
    # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
    #              out_test)
    prefill = '\0'*(pos+ipos)*2
    postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
    outputdata = prefill + audioop.mul(outputdata, 2, -factor) + postfill
    return audioop.add(inputdata, outputdata, 2)