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)

Преобразует образцы в кодировку Intel/DVI ADPCM с 4 битами. Кодирование 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)

Возвращает среднеквадратичное отклонение фрагмента, т.е. 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)