# Introducción al SDK de transmisión web de IVS \| Transmisión de baja latencia
<a name="broadcast-web-getting-started"></a>

En este documento, se explican los pasos para comenzar a usar el SDK de transmisión web para la transmisión de baja latencia de Amazon IVS.

## Instalar la biblioteca
<a name="broadcast-web-install"></a>

Tenga en cuenta que el IVSBroadcastClient aprovecha [reflect-metadata](https://www.npmjs.com/package/reflect-metadata), lo cual amplía el objeto Reflect global. Si bien esto no debería generar ningún problema, excepcionalmente podría provocar un comportamiento no deseado.

### Uso de una etiqueta de script
<a name="broadcast-web-how-to-install-script"></a>

El SDK de transmisión web se distribuye como biblioteca de JavaScript y se puede obtener en [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).

Cuando se carga mediante una etiqueta `<script>`, la biblioteca muestra una variable global en el ámbito del intervalo denominado `IVSBroadcastClient`.

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

Para instalar el paquete de `npm`:

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

Ahora puede acceder al objeto `IVSBroadcastClient` y extraer otros módulos y restricciones, como `Errors` y `BASIC_LANDSCAPE`:

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

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

Para comenzar rápidamente, consulte los ejemplos a continuación:
+ [Transmisión única a un canal de IVS (HTML y JavaScript)](https://codepen.io/amazon-ivs/pen/poLRoPp)
+ [Transmisión única con pantalla compartida a un canal de IVS](https://stream.ivs.rocks/) ([Código fuente de React](https://github.com/aws-samples/amazon-ivs-broadcast-web-demo))

## Creación de una instancia del AmazonIVSBroadcastClient
<a name="broadcast-web-instance"></a>

Para utilizar la biblioteca, debe crear una instancia del cliente. Puede hacerlo al activar el método `create` en `IVSBroadcastClient` con el parámetro `streamConfig` (debe especificar las restricciones de la transmisión, como la resolución y la velocidad de los fotogramas). Tiene la posibilidad de indicar el punto de conexión de incorporación al crear el cliente o cuando inicia la transmisión.

El punto de conexión de ingesta puede estar en la Consola de AWS o lo puede devolver la operación CreateChannel (por ejemplo, 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',
});
```

Estas son las configuraciones de transmisión que generalmente son compatibles. Los ajustes preestablecidos son hasta 480p y 1,5 Mbps de velocidad de bits para `BASIC`, 1080p y 3,5 Mbps para BASIC Full HD y 1080p y 8,5 Mbps para `STANDARD` (o `ADVANCED`). Si lo desea, puede personalizar la velocidad de los bits, de los fotogramas y la resolución. Para obtener más información, consulte [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;
```

Puede importarlos individualmente si utiliza el paquete `npm`.

Nota: Asegúrese de que la configuración del cliente esté en consonancia con el tipo de canal de backend. Por ejemplo, si el tipo de canal es `STANDARD`, `streamConfig` se debe establecer en uno de los valores `IVSBroadcastClient.STANDARD_*`. Si el tipo de canal es `ADVANCED`, tendrá que ajustar la configuración de manera manual tal como se muestra a continuación (con `ADVANCED_HD` a modo de ejemplo):

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

## Solicitar permisos
<a name="broadcast-web-request-permissions"></a>

La aplicación debe solicitar permiso para acceder a la cámara y al micrófono del usuario, y deberán ser ofrecidos mediante HTTPS. (Esto no es específico de Amazon IVS; es necesario para cualquier sitio web que necesite acceso a cámaras y micrófonos).

A continuación, le presentamos una función a modo de ejemplo que muestra cómo solicitar y capturar permisos para los dispositivos de audio y 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.');
   }
}
```

Para obtener más información, consulte la [API de permisos](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API) y [MediaDevices.getUserMedia()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia).

## Configurar la vista previa de la transmisión
<a name="broadcast-web-request-set-up-stream"></a>

Para obtener una vista previa de lo que se transmitirá, debe proporcionar al SDK un elemento `<canvas>`.

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

## Enlistar los dispositivos disponibles
<a name="broadcast-web-request-list-devices"></a>

Para conocer los dispositivos que puede capturar, consulte el método [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices) del navegador:

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

## Recuperar MediaStream de un dispositivo
<a name="broadcast-web-retrieve-mediastream"></a>

Después de obtener la lista de dispositivos disponibles, puede recuperar una transmisión de diversos dispositivos. Por ejemplo, puede utilizar el método `getUserMedia()` para recuperar la transmisión de una cámara.

Si quisiera indicar desde cuál dispositivo desea capturar la transmisión, puede establecer de forma expresa `deviceId` en las secciones `audio` o `video` de las restricciones de multimedia. De forma alternativa, puede omitir `deviceId` y que los usuarios seleccionen los dispositivos desde el símbolo del navegador.

También puede especificar la resolución de cámara ideal mediante las restricciones `width` y `height`. (Obtenga más información sobre estas restricciones [aquí](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#properties_of_video_tracks)). El SDK aplica de forma automática las restricciones máximas de ancho y alto que corresponden a la resolución máxima de transmisión; sin embargo, es aconsejable que las aplique usted mismo para garantizar que la relación de aspecto de la fuente no cambie después de que la agregue al 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 },
});
```

## Incorporar un dispositivo a una transmisión
<a name="broadcast-web-add-device"></a>

Después de adquirir la transmisión, puede agregar dispositivos al diseño especificando un nombre único (a continuación, vea `camera1`) y la posición de la composición (para el video). Por ejemplo, cuando indica el dispositivo de cámara web, agrega la fuente de video de la cámara al flujo de la transmisión.

Al especificar el dispositivo de entrada de video, debe indicar el índice, el cual representa la “capa” en la que desea hacer la transmisión. Esto es sinónimo de edición de imágenes o CSS, donde el índice Z representa el orden de las capas que se van a procesar. Si lo desea, puede establecer una posición, la cual define las coordenadas x/y (como también el tamaño) de la fuente de transmisión.

Para obtener más información sobre los parámetros, consulte [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');
```

## Inicio de una transmisión
<a name="broadcast-web-start-broadcast"></a>

Para iniciar una transmisión, proporcione la clave de transmisión para el canal de Amazon IVS:

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

## Detención de una transmisión
<a name="broadcast-web-stop-broadcast"></a>

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

## Cambiar las posiciones del video
<a name="broadcast-web-swap-video-positions"></a>

El cliente admite el cambio de posiciones de la composición de los dispositivos de video:

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

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

Para silenciar el audio, quite el dispositivo de audio mediante `removeAudioInputDevice` o establezca la propiedad `enabled` en la pista de audio:

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

`AUDIO_DEVICE_NAME` es el nombre del dispositivo de audio original durante la llamada `addAudioInputDevice()`.

Para reactivar el audio:

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

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

Para ocultar el video, quite el dispositivo de video mediante `removeVideoInputDevice` o establezca la propiedad `enabled` en la pista de video:

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

`VIDEO_DEVICE_NAME` es el nombre del dispositivo de video durante la llamada a `addVideoInputDevice()` original.

Para volver a mostrar:

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