cordova-plugin-media-capture

Android Testsuite Chrome Testsuite iOS Testsuite Lint Test

このプラグインは、デバイスの音声、画像、ビデオのキャプチャ機能へのアクセスを提供します。

警告：デバイスのカメラやマイクから画像、ビデオ、または音声の収集と使用は、重要なプライバシー問題を引き起こします。アプリのプライバシーポリシーでは、アプリがそのようなセンサーをどのように使用するか、および記録されたデータが他の当事者と共有されるかどうかについて説明する必要があります。さらに、アプリのカメラまたはマイクの使用がユーザーインターフェースでは明らかでない場合、アプリがカメラまたはマイクにアクセスする前に、ジャストインタイム通知を提供する必要があります（デバイスのオペレーティングシステムが既にそうしていない場合）。その通知では、上記と同じ情報に加えて、ユーザーの許可を取得する必要があります（例：OKとキャンセルの選択肢を表示する）。一部のアプリマーケットプレイスでは、アプリがジャストインタイム通知を提供し、カメラまたはマイクにアクセスする前にユーザーから許可を得る必要がある場合があります。詳細については、プライバシーガイドを参照してください。

このプラグインは、グローバルなnavigator.device.captureオブジェクトを定義します。

グローバルスコープにあるものの、devicereadyイベントの後でなければ使用できません。

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

インストール

cordova plugin add cordova-plugin-media-capture

サポートされているプラットフォーム

  • Android
  • ブラウザ
  • iOS
  • Windows

オブジェクト

  • Capture
  • CaptureAudioOptions
  • CaptureImageOptions
  • CaptureVideoOptions
  • CaptureCallback
  • CaptureErrorCB
  • ConfigurationData
  • MediaFile
  • MediaFileData

メソッド

  • capture.captureAudio
  • capture.captureImage
  • capture.captureVideo
  • MediaFile.getFormatData

プロパティ

  • supportedAudioModes：デバイスでサポートされている音声録音フォーマット。（ConfigurationData[]）

  • supportedImageModes：デバイスでサポートされている記録画像サイズとフォーマット。（ConfigurationData[]）

  • supportedVideoModes：デバイスでサポートされている記録ビデオ解像度とフォーマット。（ConfigurationData[]）

capture.captureAudio

オーディオレコーダーアプリケーションを開始し、キャプチャされたオーディオクリップファイルに関する情報を返します。

navigator.device.capture.captureAudio(
    CaptureCB captureSuccess, CaptureErrorCB captureError,  [CaptureAudioOptions options]
);

説明

デバイスのデフォルトのオーディオ録音アプリケーションを使用してオーディオ録音をキャプチャする非同期操作を開始します。この操作により、デバイスユーザーは単一のセッションで複数の録音をキャプチャできます。

キャプチャ操作は、ユーザーがオーディオ録音アプリケーションを終了するか、CaptureAudioOptions.limitで指定された最大録音数に達すると終了します。limitパラメーター値が指定されていない場合、デフォルトは1になり、ユーザーが単一のオーディオクリップを録音した後、キャプチャ操作は終了します。

キャプチャ操作が完了すると、CaptureCallbackが、キャプチャされた各オーディオクリップファイルについて説明するMediaFileオブジェクトの配列で実行されます。ユーザーがオーディオクリップをキャプチャする前に操作を終了した場合、CaptureErrorCallbackは、CaptureError.CAPTURE_NO_MEDIA_FILESエラーコードを含むCaptureErrorオブジェクトで実行されます。

サポートされているプラットフォーム

  • Android
  • iOS
  • Windows

例

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start audio capture
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});

iOS特有の動作

  • iOSにはデフォルトのオーディオ録音アプリケーションがないため、シンプルなユーザーインターフェースが提供されます。

Windows Phone 7および8特有の動作

  • Windows Phone 7にはデフォルトのオーディオ録音アプリケーションがないため、シンプルなユーザーインターフェースが提供されます。

capture.captureImage

カメラアプリケーションを開始し、キャプチャされた画像ファイルに関する情報を返します。

navigator.device.capture.captureImage(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options]
);

説明

デバイスのカメラアプリケーションを使用して画像をキャプチャする非同期操作を開始します。この操作により、ユーザーは単一のセッションで複数の画像をキャプチャできます。

キャプチャ操作は、ユーザーがカメラアプリケーションを閉じるか、CaptureImageOptions.limitで指定された最大録音数に達すると終了します。limit値が指定されていない場合、デフォルトは1になり、ユーザーが単一の画像をキャプチャした後、キャプチャ操作は終了します。

キャプチャ操作が完了すると、キャプチャされた各画像ファイルについて説明するMediaFileオブジェクトの配列を使用してCaptureCBコールバックが呼び出されます。ユーザーが画像をキャプチャする前に操作を終了した場合、CaptureErrorCBコールバックは、CaptureError.CAPTURE_NO_MEDIA_FILESエラーコードを含むCaptureErrorオブジェクトで実行されます。

サポートされているプラットフォーム

  • Android
  • ブラウザ
  • iOS
  • Windows

iOS特有の動作

iOS 10以降、プライバシーに関連するデータにアクセスしようとする場合、info.plistに利用状況説明を提供することが必須です。システムがユーザーにアクセスを許可するよう促す際に、この利用状況説明文字列は許可ダイアログボックスの一部として表示されますが、利用状況説明を提供しなかった場合、アプリはダイアログを表示する前にクラッシュします。また、Appleは、プライベートデータにアクセスするが利用状況説明を提供しないアプリを拒否します。

このプラグインは、次の利用状況説明が必要です。

  • NSCameraUsageDescriptionは、アプリがユーザーのカメラにアクセスする理由を説明します。
  • NSMicrophoneUsageDescriptionは、アプリがユーザーのマイクにアクセスする理由を説明します。
  • NSPhotoLibraryUsageDescriptionentryは、アプリがユーザーの写真ライブラリにアクセスする理由を説明します。

これらのエントリをinfo.plistに追加するには、次のようにconfig.xmlでedit-configタグを使用できます。

<edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
    <string>need camera access to take pictures</string>
</edit-config>

<edit-config target="NSMicrophoneUsageDescription" file="*-Info.plist" mode="merge">
    <string>need microphone access to record sounds</string>
</edit-config>

<edit-config target="NSPhotoLibraryUsageDescription" file="*-Info.plist" mode="merge">
    <string>need to photo library access to get pictures from there</string>
</edit-config>

ブラウザ特有の動作

Chrome、Firefox、Operaでのみ動作します（IEとSafariはnavigator.getUserMedia APIをサポートしていないため）。

キャプチャされたファイルのURLを使用して画像を表示するのは、Chrome/Operaでのみ可能です。Firefoxはキャプチャされた画像をIndexedDBストレージに保存します（ファイルプラグインのドキュメントを参照）。そのため、キャプチャされた画像を表示する唯一の方法は、それを読み込んでDataURLを使用して表示することです。

例

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start image capture
navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2});

capture.captureVideo

ビデオレコーダーアプリケーションを開始し、キャプチャされたビデオクリップファイルに関する情報を返します。

navigator.device.capture.captureVideo(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options]
);

説明

デバイスのビデオ録音アプリケーションを使用してビデオ録音をキャプチャする非同期操作を開始します。この操作により、ユーザーは単一のセッションで複数の録音をキャプチャできます。

キャプチャ操作は、ユーザーがビデオ録音アプリケーションを終了するか、CaptureVideoOptions.limitで指定された最大録音数に達すると終了します。limitパラメーター値が指定されていない場合、デフォルトは1になり、ユーザーが単一のビデオクリップを録音した後、キャプチャ操作は終了します。

キャプチャ操作が完了すると、キャプチャされた各ビデオクリップファイルについて説明するMediaFileオブジェクトの配列を使用してCaptureCBコールバックが実行されます。ユーザーがビデオクリップをキャプチャする前に操作を終了した場合、CaptureErrorCBコールバックは、CaptureError.CAPTURE_NO_MEDIA_FILESエラーコードを含むCaptureErrorオブジェクトで実行されます。

サポートされているプラットフォーム

  • Android
  • iOS
  • Windows

例

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start video capture
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});

CaptureAudioOptions

オーディオキャプチャ設定オプションをカプセル化します。

プロパティ

  • limit：デバイスユーザーが単一のキャプチャ操作で録音できるオーディオクリップの最大数。値は1以上である必要があります（デフォルトは1）。

  • duration：オーディオサウンドクリップの最大時間（秒単位）。

例

// limit capture operation to 3 media files, no longer than 10 seconds each
var options = { limit: 3, duration: 10 };

navigator.device.capture.captureAudio(captureSuccess, captureError, options);

Android特有の動作

  • durationパラメーターはサポートされていません。録音の長さはプログラムで制限できません。

iOS特有の動作

  • limitパラメーターはサポートされておらず、呼び出しごとに1つの録音しか作成できません。

CaptureImageOptions

画像キャプチャ設定オプションをカプセル化します。

プロパティ

  • limit：ユーザーが単一のキャプチャ操作でキャプチャできる画像の最大数。値は1以上である必要があります（デフォルトは1）。

例

// limit capture operation to 3 images
var options = { limit: 3 };

navigator.device.capture.captureImage(captureSuccess, captureError, options);

iOS特有の動作

  • limitパラメーターはサポートされておらず、呼び出しごとに1つの画像しか撮影できません。

CaptureVideoOptions

ビデオキャプチャ設定オプションをカプセル化します。

プロパティ

  • limit：デバイスユーザーが単一のキャプチャ操作でキャプチャできるビデオクリップの最大数。値は1以上である必要があります（デフォルトは1）。

  • duration：ビデオクリップの最大時間（秒単位）。

  • quality：異なる品質でビデオをキャプチャできるようにします。値1（デフォルト）は高品質を意味し、値0はMMSメッセージに適した低品質を意味します。

例

// limit capture operation to 3 video clips
var options = { limit: 3 };

navigator.device.capture.captureVideo(captureSuccess, captureError, options);

iOS特有の動作

  • limitプロパティは無視されます。呼び出しごとに1つのビデオしか記録されません。

  • qualityプロパティの値には、中品質の0.5を使用できます。

  • iOSのqualityプロパティの詳細については、こちらを参照してください。

Android特有の動作

  • Androidのqualityプロパティの詳細については、こちらを参照してください。

例（品質付き）

// limit capture operation to 1 video clip of low quality
var options = { limit: 1, quality: 0 };
navigator.device.capture.captureVideo(captureSuccess, captureError, options);

CaptureCB

メディアキャプチャ操作が成功すると呼び出されます。

function captureSuccess( MediaFile[] mediaFiles ) { ... };

説明

この関数は、キャプチャ操作が正常に完了した後に実行されます。この時点でメディアファイルがキャプチャされ、ユーザーがメディアキャプチャアプリケーションを終了するか、キャプチャ制限に達しています。

各MediaFileオブジェクトは、キャプチャされたメディアファイルについて説明します。

例

// capture callback
function captureSuccess(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

CaptureError

メディアキャプチャ操作の失敗によって発生したエラーコードをカプセル化します。

プロパティ

  • code：以下にリストされている定義済みのエラーコードのいずれか。

定数

  • CaptureError.CAPTURE_INTERNAL_ERR：カメラまたはマイクが画像または音声をキャプチャできませんでした。

  • CaptureError.CAPTURE_APPLICATION_BUSY：カメラまたはオーディオキャプチャアプリケーションは現在、別のキャプチャリクエストを処理しています。

  • CaptureError.CAPTURE_INVALID_ARGUMENT：APIの無効な使用（例：limitの値が1未満）。

  • CaptureError.CAPTURE_NO_MEDIA_FILES：ユーザーは何かをキャプチャする前にカメラまたはオーディオキャプチャアプリケーションを終了しました。

  • CaptureError.CAPTURE_PERMISSION_DENIED：ユーザーは、指定されたキャプチャリクエストを実行するために必要なアクセス許可を拒否しました。

  • CaptureError.CAPTURE_NOT_SUPPORTED：要求されたキャプチャ操作はサポートされていません。

CaptureErrorCB

メディアキャプチャ操作中にエラーが発生した場合に呼び出されます。

function captureError( CaptureError error ) { ... };

説明

メディアキャプチャ操作の起動中にエラーが発生した場合、この関数が実行されます。キャプチャアプリケーションがビジー状態である場合、キャプチャ操作が既に実行中である場合、またはメディアファイルがキャプチャされる前にユーザーが操作をキャンセルした場合などが、失敗シナリオに含まれます。

この関数は、適切なエラーcodeを含むCaptureErrorオブジェクトと共に実行されます。

例

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

ConfigurationData

デバイスがサポートするメディアキャプチャパラメータのセットをカプセル化します。

説明

デバイスがサポートするメディアキャプチャモードを記述します。設定データには、MIMEタイプと、ビデオまたは画像キャプチャのキャプチャ寸法が含まれます。

MIMEタイプはRFC2046に準拠する必要があります。例

  • video/3gpp
  • video/quicktime
  • image/jpeg
  • audio/amr
  • audio/wav

プロパティ

  • type: メディアタイプを表すASCIIエンコードされた小文字の文字列。(DOMString)

  • height: 画像またはビデオの高さをピクセル単位で表します。サウンドクリップの場合は0になります。(Number)

  • width: 画像またはビデオの幅をピクセル単位で表します。サウンドクリップの場合は0になります。(Number)

例

// retrieve supported image modes
var imageModes = navigator.device.capture.supportedImageModes;

// Select mode that has the highest horizontal resolution
var width = 0;
var selectedmode;
for each (var mode in imageModes) {
    if (mode.width > width) {
        width = mode.width;
        selectedmode = mode;
    }
}

どのプラットフォームでもサポートされていません。すべての構成データ配列は空です。

MediaFile.getFormatData

メディアキャプチャファイルに関する形式情報を取得します。

mediaFile.getFormatData(
    MediaFileDataSuccessCB successCallback,
    [MediaFileDataErrorCB errorCallback]
);

説明

この関数は、メディアファイルの形式情報を非同期的に取得しようとします。成功すると、MediaFileDataオブジェクトを使用してMediaFileDataSuccessCBコールバックを呼び出します。試行が失敗すると、この関数はMediaFileDataErrorCBコールバックを呼び出します。

サポートされているプラットフォーム

  • Android
  • iOS
  • Windows

Android特有の動作

メディアファイル形式情報にアクセスするためのAPIは制限されているため、すべてのMediaFileDataプロパティがサポートされているわけではありません。

iOS特有の動作

メディアファイル形式情報にアクセスするためのAPIは制限されているため、すべてのMediaFileDataプロパティがサポートされているわけではありません。

MediaFile

メディアキャプチャファイルのプロパティをカプセル化します。

プロパティ

  • name: パス情報を含まないファイル名。(DOMString)

  • fullPath: ファイルのフルパス（ファイル名を含む）。(DOMString)

  • type: ファイルのMIMEタイプ (DOMString)

  • lastModifiedDate: ファイルが最後に変更された日時。(Date)

  • size: ファイルのサイズ（バイト単位）。(Number)

メソッド

  • MediaFile.getFormatData: メディアファイルの形式情報を取得します。

MediaFileData

メディアファイルに関する形式情報をカプセル化します。

プロパティ

  • codecs: オーディオおよびビデオコンテンツの実際の形式。(DOMString)

  • bitrate: コンテンツの平均ビットレート。画像は0になります。(Number)

  • height: 画像またはビデオの高さをピクセル単位で表します。オーディオクリップの場合は0になります。(Number)

  • width: 画像またはビデオの幅をピクセル単位で表します。オーディオクリップの場合は0になります。(Number)

  • duration: ビデオまたはサウンドクリップの長さ（秒単位）。画像は0になります。(Number)

Android特有の動作

次のMediaFileDataプロパティをサポートしています。

  • codecs: サポートされておらず、nullを返します。

  • bitrate: サポートされておらず、0を返します。

  • height: サポート: 画像ファイルとビデオファイルのみ。

  • width: サポート: 画像ファイルとビデオファイルのみ。

  • duration: サポート: オーディオファイルとビデオファイルのみ。

iOS特有の動作

次のMediaFileDataプロパティをサポートしています。

  • codecs: サポートされておらず、nullを返します。

  • bitrate: iOS4デバイスのオーディオのみでサポートされています。画像とビデオでは0を返します。

  • height: サポート: 画像ファイルとビデオファイルのみ。

  • width: サポート: 画像ファイルとビデオファイルのみ。

  • duration: サポート: オーディオファイルとビデオファイルのみ。

Androidライフサイクルの特殊性

Androidプラットフォームでオーディオ、ビデオ、または画像をキャプチャする場合、ネイティブキャプチャアプリケーションによってCordova Webviewがバックグラウンドにプッシュされた後、アプリケーションが破棄される可能性があります。この問題の完全な説明については、Androidライフサイクルガイドを参照してください。この場合、キャプチャメソッドに渡された成功および失敗コールバックは起動されず、代わりにその呼び出しの結果は、Cordova resumeイベントの後で起動されるドキュメントイベントを介して配信されます。

アプリケーションでは、次のように2つの可能なイベントを購読する必要があります。

function onDeviceReady() {
    // pendingcaptureresult is fired if the capture call is successful
    document.addEventListener('pendingcaptureresult', function(mediaFiles) {
        // Do something with result
    });

    // pendingcaptureerror is fired if the capture call is unsuccessful
    document.addEventListener('pendingcaptureerror', function(error) {
        // Handle error case
    });
}

// Only subscribe to events after deviceready fires
document.addEventListener('deviceready', onDeviceReady);

これらの結果がコードのどの部分から来ているかを追跡するのは、ユーザーの責任です。必要に応じて、pauseイベントとresumeイベントの一部として、アプリケーションの状態を保存および復元してください。これらのイベントは、Androidプラットフォームでのみ、かつキャプチャ操作中にWebviewが破棄された場合にのみ起動されることに注意してください。