node-medley
is a Node.js native module built on top of JUCE framework to provide audio playback to either an audio output device or Node.js stream
- Cross-platform
- Seamless playback, automatically transit between tracks
- Nice transition between tracks, with customizable transition point
- Track metadata reading, including cover art and lyrics
- ReplayGain support
- Audio level normalization (in conjunction with ReplayGain)
- Built-in audio limiter
- Built-in Karaoke effect (vocal removal)
- Audio level measurement
- Play directly to audio device
- Consume PCM data directly from audio pipeline via Node.js stream
linux/amd64
linux/arm64
win32/x64
macOS/x64
macOS/arm64
npm i @seamless-medley/medley
pnpm add @seamless-medley/medley
// Import 2 main classes.
import { Medley, Queue } from '@seamless-medley/medley';
// Then craete a new queue instance and pass it to `Medley` class while instantiating.
const queue = new Queue();
const medley = new Medley(queue);
// Add some tracks to the `queue` and start playing
queue.add('/path/to/file');
queue.add('/path/to/file2');
medley.play();
This will start playing to the default audio device.
Currently, the supported file formats are limited to: wav
, aiff
, mp3
, ogg
and flac
, but more formats might be added in the future.
- Getting available audio devices
- Selecting audio device
- Null Audio device
- Getting PCM data
- Dynamic queue
- Check if a track is loadable
- Getting metadata
- Getting cover art and lyrics
- Reading audio level information
- Normalizing tracks audio level
- Custom transition point
Just use getAvailableDevices method.
Use data returned from getAvailableDevices method with setAudioDevice method
Example:
// Use default device of the first type
const allDevices = medley.getAvailableDevices();
medley.setAudioDevice({
type: allDevices[0].type,
device: allDevices[0].defaultDevice
});
node-medley
has a special audio device called Null Device
which does not play sound to the actual audio device.
This is useful when node-medley
is being used in an environment without any audio devices installed.
Or simply because you just need to consume the PCM audio data without sending it to the actual audio device. see requestAudioStream method.
Example:
medley.setAudioDevice({ type: 'Null', device: 'Null Device' });
// Request for signed 16 bit, little endian, 48000 sample rate audio stream
const result = await medley.requestAudioStream({
format: 'Int16LE',
sampleRate: 48000
});
// Pipe to another stream
result.stream.pipe(/* destination */);
// Or intercept data with `data` event
result.stream.on('data', (buffer) => {
// Do something with `buffer`
});
// When done, don't forget the delete the stream
medley.deleteAudioStream(result.id);
Sometimes adding tracks to the queue upfront can cause Musical Boredom, so let's make the queue dynamic by leveraging enqueueNext event
Example:
medley.on('enqueueNext', (done) => {
const newTrack = getNewFreshTrack(); // Your logic goes here
queue.add(newTrack);
done(true);
});
Use isTrackLoadable static method.
There are two ways of getting metadata:
- From file path
- Use getMetadata static method
- From a deck
- Use getDeckMetadata method
Use getCoverAndLyrics method.
Real-time audio level information can be retrieved by using level property.
Example:
// Reading audio level at 30 times per second rate
setInterval(() => {
const audioLevel = medley.level;
// Use the returned value
}, 1000 / 30);
ReplayGain can be used to analyze for the adjustment to the perceived loudness of audio tracks.
node-medley
supports reading ReplayGain Track-gain
metadata embeded in audio files.
To embed it, you can use one of these scanners.
Usually, ReplayGain attenuates the played back audio, a make-up
gain should be applied to boost the audio level back to the normalized level, you can change this make-up
gain by changing the replayGainBoost property.
The make-up
gain will not cause clipping, because there is an audio limiter preventing that from happening in the audio pipline.
node-medley
automatically analyze tracks to find audio positions in which it should start/stop playing and also the positions/durations the transition between track should occur.
but, sometimes this may not be as intended, you can customize that by giving node-medley
some hints.
The hints can come from the metadata embed in the track itself using user-defined tag, here are the supported tags:
-
CUE-IN
orCUE_IN
- Start position of the track, in secondsThis correspond to the TrackInfo
cueInPosition
property. -
CUE-OUT
orCUE_OUT
- Stop position of the track, in secondsThis correspond to the TrackInfo
cueOutPosition
property.
Alternatively, you can provide that values when adding a track into the queue.
See also:
-
- Methods
- Properties
- Events
- Static methods
This is the main class, the constructor accepts an instance of Queue class.
new Medley(queue, options)
NOTE: JavaScript
Array
cannot be used as a queue.
-
logging
(boolean?) - Enable logging, See log event -
skipDeviceScanning
(boolean?) - Skip scanning for audio devices
Methods
Start playing, if the playing was previously paused it will be resumed.
The shouldFade
parameter will be used only when resuming.
Stop playing.
Toggle play/pause.
Forcefully transit to the next track with fade-out effect.
-
time
is in seconds -
deckIndex
optional deck index, possible values are:0
,1
,2
-
fraction
Fraction of track's length.-
0
- Seek to the beginning. -
0.5
Seek to the middle of a track.
-
-
deckIndex
optional deck index, possible values are:0
,1
,2
-
deckIndex
deck index, possible values are:0
,1
,2
Returns an object
with:
-
current
(number?) - Current playing position -
duration
(number?) - Total duration -
first
(number?) - First audible position -
last
(number?) - Last audible position -
leading
(number?) - Fade-in position -
trailing
(number?) - Fade-out position -
cuePoint
(number?) -
transitionStart
(number?) -
transitionEnd
(number?)
-
deckIndex
index, possible values are:0
,1
,2
Returns Metadata for the specified deckIndex
Returns array
of object
describing an audio device type.
-
type
(string) - Device type -
isCurrent
(boolean) -true
if this device type is currently selected -
devices
(string[]) - List of devices of this type -
defaultDevice
(string) - Default device name of this type -
currentDevice
(string | undefined) - Currently selected device name of this type,undefined
if none
Get audio device currently being selected, returns undefined
if none.
If available, returns an object
with:
-
type
(string) - Device type -
device
(string) - Device name
Set audio device used for playback.
The descriptor
is an object
containing:
-
type
(string?) - Device type, if omitted, the currently selected device type is used -
device
(string?) - Device name, if omitted, the default
If both fields are omitted, this method does nothing.
Returns false
if the specified device cannot be used.
Returns true
if some device is selected.
Use getAudioDevice() to get the actual selected device.
Request for PCM audio data stream
options?
is an object
with:
-
sampleRate
(number) - Sample rate for the PCM data, if omitted, the default device's sample rate will be used -
format
- Audio sample format, possible values are:-
Int16LE
- 16 bit signed integer, little endian -
Int16BE
- 16 bit signed integer, big endian -
FloatLE
- 32 bit floating point, little endian -
FloatBE
- 32 bit floating point, big endian
-
-
bufferSize
(number) - Maximun frames the internal buffer can hold, increase this value helps reduce stuttering in some situations- Default value is 250ms (
deviceSampleRate
* 0.25)
- Default value is 250ms (
-
buffering
(number):- Number of frames to buffer before returning the buffered frames back to Node.js stream
- Reducing this value will cause the stream to pump faster
- Default value is 10ms (
deviceSampleRate
* 0.01)
-
gain
(number) - Output gain, a floating point number ranging from 0 to 1 -
fx
(object) - Effects parameter:-
karaoke
: Parameters for the karaoke effect, see setFx(type: 'karaoke', params)
-
Returns a Promise
of object
with:
-
id
(number) - The request id, use this value to update or delete the requested stream -
channels
(number) - Number of audio channels, This is usuaully2
-
originalSampleRate
(number) - Original sample rate in audio pipeline -
sampleRate
(number) - Sample rate as requested -
bitPerSample
(number) - Bit per sample, depending on theformat
-
16
- forInt16LE
ofInt16BE
-
32
- forFloatLE
ofFloatBE
-
-
stream
(Readable) - Readable stream, use this field to consume PCM data -
update
((options) => boolean) - Update this audio stream, theoptions
is the same as updateAudioStream(id, options) -
getLatency
() => number - Get the audio latency -
getFx
- See getFxCalling this method from this object only effects the corresponding stream, but does not effect the main output.
-
setFx
- See setFxCalling this method from this object only effects the corresponding stream, but does not effect the main output.
Update the requested audio stream specified by id
returned from requestAudioStream method.
options
is an object
with:
-
gain
(number) - Output gain, a floating point number ranging from 0 to 1 -
buffering
- See requestAudioStream -
fx
(object) - Effects parameter:-
karaoke
: Parameters for the karaoke effect, see setFx(type: 'karaoke', params)
-
Returns true
if succeeded.
Delete the requested audio stream specified by id
returned from requestAudioStream method.
Get all parameter values for the karaoke effect.
Returns an object
with:
-
enabled
(boolean) -
mix
(number) - Dry/Wet for the karaoke effect -
lowpassCutoff
(number) - Cut off frequency for the low pass filter -
lowpassQ
(number) - Quality factor for the low pass filter -
highpassCutoff
(number) - Cut off frequency for the high pass filter -
highpassQ
(number) - Quality factor for the high pass filter
Set karaoke effect parameters.
The params
is an object
with:
-
enabled
(boolean?) -
dontTransit
(boolean?) - Do not apply dry/wet mix transition while enabling/disabling the effect. Must be used with theenabled
property. -
mix
(number?) - Dry/Wet for the karaoke effect -
lowpassCutoff
(number?) - Cut off frequency for the low pass filter -
lowpassQ
(number?) - Quality factor for the low pass filter -
highpassCutoff
(number?) - Cut off frequency for the high pass filter -
highpassQ
(number?) - Quality factor for the high pass filter
Returns true
if succeeded.
Properties
Type: boolean
Read only
Returns true
if is playing, but not affected by the paused
property.
Type: boolean
Read only
Returns true
if is playing but has been paused.
Type: number
Audio volume in linear scale.
0
= Silent
1
= 0dBFS
Type: number
Minimum: 0
Maximum: 100
S-Curve value used for fading in/out.
Type: number
The maximum duration in seconds for the fade-out transition between tracks.
Type: number
The duration in seconds at the beginning of a track to be considered as having a long intro.
A track with a long intro will cause a fading-in to occur during transition.
Type: number
Default: 9.0
Gain (in dB) to boost for tracks having ReplayGain metadata embeded, default to 9.0dB.
If a track has no ReplayGain metadata, this value is ignored.
Read only
Returns an object
with:
-
left
- Left channel level -
right
- Right channel level
With each channel having:
-
magnitude
(number) - Audio level -
peak
(number) - Holding peak
Read only
Returns audio reduction level in dB
Audio reduction occur during the internal audio processing
Events
Parameters:
-
deckIndex
(number) - Deck index in which the event occur -
trackPlay
- An object describing detail of the play session for the Deck.-
uuid
(string) - A unique string identifying thetrackPlay
itself -
track
- Track, see TrackInfo -
duration
(number) - Track duration
-
Emits when a track has been loaded into a Deck.
Emits when a track has been loaded into a Deck.
Emits when a track has been unloaded from a Deck.
Emits when a Deck has started playing.
Emits when a Deck has finished playing.
Emits when a Deck become the main playing Deck.
Emits when the playing queue is exhausted and need to be filled.
See Dynamic quque
Parameter:
-
done
- Call this function in the event handler withtrue
value to informnode-medley
that at least a track has been added to the queue and should be loaded.
Emits when the audio device has changed, use getAudioDevice method to get the audio device.
Emits when a log message has been pushed from the native module.
Logging must be enabled when constructing the Medley instance, see Medley class options
Parameter:
-
level
(number) - Log levelname value trace -1 debug 0 info 1 warn 2 error 3 fatal 4 -
name
(string) - The logger's name -
msg
(string) - Log message
Static methods
Returns an object
containing information about node-medley
-
runtime
:-
file
- Node native module file name -
runtime
- Runtime name -
napi
-node-addon-api
version
-
-
version
-node-medley
version number -
juce
- Detail for the JUCE framework library being linked intonode-medley
version
-
cpu
-
intel
- Intel CPU -
arm
- ARM CPU -
arm64
- ARM64 CPU -
aarch64
- ARM64 CPU -
sse
- SIMD supports on x84_64 CPU -
neon
- SIMD supports on ARM CPU -
vdsp
- vDSP supports on macOS
-
Returns true
if the track
can be loaded and played.
Returns Metadata for path
Returns AudioProperties for path
Please note that this function may scan the whole file in order to get a good result.
Returns an object
with:
-
cover
(Buffer) - Cover art data -
coverMimeType
(string) - Cover art mime type -
lyrics
(string) - Raw lyrics data
The queue class provides tracks list to the Medley class.
Constructor
Create a new instance of the Queue
class, an optional tracks
is an array of tracks to initially fill the queue.
The Queue
class is dead simple, if you need more control over your tracks list, you must manage the list by yourself and provide a track when the Medley
object requires one, see enqueueNext event
Methods
Add a track to the queue, see TrackInfo
Add list of tracks to the queue, see TrackInfo
Insert track(s) at position specified by the index
parameter.
Delete tracks(s) specified by count
starting from index
.
Swap track.
Move a track to the new location.
Get the track at index
Set the track at index
Returns a new shallow copy of all tracks.
Properties
Returns total number of tracks in the queue.
A TrackInfo
can be either a string
to file path, or an object
with:
-
path
(string) - file path -
cueInPosition
(number?) - Start position of the track -
cueOutPosition
(number?) - Stop position of the track -
disableNextLeadIn
(boolean?)- Disable lead-in of the next track, useful for transiting from jingle/sweeper
- The lead-in is the position where it is considered as the start singing point, usually presented in a track which has smooth/long beginning.
-
title
(string?) -
artist
(string?) -
album
(string?) -
isrc
(string?) - International Standard Recording Code -
albumArtist
(string?) -
originalArtist
(string?) -
trackGain
(number?) - ReplayGain value in dB (decibels),0
means noReplayGain
value for this track -
bpm
(number?) - Beats Per Minute -
comments
([string, string][]) - List of key/value pair for all user-defined comments
-
bitrate
(number?) - in Kbps -
sampleRate
(number?) - in Hz -
duration
(number?) - in seconds
Demo music from Bensound.com