# Media プラグイン

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

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

このプラグインを使用して、オーディオファイルの再生と録音を行います。

{% hint style="info" %}
現在の実装方式は、W3C の仕様 ( メディアキャプチャーに関して ) に準拠しておらず、利便上提供しているものです。リリース予定の次期の実装方式では、最新の W3C の仕様に準拠する予定です。また、その場合には、現在の API を廃止することもあります。
{% endhint %}

このプラグインは、グローバルな `Media` コンストラクタを定義します。\
グローバルスコープでは、`deviceready` イベントの発火後まで使用できません。

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

### プラグイン ID

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

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

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

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

* Android
* iOS

### メディアオブジェクト

```javascript
var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);
```

#### パラメーター

* **src**: オーディオコンテンツを指し示す URI *(DOMString)*
* **mediaSuccess**: ( 任意 ) `Media`オブジェクト側の再生・録音・停止処理が完了した後に、実行されるコールバック*(Function)*
* **mediaError**: ( 任意 ) エラーが発生した場合に、実行されるコールバック *(Function)*
* **mediaStatus**: ( 任意 ) ステータスが変化したことを示すときに使用されるコールバック*(Function)*

{% hint style="info" %}
`src` パラメーターには、`cdvfile` パスを使用できます。

```javascript
var my_media = new Media('cdvfile://localhost/temporary/recording.mp3', ...);
```

{% endhint %}

#### Additional ReadOnly パラメーター

* **position**: オーディオの再生位置 ( 秒単位 )
  * 再生中、自動的には値を更新しないので、`getCurrentPosition`メソッドを呼び、値を更新します。
* **duration**: メディアの再生時間 ( 秒単位 )

#### 定数

`mediaStatus` コールバックだけで使用されるパラメーターとして、次の定数があります。

* `Media.MEDIA_NONE` = 0
* `Media.MEDIA_STARTING` = 1
* `Media.MEDIA_RUNNING` = 2
* `Media.MEDIA_PAUSED` = 3
* `Media.MEDIA_STOPPED` = 4

#### メソッド

* `media.getCurrentAmplitude`: オーディオファイル内の現在の振幅を返します。
* `media.getCurrentPosition`: オーディオファイル内の現在の再生位置を返します。
* `media.getDuration`: オーディオファイルの再生時間を返します。
* `media.play`: オーディオファイルの再生を、開始または再開します。
* `media.pause`: オーディオファイルの再生を一時停止します。
* `media.pauseRecord`: オーディオファイルの録音を一時停止します。
* `media.release`: オーディオリソースを解放 ( release ) します。
* `media.resumeRecord`：オーディオファイルのレコーディングを再開します。
* `media.seekTo`: オーディオファイル内の再生位置を動かします。
* `media.setVolume`: オーディオ再生時の音量を設定します。
* `media.startRecord`: オーディオファイルの録音を開始します。
* `media.stopRecord`: オーディオファイルの録音を停止します。
* `media.stop`: オーディオファイルの再生を停止します。

#### media.getCurrentAmplitude

録音している音の振幅 ( amplitude ) を返します。

```javascript
media.getCurrentAmplitude(mediaSuccess, [mediaError]);
```

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

* Android
* iOS

#### パラメーター

* **mediaSuccess**: 取得した振幅 ( 0.0 - 1.0 )を渡して実行するコールバック
* **mediaError**: ( 任意 ) エラーの発生時に実行されるコールバック

**例**

```javascript
// Audio player
//
var my_media = new Media(src, onSuccess, onError);

// Record audio
my_media.startRecord();

mediaTimer = setInterval(function () {
    // get media amplitude
    my_media.getCurrentAmplitude(
        // success callback
        function (amp) {
            console.log(amp + "%");
        },
        // error callback
        function (e) {
            console.log("Error getting amp=" + e);
        }
    );
}, 1000);
```

#### media.getCurrentPosition

オーディオファイル内の現在の再生位置を返します。また、`Media` オブジェクト内の `position` パラメーターを更新します。

```javascript
media.getCurrentPosition(mediaSuccess, [mediaError]);
```

**パラメーター**

* **mediaSuccess**: 現在の再生位置 ( 秒単位 )を渡して実行されるコールバック
* **mediaError**: ( 任意 ) エラーの発生時に実行されるコールバック

**例**

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

オーディオファイルの再生時間を、秒単位で返します。再生時間が不明の場合には、「 -1 」 の値を返します。

```javascript
media.getDuration();
```

**例**

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

オーディオファイルの再生を、開始または再開します。

```javascript
media.play();
```

**例**

```javascript
// 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 特有の動作**

* **numberOfLoops**: このオプションを `play` メソッドに渡して、メディアファイルの再生回数を指定します。次に例を示します。

  ```javascript
  var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
  myMedia.play({ numberOfLoops: 2 });
  ```
* **playAudioWhenScreenIsLocked**: このオプションを `play` メソッドに渡して、画面にロックがかかった状態でも、再生を続行するか指定します。 `true` ( デフォルトはこちら ) に設定した場合、ハードウェア側のミュートボタンの設定を無視します。次に例を示します。

  ```javascript
  var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
  myMedia.play({ playAudioWhenScreenIsLocked : true });
  myMedia.setVolume('1.0');
  ```

{% hint style="info" %}
画面がロックされた状態またはバックグラウンドで音声を再生できるようにするには、info.plist ファイルの `UIBackgroundModes` に `audio` を追加する必要があります。 詳しくは、[ Apple ドキュメント ](https://developer.apple.com/library/content/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/BackgroundExecution/BackgroundExecution.html#//apple_ref/doc/uid/TP40007072-CH4-SW23)を参照してください。 また、バックグラウンドに移行する前に音声を再生する必要があることにも注意してください。
{% endhint %}

* **ファイルの検索順序**: ファイル名のみまたは不完全なパス ( simple path ) を指定している場合、iOS では、最初に、`www` ディレクトリー内を検索して、見つからなければ、次に、アプリの `documents/tmp` ディレクトリーを検索します。

  ```javascript
  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.pause

オーディオファイルの再生を一時停止します。

```javascript
media.pause();
```

**例**

```javascript
// 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.pause();
    }, 10000);
}
```

#### media.pauseRecord

オーディオファイルの録音を一時停止します。

```javascript
media.pauseRecord();
```

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

* iOS

**例**

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

    // Pause Recording after 5 seconds
    setTimeout(function() {
        mediaRec.pauseRecord();
    }, 5000);
}
```

#### media.release

オペレーティングシステム側のオーディオリソースを解放 ( release ) します。特に、Android では、メディア再生に割り当てることができる OpenCore インスタンスの数に限りがあるため、解放処理は重要となります。`Media` リソースが不要になった場合には、`release` メソッドを都度呼び出すことを推奨します。

```javascript
media.release();
```

**例**

```javascript
// Audio player
//
var my_media = new Media(src, onSuccess, onError);

my_media.play();
my_media.stop();
my_media.release();
```

#### media.resumeRecord

オーディオファイルの録音を再開します。

```javascript
media.resumeRecord();
```

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

* iOS

**例**

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

    // Pause Recording after 5 seconds
    setTimeout(function() {
        mediaRec.pauseRecord();
    }, 5000);

    // Resume Recording after 10 seconds
    setTimeout(function() {
        mediaRec.resumeRecord();
    }, 10000);
}
```

#### media.seekTo

オーディオファイルの再生位置を指定します。

```javascript
media.seekTo(milliseconds);
```

**パラメーター**

* **milliseconds**: オーディオの再生位置を、ミリ秒単位で指定します。

**例**

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

#### media.setVolume

オーディオファイルの音量を指定します。

```javascript
media.setVolume(volume);
```

**パラメーター**

* **volume**: 再生時の音量を指定します。0.0 から 1.0の間で、値を指定します。

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

* Android
* iOS

**例**

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

オーディオファイルの録音を開始します。

```javascript
media.startRecord();
```

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

* Android
* iOS

**例**

```javascript
// 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 特有の動作**

* Androidデバイスは、オーディオをAAC ADTSファイル形式で記録します。指定されたファイルは`.aac`拡張子で終わる必要があります。
* Media オブジェクトが存続する間は、ハードウェア側の音量設定は、オブジェクト 側の音量設定と紐付けされています。直近で作成した Media オブジェクトに対して、`release()` が呼ばれた場合、音量設定は、システム側のデフォルトの設定に戻ります。また、ページ遷移を行った場合も、設定はリセットされます ( 遷移時に、すべての Media オブジェクトが解放されるため )。

**iOS 特有の動作**

* iOSは`.wav`および`.m4a`タイプのファイルにのみ記録し、ファイル名の拡張子が正しくない場合はエラーを返します。
* フルパス ( full path ) を指定しない場合、アプリの `documents/tmp` ディレクトリーに、録音ファイルが置かれます。このファイルへのアクセスには、`ファイル操作` API ( File API ) を使用します ( `LocalFileSystem.TEMPORARY` を使用 )。録音時にサブディレクトリーを使用する場合には、事前に作成しておく必要があります。
* 「 documents\:// 」 形式の URI を使用して、ファイルを録音・再生できます。

```javascript
var myMedia = new Media("documents://beer.mp3")
```

* iOS 10以降、プライバシーに関連するデータにアクセスする場合は、 `info.plist` に使用の説明を設定することが必須になります。アクセスを許可するようにシステムに指示すると、この使用の説明はアクセス許可ダイアログボックスの一部として表示されますが、使用の説明を入力しない場合は、ダイアログが表示される前にアプリが強制終了します。また、Apple は個人データにアクセスするアプリをリジェクトしますが、使用の説明は提供していません。

このプラグインでは、次の使用の説明が必要になります。

`NSMicrophoneUsageDescription` は、アプリがユーザーのマイクにアクセスする理由を記述します。

これらの設定を `info.plist` に追加するには、`config.xml` ファイルの `<edit-config>` タグに以下のように設定します。

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

#### media.stop

オーディオファイルの再生を停止します。

```javascript
media.stop();
```

**例**

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

オーディオファイルの録音を停止します。

```javascript
media.stopRecord();
```

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

* Android
* iOS

**例**

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

## MediaError Object

エラーが発生した場合、`mediaError` コールバック関数へ `MediaError` オブジェクトが渡されます。

### プロパティ

* **code**: 次のエラーコードのいずれか
* **message**: 詳細を示したエラーメッセージ

### 定数

* `MediaError.MEDIA_ERR_ABORTED` = 1
* `MediaError.MEDIA_ERR_NETWORK` = 2
* `MediaError.MEDIA_ERR_DECODE` = 3
* `MediaError.MEDIA_ERR_NONE_SUPPORTED` = 4

関連項目:

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