SACRED1: Baptism

Analyze and accept audio submissions conditionally and programmatically.

Baptism is the first stage in the SACRED AUDIO automated workflow. It objectifies WAV files and provides interfaces to ffmpeg and sox to produce industry-compliant analyses of the audio data.

The module can serve as the backend for applications where the main use case is to accept, analyze, and QC audio file submissions. By providing easy interfaces for audio file introspection, generation of visual assets from audio file measurements, and validation to standard audio industry specifications, Baptism aims to support most of the basic considerations that are necessary to iron out new audio and music projects.

Status

In Development

Installation

$ npm -i baptism

Dependencies

This module utilizes some open source and/or GPL command line media processing tools. It expects there to be binaries for ffmpeg and sox inside the user's PATH.

Example

const bap = require('../index')

const newAlbum = new bap.Album('./')

newAlbum.probe((err, res) => {
  console.log(res)
  newAlbum.query()[0].spectrogram((err, spec) => {
    console.log(`Spectrogram output to: ${spec}`)
    newAlbum.query()[0].waveform((err, wave) => {
      console.log(`Waveform output to: ${wave}`)
    })
  })
})

{
  '/home/gwohl/code/sacreddata/baptism/example/example.wav': {
    duration: 10,
    peak: { db: -0.018041945998171376, value: 0.997925, valid: false },
    rms: { db: -15.695817254036564, value: 0.164138, valid: true }
  }
}
Spectrogram output to: /home/gwohl/code/sacreddata/baptism/example/example.wav.png
Waveform output to: /home/gwohl/code/sacreddata/baptism/example/example.wav_waveform.png

Usage

Audio Files

Baptism only works on WAV audio files and its extension formats, such as broadcast wave (BWF).

A WAV file is objectified by instantiating a new Baptism.Track, or its extension classes, Premaster and Master. However, it is recommended to use the Album or Release classes to create Track objects. A Premaster is meant to be added to an Album, while a Master is meant to be added to a Release.

Releases

An Album is instantiated by passing it a directory of WAV files. In order to guarantee proper track ordering, ensure WAV file path basenames begin with a leading zero, then the track number, followed by the track title, i.e., 03 - This Is A Song Title.wav. Other files present in the directory lacking the .wav file extension will be ignored.

A Release is an objectified version of a physical or digital music release, and it can be instantiated by calling new Baptism.Release. However, it is recommended to call one of its class extensions, Vinyl, Stream, Download, and CD. An Album can be added to a Release via its Release.add() method.

Assets

An ancillary file asset such as a cover art image, a cue sheet, credits, etc., may be objectified by the Asset class. It can be instantiated via new Baptism.Asset. Certain class extensions exist for specific asset features , including CoverArt. Additional class extensions are in development and forthcoming in a future release.

API

WIP

const bap = require('baptism')

Import baptism.

const album = new bap.Album(dir, [opts])

An object, which provides one or more Track objects. Extends nanoresource-pool.

The optional opts object allows for designating the following flags:

opts.metadata: An object to specify metadata about the Album. Accepted keys are opts.metadata.artist, opts.metadata.album, opts.metadata.title, and opts.metadata.comment. This metadata will be written to any WAVs output from the Album object.

album.probe(callback)

Batch processes each Track in the Album, calling the Track object's track.stats(), track.silence(), and track.soxi() methods. Callback provides an object containing each Track object's probe results.

album.validate

Returns object containing validation information for all the Track objects added to the Album.

const asset = new bap.Asset(file, [opts])

An object, which represents and objectifies a single Asset meant to be added to an Album or Release prior to completion. Accepts an optional opts object, with the following keys:

opts.hint: A string that provides an indication of the function of the asset.

Extends nanoresource.

const coverArt = new bap.CoverArt(file, [opts])

Extends Asset to provide specific functionality for cover art images. Adds { hint: 'image' } opt upon instantiation.

const flags = bap.flags

An object containing command line flags for various spawned child processes.

bap.soxi(filename, callback)

Callback returns an object containing media file formatting metadata, such as bit depth, sampling frequency, and channel count. Information is provided by the soxi command line application, provided by the SoX application.

This method is meant to be called by the Track class, so do not use this method directly in your code.

bap.stats(filename, callback)

Returns an object containing dynamics analysis measurements provided by the SoX application.

bap.spectrogram(filename, callback)

Returns a file path to a PNG of the file's spectrogram

const master = bap.Master(filename, [opts])

An object representing a mastered music track. Extends bap.Track. Accepts an optional opts object with the following configuration parameters:

opts.parent: Specify the Track object which served as the premaster source file for this Master. This property can also be set later via bap.Master.parent.

master.compare(callback)

Compare the Master audio file's dynamics and formatting properties with its parent Track or Premaster. Performs necessary analyses on the Master and Track objects if the information is not already available. Callback returns an object which provides comparison results and value deltas.

const premaster = bap.Premaster(filename, [opts])

An object representing a Track which has been prepared as a premaster. This is a common form of audio asset that is delivered to a mastering engineer.

Same as declaring a Track except for the extra properties that limit its data scope.

const Release = bap.Release

Class representations of physical and digital audio media products.

Release.add(item)

Add an Album or a single Track to the Release object.

const cd = new Release.CD([opts])

An object which represents a CD album release product. Extends Release.

const digital = new Release.Digital([opts])

An object which represents a digital release product. Extends Release.

const vinyl = new Release.Vinyl([opts])

An object which represents a vinyl release product. Extends Release.

Optional opts object accepts the following flags:

opts.size: Declare the size of the vinyl disc. Accepted values are 7, 10, or 12.

opts.speed: Declare the rotation speed of the vinyl disc. Accepted values are 33 or 45.

const track = new bap.Track(filename, [opts])

An object, which represents a single audio file. Extends nanoresource. Accepts an optional opts object to specify track number, via opts.trackNumber.

track.fingerprint(callback)

Generates a buffer of the raw fpcalc audio fingerprint for the Track. Writes the data to Track.fp as a buffer. Callback returns the fingerprint buffer.

track.peaks(callback)

Generates an Array of audio peaks data for the Track, for use in libraries such as wavesurfer and peaks.js.

This data is then scaled to [-1...1] and stored in track.peaksData. The callback also returns this scaled Array of peaks data.

track.size(callback)

Callback returns the file size of the file belonging to the Track.

track.silence(callback)

Checks the Track object for silence at the beginning and end of the file. Callback returns an object describing the silences as well as validation results.

track.soxi(callback)

Runs a soxi analysis on the filename belonging to the Track. Callback returns the relevant soxi information which is also written to Track.format.

track.spectrogram(callback)

Calls bap.spectrogram() on the Track object. track.spectrogram becomes the base64 byte-string of the generated PNG image. When finished, the output file path to the PNG is written returned by the callback, as well as written to track.spectrogramFile.

track.stats(callback)

Calls bap.stats() on the Track object. track.stats becomes the data object returned by the bap.stats() method.

track.wav

When Track.source points to a WAV file, track.wav will be provided upon instantiation, giving full access to the file via the WaveFile npm module. This allows users to set/remove RIFF tags, parse WAV chunks, modify WAV formatting, etc.

track.waveform(callback)

Generates a waveform PNG of the Track's file. track.waveform becomes the base64 byte-string of the generated PNG image. When finished, the output file path to the PNG is written returned by the callback, as well as written to track.waveformFile.