RobbyV2/selkies
1
0
Fork 0
mirror of https://github.com/selkies-project/selkies.git synced 2025-09-04 19:12:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Initial patching of repository links

Browse Source
This commit is contained in:
Seungmin Kim
2025-06-29 18:36:30 +09:00
parent fe21491c3e
commit 0b1c9eede5
23 changed files with 106 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.devcontainer/Dockerfile
View File

@@ -3,7 +3,7 @@ FROM mcr.microsoft.com/devcontainers/base:${IMAGE_TAG}
ARG DEBIAN_FRONTEND=noninteractive
# Install base Selkies-GStreamer dependencies
# Install base Selkies dependencies
RUN sudo apt-get update && sudo apt-get install --no-install-recommends -y \
python3-pip \
python3-dev \
@@ -58,8 +58,8 @@ RUN if { [ "$(grep '^ID=' /etc/os-release | cut -d= -f2 | tr -d '\"')" = "ubuntu
fi
# Download and extract latest GStreamer component
RUN cd /opt && SELKIES_VERSION=$(curl -fsSL "https://api.github.com/repos/selkies-project/selkies-gstreamer/releases/latest" | jq -r '.tag_name' | sed 's/[^0-9\.\-]*//g') && \
curl -fsSL "https://github.com/selkies-project/selkies-gstreamer/releases/download/v${SELKIES_VERSION}/selkies-gstreamer-v${SELKIES_VERSION}-$(grep '^ID=' /etc/os-release | cut -d= -f2 | tr -d '\"')$(grep '^VERSION_ID=' /etc/os-release | cut -d= -f2 | tr -d '\"').tar.gz" | sudo tar -xzf -
RUN cd /opt && SELKIES_VERSION=$(curl -fsSL "https://api.github.com/repos/selkies-project/selkies/releases/latest" | jq -r '.tag_name' | sed 's/[^0-9\.\-]*//g') && \
curl -fsSL "https://github.com/selkies-project/selkies/releases/download/v${SELKIES_VERSION}/selkies-gstreamer-v${SELKIES_VERSION}-$(grep '^ID=' /etc/os-release | cut -d= -f2 | tr -d '\"')$(grep '^VERSION_ID=' /etc/os-release | cut -d= -f2 | tr -d '\"').tar.gz" | sudo tar -xzf -
# Install development dependencies
ARG PIP_BREAK_SYSTEM_PACKAGES=1

6
.devcontainer/features/desktop-selkies/src/devcontainer-feature.json
View File

@@ -1,13 +1,13 @@
{
"name": "Selkies GStreamer",
"id": "selkies-gstreamer",
"name": "Selkies",
"id": "selkies",
"version": "1.0.0",
"description": "WebRTC Remote Desktop for Linux",
"options": {
"release": {
"type": "string",
"default": "latest",
"description": "The selkies-gstreamer release tag."
"description": "The selkies release tag."
},
"xserver": {
"type": "string",

14
.devcontainer/features/desktop-selkies/src/install.sh
View File

@@ -69,12 +69,12 @@ if { [ "$(grep '^ID=' /etc/os-release | cut -d= -f2 | tr -d '\"')" = "ubuntu" ]
SELKIES_RELEASE_TAG=${RELEASE}
if [ "${RELEASE}" = "latest" ]; then
# Automatically fetch the latest selkies-gstreamer version and install the components
SELKIES_RELEASE_TAG=$(curl -fsSL "https://api.github.com/repos/selkies-project/selkies-gstreamer/releases/latest" | jq -r '.tag_name' | sed 's/[^0-9\.\-]*//g')
# Automatically fetch the latest Selkies version and install the components
SELKIES_RELEASE_TAG=$(curl -fsSL "https://api.github.com/repos/selkies-project/selkies/releases/latest" | jq -r '.tag_name' | sed 's/[^0-9\.\-]*//g')
else
# Check for tagged release
if ! curl -fsSL -o /dev/null "https://api.github.com/repos/selkies-project/selkies-gstreamer/releases/tags/${RELEASE}"; then
echo "ERROR: could not find selkies-gstreamer release ${RELEASE}"
if ! curl -fsSL -o /dev/null "https://api.github.com/repos/selkies-project/selkies/releases/tags/${RELEASE}"; then
echo "ERROR: could not find Selkies release ${RELEASE}"
exit 1
fi
fi
@@ -82,9 +82,9 @@ fi
SELKIES_VERSION=${SELKIES_RELEASE_TAG:1}
cd /opt
curl -fsSL "https://github.com/selkies-project/selkies-gstreamer/releases/download/${SELKIES_RELEASE_TAG}/selkies-gstreamer-${SELKIES_RELEASE_TAG}-$(grep '^ID=' /etc/os-release | cut -d= -f2 | tr -d '\"')$(grep '^VERSION_ID=' /etc/os-release | cut -d= -f2 | tr -d '\"').tar.gz" | tar -xzf -
curl -O -fsSL "https://github.com/selkies-project/selkies-gstreamer/releases/download/${SELKIES_RELEASE_TAG}/selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl" && PIP_BREAK_SYSTEM_PACKAGES=1 pip3 install --no-cache-dir "selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl" && rm -f "selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl"
curl -fsSL "https://github.com/selkies-project/selkies-gstreamer/releases/download/${SELKIES_RELEASE_TAG}/selkies-gstreamer-web-${SELKIES_RELEASE_TAG}.tar.gz" | tar -xzf -
curl -fsSL "https://github.com/selkies-project/selkies/releases/download/${SELKIES_RELEASE_TAG}/selkies-gstreamer-${SELKIES_RELEASE_TAG}-$(grep '^ID=' /etc/os-release | cut -d= -f2 | tr -d '\"')$(grep '^VERSION_ID=' /etc/os-release | cut -d= -f2 | tr -d '\"').tar.gz" | tar -xzf -
curl -O -fsSL "https://github.com/selkies-project/selkies/releases/download/${SELKIES_RELEASE_TAG}/selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl" && PIP_BREAK_SYSTEM_PACKAGES=1 pip3 install --no-cache-dir "selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl" && rm -f "selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl"
curl -fsSL "https://github.com/selkies-project/selkies/releases/download/${SELKIES_RELEASE_TAG}/selkies-gstreamer-web-${SELKIES_RELEASE_TAG}.tar.gz" | tar -xzf -
mkdir -pm755 /etc/OpenCL/vendors && echo "libnvidia-opencl.so.1" > /etc/OpenCL/vendors/nvidia.icd

6
.devcontainer/features/desktop-selkies/src/start-selkies.sh
View File

@@ -6,7 +6,7 @@ SCRIPT_DIR=$(dirname $(readlink -f $0))
function cleanup() {
kill -9 $(pidof turnserver) 1>/dev/null 2>&1|| true
pgrep -af '.*selkies-gstreamer.*' | cut -d' ' -f1 | xargs kill -9 1>/dev/null 2>&1|| true
pgrep -af '.*selkies.*' | cut -d' ' -f1 | xargs kill -9 1>/dev/null 2>&1|| true
pgrep -afi '.*xfce4.*' | cut -d' ' -f1 | xargs kill -9 1>/dev/null 2>&1|| true
pgrep -afi '.*fluxbox.*' | cut -d' ' -f1 | xargs kill -9 1>/dev/null 2>&1|| true
sudo /usr/bin/pulseaudio -k 1>/dev/null 2>&1 || true
@@ -67,8 +67,8 @@ esac
${SCRIPT_DIR}/start-turnserver.sh &
# Start Selkies
selkies-gstreamer-resize 1920x1080
selkies-gstreamer \
selkies-resize 1920x1080
selkies \
--addr="0.0.0.0" \
--port="${WEB_PORT:-6080}" \
--metrics_port=${SELKIES_METRICS_PORT:-19090} \

2
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@@ -50,7 +50,7 @@ Add any other context about the problem here.
- [ ] I confirm that the authors of this issue does not willfully breach or infringe legal regulations, in any and all global law, regarding trademarks, trade names, logos, patents, or any and all other forms of external intellectual property, as well as adhering to software license terms of open-source and proprietary software projects.
<!--
- ALL BUGS: upload the output log from Selkies-GStreamer regardless of whether the bug is caused by the web browser or the host. Read the error. If you are using `docker-*-desktop` container, upload all log files in `/tmp`.
- ALL BUGS: upload the output log from Selkies regardless of whether the bug is caused by the web browser or the host. Read the error. If you are using `docker-*-desktop` container, upload all log files in `/tmp`.
- If the issue relates to `ximagesrc` and therefore screen capture, upload the Xorg.*.log (such as `/var/log/Xorg.0.log` or `~/.local/share/xorg/Xorg.0.log`).
- If the issue relates to `webrtcbin` or the web browser, upload contents (or the JSON dump) of `chrome://webrtc-internals` and check in the browser console (F12) to see if there are any errors or warnings. In the browser console, check that the codec is supported in the web browser with `console.log(RTCRtpReceiver.getCapabilities('video').codecs)` or `console.log(RTCRtpReceiver.getCapabilities('audio').codecs)` after putting in `allow pasting`.
- Check your TURN server configuration and see if it is valid and connectable. In case the ISP throttles a certain protocol, try turning on TURN over TCP and/or TURN over TLS.

6
.vscode/tasks.json vendored
View File

@@ -28,7 +28,7 @@
"problemMatcher": []
},
{
"label": "[run] Start selkies-gstreamer",
"label": "[run] Start Selkies",
"type": "shell",
"command": "${workspaceFolder}/.devcontainer/features/desktop-selkies/src/start-selkies.sh",
"problemMatcher": [],
@@ -39,14 +39,14 @@
}
},
{
"label": "[run] re-build, re-install and run selkies-gstreamer",
"label": "[run] re-build, re-install and run Selkies",
"problemMatcher": [],
"dependsOrder": "sequence",
"dependsOn": [
"[build] build joystick interposer library",
"[build] build python package",
"[install] re-install python package",
"[run] Start selkies-gstreamer"
"[run] Start Selkies"
]
},
{

2
Dockerfile
View File

@@ -17,7 +17,7 @@ WORKDIR /opt/pypi
COPY src ./src
COPY README.md pyproject.toml ./
ARG PYPI_PACKAGE=selkies-gstreamer
ARG PYPI_PACKAGE=selkies
ARG PACKAGE_VERSION=0.0.0.dev0
# Patch the package name and version

8
README.md
View File

@@ -1,6 +1,6 @@
![Selkies WebRTC](/docs/assets/logo/horizontal-480.png)
[![Build](https://github.com/selkies-project/selkies-gstreamer/actions/workflows/build_and_publish_all_images.yaml/badge.svg)](https://github.com/selkies-project/selkies-gstreamer/actions/workflows/build_and_publish_all_images.yaml)
[![Build](https://github.com/selkies-project/selkies/actions/workflows/build_and_publish_all_images.yaml/badge.svg)](https://github.com/selkies-project/selkies/actions/workflows/build_and_publish_all_images.yaml)
[![Discord](https://img.shields.io/badge/dynamic/json?logo=discord&label=Discord%20Members&query=approximate_member_count&url=https%3A%2F%2Fdiscordapp.com%2Fapi%2Finvites%2FwDNGDeSW5F%3Fwith_counts%3Dtrue)](https://discord.gg/wDNGDeSW5F)
@@ -8,10 +8,10 @@
**We are in need of maintainers and community contributors. Please consider stepping up, as we can never have too much help!**
Selkies-GStreamer is an open-source low-latency high-performance Linux-native GPU/CPU-accelerated WebRTC HTML5 remote desktop streaming platform, for self-hosting, containers, Kubernetes, or Cloud/HPC platforms, [started out first by Google engineers](https://web.archive.org/web/20210310083658/https://cloud.google.com/solutions/gpu-accelerated-streaming-using-webrtc), then expanded by academic researchers.
Selkies is an open-source low-latency high-performance Linux-native GPU/CPU-accelerated WebRTC HTML5 remote desktop streaming platform, for self-hosting, containers, Kubernetes, or Cloud/HPC platforms, [started out first by Google engineers](https://web.archive.org/web/20210310083658/https://cloud.google.com/solutions/gpu-accelerated-streaming-using-webrtc), then expanded by academic researchers.
Selkies-GStreamer is designed for researchers studying Agentic AI, Graphical AI, Robotics, Autonomous Driving, Drug Discovery technologies, SLURM supercomputer or HPC system administrators, Jupyter, Kubernetes, Docker®, Coder infrastructure administrators, and Linux cloud gaming enthusiasts.
Selkies is designed for researchers studying Agentic AI, Graphical AI, Robotics, Autonomous Driving, Drug Discovery technologies, SLURM supercomputer or HPC system administrators, Jupyter, Kubernetes, Docker®, Coder infrastructure administrators, and Linux cloud gaming enthusiasts.
While designed for clustered or unprivileged containerized environments, Selkies-GStreamer can also be deployed in desktop computers, and any performance issue that would be problematic in cloud gaming platforms is also considered a bug.
While designed for clustered or unprivileged containerized environments, Selkies can also be deployed in desktop computers, and any performance issue that would be problematic in cloud gaming platforms is also considered a bug.
**[Read the Documentation](https://selkies-project.github.io/selkies/) to get started.**

2
addons/gst-web/src/index.html
View File

@@ -318,7 +318,7 @@
<li>Fullscreen: Ctrl + Shift + F or Fullscreen Button</li>
<li>Remote (Game) Cursor Lock: Ctrl + Shift + LeftClick</li>
<li>Open Side Menu: Ctrl + Shift + M or Side Button</li>
<li><a style="color:inherit;text-decoration:none" target="_blank" rel="noopener noreferrer" href="https://github.com/selkies-project/selkies-gstreamer/blob/main/README.md#citations-in-academic-publications"><b>Please cite within your publication for academic usage</b></a></li>
<li><a style="color:inherit;text-decoration:none" target="_blank" rel="noopener noreferrer" href="https://github.com/selkies-project/selkies/blob/main/docs/README.md#citations-in-academic-publications"><b>Please cite within your publication for academic usage</b></a></li>
</ul>
</small>
</p>

4
addons/js-interposer/README.md
View File

@@ -2,7 +2,7 @@
An `LD_PRELOAD` library for interposing application calls to open a Linux joystick/gamepad device and pass data through a unix domain socket.
This allows the Selkies-GStreamer WebRTC interface to pass gamepad events over the WebRTC `RTCDataChannel`, and translate them to joystick/gamepad events to emulate devices without requiring access to /dev/input/js0 or depending on kernel modules including `uinput`.
This allows the Selkies remote desktop application interface to pass gamepad events over the WebRTC `RTCDataChannel` or WebSockets, and translate them to joystick/gamepad events to emulate devices without requiring access to /dev/input/js0 or depending on kernel modules including `uinput`.
## Compiling
@@ -26,7 +26,7 @@ sudo touch /dev/input/js0 /dev/input/js1 /dev/input/js2 /dev/input/js3
sudo chmod 777 /dev/input/js*
```
3. Use the below command before running your target application as well as Selkies-GStreamer for the interposer library to intercept joystick/gamepad events (the single quotes are required in the first line).
3. Use the below command before running your target application as well as Selkies for the interposer library to intercept joystick/gamepad events (the single quotes are required in the first line).
```bash
export SELKIES_INTERPOSER='/usr/$LIB/selkies_joystick_interposer.so'

2
addons/js-interposer/build_deb.sh
View File

@@ -28,7 +28,7 @@ Architecture: $(dpkg --print-architecture)
Essential: no
Installed-Size: ${PKG_SIZE?missing env}
Maintainer: ${DEBFULLNAME?missing env} <${DEBEMAIL?missing env}>
Description: Joystick device interposer for Selkies-GStreamer project
Description: Joystick device interposer for Selkies project
EOF
dpkg-deb --build ${PKG_DIR}

2
addons/selkies-dashboard-zinc/src/components/dashboard/shortcuts-menu.tsx
View File

@@ -24,7 +24,7 @@ const ShortcutsMenu = () => {
className="text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-300"
target="_blank"
rel="noopener noreferrer"
href="https://github.com/selkies-project/selkies-gstreamer/blob/main/README.md#citations-in-academic-publications"
href="https://github.com/selkies-project/selkies/blob/main/docs/README.md#citations-in-academic-publications"
>
<b>Please cite within your publication for academic usage</b>
</a>

2
addons/selkies-dashboard-zinc/src/components/dashboard/side-menu.tsx
View File

@@ -257,7 +257,7 @@ export function MenuComponent({ isGamepadEnabled, onGamepadToggle }) {
const renderMenuFooter = () => (
<div className="border-t p-2">
<div className="flex items-center justify-between">
<a href="https://github.com/selkies-project/selkies-gstreamer" target="_blank" rel="noopener noreferrer">
<a href="https://github.com/selkies-project/selkies" target="_blank" rel="noopener noreferrer">
<img
src="/horizontal.png"
alt="footer Logo"

6
docs/README.md
View File

@@ -5,7 +5,7 @@ hide:
---
![Selkies WebRTC](assets/logo/horizontal-480.png)
[![Build](https://github.com/selkies-project/selkies-gstreamer/actions/workflows/build_and_publish_all_images.yaml/badge.svg)](https://github.com/selkies-project/selkies-gstreamer/actions/workflows/build_and_publish_all_images.yaml)
[![Build](https://github.com/selkies-project/selkies/actions/workflows/build_and_publish_all_images.yaml/badge.svg)](https://github.com/selkies-project/selkies/actions/workflows/build_and_publish_all_images.yaml)
[![Discord](https://img.shields.io/badge/dynamic/json?logo=discord&label=Discord%20Members&query=approximate_member_count&url=https%3A%2F%2Fdiscordapp.com%2Fapi%2Finvites%2FwDNGDeSW5F%3Fwith_counts%3Dtrue)](https://discord.gg/wDNGDeSW5F)
@@ -19,7 +19,7 @@ Selkies-GStreamer is designed for researchers, including people in the graphical
While designed for clustered or unprivileged containerized environments, Selkies-GStreamer can also be deployed in desktop computers, and any performance issue that would be problematic in cloud gaming platforms is also considered a bug.
**Please read [Troubleshooting and FAQs](faq.md) first, then use [Discord](https://discord.gg/wDNGDeSW5F) or [GitHub Discussions](https://github.com/selkies-project/selkies-gstreamer/discussions) for support questions. Please only use [Issues](https://github.com/selkies-project/selkies-gstreamer/issues) for technical inquiries or bug reports.**
**Please read [Troubleshooting and FAQs](faq.md) first, then use [Discord](https://discord.gg/wDNGDeSW5F) or [GitHub Discussions](https://github.com/selkies-project/selkies/discussions) for support questions. Please only use [Issues](https://github.com/selkies-project/selkies/issues) for technical inquiries or bug reports.**
**NOTE: this project is licensed under the [Mozilla Public License, version 2.0](https://www.mozilla.org/en-US/MPL/2.0/FAQ/), which obliges to share modified code files licensed by MPL-2.0 when distributed externally, but does not apply for any larger work outside this project, which might be open-source or proprietary under any license of choice. Externally originated components outside this project may contain works licensed over more restrictive copyleft/proprietary licenses, as well as other terms of intellectual property, including but not limited to patents, which users or developers are obliged to adhere to.**
@@ -53,7 +53,7 @@ Therefore, we kindly, but strongly ask all software projects which are applying
(Please note that this is currently a placeholder, an upcoming publication will be available after article review.)
`Kim, S., Isla, D., Hejtmánek, L., et al., Selkies-GStreamer, (2024), GitHub repository, https://github.com/selkies-project/selkies-gstreamer`
`Kim, S., Isla, D., Hejtmánek, L., et al., Selkies-GStreamer, (2024), GitHub repository, https://github.com/selkies-project/selkies`
**Maintainers of derivative open-source projects should also place this text in a clearly visible location of your project.**

66
docs/component.md
View File

@@ -2,14 +2,14 @@
## Component Structure
Selkies-GStreamer is composed of various mandatory and optional components.
Selkies is composed of various mandatory and optional components.
**Refer to [Getting Started](start.md) on how you can get on board.**
Use the following commands to retrieve the latest `SELKIES_VERSION` release, the current Ubuntu `DISTRIB_RELEASE`, and the current architecture `ARCH` in the next sections:
```bash
export SELKIES_VERSION="$(curl -fsSL "https://api.github.com/repos/selkies-project/selkies-gstreamer/releases/latest" | jq -r '.tag_name' | sed 's/[^0-9\.\-]*//g')"
export SELKIES_VERSION="$(curl -fsSL "https://api.github.com/repos/selkies-project/selkies/releases/latest" | jq -r '.tag_name' | sed 's/[^0-9\.\-]*//g')"
export DISTRIB_RELEASE="$(grep '^VERSION_ID=' /etc/os-release | cut -d= -f2 | tr -d '\"')"
export ARCH="$(dpkg --print-architecture)"
```
@@ -22,21 +22,21 @@ docker run --rm --privileged tonistiigi/binfmt:latest --install all
### Mandatory Components
There are currently three mandatory components in Selkies-GStreamer.
There are currently three mandatory components in Selkies.
All mandatory components are available for download from the [Releases](https://github.com/selkies-project/selkies-gstreamer/releases) for the latest stable version.
All mandatory components are available for download from the [Releases](https://github.com/selkies-project/selkies/releases) for the latest stable version.
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies-gstreamer/actions) `Build & publish all images` Build Artifacts (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch. Build Artifacts can also be downloaded using the [GitHub CLI](https://cli.github.com) command [`gh run download`](https://cli.github.com/manual/gh_run_download).
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies/actions) `Build & publish all images` Build Artifacts (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch. Build Artifacts can also be downloaded using the [GitHub CLI](https://cli.github.com) command [`gh run download`](https://cli.github.com/manual/gh_run_download).
#### Conda Toolchain
Our [reference portable distribution toolchain](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/conda) is compiled with the distribution-neutral [Conda](https://conda-forge.org) build toolchain, distributing all three mandatory components as well as portable versions of most dependencies in a tarball.
Our [reference portable distribution toolchain](https://github.com/selkies-project/selkies/tree/main/addons/conda) is compiled with the distribution-neutral [Conda](https://conda-forge.org) build toolchain, distributing all three mandatory components as well as portable versions of most dependencies in a tarball.
Pre-built `x86_64` portable distributions for **any Linux distribution with `glibc ≥ 2.17`** (CentOS 7 or newer) are available with the name **`selkies-gstreamer-portable-v${SELKIES_VERSION}_amd64.tar.gz`** for download in the [Releases](https://github.com/selkies-project/selkies-gstreamer/releases) for the latest stable version.
Pre-built `x86_64` portable distributions for **any Linux distribution with `glibc ≥ 2.17`** (CentOS 7 or newer) are available with the name **`selkies-gstreamer-portable-v${SELKIES_VERSION}_amd64.tar.gz`** for download in the [Releases](https://github.com/selkies-project/selkies/releases) for the latest stable version.
**Instructions from [Quick Start](start.md#quick-start) still apply below.**
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies-gstreamer/actions) `Build & publish all images` **`conda_linux-amd64`** Build Artifact (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch.
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies/actions) `Build & publish all images` **`conda_linux-amd64`** Build Artifact (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch.
Alternatively, copy the pre-built `x86_64` portable distribution build from the container image (use your own directory other than `/opt`, change `main` with `latest` for the latest stable release):
@@ -53,17 +53,17 @@ Otherwise (for different system architectures), you can build your own portable
#### Python Application
The term `host` or `server` refers to the [Python Components](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer) across this documentation.
The term `host` or `server` refers to the [Python Components](https://github.com/selkies-project/selkies/tree/main/src/selkies_gstreamer) across this documentation.
The [Python Components](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer) are responsible for the host server backend, capturing and encoding the host screen and audio, receiving input signals and communicating other data (including the clipboard) between the client and the host, and establishing the WebRTC (with RTP underneath) connection to the client.
The [Python Components](https://github.com/selkies-project/selkies/tree/main/src/selkies_gstreamer) are responsible for the host server backend, capturing and encoding the host screen and audio, receiving input signals and communicating other data (including the clipboard) between the client and the host, and establishing the WebRTC (with RTP underneath) connection to the client.
Host screen video and audio are transported using the WebRTC `MediaStream` interface, and other data are transported using the WebRTC `DataChannel` interface.
The architecture-independent components are available with the name **`selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl`** for download in the [Releases](https://github.com/selkies-project/selkies-gstreamer/releases) for the latest stable version.
The architecture-independent components are available with the name **`selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl`** for download in the [Releases](https://github.com/selkies-project/selkies/releases) for the latest stable version.
**Instructions from [Advanced Install](start.md#advanced-install) still apply below.**
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies-gstreamer/actions) `Build & publish all images` **`py-build_linux-amd64`** Build Artifact (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch.
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies/actions) `Build & publish all images` **`py-build_linux-amd64`** Build Artifact (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch.
Alternatively, copy the Python Wheel file from the build container image (DO NOT change the platform in non-`x86_64` architectures, install [binfmt](https://github.com/tonistiigi/binfmt) instead, and change `main` with `latest` for the latest stable release):
@@ -80,7 +80,7 @@ selkies-gstreamer --addr=0.0.0.0 --port=8080 --enable_https=false --https_cert=/
One other alternative way to install the Python application components from the most recent unreleased commit:
```bash
git clone https://github.com/selkies-project/selkies-gstreamer.git
git clone https://github.com/selkies-project/selkies.git
cd selkies-gstreamer
sudo PIP_BREAK_SYSTEM_PACKAGES=1 pip3 install --no-cache-dir --force-reinstall .
# Run Selkies-GStreamer Python executable after all components are installed
@@ -89,9 +89,9 @@ selkies-gstreamer --addr=0.0.0.0 --port=8080 --enable_https=false --https_cert=/
#### Web Application
The term `client` refers to the [Web Components](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gst-web) across this documentation.
The term `client` refers to the [Web Components](https://github.com/selkies-project/selkies/tree/main/addons/gst-web) across this documentation.
The [Web Components](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gst-web) are responsible the web browser interface that you see when you use Selkies-GStreamer.
The [Web Components](https://github.com/selkies-project/selkies/tree/main/addons/gst-web) are responsible the web browser interface that you see when you use Selkies-GStreamer.
They receive and display the received screen and audio within the web browser, detect input signal and other data (including the clipboard) from the user, then send them to the host server backend.
@@ -99,11 +99,11 @@ They also handle remote cursors with the Pointer Lock API that allows you to cor
WebRTC enables web browser clients to decode the stream using GPU hardware acceleration, as well as GPU-accelerated stream encoding from the host.
The architecture-independent components are available with the name **`selkies-gstreamer-web_v${SELKIES_VERSION}.tar.gz`** for download in the [Releases](https://github.com/selkies-project/selkies-gstreamer/releases) for the latest stable version.
The architecture-independent components are available with the name **`selkies-gstreamer-web_v${SELKIES_VERSION}.tar.gz`** for download in the [Releases](https://github.com/selkies-project/selkies/releases) for the latest stable version.
**Instructions from [Advanced Install](start.md#advanced-install) still apply below.**
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies-gstreamer/actions) `Build & publish all images` **`gst-web_linux-amd64`** Build Artifact (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch.
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies/actions) `Build & publish all images` **`gst-web_linux-amd64`** Build Artifact (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch.
Alternatively, install the web interface components to the container image (DO NOT change the platform in non-`x86_64` architectures, install [binfmt](https://github.com/tonistiigi/binfmt) instead, and change `main` with `latest` for the latest stable release):
@@ -116,7 +116,7 @@ docker rm gst-web
One other alternative way to install the web interface components from the most recent unreleased commit (replace `INSTALL_DIR=/opt/gst-web` with your own directory):
```bash
git clone https://github.com/selkies-project/selkies-gstreamer.git
git clone https://github.com/selkies-project/selkies.git
cd selkies-gstreamer/addons/gst-web
sudo INSTALL_DIR=/opt/gst-web ./install.sh
```
@@ -125,13 +125,13 @@ sudo INSTALL_DIR=/opt/gst-web ./install.sh
[GStreamer](https://gstreamer.freedesktop.org) "is a library for constructing graphs of media-handling components. The applications it supports range from simple Ogg/Vorbis playback, audio/video streaming to complex audio (mixing) and video (non-linear editing) processing." GStreamer is likely inside your smart TV, car infotainment system, or the digital street signage or surveillance camera near you, as well as many media players and video editing software.
GStreamer is responsible for the actual heavy lifting of Selkies-GStreamer, starting from capturing and encoding the host screen and audio to transporting the stream and other data between the host and the client web browser using WebRTC. GStreamer can be installed from your Linux distribution (but the required newest version may not be available), be [built for your distribution](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gstreamer), or be compiled and distributed in portable form with [Conda](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/conda).
GStreamer is responsible for the actual heavy lifting of Selkies-GStreamer, starting from capturing and encoding the host screen and audio to transporting the stream and other data between the host and the client web browser using WebRTC. GStreamer can be installed from your Linux distribution (but the required newest version may not be available), be [built for your distribution](https://github.com/selkies-project/selkies/tree/main/addons/gstreamer), or be compiled and distributed in portable form with [Conda](https://github.com/selkies-project/selkies/tree/main/addons/conda).
Check [GStreamer Components](#gstreamer-components) for more details.
Pre-built `x86_64` GStreamer components for Ubuntu are available with the name (fill in the OS version `DISTRIB_RELEASE` such as `24.04`, `22.04`) **`gstreamer-selkies_gpl_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_amd64.tar.gz`** for download in the [Releases](https://github.com/selkies-project/selkies-gstreamer/releases) for the latest stable version.
Pre-built `x86_64` GStreamer components for Ubuntu are available with the name (fill in the OS version `DISTRIB_RELEASE` such as `24.04`, `22.04`) **`gstreamer-selkies_gpl_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_amd64.tar.gz`** for download in the [Releases](https://github.com/selkies-project/selkies/releases) for the latest stable version.
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies-gstreamer/actions) `Build & publish all images` **`gstreamer-ubuntu${DISTRIB_RELEASE}_linux-amd64`** Build Artifact (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch.
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies/actions) `Build & publish all images` **`gstreamer-ubuntu${DISTRIB_RELEASE}_linux-amd64`** Build Artifact (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch.
**Instructions from [Advanced Install](start.md#advanced-install) still apply below.**
@@ -153,13 +153,13 @@ These components are not required for Selkies-GStreamer, but may be required in
#### Joystick Interposer
The [Joystick Interposer](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/js-interposer) is a special library that allows the usage of joysticks or gamepads inside unprivileged containers (most of the occasions with shared Kubernetes clusters or HPC clusters), where host kernel devices required for creating a joystick interface are not available. It uses a `LD_PRELOAD` hack to intercept `uinput` input commands from joysticks or gamepads into Selkies-GStreamer (much like how [VirtualGL](https://github.com/VirtualGL/virtualgl) intercepts OpenGL commands).
The [Joystick Interposer](https://github.com/selkies-project/selkies/tree/main/addons/js-interposer) is a special library that allows the usage of joysticks or gamepads inside unprivileged containers (most of the occasions with shared Kubernetes clusters or HPC clusters), where host kernel devices required for creating a joystick interface are not available. It uses a `LD_PRELOAD` hack to intercept `uinput` input commands from joysticks or gamepads into Selkies-GStreamer (much like how [VirtualGL](https://github.com/VirtualGL/virtualgl) intercepts OpenGL commands).
Pre-built `x86_64` and `aarch64` joystick interposer components for Ubuntu are available with the name (fill in the OS version `DISTRIB_RELEASE` such as `24.04`, `22.04`, Ubuntu-style architecture `ARCH` such as `amd64` and `arm64`) **`selkies-js-interposer_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_${ARCH}.tar.gz`** or **`selkies-js-interposer_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_${ARCH}.deb`** for download in the [Releases](https://github.com/selkies-project/selkies-gstreamer/releases) for the latest stable version.
Pre-built `x86_64` and `aarch64` joystick interposer components for Ubuntu are available with the name (fill in the OS version `DISTRIB_RELEASE` such as `24.04`, `22.04`, Ubuntu-style architecture `ARCH` such as `amd64` and `arm64`) **`selkies-js-interposer_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_${ARCH}.tar.gz`** or **`selkies-js-interposer_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_${ARCH}.deb`** for download in the [Releases](https://github.com/selkies-project/selkies/releases) for the latest stable version.
**Instructions from [Advanced Install](start.md#advanced-install) still apply below.**
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies-gstreamer/actions) `Build & publish all images` **`js-interposer-ubuntu${DISTRIB_RELEASE}-tar.gz_linux-${ARCH}`** or **`js-interposer-ubuntu${DISTRIB_RELEASE}-deb_linux-${ARCH}`** Build Artifact (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch.
For the most recent unreleased commit, download from the [GitHub Actions Workflow Runs](https://github.com/selkies-project/selkies/actions) `Build & publish all images` **`js-interposer-ubuntu${DISTRIB_RELEASE}-tar.gz_linux-${ARCH}`** or **`js-interposer-ubuntu${DISTRIB_RELEASE}-deb_linux-${ARCH}`** Build Artifact (under `Artifacts (Produced during runtime)`) for each commit from the `main` branch.
Alternatively, copy and install the pre-built Joystick Interposer build (change `--platform=` to `linux/arm64` for `aarch64`, and change `main` with `latest` and `0.0.0` to the release version for the latest stable release):
@@ -199,7 +199,7 @@ export SDL_JOYSTICK_DEVICE=/dev/input/js0
You can replace `/usr/$LIB/selkies_joystick_interposer.so` with any non-root path of your choice if using the `.tar.gz` tarball.
Check the [Joystick Interposer README.md](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/js-interposer/README.md) documentation for usage instruction and compiling information on other platforms.
Check the [Joystick Interposer README.md](https://github.com/selkies-project/selkies/tree/main/addons/js-interposer/README.md) documentation for usage instruction and compiling information on other platforms.
Check the following links for explanations of similar, but different attempts, for reference:
@@ -215,11 +215,11 @@ Check the following links for explanations of similar, but different attempts, f
#### Example Container
The [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) is the reference minimal-functionality container developers can base upon, or test Selkies-GStreamer quickly. The bare minimum Xfce4 desktop environment is installed together with Firefox, as well as an embedded TURN server inside the container for quick WebRTC firewall traversal.
The [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example) is the reference minimal-functionality container developers can base upon, or test Selkies-GStreamer quickly. The bare minimum Xfce4 desktop environment is installed together with Firefox, as well as an embedded TURN server inside the container for quick WebRTC firewall traversal.
Read the [Development](development.md) section for customizing this container for your own usage.
Run the Docker®/Podman container built from the [`Example Dockerfile`](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example/Dockerfile), then connect to port **8080** of your Docker®/Podman host to access the web interface (Username: **`ubuntu`**, Password: **`mypasswd`**, **change `DISTRIB_RELEASE` to `24.04`, `22.04`, or `20.04`, and replace `main` to `latest` for the latest stable release**):
Run the Docker®/Podman container built from the [`Example Dockerfile`](https://github.com/selkies-project/selkies/tree/main/addons/example/Dockerfile), then connect to port **8080** of your Docker®/Podman host to access the web interface (Username: **`ubuntu`**, Password: **`mypasswd`**, **change `DISTRIB_RELEASE` to `24.04`, `22.04`, or `20.04`, and replace `main` to `latest` for the latest stable release**):
```bash
docker run --name selkies -it -d --rm -e SELKIES_TURN_PROTOCOL=udp -e SELKIES_TURN_PORT=3478 -e TURN_MIN_PORT=65534 -e TURN_MAX_PORT=65535 -p 8080:8080 -p 3478:3478 -p 3478:3478/udp -p 65534-65535:65534-65535 -p 65534-65535:65534-65535/udp ghcr.io/selkies-project/selkies-gstreamer/gst-py-example:main-ubuntu${DISTRIB_RELEASE}
@@ -243,9 +243,9 @@ If you are behind a reverse proxy or can only expose one HTTP port, you will nee
>
> [Pion TURN](https://github.com/pion/turn)'s `turn-server-simple` executable or [eturnal](https://eturnal.net) are recommended alternative TURN server implementations that support Windows as well as Linux or MacOS. [STUNner](https://github.com/l7mp/stunner) is a Kubernetes native STUN and TURN deployment if Helm is possible to be used.
The [coTURN Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/coturn) is a reference container which provides the [coTURN](https://github.com/coturn/coturn) TURN server. Other than options including `-e TURN_SHARED_SECRET=`, `-e TURN_REALM=`, `-e TURN_PORT=`, `-e TURN_MIN_PORT=` (at least `49152`), and `-e TURN_MAX_PORT=` (at most `65535`), add more command-line options in `-e TURN_EXTRA_ARGS=`.
The [coTURN Container](https://github.com/selkies-project/selkies/tree/main/addons/coturn) is a reference container which provides the [coTURN](https://github.com/coturn/coturn) TURN server. Other than options including `-e TURN_SHARED_SECRET=`, `-e TURN_REALM=`, `-e TURN_PORT=`, `-e TURN_MIN_PORT=` (at least `49152`), and `-e TURN_MAX_PORT=` (at most `65535`), add more command-line options in `-e TURN_EXTRA_ARGS=`.
Run the Docker®/Podman container built from the [`coTURN Dockerfile`](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/coturn/Dockerfile) (**replace `main` to `latest` for the latest stable release**):
Run the Docker®/Podman container built from the [`coTURN Dockerfile`](https://github.com/selkies-project/selkies/tree/main/addons/coturn/Dockerfile) (**replace `main` to `latest` for the latest stable release**):
```bash
docker run --name coturn -it -d --rm -e TURN_SHARED_SECRET=n0TaRealCoTURNAuthSecretThatIsSixtyFourLengthsLongPlaceholdPlace -e TURN_REALM=example.com -e TURN_PORT=3478 -e TURN_MIN_PORT=65500 -e TURN_MAX_PORT=65535 -p 3478:3478 -p 3478:3478/udp -p 65500-65535:65500-65535 -p 65500-65535:65500-65535/udp ghcr.io/selkies-project/selkies-gstreamer/coturn:main
@@ -273,19 +273,19 @@ In easier words, if both the host and client are behind restrictive firewalls, t
The recommended multi-user TURN server authentication mechanism is the [time-limited short-term credential/TURN REST API mechanism](https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00), where there is a single [shared secret](https://github.com/coturn/coturn/blob/master/README.turnserver) that is never exposed externally (only the TURN-REST Container and the coTURN TURN server know), but instead authenticates WebRTC clients (which are Selkies-GStreamer hosts and clients) based on generated credentials which are valid for only a short time (typically 24 hours).
The [TURN-REST Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/turn-rest) is an easy way to distribute short-term TURN server authentication credentials and the information of the TURN server based on the REST API to many Selkies-GStreamer host instances, particularly when behind a local area network (LAN), which may or may not have restricted firewalls.
The [TURN-REST Container](https://github.com/selkies-project/selkies/tree/main/addons/turn-rest) is an easy way to distribute short-term TURN server authentication credentials and the information of the TURN server based on the REST API to many Selkies-GStreamer host instances, particularly when behind a local area network (LAN), which may or may not have restricted firewalls.
Using the `selkies-gstreamer --turn_rest_uri=` option or `SELKIES_TURN_REST_URI` environment variable, the Selkies-GStreamer host periodically queries a URI such as `https://turn-rest.myinfrastructure.io/myturnrest` or `http://192.168.0.10/myturnrest`.
This URI is ideally behind a local area network (LAN) inaccessible from the outside and only accessible to the Python hosts inside the LAN, or alternatively behind authentication using any web server or reverse proxy, if accessible from the outside. This information is periodically sent to the web client (that is also preferably behind authentication with HTTP Basic Authentication or a web server/reverse proxy) through HTTP(S), thus the TURN server information and credentials being propagated to both the Python host and the web client without exposing the TURN server information outside.
Because the time-limited TURN credentials automatically expire after some time, they are not useful even if they are leaked outside, as long as the pathway to the air-gapped or authenticated TURN-REST Container REST HTTP endpoint is not exposed plainly to the internet. [app.py](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/turn-rest/app.py) may also be hosted standalone without a container using the same startup command in the [Dockerfile](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/turn-rest/Dockerfile).
Because the time-limited TURN credentials automatically expire after some time, they are not useful even if they are leaked outside, as long as the pathway to the air-gapped or authenticated TURN-REST Container REST HTTP endpoint is not exposed plainly to the internet. [app.py](https://github.com/selkies-project/selkies/tree/main/addons/turn-rest/app.py) may also be hosted standalone without a container using the same startup command in the [Dockerfile](https://github.com/selkies-project/selkies/tree/main/addons/turn-rest/Dockerfile).
Other authentication methods such as TURN-REST over various types of REST API authentication (but adding support for TURN-REST behind Basic Authentication is trivial, so reach out with some funding) or TURN oAuth authentication are not supported as of now, and likely requires funding.
The TURN-REST Container (or similarly, Kubernetes Pod) should be triggered with the Docker®/Podman options `-e TURN_SHARED_SECRET=`, `-e TURN_HOST=`, `-e TURN_PORT=`, `-e TURN_PROTOCOL=`, `-e TURN_TLS=`, `-e STUN_HOST=`, `-e STUN_PORT=`, where the options are dependent on the TURN server configuration of [coTURN](#coturn) or other TURN server implementations.
Run the Docker®/Podman container built from the [`TURN-REST Dockerfile`](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/turn-rest/Dockerfile) (replace `main` to `latest` for the latest stable release**):
Run the Docker®/Podman container built from the [`TURN-REST Dockerfile`](https://github.com/selkies-project/selkies/tree/main/addons/turn-rest/Dockerfile) (replace `main` to `latest` for the latest stable release**):
```bash
docker run --name turn-rest -it -d --rm -e TURN_SHARED_SECRET=n0TaRealCoTURNAuthSecretThatIsSixtyFourLengthsLongPlaceholdPlace -e TURN_HOST=turn.myinfrastructure.io -e TURN_PORT=3478 -e TURN_PROTOCOL=udp -e TURN_TLS=false -p 8008:8008 ghcr.io/selkies-project/selkies-gstreamer/turn-rest:main
@@ -297,7 +297,7 @@ Consult the [WebRTC and Firewall Issues: TURN Server Authentication Methods](fir
#### coTURN-Web
The [coTURN-Web Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/coturn-web) is a legacy component meant to provide similar capabilities to the [TURN-REST Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/turn-rest) for the Google Kubernetes Engine, mostly old remnants from the Google era. This component may be phased out as well as the [`infra/gce`](https://github.com/selkies-project/selkies-gstreamer/tree/main/infra/gce) and [`infra/gke`](https://github.com/selkies-project/selkies-gstreamer/tree/main/infra/gke) components and `cloudbuild.yml` configurations in favor of platform-agnostic Kubernetes configurations. Contributions are welcome.
The [coTURN-Web Container](https://github.com/selkies-project/selkies/tree/main/addons/coturn-web) is a legacy component meant to provide similar capabilities to the [TURN-REST Container](https://github.com/selkies-project/selkies/tree/main/addons/turn-rest) for the Google Kubernetes Engine, mostly old remnants from the Google era. This component may be phased out as well as the [`infra/gce`](https://github.com/selkies-project/selkies/tree/main/infra/gce) and [`infra/gke`](https://github.com/selkies-project/selkies/tree/main/infra/gke) components and `cloudbuild.yml` configurations in favor of platform-agnostic Kubernetes configurations. Contributions are welcome.
## GStreamer Components

20
docs/development.md
View File

@@ -8,7 +8,7 @@ This project was meant to be built upon community contributions from people with
[GStreamer](https://gstreamer.freedesktop.org) is much easier to develop without prior experience on multimedia application development, and this project is a perfect starting point for anyone who wants to get started.
Please return your developments with a [Pull Request](https://github.com/selkies-project/selkies-gstreamer/pulls) if you made modifications to the code or added new features, especially if you use this project commercially (as per MPL-2.0 license obligations). We will be happy to help or consult if you are stuck.
Please return your developments with a [Pull Request](https://github.com/selkies-project/selkies/pulls) if you made modifications to the code or added new features, especially if you use this project commercially (as per MPL-2.0 license obligations). We will be happy to help or consult if you are stuck.
**NOTE: this project is licensed under the [Mozilla Public License, version 2.0](https://www.mozilla.org/en-US/MPL/2.0/FAQ/), which obliges to share modified code files licensed by MPL-2.0 when distributed externally, but does not apply for any larger work outside this project, which might be open-source or proprietary under any license of choice. Externally originated components outside this project may contain works licensed over more restrictive copyleft/proprietary licenses, as well as other terms of intellectual property, including but not limited to patents, which users or developers are obliged to adhere to.**
@@ -18,9 +18,9 @@ As the relatively permissive license compared to similar projects is for the ben
## Contributions
Please join our [Discord](https://discord.gg/wDNGDeSW5F) server, then start out with the [Issues](https://github.com/selkies-project/selkies-gstreamer/issues) to see if new enhancements that you can make or things that you want solved have been already raised.
Please join our [Discord](https://discord.gg/wDNGDeSW5F) server, then start out with the [Issues](https://github.com/selkies-project/selkies/issues) to see if new enhancements that you can make or things that you want solved have been already raised.
**No programming experience:** You can still be a tester or a community helper/moderator at [Discord](https://discord.gg/wDNGDeSW5F)! Do you see anything that feels uncomfortable compared to other projects? Raise an issue and suggest various improvements including to the documentation. Have you used OBS, FFmpeg, or any other live streaming/video editing software before? You can suggest optimized parameters for the video encoders from your experiences. You can experiment with various encoder parameters which are exposed in a very accessible way under [gstwebrtc_app.py](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer/gstwebrtc_app.py). You can add or modify properties exposed under the comment `ADD_ENCODER:` for each encoder, improving streaming performance.
**No programming experience:** You can still be a tester or a community helper/moderator at [Discord](https://discord.gg/wDNGDeSW5F)! Do you see anything that feels uncomfortable compared to other projects? Raise an issue and suggest various improvements including to the documentation. Have you used OBS, FFmpeg, or any other live streaming/video editing software before? You can suggest optimized parameters for the video encoders from your experiences. You can experiment with various encoder parameters which are exposed in a very accessible way under [gstwebrtc_app.py](https://github.com/selkies-project/selkies/tree/main/src/selkies_gstreamer/gstwebrtc_app.py). You can add or modify properties exposed under the comment `ADD_ENCODER:` for each encoder, improving streaming performance.
**Some Python or HTML/JavaScript frontend experience:** Our codebase and web interface always has room for improvement. Consider helping out on various issues or cleaning up the code otherwise.
@@ -90,7 +90,7 @@ This section is a knowledge base for code contributions and development.
## Resources
- **Our [Documentation](README.md) and [Issues](https://github.com/selkies-project/selkies-gstreamer/issues)/[Pull Requests](https://github.com/selkies-project/selkies-gstreamer/pulls)** (including closed Issues/Pull Requests) and <https://github.com/m1k1o/neko/issues/371>
- **Our [Documentation](README.md) and [Issues](https://github.com/selkies-project/selkies/issues)/[Pull Requests](https://github.com/selkies-project/selkies/pulls)** (including closed Issues/Pull Requests) and <https://github.com/m1k1o/neko/issues/371>
- GStreamer Repository (sources of truth are below, other repositories such as `gst-plugins-base` have been relocated to the below):
@@ -163,13 +163,13 @@ ENTRYPOINT ["/usr/bin/supervisord"]
## Container Guide
The [`docker-nvidia-glx-desktop`](https://github.com/selkies-project/docker-nvidia-glx-desktop)/[`docker-nvidia-egl-desktop`](https://github.com/selkies-project/docker-nvidia-egl-desktop) desktop container repositories (referenced as Desktop Containers here), and the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) share various components between each other:
The [`docker-nvidia-glx-desktop`](https://github.com/selkies-project/docker-nvidia-glx-desktop)/[`docker-nvidia-egl-desktop`](https://github.com/selkies-project/docker-nvidia-egl-desktop) desktop container repositories (referenced as Desktop Containers here), and the [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example) share various components between each other:
`LICENSE`, `supervisord.conf`, `kasmvnc-entrypoint.sh`, and `selkies-gstreamer-entrypoint.sh` are always identical in both Desktop Containers (copy and paste between each container). As these components are also very similar to the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example), **you need to do three Pull Requests including the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) if relevant lines changed in the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example), and at least two Pull Requests for both Desktop Containers.**
`LICENSE`, `supervisord.conf`, `kasmvnc-entrypoint.sh`, and `selkies-gstreamer-entrypoint.sh` are always identical in both Desktop Containers (copy and paste between each container). As these components are also very similar to the [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example), **you need to do three Pull Requests including the [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example) if relevant lines changed in the [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example), and at least two Pull Requests for both Desktop Containers.**
The `Dockerfile` is always identical below and above the lines that say `Anything above/below this line should always be kept the same...` in both Desktop Containers. This component is not shared with the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example), and installation procedures for Selkies-GStreamer should be updated to the desktop containers on every release, so **you need to do three Pull Requests including the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) if relevant lines changed in the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example), and at least two Pull Requests for both Desktop Containers.**
The `Dockerfile` is always identical below and above the lines that say `Anything above/below this line should always be kept the same...` in both Desktop Containers. This component is not shared with the [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example), and installation procedures for Selkies-GStreamer should be updated to the desktop containers on every release, so **you need to do three Pull Requests including the [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example) if relevant lines changed in the [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example), and at least two Pull Requests for both Desktop Containers.**
The `entrypoint.sh` components are always identical from the start until the line containing `export PULSE_SERVER=..."` in both Desktop Containers. The script for installing NVIDIA userspace driver components are always identical except for the outermost `if` condition. Other script sections require manual assessment when updating, so **you need to do three Pull Requests including the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) if relevant lines changed in both Desktop Containers and the [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example).**
The `entrypoint.sh` components are always identical from the start until the line containing `export PULSE_SERVER=..."` in both Desktop Containers. The script for installing NVIDIA userspace driver components are always identical except for the outermost `if` condition. Other script sections require manual assessment when updating, so **you need to do three Pull Requests including the [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example) if relevant lines changed in both Desktop Containers and the [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example).**
`README.md` and `egl.yml`/`xgl.yml` files in both Desktop Containers are similar but have different components, thus requiring manual assessment for both Desktop Containers when updating.
@@ -191,7 +191,7 @@ The `entrypoint.sh` components are always identical from the start until the lin
- **Write or edit code in relevant files and reference them so that the code style is kept consistent.** For instance, many handler methods that start with `on_` are initially unset, then set and referenced in other components or classes during initialization. If you are implementing a new capability on certain methods or handlers that use methods starting with `on_` frequently, you have to create new `on_` methods as well to handle your capability. This assists with keeping the code highly readable, and putting methods or functions in the wrong files will harm the consistency of the code style. **If you are starting to feel that the location you are writing code in does not blend properly into adjacent code, you are probably writing it in the wrong place!**
- For example, assume that we are writing a new component that receives WebRTC Metrics from the web interface and writes them into multiple CSV files in the host ([#141](https://github.com/selkies-project/selkies-gstreamer/pull/141)). Because the WebRTC RTCDataChannel interface is used, receiving the metrics will be handled in [`webrtc_input.py`](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer/webrtc_input.py). But this does not mean that everything should be implemented in this file. Instead, they should be [implemented in the `Metrics` class](https://github.com/selkies-project/selkies-gstreamer/pull/141/commits/abae13645fdf0082f27041c59a14e1c030cf3763) of [`metrics.py`](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer/metrics.py), and be initialized in [`__main__.py`](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer/__main__.py). This way, relevant code stays in appropriate files and is initialized only when the capabilities are needed.
- For example, assume that we are writing a new component that receives WebRTC Metrics from the web interface and writes them into multiple CSV files in the host ([#141](https://github.com/selkies-project/selkies/pull/141)). Because the WebRTC RTCDataChannel interface is used, receiving the metrics will be handled in [`webrtc_input.py`](https://github.com/selkies-project/selkies/tree/main/src/selkies_gstreamer/webrtc_input.py). But this does not mean that everything should be implemented in this file. Instead, they should be [implemented in the `Metrics` class](https://github.com/selkies-project/selkies/pull/141/commits/abae13645fdf0082f27041c59a14e1c030cf3763) of [`metrics.py`](https://github.com/selkies-project/selkies/tree/main/src/selkies_gstreamer/metrics.py), and be initialized in [`__main__.py`](https://github.com/selkies-project/selkies/tree/main/src/selkies_gstreamer/__main__.py). This way, relevant code stays in appropriate files and is initialized only when the capabilities are needed.
- Some code components have `CAPITALIZED_COMMENT:` comment sections such as `ADD_ENCODER:` or `OPUS_FRAME:`. These sections indicate that locations with the `CAPITALIZED_COMMENT:` must be edited or added simultaneously.
@@ -211,4 +211,4 @@ Please also note that objects based on GstBin (most notably `webrtcbin` and `rtp
# Maintainer Documentation
- New releases are published by going to the [Publish release](https://github.com/selkies-project/selkies-gstreamer/actions/workflows/build_and_publish_release.yaml) GitHub Action Workflow, and triggering `workflow_dispatch` by clicking on `Run workflow` with `Branch: main`, and specifying the release tag. The draft release for the new proposed release will be generated in the [Releases](https://github.com/selkies-project/selkies-gstreamer/releases) page, only visible to the maintainers. After waiting for the release build to finish, editing the release notes, and publishing the release, the release will be visible as the latest release. **If the same release is created multiple times because of certain issues, make sure to delete the previous release and the tag before running the [Publish release](https://github.com/selkies-project/selkies-gstreamer/actions/workflows/build_and_publish_release.yaml) GitHub Action Workflow again.**
- New releases are published by going to the [Publish release](https://github.com/selkies-project/selkies/actions/workflows/build_and_publish_release.yaml) GitHub Action Workflow, and triggering `workflow_dispatch` by clicking on `Run workflow` with `Branch: main`, and specifying the release tag. The draft release for the new proposed release will be generated in the [Releases](https://github.com/selkies-project/selkies/releases) page, only visible to the maintainers. After waiting for the release build to finish, editing the release notes, and publishing the release, the release will be visible as the latest release. **If the same release is created multiple times because of certain issues, make sure to delete the previous release and the tag before running the [Publish release](https://github.com/selkies-project/selkies/actions/workflows/build_and_publish_release.yaml) GitHub Action Workflow again.**

2
docs/faq.md
View File

@@ -44,7 +44,7 @@ If the latency becomes higher while the screen is idle or the tab is not focused
If it does not, disable all power saving or efficiency features available in the web browser. In Windows 10 or 11, try `Start > Settings > System > Power & battery > Power mode > Best performance`. Also, note that if you saturate your CPU or GPU with an application on the host, the remote desktop interface will also substantially slow down as it cannot use the CPU or GPU enough to decode the screen. Also, check for GPU driver/firmware updates in the client computer.
However, it might be that the parameters for the WebRTC interface, video encoders, the RTP payloader, or other [GStreamer](https://gstreamer.freedesktop.org) plugins are not optimized enough. If you find that it is the case, we always welcome [contributions](development.md). If your changes show noticeably better results in the same conditions, please make a [Pull Request](https://github.com/selkies-project/selkies-gstreamer/pulls), or tell us about the parameters in any channel that we can reach so that we could also test.
However, it might be that the parameters for the WebRTC interface, video encoders, the RTP payloader, or other [GStreamer](https://gstreamer.freedesktop.org) plugins are not optimized enough. If you find that it is the case, we always welcome [contributions](development.md). If your changes show noticeably better results in the same conditions, please make a [Pull Request](https://github.com/selkies-project/selkies/pulls), or tell us about the parameters in any channel that we can reach so that we could also test.
</details>

6
docs/firewall.md
View File

@@ -84,7 +84,7 @@ If you are using Selkies-GStreamer in a private network without access to the in
An open-source TURN server for Linux or UNIX-like operating systems that may be used is [coTURN](https://github.com/coturn/coturn), available in major package repositories or as an official container [`coturn/coturn:latest`](https://hub.docker.com/r/coturn/coturn).
The Selkies-GStreamer [coTURN](component.md#coturn) image [`ghcr.io/selkies-project/selkies-gstreamer/coturn:main`](https://github.com/selkies-project/selkies-gstreamer/pkgs/container/selkies-gstreamer%2Fcoturn) is also included in this repository, and may be used to host your own STUN/TURN infrastructure. As this image contains additional features for identifying the external server IP in cloud environments, usage of this container is recommended.
The Selkies-GStreamer [coTURN](component.md#coturn) image [`ghcr.io/selkies-project/selkies-gstreamer/coturn:main`](https://github.com/selkies-project/selkies/pkgs/container/selkies-gstreamer%2Fcoturn) is also included in this repository, and may be used to host your own STUN/TURN infrastructure. As this image contains additional features for identifying the external server IP in cloud environments, usage of this container is recommended.
[Pion TURN](https://github.com/pion/turn)'s `turn-server-simple` executable or [eturnal](https://eturnal.net) are recommended alternative TURN server implementations that support Windows as well as Linux or MacOS. [STUNner](https://github.com/l7mp/stunner) is a Kubernetes-native STUN and TURN deployment if Helm is possible to be used.
@@ -181,7 +181,7 @@ Consult the [coTURN Documentation](https://github.com/coturn/coturn/blob/master/
### Deploy coTURN with Docker®
The [coTURN Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/coturn) is a reference container which provides the [coTURN](https://github.com/coturn/coturn) TURN server. Other than options including `-e TURN_SHARED_SECRET=`, `-e TURN_REALM=`, `-e TURN_PORT=`, `-e TURN_MIN_PORT=`, and `-e TURN_MAX_PORT=`, add more command-line options in `-e TURN_EXTRA_ARGS=`.
The [coTURN Container](https://github.com/selkies-project/selkies/tree/main/addons/coturn) is a reference container which provides the [coTURN](https://github.com/coturn/coturn) TURN server. Other than options including `-e TURN_SHARED_SECRET=`, `-e TURN_REALM=`, `-e TURN_PORT=`, `-e TURN_MIN_PORT=`, and `-e TURN_MAX_PORT=`, add more command-line options in `-e TURN_EXTRA_ARGS=`.
**Read the [coTURN](component.md#coturn) section to get started.**
@@ -213,7 +213,7 @@ Consult the [coTURN Documentation](https://github.com/coturn/coturn/blob/master/
In both types of containers, the `--cert=` and `--pkey=` options are required for using TURN over TLS/DTLS, but are otherwise optional. They should lead to the certificate and the private key from a legitimate certificate authority such as [ZeroSSL](https://zerossl.com/features/acme/) or [Let's Encrypt](https://letsencrypt.org/getting-started/) with a valid hostname which resolves to the TURN server.
Provide the certificate and private files to the coTURN container with `-v /my_local_path/coturncert.crt:/etc/coturn_tls.crt -v /my_local_path/coturnkey.key:/etc/coturn_tls.key` (specified paths are an example), then add the options `-e TURN_EXTRA_ARGS="--cert=/etc/coturn_tls.crt --pkey=/etc/coturn_tls.key"` for the Selkies [coTURN Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/coturn) and use the options `--cert=/etc/coturn_tls.crt --pkey=/etc/coturn_tls.key` for the official coTURN container.
Provide the certificate and private files to the coTURN container with `-v /my_local_path/coturncert.crt:/etc/coturn_tls.crt -v /my_local_path/coturnkey.key:/etc/coturn_tls.key` (specified paths are an example), then add the options `-e TURN_EXTRA_ARGS="--cert=/etc/coturn_tls.crt --pkey=/etc/coturn_tls.key"` for the Selkies [coTURN Container](https://github.com/selkies-project/selkies/tree/main/addons/coturn) and use the options `--cert=/etc/coturn_tls.crt --pkey=/etc/coturn_tls.key` for the official coTURN container.
### Deploy coTURN With Kubernetes

28
docs/start.md
View File

@@ -19,8 +19,8 @@ In the future, this host dependency requirement may be completely eliminated if
**2. Download and unpack the latest stable release of the Selkies-GStreamer portable distribution inside a directory of your choice:**
```bash
export SELKIES_VERSION="$(curl -fsSL "https://api.github.com/repos/selkies-project/selkies-gstreamer/releases/latest" | jq -r '.tag_name' | sed 's/[^0-9\.\-]*//g')"
cd ~ && curl -fsSL "https://github.com/selkies-project/selkies-gstreamer/releases/download/v${SELKIES_VERSION}/selkies-gstreamer-portable-v${SELKIES_VERSION}_amd64.tar.gz" | tar -xzf -
export SELKIES_VERSION="$(curl -fsSL "https://api.github.com/repos/selkies-project/selkies/releases/latest" | jq -r '.tag_name' | sed 's/[^0-9\.\-]*//g')"
cd ~ && curl -fsSL "https://github.com/selkies-project/selkies/releases/download/v${SELKIES_VERSION}/selkies-gstreamer-portable-v${SELKIES_VERSION}_amd64.tar.gz" | tar -xzf -
```
**3. Set your `DISPLAY` and `PULSE_SERVER` environment variables for the X.Org X11 display server or PulseAudio audio server.**
@@ -78,7 +78,7 @@ The [`selkies-vdi`](https://github.com/selkies-project/selkies-vdi) or [`selkies
## Minimal Container
The [Example Container](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/example) is the reference minimal-functionality container developers can base upon, or test Selkies-GStreamer quickly. The bare minimum Xfce4 desktop environment is installed together with Firefox, as well as an embedded TURN server inside the container for quick WebRTC firewall traversal.
The [Example Container](https://github.com/selkies-project/selkies/tree/main/addons/example) is the reference minimal-functionality container developers can base upon, or test Selkies-GStreamer quickly. The bare minimum Xfce4 desktop environment is installed together with Firefox, as well as an embedded TURN server inside the container for quick WebRTC firewall traversal.
Instructions are available in the [Example Container](component.md#example-container) section.
@@ -96,15 +96,15 @@ This distribution is slightly more complicated to deploy, yet is the recommended
Selkies-GStreamer has a highly modularized architecture, composed of multiple components.
Three mandatory components are required to run Selkies-GStreamer: the [standalone or distribution-provided build of GStreamer](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gstreamer) with the most recent version (currently ≥ 1.22), the [Python component wheel package](https://github.com/selkies-project/selkies-gstreamer/tree/main/src/selkies_gstreamer) including the signaling server, and the [HTML5 web interface components](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gst-web). Currently, Ubuntu 24.04 (Mint 22), 22.04 (Mint 21), 20.04 (Mint 20) are supported, but other operating systems should also work if using your own GStreamer build of the newest version (contributions for build workflows of more operating systems are welcome).
Three mandatory components are required to run Selkies-GStreamer: the [standalone or distribution-provided build of GStreamer](https://github.com/selkies-project/selkies/tree/main/addons/gstreamer) with the most recent version (currently ≥ 1.22), the [Python component wheel package](https://github.com/selkies-project/selkies/tree/main/src/selkies_gstreamer) including the signaling server, and the [HTML5 web interface components](https://github.com/selkies-project/selkies/tree/main/addons/gst-web). Currently, Ubuntu 24.04 (Mint 22), 22.04 (Mint 21), 20.04 (Mint 20) are supported, but other operating systems should also work if using your own GStreamer build of the newest version (contributions for build workflows of more operating systems are welcome).
All three of the components are built and packaged every [Release](https://github.com/selkies-project/selkies-gstreamer/releases). In addition, every latest commit gets built and is made available in container forms [`ghcr.io/selkies-project/selkies-gstreamer/gstreamer`](https://github.com/selkies-project/selkies-gstreamer/pkgs/container/selkies-gstreamer%2Fgstreamer), [`ghcr.io/selkies-project/selkies-gstreamer/py-build`](https://github.com/selkies-project/selkies-gstreamer/pkgs/container/selkies-gstreamer%2Fpy-build), and [`ghcr.io/selkies-project/selkies-gstreamer/gst-web`](https://github.com/selkies-project/selkies-gstreamer/pkgs/container/selkies-gstreamer%2Fgst-web).
All three of the components are built and packaged every [Release](https://github.com/selkies-project/selkies/releases). In addition, every latest commit gets built and is made available in container forms [`ghcr.io/selkies-project/selkies-gstreamer/gstreamer`](https://github.com/selkies-project/selkies/pkgs/container/selkies-gstreamer%2Fgstreamer), [`ghcr.io/selkies-project/selkies-gstreamer/py-build`](https://github.com/selkies-project/selkies/pkgs/container/selkies-gstreamer%2Fpy-build), and [`ghcr.io/selkies-project/selkies-gstreamer/gst-web`](https://github.com/selkies-project/selkies/pkgs/container/selkies-gstreamer%2Fgst-web).
For more information, check the [Components](component.md#components) section.
The [All-In-One Desktop Containers](#desktop-container) support unprivileged self-hosted Kubernetes clusters and Docker®/Podman.
Example Google Compute Engine/Google Kubernetes Engine deployment configurations of all components are available in the [`infra/gce`](https://github.com/selkies-project/selkies-gstreamer/tree/main/infra/gce) and [`infra/gke`](https://github.com/selkies-project/selkies-gstreamer/tree/main/infra/gke) directories, but may be deprecated in favor of vendor-agnostic Kubernetes configurations.
Example Google Compute Engine/Google Kubernetes Engine deployment configurations of all components are available in the [`infra/gce`](https://github.com/selkies-project/selkies/tree/main/infra/gce) and [`infra/gke`](https://github.com/selkies-project/selkies/tree/main/infra/gke) directories, but may be deprecated in favor of vendor-agnostic Kubernetes configurations.
### Install the packaged version on self-hosted standalone machines, cloud instances, or virtual machines
@@ -124,14 +124,14 @@ Install additional dependencies if using Ubuntu ≥ 22.04 (Mint 21) or a higher
sudo apt-get update && sudo apt-get install --no-install-recommends -y xcvt libopenh264-dev svt-av1 aom-tools
```
If using supported NVIDIA GPUs, install NVENC (bundled with the GPU driver) and NVRTC (bundled with pre-built GStreamer component, check the [GStreamer Dockerfile](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gstreamer/Dockerfile) for manual installation instructions).
If using supported NVIDIA GPUs, install NVENC (bundled with the GPU driver) and NVRTC (bundled with pre-built GStreamer component, check the [GStreamer Dockerfile](https://github.com/selkies-project/selkies/tree/main/addons/gstreamer/Dockerfile) for manual installation instructions).
If using AMD or Intel GPUs, install its graphics and VA-API drivers, as well as `libva2`. The bundled VA-API driver in the AMDGPU Pro graphics driver is recommended for AMD GPUs and the `i965-va-driver-shaders` or `intel-media-va-driver-non-free` packages are recommended depending on your Intel GPU generation. Optionally install `vainfo`, `intel-gpu-tools`, `radeontop`, or `nvtop` for GPU monitoring.
Use the following commands to retrieve the latest `SELKIES_VERSION` release, the current Ubuntu `DISTRIB_RELEASE`, and the current architecture `ARCH` in the following steps:
```bash
export SELKIES_VERSION="$(curl -fsSL "https://api.github.com/repos/selkies-project/selkies-gstreamer/releases/latest" | jq -r '.tag_name' | sed 's/[^0-9\.\-]*//g')"
export SELKIES_VERSION="$(curl -fsSL "https://api.github.com/repos/selkies-project/selkies/releases/latest" | jq -r '.tag_name' | sed 's/[^0-9\.\-]*//g')"
export DISTRIB_RELEASE="$(grep '^VERSION_ID=' /etc/os-release | cut -d= -f2 | tr -d '\"')"
export ARCH="$(dpkg --print-architecture)"
```
@@ -141,17 +141,17 @@ export ARCH="$(dpkg --print-architecture)"
Read [GStreamer](component.md#gstreamer) for more details of this step and procedures for installing from the latest commit in the `main` branch.
```bash
cd /opt && curl -fsSL "https://github.com/selkies-project/selkies-gstreamer/releases/download/v${SELKIES_VERSION}/gstreamer-selkies_gpl_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_amd64.tar.gz" | sudo tar -xzf -
cd /opt && curl -fsSL "https://github.com/selkies-project/selkies/releases/download/v${SELKIES_VERSION}/gstreamer-selkies_gpl_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_amd64.tar.gz" | sudo tar -xzf -
```
This will install the GStreamer components to the default directory of `/opt/gstreamer`. If you are unpacking to a different directory, make sure to set the the environment variable `GSTREAMER_PATH` to the directory. GStreamer builds for `aarch64` are not provided but can be built following procedures in the [GStreamer Dockerfile](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/gstreamer/Dockerfile) or [Conda Dockerfile](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons/conda/Dockerfile).
This will install the GStreamer components to the default directory of `/opt/gstreamer`. If you are unpacking to a different directory, make sure to set the the environment variable `GSTREAMER_PATH` to the directory. GStreamer builds for `aarch64` are not provided but can be built following procedures in the [GStreamer Dockerfile](https://github.com/selkies-project/selkies/tree/main/addons/gstreamer/Dockerfile) or [Conda Dockerfile](https://github.com/selkies-project/selkies/tree/main/addons/conda/Dockerfile).
**3. Install the Selkies-GStreamer Python components** (this component is pure Python and any operating system is compatible, fill in `SELKIES_VERSION`)**:**
Read [Python Application](component.md#python-application) for more details of this step and procedures for installing from the latest commit in the `main` branch.
```bash
cd /tmp && curl -O -fsSL "https://github.com/selkies-project/selkies-gstreamer/releases/download/v${SELKIES_VERSION}/selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl" && sudo PIP_BREAK_SYSTEM_PACKAGES=1 pip3 install --no-cache-dir --force-reinstall "selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl" && rm -f "selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl"
cd /tmp && curl -O -fsSL "https://github.com/selkies-project/selkies/releases/download/v${SELKIES_VERSION}/selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl" && sudo PIP_BREAK_SYSTEM_PACKAGES=1 pip3 install --no-cache-dir --force-reinstall "selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl" && rm -f "selkies_gstreamer-${SELKIES_VERSION}-py3-none-any.whl"
```
**4. Unpack the Selkies-GStreamer HTML5 components:**
@@ -159,7 +159,7 @@ cd /tmp && curl -O -fsSL "https://github.com/selkies-project/selkies-gstreamer/r
Read [Web Application](component.md#web-application) for more details of this step and procedures for installing from the latest commit in the `main` branch.
```bash
cd /opt && curl -fsSL "https://github.com/selkies-project/selkies-gstreamer/releases/download/v${SELKIES_VERSION}/selkies-gstreamer-web_v${SELKIES_VERSION}.tar.gz" | sudo tar -xzf -
cd /opt && curl -fsSL "https://github.com/selkies-project/selkies/releases/download/v${SELKIES_VERSION}/selkies-gstreamer-web_v${SELKIES_VERSION}.tar.gz" | sudo tar -xzf -
```
This will install the HTML5 components to the default directory of `/opt/gst-web`. If you are unpacking to a different directory, make sure to set the directory to the environment variable `SELKIES_WEB_ROOT` or add the command-line option `--web_root=` to Selkies-GStreamer. Note that you should change `manifest.json` and `cacheName` in `sw.js` to rebrand the web interface to a different name.
@@ -169,7 +169,7 @@ This will install the HTML5 components to the default directory of `/opt/gst-web
Read [Joystick Interposer](component.md#joystick-interposer) for more details of this step and procedures for installing from the latest commit in the `main` branch.
```bash
cd /tmp && curl -o selkies-js-interposer.deb -fsSL "https://github.com/selkies-project/selkies-gstreamer/releases/download/v${SELKIES_VERSION}/selkies-js-interposer_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_${ARCH}.deb" && sudo apt-get update && sudo apt-get install --no-install-recommends -y ./selkies-js-interposer.deb && rm -f selkies-js-interposer.deb
cd /tmp && curl -o selkies-js-interposer.deb -fsSL "https://github.com/selkies-project/selkies/releases/download/v${SELKIES_VERSION}/selkies-js-interposer_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_${ARCH}.deb" && sudo apt-get update && sudo apt-get install --no-install-recommends -y ./selkies-js-interposer.deb && rm -f selkies-js-interposer.deb
```
Alternatively, users may directly place the Joystick Interposer libraries from the `selkies-js-interposer_v${SELKIES_VERSION}_ubuntu${DISTRIB_RELEASE}_${ARCH}.tar.gz` tarball into the library path, for instance into `/usr/lib/i386-linux-gnu` and `/usr/lib/i386-linux-gnu`. More information can be found in [Joystick Interposer](component.md#joystick-interposer).
@@ -246,7 +246,7 @@ Please read [**WebRTC and Firewall Issues**](firewall.md).
### Install the latest build on self-hosted standalone machines, cloud instances, or virtual machines
**Build artifacts for every `main` branch commit are available as an after logging into GitHub in [Actions](https://github.com/selkies-project/selkies-gstreamer/actions), and you do not need Docker® to download them.**
**Build artifacts for every `main` branch commit are available as an after logging into GitHub in [Actions](https://github.com/selkies-project/selkies/actions), and you do not need Docker® to download them.**
Otherwise, Docker®/Podman (or any equivalent) may be used if you want to use builds from the latest commit. Refer to [Components](component.md) for more information.

2
docs/usage.md
View File

@@ -26,4 +26,4 @@ Environment variables for command-line options are available as capitalizations
## CI/CD Build
We use Docker® containers for building every commit. The root directory [`Dockerfile`](https://github.com/selkies-project/selkies-gstreamer/tree/main/Dockerfile) and Dockerfiles within the [`addons`](https://github.com/selkies-project/selkies-gstreamer/tree/main/addons) directory provide directions for building each component, so that you may replicate the procedures in your own setup even without Docker® by copying the commands to your own shell.
We use Docker® containers for building every commit. The root directory [`Dockerfile`](https://github.com/selkies-project/selkies/tree/main/Dockerfile) and Dockerfiles within the [`addons`](https://github.com/selkies-project/selkies/tree/main/addons) directory provide directions for building each component, so that you may replicate the procedures in your own setup even without Docker® by copying the commands to your own shell.

10
pyproject.toml
View File

@@ -10,7 +10,7 @@ requires = [
build-backend = "setuptools.build_meta"
[project]
name = "selkies-gstreamer"
name = "selkies"
version = "0.0.0"
authors = [
{name = "Dan Isla", email = "danisla@users.noreply.github.com"},
@@ -38,13 +38,13 @@ dependencies = [
]
[project.urls]
Homepage = "https://github.com/selkies-project/selkies-gstreamer"
"Bug Tracker" = "https://github.com/selkies-project/selkies-gstreamer/issues"
Homepage = "https://github.com/selkies-project/selkies"
"Bug Tracker" = "https://github.com/selkies-project/selkies/issues"
[project.scripts]
selkies-gstreamer = "selkies_gstreamer.__main__:main"
selkies = "selkies_gstreamer.__main__:main"
# FIXME
selkies-gstreamer-resize = "selkies_gstreamer.resize:entrypoint"
selkies-resize = "selkies_gstreamer.resize:entrypoint"
[tool.setuptools.packages.find]
where = ["src"]

0
src/selkies_gstreamer/README.md → src/README.md
View File

10
src/selkies_gstreamer/websocket.py
View File

@@ -124,7 +124,7 @@ except OSError as e:
upload_dir_path = None
class GSTAppError(Exception):
class SelkiesAppError(Exception):
pass
@@ -234,14 +234,14 @@ class GSTStreamingApp:
except Gst.ParseError as e:
error_message = f"Error parsing audio pipeline string: {e}"
logger_gst_app.error(error_message)
raise GSTAppError(error_message) from e
raise SelkiesAppError(error_message) from e
if not self.audio_ws_pipeline:
raise GSTAppError("Error: Could not create audio pipeline from string")
raise SelkiesAppError("Error: Could not create audio pipeline from string")
audio_sink = self.audio_ws_pipeline.get_by_name("sink")
if not audio_sink:
raise GSTAppError("Error: Could not get audio sink element")
raise SelkiesAppError("Error: Could not get audio sink element")
def on_new_audio_sample(sink):
sample = sink.emit("pull-sample")
@@ -386,7 +386,7 @@ class GSTStreamingApp:
if pipeline:
res = pipeline.set_state(Gst.State.PLAYING)
if res == Gst.StateChangeReturn.FAILURE:
raise GSTAppError("Failed to set audio pipeline to PLAYING")
raise SelkiesAppError("Failed to set audio pipeline to PLAYING")
elif res == Gst.StateChangeReturn.ASYNC:
logger_gst_app.info(
"Audio pipeline state change to PLAYING is ASYNC."