{"id":13399201,"url":"https://github.com/rawrtc/rawrtc","last_synced_at":"2025-03-14T03:31:42.851Z","repository":{"id":44967947,"uuid":"80470566","full_name":"rawrtc/rawrtc","owner":"rawrtc","description":"WebRTC and ORTC with a little bit of RAWR!","archived":false,"fork":false,"pushed_at":"2021-12-23T16:45:33.000Z","size":1179,"stargazers_count":370,"open_issues_count":59,"forks_count":35,"subscribers_count":25,"default_branch":"master","last_synced_at":"2024-07-31T19:18:22.583Z","etag":null,"topics":["data-channel","ortc","peer-connection","sctp","webrtc"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rawrtc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-30T22:32:38.000Z","updated_at":"2024-07-16T19:24:09.000Z","dependencies_parsed_at":"2022-07-13T03:20:29.927Z","dependency_job_id":null,"html_url":"https://github.com/rawrtc/rawrtc","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawrtc%2Frawrtc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawrtc%2Frawrtc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawrtc%2Frawrtc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawrtc%2Frawrtc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rawrtc","download_url":"https://codeload.github.com/rawrtc/rawrtc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221432728,"owners_count":16820067,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-channel","ortc","peer-connection","sctp","webrtc"],"created_at":"2024-07-30T19:00:35.151Z","updated_at":"2024-10-25T14:32:55.892Z","avatar_url":"https://github.com/rawrtc.png","language":"C","funding_links":[],"categories":["C","Developer Resources","Libraries"],"sub_categories":["C/C++ Libraries","C/C++"],"readme":"# RAWRTC\n\n[![CircleCI build status][circleci-badge]][circleci-url]\n[![Travis CI build status][travis-ci-badge]][travis-ci-url]\n[![Join our chat on Gitter][gitter-icon]][gitter]\n\nA WebRTC and ORTC library with a small footprint.\n\n## Features\n\nThe following list represents all features that are planned for RAWRTC.\nFeatures with a check mark are already implemented.\n\n* ICE [[draft-ietf-ice-rfc-5245bis-08]][ice]\n  - [x] Trickle ICE [[draft-ietf-ice-trickle-07]][trickle-ice]\n  - [x] IPv4\n  - [x] IPv6\n  - [x] UDP\n  - [ ] TCP\n* STUN [[RFC 5389]][stun]\n  - [x] UDP\n  - [ ] TCP\n  - [ ] TLS over TCP\n  - [ ] DTLS over UDP [[RFC 7350]][stun-turn-dtls]\n* TURN [[RFC 5766]][turn]\n  - [ ] UDP\n  - [ ] TCP\n  - [ ] TLS over TCP\n  - [ ] DTLS over UDP [[RFC 7350]][stun-turn-dtls]\n* Data Channel\n  - [x] DCEP [[draft-ietf-rtcweb-data-protocol-09]][dcep]\n  - [x] SCTP-based [[draft-ietf-rtcweb-data-channel-13]][sctp-dc]\n* API\n  - [x] WebRTC C-API based on the [W3C WebRTC API][w3c-webrtc] and\n    [[draft-ietf-rtcweb-jsep-24]][jsep]\n  - [x] ORTC C-API based on the [W3C CG ORTC API][w3c-ortc]\n\n## FAQ\n\n1. *Does this use multiple threads?*\n\n   No, this library is single-threaded and uses an event loop underneath.\n\n2. *Can I use it in a threaded environment?*\n\n   Yes. Just make sure you're always calling it from the same thread the event\n   loop is running on, or either [lock/unlock the event loop thread][re-lock]\n   or [use the message queues provided by re][re-mqueue] to exchange data with\n   the event loop thread. However, it is important that you only run one *re*\n   event loop in one thread.\n\n3. *I only want a data channel implementation for my SFU!*\n\n   Check out [RAWRTCDC][rawrtcdc].\n\n## Prerequisites\n\nThe following tools are required:\n\n* [git][git]\n* [ninja][ninja] \u003e= 1.5\n* [meson][meson] \u003e= 0.48.0\n* pkg-config (`pkgconf` for newer FreeBSD versions)\n* SSL development libraries (`libssl-dev` on Debian, `openssl` on OSX and\n  FreeBSD)\n\n## Build\n\n```bash\ncd \u003cpath-to-rawrtc\u003e\nmkdir build\nmeson build\ncd build\nninja\n```\n\n## Run\n\nRAWRTC provides a lot of tools that can be used for quick testing purposes and\nto get started. Let's go through them one by one. If you just want to check out\ndata channels and browser interoperation, skip to the\n[`peer-connection` tool section](#peer-connection) which uses the WebRTC API or\nto the [`data-channel-sctp` tool section](#data-channel-sctp) which uses the\nORTC API.\n\nMost of the tools have required or optional arguments which are shared among\ntools. Below is a description for the various shared arguments:\n\n#### offering\n\nWhether the peer is going to create an offer. Provide `1` to create an offer\nimmediately or `0` to create an answer once the remote offer has been\nprocessed.\n\nOnly used by WebRTC API tools.\n\n#### ice-role\n\nDetermines the ICE role to be used by the ICE transport, where `0` means\n*controlled* and `1` means *controlling*.\n\nOnly used by ORTC API tools.\n\n#### sctp-port\n\nThe port number the internal SCTP stack is supposed to use. Defaults to `5000`.\n\nNote: It doesn't matter which port you choose unless you want to be able to\ndebug SCTP messages. In this case, it's easier to distinguish the peers by\ntheir port numbers.\n\nOnly used by ORTC API tools.\n\n#### ice-candidate-type\n\nIf supplied, one or more specific ICE candidate types will be enabled and all\nother ICE candidate types will be disabled. Can be one of the following\nstrings:\n\n* *host*\n* *srflx*\n* *prflx*\n* *relay*\n\nNote that this has no effect on the gathering policy. The candidates will be\ngathered but they will simply be ignored by the tool.\n\nIf not supplied, all ICE candidate types are enabled.\n\n### ice-gatherer\n\nAPI: ORTC\n\nThe ICE gatherer tool gathers and prints ICE candidates. Once gathering is\ncomplete, the tool exits.\n\nUsage:\n\n    ice-gatherer\n\n### ice-transport-loopback\n\nAPI: ORTC\n\nThe ICE transport loopback tool starts two ICE transport instances which\nestablish an ICE connection. Once you see the following line for both clients\n*A* and *B*, the ICE connection has been established:\n\n    (\u003cclient\u003e) ICE transport state: connected\n\nUsage:\n\n    ice-transport-loopback [\u003cice-candidate-type\u003e ...]\n\n### dtls-transport-loopback\n\nAPI: ORTC\n\nThe DTLS transport loopback tool starts two DTLS transport instances which\nwork on top of an established ICE transport connection.\n\nTo verify that the DTLS connection establishes, wait for the following line for\nboth clients *A* and *B*:\n\n    (\u003cclient\u003e) DTLS transport state change: connected\n\nUsage:\n\n    dtls-transport-loopback [\u003cice-candidate-type\u003e ...]\n\n### sctp-redirect-transport\n\nAPI: ORTC\n\nThe SCTP redirect transport tool starts an SCTP redirect transport on top of an\nestablished DTLS transport to relay SCTP messages from and to a third party.\nThis tool has been developed to be able to test data channel implementations\nwithout having to write the required DTLS and ICE stacks. An example of such a\ntesting tool is [dctt][dctt] which uses the kernel SCTP stack of FreeBSD.\n\nBuilding:\n\nThis tool is not built by default. You can enable building it in the following\nway:\n\n```bash\ncd \u003cpath-to-rawrtc\u003e/build\nmeson configure -Dsctp_redirect_transport=true\nninja\n```\n\nUsage:\n\n    sctp-redirect-transport \u003c0|1 (ice-role)\u003e \u003credirect-ip\u003e \u003credirect-port\u003e\n                            [\u003csctp-port\u003e] [\u003cmaximum-message-size\u003e]\n                            [\u003cice-candidate-type\u003e ...]\n\nSpecial arguments:\n\n* `redirect-ip`: The IP address on which the external SCTP stack is listening.\n* `redirect-port` The port on which the external SCTP stack is listening.\n* `maximum-message-size`: The maximum message size of a data channel message\n  the external SCTP stack is able to handle. `0` indicates that messages of\n  arbitrary size can be handled. Defaults to `0`.\n\n### data-channel-sctp-loopback\n\nAPI: ORTC\n\nThe data channel SCTP loopback tool creates several data channels on top of an\nabstracted SCTP data transport. As soon as a data channel is open, a message\nwill be sent to the other peer. Furthermore, another message will be sent on a\nspecific channel after a brief timeout.\n\nTo verify that a data channels opens, wait for the following line:\n\n    (\u003cclient\u003e) Data channel open: \u003cchannel-label\u003e\n    \nThe tool will send some large (16 MiB) test data to the other peer depending on\nthe ICE role. We are able to do this because RAWRTC handles data channel\nmessages correctly and does not have a maximum message size limitation compared\nto most other implementations (check out\n[this article][demystifying-webrtc-dc-size-limit] for a detailed explanation).\n\nUsage:\n\n    data-channel-sctp-loopback [\u003cice-candidate-type\u003e ...]\n\n### data-channel-sctp\n\nAPI: ORTC\n\nThe data channel SCTP tool creates several data channels on top of an\nabstracted SCTP data transport:\n\n* A pre-negotiated data channel with the label `cat-noises` and the id `0`\n  that is reliable and ordered. In the WebRTC JS API, the channel would be\n  created by invoking:\n   \n   ```js\n   peerConnection.createDataChannel('cat-noises', {\n       ordered: true,\n       id: 0\n   });\n   ```\n\n* A data channel with the label `bear-noises` that is reliable but unordered.\n  In the WebRTC JS API, the channel would be created by invoking:\n   \n   ```js\n   peerConnection.createDataChannel('bear-noises', {\n       ordered: false,\n       maxRetransmits: 0\n   });\n   ```\n\nTo establish a connection with another peer, the following procecure must be\nfollowed:\n\n1. The JSON blob after `Local Parameters:` must be pasted into the other peer\n   you want to establish a connection with. This can be either a browser\n   instance that uses the \n   [WebRTC-ORTC browser example tool][webrtc-ortc-example] or another instance\n   of this tool.\n\n2. The other peer's local parameters in form of a JSON blob must be pasted into\n   this tool's instance.\n\n3. Once you've pasted the local parameters into each other's instance, the peer\n   connection can be established by pressing *Enter* in both instances (press\n   the *Start* button in the browser).\n\nThe tool will send some test data to the other peer depending on the ICE role.\nHowever, the browser tool behaves a bit differently. Check the log output of\nthe tool instances (console output in the browser) to see what data has been\nsent and whether it has been received successfully.\n\nIn the browser, you can use the created data channels by accessing\n`peer.dc['\u003cchannel-name\u003e']`, for example:\n\n```js\npeer.dc['example-channel'].send('RAWR!')\n```\n\nUsage:\n\n    data-channel-sctp \u003c0|1 (ice-role)\u003e [\u003csctp-port\u003e] [\u003cice-candidate-type\u003e ...]\n\n### data-channel-sctp-streamed\n\nAPI: ORTC\n\nThe data channel SCTP streamed tool is the counterpart to the *normal* data\nchannel SCTP tool but uses the streaming mode. **Be aware this tool and the\nstreaming mode is currently experimental and incomplete.**\n\nThe necessary peer connection establishment steps are identical to the ones\ndescribed for the [data-channel-sctp](#data-channel-sctp) tool.\n\nUsage:\n\n    data-channel-sctp-streamed \u003c0|1 (ice-role)\u003e [\u003csctp-port\u003e]\n                               [\u003cice-candidate-type\u003e ...]\n\n### data-channel-sctp-echo\n\nAPI: ORTC\n\nThe data channel SCTP echo tool behaves just like any other echo server: It\nechoes received data on any data channel back to the sender.\n\nThe necessary peer connection establishment steps are identical to the ones\ndescribed for the [data-channel-sctp](#data-channel-sctp) tool.\n\nUsage:\n\n    data-channel-sctp-echo \u003c0|1 (ice-role)\u003e [\u003csctp-port\u003e]\n                           [\u003cice-candidate-type\u003e ...]\n    \n### data-channel-sctp-throughput\n\nAPI: ORTC\n\nThe data channel SCTP throughput tool allows you to test throughput by sending\none or more message. It will report the amount of seconds elapsed and the\nthroughput in Mbit/s.\n\nThe necessary peer connection establishment steps are identical to the ones\ndescribed for the [data-channel-sctp](#data-channel-sctp) tool. However,\nbe aware that this tool has no browser counterpart at the moment, so it only\nmakes sense to use two instances of this tool for throughput testing.\n\nUsage:\n\n    data-channel-sctp-throughput \u003c0|1 (ice-role)\u003e \u003cmessage-size\u003e [\u003cn-times\u003e]\n                                 [\u003csctp-port\u003e] [\u003cice-candidate-type\u003e ...]\n\nSpecial arguments:\n\n* `message-size`: Is the message size in bytes used for throughput testing. The\n  controlling peer will determine the message size for both peers, so this\n  argument is being ignored for the controlled peer.\n* `n-times`: Is the amount of times the message will be sent. Again, this\n  value is being ignored for the controlled peer.\n\n### peer-connection\n\nAPI: WebRTC\n\nThe peer connection tool creates a peer connection instance and several data\nchannels:\n\n* A pre-negotiated data channel with the label `cat-noises` and the id `0`\n  that is reliable and ordered. In the JS API, the channel would be created\n  by invoking:\n   \n   ```js\n   peerConnection.createDataChannel('cat-noises', {\n       ordered: true,\n       id: 0\n   });\n   ```\n\n* A data channel with the label `bear-noises` that is reliable but unordered.\n  In the WebRTC JS API, the channel would be created by invoking:\n   \n   ```js\n   peerConnection.createDataChannel('bear-noises', {\n       ordered: false,\n       maxRetransmits: 0\n   });\n   ```\n\nTo establish a connection with another peer, the following procecure must be\nfollowed:\n\n1. If the peer is taking the *offering* role, the generated JSON blob that\n   contains the *offer SDP* must be pasted into the other peer you want to\n   establish a connection with. This can be either a browser instance that uses\n   the [WebRTC browser example tool][webrtc-example] or another instance of\n   this tool. In case it is a browser instance, press the *Start* button and\n   paste the data directly into the text area below\n   `Paste remote description:`. In case it is another instance of this tool,\n   paste the data into the other peer's console and press *Enter*.\n\n2. The peer who takes the *answering* role now generates a JSON blob as well\n   that contains the *answer SDP*. It must be pasted into the other browser\n   instance or tool instance as described in the previous step.\n\n3. The peer connection should be established automatically once *offer* and\n   *answer* have been exchanged and applied.\n\nThe tool will send some test data to the other peer depending on whether or not\nit took the *offering* role. However, the browser tool behaves a bit\ndifferently. Check the log output of the tool instances (in the browser, either\nopen the console log or check out the live log on the right side) to see what\ndata has been sent and whether it has been received successfully.\n\nIn the browser, you can use the created data channels by accessing\n`pc.dcs['\u003cchannel-name\u003e']` in the console log, for example:\n\n```js\npc.dcs['cat-noises'].send('RAWR!')\n```\n\nUsage:\n\n    peer-connection \u003c0|1 (offering)\u003e [\u003cice-candidate-type\u003e ...]\n\n## Contributing\n\nWhen creating a pull request, it is recommended to run `format-all.sh` to\napply a consistent code style.\n\n\n\n[circleci-badge]: https://circleci.com/gh/rawrtc/rawrtc.svg?style=shield\n[circleci-url]: https://circleci.com/gh/rawrtc/rawrtc\n[travis-ci-badge]: https://travis-ci.org/rawrtc/rawrtc.svg?branch=master\n[travis-ci-url]: https://travis-ci.org/rawrtc/rawrtc\n[gitter]: https://gitter.im/rawrtc/Lobby\n[gitter-icon]: https://badges.gitter.im/rawrtc/Lobby.svg\n\n[ice]: https://tools.ietf.org/html/draft-ietf-ice-rfc5245bis-08\n[trickle-ice]: https://tools.ietf.org/html/draft-ietf-ice-trickle-07\n[stun]: https://tools.ietf.org/html/rfc5389\n[turn]: https://tools.ietf.org/html/rfc5766\n[stun-turn-dtls]: https://tools.ietf.org/html/rfc7350\n[dcep]: https://tools.ietf.org/html/draft-ietf-rtcweb-data-protocol-09\n[sctp-dc]: https://tools.ietf.org/html/draft-ietf-rtcweb-data-channel-13\n[jsep]: https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-19\n[w3c-webrtc]: https://www.w3.org/TR/webrtc/\n[w3c-ortc]: https://draft.ortc.org\n\n[re-lock]: http://www.creytiv.com/doxygen/re-dox/html/re__main_8h.html#ad335fcaa56e36b39cb1192af1a6b9904\n[re-mqueue]: http://www.creytiv.com/doxygen/re-dox/html/re__mqueue_8h.html\n[rawrtcdc]: https://github.com/rawrtc/rawrtc-data-channel\n\n[git]: (https://git-scm.com)\n[meson]: https://mesonbuild.com\n[ninja]: https://ninja-build.org\n\n[webrtc-ortc-example]: https://rawgit.com/rawrtc/rawrtc/master/htdocs/ortc/index.html\n[webrtc-example]: https://rawgit.com/rawrtc/rawrtc/master/htdocs/webrtc/index.html\n[dctt]: https://github.com/nplab/dctt\n[demystifying-webrtc-dc-size-limit]: https://lgrahl.de/articles/demystifying-webrtc-dc-size-limit.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frawrtc%2Frawrtc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frawrtc%2Frawrtc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frawrtc%2Frawrtc/lists"}