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:

applications.list - List applications and instances
stream.start - Start stream
stream.stop - Stop stream
stream.create - Create new stream file and start the stream
stream.delete - Stop the stream and delete the stream file
instance.stop - Stop an Application instance
instance.start - Start an Application instance
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

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