Service: Eyevinn Live Encoding - EyevinnOSC/community GitHub Wiki
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.
- Accept an RTMP stream on
rtmp://<host>/live/<StreamKey>from OBS, ffmpeg or a hardware encoder, or dial ansrt://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.
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.
| 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.
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"-
SegmentType=fmp4is not carried by the CDN push: pushed playlists keep an#EXT-X-MAPpointing 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
errorif ffmpeg exits 10 times in a row within 30 seconds of listening without reachingrunning. -
Ladderand the preset-style settings fail startup when invalid; the encoder does not fall back to defaults.
- Eyevinn Live Encoding on GitHub
- HLS Stream Monitor for monitoring stream health
- FAST Channel Engine to turn live streams into FAST channels