From d8e82bb29cfbcde8030a3b5146819d7629bdf858 Mon Sep 17 00:00:00 2001 From: Graham King Date: Mon, 29 Mar 2021 13:01:54 -0700 Subject: [PATCH 1/2] FAQ entries on how to use ion-sfu All written by @leewardbound --- FAQ.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/FAQ.md b/FAQ.md index 5dffe3e4b..045e0bac6 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,5 +1,45 @@ # Frequenty Asked Questions +### Can I / should I build on ion-sfu? + +Ion-sfu is considered "stable beta" and you can safely build on it. Many features are still under development, and the API is subject to change rapidly in future releases. If you want to build production-ready apps with ion-sfu, you need a strong grasp of WebRTC fundamentals and modern web development, and some experience with pion and golang is strongly recommended. You'll need to design your own Application Layer, responsible for transmitting signalling messages, validating client input, authenticating your users, administering room membership, and orchestrating scaling decisions. + +### Is ion-sfu actively maintained or supported? Can I get help? + +Ion-sfu actively developed and supported by an awesome community of volunteers! As an open source project in the pion community, the people who support this project are just the same volunteers who've made time to build and release it. You can join us in the gophers slack in #ion, we have a helpful and positive community and many people are always glad to talk about the project! Once you learn and use ion-sfu, you can help make the community better, too! + +### Which API should I use? + +There are many strong opinions about the answer to this question! + +- Library API - Use ion-sfu as a library. Start by embedding the SFU struct. Use the grpc or jsonrpc examples as a guide. + +- JSONRPC - a websocket interface for bi-directional json messages; it is a simpler and lighter protocol. It is very easy to parse and handle the messages in any language. The internal javascript examples mostly use jsonrpc because it is easy to read and understand. + +- GRPC - uses bi-directional message streams and protobufs. The client code is automatically generated for consumers, with strong typing definitions. Typically, no manual message parsing is required. + +- "All RPC" - package is jsonrpc + grpc at the same time, for convenient testing between a cmd line publisher and a bowser subscriber (or vice-versa). + +**None of these** are designed for end-users to connect directly to them. Always build an Application Server, either by using ion-sfu as a library, or using the grpc API to talk to a local ion-sfu. (?? Is using internal GRPC "officially supported"?) + +### What do you mean by "Application Server"? + +Ion-sfu is designed to be a building block that forwards video streams, not a finished product. It contains no mechanisms for validating user accounts or published streams; you must ensure that UIDs are not duplicated or spoofed. You must parse all incoming Offer signals to parse the SDP, and determine if the expected audio codecs are being sent, or the video is of a supported resolution. If a node has too many users, maybe you want to shard your sessions across a cluster of ion-sfu -- scaling decisions are left up to you. + +If you don't want to build an Application Server, we officially recommend the pion/ion project, but please note that many of the features described above are still Work-in-Progress in the ion project - which is alpha/pre-release quality - and we are eager for your contributions to our community! + +### Are the jsonrpc/grpc signalling servers in cmd/signal/ going to continue to be supported? + +The provided jsonrpc and grpc APIs are provided for testing purposes only. The official ion-sfu API is via golang imports; you can create a new SFU service by embedding the SFU struct in just a few lines of code, with any signalling interface you prefer. We have provided examples of jsonrpc and grpc servers, and the docker images to use those services internally, but they should not be exposed to accept unvalidated client input. +"Signalling will always be pluggable" -- tarrencev + +### How do I build the client? + +Use one of the official SDKs: + - Browser: [ion-sdk-js](https://github.com/pion/ion-sdk-js) + - Go application: [ion-sdk-go](https://github.com/pion/ion-sdk-go) + - Mobile: [ion-sdk-flutter](https://github.com/pion/ion-sdk-flutter) + ### How can I join a session receive-only, without sending any media? If you are using [ion-sdk-js](https://github.com/pion/ion-sdk-js) this should work by default. If not, read on. From 09d42c7beb47fc03424750d896e723d48ef7ce37 Mon Sep 17 00:00:00 2001 From: Leeward Bound Date: Sat, 3 Apr 2021 12:58:26 -0700 Subject: [PATCH 2/2] feat: updating readme to reflect golang API --- FAQ.md | 35 ++++++++++++----------------------- 1 file changed, 12 insertions(+), 23 deletions(-) diff --git a/FAQ.md b/FAQ.md index 045e0bac6..70c09cd3f 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,37 +1,26 @@ # Frequenty Asked Questions -### Can I / should I build on ion-sfu? +### Can I / should I build on `ion-sfu`? -Ion-sfu is considered "stable beta" and you can safely build on it. Many features are still under development, and the API is subject to change rapidly in future releases. If you want to build production-ready apps with ion-sfu, you need a strong grasp of WebRTC fundamentals and modern web development, and some experience with pion and golang is strongly recommended. You'll need to design your own Application Layer, responsible for transmitting signalling messages, validating client input, authenticating your users, administering room membership, and orchestrating scaling decisions. +`ion-sfu` is considered "stable beta", and you can safely build on it. Many features are still under development, and the API is subject to change rapidly in future releases. If you want to build production-ready apps with ion-sfu, you need a strong grasp of WebRTC fundamentals and modern web development, and some experience with pion and golang is strongly recommended. You'll need to design your own Application Layer, responsible for transmitting signalling messages, validating client input, authenticating your users, administering room membership, and orchestrating scaling decisions. -### Is ion-sfu actively maintained or supported? Can I get help? +### Is `ion-sfu` actively maintained or supported? Can I get help? -Ion-sfu actively developed and supported by an awesome community of volunteers! As an open source project in the pion community, the people who support this project are just the same volunteers who've made time to build and release it. You can join us in the gophers slack in #ion, we have a helpful and positive community and many people are always glad to talk about the project! Once you learn and use ion-sfu, you can help make the community better, too! +`ion-sfu` actively developed and supported by an awesome community of volunteers! As an open source project in the pion community, the people who support this project are just the same volunteers who've made time to build and release it. You can join us in the gophers slack in #ion, we have a helpful and positive community and many people are always glad to talk about the project! Once you learn and use `ion-sfu`, you can help make the community better, too! -### Which API should I use? - -There are many strong opinions about the answer to this question! - -- Library API - Use ion-sfu as a library. Start by embedding the SFU struct. Use the grpc or jsonrpc examples as a guide. - -- JSONRPC - a websocket interface for bi-directional json messages; it is a simpler and lighter protocol. It is very easy to parse and handle the messages in any language. The internal javascript examples mostly use jsonrpc because it is easy to read and understand. +### What happened to the `cmd/signal` servers? -- GRPC - uses bi-directional message streams and protobufs. The client code is automatically generated for consumers, with strong typing definitions. Typically, no manual message parsing is required. - -- "All RPC" - package is jsonrpc + grpc at the same time, for convenient testing between a cmd line publisher and a bowser subscriber (or vice-versa). - -**None of these** are designed for end-users to connect directly to them. Always build an Application Server, either by using ion-sfu as a library, or using the grpc API to talk to a local ion-sfu. (?? Is using internal GRPC "officially supported"?) +The Signalling server implementations in `cmd/signal` were moved to the `examples/` folder. If you want to build on `ion-sfu`, you should build your own Application Server, and the `examples/` are a great place to start. ### What do you mean by "Application Server"? -Ion-sfu is designed to be a building block that forwards video streams, not a finished product. It contains no mechanisms for validating user accounts or published streams; you must ensure that UIDs are not duplicated or spoofed. You must parse all incoming Offer signals to parse the SDP, and determine if the expected audio codecs are being sent, or the video is of a supported resolution. If a node has too many users, maybe you want to shard your sessions across a cluster of ion-sfu -- scaling decisions are left up to you. - -If you don't want to build an Application Server, we officially recommend the pion/ion project, but please note that many of the features described above are still Work-in-Progress in the ion project - which is alpha/pre-release quality - and we are eager for your contributions to our community! +Ion-sfu is designed to be a building block that forwards video streams, not a finished product. It contains no mechanisms for validating user accounts or published streams; you must ensure that UIDs are not duplicated or spoofed. You must parse all incoming Offer signals to parse the SDP, and determine if the expected audio codecs are being sent, or the video is of a supported resolution. If a node has too many users, maybe you want to shard your sessions across a cluster of `ion-sfu` -- scaling decisions are left up to you. -### Are the jsonrpc/grpc signalling servers in cmd/signal/ going to continue to be supported? +### Community ion-SFU implementations +If you don't want to build an Application Server, check out these community projects: -The provided jsonrpc and grpc APIs are provided for testing purposes only. The official ion-sfu API is via golang imports; you can create a new SFU service by embedding the SFU struct in just a few lines of code, with any signalling interface you prefer. We have provided examples of jsonrpc and grpc servers, and the docker images to use those services internally, but they should not be exposed to accept unvalidated client input. -"Signalling will always be pluggable" -- tarrencev + + `pion/ion` project (Work-in-Progress) alpha/pre-release, uses grpc-web and custom protobufs for signalling + + `cryptagon/ion-cluster` project (maintained by Tandem.io), uses jsonrpc for signalling ### How do I build the client? @@ -48,7 +37,7 @@ If a participant does not have a microphone or camera, or denies access to them Add a datachannel to the publisher peer connection. e.g. `this.publisher.createDataChannel("ion-sfu")` -### Does ion-sfu support audio level indication, telling me who is talking? +### Does `ion-sfu` support audio level indication, telling me who is talking? Yes. The subscriber peer connection will contain a data channel. It gets sent an array of stream id that are making noise, ordered loudest first.