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.
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 sysCHUNK = 1024if 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 len (data)> 0: 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 sysif 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. The function has the following signature callback (
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, eg, by sleeping (5).
Overview¶Classes PyAudio, StreamHost Specific Classes PaMacCoreStreamInfoStream Conversion Convenience Functions get_sample_size (), get_format_from_width () PortAudio version get_portaudio_version (), get_portaudio_version_text () Portaudio Sample Formats paFloat32, paudioInt24, APIUntInt32, paFloat16, HostIntInt32, APIPoundUctIntInt32, APIPa8TuTiTuTiTiPtIntInt32, paFloatIntInt32, PaFloatInt24Int32 API paMME, Paasio, paSoundManager, paCoreAudio, paOSS, paALSA, Paal, paBeOS, paWDMKS, paJACK, paWASAPI, paNoDevicePortAudio Error Codes paNoError, paNotInitialized, paUnanticipatedHostError, paInvalidChannelCount, paInvalidSampleRate, paInvalidDevice, paInvalidFlag, paSampleFormatNotSupported, paBadIODeviceCombination, paInsufficientMemory, paBufferTooBig, paBufferTooSmall, paNullCallback , paBadStreamPtr, paTimedOut, paInternalError, paDeviceUnavailable, paIncompatibleHostApiSpecificStreamInfo, paStreamIsStopped, paStreamIsNotStopped, paInputOverflowed, paOutputUnderflowed, paHostApi, InvalidFanostUnderflowed, paHostApi, InvalidFanostReadCound romACallbackStream, paCanNotWriteToACallbackStream, paCanNotReadFromAnOutputOnlyStream, paCanNotWriteToAnInputOnlyStream, paIncompatibleStreamHostApiPortAudio Callback Return Codes paContinue, paComplete, paAbortPortAudio Callback Flags paInputUnderflow, paInputOverflow, paOutputUnderflow, paOutputOverflow, paPrimingOutputDetails¶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.
pyaudio.get_portaudio_version_text () ¶
Returns PortAudio version as a text 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: integerpyaudio.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 occurred, 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: dictget_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: dictget_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: dictget_device_count () ¶
Return the number of PortAudio Host APIs.
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 indexRaises: IOError – Invalid device_index.Return type: dictget_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.
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 indexRaises: IOError – for invalid host_api_indexReturn type: dictget_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 APIRaises: IOError – for invalid host_api_typeReturn type: dictget_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: integeris_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.
terminate () ¶
Finish 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 Noneinfo_specific_sstreaminfo = input_host_api_specific_sstreaminfo = stream_host = 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.
See PaMacCoreStreamInfo.
output_host_api_specific_stream_info –
Specifies a host API specific stream information data structure for output.
See PaMacCoreStreamInfo.
stream_callback –
Specifies a callback function for non-blocking (callback) operation.Default is None, which indicates blocking operation (ie, 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 Noneframe_count, # number of framestime_info, # dictionarystatus_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 to 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:
print a traceback on standard error to aid debugging, queue the exception to be thrown (at some point) in the main thread, and 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.
get_input_latency () ¶
Return the input latency.
get_output_latency () ¶
Return the output latency.
get_read_available () ¶
Return the number of frames that can be read without waiting.
get_time () ¶
Return stream time.
get_write_available () ¶
Return the number of frames that can be written without waiting.
is_active () ¶
Returns whether the stream is active.
is_stopped () ¶
Returns whether the stream is stopped.
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:
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 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¶Class PaMacCoreStreamInfo¶class pyaudio.PaMacCoreStreamInfo (flags = None, channel_map = None) ¶
Mac OS X-only: PaMacCoreStreamInfo is a PortAudio Host API Specific Stream Info data structure for specifying Mac OS X-only settings. Instantiate this class (if desired) and pass the instance as the argument in PyAudio.open () to parameters input_host_api_specific_stream_info or output_host_api_specific_stream_info. (See Stream .__ init __ ().)
Core Flags Mac PortAudio paMacCoreChangeDeviceParameters, paMacCoreFailIfConversionRequired, paMacCoreConversionQualityMin, paMacCoreConversionQualityMedium, paMacCoreConversionQualityLow, paMacCoreConversionQualityHigh, paMacCoreConversionQualityMax, paMacCorePlayNice, paMacCorePro, paMacCoreMinimizeCPUButPlayNice, paMacCoreMinimizeCPU get_flags Settings (), get_channel_map () __ init __ (flags = None, channel_map = None) ¶
Initialize with flags and channel_map. See PortAudio documentation for more details on these parameters; they are passed almost verbatim to the PortAudio library.
get_channel_map () ¶
Return the channel map set at instantiation.
Return type: tuple or Noneget_flags () ¶
Return the flags set at instantiation.