Rob Watson 5f026be769 refactor(config)!: update config file schema

BREAKING CHANGE: YAML schema

2025-04-18 18:00:28 +02:00

4.7 KiB

Raw Blame History

Octoplex 🐙

Octoplex is a live video restreamer for the terminal.

Restream RTMP to unlimited destinations
Broadcast using OBS and other standard tools
Add and remove destinations while streaming
Automatic reconnections
Terminal user interface with real-time container metrics and health status
Built on FFmpeg, Docker and other proven free software

How it works

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

Asciicast 📹

Installation

Docker Engine

First, make sure Docker Engine is installed. Octoplex uses Docker to manage FFmpeg and other streaming tools.

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.

Usage

Launch the octoplex binary.

$ octoplex

Connecting with OBS

To connect with OBS, configure it to stream to rtmp://localhost:1935/live.

Subcommands

Subcommand	Description
None	Launch the terminal user interface
`print-config`	Echo the path to the configuration file to STDOUT
`edit-config`	Edit the configuration file in $EDITOR
`version`	Print the version
`help`	Print help screen

Configuration file

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

Sample configuration:

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"
    host: rtmp.example.com             # defaults to "localhost"
    rtmp:                              # must be present, use `rtmp: {}` for defaults
      ip: 0.0.0.0                      # defaults to 127.0.0.1
      port: 1935                       # defaults to 1935
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

Bug reports

Open bug reports on GitHub.

Pull requests

Pull requests are welcome.

Acknowledgements

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

Name	License	URL
Docker	`Apache 2.0`	GitHub
FFmpeg	`LGPL`	Website
MediaMTX	`MIT`	GitHub
tview	`MIT`	GitHub

Licence

Octoplex is released under the AGPL v3 license.

4.7 KiB Raw Blame History Unescape Escape