Shaka Packager Library (Continued)

struct PackagingParams

Packaging parameters.

Public Members

std::string temp_dir

Specify temporary directory for intermediate temporary files.

Mp4OutputParams mp4_output_params

MP4 (ISO-BMFF) output related parameters.

uint32_t transport_stream_timestamp_offset_ms = 0

The offset to be applied to transport stream (e.g. MPEG2-TS, HLS packed audio) timestamps to compensate for possible negative timestamps in the input.

ChunkingParams chunking_params

Chunking (segmentation) related parameters.

AdCueGeneratorParams ad_cue_generator_params

Out of band cuepoint parameters.

bool output_media_info = false

Create a human readable format of MediaInfo. The output file name will be the name specified by output flag, suffixed with .media_info.

MpdParams mpd_params

DASH MPD related parameters.

HlsParams hls_params

HLS related parameters.

EncryptionParams encryption_params

Encryption and Decryption Parameters.

BufferCallbackParams buffer_callback_params

Buffer callback params.

struct StreamDescriptor

Defines a single input/output stream.

Public Members

std::string input

Input/source media file path or network stream URL. Required.

std::string stream_selector

Stream selector, can be audio, video, text or a zero based stream index. Required.

std::string output

Specifies output file path or init segment path (if segment template is specified). Can be empty for self initialization media segments.

std::string segment_template

Specifies segment template. Can be empty.

std::string output_format

Optional value which specifies output container format, e.g. “mp4”. If not specified, will detect from output / segment template name.

bool skip_encryption = false

If set to true, the stream will not be encrypted. This is useful, e.g. to encrypt only video streams.

std::string drm_label

Specifies a custom DRM stream label, which can be a DRM label defined by the DRM system. Typically values include AUDIO, SD, HD, UHD1, UHD2. If not provided, the DRM stream label is derived from stream type (video, audio), resolutions etc.

uint32_t trick_play_factor = 0

If set to a non-zero value, will generate a trick play / trick mode stream with frames sampled from the key frames in the original stream. trick_play_factor defines the sampling rate.

uint32_t bandwidth = 0

Optional user-specified content bit rate for the stream, in bits/sec. If specified, this value is propagated to the $Bandwidth$ template parameter for segment names. If not specified, its value may be estimated.

std::string language

Optional value which contains a user-specified language tag. If specified, this value overrides any language metadata in the input stream.

std::string hls_name

Required for audio when outputting HLS. It defines the name of the output stream, which is not necessarily the same as output. This is used as the NAME attribute for EXT-X-MEDIA.

std::string hls_group_id

Required for audio when outputting HLS. It defines the group ID for the output stream. This is used as the GROUP-ID attribute for EXT-X-MEDIA.

std::string hls_playlist_name

Required for HLS output. It defines the name of the playlist for the stream. Usually ends with .m3u8.

std::string hls_iframe_playlist_name

Optional for HLS output. It defines the name of the I-Frames only playlist for the stream. For Video only. Usually ends with .m3u8.

std::vector<std::string> hls_characteristics

Optional for HLS output. It defines the CHARACTERISTICS attribute of the stream.

std::vector<std::string> dash_accessiblities

Optional for DASH output. It defines Accessibility elements of the stream.

std::vector<std::string> dash_roles

Optional for DASH output. It defines Role elements of the stream.

struct Mp4OutputParams

MP4 (ISO-BMFF) output related parameters.

Public Members

bool include_pssh_in_stream = true

Include pssh in the encrypted stream. CMAF and DASH-IF recommends carrying license acquisition information in the manifest and not duplicate the information in the stream. (This is not a hard requirement so we are still CMAF compatible even if pssh is included in the stream.)

bool generate_sidx_in_media_segments = true

Indicates whether a ‘sidx’ box should be generated in the media segments. Note that it is required by spec if segment_template contains $Times$ specifier.

struct ChunkingParams

Chunking (segmentation) related parameters.

Public Members

double segment_duration_in_seconds = 0

Segment duration in seconds.

double subsegment_duration_in_seconds = 0

Subsegment duration in seconds. Should not be larger than the segment duration.

bool segment_sap_aligned = true

Force segments to begin with stream access points. Actual segment duration may not be exactly what is specified by segment_duration.

bool subsegment_sap_aligned = true

Force subsegments to begin with stream access points. Actual subsegment duration may not be exactly what is specified by subsegment_duration. Setting to subsegment_sap_aligned to true but segment_sap_aligned to false is not allowed.

struct MpdParams

DASH MPD related parameters.

Public Members

std::string mpd_output

MPD output file path.

std::vector<std::string> base_urls

BaseURLs for the MPD. The values will be added as <BaseURL> element(s) under the <MPD> element.

double min_buffer_time = 2.0

Set MPD attribute, which specifies, in seconds, a common duration used in the definition of the MPD representation data rate. A client can be assured of having enough data for continous playout providing playout begins at min_buffer_time after the first bit is received.

double minimum_update_period = 0

Set MPD attribute, which indicates to the player how often to refresh the MPD in seconds. For dynamic MPD only.

double time_shift_buffer_depth = 0

Set MPD attribute, which is the guaranteed duration of the time shifting buffer for ‘dynamic’ media presentations, in seconds.

size_t preserved_segments_outside_live_window = 0

Segments outside the live window (defined by ‘time_shift_buffer_depth’ above) are automatically removed except for the most recent X segments defined by this parameter. This is needed to accommodate latencies in various stages of content serving pipeline, so that the segments stay accessible as they may still be accessed by the player. The segments are not removed if the value is zero.

std::string default_language

The tracks tagged with this language will have <Role … value=”main” /> in the manifest. This allows the player to choose the correct default language for the content. This applies to both audio and text tracks. The default language for text tracks can be overriden by ‘default_text_language’.

std::string default_text_language

Same as above, but this overrides the default language for text tracks, i.e. subtitles or close-captions.

bool generate_static_live_mpd = false

Generate static MPD for live profile. Note that this flag has no effect for on-demand profile, in which case static MPD is always used.

bool generate_dash_if_iop_compliant_mpd = true

Try to generate DASH-IF IOP compliant MPD.

bool allow_approximate_segment_timeline = false

For live profile only. If enabled, segments with close duration (i.e. with difference less than one sample) are considered to have the same duration. This enables MPD generator to generate less SegmentTimeline entries. If all segments are of the same duration except the last one, we will do further optimization to use SegmentTemplate instead and omit SegmentTimeline completely. Ignored if $Time$ is used in segment template, since $Time$ requires accurate Segment Timeline.

double target_segment_duration = 0

This is the target segment duration requested by the user. The actual segment duration may be different to the target segment duration. This parameter is included here to calculate the approximate SegmentTimeline if it is enabled. It will be populated from segment duration specified in ChunkingParams if not specified.

Public Static Attributes

constexpr double kSuggestedPresentationDelayNotSet = 0

Set MPD attribute. For ‘dynamic’ media presentations, it specifies a delay, in seconds, to be added to the media presentation time. The attribute is not set if the value is 0; the client is expected to choose a suitable value in this case.

struct UtcTiming

UTCTimings. For dynamic MPD only.

struct HlsParams

HLS related parameters.

Public Members

HlsPlaylistType playlist_type = HlsPlaylistType::kVod

HLS playlist type. See HLS specification for details.

std::string master_playlist_output

HLS master playlist output path.

std::string base_url

The base URL for the Media Playlists and media files listed in the playlists. This is the prefix for the files.

double time_shift_buffer_depth = 0

Defines the live window, or the guaranteed duration of the time shifting buffer for ‘live’ playlists.

size_t preserved_segments_outside_live_window = 0

Segments outside the live window (defined by ‘time_shift_buffer_depth’ above) are automatically removed except for the most recent X segments defined by this parameter. This is needed to accommodate latencies in various stages of content serving pipeline, so that the segments stay accessible as they may still be accessed by the player. The segments are not removed if the value is zero.

std::string key_uri

Defines the key uri for “identity” and “com.apple.streamingkeydelivery” key formats. Ignored if the playlist is not encrypted or not using the above key formats.

std::string default_language

The renditions tagged with this language will have ‘DEFAULT’ set to ‘YES’ in ‘EXT-X-MEDIA’ tag. This allows the player to choose the correct default language for the content. This applies to both audio and text tracks. The default language for text tracks can be overriden by ‘default_text_language’.

std::string default_text_language

Same as above, but this overrides the default language for text tracks, i.e. subtitles or close-captions.

double target_segment_duration = 0

This is the target segment duration requested by the user. The actual segment duration may be different to the target segment duration. It will be populated from segment duration specified in ChunkingParams if not specified.

enum shaka::HlsPlaylistType

Defines the EXT-X-PLAYLIST-TYPE in the HLS specification. For HlsPlaylistType of kLive, EXT-X-PLAYLIST-TYPE tag is omitted.

Values:

kVod

kEvent

kLive

enum shaka::KeyProvider

Encryption / decryption key providers.

Values:

kNone = 0

kWidevine = 1

kPlayReady = 2

kRawKey = 3

struct WidevineSigner

Signer credential for Widevine license server.

Public Members

std::string signer_name

Name of the signer / content provider.

SigningKeyType signing_key_type = SigningKeyType::kNone

Specifies the signing key type, which determines whether AES or RSA key are used to authenticate the signer. A type of ‘kNone’ is invalid.

std::vector<uint8_t> key

AES signing key.

std::vector<uint8_t> iv

AES signing IV.

std::string key

RSA signing private key.

enum shaka::WidevineSigner::SigningKeyType

Values:

kNone

kAes

kRsa

struct WidevineEncryptionParams

Widevine encryption parameters.

Public Members

std::string key_server_url

Widevine license / key server URL.

std::vector<uint8_t> content_id

Content identifier.

std::string policy

The name of a stored policy, which specifies DRM content rights.

WidevineSigner signer

Signer credential for Widevine license / key server.

std::vector<uint8_t> group_id

Group identifier, if present licenses will belong to this group.

bool enable_entitlement_license

Enables entitlement license when set to true.

struct PlayReadyEncryptionParams

PlayReady encryption parameters. key_server_url and program_identifier are required. The presence of other parameters may be necessary depends on server configuration.

Public Members

std::string key_server_url

PlayReady license / key server URL.

std::string program_identifier

PlayReady program identifier.

std::string ca_file

Absolute path to the Certificate Authority file for the server cert in PEM format.

std::string client_cert_file

Absolute path to client certificate file.

std::string client_cert_private_key_file

Absolute path to the private key file.

std::string client_cert_private_key_password

Password to the private key file.

struct RawKeyParams

Raw key encryption/decryption parameters, i.e. with key parameters provided.

Public Members

std::vector<uint8_t> iv

An optional initialization vector. If not provided, a random iv will be generated. Note that this parameter should only be used during testing. Not needed for decryption.

std::vector<uint8_t> pssh

Inject a custom pssh or multiple concatenated psshs. If not provided, a common system pssh will be generated. Not needed for decryption.

std::map<StreamLabel, KeyInfo> key_map

Defines the KeyInfo for the streams. An empty StreamLabel indicates the default KeyInfo, which applies to all the StreamLabels not present in key_map.

struct EncryptionParams

Encryption parameters.

Public Types

enum ProtectionSystem

Supported protection systems.

Values:

kCommonSystem

kFairPlay

kMarlin

kPlayReady

kWidevine

Public Members

KeyProvider key_provider = KeyProvider::kNone

Specifies the key provider, which determines which key provider is used and which encryption params is valid. ‘kNone’ means not to encrypt the streams.

std::vector<ProtectionSystem> protection_systems

Protection systems to be generated.

double clear_lead_in_seconds = 0

Clear lead duration in seconds.

bool vp9_subsample_encryption = true

Enable/disable subsample encryption for VP9.

std::function<std::string(const EncryptedStreamAttributes &stream_attributes)> stream_label_func

Stream label function assigns a stream label to the stream to be encrypted. Stream label is used to associate KeyPair with streams. Streams with the same stream label always uses the same keyPair; Streams with different stream label could use the same or different KeyPairs. A default stream label function will be generated if not set.

Public Static Attributes

constexpr uint32_t kProtectionSchemeCenc = 0x63656E63

The protection scheme: “cenc”, “cens”, “cbc1”, “cbcs”.

constexpr double kNoKeyRotation = 0

Crypto period duration in seconds. A positive value means key rotation is enabled, the key provider must support key rotation in this case.

struct EncryptedStreamAttributes

Encrypted stream information that is used to determine stream label.

struct WidevineDecryptionParams

Widevine decryption parameters.

Public Members

std::string key_server_url

Widevine license / key server URL.

WidevineSigner signer

Signer credential for Widevine license / key server.

struct DecryptionParams

Decryption parameters.

Public Members

KeyProvider key_provider = KeyProvider::kNone

Specifies the key provider, which determines which key provider is used and which encryption params is valid. ‘kNone’ means not to decrypt the streams.

class Status

Public Functions

Status()

Creates a “successful” status.

Status(error::Code error_code, const std::string &error_message)

Create a status with the specified code, and error message. If “error_code == error::OK”, error_message is ignored and a Status object identical to Status::OK is constructed.

void Update(Status new_status)

If “ok()”, stores “new_status” into *this. If “!ok()”, preserves the current “error_code()/error_message()”,

Convenient way of keeping track of the first error encountered. Instead of: if (overall_status.ok()) overall_status = new_status Use: overall_status.Update(new_status);

std::string ToString() const

Return

A combination of the error code name and message.

enum shaka::error::Code

Error codes for the packager APIs.

Values:

OK

UNKNOWN

CANCELLED

INVALID_ARGUMENT

UNIMPLEMENTED

FILE_FAILURE

END_OF_STREAM

HTTP_FAILURE

PARSER_FAILURE

ENCRYPTION_FAILURE

CHUNKING_ERROR

MUXER_FAILURE

FRAGMENT_FINALIZED

SERVER_ERROR

INTERNAL_ERROR

STOPPED

TIME_OUT

NOT_FOUND

ALREADY_EXISTS

TRICK_PLAY_ERROR