{"_id":"@bbmail-click/cordova-plugin-nativeaudio","_rev":"1-1f74761add4f9120a6a4d9523338f196","name":"@bbmail-click/cordova-plugin-nativeaudio","dist-tags":{"latest":"3.1.2"},"versions":{"3.1.2":{"name":"@bbmail-click/cordova-plugin-nativeaudio","version":"3.1.2","description":"Cordova/PhoneGap Plugin for low latency Native Audio Playback, must have for HTML5 games","cordova":{"id":"cordova-plugin-nativeaudio","platforms":["android","ios"]},"repository":{"type":"git","url":"git+https://github.com/rastafan/cordova-plugin-nativeaudio.git"},"bugs":{"url":"https://github.com/rastafan/cordova-plugin-nativeaudio/issues"},"keywords":["cordova","ecosystem:cordova","music","audio","game","mp3","rjfun","rastafan"],"author":{"name":"Andrew Trice"},"contributors":[{"name":"Andrew Trice"},{"name":"Raymond Xie","email":"rjfun.mobile@gmail.com"},{"name":"Sidney Bofah"},{"name":"Rastafan"}],"license":"MIT","gitHead":"1ed4b29fe129f2a77d9c6ff1a22f356d054f85f9","homepage":"https://github.com/rastafan/cordova-plugin-nativeaudio#readme","_id":"@bbmail-click/cordova-plugin-nativeaudio@3.1.2","_nodeVersion":"12.16.2","_npmVersion":"6.14.4","dist":{"integrity":"sha512-s1KDo8tgegkjgKEHBlEuwLgxvpVFA9fluKvI7tH4o8E36Hm+xJ0MIBbOYNmTpLZWLqpivWM7+/JQjpRRpyYMIw==","shasum":"a55ed333351a0ac6c3e8a1a6167582650946a5d3","tarball":"https://registry.npmjs.org/@bbmail-click/cordova-plugin-nativeaudio/-/cordova-plugin-nativeaudio-3.1.2.tgz","fileCount":32,"unpackedSize":2269363,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgHZFTCRA9TVsSAnZWagAAUNYP/jFP3/jevhI0dKiaXsv8\n1wYuOBczlSskO3HIucTtmtPx5zGrHwiVftnCdVuXteW/cHfrKniBjTUbQ4GJ\nsiAmmxkJQx+cVwf035Cen2/2aoXHsKg0Kc46WdryybCOVHmmsbbzPzTt7eNY\nh/SoOHak3F/0UQ7V0KFgce5zFmpTBtVyDTF9G20NpJTZMYyIXFb4bfq5AtNj\n4Jb5CiEJkCwvF784uILqonsH1dEeOM0nEhoAKA+tBaUZae3O1MBjmd3EXCPQ\nU4nGuz6MnKE/aC3wvz4pfkewPzZCBynS70gezIIHqyeJE8pO0vHBOUT5pDoF\nAtsCixnAjeHv48lGM+dl7UU+jw+jiDyHrS0J1i/BCOExnnoOjWpdeiFovzfr\n39+d34pFjX2CxSzuHKbo2cdwNYIUIHZu5u476GD1NFGzc06NgKSMUkN84Pqt\n8lFKmTbE0fBFjEAOdaaLV+kFXCVrqv0BGJoko02fwf+fyfCIoRELERT4gfsV\nYWCptohTj2XUmK2YO0Z0UiW9vErC9V29O+a8V0tLCawAP2RJWjiOP/+ooj3g\n1Sq2Wm3mME0YbdlIsyJFvrBjhlzi8vf820xHFECI/JjwLvjWpqxuiNIo9kUy\nPRc+iMz7Iu9tnWFDk9jFleZltaKPouTqLVw7MuWwCh7AQdwVZ92J0CtUqSHS\nsRJK\r\n=OhYK\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQD2JztSP9gIUFnJX1lwkZtapwrfT63T3JYsHA1SAqIIqQIhAPNxSa9R57z8cLQWC/1xdoXZ0JA0yWJT+Si8Pa3CXTgH"}]},"_npmUser":{"name":"bbmail-click","email":"begim@mail-click.net"},"directories":{},"maintainers":[{"name":"bbmail-click","email":"begim@mail-click.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/cordova-plugin-nativeaudio_3.1.2_1612550483425_0.8239698697341262"},"_hasShrinkwrap":false}},"time":{"created":"2021-02-05T18:41:23.374Z","3.1.2":"2021-02-05T18:41:23.655Z","modified":"2022-04-04T18:00:33.403Z"},"maintainers":[{"name":"bbmail-click","email":"begim@mail-click.net"}],"description":"Cordova/PhoneGap Plugin for low latency Native Audio Playback, must have for HTML5 games","homepage":"https://github.com/rastafan/cordova-plugin-nativeaudio#readme","keywords":["cordova","ecosystem:cordova","music","audio","game","mp3","rjfun","rastafan"],"repository":{"type":"git","url":"git+https://github.com/rastafan/cordova-plugin-nativeaudio.git"},"contributors":[{"name":"Andrew Trice"},{"name":"Raymond Xie","email":"rjfun.mobile@gmail.com"},{"name":"Sidney Bofah"},{"name":"Rastafan"}],"author":{"name":"Andrew Trice"},"bugs":{"url":"https://github.com/rastafan/cordova-plugin-nativeaudio/issues"},"license":"MIT","readme":"# Cordova Native Audio Plugin\n\nCordova / PhoneGap 3.5+ extension for Native Audio playback, aimed at HTML5 gaming and audio applications which require minimum latency, polyphony and concurrency.\n\n## Contents\n\n1. [Description](#description)\n2. [History](#history)\n3. [Roadmap](#next-steps)\n5. [Integration](#integration)\n7. [Supported Platforms](#supported-platforms)\n8. [Installation](#installation)\n9. [Usage](#usage)\n10. [API](#api)\n11. [Demo](#demo)\n12. [Example](#example)\n\n## Description\n\nThis Cordova / PhoneGap (3.5+) plugin enables concurrency (multi-channel playback) and minimized latency (via caching) in audio-based applications, by leveraging native audio APIs. Designed for the use in HTML5-based cross-platform games and mobile/hybrid audio applications.\n\n## History\n\nThis plugin is a fork of [this plugin](https://github.com/floatinghotpot/cordova-plugin-nativeaudio), which in turn is a community-driven, clean fork of the Low Latency Audio Plugin for Cordova / PhoneGap, initially published by [Andrew Trice](http://www.tricedesigns.com/2012/01/25/low-latency-polyphonic-audio-in-phonegap/) and then maintained by [Raymond Xie](http://github.com/floatinghotpot/) and [Sidney Bofah](https://github.com/SidneyS/).\n\nIn addition to the clean-up of legacy code and callbacks, this fork uses AVPlayer for iOS, fixes some caveats with the original project, and can reproduce streaming audio from http/https.\n\nAlso, Media Controls are integrated to control audio flow from outside the app. Media Controls have been integrated using the code of [this plugin by ghenry22 and homerours](https://github.com/ghenry22/cordova-plugin-music-controls2). Thank you!\n\n## Roadmap\n\nFollowing the Cordova philosophy, this is a shim for a web audio implementation (on mobile) which is as fast and feature-rich as native mobile APIs. Currently, neither HTML5 Audio or the more recent Web Audio API offer a cross-platform solution which 1) is fast, 2) supports concurrency and 3) maintains a low overhead.\n\nIt should be replaced by a standardised W3C solution as soon as such an implementation offers comparable performance across (mobile) devices, which is crucial for HTML5-based games.\n\n## Integration\n\nThis plugin is available as an AngularJS service module, facilitating the usage in AngularJS-based Cordova/PhoneGap projects.\n\nIt extends the ngCordova project, an effort by the great guys at [Drifty](http://github.com/driftyco), creators of the Ionic Framework.\nDownload it at the ngCordova [website](http://www.ngcordova.com) or the [repository](http://www.github.com/driftyco/ng-cordova).\n\n## Supported Platforms\n\n* iOS (tested with 10, 11, 13)\n* Android (tested in API levels 26 - 27 - 28)\n\n## Installation\n\nVia Cordova CLI:\n```bash\ncordova plugin add cordova-plugin-nativeaudio\n```\n\n##Usage\n\n\n1. Wait for `deviceReady`.\n1. Preload an audio asset and assign an id - either optimized for single-shot style short clips (`preloadSimple()`) or looping, ambient background audio (`preloadComplex()`)\n2. `play()` the audio asset via its id.\n3. `unload()` the audio asset via its id.\n\n##API\n\n###Preloading\n\n```javascript\npreloadSimple: function ( id, assetPath, successCallback, errorCallback)\n```\nLoads an audio file into memory. Optimized for short clips / single shots (up to five seconds).\nCannot be stopped / looped.\n\nUses lower-level native APIs with small footprint (iOS: AudioToolbox/AudioServices).\nFully concurrent and multichannel.\n\n* params\n * id - string unique ID for the audio file\n * assetPath - the relative path or absolute URL (inluding http://) to the audio asset.\n * successCallback - success callback function\n * errorCallback - error callback function\n\n\n```javascript\npreloadComplex: function(id, assetPath, volume, delay, options, successCallback, errorCallback) \n```\n\nLoads an audio file into memory. Optimized for background music / ambient sound.\nUses highlevel native APIs with a larger footprint. (iOS: AVAudioPlayer).\nCan be stopped / looped. Can be faded in and out using the delay parameter.\n\nThe \"options\" parameter takes a configuration object for mediaControls.\nThese options are bound to the audioID used to load the file.\nIf you give controls to another track, the options from that track will apply.\nIt takes the same parameters as [cordova-plugin-music-controls2 plugin](https://github.com/ghenry22/cordova-plugin-music-controls2):\n\n```javascript\nMusicControls.create({\n\ttrack       : 'Time is Running Out',\t\t// optional, default : ''\n\tartist      : 'Muse',\t\t\t\t\t\t// optional, default : ''\n\talbum       : 'Absolution',     // optional, default: ''\n \tcover       : 'albums/absolution.jpg',\t\t// optional, default : nothing\n\t// cover can be a local path (use fullpath 'file:///storage/emulated/...', or only 'my_image.jpg' if my_image.jpg is in the www folder of your app)\n\t//\t\t\t or a remote url ('http://...', 'https://...', 'ftp://...')\n\tisPlaying   : true,\t\t\t\t\t\t\t// optional, default : true\n\tdismissable : true,\t\t\t\t\t\t\t// optional, default : false\n\n\t// hide previous/next/close buttons:\n\thasPrev   : false,\t\t// show previous button, optional, default: true\n\thasNext   : false,\t\t// show next button, optional, default: true\n\thasClose  : true,\t\t// show close button, optional, default: false\n\n\t// iOS only, optional\n\t\n\tduration : 60, // optional, default: 0\n\telapsed : 10, // optional, default: 0\n  \thasSkipForward : true, //optional, default: false. true value overrides hasNext.\n  \thasSkipBackward : true, //optional, default: false. true value overrides hasPrev.\n  \tskipForwardInterval : 15, //optional. default: 0.\n\tskipBackwardInterval : 15, //optional. default: 0.\n\thasScrubbing : false, //optional. default to false. Enable scrubbing from control center progress bar \n\n\t// Android only, optional\n\t// text displayed in the status bar when the notification (and the ticker) are updated\n\tticker\t  : 'Now playing \"Time is Running Out\"',\n\t//All icons default to their built-in android equivalents\n\t//The supplied drawable name, e.g. 'media_play', is the name of a drawable found under android/res/drawable* folders\n\tplayIcon: 'media_play',\n\tpauseIcon: 'media_pause',\n\tprevIcon: 'media_prev',\n\tnextIcon: 'media_next',\n\tcloseIcon: 'media_close',\n\tnotificationIcon: 'notification'\n}, onSuccess, onError);\n```\n\n####Volume & Voices\n\nThe default **volume** is 1.0, a lower default can be set by using a numerical value from 0.1 to 1.0.\n\nChange the float-based **delay** parameter to increase the fade-in/fade-out timing.\n\n**SUPPORT FOR VOICES HAS BEEN REMOVED IN THIS PLUGIN**\n\n### Playback\n\n* params\n * id - string unique ID for the audio file\n * assetPath - the relative path to the audio asset within the www directory\n * volume - the volume of the preloaded sound (0.1 to 1.0)\n * successCallback - success callback function\n * errorCallback - error callback function\n\n\n```javascript\naddControlsCallback: function(id, successCallback, errorCallback)\n```\n\nSets the callback for the Media Controls. Each time an event is fired, it will go through thid callback.\nAgain, this piece reflects what is stated in the [cordova-plugin-music-controls2 plugin](https://github.com/ghenry22/cordova-plugin-music-controls2).\nBelow are shown some of them, check the plugin code to see all of them, or just console.log the returned value if you need one event in particular.\n\n```javascript\nfunction events(action) {\n\n  const message = JSON.parse(action).message;\n\tswitch(message) {\n\t\tcase 'music-controls-next':\n\t\t\t// Do something\n\t\t\tbreak;\n\t\tcase 'music-controls-previous':\n\t\t\t// Do something\n\t\t\tbreak;\n\t\tcase 'music-controls-pause':\n\t\t\t// Do something\n\t\t\tbreak;\n\t\tcase 'music-controls-play':\n\t\t\t// Do something\n\t\t\tbreak;\n\t\tcase 'music-controls-destroy':\n\t\t\t// Do something\n\t\t\tbreak;\n\n\t\t// External controls (iOS only)\n    \tcase 'music-controls-toggle-play-pause' :\n\t\t\t// Do something\n\t\t\tbreak;\n    \tcase 'music-controls-seek-to':\n\t\t\tconst seekToInSeconds = JSON.parse(action).position;\n\t\t\tMusicControls.updateElapsed({\n\t\t\t\telapsed: seekToInSeconds,\n\t\t\t\tisPlaying: true\n\t\t\t});\n\t\t\t// Do something\n\t\t\tbreak;\n\n\t\t// Headset events (Android only)\n\t\t// All media button events are listed below\n\t\tcase 'music-controls-media-button' :\n\t\t\t// Do something\n\t\t\tbreak;\n\t\tcase 'music-controls-headset-unplugged':\n\t\t\t// Do something\n\t\t\tbreak;\n\t\tcase 'music-controls-headset-plugged':\n\t\t\t// Do something\n\t\t\tbreak;\n\t\tdefault:\n\t\t\tbreak;\n\t}\n}\n```\n\n\n\n```javascript\nsetControls: function(id, successCallback, errorCallback)\n```\nSets the controls to the audio file with the specified id. The controls will then manage that track in particular\n\n\n```javascript\nplay: function(id, setControls, successCallback, errorCallback, completeCallback)\n```\nPlays an audio asset.\n\n* params:\n * id - string unique ID for the audio file\n * setControls - boolean, true if the controls should be bound to this track\n * successCallback - success callback function\n * errorCallback - error callback function\n * completeCallback - error callback function\n\n\n```javascript\nloop: function (id, setControls, successCallback, errorCallback)\n```\nLoops an audio asset infinitely - this only works for assets loaded via preloadComplex.\n\n* params\n * id - string unique ID for the audio file\n * setControls - boolean, true if the controls should be bound to this track\n * successCallback - success callback function\n * errorCallback - error callback function\n\n\n```javascript\nstop: function (id, successCallback, errorCallback)\n```\n\nStops an audio file. Only works for assets loaded via preloadComplex.\n\n* params:\n * ID - string unique ID for the audio file\n * successCallback - success callback function\n * errorCallback - error callback function\n\n```javascript\nunload: function (id, successCallback, errorCallback)\n```\n\nUnloads an audio file from memory.\n\n\n* params:\n * ID - string unique ID for the audio file\n * successCallback - success callback function\n * errorCallback - error callback function\n\n```javascript\nsetVolumeForComplexAsset: function (id, volume, successCallback, errorCallback)\n```\n\nChanges the volume for preloaded complex assets.\n \n \n* params:\n * ID - string unique ID for the audio file\n * volume - the volume of the audio asset (0.1 to 1.0)\n * successCallback - success callback function\n * errorCallback - error callback function\n\n## Example Code\n\nIn this example, the resources reside in a relative path under the Cordova root folder \"www/\".\n\n```javascript\nif( window.plugins && window.plugins.NativeAudio ) {\n\t\n\t// Preload audio resources\n\twindow.plugins.NativeAudio.preloadComplex( 'music', 'audio/music.mp3', 1, 1, 0, function(msg){\n\t}, function(msg){\n\t\tconsole.log( 'error: ' + msg );\n\t});\n\t\n\twindow.plugins.NativeAudio.preloadSimple( 'click', 'audio/click.mp3', function(msg){\n\t}, function(msg){\n\t\tconsole.log( 'error: ' + msg );\n\t});\n\n\n\t// Play\n\twindow.plugins.NativeAudio.play( 'click' );\n\twindow.plugins.NativeAudio.loop( 'music' );\n\n\n\t// Stop multichannel clip after 60 seconds\n\twindow.setTimeout( function(){\n\n\t\twindow.plugins.NativeAudio.stop( 'music' );\n\t\t\t\n\t\twindow.plugins.NativeAudio.unload( 'music' );\n\t\twindow.plugins.NativeAudio.unload( 'click' );\n\n\t}, 1000 * 60 );\n}\n```\n\n## Demo\n\nThe **Drumpad** in the examples directory is a first starting point.\n\n```bash\n[sudo] npm install plugin-verify -g\nplugin-verify cordova-plugin-nativeaudio ios\nplugin-verify cordova-plugin-nativeaudio android\n```\n\nOr, type the commands step by step:\n\n```bash\ncordova create drumpad com.example.nativeaudio drumpad\ncd drumpad\ncordova platform add ios\ncordova plugin add cordova-plugin-nativeaudio\nrm -r www/*\ncp -r plugins/cordova-plugin-nativeaudio/test/* www\ncordova build ios\ncordova emulate ios\n```\n","readmeFilename":"README.md"}