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)

«Переставляет байты» всех образцов в фрагменте и возвращает измененный фрагмент. Преобразует образцы с big-endian в little-endian и наоборот.

Новое в версии 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)