Migrate from v1.5 to v1.6

Updated on 04/19/2022 12:43 pm PDT

A number of things have changed between version 1.5 and 1.6 of the API. While this guide includes most changes you need to know, see the Wowza Video REST API reference documentation to confirm specific details of endpoint behavior in v1.6.

What's changed

This topic covers REST API changes that occurred between the release of v1.5 and v1.6. These changes fall into two categories:

  • Changes present only in v1.6.
  • Changes that originate from the development of v1.6, but also retroactively apply to earlier versions of the API. These are non-breaking changes unless otherwise communicated by Wowza.

Highlights:

  • Wowza CDN on Akamai usage data – Previously, v1.3 was the most recent REST API version to return Akamai stream target data in the /usage/stream_targets endpoints. Now you can upgrade from v1.3 to any newer version of the API and have Akamai data returned.
  • WebRTC playback – You can ingest and playback WebRTC streams for low latency, near real time delivery of streams.


Only in v1.6

Over the course of development, we made the following changes to the REST API from v1.5 to v1.6. These changes are present in v1.6 only.

Direct playback URLs
Audio and video codecs
Ingest IP whitelist
Playback stream name
File names for recordings

Direct playback URLs

In v1.6, we replaced playback_url with playback_urls in the response for the following endpoints:

  • POST /stream_targets/fastly
  • GET /stream_targets/fastly/[target_id]
  • PATCH /stream_targets/fastly/[target_id]
v1.5v1.6
{
   "playback_url": "https://[wowzasubdomain].wowza.com/1/TWhoL3BiZnJXMFhmNzZVN3JrZDAwUT09/ZmYxSXRrTERrUlk9/hls/live/playlist.m3u8"
}
{
  "playback_urls": {
    "hls": [
      {
        "name": "default",
        "url": "https://[wowzasubdomain].wowza.com/1/TWhoL3BiZnJXMFhmNzZVN3JrZDAwUT09/ZmYxSXRrTERrUlk9/hls/live/playlist.m3u8"
      }    
    ]
  }
}

Audio and video codecs

In v1.6, we added functionality that allows you to specify audio and video codecs, from a limited set of options, for output renditions in the transcoder workflow. The following is the full list of options for the audio_codec and video_codec parameters:

  • audio_codec
    • aac – Transcodes the audio to AAC. AAC is the most commonly compatible audio codec for protocols.
    • opus – Transcodes the audio to Opus. Opus is used for WebRTC streams.
    • passthrough – Sends the stream to the target without transcoding the audio data.
    • disabled – Sends the stream to the target without an audio track.
  • video_codec
    • h264 – Transcodes the video to H.264. H.264 is the most commonly compatible video codec for protocols.
    • passthrough – Sends the stream to the target without transcoding the video track.
    • disabled – Sends the stream to the target without a video track.

The audio_codec and video_codec parameters replace the stream_format, passthrough_audio, and passthrough_video parameters in the following endpoints:

  • POST /transcoders/[transcoder_id]/outputs
  • GET /transcoders/[transcoder_id]/outputs
  • GET /transcoders/[transcoder_id]/outputs/[id]
  • PATCH /transcoders/[transcoder_id]/outputs/[id]
v1.5v1.6
{
  "output": {
    "stream_format": "audiovideo",
    "aspect_ratio_height": 480,
    "aspect_ratio_width": 848,
    "bitrate_audio": 128,
    "bitrate_video": 1600,
    "framerate_reduction": "1/2",
    "h264_profile": "main",
    "keyframes": "follow_source"
    "passthrough_audio": false,
    "passhtrough_video": false
  }
}
{
  "output": {
    "video_codec": "h264",
    "audio_codec": "aac",
    "aspect_ratio_height": 480,
    "aspect_ratio_width": 848,
    "bitrate_audio": 128,
    "bitrate_video": 1600,
    "framerate_reduction": "1/2",
    "h264_profile": "main",
    "keyframes": "follow_source"
  }
}

Ingest IP whitelist

In v1.6, we renamed the ingest_ip_whitelist parameter to ingest_ip_allowlist in the following endpoints:

  • POST /stream_targets/ull
  • GET /stream_targets/ull/[id]
  • PATCH /stream_targets/ull/[id]

Playback stream name

In v1.6, we added playback_stream_name to the responses for the following endpoints:

  • POST /live_streams
  • GET /live_streams/[id]
  • PATCH /live_streams/[id]
  • POST /transcoders
  • GET /transcoders/[id]
  • PATCH /transcoders/[id]
"playback_stream_name": "wxyz6789"

File names for recordings

In v1.6, we added the file_name parameter to the response for the GET /recordings endpoint.

"file_name": "31a4f9f4.stream.0.mp4"

In v1.6 and earlier versions

After the release of version 1.5 and during the development of version 1.6, we made the following changes to 1.6 that also retroactively change earlier versions of the API. You might already be aware of these changes as they've been released and the changes communicated through the Wowza Video REST API release notes, but you might still consider them as you upgrade to version 1.6.

Wowza CDN on Akamai usage data
WebRTC playback
Passthrough for WebRTC live streams
Stream a file
Access Control: Allow Origin property
Direct playback connection limit
Format of direct playback URL names
Application name length
Current viewer data updates
Maximum value for playlistSeconds
Outputs per transcoder

Wowza CDN on Akamai usage data

Change present in: v1.4 through v1.6

We added usage data for Wowza CDN on Akamai stream targets to the following endpoints:

  • /usage/stream_targets
  • /usage/stream_targets/summary
  • /usage/stream_targets/[id]
  • /usage/stream_targets/[id]/countries
  • /usage/stream_targets/[id]/renditions
Important: Previously, v1.3 was the most recent REST API version to return Akamai stream target data in the /usage/stream_targets endpoints. This change allows customers who remained on v1.3 for the Akamai data to upgrade to a newer version of the REST API and retain the ability to retrieve that data.

WebRTC playback

Change present in: v1.3 through v1.6

We added functionality to the Wowza Video REST API that allows you to deliver WebRTC streams for playback directly from the transcoder. You can do direct playback using the /live_streams or /transcoders endpoints. See WebRTC workflows in Wowza Video to learn more about WebRTC and the workflows you can choose from.

Passthrough for WebRTC live streams

Change present in: v1.3 through v1.6

We removed passthrough as a transcoder_type for WebRTC streams created through the /live_streams endpoint.

Stream a file

Change present in: v1.5 and v1.6

We removed the file value from the delivery_method parameter for the following endpoints:

  • POST /live_streams
  • GET /live_streams/[live_stream_id]
  • PATCH /live_streams/[live_stream_id]
  • POST /transcoders
  • GET /transcoders/[transcoder_id]
  • PATCH /transcoders/[transcoder_id]

To create a live stream that uses a file as the source, you need to set the following values:

  • Live stream workflow: Set encoder to file, delivery_method to pull, and source_url to the URL where the file is located.
  • Transcoder workflow: Set protocol to file, delivery_method to pull, and source_url to the URL where the file is located.
Note: Existing live streams that use a file as the source were automatically updated to the new configuration. No further action is required.

Live stream workflow

v1.4v1.5 and v1.6
{
   "live_stream": {
     "aspect_ratio_height": 1080,
     "aspect_ratio_width": 1920,
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "delivery_method": "file",
     "encoder": "file",
     "hosted_page": true,
     "hosted_page_sharing_icons": true,
     "name": "MyLiveStream",
     "player_responsive": true,
     "source_url": "https://example.com/file.mp4",
     "transcoder_type": "transcoded"
   }
}
{
   "live_stream": {
     "aspect_ratio_height": 1080,
     "aspect_ratio_width": 1920,
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "delivery_method": "pull",
     "encoder": "file",
     "hosted_page": true,
     "hosted_page_sharing_icons": true,
     "name": "MyLiveStream",
     "player_responsive": true,
     "source_url": "https://example.com/file.mp4",
     "transcoder_type": "transcoded"
   }
}

Transcoder workflow

v1.4v1.5 and v1.6
{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "delivery_method": "file",
     "name": "MyTranscoder",
     "source_url": "https://example.com/file.mp4",
     "transcoder_type": "transcoded"
   } 
}
{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "delivery_method": "pull",
     "name": "MyTranscoder",
     "protocol": "file",
     "source_url": "https://example.com/file.mp4",
     "transcoder_type": "transcoded"
   } 
}

For more information, see Stream a file with the Wowza Video REST API.

Access Control: Allow Origin property

Change present in: v1.3 through v1.6

We added the acoa property for Wowza CDN on Fastly stream targets so you can explicitly specify the origin that can access the stream. While most streams won't need the origin explicitly set, you might use this property for older players that don't send the Referer header in their stream request. For more information, see Configure a property for a stream target.

"properties": [
      {
        "key": "acao",
        "section": "hls",
        "value": "http://<origin>"
      }
    ]

Direct playback connection limit

Change present in: v1.3 through v1.6

We changed the maximum value for the play_maximum_connections parameter from 100 to the maximum number of connections the specific transcoder can support. Generally, adaptive bitrate transcoders are larger and support more viewer connections (up to 300) while passthrough transcoders are smaller and support fewer viewer connections.

Format of direct playback URL names

Change present in: v1.3 through v1.6

We changed the format of the name object in direct_playback_urls to display the video and audio bitrate values for the output rendition.

Previousv1.3 through v1.6
"direct_playback_urls": {
  - "rtmp": [
      ...
      - {
        "name": "1280x720",
        "output_id": "0g116zkf",
        "url": "rtmp://abc123.entrypoint.video.wowza.com/app-B8P6K226/wxyz6789_stream2"
        }
       ...
  }
"direct_playback_urls": {
  - "rtmp": [
      ...
      - {
        "name": "V:1280x720+A:128K",
        "output_id": "0g116zkf",
        "url": "rtmp://abc123.entrypoint.video.wowza.com/app-B8P6K226/wxyz6789_stream2"
        }
       ...
  }

Application name length

Change present in: v1.5 and v1.6

We updated the transcoder application_name property to default to names that are eight characters in length instead of four.

v1.4v1.5 and v1.6
"application_name": "app-3757"
"application_name": "app-B8P6K226"

Current viewer data updates

Change present in: v1.4 through v1.6

We changed how often current viewer data is updated from 90 seconds to 5 minutes. Previously, unique_views would occasionally show the number of current viewers as 0.

Maximum value for playlistSeconds

Change present in: v1.3 through v1.6

We changed the maximum valid value for the stream target property, playlistSeconds, from 200 seconds to 28800 seconds (8 hours).

Outputs per transcoder

Change present in: v1.3 through v1.6

We adjusted transcoder functionality to allow only 10 output renditions per transcoder. Existing transcoders with more than 10 outputs retain those outputs, but you can't add more. For the best playback performance, we recommend limiting the outputs on a single transcoder to 8 or fewer.

© 2007–2024 Wowza Media Systems™, LLC. All rights reserved.   Security & Privacy PolicyLegalSystem Status