cordova-plugin-media

Android Testsuite Chrome Testsuite iOS Testsuite Lint Test

このプラグインは、デバイスでのオーディオファイルの録音と再生機能を提供します。

注意: 現在の実装は、メディアキャプチャに関する W3C 仕様に準拠しておらず、便宜上のみ提供されています。将来の実装では、最新の W3C 仕様に準拠し、現在の API を非推奨にする可能性があります。

このプラグインは、グローバルな Media コンストラクタを定義します。

グローバルスコープ内にありますが、deviceready イベントの後まで利用できません。

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

インストール

cordova plugin add cordova-plugin-media

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

  • Android
  • iOS
  • ブラウザ

Android の特異性

SDK ターゲットが 29 未満

公式の Android 11 のストレージ更新ドキュメントによると、WRITE_EXTERNAL_STORAGE パーミッションはもはや動作せず、アクセスを提供しません。

Build.VERSION_CODES.Q (SDK 29) より前の API レベルをターゲットとするアプリでこのパーミッションが許可リストに追加されていない場合、このパーミッションはアプリに付与できません。

このパーミッションを追加する必要がある場合は、config.xml に以下を追加してください。

<config-file target="AndroidManifest.xml" parent="/*" xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="28" />
</config-file>

メディア

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

パラメータ

  • src: オーディオコンテンツを含む URI。(DOMString)

  • mediaSuccess: (オプション) Media オブジェクトが現在の再生、録音、または停止アクションを完了した後に実行されるコールバック。(関数)

  • mediaError: (オプション) エラーが発生した場合に実行されるコールバック。整数のエラーコードを受け取ります。(関数)

  • mediaStatus: (オプション) ステータスの変更を示すために実行されるコールバック。整数のステータスコードを受け取ります。(関数)

  • mediaDurationUpdate: (オプション) ファイルの期間が更新され、利用可能になったときに実行されるコールバック。(関数)

注意: cdvfile パスは src パラメータとしてサポートされています

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

定数

次の定数は、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: 基盤となるオペレーティングシステムのオーディオリソースを解放します。

  • media.resumeRecord: オーディオファイルの録音を再開します。

  • media.seekTo: オーディオファイル内の位置を移動します。

  • media.setVolume: オーディオ再生の音量を設定します。

  • media.startRecord: オーディオファイルの録音を開始します。

  • media.stopRecord: オーディオファイルの録音を停止します。

  • media.stop: オーディオファイルの再生を停止します。

  • media.setRate: オーディオファイルの再生速度を設定します。

追加の読み取り専用パラメータ

  • position: オーディオ再生内の位置（秒単位）。
    • 再生中に自動的に更新されません。更新するには getCurrentPosition を呼び出してください。
  • duration: メディアの期間（秒単位）。

media.getCurrentAmplitude

オーディオファイル内の現在の振幅を返します。

media.getCurrentAmplitude(mediaSuccess, [mediaError]);

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

  • Android
  • iOS

パラメータ

  • mediaSuccess: 現在の振幅 (0.0 - 1.0) が渡されるコールバック。

  • mediaError: (オプション) エラーが発生した場合に実行するコールバック。

簡単な例

// 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 パラメータも更新します。

media.getCurrentPosition(mediaSuccess, [mediaError]);

パラメータ

  • mediaSuccess: 現在の位置（秒単位）が渡されるコールバック。

  • mediaError: (オプション) エラーが発生した場合に実行するコールバック。

簡単な例

// 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 の値を返します。

media.getDuration();

簡単な例

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

Android の特異性

Android の新しいバージョンでは、バックグラウンド処理を制限する積極的なルーチンがあります。アプリがバックグラウンドで約 5 分以上経過している間に期間を取得しようとすると、コンストラクタの mediaDurationUpdate コールバックを使用すると、より一貫した結果が得られます。

media.pause

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

media.pause();

簡単な例

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

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

media.pauseRecord();

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

  • iOS

簡単な例

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

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

media.play();

簡単な例

// 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 メソッドにこのオプションを渡します。例:

      var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
  myMedia.play({ numberOfLoops: 2 })

  • playAudioWhenScreenIsLocked: 画面がロックされているときに再生を許可するかどうかを指定するには、play メソッドにこのオプションを渡します。true (デフォルト値) に設定されている場合、ハードウェアのミュートボタンの状態は無視されます。例:

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

注: 画面ロックまたはバックグラウンドオーディオで再生を許可するには、info.plist ファイルの UIBackgroundModes に audio を追加する必要があります。Apple のドキュメントを参照してください。また、バックグラウンドに移行する前にオーディオを開始する必要があることにも注意してください。

  • ファイル検索の順序: ファイル名または簡単なパスのみが指定されている場合、iOS は www ディレクトリ、次にアプリケーションの documents/tmp ディレクトリでファイルを検索します。

      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

基盤となるオペレーティングシステムのオーディオリソースを解放します。メディア再生のための OpenCore インスタンスの量が限られているため、これは Android では特に重要です。アプリケーションは、不要になった Media リソースに対して release 関数を呼び出す必要があります。

media.release();

簡単な例

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

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

media.resumeRecord

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

media.resumeRecord();

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

  • iOS

簡単な例

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

オーディオファイル内の現在の位置を設定します。

media.seekTo(milliseconds);

パラメータ

  • milliseconds: オーディオ内の再生位置を設定する位置（ミリ秒単位）。

簡単な例

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

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

media.setVolume(volume);

パラメータ

  • volume: 再生に設定する音量。値は 0.0 ～ 1.0 の範囲内である必要があります。

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

  • Android
  • iOS

簡単な例

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

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

media.startRecord();

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

  • Android
  • iOS

簡単な例

// 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 タイプのファイルのみに記録し、ファイル名拡張子が正しくない場合はエラーを返します。

  • 完全なパスが提供されていない場合、録音はアプリケーションの documents/tmp ディレクトリに配置されます。これは、LocalFileSystem.TEMPORARY を使用して File API 経由でアクセスできます。録音時に指定されたサブディレクトリは、すでに存在している必要があります。

  • ドキュメント URI を使用してファイルを録音および再生できます。

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

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

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

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

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

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

media.stop

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

media.stop();

簡単な例

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

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

media.stopRecord();

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

  • Android
  • iOS

簡単な例

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

media.setRate

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

media.setRate(rate);

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

  • iOS
  • Android (API 23+)

パラメータ

  • rate: 再生に設定するレート。

簡単な例

// Audio player
//
var my_media = new Media(src, onSuccess, onError);
    my_media.play();

// Set playback rate to 2.0x after 10 seconds
setTimeout(function() {
    my_media.setRate(2.0);
}, 5000);

MediaError

エラーが発生すると、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