forked from roc-streaming/roc-toolkit
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
5 changed files
with
61 additions
and
128 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,112 +1,97 @@ | ||
| Overview | ||
| ******** | ||
|
|
||
| .. seealso:: :doc:`/about_project/features`, :doc:`/about_project/usage`, :doc:`/about_project/publications` | ||
|
|
||
| .. contents:: Table of contents: | ||
| :local: | ||
| :depth: 1 | ||
|
|
||
| Synopsis | ||
| -------- | ||
| What is it? | ||
| ----------- | ||
|
|
||
| Roc Toolkit implements real-time audio streaming over the network. | ||
|
|
||
| Roc is a toolkit for real-time audio streaming over the network. | ||
| Basically, it is a network transport, highly specialized for the real-time streaming. You write the stream to the one end and read it from another end, and Roc handles all the complexities of delivering data in time and with no loss. Encoding, decoding, maintaining latency, adjusting clocks, restoring losses -- all this happens transparently under the hood. | ||
|
|
||
| Basically, Roc is a network transport, highly specialized for the real-time streaming use case. The user writes the stream to the one end and reads it from another end, and Roc deals with all the complexity of the task of delivering data in time and with no loss. Encoding, decoding, adjusting rates, restoring losses -- all these are performed transparently under the hood. | ||
| The project is conceived as a swiss army knife for real-time streaming. It is designed to support a variety of network protocols, encodings, FEC schemes, and related features. Users can build custom configurations dedicated for specific use cases, while balancing quality, robustness, bandwidth, and compatibility. | ||
|
|
||
| The project is conceived as a swiss army knife for real-time streaming. It is designed to support a variety of network protocols, encodings, FEC schemes, and related features. The user can build custom configurations dedicated for specific use cases and choose an appropriate compromise between the quality, robustness, bandwidth, and compatibility issues. | ||
| What problems does it solve? | ||
| ---------------------------- | ||
|
|
||
| Note that the project is still at an early stage of development, and the list of the supported features is not very long. But there's more to come, of course. Contributions are also welcome! | ||
| .. seealso:: :doc:`/about_project/features` | ||
|
|
||
| Rationale | ||
| --------- | ||
| Real-time streaming needs a special approach. When we create software for it, we must address several problems. | ||
|
|
||
| Why real-time streaming needs a special approach? | ||
| When the network is not reliable (e.g. Wi-Fi or Internet), we need to handle losses. We can't just use a reliable protocol like TCP, because the latency would suffer. We also can't just ignore losses, because the service quality would suffer. | ||
|
|
||
| First, if both sender input and receiver output have real-time clocks, we should somehow deal with the (small) difference between their frequencies because every device has its own clock domain. A real-time streaming library should solve this problem, or otherwise, the sender and receiver streams will quickly get out of sync. | ||
| When network conditions are not known beforehand, or are varying in time, we should adapt to changes dynamically. In response to changed conditions, we may need to adjust latency, compression level, redundancy level, and other parameters on fly. | ||
|
|
||
| Second, if the network is not reliable, we should cope with losses. We can't just retry lost packets until they are delivered because it may be too late when we're done retrying. A real-time streaming library should solve this problem as well, or otherwise either latency or quality of service will suffer. | ||
| When both sender input and receiver output have real-time clocks (e.g. both are sound cards), we must compensate the drift between their clocks. Otherwise, the sender and receiver will quickly get out of sync. | ||
|
|
||
| Third, the real-time requirement usually leads to a compromise between various factors like quality, robustness, latency, bandwidth, and resource consumption. The right configuration depends on the specific use case. On the other hand, different encodings are suitable for different quality requirements, different FEC schemes are suitable for different latency and CPU requirements, and so on. Therefore, a real-time streaming library should support a variety of protocols, media encodings, FEC codes, and allow the user to select the most suitable configuration. | ||
| When sender and receiver capabilities differ, we need to negotiate stream format and select what is supported by everyone. When local and network formats are different, we should automatically perform all necessary conversions. | ||
|
|
||
| Fourth, applications that need real-time streaming usually also need some related features like service announcement and discovery, session negotiation, stream feedback and control, and so on. Such features are not directly related to real-time, but still would be expected to be found in a real-time streaming library. | ||
| The real-time requirement leads to a compromise between many factors like quality, robustness, latency, bandwidth, and resource consumption. This compromise highly depends on the use-case. We should offer the user enough variety of protocols, codecs, and profiles, to suit everyone's needs. | ||
|
|
||
| All of the issues listed above belong to the scope of this project. Some of them are addressed already, and others will be addressed in future releases. | ||
| Many applications that need real-time streaming often need similar related features. Encryption, QoS control, playback synchronization, to name a few. Such features are also in the scope of this project. | ||
|
|
||
| Project goals | ||
| ------------- | ||
| What are project goals? | ||
| ----------------------- | ||
|
|
||
| Project goals: | ||
| At the very high level, the project has the following goals: | ||
|
|
||
| * *real-time* --- allow the user to create real-time streams with guaranteed latency; | ||
| * *good media quality* --- cope even with medium- and high-quality audio streams; | ||
| * *good service quality* --- provide good quality of service even on unreliable networks; | ||
| * *high-level* --- implement a simple high-level API that hides all the complexity of the network transport; | ||
| * *comprehensive toolset* --- support multiple protocols, encodings, schemes, and give the user the full control of them; | ||
| * *guaranteed latency* --- implement real-time streaming with guaranteed latency; | ||
| * *high quality streaming* --- support CD- and DVD-quality audio streams; | ||
| * *robust playback* --- provide good quality of service even on unreliable networks; | ||
| * *high-level and easy to use interface* --- implement a simple and high-level API that hides all the complexity from user; | ||
| * *work "from the box" with optional tuning* --- provide good defaults that work in many environments; and allow fine tuning to achieve best results for specific setup; | ||
| * *adaptive algorithms* --- support adjusting to environment conditions on fly; | ||
| * *comprehensive toolset* --- support multiple protocols and codecs, and give the user the full control of them; | ||
| * *portability* --- support multiple operating systems and hardware architectures; | ||
| * *interoperability* --- rely on open, standard protocols. | ||
|
|
||
| Project scope | ||
| ------------- | ||
|
|
||
| The following list can help to determine whether Roc is suitable for a specific use case. | ||
|
|
||
| Latency requirements: | ||
|
|
||
| * low latency --- yes | ||
| * higher latency --- yes | ||
| * not real-time --- not very helpful, better use protocols like HTTP | ||
|
|
||
| Quality requirements: | ||
| When do I need it? | ||
| ------------------ | ||
|
|
||
| * lossless --- yes; CD-quality currently | ||
| * lossy --- not yet supported, but will be | ||
| * HD --- not yet supported, but will be | ||
| You need Roc when you need streaming: | ||
|
|
||
| Network type: | ||
| * with fixed or bounded latency; | ||
| * over unreliable network (e.g. Wi-Fi or Internet); | ||
| * between real-time sources (e.g. from captured output to sound card). | ||
|
|
||
| * wireless LAN --- yes | ||
| * wired LAN --- yes, still useful even though the network is reliable | ||
| * Internet --- yes, but no encryption is implemented yet | ||
| Example applications: | ||
|
|
||
| Media type: | ||
| * live broadcasting software | ||
| * home audio systems and home cinema | ||
| * concert or hall sound systems | ||
| * online jamming (playing music together remotely) | ||
| * streaming platforms for radio | ||
| * cloud streaming | ||
|
|
||
| * audio --- yes | ||
| * video --- not yet supported, but will be | ||
| * other --- not supported; maybe in future, but no plans yet | ||
| How do I use it? | ||
| ---------------- | ||
|
|
||
| Platform type: | ||
| .. seealso:: :doc:`/about_project/publications` | ||
|
|
||
| * server --- yes | ||
| * desktop -- yes, but we should separate desktop integrations from core | ||
| * mobile --- not yet supported, but will be | ||
| * embedded --- only Linux is supported currently | ||
| You can use the project several ways, depending on your use case: | ||
|
|
||
| Networking features: | ||
| * If you're creating an application, refer to :doc:`C library </api>` and its :doc:`bindings for other languages </api/bindings>`. | ||
|
|
||
| * network I/O --- yes | ||
| * real-time streaming protocols --- yes; only RTP-based protocols are implemented so far | ||
| * control protocols --- not yet supported, but will be | ||
| * Use :doc:`command-line tools </tools/command_line_tools>` in simple scenarios and for experimenting. | ||
|
|
||
| Sound processing features: | ||
| * Use :doc:`sound server modules </tools/sound_server_modules>` for deeper integration with systems like PulseAudio and PipeWire. | ||
|
|
||
| * sound I/O --- not yet (except command-line tools); use other libraries | ||
| * DSP --- limited; Roc is not a general-purpose DSP library | ||
| * For use on mobile, check out :doc:`end-user applications </tools/applications>`. | ||
|
|
||
| Application fields | ||
| ------------------ | ||
| Using for home audio | ||
| ~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Below is the list of example applications where Roc could be useful. | ||
| One application of Roc is building your own wireless home audio system. | ||
|
|
||
| Some of the applications will be possible only after adding relevant features like service discovery or video support, which are not ready yet. If you are thinking about using Roc in an open-source or closed-source project and want to join the efforts or need some improvements in Roc, feel free to contact us. | ||
| Using Roc, you can interconnect audio applications and devices across different platforms and audio systems, for example, ALSA (using command-line tools), PulseAudio and PipeWire (using sound server modules), macOS CoreAudio (using virtual device), and Android (using mobile app). | ||
|
|
||
| Example applications: | ||
| Here are some examples of what you can do: | ||
|
|
||
| * live broadcasting software | ||
| * cloud streaming | ||
| * VoIP, teleconferences | ||
| * home audio systems and home cinema | ||
| * mobile audio/video sharing | ||
| * video surveillance | ||
| * remote desktop | ||
| * remote controls with cameras | ||
| * you can connect speakers to a single-board computer and stream sound from your other devices to it; | ||
| * you can stream sound to your Android device, or back; | ||
| * you can set up some music server with remote control (like MPD) and then stream sound from it to other devices; | ||
| * you can set up several devices and switch between them on the fly via standard PulseAudio GUI or CLI; you can also route different apps to different devices; | ||
| * all of these can work over Wi-Fi with acceptable service quality. |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters