本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 上傳至 Kinesis Video Streams Amazon Kinesis Video Streams 生產者程式庫是 Kinesis Video Streams 生產者開發套件中的一組程式庫。用戶端使用 程式庫和 SDK 建置裝置內應用程式，以安全地連線至 Kinesis Video Streams，並串流媒體資料以在主控台或用戶端應用程式中即時檢視。 媒體資料可以依下列方式進行串流： + 即時 + 緩衝幾秒鐘後 + 媒體上傳之後 建立 Kinesis Video Streams 串流後，您可以開始將資料傳送至該串流。您可以使用 SDK 建立應用程式碼，從媒體來源擷取影片資料，稱為影格，並將其上傳至 Kinesis Video Streams。這些應用程式也稱為*生產者*應用程式。 生產者程式庫包含下列元件： + [Kinesis Video Streams 生產者用戶端](#producer-sdk-client) + [Kinesis Video Streams 生產者程式庫](#producer-sdk-library) ## Kinesis Video Streams 生產者用戶端 Kinesis Video Streams 生產者用戶端包含單一`KinesisVideoClient`類別。此類別會管理媒體來源、從來源接收資料，並在資料從媒體來源流向 Kinesis Video Streams 時管理串流生命週期。它還提供了一個`MediaSource`界面，用於定義 Kinesis Video Streams 與專屬硬體和軟體之間的互動。 媒體來源可以是任何項目。例如，您可以使用攝影機媒體來源或麥克風媒體來源。媒體來源不僅限於音訊和影片來源。例如，資料日誌可能是文字檔案，但它們依然可以做為資料串流來傳送。您也可以在電話上擁有多個攝影機，以便同時串接資料。 若要從這些資源取得資料，您可以實作 `MediaSource` 界面。此界面可啟用我們不提供內建支援的其他案例。例如，您可以選擇將下列項目傳送至 Kinesis Video Streams： + 診斷資料串流 (例如，應用程式日誌和事件) + 從紅外線攝影機、RADARs 或深度攝影機的資料 Kinesis Video Streams 不會為攝影機等產生媒體的裝置提供內建實作。若要從這些裝置擷取資料，您必須實作程式碼，藉此建立您自己的自訂媒體來源實作。然後，您可以使用 明確註冊自訂媒體來源`KinesisVideoClient`，將資料上傳至 Kinesis Video Streams。 Kinesis Video Streams 生產者用戶端適用於 Java 和 Android 應用程式。如需詳細資訊，請參閱[使用 Java 生產者程式庫](producer-sdk-javaapi.md)及[使用 Android 生產者程式庫](producer-sdk-android.md)。 ## Kinesis Video Streams 生產者程式庫 Kinesis Video Streams 生產者程式庫包含在 Kinesis Video Streams 生產者用戶端中。此程式庫也可供希望與 Kinesis Video Streams 更深入整合的使用者直接使用。它讓您可透過內含專屬的作業系統、網路堆疊，有限裝置內資源的裝置進行整合。 Kinesis Video Streams 生產者程式庫實作狀態機器，以串流至 Kinesis Video Streams。它提供回呼勾點，此需要您提供自己的傳輸實作和明確處理每則傳入和來自服務的訊息。 您可以選擇直接使用 Kinesis Video Streams 生產者程式庫，原因如下： + 您想要執行應用程式的裝置沒有 Java 虛擬機器。 + 您想以非 Java 語言編寫應用程式程式碼。 + 由於記憶體和處理能力等限制，您想要減少程式碼中的額外負荷，並將其限制為裸露的最低抽象層級。 目前，Kinesis Video Streams 生產者程式庫適用於 Android、C、C\$1\$1 和 Java 應用程式。如需詳細資訊，請參閱下列*相關主題*中支援的語言。 ## 了解什麼是生產者程式庫 [使用 Java 生產者程式庫](producer-sdk-javaapi.md) [使用 Android 生產者程式庫](producer-sdk-android.md) [使用 C\$1\$1 生產者程式庫](producer-sdk-cpp.md) [使用 C 生產者程式庫](producer-sdk-c-api.md) [在 Raspberry Pi 上使用 C\$1\$1 生產者 SDK](producersdk-cpp-rpi.md) # 使用 Java 生產者程式庫 您可以使用 Amazon Kinesis Video Streams 提供的 Java 生產者程式庫，以最少的組態撰寫應用程式碼，將媒體資料從裝置傳送至 Kinesis 影片串流。 執行下列步驟，將程式碼與 Kinesis Video Streams 整合，讓您的應用程式可以開始將資料串流至 Kinesis 影片串流： 1. 建立 `KinesisVideoClient` 物件的執行個體。 1. 透過提供媒體資源資訊建立 `MediaSource` 物件。例如，當建立攝影機媒體資源時，您提供如識別攝影機和指定攝影機所使用之編碼的資訊。 當您想要開始串流，您必須建立自訂媒體資源。 1. 使用 `KinesisVideoClient` 註冊媒體來源。 使用 `KinesisVideoClient` 註冊媒體來源後，每當媒體來源有可用的資料時，它會使用資料呼叫 `KinesisVideoClient`。 ## 程序：使用 Java 生產者 SDK 此程序示範如何在 Java 應用程式中使用 Kinesis Video Streams Java 生產者用戶端，將資料傳送至 Kinesis 影片串流。 這些步驟不會要求您擁有媒體來源 (例如相機或麥克風)。反之，為了進行測試，程式碼會產生由一系列位元組組成的範例影格。當您透過真實的來源 (例如相機和麥克風) 來傳送媒體資料時，您可以使用相同的編碼模式。 此程序包含以下步驟： + [下載並設定程式碼](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producersdk-javaapi-downloadcode.html) + [撰寫並檢查程式碼](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producersdk-javaapi-writecode.html) + [執行並驗證程式碼](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producersdk-javaapi-reviewcode.html) # 先決條件 在您設定 Java 生產者 SDK 之前，請確定您有下列先決條件： + 在範例程式碼中，您可以透過指定您在登入資料設定檔檔案中設定的設定檔來提供 AWS 登入資料。如果您尚未這麼做，請先設定您的登入資料設定檔。如需詳細資訊，請參閱《》中的[設定開發的 AWS 登入資料和區域](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html)*適用於 Java 的 AWS SDK*。 **注意** Java 範例使用 `SystemPropertiesCredentialsProvider` 物件來取得您的登入資料。供應商會從 `aws.accessKeyId` 和 `aws.secretKey` Java 系統屬性擷取這些登入資料。您在 Java 開發環境中設定這些系統屬性。如需有關如何設定 Java 系統屬性的詳細資訊，請參閱適用於您特定整合開發環境 (IDE) 的文件。 + 您 `NativeLibraryPath` 必須包含 `KinesisVideoProducerJNI` 檔案，其可在 [https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp) 取得。此檔案的副檔名取決於您的作業系統： + Linux 中為 **KinesisVideoProducerJNI.so** + macOS 中為 **KinesisVideoProducerJNI.dylib** + 適用於 Windows 的​ **KinesisVideoProducerJNI.dll** **注意** 預先建置的 macOS、Ubuntu、Windows 和 Raspbian 程式庫可在 `src/main/resources/lib`https：//[https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java.git](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java) 中取得。若是其他環境，則編譯 [C\$1\$1](producer-sdk-cpp.md)。 # 下載並設定 Java 生產者程式庫程式碼 在 Java 生產者程式庫程序的本節中，您可以下載 Java 範例程式碼、將專案匯入您的 Java IDE，以及設定程式庫位置。 如需此範例的先決條件和其他詳細資訊，請參閱[使用 Java 生產者程式庫](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk-javaapi.html)。 1. 建立目錄，然後從 GitHub 儲存庫複製範例原始碼。 ``` git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java ``` 1. 開啟您使用的 Java 整合開發環境 (IDE) (如 [Eclipse](https://www.eclipse.org/) 或 [JetBrains IntelliJ IDEA](https://www.jetbrains.com/idea/))，並匯入您下載的 Apache Maven 專案： + ** 在 IntelliJ IDEA：**選擇 **Import (匯入)**。巡覽至已下載套件根目錄的 `pom.xml` 檔案。 + **在 Eclipse 中：**選擇 **File (檔案)**、**Import (匯入)**、**Maven (Maven)**、**Existing Maven Projects (現有 Maven 專案)**。接著，前往 `kinesis-video-java-demo` 目錄。 如需更多詳細資訊，請參閱您的 IDE 文件。 1. Java 範例程式碼使用目前的 AWS 登入資料。若要使用不同的登入資料設定檔，請在 `DemoAppMain.java` 中尋找以下程式碼： ``` final KinesisVideoClient kinesisVideoClient = KinesisVideoJavaClientFactory .createKinesisVideoClient( Regions.US_WEST_2, AuthHelper.getSystemPropertiesCredentialsProvider()); ``` 將程式碼變更為下列內容： ``` final KinesisVideoClient kinesisVideoClient = KinesisVideoJavaClientFactory .createKinesisVideoClient( Regions.US_WEST_2, new ProfileCredentialsProvider("credentials-profile-name")); ``` 如需詳細資訊，請參閱 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/profile/ProfileCredentialsProvider.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/profile/ProfileCredentialsProvider.html)* 參考中的適用於 Java 的 AWS SDK ProfileCredentialsProvider*。 # 撰寫並檢查程式碼 在 [Java 生產者程式庫程序](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk-javaapi.html)的本節中，您會撰寫並檢查您在上一節中下載的 Java 範例程式碼。 Java 測試應用程式 ([https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java/blob/master/src/main/demo/com/amazonaws/kinesisvideo/demoapp/DemoAppMain.java](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java/blob/master/src/main/demo/com/amazonaws/kinesisvideo/demoapp/DemoAppMain.java)) 顯示以下編碼模式： + 建立 `KinesisVideoClient` 的執行個體。 + 建立 `MediaSource` 的執行個體。 + 使用用戶端註冊 `MediaSource`。 + 開始串流。啟動 ，`MediaSource`然後開始將資料傳送至用戶端。 下列各節將詳細說明。 ## 建立 KinesisVideoClient 的執行個體 您呼叫 `createKinesisVideoClient` 操作建立 `KinesisVideoClient` 物件。 ``` final KinesisVideoClient kinesisVideoClient = KinesisVideoJavaClientFactory .createKinesisVideoClient( Regions.US_WEST_2, AuthHelper.getSystemPropertiesCredentialsProvider()); ``` 如果要讓 `KinesisVideoClient` 進行網路呼叫，需要可驗證的登入資料。您會傳遞 `SystemPropertiesCredentialsProvider` 執行個體，其會針對登入資料檔案中的預設設定檔讀取 `AWSCredentials`： ``` [default] aws_access_key_id = ABCDEFGHIJKLMOPQRSTU aws_secret_access_key = AbCd1234EfGh5678IjKl9012MnOp3456QrSt7890 ``` ## 建立 MediaSource 執行個體 若要將位元組傳送至 Kinesis 影片串流，您必須產生資料。Amazon Kinesis Video Streams 提供 `MediaSource`界面，代表資料來源。 例如，Kinesis Video Streams Java 程式庫提供 `MediaSource` 介面的`ImageFileMediaSource`實作。此類別只會從一系列媒體檔案讀取資料，而不是 Kinesis 影片串流，但您可以使用它來測試程式碼。 ``` final MediaSource bytesMediaSource = createImageFileMediaSource(); ``` ## 向用戶端註冊 MediaSource 註冊您使用 `KinesisVideoClient` 所建立的媒體來源，系統就會知道該用戶端 (並可將資料傳送到用戶端)。 ``` kinesisVideoClient.registerMediaSource(mediaSource); ``` ## 啟動媒體來源 啟動媒體來源，使其可以開始產生資料並將其傳送至用戶端。 ``` bytesMediaSource.start(); ``` # 清除資源 為了避免記憶體洩漏，請執行下列動作從用戶端取消註冊媒體來源，並釋放用戶端。 ``` try { kinesisVideoClient.unregisterMediaSource(mediaSource); kinesisVideoClient.free(); } catch (final KinesisVideoException e) { throw new RuntimeException(e); } ``` 如果您使用 將任何項目新增至快取[https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java/blob/master/src/main/java/com/amazonaws/kinesisvideo/java/service/CachedInfoMultiAuthServiceCallbacksImpl.java](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java/blob/master/src/main/java/com/amazonaws/kinesisvideo/java/service/CachedInfoMultiAuthServiceCallbacksImpl.java)，例如： ``` serviceCallbacks.addStreamInfoToCache(streamName, streamInfo); serviceCallbacks.addStreamingEndpointToCache(streamName, dataEndpoint); ``` 完成時清除快取： ``` serviceCallbacks.removeStreamFromCache(streamName); ``` # 執行並驗證程式碼 若要執行 Java [生產者程式庫的 Java](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk-javaapi.html) 測試機制，請執行下列動作。 1. 選擇 **DemoAppMain**。 1. 選擇 **Run (執行)**、**Run 'DemoAppMain (執行「DemoAppMain」)**。 1. 將您的登入資料新增至應用程式的 JVM 引數： + **對於非暫時 AWS 登入資料：** `"-Daws.accessKeyId={YourAwsAccessKey} -Daws.secretKey={YourAwsSecretKey} -Djava.library.path={NativeLibraryPath}"` + **對於臨時 AWS 登入資料：** `"-Daws.accessKeyId={YourAwsAccessKey} -Daws.secretKey={YourAwsSecretKey} -Daws.sessionToken={YourAwsSessionToken} -Djava.library.path={NativeLibraryPath}" ` 1. 登入 AWS 管理主控台 並開啟 [Kinesis Video Streams 主控台](https://console.aws.amazon.com//kinesisvideo/home/)。 在 **Manage Streams (管理串流)** 頁面中，選擇您的串流。 1. 範例影片會在嵌入式播放器中播放。在出現視訊之前，您可能需要稍微等待畫面聚積 (在一般性頻寬和處理器的條件下最多 10 秒)。 建立串流的程式碼範例。當程式碼中的 `MediaSource` 開啟時，會開始將範例影格傳送到 `KinesisVideoClient`。然後，用戶端會將資料傳送至您的 Kinesis 影片串流。 # 使用 Android 生產者程式庫 您可以使用 Amazon Kinesis Video Streams 提供的 Android 生產者程式庫，以最少的組態撰寫應用程式程式碼，將媒體資料從 Android 裝置傳送至 Kinesis 影片串流。 執行下列步驟，將程式碼與 Kinesis Video Streams 整合，讓您的應用程式可以開始將資料串流至 Kinesis 影片串流： 1. 建立 `KinesisVideoClient` 物件的執行個體。 1. 透過提供媒體資源資訊建立 `MediaSource` 物件。例如，當建立攝影機媒體資源時，您提供如識別攝影機和指定攝影機所使用之編碼的資訊。 當您想要開始串流，您必須建立自訂媒體資源。 ## 程序：使用 Android 生產者 SDK 此程序示範如何在 Android 應用程式中使用 Kinesis Video Streams Android 生產者用戶端，將資料傳送至 Kinesis 影片串流。 此程序包含以下步驟： + [先決條件](producersdk-android-prerequisites.md) + [下載並設定 Android 生產者程式庫程式碼](producersdk-android-downloadcode.md) + [檢查程式碼](producersdk-android-writecode.md) + [執行並驗證程式碼](producersdk-android-reviewcode.md) # 先決條件 建議使用 [Android Studio](https://developer.android.com/studio/index.html) 檢查、編輯和執行應用程式的程式碼。建議使用最新的穩定版本。 在範本程式碼中，您會提供 Amazon Cognito 登入資料。 **Topics** + [設定使用者集區](#set-up-user-pool) + [設定身分集區](#set-up-identity-pool) ## 設定使用者集區 **設定使用者集區** 1. 登入 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)並確認區域正確無誤。 1. 在左側導覽中，選擇**使用者集區**。 1. 在**使用者集**區區段中，選擇**建立使用者集區**。 1. 完成下列各節： 1. **步驟 1：設定登入體驗** - 在 **Cognito 使用者集區登入選項**區段中，選取適當的選項。 選取**下一步**。 1. **步驟 2：設定安全需求** - 選取適當的選項。 選取**下一步**。 1. **步驟 3：設定註冊體驗** - 選取適當的選項。 選取**下一步**。 1. **步驟 4：設定訊息傳遞** - 選取適當的選項。 在 **IAM 角色選取**欄位中，選取現有角色或建立新的角色。 選取**下一步**。 1. **步驟 5：整合您的應用程式** - 選取適當的選項。 在**初始應用程式用戶端**欄位中，選擇**機密用戶端**。 選取**下一步**。 1. **步驟 6：檢閱並建立** - 檢閱先前區段的選擇，然後選擇**建立使用者集區**。 1. 在**使用者集**區頁面上，選取您剛建立的集區。 複製**使用者集區 ID**，並記下此 ID 以供稍後使用。在 `awsconfiguration.json`檔案中，這是 `CognitoUserPool.Default.PoolId`。 1. 選取**應用程式整合**索引標籤，然後移至頁面底部。 1. 在**應用程式用戶端清單**區段中，選擇您剛建立**的應用程式用戶端名稱**。 複製**用戶端 ID** 並記下此 ID 以供稍後使用。在 `awsconfiguration.json`檔案中，這是 `CognitoUserPool.Default.AppClientId`。 1. 顯示**用戶端秘密**，並記下此秘密以供稍後使用。在 `awsconfiguration.json`檔案中，這是 `CognitoUserPool.Default.AppClientSecret`。 ## 設定身分集區 **設定身分集區** 1. 登入 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)並確認區域正確無誤。 1. 在左側導覽中，選擇**身分集區**。 1. 選擇 **建立身分池**。 1. 設定身分集區。 1. **步驟 1：設定身分集區信任** - 完成下列區段： + **使用者存取** - 選取**已驗證的存取** + **已驗證的身分來源** - 選取 **Amazon Cognito 使用者集區** 選取**下一步**。 1. **步驟 2：設定許可** - 在**已驗證角色**區段中，完成下列欄位： + **IAM 角色** - 選取**建立新的 IAM 角色** + **IAM 角色名稱** - 輸入名稱並將其記下以供後續步驟使用。 選取**下一步**。 1. **步驟 3：連接身分提供者** - 在**使用者集區詳細資訊**區段中，完成下列欄位： + **使用者集區 ID** - 選取您先前建立的使用者集區。 + **應用程式用戶端 ID** - 選取您先前建立的應用程式用戶端 ID。 選取**下一步**。 1. **步驟 4：設定屬性** - 在**身分集區名稱欄位中輸入名稱**。 選取**下一步**。 1. **步驟 5：檢閱並建立** - 檢閱每個區段中的選擇，然後選取**建立身分集區**。 1. 在**身分集**區頁面上，選取新的身分集區。 複製**身分集區 ID**，並記下此 ID 以供稍後使用。在 `awsconfiguration.json`檔案中，這是 `CredentialsProvider.CognitoIdentity.Default.PoolId`。 1. 更新 IAM 角色的許可。 1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。 1. 在左側導覽中，選擇**角色**。 1. 尋找並選取您在上面建立的角色。 **注意** 如有需要，請使用搜尋列。 1. 選取連接的許可政策。 選擇 **Edit** (編輯)。 1. 選取 **JSON** 索引標籤，並以下列內容取代政策： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cognito-identity:*", "kinesisvideo:*" ], "Resource": [ "*" ] } ] } ``` ------ 選取**下一步**。 1. 如果尚未選取，請選取**此新版本設定為預設值**旁的方塊。 選取**儲存變更**。 # 下載並設定 Android 生產者程式庫程式碼 在 Android 生產者程式庫程序的本節中，您可以下載 Android 範例程式碼，並在 Android Studio 中開啟專案。 如需此範例的先決條件和其他詳細資訊，請參閱[使用 Android 生產者程式庫](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk-android.html)。 1. 建立目錄，然後從 GitHub 適用於 Android 的 AWS Mobile SDK 儲存庫複製 。 ``` git clone https://github.com/awslabs/aws-sdk-android-samples ``` 1. 開啟 [Android Studio](https://developer.android.com/studio/index.html)。 1. 在開啟畫面中，選擇 **Open an existing Android Studio project** (開放現有的 Android Studio 專案)。 1. 導覽至 `aws-sdk-android-samples/AmazonKinesisVideoDemoApp` 目錄，並選擇 **OK (確定)**。 1. 開啟 `AmazonKinesisVideoDemoApp/src/main/res/raw/awsconfiguration.json` 檔案。 在`CredentialsProvider`節點中，提供來自[先決條件](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk-android.html#producersdk-android-prerequisites)區段中**設定身分集區程序的身分集**區 ID，並提供您的 AWS 區域 （例如，**us-west-2**)。 在`CognitoUserPool`節點中，提供來自[先決條件](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk-android.html#producersdk-android-prerequisites)區段中**設定使用者集區程序的應用程式用戶端秘密、應用程式用戶端 ID 和集區** ID，並提供您的 AWS 區域 （例如，**us-west-2**)。 1. 您的 `awsconfiguration.json` 檔案看起來如下： ``` { "Version": "1.0", "CredentialsProvider": { "CognitoIdentity": { "Default": { "PoolId": "us-west-2:01234567-89ab-cdef-0123-456789abcdef", "Region": "us-west-2" } } }, "IdentityManager": { "Default": {} }, "CognitoUserPool": { "Default": { "AppClientSecret": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmno", "AppClientId": "0123456789abcdefghijklmnop", "PoolId": "us-west-2_qRsTuVwXy", "Region": "us-west-2" } } } ``` 1. 將 更新`AmazonKinesisVideoDemoApp/src/main/java/com/amazonaws/kinesisvideo/demoapp/KinesisVideoDemoApp.java`為您的 區域 （在下列範例中，設定為 **US\$1WEST\$12**)： ``` public class KinesisVideoDemoApp extends Application { public static final String TAG = KinesisVideoDemoApp.class.getSimpleName(); public static Regions KINESIS_VIDEO_REGION = Regions.US_WEST_2; ``` 如需 AWS 區域 常數的資訊，請參閱 [區域](https://aws-amplify.github.io/aws-sdk-android/docs/reference/com/amazonaws/regions/Regions.html)。 # 檢查程式碼 在 [Android 生產者程式庫程序](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk-android.html)的本節中，您會檢查範例程式碼。 Android 測試應用程式 (`AmazonKinesisVideoDemoApp`) 顯示以下編碼模式： + 建立 `KinesisVideoClient` 的執行個體。 + 建立 `MediaSource` 的執行個體。 + 開始串流。啟動 `MediaSource`，並開始將資料傳送至用戶端。 下列各節將詳細說明。 ## 建立 KinesisVideoClient 的執行個體 您呼叫 `[createKinesisVideoClient](https://github.com/aws-amplify/aws-sdk-android/blob/main/aws-android-sdk-kinesisvideo/src/main/java/com/amazonaws/mobileconnectors/kinesisvideo/client/KinesisVideoAndroidClientFactory.java)` 操作建立 `[KinesisVideoClient](https://github.com/aws-amplify/aws-sdk-android/blob/main/aws-android-sdk-kinesisvideo/src/main/java/com/amazonaws/kinesisvideo/client/KinesisVideoClient.java)` 物件。 ``` mKinesisVideoClient = KinesisVideoAndroidClientFactory.createKinesisVideoClient( getActivity(), KinesisVideoDemoApp.KINESIS_VIDEO_REGION, KinesisVideoDemoApp.getCredentialsProvider()); ``` 如果要讓 `KinesisVideoClient` 進行網路呼叫，需要可驗證的登入資料。您會傳入 執行個體`AWSCredentialsProvider`，該執行個體會從您在上一節修改`awsconfiguration.json`的檔案讀取 Amazon Cognito 登入資料。 ## 建立 MediaSource 執行個體 若要將位元組傳送至 Kinesis 影片串流，您必須產生資料。Amazon Kinesis Video Streams 提供 `[MediaSource](https://github.com/aws-amplify/aws-sdk-android/blob/main/aws-android-sdk-kinesisvideo/src/main/java/com/amazonaws/kinesisvideo/internal/client/mediasource/MediaSource.java)`界面，代表資料來源。 例如，Kinesis Video Streams Android 程式庫提供 `MediaSource` 介面的`[AndroidCameraMediaSource](https://github.com/aws-amplify/aws-sdk-android/blob/main/aws-android-sdk-kinesisvideo/src/main/java/com/amazonaws/mobileconnectors/kinesisvideo/mediasource/android/AndroidCameraMediaSource.java)`實作。此類別讀取其中一個裝置攝影機的資料。 在以下程式碼範例 (來自 `[fragment/StreamConfigurationFragment.java](https://github.com/awslabs/aws-sdk-android-samples/blob/main/AmazonKinesisVideoDemoApp/src/main/java/com/amazonaws/kinesisvideo/demoapp/fragment/StreamConfigurationFragment.java)` 檔案) 中，將建立媒體資源的組態： ``` private AndroidCameraMediaSourceConfiguration getCurrentConfiguration() { return new AndroidCameraMediaSourceConfiguration( AndroidCameraMediaSourceConfiguration.builder() .withCameraId(mCamerasDropdown.getSelectedItem().getCameraId()) .withEncodingMimeType(mMimeTypeDropdown.getSelectedItem().getMimeType()) .withHorizontalResolution(mResolutionDropdown.getSelectedItem().getWidth()) .withVerticalResolution(mResolutionDropdown.getSelectedItem().getHeight()) .withCameraFacing(mCamerasDropdown.getSelectedItem().getCameraFacing()) .withIsEncoderHardwareAccelerated( mCamerasDropdown.getSelectedItem().isEndcoderHardwareAccelerated()) .withFrameRate(FRAMERATE_20) .withRetentionPeriodInHours(RETENTION_PERIOD_48_HOURS) .withEncodingBitRate(BITRATE_384_KBPS) .withCameraOrientation(-mCamerasDropdown.getSelectedItem().getCameraOrientation()) .withNalAdaptationFlags(StreamInfo.NalAdaptationFlags.NAL_ADAPTATION_ANNEXB_CPD_AND_FRAME_NALS) .withIsAbsoluteTimecode(false)); } ``` 在以下程式碼範例 (來自 `[fragment/StreamingFragment.java](https://github.com/awslabs/aws-sdk-android-samples/blob/main/AmazonKinesisVideoDemoApp/src/main/java/com/amazonaws/kinesisvideo/demoapp/fragment/StreamingFragment.java)` 檔案) 中，將建立媒體資源： ``` mCameraMediaSource = (AndroidCameraMediaSource) mKinesisVideoClient .createMediaSource(mStreamName, mConfiguration); ``` ## 啟動媒體來源 開啟媒體來源，以開始產生資料並傳送到用戶端。以下是來自 `[fragment/StreamingFragment.java](https://github.com/awslabs/aws-sdk-android-samples/blob/main/AmazonKinesisVideoDemoApp/src/main/java/com/amazonaws/kinesisvideo/demoapp/fragment/StreamingFragment.java)` 檔案的程式碼範例： ``` mCameraMediaSource.start(); ``` # 執行並驗證程式碼 若要執行 Android [生產者程式庫的 Android](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk-android.html) 範例應用程式，請執行下列動作。 1. 連接 Android 裝置。 1. 選擇 **Run (執行)**、**Run... (執行...)**，然後選擇 **Edit configurations... (編輯組態...)**。 1. 選擇加號圖示 (**\$1**)、**Android 應用程式**。在 **Name (名稱)** 欄位中，輸入 **AmazonKinesisVideoDemoApp**。在 **Module (模組)** 下拉式選單中，選擇 **AmazonKinesisVideoDemoApp**。選擇**確定**。 1. 選擇 **Run (執行)**、**Run (執行)**。 1. 在 **Select Deployment Target (選取部署目標)** 畫面中，選擇您的連線裝置，然後選擇 **OK (確定)**。 1. 在裝置上的 **AWSKinesisVideoDemoApp** 應用程式中，選擇 **Create new account (建立新帳戶)**。 1. 輸入 **USERNAME (使用者名稱)**、**Password (密碼)**，**Given name (名字)**、**Email address (電子郵件地址)** 和 **Phone number (電話號碼)** 的值，然後選擇 **Sign up (註冊)**。 **注意** 這些值有下列限制： **密碼：**必須包含大小寫字母、數字和特殊字元。您可以在 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)的使用者集區頁面中變更這些限制條件。 **電子郵件地址：**必須為有效的地址，讓您可以收到確認代碼。 **電話號碼：**格式須如下：**\$1******，例如，**\$112065551212**。 1. 輸入您透過電子郵件收到的代碼，然後選擇**確認**。選擇**確定**。 1. 在下一頁中，保留預設值，然後選擇**串流**。 1. 登入 AWS 管理主控台 ，並在美國西部 （奧勒岡） 區域開啟 [Kinesis Video Streams 主控台](https://console.aws.amazon.com//kinesisvideo/home/)。 在 **Manage Streams** (管理串流) 頁面中，選擇 **demo-stream** (示範串流)。 1. 串流視訊在內建播放器中播放。在出現視訊之前，您可能需要稍微等待畫面聚積 (在一般性頻寬和處理器的條件下最多 10 秒)。 **注意** 如果裝置的畫面旋轉 (例如，從縱向到橫向)，應用程式會停止串流視訊。 建立串流的程式碼範例。當程式碼中的 `MediaSource` 開啟時，會開始將攝影機的畫面傳送到 `KinesisVideoClient`。用戶端接著會將資料傳送至名為**示範串流的 Kinesis 影片串流**。 # 使用 C\$1\$1 生產者程式庫 您可以使用 Amazon Kinesis Video Streams 提供的 C\$1\$1 生產者程式庫撰寫應用程式程式碼，將媒體資料從裝置傳送至 Kinesis 影片串流。 ## 物件模型 C\$1\$1 程式庫提供下列物件來管理將資料傳送至 Kinesis 影片串流： + **KinesisVideoProducer：**包含媒體來源和 AWS 登入資料的相關資訊，並維護回呼以報告 Kinesis Video Streams 事件。 + **KinesisVideoStream：**代表 Kinesis 影片串流。包含視訊串流參數的相關資訊，例如名稱、資料保留期和媒體內容類型。 ## 將媒體放入串流 您可以使用 C\$1\$1 程式庫提供的方法 （例如 `PutFrame`) 將資料放入`KinesisVideoStream`物件。然後程式庫會管理資料的內部狀態，包括以下任務： + 執行身分驗證。 + 查看網路延遲。如果延遲太高，程式庫可能選擇減少影格數。 + 追蹤進行中串流的狀態。 ## 回呼介面 此層公開一組回呼界面，使其能與應用程式層溝通。這些回呼界面包含以下項目： + **服務回呼界面 (`CallbackProvider`)：**程式庫會在建立串流、取得串流描述，以及刪除串流時，叫用透過此界面取得的事件。 + **用戶端就緒狀態或低儲存事件界面 (`ClientCallbackProvider`)：**當用戶端就緒，或偵測到其可能耗盡可用儲存體或記憶體時，程式庫會在此界面上叫用事件。 + **串流事件回呼界面 (`StreamCallbackProvider`)：**當串流事件發生時，程式庫會在此界面上叫用事件，例如進入就緒狀態的串流、捨棄影格或串流錯誤。 Kinesis Video Streams 提供這些介面的預設實作。您也可以提供自己的自訂實作，例如，如果您需要自訂聯網邏輯，或想要向使用者介面公開低儲存條件。 如需生產者程式庫中回呼的詳細資訊，請參閱 [生產者開發套件回呼](producer-reference-callbacks.md)。 ## 程序：使用 C\$1\$1 生產者 SDK 此程序示範如何在 C\$1\$1 應用程式中使用 Kinesis Video Streams 用戶端和媒體來源，將資料傳送至 Kinesis 影片串流。 此程序包含以下步驟： **Topics** # 先決條件 在您設定 C\$1\$1 生產者 SDK 之前，請確定您有下列先決條件： + **登入資料：**在範例程式碼中，您可以透過指定您在登入資料設定檔檔案中設定的 AWS 設定檔來提供登入資料。如果您尚未這麼做，請先設定您的登入資料設定檔。 如需詳細資訊，請參閱[設定用於開發的 AWS 登入資料和區域](https://docs.aws.amazon.com//sdk-for-java/v1/developer-guide/setup-credentials.html)。 + **憑證存放區整合：**Kinesis Video Streams 生產者程式庫必須與呼叫的服務建立信任。這是透過驗證公有憑證存放區中的憑證授權單位 (CAs) 來完成。在以 Linux 為基礎的模型中，此存放位於 `/etc/ssl`/ 目錄。 將下列位置的憑證下載到您的憑證存放區： [https://www.amazontrust.com/repository/SFSRootCAG2.pem](https://www.amazontrust.com/repository/SFSRootCAG2.pem) + 安裝下列適用於 macOS 的建構相依性： + [Autoconf 2.69](http://www.gnu.org/software/autoconf/autoconf.html) (授權 GPLv3\$1/Autoconf：GNU GPL 第 3 版或更新版本) + [CMake 3.7 或 3.8](https://cmake.org/) + [Pkg-Config](https://www.freedesktop.org/wiki/Software/pkg-config/) + xCode (macOS)/clang/gcc (xcode-select 2347 版) + Java 開發套件 (JDK) (適用於 Java JNI 編譯) + [Lib-Pkg](https://github.com/freebsd/pkg/tree/master/libpkg) + 安裝下列 Ubuntu 的建置相依性： + Git： `sudo apt install git` + [CMake：](http://kitware.com/cmake)`sudo apt install cmake` + G\$1\$1： `sudo apt install g++` + pkg-config： `sudo apt install pkg-config` + OpenJDK： `sudo apt install openjdk-8-jdk` **注意** 只有在您要建置 Java 原生界面 (JNI) 時，才需要此操作。 + 設定 `JAVA_HOME` 環境變數：`export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/` # 下載並設定 C\$1\$1 生產者程式庫程式碼 如需如何下載和設定 C\$1\$1 生產者程式庫的資訊，請參閱 [Amazon Kinesis Video Streams CPP Producer、GStreamer Plugin 和 JNI](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp)。 如需此範例的先決條件和詳細資訊，請參閱 [使用 C\$1\$1 生產者程式庫](producer-sdk-cpp.md)。 ## CMake 引數 以下是 C\$1\$1 Producer SDK 特定 CMake 引數的參考表。您也可以將[標準 CMake 選項](https://cmake.org/cmake/help/latest/manual/cmake-env-variables.7.html)傳遞給 CMake。 **重要** 這些都是選用的。 **包含或排除特定功能的旗標** | CMake 引數 | Type | 預設 | 說明 | | --- | --- | --- | --- | | `BUILD_DEPENDENCIES` | Boolean | ON | 從來源建置相依性。否則，請使用已安裝在系統上的相依性。如果找不到其中一個必要的相依性，則會傳回錯誤。 | | `BUILD_GSTREAMER_PLUGIN` | Boolean | OFF | 建置 kvssink GStreamer 外掛程式。 | | `BUILD_JNI` | Boolean | OFF | 建置 Java 原生界面 (JNI)，以便能夠從 Java 執行時間環境呼叫此程式碼。 | | `ALIGNED_MEMORY_MODEL` | Boolean | OFF | 如果記憶體配置應對齊 8 位元組邊界。有些架構不允許未對齊的記憶體存取。 | | `CONSTRAINED_DEVICE` | Boolean | OFF | 僅限非 Windows。開啟時， 會將執行緒堆疊大小設定為 0.5 MiB。[Alpine Linux](https://wiki.alpinelinux.org/wiki/Main_Page) 組建需要。否則，會使用作業系統預設值。 | | `BUILD_STATIC` | Boolean | OFF | 將程式庫和可執行檔建置為[共用](https://en.wikipedia.org/wiki/Shared_library) (OFF) 或[靜態](https://en.wikipedia.org/wiki/Static_library) (ON)。 | | `ADD_MUCLIBC` | Boolean | OFF | 連結至 [uClibc](https://en.wikipedia.org/wiki/UClibc) 而非標準 C 程式庫，這是專為嵌入式系統設計的小型 C 標準程式庫。 | | `OPEN_SRC_INSTALL_PREFIX` | String | ../open-source/local | 如果從來源建置，安裝開放原始碼相依性的位置。 | **跨編譯的旗標** **重要** 如果您的目標和主機機器 CPU 架構不同，請設定這些架構。 | CMake 引數 | Type | 預設 | 說明 | | --- | --- | --- | --- | | `BUILD_LOG4CPLUS_HOST` | String | "" | 為指定的 CPU 架構建置log4cplus相依性。如果未設定， log4cplus會自動偵測並使用主機機器的 CPU 架構。 | | `BUILD_OPENSSL_PLATFORM` | String | "" | 為指定的 CPU 架構建置OpenSSL相依性。如果未設定， OpenSSL會自動偵測並使用主機機器的 CPU 架構。 | **與測試相關的旗標** | CMake 引數 | Type | 預設 | 說明 | | --- | --- | --- | --- | | `BUILD_TEST` | Boolean | OFF | 建置單元和整合測試。若要執行所有測試，./tst/producerTest請從建置目錄執行 。 AWS 需要登入資料才能執行測試。 | | `CODE_COVERAGE` | Boolean | OFF | 僅適用於 GNU/Clang 編譯器。使用 [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) 和產生報告來啟用程式碼涵蓋範圍集合。 | | `COMPILER_WARNINGS` | Boolean | OFF | 僅適用於 GNU/Clang 編譯器。啟用所有編譯器警告。 | | `ADDRESS_SANITIZER` | Boolean | OFF | 僅適用於 GNU/Clang 編譯器。使用 [AddressSanitizer](https://compiler-rt.llvm.org/) 建置 。 | | `MEMORY_SANITIZER` | Boolean | OFF | 僅適用於 GNU/Clang 編譯器。使用 [MemorySanitizer](https://compiler-rt.llvm.org/) 建置 。 | | `THREAD_SANITIZER` | Boolean | OFF | 僅適用於 GNU/Clang 編譯器。使用 [ThreadSanitizer](https://compiler-rt.llvm.org/) 建置 。 | | `UNDEFINED_BEHAVIOR_SANITIZER` | Boolean | OFF | 僅適用於 GNU/Clang 編譯器。使用 [UndefinedBehaviorSanitizer](https://compiler-rt.llvm.org/) 建置 。 | 若要使用這些 CMake 引數，請依照 `cmake ..`命令以空格分隔的`-Dkey=value`配對清單傳遞這些引數。例如： ``` cmake .. -DBUILD_GSTREAMER_PLUGIN=ON -DBUILD_DEPENDENCIES=OFF -DALIGNED_MEMORY_MODEL=ON ``` CMake 會遵循 `$PATH`變數尋找編譯器工具鏈。在執行 CMake 之前，請設定 `CC`和 `CXX`環境變數，以明確設定用於跨編譯的工具鏈。 # 撰寫並檢查程式碼 在 的本節中[使用 C\$1\$1 生產者程式庫](producer-sdk-cpp.md)，您會檢查 C\$1\$1 測試工具組中的程式碼 (`tst/ProducerTestFixture.h` 和其他 檔案）。您在上一節中下載了此程式碼。 **平台獨立** C\$1\$1 範例顯示下列編碼模式： + 建立 執行個體`KinesisVideoProducer`以存取 Kinesis Video Streams。 + 建立 `KinesisVideoStream` 的執行個體。 AWS 帳戶 如果相同名稱的串流尚未存在，這會在 中建立 Kinesis 影片串流。 + 當可用時，在 `KinesisVideoStream` 上呼叫每個資料畫面的 `putFrame`，將其傳送到串流。 下列各節提供有關此編碼模式的詳細資訊。 ## 建立 KinesisVideoProducer 的執行個體 您呼叫 `KinesisVideoProducer` 方法建立 `KinesisVideoProducer::createSync` 物件。下列範例在 `KinesisVideoProducer` 檔案中建立 `ProducerTestFixture.h`： ``` kinesis_video_producer_ = KinesisVideoProducer::createSync(move(device_provider_), move(client_callback_provider_), move(stream_callback_provider_), move(credential_provider_), defaultRegion_); ``` `createSync` 方法會使用下列三個參數： + `DeviceInfoProvider` 物件，其會傳回包含裝置或存放區組態相關資訊的 `DeviceInfo` 物件。 **注意** 您使用 `deviceInfo.storageInfo.storageSize` 參數設定內容存放區大小。您的內容串流會共用內容存放區。若要判斷您的儲存大小需求，請將平均畫面大小乘以為所有串流最大持續時間存放的畫面數量，再乘以 1.2 以計算磁碟重組。例如，假設您的應用程式具有以下組態： 三個串流 最大持續時間 3 分鐘 每個串流為每秒 30 個影格 (FPS) 每個畫面大小為 10,000 KB 此應用程式的內容存放區需求為 **3 （串流） \$1 3 （分鐘） \$1 60 （分鐘內秒） \$1 10000 (kb) \$1 1.2 （重組額度） = 194.4 Mb \$1 200 Mb。** + `ClientCallbackProvider` 物件，其會傳回報告用戶端特定事件的函數指標。 + `StreamCallbackProvider` 物件，其會傳回串流特定事件發生後收回的函數指標。 + `CredentialProvider` 物件，可讓您存取 AWS 登入資料環境變數。 + The AWS 區域 ("us-west-2")。服務端點取決於區域。 ## 建立 KinesisVideoStream 的執行個體 您呼叫使用 `StreamDefinition` 參數的 `KinesisVideoProducer::CreateStream` 方法建立 `KinesisVideoStream` 物件。該範例會在 `ProducerTestFixture.h` 檔案中建立 `KinesisVideoStream`，並將軌道類型設為視訊，軌道 ID 設為 1： ``` auto stream_definition = make_unique(stream_name, hours(2), tags, "", STREAMING_TYPE_REALTIME, "video/h264", milliseconds::zero(), seconds(2), milliseconds(1), true, true, true); return kinesis_video_producer_->createStream(move(stream_definition)); ``` `StreamDefinition` 物件包含以下欄位： + 串流名稱。 + 資料保留期間。 + 標籤的串流。這些標籤可供消費者應用程式用於尋找正確的串流，或是取得更多關於串流的資訊。​也可以在 AWS 管理主控台​ 查看這些標籤。 + AWS KMS 串流的加密金鑰。如需詳細資訊，請參閱[Kinesis Video Streams 中的資料保護](how-kms.md)。 + 串流類型。目前唯一有效的值為：`STREAMING_TYPE_REALTIME`。 + 媒體內容類型。 + 媒體延遲。此值目前未使用，且應設為 0。 + 每個片段的播放持續時間。 + 媒體時間碼擴展。 + 媒體是否使用關鍵影格片段。 + 媒體是否使用時間碼。 + 媒體是否使用絕對片段時間。 ## 將音軌新增至 Kinesis 影片串流 您可以使用 的 `addTrack`方法，將音訊軌詳細資訊新增至視訊軌串流定義`StreamDefinition`： ``` stream_definition->addTrack(DEFAULT_AUDIO_TRACKID, DEFAULT_AUDIO_TRACK_NAME, DEFAULT_AUDIO_CODEC_ID, MKV_TRACK_INFO_TYPE_AUDIO); ``` `addTrack` 方法需要下列參數： + 音軌 ID （做為音訊的 ID)。這應該是唯一且非零的數值。 + 使用者定義的音軌名稱 （例如，音訊音軌的「音訊」)。 + 此音軌的轉碼器 ID （例如，音訊音軌 "A\$1AAC")。 + 音軌類型 （例如，將 MKV\$1TRACK\$1INFO\$1TYPE\$1AUDIO 的列舉值用於音訊）。 如果您有音軌的轉碼器私有資料，則可以在呼叫 addTrack 函數時傳遞。您也可以在建立 KinesisVideoStream 物件之後傳送轉碼器建立私有資料，同時在 KinesisVideoStream 中呼叫開始方法。 ## 將影格放入 Kinesis 影片串流 您可以使用 將媒體放入 Kinesis 影片串流`KinesisVideoStream::putFrame`，並傳入包含 標頭和媒體資料的`Frame`物件。此範例呼叫 `ProducerApiTest.cpp` 檔案中的 `putFrame`： ``` frame.duration = FRAME_DURATION_IN_MICROS * HUNDREDS_OF_NANOS_IN_A_MICROSECOND; frame.size = SIZEOF(frameBuffer_); frame.frameData = frameBuffer_; MEMSET(frame.frameData, 0x55, frame.size); while (!stop_producer_) { // Produce frames timestamp = std::chrono::duration_cast( std::chrono::system_clock::now().time_since_epoch()).count() / DEFAULT_TIME_UNIT_IN_NANOS; frame.index = index++; frame.decodingTs = timestamp; frame.presentationTs = timestamp; // Key frame every 50th frame.flags = (frame.index % 50 == 0) ? FRAME_FLAG_KEY_FRAME : FRAME_FLAG_NONE; ... EXPECT_TRUE(kinesis_video_stream->putFrame(frame)); ``` **注意** 上述 C\$1\$1 生產者範例會傳送測試資料的緩衝區。在實際的應用程式中，您應該從媒體資源 (例如攝影機) 獲得畫面資料的畫面緩衝和大小。 `Frame` 物件包含以下欄位： + 畫面索引。此應為單一遞增的值。 + 與畫面關聯的旗標。例如，如果設定編碼器產生關鍵影格，將會指定 `FRAME_FLAG_KEY_FRAME` 旗標給此畫面。 + 解碼時間戳記。 + 簡報時間戳記。 + 畫面的持續時間 (到 100 ns 單位)。 + 畫面的大小 (位元組)。 + 畫面資料。 如需影格格式的詳細資訊，請參閱 [Kinesis Video Streams 資料模型](how-data.md)。 ## 將 KinesisVideoFrame 放入 KinesisVideoStream 的特定軌道 您可以使用 `PutFrameHelper`類別將影格資料放入特定軌道。首先，呼叫 `getFrameDataBuffer`以取得其中一個預先配置緩衝區的指標，以填入`KinesisVideoFrame`資料。然後，您可以呼叫 `putFrameMultiTrack`來傳送 `KinesisVideoFrame`以及布林值，以指出影格資料類型。如果是視訊資料，使用 true，或者，如果影格包含音訊資料，則使用 false。此`putFrameMultiTrack`方法使用佇列機制，以確保 MKV 片段維持單調增加的影格時間戳記，且任兩個片段都不會重疊。例如，片段第一個影格的 MKV 時間戳記應一律大於先前片段最後一個影格的 MKV 時間戳記。 `PutFrameHelper` 具有下列欄位： + 佇列中的音訊影格數目上限。 + 佇列中的影片影格數目上限。 + 為單一音訊影格配置的大小。 + 要為單一影片影格配置的大小。 ## 存取指標和指標記錄 C\$1\$1 生產者 SDK 包含指標和指標記錄的功能。 您可以使用 `getKinesisVideoMetrics`和 `getKinesisVideoStreamMetrics` API 操作來擷取 Kinesis Video Streams 和作用中串流的相關資訊。 以下是來自 `kinesis-video-pic/src/client/include/com/amazonaws/kinesis/video/client/Include.h` 檔案的程式碼。 ``` /** * Gets information about the storage availability. * * @param 1 CLIENT_HANDLE - the client object handle. * @param 2 PKinesisVideoMetrics - OUT - Kinesis Video metrics to be filled. * * @return Status of the function call. */ PUBLIC_API STATUS getKinesisVideoMetrics(CLIENT_HANDLE, PKinesisVideoMetrics); /** * Gets information about the stream content view. * * @param 1 STREAM_HANDLE - the stream object handle. * @param 2 PStreamMetrics - Stream metrics to fill. * * @return Status of the function call. */ PUBLIC_API STATUS getKinesisVideoStreamMetrics(STREAM_HANDLE, PStreamMetrics); ``` 由 `getKinesisVideoMetrics` 填滿的 `PClientMetrics` 物件包含下列資訊： + **contentStoreSize：**內容存放區 (用於存放串流資料的記憶體) 的總大小 (位元組)。 + **contentStoreAvailableSize：**內容存放區中可用的記憶體，以位元組為單位。 + **contentStoreAllocatedSize：**內容存放區的配置記憶體。 + **totalContentViewsSize：**用於內容檢視的總記憶體。內容檢視是內容存放區中一系列的資訊索引。 + **totalFrameRate：**所有作用中串流的每秒畫面彙總數量。 + **totalTransferRate：**所有串流中每秒傳送的總位元數 (bps)。 由 `getKinesisVideoStreamMetrics` 填滿的 `PStreamMetrics` 物件包含下列資訊： + **currentViewDuration：**內容檢視前端 （編碼影格時） 與目前位置 （將影格資料傳送至 Kinesis Video Streams 時） 之間 100 ns 單位的差異。 + **overallViewDuration：**內容檢視前端 （編碼影格時） 與尾端 （從記憶體排清影格時，因為超過內容檢視的總配置空間，或因為從 Kinesis Video Streams 接收`PersistedAck`訊息，而已知會保留的影格） 之間的 100 ns 單位差異。 + **currentViewSize：**內容檢視的大小，從前端 （編碼影格時） 到目前位置 （將影格傳送至 Kinesis Video Streams 時）。 + **overallViewSize：**內容檢視的總大小 (位元組)。 + **currentFrameRate：**串流的最新測量速率 (每秒畫面數)。 + **currentTransferRate：**串流的最新測量速率 (每秒位元組)。 ## 分解 如果您想要傳送緩衝區中剩餘的位元組，並等待 `ACK`，則可以使用 `stopSync`： ``` kinesis_video_stream->stopSync(); ``` 或者，您可以呼叫 `stop` 來結束串流： ``` kinesis_video_stream->stop(); ``` 停止串流後，您可以透過叫用下列 API 來釋出串流： ``` kinesis_video_producer_->freeStream(kinesis_video_stream); ``` # 執行並驗證程式碼 若要執行和驗證 的程式碼[使用 C\$1\$1 生產者程式庫](producer-sdk-cpp.md)，請參閱下列作業系統特定指示： + [Linux](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/docs/linux.md) + [macOS ](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/docs/macos.md) + [Windows](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/docs/windows.md) + [Raspberry Pi 作業系統](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/docs/raspberry-pi.md) 您可以在 Amazon CloudWatch 主控台中監看與串流相關聯的指標，例如 ，以監控串流上的流量`PutMedia.IncomingBytes`。 # 使用 C\$1\$1 生產者 SDK 做為 GStreamer 外掛程式 [GStreamer](https://gstreamer.freedesktop.org/) 是多個攝影機和視訊來源使用的熱門媒體架構，可透過結合模組化外掛程式來建立自訂媒體管道。Kinesis Video Streams GStreamer 外掛程式可簡化現有 GStreamer 媒體管道與 Kinesis Video Streams 的整合。 如需使用 C\$1\$1 生產者 SDK 做為 GStreamer 外掛程式的詳細資訊，請參閱 [範例：Kinesis Video Streams 生產者 SDK GStreamer 外掛程式 - kvssink](examples-gstreamer-plugin.md)。 # 使用 C\$1\$1 生產者 SDK 做為 Docker 容器中的 GStreamer 外掛程式 [GStreamer](https://gstreamer.freedesktop.org/) 是多個攝影機和視訊來源使用的熱門媒體架構，可透過結合模組化外掛程式來建立自訂媒體管道。Kinesis Video Streams GStreamer 外掛程式可簡化現有 GStreamer 媒體管道與 Kinesis Video Streams 的整合。 此外，使用 [Docker]() 建立 GStreamer 管道會將 Kinesis Video Streams 的操作環境標準化，以簡化應用程式的建置和執行。 如需在 Docker 容器中使用 C\$1\$1 生產者 SDK 做為 GStreamer 外掛程式的詳細資訊，請參閱 [在 Docker 容器中執行 GStreamer 元素](examples-gstreamer-plugin.md#examples-gstreamer-plugin-docker)。 # 搭配 C\$1\$1 生產者 SDK 使用記錄 您可以在 `kinesis-video-native-build` 資料夾中的 `kvs_log_configuration` 檔案中設定 C\$1\$1 生產者 SDK 應用程式的記錄。 以下範例顯示預設組態檔案的第一行，可用來設定應用程式將 `DEBUG` 層級日誌項目寫至 AWS 管理主控台： ``` log4cplus.rootLogger=DEBUG, KvsConsoleAppender ``` 您可以將記錄層級設為 `INFO`，以用於較為詳細的記錄。 若要設定應用程式將日誌項目寫入日誌檔案，請將檔案中的第一行更新為下列項目： ``` log4cplus.rootLogger=DEBUG, KvsConsoleAppender, KvsFileAppender ``` 這會把應用程式設為將日誌項目寫入至 `kvs.log` 資料夾的 `kinesis-video-native-build/log` 中。 若要變更日誌檔位置，請以新路徑更新下列行： ``` log4cplus.appender.KvsFileAppender.File=./log/kvs.log ``` **注意** 如果 `DEBUG` - 層級記錄為寫入至檔案，則日誌檔可能快速用掉裝置上的可用儲存空間。 # 使用 C 生產者程式庫 您可以使用 Amazon Kinesis Video Streams 提供的 C 生產者程式庫撰寫應用程式程式碼，將媒體資料從裝置傳送至 Kinesis 影片串流。 ## 物件模型 Kinesis Video Streams C 生產者程式庫是以稱為 Platform Independent Codebase (PIC) 的常見元件為基礎，可在 GitHub 上取得，網址為 [https://github.com/awslabs/amazon-kinesis-video-streams-pic/](https://github.com/awslabs/amazon-kinesis-video-streams-pic/)：//。PIC 包含基礎元件的平台獨立商業邏輯。Kinesis Video Streams C 生產者程式庫使用額外的 API 層包裝 PIC，允許案例和平台特定的回呼和事件。Kinesis Video Streams C 生產者程式庫具有下列建置在 PIC 上的元件： + **裝置資訊提供者** – 公開可直接提供給 PIC API 的`DeviceInfo`結構。您可以設定一組提供者，包括應用程式案例最佳化提供者，可根據應用程式處理的串流數量和類型，以及根據可用 RAM 數量設定的所需緩衝量來最佳化內容存放區。 + **串流資訊提供者** – 公開可直接提供給 PIC API 的`StreamInfo`結構。有一組特定於應用程式類型和常見串流案例類型的提供者。這些包括視訊、音訊、音訊和視訊多軌等供應商。這些案例都有預設值，您可以根據應用程式的需求進行自訂。 + **回呼提供者** – 公開可直接提供給 PIC API 的`ClientCallbacks`結構。這包括一組用於聯網的回呼提供者 (CURL 型 API 回呼）、授權 (AWS 憑證 API)，以及在錯誤回呼時重試串流。回呼提供者 API 需要設定許多引數，例如 AWS 區域 和 授權資訊。這可透過使用 IoT 憑證或使用 AWS AccessKeyId、SecretKey 或 SessionToken 來完成。如果您的應用程式需要進一步處理特定回呼，才能實現一些應用程式特定邏輯，您可以使用自訂回呼來增強回呼提供者。 + **FrameOrderCoordinator** – 協助處理多軌案例的音訊和視訊同步。它具有預設行為，您可以自訂以處理應用程式的特定邏輯。它也會先簡化 PIC Frame 結構中的影格中繼資料封裝，再將其提交至底層 PIC API。對於非多軌案例，此元件是 PIC putFrame API 的傳遞。 C 程式庫提供以下物件，管理將資料傳送到 Kinesis 影片串流的作業： + **KinesisVideoClient** – 包含您的裝置相關資訊，並維護要報告 Kinesis Video Streams 事件的回呼。 + **KinesisVideoStream** – 代表視訊串流參數的相關資訊，例如名稱、資料保留期和媒體內容類型。 ## 將媒體放入串流 您可以使用 C 程式庫提供的方法 （例如 `PutKinesisVideoFrame`) 將資料放入`KinesisVideoStream`物件。然後程式庫會管理資料的內部狀態，包括以下任務： + 執行身分驗證。 + 查看網路延遲。如果延遲太高，程式庫可能選擇減少影格數。 + 追蹤進行中串流的狀態。 ## 程序：使用 C 生產者 SDK 此程序示範如何在 C 應用程式中使用 Kinesis Video Streams 用戶端和媒體來源，將 H.264 編碼的影片影格傳送至您的 Kinesis 影片串流。 此程序包含以下步驟： + [下載 C 生產者程式庫程式碼](producersdk-c-download.md) + [撰寫並檢查程式碼](producersdk-c-write.md) + [執行並驗證程式碼](producersdk-c-test.md) # 先決條件 設定 C 生產者 SDK 之前，請確定您有下列先決條件： + **登入**資料 – 在範例程式碼中，您可以透過指定您在登入資料設定檔檔案中設定的設定檔來提供 AWS 登入資料。如果您尚未這麼做，請先設定您的登入資料設定檔。 如需詳細資訊，請參閱[設定用於開發的 AWS 登入資料和區域](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html)。 + **憑證存放區整合** – Kinesis Video Streams 生產者程式庫必須與呼叫的服務建立信任。這是透過驗證公有憑證存放區中的憑證授權單位 (CAs) 來完成。在以 Linux 為基礎的模型中，此存放位於 `/etc/ssl`/ 目錄。 將下列位置的憑證下載到您的憑證存放區： [https://www.amazontrust.com/repository/SFSRootCAG2.pem](https://www.amazontrust.com/repository/SFSRootCAG2.pem) + 安裝下列適用於 macOS 的建構相依性： + [Autoconf 2.69](http://www.gnu.org/software/autoconf/autoconf.html) (授權 GPLv3\$1/Autoconf：GNU GPL 第 3 版或更新版本) + [CMake 3.7 或 3.8](https://cmake.org/) + [Pkg-Config](https://www.freedesktop.org/wiki/Software/pkg-config/) + xCode (macOS)/clang/gcc (xcode-select 2347 版) + Java 開發套件 (JDK) (適用於 Java JNI 編譯) + [Lib-Pkg](https://github.com/freebsd/pkg/tree/master/libpkg) + 安裝下列 Ubuntu 的建置相依性： + Git： `sudo apt install git` + [CMake：](http://kitware.com/cmake)`sudo apt install cmake` + G\$1\$1： `sudo apt install g++` + pkg-config： `sudo apt install pkg-config` + OpenJDK： `sudo apt install openjdk-8-jdk` + 設定 `JAVA_HOME` 環境變數：`export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/` # 下載 C 生產者程式庫程式碼 在本節中，您會下載低階程式庫。如需此範例的先決條件和其他詳細資訊，請參閱 [使用 C\$1\$1 生產者程式庫](producer-sdk-cpp.md)。 1. 建立目錄，然後從 GitHub 儲存庫複製範例原始碼。 ``` git clone --recursive https://github.com/awslabs/amazon-kinesis-video-streams-producer-c.git ``` **注意** 如果您錯過了搭配 `--recursive` 執行 Git 複製，請在 `amazon-kinesis-video-streams-producer-c/open-source` 目錄中運行 `git submodule update --init` 。您也必須安裝 pkg-config、CMake 和建置環境。 如需詳細資訊，請參閱 https：//[https://github.com/awslabs/amazon-kinesis-video-streams-producer-c.git](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c.git) `README.md`中的 。 1. 在您選擇的整合開發環境 (IDE) 中開啟程式碼 (例如 [Eclipse](https://www.eclipse.org/))。 # 撰寫並檢查程式碼 在本節`KvsVideoOnlyStreamingSample.c`中，您會在 GitHub 上 [https://github.com/awslabs/amazon-kinesis-video-streams-producer-c](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c) 儲存庫的 `samples`資料夾中檢查範例應用程式的程式碼。您在上一個步驟中下載了此程式碼。此範例示範如何使用 C 生產者程式庫，將資料夾內的 H.264 編碼影片影格`samples/h264SampleFrames`傳送至 Kinesis 影片串流。 此範例應用程式有三個部分： + 初始化及設定： + 初始化及設定平台特定的媒體管道。 + 初始化及設定管道的 KinesisVideoClient 和 KinesisVideoStream、設定回呼、整合案例特定驗證、擷取和提交轉碼器私有資料，以及讓串流成為「就緒」狀態。 + 主要迴圈： + 從包含時間戳記及旗標的媒體管道取得影格。 + 提交影格至 KinesisVideoStream。 + 分解： + 停止 (同步) KinesisVideoStream、釋放 KinesisVideoStream、釋放 KinesisVideoClient。 此範例應用程式完成下列任務： + 呼叫 `createDefaultDeviceInfo` API 以建立 `deviceInfo` 物件，其中包含裝置或儲存組態的相關資訊。 ``` // default storage size is 128MB. Use setDeviceInfoStorageSize after create to change storage size. CHK_STATUS(createDefaultDeviceInfo(&pDeviceInfo)); // adjust members of pDeviceInfo here if needed pDeviceInfo->clientInfo.loggerLogLevel = LOG_LEVEL_DEBUG; ``` + 呼叫 `createRealtimeVideoStreamInfoProvider` API 以建立 `StreamInfo` 物件。 ``` CHK_STATUS(createRealtimeVideoStreamInfoProvider(streamName, DEFAULT_RETENTION_PERIOD, DEFAULT_BUFFER_DURATION, &pStreamInfo)); // adjust members of pStreamInfo here if needed ``` + 呼叫 `createDefaultCallbacksProviderWithAwsCredentials` API，根據靜態 AWS 登入資料建立預設回呼提供者。 ``` CHK_STATUS(createDefaultCallbacksProviderWithAwsCredentials(accessKey, secretKey, sessionToken, MAX_UINT64, region, cacertPath, NULL, NULL, FALSE, &pClientCallbacks)); ``` + 呼叫 `createKinesisVideoClient` API 以建立包含裝置儲存相關資訊的`KinesisVideoClient`物件，並維護回呼以報告 Kinesis Video Streams 事件。 ``` CHK_STATUS(createKinesisVideoClient(pDeviceInfo, pClientCallbacks, &clientHandle)); ``` + 呼叫 `createKinesisVideoStreamSync` API 以建立 `KinesisVideoStream` 物件。 ``` CHK_STATUS(createKinesisVideoStreamSync(clientHandle, pStreamInfo, &streamHandle)); ``` + 設定範例影格並呼叫 `PutKinesisVideoFrame` API，將該影格傳送至 `KinesisVideoStream` 物件。 ``` // setup sample frame MEMSET(frameBuffer, 0x00, frameSize); frame.frameData = frameBuffer; frame.version = FRAME_CURRENT_VERSION; frame.trackId = DEFAULT_VIDEO_TRACK_ID; frame.duration = HUNDREDS_OF_NANOS_IN_A_SECOND / DEFAULT_FPS_VALUE; frame.decodingTs = defaultGetTime(); // current time frame.presentationTs = frame.decodingTs; while(defaultGetTime() > streamStopTime) { frame.index = frameIndex; frame.flags = fileIndex % DEFAULT_KEY_FRAME_INTERVAL == 0 ? FRAME_FLAG_KEY_FRAME : FRAME_FLAG_NONE; frame.size = SIZEOF(frameBuffer); CHK_STATUS(readFrameData(&frame, frameFilePath)); CHK_STATUS(putKinesisVideoFrame(streamHandle, &frame)); defaultThreadSleep(frame.duration); frame.decodingTs += frame.duration; frame.presentationTs = frame.decodingTs; frameIndex++; fileIndex++; fileIndex = fileIndex % NUMBER_OF_FRAME_FILES; } ``` + 分解： ``` CHK_STATUS(stopKinesisVideoStreamSync(streamHandle)); CHK_STATUS(freeKinesisVideoStream(&streamHandle)); CHK_STATUS(freeKinesisVideoClient(&clientHandle)); ``` # 執行並驗證程式碼 若要執行和驗證 的程式碼[使用 C\$1\$1 生產者程式庫](producer-sdk-cpp.md)，請執行下列動作： 1. 執行下列命令，在[下載的 C 開發套件](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c.git)中建立`build`目錄，並從`cmake`中啟動： ``` mkdir -p amazon-kinesis-video-streams-producer-c/build; cd amazon-kinesis-video-streams-producer-c/build; cmake .. ``` 您可以將以下選項傳給 `cmake ..` + `-DBUILD_DEPENDENCIES` - 是否根據來源的程式庫建置 。 + `-DBUILD_TEST=TRUE` - 建置單位和整合測試。可能有助於確認對裝置的支援。 `./tst/webrtc_client_test` + `-DCODE_COVERAGE` - 啟用涵蓋範圍報告。 + `-DCOMPILER_WARNINGS` - 啟用所有編譯器警告。 + `-DADDRESS_SANITIZER` - 使用 AddressSanitizer 建置 。 + `-DMEMORY_SANITIZER` - 使用 MemorySanitizer 建置 。 + `-DTHREAD_SANITIZER` - 使用 ThreadSanitizer 建置 。 + `-DUNDEFINED_BEHAVIOR_SANITIZER` - 使用 UndefinedBehaviorSanitizer 建置 。 + `-DALIGNED_MEMORY_MODEL` - 僅針對對齊記憶體模型的裝置建立。預設值為 `OFF`。 1. 導覽至您剛使用上一個步驟建立的`build`目錄，然後執行 `make` 來建置 WebRTC C 開發套件及其提供的範例。 ``` make ``` 1. 範例應用程式會將資料夾內的 `kinesis_video_cproducer_video_only_sample` h.264 編碼影片影格`samples/h264SampleFrames`傳送至 Kinesis Video Streams。下列命令會將迴圈中的影片影格 10 秒傳送至 Kinesis Video Streams： ``` ./kinesis_video_cproducer_video_only_sample YourStreamName 10 ``` 如果您想要從另一個資料夾 （例如 `MyH264FramesFolder`) 傳送 H.264 編碼的影格，請使用下列引數執行範例： ``` ./kinesis_video_cproducer_video_only_sample YourStreamName 10 MyH264FramesFolder ``` 1. 若要啟用詳細日誌，請取消 `CMakeList.txt` 中適當的程式列來定義 `HEAP_DEBUG` 和 `LOG_STREAMING` C-defines。 在 IDE 中，您可以監控偵錯輸出測試套件的進度。您也可以在 Amazon CloudWatch 主控台中觀看與串流相關聯的指標，例如 ，來監控串流上的流量`PutMedia.IncomingBytes`。 **注意** 因為測試工具只傳送空位元組的影格，所以主控台不會將資料顯示為視訊串流。 # 在 Raspberry Pi 上使用 C\$1\$1 生產者 SDK Raspberry Pi 是一款小型且便宜的電腦，可用來教授和學習基本電腦程式設計技能。本教學課程說明如何在 Raspberry Pi 裝置上設定和使用 Amazon Kinesis Video Streams C\$1\$1 生產者 SDK。此步驟同時包含如何使用 GStreamer 示範應用程式驗證安裝。 **Topics** + [先決條件](producersdk-cpp-rpi-prerequisites.md) + [建立具有寫入 Kinesis Video Streams 許可的 IAM 使用者](producersdk-cpp-rpi-iam.md) + [將 Raspberry Pi 加入 Wi-Fi 網路](producersdk-cpp-rpi-wifi.md) + [遠端連線至 Raspberry Pi](producersdk-cpp-rpi-connect.md) + [設定 Raspberry Pi 攝影機](producersdk-cpp-rpi-camera.md) + [安裝軟體先決條件](producersdk-cpp-rpi-software.md) + [下載並建置 Kinesis Video Streams C\$1\$1 生產者 SDK](producersdk-cpp-rpi-download.md) + [將影片串流到您的 Kinesis 影片串流](producersdk-cpp-rpi-run.md) + [從 Kinesis 影片串流播放媒體](producersdk-cpp-rpi-playback.md) + [針對適用於 Raspberry Pi 的 C\$1\$1 生產者 SDK 的建置問題進行故障診斷](troubleshoot-rpi.md) # 先決條件 在 Raspberry Pi 上設定 C\$1\$1 生產者開發套件之前，請確定您有下列先決條件： + 使用以下組態的 Raspberry Pi 裝置： + 機板版本：3 Model B 或更新版本。 + 連接的[攝影機模組](https://www.raspberrypi.com/documentation/accessories/camera.html)或連接的 USB 攝影機 （網路攝影機）。 + 容量至少 8 GB 的 SD 卡。 + 已安裝 Raspbian 作業系統 (4.9 核心版或更新版本)。您可以從 Raspberry Pi [網站下載最新的 Raspberry Pi](https://www.raspberrypi.com/software/) OS （先前稱為 Raspbian) 映像。遵循 Raspberry Pi 指示[將下載的映像安裝在 SD 卡上](https://www.raspberrypi.com/documentation/computers/getting-started.html#install-an-operating-system)。 + AWS 帳戶 具有 Kinesis 影片串流的 。如需更多資訊，請參閱 [Kinesis 視訊串流入門](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/getting-started.html)。 # 建立具有寫入 Kinesis Video Streams 許可的 IAM 使用者 如果您尚未這麼做，請設定具有寫入 Kinesis 影片串流許可的 AWS Identity and Access Management (IAM) 使用者。 這些程序旨在協助您快速開始使用 AWS 存取金鑰對。裝置可以使用 X.509 憑證來連線 AWS IoT。[使用 控制對 Kinesis Video Streams 資源的存取 AWS IoT](how-iot.md) 如需如何設定裝置以使用憑證型身分驗證的詳細資訊，請參閱 。 1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。 1. 在左側的導覽功能表中，選擇 **Users (使用者)**。 1. 若要建立新使用者，請選擇 **Add user (新增使用者)**。 1. 提供使用者的​描述性**使用者名稱**​，例如 **kinesis-video-raspberry-pi-producer**​。 1. 在 **Access type (存取類型)** 下，選擇 **Programmatic access (程式設計存取)**。 1. 選擇**下一步：許可**。 1. 在 **Set permissions for kinesis-video-raspberry-pi-producer (設定 kinesis-video-raspberry-pi-producer 許可)** 下，選擇 **Attach existing policies directly (直接貼附現有的政策)**。 1. 選擇**建立政策**。**Create policy (建立政策)** 頁面在 web 瀏覽器的新索引標籤中開啟。 1. 選擇 **JSON** 標籤。 1. 將下列 JSON 政策複製並貼入文字區域。此政策提供使用者建立資料並將其寫入 Kinesis 影片串流的許可。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "kinesisvideo:DescribeStream", "kinesisvideo:CreateStream", "kinesisvideo:GetDataEndpoint", "kinesisvideo:PutMedia" ], "Resource": [ "*" ] }] } ``` ------ 1. 選擇**檢閱政策**。 1. 為您的政策提供一個**名稱**，例如 **kinesis-video-stream-write-policy**。 1. 選擇**建立政策**。 1. 在瀏覽器中，返回 **Add user (新增使用者)** 索引標籤，然後選擇 **Refresh (重新整理)**。 1. 在搜尋方塊中，輸入您建立之政策的名稱。 1. 在清單中，選取新政策旁邊的核取方塊。 1. 選擇 **Next:Review (下一步：檢閱)**。 1. 選擇 **Create user** (建立使用者)。 1. 主控台會顯示新使用者的 **Access key ID (存取金鑰 ID)**。請選擇 **Show (顯示)**，以顯示 **Secret access key (私密存取金鑰)**。記錄這些值；設定應用程式時需要它們。 # 將 Raspberry Pi 加入 Wi-Fi 網路 如果您使用連接的螢幕和鍵盤，請前往 [設定 Raspberry Pi 攝影機](producersdk-cpp-rpi-camera.md)。 這些指示旨在協助您在*無頭*模式下執行時設定 Raspberry Pi，也就是沒有連接的鍵盤、監視器或網路纜線。請依照下列指示設定 Raspberry Pi，以自動嘗試連線到指定的網路，讓您的主機機器能夠 SSH 連入其中。 1. 在您的電腦上，建立名為 `wpa_supplicant.conf` 的檔案。 1. 複製下列文字並將其貼入 `wpa_supplicant.conf` 檔案： ``` country=US ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev update_config=1 network={ ssid="Your Wi-Fi SSID" scan_ssid=1 key_mgmt=WPA-PSK psk="Your Wi-Fi Password" } ``` 將 `ssid` 和 `psk` 值更換為 Wi-Fi 網路的資訊。 1. 將 `wpa_supplicant.conf` 檔案複製到 SD 卡。必須複製到 `boot` 磁碟區的根使用者。 1. 將 SD 卡插入 Raspberry Pi 並開機。它會加入您的 Wi-Fi 網路，且 SSH 已啟用。 # 遠端連線至 Raspberry Pi 如果您使用連接的螢幕和鍵盤，請前往 [設定 Raspberry Pi 攝影機](producersdk-cpp-rpi-camera.md)。 這些指示旨在協助您在*無周邊*模式下執行時設定 Raspberry Pi，也就是不使用連接的鍵盤、監視器或網路纜線。請依照下列指示，在網路上找到您的 Raspberry Pi，並從主機機器將 SSH 放入其中。 1. 在遠端連接 Raspberry Pi 裝置之前，請執行以下其中一項操作以判斷其 IP 地址： + 如果您可以存取網路的 Wi-Fi 路由器，請查看連接的 Wi-Fi 裝置。尋找名為 `Raspberry Pi` 的裝置，以找到您裝置的 IP 地址。 + 如果您無法存取網路的 Wi-Fi 路由器，可以使用其他軟體來尋找網路上的裝置。[Fing](https://www.fing.com/) 是一款常見的應用程式，同時適用於 Android 和 iOS 裝置。您可以使用此應用程式的免費版本，在網路上尋找裝置的 IP 地址。 1. 當您知道 Raspberry Pi 裝置的 IP 地址之後，就可以使用任何終端應用程式進行連接。 + 在 macOS 或 Linux 上，請使用 `ssh`： ``` ssh pi@ ``` + 在 Windows 上，請使用 [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)，其為適用於 Windows 的免費 SSH 用戶端。 新安裝的 Raspbian 中，使用者名稱為 **pi**，密碼為 **raspberry**。建議您[變更預設密碼](https://www.raspberrypi.com/documentation/computers/configuration.html#change-user-password-nonint)。 # 設定 Raspberry Pi 攝影機 請依照下列步驟設定 [Raspberry Pi 攝影機模組](https://www.raspberrypi.com/documentation/accessories/camera.html)，將影片從裝置傳送至 Kinesis 影片串流。 **注意** 如果您使用的是 USB 網路攝影機，請跳至 [安裝軟體先決條件](producersdk-cpp-rpi-software.md)。 ------ #### [ Camera module 1 ] 請依照這些指示更新模組檔案、啟用相機界面，以及驗證相機的功能。更新模組檔案會告知 Raspberry Pi 在開機時要載入哪些核心模組。預設不會載入攝影機驅動程式，以便在未使用攝影機的 Raspberry Pi 裝置上節省系統資源。 1. 開啟編輯器以變更模組檔案。開啟終端機，並使用下列命令，使用`nano`編輯器編輯檔案： ``` sudo nano /etc/modules ``` 1. 如果檔案結尾沒有下列內容，請將它加入： ``` bcm2835-v4l2 ``` 1. 儲存檔案，然後退出編輯器。若要使用`nano`編輯器儲存和結束，請使用 Ctrl\$1X。 1. 重新啟動 Raspberry Pi： ``` sudo reboot ``` 1. 裝置重新啟動時，如果您是遠端連接，請透過終端應用程式再次連接。 1. Open `raspi-config`: ``` sudo raspi-config ``` 1. 選擇**介面選項**、**舊版攝影機**。在 Raspbian 作業系統的較舊版本中，此功能表選項可能位於**介面選項****相機**下。 如果沒有啟用攝影機則將其啟用，並在出現提示訊息時重新啟動。 1. 輸入下列命令，驗證攝影機是否正常運作： ``` raspistill -v -o test.jpg ``` 如果您的攝影機設定正確，此命令會從攝影機擷取影像，將其儲存至名為 的檔案`test.jpg`，並顯示資訊性訊息。 ------ #### [ Camera module 2 or 3 ] 如果您使用的是攝影機模組 2，您可以使用 `bcm2835-v4l2`（舊版） 或 `libcamera`（現代）。不過，建議使用 `libcamera`堆疊以獲得更好的支援和功能。請依照下列步驟，確認 在您的系統上`libcamera`是up-to-date。 1. [libcamera](https://www.raspberrypi.com/documentation/computers/camera_software.html#libcamera) 應該預先安裝在 Raspberry Pi 上。檢查是否有任何更新，並更新至最新版本，以取得錯誤修正和安全性更新。開啟終端機並輸入下列命令： ``` sudo apt-get update sudo apt-get upgrade ``` 1. 重新啟動您的系統，讓更新生效。 ``` sudo reboot ``` 1. 測試您的攝影機。此應用程式會啟動攝影機預覽串流，並在螢幕上顯示。 ``` libcamera-hello ``` 如果相機模組發生問題，請參閱 [Raspberry Pi 文件](https://raspberrypi.com/documentation/computers/camera_software.html#troubleshooting)進行故障診斷。 ------ # 安裝軟體先決條件 C\$1\$1 生產者 SDK 需要您在 Raspberry Pi 上安裝下列軟體先決條件。 1. 更新套件清單並安裝建置 SDK 所需的程式庫。開啟終端機並輸入下列命令： ``` sudo apt-get update sudo apt-get install -y \ automake \ build-essential \ cmake \ git \ gstreamer1.0-plugins-base-apps \ gstreamer1.0-plugins-bad \ gstreamer1.0-plugins-good \ gstreamer1.0-plugins-ugly \ gstreamer1.0-tools \ gstreamer1.0-omx-generic \ libcurl4-openssl-dev \ libgstreamer1.0-dev \ libgstreamer-plugins-base1.0-dev \ liblog4cplus-dev \ libssl-dev \ pkg-config ``` 1. 如果您使用的是 `libcamera`堆疊，也請安裝 `libcamerasrc` GStreamer 外掛程式。預設不會安裝此 GStreamer 外掛程式。 ``` sudo apt-get install gstreamer1.0-libcamera ``` 1. 將以下 PEM 檔案複製到 `/etc/ssl/cert.pem`： ``` sudo curl https://www.amazontrust.com/repository/AmazonRootCA1.pem -o /etc/ssl/AmazonRootCA1.pem sudo chmod 644 /etc/ssl/AmazonRootCA1.pem ``` # 下載並建置 Kinesis Video Streams C\$1\$1 生產者 SDK 請依照下列程序下載並建置 [Kinesis Video Streams C\$1\$1 生產者 SDK](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp)。請確定您已安裝軟體先決條件；如需這些步驟[安裝軟體先決條件](producersdk-cpp-rpi-software.md)，請參閱 。 1. 導覽至下載目錄。開啟終端機並變更為您偏好的下載目錄。 例如： ``` cd ~/Downloads ``` 1. 複製 SDK 儲存庫。使用 `git clone`命令從 GitHub 儲存庫下載 SDK。類型： ``` git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp.git --single-branch -b master kvs-producer-sdk-cpp ``` 此命令只會複製單一分支 (`master`分支），以減少下載大小和時間。它也會將下載的內容放入目前目錄中名為 `kvs-producer-sdk-cpp`的資料夾。 1. 驗證下載。複製程序完成後，請列出`kvs-producer-sdk-cpp`資料夾的內容，以確認已下載 SDK。 ``` ls kvs-producer-sdk-cpp ``` 1. 準備建置目錄。類型： ``` mkdir -p kvs-producer-sdk-cpp/build cd kvs-producer-sdk-cpp/build ``` 1. 設定建置。執行下列`cmake`命令，以使用特定選項設定建置環境： ``` cmake .. -DBUILD_GSTREAMER_PLUGIN=ON -DBUILD_DEPENDENCIES=OFF -DALIGNED_MEMORY_MODEL=ON ``` [CMake](https://cmake.org/cmake/help/latest/manual/cmake.1.html) 使用以下選項來產生適當的 `Makefiles`： + 使用專案資料夾 (`..`) 做為來源目錄。 + 使用目前的目錄 (`.`) (`build/`) 進行建置輸出。 + `-DBUILD_GSTREAMER_PLUGIN=ON` 可建置 GStreamer 外掛程式 kvssink。 + `-DBUILD_DEPENDENCIES=OFF` 停用從來源建置外部相依性。專案會尋找並使用上一個步驟中安裝的外部相依性。 + `-DALIGNED_MEMORY_MODEL=ON` 會停用未對齊的記憶體模型。某些 Raspberry Pi 裝置不支援未對齊的記憶體存取。 **注意** 如需 CMake 引數的完整清單，請參閱 [下載並設定 C\$1\$1 生產者程式庫程式碼](producersdk-cpp-download.md)。 1. 建置專案。設定組建後，請使用 `make`命令，使用 `Makefile`產生的 編譯 `cmake`。 ``` make -j$(nproc) ``` 的 `-j` 引數`make`允許它平行執行多個編譯任務。若要減少建置時間，請使用 `nproc`命令動態計算 Raspberry Pi 上的 CPU 核心數量。 1. 確認 `libgstkvssink.so` 存在。 列出目前目錄中的檔案。 **提示：** ``` ls ``` **回應：** ``` CMakeCache.txt dependency kvs_gstreamer_sample CMakeFiles kvs_gstreamer_audio_video_sample kvssink_gstreamer_sample Makefile kvs_gstreamer_file_uploader_sample libKinesisVideoProducer.so cmake_install.cmake kvs_gstreamer_multistream_sample libgstkvssink.so ``` 1. 確認 GStreamer 可以載入 `kvssink`。 將`GST_PLUGIN_PATH`環境變數設定為包含 的目錄`libgstkvssink.so`。 ``` export GST_PLUGIN_PATH=`pwd` ``` 讓 GStreamer 載入`kvssink`： ``` gst-inspect-1.0 kvssink ``` 您應該會看到一些有關 的文件`kvssink`。使用方向鍵導覽並按 `q` 退出。 1. (**選用**) 更新 shell 的啟動指令碼，以包含設定`GST_PLUGIN_PATH`環境變數。這可確保`GST_PLUGIN_PATH`在新的終端機工作階段期間正確設定。在 Raspberry Pi 裝置上，殼層的啟動指令碼為 `~/.bashrc`。 執行下列命令，將命令附加到 shell 啟動指令碼的結尾。 ``` echo "export GST_PLUGIN_PATH=~/Downloads/kvs-producer-sdk-cpp/build" >> ~/.bashrc ``` 輸入以下內容以執行 shell 的啟動指令碼，或關閉目前的 shell 並開啟新的 shell。 ``` source ~/.bashrc ``` 確認 `GST_PLUGIN_PATH` 已設定，您可以載入 `kvssink`。 ``` echo $GST_PLUGIN_PATH ``` ``` gst-inspect-1.0 kvssink ``` # 將影片串流到您的 Kinesis 影片串流 若要執行範本應用程式，您需要以下資訊： + 在 [先決條件](producersdk-cpp-rpi-prerequisites.md) 區段中建立之串流的名稱。 + 在[建立具有寫入 Kinesis Video Streams 許可的 IAM 使用者](producersdk-cpp-rpi-iam.md)中建立的帳戶登入資料 (存取金鑰 ID 和私密存取金鑰)。 + GStreamer 能夠找到`kvssink`外掛程式。如需詳細資訊，請參閱[下載並建置 Kinesis Video Streams C\$1\$1 生產者 SDK](producersdk-cpp-rpi-download.md)。 1. 設定登入資料和區域。 ``` export AWS_ACCESS_KEY_ID=YourAccessKey export AWS_SECRET_ACCESS_KEY=YourSecretKey export AWS_DEFAULT_REGION=us-west-2 ``` 如需其他身分驗證方法，請參閱 [提供登入資料給 `kvssink`](examples-gstreamer-plugin-parameters.md#credentials-to-kvssink)。 **注意** C\$1\$1 生產者 SDK 預設使用美國西部 （奧勒岡） (`us-west-2`) 區域。若要使用預設，在美國西部 （奧勒岡） 區域中 AWS 區域 建立 Kinesis 影片串流。 若要為 Kinesis 影片串流使用不同的區域，請將下列環境變數設定為您的區域 （例如 *us-east-1*)： ``` export AWS_DEFAULT_REGION=us-east-1 ``` 1. 根據您的輸入媒體，選擇下列其中一項： ------ #### [ Sample GStreamer video ] 此 GStreamer 管道會產生即時測試影片串流，其標準測試模式以每秒 10 個影格執行，解析度為 640x480 像素。新增浮水印，顯示目前的系統時間和日期。然後影片會編碼為 H.264 格式，金鑰影格最多每 10 個影格產生一次，導致片段持續時間 （也稱為一組圖片 (GoP) 大小） 為 1 秒。kvssink 採用 H.264 編碼的影片串流，將其封裝為 Matroska (MKV) 容器格式，並將其上傳至 Kinesis 影片串流。 執行以下命令： ``` gst-launch-1.0 -v videotestsrc is-live=true \ ! video/x-raw,framerate=10/1,width=640,height=480 \ ! clockoverlay time-format="%a %B %d, %Y %I:%M:%S %p" \ ! x264enc bframes=0 key-int-max=10 \ ! h264parse \ ! kvssink stream-name="YourStreamName" ``` 若要停止 GStreamer 管道，請選取終端機視窗，然後按 **CTRL\$1C**。 範例影片 GStreamer 管道如下所示： ![\[具有疊加日期和時間戳的標準測試模式的影像。\]](http://docs.aws.amazon.com/zh_tw/kinesisvideostreams/latest/dg/images/sample-video.png) ------ #### [ USB web cam ] 執行下列命令，讓 GStreamer 自動偵測您的 USB 攝影機： ``` gst-launch-1.0 autovideosrc \ ! videoconvert \ ! video/x-raw,format=I420,width=640,height=480 \ ! x264enc bframes=0 key-int-max=45 tune=zerolatency byte-stream=true speed-preset=ultrafast \ ! h264parse \ ! video/x-h264,stream-format=avc,alignment=au,profile=baseline \ ! kvssink stream-name="YourStreamname" ``` 若要停止 GStreamer 管道，請選取終端機視窗，然後按 **CTRL\$1C**。 您可以`v4l2src`搭配特定裝置識別符使用 ，而不是讓 GStreamer 自動偵測。執行以下命令： ``` gst-device-monitor-1.0 ``` 在輸出中，您會看到一些裝置，以及 GStreamer 管道的開始，了解如何使用裝置： ``` Device found: name : H264 USB Camera: USB Camera class : Video/Source caps : video/x-h264, stream-format=(string)byte-stream, alignment=(string)au, width=(int)1920, height=(int)1080, pixel-aspect-ratio=(fraction)1/1, colorimetry=(string){ 2:4:7:1 }, framerate=(fraction){ 30/1, 25/1, 15/1 }; ... properties: device.path = /dev/video4 udev-probed = false device.api = v4l2 v4l2.device.driver = uvcvideo v4l2.device.card = "H264\ USB\ Camera:\ USB\ Camera" v4l2.device.bus_info = usb-3f980000.usb-1.3 v4l2.device.version = 265767 (0x00040e27) v4l2.device.capabilities = 2216689665 (0x84200001) v4l2.device.device_caps = 69206017 (0x04200001) gst-launch-1.0 v4l2src device=/dev/video4 ! ... ``` 若要停止 GStreamer 管道，請選取終端機視窗，然後按 **CTRL\$1C**。 ------ #### [ Raspberry Pi camera module 1 ] 如果您使用 Pi 攝影機模組 1 或 Pi 攝影機模組 2 搭配 `bcm2835-v4l2`，請使用下列項目： ``` gst-launch-1.0 v4l2src device=/dev/video0 \ ! videoconvert \ ! video/x-raw,format=I420,width=640,height=480 \ ! x264enc bframes=0 key-int-max=45 bitrate=500 tune=zerolatency \ ! h264parse ! video/x-h264,stream-format=avc,alignment=au,profile=baseline \ ! kvssink stream-name="YourStreamname" ``` 若要停止 GStreamer 管道，請選取終端機視窗，然後按 **CTRL\$1C**。 ------ #### [ Raspberry Pi camera module 2 or 3 ] 如果您使用的是現代`libcamera`堆疊，請使用下列 GStreamer 管道： ``` gst-launch-1.0 libcamerasrc \ ! video/x-raw,width=640,height=480,framerate=30/1,format=I420 \ ! videoconvert \ ! x264enc speed-preset=ultrafast tune=zerolatency byte-stream=true key-int-max=75 \ ! video/x-h264,level='(string)4' \ ! h264parse \ ! video/x-h264,stream-format=avc,alignment=au,width=640,height=480,framerate=30/1 \ ! kvssink stream-name="YourStreamname" ``` 若要停止 GStreamer 管道，請選取終端機視窗，然後按 **CTRL\$1C**。 ------ #### [ Sample RTSP camera ] 在此範例中，我們使用 Gst-Rtsp-Server 在本機託管示範 RTSP 攝影機摘要。然後，我們會建構 GStreamer 管道，將該 RTSP 攝影機摘要上傳至指定的 Kinesis 影片串流。 **在 Raspberry Pi 上設定 Gst-Rtsp-Server ** 1. 安裝必要的相依性程式庫，以建置 Gst-Rtsp-Server 專案。請確定您也已安裝軟體先決條件。在終端機中輸入以下內容： ``` sudo apt-get update sudo apt-get install libgstrtspserver-1.0 ``` 1. 在 Raspberry Pi 上下載 1.22 版的 GStreamer。 ``` git clone https://gitlab.freedesktop.org/gstreamer/gstreamer.git --single-branch -b 1.22 ``` 1. 將目錄變更為 gst-rtsp-server 中的範例目錄。 ``` cd gstreamer cd subprojects cd gst-rtsp-server cd examples ``` 1. 使用 gcc 將 test-launch.c 編譯為稱為 test-launch 的可執行檔。 ``` gcc -o test-launch test-launch.c `pkg-config --cflags --libs gstreamer-rtsp-server-1.0` ``` 1. 使用以下引數執行可執行檔。注意：GStreamer 第一次載入可能需要一些時間。 ``` ./test-launch "videotestsrc is-live=true ! video/x-raw,height=480,width=640,framerate=10/1 ! videoconvert ! x264enc tune=zerolatency bitrate=512 key-int-max=25 bframes=0 ! h264parse ! rtph264pay ! name=pay0 pt=96" ``` 您應該會看到下列輸出： ``` stream ready at rtsp://127.0.0.1:8554/test ``` 1. 驗證 RTSP 影片串流。您可以使用任何 RTSP 檢視器。例如，VPC 媒體播放器。若要使用 VLC 媒體播放器來檢視即時串流，請開啟新的終端機並輸入： ``` sudo apt-get install vlc ``` 安裝 VLC 媒體播放器。然後輸入： ``` vlc rtsp://127.0.0.1:8554/test ``` VLC 視窗應該會隨即時串流彈出。如果沒有，請檢查 test-launch 可執行檔是否仍在執行，並檢查輸出是否有任何錯誤。 驗證 RTSP 串流的另一種方法是使用 gst-discoverer-1.0 公用程式。類型： ``` gst-discoverer-1.0 "rtsp://127.0.0.1:8554/test" ``` 預期的輸出如下所示： ``` Analyzing rtsp://127.0.0.1:8554/test Done discovering rtsp://127.0.0.1:8554/test Properties: Duration: 99:99:99.999999999 Seekable: no Live: yes unknown #0: application/x-rtp video #1: H.264 (Constrained Baseline Profile) Stream ID: 359314d7d4bba383223927d7e57d4244d0800e629c626be81c505055c62170e2/video:0:0:RTP:AVP:96 Width: 640 Height: 480 Depth: 24 Frame rate: 10/1 Pixel aspect ratio: 1/1 Interlaced: false Bitrate: 0 Max bitrate: 0 ``` **使用 kvssink 將 RTSP 摘要傳送至 Kinesis Video Stream** 此 GStreamer 管道使用 `rtspsrc`連線至 RTSP 伺服器來擷取 RTP 影片串流。它會將影格傳遞至 `rtph264depay`，它會從 RTP 封包擷取 H.264 編碼的影片影格。 會將影片影格`h264parse`分組為`kvssink`可理解的格式。 會`kvssink`採用 H.264 編碼的影片串流，將其封裝為 Matroska (MKV) 容器格式，並將其上傳至 Kinesis 影片串流。 執行以下命令： ``` gst-launch-1.0 -v rtspsrc location="rtsp://127.0.0.1:8554/test" short-header=true \ ! rtph264depay \ ! h264parse \ ! video/x-h264,format=avc,alignment=au \ ! kvssink stream-name="YourStreamName" ``` 若要停止 GStreamer 管道，請選取終端機視窗，然後按 **CTRL\$1C**。 ------ ## 使用硬體 有些 Raspberry Pi 模型隨附硬體加速 H.264 編碼器。您可以使用它們來取代 `x264enc`，這是軟體編碼器。 1. 請確定已安裝 GStreamer 外掛程式： ``` sudo apt-get install gstreamer1.0-tools gstreamer1.0-plugins-bad ``` 1. 類型： ``` gst-inspect-1.0 | grep h264 ``` 判斷下列元素是否可用： + omxh264enc + v4l2h264enc 如果可用，您可以使用它們。以下是使用這些元素的一些管道範例： **`omxh264enc`:** ``` gst-launch-1.0 v4l2src device=/dev/video0 \ ! videoconvert \ ! video/x-raw,format=I420,width=640,height=480 \ ! omxh264enc control-rate=2 target-bitrate=512000 periodicity-idr=45 inline-header=FALSE \ ! h264parse ! video/x-h264,stream-format=avc,alignment=au,profile=baseline \ ! kvssink stream-name="raspberry" ``` **`v4l2h264enc` 和 `v4l2convert`：** ``` gst-launch-1.0 libcamerasrc \ ! video/x-raw,width=640,height=480,framerate=30/1,format=I420 \ ! v4l2convert \ ! v4l2h264enc extra-controls="controls,repeat_sequence_header=1" \ ! video/x-h264,level='(string)4' \ ! h264parse \ ! video/x-h264,stream-format=avc,alignment=au,width=640,height=480,framerate=30/1 \ ! kvssink stream-name="test-stream" ``` ## 執行時間問題 以下是一些經常遇到的執行時間問題，以及如何進行故障診斷。 ### 沒有這類元素 "xxxxxxxxx" 如果您收到類似以下的錯誤，表示您缺少 GStreamer 外掛程式： ``` WARNING: erroneous pipeline: no element "videoconvert" ``` **解決方法：** 根據缺少哪個元素，判斷適當的動作： + `kvssink`：請參閱[下載並建置 Kinesis Video Streams C\$1\$1 生產者 SDK](producersdk-cpp-rpi-download.md)。 + `libcamerasrc`：請參閱 [「緩衝集區啟用失敗」錯誤](#rpi-troubleshoot-buffer) 安裝 `libcamerasrc` GStreamer 元素。 + `omxh264enc` 或 `v4l2h264enc`： 遵循 [安裝軟體先決條件](producersdk-cpp-rpi-software.md) 安裝所有 GStreamer 程式庫。如果您已全部安裝它們，而且這些元素未顯示，這表示您的 Raspberry Pi 沒有硬體。請`x264enc`改用軟體編碼器。 + 其他：遵循 [安裝軟體先決條件](producersdk-cpp-rpi-software.md) 安裝所有 GStreamer 程式庫。在各種 GStreamer 外掛程式群組中找到不同的 GStreamer 元素 （好、壞、醜），因此請務必全部安裝。 ### 「緩衝集區啟用失敗」錯誤 如果您收到類似以下的錯誤，表示使用的管道正在使用 `v4l2src`，但應該`libcamerasrc`改用 。 ``` ERROR bufferpool gstbufferpool.c:572:gst_buffer_pool_set_active:source:pool0:src start failed WARN v4l2src gstv4l2src.c:976:gst_v4l2src_decide_allocation: error: Failed to allocate required memory. WARN v4l2src gstv4l2src.c:976:gst_v4l2src_decide_allocation: error: Buffer pool activation failed WARN basesrc gstbasesrc.c:3352:gst_base_src_prepare_allocation: Subclass failed to decide allocation Error received from element source: Failed to allocate required memory. WARN basesrc gstbasesrc.c:3132:gst_base_src_loop: error: Internal data stream error. Debugging information: ../sys/v4l2/gstv4l2src.c(976): gst_v4l2src_decide_allocation (): /GstPipeline:live-kinesis-pipeline/GstV4l2Src:source: Buffer pool activation failed WARN basesrc gstbasesrc.c:3132:gst_base_src_loop: error: streaming stopped, reason not-negotiated (-4) ``` 例如，如果您在未`libcamerasrc`安裝攝影機模組 2 的情況下使用下列管道 ，當 GStreamer 嘗試自動偵測要使用的元素時，您可能會遇到此錯誤。 ``` gst-launch-1.0 autovideosrc ! videoconvert ! autovideosink ``` **解決方法：** 確定`libcamerasrc`已安裝 ，並將其用作來源元素，而不是 `v4l2src`。輸入以下內容以安裝 `libcamerasrc` GStreamer 元素： ``` sudo apt-get update sudo apt-get install gstreamer1.0-libcamera ``` 安裝`libcamerasrc`完成後，如果您使用的是 `autovideosrc`元素，GStreamer 應該自動切換為使用正確的來源，`libcamerasrc`而不是 `v4l2src`。 ### 匯流排錯誤 如果您在啟動後不久收到匯流排錯誤 `kvssink`（通常是 HTTP 呼叫`PutMedia`完成的前後），這表示您的 Raspberry Pi 不支援未對齊的記憶體存取。日誌看起來如下： ``` INFO Camera camera.cpp:1197 configuring streams: (0) 640x480-YUV420 INFO RPI pisp.cpp:1450 Sensor: /base/axi/pcie@120000/rp1/i2c@88000/imx708@1a - Selected sensor format: 1536x864-SBGGR10_1X10 - Selected CFE format: 1536x864-PC1B [INFO ] kinesisVideoStreamFormatChanged(): Stream format changed. [DEBUG] setRequestHeader(): Appending header to request: user-agent -> AWS-SDK-KVS-CPP-CLIENT/3.4.2/1.5.3 GCC/12.2.0 Linux/6.6.51+rpt-rpi-v8 aarch64 CPPSDK [DEBUG] setRequestHeader(): Appending header to request: x-amzn-stream-name -> demo-stream [DEBUG] setRequestHeader(): Appending header to request: x-amzn-producer-start-timestamp -> 1732012345.678 [DEBUG] setRequestHeader(): Appending header to request: x-amzn-fragment-acknowledgment-required -> 1 [DEBUG] setRequestHeader(): Appending header to request: x-amzn-fragment-timecode-type -> ABSOLUTE [DEBUG] setRequestHeader(): Appending header to request: transfer-encoding -> chunked [DEBUG] setRequestHeader(): Appending header to request: connection -> keep-alive [INFO ] putStreamResultEvent(): Put stream result event. New upload handle 0 [WARN ] notifyDataAvailable(): [demo-stream] Failed to un-pause curl with error: 43. Curl object 0xe2f6f418 Bus error ``` Kinesis Video Streams PIC 使用未對齊的記憶體存取來最佳化記憶體用量，這並非所有裝置都支援。 **解決方法：** 若要在對齊的記憶體存取模式中使用 SDK，您需要在編譯 `ON`時明確將 `ALIGNED_MEMORY_MODEL` CMake 旗標設定為 `kvssink`，因為它預設為 `OFF`。如需更詳細的說明[下載並建置 Kinesis Video Streams C\$1\$1 生產者 SDK](producersdk-cpp-rpi-download.md)，請參閱 。 ### 時間戳記凍結且管道停滯 在 GStreamer 管道`x264enc`中使用 時，您可能會遇到管道的時間軸在幾秒鐘內明顯或完全停止緩慢的情況。 這是因為`x264enc`預設設定可能會帶來高編碼延遲，這超過預設輸入緩衝區的容量。因此，輸入緩衝區會填滿，導致上游元素封鎖且管道停滯。 如需詳細資訊，請參閱 [GStreamer 文件](https://gstreamer.freedesktop.org/documentation/x264/index.html?gi-language=c)。 **解決方法：** `x264enc` 使用`zerolatency`調校選項來設定 。這可透過針對即時案例進行最佳化，確保更快地處理和輸出影格，大幅降低編碼延遲。 範例組態： ``` ... ! x264enc tune=zerolatency byte-stream=true speed-preset=ultrafast bframes=0 key-int-max=60 ! ... ``` **注意** 雖然此解決方案可有效防止管道停滯，但可能會影響編碼效率和品質。對於同時需要低延遲和高品質的情況，請考慮替代方法，例如使用硬體最佳化或尋找直接輸出 H.264 的網路攝影機，略過此編碼步驟。 如需詳細資訊，請參閱[使用硬體](#producersdk-cpp-rpi-utilize)。 ### 無法同時從相同`v4l2`裝置執行多個管道 這類裝置一次`/dev/video0`只能透過一個程序存取。如果多個程序嘗試同時存取它，第二個程序會等到第一個程序完成。 **解決方法：** 建立迴路裝置，允許多個程序同時使用迴路界面。如需詳細資訊，請參閱 [Stack Exchange](https://raspberrypi.stackexchange.com/questions/19630/take-picam-image-while-motion-is-running/19897#19897)。 ### 內部資料串流錯誤 當您建立 GStreamer 管道時，您可以透過將一個元素的來源鍵盤連結至另一個元素的接收器鍵盤來連接元素。此連結程序允許資料從來源元素流向接收器元素，形成資料管道。 日誌中的錯誤訊息「Pad 連結失敗」表示 GStreamer 在嘗試在管道中兩個元素的Pad 之間建立連線 （連結） 時遇到問題。 ``` Pad link failed Error received from element udpsrc0: Internal data stream error. ``` **解決方法：** 判斷哪些元素無法互相連結。若要縮小管道範圍，請從管道中移除元素。將最右側的元素取代為 `fakesink`，並一次移除一個元素。 您可能需要調整 [capsfilter](https://gstreamer.freedesktop.org/documentation/coreelements/capsfilter.html?gi-language=c) 元素，和/或變更管道使用的元素。 常見情況是要求 `framerate`或攝影機不支援`resolution`的 。在終端機`gst-device-monitor-1.0`中使用 來取得支援的 `framerates`、 `resolutions`和 `formats`。您可以使用[影片規模](https://gstreamer.freedesktop.org/documentation/videoconvertscale/videoscale.html?gi-language=c) GStreamer 元素來調整影片解析度，並使用[影片速率](https://gstreamer.freedesktop.org/documentation/videorate/?gi-language=c)來調整影片影格速率。 若要檢查個別 GStreamer 元素支援的格式，請在終端機`gst-inspect-1.0 element-name`中輸入 。 # 從 Kinesis 影片串流播放媒體 開啟 [Kinesis Video Streams 主控台](https://console.aws.amazon.com//kinesisvideo/home/)，並為您建立的串流選取**串流名稱**。 從 Raspberry Pi 傳送的視訊串流，會出現在主控台。 **注意** 可能需要幾秒鐘的時間，影片才會出現在主控台中。 串流播放後，您可以在 主控台中實驗下列功能： + 在 **Video preview** (視訊預覽) 區段中，請使用導覽控制，以倒轉或向前快轉串流。 + 在**串流資訊**區段中，檢閱串流的轉碼器、解析度和位元速率。Raspberry Pi 上的解析度和位元速率值會刻意設為低，以將本教學課程的頻寬使用量降至最低。 若要檢視為串流建立的 Amazon CloudWatch 指標，請選取在 ** CloudWatch 中檢視串流指標**。 + 在 **Data retention period** (資料保留期間) 下，請注意視訊串流的保留期間為 1 天。您可以編輯此值，將其設定為 **No data retention** (無資料保留)，或將值設定為從一天到數年。 + 在**伺服器端加密**下，請注意您的資料正在使用由 AWS Key Management Service () 維護的金鑰進行靜態加密AWS KMS。 ## 播放問題 以下是一些經常遇到的播放問題，以及如何進行故障診斷。 ### 沒有媒體，但日誌中有 PERSISTED Acks 如果您在日誌中看到 PERSISTED Acks，Kinesis Video Streams 已成功擷取並存放 上傳的媒體`kvssink`。從 Kinesis Video Streams 收到的 Acks 如下所示。在 JSON 中，查看`"EventType"`金鑰的值。 ``` {"EventType":"RECEIVED","FragmentTimecode":252200,"FragmentNumber":"12345678901234567890123456724587702494771079511"} {"EventType":"BUFFERING","FragmentTimecode":252467,"FragmentNumber":"12345678901234567890123456781729223736853277017"} {"EventType":"RECEIVED","FragmentTimecode":252467,"FragmentNumber":"12345678901234567890123456781729223736853277017"} {"EventType":"BUFFERING","FragmentTimecode":253000,"FragmentNumber":"12345678901234567890123456738870744847093249408"} {"EventType":"PERSISTED","FragmentTimecode":252200,"FragmentNumber":"12345678901234567890123456724587702494771079511"} {"EventType":"PERSISTED","FragmentTimecode":252467,"FragmentNumber":"1234567890123456789012345671729223736853277017"} ``` **解決方法：** 在 Kinesis Video Streams 主控台中等待一兩分鐘，然後使用向右雙箭頭。如果沒有顯示媒體，請確認您的串流正在傳送至正確的區域，並檢閱串流名稱的拼寫。您可以在日誌中找到此資訊。 [提供區域給 `kvssink`](examples-gstreamer-plugin-parameters.md#kvssink-region) 如需 kvssink 如何決定要使用的區域的詳細資訊，請參閱 。 ### 媒體在 中載入需要很長的時間 AWS 管理主控台 **重要** 主控台播放體驗與 HLS 和 DASH 播放體驗不同。使用 GitHub 中的範例媒體播放器[託管網頁](https://aws-samples.github.io/amazon-kinesis-video-streams-media-viewer/)來測試播放。您可以在[此處](https://github.com/aws-samples/amazon-kinesis-video-streams-media-viewer)找到網頁的原始碼。 由於網路頻寬不足或裝置受限，媒體可能會在主控台中緩慢載入，但也可能與影片編碼和分段相關。 **影片編碼基本概念：** + H.264 和 H.265 編碼器使用關鍵影格 (I-Frame) 和預測影格 (P-Frame) 以實現高效壓縮。 + 關鍵影格包含完整的影像資料，而 P 影格僅包含先前影格的變更。 + 「關鍵影格間隔」會決定關鍵影格在影片串流中的發生頻率。 **串流中的分段：** + 在 Kinesis Video Streams 中，新片段會從每個關鍵影格開始。如需詳細資訊，請參閱[Kinesis Video Streams 資料模型](how-data.md)。 + 片段長度 （以秒為單位） 可估計為：*關鍵影格間隔* ÷ *影格率* **範例**： 對於關鍵影格間隔為 30 且影格速率為 15 fps 的串流： 片段長度 = 30 ÷ 15 = 2 秒 由於關鍵影格間隔較大，較長的片段會增加串流媒體的延遲。 **解決方法：** 為了改善載入時間，請考慮減少關鍵影格間隔。這將建立較短的片段，減少延遲，但也會增加影片檔案的大小。 對於 `x264enc` GStreamer 元素，您可以透過 `key-int-max` 屬性明確設定關鍵影格間隔： ``` x264enc bframes=0 key-int-max=60 ``` 檢閱日誌輸出時，請注意上傳用戶端從 Kinesis Video Streams 接收 ACKs 的頻率。產生的關鍵影格越多，傳回ACKs 越多。 ### 媒體失真或有成品 若要疑難排解此問題，請確定所有纜線都已緊密連接。檢閱攝影機模組的輸出 `libcamera-hello`（或`raspistill`舊版 Pi 攝影機的輸出）。 在您的 GStreamer 管道中，將 取代`kvssink`為 `autovideosink`或 `matroskamux`和 `filesink`。例如： ``` ... x264enc tune=zerolatency speed-preset=ultrafast bframes=0 key-int-max=60 byte-stream=true ! h264parse ! matroskamux ! filesink location=output.mkv ``` 檢閱 的輸出檔案，`filesink`或是使用 時開啟的媒體播放器`autovideosink`，以查看成品是否也存在。 同時檢閱下列管道的輸出： ``` gst-launch-1.0 autovideosrc ! videoconvert ! autovideosink ``` 將元素新增至管道，例如[去彎曲](https://gstreamer.freedesktop.org/documentation/opencv/dewarp.html?gi-language=c)，可以修正魚眼攝影機輸出。 檢閱攝影機支援的輸出轉碼器，並視需要調整元素。 例如，如果您的 USB 攝影機僅支援 JPEG 輸出，則您將需要使用 `jpegparse`和 `jpegdec`元素來轉換媒體，然後再使用 將其編碼為 H.264`x264enc`。在 GStreamer 論壇上搜尋具有類似管道和/或網路攝影機設定的其他使用者的協助。 # 針對適用於 Raspberry Pi 的 C\$1\$1 生產者 SDK 的建置問題進行故障診斷 如果您遇到建置問題，並想要嘗試不同的 CMake 引數，請務必執行乾淨的建置。刪除 `open-source`、 `dependency`和 `build` 資料夾，然後再試一次。 ## 使用 OpenSSL 建置問題 如果您收到類似以下的輸出，則表示 OpenSSL 未正確偵測到您的系統架構。 ``` crypto/md5/md5-aarch64.S: Assembler messages: crypto/md5/md5-aarch64.S:3: Error: unrecognized symbol type "" crypto/md5/md5-aarch64.S:6: Error: bad instruction `stp x19,x20,[sp,#-80]!' crypto/md5/md5-aarch64.S:7: Error: bad instruction `stp x21,x22,[sp,#16]' crypto/md5/md5-aarch64.S:8: Error: bad instruction `stp x23,x24,[sp,#32]' crypto/md5/md5-aarch64.S:9: Error: bad instruction `stp x25,x26,[sp,#48]' ``` 在此範例中，當 Raspberry Pi 實際上是 32 位元時，它會嘗試建置 64 位元版本 (`linux-aarch64`)。有些 Raspberry Pi 裝置具有 64 位元的核心，但有 32 位元的使用者空間。 決定 OpenSSL 嘗試建置的架構。您可以在 OpenSSL `configure` 的步驟中找到日誌列： ``` [ 33%] Performing update step for 'project_libopenssl' -- Already at requested tag: OpenSSL_1_1_1t [ 44%] No patch step for 'project_libopenssl' [ 55%] Performing configure step for 'project_libopenssl' Operating system: x86_64-whatever-linux2 Configuring OpenSSL version 1.1.1t (0x1010114fL) for linux-x86_64 Using os-specific seed configuration Creating configdata.pm Creating Makefile ``` 驗證系統的架構： + 檢閱核心位元程度：執行 `uname -m` + 檢閱使用者空間位元：執行 `getconf LONG_BIT` 您也可以使用 `cat /proc/cpuinfo`或 `lscpu`命令檢閱 CPU 資訊。 **解決方法：** 若要解決此問題，請在建置時新增下列 CMake 引數，以確保 OpenSSL 針對 32 位元 ARM 架構正確建置： ``` -DBUILD_OPENSSL_PLATFORM=linux-armv4 ``` ## 對 GStreamer 中的`kvssink`載入問題進行故障診斷 確認 `GST_PLUGIN_PATH` 確保目前 Shell 工作階段中的`GST_PLUGIN_PATH`環境變數指向包含 的目錄`kvssink`。環境變數是工作階段特定的，因此您需要為每個新工作階段設定它們。若要讓此變更永久存在，請參閱「更新 shell 的啟動指令碼以包含設定 GST\$1PLUGIN\$1PATH 環境變數」。 **錯誤：無法開啟共用物件檔案：沒有此類檔案或目錄** 如果您遇到錯誤 `Cannot open shared object file: No such file or directory`，請執行下列命令： ``` gst-inspect-1.0 /path/to/libgstkvssink.so ``` 如果您收到下列輸出，表示動態連結器找不到 所需的程式庫`kvssink`。這通常是因為： + `kvssink` 移至與建置位置不同的位置。 + 交叉編譯錯誤的 CPU 架構。 + 缺少必要的相依性。 **輸出：** ``` WARNING: erroneous pipeline: no element "kvssink" error while loading shared libraries: libcproducer.so: cannot open shared object file: No such file or directory ``` **解決方法：** 對於**移動的程式庫**，請將包含遺失程式庫的目錄新增至 `LD_LIBRARY_PATH`。 從原始儲存庫的根目錄中，您可以使用 `find`公用程式來尋找遺失的程式庫。在終端機中，輸入： ``` find . -name "*libcproducer*" ``` **輸出：** ``` ./build/dependency/libkvscproducer/kvscproducer-src/libcproducer.so ``` Linux 裝置上的檔案路徑分隔符號為 `:`。以下命令會將新的資料夾路徑附加至現有的`LD_LIBRARY_PATH`環境變數，以保留任何先前的值。 在終端機中，輸入： ``` export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/build/dependency/libkvscproducer/kvscproducer-src ``` **重要** 環境變數是工作階段特定的。若要保留跨工作階段的變更，請修改 shell 的啟動指令碼。 您可能還需要將 `open-source/local/lib` 新增至您的 `$LD_LIBRARY_PATH`。 **錯誤：./path/to/libcproducer.so.1：無效的 ELF 標頭** 如果您在載入**共用程式庫**時收到此錯誤，可能是因為符號連結損壞 (`symlinks`)。如果主機機器的作業系統與目標機器的 作業系統不相符，Symlinks 可能會中斷。例如，Raspberry Pi 的 MacBook 上的交叉編譯。 另一個可能的原因是建置的二進位檔用於錯誤的架構。例如，如果二進位檔是針對 x86 建置的 (Raspberry Pi 使用 ARM CPUs)。 導覽至錯誤和類型中指定的程式庫位置： `ls -la`以檢查程式庫 `symlinks`。 **回應：** ``` drwxr-xr-x 16 me staff 512 Sep 10 17:16 . drwxr-xr-x 7 me staff 224 Jan 6 23:46 .. drwxr-xr-x 4 me staff 128 Sep 10 17:16 engines-1.1 -rwxr-xr-x 1 me staff 2294496 Sep 10 17:16 libcrypto.1.1.so -rw-r--r-- 1 me staff 4002848 Sep 10 17:16 libcrypto.a lrwxr-xr-x 1 me staff 19 Sep 10 17:16 libcrypto.so -> libcrypto.1.1.so -rwxr-xr-x 1 me staff 631176 Sep 10 17:12 liblog4cplus-2.0.3.so lrwxr-xr-x 1 me staff 24 Sep 10 17:12 liblog4cplus.so -> liblog4cplus-2.0.3.so -rwxr-xr-x 1 me staff 1012 Sep 10 17:12 liblog4cplus.a -rwxr-xr-x 1 me staff 694328 Sep 10 17:12 liblog4cplusU-2.0.3.so lrwxr-xr-x 1 me staff 25 Sep 10 17:12 liblog4cplusU.dylib -> liblog4cplusU-2.0.3.so -rwxr-xr-x 1 me staff 1017 Sep 10 17:12 liblog4cplusU.a -rwxr-xr-x 1 me staff 536416 Sep 10 17:16 libssl.1.1.so -rw-r--r-- 1 me staff 795184 Sep 10 17:16 libssl.a lrwxr-xr-x 1 me staff 16 Sep 10 17:16 libssl.so -> libssl.1.1.so drwxr-xr-x 6 me staff 192 Sep 10 17:16 pkgconfig ``` 在上述範例輸出中， `symlinks` 不會中斷。中斷`symlinks`不會有指向其目標的箭頭。 **解決方法：** 有兩種選項可以修正符號連結： + **建議：**`symlink`使用 `ln`命令重新建立 。類型： ``` ln -s /path/to/actual/library /path/to/symlink ``` + 複製實際的程式庫檔案，並將其重新命名以符合 `symlink`。 **注意** 此選項會導致儲存用量增加。 最佳實務是使用 Docker 等工具在相同的作業系統上編譯 ，以避免跨編譯問題。 **缺少相依性：** 如果缺少的程式庫名稱以 開頭`libkvs`，請參閱上面「移動的程式庫」一節，將 Kinesis Video Streams 程式庫從主機裝置安裝到目標裝置。 否則，請遵循 [安裝軟體先決條件](producersdk-cpp-rpi-software.md)以確保目標裝置上已安裝所有開放原始碼軟體先決條件。 # 錯誤碼參考 本節包含 [上傳至 Kinesis Video Streams](producer-sdk.md) 的錯誤碼與狀態碼資訊。 有關常見問題的解決方法，請參閱 [對 Kinesis Video Streams 進行故障診斷](troubleshooting.md)。 **Topics** + [PutFrame 回呼傳回的錯誤和狀態碼 - 平台獨立代碼 (PIC)](#producer-sdk-errors-putframe) + [PutFrame 回呼 - C 生產者程式庫傳回的錯誤和狀態碼](#producer-sdk-errors-putframe-c) ## PutFrame 回呼傳回的錯誤和狀態碼 - 平台獨立代碼 (PIC) 下列各節包含 平台獨立程式碼 (PIC) 內 `PutFrame` 操作的回呼所傳回的錯誤和狀態資訊。 **Topics** + [用戶端程式庫傳回的錯誤和狀態碼](#producer-sdk-errors-client) + [持續時間程式庫傳回的錯誤和狀態碼](#producer-sdk-errors-duration) + [常見程式庫傳回的錯誤和狀態碼](#producer-sdk-errors-common) + [堆積程式庫傳回的錯誤和狀態碼](#producer-sdk-errors-heap) + [MKVGen 程式庫傳回的錯誤和狀態碼](#producer-sdk-errors-mkvgen) + [追蹤程式庫傳回的錯誤和狀態碼](#producer-sdk-errors-trace) + [Utils 程式庫傳回的錯誤和狀態碼](#producer-sdk-errors-utils) + [檢視程式庫傳回的錯誤和狀態碼](#producer-sdk-errors-view) ### 用戶端程式庫傳回的錯誤和狀態碼 下表包含 Kinesis Video Streams `Client`程式庫中方法傳回的錯誤和狀態資訊。 **** | 代碼 | 訊息 | Description | 建議的動作 | | --- | --- | --- | --- | | 0x52000001 | STATUS\$1MAX\$1STREAM\$1COUNT | 已達串流次數上限。 | 請依照 [生產者開發套件配額](limits.md#producer-sdk-limits) 中說明之方式在 DeviceInfo 中指定較大的最高串流計數。 | | 0x52000002 | STATUS\$1MIN\$1STREAM\$1COUNT | 最低串流計數錯誤。 | 在 中指定大於零的串流數目上限DeviceInfo。 | | 0x52000003 | STATUS\$1INVALID\$1DEVICE\$1NAME\$1LENGTH | 無效裝置名稱長度。 | 請參閱 中指定的字元的最大裝置名稱長度[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x52000004 | STATUS\$1INVALID\$1DEVICE\$1INFO\$1VERSION | 無效的 DeviceInfo 架構版本。 | 指定正確的目前架構版本。 | | 0x52000005 | STATUS\$1MAX\$1TAG\$1COUNT | 已達標籤次數上限。 | 請參閱 中指定的目前最大標籤計數[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x52000006 | STATUS\$1DEVICE\$1FINGERPRINT\$1LENGTH | | 0x52000007 | STATUS\$1INVALID\$1CALLBACKS\$1VERSION | 無效的 Callbacks 架構版本。 | 指定正確的目前架構版本。 | | 0x52000008 | STATUS\$1INVALID\$1STREAM\$1INFO\$1VERSION | 無效的 StreamInfo 架構版本。 | 指定正確的目前架構版本。 | | 0x52000009 | STATUS\$1INVALID\$1STREAM\$1NAME\$1LENGTH | 無效串流名稱長度。 | 請參閱 中指定的字元的最大串流名稱長度[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x5200000a | STATUS\$1INVALID\$1STORAGE\$1SIZE | 指定了無效的儲存空間大小。 | 以位元表示的儲存空間大小需介於 [生產者開發套件配額](limits.md#producer-sdk-limits) 中所指定的上限內。 | | 0x5200000b | STATUS\$1INVALID\$1ROOT\$1DIRECTORY\$1LENGTH | 無效的根目錄字串長度。 | 請參閱 中指定的根目錄路徑長度上限[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x5200000c | STATUS\$1INVALID\$1SPILL\$1RATIO | 無效的溢出率。 | 以 0–100 的百分比表示溢出率。 | | 0x5200000d | STATUS\$1INVALID\$1STORAGE\$1INFO\$1VERSION | 無效的 StorageInfo 架構版本。 | 指定正確的目前架構版本。 | | 0x5200000e | STATUS\$1INVALID\$1STREAM\$1STATE | 串流的狀態不允許目前的操作。 | 最常見的情況是，當 SDK 無法達到執行請求的操作所需的狀態時，就會發生此錯誤。例如，如果 GetStreamingEndpoint API 呼叫失敗，且用戶端應用程式忽略該失敗並繼續將影格放入串流中，則會出現該錯誤。 | | 0x5200000f | STATUS\$1SERVICE\$1CALL\$1CALLBACKS\$1MISSING | 對於部分必要函數來說，Callbacks 架構含有遺失的函數入口點。 | 確認用戶端應用程式中已實作強制回呼。此錯誤只會向平台獨立程式碼 (PIC) 用戶端公開。C\$1\$1 和其他更高級別的包裝函式可滿足這些呼叫的要求。 | | 0x52000010 | STATUS\$1SERVICE\$1CALL\$1NOT\$1AUTHORIZED\$1ERROR | 未獲授權。 | 驗證安全字符、憑證、安全字符整合和過期。確認字符具有與其相關的正確權限。對於 Kinesis Video Streams 範例應用程式，請確認環境變數已正確設定。 | | 0x52000011 | STATUS\$1DESCRIBE\$1STREAM\$1CALL\$1FAILED | DescribeStreamAPI 失敗。 | 此錯誤會在 DescribeStream API 重試失敗後傳回。PIC 用戶端會在停止重試後傳回此錯誤。 | | 0x52000012 | STATUS\$1INVALID\$1DESCRIBE\$1STREAM\$1RESPONSE | 無效的 DescribeStreamResponse 架構。 | 傳遞到 DescribeStreamResultEvent 的架構會是 null 或者包含無效項目，例如 null 的 Amazon Resource Name (ARN)。 | | 0x52000013 | STATUS\$1STREAM\$1IS\$1BEING\$1DELETED\$1ERROR | 正在刪除的串流。 | 刪除串流時導致 API 失敗。確認沒有其他程序在使用串流時嘗試刪除串流。 | | 0x52000014 | STATUS\$1SERVICE\$1CALL\$1INVALID\$1ARG\$1ERROR | 服務呼叫指定了無效引數。 | 當服務呼叫引數無效，或 SDK 遇到無法解譯的錯誤時，後端會傳回此錯誤。 | | 0x52000015 | STATUS\$1SERVICE\$1CALL\$1DEVICE\$1NOT\$1FOUND\$1ERROR | 找不到該裝置。 | 確認在使用中時未刪除裝置。 | | 0x52000016 | STATUS\$1SERVICE\$1CALL\$1DEVICE\$1NOT\$1PROVISIONED\$1ERROR | 該裝置未佈建。 | 確認裝置已佈建。 | | 0x52000017 | STATUS\$1SERVICE\$1CALL\$1RESOURCE\$1NOT\$1FOUND\$1ERROR | 找不到該服務傳回的一般資源。 | 在服務找不到資源 (例如，串流) 時，將會出現該錯誤。它可能在不同上下文中具有不同的含意，但可能的原因是在建立串流之前使用 API。使用 SDK 會確認先建立串流。 | | 0x52000018 | STATUS\$1INVALID\$1AUTH\$1LEN | 無效授權資訊長度。 | 請參考 [生產者開發套件配額](limits.md#producer-sdk-limits) 中指定的目前數值。 | | 0x52000019 | STATUS\$1CREATE\$1STREAM\$1CALL\$1FAILED | CreateStream API 呼叫失敗。 | 有關操作失敗原因的詳細資訊，請參考錯誤字串。 | | 0x5200002a | STATUS\$1GET\$1STREAMING\$1TOKEN\$1CALL\$1FAILED | GetStreamingToken 呼叫失敗。 | 有關操作失敗原因的詳細資訊，請參考錯誤字串。 | | 0x5200002b | STATUS\$1GET\$1STREAMING\$1ENDPOINT\$1CALL\$1FAILED | GetStreamingEndpoint API 呼叫失敗。 | 有關操作失敗原因的詳細資訊，請參考錯誤字串。 | | 0x5200002c | STATUS\$1INVALID\$1URI\$1LEN | 從 GetStreamingEndpoint API 傳回了無效的 URI 字串長度。 | 請參考 [生產者開發套件配額](limits.md#producer-sdk-limits) 中指定的目前最高數值。 | | 0x5200002d | STATUS\$1PUT\$1STREAM\$1CALL\$1FAILED | PutMedia API 呼叫失敗。 | 有關操作失敗原因的詳細資訊，請參考錯誤字串。 | | 0x5200002e | STATUS\$1STORE\$1OUT\$1OF\$1MEMORY | 內容存放區大於記憶體容量。 | 內容存放區是在串流之間共用的，應具有足夠的容量以儲存所有串流的最大持續時間內的內容 \$1 \$120% (考慮磁碟重組)。請勿超出儲存空間。請選擇與累計儲存空間大小和容許的延遲所對應的每個串流的最大持續時間值。我們建議您捨棄影格，因為它們掉出內容檢視視窗，而不是只是被放置 （內容存放區記憶體壓力）。這是因為捨棄影格會啟動串流壓力通知回呼。然後，應用程式可以調整上游媒體元件 (如編碼器) 以降低位元速率，刪除影格或執行對應的操作。 | | 0x5200002f | STATUS\$1NO\$1MORE\$1DATA\$1AVAILABLE | 目前的串流沒有其他可用資料。 | 在媒體管道產生影格的速度比網路執行緒使用傳送到服務的影格的速度慢時，這可能是一個有效的結果。較高層級的用戶端 （例如 C\$1\$1、Java 或 Android) 不會看到此警告，因為它是在內部處理。 | | 0x52000030 | STATUS\$1INVALID\$1TAG\$1VERSION | 無效的 Tag 架構版本。 | 指定正確的目前架構版本。 | | 0x52000031 | STATUS\$1SERVICE\$1CALL\$1UNKNOWN\$1ERROR | 從網路堆疊中傳回未知或常規錯誤。 | 有關更詳細資訊，請參閱記錄。 | | 0x52000032 | STATUS\$1SERVICE\$1CALL\$1RESOURCE\$1IN\$1USE\$1ERROR | 資源使用中。 | 從服務傳回。如需詳細資訊，請參閱 Kinesis Video Streams API 參考。 | | 0x52000033 | STATUS\$1SERVICE\$1CALL\$1CLIENT\$1LIMIT\$1ERROR | 客戶端限制。 | 從服務傳回。如需詳細資訊，請參閱 Kinesis Video Streams API 參考。 | | 0x52000034 | STATUS\$1SERVICE\$1CALL\$1DEVICE\$1LIMIT\$1ERROR | 裝置限制。 | 從服務傳回。如需詳細資訊，請參閱 Kinesis Video Streams API 參考。 | | 0x52000035 | STATUS\$1SERVICE\$1CALL\$1STREAM\$1LIMIT\$1ERROR | 串流限制。 | 從服務傳回。如需詳細資訊，請參閱 Kinesis Video Streams API 參考。 | | 0x52000036 | STATUS\$1SERVICE\$1CALL\$1RESOURCE\$1DELETED\$1ERROR | 已刪除或正在刪除資源。 | 從服務傳回。如需詳細資訊，請參閱 Kinesis Video Streams API 參考。 | | 0x52000037 | STATUS\$1SERVICE\$1CALL\$1TIMEOUT\$1ERROR | 服務呼叫逾時。 | 呼叫特定服務 API 產生逾時。確認您具有有效的網路連線。PIC 會自動重試操作。 | | 0x52000038 | STATUS\$1STREAM\$1READY\$1CALLBACK\$1FAILED | 串流就緒通知。 | 該通知從 PIC 發送到客戶端，表示已建立非同步串流。 | | 0x52000039 | STATUS\$1DEVICE\$1TAGS\$1COUNT\$1NON\$1ZERO\$1TAGS\$1NULL | 指定了無效的標籤。 | 標籤計數不是零，但標籤是空的。確認標籤已指定或計數為零。 | | 0x5200003a | STATUS\$1INVALID\$1STREAM\$1DESCRIPTION\$1VERSION | 無效的 StreamDescription 架構版本。 | 指定正確的目前架構版本。 | | 0x5200003b | STATUS\$1INVALID\$1TAG\$1NAME\$1LEN | 無效標籤名稱長度。 | 請參考 [生產者開發套件配額](limits.md#producer-sdk-limits) 中指定的標籤名稱限制。 | | 0x5200003c | STATUS\$1INVALID\$1TAG\$1VALUE\$1LEN | 無效標籤值長度。 | 請參考 [生產者開發套件配額](limits.md#producer-sdk-limits) 中指定的標籤值限制。 | | 0x5200003d | STATUS\$1TAG\$1STREAM\$1CALL\$1FAILED | TagResource API 失敗。 | TagResource API 呼叫失敗。檢查是否有有效的網路連線。查看關於操作失敗的記錄詳細資訊。 | | 0x5200003e | STATUS\$1INVALID\$1CUSTOM\$1DATA | 無效的自訂資料呼叫 PIC API。 | 無效的自訂資料已在對 PIC API 的呼叫中指定。此情況只會在直接使用 PIC 的客戶端發生。 | | 0x5200003f | STATUS\$1INVALID\$1CREATE\$1STREAM\$1RESPONSE | 無效的 CreateStreamResponse 架構。 | 架構或其成員欄位無效 (也就是 ARN 為 null 或大於 [生產者開發套件配額](limits.md#producer-sdk-limits) 中指定的值)。 | | 0x52000040 | STATUS\$1CLIENT\$1AUTH\$1CALL\$1FAILED | 客戶端授權失敗。 | 多次重試後，PIC 無法取得適當的身分驗證資訊 (AccessKeyId 或 SecretAccessKey)。檢查身分驗證整合。範例應用程式使用環境變數將登入資料資訊傳入到 C\$1\$1 Producer Library。 | | 0x52000041 | STATUS\$1GET\$1CLIENT\$1TOKEN\$1CALL\$1FAILED | 取得安全字符呼叫失敗。 | 此情況只會在直接使用 PIC 的客戶端發生。在重試一定次數後，呼叫失敗並出現該錯誤。 | | 0x52000042 | STATUS\$1CLIENT\$1PROVISION\$1CALL\$1FAILED | 佈建錯誤。 | 佈建未實作。 | | 0x52000043 | STATUS\$1CREATE\$1CLIENT\$1CALL\$1FAILED | 無法建立製作者客戶端。 | 在客戶端建立失敗時，在重試一定次數後，PIC 會傳回一個一般錯誤。 | | 0x52000044 | STATUS\$1CLIENT\$1READY\$1CALLBACK\$1FAILED | 無法讓製作者用戶端成為「就緒」(Ready) 狀態。 | 若 PIC 無法移動為「就緒」(Ready) 狀態，將由 PIC 狀態機器傳回。查看關於根本原因的記錄詳細資訊。 | | 0x52000045 | STATUS\$1TAG\$1CLIENT\$1CALL\$1FAILED | 製作者客戶端的 TagResource 失敗。 | 製作者客戶端的 TagResource API 呼叫失敗。查看關於根本原因的記錄詳細資訊。 | | 0x52000046 | STATUS\$1INVALID\$1CREATE\$1DEVICE\$1RESPONSE | 裝置/製作者建立失敗。 | 高階 SDKs （例如 C\$1\$1 或 Java) 尚未實作裝置或生產者建立 API。直接使用 PIC 的客戶端可以使用結果通知來顯示操作失敗。 | | 0x52000047 | STATUS\$1ACK\$1TIMESTAMP\$1NOT\$1IN\$1VIEW\$1WINDOW | 在視圖中不顯示收到的 ACK 的時間戳記。 | 如果與收到的 ACK 對應的影格未位於內容視圖視窗中，則會出現該錯誤。通常，如果 ACK 傳送速率較慢就會發生這種情況。可以將其解釋為警告，並顯示下行線路速度較慢。 | | 0x52000048 | STATUS\$1INVALID\$1FRAGMENT\$1ACK\$1VERSION | 無效的 FragmentAck 架構版本。 | 指定正確的目前 FragmentAck 架構版本。 | | 0x52000049 | STATUS\$1INVALID\$1TOKEN\$1EXPIRATION | 無效的安全字符過期。 | 安全性字符過期應具有未來大於目前時間戳記的絕對時間戳記，並具有寬限期。對於寬限期的限制，請參閱 [生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x5200004a | STATUS\$1END\$1OF\$1STREAM | 串流結束 (EOS) 指標。 | 在 GetStreamData API 呼叫中，表示目前上傳處理工作階段已結束。如果工作階段結束或出現錯誤，或者工作階段字符已過期並且正在輪換工作階段，則會發生這種情況。 | | 0x5200004b | STATUS\$1DUPLICATE\$1STREAM\$1NAME | 重複的串流名稱。 | 多個串流不能具有相同的串流名稱。請為串流選擇專屬名稱。 | | 0x5200004c | STATUS\$1INVALID\$1RETENTION\$1PERIOD | 無效保留期間。 | StreamInfo 結構中指定了無效的保留期。關於保留期數值的有效範圍資訊，請參閱 [生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x5200004d | STATUS\$1INVALID\$1ACK\$1KEY\$1START | 無效的 FragmentAck。 | 無法解析區段 ACK 字串。無效的金鑰開始指標。區段 ACK 字串可能已損壞。它可以自行更正，並且可以將該錯誤視為警告。 | | 0x5200004e | STATUS\$1INVALID\$1ACK\$1DUPLICATE\$1KEY\$1NAME | 無效的 FragmentAck。 | 無法解析區段 ACK 字串。多個金鑰有相同的名稱。區段 ACK 字串可能已損壞。它可以自行更正，並且可以將該錯誤視為警告。 | | 0x5200004f | STATUS\$1INVALID\$1ACK\$1INVALID\$1VALUE\$1START | 無效的 FragmentAck。 | 因為無效的金鑰值開始指標而無法解析區段 ACK 字串。區段 ACK 字串可能已損壞。它可以自行更正，並且可以將該錯誤視為警告。 | | 0x52000050 | STATUS\$1INVALID\$1ACK\$1INVALID\$1VALUE\$1END | 無效的 FragmentAck。 | 因為無效的金鑰值結束指標而無法解析區段 ACK 字串。區段 ACK 字串可能已損壞。它可以自行更正，並且可以將該錯誤視為警告。 | | 0x52000051 | STATUS\$1INVALID\$1PARSED\$1ACK\$1TYPE | 無效的 FragmentAck。 | 因指定了無效的 ACK 類型，無法解析區段 ACK 字串。 | | 0x52000052 | STATUS\$1STREAM\$1HAS\$1BEEN\$1STOPPED | 串流已停止。 | 串流已停止，但影格仍放入串流中。 | | 0x52000053 | STATUS\$1INVALID\$1STREAM\$1METRICS\$1VERSION | 無效的 StreamMetrics 架構版本。 | 指定正確的目前 StreamMetrics 架構版本。 | | 0x52000054 | STATUS\$1INVALID\$1CLIENT\$1METRICS\$1VERSION | 無效的 ClientMetrics 架構版本。 | 指定正確的目前 ClientMetrics 架構版本。 | | 0x52000055 | STATUS\$1INVALID\$1CLIENT\$1READY\$1STATE | 製作者初始化無法達到「就緒」(Ready) 狀態。 | 無法在製作者客戶端初始化期間達到「就緒」(Ready) 狀態。查看記錄了解更多資訊。 | | 0x52000056 | STATUS\$1STATE\$1MACHINE\$1STATE\$1NOT\$1FOUND | 內部狀態機器錯誤。 | 不是公開顯示的錯誤。 | | 0x52000057 | STATUS\$1INVALID\$1FRAGMENT\$1ACK\$1TYPE | FragmentAck 結構中指定的無效 ACK 類型。 | FragmentAck 結構應包含公開標題中定義的 ACK 類型。 | | 0x52000058 | STATUS\$1INVALID\$1STREAM\$1READY\$1STATE | 內部狀態機器轉移錯誤。 | 不是公開顯示的錯誤。 | | 0x52000059 | STATUS\$1CLIENT\$1FREED\$1BEFORE\$1STREAM | 在釋放建立者後釋放串流對象。 | 嘗試在釋放製作者物件後釋放串流物件。只有在直接使用 PIC 的客戶端中可能會發生這種情況。 | | 0x5200005a | STATUS\$1ALLOCATION\$1SIZE\$1SMALLER\$1THAN\$1REQUESTED | 內部儲存空間錯誤。 | 內部錯誤，指出內容存放區的實際配置大小小於封裝影格和片段的大小。 | | 0x5200005b | STATUS\$1VIEW\$1ITEM\$1SIZE\$1GREATER\$1THAN\$1ALLOCATION | 內部儲存空間錯誤。 | 分配在內容視圖的儲存大小大於內容存放區中的分配大小。 | | 0x5200005c | STATUS\$1ACK\$1ERR\$1STREAM\$1READ\$1ERROR | 串流讀取錯誤 ACK。 | ACK 從後端傳回的錯誤，指出串流讀取或剖析錯誤。在後端無法擷取串流時，通常會發生這種情況。自動重新資料串流通常可以修正該錯誤。 | | 0x5200005d | STATUS\$1ACK\$1ERR\$1FRAGMENT\$1SIZE\$1REACHED | 已達最高區段大小上限。 | 以位元表示的最高區段大小定義於 [生產者開發套件配額](limits.md#producer-sdk-limits) 中。該錯誤表示具有非常大的影格，或者沒有用於建立可管理大小的區段的關鍵影格。檢查編碼器設定並確認已正確產生關鍵影格。對於具有較高密度的串流，請將編碼器配置以較小持續時間產生的區段以管理最大大小。 | | 0x5200005e | STATUS\$1ACK\$1ERR\$1FRAGMENT\$1DURATION\$1REACHED | 已達最高區段持續時間上限。 | 最高區段持續時間定義於 [生產者開發套件配額](limits.md#producer-sdk-limits) 中。該錯誤表示每秒具有非常小的影格，或者沒有用於建立可管理持續時間的區段的關鍵影格。檢查編碼器設定，並確認金鑰影格是否定期正確產生。 | | 0x5200005f | STATUS\$1ACK\$1ERR\$1CONNECTION\$1DURATION\$1REACHED | 已達最高連線持續時間上限。 | Kinesis Video Streams 會強制執行 中指定的最長連線持續時間[生產者開發套件配額](limits.md#producer-sdk-limits)。製作者開發套件會在達到上限之前自動輪換串流或字符。使用 SDK 的用戶端不應收到此錯誤。 | | 0x52000060 | STATUS\$1ACK\$1ERR\$1FRAGMENT\$1TIMECODE\$1NOT\$1MONOTONIC | 時間碼並非以單調遞增。 | Producer SDK 會強制執行時間戳記，因此使用 SDK 的用戶端不應收到此錯誤。 | | 0x52000061 | STATUS\$1ACK\$1ERR\$1MULTI\$1TRACK\$1MKV | 在 MKV 中的多個音軌。 | Producer SDK 會強制執行單一追蹤串流，因此使用 SDK 的用戶端不應收到此錯誤。 | | 0x52000062 | STATUS\$1ACK\$1ERR\$1INVALID\$1MKV\$1DATA | 無效的 MKV 資料。 | 後端 MKV 解析器在解析串流時遇到錯誤。如果轉換期間串流損毀，使用 SDK 的用戶端可能會遇到此錯誤。如果緩衝壓力強制 SDK 捨棄部分傳輸的尾影格，也會發生這種情況。在後一種情況下，我們建議您減少 FPS 和解析度、提高壓縮率，或 （如果有「爆量」網路） 允許較大的內容存放區和緩衝區持續時間，以適應暫時壓力。 | | 0x52000063 | STATUS\$1ACK\$1ERR\$1INVALID\$1PRODUCER\$1TIMESTAMP | 無效的製作者時間戳記。 | 如果製作者時鐘大幅漂移到將來的時間，服務將傳回該錯誤 ACK。更高級別的軟體開發套件 (例如，Java 或 C\$1\$1) 使用某種版本的系統時鐘以符合從 PIC 中回呼目前時間的要求。確認系統時鐘已正確設定。直接使用 PIC 的用戶端應驗證其回呼函數是否傳回正確的時間戳記。 | | 0x52000064 | STATUS\$1ACK\$1ERR\$1STREAM\$1NOT\$1ACTIVE | 閒置串流。 | 在串流未處於「使用中」狀態時，對後端 API 進行呼叫。如果客戶端建立串流並立即繼續將影格推入串流中，則會發生這種情況。軟體開發套件使用狀態機器和復原機制來處理這種情況。 | | 0x52000065 | STATUS\$1ACK\$1ERR\$1KMS\$1KEY\$1ACCESS\$1DENIED | AWS KMS 存取遭拒錯誤。 | 當帳戶沒有存取特定金鑰的權限時傳回。 | | 0x52000066 | STATUS\$1ACK\$1ERR\$1KMS\$1KEY\$1DISABLED | AWS KMS 金鑰已停用。 | 指定的金鑰已停用。 | | 0x52000067 | STATUS\$1ACK\$1ERR\$1KMS\$1KEY\$1VALIDATION\$1ERROR | AWS KMS 金鑰驗證錯誤。 | 一般驗證錯誤。如需詳細資訊，請參閱 [AWS Key Management Service API 參考](https://docs.aws.amazon.com/kms/latest/APIReference/)。 | | 0x52000068 | STATUS\$1ACK\$1ERR\$1KMS\$1KEY\$1UNAVAILABLE | AWS KMS key 無法使用。 | 金鑰無法使用。如需詳細資訊，請參閱 [AWS Key Management Service API 參考](https://docs.aws.amazon.com/kms/latest/APIReference/)。 | | 0x52000069 | STATUS\$1ACK\$1ERR\$1KMS\$1KEY\$1INVALID\$1USAGE | KMS 金鑰的使用無效。 | AWS KMS key 未設定為在此內容中使用。如需詳細資訊，請參閱 [AWS Key Management Service API 參考](https://docs.aws.amazon.com/kms/latest/APIReference/)。 | | 0x5200006a | STATUS\$1ACK\$1ERR\$1KMS\$1KEY\$1INVALID\$1STATE | AWS KMS 無效狀態。 | 如需詳細資訊，請參閱 [AWS Key Management Service API 參考](https://docs.aws.amazon.com/kms/latest/APIReference/)。 | | 0x5200006b | STATUS\$1ACK\$1ERR\$1KMS\$1KEY\$1NOT\$1FOUND | 找不到 KMS 金鑰。 | 找不到金鑰。如需詳細資訊，請參閱 [AWS Key Management Service API 參考](https://docs.aws.amazon.com/kms/latest/APIReference/)。 | | 0x5200006c | STATUS\$1ACK\$1ERR\$1STREAM\$1DELETED | 串流已被刪除或者正在刪除。 | 串流正由其他應用程式刪除或者透過 AWS 管理主控台刪除。 | | 0x5200006d | STATUS\$1ACK\$1ERR\$1ACK\$1INTERNAL\$1ERROR | 內部錯誤。 | 一般服務內部錯誤。 | | 0x5200006e | STATUS\$1ACK\$1ERR\$1FRAGMENT\$1ARCHIVAL\$1ERROR | 區段存檔錯誤。 | 在服務無法長期保留區段並為其編制索引時傳回。雖然非常少見，但可能會因為各種原因而發生此情況。預設情況下，軟體開發套件會再次嘗試發送區段。 | | 0x5200006f | STATUS\$1ACK\$1ERR\$1UNKNOWN\$1ACK\$1ERROR | 不明錯誤. | 此服務傳回了一個不明錯誤。 | | 0x52000070 | STATUS\$1MISSING\$1ERR\$1ACK\$1ID | 遺失的 ACK 資訊。 | ACK 解析器已完成解析，但是仍缺少 FragmentAck 資訊。 | | 0x52000071 | STATUS\$1INVALID\$1ACK\$1SEGMENT\$1LEN | 無效的 ACK 區段長度。 | 指定給 ACK 解析器的 ACK 區段字串為無效長度。如需詳細資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x52000074 | STATUS\$1MAX\$1FRAGMENT\$1METADATA\$1COUNT | 片段中繼資料項目新增數量已達上限。 | Kinesis 影片串流最多可以將 10 個中繼資料項目新增至片段，方法是將非持久性項目新增至片段，或將持久性項目新增至中繼資料佇列。如需詳細資訊，請參閱[搭配 Kinesis Video Streams 使用串流中繼資料](how-meta.md)。 | | 0x52000075 | STATUS\$1ACK\$1ERR\$1FRAGMENT\$1METADATA\$1LIMIT\$1REACHED | 已達上限 (中繼資料計數上限、中繼資料名稱長度上限、中繼資料數值長度上限)。 | 製作者開發套件會限制中繼資料項目的名稱與大小。除非 Producer SDK 程式碼中的限制變更，否則不會發生此錯誤。如需詳細資訊，請參閱[搭配 Kinesis Video Streams 使用串流中繼資料](how-meta.md)。 | | 0x52000076 | STATUS\$1BLOCKING\$1PUT\$1INTERRUPTED\$1STREAM\$1TERMINATED | 不實作。 | | | 0x52000077 | STATUS\$1INVALID\$1METADATA\$1NAME | 中繼資料名稱無效。 | 中繼資料名稱不能以字串 "AWS" 開頭。如果發生此錯誤，中繼資料項目不會新增至片段或中繼資料佇列。如需詳細資訊，請參閱[搭配 Kinesis Video Streams 使用串流中繼資料](how-meta.md)。 | | 0x52000078 | STATUS\$1END\$1OF\$1FRAGMENT\$1FRAME\$1INVALID\$1STATE | 片段影格的結尾為無效狀態。 | 片段結尾不應在non-key-frame分段串流中傳送。 | | 0x52000079 | STATUS\$1TRACK\$1INFO\$1MISSING | 遺失軌道資訊。 | 軌跡編號必須大於零，且符合軌跡 ID。 | | 0x5200007a | STATUS\$1MAX\$1TRACK\$1COUNT\$1EXCEEDED | 超過最大軌道數量。 | 每個串流最多可有三個音軌。 | | 0x5200007b | STATUS\$1OFFLINE\$1MODE\$1WITH\$1ZERO\$1RETENTION | 離線串流模式保留時間設定為零。 | 離線串流模式保留時間不應設定為零。 | | 0x5200007c | STATUS\$1ACK\$1ERR\$1TRACK\$1NUMBER\$1MISMATCH | 錯誤 ACK 的軌道編號不符。 | | | 0x5200007d | STATUS\$1ACK\$1ERR\$1FRAMES\$1MISSING\$1FOR\$1TRACK | 軌道遺漏影格。 | | | 0x5200007e | STATUS\$1ACK\$1ERR\$1MORE\$1THAN\$1ALLOWED\$1TRACKS\$1FOUND | 超過允許的軌道數量上限。 | | | 0x5200007f | STATUS\$1UPLOAD\$1HANDLE\$1ABORTED | 上傳處理中止。 | | | 0x52000080 | STATUS\$1INVALID\$1CERT\$1PATH\$1LENGTH | 無效的憑證路徑長度。 | | | 0x52000081 | STATUS\$1DUPLICATE\$1TRACK\$1ID\$1FOUND | 找到重複的軌道 ID。 | | | 0x52000082 | STATUS\$1INVALID\$1CLIENT\$1INFO\$1VERSION | | | | 0x52000083 | STATUS\$1INVALID\$1CLIENT\$1ID\$1STRING\$1LENGTH | | | | 0x52000084 | STATUS\$1SETTING\$1KEY\$1FRAME\$1FLAG\$1WHILE\$1USING\$1EOFR | | | | 0x52000085 | STATUS\$1MAX\$1FRAME\$1TIMESTAMP\$1DELTA\$1BETWEEN\$1TRACKS\$1EXCEEDED | | | | 0x52000086 | STATUS\$1STREAM\$1SHUTTING\$1DOWN | | | | 0x52000087 | STATUS\$1CLIENT\$1SHUTTING\$1DOWN | | | | 0x52000088 | STATUS\$1PUTMEDIA\$1LAST\$1PERSIST\$1ACK\$1NOT\$1RECEIVED | | | | 0x52000089 | STATUS\$1NON\$1ALIGNED\$1HEAP\$1WITH\$1IN\$1CONTENT\$1STORE\$1ALLOCATORS | | | | 0x5200008a | STATUS\$1MULTIPLE\$1CONSECUTIVE\$1EOFR | | | | 0x5200008b | STATUS\$1DUPLICATE\$1STREAM\$1EVENT\$1TYPE | | | | 0x5200008c | STATUS\$1STREAM\$1NOT\$1STARTED | | | | 0x5200008d | STATUS\$1INVALID\$1IMAGE\$1PREFIX\$1LENGTH | | | | 0x5200008e | STATUS\$1INVALID\$1IMAGE\$1METADATA\$1KEY\$1LENGTH | | | | 0x5200008f | STATUS\$1INVALID\$1IMAGE\$1METADATA\$1VALUE\$1LENGTH | | | ### 持續時間程式庫傳回的錯誤和狀態碼 下表包含程式`Duration`庫中方法傳回的錯誤和狀態資訊。 **** | 代碼 | 訊息 | | --- | --- | | 0xFFFFFFFFFFFFFFFF | INVALID\$1DURATION\$1VALUE | ### 常見程式庫傳回的錯誤和狀態碼 下表包含程式`Common`庫中方法傳回的錯誤和狀態資訊。 **注意** 這些錯誤與狀態資訊代碼常見於許多 API。 **** | Code | 沒有前導 0 的程式碼 | 訊息 | Description | | --- | --- | --- | --- | | 0x00000001 | 0x1 | STATUS\$1NULL\$1ARG | 為必要引數傳遞 NULL。 | | 0x00000002 | 0x2 | STATUS\$1INVALID\$1ARG | 為引數指定了無效的值。 | | 0x00000003 | 0x3 | STATUS\$1INVALID\$1ARG\$1LEN | 指定了無效的引數長度。 | | 0x00000004 | 0x4 | STATUS\$1NOT\$1ENOUGH\$1MEMORY | 無法配置足夠的記憶體。 | | 0x00000005 | 0x5 | STATUS\$1BUFFER\$1TOO\$1SMALL | 指定的緩衝大小太小。 | | 0x00000006 | 0x6 | STATUS\$1UNEXPECTED\$1EOF | 達到未預期的檔案結尾。 | | 0x00000007 | 0x7 | STATUS\$1FORMAT\$1ERROR | 遇到無效的格式。 | | 0x00000008 | 0x8 | STATUS\$1INVALID\$1HANDLE\$1ERROR | 無效的處理常式值。 | | 0x00000009 | 0x9 | STATUS\$1OPEN\$1FILE\$1FAILED | 無法開啟檔案。 | | 0x0000000a | 0xa | STATUS\$1READ\$1FILE\$1FAILED | 無法從檔案讀取。 | | 0x0000000b | 0xb | STATUS\$1WRITE\$1TO\$1FILE\$1FAILED | 無法寫入檔案。 | | 0x0000000c | 0xc | STATUS\$1INTERNAL\$1ERROR | 通常不會出現的內部錯誤，可能表示軟體開發套件或服務 API 錯誤。 | | 0x0000000d | 0xd | STATUS\$1INVALID\$1OPERATION | 具有無效的操作，或者不允許執行該操作。 | | 0x0000000e | 0xe | STATUS\$1NOT\$1IMPLEMENTED | 未套用功能。 | | 0x0000000f | 0xf | STATUS\$1OPERATION\$1TIMED\$1OUT | 此操作逾時。 | | 0x00000010 | 0x10 | STATUS\$1NOT\$1FOUND | 找不到需要的資源。 | | 0x00000011 | 0x11 | STATUS\$1CREATE\$1THREAD\$1FAILED | 無法建立執行緒。 | | 0x00000012 | 0x12 | STATUS\$1THREAD\$1NOT\$1ENOUGH\$1RESOURCES | 資源不足以建立另一個執行緒，或遇到系統對執行緒數量施加的限制。 | | 0x00000013 | 0x13 | STATUS\$1THREAD\$1INVALID\$1ARG | 指定的執行緒屬性無效，或另一個執行緒已等待加入此執行緒。 | | 0x00000014 | 0x14 | STATUS\$1THREAD\$1PERMISSIONS | 沒有許可來設定執行緒屬性中指定的排程政策和參數。 | | 0x00000015 | 0x15 | STATUS\$1THREAD\$1DEADLOCKED | 偵測到死結或聯結執行緒指定呼叫執行緒。 | | 0x00000016 | 0x16 | STATUS\$1THREAD\$1DOES\$1NOT\$1EXIST | 找不到具有指定執行緒 ID 的執行緒。 | | 0x00000017 | 0x17 | STATUS\$1JOIN\$1THREAD\$1FAILED | 從執行緒聯結操作傳回未知或一般錯誤。 | | 0x00000018 | 0x18 | STATUS\$1WAIT\$1FAILED | 超過等待條件式變數的時間上限。 | | 0x00000019 | 0x19 | STATUS\$1CANCEL\$1THREAD\$1FAILED | 從執行緒取消操作傳回未知或一般錯誤。 | | 0x0000001a | 0x1a | STATUS\$1THREAD\$1IS\$1NOT\$1JOINABLE | 在不可聯結的執行緒上請求執行緒聯結操作。 | | 0x0000001b | 0x1b | STATUS\$1DETACH\$1THREAD\$1FAILED | 從執行緒分離操作傳回未知或一般錯誤。 | | 0x0000001c | 0x1c | STATUS\$1THREAD\$1ATTR\$1INIT\$1FAILED | 無法初始化執行緒屬性物件。 | | 0x0000001d | 0x1d | STATUS\$1THREAD\$1ATTR\$1SET\$1STACK\$1SIZE\$1FAILED | 無法設定執行緒屬性物件的堆疊大小。 | | 0x0000001e | 0x1e | STATUS\$1MEMORY\$1NOT\$1FREED | 僅用於測試。表示尚未釋放所有請求的記憶體。 | | 0x0000001f | 0x1f | STATUS\$1INVALID\$1THREAD\$1PARAMS\$1VERSION | 無效的 "ThreadParams" 結構版本。指定正確的目前架構版本。 | ### 堆積程式庫傳回的錯誤和狀態碼 下表包含程式`Heap`庫中方法傳回的錯誤和狀態資訊。 **** | 代碼 | 訊息 | Description | | --- | --- | --- | | 0x10000001 | STATUS\$1HEAP\$1FLAGS\$1ERROR | 指定的標籤組合無效。 | | 0x10000002 | STATUS\$1HEAP\$1NOT\$1INITIALIZED | 堆積初始化前已嘗試操作。 | | 0x10000003 | STATUS\$1HEAP\$1CORRUPTED | 督機已損壞或已覆蓋保護頻寬 (在偵錯模式下)。客戶端代碼中的緩衝區溢位可能導致堆積損壞。 | | 0x10000004 | STATUS\$1HEAP\$1VRAM\$1LIB\$1MISSING | 無法載入或遺失 VRAM （影片 RAM) 使用者或核心模式程式庫。檢查基礎平台是否支援 VRAM 分配。 | | 0x10000005 | STATUS\$1HEAP\$1VRAM\$1LIB\$1REOPEN | 無法開啟 VRAM 程式庫。 | | 0x10000006 | STATUS\$1HEAP\$1VRAM\$1INIT\$1FUNC\$1SYMBOL | 無法載入 INIT 函數匯出。 | | 0x10000007 | STATUS\$1HEAP\$1VRAM\$1ALLOC\$1FUNC\$1SYMBOL | 無法載入 ALLOC 函數匯出。 | | 0x10000008 | STATUS\$1HEAP\$1VRAM\$1FREE\$1FUNC\$1SYMBOL | 無法載入 FREE 函數匯出。 | | 0x10000009 | STATUS\$1HEAP\$1VRAM\$1LOCK\$1FUNC\$1SYMBOL | 無法載入 LOCK 函數匯出。 | | 0x1000000a | STATUS\$1HEAP\$1VRAM\$1UNLOCK\$1FUNC\$1SYMBOL | 無法載入 UNLOCK 函數匯出。 | | 0x1000000b | STATUS\$1HEAP\$1VRAM\$1UNINIT\$1FUNC\$1SYMBOL | 無法載入 UNINIT 函數匯出。 | | 0x1000000c | STATUS\$1HEAP\$1VRAM\$1GETMAX\$1FUNC\$1SYMBOL | 無法載入 GETMAX 函數匯出。 | | 0x1000000d | STATUS\$1HEAP\$1DIRECT\$1MEM\$1INIT | 無法初始化在混合堆積中的主要堆積集區。 | | 0x1000000e | STATUS\$1HEAP\$1VRAM\$1INIT\$1FAILED | VRAM 動態初始化失敗。 | | 0x1000000f | STATUS\$1HEAP\$1LIBRARY\$1FREE\$1FAILED | 無法取消分配和釋放 VRAM 程式庫。 | | 0x10000010 | STATUS\$1HEAP\$1VRAM\$1ALLOC\$1FAILED | VRAM 分配失敗。 | | 0x10000011 | STATUS\$1HEAP\$1VRAM\$1FREE\$1FAILED | VRAM 釋放失敗。 | | 0x10000012 | STATUS\$1HEAP\$1VRAM\$1MAP\$1FAILED | VRAM 對應失敗。 | | 0x10000013 | STATUS\$1HEAP\$1VRAM\$1UNMAP\$1FAILED | VRAM 取消對應失敗。 | | 0x10000014 | STATUS\$1HEAP\$1VRAM\$1UNINIT\$1FAILED | VRAM 取消初始化失敗。 | | 0x10000015 | STATUS\$1INVALID\$1ALLOCATION\$1SIZE | | | 0x10000016 | STATUS\$1HEAP\$1REALLOC\$1ERROR | | | 0x10000017 | STATUS\$1HEAP\$1FILE\$1HEAP\$1FILE\$1CORRUPT | | ### MKVGen 程式庫傳回的錯誤和狀態碼 下表包含程式`MKVGen`庫中方法傳回的錯誤和狀態資訊。 **** | 代碼 | 訊息 | 描述/建議的動作 | | --- | --- | --- | | 0x32000001 | STATUS\$1MKV\$1INVALID\$1FRAME\$1DATA | Frame 資料結構的無效成員。請確定持續時間、大小和影格資料有效，且在 中指定的限制內[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x32000002 | STATUS\$1MKV\$1INVALID\$1FRAME\$1TIMESTAMP | 無效的影格時間戳記。計算的 PTS (簡報時間戳記) 和 DTS (解碼時間戳記) 大於或等於片段開始影格的時間戳記。這表示有潛在的媒體管道重新開機或編碼器穩定性問題。如需故障診斷資訊，請參閱 [錯誤：「無法將影格提交到 Kinesis Video 用戶端」](troubleshooting.md#troubleshooting-producer-failed-frame-client)。 | | 0x32000003 | STATUS\$1MKV\$1INVALID\$1CLUSTER\$1DURATION | 指定了無效的區段持續時間。如需詳細資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x32000004 | STATUS\$1MKV\$1INVALID\$1CONTENT\$1TYPE\$1LENGTH | 無效的內容類型字串長度。如需詳細資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x32000005 | STATUS\$1MKV\$1NUMBER\$1TOO\$1BIG | 嘗試編碼的數位太大，無法使用 EBML (可擴展二進位元語言) 格式表示。不會向軟體開發套件客戶端顯示該錯誤。 | | 0x32000006 | STATUS\$1MKV\$1INVALID\$1CODEC\$1ID\$1LENGTH | 無效的轉碼器 ID 字串長度。如需詳細資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x32000007 | STATUS\$1MKV\$1INVALID\$1TRACK\$1NAME\$1LENGTH | 無效的音軌名稱字串長度。如需詳細資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x32000008 | STATUS\$1MKV\$1INVALID\$1CODEC\$1PRIVATE\$1LENGTH | 無效的轉碼器私有資料長度。如需詳細資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x32000009 | STATUS\$1MKV\$1CODEC\$1PRIVATE\$1NULL | 轉碼器私有資料 (CPD) 為 NULL，而 CPD 大小大於零。 | | 0x3200000a | STATUS\$1MKV\$1INVALID\$1TIMECODE\$1SCALE | 時間碼比例值無效。如需詳細資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x3200000b | STATUS\$1MKV\$1MAX\$1FRAME\$1TIMECODE | 影格時間碼大於最大值。如需詳細資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x3200000c | STATUS\$1MKV\$1LARGE\$1FRAME\$1TIMECODE | 已達最高影格時間碼。MKV 格式使用有符號 16 位元表示影格相對於叢集開頭的時間碼。如果無法表示影格時間碼，則會產生錯誤。該錯誤表示選擇的時間碼比例不正確叢集持續時間太長，因此，表示影格時間碼將導致有符號 16 位元空間溢出。 | | 0x3200000d | STATUS\$1MKV\$1INVALID\$1ANNEXB\$1NALU\$1IN\$1FRAME\$1DATA | 遇到無效的 Annex-B 啟動代碼。例如，指定了 Annex-B 調節標記，且代碼遇到包含超過三個零的無效開始序列。有效的 Annex-B 格式應具有「模擬防護」序列，以便對位元組串流中包含三個或更多零的序列進行逸出。如需詳細資訊，請參閱 MPEG 規格。如需 Android 上此錯誤的詳細資訊，請參閱[在 Android 上發生 STATUS\$1MKV\$1INVALID\$1ANNEXB\$1NALU\$1IN\$1FRAME\$1DATA (0x3200000d) 錯誤](troubleshooting.md#troubleshooting-producer-android-invalid-annexb)。 | | 0x3200000e | STATUS\$1MKV\$1INVALID\$1AVCC\$1NALU\$1IN\$1FRAME\$1DATA | 指定調整 AVCC 旗標時，無效的 AVCC NALU 封裝。確認位元組串流是有效的 AVCC 格式。如需詳細資訊，請參閱 MPEG 規格。 | | 0x3200000f | STATUS\$1MKV\$1BOTH\$1ANNEXB\$1AND\$1AVCC\$1SPECIFIED | 已指定調整 AVCC 和 Annex-B NALUs。指定其中的一個 NAL，或者不指定任何 NAL。 | | 0x32000010 | STATUS\$1MKV\$1INVALID\$1ANNEXB\$1NALU\$1IN\$1CPD | 在指定了調節 Annex-B 標記時，CPD 的 Annex-B 格式無效。確認 CPD 為有效的 Annex-B 格式。如果不是，請移除 CPD Annex-B 適應旗標。 | | 0x32000011 | STATUS\$1MKV\$1PTS\$1DTS\$1ARE\$1NOT\$1SAME | Kinesis Video Streams 會強制執行片段開始影格的 PTS （呈現時間戳記） 和 DTS （解碼時間戳記） 相同。這些是區段開頭的關鍵影格。 | | 0x32000012 | STATUS\$1MKV\$1INVALID\$1H264\$1H265\$1CPD | 無法解析 H264/H265 轉碼器私有資料。 | | 0x32000013 | STATUS\$1MKV\$1INVALID\$1H264\$1H265\$1SPS\$1WIDTH | 無法從轉碼器私有資料中取得寬度。 | | 0x32000014 | STATUS\$1MKV\$1INVALID\$1H264\$1H265\$1SPS\$1HEIGHT | 無法從轉碼器私有資料中取得高度。 | | 0x32000015 | STATUS\$1MKV\$1INVALID\$1H264\$1H265\$1SPS\$1NALU | 無效的 H264/H265 SPS NALU。 | | 0x32000016 | STATUS\$1MKV\$1INVALID\$1BIH\$1CPD | 轉碼器私有資料中的點陣圖資訊標題格式無效。 | | 0x32000017 | STATUS\$1MKV\$1INVALID\$1HEVC\$1NALU\$1COUNT | 無效的高效能視訊編碼 (HEVC) 網路抽象層單元 (NALU) 計數。 | | 0x32000018 | STATUS\$1MKV\$1INVALID\$1HEVC\$1FORMAT | 無效的 HEVC 格式。 | | 0x32000019 | STATUS\$1MKV\$1HEVC\$1SPS\$1NALU\$1MISSING | 序列參數集 (SPS) 中缺少 HEVC NALU。 | | 0x3200001a | STATUS\$1MKV\$1INVALID\$1HEVC\$1SPS\$1NALU\$1SIZE | 無效的 HEVC SPS NALU 大小。 | | 0x3200001b | STATUS\$1MKV\$1INVALID\$1HEVC\$1SPS\$1CHROMA\$1FORMAT\$1IDC | 無效的 Chroma 格式 IDC。 | | 0x3200001c | STATUS\$1MKV\$1INVALID\$1HEVC\$1SPS\$1RESERVED | 無效的 HEVC 預留 SPS。 | | 0x3200001d | STATUS\$1MKV\$1MIN\$1ANNEX\$1B\$1CPD\$1SIZE | AnnexBb 轉碼器私有 Beta 值大小下限。對於 H264，此數值必須等於或大於 11。對於 H265，此數值必須等於或大於 15。 | | 0x3200001e | STATUS\$1MKV\$1ANNEXB\$1CPD\$1MISSING\$1NALUS | Annex-B NALU 中缺少轉碼器私有資料。 | | 0x3200001f | STATUS\$1MKV\$1INVALID\$1ANNEXB\$1CPD\$1NALUS | Annex-B NALU 中的轉碼器私有 beta 無效。 | | 0x32000020 | STATUS\$1MKV\$1INVALID\$1TAG\$1NAME\$1LENGTH | 無效標籤名稱長度。有效值為大於零並小於 128。 | | 0x32000021 | STATUS\$1MKV\$1INVALID\$1TAG\$1VALUE\$1LENGTH | 無效標籤值長度。有效值大於零且小於 256。 | | 0x32000022 | STATUS\$1MKV\$1INVALID\$1GENERATOR\$1STATE\$1TAGS | 無效的產生器狀態標籤。 | | 0x32000023 | STATUS\$1MKV\$1INVALID\$1AAC\$1CPD\$1SAMPLING\$1FREQUENCY\$1INDEX | 無效的 AAC 轉碼器私有資料取樣頻率索引。 | | 0x32000024 | STATUS\$1MKV\$1INVALID\$1AAC\$1CPD\$1CHANNEL\$1CONFIG | 無效的 AAC 轉碼器私有資料管道組態。 | | 0x32000025 | STATUS\$1MKV\$1INVALID\$1AAC\$1CPD | 無效的 AAC 轉碼器私有資料。 | | 0x32000026 | STATUS\$1MKV\$1TRACK\$1INFO\$1NOT\$1FOUND | 找不到軌道資訊。 | | 0x32000027 | STATUS\$1MKV\$1INVALID\$1SEGMENT\$1UUID | 無效的區段 UUID。 | | 0x32000028 | STATUS\$1MKV\$1INVALID\$1TRACK\$1UID | 無效的軌道 UID。 | | 0x32000029 | STATUS\$1MKV\$1INVALID\$1CLIENT\$1ID\$1LENGTH | | | 0x3200002a | STATUS\$1MKV\$1INVALID\$1AMS\$1ACM\$1CPD | | | 0x3200002b | STATUS\$1MKV\$1MISSING\$1SPS\$1FROM\$1H264\$1CPD | | | 0x3200002c | STATUS\$1MKV\$1MISSING\$1PPS\$1FROM\$1H264\$1CPD | | | 0x3200002d | STATUS\$1MKV\$1INVALID\$1PARENT\$1TYPE | | ### 追蹤程式庫傳回的錯誤和狀態碼 下表包含程式`Trace`庫中方法傳回的錯誤和狀態資訊。 **** | 代碼 | 訊息 | | --- | --- | | 0x10100001 | STATUS\$1MIN\$1PROFILER\$1BUFFER | ### Utils 程式庫傳回的錯誤和狀態碼 下表包含程式`Utils`庫中方法傳回的錯誤和狀態資訊。 **** | 代碼 | 訊息 | | --- | --- | | 0x40000001 | STATUS\$1INVALID\$1BASE64\$1ENCODE | | 0x40000002 | STATUS\$1INVALID\$1BASE | | 0x40000003 | STATUS\$1INVALID\$1DIGIT | | 0x40000004 | STATUS\$1INT\$1OVERFLOW | | 0x40000005 | STATUS\$1EMPTY\$1STRING | | 0x40000006 | STATUS\$1DIRECTORY\$1OPEN\$1FAILED | | 0x40000007 | STATUS\$1PATH\$1TOO\$1LONG | | 0x40000008 | STATUS\$1UNKNOWN\$1DIR\$1ENTRY\$1TYPE | | 0x40000009 | STATUS\$1REMOVE\$1DIRECTORY\$1FAILED | | 0x4000000a | STATUS\$1REMOVE\$1FILE\$1FAILED | | 0x4000000b | STATUS\$1REMOVE\$1LINK\$1FAILED | | 0x4000000c | STATUS\$1DIRECTORY\$1ACCESS\$1DENIED | | 0x4000000d | STATUS\$1DIRECTORY\$1MISSING\$1PATH | | 0x4000000e | STATUS\$1DIRECTORY\$1ENTRY\$1STAT\$1ERROR | | 0x4000000f | STATUS\$1STRFTIME\$1FALIED | | 0x40000010 | STATUS\$1MAX\$1TIMESTAMP\$1FORMAT\$1STR\$1LEN\$1EXCEEDED | | 0x40000011 | STATUS\$1UTIL\$1MAX\$1TAG\$1COUNT | | 0x40000012 | STATUS\$1UTIL\$1INVALID\$1TAG\$1VERSION | | 0x40000013 | STATUS\$1UTIL\$1TAGS\$1COUNT\$1NON\$1ZERO\$1TAGS\$1NULL | | 0x40000014 | STATUS\$1UTIL\$1INVALID\$1TAG\$1NAME\$1LEN | | 0x40000015 | STATUS\$1UTIL\$1INVALID\$1TAG\$1VALUE\$1LEN | | 0x4000002a | STATUS\$1EXPONENTIAL\$1BACKOFF\$1INVALID\$1STATE | | 0x4000002b | STATUS\$1EXPONENTIAL\$1BACKOFF\$1RETRIES\$1EXHAUSTED | | 0x4000002c | STATUS\$1THREADPOOL\$1MAX\$1COUNT | | 0x4000002d | STATUS\$1THREADPOOL\$1INTERNAL\$1ERROR | | 0x40100001 | STATUS\$1HASH\$1KEY\$1NOT\$1PRESENT | | 0x40100002 | STATUS\$1HASH\$1KEY\$1ALREADY\$1PRESENT | | 0x40100003 | STATUS\$1HASH\$1ENTRY\$1ITERATION\$1ABORT | | 0x41000001 | STATUS\$1BIT\$1READER\$1OUT\$1OF\$1RANGE | | 0x41000002 | STATUS\$1BIT\$1READER\$1INVALID\$1SIZE | | 0x41100001 | STATUS\$1TIMER\$1QUEUE\$1STOP\$1SCHEDULING | | 0x41100002 | STATUS\$1INVALID\$1TIMER\$1COUNT\$1VALUE | | 0x41100003 | STATUS\$1INVALID\$1TIMER\$1PERIOD\$1VALUE | | 0x41100004 | STATUS\$1MAX\$1TIMER\$1COUNT\$1REACHED | | 0x41100005 | STATUS\$1TIMER\$1QUEUE\$1SHUTDOWN | | 0x41200001 | STATUS\$1SEMAPHORE\$1OPERATION\$1AFTER\$1SHUTDOWN | | 0x41200002 | STATUS\$1SEMAPHORE\$1ACQUIRE\$1WHEN\$1LOCKED | | 0x41300001 | STATUS\$1FILE\$1LOGGER\$1INDEX\$1FILE\$1INVALID\$1SIZE | ### 檢視程式庫傳回的錯誤和狀態碼 下表包含程式`View`庫中方法傳回的錯誤和狀態資訊。 **** | 代碼 | 訊息 | Description | | --- | --- | --- | | 0x30000001 | STATUS\$1MIN\$1CONTENT\$1VIEW\$1ITEMS | 指定的內容視圖項目數無效。如需詳細資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x30000002 | STATUS\$1INVALID\$1CONTENT\$1VIEW\$1DURATION | 指定的內容視圖持續時間無效。如需詳細資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。 | | 0x30000003 | STATUS\$1CONTENT\$1VIEW\$1NO\$1MORE\$1ITEMS | 嘗試獲取的位置超過標題。 | | 0x30000004 | STATUS\$1CONTENT\$1VIEW\$1INVALID\$1INDEX | 指定的索引無效。 | | 0x30000005 | STATUS\$1CONTENT\$1VIEW\$1INVALID\$1TIMESTAMP | 具有無效的時間戳記，或者時間戳記發生重疊。影格解碼時間戳記應大於或等於前一個影格時間戳記，加上前一個影格持續時間：`DTS(n) >= DTS(n-1) \$1 Duration(n-1)`。此錯誤通常會指出「不穩定」的編碼器。編碼器會產生一組突發編碼影格，並且其時間戳記小於影格內的持續時間。或者，串流配置為使用軟體開發套件時間戳記，並且發送影格的速度比影格持續時間快。為了說明解決編碼器中的一些「抖動」問題，請在 StreamInfo.StreamCaps 架構中指定較小的影格持續時間。例如，如果串流為 25 FPS，則每個影格的持續時間為 40 毫秒。不過，若要處理編碼器「抖動」，建議您使用該影格持續時間的一半 (20 毫秒）。某些串流要求更精確地控制錯誤檢測時間。 | | 0x30000006 | STATUS\$1INVALID\$1CONTENT\$1VIEW\$1LENGTH | 指定的內容視圖項目資料長度無效。 | ## PutFrame 回呼 - C 生產者程式庫傳回的錯誤和狀態碼 下一節包含 C 生產者程式庫中 `PutFrame`操作的回呼所傳回的錯誤和狀態資訊。 **** | 代碼 | 訊息 | Description | 建議的動作 | | --- | --- | --- | --- | | 0x15000001 | STATUS\$1STOP\$1CALLBACK\$1CHAIN | 回呼鏈已停止。 | | | 0x15000002 | STATUS\$1MAX\$1CALLBACK\$1CHAIN | 已達到回呼鏈上限。 | | | 0x15000003 | STATUS\$1INVALID\$1PLATFORM\$1CALLBACKS\$1VERSION | 無效的 PlatformCallbacks 架構版本。 | 指定正確的目前架構版本。 | | 0x15000004 | STATUS\$1INVALID\$1PRODUCER\$1CALLBACKS\$1VERSION | 無效的 ProducerCallbacks 架構版本。 | 指定正確的目前架構版本。 | | 0x15000005 | STATUS\$1INVALID\$1STREAM\$1CALLBACKS\$1VERSION | 無效的 StreamCallbacks 架構版本。 | 指定正確的目前架構版本。 | | 0x15000006 | STATUS\$1INVALID\$1AUTH\$1CALLBACKS\$1VERSION | 無效的 AuthCallbacks 架構版本。 | 指定正確的目前架構版本。 | | 0x15000007 | STATUS\$1INVALID\$1API\$1CALLBACKS\$1VERSION | 無效的 ApiCallbacks 架構版本。 | 指定正確的目前架構版本。 | | 0x15000008 | STATUS\$1INVALID\$1AWS\$1CREDENTIALS\$1VERSION | 無效的 AwsCredentials 架構版本。 | 指定正確的目前架構版本。 | | 0x15000009 | STATUS\$1MAX\$1REQUEST\$1HEADER\$1COUNT | 已達到的請求標頭計數上限。 | | | 0x1500000a | STATUS\$1MAX\$1REQUEST\$1HEADER\$1NAME\$1LEN | 已達到請求標頭名稱長度上限。 | | | 0x1500000b | STATUS\$1MAX\$1REQUEST\$1HEADER\$1VALUE\$1LEN | 已達到請求標頭值長度上限。 | | | 0x1500000c | STATUS\$1INVALID\$1API\$1CALL\$1RETURN\$1JSON | 針對 API 呼叫傳回無效的 JSON。 | | | 0x1500000d | STATUS\$1CURL\$1INIT\$1FAILED | Curl 初始化失敗。 | | | 0x1500000e | STATUS\$1CURL\$1LIBRARY\$1INIT\$1FAILED | Curl lib 初始化失敗。 | | | 0x1500000f | STATUS\$1INVALID\$1DESCRIBE\$1STREAM\$1RETURN\$1JSON | 針對 DescribeStream 傳回無效的 JSON。 | | | 0x15000010 | STATUS\$1HMAC\$1GENERATION\$1ERROR | HMAC 產生錯誤。 | | | 0x15000011 | STATUS\$1IOT\$1FAILED | IoT 授權失敗。 | | | 0x15000012 | STATUS\$1MAX\$1ROLE\$1ALIAS\$1LEN\$1EXCEEDED | 已達到角色別名長度上限。 | 指定較短的別名長度。 | | 0x15000013 | STATUS\$1MAX\$1USER\$1AGENT\$1NAME\$1POSTFIX\$1LEN\$1EXCEEDED | 已達到代理程式名稱後置長度上限。 | | | 0x15000014 | STATUS\$1MAX\$1CUSTOM\$1USER\$1AGENT\$1LEN\$1EXCEEDED | 已達到客戶使用者代理程式長度上限。 | | | 0x15000015 | STATUS\$1INVALID\$1USER\$1AGENT\$1LENGTH | 無效的使用者代理程式長度。 | | | 0x15000016 | STATUS\$1INVALID\$1ENDPOINT\$1CACHING\$1PERIOD | 無效的端點快取期間。 | 指定少於 24 小時的快取期間。 | | 0x15000017 | STATUS\$1IOT\$1EXPIRATION\$1OCCURS\$1IN\$1PAST | IoT 過期時間戳記發生在過去。 | | | 0x15000018 | STATUS\$1IOT\$1EXPIRATION\$1PARSING\$1FAILED | IoT 過期剖析失敗。 | | | 0x15000019 | STATUS\$1DUPLICATE\$1PRODUCER\$1CALLBACK\$1FREE\$1FUNC | | | | 0x1500001a | STATUS\$1DUPLICATE\$1STREAM\$1CALLBACK\$1FREE\$1FUNC | | | | 0x1500001b | STATUS\$1DUPLICATE\$1AUTH\$1CALLBACK\$1FREE\$1FUNC | | | | 0x1500001c | STATUS\$1DUPLICATE\$1API\$1CALLBACK\$1FREE\$1FUNC | | | | 0x1500001d | STATUS\$1FILE\$1LOGGER\$1INDEX\$1FILE\$1TOO\$1LARGE | | | | 0x1500001e | STATUS\$1MAX\$1IOT\$1THING\$1NAME\$1LENGTH | | | | 0x1500001f | STATUS\$1IOT\$1CREATE\$1LWS\$1CONTEXT\$1FAILED | | | | 0x15000020 | STATUS\$1INVALID\$1CA\$1CERT\$1PATH | | | | 0x15000022 | STATUS\$1FILE\$1CREDENTIAL\$1PROVIDER\$1OPEN\$1FILE\$1FAILED | | | | 0x15000023 | STATUS\$1FILE\$1CREDENTIAL\$1PROVIDER\$1INVALID\$1FILE\$1LENGTH | | | | 0x15000024 | STATUS\$1FILE\$1CREDENTIAL\$1PROVIDER\$1INVALID\$1FILE\$1FORMAT | | | | 0x15000026 | STATUS\$1STREAM\$1BEING\$1SHUTDOWN | | | | 0x15000027 | STATUS\$1CLIENT\$1BEING\$1SHUTDOWN | | | | 0x15000028 | STATUS\$1CONTINUOUS\$1RETRY\$1RESET\$1FAILED | | | | 0x16000001 | STATUS\$1CURL\$1PERFORM\$1FAILED | CURL 傳回非成功代碼。 | 檢閱日誌以取得其他資訊。常見的 CURL 錯誤是「無法解析主機名稱」，請檢查裝置的網際網路連線。 另一個常見的錯誤是 403 錯誤代碼。這表示未正確建立或指定 IoT 憑證。檢查 IoT 憑證和許可的檔案路徑是否已正確設定。如需詳細資訊，請參閱[使用 控制對 Kinesis Video Streams 資源的存取 AWS IoT](how-iot.md)。 | | 0x16000002 | STATUS\$1IOT\$1INVALID\$1RESPONSE\$1LENGTH | 擷取 IoT 登入資料時收到 0 長度的回應。 | 檢閱 AWS 運作狀態儀表板，稍後再試一次。 | | 0x16000003 | STATUS\$1IOT\$1NULL\$1AWS\$1CREDS | 從 IoT 登入資料端點傳回的 JSON 不包含登入資料物件。 | 如需其他資訊，請參閱 JSON 中的「訊息」項目。 | | 0x16000004 | STATUS\$1IOT\$1INVALID\$1URI\$1LEN | 傳入擷取 IoT 登入資料函數的 URL 長度不介於 1 到 10，000 之間。 | 檢閱傳遞至此函數的 URL。 | | 0x16000005 | STATUS\$1TIMESTAMP\$1STRING\$1UNRECOGNIZED\$1FORMAT | JSON 中從擷取 IoT 登入資料的「過期」項目的格式不是：`YYYY-MM-DDTHH:mm:SSZ`。 | 檢閱 AWS 運作狀態儀表板，稍後再試一次。 | # 網路抽象層 (NAL) 適應性旗標參考 本節包含有關 `StreamInfo.NalAdaptationFlags` 列舉的可用旗標的資訊。 應用程式中的[基礎串流](https://en.wikipedia.org/wiki/Elementary_stream)可以是 **Annex-B** 或 **AVCC** 格式： + **Annex-B** 格式使用兩個位元組的零劃分 [NALU (網路抽象層單位)](https://en.wikipedia.org/wiki/Network_Abstraction_Layer#NAL_units)，後面跟隨一或三個位元組的零，然後是數位 *1* (稱為**起始碼**，例如 00000001)。 + **AVCC** 格式也對 NALU 進行了包裝，但每個 NALU 前都有一個表示 NALU 大小 (通常為 4 個位元組) 的值。 許多編碼器產生 Annex-B 位元串流格式。某些高階位元串流處理器 （例如播放引擎或 中的[媒體來源延伸 (MSE) ](https://en.wikipedia.org/wiki/Media_Source_Extensions)播放器 AWS 管理主控台) 會針對其影格使用 AVCC 格式。 轉碼器私有資料 (CPD) 為 H.264 轉碼器的 SPS/PPS (序列參數集/圖片參數集)，也可以採用 Annex-B 或 AVCC 格式。但是，對 CPD 而言，格式與前面描述的有所不同。 這些旗標告知軟體開發套件將 NALU 與影格資料和 CPD 的 AVCC 或 Annex-B 調節，如下所示： **** | 旗標 | 調節 | | --- | --- | | NAL\$1ADAPTATION\$1FLAG\$1NONE | 不適應。 | | NAL\$1ADAPTATION\$1ANNEXB\$1NALS | 將 Annex-B NALUs 調整為 AVCC NALUs。 | | NAL\$1ADAPTATION\$1AVCC\$1NALS | 將 AVCC NALUs 調整為 Annex-B NALUs。 | | NAL\$1ADAPTATION\$1ANNEXB\$1CPD\$1NALS | 將轉碼器私有資料的 Annex-B NALUs調整為 AVCC 格式 NALUs。 | | NAL\$1ADAPTATION\$1ANNEXB\$1CPD\$1AND\$1FRAME\$1NALS | 將轉碼器和影格私有資料的 Annex-B NALUs調整為 AVCC 格式 NALUs。 | 有關 NALU 類型的更多資訊，請參閱 **RFC 3984** 中的[第 1.3 節：網路抽象層單位類型](https://www.ietf.org/rfc/rfc3984.txt)。 # 生產者開發套件結構 本節包含您可以用來將資料提供給 Kinesis Video Streams Producer 物件的結構相關資訊。 **Topics** + [DeviceInfo/DefaultDeviceInfoProvider](#producer-reference-structures-producer-deviceinfo) + [StorageInfo](#producer-reference-structures-producer-storageinfo) ## DeviceInfo/DefaultDeviceInfoProvider **DeviceInfo** 和 **DefaultDeviceInfoProvider** 物件控制 Kinesis Video Streams Producer 物件的行為。 ### 成員欄位 + **版本** – 整數值，用來確保結構的正確版本與程式碼基底的目前版本搭配使用。目前版本指定使用 `DEVICE_INFO_CURRENT_VERSION` 巨集。 + **name** – 裝置的人類可讀名稱。 + **tagCount/tags** – 目前未使用。 + **streamCount** – 裝置可處理的串流數目上限。這將為最初指向串流物件的指標預先分配儲存空間，但實際串流物件會隨後建立。預設值為 16 的串流，但您可於檔案中更改 `DefaultDeviceInfoProvider.cpp` 此編號。 + **storageInfo**：描述主要儲存空間組態的物件。如需詳細資訊，請參閱[StorageInfo](#producer-reference-structures-producer-storageinfo)。 ## StorageInfo 指定 Kinesis Video Streams 主要儲存體的組態。 預設實施根據低區段快速堆積實施，此實作針對串流式處理進行最佳化。它使用 `MEMALLOC` 分配器，可以在指定平台上覆蓋。一些平台具有虛擬記憶體分配，沒有物理頁分配的支援。由於使用了記憶體，虛擬頁由實體頁提供支援。在儲存利用率偏低時，這會導致整體系統上的低記憶體壓力。 預設儲存空間大小根據以下公式計算。`DefragmentationFactor` 應設定為 1.2 (20%)。 ``` Size = NumberOfStreams * AverageFrameSize * FramesPerSecond * BufferDurationInSeconds * DefragmentationFactor ``` 在以下範例中，裝置具有音訊和視訊串流。音訊串流每秒採樣 512 次，平均樣本 100 位元組。視訊串流每秒 25 影格，平均樣本 10,000 位元組。每個串流有 3 分鐘的緩衝時間。 ``` Size = (512 * 100 * (3 * 60) + 25 * 10000 * (3 * 60)) * 1.2 = (9216000 + 45000000) * 1.2 = 65059200 = ~ 66MB. ``` 如果裝置有更多可用的記憶體，建議您將更多記憶體新增至儲存體，以避免嚴重分段。 確認儲存體大小足以容納高編碼複雜性 （因高動作而增加影格大小） 或頻寬低的所有串流的完整緩衝區。如果生產者達到記憶體壓力，它會發出儲存溢出壓力回呼 (`StorageOverflowPressureFunc`)。不過，當內容存放區中沒有可用的記憶體時，它會捨棄推送至 Kinesis Video Streams 的影格，並顯示錯誤 (`STATUS_STORE_OUT_OF_MEMORY = 0x5200002e`)。如需詳細資訊，請參閱[用戶端程式庫傳回的錯誤和狀態碼](producer-sdk-errors.md#producer-sdk-errors-client)。這也可能發生，如果應用程式無法使用確認 (ACK) 或 ACK 持續延遲。在這種情況下，緩衝區會在前一個影格開始捨棄之前填充至「緩衝持續時間」容量。 ### 成員欄位 + **版本** – 整數值，用來確保結構的正確版本與程式碼基底的目前版本搭配使用。 + **storageType** – `DEVICE_STORAGE_TYPE` 指定儲存體基礎備份和實作的列舉。目前僅支援的值為 `DEVICE_STORAGE_TYPE_IN_MEM`。未來的實作中將支援 `DEVICE_STORAGE_TYPE_HYBRID_FILE`，表示儲存空間退回到檔案支援的內容儲存空間。 + **storageSize** – 要預先配置的儲存體大小，以位元組為單位。最小配置為 10 MB，最大配置為 10 GB。(這會變更檔案支援內容的存放區的未來實作。) + **spillRatio** – 整數值，代表要從直接記憶體儲存類型 (RAM) 配置的儲存體百分比，而不是次要溢位儲存體 （檔案儲存）。目前未使用。 + **rootDirectory**：檔案支援的內容儲存空間所在目錄的路徑位置。目前未使用。 # Kinesis 影片串流結構 您可以使用下列結構，將資料提供給 Kinesis 影片串流的執行個體。 **Topics** + [StreamDefinition/StreamInfo](#producer-reference-structures-stream-streaminfo) + [ClientMetrics](#producer-reference-structures-stream-clientmetrics) + [StreamMetrics](#producer-reference-structures-stream-streammetrics) ## StreamDefinition/StreamInfo `StreamDefinition` 物件在 C\$1\$1 層中包裝 `StreamInfo` 物件於獨立於平台的代碼中，並提供建構函數中的某些預設值。 ### 成員欄位 **** | 欄位 | 資料類型 | Description | 預設值 | | --- | --- | --- | --- | | stream\$1name | string | 選用的串流名稱。如需更多關於串流名稱長度的資訊，請參閱[生產者開發套件配額](limits.md#producer-sdk-limits)。每個串流皆應有唯一的名稱。 | 如果未指定名稱，則會產生隨機的名稱。 | | retention\$1period | duration> | 串流的保留期間以秒為單位。指定 0 代表沒有保留。 | 3600 (一小時) | | tags | const map\$1 | 包含使用者資訊之金鑰值對的對應。如果串流已有一組標籤，則新標籤會附加到現有的一組標籤之後。 | 無標籤 | | kms\$1key\$1id | string | 用於加密串流的 AWS KMS 金鑰 ID。如需詳細資訊，請參閱[Kinesis Video Streams 中的資料保護](how-kms.md)。 | 預設 KMS 金鑰 (aws/kinesisvideo)。 | | streaming\$1type | STREAMING\$1TYPE 列舉 | 唯一支援的值為 STREAMING\$1TYPE\$1REALTIME。 | | | content\$1type | string | 串流的內容格式。Kinesis Video Streams 主控台可以 video/h264 格式播放內容。 | video/h264 | | max\$1latency | duration | 串流的最大延遲，以毫秒為單位。當緩衝持續時間超過此時間量時，會呼叫串流延遲壓力回呼 (如果指定)。指定 0 表示將不呼叫串流延遲壓力回呼。 | milliseconds::zero() | | fragment\$1duration | duration | 您要的片段持續時間，以秒為單位。此值與 key\$1frame\$1fragmentation 值結合使用。如果此值為 false，Kinesis Video Streams 會在超過此持續時間後，在金鑰影格上產生片段。例如，進階音訊編碼 (AAC) 音訊串流將每個影格做為關鍵影格。指定 key\$1frame\$1fragmentation = false 導致在經過此持續時間之後在關鍵影格上片段化，產生 2 秒的片段。 | 2 | | timecode\$1scale | duration | MKV 時間碼比例以毫秒為單位，這用於指定 MKV 叢集中影格的時間碼精細度。MKV 影格時間碼一律相對於叢集的開始。MKV 使用簽章的 16 位元值 (0-32767) 來代表時間碼在叢集 (片段) 中。確認框架時間碼可以使用指定的時間碼比例來表示。時間碼規模的預設值 1 毫秒可確保最大的影格，則可以代表 32767 毫秒 \$1= 32 秒。這是超過最大持續時間指定片段 [Amazon Kinesis Video Streams 服務配額](limits.md)為 10 秒。 | 1 | | key\$1frame\$1fragmentation | bool | 是否在關鍵影格上產生片段。如果為 true，則開發套件在每次關鍵影格出現時會產生片段的開始。如果為 false，Kinesis Video Streams 至少會等待 ，fragment\$1duration並在關鍵影格上產生新的片段。 | true | | frame\$1timecodes | bool | 是否使用影格時間碼或者使用目前時間回呼產生時間戳記。許多編碼器不會產生時間戳記的影格。因此false，指定此參數可確保影格在放入 Kinesis Video Streams 時加上時間戳記。 | true | | absolute\$1fragment\$1times | bool | Kinesis Video Streams 使用 MKV 作為其基礎封裝機制。有關影格的時間碼 MKV 規格嚴格的相對於叢集 (片段) 的開始。不過，在叢集的時間碼可以絕對或相對於串流的開始時間。如果時間戳記是相對的，PutMedia 服務 API 呼叫會使用可選的串流開始時間戳記並調節叢集時間戳記。該服務隨時儲存區段及其絕對時間戳記。 | true | | fragment\$1acks | bool | 是否接收應用程式層級片段 ACKs（確認）。 | true，表示軟體開發套件接收 ACK 並依此操作。 | | restart\$1on\$1error | bool | 是否在出現特定錯誤時重新啟動。 | true，表示在出現任何錯誤時開發套件將嘗試重新啟動串流。 | | recalculate\$1metrics | bool | 是否重新計算指標。每個擷取指標的呼叫可以重新計算這些值，以獲取最新的「執行中」值，這可能會產生較小的 CPU 影響。您可能需要設定為 false 在極低功耗/容量的裝置上以避免佔用 CPU 週期。否則，我們不建議使用 false做為此值。 | true | | nal\$1adaptation\$1flags | uint32\$1t | 指定網路抽象層單位 (NALU) 調節旗標。如果位元串流是 H.264 編碼，則在 NALU 中可以處理做為原始資料或封裝。這些可以為 Annex-B 或 AVCC 格式。大多數基本串流生產者和消費者 （讀取編碼器和解碼器） 都使用 Annex-B 格式，因為它具有優勢，例如錯誤復原。較高層級的系統使用 AVCC 格式的預設格式，適用於 MPEG、HLS、DASH 等。主控台播放使用瀏覽器的 MSE (Media Source Extensions) 來解碼和播放使用 AVCC 格式的串流。對於 H264 (以及對於 M-JPEG 和 H265)，開發套件提供自我調節功能。 許多基本串流採用以下格式。在此範例中，`Ab` 是 Annex-B 開始代碼 (001 或 0001)。 
Ab(Sps)Ab(Pps)Ab(I-frame)Ab(P/B-frame) Ab(P/B-frame)…. Ab(Sps)Ab(Pps)Ab(I-frame)Ab(P/B-frame) Ab(P/B-frame)
在 H.264 的情況下，轉碼器私有資料 (CPD) 位於 SPS （序列參數集） 和 PPS （圖片參數集） 參數中，並且可以適應 AVCC 格式。除非媒體管道讓 CPD 分開，應用程式可以從影格擷取 CPD。它可以透過尋找第一個 IDR 影格 （應包含 SPS 和 PPS)、擷取兩個 NALUs（即 `Ab(Sps)Ab(Pps)`)，並在 的 CPD 中設定它來執行此操作`StreamDefinition`。 如需詳細資訊，請參閱[網路抽象層 (NAL) 適應性旗標參考](producer-reference-nal.md)。 | 預設情況下，影格資料和編解碼器私有資料均為從 Annex-B 格式調節為 AVCC 格式。 | | frame\$1rate | uint32\$1t | 預期的影格率。此值用於更完善計算緩衝需求。 | 25 | | avg\$1bandwidth\$1bps | uint32\$1t | 串流的預期平均頻寬。此值用於更完善計算緩衝需求。 | 4 \$1 1024 \$1 1024 | | buffer\$1duration | duration | 串流緩衝持續時間，以秒為單位。SDK 會將內容存放區中的影格保留最多 buffer\$1duration，之後會隨著視窗向前移動而捨棄先前的影格。如果正在捨棄的影格尚未傳送至後端，則會呼叫捨棄的影格回呼。如果目前緩衝區持續時間大於 max\$1latency，則將呼叫延遲壓力回呼。收到片段持續 ACK 時，緩衝區會裁剪到下一個片段啟動。這表示其內容的已長期存放在雲端，所以不再需要在執行個體的本機裝置的內容儲存。 | 120 | | replay\$1duration | duration | 如果啟用重新啟動，則在錯誤期間向後滾動目前讀取器以重播的持續時間，以秒為單位。轉返操作將在緩衝開始時停止 (在剛啟動串流時或已出現持續的 ACK 時)。轉返嘗試停留在顯示片段開始的關鍵影格上。如果 ' 導致重新啟動的錯誤並未指示無效主機 （主機仍然有效，並在其內部緩衝區中包含影格資料），則轉返會在最後收到的 ACK 影格停止。它會將轉發到下一個金鑰影格，因為整個片段已存放在主機記憶體。 | 40 | | connection\$1staleness | duration | 如果 SDK 未收到緩衝 ACK，則會呼叫串流過時回呼的時間，以秒為單位。它表示正在從裝置傳送影格，但後端未確認它們。此條件表示在中間躍點或負載平衡器的連線已中斷。 | 30 | | codec\$1id | string | MKV 音軌的轉碼器 ID。 | V\$1MPEG4/ISO/AVC | | track\$1name | string | MKV 音軌名稱。 | kinesis\$1video | | codecPrivateData | unsigned char\$1 | 編解碼器私有資料 (CPD) 緩衝區。如果媒體管道在串流啟動之前具有 CPD 的相關資訊，則可以在 StreamDefinition.codecPrivateData 中發送。此時將複製位元，在建立串流的呼叫之後可以重新使用緩衝區或將其釋放。不過，如果資料在建立串流時無法使用，則可以在KinesisVideoStream.start(cpd)函數的其中一個過載中設定。 | null | | codecPrivateDataSize | uint32\$1t | 編解碼器私有資料緩衝區大小。 | 0 | ## ClientMetrics **ClientMetrics** 物件透過呼叫 `getKinesisVideoMetrics` 來填充。 ### 成員欄位 **** | 欄位 | 資料類型 | Description | | --- | --- | --- | | version | UINT32 | 結構的版本，在 CLIENT\$1METRICS\$1CURRENT\$1VERSION 巨集中定義。 | | contentStoreSize | UINT64 | 整體內容存放區大小，以位元組為單位。這是 DeviceInfo.StorageInfo.storageSize 中指定的值。 | | contentStoreAvailableSize | UINT64 | 目前可用的儲存大小，以位元組為單位。 | | contentStoreAllocatedSize | UINT64 | 目前配置的大小。由於內部記帳和內容存放區的實施，配置加上可用的大小應略小於總儲存空間的大小。 | | totalContentViewsSize | UINT64 | 所有串流的所有內容視圖的已分配記憶體大小。這不會計入儲存體大小。此記憶體使用 MEMALLOC 巨集分配，可以覆蓋該值以提供自訂分配器。 | | totalFrameRate | UINT64 | 在所有串流上觀察到的總影格率。 | | totalTransferRate | UINT64 | 在所有串流上觀察到的總串流速率，以每秒位元組數為單位。 | ## StreamMetrics 透過呼叫 ** 來填充 **StreamMetrics`getKinesisVideoMetrics` 物件。 ### 成員欄位 **** | 欄位 | 資料類型 | Description | | --- | --- | --- | | version | UINT32 | 結構的版本，在 STREAM\$1METRICS\$1CURRENT\$1VERSION 巨集中定義。 | | currentViewDuration | UINT64 | 累積影格的時間長度。在快速聯網案例中，此持續時間為零或影格持續時間 （正在傳輸影格時）。如果持續時間超過 中max\$1latency指定的持續時間StreamDefinition，則會在指定時呼叫串流延遲回呼。以 100 奈秒 (ns) 為單位指定持續時間，這是 PIC 層的預設時間單位。 | | overallViewDuration | UINT64 | 整體檢視持續時間。如果串流設定沒有 ACKs或持久性，此值會隨著影格放入 Kinesis 影片串流而增加，並等於 buffer\$1duration中的 StreamDefinition。啟用 ACKs並收到持續的 ACK 時，緩衝區會修剪為下一個金鑰影格。這是因為 ACK 時間戳記表示整個片段的開頭。以 100 奈秒 (ns) 為單位指定持續時間，這是 PIC 層的預設時間單位。 | | currentViewSize | UINT64 | 目前緩衝區的大小，以位元組為單位。 | | overallViewSize | UINT64 | 整體檢視大小，以位元組為單位。 | | currentFrameRate | UINT64 | 目前串流觀察到的影格率。 | | currentTransferRate | UINT64 | 目前串流觀察到的傳輸速率，以每秒位元組數為單位。 | # 生產者開發套件回呼 Amazon Kinesis Video Streams Producer SDK 中的類別和方法不會維護自己的程序。反之，他們會使用傳入的功能呼叫和事件來排程回呼與應用程式通訊。 有兩種呼模式應用程式可以使用與開發套件互動： + `CallbackProvider` – 此物件會將平台獨立程式碼 (PIC) 元件的每個回呼公開給應用程式。此模式允許完整的功能，但也表示實作必須處理所有公有 API 方法和在 C\$1\$1 層的簽章。 + [StreamCallbackProvider](#producer-reference-callbacks-streamcallbackprovider) 和 [ClientCallbackProvider](#producer-reference-callbacks-clientcallbackprovider) – 這些物件公開串流特定和用戶端特定回呼，而 SDK 的 C\$1\$1 層公開其餘回呼。這是與製作者開發套件互動偏好的回呼模式。 下圖說明回呼物件的物件模型： ![\[圖表顯示 Kinesis Video Streams 中生產者和消費者的互動。\]](http://docs.aws.amazon.com/zh_tw/kinesisvideostreams/latest/dg/images/callbacks-10.png) 在先前的圖表， `DefaultCallbackProvider` 從衍生的 `CallbackProvider` (公開在 PIC 的所有回呼) 和包含 `StreamCallbackProvider` 和 `ClientCallbackProvider`。 **Topics** + [ClientCallbackProvider](#producer-reference-callbacks-clientcallbackprovider) + [StreamCallbackProvider](#producer-reference-callbacks-streamcallbackprovider) + [ClientCallbacks 結構](#producer-reference-callbacks-clientcallbacks) + [要重試串流的回呼實作](#producer-reference-callbacks-retry) ## ClientCallbackProvider `ClientCallbackProvider` 用戶端層級回呼函數公開的物件。函數的詳細資訊說明在 [ClientCallbacks 結構](#producer-reference-callbacks-clientcallbacks) 節。 **回呼方法：** + `getClientReadyCallback` – 報告用戶端的就緒狀態。 + `getStorageOverflowPressureCallback` – 報告儲存溢出或壓力。此回呼稱為當儲存使用率低於 `STORAGE_PRESSURE_NOTIFICATION_THRESHOLD` 值，這是 5% 的整體儲存大小。如需詳細資訊，請參閱[StorageInfo](producer-reference-structures-producer.md#producer-reference-structures-producer-storageinfo)。 ## StreamCallbackProvider `StreamCallbackProvider` 串流層級回呼函數公開的物件。 **回呼方法：** + `getDroppedFragmentReportCallback`：報告捨棄的片段。 + `getDroppedFrameReportCallback` – 報告捨棄的影格。 + `getFragmentAckReceivedCallback` – 報告已接收串流的片段 ACK。 + `getStreamClosedCallback` – 報告串流關閉條件。 + `getStreamConnectionStaleCallback` – 報告過時的連線條件。在這種情況下，生產者正在將資料傳送至服務，但沒有收到確認。 + `getStreamDataAvailableCallback` – 報告資料可在串流中使用。 + `getStreamErrorReportCallback` – 報告串流錯誤條件。 + `getStreamLatencyPressureCallback` – 報告串流延遲條件，也就是當累積的緩衝區大小大於 `max_latency`值時。如需詳細資訊，請參閱[StreamDefinition/StreamInfo](producer-reference-structures-stream.md#producer-reference-structures-stream-streaminfo)。 + `getStreamReadyCallback`： –報告串流就緒條件。 + `getStreamUnderflowReportCallback` – 報告串流下溢條件。此函數目前未使用，並保留供日後使用。 如需原始程式碼詳細資訊 `StreamCallbackProvider`，請參閱 [StreamCallbackProvider.h](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/d1684599a141785752582c16264e3123866f3cf8/kinesis-video-producer/src/StreamCallbackProvider.h)。 ## ClientCallbacks 結構 此 `ClientCallbacks` 架構包含回呼函數進入點，當特定事件發生時的 PIC 呼叫。結構也包含版本資訊 `CALLBACKS_CURRENT_VERSION` 的欄位，以及 `customData` 欄位使用者定義資料回傳的個別回呼功能。 用戶端應用程式可以使用 `this` 指標 `custom_data` 欄位到對應成員函數的靜態 `ClientCallback` 函數在執行時間，如下列程式碼範例所示： ``` STATUS TestStreamCallbackProvider::streamClosedHandler(UINT64 custom_data, STREAM_HANDLE stream_handle, UINT64 stream_upload_handle) { LOG_INFO("Reporting stream stopped."); TestStreamCallbackProvider* streamCallbackProvider = reinterpret_cast (custom_data); streamCallbackProvider->streamClosedHandler(...); ``` **事件** | 函式 | 說明 | Type | | --- | --- | --- | | CreateDeviceFunc | 目前並未在後端實作。從 Java 或 C\$1\$1 呼叫時發生故障。其他用戶端執行平台特定的初始化。 | 後端 API | | CreateStreamFunc | 建立串流時呼叫。 | 後端 API | | DescribeStreamFunc | 呼叫 DescribeStream 時已呼叫。 | 後端 API | | GetStreamingEndpointFunc | 呼叫 GetStreamingEndpoint 時已呼叫。 | 後端 API | | GetStreamingTokenFunc | 呼叫 GetStreamingToken 時已呼叫。 | 後端 API | | PutStreamFunc | 呼叫 PutStream 時已呼叫。 | 後端 API | | TagResourceFunc | 呼叫 TagResource 時已呼叫。 | 後端 API | |   |   |   | | CreateMutexFunc | 建立同步互斥。 | 同步 | | FreeMutexFunc | 釋放互斥。 | 同步 | | LockMutexFunc | 鎖定同步互斥。 | 同步 | | TryLockMutexFunc | 嘗試鎖定互斥。目前並未實作。 | 同步 | | UnlockMutexFunc | 解除鎖定互斥。 | 同步 | |   |   |   | | ClientReadyFunc | 當用戶端進入就緒狀態時呼叫。 | 通知 | | DroppedFrameReportFunc | 當影格已刪除時報告。 | 通知 | | DroppedFragmentReportFunc | 當片段已刪除時報告。此函數目前未使用，並保留供日後使用。 | 通知 | | FragmentAckReceivedFunc | 當片段 ACK (緩衝、收到、保留和錯誤) 收到呼叫。 | 通知 | | StorageOverflowPressureFunc | 當儲存使用率低於 STORAGE\$1PRESSURE\$1NOTIFICATION\$1THRESHOLD 值時呼叫，這是定義為 5% 的整體儲存大小。 | 通知 | | StreamClosedFunc | 當呼叫最後位元串流的剩餘影格。 | 通知 | | StreamConnectionStaleFunc | 當串流輸入過時連線狀態時呼叫。在這個條件，是製作者傳送資料到服務但未收到確認。 | 通知 | | StreamDataAvailableFunc | 串流資料可用時呼叫。 | 通知 | | StreamErrorReportFunc | 出現串流錯誤時呼叫。在這個條件下的 PIC 自動關閉串流。 | 通知 | | StreamLatencyPressureFunc | 串流進入延遲條件時呼叫，這是當累計緩衝大小大於 max\$1latency 值。如需詳細資訊，請參閱[StreamDefinition/StreamInfo](producer-reference-structures-stream.md#producer-reference-structures-stream-streaminfo)。 | 通知 | | StreamReadyFunc | 當串流進入就緒狀態時呼叫。 | 通知 | | StreamUnderflowReportFunc | 此函數目前未使用，並保留供日後使用。 | 通知 | |   |   |   | | DeviceCertToTokenFunc | 傳回連線憑證為字符。 | 平台整合 | | GetCurrentTimeFunc | 傳回目前的時間。 | 平台整合 | | GetDeviceCertificateFunc | 傳回裝置憑證。此函數目前未使用，並保留供日後使用。 | 平台整合 | | GetDeviceFingerprintFunc | 傳回裝置指紋。此函數目前未使用，並保留供日後使用。 | 平台整合 | | GetRandomNumberFunc | 傳回一隨機編號介於 0 和 RAND\$1MAX之間。 | 平台整合 | | GetSecurityTokenFunc | 傳回傳遞給與後端 API 通訊之函數的安全性字符。此實作可指定序列化 AccessKeyId，SecretKeyId 以及工作階段字符。 | 平台整合 | | LogPrintFunc | 文字行日誌與標籤和日誌層級。如需詳細資訊，請參閱PlatformUtils.h。 | 平台整合 | 對於先前表格的平台整合功能，最後參數是一種 `ServiceCallContext` 架構，其中包含下列欄位： + `version`：此結構的版本。 + `callAfter`：絕對時間之後的呼叫函數。 + `timeout`：逾時在 100 奈米秒單位的操作。 + `customData`：使用者定義的值傳回用戶端。 + `pAuthInfo`：呼叫的登入資料。如需詳細資訊，請參閱下列 (`__AuthInfo`) 結構。 授權資訊提供使用的 `__AuthInfo` 結構，這可以是序列化登入資料或提供者特定身分驗證字符。此架構包含下列欄位： + `version`：此版本的 `__AuthInfo` 結構。 + `type`：`AUTH_INFO_TYPE` 數值定義登入資料類型 (憑證或安全字符)。 + `data`：位元組陣列包含身分驗證資訊。 + `size`：參數 `data` 的大小。 + `expiration`：登入資料在 100 奈米秒單位過期。 ## 要重試串流的回呼實作 Kinesis Video Producer SDK 提供透過回呼函數串流的狀態。我們建議您實作下列回呼機制，從串流期間遇到的任何暫時性網路問題中復原。 + **串流延遲壓力回呼** - 此回呼機制會在 SDK 遇到串流延遲條件時啟動。累積的緩衝大小大於 MAX\$1LATENCY 值時，就會發生這種情況。建立串流時，串流應用程式會將 MAX\$1LATENCY 設為 60 秒的預設值。此回呼的典型實作是重設連線。您可以視需要使用 [https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/kinesis-video-c-producer/src/source/StreamLatencyStateMachine.c](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/src/source/StreamLatencyStateMachine.c) 的範例實作。請注意，由於網路中斷，無法將未交付的影格存放在次要儲存中，以供回填。 + **串流過時回呼** - 當生產者可以將資料傳送至 Amazon Kinesis Data Streams 服務 （上行），但無法及時取得確認 （緩衝 ACK) 時 （預設為 60 秒），就會啟動此回呼。根據網路設定，串流延遲壓力回呼或串流過時回呼，或兩者都可以啟動。與串流延遲壓力回呼重試實作類似，典型實作是重設連線並開始新的串流連線。您可以視需要使用 [https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/src/source/ConnectionStaleStateMachine.c](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/src/source/ConnectionStaleStateMachine.c) 的範例實作。 + **串流錯誤回呼** - 當 SDK 在呼叫 KVS API 服務呼叫期間遇到網路連線逾時或其他錯誤時，就會啟動此回呼。 + **捨棄影格回呼** - 當儲存大小已滿時，由於網路速度緩慢或串流錯誤，會啟動此回呼。如果網路速度導致影格遺失，您可以增加儲存體大小、減少影片影格大小或影格速率以符合網路速度。 # 搭配 Kinesis Video Streams 使用串流中繼資料 您可以使用 Amazon Kinesis Video Streams 生產者 SDK，在 Kinesis 影片串流中的個別片段層級內嵌中繼資料。Kinesis Video Streams 中的中繼資料是可變的鍵/值對。您可以使用它來描述片段的內容、嵌入必須與實際片段一起傳輸的相關感應器讀數，或滿足其他自訂需求。中繼資料提供為 [GetMedia](API_dataplane_GetMedia.md) 或 [GetMediaForFragmentList](API_reader_GetMediaForFragmentList.md) API 操作的一部分。它會與片段一起存放，在整個串流保留期間。您的取用應用程式可以根據中繼資料使用 來讀取、處理和反應[使用剖析器程式庫監看攝影機的輸出](parser-library.md)。 中繼資料可以用兩種模式內嵌於串流中的片段： + **非持久性** – 您可以根據已發生的業務特定條件，將中繼資料一次性或臨時附加至串流中的片段。例如，智慧攝影機可偵測動作，並將中繼資料新增至包含動作的對應片段，再將片段傳送至其 Kinesis 影片串流。您可以將中繼資料套用至下列格式的片段中：`Motion = true`。 + **持久性** – 您可以根據持續的需求，將中繼資料附加至串流中的連續片段。例如，智慧攝影機會傳送與其傳送至其 Kinesis 影片串流之所有片段相關聯的目前經緯度座標。您可以將中繼資料套用至所有下列格式的片段中：`Lat = 47.608013N , Long = -122.335167W` 您可以根據應用程式的需求，同時在同一片段附加兩種模式的中繼資料。內嵌的中繼資料可能包括偵測到的物件、追蹤活動、GPS 座標等任何您欲附加至串流片段的自訂資料。中繼資料是以鍵值字串對編碼。 ## 將中繼資料新增至 Kinesis 影片串流 您新增至 Kinesis 影片串流的中繼資料會建模為 MKV 標籤，這些標籤會實作為鍵/值對。 中繼資料可以是*暫時性*，例如標記串流內的事件，或*持久性*，例如識別指定事件發生的片段。持久性中繼資料項目會保留，並套用至每個連續片段，直到取消為止。 **注意** 使用 [上傳至 Kinesis Video Streams](producer-sdk.md) 新增的中繼資料項目不同於以 [TagStream](API_TagStream.md)、[UntagStream](API_UntagStream.md)、[ListTagsForStream](API_ListTagsForStream.md) 執行的串流層級標記 API。 ### 串流中繼資料 API 您可以在生產者 SDK 中使用下列操作來實作串流中繼資料。 **Topics** + [PIC](#how-meta-api-pic) + [C\$1\$1 生產者 SDK](#how-meta-api-cpp) + [Java 生產者 SDK](#how-meta-api-java) + [持久性和非持久性中繼資料](#how-meta-api-persistence) #### PIC ``` PUBLIC_API STATUS putKinesisVideoFragmentMetadata(STREAM_HANDLE streamHandle, PCHAR name, PCHAR value, BOOL persistent); ``` #### C\$1\$1 生產者 SDK ``` /** * Appends a "tag" or metadata - a key/value string pair into the stream. */ bool putFragmentMetadata(const std::string& name, const std::string& value, bool persistent = true); ``` #### Java 生產者 SDK 您可以使用 Java 生產者 SDK，`MediaSource`使用 將中繼資料新增至 `MediaSourceSink.onCodecPrivateData`： ``` void onFragmentMetadata(final @Nonnull String metadataName, final @Nonnull String metadataValue, final boolean persistent) throws KinesisVideoException; ``` #### 持久性和非持久性中繼資料 對於非持久性中繼資料，您可以新增數個相同*​名稱*​的中繼資料項目。生產者 SDK 會收集中繼資料佇列中的中繼資料項目，直到它們在下一個片段前面。中繼資料項目套用至串流後，中繼資料佇列將清空。若要重複中繼資料，請再次呼叫 `putKinesisVideoFragmentMetadata` 或 `putFragmentMetadata`。 對於持久性中繼資料，生產者 SDK 會以與非持久性中繼資料相同的方式收集中繼資料佇列中的中繼資料項目。不過，中繼資料項目在加上下一個片段時，不會從佇列中移除。 呼叫 `putKinesisVideoFragmentMetadata`​ 或 `putFragmentMetadata`​，`persistent` 設定為 `true`，有以下行為： + 呼叫 API 將中繼資料項目放入佇列。佇列中的中繼資料項目將以 MKV 標籤新增至每個片段。 + 如先前新增的中繼資料項目覆寫另一項目，請以相同*​名稱*​不同*​數值*​呼叫 API。 + 若以空*數值*呼叫 API，將移除 (取消) 中繼資料佇列中的中繼資料項目。 # 搭配 Kinesis Video Streams 使用 IPv6 您可以設定 Kinesis Video Streams，以將 IPv6 用於控制平面和資料平面操作。這可讓您的應用程式透過雙堆疊端點，使用 IPv6 地址與 Kinesis Video Streams 服務通訊。 **注意** IPv6 支援需要特定的 SDK 版本和組態設定。確保您的 Kinesis Video Streams SDK 和 AWS SDK 版本支援 IPv6 雙堆疊端點。雙堆疊端點同時支援 IPv4 和 IPv6 流量，適用於某些區域中的某些 服務。 Kinesis Video Streams 透過生產者和消費者應用程式的雙堆疊端點支援 IPv6。您可以設定應用程式使用 IPv6 控制平面 API 呼叫和資料平面串流操作。 ## 設定適用於 IPv6 的 AWS SDK 如果您使用 AWS SDK 在生產設定中呼叫 Kinesis Video Streams 控制平面 APIs，您可以透過設定雙堆疊端點來啟用 IPv6。 AWS 開發套件提供多種標準化方法來啟用雙堆疊端點。 **重要** 啟用雙堆疊端點時，軟體開發套件會嘗試使用雙堆疊端點來提出網路請求。如果服務或區域不存在雙堆疊端點，則請求會失敗。 ### 使用環境變數 設定下列環境變數以啟用 IPv6 雙堆疊端點： ``` export AWS_USE_DUALSTACK_ENDPOINT=true ``` ### 使用 AWS 組態檔案 將下列設定新增至您的 AWS 組態檔案 (`~/.aws/config`)： ``` [default] use_dualstack_endpoint = true ``` ### 使用 JVM 系統屬性 （僅限 Java 和 Kotlin SDKs) 對於 Java 和 Kotlin 應用程式，設定下列 JVM 系統屬性： ``` -Daws.useDualstackEndpoint=true ``` 或以程式設計方式在您的 Java 程式碼中： ``` System.setProperty("aws.useDualstackEndpoint", "true"); ``` ### 開發套件支援 下列 AWS SDKs支援雙堆疊端點組態： | SDK | 支援 | 組態方法 | | --- | --- | --- | | AWS CLI v2 | 是 | 環境變數、組態檔案 | | 適用於 C\$1\$1 的 SDK | 是 | 環境變數、組態檔案 | | 適用於 Go V2 的 SDK (1.x) | 是 | 環境變數、組態檔案 | | 適用於 Java 2.x 的 SDK | 是 | 環境變數、組態檔案、JVM 屬性 | | 適用於 Java 1.x 的 SDK | 否 | 不支援 | | 適用於 JavaScript 3.x 的 SDK | 是 | 環境變數、組態檔案 | | 適用於 Python 的 SDK (Boto3) | 是 | 環境變數、組態檔案 | 設定雙堆疊端點之後，軟體 AWS 開發套件會在呼叫 Kinesis Video Streams 控制平面 APIs 時自動使用 IPv6 端點。 ## 設定適用於 IPv6 的 Kinesis Video Streams Producer SDK Kinesis Video Streams Producer SDK 為控制平面和資料平面操作提供 IPv6 組態選項。這些設定適用於 AWS SDK 雙堆疊端點組態。 ### 設定 C/C\$1\$1 Producer SDK 預設端點和 DNS 解析鏈是由 KVS Producer-C SDK 1.6.0 版實作。它會依序檢查您可以設定這些參數組態的每個位置，然後選取您設定的第一個。預先定義的序列如下： 如需 Producer SDKs 的詳細資訊，請參閱 [Producer SDK for C](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c)、[Producer SDK for C\$1\$1](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp) 和 [Producer SDK 相關主題](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk.html#producer-sdk-related-topics)。 #### 端點組態 1. 的 `controlPlaneUrl` 參數`createAbstractDefaultCallbacksProvider`。 1. 端點組態 CMake 參數：(`-DAWS_KVS_USE_LEGACY_ENDPOINT_ONLY=TRUE`、`-DAWS_KVS_USE_DUAL_STACK_ENDPOINT_ONLY=TRUE`) 1. 環境變數：(`export AWS_USE_DUALSTACK_ENDPOINT=TRUE`) + 如果 `AWS_USE_DUALSTACK_ENDPOINT`為 `TRUE`（不區分大小寫），則會使用雙堆疊端點。 1. 否則，將建構和使用舊版端點。 使用 2、3 和 4 時，會根據提供給 的區域來建構端點`createAbstractDefaultCallbacksProvider`。 #### DNS 篩選 KVS Producer SDK 會根據組態設定適當的`CURLOPT_IPRESOLVE`參數： 1. DNS 解析 CMake 參數：(`-DAWS_KVS_IPV4_ONLY=TRUE`、`-DAWS_KVS_IPV6_ONLY=TRUE`、`-DAWS_KVS_IPV4_AND_IPV6_ONLY=TRUE`) 1. 環境變數 (`export AWS_KVS_USE_IPV4=TRUE`、`export AWS_KVS_USE_IPV6=TRUE`) 1. 否則，將不會進行篩選。如果 DNS 傳回 IPv4 和 IPv6 IP 地址，則可以使用。 **注意** 如果 DNS 篩選設定設定為篩選 IPV6 IP 地址，但 SDK 組態是使用舊版端點 （傳回IPV4-only 的地址），則請求將會失敗。 C\$1\$1 Producer SDK 3.5.0 版使用 Producer-C SDK 1.6.0 進行 KVS API 呼叫。 ### 設定 GStreamer 外掛程式 GStreamer 外掛程式使用基礎 C Producer SDK，因此當您設定適用於 IPv6 的 C SDK 時，會自動處理 IPv6 組態，如先前所述。 不需要修改程式碼，只需使用 CMake 參數建置 SDK 或設定適當的環境變數，如上一節所述。 ### 資料平面端點解析 對於資料平面操作，請使用 `GetDataEndpoint` API 擷取適當的雙堆疊資料平面端點。服務會根據請求 URL 傳回對應的端點。 範例： + 如果對結尾為 的舊版端點提出 `GetDataEndpoint` API 請求`.amazonaws.com`，Kinesis Video Streams 會傳回結尾為 的舊版資料平面端點`.amazonaws.com`。 + 如果對以 結尾的雙堆疊端點提出 `GetDataEndpoint` API 請求`.api.aws`，Kinesis Video Streams 會傳回以 結尾的雙堆疊資料平面端點`.api.aws`。 ## 設定 IPv6 AWS CLI 的 如果您使用 AWS CLI 進行 Kinesis Video Streams 操作 （通常用於proof-of-concept工作），您可以透過設定雙堆疊端點來啟用 IPv6。 ### 使用環境變數 ``` export AWS_USE_DUALSTACK_ENDPOINT=true ``` ### 使用 AWS 組態檔案 將下列項目新增至您的 AWS CLI 組態檔案 (`~/.aws/config`)： ``` [default] use_dualstack_endpoint = true ``` ## 組態範例 ### C SDK 範例 若要以IPV6-only Producer-C SDK，並忽略環境變數組態，請使用下列命令來建置 SDK： ``` cmake .. -DAWS_KVS_USE_DUAL_STACK_ENDPOINT_ONLY=TRUE -DAWS_KVS_IPV6_ONLY=TRUE make -j ``` **注意** 如果您已建置 開發套件，則需要執行乾淨的建置。在執行建置命令之前，刪除現有的建置、開放原始碼和相依性資料夾。 ## 考量事項 ### 網路需求 + 確保您的網路基礎設施支援 IPv6 連線 + 確認您的安全群組和網路 ACLs IPv6 流量 + 從部署環境測試對 AWS IPv6 端點的連線 + 某些 區域中的某些服務可使用雙堆疊端點 - 驗證目標區域的可用性 ### 開發套件相容性 + 確保您使用的是支援的 AWS SDK 版本 + 適用於 Java 的 AWS SDK 1.x 不支援雙堆疊端點組態 + 對於適用於 Go 1.x (V1) 的 SDK，您必須啟用從組態檔案載入，才能使用共用的組態檔案設定 ### 測試和驗證 將IPv6-enabled Kinesis Video Streams 應用程式部署到生產環境之前： + 測試控制平面操作 （串流建立、刪除、列出） + 驗證資料平面操作 （影片擷取和取用） + 驗證網路環境中的效能和連線 + 執行 Canary 測試以確保一致的 IPv6 功能 + 雙堆疊端點無法使用時的測試容錯移轉行為 ## 受 IPv6 升級影響的客戶 當您為 Kinesis Video Streams 啟用 IPv6 時，有幾個區域可能需要更新現有的組態和政策，以確保持續功能。 ### IAM 政策和 IP 地址篩選 如果您在 IAM 使用者政策、角色政策或資源型政策中使用來源 IP 地址篩選，則需要更新這些政策以包含 IPv6 地址範圍。 **重要** 在 `IpAddress`或 `NotIpAddress`條件中使用 IPv4 CIDR 區塊的現有 IAM 政策不會自動使用 IPv6 地址。您必須明確新增 IPv6 範圍以維護存取控制。 IPv6 的 IAM 政策更新範例： ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "kinesisvideo:*", "Resource": "*", "Condition": { "IpAddress": { "aws:SourceIp": [ "192.0.2.0/24", "203.0.113.0/24", "2001:db8::/32" ] } } } ] } ``` ### 日誌記錄和監控 IPv6 地址的格式與 IPv4 地址不同，這可能會影響您的記錄、監控和分析系統。 #### 日誌 當透過 IPv6 提出請求時， 日誌會在 `sourceIPAddress` 欄位中包含 IPv6 地址。更新您的日誌剖析工具和指令碼，以處理 IPv6 地址格式。 日誌中 IPv6 地址的範例： ``` { "sourceIPAddress": "2001:db8::1", "eventName": "CreateStream", "eventSource": "kinesisvideo.amazonaws.com" } ``` ## 疑難排解 ### 常見問題 + 連線失敗 – 驗證 IPv6 網路連線和 DNS 解析 + SDK 錯誤 – 確保您使用的是支援雙堆疊端點的相容 SDK 版本 + 身分驗證問題 – 確認 IAM 政策和登入資料可與 IPv6 端點搭配使用 + 端點無法使用 – 如果服務或區域不存在雙堆疊端點，則請求會失敗 ### 驗證步驟 + 檢查 `AWS_USE_DUALSTACK_ENDPOINT=true` 是否已在您的組態檔案中設定`use_dualstack_endpoint = true`或 + 確認 Kinesis Video Streams SDK IPv6 組態旗標已正確設定 + 測試 AWS IPv6 端點的網路連線能力 + 檢閱應用程式日誌是否有 IPv6-specific錯誤訊息 + 確認您的區域支援 Kinesis Video Streams 的雙堆疊端點 ### 組態驗證 您可以檢查以下項目來驗證雙堆疊端點組態： + 環境變數： `echo $AWS_USE_DUALSTACK_ENDPOINT` + AWS 組態檔案： `cat ~/.aws/config | grep use_dualstack_endpoint` + JVM 屬性 (Java)：檢查應用程式日誌中的系統屬性