Scripts and their functions¶
The ebu-run script¶
This script is capable of picking up a structured configuration file and use
that to create the nodes and carriage mechanism objects that we would like to
use. They can be even wired in the same configuration file together so in the
end a complex system can be modeled using a single json file. Please refer to
ebu_tt_live.scripts.ebu_run as well as ebu_tt_live.config to
learn more about the way the configuration logic works. To get help on permitted
options for the specified node(s) run ebu-run with a --help. See
Configuration files and ebu-run.
Simple Producer¶
This script loads static text from a file
(ebu-tt-live-toolkit/ebu_tt_live/examples/simple_producer.txt) and breaks it
into a sequence of EBU-TT Live documents using natural language processing. Use
ebu-run to start it: ebu-run
--admin.conf=ebu_tt_live/examples/config/simple_producer.json
The default carriage mechanism is WebSocket, so you will need to listen to
ws://127.0.0.1:9000. Conveniently, we’ve created an HTML page that does just
that. After you launch the Simple Producer, open docs/build/ui/test/index.html
or the current release pre-built page in your
browser. The ‘Broadcast message’ field should be populated with the correct
address (ws://localhost:9000). Click ‘Connect’ and then ‘Subscribe’. You can
also change the identifier for the sequence. The documents should appear in the
window below.
Alternatively, the Simple Producer can use the file system as the carriage mechanism. To do this, create a configuration file and specify the carriage mechanism and output folder options as described in Configuration files and ebu-run . This saves the documents in the specified output folder together with a manifest file that can be used by the Simple Consumer (below). See Filesystem Carriage Mechanism for more details about the file system carriage mechanism.
Simple consumer¶
This script reads and validates documents in a sequence. It performs both
semantic and syntactic validation of the XML. By default, it uses WebSocket and
listens to ws://localhost:9000. To start this default configuration, run
ebu-run --admin.conf=ebu_tt_live/examples/config/simple_consumer.json.
You can also point the Simple Consumer to the file system. If you saved the documents
in a folder (using the folder export configuration option
of the Simple Producer), you can write a configuration file as
described in Configuration files and ebu-run and pass this file to ebu-run.
User Input Producer¶
This is a web page that adds a user interface and various configurations to the
Simple Producer. It needs to connect to a node that can receive incoming
/publish style WebSocket connections, for example a Simple Consumer, a
Distributor or a Handover Manager Node. First, with your virtual environment
activated and the code built, start one, with a command line such as ebu-run
--admin.conf ebu_tt_live/examples/config/user_input_producer_consumer.json -
this one runs a simple consumer. Then, in your browser, open
docs/build/ui/user_input_producer/index.html or the
current release pre-built page and click
‘Connect’. Select the sending mode (manual, scheduled or asynchronous). You
should see the documents arriving in the command line window where the simple
consumer is listening. See detailed instructions here:
User input producer.
Distributor¶
This script mimics a distribution node. To see it forwarding documents from the
Simple Producer to the Simple Consumer using Websocket, run ebu-run
--admin.conf=ebu_tt_live/examples/config/sproducer_dist_sconsumer_ws.json. A
more interesting scenario is distributing documents from the User Input Producer
to two consumer nodes: ebu-run
--admin.conf=ebu_tt_live/examples/config/user_input_producer_dist_consumers.json.
Like the Simple Producer, the Distributor can also save the documents it
receives to the file system. To do that, create you own configuration file as
described in Configuration files and ebu-run and pass this file to ebu-run.
Handover Manager¶
This node implements the ‘Who claimed control most recently’ algorithm defined
in the specification, with added functionality to allow messages to be broadcast
between members of the authors group, which may be added to a future
specification. This algorithm determines the output from multiple input
sequences. The Handover Manager is a specialised case of the switching node that
bases its decisions on handover-related attributes in the document and its
previous decisions. There is no separate command to run this script. Start it
with the ebu-run, for example ebu-run
--admin.conf=ebu_tt_live/examples/config/user_input_producer_handover.json for
the default configuration. For detailed instruction on setting up the Handover
Manager with the UIP see User input producer.
Buffer Delay Node¶
This script buffers each received Document and emits it after a fixed
non-negative delay offset period. Since this is a passive node, essentially
equivalent to a longer carriage latency, no modification to the documents is
required. The Buffer Delay Node is primarily intended for delaying implicitly
timed documents for resynchronisation. Use ebu-run to start this script, for
example ebu-run --admin.conf=ebu_tt_live/examples/config/buffer_delay.json
DeDuplicator Node¶
This node addresses instances where style and region elements and
attributes are duplicated, which can occur for example when sequences are
resequenced.
For the default configuration of the node, see:
ebu-run --admin.conf=ebu_tt_live/examples/config/deduplicator_fs.json
Resequencer Node¶
This node consumes documents from one sequence and creates a new sequence of documents based on the content in that input sequence, where every document in the output sequence has the same duration. The resequencer repeatedly extracts and then outputs a document of the specified duration, then waits for a period equal to that duration before extracting the next document. It can be configured to begin extracting the first document immediately when it is run, or to wait until a specific time until extracting the first document.
The resequencer is particularly useful upstream of an EBU-TT-D Encoder, to generate segmented EBU-TT-D, for example prior to wrapping in fragmented MPEG-4 and serving with a DASH or HLS manifest; those onward steps are not part of this project. This pattern effectively converts an asynchronous stream of input documents into something that can be delivered synchronously downstream, which is useful for distribution to media players.
Note that the resequencer output can contain duplicated style and region
elements. These can be cleaned up by passing the output to a DeDuplicator
node before downstream encoding to other formats.
In general the resequencer does not begin emitting any documents until it has received at least one input document. To immediately start to emit documents an initial document can be configured. Necessary initial parameters like language or sequence ID are retrieved from that document.
Note that the resequencer accepts only input documents which all have the same sequence ID. This sequence ID is determined by the first received input document (or the configured initial document instead, if applicable).
Use ebu-run to start
this script, for example ebu-run --admin.conf=ebu_tt_live/examples/config/sproducer_resequencer_direct_ebuttd_encoder_fs.json
Retiming Delay Node¶
This script modifies the times within each Document and issues them without
further emission delay as part of a new sequence with a new sequence identifier.
The times are modified such that all of the computed begin and end times within
the document are increased by a non-negative fixed delay offset period. The
Retiming Delay Node is primarily intended for delaying explicitly timed
documents. Use ebu-run to start this script, for example ebu-run
--admin.conf=ebu_tt_live/examples/config/retiming_delay.json.
EBU-TT-D Encoder¶
This script is an extension of simple consumer and is responsible for resegmenting and converting the incoming EBU-TT Live documents into EBU-TT-D documents that can be later used to be embedded in video streams such as DASH. There are configuration file options for controlling the media time conversion reference point and the segmentation interval; these are described in Configuration files and ebu-run.
To see the Encoder in action, using output from the Simple Producer and the
‘direct’ carriage mechanism, run ebu-run
--admin.conf=ebu_tt_live/examples/config/sproducer_ebuttd_direct.json.
IMPORTANT: the Encoder is not a complete EBU-TT Live to EBU-TT-D converter. Since EBU-TT-D generation was not part of this project, this functionality was implemented only partially and should not be used as complete reference.