API Definitions

126 Pages·2015·2.32 MB·English

EvoStream Media Server
API Definitions
V1.7.0

www.evostream.com
Subject to Change without prior notice
© Copyright 2015 All Rights Reserved
Table Of Contents

I. Document Definitions ....................................................................... 2
II. Overview ............................................................................................. 4
III. Run-Time API ..................................................................................... 5
Accessing the Runtime API .................................................................................................... 5
Configuring and Receiving Event Notifications ........................................................................ 8
User Defined Variables .......................................................................................................... 8
Streams vs Stream Configs and API Command Return Values............................................... 9
IV. EvoStream Media Server API ......................................................... 11
Streams ............................................................................................................................... 11
Aliasing ................................................................................................................................ 58
Utility and Feature API Functions ......................................................................................... 68
Connections ......................................................................................................................... 92
Services ............................................................................................................................. 103
V. EMS Event Notification System ................................................... 109
Stream Event Definitions .................................................................................................... 111
Adaptive Streaming/File-based Streaming Events .............................................................. 117
Web Server Events ............................................................................................................ 118
API Based Events .............................................................................................................. 119
Connection Based Events .................................................................................................. 121
Application Based Events ................................................................................................... 121
Web Server Events ............................................................................................................ 124
VI. Event Table of Protocol Types ..................................................... 125

List of Figures
Figure 1 : Turning Telnet Feature On.............................................................................................. 5

List of Tables
Table 1: Definition of Terms ......................................................................................................... 3

EvoStream Media Server
[phone] Page 1 of 125
[email protected] www.acs.com.h
k
I. Document Definitions
TERM DEFINITION
DASH Dynamic Adaptive Streaming over HTTP. HTTP adaptive bitrate
streaming defined by ISO.
EMS EvoStream Media Server
EWS EvoStream Web Server
ERS EvoStream Rendezvous Server
HDS HTTP Dynamic Streaming. HTTP adaptive bitrate streaming defined by
Adobe.
HLS HTTP Live Stream. HTTP adaptive bitrate streaming defined by Apple.
HTTP Hyper-Text Transfer Protocol. The basic protocol used for web-page
loading and web browsing. Also used for tunneling by many protocols.
TCP based.
IDR Instantaneous Decoding Refresh – This is a specific packet in the
H.264 video encoding specification. It is a full snapshot of the video at
a specific instance (one full frame). Video players require an IDR frame
to start playing any video. “Frames” that occur between IDR Frames
are simply offsets/differences from the first IDR.
JSON JavaScript Object Notation
Lua A lightweight multi-paradigm programming language
MSS Microsoft Smooth Streaming. HTTP adaptive bitrate streaming defined
by Microsoft.
RTCP Real Time Control Protocol – An protocol that is typically used with
RTSP to synchronize two RTP streams, often audio and video streams
RTMP Real Time Messaging Protocol – Used with Adobe Flash players
RTMPT Real Time Messaging Protocol Tunneled – Essentially RTMP over
HTTP
RTP Real-time Transport Protocol – A simple protocol used to stream data,
typically audio or video data.
RTSP Real Time Streaming Protocol – Used with Android devices and live
streaming clients like VLC or Quicktime. RTSP does not actually
transport the audio/video data, it is simply a negotiation protocol. It is
normally paired with a protocol like RTP, which will handle the actual
data transport.
swfURL Used in the RTMP protocol, this field is used to designate the
URL/address of the Adobe Flash Applet being used to generate the
stream (if any).

EvoStream Media Server
[phone] Page 2 of 125
[email protected] www.acs.com.h
k
tcURL Used in the RTMP protocol, this field is used to designate the
URL/address of the originating stream server.
TOS Type of Service. This is a field in IPv4 packets used by routers to
determine how traffic should be dispersed, usually for prioritizing
packets.
TTL Time To Live. This is a field in Ipv4 packets used by routers to
determine how many gateways/routers the packet should be able to
pass through.
URI Universal Resource Identifier. The generic form of a URL. URI’s are
used to specify the location and type of streams.
URL Uniform Resource Locator. This is a specific form of the URI used for
web browsing (http://ip/page).
VOD Video On Demand
Table 1: Definition of Terms

EvoStream Media Server
[phone] Page 3 of 125
[email protected] www.acs.com.h
k
II. Overview
This document describes the Application Programming Interface (API) and the Event Notification
System presented by the EvoStream Media Server (EMS). The API provides the ability to manipulate
the server at runtime. The server can be told to retrieve or create new streams, return information on
streams and connections, or even start or stop functional services. The Event Notification System
provides a means for the EMS to alert users of certain events that occur within the EMS, such as a
new stream is created, a stream has been dropped, server stopped, etc. The EvoStream Media
Server API and Event Notification System allows users to tightly integrate with the server without
having to write native plugins or modules.

EvoStream Media Server
[phone] Page 4 of 125
[email protected] www.acs.com.h
k
III. Run-Time API
While the EMS has a “great” User Interface, users typically interact with the EMS through the Run-
Time API. This API, which is used by the UI, provides a whole suite of ways to interact with the EMS.
It can be used to create custom User Interfaces, hook the EMS up to existing systems, integrate it
with other pieces of software and much more!
Accessing the Runtime API
A. ASCII
The ASCII interface is often the first interface used by users. It can be accessed easily through
the telnet application (available on all operating systems) or through common scripting languages.
To access the API via the telnet interface, a telnet application will need to be launched on the
same computer that the EMS is running on. The command to open telnet from a command
prompt should look something like the following:
telnet localhost 1112
Note:
Telnet may need to be enabled using Windows® operating systems. To do this, go to the Control
Panel -> Programs -> Turn Windows Features on and off. Turn the Telnet Client program on.
Figure 1 : Turning Telnet Feature On

Please also note that on Windows®, the default telnet behavior will need to be changed. The
local echo and new line mode should be set for proper behavior. Once telnet is launched, exit the
telnet session by typing “ctrl+]”. Then enter the following commands:
set localecho
set crlf

To return to the Windows® telnet session, press Enter/Return key.

EvoStream Media Server
[phone] Page 5 of 125
[email protected] www.acs.com.h
k
Once the telnet session is established, type out the desired commands which will be immediately
executed on the server after the Enter/Return key is pressed.
An example of a command request and response from a telnet session would be the following:
Request version
Response ☺«{"data":{"banner":"EvoStream Media Server (www.evostream.com)
version 1.7.0. build 4153 with hash:
c50ee04ec98886ed1f54d599355e04346bf50df0 on branch: develop -
PacMan|m|-(built on 2015-11-
03T01:50:37.000)","branchName":"develop","buildDate":1446515437,"
buildNumber":"4153","codeName":"PacMan|m|","hash":"c50ee04ec98886
ed1f54d599355e04346bf50df0","releaseNumber":"1.7.0."},"descriptio
n":"Version","status":"SUCCESS"}
 JSON
When using the regular ASCII interface, it may be necessary to use a JSON interpreter so that
responses can be more human-readable. JSON parsers are available online.

B. ASCII CLI
This is the user friendly version of the ASCII telnet interface. It offers a readable response without
having to parse the JSON results. To access this interface from the command prompt, execute
telnet localhost 1222
the following:
However, since the objective of this interface is simplicity, there are some parameters that are not
included on the display. Thus, for advanced usages and/or configurations, it is better to use the
regular ASCII telnet interface.
An example of a command request and response from an ASCLII CLI telnet session would be the
following:
Request version
Command entered successfully!
Response
Version

banner: EvoStream Media Server (www.evostream.com) version
1.7.0. build 4153 with hash:
4ab5d9145ae3b4b3dfeb3af5ce6890f015824974 on branch: develop -
PacMan|m| - (built on 2015-11-06T08:24:32.000)
buildDate: 2015-11-03T01:50:37.000
buildNumber: 4153
codeName: PacMan|m|
releaseNumber: 1.7.0.

C. HTTP
To access the API via the HTTP interface, simply make an HTTP request on the server using any
browser with the command to be executed. By default, the port used for these HTTP requests is
7777. The HTTP interface port can be changed in the main configuration file used by the EMS
(config.lua).

EvoStream Media Server
[phone] Page 6 of 125
[email protected] www.acs.com.h
k
A general http format request would be the following:
http://[EMS IP]:7777/[API]

An example of a command request and response from an HTTP session would be the following:
http://IP:7777/[API]?params=([base64 encoded parameters])

http://localhost:7777/version
Request
{"data":{"banner":"EvoStream Media Server (www.evostream.com) version
Response
1.7.0. build 4153 with hash: 4ab5d9145ae3b4b3dfeb3af5ce6890f015824974
on branch: develop - PacMan|m| - (built on 2015-11-
06T08:24:32.000)","branchName":"develop","buildDate":"2015-11-
06T08:24:32.000","buildNumber":"4176","codeName":"PacMan|m|","hash":"4
ab5d9145ae3b4b3dfeb3af5ce6890f015824974","releaseNumber":"1.7.0."},"de
scription":"Version","status":"SUCCESS"}
All of the API functions are available via HTTP, but the request must be formatted slightly different if
parameters are included. To make an API call over HTTP, the parameters to be used should be in
base64 format.
Sampling a pullstream command:
1. Type in the parameters first:
(firstParam=XXX secondParam=YYY…)

(uri=rtsp://localhost:5544/vod/mp4.bunny.mp4 localStreamName=bunny)
2. Convert the parameters using a base64 encoder:
Converted parameter:
dXJpPXJ0c3A6Ly9sb2NhbGhvc3Q6NTU0NC92b2QvbXA0LmJ1bm55Lm1wNCBsb2NhbHN0
cmVhbW5hbWU9YnVubnkp
3. The corresponding request in HTTP format would be:
http://localhost:7777/pullstream?params=
dXJpPXJ0c3A6Ly9sb2NhbGhvc3Q6NTU0NC92b2QvbXA0LmJ1bm55Lm1wNCBsb2NhbHN0cmVhbW5
hbWU9YnVubnkp

 Base64
A group of similar binary-to-text encoding schemes that represent binary data in
an ASCII string format by translating it into a radix-64 representation. There are available
base64 encoders online to get the encoded result.
 PHP and JavaScript
PHP and JavaScript functions are also provided. These functions simply wrap the HTTP
interface calls and can be found in the EMS Web UI directory.
 Securing the API
By default, the ASCII API is protected and access from any outside computer is prohibited.
This can of course be modified within the config.lua file, but keeping this restriction is
recommended for maintaining server security.

EvoStream Media Server
[phone] Page 7 of 125
[email protected] www.acs.com.h
k
The HTTP based API is also restricted by default to only local access. However, unlike the
ASCII API interface, there are often good reasons to expose the HTTP API. To secure the
HTTP based API in this case, you will enable Proxy Authentication on the EWS (details found
in the EWS section of this doc). This will enforce that a valid username and password be
provided for each and every API call made, ensuring on authorized access to the EMS API.

Configuring and Receiving Event Notifications
The EvoStream Media Server (EMS) generates notifications based upon events that occur at runtime.
These events are formatted as HTTP calls and can be delivered to any address and port desired.
Event Notifications are disabled by default and must be enabled by modifying the EMS config file:
config.lua.
To enable Event Notifications you will need to Enable/Uncomment the eventLogger section of the
config.lua file. Comments in LUA are specified by either a “--“ for a single line, or denoted by a “--[[“ to
start a comment block and a “]]--“ to end a comment block. By default the eventLogger section is
commented out using block style comments, so you will need to remove both the “--[[“ and “]]--“
strings. See the Configuration Files section for more information.
A. Sinks
Sinks are defined as “a specific destination for events” and can be of two types: “file” and “RPC”. File
sinks simply write events to a file, as defined by the “filename” parameter. This works much like a
system logger. Users can choose the format of the output between JSON, XML, W3C and text.
JSON and XML will be formatted as JSON and XML respectively and each event will be written to a
single line. This is done for ease of parsing. The W3C formatted file is compliant with the requirement
of having space or tab-delimited columns. In addition, it has a header line that is commented out (#)
that indicates the names of the columns. As with JSON and XML, each event is also written to a
single line. The Text format writes to the event file in a way that is easy to read, where events are on
multiple lines. The file sink is off by default, but can be turned on by creating the sink in the config.lua
file.
To receive HTTP based Event Notifications, an RPC type sink must be defined (and is by default).
The URL parameter defines the location that will be called with each event. The URL can be a
specific web service script or just an IP and port on which you are listening. RPC sinks have the
option of one of three serializer types, or in other words, the way the data will be formatted within the
HTTP post: JSON, XML, XMLRPC. XMLRPC events will be formatted as XML using a traditional
XML-RPC schema. The XML serializer type will use an XML schema that is more condensed and
specific to the EMS Event Notification System. The JSON serializer type will have the same schema
as XML, but will be formatted as JSON.
For any Sink, users can define an array of enabledEvents. When this array is present, ONLY the
events listed will be sent to that sink. If this array is not present, ALL events will be sent to the sink.
The full list of events can be found later in this document.

User Defined Variables
While the EMS provides an extensive set of API functions, there may be times where the variables
provided are not sufficient, or where you may need extra information to be associated with individual
streams. To support these needs, the EMS API implements User Defined Variables. User Defined
Variables can be used with any API function where information is maintained by the EMS (i.e. pulling
a stream, creating a timer, starting a transcode job, etc.).
To specify a User Defined Variable, you simply need to append a ‘_’ to the beginning of your variable
name. The User Defined variables are reported back whenever you get information about the
command: listStreams, listConfig, Event Notifications, etc.
Some common use cases for User Defined Variables are as follows:

EvoStream Media Server
[phone] Page 8 of 125
[email protected] www.acs.com.h
k
a. Setting a timer to stop a stream after a set period of time
setTimer value=120 _streamName=MyStream
setTimer value=120 _streamID=5
These commands will fire a timer event after 120 seconds with the set stream name or stream id
respectively.
b. Attach a custom identifier to a local stream
pullstream uri=rtmp://192.168.1.5/live/myStream localstreamname=test1 _myID=5
_myName=secretSquirrel
c. Set a custom value on a pushed stream
pushstream uri=rtmp://192.168.1.5/live/myStream localstreamname=test1 _myID=5
_myName=secretSquirrel

Streams vs Stream Configs and API Command Return Values
Issuing commands to the EvoStream Media Server is an Asynchronous event. This means that a
successfully issued command will not actually be executed immediately. It will instead be Queued for
execution. While this generally transparent for the user, there is an important ramification of this
reality:
When the EMS returns SUCCESS for an issued API command, this only means that the
command was successfully QUEUED. IT DOES NOT MEAN THAT THE COMMAND WAS
SUCCESSFULLY EXECUTED!
For example, a pullStream command may return SUCCESS, but the stream may not have actually
been pulled!
More details on why this occurs follows.
A. Stream Configs
When an API command is issued, it creates a Stream Config entry. Each Stream Config is a list
of parameters which instructs EMS to take an action. As a result of that action, a stream may be
born. At the time at which the command is executed (stream config is created), there is absolutely
no guarantee that the action will indeed spawn a stream. There is a very good reason for this
behavior. The action itself doesn't solely depend on EMS. In the case of pullStream, the success
of the command greatly depends on the distant party being invoked to send the stream in
question. If that distant party doesn't do that, then the stream can't be created. To summarize,
stream config is only the blueprint of the future stream, nothing less, and nothing more.
Stream Configs also have a unique, monotonically increasing ID. This is completely different from
the "stream id". When listConfig is used, it will output the format described in the "API
Definiion.pdf". Notice the configId value for each node. The listing of the configurations also
contains the current status of the stream and the previous status. Finally, removeConfig can be
used to terminate a configuration and the corresponding stream (if ever spawned)
B. Streams
Streams are the active streams currently managed by EMS. They may or may not have an
associated config. That is because the stream could be pushed/pulled into/from EMS by a distant
party, without any execution of a pushStream/pullStream command. For example, an Adobe flash

EvoStream Media Server
[phone] Page 9 of 125
[email protected] www.acs.com.h
k