Subscribing to a Stream - Storm JS Player Core

One of the core and most important features of the Storm JS Player Core is the ability to dynamically subscribe to any stream based on a provided streamKey. Once the player is subscribed to a given stream, it will start receiving notifications about its state changes or updates (e.g., the stream has been published or, conversely, has ended).

Subscribing to a Stream

There are two ways to subscribe to a stream. For example, we can configure the player by immediately providing the streamKey we're interested in:

Configuration with streamKey

javascript

const streamConfig = {
    stream: {
        serverList: [{
            host: "yourdomain.com",
            application: "live",
            port: 443,
            ssl: true
        }],
        streamKey: "test",          // our streamKey goes here
    },
    settings: {
        video: {
            containerID: "videoHolder",
            aspectRatio: "16:9",
            width: "100%",
        },
    }
}

const storm = stormPlayerCore(streamConfig);

However, we can also omit the streamKey field and call the appropriate method instead:

Dynamic subscription

javascript

const storm = stormPlayerCore(streamConfig);
storm.initialize();

storm.subscribe("test");

Once the player has been initialized via the initialize() method, we can freely switch between streams by calling this method again with a new key.

Related Events and Their Handling

When the subscribe method is called, a series of events will be triggered to inform us about what is happening during the subscription process:

Subscription events

javascript

storm.addEventListener("subscriptionStart", () => {
  // Subscription has been started
});

storm.addEventListener("subscriptionComplete", () => {
  // Stream exists and subscription is now complete
});

storm.addEventListener("subscriptionFailed", () => {
  // Stream does not exist and subscription has failed
});

A very important event that allows us to track the state of the subscribed stream is streamStateChange. Every time the stream's state changes, the player object will trigger this event to notify us of the new state. This mechanism is especially useful when the stream initially doesn't exist (NOT_FOUND), but later becomes available (PUBLISHED).

Stream state change handling

javascript

storm.addEventListener("streamStateChange", (event) => {
  switch(event.state){
    case "NOT_FOUND":
      // stream does not exist yet
      break;
    case "AWAITING":
      // stream exists, it's initialized, but there is no audio/video data yet
      break;
    case "NOT_PUBLISHED":
      // stream exists, audio/video data are there, but viewers are not allowed to watch it just yet
      break;
    case "PUBLISHED":
      // stream is live
      break;
    case "UNPUBLISHED":
      // stream was live, but it's not anymore
      break;
    case "STOPPED":
      // stream has stopped
      break;
    case "CLOSED":
      // stream is closed
      break;
  }
});

Note

The PUBLISHED event will also be triggered when substreams with different qualities are added to or removed from the stream. More information can be found on the Quality Management page.

You can also always retrieve the current state using the provided API:

Get current state

javascript

let currentState = storm.getStreamState();

If you want to learn more about the stream states and their meanings, a full description is available on the player Events page.

Unsubscribing from a Stream

Once subscribed, the player will continuously receive notifications about stream state changes. If we want the player object to stop monitoring a specific streamKey, we need to unsubscribe from it:

Unsubscribe

javascript

storm.unsubscribe();

Support Needed?

If you have any questions or need assistance, please create a support ticket and our team will help you.