sc-utils

Simple generic utilities (type check, common math functions, etc.)

Install

npm install --save @ircam/sc-utils

API

Table of Contents

• atodb
• counter
• dbtoa
• decibelToLinear
• decibelToPower
• delay
• exponentialScale
• ftom
• getTime
• hertzToNormalised
• idGenerator
• isBrowser
• isFunction
• isNumber
• isPlainObject
• isSequence
• isString
• isTouchDevice
• isTypedArray
• isURL
• linearScale
• linearToDecibel
• logarithmicScale
• mtof
• normalisedToHertz
• normalizedToTableScale
• powerToDecibel
• sleep
• tableToNormalizedScale

atodb

Convert a linear gain into dB

Alias: linearToDecibel

Parameters

• val number Value to convert

Examples

import { atodb } from '@ircam/sc-utils';
atodb(0);
// > 1

Returns number

counter

Create a counter function.

Parameters

• from number Start of the counter, included (optional, default 0)
• to number End of the counter, included (optional, default Number.MAX_SAFE_INTEGER)
• step number Increment / decrement step, if 0 returns from forever (optional, default 1)

Returns Function import { counter } from '@ircam/sc-utils'; const myCounter = counter(0.1, 0.3, 0.1); counter(); // 0.1 counter(); // 0.2 counter(); // 0.3 counter(); // 0.1 // ...

dbtoa

Convert a dB into linear gain

Alias: decibelToLinear

Parameters

• val number Value to convert

Examples

import { dbtoa } from '@ircam/sc-utils';
dbtoa(0);
// > 1

Returns number

decibelToLinear

Convert a dB into linear gain (i.e. gain)

Alias: dbtoa

Parameters

• val number Value to convert

Examples

import { decibelToLinear } from '@ircam/sc-utils';
decibelToLinear(0);
// > 1

Returns number

decibelToPower

Convert a dB into power gain

Parameters

• val number Value to convert

Examples

import { decibelToPower } from '@ircam/sc-utils';
decibelToPower(0);
// > 1

Returns number

delay

Wait for a given number of milliseconds.

See also sleep

Parameters

• ms Number Number of milliseconds to wait

Examples

import { delay } from '@ircam/sc-utils';
// wait for 1 second
await delay(1000);

Returns Promise

exponentialScale

Create an exponential scale function.

Parameters

• inputStart number Start value of input range
• inputEnd number End value of input range
• outputStart number Start value of output range
• outputEnd number End value of output range
• base number Base value for exponential scaling, default to 2 (optional, default 2)
• clip boolean Clip output to output range, default to false (optional, default false)

Examples

const { exponentialScale } = utils;
const midiToFreq = exponentialScale(69, 81, 440, 880);
midiToFreq(57);
// > 220

ftom

Convert a frequency in Hz to a MIDI note

Parameters

• freq number Frequency to convert

Examples

import { ftom } from '@ircam/sc-utils';
const freq = ftom(440);
// > 69

Returns number

getTime

Provide a unified clock in seconds accross platforms, with an origin defined by the start of the process.

Examples

import { getTime } from '@ircam/sc-utils';

setInterval(() => {
  const now = getTime();
  // ...
}, 1000);

Returns number

hertzToNormalised

Convert a frequency in Hertz to a normalised one in [0, 1].

Normalised frequency of 1 is half the sample-rate (Nyquist frequency).

Parameters

• frequencyHertz number Frequency in Hertz to convert

• sampleRate number Twice the Nyquist frequency (optional, default {})

  • sampleRate.sampleRate (optional, default 2)

Examples

import { hertzToNormalised } from '@ircam/sc-utils';
hertzToNormalised(12000, {sampleRate: 48000});
// > 0.5

Returns number

idGenerator

Create a iterator of incrementing ids

DEPRECATED Use the more generic and user friendly counter instead.

Examples

import { idGenerator } from '@ircam/sc-utils';
const generator = idGenerator();
const id = generator.next().value

Returns Iterator

isBrowser

Check if the platform is a browser or a node process

Examples

import { isBrowser } from '@ircam/sc-utils';
isBrowser();
// > true|false

Returns boolean

isFunction

Check if the value is a function

Parameters

• val any Value to check

Examples

import { isFunction } from '@ircam/sc-utils';
isFunction(() => {});
// > true

Returns boolean

isNumber

Check if the value is a number, including Infinity. If you want to excluse Infinity, check the native Number.isFinite function

Parameters

• val any Value to check

Examples

import { isNumber } from '@ircam/sc-utils';
isNumber(42);
// > true

Returns boolean

isPlainObject

Check if the value is a Plain Old Javascript Object (POJO)

Parameters

• val any Value to check

Examples

import { isPlainObject } from '@ircam/sc-utils';
isPlainObject({ a: 1 });
// > true

Returns boolean

isSequence

Check if the value is a sequence (Array or TypedArray) of finite numbers

Parameters

• val any Value to check

Examples

import { isSequence } from '@ircam/sc-utils';
isSequence([1, 2, 3]);
// > true

Returns boolean

isString

Check if the value is a string

Parameters

• val any Value to check

Examples

import { isString } from '@ircam/sc-utils';
isString('test');
// > true

Returns boolean

isTouchDevice

Check if the device supports touch events

Examples

import { isTouchDevice } from '@ircam/sc-utils';
isTouchDevice();
// > true|false

Returns boolean

isTypedArray

Check if the value is a TypedArray

Parameters

• val any Value to check

Examples

import { isTypedArray } from '@ircam/sc-utils';
isTypedArray(new Float32Array([1, 2, 3]));
// > true

Returns boolean

isURL

Check if the value is a valid URL

Parameters

• url
• val any Value to check

Examples

import { isURL } from '@ircam/sc-utils';
isURL('http://sub.my-site.org/abcd?test=123');
// > true

Returns boolean

linearScale

Create a linear scale function.

Parameters

• inputStart number Start value of input range
• inputEnd number End value of input range
• outputStart number Start value of output range
• outputEnd number End value of output range
• clip boolean Clip output to output range, default to false (optional, default false)

Examples

import { scale } from '@ircam/sc-utils';
const myScale = scale(0, 1, 50, 100);
myScale(0.5);
// > 75

Returns Function

linearToDecibel

Convert a linear gain into dB

Alias: atodb

Parameters

• val number Value to convert

Examples

import { decibelToPower } from '@ircam/sc-utils';
decibelToPower(0);
// > 1

Returns number

logarithmicScale

Create a logarithmic scale function.

Parameters

• inputStart number Start value of input range
• inputEnd number End value of input range
• outputStart number Start value of output range
• outputEnd number End value of output range
• base number Base value for logarithmic scaling, default to 2 (optional, default 2)
• clip boolean Clip output to output range, default to false (optional, default false)

Examples

const { logarithmicScale } = utils;
const freqToMidi = logarithmicScale(440, 880, 69, 81);
freqToMidi(220);
// > 57

mtof

Convert a MIDI note to frequency

Parameters

• midiNote number MIDI Note to convert

Examples

import { mtof } from '@ircam/sc-utils';
const freq = mtof(69);
// > 440

Returns number

normalisedToHertz

Convert a normalised frequency, in [0, 1], to a frequency in Hertz.

Normalised frequency of 1 is half the sample-rate (Nyquist frequency).

Parameters

• frequencyNormalised number Normalised frequency to convert

• sampleRate number Twice the Nyquist frequency (optional, default {})

  • sampleRate.sampleRate (optional, default 2)

Examples

import { normalisedToHertz } from '@ircam/sc-utils';
normalisedToHertz(0.5, {sampleRate: 48000});
// > 12000

Returns number

normalizedToTableScale

Create a scale function that returns a linearly interpolated value from the given transfert table according to the given normalized position.

Parameters

• transfertTable Array<number> Sequence of finite numbers to use as lookup table

Examples

import { normalizedToTableScale } from '@ircam/sc-utils'
const scale = normalizedToTableScale([1, 2, 4])
scale(0);    // 1
scale(0.25); // 1.5
scale(0.5);  // 2
scale(0.75); // 3
scale(1);    // 4

Returns function

powerToDecibel

Convert a linear gain into dB

Parameters

• val number Value to convert

Examples

import { decibelToPower } from '@ircam/sc-utils';
decibelToPower(0);
// > 1

Returns number

sleep

Wait for a given number of seconds.

See also delay

Parameters

• sec Number Number of seconds to wait

Examples

import { sleep } from '@ircam/sc-utils';
// wait for 1 second
await sleep(1);

Returns Promise

tableToNormalizedScale

Create a scale function that returns a normalized position in the transfert table according to the given value.

Parameters

• transfertTable Array<number> Sequence of finite numbers to use as lookup table

Examples

import { tableToNormalized } from '@ircam/sc-utils'
const scale = tableToNormalized([1, 2, 4])
scale(1);    // 0
scale(1.5);  // 0.25
scale(2);    // 0.5
scale(3);    // 0.75
scale(4);    // 1

Returns function

License

BSD-3-Clause