\r\n\r\n[Become a sponsor](https://github.com/sponsors/naomiaro)\r\n\r\n# Waveform Playlist\r\n\r\nInspired by [Audacity](http://audacity.sourceforge.net/), this project is a multiple track playlist editor written in ES2015 using the [Web Audio API](http://webaudio.github.io/web-audio-api/).\r\n\r\nLoad tracks and set cues (track cue in, cue out), fades (track fade in, fade out) and track start/end times within the playlist.\r\nI've written up some demos on github for the different [audio fade types](https://github.com/naomiaro/Web-Audio-Fades) in the project.\r\n\r\n- [See examples in action](http://naomiaro.github.io/waveform-playlist)\r\n- [Try out the waveform editor!](http://naomiaro.github.io/waveform-playlist/web-audio-editor.html)\r\n\r\n![Screenshot](img/stemtracks.png?raw=true \"stem tracks mute solo volume control\")\r\n(code for picture shown can be found in ghpages/\\_examples/04stemtracks.html)\r\n\r\n![Screenshot](img/annotations.png?raw=true \"Aeneas annotations adjust alignment json export\")\r\n(code for picture shown can be found in ghpages/\\_examples/13annotations.html)\r\n\r\n## Browser Support\r\n\r\nWaveform Playlist requires webaudio in the browser to function correctly: [Can I Use?](http://caniuse.com/#search=webaudio)\r\n\r\n## Installation\r\n\r\n`npm install waveform-playlist --save`\r\n\r\nHate npm? Check Unpkg: https://unpkg.com/browse/waveform-playlist/\r\n\r\n- If you want to download and run the already compiled website, navigate to folder `/dist` and run `python -m SimpleHTTPServer 8000`. The website will be available at `localhost:8000/waveform-playlist`.\r\n\r\n## Basic Usage\r\n\r\nhttps://github.com/naomiaro/waveform-playlist/blob/main/examples/basic-html/\r\n\r\nhttps://github.com/naomiaro/waveform-playlist/tree/main/examples/basic-express/\r\n\r\n```javascript\r\nimport WaveformPlaylist from \"waveform-playlist\";\r\n\r\nvar playlist = WaveformPlaylist({\r\n samplesPerPixel: 3000,\r\n mono: true,\r\n waveHeight: 70,\r\n container: document.getElementById(\"playlist\"),\r\n state: \"cursor\",\r\n colors: {\r\n waveOutlineColor: \"#E0EFF1\",\r\n timeColor: \"grey\",\r\n fadeColor: \"black\",\r\n },\r\n controls: {\r\n show: false,\r\n width: 150,\r\n },\r\n zoomLevels: [500, 1000, 3000, 5000],\r\n});\r\n\r\nplaylist\r\n .load([\r\n {\r\n src: \"media/audio/Vocals30.mp3\",\r\n name: \"Vocals\",\r\n gain: 0.5,\r\n },\r\n {\r\n src: \"media/audio/BassDrums30.mp3\",\r\n name: \"Drums\",\r\n start: 8.5,\r\n fadeIn: {\r\n duration: 0.5,\r\n },\r\n fadeOut: {\r\n shape: \"logarithmic\",\r\n duration: 0.5,\r\n },\r\n },\r\n {\r\n src: \"media/audio/Guitar30.mp3\",\r\n name: \"Guitar\",\r\n start: 23.5,\r\n fadeOut: {\r\n shape: \"linear\",\r\n duration: 0.5,\r\n },\r\n cuein: 15,\r\n },\r\n ])\r\n .then(function () {\r\n // can do stuff with the playlist.\r\n });\r\n```\r\n\r\n### Playlist Options\r\n\r\n```javascript\r\nvar options = {\r\n // webaudio api AudioContext\r\n ac: new (window.AudioContext || window.webkitAudioContext)(),\r\n\r\n // DOM container element REQUIRED\r\n container: document.getElementById(\"playlist\"),\r\n\r\n // sample rate of the project. (used for correct peaks rendering)\r\n sampleRate: new (\r\n window.AudioContext || window.webkitAudioContext\r\n ).sampleRate(),\r\n\r\n // number of audio samples per waveform peak.\r\n // must be an entry in option: zoomLevels.\r\n samplesPerPixel: 4096,\r\n\r\n // whether to draw multiple channels or combine them.\r\n mono: true,\r\n\r\n // enables \"exclusive solo\" where solo switches between tracks\r\n exclSolo: false,\r\n\r\n // default fade curve type.\r\n fadeType: \"logarithmic\", // (logarithmic | linear | sCurve | exponential)\r\n\r\n // whether or not to include the time measure.\r\n timescale: false,\r\n\r\n // control panel on left side of waveform\r\n controls: {\r\n // whether or not to include the track controls\r\n show: false,\r\n\r\n // width of controls in pixels\r\n width: 150,\r\n\r\n // whether to render the widget or not in the controls panel.\r\n widgets: {\r\n // Mute & solo button widget\r\n muteOrSolo: true,\r\n\r\n // Volume slider\r\n volume: true,\r\n\r\n // Stereo pan slider\r\n stereoPan: true,\r\n\r\n // Collapse track button\r\n collapse: true,\r\n\r\n // Remove track button\r\n remove: true,\r\n },\r\n },\r\n\r\n colors: {\r\n // color of the wave background\r\n waveOutlineColor: \"white\",\r\n\r\n // color of the time ticks on the canvas\r\n timeColor: \"grey\",\r\n\r\n // color of the fade drawn on canvas\r\n fadeColor: \"black\",\r\n },\r\n\r\n // height in pixels of each canvas element a waveform is on.\r\n waveHeight: 128,\r\n\r\n // width in pixels of waveform bars.\r\n barWidth: 1,\r\n\r\n // spacing in pixels between waveform bars.\r\n barGap: 0,\r\n\r\n // interaction state of the playlist\r\n // (cursor | select | fadein | fadeout | shift)\r\n state: \"cursor\",\r\n\r\n // (line | fill)\r\n seekStyle: \"line\",\r\n\r\n // Array of zoom levels in samples per pixel.\r\n // Smaller numbers have a greater zoom in.\r\n zoomLevels: [512, 1024, 2048, 4096],\r\n\r\n // Whether to automatically scroll the waveform while playing\r\n isAutomaticScroll: false,\r\n\r\n // configuration object for the annotations add on.\r\n annotationList: {\r\n // Array of annotations in [Aeneas](https://github.com/readbeyond/aeneas) JSON format\r\n annotations: [],\r\n\r\n // Whether the annotation texts will be in updateable contenteditable html elements\r\n editable: false,\r\n\r\n // User defined functions which can manipulate the loaded annotations\r\n controls: [\r\n {\r\n // class names for generated tag separated by '.'\r\n class: \"fa.fa-minus\",\r\n\r\n // title attribute for the generated tag\r\n title: \"Reduce annotation end by 0.010s\",\r\n\r\n // function which acts on the given annotation row\r\n // when the corresponding is clicked.\r\n action: (annotation, i, annotations, opts) => {\r\n // @param Object annotation - current annotation\r\n // @param Number i - index of annotation\r\n // @param Array annotations - array of annotations in the playlist\r\n // @param Object opts - configuration options available\r\n // - opts.linkEndpoints\r\n },\r\n },\r\n ],\r\n\r\n // If false when clicking an annotation id segment\r\n // playback will stop after segment completion.\r\n isContinuousPlay: false,\r\n\r\n // If true annotation endpoints will remain linked when dragged\r\n // if they were the same value before dragging started.\r\n linkEndpoints: false,\r\n\r\n // pass a custom function which will receive the mastergainnode for this playlist and the audio context's destination.\r\n // if you pass a function, you must connect these two nodes to hear sound at minimum.\r\n // if you need to clean something up when the graph is disposed, return a cleanup function. Waveform Playlist will cleanup the nodes passed as arguments.\r\n effects: function (masterGainNode, destination, isOffline) {\r\n // analyser nodes don't work offline.\r\n if (!isOffline) masterGainNode.connect(analyser);\r\n masterGainNode.connect(destination);\r\n\r\n // return function cleanup() {\r\n // // if you create webaudio nodes that need to be cleaned up do that here\r\n // // see the track effects example.\r\n // };\r\n },\r\n },\r\n};\r\n```\r\n\r\n### Track Options\r\n\r\n```javascript\r\n{\r\n // a media path for XHR, a Blob, a File, or an AudioBuffer object.\r\n src: 'media/audio/BassDrums30.mp3',\r\n\r\n // name that will display in the playlist control panel.\r\n name: 'Drums',\r\n\r\n // volume level of the track between [0-1]\r\n gain: 1,\r\n\r\n // whether the track should initially be muted.\r\n muted: false,\r\n\r\n // whether the track should initially be soloed.\r\n soloed: false,\r\n\r\n // time in seconds relative to the playlist\r\n // ex (track will start after 8.5 seconds)\r\n // DEFAULT 0 - track starts at beginning of playlist\r\n start: 8.5,\r\n\r\n // track fade in details\r\n fadeIn: {\r\n // fade curve shape\r\n // (logarithmic | linear | sCurve | exponential)\r\n shape: 'logarithmic',\r\n\r\n // length of fade starting from the beginning of this track, in seconds.\r\n duration: 0.5,\r\n },\r\n\r\n // track fade out details\r\n fadeOut: {\r\n // fade curve shape\r\n // (logarithmic | linear | sCurve | exponential)\r\n shape: 'logarithmic',\r\n\r\n //length of fade which reaches the end of this track, in seconds.\r\n duration: 0.5,\r\n }\r\n\r\n // where the waveform for this track should begin from\r\n // ex (Waveform will begin 15 seconds into this track)\r\n // DEFAULT start at the beginning - 0 seconds\r\n cuein: 15,\r\n\r\n // where the waveform for this track should end\r\n // ex (Waveform will end at 30 second into this track)\r\n // DEFAULT duration of the track\r\n cueout: 30,\r\n\r\n // custom class for unique track styling\r\n customClass: 'vocals',\r\n\r\n // custom background-color for the canvas-drawn waveform\r\n waveOutlineColor: '#f3f3f3',\r\n\r\n // interaction states allowed on this track.\r\n // DEFAULT - all true\r\n states: {\r\n cursor: true,\r\n fadein: true,\r\n fadeout: true,\r\n select: true,\r\n shift: true,\r\n },\r\n\r\n // pre-selected section on track.\r\n // ONLY ONE selection is permitted in a list of tracks, will take most recently set if multiple passed.\r\n // This track is marked as 'active'\r\n selected: {\r\n // start time of selection in seconds, relative to the playlist\r\n start: 5,\r\n\r\n // end time of selection in seconds, relative to the playlist\r\n end: 15,\r\n },\r\n\r\n // value from -1 (full left pan) to 1 (full right pan)\r\n stereoPan: 0,\r\n\r\n // pass a custom function which will receive the last graphnode for this track and the mastergainnode.\r\n // if you pass a function, you must connect these two nodes to hear sound at minimum.\r\n // if you need to clean something up when the graph is disposed, return a cleanup function. Waveform Playlist will cleanup the nodes passed as arguments.\r\n effects: function(graphEnd, masterGainNode, isOffline) {\r\n var reverb = new Tone.Reverb(1.2);\r\n\r\n Tone.connect(graphEnd, reverb);\r\n Tone.connect(reverb, masterGainNode);\r\n\r\n return function cleanup() {\r\n reverb.disconnect();\r\n reverb.dispose();\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Playlist Events\r\n\r\nWaveform Playlist uses an instance of [event-emitter](https://www.npmjs.com/package/event-emitter) to send & receive messages from the playlist.\r\n\r\n```javascript\r\nimport EventEmitter from \"event-emitter\";\r\nimport WaveformPlaylist from \"waveform-playlist\";\r\n\r\nvar playlist = WaveformPlaylist(\r\n {\r\n container: document.getElementById(\"playlist\"),\r\n },\r\n\r\n // you can pass your own event emitter\r\n EventEmitter()\r\n);\r\n\r\n// retrieves the event emitter the playlist is using.\r\nvar ee = playlist.getEventEmitter();\r\n```\r\n\r\nAn example of using the event emitter to control the playlist can be found in [/dist/js/examples/emitter.js](https://github.com/naomiaro/waveform-playlist/blob/main/dist/waveform-playlist/js/emitter.js)\r\n\r\n#### Events to Invoke\r\n\r\n| event | arguments | description |\r\n| --------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| `play` | `start:optional, end:optional` | Starts playout of the playlist. Takes optional Number parameters in seconds `start` and `end` to play just an audio segment. `start` can be passed without an `end` to play to the end of the track. |\r\n| `pause` | _none_ | Pauses playout of the playlist. |\r\n| `stop` | _none_ | Stops playout of the playlist. |\r\n| `rewind` | _none_ | Stops playout if playlist is playing, resets cursor to the beginning of the playlist. |\r\n| `fastforward` | _none_ | Stops playout if playlist is playing, resets cursor to the end of the playlist. |\r\n| `clear` | _none_ | Stops playout if playlist is playing, removes all tracks from the playlist. |\r\n| `record` | _none_ | Starts recording an audio track. Begins playout of other tracks in playlist if there are any. |\r\n| `zoomin` | _none_ | Changes zoom level to the next smallest entry (if one exists) from the array `zoomLevels`. |\r\n| `zoomout` | _none_ | Changes zoom level to the next largest entry (if one exists) from the array `zoomLevels`. |\r\n| `trim` | _none_ | Trims currently active track to the cursor selection. |\r\n| `statechange` | `cursor` / `select` / `fadein` / `fadeout` / `shift` | Changes interaction state to the state given. |\r\n| `fadetype` | `logarithmic` / `linear` / `sCurve` / `exponential` | Changes playlist default fade type. |\r\n| `newtrack` | `File` | Loads `File` object into the playlist. |\r\n| `volumechange` | `volume, track` | Set volume of `track` to `volume` (0-100) |\r\n| `mastervolumechange` | `volume` | Set a new master volume `volume` (0-100) |\r\n| `select` | `start, end, track:optional` | Seek to the start time or start/end selection optionally with active track `track`. |\r\n| `startaudiorendering` | `wav` / `buffer` | Request for a downloadable file or web Audio buffer that represent the current work |\r\n| `automaticscroll` | `true`/`false` | Change property `isAutomaticScroll`. |\r\n| `continuousplay` | `true`/`false` | Change property `isContinuousPlay`. |\r\n| `linkendpoints` | `true`/`false` | Change property `linkEndpoints`. |\r\n| `annotationsrequest` | _none_ | Requests to download the annotations to a json file. |\r\n| `stereopan` | `panvalue, track` | Set pan value of `track` to `panvalue` (-1-1) |\r\n\r\n#### Events to Listen to\r\n\r\n| event | arguments | description |\r\n| ------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| `select` | `start, end, track` | Cursor selection has occurred from `start` to `end` with active Track `track`. |\r\n| `timeupdate` | `playbackPosition` | Sends current position of playout `playbackPosition` in seconds. |\r\n| `scroll` | `scrollLeft` | Sends current position of scroll `scrollLeft` in seconds. |\r\n| `statechange` | `state` | Sends current interaction state `state`. |\r\n| `shift` | `deltaTime, track` | Sends `deltaTime` in seconds change for Track `track` |\r\n| `mute` | `track` | Mute button has been pressed for `track` |\r\n| `solo` | `track` | Solo button has been pressed for `track` |\r\n| `removeTrack` | `track` | Remove button has been pressed for `track` |\r\n| `changeTrackView` | `track, opts` | Collapse button has been pressed for `track` |\r\n| `volumechange` | `volume, track` | Volume of `track` has changed to `volume` (0-100) |\r\n| `mastervolumechange` | `volume` | Master volume of the playlist has changed to `volume` (0-100) |\r\n| `audiorequeststatechange` | `state, src` | Loading audio `src` (`string` or `File`) is now in state [`state`](https://github.com/naomiaro/waveform-playlist/wiki/Track-Loading-States) (Number) |\r\n| `loadprogress` | `percent, src` | Loading audio `src` has loaded percent `percent` (0-100) |\r\n| `audiosourcesloaded` | _none_ | Audio decoding has finished for all tracks |\r\n| `audiosourcesrendered` | _none_ | Tracks are rendered to the playlist |\r\n| `audiosourceserror` | `err` | Error thrown while loading tracks |\r\n| `finished` | _none_ | Event fired when cursor ( while playing ) reaches the end (maximum duration) |\r\n| `audiorenderingstarting` | `offlineCtx, setUpPromiseArray` | Event fired after the OfflineAudioContext is created before any rendering begins. If any setup is async before offline redering, push a promise to the setUpPromiseArray. |\r\n| `audiorenderingfinished` | `type, data` | Return the result of the rendering in the desired format. `type` can be `buffer` or `wav` and can be used to dertermine the `data` type. When `type` is `wav`, data is a `blob` object that represent the wav file. |\r\n| `stereopan` | `panvalue, track` | Pan value of `track` has been changed to `panvalue` |\r\n\r\n## Tests\r\n\r\n`npm test`\r\n\r\n## Development without example changes\r\n\r\n`npm install && npm start`\r\n\r\nThis will install dependencies and start the webpack server.\r\n\r\n## Development with example changes\r\n\r\n`gem install jekyll`\r\n\r\nJekyll is needed if changes to the example pages will be done.\r\n\r\n`npm install && npm run dev`\r\n\r\nThis will build and watch the jekyll site and startup the webpack dev server.\r\n\r\n## Credits\r\n\r\nOriginally created for the [Airtime](https://www.sourcefabric.org/software/airtime/) project at [Sourcefabric](https://www.sourcefabric.org/)\r\n\r\nThe annotation plugin has been sponsored by a fond Italian TED volunteer transcriber hoping to make the transcription process of TEDx talks easier and more fun.\r\n\r\n## Books\r\n\r\nCurrently writing: [Mastering Tone.js](https://leanpub.com/masteringtonejs). Get notified by Leanpub when I publish.\r\n\r\n\r\n\r\n## License\r\n\r\n[MIT License](http://doge.mit-license.org)\r\n","readmeFilename":"README.md"}
![](\"https://raw.githubusercontent.com/naomiaro/waveform-playlist/main/ghpages/img/logos/moises-ai.svg\")
\r\n \r\n![](\"https://naomiaro.github.io/img/masteringtonejs.png\" "\\"Mastering")
\r\n\r\n## License\r\n\r\n[MIT License](http://doge.mit-license.org)\r\n","readmeFilename":"README.md"}