本頁面說明如何使用 Co-Watching API 支援共同觀看情境。
初始設定
如要準備程式庫使用,即時分享應用程式應初始化代表共同觀看工作階段的 CoWatchingClient
物件。
如要使用 Meet 即時分享 SDK,請呼叫 AddonClientFactory.getClient
方法。這樣做會回傳 AddonClient
,做為共同觀看工作階段的進入點。
如要使用用戶端,請從 AddonClient
呼叫 newSessionBuilder
方法,傳回新 AddonSession
的建構工具。newSessionBuilder
會實作 AddonSessionHandler
介面,以處理工作階段外掛程式提供的回呼。
如要啟動工作階段,請將 withCoWatching
方法新增至建構工具。
以下程式碼範例顯示共同觀看用戶端物件的基本初始化:
Java
class AwesomeVideoAddonSessionHandler implements AddonSessionHandler {}
// For sample implementation, see the "Manage remote state" section below.
class AwesomeVideoCoWatchingHandler implements CoWatchingHandler {}
public ListenableFuture<AddonSession> initialSetup() {
AddonClient meetClient = AddonClientFactory.getClient();
return meetClient
.newSessionBuilder(
new AwesomeVideoAddonSessionHandler())
.withCoWatching(new AwesomeVideoCoWatchingHandler())
.begin();
}
在使用者動作時傳送通知
當本機使用者在裝置上執行動作 (例如暫停或尋找播放媒體) 時,程式庫必須獲得通知,才能將這些動作鏡像至共同觀看體驗中的其他參與者。如需如何通知程式庫多個狀態的範例,請參閱「開始使用」。
您可以透過以下方法控制共同觀看狀態:
CoWatchingClient.notifyBuffering
:通知 Meet,由於先前的媒體切換、媒體跳轉或一般網路壅塞,導致媒體仍有緩衝問題而無法播放。CoWatchingClient.notifyEnded
:通知 Meet 媒體播放器已到達目前媒體的結尾。CoWatchingClient.notifyPauseState
通知 Meet 使用者暫停或取消暫停播放媒體,讓 Meet 向其他使用者鏡像投放動作。CoWatchingClient.notifyPlayoutRate
:通知 Meet 使用者已將媒體的播放率更新為新的值 (例如 1.25 倍)。CoWatchingClient.notifyQueueUpdate
:通知 Meet 佇列已變更,以便 Meet 為其他使用者建立鏡像。CoWatchingClient.notifyReady
:通知 Meet 緩衝處理已完成,且媒體已可播放,時間從提供的時間戳記開始。CoWatchingClient.notifySeekToTimestamp
:通知 Meet 使用者已搜尋媒體播放點,讓 Meet 向其他使用者建立該動作。CoWatchingClient.notifySwitchedToMedia
:通知 Meet 使用者已切換媒體,以便 Meet 將該內容傳遞給其他使用者。您也可以選擇同時更新佇列
以下程式碼範例說明如何通知使用者:
Java
public void onVideoPaused(Duration currentTimestamp) {
// Use Meet to broadcast the pause state to ensure other participants also pause.
this.session.getCoWatching().notifyPauseState(/* paused= */ true, currentTimestamp);
};
管理遠端狀態
如要套用遠端參與者傳入的更新,您必須讓 Meet 使用 CoWatchingHandler.onCoWatchingStateChanged()
回呼直接管理本機媒體播放狀態。
Meet 也需要呼叫 CoWatchingHandler.onStateQuery()
回呼,以擷取媒體播放的目前位置。系統會定期呼叫這個 API,因此其寫入作業必須具有高效能 (例如小於 100 毫秒)。
以下程式碼範例顯示 CoWatchingHandler
的實作方式:
Java
class AwesomeVideoCoWatchingHandler implements CoWatchingHandler {
/** Applies incoming playback state to the local video. */
public void onCoWatchingStateChanged(CoWatchingState newState) {
// Handle transition to new video.
if (!newState.mediaId().equals(this.videoPlayer.videoUrl)) {
this.videoPlayer.loadVideo(newState.mediaId());
}
// Only adjust the local video playout if it's sufficiently diverged from the timestamp in the
// applied update.
if (newState
.mediaPlayoutPosition()
.minus(this.videoPlayer.videoTimestamp)
.compareTo(Duration.ofMillis(500))
> 0) {
this.videoPlayer.seek(newState.mediaPlayoutPosition());
}
// Update pause state, if necessary.
if (newState.playbackState().equals(PLAY) && this.videoPlayer.isPaused) {
this.videoPlayer.unpause();
} else if (newState.playbackState().equals(PAUSE) && !this.videoPlayer.isPaused) {
this.videoPlayer.pause();
}
}
/** Returns local video playback state. */
public Optional<QueriedCoWatchingState> onStateQuery() {
return Optional.of(QueriedCoWatchingState.of(
/* mediaPlayoutPosition= */ this.videoPlayer.videoTimestamp));
}
}