Video-Anschluss

Mit dem Vonage Video Connector können Sie programmgesteuert als serverseitiger Teilnehmer an Vonage Video API-Sitzungen teilnehmen. Er ermöglicht es Ihnen, eine Verbindung zu Videositzungen herzustellen, Streams zu veröffentlichen und zu abonnieren sowie Audio- und Videodaten in Echtzeit zu verarbeiten.

Die Bibliothek übernimmt automatisch die WebRTC-Konnektivität, die Medienverarbeitung und die Sitzungsverwaltung, so dass Sie sich auf die Entwicklung Ihrer Anwendungslogik konzentrieren können. auf die Entwicklung Ihrer Anwendungslogik konzentrieren können. Audio wird als lineare PCM 16-Bit-Daten und Video als 8-Bit-Frames in den Formaten YUV420P, RGB24 oder ARGB32 geliefert, und zwar mit konfigurierbaren Abtastraten, Auflösungen und Kanalkonfigurationen.

Auf dieser Seite werden die Concepts und das Verhalten beschrieben, die allen Video Connector-Bibliotheken gemeinsam sind. Informationen zur Installation, zu API-Signaturen und zu Code-Beispielen finden Sie im Leitfaden für Ihre Sprache.

Wählen Sie Ihre Bibliothek aus

Beide Bibliotheken bieten dieselben Funktionen und basieren auf derselben nativen Implementierung. Sie unterscheiden sich in den Namenskonventionen und darin, wie asynchrone Operationen bereitgestellt werden: Die Python-Bibliothek verwendet Callbacks zur Abschlussbenachrichtigung, während die Node.js-Bibliothek Promises zurückgibt. Auf dieser Seite wird das gemeinsame Verhalten der beiden Bibliotheken beschrieben.

Dieses Thema umfasst die folgenden Abschnitte:

• Wie es funktioniert
• Anforderungen
• Kernkonzepte
• Medienformate
• Sitzungskonfiguration
• Verlagsmedien
• Abonnieren von Streams
• Verwaltung der Medienpuffer
• Ereignismodell
• Grenzen

Wie es funktioniert

Der Video-Connector nimmt als regulärer WebRTC-Teilnehmer an einer Sitzung teil. Aus der Sicht der anderen Teilnehmer ist er nicht von einem Browser oder einem mobilen Client zu unterscheiden: Er verfügt über eine eigene Verbindung, kann einen Stream veröffentlichen und die Streams anderer abonnieren.

Der Unterschied besteht darin, dass Medien nicht über eine Kamera, ein Mikrofon oder einen Bildschirm, sondern mit Ihrem Anwendungscode ausgetauscht werden. Sie übermitteln Rohdaten von Audio- und Video-Frames an den Connector, um diese zu veröffentlichen, und empfangen Rohdaten von Audio und Video aus den Streams, die Sie abonniert haben. Dadurch eignet sich der Connector für serverseitige Workloads wie beispielsweise:

• KI-Agenten für Sprache und Video in Echtzeit
• Live-Transkription, -Übersetzung und -Untertitelung
• Erfassung, Archivierung und Compliance-Erfassung
• Computervision und Inhaltsmoderation
• Bearbeitung von Audio- und Videoeffekten

Der typische Lebenszyklus sieht wie folgt aus:

1. Stellen Sie mithilfe Ihrer Anwendungs-ID, Ihrer Sitzungs-ID und eines Tokens eine Verbindung zu einer Sitzung her.
2. Veröffentlichen Sie einen Stream und speisen Sie dann Audio- und/oder Video-Frames in diesen ein.
3. Abonnieren Sie die Streams anderer Teilnehmer, sobald diese eintreffen, und verarbeiten Sie die empfangenen Medien.
4. Abmelden, Veröffentlichung rückgängig machen und Verbindung trennen, wenn Sie fertig sind.

Anforderungen

Der Video Connector wird als native Bibliothek mit vorgefertigten Binärdateien ausgeliefert. Er läuft auf Linux auf x86_64 (AMD64) und ARM64 nur.

Wir empfehlen Debian Bookworm, da dies die Distribution ist, in der der Connector am gründlichsten getestet wurde.

Kernkonzepte

Der Video Connector verwendet eine kleine Anzahl von Objekten, um Sitzungen, Teilnehmer, Streams und Medien darzustellen. Das Verständnis dieser Objekte ist unerlässlich, um mit beiden Bibliotheken effektiv arbeiten zu können.

Sitzung

Eine Vonage Video API-Sitzung, mit der sich Clients verbinden. Die Sitzung wird anhand ihrer ID identifiziert und an Ereignis-Handler auf Sitzungsebene weitergeleitet, sodass Sie feststellen können, welche Sitzung ein Ereignis ausgelöst hat.

Verbindung

Die Verbindung eines Teilnehmers zu einer Sitzung. Jeder Teilnehmer, einschließlich des Connectors selbst, verfügt über genau eine Verbindung. Eine Verbindung umfasst:

• Eine eindeutige Kennung
• Ein Zeitstempel der Erstellung
• Verbindungsdaten, die in dem für die Verbindung verwendeten Token verschlüsselt sind

Verbindungsdaten eignen sich zum Speichern benutzerdefinierter Metadaten zu Teilnehmern, wie beispielsweise Benutzer-IDs oder Rollen.

Stream

Ein von einem Teilnehmer veröffentlichter Medienstrom (Audio, Video oder beides). Ein Strom verfügt über eine eindeutige Kennung und einen Verweis auf die Verbindung, über die er veröffentlicht wurde. Ströme werden Ihnen gemeldet, sobald Teilnehmer mit der Veröffentlichung beginnen, und Sie abonnieren diese, um Medien zu empfangen.

Herausgeber

Ihr eigener veröffentlichter Stream in der Sitzung. Pro Connector-Instanz gibt es höchstens einen Publisher. Der Publisher verfügt über einen Verweis auf den von ihm erstellten Stream – so werden Sie von anderen Teilnehmern wahrgenommen.

Abonnent

Ein Abonnement für den Stream eines anderen Teilnehmers. Sie erstellen einen Abonnenten pro Stream, von dem Sie Medien empfangen möchten, und jeder Abonnent enthält einen Verweis auf den Stream, den er abonniert hat. Medien- und Untertitel-Ereignisse werden zusammen mit dem Abonnenten übermittelt, der sie erzeugt hat, sodass Sie erkennen können, von welchem Teilnehmer die Daten stammen.

In welcher Beziehung stehen sie zueinander?

Session
├── Connection (multiple participants)
│   └── Stream (participant's published media)
│       ├── Publisher (your published stream)
│       └── Subscriber (your subscription to their stream)
├── Audio data (flowing through streams)
└── Video frames (flowing through streams)

Medienformate

Audio

Audio wird immer ausgetauscht als Lineares PCM, 16-Bit-Ganzzahlen mit Vorzeichen. Ein Audio-Frame umfasst ein Sample pro Kanal, daher muss ein Puffer mindestens (Anzahl der Frames × Anzahl der Kanäle) Samples enthalten.

• Musterpreise8000, 12000, 16000, 24000, 32000, 44100, oder 48000 Hz
• Kanäle: 1 (Mono) oder 2 (Stereo)
• Rahmengröße: in der Regel 20-ms-Blöcke, je nach Abtastrate unterschiedlich

Die Abtastrate und die Kanalanzahl lassen sich für das von Ihnen veröffentlichte Audiosignal und das gemischte Audiosignal, das Sie empfangen, unabhängig voneinander konfigurieren. Siehe Sitzungskonfiguration.

Video

Videos werden ausgetauscht als 8-Bit-Werte ohne Vorzeichen in einem von drei Pixelformaten:

• Entschließungen: bis zu 1920 × 1080 (insgesamt 2.073.600 Pixel)
• Bildfrequenzen: 1 bis 30 FPS

Sitzungskonfiguration

Audio zum Veröffentlichen im Vergleich zum Abonnieren

Über den Anschluss können Sie zwei unabhängige Audioformate konfigurieren:

• Audio des Verlags legt das Format der Audiodaten fest, die Sie bei der Veröffentlichung bereitstellen. Die von Ihnen übermittelten Audiodaten müssen dieser Abtastrate und der Kanalanzahl entsprechen.
• Abonnentenstruktur (Audio) legt das Format des gemischten Audios fest, das Sie von allen abonnierten Streams erhalten. Die Bibliothek übernimmt das Mischen mehrerer Teilnehmer sowie das Resampling oder die Kanalumwandlung, um das gewünschte Format zu erreichen.

Durch diese Trennung können Sie die Lösung optimal an Ihren Anwendungsfall anpassen. Zum Beispiel:

• Veröffentlichen Sie in Stereo, um eine hochwertige Ausgabe zu erzielen, und erhalten Sie gleichzeitig einen Mono-Mix, um die Bearbeitung zu vereinfachen
• Für Sprache mit 16 kHz senden und für die High-Fidelity-Wiedergabe mit 48 kHz empfangen
• Verwenden Sie auf jeder Seite unterschiedliche Raten, um den Anforderungen einer Audioverarbeitungs-Pipeline gerecht zu werden

Bevorzugte Auflösung und Bildfrequenz für Abonnenten

Beim Abonnieren von gerouteten Streams, die Simulcast nutzen, kann die SFU (Selective Forwarding Unit) der Vonage Video API verschiedene Qualitätsstufen des Videos senden. Über die Abonnenteneinstellungen können Sie eine bestimmte Qualitätsstufe anfordern:

• Bevorzugte Auflösung fordert eine räumliche Ebene an. Die SFU sendet die Ebene, die am besten passt.
• Bevorzugte Bildrate fordert eine zeitliche Ebene an. Die SFU sendet die Ebene, die am besten passt.

Diese Einstellungen tragen dazu bei, die Bandbreite und die Rechenleistung auf der Seite des Teilnehmers zu optimieren, indem nur die Qualitätsstufe angefordert wird, die Sie benötigen, anstatt stets die höchstmögliche Qualität zu erhalten.

Migration von Sitzungen

Die Sitzungsmigration kann aktiviert werden, damit der Konnektor im Falle einer SFU-Rotation automatisch migriert. Standardmäßig ist diese Funktion deaktiviert.

Protokollierung

Die Ausführlichkeit der Konsolenprotokollierung lässt sich in fünf Stufen konfigurieren: ERROR, WARN, INFO, DEBUGund TRACE.

Verlagsmedien

Ein Publisher muss Audio, Video oder beides veröffentlichen. Die Konfiguration eines Publishers ohne beides führt zu einem Fehler.

Warten auf Audiobereitschaft

Audio-Kontinuität

Wenn Sie Audioinhalte veröffentlichen, sorgt die Bibliothek in Ihrem Namen für einen kontinuierlichen Stream:

Erstveröffentlichung. Die Bibliothek sendet Stille (mit Nullen gefüllte Frames), bis Sie Ihre ersten Audiodaten bereitstellen. Dadurch steht der Stream den Abonnenten sofort zur Verfügung, ohne dass sie warten müssen, bis Ihre Applications Audiodaten erzeugen.

Toleranz gegenüber Stille. Wenn Sie die Audioübertragung vorübergehend unterbrechen, gleicht die Bibliothek kurze Lücken aus, indem sie überhaupt keine Audiopakete sendet. Diese Hysterese verhindert unnötige Stillepakete bei kurzzeitigen Verarbeitungsverzögerungen.

Ausdrückliches Schweigen. Wenn nach Ablauf der Toleranzphase kein neues Audiomaterial verfügbar ist, wechselt die Bibliothek dazu, explizite Stille-Frames zu senden. Dadurch wird der Stream aufrechterhalten, während gleichzeitig angezeigt wird, dass kein aktives Audiomaterial bereitgestellt wird.

Puffer leeren. Wenn Sie weniger als die Audio-Daten einer vollständigen Periode bereitstellen, löscht die Bibliothek die verbleibenden Daten und füllt die Lücke mit Stille auf, um das korrekte Timing beizubehalten und eine Audio-Drift zu verhindern.

Videokontinuität

Wenn Sie ein Video veröffentlichen, sorgt die Bibliothek für Sie für die Kontinuität der Einzelbilder:

Erstveröffentlichung. Die Bibliothek sendet schwarze Bilder, bis Sie Ihr erstes Bild bereitstellen, sodass der Stream den Abonnenten sofort zur Verfügung steht.

Wiederholung des letzten Bildes. Wenn Sie keine Frames mehr bereitstellen, wiederholt die Bibliothek das zuletzt von Ihnen bereitgestellte Frame bis zu 2 Sekunden lang, um den Abonnenten eine flüssige Wiedergabe zu gewährleisten.

Ausweichlösung mit schwarzem Rahmen. Nach 2 Sekunden Wiederholung wechselt die Bibliothek zu schwarzen Bildern. Dies signalisiert den Abonnenten, dass das Video nicht mehr aktiv bereitgestellt wird, während der Stream aufrechterhalten bleibt.

Bewährte Praktiken

• Senden Sie Medien in regelmäßigen Abständen, die Ihrer konfigurierten Abtastrate und Bildrate entsprechen
• Überwachen Sie die Pufferstatistiken, um sicherzustellen, dass Sie genügend Daten bereitstellen.
• Behandeln Sie das Ereignis „Puffer leer“, um zu erkennen, wann Ihre Medienpuffer leer sind
• Passen Sie Ihre Strategie zur Medienerstellung an schwankende Verarbeitungsauslastungen an

Abonnieren von Streams

Sobald ein Teilnehmer mit der Veröffentlichung beginnt, wird ein „Stream-Received“-Ereignis ausgelöst, und Sie entscheiden, ob Sie das Abonnement abonnieren möchten. Medien aus Ihren Abonnements werden über drei separate Kanäle bereitgestellt.

Video wird pro Stream übertragen. Jeder Frame wird mit einer Kennung des Abonnenten gesendet, die dessen Quelle identifiziert, sodass Sie das Video jedes Teilnehmers unabhängig verarbeiten können – für die Layout-Verwaltung, die Aufzeichnung pro Stream oder die Anwendung von Effekten pro Stream.

Gemischter Ton wird auf Sitzungsebene als einzelner Stream übertragen. Die Bibliothek mischt die Audiodaten aus allen abonnierten Streams automatisch zu einem Stream in dem Format zusammen, das Sie für den Abonnenten-Mix konfiguriert haben. Einzelne Teilnehmer lassen sich in diesem gemischten Audiostream nicht unterscheiden.

Individueller Ton wird pro Stream auf Abonnentenebene bereitgestellt. Diese Funktion ist derzeit als Beta-Funktion verfügbar. Der Ton wird in dem Format übertragen, in dem er vom Stream empfangen wird – Linear PCM 16 Bit – und weder die Abtastrate noch die Kanalanzahl können vor dem Empfang konfiguriert werden.

Untertitel werden pro Stream ausgeliefert. Diese Funktion ist derzeit als Beta-Funktion verfügbar. Jedes Untertitel-Ereignis umfasst die Angabe des Abonnenten, der den Quell-Stream identifiziert, den Untertiteltext sowie die Angabe, ob es sich um ein endgültiges oder vorläufiges Ergebnis handelt:

• Vorläufig Die Ergebnisse sind vorläufig und werden möglicherweise aktualisiert, sobald weitere Sprachdaten verarbeitet wurden. Nützlich für die Live-Anzeige.
• Finale Die Ergebnisse sind vollständig und werden sich nicht mehr ändern. Verwenden Sie diese zur Speicherung oder zur weiteren Verarbeitung.

Verwaltung der Medienpuffer

Der Connector verwaltet interne Puffer für die von Ihnen veröffentlichten Audio- und Videodaten. Sie können die Menge der in der Warteschlange befindlichen Medien jederzeit einsehen und beide Puffer leeren, wenn Sie ausstehende Medien verwerfen müssen – beispielsweise, wenn Sie einen Bot mitten in einer Äußerung unterbrechen.

Puffer-Drain-Ereignisse

Ein „Buffer-Drained“-Ereignis wird ausgelöst, wenn ein interner Audio- oder Videopuffer leer ist. Dies geschieht, wenn Medien schneller an die Sitzung übertragen werden, als Ihre Anwendung sie bereitstellen kann. Betrachten Sie das Ereignis als Signal, Ihre Medienproduktionsrate zu erhöhen oder Ihre Veröffentlichungsstrategie anzupassen.

Das Ereignis nutzt eine Hysterese, um eine übermäßige Auslösung zu vermeiden: Nach einer ersten Entleerung wird es erst dann erneut ausgelöst, wenn der Puffer mit neuen Medien aufgefüllt wurde und anschließend wieder leer ist. Dadurch wird eine Flut von wiederholten Benachrichtigungen verhindert, solange der Puffer leer bleibt.

Ereignismodell

Beide Bibliotheken stellen denselben Satz von Ereignissen bereit, gruppiert nach dem Objekt, zu dem sie gehören.

Wie diese Ereignisse bereitgestellt werden, ist je nach Sprache unterschiedlich. In Python ist jedes Ereignis ein Callback, den Sie registrieren. In Node.js werden die einmalig auftretenden Lebenszyklusereignisse – „Session connected“, „Publisher stream created“ und „Subscriber connected“ – von dem Promise verarbeitet, das von der entsprechenden Methode zurückgegeben wird, während die übrigen Ereignisse Callbacks sind. Weitere Informationen finden Sie im Sprachhandbuch.

Grenzen