LiveKit GStreamer Publisher

This utility allows you to publish from any GStreamer source to LiveKit. It parses a gst-launch style pipeline and reads negotiates

Prerequisites

• Go 1.22 or later
• GStreamer 1.20 or later

Install

go install github.com/MainSquare/gstreamer-publisher@latest

Usage

To use this utility, you need to generate an access token that includes the canPublish permission.

When constructing pipelines, you would want to end the pipeline with elements that produce H264, VP8, VP9, or Opus. Do not mux the streams into a container format. GStreamer-publisher will inspect the pipeline and import the raw streams into LiveKit.

Subscription allowlist

Pass --allowed-users with a comma-separated list of LiveKit participant identities to restrict who can subscribe to the published tracks:

• On startup only the listed identities are allowed to subscribe; everyone else is denied.
• While the publisher runs, it reads updated allowlists from stdin: each line is a full, comma-separated list and is applied as soon as it is read. SIGUSR1 re-applies the currently active allowlist (e.g. after a reconnect).
• The stdin allowlist reader only runs when stdin is a pipe or file, not an interactive terminal. In production stdin is a pipe from the room server, so lines typed at an interactive terminal are not consumed.
• An empty (or otherwise identity-free) line is an explicit deny-all: no participant may subscribe, and participants that are currently subscribed are revoked.
• The special line all (also accepted as --allowed-users all) broadcasts to every participant in the room. The identity all is therefore reserved and cannot be allow-listed as a regular participant.
• Identities are opaque participant identifiers (e.g. UUIDs) supplied by the consumer. This binary defines no identity namespaces of its own and accepts whatever strings the caller passes.

Without --allowed-users the publisher does not read stdin at all and every participant in the room can subscribe.

Examples

The examples below assume you have the following environment variables defined:

export LIVEKIT_URL=<wss://project.livekit.cloud>
export LIVEKIT_PUBLISH_TOKEN=<token>

To view the stream, you can create a second token and head over to our example app to connect as a viewer.

Test stream as H.264

This creates a video and audio from test src, encoding it to H.264 and Opus.

gstreamer-publisher --token $LIVEKIT_PUBLISH_TOKEN \
    -- \
    videotestsrc is-live=true ! \
        video/x-raw,width=1280,height=720 ! \
        clockoverlay ! \
        videoconvert ! \
        x264enc tune=zerolatency key-int-max=60 bitrate=2000 \
    audiotestsrc is-live=true ! \
        audioresample ! \
        audioconvert ! \
        opusenc bitrate=64000

Publish from file

The following converts any video file into VP9 and Opus using decodebin3

gstreamer-publisher --token $LIVEKIT_PUBLISH_TOKEN \
  -- \
    filesrc location="/path/to/file" ! \
    decodebin3 name=decoder \
    decoder. ! queue ! \
        videoconvert ! \
        videoscale ! \
        video/x-raw,width=1280,height=720 ! \
        vp9enc deadline=1 cpu-used=-6 row-mt=1 tile-columns=3 tile-rows=1 target-bitrate=2000000 keyframe-max-dist=60 \
    decoder. ! queue ! \
        audioconvert ! \
        audioresample ! \
        opusenc bitrate=64000