Help

Installing

Requirements

  • 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
  • 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 https://gitlab.com/Deamos/flask-nginx-rtmp-manager.git
  • 2) Run the install script
    cd flask-nginx-rtmp-manager/setup
    sudo bash setup-osp.sh
  • 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 config.py.dist config.py
  • 4) Edit the Default Values in the Configuration File
    vi config.py
  • 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 https://docs.sqlalchemy.org/en/13/core/engines.html 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

    Coming Soon...

    Docker Install

    Coming Soon...

    top

    Upgrading

    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 setup-osp.sh
    • 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 dbUpgrade.sh
    • Restart Nginx and OSP
      sudo systemctl restart nginx-osp
      sudo systemctl restart osp

    top

    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 https://github.com/arut/nginx-rtmp-module/wiki/Directives

    With OBS

    Reduced Delay Setup (5 seconds)

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

    With ffmpeg

    Coming Soon...

    Transcoding

    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.

    Latency

    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.

    top

    Webhooks

    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%

    Examples

    Discord

    Type: POST
    Trigger event: Stream start

    Header

    
        {
            "Content-Type": "application/json"
        }
                    

    Payload

    
        {
            "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
                    }
                ]
                }
            ]
        }
                    
    Rocket.Chat

    Coming Soon...

    top

    API

    OSP provides a self-documenting API using swagger.io. 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.

    Example

    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"
                    
    top

    Clips

    Coming Soon...

    top

    Video uploads

    Coming Soon...

    top

    Channel protection

    Coming Soon...

    top

    Troubleshooting

    • 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

    top