Warning: This is a development version. The latest stable version is Version 7.0.0.

Rely’s Two Modes

Rely can be used in two modes:

  1. The first mode is “automatic repair” in this mode Rely will automatically generate repair as payloads are being consumed.
  2. The second mode is “manual repair”. In this mode the user controls the generation of repair symbols.

Let’s spend a few minutes to look at both modes in more detail.

Mode #1: Automatic Repair

In automatic repair mode we use the rely::encoder::set_repair_trigger() and related functions to drive the generation of repair symbols. Using the repair trigger we automatically will generate repair when a configurable amount of payloads have been added to Rely.

The following pseudocode highlights the basic usage:

// Enable the automatic repair generation
repair_interval = 4
repair_target = 1

// In this case 20% repair will be generated i.e. after consuming four
// source symbols one repair symbol will be generated.
encoder.set_repair_trigger(repair_interval, repair_target)

encoder.consume(payload #1)
encoder.consume(payload #2)
encoder.consume(payload #3)
encoder.consume(payload #4)

// At this point one repair symbols has been produced

It is still possible to generate additional repair using the rely::encoder::generate_repair() function. This can be useful in situations where suddenly more packet loss than expected is observed on the network and to avoid decoding failure we want to temporarily generate more repair than our repair target.

You may turn off the repair trigger by calling rely::encoder::disable_repair_trigger() if no further repair is required.

Avoid Bursty Repair Generation

If you are using Rely in “automatic repair” mode there may be periods where you observe no losses and therefore do not require any repair generation. In this case all symbols stored in the encoder will be considered unprotected.

When switching repair on this may cause a burst of repair packets to be generated.

As an example let’s assume that repair is disabled and that the encoder contains 50 source symbols. Say we are starting to observe some losses at this point we may want to start to generate repair e.g. 10%. This could be accomplished by calling rely::encoder::set_repair_trigger() and setting repair_interval = 9 and repair_target = 1.

However, since the encoder already contains 50 unprotected symbols Rely will generate repair for all 50 symbols. Which means that 5 repair symbols will be generated instead of just repair_target = 1.

To avoid this situation you can limit the amount of repair that is generated by specifying the repair_limit parameter. For example setting it equal to the repair_target will limit the generated repair to 1 symbol.

Flushing Repair

When running in automatic mode you may have situations where symbols are added sporadically, this may lead to situations where the repair_interval is not reached before a symbol is about to expire. In this case you need to use the flush API to ensure that all symbols get the configured level of protection (see rely::encoder::flush()).

Changing the Timeout

In some situations we may experience cases where the configured timeout needs to be changed. This could be because the network latency has decreased or increased causing us to have either more or less time for Rely.

When increasing the timeout we have more time to protect the data consumed by Rely and no specific considerations are needed.

However, when decreasing the timeout we may have a situation where we suddenly have expired unprotected symbols in Rely. In general this situation can be handled by the rely::encoder::flush() mechanism, which is designed to ensure that symbols that have just expired will be protected by repair. However, when changing the timeout some symbols may be so old that providing repair for them no longer makes sense. To accommodate for this we can use the rely::encoder::catch_up() mechanism which allows us to drop symbols older than a given threshold.

Mode #2: Manual Repair

In the “manual repair” mode we control the generation of repair traffic. This is done via the rely::encoder::generate_repair() function. Using this approach we can implement Content-Aware Coding coding by calling rely::encoder::generate_repair() e.g. after all payloads of a specific video frame have been added.

See the Content-Aware Coding for more details.

The default mode of a Rely encoder is “manual repair”. Unless you specify a repair trigger you will fully control when and how repair is generated.

When using “manual repair” we have to be careful to ensure that symbols receive the desired level of protection.