Nighttime Pachinko Marathon
    Wondering what’s next for npm?Check out our public roadmap! »

    @domchristie/needles

    0.0.2-1 • Public • Published

    Needles

    Audio loudness metering in the browser.

    Features:

    • Live momentary, short-term, and integrated K-weighted loudness (LUFS/LKFS) for a given web audio source.
    • Offline integrated K-weighted loudness for file analysis.
    • Offline momentary and short-term loudness values for higher resolution file analysis.
    • No GUI, it just reports values. The choice of interface and visual style is up to you!
    • Aims to be EBU Mode compliant, following EBU R 128 / ITU-R BS.1770-4.
    • Supports recent versions of Chrome and Firefox.

    Future features:

    • True-peak, dBTP (ITU-R BS.1770-4)
    • Loudness range, LRA (EBU R 128)
    • RMS?
    • Progress events for offline measurements
    • Update source and modes dynamically
    • Support for Safari (where some features of the Web Audio API are not supported)

    Installation

    Install via npm:

    npm install @domchristie/needles
    

    Then make the included dist/needles-worker.js file accessible on your server.

    Usage

    Import the library and create your source, for example via an <audio> element:

    import { LoudnessMeter } from '@domchristie/needles'
     
    var AudioContext = window.AudioContext || window.webkitAudioContext
    var audioContext = new AudioContext()
     
    var audioElement = document.querySelector('audio')
    var source = audioContext.createMediaElementSource(audioElement)
     
    // Listen to the output (optional)
    source.connect(audioContext.destination)

    Create your loudnessMeter passing in the source, and the worker path:

    var loudnessMeter = new LoudnessMeter({
      source: source,
      workerUri: 'public/path/to/needles-worker.js'
    })

    Listen for the dataavailable event which reports the loudness for each mode:

    loudnessMeter.on('dataavailable', function (event) {
      event.data.mode // momentary | short-term | integrated
      event.data.value // -14
    })

    Start metering:

    loudnessMeter.start()

    Offline Analysis

    Import the library and create an AudioContext:

    import { LoudnessMeter } from '@domchristie/needles'
     
    var AudioContext = window.AudioContext || window.webkitAudioContext
    var audioContext = new AudioContext()

    Create your source: usually by decoding an array buffer from an XHR response, or from reading the file with the FileReader API. Once a file has been decoded, create an OfflineAudioContext using the buffer properties, followed by a buffer source. Finally, create your loudnessMeter passing in the source, then start the analysis. Offline integrated analyses report dataavailable just once, when the entire buffer has been processed.

    var fileReader = new FileReader()
    fileReader.onload = function (event) {
      audioContext.decodeAudioData(event.target.result, audioDecoded)
    }
     
    var fileInput = document.querySelector('input[type="file"]')
    fileInput.onchange = function (event) {
      if (fileInput.files[0]) {
        fileReader.readAsArrayBuffer(fileInput.files[0])
      }
    }
     
    var OfflineAudioContext = window.OfflineAudioContext || window.webkitOfflineAudioContext
     
    function audioDecoded (buffer) {
      var offlineAudioContext = new OfflineAudioContext(
        buffer.numberOfChannels,
        buffer.length,
        buffer.sampleRate
      )
      var source = offlineAudioContext.createBufferSource()
      source.buffer = buffer
     
      var loudnessMeter = new Needles({
        source: source,
        modes: ['integrated'],
        workerUri: 'public/path/to/needles-worker.js'
      })
     
      loudnessMeter.on('dataavailable', function (event) {
        console.log(event.data.value)
      })
     
      loudnessMeter.start()
    }

    Options

    Needles is initialized with an object, requiring source property (an audio source node), and a workerUri property, referencing the public path of the needles-worker.js file.

    Operating modes can be chosen by passing in a modes array. Possible modes are:

    • momentary
    • short-term
    • integrated

    For example, to only meter short-term and integrated readings:

    var loudnessMeter = new LoudnessMeter({
      source: source,
      modes: ['short-term', 'integrated'],
      workerUri: 'public/path/to/needles-worker.js'
    })

    Methods

    start

    Starts processing samples from the source. For offline sources, the source and context rendering will also be started.

    pause

    Pauses metering.

    resume

    Resumes metering (following a pause).

    reset

    Resets all meters, reporting any remaining valid measurements in a dataavailable event. Event handlers are still maintained.

    stop

    Stops processing, resets all meters and reports any remaining valid measurements in a dataavailable event. Event handlers are still maintained.

    on(type, handler)

    Listens for an event type then calls the handler.

    off(type, handler)

    Removes the event handler for the given type. If no handler is specified, all handlers for the given event type are removed. If no arguments are supplied, all event handlers are removed.

    Events

    dataavailable

    Reports measurements for a given mode. The event's data includes:

    • mode: the operating mode, either momentary, short-term, or integrated
    • value: the loudness in LUFS

    Other events

    start, pause, resume, and stop are triggered after the corresponding methods are called.

    Notes on Implementation

    Needles uses the ScriptProcessorNode interface to access raw sample data. This is a deprecated API which will be replaced by the Audio Worklet interface (currently only supported in Chrome). Needles aims to be prepared for broader Audio Worklet support by implementing adapters for both interfaces. Initial tests using Audio Worklets in Chrome results in glitchy performance, and so are currently disabled. On the plus side, it doesn't look like ScriptProcessorNodes are going away (at least any time soon).

    License

    Needles is copyright © 2020+ Dom Christie and released under the MIT license.

    Install

    npm i @domchristie/needles

    DownloadsWeekly Downloads

    5

    Version

    0.0.2-1

    License

    MIT

    Unpacked Size

    980 kB

    Total Files

    35

    Last publish

    Collaborators

    • avatar