Bevorzugte Video Codec API des Herausgebers

Ein praktischer Leitfaden zum Einstellen von Codec-Präferenzen für einzelne Verlage, zum Verständnis, wie diese Präferenzen mit der Aushandlung interagieren, und zum Bestätigen des Codecs, der während einer Live-Sitzung tatsächlich verwendet wird.

Dieses Thema umfasst die folgenden Abschnitte:

Voraussetzungen

Bevor Sie die Preferred Video Codec API über das SDK verwenden können, müssen Sie sie in Ihren Projekteinstellungen aktivieren:

Rufen Sie das Vonage API Dashboard auf und wählen Sie Ihr Projekt aus.
Wählen Sie in den Projekteinstellungen den bevorzugten Videocodec auf Projektebene aus.
Nehmen Sie die erforderlichen Einstellungen vor, um die Codec-Einstellungen auf SDK-Ebene zu aktivieren.

Anmerkung: Ihre Auswahl wirkt sich nur auf das ausgewählte Projekt aus. Weitere Informationen über unterstützte Codecs finden Sie in der Video-Codecs Leitfaden.

Übersicht

Mit der Publisher Preferred Video Codec API kann jeder Publisher seine eigene Codec-Priorität deklarieren, unabhängig vom bevorzugten Codec auf Projektebene, der in der Vonage Dashboard. Sie können entweder eine explizit geordnete Liste von Codecs angeben oder die Entscheidung an das SDK delegieren, indem Sie Automatikbetrieb.

Das ist wichtig: Diese API setzt eine Präferenzist keine Einschränkung. Andere Codecs können immer noch ausgehandelt werden, wenn die bevorzugten Codecs nicht verfügbar sind. Die Präferenz beeinflusst die Reihenfolge, in der die Codecs im SDP-Angebot erscheinen, und verleiht ihnen bei der Verhandlung eine höhere Priorität.

Verwenden Sie diese API, wenn die Einstellung auf Projektebene nicht spezifisch genug für Ihre Bedürfnisse ist. Zu den üblichen Szenarien gehören:

Sitzungen mit verschiedenen Geräten. Verschiedene Verlage in derselben Sitzung profitieren von unterschiedlichen Codecs. Mit den Präferenzen für jeden Verleger kann jedes Gerät die Codec-Reihenfolge angeben, die ihm am besten passt.
Funktionsspezifische Verlage. Ein Anbieter von Bildschirmfreigaben kann von VP9 profitieren, während ein Kameraanbieter in derselben Sitzung VP8 wegen der breiteren Kompatibilität bevorzugt.
Überlassen Sie die Entscheidung dem SDK. Wenn Sie eine Liste nicht hart kodieren wollen, delegiert der automatische Modus die Wahl an das SDK.

Wenn jeder Publisher in Ihrer Anwendung denselben Codec verwenden soll und die Einstellung auf Projektebene diese Wahl bereits widerspiegelt, benötigen Sie diese API nicht.

VP8 ist ein obligatorisch zu implementierender Codec, der von allen Endpunkten unterstützt wird. Da alle unterstützten Codecs automatisch als Fallback-Codecs hinzugefügt werden, steht VP8 immer als ultimativer Fallback-Codec zur Verfügung, auch wenn Sie ihn nicht ausdrücklich in Ihre Liste aufnehmen.

Hintergrundinformationen zu den VP8-, H.264- und VP9-Codecs selbst, Codec-Abdeckungstabellen und die Einstellung für den bevorzugten Codec auf Projektebene finden Sie in der Video-Codecs Leitfaden.

Auswahl eines Modus

Automatisch

Übergeben Sie die Zeichenfolge 'automatic' (Web, React Native) oder rufen Sie die entsprechende Fabrikmethode bei nativen SDKs auf. Das SDK wertet die lokale Umgebung aus und bestimmt eine geeignete Codec-Prioritätenfolge.

Verwenden Sie den Automatikmodus, wenn:

Sie möchten, dass sich das SDK an verschiedene Browser und Geräte anpasst, ohne dass Sie Ihre eigene Logik für jedes Gerät pflegen müssen.
Sie bevorzugen einen zukunftskompatiblen Ansatz. Der automatische Modus wird in zukünftigen SDK-Versionen ausgefeiltere Auswahlheuristiken enthalten, so dass Applikationen, die ihn heute übernehmen, von Verbesserungen ohne Codeänderungen profitieren.

Anmerkung: Die vom automatischen Modus verwendeten Heuristiken werden im Laufe der Zeit weiterentwickelt. Frühe Versionen verwenden eine Basisauswahlstrategie. Zukünftige SDK-Versionen können zusätzliche Signale wie Hardware-Fähigkeiten, Netzwerkbedingungen und Sitzungstopologie berücksichtigen. Behandeln Sie den automatischen Modus als empfohlenen Standard, es sei denn, Sie haben einen besonderen Grund, eine Liste fest zu kodieren.

Handbuch

Liefern Sie ein geordnetes Array von Codecs. Das erste Element hat die höchste Priorität:

['vp9', 'vp8']          prefer VP9, fall back to VP8, then remaining codecs
['h264']                 prefer H.264; remaining codecs (VP8, VP9) are appended automatically as fallbacks
['vp8', 'h264', 'vp9']  explicit full ordering: VP8 first, then H.264, then VP9

Verwenden Sie den manuellen Modus, wenn Sie genau wissen, welche Codec-Reihenfolge für einen bestimmten Verlag oder ein bestimmtes Gerät am besten ist. Diese Einstellung setzt den im Dashboard konfigurierten bevorzugten Codec auf Projektebene außer Kraft.

Anmerkung: Die von Ihnen angegebenen Codecs legen die Prioritätsreihenfolge fest, aber alle übrigen unterstützten Codecs werden immer als Fallback angefügt. Zum Beispiel, wenn Sie ['vp9'] bedeutet, dass VP9 bevorzugt wird, aber VP8 und H.264 bleiben zur Verhandlung verfügbar, wenn VP9 nicht verfügbar ist.

Standard

Wenn Sie nicht preferredVideoCodecs verwendet der Herausgeber den im Dashboard konfigurierten bevorzugten Codec auf Projektebene. Dies ist das gleiche Verhalten wie vor der Existenz dieser API.

Vergleich

Modus	Wann zu verwenden	Zukunftssicher?
Automatisch	Sie möchten, dass das SDK die beste Reihenfolge auswählt	Ja, profitiert von SDK-Updates
Handbuch Liste	Sie kennen die genaue Codec-Reihenfolge für diesen Verlag	Nein, Sie verwalten die Liste
Standard	Einstellung auf Projektebene ist ausreichend	N/A, verwendet die Projektumgebung

Empfohlene Codec-Bestellungen für gängige Szenarien

Wenn Sie den manuellen Modus verwenden, hängt die Reihenfolge der Codecs von der Art der Sitzung, dem Publikum und dem Anwendungsfall ab. In der folgenden Tabelle sind häufige Szenarien mit einem Vorschlag für preferredVideoCodecs Wert und die dahinter stehenden Überlegungen.

Szenario	Vorgeschlagene Reihenfolge	Warum
Große Sitzung / Webinar (geroutet)	`['vp9', 'vp8']`	Sowohl VP9 als auch VP8 unterstützen skalierbares Video, was für Sitzungen mit vielen Teilnehmern wichtig ist. VP9 bietet eine bessere Komprimierung und benötigt bei gleicher Qualität weniger Bandbreite. VP8 ist der Fallback für Endpunkte, an denen VP9 Scalable Video nicht verfügbar ist (siehe die Codec-Abdeckungstabellen). H.264 mit Scalable Video wird von der Plattform nicht unterstützt, so dass H.264 für große Sitzungen vermieden und stattdessen VP8 oder VP9 verwendet werden sollte.
Kleine Sitzung, nur iOS-Geräte	`['h264', 'vp8']`	iOS-Geräte verfügen über hardwarebeschleunigtes H.264, das die CPU-Last verringert und die Akkulaufzeit verbessert. VP8 bleibt als sicherer Fallback erhalten.
Kleine Sitzung, eingeschränkte Bandbreite	`['vp9', 'vp8']`	VP9 erreicht eine bessere Qualität als VP8 bei gleicher Bitrate. VP8 ist der Fallback für Endgeräte, die VP9 nicht unterstützen (z. B. ältere Safari-Versionen).
Herausgeber von Bildschirmfreigaben	`['vp9', 'vp8']`	Bildschirminhalte werden mit VP9 sehr effizient komprimiert, da es scharfe Kanten und statische Bereiche besser verarbeitet. VP8 ist der Fallback.
Bildschirmfreigabe mit bester Kompression	`['vp9']`	Bevorzugen Sie VP9 wegen seiner besseren Handhabung von scharfen Kanten und statischen Regionen. Andere unterstützte Codecs werden weiterhin mit geringerer Priorität als Fallback ausgehandelt.
Maximale Kompatibilität (muss alle Geräte erreichen)	`['vp8']`	VP8 ist der einzige Codec, der von allen OpenTok-Endpunkten unterstützt wird, einschließlich des Linux-SDKs (das H.264 nicht unterstützt) und älterer Safari-Versionen (denen VP9 fehlen kann).

Tipp: Wenn keines der oben genannten Szenarien auf Ihren Anwendungsfall zutrifft, sollten Sie die Verwendung von Automatikbetrieb stattdessen. Damit kann das SDK die beste Reihenfolge auf der Grundlage der lokalen Umgebung auswählen und wird in künftigen Versionen verbesserte Heuristiken einbauen.

Wie die Codec-Aushandlung funktioniert

Das Festlegen eines bevorzugten Codecs bewirkt nicht garantieren, dass der Codec verwendet wird. Der endgültige Codec wird durch einen Verhandlungsprozess bestimmt, der von der Sitzungsart abhängt.

Geroutete Sitzungen (Media Router)

In einem weitergeleitete Sitzungverhandelt der Verlag mit dem Medienrouter:

Der Herausgeber sendet ein SDP-Angebot mit Codecs, die nach der Präferenz geordnet sind (der bevorzugte Codec erscheint zuerst).
Der Media Router prüft das Angebot und wählt einen von ihm unterstützten Codec aus.
Wenn der bevorzugte Codec unterstützt wird, wird er verwendet. Andernfalls greift der Media Router auf den nächsten Codec im Angebot zurück.

Da der Medienrouter die Medienverteilung übernimmt, erhalten alle Teilnehmer einer gerouteten Sitzung Video, das mit demselben Codec codiert ist, den der Herausgeber ausgehandelt hat.

Vermittelte Sitzungen (Peer-to-Peer)

In einem weitergeleitete Sitzunggibt es keinen Media Router. Jedes Herausgeber-Teilnehmer-Paar verhandelt unabhängig voneinander:

Der Verleger sendet ein SDP-Angebot mit nach Präferenzen geordneten Codecs.
Der Teilnehmer antwortet mit einer SDP-Antwort, in der die von ihm unterstützten Codecs aufgeführt sind.
Das Paar wählt den Codec mit der höchsten Priorität, den beide Endpunkte unterstützen.

Das bedeutet, dass verschiedene Teilnehmerpaare in derselben weitergeleiteten Sitzung unterschiedliche Codecs verwenden können, je nach den Fähigkeiten der einzelnen Teilnehmer.

Was kann einen Rückfall verursachen?

Ein Fallback bedeutet, dass der bevorzugte Codec nicht verwendet wurde und stattdessen ein anderer Codec für die Veröffentlichung ausgewählt wurde. Dies kann passieren, wenn:

Der bevorzugte Codec wird vom entfernten Endpunkt (bei weitergeleiteten Sitzungen) oder vom Media Router (bei gerouteten Sitzungen) nicht unterstützt.
Der Browser oder das Gerät unterstützt die Codierung mit dem bevorzugten Codec nicht (z. B. H.264 auf einigen Android-Geräten, VP9 auf älteren Safari-Versionen).

Da es zu Fallbacks kommen kann, sollten Sie immer den verwendeten Codec verifizieren, anstatt davon auszugehen, dass die Voreinstellung beachtet wurde. Die Kenntnis des aktiven Codecs hilft Ihnen:

Fehlersuche und Qualitätskontrolle. Protokollieren Sie, welcher Codec für die Diagnose und Qualitätsanalyse über Insights verwendet wird.
Zur Laufzeit anpassen. Passen Sie die Einstellungen für Auflösung oder Bitrate an die Stärken des ausgehandelten Codecs an (z. B. kann VP9 die gleiche Qualität bei einer niedrigeren Bitrate als VP8 erreichen).
Gewährleisten Sie die Konsistenz der Sitzungen. Vergewissern Sie sich, dass alle Anbieter in einer Sitzung den erwarteten Codec verwenden, insbesondere in gerouteten Sitzungen, in denen der Media Router einen einzigen Codec pro Anbieter an alle Teilnehmer verteilt.

Siehe Verify des verwendeten Codecs für plattformspezifische Anweisungen.

Einstellung der Präferenzen nach Plattform

Web-SDK

Die Übergabe eines leeren Arrays oder einer ungültigen Codec-Zeichenkette führt dazu, dass der Herausgeber mit einer Fehlermeldung OT_INVALID_PARAMETER Fehler.

iOS-SDK

Android-SDK

Übergabe einer null oder leere Liste an manual() wirft IllegalArgumentException.

Windows-SDK

Die Übergabe einer leeren Liste führt zu ArgumentException.

Linux-SDK

// Automatic mode
otc_publisher_settings* settings = otc_publisher_settings_new();
otc_publisher_settings_set_preferred_video_codecs_automatic(settings);

otc_publisher_callbacks callbacks = {0};
struct otc_publisher* publisher =
    otc_publisher_new_with_settings(&callbacks, settings);
otc_publisher_settings_delete(settings);

// Manual mode
otc_publisher_settings* settings = otc_publisher_settings_new();

otc_video_codec_type codecs[] = {
    OTC_VIDEO_CODEC_VP9,
    OTC_VIDEO_CODEC_H264,
    OTC_VIDEO_CODEC_VP8
};

otc_publisher_settings_set_preferred_video_codecs(
    settings, codecs, sizeof(codecs) / sizeof(codecs[0]));

otc_publisher_callbacks callbacks = {0};
struct otc_publisher* publisher =
    otc_publisher_new_with_settings(&callbacks, settings);
otc_publisher_settings_delete(settings);

React Native SDK

Verify des verwendeten Codecs

Nachdem ein Publisher mit dem Streaming begonnen hat, verwenden Sie die SDK-Statistik-APIs, um festzustellen, welcher Codec tatsächlich ausgehandelt wurde. Gehen Sie nicht davon aus, dass die Präferenz beachtet wurde.

Überprüfung der unterstützten Codecs vor der Veröffentlichung

Sie können proaktiv prüfen, welche Codecs ein Client unterstützt, bevor Sie eine Präferenz festlegen.

Web-SDK:

Android SDK:

Linux SDK:

otc_media_utils_codecs* supported_codecs = NULL;
otc_status status = otc_media_utils_get_supported_codecs(&supported_codecs);
if (status == OTC_SUCCESS) {
  for (size_t i = 0; i < supported_codecs->number_encoder_video_codecs; i++) {
    printf("Encoder: %d\n", supported_codecs->encoder_video_codecs[i]);
  }
  for (size_t i = 0; i < supported_codecs->number_decoder_video_codecs; i++) {
    printf("Decoder: %d\n", supported_codecs->decoder_video_codecs[i]);
  }
  otc_media_utils_codecs_delete(supported_codecs);
}

Auslesen des aktiven Codecs aus der SDK-Statistik

Anmerkung: Das Auslesen des aktiven Codecs aus den SDK-Statistiken erfordert Web SDK 2.33 oder höher, mit dem die Client Observability API eingeführt wurde, die Codec-Informationen im stats-Objekt offenlegt.

Web-SDK

Herausgeber:

Abonnent:

Für WebRTC-Informationen auf niedrigerer Ebene, verwenden Sie getRtcStatsReport():

Android-SDK

iOS-SDK

React Native SDK

Verwendung von Insights und Video Inspector

Das Tool Videoinspektor zeigt Codec, Auflösung und Bildrate im Modul Qualitätsmetrik an. Bewegen Sie die Maus über einen beliebigen Punkt auf einer gezeichneten Linie, um den zu diesem Zeitpunkt verwendeten Codec anzuzeigen.

Sie können die Stream-Statistiken auch nach Codec filtern in Einblicke GraphQL-Abfragen:

Bewährte Praktiken

Beachten Sie den Sitzungstyp. Bei gerouteten Sitzungen teilen sich alle Teilnehmer einen Codec pro Verleger. Bei weitergeleiteten Sitzungen verhandelt jedes Paar unabhängig voneinander, so dass ein und derselbe Herausgeber verschiedene Codecs mit verschiedenen Teilnehmern verwenden kann.
Angleichung der Einstellungen auf Verlags- und Projektebene. Der bevorzugte Codec auf Projektebene gilt immer noch für Verlage, die keine eigene Präferenz festlegen. Stellen Sie sicher, dass beide Ebenen konsistent sind, um Überraschungen zu vermeiden.
Überprüfen Sie die Codec-Unterstützung auf dem Client. Bevor Sie eine manuelle Präferenz einstellen, verwenden Sie OT.getSupportedCodecs() (Web) oder MediaUtils.SupportedCodecs (Android), um zu bestätigen, dass der bevorzugte Codec lokal verfügbar ist.
Beginnen Sie mit dem automatischen Modus. Wenn Sie keine speziellen Codec-Anforderungen haben, verwenden Sie den automatischen Modus und lassen Sie das SDK wählen. Zukünftige SDK-Versionen werden die automatische Auswahlheuristik verfeinern, und Ihre Anwendung wird davon profitieren, ohne dass der Code geändert werden muss.
Verifizieren Sie den ausgehandelten Codec. Verwenden Sie getStats() oder getRtcStatsReport() um den Codec nach Beginn der Veröffentlichung zu bestätigen.
Testen Sie verschiedene Zielgeräte. Die Codec-Unterstützung variiert je nach Browser und Plattform. Siehe die Codec-Abdeckungstabellen für Details. Testen Sie Ihre Einstellungskonfiguration auf den Geräten, die Ihre Benutzer tatsächlich verwenden.

Navigation

Bevorzugte Video Codec API des Herausgebers

Voraussetzungen

Übersicht

Auswahl eines Modus

Automatisch

Handbuch

Standard

Vergleich

Empfohlene Codec-Bestellungen für gängige Szenarien

Wie die Codec-Aushandlung funktioniert

Geroutete Sitzungen (Media Router)

Vermittelte Sitzungen (Peer-to-Peer)

Was kann einen Rückfall verursachen?

Einstellung der Präferenzen nach Plattform

Web-SDK

iOS-SDK

Android-SDK

Windows-SDK

Linux-SDK

React Native SDK

Verify des verwendeten Codecs

Überprüfung der unterstützten Codecs vor der Veröffentlichung

Auslesen des aktiven Codecs aus der SDK-Statistik

Web-SDK

Android-SDK

iOS-SDK

React Native SDK

Verwendung von Insights und Video Inspector

Bewährte Praktiken