audioop — Работа с сырыми аудиоданными

Модуль audioop содержит полезные операции с фрагментами звука. Он работает с фрагментами звука, состоящими из образцов со знаком, целых чисел 8, 16 или 32 бит, хранящихся в строках Python. Это тот же формат, что и в модулях al и sunaudiodev. Все скалярные элементы являются целыми числами, если не указано иное.

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

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

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

exception audioop.error

Это исключение генерируется при всех ошибках, таких как неизвестное количество байтов на образец и т.д.

audioop.add(fragment1, fragment2, width)

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

audioop.adpcm2lin(adpcmfragment, width, state)

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

audioop.alaw2lin(fragment, width)

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

Добавлена в версии 2.5.

audioop.avg(fragment, width)

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

audioop.avgpp(fragment, width)

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

audioop.bias(fragment, width, bias)

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

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 и возвращает его как строку Python. a-LAW — это формат аудиокодирования, в котором вы получаете динамический диапазон около 13 бит, используя только 8-битные образцы. Он используется, в том числе, аудиооборудованием Sun.

Добавлена в версии 2.5.

audioop.lin2lin(fragment, width, newwidth)

Преобразует образцы между форматами 1-, 2- и 4-байтовых.

Примечание

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

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

Аналогично, при преобразовании из 8 в 16 или 32-битный размер образцов, необходимо применить обратную операцию.

audioop.lin2ulaw(fragment, width)

Преобразует образцы в фрагменте аудио в кодировку u-LAW и возвращает его как строку Python. 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)