Caution

You're reading an old version of this documentation. If you want up-to-date information, please have a look at 0.9.1.

librosa.util.frame

librosa.util.frame(x, frame_length=2048, hop_length=512, axis=- 1)

Slice a data array into (overlapping) frames.

This implementation uses low-level stride manipulation to avoid making a copy of the data. The resulting frame representation is a new view of the input data.

For example, a one-dimensional input x = [0, 1, 2, 3, 4, 5, 6] can be framed with frame length 3 and hop length 2 in two ways. The first (axis=-1), results in the array x_frames:

[[0, 2, 4],

[1, 3, 5], [2, 4, 6]]

where each column x_frames[:, i] contains a contiguous slice of the input x[i * hop_length : i * hop_length + frame_length].

The second way (axis=0) results in the array x_frames:

[[0, 1, 2],

[2, 3, 4], [4, 5, 6]]

where each row x_frames[i] contains a contiguous slice of the input.

This generalizes to higher dimensional inputs, as shown in the examples below. In general, the framing operation increments by 1 the number of dimensions, adding a new “frame axis” either to the end of the array (axis=-1) or the beginning of the array (axis=0).

Parameters

xnp.ndarray

Time series to frame. Must be contiguous in memory, see the “Raises” section below for more information.

frame_lengthint > 0 [scalar]

Length of the frame

hop_lengthint > 0 [scalar]

Number of steps to advance between frames

axis0 or -1

The axis along which to frame.

If axis=-1 (the default), then x is framed along its last dimension. x must be “F-contiguous” in this case.

If axis=0, then x is framed along its first dimension. x must be “C-contiguous” in this case.

Returns

x_framesnp.ndarray [shape=(…, frame_length, N_FRAMES) or (N_FRAMES, frame_length, …)]

A framed view of x, for example with axis=-1 (framing on the last dimension): x_frames[…, j] == x[…, j * hop_length : j * hop_length + frame_length]

If axis=0 (framing on the first dimension), then: x_frames[j] = x[j * hop_length : j * hop_length + frame_length]

Raises

ParameterError

If x is not contiguous in memory or not an np.ndarray.

If x.shape[axis] < frame_length, there is not enough data to fill one frame.

If hop_length < 1, frames cannot advance.

If axis is not 0 or -1. Framing is only supported along the first or last axis.

If axis=-1 (the default), then x must be “F-contiguous”. If axis=0, then x must be “C-contiguous”.

If the contiguity of x is incompatible with the framing axis.

See also

np.asfortranarray

Convert data to F-contiguous representation

np.ascontiguousarray

Convert data to C-contiguous representation

np.ndarray.flags

information about the memory layout of a numpy ndarray.

Examples

Extract 2048-sample frames from monophonic y with a hop of 64 samples per frame

>>> y, sr = librosa.load(librosa.util.example_audio_file())
>>> frames = librosa.util.frame(y, frame_length=2048, hop_length=64)
>>> frames
array([[ 0.000e+00,  0.000e+00, ..., -2.448e-06, -6.789e-07],
       [ 0.000e+00,  0.000e+00, ..., -1.399e-05,  1.004e-06],
       ...,
       [-7.352e-04,  5.162e-03, ...,  0.000e+00,  0.000e+00],
       [ 2.168e-03,  4.870e-03, ...,  0.000e+00,  0.000e+00]],
      dtype=float32)
>>> y.shape
(1355168,)
>>> frames.shape
(2048, 21143)

Or frame along the first axis instead of the last:

>>> frames = librosa.util.frame(y, frame_length=2048, hop_length=64, axis=0)
>>> frames.shape
(21143, 2048)

Frame a stereo signal:

>>> y, sr = librosa.load(librosa.util.example_audio_file(), mono=False)
>>> y.shape
(2, 1355168)
>>> frames = librosa.util.frame(y, frame_length=2048, hop_length=64)
(2, 2048, 21143)

Carve an STFT into fixed-length patches of 32 frames with 50% overlap

>>> y, sr = librosa.load(librosa.util.example_audio_file())
>>> S = np.abs(librosa.stft(y))
>>> S.shape
(1025, 2647)
>>> S_patch = librosa.util.frame(S, frame_length=32, hop_length=16)
>>> S_patch.shape
(1025, 32, 82)
>>> # The first patch contains the first 32 frames of S
>>> np.allclose(S_patch[:, :, 0], S[:, :32])
True
>>> # The second patch contains frames 16 to 16+32=48, and so on
>>> np.allclose(S_patch[:, :, 1], S[:, 16:48])
True