:mod:`audiobusio`
=================

.. py:module:: audiobusio

.. autoapi-nested-parse::

   Support for audio input and output over digital buses

   The `audiobusio` module contains classes to provide access to audio IO
   over digital buses. These protocols are used to communicate audio to other
   chips in the same circuit. It doesn't include audio interconnect protocols
   such as S/PDIF.

   All libraries change hardware state and should be deinitialized when they
   are no longer needed. To do so, either call :py:meth:`!deinit` or use a
   context manager.





.. py:class:: I2SOut(bit_clock: microcontroller.Pin, word_select: microcontroller.Pin, data: microcontroller.Pin, *, left_justified: bool)

   Output an I2S audio signal

   .. attribute:: playing
      :annotation: :Any

      True when the audio sample is being output. (read-only)


   .. attribute:: paused
      :annotation: :Any

      True when playback is paused. (read-only)


   .. method:: deinit(self)


      Deinitialises the I2SOut and releases any hardware resources for reuse.


   .. method:: __enter__(self)


      No-op used by Context Managers.


   .. method:: __exit__(self)


      Automatically deinitializes the hardware when exiting a context. See
      :ref:`lifetime-and-contextmanagers` for more info.


   .. method:: play(self, sample: Any, *, loop: Any = False)


      Plays the sample once when loop=False and continuously when loop=True.
      Does not block. Use `playing` to block.

      Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`.

      The sample itself should consist of 8 bit or 16 bit samples.


   .. method:: stop(self)


      Stops playback.


   .. method:: pause(self)


      Stops playback temporarily while remembering the position. Use `resume` to resume playback.


   .. method:: resume(self)


      Resumes sample playback after :py:func:`pause`.



.. py:class:: PDMIn(clock_pin: microcontroller.Pin, data_pin: microcontroller.Pin, *, sample_rate: int = 16000, bit_depth: int = 8, mono: bool = True, oversample: int = 64, startup_delay: float = 0.11)

   Record an input PDM audio stream

   .. attribute:: sample_rate
      :annotation: :Any

      The actual sample_rate of the recording. This may not match the constructed
      sample rate due to internal clock limitations.


   .. method:: deinit(self)


      Deinitialises the PDMIn and releases any hardware resources for reuse.


   .. method:: __enter__(self)


      No-op used by Context Managers.


   .. method:: __exit__(self)


      Automatically deinitializes the hardware when exiting a context.


   .. method:: record(self, destination: Any, destination_length: Any)


      Records destination_length bytes of samples to destination. This is
      blocking.

      An IOError may be raised when the destination is too slow to record the
      audio at the given rate. For internal flash, writing all 1s to the file
      before recording is recommended to speed up writes.

      :return: The number of samples recorded. If this is less than ``destination_length``,
        some samples were missed due to processing time.