Debug CMAF streaming in Wowza Streaming Engine

Wowza Streaming Engine™ media server software version 4.7.8 and later can log debug information about CMAF live streams to help you monitor them, verify that they're running correctly, and troubleshoot problems that may arise.

Enable debug logging for CMAF streams


To use debug logging for CMAF streams, enable debug logging for individual HLS and MPEG-DASH streams. Streaming debug information is recorded to the wowzastreamingengine_access.log file.

HTTP adapter debug logging is enabled by default in Wowza Streaming Engine, but HLS and MPEG-DASH debug logging must be manually enabled by editing your Wowza Streaming Engine server's virtual host configuration in XML.

  1. Navigate to [install-dir]/conf/ and open VHost.xml in a text editor.
  2. Add the mpegdashAdapterDebugLog and cupertinoAdapterDebugLog properties to the <VHost> container element and set them to true. The XML should look like this:
    <VHost>
    ...
        <Properties>
            <Property>
                <Name>httpAdapterDebugLog</Name>
                <Value>true</Value>
                <Type>Boolean</Type>
            </Property>
            <Property>
                <Name>cupertinoAdapterDebugLog</Name>
                <Value>true</Value>
                <Type>Boolean</Type>
            </Property><Property>
                <Name>mpegdashAdapterDebugLog</Name>
                <Value>true</Value>
                <Type>Boolean</Type>
            </Property>
        </Properties>
    </VHost>
  3. Save your changes and restart Wowza Streaming Engine.

CMAF logging property reference


Wowza Streaming Engine can log the following custom properties for CMAF streams to the wowzastreamingengine_access.log file.

Name Type Description
cmafLogAACAudioGaps Boolean

When true, detects and logs gaps in AAC audio.

cmafLogStreamDriftAdjustments Boolean When true, logs the drift incurred between CMAF segments.
cmafMaxSegmentLogCount Integer

The number of created fMP4 segments to record in the log. Zero (0) logs all segments that are created. Specify a positive integer (n) to log the first n segments that are created.

cmafPtsAndDtsTimestampLogging Boolean When true, Wowza Streaming Engine logs presentation time stamp (PTS) and decoding time stamp (DTS) values on each video frame, the stamps' offset from each other, and whether the CMAF packetizer is aligning segments on PTS or DTS values. Use with caution. Enabling cmafPtsAndDtsTimestampLogging creates a significant number of additional log entries.
cmafSegmentTimecodeLogging Boolean When true, adds a log entry that indicates the segment ID and the start timecode for every audio and video segment.

Enable CMAF logging properties


Enable custom CMAF logging properties in Wowza Streaming Engine Manager or by editing the Application.xml file for your CMAF live stream application. We recommend enabling them by editing the live stream's Application.xml file.

  1. Navigate to the Application.xml file for your CMAF live stream application. If you're using the default live application that installs with Wowza Streaming Engine, navigate to [install-dir]/conf/live.
  2. Open Application.xml in a text editor.
  3. In the <LiveStreamPacketizer> container element, add the desired property or properties, making sure to specify a name, type, and value for each one. The XML looks like this:
<LiveStreamPacketizer>
    <Properties>
        <Property>
            <Name>cmafLogAACAudioGaps</Name>
            <Type>Boolean</Type>
            <Value>True</Value>
        </Property>
         <Property>
            <Name>cmafMaxSegmentLogCount</Name>
            <Type>Integer</Type>
            <Value>0</Value>
        </Property>
    </Properties>
</LiveStreamPacketizer>
 
  1. Save your changes and restart Wowza Streaming Engine.

Example CMAF log entries

Wowza Streaming Engine generates separate log entries for created CMAF audio and video segments. The entries look like this:

CmafWriterHandler.createSegmentM4S[live/_definst_/myStream][a]: Add segment: id:1 type:m4s_audio a:174 start:0 duration:4040

CmafWriterHandler.createSegmentM4S[live/_definst_/myStream][v]: Add segment: id:1 type:m4s_video v/k:120/2 start:23 duration:4000

CmafWriterHandler.createSegmentM4S[live/_definst_/myStream][a]: Add segment: id:2 type:m4s_audio a:172 start:4040 duration:3994

CmafWriterHandler.createSegmentM4S[live/_definst_/myStream][v]: Add segment: id:2 type:m4s_video v/k:120/2 start:4023 duration:4000

Log entries for cmafLogAACAudioGaps look like this:

LiveStreamPacketizerPacketHandler.handleHolderInternal[dash/_definst_/1.stream] AAC timecode gap/overlap; expected tc:23627, actual tc:127094, delta:103467ms (positive = gap, negative = overlap)

Where:

  • [a] or [v] indicates whether the chunk contains audio or video.
  • s is the segment number.
  • c is the chunk number.
  • f is the number of frames in the chunk that's being logged.
  • tf is the total number of frames in all chunks in the current segment. A running total, the tf value increases as chunks are added to the segment.

Log output for cmafPTSDTSTimestampLogging looks like this:

LiveStreamPacketizerPacketHandler.handleHolderInternal[live/_definst_/myStream][a/v] PTS/DTS: 434/567, offset: 133, breaking on: DTS

Review logs


It's a good idea to review log files frequently to monitor CMAF streams and identify problems as they arise.

Server log messages are written to the [install-dir]/logs/wowzastreamingengine_access.log file.

Error log messages are written to [install-dir]/logs/wowzastreamingengine_error.log file.

See View log messages in Wowza Streaming Engine Manager.

More resources