Mistika scripts syntax. 


There is no formal documentation about Mistika scripts syntax. However, eveything is saved on text files, and in general it is easy to understand the 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. By default Mistika produce compressed files for getting more performance when reading and saving files.


Compressed and uncompressed formats.


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


In compressed (or better said "compact") format, each effect will only appear completely the first time.  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 reading them from user scripts because you need to count the number of c() fields rather than searching for their names.


If you want to switch to uncompressed you can declare this variable environment variable in your operating system:


COMPACT_CURVE_SAVE 0


In the case of Linux, there are two ways:


SUSE11 systems (.cshrc file):

setenv COMPACT_CURVE_SAVE 0  


CENTOS systems ( .bashrc file):


export COMPACT_CURVE_SAVE=0  




Effect numbers, effect names,  and effect definitions


The prototype definition for each effect is stored in MISTIKA-ENV/etc/curves (where MISTIKA-ENV is the path to your software location, which will depend on the product and operating system). 


You can use those files to avoid having to save  examples. Also use the filename to find which effect number corresponds to  it. Also useful is to check if there are new parameters in a new version to automate  changes to the scripts.


In these files, the default parameter vales are the ones inside the d() field, which is the only value in these .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  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  vectorized information. Otheer plugins may have 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 they are 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 syntax, even for the case of windows filesystems. (they will be converted to "/").  So Mistika will never put a "\" character  in a path.


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


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:  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)). 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 stands 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 them for other purpose:  In case of R3D clips Mistika will put there a snapshot of the R3D settings at the
moment of R3D import. However, the actual R3D settings for processing are always read from the R3D media itself.  If you want to keep this metadata as a reference you would need to create also an instance R3DParams effect.

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, tthe 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(?)
)



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, grow rightwards
Y() - the layer of the timeline, grows upwards
The timeline coordinates are signed 32 bits numbers, and origin can be
choosen arbitrarily, however for a good practice they should start somewhere near
(0,0).

You can for example choose 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 number of frames of the media, if the head or tail needs to be
trimmed both need to be substracted 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 normaliy 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 displyed by mistika interface, but you
can define less, at least one should be present.

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