Use the Wowza encoder GraphQL API

The Wowza™ encoder GraphQL API enables you to manage your Wowza hardware encoder and broadcasts directly via the API. GraphQL APIs are structured so that the operations mirror the responses. We recommend using the GraphiQL app, an interactive, browser-based IDE for exploring and using GraphQL APIs.

This article describes how to create, configure, manage, publish, and end a broadcast with the Wowza encoder GraphQL API. Some additional useful operations are also provided.

Notes:

  • Wowza ClearCaster version 2.0.0.07 or later is required.
  • This article assumes that you're using the following information that was provided to you in your Wowza encoder GraphQL API Preview welcome email.
    • A link to the Wowza encoder GraphiQL interface with your username and password.
    • Download links for two USB key files.
    • The name of your company, as assigned in the Wowza encoder GraphQL API.

Overview of the Wowza encoder GraphQL API schema

If you're not familiar with the structure and terminology of GraphQL APIs, see GraphQL Schema and Types for more information.

The Wowza encoder GraphQL API uses three root object types: query, mutation, and subscription. All example operations will use these root object type as operational keywords as well as the operation name.  Query operations return an item or an array of items, while mutations create or modify objects and can return a field or an array of fields for the created or updated object. Note that mutation operations return object IDs, which are required as input for subsequent operations.

To make the API more intuitive to use, we've used the following naming patterns:

  • Any operation that starts with create has a corresponding delete operation.
  • Any operation that starts with add has a corresponding remove operation.
  • Any operation that starts with set can add an item in addition to modifying a value. 

For a complete list of operations and their arguments, see the documentation in the GraphiQL app or our Wowza encoder GraphQL API reference documentation

Known limitations 

  • Only the following video codecs and implementations are supported:
    • H.264
      • MainConcept software transcoding (default)
      • x264 software transcoding (x264)
      • Intel Quick Sync hardware-accelerated transcoding
    • H.265
      • Intel Quick Sync hardware-accelerated transcoding

Object hierarchy 

  • company
    • namespaces
      • broadcasts
        • inputs
        • outputs
          • encodingConfiguration
            • encodingConfigurationVideo
              • parameters
            • encodingConfigurationAudio
              • parameters
            • extraProperties
          • streamTargets
          • recordings
        • displays
        • broadcastEncoders
        • extraProperties
      • encoders
        • encoderStatus
        • captureSessionInfo
        • activeBroadcast
        • extraProperties
      • broadcastGroups
        • broadcasts
        • extraProperties
      • encoderGroups
        • encoders
        • extraProperties

Change your hardware encoder's personality 


Before you can use the Wowza encoder GraphQL API, you must configure the hardware encoder to use the API.

  1. Update to Wowza ClearCaster version 1.0.5.03 or later. For more information, see Update Wowza ClearCaster Software.
  2. Use the USB file and instructions provided in your Wowza encoder GraphQL API Preview welcome email to put your encoder into API mode.
    Note: A second USB file is also provided, which can be used to change your encoder back out of API mode.
  3. Restart your encoder for the changes to take effect. 

Set up your namespace and encoder 


A broadcast always belongs to a company and a namespace and must have an encoder object (hardware encoder device) associated with it. In a production environment, Wowza Media Systems™ will assign you a single companyId. This company is the overarching container for an array of namespaces. Namespaces are used to create separate environments for each of your customers, and your namespaces will contain all of the broadcast-related objects. Note that objects in different namespaces can't interact.

Note: Most create operations return an ID, which are used when creating child objects in subsequent operations.

  1. First, create a namespace within that company, using yourCompanyId and replacing namespaceName with the name you want to assign to this namespace. 
    mutation createNamespace {
      createNamespace(
        companyId: "yourCompanyId", 
        input: {name: "namespaceName"}) {
        id
        name
      }
    }
    

    This returns a unique namespace ID (yourNamespaceId) value that is used in other operations.
    {
      "data": {
        "createNamespace": {
          "id": "yourNamespaceId",
          "name": "namespaceName"
        }
      }
    }
  2. Create an encoder, using yourNamespaceId and replacing encoder1 with the encoder device's name and the encoderUUID with your device's UUID. For instructions on finding your encoder UUID, see How to find your Wowza ClearCaster encoder UUID.
    mutation createEncoder {
      createEncoder(
        namespaceId: "youNamespaceId", 
        input: {name: "encoder1", deviceId: "encoderUUID"}) {
        id
        name
        deviceId
      }
    }

    This returns an encoder ID (yourEncoderId), which is used when creating a broadcast encoder. 
    {
      "data": {
        "createEncoder": {
          "id": "yourEncoderId",
          "name": "encoder1",
          "deviceId": "encoderUUID"
        }
      }
    }
  3. Restart your encoder for your changes to take effect.

Create a broadcast


Next, create a broadcast using yourNamespaceId and replacing broadcastName with the name of the broadcast. Note that inputs takes an array of one or more source streams.

The following example creates the broadcast as well as defining the following objects associated with the broadcast: an array of at least one input, an array of at least one broadcast encoder, a stream target, and the video and audio encoding configurations. Note that each of these objects can be created and managed separately as well.

mutation createBroadcast {
  createBroadcast(namespaceId: "yourNamespaceId", 
    input: {
      name: "broadcastName", 
      inputs: {
        inputType: CAPTURE_HARDWARE,
        videoFrameWidthMax: 1920, 
        videoFrameHeightMax: 1080, 
        videoFrameRateMax: 30, 
        broadcastInputEncoderIndex: 0
        }, 
      broadcastEncoders: [
        {
        encoderId: "yourEncoderId",
        streamTargetEncoderIndex: 0,
        broadcastInputEncoderIndex: 0
        }
      ],
      outputs: [
        {
          streamName: "1080p30", 
          streamTargets:[
            {
              url: "rtmp://sourceURL",
              streamName: "yourStreamName",
              protocol: RTMP,
              streamTargetEncoderIndex: 0,
            },
        ],
          encodingConfiguration: 
          {
            name: "1080p30", 
            encodingConfigurationVideo: 
            {
              codec: "H.264", 
              implementation: "x264", 
              frameSizeFitMode: "stretch", 
              frameSizeWidth: 1920, 
              frameSizeHeight: 1080, 
              profile: "main", 
              bitrate: 8000000, 
              bitrateMin: 1000000, 
              autoAdjustBitrate: true, 
              keyFrameIntervalFollowSource: true, 
              keyFrameInterval: 60,
              parameters: [
                {
                  name: "x264.preset", 
                  value: "3", 
                  type: "Long"
                },
                {
                  name: "x264.ref", 
                  value: "1", 
                  type: "Long"
                },
                {
                  name: "x264.bframes", 
                  value: "1", 
                  type: "Long"
                }
              ]
            }, 
            encodingConfigurationAudio: 
            {
              codec: "AAC", 
              bitrate: 96000
            }
          }
        }
      ]
    }
  ) {
      id
      name
  }
}

This returns a broadcast ID (yourBroadcastId), which is used in other operations.

{
  "data": {
    "createBroadcast": {
      "id": "yourBroadcastId",
      "name": "broadcastName"
  }
}

Publishing the broadcast 


A broadcast can be activated or deactivated. Activated broadcasts can have a status of IDLE (default), PREVIEW, LIVE, STOPPED. 

Activate the broadcast

Note: A broadcast must be activated to be published, however, if the broadcast you're activating already has a status of LIVE, it will go live immediately. Always make sure the broadcast status is IDLE before activating the broadcast. For more information, see Set the broadcast status to IDLE.

 To activate the broadcast, use the following operation with yourBroadcastId.

mutation activateBroadcastEncoders {
  activateBroadcastEncoders(broadcastId: "yourBroadcastId") {
    id
    broadcastEncoders {
      id
      encoder {
        id
        deviceId
        name
      }
    }
  }
}
This returns:
{
  "data": {
    "activateBroadcastEncoders": {
      "id": "yourBroadcastId",
      "broadcastEncoders": [
        {
          "id": "yourBroadcastEncoderId",
          "encoder": {
            "id": "yourEncoderId",
            "deviceId": "encoderUUID",
            "name": "encoder1"
          }
        }
      ]
    }
  }
}

Set the broadcast status

Use the setBroadcastStatus object to update the status of a broadcast. All of these operations use yourBroadcastId.

IDLE
Although a status can be set when creating a broadcast, we recommend always resetting the broadcast status to IDLE before going live. Use the following operation, with yourBroadcastId, to set the broadcast to IDLE.

mutation setBroadcastStatusIDLE {
  setBroadcastStatus(broadcastId: "yourBroadcastId", status: IDLE) {
    id
    status
    liveAt
    previewedAt
    stoppedAt
  }
}
This returns: 
{
  "data": {
    "setBroadcastStatus": {
      "id": "yourBroadcastId",
      "status": "IDLE",
      "liveAt": null,
      "previewedAt": null,
      "stoppedAt": null
    }
  }
}

PREVIEW
Use the PREVIEW status to test the broadcast before going live.

mutation setBroadcastStatusPREVIEW {
  setBroadcastStatus(broadcastId: "yourBroadcastId", status: PREVIEW) {
    id
    status
    liveAt
    previewedAt
    stoppedAt
  }
}
This returns the following, including the time at which the PREVIEW status was set. 
{
  "data": {
    "setBroadcastStatus": {
      "id": "yourBroadcastId",
      "status": "PREVIEW",
      "liveAt": null,
      "previewedAt": "2018-08-13T15:22:30.000Z",
      "stoppedAt": null
    }
  }
}

LIVE
Use the LIVE status to publish the broadcast and deliver it to any configured stream target destinations. 

mutation setBroadcastStatusLIVE {
  setBroadcastStatus(broadcastId: "yourBroadcastId", status: LIVE) {
    id
    status
    liveAt
    previewedAt
    stoppedAt
  }
}
This returns the following, including the time at which the LIVE status was set. 
{
  "data": {
    "setBroadcastStatus": {
      "id": "yourBroadcastId",
      "status": "LIVE",
      "liveAt": "2018-08-13T15:23:03.000Z",
      "previewedAt": "2018-08-13T15:22:30.000Z",
      "stoppedAt": null
    }
  }
}

STOPPED
Use the STOPPED status to end a broadcast. If you're done with the broadcast, you'll usually want to deactivate it as well. See Deactivate the broadcast.

mutation setBroadcastStatusSTOPPED {
  setBroadcastStatus(broadcastId: "yourBroadcastId", status: STOPPED) {
    id
    status
    liveAt
    previewedAt
    stoppedAt
  }
}
This returns the following, including the time at which the STOPPED status was set.
{
  "data": {
    "setBroadcastStatus": {
      "id": "yourBroadcastId",
      "status": "STOPPED",
      "liveAt": "2018-08-13T15:23:03.000Z",
      "previewedAt": "2018-08-13T15:22:30.000Z",
      "stoppedAt": "2018-08-13T15:23:31.000Z"
    }
  }
}

Deactivate the broadcast

Use the following operation, with yourBroadcastId, to deactivate a broadcast.

mutation deactivateBroadcastEncoders {
  deactivateBroadcastEncoders(broadcastId: "yourBroadcastId") {
    id
  }
}
When you've successfully deactivated your broadcast, you should see a response similar to the following:
{
  "data": {
    "deactivateBroadcastEncoders": {
      "id": "yourBroadcastId"
    }
  }
}

Note: Deactivated broadcasts can be reactivated and used again. However, if you intend to use a broadcast again make sure to reset the broadcast's status to IDLE after deactivating it. This ensures it's in a good state when you use it again.

Useful queries 


The following is a list of useful queries. For a complete list, see the documentation in the GraphiQL app.

  • All namespaces
    query allNamespaces {
      allNamespaces {
        id
        name
      }
    }
  • All encoders
    query allEncoders {
      allEncoders {
        id
        name
        deviceId
      }
    }
  • All encoders by deviceId 
    query encoderByDeviceId {
      encoderByDeviceId(deviceId: "encoderUUID") {
        id
        name
        deviceId
      }
    }
  • All broadcasts
    query allBroadcasts {
      allBroadcasts {
        id
        name
        inputs {
            inputType
            videoInput
            videoFrameWidthMax
            videoFrameHeightMax
            videoFrameRateMax
            videoAspectRatioMode
            videoAspectRatioWidth
            videoAspectRatioHeight
            videoAspectRatioRotation
            audioLevel
            overlayVendor
            overlayUrl
        }
        outputs {
          id
          encodingConfiguration {
            name
            encodingConfigurationVideo {
              codec
              bitrate
            }
            encodingConfigurationAudio {
              codec
              bitrate
            }
          }
          streamTargets {
            id
            url
            protocol
            streamTargetEncoderIndex
          }
          recordings {
            id
            format
          }
        }
        displays {
          id
        }
        broadcastEncoders {
          id
          streamTargetEncoderIndex
          broadcastInputEncoderIndex
          encoder {
            id
            deviceId
            name
          }
        }
      }
    
    }
  • A broadcast
    query broadcasts {
      broadcast(id: "yourBroadcastId") {
        id
        name
        createdAt
        updatedAt
        previewedAt
        liveAt
        stoppedAt
        inputs {
            inputType
            videoInput
            videoFrameWidthMax
            videoFrameHeightMax
            videoFrameRateMax
            videoAspectRatioMode
            videoAspectRatioWidth
            videoAspectRatioHeight
            videoAspectRatioRotation
            audioLevel
            overlayVendor
            overlayUrl
        }
        broadcastEncoders {
          id
          streamTargetEncoderIndex
          broadcastInputEncoderIndex
          encoder {
            id
            deviceId
            name
          }
        }
        outputs {
          id
          encodingConfiguration {
            name
            encodingConfigurationVideo {
              codec
              bitrate
            }
            encodingConfigurationAudio {
              codec
              bitrate
            }
          }
          streamTargets {
            id
            url
            protocol
            streamTargetEncoderIndex
          }
          recordings {
            id
            format
          }
        }
      }
    }