排入佇列

總覽

Web Receiver SDK 支援使用 QueueData 和 QueueManager 的 SDK 提供的預設佇列進行佇列，也可透過 cast.framework.QueueBase 使用 自訂佇列，並使用 QueueManager 進行更新。

Queueing API 提供下列功能，可讓應用程式與 Cast 更緊密整合：

  • 支援 Google 與合作夥伴的雲端佇列實作，以便將外部儲存和建立的佇列直接載入至 Cast 裝置。
  • 允許在佇列中分頁項目而非一次載入所有內容的機制。
  • 支援新的訊息，例如前往下一個項目、上一個項目、擷取項目的視窗，以及取得與一組佇列項目相關的媒體資訊。
  • 用於管理佇列插入、移除及更新的 QueueManager。

預設佇列

Web Receiver SDK 以預設佇列的形式提供有限的佇列支援。

如要使用預設佇列，請在寄件者端負載的 LoadRequestData 中提供 queueData，或使用 PlayerManager#load 傳送本機載入要求。另請參閱載入媒體。

在接收器端，載入初始媒體後，可使用 QueueManager 修改佇列。

自訂待播清單

如果預設佇列並未提供應用程式所需的佇列功能，則可建立自訂佇列，讓您使用更多功能及享有更多彈性。

應用程式開發人員可以實作 cast.framework.QueueBase 來建立 Web Receiver 端佇列。

以下提供一個簡易佇列的基本範例，其中系統會覆寫 initialize 呼叫，然後將佇列項目清單以及佇列說明提供給 Cast 裝置。

另請參閱載入媒體。

// Creates a simple queue with a combination of contents.
const DemoQueue = class extends cast.framework.QueueBase {
 constructor() {
   super();

   /**
    * List of media urls.
    * @private @const {!Array<string>}
    */
   this.myMediaUrls_ = [...];
 }
 /**
  * Provide a list of items.
  * @param {!cast.framework.messages.LoadRequestData} loadRequestData
  * @return {!cast.framework.messages.QueueData}
  */
 initialize(loadRequestData) {
   const items = [];
   for (const mediaUrl of this.myMediaUrls_) {
     const item = new cast.framework.messages.QueueItem();
     item.media = new cast.framework.messages.MediaInformation();
     item.media.contentId = mediaUrl;
     items.push(item);
   }
   let queueData = loadRequestData.queueData;
   // Create a new queue with media from the load request if one doesn't exist.
   if (!queueData) {
     queueData = new cast.framework.messages.QueueData();
     queueData.name = 'Your Queue Name';
     queueData.description = 'Your Queue Description';
     queueData.items = items;
     // Start with the first item in the playlist.
     queueData.startIndex = 0;
     // Start from 10 seconds into the first item.
     queueData.currentTime = 10;
   }
   return queueData;
 }
};

在此範例中，initialize 呼叫中的項目清單會在提供者的 QueueBase 建構函式呼叫中提供。然而，在執行雲端佇列時，自訂 Web 接收器的邏輯可從外部擷取項目，然後做為初始化呼叫的一部分傳回。

為了示範更全面的佇列 API 使用方法，以下示範一個實作 QueueBase 類別的大部分佇列。

const DemoQueue = class extends cast.framework.QueueBase {
 constructor() {
   /** @private {} */
   super();
   YourServer.onSomeEvent = this.updateEntireQueue_;
 }

 /**
  * Initializes the queue.
  * @param {!cast.framework.messages.LoadRequestData} loadRequestData
  * @return {!cast.framework.messages.QueueData}
  */
 initialize(loadRequestData) {
   let queueData = loadRequestData.queueData;
   // Create a new queue with media from the load request if one doesn't exist.
   if (!queueData) {
     queueData = new cast.framework.messages.QueueData();
     queueData.name = 'Your Queue Name';
     queueData.description = 'Your Queue Description';
     // Put the first set of items into the queue
     const items = this.nextItems();
     queueData.items = items;
     // Start with the first item in the playlist.
     queueData.startIndex = 0;
     // Start from 10 seconds into the first item.
     queueData.currentTime = 10;
   }
   return queueData;
 }

 /**
  * Picks a set of items from remote server after the reference item id and
  * return as the next items to be inserted into the queue. When
  * referenceItemId is omitted, items are simply appended to the end of the
  * queue.
  * @param {number} referenceItemId
  * @return {!Array<cast.framework.QueueItem>}
  */
 nextItems(referenceItemId) {
   // Assume your media has a itemId and the media url
   return this.constructQueueList_(YourServer.getNextMedias(referenceItemId));
 }

 /**
  * Picks a set of items from remote server before the reference item id and
  * return as the items to be inserted into the queue. When
  * referenceItemId is omitted, items are simply appended to beginning of the
  * queue.
  * @param {number} referenceItemId
  * @return {!Array<cast.framework.QueueItem>}
  */
 prevItems(referenceItemId) {
   return this.constructQueueList_(YourServer.getPrevMedias(referenceItemId));
 }

 /**
  * Constructs a list of QueueItems based on the media information containing
  * the item id and the media url.
  * @param {number} referenceItemId
  * @return {!Array<cast.framework.QueueItem>}
  */
 constructQueueList_(medias) {
   const items = [];
   for (media of medias) {
     const item = new cast.framework.messages.QueueItem(media.itemId);
     item.media = new cast.framework.messages.MediaInformation();
     item.media.contentId = media.url;
     items.push(item);
   }
   return items;
 }

 /**
  * Logs the currently playing item.
  * @param {number} itemId The unique id for the item.
  * @export
  */
 onCurrentItemIdChanged(itemId) {
   console.log('We are now playing video ' + itemId);
   YourServer.trackUsage(itemId);
 }
};

在上述範例中，YourServer 是您的雲端佇列伺服器，並具備擷取特定媒體項目邏輯的邏輯。

如要使用 QueueBase 實作的佇列，必須在 CastReceiverContext 中設定佇列選項：

const context = cast.framework.CastReceiverContext.getInstance();
context.start({queue: new DemoQueue()});

管理佇列

QueueManager 為開發人員提供有用的存取方法，讓他們能夠存取目前儲存的佇列項目清單，以及目前播放的項目。並提供佇列、移除和更新佇列項目等作業。下列程式碼片段說明如何存取 QueueManager 的執行個體：

const context = cast.framework.CastReceiverContext.getInstance();
const queueManager = context.getPlayerManager().getQueueManager();

預設佇列管理

初始佇列載入完畢後，QueueManager 可用於執行各種操作，例如擷取目前的項目、擷取佇列中的所有項目，以及使用 insertItems、removeItems 和 updateItems 更新佇列中的項目。

自訂佇列管理

以下為自訂佇列實作的範例，該範例會根據某些事件使用插入和移除方法。此範例也示範了 updateItems 的使用方法，讓開發人員可以修改現有佇列中的佇列項目，例如移除廣告插播。

const DemoQueue = class extends cast.framework.QueueBase {
  constructor() {
    super();

    /** @private @const {!cast.framework.QueueManager} */
    this.queueManager_ = context.getPlayerManager().getQueueManager();
  }

  /**
   * Provide a list of items.
   * @param {!cast.framework.messages.LoadRequestData} loadRequestData
   * @return {!cast.framework.messages.QueueData}
   */
  initialize(loadRequestData) {
    // Your normal initialization; see examples above.
    return queueData;
  }

  /** Inserts items to the queue. */
  onSomeEventTriggeringInsertionToQueue() {
    const twoMoreUrls = ['http://url1', 'http://url2'];
    const items = [];
    for (const mediaUrl of twoMoreUrls) {
      const item = new cast.framework.QueueItem();
      item.media = new cast.framework.messages.MediaInformation();
      item.media.contentId = mediaUrl;
      items.push(item);
    }
    // Insert two more items after the current playing item.
    const allItems = this.queueManager_.getItems();
    const currentItemIndex = this.queueManager_.getCurrentItemIndex();
    const nextItemIndex = currentItemIndex + 1;
    let insertBefore = undefined;
    if (currentItemIndex >= 0 &&
        currentItemIndex < allItems.length - 1) {
      insertBefore = allItems[nextItemIndex].itemId;
    }
    this.queueManager_.insertItems(items, insertBefore);
  }

  /** Removes a particular item from the queue. */
  onSomeEventTriggeringRemovalFromQueue() {
    this.queueManager_.removeItems([2]);
  }

  /** Removes all the ads from all the items across the entire queue. */
  onUserBoughtAdFreeVersion() {
    const items = this.queueManager_.getItems();
    this.queueManager_.updateItems(items.map(item => {
      item.media.breaks = undefined;
      return item;
    }));
  }
};

收到和送出的訊息

為完整支援接收器端佇列擷取功能做為真實資訊來源，CAF 接收器 SDK 會導入並處理下列其他佇列訊息：

傳入的訊息 參數 傳出回應訊息 返回
繼續 不需要參數。 MEDIA_STATUS 接收器會 (在需要時透過 NextItems() 擷取) 並開始播放下一個項目。
上一步 不需要參數。 MEDIA_STATUS 網路接收器會 (在必要時透過 prevItems() 擷取) 並開始播放上一個項目。
FETCH_ITEMS FetchItemsRequestData QUEUE_CHANGE cast.framework.messages.QueueChange。以插入案例為例，JSON 中的項目欄位會包含擷取的新項目清單。
GET_ITEMS_INFO 含有 itemIds 的 GetItemsInfoRequestData： Array<number> ITEMS_INFO cast.framework.messages.ItemsInfo。
GET_QUEUE_IDS 不需要參數。 QUEUE_IDS cast.framework.messages.QueueIds。

對於 NEXT/PREVIOUS，如果 Web 接收器上的現有佇列表示法沒有更多項目，則系統會自動叫用 QueueBase.nextItems() 或 QueueBase.prevItems() 以接收更多項目。

針對 FETCH_ITEM，系統會呼叫 Cloud 佇列的 QueueBase 實作中對應的函式 fetchItems，以擷取要傳回給網頁接收器的相關資料。

系統擷取更多項目時，就會觸發新的訊息類型 QUEUE_CHANGE 並傳回寄件者。請參閱各種佇列變更類型。

針對 GET_ITEMS_INFO，系統不會觸發 QueueBase 的實作作業，網路接收器也會傳回 ID 清單已知的媒體資訊。

隨機播放佇列

如要設定待隨機處理佇列中的項目，請在將項目載入佇列時，將 QueueData 的 shuffle 標記設為 true。

如果您要使用 QueueBase 的實作，請使用 shuffle 方法傳回已重組的項目清單。

如要隨機調整現有佇列，請使用 QUEUE_UPDATE MessageType 的 shuffle 標記，而非 QUEUE_SHUFFLE 指令。詳情請參閱 QueueUpdateRequestData 相關說明。

重複播放模式

如要將佇列中的項目設為重複項目，請在將項目載入佇列時，將 QueueData 的 repeatMode 屬性設為指定的 RepeatMode。

如要變更現有佇列的 RepeatMode，請使用 QueueUpdateRequestData 的 repeatMode 屬性，該屬性使用 QUEUE_UPDATE MessageType。

上一頁
曲目
下一頁
廣告插播時間點