Storm JavaScript Streamer

StormStreamer is a core web broadcasting component for publishing live-video streams from a website. It is a part of Storm Streaming Suite and requires a Storm Streaming Server instance or Cloud subscription to work. This library contains only core network and media functionality for streaming from cameras and microphones and comes with no GUI (user interface).

This library comes in IIFE, ESM, AMD, UMD, and CJS versions (if you don't know these, grab IIFE, and it will be OK). Typings are now also included.

Installation

1. Using NPM:

npm install @stormstreaming/stormstreamer

2. Using Yarn:

yarn add @stormstreaming/stormstreamer

3. Manually - if you are clueless about NPM/Yarn or simply want to test it out, just grab/dist/iife/index.js file and embed it on your website.

Attaching and detaching events

/**
 * An event can be registered using the addEventListener method (preferably before the initialize() method is called)
 */
stormStreamer.addEventListener("streamerReady", onStreamerReady);

/**
 * Inline functions work well too...
 */
stormStreamer.addEventListener("streamerReady", function(event){
    console.log("streamerReady!");
});

/**
 * An event can also be removed...
 */
stormStreamer.removeEventListener("streamerReady", onStreamerReady);

/**
 * All event listeners of a specific type can be removed like this
 */
stormStreamer.removeEventListener("streamerReady");

Starting and stopping devices (manual method)

 /**
 * Starts cameras/microphones (might initiate a popup in a browser)
 */
stormStreamer.start();

/**
 * Stops all cameras/microphones
 */
stormStreamer.stop();

Publishing and unpublishing to a streamKey (manual method)

 /**
 * Publishing to streamKey called "test" (make sure that a camera and microphone are active via getInputDevicesState() == READY)
 */
stormStreamer.publish("test");

/**
 * Unpublishes stream.
 */
stormStreamer.unpublish();

Attaching and detaching streamer (manual method)

 /**
 * Attaching streamer to a container by container ID
 */
stormStreamer.attachToContainer("containerName");


/**
 * Attaching streamer to a container by a reference
 */
const myContainer = document.getElementById("containerName")
stormStreamer.attachToContainer(myContainer);

/**
 * Detaching streamer from a container (it'll also stop the stream)
 */
stormStreamer.detachFromContainer();

Resizing streamer (manual method)

 /**
 * Setting streamer width and height to 100% of its parent
 */
stormStreamer.setSize("100%", "100%");

/**
 * Setting width and height to 1280x720
 */
stormStreamer.setSize("1280px", "720px");

/**
 * Setting just width to 100%
 */
stormStreamer.setWidth("100%");

/**
 * Setting height to 720px
 */
stormStreamer.setHeight("720px");

StormStreamer Event List

| Event name | Additional data | Description | |:------------------------------|:-------------------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | streamerReady | - | Triggered when a streamer instance is initialized via the initialize() method. | | serverConnectionInitiate | serverURL:string | Fired when a streamer instance initiates a connection with a Storm Streaming Server/Cloud instance. | | serverConnect | serverURL:string, sequenceNum:number | Triggered when a streamer instance successfully establishes a connection with a Storm Streaming Server/Cloud instance. | | statusServerConnect | serverURL:string, sequenceNum:number | Triggered when a streamer instance successfully establishes a connection with a status server. | | serverDisconnect | serverURL:string, restart:boolean, sequenceNum:number | Called when a streamer instance is disconnected from the Storm Streaming Server/Cloud (after a connection was previously established), which may occur due to publisher networking issues or Storm Streaming Server/Cloud problems. | | statusServerDisconnect | serverURL:string, restart:boolean, sequenceNum:number | Called when a streamer instance is disconnected from the status server. | | serverConnectionError | serverURL:string, restart:boolean, sequenceNum:number | Triggered when a streamer instance fails to establish a connection with a Storm Streaming Server/Cloud instance, possibly due to networking issues. If there are additional servers on the configuration list and the "restartOnError" parameter is set to true, the streamer will attempt to connect to a different server instead. | | statusServerConnectionError | serverURL:string, restart:boolean, sequenceNum:number | Triggered when a streamer instance fails to establish a connection with a status server. | | allConnectionsFailed | mode:string | Associated with serverConnectionError. If a streamer instance is unable to connect to any of the servers provided in the configuration list, this event indicates that no further action can be taken. | | interactionRequired | mode:string | Certain browsers and devices do not permit a video element to initiate on its own and necessitate direct user interaction, such as a mouse click or a touch gesture. This event signifies that such an engagement is required. | | compatibilityError | message:string | Triggered if a browser or device does not support the required features for streaming. Please note that the streamer will attempt all possible measures to ensure maximum compatibility with a given device. | | playbackForcePause | - | Fired when the preview playback is forcefully paused by the system (not by user interaction). | | playbackForceMute | - | Fired when the preview playback is forcefully muted by the system (not by user interaction). | | volumeChange | volume:number, muted:boolean, invokedBy:"user" | "browser" | Notifies that video volume was changed (either its value was changed, or video was muted/un-muted). | | videoElementCreate | videoElement:HTMLVideoElement | Triggered whenever a video element within a streamer instance is either created or recreated. | | containerChange | container:HTMLElement | null | Fired whenever a streamer is detached or attached to a new container. | | resizeUpdate | width:number, height:number | Triggered when the video preview size is changed or updated. | | videoUnmuted | - | Fired when the video preview is successfully unmuted. | | SSLError | mode:string | Fired if an SSL layer is required for streaming and the browser does not provide it. | | incompatibleProtocol | clientProtocolVer:number, serverProtocolVersion:number | Fired when there is a protocol version mismatch between the client and server. | | authorizationError | - | Fired when a streamer instance fails to authorize with a server application on Storm Streaming Server/Cloud instance (e.g. incorrect token). | | authorizationComplete | - | Called when a streamer instance successfully authorizes with a server application on Storm Streaming Server/Cloud instance. | | invalidLicense | - | Fired whenever a Storm Streaming Server/Cloud license expires. | | streamConfigChange | newConfig:ConfigManager | Notifies that basic stream configuration has been updated. | | fullScreenEnter | - | Fired whenever a streamer instance enters browser fullscreen mode (either native or overlay type). | | fullScreenExit | - | Fired whenever a streamer instance exits fullscreen mode (either native or overlay type). | | noCameraFound | - | Triggered when no camera device is found on the system. | | publishStateChange | state:PublishState | Notifies about changes in the publishing state (e.g., NOT_INITIALIZED, INITIALIZING, PUBLISHING, etc.). | | noMicrophoneFound | - | Triggered when no microphone device is found on the system. | | deviceListUpdate | cameraList:InputDevice[], microphoneList:InputDevice[] | Fired when the list of available input devices (cameras and microphones) is updated. | | inputDeviceError | - | Triggered when there is an error accessing or using an input device. | | cameraAccessDenied | - | Fired when camera access permission is denied by the user or the system. | | deviceStateChange | state:InputDevicesState, selectedCamera:InputDevice | null, selectedMicrophone:InputDevice | null | Notifies about changes in the state of input devices and provides information about selected camera and microphone. | | publishMetadataUpdate | metadata:PublishMetadata | Fired when new metadata about the publishing stream is available. | | streamStatusUpdate | streamStatus:StreamStatusInfo | Provides updated information about the status of the published stream on the server. | | cameraDeviceStateChange | state:DeviceState, selectedCamera:InputDevice | null | Notifies about changes in the camera device state and provides information about the selected camera. | | microphoneDeviceStateChange | state:DeviceState, selectedMicrophone:InputDevice | null | Notifies about changes in the microphone device state and provides information about the selected microphone. | | microphoneAccessDenied | - | Fired when microphone access permission is denied by the user or the system. | | savedCameraNotFound | savedDeviceID:string | null | Triggered when a previously saved camera device is no longer available on the system. | | savedMicrophoneNotFound | savedDeviceID:string | null | Triggered when a previously saved microphone device is no longer available on the system. | | streamKeyInUse | streamKey:string | Fired when attempting to publish with a stream key that is already in use by another publisher. | | streamKeyInUseInterval | streamKey:string, count:number, maxCount:number | Fired periodically when attempting to publish with a stream key that is already in use, providing retry count information. | | soundMeter | high:number, low:number | Provides real-time audio level information from the microphone. | | microphoneStateChange | isMuted:boolean | Notifies about changes in the microphone mute state. | | metadata | videoWidth:number, videoHeight:number | Provides metadata about the video being published, including dimensions. | | publish | streamKey:string | Fired when publishing to a stream key is initiated. | | unpublish | - | Fired when publishing is stopped. |

Basic API

| Method | Returns | Return type | Description | |:---------------------------------------------------------|:-----------------------------------------------------------------:|:------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | initialize() | - | void | Initializes the streamer object. From this point, a connection to the server is established and authentication occurs. It is recommended to add all event listeners before calling this method to ensure they can be properly captured. | | isInitialized() | true if this streamer instance was already initialized | boolean | Returns true if this streamer instance has already been initialized. | | isConnected() | true if this streamer instance is connected to a server | boolean | Returns true if this streamer instance is currently connected to a Storm Server/Cloud instance. | | getStreamerID() | Streamer ID (first instance starts with 0, next one gets 1, etc.) | number | Returns the unique ID of this streamer instance. Each subsequent instance has a higher number. | | getBranch() | Name of a development branch | string | Returns the development branch of this streamer (e.g., main, experimental). | | getVersion() | Streamer version in xx.xx.xx format | string | Returns the version of this streamer instance. The version is returned in the SemVer format (Major.Minor.Patch). | | start() | - | Promise | Starts the streaming process. | | stop() | - | void | Stops the streaming process. | | mute() | - | void | Mutes the streamer's video object. Audio output will be silenced. | | unmute() | - | void | Unmutes the streamer's video object. Audio output will be restored. | | toggleMute() | New mute state after toggling | boolean | Toggles between mute and unmute states. Returns the new mute state. | | isMute() | true if the streamer is muted | boolean | Checks whether the streamer audio is currently muted. | | setVolume(newVolume:number) | - | void | Sets new volume for the streamer (0-100). Once the method is performed, the volumeChange event will be triggered. If the video was muted prior to the volume change, it will be automatically unmuted. | | getVolume() | Current volume level 0-100 | number | Returns current streamer volume (0-100). | | getCameraList() | Array containing available cameras | InputDevice[] | Returns the list of available camera devices. | | getMicrophoneList() | Array containing available microphones | InputDevice[] | Returns the list of available microphone devices. | | setCamera(cameraID:string) | - | void | Sets the active camera device by ID. | | setMicrophone(microphoneID:string) | - | void | Sets the active microphone device by ID. | | getCurrentCamera() | Currently active camera or null | InputDevice | null | Returns the currently active camera device or null if none is active. | | getCurrentMicrophone() | Currently active microphone or null | InputDevice | null | Returns the currently active microphone device or null if none is active. | | muteMicrophone(microphoneState:boolean) | - | void | Mutes or unmutes the microphone. True to mute, false to unmute. | | isMicrophoneMuted() | true if the microphone is currently muted | boolean | Checks if the microphone is currently muted. | | getPublishState() | Current publish state | PublishState | Returns the current publishing state of the streamer. | | getPublishTime() | Time in milliseconds since publishing | number | Returns the total time the stream has been publishing in milliseconds. | | publish(streamKey:string) | true if publishing was successfully initiated | boolean | Starts publishing a stream with the given stream key. | | unpublish() | - | void | Stops publishing the current stream. | | getInputDevicesState() | Current state of input devices (camera and microphone) | InputDevicesState | Returns the current state of input devices (camera and microphone). | | getCameraState() | Current camera device state | DeviceState | Returns the current state of the camera device. | | getMicrophoneState() | Current microphone device state | DeviceState | Returns the current state of the microphone device. | | clearSavedDevices() | - | void | Clears saved device preferences from storage. | | messSavedDevices() | - | void | Randomizes saved device preferences (for testing purposes). | | isStreamReady() | true if the stream is ready for publishing | boolean | Checks if the stream is ready for publishing. | | setSize(width:number/string, height:number/string) | - | void | Sets a new width and height for the streamer. The values can be given as a number (in which case they are treated as the number of pixels), or as a string ending with "px" (this will also be the number of pixels) or "%", where the number is treated as a percentage of the parent container's value. | | setWidth(width:number/string) | - | void | Sets a new width for the streamer. The value can be given as a number (in which case it is treated as the number of pixels), or as a string ending with "px" (this will also be the number of pixels) or "%", where the number is treated as a percentage of the parent container's value. | | getWidth() | Streamer object width | number | Returns current streamer width in pixels. | | setHeight(height:number/string) | - | void | Sets a new height for the streamer. The value can be given as a number (in which case it is treated as the number of pixels), or as a string ending with "px" (this will also be the number of pixels) or "%", where the number is treated as a percentage of the parent container's value. | | getHeight() | Streamer object height | number | Returns current streamer height in pixels. | | updateToSize() | - | void | Forces the streamer to recalculate its size based on parent internal dimensions. | | setScalingMode(newMode:string) | - | void | Changes the streamer scaling mode. Available modes include fill, letterbox, original, and crop. | | getScalingMode() | Current scaling mode | ScalingType | Returns the current streamer scaling mode. | | setStreamConfig(config:StreamerConfig) | - | void | Sets stream config for the streamer (or overwrites an existing one). | | makeScreenshot() | A promise containing either a blob or null | Promise<Blob | null> | Returns a promise that resolves with a screenshot of the video element as a blob, or null if taking the screenshot was not possible. | | destroy() | - | void | Destroys this instance of StormStreamer, releasing all resources and disconnecting from the server. After calling this method, the instance should not be used anymore. | | createFPSGraph(container:string \| HTMLElement) | Graph for FPS performance | FPSGraph | Creates a FPS performance graph in the specified location (container ID or reference). The graph is a separate object that must be started using its start() method and stopped using its stop() method. The dimensions of the graph depend on the dimensions of the specified container. | | createBitrateGraph(container:string \| HTMLElement) | Graph for bitrate performance | BitrateGraph | Creates a bitrate performance graph in the specified location (container ID or reference). The graph is a separate object that must be started using its start() method and stopped using its stop() method. The dimensions of the graph depend on the dimensions of the specified container. | | createMicrophoneGraph(container:string \| HTMLElement) | Graph for microphone input | MicrophoneGraph | Creates a microphone input graph in the specified location (container ID or reference). The graph is a separate object that must be started using its start() method and stopped using its stop() method. The dimensions of the graph depend on the dimensions of the specified container. | | stopAllGraphs() | - | void | Stops all active performance graphs. | | attachToContainer(containerID:string \| HTMLElement) | true if attaching was successful | boolean | Attaches the streamer to a new parent container using either a container ID (string) or a reference to an HTMLElement. If the instance is already attached, it will be moved to a new parent. | | detachFromContainer() | true if detaching was successful | boolean | Detaches the streamer from the current parent element, if possible. | | getContainer() | Parent HTMLElement or null | HTMLElement | null | Returns the current parent element of the streamer, or null if none exists. | | enterFullScreen() | - | void | Enters fullscreen mode for the streamer container. | | exitFullScreen() | - | void | Exits fullscreen mode. | | isFullScreenMode() | true if the streamer is in fullscreen mode | boolean | Returns true if the streamer is currently in fullscreen mode. | | getStreamKey() | Current stream key or null | string | null | Returns the current stream key or null if none is set. | | getStatsController() | Object containing streaming statistics | StatsController | null | Returns the Stats Controller instance which contains statistical data about streaming performance. | | getVideoElement() | Reference to the main Video Element | HTMLVideoElement | null | Returns the HTML video element used by this streamer instance. | | getNetworkController() | Object responsible for managing server communication | NetworkController | null | Returns the network controller which manages all server communication. | | getStreamerController() | Object responsible for media stream operations | StreamerController | null | Returns the streamer controller which manages media stream operations. | | getStageController() | Object responsible for visual presentation | StageController | null | Returns the stage controller which manages visual presentation. | | getStorageManager() | Object responsible for data storage | StorageManager | null | Returns the storage manager which handles persistent data storage. |

Objects & Enums

InputDevice Getters

| Getter | Return Type | Description | |:-------------|:------------|:---------------------------------------------------------------| | label | string | Returns the display name of the input device. | | id | string | Returns the unique identifier of the input device. | | groupID | string | Returns the group identifier that the input device belongs to. | | isSelected | boolean | Returns whether the input device is currently selected. |

PublishState Enum

| Value | Description | |:------------------|:--------------------------------------------| | NOT_INITIALIZED | Initial state, before initialization. | | INITIALIZED | Component has been initialized. | | CONNECTING | In the process of connecting to the server. | | CONNECTED | Connected to the server. | | PUBLISHED | Stream is actively being published. | | UNPUBLISHED | Stream has been stopped (by user). | | STOPPED | Stream has been stopped (by system). | | UNKNOWN | Unknown state. | | ERROR | An error occurred during publishing. |

DeviceState Enum

| Value | Description | |:------------------|:--------------------------------------------------------------| | NOT_INITIALIZED | Initial state, device has not been initialized yet. | | ENABLED | Device is enabled and ready to use. | | ACCESS_DENIED | Permission to access the device was denied by user or system. | | NOT_FOUND | Device could not be found on the system. | | STOPPED | Device has been intentionally stopped. |

InputDevicesState Enum

| Value | Description | |:------------------|:------------------------------------------------------------------| | NOT_INITIALIZED | Initial state, input devices have not been initialized yet. | | INITIALIZED | Input devices have been initialized but may not be ready for use. | | READY | Input devices are initialized and ready for use. | | UPDATING | Input devices list or configuration is currently being updated. | | INVALID | Input devices configuration is invalid or incompatible. | | UNKNOWN | Input devices state cannot be determined. | | STOPPED | Input devices have been intentionally stopped. |

ScalingType Enum

| Value | Description | |:-------------|:------------------------------------------------------------------------------------------| | FILL | Scales content to fill the entire container, may distort aspect ratio. | | LETTER_BOX | Scales content to fit within container while preserving aspect ratio, may add black bars. | | CROP | Scales content to fill container while preserving aspect ratio, may crop edges. | | ORIGINAL | Displays content at its original size without scaling. |

Browser compatibility

• Edge 12+
• Chrome 31+
• Firefox 42+
• Safari 13+
• Opera 15+

License

• License