overwolf.streaming

This namespace contains all the functionality that allows the streaming of video/audio.

The term streaming might be a bit misleading – we regard saving a video to the local drive as streaming, as well as streaming the video to a streaming service such as Twitch.tv.

 

The basic usage flow should be:

  1. Register to the onStopStreaming event – know when the streaming stopped:
    overwolf.streaming.onStopStreaming.addListener(function(result) {
      //result.stream_id
      //result.url (relevant to video only)
    });
  2. Register to the onStreamingError event – know if a streaming error occurred which will also stop the streaming session:

    NOTE: we only started with the UPPERCASE convention later on.

    overwolf.streaming.onStreamingError.addListener(function(result) {
      //result.stream_id
      /*
        result.error = (one of):
          "Unknown"
          "Unauthorized"
          "Invalid_Server"
          "No_Internet"
          "Invalid_Video_Settings"
          "No_Playback_Device"
          "Not_InGame"
          "Internet_Congested"
          "Twitch_Dll_Load_Error"
          "Twitch_Init_Error"
          "MEDIA_PLAYER_DLL_ERROR"
          "No_Encoder"
          "Out_Of_Disk_Space"
    
          "CAPTURE_DEVICE_ERROR"
          "CAPTURE_DEVICE_NO_FRAMES"
          "GAME_UNSUPPORTED_FORMAT_ERROR"
          "KRAKEN_DEVICE"
          "PLAYBACK_DEVICE_FORMAT"
          "INPUT_DEVICE_FORMAT"
          "NVIDIA_UPDATE_DRIVER"
          "NVIDIA_ENCODER"
          "CPU_OVERLOADED"
          "FILE_OUTPUT_ERROR"
          "SWITCHABLE_GRAPHICS_SHT_UNSUPPORTED"
          "NO_CAPTURE_DEVICE"  
      */
    });
    
  3. Register to the onStreamingWarning event – know when a warning occurred
    overwolf.streaming.onStreamingWarning.addListener(function(result) {
      //result.stream_id
      //result.error = "HIGH_CPU_USAGE" // there will probably be frames lost
    });
  4. Optionally register to: onStreamingSourceImageChanged to get an event when the user switched between capturing his desktop and the game.
  5. Call overwolf.streaming.getStreamEncoders and overwolf.streaming.getAudioDevices, this will give a list of all possible encoders and audio devices – you can then use this list to let the user select his preferred encoder/device.

    In terms of encoder priorities – we recommend: NVIDIA > AMD > INTEL > x264

    As long as the “enabled” field = true, you can offer the user to use the encoder.

  6. Create a JSON object with all of the streaming details (See example on the top of the page) and call overwolf.streaming.start

    • For video recording you don’t need the “ingest_server”, “stream_info” and “auth” objects.
    • For video recording we recommend using a max_kbps value of higher than 8000.
    • For streaming we recommend using a max_kbps smaller than 3000.

      Once start succeeded, you’ll get a callback with result.status == "success" and a stream_id that can be used to stop the streaming session or change the volume of the stream.

  7. Allow the user to change volume with: overwolf.streaming.changeVolume while streaming.
  8. Call: overwolf.streaming.stop to stop the streaming session

EXTRAS:

  1. Use setBRBImage when streaming to Twitch.tv when capture_desktop is not enabled, this will allow you to customize the Be-Right-Back image the viewers will see.
  2. Use setWindowStreamingMode for video recording and streaming – this method works on a per-overwolf-window basis – for each window you can decide if it is to be shown in the stream or not – regardless of whether the streamer is viewing it or not.
  3. Use setWindowObsStreamingMode when you aren’t streaming with Overwolf but want to leverage Overwolf’s APIs and stream with OBS.

 

Methods

start(settings, callback)

Version added: 0.78

Start a new stream.

Example:

overwolf.streaming.start(
    {
      "provider": overwolf.streaming.enums.StreamingProvider.Twitch,
      "settings": {
        "stream_info": {
          "url": "http://www.twitch.tv/{twitch_user_name}",
          "title": "title"
        },
        "auth": {
          "client_id": "{twitch_client_id}",
          "token": storage.get('login-token')
        },
        "audio": {
          "mic": {
            "volume": 100,
            "enabled": true
          },
          "game": {
            "volume": 75,
            "enabled": true
          }
        },
        "video": {
          "auto_calc_kbps": false,
          "fps": 30,
          "width": 1920,
          "height": 1080,
          "max_kbps": 1500,
          "notify_dropped_frames_ratio": 0.5,
          "test_drop_frames_interval": 5000,
          "encoder": {
            "name": overwolf.streaming.enums.StreamEncoder.X264,
            "config": {
              "preset": overwolf.streaming.enums.StreamEncoderPreset_x264.ULTRAFAST,
              "rate_control": overwolf.streaming.enums.StreamEncoderRateControl_x264.RC_CBR,
              "keyframe_interval": 2
            }
          }
        },
        "ingest_server": {
          "name": "US West: San Francisco, CA",
          "template_url": "rtmp://live.twitch.tv/app/{stream_key}"
        },
        "peripherals": {
          "capture_mouse_cursor": "both"
        }
      }
    },
    function(result) {
        if (result.status == "success")
        {
            console.debug(result.stream_id);
        }
    }
);
  • Parameter: settings <StreamSettings>

    The stream settings.

  • Parameter: callback <function>

    A function that will be called with a JSON containing the status

    Example:

    { "status": "success", "stream_id": 1 } 
    { "status": "error", "error": "something went wrong..." }
    
Callback argument:
{
    "status": "success",
    "stream_id": 1
}

stop(streamId, callback)

Stops the given stream.

  • Parameter: streamId <int>

    The id of the stream to stop.

  • Parameter: callback <function>

    A function that will be called with a JSON containing the status and the stream id if successful.

    Example:

    { "status": "success", "stream_id": 1 } 
    { "status": "error", "error": "something went wrong..." }
    
Callback argument:
{
    "status": "success",
    "stream_id": 1
}

changeVolume(streamId, audioOptions, callback)

Changes the volume of the stream.

  • Parameter: streamId <int>

    The id of the stream on which the volume is changed.
  • Parameter: audioOptions <StreamAudioOptions>

    The new volumes encapsulated in an object.
  • Parameter: callback <function>

    A function that will be called with success or error status.

setWatermarkSettings(settings, callback)

Sets the watermark settings.

Example:

overwolf.streaming.setWatermarkSettings(
    { showWatermark : true },
    function (result) {
        console.log ("watermark settings changed.");
    }
);
  • Parameter: settings <WatermarkSettings>

    The new watermark settings.
  • Parameter: callback <function> — Optional

    A callback to call when done setting the new watermark settings.

getWatermarkSettings(callback)

Version added: 0.78

Gets the watermark settings.

  • Parameter: callback <function>

    A function that will be called with a JSON containing the status and the watermark settings if successful or an error message if not.

getWindowStreamingMode(windowId, callback)

Version added: 0.78

Call the given callback function with the window’s streaming mode as a parameter.

  • Parameter: windowId <string>

    The id of the window for which to get the streaming mode.
  • Parameter: callback <function>

    The callback function to call with the window’s streaming mode as a parameter.

setWindowStreamingMode(windowId, streamingMode, callback)

Version added: 0.78

Set the window’s stream mode.

  • Parameter: windowId

    The id of the window for which to set the streaming mode.
  • Parameter: streamingMode <overwolf.streaming.enums.StreamingMode>

    The desired streaming mode.
  • Parameter: callback <function> — Optional

    A function called after streaming mode was set indicating success, or error in case of an error.

setWindowObsStreamingMode(windowId, obsStreamingMode, callback)

Version added: 0.78

Sets the streaming mode for the window when using OBS.

setBRBImage(streamId, image, backgroundColor, callback)

Set a stream’s Be Right Back image.

  • Parameter: streamId <int>

    The id of the stream for which to set the Be Right Back image.
  • Parameter: image <object>

    The image to set, as an IMG object or a URL.
  • Parameter: backgroundColor <string>

    The color to paint the last game frame with before overlaying the image.
  • Parameter: callback <function> — Optional

    A callback function to call with success or failure indication.

getStreamEncoders(callback)

Version added: 0.83

Returns an array of supported streaming encoders, with extra metadata for each one.

  • Parameter: callback <function>

    A callback function to call with the array of encoders and their metadata.
Callback argument:
{
    "status": "success",
    "encoders": [
        {
            "name" : "INTEL",
            "display_name" : "Intel® Quick Sync (uses iGPU)",
            "enabled" : true,
            "presets" : ["LOW", "MEDIUM", "HIGH"]
        },
        ...
    ]
}

getAudioDevices(callback)

Version added: 0.78

Returns an array of all audio devices that can be used.

  • Parameter: callback <function>

    A callback function to call with the array of audio devices and their metadata.
Callback argument:
{
    "status": "success",
    "devices": [
        {
            "display_name" : "Speakers (USB Ear-Microphone)",
            "display_id" : "{0.0.0.00000000}.{ec2a6c4b-f750-4045-bb93-d745ecc76937}",
            "device_state" : "Active",
            "can_record" : false,
            "can_playback" : true
        },
        ...
    ],
    "default_recording_device_id": "{0.0.0.00000000}.{ec2a6c4b-f750-4045-bb93-d745ecc76937}",
    "default_playback_device_id": "{0.0.1.00000000}.{39da502b-2b96-4b76-83ae-9841f0b46570}"
}

updateStreamingDesktopOptions(streamId, newOptions, mouseCursorStreamingMethod, callback)

Version added: 0.83

Update stream desktop capture options.

  • Parameter: streamId <int>

    The id of the stream for which to set the Be Right Back image.

  • Parameter: newOptions <StreamDesktopCaptureOptions>

    The updated desktop capture streaming options.

  • Parameter: mouseCursorStreamingMethod <overwolf.streaming.enums.StreamMouseCursor>

    The updated value of the mouse cursor streaming method.
  • Parameter: callback <function>

    A callback function to call with success or failure indication.

updateTobiiSetting(streamId, param, callback)

Version added: 0.97

Update Tobii streaming layer.

  • Parameter: streamId <int>

    The id of the stream.

  • Parameter: param <TobiiLayerParams>

    The Tobii layer visibility param.

  • Parameter: callback <function>

    A callback with the result.

Events How to use events

onStreamingSourceImageChanged

Version added: 0.78

Fired when the stream started streaming a new image source (desktop, game).

onStopStreaming

Version added: 0.78

Fired when the stream has stopped.

onStreamingError

Version added: 0.78

Fired upon an error with the stream.

Possible error codes:

  • Unknown
  • Unauthorized
  • Invalid_Server
  • No_Internet
  • Invalid_Video_Settings
  • No_Playback_Device
  • Not_InGame
  • Internet_Congested
  • Game_Quit_Mid_Stream
  • Twitch_Dll_Load_Error
  • Twitch_Init_Error
  • No_Encoder
  • Out_Of_Disk_Space
  • NVIDIA_UPDATE_DRIVER
Event value:
{
    "status": "error",
    "stream_id": 1,
    "error": "Internet_Congested"
}

onStreamingWarning

Fired upon a warning with the stream.

onVideoFileSplited

Version added: 0.103.200

Fired upon video file splited

Types

overwolf.streaming.enums.ObsStreamingMode

Options

OBSNoAwareness

The default Overwolf window style.

OBSAwareness

Allows to capture the window using Overwolf OBS plugin and will not be visible ingame or by Overwolf capturing apps (will still be visible in desktop).

OBSAwarenessHideFromDeskTop

Same as OBSAwareness but also not visible in desktop (hidden).

overwolf.streaming.enums.StreamingMode

Options

WhenVisible

Stream the window when it is visible. This is the default behavior. The viewers will see what you see.

Always

Always stream the window, even when it is hidden or minimized. The viewers will continue to see it while you don’t.

Never

Never stream the window. The viewers will not see the window even if you do see it.

overwolf.streaming.enums.StreamingProvider

Options

Unknown

Twitch

Stream to Twitch.

VideoRecorder

RTMP

Stream to YouTube, Facebook, smashcast.tv, etc.

StreamParams

Represents the settings required to start a stream.

Properties

stream_info

Version added: 0.78

The basic stream information.

Type: StreamInfo

auth

Version added: 0.78

Stream authorization data.

Type: StreamAuthParams

video

Version added: 0.78

Stream video options.

Type: StreamVideoOptions

audio

Version added: 0.78

Stream audio options.

Type: StreamAudioOptions

peripherals

Version added: 0.83

Defines how peripherals (i.e. mouse cursor) are streamed.

Permissions required: DesktopStreaming

Type: StreamPeripheralsCaptureOptions

ingest_server

Version added: 0.78

Information on the server that is being streamed to.

Type: StreamIngestServer

replay_type

The replay type to use.

Type: ReplayType

gif_as_video

Create gif as video (Gif Replay Type only).

Type: bool

max_quota_gb

Version added: 0.105.0

Max media folder size in GB

Type: double

StreamSettings

Stream settings container.

Properties

provider

Version added: 0.78

The stream provider name.

Type: overwolf.streaming.enums.StreamingProvider

settings

Version added: 0.78

The stream provider settings.

Type: StreamParams

WatermarkSettings

A settings container for a stream Overwolf watermark settings.

Properties

showWatermark

Version added: 0.78

Determines whether or not to display the Overwolf watermark on the stream.

Type: bool

overwolf.streaming.enums.StreamEncoderPreset_Intel

Defines which preset to use with the Intel encoder.

Options

LOW

MEDIUM

HIGH