Master Module — sudio documentation

# Master Module

class sudio.core.Master(std_input_dev_id=None, std_output_dev_id=None, data_format=<SampleFormat.SIGNED16: 2>, nperseg=500, noverlap=None, window='hann', NOLA_check=True, input_dev_sample_rate=48000, input_dev_nchannels=None, input_dev_callback=None, output_dev_nchannels=None, output_dev_callback=None, buffer_size=30, audio_data_directory='./data/')

  Bases: `object`

  The Master class is responsible for managing audio data streams, applying windowing, and handling input/output devices. This class provides various methods for processing, recording, and playing audio data, with functionality to handle different audio formats, sample rates, and device configurations.

  > - std_input_dev_id : Standard input device ID (default: None). If None, uses the system’s default input device.

  > - std_output_dev_id : Standard output device ID (default: None). If None, uses the system’s default output device.

  > - data_format : SampleFormat, optional The sample format of the audio. Default is 16-bit integer (SIGNED16). Supported formats: FLOAT32, SIGNED32, SIGNED24, SIGNED16, UNSIGNED8.

  > - nperseg : int, optional Number of segments per window. Default is 500.

  > - noverlap : int, optional Number of overlapping segments. If None, defaults to nperseg // 2.

  > - window : str, float, tuple, or ndarray, optional Window type or array. Default is ‘hann’. - If string: Specifies a scipy.signal window type (e.g., ‘hamming’, ‘blackman’). - If float: Interpreted as the beta parameter for scipy.signal.windows.kaiser. - If tuple: First element is the window name, followed by its parameters. - If ndarray: Direct specification of window values. - If None: Disables windowing.

  > - NOLA_check : bool, optional Perform the Non-Overlap-Add (NOLA) check. Default is True.

  > - input_dev_sample_rate : int, optional Sample rate of input device. Default is 48000 Hz. Only used if input_dev_callback is provided.

  > - input_dev_nchannels : int, optional Number of input device channels. Required if input_dev_callback is provided.

  > - input_dev_callback : Callable, optional Input device callback function. Should return a numpy array of shape (nchannels, nperseg) with appropriate data format.

  > - output_dev_nchannels : int, optional Number of output device channels. Required if output_dev_callback is provided.

  > - output_dev_callback : Callable, optional Output device callback function. Receives a numpy array of shape (nchannels, nperseg) with processed audio data.

  > - buffer_size : int, optional Size of the sound buffer. Default is 30.

  > - audio_data_directory : str, optional Directory for storing audio data (default: ‘./data/’).

  Notes

  - Various methods are available for audio processing, pipeline management, and device control. Refer to individual method docstrings for details.

  - The class uses threading for efficient audio stream management.

  - Window functions are crucial for spectral analysis and should be chosen carefully.

  - NOLA constraint ensures proper reconstruction in overlap-add methods.

  - Custom callbacks allow for flexible input/output handling but require careful implementation.

  CACHE_INFO = 32
  BUFFER_TYPE = '.bin'
  start()

    Starts the audio input and output streams and launches any registered threads.

    Returns:

      self – Returns the instance of the Master class for method chaining.

    Return type:

      Master

  add_file(filename, sample_format=<SampleFormat.UNKNOWN: 0>, nchannels=None, sample_rate=None, safe_load=True)

    Add an audio file to database. None value for the parameters means that they are automatically selected based on the properties of the audio file, and the master object.

    Note

    supported files format: WAV, FLAC, VORBIS, MP3

    Note

    The audio data maintaining process has additional cached files to reduce dynamic memory usage and improve performance, meaning that, The audio data storage methods can have different execution times based on the cached files.

    Parameters:

      - filename (`str`) – path/name of the audio file

      - sample_format (`SampleFormat`) – sample format

      - nchannels (`int`) – number of audio channels

      - sample_rate (`int`) – sample rate

      - safe_load – load an audio file and modify it according to the ‘Master’ attributes. (sample rate, sample format, number of channels, etc).

    Returns:

      WrapGenerator object

  add(record, safe_load=True)

    Adds audio metadata or data to the local database. This method can handle various types of input including wrapped records, metadata objects, or audio files in mp3, WAV, FLAC, or VORBIS format.

    ## Parameters:

    record :

      The record to be added. Can be: - A Wrap or WrapGenerator object - A string representing the path to an audio file - AudioMetadata containing record data

    safe_loadbool, optional

      If True (default), the audio file is loaded and modified according to the Master object’s attributes. This ensures compatibility with the current audio processing settings.

    ## Returns:

    : WrapGenerator

    > A wrapped version of the added record.

    ## Notes:

    - The method uses cached files to optimize memory usage and improve performance.

    > As a result, execution times may vary depending on the state of these cached files.

    - Supported audio file formats: mp3, WAV, FLAC, VORBIS

    ## Examples:

        # consider we have two master instances as m1, and m2
        # Adding an audio file
        record1 = m1.add("path/to/audio.wav")

        # adding a copy of record1 into master 2 instance
        record2 = m2.add(record1)

  recorder(record_duration, name=None)

    Record audio for a specified duration. This method captures audio input for a given duration and stores it as a new record in the Master object’s database.

    ## Parameters:

    record_durationfloat

      The duration of the recording in seconds.

    namestr, optional

      A custom name for the recorded audio. If None, a timestamp-based name is generated.

    return:

      WrapGenerator instance

    ## Notes:

    - The recording uses the current audio input settings of the Master object

    > (sample rate, number of channels, etc.).

    - The recorded audio is automatically added to the Master’s database and can be

    > accessed later using the provided or generated name.

    - This method temporarily modifies the internal state of the Master object to

    > facilitate recording. It restores the previous state after recording is complete.

    ## Examples:

    Record for 5 seconds with an auto-generated name

        >>> recorded_audio = master.recorder(5)

    Record for 10 seconds with a custom name

        >>> recorded_audio = master.recorder(10, name="my_recording")

    Use the recorded audio

        >>> master.echo(recorded_audio)

  load(name, safe_load=True, series=False)

    Loads a record from the local database. Trying to load a record that was previously loaded, outputs a wrapped version of the named record.

    Parameters:

      - name (`str`) – record name

      - safe_load (`bool`) – Flag to safely load the record. if safe load is enabled then load function tries to load a record in the local database based on the master settings, like the frame rate and etc (default: True).

      - series (`bool`) – Return the record as a series (default: False).

    Return type:

      `Union`[`WrapGenerator`, `AudioMetadata`]

    Returns:

      (optional) WrapGenerator object, AudioMetadata

  get_record_info(record)

    Retrieves metadata for a given record.

    Parameters:

      record (`Union`[`str`, `WrapGenerator`, `Wrap`]) – The record (str, WrapGenerator, or Wrap) whose info is requested.

    Return type:

      `dict`

    Returns:

      information about saved record in a dict format [‘frameRate’ ‘sizeInByte’ ‘duration’ ‘nchannels’ ‘nperseg’ ‘name’].

  syncable(*target, nchannels=None, sample_rate=None, sample_format=<SampleFormat.UNKNOWN: 0>)

    > Prepares a list of targets to be synchronized. Determines whether the target can be synced with specified properties or not

    Parameters:

      - target – Targets to sync. wrapped objects

      - nchannels (`int`) – Number of channels (default: None); if the value is None, the target will be compared to the ‘self’ properties.

      - sample_rate (`int`) – Sample rate (default: None); if the value is None, the target will be compared to the ‘self’ properties.

      - sample_format (`SampleFormat`) – Sample format (default: SampleFormat.UNKNOWN); if the value is None, the target will be compared to the ‘self’ properties.

    Returns:

      only objects that need to be synchronized.

  sync(*targets, nchannels=None, sample_rate=None, sample_format=<SampleFormat.UNKNOWN: 0>, output='wrapped')

    Synchronizes audio across multiple records. Synchronizes targets in the Wrap object format with the specified properties.

    Parameters:

      - targets – Records to sync. wrapped objects.

      - nchannels (`int`) – Number of channels (default: None); if the value is None, the target will be synced to the ‘self’ properties.

      - sample_rate (`int`) – Sample rate (default: None); if the value is None, the target will be synced to the ‘self’ properties.

      - sample_format (`SampleFormat`) – if the value is None, the target will be synced to the ‘self’ properties.

      - output – can be ‘wrapped’, ‘series’ or ‘ndarray_data’

    Returns:

      synchronized objects.

  del_record(record)

    Deletes a record from the local database.

    Parameters:

      record (`Union`[`str`, `AudioMetadata`, `Wrap`, `WrapGenerator`]) – Record to delete (str, AudioMetadata, Wrap, or WrapGenerator).

  export(record, file_path='./', format=<FileFormat.UNKNOWN: 0>, quality=0.5, bitrate=128)

    Exports a record to a file in WAV, MP3, FLAC, or VORBIS format. The output format can be specified either through the format argument or derived from the file extension in the file_path. If a file extension (‘.wav’, ‘.mp3’, ‘.flac’, or ‘.ogg’) is included in file_path, it takes precedence over the format argument. If no extension is provided, the format argument is used, defaulting to WAV if set to FileFormat.UNKNOWN. The exported file is saved at the specified file_path.

    Parameters:

      - record (`Union`[`str`, `AudioMetadata`, `Wrap`, `WrapGenerator`]) – Record to export (str, AudioMetadata, Wrap, or WrapGenerator). - str: Path to a file to be loaded and exported. - AudioMetadata: A metadata object containing audio data. - Wrap / WrapGenerator: Objects that wrap or generate the audio data.

      - file_path (`str`) – Path to save the exported file (default: ‘./’). - A new filename can be specified at the end of the path. - If a valid file extension (‘.wav’, ‘.mp3’, ‘.flac’, or ‘.ogg’) is provided, it determines the output format, overriding the format argument. - If no extension is included and the path is set to ‘./’, the name of the record is used.

      - format (`FileFormat`) – Output format (FileFormat.WAV, FileFormat.MP3, FileFormat.FLAC, or FileFormat.VORBIS). Defaults to FileFormat.UNKNOWN, which results in WAV being chosen unless a valid extension is provided in file_path.

      - quality (`float`) – Quality setting for encoding (default: 0.5). - For WAV: Ignored - For MP3: Converted to scale 0-9 (0 highest, 9 lowest) - For FLAC: Converted to scale 0-8 (0 fastest/lowest, 8 slowest/highest) - For VORBIS: Used directly (0.0 lowest, 1.0 highest)

      - bitrate (`int`) – Bitrate for MP3 encoding in kbps (default: 128). Only used if the format is MP3.

    Returns:

      None

    Raises: - TypeError: Raised if record is not one of the expected types (str, AudioMetadata, Wrap, or WrapGenerator). - ValueError: Raised if an unsupported format is provided.

  get_record_names()

    Returns a list of record names in the local database.

    Return type:

      `list`

  get_nperseg()

    Returns the number of segments per window.

  get_nchannels()

    Returns the number of audio channels.

  get_sample_rate()

    Returns the sample rate of the master instanse core processor.

  stream(record, block_mode=False, safe_load=False, on_stop=None, loop_mode=False, use_cached_files=True, stream_mode=StreamMode.optimized)

    Streams a record with optional loop and safe load modes.

    Note

    The audio data maintaining process has additional cached files to reduce dynamic memory usage and improve performance, meaning that, The audio data storage methods can have different execution times based on the cached files.

    Note: The recorder can only capture normal streams(Non-optimized streams)

    Parameters:

      - record (`Union`[`str`, `Wrap`, `AudioMetadata`, `WrapGenerator`]) – Record to stream (str, Wrap, AudioMetadata, or WrapGenerator).

      - block_mode (`bool`) – Whether to block the stream (default: False).

      - safe_load (`bool`) – Whether to safely load the record (default: False). load an audio file and modify it according to the ‘Master’ attributes(like the frame rate, number oof channels, etc).

      - on_stop (`callable`) – Callback for when the stream stops (default: None).

      - loop_mode (`bool`) – Whether to enable loop mode (default: False).

      - use_cached_files – Whether to use cached files (default: True).

      - stream_mode (`StreamMode`) – Streaming mode (default: StreamMode.optimized).

    Return type:

      `StreamControl`

    Returns:

      A StreamControl object

  mute()

    Mutes the master main stream.

  unmute()

    Unmutes the master main stream.

  is_muted()

    Checks if the audio stream is muted.

  echo(record=None, enable=None, main_output_enable=False)

    Play “Record” on the operating system’s default audio output. its also Enables or disables echoing of recorded data to the system’s default output, if record is not provided.

    Parameters:

      - record (`Union`[`Wrap`, `str`, `AudioMetadata`, `WrapGenerator`]) – optional, default None; Record to echo (str, Wrap, AudioMetadata, or WrapGenerator) (default: None).

      - enable (`bool`) – Whether to enable echoing on the master’s main stream (default: None means trigger mode).

      - main_output_enable (`bool`) – Whether to enable main stream’s output while playing provided record (default: False).

  disable_echo()

    Disables the echo functionality.

  wrap(record)

    wraps a record as a WrapGenerator.

    Parameters:

      record (`Union`[`str`, `AudioMetadata`]) – Record to wrap (str or AudioMetadata).

  clean_cache()

    The audio data maintaining process has additional cached files to reduce dynamic memory usage and improve performance, meaning that, The audio data storage methods can have different execution times based on the cached files. This function used to clean the audio cache by removing cached files.

  is_started()

    Checks if the audio input and output streams are started.

  get_window()

    Retrieves the current window configuration.

    Returns:

      dict or None: A dictionary containing window information if available, or None if not set.

      - ’type’: str, the type of window.

      - ’window’: window data.

      - ’overlap’: int, the overlap value.

      - ’size’: int, the size of the window.

  disable_std_input()

    Disables standard input stream by acquiring the main stream’s lock object.

  enable_std_input()

    Enables standard input stream by clearing the main stream’s lock.

  add_pipeline(pip, name=None, process_type=PipelineProcessType.MAIN, channel=None)

    Adds a new processing pipeline.

    ## Parameters:

    - pip (obj): Pipeline object or array of defined pipelines.

    Note

    In PipelineProcessType.MULTI_STREAM process type, pip must be an array of defined pipelines. The size of the array must be the same as the number of input channels.

    - name (str): Indicates the name of the pipeline.

    - process_type (PipelineProcessType): Type of processing pipeline (default: PipelineProcessType.MAIN). it can be:

    > - PipelineProcessType.MAIN: Processes input data and passes it to activated pipelines (if exist).

    > - PipelineProcessType.BRANCH: Represents a branch pipeline with optional channel parameter.

    > - PipelineProcessType.MULTI_STREAM: Represents a multi_stream pipeline mode. Requires an array of pipelines.

    - channel (obj): None or [0 to self.nchannel].

    > The input data passed to the pipeline can be a NumPy array in (self.nchannel, 2[2 windows in 1 frame], self._nperseg) dimension [None] or mono (2, self._nperseg) dimension. In mono mode [self.nchannel = 1 or mono mode activated], channel must be None.

    Note

    The pipeline must process data and return it to the core with the dimensions as same as the input.

  set_pipeline(stream)

    sets the main processing pipeline.

  disable_pipeline()

    Disables the current processing pipeline.

  clear_pipeline()

    Clears all pipeline’s data.

  set_window(window='hann', noverlap=None, NOLA_check=True)

    Configures the window function for audio processing.

    Parameters:

      - window (`object`) – The window function (default: ‘hann’).

      - noverlap (`int`) – Number of overlapping segments (default: None).

      - NOLA_check (`bool`) – Perform the NOLA check (default: True).

  get_sample_format()

    Returns the sample format of the master instance.

    Return type:

      `SampleFormat`

  static get_default_input_device_info()

    Returns information about the default input audio device.

    :return AudioDeviceInfo

    Return type:

      `AudioDeviceInfo`

  static get_default_output_device_info()

    Returns information about the default output audio device.

    :return AudioDeviceInfo

    Return type:

      `AudioDeviceInfo`

  static get_device_count()

    Returns the number of available audio devices.

    Return type:

      `int`

  static get_device_info_by_index(index)

    Returns information about a specific audio device by index.

    Parameters:

      index (`int`) – The index of the audio device (int).

    Return type:

      `AudioDeviceInfo`

    :return AudioDeviceInfo

  static get_input_devices()

    Returns a list of available input devices.

  static get_output_devices()

    Returns a list of available output devices.