/* * 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 com.amazonaws.*; import com.amazonaws.regions.*; import com.amazonaws.services.kinesisvideoarchivedmedia.model.*; /** * Interface for accessing Amazon Kinesis Video Streams Archived Media *

**/ public interface AWSKinesisVideoArchivedMedia { /** * Overrides the default endpoint for this client * ("https://kinesisvideo.us-east-1.amazonaws.com"). Callers can use this * method to control which AWS region they want to work with. *

* Callers can pass in just the endpoint (ex: * "kinesisvideo.us-east-1.amazonaws.com") or a full URL, including the * protocol (ex: "https://kinesisvideo.us-east-1.amazonaws.com"). If the * protocol is not specified here, the default protocol from this client's * {@link ClientConfiguration} will be used, which by default is HTTPS. *

* For more information on using AWS regions with the AWS SDK for Java, and * a complete list of all available endpoints for all AWS services, see: http://developer.amazonwebservices.com/connect/entry.jspa?externalID= * 3912 *

* This method is not threadsafe. An endpoint should be configured when * the client is created and before any service requests are made. Changing * it afterwards creates inevitable race conditions for any service requests * in transit or retrying. * * @param endpoint The endpoint (ex: "kinesisvideo.us-east-1.amazonaws.com") * or a full URL, including the protocol (ex: * "https://kinesisvideo.us-east-1.amazonaws.com") of the region * specific AWS endpoint this client will communicate with. * @throws IllegalArgumentException If any problems are detected with the * specified endpoint. */ public void setEndpoint(String endpoint) throws java.lang.IllegalArgumentException; /** * An alternative to * {@link AWSKinesisVideoArchivedMedia#setEndpoint(String)}, sets the * regional endpoint for this client's service calls. Callers can use this * method to control which AWS region they want to work with. *

* By default, all service endpoints in all regions use the https protocol. * To use http instead, specify it in the {@link ClientConfiguration} * supplied at construction. *

* This method is not threadsafe. A region should be configured when the * client is created and before any service requests are made. Changing it * afterwards creates inevitable race conditions for any service requests in * transit or retrying. * * @param region The region this client will communicate with. See * {@link Region#getRegion(com.amazonaws.regions.Regions)} for * accessing a given region. * @throws java.lang.IllegalArgumentException If the given region is null, * or if this service isn't available in the given region. See * {@link Region#isServiceSupported(String)} * @see Region#getRegion(com.amazonaws.regions.Regions) * @see Region#createClient(Class, * com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration) */ public void setRegion(Region region) throws java.lang.IllegalArgumentException; /** *

* 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. */ GetClipResult getClip(GetClipRequest getClipRequest) throws AmazonClientException, AmazonServiceException; /** *

* 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 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. *
  2. *

    * 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. *

    *
    3. *
  3. *

    * 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. *

    *
    4. *
  4. *

    * 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. *

      *
      • *
    *
    5. *
* *

* 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: *

* *

* 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. */ GetDASHStreamingSessionURLResult getDASHStreamingSessionURL( GetDASHStreamingSessionURLRequest getDASHStreamingSessionURLRequest) throws AmazonClientException, AmazonServiceException; /** *

* 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: *

* *

* 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. *
  2. *

    * 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. *

    *
    3. *
  3. *

    * 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. *

    *
    4. *
  4. *

    * 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. *

      *
      • *
    *
    5. *
*

* 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: *

* *

* 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. */ GetHLSStreamingSessionURLResult getHLSStreamingSessionURL( GetHLSStreamingSessionURLRequest getHLSStreamingSessionURLRequest) throws AmazonClientException, AmazonServiceException; /** *

* 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. */ GetImagesResult getImages(GetImagesRequest getImagesRequest) throws AmazonClientException, AmazonServiceException; /** *

* 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: *

* *

* 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. */ GetMediaForFragmentListResult getMediaForFragmentList( GetMediaForFragmentListRequest getMediaForFragmentListRequest) throws AmazonClientException, AmazonServiceException; /** *

* 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: *

* *

* 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. */ ListFragmentsResult listFragments(ListFragmentsRequest listFragmentsRequest) throws AmazonClientException, AmazonServiceException; /** * Shuts down this client object, releasing any resources that might be held * open. This is an optional method, and callers are not expected to call * it, but can if they want to explicitly release any open resources. Once a * client has been shutdown, it should not be used to make any more * requests. */ public void shutdown(); /** * 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 a request. * * @param request The originally executed request. * @return The response metadata for the specified request, or null if none * is available. */ public ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request); }