API Documentation

Overview

The purpose of the StreamControl plugin is to provide mechanisms that allow dynamic adding or removing of streams, as well as shut down and start up of applications. The application restarts trigger configuration reloads, avoiding a full restart of a wowza server - think of it as a graceful restart of a single application.

Introduction

All API requests start with http://localhost:1935/streamcontrol.

The HTTP provider is added to Wowza using the following code snippet. It should go into the relevant VHost.xml, at the start inside the <HTTPProviders> block. The entry point name streamcontrol can be modified below if needed.

<HTTPProvider>
        <BaseClass>com.titpetric.wse.module.StreamControl</BaseClass>
        <RequestFilters>streamcontrol*</RequestFilters>
        <AuthenticationMethod>none</AuthenticationMethod>
</HTTPProvider>

Additional authentication is handed by Wowza (<AuthenticationMethod>)


API Requests

The API endpoints recieves HTTP GET requests. Parameters are passed as HTTP encoded GET variables.

The parameter action is mandatory. It can be any of these values:

  1. applications.list - List applications and instances
  2. stream.start - Start stream
  3. stream.stop - Stop stream
  4. stream.create - Create new stream file and start the stream
  5. stream.delete - Stop the stream and delete the stream file
  6. instance.stop - Stop an Application instance
  7. instance.start - Start an Application instance
  8. application.stop - Stop an Application

1. List applications and instances

The action parameter must be applications.list.

No other parameters are required for this call.

The call returns the list of applications, instances and streams which are registered in Wowza. These parameters are required to stop, start, create and delete streams. The API call also exposes limited wowza internal information, the running time for each application and instance.

Example: /streamcontrol?action=applications.list

{
    "status": "ok",
    "action": "applications.list",
    "applications": [
        {
            "status": "loaded",
            "name": "vlive",
            "timeRunning": 6.035,
            "instances": [
                {
                    "name": "_definst_",
                    "streams": [

                    ],
                    "timeRunning": 6.032
                }
            ]
        },
        {
            "status": "loaded",
            "name": "live",
            "timeRunning": 8.757,
            "instances": [
                {
                    "name": "_definst_",
                    "streams": [
                        {
                            "name": "test.stream",
                            "active": true
                        },
                        {
                            "name": "test",
                            "active": true
                        }
                    ],
                    "timeRunning": 8.729
                }
            ]
        },
        {
            "status": "unloaded",
            "name": "vods3"
        },
        {
            "status": "unloaded",
            "name": "vod"
        }
    ]
}

2. Start stream

The action parameter must be stream.start.

Additional parameters (case-sensitive):

Parameter Required Default
app Yes None
instance No _definst_
streamName Yes None
mediaCasterType No liverepeater

The API call will start a mediacaster stream. The stream may be any .stream file created under the virtual host content/ folder. It is common for these stream files to contain a rtsp link.

Possible mediaCasterType values include rtp or rtp-live. For more information please consult the appropriate section of the Wowza documentation.

Example: /streamcontrol?action=stream.start&app=live&streamName=test2.stream

{
    "app": "live",
    "status": "ok",
    "mediaCasterType": "liverepeater",
    "action": "stream.start",
    "instance": "_definst_",
    "streamName": "test2.stream"
}

3. Stop stream

The action parameter must be stream.stop.

Additional parameters (case-sensitive):

Parameter Required Default
app Yes None
instance No _definst_
streamName Yes None

The API call will stop a mediacaster stream. The stream may be any .stream file created under the virtual host content/ folder. It is common for these stream files to contain a rtsp link.

The stream files are not deleted, but in case they need to be added and started on Wowza server restart, they should be started with Wowza's StartupStreams.xml or additional calls to the API.

Example: /streamcontrol?action=stream.stop&app=vlive&streamName=live1

{
    "app": "vlive",
    "status": "ok",
    "action": "stream.stop",
    "instance": "_definst_",
    "streamName": "live1"
}

4. Create new stream file and start the stream

The action parameter must be stream.create.

Additional parameters (case-sensitive):

Parameter Required Default
app Yes None
instance No _definst_
streamName Yes None
source Yes None
mediaCasterType No liverepeater

The API call with create a stream file under the virtual host content/ folder. The stream source contained in the file is passed via the source parameter. Using the other parameters the API call will start a mediacaster stream, just like stream.start.

Possible mediaCasterType values include rtp or rtp-live. For more information please consult the appropriate section of the Wowza documentation.

Example: /streamcontrol?action=stream.create&app=live&streamName=test2.stream&source=rtmp%3A%2F%2Fserver%2Flive%2Ftest

{
    "app": "live",
    "status": "ok",
    "mediaCasterType": "liverepeater",
    "source": "rtmp:\/\/server\/live\/test"
    "action": "stream.create",
    "instance": "_definst_",
    "streamName": "test2.stream"
}

5. Stop the stream and delete the stream file

The action parameter must be stream.delete.

Additional parameters (case-sensitive):

Parameter Required Default
app Yes None
instance No _definst_
streamName Yes None

The API call will stop a mediacaster stream. The stream may be any .stream file created under the virtual host content/ folder. It is common for these stream files to contain a rtsp link.

The stream files are not deleted, but in case they need to be added and started on Wowza server restart, they should be started with Wowza's StartupStreams.xml or additional calls to the API.

Example: /streamcontrol?action=stream.delete&app=vlive&streamName=live1

{
    "app": "vlive",
    "status": "ok",
    "action": "stream.delete",
    "instance": "_definst_",
    "streamName": "live1"
}

6. Stop an Application instance

The action parameter must be instance.stop.

Additional parameters (case-sensitive):

Parameter Required Default
app Yes None
instance No _definst_

Stops a specific application instance.

Example: /streamcontrol?action=instance.stop&app=live

{
    "app": "live",
    "instance": "_definst_",
    "action": "instance.stop",
    "status": "ok"
}

7. Start an Application instance

The action parameter must be instance.start.

Additional parameters (case-sensitive):

Parameter Required Default
app Yes None
instance No _definst_

Starts a specific application instance.

Example: /streamcontrol?action=instance.start&app=live

{
    "app": "live",
    "instance": "_definst_",
    "action": "instance.start",
    "status": "ok"
}

8. Stop an Application

The action parameter must be application.stop.

Additional parameters (case-sensitive):

Parameter Required Default
app Yes None

Stops all the application instances under one application.

Example: /streamcontrol?action=application.stop&app=live

{
    "app": "live",
    "action": "application.stop",
    "status": "ok"
}

Possible errors

Errors can happen. Most likely the errors will be descriptive. Usually, errors are reported only for missing required parameters, or system errors.

Example: /streamcontrol?action=stream.stop&app=vlive

{
    "status": "fail",
    "message": "Required parameter not found: streamName"
}

Author

The StreamControl plugin is developed by Tit Petrič (c), all rights reserved.

Contact: black@scene-si.org
Product page: scene-si.org