HStft

An HStft is used to create STFTs. It caches results internally, so when making more than one Stft it is advisable to reuse the same HStft instance.

Methods

new_forward

new_forward(length: integer, dtype: HDataType) -> HStft source

Creates a new HStft instance which will be used to calculate forward STFTs.

If you plan on creating multiple STFT instances, it is recommended to reuse the same planner for all of them. This is because the planner re-uses internal data across STFT instances wherever possible, saving memory and reducing setup time (STFT instances created with one planner will never re-use data and buffers with STFT instances created by a different planner).

In the constructor, the FftPlanner will detect available CPU features. If AVX, SSE, Neon, or WASM SIMD are available, it will set itself up to plan STFTs with the fastest available instruction set. If no SIMD instruction sets are available, the planner will seamlessly fall back to planning non-SIMD STFTs.

Arguments

  • length - an integer denoting the length of the input. For 2D HArray’s, nrows must be provided.

  • dtype - a complex HDataType to indicate the dtype that the HStft will be working with.

Returns

An HStft.

Will return an error if dtype is of a float type.

Examples

library(harmonium)
dtype = HDataType$Complex32
hstft = HStft$new_forward(3L, dtype)

new_real_forward

new_real_forward(length: integer, dtype: HDataType) -> HStft source

Creates a new HStft instance which will be used to calculate real forward STFTs.

If you plan on creating multiple STFT instances, it is recommended to reuse the same planner for all of them. This is because the planner re-uses internal data across STFT instances wherever possible, saving memory and reducing setup time (STFT instances created with one planner will never re-use data and buffers with STFT instances created by a different planner).

In the constructor, the FftPlanner will detect available CPU features. If AVX, SSE, Neon, or WASM SIMD are available, it will set itself up to plan STFTs with the fastest available instruction set. If no SIMD instruction sets are available, the planner will seamlessly fall back to planning non-SIMD STFTs.

Arguments

  • length - an integer denoting the length of the input. For 2D HArray’s, nrows must be provided.

  • dtype - a float HDataType to indicate the dtype that the HStft will be working with.

Returns

An HStft.

Will return an error if dtype is of complex type.

Examples

library(harmonium)
dtype = HDataType$Float32
hstft = HStft$new_real_forward(3L, dtype)

process

process(harray: HArray, hop_length: Integer, window_length: Integer, window: Optional<HArray>) source

Computes the STFT of a complex HArray. The STFT computed may be forward or inverse, depending on the HStft created.

The STFT computes the Fourier transform of short overlapping windows of the input. This giving frequency components of the signal as they change over time.

The operation is done in-place, which means, in this case, although a new HArray is created, the same external pointer will be used to store it.

For a forward STFT, the HArray output will have the shape: - (fft_length, n_fft) if 1D input HArray. - (ncols, fft_length, n_fft) if 2D input HArray.

For a real forward STFT, it will have the shape: - (fft_length / 2 + 1, n_fft) if 1D input HArray. - (ncols, fft_length / 2 + 1, n_fft) if 2D input HArray.

Where ncols is the number of columns of the input HArray, fft_length is the length provided when the HStft is created, n_fft is the number of frames and fft_length / 2 is a floor division

Arguments

  • harray - A complex 1D or 2D HArray.

  • hop_length - the distance between neighboring sliding window frames.

  • window_length - Each column of the HArray is windowed by window of length window_length and then padded with zeros to match n_fft. Padding is added on both the left and the right side of the window so that the window is centered within the frame. Smaller values improve the temporal resolution of the STFT (i.e. the ability to discriminate impulses that are closely spaced in time) at the expense of frequency resolution (i.e. the ability to discriminate pure tones that are closely spaced in frequency).

  • window - A float HArray representing a window function. This input is optional.

Returns

Will return an error if:

  • The HArray’s dtype is incompatible with the HStft’s dtype.

  • The HArray’s ndim is greater than 2.

Examples

library(harmonium)
arr = as.array(c(1+1i,2+2i,3+3i,4+4i,5+5i,6+6i))
dtype = HDataType$Complex32
harray = HArray$new_from_values(arr, dtype)
hstft = HStft$new_forward(5L, dtype)
hop_length = 2L
window_length = 3L
window = HArray$new_from_values(as.array(c(1,2,3)), HDataType$Float32)
hstft$process(harray, hop_length, window_length, window)

dtype

dtype() -> HDataType source

Gets the HStft’s dtype.

Returns

An HDataType.

Examples

library(harmonium)
dtype = HDataType$Complex32
hstft = HStft$new_forward(3L, dtype)
hstft$dtype()

print

print() source

Prints the HStft.

Differently from R’s normal behaviour, print doesn’t return the value invisibly.

Examples

library(harmonium)
dtype = HDataType$Complex32
hstft = HStft$new_forward(3L, dtype)
hstft$print()

# or similarly:
print(hstft)

clone

clone() -> HStft source

Clones the HStft.

Creates a new HStft, with the underlying data pointing to the same place in memory. When HSTFT is cloned, thus having more than one reference to the same internal struct, and process is run, it uses the same cached Fft instance, but a new scratch buffer will have to be allocated.

Returns

An HStft.

Examples

library(harmonium)
dtype = HDataType$Complex32
hstft = HStft$new_forward(3L, dtype)
hstft$clone()

is_unique

is_unique() -> bool source

Checks if the object is unique.

Since HStft has a COW (clone-on-write) behaviour, this function is useful to check if a new object will be created or if the change will be done in-place.

Returns

A bool.

Examples

library(harmonium)
dtype = HDataType$Complex32
hstft = HStft$new_forward(3L, dtype)
hstft$is_unique() # TRUE.

hstft2 = hstft$clone()
hstft$is_unique() # FALSE, hstft shares the same inner object with hstft2.

invalidate

invalidate() source

Replaces the inner value of the external pointer, invalidating it. This function is useful to remove one of the shared references of the inner pointer in rust.

Examples

library(harmonium)
dtype = HDataType$Complex32
hstft = HStft$new_forward(3L, dtype)
hstft$invalidate()