186 lines
5.7 KiB
Markdown
186 lines
5.7 KiB
Markdown
# Octoplex :octopus:
|
||
|
||
|
||
|
||
|
||
[](https://www.gnu.org/licenses/agpl-3.0)
|
||
|
||
Octoplex is a live video restreamer for the terminal.
|
||
|
||
* 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 |
|
||
+--------------+
|
||
```
|
||
|
||
## Asciicast :video_camera:
|
||
|
||
[](https://asciinema.org/a/Es8hpa6rq82ov7cDM6bZTVyCT)
|
||
|
||
## 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](https://github.com/rfwatson/octoplex/releases).
|
||
|
||
Unarchive the `octoplex` binary and copy it somewhere in your $PATH.
|
||
|
||
## Usage
|
||
|
||
Launch the `octoplex` binary.
|
||
|
||
```
|
||
$ octoplex
|
||
```
|
||
|
||
### Restreaming with OBS
|
||
|
||
#### RTMP
|
||
|
||
Use the following OBS stream configuration:
|
||
|
||
|
||
|
||
#### RTMPS
|
||
|
||
Or to connect with RTMPS:
|
||
|
||
|
||
|
||
:warning: 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](#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
|
||
```
|
||
|
||
### 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
|
||
|
||
Octoplex stores configuration state in a simple YAML file. (See [above](#subcommands) for its location.)
|
||
|
||
Sample configuration:
|
||
|
||
```yaml
|
||
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"
|
||
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.
|
||
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
|
||
```
|
||
|
||
:information_source: It is also possible to add and remove destinations directly from the
|
||
terminal user interface.
|
||
|
||
:warning: `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](https://github.com/rfwatson/octoplex/issues/new).
|
||
|
||
### 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](https://github.com/moby/moby/tree/master/client)
|
||
FFmpeg|`LGPL`|[Website](https://www.ffmpeg.org/legal.html)
|
||
MediaMTX|`MIT`|[GitHub](https://github.com/bluenviron/mediamtx)
|
||
tview|`MIT`|[GitHub](https://github.com/rivo/tview)
|
||
|
||
## Licence
|
||
|
||
Octoplex is released under the [AGPL v3](https://github.com/rfwatson/octoplex/blob/main/LICENSE) license.
|