# PyAudio Documentation

Contents

- PyAudio Documentation
  - Introduction
    - Example: Blocking Mode Audio I/O
    - Example: Callback Mode Audio I/O
    - Overview
    - Details
  - Class PyAudio
  - Class Stream
  - Platform Specific
- Indices and tables

## 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. PyAudio is inspired by:

- pyPortAudio/fastaudio: Python bindings for PortAudio v18 API.
- tkSnack: cross-platform sound toolkit for Tcl/Tk and Python.

### Example: Blocking Mode Audio I/O

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

    import pyaudio
    import wave
    import sys

    CHUNK = 1024

    if len(sys.argv) < 2:
        print("Plays a wave file.\n\nUsage: %s filename.wav" % sys.argv[0])
        sys.exit(-1)

    wf = wave.open(sys.argv[1], 'rb')

    # instantiate PyAudio (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)

    # read data
    data = wf.readframes(CHUNK)

    # play stream (3)
    while data != '':
        stream.write(data)
        data = wf.readframes(CHUNK)

    # stop stream (4)
    stream.stop_stream()
    stream.close()

    # close PyAudio (5)
    p.terminate()

To use PyAudio, first instantiate PyAudio using `pyaudio.PyAudio()` (1), which sets up the portaudio system.

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.Stream` to play or record audio.

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

Note that in “blocking mode”, each `pyaudio.Stream.write()` or `pyaudio.Stream.read()` blocks until all the given/requested frames have been played/recorded. Alternatively, to generate audio data on the fly or immediately process recorded audio data, use the “callback mode” outlined below.

Use `pyaudio.Stream.stop_stream()` to pause playing/recording, and `pyaudio.Stream.close()` to terminate the stream. (4)

Finally, terminate the portaudio session using `pyaudio.PyAudio.terminate()` (5)

### Example: Callback Mode Audio I/O

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

    import pyaudio
    import wave
    import time
    import sys

    if len(sys.argv) < 2:
        print("Plays a wave file.\n\nUsage: %s filename.wav" % sys.argv[0])
        sys.exit(-1)

    wf = wave.open(sys.argv[1], 'rb')

    # instantiate PyAudio (1)
    p = pyaudio.PyAudio()

    # define callback (2)
    def callback(in_data, frame_count, time_info, status):
        data = wf.readframes(frame_count)
        return (data, pyaudio.paContinue)

    # 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)

    # start the stream (4)
    stream.start_stream()

    # wait for stream to finish (5)
    while stream.is_active():
        time.sleep(0.1)

    # stop stream (6)
    stream.stop_stream()
    stream.close()
    wf.close()

    # close PyAudio (7)
    p.terminate()

In callback mode, PyAudio will call a specified callback function (2) whenever it needs new audio data (to play) and/or when there is new (recorded) audio data available. Note that PyAudio calls the callback function in a separate thread. The function has the following signature `callback(<input_data>, <frame_count>, <time_info>, <status_flag>)` and must return a tuple containing `frame_count` frames of audio data and a flag signifying whether there are more frames to play/record.

Start processing the audio stream using `pyaudio.Stream.start_stream()` (4), which will call the callback function repeatedly until that function returns `pyaudio.paComplete`.

To keep the stream active, the main thread must not terminate, e.g., by sleeping (5).

### Overview

Classes
  `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: | string

`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

  Use this class to open and close streams.

  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.

  `close`(stream)

    Close a stream. Typically use `Stream.close()` instead.

    Parameters: | stream – An instance of the `Stream` object.
    Raises: | ValueError – if stream does not exist.

  `get_default_host_api_info`()

    Return 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`()

    Return 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`()

    Return 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`()

    Return the number of PortAudio Host APIs.

    Return type: | integer

  `get_device_info_by_host_api_device_index`(host_api_index, host_api_device_index)

    Return 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)

    Return 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`()

    Return the number of available PortAudio Host APIs.

    Return type: | integer

  `get_host_api_info_by_index`(host_api_index)

    Return 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)

    Return 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)

    Check to see if specified device configuration is supported. Returns True if the configuration is supported; throws a ValueError exception 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)

    Open a new stream. See constructor for `Stream.__init__()` for parameter details.

    Returns: | A new `Stream`

  `terminate`()

    Terminate PortAudio.

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

## Class Stream

class `pyaudio.``Stream`(PA_manager, rate, channels, format, input=False, output=False, input_device_index=None, output_device_index=None, frames_per_buffer=1024, 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 make a new `Stream`.

  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=1024, start=True, input_host_api_specific_stream_info=None, output_host_api_specific_stream_info=None, stream_callback=None)

    Initialize a stream; this should be called by `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., `Stream.read()` and `Stream.write()`). To use non-blocking operation, specify a callback that conforms to the following signature:

          callback(in_data,      # recorded 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 `Stream.read()` or `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.

  `close`()

    Close the stream

  `get_cpu_load`()

    Return the CPU load. This is always 0.0 for the blocking API.

    Return type: | float

  `get_input_latency`()

    Return the input latency.

    Return type: | float

  `get_output_latency`()

    Return the input latency.

    Return type: | float

  `get_read_available`()

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

    Return type: | integer

  `get_time`()

    Return 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)

    Read samples from the stream. Do not call when using non-blocking mode.

    Parameters: | num_frames – The number of frames to read.
    Raises: | IOError – if stream is not an input stream or if the read operation was unsuccessful.
    Return type: | string

  `start_stream`()

    Start the stream.

  `stop_stream`()

    Stop the stream. Once the stream is stopped, one may not call write or read. Call `start_stream()` to resume the stream.

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

    Write samples to the stream. 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 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