Introduction 


Mistika does not have an SDK as such. However, there is a new "Mistika Workflows" product specialized on workflow automation, which provides a convenient Python interface to many Mistika metadata structures and functionality. For example, with this product the whole Mistika transcoding engine can be used within Python scripts very easily, and also Mistika display filters containing Mistika effects. 


More Mistika functionality is planned as the Mistika Workflows product grows, but at the date of this document it is still in the first version and you may miss desirable functions. For that reason you may need to work directly with Mistika scripts, to which this document is dedicated. In any case, whatever you are trying to automate we recommend to try with Mistika Workflows first, as even when it does not solve all your needs it will probably save a lot of work for you, also ensuring forward compatibility.  You can find an introduction to its Python interface is in this link


Also, for the particular case of image manipulation (rather than metadata) we recommend to use the Mistika GLSL effect instead, which permits to execute user scripts written in GLSL language. This language is specialised in image transformations and provides realtime capabilities within Mistika.


Finally, for the case of writing 3rd party plugins we recommend to use the OFX specification, which is also supported in Mistika Ultima & Mistika Boutique.


The rest of the document is dedicated to Mistika scripts syntax, which are created when saving timelines (.env, .vrenv files), groups (.grp files), render jobs and rendered clips ( .rnd and .clp ), and when importing media clips ( .lnk ) 




Mistika scripts syntax. 


Most of the work you do in Mistika is saved on Mistika scripts, which are plain text files (there are no binary databases in Mistika). 


There is no formal documentation about Mistika scripts syntax. However, almost everything is saved on text files that you will find under the project folders, with similar syntax but different extensions depending on their purpose ( .env, .vrenv, .lnk,  .clp, .rnd, .grp). In general it is easy to understand the file syntax by saving simple example timelines and reading the content.


Although they are always text files, an important  point to remind is that there are two possible formats: Compressed and uncompressed (but both of them are text files). By default Mistika Ultima & Mistika Boutique produce "compressed" files for getting more performance when reading and saving files. 



Compressed and uncompressed formats.


Note: This point only applies to Mistika Ultima & Mistika Boutique syntax. As a difference, Mistika VR always use the uncompressed format (the vrenv scripts are always small, so they are not compressed). 


The only difference is that in compressed (or better said "compact") syntax, each effect will only appear completely the first time that it appears in the file.  From that point, all the animation curves that have default values will simply appear as c().  Normally this reduces the size of the file tremendously, although it complicates a bit reading files from user scripts (basically you need to count the number of c() fields rather than searching for their parameter names).


If you prefer to switch Mistika to use uncompressed format you can declare this variable environment variable in your operating system:


COMPACT_CURVE_SAVE 0


In the case of Linux, put this line in .bashrc file:


export COMPACT_CURVE_SAVE=0  


Meanwhile, Windows and macOS provide permit to define "environment variables" in their GUIs.



Effect numbers, effect names,  and effect definitions


The prototype definition for each effect is stored in InstallationPath/SGO Apps/ProductName/etc/curves (where InstallationPath and ProductName depend on your software installation location and the Mistika product). 


You can use those files to get the parameter list  from each effect, rather than having to save your own examples. Also you can use their filenames to find which effect number corresponds to  it (as to save space, in Mistika scripts they are mentioned by its effect number rather than its name). 

This is also useful to check if there are new parameters in a new version, in case you want to automate changes to your scripts.


In these files, the default parameter values are the ones inside the d() field, which is the only value in the .proto files. Once in a .env file, each d() field is then followed by the user keyframes


Plugins and Inline data


- Shapes are embedded in the  .env files converted to inline text.


-  For performance reasons, more complex binary data (typically from external plugins)  is not saved in the env files.  Instead it is saved in the PRIVATE folder of the project,  with the name of the environment as part of the filename.  Regarding Mistika effects, only the VectorPaint, Title, and Morph use this method to store  vector information. But other 3rd party plugins may also save their own files in there.


Using backslash as escape characer for reserved characters in media paths and comments


The characters "(" ")" are reserved for the syntax. And also "{","}" which can create problems with filenames.  However those characters are also supported by using the backslash \ character.


Example:


MyCLip\{1\).mxf


The "\" character is safe to use for this  because all paths are normalised to unix style syntax, even for the case of Windows filesystems. (the "\"  will be converted to "/").  So Mistika will never store a "\" character in a path reference.


------------------------


F.A.Q


Most of the syntax is trivial, but some aspects are not evident.  The following is a compilation of answers to support cases related to the syntax.


Question:  Why not using XML as Mistika Workflows and other applications are doing?

Answer:
  In complex productions with Mistika Ultima / Mistika Boutique it is normal to require hundreds of megabytes of metadata per Timeline, and thousands of Timelines and render scripts per project. This would be too slow to parse in Xml format.  In comparison this format is much shorter (in many cases using single letters and numbers for field headers and values.), while still giving open access as a text file rather than  using a binary database. 



Question:  When populating timelines with scripts, which parts of the scripts could potentially be omitted?

Answer:
The whole AudioRoute(...) section can be omitted, as well as the
clips AudioRoute(...) local statements. Mistika will set it to default, so that is OK



Question: What are the L() and H() fields


Answer: The L() and H() statements refer to the Hi res and Low res (proxy) media.
Nowadays it is not normal to have any proxy media as in modern systems Mistika can create the proxies on the fly in realtime (and then process the effects in proxy resolution if that is that is requested). Then, for example you could simply let the proxy line with "?" values:

L( d(Xfs.dev) p(?) n(?) f(?) )



Question: Can can we include our own  metadata somewhere?

Answer:  The c(..) fields on each clip stand for "comments", and they are the easiest way to do this.  Mistika will interpret it as simply as that,  as a comment. You can create examples with Edit->Attributes to see how they work.


But there is a case that Mistika also use these fields for other purpose:  In case of R3D clips Mistika will put in there a snapshot of the R3D settings at the
moment of R3D import, just for user reference (the actual R3D settings for processing are always read from the R3D media itself).  And other cameras could show the same comments in future versions.  


Round brackets "(" or ")" are obviously reserved characters for the script syntax. If you want to use them inside the comments or elsewhere it is still possible, but they need to be escaped as "\(" and "\)".

Question: How are R3D multisegment movies represented?


Answer:  In the case of multisegment R3D movies, you need to point

to the first one (the 001.R3D) . Then, the codec itself will follow the other
segments. For example:


H( d(Movie.dev)

       p(/TRANSPORT/CUSTOMERS/SUNSET/C005_L008_061459.RDM/C005_L008_061459.RDC)
n(C005_L008_061459_001.R3D) f(?)
)


Note: Mistika supports to delete unused R3D segments to make space, as long as the first segment is kept (and the ones for the used media)


Question: - What is the meaning of the I() section?

Answer:  I() stands imply for Image() as opposed to Sound(). Audio clips will use
 S()



Question: - What are all the coordinate sections or sections containing numbers?

Answer: Inside clip, the statements mean:

X() - the frame of the timeline, grows rightwards
Y() - the layer of the timeline, grows upwards


The timeline coordinates are signed 32 bits numbers, and origin can be
chosen arbitrarily, however for a good practice they should start somewhere near
(0,0).

You can for example chose the Y(0) layer for right eye and Y(1) for
the left eye on top of it. If you needed to add effect nodes on top of
each clip, you could leave some space using Y(0) and Y(5) for example.

For X(), first clips start at X(0), the second at X(1234) if
length of the first shot were 1234 frames, etc.

W() stands for Width of the clip as drawn in the timeline. Would equal
to the number of frames of the media, but if the head or tail needs to be
trimmed both values need to be subtracted from this width.

f(0) l(1216) - first and last frame of the trimmed media, first
inclusive, last exclusive.

s(0) e(1214) - start and end index of the original, untrimmed, media,
both INCLUSIVE this time.

Some examples:
The media does have 1000 frames.
Untrimmed clip would state (in the correct places of the structure):

W(1000)
f(0) l(1000)
s(0) e(999)

The same clip with 5 frames trimmed from its head (beginning):

W(995)
f(5) l(1000)
s(0) e(999)

The same clip with 5 frames trimmed from its head (beginning) and 10 frames
trimmed from its tail:

W(985)
f(5) l(990)
s(0) e(999)

t() is the tapename. For example, t(C005_L008_061459)

T(10:29:41:05) Timecode of the first frame of the media. Trimming does
not change this number.


Timecodes can vary depending on media file type, so it is recommended to get an actual reference timeline
with clips pointing to real media,


Here is an example of an actual T() statement for an R3D timecode:

T(1950570@47.952049|1950570@47.952049|172801@47.952049)

First, the "|" character separates multiple timecodes available for
the media(they are 3 of them for R3D, first 2 normally identical). so
the string describes 3 different timecodes in this case:

1950570@47.952049
1950570@47.952049
172801@47.952049

The number before the @ character is the timecode converted to a frame
index of a hypothetical sequence starting at 00:00:00:00.

All frames are counted, so 00:00:00.10 would equal to number 20, not
10, due to the ./: TC pairing.

Up to 3 different TCs will be displayed by mistika interface, but you
can define less, and at least one should be present.

The number after the @ is the framerate of the initial timecode,
which could be different from the working framerate of Mistika at that moment.