GetHLSStreamingSessionURL

擷取串流的 HTTP 即時串流 (HLS) 網址。然後，您可以在瀏覽器或媒體播放器中打開 URL 以查看流內容。

StreamName和StreamARN參數都是可選的，但您必須在調用此 API 操作StreamARN時指定StreamName或。

Amazon Kinesis 影片串流對於透過 HLS 提供資料有以下要求：

• 視頻播放軌道要求。

• 資料保留必須大於 0。

• 每個片段的視訊軌道必須包含 H.264 格式的「進階視訊編碼」(AVC) 中的編解碼器私人資料，或是 H.265 格式的 HEVC (MPEG-4 規格 ISO/IEC 14496-15)。如需將串流資料轉換為特定格式的相關資訊，請參閱 NAL Adaptation Flags。

• 每個片段的音軌（如果存在）必須包含 AAC 格式的編解碼器私有數據（A AC 規格 ISO/IEC 13818-7）。

Kinesis Video Streams HLS 工作階段包含片段的 MPEG-4 形式 (也稱為 FMP4 或 CMAF) 或 MPEG-2 形式 (也稱為 TS 區塊，HLS 規格也支援) 的片段。如需有關 HLS 片段類型的詳細資訊，請參閱 HLS 規格。

下列程序說明如何搭配 Kinesis Video Streams 使用 HLS：

1. 呼叫 GetDataEndpoint API 以取得端點。然後使用 --end 點 url 參數將GetHLSStreamingSessionURL請求發送到此端點。

2. 使GetHLSStreamingSessionURL用擷取 HLS 網址。Kinesis Video Streams 會建立 HLS 串流工作階段，以便使用 HLS 通訊協定存取串流中的內容。 GetHLSStreamingSessionURL傳回工作階段的 HLS 主播放清單 (使用 HLS 串流所需的根資源) 的驗證 URL (包含加密的工作階段權杖)。

   注意

   不要在未經授權的實體可以訪問它的地方共享或存儲此令牌。令牌提供對流內容的訪問。使用與 AWS 憑據一起使用的相同措施來保護令牌。

   透過播放清單提供的媒體僅包含要求的串流、時間範圍和格式。沒有其他媒體資料 (例如要求視窗外的框架或替代位元率) 可用。

3. 將 HLS 主播放清單的 URL (包含加密的工作階段權杖) 提供給支援 HLS 通訊協定的媒體播放器。Kinesis Video Streams 可讓 HLS 媒體播放清單、初始化片段和媒體片段透過主播放清單 URL 取得。初始化片段包含流的編解碼器私有數據，以及設置視頻或音頻解碼器和渲染器所需的其他數據。媒體片段包含 H.264 編碼的視訊影格或 AAC 編碼的音訊樣本。

4. 媒體播放器接收經過身份驗證的 URL，並正常請求流元數據和媒體數據。當媒體播放器請求數據時，它會調用以下操作：

   • GetHLSMasterPlaylist：擷取 HLS 主播放清單，其中包含每個音軌GetHLSMediaPlaylist動作的 URL，以及媒體播放器的其他中繼資料，包括估計的位元率和解析度。

   • GetHLSMediaPlaylist：擷取 HLS 媒體播放清單，其中包含可透過動作存取 MP4 初始化片段的 URL，以及使用GetMP4InitFragment動作存取 MP4 媒體片段的 URL。GetMP4MediaFragmentHLS 媒體播放列表還包含有關播放器需要播放的流的元數據，例如PlaybackMode是LIVE或ON_DEMAND。對於使用的工作階段，HLS 媒體播放清單通常是靜態PlaybackType的ON_DEMAND。HLS 媒體播放清單會持續更新，PlaybackType其LIVE中包含新的片段，適用於. 視頻軌道和音軌（如果適用）有一個不同的 HLS 媒體播放列表，其中包含特定軌道的 MP4 媒體 URL。

   • 獲取 MP4InitFragment：檢索 MP4 初始化片段。媒體播放器通常會在載入任何媒體片段之前載入初始化片段。此片段包含「fytpmoov」和「MP4 原子，以及初始化媒體播放器解碼器所需的子原子。

     初始化片段不對應於 Kinesis 視訊串流中的片段。它僅包含流和相應軌道的編解碼器私有數據，媒體播放器需要解碼媒體幀。

   • 獲取 MP4MediaFragment：檢索 MP4 媒體片段。這些片段包含「moofmdat」和「MP4 原子及其子原子，其中包含編碼片段的媒體框架及其時間戳記。

     注意

     每個片段中包含的編解碼器私有資料 (CPD) 都包含特定於編解碼器的初始化資訊，例如影格速率、解析度和編碼設定檔，這些資訊對於正確解碼片段是必要的。對於 TS 和 MP4，在串流工作階段期間支援 CPD 變更。因此，會話中的片段可以在 CPD 中具有不同的信息，而不會中斷播放。對於每個串流工作階段，只允許 500 個 CPD 變更。

     重要

     不支援追蹤變更。在整個查詢的媒體中，曲目必須保持一致。如果串流中的片段從僅具有視訊變更為同時具有音訊和視訊，或是 AAC 音軌變更為 A-Law 音軌，串流就會失敗。

     使用此動作擷取的資料可計費。如需相關資訊，請參閱 定價。

   • GetTSFragment：檢索包含流中所有軌道的初始化和媒體數據的 MPEG TS 片段。

     注意

     如果ContainerFormat是MPEG_TS，則使用此 API 代替GetMP4InitFragment和GetMP4MediaFragment檢索流媒體。

     使用此動作擷取的資料可計費。如需詳細資訊，請參閱 Kinesis Video Streams 定價。

串流工作階段 URL 不得在播放器之間共用。如果多個媒體播放器共用工作階段，服務可能會限制工作階段。如需連線限制，請參閱 Kinesis Video Streams 限制。

您可以透過監控 GetMP4MediaFragment.OutgoingBytes Amazon CloudWatch 指標來監控媒體播放器使用的資料量。如需使用 CloudWatch 監視 Kinesis Video Streams 的相關資訊，請參閱監控 Kinesis Video Streams。如需定價資訊，請參閱 Amazon Kinesis Video Streams 定價和定AWS價。HLS 工作階段和傳出 AWS 資料均需支付費用。

請參閱文件指南中的影片播放範例：使用擷 AWS CLI 取 HLS 串流工作階段 URL和範例：在 HTML 和中使用 HLS JavaScript。

如需有關 HLS 的詳細資訊，請參閱 Apple 開發人員網站上的 HTTP 即時串流。

重要

如果在叫用 Kinesis 影片串流封存媒體 API 之後擲回錯誤，除了 HTTP 狀態碼和回應本文之外，它還包含下列資訊：

• x-amz-ErrorTypeHTTP 標頭 — 除了 HTTP 狀態碼提供的內容之外，還包含更具體的錯誤類型。

• x-amz-RequestIdHTTP 標頭 — 如果您想向其報告問題 AWS，支持團隊可以在給出請求 ID 時更好地診斷問題。

HTTP 狀態碼和 ErrorType 標頭都可用於對錯誤是否可重試以及在什麼情況下進行程式設計決定，以及提供用戶端程式設計人員可能需要採取哪些動作才能成功再試一次的資訊。

如需詳細資訊，請參閱本主題底部的「錯誤」一節，以及常見錯誤。

請求語法

POST /getHLSStreamingSessionURL HTTP/1.1
Content-type: application/json

{
   "ContainerFormat": "string",
   "DiscontinuityMode": "string",
   "DisplayFragmentTimestamp": "string",
   "Expires": number,
   "HLSFragmentSelector": { 
      "FragmentSelectorType": "string",
      "TimestampRange": { 
         "EndTimestamp": number,
         "StartTimestamp": number
      }
   },
   "MaxMediaPlaylistFragmentResults": number,
   "PlaybackMode": "string",
   "StreamARN": "string",
   "StreamName": "string"
}

URI 請求參數

請求不會使用任何 URI 參數。

請求主體

請求接受採用 JSON 格式的下列資料。

ContainerFormat

指定應該用於封裝媒體的格式。指定FRAGMENTED_MP4容器格式會將媒體封裝至 MP4 片段 (fMP4 或 CMAF)。這是建議使用的包裝，因為包裝開銷最小。另一個容器格式選項是MPEG_TS。HLS 自發布以來一直支持 MPEG TS 塊，有時是舊版 HLS 播放器上唯一支持的包裝。MPEG TS 通常具有 5-25% 的封裝開銷。這意味著 MPEG TS 通常需要比 fMP4 多 5-25% 的頻寬和成本。

預設值為 FRAGMENTED_MP4。

類型：字串

有效值:FRAGMENTED_MP4 | MPEG_TS

必要：否

DiscontinuityMode

指定何時標記片段之間不連續性的旗標新增至媒體播放清單。

媒體播放程式通常會根據每個片段的時間戳記，建立要播放的媒體內容時間軸。這意味著，如果片段之間存在任何重疊或間隙（通常情況下，如果設置HLSFragmentSelector為SERVER_TIMESTAMP），媒體播放器時間軸在某些地方的片段之間也會有很小的間隙，並且會覆蓋其他地方的幀。媒體播放器時間軸中的間隙可能會導致播放停止，重疊可能會導致播放不安。當片段之間存在不連續標誌時，媒體播放器預期會重置時間軸，從而導致下一個片段在上一個片段之後立即播放。

支援下列模式：

• ALWAYS：在 HLS 媒體播放列表中的每個片段之間放置一個不連續性標記。ALWAYS如果片段時間戳記不準確，建議使用的值為。

• NEVER：不會將不連續性標記放置在任何地方。建議使用的NEVER值，以確保媒體播放器時間軸最準確地對應至製作者時間戳記。

• ON_DISCONTINUITY: 不連續性標記放置在間隙或重疊超過 50 毫秒的片段之間。對於大多數播放情況，建議使用的值為，ON_DISCONTINUITY以便只有在媒體時間軸出現重大問題時才會重設媒體播放器時間軸 (例如遺失片段)。

預設值HLSFragmentSelector為ALWAYS何時設定為SERVER_TIMESTAMP，以及設定為NEVER時PRODUCER_TIMESTAMP。

類型：字串

有效值:ALWAYS | NEVER | ON_DISCONTINUITY

必要：否

DisplayFragmentTimestamp

指定 HLS 媒體播放清單中應包含片段開始時間戳記的時間。媒體播放程式通常會將播放磁頭位置報告為相對於播放工作階段中第一個片段開始的時間。但是，當開始時間戳記包含在 HLS 媒體播放清單中時，某些媒體播放器可能會根據片段時間戳記將目前的播放磁頭報告為絕對時間。這對於建立可向觀眾顯示媒體掛鐘時間的播放體驗非常有用。

預設值為 NEVER。如果HLSFragmentSelector是SERVER_TIMESTAMP，時間戳記將是伺服器啟動時間戳記。同樣，如果HLSFragmentSelector是PRODUCER_TIMESTAMP，時間戳記將是生產者開始時間戳記。

類型：字串

有效值:ALWAYS | NEVER

必要：否

Expires

要求的工作階段到期前的時間 (以秒為單位)。此值可以介於 300（5 分鐘）到 43200（12 小時）之間。

當工作階段到期時，無法對該工作階段GetTSFragment進行GetMP4InitFragmentGetMP4MediaFragment、、或的新呼叫。GetHLSMasterPlaylist GetHLSMediaPlaylist

預設值為 300 (5 分鐘)。

類型：整數

有效範圍：最小值 300。最大值為 43200。

必要：否

HLSFragmentSelector

請求片段的時間範圍和時間戳記的來源。

如果是或，則PlaybackMode需要此參ON_DEMAND數LIVE_REPLAY。如果是，則此參數 PlaybackMode 是可選的LIVE。如果PlaybackMode是LIVE，則FragmentSelectorType可以設定，但不TimestampRange應設定。如果PlaybackMode是ON_DEMAND或LIVE_REPLAY，則TimestampRange必須同時FragmentSelectorType設定 AND。

類型：HLSFragmentSelector 物件

必要：否

MaxMediaPlaylistFragmentResults

HLS 媒體播放清單中傳回的片段數目上限。

如果PlaybackMode是LIVE，則最新的片段會返回到此值。如果PlaybackMode是ON_DEMAND，則返回最舊的片段，直到此最大數量。

當即時 HLS 媒體播放清單中可用的片段數目較多時，視訊播放程式通常會在開始播放之前緩衝內容。增加緩衝區大小會增加播放延遲，但會降低播放期間發生重新緩衝的可能性。我們建議即時 HLS 媒體播放清單至少有 3 個片段和最多 10 個片段。

如果是LIVE或LIVE_REPLAY，預設值為 5 個片段，如果PlaybackMode是，則預設值PlaybackMode為 1,000 ON_DEMAND。

5,000 個片段的最大值對應於具有 1 秒片段的流上的視頻 80 分鐘以上，以及具有 10 秒片段的流上的視頻超過 13 小時。

類型：Long

有效範圍：最小值為 1。最大值為 5000。

必要：否

PlaybackMode

是否要擷取即時、即時重播或封存的隨選資料。

三種工作階段類型的功能包括：

• LIVE：對於此類型的工作階段，HLS 媒體播放清單會在可用時不斷更新為最新片段。我們建議媒體播放器以一秒鐘的時間間隔擷取新的播放清單。在媒體播放程式中播放此類工作階段時，使用者介面通常會顯示「即時」通知，而且沒有用於選擇播放視窗中要顯示的位置的定位器控制項。

  注意

  在LIVE模式下，最新的可用片段包含在 HLS 媒體播放列表中，即使片段之間存在間隙（也就是說，如果缺少片段）。這樣的間隙可能會導致媒體播放器停止或導致播放跳躍。在此模式下，如果片段比播放清單中的最新片段舊，則不會將片段新增至 HLS 媒體播放清單。如果在後續片段新增至播放清單後，遺失的片段變為可用，則不會新增較舊的片段，且不會填滿間隙。

• LIVE_REPLAY：對於此類型的工作階段，HLS 媒體播放清單的更新方式與LIVE模式更新的方式類似，不同之處在於它會從指定開始時間包含片段開始。而不是在攝入片段時添加片段，而是在下一個片段的持續時間過去時添加片段。例如，如果工作階段中的片段長度為兩秒鐘，則每兩秒鐘就會將新片段新增至媒體播放清單。此模式對於能夠在偵測到事件時開始播放，並繼續在工作階段建立時尚未擷取的即時串流媒體非常有用。此模式對於串流先前封存的媒體也很有用，而不受ON_DEMAND模式中 1,000 片段限制的限制。

• ON_DEMAND：對於此類型的工作階段，HLS 媒體播放清單會包含工作階段的所有片段，最多可達到中MaxMediaPlaylistFragmentResults指定的數目。每個工作階段只能擷取一次播放清單。在媒體播放程式中播放此類工作階段時，使用者介面通常會顯示定位器控制項，以便在播放視窗中選擇要顯示的位置。

在所有播放模式中，如果FragmentSelectorType是PRODUCER_TIMESTAMP，且如果有多個片段具有相同的開始時間戳記，則 HLS 媒體播放清單中會包含具有最大片段編號 (即最新片段) 的片段。其他片段不包括在內。具有不同時間戳但持續時間重疊的片段仍包含在 HLS 媒體播放清單中。這可能會導致媒體播放器中出現意外行為。

預設值為 LIVE。

類型：字串

有效值:LIVE | LIVE_REPLAY | ON_DEMAND

必要：否

StreamARN

要擷取 HLS 主播放清單 URL 的資料流的 Amazon 資源名稱 (ARN)。

您必須指定StreamName或StreamARN。

類型：字串

長度限制：長度下限為 1。長度上限為 1024。

模式：arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+

必要：否

StreamName

要擷取 HLS 主播放清單 URL 的串流名稱。

您必須指定StreamName或StreamARN。

類型：字串

長度限制：長度下限為 1。長度上限為 256。

模式：[a-zA-Z0-9_.-]+

必要：否

回應語法

HTTP/1.1 200
Content-type: application/json

{
   "HLSStreamingSessionURL": "string"
}

回應元素

如果動作成功，則服務傳回 HTTP 200 回應。

服務會傳回下列 JSON 格式的資料。

HLSStreamingSessionURL

媒體播放程式可用來擷取 HLS 主播放清單的 URL (包含工作階段權杖)。

類型：字串

錯誤

如需所有動作常見錯誤的資訊，請參閱常見錯誤。

ClientLimitExceededException

Kinesis Video Streams 已限制要求，因為您已超過限制。稍後再嘗試撥打電話。如需有關限制的資訊，請參閱 Kinesis Video Streams 限制。

HTTP 狀態碼：400

InvalidArgumentException

指定的參數超出其限制、不受支援或無法使用。

HTTP 狀態碼：400

InvalidCodecPrivateDataException

視訊串流中至少一個軌道中的編解碼器私人資料對此作業無效。

HTTP 狀態碼：400

MissingCodecPrivateDataException

在視訊串流的至少一個軌道中找不到轉碼器私人資料。

HTTP 狀態碼：400

NoDataRetentionException

GetImages要求不保留資料的串流 (也就是說，a DataRetentionInHours 為 0)。

HTTP 狀態碼：400

NotAuthorizedException

狀態碼：403，調用者未授權在給定流上執行操作，或令牌已過期。

狀態碼：4

ResourceNotFoundException

GetImages當 Kinesis 影片串流找不到您指定的串流時，就會擲回此錯誤。

GetHLSStreamingSessionURL如果在請求的時間範圍內沒有片段PlaybackMode的流請求具有 ON_DEMAND or LIVE_REPLAY 的會話，或者如果在過去 30 秒內沒有片段PlaybackMode的LIVE流請求具有 a 的會話，則GetDASHStreamingSessionURL拋出此錯誤。

HTTP 狀態碼：404

UnsupportedStreamMediaTypeException

媒體類型 (例如 h.264 或 h.265 視訊或 AAC 或 G.711 音訊) 無法從播放工作階段的第一個片段中曲目的轉碼器識別碼來決定。音軌 1 的轉碼器 ID 應該是V_MPEG/ISO/AVC音軌 2 的編解碼器識別碼 (選擇性) A_AAC。

HTTP 狀態碼：400

另請參閱

如需在其中一個特定語言 AWS SDK 中使用此 API 的詳細資訊，請參閱下列內容：

• AWS 命令列介面

• AWS SDK for .NET

• AWS SDK for C++

• AWS 適用於轉到 V2 的 SDK

• AWS 適用於 Java V2 的 SDK

• AWS 適用於 JavaScript V3 的 SDK

• AWS SDK for PHP

• AWS 適用於 Python 的 SDK

• AWS 適用於紅寶石 V3 的 SDK