[Matroska-devel] Control Track proposal draft

Steve Lhomme steve.lhomme at free.fr
Sun Aug 15 12:05:59 CEST 2004

Well, it's almost a menu system proposal as it even includes hotspot 

As said previously, we need some control commands, named variables, a 
way to handle the hooks and hotspots. The system is finally quite 
similar to the one of DVD but hopefully doesn't look so basic, to allow 
developer/authors creativity... I hope there is no patent covered in 
this field !

Here is a proposal of how it could be done. This is only a draft, it 
doesn't handle all the possible cases. Things should be changed/enhanced.

1) Design Model

The Control Track is seen as a codec. It should have access to some 
"player" properties on demand: request the value of a "well known" named 
variable. And it should also be able to set the value of such a well 
known variable too. All "code" will have a timecode and a duration. 
Overlapping of code is allowed... Since the timecode in Matroska is not 
meant to have overlapping time, when a new Control code is introduced at 
a given time, the other codes that should remain should be "restated". 
This way it should be easier to cut a file and keep all commands that 
are meant to be in the remaining part.

2) Named Variables

The named variable cover most of what is possible to do with the Control 
Track. Some can be read-only. Most would have a default value (if not all).

As in Matroska, the type of value inside a named variable depends on the 
name. For example, a value could either have an integer type, string 
type or binary type (for now it would mostly be useful for Segment UIDs, 
or encryption keys). Each type being exclusive. This system is very 
similar to the MIBs in SNMP.

In some case it would be useful to get/set a list of values. Like the 
like of tracks available for playback or the chapters that are before or 
after a given timecode.

Some examples of named variables :
- playback mode (integer - read/write) : stop, pause, play
- timecode scale (integer - read/write) : to change the playback speed, 
but is not enough for audio because of the samplerate
- current timecode (integer - read/write) : allow the jump function
- current chapter (integer - write) : allow jump to a chapter
- random number (integer - read) : allow a random number generation
- random number min (integer - read/write)
- random number max (integer - read/write)
- segment UID playing (binary - read/write) : allow loading a new segment
- chapter edition selected (integer - read/write) : change the edition

(how to enable /disable some tracks ? a list should be read/write for that)

The Control Track should be allowed to set custom named variables. 
Because of memory limits there could have in some players, it should be 
possible to know the max number of available named variables for each type :
- custom max integer variables available (integer - read)

3) Player Hooks

At any given time, the Control Track should be able to asked (not) to be 
notified when certain events occur. Like when the pause/play button is 
pressed, a new chapter is selected, the skip button is pressed, a named 
value has changed.

The code to register a hook could be like this :

<event_register value="EVENT_SKIP_TO_NEXT_RELEASE">
   <if 'part_cannot_be_skipped'>
     <event_return value="done">
     <event_return value="do">

The code to unregister the event :

<event_register value="EVENT_SKIP_TO_NEXT_RELEASE"/>

4) Hotspots

We should be able to set the shape and request a hook on it, and unset a 
hotspot... Will be covered later...

5) Control Commands

The Control should be able to change the playback properties. That means 
setting some named values of the players. So these commands will be 
described in the name values.

I can think of 3 basic commands that should cover all we need :

- GetValue : get the value of a named variable
- SetValue : set the value of a named variable
- ValueIsSet : indicate wether a variable is set or not, can be useful 
when starting playback to detect if all variables needed by a movie are 
available from the player (otherwise you could skip to a location in a 
movie indicating the player can't play this movie).
- RegisterEvent : indicate the Control Track request (not) to be 
notified when the given event occur.

random num -> a read-only value integer
random min, random max

6) Conditional Statements

A few basic conditional code should be possible. At least we need 
if/else. We also need basic mathematical operations on integer 
(++,--,==) and an equal operator for strings and binary data.

7) Storing

I think we should be using XML to write the Control Track data. We'll 
decide later if EBML will be prefered...

More information about the Matroska-devel mailing list