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

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

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

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

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

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

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

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

// 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.
Если полный путь не указан, запись помещается в каталог 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);
}

Ошибка медиа

Объект 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/8.x/reference/cordova-plugin-media/index.html