Test and measurement

Octave Bands `<smart-octave-bands>`

OctaveBands displays the level in each octave or third-octave band as a bar, with the frequency-weighted overall level and a limit curve the bands are checked against: the display of a sound level meter and of a vibration survey.

JavaScript TypeScript Angular React Vue Blazor

<smart-octave-bands> · 19 properties, 7 methods, 2 events · source/modules/smart.octavebands.js

Usage in React

The React wrapper is the OctaveBands component: every property is a prop, every event a prop named on<Event> that receives the CustomEvent, and the methods are called on the element through a ref.

import { OctaveBands } from 'smart-industrial/react/octavebands';

const ref = useRef<OctaveBands>(null);

<OctaveBands ref={ref} resolution={'octave'}
    onLevelsChange={(event: CustomEvent) => console.log(event.detail)} />

// methods are called on the wrapper the ref holds, which calls the element
ref.current?.push({});

Properties

Prop	Type, default	Description
`resolution`	OctaveBandsResolution third	Sets or retrieves the band width: whole octaves or third octaves.
`sampleRate`	number 48000	Sets or retrieves the sample rate of pushed blocks, in samples per second. A band is shown only when all of it lies below half the sample rate. A value that is not a positive number analyses nothing: push() returns false, the header says so, and one console warning names the value; assigned levels are still shown.
`size`	number 0	Sets or retrieves the FFT size a pushed block is analysed with. 0 uses the block's own length. Held to 16,777,216 at most.
`frequencyMin`	number 20	Sets or retrieves the centre frequency of the lowest band shown. Set above frequencyMax, the two are swapped, with one console warning, rather than leaving the chart empty.
`frequencyMax`	number 20000	Sets or retrieves the centre frequency of the highest band shown. Bands whose upper edge lies above half the sample rate are not shown whatever this says: at a sample rate of 8 kHz the 4 kHz third-octave band, which runs to 4.49 kHz, would be summed from the bins that exist and read low.
`weighting`	OctaveBandsWeighting Z	Sets or retrieves the frequency weighting applied to each band and to the overall level: Z (none), A or C, per IEC 61672.
`reference`	number 1	Sets or retrieves what reads as 0 dB: 1 for dB re one unit of the signal, 0.00002 for dB SPL of a signal in pascal.
`unit`	string	Sets or retrieves the signal's unit, so a level reads dBV or, with the 20 µPa reference, dB SPL.
`averaging`	OctaveBandsAveraging fast	Sets or retrieves the exponential time weighting of the bars: none, fast (125 ms) or slow (1 s), as a meter's.
`peakHold`	boolean true	Keeps the highest level of each band as a marker.
`levels`	array	Sets or retrieves the level of each band in dB, in the order of bands(). Assigned by an application with its own filter bank, or computed by push.
`limit`	array	Sets or retrieves the limit the bands are checked against: a level per band in dB, or [{ frequency, level }] points interpolated across the bands on the log axis. A band above its limit is drawn in the exceeded colour and counted in the header. A null or non-numeric per-band value is no limit for that band; a point that is not an object with a frequency and a level is skipped. Either is said once in a console warning.
`levelMin`	number?	Sets or retrieves the bottom of the level axis in dB. Null follows the data. With levelMax set below it, the two are swapped; set equal, the axis follows the data. Either is said once in a console warning.
`levelMax`	number?	Sets or retrieves the top of the level axis in dB. Null follows the data. Fixes the axis together with levelMin.
`showOverall`	boolean true	Shows the overall level in the header.
`showGrid`	boolean true	Shows the grid lines at the level ticks.
`paused`	boolean false	Drops pushed blocks while set.
`label`	string	Sets or retrieves the title shown in the header and used in the accessible name.
`precisionDigits`	number 1	Sets or retrieves the number of decimals in levels, held to 0 to 20.

Methods

Method	Description
`push(block: any): boolean`	Analyses a block of samples into band levels and shows them, with averaging and peak hold applied. Samples that are not numbers are analysed as zeros, and never passed off as clean: the header shows how many, levelsChange carries the count, and the console says so once per run of such blocks. Returns false, and analyses nothing, when the analyser is paused, when Smart.DSP is not loaded, when the block is not an array of at least two samples or has no number in it, or when the sample rate is not a positive number. `block` any The samples, as an array or a typed array.
`bands(): array`	Returns the bands shown: [{ centre, low, high, label, index }], centres on the IEC 61260 base-10 series, between frequencyMin and frequencyMax, and only bands whose upper edge lies below half the sample rate.
`overall(): number`	Returns the overall level: the levels of the bands summed on energy, in dB, or NaN with no levels.
`clear(): void`	Clears the levels and the peaks.
`resetPeaks(): void`	Drops the held peaks.
`describe(): string`	Returns a sentence describing what the analyser shows, as used in its accessible name: the bands, the overall level, the highest band and the number above the limit (exceededSummaryOne for one).
`invalidate(): void`	Redraws the plot on the next animation frame, so that many changes between two frames cost one draw.

Events

The data of an event is in event.detail. levelsChange reports levels the component has already computed from a pushed block and written to levels; blocks pushed while paused is true are dropped and raise nothing. bandClick reports a click on a band and changes nothing.

Event	Description and detail
`onLevelsChange` levelsChange	This event is triggered after a pushed block has been analysed. `levels` array The level of each band, in dB. `overall` number The overall level, in dB. `invalidSamples` number How many samples of the block were not numbers and were analysed as zeros; 0 for a clean block.
`onBandClick` bandClick	This event is triggered when a band is clicked. `index` number The band. `centre` number Its centre frequency. `label` string Its nominal frequency. `level` number Its level. `peak` number Its held peak.

Types

`type OctaveBandsResolution`

'octave' | 'third'

`type OctaveBandsWeighting`

'Z' | 'A' | 'C'

`type OctaveBandsAveraging`

'none' | 'fast' | 'slow'

CSS variables

The component declares 4 CSS variables; the CSS page shows how to set them.

--smart-octave-height --smart-octave-plot-background --smart-octave-grid-color --smart-octave-axis-color