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 instancesstream.start
- Start streamstream.stop
- Stop streamstream.create
- Create new stream file and start the streamstream.delete
- Stop the stream and delete the stream fileinstance.stop
- Stop an Application instanceinstance.start
- Start an Application instanceapplication.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