diff --git a/README.md b/README.md index 4fde98098c..c5ebb49ca2 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,203 @@ -# AlphaCC +# AlphaRTC -AlphaCC is the ML-based bandwidth estimation on WebRTC. + + + + + + + + + + + + + +
master + + + +
dev + + + +
issues + + + +
-## 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: -* 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) \ No newline at end of file diff --git a/README.webrtc.md b/README.webrtc.md new file mode 100644 index 0000000000..2a24595476 --- /dev/null +++ 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)