Microphone - for recording sound

The Microphone class provides an interface to audio recording devices connected to the computer. As of now, Psychtoolbox is required to use this feature and must be installed.

Overview

Microphone([device, sampleRateHz, channels, …])

Class for recording audio from a microphone or input stream.

Details

class psychopy.sound.Microphone(device=None, sampleRateHz=None, channels=2, streamBufferSecs=2.0, maxRecordingSize=24000, policyWhenFull='warn', audioLatencyMode=None, audioRunMode=0)[source]

Class for recording audio from a microphone or input stream.

Creating an instance of this class will open a stream using the specified device. Streams should remain open for the duration of your session. When a stream is opened, a buffer is allocated to store samples coming off it. Samples from the input stream will written to the buffer once start() is called.

Parameters
  • device (int or ~psychopy.sound.AudioDevice) – Audio capture device to use. You may specify the device either by index (int) or descriptor (AudioDevice).

  • sampleRateHz (int) – Sampling rate for audio recording in Hertz (Hz). By default, 48kHz (sampleRateHz=480000) is used which is adequate for most consumer grade microphones (headsets and built-in).

  • channels (int) – Number of channels to record samples to 1=Mono and 2=Stereo.

  • streamBufferSecs (float) – Stream buffer size to pre-allocate for the specified number of seconds. The default is 2.0 seconds which is usually sufficient.

  • maxRecordingSize (int) – Maximum recording size in kilobytes (Kb). Since audio recordings tend to consume a large amount of system memory, one might want to limit the size of the recording buffer to ensure that the application does not run out of memory. By default, the recording buffer is set to 24000 KB (or 24 MB). At a sample rate of 48kHz, this will result in 62.5 seconds of continuous audio being recorded before the buffer is full.

  • audioLatencyMode (int or None) – Audio latency mode to use, values range between 0-4. If None, the setting from preferences will be used. Using 3 (exclusive mode) is adequate for most applications and required if using WASAPI on Windows for other settings (such audio quality) to take effect. Symbolic constants psychopy.sound.audiodevice.AUDIO_PTB_LATENCY_CLASS_ can also be used.

  • audioRunMode (int) – Run mode for the recording device. Default is standby-mode (0) which allows the system to put the device to sleep. However when the device is needed, waking the device results in some latency. Using a run mode of 1 will keep the microphone running (or ‘hot’) with reduces latency when th recording is started. Cannot be set when after initialization at this time.

Examples

Capture 10 seconds of audio from the primary microphone:

import psychopy.core as core
import psychopy.sound.Microphone as Microphone

mic = Microphone(bufferSecs=10.0)  # open the microphone
mic.start()  # start recording
core.wait(10.0)  # wait 10 seconds
mic.stop()  # stop recording

audioClip = mic.getRecording()

print(audioClip.duration)  # should be ~10 seconds
audioClip.save('test.wav')  # save the recorded audio as a 'wav' file

The prescribed method for making long recordings is to poll the stream once per frame (or every n-th frame):

mic = Microphone(bufferSecs=2.0)
mic.start()  # start recording

# main trial drawing loop
mic.poll()
win.flip()  # calling the window flip function

mic.stop()  # stop recording
audioClip = mic.getRecording()
property audioLatencyMode

Audio latency mode in use (int). Cannot be set after initialization.

bank(tag=None, transcribe=False, **kwargs)[source]

Store current buffer as a clip within the microphone object.

This method is used internally by the Microphone component in Builder, don’t use it for other applications. Either stop() or pause() must be called before calling this method.

Parameters
  • tag (str or None) – Label for the clip.

  • transcribe (bool or str) – Set to the name of a transcription engine (e.g. “GOOGLE”) to transcribe using that engine, or set as False to not transcribe.

  • kwargs (dict) – Additional keyword arguments to pass to transcribe().

clear()[source]

Wipe all clips. Deletes previously banked audio clips.

close()[source]

Close the stream.

Should not be called until you are certain you’re done with it. Ideally, you should never close and reopen the same stream within a single session.

enforceWASAPI = True
flush()[source]

Get a copy of all banked clips, then clear the clips from storage.

static getDevices()[source]

Get a list of audio capture device (i.e. microphones) descriptors. On Windows, only WASAPI devices are used.

Returns

List of AudioDevice descriptors for suitable capture devices. If empty, no capture devices have been found.

Return type

list

getRecording()[source]

Get audio data from the last microphone recording.

Call this after stop to get the recording as an AudioClip object. Raises an error if a recording is in progress.

Returns

Recorded data between the last calls to start (or record) and stop.

Return type

AudioClip

property isRecBufferFull

True if there is an overflow condition with the recording buffer.

If this is True, then poll() is still collecting stream samples but is no longer writing them to anything, causing stream samples to be lost.

property isStarted

True if stream recording has been started (bool).

property latencyBias

Latency bias to add when starting the microphone (float).

property maxRecordingSize

Maximum recording size in kilobytes (int).

Since audio recordings tend to consume a large amount of system memory, one might want to limit the size of the recording buffer to ensure that the application does not run out. By default, the recording buffer is set to 64000 KB (or 64 MB). At a sample rate of 48kHz, this will result in about. Using stereo audio (nChannels == 2) requires twice the buffer over mono (nChannels == 2) for the same length clip.

Setting this value will allocate another recording buffer of appropriate size. Avoid doing this in any time sensitive parts of your application.

pause(blockUntilStopped=True, stopTime=None)[source]

Pause a recording (alias of .stop).

Call this method to end an audio recording if in progress. This will simply halt recording and not close the stream. Any remaining samples will be polled automatically and added to the recording buffer.

Parameters
  • blockUntilStopped (bool) – Halt script execution until the stream has fully stopped.

  • stopTime (float or None) – Scheduled stop time for the stream in system time. If None, the stream will stop as soon as possible.

Returns

Tuple containing startTime, endPositionSecs, xruns and estStopTime.

Return type

tuple

poll()[source]

Poll audio samples.

Calling this method adds audio samples collected from the stream buffer to the recording buffer that have been captured since the last poll call. Time between calls of this function should be less than bufferSecs. You do not need to call this if you call stop before the time specified by bufferSecs elapses since the start call.

Can only be called between called of start (or record) and stop (or pause).

Returns

Number of overruns in sampling.

Return type

int

property recBufferSecs

Capacity of the recording buffer in seconds (float).

record(when=None, waitForStart=0, stopTime=None)[source]

Start an audio recording (alias of .start()).

Calling this method will begin capturing samples from the microphone and writing them to the buffer.

Parameters
  • when (float, int or None) – When to start the stream. If the time specified is a floating point (absolute) system time, the device will attempt to begin recording at that time. If None or zero, the system will try to start recording as soon as possible.

  • waitForStart (bool) – Wait for sound onset if True.

  • stopTime (float, int or None) – Number of seconds to record. If None or -1, recording will continue forever until stop is called.

Returns

Absolute time the stream was started.

Return type

float

property recording

Reference to the current recording buffer (RecordingBuffer).

start(when=None, waitForStart=0, stopTime=None)[source]

Start an audio recording.

Calling this method will begin capturing samples from the microphone and writing them to the buffer.

Parameters
  • when (float, int or None) – When to start the stream. If the time specified is a floating point (absolute) system time, the device will attempt to begin recording at that time. If None or zero, the system will try to start recording as soon as possible.

  • waitForStart (bool) – Wait for sound onset if True.

  • stopTime (float, int or None) – Number of seconds to record. If None or -1, recording will continue forever until stop is called.

Returns

Absolute time the stream was started.

Return type

float

property status

Status flag for the microphone. Value can be one of psychopy.constants.STARTED or psychopy.constants.NOT_STARTED.

For detailed stream status information, use the streamStatus property.

stop(blockUntilStopped=True, stopTime=None)[source]

Stop recording audio.

Call this method to end an audio recording if in progress. This will simply halt recording and not close the stream. Any remaining samples will be polled automatically and added to the recording buffer.

Parameters
  • blockUntilStopped (bool) – Halt script execution until the stream has fully stopped.

  • stopTime (float or None) – Scheduled stop time for the stream in system time. If None, the stream will stop as soon as possible.

Returns

Tuple containing startTime, endPositionSecs, xruns and estStopTime.

Return type

tuple

property streamBufferSecs

Size of the internal audio storage buffer in seconds (float).

To ensure all data is captured, there must be less time elapsed between subsequent getAudioClip calls than bufferSecs.

property streamStatus

Status of the audio stream (AudioDeviceStatus or None).

See AudioDeviceStatus for a complete overview of available status fields. This property has a value of None if the stream is presently closed.

Examples

Get the capture start time of the stream:

# assumes mic.start() was called
captureStartTime = mic.status.captureStartTime

Check if microphone recording is active:

isActive = mic.status.active

Get the number of seconds recorded up to this point:

recordedSecs = mic.status.recordedSecs

Back to top