Skip to content

πŸŽ› πŸ”Š A Python library for audio.

Add `num_threads` to `AudioFile::encode`. (#494)

Peter Sobotcb4516d17034
diff --git a/CMakeLists.txt b/CMakeLists.txt
index d9ae8b9..2241de1 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -169,6 +169,11 @@ elseif(WIN32)
# Windows specific flags
add_compile_definitions(WINDOWS=1 USE_BUILTIN_FFT NO_THREADING)
add_compile_definitions(JUCE_DLL_BUILD=1)
+
+ # python_bindings.cpp generates a very large number of COFF sections (from
+ # the pybind11 template instantiations); /bigobj raises the per-object
+ # section limit so MSVC doesn't fail with error C1128.
+ add_compile_options(/bigobj)
# Windows-specific libraries
list(APPEND PLATFORM_LIBRARIES
diff --git a/pedalboard/BufferUtils.h b/pedalboard/BufferUtils.h
index 13f7085..d504425 100644
--- a/pedalboard/BufferUtils.h
+++ b/pedalboard/BufferUtils.h
@@ -18,6 +18,8 @@
#pragma once
#include "JuceHeader.h"
+#include <cstdint>
+
#include <pybind11/numpy.h>
#include <pybind11/pybind11.h>
@@ -264,4 +266,91 @@ py::array_t<T> copyJuceBufferIntoPyArray(const juce::AudioBuffer<T> &juceBuffer,
return outputArray;
}
+
+/**
+ * Convert a NumPy array of a specific dtype into a deinterleaved
+ * juce::AudioBuffer<float> normalized to [-1, 1] by multiplying each sample by
+ * `scale`. Handles both interleaved and non-interleaved input layouts.
+ */
+template <typename T>
+juce::AudioBuffer<float>
+copyTypedPyArrayIntoFloatJuceBuffer(const py::array &samples,
+ int numChannelsHint, float scale) {
+ py::array_t<T, py::array::c_style> inputArray(samples);
+ py::buffer_info inputInfo = inputArray.request();
+ ChannelLayout inputChannelLayout =
+ detectChannelLayout(inputArray, {numChannelsHint});
+
+ int numChannels = 1;
+ int numSamples = 0;
+ bool interleaved = false;
+ if (inputInfo.ndim == 1) {
+ numChannels = 1;
+ numSamples = static_cast<int>(inputInfo.shape[0]);
+ } else if (inputInfo.ndim == 2) {
+ if (inputChannelLayout == ChannelLayout::Interleaved) {
+ numSamples = static_cast<int>(inputInfo.shape[0]);
+ numChannels = static_cast<int>(inputInfo.shape[1]);
+ interleaved = true;
+ } else {
+ numChannels = static_cast<int>(inputInfo.shape[0]);
+ numSamples = static_cast<int>(inputInfo.shape[1]);
+ }
+ } else {
+ throw std::runtime_error("Number of input dimensions must be 1 or 2 (got " +
+ std::to_string(inputInfo.ndim) + ").");
+ }
+
+ juce::AudioBuffer<float> ioBuffer(std::max(numChannels, 1),
+ std::max(numSamples, 0));
+ const T *inputPointer = static_cast<const T *>(inputInfo.ptr);
+ for (int c = 0; c < numChannels; c++) {
+ float *channelBuffer = ioBuffer.getWritePointer(c);
+ for (int i = 0; i < numSamples; i++) {
+ const T value = interleaved ? inputPointer[(i * numChannels) + c]
+ : inputPointer[(c * numSamples) + i];
+ channelBuffer[i] = static_cast<float>(value) * scale;
+ }
+ }
+ return ioBuffer;
+}
+
+/**
+ * Convert a NumPy array of any supported dtype (int8, int16, int32, float32, or
+ * float64) into a deinterleaved juce::AudioBuffer<float> normalized to [-1, 1].
+ *
+ * Unlike copyPyArrayIntoJuceBuffer, this always produces a float buffer (JUCE's
+ * AudioBuffer only supports floating-point sample types), which is useful when
+ * a plain C++ float buffer is needed regardless of the input dtype - for
+ * example, to feed encoder threads that must not touch Python.
+ */
+inline juce::AudioBuffer<float>
+copyPyArrayIntoFloatJuceBuffer(const py::array &samples, int numChannelsHint) {
+ switch (samples.dtype().char_()) {
+ case 'f':
+ return copyTypedPyArrayIntoFloatJuceBuffer<float>(samples, numChannelsHint,
+ 1.0f);
+ case 'd':
+ return copyTypedPyArrayIntoFloatJuceBuffer<double>(samples, numChannelsHint,
+ 1.0f);
+ case 'b':
+ return copyTypedPyArrayIntoFloatJuceBuffer<int8_t>(samples, numChannelsHint,
+ 1.0f / 128.0f);
+ case 'h':
+ return copyTypedPyArrayIntoFloatJuceBuffer<int16_t>(
+ samples, numChannelsHint, 1.0f / 32768.0f);
+ case 'i':
+#ifdef JUCE_WINDOWS
+ // On 64-bit Windows, int32 is a "long".
+ case 'l':
+#endif
+ return copyTypedPyArrayIntoFloatJuceBuffer<int32_t>(
+ samples, numChannelsHint, 1.0f / 2147483648.0f);
+ default:
+ throw py::type_error(
+ "Encoding audio requires an array with a datatype of int8, "
+ "int16, int32, float32, or float64. (Got: " +
+ py::str(samples.attr("dtype")).cast<std::string>() + ")");
+ }
+}
} // namespace Pedalboard
\ No newline at end of file
diff --git a/pedalboard/io/AudioFileInit.h b/pedalboard/io/AudioFileInit.h
index 1005388..1b8745d 100644
--- a/pedalboard/io/AudioFileInit.h
+++ b/pedalboard/io/AudioFileInit.h
@@ -17,14 +17,18 @@
#pragma once
+#include <algorithm>
+#include <cctype>
#include <mutex>
#include <optional>
#include <pybind11/numpy.h>
#include <pybind11/pybind11.h>
+#include "../BufferUtils.h"
#include "../JuceHeader.h"
#include "AudioFile.h"
+#include "ParallelMP3Encoder.h"
#include "WriteableAudioFileFlags.h"
#include "ReadableAudioFile.h"
@@ -34,6 +38,73 @@ namespace py = pybind11;
namespace Pedalboard {
+/**
+ * Encode `samples` to MP3 using multiple encoder threads, if requested and
+ * worthwhile. Returns the encoded file bytes, or std::nullopt to signal that
+ * the caller should fall back to the standard single-threaded encode path.
+ *
+ * Multithreading is only applied when encoding MP3; for any other format (or a
+ * buffer too short to benefit) this returns std::nullopt so the caller falls
+ * back to single-threaded encoding. Throws py::value_error only if numThreads
+ * is not a positive integer.
+ */
+inline std::optional<std::string> maybeEncodeMP3InParallel(
+ const py::array &samples, double sampleRate, const std::string &format,
+ int numChannels,
+ const std::optional<std::variant<std::string, float>> &quality,
+ int numThreads) {
+ if (numThreads < 1) {
+ throw py::value_error("num_threads must be a positive integer.");
+ }
+ if (numThreads == 1) {
+ return std::nullopt;
+ }
+
+ // Multithreaded encoding is only supported for MP3; silently fall back to
+ // single-threaded encoding for any other format.
+ std::string lowerFormat = format;
+ std::transform(lowerFormat.begin(), lowerFormat.end(), lowerFormat.begin(),
+ [](unsigned char c) { return std::tolower(c); });
+ if (lowerFormat != "mp3") {
+ return std::nullopt;
+ }
+
+ // Determine an approximate sample count without a full conversion, so tiny
+ // inputs stay on the (byte-identical) serial path where parallelism would not
+ // help.
+ size_t approxSamples = 0;
+ {
+ py::buffer_info info = samples.request();
+ for (auto dim : info.shape)
+ approxSamples = std::max<size_t>(approxSamples, static_cast<size_t>(dim));
+ }
+ if (approxSamples <
+ static_cast<size_t>(numThreads) * 3 * MP3_SAMPLES_PER_FRAME) {
+ return std::nullopt;
+ }
+
+ juce::AudioBuffer<float> buffer =
+ copyPyArrayIntoFloatJuceBuffer(samples, numChannels);
+ if (buffer.getNumChannels() != numChannels) {
+ throw std::runtime_error(
+ "AudioFile.encode was called with num_channels=" +
+ std::to_string(numChannels) + ", but was passed an array containing " +
+ std::to_string(buffer.getNumChannels()) + "-channel audio!");
+ }
+
+ LameMP3AudioFormat mp3Format;
+ int qualityOptionIndex =
+ determineQualityOptionIndex(&mp3Format, qualityToString(quality));
+
+ std::string result;
+ {
+ py::gil_scoped_release release;
+ result = encodeMP3InParallel(buffer, sampleRate, numChannels,
+ qualityOptionIndex, numThreads);
+ }
+ return result;
+}
+
// For pybind11-stubgen to properly parse the docstrings,
// we have to declare all of the AudioFile subclasses first before using
// their types (i.e.: as return types from `__new__`).
@@ -286,7 +357,13 @@ inline void init_audio_file(
[](const py::array samples, double sampleRate, std::string format,
int numChannels, int bitDepth,
std::optional<std::variant<std::string, float>> quality,
- CodecOptionsMap codecOptions) {
+ CodecOptionsMap codecOptions, int numThreads) {
+ if (auto parallelResult = maybeEncodeMP3InParallel(
+ samples, sampleRate, format, numChannels, quality,
+ numThreads)) {
+ return py::bytes(*parallelResult);
+ }
+
juce::MemoryBlock outputBlock;
auto audioFile = std::make_unique<WriteableAudioFile>(
format,
@@ -303,6 +380,7 @@ inline void init_audio_file(
py::arg("num_channels") = 1, py::arg("bit_depth") = 16,
py::arg("quality") = py::none(),
py::arg("codec_options") = CodecOptionsMap{},
+ py::arg("num_threads") = 1,
R"(
Encode an audio buffer to a Python :class:`bytes` object.
@@ -322,6 +400,15 @@ encoding process. This allows Python's Global Interpreter Lock (GIL) to be
released, which also makes this method much more performant in multi-threaded
programs.
+If ``num_threads`` is greater than 1, the input buffer is split into chunks that
+are encoded on separate threads and spliced back together. For long files this
+scales nearly linearly with the number of threads, at the cost of a small amount
+of compression efficiency (up to 10%). The decoded audio is perceptually
+identical to a single-threaded encode, but the resulting bytes are not identical
+to the serial encoder's output. Multithreaded encoding is only applied when
+encoding MP3; for any other format (or a buffer too short to benefit)
+``num_threads`` is ignored and encoding falls back to single-threaded.
+
.. warning::
This function will encode the entire audio buffer at once, and may consume a
large amount of memory if the input audio buffer is large.
diff --git a/pedalboard/io/ParallelMP3Encoder.h b/pedalboard/io/ParallelMP3Encoder.h
new file mode 100644
index 0000000..8bbf34a
--- /dev/null
+++ b/pedalboard/io/ParallelMP3Encoder.h
@@ -0,0 +1,480 @@
+/*
+ * pedalboard
+ * Copyright 2026 Spotify AB
+ *
+ * Licensed under the GNU Public License, Version 3.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <cstring>
+#include <stdexcept>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "../JuceHeader.h"
+#include "LameMP3AudioFormat.h"
+#include "WriteableAudioFileFlags.h"
+
+/**
+ * Parallel MP3 encoding by chunk-encode-and-splice.
+ *
+ * MP3 is a stream of (mostly) independent frames of 1152 samples each. Given an
+ * entire PCM buffer up front, we can split it into contiguous, frame-aligned
+ * regions, encode each region with its own LAME instance on a separate thread,
+ * and splice the resulting frames back together. For long files this scales
+ * close to linearly with core count.
+ *
+ * Three MP3 details make the splice correct:
+ *
+ * 1. Bit reservoir: normally a frame's main_data may begin in a previous
+ * frame, so frames are not independent. We disable the reservoir per
+ * worker so every frame is self-contained and safe to splice.
+ *
+ * 2. Encoder delay + filterbank warmup: each fresh LAME instance emits
+ * `enc_delay` samples of priming and needs a little audio *before* a
+ * region to encode its first frames correctly. We read the true encoder delay
+ * from the LAME tag and feed each worker frame-aligned pre-roll (and a little
+ * post-roll for the trailing MDCT lookahead), then discard the frames that
+ * cover the warmup regions.
+ *
+ * 3. The Xing/Info header: exactly one belongs at the front of the file. We
+ * drop the workers' individual tag frames and synthesize a single header
+ * with the correct total frame/byte counts for the merged stream.
+ *
+ * The output is a valid MP3 whose decoded audio is perceptually identical to a
+ * single-threaded encode. It is *not* byte-identical, because LAME's
+ * psychoacoustic model carries state across the whole stream; reproducing that
+ * exactly would require feeding each worker the entire preceding signal, which
+ * would defeat the parallelism.
+ */
+
+namespace Pedalboard {
+
+// MPEG-1 Layer III frame size in samples. MP3 writing only supports 32/44.1/48
+// kHz (all MPEG-1), so this is constant for every file we produce.
+static constexpr int MP3_SAMPLES_PER_FRAME = 1152;
+
+struct ParsedMP3Frame {
+ size_t offset; // byte offset of the frame within its buffer
+ size_t length; // frame length in bytes
+ int samples; // decoded samples represented by this frame
+ bool isTag; // true if this is a Xing/Info/LAME metadata frame
+};
+
+/**
+ * Parse an MPEG Layer III frame header at `pos`. Returns true and populates
+ * `frameLength` / `samplesPerFrame` if a valid header is present.
+ */
+inline bool parseMP3FrameHeader(const uint8_t *data, size_t pos, size_t len,
+ size_t &frameLength, int &samplesPerFrame) {
+ if (pos + 4 > len)
+ return false;
+
+ const uint8_t b0 = data[pos];
+ const uint8_t b1 = data[pos + 1];
+ const uint8_t b2 = data[pos + 2];
+
+ // 11-bit frame sync:
+ if (b0 != 0xFF || (b1 & 0xE0) != 0xE0)
+ return false;
+
+ const int version = (b1 >> 3) & 0b11; // 0=2.5, 1=reserved, 2=2, 3=1
+ const int layer = (b1 >> 1) & 0b11; // 1 == Layer III
+ if (version == 0b01 || layer != 0b01)
+ return false;
+
+ const bool isMpeg1 = (version == 0b11);
+ const int bitrateIndex = (b2 >> 4) & 0x0F;
+ const int sampleRateIndex = (b2 >> 2) & 0b11;
+ const int padding = (b2 >> 1) & 0b1;
+
+ static const int kBitrateMpeg1[] = {0, 32, 40, 48, 56, 64, 80, 96,
+ 112, 128, 160, 192, 224, 256, 320, 0};
+ static const int kBitrateMpeg2[] = {0, 8, 16, 24, 32, 40, 48, 56,
+ 64, 80, 96, 112, 128, 144, 160, 0};
+ static const int kSampleRateMpeg1[] = {44100, 48000, 32000, 0};
+ static const int kSampleRateMpeg2[] = {22050, 24000, 16000, 0};
+ static const int kSampleRateMpeg25[] = {11025, 12000, 8000, 0};
+
+ const int bitrate = (isMpeg1 ? kBitrateMpeg1 : kBitrateMpeg2)[bitrateIndex];
+ const int sampleRate =
+ (version == 0b11 ? kSampleRateMpeg1
+ : version == 0b10 ? kSampleRateMpeg2
+ : kSampleRateMpeg25)[sampleRateIndex];
+ if (bitrate == 0 || sampleRate == 0)
+ return false;
+
+ samplesPerFrame = isMpeg1 ? 1152 : 576;
+ const int coefficient = samplesPerFrame / 8; // 144 (MPEG-1) or 72 (MPEG-2)
+ frameLength =
+ static_cast<size_t>((coefficient * bitrate * 1000) / sampleRate) +
+ padding;
+ return frameLength > 4;
+}
+
+/** Return true if the frame at [offset, offset+length) carries a Xing/Info tag.
+ */
+inline bool mp3FrameIsTag(const uint8_t *data, size_t offset, size_t length) {
+ const size_t end = offset + length;
+ for (size_t i = offset; i + 4 <= end; i++) {
+ if (std::memcmp(data + i, "Xing", 4) == 0 ||
+ std::memcmp(data + i, "Info", 4) == 0)
+ return true;
+ }
+ return false;
+}
+
+/** Walk an MP3 byte buffer and return every frame it contains. */
+inline std::vector<ParsedMP3Frame> parseMP3Frames(const uint8_t *data,
+ size_t len) {
+ std::vector<ParsedMP3Frame> frames;
+ size_t pos = 0;
+ while (pos < len) {
+ size_t length = 0;
+ int samples = 0;
+ if (!parseMP3FrameHeader(data, pos, len, length, samples)) {
+ // Skip ID3 tags or resync on unexpected bytes by scanning for the next
+ // sync byte.
+ size_t next = pos + 1;
+ while (next < len && data[next] != 0xFF)
+ next++;
+ if (next >= len)
+ break;
+ pos = next;
+ continue;
+ }
+ if (pos + length > len)
+ break;
+ frames.push_back({pos, length, samples, mp3FrameIsTag(data, pos, length)});
+ pos += length;
+ }
+ return frames;
+}
+
+/**
+ * Read the encoder delay (in samples) from a LAME/Xing tag, if present.
+ * Returns the LAME default of 576 if the tag can't be found or parsed.
+ */
+inline int readMP3EncoderDelay(const uint8_t *data, size_t len) {
+ static constexpr int kLameDefaultEncoderDelay = 576;
+
+ // Find the Xing/Info magic string.
+ size_t idx = 0;
+ bool found = false;
+ for (; idx + 4 <= len; idx++) {
+ if (std::memcmp(data + idx, "Xing", 4) == 0 ||
+ std::memcmp(data + idx, "Info", 4) == 0) {
+ found = true;
+ break;
+ }
+ }
+ if (!found || idx + 8 > len)
+ return kLameDefaultEncoderDelay;
+
+ const uint32_t flags = (static_cast<uint32_t>(data[idx + 4]) << 24) |
+ (static_cast<uint32_t>(data[idx + 5]) << 16) |
+ (static_cast<uint32_t>(data[idx + 6]) << 8) |
+ static_cast<uint32_t>(data[idx + 7]);
+ size_t off = idx + 8;
+ if (flags & 0x1)
+ off += 4; // frame count
+ if (flags & 0x2)
+ off += 4; // byte count
+ if (flags & 0x4)
+ off += 100; // TOC
+ if (flags & 0x8)
+ off += 4; // quality
+
+ // The LAME extension begins with the version string "LAME....".
+ if (off + 4 > len || std::memcmp(data + off, "LAME", 4) != 0)
+ return kLameDefaultEncoderDelay;
+
+ const size_t delayOffset = off + 21; // 3 bytes: 12-bit delay + 12-bit padding
+ if (delayOffset + 3 > len)
+ return kLameDefaultEncoderDelay;
+
+ const int encDelay = (data[delayOffset] << 4) | (data[delayOffset + 1] >> 4);
+ return encDelay;
+}
+
+namespace detail {
+
+/** Encode a fully-prepared PCM block to MP3 bytes using a single LAME writer.
+ */
+inline juce::MemoryBlock encodeBlockToMP3(const juce::AudioBuffer<float> &block,
+ double sampleRate, int numChannels,
+ int qualityOptionIndex) {
+ juce::MemoryBlock output;
+ // The LAME writer takes ownership of this stream and deletes it in its
+ // destructor, so it must be heap-allocated. `output` outlives the writer.
+ // We hold it in a unique_ptr until the writer is successfully constructed so
+ // that a throwing constructor doesn't leak the stream.
+ auto stream = std::make_unique<juce::MemoryOutputStream>(output, false);
+
+ // The bit reservoir must be disabled so each frame is independently
+ // splice-able.
+ CodecOptionsMap codecOptions;
+ codecOptions[WriteableAudioFileFlag::Mp3EnableBitReservoir] = false;
+
+ {
+ LameMP3AudioFormat::Writer writer(stream.get(), sampleRate, numChannels,
+ qualityOptionIndex, codecOptions);
+ stream.release(); // the writer now owns the stream
+ if (!writer.writeFromFloatArrays(block.getArrayOfReadPointers(),
+ numChannels, block.getNumSamples())) {
+ throw std::runtime_error(
+ "Parallel MP3 encoder failed to encode a chunk.");
+ }
+ // Writer destructor here flushes LAME, writes the VBR tag, and deletes the
+ // stream.
+ }
+
+ return output;
+}
+
+/**
+ * Build the PCM block for one region: [coreStart - pre, coreEnd + post),
+ * zero-padded wherever the requested range falls outside the source buffer.
+ */
+inline juce::AudioBuffer<float>
+buildRegionBlock(const juce::AudioBuffer<float> &audio, int numChannels,
+ int coreStart, int coreEnd, int pre, int post) {
+ const int total = audio.getNumSamples();
+ const int start = coreStart - pre;
+ const int end = coreEnd + post;
+ const int length = end - start;
+
+ juce::AudioBuffer<float> block(numChannels, length);
+ block.clear();
+
+ const int validStart = std::max(0, start);
+ const int validEnd = std::min(total, end);
+ const int validLength = validEnd - validStart;
+ if (validLength > 0) {
+ const int destOffset = validStart - start;
+ for (int c = 0; c < numChannels; c++) {
+ block.copyFrom(c, destOffset, audio, c, validStart, validLength);
+ }
+ }
+ return block;
+}
+
+inline void writeBigEndian32(uint8_t *dest, uint32_t value) {
+ dest[0] = static_cast<uint8_t>(value >> 24);
+ dest[1] = static_cast<uint8_t>(value >> 16);
+ dest[2] = static_cast<uint8_t>(value >> 8);
+ dest[3] = static_cast<uint8_t>(value);
+}
+
+/**
+ * Produce a single Xing/Info header frame for the merged stream by patching a
+ * worker's tag frame with the correct total frame/byte counts. Because we strip
+ * all encoder priming when splicing, the gapless encoder-delay/padding fields
+ * are zeroed (the stream already starts at true sample zero).
+ */
+inline std::vector<uint8_t> buildMergedHeaderFrame(const uint8_t *tagFrame,
+ size_t tagFrameLength,
+ uint32_t totalAudioFrames,
+ uint32_t totalBytes) {
+ std::vector<uint8_t> header(tagFrame, tagFrame + tagFrameLength);
+
+ size_t idx = 0;
+ bool found = false;
+ for (; idx + 4 <= header.size(); idx++) {
+ if (std::memcmp(header.data() + idx, "Xing", 4) == 0 ||
+ std::memcmp(header.data() + idx, "Info", 4) == 0) {
+ found = true;
+ break;
+ }
+ }
+ if (!found || idx + 8 > header.size())
+ return header;
+
+ const uint32_t flags = (static_cast<uint32_t>(header[idx + 4]) << 24) |
+ (static_cast<uint32_t>(header[idx + 5]) << 16) |
+ (static_cast<uint32_t>(header[idx + 6]) << 8) |
+ static_cast<uint32_t>(header[idx + 7]);
+ size_t off = idx + 8;
+ if ((flags & 0x1) && off + 4 <= header.size()) {
+ writeBigEndian32(header.data() + off, totalAudioFrames);
+ off += 4;
+ }
+ if ((flags & 0x2) && off + 4 <= header.size()) {
+ writeBigEndian32(header.data() + off, totalBytes);
+ off += 4;
+ }
+ if (flags & 0x4)
+ off += 100;
+ if (flags & 0x8)
+ off += 4;
+
+ if (off + 4 <= header.size() &&
+ std::memcmp(header.data() + off, "LAME", 4) == 0) {
+ const size_t delayOffset = off + 21;
+ if (delayOffset + 3 <= header.size()) {
+ header[delayOffset] = 0;
+ header[delayOffset + 1] = 0;
+ header[delayOffset + 2] = 0;
+ }
+ }
+
+ return header;
+}
+
+} // namespace detail
+
+/**
+ * Encode `audio` to MP3 using `numWorkers` threads and return the full file
+ * bytes. `qualityOptionIndex` is the LAME quality index (as returned by
+ * `determineQualityOptionIndex`). This function does not touch Python and must
+ * be called with the GIL released.
+ */
+inline std::string encodeMP3InParallel(const juce::AudioBuffer<float> &audio,
+ double sampleRate, int numChannels,
+ int qualityOptionIndex, int numWorkers,
+ int warmupFrames = 1,
+ int postrollFrames = 1) {
+ const int total = audio.getNumSamples();
+ constexpr int FRAME = MP3_SAMPLES_PER_FRAME;
+
+ // Probe a short encode to learn this LAME build's encoder delay.
+ const int probeLength = std::min(total, FRAME * 4);
+ juce::AudioBuffer<float> probeBlock(numChannels, std::max(probeLength, 1));
+ probeBlock.clear();
+ if (probeLength > 0) {
+ for (int c = 0; c < numChannels; c++)
+ probeBlock.copyFrom(c, 0, audio, c, 0, probeLength);
+ }
+ const juce::MemoryBlock probe = detail::encodeBlockToMP3(
+ probeBlock, sampleRate, numChannels, qualityOptionIndex);
+ const int encoderDelay = readMP3EncoderDelay(
+ static_cast<const uint8_t *>(probe.getData()), probe.getSize());
+
+ // Choose pre-roll so (encoderDelay + pre) is a whole number of frames; this
+ // makes each region's kept audio begin exactly on a frame boundary in the
+ // decoded timeline.
+ const int align = ((-encoderDelay) % FRAME + FRAME) % FRAME;
+ const int pre = align + warmupFrames * FRAME;
+ const int post = postrollFrames * FRAME;
+ const int leadDrop = (encoderDelay + pre) / FRAME;
+
+ const int totalFrames = (total + FRAME - 1) / FRAME;
+ numWorkers = std::max(1, std::min(numWorkers, std::max(1, totalFrames)));
+ const int framesPerChunk = (totalFrames + numWorkers - 1) / numWorkers;
+
+ struct Region {
+ int coreStart;
+ int coreEnd;
+ int keepFrames;
+ };
+ std::vector<Region> regions;
+ for (int w = 0; w < numWorkers; w++) {
+ const int f0 = w * framesPerChunk;
+ const int f1 = std::min((w + 1) * framesPerChunk, totalFrames);
+ if (f0 >= f1)
+ break;
+ const int coreStart = f0 * FRAME;
+ const int coreEnd = std::min(f1 * FRAME, total);
+ const int keepFrames = (coreEnd - coreStart + FRAME - 1) / FRAME;
+ regions.push_back({coreStart, coreEnd, keepFrames});
+ }
+
+ // Encode each region on its own thread.
+ std::vector<juce::MemoryBlock> encoded(regions.size());
+ std::vector<std::exception_ptr> errors(regions.size());
+ std::vector<std::thread> threads;
+ threads.reserve(regions.size());
+ for (size_t i = 0; i < regions.size(); i++) {
+ threads.emplace_back([&, i]() {
+ try {
+ const Region &r = regions[i];
+ juce::AudioBuffer<float> block = detail::buildRegionBlock(
+ audio, numChannels, r.coreStart, r.coreEnd, pre, post);
+ encoded[i] = detail::encodeBlockToMP3(block, sampleRate, numChannels,
+ qualityOptionIndex);
+ } catch (...) {
+ errors[i] = std::current_exception();
+ }
+ });
+ }
+ for (auto &t : threads)
+ t.join();
+ for (auto &e : errors) {
+ if (e)
+ std::rethrow_exception(e);
+ }
+
+ // Trim each region to just the frames covering its core, and remember the
+ // first tag frame we see so we can build the merged header.
+ std::vector<std::pair<const uint8_t *, size_t>>
+ body; // (ptr, length) segments
+ const uint8_t *headerTagFrame = nullptr;
+ size_t headerTagFrameLength = 0;
+ uint32_t totalAudioFrames = 0;
+ size_t bodyBytes = 0;
+
+ // Keep the parsed frames alive alongside the encoded buffers.
+ std::vector<std::vector<ParsedMP3Frame>> parsedPerRegion(regions.size());
+
+ for (size_t i = 0; i < regions.size(); i++) {
+ const auto *data = static_cast<const uint8_t *>(encoded[i].getData());
+ const size_t size = encoded[i].getSize();
+ parsedPerRegion[i] = parseMP3Frames(data, size);
+ const auto &frames = parsedPerRegion[i];
+
+ std::vector<const ParsedMP3Frame *> audioFrames;
+ for (const auto &f : frames) {
+ if (f.isTag) {
+ if (headerTagFrame == nullptr) {
+ headerTagFrame = data + f.offset;
+ headerTagFrameLength = f.length;
+ }
+ } else {
+ audioFrames.push_back(&f);
+ }
+ }
+
+ const int keep = regions[i].keepFrames;
+ for (int k = 0; k < keep; k++) {
+ const int index = leadDrop + k;
+ if (index < 0 || index >= static_cast<int>(audioFrames.size()))
+ continue;
+ const ParsedMP3Frame *f = audioFrames[index];
+ body.emplace_back(data + f->offset, f->length);
+ bodyBytes += f->length;
+ totalAudioFrames++;
+ }
+ }
+
+ std::vector<uint8_t> header;
+ if (headerTagFrame != nullptr) {
+ const uint32_t totalBytes =
+ static_cast<uint32_t>(headerTagFrameLength + bodyBytes);
+ header = detail::buildMergedHeaderFrame(
+ headerTagFrame, headerTagFrameLength, totalAudioFrames, totalBytes);
+ }
+
+ std::string result;
+ result.reserve(header.size() + bodyBytes);
+ result.append(reinterpret_cast<const char *>(header.data()), header.size());
+ for (const auto &segment : body) {
+ result.append(reinterpret_cast<const char *>(segment.first),
+ segment.second);
+ }
+ return result;
+}
+
+} // namespace Pedalboard
diff --git a/pedalboard/io/WriteableAudioFile.h b/pedalboard/io/WriteableAudioFile.h
index 51a312c..5a25004 100644
--- a/pedalboard/io/WriteableAudioFile.h
+++ b/pedalboard/io/WriteableAudioFile.h
@@ -39,6 +39,27 @@ bool isInteger(double value) {
return modf(value, &intpart) == 0.0;
}
+/**
+ * Normalize the optional quality argument (either a string like "V0" or
+ * "320 kbps", or a numeric bitrate) into a string suitable for
+ * determineQualityOptionIndex.
+ */
+inline std::string qualityToString(
+ const std::optional<std::variant<std::string, float>> &qualityInput) {
+ std::string qualityString;
+ if (qualityInput) {
+ if (auto *q = std::get_if<std::string>(&(*qualityInput))) {
+ qualityString = *q;
+ } else if (auto *q = std::get_if<float>(&(*qualityInput))) {
+ qualityString =
+ isInteger(*q) ? std::to_string((int)*q) : std::to_string(*q);
+ } else {
+ throw std::runtime_error("Unknown quality type!");
+ }
+ }
+ return qualityString;
+}
+
// Per-format overrides for the "worst"/"best"/"fastest"/"slowest"
static inline std::map<std::string, std::pair<std::string, std::string>>
MIN_MAX_QUALITY_OPTIONS = {
@@ -338,20 +359,7 @@ public:
}
// Normalize the input to a string here, as we need to do parsing anyways:
- std::string qualityString;
- if (qualityInput) {
- if (auto *q = std::get_if<std::string>(&(*qualityInput))) {
- qualityString = *q;
- } else if (auto *q = std::get_if<float>(&(*qualityInput))) {
- if (isInteger(*q)) {
- qualityString = std::to_string((int)*q);
- } else {
- qualityString = std::to_string(*q);
- }
- } else {
- throw std::runtime_error("Unknown quality type!");
- }
- }
+ std::string qualityString = qualityToString(qualityInput);
int qualityOptionIndex = determineQualityOptionIndex(format, qualityString);
if (format->getQualityOptions().size() > qualityOptionIndex) {
diff --git a/pedalboard_native/io/__init__.pyi b/pedalboard_native/io/__init__.pyi
index d89dc1d..c5f7e8d 100644
--- a/pedalboard_native/io/__init__.pyi
+++ b/pedalboard_native/io/__init__.pyi
@@ -223,6 +223,7 @@ class AudioFile:
bit_depth: int = 16,
quality: typing.Optional[typing.Union[str, float]] = None,
codec_options: typing.Dict[WriteableAudioFileFlag, typing.Union[bool, float, int, str]] = ...,
+ num_threads: int = 1,
) -> bytes:
"""
Encode an audio buffer to a Python :class:`bytes` object.
@@ -243,6 +244,15 @@ class AudioFile:
released, which also makes this method much more performant in multi-threaded
programs.
+ If ``num_threads`` is greater than 1, the input buffer is split into chunks that
+ are encoded on separate threads and spliced back together. For long files this
+ scales nearly linearly with the number of threads, at the cost of a small amount
+ of compression efficiency (up to 10%). The decoded audio is perceptually
+ identical to a single-threaded encode, but the resulting bytes are not identical
+ to the serial encoder's output. Multithreaded encoding is only applied when
+ encoding MP3; for any other format (or a buffer too short to benefit)
+ ``num_threads`` is ignored and encoding falls back to single-threaded.
+
.. warning::
This function will encode the entire audio buffer at once, and may consume a
large amount of memory if the input audio buffer is large.
diff --git a/tests/test_parallel_mp3_encode.py b/tests/test_parallel_mp3_encode.py
new file mode 100644
index 0000000..354a746
--- /dev/null
+++ b/tests/test_parallel_mp3_encode.py
@@ -0,0 +1,249 @@
+#! /usr/bin/env python
+#
+# Copyright 2026 Spotify AB
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Tests for the parallel MP3 encoding path exposed via
+``AudioFile.encode(..., num_threads=N)``.
+
+The parallel encoder splits a buffer into MP3-frame-aligned chunks, encodes them
+on separate threads (with the bit reservoir disabled so frames are independently
+splice-able), and stitches the resulting frames back together. It must produce a
+valid MP3 whose decoded audio is perceptually identical to a single-threaded
+encode, without introducing clicks at the chunk boundaries.
+
+Multithreaded encoding (``num_threads > 1``) is only applied for MP3; for any
+other format it is silently ignored and encoding falls back to single-threaded.
+"""
+
+import io
+
+import numpy as np
+import pytest
+
+import pedalboard
+
+from .utils import generate_sine_at
+
+MP3_FRAME_LENGTH_SAMPLES = 1152
+
+
+def _decode_mp3_bytes(encoded: bytes):
+ with pedalboard.io.ReadableAudioFile(io.BytesIO(encoded)) as af:
+ return af.read(af.frames), af.samplerate, af.num_channels
+
+
+def _best_aligned_snr(decoded: np.ndarray, original: np.ndarray, samplerate: int):
+ """
+ A decoded MP3 is delayed relative to its source by encoder priming (present
+ only in monolithic encodes) plus a fixed decoder delay, so we search a small
+ window of leading offsets for the best alignment and return
+ (snr_dB, shift, aligned_abs_error).
+ """
+ n = original.shape[-1]
+ best = (-np.inf, 0, None)
+ for shift in range(0, 1400):
+ d = decoded[:, shift:]
+ m = min(d.shape[-1], n)
+ if m < samplerate:
+ continue
+ err = d[:, :m] - original[:, :m]
+ power = float(np.mean(original[:, :m] ** 2))
+ snr = 10 * np.log10(power / float(np.mean(err**2)))
+ if snr > best[0]:
+ best = (snr, shift, np.abs(err))
+ return best
+
+
[email protected]("num_channels", [1, 2])
+def test_parallel_mp3_encode_matches_serial_fidelity(num_channels: int):
+ """
+ Parallel MP3 encoding should decode to essentially the same audio as a
+ single-threaded encode (equal SNR versus the original), even though the
+ encoded bytes differ.
+ """
+ samplerate = 44100
+ signal = generate_sine_at(
+ samplerate, num_seconds=10, num_channels=num_channels
+ ).astype(np.float32)
+ original = signal if signal.ndim == 2 else signal.reshape(1, -1)
+
+ serial = pedalboard.io.AudioFile.encode(
+ signal, samplerate, "mp3", num_channels=num_channels, quality="256 kbps"
+ )
+ parallel = pedalboard.io.AudioFile.encode(
+ signal,
+ samplerate,
+ "mp3",
+ num_channels=num_channels,
+ quality="256 kbps",
+ num_threads=4,
+ )
+
+ serial_decoded, _, _ = _decode_mp3_bytes(serial)
+ parallel_decoded, _, parallel_channels = _decode_mp3_bytes(parallel)
+
+ assert parallel_channels == num_channels
+
+ serial_snr, _, _ = _best_aligned_snr(serial_decoded, original, samplerate)
+ parallel_snr, _, _ = _best_aligned_snr(parallel_decoded, original, samplerate)
+
+ assert parallel_snr > 20
+ # Parallel encoding must not measurably degrade quality vs. a serial encode:
+ assert abs(parallel_snr - serial_snr) < 1.0
+
+
+def test_parallel_mp3_encode_has_no_seam_artifacts():
+ """
+ Splicing chunk boundaries must not introduce clicks: the error at seam
+ boundaries should be no larger than the overall error envelope.
+ """
+ samplerate = 44100
+ num_encoders = 8
+ signal = generate_sine_at(samplerate, num_seconds=10).astype(np.float32).reshape(
+ 1, -1
+ )
+ encoded = pedalboard.io.AudioFile.encode(
+ signal,
+ samplerate,
+ "mp3",
+ num_channels=1,
+ quality="256 kbps",
+ num_threads=num_encoders,
+ )
+ decoded, _, _ = _decode_mp3_bytes(encoded)
+ _, shift, error = _best_aligned_snr(decoded, signal, samplerate)
+ assert error is not None
+
+ total = signal.shape[-1]
+ num_frames = (total + MP3_FRAME_LENGTH_SAMPLES - 1) // MP3_FRAME_LENGTH_SAMPLES
+ frames_per_chunk = (num_frames + num_encoders - 1) // num_encoders
+
+ window = 128
+ worst_seam = 0.0
+ for w in range(1, num_encoders):
+ seam = w * frames_per_chunk * MP3_FRAME_LENGTH_SAMPLES
+ if seam >= total:
+ continue
+ idx = seam - shift
+ worst_seam = max(
+ worst_seam, float(error[:, max(0, idx - window) : idx + window].max())
+ )
+
+ # No seam should spike above the global maximum error:
+ assert worst_seam <= float(error.max()) * 1.05
+
+
+def test_parallel_mp3_encode_one_encoder_matches_default():
+ """
+ num_threads=1 must be byte-identical to the default serial path.
+ """
+ samplerate = 44100
+ signal = generate_sine_at(samplerate, num_seconds=5).astype(np.float32)
+ default = pedalboard.io.AudioFile.encode(
+ signal, samplerate, "mp3", num_channels=1, quality="256 kbps"
+ )
+ explicit = pedalboard.io.AudioFile.encode(
+ signal,
+ samplerate,
+ "mp3",
+ num_channels=1,
+ quality="256 kbps",
+ num_threads=1,
+ )
+ assert default == explicit
+
+
+def test_parallel_mp3_encode_short_buffer_falls_back_to_serial():
+ """
+ Buffers too short to benefit from parallelism should produce byte-identical
+ output to the serial encoder.
+ """
+ samplerate = 44100
+ signal = (
+ (0.5 * np.sin(2 * np.pi * 440 * np.arange(2000) / samplerate))
+ .astype(np.float32)
+ .reshape(1, -1)
+ )
+ serial = pedalboard.io.AudioFile.encode(
+ signal, samplerate, "mp3", num_channels=1, quality="256 kbps"
+ )
+ parallel = pedalboard.io.AudioFile.encode(
+ signal,
+ samplerate,
+ "mp3",
+ num_channels=1,
+ quality="256 kbps",
+ num_threads=8,
+ )
+ assert serial == parallel
+
+
[email protected]("non_mp3_format", ["wav", "flac", "ogg"])
+def test_parallel_mp3_encode_non_mp3_falls_back_to_serial(non_mp3_format: str):
+ """
+ num_threads > 1 is only applied for MP3. For any other format it is silently
+ ignored and encoding falls back to single-threaded.
+ """
+ signal = generate_sine_at(44100, num_seconds=1).astype(np.float32)
+ serial = pedalboard.io.AudioFile.encode(
+ signal, 44100, non_mp3_format, num_channels=1
+ )
+ with_threads = pedalboard.io.AudioFile.encode(
+ signal, 44100, non_mp3_format, num_channels=1, num_threads=4
+ )
+
+ # For deterministic formats, falling back to serial produces byte-identical
+ # output. (Ogg embeds a random bitstream serial number, so it is not
+ # byte-reproducible; we only check that it remains a valid file below.)
+ if non_mp3_format in ("wav", "flac"):
+ assert serial == with_threads
+
+ with pedalboard.io.ReadableAudioFile(io.BytesIO(with_threads)) as af:
+ assert af.samplerate == 44100
+ assert af.num_channels == 1
+ assert af.frames > 0
+
+
+def test_parallel_mp3_encode_rejects_invalid_thread_count():
+ signal = generate_sine_at(44100, num_seconds=1).astype(np.float32)
+ with pytest.raises(ValueError, match="positive integer"):
+ pedalboard.io.AudioFile.encode(
+ signal, 44100, "mp3", num_channels=1, num_threads=0
+ )
+
+
+def test_parallel_mp3_encode_is_readable_and_correct_length():
+ """
+ The parallel-encoded file must be readable and approximately the right
+ length (within a couple of MP3 frames of padding).
+ """
+ samplerate = 44100
+ signal = generate_sine_at(samplerate, num_seconds=7).astype(np.float32).reshape(
+ 1, -1
+ )
+ encoded = pedalboard.io.AudioFile.encode(
+ signal,
+ samplerate,
+ "mp3",
+ num_channels=1,
+ quality="256 kbps",
+ num_threads=4,
+ )
+ with pedalboard.io.ReadableAudioFile(io.BytesIO(encoded)) as af:
+ assert af.samplerate == samplerate
+ assert af.num_channels == 1
+ assert af.frames >= signal.shape[-1]
+ assert af.frames <= signal.shape[-1] + MP3_FRAME_LENGTH_SAMPLES * 4