docs: update documentation for master

Author: psobot

.nojekyll

@@ -0,0 +1,6 @@
+Citation
+=======
+
+.. mdinclude:: ../../README.md
+   :start-line: 289
+   :end-line: 306

_sources/citation.rst.txt

@@ -0,0 +1,21 @@
+Plugin Compatibility
+====================
+
+``pedalboard`` allows loading VST3® and Audio Unit plugins, which could contain *any* code.
+Most plugins that have been tested work just fine with ``pedalboard``, but some plugins may
+not work with ``pedalboard``; at worst, some may even crash the Python interpreter without
+warning and with no ability to catch the error.
+
+Most audio plugins are "well-behaved" and conform to a set of conventions for how audio
+plugins are supposed to work, but many do not conform to the VST3® or Audio Unit
+specifications. ``pedalboard`` attempts to detect some common programming errors in plugins
+and can work around many issues, including automatically detecting plugins that don't
+clear their internal state when asked. Even so, plugins can misbehave without ``pedalboard``
+noticing.
+
+If audio is being rendered incorrectly or if audio is "leaking" from one ``process()`` call
+to the next in an undesired fashion, try:
+
+1. Passing silence to the plugin in between calls to ``process()``, to ensure that any
+   reverb tails or other internal state has time to fade to silence
+2. Reloading the plugin every time audio is processed (with ``pedalboard.load_plugin``)

_sources/compatibility.rst.txt

@@ -0,0 +1,6 @@
+Examples
+========
+
+.. mdinclude:: ../../README.md
+   :start-line: 75
+   :end-line: 284

_sources/examples.rst.txt

@@ -0,0 +1,66 @@
+Frequently Asked Questions
+--------------------------
+
+Can Pedalboard be used with live (real-time) audio?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As of version 0.7.0, yes! See the :class:`pedalboard.io.AudioStream` class for more details.
+
+
+Does Pedalboard support changing a plugin's parameters over time?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Yes! While there's no built-in function for this, it is possible to
+vary the parameters of a plugin over time manually:
+
+.. code-block:: python
+
+   from pedalboard.io import AudioFile
+   from pedalboard import Pedalboard, Compressor, Reverb
+   from tqdm import tqdm
+
+   board = Pedalboard([Compressor(), Reverb()])
+   reverb = board[1]
+
+   # Smaller step sizes would give a smoother transition,
+   # at the expense of processing speed
+   step_size_in_samples = 100
+
+   # Manually step through the audio _n_ samples at a time, reading in chunks:
+   with AudioFile("sample.wav") as af:
+
+       # Open the output audio file so that we can directly write audio as we process, saving memory:
+       with AudioFile(
+           "sample-processed-output.wav", "w", af.samplerate, num_channels=af.num_channels
+       ) as o:
+
+           # Create a progress bar to show processing speed in real-time:
+           with tqdm(total=af.frames, unit=' samples') as pbar:
+               for i in range(0, af.frames, step_size_in_samples):
+                   chunk = af.read(step_size_in_samples)
+
+                   # Set the reverb's "wet" parameter to be equal to the
+                   # percentage through the track (i.e.: make a ramp from 0% to 100%)
+                   percentage_through_track = i / af.frames
+                   reverb.wet_level = percentage_through_track
+
+                   # Update our progress bar with the number of samples received:
+                   pbar.update(chunk.shape[1])
+
+                   # Process this chunk of audio, setting `reset` to `False`
+                   # to ensure that reverb tails aren't cut off
+                   output = board.process(chunk, af.samplerate, reset=False)
+                   o.write(output)
+
+With this technique, it's possible to automate any parameter. Usually, using a step size of somewhere between 100 and 1,000 (2ms to 22ms at a 44.1kHz sample rate) is small enough to avoid hearing any audio artifacts, but big enough to avoid slowing down the code dramatically.
+
+Can Pedalboard be used with VST instruments, instead of effects?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As of version 0.7.4, yes! See the :class:`pedalboard.VST3Plugin` and :class:`pedalboard.AudioUnitPlugin` classed for more details.
+
+Can Pedalboard plugins accept MIDI?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As of version 0.7.4, both :class:`pedalboard.VST3Plugin` and :class:`pedalboard.AudioUnitPlugin` support passing MIDI
+messages to instrument plugins for audio rendering. However, effect plugins cannot yet be passed MIDI data.

_sources/faq.rst.txt

@@ -0,0 +1,26 @@
+:og:title: Pedalboard Documentation
+:og:description: 🎛 🔊 Documentation for Pedalboard: A Python library for working with audio.
+
+.. mdinclude:: ../../README.md
+   :end-line: 74
+
+Reference
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   API Reference (Audio Plugins) <reference/pedalboard>
+   API Reference (Audio I/O) <reference/pedalboard.io>
+
+
+Documentation
+-------------
+
+.. toctree::
+   examples
+   faq
+   compatibility
+   internals
+   license
+   GitHub Repo <http://github.com/spotify/pedalboard>

_sources/index.rst.txt

@@ -0,0 +1,33 @@
+Pedalboard Internals
+====================
+
+Pedalboard is a Python wrapper around JUCE, an open-source cross-platform C++ library for developing audio applications.
+Most of Pedalboard is written in C++ using pybind11, a library for binding C++ code to Python. The design goals of
+Pedalboard are to:
+
+ - Expose the digital signal processing functionality of JUCE to Python code in an idiomatic way
+ - Provide the raw speed and performance of JUCE's DSP code to Python
+ - Hide the complexity of JUCE's C++ interface and show programmers an intuitive API
+ 
+
+Adding new built-in Pedalboard plugins
+--------------------------------------
+
+Pedalboard supports loading VST3® and Audio Unit plugins, but it can also be useful to add new plugins to Pedalboard itself, for a variety of reasons:
+
+ - **Wider compatibility**: Not all plugins are supported on every platform. (Notably, VST3® plugins that support Linux are rare.)
+ - **Fewer dependencies**: ``import pedalboard`` is simpler than ``pedalboard.load_plugin(...)``, and removes the need to copy around plugin files and any associated resources.
+ - **More options**: Available plugins might not include all of the required options; for instance, plugins meant for musical use may not include the appropriate options to be used for machine learning use cases, or vice versa.
+ - **Stability**: Some VST3® or Audio Unit plugins might have compatibility issues with Pedalboard or in environments where Pedalboard is used. Implementing the same effect within Pedalboard itself ensures that the logic is portable, well tested, thread-safe, and performant.
+
+
+Design considerations
+^^^^^^^^^^^^^^^^^^^^^
+
+When adding a new Pedalboard effect plugin, the following constraints should be considered:
+
+ - **Licensing**: is the code that implements the new effect compatible with the GPLv3 license used for Pedalboard? Can it be statically linked?
+ - **Vendorability**: will the code have to be added to Pedalboard's repository, or can it be included as a Git submodule?
+ - **Binary Size**: Pedalboard is distributed as a binary wheel. Will the new code required (or any required resources) increase the binary size by a considerable amount?
+ - **Platform Compatibility**: Does the new effect's code compile on macOS, Windows, and Linux?
+ - **Dependencies**: Does the new code require any runtime dependencies that cannot be included in the Pedalboard binary? Requiring users to install additional files or have additional software installed, for example, would complicate the "just `import pedalboard`" simplicity of the package.

_sources/internals.rst.txt

@@ -0,0 +1,6 @@
+License
+=======
+
+.. mdinclude:: ../../README.md
+   :start-line: 307
+   :end-line: 319

_sources/license.rst.txt

@@ -0,0 +1,44 @@
+The ``pedalboard.io`` API
+=========================
+
+This module provides classes and functions for reading and writing audio files or streams.
+
+.. note::
+   For audio effects, see the :py:mod:`pedalboard` module.
+
+:py:mod:`pedalboard.io` allows for reading and writing to audio files
+just like working with other types of files in Python. Audio encoding
+and decoding is handled automatically behind the scenes in C++, providing
+high quality, high performance, thread-safe access to audio files.
+
+The goal of :py:mod:`pedalboard.io` is to direct access to audio like
+a regular file in Python::
+
+   from pedalboard.io import AudioFile
+
+   with AudioFile("my_filename.mp3") as f:
+      print(f.duration) # => 30.0
+      print(f.samplerate) # => 44100
+      print(f.num_channels) # => 2
+      print(f.read(f.samplerate * 10))
+      # => returns a NumPy array of shape (2, 441_000):
+      #    [[ 0.  0.  0. ... -0. -0. -0.]
+      #     [ 0.  0.  0. ... -0. -0. -0.]]
+
+.. note::
+   The :class:`pedalboard.io.AudioFile` class should be all that's necessary for most use cases.
+
+   - Writing to a file can be accomplished by passing ``"w"`` as a second argument, just like with regular files in Python.
+   - Changing the sample rate of a file can be accomplished by calling :py:meth:`pedalboard.io.ReadableAudioFile.resampled_to`.
+
+   If you find yourself importing :class:`pedalboard.io.ReadableAudioFile`,
+   :class:`pedalboard.io.WriteableAudioFile`, or :class:`pedalboard.io.ResampledReadableAudioFile` directly,
+   you *probably don't need to do that* - :class:`pedalboard.io.AudioFile` has you covered.
+
+The following documentation lists all of the available I/O classes.
+
+
+.. automodule:: pedalboard.io
+   :members:
+   :imported-members:
+   :special-members: __enter__, __exit__

_sources/reference/pedalboard.io.rst.txt

@@ -0,0 +1,43 @@
+The ``pedalboard`` API
+======================
+
+This module provides classes and functions for adding effects to audio.
+Most classes in this module are subclasses of :class:`Plugin`, each of
+which allows applying effects to an audio buffer or stream.
+
+.. note::
+   For audio I/O functionality (i.e.: reading and writing audio files), see
+   the :py:mod:`pedalboard.io` module.
+
+The :py:mod:`pedalboard` module is named after
+`the concept of a guitar pedalboard <https://en.wikipedia.org/wiki/Guitar_pedalboard>`_,
+in which musicians will chain various effects pedals together to give them
+complete control over their sound. The :py:mod:`pedalboard` module implements
+this concept with its main :class:`Pedalboard` class::
+
+   from pedalboard import Pedalboard, Chorus, Distortion, Reverb
+
+   # Create an empty Pedalboard object:
+   my_pedalboard = Pedalboard()
+
+   # Treat this object like a Python list:
+   my_pedalboard.append(Chorus())
+   my_pedalboard.append(Distortion())
+   my_pedalboard.append(Reverb())
+
+   # Pass audio through this pedalboard:
+   output_audio = my_pedalboard(input_audio, input_audio_samplerate)
+
+
+:class:`Pedalboard` objects are lists of zero or more :class:`Plugin` objects,
+and :class:`Pedalboard` objects themselves are subclasses of :class:`Plugin` -
+which allows for nesting and composition.
+
+The following documentation lists all of the available types of :class:`Plugin`.
+
+
+.. automodule:: pedalboard
+   :members:
+   :imported-members:
+   :inherited-members:
+   :special-members: __call__