How to add poster frames to Apple HLS streams (ID3-metadata) for on-demand and live audio streams (ModuleCupertinoLiveAttachPicture2/ModuleCupertinoVODAttachPicture)

Note: This article is for an older Wowza™ product or technology that either has been updated or is no longer supported. For the current version of this article, see How to add a poster image to an audio-only iOS stream (CupertinoLiveAttachPicture).
These two modules illustrate how to add poster images to an iOS audio-only live or on-demand (VOD) stream. This is accomplished by adding ID3 metadata to the stream that's interpreted by the iOS player. The modules will search for an image file in the Wowza media server's [install-dir]/content folder that has the file name [stream-name].[extension], where [extension] can be jpg, jpeg, or png. For example, if you use the stream name myStream to stream and add the file myStream.jpg, which is the desired poster frame in JPG format, then the module will use this image as the poster frame.
  • This version of the live module (ModuleCupertinoLiveAttachPicture2) only works with stand-alone audio-only live streams. If you're using the audio-only rendition with the Apple App Store compliance technique, use the ModuleCupertinoLiveAttachPicture module.
  • The poster frame is only displayed for audio-only streams. For video streams, the poster frames aren't displayed.
  • When streaming MP3 files (audio on demand), embedded poster frames are propagated automatically to iOS streams.
  • If you use the API, a much broader set of ID3 metadata is supported than what's in these example modules. For more details, refer to the package in the Wowza Streaming Engine server-side API.
  • Support for poster frames was dropped by Apple in iOS 8.0 and as a result, adding poster frames will only work on iOS versions prior to iOS 8.0.
A compiled version of both of these modules is included in the Wowza Module Collection.


To enable either module, add one of the following module definitions to your application, depending on whether it's a video on demand or live application. See Configure modules for details.

Video On Demand

Fully Qualified Class Name
ModuleCupertinoVODAttachPicture Adds poster image to VOD iOS stream. com.wowza.wms.plugin.collection.module.ModuleCupertinoVODAttachPicture


Fully Qualified Class Name
ModuleCupertinoLiveAttachPicture2 Adds poster image to live iOS stream. com.wowza.wms.plugin.collection.module.ModuleCupertinoLiveAttachPicture2


After enabling the module, you can adjust the default logging setting by adding the following property to your application. See Configure properties for details.
Root/Application cupertinoAttachPictureDebugLog Boolean true Extra debug logging (default: false).

Wowza media server software and all components, including modules, source code, and other related items offered on this page, are copyrighted (c) 2006-2016 by Wowza Media Systems, LLC, all rights reserved, and are licensed pursuant to the Wowza Media Software End User License Agreement.
Originally Published: 10-29-2012.