RTMP metadata plugin for Wowza
Overview
The intent of the plugin is to provide metadata forwarding from a RTMP origin stream to headers in the Cuppertino m3u8 chunklist responses; Possible use cases include latency monitoring between the encoder and wowza origin server, and passing specific application metadata from the encoder to your application (onDataEvent).
The plugin should be compatible against Wowza 4.7.0+.
Installing the plugin
Copy the provided jar files into your WowzaStreamingEngine's lib/ folder. On Linux
systems, the location for it is usually /usr/local/WowzaStreamingEngine/lib/.
You have to enable the GeoIP plugin for specific applications where you want to use it.
You should add the following configuration into the Application.xml in every application
that you want to enable it. The configuration should be added into the <Modules> section,
just after the <Module>...</Module> declaration for logging.
<Module>
<Name>RTMPMetadata</Name>
<Description>RTMP Metadata</Description>
<Class>com.titpetric.wse.module.RTMPMetadata</Class>
</Module>
The WowzaStreamingEngine needs to be restarted to enable the module.
Configuring logging
To configure the RTMP to HLS event logging, copy StreamLogConfig.json to your application
folder. This is located under [Wowza-dir]/conf/[selected-application].
{
"dir": "/usr/local/stream_log/",
"filename": "HLS.log"
}
The dir entry controls where the server will create log files, and the filename specifies
what the log file will be named. You'll have to use external tools like logrotate to archive
log contents.
Features
The plugin has no additional configuration available. Any events created on the encoder will be passed to a Cuppertino stream chunklist as m3u8 headers. The received headers are bound to the active chunk, but will persist as new chunks are added. When a chunk is removed from the chunklist, the old headers will be removed as well.
Events are formatted like this:
X-RTMP-[sequence]-[type]:[name]="value"
X-RTMP- standard plugin data prefix[sequence]- integer, sequence number of event received during a chunk[type]-DATAis the event payload,TIMEis the wowza timestamp when event was received[name]-onFI,onMetaData, ...value- a quoted string, may be anything from a timestamp foronFIevents, or JSON payload fromonDataEvent
A special header is always present:
#X-RTMP:LAST-CHUNK-TIME="2018-06-15 09:22:47.394"
This is the time when Wowza started processing a new video chunk. The timestamp will get updated only when a new chunk is produced. The time for that is based on your keyframe interval.
onMetaData event
This event is sent only once, on the first chunk. It may contain any of the following keys, or other keys not listed here:
| Key | Type | Example value |
|---|---|---|
| author | string | |
| copyright | string | |
| description | string | |
| keywords | string | |
| rating | string | |
| title | string | |
| presetname | string | Custom |
| creationdate | string | Wed Jun 13 11:27:54 2018\n |
| videodevice | string | Osprey-825e SDI-A Video Device 1 |
| framerate | number | 24.0 |
| width | number | 512.0 |
| height | number | 288.0 |
| videocodecid | string | avc1 |
| videodatarate | number | 200.0 |
| avclevel | number | 31.0 |
| avcprofile | number | 66.0 |
| videokeyframe_frequency | number | 1.0 |
| audiodevice | string | SDI Input A-1 (Osprey-825e 1) |
| audiosamplerate | number | 44100.0 |
| audiochannels | number | 1.0 |
| audioinputvolume | number | 75.0 |
| audiocodecid | string | mp4a |
| audiodatarate | number | 48.0 |
Other data may be sent, depending on encoder. The data is output as JSON.
onDataEvent event
This event is asumed to be an XML string. The module will attempt to parse it, and convert it to JSON. In case the parsing doesn't succeed, the event data will be returned as a plain string. This is useful when your events aren't XML formatted.
The intent of onDataEvent messages is to send these event payloads from the encoder to the video streaming server and then towards the application-aware clients. Possible uses include:
- Gaming, tracking drawn game cards in live card games, tracking lottery like systems with RFID sensors, minimizing things like dealer error or cheating,
- OCR (optical character recognition) for things like automated door systems, tracking entry and exit from private parking areas for billing (duration),
- Live events, tracking speaker schedules and providing information about the current speaker and talk track, time elapsed from start of current talk,
- Subtitling of event tracks done by a live transcription service or human effort
These are just some of the possible use cases where the payloads in the onDataEvent may be used to enrich the experience of watching video, or provide a separate data stream to leverage for custom clients.
onFI event
This event is sent for every key chunk. It contains timecode metadata from the encoder. This event may be disabled on encoders, and it's frequency configured.
onFI are name standardized cuepoints, and contain the absolute timecode injected by the encoder in configurable intervals. As example, you can send an onFI event every 10 frames, or every 30 frames.
The timecode event contains two fields:
sddate, formatdd-mm-yyyy, example:14-06-2018sttime, formathh:mm:ss.SSS, example:22:59:20.994"
This received data is reformatted into the following format:
2018-06-14 22:59:20.994
This value can be used to measure latency between the encoder and the Wowza server.
Last chunk time header
The plugin returns the Wowza server timestamp of the last received video chunk.
When you combine this with the onFI event, it's possible to calculate the latency
between when the video was encoded, and when the Wowza server received the event.
#X-RTMP:LAST-CHUNK-TIME="2018-06-15 09:22:47.394"
#EXTINF:1.006,
#X-RTMP-1-TIME:onFI="2018-06-15 09:22:46.499"
#X-RTMP-1-DATA:onFI="2018-06-15 17:15:12.882"
2_S2","m_CardNum":"0"}]}]}"
media-uf9209nzx_40.ts
#EXTINF:1.003,
#X-RTMP-1-TIME:onFI="2018-06-15 09:22:47.492"
#X-RTMP-1-DATA:onFI="2018-06-15 17:15:13.881"
media-uf9209nzx_41.ts
Given the above headers, and ignoring the timezone difference between the
encoder and the wowza server, we can estimate the lag by substracting the
most recent onFI payload from the event time (-TIME suffix).
In order to gauge latency with a better precision, the encoder and the Wowza server time must be synchronized. In the above example, they are not, so there is a significant time drift between them, making latency measurements useless.
This information can be plugged into your monitoring system, so you may monitor any latency issues with video playback that might occur between the origin and the wowza server.
Author
The RTMP Metadata plugin is developed by Tit Petrič (c), all rights reserved.
Contact: black@scene-si.org
Product page: scene-si.org