Wrap Module — sudio documentation

# Wrap Module

class sudio.wrap.wrap.Wrap(other, record, generator)

  Bases: `object`

  Initialize the Wrap object.

  Parameters:

    - other – The parent object.

    - record – Preloaded record or AudioMetadata.

    - generator – The audio generator associated with the record.

  Slicing: The Wrapped object can be sliced using standard Python slice syntax x[start: stop: step], where x is the wrapped object.

  Slicing the time domain: Use [i: j: k, i(2): j(2): k(2), i(n): j(n): k(n)] syntax, where i is start time, j is stop time, and k is step (negative for inversing). This selects nXm seconds with index times i, i+1, i+2, …, j, i(2), i(2)+1, …, j(2), i(n), …, j(n) where m = j - i (j > i).

  Note: for i < j, i is stop time, j is start time, meaning audio data is read inversely.

  Filtering (Slicing the frequency domain): Use [‘i’: ‘j’: ‘filtering options’, ‘i(2)’: ‘j(2)’: ‘options(2)’, …, ‘i(n)’: ‘j(n)’: ‘options(n)’] where i is starting frequency, j is stopping frequency (string type, same units as fs). Activates n iir filters with specified frequencies and options.

  For slice syntax [x: y: options]: - x=None, y=’j’: low pass filter with a cutoff frequency of j - x=’i’, y=None: high pass filter with a cutoff frequency of i - x=’i’, y=’j’: bandpass filter with critical frequencies i, j - x=’i’, y=’j’, options=’scale=[Any negative number]’: bandstop filter with critical frequencies i, j

  Filtering options: - ftype: optional; The type of IIR filter to design: ‘butter’ (default), ‘cheby1’, ‘cheby2’, ‘ellip’, ‘bessel’ - rs: float, optional: For Chebyshev and elliptic filters, provides minimum attenuation in stop band (dB) - rp: float, optional: For Chebyshev and elliptic filters, provides maximum ripple in passband (dB) - order: The order of the filter (default 5) - scale: [float, int] optional; Attenuation or amplification factor, must be negative in bandstop filter.

  Complex slicing: Use [a: b, ‘i’: ‘j’: ‘filtering options’, …, ‘i(n)’: ‘j(n)’: ‘options(n)’, …, a(n): b(n), …] or [a: b, [Filter block 1)], a(2): b(2), [Filter block 2] …, a(n): b(n), [Filter block n]]. i is starting frequency, j is stopping frequency, a is starting time, b is stopping time in seconds. Activates n filter blocks described in the filtering section, each operating within a predetermined time range.

  Note: The sliced object is stored statically, so calling the original wrapped returns the sliced object.

  Dynamic and static memory management: Wrapped objects are stored statically; all calculations need additional IO read/write time. This reduces dynamic memory usage, especially for large audio data. All operations (mathematical, slicing, etc.) can be done faster in dynamic memory using the unpack method.

  Examples: Slicing wrap object snd remove 10 to 36 seconds >>> master = Master() >>> wrap = master.add(‘file.mp3’) >>> master.echo(wrap[5: 10, 36:90] * .5)

  Bandstop filter: >>> wrap[‘200’: ‘1000’: ‘order=6, scale=-.8’] >>> master.echo(wrap)

  Complex slicing and inversing: >>> wrap[: 10, :’100’: ‘scale=1.1’, 5: 15: -1, ‘100’: ‘5000’: ‘order=10, scale=.8’] >>> master.echo(wrap - .7)

  Simple two-band EQ: >>> wrap[20:30,: ‘100’: ‘order=4, scale=.7’, ‘100’::’order=5, scale=.4’] >>> master.echo(wrap)

  name

    Descriptor class for accessing and modifying the ‘name’ attribute of an object.

    This class is intended to be used as a descriptor for the ‘name’ attribute of an object. It allows getting and setting the ‘name’ attribute through the __get__ and __set__ methods.

  get_sample_format()

    Get the sample format of the audio data.

    Return type:

      `SampleFormat`

    Returns:

      The sample format enumeration.

  get_sample_width()

    Get the sample width (in bytes) of the audio data.

    Return type:

      `int`

    Returns:

      The sample width.

  get_master()

    Get the parent object (Master) associated with this Wrap object.

    Returns:

      The parent Master object.

  get_size()

    Get the size of the audio data file.

    Return type:

      `int`

    Returns:

      The size of the audio data file in bytes.

  get_sample_rate()

    Get the frame rate of the audio data.

    Return type:

      `int`

    Returns:

      The frame rate of the audio data.

  get_nchannels()

    Get the number of channels in the audio data.

    Return type:

      `int`

    Returns:

      The number of channels.

  get_duration()

    Get the duration of the audio data in seconds.

    Return type:

      `float`

    Returns:

      The duration of the audio data.

  join(*other)

    Join the current audio data with other audio data.

    Parameters:

      other – Other audio data to be joined.

    Returns:

      The current Wrap object after joining with other audio data.

  unpack(reset=False, astype=<SampleFormat.UNKNOWN: 0>)

    Unpacks audio data from cached files to dynamic memory.

    Parameters:

      reset – Resets the audio pointer to time 0 (Equivalent to slice ‘[:]’).

    Return type:

      `ndarray`

    Returns:

      Audio data in ndarray format with shape (number of audio channels, block size).

    Notes: - All calculations within the unpacked block are performed on the pre-cached files, not on the original audio data.

    Examples

        >>> master = Master()
        >>> wrap = master.add('file.mp3')
        >>> with wrap.unpack() as data:
        >>>     wrap.set_data(data * 0.7)
        >>> master.echo(wrap)

  get_data()

    Get the audio data either from cached files or dynamic memory.

    Return type:

      `Union`[`AudioMetadata`, `ndarray`]

    Returns:

      If packed, returns record information. If unpacked, returns the audio data.

  is_packed()

    Check if the Wrap object is in packed mode.

    Return type:

      `bool`

    Returns:

      True if the Wrap object is in packed mode, False otherwise.

  get(offset=None, whence=None)

    Context manager for getting a file handle and managing seek position.

    Parameters:

      - offset – Offset to seek within the file.

      - whence – Reference point for the seek operation.

    Returns:

      File handle for reading or writing.

  set_data(data)

    Set the audio data when the Wrap object is in unpacked mode.

    Parameters:

      data – Audio data to be set.

    Returns:

      None

class sudio.wrap.wrapgenerator.WrapGenerator(master, record)

  Bases: `object`

  Initialize the WrapGenerator instance.

  Parameters:

    - master – The master instance.

    - record – The record to be wrapped.

  name

    Descriptor class for accessing and modifying the ‘name’ attribute of an object.

    This class is intended to be used as a descriptor for the ‘name’ attribute of an object. It allows getting and setting the ‘name’ attribute through the __get__ and __set__ methods.

  get_data()

    Get the data of the WrapGenerator instance.

    Returns:

      The data.

    Return type:

      AudioMetadata

  get(offset=None, whence=None)

    Get the context manager for the file.

    Parameters:

      - offset – Offset for seeking.

      - whence – Reference for seeking.

    Yields:

      io.BufferedRandom – The file.

  set_data(data)

    Set the data of the WrapGenerator instance.

    Parameters:

      data – The data to be set.

  get_sample_format()

    Get the sample format of the WrapGenerator instance.

    Returns:

      The sample format.

    Return type:

      SampleFormat

  get_sample_width()

    Get the sample width of the WrapGenerator instance.

    Returns:

      The sample width.

    Return type:

      int

  get_master()

    Get the master of the WrapGenerator instance.

    Returns:

      The master.

  get_size()

    Get the size of the WrapGenerator instance.

    Returns:

      The size.

    Return type:

      int

  get_cache_size()

    Get the cache size of the WrapGenerator instance.

    Returns:

      The cache size.

    Return type:

      int

  get_sample_rate()

    Get the frame rate of the WrapGenerator instance.

    Returns:

      The frame rate.

    Return type:

      int

  get_nchannels()

    Get the number of channels of the WrapGenerator instance.

    Returns:

      The number of channels.

    Return type:

      int

  get_duration()

    Get the duration of the WrapGenerator instance.

    Returns:

      The duration.

    Return type:

      float

  join(*other, sync_sample_format=None, sync_nchannels=None, sync_sample_rate=None, safe_load=True)

    Join multiple WrapGenerators.

    Parameters:

      - *other – Other WrapGenerators.

      - sync_sample_format (`SampleFormat`) – Sync the sample format.

      - sync_nchannels (`int`) – Sync the number of channels.

      - sync_sample_rate (`int`) – Sync the sample rate.

      - safe_load (`bool`) – Use safe loading.

    Returns:

      A Wrap instance.

    Return type:

      Wrap

  unpack(reset=False, astype=<SampleFormat.UNKNOWN: 0>)

    Unpacks audio data from cached files to dynamic memory.

    Parameters:

      reset – Resets the audio pointer to time 0 (Equivalent to slice ‘[:]’).

    Return type:

      `ndarray`

    Returns:

      Audio data in ndarray format with shape (number of audio channels, block size).

    Notes: - All calculations within the unpacked block are performed on the pre-cached files, not on the original audio data.

    Examples

        >>> master = Master()
        >>> wrap = master.add('file.mp3')
        >>> with wrap.unpack() as data:
        >>>     wrap.set_data(data * 0.7)
        >>> master.echo(wrap)