Recorder

The Recorder module is responsible for performing original multicast stream recording. It can be controlled either directly from the frontend or through the use of a REST API.

Recorder can operate in one of 2 modes:
- MPEG TS segmented recording
- HLS recording

Note, recording is only available for multicast streams.

Running with Docker

docker run --rm --network host --name stanag2webrtc -v /home/myuser/recorder:/recorder impleo/stanag2webrtc:2.1.2 -url udp://227.1.1.1:30120 -multicastIface lo -recorderTargetDir /recorder

In the above command, we map the folder /home/myuser/recorder to the container and run the service to play back the multicast UDP stream udp://227.1.1.1:30120 on the loopback network interface. Since we haven't provided the -addr argument, the default address (0.0.0.0:4000) will be used, allowing us to access the frontend at http://localhost:4000 (or from the remote computer, using the server's address).

Or using Docker compose:

version: "3.4"

services:
  stanag2webrtc: 
    image: impleo/stanag2webrtc:2.1.2 
    container_name: stanag2webrtc
    restart: always
    volumes:
      - /home/myuser/recorder:/recorder
    network_mode: host   
    command: >
      -url udp://227.1.1.1:30120
      -multicastIface lo
      -recorderTargetDir /recorder

Recording configuration parameters

Name	Description	Default
url	Stream url	"udp://227.1.1.1:30120"
multicastIface	The network interface on which to join the multicast group. Multiple interfaces can be specified by separating them with commas. (e.g. "eth0,eth1" on Linux or "192.168.1.20" on Windows.). If multiple interfaces are provided, recorder will use the first one
recorderMode	Recorder mode (hls/mpegts)	mpegts
missionName	Mission Name	Mission
channelName	Channel (Sensor) name	E0
recorderSegmentDuration	Recorder segment Duration (in sec)	30
recorderSegmentWrap	Recorder segment wrap counter	0
recorderTargetDir	Recorder Target Directory. Note, you must provide it, otherwise recording will not be enabled.	""
recorderTranscode	Transcode video while recording	false
recorderVideoResolution	Transcoded Video resolution (for recording)	720x480
recorderVideoBitrate	Transcoded Video Bitrate (for recording)	120000
recorderProfile	Transcoding profile (for recording): baseline, main, high"	baseline
recorderPreset	Transcoding preset (for recording): ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow". More info on recorderPreset	veryfast
recorderPath	Recorder Executable Path. A default recorder is ./recorderProc.run (for Linux) or ./recorderProc.exe (for Windows), so if nothing is specified, the recorder executable will be set according to the OS"	./recorderProc.run (./recorderProc.exe for Windows)
klvSampling	KLV metadata sampling (for vtt generation) interval in milliseconds. Set to 0 to disable sampling.	0

Recorder states

Recorder can be in one of the following states:

• ⭕ starting. Recorder received start command.
• 🔴 running. Recorder is running.
• 🔘 stopping. Recorder is stopping, not all files are finalized.
• ⚪ stopped. Recorder is stopped. All files are finalized.
• 🟠 waiting. Recorder is waiting for the stream.
• 🚫 error. Recorder is in error state.
• 🔵 Unknown state. Recorder state is unknown.

MPEG TS segmented recording

In this mode an incoming MPEG transport stream is divided into segments of predefined duration for storage or further processing. The recorder splits the stream into individual segments, each containing a specific time interval of the stream. This technique is commonly used in digital video broadcasting and streaming applications, where the need for efficient storage and delivery of video content is essential. The segmented recording allows for easy management and retrieval of specific segments of the stream, making it easier to edit, manipulate, and distribute. It also allows for better error resilience, as a problem in one segment does not affect the entire stream.

Naming convention

When recorder starts, it creates teh recorderTargetDir, if it doesn't already exist. In that directory, the following hierarchy of files is created:

├── recorderTargetDir/  
│    ├── missionName-channelName-YYYY-MM-DD-HH-MM-SS_0.ts  
│    ├── missionName-channelName-YYYY-MM-DD-HH-MM-SS_1.ts  
|    ├── missionName-channelName-YYYY-MM-DD-HH-MM-SS_2.ts  
|    ├── missionName-channelName-YYYY-MM-DD-HH-MM-SS_3.ts  

If missionName or channelName contains characters that are not allowed in a path, they will be automatically substituted with '-' for compatibility. If missionName or channelName are not specified, they will be skipped from the file name. If recorderSegmentDuration is less or equal to 0, segmentation will be disabled and only one file will be created.

Here is an example:

├── ./tmp/recorder/  
│    ├── TestMission-EO-2023-5-1-9-42-29_0.ts  
│    ├── TestMission-EO-2023-5-1-9-42-29_1.ts  
|    ├── TestMission-EO-2023-5-1-9-42-29_2.ts  
|    ├── TestMission-EO-2023-5-1-9-42-29_3.ts  

HLS recording

HLS (HTTP Live Streaming) recording mode is a more modern and widely used method of recording video streams, particularly for online video streaming applications. Like MPEG TS segmented recording, HLS also splits the incoming video stream into segments, but the segments are stored in a playlist file in a specific order. The playlist file is then delivered to the viewer's device, which requests the segments in the correct order and stitches them together to play the video. Overall, HLS recording mode is a more robust and versatile solution for recording and delivering online video content.

Naming convention

When recorder starts, it creates teh recorderTargetDir, if it doesn't already exist. In that directory, the following hierarchy of subdirectories/files is created:

├── MissionName/  
     │   ├── SensorName/  
     │   │         ├── MissionMasterManifest.m3u8  
     │   │         ├── MissionVideoManifest.m3u8  
     │   │         ├── MissionManifest-0-CC.m3u8  
     │   │         ├── Clip1  
     │   │         │      ├── ClipMasterManifest.m3u8  
     │   │         │      ├── ClipVideoManifest.m3u8  
     │   │         │      ├── Manifest-0-CC.m3u8  
     │   │         │      ├── Clip1-1-0.ts  
     │   │         │      ├── Clip1-1-0.vtt  
     │   │         │      ├── Clip1-1-1.ts  
     │   │         │      ├── Clip1-1-1.vtt  
     │   │         │      ├── ....  
     │   │         │          
     │   │         ├── Clip2  
     │   |         │      ├── ClipMasterManifest.m3u8  
     │   │         │      ├── ClipVideoManifest.m3u8  
     │   │         │      ├── ClipManifest-0-CC.m3u8  
     │   │         │      ├── Clip2-2-0.ts  
     │   │         │      ├── Clip2-2-0.vtt  
     │   │         │      ├── ....  

Clip represents continues recording. This will allow us to stop / restart a live sensor recording without overriding existing data.
MissionManifest is a higher level manifest that points to the video / vtt segments inside the clips. It is created and updated dynamically (to accommodate non continues clips in one continues playlist)

Transcoding

The recorder module, by default, operates in a manner where it copies the video instead of transcoding it. This means that it reproduces the video stream as it is, without altering its resolution, bitrate, or any other characteristics. This approach is beneficial as it ensures minimal loss in video quality and maintains the original format.

However, for users who wish to transcode the video (to H264) and make specific adjustments such as changing the resolution, bitrate, or other parameters, there is an option available. By utilizing the "recorderTranscode" argument, users can enable on-the-fly transcoding of the video. This feature allows for real-time modification and conversion of the video stream based on the desired specifications.

Furthermore, users have the flexibility to choose different encoding profiles and presets through the "recorderProfile" and "recorderPreset" parameters. These settings control the internal encoder used for transcoding, enabling users to select the most suitable configuration for their specific needs. By customizing these parameters, users can optimize the transcoding process according to their preferences, balancing factors such as file size, video quality, and compatibility.

Here is an example of how to configure transcoding:

 ./stanag2WebRTC -addr localhost:3000 -url udp://227.1.1.1:30120 -recorderTargetDir /recorder -recorderTranscode -recorderVideoBitrate 150000 -recorderVideoResolution 720x480 -recorderProfile main -recorderPreset fast