https://github.com/matrix-org/waterfall
A cascading stream forwarding unit for scalable, distributed voice and video conferencing over Matrix
https://github.com/matrix-org/waterfall
Last synced: about 1 year ago
JSON representation
A cascading stream forwarding unit for scalable, distributed voice and video conferencing over Matrix
- Host: GitHub
- URL: https://github.com/matrix-org/waterfall
- Owner: matrix-org
- License: apache-2.0
- Created: 2022-03-30T02:55:14.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-04-27T17:16:56.000Z (about 3 years ago)
- Last Synced: 2025-04-10T16:07:03.674Z (about 1 year ago)
- Language: Go
- Homepage:
- Size: 738 KB
- Stars: 103
- Watchers: 10
- Forks: 5
- Open Issues: 35
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Waterfall
## Why
Waterfall is a cascaded, decentralised SFU. The intention is to be a
implementation of Matrix's [MSC3898: Native Matrix VoIP signalling for cascaded
foci (SFUs, MCUs...)](https://github.com/matrix-org/matrix-spec-proposals/pull/3898).
This example is self contained and doesn't require any external software. The
project was informed by the following goals.
* **Easy Scaling** - SFU count can be grown/shrunk as users arrive. We don't
scale on the dimension of calls making things easier.
* **Shorter Last Mile** - Users can connect to SFUs closest to them. Links `SFU
<-> SFU` are higher quality then public hops.
* **Flexibility in WebRTC server choice** - All communication takes place using
standard protocols/formats. You can use whatever server software best fits
your needs.
* **Client Simplicity** - Clients will need to be created on lots of platforms.
We should aim to use native WebRTC features as much as possible.
This project is at an early stage and implements the MSC only roughly - given
the current experimental nature of this projects, it deviates in certain areas
from the MSC.
## How
### Configuration
* `cp config.sample.yaml config.yaml`
* Fill in `config.yaml`
### Running
* `./scripts/run.sh`
* Access at
### Profiling
* `./scripts/profile.sh`
* Access at
### Building
* `./scripts/build.sh`
* `./dist/bin`
* Access at
## Docker
### Building docker image
In order to build a docker image, run the following in the root directory:
`$ docker build . -t matrix/waterfall`
### Running docker image
#### Easy Way
Just use `docker-compose up` and you're good to go.
Or `docker-compose up -d` if you're running it on a server in a detached state.
You can then find your container ID by checking `docker container ls`.
Which could then be used to e.g. check the container logs with `docker container logs `.
If you're developing locally, you can replace the path to the image with your own image tag, e.g. `matrix/waterfall`.
#### Hard Way
To run the image from the current directory assuming that there is a `config.yaml`:
```sh
docker run \
-v $(pwd)/config.yaml:/config.yaml \
--network host \
-it --rm matrix/waterfall \
sfu --config config.yaml
```
## _Element Call_ with SFU locally
You can find an example for a local VoIP setup with _Element Call_ and _SFU_ here: [local environment setup](doc/development.md)