# PyAudio Documentation

## Introduction

PyAudio provides Python bindings for PortAudio, the cross-platform audio I/O library. With PyAudio, you can easily use Python to play and record audio on a variety of platforms.

### Example: Blocking Mode Audio I/O

    """PyAudio Example: Play a wave file."""

    import wave
    import sys

    import pyaudio

    CHUNK = 1024

    if len(sys.argv) < 2:
        print(f'Plays a wave file. Usage: {sys.argv[0]} filename.wav')
        sys.exit(-1)

    with wave.open(sys.argv[1], 'rb') as wf:
        # Instantiate PyAudio and initialize PortAudio system resources (1)
        p = pyaudio.PyAudio()

        # Open stream (2)
        stream = p.open(format=p.get_format_from_width(wf.getsampwidth()),
                        channels=wf.getnchannels(),
                        rate=wf.getframerate(),
                        output=True)

        # Play samples from the wave file (3)
        while len(data := wf.readframes(CHUNK)):  # Requires Python 3.8+ for :=
            stream.write(data)

        # Close stream (4)
        stream.close()

        # Release PortAudio system resources (5)
        p.terminate()

To use PyAudio, first instantiate PyAudio using `pyaudio.PyAudio()` (1), which acquires system resources for PortAudio.

To record or play audio, open a stream on the desired device with the desired audio parameters using `pyaudio.PyAudio.open()` (2). This sets up a `pyaudio.PyAudio.Stream` to play or record audio.

Play audio by writing audio data to the stream using `pyaudio.PyAudio.Stream.write()`, or read audio data from the stream using `pyaudio.PyAudio.Stream.read()`. (3)

Note that in “blocking mode”, each `pyaudio.PyAudio.Stream.write()` or `pyaudio.PyAudio.Stream.read()` blocks until all frames have been played/recorded. An alternative approach is “callback mode”, described below, in which PyAudio invokes a user-defined function to process recorded audio or generate output audio.

Use `pyaudio.PyAudio.Stream.close()` to close the stream. (4)

Finally, terminate the PortAudio session and release system resources using `pyaudio.PyAudio.terminate()`. (5)

### Example: Callback Mode Audio I/O

    """PyAudio Example: Play a wave file (callback version)."""

    import wave
    import time
    import sys

    import pyaudio

    if len(sys.argv) < 2:
        print(f'Plays a wave file. Usage: {sys.argv[0]} filename.wav')
        sys.exit(-1)

    with wave.open(sys.argv[1], 'rb') as wf:
        # Define callback for playback (1)
        def callback(in_data, frame_count, time_info, status):
            data = wf.readframes(frame_count)
            # If len(data) is less than requested frame_count, PyAudio automatically
            # assumes the stream is finished, and the stream stops.
            return (data, pyaudio.paContinue)

        # Instantiate PyAudio and initialize PortAudio system resources (2)
        p = pyaudio.PyAudio()

        # Open stream using callback (3)
        stream = p.open(format=p.get_format_from_width(wf.getsampwidth()),
                        channels=wf.getnchannels(),
                        rate=wf.getframerate(),
                        output=True,
                        stream_callback=callback)

        # Wait for stream to finish (4)
        while stream.is_active():
            time.sleep(0.1)

        # Close the stream (5)
        stream.close()

        # Release PortAudio system resources (6)
        p.terminate()

In callback mode, PyAudio will call a user-defined callback function (1) whenever it needs new audio data to play and/or when new recorded audio data becomes available. PyAudio calls the callback function in a separate thread. The callback function must have the following signature `callback(<input_data>, <frame_count>, <time_info>, <status_flag>)`. It must return a tuple containing `frame_count` frames of audio data to output (for output streams) and a flag signifying whether there are more expected frames to play or record. (For input-only streams, the audio data portion of the return value is ignored.)

The audio stream starts processing once the stream is opened (3), which will call the callback function repeatedly until that function returns `pyaudio.paComplete` or `pyaudio.paAbort`, or until either `pyaudio.PyAudio.Stream.stop` or `pyaudio.PyAudio.Stream.close` is called. Note that if the callback returns fewer frames than the `frame_count` argument (2), the stream automatically closes after those frames are played.

To keep the stream active, the main thread must remain alive, e.g., by sleeping (4). In the example above, once the entire wavefile is read, `wf.readframes(frame_count)` will eventually return fewer than the requested frames. The stream will stop, and the while loop (4) will end.

### Overview

Classes

  `PyAudio`, `PyAudio.Stream`

Stream Conversion Convenience Functions

  `get_sample_size()`, `get_format_from_width()`

PortAudio version

  `get_portaudio_version()`, `get_portaudio_version_text()`

Portaudio Sample Formats

  `paFloat32`, `paInt32`, `paInt24`, `paInt16`, `paInt8`, `paUInt8`, `paCustomFormat`

PortAudio Host APIs

  `paInDevelopment`, `paDirectSound`, `paMME`, `paASIO`, `paSoundManager`, `paCoreAudio`, `paOSS`, `paALSA`, `paAL`, `paBeOS`, `paWDMKS`, `paJACK`, `paWASAPI`, `paNoDevice`

PortAudio Error Codes

  `paNoError`, `paNotInitialized`, `paUnanticipatedHostError`, `paInvalidChannelCount`, `paInvalidSampleRate`, `paInvalidDevice`, `paInvalidFlag`, `paSampleFormatNotSupported`, `paBadIODeviceCombination`, `paInsufficientMemory`, `paBufferTooBig`, `paBufferTooSmall`, `paNullCallback`, `paBadStreamPtr`, `paTimedOut`, `paInternalError`, `paDeviceUnavailable`, `paIncompatibleHostApiSpecificStreamInfo`, `paStreamIsStopped`, `paStreamIsNotStopped`, `paInputOverflowed`, `paOutputUnderflowed`, `paHostApiNotFound`, `paInvalidHostApi`, `paCanNotReadFromACallbackStream`, `paCanNotWriteToACallbackStream`, `paCanNotReadFromAnOutputOnlyStream`, `paCanNotWriteToAnInputOnlyStream`, `paIncompatibleStreamHostApi`

PortAudio Callback Return Codes

  `paContinue`, `paComplete`, `paAbort`

PortAudio Callback Flags

  `paInputUnderflow`, `paInputOverflow`, `paOutputUnderflow`, `paOutputOverflow`, `paPrimingOutput`

### Details

pyaudio.get_format_from_width(width, unsigned=True)

  Returns a PortAudio format constant for the specified width.

  Parameters:

    - width – The desired sample width in bytes (1, 2, 3, or 4)

    - unsigned – For 1 byte width, specifies signed or unsigned format.

  Raises:

    ValueError – when invalid width

  Return type:

    A PortAudio Sample Format constant

pyaudio.get_portaudio_version()

  Returns portaudio version.

  Return type:

    int

pyaudio.get_portaudio_version_text()

  Returns PortAudio version as a text string.

  Return type:

    string

pyaudio.get_sample_size(format)

  Returns the size (in bytes) for the specified sample format.

  Parameters:

    format – A PortAudio Sample Format constant.

  Raises:

    ValueError – on invalid specified format.

  Return type:

    integer

pyaudio.paAL = 9

  Open Audio Library

pyaudio.paALSA = 8

  Advanced Linux Sound Architecture (Linux only)

pyaudio.paASIO = 3

  Steinberg Audio Stream Input/Output

pyaudio.paAbort = 2

  An error ocurred, stop playback/recording

pyaudio.paBeOS = 10

  BeOS Sound System

pyaudio.paComplete = 1

  This was the last block of audio data

pyaudio.paContinue = 0

  There is more audio data to come

pyaudio.paCoreAudio = 5

  CoreAudio (OSX only)

pyaudio.paCustomFormat = 65536

  a custom data format

pyaudio.paDirectSound = 1

  DirectSound (Windows only)

pyaudio.paFloat32 = 1

  32 bit float

pyaudio.paInDevelopment = 0

  Still in development

pyaudio.paInputOverflow = 2

  Buffer overflow in input

pyaudio.paInputUnderflow = 1

  Buffer underflow in input

pyaudio.paInt16 = 8

  16 bit int

pyaudio.paInt24 = 4

  24 bit int

pyaudio.paInt32 = 2

  32 bit int

pyaudio.paInt8 = 16

  8 bit int

pyaudio.paJACK = 12

  JACK Audio Connection Kit

pyaudio.paMME = 2

  Multimedia Extension (Windows only)

pyaudio.paNoDevice = -1

  Not actually an audio device

pyaudio.paOSS = 7

  Open Sound System (Linux only)

pyaudio.paOutputOverflow = 8

  Buffer overflow in output

pyaudio.paOutputUnderflow = 4

  Buffer underflow in output

pyaudio.paPrimingOutput = 16

  Just priming, not playing yet

pyaudio.paSoundManager = 4

  SoundManager (OSX only)

pyaudio.paUInt8 = 32

  8 bit unsigned int

pyaudio.paWASAPI = 13

  Windows Vista Audio stack architecture

pyaudio.paWDMKS = 11

  Windows Driver Model (Windows only)

## Class PyAudio

class pyaudio.PyAudio

  Python interface to PortAudio.

  Provides methods to:

    - initialize and terminate PortAudio

    - open and close streams

    - query and inspect the available PortAudio Host APIs

    - query and inspect the available PortAudio audio devices.

  Stream Management

    `open()`, `close()`

  Host API

    `get_host_api_count()`, `get_default_host_api_info()`, `get_host_api_info_by_type()`, `get_host_api_info_by_index()`, `get_device_info_by_host_api_device_index()`

  Device API

    `get_device_count()`, `is_format_supported()`, `get_default_input_device_info()`, `get_default_output_device_info()`, `get_device_info_by_index()`

  Stream Format Conversion

    `get_sample_size()`, `get_format_from_width()`

  Details

  __init__()

    Initialize PortAudio.

  __weakref__

    list of weak references to the object

  close(stream)

    Closes a stream. Use `PyAudio.Stream.close()` instead.

    Parameters:

      stream – An instance of the `PyAudio.Stream` object.

    Raises:

      ValueError – if stream does not exist.

  get_default_host_api_info()

    Returns a dictionary containing the default Host API parameters.

    The keys of the dictionary mirror the data fields of PortAudio’s `PaHostApiInfo` structure.

    Raises:

      IOError – if no default input device is available

    Return type:

      dict

  get_default_input_device_info()

    Returns the default input device parameters as a dictionary.

    The keys of the dictionary mirror the data fields of PortAudio’s `PaDeviceInfo` structure.

    Raises:

      IOError – No default input device available.

    Return type:

      dict

  get_default_output_device_info()

    Returns the default output device parameters as a dictionary.

    The keys of the dictionary mirror the data fields of PortAudio’s `PaDeviceInfo` structure.

    Raises:

      IOError – No default output device available.

    Return type:

      dict

  get_device_count()

    Returns the number of PortAudio Host APIs.

    Return type:

      integer

  get_device_info_by_host_api_device_index(host_api_index, host_api_device_index)

    Returns a dictionary containing the Device parameters for a given Host API’s n’th device. The keys of the dictionary mirror the data fields of PortAudio’s `PaDeviceInfo` structure.

    Parameters:

      - host_api_index – The Host API index number

      - host_api_device_index – The n’th device of the host API

    Raises:

      IOError – for invalid indices

    Return type:

      dict

  get_device_info_by_index(device_index)

    Returns the device parameters for device specified in device_index as a dictionary. The keys of the dictionary mirror the data fields of PortAudio’s `PaDeviceInfo` structure.

    Parameters:

      device_index – The device index

    Raises:

      IOError – Invalid device_index.

    Return type:

      dict

  get_format_from_width(width, unsigned=True)

    Returns a PortAudio format constant for the specified width.

    Parameters:

      - width – The desired sample width in bytes (1, 2, 3, or 4)

      - unsigned – For 1 byte width, specifies signed or unsigned format.

    Raises:

      ValueError – for invalid width

    Return type:

      A PortAudio Sample Format constant.

  get_host_api_count()

    Returns the number of available PortAudio Host APIs.

    Return type:

      integer

  get_host_api_info_by_index(host_api_index)

    Returns a dictionary containing the Host API parameters for the host API specified by the host_api_index. The keys of the dictionary mirror the data fields of PortAudio’s `PaHostApiInfo` structure.

    Parameters:

      host_api_index – The host api index

    Raises:

      IOError – for invalid host_api_index

    Return type:

      dict

  get_host_api_info_by_type(host_api_type)

    Returns a dictionary containing the Host API parameters for the host API specified by the host_api_type. The keys of the dictionary mirror the data fields of PortAudio’s `PaHostApiInfo` structure.

    Parameters:

      host_api_type – The desired PortAudio Host API

    Raises:

      IOError – for invalid host_api_type

    Return type:

      dict

  get_sample_size(format)

    Returns the size (in bytes) for the specified sample format (a PortAudio Sample Format constant).

    Parameters:

      format – A PortAudio Sample Format constant.

    Raises:

      ValueError – Invalid specified format.

    Return type:

      integer

  is_format_supported(rate, input_device=None, input_channels=None, input_format=None, output_device=None, output_channels=None, output_format=None)

    Checks if specified device configuration is supported.

    Returns True if the configuration is supported; raises ValueError otherwise.

    Parameters:

      - rate – Specifies the desired rate (in Hz)

      - input_device – The input device index. Specify `None` (default) for half-duplex output-only streams.

      - input_channels – The desired number of input channels. Ignored if input_device is not specified (or `None`).

      - input_format – PortAudio sample format constant defined in this module

      - output_device – The output device index. Specify `None` (default) for half-duplex input-only streams.

      - output_channels – The desired number of output channels. Ignored if input_device is not specified (or `None`).

      - output_format – PortAudio Sample Format constant.

    Return type:

      bool

    Raises:

      ValueError – tuple containing (error string, PortAudio Error Code).

  open(*args, **kwargs)

    Opens a new stream.

    See constructor for `PyAudio.Stream.__init__()` for parameter details.

    Returns:

      A new `PyAudio.Stream`

  terminate()

    Terminates PortAudio.

    Attention:

      Be sure to call this method for every instance of this object to release PortAudio resources.

## Class PyAudio.Stream

class pyaudio.PyAudio.Stream(PA_manager, rate, channels, format, input=False, output=False, input_device_index=None, output_device_index=None, frames_per_buffer=0, start=True, input_host_api_specific_stream_info=None, output_host_api_specific_stream_info=None, stream_callback=None)

  PortAudio Stream Wrapper. Use `PyAudio.open()` to instantiate.

  Opening and Closing

    `__init__()`, `close()`

  Stream Info

    `get_input_latency()`, `get_output_latency()`, `get_time()`, `get_cpu_load()`

  Stream Management

    `start_stream()`, `stop_stream()`, `is_active()`, `is_stopped()`

  Input Output

    `write()`, `read()`, `get_read_available()`, `get_write_available()`

  __init__(PA_manager, rate, channels, format, input=False, output=False, input_device_index=None, output_device_index=None, frames_per_buffer=0, start=True, input_host_api_specific_stream_info=None, output_host_api_specific_stream_info=None, stream_callback=None)

    Initialize an audio stream.

    Do not call directly. Use `PyAudio.open()`.

    A stream can either be input, output, or both.

    Parameters:

      - PA_manager – A reference to the managing `PyAudio` instance

      - rate – Sampling rate

      - channels – Number of channels

      - format – Sampling size and format. See PortAudio Sample Format.

      - input – Specifies whether this is an input stream. Defaults to `False`.

      - output – Specifies whether this is an output stream. Defaults to `False`.

      - input_device_index – Index of Input Device to use. Unspecified (or `None`) uses default device. Ignored if input is `False`.

      - output_device_index – Index of Output Device to use. Unspecified (or `None`) uses the default device. Ignored if output is `False`.

      - frames_per_buffer – Specifies the number of frames per buffer.

      - start – Start the stream running immediately. Defaults to `True`. In general, there is no reason to set this to `False`.

      - input_host_api_specific_stream_info –

        Specifies a host API specific stream information data structure for input.

      - output_host_api_specific_stream_info –

        Specifies a host API specific stream information data structure for output.

      - stream_callback –

        Specifies a callback function for non-blocking (callback) operation. Default is `None`, which indicates blocking operation (i.e., `PyAudio.Stream.read()` and `PyAudio.Stream.write()`). To use non-blocking operation, specify a callback that conforms to the following signature:

            callback(in_data,      # input data if input=True; else None
                     frame_count,  # number of frames
                     time_info,    # dictionary
                     status_flags) # PaCallbackFlags

        `time_info` is a dictionary with the following keys: `input_buffer_adc_time`, `current_time`, and `output_buffer_dac_time`; see the PortAudio documentation for their meanings. `status_flags` is one of PortAutio Callback Flag.

        The callback must return a tuple:

            (out_data, flag)

        `out_data` is a byte array whose length should be the (`frame_count * channels * bytes-per-channel`) if `output=True` or `None` if `output=False`. `flag` must be either `paContinue`, `paComplete` or `paAbort` (one of PortAudio Callback Return Code). When `output=True` and `out_data` does not contain at least `frame_count` frames, `paComplete` is assumed for `flag`.

        Note: `stream_callback` is called in a separate thread (from the main thread). Exceptions that occur in the `stream_callback` will:

        1. print a traceback on standard error to aid debugging,

        2. queue the exception to be thrown (at some point) in the main thread, and

        3. return paAbort to PortAudio to stop the stream.

        Note: Do not call `PyAudio.Stream.read()` or `PyAudio.Stream.write()` if using non-blocking operation.

        See: PortAudio’s callback signature for additional details: http://portaudio.com/docs/v19-doxydocs/portaudio_8h.html#a8a60fb2a5ec9cbade3f54a9c978e2710

    Raises:

      ValueError – Neither input nor output are set True.

  __weakref__

    list of weak references to the object

  close()

    Closes the stream.

  get_cpu_load()

    Return the CPU load. Always 0.0 when using the blocking API.

    Return type:

      float

  get_input_latency()

    Returns the input latency.

    Return type:

      float

  get_output_latency()

    Returns the output latency.

    Return type:

      float

  get_read_available()

    Return the number of frames that can be read without waiting.

    Return type:

      integer

  get_time()

    Returns stream time.

    Return type:

      float

  get_write_available()

    Return the number of frames that can be written without waiting.

    Return type:

      integer

  is_active()

    Returns whether the stream is active.

    Return type:

      bool

  is_stopped()

    Returns whether the stream is stopped.

    Return type:

      bool

  read(num_frames, exception_on_overflow=True)

    Read samples from the stream.

    Do not call when using non-blocking mode.

    Parameters:

      - num_frames – The number of frames to read.

      - exception_on_overflow – Specifies whether an IOError exception should be thrown (or silently ignored) on input buffer overflow. Defaults to True.

    Raises:

      IOError – if stream is not an input stream or if the read operation was unsuccessful.

    Return type:

      bytes

  start_stream()

    Starts the stream.

  stop_stream()

    Stops the stream.

  write(frames, num_frames=None, exception_on_underflow=False)

    Write samples to the stream for playback.

    Do not call when using non-blocking mode.

    Parameters:

      - frames – The frames of data.

      - num_frames – The number of frames to write. Defaults to None, in which this value will be automatically computed.

      - exception_on_underflow – Specifies whether an IOError exception should be thrown (or silently ignored) on buffer underflow. Defaults to False for improved performance, especially on slower platforms.

    Raises:

      IOError – if the stream is not an output stream or if the write operation was unsuccessful.

    Return type:

      None

## Platform Specific

# Indices and tables

- Index

- Search Page