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.
|
Class for recording audio from a microphone or input stream. |
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 writen to the buffer once
start() is called.
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()
Audio latency mode in use (int). Cannot be set after initialization.
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.
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().
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.
Get a list of audio capture device (i.e. microphones) descriptors. On Windows, only WASAPI devices are used.
List of AudioDevice descriptors for suitable capture devices. If empty, no capture devices have been found.
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.
Recorded data between the last calls to start (or record) and stop.
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.
True if stream recording has been started (bool). Alias of
isStarted.
True if stream recording has been started (bool).
Latency bias to add when starting the microphone (float).
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 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.
Tuple containing startTime, endPositionSecs, xruns and estStopTime. Returns None if stop() or pause() was called previously before start().
tuple or None
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).
Number of overruns in sampling.
Capacity of the recording buffer in seconds (float).
Start an audio recording (alias of .start()).
Calling this method will begin capturing samples from the microphone and writing them to the buffer.
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.
Absolute time the stream was started.
Reference to the current recording buffer (RecordingBuffer).
Start an audio recording.
Calling this method will begin capturing samples from the microphone and writing them to the buffer.
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.
Absolute time the stream was started.
Status flag for the microphone. Value can be one of
psychopy.constants.STARTED or psychopy.constants.NOT_STARTED.
This is attribute is used by Builder and does not correspond to the actual state of the microphone. Use streamStatus and isStarted instead.
For detailed stream status information, use the
streamStatus property.
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.
Tuple containing startTime, endPositionSecs, xruns and estStopTime. Returns None if stop or pause was called previously before start.
tuple or None
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.
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