diff --git a/README.md b/README.md index 264e26330..8d341bbd9 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,33 @@ -# LiveKit - Open source, high performance WebRTC infrastructure +# LiveKit: High-performance WebRTC -LiveKit is an open source project that provides scalable, multi-user conferencing over WebRTC. It's designed to give you -everything you need to build real time video/audio/data capabilities in your applications. +LiveKit is an open source project that provides scalable, multi-user conferencing based on WebRTC. It's designed to provide everything you need to build real-time video/audio/data capabilities in your applications. -LiveKit is written in Go, using the awesome [Pion WebRTC](https://github.com/pion/webrtc) implementation. +LiveKit's server is written in Go, using the awesome [Pion WebRTC](https://github.com/pion/webrtc) implementation. + +[![GitHub stars](https://img.shields.io/github/stars/livekit/livekit?style=social&label=Star&maxAge=2592000)](https://github.com/livekit/livekit/stargazers/) +[![Slack community](https://img.shields.io/endpoint?url=https%3A%2F%2Flivekit.io%2Fbadges%2Fslack)](https://livekit.io/join-slack) +[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/livekit/livekit/Test)](https://github.com/livekit/livekit/actions/workflows/buildtest.yaml) +[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/livekit/livekit)](https://github.com/livekit/livekit/releases/latest) +[![License](https://img.shields.io/github/license/livekit/livekit)](https://github.com/livekit/livekit/blob/master/LICENSE) ## Features - Scalable, distributed WebRTC SFU (Selective Forwarding Unit) -- Modern, full-featured [client SDKs](https://docs.livekit.io/references/client-sdks/) -- Built for production - JWT authentication and [server APIs](https://docs.livekit.io/guides/server-api) -- Robust networking & connectivity. UDP/TCP/TURN -- Easy to deploy - single binary, docker & kubernetes -- Advanced features - speaker detection, simulcast, selective subscription, moderation APIs, and webhooks. +- Modern, full-featured client SDKs +- Built for production, supports JWT authentication +- Robust networking and connectivity, UDP/TCP/TURN +- Easy to deploy: single binary, Docker or Kubernetes +- Advanced features including: + - [speaker detection](https://docs.livekit.io/guides/room/receive/#speaker-detection) + - [simulcast](https://docs.livekit.io/guides/room/publish/#video-simulcast) + - [end-to-end optimizations](https://blog.livekit.io/livekit-one-dot-zero/) + - [selective subscription](https://docs.livekit.io/guides/room/receive/#selective-subscription) + - [moderation APIs](https://docs.livekit.io/guides/server-api/) + - [webhooks](https://docs.livekit.io/guides/webhooks/) ## Documentation & Guides -Docs & Guides at: https://docs.livekit.io +https://docs.livekit.io ## Try it live @@ -25,110 +36,199 @@ Head to [our playground](https://livekit.io/playground) and give it a spin. Buil ## SDKs & Tools -Client SDKs: +### Client SDKs -- [JavaScript](https://github.com/livekit/client-sdk-js) ([docs](https://docs.livekit.io/client-sdk-js/)) -- [React](https://github.com/livekit/livekit-react) -- [iOS & MacOS - Swift](https://github.com/livekit/client-sdk-swift) ([docs](https://docs.livekit.io/client-sdk-swift/)) -- [Android - Kotlin](https://github.com/livekit/client-sdk-android) ([docs](https://docs.livekit.io/client-sdk-android/)) -- [Flutter](https://github.com/livekit/client-sdk-flutter) ([docs](https://docs.livekit.io/client-sdk-flutter/)) -- [Unity (WebGL)](https://github.com/livekit/client-sdk-unity-web) ([docs](https://livekit.github.io/client-sdk-unity-web/) [demo](https://unity.livekit.io)) -- [React Native](https://github.com/livekit/client-sdk-react-native) +Client SDKs enable your frontend to include interactive, multi-user experiences. -Server SDKs: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LanguageRepo + Declarative UI + Links
JavaScript (TypeScript) + client-sdk-js + + React + + docs + | + JS example + | + React example +
Swift (iOS / MacOS) + client-sdk-swift + Swift UI + docs + | + example +
Kotlin (Android) + client-sdk-android + Compose + docs + | + example + | + Compose example +
Flutter + client-sdk-flutter + native + docs + | + example +
Unity WebGL + client-sdk-unity-web + + docs +
React Native (beta) + client-sdk-react-native + native
-- [JavaScript](https://github.com/livekit/server-sdk-js) ([docs](https://docs.livekit.io/server-sdk-js/)) -- [Go](https://github.com/livekit/server-sdk-go) ([docs](https://pkg.go.dev/github.com/livekit/server-sdk-go)) -- [Ruby](https://github.com/livekit/server-sdk-ruby) -- [Python (community)](https://github.com/tradablebits/livekit-server-sdk-python) -- [PHP (community)](https://github.com/agence104/livekit-server-sdk-php) +### Server SDKs -Tools: +Server SDKs enable your backend to generate [access tokens](https://docs.livekit.io/guides/access-tokens/), call [server APIs](https://docs.livekit.io/guides/server-api/), and receive [webhooks](https://docs.livekit.io/guides/webhooks/). In addition, the Go SDK includes client capabilities, enabling you to build automations that behave like end-users. -- [Egress](https://github.com/livekit/egress): export and record your rooms -- [livekit-cli](https://github.com/livekit/livekit-cli): command line admin & tools -- [livekit-load-tester](https://github.com/livekit/livekit-cli#livekit-load-tester): load testing +| Language | Repo | Docs | +| :---------------------- | :-------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- | +| Go | [server-sdk-go](https://github.com/livekit/server-sdk-go) | [docs](https://pkg.go.dev/github.com/livekit/server-sdk-go) | +| JavaScript (TypeScript) | [server-sdk-js](https://github.com/livekit/server-sdk-js) | [docs](https://docs.livekit.io/server-sdk-js/) | +| Ruby | [server-sdk-ruby](https://github.com/livekit/server-sdk-ruby) | | +| Python (community) | [tradablebits/livekit-server-sdk-python](https://github.com/tradablebits/livekit-server-sdk-python) | | +| PHP (community) | [agence104/livekit-server-sdk-php](https://github.com/agence104/livekit-server-sdk-php) | | + +### Ecosystem & Tools + +- [Egress](https://github.com/livekit/egress) - export and record your rooms +- [CLI](https://github.com/livekit/livekit-cli) - command line interface & load tester - [Docker image](https://hub.docker.com/r/livekit/livekit-server) - [Helm charts](https://github.com/livekit/livekit-helm) -## Quickstart +## Install -### Generate config file and keys +We recommend installing [livekit-cli](https://github.com/livekit/livekit-cli) along with the server. It lets you access server APIs, create tokens, and generate test traffic. + +### MacOS ```shell -docker run --rm -v$PWD:/output livekit/generate --local +brew install livekit ``` -The above command generates a `livekit.yaml` you can use to start LiveKit. It'll contain an API key/secret pair you can -use with your LiveKit install. - -### Starting with docker +### Linux ```shell -docker run --rm -p 7880:7880 \ - -p 7881:7881 \ - -p 7882:7882/udp \ - -v $PWD/livekit.yaml:/livekit.yaml \ - livekit/livekit-server \ - --config /livekit.yaml \ - --node-ip +curl -sSL https://get.livekit.io | bash ``` -When running with docker, `--node-ip` needs to be set to your machine's IP address. If the service will be exposed to -the public Internet, this should the machine's public IP. +### Windows + +Download the [latest release here](https://github.com/livekit/livekit/releases/latest) + +## Getting Started + +### Starting LiveKit + +Start LiveKit by running `livekit-server` with no arguments. It will start in development mode by default with a placeholder API key/secret pair. + +``` +API Key: devkey +API Secret: secret +``` + +To customize your setup for production, refer to our [deployment docs](https://docs.livekit.io/deploy/) + +### Creating an access token + +A user connecting to a LiveKit room requires an [access token](https://docs.livekit.io/guides/access-tokens/). Access tokens (JWT) encode the user's identity and the room permissions they've been granted. You can generate a token with our CLI: + +```shell +livekit-cli create-token \ + --api-key devkey --api-secret secret \ + --join --room my-first-room --identity user1 \ + --valid-for 24h +``` ### Test with example app -Head over to the [example app](https://example.livekit.io) and enter the generated token to connect to your LiveKit -server. This app is built with our [React SDK](https://github.com/livekit/livekit-react). +Head over to our [example app](https://example.livekit.io) and enter a generated token to connect to your LiveKit server. This app is built with our [React SDK](https://github.com/livekit/livekit-react). -Once connected, your video and audio are now published to your new LiveKit instance! +Once connected, your video and audio are now being published to your new LiveKit instance! -### Generating access tokens (JWT) - -To add more users to a room, you'll have to create a token for each -participant. [Learn more about access tokens](https://docs.livekit.io/guides/access-tokens/). - -`livekit-server` provides a convenient sub-command to create a development token. This token has an expiration of a -month, which is useful for development and testing, but not appropriate for production use. +### Simulating a test publisher ```shell -docker run --rm -e LIVEKIT_KEYS=": " \ - livekit/livekit-server create-join-token \ - --room "" \ - --identity "" +livekit-cli join-room \ + --url ws://localhost:7880 \ + --api-key devkey --api-secret secret \ + --room my-first-room --identity bot-user1 \ + --publish-demo ``` -## Deploying to server +This command publishes a looped demo video to a room. Due to how the video clip was encoded (keyframes every 3s), there's a slight delay before the browser has sufficient data to begin rendering frames. This is an artifact of the simulation. -Deployment Docs: https://docs.livekit.io/deploy/ +## Deploying to a server -### Single node server - -Use our deploy config generator to set up a single node deployment with automatic TLS termination and built-in TURN. - -It includes a cloud-init/setup script that's supported by most cloud environments. - -```shell -docker run --rm -it -v$PWD:/output livekit/generate -``` - -### Kubernetes - -We publish a [helm chart](https://github.com/livekit/livekit-helm) that helps you to set up a cluster with high -availability. For detailed instructions, see [Kubernetes guide](https://docs.livekit.io/deploy/kubernetes) - -### Testing your deployment - -Use the [connection tester](https://livekit.io/connection-test) to ensure your installation is set up properly for user -traffic. +Read our [deployment docs](https://docs.livekit.io/deploy/) for more information. ## Building from source Pre-requisites: -* Go 1.15+ is installed -* GOPATH/bin is in your PATH +- Go 1.15+ is installed +- GOPATH/bin is in your PATH Then run @@ -141,9 +241,8 @@ mage ## Contributing -We welcome your contributions to make LiveKit better! Please join us -[on Slack](http://livekit.io/join-slack) to discuss your ideas and/or -submit PRs. +We welcome your contributions toward improving LiveKit! Please join us +[on Slack](http://livekit.io/join-slack) to discuss your ideas and/or PRs. ## License diff --git a/install-livekit.sh b/install-livekit.sh new file mode 100755 index 000000000..84f534f66 --- /dev/null +++ b/install-livekit.sh @@ -0,0 +1,73 @@ +#!/usr/bin/env bash +# LiveKit install script for Linux + +set -u +set -o errtrace +set -o errexit +set -o pipefail + +REPO="livekit" +INSTALL_PATH="/usr/local/bin" + +log() { printf "%b\n" "$*"; } +abort() { + printf "%s\n" "$@" >&2 + exit 1 +} + +# returns the latest version according to GH +# i.e. 1.0.0 +get_latest_version() +{ + latest_version=$(curl -s https://api.github.com/repos/livekit/$REPO/releases/latest | grep -oP '"tarball_url": ".*/tarball/v\K([^/]*)(?=")') + printf "%s" "$latest_version" +} + +# Ensure bash is used +if [ -z "${BASH_VERSION:-}" ] +then + abort "This script requires bash" +fi + +# Check cURL is installed +if ! command -v curl >/dev/null +then + abort "cURL is required and is not found" +fi + +# OS check +OS="$(uname)" +if [[ "${OS}" == "Darwin" ]] +then + abort "Installer not supported on MacOS, please install using Homebrew." +elif [[ "${OS}" != "Linux" ]] +then + abort "Installer is only supported on Linux." +fi + +ARCH="$(/usr/bin/uname -m)" + +# fix arch on linux +if [[ "${ARCH}" == "aarch64" ]] +then + ARCH="arm64" +elif [[ "${ARCH}" == "x86_64" ]] +then + ARCH="amd64" +fi + +VERSION=$(get_latest_version) +ARCHIVE_URL="https://github.com/livekit/$REPO/releases/download/v${VERSION}/${REPO}_${VERSION}_linux_${ARCH}.tar.gz" + +# Ensure version follows SemVer +if ! [[ "${VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] +then + abort "Invalid version: ${VERSION}" +fi + +log "Installing ${REPO} ${VERSION}" +log "Downloading from ${ARCHIVE_URL}..." + +curl -s -L "${ARCHIVE_URL}" | tar xzf - -C "${INSTALL_PATH}" --wildcards --no-anchored "$REPO*" + +log "\nlivekit-server is installed to $INSTALL_PATH\n"