• Ubuntu 18.04 or Later, Debian 10 or Later
  • Python 3.7 or later
  • MySQL 5.7.7 or later, or MariaDB > 10.1, if not using SQLite
  • Redis
  • SMTP Mail Server for Email Address Validation and Subscriptions
  • FFMPEG 3 or greater

Automatic Install

OSP has been tested on Ubuntu 18.04 and Recent Debian Builds. The installation script may not work properly on other OS's.

  • 1) Clone the Gitlab Repo
    git clone
  • 2) Run the install script
    cd flask-nginx-rtmp-manager/setup
    sudo bash
  • The installation script will install the files in the following location:
    • Video Files, Video Stream Files, and User Uploaded Images: /var/www
    • OSP Files: /opt/osp
    • Nginx Config Files: /usr/local/nginx/conf/
  • 3) Rename the Configuration File
    cd /opt/osp/conf
    sudo mv
  • 4) Edit the Default Values in the Configuration File
  • 6) Change the following values from their Default:
    • dbLocation - By Default, OSP uses SQLite, but you can change this value to use MySQL or Maria DB. See for more info on format
    • secretKey - Flask Secret Key, change this!
    • passwordSalt - Flask Security uses this value for Salting User Passwords, change this!
  • 7) Restart the OSP service
    sudo systemctl restart osp
  • 8) Open a Web Browser and configure OSP
    http://[SERVER IP]/
  • Manual Install

    Instructions can be found at the Gitlab Page

    Docker Install

    Instructions can be found at the Gitlab Page

    Database Notes

    By Default OSP uses a SQLite Database located in /opt/osp/db. However, it is recommended to use MySQL or another similar database in production. Once MySQL is installed and a database created, you can switch to MySQL by editing your /opt/osp/conf/ and change:
    dbLocation = 'sqlite:///db/database.db' to dbLocation = 'mysql+pymysql://$DBUsername:$DBPassword@localhost/$DBName?charset=utf8mb4'
    It is also recommended to increase the number of open connections for MySQL by editing nano /etc/mysql/mysql.conf.d/mysqld.cnf and change max_connections to match the following
    max_connections = 250
    After, restart MySQL and OSP to switch to the new Database.



    Standard Upgrade

    • Backup your Nginx.conf and Database File:
      sudo cp /usr/local/nginx/conf/nginx.conf /usr/local/nginx/conf/nginx.conf.bak sudo cp /opt/osp/db/database.db /opt/osp/db/database.bak
    • Perform a Git Pull
      cd /opt/osp
      sudo git pull
    • Rerun the OSP Setup Script - Updates any Dependencies and Rebuilds Nginx
      cd setup
      sudo bash
    • Verify your Nginx.conf and make any needed changes
      sudo vi /usr/local/nginx/conf/nginx.conf
    • Run the DB Upgrade Script to Ensure the Database Schema is up-to-date
      sudo bash
    • Restart Nginx and OSP
      sudo systemctl restart nginx-osp
      sudo systemctl restart osp


    Streaming to OSP

    In order to stream to OSP, a channel with a valid stream key is needed. After creating a channel, the streaming program must be set to the corresponding URL
    rtmp://Site FQDN or IP/stream/<steam-key>
    Note that only registered users with the streamer role are able to stream to OSP.

    OSP is configured by default with the following settings:

    • hls_framents: 1 second
    • hls_playlist_length: 10 seconds
    Alterations to the the Nginx-RTMP configuration can be made by editing the osp-rtmp.conf file in /usr/local/nginx/conf. More information on the Nginx-RTMP directives can be found at

    With OBS

    Reduced Delay Setup (5 seconds)

    Reduced Delay Streams can be achieved in OSP using the following settings:

    With ffmpeg

    ffmpeg can be used to stream directly to OSP in various situations which can add additional flexibility that is not available using another client software:

    • Stream from a local camera without a UI - ffmpeg -re -f video4linux2 -i $VideoDeviceLocation -vcodec libx264 -vprofile baseline -acodec aac -strict -2 -f flv rtmp://$OSPIP/stream/$StreamKey
    • Stream from a video file - ffmpeg -re -i $videolocation -vcodec libx264 -vprofile baseline -g 30 -acodec aac -strict -2 -f flv rtmp://$OSPIP/stream/$StreamKey
    • Restream from another RTMP Stream - ffmpeg -i $sourceStream -vcodec libx264 -vprofile baseline -acodec aac -strict -2 -f flv rtmp://$OSPIP/stream/$StreamKey


    Transcoding or adaptive streaming is possible with OSP. It can be enabled globally in the admin settings. However, this feature uses the CPU of the server to re-encode the streams and requires a lot of CPU power. It's possible to utilize GPUs instead by changing the encoder used by ffmpeg in the osp-rtmp.conf. Enabling transcoding will increase the stream latency. It may be necessary to increase the playlist length (see Latency).

    By default, nginx has been configured to transcode 1080p, 720p, 480p, & 360p. You can optimize how streams are transcoded by editing the osp-rtmp.conf file and following the instructions here.


    OSP uses HLS to serve RTMP streams to clients. This brings a certain latency by design. The default configuration of nginx is fine-tuned to reduce the latency as far as possible while providing stable HLS streams. For this configuration it is imporant that the encoder sends a keyframe every second! The latency should be 4.5 to 5 seconds.
    If streams are buffering, it's most likely because of a suboptimal network connection. In this case, increase the hls_playlist_length in the osp-rtmp.conf. The latency will increase with a longer playlist length.

    RTMP capable players (e.g. VLC) can access the RTMP stream directly. The URL is available in the share dialog below the stream. The latency of the RTMP stream should be 1 to 2 seconds.



    OSP can send HTTP requests (GET,POST,PUT,DELETE) to notify other services about various triggers. Webhooks can be set globally in the admin settings and per channel by users. The HTTP requests are entirely definable (see Examples below).

    Currently supported triggers:

    • At the Start of a Live Stream
    • At the End of a Live Stream
    • On a New Viewer Joining a Live Stream
    • On a Stream Upvote
    • On a Stream Metadata Change (Name/Topic)
    • On a Stream Chat Message
    • On Posting of a New Video to a Channel
    • On a New Video Comment
    • On a Video Upvote
    • On a Video Metadata Change (Name/Topic)

    When defining a webhook payload, various variables can be set which will be replaced with live data at the time the webhook is run. Webhook variables are defined as the following:

    • %channelname%
    • %channelurl%
    • %channeltopic%
    • %channelimage%
    • %streamer%
    • %channeldescription%
    • %streamname%
    • %streamurl%
    • %streamtopic%
    • %streamimage%
    • %user%
    • %userpicture%
    • %videoname%
    • %videodate%
    • %videodescription%
    • %videotopic%
    • %videourl%
    • %videothumbnail%
    • %comment%



    Type: POST
    Trigger event: Stream start


            "Content-Type": "application/json"


            "content": "%channelname% went live on OSP Test",
            "username": "OSP Bot",
            "embeds": [
                    "title": "%streamurl%",
                    "url": "%streamurl%",
                    "color": 6570404,
                    "image": {
                    "url": "%channelimage%"
                "author": {
                    "name": "%streamer% is now streaming"
                "fields": [
                        "name": "Channel",
                        "value": "%channelname%",
                        "inline": true
                        "name": "Topic",
                        "value": "%streamtopic%",
                        "inline": true
                        "name": "Stream Name",
                        "value": "%streamname%",
                        "inline": true
                        "name": "Description",
                        "value": "%channeldescription%",
                        "inline": true

    Coming Soon...



    OSP provides a self-documenting API using The API can be accessed at http(s)://Site FQDN or IP/apiv1". For authenticated endpoints, an API key is needed, which can be created by users with the streamer role in the user menu to the top right. Requests to authenticated endpoints must have the 'X-API-KEY': header field set with a valid API key.


    In this example a chat message is sent to a chat channel endpoint.

    Username: botname
    Message: beep bob
    Endpoint: channels/chat/72223bf3-be79-4a2a-88d9-c7bdce271f0e
    API key: d26de1eb2d48a784e109b29025632fc1a0211a2ffbede09672c8cf6f4321fb0000c49cb243e2d07e

        curl -X POST "http://localhost/apiv1/channels/chat/72223bf3-be79-4a2a-88d9-c7bdce271f0e?username=botname&message=beep%20bop" \
        -H  "accept: application/json" -H  "X-API-KEY: d26de1eb2d48a784e109b29025632fc1a0211a2ffbede09672c8cf6f4321fb0000c49cb243e2d07e"


    Coming Soon...


    Video uploads

    Coming Soon...


    Channel protection

    Coming Soon...



    • OSP opens fine but when you try to stream to it, the stream never displays on the live channel page
        - Check the Admin Settings under Site Protocol and Site Address. Incorrect values can cause the system to not pass the stream off properly to Nginx-RTMP.
    • OSP doesn't open properly. The tv static error pages doesn't show and instead, a basic 500 error page is given
        - Ensure the OSP service (sudo systemctl start osp) has been started. If it continues to fail, check the OSP logs at /var/log/gunicorn/error.log