• How to use CDNs and services to distribute live streams (push publishing)

    The Stream Targets feature in Wowza Streaming Engine™ live streaming software (version 4.2.0 and later) allows you to send live streams to destinations such as content delivery networks (CDNs) and services over a variety of protocols. The destinations distribute your live stream, enabling you to scale your Streaming Engine implementation, computing resources, and delivery options for a variety of scenarios.

    For example, you can use Stream Targets to send a live stream to:

    • The Wowza Streaming Cloud™ live streaming service, which can transcode and deliver the stream to viewers anywhere around the world.

    • A third-party content delivery network (CDN), which can deliver the broadcast to viewers using a global edge network.

    • Video-sharing websites such as YouTube Live or Facebook Live, which can host playback of the event on their own portal.

    • A live application on another Wowza Streaming Engine software instance, which can transcode and deliver the stream to viewers.

    The Stream Targets graphical user interface in Wowza Streaming Engine Manager lets you send live streams to CDNs, streaming servers, streaming services, and multicast networks—without manually editing an XML map file. Alternatively, if you prefer, you can manually edit and manage a map file to send live source streams to these destinations.

    Contents


    Send streams to destinations using Wowza Streaming Engine 4.2 and later
    Send streams to destinations using Wowza Streaming Engine 4.1 and earlier
    About editing the push publishing map file
    Debugging connections
    About the push publishing API
    Send streams to destinations using Wowza Media Server 3.6.4

    Send streams to destinations using Wowza Streaming Engine 4.2 and later


    The easiest way to send live streams to distributed destinations is to use the Stream Targets graphical user interface in Wowza Streaming Engine. You don't have to install any modules or manually edit an XML map file, and the stream targets are displayed alphabetically (by destination type, protocol, adaptive group name (HTTP protocols only), and then stream target name) with an automatically-updated status for each. For instructions on how to use Stream Targets for your desired workflow, see any of the following articles:


    Note: If you manually created stream targets by editing the push publishing map file in earlier versions of Wowza media server software, those map entries will appear in your live application's Stream Targets page in Wowza Streaming Engine Manager when you upgrade to Wowza Streaming Engine 4.2 and later. Targets that were defined as RTMP will appear as generic RTMP targets, even if they point to a BitGravity, Mirror Image, or YouTube destination.

    Send streams to destinations using Wowza Streaming Engine 4.1 and earlier


    If you're using Wowza Streaming Engine 4.1 or earlier, you must install the ModulePushPublish module, which listens for incoming live streams (source streams) published to the server.

    1. In Wowza Streaming Engine Manager, click the desired live application in the contents panel.

    2. On the live application page, click the Modules tab.

      Note: Access to the Modules tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
    3. On the Modules tab, click Edit, click Add Module, and then add the following in the Add New Module dialog box:

      Name ModulePushPublish
      Description ModulePushPublish
      Fully Qualified Class Name com.wowza.wms.pushpublish.module.ModulePushPublish


    4. Click Add, then Save, and then click Restart Now when prompted to apply the changes.

    About editing the push publishing map file


    The PushPublishMap.txt map file stores the configuration that maps live source streams to destinations. In Wowza Streaming Engine 4.2 and later, you can manage the map file configuration using the Stream Targets feature in Wowza Streaming Engine Manager. In earlier versions of the Streaming Engine software, and in Wowza Media Server 3.6, you edit the map file in a text editor to manage the configuration.

    Managing the map file

    By default, Wowza Streaming Engine 4.2 (and later) uses a unique map file for each application. The default pushPublishMapPath property value for the default live application in the software and for any new live applications that you create is ${com.wowza.wms.context.VHostConfigHome}/conf/${com.wowza.wms.context.Application}/PushPublishMap.txt. This means the default map file location is [install-dir]/conf/[application]/PushPublishMap.txt. The map file is automatically created for you in this location when you enable the Stream Targets feature.

    Earlier versions of Streaming Engine software (and Wowza Media Server 3.6) use a single map file for all applications by default. To configure a unique map file for an individual application, copy the [install-dir]/conf/PushPublishMap.txt file to the [install-dir]/conf/[application] folder and then define the pushPublishMapPath property in the application's configuration file (Application.xml) using the ${com.wowza.wms.context.Application} variable to point to the appropriate path. If pushPublishMapPath isn't explicitly defined for an application in Application.xml, the default path value, [install-dir]/conf/PushPublishMap.txt, is used.

    To change the default map file location for your applications, update the pushPublishMapPath property value to the desired location, and then make sure that you copy the [install-dir]/conf/PushPublishMap.txt map file to this location so that the Wowza media server software can find the file. You can do this in Wowza Streaming Engine Manager for Wowza Streaming Engine 4.2 and later or by editing the application's configuration file in a text editor.

    pushPublishMapPath property details


    Path
    Name
    Type
    Example Values
    Notes
    Root/Application pushPublishMapPath String ${com.wowza.wms.context.VHostConfigHome}/conf/${com.wowza.wms.context.Application}/PushPublishMap.txt

    ${com.wowza.wms.context.VHostConfigHome}/conf/PushPublishMap.txt
    Defines the path to the publishing map file. Can be made application-specific using Wowza Application variable notation.

    Applies to all push publishing profiles.

    Update the map file path property in Wowza Streaming Engine Manager 4.2 and later


    1. In Wowza Streaming Engine Manager, click the Applications tab, and then click the name of your live application in the contents panel.

    2. On the live application's Properties tab, in the Quick Links list, click Custom.

      Note: Access to the Properties tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
    3. In the Custom area, click Edit, and then update the pushPublishMapPath property value.

    4. Click Save, and then restart the application to apply the changes.

    Update the map file path property in Application.xml


    Use a text editor to open the [install-dir]/conf/[application]/Application.xml file for your live application and update the pushPublishMapPath property to the desired value. Then, restart the Wowza media server software to apply the changes.

    Note: If you upgrade your Wowza media server software that has push publishing enabled to Wowza Streaming Engine 4.2 or later, the Stream Targets feature will look for the map file specified by the pushPublishMapPath property for your older configuration.

    About map entries

    Each line in the map file represents a single destination for a given source stream. You can send one source stream to multiple destinations by adding multiple entries for that stream name. Map entries can be added or modified while Wowza Streaming Engine is running. Modifications don't affect streams that are currently running. Only streams received by Streaming Engine after the map file is updated are affected.

    A map entry has the following format:

    [source-stream-name]={"profile":"[profile]", [additional-configuration-items]}

    For example, to use the RTMP protocol to send a stream named myStream to another media server that's running Wowza Streaming Engine software, the PushPublishMap.txt file entry looks like this:

    myStream={"profile":"rtmp", "streamName":"myStream", "host":"wowza.myserver.com", "userName":"myUser", "password":"myPassword"}

    To send a stream to more than one destination, add multiple map entries for the stream. For example, to send a stream named myStream to a remote media server that's running Streaming Engine software and also to deliver it as multicast using MPEG-TS, add the following entries to the map file:

    myStream={"profile":"rtmp", "streamName":"myStream", "host":"wowza.myserver.com", "userName":"myUser", "password":"myPassword"}
    myStream={"profile":"mpegts", "streamName":"myStreamMPEGTS", "host":"239.1.1.1", "port":"10000"}

    Note: The PushPublishMap.txt file supports quotation (") marks around the keys and value strings, in compliance with the JSON specification.
    Each map entry refers to a profile that defines how the stream is published and determines which additional configurable parameters are available. For details, see About map profiles below.

    For sample map file entries for many destinations, see Sample map file entries for Stream Target destinations (push publishing).

    About map profiles

    Each map entry in the PushPublishMap.txt map file refers to a profile that defines how the stream is sent to its destination and determines which additional configurable parameters are available. This section lists the available profiles and each profile's parameters:


    rtmp, rtmp-akamai, and rtmp-limelight profile parameters


    Name Description
    streamName Destination stream name (default is the source stream name). A destination stream name is required for rtmp-akamai profiles. See Akamai RTMP for more information.
    application Destination application name (default is _defapp_).
    appInstance Destination application instance name (default is _definst_).
    host Destination hostname or IP address (default depends on the profile).
    port Destination port number (default is 1935).
    userName Destination server user name (needed if the destination requires authentication).
    password Destination server password (needed if the destination requires authentication).
    secureTokenSharedSecret SecureToken value to use to connect to remote server (needed if the destination is configured to use SecureToken).
    adaptiveStreaming Set to true if doing adaptive bitrate streaming (default is false). Automatically sets sendOriginalTimecodes to true and originalTimecodeThreshold to 0x100000.
    sendFCPublish Set to true to call the FCPublish command before publishing begins (default is true).
    sendReleaseStream Set to true to call the releaseStream command before publishing begins (default is true).
    sendStreamCloseCommands Set to true to send stream close commands when publishing stops (default is true).
    removeDefaultAppInstance Set to true to remove the _definst_ instance name from the connect command (default is true).
    sendOriginalTimecodes Set to true to send source streams absolute timecodes (needed for adaptive bitrate streaming; default is false). Overrides the setting change done by adaptiveStreaming = true.
    originalTimecodeThreshold Used when sending original timecodes to a lower timecode magnitude (needed when Adobe Media Server is the destination server; default is 0). Overrides the setting change done by adaptiveStreaming = true.
    connectionFlashVersion Flash version to report as part of connection information (default depends on profile). The connectionFlashVersion value accepts the following variables:
    ${com.wowza.wms.pushpublish.CurrentFMLEVersion} - Current Adobe Flash Media Live Encoder version number: FMLE/3.0 (compatible with FMSc/1.0)
    ${com.wowza.wms.pushpublish.CurrentFlashVersion} - Adobe Flash Player version: WIN 10,0,12,36
    ${com.wowza.wms.pushpublish.PushPublishVersion} - Wowza Streaming Engine push publishing version
    queryString Query string data added to URL as part of connection information (default is [no-value]).
    debugLog Set to true to turn on debug connection logging (default is false).
    debugPackets Set to true to turn on verbose packet logging (default is false).
    localBindAddress Local network interface to bind the output stream connection to, in the form of an IP address (default is the system default interface).
    sendSSL Set to true to connect two Wowza Streaming Engine servers over RTMP using SSL (default is false).
    removeMetadataObjects
    (Available for use in Wowza Streaming Engine 4.2 and later.)
    Set to true to enable removal of all array and object data types sent to the destination in RTMP onMetaData messages.
    filteredMetadataItems
    (Available for use in Wowza Streaming Engine 4.2 and later.)
    Specifies a pipe-delimited list ("|") of named metadata items to remove from all RTMP onMetaData messages sent to the destination.
    akamai.hdNetwork Set to false to allow plain (non-[name]_[angle]_[bitrate]) stream names for Akamai AMS network (rtmp-akamai only; default is true).
    akamai.streamId Destination StreamId (rtmp-akamai only).
    akamai.sendToBackupServer If set to true, the destination is set to the backup entry point (rtmp-akamai only; default is false).

    cupertino-akamai and sanjose-akamai profile parameters


    Name Description
    streamName
    (required)
    Destination stream name. See URL formats below. All entries in an adaptive bitrate set (adaptiveGroup) must have unique streamName values. We recommend including the bitrate or vertical resolution of the stream, such as myStream_720p. It's sufficient to set the streamName to the same value as the source stream name.
    cupertino.renditions Renditions to include. Valid values are: audiovideo and audioonly. If not specified, defaults to audiovideo.
    This setting is used primarily for single stream playback, but multiple renditions can be specified in a pipe-delimited list ("|"). For example, if you turn on the LiveStreamPacketizer property cupertinoCreateAudioOnlyRendition, then you can specify "audiovideo|audioonly". This will then push both an audio/video stream and an audio-only stream, providing Apple AppStore compliance.
    cupertino.playlistCount Deprecated. See http.playlistCount.
    cupertino.playlistAcrossSessions Deprecated. See http.playlistAcrossSessions.
    cupertino.playlistTimeout Deprecated. See http.playlistTimeout.
    http.playlistCount Number of chunks to maintain in the playlist. The default value (0) means that live stream packetizer PlaylistChunkCount property values in the application configuration specify the playlistCount:
    cupertinoPlaylistChunkCount property - default is 3
    sanjosePlaylistChunkCount property - default is 4
    http.playlistAcrossSessions Set to true to maintain playlists across push publishing sessions (default is false).
    http.playlistTimeout Time in milliseconds that a cross-session playlist is maintained (default is 120000 – 2 minutes).
    http.fakePosts A true/false debug-only parameter that instructs the server to "fake" posting of cupertino or sanjose files to Akamai, in terms of logging. Used to isolate internal server errors from Akamai server communication errors. No actual files are pushed so playback doesn't occur.
    debugLog Set to true to turn on debug connection logging (default is false).
    http.writerDebug A true/false debug-only parameter that enables debug logging associated with HTTP connections, including information about failed connections, retries, and socket read/write timing.
    akamai.streamId
    (required)
    Destination Akamai StreamId.
    akamai.hostId Destination Akamai HostId (if not specified, defaults to example-i).
    akamai.eventName
    (optional)
    Destination event name.
    adaptiveGroups
    (optional)
    Specifies multiple renditions in a pipe-delimited list. For details about this parameter, see About adaptive groups.
    akamai.sendToBackupServer Deprecated. See akamai.destinationServer.
    akamai.destinationServer
    (optional)
    Destination Akamai server(s) to send stream to for redundancy. Valid values are: primary, backup, or redundant. Similar to akamai.sendToBackupServer, but allows a single map entry to be pushed to both primary and backup servers when redundant is specified. Overrides akamai.sendToBackupServer when both are present in the same map entry.

    Specifying redundant also generates a separate redundancy manifest/playlist that provides playback URLs for both the primary and backup streams.
    sanjose.representationId Defines a unique ID string for the stream representation used in the naming of the HDS stream-level manifest and bootstrap file names, and the bootstrapInfo ID and media URL values in the stream level manifest. Can be any string of alphanumeric characters.
    If not provided, a calculated bitrate value in kbps is used as the representationId such as "752kbps", so a resulting stream-level manifest file name could be "752kbps.f4m".

    Akamai HTTP protocol playback URL formats


    Primary stream with akamai.eventName specified:
    HLS: http://[akamai.hostId].akamaihd.net/hls/live/[akamai.streamId]/[akamai.eventName]/[streamName]/playlist.m3u8
    HDS: http://[akamai.hostId].akamaihd.net/hds/live/[akamai.streamId]/[akamai.eventName]/[streamName]/setlevelmanifest.f4m

    Primary stream with akamai.eventName NOT specified:
    HLS: http://[akamai.hostId].akamaihd.net/hls/live/[akamai.streamId]/[streamName]/playlist.m3u8
    HDS: http://[akamai.hostId].akamaihd.net/hds/live/[akamai.streamId]/[streamName]/setlevelmanifest.f4m

    Backup stream with akamai.eventName specified:
    HLS: http://[akamai.hostId].akamaihd.net/hls/live/[akamai.streamId]-b/[akamai.eventName]/[streamName]/playlist.m3u8
    HDS: http://[akamai.hostId].akamaihd.net/hds/live/[akamai.streamId]-b/[akamai.eventName]/[streamName]/setlevelmanifest.f4m

    Redundant stream with akamai.eventName NOT specified:
    HLS primary: http://[akamai.hostId].akamaihd.net/hls/live/[akamai.streamId]/[streamName]_red/playlist.m3u8
    HLS backup: http://[akamai.hostId].akamaihd.net/hls/live/[akamai.streamId]-b/[streamName]_red/playlist.m3u8
    HDS primary: http://[akamai.hostId].akamaihd.net/hds/live/[akamai.streamId]/[streamName]_red/setlevelmanifest.f4m
    HDS backup: http://[akamai.hostId].akamaihd.net/hds/live/[akamai.streamId]-b/[streamName]_red/setlevelmanifest.f4m

    Primary stream in adaptive group with akamai.eventName specified:
    HLS: http://[akamai.hostId].akamaihd.net/hls/live/[akamai.streamId]/[akamai.eventName]/[adaptiveGroup]/playlist.m3u8
    HDS: http://[akamai.hostId].akamaihd.net/hds/live/[akamai.streamId]/[akamai.eventName]/[adaptiveGroup]/setlevelmanifest.f4m

    Primary stream in adaptive group with akamai.eventName NOT specified:
    HLS: http://[akamai.hostId].akamaihd.net/hls/live/[akamai.streamId]/[adaptiveGroup]/playlist.m3u8
    HDS: http://[akamai.hostId].akamaihd.net/hds/live/[akamai.streamId]/[adaptiveGroup]/setlevelmanifest.f4m

    Backup stream in adaptive group with akamai.eventName specified:
    HLS: http://[akamai.hostId].akamaihd.net/hls/live/[akamai.streamId]-b/[akamai.eventName]/[adaptiveGroup]/playlist.m3u8
    HDS: http://[akamai.hostId].akamaihd.net/hds/live/[akamai.streamId]-b/[akamai.eventName]/[adaptiveGroup]/setlevelmanifest.f4m

    Notes:
    • In cases where both akamai.destinationServer:"redundant" and adaptiveGroups:"[groupName]" are specified, a redundancy manifest/playlist won't be generated for the stream and the adaptive group manifest/playlist should instead be used for playback, since both the primary and backup streams will be listed there as well.

    • Akamai encoder documentation indicates that their ingest servers only support 6-second chunk durations in the current version of their product for Adobe HDS. The Streaming Engine default chunk duration is 10 seconds for HDS. Therefore, we recommend changing the sanjoseChunkDurationTarget property value in Wowza Streaming Engine Manager to 6000 (6 seconds) for applications configured to send HDS streams to Akamai. Also, to ensure that accurate chunk durations are produced, we recommend that the the source stream is encoded with 1, 2, or 3-second keyframe intervals.

    rtp profile parameters


    Name Description
    streamName Base file name of the SDP file.
    host Destination hostname or IP address.
    videoPort Destination video port (2 ports are used).
    audioPort Destination audio port (2 ports are used).
    timeToLive When streaming over multicast, this is the time to live (TTL) value for the UDP packets (default is 63).
    streamWaitTimeout At stream startup, the time in milliseconds to wait for the stream to be recognized and accepted (default is 5000).

    mpegts profile parameters


    Name Description
    streamName Base file name of the SDP file.
    host Destination hostname or IP address.
    port Destination port.
    timeToLive When streaming over multicast, this is the time to live (TTL) value for the UDP packets (default is 63).
    rtpWrap Set to true to wrap the MPEG-TS stream in RTP (default is false).

    wowza-streaming-cloud profile parameters


    Name Description
    connectionCode The 6-digit, single-use Connection Code available in Wowza Streaming Cloud, on the Overview tab of the live stream detail page. The Connection Code is automatically replaced with a longToken field after the initial connection is made. If the longToken field is accidentally deleted, you must generate a new Connection Code in Wowza Streaming Cloud and enter it in the connectionCode field in the map file.
    debugLog Set to true to turn on debug logging of the communications with the Wowza Streaming Cloud service (default is false).
    debugLogChildren Set to true to turn on debug logging of the child push publishing session initiated with the Wowza Streaming Cloud transcoder instance (default is false).

    shoutcast1 profile parameters


    Note: Streaming to SHOUTcast 1 requires Wowza Streaming Engine 4.5.0 or later.
    Name Description
    host (required) Destination hostname or IP address.
    port (required) Destination port.
    password (required) The broadcasting password.
    shoutcast.public Set to true to announce the stream in the SHOUTcast directory (default is false).
    shoutcast.name The name of the SHOUTcast 1 server, which should be short and reflect a brand or describe the stream’s content.
    shoutcast.genre The type of audio style being sent to the server. For example, Rock or Classical.
    shoutcast.url The absolute URL (i.e., beginning with http:// or https://) sent to the SHOUTcast 1 server. For example, https://www.wowza.com.
    shoutcast.aim The AOL Instant Messanger (AIM) number sent to the server when the connection is established.
    shoutcast.icq The I See You (ICQ) number sent to the server when the connection is established.
    shoutcast.irc The Internet Relay Chat (IRC) number sent to the server when the connection is established.

    shoutcast2 profile parameters


    Note: Streaming to SHOUTcast 2 requires Wowza Streaming Engine 4.5.0 or later.
    Name Description
    host (required) Destination hostname or IP address.
    port (required) Destination port.
    userName (required) The user name/authentication hash required to connect to the destination server. This information is obtained from the SHOUTcast 2 configuration utility.
    password (required) The broadcasting password.
    streamName (required) The stream mount point/ID assigned when configuring the SHOUTcast 2 server. This is commonly a number, and is unique per stream on the destination SHOUTcast server.
    shoutcast.public Set to true to announce the stream in the SHOUTcast directory (default is false).
    shoutcast.name The name of the SHOUTcast 2 server, which should be short and reflect a brand or describe the content.
    shoutcast.genre The type of audio style being sent to the server. For example, Rock or Classical.
    shoutcast.url The absolute URL (i.e., beginning with http:// or https://) sent to the SHOUTcast 2 server. For example, https://www.wowza.com.
    shoutcast.aim The AOL Instant Messanger (AIM) number sent to the server when the connection is established.
    shoutcast.icq The I See You (ICQ) number sent to the server when the connection is established..
    shoutcast.irc The Internet Relay Chat (IRC) number sent to the server when the connection is established.

    icecast2 profile parameters


    Note: Streaming to Icecast 2 requires Wowza Streaming Engine 4.5.0 or later.
    Name Description
    host (required) Destination hostname or IP address.
    port (required) Destination port.
    userName (required) The user name/authentication hash required to connect to the destination server. This information is obtained from the Icecast 2 configuration utility.
    password (required) The password required to connect to the destination server.
    streamName (required) The stream mount point/ID assigned when configuring the Icecast 2 server. This is commonly a number, and is unique per stream on the destination Icecast server. It should be noted that a suffix outlining the content type (i.e. .mp3 or .aac) should be used.
    icecast2.public Set to true to announce the stream in the Icecast 2 directory (default is false).
    icecast2.name The name of the Icecast 2 server, which should be short and reflect a brand or describe the stream’s content.
    icecast2.genre The type of audio style being sent to the server. For example, Rock or Classical.
    icecast2.url The absolute URL (i.e., beginning with http:// or https://) sent to the Icecast 2 server. For example, https://www.wowza.com.
    icecast2.aim The AOL Instant Messanger (AIM) number sent to the server when the connection is established.
    icecast2.icq The I See You (ICQ) number sent to the server when the connection is established.
    icecast2.irc The Internet Relay Chat (IRC) number sent to the server when the connection is established.

    Debugging connections


    To debug stream-level issues such as connection problems with a destination, you can configure debugging on a per-destination, per-map file entry basis with the debugLog and debugPackets map file parameters. When enabled, debugLog logs high-level connection information as well as connection health. For RTMP-specific debugging at the packet level, debugPackets logs verbose per-packet information.

    The following example map file entries show how these parameters are used:
    myStream={"profile":"rtmp", "streamName":"myStream", "host":"wowza.myserver.com", "userName":"myUser", "password":"myPassword", "debugLog":"true", "debugPackets":"true"}
    myStream={"profile":"cupertino-akamai", "streamName":"myStream", "cupertino.renditions":"audiovideo", "akamai.streamId":"215930", "akamai.hostId":"wowzadevapple-i", "debugLog":"true"}

    For advanced debugging needs, see How to debug Stream Targets (push publishing).

    About the push publishing API


    Push publishing in Wowza Streaming Engine software includes a low-level application programming interface (API) for building custom publishing applications. The Javadocs for the API are included in the documentation/serverapi folder in the Wowza Streaming Engine software installation (see com.wowza.wms.pushpublish.* packages in the documentation).

    You can download an example module that demonstrates how to use the push publishing APIs to push an RTMP stream to a remote server. This module listens for new streams to be published and will push them back to the application with the name push-[streamName]. When the stream is stopped (unpublished), it disconnects the push publishing stream.

    To install the module, see the README.html file in the compressed (zipped) folder for instructions.

    Send streams to destinations using Wowza Media Server 3.6.4


    If you're using Wowza Media Server™ software version 3.6.4, you must install the Push Publishing AddOn package in order to send streams to CDNs, services, and other destinations. To get the Push Publishing AddOn, fill out the AddOn Request form. In the form, be sure to select the Check to Request Push Publishing check box. After your information has been verified, you'll receive an email within three (3) business days that includes download instructions.

    Note: The AddOn package has instructions for installing and using the AddOn in the Readme.html file. Changes and updates to this AddOn are listed in the version.txt file.

    Additional help and resources




    Originally Published: 10-02-2010.
    Updated: For Wowza Streaming Engine 4.5.0 on 06-23-2016.

    If you're having problems or want to discuss this article, post in our forum.