# Guida introduttiva all'SDK di trasmissione IVS per il web \| Streaming a bassa latenza
<a name="broadcast-web-getting-started"></a>

Questo documento illustra i passaggi necessari per iniziare a utilizzare l'SDK di trasmissione per lo streaming a bassa latenza di Amazon IVS per il web.

## Installazione della libreria
<a name="broadcast-web-install"></a>

Tieni presente che IVSBroadcastClient sfrutta [reflect-metadata](https://www.npmjs.com/package/reflect-metadata), che estende l'oggetto Reflect globale. Sebbene ciò non dovrebbe creare conflitti, possono esserci rari casi in cui potrebbe causare comportamenti indesiderati.

### Utilizzo di un tag di script
<a name="broadcast-web-how-to-install-script"></a>

L'SDK di trasmissione Web è distribuito come libreria JavaScript e può essere recuperato all'indirizzo [https://web-broadcast.live-video.net/1.35.0/amazon-ivs-web-broadcast.js](https://web-broadcast.live-video.net/1.35.0/amazon-ivs-web-broadcast.js).

Quando viene caricata tramite il tag `<script>`, la libreria espone una variabile globale nell'ambito della finestra denominato `IVSBroadcastClient`.

### Utilizzo di npm
<a name="broadcast-web-how-to-install-npm"></a>

Per installare il pacchetto della `npm`:

```
npm install amazon-ivs-web-broadcast
```

Ora puoi accedere all'oggetto `IVSBroadcastClient` e inserire altri moduli e costanti come `Errors`, `BASIC_LANDSCAPE`:

```
import IVSBroadcastClient, {
   Errors,
   BASIC_LANDSCAPE
} from 'amazon-ivs-web-broadcast';
```

## Esempi
<a name="broadcast-web-samples"></a>

Per iniziare rapidamente, consulta gli esempi di seguito:
+ [Trasmissione singola su un canale IVS (HTML e JavaScript)](https://codepen.io/amazon-ivs/pen/poLRoPp)
+ [Trasmissione singola con condivisione dello schermo su un canale IVS](https://stream.ivs.rocks/) ([React Source Code](https://github.com/aws-samples/amazon-ivs-broadcast-web-demo))

## Creazione di un'istanza di AmazonIVSBroadcastClient
<a name="broadcast-web-instance"></a>

Per utilizzare la libreria, è necessario creare un'istanza del client. Puoi farlo richiamando il metodo`create` su `IVSBroadcastClient` con il parametro `streamConfig` (specificando i vincoli della trasmissione come risoluzione e frequenza dei fotogrammi). Puoi specificare l'endpoint di acquisizione durante la creazione del client oppure impostarlo all'avvio di un flusso.

L'endpoint di acquisizione è disponibile nella console AWS o può essere restituito dall'operazione CreateChannel (ad esempio UNIQUE\_ID.global-contribute.live-video.net).

```
const client = IVSBroadcastClient.create({
   // Enter the desired stream configuration
   streamConfig: IVSBroadcastClient.BASIC_LANDSCAPE,
   // Enter the ingest endpoint from the AWS console or CreateChannel API
   ingestEndpoint: 'UNIQUE_ID.global-contribute.live-video.net',
});
```

Queste sono le configurazioni di streaming supportate più comuni. Le impostazioni predefinite sono `BASIC` fino a 480p e 1,5 Mb/s di bitrate, BASIC Full HD fino a 1080p e 3,5 Mb/s di bitrate e `STANDARD` (o `ADVANCED`) fino a 1080p e 8,5 Mb/s. Se lo desideri, puoi personalizzare il bitrate, la frequenza dei fotogrammi e la risoluzione. Per ulteriori informazioni, consulta [BroadcastClientConfig](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference/interfaces/BroadcastClientConfig).

```
IVSBroadcastClient.BASIC_LANDSCAPE;
IVSBroadcastClient.BASIC_FULL_HD_LANDSCAPE;
IVSBroadcastClient.STANDARD_LANDSCAPE;
IVSBroadcastClient.BASIC_PORTRAIT;
IVSBroadcastClient.BASIC_FULL_HD_PORTRAIT;
IVSBroadcastClient.STANDARD_PORTRAIT;
```

Puoi importarli singolarmente se usi il pacchetto `npm`.

Nota: assicurati che la configurazione lato client sia in linea con il tipo di canale di backend. Ad esempio, se il tipo di canale è `STANDARD`, `streamConfig` deve essere impostato su uno dei valori `IVSBroadcastClient.STANDARD_*`. Se il tipo di canale è `ADVANCED`, dovrai impostare la configurazione manualmente come mostrato di seguito (usando `ADVANCED_HD` come esempio):

```
const client = IVSBroadcastClient.create({
   // Enter the custom stream configuration
   streamConfig: {
      maxResolution: {
         width: 1080,
         height: 1920,
     },
     maxFramerate: 30,
     /**
      * maxBitrate is measured in kbps
      */
     maxBitrate: 3500,
   },
   // Other configuration . . .
});
```

## Richiedere autorizzazioni
<a name="broadcast-web-request-permissions"></a>

L'app deve richiedere l'autorizzazione per accedere alla fotocamera e al microfono dell'utente e tale autorizzazione deve utilizzare HTTPS. (Questo non riguarda solo Amazon IVS, ma qualsiasi sito Web che abbia bisogno di accedere alle fotocamere e ai microfoni.)

Ecco un esempio di funzione che mostra come richiedere e ottenere le autorizzazioni per dispositivi audio e video:

```
async function handlePermissions() {
   let permissions = {
       audio: false,
       video: false,
   };
   try {
       const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
       for (const track of stream.getTracks()) {
           track.stop();
       }
       permissions = { video: true, audio: true };
   } catch (err) {
       permissions = { video: false, audio: false };
       console.error(err.message);
   }
   // If we still don't have permissions after requesting them display the error message
   if (!permissions.video) {
       console.error('Failed to get video permissions.');
   } else if (!permissions.audio) {
       console.error('Failed to get audio permissions.');
   }
}
```

Per ulteriori informazioni, consulta l'[API delle autorizzazioni](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API) e [MediaDevices.getUserMedia()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia).

## Configurazione di un'anteprima dello streaming
<a name="broadcast-web-request-set-up-stream"></a>

Per visualizzare in anteprima ciò che verrà trasmesso, fornisci all'SDK un elemento `<canvas>`.

```
// where #preview is an existing <canvas> DOM element on your page
const previewEl = document.getElementById('preview');
client.attachPreview(previewEl);
```

## Elenco dei dispositivi disponibili
<a name="broadcast-web-request-list-devices"></a>

Per vedere quali dispositivi sono disponibili per l'acquisizione, interroga il metodo [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices) del browser:

```
const devices = await navigator.mediaDevices.enumerateDevices();
window.videoDevices = devices.filter((d) => d.kind === 'videoinput');
window.audioDevices = devices.filter((d) => d.kind === 'audioinput');
```

## Recupero di un MediaStream da un dispositivo
<a name="broadcast-web-retrieve-mediastream"></a>

Dopo aver acquisito l'elenco dei dispositivi disponibili, puoi recuperare un flusso da qualsiasi numero di dispositivi. Ad esempio, puoi utilizzare il metodo `getUserMedia()` per recuperare un flusso da una videocamera.

Se desideri specificare da quale dispositivo catturare lo streaming, puoi impostare esplicitamente il `deviceId` nella sezione `audio` o `video` dei vincoli del supporto. In alternativa, puoi omettere `deviceId` e fare in modo che gli utenti selezionino i propri dispositivi dal prompt del browser.

È inoltre possibile specificare una risoluzione ideale della fotocamera utilizzando i vincoli `width` e `height`. (Ulteriori informazioni su questi vincoli sono disponibili [qui](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#properties_of_video_tracks).) L'SDK applica automaticamente i limiti di larghezza e altezza che corrispondono alla risoluzione massima di trasmissione; tuttavia, è una buona idea applicarli anche tu stesso in modo da essere certi che le proporzioni dell'aspetto della sorgente non vengano modificate dopo aver aggiunto la sorgente all'SDK.

```
const streamConfig = IVSBroadcastClient.BASIC_LANDSCAPE;
...
window.cameraStream = await navigator.mediaDevices.getUserMedia({
   video: {
       deviceId: window.videoDevices[0].deviceId,
       width: {
           ideal: streamConfig.maxResolution.width,
       },
       height: {
           ideal: streamConfig.maxResolution.height,
       },
   },
});
window.microphoneStream = await navigator.mediaDevices.getUserMedia({
   audio: { deviceId: window.audioDevices[0].deviceId },
});
```

## Aggiunta di un dispositivo a uno streaming
<a name="broadcast-web-add-device"></a>

Dopo aver acquisito il flusso, puoi aggiungere dispositivi al layout specificando un nome univoco (di seguito, questo è `camera1`) e la posizione della composizione (per il video). Ad esempio, specificando una webcam, aggiungi la sorgente video della webcam allo streaming di trasmissione.

Quando si specifica il dispositivo di ingresso video, è necessario specificare l'indice, che rappresenta il "livello" su cui si desidera trasmettere. Questo è sinonimo di modifica delle immagini o CSS, dove uno z-index rappresenta l'ordine dei livelli da renderizzare. Facoltativamente, puoi fornire una posizione che definisca le coordinate x/y (così come la dimensione) della sorgente del flusso.

Per i dettagli dei parametri, consulta [VideoComposition](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference/interfaces/VideoComposition).

```
client.addVideoInputDevice(window.cameraStream, 'camera1', { index: 0 }); // only 'index' is required for the position parameter
client.addAudioInputDevice(window.microphoneStream, 'mic1');
```

## Avviare una trasmissione
<a name="broadcast-web-start-broadcast"></a>

Per avviare una trasmissione, fornisci la chiave di streaming per il tuo canale Amazon IVS:

```
client
   .startBroadcast(streamKey)
   .then((result) => {
       console.log('I am successfully broadcasting!');
   })
   .catch((error) => {
       console.error('Something drastically failed while broadcasting!', error);
   });
```

## Interrompere una trasmissione
<a name="broadcast-web-stop-broadcast"></a>

```
client.stopBroadcast();
```

## Scambio delle posizioni video
<a name="broadcast-web-swap-video-positions"></a>

Il client supporta lo scambio delle posizioni di composizione dei dispositivi video:

```
client.exchangeVideoDevicePositions('camera1', 'camera2');
```

## Mute Audio (Disattiva audio)
<a name="broadcast-web-muting-audio"></a>

Per disattivare l'audio, rimuovi il dispositivo audio che utilizza `removeAudioInputDevice` o imposta la proprietà `enabled` sulla traccia audio:

```
let audioStream = client.getAudioInputDevice(AUDIO_DEVICE_NAME);
audioStream.getAudioTracks()[0].enabled = false;
```

Dove `AUDIO_DEVICE_NAME` è il nome dato al dispositivo audio originale durante la chiamata `addAudioInputDevice()`.

Per riattivare l'audio:

```
let audioStream = client.getAudioInputDevice(AUDIO_DEVICE_NAME);
audioStream.getAudioTracks()[0].enabled = true;
```

## Nascondere il video
<a name="broadcast-web-hiding-video"></a>

Per nascondere il video, rimuovi il dispositivo video utilizzando `removeVideoInputDevice` o imposta la proprietà `enabled` sulla traccia video:

```
let videoStream = client.getVideoInputDevice(VIDEO_DEVICE_NAME).source;
videoStream.getVideoTracks()[0].enabled = false;
```

Dove `VIDEO_DEVICE_NAME` è il nome dato al dispositivo video durante la chiamata `addVideoInputDevice()` originale.

Per mostrare il video:

```
let videoStream = client.getVideoInputDevice(VIDEO_DEVICE_NAME).source;
videoStream.getVideoTracks()[0].enabled = true;
```