Service: Eyevinn Live Encoding - EyevinnOSC/community GitHub Wiki

Eyevinn Live Encoding

Eyevinn Live Encoding (serviceId eyevinn-live-encoding, catalog page) is an open source, ffmpeg-based live transcoder that takes an RTMP push (or pulls an SRT source) and outputs a live HLS ladder. It is a long-running service instance. License: MIT.

What it can do

  • Accept an RTMP stream on rtmp://<host>/live/<StreamKey> from OBS, ffmpeg or a hardware encoder, or dial an srt:// source in caller mode.
  • Transcode to a multi-rung ABR HLS ladder with configurable ladder, framerate, rate control, segment duration and segment container (MPEG-TS or fMP4).
  • Add a WebVTT subtitle rendition from a sidecar URL.
  • Serve the output as an origin for a CDN, or push it to a CDN origin such as AWS MediaPackage with OutputUrl.

Creating an instance

No OSC dependencies. Call create-service-instance with serviceId: "eyevinn-live-encoding":

{ "name": "mystream", "StreamKey": "mykey" }

Verify with wait-for-service-ready or get-instance-status, then describe-service-instance for the URL and RTMP connection details. The RTMP ingest address has the form rtmp://<host>:<port>/live/<StreamKey>. Use only alphanumeric characters in StreamKey: characters such as ^, [, {, } are not valid in RTMP URLs and prevent the encoder from starting.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
HlsOnly No boolean Output HLS only (HLS_ONLY, upstream default true). Upstream states HLS is the only output implemented, so HLS is produced either way.
StreamKey No string, sensitive RTMP stream key; the encoder takes RTMP pushes on rtmp://<host>/live/<StreamKey> (STREAM_KEY, upstream default stream).
InputUrl No string Optional srt:// URL. If set, the encoder dials this source in caller mode instead of listening for an RTMP publisher (INPUT_URL). SRT options such as latency (microseconds), passphrase, streamid, connect_timeout (milliseconds) go as query parameters.
InputDialTimeout No string Caller-mode dial deadline in seconds; if the source is not reached the encoder goes to error (INPUT_DIAL_TIMEOUT, upstream default 300).
OutputUrl No string URL to push media segments and playlists to a CDN origin, e.g. an AWS MediaPackage ingest URL (OUTPUT_URL). If unset, CDN push is disabled. The URL may embed credentials, so treat it as sensitive.
Ladder No string ABR ladder as comma-separated video rungs <width>x<height>:<bitrate>, e.g. 1920x1080:5000k,1280x720:2800k,640x360:800k (LADDER). Invalid value fails startup. Default 1280x720:4M,640x360:3M.
Framerate No string Output framerate as a positive integer, typically 25, 30, 50 or 60 (FRAMERATE). GOP is set to 2 x framerate. If unset, output follows the input framerate.
RateControl No string cbr (default) or capped-vbr (RATE_CONTROL).
MaxrateFactor No string Positive float; under capped-vbr the per-rung maxrate is this factor times the target bitrate (MAXRATE_FACTOR, default 1.15). Ignored under cbr.
BufsizeFactor No string Positive float; under capped-vbr the buffer size is this factor times maxrate (BUFSIZE_FACTOR, default 2.0). Ignored under cbr.
SegmentDuration No string HLS segment duration in seconds, positive integer up to 60 (SEGMENT_DURATION, default 10). Segments are cut on keyframes, so actual length can be longer.
SubtitleUrl No string http(s) WebVTT source fetched alongside the input and published as a subtitle rendition (SUBTITLE_URL). If unset the output is video and audio only.
SubtitleLanguage No string BCP-47 language tag of the subtitle rendition, e.g. en (SUBTITLE_LANGUAGE, default und).
SubtitleName No string Display name of the subtitle rendition, e.g. English (SUBTITLE_NAME, defaults to the language).
SubtitleDefault No string true or 1 makes the subtitle rendition the default (SUBTITLE_DEFAULT, default false).
SegmentType No string mpegts (default) or fmp4 (init segment plus .m4s fragments) (SEGMENT_TYPE).
ProgramDateTime No string true or 1 writes #EXT-X-PROGRAM-DATE-TIME for every segment (PROGRAM_DATE_TIME, default false). Timestamps come from the host clock.

If you store StreamKey or an OutputUrl with credentials as a service secret, reference it as {{secrets.NAME}} as the entire field value. Overwriting a secret does not restart a running instance.

Using the instance

Push your stream, for example with ffmpeg:

ffmpeg -re -i input.mp4 \
  -c:v libx264 -preset fast -b:v 2500k \
  -c:a aac -b:a 128k \
  -f flv rtmp://<host>:<port>/live/<StreamKey>

In OBS use server rtmp://<host>:<port>/live and your StreamKey as stream key.

The previous documentation for this page gives the HLS playlist URL as https://<instance-url>/live/<StreamKey>/index.m3u8. The upstream README describes the encoder lifecycle as: start the encoder (POST /api/encoder), push to the RTMP address while the status is starting, and when the status is running play the HLS from /origin/hls/index.m3u8 on the service. Check GET /api/encoder for status; DELETE /api/encoder stops it. A web UI is served at /. Test the stream with the HLS Playlist Viewer.

Push to a CDN origin with the OSC CLI:

npx -y @osaas/cli create eyevinn-live-encoding mystream \
  -o StreamKey="mykey" \
  -o OutputUrl="https://<username>:<password>@xxxxx.mediapackage.us-east-1.amazonaws.com/in/v2/<channel-id>/channel"

Limitations

  • SegmentType=fmp4 is not carried by the CDN push: pushed playlists keep an #EXT-X-MAP pointing at the encoder's own origin and the init file is not delivered. Use the local origin output for fMP4.
  • The encoder gives up and goes to error if ffmpeg exits 10 times in a row within 30 seconds of listening without reaching running.
  • Ladder and the preset-style settings fail startup when invalid; the encoder does not fall back to defaults.

Resources

⚠️ **GitHub.com Fallback** ⚠️