Documentation

Description

Flussonic is a third version of streaming server Erlyvideo that allows you to stream video and audio in the internet to Flash player, iPad, Android and Set-Top-Boxes.

Flussonic is distributed in two flavors: GPL version with basic features described below and commercial version.

Basic features

  • Support of following formats and codecs: MP4, FLV, H264, AAC, VP6, RTSP/RTP/RTCP, MPEG-TS, HDS, HLS.
  • Streaming local files (mp4/flv) via RTMP/HDS/HLS. Flussonic has unique feature: it can stream FLV (h264) files via HLS.
  • Take MPEG-TS stream from VLC or satellite.
  • Take RTSP video from surveillance cameras.

Additional commercial features

  • Additional support of HLS.
  • Streaming local files HLS. Flussonic has unique feature: it can stream FLV (h264) files via HLS.
  • Streaming files located on remote HTTP server.
  • Recording streams into endless archives with instant cleanup of old files, extracting content to mp4 files, etc.

Request trial license right now

Difference between erlyvideo 2 and flussonic

Erlyvideo 2 was an RTMP server. RTMP is an abandoned protocol with major design problems, used only by Flash Player. It is not developed anymore.

Flussonic is a superior server: it is built with HTTP streaming in mind.

HTTP streaming is an approach for video distribution, when video is split into chunks that are downloaded as separate small files. These chunks can be cached by intermediate cache servers like Varnish and thus you can easily distribute load between servers.

So the main difference is that Flussonic is primarily HDS/HLS server and only if you require RTMP, you should use this obsolete protocol.

Internal structure

Flussonic can serve files and streams. Files are static and are located on disk, streams are frame flows. Video stream is a very complicated thing, because it may be originated by flussonic (server goes to some source), by user (user publishes some stream via flash or Adobe FMLE), be static (like UDP multicast stream).

Flussonic has concept of static streams and ondemand streams. Static streams should live forever. It is right the case, if you use flussonic as a camera repeater or for needs of IPTV restreaming. Ondemand streams are used for cases, when you don't want your source to be connected forever.

Configuration

Flussonic is a good piece of software that doesn't require you to edit many megabytes of XML to launch simple example. You can launch it without any configuration.

It is possible to edit following things: ports for different protocols, limit access to admin interface, setup file access and edit live streams. Further goes more detailed description of config file and options.

Config file of your flussonic installation is in /etc/flussonic/flussonic.conf or /opt/flussonic/pric/flussonic.conf file. It is a valid erlang config file, so note that every section must end with a dot: {http_port, 8080}. and comma should separate entries in a list: {options, [{key1,value1},{key2,value2},{key3,value3}]}.

Full list of top-level config options

  • {rtmp, 1935}. — RTMP port
  • {http, 8080}. — HTTP port
  • {file, "vod", "/var/movies"}. — HTTP prefix and folder where to serve static files from. To stream file /var/movies/bunny.mp4 you should use url http://localhost:8080/vod/bunny.mp4/manifest.f4m for HDS and http://localhost:8080/vod/bunny.mp4/index.m3u8 for HLS.
  • {live, "live", [{dvr,"livestreams"}]}. or {live, "live"}. —HTTP prefix and RTMP application where to publish user streams and receive them via HDS or RTMP. You can also specify stream options like dvr, described below.
  • {api, [{admin,"admin","pass0"}]}. — options for API. Supported option is admin with login and password for HTTP protection of destructive API calls
  • {stream, Stream, URL, Options}. — static stream. Flussonic will keep it connected.
  • {rewrite, Stream, URL, Options}. — ondemand stream
  • {root, "wwwroot"}. — where to serve static files from. Usually it is wwwroot, change only if you want to completely disable admin panel.
  • {password_publish, "user:password"}. — if you wish to protect RTMP publishing from unauthorized access, edit password here.

Stream options

  • {dvr, Root} — root of dvr storage, where flussonic should write archive of your stream. {stream, "cam0", "rtsp://cam/h264", [{dvr,"/storage"}]} will write files in /storage/cam0
  • {dvr_limit, 20160} — Limit of recorded files in minutes. 20160 is for two weeks. Usual 2 mbit camera produce about 20 GB of video per day, so two weeks are about 300 GB.
  • {retry_limit, 100} — how many retries to request source. After this retry limit non-static stream will fail.
  • {source_timeout, 30000} — how many milliseconds to wait frames from source. If source doesn't send frames for this limit, stream will fail.
  • {clients_timeout, 30000} — how many milliseconds to wait after last request of client.
  • {udp, "udp://239.1.1.4:5001"} — restream this stream to UDP. Multicast is possible
  • {tracks, [1]} — use this option to limit RTSP source to video only. It is required if your camera is sending non-AAC sound.
  • {sessions, "http://authenticationhost/auth.php"} — enable sessions on this stream and forward auth requests on this HTTP url. See below description.

Usage

Start, stop

/etc/init.d/flussonic stop|start|restart for common tasks

curl -u admin:pass0 http://localhost:8080/erlyvideo/api/reload for reconfiguring flussonic.

HTTP API

http://localhost:8080/erlyvideo/api/reload reconfiguring flussonic

http://localhost:8080/erlyvideo/api/streams JSON list of streams with their stats

http://localhost:8080/erlyvideo/api/stream_health/[STREAM_NAME] 200 OK is stream delay is normal.

http://localhost:8080/cam0/manifest.f4m HDS manifest url for viewing cam0 stream

http://localhost:8080/cam0/index.m3u8 HLS manifest url for viewing cam0 stream

http://localhost:8080/cam0/archive/1346601960/840/manifest.f4m HDS manifest url for viewing cam0 archive from unix timestamp 1346601960 during 840 seconds

http://localhost:8080/cam0/archive/1346601960/840/index.m3u8 HLS manifest url for viewing cam0 archive from unix timestamp 1346601960 during 840 seconds

http://localhost:8080/cam0/archive-1346601960-840.mp4 Export cam0 archive from unix timestamp 1346601960 during 840 seconds within mp4 container.

HTML examples

To embed flash player for viewing stream use following snippet of code: 

		
		<object width="640" height="480" type="application/x-shockwave-flash" data="/flu/StrobeMediaPlayback.swf">
			<param name="allowScriptAccess" value="always">
			<param name="allowFullScreen" value="true">
			<param name="allowNetworking" value="all">
			<param name="flashvars" value="src=http://localhost:8080/cam0/manifest.f4m?session=1346609403970&autoPlay=true">
		</object>
To embed HTML5 tag video on iPhone use following: 

		<video src="http://localhost:8080/cam0/index.m3u8?session=1346609403970" controls autoplay></video>

Recommended flash players

The most recommended flash player is OSMF based StrobeMediaPlayback. Use any player based on OSMF.

Logs

/var/log/flussonic is used for autorotated log files.

Sessions and authorization

To discuss authorization and sessions issue first should be mentioned, that flussonic primarily is a HTTP server. There is no single TCP connection for a continuos stream access. This is why flussonic uses HTTP sessions just like Rails, PHP or any other web framework to track users.

Second very important thing to understand is that chunks of video are distributed without protection. It is required because intermediate HTTP cache server doesn't know anything about our http sessions. Only meta information is transferred with protection.

Now let's explain process of session handling in flussonic.

  1. web site that embeds Flash or HLS video tag generates session token. Contents of this session token may be anything. For example it may be: sha1(streamname + user_id + user_ip + secret_code).
  2. session token is used a session=SESSION_TOKEN in query string when embedding flash.
  3. when user comes to a stream protected by sessions option, flussonic looks if this session token is already known. If it is unknown, than http request is made to url, specified in option with following params: url, token, ip
  4. If backend replies with some non-200 response, negative reply is remembered for 2 minutes
  5. If backend replies with 200, client is granted access for some time.
  6. Backend can also implement rewrite with header X-Name and specify time for token lifetime: X-AuthDuration
So you should not try to write any server-side logic on cryptic language, just use your website to reply on auth requests from flussonic.

Problems

Large delay of video
It is nature of HTTP streaming. Player needs to buffer big amount of video to seamlessly survive network problems.