# Mise en route avec le kit SDK de diffusion Web IVS \| Diffusion à faible latence
<a name="broadcast-web-getting-started"></a>

Ce document vous présente les étapes à suivre pour commencer à utiliser le kit SDK de diffusion Web à faible latence d’Amazon IVS.

## Installer la bibliothèque
<a name="broadcast-web-install"></a>

Notez que l'IVSBroadcastClient exploite les [reflect-metadata](https://www.npmjs.com/package/reflect-metadata) (métadonnées reflect), qui étendent l'objet Reflect global. Bien que cela ne devrait pas créer de conflit, dans certains rares cas, cela pourrait entraîner un comportement indésirable.

### Utilisation d'une balise de script
<a name="broadcast-web-how-to-install-script"></a>

Le kit SDK de diffusion Web est distribué sous forme de bibliothèque JavaScript et peut être consulté à l'adresse [https://web-broadcast.live-video.net/1.34.0/amazon-ivs-web-broadcast.js](https://web-broadcast.live-video.net/1.34.0/amazon-ivs-web-broadcast.js).

Lorsqu'elle est chargée via une balise `<script>`, la bibliothèque expose une variable globale dans la portée de la fenêtre nommée `IVSBroadcastClient`.

### Utilisation de npm
<a name="broadcast-web-how-to-install-npm"></a>

Pour installer le package `npm` :

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

Vous pouvez désormais accéder à l'objet `IVSBroadcastClient` et y intégrer d'autres modules et consts, tels que `Errors`, `BASIC_LANDSCAPE` :

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

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

Pour démarrer rapidement, consultez les exemples ci-dessous :
+ [Diffusion unique vers un canal IVS (HTML et JavaScript)](https://codepen.io/amazon-ivs/pen/poLRoPp)
+ [Diffusion unique avec partage d'écran vers un canal IVS](https://stream.ivs.rocks/) ([React Source Code](https://github.com/aws-samples/amazon-ivs-broadcast-web-demo))

## Créer une instance de l'AmazonIVSBroadcastClient
<a name="broadcast-web-instance"></a>

Pour utiliser la bibliothèque, vous devez créer une instance du client. Vous pouvez le faire en appelant la méthode `create` sur `IVSBroadcastClient` avec le paramètre `streamConfig` (en spécifiant les contraintes de votre diffusion, telles que la résolution et la fréquence d'images). Vous pouvez spécifier le point de terminaison d'ingestion lors de la création du client ou le définir lorsque vous démarrez un flux.

Le point de terminaison d’ingestion peut être trouvé dans la console AWS ou être renvoyé par l’opération CreateChannel (par exemple, 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',
});
```

Il s'agit des configurations de flux couramment prises en charge. Les préréglages sont `BASIC` jusqu'à 480p et 1,5 Mbit/s, BASIC Full HD jusqu'à 1080p et 3,5 Mbit/s, et `STANDARD` (ou `ADVANCED`) jusqu'à 1080p et 8,5 Mbit/s. Vous pouvez personnaliser le débit, la fréquence d'images et la résolution si vous le souhaitez. Pour plus d’informations, consultez [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;
```

Vous pouvez les importer individuellement si vous utilisez le package `npm`.

Remarque : assurez-vous que votre configuration côté client correspond au type de canal dorsal. Par exemple, si le type de canal est `STANDARD`, `streamConfig` doit être défini sur l'une des valeurs `IVSBroadcastClient.STANDARD_*`. Si le type de canal est `ADVANCED`, vous devrez définir la configuration manuellement comme indiqué ci-dessous (`ADVANCED_HD` à titre d'exemple) :

```
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 . . .
});
```

## Demander des autorisations
<a name="broadcast-web-request-permissions"></a>

Votre application doit demander l’autorisation d’accéder à la caméra et au microphone de l’utilisateur, et cela doit être réalisé en utilisant HTTPS. (Ce n’est pas spécifique à Amazon IVS ; cette autorisation est requise pour toute application devant accéder aux caméras et aux microphones.)

Voici un exemple de fonction qui montre comment demander et capturer des autorisations pour les périphériques audio et vidéo :

```
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.');
   }
}
```

Pour plus d’informations, consultez l’[API Permissions](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API) et [MediaDevices.getUserMedia()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia).

## Configurer un aperçu de flux
<a name="broadcast-web-request-set-up-stream"></a>

Pour prévisualiser ce qui sera diffusé, fournissez un élément `<canvas>` au kit SDK.

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

## Répertorier les périphériques disponibles
<a name="broadcast-web-request-list-devices"></a>

Pour voir quels périphériques peuvent être capturés, interrogez la méthode [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices) du navigateur :

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

## Récupérer un MediaStream depuis un périphérique
<a name="broadcast-web-retrieve-mediastream"></a>

Après avoir acquis la liste des périphériques disponibles, vous pouvez récupérer un flux à partir d’un nombre quelconque de périphériques. Par exemple, vous pouvez utiliser la méthode `getUserMedia()` pour récupérer un flux d’une caméra.

Si vous souhaitez spécifier le périphérique à partir duquel vous souhaitez capturer le flux, vous pouvez définir explicitement le `deviceId` dans la section `audio` ou `video` des contraintes multimédias. Vous pouvez également omettre le `deviceId` et demander aux utilisateurs de sélectionner leurs périphériques à l’invite du navigateur.

Vous pouvez également spécifier une résolution de caméra idéale à l’aide des contraintes `width` et `height`. (Pour en savoir plus sur ces contraintes, [cliquez ici](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#properties_of_video_tracks).) Le kit SDK applique automatiquement des contraintes de largeur et de hauteur qui correspondent à votre résolution de diffusion maximale ; cependant, il est conseillé de les appliquer vous-même pour vous assurer que le rapport hauteur/largeur de la source n'est pas modifié une fois que vous avez ajouté la source au kit 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 },
});
```

## Ajouter un périphérique à un flux
<a name="broadcast-web-add-device"></a>

Après avoir acquis le flux, vous pouvez ajouter des périphériques à la mise en page en spécifiant un nom unique (ci-dessous `camera1`) et une position de composition (pour la vidéo). Par exemple, en spécifiant votre périphérique webcam, vous ajoutez la source vidéo de votre webcam au flux de diffusion.

Lorsque vous spécifiez le périphérique d'entrée vidéo, vous devez indiquer l'index, qui représente la « couche » sur laquelle vous souhaitez diffuser. Ceci est comparable à l'édition d'images ou au CSS, où un z-index représente l'ordre des couches à afficher. Vous pouvez éventuellement fournir une position qui définit les coordonnées x/y (ainsi que la taille) de la source du flux.

Pour plus de détails sur les paramètres, consultez [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');
```

## Démarrer une diffusion
<a name="broadcast-web-start-broadcast"></a>

Pour démarrer une diffusion, fournissez la clé de diffusion de votre canal Amazon IVS :

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

## Arrêter une diffusion
<a name="broadcast-web-stop-broadcast"></a>

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

## Échanger des positions vidéo
<a name="broadcast-web-swap-video-positions"></a>

Le client prend en charge l'échange des positions de composition des périphériques vidéo :

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

## Désactiver le son
<a name="broadcast-web-muting-audio"></a>

Pour désactiver le son, supprimez le périphérique audio en utilisant `removeAudioInputDevice` ou définissez la propriété `enabled` sur la piste audio :

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

Où `AUDIO_DEVICE_NAME` est le nom donné au périphérique audio d'origine pendant l'appel à `addAudioInputDevice()`.

Pour réactiver le son :

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

## Masquer la vidéo
<a name="broadcast-web-hiding-video"></a>

Pour masquer une vidéo, supprimez le périphérique vidéo en utilisant `removeVideoInputDevice` ou définissez la propriété `enabled` sur la piste vidéo :

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

Où `VIDEO_DEVICE_NAME` est le nom donné au périphérique vidéo lors de l'appel initial à `addVideoInputDevice()`.

Pour démasquer :

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