source: plugins/livestream/js/doc/guides/overview.rst @ 1621

.. _overview:

Introduction
============

**The livestream plugin is a fairly straightforward tool aimed at offering a smoother user experience around live events. It sits on top of the player, displaying state messages to the user.**

Messages
--------

The plugin displays a message if playback is in any of the following states:

* The live event hasn't started yet (the plugin displays a **countdown** message).
* The live event was interrupted (the plugin displays a **reconnecting** message).
* The live event has ended (the plugin displays an **event ended** message).

Here is an image containing an example of each state:

.. image:: ../assets/states.png
   :alt: The three available messages in this plugin

Reconnecting
------------

The interruption of a live event is automatically detected by the plugin. This includes the following scenarios:

* The upload application (e.g. `FMLE <http://www.adobe.com/products/flashmediaserver/flashmediaencoder/>`_) is gracefully stopped.
* The upload application (e.g. `FMLE <http://www.adobe.com/products/flashmediaserver/flashmediaencoder/>`_) is crashed.
* The streaming server (e.g. `Wowza <http://www.wowzamedia.com/>`_) is gracefully stopped.
* The streaming server (e.g. `Wowza <http://www.wowzamedia.com/>`_) is crashed.
* The internet connection from the client is lost.

If playback is interrupted and the current time is still before the event ending, the **reconnecting** message is displayed. The plugin attempts to reconnect to the server every ten seconds, until a connection is established again.

If playback is interrupted and the current time is beyond the event ending, the plugin displays the **event ended** message.

Compatibility
-------------

This plugin is written in JavaScript and therefore compatible with JW Player 5.5+ and HTML5. Only the `JW Embedder method <http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/15995/jw-embedder-reference-guide>`_ can be used for embedding this plugin; SWFObject and embed/object are not supported.

The plugin is specifically tested with `Flash Media Server <http://www.adobe.com/products/flashmediaserver/>`_ and `Wowza Media Server <http://www.wowzamedia.com/>`_. With the latter, simultaneous live streaming to Flash + iOS (iPad/iPhone) is supported (see below).



Configuration
=============

The livestream plugin has three configuration options:

.. describe:: start

   Start date and time of the live event, as a unix timestamp. Since a timestamp is inserted, the plugin will be timezone-agnostic. `Visit this page <http://www.timestampgenerator.com/>`_ to quickly generate a timestamp for a certain date.
   
   The plugin will compare the current time with the start date. If the start date hasn't arrived, the plugin will show a countdown timer. If the start date has arrived, the live stream immediately starts.
   
   The default *start* is **0** (the plugin assumes the event has started).

.. describe:: end

   End date and time of the live event, as a unix timestamp. Since a timestamp is inserted, the plugin will be timezone-agnostic. `Visit this page <http://www.timestampgenerator.com/>`_ to quickly generate a timestamp for a certain date.
   
   The plugin will compare the current time with the end date. If the end date already passed, the plugin will show an *event ended* message. If the end date hasn't arrived, the live stream immediately starts.
   
   The default *end* is **9999999999** (the plugin assumes the event will last forever).

.. describe:: title

   The event title the plugin displays in its messaging window. Any title is accepted, but do note the length of the title is restricted to whatever fits on one line. Whichever title looks best will depend upon the combination of title length and player width. We recommend a player width between 400 and 800 pixels.
   
   The default *title* is **Live event**.

Example
-------

Here is an example page with a basic configuration of the livestream plugin. This example presumes you host the plugin (*livestream.js*) yourself:

.. code-block:: html

    <html>
    <head>
        <script type="text/javascript" src="assets/jwplayer.js"></script>
    </head>
    <body>
        <div id='player'>You need Flash to play this stream</div>
        <script type='text/javascript'>
            jwplayer("player").setup({
                file:'livestream',
                height: 270,
                flashplayer: '/assets/player.swf',
                plugins: {
                    '/assets/livestream.js': {
                        end: 1299081600,
                        start: 1299078000,
                        title: 'Swimming Championships 2011, Finals'
                    }
                },
                streamer: 'rtmp://example.com/live',
                width: 480
            });
        </script>
    </body>
    </html>



Streaming to iOS
================

When using the `Wowza Media Server <http://www.wowzamedia.com/>`_ for streaming, it is possible to make your event available to both Flash and iOS at the same time. 

The livestream plugin will display the **countdown** and **event ended** messages on iOS (tested on iPad). Unfortunately, automated reconnection is not possible, because:

* iOS doesn't send out an event on stream interruptions.
* iOS doesn't allow the *play()* API call. 

Users have to reconnect themselves by pressing the play icon that appears over the video when a stream disconnects.

Ingestion
---------

For ingestion, it's important to use the right encoding settings:

* iOS **requires** H264 video and AAC audio. 
* For compatibility with the iPhone 3G(s), make sure your video is Baseline, max level 3.1. 

Here's a screenshot with recommended settings. Dial back the resolution and bitrate (e.g. to 480x272px, 400kbps) if your outbound connection is having trouble sending the stream:

.. image:: ../assets/fmle.png
   :alt: Recommended FMLE settings for streaming to iOS.

Streaming
---------

A default setup of the Wowza Media Server 2 is correctly configured to do RTMP + iOS streaming. Please refer to the `QuickStart Guide <http://www.wowzamedia.com/forums/content.php?217>`_ for more details.

If you don't own a Wowza Media Server (or server for that matter), take a look at our `blog post on Wowza EC2 <http://www.longtailvideo.com/support/blog/17376/live-streaming-using-wowza-ec2>`_. It explains how to run a Wowza server by the hour off Amazon's EC2 service.

Embedding
---------

On the embedding side, one change needs to be made to the basic example shown above. Instead of setting the RTMP file/streamer as a global option, they should be made unique to the player's **flash** mode. Next, the iOS compatible stream (always under *STREAMNAME/playlist.m3u8*) needs to get set for the **html5** mode:

.. code-block:: html

    <html>
    <head>
        <script type="text/javascript" src="/assets/jwplayer.js"></script>
    </head>
    <body>
        <div id="player">You need Flash or iOS to play this stream</div>
        <script type="text/javascript">
            jwplayer("player").setup({
                height: 270,
                players: [{ 
                    config: {
                        file:'livestream',
                        streamer:'rtmp://example.com/live'
                    },
                    type: 'flash',
                    src: '/assets/player.swf'
                },{ 
                    config: {
                        file: 'http://example.com:1935/live/teststream/playlist.m3u8'
                    },
                    type: 'html5'
                }],
                plugins: {
                    '/assets/livestream.js': {
                        end: 1299081600,
                        start: 1299078000,
                        title: 'Swimming Championships 2011, Finals'
                    }
                },
                width: 480
            });
        </script>
    </body>
    </html>

This configuration will playback the RTMP stream for any browser that supports Flash (desktops/Android) and the M3U8 stream for any iOS browser (iPad/iPhone). On other browsers, the fallback message in the <div> (*you need Flash or iOS*) stays untouched.