:mod:`audiomixer`
=================

.. py:module:: audiomixer

.. autoapi-nested-parse::

   Support for audio mixing



.. raw:: html

    <p>
    <details>
    <summary>Available on these boards</summary>
    <ul>
    <li> AITHinker ESP32-C3S_Kit
    <li> ARAMCON Badge 2019
    <li> ARAMCON2 Badge
    <li> ATMegaZero ESP32-S2
    <li> Adafruit CLUE nRF52840 Express
    <li> Adafruit Circuit Playground Bluefruit
    <li> Adafruit EdgeBadge
    <li> Adafruit Feather Bluefruit Sense
    <li> Adafruit Feather ESP32-S2 TFT
    <li> Adafruit Feather ESP32S2
    <li> Adafruit Feather M4 CAN
    <li> Adafruit Feather M4 Express
    <li> Adafruit Feather RP2040
    <li> Adafruit Feather nRF52840 Express
    <li> Adafruit FunHouse
    <li> Adafruit Grand Central M4 Express
    <li> Adafruit Hallowing M4 Express
    <li> Adafruit ItsyBitsy M4 Express
    <li> Adafruit ItsyBitsy RP2040
    <li> Adafruit ItsyBitsy nRF52840 Express
    <li> Adafruit KB2040
    <li> Adafruit LED Glasses Driver nRF52840
    <li> Adafruit Macropad RP2040
    <li> Adafruit MagTag
    <li> Adafruit Matrix Portal M4
    <li> Adafruit Metro ESP32S2
    <li> Adafruit Metro M4 Airlift Lite
    <li> Adafruit Metro M4 Express
    <li> Adafruit Metro nRF52840 Express
    <li> Adafruit Monster M4SK
    <li> Adafruit PyGamer
    <li> Adafruit PyPortal
    <li> Adafruit PyPortal Pynt
    <li> Adafruit PyPortal Titano
    <li> Adafruit Pybadge
    <li> Adafruit QT Py ESP32S2
    <li> Adafruit QT Py RP2040
    <li> Adafruit QT2040 Trinkey
    <li> Adafruit Trellis M4 Express
    <li> AloriumTech Evo M51
    <li> Arduino Nano 33 BLE
    <li> Arduino Nano RP2040 Connect
    <li> Artisense Reference Design RD00
    <li> AtelierDuMaker nRF52840 Breakout
    <li> BDMICRO VINA-D51
    <li> BLE-SS dev board Multi Sensor
    <li> BastBLE
    <li> BastWiFi
    <li> BlueMicro840
    <li> CP32-M4
    <li> Capable Robot Programmable USB Hub
    <li> Challenger NB RP2040 WiFi
    <li> Challenger RP2040 LTE
    <li> Challenger RP2040 WiFi
    <li> CircuitBrains Deluxe
    <li> CrumpS2
    <li> Cytron Maker Nano RP2040
    <li> Cytron Maker Pi RP2040
    <li> DynOSSAT-EDU-OBC
    <li> ESP 12k NodeMCU
    <li> Electronut Labs Blip
    <li> Electronut Labs Papyr
    <li> EncoderPad RP2040
    <li> Feather ESP32S2 without PSRAM
    <li> FeatherS2
    <li> FeatherS2 Neo
    <li> FeatherS2 PreRelease
    <li> Franzininho WIFI w/Wroom
    <li> Franzininho WIFI w/Wrover
    <li> Gravitech Cucumber M
    <li> Gravitech Cucumber MS
    <li> Gravitech Cucumber R
    <li> Gravitech Cucumber RS
    <li> HMI-DevKit-1.1
    <li> HiiBot BlueFi
    <li> IkigaiSense Vita nRF52840
    <li> Kaluga 1
    <li> LILYGO TTGO T8 ESP32-S2 w/Display
    <li> MDBT50Q-DB-40
    <li> MDBT50Q-RX Dongle
    <li> MORPHEANS MorphESP-240
    <li> MakerDiary nRF52840 MDK
    <li> MakerDiary nRF52840 MDK USB Dongle
    <li> Makerdiary M60 Keyboard
    <li> Makerdiary Pitaya Go
    <li> Makerdiary nRF52840 M.2 Developer Kit
    <li> Melopero Shake RP2040
    <li> MicroDev microC3
    <li> MicroDev microS2
    <li> Mini SAM M4
    <li> Oak Dev Tech BREAD2040
    <li> Oak Dev Tech PixelWing ESP32S2
    <li> Open Hardware Summit 2020 Badge
    <li> PCA10056 nRF52840-DK
    <li> PCA10059 nRF52840 Dongle
    <li> PCA10100 nRF52833 DK
    <li> Particle Argon
    <li> Particle Boron
    <li> Particle Xenon
    <li> PewPew M4
    <li> Pimoroni Interstate 75
    <li> Pimoroni Keybow 2040
    <li> Pimoroni PGA2040
    <li> Pimoroni Pico LiPo (16MB)
    <li> Pimoroni Pico LiPo (4MB)
    <li> Pimoroni PicoSystem
    <li> Pimoroni Plasma 2040
    <li> Pimoroni Tiny 2040
    <li> PyCubedv04
    <li> PyCubedv04-MRAM
    <li> PyCubedv05
    <li> PyCubedv05-MRAM
    <li> PyKey60
    <li> RP2040 Stamp
    <li> Raspberry Pi Pico
    <li> Robo HAT MM1 M4
    <li> S2Mini
    <li> S2Pico
    <li> SAM E54 Xplained Pro
    <li> SAM32v26
    <li> Saola 1 w/Wroom
    <li> Saola 1 w/Wrover
    <li> Seeeduino Wio Terminal
    <li> Silicognition LLC M4-Shim
    <li> SparkFun MicroMod RP2040 Processor
    <li> SparkFun MicroMod SAMD51 Processor
    <li> SparkFun MicroMod nRF52840 Processor
    <li> SparkFun Pro Micro RP2040
    <li> SparkFun Pro nRF52840 Mini
    <li> SparkFun Thing Plus - RP2040
    <li> SparkFun Thing Plus - SAMD51
    <li> TG-Boards' Datalore IP M4
    <li> TG-Watch
    <li> Targett Module Clip w/Wroom
    <li> Targett Module Clip w/Wrover
    <li> Teknikio Bluebird
    <li> The Open Book Feather
    <li> Thingz - Galaxia
    <li> TinkeringTech ScoutMakes Azul
    <li> TinyS2
    <li> UARTLogger II
    <li> WarmBit BluePixel nRF52840
    <li> micro:bit v2
    <li> nanoESP32-S2  w/Wrover
    <li> nanoESP32-S2 w/Wroom
    <li> nice!nano
    </ul>
    </details>
    </p>




.. py:class:: Mixer(voice_count: int = 2, buffer_size: int = 1024, channel_count: int = 2, bits_per_sample: int = 16, samples_signed: bool = True, sample_rate: int = 8000)

   Mixes one or more audio samples together into one sample.

   Create a Mixer object that can mix multiple channels with the same sample rate.
   Samples are accessed and controlled with the mixer's `audiomixer.MixerVoice` objects.

   :param int voice_count: The maximum number of voices to mix
   :param int buffer_size: The total size in bytes of the buffers to mix into
   :param int channel_count: The number of channels the source samples contain. 1 = mono; 2 = stereo.
   :param int bits_per_sample: The bits per sample of the samples being played
   :param bool samples_signed: Samples are signed (True) or unsigned (False)
   :param int sample_rate: The sample rate to be used for all samples

   Playing a wave file from flash::

     import board
     import audioio
     import audiocore
     import audiomixer
     import digitalio

     a = audioio.AudioOut(board.A0)
     music = audiocore.WaveFile(open("cplay-5.1-16bit-16khz.wav", "rb"))
     drum = audiocore.WaveFile(open("drum.wav", "rb"))
     mixer = audiomixer.Mixer(voice_count=2, sample_rate=16000, channel_count=1,
                              bits_per_sample=16, samples_signed=True)

     print("playing")
     # Have AudioOut play our Mixer source
     a.play(mixer)
     # Play the first sample voice
     mixer.voice[0].play(music)
     while mixer.playing:
       # Play the second sample voice
       mixer.voice[1].play(drum)
       time.sleep(1)
     print("stopped")

   .. py:attribute:: playing
      :annotation: :bool

      True when any voice is being output. (read-only)


   .. py:attribute:: sample_rate
      :annotation: :int

      32 bit value that dictates how quickly samples are played in Hertz (cycles per second).


   .. py:attribute:: voice
      :annotation: :Tuple[MixerVoice, Ellipsis]

      A tuple of the mixer's `audiomixer.MixerVoice` object(s).

      .. code-block:: python

         >>> mixer.voice
         (<MixerVoice>,)


   .. py:method:: deinit() -> None

      Deinitialises the Mixer and releases any hardware resources for reuse.


   .. py:method:: __enter__() -> Mixer

      No-op used by Context Managers.


   .. py:method:: __exit__() -> None

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


   .. py:method:: play(sample: _typing.AudioSample, *, voice: int = 0, loop: bool = False) -> None

      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`, `audiomixer.Mixer` or `audiomp3.MP3Decoder`.

      The sample must match the Mixer's encoding settings given in the constructor.


   .. py:method:: stop_voice(voice: int = 0) -> None

      Stops playback of the sample on the given voice.



.. py:class:: MixerVoice

   Voice objects used with Mixer

   Used to access and control samples with `audiomixer.Mixer`.

   MixerVoice instance object(s) created by `audiomixer.Mixer`.

   .. py:attribute:: level
      :annotation: :float

      The volume level of a voice, as a floating point number between 0 and 1.


   .. py:attribute:: playing
      :annotation: :bool

      True when this voice is being output. (read-only)


   .. py:method:: play(sample: _typing.AudioSample, *, loop: bool = False) -> None

      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`, `audiomixer.Mixer` or `audiomp3.MP3Decoder`.

      The sample must match the `audiomixer.Mixer`'s encoding settings given in the constructor.


   .. py:method:: stop() -> None

      Stops playback of the sample on this voice.