From 705dec3044938147fa693b87ce2291acce3afc74 Mon Sep 17 00:00:00 2001 From: Steve Lhomme Date: Wed, 29 May 2024 14:30:45 +0200 Subject: [PATCH 1/2] Add MatroskaJS Chapter Codec Rather than reinventing the wheel with a custom language, we can reuse and well-known one. The goal of Matroska Script was to be similar to JavaScript/ECMAStrip/ActionScript. But, in JS, integers can only use 56 bits. So not all ChapterUID (64-bit unsigned integer) can be addressed with the current Matroska Script stable API. Rather than adding a different GotoAndPlay that is compatible with JavaScript (using a string), we start from scratch with ECMAScript 6th Edition (ES6). --- chapter_codecs.md | 26 ++++++++++++++++++++++++++ rfc_backmatter_chapter_codecs.md | 6 +++--- 2 files changed, 29 insertions(+), 3 deletions(-) diff --git a/chapter_codecs.md b/chapter_codecs.md index 475f7714..cf0ba13a 100644 --- a/chapter_codecs.md +++ b/chapter_codecs.md @@ -72,6 +72,32 @@ The one and only command existing for the moment is `GotoAndPlay( ChapterUID );` same suggests, it means that, when this command is encountered, the `Matroska Player` **SHOULD** jump to the `Chapter` specified by the UID and play it, as long as this `Chapter` exists. +## MatroskaJS + +This is the case when `ChapProcessCodecID` = 2. This is a script language build for +Matroska purposes. It uses the [@!ECMAScript] 6th Edition (ES6) syntax. The commands are stored as text commands, in UTF-8. +The syntax is C like, with commands spanned on many lines, each terminating with a semicolon ";". You can also include comments +at the end of lines with "//" or comment many lines using "/* \*/". The scripts are stored +in `ChapProcessData`. For the moment `ChapProcessPrivate` is not used. + +The Matroska Script contains the following commands. + +### GotoAndPlay + +The command is called with `GotoAndPlay( "" );`. + +As the same suggests, it means that, when this command is encountered, the `Matroska Player` +**SHOULD** jump to the `Chapter` specified by the `ChapterUID` string and play it, as long as this `Chapter` exists. + +### LogMsg + +The command is called with `LogMsg( "A String" );`. + +The `Matroska Player` **SHOULD** send the provided message to the user debugging console, if there is one. +In this example it would send "A String", without the double quotes, to the debugging console. + + + ## DVD Menu This is the case when `ChapProcessCodecID` = 1. Each level of a chapter corresponds diff --git a/rfc_backmatter_chapter_codecs.md b/rfc_backmatter_chapter_codecs.md index b0a0d330..ff94c233 100644 --- a/rfc_backmatter_chapter_codecs.md +++ b/rfc_backmatter_chapter_codecs.md @@ -10,13 +10,13 @@ - + - ECMA-262 14th Edition, June 2022. ECMAScript 2023 language specification + ECMA-262 6th Edition, June 2015. ECMAScript 2015 language specification Ecma International - + From 86cfb043394a5b6f54085abaea06a2f7b7438bd7 Mon Sep 17 00:00:00 2001 From: Steve Lhomme Date: Wed, 21 Aug 2024 11:23:03 +0200 Subject: [PATCH 2/2] Add a MatroskaJS choice API This API is meant for interactive movies. The author adds choices in a chapter and retrieves the user choice at the end of this chapter. Depending on the choice, different actions can be performed. The choice rendering and user interaction is the responsibility of the player. --- chapter_codecs.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/chapter_codecs.md b/chapter_codecs.md index cf0ba13a..ccc100f6 100644 --- a/chapter_codecs.md +++ b/chapter_codecs.md @@ -96,6 +96,58 @@ The command is called with `LogMsg( "A String" );`. The `Matroska Player` **SHOULD** send the provided message to the user debugging console, if there is one. In this example it would send "A String", without the double quotes, to the debugging console. +### AddChoice + +The command is called with `AddChoice( "", group = Null );`. + +The `Matroska Player` **MUST** keep the choice with the given UID in memory until the Chapter it belongs to +has ended. The string may be any length and should be a valid ECMAScript string literal. + +If a group string is supplied, the choice **MUST** only be evaluated within the group of the given string. +Otherwise the choice **MUST** be evaluated with the other choices with no group, called the Default Group. + +It is possible to add a single choice for a group to let the user select it or not, for example with a checkbox. + +### SetChoiceText + +The command is called with `SetChoiceText( "", "Some text", "" );`. + +Set the string to use for the choice with the given UID if the given language is selected. +The language string is the same form defined in [@!RFC5646] as for the `ChapLanguageBCP47` element. + +When the `Matroska Player` collects the strings to use for all available choices, the same language +rules apply as of [@!Matroska, section 19] for track selection. In addition if a string is missing for a language +the whole language is considered to be not available, unless there is no other language option available. + + + +### SetChoiceDefault + +The command is called with `SetChoiceDefault( "", group = Null );`. + +Tell the `Matroska Player` that the choice with the given UID is the default one to use. +If this function is not called, no choice is considered the default one. + +If a group string is supplied, the default state only applies within the group of the given string. +Otherwise the default state only applies among the choices of the Default Group. + +### CommitChoices + +The command is called with `CommitChoices( );`. + +Tell the `Matroska Player` that all previously added choices with AddChoice ((#addchoice)) should be used. +This **SHOULD** generate some visually visible choice, with the default choice selected, if there is one. + +### GetChoice + +The command is called with `GetChoice( group = Null );`. + +The function returns the UID string corresponding to the choice selected by the user. +If the user did not make a selection and there is no default one, this function returns the ECMAScript `Undefined`. + +If a group string is supplied, the selected UID string returned is the selection within the choices of the given group string. +Otherwise selected UID string returned is the selection within the choices of the Default Group. + ## DVD Menu