Main Content

octaveSpectrumEstimator

Compute octave-band spectrum

Since R2024b

expand all in page

Description

The octaveSpectrumEstimator System object™ measures the spectrum of streaming audio data using octave or fractional-octave bands.

To estimate the octave-band spectrum:

  1. Create the octaveSpectrumEstimator object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

o = octaveSpectrumEstimator
o = octaveSpectrumEstimator(fs)
o = octaveSpectrumEstimator(Name=Value)

Description

o = octaveSpectrumEstimator creates an octave spectrum estimator System object with default property values.

example

o = octaveSpectrumEstimator(fs) sets the SampleRate property to fs.

example

o = octaveSpectrumEstimator(Name=Value) sets Properties using one or more name-value arguments.

Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Input sample rate in Hz, specified as a positive scalar.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Frequency weighting applied to the input, specified as "A-weighting","C-weighting", or "Z-weighting", where "Z-weighting" corresponds to no weighting. The octaveSpectrumEstimator object implements the frequency weighting using weightingFilter.

This property is tunable in simulation but not in generated code.

Tunable: Yes

Data Types: char | string

Type of time-weighting applied to the spectrum estimates for smoothing, specified as "fast", "slow", or "custom". Setting TimeWeighting to "fast" corresponds to an attack time of 125 ms and a release time of 125 ms. Setting TimeWeighting to "slow" corresponds to an attack time of 1000 ms and a release time of 1000 ms. Set TimeWeighting to "custom" to use the AttackTime and ReleaseTime properties to define a custom time-weighting filter.

Tunable: Yes

Data Types: char | string

Time-weighting attack time in seconds, specified as a positive scalar.

This argument applies only when you set TimeWeighting to "custom".

Tunable: Yes

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Time-weighting release time in seconds, specified as a positive scalar.

This argument applies only when you set TimeWeighting to "custom".

Tunable: Yes

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Bandwidth of the octave-band filters used to compute the spectrum, specified as "1 octave", "2/3 octave", "1/2 octave", "1/3 octave", "1/6 octave", "1/12 octave", "1/24 octave", "1/48 octave", or "full band". If you set Bandwidth to "full band", the object does not compute an octave filter bank and instead measures the power of the whole frequency band.

This property is tunable in simulation but not in generated code.

Tunable: Yes

Data Types: char | string

Frequency range of the octave filter bank in Hz, specified as a two-element row vector of positive monotonically increasing values.

This property does not apply when you set Bandwidth to "full band".

This property is tunable in simulation but not in generated code.

Tunable: Yes

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Reference frequency of the filter bank in Hz, specified as a positive integer scalar. The ANSI S1.11-2004 standard defines the center frequencies of the octave filters relative to the reference frequency [1].

This property does not apply when you set Bandwidth to "full band".

This property is tunable in simulation but not in generated code.

Tunable: Yes

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Order of the octave filters, specified as an even integer. The filter order applies to each individual filter in the filter bank.

This property does not apply when you set Bandwidth to "full band".

This property is tunable in simulation but not in generated code.

Tunable: Yes

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Octave ratio base, specified as 10 or 2. The octave ratio base determines the distribution of the center frequencies of the octave filters. The ANSI S1.11 standard recommends base 10. Base 2 is popular for music applications. Base 2 defines an octave as a factor of 2, and base 10 defines an octave as a factor of 100.3.

This property does not apply when you set Bandwidth to "full band".

This property is tunable in simulation but not in generated code.

Tunable: Yes

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Apply base 10 logarithm to the output, specified as true or false.

Tunable: Yes

Data Types: logical

Usage

Syntax

p = o(audioIn)
[p,cf] = o(audioIn)

Description

p = o(audioIn) returns the octave spectrum for the current input frame, audioIn.

example

[p,cf] = o(audioIn) also returns the center frequencies of the octave filter bank.

Input Arguments

expand all

Audio input signal, specified as a column vector or matrix. If the input is a matrix, the object treats the columns as independent channels

Output Arguments

expand all

Octave spectrum, containing the measured power in each frequency band, returned as an N-by-B matrix or an N-by-B-by-C array where N is the length of the input audio frame, B is the number of bands in the octave filter bank, and C is the number of channels in the input. If you set Bandwidth to "full band", the object returns p as a column vector of length N or an N-by-C matrix.

Center frequencies in Hz of the filter bank used to compute the octave spectrum, returned as a row vector. If you set Bandwidth to "full band", the object returns cf as a scalar equal to fs/4, where fs is the SampleRate.

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

expand all

visualizeVisualize octave spectrum
parameterTunerTune object parameters while streaming
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

Open Live Script

Create an octaveSpectrumEstimator object and set the Bandwidth to "1 octave".

o = octaveSpectrumEstimator;
o.Bandwidth = "1 octave";

Create a single-channel, one-second-long pink noise signal.

x = pinknoise(o.SampleRate);

Measure the octave spectrum of the the pink noise and call visualize on the object to visualize the measured spectrum.

p = o(x);
visualize(o)

Open Live Script

Create a dsp.AudioFileReader to stream an audio file for processing. Create an audioDeviceWriter to play the audio as you stream it.

reader = dsp.AudioFileReader("FunkyDrums-44p1-stereo-25secs.mp3");
player = audioDeviceWriter(SampleRate=reader.SampleRate);

Create an octaveSpectrumEstimator object with the same sample rate as the file reader.

o = octaveSpectrumEstimator(reader.SampleRate)
o = 
  octaveSpectrumEstimator with properties:

            SampleRate: 44100
             Bandwidth: '1/3 octave'
    FrequencyWeighting: 'A-weighting'
         TimeWeighting: 'fast'
        FrequencyRange: [22 22050]
           FilterOrder: 2
    ReferenceFrequency: 1000
       OctaveRatioBase: 10
              ApplyLog: false

Call visualize on the object to open a visualizer to display the spectrum.

visualize(o)

In a streaming loop:

  1. Read in a frame of audio data.

  2. Compute the octave-band spectrum

  3. Play the audio with the device writer.

See the visualizer update with the measured spectrum as the audio plays.

while ~isDone(reader)
    audioIn = reader();
    p = o(audioIn);
    player(audioIn);
end

Open Live Script

Create a dsp.AudioFileReader to stream an audio file for processing. Create an audioDeviceWriter to play the audio as you stream it.

reader = dsp.AudioFileReader("FunkyDrums-44p1-stereo-25secs.mp3");
player = audioDeviceWriter(SampleRate=reader.SampleRate);

Create an octaveSpectrumEstimator object with the same sample rate as the file reader and set the Bandwidth to 1 octave.

o = octaveSpectrumEstimator(reader.SampleRate,Bandwidth="1 octave");

Call visualize on the object to open a visualizer to display the spectrum.

visualize(o)

Call parameterTuner to open a UI to tune parameters of the octaveSpectrumEstimator while streaming.

parameterTuner(o)

In a streaming loop:

  1. Read in a frame of audio data.

  2. Compute the octave-band spectrum

  3. Play the audio with the device writer.

Adjust the properties in the parameterTuner UI while streaming.

while ~isDone(reader)
    audioIn = reader();
    p = o(audioIn);
    player(audioIn);
end

Algorithms

To compute the octave-band spectrum, the octaveSpectrumEstimator object first optionally applies frequency-weighted filtering on the input signal using weightingFilter based on the FrequencyWeighting property. The octaveSpectrumEstimator object then passes the signal through an octave filter bank constructed using octaveFilterBank with the Bandwidth, FrequencyRange, ReferenceFrequency, FilterOrder, and OctaveRatioBase properties. The octaveSpectrumEstimator object takes the square of the filter bank output to get the power in each band then applies an averaging, time-weighted filter to perform time smoothing on the power values.

The time-weighted filter with attack time A and release time R is defined as:

y[n]={αAy[n−1]+(1−αA)x[n],x[n]≤y[n−1]αRy[n−1]+(1−αR)x[n],x[n]>y[n−1]

The attack time coefficient αA with sample rate Fs is:

αA=exp(−1Fs×A)

The release time coefficient αR is:

αR=exp(−1Fs×R)

References

[1] Acoustical Society of America. American National Standard Specification for Octave-Band and Fractional-Octave-Band Analog and Digital Filters. ANSI S1.11-2004. Melville, NY: Acoustical Society of America, 2009.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2024b

See Also

| |