ScenariStream

Scenarist MUI+Elementary Stream and raw stream manipulation library.

Brief

ScenariStream is a Python utility to manipulate and perform bidirectional conversion between proprietary Scenarist project files (MUI+xES) and open data stream formats like SUP/PGS, MNU/IGS and TextST.

In other words, this tool converts SUP (captions) or IGS (interactive menu) files generated using open source projects to Scenarist BD assets that may be imported professional Blu-ray authoring suites. Similarly, data streams generated with authoring suites can be converted to their respective open format, to be usable with tools like BDEdit, tsMuxer, etc! The conversion is bijective: all data and timestamps are preserved¹.

Limitations

• Timestamp wrap-around is not fully tested, due to the lack of samples.
• TextST support is only unidirectional, from .TextST to TES+MUI assets. TextST files must be generated by SubtitleEdit
• The project has safeguards to prevent the usage of MUI assets that are not "Text" (TES) or "Graphic" (IES, PES). Support for other MUI assets (audio or video) may be added later.

Usage:

Command line client

This utility requires Python3.9 or more. python3 client.py PARAMETERS -o output_file

Parameters

-s --stream <file> – Input raw stream file (SUP-PGS, MNU-IGS or TextST).²
-x --xes <file> – Input Scenarist Elementary Stream file (PES, IES or TES).²
-o --output <file> – Output file with extension. The format is inferred from the extension. For xES+MUI output, only the xES file should be specified, the MUI file is generated aside.
-m --mui <file> – Input Scenarist MUI file, required if .mui file has a different name or location to the .pes file.
-t --textst – Flag for TextST conversion.
-l --late-ts – Flag when the SUP or MNU input have a first presentation timestamp beyond 13 hours and 15 minutes. Meaningless with xES input.

Example

The command below converts a .SUP file to PES+MUI assets.
python3 client.py -s subtitles.sup -o ./project/subtitles.pes
The existing ./project folder will be populated with the output of the program: subtitles.pes and subtitles.pes.mui.

Python library

ScenariStream may also be installed as a Python library:
python3 -m pip install git+https://github.com/cubicibo/ScenariStream.git

Internal classes are:

• EsMuiStream to parse ES+MUI assets.
• StreamFile to parse generic SUP, MNU files.
• TextSTFile which derives from StreamFile to parse TextST files. The EsMuiStream class contains the necessary methods to perform the format conversion.

Note

The user has the responisiblity to pick the proper extension when converting to Scenarist xES+MUI format. The output extension should be .PES (.IES, .TES) when converting from .SUP (.MNU, .TextST, respectively). Furthermore, ScenariStream does not check the compliancy of the data in the stream; it only performs a conversion.

Footnotes

1. As long as the duration of the stream is below 13:15:21,858 for SUP and IGS, this should not be an issue anyway. ↩

2. mutually exclusive as they specify the input type. ↩ ↩²