Revise Readme (#13)

* Move readme from main * Improved styling for readme * Polish Readme Signed-off-by: zegan <ganze718@gmail.com> Co-authored-by: zegan <ganze718@gmail.com>
OpenNetLab · Nov 18, 2020 · c169ae2 · c169ae2
1 parent cfaa6fe
commit c169ae2
Show file tree

Hide file tree

Showing 2 changed files with 219 additions and 28 deletions.
diff --git a/README.md b/README.md
@@ -1,40 +1,203 @@
-# AlphaCC
+# AlphaRTC
 
-AlphaCC is the ML-based bandwidth estimation on WebRTC.
+<table>
+    <tr>
+        <td align="center">master</td>
+        <td align="center">
+            <a href="https://dev.azure.com/OpenNetLab/ONL-github/_build/latest?definitionId=3&branchName=main">
+                <img src="https://dev.azure.com/OpenNetLab/ONL-github/_apis/build/status/OpenNetLab.AlphaRTC?branchName=main">
+            </a>
+        </td>
+    </tr>
+    <tr>
+        <td align="center">dev</td>
+        <td align="center">
+            <a href="https://dev.azure.com/OpenNetLab/ONL-github/_build/latest?definitionId=3&branchName=dev">
+                <img src="https://dev.azure.com/OpenNetLab/ONL-github/_apis/build/status/OpenNetLab.AlphaRTC?branchName=dev">
+            </a>
+        </td>
+    </tr>
+    <tr>
+        <td align="center">issues</td>
+        <td align="center">
+            <a href="https://github.com/OpenNetLab/AlphaRTC/issues">
+                <img src="https://img.shields.io/github/issues-raw/OpenNetLab/AlphaRTC">
+            </a>
+        </td>
+    </tr>
+</table>
 
-## WebRTC
+## Motivation
+
+AlphaRTC is a fork of Google's WebRTC project using ML-based bandwidth estimation, delivered by the OpenNetLab team. By equipping WebRTC with a more accurate bandwidth estimator, our mission is to eventually increase the quality of transmission.
+
+AlphaRTC replaces Google Congestion Control (GCC) with ONNXInfer, an ML-powered bandwidth estimator, which takes in an ONNX model to make bandwidth estimation more accurate. ONNXInfer is proudly powered by Microsoft's [ONNXRuntime](https://github.com/microsoft/onnxruntime).
+
+## Environment
+
+Ubuntu 18.04 is the only officially supported distro at this moment. For other distros, you may be able to compile your own binary, or use our pre-provided Docker images.
+
+## Compilation
+
+To compile AlphaRTC, please refer to the following steps
+
+1. Prerequisites
+
+   Make sure Docker is installed on your system.
+
+   ``` shell
+   # Install Docker
+   curl -fsSL get.docker.com -o get-docker.sh
+   sudo sh get-docker.sh
+   ```
+
+2. Clone the code
+
+   ``` shell
+   git clone https://github.com/OpenNetLab/AlphaRTC.git
+   ```
+
+3. Build Docker images
+
+   ``` shell
+   cd AlphaRTC
+   sudo make all
+   ```
+
+   You should then be able to see two Docker images, `alphartc` and `alphartc-compile` using `sudo docker images`
+
+## Demo
+
+AlphaRTC consists of many different components. `peerconnection_serverless` is an application for demo purposes that comes with AlphaRTC. It establishes RTC communication with another peer without the need of a server.
 
-**WebRTC is a free, open software project** that provides browsers and mobile
-applications with Real-Time Communications (RTC) capabilities via simple APIs.
-The WebRTC components have been optimized to best serve this purpose.
+In order to run the application, you will need a configuration file in json format. The details are explained in the next chapter.
 
-**Our mission:** To enable rich, high-quality RTC applications to be
-developed for the browser, mobile platforms, and IoT devices, and allow them
-all to communicate via a common set of protocols.
+In addition to the config file, you will also need other files, such as video/audio source files and an ONNX model.
 
-The WebRTC initiative is a project supported by Google, Mozilla and Opera,
-amongst others.
+To run an AlphaRTC instance, put the config files in a directory, e.g., `config_files`, then mount it to an endpoint inside `alphartc` container
 
-### Basic Information
+``` shell
+sudo docker run -v config_files:/app/config_files alphartc peerconnection_serverless /app/config_files/config.json
+```
 
-* Commit ID: @656590dabce079db46a7c6676a55cd81268ea786
-* Repository: <https://webrtc.googlesource.com/src>
-* Branch: master
+Since `peerconnection_serverless` needs two peers, you may spawn two instances (a receiver and a sender) in the same network and make them talk to each other. For more information on Docker networking, check [Docker Networking](https://docs.docker.com/network/network-tutorial-standalone/)
 
-### Development
+### Configurations for *peerconnection_serverless*
 
-See http://www.webrtc.org/native-code/development for instructions on how to get
-started developing with the native code.
+This section describes required fields for the json configuration file.
 
-[Authoritative list](native-api.md) of directories that contain the
-native API header files.
+- **serverless_connection**
+  - **sender**
+    - **enabled**: If set to `true`, the client will act as sender and automatically connect to receiver when launched
+    - **send_to_ip**: The IP of serverless peerconnection receiver 
+    - **send_to_port**: The port of serverless peerconnection receiver
+  - **receiver**
+    - **enabled**: If set to `true`, the client will act as receiver and wait for sender to connect.
+    - **listening_ip**: The IP address that the socket in receiver binds and listends to
+    - **listening_port**: The port number that the socket in receiver binds and listends to
+  - **autoclose**: The time *in seconds* before close automatically (always run if autoclose=0)
 
-### More info
+  ***Note: one and only one of `sender.enabled` and `receiver.enabled` has to be `true`. I.e., `sender.enabled` XOR `receiver.enabled`***
+
+- **bwe_feedback_duration**: The duration the receiver sends its estimated target rate every time(*in millisecond*)
+
+- **onnx**
+  - **onnx_model_path**: The path of the [onnx](https://www.onnxruntime.ai/) model
+
+- **video_source**
+  - **video_disabled**:
+    - **enabled**: If set to `true`, the client will not take any video source as input
+  - **webcam**:
+    - **enabled**: __Windows-only__. If set to `true`, then the client will use the web camera as the video source. For Linux, please set to `false`
+  - **video_file**:
+    - **enabled**: If set to `true`, then the client will use a video file as the video source
+    - **height**: The height of the input video
+    - **width**: The width of the input video
+    - **fps**: The frames per second (FPS) of the input video
+    - **file_path**: The file path of the input video in [YUV](https://en.wikipedia.org/wiki/YUV) format
+
+  ***Note: one and only one of `video_source.webcam.enabled` and `video_source.video_file.enabled` has to be `true`. I.e., `video_source.webcam.enabled` XOR `video_source.video_file.enabled`***
+
+- **audio_source**
+  - **microphone**:
+    - **enabled**: Whether to enable microphone output or not
+  - **audio_file**:
+    - **enabled**: Whether to enable audio file input or not
+    - **file_path**: The file path of the input audio file in WAV format
+
+- **save_to_file**
+  - **enabled**: Whether to enable file saving or not
+  - **audio**:
+    - **file_path**: The file path of the output audio file in WAV format
+  - **video**
+    - **width**: The width of the output video file
+    - **height**: The height of the output video file
+    - **fps**: Frames per second of the output video file
+    - **file_path**: The file path of the output video file in YUV format
+
+#### Example
+
+``` json
+{
+    "serverless_connection": {
+        "sender": {
+            "enabled": false,
+            "dest_ip": "127.0.0.1",
+            "dest_port": 8888
+        }
+        "autoclose": 20
+    },
+
+    "bwe_feedback_duration": 200,
+
+    "onnx": {
+        "onnx_model_path": "onnx-model.onnx"
+    },
+
+    "video_source":{
+        "video_disabled": {
+            "enabled": true
+        },
+        "webcam": {
+            "enabled": false
+        },
+        "video_file": {
+            "enabled": true,
+            "height": 480,
+            "width": 640,
+            "fps": 24,
+            "file_path": "testmedia/test.yuv"
+        }
+    },
+
+    "audio_source": {
+        "microphone": {
+            "enabled": false
+        },
+        "audio_file": {
+            "enabled": true,
+            "file_path": "testmedia/test.wav"
+        }
+    },
+    "save_to_file": {
+        "enabled": true,
+        "audio": {
+            "file_path": "outaudio.wav"
+        },
+        "video": {
+            "width": 640,
+            "height": 480,
+            "fps": 24,
+            "file_path": "outvideo.yuv"
+        }
+    }
+}
+```
+
+## Who Are We
+
+The OpenNetLab team is an inter-academia research team, initiated by the Networking Reasearch Group at Microsoft Research Asia. Our team members are from different research institudes, including Peking University, Nanjing University and Nanyang Technological University.
+
+## WebRTC
 
-* Official web site: http://www.webrtc.org
-* Master source code repo: https://webrtc.googlesource.com/src
-* Samples and reference apps: https://github.com/webrtc
-* Mailing list: http://groups.google.com/group/discuss-webrtc
-* Continuous build: http://build.chromium.org/p/client.webrtc
-* [Coding style guide](style-guide.md)
-* [Code of conduct](CODE_OF_CONDUCT.md)
+You can find the Readme of the original WebRTC project [here](./README.webrtc.md)
diff --git a/README.webrtc.md b/README.webrtc.md
@@ -0,0 +1,28 @@
+**WebRTC is a free, open software project** that provides browsers and mobile
+applications with Real-Time Communications (RTC) capabilities via simple APIs.
+The WebRTC components have been optimized to best serve this purpose.
+
+**Our mission:** To enable rich, high-quality RTC applications to be
+developed for the browser, mobile platforms, and IoT devices, and allow them
+all to communicate via a common set of protocols.
+
+The WebRTC initiative is a project supported by Google, Mozilla and Opera,
+amongst others.
+
+### Development
+
+See http://www.webrtc.org/native-code/development for instructions on how to get
+started developing with the native code.
+
+[Authoritative list](native-api.md) of directories that contain the
+native API header files.
+
+### More info
+
+ * Official web site: http://www.webrtc.org
+ * Master source code repo: https://webrtc.googlesource.com/src
+ * Samples and reference apps: https://github.com/webrtc
+ * Mailing list: http://groups.google.com/group/discuss-webrtc
+ * Continuous build: http://build.chromium.org/p/client.webrtc
+ * [Coding style guide](style-guide.md)
+ * [Code of conduct](CODE_OF_CONDUCT.md)