Java-Server-SDK

Das Vonage Java SDK bietet Methoden für:

Einrichtung

Die Video API wurde in Version 8.0.0 des SDK im Jahr 2023 hinzugefügt. Es wird jedoch empfohlen, die neueste Version zu verwenden, um Sicherheit, Fehlerbehebungen und neue Funktionen in späteren Versionen zu erhalten.

Maven Central:

Der beste Weg, das Vonage Java Server SDK zu Ihrem Projekt hinzuzufügen, besteht darin, die Abhängigkeit zu Ihrem Projekt-Build-System hinzuzufügen. Anweisungen finden Sie auf der Seite GitHub-Repositorium wie auch Maven-Zentrale für Maven, Gradle, Ivy, SBT, Leiningen usw.

Maven

Wenn Sie Maven als Build-Tool verwenden, können Sie die Abhängigkeiten in der pom.xml Datei:

<dependency>
    <groupId>com.vonage</groupId>
    <artifactId>server-sdk</artifactId>
    <version>9.3.1</version>
</dependency>

Gradle

Wenn Sie Gradle als Build-Tool verwenden, können Sie die Abhängigkeiten in der build.gradle Datei:

dependencies {
  implementation 'com.vonage:server-sdk:9.+'
}

Verwendung

Das Vonage Java SDK ermöglicht Ihnen die Verwendung von Vonage REST-APIs unter Verwendung seiner Subclients, einen für jede API. Für die Arbeit mit dem Video APIverwenden Sie die com.vonage.client.video.VideoClient Klasse. Diese enthält Methoden für alle unterstützten Endpunkte der API-Spezifikation. Sie erhalten diese, indem Sie die getVideoClient() Methode der VonageClient.

Initialisierung

Initialisieren einer com.vonage.client.VonageClient Objekt mit Ihrer Video Application ID und Ihrem privaten Schlüssel. Dies gibt ein Objekt mit allen Methoden zurück, die für die Arbeit mit der Video API erforderlich sind.

import com.vonage.client.VonageClient;
import com.vonage.client.video.*;

// Inside a class or method...
VideoClient videoClient = VonageClient.builder()
    .applicationId("APP_ID")
    .privateKeyPath("/path/to/private.key")
    .build().getVideoClient();

Token generieren

Ihre Vonage Video-Anwendung benötigt ein Token auf der Client-Seite, um nützlich zu sein. Dieses Token kann vom Server-SDK über die Funktion VideoClient#generateToken(String sessionId, TokenOptions options) Methode. Sie müssen die Sitzungs-ID übergeben, aber die options ist nicht zwingend erforderlich (er kann null sein, oder Sie können den Parameter VideoClient#generateToken(String sessionId) der Einfachheit halber). Die Methode gibt ein signiertes JWT mit den entsprechenden Ansprüchen als Base64-kodierte Zeichenfolge zurück, die Sie an den Client weitergeben können.

String jwt = videoClient.generateToken(sessionId);

Standardmäßig hat das Token eine Verfallszeit von 24 Stunden und die Rolle ist auf "Herausgeber" eingestellt (com.vonage.video.client.Role#PUBLISHER). Die maximal zulässige Verfallszeit beträgt 30 Tage. Sie können diese mit der Funktion TokenOptions Parameter, der das Builder-Muster verwendet. Sie können auch die Metadaten der Verbindung festlegen, die jedoch 1000 Zeichen nicht überschreiten dürfen.

TokenOptions tokenOptions = TokenOptions.builder()
        .expiryLength(Duration.ofHours(6))
        .role(Role.SUBSCRIBER)
        .build();
String jwt = videoClient.generateToken(sessionId, tokenOptions);

Siehe die Leitfaden zur Token-Erstellung für eine genauere Erläuterung der Konfigurationsoptionen.

Sitzungen erstellen

Um eine Vonage-Videositzung zu erstellen, verwenden Sie die VideoClient#createSession(CreateSessionRequest request) Methode. Die Website request ist optional und wird zur Angabe verwendet:

  • Ob die Sitzung den Vonage Video Media Router verwendet
  • Ein Standort-Hinweis für den Vonage Video-Server.
  • Ob die Sitzung automatisch archiviert wird.

Wie bei den meisten anderen Anforderungseigenschaften wird das Builder-Muster verwendet. Zur Instanziierung beginnen Sie mit der statischen builder() Methode, legen Sie die Eigenschaften fest und rufen Sie build() um eine Instanz zu konstruieren.

Wenn die Anfrage erfolgreich war, wird eine CreateSessionResponse zurückgegeben wird. Die nützlichste Eigenschaft ist die Sitzungs-ID, die man durch den Aufruf der Funktion getSessionId() Methode. Möglicherweise möchten Sie die Sitzungs-ID zur späteren Verwendung aufbewahren, da sie ein gängiger Parameter für andere Methodenaufrufe ist.

// A session that attempts to stream media directly between clients:
CreateSessionResponse session = videoClient.createSession();

// A session that uses the Vonage Video Media Router:
CreateSessionResponse session = videoClient.createSession(
    CreateSessionRequest.builder().mediaMode(MediaMode.ROUTED).build()
);

// A Session with a location hint:
CreateSessionResponse session = videoClient.createSession(
    CreateSessionRequest.builder().location("12.34.56.78").build()
);

// A session that is automatically archived (it must be used for the routed media mode)
CreateSessionResponse session = videoClient.createSession(
    CreateSessionRequest.builder()
      .mediaMode(MediaMode.ROUTED)
      .archiveMode(ArchiveMode.ALWAYS)
      .build()
);

// Store this sessionId in the database for later use:
String sessionId = session.getSessionId();

Arbeiten mit Archiven

Sie können nur Sitzungen archivieren, die den Vonage Video Media Router verwenden (d. h. Sitzungen, bei denen der Medienmodus auf MediaMode.ROUTED). Weitere Informationen zur Archivierung finden Sie in der Vonage Video-Archivierung Leitfaden für Entwickler.

Archiv erstellen

Sie können die Aufzeichnung einer Vonage-Videositzung manuell über die Schaltfläche createArchive(Archive request) Methode. Wenn dies erfolgreich ist, werden zusätzliche Eigenschaften in der Datei com.vonage.client.video.Archive Instanz mit der Antwort des Servers.

Beachten Sie, dass Sie ein Archiv nur in einer Sitzung starten können, in der Clients verbunden sind. Die Seite Archive Anfrage folgt beim Aufbau dem Builder-Muster. Alle Eigenschaften außer der Sitzungs-ID sind optional, daher die Archive.builder(String sessionId) Methode erfordert diesen Parameter.

// A simple Archive with the default property values
Archive archive = videoClient.createArchive(Archive.builder(sessionId).build());

// Store this archiveId in the database for later use
UUID archiveId = archive.getId();

Sie können die Audio- oder Videoaufzeichnung auch deaktivieren, indem Sie die Funktion hasAudio(false) oder hasVideo(false) Methoden eines Archive Baumeister.

// Audio-only archive
Archive.builder(sessionId).hasVideo(false).hasAudio(true).build();

Einstellung des Ausgabemodus auf OutputMode.INDIVIDUAL bewirkt, dass jeder Stream im Archiv in einer eigenen Datei aufgezeichnet wird:

Archive.builder(sessionId).outputMode(OutputMode.INDIVIDUAL).name("My recording").build();

Die OutputMode.COMPOSED ist der Standardwert für die Option outputMode. Es archiviert alle aufzuzeichnenden Streams in einer einzigen (zusammengesetzten) Datei.

Sie können nur die resolution für zusammengesetzte Archive. Wenn Sie die Option resolution Eigenschaft und setzen Sie auch die outputMode Eigenschaft zu OutputMode.INDIVIDUALdie build() Methode wird eine IllegalStateException.

// Set the archive resolution to 1280x720
Archive.builder(sessionId).resolution(Resolution.HD_LANDSCAPE).build();

Aufnahme stoppen

Sie können die Aufzeichnung eines gestarteten Archivs mit der Taste VideoClient#stopArchive(String archiveId) Methode.

// Stop an Archive
Archive archive = videoClient.stopArchive(archiveId);

Ein Archiv löschen

Um ein Archiv zu löschen, verwenden Sie die VideoClient#deleteArchive(String archiveId) Methode.

// Delete an Archive
videoClient.deleteArchive(archiveId);

Ein einzelnes Archiv abrufen

Um eine Einzelperson zu bekommen Archive Instanz (und alle zugehörigen Informationen) aus einer Archiv-ID zu erhalten, verwenden Sie die VideoClient#getArchive(String archiveId) Methode.

// Retrieve archive info
Archive archive = videoClient.getArchive(archiveId);

Mehrere Archive abrufen

Sie können eine Liste aller Archive, die Sie in Ihrer Anwendung erstellt haben (bis zu 1000), mit der Funktion VideoClient#listArchives() Methode. Um die zurückgegebenen Ergebnisse zu filtern, rufen Sie die Methode VideoClient#listArchives(ListArchivesRequest request) Methode statt. Das Request-Objekt wird nach dem Builder-Muster aufgebaut und hat drei optionale Parameter:

  • sessionId: ermöglicht es Ihnen, die Ergebnisse auf Archive zu beschränken, die mit einer bestimmten Sitzung verbunden sind.
  • count: begrenzt die Anzahl der zurückgegebenen Ergebnisse.
  • offsetNumbers: verwirft eine anfängliche Anzahl von Ergebnissen (nützlich, wenn es mehr als 1000 Archive gibt).

Eine IllegalArgumentException wird ausgelöst, wenn die offset oder count negativ sind oder wenn die count größer als 1000 ist. Die resultierende Liste von Archives werden in Datum/Uhrzeit Reihenfolge, vom neuesten zum ältesten.

// Get a list with the first 1000 archives
List<Archive> archives = videoClient.listArchives();

// Get a list of the first 50 archives created
List<Archive> archives = videoClient.listArchives(
    Archive.builder().count(50).build()
);

// Get a list of the next 50 archives
List<Archive> archives = videoClient.listArchives(
    Archive.builder().offset(50).count(50).build()
);

Sie können auch die Liste der Archive für eine bestimmte Sitzungs-ID abrufen und optional die Parameter offset und count wie oben beschrieben verwenden.

// Get a list with the first 1000 archives for a specific session
List<Archive> archives = videoClient.listArchives(
    ListStreamCompositionsRequest.builder().sessionId(sessionId).build()
);

// Get a list of the next 1000 archives for a specific session
List<Archive> archives = videoClient.listArchives(
    ListStreamCompositionsRequest.builder()
      .offset(1000)
      .sessionId(sessionId)
      .build()
);

Archiv-Layout festlegen

Für zusammengesetzte Archive können Sie das Archivlayout dynamisch festlegen (während das Archiv aufgezeichnet wird), indem Sie den Befehl VideoClient#setArchiveLayout(String archiveId, ArchiveLayout layout) Methode.

Sie können das Layout auch bei der Erstellung des Archivs festlegen (siehe Archive.Builder#layout(ArchiveLayout layout)). Siehe Anpassen des Videolayouts für zusammengestellte Archive für weitere Informationen.

Verwenden Sie die ArchiveProperties Erbauer wie folgt:

StreamCompositionLayout layout = StreamCompositionLayout.standardLayout(ScreenLayoutType.VERTICAL);
videoClient.updateArchiveLayout(archiveId, layout);

Für benutzerdefinierte Layouts müssen Sie das Stylesheet (in CSS) angeben:

StreamCompositionLayout layout = StreamCompositionLayout.customLayout("stream { position: absolute; }")

Sie können auch den Layouttyp für die Bildschirmfreigabe festlegen, wobei das ursprüngliche Layout auf ScreenLayoutType.BEST_FIT:

StreamCompositionLayout layout = StreamCompositionLayout.screenshareLayout(ScreenLayoutType.PIP);

Stream zu einem Archiv hinzufügen

Sie können einen Stream zu einem zusammengesetzten Archiv hinzufügen, das mit dem Befehl streamMode eingestellt auf StreamMode.MANUAL unter Verwendung der VideoClient#addArchiveStream(String archiveId, String streamId) Methode und übergibt dabei die Archiv-ID und Stream-ID die Sie dem Archiv hinzufügen möchten.

Die VideoClient#addArchiveStream(String archiveId, String streamId, Boolean audio, Boolean video) Variante dieser Methode ermöglicht es Ihnen, Audio und Video zu aktivieren oder zu deaktivieren.

Standardmäßig sind beide aktiviert (d. h. true).Übergabe in false für die audio Parameter deaktiviert den Ton, die Übergabe von false für Video wird Video deaktiviert (was zu einem reinen Audio-Stream führt). Die Einstellung eines dieser Werte auf null entspricht der Standardeinstellung (d. h. true in beiden Fällen).

// Add stream to archive
videoClient.addArchiveStream(archiveId, streamId);

// Add stream to archive without audio
videoClient.addArchiveStream(archiveId, streamId, false, true);

// Add stream to archive without video
videoClient.addArchiveStream(archiveId, streamId, true, false);

Entfernen eines Streams aus einem Archiv

Sie können einen Datenstrom aus einem zusammengesetzten Archiv entfernen, indem Sie die VideoClient#removeArchiveStream(String archiveId, String streamId) Methode. Wie beim Hinzufügen eines Streams muss das Archiv mit streamMode auf "manuell" eingestellt.

videoClient.removeArchiveStream(archiveId, streamId);

Arbeiten mit Broadcasts

Die Arbeit mit Live-Übertragungen ist der Arbeit mit Archiven sehr ähnlich

Alle Live-Übertragungen auflisten

List<Broadcast> broadcasts = videoClient.listBroadcasts();

Details zu einer bestimmten Sendung abrufen

Broadcast broadcast = videoClient.getBroadcast(broadcastId);

Starten Sie einen Live-Streaming-Broadcast

Um die Übertragung einer Sitzung erfolgreich zu starten, muss mindestens ein Client mit der Sitzung verbunden sein. Die Live-Streaming-Übertragung kann einen HLS-Endpunkt und bis zu fünf RTMP-Server gleichzeitig für eine Sitzung ansteuern. Die Sitzungs-ID ist erforderlich, und es sollte mindestens ein Ausgangsstrom (RTMP und/oder HLS) angegeben werden.

Broadcast broadcast = videoClient.createBroadcast(
		Broadcast.builder(sessionId)
            .hls(Hls.builder().lowLatency(true).build())
            .resolution(Resolution.HD_LANDSCAPE)
		    .streamMode(StreamMode.MANUAL)
            .layout(StreamCompositionLayout.builder(ScreenLayoutType.BEST_FIT)
                    .screenshareType(ScreenLayoutType.PIP)
                    .build()
            )
            .maxDuration(Duration.ofMinutes(45))
        .build()
);

Anhalten einer Rundfunkaufzeichnung

Broadcast broadcast = videoClient.stopBroadcast(broadcastId);

Dynamische Änderung des Layout-Typs einer Live-Streaming-Übertragung

videoClient.updateBroadcastLayout(broadcastId,
		StreamCompositionLayout.standardLayout(ScreenLayoutType.HORIZONTAL)
);

Hinzufügen oder Entfernen von Streams in einem Live-Streaming Broadcast

Ändern Sie die Streams, die in einer Sendung enthalten sind, die mit der Einstellung streamMode auf SteamMode.MANUAL:

videoClient.addBroadcastStream(broadcastId, streamId);

videoClient.removeBroadcastStream(broadcastId, streamId);

Arbeiten mit Strömen

Sie können Informationen über einen Stream erhalten, indem Sie die VideoClient#getStream(String sessionId, String streamId) Methode. Wenn die Anfrage erfolgreich war, wird ein com.vonage.client.video.GetStreamResponse Instanz zurückgegeben, die zur Abfrage der für den Stream interessanten Eigenschaften verwendet werden kann.

GetStreamResponse stream = videoClient.getStream(sessionId, streamId);

// Stream Properties
VideoType videoType = stream.getVideoType();
String name = stream.getName();
List<String> layoutClassList = stream.layoutClassList();

Sie können Informationen über alle Streams in einer Sitzung erhalten, indem Sie die VideoClient#listStreams(String sessionId) Methode. Diese gibt eine List von GetStreamResponse Instanzen, die Sie durchsuchen können, um die gesuchten Informationen zu finden.

// Get list of streams from a session ID
List<GetStreamResponse> streams = videoClient.listStreams(sessionId);
int count = streams.size();

// Get stream ID for a given stream name
UUID myStreamId = streams.stream()
    .filter(s -> "My Stream".equals(s.getName()))
    .findFirst().ifPresent(GetStreamResponse::getId)
    .orElseThrow(() -> new IllegalStateException(
          "Could not find stream in session "+sessionId
    ));

Stream-Layout festlegen

Sie können die Layout-Klassen eines Datenstroms mit der Funktion VideoClient#setStreamLayout(String sessionId, List<SessionStream> streams) Methode. Diese nimmt als Eingabe die Sitzungs-ID und die Liste der zu ändernden Streams. Jeder Stream wird durch eine SessionStream Objekt, das nach dem Builder-Muster aufgebaut ist, wobei die Stream-ID zur Identifizierung des Streams verwendet wird (dies ist ein obligatorischer Parameter). Verwenden Sie die SessionStream.Builder#layoutClassList(List<String> layoutClassList) Methode, um die Layouts für den Stream festzulegen (oder der Einfachheit halber die varargs-Variante). Zur Veranschaulichung: Nehmen wir an, wir haben zwei Streams, nennen wir sie stream1 und stream2. Angenommen, stream1Id und stream2Id sind Zeichenketten mit den IDs von stream1 und stream2 und wollen die stream1Layout-Klassen zu full und focusaber stream2zu min.

So lässt sich das erreichen:

SessionStream
    stream1 = SessionStream.builder(stream1Id)
        .layoutClassList("full", "focus").build(),
    stream2 = SessionStream.builder(stream2Id)
        .layoutClassList("min").build();

videoClient.setStreamLayout(sessionId, stream1, stream2);

Moderation

Trennen von Clients

Ihr Anwendungsserver kann die Verbindung eines Clients zu einer Vonage Video-Sitzung trennen, indem er die Funktion VideoClient#forceDisconnect(String sessionId, String connectionId) Methode.

videoClient.forceDisconnect(sessionId, connectionId);

Die connectionId wird verwendet, um die Verbindungs-ID eines Clients anzugeben, der mit der Sitzung verbunden ist.

Weitere Informationen über die Funktion "Force Disconnect" und die Ausnahmecodes finden Sie in der REST-API-Dokumentation.

Erzwingen, dass Clients in einer Sitzung das veröffentlichte Audio stummschalten

Sie können den Herausgeber eines bestimmten Streams dazu zwingen, die Veröffentlichung von Audiodaten zu beenden, indem Sie die VideoClient#muteStream(String sessionId, String streamId) Methode.

videoClient.muteStream(sessionId, streamId);

Sie können den Herausgeber aller Streams in einer Sitzung (mit Ausnahme einer optionalen Liste von Streams) zwingen, die Veröffentlichung von Audiodaten zu beenden, indem Sie die VideoClient#muteSession(String sessionId, boolean active, String... excludedStreamIds) Methode. Die Website active bestimmt, ob vorhandene und neue Streams standardmäßig stummgeschaltet werden. Der optionale excludedStreamIds können Sie die Streams angeben, die von dieser Stummschaltungsanforderung ausgeschlossen werden sollen.

videoClient.muteSession(sessionId, true);

Weitere Informationen finden Sie unter Stummschalten des Tons von Streams in einer Sitzung.

Signalisierung

Sie können Signale an alle Teilnehmer einer Sitzung senden, indem Sie die VideoClient#signalAll(String sessionId, SignalRequest request) Methode. Um einen bestimmten Teilnehmer zu signalisieren, verwenden Sie die VideoClient#signal(String sessionId, String connectionId, SignalRequest request) Methode an.

Die SignalRequest (konstruiert nach dem Builder-Muster) hat zwei Felder: type und data, die beide obligatorisch sind. Sie entsprechen den Typ- und Datenparametern, die in den Handlern für empfangene Client-Signale übergeben werden. Stellen Sie sicher, dass die type Zeichenfolge die maximale Länge (128 Byte) nicht überschreitet und die data String die maximale Länge (8 kB) nicht überschreitet.

SignalRequest signal = SignalRequest.builder()
    .type("chat")
    .data("Hello, World!")
    .build();

// Signal all connections in the session
videoClient.signalAll(sessionId, signal);

// Signal a specific connection in the session
videoClient.signal(sessionId, connectionId, signal);

Weitere Informationen zu Signalisierungs- und Ausnahmecodes finden Sie in der REST-API-Spezifikation.

SIP

Verbinden Sie Ihre SIP-Plattform mit einer Vonage-Videositzung, indem Sie die VideoClient#sipDial(SipDialRequest request) Methode. Sie müssen die URI, sessionId und das Token in der Anfrage angeben. Sie können angeben, ob die Aushandlung zwischen Vonage und dem SIP-Endpunkt sicher (mit TLS) erfolgen soll, indem Sie die Option secure Parameter von SipDialRequest.Builder#uri(URI uri, boolean secure) zu true. Optional können Sie auch einen Benutzernamen und ein Passwort für die Authentifizierung in der Anfrage angeben.

SipDialRequest request = SipDialRequest.builder()
	.uri(URI.create("sip:user@sip.partner.com"), false)
	.sessionId(sessionId).token(token).build();

SipDialResponse parsed = videoClient.sipDial(request);

Sie können allen Teilnehmern eines Anrufs DTMF-Töne vorspielen, indem Sie die VideoClient#sendDtmf(String sessionId, String digits) Methode. Um Töne nur an einen bestimmten Teilnehmer zu senden, verwenden Sie die VideoClient#sendDtmf(String sessionId, String connectionId, String digits) Methode an.

String digits = "*0123456789#";
// Send to all participants in the session
videoClient.sendDtmf(sessionId, digits);

// Send to a specific participant
videoClient.sendDtmf(sessionId, connectionId, digits);

Anforderungen

Sie benötigen eine Vonage Video App ID und einen privaten Schlüssel, die Sie erhalten, wenn Sie sich bei Ihrem Vonage Video API-Konto.

Das Vonage Java SDK erfordert JDK 8 oder höher zum Kompilieren. Die Laufzeit erfordert Java SE 8 oder höher.

Anmerkungen zur Veröffentlichung

Siehe die Veröffentlichungen Seite für Details zu jeder Version.