The EMS API provides return responses from most of the API functions. These responses are formatted in JSON so that they can be easily parsed and used by third party systems and applications. These responses will be identical, regardless of what interface is used.

The EMS API functions parameters are NOT case sensitive.

The EMS API can be accessed in three ways:

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.

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.

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":"c50ee04ec98886ed1f54d599355e04346bf50df0","releaseNumber":"1.7.0."},"description":"Version","status":"SUCCESS"}
  • JSON Parser

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.

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 the following:

telnet localhost 1222

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

Response

Command entered successfully!
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.

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.

A general HTTP format request would be the following:

http://<EMS_IP_ADDRESS>:7777/<API_COMMAND>

An example of a command request and response from an HTTP session would be the following:

Request

http://localhost:7777/version

Response

{"data":{"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)","branchName":"develop","buildDate":"2015-11-06T08:24:32.000","buildNumber":"4176","codeName":"PacMan|m|","hash":"4ab5d9145ae3b4b3dfeb3af5ce6890f015824974","releaseNumber":"1.7.0."},"description":"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.

http://<EMS_IP_ADDRESS>:7777/<API_COMMAND>?params=([base64-encoded parameters])

Sampling a pullstream command:

  1. Type in the parameters first:

    Raw parameters:

     uri=rtsp://localhost:5544/vod/mp4.bunny.mp4 localStreamName=bunny

  2. Convert the parameters using a base64 encoder:

    Converted parameters:

     dXJpPXJ0c3A6Ly9sb2NhbGhvc3Q6NTU0NC92b2QvbXA0LmJ1bm55Lm1wNCBsb2NhbHN0cmVhbW5hbWU9YnVubnkp

  3. The corresponding request in HTTP format would be:

     http://localhost:7777/pullstream?params=dXJpPXJ0c3A6Ly9sb2NhbGhvc3Q6NTU0NC92b2QvbXA0LmJ1bm55Lm1wNCBsb2NhbHN0cmVhbW5hbWU9YnVubnkp
  • 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.