-
Notifications
You must be signed in to change notification settings - Fork 4
config example
Regarding the theoretical description of the configuration, this page will have closer look on a practical example on the project configuration.
This basic example assumes the pre-knowledge from the setup example. If you have not attended this example yet, here's a short summary: In basic all pre-requirements have been setup. StreamSim has been packed into a separate folder at /home/myuser/stream-sim and a first stream sim project, named "proj1", has been setup at /home/myuser/proj1.
Furthermore this tutorial assumes, that three videos have been packet into proj1's srcVid directory: vidA.avi, vidB.avi, vidC.avi.
[TIP]In general it is recommended to open the configuration csv files in an usual text editor and not in a table calculation tool, due to a cleaner overview. If you prefer to use a table calculation tool, ensure that the semicolon symbol is used as column separator.
Adding AVI files into the srcVid folder will not enable control on them from the tool chain's side. Therefore they have to be reigstered in a separate source list, located in /home/myuser/proj1/config/src.csv. Open the file in a usual text editor, like gedit, will deliver you the following content:
# SRC
# ===
#
# In this csv file you are able to specify which link resources should be used to perform operations on in the processing
# chain. Be aware that each file listed here must exists in the "srcVid" folder.
#
# Fields:
# -------
#
# * <type 'int'> src_id : unique id to identify each individual source
#
# * <type 'str'> src_name : unique name to identify the source file in the folder "srcVid"
#
# * <type 'str'> res : video frame resolution in px
#
# * <type 'int'> fps : number of frames to encode the video with (unit: frame/s)
#
#
# Annotation:
# -----------
#
# The table columns are separated by a semicolon!
#
src_id;src_name;res;fps
Above you can see the main header comment, describing what the table configures and the individual configuration field descriptions. Beneath in the last line the csv-specific configuration field names are given.
[TIP]Lines starting with a hash tag ("#") will be generally ignored during the parsing, neglecting there position in the document. So you are able to add several comments for a specific configuration or to comment specific lines out, if you do not want to remove them but do not currently require them. Further more you can put an arbitrary set of empty lines into the document if you need them in order to ensure a clean overview. These lines will be ignored during the parsing too.
Now, let's register the three videos, by adding the following text to our document and saving it.
# VIDEO A
0;vidA.avi;1366x768;25
# VIDEO B
1;vidB.avi;3840x2160;25
# VIDEO C
2;vidC.avi;7680x4320;25
After the source videos have been registered, several HRC settings can be configured, which should be applied on the videos. An HRC is a set of configurations defining the settings which should be applied during encoding, streaming and stream manipulation. It is possible to connect the HRCs with the SRC sets from the src.csv via a so-called PVS matrix. Furthermore a SRC set may be used multiply for different HRC sets. The linking between HRC and SRC sets will be explained in a separate section. The current section will more concentrate on setting up different HRCs.
Before we'll get closer into detail let's have a look at the hrc.csv located next to the src.csv:
# HRC
# ===
#
# In this csv file you are able to link different settings together which can be applied on an arbitrary source.
#
# Fields:
# -------
#
# * <type 'int'> hrc_id : unique id for each individual HRC data set used to reference it
#
# * <type 'int'> encoding_id : id of the settings used for encoding (Defined in the hrc/encoding.csv file)
#
# * <type 'int'> packet_loss_id : id of the settings used for packet manipulation (Defined in the hrc/packet_loss.csv
# file)
#
# * <type 'str'> coder_id : name of the coder to use for encoding, streaming and decoding
#
# * <type 'str'> stream_mode : mode in which the file should be streamed
#
# >> mpegts-rtp
# >> mpegts-udp
# >> raw-rtp
#
#
# Annotation:
# -----------
#
# The table columns are separated by a semicolon!
#
hrc_id;encoding_id;packet_loss_id;coder_id;stream_mode
As you can see this file will mainly connect setting of of other configuration files in one data set. Only the stream_mode field is separate. Before we will add HRC configurations, we will add some further encoding and packet loss datasets to the files located in the hrc dir (/home/myuser/proj1/config/hrc/*.csv). After we are done with that we will return to the hrc.csv file and add the appropriate settings.
Before we will set up an encoding set, we will configure a codec setting. Therefore we will open an appropriate configuration file from the codec-folder (/home/myuser/proj1/codec). Therein you'll find configuration files for each supported codec. You are invited to develop further ones. Regard therefore our codec development guide.
In this example we want to set only a configuration for the H.265 codec. Open therefore the x265.csv file: /home/myuser/proj1/codec/x265.csv
# X265
# ====
#
# In this csv file you are able to define multiple individual x265 settings which can be applied for video encoding
# techniques in the context of the processing chain.
#
# Fields:
# -------
#
# * <type 'int'> codec_settings_id : unique integer value identifying the data set
#
# * <type 'str'> preset : preset according to https://trac.ffmpeg.org/wiki/Encode/H.264#crf
#
# >> ultrafast
# >> superfast
# >> veryfast
# >> faster
# >> fast
# >> medium
# >> slow
# >> slower
# >> veryslow
# >> placebo
#
# * <type 'int'> crf : quantizer scale according to https://trac.ffmpeg.org/wiki/Encode/H.264#crf
#
# * <type 'int'> keyint : similiar to gop length; defines the maximum number of frames between two I-frames
#
# * <type 'int'> min-keyint : minimum distance between two I-frames
#
# * <type 'int'> merange : motion search range [default: 57]
#
# * <type 'str'> me : motion search method
#
# >> dia
# >> hex [default]
# >> umh
# >> star
# >> full
#
# * <type 'str'> bpyramid : use, if possible, b-frames as references
#
# * <type 'int'> bframes : max number of consecutive b-frames
#
#
# Annotation:
# -----------
#
# The table columns are separated by a semicolon!
#
codec_settings_id;preset;crf;keyint;min-keyint;merange;me;bpyramid;bframes
Add now the following lines and save the document:
0;;;25;;;;strict;3
[TIP]If you do not want to fill out a special column, because a default value is therefore provided, you can leave it blank.
After the codec settings have been set, we can link them in the encoding.csv file (/home/myuser/proj1/config/hrc/encoding.csv).
# ENCODING
# ========
#
# In this csv file you are able to specify different sets of encoding settings which can be used by different encoders,
# to encode an arbitrary video source.
#
# Fields:
# -------
#
# * <type 'int'> encoding_id : unique id to identify the encoding data set
#
# * <type 'str'> codec_id : unique name id to identify the codec used for the encoding operation
#
# * <type 'int'> codec_settings_id : id to link these settings with the codec's appropriate settings
#
# * <type 'int'> bit_rate : bit rate the video should be encoded with (unit: kbit/s)
#
# * <type 'bool'> two-pass : 0 if one-pass encoding should be used, 1 otherwise
#
# * <type 'str'> alt_cmd_line : Instead of using the flexible and generic encoding table system, you can also define
# here a complete command line which will be then executed. Note that you are
# responsible by your own for the validity of this command line. A wrong command line
# might arise an undesired behaviour with wrong results! You can use the following
# parameters as generic variables within your command line
#
# >> __SRC_PATH__ : The complete path of the source video including
# the source file name
# >> __FPS_VALUE__ : The fps value of the appropriate source defined in
# the source table
# >> __OUT_PATH__ : The complete path of the destination where to save
# the encoded video (usually not required, is added
# automatically at the line's end)
# >> __RES_VALUE__ : The res value of the appropriate source defined in
# the source table
#
#
# Annotation:
# -----------
#
# The table columns are separated by a semicolon!
#
encoding_id;codec_id;codec_settings_id;bit_rate;two-pass;alt_cmd_line
Add now the following lines and save the document:
10;x265;0;1000;0;
25;x265;0;2500;0;
50;x265;0;5000;0;
[TIP]As you can see the field IDs do not have to be hardly consecutive. It is just enough when they are greater or equal zero. So you can use the IDs in order to improve the overview. In this example, the IDs give at the same a clue about the encoding bitrate (10 -> 1000, 25 -> 2500, 50 -> 5000).
Now it is time to configure the packet manipulation behaviour. For simplicities sake we will not consider packet manipulation in this example and just define a data set which can be used in order to configure the NO_LOSS-case. Open therefore the packet_loss.csv file located at /home/myuser/proj1/config/hrc/packet_loss.csv:
# PACKET_LOSS
# ===========
#
# In this csv file you are able to set settings for packet loss manipulation, which can be applied on different streamed
# sources.
#
# Fields:
# -------
#
# * <type 'int'> packet_loss_id : unique id identifying the packet loss settings
#
# * <type 'str'> manipulator_tool : name of the manipulator tool to use
#
# >> none
# >> tc
# >> telchemy
#
# * <type 'int'> manipulator_tool_id : unique id which refers to the manipulator's specific settings
#
#
# Annotation:
# -----------
#
# The table columns are separated by a semicolon!
#
packet_loss_id;manipulator_tool;manipulator_tool_id
Add now the following line to the document and save it:
0;none;
Finally we can link the encoding and packet loss settings together in one file. Therefore add the following lines to the hrc.csv file opened above:
# ID naming convention
# bitrate|loss_rate|(1 = mpegts-rtp, 2 = mpegts-udp, ...)
#
# NO LOSS
#
# bitrate 1000
1001;10;0;ffmpeg;mpegts-rtp
1002;10;0;ffmpeg;mpegts-udp
# bitrate 2500
2501;25;0;ffmpeg;mpegts-rtp
2502;25;0;ffmpeg;mpegts-udp
# bitrate 5000
5001;50;0;ffmpeg;mpegts-rtp
5002;50;0;ffmpeg;mpegts-udp
At the last step we can now link our sources from the src.csv file with the settings from the hrc.csv file. Therefore you should open the pvs.csv (located at /home/myuser/proj1/config/pvs.csv).
# PVS
# ===
#
# In this csv-file you are able to link sources with different HRC settings multiply. Remember to set for each individual
# connection a unique id.
#
# Fields:
# -------
#
# * <type 'int'> pvs_id : unique id for each connection
#
# * <type 'int'> src_id : id of the source (specified in the source table) to link with the HRC
#
# * <type 'int'> hrc_id : id of the HRC setting to link with the source
#
#
# Annotation:
# -----------
#
# The table columns are separated by a semicolon!
#
pvs_id;src_id;hrc_id
You can think of an arbitrary connection. E.g. if you want to apply HRC 1001 on SRC 1, you just need to add the following line:
10010;0;1001
Be aware that also a different ID is possible. You can add further linkings if you like.