Skip to content

Commit

Permalink
chore: update docs, README (8xFF#232)
Browse files Browse the repository at this point in the history
  • Loading branch information
@giangndm
giangndm authored Feb 15, 2024
1 parent 548633a commit a9c32eb
Show file tree
Hide file tree
Showing 40 changed files with 344 additions and 344 deletions.
242 changes: 85 additions & 157 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,15 @@
<a href="https://codecov.io/gh/8xff/atm0s-media-server">
<img src="https://codecov.io/gh/8xff/atm0s-media-server/branch/master/graph/badge.svg">
</a>
<!-- <a href="https://deps.rs/repo/github/8xff/atm0s-media-server">
<a href="https://deps.rs/repo/github/8xff/atm0s-media-server">
<img src="https://deps.rs/repo/github/8xff/atm0s-media-server/status.svg">
</a> -->
<!-- <a href="https://crates.io/crates/atm0s-media-server">
<img src="https://img.shields.io/crates/v/8xff-sdn.svg">
</a> -->
<!-- <a href="https://docs.rs/atm0s-media-server">
<img src="https://docs.rs/8xff-sdn/badge.svg">
</a> -->
</a>
<a href="https://crates.io/crates/atm0s-media-server">
<img src="https://img.shields.io/crates/v/atm0s-media-server.svg">
</a>
<a href="https://docs.rs/atm0s-media-server">
<img src="https://docs.rs/atm0s-media-server/badge.svg">
</a>
<a href="https://github.com/8xFF/atm0s-media-server/blob/master/LICENSE">
<img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT">
</a>
Expand All @@ -24,7 +24,9 @@

# Decentralized Ultra-Low Latency Streaming Server

A decentralized media server designed to handle media streaming on a global scale, making it suitable for large-scale applications but with minimal cost. It is designed with [SAN-I/O](https://sans-io.readthedocs.io/) in mind.
A decentralized media server designed to handle media streaming on a global scale, making it suitable for large-scale applications but with minimal cost.

It is developed by 8xFF, a group of independent developers who are passionate about building a new generation of media server and network infrastructure with decentralization in mind. While we have received support from various companies and individuals, we are not affiliated with any specific company. 8xFF is a community-driven project, and we welcome anyone interested in contributing to join us.

For a deep dive into the technical aspects of network architecture, please refer to our [Smart-Routing](https://github.com/8xFF/atm0s-sdn/blob/master/docs/smart_routing.md)

Expand All @@ -33,194 +35,120 @@ For a deep dive into the technical aspects of network architecture, please refer

(Above is a demo video of the version used by Bluesea Network)

## Features
- 🚀 Powered by Rust with memory safety and performance.
- High availability by being fully decentralized, with no central controller.
- 🛰️ Multi-zone support, high scalability.
- Support encodings: H264, Vp8, Vp9, H265 (Coming soon), AV1 (Coming soon)
- Cross-platform: Linux, macOS, Windows.
- Decentralized WebRTC SFU (Selective Forwarding Unit)
- Modern, full-featured client SDKs
- [x] [Vanilla JavaScript](https://github.com/8xFF/atm0s-media-sdk-js)
- [x] [Rust](WIP)
- [x] [React](https://github.com/8xFF/atm0s-media-sdk-react)
- [x] [React Native](WIP)
- [ ] Flutter
- [ ] iOS Native
- [ ] Android Native
- Easy to deploy: single binary, Docker, or Kubernetes
- Advanced features including:
- [x] Audio Mix-Minus (WIP)
- [x] Simulcast/SVC
- [x] SFU
- [x] SFU Cascading (each stream is a global PubSub channel, similar to [Cloudflare interconnected network](https://blog.cloudflare.com/announcing-cloudflare-calls/))
- [ ] Recording
- [x] RTMP
- [x] SIP (WIP)
- [x] WebRTC
- [x] Whip/Whep

## Getting started
To get started, you can either:
- Start from Docker

```bash
docker run --net=host 8xff/atm0s-media-server:latest
```

- Download prebuild

```bash
wget https://github.com/8xFF/atm0s-media-server/releases/download/latest/atm0s-media-server-aarch64-apple-darwin
```

- Build from source

```
cargo build --release --package atm0s-media-server
```
- Or using Helm chart

```bash
helm repo add 8xff https://8xff.github.io/helm
helm repo update
helm install atm0s-media-stack 8xff/atm0s-media-stack --set gateway.host={host}.{example.com} --namespace atm0s-media --create-namespace
```

### Prepare access token
## Project Status: Alpha

Any HTTP Request to any server will require an access token. These can be generated using the `token-generate` service's API.
By default, without specifying the cluster `secret`, you can use these pre-generated tokens for the default secret.
This project is currently in the alpha stage of development. It is actively being developed and may undergo significant changes, including changes to the API. The primary focus at this stage is to make the project stable and reliable.

- WHIP: `eyJhbGciOiJIUzI1NiJ9.eyJyb29tIjoiZGVtbyIsInBlZXIiOiJwdWJsaXNoZXIiLCJwcm90b2NvbCI6IldoaXAiLCJwdWJsaXNoIjp0cnVlLCJzdWJzY3JpYmUiOmZhbHNlLCJ0cyI6MTcwMzc1MjI5NDEyMn0.EfRZK7eHMZ-TCG23-jst8TAKVfbiQhX21cxB2mSznAM`
Our goals for this project can be summarized as follows:

- WHEP: `eyJhbGciOiJIUzI1NiJ9.eyJyb29tIjoiZGVtbyIsInBlZXIiOm51bGwsInByb3RvY29sIjoiV2hlcCIsInB1Ymxpc2giOmZhbHNlLCJzdWJzY3JpYmUiOnRydWUsInRzIjoxNzAzNzUyMzE1NTgyfQ.6XS0gyZWJ699BUN0rXtlLH-0SvgtMXJeXIDtJomxnig`
- **Goal 1**: Cluster: Create a global decentralized media server cluster with multiple zones, support both SDKs for flexible and mainstream protocols (RTMP, SIP, SRT) for compatibility.
- **Goal 2**: Market: Develop a sharing marketplace for the media server, enabling resource sharing and monetization. This will help scale the media server cluster during peak times and reduce costs during off-peak times. In the feature marketplace fees will be used to fund the development of the project.
- **Goal 3**: P2P Network: Establish a network between users, where servers only act as fallbacks. This approach aims to significantly reduce infrastructure costs and scale to infinity.

- RTMP: `eyJhbGciOiJIUzI1NiJ9.eyJyb29tIjoiZGVtbyIsInBlZXIiOiJydG1wIiwicHJvdG9jb2wiOiJSdG1wIiwicHVibGlzaCI6dHJ1ZSwic3Vic2NyaWJlIjpmYWxzZSwidHMiOjE3MDM3NTIzMzU2OTV9.Gj0uCxPwqsFfMFLX8Cufrsyhtb7vedNp3GeUtKQCk3s`
Our primary focus is currently on Goal 1. For details on the current phase plan, please refer to our [Roadmap](https://github.com/8xFF/atm0s-media-server/issues/69).

- SDK: `eyJhbGciOiJIUzI1NiJ9.eyJyb29tIjoiZGVtbyIsInBlZXIiOm51bGwsInByb3RvY29sIjoiV2VicnRjIiwicHVibGlzaCI6dHJ1ZSwic3Vic2NyaWJlIjp0cnVlLCJ0cyI6MTcwMzc1MjM1NTI2NH0.llwwbSwVTsyFgL_jYCdoPNVdOiC2jbtNb4uxxE-PU7A`
Goals 2 and 3 are in the research phase. For more information, you can visit this [Repository](https://github.com/giangndm/decentralized-p2p-streaming).

Or create with token-generate APIs. To do this, you will need to start the `token-generate` service by:

```
atm0s-media-server --http-port 3100 token-generate
```
## Features

After that, you can go to http://localhost:3100/ui/ to access the Swagger dashboard, from there you can choose the appropriate API to generate a token by yourself.
- 🚀 Powered by Rust with memory safety and performance.
- High availability by being fully decentralized, with no central controller.
- 🛰️ Multi-zone support, high scalability.
- Support encodings: H264, Vp8, Vp9, H265 (Coming soon), AV1 (Coming soon)
- Cross-platform: Linux, macOS, Windows.
- Decentralized WebRTC SFU (Selective Forwarding Unit)
- Modern, full-featured client SDKs
- [x] [Vanilla JavaScript](https://github.com/8xFF/atm0s-media-sdk-js)
- [x] [Rust](WIP)
- [x] [React](https://github.com/8xFF/atm0s-media-sdk-react)
- [x] [React Native](WIP)
- [ ] Flutter
- [ ] iOS Native
- [ ] Android Native
- Easy to deploy: single binary, Docker, or Kubernetes
- Advanced features including:
- [x] Audio Mix-Minus (WIP)
- [x] Simulcast/SVC
- [x] SFU
- [x] SFU Cascading (each stream is a global PubSub channel, similar to [Cloudflare interconnected network](https://blog.cloudflare.com/announcing-cloudflare-calls/))
- [ ] Recording
- [x] RTMP
- [x] SIP (WIP)
- [x] WebRTC
- [x] Whip/Whep

## Quick Start

### Prebuild or build from source

- From Docker

The default cluster secret is `insecure`, you can specify your own cluster secret using the flag `--secret` or with env `SECRET`. For example:
```bash
atm0s-media-server --http-port 3000 --secret supersecret gateway
docker run --net=host ghcr.io/8xff/atm0s-media-server:master --help
```

### Start a webrtc node only
- Download prebuild

| OS | Arch | Link |
| ----- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| MacOS | aarch64 | [Download](https://github.com/8xFF/atm0s-media-server/releases/download/latest/atm0s-media-server-aarch64-apple-darwin) |
| MacOS | x86_64 | [Download](https://github.com/8xFF/atm0s-media-server/releases/download/latest/atm0s-media-server-x86_64-apple-darwin) |
| Linux | aarch64 gnu | [Download](https://github.com/8xFF/atm0s-media-server/releases/download/latest/atm0s-media-server-aarch64-unknown-linux-gnu) |
| Linux | x86_64 gnu | [Download](https://github.com/8xFF/atm0s-media-server/releases/download/latest/atm0s-media-server-x86_64-unknown-linux-gnu) |
| Linux | aarch64 musl | [Download](https://github.com/8xFF/atm0s-media-server/releases/download/latest/atm0s-media-server-aarch64-unknown-linux-musl) |
| Linux | x86_64 musl | [Download](https://github.com/8xFF/atm0s-media-server/releases/download/latest/atm0s-media-server-x86_64-unknown-linux-musl) |

For simple testing, we can start a single node which supports Webrtc for testing with Whip and Whep
- Build from source

```
atm0s-media-server --http-port 3200 webrtc
cargo build --release --package atm0s-media-server
./target/release/atm0s-media-server --help
```

After that, we can access `http://localhost:3000/samples` to see all embedded samples

### Start entire cluster
### Run

In cluster mode, each module needs to be on a separate node. This setup can run on a single machine or multiple machines, whether they are connected via a public or private network.
Run first WebRTC node:

The Gateway node routes user traffic to the most suitable media server node.
```bash
atm0s-media-server --node-id 10 --sdn-port 10010 --http-port 3000 gateway
atm0s-media-server --http-port 3001 --zone-index=101 webrtc
```

Afterward, the gateway prints out its address in the format: 10@/ip4/127.0.0.1/udp/10010/ip4/127.0.0.1/tcp/10010. This address serves as the seed node for other nodes joining the cluster.

The WebRTC node serves users with either an SDK or a Whip, Whep client.
```bash
atm0s-media-server --node-id 21 --http-port 3001 --seeds ABOVE_GATEWAY_ADDR webrtc
```
After node1 started it will print out the node address like `101@/ip4/192.168.1.10/udp/10101/ip4/192.168.1.10/tcp/10101`, you can use it as a seed node for other nodes.

The RTMP node serves users with an RTMP broadcaster such as OBS or Streamyard.
```bash
atm0s-media-server --node-id 30 --seeds ABOVE_GATEWAY_ADDR rtmp
```
Run second WebRTC node:

The SIP module serves users with a SIP endpoint for integration with telephone providers.
```bash
atm0s-media-server --node-id 40 --seeds ABOVE_GATEWAY_ADDR sip
atm0s-media-server --http-port 3002 --zone-index=102 --seeds FIRST_NODE_ADDR webrtc
```

You can now access the sample page at the URL: http://localhost:3000/samples/webrtc/. There, you will find two pages: Whip Broadcast and Whep Viewer.
Now two nodes will form a cluster and can be used for media streaming.

Please note that the inner-gateway selects nodes based on usage, routing to the same media-server instance until it reaches high usage. For testing media exchange between systems, you can start more than one WebRTC module as needed.
First media-server: http://localhost:3001/samples/whip/whip.html

```
atm0s-media-server --node-id 22 --http-port 3002 --seeds ABOVE_GATEWAY_ADDR webrtc
atm0s-media-server --node-id 23 --http-port 3003 --seeds ABOVE_GATEWAY_ADDR webrtc
```
Second media-server: http://localhost:3002/samples/whep/whep.html

Afterward, you can directly access the samples on each WebRTC node:

First media-server: http://localhost:3001/samples/
Second media-server: http://localhost:3002/samples/
Third media-server: http://localhost:3003/samples/
You can use [Pregenerated-Token](./docs/getting-started/quick-start/whip-whep.md) to publish and play stream.

![Demo Screen](./docs/imgs/demo-screen.jpg)

Each node also exposes a metric dashboard here:

- Gateway: http://localhost:3000/dashboard/
- Media1: http://localhost:3001/dashboard/
- Media2: http://localhost:3002/dashboard/
- Media3: http://localhost:3003/dashboard/
Each node also has embedded monitoring page at `http://localhost:3001/dashboard/` and `http://localhost:3002/dashboard/`

![Monitoring](./docs/imgs/demo-monitor.png)

### Start RTMP session

Instead of publishing with the Whip client, we can use any RTMP client, such as OBS, to publish to the following stream:
## Resources

- Server: `rtmp://RTMP_NODE_IP:1935/live`
- Stream Key: `above generated rtmp token`

The stream codec should be configured with h264, without B-frames, and with the ultra-low latency option, as shown in the screenshot below.

![Monitoring](./docs/imgs/demo-rtmp-config.png)

### Testing with remote server

Some samples required access to microphone and camera permission, therefore it need to run with https if you want to test with some remote servers. We have 2 options for that:

- Running gateway or media-server under a reverse proxy like NGINX for providing https
- Start gateway or media-server with `--http-tls` for switching to self-signed https server.

## Live Demos

- SDK demos: [TBA]()
- Gather.io Clone: [TBA]()
- Meeting Sample: [TBA]()
- Broadcasting Sample: [TBA]()

## Docs

WIP

## Architecture

- Global Gateway
- Inner zone gateway
- Media Server
- Connector (connect to custom logic)

TODO: Diagram
- [Summary](./docs/summary.md)
- [Getting Started](./docs/getting-started/README.md)
- [User Guide](./docs/user-guide/README.md)
- [Contributor Guide](./docs/contributor-guide/README.md)
- [RFCs](https://github.com/8xff/RFCs)
- [FAQ](./docs/getting-started/faq.md)

## Contributing
The project is continuously being improved and updated. We are always looking for ways to make it better, whether that's through optimizing performance, adding new features, or fixing bugs. We welcome contributions from the community and are always looking for new ideas and suggestions. If you find it interesting or believe it could be helpful, we welcome your contributions to the codebase or consider starring the repository to show your support and motivate our team!

For more information, you can join our [Discord channel](https://discord.gg/qXr5zxsJWp)
The project is continuously being improved and updated. We are always looking for ways to make it better, whether that's through optimizing performance, adding new features, or fixing bugs. We welcome contributions from the community and are always looking for new ideas and suggestions. If you find it interesting or believe it could be helpful, we welcome your contributions to the codebase or consider starring the repository to show your support and motivate our team!

## Roadmap
The first version will be released together with [our Overlay Network](https://github.com/8xFF/atm0s-sdn).
Details on our roadmap can be seen [Roadmap](https://github.com/8xFF/atm0s-media-server/issues/69).
For more information, you can access [Contributor Guide](./docs/contributor-guide/README.md) and join our [Discord channel](https://discord.gg/qXr5zxsJWp)

## License

Expand Down
Loading

0 comments on commit a9c32eb

Please sign in to comment.