HlsDriver

Source: HlsDriver.h

HlsDriver

class HlsDriver

src/light/drivers/HlsDriver.h:35

Inherits: DriverBase

Output driver: publishes the rendered frame as an H.264 stream over HLS, from the device's own HTTP server.

A TV, VLC or a browser can play it. It complements NdiDriver: NDI is the pro-tools path, HLS is the consumer-playback path.

The driver states numbers and the platform encodes. This driver packs the corrected frame and hands it over with the geometry, rate and bitrate. How those become H.264 differs per platform.

Prior art: HLS is Apple's, described in RFC 8216, and ffmpeg does the desktop encoding.

Public Attributes

uint8_t scale = 0 : Video pixels per light, 0 being auto; one factor for both axes.

uint8_t targetFps = 30 : Encode-rate ceiling; the render loop runs faster and extra frames are not encoded.

uint8_t encoderSel_ = 0 : The ffmpeg encoder pick; hardware entries offload the encode (see the control's comment).

Public Methods

inline ~HlsDriver() override : A destroyed driver releases the encoder, since nothing else can: a claim outliving its owner would refuse every later driver, and the next one can even land on this address.

inline HlsDriver() : Bind the two scratch buffers to this module, so their memory is accounted for.

virtual inline const char * tags() const override : The catalog tags shown on this driver's card.

virtual inline void setSourceBuffer(Buffer * buf) override : Point the driver at the shared source buffer.

virtual inline void defineDriverControls() override : Bind the frame rate, the scale, and the encoder choice where there is one.

virtual inline bool affectsPrepare(const char * name) const override : Which controls need a fresh encode, the encoder fixing its rate at spawn.

virtual inline void prepare() override : Derive the scaled geometry, make the segment directory, and start the encoder.

virtual inline void release() override : Stop the encoder and drop the segments it wrote.

virtual inline void tick() override : The hot tick, which by default ticks every enabled child and times each.

virtual inline void tick1s() override : The once-a-second tick for housekeeping, which by default ticks the children.

Public Static Attributes

constexpr const char * kTags = "🖥️" : The catalog tag this driver carries.

constexpr const char * kSegmentDir = "/.hls" : Where the encoder's segments are written, under the filesystem mount.

More info

Pixel-exact contract

The encoded frame is the grid from the layer, letterboxed by the display. Above scale 1 a light becomes a solid square block, still pixel-exact since replication invents no color. Scaling exists because a hardware encoder has a minimum frame size, and a small wall at one to one is a postage stamp.

Frame pacing

A fixed schedule rather than a last-sent timestamp. Millisecond division truncates and re-basing on arrival lets one late tick shift the schedule, and either drift ends in the player re-buffering.

Where it runs

H.264 needs a desktop-class CPU or a hardware encoder, so desktop and the ESP32-P4. Every other board reaches viewers through the preview instead.