Module pyaudio :: Class Stream
[frames] | no frames]

Class Stream

source code

PortAudio Stream Wrapper. Use PyAudio.open to make a new Stream.
Instance Methods
    Opening and Closing
 
__init__(self, 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.
source code
 
close(self)
Close the stream
source code
    Stream Info
float
get_input_latency(self)
Return the input latency.
source code
float
get_output_latency(self)
Return the input latency.
source code
float
get_time(self)
Return stream time.
source code
float
get_cpu_load(self)
Return the CPU load.
source code
    Stream Management
 
start_stream(self)
Start the stream.
source code
 
stop_stream(self)
Stop the stream. Once the stream is stopped, one may not call write or read. However, one may call start_stream to resume the stream.
source code
bool
is_active(self)
Returns whether the stream is active.
source code
bool
is_stopped(self)
Returns whether the stream is stopped.
source code
    Input Output
None
write(self, frames, num_frames=None, exception_on_underflow=False)
Write samples to the stream. Do not call when using non-blocking mode.
source code
str
read(self, num_frames)
Read samples from the stream. Do not call when using non-blocking mode.
source code
int
get_read_available(self)
Return the number of frames that can be read without waiting.
source code
int
get_write_available(self)
Return the number of frames that can be written without waiting.
source code
Method Details

__init__(self, 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)
(Constructor)

source code 
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 PaSampleFormat.
  • 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 (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) # PaCallbackStatus

    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.

    The callback must return a tuple:

    (out_data, flag)

    out_data is a string 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.

    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.

get_cpu_load(self)

source code 

Return the CPU load.

(Note: this is always 0.0 for the blocking API.)

Returns: float

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

source code 
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.
Returns: None
Raises:
  • IOError - if the stream is not an output stream or if the write operation was unsuccessful.

read(self, num_frames)

source code 
Read samples from the stream. Do not call when using non-blocking mode.
Parameters:
  • num_frames - The number of frames to read.
Returns: str
Raises:
  • IOError - if stream is not an input stream or if the read operation was unsuccessful.