Openshot-qt: Contribute on development

Created on 13 Jul 2018 · 14Comments · Source: OpenShot/openshot-qt

HI
my company is interested in developing a plugin or an interface in order to make our custom video file format compatible with OpenShot. We operate on Windows. I've yet developed plugin interface for VLC (crosscompiling from Debian Linux) and ffmpeg (compiled under Windows with minGW). I have some questions:
Did you have a starting tutorial in order to develop plugins ?
Did you suggest to develop under windows or crosscompiling from linux ?
Did you have some writing rules used in development ?
Regards
Francesco

question

Source

francescoBLT

All 14 comments

Um... @DylanC - Do you know anything about this, Cap'ain? @N3WWN ?

@francescoBLT - While I don't know much about the things under-the-hood in OpenShot, perhaps if the company wants to make some contributions, this would be a good starting guide. Hopefully someone else will soon be able to answer the rest of your questions.

peanutbutterandcrackers on 14 Jul 2018

@peanutbutterandcrackers - I don't think we support plugins as far as I know. Maybe they could just contribute the features they need. However, the features would have to be acceptable in terms of what this project plans to be feature wise.

DylanC on 14 Jul 2018

@francescoBLT - Hi there, do you have details on what this custom format is?

DylanC on 14 Jul 2018

@peanutbutterandcrackers - If they use a package of OpenShot that uses the system ffmpeg, import support may "just work" because it looks like libopenshot will try to open any file supported by ffmpeg, but output support would probably need to be added into openshot-qt (a preset?) to have a persistent output format. Manually setting the output format via the Export Video->Advanced->Video Settings may work, too.

N3WWN on 16 Jul 2018

👍1

This guide should probably be a bit helpful, then... Hopefully...

peanutbutterandcrackers on 17 Jul 2018

I apologize for the delay, I wasn't at office. Thanks to all for the answeres, I will study the documentation now. Asap I receive the autorization I will make available a documentation of our format (or, if you have a directory where upload a file it will be better)
Regards
Francesco

francescoBLT on 9 Aug 2018

@francescoBLT - You can provide the details here or attach the file here. Drag and drop to attach the file.

DylanC on 9 Aug 2018

HI to all
I start here with the description of file format. Asap will be available a link from which you can download the complete specification and three clips.
The .blt Multimedia file is composed of three main segments, (the sequence order of segments is mandatory)
BLT HEADER is fixed size and contains metadata, BLT TABLE is the index table used to addres the single
field into the BLT ESSENCE PAYLOAD (the use of table is mandatory for random access). Size of BLT
TABLE and BLT ESSENCE PAYLOAD is function of material content and duration.
First segment of .blt file is the BLT Header, that is 4096 Bytes long (fixed size) and contains miscellaneous
informations and metadata. The header segment is a sequence of entries in ASCII characters in easy human
readable format. Each entry is formed by a TAG followed by PARAMETER and terminated with the sequence
(hexdecimal 0x0A 0x0D). All TAG should be written upper/lower case as listed below, while
reader could disregard the case. The file Signature is the first tag and must be at beginning of file and it is
the only tag without parameter, all other entries and tags can be in any order.
After the last header segment entry, the segment is filled with 0x00 up to the lenght of 4096 Byte.
Tag Parameter
BLTMB01 +
Fixed lenght file Signature, indicating specs reference version, no parameter. This signature
is used by reader to properly verify the file type. This TAG is mandatory and must be at the
beginning of file.
APP: + up to 64 ASCII chars +
Application name that generated the file. This TAG is strongly recommended for the writer in
order to keep track of the source. The reader should accept that this TAG could be missing.
NUMBER: + 5 ASCII digits +
Original Clip number, used by some application for placing in ordered list by this number.
Writer should insert 5 digit numbers, reader should accept less number of digits and also non
numerical characters.
NAME1: + up to 64 ASCII chars +
Clip Name 1, Main description (can be different to file name) used for listing.
This TAG is mandatory
NAME2: + up to 64 ASCII chars +
Clip name2.
NAME3: + up to 64 ASCII chars +
Clip name3.
DURATION: + HH:MM:SS:FF +
Clip duration in Hours/Minutes/Seconds/Frames (if M formats, time is always DF !!!)
This TAG is mandatory
DATE: + YYYY/MM/DD + + HH:MM:SS:FF +
Clip reference date/time, referred to acquisition.
This TAG is mandatory
ID: + 8 ASCII HEX digits + <.> + 4 ASCII HEX digits + <.> + 4 ASCII HEX digits + <.> +
4 ASCII HEX digits + <.>+ 12 ASCII HEX digits + <.> +
Clip unique ID reference number, used to identify material, regardless of name and date; it
helps to distinguish Clips with same name. This TAG is mandatory.
Example: ID: AAAAAAAA.BBBB.CCCC.DDDD.EEEEEEEEEEEE
TYPE: + type +
Fixed parameter value <2>, indicating JPEG2000. To be fully compliant with current specs,
the Writer should include this TAG, the reader can disregards to check this value because
current file Signature is used only with JPEG2000 file type.
FLDPRECISION: + 4KB +
Fixed value <4KB>, indicating 4K Bytes alignment. To be fully compliant with current specs,
the Writer should include this TAG, the reader can disregards to check this value because
current file Signature is used only with 4KByte alignement.
VCHANNEL: + 1 ASCII Char +
Clip source original video channel identification. It indicate which input channel was
ingesting this material, eg. A/B/C/D/E/F/G/H. This TAG is optional and reader should accept
that it could be missing.
VMASK: + 2 ASCII Chars +
Ingesting channel mask. This parameter value is a two char expressing one hexadecimal
value of 8 bits. Each bit set high ("1") means the ingested channel was enabled. This TAG is
optional and if missing it should be considered a single channel file. If this TAG is present,
than it must be used.
VIDEO: + JP2K +
Specify Video essence as JP2K = JPEG 2000. This TAG is mandatory.
ASPECT: + ASCII Char +
Image aspect ratio. Legal values are <4/3> and <16/9>. Reader should expect the
separation between numbers could be or <:>
Tvstandard: + Value +
TV Standard and format. This TAG is mandatory. Legal values are:
<525/60i>, <625/50i>,
<1080/60i>, <1080/50i>, <720/60p>, <720/50p>,
<2160/60p>, <2160/50p>
VTRACK: + Value +
Video Track format. Legal values are:
= Normal (Default)
= Video/Key/Audio (Fill ^ Key)
= 3D/Stereoscopic Left/Right
SSM: + Value +
This TAG, when present, indicate source material is coming from High Speed camera for
SuperSlowMotion. Legal values are: .
AUDIO: + Value +
Specify AUDIO format. Legal value is:
ASAMPLE: + Value +
Specify AUDIO sample rate. Supported value is: <48KHz>
APRECISION: + Value +
Specify Audio sample precision. Supported value is: <16bit>
ACHANNEL: + Value +
Specify number of Audio tracks per each Video tracks. Legal values are <4>, <8> or <16>
INCAMA: + up to 64 ASCII chars +
Label name assigned by user to channel/camera 1
INCAMB: + up to 64 ASCII chars +
Label name assigned by user to channel/camera 2
INCAMC: + up to 64 ASCII chars +
Label name assigned by user to channel/camera 3
INCAMD: + up to 64 ASCII chars +
Label name assigned by user to channel/camera 4
INCAME: + up to 64 ASCII chars +
Label name assigned by user to channel/camera 5
INCAMF: + up to 64 ASCII chars +
Label name assigned by user to channel/camera 6
INCAMG: + up to 64 ASCII chars +
Label name assigned by user to channel/camera 7
INCAMH: + up to 64 ASCII chars +
Label name assigned by user to channel/camera 8
SMSNAM: + up to 64 ASCII chars +
Label name assigned by user to SMS-U Server that generated the Clip
CRDAT: + YYYY/MM/DD + + HH:MM:SS:FF +
Creation date and time of file

francescoBLT on 30 Aug 2018

BLT TABLE SEGMENT

The BLT Table segment begins at fixed file byte offset 4096 (at the end of the BLT Header segment).
The TABLE is composed by one entry for each video FRAME offset location and FIELD size information.
Each entry is 16Bytes long. The Table lenght is function of number of frames (eg. Clip duration) and BLT
Table Segment End is mandatory to be at 4096 Bytes boundary, with zero value fill as required.
Reader must take count that BLT Table Segment could be longer than clip duration: it is a writer option to
round-up this segment at nearest 4096 Bytes boundary, or it could be any lenght up to the maximum allowed
(ie. 24 hours of material), while mantaining the 4096 Bytes boundary and Zero value fill for the unused
entries.
Byte[0:3] Reserved for future use (should be ZERO)
Byte[4:7] TimeCode ( [4]MSB – [7]LSB ), ZERO if not available
Byte[8:12] Big Endian absolute frame Byte offset from file begin (MAX File lenght is 1TByte,
offset alignement is 4096 Bytes as mandatory)
Byte[13] Field 0 (Top) total Lenght (Header / TimeCode / Audio / Video) in 4096 Bytes steps
(MAX lenght is 1MByte)
Byte[14] Field 1 (Bottom) total Lenght (Header / TimeCode / Audio / Video) in 4096 Bytes steps
(MAX lenght is 1MByte)
Byte[15] Reserved for future use (should be ZERO)
Any Frame can be randomly accessed using the Byte offset from file begin value indicated as above listed by
Byte[8:12]; a Frame is composed by two Field (named 0 / 1 or Top / Bottom) and the Lenght of each Field is
respectively specified by Byte[13] and Byte[14] (please note each field can be different size). Lenght is
specified in 4096 Bytes steps and otvis total Field lenght, including Metadata, TimeCode, Audio and Video
essences.
In case the .blt file contains multichannel material (eg. It contains more than one ingested source), each NFrame
channel is followed by N-Frame channel+1: the offset of first channel is indicated by Byte[8:12] and
offset of following channels are given by sum of Byte offset with Field0 and Field1 lenght of previous
channels, taking count all channels Fields0 of N-Frame will have same size as well as all channels Fields1.

francescoBLT on 30 Aug 2018

BLT ESSENCE PAYLOAD SEGMENT

The BLT Essence Payload Segment is made by sequential Frames in a minimum number as per DURATION
Tag in the BLT HEADER; any Frame can be randomly accessed using the byte offset value indicated in the
BLT TABLE SEGMENT; a Frame is composed by two Field (named 0 / 1 or Top / Bottom).
The Lenght of each Field is specified in the BLT TABLE SEGMENT (please note each field can be different
size). Even in case of PROGRESSIVE materials (ie. 720p) the FRAME is composed by two Field, each one
representing a FULL frame picture; in other words, when progressive the frames are grouped two by two for
seamless transition between Interlacved and progressive materials.
Each single FIELD (containing a complete TV Field) of the BLT PAYLOAD ESSENCE segment, is composed
as follow:

The FIELD HEAD is fixed lenght of 16 Bytes and it can be used for identifyng start of FIELD (in case of
streaming). It is mandatory the first part of FIELD and indicates the start.The FIELD HEAD is 4DW with
these fixed values: 0xFFFFFFF8 0x00000000 0x00000000 0x00000000
The FIELD TCD is fixed lenght of 20 Bytes and it carries the Time Code information as per SMPTE12m -
LTC. The FIELD TCD is 5DW with this use:
DW1 is fixed value 0xFFFFFFF4
DW2 + DW3 is SMPTE LTC as below detailed table (8 Bytes)
DW5 + DW5 is used for extended TCD info
TCD bit assignement as per SMPTE12m – LTC
TCD Byte
1 bit [3:0] = FRAME lsb (9..0) bit[7:4] UBIT 3:0
2 bit [1:0] = FRAME Msb (2..0) bit[2] = DF bit[7:4] UBIT
3 bit [3:0] = SEC lsb (9..0) bit[7:4] UBIT
4 bit [2:0] = SEC Msb (5..0) bit[7:4] UBIT
5 bit [3:0] = MIN lsb (9..0) bit[7:4] UBIT
6 bit [2:0] = MIN Msb (5..0) bit[7:4] UBIT
7 bit [3:0] = HOUR lsb (9..0) bit[7:4] UBIT
8 bit [1:0] = HOUR Msb (2..0)
The FIELD AUDIO ESSENCE carries the Audio datas with multitrack capabilities (4/8/16 mono tracks) and it
is composed by a Marker/Header and followed by the Audio payload. The lenght of Audio Payload is variable

in function of the number of Audio tracks and TV Standard (ie. 50Hz or 59.94Hz). The structure is:

| AUDIO MARKER | AUDIO HEADER | AUDIO PAYLOAD |

| 0xFFFFFFF5 | LL ID (2x2 Bytes) | |

The DW of Audio Header indicates the lenght and type of Audio Payload.
Bit[31:16] is the Total Bytes Lenght of FIELD AUDIO ESSENCE (including MARKER+HEADER+PAYLOAD).
Bit[15:0] is Audio ID, with following legal values (at present specs):
0x0083 4 Audio Tracks
0x0087 8 Audio Tracks
0x008F 16 Audio Tracks
Number of Audio Samples per FIELD is 960 with TV Standard 50Hz otherwise it is 802/800 with TV Standard
59.94Hz (the M format). So, the Total Bytes Lenght and ID will have following values:
Lenght Value ID Byte Lenght TV Std DESCRIPTION
0x1E04 0x0083 7684 50Hz 4 Audio Tracks
0x1904/0x1914 0x0083 6404/6420 59.94Hz 4 Audio Tracks
0x3C04 0x0087 15364 50Hz 8 Audio Tracks
0x3204/0x3224 0x0087 12804/12836 59.94Hz 8 Audio Tracks
0x7804 0x008F 30724 50Hz 16 Audio Tracks
0x6404/0x6444 0x008F 25604/25668 59.94Hz 16 Audio Tracks

When TV Standard is 59.94Hz (the M format) the typical lenghts sequence is 5 FIELD long and it is:
800/802/800/802/800. Reader should tolerate different sequences also.
The Audio Payload is composed by sequential values, Little indian ordered (LSB byte first), with ordered
Audio tracks in sequence Sample by Sample, that is:
4 Audio tracks: 1/2/3/4/1/2/3/4 ...
8 Audio tracks: 1/2/3/4/5/6/7/8/1/2/3/4/5/6/7/8 ...
16 Audio tracks: 1/2/3/4/5/6/7/8/9/10/11/12/13/14/15/16/1/2/3/4/5/6/7/8/9/10/11/12/13/14/15/16 ...

francescoBLT on 30 Aug 2018

The FIELD VIDEO ESSENCE carries the compressed Video datas; the current specs of this document
specify JPEG2000 (ISO/IEC 15444-1) as image compression standard wavelet based. Refer to ISO/IEC
15444-1 for deep details about Codec and wavelet details.
The Video essence can be in two flavours: merged (luma and chroma interleaved) or split (luma and
chroma separated). The possible structures are:

MERGED:

| VIDEO MARKER | VIDEO HEADER | VIDEO / JP2K PAYLOAD (Y+C) |

| 0xFFFFFFF0/1 | (12 Bytes) | |

SPLIT:

| 0xFFFFFFF0/1 | Y (12 Bytes) | Y PAYLOAD | 0xFFFFFFF2/3 | U,V (12 Bytes) | U,V PAYLOAD |

VIDEO MARKER VALUES:
MARKER Byte LEN DESCRIPTION
0xFFFFFFF0 4 Field 0 (TOP) merged or split mode, at begin of FIELD VIDEO ESSENCE
0xFFFFFFF1 4 Field 1 (BOTTOM) merged or split mode, at begin of FIELD VIDEO ESSENCE
0xFFFFFFF2 4 Field 0 (TOP) split mode only, at begin of CHROMA Payload
0xFFFFFFF3 4 Field 1 (BOTTOM) split mode only, at begin of CHROMA Payload

hint: how to understand if VIDEO PAYLOAD is merged or split.
First method: Reader can check if Chroma Marker is following the Video Payload, that is once got first
MARKER (0xFFFFFFF0/1) in the FIELD VIDEO ESSENCE, use the PAYLOAD LEN + 16 as byte offset to
check at the end of Payload if next value is a Chroma Marker (0xFFFFFFF2/3).
Second method: Reader can check the value of byte at offset 22 (from begin of FIELD VIDEO
ESSENCE), if value is 0x2F then Payload is merged mode, any other value is split mode.

francescoBLT on 30 Aug 2018

At the end of these long posts a question:
I've compiled openshot under Linux Ubuntu 18.04 following the instructions at:

https://openshot.org/static/files/user-guide/developers.html

all works fine. The question is: How I can cross compile for windows ?
Regards

francescoBLT on 30 Aug 2018

@francescoBLT - Apologies for the late reply. As far as I know we do not cross compile. @ferdnyc Do we?

DylanC on 12 Sep 2018

Not to my knowledge. OpenShot itself isn't compiled anyway, but libopenshot and -audio are and AIUI the packaged builds are compiled for Windows on Windows. The tricky part isn't so much doing the build, it's getting all of the dependencies sorted out. The only guide I know of with any information on how to do so is this one which was written in 2008, last updated in 2015, and is out of date enough that it has not proved particularly helpful in my experience.

(The only definitive statement I can make about compiling libopenshot on Windows is that at one point I tried to figure out how to do it. I never succeeded.)