# Media Capture プラグイン

テスト環境 ( バージョン番号 ) : [3.0.3](https://github.com/apache/cordova-plugin-media-capture/releases/tag/3.0.3)

このプラグインの詳細は、 [こちらの原文 ( GitHub )](https://github.com/apache/cordova-plugin-media-capture) をご確認ください。

このプラグインを使用して、端末側の録音・録画 ( オーディオ・画像・動画 ) 機能にアクセスします。

このプラグインは、グローバルな `navigator.device.capture` オブジェクトを定義します。\
グローバルスコープでは、`deviceready` イベントの発火後まで使用できません。

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

### プラグイン ID

```javascript
cordova-plugin-media-capture
```

### プラグインの追加方法

このプラグインを使用する場合には、Monaca クラウド IDE の \[ Cordova プラグインの管理 ] 上で、`Capture` プラグインを[有効](https://ja.docs.monaca.io/products_guide/monaca_ide/dependencies/cordova_plugin#cordova-puraguin-noinpto)にします。

### 対象プラットフォーム

* Android
* iOS

### API の解説

### オブジェクト

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

### CaptureAudioOptions

オーディオキャプチャー時の各種設定を行えます。

#### プロパティ

* **limit**: 同一のキャプチャー処理の中で、端末が録音できるオーディオクリップの最大数。値は、1以上に設定します ( デフォルトでは 1 )。
* **duration**: 1 つあたりのオーディオ サウンド クリップの最大長 (秒単位 )

#### 例

```javascript
// 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回のキャプチャー処理につき、1 回の録音のみ行います。

### CaptureImageOptions

画像キャプチャー時の各種設定を行うときに使用します。

#### プロパティ

* **limit**: 同一のキャプチャー処理の中で、端末がキャプチャーできる画像の最大数。値は、1 以上に設定します ( デフォルトでは 1 )。

#### 例

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

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

#### iOS 特有の動作

* **limit** パラメーターは使用できません。1 回の実行につき、1つの画像のみキャプチャーします。

### CaptureVideoOptions

ビデオキャプチャー時の各種設定を行う時に使用します。

#### プロパティ

* **limit**: 同一のキャプチャー処理の中で、端末が録画できるビデオクリップの最大数。値は、1以上に設定します ( デフォルトでは 1 )。
* **duration**: 1 つあたりのビデオクリップの最大長 ( 秒単位 )

#### 例

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

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

#### iOS 特有の動作

* **limit** プロパティは無視されます。1 回の実行につき、1回のビデオ録画のみ行います。

#### Android 特有の動作

* Android では、**quality** プロパティも使用できます。このプロパティを使用して、画質 (quality ) を変えて、ビデオをキャプチャーできます。このプロパティに `1` ( デフォルト ) を設定した場合、高画質 ( HQ ) になり、`0`を設定した場合、低画質 ( LQ ) になります。低画質のビデオは、MMS メッセージなどで使用するときに有用です。詳細は、[こちら](http://developer.android.com/reference/android/provider/MediaStore.html#EXTRA_VIDEO_QUALITY)をご確認ください。

#### 例 ( Android w/ quality )

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

### CaptureCallback

メディアキャプチャー処理の成功時に呼び出されます。

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

#### 解説

キャプチャー処理の成功時に、この関数が実行されます。この時には、メディアファイルのキャプチャーが最低 1 回は終了しており、加えて、メディアキャプチャー用アプリをユーザーが終了させたか、または、キャプチャー数が最大数に達してい

各 `MediaFile` オブジェクトには、キャプチャーしたメディアファイルに関する情報が格納されています。

#### 例

```javascript
// 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

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

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

#### 解説

メディアのキャプチャー処理を開始して、エラーが発生した場合、この関数が実行されます。想定できるエラー発生のシナリオとして、キャプチャー用のアプリがビジー ( busy ) 状態の場合、キャプチャー処理がすでに実行されている場合、メディアファイルのキャプチャー前にユーザーが処理をキャンセルした場合などが考えられます。

適切なエラーコード ( `code` ) が格納された `CaptureError` オブジェクトを使用して、この関数が実行されます。

#### 例

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

### ConfigurationData

メディアキャプチャー用の各種パラメーターを設定するときに使用します。

#### 解説

メディアキャプチャーの各種情報 ( MIME タイプ、ビデオ・画像キャプチャーの各種情報など ) を設定できます。サポートされているプロパティは、端末毎に異なります。

MIME タイプに関しては、[RFC2046](http://www.ietf.org/rfc/rfc2046.txt) に準拠する必要があります。次に例を示します。

* `video/3gpp`
* `video/quicktime`
* `image/jpeg`
* `audio/amr`
* `audio/wav`

#### プロパティ

* **type**: メディアタイプを示す、ASCII でエンコードされた小文字の文字列 (DOMString)
* **height**: ピクセル単位で示す、画像またはビデオの縦の長さ。サウンドクリップに関しては、「0 」 に設定します。 (Number)
* **width**: ピクセル単位で示す、画像またはビデオの横幅。サウンドクリップに関しては、「0 」 に設定します。 (Number)

#### 例

```javascript
// 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

キャプチャーしたメディアファイルの各種プロパティを設定するときに使用します。

#### プロパティ

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

オーディオ録音用アプリの起動、および、キャプチャーしたオーディオクリップ ファイルの情報を返します。

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

#### 解説

端末に標準搭載されたオーディオ録音用のアプリを使用して、オーディオのキャプチャー ( 非同期処理 ) を行います。この処理では、同一セッション内で、複数の録音を行うことができます。

オーディオ録音アプリを終了したとき、または、`CaptureAudioOptions.limit` で指定した最大録音数に達したとき、キャプチャー処理は終了します。`limit` パラメーターを指定しない場合、「 1 」 がデフォルトとなります。この場合、1 つのオーディオクリップを録音したあとに、キャプチャー処理が終了します。

キャプチャー処理が終了するときには、`MediaFile` オブジェクト ( 群 ) の配列を使用して、 `CaptureCB` コールバックが実行されます。各 MediaFile オブジェクトには、キャプチャーしたオーディオ クリップ ファイルに関する情報が格納されています。オーディオクリップのキャプチャー前に、ユーザーが処理を終了させた場合、 `CaptureError` オブジェクトを使用して、`CaptureErrorCallback` が実行されます。`CaptureError` オブジェクトには、`CaptureError.CAPTURE_NO_MEDIA_FILES` エラーコードが格納されています。

#### 例

```javascript
// 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 には、標準のオーディオ録音アプリがありません。簡易なユーザーインターフェースのみ提供されています。

### capture.captureImage

カメラアプリの起動、および、キャプチャーした画像ファイルの情報を返します。

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

#### 解説

端末に標準搭載されているカメラアプリを使用して、画像のキャプチャーを行います ( 非同期処理 )。この処理では、同一セッション内で、複数のキャプチャーを行うことができます。

カメラアプリを終了したとき、または、`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>` タグに以下のように設定します。

```markup
<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>
```

#### 例

```javascript
// 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

ビデオ録画アプリの起動、および、キャプチャーしたビデオクリップファイルの情報を返します。

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

#### 解説

端末に標準搭載されているビデオ録画アプリを使用して、ビデオのキャプチャーを行います ( 非同期処理 )。この処理では、同一セッション内で、複数のキャプチャーを行うことができます。

ビデオ録画アプリを終了したとき、または、`CaptureVideoOptions.limit` で指定した最大録画数に達したとき、キャプチャー処理は終了します。`limit` パラメーターを指定しない場合、「 1 」 がデフォルトとなります。この場合、1 つのビデオクリップを録画したあとに、キャプチャー処理が終了します。

キャプチャー処理が終了するときには、`MediaFile` オブジェクト ( 群 ) の配列を使用して、 `CaptureCB` コールバックが実行されます。各 MediaFile オブジェクトには、キャプチャーしたビデオクリップファイルに関する情報が格納されています。ビデオクリップのキャプチャー前に、ユーザーが処理を終了させた場合、 `CaptureError` オブジェクトを使用して、`CaptureErrorCB` コールバックが実行されます。`CaptureError` オブジェクトには、`CaptureError.CAPTURE_NO_MEDIA_FILES` エラーコードが格納されています。

#### 例

```javascript
// 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});
```

### MediaFile.getFormatData

キャプチャーしたメディア ファイルのフォーマット情報を取得できます。

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

#### 解説

メディアファイルのフォーマット情報を取得できます ( 非同期処理 )。成功時には、`MediaFileData` オブジェクトを使用して、`MediaFileDataSuccessCB` コールバックが呼び出されます。失敗時には、 `MediaFileDataErrorCB` コールバックが呼び出されます。

#### Android 特有の動作

メディアファイルのフォーマット情報にアクセスできる API には、さまざまな制約が設けられています ( 一部の `MediaFileData` プロパティのみサポートされています )。

#### iOS 特有の動作

メディアファイルのフォーマット情報にアクセスできる API には、さまざまな制約が設けられています ( 一部の `MediaFileData` プロパティのみサポートされています )。

## プロパティ

* **supportedAudioModes**: 端末がサポートしている、オーディオの録音形式 (ConfigurationData\[])
* **supportedImageModes**:  端末がサポートしている、画像のサイズと形式 (ConfigurationData\[])
* **supportedVideoModes**: 端末がサポートしている、ビデオ録画の解像度と形式 (ConfigurationData\[])

## Android の 「 ライフサイクル 」 に起因する注意点

Android プラットフォーム上で、オーディオ・ビデオ・画像をキャプチャーする場合、ネイティブ側のキャプチャー用アプリが起動され、Cordova Webview がバックグラウンド処理に切り替わったタイミングで、アプリ自体 ( Cordova が動作中 ) が強制終了 ( kill ) させられる場合があります。この問題の詳細は、 [Android Lifecycle Guide](http://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html#lifecycle-guide) をご確認ください。強制終了させられた場合、キャプチャー処理のメソッドに指定されていた成功時または失敗時のコールバックは実行されません。未処理/保留されている実行結果は、Cordova の [resume event](http://cordova.apache.org/docs/en/latest/cordova/events/events.html#resume) イベント後に実行される document イベントで使用できます ( resume イベントに関する詳細は、左記の 「 ライフサイクルに関する注意点 」 を参照のこと )。

なお、アプリ内では、次のように、どちらのイベントにも対応できるように記述 ( サブスクライブ/subscribe ) しておくことを推奨します。

```javascript
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](http://cordova.apache.org/docs/en/latest/cordova/events/events.html#pause) イベントと [resume](http://cordova.apache.org/docs/en/latest/cordova/events/events.html#resume) イベントで適宜行うことが必要です。なお、これらのイベントは、Android プラットフォーム上でのみ使用でき、加えて、キャプチャー実行時、WebView が強制終了された場合のみ使用できます。

関連項目:

* [サードパーティー製プラグイン](https://ja.docs.monaca.io/reference/third_party_phonegap)
* [基本プラグイン](https://ja.docs.monaca.io/reference/core-cordova-plugins)