Stream

Get Stream List

Get all stream names in the {vhost name}/{app name} application.

Request

GET /v1/vhosts/{vhost}/apps/{app}/streams

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
	"response": [
		"stream",
		"stream2"
	]
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Json array containing a list of stream names

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Header

Content-Type: application/json

Body

{
    "statusCode": 404,
    "message": "Could not find the application: [default/non-exists] (404)"
}

Create Stream (Pull)

Create a stream by pulling an external URL. External URL protocols currently support RTSP and OVT.

Request

POST /v1/vhosts/{vhost}/apps/{app}/streams

Header

Authorization: Basic {credentials}
Content-Type: application/json

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
	"name": "new_stream_name",
	"urls": [
		"rtsp://192.168.0.160:553/app/stream",
		"url to pull the stream from - support OVT/RTSP",
		"Only urls with the same scheme can be sent as a group."
  	],
  	"properties":{
		"persistent": false,
		"noInputFailoverTimeoutMs": 3000,
		"unusedStreamDeletionTimeoutMs": 60000,
		"ignoreRtcpSRTimestamp": false
  	}
}

# name (required)
	Stream name to create
# urls (required)
	A list of URLs to pull streams from, in Json array format. 
	All URLs must have the same scheme.
# properties (optional)
	## persistent
		Created as a persistent stream, not deleted until DELETE
	## noInputFailoverTimeoutMs
		If no data is input during this period, the stream is deleted, 
		but ignored if persistent is true
	## unusedStreamDeletionTimeoutMs
		If no data is output during this period (if there is no viewer), 
		the stream is deleted, but ignored if persistent is true
	## ignoreRtcpSRTimestamp
		No waits RTCP SR and start stream immediately

Responses

201 Created

A stream has been created.

Header

Content-Type: application/json

Body

{
    "message": "Created",
    "statusCode": 201
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code

400 Bad Request

Invalid request. Body is not a Json Object or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Body

{
    "statusCode": 404,
    "message": "Could not find the application: [default/non-exists] (404)"
}

409 Conflict

A stream with the same name already exists

502 Bad Gateway

Failed to pull provided URL

500 Internal Server Error

Unknown error

Get Stream Info

Get detailed information of stream.

Request

GET /v1/vhosts/{vhost}/apps/{app}/streams/{stream}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
	"response": {
		"input": {
			"createdTime": "2021-01-11T03:45:21.879+09:00",
			"sourceType": "Rtmp",
			"tracks": [
			{
				"id": 0,
				"type": "Video",
				"video": {
					"bitrate": "2500000",
					"bypass": false,
					"codec": "H264",
					"framerate": 30.0,
					"hasBframes": false,
					"keyFrameInterval": 30,
					"height": 720,
					"width": 1280
				}
			},
			{
				"id": 1,				
				"audio": {
					"bitrate": "128000",
					"bypass": false,
					"channel": 2,
					"codec": "AAC",
					"samplerate": 48000
				},
				"type": "Audio"
			}
			]
		},
		"name": "stream",
		"outputs": [
		{
			"name": "stream",
			"tracks": [
			{
				"id": 0,
				"type": "Video",
				"video": {
					"bypass": true
				}
			},
			{
				"id": 1,					
				"audio": {
					"bypass": true
				},
				"type": "Audio"
			},
			{
				"id": 2,					
				"audio": {
					"bitrate": "128000",
					"bypass": false,
					"channel": 2,
					"codec": "OPUS",
					"samplerate": 48000
				},
				"type": "Audio"
			}
			]
		}
	]
	}
}


# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Details of the stream

Note

keyFrameInterval is GOP size

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Header

Content-Type: application/json

Body

{
    "statusCode": 404,
    "message": "Could not find the application or stream (404)"
}

OpenAPI Specification

OpenAPI 3.0 specification

openapi: 3.0.0
info:
  title: Stream API
  version: 1.0.0
  description: API for stream information

paths:
  /stream:
    get:
      summary: Get stream information
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'

components:
  schemas:
    SuccessResponse:
      type: object
      required:
        - statusCode
        - message
        - response
      properties:
        statusCode:
          type: integer
        message:
          type: string
        response:
          type: object
          required:
            - name
            - input
          properties:
            name:
              type: string
            input:
              $ref: '#/components/schemas/Input'
            outputs:
              type: array
              items:
                $ref: '#/components/schemas/Output'
    Error401:
      type: object
      required:
        - statusCode
        - message
      properties:
        statusCode:
          type: integer
          enum: [401]
        message:
          type: string
          enum: ["[HTTP] Authorization header is required to call API (401)"]
          
    Error404:
      type: object
      required:
        - statusCode
        - message
      properties:
        statusCode:
          type: integer
          enum: [404]
        message:
          type: string
          enum: ["Could not find the application or stream (404)"]
          
          
    VideoTrack:
      type: object
      required:
        - id
        - type
        - video
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum:
            - Video
        video:
          type: object
          properties:
            bitrate:
              type: string
            bitrateAvg:
              type: string
            bitrateConf:
              type: string
            bitrateLatest:
              type: string
            bypass:
              type: boolean
            codec:
              type: string
            deltaFramesSinceLastKeyFrame:
              type: integer
            framerate:
              type: number
            framerateAvg:
              type: number
            framerateConf:
              type: number
            framerateLatest:
              type: number
            hasBframes:
              type: boolean
            keyFrameInterval:
              type: integer
            keyFrameIntervalAvg:
              type: number
            keyFrameIntervalConf:
              type: number
            keyFrameIntervalLatest:
              type: integer
            height:
              type: integer
            width:
              type: integer
              
    AudioTrack:
      type: object
      required:
        - id
        - type
        - audio
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum:
            - Audio
        audio:
          type: object
          properties:
            bitrate:
              type: string
            bitrateAvg:
              type: string
            bitrateConf:
              type: string
            bitrateLatest:
              type: string
            bypass:
              type: boolean
            channel:
              type: integer
            codec:
              type: string
            samplerate:
              type: integer
              
    DataTrack:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum:
            - Data
            
    Track:
      oneOf:
        - $ref: '#/components/schemas/VideoTrack'
        - $ref: '#/components/schemas/AudioTrack'
        - $ref: '#/components/schemas/DataTrack'
      discriminator:
        propertyName: type
        mapping:
          Video: '#/components/schemas/VideoTrack'
          Audio: '#/components/schemas/AudioTrack'
          Data: '#/components/schemas/DataTrack'
          
    Rendition:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        videoVariantName:
          type: string
        audioVariantName:
          type: string
          
    Playlist:
      type: object
      required:
        - name
        - fileName
        - options
        - renditions
      properties:
        name:
          type: string
        fileName:
          type: string
        options:
          type: object
          properties:
            enableTsPackaging:
              type: boolean
            hlsChunklistPathDepth:
              type: integer
            webrtcAutoAbr:
              type: boolean
        renditions:
          type: array
          items:
            $ref: '#/components/schemas/Rendition'
            
    Output:
      type: object
      required:
        - name
        - tracks
      properties:
        name:
          type: string
        playlists:
          type: array
          items:
            $ref: '#/components/schemas/Playlist'
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/Track'
            
    Input:
      type: object
      required:
        - createdTime
        - sourceType
        - tracks
      properties:
        createdTime:
          type: string
          format: date-time
        sourceType:
          type: string
        sourceUrl:
          type: string
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/Track'

Delete Stream

Delete Stream. This terminates the ingress connection.

The sender can reconnect after the connection is terminated. To prevent reconnection, you must use AccessControl.

Request

DELETE /v1/vhosts/{vhost}/apps/{app}/streams/{stream}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
}


# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Header

Content-Type: application/json

Body

{
    "message": "[HTTP] Could not find the stream: [default/#default#app/stream] (404)",
    "statusCode": 404
}