• How to add a poster image to an audio-only iOS stream (CupertinoLiveAttachPicture)

    The ModuleCupertinoLiveAttachPicture module for Wowza Streaming Engine™ media server software can be used to add a poster image to audio-only iOS streams. Poster images can be added to audio-only streams that are produced to comply with Apple App Store rules for 3G delivery as well as to live and on-demand streams that don't comply with the Apple App Store rules.

    • Support for poster images was dropped by Apple in iOS 8.0 and as a result, adding poster images only works on iOS versions prior to iOS 8.0.

    • When streaming MP3 files (audio on demand), embedded poster images are automatically propagated to iOS streams.


    For developers


    Wowza Streaming Engine 4.0.0 or later is required.


    1. Download wse-plugin-cupertinoliveattachpicture.zip.

    2. Extract the contents from the downloaded (zipped) package, and then copy the lib/wse-plugin-cupertinoliveattachpicture.jar file from the package to the lib folder in your Wowza Streaming Engine installation ([install-dir]/lib).

    3. Restart Wowza Streaming Engine.


    To enable this module, add one or more of the following module definitions to your application configuration. See Configure modules for details.

    Fully Qualified Class Name
    CupertinoLiveAttachPicture Adds a poster image to a live, audio-only iOS stream produced to comply with the App Store rules for 3G delivery. com.wowza.wms.plugin.CupertinoLiveAttachPicture
    CupertinoLiveAttachPicture2 Adds a poster image to a live, audio-only iOS stream that doesn't comply with the App Store rules. com.wowza.wms.plugin.CupertinoLiveAttachPicture2
    CupertinoVODAttachPicture Adds a poster image to an on-demand, audio-only iOS stream that doesn't comply with the App Store rules. com.wowza.wms.plugin.CupertinoVODAttachPicture


    After enabling the module(s), you can adjust the default settings by adding the following property to your application. See Configure properties for details.

    /Root/Application cupertinoAttachPictureDebugLog Boolean true Extra debug logging. (default: false)


    There are three ways you can add a poster image to an iOS audio-only stream by using the CupertinoLiveAttachPicture module. To add a poster image to an audio-only iOS stream, use:

    • CupertinoLiveAttachPicture - For live streams that are produced using the audio-only rendition of the App Store compliance technique.

    • CupertinoLiveAttachPicture2 - For live, audio-only streams that don't use the App Store compliance technique.

    • CupertinoVODAttachPicture - For on-demand, audio-only streams that don't use the App Store compliance technique.

    Poster images are added through the addition of ID3 metadata to the stream that's interpreted by the iOS player. The module searches for an image file in the Wowza media server's [install-dir]/content folder with the name [stream-name].[extension], where [extension] can be jpg, jpeg, or png. For example, if your stream is named myStream and your image is in the JPG format, your poster image file must be named myStream.jpg for the module to use it as the poster image.

    Note: You can use the Wowza Streaming Engine server-side API to include a broader set of ID3 metadata in your stream. For details see the com.wowza.wms.media.mp3.model.idtags package in the Wowza Streaming Engine Server-Side API User Guide (PDF).
    For streams that comply with the App Store, you can test by using the following playback URL. Note that the ?wowzaaudioonly querystring at the end of the URL is required.

    For Developers

    Source code is available on GitHub.

    Wowza Media Systems™ provides developers with a platform to create streaming applications and solutions. See Wowza Developer Tools to learn more about our APIs and SDK.
    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: on 11-22-2010.
    Updated: 09-28-2016.

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