CB-8653 Updated Readme (478ac90d) · Commits · codevise / cordova-plugin-media

README.md

+488 −2

Original line number	Diff line number	Diff line
		@@ -17,8 +17,494 @@
		under the License.
		-->

		# org.apache.cordova.media
		# cordova-plugin-media

		[![Build Status](https://travis-ci.org/apache/cordova-plugin-media.svg)](https://travis-ci.org/apache/cordova-plugin-media)

		Plugin documentation: [doc/index.md](doc/index.md)
		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.

		This plugin defines a global `Media` Constructor.

		Although in the global scope, it is not available until after the `deviceready` event.

		document.addEventListener("deviceready", onDeviceReady, false);
		function onDeviceReady() {
		console.log(Media);
		}

		## Installation

		cordova plugin add cordova-plugin-media

		## Supported Platforms

		- Android
		- BlackBerry 10
		- iOS
		- Windows Phone 7 and 8
		- Tizen
		- Windows

		## 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

		### 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.
		- 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.

		- 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")

		### Windows Quirks

		- If a full path is not provided, the recording is placed in the AppData/temp directory. This can be accessed via the `File` API using `LocalFileSystem.TEMPORARY` or 'ms-appdata:///temp/<filename>' URI.

		- Any subdirectory specified at record time must already exist.

		### 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

		### 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` = 1
		- `MediaError.MEDIA_ERR_NETWORK` = 2
		- `MediaError.MEDIA_ERR_DECODE` = 3
		- `MediaError.MEDIA_ERR_NONE_SUPPORTED` = 4

doc/index.md

deleted100644 → 0

+0 −508

File deleted.

Preview size limit exceeded, changes collapsed.