Quality Management - Storm JS Player Core

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:

Quality list event

javascript

Copy

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:

Manual quality selection

javascript

Copy

storm.playQualityItem(qualityItem.id);

Quality Selection Mechanism

The player 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:

Quality configuration

javascript

Copy

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

Alternatively:

Dynamic quality control mode

javascript

Copy

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

There are four basic quality control modes:

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.

1. 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.

2. Quality Downgrade - When triggered, the player 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.

3. 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.