cordova-plugin-media

Этот плагин предоставляет возможность записи и воспроизведения аудиофайлов на устройстве.

ПРИМЕЧАНИЕ: Текущая реализация не соответствует спецификации W3C для захвата медиа и предоставляется только для удобства. Будущая реализация будет соответствовать последней спецификации W3C и может устареть текущие API.

Этот плагин определяет глобальный Media конструктор.

Несмотря на глобальное объявление, он недоступен до события deviceready.

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

Сообщите об ошибках в этом плагине на форуме отслеживания проблем Apache Cordova

Установка

cordova plugin add cordova-plugin-media

Поддерживаемые платформы

• Android
• BlackBerry 10
• iOS
• Windows Phone 7 и 8
• Tizen
• Windows 8
• Windows
• Браузер

Особенности Windows Phone

• Одновременно может воспроизводиться только один медиафайл.

Медиа

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

Параметры

• src: URI, содержащий аудиоконтент. (DOMString)

• mediaSuccess: (Необязательно) Обработчик, который выполняется после завершения текущего действия воспроизведения, записи или остановки объектом Media. (Функция)

• mediaError: (Необязательно) Обработчик, который выполняется при возникновении ошибки. (Функция)

• mediaStatus: (Необязательно) Обработчик, который выполняется для указания изменений состояния. (Функция)

ПРИМЕЧАНИЕ: 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: Остановить воспроизведение аудиофайла.

Дополнительные параметры только для чтения

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

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

Примечание: Чтобы разрешить воспроизведение при заблокированном экране или фоновом аудио, вам нужно добавить audio к UIBackgroundModes в файле info.plist . Смотрите документацию 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

Освобождает системные аудиоресурсы. Это особенно важно для Android, так как количество экземпляров OpenCore для воспроизведения медиа ограничено. Приложения должны вызывать функцию release для любого ресурса Media, который больше не нужен.

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

Особенности BlackBerry 10

• Не поддерживается на устройствах BlackBerry OS 5.

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
• Windows Phone 7 и 8
• Windows

Быстрый пример

// 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. Доступ к нему можно получить через API File с помощью LocalFileSystem.TEMPORARY. Любой подкаталог, указанный при записи, должен уже существовать.

• Файлы можно записывать и воспроизводить, используя URI документов:

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

• Начиная с iOS 10, обязательно добавить запись NSMicrophoneUsageDescription в файл info.plist.

NSMicrophoneUsageDescription описывает причину доступа приложения к микрофону пользователя. Когда система запрашивает у пользователя разрешение, эта строка отображается в диалоговом окне. Для добавления этой записи можно передать переменную MICROPHONE_USAGE_DESCRIPTION при установке плагина.

Пример: cordova plugin add cordova-plugin-media --variable MICROPHONE_USAGE_DESCRIPTION="your usage message"

Если переменная не передана, плагин добавит пустую строку в качестве значения.

Особенности Windows

• Устройства Windows могут использовать форматы MP3, M4A и WMA для записи аудио. Однако в большинстве случаев невозможно использовать MP3 для записи аудио на устройствах Windows Phone 8.1, потому что кодер MP3 не поставляется с Windows Phone.

• Если полный путь не указан, запись выполняется в каталоге AppData/temp . Доступ к нему можно получить через API File с помощью URI LocalFileSystem.TEMPORARY или ms-appdata:///temp/<filename>.

• Любой подкаталог, указанный при записи, должен уже существовать.

Особенности Tizen

• Не поддерживается на устройствах Tizen.

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
• Windows Phone 7 и 8
• Windows

Быстрый пример

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

Особенности Tizen

• Не поддерживается на устройствах Tizen.

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