Use the Wowza ClearCaster GraphQL API

The Wowza™ ClearCaster GraphQL API enables you to manage your Wowza ClearCaster™ appliance and broadcasts directly via the API. GraphQL APIs are structured so that the operations mirror the responses.

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

Note: Wowza ClearCaster version 2.0.0.07 or later is required.


Overview of the Wowza ClearCaster 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 ClearCaster 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 ClearCaster 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 QuickSync hardware-accelerated transcoding (QuickSync)
    • H.265
      • Intel QuickSync hardware-accelerated transcoding (QuickSync)

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

Use GraphiQL to access Wowza ClearCaster GraphQL API


We recommend using the GraphiQL app, an interactive, browser-based IDE for exploring and using GraphQL APIs. You can use GraphiQL the same way you might use Postman to test and learn about other types of APIs. For your convenience, we provide an instance of GraphiQL for you to use to explore the wowza ClearCaster GraphQL API.

Note: For more information about GraphiQL, see GraphiQL .
  1. Sign in to Wowza ClearCaster Manager at clearcaster.wowza.com.
  2. Click Manage in the menu bar, click the Integrations tab, and then click Generate a new ClearCaster API Key.
  3. Enter a name for your API key, and then click Generate a new ClearCaster API Key.
    Important! You must save the API key and Secret Key provided. They are only displayed once, but must be provided every time you decide to use GraphQL.
  4. Open clearcaster.c2.woza.com/graphiql in a new browser tab, and enter your GraphQL Credentials (API key, secret key, and the GraphQL URL) the following format: {"key":"[api-key]","secret":"[secret-key]","url":"clearcaster.c2.wowza.com/graphql"}
    Where:
    • [api-key] is the API Key value generated in Wowza ClearCaster Manager.
    • [secret-key] is the corresponding Secret Key value generated in Wowza ClearCaster Manager.
  5. Click Submit. The GrapiQL interface will automatically open in a new window.

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
          }
        }
      }
    }