Quality Management - Storm JavaScript Library

In this guide, we’ll explain in detail how quality management and selection work in the Storm JavaScript Library. We’ll also show you how to implement quality selection on the user side and how to tailor the quality selection strategy to your needs.

Server/Cloud-side Configuration

Both Storm Streaming Server and Storm Streaming Cloud are capable of delivering optimized versions of a stream in the form of lower-quality substreams (lower resolution and bitrate than the original).

• In Storm Streaming Server, transcoding must be explicitly enabled within the application, along with properly prepared transcoding templates.
• In Storm Streaming Cloud, transcoding is enabled per stream during its creation - if the subscription plan allows it.

Quality List

When a stream is designated for transcoding, the server sends a list of available quality variants via the qualityListUpdate event, which is typically dispatched right after subscribing to a given streamKey. Importantly, this event may also be triggered during an ongoing stream - for example, when new substreams are created or removed:

                        
storm.addEventListener("qualityListUpdate", (event) => {
    console.log(event.qualityList); // new quality list for our player
});
                    

The event’s qualityList parameter is an array of available qualities. It can also be retrieved using the base API method getQualityItemList():

Each qualityItem object contains the following fields:

Manual Quality Selection

To manually activate a specific quality, use the playQualityItem() method with the desired quality id. The special "Auto" item always has id == 0:

                        
storm.playQualityItem(qualityItem.id);
                    

Quality Selection Mechanism

The library uses quality selection logic based on the chosen control mechanism. This can be configured via the stream configuration object or set dynamically using the API:

                        
const streamConfig = {
    stream: {
        ... // stream settings
    },
    settings: {
        ... // general settings
        video: {
            ... // video settings
        },
        quality: {
            controlMode: "RESOLUTION_AWARE", // quality control method
            initialUpgradeTimeout: 30,
            maxUpgradeTimeout: 3600
        }
    }
};
                    

Alternatively:

                        
storm.setQualityControlMode(QualityControlMode.RESOLUTION_AWARE, true);
// `true` means the current source will be reloaded immediately
                    

There are four basic quality control modes:

• RESOLUTION_AWARE
• PASSIVE
• HIGHEST_QUALITY
• LOWEST_QUALITY

Dynamic Quality Control (Auto Mode)

The core purpose of the quality control system is to select the most suitable substream based on current bandwidth and playback conditions.

This feature is available only when the “Auto” quality option is enabled.

• Trigger

  The downgrade process starts when the video buffer empties twice within 30 seconds.

  • The buffer has an initial value (typically around 0.5 seconds) and a minimum threshold.
  • Dropping below the minimum triggers a buffering state.
  • The player pauses playback until the buffer recovers.
  
  
• Quality Downgrade

  When triggered, the library chooses a lower quality stream based on average bandwidth calculations. It may drop by one level or directly to the lowest level available.

  This triggers the upgrade testing cycle, controlled by initialUpgradeTimeout.

• Grace Period & Escalation

  After a downgrade, the player waits for the initialUpgradeTimeout duration before attempting to upgrade to a higher quality.

  If another buffer depletion occurs during this period, the quality is downgraded again, and the wait time before future upgrades increases exponentially, up to maxUpgradeTimeout.

  Selecting any non-Auto quality option resets all gathered bandwidth statistics and quality preferences .