Skip to main content

overwolf.streaming API

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.

Permissions required: Streaming

info

Please check the streaming API sample app that demonstrates a primary usage in the API. Please read all the info about streaming usage and options on our video capture best practices guide.

Methods Reference

Events Reference

Types Reference

Sample app

In our APIs sample apps repository, you can find and download the Streaming Sample App. It's a great place to get started - All the samples in this repository are built with JS code and demonstrate primary usage in the API.

Functionality

The sample app's functionality is pretty straightforward: You launch it, open the dev console (to see all the debug messages) and hit the start button to start the capture, and stop to stop it. You can look at the dev console to see the status of each call (success, failure, etc.). Once done, you can hit the open media folder to check the captured clip. Setting up

Setting up

Download the app's source code from the repository as a zip file, and extract it to a new folder on your machine.
Load the app as an "unpacked extension" (Note that to do that you have to whitelist your OW username as a developer).

  • Open the Overwolf desktop client settings (by right-clicking the client and selecting "Packages" Or by clicking on the wrench icon in the dock and going to the "About" tab => "Development Options").
  • Click on "Development options".
  • In the opened window, click on "Load unpacked extension" and select the extracted 'streaming-sample' folder. This will add the app to your Overwolf dock.
  • Make sure you are logged in to the OW client. Otherwise, you will get an "Unauthorized App" error message. (Click on the "Appstore" icon in the OW dock to login to the OW client).
  • Click on the app's icon in your OW dock to run the app.

start(settings, callback)

Version added: 0.78

Start a new stream.

Note that this feature will work only when your target game is running.

ParameterTypeDescription
settingsStreamSettings objectThe stream settings
callback(Result: StreamResult) => voidReturns with the result

For more info read our Basic streaming usage flow.

tip

Note that the stream will be recorded in chunks in a size of max_file_size_bytes. If you would like in addition, a full length single file copy, you can set include_full_size_video to true.

Usage Examples

Minimal required settings:

Here you can find example with the minimal required setting.
Note that when a setting value is not defined, a default value is set.


overwolf.streaming.onStopStreaming.addListener(console.log); //register to the onStopStreaming
overwolf.streaming.onStreamingError.addListener(console.log); //register to the onStreamingError
overwolf.streaming.onStreamingWarning.addListener(console.log); //register to the onStreamingWarning
var streamId; //we will use this variable to save the stream id
var stream_settings = {
"provider": overwolf.streaming.enums.StreamingProvider.VideoRecorder,
"settings": {
"audio": {"mic": {},"game": {} },
"video": {}
}
};

//start the stream
overwolf.streaming.start(stream_settings,
function(result) {
if (result.status == "success")
{
streamId = result.stream_id; //we need it for stopping the stream and manipulating stream settings later
console.debug(result.stream_id);
}
else {
console.debug("something went wrong...");
}
}
);

//stop the stream
overwolf.streaming.stop(streamId);
Example with customized Audio and Video settings:

overwolf.streaming.onStopStreaming.addListener(console.log); //register to the onStopStreaming
overwolf.streaming.onStreamingError.addListener(console.log); //register to the onStreamingError
overwolf.streaming.onStreamingWarning.addListener(console.log); //register to the onStreamingWarning

var streamId; //we will use this variable to save the stream id

var stream_settings = {
"provider": overwolf.streaming.enums.StreamingProvider.VideoRecorder,
"settings": {
"audio": {
"mic": {
"volume": 75,
"enable": true
},
"game": {
"volume": 75,
"enable": true
}
},
"video": {
"auto_calc_kbps": false,
"fps": 30,
"width": 1920,
"height": 1080,
"max_kbps": 1500,
"buffer_length": 20000,
"max_file_size_bytes": 50000000,
"include_full_size_video": true,
"notify_dropped_frames_ratio": 0.5,
"test_drop_frames_interval": 5000,
"indication_position": 'TopRightCorner',
"indication_type": 'dot',
"base_frame_size_source" : ["Setting","Auto"] , // if not set, "Setting" is the default
"frame_size_method": ["Original", "ExactOrKeepRatio", "ExactOrClosestResolution"] , // // Original
"encoder": {
"name": overwolf.streaming.enums.StreamEncoder.X264,
"config": {
"preset": overwolf.streaming.enums.StreamEncoderPreset_x264,
"rate_control": overwolf.streaming.enums.StreamEncoderRateControl_x264,
"keyframe_interval": 2
}
}
}
}
};

//start the stream
overwolf.streaming.start(stream_settings,
function(result) {
if (result.status == "success")
{
streamId = result.stream_id; //we need it for stopping the stream and manipulating stream settings later
console.debug(result.stream_id);
}
else {
console.debug("something went wrong...");
}
}
);

//stop the stream
overwolf.streaming.stop(streamId);
Example with customized Quota settings:

You can customize the stream quota settings and enable individual folders that are not part of the quota (to save favorite videos, for example). Read more about quota options here.


overwolf.streaming.onStopStreaming.addListener(console.log); //register to the onStopStreaming
overwolf.streaming.onStreamingError.addListener(console.log); //register to the onStreamingError
overwolf.streaming.onStreamingWarning.addListener(console.log); //register to the onStreamingWarning

var streamId; //we will use this variable to save the stream id

var stream_settings = {
"provider": overwolf.streaming.enums.StreamingProvider.VideoRecorder,
"settings": {
"audio": {"mic": {},"game": {} },
"video": {},
"quota": {
"max_quota_gb": 2,
"excluded_directories": [ "cool_session" ] //set directories that are not part of the quota
}
}
};

//start the stream
overwolf.streaming.start(stream_settings,
function(result) {
if (result.status == "success")
{
streamId = result.stream_id; //we need it for stopping the stream and manipulating stream settings later
console.debug(result.stream_id);
}
else {
console.debug("something went wrong...");
}
}
);

//stop the stream
overwolf.streaming.stop(streamId);

stop(streamId, callback)

Version added: 0.78

Stops the given stream.

ParameterTypeDescription
streamIdintThe id of the stream to stop
callback(Result: StopStreamingResult) => voidReturns with the result

getActiveRecordingApps(callback)

Version added: 0.233

Checks which apps are currently using the overwolf.streaming recording engine.

ParameterTypeDescription
callback(Result: GetActiveRecordingAppsResult) => voidReturns with the result

getCapabilities(callback)

Version added: 0.199

Returns all different streaming capabilities

ParameterTypeDescription
callback(Result: StreamingCapabilities) => voidThe streaming capabilities

split(streamId, callback)

Version added: 0.141

Request to split video now.

danger

This is an experimental function and shouldn’t be used without Overwolf’s permission

This method is available when recording with the enable_on_demand_split setting.
onVideoFileSplit event will be fired when the video splits.

ParameterTypeDescription
streamIdintThe id of the stream to split
callback(Result: SplitResult) => voidReturns with the result

changeVolume(streamId, audioOptions, callback)

Version added: 0.78

Changes the volume of the stream.

ParameterTypeDescription
streamIdintThe id of the stream on which the volume is changed
audioOptionsStreamAudioOptions ObjectThe new volumes encapsulated in an object
callback(Result) => voidReturns with the result

setWatermarkSettings(settings, callback)

Version added: 0.78

Sets the watermark settings.

ParameterTypeDescription
settingsWatermarkSettings ObjectThe new watermark settings
callback(Result) => voidReturns with the result

Usage Example

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

getWatermarkSettings(callback)

Version added: 0.78

Gets the watermark settings.

ParameterTypeDescription
callback(Result: GetWatermarkSettingsResult) => voidReturns with the result and the current watermark settings

getWindowStreamingMode(windowId, callback)

Version added: 0.78

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

ParameterTypeDescription
windowIdstringThe id of the window for which to get the streaming mode
callback(Result: GetWindowStreamingModeResult) => voidReturns with the result

setWindowStreamingMode(windowId, streamingMode, callback)

Version added: 0.78

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

ParameterTypeDescription
windowIdstringThe id of the window for which to set the streaming mode
streamingModestreamingMode enumThe desired streaming mode
callback(Result) => voidReturns with the result

setWindowObsStreamingMode(windowId, obsStreamingMode, callback)

Version added: 0.78

Sets the streaming mode for the window when using OBS.

ParameterTypeDescription
windowIdstringThe id of the window for which to set the streaming mode
streamingModeObsStreamingMode enumThe desired OBS streaming mode
callback(Result) => voidReturns with the result

setBRBImage(streamId, image, backgroundColor, callback)

Version added: 0.78

Set a stream’s Be Right Back image.

ParameterTypeDescription
streamIdintThe id of the stream for which to set the Be Right Back image
imageObjectThe image to set, as an IMG object or a URL
backgroundColorstringThe color to paint the last game frame with before overlaying the image
callback(Result) => voidReturns with the result

getStreamEncoders(callback)

Version added: 0.83

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

ParameterTypeDescription
callback(Result: GetStreamEncodersResult) => voidA callback function to call with the array of encoders and their metadata

getAudioDevices(callback)

Version added: 0.78

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

ParameterTypeDescription
callback(Result: GetAudioDevicesResult) => voidA callback function to call with the array of audio devices and their metadata

updateStreamingDesktopOptions(streamId, newOptions, mouseCursorStreamingMethod, callback)

Version added: 0.78

Update stream desktop capture options.

OBSOLETE

This function is obsolete.

ParameterTypeDescription
streamIdintThe id of the stream
newOptionsStreamDesktopCaptureOptions ObjectThe updated desktop capture streaming options
mouseCursorStreamingMethodstreamMouseCursor enumThe updated value of the mouse cursor streaming method
callback(Result) => voidReports success or failure

onStreamingSourceImageChanged

Version added: 0.78

Fired when the stream started streaming a new image source (desktop, game), with the following structure: StreamingSourceImageChangedEvent Object.

onStopStreaming

Version added: 0.78

Fired when the stream was stopped (and a recording was created), with the following structure: StopStreamingEvent Object.

onStartStreaming

Version added: 0.106

Fired when the stream has started, with the following structure: StreamEvent Object.

onStreamingError

Version added: 0.78

Fired when the stream has crashed, with the following structure: StreamEvent Object.

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
  • Update_Driver

Event Data Example

{
"status": "error",
"stream_id": 1,
"error": "Internet_Congested"
}

onStreamingWarning

Version added: 0.78

Fired upon a warning with the stream, with the following structure: StreamEvent Object.

Usage example

overwolf.streaming.onStreamingWarning.addListener(function(result) {
//result.stream_id
//result.error = "HIGH_CPU_USAGE" // there will probably be frames lost
});

onVideoFileSplit

Version added: 0.103

Fired upon video file splited, with the following structure: VideoFileSplitedEvent Object.

onSupportedEncodersUpdated

Version added: 0.169

Fired upon support encoder list updated, with the following structure: SupportedEncodersUpdatedEvent Object.

StreamingCapabilities Object

Version added: 0.199

Stream settings container.

NameTypeDescriptionSince
successboolThe stream provider name0.199
errorstringOptional error if any occured0.199
videoEncoderData[]Array of available video encoders0.199
audioAudioDeviceData[]Array of available audio devices0.199
audioProcessCaptureSupportedboolIs filtered sound capturing supported?0.199

Object data example

"settings": {
"success": true,
"video": [
{
"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
},
]
"audio": [
{
...
}
],
"audioProcessCaptureSupported": true
}

AudioCapabilities Object

Version added: 0.199

Audio devices container.

NameTypeDescriptionSince
devicesAudioDeviceData[]Array of available audio devices0.199
audioProcessCaptureSupportedboolIs filtered sound capturing supported?0.199

VideoCapabilities Object

Version added: 0.199

Video capabilities container.

NameTypeDescriptionSince
encodersEncoderData[]Array of available video encoders0.199

StreamSettings Object

Version added: 0.78

Stream settings container.

NameTypeDescriptionSince
providerstreamingProvider enumThe stream provider name0.78
settingsStreamParams objectThe stream provider settings0.78

Object data example

"settings": {
"video": { "buffer_length": 20000 },
"audio": {
"mic": {
"volume": 100,
"enable": true,
"mono": false
},
"game": {
"volume": 75,
"enable": true
}
},
"peripherals": {
"capture_mouse_cursor": "both"
},
"quota": {
"max_quota_gb": 2,
"excluded_directories": [ "cool_session" ] //set directories that are not part of the quota
}
}

StreamingProvider Enum

Version added: 0.78

OptionsDescription
UnknownThe stream provider name
TwitchStream to Twitch
VideoRecorder
RTMPStream to YouTube, Facebook, smashcast.tv, etc.

CaptureErrorCode Enum

Version added: 0.208

OptionsDescription
Success0
FolderCreation1
RansomwareProtection2
AlreadyStreaming3
MissingSetting4
SettingError5
InternalOBSError6
NotAllowedInGame7
HighPerformanceCaptureNotSupported8
NotInGame9
HighlightsMissing10
RequestedHighlightsUnsupported11
UnsupportedEncoder12
Unknown1000

RansomwareProtection Note

If Windows ransomware protection on folders is turned on, writing to the capture folder path is blocked, and as such, the stream returns an error. More information can be found here.

StreamParams Object

Version added: 0.78

Represents the settings required to start a stream.

NameTypeDescriptionSince
audioStreamAudioOptions ObjectStream audio options0.78
peripheralsStreamPeripheralsCaptureOptions ObjectDefines how peripherals (i.e. mouse cursor) are streamed.
Permissions required: DesktopStreaming
0.78
max_quota_gbdoubleMax media folder size in GB.
deprecated
0.78
quotaStreamQuotaParams objectParameters for limiting disk space allocation.0.147
stream_infoStreamInfo objectThe basic stream information0.78
authStreamAuthParams objectStream authorization data0.78
videoStreamVideoOptions ObjectStream video options0.78
ingest_serverStreamIngestServer ObjectInformation on the server that is being streamed to0.78
replay_typeReplayType enumThe replay type to use0.78

StreamQuotaParams Object

Version added: 0.147

The basic quota information.

You can allocate limited disk space for your captured video and even set an array of directories that are excluded from max quota calculations.
You can use it, for example, to implement "favorites captures" feature: allow your app's users to mark some captured videos as "favorites," move them to one of the excluded directories, and make sure that they not deleted when the quota has reached the limit. Of course, this is just a suggested usage example.

NameTypeDescriptionSince
max_quota_gbdoubleMax media folder size in GB0.147
excluded_directoriesstring[]Array of directories that are excluded from max quota calculations0.147

Notes

To set your app to never deletes the captured clips, you can skip passing max_quota_gb (it's an optional property), or you exclude a specific directory using the excluded_directories param.

StreamInfo Object

Version added: 0.78

The basic stream information.

NameTypeDescriptionSince
urlstringThe URL where the stream can be watched0.78
titlestringThe stream title0.78

StreamAuthParams Object

Version added: 0.78

Stream authorization data.

NameTypeDescriptionSince
client_idstringThe client id part of the authorization data. This part is usually constant for each application.0.78
tokenstringThe token part of the authorization data. This part if usually user-specific, and received after login.0.78

StreamVideoOptions Object

Version added: 0.78

Stream video options.

NameTypeDescriptionSince
auto_detectboolDefines if to try to automatically detect the best settings for streaming0.83
auto_calc_kbpsboolDefines if to try to automatically calculate the kbps. If set to true, then the max_kbps field is ignored0.83
fpsintDefines the Frames Per Second for the stream0.78
widthintDefines the stream width in pixels0.78
heightintDefines the stream height in pixels0.78
max_kbpsintDefines the maximum KB per second of the stream. See notes.0.78
buffer_lengthintDefines the length of the buffer to be recorded in millisenconds (max 40 seconds)0.83
encoderStreamingVideoEncoderSettings ObjectDefines the video encoder settings to use0.83
capture_desktopStreamDesktopCaptureOptions ObjectDefines the desktop streaming options.
Permissions required: DesktopStreaming
0.83
test_drop_frames_intervaluintThe interval, in milliseconds, in which to test for dropped frames0.92
notify_dropped_frames_ratiodoubleThe ratio of dropped to non-dropped frames for which to issue a notification0.92
sub_folder_namestringDefines Sub folder for video file path destination (See note below this table)0.103
override_overwolf_settingboolDo not use Overwolf capture setting.0.103
max_file_size_bytesuintDefines file maximum size. when video reach {max_file_size_bytes}, the recorder will flush the video file and stat a new video file. onVideoFileSplit event will be fired0.103
enable_on_demand_splitboolEnable video file splitting on demand. See notes.0.141
include_full_size_videoboolin case max_file_size_bytes is onfull video will be recorded to disk parallel to splits videos.0.105
disable_when_sht_not_supportedboolDo not start video replay service in case shared texture is not supported.0.105
indication_positionindication_position EnumPosition of the recorder indicator. Available for video capture only.0.143
indication_typeindication_type EnumType of the recorder indicator. Available for video capture only.0.143
use_app_display_nameboolUse the app display (if has any e.g dock_button_title name when creating video folder. See note0.154
sourcesoverwolf.media.replays.VideoSource[]Add sources to video. See note0.159
base_frame_size_sourceeVideoBaseFrameSizeSource EnumSee note0.168
frame_size_methodeVideoFrameSizeCalcMethod EnumSee note0.168
game_window_captureGameWindowCapture ObjectDedicate option for game window capture (when available). See note0.176
keep_game_capture_on_lost_focusboolKeep capturing the game when the game loses focus (i.e do not show "Be Right Back"). Note: if game is minimized, BRB will be shown.0.180
disable_auto_shutdown_on_game_exitboolShould the recording engine stay running even after the relevant game was closed.0.236
color_spacestring | overwolf.streaming.enums.VideoColorSpecThe default value is: Rec709.0.254
color_formatstring | overwolf.streaming.enums.VideoColorFormatThe default value is: NV12.0.254
fragmented_video_fileboolSplits the video to smaller fragments which allows for the immediate start of video playback after downloading only a small initial segment.
Defaults to false.
0.254

VideoColorSpec enum

Version added: 0.254

OptionsDescription
Rec709Default.
RecsRGB
Rec601
Rec2100PQRequires one of the 10bit color format options
Rec2100HLGRequires one of the 10bit color format options

VideoColorFormat enum

Version added: 0.254

OptionsDescription
NV12Default.
8bit color format.
I4208bit color format.
I4448bit color format.
P01010bit color format.
I01010bit color format.
P21616bit color format.
P41616bit color format.
BGRA8bit color format.

base_frame_size_source notes

Possible values:

  • If not set, "Setting" (setting configuration) is the default. This means that it will look at what method has been selected in the eVideoFrameSizeCalcMethod field.
  • "Auto" is logical width\height (if in-game, take the game, otherwise take monitor).

frame_size_method notes

If the above base_frame_size_source was set as "Setting", the bellow values are available:

  • "Original": Original calculation to get the output resolution for the needed quality keeping the aspect ratio.
  • "ExactOrKeepRatio" (Recommended): Get the exact resolution from a resolutions list for the needed quality; if not found in the list, then calculate a new resolution keeping the aspect ratio.
  • "ExactOrClosestResolution": Find the closer resolution from a resolutions list for the needed quality.

game_window_capture notes

Dedicate option for specific games (CSGO, Warzone, Destiny 2) that requires exclusive mode to interact with the OW windows.

Up until now when we recorded these games in windowed mode, it resulted in a recording of the whole desktop.
We now provide the option to record only the game window. This feature is disabled by default, but you can enable it with these recording settings properties:

"video": {
"game_window_capture": {
"enable_when_available": bool, // Disabled by default
"capture_overwolf_windows": bool // Default value is taken from the Overwolf Settings
}
}

Note that we added a new is_game_window_capture property to onStartStreaming event to inform the app Creator if this new capturing feature was used or not on the current OW window.

sources notes

danger

The streaming API does not support webcam capture. For webcam capture, use the overwolf.media.replays API!

use_app_display_name notes

If this flag in on, when creating a video capture folder, it will use the app "short name" as the folder name, instead of using the app name from the manifest.
The app "short name" is defined in the dock_button_title manifest flag.

sub_folder_name notes

  • Defines Sub folder for video file path destination (Optional):
    OverwolfVideoFolder\\AppName\\|sub_folder_name\\|file_name|
  • In case [folder_name] is empty:
    OverwolfVideoFolder\\AppName\\|sub_folder_name|

enable_on_demand_split notes

  • When calling split(), the recorder will flush the video file to the local disk.
  • When the recorder encoded the key frame with presentation time stamp thats is equal to grater than split() timestamps.
  • When |max_file_size_bytes| is set, this flag is ignored.
  • onVideoFileSplit event will be fired.

max_kbps notes

increase the max_kbps of the encoder configuration may help the performance, but increase the video file size.

  • For video recording, we recommend using a value of higher than 8000.
  • For streaming, we recommend using a value smaller than 3000.

StreamingVideoEncoderSettings Object

Version added: 0.78

Stream video options.

NameTypeDescriptionSince
namestreamEncoder enumDefines which video encoder to use. Default: X2640.83
configone of the settings objects belowDefines the settings of the specific encoder0.83

See also:

StreamEncoder enum

Version added: 0.78

OptionsDescription
INTELUse the Intel Quick Sync encoder. Only available on supporting devices
X264Use the x264 encoder. This is the default encoder
NVIDIA_NVENCUses the nVidia encoder
AMD_AMFUses the AMD AMF encoder
NVIDIA_NVENC_NEWUses the New nVidia encoder

StreamingVideoEncoderNVIDIA_NVENCSettings Object

Version added: 0.83

Defines the configuration for the NVIDIA NVENC encoder.

NameTypeDescriptionSince
presetstreamEncoderPreset_NVIDIA enumDefines which preset the encoder should use0.83
rate_controlstreamEncoderRateControl_NVIDIA enumDefines the rate control mode the encoder should use0.83
keyframe_intervalintDefines the time, in seconds, after which to send a keyframe. See notes.0.83

keyframe_interval notes

Keyframes are points in the video where the entire frame is sent instead of just the differences from the previous frame.

  • Having a keyframe interval of 2 means that it takes at most 2 seconds for the viewers to catch up to a point where they can properly display the feed.
  • Streaming services would allow it to be 1, but setting it to 0 usually ends up making it somewhere around 8.5s between keyframes.
  • 2 offers a better balance between picture quality and viewer join speed.

Increasing the keyframe_interval of the encoder configuration may help the performance but decrease in quality or inability to seek a specific resolution (if you want to slice the video, for example).

streamEncoderPreset_NVIDIA enum

Version added: 0.83

OptionsDescription
AUTOMATIC
DEFAULT
HIGH_QUALITY
HIGH_PERFORMANCE
BLURAY_DISK
LOW_LATENCY
HIGH_PERFORMANCE_LOW_LATENCY
HIGH_QUALITY_LOW_LATENCY
LOSSLESS
HIGH_PERFORMANCE_LOSSLESS

streamEncoderRateControl_NVIDIA enum

Version added: 0.83

OptionsDescription
RC_CBR
RC_CQP
RC_VBR
RC_VBR_MINQP
RC_2_PASS_QUALITY

StreamingVideoEncoderIntelSettings Object

Version added: 0.83

TBA

StreamingVideoEncoderx264Settings Object

Version added: 0.83

Defines the configuration for an x264 encoder.

NameTypeDescriptionSince
presetstreamEncoderPreset_x264 enumDefines which preset the encoder should use0.83
rate_controlstreamEncoderRateControl_x264 enumDefines the rate control mode the encoder should use0.83
keyframe_intervalintDefines the time, in seconds, after which to send a keyframe. See notes.0.83

streamEncoderPreset_x264 enum

Version added: 0.83

OptionsDescription
ULTRAFAST
SUPERFAST
VERYFAST
FASTER
FAST
MEDIUM
SLOW
SLOWER
VERYSLOW
PLACEBO

streamEncoderRateControl_x264 enum

Version added: 0.83

OptionsDescription
RC_CBR
RC_CQP
RC_VBR
RC_VBR_MINQP
RC_2_PASS_QUALITY

StreamingVideoEncoderAMD_AMFSettings Object

Version added: 0.84

Defines the configuration for an x264 encoder.

NameTypeDescriptionSince
presetstreamEncoderPreset_AMD_AMF enumDefines which preset the encoder should use0.84
rate_controlstreamEncoderRateControl_AMD_AMF enumDefines the rate control mode the encoder should use0.84
keyframe_intervalintDefines the time, in seconds, after which to send a keyframe. See notes.0.83

streamEncoderPreset_AMD_AMF enum

Version added: 0.84

OptionsDescription
AUTOMATIC
BALANCED
SPEED
QUALITY
ULTRA_LOW_LATENCY
LOW_LATENCY

streamEncoderRateControl_AMD_AMF enum

Version added: 0.84

OptionsDescription
RC_CBR
RC_CQP
RC_VBR
RC_VBR_MINQP

StreamDesktopCaptureOptions Object

Version added: 0.78

Defines the configuration for an x264 encoder.

NameTypeDescriptionSince
enableboolDefines if to capture the desktop while game is not running or not in focus0.78
monitor_iduintDefines which monitor to stream when streaming desktop. Use the index of the requested monitor in the monitor's array that returned from overwolf.utils.getMonitorList().0.78
force_captureboolDefines if to force desktop streaming even when a game is in foreground0.78

StreamAudioOptions Object

Version added: 0.83

Defines the configuration for an x264 encoder.

NameTypeDescriptionSince
micStreamDeviceVolumeDefines the microphone volume as applied to the stream0.83
gameGameAudioDeviceDefines the game volume as applied to the stream0.83
separate_tracksboolEnable multiple audio tracks. See notes0.156
devicesAudioDeviceOptions[]An array of devices to capture.
MUST disable the mic + game audio options when using this feature.
0.254
process_audio_captureProcessAudioCapture[]Add and control process’ audio capture.
MUST disable the game audio options when using this feature.
0.254
tracksint | overwolf.streaming.enums.AudioTracksSpecify how many tracks you want to create for your captured video.
Defaults to ’AllTracks’ (255).
0.254
sample_ratestring | overwolf.streaming.enums.AudioSampleRateControl the audio sample rate.
Defaults to kHz441.
0.254

AudioSampleRate enum

Version added: 0.254

OptionsDescription
kHz441Default.
kHz48

separate_tracks notes

When disabled (default), the video (mp4) will be created with a single track. When enabled, it is possible to record videos that support multiple audio tracks:
The Video will be created with three different audio tracks (when both Mic + Desktop is enabled):

  • Track 1: Microphone + Desktop
  • Track 2: Desktop output
  • Track 3: Microphone input

AudioDeviceOptions Object

Version added: 0.254

NameTypeDescriptionSince
device_idstringDefines the device_id to use.
Can be passed ‘default’.
0.254
type (optional)string | overwolf.streaming.enums.AudioDeviceTypeSpecify the type of the device (output/input)
When passing ‘default’ to device_id, you MUST specify the device type.
Defaults to type 0 (output).
0.254
volumeintDefines the volume of the device from 0 to 2000.0.254
use_device_timing (optional)boolCan be used to try fix sync issues between video and sound.
On input devices defaults to false. On output devices defaults to true.
0.254
{
provider: 'VideoRecorder',
settings: {
audio: {
devices: [
// Microphone
// When device is a microphone and device_id is set to ‘default’, you MUST set the type to Input.
{
device_id: 'default',
type: overwolf.streaming.enums.AudioDeviceType.Input,
use_device_timing: false,
},


// Headset
{ device_id: 'default', volume: 100, use_device_timing: false },
],
// mic && game MUST be set to false to use devices[]
mic: {
enable: false,
},
game: {
enable: false,
},
},


video: {
include_full_size_video: false,
frame_size_method: 'Original',
base_frame_size_source: 'Setting',
enable_on_demand_split: true,
use_app_display_name: false,
capture_desktop: {
enable: true,
},
keep_game_capture_on_lost_focus: false,
override_overwolf_setting: false,
},
peripherals: {
capture_mouse_cursor: 'both',
},
quota: {
max_quota_gb: 1,
},
},
};

AudioDeviceType enum

Version added: 0.254

OptionsDescription
OutputDefault.
Input

ProcessAudioCapture Object

Version added: 0.254

NameTypeDescriptionSince
process_namestringSpecify the process name that should be recorded.0.254
volumeintDefines the volume of the recorded process from 0 to 2000.0.254
monoboolSpecify whether the process should be recorded as mono or not.
Defaults to false (stereo).
0.254
tracksint | overwolf.streaming.enums.AudioTracksSpecify which track the process should be recorded on. Can select multiple tracks by using | .
Defaults to ’AllTracks’ (255).
0.254
{
provider: 'VideoRecorder',
settings: {
audio: {
mic: {
device_id: 'default',
enable: true,
volume: 75,
},
game: {
device_id: 'default',
// Must be false to prevent unwanted sounds from the background to be captured
enable: false,
volume: 75,
},
process_audio_capture: [
{ process_name: 'gw.exe', volume: 50, mono: false },
// { "process_name": "chrome.exe", "volume": 50, "mono": false },
],
},


video: {
include_full_size_video: false,
frame_size_method: 'Original',
base_frame_size_source: 'Setting',
enable_on_demand_split: true,
use_app_display_name: false,
capture_desktop: {
enable: true,
},
keep_game_capture_on_lost_focus: false,
override_overwolf_setting: false,
},
peripherals: {
capture_mouse_cursor: 'both',
},
quota: {
max_quota_gb: 1,
},
},
};

StreamDeviceVolume Object

Version added: 0.78

Defines a device volume and enablement settings.

NameTypeDescriptionSince
enableboolDefines if the device is enabled0.78
monoboolWhether or not this device should be recorded as in mono or stereo mode. Defaults to false0.224
volumeintDefines the device volume in the range of 0 to 20000.78
device_idstringDefines the device ID to use0.78
tracksint | overwolf.streaming.enums.AudioTracksSpecify which track the input device should be recorded on. Can select multiple tracks by using | .
Defaults to ’AllTracks’ (255).
0.254
use_device_timing (optional)boolCan be used to try fix sync issues between video and sound. On input devices defaults to false. On output devices defaults to true.0.254

Example data: Tracks Settings

{
provider: 'VideoRecorder',
settings: {
audio: {
mic: {
device_id: 'default',
enable: true,
volume: 75,
// Sets input to Audio tracks 1 and 2
tracks:
overwolf.streaming.enums.AudioTracks.AudioTrack1 |
overwolf.streaming.enums.AudioTracks.AudioTrack2,
},
game: {
device_id: 'default',
enable: true,
volume: 75,
// Sets output on Audio tracks 1 and 3
tracks:
overwolf.streaming.enums.AudioTracks.AudioTrack1 |
overwolf.streaming.enums.AudioTracks.AudioTrack3,
},
process_audio_capture: [
// Sets the process audio capture to Audio tracks 1 and 4
{
process_name: 'gw.exe',
volume: 50,
mono: false,
tracks:
overwolf.streaming.enums.AudioTracks.AudioTrack1 |
overwolf.streaming.enums.AudioTracks.AudioTrack4,
},
],
// Sets the overall amount of tracks
tracks:
overwolf.streaming.enums.AudioTracks.AudioTrack1 |
overwolf.streaming.enums.AudioTracks.AudioTrack2 |
overwolf.streaming.enums.AudioTracks.AudioTrack3 |
overwolf.streaming.enums.AudioTracks.AudioTrack4,
},
video: {
include_full_size_video: false,
frame_size_method: 'Original',
base_frame_size_source: 'Setting',
enable_on_demand_split: true,
use_app_display_name: false,
capture_desktop: {
enable: true,
},
keep_game_capture_on_lost_focus: false,
override_overwolf_setting: false,
},
peripherals: {
capture_mouse_cursor: 'both',
},
quota: {
max_quota_gb: 1,
},
},
};

AudioTracks enum

Version added: 0.254

OptionsDescription
AudioTrack1
AudioTrack2
AudioTrack3
AudioTrack4
AudioTrack5
AudioTrack6
AudioTrackAllDefault.

GameAudioDevice Object

Version added: 0.199

Defines a game's volume and enablement settings.

NameTypeDescriptionSince
enableboolDefines if game audio is enabled0.78
volumeintDefines the game's volume in the range of 0 to 20000.78
device_idstringDefines the device ID to use0.78
filtered_captureGameCaptureOptionsIf enabled, only audio from the game and the specifically marked processes will be captured. See notes0.199
tracksint | overwolf.streaming.enums.AudioTracksSpecify which track the game audio should be recorded on. Can select multiple tracks by using | .
Defaults to ’AllTracks’ (255).
0.254
use_device_timing (optional)boolCan be used to try fix possible sync issues between video and sound. On input devices defaults to false. On output devices defaults to true.0.254

filtered_capture notes

danger

This feature is experimental, proceed with caution!

When enabling filtered_capture, only audio from the currently detected game, and from any other process in the specific list of processes defined under additional_process_names, will be captured.

GameCaptureOptions Object

Version added: 0.199

If enabled, only audio from the current game, as well as from any strictly specified process in this list, will be captured. Requires audioProcessCaptureSupported to return true in audioProcessCaptureSupported (this depends on the running machine, so make sure to verify it!)

NameTypeDescriptionSince
enableboolDefines if filtered capture is enabled. See note0.199
additional_process_namesstring[]The array of process names to be affected0.199

filtered capture notes

In order for filtered_capture to work, the user must be running one of the following:

  • windows 11
  • windows 10 2004 (released 2020-05-27) or later

enable Checks whether or not filtered_capture is supported on this system.

StreamPeripheralsCaptureOptions Object

Version added: 0.83

Stream capture options for peripheral devices.

Note: To turn off capture_mouse_cursor, set peripherals to null

NameTypeDescriptionSince
capture_mouse_cursorstreamMouseCursor enumDefines when to capture the mouse cursor while streaming is on0.83

StreamMouseCursor enum

Version added: 0.83

OptionsDescription
bothAlways capture the mouse cursor
gameOnlyCapture the mouse cursor only when a game is focued
desktopOnlyCapture the mouse cursor only when on the desktop
noneNever capture the mouse cursor

StreamIngestServer Object

Version added: 0.78

Information on the server that is being streamed to.

NameTypeDescriptionSince
namestringThe server name that is being streamed to0.78
template_urlstringThe server’s url template. Use the token {stream_key} to specify the stream key in the url0.78

WatermarkSettings Object

Version added: 0.78

The basic stream information.

NameTypeDescriptionSince
showWatermarkboolDetermines whether or not to display the Overwolf watermark on the stream0.78

StreamingMode enum

Version added: 0.78

OptionsDescription
WhenVisibleStream the window when it is visible. This is the default behavior. The viewers will see what you see
AlwaysAlways stream the window, even when it is hidden or minimized. The viewers will continue to see it while you don’t
NeverNever stream the window. The viewers will not see the window even if you do see it.

ObsStreamingMode enum

Version added: 0.78

OptionsDescription
OBSNoAwarenessThe default Overwolf window style
OBSAwarenessAllows 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)
OBSAwarenessHideFromDeskTopSame as OBSAwareness but also not visible in desktop (hidden)

SplitResult Object

Version added: 0.141

Returns with the result.

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object

indication_position enum

Version added: 0.143

OptionsDescription
None
TopLeftCorner
TopRightCorner
BottomLeftCorner
BottomRightCorner

indication_type enum

Version added: 0.143

OptionsDescription
NoIndication
Dot
DotAndTimer

StreamResult Object

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
activeRecordingAppsActiverecordingApps[]other apps that are already using the streaming api
stream_idnumberoptional
errorCodeCaptureErrorCode
errorDescriptionstring

Example data: Success

{ "status": "success", "stream_id": 3 }

Example data: Failure

{ "status": "error", "error": "something went wrong...", "SubErrorMessage": "already running" }

GetActiveRecordingAppsResult Object

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
streamingActiverecordingApps[]The apps currently using the overwolf.streaming recording engine

ActiveRecordingApps Object

ParameterTypeDescription
uidstringthe uid of the app
displayNamestringthe display name of the app

StreamEvent Object

ParameterTypeDescription
stream_idnumber
SubErrorMessagestring
is_game_window_captureboolSee game_window_capture

StopStreamingEvent Object

ParameterTypeDescription
stream_idnumber
urlstring
file_pathstring
durationnumber
last_file_pathstring
splitboolean
extraobject
total_framesnumber
osVersionstring
osBuildstring
errorstring(Optional) error given if the recording engine errored (but still created a recording)

Event data example

{
"stream_id":3,
"url":"overwolf://media/recordings/Game+Events+Simulator/Desktop+02-27-2020+14-37-13-913.mp4",
"file_path":"C:\\Users\\Hal9000\\Videos\\Overwolf\\Game Events Simulator\\Desktop 02-27-2020 14-37-13-913.mp4",
"duration":61045,
"last_file_path":"C:\\Users\\Hal9000\\Videos\\Overwolf\\Game Events Simulator\\Desktop 02-27-2020 14-37-13-913",
"split": true,
"extra":"{"drawn": 856,"dropped": 0,"lagged": 0,"percentage_dropped": 0,"percentage_lagged": 0,"system_info": {"game_dvr_enabled": true,"game_mode_enabled": true}",
"total_frames": 1835,
"osVersion": "10.0.18362.650",
"osBuild":"1903"
}
tip

To use the file_path and not the url (as a source for a video player, for example) - you should add the allow_local_file_access : true flag to your app manifest, under the relevant window section.

StopStreamingResult Object

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
stream_idnumber
urlstring
file_pathstring
durationnumber
last_file_pathstring
splitboolean
extraobject
total_framesnumber
osVersionstring
osBuildstring

Callback argument: Success

{
"success":true,
"stream_id":3,
"url":"overwolf://media/recordings/Game+Events+Simulator/Desktop+02-27-2020+14-37-13-913.mp4",
"file_path":"C:\\Users\\Hal9000\\Videos\\Overwolf\\Game Events Simulator\\Desktop 02-27-2020 14-37-13-913.mp4",
"duration":61045,
"last_file_path":"C:\\Users\\Hal9000\\Videos\\Overwolf\\Game Events Simulator\\Desktop 02-27-2020 14-37-13-913",
"split": true,
"extra":"{"drawn": 856,"dropped": 0,"lagged": 0,"percentage_dropped": 0,"percentage_lagged": 0,"system_info": {"game_dvr_enabled": true,"game_mode_enabled": true}",
"total_frames": 1835,
"osVersion": "10.0.18362.650",
"osBuild":"1903"
}
tip

To use the file_path and not the url (as a source for a video player, for example) - you should add the allow_local_file_access : true flag to your app manifest, under the relevant window section.

GetWatermarkSettingsResult Object

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
showWatermarkboolean

Callback argument: Success

A function that will be called with a JSON containing the status and the watermark settings if successful

{ "status": "success" , "showWatermark": true }

GetWindowStreamingModeResult Object

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
streaming_modestring

Callback argument: Success

A callback function which will be called with the status of the request and the window’s streaming mode as a parameter

{ "status": "success", "streaming_mode": "WhenVisible" }

GetStreamEncodersResult Object

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
encodersEncoderData[]List of supported encoders. The latest version of supported video encoders can be found here

Callback argument: Success

A callback function which will be called with the status of the request

{
"status": "success",
"encoders": [
{
"name" : "INTEL",
"display_name" : "Intel® Quick Sync (uses iGPU)",
"enabled" : true,
"presets" : ["LOW", "MEDIUM", "HIGH"]
},
...
]
}

EncoderData Object

ParameterTypeDescription
namestring
display_namestring
enabledboolean
presetsstring[]See notes
validbooleanIs the encoder valid for usage. The encoder can be supported but not valid
vendor_errorstring"Invalid version", for example. The data will guide us for solutions for problems we didn't have enough information about until now
error_descriptionstring"Not supported", for example, The data will guide us for solutions for problems we didn't have enough information about until now

Endoder Preset notes

For each encoder in the list, a preset enum returns. For example:

  1. The NVIDIA encoder returns StreamEncoderPreset_NVIDIA enum.
  2. The X264 encoder returns StreamEncoderPreset_x264 enum.
  3. The AMD encoder returns StreamEncoderPreset_AMD_AMF enum.

AudioDeviceData Object

ParameterTypeDescription
display_namestringThe display name of the device
device_idstringThe device ID
can_recordbooleanCan the device record
can_playbackbooleanCan the device play a playback
device_statestringThe device's state
device_setting_idstring

GetAudioDevicesResult Object

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
devicesAudioDeviceData[]An array of connected audio devices
default_recording_device_idAudioDeviceDataThe default recording device
default_playback_device_idAudioDeviceDataThe default playback device

Callback argument: Success

A callback function which will be called with the status of the request

{
"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}"
}

StreamingSourceImageChangedEvent Object

ParameterTypeDescription
stream_idnumber
old_sourcestring
new_sourcestring

VideoFileSplitedEvent Object

ParameterTypeDescription
stream_idnumber
file_namestring
durationnumber
countnumber
next_filestring

SupportedEncodersUpdatedEvent Object

ParameterTypeDescription
encodersEncoderData[]

eVideoBaseFrameSizeSource enum

Version added: 0.168

OptionsDescription
Autological width\height (if in game, take game, otherwhise take monitor)
Settingsetting configuraion

eVideoFrameSizeCalcMethod enum

Version added: 0.168

OptionsDescription
OriginalOriginal calculation to get the output resolution for the needed quality keeping the aspect ratio
ExactOrKeepRatio(Recommended) Get the exact resolution from a resolutions list for the needed quality, if not found in the list then calculate a new resolution keeping the aspect ratio.
ExactOrClosestResolutionOriginal calculation to get the output resolution for the needed quality keeping the aspect ratio

GameWindowCapture Object

Version added: 0.176

Game window capture options.

NameTypeDescriptionSince
enable_when_availableboolDisabled by default0.176
capture_overwolf_windowsboolDefault value is taken from the Overwolf Settings0.176

Example data

"game_window_capture": {
"enable_when_available": bool, // Disabled by default
"capture_overwolf_windows": bool // Default value is taken from the Overwolf Settings
}