Skip to content

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

Improve documentation consistency.

Peter Sobotfc009ef8984e
diff --git a/pedalboard/io/AudioFile.h b/pedalboard/io/AudioFile.h
index 04569b0..7f53864 100644
--- a/pedalboard/io/AudioFile.h
+++ b/pedalboard/io/AudioFile.h
@@ -122,6 +122,8 @@ public:
return "int8";
case 16:
return "int16";
+ case 24:
+ return "int24";
case 32:
return "int32";
case 64:
@@ -596,8 +598,18 @@ public:
" bits. Supported bit depths: " + bitDepthString.str());
}
- throw std::domain_error("Unable to create audio file writer: " +
- filename);
+ std::string humanReadableQuality;
+ if (qualityString.empty()) {
+ humanReadableQuality = "None";
+ } else {
+ humanReadableQuality = qualityString;
+ }
+
+ throw std::domain_error(
+ "Unable to create audio file writer with samplerate=" +
+ std::to_string(writeSampleRate) +
+ ", num_channels=" + std::to_string(numChannels) + ", bit_depth=" +
+ std::to_string(bitDepth) + ", and quality=" + humanReadableQuality);
} else {
outputStream.release();
}
@@ -853,6 +865,38 @@ public:
return writer->getNumChannels();
}
+ std::string getFileDatatype() const {
+ if (!writer)
+ throw std::runtime_error("I/O operation on a closed file.");
+
+ if (writer->isFloatingPoint()) {
+ switch (writer->getBitsPerSample()) {
+ case 16: // OGG returns 16-bit int data, but internally stores floats
+ case 32:
+ return "float32";
+ case 64:
+ return "float64";
+ default:
+ return "unknown";
+ }
+ } else {
+ switch (writer->getBitsPerSample()) {
+ case 8:
+ return "int8";
+ case 16:
+ return "int16";
+ case 24:
+ return "int24";
+ case 32:
+ return "int32";
+ case 64:
+ return "int64";
+ default:
+ return "unknown";
+ }
+ }
+ }
+
std::shared_ptr<WriteableAudioFile> enter() { return shared_from_this(); }
void exit(const py::object &type, const py::object &value,
@@ -922,8 +966,8 @@ inline void init_audiofile(py::module &m) {
"An audio file reader interface, with native support for Ogg Vorbis, "
"MP3, WAV, FLAC, and AIFF files on all operating systems. On some "
"platforms, other formats may also be readable. (Use "
- "AudioFile.supported_read_formats and AudioFile.supported_write_formats "
- "to see which formats are supported on the current platform.)")
+ "pedalboard.io.get_supported_read_formats() to see which formats are "
+ "supported on the current platform.)")
.def(py::init([](std::string filename) {
return std::make_shared<ReadableAudioFile>(filename);
}),
@@ -934,26 +978,28 @@ inline void init_audiofile(py::module &m) {
return std::make_shared<ReadableAudioFile>(filename);
},
py::arg("cls"), py::arg("filename"))
- .def("read", &ReadableAudioFile::read, py::arg("num_frames") = 0,
- "Read the given number of frames (samples in each channel) from the "
- "audio file at the current position. Audio samples are returned in "
- "the shape (channels, samples); i.e.: a stereo audio file will have "
- "shape (2, <length>). Returned data is always in float32 format.")
- .def("read_raw", &ReadableAudioFile::readRaw, py::arg("num_frames") = 0,
- "Read the given number of frames (samples in each channel) from the "
- "audio file at the current position. Audio samples are returned in "
- "the shape (channels, samples); i.e.: a stereo audio file will have "
- "shape (2, <length>). Returned data is in the raw format stored by "
- "the underlying file (one of int8, int16, int32, or float32).")
+ .def(
+ "read", &ReadableAudioFile::read, py::arg("num_frames") = 0,
+ "Read the given number of frames (samples in each channel) from this "
+ "audio file at the current position. Audio samples are returned in "
+ "the shape (channels, samples); i.e.: a stereo audio file will have "
+ "shape (2, <length>). Returned data is always in float32 format.")
+ .def(
+ "read_raw", &ReadableAudioFile::readRaw, py::arg("num_frames") = 0,
+ "Read the given number of frames (samples in each channel) from this "
+ "audio file at the current position. Audio samples are returned in "
+ "the shape (channels, samples); i.e.: a stereo audio file will have "
+ "shape (2, <length>). Returned data is in the raw format stored by "
+ "the underlying file (one of int8, int16, int32, or float32).")
.def("seekable", &ReadableAudioFile::isSeekable,
- "Returns True if the file is currently open and calls to seek() "
+ "Returns True if this file is currently open and calls to seek() "
"will work.")
.def("seek", &ReadableAudioFile::seek, py::arg("position"),
- "Seek the file to the provided location in frames.")
+ "Seek this file to the provided location in frames.")
.def("tell", &ReadableAudioFile::tell,
- "Fetch the position in the audio file, in frames.")
+ "Fetch the position in this audio file, in frames.")
.def("close", &ReadableAudioFile::close,
- "Close the file, rendering this object unusable.")
+ "Close this file, rendering this object unusable.")
.def("__enter__", &ReadableAudioFile::enter)
.def("__exit__", &ReadableAudioFile::exit)
.def("__repr__",
@@ -967,7 +1013,7 @@ inline void init_audiofile(py::module &m) {
ss << " closed";
} else {
ss << " samplerate=" << file.getSampleRate();
- ss << " channels=" << file.getNumChannels();
+ ss << " num_channels=" << file.getNumChannels();
ss << " frames=" << file.getLengthInSamples();
ss << " file_dtype=" << file.getFileDatatype();
}
@@ -975,33 +1021,35 @@ inline void init_audiofile(py::module &m) {
ss << ">";
return ss.str();
})
- .def_property_readonly(
- "name", &ReadableAudioFile::getFilename,
- "If the file has been closed, this property will be True.")
+ .def_property_readonly("name", &ReadableAudioFile::getFilename,
+ "The name of this file.")
.def_property_readonly(
"closed", &ReadableAudioFile::isClosed,
- "If the file has been closed, this property will be True.")
+ "If this file has been closed, this property will be True.")
.def_property_readonly("samplerate", &ReadableAudioFile::getSampleRate,
- "Fetch the sample rate of the file in samples "
+ "The sample rate of this file in samples "
"(per channel) per second (Hz).")
.def_property_readonly("channels", &ReadableAudioFile::getNumChannels,
- "Fetch the number of channels in the file.")
+ "The number of channels in this file.")
.def_property_readonly("frames", &ReadableAudioFile::getLengthInSamples,
- "Fetch the total number of frames (samples per "
- "channel) in the file.")
+ "The total number of frames (samples per "
+ "channel) in this file.")
.def_property_readonly(
"duration", &ReadableAudioFile::getDuration,
- "Fetch the duration of this file (frames divided by sample rate).")
+ "The duration of this file (frames divided by sample rate).")
.def_property_readonly(
"file_dtype", &ReadableAudioFile::getFileDatatype,
- "Fetch the data type stored natively by the file. Note that read() "
- "will always return a float32 array, regardless of this method.");
+ "The data type stored natively by this file. Note that read(...) "
+ "will always return a float32 array, regardless of the value of this "
+ "property.");
py::class_<WriteableAudioFile, AudioFile,
std::shared_ptr<WriteableAudioFile>>(
m, "WriteableAudioFile",
"An audio file writer interface, with native support for Ogg Vorbis, "
- "MP3, WAV, FLAC, and AIFF files on all operating systems.")
+ "MP3, WAV, FLAC, and AIFF files on all operating systems. (Use "
+ "pedalboard.io.get_supported_write_formats() to see which formats are "
+ "supported on the current platform.)")
.def(
py::init([](std::string filename, double sampleRate, int numChannels,
int bitDepth,
@@ -1033,34 +1081,67 @@ inline void init_audiofile(py::module &m) {
[](WriteableAudioFile &file, py::array_t<char> samples) {
file.write<char>(samples);
},
- py::arg("samples").noconvert())
+ py::arg("samples").noconvert(),
+ "Encode an array of int8 (8-bit signed integer) audio data and write "
+ "it to this file. The number of channels in the array must match the "
+ "number of channels used to open the file. The array may contain "
+ "audio in any shape. If the file's bit depth or format does not "
+ "match this data type, the audio will be automatically converted.")
.def(
"write",
[](WriteableAudioFile &file, py::array_t<short> samples) {
file.write<short>(samples);
},
- py::arg("samples").noconvert())
+ py::arg("samples").noconvert(),
+ "Encode an array of int16 (16-bit signed integer) audio data and "
+ "write it to this file. The number of channels in the array must "
+ "match the number of channels used to open the file. The array may "
+ "contain audio in any shape. If the file's bit depth or format does "
+ "not match this data type, the audio will be automatically "
+ "converted.")
.def(
"write",
[](WriteableAudioFile &file, py::array_t<int> samples) {
file.write<int>(samples);
},
- py::arg("samples").noconvert())
+ py::arg("samples").noconvert(),
+ "Encode an array of int32 (32-bit signed integer) audio data and "
+ "write it to this file. The number of channels in the array must "
+ "match the number of channels used to open the file. The array may "
+ "contain audio in any shape. If the file's bit depth or format does "
+ "not match this data type, the audio will be automatically "
+ "converted.")
.def(
"write",
[](WriteableAudioFile &file, py::array_t<float> samples) {
file.write<float>(samples);
},
- py::arg("samples").noconvert())
+ py::arg("samples").noconvert(),
+ "Encode an array of float32 (32-bit floating-point) audio data and "
+ "write it to this file. The number of channels in the array must "
+ "match the number of channels used to open the file. The array may "
+ "contain audio in any shape. If the file's bit depth or format does "
+ "not match this data type, the audio will be automatically "
+ "converted.")
.def(
"write",
[](WriteableAudioFile &file, py::array_t<double> samples) {
file.write<double>(samples);
},
- py::arg("samples").noconvert())
- .def("flush", &WriteableAudioFile::flush)
+ py::arg("samples").noconvert(),
+ "Encode an array of float64 (64-bit floating-point) audio data and "
+ "write it to this file. The number of channels in the array must "
+ "match the number of channels used to open the file. The array may "
+ "contain audio in any shape. No supported formats support float64 "
+ "natively, so the audio will be converted automatically.")
+ .def("flush", &WriteableAudioFile::flush,
+ "Attempt to flush this audio file's contents to disk. Not all "
+ "formats support flushing, so this may throw a RuntimeError. (If "
+ "this happens, closing the file will reliably force a flush to "
+ "occur.)")
.def("close", &WriteableAudioFile::close,
- "Close the file, rendering this object unusable.")
+ "Close this file, flushing its contents to disk and rendering this "
+ "object unusable for further writing.")
.def("__enter__", &WriteableAudioFile::enter)
.def("__exit__", &WriteableAudioFile::exit)
.def("__repr__",
@@ -1074,11 +1155,11 @@ inline void init_audiofile(py::module &m) {
ss << " closed";
} else {
ss << " samplerate=" << file.getSampleRate();
- ss << " channels=" << file.getNumChannels();
- ss << " frames=" << file.getFramesWritten();
+ ss << " num_channels=" << file.getNumChannels();
if (file.getQuality()) {
ss << " quality=\"" << file.getQuality().value() << "\"";
}
+ ss << " file_dtype=" << file.getFileDatatype();
}
ss << " at " << &file;
ss << ">";
@@ -1086,19 +1167,23 @@ inline void init_audiofile(py::module &m) {
})
.def_property_readonly(
"closed", &WriteableAudioFile::isClosed,
- "If the file has been closed, this property will be True.")
+ "If this file has been closed, this property will be True.")
.def_property_readonly("samplerate", &WriteableAudioFile::getSampleRate,
- "Fetch the sample rate of the file in samples "
+ "The sample rate of this file in samples "
"(per channel) per second (Hz).")
.def_property_readonly("channels", &WriteableAudioFile::getNumChannels,
- "Fetch the number of channels in the file.")
+ "The number of channels in this file.")
.def_property_readonly("frames", &WriteableAudioFile::getFramesWritten,
- "Fetch the total number of frames (samples per "
- "channel) written to the file so far.")
- // TODO: Add file_dtype!
+ "The total number of frames (samples per "
+ "channel) written to this file so far.")
+ .def_property_readonly(
+ "file_dtype", &WriteableAudioFile::getFileDatatype,
+ "The data type stored natively by this file. Note that write(...) "
+ "will accept multiple datatypes, regardless of the value of this "
+ "property.")
.def_property_readonly(
"quality", &WriteableAudioFile::getQuality,
- "Fetch the quality setting used to write this file. For many "
+ "The quality setting used to write this file. For many "
"formats, this may be None.");
m.def("get_supported_read_formats", []() {
diff --git a/tests/test_io.py b/tests/test_io.py
index ec5bd20..62242a9 100644
--- a/tests/test_io.py
+++ b/tests/test_io.py
@@ -171,8 +171,7 @@ def test_basic_read(audio_filename: str, samplerate: float):
assert samples.shape == (1, int(samplerate * EXPECTED_DURATION_SECONDS / 2))
assert f"samplerate={int(af.samplerate)}" in repr(af)
- assert f"channels={af.channels}" in repr(af)
- assert f"frames={af.frames}" in repr(af)
+ assert f"num_channels={af.channels}" in repr(af)
assert f"file_dtype={af.file_dtype}" in repr(af)
af.seek(0)
@@ -231,8 +230,7 @@ def test_use_reader_as_context_manager(audio_filename: str, samplerate: float):
assert samples.shape == (1, int(samplerate * EXPECTED_DURATION_SECONDS / 2))
assert f"samplerate={int(af.samplerate)}" in repr(af)
- assert f"channels={af.channels}" in repr(af)
- assert f"frames={af.frames}" in repr(af)
+ assert f"num_channels={af.channels}" in repr(af)
with pytest.raises(RuntimeError):
af.channels