CB-5658 Add doc.index.md for Media plugin
Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-media/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-media/commit/6dcf4131 Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-media/tree/6dcf4131 Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-media/diff/6dcf4131 Branch: refs/heads/master Commit: 6dcf413131caba3673d13078df148e1b89ab6b09 Parents: e06ec8a Author: Andrew Grieve <[email protected]> Authored: Wed Dec 18 15:54:15 2013 -0500 Committer: Andrew Grieve <[email protected]> Committed: Wed Dec 18 15:54:15 2013 -0500 ---------------------------------------------------------------------- README.md | 25 ++- doc/index.md | 492 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 513 insertions(+), 4 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-plugin-media/blob/6dcf4131/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 2a0cb89..bacd84b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,22 @@ -cordova-plugin-media --------------------- -To install this plugin, follow the [Command-line Interface Guide](http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface). +<!--- + license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at -If you are not using the Cordova Command-line Interface, follow [Using Plugman to Manage Plugins](http://cordova.apache.org/docs/en/edge/plugin_ref_plugman.md.html). + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +# org.apache.cordova.media + +Plugin documentation: [doc/index.md](doc/index.md) http://git-wip-us.apache.org/repos/asf/cordova-plugin-media/blob/6dcf4131/doc/index.md ---------------------------------------------------------------------- diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..5773ed7 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,492 @@ +<!--- + license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +# org.apache.cordova.media + +This plugin provides the ability to record and play back audio files on a device. + +__NOTE__: The current implementation does not adhere to a W3C +specification for media capture, and is provided for convenience only. +A future implementation will adhere to the latest W3C specification +and may deprecate the current APIs. + +## Installation + + cordova plugin add org.apache.cordova.media + +## Supported Platforms + +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 +- Tizen +- Windows 8 + +## Windows Phone Quirks + +- Only one media file can be played back at a time. + +- There are strict restrictions on how your application interacts with other media. See the [Microsoft documentation for details][url]. + +[url]: http://msdn.microsoft.com/en-us/library/windowsphone/develop/hh184838(v=vs.92).aspx + +## Media + + var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]); + +### Parameters + +- __src__: A URI containing the audio content. _(DOMString)_ + +- __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)_ + +- __mediaStatus__: (Optional) The callback that executes to indicate status changes. _(Function)_ + +### Constants + +The following constants are reported as the only parameter to the +`mediaStatus` callback: + +- `Media.MEDIA_NONE` = 0; +- `Media.MEDIA_STARTING` = 1; +- `Media.MEDIA_RUNNING` = 2; +- `Media.MEDIA_PAUSED` = 3; +- `Media.MEDIA_STOPPED` = 4; + +### Methods + +- `media.getCurrentPosition`: Returns the current position within an audio file. + +- `media.getDuration`: Returns the duration of an audio file. + +- `media.play`: Start or resume playing an audio file. + +- `media.pause`: Pause playback of an audio file. + +- `media.release`: Releases the underlying operating system's audio resources. + +- `media.seekTo`: Moves the position within the audio file. + +- `media.setVolume`: Set the volume for audio playback. + +- `media.startRecord`: Start recording an audio file. + +- `media.stopRecord`: Stop recording an audio file. + +- `media.stop`: Stop playing an audio file. + +### Additional ReadOnly Parameters + +- __position__: The position within the audio playback, in seconds. + - Not automatically updated during play; call `getCurrentPosition` to update. + +- __duration__: The duration of the media, in seconds. + + +## media.getCurrentPosition + +Returns the current position within an audio file. Also updates the `Media` object's `position` parameter. + + media.getCurrentPosition(mediaSuccess, [mediaError]); + +### Parameters + +- __mediaSuccess__: The callback that is passed the current position in seconds. + +- __mediaError__: (Optional) The callback to execute if an error occurs. + +### Quick Example + + // Audio player + // + var my_media = new Media(src, onSuccess, onError); + + // Update media position every second + var mediaTimer = setInterval(function () { + // get media position + my_media.getCurrentPosition( + // success callback + function (position) { + if (position > -1) { + console.log((position) + " sec"); + } + }, + // error callback + function (e) { + console.log("Error getting pos=" + e); + } + ); + }, 1000); + + +## media.getDuration + +Returns the duration of an audio file in seconds. If the duration is unknown, it returns a value of -1. + + + media.getDuration(); + +### Quick Example + + // Audio player + // + var my_media = new Media(src, onSuccess, onError); + + // Get duration + var counter = 0; + var timerDur = setInterval(function() { + counter = counter + 100; + if (counter > 2000) { + clearInterval(timerDur); + } + var dur = my_media.getDuration(); + if (dur > 0) { + clearInterval(timerDur); + document.getElementById('audio_duration').innerHTML = (dur) + " sec"; + } + }, 100); + + +## media.pause + +Pauses playing an audio file. + + media.pause(); + + +### Quick Example + + // Play audio + // + function playAudio(url) { + // Play the audio file at url + var my_media = new Media(url, + // success callback + function () { console.log("playAudio():Audio Success"); }, + // error callback + function (err) { console.log("playAudio():Audio Error: " + err); } + ); + + // Play audio + my_media.play(); + + // Pause after 10 seconds + setTimeout(function () { + media.pause(); + }, 10000); + } + + +## media.play + +Starts or resumes playing an audio file. + + media.play(); + + +### Quick Example + + // Play audio + // + function playAudio(url) { + // Play the audio file at url + var my_media = new Media(url, + // success callback + function () { + console.log("playAudio():Audio Success"); + }, + // error callback + function (err) { + console.log("playAudio():Audio Error: " + err); + } + ); + // Play audio + my_media.play(); + } + + +### iOS Quirks + +- __numberOfLoops__: Pass this option to the `play` method to specify + the number of times you want the media file to play, e.g.: + + var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3";) + myMedia.play({ numberOfLoops: 2 }) + +- __playAudioWhenScreenIsLocked__: Pass in this option to the `play` + method to specify whether you want to allow playback when the screen + 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 }) + +- __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 + the application's `documents/tmp` directory: + + var myMedia = new Media("audio/beer.mp3") + myMedia.play() // first looks for file in www/audio/beer.mp3 then in <application>/documents/tmp/audio/beer.mp3 + +## media.release + +Releases the underlying operating system's audio resources. +This is particularly important for Android, since there are a finite amount of +OpenCore instances for media playback. Applications should call the `release` +function for any `Media` resource that is no longer needed. + + media.release(); + + +### Quick Example + + // Audio player + // + var my_media = new Media(src, onSuccess, onError); + + my_media.play(); + my_media.stop(); + my_media.release(); + + +## media.seekTo + +Sets the current position within an audio file. + + media.seekTo(milliseconds); + +### Parameters + +- __milliseconds__: The position to set the playback position within the audio, in milliseconds. + + +### Quick Example + + // Audio player + // + var my_media = new Media(src, onSuccess, onError); + my_media.play(); + // SeekTo to 10 seconds after 5 seconds + setTimeout(function() { + my_media.seekTo(10000); + }, 5000); + + +### BlackBerry 10 Quirks + +- Not supported on BlackBerry OS 5 devices. + +## media.setVolume + +Set the volume for an audio file. + + media.setVolume(volume); + +### Parameters + +- __volume__: The volume to set for playback. The value must be within the range of 0.0 to 1.0. + +### Supported Platforms + +- Android +- iOS + +### Quick Example + + // Play audio + // + function playAudio(url) { + // Play the audio file at url + var my_media = new Media(url, + // success callback + function() { + console.log("playAudio():Audio Success"); + }, + // error callback + function(err) { + console.log("playAudio():Audio Error: "+err); + }); + + // Play audio + my_media.play(); + + // Mute volume after 2 seconds + setTimeout(function() { + my_media.setVolume('0.0'); + }, 2000); + + // Set volume to 1.0 after 5 seconds + setTimeout(function() { + my_media.setVolume('1.0'); + }, 5000); + } + + +## media.startRecord + +Starts recording an audio file. + + media.startRecord(); + +### Supported Platforms + +- Android +- iOS +- Windows Phone 7 and 8 +- Windows 8 + +### Quick Example + + // Record audio + // + function recordAudio() { + var src = "myrecording.mp3"; + var mediaRec = new Media(src, + // success callback + function() { + console.log("recordAudio():Audio Success"); + }, + + // error callback + function(err) { + console.log("recordAudio():Audio Error: "+ err.code); + }); + + // Record audio + mediaRec.startRecord(); + } + + +### Android Quirks + +- Android devices record audio in Adaptive Multi-Rate format. The specified file should end with a _.amr_ extension. + +### iOS Quirks + +- iOS only records to files of type _.wav_ 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") + +### Tizen Quirks + +- Not supported on Tizen devices. + +## media.stop + +Stops playing an audio file. + + media.stop(); + +### Quick Example + + // Play audio + // + function playAudio(url) { + // Play the audio file at url + var my_media = new Media(url, + // success callback + function() { + console.log("playAudio():Audio Success"); + }, + // error callback + function(err) { + console.log("playAudio():Audio Error: "+err); + } + ); + + // Play audio + my_media.play(); + + // Pause after 10 seconds + setTimeout(function() { + my_media.stop(); + }, 10000); + } + + +## media.stopRecord + +Stops recording an audio file. + + media.stopRecord(); + +### Supported Platforms + +- Android +- iOS +- Windows Phone 7 and 8 +- Windows 8 + +### Quick Example + + // Record audio + // + function recordAudio() { + var src = "myrecording.mp3"; + var mediaRec = new Media(src, + // success callback + function() { + console.log("recordAudio():Audio Success"); + }, + + // error callback + function(err) { + console.log("recordAudio():Audio Error: "+ err.code); + } + ); + + // Record audio + mediaRec.startRecord(); + + // Stop recording after 10 seconds + setTimeout(function() { + mediaRec.stopRecord(); + }, 10000); + } + + +### Tizen Quirks + +- Not supported on Tizen devices. + +## MediaError + +A `MediaError` object is returned to the `mediaError` callback +function when an error occurs. + +### Properties + +- __code__: One of the predefined error codes listed below. + +- __message__: An error message describing the details of the error. + +### Constants + +- `MediaError.MEDIA_ERR_ABORTED` +- `MediaError.MEDIA_ERR_NETWORK` +- `MediaError.MEDIA_ERR_DECODE` +- `MediaError.MEDIA_ERR_NONE_SUPPORTED` +
