Skip to main content

Getting Started with HLS Stream Recorder

HTTP Live Streaming (HLS) is an HTTP-based media streaming protocol developed by Apple. In HLS mode, the recorder splits the MPEG transport stream into short .ts files and maintains .m3u8 playlists that clients can consume.

The recorder performs two primary tasks:

  • Segmented recording
  • Manifest creation and updates

When recording starts, the recorder writes the playlist as an EVENT playlist. When recording stops, the playlist is finalized as VOD.

Basic Usage​

  • Add references to TsRecorderLib.dll and TSRecorderWr.dll.
  • Copy the remaining runtime dependencies from bin\x64 into the target output folder.
note

You must have the Visual C++ 64-bit Redistributable installed on the target machine.

  • Create a recorder instance and activate the license.
m_Recorder = new CRecorder(id, "Recorder");
m_Recorder.Activate("TSRecorder", m_licenseFile, m_licenseKey);
  • Attach event handlers.
m_Recorder.RecorderEvent += OnRecorderEvent;
m_Recorder.ErrorEvent += OnRecorderError;

private void OnRecorderEvent(Recorder_Event ev, string info, long param, object context)
{
}

private void OnRecorderError(Error_Type e, string err, object context)
{
}
  • Configure the playlist size and initialize HLS recording.
m_Recorder.MaxPlaylistSize = (uint)(5 * 60 / m_SegmentDuration);
m_Recorder.InitHls(m_Url, m_targetFile, m_SegmentDuration, m_GopAlignment);
  • Start the recording loop and continue dispatching Windows events.
m_Recorder.Start();
while (!Console.KeyAvailable)
{
    Thread.Sleep(200);
    Application.DoEvents();
}
  • Stop recording and finalize the manifest.
m_Recorder.Stop();

Naming Convention​

In HLS mode, the target .m3u8 path defines the playlist name, and the recorder derives the media segment base name from the same path with a .ts extension.

Example:

Target manifest: C:/Recordings/live.m3u8
Derived segment base name: C:/Recordings/live.ts
First segment file: C:/Recordings/live_0_2026_03_25_14_07_11.ts
Playlist entry: live_0_2026_03_25_14_07_11.ts

If CreateMasterManifest is enabled, the master manifest is created as Master-<video-manifest-stem>.m3u8.

If SplitSegmentOnHlsDiscontinuity is enabled, a recorded segment can be split into physical sub-segment files such as live_0_2026_03_25_14_07_11-1.ts and live_0_2026_03_25_14_07_11-2.ts.

For the full TS and HLS naming rules, see Recorder Segment Naming Convention.

Optional Configuration​

Manifest Byte Range​

Set ManifestByteRange to true to include byte-range information in the playlist.

m_Recorder.ManifestByteRange = true;

Split Segment On HLS Discontinuity​

Set SplitSegmentOnHlsDiscontinuity to true to split the current segment when a discontinuity is detected.

m_Recorder.SplitSegmentOnHlsDiscontinuity = true;

Master Playlist​

Set CreateMasterManifest to true to generate both a master playlist and an I-frame playlist.

m_Recorder.CreateMasterManifest = true;

When this mode is enabled, ManifestByteRange is automatically set to true because byte ranges are required for the I-frame playlist.

You can retrieve the generated filenames through MasterManifestName and IFrameManifestName.

Copy Files to a Remote Directory​

The recorder supports two related properties:

  • CopyOutputLocation: an additional remote output location
  • DeleteOriginalAfterCopy: delete local files after the copy succeeds

General Rules​

  • During Init, the recorder attempts to create the remote directory if CopyOutputLocation is not empty.
  • Empty segments are not copied.
  • Files with the same name are overwritten.
  • Files are copied serially so that each segment is present remotely before the playlist is updated.
  • If copying a segment takes longer than the segment duration, the recorder will not behave correctly.
  • On stop, the recorder spends up to 2000 ms draining the copy queue.
  • If the process exits before the queue is drained, the remaining files stay in the local directory.
  • The I-frame manifest stays local during recording even when DeleteOriginalAfterCopy is enabled, and is removed on stop.

Duration Detection​

  1. The recorder first attempts to detect duration from video PTS.
  2. If that fails, it falls back to PCR-based duration detection.
  3. If that also fails, it uses the configured recording duration to create the playlist.

In the last two cases, discontinuity detection is not available and segment splitting on discontinuity does not occur.

TS Recording Mode​

If CopyOutputLocation is set in TS recording mode, completed .ts segments are copied on SegmentCompleted.

HLS Recording Mode​

If CopyOutputLocation is set in HLS recording mode, completed .ts segments are copied on HlsSegmentInfo. Manifests are copied on MasterManifestUpdated, ManifestUpdated, IFrameManifestUpdated, and ManifestFinalized.