octoplex

Octoplex 🐙

Octoplex is a Docker-native live video restreamer.

• Restream RTMP/RTMPS to unlimited destinations
• Broadcast using OBS or any standard tool
• Add and remove destinations on-the-fly
• Automatic reconnections on drop
• Terminal UI with live metrics and health status
• Powered by FFmpeg, Docker & other open source tools

How it works

         +------------------+             +-------------------+
         |      OBS          |  ---->     |     Octoplex      |
         | (Video Capture)   |   RTMP     |                   |
         +------------------+             +-------------------+
                                                 |
                                                 | Restream to multiple destinations
                                                 v
              +------------+     +------------+     +------------+     +--------------+
              |  Twitch.tv |     |   YouTube  |     | Facebook   |     |  Other       |
              +------------+     +------------+     +------------+     | Destinations |
                                                                       +--------------+

Installation

Docker Engine (only if you'll run Octoplex locally)

Linux: See https://docs.docker.com/engine/install/.

macOS: https://docs.docker.com/desktop/setup/install/mac-install/

Octoplex

Homebrew

Octoplex can be installed using Homebrew on macOS or Linux.

$ brew tap rfwatson/octoplex
$ brew install octoplex

From GitHub

Alternatively, grab the latest build for your platform from the releases page.

Unarchive the octoplex binary and copy it somewhere in your $PATH.

Starting Octoplex

Octoplex can run as a single process (all-in-one), or in a client/server pair.

All-in-one

$ octoplex run

Starts the Octoplex server and the terminal UI in one process.

Docker must be running on the same machine.

Client/server

1. Start the server (on the host that has Docker):

$ octoplex server start

1. Connect the client (from your laptop or any host):

$ octoplex client start # --host my.remotehost.com if on a different host

client start is a lightweight TUI and does not need Docker to be installed.

1. Stop the server (and clean up any Docker resources) on the remote host:

$ octoplex server stop

Subcommand reference

Usage

Restreaming with OBS

RTMP

Use the following OBS stream configuration:

RTMPS

Or to connect with RTMPS:

⚠ Warning: OBS may not accept self‑signed certificates.

If you see the error

"The RTMP server sent an invalid SSL certificate."

then either install a CA‑signed cert for your RTMPS host, or import your self‑signed cert into your OS’s trusted store. See the configuration section below.

Restreaming with FFmpeg

RTMP

$ ffmpeg -i input.mp4 -c copy -f flv rtmp://localhost:1935/live

RTMPS

$ ffmpeg -i input.mp4 -c copy -f flv rtmps://localhost:1936/live

Configuration

Octoplex stores configuration state in a simple YAML file. (See above for its location.)

Sample configuration:

host: rtmp.example.com             # defaults to "localhost"
tls:                               # optional TLS settings; RTMPS support is automatic.
  cert: /etc/mycert.pem            # If you omit cert/key, a self-signed keypair will be
  key: /etc/mykey.pem              # generated using the `host` value above.
logfile:
  enabled: true                        # defaults to false
  path: /path/to/logfile               # defaults to $XDG_STATE_HOME/octoplex/octoplex.log
sources:
  mediaServer:
    streamKey: live                    # defaults to "live"
    rtmp:
      enabled: true                    # defaults to false
      ip: 127.0.0.1                    # defaults to 127.0.0.1
      port: 1935                       # defaults to 1935
    rtmps:
      enabled: true                    # defaults to false
      ip: 0.0.0.0                      # defaults to 127.0.0.1
      port: 1936                       # defaults to 1936
destinations:
  - name: YouTube                      # Destination name, used only for display
    url: rtmp://rtmp.youtube.com/12345 # Destination  URL with stream key
  - name: Twitch.tv
    url: rtmp://rtmp.youtube.com/12345
  # other destinations here

ℹ It is also possible to add and remove destinations directly from the terminal user interface.

⚠ sources.mediaServer.rtmp.ip must be set to a valid IP address if you want to accept connections from other hosts. Leave it blank to bind only to localhost (127.0.0.1) or use 0.0.0.0 to bind to all network interfaces.

Contributing

See CONTRIBUTING.md.

Bug reports

Open bug reports on GitHub.

Acknowledgements

Octoplex is built on and/or makes use of other free and open source software, most notably:

Licence

Octoplex is released under the AGPL v3 license.