MOD move wiki to /docs

README.md

@@ -1,14 +1,29 @@
 # NGINX-based Media Streaming Server
-## nginx-rtmp-module
 
+## nginx-rtmp-module
 
 ### Project blog
 
   http://nginx-rtmp.blogspot.com
 
-### Wiki manual
+### Documentation
 
-  https://github.com/arut/nginx-rtmp-module/wiki/Directives
+* [Home](doc/README.md)
+* [Control module](doc/control_modul.md)
+* [Debug log](doc/debug_log.md)
+* [Directives](doc/directives.md)
+* [Examples](doc/examples.md)
+* [Exec wrapper in bash](doc/exec_wrapper_in_bash.md)
+* [FAQ](doc/faq.md)
+* [Getting number of subscribers](doc/getting_number_of_subscribers.md)
+* [Getting started with nginx rtmp](doc/getting_started.md)
+* [Installing in Gentoo](doc/installing_in_gentoo.md)
+* [Installing on Ubuntu using PPAs](doc/installing_ubuntu_using_ppas.md)
+* [Tutorial](doc/tutorial.md)
+
+*Source: https://github.com/arut/nginx-rtmp-module/wiki*
+
+* [Latest updates](doc/README.md#updates)
 
 ### Google group
 

doc/control_modul.md

@@ -0,0 +1,94 @@
+# Control module
+
+Control module is HTTP module which makes it possible to control rtmp module from outside using HTTP protocol. Here's an example of how to enable control.
+```sh
+http {
+...
+    server {
+        listen       8080;
+        server_name  localhost;
+        ....
+        location /control {
+            rtmp_control all;
+        }
+     }
+}
+```
+
+There are several sub-modules within control module each controlling a different feature.
+
+# Record
+This sub-module starts and stops recordings created with _manual_ flag.
+Syntax:
+```sh
+http://server.com/control/record/start|stop?srv=SRV&app=APP&name=NAME&rec=REC
+```
+
+* srv=SRV - optional server{} block number within rtmp{} block, default to first server{} block
+* app=APP - required application name
+* name=NAME - required stream name
+* rec=REC - optional recorder name, defaults to root (unnamed) recorder
+
+Example
+```sh
+rtmp {
+    server {
+        listen 1935;
+        application myapp {
+            live on;
+            recorder rec1 {
+               record all manual;
+               record_suffix all.flv;
+               record_path /tmp/rec;
+               record_unique on;
+           }
+       }
+    }
+}
+```
+
+Publish the stream with the following command
+```sh
+$ ffmpeg -i http://someserver.com/mychannel.ts -c:v copy -c:a nellymoser -ar 44100 -ac 1 -f flv rtmp://localhost/myapp/mystream
+```
+
+Use the following commands to start and stop recording
+```sh
+$ curl "http://localhost:8080/control/record/start?app=myapp&name=mystream&rec=rec1"
+§ curl "http://localhost:8080/control/record/stop?app=myapp&name=mystream&rec=rec1"
+```
+
+if the record start/stop request returns nothing sometimes, you should check if you use multi workers. one worker works great. 
+
+# Drop
+This sub-module provides a simple way to drop client connection.
+Syntax:
+```sh
+http://server.com/control/drop/publisher|subscriber|client?
+srv=SRV&app=APP&name=NAME&addr=ADDR&clientid=CLIENTID
+```
+
+* srv, app, name - the same as above
+* addr - optional client address (the same as returned by rtmp_stat)
+* clientid - optional nginx client id (displayed in log and stat) 
+
+The first method ```drop/publisher``` drops publisher connection. The second ```drop/client``` drops every connection matching ```addr``` argument or all clients (including publisher) if ```addr``` is not specified.
+
+Examples
+```sh
+$ curl http://localhost:8080/control/drop/publisher?app=myapp&name=mystream
+$ curl http://localhost:8080/control/drop/client?app=myapp&name=mystream
+$ curl http://localhost:8080/control/drop/client?app=myapp&name=mystream&addr=192.168.0.1
+$ curl http://localhost:8080/control/drop/client?app=myapp&name=mystream&clientid=1
+```
+
+# Redirect
+Redirect play/publish client to a new stream.
+Syntax:
+```sh
+http://server.com/control/redirect/publisher|subscriber|client?
+srv=SRV&app=APP&name=NAME&addr=ADDR&clientid=CLIENTID&newname=NEWNAME
+```
+
+* srv, app, name, addr, clients - the same as above
+* newname - new stream name to redirect to

doc/debug_log.md

@@ -0,0 +1,16 @@
+# Debug log
+
+In case you need to solve a streaming problem you might need to watch debug log.
+For that configure nginx with *--with-debug* flag.
+```sh
+$ cd nginx-X.Y.Z
+$ ./configure --add-module=/path/to/nginx-rtmp-module --with-debug ...
+```
+
+After compiling set nginx error.log level to *debug* in nginx.conf
+```sh
+error_log logs/error.log debug;
+```
+
+After that you will have  _a lot_ of debug info in error.log. Please grep
+what your problem relates to (exec, notify etc) and post to [nginx-rtmp google group](https://groups.google.com/group/nginx-rtmp) to help with solving it.

doc/examples.md

@@ -0,0 +1,68 @@
+# Exampled
+
+### Simple Video-on-Demand
+
+```sh
+rtmp {
+    server {
+        listen 1935;
+        application vod {
+            play /var/flvs;
+        }
+    }
+}
+```
+
+### Simple live broadcast service
+```sh
+rtmp {
+    server {
+        listen 1935;
+        application live {
+            live on;
+        }
+    }
+}
+```
+
+### Re-translate remote stream
+```sh
+rtmp {
+    server {
+        listen 1935;
+        application tv {
+            live on;
+            pull rtmp://cdn.example.com:443/programs/main pageUrl=http://www.example.com/index.html name=maintv;
+        }
+    }
+}
+
+### Re-translate remote stream with HLS support
+```sh
+rtmp {
+    server {
+        listen 1935;
+        application tv {
+            live on;
+            hls on;
+            hls_path /tmp/tv2;
+            hls_fragment 15s;
+
+            pull rtmp://tv2.example.com:443/root/new name=tv2;
+        }
+    }
+}
+http {
+    server {
+        listen 80;
+        location /tv2 {
+            alias /tmp/tv2;
+        }
+    }
+}
+```
+
+### Stream your X screen through RTMP
+```sh
+$ ffmpeg -f x11grab -follow_mouse centered -r 25 -s cif -i :0.0 -f flv rtmp://localhost/myapp/screen
+```

doc/exec_wrapper_in_bash.md

@@ -0,0 +1,33 @@
+# Exec wrapper in bash
+
+You can write exec wrapper in any language. However you should pay attention to termination process. When publisher closes the stream all executed processed get terminated. If you specify wrapper in ```exec``` directive instead of real ffmpeg then you might end up with your ffmpeg still alive and orphaned until it times out reading input data.
+
+The solution is using signal traps. Here's an example of such wrapper in bash.
+
+```sh
+#!/bin/bash
+
+on_die ()
+{
+    # kill all children
+    pkill -KILL -P $$
+}
+
+trap 'on_die' TERM
+ffmpeg -i rtmp://localhost/myapp/$1 -c copy -f flv rtmp://localhost/myapp2/$1 &
+wait
+```
+
+The script registers SIGTERM handler which terminates child ffmpeg. Default signal sent by nginx-rtmp is SIGKILL which cannot be caught. For the above script to behave as expected you need to change exec kill signal with ```exec_kill_signal``` directive. It accept numeric or symbolic signal name (for POSIX.1-1990 signals). Here's example application.
+```sh
+application myapp {
+    live on;
+
+    exec /var/scripts/exec_wrapper.sh $name;
+    exec_kill_signal term;
+}
+
+application myapp2 {
+    live on;
+}
+```

doc/faq.md

@@ -0,0 +1,26 @@
+# FAQ
+
+####RTMP stream is not played normally in IE, stream stops after several seconds.
+
+Add this directive to fix the problem
+```sh
+wait_video on;
+```
+
+####I use `pull` directive to get stream from remote location. That works for RTMP clients but does not work for HLS.
+
+Currently HLS clients do not trigger any events. You cannot pull or exec when HLS client connects to server. However you can use static directives `exec_static`, `pull ... static` to pull the stream always. 
+
+####Seek does not work with flv files recorded by the module.
+
+To make the files seekable add flv metadata with external software like yamdi, flvmeta or ffmpeg.
+```sh
+exec_record_done yamdi -i $path -o /var/videos/$basename;
+```
+
+####Published stream is missing from stats page after some time and clients fail to connect
+
+Check if you use multiple workers in nginx (`worker_processes`). In such case you have to enable:
+```sh
+rtmp_auto_push on;
+```

doc/getting_number_of_subscribers.md

@@ -0,0 +1,38 @@
+# Getting number of subscribers
+
+There's an easy way to display number of clients watching the stream. You need to
+
+Set up statistics page at location `/stat`
+```sh
+location /stat {
+    rtmp_stat all;
+    allow 127.0.0.1;
+}
+```
+
+Create a simple xsl stylesheet `nclients.xsl` extracting number of stream subscribers
+```xsl
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<xsl:output method="html"/>
+
+<xsl:param name="app"/>
+<xsl:param name="name"/>
+
+<xsl:template match="/">
+    <xsl:value-of select="count(//application[name=$app]/live/stream[name=$name]/client[not(publishing) and flashver])"/>
+</xsl:template>
+
+</xsl:stylesheet>
+```
+
+Set up a location returning number of suscribers
+```sh
+location /nclients {
+    proxy_pass http://127.0.0.1/stat;
+    xslt_stylesheet /www/nclients.xsl app='$arg_app' name='$arg_name';
+    add_header Refresh "3; $request_uri";
+}
+```
+
+Use HTTP request `http://myserver.com/nclients?app=myapp&name=mystream` to get the number of stream subscribers. This number will be automatically refreshed every 3 seconds when opened in browser or iframe.

doc/getting_started.md

@@ -0,0 +1,188 @@
+# Getting started with nginx rtmp
+
+## Download, build and install
+
+CD to build directory (home)
+```sh
+$ cd /usr/build
+```
+
+Download & unpack latest nginx-rtmp (you can also use http)
+```sh
+$ git clone git://github.com/arut/nginx-rtmp-module.git
+```
+
+Download & unpack nginx (you can also use svn)
+
+```sh
+$ wget http://nginx.org/download/nginx-1.2.4.tar.gz
+$ tar xzf nginx-1.2.4.tar.gz
+$ cd nginx-1.2.4
+```
+
+Build nginx with nginx-rtmp
+```sh
+$ ./configure --add-module=/usr/build/nginx-rtmp-module
+$ make
+$ make install
+```
+
+For nginx 1.3.4-1.5.0 more options are needed
+```sh
+$ ./configure --add-module=/usr/build/nginx-rtmp-module --with-http_ssl_module
+$ make
+$ make install
+```
+
+## Set up live streaming
+
+To set up RTMP support you need to add `rtmp{}` section to `nginx.conf` (can be found in PREFIX/conf/nginx.conf). Stock `nginx.conf` contains only `http{}` section.
+
+Use this `nginx.conf` instead of stock config:
+```sh
+#user  nobody;
+worker_processes  1;
+    
+error_log  logs/error.log debug;
+    
+events {
+    worker_connections  1024;
+}
+
+http {
+    include       mime.types;
+    default_type  application/octet-stream;
+    
+    sendfile        on;
+    keepalive_timeout  65;
+
+    server {
+        listen       8080;
+        server_name  localhost;
+    
+        # sample handlers
+        #location /on_play {
+        #    if ($arg_pageUrl ~* localhost) {
+        #        return 201;
+        #    }
+        #    return 202;
+        #}
+        #location /on_publish {
+        #    return 201;
+        #}
+    
+        #location /vod {
+        #    alias /var/myvideos;
+        #}
+    
+        # rtmp stat
+        location /stat {
+            rtmp_stat all;
+            rtmp_stat_stylesheet stat.xsl;
+        }
+        location /stat.xsl {
+            # you can move stat.xsl to a different location
+            root /usr/build/nginx-rtmp-module;
+        }
+    
+        # rtmp control
+        location /control {
+            rtmp_control all;
+        }
+        error_page   500 502 503 504  /50x.html;
+        location = /50x.html {
+            root   html;
+        }
+    }
+}
+rtmp {
+    server {
+        listen 1935;
+        ping 30s;
+        notify_method get;
+    
+        application myapp {
+            live on;
+    
+            # sample play/publish handlers
+            #on_play http://localhost:8080/on_play;
+            #on_publish http://localhost:8080/on_publish;
+    
+            # sample recorder
+            #recorder rec1 {
+            #    record all;
+            #    record_interval 30s;
+            #    record_path /tmp;
+            #    record_unique on;
+            #}
+
+            # sample HLS
+            #hls on;
+            #hls_path /tmp/hls;
+            #hls_sync 100ms;
+        }
+
+        # Video on demand
+        #application vod {
+        #    play /var/Videos;
+        #}
+
+        # Video on demand over HTTP
+        #application vod_http {
+        #    play http://localhost:8080/vod/;
+        #}
+    }
+}
+```
+
+## Statistics
+
+Navigate your browser to `http://localhost:8080/stat` to see current
+streaming statistics, connected clients, bandwidth etc.
+
+## Publishing with ffmpeg
+
+The easiest way to publish live video stream is using ffmpeg (or avconv).
+It's already installed on most systems and easy to install on others.
+
+RTMP supports only a limited number of codecs. The most popular RTMP video
+codecs are H264, Sorenson-H263 (aka flv) and audio codecs AAC, MP3,
+Nellymoser, Speex. If your video is encoded with these codecs
+(the most common pair is H264/AAC) then you do not need any conversion.
+Otherwise you need to convert video to one of supported codecs.
+
+We'll stream test file `/var/videos/test.mp4` to server with ffmpeg.
+
+Streaming without conversion (given `test.mp4` codecs are compatible with RTMP)
+```sh
+$ ffmpeg -re -i /var/Videos/test.mp4 -c copy -f flv rtmp://localhost/myapp/mystream
+```
+
+Streaming and encoding audio (AAC) and video (H264), need `libx264` and `libfaac`
+```sh
+$ ffmpeg -re -i /var/Videos/test.mp4 -c:v libx264 -c:a libfaac -ar 44100 -ac 1 -f flv rtmp://localhost/myapp/mystream
+```
+
+Streaming and encoding audio (MP3) and video (H264), need `libx264` and `libmp3lame`
+```sh
+$ ffmpeg -re -i /var/Videos/test.mp4 -c:v libx264 -c:a libmp3lame -ar 44100 -ac 1 -f flv rtmp://localhost/myapp/mystream
+```
+
+Streaming and encoding audio (Nellymoser) and video (Sorenson H263)
+```sh
+$ ffmpeg -re -i /var/Videos/test.mp4 -c:v flv -c:a nellymoser -ar 44100 -ac 1 -f flv rtmp://localhost/myapp/mystream
+```
+
+## Publishing video from webcam
+```sh
+$ ffmpeg -f video4linux2 -i /dev/video0 -c:v libx264 -an -f flv rtmp://localhost/myapp/mystream
+```
+
+## Playing with ffplay
+```sh
+$ ffplay rtmp://localhost/myapp/mystream
+```
+
+## Publishing and playing with flash
+
+See `test/rtmp-publisher` directory for test flash applets and html.

doc/installing_in_gentoo.md

@@ -0,0 +1,24 @@
+# Installing in Gentoo
+
+## Download module source code
+You have many options:
+* Get the zip at https://github.com/arut/nginx-rtmp-module/archive/master.zip
+* Or much better, do a git clone (see options in top of https://github.com/arut/nginx-rtmp-module)
+* Or get an ebuild from [fem-overlay](http://subversion.fem.tu-ilmenau.de/repository/fem-overlay/trunk/www-servers/nginx/nginx-1.2.5-r1.ebuild). And set the USE flag "nginx_modules_rtmp" or "nginx_modules_rtmp_hls".
+
+## Emerge nginx with nginx-rtmp-module
+> NGINX_ADD_MODULES="/path/to/nginx-rtmp-module" emerge -va nginx
+
+Replace `/path/to/` with the actual module's source path.
+You can add with this method any number of custom modules.
+
+To make this change permanent see:
+http://wiki.gentoo.org/wiki/Knowledge_Base:Overriding_environment_variables_per_package
+
+## Configure nginx
+Don't forget to include a rtmp section inside your nginx configuration file located at `/etc/nginx/nginx.conf`.
+
+See:
+* [Getting started](getting_started.md) We already have done _Download, build and install_ Gentoo style ;-)
+* [More Examples](examples.md)
+* [Reference of all directives](directives.md)

doc/installing_ubuntu_using_ppas.md

@@ -0,0 +1,30 @@
+# Installing on Ubuntu using PPAs
+```sh
+$ sudo apt-get install dpkg-dev
+$ sudo apt-get source nginx
+$ cd /usr/src/nginx
+$ sudo git clone https://github.com/arut/nginx-rtmp-module.git
+$ cd nginx-[version-number]
+$ sudo vi debian/rules
+```
+
+Edit the rules and at then end of the add-modules configuration string add
+```sh
+--add-module=/usr/src/nginx/nginx-rtmp-module \
+```
+
+If installing for the first time build nginx dependancies.
+```sh
+$ sudo apt-get build-dep nginx
+$ dpkg-buildpackage -b
+```
+
+(wait for a while while it builds... a really long while... like you might want to go grab a meal)
+
+```sh
+$ cd .. && sudo dpkg --install nginx-common_1.3.13-1chl1~quantal1_all.deb nginx-full_1.3.13-1chl1~quantal1_amd64.deb
+$ sudo service nginx status
+$ sudo service nginx start (if nginx isn't running)
+```
+
+[Source](http://serverfault.com/questions/227480/installing-optional-nginx-modules-with-apt-get)

doc/tutorial.md

@@ -0,0 +1,114 @@
+# Tutorial
+
+[This article is not finished yet]
+
+## RTMP
+RTMP is a proprietary protocol developed by Adobe (Macromedia) for use
+in flash player. Until 2009 it had no public specification.
+A number of third-party RTMP-related products started in that period
+were based on the results of reverse engineering. In 2009 
+[RTMP specification](http://www.adobe.com/devnet/rtmp.html) has been 
+published which made developing such applications easier. However
+the spec is not full and misses significant issues concerning streaming H264.
+
+## System requirements
+The module has been tested on Linux x86-family platforms. 
+However it should work on FreeBSD too.
+
+## Licence
+The module is distributed under BSD license.
+
+## Building NGINX with the module
+Building is pretty obvious. Just cd to nginx source directory
+and configure nginx this way:
+```sh
+$ ./configure --add-module=/path/to/nginx-rtmp-module
+```
+
+Then `make` and `make install`.
+
+## Configuration
+
+## Simple live application
+Simple live application configuration:
+```sh
+application live {
+
+    live on;
+
+}
+```
+
+You can add access list control:
+```sh
+application live {
+
+    live on;
+
+    allow publish 127.0.0.1;
+    deny publish all;
+    allow play all;
+
+}
+```
+
+And you can add record support for live streams:
+```sh
+application live {
+
+    live on;
+
+    allow publish 127.0.0.1;
+    deny publish all;
+    allow play all;
+
+    record all;
+    record_path /path/to/record/dir;
+    record_max_size 100M;
+    record_unique off;
+
+}
+```
+
+## HLS (HTTP Live Streaming)
+
+## Choosing flash player
+To watch RTMP stream in browser one should either develop
+flash application for that or use one of available flash
+players. The most popular players which are proved to have
+no problems with the module are:
+
+* [JWPlayer](http://www.longtailvideo.com/)
+* [FlowPlayer](http://flowplayer.org/)
+* [Strobe Media Playback](http://www.osmf.org/strobe_mediaplayback.html)
+* [Clappr](https://github.com/globocom/clappr)
+
+Old versions of JWPlayer (<=4.4) supported capturing video
+from webcam. You can find that version in test/ subdirectory.
+However audio is not captured by this version of player.
+Recent free versions of JWPlayer have no capture capability at
+all.
+
+## Transcoding streams
+You can use exec directive and ffmpeg for transcoding streams. For example:
+```sh
+application big {  
+    live on;  
+    exec /usr/bin/ffmpeg -re -i rtmp://localhost:1935/$app/$name -vcodec flv -acodec copy -s 32x32 -f flv rtmp://localhost:1935/small/${name};  
+}  
+application small {  
+    live on;  
+}
+```
+
+## Video on demand
+
+## Distributed streaming
+
+## Notifications & access control
+
+## Statistics
+
+## Verifying session
+
+## Utilizing multi-core CPUs