Warning: HTML preview using PygmentsRenderer failed (TypeError: function() takes at least 2 arguments (0 given))

source: trunk/fl5/doc/publishers/rtmpstreaming.rst @ 1280

Revision 1280, 20.2 KB checked in by jeroen, 4 years ago (diff)

fixed a bug in RTMPT error handling. Fixed a bug in HTTP continuous bitrate switching. Fixed a bug for playlist PNG rollovers without itemActive element. Added logic for hiding the image/description of playlist buttons when the button is <40px high or <240px wide. Added RST documentation on HTTP _droppedframes, HTTP DVR, RTMP DVRCast, RTMP _droppedframes, RTMP Tunneling and small playlist button element hiding.

Line 
1.. _rtmpstreaming:
2
3RTMP Streaming
4==============
5
6RTMP (Real Time Messaging Protocol) is a system for delivering on-demand and live media to Adobe Flash applications (like the JW Player). RTMP supports video in FLV and H.264 (MP4/MOV/F4V) :ref:`formats <mediaformats>` and audio in  MP3 and AAC (M4A) :ref:`formats  <mediaformats>`. RTMP offers several advantages over regular HTTP video downloads:
7
8* RTMP can do live streaming - people can watch your video while it is being recorded.
9* With RTMP, viewers can seek to not-yet-downloaded parts of a video. This is especially useful for longer-form content (> 10 minutes).
10* Videos delivered over RTMP (and its encrypted brother, RTMPE) are harder to steal than videos delivered over regular HTTP.
11
12However, do note that RTMP has its disadvantages too. Especially since the introduction of :ref:`httpstreaming` (used by e.g. Youtube), RTMP is not the only option for efficient video delivery. Some drawbacks to be aware of:
13
14* RTMP is a different protocol than HTTP and is sent over a different port (1935 instead of 80). Therefore, RTMP is frequently blocked by (corporate) firewalls. The JW Player :ref:`detects and circumvents this issue <rtmpt>`.
15* RTMP is a *true* streaming protocol, which means that the bandwidth of the connection must always be larger than the datarate of the video. If the connection drops for a couple of seconds, the stream will stutter. If the connection bandwidth overall is smaller than the video datarate, the video will not play at all.
16
17The JW Player supports a wide array of features of the RTMP protocol, listed below.
18
19
20Servers
21-------
22
23In order to use RTMP, your webhoster or CDN needs to have a dedicated RTMP webserver installed. There are three major offerings, all supported by the JW Player:
24
25* The `Flash Media Server <http://www.adobe.com/products/flashmediaserver/>`_ from Adobe is the de facto standard. Since Flash is also developed by Adobe, new video functionalities always find their way in FMS first.
26* The `Wowza Media Server <http://www.wowzamedia.com>`_ from Wowza is a great alternative, because it includes support for other streaming protocols than RTMP (for e.g. Shoutcast, the iPad/iPhone or Silverlight).
27* The `Red5 Media Server <http://red5.org/>`_ is an open-source RTMP alternative. It lags in features (e.g. no dynamic streaming), but is completely free.
28
29RTMP servers are not solely used for one-to-many media streaming. They include support for such functionalities as video conferencing, document sharing and multiplayer games. Each of these functionalities is separately set up on the server in what is called an *application*. Every application has its own URL (typically a subfolder of the root). For example, these might be the path to both an on-demand streaming and live streaming application on your webserver:
30
31.. code-block:: html
32
33   rtmp://www.myserver.com/ondemand/
34   rtmp://www.myserver.com/live/
35
36The JW Player solely supports the basic live, on-demand and dvr streaming applications. There's no support for such things as webcasting, videochat or screen sharing.
37
38
39Options
40-------
41
42To play an RTMP stream in the player, both the *streamer* and *file* :ref:`options <options>` must be set. The *streamer* is set to the server + path of your RTMP application. The *file* is set to the internal URL of video or audio file you want to stream. Here is an example :ref:`embed code <embedding>`:
43
44.. code-block:: html
45
46   <div id='container'>The player will be placed here</div>
47
48   <script type="text/javascript">
49     var flashvars = {
50       file:'library/clip.mp4',
51       streamer:'rtmp://www.myserver.com/ondemand/'
52     };
53
54     swfobject.embedSWF('player.swf','container','480','270','9.0.115','false', flashvars,
55      {allowfullscreen:'true',allowscriptaccess:'always'},
56      {id:'jwplayer',name:'jwplayer'}
57     );
58   </script>
59
60
61Note that the documentation of RTMP servers tell you to set the *file* option in players like this:
62
63* For FLV video: **file=clip** (without the *.flv* extension).
64* For MP4 video: **file=mp4:clip.mp4** (with *mp4:* prefix).
65* For MP3 audio: **file=mp3:song.mp3** (with *mp3:* prefix).
66* For AAC audio: **file=mp4:song.aac** (with *mp4:* prefix).
67
68You do not have to do this with the JW Player, since the player takes care of stripping the extension and/or adding the prefix. If you do add the prefix yourself, the player will recognize it and not modify the URL.
69
70Additionally, the player will leave querystring variables (e.g. for certain CDN security mechanisms) untouched. It basically ignores everything after the **?** character. However, because of the way options are :ref:`loaded <options>` into Flash, it is not possible to plainly use querystring delimiters (*?*, *=*, *&*) inside the *file* or *streamer* option. This issue can be circumvented by :ref:`URL encoding these characters <options>`.
71
72.. note::
73
74   Amazon Cloudfront's private streaming protocol is an example in which the MP4 URL should be URL Encoded, since the long security hash appended to the video URL can contain special characters.
75
76
77Playlists
78---------
79
80RTMP streams can also be included in playlists, by leveraging the :ref:`JWPlayer namespace <playlistformats>`. The *streamer*  option should be set for every RTMP entry in a playlist. You don't have to set them in the embed code (just point the *file* option to your playlist).
81
82Here's an example, an RSS feed with an RTMP video and audio clip:
83
84.. code-block:: xml
85
86   <rss version="2.0" xmlns:jwplayer="http://developer.longtailvideo.com/">
87     <channel>
88       <title>Playlist with RTMP streams</title>
89   
90       <item>
91         <title>Big Buck Bunny</title>
92         <description>Big Buck Bunny is a short animated film by the Blender Institute,
93            part of the Blender Foundation.</description>
94         <enclosure url="files/bbb.mp4" type="video/mp4" length="3192846" />
95         <jwplayer:streamer>rtmp://myserver.com/ondemand</jwplayer:streamer>
96       </item>
97   
98       <item>
99         <title>Big Buck Bunny (podcast)</title>
100         <description>Big Buck Bunny is a short animated film by the Blender Institute,
101            part of the Blender Foundation.</description>
102         <enclosure url="files/bbb.mp3" type="audio/mp3" length="3192846" />
103         <jwplayer:streamer>rtmp://myserver.com/ondemand</jwplayer:streamer>
104       </item>
105   
106     </channel>
107   </rss>
108
109Instead of the *enclosure* element, you can also use the *media:content* or *jwplayer:file* element. You could even set the *enclosure* to a regular http download of the video ánd *jwplayer:file* to the RTMP stream. That way, this single feed is useful for both regular RSS readers and the JW Player. More info in :ref:`playlistformats`.
110
111.. note::
112
113   Do not forget the **xmlns** at the top of the feed. It is needed by the player (and any other feed reader you might use) to understand the *jwplayer:* elements.
114
115
116Live Streaming
117--------------
118
119A unique feature of RTMP is the ability to do live streaming, e.g. of presentations, concerts or sports events. Next to the player and an RTMP server, one then also needs a small tool to *ingest* (upload) the live video into the server. There's a bunch of such tools available, but the easiest to use is the (free) `Flash Live Media Encoder <http://www.adobe.com/products/flashmediaserver/flashmediaencoder/>`_. It is available for Windows and Mac.
120
121A live stream can be embedded in the player using the same options as an on-demand stream. The only difference is that a live stream has no file extension. Example:
122
123.. code-block:: html
124
125   <div id='container'>The player will be placed here</div>
126
127   <script type="text/javascript">
128     var flashvars = {
129       file:'livepresentation',
130       streamer:'rtmp://www.myserver.com/live/'
131     };
132
133     swfobject.embedSWF('player.swf','container','480','270','9.0.115','false', flashvars,
134      {allowfullscreen:'true',allowscriptaccess:'always'},
135      {id:'jwplayer',name:'jwplayer'}
136     );
137   </script>
138
139
140Subscribing
141^^^^^^^^^^^
142
143When streaming live streams using the Akamai, Edgecast or Limelight CDN, players cannot simply connect to the live stream. Instead, they have to *subscribe* to it, by sending an **FCSubscribe call** to the server. The JW Player includes support for this functionality. Simply add the *rtmp.subscribe=true* option to your embed code to enable:
144
145.. code-block:: html
146
147   <div id='container'>The player will be placed here</div>
148
149   <script type="text/javascript">
150     var flashvars = {
151       file:'livepresentation',
152       streamer:'rtmp://www.myserver.com/live/',
153       'rtmp.subscribe':'true'
154     };
155
156     swfobject.embedSWF('player.swf','container','480','270','9.0.115','false', flashvars,
157      {allowfullscreen:'true',allowscriptaccess:'always'},
158      {id:'jwplayer',name:'jwplayer'}
159     );
160   </script>
161
162
163DVR Live Streaming
164^^^^^^^^^^^^^^^^^^
165
166Flash Media Server 3.5 introduced live DVR streaming - the ability to pause and seek in a live stream. A DVR stream acts like a regular on-demand stream, the only difference being that the *duration* of the stream keeps increasing (that is, when the stream is still recording).
167
168Instead of starting from the beginning, the player will automatically jump to the *live* head of the DVR stream, so users can jump right into a live event. Subsequently, they are able to seek back to the beginning.
169
170In order to enable DVR streaming you should:
171
172* Install the **DVRCast** application (which is provided for free by Adobe) onto your FMS3.5 server. Certain Content Delivery Networks (like `Edgecast <http://edgecast.com/>`_) have this application already installed for you.
173* Use a live stream publishing tool (such as Adobe's Flash Media Live Encoder 3.1) that can issue DVR recording commands to an RTMP server.
174* Set the option **rtmp.dvr=true**. to your JW Player. This option switches the player in **DVRCast** mode, attempting to DVR subscribe to the stream and increasing the duration of the stream if recording is still in progress.
175
176Here is an example embed code, with the *rtmp.dvr* option set:
177
178.. code-block:: html
179
180   <div id='container'>The player will be placed here</div>
181
182   <script type="text/javascript">
183     var flashvars = {
184       file:'livepresentation',
185       streamer:'rtmp://www.myserver.com/live/',
186       'rtmp.dvr':'true'
187     };
188
189     swfobject.embedSWF('player.swf','container','480','270','9.0.115','false', flashvars,
190      {allowfullscreen:'true',allowscriptaccess:'always'},
191      {id:'jwplayer',name:'jwplayer'}
192     );
193   </script>
194
195
196Dynamic Streaming
197-----------------
198
199Like :ref:`httpstreaming`, RTMP Streaming includes the ability to dynamically optimize the video quality for each individual viewer. Adobe calls this mechanism *dynamic streaming*. This functionality is supported for FMS 3.5+ and Wowza 2.0+.
200
201To use dynamic streaming, you need multiple copies of your MP4 or FLV video, each with a different quality (dimensions and bitrate). These multiple videos are loaded into the player using an mRSS playlist (see example right below) or SMIL file (see :ref:`loadbalancing`) The player recognizes the various *levels* of your video and automatically selects the highest quality one that:
202
203* Fits the *bandwidth* of the server » client connection.
204* Fits the *width* of the player's display (or, to be precise, is not more than 20% larger).
205* Results in less than 25% *frames dropped* at any point in time (e.g. 7fps for a video that is 25fps).
206
207As a viewer continues to watch the video, the player re-examines its decision (and might switch) in response to certain events:
208
209* On a **bandwidth** increase or decrease - the bandwidth is re-calculated at an interval of 2 seconds.
210* On a **resize** of the player. For example, when a viewer goes fullscreen and has sufficient bandwidth, the player might serve an HD version of the video.
211* On a **framedrop** of more than about 7 or 8 fps.
212
213Framedrop is continously monitored. Spikes are ruled out by taking 5-second averages. Once a quality level results in too large a framedrop, it will be *blacklisted* (made unavailable) for 30 seconds. After 30 seconds, it will be made available again, since the framedrop might be a result of a very decoding-heavy section in the video or external forces (e.g. the user opening Microsoft Office ;).
214
215Unlike with :ref:`httpstreaming`, a dynamic streaming switch is unobtrusive. There'll be no re-buffering or audible/visible hickup. It does take a few seconds for a switch to occur in response to a bandwidth change / player resize, since the server has to wait for a *keyframe* to do a smooth switch and the player always has a few seconds of the old stream in its buffer. To keep stream switches fast, make sure your videos are encoded with a small (2 to 4 seconds) keyframe interval.
216
217.. note::
218
219   So far, we have not been able to combine dynamic streaming with live streaming. This functionality is highlighted in  documentation from FMS, but in our tests we found that the bandwidth the player receives never exceeds the bandwidth of the level that currently plays. In other words: the player will never switch to a higher quality stream than the one it starts with.
220
221
222Example
223^^^^^^^
224
225Here is an example dynamic streaming playlist (only one item). It is similar to a regular RTMP Streaming playlist, with the exception of the multiple video elements per item. The mRSS extension is the only way to provide these multiple elements including *bitrate* and *width* attributes:
226
227.. code-block:: xml
228
229   <rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/"
230     xmlns:jwplayer="http://developer.longtailvideo.com/">
231     <channel>
232       <title>Playlist with RTMP Dynamic Streaming</title>
233   
234       <item>
235         <title>Big Buck Bunny</title>
236         <description>Big Buck Bunny is a short animated film by the Blender Institute,
237            part of the Blender Foundation.</description>
238         <media:group>
239           <media:content bitrate="1800" url="videos/Qvxp3Jnv-486.mp4"  width="1280" />
240           <media:content bitrate="1100" url="videos/Qvxp3Jnv-485.mp4" width="720"/>
241           <media:content bitrate="700" url="videos/Qvxp3Jnv-484.mp4" width="480" />
242           <media:content bitrate="400" url="videos/Qvxp3Jnv-483.mp4" width="320" />
243         </media:group>
244         <jwplayer:streamer>rtmp://www.myserver.com/ondemand/</jwplayer:streamer>
245       </item>
246   
247     </channel>
248   </rss>
249
250Some hints:
251
252* The *bitrate* attributes must be in kbps, as defined by the `mRSS spec <http://video.search.yahoo.com/mrss>`_. The *width* attribute is in pixels.
253* It is recommended to order the streams by quality, the best one at the beginning.
254* The four levels displayed in this feed are actually what we recommend for bitrate switching of widescreen MP4 videos. For 4:3 videos or FLV videos, you might want to increase the bitrates or decrease the dimensions a little.
255* Some publishers only modify the bitrate when encoding multiple levels. The player can work with this, but modifying both the bitrate + dimensions allows for more variation between the levels (and re-use of videos, e.g. the smallest one for streaming to mobile phones).
256* The *media:group* element here is optional, but it organizes the video links a little.
257
258
259.. _loadbalancing:
260
261Load Balancing
262--------------
263
264For high-volume publishers who maintain several RTMP servers, the player supports load-balancing by means of an intermediate XML file. This is used by e.g. the `Highwinds <http://www.highwinds.com/>`_ and `Streamzilla <http://www.streamzilla.eu>`_  CDNs. Load balancing works like this:
265
266* The player first requests the XML file (typically from a single *master* server).
267* The server returns the XML file, which includes the location of the RTMP server to use (typically the server that's least busy) and the location of the videos on this server.
268* The player parses the XML file, connects to the server and starts the stream.
269
270
271Example
272^^^^^^^
273
274Here's an example of such an XML file. It is in the SMIL format:
275
276.. code-block:: html
277
278   <smil>
279     <head>
280       <meta base="rtmp://server1234.mycdn.com/ondemand/" />
281     </head>
282     <body>
283       <video src="library/myVideo.mp4" />
284     </body>
285   </smil>
286
287Here's an example embed code for enabling this functionality in the player. Note the *provider=rtmp* :ref:`option <options>` is needed in addition to *rtmp.loadbalance*, since otherwise the player thinks the XML file is a playlist.
288
289.. code-block:: html
290
291   <div id='container'>The player will be placed here</div>
292
293   <script type="text/javascript">
294     var flashvars = {
295       file:'http://www.mycdn.com/videos/myVideo.mp4.xml',
296       provider:'rtmp',
297       'rtmp.loadbalance':'true'
298     };
299
300     swfobject.embedSWF('player.swf','container','480','270','9.0.115','false', flashvars,
301      {allowfullscreen:'true',allowscriptaccess:'always'},
302      {id:'jwplayer',name:'jwplayer'}
303     );
304   </script>
305
306
307Playlists
308^^^^^^^^^
309
310RTMP Load balancing in playlists works in a similar fashion: the *provider=rtmp* and *rtmp.loadbalance=true* options can be set for every entry in the playlist that uses loadbalancing. Here's an example with one item:
311
312.. code-block:: xml
313
314   <rss version="2.0" xmlns:jwplayer="http://developer.longtailvideo.com/">
315     <channel>
316       <title>Playlist with RTMP loadbalancing</title>
317   
318       <item>
319         <title>Big Buck Bunny (podcast)</title>
320         <description>Big Buck Bunny is a short animated film by the Blender Institute,
321            part of the Blender Foundation.</description>
322         <enclosure url="http://www.mycdn.com/videos/bbb.mp3.xml" type="text/xml" length="185" />
323         <jwplayer:provider>rtmp</jwplayer:provider>
324         <jwplayer:rtmp.loadbalance>true</jwplayer:rtmp.loadbalance>
325       </item>
326   
327     </channel>
328   </rss>
329
330See the playlist section above for more information on format and element support.
331
332
333Dynamic Streaming
334^^^^^^^^^^^^^^^^^
335
336The dynamic streaming mechanism of FMS 3.5+ and Wowza 2.0+ can be used in combination with load balancing. Therefore, simply add the different levels of your video to the SMIL file. Here's an example again:
337
338.. code-block:: html
339
340   <smil>
341     <head>
342       <meta base="rtmp://server1234.mycdn.com/ondemand/" />
343     </head>
344     <body>
345       <switch>
346         <video src="videos/Qvxp3Jnv-486.mp4" system-bitrate="1800000" width="1280" />
347         <video src="videos/Qvxp3Jnv-485.mp4" system-bitrate="1100000" width="720"/>
348         <video src="videos/Qvxp3Jnv-484.mp4" system-bitrate="700000" width="480"/>
349         <video src="videos/Qvxp3Jnv-483.mp4" system-bitrate="400000" width="320"/>
350       </switch>
351     </body>
352   </smil>
353
354A couple of hints:
355
356* This file is structured, and behaves exactly the same as the one Adobe uses in its `dynamic streaming documentation <http://www.adobe.com/devnet/flashmediaserver/articles/dynstream_advanced_pt1.html>`_. The *width* attributes of the various bitrate levels are not required (though preferred) by the JW Player.
357* Opposed to a *regular* loadbalancing SMIL document, a dynamic streaming SMIL contains a *<switch>* statement directly inside the <body>* element. Include the closing *</switch>* as well!
358* Opposed to MediaRSS feeds, the bitrate attributes of the various levels are set in *bitspersecond*, **not** in *kilobitspersecond*.
359
360
361
362.. _rtmpt:
363
364RTMPT Fallback
365--------------
366
367A frequent issue with RTMP streaming is the protocol being blocked by corporate firewalls. RTMP uses the UDP transmission protocol over port 1935, whereas regular HTTP traffic uses the TCP protocol over port 80.
368
369All current-day RTMP servers have a way to circumvent this issue, by **tunnelling** the RTMP data in HTTP packets, over TCP and port 80. Performance will degrade - especially the buffer times, which may double - but the video can be pushed through corporate firewalls.
370
371The 5.3 player introduced a mechanism that automatically detects and circumvents firewall issues for RTMP streaming. Here's how it works:
372
373* First, the player connects to the regular application, either RTMP or RTMPe (encrypted).
374* Half a second later, the player connects to the same application over a tunneled connection, either RTMPT or RTMPTe (tunnelled and encrypted).
375* Whichever connection is established first is used for streaming the video.
376
377In most cases the player is connected to the application over RTMP within 500 milliseconds, cancelling the second connection. This functionality is fully automated (no need to set port numbers or rtmp **t** in your *streamer* flashvar) and works for all flavors of RTMP streaming (on-demand, live, dvr and dynamic).
Note: See TracBrowser for help on using the repository browser.