The Recorder
class
- class audiomath.Recorder(seconds, device=None, stream=None, bufferLengthMsec=None, minLatencyMsec=None, fs=None, start=True, loop=False, verbose=None, filename=None, **kwargs)
Bases:
GenericRecorder
A
Recorder
provides a persistent connection to the chosen recording hardware, allowing sound to be recorded into aSound
instance.You may find it more useful to use the global function
Record
, which synchronously records and returns aSound
instance, than to create or interact directly withRecorder
instances. However,Recorder
instances are the way to go if you want to record asynchronously, in the background.- Parameters:
seconds (float, Sound) – number of seconds to pre-allocate for recording, or an already-pre-allocated
Sound
instance into which to recorddevice (int, str, dict, Stream) – specification of the device/stream to use for recording (as an index, name, full device record from
FindDevice()
, or already-openStream
instance)stream (int, str, dict, Stream) – synonymous with
device
, for compatibilityfs (float, None) – Optionally specify the sampling frequency, in Hz, when creating your first
Recorder
or firstStream
(after that,Recorder
instances may share an openStream
instance so it is possible that only the first call will make any difference).start (bool) – whether to start recording immediately
loop (bool) – whether to record indefinitely, treating
self.sound
as a circular buffer, or simply stop when the capacity ofself.sound
is reachedverbose (bool, None) – verbosity for debugging. If
None
, inherit from the setting specified bySetDefaultVerbosity()
, if any**kwargs – passed through to
Set()
to initialize properties of theRecorder
instance.
- Cut(position=None)
Stop recording, and return the portion of
self.sound
that has been recorded so far, up to the currenthead
position (or the explicitly specifiedposition
in seconds), as a newSound
instance.
- classmethod MakeRecording(space=60, prompt=None, verbose=None, cut=True, nChannels=None, filename=None, **kwargs)
Record and return a
Sound
synchronously. Slightly easier than creating your ownRecorder
instance and working with that (which is what you would have to do if you want to record asynchronously).- Parameters:
space (Sound, float) – specifies either a pre-existing
Sound
instance into which to record, or a number of seconds. In the latter case aSound
instance is created, pre- allocated with the specified amount of space in seconds.prompt (None, bool, str, function) – if this is left as
None
, a default string is composed. Ifprompt
is a string, it is printed to the console and theRecorder
waits until it has finished (or until ctrl-C is pressed). Alternatively, supply a callable whose non-None
return value signals that the recording should end.verbose (bool) – Passed through to the constructor of the
Recorder
object that is being used.cut (bool) – If true, return a
Cut()
version of theSound
when recording stops—i.e. ensure that the duration of theSound
does not exceed the duration of the recording. If false, the entire pre-allocatedspace
is returned, with the recording at the beginning.nChannels (int) – Optionally specify the number of channels to record (some APIs have crazy defaults, like ALSA’s 32 channels - if you’re not using one of those APIs, you probably don’t need this).
filename (str) – Optionally, use the
ffmpeg
class to stream the recorded content to the specified file. This requires theffmpeg
binary to be (separately) installed—see theffmpeg
class documentation.**kwargs – Additional keyword arguments are passed through to the constructor of the
Recorder
object (for example, to specify thedevice
that should be used).
Examples:
import audiomath as am s = am.Record() # this records for up to 60 seconds (less if ctrl-C # is pressed) and returns a `Sound` instance containing # the recorded data. s2 = am.Record(10, loop=True, filename='blah.mp3') # this records indefinitely into a 10-second circular # buffer, streaming the recorded data all the while into # the file `blah.mp3`, and when you press ctrl-C it # stops, cleans up, and returns the last 10 seconds as # a `Sound` instance.
- Pause(position=None, **kwargs)
Stop recording. If
position
is specified, move the recordinghead
to that position, expressed in seconds from the beginning.
- ReadSamples(startPositionInSamples, nSamples)
Read the specified number of samples and return them as a
numpy
array. If necessary, wait until the requisite number of samples has been recorded. Ifself.loop==False
, then this method may return fewer samples than you ask for if the recording reaches, or has already reached, the end of the space allocated inself.sound
. Otherwise, the wraparound calculations will be handled automatically and the return value will have the requested number of samples in chronological order.
- Record(position=None, wait=False, **kwargs)
Start recording. If
position
is specified, move the recordinghead
to that position, expressed in seconds from the beginning, before starting. Ifwait
is true,Wait()
until the end, or until the user presses ctrl+C.
- Seek(position, relative=False)
Move the recording
head
to the specifiedposition
in seconds. Negative values count back from the end of the available recording space inself.sound
. Ifrelative
is true,position
is interpreted as an offset relative to the current head position. The following are equivalent:r.Seek( 5.0, relative=False ) # more efficient r.head = 5.0
And the following are also equivalent:
r.Seek( -2.0, relative=True ) # more efficient r.head -= 2.0
- Set(**kwargs)
Set the values of multiple attributes or properties in one call. An error will be raised if you try to set the value of a non-existent attribute.
- Returns:
self
Example:
p.Set( head=0, recording=True )
- Start(position=None, wait=False, **kwargs)
Start recording. If
position
is specified, move the recordinghead
to that position, expressed in seconds from the beginning, before starting. Ifwait
is true,Wait()
until the end, or until the user presses ctrl+C.
- Stop(position=None, **kwargs)
Stop recording. If
position
is specified, move the recordinghead
to that position, expressed in seconds from the beginning.
- Wait()
Sleep until
self.recording
is no longer true. This will occur when the allocated recording time is exhausted, or if the user presses ctrl+C in the meantime.
- WaitFor(condition, finalRecordingStatus=None)
Sleep until
condition
is fulfilled. Thecondition
argument may be:- a
Recorder
instance: in which case the method waits until the recorder is no longer recording;
- a
Player
instance: in which case the method waits until the player is no longer playing;
- a string:
in which case the method will print the string as a prompt and wait for the user to enter press ctrl-C on the console;
- any callable:
in which case the method will repeatedly call
condition()
between 1-ms sleeps until it returns anything other thanNone
.
If
finalRecordingStatus
is notNone
, thenself.recording
is set to its value when the wait is over. So for example, you can prompt a user to end an ongoing recording as follows:r.WaitFor('Press ctrl-C to stop recording: ', finalRecordingStatus=False)
- a
- property head
Current recording position, in seconds relative to the beginning.
- property loop
A boolean property. If this is
True
, treatself.sound
as a circular buffer and record into it indefinitely (use theCut() method to extract the recorded data in the correct order). If this is `False
, the recorder will simply stop recording when the capacity ofself.sound
is reached.