Solveig Multimedia logo

Batch Processing

Batch files to be supported by the Video Editing SDK for Linux are Extensible Markup Language (XML) with *.xtl extension and structure based on Direct Show Editing Services XTL format.

SDK Batch file structure

This section documents the XTL elements and attributes.

Note: All the elements and attributes are case-sensitive. The values must be quoted(""). For an examples see Batch Samples.

This table contains the basic elements of the XTL file:

Element Description
timelines The timelines element is the root XML node
timeline The timeline element describes particular timeline.
group The group element defines output files parameters
track The track element is container for clip elements it defines common attributes for clips if it is not set
clip Specifies a media source file
task The task element defines operation that is applied to the timeline
effect The effect element defines the effect that is applied to the track
transition The transition element defines the type of transition that is applied to the track
param The param element specifies the value of a property on a clip or track
additional_param The additional_param element specifies the additional params to the preceding tag

timelines Element

The timelines element is the root XML node

Parent/Child information

Parent Children
None, this is the root element timeline

Attributes:

Attribute Possible values Obligation presence Description
version 3 Yes Specifies current version of XTL format

timeline Element

The timeline element describes particular timeline

Parent/Child information

Parent Children
timelines group

Attributes: no attributes specified

group Element

The group element defines output files parameters

Parent/Child information

Parent Children
timeline track, param

Attributes

Attribute Possible values Obligation presence Description
output string with file path name Yes Specifies an output filename with a path
out_type see Output file types No Specifies output file type.
Note: This parameter should be set depending on input format and video audio codec.
By default the value is the same as Input File's type
outdir string with file path Yes Specifies the output files' path for tasks with multiple files output

Output file types:

mpg_ts - MPEG2 transport stram mpg_ves - MPEG2 video elementary stream avc_ves - AVC video elementary stream hevc_ves - HEVC video elementary stream mp4 - MPEG-4 Part 14 format file mxf - Material Exchange Format file

If the transcoding is involved, the group tag must contain param tag to specify the compression parameters the same way as in the task tag.

track Element

The track element is container for clip elements it defines common attributes for clips if it is not set.

Parent/Child information

Parent Children
group clip

Attributes

Attribute Possible values Obligation presence Description
video [-1, n] No Specifies stream number of video ("-1" - means all streams, "0" - means disable stream).
By default video equals to 0.
audio [-1, n] No Specifies stream number of audio ("-1" - means all streams, "0" - means disable stream).
By default audio equals to 0.
text [-1, n] No Specifies stream number of audio ("-1" - means all streams, "0" - means disable stream).
By default text equals to 0.
accuracy [frame, gop] No Specifies accuracy type in trimming operaion:
frame - Frame accuracy,
gop - K-frame (GOP) accuracy.
Default value: "frame" - if supported for the input format and codec, "gop" - otherwise.
flags see Trimm flags No Specifies coma separated options used in trimming operation.
By default no flags set.

Trimm flags

blank - when set in clip, turns a clip as a placeholder of the specified duration to preserve the clip alignments. No video/audio from the file will be delivered to the output file.

audio_silence - generates a silent audio for the specified duration of time.

clip Element

The clip element specifies media source files and start/stop positions of fragments to be kept.

Parent/Child information

Parent Children
track None

Attributes

Attribute Possible values Obligation presence Description
src string with file path name Yes Specifies the path name of the input media file
index string with index file path name Yes Specifies the path name of the input media file' index
video [-1,n] No Specifies the number of video stream. The 0 value means no video stream. The -1 value means - all video streams.
By default video equals to 0.
audio [-1,n] No Specifies the number of audio stream. The 0 value means no audio stream. The -1 value means - all audio streams.
By default audio equals to 0.
text [-1,n] No Specifies the number of text stream. The 0 value means no audio stream. The -1 value means - all text streams.
By default text equals to 0.
start time string No The start time of the fragment. See time format types for details.
The default value represents the beginning of the media file.
stop time string No The stop time of the fragment. See time format types for details.
The default value represents the end of the media file.
length time string No Alternative description of the time. This description is the same as start="00:00:00:00", stop="length".
Should present either start/stop or length.
timeFormat 100ns_units,
time10ms,
position		 No Specifies the format of "start" and "stop" attributes.
If not specified - time10ms
flags see Trimm flags No Specifies coma separated options used in trimming operation. See Trimm flags for details.
By default no flags set.

Time format types:

100ns_units - Value is interpreted as 100ns Units ( 1 sec = 1e7 UNITS) time10ms - Value is set in format "HH:MM:SS.mS" position - Value is set using key words: "begin", "end" bytes - Value is interpreted as bytes count (available only for task element) parts - Value is interpreted as parts count (available only for task element)

task Element

The task element defines operation that is applied to the timeline

Parent/Child information

Parent Children
group param

Attributes

Attribute Possible values Obligation presence Description
type transcoding Yes Specifies the task type. See Task types for details
time time string No Specifies the time parameter for task
timeFormat 100ns_units,
time10ms,
parts,
bytes		 No Specifies how to interpret value specified in time attribute. See time format types.
By default timeFormat equals to time10ms.

Task types:

transcoding - The files on the timeline must be transcoded with the parameters specified in a child param tag.

Available params:

  • reference_file

    <param name="reference_file" value="val"/>

    The parameter's value attribute is interpreted as a name of file that contains the compression parameters. Required for the transcoding. Can also be a child of the group tag.

  • vcodec

    <param name="vcodec" value="val"/>

    The parameter's value attribute is interpreted as a comma-separated list of the video compression parameters in the form of name=value. Similar to the reference_file. Available parameters for the video compression are as follows:

    Name Possible values Obligation presence Description
    type h264 Yes Specifies the compression codec
    width [1, n] No Specifies the width of the output video in pixels
    height [1, n] No Specifies the height of the output video in pixels
    bitrate [1000, n] No Specifies the average bitrate of the output video in bits/s
    fps_n [1, n] Only with fps_d Specifies the numerator of the FPS value
    fps_d [1, n] Only with fps_n Specifies the dennominator of the FPS value
    profile baseline
    main
    high
    high10
    high422
    high444    		 No Specifies the compression profile

  • acodec

    <param name="acodec" value="val"/>

    the parameter's value attribute is interpreted as a comma-separated list of the video compression parameters in the form of name=value. Similar to the reference_file. Available parameters for the audio compression are as follows:

    Name Possible values Obligation presence Description
    type aac Yes Specifies the compression codec
    rate [8000, n] No Specifies sampling rate of sampling frequency for the compressed audio in Hz, most common values are 44100 and 48000
    channels [1, n] No Specifies the number of channels in the compressed audio
    bitrate [1000, n] No Specifies the average bitrate of the output video in bits/s
    profile LC
    MAIN    		 No Specifies the compression profile

effect Element

The effect element defines the effect that is applied to the clips in the current track

Parent/Child information

Parent Children
track param

Attributes

Attribute Possible values Obligation presence Description
type transparency Yes Specifies the effect type by name.
start time string Yes Specifies the effect start time.
stop time string Yes Specifies the effect stop time.
timeFormat See time format types. No Specifies how to interpret value specified in time attribute.
By default timeFormat equals to time10ms.

Effect types:

transparency - Applied to the video stream of the parent track tag. Must contain additional param tags. Available params:

  • alpha

    <param name="alpha" value="val">

    The parameter's value attribute is interpreted as a transparency and stores the initial value of the transparency. This type of param tag must include a child tag with a description of the value variation function, which will also contain the destination value of the parameter that the initial value will be changed to. Available values: (0 - 255)

  • bkcolor

    <param name="bkcolor" value="val" />

    The parameter's value attribute is interpreted as a name of the backgroung color. Available values: "transparent", "black"

chroma_key - Applies Chroma key effect to the video stream of the parent track tag. Must contain additional param tags.

Available params:

  • r,g,b

    <param name="r" value="val"/>
<param name="g" value="val"/>
<param name="b" value="va"/>

    Defines the main key color RGB components for the effect

    Available values: (0 - 255)

  • similarity

    <param name="similarity" value="val"/>

    Defines the threshold applied when compare source pixels with the main key color. Higher value will remove more pixels.

    Available values: (0 - 1000)

  • smoothness

    <param name="smoothness" value="val"/>

    Defines the smoothness for the pixels that are neighbors to removed pixel. Lower values leave hard edges around removed pixels; higher values soften the edge of removed areas

    Available values: (0 - 1000)

  • spill

    <param name="spill" value="val"/>

    Specifies how aggressively to remove traces of the key color around the edge of other colors (for example, green pixels around a subject's hair)

    Available values: (0 - 1000)

  • opacity

    <param name="opacity" value="val"/>

    Sets the opacity of the resulted opaque pixels after key color remove. 0 - transparent; 255 - is opaque

    Available values: (0 - 255)

  • brightness, contrast, gamma

    <param name="brightness" value="val"/>
<param name="contrast" value="val"/>
<param name="gamma" value="val"/>

    Changes the brightness, contrast, gamma parameters of the resulted opaque image.

    Available values: (0 - 100)

volume - Applied to the audio stream of the parent track tag. Must contain additional param tags. Available params:

  • volume

    <param name="volume" value="val">

    The parameter's value attribuate is interpreted as a volume value in percent of original value Available values: (0 - 1000)

transition Element

The transition element defines the type of transition that is applied to the track

Parent/Child information

Parent Children
track none

Attributes

Attribute Possible values Obligation presence Description
type See transition types Yes Specifies the transition type by name.
start time string Yes Specifies the effect start time.
stop time string Yes Specifies the effect stop time.
timeFormat See time format types. No Specifies how to interpret value specified in time attribute.
By default timeFormat equals to time10ms.

Transition types:

mix - Affected tracks will be mixed together. Streams to be mixed are specified in the transition's parent track tag. Available params:

  • audio 
    <param name="audio", value="val">
    the parameter's value attribute is interpreted as an ordered number of the audio stream trom the main track where current audio will be mixed. Available values: (1 - Total Audio Streams)

pip - one of the affected tracks will be overlaid on the other. Requires the destination rectangle description in child param tags.

Available params:

  • x, y

    <param name="x", value="val">
<param name="y", value="val">

    the parameter's value attribute is interpreted as a position in pixels.

  • width, height

    <param name="width", value="val">
<param name="height", value="val">

    the parameter's value attribute is interpreted as dimensions in pixels.

param Element.

Parent/Child information

Parent Children
group, transition, effect None

Attributes

Attribute Possible values Obligation presence Description
name string Yes Specifies the parameter name
value string Yes Specifies the parameter value

Available values are listed in the related parent tags.

Value variation functions

Specifies the type of function to be applied for the values variations.

Parent/Child information

Parent Children
param None

Only the linear function is supported:

<linear attribute="value">

Attributes

Attribute Possible values Obligation presence Description
value [0, 255] Yes Specifies the destination value of the parent pamameter's tag
start time string No The start time of the fragment. See time format types for details.
The default value represents the beginning of the media file.
stop time string No The stop time of the fragment. See time format types for details.
The default value represents the end of the media file.
length time string No Alternative description of the time. This description is the same as start="00:00:00:00", stop="length".
Should present either start/stop or length.
timeFormat 100ns_units,
time10ms,
position		 No Specifies the format of "start" and "stop" attributes.
If not specified - time10ms

additional_param Element.

Parent/Child information

Parent Children
Any None

This tag is applied to the preceding tag and extends its parameters. Currently applied to the track tag.

Attributes

Attribute Possible values Obligation presence Description
video [1, n] No Specifies the additional video stream number to be processed
audio [1, n] No Specifies the additional audio stream number to be processed
text [1, n] No Specifies the additional text stream number to be processed

Copyright © Solveig Multimedia, 2009-2024