# Erste Schritte mit dem IVS-Web-Broadcast-SDK \| Streaming mit niedriger Latenz
<a name="broadcast-web-getting-started"></a>

Dieses Dokument führt Sie durch die Schritte zum Einstieg in das Web-Broadcast-SDK für Amazon-IVS-Streaming mit niedriger Latenz.

## Installieren der Bibliothek
<a name="broadcast-web-install"></a>

Beachten Sie, dass der IVSBroadcastClient [reflect-metadata](https://www.npmjs.com/package/reflect-metadata) verwendet, wodurch das globale Reflect-Objekt erweitert wird. Das sollte zwar keine Konflikte hervorrufen, kann jedoch in seltenen Fällen unerwünschtes Verhalten verursachen.

### Verwenden eines Skript-Tags
<a name="broadcast-web-how-to-install-script"></a>

Das Web Broadcast SDK wird als JavaScript-Bibliothek verteilt und kann unter [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) abgerufen werden.

Wenn sie per `<script>`-Tag geladen wird, stellt die Bibliothek eine globale Variable im Fensterbereich namens `IVSBroadcastClient` bereit.

### Verwenden von npm
<a name="broadcast-web-how-to-install-npm"></a>

So installieren Sie das `npm`-Paket:

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

Sie können jetzt auf das Objekt `IVSBroadcastClient` zugreifen und andere Module und Konstanten wie `Errors` und `BASIC_LANDSCAPE` abrufen:

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

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

Um schnell loszulegen, sehen Sie sich die folgenden Beispiele an:
+ [Einzelübertragung auf einen IVS-Kanal (HTML und JavaScript)](https://codepen.io/amazon-ivs/pen/poLRoPp)
+ [Einzelübertragung mit Bildschirmübertragung auf einen IVS-Kanal](https://stream.ivs.rocks/) ([React Source Code](https://github.com/aws-samples/amazon-ivs-broadcast-web-demo))

## Erstellen einer Instance des AmazonIVSBroadcastClient
<a name="broadcast-web-instance"></a>

Zur Verwendung der Bibliothek müssen Sie eine Instance des Clients erstellen. Dazu rufen Sie die Methode `create` für `IVSBroadcastClient` mit dem Parameter `streamConfig` auf (unter Angabe von Einschränkungen für die Übertragung wie etwa Auflösung und Framerate). Den Ingest-Endpunkt können Sie beim Erstellen des Clients oder beim Starten eines Streams angeben.

Den Erfassungs-Endpunkt finden Sie in der AWS-Konsole. Alternativ kann er vom Vorgang CreateChannel zurückgegeben werden (z. B. 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',
});
```

Dies sind die gängigen unterstützten Stream-Konfigurationen. Die Voreinstellungen sind `BASIC` (mit bis zu 480p und einer Bitrate von bis zu 1,5 Mbit/s, BASIC Full HD mit bis zu 1080p und einer Bitrate von bis zu 3,5 Mbit/s und `STANDARD` (oder `ADVANCED`) mit bis zu 1080p und einer Bitrate von bis zu 8,5 Mbit/s. Sie können die Bitrate, Framerate und Auflösung bei Bedarf anpassen. Weitere Informationen finden Sie unter [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;
```

Bei Verwendung des `npm`-Pakets können Sie diese einzeln importieren.

Hinweis: Stellen Sie sicher, dass die clientseitige Konfiguration dem Kanaltyp des Backends entspricht. Wenn der Kanaltyp beispielsweise `STANDARD` lautet, muss `streamConfig` auf einen der `IVSBroadcastClient.STANDARD_*`-Werte eingestellt werden. Wenn der Kanaltyp `ADVANCED` lautet, müssen Sie die Konfiguration manuell festlegen, wie unten gezeigt (`ADVANCED_HD` wird als Beispiel verwendet):

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

## Berechtigungen anfordern
<a name="broadcast-web-request-permissions"></a>

Ihre App muss die Berechtigung für den Zugriff auf die Kamera und das Mikrofon des Benutzers anfordern und muss über HTTPS bereitgestellt werden. (Das gilt nicht nur für Amazon IVS, sondern für alle Websites, die Zugriff auf Kameras und Mikrofone benötigen.)

Die folgende Beispielfunktion zeigt, wie Sie Berechtigungen für Audio- und Videogeräte anfordern und erfassen können:

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

Weitere Informationen finden Sie in der [Berechtigungs-API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API) und unter [MediaDevices.getUserMedia()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia).

## Einrichten einer Stream-Vorschau
<a name="broadcast-web-request-set-up-stream"></a>

Um eine Vorschau der Übertragung anzuzeigen, stellen Sie dem SDK ein `<canvas>`-Element zur Verfügung.

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

## Auflisten der verfügbaren Geräte
<a name="broadcast-web-request-list-devices"></a>

Um festzustellen, welche Geräte für die Erfassung verfügbar sind, fragen Sie die Methode [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices) des Browsers ab:

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

## Abrufen eines MediaStream von einem Gerät
<a name="broadcast-web-retrieve-mediastream"></a>

Nachdem Sie die Liste der verfügbaren Geräte erfasst haben, können Sie einen Stream von einer beliebigen Anzahl von Geräten abrufen. Sie können zum Beispiel mit der Methode `getUserMedia()` einen Stream von einer Kamera abrufen.

Wenn Sie angeben möchten, von welchem Gerät der Stream erfasst werden soll, können Sie die `deviceId` im Bereich `audio` oder `video` der Medieneinschränkungen explizit festlegen. Alternativ können Sie die `deviceId` weglassen und Benutzer ihre Geräte über die Eingabeaufforderung des Browsers auswählen lassen.

Zudem können Sie mithilfe der Einschränkungen `width` und `height` eine ideale Kameraauflösung angeben. (Mehr über diese Einschränkungen erfahren Sie [hier](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#properties_of_video_tracks).) Das SDK wendet automatisch die Einschränkungen für die Breite und Höhe an, die Ihrer maximalen Übertragungsauflösung entsprechen. Es empfiehlt sich jedoch, diese auch selbst anzuwenden, damit das Seitenverhältnis der Quelle nicht geändert wird, nachdem Sie sie dem SDK hinzugefügt haben.

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

## Hinzufügen eines Geräts zu einem Stream
<a name="broadcast-web-add-device"></a>

Nach Erfassung des Streams können Sie dem Layout Geräte hinzufügen, indem Sie einen eindeutigen Namen (unten lautet er `camera1`) und eine Bildposition (für Videos) angeben. Durch Angabe einer Webcam können Sie zum Beispiel eine Webcam-Videoquelle zum übertragenen Stream hinzufügen.

Bei Angabe des Videoeingabegeräts müssen Sie den Index angeben, der die „Ebene“ darstellt, auf der die Übertragung erfolgen soll. Dies ist vergleichbar mit der Bildbearbeitung oder CSS, wo ein Z-Index die Reihenfolge der zu rendernden Ebenen angibt. Optional können Sie eine Position angeben, die die X/Y-Koordinaten (sowie die Größe) der Stream-Quelle definiert.

Einzelheiten zu Parametern finden Sie unter [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');
```

## Starten eines Broadcastings
<a name="broadcast-web-start-broadcast"></a>

Um eine Übertragung zu starten, geben Sie den Stream-Schlüssel für Ihren Amazon-IVS-Kanal ein:

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

## Anhalten eines Broadcastings
<a name="broadcast-web-stop-broadcast"></a>

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

## Wechseln von Videopositionen
<a name="broadcast-web-swap-video-positions"></a>

Der Client unterstützt das Wechseln der Bildpositionen von Videogeräten:

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

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

Zum Stummschalten entfernen Sie entweder das Audiogerät mit `removeAudioInputDevice` oder stellen Sie die Eigenschaft `enabled` für die Audiospur ein:

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

Dabei ist `AUDIO_DEVICE_NAME` der Name, der dem ursprünglichen Audiogerät beim Aufruf von `addAudioInputDevice()` gegeben wurde.

So heben Sie die Stummschaltung auf:

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

## Ausblenden eines Videos
<a name="broadcast-web-hiding-video"></a>

Um ein Video auszublenden, entfernen Sie entweder das Videogerät mit `removeVideoInputDevice` oder legen Sie die Eigenschaft `enabled` für die Videospur fest:

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

Dabei ist `VIDEO_DEVICE_NAME` der Name, der dem Videogerät beim ursprünglichen Aufruf von `addVideoInputDevice()` gegeben wurde.

So blenden Sie ein Video ein:

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