End System Multicast

Introduction

The aim of the ESM Engine API is to provide application developers with a mechanism for interacting with the ESM network, without requiring the alteration of the developer’s build process and using an extremely minimal interface.

In order to support any build process on any platform, and to avoid possible issues related to source code licensing, the ESM Engine will run as a separate process with no graphical interface, and will communicate with its client process using standard IPC protocols. There will be an Engine process built for Windows and another for Macintosh. The source code of both engine processes will be made available under the GPL.

Command-Line Interface

Usage

The ESM Engine may be invoked from the command line, or by any other equivalent method. On the command line, the ESM Engine supports the following command-line syntax:

ESMEngine [options] [url]

Where url is the URL of an event that should be started immediately (it may be passed with or without a protocol prefix such as http, esm, or esm-engine). Currently supported options and their descriptions are:

  • --help: Displays a usage statement.
  • --no-player: If url is specified, do not launch a media player when starting the event at that URL.

If --no-player is specified, the Engine will do its best to ensure that, if the event requires the media player to connect to a port on the local machine, that port will always be port number 8192. If another process is already using this port, however, a different port may be used. Currently there is no way for the ESM Engine to report what port the media player should connect to; this will be corrected in a future release.

Multiple Instances

If the Engine is invoked, with or without arguments, and another copy of the Engine is already running, the arguments will be forwarded to the already running Engine instance, and the new instance will then exit immediately.

Note that this feature is not implemented in the Mac OS X version of the Engine, as it is intended to allow robust URL protocol handling on Windows (where the URL is passed as a command-line argument). On Mac OS X, URL handling is conducted using Apple Events, and therefore the command line interface is rarely used. If you launch multiple instances of the Engine on Mac OS X, all but the first instance will complain that the port is in use and will exit, without forwarding any arguments.

Socket API Interface

General

Communication between the client process and the ESM Engine will be full-duplex. The exact IPC mechanism is currently unspecified, but will perform in a functionally identical manner to a local socket pair.

All messages to and from the Engine will adhere strictly to the protocol described in the next section.

Protocol

The protocol for communication with the ESM Engine will take the form of textual messages, transmitted in host byte order and terminated with a newline character (‘\n’, ASCII 0x0A). A message is formally defined as follows:

<message>     ::= <status_code> | <status_code> <whitespace> <parameters> "\n"
<status_code> ::= <digit> | <digit> <status_code>
<digit>       ::= [any character between ASCII 0x30 and 0x39, inclusive]
<whitespace>  ::= " " | " " <whitespace>
<parameters>  ::= <specifier> | <specifier> <whitespace> <parameters>
<specifier>   ::= <word> | [ASCII 0x2B] <phrase> [ASCII 0x2B]
<phrase>      ::= <word> <whitespace> <word> | <phrase> <whitespace> <word>
<word>        ::= <symbol> | <word> <symbol>
<symbol>      ::= [any character between ASCII 0x21 and 0x7E, inclusive]

It is not an error, though not necessary, to specify additional parameters after a message beyond those required. These parameters could be a human-readable description of the message, or other information useful for debugging.

Multi-word parameters are enclosed in double quotes (“, ASCII 0x2B). The double quote, therefore, cannot occur inside a parameter without being escaped. The escape sequence for a literal double quote is " (ASCII 0x5C + 0x2B). The escape sequence for a literal backslash is thus \ (ASCII 0x5C + 0x5C). No other escape sequences are defined.

Examples of valid messages include:

1 esm://esm.cs.cmu.edu/priv/4/107/TV.Guess10BaseT.640.VLC.e5m
2
2 Stop
130 Configuring
800 "Something bad happened."
500 1
500 1 OK
200 Viewing

Client Messages to Engine

The following messages can be sent from the client to the Engine to initiate an operation.

Start Viewing

Message Code: 1

Parameters:

  1. Event URL

Description:

The Start Viewing message directs the ESM Engine to start viewing an event. This message takes one parameter: the URL of the event that should be started. Once Start Viewing has been sent, the Engine will send back an OK or Error message with a description of any error that occurred, followed by several Engine State messages as various steps of the initialization process are reached. This will allow the client to display a progress indicator or update the client’s interface state if desired.

If Start Viewing is called while an event is already running, the old event will be stopped and the new one will be started instead.

Example:

1 StartViewing esm://esm.cs.cmu.edu/priv/4/107/TV.Guess10BaseT.640.VLC.e5m

Stop Viewing

Message Code: 2

Parameters: none.

Description:

The Stop Viewing message directs the ESM Engine to stop viewing the event it is currently viewing and close the media player. It takes no parameters. Once Stop Viewing has been sent, the Engine will send back an OK message or an Error message with a description of any error that occurred, followed by a Engine State message confirming that the event has been stopped.

Example:

2

Get Engine State

Message Code: 3

Parameters: none.

Description:

The Get Engine State message directs the ESM Engine to send back an OK or Error message, followed by a Engine State message indicating the current state of the Engine. (These states are described under the Engine State message in the next section.)

Example:

3

Get Event List

Message Code: 4

Parameters:

  1. Username (optional)

Description:

The Get Event List message directs the ESM Engine to send back a list of Event messages, followed by an OK message. The Event message is described in the next section. If no username parameter is specified, there will be one Event message for every public event on the currently specified Web server. If a username is specified, there will be one Event message for every event (public or private) belonging to that user.

Note that the Event message only gives very basic information about an event. For more detailed information, you will need to send a Get Event Details message for the event you are interested in.

Examples:

4
4 testuser

Get Event Details

Message Code: 5

Parameters:

  1. Event ID
  2. Event ID (optional)
  3. …

Description:

The Get Event Details message directs the ESM Engine to send back a list of Event Details messages, followed by an OK message. The Event Details message is described in the next section.

You can pass as many event IDs as you like to the Get Event Details message. The ESM Engine will return event details for each event you specify, in order, and then a single OK message at the very end.

Examples:

5 501
5 501 502 504 508

Set ESM Server

Message Code: 6

Parameters:

  1. Server URL

Description:

The Set ESM Server message directs the ESM Engine to process all forthcoming commands using the specified ESM server. It is not necessary to specify a protocol string (e.g., “http://”), though it is not an error to do so.

The ESM Engine will send back an OK message once the server has been changed.

Examples:

6 esm.cs.cmu.edu

Engine Messages to Client

The following messages will be sent from the Engine to the client to confirm an operation, respond to a command, or indicate a change in state about which the client might be interested.

OK

Message Code: 500

Parameters:

  1. the message code of the command that succeeded

Description:

The OK message is sent to inform the client that its command was successfully performed. The OK message is generally preceded by one or more Viewing Status messages informing the client of changes to the Engine’s state. The message code of the OK message will be followed by the message code of the command that was acknowledged.

Example:

500 1

Error

Message Code: varies (see below).

Parameters:

  1. The message code of the command that failed
  2. Textual error description

Description:

The Error message is sent to inform the client that a command that was sent has failed. The Error message is always followed by a single Engine State message informing the client of the Engine’s state after the error. The message code of the error will be in the range 800-899 (inclusive) depending on the particular type of error that occurred. The message code will be followed by the message code of the command that failed, and then by a textual description of the error that occurred.

Individual error codes are as follows:

800 Unknown or unexpected error
801 Unknown message code
802 Missing parameters to command
803 Parameters to command were invalid
810 Tried to start event that is not being broadcast
811 Tried to stop event while already stopped
820 Could not connect to Web server
821 Could not launch ESM proxy
822 Could not launch media player

Engine State

Message Code: varies (see below).

Parameters:

  1. status description

Description:

The Engine State message is sent to inform the client of the current state of the Engine. One or more Engine State messages are sent in response to client messages. In the case of Stop Viewing and Get Engine State messages, exactly one Engine State message will be sent in response. In the case of Start Viewing, several Engine State messages may be sent.

Each type of Engine State message has a different message code depending on the state that is being reported. Defined states are:

100 Stopped
110 Running bandwidth measurement
120 Running software update
130 Configuring event
200 Viewing

Event

Message Code: 400

Parameters:

  1. event ID
  2. event URL
  3. event name
  4. event description

Description:

The Event message is sent in response to a Get Event List message from the client. An Event message contains basic information about a single event identified by the event ID passed as the first parameter.

Note:

The event name and event description may contain whitespace. As such, they may be delimited by double quotes (“) pursuant to the protocol.

Example:

400 1658 esm://esm.cs.cmu.edu/priv/389/1658/TV.Guess10BaseT.640.VLC.e5m
"cmuTV Online Channel [Buggy]" "Buggy Event 2006 on cmuTV"

Event Details

Message Code: 401

Parameters:

  1. event ID
  2. event URL
  3. event name
  4. event description
  5. event email
  6. event Web site
  7. event username
  8. event status
  9. event privacy
  10. event bitrate
  11. event start time
  12. event end time
  13. event duration

Description:

The Event Details message is sent in response to a Get Event Details message from the client. An Event Details message contains detailed information about a single event identified by the event ID passed as the first parameter. The meaning of the parameters is as follows:

  1. event ID: the unique ID of the event.
  2. event URL: the URL of the configuration file pertaining to this event.
  3. event name: the name of the event.
  4. event description: the long description of the event, if there is one. If no description is specified, the word “none” (without quotes) will be sent in place of the description.
  5. event email: the email address associated with the event, if there is one. If no email address is associated, the word “none” (without quotes) will be sent in place of the email address.
  6. event Web site: the Web site address associated with the event, if there is one. If no Web site is associated, the word “none” (without quotes) will be sent in place of the Web site address.
  7. event username: the username of the user who is broadcasting this event.
  8. event status: one of “yes” or “no” (without quotes); “yes” if the event is currently running, “no” otherwise.
  9. event privacy: one of “public” or “private” (without quotes) depending on whether the event is marked as public or private.
  10. event bitrate: the total bitrate of the event, expressed in kilobits per second. This number does not include the estimated overhead of the ESM protocol.
  11. event start time: a timestamp, in the form "YYYY-MM-DD hh:mm:ss TZC" (with quotes), representing the date and time that the event started or will start.
  12. event end time: a timestamp, in the form "YYYY-MM-DD hh:mm:ss TZC" (with quotes), representing the date and time that the event ended or will end.
  13. event duration: a number, expressed in minutes, representing the duration of the event. This will always be the difference between the end time and the start time, and is provided as a convenience.

Note:

The event name, event description, start and end times, and potentially even the Web site address and email address, may contain whitespace. As such, they may be delimited by double quotes (“) pursuant to the protocol.

Example:

401 1658 esm://esm.cs.cmu.edu/priv/389/1658/TV.Guess10BaseT.640.VLC.e5m "cmuTV Online Channel [Buggy]" "Buggy Event 2006 on cmuTV" foo@bar.com none testuser yes public 512 "2003-04-08 12:30:00 EST" "2003-04-08 14:30:00 EST" 120

Status

Message Code: varies (see below).

Parameters:

  1. status description

Description:

The Status message is sent to inform the client of some status information that does not result in a change in the engine state, but might nonetheless be important for the client to know about. An example of this might be periodic Status messages sent to inform the client of the quality of the ESM connection and the number of connected users.

Currently, no Status messages are defined.