Spec-Zone.ru › Cordova 9

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
  • iOS
  • Windows
  • Браузер

Медиа

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: Остановить воспроизведение аудиофайла.

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

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

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

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

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

Для этого плагина требуется следующее описание использования:

  • NSMicrophoneUsageDescription описывает причину доступа приложения к микрофону пользователя.

Чтобы добавить эту запись в info.plist, можно использовать тег edit-config в файле config.xml следующим образом:

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

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

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

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

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

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

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

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

Параметры

  • скорость: Скорость воспроизведения.

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

// 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.MEDIA_ERR_ABORTED = 1
  • MediaError.MEDIA_ERR_NETWORK = 2
  • MediaError.MEDIA_ERR_DECODE = 3
  • MediaError.MEDIA_ERR_NONE_SUPPORTED = 4

© 2012, 2013, 2015 The Apache Software Foundation
Licensed under the Apache License 2.0.
https://cordova.apache.org/docs/en/9.x/reference/cordova-plugin-media/index.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API