Merge branch 'master' into master

Author: schoetty

.appveyor.yml

@@ -0,0 +1,28 @@
+# appveyor file
+# http://www.appveyor.com/docs/appveyor-yml
+
+max_jobs: 1
+
+shallow_clone: true
+
+init:
+  - git config --global core.autocrlf true
+
+image:
+  - Visual Studio 2017
+
+environment:
+  nodejs_version: "4"
+  matrix:
+    - PLATFORM: windows-10-store
+      JUST_BUILD: --justBuild
+install:
+  - npm cache clean -f
+  - node --version
+  - npm install -g cordova-paramedic@https://github.com/apache/cordova-paramedic.git
+  - npm install -g cordova
+
+build: off
+
+test_script:
+  - cordova-paramedic --config pr\%PLATFORM% --plugin . %JUST_BUILD%

.github/PULL_REQUEST_TEMPLATE.md

@@ -17,7 +17,6 @@ Thanks!
 
 
 ### Checklist
-- [ ] [ICLA](http://www.apache.org/licenses/icla.txt) has been signed and submitted to [email protected].
 - [ ] [Reported an issue](http://cordova.apache.org/contribute/issues.html) in the JIRA database
 - [ ] Commit message follows the format: "CB-3232: (android) Fix bug with resolving file paths", where CB-xxxx is the JIRA ID & "android" is the platform affected.
 - [ ] Added automated test coverage as appropriate for this change.

.gitignore

@@ -14,10 +14,13 @@ Thumbs.db
 
 node_modules
 
+#eclipse
+bin
+.project
+.classpath
 
 
 
 
 
-
- 
+ 

.travis.yml

@@ -1,4 +1,86 @@
-language: node_js
 sudo: false
-node_js:
-  - "4.2"
+addons:
+  jwt:
+    secure: M4uBGUMbanDtCBrNktJhEwNSLL0UsOV3IoINqW3GRupX7Mr13MBZzsORm4HVbdbPxQ6Bf2LhyJ/fabQRsOoJrCokgWwfKkigztQcMFeLNao9liBRA6kuQOh5/rdfoULpu96GvlYzB4ddgSBSSGQW3DesaKC/BpTXnvQ4OnXo5e4=
+env:
+  global:
+  - SAUCE_USERNAME=snay
+  - TRAVIS_NODE_VERSION="6.14.2"
+matrix:
+  include:
+  - env: PLATFORM=browser-chrome
+    os: linux
+    language: node_js
+    node_js: '6.14.2'
+  - env: PLATFORM=browser-firefox
+    os: linux
+    language: node_js
+    node_js: '6.14.2'
+  - env: PLATFORM=browser-safari
+    os: linux
+    language: node_js
+    node_js: '6.14.2'
+  - env: PLATFORM=browser-edge
+    os: linux
+    language: node_js
+    node_js: '6.14.2'
+  - env: PLATFORM=ios-9.3
+    os: osx
+    osx_image: xcode8.3
+    language: node_js
+    node_js: '6.14.2'
+  - env: PLATFORM=ios-10.0
+    os: osx
+    osx_image: xcode8.3
+    language: node_js
+    node_js: '6.14.2'
+  - env: PLATFORM=android-4.4
+    os: linux
+    language: android
+    jdk: oraclejdk8
+    android:
+      components:
+      - tools
+      - build-tools-26.0.2
+  - env: PLATFORM=android-5.1
+    os: linux
+    language: android
+    jdk: oraclejdk8
+    android:
+      components:
+      - tools
+      - build-tools-26.0.2
+  - env: PLATFORM=android-6.0
+    os: linux
+    language: android
+    jdk: oraclejdk8
+    android:
+      components:
+      - tools
+      - build-tools-26.0.2
+  - env: PLATFORM=android-7.0
+    os: linux
+    language: android
+    jdk: oraclejdk8
+    android:
+      components:
+      - tools
+      - build-tools-26.0.2
+before_install:
+- rm -rf ~/.nvm && git clone https://github.com/creationix/nvm.git ~/.nvm && (cd ~/.nvm
+  && git checkout `git describe --abbrev=0 --tags`) && source ~/.nvm/nvm.sh && nvm
+  install $TRAVIS_NODE_VERSION
+- node --version
+- if [[ "$PLATFORM" =~ android ]]; then gradle --version; fi
+- if [[ "$PLATFORM" =~ ios ]]; then npm install -g ios-deploy; fi
+- if [[ "$PLATFORM" =~ android ]]; then echo y | android update sdk -u --filter android-22,android-23,android-24,android-25,android-26;
+  fi
+- git clone https://github.com/apache/cordova-paramedic /tmp/paramedic && pushd /tmp/paramedic
+  && npm install && popd
+- npm install -g cordova
+install:
+- npm install
+script:
+- npm test
+- node /tmp/paramedic/main.js --config pr/$PLATFORM --plugin $(pwd) --shouldUseSauce
+  --buildName travis-plugin-media-$TRAVIS_JOB_NUMBER

README.md

@@ -21,7 +21,9 @@ description: Record and play audio on the device.
 #         under the License.
 -->
 
-[![Build Status](https://travis-ci.org/apache/cordova-plugin-media.svg?branch=master)](https://travis-ci.org/apache/cordova-plugin-media)
+|AppVeyor|Travis CI|
+|:-:|:-:|
+|[![Build status](https://ci.appveyor.com/api/projects/status/github/apache/cordova-plugin-media?branch=master)](https://ci.appveyor.com/project/ApacheSoftwareFoundation/cordova-plugin-media)|[![Build Status](https://travis-ci.org/apache/cordova-plugin-media.svg?branch=master)](https://travis-ci.org/apache/cordova-plugin-media)|
 
 # cordova-plugin-media
 
@@ -44,7 +46,7 @@ function onDeviceReady() {
 }
 ```
 
-Report issues with this plugin on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Media%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
+Report issues with this plugin on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22cordova-plugin-media%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
 
 
 ## Installation
@@ -56,18 +58,10 @@ cordova plugin add cordova-plugin-media
 ## Supported Platforms
 
 - Android
-- BlackBerry 10
 - iOS
-- Windows Phone 7 and 8
-- Tizen
-- Windows 8
 - Windows
 - Browser
 
-## Windows Phone Quirks
-
-- Only one media file can be played back at a time.
-
 ## Media
 
 ```js
@@ -80,9 +74,9 @@ var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);
 
 - __mediaSuccess__: (Optional) The callback that executes after a `Media` object has completed the current play, record, or stop action. _(Function)_
 
-- __mediaError__: (Optional) The callback that executes if an error occurs. _(Function)_
+- __mediaError__: (Optional) The callback that executes if an error occurs. It takes an integer error code. _(Function)_
 
-- __mediaStatus__: (Optional) The callback that executes to indicate status changes. _(Function)_
+- __mediaStatus__: (Optional) The callback that executes to indicate status changes. It takes a integer status code. _(Function)_
 
 __NOTE__: `cdvfile` path is supported as `src` parameter:
 ```javascript
@@ -102,7 +96,7 @@ The following constants are reported as the only parameter to the
 
 ### Methods
 
-- `media.getCurrentAmplitude`: Returns the current position within an audio file.
+- `media.getCurrentAmplitude`: Returns the current amplitude within an audio file.
 
 - `media.getCurrentPosition`: Returns the current position within an audio file.
 
@@ -128,6 +122,8 @@ The following constants are reported as the only parameter to the
 
 - `media.stop`: Stop playing an audio file.
 
+- `media.setRate`: Set the playback rate for the audio file.
+
 ### Additional ReadOnly Parameters
 
 - __position__: The position within the audio playback, in seconds.
@@ -138,7 +134,7 @@ The following constants are reported as the only parameter to the
 
 ## media.getCurrentAmplitude
 
-Returns the current amplitude of the current recording.
+Returns the current amplitude within an audio file.
 
     media.getCurrentAmplitude(mediaSuccess, [mediaError]);
 
@@ -310,7 +306,7 @@ function recordAudio() {
 
     // Pause Recording after 5 seconds
     setTimeout(function() {
-        my_media.pauseRecord();
+        mediaRec.pauseRecord();
     }, 5000);
 }
 ```
@@ -358,8 +354,11 @@ function playAudio(url) {
   is locked.  If set to `true` (the default value), the state of the
   hardware mute button is ignored, e.g.:
 
-        var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
-        myMedia.play({ playAudioWhenScreenIsLocked : false })
+        var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
+        myMedia.play({ playAudioWhenScreenIsLocked : true });
+        myMedia.setVolume('1.0');
+
+> Note: To allow playback with the screen locked or background audio you have to add `audio` to `UIBackgroundModes` in the `info.plist` file. See [Apple documentation](https://developer.apple.com/library/content/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/BackgroundExecution/BackgroundExecution.html#//apple_ref/doc/uid/TP40007072-CH4-SW23). Also note that the audio has to be started before going to background.
 
 - __order of file search__: When only a file name or simple path is
   provided, iOS searches in the `www` directory for the file, then in
@@ -425,12 +424,12 @@ function recordAudio() {
 
     // Pause Recording after 5 seconds
     setTimeout(function() {
-        my_media.pauseRecord();
+        mediaRec.pauseRecord();
     }, 5000);
 
     // Resume Recording after 10 seconds
     setTimeout(function() {
-        my_media.resumeRecord();
+        mediaRec.resumeRecord();
     }, 10000);
 }
 ```
@@ -459,10 +458,6 @@ setTimeout(function() {
 }, 5000);
 ```
 
-### BlackBerry 10 Quirks
-
-- Not supported on BlackBerry OS 5 devices.
-
 ## media.setVolume
 
 Set the volume for an audio file.
@@ -520,7 +515,6 @@ Starts recording an audio file.
 
 - Android
 - iOS
-- Windows Phone 7 and 8
 - Windows
 
 ### Quick Example
@@ -548,19 +542,33 @@ function recordAudio() {
 
 ### Android Quirks
 
-- Android devices record audio in Adaptive Multi-Rate format. The specified file should end with a _.amr_ extension.
+- Android devices record audio in AAC ADTS file format. The specified file should end with a _.aac_ extension.
 - The hardware volume controls are wired up to the media volume while any Media objects are alive. Once the last created Media object has `release()` called on it, the volume controls revert to their default behaviour. The controls are also reset on page navigation, as this releases all Media objects.
 
 ### iOS Quirks
 
-- iOS only records to files of type _.wav_ and returns an error if the file name extension is not correct.
+- iOS only records to files of type _.wav_ and _.m4a_ and returns an error if the file name extension is not correct.
 
 - If a full path is not provided, the recording is placed in the application's `documents/tmp` directory. This can be accessed via the `File` API using `LocalFileSystem.TEMPORARY`. Any subdirectory specified at record time must already exist.
 
 - Files can be recorded and played back using the documents URI:
 
         var myMedia = new Media("documents://beer.mp3")
 
+- Since iOS 10 it's mandatory to provide an usage description in the `info.plist` if trying to access privacy-sensitive data. When the system prompts the user to allow access, this usage description string will displayed as part of the permission dialog box, but if you didn't provide the usage description, the app will crash before showing the dialog. Also, Apple will reject apps that access private data but don't provide an usage description.
+
+This plugins requires the following usage description:
+
+* `NSMicrophoneUsageDescription` describes the reason that the app accesses the user's microphone. 
+
+To add this entry into the `info.plist`, you can use the `edit-config` tag in the `config.xml` like this:
+
+```
+<edit-config target="NSMicrophoneUsageDescription" file="*-Info.plist" mode="merge">
+    <string>need microphone access to record sounds</string>
+</edit-config>
+```
+
 ### Windows Quirks
 
 - Windows devices can use MP3, M4A and WMA formats for recorded audio. However in most cases it is not possible to use MP3 for audio recording on _Windows Phone 8.1_ devices, because an MP3 encoder is [not shipped with Windows Phone](https://msdn.microsoft.com/en-us/library/windows/apps/windows.media.mediaproperties.mediaencodingprofile.createmp3.aspx).
@@ -569,10 +577,6 @@ function recordAudio() {
 
 - Any subdirectory specified at record time must already exist.
 
-### Tizen Quirks
-
-- Not supported on Tizen devices.
-
 ## media.stop
 
 Stops playing an audio file.
@@ -617,7 +621,6 @@ Stops recording an audio file.
 
 - Android
 - iOS
-- Windows Phone 7 and 8
 - Windows
 
 ### Quick Example
@@ -649,9 +652,33 @@ function recordAudio() {
 }
 ```
 
-### Tizen Quirks
+## media.setRate
+
+Stops recording an audio file.
+
+    media.setRate(rate);
 
-- Not supported on Tizen devices.
+### Supported Platforms
+
+- iOS
+
+### Parameters
+
+- __rate__: The rate to set for playback.
+
+### Quick Example
+
+```js
+// Audio player
+//
+var my_media = new Media(src, onSuccess, onError);
+    my_media.play();
+
+// Set playback rate to 2.0x after 10 seconds
+setTimeout(function() {
+    my_media.setRate(2.0);
+}, 5000);
+```
 
 ## MediaError