Getting Started with HLS Stream Recorder

HTTP Live Streaming (HLS) is an HTTP-based media streaming protocol implemented by Apple Inc. HLS recorder cuts the TS stream into a sequence of small files, so the player could download one short chunk of a transport stream when it is required. A list of available streams (manifest) can be accessed by client as M3U playlist.

So, the stream recorder does two main tasks:

• Segmented recording
• M3u8 manifect creation and update

When recording is started, the stream recorder sets a PLAYLIST-TYPE as EVENT, indicating live recording. Upon stop, the playlist is finalized - PLAYLIST-TYPE is set to VOD.

Usage:

• Add references to TsRecorderLib.dll, TSRecorderWr.dll and make sure that other dependencies from bin\x64 folder are copied to the target folder

Note

You must have visual c++ 64bit redistributables (2017) installed on your PC.

• Create recorder instance and activate the license

m_Recorder = new CRecorder(id, "Recorder");
m_Recorder.Activate("TSRecorder", m_licenseFile, m_licenseKey); 

• Setup events

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)
{
}

m_Recorder.MaxPlaylistSize = (uint) (5 * 60 / m_SegmentDuration); // Set sliding window to 5 min
m_Recorder.InitHls(m_Url, m_targetFile, m_SegmentDuration, m_GopAlignment);

• Start the recording and dispatch Windows events

m_Recorder.Start())
while (!Console.KeyAvailable)   // Loop until input is entered.
{
  Thread.Sleep(200);
  Application.DoEvents();
}

• Stop recording and finalize the manifest

m_Recorder.Stop(); 

Optional Configuration

• ManifestByteRange

Set ManifestByteRange property to true in order to include byteRange information into manifest.

m_Recorder.ManifestByteRange = true;

• SplitSegmentOnHlsDiscontinuity

Set SplitSegmentOnHlsDiscontinuity property to true in order to split the recorded segment when discontinuity detected.

m_Recorder.SplitSegmentOnHlsDiscontinuity = true;

• Master Playlist

Set CreateMasterManifest property to true in order to generate master manifest together with I Frame manifest.

m_Recorder.CreateMasterManifest = true;

Once this set, Recorder will generate video manifest, master manifest and I frame manifest.

Note

ManifestByteRange will be automatically set to true in this mode, as it is required for proper I frame list generation.

You can get the Master manifest and IFrame manifest names using MasterManifestName and IFrameManifestName properties.

Copy files to remote directory

There are 2 related properties

• CopyOutputLocation Additional (Remote) location to copy recorder's output
• DeleteOriginalAfterCopy Delete original files after copying to the remote (copyOutputLocation) target

General

During recorder Init phase, if CopyOutputLocation is not empty, recorder will try to create the remote directory Empty segments will not be copied. Files with the same name will be overwritten Files are not copied in parallel, to insure that the large TS segment is present at the remote location before the manifest is updated. Recorder will not work property if the time it takes to copy a segment exceeds the segment duration. On stop command, recorder will try to copy the files for 2000 ms. Stop will block for that time. If recorder process is terminated with files still in the queue, they will not be copied to the remote and can be found at the local directory. IFrame manifest stays in the local directory during the recording even when DeleteOriginalAfterCopy is set to true. It is removed on stop.

Detection mechanism:

1. Recorder first tries to detect video duration by video PTS.
2. If it fails, it tries another detection module and detects duration by PCR (pcr pid)
3. If it fails, it sets duration to the requested recording duration and uses it to create a manifest.

In last two cases it does not detect discontinuity and consequently, does not split the files.

TS recording mode

In TS recording mode, if CopyOutputLocation is not empty, recorder will try to copy recorded ts segments upon SegmentCompleted event.

HLS recording mode

In HLS recording mode, if CopyOutputLocation is not empty, recorder will try to copy recorded ts segments upon SegmentInfo event and manifests upon MasterManifestUptated, ManifestUpdated, IFrameManifestUpdated and ManifestFinalized respectively.