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 a Sound instance.

You may find it more useful to use the global function Record, which synchronously records and returns a Sound instance, than to create or interact directly with Recorder 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 record
device (int, str, dict, Stream) – specification of the device/stream to use for recording (as an index, name, full device record from FindDevice(), or already-open Stream instance)
stream (int, str, dict, Stream) – synonymous with device, for compatibility
fs (float, None) – Optionally specify the sampling frequency, in Hz, when creating your first Recorder or first Stream (after that, Recorder instances may share an open Stream 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 of self.sound is reached
verbose (bool, None) – verbosity for debugging. If None, inherit from the setting specified by SetDefaultVerbosity(), if any
**kwargs – passed through to Set() to initialize properties of the Recorder instance.

Cut(position=None): Stop recording, and return the portion of self.sound that has been recorded so far, up to the current head position (or the explicitly specified position in seconds), as a new Sound 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 own Recorder 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 a Sound 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. If prompt is a string, it is printed to the console and the Recorder 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 the Sound when recording stops—i.e. ensure that the duration of the Sound does not exceed the duration of the recording. If false, the entire pre-allocated space 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 the ffmpeg binary to be (separately) installed—see the ffmpeg class documentation.
**kwargs – Additional keyword arguments are passed through to the constructor of the Recorder object (for example, to specify the device 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 recording head 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. If self.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 in self.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 recording head to that position, expressed in seconds from the beginning, before starting. If wait is true, Wait() until the end, or until the user presses ctrl+C.

Seek(position, relative=False)

Move the recording head to the specified position in seconds. Negative values count back from the end of the available recording space in self.sound. If relative 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 recording head to that position, expressed in seconds from the beginning, before starting. If wait 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 recording head 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. The condition 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 than None.

If finalRecordingStatus is not None, then self.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)

property head: Current recording position, in seconds relative to the beginning.

property loop: A boolean property. If this is True, treat self.sound as a circular buffer and record into it indefinitely (use the Cut() method to extract the recorded data in the correct order). If this is `False, the recorder will simply stop recording when the capacity of self.sound is reached.

The Recorder class

The `Recorder` class