org.kurento.client

Enum GapsFixMethod

java.lang.Object

java.lang.Enum<GapsFixMethod>

org.kurento.client.GapsFixMethod

All Implemented Interfaces:

Serializable, Comparable<GapsFixMethod>

public enum GapsFixMethod
extends Enum<GapsFixMethod>

How to fix gaps when they are found in the recorded stream.

Gaps are typically caused by packet loss in the input streams, such as when an RTP or WebRTC media flow suffers from network congestion and some packets don't arrive at the media server.

Different ways of handling gaps have different tradeoffs:

• NONE: Do not fix gaps. This means that the resulting files will contain gaps in the timestamps. Some players are clever enough to adapt to this during playback, so that the gaps are reduced to a minimum and no problems are perceived by the user; other players are not so sophisticated, and will struggle trying to decode a file that contains gaps. For example, trying to play such a file directly with Chrome will cause lipsync issues (audio and video out of sync).

  For example, assume a session length of 15 seconds: packets arrive correctly during the first 5 seconds, then there is a gap, then data arrives again for the last 5 seconds. Also, for simplicity, assume 1 frame per second. With no fix for gaps, the RecorderEndpoint will store each frame as-is, with these timestamps:

         frame 1  - 00:01
         frame 2  - 00:02
         frame 3  - 00:03
         frame 4  - 00:04
         frame 5  - 00:05
         frame 11 - 00:11
         frame 12 - 00:12
         frame 13 - 00:13
         frame 14 - 00:14
         frame 15 - 00:15
       

  Notice how the frames between 6 to 10 are missing, but the last 5 frames still conserve their original timestamp. The total length of the file is detected as 15 seconds by most players, although playback could stutter or hang during the missing section.

• GENPTS: Replace timestamps of all frames arriving after a gap. With this method, the length of each gap will be taken into account, to be subtracted from the timestamp of all following frames. This provides for a continuous, gap-less recording, at the expense of reducing the total apparent length of each file.

  In our example, the RecorderEndpoint will change all timestamps that follow a gap in the stream, and store each frame as follows:

         frame 1  - 00:01
         frame 2  - 00:02
         frame 3  - 00:03
         frame 4  - 00:04
         frame 5  - 00:05
         frame 11 - 00:06
         frame 12 - 00:07
         frame 13 - 00:08
         frame 14 - 00:09
         frame 15 - 00:10
       

  Notice how the frames between 6 to 10 are missing, and the last 5 frames have their timestamps corrected to provide a smooth increment over the previous ones. The total length of the file is detected as 10 seconds, and playback should be correct throughout the whole file.

• FILL_IF_TRANSCODING: NOT IMPLEMENTED.

  This is a proposal for future improvement of the RecorderEndpoint.

  It is possible to perform a dynamic adaptation of audio rate and add frame duplication to the video, such that the missing parts are filled with artificial data. This has the advantage of providing a smooth playback result, and at the same time conserving all original timestamps.

  However, the main issue with this method is that it requires accessing the decoded media; i.e., transcoding must be active. For this reason, the proposal is to offer this option to be enabled only when transcoding would still happen anyways.

  In our example, the RecorderEndpoint would change all missing frames like this:

         frame 1  - 00:01
         frame 2  - 00:02
         frame 3  - 00:03
         frame 4  - 00:04
         frame 5  - 00:05
         fake frame - 00:06
         fake frame - 00:07
         fake frame - 00:08
         fake frame - 00:09
         fake frame - 00:10
         frame 11 - 00:11
         frame 12 - 00:12
         frame 13 - 00:13
         frame 14 - 00:14
         frame 15 - 00:15
       

  This joins the best of both worlds: on one hand, the playback should be smooth and even the most basic players should be able to handle the recording files without issue. On the other, the total length of the file is left unmodified, so it matches with the expected duration of the sessions that are being recorded.

Enum Constant Summary

Enum Constants

Enum Constant and Description
FILL_IF_TRANSCODING
GENPTS
NONE

Method Summary

Modifier and Type	Method and Description
static GapsFixMethod	valueOf(String name) Returns the enum constant of this type with the specified name.
static GapsFixMethod[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

NONE

public static final GapsFixMethod NONE

GENPTS

public static final GapsFixMethod GENPTS

FILL_IF_TRANSCODING

public static final GapsFixMethod FILL_IF_TRANSCODING

Method Detail

values

public static GapsFixMethod[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (GapsFixMethod c : GapsFixMethod.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static GapsFixMethod valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null