Documentation:Streaming HowTo/Streaming for the iPhone

Note: this functionality is intended to be part of the 1.2 release, so at the time of writing it is only available in nightly builds.

Streaming for the iPhone

This functionality allows you to link VLC's transcoding capability with a segmenter which will in turn create the series of files needed for http live streaming to the iPhone.

Unlike most of VLC's streaming, it doesn't actually stream the files, but assumes that you have your own webserver which will do that job.

Notes from the developer:

• This has only been tested using H.264 w/MP3 or AAC audio using mux=ts, and raw MP3 using mux=raw
• I've been mostly an FFMPEG guy till now, so forgive me if my VLC understanding/terminology is somewhat off.
• This plug-in should support both Live and non-live HTTP Live streaming feeds, depending on the options passed to the module.

Notes from the community:

• The user running vlc needs to have read/write/delete permissions on the directory where the .m3u8 playlist and .ts file segments will be created and deleted on the webserver.

Instructions

The name of the module is livehttp, and is specified by specifying "access=livehttp"

Options

splitanywhere= (default: false)

• Tells livehttp to split the stream anywhere, not just on video keyframes. Currently required to be set to true for audio-only streams and not recommended (probably won't work) for video streams.

seglen= (default: 10)

• How many seconds of audio/video each segment should contain. Apple recommends 10, I have been using 5.

numsegs=(default: 0)

• The number of segments to keep in the index file. The default of 0 keeps all segments in the index (which you would want for non-live streaming). For live streaming the specification require at least 3.

delsegs= (default: true)

• Delete segments as they are no longer needed. If numsegs=0 this parameter is ignored (as all segments are assumed to be needed)

dst=

• This is actually an option to the access std module. The path of the segment files to write. The # characters get replaced with the segment number. So a path of "seg-###.ts" will end up with files called "seg-001.ts, seg-002.ts, seg-003.ts" etc.

index=

• The path of the index file to write, which will contain the "playlist" of video/audio segments to stream. Recommended to end in .m3u8 by specifications. This is the file the <video> tag should be pointed to.

index-url=

• This is the URL that corresponds to the dst above (how a browser would access the dst file). The # characters get replaced same as in the dst parameter. Note: The filename portion of this URL will most likely need to be in the exact same format as the dst parameter. So for example if dst=/www/seg-##.ts then the index-url should be something like index-url=http://mydomain.com/streams/seg-##.ts (Note the same number of # characters)

rate-control=(default: false)

• If set to false the there is no rate control (the muxer sends the data as fast/slow as it can to the streamer). If set to true the muxer should do rate-control to control the speed to muxed audio/video is sent to the streamer. I'm a little unsure what the "best" setting for this parameter is when re-streaming an existing video stream. I've been leaving it at false...

Examples

All examples assume the following:

• The Web Server root directory is /var/www
• The domain name of the web server is mydomain.com
• The stream segments & index files will be written into /var/www/streaming/ and will be accessed via http://mydomain.com/streaming/...
• The destination stream name index file will be called "mystream.m3u8"
• The following HTML will allow you to view the video based on the above on an iPhone:

Re-stream a live video feed:

% vlc -I dummy --mms-caching 0 http://www.nasa.gov/55644main_NASATV_Windows.asx vlc://quit --sout='#transcode{threads=2,width=320,height=240,fps=25,vcodec=h264,vb=256,venc=x264{aud,profile=baseline,level=30,keyint=30,bframes=0,ref=1,nocabac},acodec=mp3,ab=96}:duplicate{dst=std{access=livehttp{seglen=10,delsegs=true,numsegs=5,index=/var/www/streaming/mystream.m3u8,index-url=http://mydomain.com/streaming/mystream-########.ts},mux=ts{use-key-frames},dst=/var/www/streaming/mystream-########.ts}}' 

Create a VOD stream: (Non-live. When this command finishes, all the segments should have been created and the index file contain pointers to all of them)

% vlc -I dummy /var/myvideos/video.mpg vlc://quit --sout='#transcode{threads=2,width=320,height=240,fps=25,vcodec=h264,vb=256,venc=x264{aud,profile=baseline,level=30,keyint=30,bframes=0,ref=1,nocabac},acodec=mp3,ab=96}:duplicate{dst=std{access=livehttp{seglen=10,delsegs=false,numsegs=0,index=/var/www/streaming/mystream.m3u8,index-url=http://mydomain.com/streaming/mystream-########.ts},mux=ts{use-key-frames},dst=/var/www/streaming/mystream-########.ts}}' 

Re-stream a live audio feed:

% vlc -I dummy --mms-caching 0 http://www.nasa.gov/55644main_NASATV_Windows.asx vlc://quit --sout='#transcode{acodec=mp3,ab=96}:duplicate{dst=std{access=livehttp{seglen=10,delsegs=true,numsegs=5,index=/var/www/streaming/mystream.m3u8,index-url=http://mydomain.com/streaming/mystream-########.mp3},mux=raw,dst=/var/www/streaming/mystream-########.mp3},select=novideo}' 

Formats supported by the iOS

See the iPhone article for a list of supported codecs as well as Apple's HTTP Live Streaming FAQ.

Possible improvements/fixes

from the developer:

• Have the module auto-detect audio only streams, so the splitanywhere option is not required.
• I'm not sure I am doing the right thing with the Win32 rename function. Linux (I believe) allows me to rename a file over an existing file, even if the existing file is in use. Win32 is not so friendly. This ability is useful for updating the index file at same time it may be currently being read by the HTTP server serving the files.
• Break the dst= and index= parameter into seperate filename/directory entries, so you only need to specify the filename format once. (instead of once for the dst= parameter, and once for the index-url= parameter)

from the community:

• Have the module detect the codecs used and warn the end user if they are not compatible with the iPhone/iPod Touch/iPad.
• Possible multibitrate implementation that meets the iPhone SDK specs so app developers can use VLC to host streams for their apps.

fixes:

• Audio only streams do not validate with Apple's mediastreamvalidator. Audio streams are missing id3tags and timestamps. Check with command, "mediastreamvalidator validate --timeout=60 [url]"

This page is part of official VLC media player Documentation (User Guide • Streaming HowTo • Hacker Guide • Modules)
Please read the Documentation Editing Guidelines before you edit the documentation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.