Media Capture プラグイン
テスト環境 ( バージョン番号 ) : 4.0.0
このプラグインの詳細は、 こちらの原文 ( GitHub ) をご確認ください。
このプラグインを使用して、端末側の録音・録画 ( オーディオ・画像・動画 ) 機能にアクセスします。
このプラグインは、グローバルな navigator.device.capture
オブジェクトを定義します。
グローバルスコープでは、deviceready
イベントの発火後まで使用できません。
プラグイン ID
プラグインの追加方法
このプラグインを使用する場合には、Monaca クラウド IDE の [ Cordova プラグインの管理 ] 上で、Capture
プラグインを有効にします。
対象プラットフォーム
Android
iOS
API の解説
オブジェクト
Capture
CaptureAudioOptions
CaptureImageOptions
CaptureVideoOptions
CaptureCallback
CaptureErrorCB
ConfigurationData
MediaFile
MediaFileData
CaptureAudioOptions
オーディオキャプチャー時の各種設定を行えます。
プロパティ
limit: 同一のキャプチャー処理の中で、端末が録音できるオーディオクリップの最大数。値は、1以上に設定します ( デフォルトでは 1 )。
duration: 1 つあたりのオーディオ サウンド クリップの最大長 (秒単位 )
例
Android 特有の動作
duration
パラメーターは使用できません。よって、録音時間はプログラムで制御できません。
iOS 特有の動作
limit
パラメーターは使用できません。1回のキャプチャー処理につき、1 回の録音のみ行います。
CaptureImageOptions
画像キャプチャー時の各種設定を行うときに使用します。
プロパティ
limit: 同一のキャプチャー処理の中で、端末がキャプチャーできる画像の最大数。値は、1 以上に設定します ( デフォルトでは 1 )。
例
iOS 特有の動作
limit パラメーターは使用できません。1 回の実行につき、1つの画像のみキャプチャーします。
CaptureVideoOptions
ビデオキャプチャー時の各種設定を行う時に使用します。
プロパティ
limit: 同一のキャプチャー処理の中で、端末が録画できるビデオクリップの最大数。値は、1以上に設定します ( デフォルトでは 1 )。
duration: 1 つあたりのビデオクリップの最大長 ( 秒単位 )
例
iOS 特有の動作
limit プロパティは無視されます。1 回の実行につき、1回のビデオ録画のみ行います。
Android 特有の動作
Android では、quality プロパティも使用できます。このプロパティを使用して、画質 (quality ) を変えて、ビデオをキャプチャーできます。このプロパティに
1
( デフォルト ) を設定した場合、高画質 ( HQ ) になり、0
を設定した場合、低画質 ( LQ ) になります。低画質のビデオは、MMS メッセージなどで使用するときに有用です。詳細は、こちらをご確認ください。
例 ( Android w/ quality )
CaptureCallback
メディアキャプチャー処理の成功時に呼び出されます。
解説
キャプチャー処理の成功時に、この関数が実行されます。この時には、メディアファイルのキャプチャーが最低 1 回は終了しており、加えて、メディアキャプチャー用アプリをユーザーが終了させたか、または、キャプチャー数が最大数に達してい
各 MediaFile
オブジェクトには、キャプチャーしたメディアファイルに関する情報が格納されています。
例
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
メディアのキャプチャー処理中に、エラーが発生した場合に呼び出されます。
解説
メディアのキャプチャー処理を開始して、エラーが発生した場合、この関数が実行されます。想定できるエラー発生のシナリオとして、キャプチャー用のアプリがビジー ( busy ) 状態の場合、キャプチャー処理がすでに実行されている場合、メディアファイルのキャプチャー前にユーザーが処理をキャンセルした場合などが考えられます。
適切なエラーコード ( code
) が格納された CaptureError
オブジェクトを使用して、この関数が実行されます。
例
ConfigurationData
メディアキャプチャー用の各種パラメーターを設定するときに使用します。
解説
メディアキャプチャーの各種情報 ( MIME タイプ、ビデオ・画像キャプチャーの各種情報など ) を設定できます。サポートされているプロパティは、端末毎に異なります。
MIME タイプに関しては、RFC2046 に準拠する必要があります。次に例を示します。
video/3gpp
video/quicktime
image/jpeg
audio/amr
audio/wav
プロパティ
type: メディアタイプを示す、ASCII でエンコードされた小文字の文字列 (DOMString)
height: ピクセル単位で示す、画像またはビデオの縦の長さ。サウンドクリップに関しては、「0 」 に設定します。 (Number)
width: ピクセル単位で示す、画像またはビデオの横幅。サウンドクリップに関しては、「0 」 に設定します。 (Number)
例
一部のプラットフォームでのみ、サポートしています。サポートされていない場合、配列には、なにも入っていません。
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: iOS 4 上でのみ使用できます (対象はオーディオのみ、画像・ビデオに関しては、「 0 」 を返します。 )
height: 使用できます。画像・ビデオファイルのみが対象です。
width: 使用できます。画像・ビデオファイルのみが対象です。
duration: 使用できます。オーディオ・ビデオファイルのみが対象です。
メソッド
capture.captureAudio
capture.captureImage
capture.captureVideo
MediaFile.getFormatData
capture.captureAudio
オーディオ録音用アプリの起動、および、キャプチャーしたオーディオクリップ ファイルの情報を返します。
解説
端末に標準搭載されたオーディオ録音用のアプリを使用して、オーディオのキャプチャー ( 非同期処理 ) を行います。この処理では、同一セッション内で、複数の録音を行うことができます。
オーディオ録音アプリを終了したとき、または、CaptureAudioOptions.limit
で指定した最大録音数に達したとき、キャプチャー処理は終了します。limit
パラメーターを指定しない場合、「 1 」 がデフォルトとなります。この場合、1 つのオーディオクリップを録音したあとに、キャプチャー処理が終了します。
キャプチャー処理が終了するときには、MediaFile
オブジェクト ( 群 ) の配列を使用して、 CaptureCB
コールバックが実行されます。各 MediaFile オブジェクトには、キャプチャーしたオーディオ クリップ ファイルに関する情報が格納されています。オーディオクリップのキャプチャー前に、ユーザーが処理を終了させた場合、 CaptureError
オブジェクトを使用して、CaptureErrorCallback
が実行されます。CaptureError
オブジェクトには、CaptureError.CAPTURE_NO_MEDIA_FILES
エラーコードが格納されています。
例
iOS 特有の動作
iOS には、標準のオーディオ録音アプリがありません。簡易なユーザーインターフェースのみ提供されています。
capture.captureImage
カメラアプリの起動、および、キャプチャーした画像ファイルの情報を返します。
解説
端末に標準搭載されているカメラアプリを使用して、画像のキャプチャーを行います ( 非同期処理 )。この処理では、同一セッション内で、複数のキャプチャーを行うことができます。
カメラアプリを終了したとき、または、CaptureImageOptions.limit
で指定した最大撮影数に達したとき、キャプチャー処理は終了します。limit
パラメーターを指定しない場合、「 1 」 がデフォルトとなります。この場合、1 つの画像を撮影したあとに、キャプチャー処理が終了します。
キャプチャー処理が終了するときには、MediaFile
オブジェクト ( 群 ) の配列を使用して、 CaptureCB
コールバックが実行されます。各 MediaFile オブジェクトには、キャプチャーした画像ファイルに関する情報が格納されています。画像のキャプチャー前に、ユーザーが処理を終了させた場合、 CaptureError
オブジェクトを使用して、CaptureErrorCB
コールバックが実行されます。CaptureError
オブジェクトには、CaptureError.CAPTURE_NO_MEDIA_FILES
エラーコードが格納されています。
対象プラットフォーム
Android
iOS
iOS 特有の動作
iOS 10以降、プライバシーに関連するデータにアクセスする場合は、 info.plist
に使用の説明を設定することが必須になります。アクセスを許可するようにシステムに指示すると、この使用の説明はアクセス許可ダイアログボックスの一部として表示されますが、使用の説明を入力しない場合は、ダイアログが表示される前にアプリが強制終了します。また、Apple は個人データにアクセスするアプリをリジェクトしますが、使用の説明は提供していません。
このプラグインでは、次の使用の説明が必要になります。
NSCameraUsageDescription
には、アプリがユーザーのカメラにアクセスする理由を記述します。NSMicrophoneUsageDescription
は、アプリがユーザーのマイクにアクセスする理由を記述します。NSPhotoLibraryUsageDescriptionentry
は、アプリケーションがユーザの写真ライブラリにアクセスする理由を記述します。
これらの設定を info.plist
に追加するには、config.xml
ファイルの <edit-config>
タグに以下のように設定します。
例
capture.captureVideo
ビデオ録画アプリの起動、および、キャプチャーしたビデオクリップファイルの情報を返します。
解説
端末に標準搭載されているビデオ録画アプリを使用して、ビデオのキャプチャーを行います ( 非同期処理 )。この処理では、同一セッション内で、複数のキャプチャーを行うことができます。
ビデオ録画アプリを終了したとき、または、CaptureVideoOptions.limit
で指定した最大録画数に達したとき、キャプチャー処理は終了します。limit
パラメーターを指定しない場合、「 1 」 がデフォルトとなります。この場合、1 つのビデオクリップを録画したあとに、キャプチャー処理が終了します。
キャプチャー処理が終了するときには、MediaFile
オブジェクト ( 群 ) の配列を使用して、 CaptureCB
コールバックが実行されます。各 MediaFile オブジェクトには、キャプチャーしたビデオクリップファイルに関する情報が格納されています。ビデオクリップのキャプチャー前に、ユーザーが処理を終了させた場合、 CaptureError
オブジェクトを使用して、CaptureErrorCB
コールバックが実行されます。CaptureError
オブジェクトには、CaptureError.CAPTURE_NO_MEDIA_FILES
エラーコードが格納されています。
例
MediaFile.getFormatData
キャプチャーしたメディア ファイルのフォーマット情報を取得できます。
解説
メディアファイルのフォーマット情報を取得できます ( 非同期処理 )。成功時には、MediaFileData
オブジェクトを使用して、MediaFileDataSuccessCB
コールバックが呼び出されます。失敗時には、 MediaFileDataErrorCB
コールバックが呼び出されます。
Android 特有の動作
メディアファイルのフォーマット情報にアクセスできる API には、さまざまな制約が設けられています ( 一部の MediaFileData
プロパティのみサポートされています )。
iOS 特有の動作
メディアファイルのフォーマット情報にアクセスできる API には、さまざまな制約が設けられています ( 一部の MediaFileData
プロパティのみサポートされています )。
プロパティ
supportedAudioModes: 端末がサポートしている、オーディオの録音形式 (ConfigurationData[])
supportedImageModes: 端末がサポートしている、画像のサイズと形式 (ConfigurationData[])
supportedVideoModes: 端末がサポートしている、ビデオ録画の解像度と形式 (ConfigurationData[])
Android の 「 ライフサイクル 」 に起因する注意点
Android プラットフォーム上で、オーディオ・ビデオ・画像をキャプチャーする場合、ネイティブ側のキャプチャー用アプリが起動され、Cordova Webview がバックグラウンド処理に切り替わったタイミングで、アプリ自体 ( Cordova が動作中 ) が強制終了 ( kill ) させられる場合があります。この問題の詳細は、 Android Lifecycle Guide をご確認ください。強制終了させられた場合、キャプチャー処理のメソッドに指定されていた成功時または失敗時のコールバックは実行されません。未処理/保留されている実行結果は、Cordova の resume event イベント後に実行される document イベントで使用できます ( resume イベントに関する詳細は、左記の 「 ライフサイクルに関する注意点 」 を参照のこと )。
なお、アプリ内では、次のように、どちらのイベントにも対応できるように記述 ( サブスクライブ/subscribe ) しておくことを推奨します。
コード内における、キャプチャー結果を処理する場所は、開発者側で自由に設定できますが ( 上記の 「 ライフサイクル 」 を参照のこと )、アプリ側の処理の ( 保留する/されている処理 ) の保存と復旧は、それぞれ、pause イベントと resume イベントで適宜行うことが必要です。なお、これらのイベントは、Android プラットフォーム上でのみ使用でき、加えて、キャプチャー実行時、WebView が強制終了された場合のみ使用できます。
最終更新