Configuration Field Reference

There are two config files required by Shaka Streamer: one to describe the inputs, and one to describe the encoding pipeline. Through the module API, these are taken as dictionaries. Through the command-line front-end, these are parsed as YAML files.

(If you aren’t familiar with YAML, it fills many of the same roles as JSON, except that it’s more readable and can contain comments.)

If you are just getting started with Shaka Streamer, you should probably look in the config_files/ folder and browse through some examples. If you are trying to customize one of those examples or get more details on supported options, this document is for you.

Input Configs

The input config describes the inputs. In general, each needs to have an input type (such as a looped file), a media type (such as video), and a name (such as a file path). Other fields may be required for certain types.

An input config is generally composed of multiple inputs, such as one high-res video, one audio input per language, and possibly some subtitle or caption files.

class streamer.input_configuration.InputConfig(dictionary: Dict[str, Any])

Bases: streamer.configuration.Base

An object representing the entire input config to Shaka Streamer.

multiperiod_inputs_list = : list of SinglePeriod

A list of SinglePeriod objects

inputs = : list of Input

A list of Input objects

class streamer.input_configuration.Input(*args)

Bases: streamer.configuration.Base

An object representing a single input stream to Shaka Streamer.

input_type = : InputType (one of 'file', 'looped_file', 'webcam', 'microphone', 'external_command')

The type of the input.

name = : string

Name of the input.

With input_type set to ‘file’, this is a path to a file name.

With input_type set to ‘looped_file’, this is a path to a file name to be looped indefinitely in FFmpeg.

With input_type set to ‘webcam’, this is which webcam. On Linux, this is a path to the device node for the webcam, such as ‘/dev/video0’. On macOS, this is a device name, such as ‘default’.

With input_type set to ‘external_command’, this is an external command that generates a stream of audio or video. The command will be parsed using shell quoting rules. The command should send its generated output to the path in the environment variable $SHAKA_STREAMER_EXTERNAL_COMMAND_OUTPUT, which Shaka Streamer set to the path to the output pipe.

extra_input_args = : string

Extra input arguments needed by FFmpeg to understand the input.

This allows you to take inputs that cannot be understand or detected automatically by FFmpeg.

This string will be parsed using shell quoting rules.

media_type = : MediaType (one of 'audio', 'video', 'text')

The media type of the input stream.

track_num = : int

The track number of the input.

The track number is specific to the media_type. For example, if there is one video track and two audio tracks, media_type of ‘audio’ and track_num of ‘0’ indicates the first audio track, not the first track overall in that file.

If unspecified, track_num will default to 0, meaning the first track matching the media_type field will be used.

start_time = : string

The start time of the slice of the input to use.

Only valid for VOD and with input_type set to ‘file’.

Not supported with media_type of ‘text’.

end_time = : string

The end time of the slice of the input to use.

Only valid for VOD and with input_type set to ‘file’.

Not supported with media_type of ‘text’.

drm_label = : string

Optional value for a custom DRM label, which defines the encryption key applied to the stream. If not provided, the DRM label is derived from stream type (video, audio), resolutions, etc. Note that it is case sensitive.

Applies to ‘raw’ encryption_mode only.

skip_encryption = : int

If set, no encryption of the stream will be made

filters = : list of string

A list of FFmpeg filter strings to add to the transcoding of this input.

Each filter is a single string. For example, ‘pad=1280:720:20:20’.

Not supported with media_type of ‘text’.

is_interlaced = : bool

True if the input video is interlaced.

Only valid for media_type of ‘video’.

If true, the video will be deinterlaced during transcoding.

Can be auto-detected for some input types, but may be default to False for others. For example, an input_type of ‘external_command’, it will default to False.

frame_rate = : float

The frame rate of the input stream, in frames per second.

Only valid for media_type of ‘video’.

Can be auto-detected for some input types, but may be required for others. For example, required for input_type of ‘external_command’.

resolution = : VideoResolution name (one of '144p', '240p', '360p', '480p', '576p', '720p', '720p-hfr', '1080p', '1080p-hfr', '1440p', '1440p-hfr', '4k', '4k-hfr', '8k', '8k-hfr')

The name of the input resolution (1080p, etc).

Only valid for media_type of ‘video’.

Can be auto-detected for some input types, but may be required for others. For example, required for input_type of ‘external_command’.

channel_layout = : AudioChannelLayout name (one of 'mono', 'stereo', 'surround')

The name of the input channel layout (stereo, surround, etc).

language = : string

The language of an audio or text stream.

With input_type set to ‘file’ or ‘looped_file’, this will be auto-detected. Otherwise, it will default to ‘und’ (undetermined).

exception streamer.input_configuration.InputNotFound(input)

Bases: streamer.configuration.ConfigError

An error raised when an input stream is not found.

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class_ref

A reference to the config class that the error refers to.

class_name

The name of the config class that the error refers to.

field_name

The name of the field that the error refers to.

field

The Field metadata object that the error refers to.

class streamer.input_configuration.InputType(value)

Bases: enum.Enum

An enumeration.

FILE = 'file'

A track from a file. Usable only with VOD.

LOOPED_FILE = 'looped_file'

A track from a file, looped forever by FFmpeg. Usable only with live.

Does not support media_type of ‘text’.

WEBCAM = 'webcam'

A webcam device. Usable only with live.

The device path should be given in the name field. For example, on Linux, this might be /dev/video0.

Only supports media_type of ‘video’.

MICROPHONE = 'microphone'

A microphone device. Usable only with live.

The device path should given in the name field. For example, on Linux, this might be “default”.

Only supports media_type of ‘audio’.

EXTERNAL_COMMAND = 'external_command'

An external command that generates a stream of audio or video.

The command should be given in the name field, using shell quoting rules. The command should send its generated output to the path in the environment variable $SHAKA_STREAMER_EXTERNAL_COMMAND_OUTPUT, which Shaka Streamer set to the path to the output pipe.

May require the user of extra_input_args if FFmpeg can’t guess the format or framerate.

Does not support media_type of ‘text’.

class streamer.input_configuration.MediaType(value)

Bases: enum.Enum

An enumeration.

AUDIO = 'audio'

VIDEO = 'video'

TEXT = 'text'

class streamer.input_configuration.SinglePeriod(dictionary: Dict[str, Any])

Bases: streamer.configuration.Base

An object representing a single period in a multiperiod inputs list.

inputs = : list of Input

Pipeline Configs

The pipeline config describes the encoding pipeline. The only required parameters are the streaming mode (live or VOD) and the resolutions. Everything else has default values, but you may want to customize the codecs, resolutions, availability window, and/or encryption settings.

class streamer.pipeline_configuration.PipelineConfig(*args)

Bases: streamer.configuration.Base

An object representing the entire pipeline config for Shaka Streamer.

streaming_mode = : StreamingMode (one of 'live', 'vod')

The streaming mode, which can be either ‘vod’ or ‘live’.

quiet = : bool

If true, reduce the level of output.

Only errors will be shown in quiet mode.

debug_logs = : bool

If true, output simple log files from each node.

No control is given over log filenames. Logs are written to the current working directory. We do not yet support log rotation. This is meant only for debugging.

hwaccel_api = : string

The FFmpeg hardware acceleration API to use with hardware codecs.

A per-platform default will be chosen if this field is omitted.

See documentation here: https://trac.ffmpeg.org/wiki/HWAccelIntro

resolutions = : list of VideoResolution name (one of '144p', '240p', '360p', '480p', '576p', '720p', '720p-hfr', '1080p', '1080p-hfr', '1440p', '1440p-hfr', '4k', '4k-hfr', '8k', '8k-hfr')

A list of resolution names to encode.

Any resolution greater than the input resolution will be ignored, to avoid upscaling the content. This also allows you to reuse a pipeline config for multiple inputs.

If not set, it will default to a list of all the (VideoResolutionName)s defined in the bitrate configuration.

channel_layouts = : list of AudioChannelLayout name (one of 'mono', 'stereo', 'surround')

A list of channel layouts to encode.

Any channel count greater than the input channel count will be ignored.

If not set, it will default to a list of all the (AudioChannelLayoutName)s defined in the bitrate configuration.

audio_codecs = : list of AudioCodec (one of 'aac', 'opus', 'ac3', 'eac3')

The audio codecs to encode with.

video_codecs = : list of VideoCodec (one of 'h264', 'vp9', 'av1', 'hevc')

The video codecs to encode with.

Note that the prefix “hw:” indicates that a hardware encoder should be used.

manifest_format = : list of ManifestFormat (one of 'dash', 'hls')

A list of manifest formats (dash or hls) to create.

By default, this will create both.

dash_output = : string

Output filename for the DASH manifest, if created.

hls_output = : string

Output filename for the HLS master playlist, if created.

segment_folder = : string

Sub-folder for segment output (or blank for none).

segment_size = : float

The length of each segment in seconds.

segment_per_file = : bool

If true, force each segment to be in a separate file.

Must be true for live content.

availability_window = : int

The number of seconds a segment remains available.

presentation_delay = : int

How far back from the live edge the player should be, in seconds.

update_period = : int

How often the player should fetch a new manifest, in seconds.

encryption = : EncryptionConfig

Encryption settings.

low_latency_dash_mode = : bool

If true, stream in low latency mode for DASH.

utc_timings = : list of UtcTimingPair

UTCTiming schemeIdUri and value pairs for the DASH MPD.

If multiple UTCTiming pairs are provided for redundancy, list the pairs in the order of preference.

Must be set for LL-DASH streaming.

class streamer.pipeline_configuration.StreamingMode(value)

Bases: enum.Enum

An enumeration.

LIVE = 'live'

Indicates a live stream, which has no end.

VOD = 'vod'

Indicates a video-on-demand (VOD) stream, which is finite.

class streamer.pipeline_configuration.ManifestFormat(value)

Bases: enum.Enum

An enumeration.

DASH = 'dash'

HLS = 'hls'

class streamer.pipeline_configuration.ProtectionScheme(value)

Bases: enum.Enum

An enumeration.

CENC = 'cenc'

AES-128-CTR mode.

CBCS = 'cbcs'

AES-128-CBC mode with pattern encryption.

class streamer.pipeline_configuration.ProtectionSystem(value)

Bases: enum.Enum

An enumeration.

WIDEVINE = 'Widevine'

FAIRPLAY = 'FairPlay'

PLAYREADY = 'PlayReady'

MARLIN = 'Marlin'

COMMON = 'CommonSystem'

class streamer.pipeline_configuration.EncryptionMode(value)

Bases: enum.Enum

An enumeration.

WIDEVINE = 'widevine'

Widevine key server mode

RAW = 'raw'

Raw key mode

class streamer.pipeline_configuration.UtcTimingPair(dictionary: Dict[str, Any])

Bases: streamer.configuration.Base

An object containing the attributes for a DASH MPD UTCTiming element

scheme_id_uri = : string

SchemeIdUri attribute to be used for the UTCTiming element

value = : string

Value attribute to be used for the UTCTiming element

class streamer.pipeline_configuration.RawKeyConfig(dictionary: Dict[str, Any])

Bases: streamer.configuration.Base

An object representing a list of keys for Raw key encryption

label = : string

An arbitary string or a predefined DRM label like AUDIO, SD, HD, etc. If not specified, indicates the default key and key_id.

key_id = : hexadecimal string

A key identifier as a 32-digit hex string

key = : hexadecimal string

The encryption key to use as a 32-digit hex string

class streamer.pipeline_configuration.EncryptionConfig(*args)

Bases: streamer.configuration.Base

An object representing the encryption config for Shaka Streamer.

enable = : bool

If true, encryption is enabled.

Otherwise, all other encryption settings are ignored.

encryption_mode = : EncryptionMode (one of 'widevine', 'raw')

Encryption mode to use. By default it is widevine but can be changed to raw.

protection_systems = : list of ProtectionSystem (one of 'Widevine', 'FairPlay', 'PlayReady', 'Marlin', 'CommonSystem')

Protection Systems to be generated. Supported protection systems include Widevine, PlayReady, FairPlay, Marin and CommonSystem.

pssh = : hexadecimal string

One or more concatenated PSSH boxes in hex string format. If this and protection_systems is not specified, a v1 common PSSH box will be generated.

Applies to ‘raw’ encryption_mode only.

iv = : hexadecimal string

IV in hex string format. If not specified, a random IV will be generated.

Applies to ‘raw’ encryption_mode only.

keys = : list of RawKeyConfig

A list of encryption keys to use.

Applies to ‘raw’ encryption_mode only.

content_id = : hexadecimal string

The content ID, in hex.

If omitted, a random content ID will be chosen for you.

Applies to ‘widevine’ encryption_mode only.

key_server_url = : string

The URL of your key server.

This is used to generate an encryption key. By default, it is Widevine’s UAT server.

Applies to ‘widevine’ encryption_mode only.

signer = : string

The name of the signer when authenticating to the key server.

Applies to ‘widevine’ encryption_mode only.

Defaults to the Widevine test account.

signing_key = : hexadecimal string

The signing key, in hex, when authenticating to the key server.

Applies to ‘widevine’ encryption_mode only.

Defaults to the Widevine test account’s key.

signing_iv = : hexadecimal string

The signing IV, in hex, when authenticating to the key server.

Applies to ‘widevine’ encryption_mode only.

Defaults to the Widevine test account’s IV.

protection_scheme = : ProtectionScheme (one of 'cenc', 'cbcs')

The protection scheme (cenc or cbcs) to use when encrypting.

clear_lead = : int

The seconds of unencrypted media at the beginning of the stream.

Custom Bitrate and Resolution Configs

To customize bitrates or resolution, you may provide a third config file defining these. If this config is given, it replaces the default definitions.

class streamer.bitrate_configuration.BitrateConfig(dictionary: Dict[str, Any])

Bases: streamer.configuration.Base

audio_channel_layouts = : dictionary of string to AudioChannelLayout

A map of named channel layouts.

For example, the key would be a name like “stereo”, and the value would be an object with all the parameters of how stereo audio would be encoded (2 channels max, bitrates, etc.).

video_resolutions = : dictionary of string to VideoResolution

A map of named resolutions.

For example, the key would be a name like “1080p”, and the value would be an object with all the parameters of how 1080p video would be encoded (max size, bitrates, etc.)

class streamer.bitrate_configuration.AudioCodec(value)

Bases: enum.Enum

An enumeration.

AAC: str = 'aac'

OPUS: str = 'opus'

AC3: str = 'ac3'

EAC3: str = 'eac3'

class streamer.bitrate_configuration.VideoCodec(value)

Bases: enum.Enum

An enumeration.

H264 = 'h264'

H264, also known as AVC.

VP9 = 'vp9'

VP9.

AV1 = 'av1'

AV1.

HEVC = 'hevc'

HEVC, also known as h.265

class streamer.bitrate_configuration.AudioChannelLayout(dictionary: Dict[str, Any])

Bases: streamer.configuration.RuntimeMap

max_channels = : int

The maximum number of channels in this layout.

For example, the maximum number of channels for stereo is 2.

bitrates = : dictionary of AudioCodec (one of 'aac', 'opus', 'ac3', 'eac3') to bitrate string

A map of audio codecs to the target bitrate for this channel layout.

For example, in stereo, AAC can have a different bitrate from Opus.

This value is a string in bits per second, with the suffix ‘k’ or ‘M’ for kilobits per second or megabits per second.

For example, this could be ‘500k’ or ‘7.5M’.

class streamer.bitrate_configuration.AudioChannelLayoutName

Bases: streamer.configuration.RuntimeMapKeyValidator

A type which will only allow valid AudioChannelLayout names at runtime.

map_class

alias of streamer.bitrate_configuration.AudioChannelLayout

capitalize()

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()

Return a version of the string suitable for caseless comparisons.

center(width, fillchar=' ', /)

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count(sub[, start[, end]]) → int

Return the number of non-overlapping occurrences of substring sub in string S[start:end]. Optional arguments start and end are interpreted as in slice notation.

encode(encoding='utf-8', errors='strict')

Encode the string using the codec registered for encoding.

encoding

The encoding in which to encode the string.

errors

The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith(suffix[, start[, end]]) → bool

Return True if S ends with the specified suffix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. suffix can also be a tuple of strings to try.

expandtabs(tabsize=8)

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

format(*args, **kwargs) → str

Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping) → str

Return a formatted version of S, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

index(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isascii()

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

isdecimal()

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isidentifier()

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

islower()

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isnumeric()

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isprintable()

Return True if the string is printable, False otherwise.

A string is printable if all of its characters are considered printable in repr() or if it is empty.

isspace()

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

istitle()

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isupper()

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

join(iterable, /)

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

ljust(width, fillchar=' ', /)

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()

Return a copy of the string converted to lowercase.

lstrip(chars=None, /)

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

classmethod name() → str

partition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

removeprefix(prefix, /)

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

replace(old, new, count=- 1, /)

Return a copy with all occurrences of substring old replaced by new.

count

Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

rfind(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

rindex(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rpartition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

rsplit(sep=None, maxsplit=- 1)

Return a list of the words in the string, using sep as the delimiter string.

sep

The delimiter according which to split the string. None (the default value) means split according to any whitespace, and discard empty strings from the result.

maxsplit

Maximum number of splits to do. -1 (the default value) means no limit.

Splits are done starting at the end of the string and working to the front.

rstrip(chars=None, /)

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

split(sep=None, maxsplit=- 1)

Return a list of the words in the string, using sep as the delimiter string.

sep

The delimiter according which to split the string. None (the default value) means split according to any whitespace, and discard empty strings from the result.

maxsplit

Maximum number of splits to do. -1 (the default value) means no limit.

splitlines(keepends=False)

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

startswith(prefix[, start[, end]]) → bool

Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

strip(chars=None, /)

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

translate(table, /)

Replace each character in the string using the given translation table.

table

Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()

Return a copy of the string converted to uppercase.

classmethod validate(key)

zfill(width, /)

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

class streamer.bitrate_configuration.VideoResolution(dictionary: Dict[str, Any])

Bases: streamer.configuration.RuntimeMap

max_width = : int

The maximum width in pixels for this named resolution.

max_height = : int

The maximum height in pixels for this named resolution.

max_frame_rate = : float

The maximum frame rate in frames per second for this named resolution.

By default, the max frame rate is unlimited.

bitrates = : dictionary of VideoCodec (one of 'h264', 'vp9', 'av1', 'hevc') to bitrate string

A map of video codecs to the target bitrate for this resolution.

For example, in 1080p, H264 can have a different bitrate from VP9.

This value is a string in bits per second, with the suffix ‘k’ or ‘M’ for kilobits per second or megabits per second.

For example, this could be ‘500k’ or ‘7.5M’.