/* * Copyright 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. */ /* * Do not modify this file. This file is generated from the kinesis-video-archived-media-2017-09-30.normal.json service model. */ using System; using System.Collections.Generic; using System.Xml.Serialization; using System.Text; using System.IO; using System.Net; using Amazon.Runtime; using Amazon.Runtime.Internal; namespace Amazon.KinesisVideoArchivedMedia.Model { /// /// Container for the parameters to the GetHLSStreamingSessionURL operation. /// 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. /// /// 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. /// /// 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. /// /// 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. /// ///
/// /// 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. /// /// /// public partial class GetHLSStreamingSessionURLRequest : AmazonKinesisVideoArchivedMediaRequest { private ContainerFormat _containerFormat; private HLSDiscontinuityMode _discontinuityMode; private HLSDisplayFragmentTimestamp _displayFragmentTimestamp; private int? _expires; private HLSFragmentSelector _hlsFragmentSelector; private long? _maxMediaPlaylistFragmentResults; private HLSPlaybackMode _playbackMode; private string _streamARN; private string _streamName; /// /// Gets and sets the property ContainerFormat. /// /// Specifies which format should be used for packaging the media. Specifying the FRAGMENTED_MP4 /// container format packages the media into MP4 fragments (fMP4 or CMAF). This is the /// recommended packaging because there is minimal packaging overhead. The other container /// format option is MPEG_TS. HLS has supported MPEG TS chunks since it was /// released and is sometimes the only supported packaging on older HLS players. MPEG /// TS typically has a 5-25 percent packaging overhead. This means MPEG TS typically requires /// 5-25 percent more bandwidth and cost than fMP4. /// /// /// /// The default is FRAGMENTED_MP4. /// /// public ContainerFormat ContainerFormat { get { return this._containerFormat; } set { this._containerFormat = value; } } // Check to see if ContainerFormat property is set internal bool IsSetContainerFormat() { return this._containerFormat != null; } /// /// Gets and sets the property DiscontinuityMode. /// /// Specifies when flags marking discontinuities between fragments are added to the media /// playlists. /// /// /// /// Media players typically build a timeline of media content to play, based on the timestamps /// of each fragment. This means that if there is any overlap or gap between fragments /// (as is typical if HLSFragmentSelector is set to SERVER_TIMESTAMP), /// the media player timeline will also have small gaps between fragments in some places, /// and will overwrite frames in other places. Gaps in the media player timeline can cause /// playback to stall and overlaps can cause playback to be jittery. When there are discontinuity /// flags between fragments, the media player is expected to reset the timeline, resulting /// in the next fragment being played immediately after the previous fragment. /// /// /// /// The following modes are supported: /// /// /// /// The default is ALWAYS when HLSFragmentSelector is set to SERVER_TIMESTAMP, /// and NEVER when it is set to PRODUCER_TIMESTAMP. /// /// public HLSDiscontinuityMode DiscontinuityMode { get { return this._discontinuityMode; } set { this._discontinuityMode = value; } } // Check to see if DiscontinuityMode property is set internal bool IsSetDiscontinuityMode() { return this._discontinuityMode != null; } /// /// Gets and sets the property DisplayFragmentTimestamp. /// /// Specifies when the fragment start timestamps should be included in the HLS media playlist. /// Typically, media players report the playhead position as a time relative to the start /// of the first fragment in the playback session. However, when the start timestamps /// are included in the HLS media playlist, some media players might report the current /// playhead as an absolute time based on the fragment timestamps. This can be useful /// for creating a playback experience that shows viewers the wall-clock time of the media. /// /// /// /// The default is NEVER. When HLSFragmentSelector is SERVER_TIMESTAMP, /// the timestamps will be the server start timestamps. Similarly, when HLSFragmentSelector /// is PRODUCER_TIMESTAMP, the timestamps will be the producer start timestamps. /// /// /// public HLSDisplayFragmentTimestamp DisplayFragmentTimestamp { get { return this._displayFragmentTimestamp; } set { this._displayFragmentTimestamp = value; } } // Check to see if DisplayFragmentTimestamp property is set internal bool IsSetDisplayFragmentTimestamp() { return this._displayFragmentTimestamp != null; } /// /// Gets and sets the property Expires. /// /// The time in seconds until the requested session expires. This value can be between /// 300 (5 minutes) and 43200 (12 hours). /// /// /// /// When a session expires, no new calls to GetHLSMasterPlaylist, GetHLSMediaPlaylist, /// GetMP4InitFragment, GetMP4MediaFragment, or GetTSFragment /// can be made for that session. /// /// /// /// The default is 300 (5 minutes). /// /// [AWSProperty(Min=300, Max=43200)] public int Expires { get { return this._expires.GetValueOrDefault(); } set { this._expires = value; } } // Check to see if Expires property is set internal bool IsSetExpires() { return this._expires.HasValue; } /// /// Gets and sets the property HLSFragmentSelector. /// /// The time range of the requested fragment and the source of the timestamps. /// /// /// /// This parameter is required if PlaybackMode is ON_DEMAND /// or LIVE_REPLAY. This parameter is optional if PlaybackMode is /// LIVE. If PlaybackMode is LIVE, the FragmentSelectorType /// can be set, but the TimestampRange should not be set. If PlaybackMode /// is ON_DEMAND or LIVE_REPLAY, both FragmentSelectorType /// and TimestampRange must be set. /// /// public HLSFragmentSelector HLSFragmentSelector { get { return this._hlsFragmentSelector; } set { this._hlsFragmentSelector = value; } } // Check to see if HLSFragmentSelector property is set internal bool IsSetHLSFragmentSelector() { return this._hlsFragmentSelector != null; } /// /// Gets and sets the property MaxMediaPlaylistFragmentResults. /// /// The maximum number of fragments that are returned in the HLS media playlists. /// /// /// /// When the PlaybackMode is LIVE, the most recent fragments /// are returned up to this value. When the PlaybackMode is ON_DEMAND, /// the oldest fragments are returned, up to this maximum number. /// /// /// /// When there are a higher number of fragments available in a live HLS media playlist, /// video players often buffer content before starting playback. Increasing the buffer /// size increases the playback latency, but it decreases the likelihood that rebuffering /// will occur during playback. We recommend that a live HLS media playlist have a minimum /// of 3 fragments and a maximum of 10 fragments. /// /// /// /// The default is 5 fragments if PlaybackMode is LIVE or LIVE_REPLAY, /// and 1,000 if PlaybackMode is ON_DEMAND. /// /// /// /// The maximum value of 5,000 fragments corresponds to more than 80 minutes of video /// on streams with 1-second fragments, and more than 13 hours of video on streams with /// 10-second fragments. /// /// [AWSProperty(Min=1, Max=5000)] public long MaxMediaPlaylistFragmentResults { get { return this._maxMediaPlaylistFragmentResults.GetValueOrDefault(); } set { this._maxMediaPlaylistFragmentResults = value; } } // Check to see if MaxMediaPlaylistFragmentResults property is set internal bool IsSetMaxMediaPlaylistFragmentResults() { return this._maxMediaPlaylistFragmentResults.HasValue; } /// /// Gets and sets the property PlaybackMode. /// /// Whether to retrieve live, live replay, or archived, on-demand data. /// /// /// /// Features of the three types of sessions include the following: /// /// /// /// In all playback modes, if FragmentSelectorType is PRODUCER_TIMESTAMP, /// and if there are multiple fragments with the same start timestamp, the fragment that /// has the largest fragment number (that is, the newest fragment) is included in the /// HLS media playlist. The other fragments are not included. Fragments that have different /// timestamps but have overlapping durations are still included in the HLS media playlist. /// This can lead to unexpected behavior in the media player. /// /// /// /// The default is LIVE. /// /// public HLSPlaybackMode PlaybackMode { get { return this._playbackMode; } set { this._playbackMode = value; } } // Check to see if PlaybackMode property is set internal bool IsSetPlaybackMode() { return this._playbackMode != null; } /// /// Gets and sets the property StreamARN. /// /// The Amazon Resource Name (ARN) of the stream for which to retrieve the HLS master /// playlist URL. /// /// /// /// You must specify either the StreamName or the StreamARN. /// /// [AWSProperty(Min=1, Max=1024)] public string StreamARN { get { return this._streamARN; } set { this._streamARN = value; } } // Check to see if StreamARN property is set internal bool IsSetStreamARN() { return this._streamARN != null; } /// /// Gets and sets the property StreamName. /// /// The name of the stream for which to retrieve the HLS master playlist URL. /// /// /// /// You must specify either the StreamName or the StreamARN. /// /// [AWSProperty(Min=1, Max=256)] public string StreamName { get { return this._streamName; } set { this._streamName = value; } } // Check to see if StreamName property is set internal bool IsSetStreamName() { return this._streamName != null; } } }