/* * Copyright 2010-2022 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). * You may not use this file except in compliance with the License. * A copy of the License is located at * * http://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. This file is distributed * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either * express or implied. See the License for the specific language governing * permissions and limitations under the License. */ package com.amazonaws.services.kinesisvideoarchivedmedia; import java.util.*; import com.amazonaws.*; import com.amazonaws.auth.*; import com.amazonaws.handlers.*; import com.amazonaws.http.*; import com.amazonaws.internal.*; import com.amazonaws.metrics.*; import com.amazonaws.transform.*; import com.amazonaws.util.*; import com.amazonaws.util.AWSRequestMetrics.Field; import com.amazonaws.services.kinesisvideoarchivedmedia.model.*; import com.amazonaws.services.kinesisvideoarchivedmedia.model.transform.*; /** * Client for accessing Amazon Kinesis Video Streams Archived Media. All service * calls made using this client are blocking, and will not return until the * service call completes. *

*

*/ public class AWSKinesisVideoArchivedMediaClient extends AmazonWebServiceClient implements AWSKinesisVideoArchivedMedia { /** Provider for AWS credentials. */ private AWSCredentialsProvider awsCredentialsProvider; /** * List of exception unmarshallers for all Amazon Kinesis Video Streams * Archived Media exceptions. */ protected List jsonErrorUnmarshallers; /** * Constructs a new client to invoke service methods on * AWSKinesisVideoArchivedMedia. A credentials provider chain will be used * that searches for credentials in this order: *

*

* All service calls made using this new client object are blocking, and * will not return until the service call completes. * * @see DefaultAWSCredentialsProviderChain */ @Deprecated public AWSKinesisVideoArchivedMediaClient() { this(new DefaultAWSCredentialsProviderChain(), new ClientConfiguration()); } /** * Constructs a new client to invoke service methods on * AWSKinesisVideoArchivedMedia. A credentials provider chain will be used * that searches for credentials in this order: *

*

* All service calls made using this new client object are blocking, and * will not return until the service call completes. * * @param clientConfiguration The client configuration options controlling * how this client connects to AWSKinesisVideoArchivedMedia (ex: * proxy settings, retry counts, etc.). * @see DefaultAWSCredentialsProviderChain */ @Deprecated public AWSKinesisVideoArchivedMediaClient(ClientConfiguration clientConfiguration) { this(new DefaultAWSCredentialsProviderChain(), clientConfiguration); } /** * Constructs a new client to invoke service methods on * AWSKinesisVideoArchivedMedia using the specified AWS account credentials. *

* The client requests are authenticated using the {@link AWSCredentials} * provided in this constructor. Static AWSCredentials can be passed for * quick testing. However, it is strongly recommended to use Amazon Cognito * vended temporary credentials for use in production. This can be achieved * by using {@link AWSMobileClient}. Please see * https://aws-amplify.github.io/docs/android/authentication for * instructions on how to enable {@link AWSMobileClient}. * *

     * AWSMobileClient.getInstance().initialize(getApplicationContext(), new Callback<UserStateDetails>() {
     *     @Override
     *     public void onResult(final UserStateDetails details) {
     *         AWSKinesisVideoArchivedMediaClient client = new AWSKinesisVideoArchivedMediaClient(
     *                 AWSMobileClient.getInstance());
     *     }
     * 
     *     @Override
     *     public void onError(final Exception e) {
     *         e.printStackTrace();
     *     }
     * });
     * 
*

* All service calls made using this new client object are blocking, and * will not return until the service call completes. * * @param awsCredentials The AWS credentials (access key ID and secret key) * to use when authenticating with AWS services. */ public AWSKinesisVideoArchivedMediaClient(AWSCredentials awsCredentials) { this(awsCredentials, new ClientConfiguration()); } /** * Constructs a new client to invoke service methods on * AWSKinesisVideoArchivedMedia using the specified AWS account credentials * and client configuration options. *

* The client requests are authenticated using the {@link AWSCredentials} * provided in this constructor. Static AWSCredentials can be passed for * quick testing. However, it is strongly recommended to use Amazon Cognito * vended temporary credentials for use in production. This can be achieved * by using {@link AWSMobileClient}. Please see * https://aws-amplify.github.io/docs/android/authentication for * instructions on how to enable {@link AWSMobileClient}. * *

     * AWSMobileClient.getInstance().initialize(getApplicationContext(), new Callback<UserStateDetails>() {
     *     @Override
     *     public void onResult(final UserStateDetails details) {
     *         AWSKinesisVideoArchivedMediaClient client = new AWSKinesisVideoArchivedMediaClient(
     *                 AWSMobileClient.getInstance());
     *     }
     * 
     *     @Override
     *     public void onError(final Exception e) {
     *         e.printStackTrace();
     *     }
     * });
     * 
*

* All service calls made using this new client object are blocking, and * will not return until the service call completes. * * @param awsCredentials The AWS credentials (access key ID and secret key) * to use when authenticating with AWS services. * @param clientConfiguration The client configuration options controlling * how this client connects to AWSKinesisVideoArchivedMedia (ex: * proxy settings, retry counts, etc.). */ public AWSKinesisVideoArchivedMediaClient(AWSCredentials awsCredentials, ClientConfiguration clientConfiguration) { this(new StaticCredentialsProvider(awsCredentials), clientConfiguration); } /** * Constructs a new client to invoke service methods on * AWSKinesisVideoArchivedMedia using the specified AWS account credentials * provider. *

* The client requests are authenticated using the {@link AWSCredentials} * provided by the {@link AWSCredentialsProvider}. Static AWSCredentials can * be passed for quick testing. However, it is strongly recommended to use * Amazon Cognito vended temporary credentials for use in production. This * can be achieved by using {@link AWSMobileClient}. Please see * https://aws-amplify.github.io/docs/android/authentication for * instructions on how to enable {@link AWSMobileClient}. * *

     * AWSMobileClient.getInstance().initialize(getApplicationContext(), new Callback<UserStateDetails>() {
     *     @Override
     *     public void onResult(final UserStateDetails details) {
     *         AWSKinesisVideoArchivedMediaClient client = new AWSKinesisVideoArchivedMediaClient(
     *                 AWSMobileClient.getInstance());
     *     }
     * 
     *     @Override
     *     public void onError(final Exception e) {
     *         e.printStackTrace();
     *     }
     * });
     * 
*

* All service calls made using this new client object are blocking, and * will not return until the service call completes. * * @param awsCredentialsProvider The AWS credentials provider which will * provide credentials to authenticate requests with AWS * services. */ public AWSKinesisVideoArchivedMediaClient(AWSCredentialsProvider awsCredentialsProvider) { this(awsCredentialsProvider, new ClientConfiguration()); } /** * Constructs a new client to invoke service methods on * AWSKinesisVideoArchivedMedia using the specified AWS account credentials * provider and client configuration options. *

* The client requests are authenticated using the {@link AWSCredentials} * provided by the {@link AWSCredentialsProvider}. Static AWSCredentials can * be passed for quick testing. However, it is strongly recommended to use * Amazon Cognito vended temporary credentials for use in production. This * can be achieved by using {@link AWSMobileClient}. Please see * https://aws-amplify.github.io/docs/android/authentication for * instructions on how to enable {@link AWSMobileClient}. * *

     * AWSMobileClient.getInstance().initialize(getApplicationContext(), new Callback<UserStateDetails>() {
     *     @Override
     *     public void onResult(final UserStateDetails details) {
     *         AWSKinesisVideoArchivedMediaClient client = new AWSKinesisVideoArchivedMediaClient(
     *                 AWSMobileClient.getInstance());
     *     }
     * 
     *     @Override
     *     public void onError(final Exception e) {
     *         e.printStackTrace();
     *     }
     * });
     * 
*

* All service calls made using this new client object are blocking, and * will not return until the service call completes. * * @param awsCredentialsProvider The AWS credentials provider which will * provide credentials to authenticate requests with AWS * services. * @param clientConfiguration The client configuration options controlling * how this client connects to AWSKinesisVideoArchivedMedia (ex: * proxy settings, retry counts, etc.). */ public AWSKinesisVideoArchivedMediaClient(AWSCredentialsProvider awsCredentialsProvider, ClientConfiguration clientConfiguration) { this(awsCredentialsProvider, clientConfiguration, new UrlHttpClient(clientConfiguration)); } /** * Constructs a new client to invoke service methods on * AWSKinesisVideoArchivedMedia using the specified AWS account credentials * provider, client configuration options and request metric collector. *

* All service calls made using this new client object are blocking, and * will not return until the service call completes. * * @param awsCredentialsProvider The AWS credentials provider which will * provide credentials to authenticate requests with AWS * services. * @param clientConfiguration The client configuration options controlling * how this client connects to AWSKinesisVideoArchivedMedia (ex: * proxy settings, retry counts, etc.). * @param requestMetricCollector optional request metric collector */ @Deprecated public AWSKinesisVideoArchivedMediaClient(AWSCredentialsProvider awsCredentialsProvider, ClientConfiguration clientConfiguration, RequestMetricCollector requestMetricCollector) { super(adjustClientConfiguration(clientConfiguration), requestMetricCollector); this.awsCredentialsProvider = awsCredentialsProvider; init(); } /** * Constructs a new client to invoke service methods on * AWSKinesisVideoArchivedMedia using the specified AWS account credentials * provider, client configuration options and request metric collector. *

* The client requests are authenticated using the {@link AWSCredentials} * provided by the {@link AWSCredentialsProvider}. Static AWSCredentials can * be passed for quick testing. However, it is strongly recommended to use * Amazon Cognito vended temporary credentials for use in production. This * can be achieved by using {@link AWSMobileClient}. Please see * https://aws-amplify.github.io/docs/android/authentication for * instructions on how to enable {@link AWSMobileClient}. * *

     * AWSMobileClient.getInstance().initialize(getApplicationContext(), new Callback<UserStateDetails>() {
     *     @Override
     *     public void onResult(final UserStateDetails details) {
     *         AWSKinesisVideoArchivedMediaClient client = new AWSKinesisVideoArchivedMediaClient(
     *                 AWSMobileClient.getInstance());
     *     }
     * 
     *     @Override
     *     public void onError(final Exception e) {
     *         e.printStackTrace();
     *     }
     * });
     * 
*

* All service calls made using this new client object are blocking, and * will not return until the service call completes. * * @param awsCredentialsProvider The AWS credentials provider which will * provide credentials to authenticate requests with AWS * services. * @param clientConfiguration The client configuration options controlling * how this client connects to AWSKinesisVideoArchivedMedia (ex: * proxy settings, retry counts, etc.). * @param httpClient A http client */ public AWSKinesisVideoArchivedMediaClient(AWSCredentialsProvider awsCredentialsProvider, ClientConfiguration clientConfiguration, HttpClient httpClient) { super(adjustClientConfiguration(clientConfiguration), httpClient); this.awsCredentialsProvider = awsCredentialsProvider; init(); } private void init() { jsonErrorUnmarshallers = new ArrayList(); jsonErrorUnmarshallers.add(new ClientLimitExceededExceptionUnmarshaller()); jsonErrorUnmarshallers.add(new InvalidArgumentExceptionUnmarshaller()); jsonErrorUnmarshallers.add(new InvalidCodecPrivateDataExceptionUnmarshaller()); jsonErrorUnmarshallers.add(new InvalidMediaFrameExceptionUnmarshaller()); jsonErrorUnmarshallers.add(new MissingCodecPrivateDataExceptionUnmarshaller()); jsonErrorUnmarshallers.add(new NoDataRetentionExceptionUnmarshaller()); jsonErrorUnmarshallers.add(new NotAuthorizedExceptionUnmarshaller()); jsonErrorUnmarshallers.add(new ResourceNotFoundExceptionUnmarshaller()); jsonErrorUnmarshallers.add(new UnsupportedStreamMediaTypeExceptionUnmarshaller()); jsonErrorUnmarshallers.add(new JsonErrorUnmarshaller()); // calling this.setEndPoint(...) will also modify the signer accordingly this.setEndpoint("kinesisvideo.us-east-1.amazonaws.com"); this.endpointPrefix = "kinesisvideo"; HandlerChainFactory chainFactory = new HandlerChainFactory(); requestHandler2s.addAll(chainFactory.newRequestHandlerChain( "/com/amazonaws/services/kinesisvideoarchivedmedia/request.handlers")); requestHandler2s.addAll(chainFactory.newRequestHandler2Chain( "/com/amazonaws/services/kinesisvideoarchivedmedia/request.handler2s")); } private static ClientConfiguration adjustClientConfiguration(ClientConfiguration orig) { ClientConfiguration config = orig; return config; } /** *

* Downloads an MP4 file (clip) containing the archived, on-demand media * from the specified video stream over the specified time range. *

*

* Both the StreamName and the StreamARN parameters are optional, but you * must specify either the StreamName or the StreamARN when invoking this * API operation. *

*

* As a prerequisite to using GetCLip API, you must obtain an endpoint using * GetDataEndpoint, specifying GET_CLIP for * the APIName parameter. *

*

* An Amazon Kinesis video stream has the following requirements for * providing data through MP4: *

* *

* You can monitor the amount of outgoing data by monitoring the * GetClip.OutgoingBytes Amazon CloudWatch metric. For * information about using CloudWatch to monitor Kinesis Video Streams, see * Monitoring Kinesis Video Streams. For pricing information, see Amazon * Kinesis Video Streams Pricing and AWS Pricing. Charges for * outgoing AWS data apply. *

* * @param getClipRequest * @return getClipResult The response from the GetClip service method, as * returned by Amazon Kinesis Video Streams Archived Media. * @throws ResourceNotFoundException * @throws InvalidArgumentException * @throws ClientLimitExceededException * @throws NotAuthorizedException * @throws UnsupportedStreamMediaTypeException * @throws MissingCodecPrivateDataException * @throws InvalidCodecPrivateDataException * @throws InvalidMediaFrameException * @throws NoDataRetentionException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * Kinesis Video Streams Archived Media indicating either a * problem with the data in the request, or a server side issue. */ public GetClipResult getClip(GetClipRequest getClipRequest) throws AmazonServiceException, AmazonClientException { ExecutionContext executionContext = createExecutionContext(getClipRequest); AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics(); awsRequestMetrics.startEvent(Field.ClientExecuteTime); Request request = null; Response response = null; try { awsRequestMetrics.startEvent(Field.RequestMarshallTime); try { request = new GetClipRequestMarshaller().marshall(getClipRequest); // Binds the request metrics to the current request. request.setAWSRequestMetrics(awsRequestMetrics); } finally { awsRequestMetrics.endEvent(Field.RequestMarshallTime); } Unmarshaller unmarshaller = new GetClipResultJsonUnmarshaller(); JsonResponseHandler responseHandler = new JsonResponseHandler( unmarshaller); response = invoke(request, responseHandler, executionContext); return response.getAwsResponse(); } finally { awsRequestMetrics.endEvent(Field.ClientExecuteTime); endClientExecution(awsRequestMetrics, request, response, LOGGING_AWS_REQUEST_METRIC); } } /** *

* Retrieves an MPEG Dynamic Adaptive Streaming over HTTP (DASH) URL for the * stream. You can then open the URL in a media player to view the stream * contents. *

*

* Both the StreamName and the StreamARN * parameters are optional, but you must specify either the * StreamName or the StreamARN when invoking this * API operation. *

*

* An Amazon Kinesis video stream has the following requirements for * providing data through MPEG-DASH: *

*
    *
  • *

    * The media must contain h.264 or h.265 encoded video and, optionally, AAC * or G.711 encoded audio. Specifically, the codec ID of track 1 should be * V_MPEG/ISO/AVC (for h.264) or V_MPEGH/ISO/HEVC (for H.265). * Optionally, the codec ID of track 2 should be A_AAC (for * AAC) or A_MS/ACM (for G.711). *

    *
  • *
  • *

    * Data retention must be greater than 0. *

    *
  • *
  • *

    * The video track of each fragment must contain codec private data in the * Advanced Video Coding (AVC) for H.264 format and HEVC for H.265 format. * For more information, see MPEG-4 specification * ISO/IEC 14496-15. For information about adapting stream data to a * given format, see NAL Adaptation Flags. *

    *
  • *
  • *

    * The audio track (if present) of each fragment must contain codec private * data in the AAC format (AAC specification ISO/IEC * 13818-7) or the MS * Wave format. *

    *
  • *
*

* The following procedure shows how to use MPEG-DASH with Kinesis Video * Streams: *

*
    *
  1. *

    * Get an endpoint using GetDataEndpoint, specifying * GET_DASH_STREAMING_SESSION_URL for the APIName * parameter. *

    *
  2. *
  3. *

    * Retrieve the MPEG-DASH URL using GetDASHStreamingSessionURL. * Kinesis Video Streams creates an MPEG-DASH streaming session to be used * for accessing content in a stream using the MPEG-DASH protocol. * GetDASHStreamingSessionURL returns an authenticated URL * (that includes an encrypted session token) for the session's MPEG-DASH * manifest (the root resource needed for streaming with MPEG-DASH). *

    * *

    * Don't share or store this token where an unauthorized entity can access * it. The token provides access to the content of the stream. Safeguard the * token with the same measures that you use with your AWS credentials. *

    *
    *

    * The media that is made available through the manifest consists only of * the requested stream, time range, and format. No other media data (such * as frames outside the requested window or alternate bitrates) is made * available. *

    *
  4. *
  5. *

    * Provide the URL (containing the encrypted session token) for the * MPEG-DASH manifest to a media player that supports the MPEG-DASH * protocol. Kinesis Video Streams makes the initialization fragment and * media fragments available through the manifest URL. The initialization * fragment contains the codec private data for the stream, and other data * needed to set up the video or audio decoder and renderer. The media * fragments contain encoded video frames or encoded audio samples. *

    *
  6. *
  7. *

    * The media player receives the authenticated URL and requests stream * metadata and media data normally. When the media player requests data, it * calls the following actions: *

    *
      *
    • *

      * GetDASHManifest: Retrieves an MPEG DASH manifest, which contains * the metadata for the media that you want to playback. *

      *
    • *
    • *

      * GetMP4InitFragment: Retrieves the MP4 initialization fragment. The * media player typically loads the initialization fragment before loading * any media fragments. This fragment contains the "fytp" and " * moov" MP4 atoms, and the child atoms that are needed to * initialize the media player decoder. *

      *

      * The initialization fragment does not correspond to a fragment in a * Kinesis video stream. It contains only the codec private data for the * stream and respective track, which the media player needs to decode the * media frames. *

      *
    • *
    • *

      * GetMP4MediaFragment: Retrieves MP4 media fragments. These * fragments contain the "moof" and "mdat" MP4 * atoms and their child atoms, containing the encoded fragment's media * frames and their timestamps. *

      * *

      * After the first media fragment is made available in a streaming session, * any fragments that don't contain the same codec private data cause an * error to be returned when those different media fragments are loaded. * Therefore, the codec private data should not change between fragments in * a session. This also means that the session fails if the fragments in a * stream change from having only video to having both audio and video. *

      *
      *

      * Data retrieved with this action is billable. See Pricing * for details. *

      *
    • *
    *
  8. *
* *

* For restrictions that apply to MPEG-DASH sessions, see Kinesis Video Streams Limits. *

*
*

* You can monitor the amount of data that the media player consumes by * monitoring the GetMP4MediaFragment.OutgoingBytes Amazon * CloudWatch metric. For information about using CloudWatch to monitor * Kinesis Video Streams, see Monitoring Kinesis Video Streams. For pricing information, see Amazon * Kinesis Video Streams Pricing and AWS Pricing. Charges for both * HLS sessions and outgoing AWS data apply. *

*

* For more information about HLS, see HTTP Live Streaming on * the Apple Developer site. *

* *

* If an error is thrown after invoking a Kinesis Video Streams archived * media API, in addition to the HTTP status code and the response body, it * includes the following pieces of information: *

*
    *
  • *

    * x-amz-ErrorType HTTP header – contains a more specific error * type in addition to what the HTTP status code provides. *

    *
  • *
  • *

    * x-amz-RequestId HTTP header – if you want to report an issue * to AWS, the support team can better diagnose the problem if given the * Request Id. *

    *
  • *
*

* Both the HTTP status code and the ErrorType header can be utilized to * make programmatic decisions about whether errors are retry-able and under * what conditions, as well as provide information on what actions the * client programmer might need to take in order to successfully try again. *

*

* For more information, see the Errors section at the bottom of this * topic, as well as Common Errors. *

*
* * @param getDASHStreamingSessionURLRequest * @return getDASHStreamingSessionURLResult The response from the * GetDASHStreamingSessionURL service method, as returned by Amazon * Kinesis Video Streams Archived Media. * @throws ResourceNotFoundException * @throws InvalidArgumentException * @throws ClientLimitExceededException * @throws NotAuthorizedException * @throws UnsupportedStreamMediaTypeException * @throws NoDataRetentionException * @throws MissingCodecPrivateDataException * @throws InvalidCodecPrivateDataException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * Kinesis Video Streams Archived Media indicating either a * problem with the data in the request, or a server side issue. */ public GetDASHStreamingSessionURLResult getDASHStreamingSessionURL( GetDASHStreamingSessionURLRequest getDASHStreamingSessionURLRequest) throws AmazonServiceException, AmazonClientException { ExecutionContext executionContext = createExecutionContext(getDASHStreamingSessionURLRequest); AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics(); awsRequestMetrics.startEvent(Field.ClientExecuteTime); Request request = null; Response response = null; try { awsRequestMetrics.startEvent(Field.RequestMarshallTime); try { request = new GetDASHStreamingSessionURLRequestMarshaller() .marshall(getDASHStreamingSessionURLRequest); // Binds the request metrics to the current request. request.setAWSRequestMetrics(awsRequestMetrics); } finally { awsRequestMetrics.endEvent(Field.RequestMarshallTime); } Unmarshaller unmarshaller = new GetDASHStreamingSessionURLResultJsonUnmarshaller(); JsonResponseHandler responseHandler = new JsonResponseHandler( unmarshaller); response = invoke(request, responseHandler, executionContext); return response.getAwsResponse(); } finally { awsRequestMetrics.endEvent(Field.ClientExecuteTime); endClientExecution(awsRequestMetrics, request, response, LOGGING_AWS_REQUEST_METRIC); } } /** *

* Retrieves an HTTP Live Streaming (HLS) URL for the stream. You can then * open the URL in a browser or media player to view the stream contents. *

*

* Both the StreamName and the StreamARN * parameters are optional, but you must specify either the * StreamName or the StreamARN when invoking this * API operation. *

*

* An Amazon Kinesis video stream has the following requirements for * providing data through HLS: *

*
    *
  • *

    * The media must contain h.264 or h.265 encoded video and, optionally, AAC * encoded audio. Specifically, the codec ID of track 1 should be * V_MPEG/ISO/AVC (for h.264) or V_MPEG/ISO/HEVC * (for h.265). Optionally, the codec ID of track 2 should be * A_AAC. *

    *
  • *
  • *

    * Data retention must be greater than 0. *

    *
  • *
  • *

    * The video track of each fragment must contain codec private data in the * Advanced Video Coding (AVC) for H.264 format or HEVC for H.265 format (MPEG-4 specification * ISO/IEC 14496-15). For information about adapting stream data to a * given format, see NAL Adaptation Flags. *

    *
  • *
  • *

    * The audio track (if present) of each fragment must contain codec private * data in the AAC format (AAC specification ISO/IEC * 13818-7). *

    *
  • *
*

* Kinesis Video Streams HLS sessions contain fragments in the fragmented * MPEG-4 form (also called fMP4 or CMAF) or the MPEG-2 form (also called TS * chunks, which the HLS specification also supports). For more information * about HLS fragment types, see the HLS specification. *

*

* The following procedure shows how to use HLS with Kinesis Video Streams: *

*
    *
  1. *

    * Get an endpoint using GetDataEndpoint, specifying * GET_HLS_STREAMING_SESSION_URL for the APIName * parameter. *

    *
  2. *
  3. *

    * Retrieve the HLS URL using GetHLSStreamingSessionURL. * Kinesis Video Streams creates an HLS streaming session to be used for * accessing content in a stream using the HLS protocol. * GetHLSStreamingSessionURL returns an authenticated URL (that * includes an encrypted session token) for the session's HLS master * playlist (the root resource needed for streaming with HLS). *

    * *

    * Don't share or store this token where an unauthorized entity could access * it. The token provides access to the content of the stream. Safeguard the * token with the same measures that you would use with your AWS * credentials. *

    *
    *

    * The media that is made available through the playlist consists only of * the requested stream, time range, and format. No other media data (such * as frames outside the requested window or alternate bitrates) is made * available. *

    *
  4. *
  5. *

    * Provide the URL (containing the encrypted session token) for the HLS * master playlist to a media player that supports the HLS protocol. Kinesis * Video Streams makes the HLS media playlist, initialization fragment, and * media fragments available through the master playlist URL. The * initialization fragment contains the codec private data for the stream, * and other data needed to set up the video or audio decoder and renderer. * The media fragments contain H.264-encoded video frames or AAC-encoded * audio samples. *

    *
  6. *
  7. *

    * The media player receives the authenticated URL and requests stream * metadata and media data normally. When the media player requests data, it * calls the following actions: *

    *
      *
    • *

      * GetHLSMasterPlaylist: Retrieves an HLS master playlist, which * contains a URL for the GetHLSMediaPlaylist action for each * track, and additional metadata for the media player, including estimated * bitrate and resolution. *

      *
    • *
    • *

      * GetHLSMediaPlaylist: Retrieves an HLS media playlist, which * contains a URL to access the MP4 initialization fragment with the * GetMP4InitFragment action, and URLs to access the MP4 media * fragments with the GetMP4MediaFragment actions. The HLS * media playlist also contains metadata about the stream that the player * needs to play it, such as whether the PlaybackMode is * LIVE or ON_DEMAND. The HLS media playlist is * typically static for sessions with a PlaybackType of * ON_DEMAND. The HLS media playlist is continually updated * with new fragments for sessions with a PlaybackType of * LIVE. There is a distinct HLS media playlist for the video * track and the audio track (if applicable) that contains MP4 media URLs * for the specific track. *

      *
    • *
    • *

      * GetMP4InitFragment: Retrieves the MP4 initialization fragment. The * media player typically loads the initialization fragment before loading * any media fragments. This fragment contains the "fytp" and " * moov" MP4 atoms, and the child atoms that are needed to * initialize the media player decoder. *

      *

      * The initialization fragment does not correspond to a fragment in a * Kinesis video stream. It contains only the codec private data for the * stream and respective track, which the media player needs to decode the * media frames. *

      *
    • *
    • *

      * GetMP4MediaFragment: Retrieves MP4 media fragments. These * fragments contain the "moof" and "mdat" MP4 * atoms and their child atoms, containing the encoded fragment's media * frames and their timestamps. *

      * *

      * After the first media fragment is made available in a streaming session, * any fragments that don't contain the same codec private data cause an * error to be returned when those different media fragments are loaded. * Therefore, the codec private data should not change between fragments in * a session. This also means that the session fails if the fragments in a * stream change from having only video to having both audio and video. *

      *
      *

      * Data retrieved with this action is billable. See Pricing * for details. *

      *
    • *
    • *

      * GetTSFragment: Retrieves MPEG TS fragments containing both * initialization and media data for all tracks in the stream. *

      * *

      * If the ContainerFormat is MPEG_TS, this API is * used instead of GetMP4InitFragment and * GetMP4MediaFragment to retrieve stream media. *

      *
      *

      * Data retrieved with this action is billable. For more information, see Kinesis * Video Streams pricing. *

      *
    • *
    *
  8. *
*

* A streaming session URL must not be shared between players. The service * might throttle a session if multiple media players are sharing it. For * connection limits, see Kinesis Video Streams Limits. *

*

* You can monitor the amount of data that the media player consumes by * monitoring the GetMP4MediaFragment.OutgoingBytes Amazon * CloudWatch metric. For information about using CloudWatch to monitor * Kinesis Video Streams, see Monitoring Kinesis Video Streams. For pricing information, see Amazon * Kinesis Video Streams Pricing and AWS Pricing. Charges for both * HLS sessions and outgoing AWS data apply. *

*

* For more information about HLS, see HTTP Live Streaming on * the Apple Developer site. *

* *

* If an error is thrown after invoking a Kinesis Video Streams archived * media API, in addition to the HTTP status code and the response body, it * includes the following pieces of information: *

*
    *
  • *

    * x-amz-ErrorType HTTP header – contains a more specific error * type in addition to what the HTTP status code provides. *

    *
  • *
  • *

    * x-amz-RequestId HTTP header – if you want to report an issue * to AWS, the support team can better diagnose the problem if given the * Request Id. *

    *
  • *
*

* Both the HTTP status code and the ErrorType header can be utilized to * make programmatic decisions about whether errors are retry-able and under * what conditions, as well as provide information on what actions the * client programmer might need to take in order to successfully try again. *

*

* For more information, see the Errors section at the bottom of this * topic, as well as Common Errors. *

*
* * @param getHLSStreamingSessionURLRequest * @return getHLSStreamingSessionURLResult The response from the * GetHLSStreamingSessionURL service method, as returned by Amazon * Kinesis Video Streams Archived Media. * @throws ResourceNotFoundException * @throws InvalidArgumentException * @throws ClientLimitExceededException * @throws NotAuthorizedException * @throws UnsupportedStreamMediaTypeException * @throws NoDataRetentionException * @throws MissingCodecPrivateDataException * @throws InvalidCodecPrivateDataException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * Kinesis Video Streams Archived Media indicating either a * problem with the data in the request, or a server side issue. */ public GetHLSStreamingSessionURLResult getHLSStreamingSessionURL( GetHLSStreamingSessionURLRequest getHLSStreamingSessionURLRequest) throws AmazonServiceException, AmazonClientException { ExecutionContext executionContext = createExecutionContext(getHLSStreamingSessionURLRequest); AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics(); awsRequestMetrics.startEvent(Field.ClientExecuteTime); Request request = null; Response response = null; try { awsRequestMetrics.startEvent(Field.RequestMarshallTime); try { request = new GetHLSStreamingSessionURLRequestMarshaller() .marshall(getHLSStreamingSessionURLRequest); // Binds the request metrics to the current request. request.setAWSRequestMetrics(awsRequestMetrics); } finally { awsRequestMetrics.endEvent(Field.RequestMarshallTime); } Unmarshaller unmarshaller = new GetHLSStreamingSessionURLResultJsonUnmarshaller(); JsonResponseHandler responseHandler = new JsonResponseHandler( unmarshaller); response = invoke(request, responseHandler, executionContext); return response.getAwsResponse(); } finally { awsRequestMetrics.endEvent(Field.ClientExecuteTime); endClientExecution(awsRequestMetrics, request, response, LOGGING_AWS_REQUEST_METRIC); } } /** *

* Retrieves a list of Images corresponding to each timestamp for a given * time range, sampling interval, and image format configuration. *

* * @param getImagesRequest * @return getImagesResult The response from the GetImages service method, * as returned by Amazon Kinesis Video Streams Archived Media. * @throws ResourceNotFoundException * @throws InvalidArgumentException * @throws ClientLimitExceededException * @throws NotAuthorizedException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * Kinesis Video Streams Archived Media indicating either a * problem with the data in the request, or a server side issue. */ public GetImagesResult getImages(GetImagesRequest getImagesRequest) throws AmazonServiceException, AmazonClientException { ExecutionContext executionContext = createExecutionContext(getImagesRequest); AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics(); awsRequestMetrics.startEvent(Field.ClientExecuteTime); Request request = null; Response response = null; try { awsRequestMetrics.startEvent(Field.RequestMarshallTime); try { request = new GetImagesRequestMarshaller().marshall(getImagesRequest); // Binds the request metrics to the current request. request.setAWSRequestMetrics(awsRequestMetrics); } finally { awsRequestMetrics.endEvent(Field.RequestMarshallTime); } Unmarshaller unmarshaller = new GetImagesResultJsonUnmarshaller(); JsonResponseHandler responseHandler = new JsonResponseHandler( unmarshaller); response = invoke(request, responseHandler, executionContext); return response.getAwsResponse(); } finally { awsRequestMetrics.endEvent(Field.ClientExecuteTime); endClientExecution(awsRequestMetrics, request, response, LOGGING_AWS_REQUEST_METRIC); } } /** *

* Gets media for a list of fragments (specified by fragment number) from * the archived data in an Amazon Kinesis video stream. *

* *

* You must first call the GetDataEndpoint API to get an * endpoint. Then send the GetMediaForFragmentList requests to * this endpoint using the --endpoint-url * parameter. *

*
*

* For limits, see Kinesis Video Streams Limits. *

* *

* If an error is thrown after invoking a Kinesis Video Streams archived * media API, in addition to the HTTP status code and the response body, it * includes the following pieces of information: *

*
    *
  • *

    * x-amz-ErrorType HTTP header – contains a more specific error * type in addition to what the HTTP status code provides. *

    *
  • *
  • *

    * x-amz-RequestId HTTP header – if you want to report an issue * to AWS, the support team can better diagnose the problem if given the * Request Id. *

    *
  • *
*

* Both the HTTP status code and the ErrorType header can be utilized to * make programmatic decisions about whether errors are retry-able and under * what conditions, as well as provide information on what actions the * client programmer might need to take in order to successfully try again. *

*

* For more information, see the Errors section at the bottom of this * topic, as well as Common Errors. *

*
* * @param getMediaForFragmentListRequest * @return getMediaForFragmentListResult The response from the * GetMediaForFragmentList service method, as returned by Amazon * Kinesis Video Streams Archived Media. * @throws ResourceNotFoundException * @throws InvalidArgumentException * @throws ClientLimitExceededException * @throws NotAuthorizedException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * Kinesis Video Streams Archived Media indicating either a * problem with the data in the request, or a server side issue. */ public GetMediaForFragmentListResult getMediaForFragmentList( GetMediaForFragmentListRequest getMediaForFragmentListRequest) throws AmazonServiceException, AmazonClientException { ExecutionContext executionContext = createExecutionContext(getMediaForFragmentListRequest); AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics(); awsRequestMetrics.startEvent(Field.ClientExecuteTime); Request request = null; Response response = null; try { awsRequestMetrics.startEvent(Field.RequestMarshallTime); try { request = new GetMediaForFragmentListRequestMarshaller() .marshall(getMediaForFragmentListRequest); // Binds the request metrics to the current request. request.setAWSRequestMetrics(awsRequestMetrics); } finally { awsRequestMetrics.endEvent(Field.RequestMarshallTime); } Unmarshaller unmarshaller = new GetMediaForFragmentListResultJsonUnmarshaller(); JsonResponseHandler responseHandler = new JsonResponseHandler( unmarshaller); response = invoke(request, responseHandler, executionContext); return response.getAwsResponse(); } finally { awsRequestMetrics.endEvent(Field.ClientExecuteTime); endClientExecution(awsRequestMetrics, request, response, LOGGING_AWS_REQUEST_METRIC); } } /** *

* Returns a list of Fragment objects from the specified stream and * timestamp range within the archived data. *

*

* Listing fragments is eventually consistent. This means that even if the * producer receives an acknowledgment that a fragment is persisted, the * result might not be returned immediately from a request to * ListFragments. However, results are typically available in * less than one second. *

* *

* You must first call the GetDataEndpoint API to get an * endpoint. Then send the ListFragments requests to this * endpoint using the --endpoint-url * parameter. *

*
*

* If an error is thrown after invoking a Kinesis Video Streams archived * media API, in addition to the HTTP status code and the response body, it * includes the following pieces of information: *

*
    *
  • *

    * x-amz-ErrorType HTTP header – contains a more specific error * type in addition to what the HTTP status code provides. *

    *
  • *
  • *

    * x-amz-RequestId HTTP header – if you want to report an issue * to AWS, the support team can better diagnose the problem if given the * Request Id. *

    *
  • *
*

* Both the HTTP status code and the ErrorType header can be utilized to * make programmatic decisions about whether errors are retry-able and under * what conditions, as well as provide information on what actions the * client programmer might need to take in order to successfully try again. *

*

* For more information, see the Errors section at the bottom of this * topic, as well as Common Errors. *

*
* * @param listFragmentsRequest * @return listFragmentsResult The response from the ListFragments service * method, as returned by Amazon Kinesis Video Streams Archived * Media. * @throws ResourceNotFoundException * @throws InvalidArgumentException * @throws ClientLimitExceededException * @throws NotAuthorizedException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * Kinesis Video Streams Archived Media indicating either a * problem with the data in the request, or a server side issue. */ public ListFragmentsResult listFragments(ListFragmentsRequest listFragmentsRequest) throws AmazonServiceException, AmazonClientException { ExecutionContext executionContext = createExecutionContext(listFragmentsRequest); AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics(); awsRequestMetrics.startEvent(Field.ClientExecuteTime); Request request = null; Response response = null; try { awsRequestMetrics.startEvent(Field.RequestMarshallTime); try { request = new ListFragmentsRequestMarshaller().marshall(listFragmentsRequest); // Binds the request metrics to the current request. request.setAWSRequestMetrics(awsRequestMetrics); } finally { awsRequestMetrics.endEvent(Field.RequestMarshallTime); } Unmarshaller unmarshaller = new ListFragmentsResultJsonUnmarshaller(); JsonResponseHandler responseHandler = new JsonResponseHandler( unmarshaller); response = invoke(request, responseHandler, executionContext); return response.getAwsResponse(); } finally { awsRequestMetrics.endEvent(Field.ClientExecuteTime); endClientExecution(awsRequestMetrics, request, response, LOGGING_AWS_REQUEST_METRIC); } } /** * Returns additional metadata for a previously executed successful, * request, typically used for debugging issues where a service isn't acting * as expected. This data isn't considered part of the result data returned * by an operation, so it's available through this separate, diagnostic * interface. *

* Response metadata is only cached for a limited period of time, so if you * need to access this extra diagnostic information for an executed request, * you should use this method to retrieve it as soon as possible after * executing the request. * * @param request The originally executed request * @return The response metadata for the specified request, or null if none * is available. * @deprecated ResponseMetadata cache can hold up to 50 requests and * responses in memory and will cause memory issue. This method * now always returns null. */ @Deprecated public ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request) { return client.getResponseMetadataForRequest(request); } private Response invoke(Request request, HttpResponseHandler> responseHandler, ExecutionContext executionContext) { request.setEndpoint(endpoint); request.setTimeOffset(timeOffset); AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics(); AWSCredentials credentials; awsRequestMetrics.startEvent(Field.CredentialsRequestTime); try { credentials = awsCredentialsProvider.getCredentials(); } finally { awsRequestMetrics.endEvent(Field.CredentialsRequestTime); } AmazonWebServiceRequest originalRequest = request.getOriginalRequest(); if (originalRequest != null && originalRequest.getRequestCredentials() != null) { credentials = originalRequest.getRequestCredentials(); } executionContext.setCredentials(credentials); JsonErrorResponseHandler errorResponseHandler = new JsonErrorResponseHandler( jsonErrorUnmarshallers); Response result = client.execute(request, responseHandler, errorResponseHandler, executionContext); return result; } }