nginx-rtmp-module README

The project's README from github.com/arut/nginx-rtmp-module. As one markdown file: README.md.

NGINX-based Media Streaming Server

nginx-rtmp-module

Project blog

http://nginx-rtmp.blogspot.com

Wiki manual

https://github.com/arut/nginx-rtmp-module/wiki/Directives

Google group

https://groups.google.com/group/nginx-rtmp

https://groups.google.com/group/nginx-rtmp-ru (Russian)

Donation page (Paypal etc)

http://arut.github.com/nginx-rtmp-module/

Features

Build

cd to NGINX source directory & run this:

./configure --add-module=/path/to/nginx-rtmp-module
make
make install

Several versions of nginx (1.3.14 - 1.5.0) require http_ssl_module to be added as well:

./configure --add-module=/path/to/nginx-rtmp-module --with-http_ssl_module

For building debug version of nginx add --with-debug

./configure --add-module=/path/to-nginx/rtmp-module --with-debug

Read more about debug log

Windows limitations

Windows support is limited. These features are not supported

RTMP URL format

rtmp://rtmp.example.com/app[/name]

app - should match one of application {} blocks in config

name - interpreted by each application can be empty

Multi-worker live streaming

Module supports multi-worker live streaming through automatic stream pushing to nginx workers. This option is toggled with rtmp_auto_push directive.

Example nginx.conf

rtmp {

    server {

        listen 1935;

        chunk_size 4000;

        # TV mode: one publisher, many subscribers
        application mytv {

            # enable live streaming
            live on;

            # record first 1K of stream
            record all;
            record_path /tmp/av;
            record_max_size 1K;

            # append current timestamp to each flv
            record_unique on;

            # publish only from localhost
            allow publish 127.0.0.1;
            deny publish all;

            #allow play all;
        }

        # Transcoding (ffmpeg needed)
        application big {
            live on;

            # On every pusblished stream run this command (ffmpeg)
            # with substitutions: $app/${app}, $name/${name} for application & stream name.
            #
            # This ffmpeg call receives stream from this application &
            # reduces the resolution down to 32x32. The stream is the published to
            # 'small' application (see below) under the same name.
            #
            # ffmpeg can do anything with the stream like video/audio
            # transcoding, resizing, altering container/codec params etc
            #
            # Multiple exec lines can be specified.

            exec 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 with reduced resolution comes here from ffmpeg
        }

        application webcam {
            live on;

            # Stream from local webcam
            exec_static ffmpeg -f video4linux2 -i /dev/video0 -c:v libx264 -an
                               -f flv rtmp://localhost:1935/webcam/mystream;
        }

        application mypush {
            live on;

            # Every stream published here
            # is automatically pushed to
            # these two machines
            push rtmp1.example.com;
            push rtmp2.example.com:1934;
        }

        application mypull {
            live on;

            # Pull all streams from remote machine
            # and play locally
            pull rtmp://rtmp3.example.com pageUrl=www.example.com/index.html;
        }

        application mystaticpull {
            live on;

            # Static pull is started at nginx start
            pull rtmp://rtmp4.example.com pageUrl=www.example.com/index.html name=mystream static;
        }

        # video on demand
        application vod {
            play /var/flvs;
        }

        application vod2 {
            play /var/mp4s;
        }

        # Many publishers, many subscribers
        # no checks, no recording
        application videochat {

            live on;

            # The following notifications receive all
            # the session variables as well as
            # particular call arguments in HTTP POST
            # request

            # Make HTTP request & use HTTP retcode
            # to decide whether to allow publishing
            # from this connection or not
            on_publish http://localhost:8080/publish;

            # Same with playing
            on_play http://localhost:8080/play;

            # Publish/play end (repeats on disconnect)
            on_done http://localhost:8080/done;

            # All above mentioned notifications receive
            # standard connect() arguments as well as
            # play/publish ones. If any arguments are sent
            # with GET-style syntax to play & publish
            # these are also included.
            # Example URL:
            #   rtmp://localhost/myapp/mystream?a=b&c=d

            # record 10 video keyframes (no audio) every 2 minutes
            record keyframes;
            record_path /tmp/vc;
            record_max_frames 10;
            record_interval 2m;

            # Async notify about an flv recorded
            on_record_done http://localhost:8080/record_done;

        }


        # HLS

        # For HLS to work please create a directory in tmpfs (/tmp/hls here)
        # for the fragments. The directory contents is served via HTTP (see
        # http{} section in config)
        #
        # Incoming stream must be in H264/AAC. For iPhones use baseline H264
        # profile (see ffmpeg example).
        # This example creates RTMP stream from movie ready for HLS:
        #
        # ffmpeg -loglevel verbose -re -i movie.avi  -vcodec libx264
        #    -vprofile baseline -acodec libmp3lame -ar 44100 -ac 1
        #    -f flv rtmp://localhost:1935/hls/movie
        #
        # If you need to transcode live stream use 'exec' feature.
        #
        application hls {
            live on;
            hls on;
            hls_path /tmp/hls;
        }

        # MPEG-DASH is similar to HLS

        application dash {
            live on;
            dash on;
            dash_path /tmp/dash;
        }
    }
}

# HTTP can be used for accessing RTMP stats
http {

    server {

        listen      8080;

        # This URL provides RTMP statistics in XML
        location /stat {
            rtmp_stat all;

            # Use this stylesheet to view XML as web page
            # in browser
            rtmp_stat_stylesheet stat.xsl;
        }

        location /stat.xsl {
            # XML stylesheet to view RTMP stats.
            # Copy stat.xsl wherever you want
            # and put the full directory path here
            root /path/to/stat.xsl/;
        }

        location /hls {
            # Serve HLS fragments
            types {
                application/vnd.apple.mpegurl m3u8;
                video/mp2t ts;
            }
            root /tmp;
            add_header Cache-Control no-cache;
        }

        location /dash {
            # Serve DASH fragments
            root /tmp;
            add_header Cache-Control no-cache;
        }
    }
}

Multi-worker streaming example

rtmp_auto_push on;

rtmp {
    server {
        listen 1935;

        application mytv {
            live on;
        }
    }
}

nginx-rtmp-module (arut/nginx-rtmp-module)

Searching Database…

14K ·GitHub
Nginx-rtmp-module
What is this?nginx-rtmp-module turns NGINX into a media streaming server, adding RTMP, HLS and MPEG-DASH live streaming plus RTMP video-on-demand playback of FLV/MP4 files.
Is this a standalone streaming server or an NGINX add-on?It is a C source module you compile directly into NGINX's source tree via NGINX's own build system; there is no separate binary.
How do I add it to NGINX?Place the module source next to NGINX's source, then from the NGINX source directory run ./configure --add-module=/path/to/nginx-rtmp-module, make, make install. Older NGINX versions 1.3.14-1.5.0 also need --with-httpsslmodule added.
Do I need FFmpeg for anything?Only if you want transcoding: the exec directive can call FFmpeg (or avconv) to resize, re-encode or re-publish a live stream.
Does everything work the same on Windows?No. On Windows, exec commands, static pulls and automatic worker push (autopush) are not supported.
Which operating systems can run it?It builds and runs on Linux, FreeBSD, macOS and Windows, with the Windows caveats noted above.
How can I check live stream statistics?The module exposes an HTTP stat endpoint that returns RTMP statistics as XML, which can be rendered as a readable page in the browser using the bundled stat.xsl stylesheet.
Can streams be relayed between multiple nginx servers?Yes, the push and pull directives let an application forward incoming streams to remote RTMP servers or pull streams from them, enabling distributed streaming setups.
Can it scale across multiple NGINX worker processes?Yes, the rtmp_auto_push directive automatically pushes a published stream to every NGINX worker so viewers get load-balanced across workers.
Can I trigger custom logic when a stream starts or stops?Yes, HTTP callbacks like onpublish, onplay and onrecorddone, plus the exec directive, let you run external programs or make HTTP requests on publish, play, record and disconnect events.
What are similar projects?livego, srs, FFmpeg, go2rtc, ZLMediaKit, owncast, mediamtx, GSYVideoPlayer
Which topics is it in?mp4, streams, relay, rtmp, recording, hls, live-streaming, nginx, web-server, video-streaming, freebsd, hooks
Creator
arut
Size
3.1 MB
Stars
14K
Updated
CommitDec 24
Age
14y
Commits · 90 Days