π π A Python library for audio.
C audioaudio-processingaudio-productionaudio-researchaudio-unitaugmentationjucemachine-learningpybind11pythonvst3vst3-host
Add `num_threads` to `AudioFile::encode`. (#494)
Peter Sobotcb4516d17034
diff --git a/CMakeLists.txt b/CMakeLists.txtindex d9ae8b9..2241de1 100644--- a/CMakeLists.txt+++ b/CMakeLists.txt@@ -169,6 +169,11 @@ elseif(WIN32)# Windows specific flagsadd_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 librarieslist(APPEND PLATFORM_LIBRARIESdiff --git a/pedalboard/BufferUtils.h b/pedalboard/BufferUtils.hindex 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 filediff --git a/pedalboard/io/AudioFileInit.h b/pedalboard/io/AudioFileInit.hindex 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 bereleased, which also makes this method much more performant in multi-threadedprograms.+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 alarge amount of memory if the input audio buffer is large.diff --git a/pedalboard/io/ParallelMP3Encoder.h b/pedalboard/io/ParallelMP3Encoder.hnew file mode 100644index 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 Pedalboarddiff --git a/pedalboard/io/WriteableAudioFile.h b/pedalboard/io/WriteableAudioFile.hindex 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__.pyiindex 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-threadedprograms.+ 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 alarge 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.pynew file mode 100644index 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