- wave.js Documentation
To get started using wave.js, install the npm package:
npm i @wave.js/wave.js</code>wave.js is a Node.js-based server with functionality to configure and customize live streams. To set up a wave.js server:
- Include the WaveJS module:
const WaveJS = require(‘@wave.js/wave.js’);- Create a new instance of a WaveJS server:
const server = new WaveJS();wave.js features a range of functions to tailor live streams to any development environment. Once you've created a new instance of a wave.js server, you can use the following built-in functions to configure and control live streams. Included are options to start and stop your server, add event listeners, configure input and output settings, and update the media directory where streams are saved:
- Update AV Settings
- Update Output Protocol
- Update HLS Output
- Update MPD Output
- Update Output Settings
- Update Media Directory
Before you start streaming, configure your audio/video output settings to meet the needs of your project. The default configuration options are as follows:
const AVConfig = {
videoCodec: 'libx264',
videoBitrate: '1200k',
audioBitrate: '256k',
audioCodec: 'aac',
audioChannels: 2,
aspectRatio: undefined,
frameRate: undefined,
h264Preset: 'superfast',
}To customize your A/V output:
- Create a new object with any updated settings. Note that all other options not included in the config object will retain their default settings:
const updatedSettings = {
videoBitrate: '1000K',
h264Preset: 'medium'
}- The updateAVSettings method accepts a single config object as its parameter. Invoke the updateAVSettings method and pass in the updated config object as an argument:
server.updateAVSettings(updatedSettings);wave.js currently supports output for HLS and MPEG-DASH streaming protocols. Users can select to output live streams in HLS, MPEG-DASH, or both concurrently:
- Output HLS:
jsserver.updateOutputProtocol('hls'); - Output MPEG-DASH:
server.updateOutputProtocol('dash'); - Output HLS and MPEG-DASH:
server.updateOutputProtocol('hls', 'dash')
The following HLS output options can be configured for your live stream, as provided by Ffmpeg video processing. For more information on each option, read the FFmpeg Format Documentation.
- hlsInitTime
- hlsTime
- hlsListSize
- hlsDeleteThreshold
- hlsStartNumberSource
- startNumber
- hlsAllowCache
- hlsBaseUrl
- hlsSegmentFilename
- strftime
- strftimeMkdir
- hlsSegmentOptions
- hlsKeyInfoFile
- hlsEnc
- hlsEncKey
- hlsEncKeyUrl
- hlsEncIv
- hlsSegmentType
- hlsFmp4InitFilename
- hlsFmp4InitResend
- hlsFlags
- hlsPlaylistType
- method
- httpUserAgent
- varStreamMap
- ccStreamMap
- masterPlName
- masterPlPublishRate
- httpPersistent
- timeout
- ignoreIoErrors
- headers
The default HLS output settings for wave.js are:
- hlsTime: 1
- hlsListSize: 1
To configure your HLS output:
- Create a new object with any updated settings. Note that all other options not included in the config object will retain their default settings:
const updatedSettings = {
hlsStartNumberSource: 'datetime',
hlsListSize: 0,
hlsPlaylistType: 'event'
};-
The updateHLSOutput method accepts a single config object as its parameter. Invoke the updateHLSOutput method and pass in the updated config object as an argument:
server.updateHLSOutput(updatedSettings)
The following MPEG-DASH output options can be configured for your live stream, as provided by Ffmpeg video processing. For more information on each option, read the FFmpeg Format Documentation.
- segDuration
- fragDuration
- fragType
- windowSize
- extraWindowSize
- removeAtExit
- useTemplate
- useTimeline
- singleFile
- singleFileName
- initSegName
- mediaSegName
- utcTimingUrl
- method
- httpUserAgent
- httpPersistent
- hlsPlaylist
- hlsMasterName
- streaming
- adaptationSets
- timeout
- indexCorrection
- formatOptions
- globalSidx
- dashSegmentType
- ignoreIoErrors
- lhls
- ldash
- masterM3u8PublishRate
- writePrft
- mpdProfile
- httpOpts
- targetLatency
- minPlaybackRate
- maxPlaybackRate
- updatePeriod
The default MPEG-DASH output settings for wave.js are:
- segDuration: 8
- fragDuration: 1
- initSegName:
init_$RepresentationID$.m4s - mediaSegName:
chunk*$RepresentationID$*$Number%05d$.m4s - streaming: true
- ldash: true
To configure your MPEG-DASH output:
- Create a new object with any updated settings. Note that all other options not included in the config object will retain their default settings:
const updatedSettings = {
segDuration: 10,
deshSegmentType: 'mp4',
writePrft: true,
targetLatency: 10,
}-
The updateMPDOutput method accepts a single config object as its parameter. Invoke the updateMPDOutput method and pass in the updated config object as an argument:
server.updateMPDOutput(updatedSettings)
The default output server port is 3000 and the default endpoint is 'wavejs':
To update the server port or endpoint, invoke the updateOutputSettings method and pass in a custom port (number) and/or a custom endpoint (string):
server.updateOutputSettings(5555, 'newEndpoint')
By default, wave.js stores video files in a 'videoFiles' directory in the current working directory. To set a custom directory name to store all streaming files, invoke the updateMediaDir() method and pass in the new directory name (string) as an argument.
server.updateMediaDir('mediaDirectory')
wave.js features an event emitter that invokes callback functions when the following events are fired:
- audio
- video
- metadata
- connect
- publish
- close
- disconnect
Create custom event handlers for the previous events that are tailored to your workflow. The 'on' method invokes the callback function every time an event occurs, and the 'once' method invokes the listener the first time the event occurs. Use the following formats:
server.on(event, callback)
server.once(event, callback)
Code Example:
streamStorage.events.on('disconnect', () => {
writeSocket.destroy();
console.log(`${streamKey} streaming session ended.`)
});Once you've configured your wave.js server, you're ready to start streaming. To start wave.js, invoke the listen method. This boots up the output server (default port 3000) and the RTMP server (default port 1935).
server.listen();To stop wave.js, invoke the close method:
server.close()wave.js serves live streams and video files for on-demand playback. The default locations to access files are provided below. Ensure you replace ${streamKey} with the user stream key and provide the ${streamId} produced during recording if using the playback endpoint.
Live Streams
http://localhost:3000/wavejs/live/${streamKey}/manifest.m3u8
Video Files for Playback
http://localhost:3000/wavejs/playback/${streamKey}/${streamId}/manifest.m3u8
View the demo repo to see how streams are accessed and served by a video player in React.
To stream real-time RTMP from OBS Studio, use the following settings. Note that the Stream Key is required and should be unique for every end user.
wave.js features built-in logging to track and monitor live stream progress and performance in real-time, including connected ports, current stream path and progress, warnings, and errors. The following log levels are available as methods that can be invoked with the Logger module:
- error
- warn
- info
- http
- rtmp
- debug
To create custom logs:
-
Include the
logger.jsmodule:const Logger = require(‘@wave.js/wave.js’) -
Invoke the desired method:
Logger.info('New stream ${streamKey} is live.')
Code Example:
const port = 8000;
const app = express();
app.listen(port, () => {
Logger.info('Listening on port ', port);
});View the wave.js demo site repository on GitHub as an example of a React application using wave.js.
View a code example of a project server that uses wave.js
const express = require('express');
const path = require('path');
const { WaveJS, Logger } = require('@wave.js/wave.js');
const app = express();
const server = new WaveJS();
const port = 8000;
app.use(express.static(path.join(__dirname, '../../dist')));
app.use(express.static(path.join(__dirname, '../frontend')));
server.updateMediaDir(path.join(__dirname, 'media'));
server.updateOutputProtocol('hls');
server.updateHLSOutput({ hlsListSize: 0 });
server.updateOutputSettings({ endpoint: 'wavejs', port: 3000 });
server.listen();
app.listen(port, () => {
Logger.info('Listening on port ', port);
});