<!--
# license: Licensed to the Apache Software Foundation (ASF) under one
#         or more contributor license agreements.  See the NOTICE file
#         distributed with this work for additional information
#         regarding copyright ownership.  The ASF licenses this file
#         to you under the Apache License, Version 2.0 (the
#         "License"); you may not use this file except in compliance
#         with the License.  You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#         Unless required by applicable law or agreed to in writing,
#         software distributed under the License is distributed on an
#         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
#         KIND, either express or implied.  See the License for the
#         specific language governing permissions and limitations
#         under the License.
-->

# cordova-plugin-media

[![Build Status](https://travis-ci.org/apache/cordova-plugin-media.svg)](https://travis-ci.org/apache/cordova-plugin-media)

Questo plugin consente di registrare e riprodurre i file audio su un dispositivo.

**Nota**: l'implementazione attuale non aderisce a una specifica del W3C per l'acquisizione di mezzi e viene fornito solo per comodità. Una futura realizzazione aderirà alla specifica W3C più recente e può deprecare le API corrente.

Questo plugin definisce un costruttore `Media` globale.

Anche se in ambito globale, non è disponibile fino a dopo l'evento `deviceready`.

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

## Installazione

    cordova plugin add cordova-plugin-media
    

## Piattaforme supportate

  * Android
  * BlackBerry 10
  * iOS
  * Windows Phone 7 e 8
  * Tizen
  * Windows 8
  * Windows
  * Browser

## Stranezze di Windows Phone

  * File sola multimediale può essere riprodotti in un momento.

  * Ci sono severe restrizioni su come l'applicazione interagisce con altri media. Vedere la [documentazione di Microsoft per maggiori dettagli](http://msdn.microsoft.com/en-us/library/windowsphone/develop/hh184838(v=vs.92).aspx).

## Media

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

### Parametri

  * **src**: un URI contenente il contenuto audio. *(DOMString)*

  * **mediaSuccess**: (facoltativo) il callback che viene eseguito dopo un `Media` oggetto ha completato il gioco corrente, record o interrompere l'azione. *(Funzione)*

  * **errore mediaError**: (facoltativo) il callback che viene eseguito se si verifica un errore. *(Funzione)*

  * **mediaStatus**: (facoltativo) il callback che viene eseguito per indicare i cambiamenti di stato. *(Funzione)*

### Costanti

Costanti sono segnalate come unico parametro al metodo di callback `mediaStatus`:

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

### Metodi

  * `media.getCurrentPosition`: Restituisce la posizione corrente all'interno di un file audio.

  * `media.getDuration`: Restituisce la durata di un file audio.

  * `media.play`: Iniziare o riprendere la riproduzione di un file audio.

  * `media.pause`: Pausa la riproduzione di un file audio.

  * `media.release`: Libera risorse audio del sistema operativo sottostante.

  * `media.seekTo`: Sposta la posizione all'interno del file audio.

  * `media.setVolume`: Impostare il volume per la riproduzione audio.

  * `media.startRecord`: Iniziare a registrare un file audio.

  * `media.stopRecord`: Interrompere la registrazione di un file audio.

  * `media.stop`: Interrompere la riproduzione di un file audio.

### Parametri supplementari ReadOnly

  * **posizione**: la posizione all'interno della riproduzione audio, in pochi secondi.
    
      * Non aggiornate automaticamente durante il gioco; chiamare `getCurrentPosition` per l'aggiornamento.

  * **durata**: la durata dei media, in secondi.

## media.getCurrentPosition

Restituisce la posizione corrente all'interno di un file audio. Aggiorna anche il parametro di `position` dell'oggetto `Media`.

    media.getCurrentPosition(mediaSuccess, [mediaError]);
    

### Parametri

  * **mediaSuccess**: il callback passato la posizione corrente in pochi secondi.

  * **errore mediaError**: (facoltativo) il callback da eseguire se si verifica un errore.

### Esempio rapido

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

Restituisce la durata di un file audio in secondi. Se la durata è sconosciuta, essa restituisce un valore di -1.

    media.getDuration();
    

### Esempio rapido

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

Sospende la riproduzione di un file audio.

    media.pause();
    

### Esempio rapido

    // 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 () {
            media.pause();
        }, 10000);
    }
    

## Media.Play

Avvia o riprende la riproduzione di un file audio.

    media.play();
    

### Esempio rapido

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

  * **numberOfLoops**: passare questa opzione per il `play` metodo per specificare il numero di volte desiderato file multimediale per riprodurre, ad esempio:
    
        var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
        myMedia.play({ numberOfLoops: 2 })
        

  * **playAudioWhenScreenIsLocked**: questa opzione per passare il `play` metodo per specificare se si desidera consentire la riproduzione quando lo schermo è bloccato. Se impostato su `true` (il valore predefinito), viene ignorato lo stato del pulsante mute hardware, ad esempio:
    
        var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
        myMedia.play({ playAudioWhenScreenIsLocked : false })
        

  * **ordine di ricerca di file**: quando viene fornito solo un nome file o percorso semplice, cerca in iOS il `www` directory per il file, quindi l'applicazione `documents/tmp` directory:
    
        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

Rilascia le risorse audio del sistema operativo sottostante. Ciò è particolarmente importante per Android, dato che ci sono una quantità finita di OpenCore istanze per la riproduzione multimediale. Le applicazioni devono chiamare la funzione di `release` qualsiasi risorsa `Media` non è più necessario.

    media.release();
    

### Esempio rapido

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

## media.seekTo

Imposta la posizione corrente all'interno di un file audio.

    media.seekTo(milliseconds);
    

### Parametri

  * **millisecondi**: posizione per impostare la posizione di riproduzione all'interno l'audio, in millisecondi.

### Esempio rapido

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

  * Non è supportato sui dispositivi BlackBerry OS 5.

## media.setVolume

Impostare il volume per un file audio.

    media.setVolume(volume);
    

### Parametri

  * **volume**: il volume impostato per la riproduzione. Il valore deve essere all'interno della gamma di 0,0 e 1,0.

### Piattaforme supportate

  * Android
  * iOS

### Esempio rapido

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

Avvia la registrazione di un file audio.

    media.startRecord();
    

### Piattaforme supportate

  * Android
  * iOS
  * Windows Phone 7 e 8
  * Windows

### Esempio rapido

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

### Stranezze Android

  * Dispositivi Android registrano audio in formato Adaptive Multi-Rate. Il file specificato deve terminare con l'estensione ** .
  * I controlli di volume di hardware sono cablati a volume media mentre eventuali oggetti multimediali sono vivi. Una volta l'ultimi Media creati oggetto ha `release()` chiamato su di esso, i controlli di volume di tornare alla loro comportamento predefinito. I controlli vengono reimpostati anche sulla pagina di navigazione, come questo rilascia tutti gli oggetti multimediali.

### iOS stranezze

  * iOS solo i record per i file di tipo *WAV* e restituisce un errore se il file di nome estensione è non corretto.

  * Se non è specificato un percorso completo, la registrazione viene inserita nell'applicazione `documents/tmp` directory. Questo si può accedere tramite il `File` API utilizzando `LocalFileSystem.TEMPORARY` . Deve esistere alcuna sottodirectory specificate a tempo di record.

  * I file possono essere registrati e giocati indietro usando i documenti URI:
    
        var myMedia = new Media("documents://beer.mp3")
        

### Stranezze di Windows

  * Dispositivi Windows possono utilizzare MP3, M4A e WMA formati per l'audio registrato. Tuttavia, nella maggior parte dei casi non è possibile utilizzare MP3 per la registrazione audio su dispositivi *Windows Phone 8.1* , perché un encoder MP3 è [non forniti con Windows Phone](https://msdn.microsoft.com/en-us/library/windows/apps/windows.media.mediaproperties.mediaencodingprofile.createmp3.aspx).

  * Se non è specificato un percorso completo, la registrazione viene inserita nella directory AppData/temp. Questo si può accedere tramite il `File` Utilizzando API `LocalFileSystem.TEMPORARY` o ' ms-appdata: / / temp /<filename>' URI.

  * Deve esistere alcuna sottodirectory specificate a tempo di record.

### Tizen stranezze

  * Tizen periferiche non supportano.

## media.stop

Interrompe la riproduzione di un file audio.

    media.stop();
    

### Esempio rapido

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

Smette di registrare un file audio.

    media.stopRecord();
    

### Piattaforme supportate

  * Android
  * iOS
  * Windows Phone 7 e 8
  * Windows

### Esempio rapido

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

  * Tizen periferiche non supportano.

## Errore MediaError

Un oggetto ` MediaError` viene restituito alla funzione di callback ` mediaError` quando si verifica un errore.

### Proprietà

  * **codice**: uno dei codici di errore predefiniti elencati di seguito.

  * **messaggio**: un messaggio di errore che descrive i dettagli dell'errore.

### Costanti

  * `MediaError.MEDIA_ERR_ABORTED`= 1
  * `MediaError.MEDIA_ERR_NETWORK`= 2
  * `MediaError.MEDIA_ERR_DECODE`= 3
  * `MediaError.MEDIA_ERR_NONE_SUPPORTED`= 4