cordova-plugin-media

Примечание: в запросе текст технической направленности из области разработки и тестирования программного обеспечения. Основной язык текста запроса — английский.

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

Примечание: текущая реализация не соответствует спецификации W3C для захвата мультимедиа и предоставляется только для удобства. Будущая реализация будет соответствовать последней спецификации W3C и может привести к устареванию текущих API.

Этот плагин определяет глобальный конструктор Media. Хотя он находится в глобальной области видимости, он недоступен до тех пор, пока не произойдёт событие deviceready.

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

Установка

cordova plugin add cordova-plugin-media

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

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

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

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

• Существуют строгие ограничения на то, как ваше приложение взаимодействует с другими медиа. Подробнее см. в документации Microsoft.

Медиа

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

Параметры

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

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

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

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

Константы

Следующие константы передаются в качестве единственного параметра обратному вызову mediaStatus:

• Media.MEDIA_NONE = 0;
• Media.MEDIA_STARTING = 1;
• Media.MEDIA_RUNNING = 2;
• Media.MEDIA_PAUSED = 3;
• Media.MEDIA_STOPPED = 4;

Методы

• media.getCurrentPosition: возвращает текущую позицию в аудиофайле.

• media.getDuration: возвращает продолжительность аудиофайла.

• media.play: начать или возобновить воспроизведение аудиофайла.

• media.pause: приостановить воспроизведение аудиофайла.

• media.release: освобождает ресурсы аудиосистемы операционной системы.

• media.seekTo: перемещает позицию в аудиофайле.

• media.setVolume: устанавливает громкость воспроизведения аудио.

• media.startRecord: начинает запись аудиофайла.

• media.stopRecord: останавливает запись аудиофайла.

• media.stop: останавливает воспроизведение аудиофайла.

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

• position: позиция воспроизведения звука в секундах. Не обновляется автоматически во время воспроизведения; обновите с помощью getCurrentPosition.

• duration: длительность медиа в секундах. Быстрый пример

  // Аудиоплеер // var my_media = new Media(src, onSuccess, onError);

  // Обновляем позицию медиа каждую секунду var mediaTimer = setInterval(function () { // Получаем позицию медиа my_media.getCurrentPosition( // успешный обратный вызов function (position) { if (position > -1) { console.log((position) + " сек"); } }, // обратный вызов ошибки function (e) { console.log("Ошибка получения позиции=" + e); } ); }, 1000);

media.getDuration

Возвращает длительность аудиофайла в секундах. Если длительность неизвестна, возвращает значение -1.

media.getDuration();

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

// Аудиоплеер
//
var my_media = new Media(src, onSuccess, onError);

// Получаем длительность
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();

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

// Воспроизвести аудио
//
function playAudio(url) {
    // Воспроизводим аудиофайл по url
    var my_media = new Media(url,
        // успешный обратный вызов
        function () { console.log("playAudio():Аудио успешно"); },
        // обратный вызов ошибки
        function (err) { console.log("playAudio():Ошибка аудио: " + err); }
    );

    // Воспроизводим аудио
    my_media.play();

    // Приостанавливаем через 10 секунд
    setTimeout(function () {
        media.pause();
    }, 10000);
}

media.play

Запускает или возобновляет воспроизведение аудиофайла.

media.play();

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

// Воспроизвести аудио
//
function playAudio(url) {
    // Воспроизводим аудиофайл по url
    var my_media = new Media(url,
        // успешный обратный вызов
        function () {
            console.log("playAudio():Аудио успешно");
        },
        // обратный вызов ошибки
        function (err) {
            console.log("playAudio():Ошибка аудио: " + err);
        }
    );
    // Воспроизводим аудио
    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 : false })

• порядок поиска файлов: Когда предоставляется только имя файла или простой путь, iOS выполняет поиск в каталоге www, а затем в каталоге приложения documents/tmp:

    var myMedia = new Media("audio/beer.mp3")
    myMedia.play()  // сначала ищет файл в www/audio/beer.mp3, затем в <application>/documents/tmp/audio/beer.mp3

media.release

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

media.release();

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

// Аудиоплеер
//
var my_media = new Media(src, onSuccess, onError);

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

media.seekTo

Устанавливает текущую позицию в аудиофайле. media.seekTo(миллисекунды)

Параметры:

• milliseconds — позиция, на которую устанавливается позиция воспроизведения аудио в миллисекундах.

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

// Аудиоплеер
var my_media = new Media(src, onSuccess, onError);
    my_media.play();
// Переход на 10 секунд через 5 секунд
setTimeout(function() {
    my_media.seekTo(10000);
}, 5000);

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

media.setVolume

Устанавливает громкость для аудиофайла.

media.setVolume(volume);

Параметры:

• volume — громкость, которая устанавливается для воспроизведения. Значение должно быть в диапазоне от 0,0 до 1,0.

Поддерживаемые платформы: Android, iOS.

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

// Воспроизведение аудио
function playAudio(url) {
    // Воспроизвести аудиофайл по URL
    var my_media = new Media(url,
        // успешный обратный вызов
        function() {
            console.log("playAudio():Аудио успешно");
        },
        // обратный вызов ошибки
        function(err) {
            console.log("playAudio():Ошибка аудио: " + err);
    });

    // Воспроизвести аудио
    my_media.play();

    // Приглушить громкость через 2 секунды
    setTimeout(function() {
        my_media.setVolume('0.0');
    }, 2000);

    // Установить громкость на 1.0 через 5 секунд
    setTimeout(function() {
        my_media.setVolume('1.0');
    }, 5000);
}

media.startRecord

Запускает запись аудиофайла.

media.startRecord();

Поддерживаемые платформы: Android, iOS, Windows Phone 7 и 8, Windows.

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

// Запись аудио
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // успешный обратный вызов
        function() {
            console.log("recordAudio():Аудио успешно");
        },

        // обратный вызов ошибки
        function(err) {
            console.log("recordAudio():Ошибка аудио: " + err.code);
        });

    // Записать аудио
    mediaRec.startRecord();
}

Android Quirks: На устройствах Android аудио записывается в формате Adaptive Multi-Rate. Указанный файл должен заканчиваться расширением .amr. Аппаратные регуляторы громкости подключены к медиа-объёму, пока активны какие-либо объекты Media. Как только последний созданный объект Media вызывает метод release(), регуляторы громкости возвращаются к своему поведению по умолчанию. Регуляторы также сбрасываются при переходе на другую страницу, так как это освобождает все объекты Media.

iOS Quirks: iOS записывает только файлы типа .wav и возвращает ошибку, если расширение файла не соответствует. Если полный путь не указан, запись помещается в каталог documents/tmp приложения. Доступ к нему можно получить через API File с помощью LocalFileSystem.TEMPORARY. Любой подкаталог, указанный во время записи, должен уже существовать. Файлы можно записывать и воспроизводить с использованием URI документов:

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

Windows Quirks: Устройства Windows могут использовать форматы MP3, M4A и WMA для записанного аудио. Однако в большинстве случаев невозможно использовать MP3 для записи аудио на устройствах Windows Phone 8.1, поскольку кодировщик MP3 не поставляется с Windows Phone. Если полный путь не указан, запись размещается в каталоге AppData/temp. Доступ к нему можно получить с помощью API File, используя LocalFileSystem.TEMPORARY или 'ms-appdata:///temp/' URI. Любой подкаталог, указанный во время записи, должен уже существовать.

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

media.stop

Останавливает воспроизведение аудиофайла.

media.stop();

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

// Воспроизведение аудио
function playAudio(url) {
    // Воспроизвести аудиофайл по URL
    var my_media = new Media(url,
        // успешный обратный вызов
        function() {
            console.log("playAudio():Аудио успешно");
        },
        // обратный вызов ошибки

playAudio()

Воспроизводит аудио.

playAudio();

Пример использования

// Воспроизвести аудио
function playAudio() {
    my_media.play();
}

// Пауза через 10 секунд
setTimeout(function() {
        my_media.stop();
    }, 10000);
}

media.stopRecord

Останавливает запись аудиофайла.

media.stopRecord();

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

• Android
• iOS
• Windows Phone 7 и 8
• Windows

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

// Записать аудио
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // успешный обратный вызов
        function() {
            console.log("recordAudio():Аудио успешно");
        },

        // обратный вызов ошибки
        function(err) {
            console.log("recordAudio():Ошибка аудио: "+ err.code);
        }
    );

    // Записать аудио
    mediaRec.startRecord();

    // Остановить запись через 10 секунд
    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