{"id":23822397,"url":"https://github.com/glimesh/janus-ftl-plugin","last_synced_at":"2025-07-11T04:34:32.632Z","repository":{"id":37456924,"uuid":"289384191","full_name":"Glimesh/janus-ftl-plugin","owner":"Glimesh","description":"A plugin for the Janus WebRTC gateway to enable relaying of audio/video streams utilizing Mixer's FTL (Faster-Than-Light) protocol.","archived":false,"fork":false,"pushed_at":"2022-06-27T20:14:50.000Z","size":471,"stargazers_count":44,"open_issues_count":28,"forks_count":9,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-04-14T16:01:50.828Z","etag":null,"topics":["ftl","janus-gateway","mixer","streaming"],"latest_commit_sha":null,"homepage":"https://hayden.fyi/posts/2020-08-03-Faster-Than-Light-protocol-engineering-notes.html","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Glimesh.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2020-08-21T23:31:07.000Z","updated_at":"2024-02-19T14:23:23.000Z","dependencies_parsed_at":"2022-08-19T18:00:52.893Z","dependency_job_id":null,"html_url":"https://github.com/Glimesh/janus-ftl-plugin","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glimesh%2Fjanus-ftl-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glimesh%2Fjanus-ftl-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glimesh%2Fjanus-ftl-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glimesh%2Fjanus-ftl-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Glimesh","download_url":"https://codeload.github.com/Glimesh/janus-ftl-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232175024,"owners_count":18483504,"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":["ftl","janus-gateway","mixer","streaming"],"created_at":"2025-01-02T09:18:05.284Z","updated_at":"2025-01-02T09:18:05.839Z","avatar_url":"https://github.com/Glimesh.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Janus FTL Plugin\n\nThis is a work-in-progress [Janus](https://github.com/meetecho/janus-gateway) plugin\nto support the FTL \"Faster-Than-Light\" protocol developed for the Mixer live streaming service.\n\nThis protocol lets streamers deliver media to browser viewers with very low,\noften sub-second latency.\n\nSee my notes on the FTL protocol [here](https://hayden.fyi/posts/2020-08-03-Faster-Than-Light-protocol-engineering-notes.html).\n\n# Building\n\n## Dependencies\n\nFirst, compile and install [Janus](https://github.com/meetecho/janus-gateway).\n\nGet [Meson](https://mesonbuild.com/Getting-meson.html) for building.\n\nSee the `Dockerfile` for the full set of dependencies.\n\n## Building\n\nBy default during build we look for Janus in `/opt/janus` (the default install path), but this can be configured with the `JANUS_PATH` env var.\n\n```sh\nmkdir build/\nmeson build/\ncd build\nninja\n```\n\n### Use GCC 10 compiler\n\nThis project utilizes some C++20 features available only in GCC 10 or newer.\n\nIf you are building on a recent Ubuntu distribution, you can install the `gcc-10` and `g++-10` packages and configure meson to use them for compilation:\n\n```sh\nCC=gcc-10 CXX=g++-10 meson build/\n```\n\n### Building for production\n\nTo enable optimizations, set meson to build in `debugoptimized` mode (recommended over `release` mode so you can use the debug information to diagnose issues).\n\n```sh\nmeson --buildtype=debugoptimized build/\n```\n\nIf you've already previously configured meson, you can reconfigure it:\n\n```sh\nmeson --reconfigure --buildtype=debugoptimized build/\n```\n\n### Building on resource-constrained machines\n\nSome machines (like the teensy tiny DigitalOcean droplet) will fail to finish building with the default Ninja build configuration.\n\nConsider configuring Ninja to disable parallel builds to allow the build to finish successfully:\n\n```sh\ncd build\nninja -j 1\n```\n\nAlso consider [adding swap space](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-20-04) if you have \u003c2GB of RAM available.\n\n## Installing\n\n_(from `build/` directory)_\n\n```sh\nsudo ninja install\n```\n\n## Running\n\nJust fire up Janus (`/opt/janus/bin/janus`), and the FTL plugin should automatically load - you should see this output:\n\n```log\nFTL: Plugin initialized!\n[...]\nFTL: Ingest server is listening on port 8084\n```\n\nNow you ought to be able to point an FTL client at the ingest server and start streaming.\n\nThe default stream key is `123456789-aBcDeFgHiJkLmNoPqRsTuVwXyZ123456`.\n\n`123456789` can be whatever \"Channel ID\" you'd like.\n\n`aBcDeFgHiJkLmNoPqRsTuVwXyZ123456` can be overridden by setting the `FTL_SERVICE_DUMMY_HMAC_KEY` environment variable.\n\nSee `DummyServiceConnection.cpp` for the default stream key retrieval mechanism.\n\nFor watching your stream from a browser, see [janus-ftl-player](https://github.com/Glimesh/janus-ftl-player).\n\n# Configuration\n\nConfiguration is achieved through environment variables.\n| Environment Variable   | Supported Values | Notes             |\n| :--------------------- | :--------------- | :---------------- |\n| `FTL_HOSTNAME`         | Valid hostname   | The hostname of the machine running the FTL service. Defaults to system hostname. |\n| `FTL_NODE_KIND`        | `Standalone`: (default) This instance will listen for incoming FTL connections and transmit them to WebRTC clients.\u003cbr /\u003e`Ingest`: This instance will listen for incoming FTL connections and relay them to other nodes when instructed by an Orchestrator service.\u003cbr /\u003e`Edge`: This instance will receive stream relays from other nodes and transmit them to WebRTC clients. | This configuration value controls the behavior of the FTL plugin when used in conjunction with an [Orchestrator service](https://github.com/Glimesh/janus-ftl-orchestrator). |\n| `FTL_ORCHESTRATOR_HOSTNAME` | Valid hostname | The hostname of the Orchestrator service to connect to for stream relay information. |\n| `FTL_ORCHESTRATOR_PORT` | Port number, `1`-`65535`. | The port number to use when connecting to the Orchestrator service. |\n| `FTL_ORCHESTRATOR_PSK` | String of arbitrary hex values (ex. `001122334455ff`) | This is the pre-shared key used to establish a secure TLS1.3 connection to the Orchestrator service. |\n| `FTL_ORCHESTRATOR_REGION_CODE` | String value, default: `global` | This is a string value used by the Orchestrator to group regional nodes together to more effectively distribute video traffic. |\n| `FTL_SERVICE_CONNECTION` | `DUMMY`: (default) Dummy service connection \u003cbr /\u003e`GLIMESH`: Glimesh service connection \u003cbr /\u003e`REST`: REST service connection ([docs](docs/REST_SERVICE.md)) | This configuration value determines which service FTL should plug into for operations such as stream key retrieval. |\n| `FTL_SERVICE_METADATAREPORTINTERVALMS` | Time in milliseconds | Defaults to `4000`, controls how often FTL stream metadata will be reported to the service. |\n| `FTL_MAX_ALLOWED_BITS_PER_SECOND` | Integer bits per second | Defaults to `0` (disabled), FTL connections that exceed the bandwidth specified here will be stopped.\u003cbr /\u003e**Note that this is a strictly enforced maximum** based on a rolling average configured below; consider providing some buffer size for encoder spikes above the configured average. |\n| `FTL_ROLLING_SIZE_AVG_MS` | Milliseconds | Defaults to `2000`ms, FTL connections that exceed the max bits allowed per second within this interval will be stopped. |\n| `FTL_NACK_LOST_PACKETS` | `0`: Ignore missing packets \u003cbr /\u003e`1`: Send NACKs | Determines whether to send NACKs for missing packet sequences in the stream. |\n| `FTL_SERVICE_DUMMY_HMAC_KEY` | String, default: `aBcDeFgHiJkLmNoPqRsTuVwXyZ123456` | Key all FTL clients must use if service connection is `DUMMY`. The HMAC key is the part after the dash in a stream key. |\n| `FTL_SERVICE_DUMMY_PREVIEWIMAGEPATH` | `/path/to/directory` | The path where preview images of ingested streams will be stored if service connection is `DUMMY`. Defaults to `~/.ftl/previews` |\n| `FTL_SERVICE_GLIMESH_HOSTNAME` | Hostname value (ex. `localhost`, `glimesh.tv`) | This is the hostname the Glimesh service connection will attempt to reach. |\n| `FTL_SERVICE_GLIMESH_PORT` | Port number, `1`-`65535`. | This is the port used to communicate with the Glimesh service via HTTP/HTTPS. |\n| `FTL_SERVICE_GLIMESH_HTTPS` | `0`: Use HTTP \u003cbr /\u003e`1`: Use HTTPS | Determines whether HTTPS is used to communicate with the Glimesh service. |\n| `FTL_SERVICE_GLIMESH_CLIENTID` | String, OAuth Client ID returned by Glimesh app registration. | Used to authenticate to the Glimesh API. |\n| `FTL_SERVICE_GLIMESH_CLIENTSECRET` | String, OAuth Client Secret returned by Glimesh app registration. | Used to authenticate to the Glimesh API. |\n| `FTL_SERVICE_REST_HOSTNAME` | Hostname value (ex. `localhost`) | This is the hostname the REST service connection will attempt to reach. |\n| `FTL_SERVICE_REST_PORT` | Port number, `1`-`65535`. | This is the port used to communicate with the REST service via HTTP/HTTPS. |\n| `FTL_SERVICE_REST_HTTPS` | `0`: Use HTTP \u003cbr /\u003e`1`: Use HTTPS | Determines whether HTTPS is used to communicate with the REST service. |\n| `FTL_SERVICE_REST_PATH_BASE` | String, default: `/` | Used to add a path prefix to all REST API calls. |\n| `FTL_SERVICE_REST_AUTH_TOKEN` | String, default: `\"\"` | Used to authenticate REST service API calls using the `Authorization` header. Leave blank to disable. |\n\n# Dockering\n\n    docker build -t janus-ftl .\n    docker run --rm -p 8084:8084/tcp -p 8088:8088/tcp -p 9000-9100:9000-9100/udp -p 20000-20100:20000-20100/udp -e \"DOCKER_IP=HOST.IP.ADDRESS.HERE\" janus-ftl\n\n# systemd\n\nThis plugin will have systemd watchdog support if the `libsystemd-dev` package is installed. To enable this integration set `WatchdogSec` in your service unit file. The following is a sample service unit for running this plugin under systemd with reasonable defaults.\n\n```systemd\n[Unit]\nDescription=Janus WebRTC Server with FTL support\nRequires=network.target\nAfter=syslog.target network.target\n\n[Service]\nType=notify\nExecStart=/opt/janus/bin/janus -o\nRestart=on-failure\nRestartSec=10\nWatchdogSec=60\n\nLimitNOFILE=65536\n\n[Install]\nWantedBy=multi-user.target\n```\n\n# Misc Notes\n\n## Streaming from OBS\n\nCurrently, there is no UI in OBS to set a custom FTL ingest endpoint.\n\nIn order to specify a custom FTL ingest server, you will need to edit the `plugin_config\\rtmp-services\\services.json` file. This is located in `%AppData%\\obs-studio\\plugin_config\\rtmp-services\\services.json` on Windows.\n\nAdd the following to the `\"services\"` array:\n\n```json\n{\n    \"name\": \"YOUR NAME HERE\",\n    \"common\": false,\n    \"servers\": [\n        {\n            \"name\": \"SERVER NAME HERE\",\n            \"url\": \"your.janus.hostname\"\n        }\n    ],\n    \"recommended\": {\n        \"keyint\": 2,\n        \"output\": \"ftl_output\",\n        \"max audio bitrate\": 160,\n        \"max video bitrate\": 8000,\n        \"profile\": \"main\",\n        \"bframes\": 0\n    }\n},\n```\n\nAfter you've made this change, you can start OBS and find your service listed in the OBS settings UI.\n\n## Include paths\n\nIf you use VS code with the C++ extension, these include paths should make intellisense happy.\n\n```json\n\"includePath\": [\n    \"${workspaceFolder}/**\",\n    \"/opt/janus/include/janus\",\n    \"/usr/include/glib-2.0\",\n    \"/usr/lib/x86_64-linux-gnu/glib-2.0/include\"\n]\n```\n\n# License\n\n```\nCopyright (C) 2020  Hayden McAfee\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU Affero General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License\nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglimesh%2Fjanus-ftl-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglimesh%2Fjanus-ftl-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglimesh%2Fjanus-ftl-plugin/lists"}